# Keys, Algorithms, COSE and CWT [![CI](https://github.com/ldclabs/cose-ts/actions/workflows/ci.yml/badge.svg)](https://github.com/ldclabs/cose-ts/actions/workflows/ci.yml) [![NPM version](http://img.shields.io/npm/v/@ldclabs/cose-ts.svg)](https://www.npmjs.com/package/@ldclabs/cose-ts) [![License](http://img.shields.io/badge/license-mit-blue.svg?style=flat-square)](https://raw.githubusercontent.com/ldclabs/cose-ts/main/LICENSE) **This is a fork of ldclabs/cose-ts that adds Secp256k1 keys to the possible keys to use.** *A TypeScript library for the [CBOR Object Signing and Encryption (COSE)][cose-spec] and [CBOR Web Token (CWT)][cwt-spec].* + Golang version: [https://github.com/ldclabs/cose](https://github.com/ldclabs/cose) + Rust version: [https://github.com/google/coset](https://github.com/google/coset) ## Introduction COSE is a standard for signing and encrypting data in the [CBOR][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](https://github.com/ldclabs/cose-ts/blob/main/src/cwt.ts) | @ldclabs/cose-ts/cwt | exports: class `Claims`, function `withCWTTag`, interface `ValidatorOpts`, class `Validator` | | [encrypt0](https://github.com/ldclabs/cose-ts/blob/main/src/encrypt0.ts) | @ldclabs/cose-ts/encrypt0 | exports: class `Encrypt0Message` | | [sign1](https://github.com/ldclabs/cose-ts/blob/main/src/sign1.ts) | @ldclabs/cose-ts/sign1 | exports: class `Sign1Message` | | [mac0](https://github.com/ldclabs/cose-ts/blob/main/src/mac0.ts) | @ldclabs/cose-ts/mac0 | exports: class `Mac0Message` | | [iana](https://github.com/ldclabs/cose-ts/blob/main/src/iana.ts) | @ldclabs/cose-ts/iana | [IANA: COSE][iana-cose] + [IANA: CWT][iana-cwt] + [IANA: CBOR Tags][iana-cbor-tags] | | [ed25519](https://github.com/ldclabs/cose-ts/blob/main/src/ed25519.ts) | @ldclabs/cose-ts/ed25519 | exports: class `Ed25519Key` | | [ecdh](https://github.com/ldclabs/cose-ts/blob/main/src/ecdh.ts) | @ldclabs/cose-ts/ecdh | exports: class `ECDHKey`, function `getCurve`, function `getKeySize` | | [ecdsa](https://github.com/ldclabs/cose-ts/blob/main/src/ecdsa.ts) | @ldclabs/cose-ts/ecdsa | exports: class `ECDSAKey`, function `getCrv`, function `getCurve` | | [hkdf](https://github.com/ldclabs/cose-ts/blob/main/src/hkdf.ts) | @ldclabs/cose-ts/hkdf | exports: function `hkdf256`, function `hkdf512` | | [hmac](https://github.com/ldclabs/cose-ts/blob/main/src/hmac.ts) | @ldclabs/cose-ts/hmac | exports: class `HMACKey` | | [aesgcm](https://github.com/ldclabs/cose-ts/blob/main/src/aesgcm.ts) | @ldclabs/cose-ts/aesgcm | exports: class `AesGcmKey` | | | [chacha20poly1305](https://github.com/ldclabs/cose-ts/blob/main/src/chacha20poly1305.ts) | @ldclabs/cose-ts/chacha20poly1305 | exports: class `ChaCha20Poly1305Key` | | [kdfcontext](https://github.com/ldclabs/cose-ts/blob/main/src/kdfcontext.ts) | @ldclabs/cose-ts/kdfcontext | exports: class `KDFContext`, class `PartyInfo`, class `SuppPubInfo` | | [key](https://github.com/ldclabs/cose-ts/blob/main/src/key.ts) | @ldclabs/cose-ts/key | exports: class `Key`, interface `Encryptor`, interface `MACer`, interface `Signer`, interface `Verifier` | | [hash](https://github.com/ldclabs/cose-ts/blob/main/src/hash.ts) | @ldclabs/cose-ts/hash | exports: `hmac`, `sha256`, `sha384`, `sha512`, `sha3_256`, `sha3_384`, `sha3_512`, function `getHash` | | [header](https://github.com/ldclabs/cose-ts/blob/main/src/header.ts) | @ldclabs/cose-ts/header | exports: class `Header` | | [map](https://github.com/ldclabs/cose-ts/blob/main/src/map.ts) | @ldclabs/cose-ts/map | exports: class `KVMap`, type `RawMap`, type `AssertFn`, `assertText`, `assertInt`, `assertIntOrText`, `assertBytes`, `assertBool`, `assertMap` | | [tag](https://github.com/ldclabs/cose-ts/blob/main/src/tag.ts) | @ldclabs/cose-ts/tag | exports: function `withTag`, function `skipTag`, and many consts | | [utils](https://github.com/ldclabs/cose-ts/blob/main/src/utils.ts) | @ldclabs/cose-ts/utils | exports: `bytesToHex`, `hexToBytes`, `utf8ToBytes`, `randomBytes`, `toBytes`, `concatBytes`, `bytesToBase64Url`, `base64ToBytes`, `compareBytes`, `decodeCBOR`, `encodeCBOR` | ## Examples ### CWT in Sign1Message with Ed25519 Key ```typescript 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)][cose-spec] 2. [RFC8392: CBOR Web Token (CWT)][cwt-spec] 3. [RFC9053: CBOR Object Signing and Encryption (COSE): Initial Algorithms][algorithms-spec] 4. [IANA: CBOR Object Signing and Encryption (COSE)][iana-cose] 5. [IANA: CBOR Web Token (CWT) Claims][iana-cwt] 6. [IANA: Concise Binary Object Representation (CBOR) Tags][iana-cbor-tags] [cbor]: https://datatracker.ietf.org/doc/html/rfc8949 [cose-spec]: https://datatracker.ietf.org/doc/html/rfc9052 [cwt-spec]: https://datatracker.ietf.org/doc/html/rfc8392 [algorithms-spec]: https://datatracker.ietf.org/doc/html/rfc9053 [iana-cose]: https://www.iana.org/assignments/cose/cose.xhtml [iana-cwt]: https://www.iana.org/assignments/cwt/cwt.xhtml [iana-cbor-tags]: https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml ## License Copyright © 2022-2024 [LDC Labs](https://github.com/ldclabs). ldclabs/cose-ts is licensed under the MIT License. See [LICENSE](LICENSE) for the full license text.