Keys, Algorithms, COSE and CWT

A TypeScript library for the CBOR Object Signing and Encryption (COSE) and CBOR Web Token (CWT).

• Golang version: https://github.com/ldclabs/cose
• Rust version: https://github.com/google/coset

Introduction

COSE is a standard for signing and encrypting data in the CBOR data format. It is designed to be simple and efficient, and to be usable in constrained environments. It is intended to be used in a variety of applications, including the Internet of Things, and is designed to be extensible to support new algorithms and applications.

Features

• Key: Full support.
• Algorithms:
  • Signing: ECDSA, Ed25519;
  • Encryption: AES-GCM, ChaCha20/Poly1305;
  • MAC: HMAC;
  • KDF: HKDF-SHA;
  • ECDH: P256, P384, P521, X25519;
• COSE: COSE_Encrypt0, COSE_Mac0, COSE_Sign1, COSE_KDF_Context.
• CWT: Full support.

Packages

| Package | Import | Description | | ---------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | cwt | @ldclabs/cose-ts/cwt | exports: class Claims, function withCWTTag, interface ValidatorOpts, class Validator | | encrypt0 | @ldclabs/cose-ts/encrypt0 | exports: class Encrypt0Message | | sign1 | @ldclabs/cose-ts/sign1 | exports: class Sign1Message | | mac0 | @ldclabs/cose-ts/mac0 | exports: class Mac0Message | | iana | @ldclabs/cose-ts/iana | IANA: COSE + IANA: CWT + IANA: CBOR Tags | | ed25519 | @ldclabs/cose-ts/ed25519 | exports: class Ed25519Key | | ecdh | @ldclabs/cose-ts/ecdh | exports: class ECDHKey, function getCurve, function getKeySize | | ecdsa | @ldclabs/cose-ts/ecdsa | exports: class ECDSAKey, function getCrv, function getCurve | | hkdf | @ldclabs/cose-ts/hkdf | exports: function hkdf256, function hkdf512 | | hmac | @ldclabs/cose-ts/hmac | exports: class HMACKey | | aesgcm | @ldclabs/cose-ts/aesgcm | exports: class AesGcmKey | | | chacha20poly1305 | @ldclabs/cose-ts/chacha20poly1305 | exports: class ChaCha20Poly1305Key | | kdfcontext | @ldclabs/cose-ts/kdfcontext | exports: class KDFContext, class PartyInfo, class SuppPubInfo | | key | @ldclabs/cose-ts/key | exports: class Key, interface Encryptor, interface MACer, interface Signer, interface Verifier | | hash | @ldclabs/cose-ts/hash | exports: hmac, sha256, sha384, sha512, sha3_256, sha3_384, sha3_512, function getHash | | header | @ldclabs/cose-ts/header | exports: class Header | | map | @ldclabs/cose-ts/map | exports: class KVMap, type RawMap, type AssertFn<T>, assertText, assertInt, assertIntOrText, assertBytes, assertBool, assertMap | | tag | @ldclabs/cose-ts/tag | exports: function withTag, function skipTag, and many consts | | utils | @ldclabs/cose-ts/utils | exports: bytesToHex, hexToBytes, utf8ToBytes, randomBytes, toBytes, concatBytes, bytesToBase64Url, base64ToBytes, compareBytes, decodeCBOR, encodeCBOR |

Examples

CWT in Sign1Message with Ed25519 Key

import { utf8ToBytes, randomBytes, compareBytes } from '@ldclabs/cose-ts/utils'
import { Validator, Claims, withCWTTag } from '@ldclabs/cose-ts/cwt'
import { Ed25519Key } from '@ldclabs/cose-ts/ed25519'
import { Sign1Message } from '@ldclabs/cose-ts/sign1'

// get key
const privKey = Ed25519Key.generate()
// const privKey = Ed25519Key.fromSecret(32_bytes_secret)
const pubKey = privKey.public()
// const pubKey = Ed25519Key.fromPublic(32_bytes_public)

const externalData = utf8ToBytes('@ldclabs/cose-ts') // optional

// signing
const claims = new Claims()
claims.iss = 'ldclabs'
claims.aud = 'cose-ts'
claims.sub = 'tester'
claims.exp = Math.floor(Date.now() / 1000) + 3600
claims.cti = randomBytes(16)

const cwtMsg = new Sign1Message(claims.toBytes())
const cwtData = cwtMsg.toBytes(privKey, externalData)
// const cwtDataWithTag = withCWTTag(cwtData)

// verifying
const cwtMsg2 = Sign1Message.fromBytes(
  pubKey,
  cwtData, // or cwtDataWithTag
  externalData
)
const claims2 = Claims.fromBytes(cwtMsg2.payload)
const validator = new Validator({ expectedIssuer: 'ldclabs' })
validator.validate(claims2)
assert.equal(claims2.iss, claims.iss)
assert.equal(claims2.aud, claims.aud)
assert.equal(claims2.sub, claims.sub)
assert.equal(claims2.exp, claims.exp)
assert.equal(compareBytes(claims2.cti, claims.cti), 0)

Security Reviews

Todo.

Reference

1. RFC9052: CBOR Object Signing and Encryption (COSE)
2. RFC8392: CBOR Web Token (CWT)
3. RFC9053: CBOR Object Signing and Encryption (COSE): Initial Algorithms
4. IANA: CBOR Object Signing and Encryption (COSE)
5. IANA: CBOR Web Token (CWT) Claims
6. IANA: Concise Binary Object Representation (CBOR) Tags

License

Copyright © 2022-2024 LDC Labs.

ldclabs/cose-ts is licensed under the MIT License. See LICENSE for the full license text.