Skip to main content

CBOR Object Signing and Encryption (COSE) implementation

Project description

pycose --- CBOR Object Signing and Encryption

Python package Documentation Status

This project is a Python implementation of the IETF CBOR Encoded Message Syntax (COSE). COSE has reached RFC status and is now available at RFC 8152.

Installation

$ pip install pycose

What is COSE ?

CBOR Encoded Message Syntax (COSE) is a data format for concise representation of small messages RFC 8152. COSE is optimized for low power devices. The messages can be encrypted, MAC'ed and signed. There are 6 different types of COSE messages:

  • Encrypt0: An encrypted COSE message with a single recipient. The payload and AAD are protected by a shared CEK (Content Encryption Keys)
  • Encrypt: An encrypted COSE message can have multiple recipients. For each recipient the CEK is encrypted with a KEK (Key Encryption Key) - using AES key wrap - and added to the message.
  • MAC0: An authenticated COSE message with one recipient.
  • MAC: An authenticated COSE message that can have multiple recipients. For each recipient, the authentication key is encrypted with a KEK and added to the message.
  • Sign1: A signed COSE message with a single signature.
  • Sign: A COSE message that has been signed by multiple entities (each signature is carried in a COSE signature structure, added to the message).

A basic COSE message consists of 2 information buckets and the payload:

  • Protected header: This message field contains information that needs to be protected. This information is taken into account during the encryption, calculation of the MAC or the signature.
  • Unprotected header: The information contained in the unprotected header is not protected by the cryptographic algorithms.
  • Payload: Contains the payload of the message, protected (mac'ed, signed or encrypted) by the cryptographic algorithms.

Additionally, based on the message type, other message fields can be added:

  • MAC or signature (for MAC0 or Sign1 messages)
  • COSE recipients or COSE signatures (for MAC, Encrypt, and Sign messages)

Examples

Encoding

from binascii import unhexlify
from pycose.messages import Enc0Message
from pycose.keys import SymmetricKey

# Create a COSE Encrypt0 Message
msg = Enc0Message(
    phdr={'ALG': 'A128GCM', 'IV': unhexlify(b'01010101010101010101010101010101')},
    uhdr={'KID': b'meriadoc.brandybuck@buckland.example'},
    payload='a secret message'.encode('utf-8')
)

# Create a COSE Symmetric Key
cose_key = SymmetricKey(key=unhexlify(b'000102030405060708090a0b0c0d0e0f'))
msg.key = cose_key

# Performs encryption and CBOR serialization
msg.encode()
b'\xd0\x83U\xa2\x01\x01\x05P\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\xa1\x04X$meriadoc.brandybuck@buckland.exampleX \xc4\xaf\x85\xacJQ4\x93\x19\x93\xec\n\x18c\xa6\xe8\xc6n\xf4\xc9\xac\x161^\xe6\xfe\xcd\x9b.\x1cy\xa1'

Decoding

from binascii import unhexlify
from pycose.messages import Enc0Message
from pycose.keys import SymmetricKey

# message bytes (CBOR encoded)
msg =  b'\xd0\x83U\xa2\x01\x01\x05P\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\xa1\x04X$meriadoc.brandybuck@buckland.exampleX \xc4\xaf\x85\xacJQ4\x93\x19\x93\xec\n\x18c\xa6\xe8\xc6n\xf4\xc9\xac\x161^\xe6\xfe\xcd\x9b.\x1cy\xa1'

cose_msg = Enc0Message.decode(msg)

# Create a COSE Symmetric Key
cose_key = SymmetricKey(key=unhexlify(b'000102030405060708090a0b0c0d0e0f'))
cose_msg.key = cose_key

cose_msg.decrypt()
b'a secret message'

More examples

More examples can be found here

Testing

To run the test suite you need pytest:

$ pip install pytest

Move to the root of the repository and type:

$ pytest

Cryptography

The project depends on pyca/cryptography for all cryptographic operations, except the deterministic ECDSA algorithm. For deterministic ECDSA cose uses python-ecdsa.

Documentation

More documentation on COSE and the cose API can be found at: https://pycose.readthedocs.io

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pycose-1.1.0.tar.gz (47.2 kB view details)

Uploaded Source

Built Distribution

pycose-1.1.0-py3-none-any.whl (50.4 kB view details)

Uploaded Python 3

File details

Details for the file pycose-1.1.0.tar.gz.

File metadata

  • Download URL: pycose-1.1.0.tar.gz
  • Upload date:
  • Size: 47.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.12.1

File hashes

Hashes for pycose-1.1.0.tar.gz
Algorithm Hash digest
SHA256 702f73c7d9b865052862407e768515aca1d7c6fb3df3c90d169fecf913ae071f
MD5 6c5db7f10fdac70e07d73b0bf128ce79
BLAKE2b-256 e6ebe87abf1707fd2f01a1ab0c428dee8ee2358f0a6af82af5c211a7f15a41d4

See more details on using hashes here.

File details

Details for the file pycose-1.1.0-py3-none-any.whl.

File metadata

  • Download URL: pycose-1.1.0-py3-none-any.whl
  • Upload date:
  • Size: 50.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.12.1

File hashes

Hashes for pycose-1.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 52b524e9d314d6ec89462a7666afdb398a6e7beeede26104617d8246b8c79692
MD5 d4610ac2df59b0bd9a75505e8a93f991
BLAKE2b-256 b360c43d3d844a674cd3fcdfaac829e2c2816a070055ec0792e326f8b9354a06

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page