key

package
v0.4.1 Latest Latest
Warning

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

Go to latest
Published: Dec 17, 2022 License: MIT Imports: 17 Imported by: 4

Documentation

Index

Constants

View Source
const (
	AlgReserved Alg = 0

	// ECDSA P-256 w/ SHA-256.
	AlgES256 Alg = -7
	// ECDSA P-384 w/ SHA-384.
	AlgES384 Alg = -35
	// ECDSA P-521 w/ SHA-512.
	AlgES512 Alg = -36

	// ECDSA using secp256k1 curve and SHA-256
	AlgES256K Alg = -47

	// PureEdDSA.
	AlgEdDSA Alg = -8

	// AES-GCM mode w/ 128-bit key, 128-bit tag
	AlgA128GCM Alg = 1
	// AES-GCM mode w/ 192-bit key, 128-bit tag
	AlgA192GCM Alg = 2
	// AES-GCM mode w/ 256-bit key, 128-bit tag
	AlgA256GCM Alg = 3

	// HMAC w/ SHA-256 truncated to 64 bits
	AlgHMAC25664 Alg = 4
	// HMAC w/ SHA-256
	AlgHMAC256256 Alg = 5
	// HMAC w/ SHA-384
	AlgHMAC384384 Alg = 6
	// HMAC w/ SHA-512
	AlgHMAC512512 Alg = 7

	// AES-CCM mode 128-bit key, 64-bit tag, 13-byte nonce
	AlgAESCCM1664128 = 10
	// AES-CCM mode 256-bit key, 64-bit tag, 13-byte nonce
	AlgAESCCM1664256 = 11
	// AES-CCM mode 128-bit key, 64-bit tag, 7-byte nonce
	AlgAESCCM6464128 = 12
	// AES-CCM mode 256-bit key, 64-bit tag, 7-byte nonce
	AlgAESCCM6464256 = 13
	// AES-CCM mode 128-bit key, 128-bit tag, 13-byte nonce
	AlgAESCCM16128128 = 30
	// AES-CCM mode 256-bit key, 128-bit tag, 13-byte nonce
	AlgAESCCM16128256 = 31
	// AES-CCM mode 128-bit key, 128-bit tag, 7-byte nonce
	AlgAESCCM64128128 = 32
	// AES-CCM mode 256-bit key, 128-bit tag, 7-byte nonce
	AlgAESCCM64128256 = 33

	// ChaCha20/Poly1305 w/ 256-bit key, 128-bit tag
	AlgChaCha20Poly1305 = 24

	// AES-CBC-MAC 128-bit key, 64-bit tag
	AlgAESMAC12864 Alg = 14
	// AES-CBC-MAC 256-bit key, 64-bit tag
	AlgAESMAC25664 Alg = 15
	// AES-CBC-MAC 128-bit key, 128-bit tag
	AlgAESMAC128128 Alg = 25
	// AES-CBC-MAC 256-bit key, 128-bit tag
	AlgAESMAC256128 Alg = 26
)

Algorithms supported by this library.

Reference https://datatracker.ietf.org/doc/html/rfc9053

View Source
const (
	MIMEApplicationCOSEKey    = "application/cose-key"
	MIMEApplicationCOSEKeySet = "application/cose-key-set"
)

Reference https://datatracker.ietf.org/doc/html/rfc9052#section-11.3.2

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 NewEncoder

func NewEncoder(w io.Writer) *cbor.Encoder

NewEncoder returns a new CBOR encoder with the special cbor.EncOptions.

func RegisterEncryptor

func RegisterEncryptor(kty Kty, alg Alg, fn EncryptorFactory)

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

func RegisterMACer

func RegisterMACer(kty Kty, alg Alg, fn MACerFactory)

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

func RegisterSigner

func RegisterSigner(kty Kty, alg Alg, crv Crv, fn SignerFactory)

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

key.RegisterSigner(key.KtyOKP, key.AlgEdDSA, key.CrvEd25519, ed25519.NewSigner)

func RegisterVerifier

func RegisterVerifier(kty Kty, alg Alg, crv Crv, fn VerifierFactory)

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

func SmallInt

func SmallInt(v any) (int, error)

SmallInt converts the given value to small int, which is from -65536 to 65536.

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

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

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

func (Alg) HashFunc

func (a Alg) HashFunc() crypto.Hash

HashFunc returns the hash associated with the algorithm supported.

func (Alg) String

func (a Alg) String() string

String returns the name of the algorithm

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

type Crv int

Crv represents the key's curve.

const (
	CrvReserved  Crv = 0
	CrvP256      Crv = 1
	CrvP384      Crv = 2
	CrvP521      Crv = 3
	CrvX25519    Crv = 4
	CrvX448      Crv = 5
	CrvEd25519   Crv = 6
	CrvEd448     Crv = 7
	CrvSecp256k1 Crv = 8
)

Reference https://www.iana.org/assignments/cose/cose.xhtml#elliptic-curves

func (Crv) Alg

func (c Crv) Alg() Alg

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

func (Crv) String

func (c Crv) String() string

String returns the name of the key's curve.

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 Encryptor.
	// If the "key_ops" field is present, it MUST include "encrypt" 3 when encrypting an plaintext.
	// If the "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#section-8.3

type EncryptorFactory

type EncryptorFactory func(Key) (Encryptor, error)

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

type IntKey

type IntKey int

IntKey is a key type for the IntMap, value is from -65536 to 65536.

const (
	OpSign       IntKey = 1  // "sign"
	OpVerify     IntKey = 2  // "verify"
	OpEncrypt    IntKey = 3  // "encrypt"
	OpDecrypt    IntKey = 4  // "decrypt"
	OpWrapKey    IntKey = 5  // "wrap key"
	OpUnwrapKey  IntKey = 6  // "unwrap key"
	OpDeriveKey  IntKey = 7  // "derive key"
	OpDeriveBits IntKey = 8  // "derive bits"
	OpMACCreate  IntKey = 9  // "MAC create"
	OpMACVerify  IntKey = 10 // "MAC verify"
)

Key Operation Values Reference https://datatracker.ietf.org/doc/html/rfc9052#name-cose-key-common-parameters

const (
	// COSE Key Common Parameters
	// Reference https://datatracker.ietf.org/doc/html/rfc9052#name-cose-key-common-parameters
	// Reference https://www.iana.org/assignments/cose/cose.xhtml#key-common-parameters
	ParamKty    IntKey = 1
	ParamKid    IntKey = 2
	ParamAlg    IntKey = 3
	ParamOps    IntKey = 4
	ParamBaseIV IntKey = 5

	// Reference https://www.iana.org/assignments/cose/cose.xhtml#key-type-parameters
	// KtyOKP, KtyEC2
	ParamCrv IntKey = -1
	ParamX   IntKey = -2
	ParamY   IntKey = -3
	ParamD   IntKey = -4

	// KtySymmetric
	ParamK IntKey = -1
)

type IntMap

type IntMap map[IntKey]any

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

func (IntMap) GetBool

func (m IntMap) GetBool(k IntKey) (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 IntKey) (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 IntKey) (int64, error)

GetInt 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) GetSmallInt

func (m IntMap) GetSmallInt(k IntKey) (int, error)

GetSmallInt returns the value for the key as an int in [-65536, 65536]. 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 [-65536, 65536], it returns (0, error).

func (IntMap) GetString

func (m IntMap) GetString(k IntKey) (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) GetUint

func (m IntMap) GetUint(k IntKey) (uint64, error)

GetUint 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 IntKey) 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. It sorts the int keys in increasing order and then encode the map. The map's capacity should be small, no more than 23 that is enough for COSE, CWT cases.

type Key

type Key IntMap

Key represents a COSE_Key object.

Reference https://datatracker.ietf.org/doc/html/rfc9052#section-7

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, algorithm not registered, an error is returned.

func (Key) GetBool

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

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

func (Key) GetBytes

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

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

func (Key) GetSmallInt

func (k Key) GetSmallInt(p IntKey) (int, error)

GetSmallInt returns the value of the given parameter as a small integer, or a error.

func (Key) Has

func (k Key) Has(p IntKey) 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() Kty

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, algorithm not registered, an error is returned.

func (Key) MarshalCBOR

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

MarshalCBOR implements the CBOR Marshaler interface for Key. It is the same as IntMap.MarshalCBOR.

func (Key) MarshalJSON

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

MarshalJSON implements the json.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) ParamString

func (k Key) ParamString(p IntKey) string

ParamString returns the name of the key parameter.

func (Key) SetKid

func (k Key) SetKid(kid ByteStr)

SetKid sets the key identifier.

func (Key) SetOps

func (k Key) SetOps(os Ops)

SetOps sets the key operations.

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

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 key set.

func (KeySet) Verifiers

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

Verifiers returns the verifiers for the keys in the key set.

type Kty

type Kty int

Kty represents the key type.

const (
	KtyReserved Kty = 0
	// Octet Key Pair
	KtyOKP Kty = 1
	// Elliptic Curve Keys w/ x- and y-coordinate pair
	KtyEC2       Kty = 2
	KtyRSA       Kty = 3
	KtySymmetric Kty = 4
	KtyHSSLMS    Kty = 5 // https://datatracker.ietf.org/doc/html/rfc8778
	KtyWalnutDSA Kty = 6 // https://datatracker.ietf.org/doc/html/rfc9021
)

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

func (Kty) String

func (k Kty) String() string

String returns the name of the key type

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) the given data.
	MACVerify(data, mac []byte) error

	// Key returns the key in MACer.
	// If the "key_ops" field is present, it MUST include "MAC create" 9 when creating an HMAC authentication tag.
	// If the "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#section-8.2

type MACerFactory

type MACerFactory func(Key) (MACer, error)

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

type Ops

type Ops []IntKey

Ops represents the key operations.

func (Ops) EmptyOrHas

func (os Ops) EmptyOrHas(op IntKey) bool

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

func (Ops) Has

func (os Ops) Has(op IntKey) bool

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

type Signer

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

	// Key returns the private key in Signer.
	// If the "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#section-8.1

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#section-4-1

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 Verifier.
	// The key returned by this method should not include private key bytes.
	// If the "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#section-8.1

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#section-4-1

func (Verifiers) KeySet

func (vs Verifiers) KeySet() KeySet

KeySet represents a list of public keys from the Verifiers.

func (Verifiers) Lookup

func (vs Verifiers) Lookup(kid ByteStr) Verifier

Lookup returns the verifier for the given key ID.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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