gose - v2.0.0

gose/cose/mac0

COSE_Mac0 single-recipient MAC creation and verification (RFC 9052).

Example

import gose/algorithm
import gose/cose/mac0
import gose/key

let k = key.generate_hmac_key(algorithm.HmacSha256)
let payload = <<"hello":utf8>>

let assert Ok(tagged) =
  mac0.new(algorithm.Hmac(algorithm.HmacSha256))
  |> mac0.tag(k, payload)

let data = mac0.serialize(tagged)
let assert Ok(parsed) = mac0.parse(data)
let assert Ok(verifier) =
  mac0.verifier(algorithm.Hmac(algorithm.HmacSha256), keys: [k])
let assert Ok(Nil) = mac0.verify(verifier, parsed)

Phantom Types

Mac0(state) uses a phantom type to track MAC state:

Algorithm Pinning

Each verifier is pinned to a single algorithm. The token’s protected header alg must match the verifier’s expected algorithm.

Types

Mac0

opaque </>

A COSE_Mac0 message parameterized by MAC state.

pub opaque type Mac0(state)

Tagged

</>

Phantom type for a COSE_Mac0 message that has been tagged or parsed.

pub type Tagged

Untagged

</>

Phantom type for a COSE_Mac0 message that has not yet been tagged.

pub type Untagged

Verifier

opaque </>

Holds an algorithm and set of keys for verifying a COSE_Mac0 message.

pub opaque type Verifier

Values

content_type

</> 
pub fn content_type(
  message: Mac0(Tagged),
) -> Result(cose.ContentType, gose.GoseError)

Extract the content type from the message headers.

critical

</> 
pub fn critical(
  message: Mac0(Tagged),
) -> Result(List(Int), gose.GoseError)

Extract the critical header labels from the message headers.

kid

</> 
pub fn kid(
  message: Mac0(Tagged),
) -> Result(BitArray, gose.GoseError)

Extract the key ID from the message headers.

new

</> 
pub fn new(alg: algorithm.MacAlg) -> Mac0(Untagged)

Create a new untagged COSE_Mac0 message with the given MAC algorithm in the protected header.

parse

</> 
pub fn parse(
  data: BitArray,
) -> Result(Mac0(Tagged), gose.GoseError)

Decode a CBOR-encoded COSE_Mac0 message, accepting both tagged and untagged forms.

payload

</> 
pub fn payload(message: Mac0(Tagged)) -> Result(BitArray, Nil)

Return the payload from a tagged message. Returns Error(Nil) if detached.

protected_headers

</> 
pub fn protected_headers(
  message: Mac0(Tagged),
) -> List(cose.Header)

Return the raw protected headers.

serialize

</> 
pub fn serialize(message: Mac0(Tagged)) -> BitArray

Encode a tagged message as an untagged CBOR COSE_Mac0 array.

serialize_tagged

</> 
pub fn serialize_tagged(message: Mac0(Tagged)) -> BitArray

Encode a tagged message as a CBOR-tagged (tag 17) COSE_Mac0 structure.

tag

</> 
pub fn tag(
  message: Mac0(Untagged),
  key key: key.Key(BitArray),
  payload payload: BitArray,
) -> Result(Mac0(Tagged), gose.GoseError)

Compute the MAC tag over the payload with the given key.

unprotected_headers

</> 
pub fn unprotected_headers(
  message: Mac0(Tagged),
) -> List(cose.Header)

Return the raw unprotected headers.

verifier

</> 
pub fn verifier(
  alg: algorithm.MacAlg,
  keys keys: List(key.Key(BitArray)),
) -> Result(Verifier, gose.GoseError)

Build a verifier pinned to a single algorithm and one or more keys.

verify

</> 
pub fn verify(
  verifier: Verifier,
  message message: Mac0(Tagged),
) -> Result(Nil, gose.GoseError)

Verify the MAC tag of a COSE_Mac0 message against the verifier’s expected algorithm and keys.

verify_detached

</> 
pub fn verify_detached(
  verifier: Verifier,
  message message: Mac0(Tagged),
  payload payload: BitArray,
) -> Result(Nil, gose.GoseError)

Verify the MAC tag of a detached-payload COSE_Mac0 message.

The caller must supply the payload that was detached from the message. Returns an error if the message already contains an embedded payload.

verify_detached_with_aad

</> 
pub fn verify_detached_with_aad(
  verifier: Verifier,
  message message: Mac0(Tagged),
  payload payload: BitArray,
  aad aad: BitArray,
) -> Result(Nil, gose.GoseError)

Verify a detached-payload COSE_Mac0 message with external AAD.

verify_with_aad

</> 
pub fn verify_with_aad(
  verifier: Verifier,
  message message: Mac0(Tagged),
  aad aad: BitArray,
) -> Result(Nil, gose.GoseError)

Verify the MAC tag with additional externally-supplied authenticated data (AAD).

with_aad

</> 
pub fn with_aad(
  message: Mac0(Untagged),
  aad aad: BitArray,
) -> Mac0(Untagged)

Set external additional authenticated data (AAD) for the MAC operation.

with_content_type

</> 
pub fn with_content_type(
  message: Mac0(Untagged),
  ct ct: cose.ContentType,
) -> Mac0(Untagged)

Add a content type to the unprotected headers.

RFC 9052 permits either bucket. MACed messages place it in unprotected, consistent with with_kid.

with_critical

</> 
pub fn with_critical(
  message: Mac0(Untagged),
  labels labels: List(Int),
) -> Mac0(Untagged)

Add critical header labels to the protected headers.

with_detached

</> 
pub fn with_detached(message: Mac0(Untagged)) -> Mac0(Untagged)

Mark the message for detached payload. The payload is still provided to tag for MAC computation but not included in the serialized output.

with_kid

</> 
pub fn with_kid(
  message: Mac0(Untagged),
  kid kid: BitArray,
) -> Mac0(Untagged)

Add a key ID to the unprotected headers.

✨ Search Document