crop

package module
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Nov 28, 2025 License: BSD-3-Clause Imports: 22 Imported by: 0

README

CROP — Cryptographic Routines, Operations & Primitives

Simple, but safe(r) to use building blocks for cryptographic systems.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrAuthCodeInvalid            = errors.New("invalid message authentication code")
	ErrCannotReuse                = errors.New("cannot reuse")
	ErrChallengeFailed            = errors.New("challenge failed")
	ErrChecksumMismatch           = errors.New("checksum mismatch")
	ErrInvalidFormat              = errors.New("invalid format")
	ErrInvalidKeyPairType         = errors.New("invalid key pair type")
	ErrNoPrivateKey               = errors.New("no private key available")
	ErrNoPublicKey                = errors.New("no public key available")
	ErrRequestedKeyLengthTooSmall = errors.New("request key length too small")
)
View Source 
var Default = Suite{
	// contains filtered or unexported fields
}

Default is the default cryptographic suite using X25519, BLAKE3, Ed25519, context hashing, and HMAC-BLAKE3.

Functions

func FindStoredKeyType 

func FindStoredKeyType[T ~string](sk *StoredKey, acceptable []T) (found T, ok bool)

FindStoredKeyType finds the type of the given stored key using the given acceptable types, using case insensitive matching.

func NewSecret 

func NewSecret(length int) []byte

NewSecret returns a new random secret with the given length (minimum 32 bytes).

Types

type Blake3Keymaker 

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

Blake3Keymaker implements KeyMaker using BLAKE3 key derivation.

func (*Blake3Keymaker) Burn 

func (b3km *Blake3Keymaker) Burn()

func (*Blake3Keymaker) DeriveKey 

func (b3km *Blake3Keymaker) DeriveKey(keyContext, keyParty string, keyLength int) ([]byte, error)

func (*Blake3Keymaker) DeriveKeyInto added in v0.2.0 

func (b3km *Blake3Keymaker) DeriveKeyInto(keyContext, keyParty string, dst []byte) error

func (*Blake3Keymaker) Type 

func (b3km *Blake3Keymaker) Type() KeyMakerType

type Challenge 

type Challenge interface {
	// Type returns the challenge algorithm type.
	Type() ChallengeType
	// GetChallenge returns the challenge bytes to send.
	GetChallenge() []byte
	// CheckResponse verifies a response to the challenge.
	CheckResponse(data []byte) error
	// MakeResponse generates a response to a received challenge.
	MakeResponse(challenge []byte) (response []byte, err error)
}

Challenge implements challenge-response authentication between peers.

func NewChallenge 

func NewChallenge(ct ChallengeType, purpose, requesterContext, responderContext string) (Challenge, error)

NewChallenge creates a new challenge for authentication.

type ChallengeType 

type ChallengeType string

ChallengeType identifies a challenge-response authentication algorithm. 

const (
	// ChallengeTypeContextHashBl3 uses context-bound hashing with BLAKE3.
	ChallengeTypeContextHashBl3 ChallengeType = "context-hash-bl3"
)

func (ChallengeType) IsValid 

func (ct ChallengeType) IsValid() bool

IsValid returns whether this challenge type is supported.

func (ChallengeType) New 

func (ct ChallengeType) New(purpose, requesterContext, responderContext string) (Challenge, error)

func (ChallengeType) String added in v0.2.0 

func (ct ChallengeType) String() string

type Ed25519KeyPair 

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

Ed25519KeyPair implements the KeyPair interface for Ed25519 signatures.

func MakeEd25519KeyPair added in v0.2.0 

func MakeEd25519KeyPair(privKey ed25519.PrivateKey, pubKey ed25519.PublicKey) *Ed25519KeyPair

MakeEd25519KeyPair creates an Ed25519KeyPair from existing key material.

func (*Ed25519KeyPair) Burn 

func (edkp *Ed25519KeyPair) Burn()

func (*Ed25519KeyPair) Export 

func (edkp *Ed25519KeyPair) Export() (*StoredKey, error)

func (*Ed25519KeyPair) HasPrivate 

func (edkp *Ed25519KeyPair) HasPrivate() bool

func (*Ed25519KeyPair) PrivateKeyData 

func (edkp *Ed25519KeyPair) PrivateKeyData() []byte

PrivateKeyData returns the raw private key bytes.

func (*Ed25519KeyPair) PublicKey 

func (edkp *Ed25519KeyPair) PublicKey() crypto.PublicKey

func (*Ed25519KeyPair) PublicKeyData 

func (edkp *Ed25519KeyPair) PublicKeyData() []byte

PublicKeyData returns the raw public key bytes.

func (*Ed25519KeyPair) Sign 

func (edkp *Ed25519KeyPair) Sign(data []byte) (signature []byte, err error)

func (*Ed25519KeyPair) ToPublic 

func (edkp *Ed25519KeyPair) ToPublic() KeyPair

func (*Ed25519KeyPair) Type 

func (edkp *Ed25519KeyPair) Type() KeyPairType

func (*Ed25519KeyPair) Verify 

func (edkp *Ed25519KeyPair) Verify(data, sig []byte) error

type Hash 

type Hash string

Hash is a hash algorithm. 

const (
	// SHA2.
	SHA2_224     Hash = "SHA2_224"
	SHA2_256     Hash = "SHA2_256"
	SHA2_384     Hash = "SHA2_384"
	SHA2_512     Hash = "SHA2_512"
	SHA2_512_224 Hash = "SHA2_512_224"
	SHA2_512_256 Hash = "SHA2_512_256"

	// SHA3.
	SHA3_224 Hash = "SHA3_224"
	SHA3_256 Hash = "SHA3_256"
	SHA3_384 Hash = "SHA3_384"
	SHA3_512 Hash = "SHA3_512"

	// BLAKE2.
	BLAKE2s_256 Hash = "BLAKE2s_256"
	BLAKE2b_256 Hash = "BLAKE2b_256"
	BLAKE2b_384 Hash = "BLAKE2b_384"
	BLAKE2b_512 Hash = "BLAKE2b_512"

	// BLAKE3.
	BLAKE3 Hash = "BLAKE3"
)

Hashes

func (Hash) Digest 

func (h Hash) Digest(data []byte) []byte

Digest calculate and returns the hash sum over the given data.

func (Hash) IsValid 

func (h Hash) IsValid() bool

IsValid returns whether the hash is known.

func (Hash) New 

func (h Hash) New() hash.Hash

New returns a new hash.Hash.

func (Hash) String added in v0.2.0 

func (h Hash) String() string

func (Hash) Verify 

func (h Hash) Verify(data, checksum []byte) error

Verify calculates the checksum of the given data and checks if it matches the given checksum.

type HashBasedMAC added in v0.2.0 

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

HashBasedMAC implements MsgAuthCodeHandler using hash-based MACs.

func (*HashBasedMAC) Burn added in v0.2.0 

func (hbm *HashBasedMAC) Burn()

func (*HashBasedMAC) Sign added in v0.2.0 

func (hbm *HashBasedMAC) Sign(context string, data []byte) (mac []byte)

func (*HashBasedMAC) Type added in v0.2.0 

func (hbm *HashBasedMAC) Type() MsgAuthCodeType

func (*HashBasedMAC) Verify added in v0.2.0 

func (hbm *HashBasedMAC) Verify(context string, data []byte, mac []byte) error

type HashedContextChallenge 

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

HashedContextChallenge implements Challenge using context-bound hashing.

func (*HashedContextChallenge) CheckResponse 

func (hcc *HashedContextChallenge) CheckResponse(data []byte) error

func (*HashedContextChallenge) GetChallenge 

func (hcc *HashedContextChallenge) GetChallenge() []byte

func (*HashedContextChallenge) MakeResponse 

func (hcc *HashedContextChallenge) MakeResponse(challenge []byte) (response []byte, err error)

func (*HashedContextChallenge) Type added in v0.2.0 

func (hcc *HashedContextChallenge) Type() ChallengeType

type KeyExchange 

type KeyExchange interface {
	// Type returns the key exchange algorithm type.
	Type() KeyExchangeType
	// ExchangeMsg returns the public key to send to the peer.
	ExchangeMsg() ([]byte, error)
	// MakeKeys derives shared keys from the peer's public key.
	MakeKeys(exchMsg []byte, keyMakerType KeyMakerType) (KeyMaker, error)
	// Burn securely erases key material from memory.
	Burn()
}

KeyExchange performs key agreement between two parties.

func NewKeyExchange 

func NewKeyExchange(kmt KeyExchangeType) (KeyExchange, error)

NewKeyExchange creates a new key exchange instance of the specified type.

type KeyExchangeType 

type KeyExchangeType string

KeyExchangeType identifies a key exchange algorithm. 

const (
	// KeyExchangeTypeX25519 is the X25519 Diffie-Hellman key exchange.
	KeyExchangeTypeX25519 KeyExchangeType = "X25519"
)

func (KeyExchangeType) IsValid 

func (kmt KeyExchangeType) IsValid() bool

IsValid returns whether this key exchange type is supported.

func (KeyExchangeType) New 

func (kmt KeyExchangeType) New() (KeyExchange, error)

func (KeyExchangeType) String added in v0.2.0 

func (kxt KeyExchangeType) String() string

type KeyMaker 

type KeyMaker interface {
	// Type returns the key maker algorithm type.
	Type() KeyMakerType
	// DeriveKey creates a new key with domain separation.
	DeriveKey(keyContext, keyParty string, keyLength int) ([]byte, error)
	// DeriveKeyInto writes a derived key directly into dst.
	DeriveKeyInto(keyContext, keyParty string, dst []byte) error
	// Burn securely erases key material from memory.
	Burn()
}

KeyMaker derives multiple keys from shared key material.

func NewKeyMaker 

func NewKeyMaker(kmt KeyMakerType, key []byte) (KeyMaker, error)

NewKeyMaker creates a new key derivation instance from key material.

type KeyMakerType 

type KeyMakerType string

KeyMakerType identifies a key derivation algorithm. 

const (
	// KeyMakerTypeBlake3 derives keys using BLAKE3.
	KeyMakerTypeBlake3 KeyMakerType = "BLAKE3"
)

func (KeyMakerType) IsValid 

func (kmt KeyMakerType) IsValid() bool

IsValid returns whether this key maker type is supported.

func (KeyMakerType) New 

func (kmt KeyMakerType) New(keyMaterial []byte) (KeyMaker, error)

func (KeyMakerType) String added in v0.2.0 

func (kmt KeyMakerType) String() string

type KeyPair 

type KeyPair interface {
	// Type returns the key pair algorithm type.
	Type() KeyPairType
	// PublicKey returns the public key.
	PublicKey() crypto.PublicKey

	// HasPrivate returns true if this key pair includes a private key.
	HasPrivate() bool
	// ToPublic returns a copy containing only the public key.
	ToPublic() KeyPair

	// Sign creates a signature over the data using the private key.
	Sign(data []byte) (sig []byte, err error)
	// Verify checks that the signature is valid for the data.
	Verify(data, sig []byte) error

	// Export serializes the key pair to a StoredKey.
	Export() (*StoredKey, error)
	// Burn securely erases key material from memory.
	Burn()
}

KeyPair represents a public/private key pair for signing and verification.

func LoadKeyPair 

func LoadKeyPair(stored *StoredKey) (KeyPair, error)

LoadKeyPair loads a key pair from a StoredKey.

func NewKeyPair 

func NewKeyPair(kpType KeyPairType) (KeyPair, error)

NewKeyPair generates a new key pair of the specified type.

type KeyPairType 

type KeyPairType string

KeyPairType identifies a signing/verification key pair algorithm. 

const (
	// KeyPairTypeEd25519 is the Ed25519 signature scheme.
	KeyPairTypeEd25519 KeyPairType = "Ed25519"
)

func AllKeyPairTypes 

func AllKeyPairTypes() []KeyPairType

AllKeyPairTypes returns all supported key pair types.

func (KeyPairType) IsValid 

func (kpt KeyPairType) IsValid() bool

IsValid returns whether this key pair type is supported.

func (KeyPairType) New 

func (kpType KeyPairType) New() (KeyPair, error)

func (KeyPairType) String added in v0.2.0 

func (kpt KeyPairType) String() string

type LooseSequenceChecker 

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

LooseSequenceChecker allows some reordering of sequence numbers, up to 64 messages. Note: Does not roll over and will stop accepting sequence numbers after 2⁶⁴ messages.

func NewLooseSequenceChecker 

func NewLooseSequenceChecker() *LooseSequenceChecker

NewLooseSequenceChecker returns a new LooseSequenceChecker.

func (*LooseSequenceChecker) CheckInSequence 

func (lsc *LooseSequenceChecker) CheckInSequence(seqNum uint64) (ok bool)

CheckInSequence checks the sequence number of an incoming message. It returns whether the sequence number is okay and the message may be accepted.

func (*LooseSequenceChecker) NextOutSequence 

func (lsc *LooseSequenceChecker) NextOutSequence() uint64

NextOutSequence returns the next sequence number for an outgoing message.

type MsgAuthCodeHandler 

type MsgAuthCodeHandler interface {
	// Type returns the MAC algorithm type.
	Type() MsgAuthCodeType
	// Sign generates an authentication code for the data.
	Sign(context string, data []byte) (mac []byte)
	// Verify checks that the MAC is valid for the data.
	Verify(context string, data []byte, mac []byte) error
	// Burn securely erases key material from memory.
	Burn()
}

MsgAuthCodeHandler generates and verifies message authentication codes.

func NewAuthCodeHandler 

func NewAuthCodeHandler(act MsgAuthCodeType, signKey, verifyKey []byte, seqChecker SequenceChecker) (MsgAuthCodeHandler, error)

NewAuthCodeHandler creates a new MAC handler with separate keys for signing and verification.

type MsgAuthCodeType 

type MsgAuthCodeType string

MsgAuthCodeType identifies a message authentication code algorithm. 

const (
	// MsgAuthCodeTypeHMACBlake3 uses HMAC with BLAKE3.
	MsgAuthCodeTypeHMACBlake3 MsgAuthCodeType = "HMAC-BLAKE3"
	// MsgAuthCodeTypeBlake3 uses keyed BLAKE3.
	MsgAuthCodeTypeBlake3 MsgAuthCodeType = "BLAKE3"
)

func (MsgAuthCodeType) IsValid 

func (act MsgAuthCodeType) IsValid() bool

IsValid returns whether this MAC type is supported.

func (MsgAuthCodeType) New 

func (act MsgAuthCodeType) New(signKey, verifyKey []byte, seqChecker SequenceChecker) (MsgAuthCodeHandler, error)

func (MsgAuthCodeType) String added in v0.2.0 

func (act MsgAuthCodeType) String() string

type SequenceChecker 

type SequenceChecker interface {
	// NextOutSequence returns the next sequence number for an outgoing message.
	NextOutSequence() uint64

	// CheckInSequence checks the sequence number of an incoming message.
	// It returns whether the sequence number is okay and the message may be accepted.
	CheckInSequence(n uint64) (ok bool)
}

SequenceChecker checks sequence numbers and mitigates replay attacks.

type StoredKey 

type StoredKey struct {
	Type      string `cbor:"t,omitzero" json:"t,omitzero"`
	IsPrivate bool   `cbor:"p,omitzero" json:"p,omitzero"`
	Key       []byte `cbor:"k,omitzero" json:"k,omitzero"`
}

StoredKey is an intermediary format used for exporting and importing keys.

func LoadKeyFromBytes 

func LoadKeyFromBytes(data []byte) (*StoredKey, error)

LoadKeyFromBytes loads a stored key from the binary format.

func LoadKeyFromJSON 

func LoadKeyFromJSON(data []byte) (*StoredKey, error)

LoadKeyFromJSON loads a stored key from json.

func LoadKeyFromText 

func LoadKeyFromText(text string) (*StoredKey, error)

LoadKeyFromText loads a stored key from the text format.

func (*StoredKey) Bytes 

func (sk *StoredKey) Bytes() ([]byte, error)

Bytes returns the stored key formatted in binary format.

func (*StoredKey) IsType 

func (sk *StoredKey) IsType(expected string) bool

IsType checks whether the stored key is of the expected type, using case insensitive matching.

func (*StoredKey) JSON 

func (sk *StoredKey) JSON() ([]byte, error)

JSON returns the stored key as json.

func (*StoredKey) Text 

func (sk *StoredKey) Text() string

Text returns the stored key formatted in text format.

type StrictSequenceChecker 

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

StrictSequenceChecker only allows sequence numbers higher than the highest previously received sequence number. Note: Using this on message without guaranteed delivery order will result in lost messages. Note: Does not roll over and will stop accepting sequence numbers after 2⁶⁴ messages.

func NewStrictSequenceChecker 

func NewStrictSequenceChecker() *StrictSequenceChecker

NewStrictSequenceChecker returns a new StrictSequenceChecker.

func (*StrictSequenceChecker) CheckInSequence 

func (ssc *StrictSequenceChecker) CheckInSequence(n uint64) (ok bool)

CheckInSequence checks the sequence number of an incoming message. It returns whether the sequence number is okay and the message may be accepted.

func (*StrictSequenceChecker) NextOutSequence 

func (ssc *StrictSequenceChecker) NextOutSequence() uint64

NextOutSequence returns the next sequence number for an outgoing message.

type Suite 

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

Suite defines a collection of cryptographic algorithms to be used together.

func (Suite) KeyExchangeType 

func (s Suite) KeyExchangeType() KeyExchangeType

KeyExchangeType returns the key exchange algorithm type for this suite.

func (Suite) KeyMakerType 

func (s Suite) KeyMakerType() KeyMakerType

KeyMakerType returns the key derivation algorithm type for this suite.

func (Suite) KeyPairType 

func (s Suite) KeyPairType() KeyPairType

KeyPairType returns the key pair algorithm type for this suite.

type ValueHasher 

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

ValueHasher hashes structured data with field separation.

func NewValueHasher 

func NewValueHasher(h hash.Hash) *ValueHasher

NewValueHasher creates a structured hasher for multiple values.

func (*ValueHasher) Add 

func (vh *ValueHasher) Add(data []byte)

Add hashes a byte slice field.

func (*ValueHasher) AddString 

func (vh *ValueHasher) AddString(data string)

AddString hashes a string field.

func (*ValueHasher) AddUint added in v0.3.0 

func (vh *ValueHasher) AddUint(n uint64)

AddUint hashes an uint field.

func (*ValueHasher) Sum 

func (vh *ValueHasher) Sum(dst []byte) []byte

Sum finalizes and returns the hash result.

type X25519KeyExchange 

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

X25519KeyExchange implements KeyExchange using X25519.

func (*X25519KeyExchange) Burn 

func (xke *X25519KeyExchange) Burn()

func (*X25519KeyExchange) ExchangeMsg 

func (xke *X25519KeyExchange) ExchangeMsg() ([]byte, error)

func (*X25519KeyExchange) MakeKeys 

func (xke *X25519KeyExchange) MakeKeys(exchMsg []byte, keyMakerType KeyMakerType) (KeyMaker, error)

func (*X25519KeyExchange) Type 

func (xke *X25519KeyExchange) Type() KeyExchangeType

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.