neofscrypto

package
v1.0.0-rc.21 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 30, 2026 License: Apache-2.0 Imports: 6 Imported by: 21

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

Examples

Constants

View Source
const (
	MaxVerificationScriptLength = 1024 // verification script or public key binary
	MaxInvocationScriptLength   = 1024 // invocation script or signature
)

Protocol limits.

Variables

View Source
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 SignRequestWithBuffer

func SignRequestWithBuffer[B ProtoMessage](signer Signer, r SignedRequest[B], buf []byte) (*session.RequestVerificationHeader, error)

SignRequestWithBuffer signs request parts using provided neofscrypto.Signer according to the NeoFS API protocol, and returns resulting verification header to attach to this request.

Buffer is optional and free after the call.

func SignResponseWithBuffer

func SignResponseWithBuffer[B ProtoMessage](signer Signer, r SignedResponse[B], buf []byte) (*session.ResponseVerificationHeader, error)

SignResponseWithBuffer signs response parts using provided neofscrypto.Signer according to the NeoFS API protocol, and returns resulting verification header to attach to this response.

Buffer is optional and free after the call.

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].

func VerifyMessageSignature

func VerifyMessageSignature(m ProtoMessage, s *refs.Signature, b []byte) error

VerifyMessageSignature verifies signature of m using buffer b.

func VerifyRequestWithBuffer

func VerifyRequestWithBuffer[B ProtoMessage](r SignedRequest[B], buf []byte) error

VerifyRequestWithBuffer checks whether verification header of the request is formed according to the NeoFS API protocol.

Buffer is optional and free after the call.

func VerifyRequestWithBufferN3

func VerifyRequestWithBufferN3[B ProtoMessage](r SignedRequest[B], buf []byte, verifyN3 func(data, invocScript, verifScript []byte) error) error

VerifyRequestWithBufferN3 checks whether verification header of the request is formed according to the NeoFS API protocol. N3 signatures are supported and checked if verifyN3 is non-nil.

Buffer is optional and free after the call.

func VerifyResponseWithBuffer

func VerifyResponseWithBuffer[B ProtoMessage](r SignedResponse[B], buf []byte) error

VerifyResponseWithBuffer checks whether verification header of the response is formed according to the NeoFS API protocol.

Buffer is optional and free after the call.

Types

type ProtoMessage

type ProtoMessage interface {
	MarshaledSize() int
	MarshalStable([]byte)
}

ProtoMessage is the marshaling interface provided by all NeoFS proto-level structures.

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
	N3                                // Neo N3 witness
)

func (Scheme) String

func (x Scheme) String() string

String implements fmt.Stringer.

type Signature

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

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

Signature is mutually compatible with refs.Signature message. See Signature.FromProtoMessage / Signature.ProtoMessage methods.

Instances should be constructed using one of the constructors.

func NewN3Signature

func NewN3Signature(invocScript, verifScript []byte) Signature

NewN3Signature constructs signature from given N3 witness scripts.

The verifScript and invocScript lengths should not be greater than MaxVerificationScriptLength and MaxInvocationScriptLength correspondingly.

func NewSignature

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

NewSignature is a Signature instance constructor.

The value length should not be greater than MaxInvocationScriptLength.

func NewSignatureFromRawKey

func NewSignatureFromRawKey(scheme Scheme, pub []byte, value []byte) Signature

NewSignatureFromRawKey constructs new Signature instance.

The pub and value lengths should not be greater than MaxVerificationScriptLength and MaxInvocationScriptLength correspondingly.

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 (
	"crypto/ecdsa"
	"crypto/elliptic"
	"crypto/rand"
	"fmt"

	neofscrypto "github.com/nspcc-dev/neofs-sdk-go/crypto"
	neofsecdsa "github.com/nspcc-dev/neofs-sdk-go/crypto/ecdsa"
)

func main() {
	// instantiate signer
	k, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
	// get data to be signed
	data := []byte("Hello, world!")
	var sig neofscrypto.Signature

	for _, signer := range []neofscrypto.Signer{
		neofsecdsa.Signer(*k),
		neofsecdsa.SignerRFC6979(*k),
		neofsecdsa.SignerWalletConnect(*k),
	} {
		// calculate signature
		_ = sig.Calculate(signer, data)
		fmt.Printf("scheme: %d; public key: %x; signature: %x\n",
			sig.Scheme(), sig.PublicKeyBytes(), sig.Value())
		// attach the signature to the request or data structure
	}
}

func (*Signature) FromProtoMessage

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

FromProtoMessage validates m according to the NeoFS API protocol and restores x from it.

See also Signature.ProtoMessage.

func (Signature) Marshal

func (x Signature) Marshal() []byte

Marshal encodes x transmitted via NeoFS API protocol into a dynamically allocated buffer.

func (Signature) ProtoMessage

func (x Signature) ProtoMessage() *refs.Signature

ProtoMessage converts x into message to transmit using the NeoFS API protocol.

See also Signature.FromProtoMessage.

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.FromProtoMessage 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.FromProtoMessage 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) 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.FromProtoMessage or Signature.Calculate methods.

func (*Signature) SetPublicKeyBytes

func (x *Signature) SetPublicKeyBytes(pub []byte)

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

The pub length should not be greater than MaxVerificationScriptLength.

func (*Signature) SetScheme

func (x *Signature) SetScheme(s Scheme)

SetScheme sets signature scheme used by signer to calculate the signature.

func (*Signature) SetValue

func (x *Signature) SetValue(v []byte)

SetValue sets calculated digital signature.

The v length should not be greater than MaxInvocationScriptLength.

func (*Signature) Unmarshal

func (x *Signature) Unmarshal(b []byte) error

Unmarshal decodes x transmitted via NeoFS API protocol from data.

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.FromProtoMessage 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
package main

import (
	"encoding/hex"
	"fmt"

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

func main() {
	// get data to be verified
	data := []byte("Hello, world!")

	for _, tc := range []struct {
		scheme neofscrypto.Scheme
		pub    string
		val    string
	}{
		{
			scheme: neofscrypto.ECDSA_SHA512,
			pub:    "034f10e101921787b4bd69098350cdfea4c5493f6b1d0f8829276b2a460988bd6f",
			val:    "0401cf064093860d4996a9e22df3638c6bcebbd326e82f01cf9c37942a652a79a4fea18ec3777fda6c999162a9414180ce8e11aad97ede7a5da930faebf195aaa8",
		},
		{
			scheme: neofscrypto.ECDSA_DETERMINISTIC_SHA256,
			pub:    "034f10e101921787b4bd69098350cdfea4c5493f6b1d0f8829276b2a460988bd6f",
			val:    "274e6a5ebae221f2c57ea9b9429c6410f31c17580a1d579088ee1839539a044f9cb89886552ed8b21b3c618ee223a061e9957518c327c81397fed074bd31d796",
		},
		{
			scheme: neofscrypto.ECDSA_WALLETCONNECT,
			pub:    "034f10e101921787b4bd69098350cdfea4c5493f6b1d0f8829276b2a460988bd6f",
			val:    "b41afc64b7a77b15ce269f9a52e39131dbe06e827cd469010ee575b7d8e4df6a627c7c79673a292f32066640b9c9b487a5aee74c45dcef8e7a0da4a2a20e9bae018647a3a43e253c26749e964593e542",
		},
	} {
		// get signature
		pub, _ := hex.DecodeString(tc.pub)
		val, _ := hex.DecodeString(tc.val)
		sig := neofscrypto.NewSignatureFromRawKey(tc.scheme, pub, val)
		// verify the signature
		valid := sig.Verify(data)
		fmt.Printf("valid: %t, scheme: %d; public key: %s; signature: %s\n",
			valid, tc.scheme, tc.pub, tc.val)
	}
}

type SignedRequest

type SignedRequest[B ProtoMessage] interface {
	GetBody() B
	GetMetaHeader() *session.RequestMetaHeader
	GetVerifyHeader() *session.RequestVerificationHeader
}

SignedRequest is a generic interface of a signed NeoFS API request.

type SignedResponse

type SignedResponse[B ProtoMessage] interface {
	GetBody() B
	GetMetaHeader() *session.ResponseMetaHeader
	GetVerifyHeader() *session.ResponseVerificationHeader
}

SignedResponse is a generic interface of a signed NeoFS API response.

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 = neofsproto.Message

StablyMarshallable describes structs which can be marshalled transparently.

Directories

Path Synopsis
Package neofsecdsa collects ECDSA primitives for NeoFS cryptography.
Package neofsecdsa collects ECDSA primitives for NeoFS cryptography.
Package neofscryptotest provides helper functions to test code importing neofscrypto.
Package neofscryptotest provides helper functions to test code importing neofscrypto.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL