frostfscrypto

Documentation

Overview

Package frostfscrypto collects FrostFS cryptographic primitives.

Signer type unifies entities for signing FrostFS data.

// instantiate Signer
// select data to be signed

var sig Signature

err := sig.Calculate(signer, data)
// ...

// attach signature to the request

SDK natively supports several signature schemes that are implemented in nested packages.

PublicKey allows to verify signatures.

// get signature to be verified
// compose signed data

isValid := sig.Verify(data)
// ...

Signature can be also used to process FrostFS API V2 protocol messages (see neo.fs.v2.refs package in https://git.frostfs.info/TrueCloudLab/frostfs-api).

On client side:

import "git.frostfs.info/TrueCloudLab/frostfs-sdk-go/api/refs"

var msg refs.Signature
sig.WriteToV2(&msg)

// send msg

On server side:

// recv msg

var sig frostfscrypto.Signature
sig.ReadFromV2(msg)

// process sig

Using package types in an application is recommended to potentially work with different protocol versions with which these types are compatible.

Index

• func RegisterScheme(scheme Scheme, f func() PublicKey)
• func StringifyKeyBinary(src []byte) string
• type PublicKey
• type Scheme
  • func (x Scheme) String() string
• type Signature
  • func (x *Signature) Calculate(signer Signer, data []byte) error
  • func (x *Signature) ReadFromV2(m refs.Signature) error
  • func (x Signature) Verify(data []byte) bool
  • func (x Signature) WriteToV2(m *refs.Signature)
• type Signer

Functions

func RegisterScheme

func RegisterScheme(scheme Scheme, f func() PublicKey)

RegisterScheme registers a function that returns a new blank PublicKey instance for the given Scheme. This is intended to be called from the init function in packages that implement signature schemes.

RegisterScheme panics if function for the given Scheme is already registered.

Note that RegisterScheme isn't tread-safe.

func StringifyKeyBinary

func StringifyKeyBinary(src []byte) string

StringifyKeyBinary returns string with HEX representation of source. Format can be changed and it's unsafe to rely on it beyond human-readable output.

Types

type PublicKey

type PublicKey interface {
	// MaxEncodedSize returns maximum size required for binary-encoded
	// public key.
	//
	// MaxEncodedSize MUST NOT return value greater than any return of
	// Encode.
	MaxEncodedSize() int

	// Encode encodes public key into buf. Returns number of bytes
	// written.
	//
	// Encode MUST panic if buffer size is insufficient and less than
	// MaxEncodedSize (*). Encode MUST return negative value
	// on any failure except (*).
	//
	// Encode is a reverse operation to Decode.
	Encode(buf []byte) int

	// Decode decodes binary public key.
	//
	// Decode is a reverse operation to Encode.
	Decode([]byte) error

	// Verify checks signature of the given data. True means correct signature.
	Verify(data, signature []byte) bool
}

PublicKey represents a public key using fixed signature scheme supported by FrostFS.

See also Signer.

type Scheme

type Scheme int32

Scheme represents digital signature algorithm with fixed cryptographic hash function.

Negative values are reserved and depend on context (e.g. unsupported scheme).

const (
	ECDSA_SHA512               Scheme // ECDSA with SHA-512 hashing (FIPS 186-3)
	ECDSA_DETERMINISTIC_SHA256        // Deterministic ECDSA with SHA-256 hashing (RFC 6979)
	ECDSA_WALLETCONNECT               // Wallet Connect signature scheme
)

func (Scheme) String

func (x Scheme) String() string

String implements fmt.Stringer.

type Signature

type Signature refs.Signature

Signature represents a confirmation of data integrity received by the digital signature mechanism.

Signature is mutually compatible with git.frostfs.info/TrueCloudLab/frostfs-sdk-go/api/refs.Signature message. See ReadFromV2 / WriteToV2 methods.

Note that direct typecast is not safe and may result in loss of compatibility:

_ = Signature(refs.Signature{}) // not recommended

func (*Signature) Calculate

func (x *Signature) Calculate(signer Signer, data []byte) error

Calculate signs data using Signer and encodes public key for subsequent verification.

Signer MUST NOT be nil.

See also Verify.

func (*Signature) ReadFromV2

func (x *Signature) ReadFromV2(m refs.Signature) error

ReadFromV2 reads Signature from the refs.Signature message. Checks if the message conforms to FrostFS API V2 protocol.

See also WriteToV2.

func (Signature) Verify

func (x Signature) Verify(data []byte) bool

Verify verifies data signature using encoded public key. True means valid signature.

Verify fails if signature scheme is not supported (see RegisterScheme).

See also Calculate.

func (Signature) WriteToV2

func (x Signature) WriteToV2(m *refs.Signature)

WriteToV2 writes Signature to the refs.Signature message. The message must not be nil.

See also ReadFromV2.

type Signer

type Signer interface {
	// Scheme returns corresponding signature scheme.
	Scheme() Scheme

	// Sign signs digest of the given data. Implementations encapsulate data
	// hashing that depends on Scheme. For example, if scheme uses SHA-256, then
	// Sign signs SHA-256 hash of the data.
	Sign(data []byte) ([]byte, error)

	// Public returns the public key corresponding to the Signer.
	Public() PublicKey
}

Signer is an interface of entities that can be used for signing operations in FrostFS. Unites secret and public parts. For example, an ECDSA private key or external auth service.

See also PublicKey.