Documentation
¶
Overview ¶
Package cose decodes a COSE_Key (RFC 9052 / RFC 8152, with parameters from the IANA COSE registries) into human-readable fields: key type, signature algorithm, curve, and the public-key coordinates. COSE keys are how WebAuthn / FIDO2 credentials, CWT (CBOR Web Tokens), and many IoT flows carry public keys, so an operator who has pulled a credential public key out of an attestation (e.g. via webauthn_authdata_decode) can read what it actually is instead of eyeballing a CBOR map of integer labels.
It builds on internal/cbordecode for the CBOR parse and then interprets the COSE label/value registries. There is no checksum — this is registry-driven field interpretation — so the risk is mis-mapping a label, which the tests pin against real-format EC2 / OKP / RSA keys.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AlgorithmName ¶ added in v0.758.0
AlgorithmName maps a COSE algorithm identifier (the value at COSE header label 1, or COSE_Key label 3) to its IANA name, or "unknown(<id>)". The registry is shared by COSE keys and COSE message headers (e.g. CWT), so it is exported for reuse rather than duplicated.
Types ¶
type COSERecipient ¶ added in v0.765.0
type COSERecipient struct {
Protected Header `json:"protected_header"`
Unprotected Header `json:"unprotected_header"`
EncryptedKeyHex string `json:"encrypted_key_hex,omitempty"`
}
COSERecipient is one recipient of a COSE_Encrypt / COSE_Mac message (RFC 9052 §5.1 / §6.1): its own protected & unprotected headers (the key-management algorithm, kid, …) and the encrypted content-encryption key. Nested recipients (multi-layer key management) are not recursed — a single level covers the common case.
type COSESignature ¶ added in v0.765.0
type COSESignature struct {
Protected Header `json:"protected_header"`
Unprotected Header `json:"unprotected_header"`
SignatureHex string `json:"signature_hex,omitempty"`
}
COSESignature is one signer of a COSE_Sign message (RFC 9052 §4.1): its own protected & unprotected headers (algorithm, kid, …) and the signature bytes.
type Header ¶ added in v0.759.0
type Header struct {
Algorithm string `json:"algorithm,omitempty"` // label 1
AlgID *int64 `json:"algorithm_id,omitempty"`
Critical []int64 `json:"critical,omitempty"` // label 2 (crit)
ContentType string `json:"content_type,omitempty"` // label 3
KeyIDHex string `json:"key_id_hex,omitempty"` // label 4 (kid)
IVHex string `json:"iv_hex,omitempty"` // label 5
PartialIVHex string `json:"partial_iv_hex,omitempty"` // label 6
Other map[string]string `json:"other,omitempty"`
}
Header is the decoded subset of COSE header parameters (IANA "COSE Header Parameters", RFC 9052 §3.1) most useful for triage. Less common parameters are collected, by integer label, into Other.
type Key ¶
type Key struct {
KeyType string `json:"key_type"` // OKP / EC2 / RSA / Symmetric / unknown(N)
KeyTypeID int64 `json:"key_type_id"`
Algorithm string `json:"algorithm,omitempty"` // e.g. ES256, EdDSA, RS256, unknown(N)
AlgID *int64 `json:"algorithm_id,omitempty"`
Curve string `json:"curve,omitempty"` // EC2/OKP: P-256, Ed25519, ...
CurveID *int64 `json:"curve_id,omitempty"`
KeyIDHex string `json:"key_id_hex,omitempty"`
// EC2 / OKP public coordinates.
XHex string `json:"x_hex,omitempty"`
YHex string `json:"y_hex,omitempty"` // EC2 only
// RSA public parameters.
ModulusHex string `json:"modulus_hex,omitempty"`
ExponentHex string `json:"exponent_hex,omitempty"`
// HasPrivateKey is true when a private component (EC2/OKP d, or RSA d)
// is present — a captured COSE key that carries the private key is
// worth flagging.
HasPrivateKey bool `json:"has_private_key"`
}
Key is a decoded COSE_Key. Only the fields relevant to the key type are populated; hex fields carry the raw coordinate / modulus bytes.
type Message ¶ added in v0.759.0
type Message struct {
Type string `json:"type"` // COSE_Sign1 / COSE_Sign / COSE_Mac0 / COSE_Mac / COSE_Encrypt0 / COSE_Encrypt / …
Tag *uint64 `json:"tag,omitempty"`
Tagged bool `json:"tagged"`
Protected Header `json:"protected_header"`
Unprotected Header `json:"unprotected_header"`
PayloadHex string `json:"payload_hex,omitempty"`
PayloadDetached bool `json:"payload_detached"`
// Single-recipient final elements.
SignatureHex string `json:"signature_hex,omitempty"` // COSE_Sign1
TagHex string `json:"tag_hex,omitempty"` // COSE_Mac0 authentication tag
CiphertextHex string `json:"ciphertext_hex,omitempty"` // COSE_Encrypt0
// Multi-recipient structures: the count plus the decoded per-entry
// detail (each entry's own protected/unprotected headers and signature /
// encrypted-key bytes), so a multi-signer attestation or multi-recipient
// encrypted message is fully readable rather than just counted.
SignatureCount *int `json:"signature_count,omitempty"` // COSE_Sign
Signatures []COSESignature `json:"signatures,omitempty"` // COSE_Sign
RecipientCount *int `json:"recipient_count,omitempty"` // COSE_Mac / COSE_Encrypt
Recipients []COSERecipient `json:"recipients,omitempty"` // COSE_Mac / COSE_Encrypt
Note string `json:"note"`
}
Message is a decoded COSE message (RFC 9052). Only the fields relevant to the message type are populated. Signature / tag / ciphertext bytes are surfaced as hex; the signature and recipient counts are reported for the multi-recipient structures rather than fully recursing.
func DecodeMessage ¶ added in v0.759.0
DecodeMessage parses raw CBOR bytes as a COSE message and surfaces its structure: message type, decoded protected & unprotected headers, payload, and the type-specific final element(s). It does NOT verify any signature or MAC and cannot decrypt — those need keys an operator inspecting a captured artifact won't have — so the result carries an explicit not-verified note.
Source Files