README.md

Keys, Algorithms, COSE and CWT in Go

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

• Rust version: https://github.com/ldclabs/cose2
• Typescript version: https://github.com/ldclabs/cose-ts

Table of Contents

• Keys, Algorithms, COSE and CWT in Go
  • Table of Contents
  • Overview
  • Highlights
  • Installation
  • Quick Start
  • Package Guide
  • Examples
  • Agent Usage
  • Development
  • Security
  • References
  • License

Overview

This project provides:

• COSE message types defined by RFC 9052: Encrypt, Encrypt0, Mac, Mac0, Sign, Sign1, Recipient, and KDF context.
• CWT claims parsing/validation utilities defined by RFC 8392.
• IANA registries and key/algorithm abstractions defined by RFC 9053.

The implementation targets interoperability, explicit algorithm selection, and practical use in constrained or binary-first environments where CBOR is preferred.

Highlights

• Full COSE key object modeling and conversion helpers.
• Built-in support for common algorithms:
  • Signature: ECDSA, Ed25519
  • Encryption: AES-CCM, AES-GCM, ChaCha20/Poly1305
  • MAC: AES-CBC-MAC, HMAC
  • KDF: HKDF (SHA and AES variants)
  • ECDH: P-256, P-384, P-521, X25519
• Generic APIs for typed payload signing/verification and encryption/decryption.
• Explicit detached-content APIs (SignDetached, ComputeDetached, EncryptDetached, VerifyDetached, DecryptDetached) for COSE messages whose payload/ciphertext is transported separately (RFC 9052 §4.1/§5.1/§6.1).
• RFC 9052 §3 / §3.1 header validation on decode: rejects messages with a crit parameter outside the protected bucket, an empty or malformed crit array, critical labels missing from the protected bucket, or a label present in both the protected and unprotected buckets.
• Recipient.Validate for opt-in RFC 9052 §8.5 recipient-layer checks, and KeySet that enforces the non-empty COSE_KeySet requirement (§7).
• Rich test suite including package examples.

Installation

go get github.com/ldclabs/cose

Import the packages you need:

import (
	"github.com/ldclabs/cose/cose"
	"github.com/ldclabs/cose/cwt"
)

Most applications and generated examples can register all built-in algorithm packages with one side-effect import:

import _ "github.com/ldclabs/cose/key/all"

Library code can import only the concrete algorithm packages it needs:

import (
	_ "github.com/ldclabs/cose/key/ed25519"
	_ "github.com/ldclabs/cose/key/ecdsa"
	_ "github.com/ldclabs/cose/key/aesgcm"
	_ "github.com/ldclabs/cose/key/aesccm"
	_ "github.com/ldclabs/cose/key/chacha20poly1305"
	_ "github.com/ldclabs/cose/key/hmac"
	_ "github.com/ldclabs/cose/key/aesmac"
	_ "github.com/ldclabs/cose/key/ecdh"
	_ "github.com/ldclabs/cose/key/hkdf"
)

Quick Start

The snippet below creates a CWT payload, signs it with COSE_Sign1, verifies it, and validates claims:

package main

import (
	"fmt"
	"time"

	"github.com/ldclabs/cose/cose"
	"github.com/ldclabs/cose/cwt"
	"github.com/ldclabs/cose/key/ed25519"
)

func main() {
	priv, err := ed25519.GenerateKey()
	if err != nil {
		panic(err)
	}
	signer, err := priv.Signer()
	if err != nil {
		panic(err)
	}

	pub, err := ed25519.ToPublicKey(priv)
	if err != nil {
		panic(err)
	}
	verifier, err := pub.Verifier()
	if err != nil {
		panic(err)
	}

	claims := cwt.Claims{
		Issuer:     "ldc:ca",
		Subject:    "ldc:chain",
		Audience:   "ldc:txpool",
		Expiration: uint64(time.Now().Add(5 * time.Minute).Unix()),
	}

	msg := cose.Sign1Message[cwt.Claims]{Payload: claims}
	encoded, err := msg.SignAndEncode(signer, nil)
	if err != nil {
		panic(err)
	}

	verified, err := cose.VerifySign1Message[cwt.Claims](verifier, encoded, nil)
	if err != nil {
		panic(err)
	}

	validator, err := cwt.NewValidator(&cwt.ValidatorOpts{
		ExpectedIssuer:   "ldc:ca",
		ExpectedAudience: "ldc:txpool",
		ClockSkew:        time.Minute,
	})
	if err != nil {
		panic(err)
	}

	if err := validator.Validate(&verified.Payload); err != nil {
		panic(err)
	}

	fmt.Println("ok")
}

Package Guide

Package	Import	Description
cose	github.com/ldclabs/cose/cose	COSE message model and encode/decode/sign/encrypt APIs (RFC 9052).
cwt	github.com/ldclabs/cose/cwt	CWT claims model and validation logic (RFC 8392).
key	github.com/ldclabs/cose/key	COSE key objects, interfaces, registries, and CBOR helpers.
iana	github.com/ldclabs/cose/iana	Constants for COSE/CWT/CBOR IANA registries.
key/all	github.com/ldclabs/cose/key/all	Aggregate side-effect import for built-in algorithm packages.
key/ed25519	github.com/ldclabs/cose/key/ed25519	Ed25519 signing support.
key/ecdsa	github.com/ldclabs/cose/key/ecdsa	ECDSA signing support.
key/ecdh	github.com/ldclabs/cose/key/ecdh	ECDH key agreement support.
key/hmac	github.com/ldclabs/cose/key/hmac	HMAC support.
key/aesmac	github.com/ldclabs/cose/key/aesmac	AES-CBC-MAC support.
key/aesgcm	github.com/ldclabs/cose/key/aesgcm	AES-GCM content encryption support.
key/aesccm	github.com/ldclabs/cose/key/aesccm	AES-CCM content encryption support.
key/chacha20poly1305	github.com/ldclabs/cose/key/chacha20poly1305	ChaCha20/Poly1305 content encryption support.
key/hkdf	github.com/ldclabs/cose/key/hkdf	HKDF derivation support.

Examples

• COSE examples: cose/*_example_test.go
• CWT examples: cwt/example_test.go
• Algorithm package examples/tests: key/**/**/*_test.go
• Runnable recipes:
  • go run ./examples/sign1-cwt
  • go run ./examples/encrypt0-cwt
  • go run ./examples/detached-sign1

Run package examples together with tests:

go test ./...

Agent Usage

AI coding agents should read AGENTS.md before generating code for this module. It documents package selection, algorithm registration, COSE header rules, detached-content helpers, common errors, and verification commands.

Development

Project helper targets:

make test    # go test -v -failfast -tags=test --race ./...
make update  # go get -u all && go mod tidy

Security

• See SECURITY.md for vulnerability reporting.
• Keep dependencies and toolchain updated.
• Prefer strict key operation checks (key_ops) and validated claim constraints in production.

References

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 is licensed under the MIT License. See LICENSE.