@ldclabs/cose-ts NPM

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;
COSE: COSE_Encrypt0, COSE_Mac0, COSE_Sign1.
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`
ecdsa	@ldclabs/cose-ts/ecdsa	exports: class `ECDSAKey`, function `getCrv`, function `getCurve`
hmac	@ldclabs/cose-ts/hmac	exports: class `HMACKey`
aesgcm	@ldclabs/cose-ts/aesgcm	exports: class `AesGcmKey`
chacha20poly1305	@ldclabs/cose-ts/chacha20poly1305	exports: class `ChaCha20Poly1305Key`
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)