CBOR Object Signing and Encryption (COSE) implementation
Project description
pycose --- CBOR Object Signing and Encryption
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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | 702f73c7d9b865052862407e768515aca1d7c6fb3df3c90d169fecf913ae071f |
|
MD5 | 6c5db7f10fdac70e07d73b0bf128ce79 |
|
BLAKE2b-256 | e6ebe87abf1707fd2f01a1ab0c428dee8ee2358f0a6af82af5c211a7f15a41d4 |
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | 52b524e9d314d6ec89462a7666afdb398a6e7beeede26104617d8246b8c79692 |
|
MD5 | d4610ac2df59b0bd9a75505e8a93f991 |
|
BLAKE2b-256 | b360c43d3d844a674cd3fcdfaac829e2c2816a070055ec0792e326f8b9354a06 |