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.