key

package
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: Dec 17, 2022 License: MIT Imports: 16 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 (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.

Source Files

View all Source files

Directories

Path Synopsis

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.