key

package
v1.3.2 Latest Latest
Warning

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

 Go to latest Published: Sep 29, 2024 License: MIT Imports: 14 Imported by: 4

Documentation

Overview

Package key implements algorithms and key objects for COSE as defined in RFC9052 and RFC9053. https://datatracker.ietf.org/doc/html/rfc9052#name-key-objects. https://datatracker.ietf.org/doc/html/rfc9053.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Base64Bytesify 

func Base64Bytesify(s string) []byte

Base64Bytesify converts a base64url string to []byte. It returns nil if the string is not a valid base64url string.

func ComputeHash 

func ComputeHash(h crypto.Hash, data []byte) ([]byte, error)

ComputeHash computes a hash of the given data using the given hash.

func GetRandomBytes 

func GetRandomBytes(n uint16) []byte

GetRandomBytes randomly generates n bytes.

func GetRandomUint32 

func GetRandomUint32() uint32

GetRandomUint32 randomly generates an unsigned 32-bit integer.

func HexBytesify 

func HexBytesify(h string) []byte

HexBytesify converts a hex string to []byte. It returns nil if the string is not a valid hex string.

func MarshalCBOR 

func MarshalCBOR(v any) ([]byte, error)

MarshalCBOR marshals value with the special cbor.EncOptions.

func MustMarshalCBOR 

func MustMarshalCBOR(v any) []byte

MustMarshalCBOR marshals value with the special cbor.EncOptions. It will panic if marshaling failed.

func RegisterEncryptor 

func RegisterEncryptor(kty, alg int, fn EncryptorFactory)

RegisterEncryptor registers a EncryptorFactory for the given key type and algorithm.

func RegisterMACer 

func RegisterMACer(kty, alg int, fn MACerFactory)

RegisterMACer registers a MACerFactory for the given key type and algorithm.

func RegisterSigner 

func RegisterSigner(kty, alg, crv int, fn SignerFactory)

RegisterSigner registers a SignerFactory for the given key type, algorithm, and curve. For example, to register a ed25519 signer factory: 

key.RegisterSigner(iana.KeyTypeOKP, iana.AlgorithmEdDSA, iana.EllipticCurveEd25519, ed25519.NewSigner)

func RegisterVerifier 

func RegisterVerifier(kty, alg, crv int, fn VerifierFactory)

RegisterVerifier registers a VerifierFactory for the given key type, algorithm, and curve.

func ToInt added in v0.6.0 

func ToInt(v any) (int, error)

ToInt converts the given value to int, the range is [math.MinInt32, math.MaxInt32].

func UnmarshalCBOR 

func UnmarshalCBOR(data []byte, v any) error

UnmarshalCBOR unmarshals data into value with the special cbor.DecOptions.

func UnwrapBytes added in v1.1.0 

func UnwrapBytes(data []byte, err error) []byte

UnwrapBytes returns the data if err is nil, otherwise it panics.

func ValidCBOR 

func ValidCBOR(data []byte) error

ValidCBOR returns true if data is valid CBOR.

Types

type Alg 

type Alg int

Alg represents an IANA algorithm entry in the COSE Algorithms registry.

Reference https://www.iana.org/assignments/cose/cose.xhtml#algorithms

func CrvAlg added in v0.6.2 

func CrvAlg(c int) Alg

CrvAlg returns the algorithm that matched the key's curve.

func (Alg) HashFunc 

func (a Alg) HashFunc() crypto.Hash

HashFunc returns the hash associated with the algorithm supported.

type ByteStr 

type ByteStr []byte

ByteStr represents a byte string.

func SumKid added in v0.4.1 

func SumKid(data []byte) ByteStr

SumKid returns a 20 bytes kid with given data.

func (ByteStr) Base64 

func (bstr ByteStr) Base64() string

Base64 returns the raw base64url string representation of the byte string.

func (ByteStr) MarshalJSON 

func (bstr ByteStr) MarshalJSON() ([]byte, error)

MarshalJSON implements encoding/json interface for ByteStr.

func (ByteStr) MarshalText 

func (bstr ByteStr) MarshalText() ([]byte, error)

MarshalText implements encoding/text interface for ByteStr.

func (ByteStr) String 

func (bstr ByteStr) String() string

String returns the hex string representation of the byte string.

func (*ByteStr) UnmarshalJSON added in v1.2.0 

func (bstr *ByteStr) UnmarshalJSON(data []byte) error

UnmarshalJSON implements encoding/json interface for ByteStr.

func (*ByteStr) UnmarshalText added in v1.2.0 

func (bstr *ByteStr) UnmarshalText(text []byte) error

UnmarshalText implements encoding/text interface for ByteStr.

type CoseMap added in v1.3.0 

type CoseMap map[any]any

CoseMap represents a map of int/text to any value. It is the base type of key.Key, cose.Header, cwt.ClaimsMap.

func (CoseMap) Bytesify added in v1.3.0 

func (m CoseMap) Bytesify() []byte

Bytesify returns a CBOR-encoded byte slice. It returns nil if MarshalCBOR failed.

func (CoseMap) Get added in v1.3.0 

func (m CoseMap) Get(k any) any

Get returns the value for the key.

func (CoseMap) GetBool added in v1.3.0 

func (m CoseMap) GetBool(k any) (bool, error)

GetBool returns the value for the key as an boolean. If the key is not present, it returns (false, nil). If the underlying value's Kind is not Bool, it returns (false, error).

func (CoseMap) GetBytes added in v1.3.0 

func (m CoseMap) GetBytes(k any) (b []byte, err error)

GetBytes returns the value for the key as an []byte. If the key is not present, it returns (nil, nil). If the underlying value is not a slice of bytes or an addressable array of bytes, it returns (nil, error).

func (CoseMap) GetInt added in v1.3.0 

func (m CoseMap) GetInt(k any) (int, error)

GetInt returns the value for the key as an int. If the key is not present, it returns (0, nil). If the underlying value's Kind is not Int, Int8, Int16, Int32, Int64, Uint, Uint8, Uint16, Uint32, Int64, or the value's range is out of [math.MinInt32, math.MaxInt32], it returns (0, error).

func (CoseMap) GetInt64 added in v1.3.0 

func (m CoseMap) GetInt64(k any) (int64, error)

GetInt64 returns the value for the key as an int64. If the key is not present, it returns (0, nil). If the underlying value's Kind is not Int, Int8, Int16, Int32, Int64, Uint, Uint8, Uint16, Uint32, Int64, or the value is overflows, it returns (0, error).

func (CoseMap) GetMap added in v1.3.0 

func (m CoseMap) GetMap(k any) (CoseMap, error)

GetMap returns the value for the key as an CoseMap. If the key is not present, it returns (nil, nil). If the underlying value is not a CoseMap, it returns (nil, error).

func (CoseMap) GetString added in v1.3.0 

func (m CoseMap) GetString(k any) (string, error)

GetString returns the value for the key as an string. If the key is not present, it returns ("", nil). If the underlying value is not a string, it returns ("", error).

func (CoseMap) GetUint64 added in v1.3.0 

func (m CoseMap) GetUint64(k any) (uint64, error)

GetUint64 returns the value for the key as an uint64. If the key is not present, it returns (0, nil). If the underlying value's Kind is not Int, Int8, Int16, Int32, Int64, Uint, Uint8, Uint16, Uint32, Int64, or the value is overflows, it returns (0, error).

func (CoseMap) Has added in v1.3.0 

func (m CoseMap) Has(k any) bool

Has returns true if the map contains the key.

func (CoseMap) MarshalCBOR added in v1.3.0 

func (m CoseMap) MarshalCBOR() ([]byte, error)

MarshalCBOR implements the CBOR Marshaler interface for CoseMap.

func (CoseMap) MarshalJSON added in v1.3.0 

func (m CoseMap) MarshalJSON() ([]byte, error)

MarshalJSON implements encoding/json interface for CoseMap.

func (CoseMap) MarshalText added in v1.3.0 

func (m CoseMap) MarshalText() ([]byte, error)

MarshalText implements encoding/text interface for CoseMap.

func (CoseMap) Set added in v1.3.0 

func (m CoseMap) Set(k, value any) error

Set sets the value for the key. The key should be int or string.

func (*CoseMap) UnmarshalCBOR added in v1.3.0 

func (m *CoseMap) UnmarshalCBOR(data []byte) error

UnmarshalCBOR implements the CBOR Unmarshaler interface for CoseMap.

func (*CoseMap) UnmarshalJSON added in v1.3.0 

func (m *CoseMap) UnmarshalJSON(text []byte) error

UnmarshalJSON implements encoding/json interface for CoseMap.

func (*CoseMap) UnmarshalText added in v1.3.0 

func (m *CoseMap) UnmarshalText(text []byte) error

UnmarshalText implements encoding/text interface for CoseMap.

type Encryptor 

type Encryptor interface {
	// Encrypt encrypts a plaintext with the given nonce and additional data.
	// It returns the ciphertext or error.
	Encrypt(nonce, plaintext, additionalData []byte) (ciphertext []byte, err error)

	// Decrypt decrypts a ciphertext with the given nonce and additional data.
	// It returns the corresponding plaintext or error.
	Decrypt(nonce, ciphertext, additionalData []byte) (plaintext []byte, err error)

	// NonceSize returns the size of the nonce for encrypting and decrypting.
	NonceSize() int

	// Key returns the symmetric key in the Encryptor.
	// If the key's "key_ops" field is present, it MUST include "encrypt":3 when encrypting an plaintext.
	// If the key's "key_ops" field is present, it MUST include "decrypt":4 when decrypting an ciphertext.
	Key() Key
}

Encryptor is the encrypting and decrypting interface for content encryption. It is used in COSE_Encrypt and COSE_Encrypt0.

Reference https://datatracker.ietf.org/doc/html/rfc9052#name-content-encryption-algorith.

type EncryptorFactory 

type EncryptorFactory func(Key) (Encryptor, error)

EncryptorFactory is a function that returns a Encryptor for the given key.

type IntMap 

type IntMap = CoseMap

IntMap is an alias of CoseMap.

type Key 

type Key CoseMap

Key represents a COSE_Key object.

Reference https://datatracker.ietf.org/doc/html/rfc9052#name-key-objects.

func (Key) Alg 

func (k Key) Alg() Alg

Alg returns the key algorithm. If It is elliptic-curves key and algorithm is not present, it will return the algorithm that matched the curve.

Reference https://www.iana.org/assignments/cose/cose.xhtml#algorithms

func (Key) BaseIV 

func (k Key) BaseIV() ByteStr

BaseIV returns the base IV to be XORed with Partial IVs.

Reference https://www.iana.org/assignments/cose/cose.xhtml#key-common-parameters

func (Key) Bytesify 

func (k Key) Bytesify() []byte

Bytesify returns a CBOR-encoded byte slice. It returns nil if MarshalCBOR failed.

func (Key) Encryptor 

func (k Key) Encryptor() (Encryptor, error)

Encryptor returns a Encryptor for the given key. If the key is nil, or EncryptorFactory for the given key type and algorithm not registered, an error is returned.

func (Key) Get added in v1.3.0 

func (k Key) Get(p any) any

Get returns the value of the given parameter.

func (Key) GetBool 

func (k Key) GetBool(p any) (bool, error)

GetBool returns the value of the given parameter as a bool, or a error.

func (Key) GetBytes 

func (k Key) GetBytes(p any) ([]byte, error)

GetBytes returns the value of the given parameter as a slice of bytes, or a error.

func (Key) GetInt added in v0.6.0 

func (k Key) GetInt(p any) (int, error)

GetInt returns the value of the given parameter as a int, or a error.

func (Key) GetInt64 added in v0.6.0 

func (k Key) GetInt64(p any) (int64, error)

GetInt64 returns the value of the given parameter as a int64, or a error.

func (Key) GetString added in v0.6.0 

func (k Key) GetString(p any) (string, error)

GetString returns the value of the given parameter as a string, or a error.

func (Key) GetUint64 added in v0.6.0 

func (k Key) GetUint64(p any) (uint64, error)

GetUint64 returns the value of the given parameter as a uint64, or a error.

func (Key) Has 

func (k Key) Has(p any) bool

Has returns true if the key has the given parameter.

func (Key) Kid 

func (k Key) Kid() ByteStr

Kid returns the key identifier. If the key identifier is not present, or the underlying value's Kind is not []byte, it returns nil.

func (Key) Kty 

func (k Key) Kty() int

Kty returns the key type. If the key is nil, it returns KtyReserved.

Reference https://www.iana.org/assignments/cose/cose.xhtml#key-type

func (Key) MACer 

func (k Key) MACer() (MACer, error)

MACer returns a MACer for the given key. If the key is nil, or MACerFactory for the given key type and algorithm not registered, an error is returned.

func (Key) MarshalCBOR 

func (k Key) MarshalCBOR() ([]byte, error)

MarshalCBOR implements the CBOR Marshaler interface for Key.

func (Key) MarshalJSON 

func (k Key) MarshalJSON() ([]byte, error)

MarshalJSON implements encoding/json interface for Key.

func (Key) MarshalText added in v1.2.0 

func (k Key) MarshalText() ([]byte, error)

MarshalText implements encoding/text interface for Key.

func (Key) Ops 

func (k Key) Ops() Ops

Ops returns the key operations, or nil.

Reference https://www.iana.org/assignments/cose/cose.xhtml#key-common-parameters

func (Key) Set added in v1.3.0 

func (k Key) Set(p, value any) error

Set sets the parameter. parameter key should be int or string.

func (Key) SetKid 

func (k Key) SetKid(kid ByteStr)

SetKid sets the key identifier.

func (Key) SetOps 

func (k Key) SetOps(os ...int)

SetOps sets the key operations. If operations is empty, it will remove the key_ops field.

func (Key) Signer 

func (k Key) Signer() (Signer, error)

Signer returns a Signer for the given key. If the key is nil, or SignerFactory for the given key type, algorithm, and curve not registered, an error is returned.

func (*Key) UnmarshalCBOR added in v0.6.0 

func (k *Key) UnmarshalCBOR(data []byte) error

UnmarshalCBOR implements the CBOR Unmarshaler interface for Key.

func (*Key) UnmarshalJSON added in v1.2.0 

func (k *Key) UnmarshalJSON(text []byte) error

UnmarshalJSON implements encoding/json interface for Key.

func (*Key) UnmarshalText added in v1.2.0 

func (k *Key) UnmarshalText(text []byte) error

UnmarshalText implements encoding/text interface for Key.

func (Key) Verifier 

func (k Key) Verifier() (Verifier, error)

Verifier returns a Verifier for the given key. If the key is nil, or VerifierFactory for the given key type, algorithm, and curve not registered, an error is returned.

type KeySet 

type KeySet []Key

KeySet is a set of Keys.

func (KeySet) Lookup 

func (ks KeySet) Lookup(kid []byte) Key

Lookup returns the first key matching the given key id. return nil if there are no keys matching the key id

func (KeySet) Signers 

func (ks KeySet) Signers() (Signers, error)

Signers returns the signers for the keys in the KeySet.

func (KeySet) Verifiers 

func (ks KeySet) Verifiers() (Verifiers, error)

Verifiers returns the verifiers for the keys in the KeySet.

type MACer 

type MACer interface {
	// MACCreate computes message authentication code (MAC) for the given data.
	MACCreate(data []byte) ([]byte, error)

	// MACVerify verifies whether the given MAC is a correct message authentication code (MAC) for the given data.
	MACVerify(data, mac []byte) error

	// Key returns the key in the MACer.
	// If the key's "key_ops" field is present, it MUST include "MAC create":9 when creating an HMAC authentication tag.
	// If the key's "key_ops" field is present, it MUST include "MAC verify":10 when verifying an HMAC authentication tag.
	Key() Key
}

MACer is the MAC interface for MAC objects. It is used in COSE_Mac and COSE_Mac0.

Reference https://datatracker.ietf.org/doc/html/rfc9052#name-message-authentication-code.

type MACerFactory 

type MACerFactory func(Key) (MACer, error)

MACerFactory is a function that returns a MACer for the given key.

type Ops 

type Ops []int

Ops represents the key operations.

func (Ops) EmptyOrHas 

func (os Ops) EmptyOrHas(op int) bool

EmptyOrHas returns true if the operations is empty, or the given operation is in the operations.

func (Ops) Has 

func (os Ops) Has(op int) bool

Has returns true if the given operation is in the operations.

type Signer 

type Signer interface {
	// Computes the digital signature for data.
	Sign(data []byte) ([]byte, error)

	// Key returns the private key in the Signer.
	// If the key's "key_ops" field is present, it MUST include "sign":1.
	Key() Key
}

Signer is the signing interface for signing objects. It is used in COSE_Sign and COSE_Sign1.

Reference https://datatracker.ietf.org/doc/html/rfc9052#name-signature-algorithms.

type SignerFactory 

type SignerFactory func(Key) (Signer, error)

SignerFactory is a function that returns a Signer for the given key.

type Signers 

type Signers []Signer

Signers is a list of signers to be used for signing with one or more signers.

Reference https://datatracker.ietf.org/doc/html/rfc9052#name-signing-with-one-or-more-si.

func (Signers) KeySet added in v0.6.3 

func (ss Signers) KeySet() KeySet

KeySet returns a set of private keys from the Signers.

func (Signers) Lookup added in v0.6.3 

func (ss Signers) Lookup(kid []byte) Signer

Lookup returns the Signer for the given key ID.

type Verifier 

type Verifier interface {
	// Verifies returns nil if signature is a valid signature for data; otherwise returns an error.
	Verify(data, signature []byte) error

	// Key returns the public key in the Verifier.
	// The key returned by this method should not include private key bytes.
	// If the key's "key_ops" field is present, it MUST include "verify":12.
	Key() Key
}

Verifier is the verifying interface for signing objects.

Reference https://datatracker.ietf.org/doc/html/rfc9052#name-signature-algorithms.

type VerifierFactory 

type VerifierFactory func(Key) (Verifier, error)

VerifierFactory is a function that returns a Verifier for the given key.

type Verifiers 

type Verifiers []Verifier

Verifiers is a list of verifiers to be used for verifying with one or more verifiers.

Reference https://datatracker.ietf.org/doc/html/rfc9052#name-signing-with-one-or-more-si.

func (Verifiers) KeySet 

func (vs Verifiers) KeySet() KeySet

KeySet returns a set of public keys from the Verifiers.

func (Verifiers) Lookup 

func (vs Verifiers) Lookup(kid []byte) Verifier

Lookup returns the Verifier for the given key ID.

Source Files

View all Source files

Directories

Path Synopsis
Package aesccm implements content encryption algorithm AES-CCM for COSE as defined in RFC9053.
 Package aesccm implements content encryption algorithm AES-CCM for COSE as defined in RFC9053.
Package aesgcm implements content encryption algorithm AES-GCM for COSE as defined in RFC9053.
 Package aesgcm implements content encryption algorithm AES-GCM for COSE as defined in RFC9053.
Package aesmac implements message authentication code algorithm AES-CBC-MAC for COSE as defined in RFC9053.
 Package aesmac implements message authentication code algorithm AES-CBC-MAC for COSE as defined in RFC9053.
Package chacha20poly1305 implements content encryption algorithm ChaCha20/Poly1305 for COSE as defined in RFC9053.
 Package chacha20poly1305 implements content encryption algorithm ChaCha20/Poly1305 for COSE as defined in RFC9053.
Package ecdh implements key agreement algorithm ECDH for COSE as defined in RFC9053.
 Package ecdh implements key agreement algorithm ECDH for COSE as defined in RFC9053.
Package ecdsa implements signature algorithm ECDSA for COSE as defined in RFC9053.
 Package ecdsa implements signature algorithm ECDSA for COSE as defined in RFC9053.
Package ed25519 implements signature algorithm Ed25519 for COSE as defined in RFC9053.
 Package ed25519 implements signature algorithm Ed25519 for COSE as defined in RFC9053.
Package hkdf implements key derivation function HKDF for COSE as defined in RFC9053.
 Package hkdf implements key derivation function HKDF for COSE as defined in RFC9053.
Package hmac implements message authentication code algorithm HMAC for COSE as defined in RFC9053.
 Package hmac implements message authentication code algorithm HMAC for COSE as defined in RFC9053.

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.