gose - v2.0.0

gose/cose/sign1

COSE_Sign1 single-signer signing and verification (RFC 9052).

Example

import gose/algorithm
import gose/cose/sign1
import gose/key
import kryptos/ec

let k = key.generate_ec(ec.P256)
let payload = <<"hello":utf8>>

let assert Ok(signed) =
  sign1.new(algorithm.Ecdsa(algorithm.EcdsaP256))
  |> sign1.sign(k, payload)

let data = sign1.serialize(signed)
let assert Ok(parsed) = sign1.parse(data)
let assert Ok(verifier) =
  sign1.verifier(algorithm.Ecdsa(algorithm.EcdsaP256), keys: [k])
let assert Ok(Nil) = sign1.verify(verifier, parsed)

Phantom Types

Sign1(state) uses a phantom type to track signing 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

Sign1

opaque </>

A COSE_Sign1 message parameterized by signing state.

pub opaque type Sign1(state)

Signed

</>

Phantom type for a COSE_Sign1 message that has been signed or parsed.

pub type Signed

Unsigned

</>

Phantom type for a COSE_Sign1 message that has not yet been signed.

pub type Unsigned

Verifier

opaque </>

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

pub opaque type Verifier

Values

content_type

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

Extract the content type from the message headers.

critical

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

Extract the critical header labels from the message headers.

kid

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

Extract the key ID from the message headers.

new

</> 
pub fn new(alg: algorithm.DigitalSignatureAlg) -> Sign1(Unsigned)

Create a new unsigned COSE_Sign1 message with the given signature algorithm in the protected header.

parse

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

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

payload

</> 
pub fn payload(message: Sign1(Signed)) -> Result(BitArray, Nil)

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

protected_headers

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

Return the raw protected headers.

serialize

</> 
pub fn serialize(message: Sign1(Signed)) -> BitArray

Encode a signed message as an untagged CBOR COSE_Sign1 array.

serialize_tagged

</> 
pub fn serialize_tagged(message: Sign1(Signed)) -> BitArray

Encode a signed message as a CBOR-tagged (tag 18) COSE_Sign1 structure.

sign

</> 
pub fn sign(
  message: Sign1(Unsigned),
  key key: key.Key(BitArray),
  payload payload: BitArray,
) -> Result(Sign1(Signed), gose.GoseError)

Sign the payload with the given key, producing a signed COSE_Sign1 message.

unprotected_headers

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

Return the raw unprotected headers.

verifier

</> 
pub fn verifier(
  alg: algorithm.DigitalSignatureAlg,
  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: Sign1(Signed),
) -> Result(Nil, gose.GoseError)

Verify the signature of a signed COSE_Sign1 message against the verifier’s expected algorithm and keys.

verify_detached

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

Verify the signature of a detached-payload COSE_Sign1 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: Sign1(Signed),
  payload payload: BitArray,
  aad aad: BitArray,
) -> Result(Nil, gose.GoseError)

Verify a detached-payload COSE_Sign1 message with external AAD.

verify_with_aad

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

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

with_aad

</> 
pub fn with_aad(
  message: Sign1(Unsigned),
  aad aad: BitArray,
) -> Sign1(Unsigned)

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

with_content_type

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

Add a content type to the unprotected headers.

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

with_critical

</> 
pub fn with_critical(
  message: Sign1(Unsigned),
  labels labels: List(Int),
) -> Sign1(Unsigned)

Add critical header labels to the protected headers.

with_detached

</> 
pub fn with_detached(message: Sign1(Unsigned)) -> Sign1(Unsigned)

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

with_kid

</> 
pub fn with_kid(
  message: Sign1(Unsigned),
  kid kid: BitArray,
) -> Sign1(Unsigned)

Add a key ID to the unprotected headers.

✨ Search Document