A golang library for the CBOR Object Signing and Encryption (COSE) and CBOR Web Token (CWT).
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.
- 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.
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"
)
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 |
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
}
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
}
Todo.
- RFC9052: CBOR Object Signing and Encryption (COSE)
- RFC8392: CBOR Web Token (CWT)
- RFC9053: CBOR Object Signing and Encryption (COSE): Initial Algorithms
- IANA: CBOR Object Signing and Encryption (COSE)
- IANA: CBOR Web Token (CWT) Claims
- IANA: Concise Binary Object Representation (CBOR) Tags
Copyright Β© 2022-2024 LDC Labs.
ldclabs/cose is licensed under the MIT License. See LICENSE for the full license text.