cose

README

go-cose

A COSE library for Go.

Supported COSE messages

• COSE Single Signer Data Object cose-sign1
• COSE Signed Data Object cose-sign

Supported COSE algorithms

• Signing and verification:
  • PS256 - RSASSA-PSS w/ SHA-256
  • PS384 - RSASSA-PSS w/ SHA-384
  • PS384 - RSASSA-PSS w/ SHA-512
  • ES256 - ECDSA w/ SHA-256
  • ES384 - ECDSA w/ SHA-384
  • ES512 - ECDSA w/ SHA-512
  • EdDSA - Ed25519

Thanks to Mozilla for creating mozilla-services/go-cose library for some inspiration.

Documentation

Index

• Constants
• Variables
• type Algorithm
• type Config
• type Encoding
  • func NewEncoding() (*Encoding, error)
  • func (e *Encoding) Decode(data []byte, config *Config) (Message, error)
  • func (e *Encoding) DecodeWithExternal(data, external []byte, config *Config) (Message, error)
  • func (e *Encoding) Encode(message Message) ([]byte, error)
  • func (e *Encoding) EncodeWithExternal(message Message, external []byte) ([]byte, error)
• type ErrMinKeySize
  • func (e ErrMinKeySize) Error() string
• type ErrUnsupportedMessageTag
  • func (e ErrUnsupportedMessageTag) Error() string
• type Headers
  • func MergeHeaders(h1, h2 *Headers) *Headers
  • func NewHeaders() *Headers
  • func (h *Headers) Delete(key interface{})
  • func (h *Headers) Get(key interface{}) (interface{}, error)
  • func (h *Headers) GetProtected(key interface{}) (interface{}, error)
  • func (h *Headers) Merge(other *Headers)
  • func (h *Headers) Set(key, value interface{}) error
  • func (h *Headers) SetProtected(key, value interface{}) error
• type Message
• type Sign1Message
  • func NewSign1Message() *Sign1Message
  • func (m *Sign1Message) GetContent() []byte
  • func (m *Sign1Message) GetMessageTag() uint64
  • func (m *Sign1Message) SetContent(content []byte)
  • func (m *Sign1Message) SetSigner(signer *Signer)
• type SignMessage
  • func NewSignMessage() *SignMessage
  • func (m *SignMessage) AddSigner(signer *Signer)
  • func (m *SignMessage) GetContent() []byte
  • func (m *SignMessage) GetMessageTag() uint64
  • func (m *SignMessage) SetContent(content []byte)
• type Signer
  • func NewSigner(alg Algorithm, key crypto.PrivateKey) (*Signer, error)
  • func (s *Signer) GetHash() crypto.Hash
  • func (s *Signer) GetHeaders() (*Headers, error)
  • func (s *Signer) GetPrivateKey() crypto.PrivateKey
  • func (s *Signer) Sign(rand io.Reader, digest []byte) ([]byte, error)
  • func (s *Signer) ToVerifier() (*Verifier, error)
• type Verifier
  • func NewVerifier(alg Algorithm, key crypto.PublicKey) (*Verifier, error)
  • func (v *Verifier) GetHash() crypto.Hash
  • func (v *Verifier) GetPublicKey() crypto.PublicKey
  • func (v *Verifier) Verify(digest, sig []byte) error

Constants

const (
	// MessageTagUnknown is the tag for unknown messages
	MessageTagUnkown = 0
	// MessageTagEncrypt0 is the tag for encrypt messages without specifid recipients
	MessageTagEncrypt0 = 16
	// MessageTagEncrypt is the tag for encrypt messages with specifid recipients
	MessageTagEncrypt = 96
	// MessageTagSign1 is the tag for signed messages with single signer
	MessageTagSign1 = 18
	// MessageTagSign is the tag for signed messages with multiple signers
	MessageTagSign = 98
	// MessageTagMAC is the tag for MAC messages with specified recipients
	MessageTagMAC = 97
	// MessageTagMAC0 is the tag for MAC messages where recipients are not specified
	MessageTagMAC0 = 17
)

const (
	HeaderAlgorithm        = "alg"
	HeaderCritical         = "crit"
	HeaderContentType      = "content type"
	HeaderKeyID            = "kid"
	HeaderIV               = "IV"
	HeaderPartialIV        = "Partial IV"
	HeaderCounterSignature = "counter signature"
)

Variables

var (
	// ErrUnsupportedKeyType represents an error when a key type is not supported.
	ErrUnsupportedKeyType = errors.New("unsupported key type")
	// ErrUnavailableHashAlgorithm represents an error when a hash algorithm is not available.
	ErrUnavailableHashAlgorithm = errors.New("hash algorithm unavailable")
	// ErrUnsupportedAlgorithm represents an error when an algorithm is not supported.
	ErrUnsupportedAlgorithm = errors.New("unsupported algorithm")
	// ErrAlgorithmNotMatchKey represents an error when an algorithm does not match the key type.
	ErrAlgorithmNotMatchKey = errors.New("algorithm does not match key type")
	// ErrInvalidEllipticCurve represents an error when an elliptic curve size does not match the key.
	ErrInvalidEllipticCurve = errors.New("invalid elliptic curve")
	// ErrVerification represents a failure to verify a signature.
	ErrVerification = errors.New("verification error")
)

var (
	// StdEncoging is the COSE standard encoding
	StdEncoding, _ = NewEncoding()
)

Types

type Algorithm

type Algorithm string

Algorithm name

const (
	// AlgorithmPS256 for signing with RSASSA-PSS w/ SHA-256
	AlgorithmPS256 Algorithm = "PS256"
	// AlgorithmPS384 for signing with RSASSA-PSS w/ SHA-384
	AlgorithmPS384 Algorithm = "PS384"
	// AlgorithmPS512 for signing with RSASSA-PSS w/ SHA-512
	AlgorithmPS512 Algorithm = "PS512"
	// AlgorithmES512 for signing with ECDSA w/ SHA-512
	AlgorithmES512 Algorithm = "ES512"
	// AlgorithmES384 for signing with ECDSA w/ SHA-384
	AlgorithmES384 Algorithm = "ES384"
	// AlgorithmES256 for signing with ECDSA w/ SHA-256
	AlgorithmES256 Algorithm = "ES256"
	// AlgorithmEdDSA for signing with EdDSA/Ed25519
	AlgorithmEdDSA Algorithm = "EdDSA"
)

type Config

type Config struct {
	// GetVerifiers returns the verifiers for the given message signature
	GetVerifiers func(*Headers) ([]*Verifier, error)
	// Verified callback
	Verified func(*Verifier)
}

Config is the configuration for the COSE encoding

type Encoding

type Encoding struct {
	// contains filtered or unexported fields
}

Encoding is the COSE encoding

func NewEncoding

func NewEncoding() (*Encoding, error)

NewEncoding creates a new COSE encoding

func (*Encoding) Decode

func (e *Encoding) Decode(data []byte, config *Config) (Message, error)

Decode decodes the given data

func (*Encoding) DecodeWithExternal

func (e *Encoding) DecodeWithExternal(data, external []byte, config *Config) (Message, error)

DecodeWithExternal decodes the given data with the given external data

func (*Encoding) Encode

func (e *Encoding) Encode(message Message) ([]byte, error)

Encode encodes the given message

func (*Encoding) EncodeWithExternal

func (e *Encoding) EncodeWithExternal(message Message, external []byte) ([]byte, error)

EncodeWithExternal encodes the given message with the given external data

type ErrMinKeySize

type ErrMinKeySize struct {
	Size int
}

ErrMinKeySize represents an error when a key is too small.

func (ErrMinKeySize) Error

func (e ErrMinKeySize) Error() string

type ErrUnsupportedMessageTag

type ErrUnsupportedMessageTag struct {
	Tag uint64
}

ErrUnsupportedMessageTag represents an error when a message tag is not supported.

func (ErrUnsupportedMessageTag) Error

func (e ErrUnsupportedMessageTag) Error() string

type Headers

type Headers struct {
	// contains filtered or unexported fields
}

Headers represents COSE protected and unprotected headers.

func MergeHeaders

func MergeHeaders(h1, h2 *Headers) *Headers

MergeHeaders merges the given headers into the new Headers instance.

func NewHeaders

func NewHeaders() *Headers

NewHeaders creates a new Headers instance.

func (*Headers) Delete

func (h *Headers) Delete(key interface{})

Delete removes the header with the given key from protected and unprotected headers.

func (*Headers) Get

func (h *Headers) Get(key interface{}) (interface{}, error)

Get returns the header with the given key from both protected and unprotected headers, prioritizing protected headers.

func (*Headers) GetProtected

func (h *Headers) GetProtected(key interface{}) (interface{}, error)

GetProtected returns the header with the given key from protected headers.

func (*Headers) Merge

func (h *Headers) Merge(other *Headers)

Merge merges the given headers into the current headers.

func (*Headers) Set

func (h *Headers) Set(key, value interface{}) error

Set sets the header with the given key in unprotected headers. `alg` and `crit` will always be set in protected headers.

func (*Headers) SetProtected

func (h *Headers) SetProtected(key, value interface{}) error

SetProtected sets the header with the given key in protected headers.

type Message

type Message interface {
	// GetMessageTag returns the COSE message tag.
	GetMessageTag() uint64
	// GetContent returns the message content.
	GetContent() []byte
	// SetContent sets the message content.
	SetContent([]byte)
}

Message represents a COSE message.

type Sign1Message

type Sign1Message struct {
	Headers *Headers
	// contains filtered or unexported fields
}

Sign1Message represents a COSE_Sign1 message.

func NewSign1Message

func NewSign1Message() *Sign1Message

NewSign1Message creates a new Sign1Message instance.

func (*Sign1Message) GetContent

func (m *Sign1Message) GetContent() []byte

GetContent returns the message content.

func (*Sign1Message) GetMessageTag

func (m *Sign1Message) GetMessageTag() uint64

GetMessageTag returns the COSE_Sign1 message tag.

func (*Sign1Message) SetContent

func (m *Sign1Message) SetContent(content []byte)

SetContent sets the message content.

func (*Sign1Message) SetSigner

func (m *Sign1Message) SetSigner(signer *Signer)

SetSigner sets the signer.

type SignMessage

type SignMessage struct {
	Headers *Headers
	// contains filtered or unexported fields
}

SignMessage represents a COSE_Sign message.

func NewSignMessage

func NewSignMessage() *SignMessage

NewSignMessage creates a new SignMessage instance.

func (*SignMessage) AddSigner

func (m *SignMessage) AddSigner(signer *Signer)

AddSigner adds a signer for the message.

func (*SignMessage) GetContent

func (m *SignMessage) GetContent() []byte

GetContent returns the message content.

func (*SignMessage) GetMessageTag

func (m *SignMessage) GetMessageTag() uint64

GetMessageTag returns the COSE_Sign message tag.

func (*SignMessage) SetContent

func (m *SignMessage) SetContent(content []byte)

SetContent sets the message content.

type Signer

type Signer struct {
	Headers *Headers
	// contains filtered or unexported fields
}

Signer represents a signer with a private key and algorithm.

func NewSigner

func NewSigner(alg Algorithm, key crypto.PrivateKey) (*Signer, error)

NewSigner creates a new signer with a private key and algorithm.

func (*Signer) GetHash

func (s *Signer) GetHash() crypto.Hash

GetHash returns the hash algorithm of the signer.

func (*Signer) GetHeaders

func (s *Signer) GetHeaders() (*Headers, error)

GetHeader returns the headers for message signature.

func (*Signer) GetPrivateKey

func (s *Signer) GetPrivateKey() crypto.PrivateKey

GetPrivateKey returns the private key used by the signer.

func (*Signer) Sign

func (s *Signer) Sign(rand io.Reader, digest []byte) ([]byte, error)

Sign signs the message with the private key using the algorithm.

func (*Signer) ToVerifier

func (s *Signer) ToVerifier() (*Verifier, error)

ToVerifier returns the public key verifier for the signer.

type Verifier

type Verifier struct {
	// contains filtered or unexported fields
}

Verifier is a public key container for verifying COSE signatures.

func NewVerifier

func NewVerifier(alg Algorithm, key crypto.PublicKey) (*Verifier, error)

NewVerifier creates a new verifier from a public key and algorithm.

func (*Verifier) GetHash

func (v *Verifier) GetHash() crypto.Hash

GetHash returns the hash algorithm used by the verifier.

func (*Verifier) GetPublicKey

func (v *Verifier) GetPublicKey() crypto.PublicKey

GetPublicKey returns the public key used by the verifier.

func (*Verifier) Verify

func (v *Verifier) Verify(digest, sig []byte) error

Verify verifies a COSE signature.