neofscrypto

Documentation

Overview

Package neofscrypto collects NeoFS cryptographic primitives.

Signer type unifies entities for signing NeoFS data.

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

PublicKey allows to verify signatures.

Index

• Variables
• func PublicKeyBytes(pubKey PublicKey) []byte
• func RegisterScheme(scheme Scheme, f func() PublicKey)
• func StringifyKeyBinary(src []byte) string
• type PublicKey
• type Scheme
  • func (x Scheme) String() string
• type Signature
  • func NewSignature(scheme Scheme, publicKey PublicKey, value []byte) Signature
  • func (x *Signature) Calculate(signer Signer, data []byte) error
  • func (x *Signature) CalculateMarshalled(signer Signer, obj StablyMarshallable, buf []byte) error
  • func (x Signature) PublicKey() PublicKey
  • func (x Signature) PublicKeyBytes() []byte
  • func (x *Signature) ReadFromV2(m refs.Signature) error
  • func (x Signature) Scheme() Scheme
  • func (x Signature) Value() []byte
  • func (x Signature) Verify(data []byte) bool
  • func (x Signature) WriteToV2(m *refs.Signature)
• type Signer
• type StablyMarshallable
• type StaticSigner
  • func NewStaticSigner(scheme Scheme, sig []byte, pubKey PublicKey) *StaticSigner
  • func (s *StaticSigner) Public() PublicKey
  • func (s *StaticSigner) Scheme() Scheme
  • func (s *StaticSigner) Sign(_ []byte) ([]byte, error)

Examples

• Signature (Marshalling)
• Signature.Calculate
• Signature.Verify

Variables

var ErrIncorrectSigner = errors.New("incorrect signer")

ErrIncorrectSigner is returned from function when the signer passed to it is incompatible with the function requirements. This variable is intended to be used as documentation and for errors.Is purposes and MUST NOT be changed.

Functions

func PublicKeyBytes

func PublicKeyBytes(pubKey PublicKey) []byte

PublicKeyBytes returns binary-encoded PublicKey. Use [PublicKey.Encode] to avoid new slice allocation.

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.

Parameter src is a serialized compressed public key. See [elliptic.MarshalCompressed].

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.
	//
	// [PublicKeyBytes] may be used to skip explicit buffer allocation.
	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 NeoFS.

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 github.com/nspcc-dev/neofs-api-go/v2/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

Example (Marshalling)

Instances can be also used to process NeoFS API V2 protocol messages with [https://github.com/nspcc-dev/neofs-api] package.

package main

import (
	"github.com/nspcc-dev/neofs-api-go/v2/refs"
	neofscrypto "github.com/nspcc-dev/neofs-sdk-go/crypto"
)

func main() {
	// import "github.com/nspcc-dev/neofs-api-go/v2/refs"

	// On the client side.

	var sig neofscrypto.Signature
	var msg refs.Signature
	sig.WriteToV2(&msg)
	// *send message*

	// On the server side.

	_ = sig.ReadFromV2(msg)
}

func NewSignature

func NewSignature(scheme Scheme, publicKey PublicKey, value []byte) Signature

NewSignature is a Signature instance constructor.

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.

Example

package main

import (
	neofscrypto "github.com/nspcc-dev/neofs-sdk-go/crypto"
)

func main() {
	var signer neofscrypto.Signer
	var data []byte

	// instantiate Signer
	// select data to be signed

	var sig neofscrypto.Signature
	_ = sig.Calculate(signer, data)

	// attach signature to the request
}

func (*Signature) CalculateMarshalled

func (x *Signature) CalculateMarshalled(signer Signer, obj StablyMarshallable, buf []byte) error

CalculateMarshalled signs data using Signer and encodes public key for subsequent verification. If signer is a StaticSigner, just sets prepared signature.

Pre-allocated byte slice can be passed in buf parameter to avoid new allocations. In ideal case buf length should be StableSize length. If buffer length shorter than StableSize or nil, new slice will be allocated.

Signer MUST NOT be nil.

See also Verify.

func (Signature) PublicKey

func (x Signature) PublicKey() PublicKey

PublicKey returns public key of the signer which calculated the signature.

PublicKey MUST NOT be called before NewSignature, Signature.ReadFromV2 or Signature.Calculate methods.

See also Signature.PublicKeyBytes.

func (Signature) PublicKeyBytes

func (x Signature) PublicKeyBytes() []byte

PublicKeyBytes returns binary-encoded public key of the signer which calculated the signature.

PublicKeyBytes MUST NOT be called before NewSignature, Signature.ReadFromV2 or Signature.Calculate methods.

The value returned shares memory with the structure itself, so changing it can lead to data corruption. Make a copy if you need to change it.

See also Signature.PublicKey.

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 NeoFS API V2 protocol.

See also WriteToV2.

func (Signature) Scheme

func (x Signature) Scheme() Scheme

Scheme returns signature scheme used by signer to calculate the signature.

Scheme MUST NOT be called before NewSignature, Signature.ReadFromV2 or Signature.Calculate methods.

func (Signature) Value

func (x Signature) Value() []byte

Value returns calculated digital signature.

The value returned shares memory with the structure itself, so changing it can lead to data corruption. Make a copy if you need to change it.

Value MUST NOT be called before NewSignature, Signature.ReadFromV2 or Signature.Calculate methods.

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.

Example

PublicKey allows to verify signatures.

package main

import (
	neofscrypto "github.com/nspcc-dev/neofs-sdk-go/crypto"
)

func main() {
	var sig neofscrypto.Signature

	var data []byte
	sig.Verify(data)
}

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 NeoFS. Unites secret and public parts. For example, an ECDSA private key or external auth service.

See also PublicKey.

type StablyMarshallable

type StablyMarshallable interface {
	StableMarshal([]byte) []byte
	StableSize() int
}

StablyMarshallable describes structs which can be marshalled transparently.

type StaticSigner

type StaticSigner struct {
	// contains filtered or unexported fields
}

StaticSigner is an emulation of a real Signer (implementing the same interface). While normally Signer is expected to hold a private key and use it to calculate Signature, StaticSigner contains already precalculated serialized signature and doesn't need a private key. Use it when you already have an appropriate signature (calculated elsewhere, not by SDK code), but want to attach it to some structure/request.

func NewStaticSigner

func NewStaticSigner(scheme Scheme, sig []byte, pubKey PublicKey) *StaticSigner

NewStaticSigner creates new StaticSigner.

func (*StaticSigner) Public

func (s *StaticSigner) Public() PublicKey

Public returns the public key that StaticSigner was instantiated with. Implements Signer.

func (*StaticSigner) Scheme

func (s *StaticSigner) Scheme() Scheme

Scheme returns the scheme that StaticSigner was instantiated with. Implements Signer.

func (*StaticSigner) Sign

func (s *StaticSigner) Sign(_ []byte) ([]byte, error)

Sign returns precalculated serialized signature that was provided upon StaticSigner creation. Never returns an error. Implements Signer.

The value returned shares memory with the structure itself, so changing it can lead to data corruption. Make a copy if you need to change it.