IF Commons GitHub

cose

Written to: 1 requirement: 0 proved, 0 partly, 0 failing, 1 with no test recorded. 0001-crypto FR-008

COSE keys and signatures (RFC 9052, RFC 9053) as WebAuthn uses them (commons 0014-webauthn FR-002): a credential's public key read from its CBOR COSE_Key, checked for one of the two algorithms commons accepts (ES256, -7: ECDSA on P-256 with SHA-256; EdDSA, -8: Ed25519), imported into Web Crypto, and a signature verified with it, an ECDSA signature turned from the DER Ecdsa-Sig-Value an authenticator gives into the raw r || s Web Crypto takes. A COSE_Key can also be made from a public JSON Web Key, which is how a test (or a migration from stored JWKs) writes one.

import { coseKeyFromJwk, parseCoseKey, verifyCose } from "./cose.ts";
const pair = await crypto.subtle.generateKey({ name: "Ed25519" }, true, ["sign", "verify"]);
const cose = coseKeyFromJwk(await crypto.subtle.exportKey("jwk", pair.publicKey));
const data = new TextEncoder().encode("signed");
const sig = new Uint8Array(await crypto.subtle.sign({ name: "Ed25519" }, pair.privateKey, data));
if (cose.kind === "ok") {
  const key = parseCoseKey(cose.value);
  if (key.kind === "ok") await verifyCose(key.value, sig, data); // { kind: "ok", value: true }
}

Source: commons/crypto/src/cose.ts

8 of 24 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

cosenamespace
namespace cose
cose.ES256constno test imports it
const ES256: -7

COSE's identifier of ES256: ECDSA on P-256 with SHA-256.

cose.EDDSAconstno test imports it
const EDDSA: -8

COSE's identifier of EdDSA (here always Ed25519).

cose.ALGORITHMSconstno test imports it
const ALGORITHMS: readonly number[]

The algorithms commons accepts, in order of preference.

cose.CoseKeytypeno test imports it
type CoseKey =
  | { readonly kty: "EC2"; readonly alg: typeof ES256; readonly crv: "P-256"; readonly x: Uint8Array; readonly y: Uint8Array }
  | { readonly kty: "OKP"; readonly alg: typeof EDDSA; readonly crv: "Ed25519"; readonly x: Uint8Array };

A public key read from a COSE_Key: an EC2 key on P-256 for ES256, or an OKP key on Ed25519 for EdDSA.

cose.parseCoseKeyfunctionno test imports it
function parseCoseKey(bytes: Uint8Array<ArrayBufferLike>): Result<CoseKey, string>

A COSE_Key read from its CBOR: a map with kty (1), alg (3), crv (-1), x (-2) and, for EC2, y (-3); anything else refused.

cose.encodeCoseKeyfunctionno test imports it
function encodeCoseKey(key: CoseKey): Uint8Array<ArrayBufferLike>

The CBOR COSE_Key of a key (deterministic: its labels sorted).

cose.Jwktypeno test imports it
type Jwk = {
  readonly alg?: string;
  readonly crv?: string;
  readonly d?: string;
  readonly e?: string;
  readonly ext?: boolean;
  readonly key_ops?: string[];
  readonly kty?: string;
  readonly n?: string;
  readonly use?: string;
  readonly x?: string;
  readonly y?: string;
};

A JSON Web Key (RFC 7517) as the fields this module reads and writes, declared here so that no consumer needs the dom library for a type of it.

cose.coseKeyFromJwkfunctionno test imports it
function coseKeyFromJwk(jwk: Jwk): Result<Uint8Array<ArrayBufferLike>, string>

The COSE_Key of a public JSON Web Key: EC on P-256 (as ES256) or OKP on Ed25519 (as EdDSA); any other key refused.

cose.jwkOfCoseKeyfunctionno test imports it
function jwkOfCoseKey(key: CoseKey): Jwk

The public JSON Web Key of a COSE key.

cose.importCoseKeyfunctionno test imports it
function importCoseKey(key: CoseKey): Promise<Result<CryptoKey, string>>

The key imported into Web Crypto for verifying; a point not on its curve is refused.

cose.ecdsaDerToRawfunctionno test imports it
function ecdsaDerToRaw(der: Uint8Array<ArrayBufferLike>, size?: number): Result<Uint8Array<ArrayBufferLike>, string>

An ECDSA signature as DER (Ecdsa-Sig-Value ::= SEQUENCE { r INTEGER, s INTEGER }) turned into raw r || s of size bytes each.

cose.verifyCosefunctionno test imports it
function verifyCose(key: CoseKey, signature: Uint8Array<ArrayBufferLike>, data: Uint8Array<ArrayBufferLike>): Promise<Result<boolean, string>>

Whether signature is the key's signature of data (ES256: DER as WebAuthn gives it; EdDSA: 64 raw bytes); an unusable key or a malformed signature is an error.

ES256const
const ES256: -7

COSE's identifier of ES256: ECDSA on P-256 with SHA-256.

Imported by 14 tests of the run (14 passed, 0 failed): the library's results

EDDSAconst
const EDDSA: -8

COSE's identifier of EdDSA (here always Ed25519).

Imported by 14 tests of the run (14 passed, 0 failed): the library's results

ALGORITHMSconstno test imports it
const ALGORITHMS: readonly number[]

The algorithms commons accepts, in order of preference.

CoseKeytypeno test imports it
type CoseKey =
  | { readonly kty: "EC2"; readonly alg: typeof ES256; readonly crv: "P-256"; readonly x: Uint8Array; readonly y: Uint8Array }
  | { readonly kty: "OKP"; readonly alg: typeof EDDSA; readonly crv: "Ed25519"; readonly x: Uint8Array };

A public key read from a COSE_Key: an EC2 key on P-256 for ES256, or an OKP key on Ed25519 for EdDSA.

parseCoseKeyfunction
function parseCoseKey(bytes: Uint8Array<ArrayBufferLike>): Result<CoseKey, string>

A COSE_Key read from its CBOR: a map with kty (1), alg (3), crv (-1), x (-2) and, for EC2, y (-3); anything else refused.

Imported by 14 tests of the run (14 passed, 0 failed): the library's results

encodeCoseKeyfunction
function encodeCoseKey(key: CoseKey): Uint8Array<ArrayBufferLike>

The CBOR COSE_Key of a key (deterministic: its labels sorted).

Imported by 14 tests of the run (14 passed, 0 failed): the library's results

Jwktypeno test imports it
type Jwk = {
  readonly alg?: string;
  readonly crv?: string;
  readonly d?: string;
  readonly e?: string;
  readonly ext?: boolean;
  readonly key_ops?: string[];
  readonly kty?: string;
  readonly n?: string;
  readonly use?: string;
  readonly x?: string;
  readonly y?: string;
};

A JSON Web Key (RFC 7517) as the fields this module reads and writes, declared here so that no consumer needs the dom library for a type of it.

coseKeyFromJwkfunction
function coseKeyFromJwk(jwk: Jwk): Result<Uint8Array<ArrayBufferLike>, string>

The COSE_Key of a public JSON Web Key: EC on P-256 (as ES256) or OKP on Ed25519 (as EdDSA); any other key refused.

Imported by 14 tests of the run (14 passed, 0 failed): the library's results

jwkOfCoseKeyfunction
function jwkOfCoseKey(key: CoseKey): Jwk

The public JSON Web Key of a COSE key.

Imported by 14 tests of the run (14 passed, 0 failed): the library's results

importCoseKeyfunctionno test imports it
function importCoseKey(key: CoseKey): Promise<Result<CryptoKey, string>>

The key imported into Web Crypto for verifying; a point not on its curve is refused.

ecdsaDerToRawfunction
function ecdsaDerToRaw(der: Uint8Array<ArrayBufferLike>, size?: number): Result<Uint8Array<ArrayBufferLike>, string>

An ECDSA signature as DER (Ecdsa-Sig-Value ::= SEQUENCE { r INTEGER, s INTEGER }) turned into raw r || s of size bytes each.

Imported by 14 tests of the run (14 passed, 0 failed): the library's results

verifyCosefunction
function verifyCose(key: CoseKey, signature: Uint8Array<ArrayBufferLike>, data: Uint8Array<ArrayBufferLike>): Promise<Result<boolean, string>>

Whether signature is the key's signature of data (ES256: DER as WebAuthn gives it; EdDSA: 64 raw bytes); an unusable key or a malformed signature is an error.

Imported by 14 tests of the run (14 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.