cose

module
v1.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 20, 2024 License: MIT

README

Keys, Algorithms, COSE and CWT in Go

CI Codecov CodeQL License Installation Go Reference

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

Index

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.

Directories

Path Synopsis
Package cose implements CBOR Object Signing and Encryption (COSE) as defined in RFC9052.
Package cose implements CBOR Object Signing and Encryption (COSE) as defined in RFC9052.
Package cwt implements CBOR Web Token (CWT) as defined in RFC8392.
Package cwt implements CBOR Web Token (CWT) as defined in RFC8392.
go module
Package iana registers COSE: https://www.iana.org/assignments/cose/cose.xhtml, CWT: https://www.iana.org/assignments/cwt/cwt.xhtml, and CBOR Tags: https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml.
Package iana registers COSE: https://www.iana.org/assignments/cose/cose.xhtml, CWT: https://www.iana.org/assignments/cwt/cwt.xhtml, and CBOR Tags: https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml.
key
Package key implements algorithms and key objects for COSE as defined in RFC9052 and RFC9053.
Package key implements algorithms and key objects for COSE as defined in RFC9052 and RFC9053.
aesccm
Package aesccm implements content encryption algorithm AES-CCM for COSE as defined in RFC9053.
Package aesccm implements content encryption algorithm AES-CCM for COSE as defined in RFC9053.
aesgcm
Package aesgcm implements content encryption algorithm AES-GCM for COSE as defined in RFC9053.
Package aesgcm implements content encryption algorithm AES-GCM for COSE as defined in RFC9053.
aesmac
Package aesmac implements message authentication code algorithm AES-CBC-MAC for COSE as defined in RFC9053.
Package aesmac implements message authentication code algorithm AES-CBC-MAC for COSE as defined in RFC9053.
chacha20poly1305
Package chacha20poly1305 implements content encryption algorithm ChaCha20/Poly1305 for COSE as defined in RFC9053.
Package chacha20poly1305 implements content encryption algorithm ChaCha20/Poly1305 for COSE as defined in RFC9053.
ecdh
Package ecdh implements key agreement algorithm ECDH for COSE as defined in RFC9053.
Package ecdh implements key agreement algorithm ECDH for COSE as defined in RFC9053.
ecdsa
Package ecdsa implements signature algorithm ECDSA for COSE as defined in RFC9053.
Package ecdsa implements signature algorithm ECDSA for COSE as defined in RFC9053.
ed25519
Package ed25519 implements signature algorithm Ed25519 for COSE as defined in RFC9053.
Package ed25519 implements signature algorithm Ed25519 for COSE as defined in RFC9053.
hkdf
Package hkdf implements key derivation function HKDF for COSE as defined in RFC9053.
Package hkdf implements key derivation function HKDF for COSE as defined in RFC9053.
hmac
Package hmac implements message authentication code algorithm HMAC for COSE as defined in RFC9053.
Package hmac implements message authentication code algorithm HMAC for COSE as defined in RFC9053.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL