key

package
v0.6.6 Latest Latest
Warning

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

Go to latest
Published: Jan 5, 2023 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 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 the json.Marshaler interface for ByteStr.

func (ByteStr) MarshalText

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

MarshalText implements the encoding.TextMarshaler interface for ByteStr.

func (ByteStr) String

func (bstr ByteStr) String() string

String returns the hex string representation of the byte string.

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 map[int]any

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

func (IntMap) Bytesify added in v0.6.6

func (m IntMap) Bytesify() []byte

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

func (IntMap) GetBool

func (m IntMap) GetBool(k int) (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 (IntMap) GetBytes

func (m IntMap) GetBytes(k int) (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 (IntMap) GetInt

func (m IntMap) GetInt(k int) (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 (IntMap) GetInt64 added in v0.6.0

func (m IntMap) GetInt64(k int) (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 (IntMap) GetString

func (m IntMap) GetString(k int) (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 (IntMap) GetUint64 added in v0.6.0

func (m IntMap) GetUint64(k int) (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 (IntMap) Has

func (m IntMap) Has(k int) bool

Has returns true if the map contains the key.

func (IntMap) MarshalCBOR

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

MarshalCBOR implements the CBOR Marshaler interface for IntMap.

func (*IntMap) UnmarshalCBOR added in v0.6.6

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

UnmarshalCBOR implements the CBOR Unmarshaler interface for IntMap.

type Key

type Key IntMap

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) GetBool

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

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

func (Key) GetBytes

func (k Key) GetBytes(p int) ([]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 int) (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 int) (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 int) (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 int) (uint64, error)

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

func (Key) Has

func (k Key) Has(p int) 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) 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) 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) 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.

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