# pycose --- CBOR Object Signing and Encryption
[](https://github.com/TimothyClaeys/pycose/actions/workflows/python-package.yml)
[](https://pycose.readthedocs.io/en/latest/?badge=latest)
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
```bash
$ pip install pycose
```
## What is COSE ?
CBOR Encoded Message Syntax (COSE) is a data format for concise representation of small messages [RFC 8152](https://tools.ietf.org/html/rfc8152). 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
```python
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
```python
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](https://pycose.readthedocs.io/en/latest/examples.html)
## Testing
To run the test suite you need `pytest`:
```shell
$ pip install pytest
```
Move to the root of the repository and type:
```shell
$ pytest
```
## Cryptography
The project depends on [pyca/cryptography](https://github.com/pyca/cryptography) for all cryptographic operations, except the deterministic ECDSA algorithm. For deterministic ECDSA `cose` uses [python-ecdsa](https://github.com/warner/python-ecdsa).
## Documentation
More documentation on COSE and the `cose` API can be found at: https://pycose.readthedocs.io
Raw data
{
"_id": null,
"home_page": "https://github.com/TimothyClaeys/pycose",
"name": "pycose",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "'COSE','Internet of Things','CBOR','object security','EDHOC','OSCORE','cryptography'",
"author": "Timothy Claeys",
"author_email": "timothy.claeys@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e6/eb/e87abf1707fd2f01a1ab0c428dee8ee2358f0a6af82af5c211a7f15a41d4/pycose-1.1.0.tar.gz",
"platform": "any",
"description": "# pycose --- CBOR Object Signing and Encryption\n[](https://github.com/TimothyClaeys/pycose/actions/workflows/python-package.yml)\n[](https://pycose.readthedocs.io/en/latest/?badge=latest)\n\nThis 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.\n\n\n## Installation\n\n```bash\n$ pip install pycose\n```\n\n## What is COSE ?\nCBOR Encoded Message Syntax (COSE) is a data format for concise representation of small messages [RFC 8152](https://tools.ietf.org/html/rfc8152). COSE is optimized for low power devices. The messages can be encrypted, MAC'ed and signed. There are 6 different types of COSE messages:\n\n- **Encrypt0**: An encrypted COSE message with a single recipient. The payload and AAD are protected by a shared CEK (Content Encryption Keys)\n- **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.\n- **MAC0**: An authenticated COSE message with one recipient.\n- **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.\n- **Sign1**: A signed COSE message with a single signature.\n- **Sign**: A COSE message that has been signed by multiple entities (each signature is carried in a COSE signature structure, added to the message).\n\nA basic COSE message consists of 2 _information_ _buckets_ and the _payload_:\n\n- **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.\n- **Unprotected header**: The information contained in the unprotected header is not protected by the cryptographic algorithms.\n- **Payload**: Contains the payload of the message, protected (mac'ed, signed or encrypted) by the cryptographic algorithms.\n\nAdditionally, based on the message type, other message fields can be added:\n\n- _MAC_ or _signature_ (for **MAC0** or **Sign1** messages)\n- _COSE recipients_ or _COSE signatures_ (for **MAC**, **Encrypt**, and **Sign** messages)\n\n## Examples\n\n### Encoding\n\n```python\nfrom binascii import unhexlify\nfrom pycose.messages import Enc0Message\nfrom pycose.keys import SymmetricKey\n\n# Create a COSE Encrypt0 Message\nmsg = Enc0Message(\n phdr={'ALG': 'A128GCM', 'IV': unhexlify(b'01010101010101010101010101010101')},\n uhdr={'KID': b'meriadoc.brandybuck@buckland.example'},\n payload='a secret message'.encode('utf-8')\n)\n\n# Create a COSE Symmetric Key\ncose_key = SymmetricKey(key=unhexlify(b'000102030405060708090a0b0c0d0e0f'))\nmsg.key = cose_key\n\n# Performs encryption and CBOR serialization\nmsg.encode()\nb'\\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'\n```\n\n### Decoding\n```python\nfrom binascii import unhexlify\nfrom pycose.messages import Enc0Message\nfrom pycose.keys import SymmetricKey\n\n# message bytes (CBOR encoded)\nmsg = 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'\n\ncose_msg = Enc0Message.decode(msg)\n\n# Create a COSE Symmetric Key\ncose_key = SymmetricKey(key=unhexlify(b'000102030405060708090a0b0c0d0e0f'))\ncose_msg.key = cose_key\n\ncose_msg.decrypt()\nb'a secret message'\n```\n\n### More examples\nMore examples can be found [here](https://pycose.readthedocs.io/en/latest/examples.html)\n\n## Testing\n\nTo run the test suite you need `pytest`:\n```shell\n$ pip install pytest\n```\nMove to the root of the repository and type:\n\n```shell\n$ pytest\n```\n\n## Cryptography\n\nThe project depends on [pyca/cryptography](https://github.com/pyca/cryptography) for all cryptographic operations, except the deterministic ECDSA algorithm. For deterministic ECDSA `cose` uses [python-ecdsa](https://github.com/warner/python-ecdsa). \n\n## Documentation\n\nMore documentation on COSE and the `cose` API can be found at: https://pycose.readthedocs.io\n\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License",
"summary": "CBOR Object Signing and Encryption (COSE) implementation",
"version": "1.1.0",
"project_urls": {
"Documentation": "https://pycose.readthedocs.io/en/latest/",
"Download": "https://pypi.org/project/pycose/",
"Homepage": "https://github.com/TimothyClaeys/pycose",
"Source": "https://github.com/TimothyClaeys/pycose"
},
"split_keywords": [
"'cose'",
"'internet of things'",
"'cbor'",
"'object security'",
"'edhoc'",
"'oscore'",
"'cryptography'"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b360c43d3d844a674cd3fcdfaac829e2c2816a070055ec0792e326f8b9354a06",
"md5": "d4610ac2df59b0bd9a75505e8a93f991",
"sha256": "52b524e9d314d6ec89462a7666afdb398a6e7beeede26104617d8246b8c79692"
},
"downloads": -1,
"filename": "pycose-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d4610ac2df59b0bd9a75505e8a93f991",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 50427,
"upload_time": "2023-12-15T18:09:41",
"upload_time_iso_8601": "2023-12-15T18:09:41.870185Z",
"url": "https://files.pythonhosted.org/packages/b3/60/c43d3d844a674cd3fcdfaac829e2c2816a070055ec0792e326f8b9354a06/pycose-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e6ebe87abf1707fd2f01a1ab0c428dee8ee2358f0a6af82af5c211a7f15a41d4",
"md5": "6c5db7f10fdac70e07d73b0bf128ce79",
"sha256": "702f73c7d9b865052862407e768515aca1d7c6fb3df3c90d169fecf913ae071f"
},
"downloads": -1,
"filename": "pycose-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "6c5db7f10fdac70e07d73b0bf128ce79",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 47186,
"upload_time": "2023-12-15T18:09:43",
"upload_time_iso_8601": "2023-12-15T18:09:43.705163Z",
"url": "https://files.pythonhosted.org/packages/e6/eb/e87abf1707fd2f01a1ab0c428dee8ee2358f0a6af82af5c211a7f15a41d4/pycose-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-15 18:09:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "TimothyClaeys",
"github_project": "pycose",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "cryptography",
"specs": []
},
{
"name": "cbor2",
"specs": []
},
{
"name": "ecdsa",
"specs": []
},
{
"name": "attrs",
"specs": []
},
{
"name": "certvalidator",
"specs": []
}
],
"tox": true,
"lcname": "pycose"
}
JSON
