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 ¶
- Constants
- Variables
- func PublicKeyBytes(pubKey PublicKey) []byte
- func RegisterScheme(scheme Scheme, f func() PublicKey)
- func SignRequestWithBuffer[B ProtoMessage](signer Signer, r SignedRequest[B], buf []byte) (*session.RequestVerificationHeader, error)
- func SignResponseWithBuffer[B ProtoMessage](signer Signer, r SignedResponse[B], buf []byte) (*session.ResponseVerificationHeader, error)
- func StringifyKeyBinary(src []byte) string
- func VerifyMessageSignature(m ProtoMessage, s *refs.Signature, b []byte) error
- func VerifyRequestWithBuffer[B ProtoMessage](r SignedRequest[B], buf []byte) error
- func VerifyRequestWithBufferN3[B ProtoMessage](r SignedRequest[B], buf []byte, ...) error
- func VerifyResponseWithBuffer[B ProtoMessage](r SignedResponse[B], buf []byte) error
- type ProtoMessage
- type PublicKey
- type Scheme
- type Signature
- func (x *Signature) Calculate(signer Signer, data []byte) error
- func (x *Signature) FromProtoMessage(m *refs.Signature) error
- func (x Signature) Marshal() []byte
- func (x Signature) ProtoMessage() *refs.Signature
- func (x Signature) PublicKey() PublicKey
- func (x Signature) PublicKeyBytes() []byte
- func (x Signature) Scheme() Scheme
- func (x *Signature) SetPublicKeyBytes(pub []byte)
- func (x *Signature) SetScheme(s Scheme)
- func (x *Signature) SetValue(v []byte)
- func (x *Signature) Unmarshal(b []byte) error
- func (x Signature) Value() []byte
- func (x Signature) Verify(data []byte) bool
- type SignedRequest
- type SignedResponse
- type Signer
- type StablyMarshallable
Examples ¶
Constants ¶
const ( MaxVerificationScriptLength = 1024 // verification script or public key binary MaxInvocationScriptLength = 1024 // invocation script or signature )
Protocol limits.
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 ¶
PublicKeyBytes returns binary-encoded PublicKey. Use PublicKey.Encode to avoid new slice allocation.
func RegisterScheme ¶
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 ¶
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 ¶
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 )
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 ¶
NewN3Signature constructs signature from given N3 witness scripts.
The verifScript and invocScript lengths should not be greater than MaxVerificationScriptLength and MaxInvocationScriptLength correspondingly.
func NewSignature ¶
NewSignature is a Signature instance constructor.
The value length should not be greater than MaxInvocationScriptLength.
func NewSignatureFromRawKey ¶
NewSignatureFromRawKey constructs new Signature instance.
The pub and value lengths should not be greater than MaxVerificationScriptLength and MaxInvocationScriptLength correspondingly.
func (*Signature) Calculate ¶
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
}
}
Output:
func (*Signature) FromProtoMessage ¶
FromProtoMessage validates m according to the NeoFS API protocol and restores x from it.
See also Signature.ProtoMessage.
func (Signature) Marshal ¶
Marshal encodes x transmitted via NeoFS API protocol into a dynamically allocated buffer.
func (Signature) ProtoMessage ¶
ProtoMessage converts x into message to transmit using the NeoFS API protocol.
See also Signature.FromProtoMessage.
func (Signature) 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 ¶
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 ¶
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 ¶
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 ¶
SetScheme sets signature scheme used by signer to calculate the signature.
func (*Signature) SetValue ¶
SetValue sets calculated digital signature.
The v length should not be greater than MaxInvocationScriptLength.
func (Signature) Value ¶
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 ¶
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)
}
}
Output:
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. |