@ldclabs/cose-ts
TypeScript icon, indicating that this package has built-in type declarations

1.2.0 • Public • Published

Keys, Algorithms, COSE and CWT

CI NPM version License

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

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)

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.

Package Sidebar

Install

npm i @ldclabs/cose-ts

Weekly Downloads

10

Version

1.2.0

License

MIT

Unpacked Size

148 kB

Total Files

54

Last publish

Collaborators

  • zensh