Keys, Algorithms, COSE and CWT in Go

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

Index

• Keys, Algorithms, COSE and CWT in Go
  • Index
  • Introduction
  • Features
  • Installation
  • Packages
  • Examples
    • Create a simple CWT with a signer
    • Create a complex CWT with one more signers
  • Security Reviews
  • Reference
  • License

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-CCM, AES-GCM, ChaCha20/Poly1305;
  • MAC: AES-MAC, HMAC;
  • KDF: HKDF-SHA, HKDF-AES.
  • ECDH: P256, P384, P521, X25519.
• COSE: COSE_Encrypt, COSE_Encrypt0, COSE_Mac, COSE_Mac0, COSE_Sign, COSE_Sign1, COSE_recipient, COSE_KDF_Context.
• CWT: Full support.

Installation

To install COSE locally run:

go get github.com/ldclabs/cose

To import in the cwt package:

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

To register crypto algorithms:

import (
  _ "github.com/ldclabs/cose/key/ed25519"
  _ "github.com/ldclabs/cose/key/aesgcm"
)

Packages

Package name	Import	Description
cose	github.com/ldclabs/cose/cose	RFC9052: CBOR Object Signing and Encryption
cwt	github.com/ldclabs/cose/cwt	RFC8392: CBOR Web Token
iana	github.com/ldclabs/cose/iana	IANA: COSE + IANA: CWT + IANA: CBOR Tags
key	github.com/ldclabs/cose/key	RFC9053: Algorithms and Key Objects
ed25519	github.com/ldclabs/cose/key/ed25519	Signature Algorithm: Ed25519
ecdsa	github.com/ldclabs/cose/key/ecdsa	Signature Algorithm: ECDSA
ecdh	github.com/ldclabs/cose/key/ecdh	Elliptic Curve Diffie-Hellman Algorithm: ECDH
hmac	github.com/ldclabs/cose/key/hmac	Message Authentication Code (MAC) Algorithm: HMAC
aesmac	github.com/ldclabs/cose/key/aesmac	Message Authentication Code (MAC) Algorithm: AES-CBC-MAC
aesgcm	github.com/ldclabs/cose/key/aesgcm	Content Encryption Algorithm: AES-GCM
aesccm	github.com/ldclabs/cose/key/aesccm	Content Encryption Algorithm: AES-CCM
chacha20poly1305	github.com/ldclabs/cose/key/chacha20poly1305	Content Encryption Algorithm: ChaCha20/Poly1305
hkdf	github.com/ldclabs/cose/key/hkdf	Key Derivation Functions (KDFs) Algorithm: HKDF

Examples

Create a simple CWT with a signer

package main

import (
	"encoding/json"
	"fmt"
	"time"

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

func main() {
	// Create a ed25519 signer key
	privKey, err := ed25519.GenerateKey()
	if err != nil {
		panic(err)
	}
	signer, err := privKey.Signer()
	if err != nil {
		panic(err)
	}

	// Create a verifier key
	pubKey, err := ed25519.ToPublicKey(privKey)
	if err != nil {
		panic(err)
	}
	verifier, err := pubKey.Verifier()
	if err != nil {
		panic(err)
	}

	// create a claims set
	claims := cwt.Claims{
		Issuer:     "ldc:ca",
		Subject:    "ldc:chain",
		Audience:   "ldc:txpool",
		Expiration: 1670123579,
		CWTID:      []byte{1, 2, 3, 4},
	}

	// sign with Sign1Message
	obj := cose.Sign1Message[cwt.Claims]{Payload: claims}
	cwtData, err := obj.SignAndEncode(signer, nil)
	if err != nil {
		panic(err)
	}

	// decode and verify the cwt
	obj2, err := cose.VerifySign1Message[cwt.Claims](verifier, cwtData, nil)
	if err != nil {
		panic(err)
	}

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

	err = validator.Validate(&obj2.Payload)
	fmt.Printf("Validate Claims: %v\n", err)
	// Validate Claims: cose/cwt: Validator.Validate: token has expired

	cborData, err := key.MarshalCBOR(obj2.Payload)
	// cborData, err := cbor.Marshal(myClaims)
	if err != nil {
		panic(err)
	}
	fmt.Printf("CBOR(%d bytes): %x\n", len(cborData), cborData)
	// CBOR(44 bytes): a501666c64633a636102696c64633a636861696e036a6c64633a7478706f6f6c041a638c103b074401020304
}

Create a complex CWT with one more signers

package main

import (
	"encoding/json"
	"fmt"
	"time"

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

func main() {
	// Create a ed25519 signer key
	privKey1, err := ed25519.GenerateKey()
	if err != nil {
		panic(err)
	}
	privKey2, err := ecdsa.GenerateKey(iana.AlgorithmES256)
	if err != nil {
		panic(err)
	}
	ks := key.KeySet{privKey1, privKey2}

	// create a claims set
	claims := cwt.ClaimsMap{
		iana.CWTClaimIss:   "ldc:ca",
		iana.CWTClaimSub:   "ldc:chain",
		iana.CWTClaimAud:   "ldc:txpool",
		iana.CWTClaimExp:   1670123579,
		iana.CWTClaimScope: "read,write",
		// and more claims...
	}

	// Sign the claims
	signers, err := ks.Signers()
	if err != nil {
		panic(err)
	}
	// sign with SignMessage
	obj := cose.SignMessage[cwt.ClaimsMap]{Payload: claims}
	cwtData, err := obj.SignAndEncode(signers, nil)
	if err != nil {
		panic(err)
	}

	// decode and verify the cwt
	verifiers, err := ks.Verifiers()
	if err != nil {
		panic(err)
	}
	obj2, err := cose.VerifySignMessage[cwt.ClaimsMap](verifiers, cwtData, nil)
	if err != nil {
		panic(err)
	}

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

	err = validator.ValidateMap(obj2.Payload)
	fmt.Printf("Validate Claims: %v\n", err)
	// Validate Claims: cose/cwt: Validator.Validate: token has expired

	cborData, err := key.MarshalCBOR(obj2.Payload)
	// cborData, err := cbor.Marshal(myClaims)
	if err != nil {
		panic(err)
	}
	fmt.Printf("CBOR(%d bytes): %x\n", len(cborData), cborData)
	// CBOR(50 bytes): a501666c64633a636102696c64633a636861696e036a6c64633a7478706f6f6c041a638c103b096a726561642c7772697465
}

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