go-cose

A golang library for the COSE specification

Project Status

Current Release: go-cose rc 1

The project was initially forked from the upstream mozilla-services/go-cose project, however the Veraison and Mozilla maintainers have agreed to retire the mozilla-services/go-cose project and focus on veraison/go-cose as the active project.

We thank the Mozilla maintainers and contributors for their great work that formed the base of the veraison/go-cose project.

Installation

go-cose is compatible with modern Go releases in module mode, with Go installed:

go get github.com/veraison/go-cose

will resolve and add the package to the current development module, along with its dependencies.

Alternatively the same can be achieved if you use import in a package:

import "github.com/veraison/go-cose"

and run go get without parameters.

Finally, to use the top-of-trunk version of this repo, use the following command:

go get github.com/veraison/go-cose@main

Usage

import "github.com/veraison/go-cose"

Construct a new COSE_Sign1 message, then sign it using ECDSA w/ SHA-512 and finally marshal it. For example:

// create a signer
privateKey, _ := ecdsa.GenerateKey(elliptic.P521(), rand.Reader)
signer, _ := cose.NewSigner(cose.AlgorithmES512, privateKey)

// create message header
headers := cose.Headers{
    Protected: cose.ProtectedHeader{
        cose.HeaderLabelAlgorithm: cose.AlgorithmES512,
    },
}

// sign and marshal message
sig, _ := cose.Sign1(rand.Reader, signer, headers, []byte("hello world"), nil)

Verify a raw COSE_Sign1 message. For example:

// create a verifier from a trusted private key
publicKey := privateKey.Public()
verifier, _ := cose.NewVerifier(cose.AlgorithmES512, publicKey)

// create a sign message from a raw COSE_Sign1 payload
var msg cose.Sign1Message
_ = msg.UnmarshalCBOR(raw)
_ = msg.Verify(nil, verifier)

Features

Signing and Verifying Objects

go-cose supports two different signature structures:

cose.Sign1Message implements COSE_Sign1.
cose.SignMessage implements COSE_Sign.

⚠️ The COSE_Sign API is currently EXPERIMENTAL and may be changed or removed in a later release. In addition, the amount of functional and security testing it has received so far is significantly lower than the COSE_Sign1 API.

Built-in Algorithms

go-cose has built-in supports the following algorithms:

PS{256,384,512}: RSASSA-PSS w/ SHA as defined in RFC 8230.
ES{256,384,512}: ECDSA w/ SHA as defined in RFC 8152.
Ed25519: PureEdDSA as defined in RFC 8152.

Custom Algorithms

The supported algorithms can be extended at runtime by using cose.RegisterAlgorithm.

API docs

Integer Ranges

CBOR supports integers in the range [-2⁶⁴, -1] ∪ [0, 2⁶⁴ - 1].

This does not map onto a single Go integer type.

go-cose uses int64 to encompass both positive and negative values to keep data sizes smaller and easy to use.

The main effect is that integer label values in the [-2⁶⁴, -2⁶³ - 1] and the [2⁶³, 2⁶⁴ - 1] ranges, which are nominally valid per RFC 8152, are rejected by the go-cose library.

Conformance Tests

go-cose runs the GlueCOSE test suite on every local go test execution. These are also executed on every CI job.

Fuzz Tests

go-cose implements several fuzz tests using Go's native fuzzing.

Fuzzing requires Go 1.18 or higher, and can be executed as follows:

go test -fuzz=FuzzSign1

ESultanik / go-cose