Symmetric Key

Overview

To encode/encrypt/authenticate or decode/decrypt/verify the payload of COSE messages Enc0Message , Mac0Message, EncMessage, and Mac0Message the COSE message object requires a COSE key of type SymmetricKey.

COSE Symmetric keys can be created using the SymmetricKey class or from a standard Python dictionary. The following two examples shows how to create COSE Symmetric keys using both methods. The keys are serialized and subsequently deserialized.

>>> from binascii import unhexlify
>>> from pycose.keys import SymmetricKey, CoseKey

>>> cose_key = SymmetricKey(k=unhexlify(b'000102030405060708090a0b0c0d0e0f'), optional_params={'ALG': 'A128GCM'})

>>> #encode/serialize key
>>> serialized_key = cose_key.encode()
>>> serialized_key
b'\xa3\x01\x04\x03\x01 P\x00\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f'

>>> # deserialize key
>>> CoseKey.decode(serialized_key)
<COSE_Key(Symmetric): {'SymKpK': "b'\\x00\\x01\\x02\\x03\\x04' ... (16 B)", 'KpKty': 'KtySymmetric', 'KpAlg': 'A128GCM'}>

>>> from binascii import unhexlify
>>> from pycose.keys import SymmetricKey, CoseKey

>>> # create key object from a dict, both the key type and key bytes (KTY and K) are mandatory attributes.
>>> key_attribute_dict = {
...     'KTY': 'SYMMETRIC',
...     'ALG': 'A128GCM',
...     'K': unhexlify(b'000102030405060708090a0b0c0d0e0f')}

>>> cose_key = CoseKey.from_dict(key_attribute_dict)

>>> #encode/serialize key
>>> serialized_key = cose_key.encode()
>>> serialized_key
b'\xa3\x01\x04\x03\x01 P\x00\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f'

>>> # deserialize key
>>> CoseKey.decode(serialized_key)
<COSE_Key(Symmetric): {'SymKpK': "b'\\x00\\x01\\x02\\x03\\x04' ... (16 B)", 'KpKty': 'KtySymmetric', 'KpAlg': 'A128GCM'}>

Alternatively you can use the generate_key() method. It generates a random COSE Symmetric Key with a given key length. Valid key lengths are 16, 24 and 32.

>>> from pycose.keys import SymmetricKey

>>> # generate a random key
>>> cose_key = SymmetricKey.generate_key(key_len=16)

When creating a COSE Symmetric Key from a dictionary, you have to make sure that the dictionary holds the KpKty and SymKpK key attributes. These attributes are mandatory for a valid COSE Symmetric Key. If you don’t specify them, the from_dict() will throw an exception.

>>> from pycose.keys import SymmetricKey, CoseKey

>>> key_attribute_dict = {
...     'ALG': 'A128GCM',
...     'K': unhexlify(b'000102030405060708090a0b0c0d0e0f')}

>>> cose_key = CoseKey.from_dict(key_attribute_dict)
Traceback (most recent call last):
  File "/usr/lib/python3.6/doctest.py", line 1330, in __run
    compileflags, 1), test.globs)
  File "<doctest default[2]>", line 1, in <module>
    cose_key = CoseKey.from_dict(key_attribute_dict)
  File "/home/timothy/Projects/pycose/pycose/keys/cosekey.py", line 69, in from_dict
    raise CoseIllegalKeyType("Could not decode CoseKey type, KpKty not set or unknown.")
pycose.exceptions.CoseIllegalKeyType: Could not decode CoseKey type, KpKty not set or unknown.

The key attributes of the COSE Symmetric Key can be represented by their string label, the integer identifier or the corresponding python class.

>>> from binascii import unhexlify
>>> from pycose.keys import SymmetricKey, CoseKey
>>> from pycose.keys.keytype import KtySymmetric
>>> from pycose.algorithms import A128GCM
>>> from pycose.keys.keyparam import KpKty, KpAlg, SymKpK

>>> # key attribute dict using string representations
>>> key_attribute_dict1 = {
...     'KTY': 'SYMMETRIC',
...     'ALG': 'A128GCM',
...     'K': unhexlify(b'000102030405060708090a0b0c0d0e0f')}

>>> cose_key1 = CoseKey.from_dict(key_attribute_dict1)

>>> # key attribute dict using integer identifiers
>>> key_attribute_dict2 = {
...     1: 4,
...     3: 1,
...     -1: unhexlify(b'000102030405060708090a0b0c0d0e0f')}

>>> cose_key2 = CoseKey.from_dict(key_attribute_dict2)

>>> # key attribute dict using Python classes
>>> key_attribute_dict3 = {
...     KpKty: KtySymmetric,
...     KpAlg: A128GCM,
...     SymKpK: unhexlify(b'000102030405060708090a0b0c0d0e0f')}

>>> cose_key3 = CoseKey.from_dict(key_attribute_dict3)

>>> # key attribute dict using a mix of attribute representations
>>> key_attribute_dict4 = {
...     1: 'SYMMETRIC',
...     'ALG': A128GCM,
...     SymKpK: unhexlify(b'000102030405060708090a0b0c0d0e0f')}

>>> cose_key4 = CoseKey.from_dict(key_attribute_dict4)

>>> # all COSE Symmetric key objects are equal
>>> cose_key1 == cose_key2 == cose_key3 == cose_key4
True

API

class pycose.keys.symmetric.SymmetricKey(k, optional_params=None, allow_unknown_key_attrs=True)
classmethod from_dict(cose_key)

Returns an initialized COSE Key object of type SymmetricKey.

Parameters:

cose_key – Dict containing COSE Key parameters and their values.

Returns:

an initialized COSE SymmetricKey object

property k

Returns the mandatory SymKpK attribute of the COSE Symmetric Key object.

property key_ops

Returns the value of the KpKeyOps key parameter

property alg

Returns the value of the KpAlg key parameter

static base64decode(to_decode)

Decodes BASE64 encoded keys to bytes.

Parameters:

to_decode – BASE64 encoded key.

Returns:

Key as bytes.

static base64encode(to_encode)

Encodes key bytes as a string.

Parameters:

to_encode – Bytes to encode.

Returns:

BASE64 encoding.

property base_iv

Returns the value of the KpBaseIV key parameter

classmethod decode(received)

Decodes a CBOR-encoded COSE key object.

Parameters:

received – A CBOR-encoded bytestring.

Returns:

An initialized COSE key.

encode()

Encodes the COSE key as a CBOR map

Returns:

A COSE key encoded as CBOR map

static from_pem_private_key(pem, password=None, optional_params=None)

Initialize a COSE key from a PEM-encoded private key.

Parameters:

  • pem – PEM-encoded private key.

  • password – Password to decrypt the key.

  • optional_params – Optional parameters to add to the key.

Returns:

an initialized CoseKey object.

static from_pem_public_key(pem, optional_params=None)

Initialize a COSE key from a PEM-encoded public key.

Parameters:

  • pem – PEM-encoded public key.

  • optional_params – Optional parameters to add to the key.

Returns:

an initialized CoseKey object.

classmethod generate_key(key_len, optional_params=None)

Generate a random Symmetric COSE key object.

Parameters:

  • key_len – Symmetric key length in bytes, must be of size 16, 24 or 32.

  • optional_params – Optional key attributes for the SymmetricKey object, e.g., KpAlg or KpKid.

Raises:

ValueError – For invalid key lengths.

Returns:

A COSE_key of type SymmetricKey.

property kid

Returns the value of the KpKid key parameter

property kty

Returns the value of the mandatory KpKty key parameter