API Reference¶

A Python implementation of CWT/COSE <https://python-cwt.readthedocs.io>

cwt.encode(claims: Union[cwt.claims.Claims, Dict[str, Any], Dict[int, Any], bytes, str], key: cwt.cose_key_interface.COSEKeyInterface, nonce: bytes = b'', recipients: Optional[List[cwt.recipient_interface.RecipientInterface]] = None, tagged: bool = False) → bytes¶

Encodes CWT with MAC, signing or encryption. This is a wrapper function of the following functions for easy use:

encode_and_mac
encode_and_sign
encode_and_encrypt

Therefore, it must be clear whether the use of the specified key is for MAC, signing, or encryption. For this purpose, the key must have the key_ops parameter set to identify the usage.

Parameters

claims (Union[Claims, Dict[str, Any], Dict[int, Any], bytes, str]) – A CWT claims object, or a JWT claims object, text string or byte string.
key (COSEKeyInterface) – A COSE key used to generate a MAC for the claims.
recipients (List[RecipientInterface]) – A list of recipient information structures.
tagged (bool) – An indicator whether the response is wrapped by CWT tag(61) or not.

Returns

A byte string of the encoded CWT.

Return type

bytes

Raises

ValueError – Invalid arguments.
EncodeError – Failed to encode the claims.

cwt.encode_and_mac(claims: Union[cwt.claims.Claims, Dict[int, Any], bytes], key: cwt.cose_key_interface.COSEKeyInterface, recipients: Optional[List[cwt.recipient_interface.RecipientInterface]] = None, tagged: bool = False) → bytes¶

Encodes with MAC.

Parameters

claims (Union[Claims, Dict[int, Any], bytes]) – A CWT claims object or byte string.
key (COSEKeyInterface) – A COSE key used to generate a MAC for the claims.
recipients (List[RecipientInterface]) – A list of recipient information structures.
tagged (bool) – An indicator whether the response is wrapped by CWT tag(61) or not.

Returns

A byte string of the encoded CWT.

Return type

bytes

Raises

ValueError – Invalid arguments.
EncodeError – Failed to encode the claims.

cwt.encode_and_sign(claims: Union[cwt.claims.Claims, Dict[int, Any], bytes], key: Union[cwt.cose_key_interface.COSEKeyInterface, List[cwt.cose_key_interface.COSEKeyInterface]], tagged: bool = False) → bytes¶

Encodes CWT with signing.

Parameters

claims (Claims, Union[Dict[int, Any], bytes]) – A CWT claims object or byte string.
key (Union[COSEKeyInterface, List[COSEKeyInterface]]) – A COSE key or a list of the keys used to sign claims.
tagged (bool) – An indicator whether the response is wrapped by CWT tag(61) or not.

Returns

A byte string of the encoded CWT.

Return type

bytes

Raises

ValueError – Invalid arguments.
EncodeError – Failed to encode the claims.

cwt.encode_and_encrypt(claims: Union[cwt.claims.Claims, Dict[int, Any], bytes], key: cwt.cose_key_interface.COSEKeyInterface, nonce: bytes = b'', recipients: Optional[List[cwt.recipient_interface.RecipientInterface]] = None, tagged: bool = False) → bytes¶

Encodes CWT with encryption.

Parameters

claims (Claims, Union[Dict[int, Any], bytes]) – A CWT claims object or byte string.
key (COSEKeyInterface) – A COSE key used to encrypt the claims.
nonce (bytes) – A nonce for encryption.
recipients (List[RecipientInterface]) – A list of recipient information structures.
tagged (bool) – An indicator whether the response is wrapped by CWT tag(61) or not.

Returns

A byte string of the encoded CWT.

Return type

bytes

Raises

ValueError – Invalid arguments.
EncodeError – Failed to encode the claims.

cwt.decode(data: bytes, key: Union[cwt.cose_key_interface.COSEKeyInterface, List[cwt.cose_key_interface.COSEKeyInterface]], no_verify: bool = False) → Union[Dict[int, Any], bytes]¶

Verifies and decodes CWT.

Parameters

data (bytes) – A byte string of an encoded CWT.
key (Union[COSEKeyInterface, List[COSEKeyInterface]]) – A COSE key or a list of the keys used to verify and decrypt the encoded CWT.
no_verify (bool) – An indicator whether token verification is skiped or not.

Returns

A byte string of the decoded CWT.

Return type

Union[Dict[int, Any], bytes]

Raises

ValueError – Invalid arguments.
DecodeError – Failed to decode the CWT.
VerifyError – Failed to verify the CWT.

cwt.set_private_claim_names(claim_names: Dict[str, int])¶

Sets private claim definitions. The definitions will be used in encode when it is called with JSON-based claims.

Parameters: claim_names (Dict[str, int]) – A set of private claim definitions which consist of a readable claim name(str) and a claim key(int). The claim key should be less than -65536 but you can use the numbers other than pre-registered numbers listed in IANA Registry.
Raises: ValueError – Invalid arguments.

class cwt.CWT(options: Optional[Dict[str, Any]] = None)[source]¶

Bases: cwt.cbor_processor.CBORProcessor

A CWT (CBOR Web Token) Implementaion, which is built on top of COSE

cwt.cwt is a global object of this class initialized with default settings.

CBOR_TAG = 61¶

__init__(options: Optional[Dict[str, Any]] = None)[source]¶

Constructor.

Parameters: options (Optional[Dict[str, Any]]) – Options for the initial configuration of CWT. At this time, expires_in (default value: 3600 ) and leaway (default value: 60) are only supported. See also expires_in, leeway.

Examples

>>> from cwt import CWT, COSEKey
>>> ctx = CWT({"expires_in": 3600*24, "leeway": 10})
>>> key = COSEKey.from_symmetric_key(alg="HS255")
>>> token = ctx.encode(
...     {"iss": "coaps://as.example", "sub": "dajiaji", "cti": "123"},
...     key,
... )

property expires_in: int¶: The default lifetime in seconds of CWT. If exp is not found in claims, this value will be used with current time.

property leeway: int¶: The default leeway in seconds for validating exp and nbf.

encode(claims: Union[cwt.claims.Claims, Dict[str, Any], Dict[int, Any], bytes, str], key: cwt.cose_key_interface.COSEKeyInterface, nonce: bytes = b'', recipients: Optional[List[cwt.recipient_interface.RecipientInterface]] = None, tagged: bool = False) → bytes[source]¶

Encodes CWT with MAC, signing or encryption. This is a wrapper function of the following functions for easy use:

encode_and_mac
encode_and_sign
encode_and_encrypt

Therefore, it must be clear whether the use of the specified key is for MAC, signing, or encryption. For this purpose, the key must have the key_ops parameter set to identify the usage.

Parameters

claims (Union[Claims, Dict[str, Any], Dict[int, Any], bytes, str]) – A CWT claims object, or a JWT claims object, text string or byte string.
key (COSEKeyInterface) – A COSE key used to generate a MAC for the claims.
recipients (List[RecipientInterface]) – A list of recipient information structures.
tagged (bool) – An indicator whether the response is wrapped by CWT tag(61) or not.

Returns

A byte string of the encoded CWT.

Return type

bytes

Raises

ValueError – Invalid arguments.
EncodeError – Failed to encode the claims.

encode_and_mac(claims: Union[cwt.claims.Claims, Dict[int, Any], bytes], key: cwt.cose_key_interface.COSEKeyInterface, recipients: Optional[List[cwt.recipient_interface.RecipientInterface]] = None, tagged: bool = False) → bytes[source]¶

Encodes with MAC.

Parameters

claims (Union[Claims, Dict[int, Any], bytes]) – A CWT claims object or byte string.
key (COSEKeyInterface) – A COSE key used to generate a MAC for the claims.
recipients (List[RecipientInterface]) – A list of recipient information structures.
tagged (bool) – An indicator whether the response is wrapped by CWT tag(61) or not.

Returns

A byte string of the encoded CWT.

Return type

bytes

Raises

ValueError – Invalid arguments.
EncodeError – Failed to encode the claims.

encode_and_sign(claims: Union[cwt.claims.Claims, Dict[int, Any], bytes], key: Union[cwt.cose_key_interface.COSEKeyInterface, List[cwt.cose_key_interface.COSEKeyInterface]], tagged: bool = False) → bytes[source]¶

Encodes CWT with signing.

Parameters

claims (Claims, Union[Dict[int, Any], bytes]) – A CWT claims object or byte string.
key (Union[COSEKeyInterface, List[COSEKeyInterface]]) – A COSE key or a list of the keys used to sign claims.
tagged (bool) – An indicator whether the response is wrapped by CWT tag(61) or not.

Returns

A byte string of the encoded CWT.

Return type

bytes

Raises

ValueError – Invalid arguments.
EncodeError – Failed to encode the claims.

encode_and_encrypt(claims: Union[cwt.claims.Claims, Dict[int, Any], bytes], key: cwt.cose_key_interface.COSEKeyInterface, nonce: bytes = b'', recipients: Optional[List[cwt.recipient_interface.RecipientInterface]] = None, tagged: bool = False) → bytes[source]¶

Encodes CWT with encryption.

Parameters

claims (Claims, Union[Dict[int, Any], bytes]) – A CWT claims object or byte string.
key (COSEKeyInterface) – A COSE key used to encrypt the claims.
nonce (bytes) – A nonce for encryption.
recipients (List[RecipientInterface]) – A list of recipient information structures.
tagged (bool) – An indicator whether the response is wrapped by CWT tag(61) or not.

Returns

A byte string of the encoded CWT.

Return type

bytes

Raises

ValueError – Invalid arguments.
EncodeError – Failed to encode the claims.

decode(data: bytes, key: Union[cwt.cose_key_interface.COSEKeyInterface, List[cwt.cose_key_interface.COSEKeyInterface]], no_verify: bool = False) → Union[Dict[int, Any], bytes][source]¶

Verifies and decodes CWT.

Parameters

data (bytes) – A byte string of an encoded CWT.
key (Union[COSEKeyInterface, List[COSEKeyInterface]]) – A COSE key or a list of the keys used to verify and decrypt the encoded CWT.
no_verify (bool) – An indicator whether token verification is skiped or not.

Returns

A byte string of the decoded CWT.

Return type

Union[Dict[int, Any], bytes]

Raises

ValueError – Invalid arguments.
DecodeError – Failed to decode the CWT.
VerifyError – Failed to verify the CWT.

set_private_claim_names(claim_names: Dict[str, int])[source]¶

Sets private claim definitions. The definitions will be used in encode when it is called with JSON-based claims.

Parameters

claim_names (Dict[str, int]) –

A set of private claim definitions which consist of a readable claim name(str) and a claim key(int). The claim key should be less than -65536 but you can use the numbers other than pre-registered numbers listed in IANA Registry.

Raises

ValueError – Invalid arguments.

class cwt.COSE(alg_auto_inclusion: int = False, kid_auto_inclusion: int = False)[source]¶

Bases: cwt.cbor_processor.CBORProcessor

A COSE (CBOR Object Signing and Encryption) Implementaion built on top of cbor2.

__init__(alg_auto_inclusion: int = False, kid_auto_inclusion: int = False)[source]¶

Constructor.

Parameters

alg_auto_inclusion (bool) – The indicator whether alg parameter is included in a proper header bucket automatically or not.
kid_auto_inclusion (bool) – The indicator whether kid parameter is included in a proper header bucket automatically or not.

encode_and_mac(payload: bytes, key: cwt.cose_key_interface.COSEKeyInterface, protected: Optional[Union[dict, bytes]] = None, unprotected: Optional[dict] = None, recipients: Optional[List[cwt.recipient_interface.RecipientInterface]] = None, external_aad: bytes = b'', out: str = '') → Union[bytes, _cbor2.CBORTag][source]¶

Encodes data with MAC.

Parameters

payload (bytes) – A content to be MACed.
key (COSEKeyInterface) – A COSE key as a MAC Authentication key.
protected (Optional[Union[dict, bytes]]) – Parameters that are to be cryptographically protected.
unprotected (Optional[dict]) – Parameters that are not cryptographically protected.
recipients (Optional[List[RecipientInterface]]) – A list of recipient information structures.
external_aad (bytes) – External additional authenticated data supplied by application.
out (str) –
An output format. Only "cbor2/CBORTag" can be used. If "cbor2/CBORTag" is specified. This function will return encoded data as cbor2’s CBORTag object. If any other value is specified, it will return encoded data as bytes.

Returns

A byte string of the encoded COSE or a cbor2.CBORTag object.

Return type

Union[bytes, CBORTag]

Raises

ValueError – Invalid arguments.
EncodeError – Failed to encode data.

encode_and_sign(payload: bytes, key: Union[cwt.cose_key_interface.COSEKeyInterface, List[cwt.cose_key_interface.COSEKeyInterface]], protected: Optional[Union[dict, bytes]] = None, unprotected: Optional[dict] = None, external_aad: bytes = b'', out: str = '') → Union[bytes, _cbor2.CBORTag][source]¶

Encodes data with signing.

Parameters

payload (bytes) – A content to be signed.
key (Union[COSEKeyInterface, List[COSEKeyInterface]]) – One or more COSE keys as signing keys.
protected (Optional[Union[dict, bytes]]) – Parameters that are to be cryptographically protected.
unprotected (Optional[dict]) – Parameters that are not cryptographically protected.
external_aad (bytes) – External additional authenticated data supplied by application.
out (str) –
An output format. Only "cbor2/CBORTag" can be used. If "cbor2/CBORTag" is specified. This function will return encoded data as cbor2’s CBORTag object. If any other value is specified, it will return encoded data as bytes.

Returns

A byte string of the encoded COSE or a cbor2.CBORTag object.

Return type

Union[bytes, CBORTag]

Raises

ValueError – Invalid arguments.
EncodeError – Failed to encode data.

encode_and_encrypt(payload: bytes, key: cwt.cose_key_interface.COSEKeyInterface, protected: Optional[Union[dict, bytes]] = None, unprotected: Optional[dict] = None, nonce: bytes = b'', recipients: Optional[List[cwt.recipient_interface.RecipientInterface]] = None, external_aad: bytes = b'', out: str = '') → bytes[source]¶

Encodes data with encryption.

Parameters

payload (bytes) – A content to be encrypted.
key (COSEKeyInterface) – A COSE key as an encryption key.
protected (Optional[Union[dict, bytes]]) – Parameters that are to be cryptographically protected.
unprotected (Optional[dict]) – Parameters that are not cryptographically protected.
nonce (bytes) – A nonce for encryption.
recipients (Optional[List[RecipientInterface]]) – A list of recipient information structures.
external_aad (bytes) – External additional authenticated data supplied by application.
out (str) –
An output format. Only "cbor2/CBORTag" can be used. If "cbor2/CBORTag" is specified. This function will return encoded data as cbor2’s CBORTag object. If any other value is specified, it will return encoded data as bytes.

Returns

A byte string of the encoded COSE or a cbor2.CBORTag object.

Return type

Union[bytes, CBORTag]

Raises

ValueError – Invalid arguments.
EncodeError – Failed to encode data.

decode(data: Union[bytes, _cbor2.CBORTag], key: Optional[Union[cwt.cose_key_interface.COSEKeyInterface, List[cwt.cose_key_interface.COSEKeyInterface]]] = None, materials: Optional[List[dict]] = None, external_aad: bytes = b'') → bytes[source]¶

Verifies and decodes COSE data.

Parameters

data (Union[bytes, CBORTag]) – A byte string or cbor2.CBORTag of an encoded data.
key (Optional[Union[COSEKeyInterface, List[COSEKeyInterface]]]) – A COSE key to verify and decrypt the encoded data.
materials (Optional[List[dict]]) – A list of key materials to be used to derive an encryption key.
external_aad (bytes) – External additional authenticated data supplied by application.

Returns

A byte string of decoded payload.

Return type

bytes

Raises

ValueError – Invalid arguments.
DecodeError – Failed to decode data.
VerifyError – Failed to verify data.

class cwt.COSEKey[source]¶

Bases: object

A COSEKeyInterface Builder.

static from_dict(cose_key: Dict[int, Any]) → cwt.cose_key_interface.COSEKeyInterface [source]¶

Create a COSE key from a CBOR-like dictionary with numeric keys.

Parameters: cose_key (Dict[int, Any]) – A CBOR-like dictionary with numeric keys of a COSE key.
Returns: A COSE key object.
Return type: COSEKeyInterface
Raises: ValueError – Invalid arguments.

classmethod from_symmetric_key(key: Union[bytes, str] = b'', alg: Union[int, str] = 'HMAC 256/256', kid: Union[bytes, str] = b'', key_ops: Optional[Union[List[int], List[str]]] = None) → cwt.cose_key_interface.COSEKeyInterface [source]¶

Create a COSE key from a symmetric key.

Parameters

key (Union[bytes, str]) – A key bytes or string.
alg (Union[int, str]) – An algorithm label(int) or name(str). Supported alg are listed in Supported COSE Algorithms.
kid (Union[bytes, str]) – A key identifier.
key_ops (Union[List[int], List[str]]) – A list of key operation values. Following values can be used: 1("sign"), 2("verify"), 3("encrypt"), 4("decrypt"), 5("wrap key"), 6("unwrap key"), 7("derive key"), 8("derive bits"), 9("MAC create"), 10("MAC verify")

Returns

A COSE key object.

Return type

COSEKeyInterface

Raises

ValueError – Invalid arguments.

classmethod from_bytes(key_data: bytes) → cwt.cose_key_interface.COSEKeyInterface [source]¶

Create a COSE key from CBOR-formatted key data.

Parameters

key_data (bytes) – CBOR-formatted key data.

Returns

A COSE key object.

Return type

COSEKeyInterface

Raises

ValueError – Invalid arguments.
DecodeError – Failed to decode the key data.

classmethod from_jwk(data: Union[str, bytes, Dict[str, Any]]) → cwt.cose_key_interface.COSEKeyInterface [source]¶

Create a COSE key from JWK (JSON Web Key).

Parameters

jwk (Union[str, bytes, Dict[str, Any]]) – JWK-formatted key data.

Returns

A COSE key object.

Return type

COSEKeyInterface

Raises

ValueError – Invalid arguments.
DecodeError – Failed to decode the key data.

classmethod from_pem(key_data: Union[str, bytes], alg: Union[int, str] = '', kid: Union[bytes, str] = b'', key_ops: Optional[Union[List[int], List[str]]] = None) → cwt.cose_key_interface.COSEKeyInterface [source]¶

Create a COSE key from PEM-formatted key data.

Parameters

key_data (bytes) – A PEM-formatted key data.
alg (Union[int, str]) – An algorithm label(int) or name(str). Different from ::func::cwt.COSEKey.from_symmetric_key, it is only used when an algorithm cannot be specified by the PEM data, such as RSA family algorithms.
kid (Union[bytes, str]) – A key identifier.
key_ops (Union[List[int], List[str]]) – A list of key operation values. Following values can be used: 1("sign"), 2("verify"), 3("encrypt"), 4("decrypt"), 5("wrap key"), 6("unwrap key"), 7("derive key"), 8("derive bits"), 9("MAC create"), 10("MAC verify")

Returns

A COSE key object.

Return type

COSEKeyInterface

Raises

ValueError – Invalid arguments.
DecodeError – Failed to decode the key data.

class cwt.EncryptedCOSEKey[source]¶

Bases: cwt.cbor_processor.CBORProcessor

An encrypted COSE key.

static from_cose_key(key: cwt.cose_key_interface.COSEKeyInterface, encryption_key: cwt.cose_key_interface.COSEKeyInterface, nonce: bytes = b'', tagged: bool = False) → Union[List[Any], bytes][source]¶

Returns an encrypted COSE key formatted to COSE_Encrypt0 structure.

Parameters

key – COSEKeyInterface: A key to be encrypted.
encryption_key – COSEKeyInterface: An encryption key to encrypt the target COSE key.
nonce (bytes) – A nonce for encryption.

Returns

A COSE_Encrypt0 structure of the target COSE key.

Return type

List[Any]

Raises

ValueError – Invalid arguments.
EncodeError – Failed to encrypt the COSE key.

static to_cose_key(key: List[Any], encryption_key: cwt.cose_key_interface.COSEKeyInterface) → cwt.cose_key_interface.COSEKeyInterface [source]¶

Returns an decrypted COSE key.

Parameters

key – COSEKeyInterface: A key formatted to COSE_Encrypt0 structure to be decrypted.
encryption_key – COSEKeyInterface: An encryption key to decrypt the target COSE key.

Returns

A key decrypted.

Return type

COSEKeyInterface

Raises

ValueError – Invalid arguments.
DecodeError – Failed to decode the COSE key.
VerifyError – Failed to verify the COSE key.

class cwt.Claims(claims: Dict[int, Any], claim_names: Dict[str, int] = {'EAT-FDO': - 257, 'EATMAROEPrefix': - 258, 'EUPHNonce': - 259, 'aud': 3, 'cnf': 8, 'cti': 7, 'dbgstat': 16, 'eat_profile': 18, 'exp': 4, 'hcert': - 260, 'iat': 6, 'iss': 1, 'location': 17, 'nbf': 5, 'nonce': 10, 'oemid': 13, 'secboot': 15, 'seclevel': 14, 'sub': 2, 'submods': 20, 'ueid': 11})[source]¶

Bases: object

A class for handling CWT Claims like JWT claims.

classmethod from_dict(claims: Dict[int, Any], private_claim_names: Dict[str, int] = {}) → Any[source]¶

Create a Claims object from a CBOR-like(Dict[int, Any]) claim object.

Parameters

claims (Dict[str, Any]) – A CBOR-like(Dict[int, Any]) claim object.
private_claim_names (Dict[str, int]) –
A set of private claim definitions which consist of a readable claim name(str) and a claim key(int). The claim key should be less than -65536 but you can use the numbers other than pre-registered numbers listed in IANA Registry.

Returns

A CWT claims object.

Return type

Claims

Raises

ValueError – Invalid arguments.

classmethod from_json(claims: Union[str, bytes, Dict[str, Any]], private_claim_names: Dict[str, int] = {}) → cwt.claims.T[source]¶

Converts a JWT claims object into a CWT claims object which has numeric keys. If a key string in JSON data cannot be mapped to a numeric key, it will be skipped.

Parameters

claims (Union[str, bytes, Dict[str, Any]]) – A JWT claims object to be converted.
private_claim_names (Dict[str, int]) –
A set of private claim definitions which consist of a readable claim name(str) and a claim key(int). The claim key should be less than -65536 but you can use the numbers other than pre-registered numbers listed in IANA Registry.

Returns

A CWT claims object.

Return type

Claims

Raises

ValueError – Invalid arguments.

classmethod validate(claims: Dict[int, Any])[source]¶

Validates a CWT claims object.

Parameters: claims (Dict[int, Any]) – A CWT claims object to be validated.
Raises: ValueError – Failed to verify.

property iss: Optional[str]¶

property sub: Optional[str]¶

property aud: Optional[str]¶

property exp: Optional[int]¶

property nbf: Optional[int]¶

property iat: Optional[int]¶

property cti: Optional[str]¶

property cnf: Optional[Union[Dict[int, Any], List[Any], str]]¶

get(key: Union[str, int]) → Any[source]¶

Gets a claim value with a claim key.

Parameters: key (Union[str, int]) – A claim key.
Returns: The value of the claim.
Return type: Any

to_dict() → Dict[int, Any][source]¶

class cwt.Recipient[source]¶

Bases: object

A RecipientInterface Builder.

classmethod from_dict(protected: dict = {}, unprotected: dict = {}, ciphertext: bytes = b'', recipients: List[Any] = [], key_ops: List[int] = [], key: bytes = b'') → cwt.recipient_interface.RecipientInterface [source]¶

Create a recipient from a CBOR-like dictionary with numeric keys.

Parameters

protected (dict) – Parameters that are to be cryptographically protected.
unprotected (dict) – Parameters that are not cryptographically protected.

Returns

A recipient object.

Return type

RecipientInterface

Raises

ValueError – Invalid arguments.

classmethod from_json(data: Union[str, bytes, Dict[str, Any]]) → cwt.recipient_interface.RecipientInterface [source]¶

Create a recipient from JSON-formatted recipient data.

Parameters

data (Union[str, bytes, Dict[str, Any]]) – JSON-formatted recipient data.

Returns

A recipient object.

Return type

RecipientInterface

Raises

ValueError – Invalid arguments.
DecodeError – Failed to decode the key data.

exception cwt.CWTError[source]¶

Bases: Exception

Base class for all exceptions.

exception cwt.EncodeError[source]¶

Bases: cwt.exceptions.CWTError

An Exception occurred when a CWT/COSE encoding process failed.

exception cwt.DecodeError[source]¶

Bases: cwt.exceptions.CWTError

An Exception occurred when a CWT/COSE decoding process failed.

exception cwt.VerifyError[source]¶

Bases: cwt.exceptions.CWTError

An Exception occurred when a verification process failed.

class cwt.cose_key_interface.COSEKeyInterface(params: Dict[int, Any])[source]¶

Bases: cwt.cbor_processor.CBORProcessor

The interface class for a COSE Key used for MAC, signing/verifying and encryption/decryption.

__init__(params: Dict[int, Any])[source]¶

Constructor.

Parameters: params (Dict[int, Any]) – A COSE key common parameter object formatted to CBOR-like structure ((Dict[int, Any])).

property kty: int¶: The identifier of the key type.

property kid: Optional[bytes]¶: The key identifier.

property alg: Optional[int]¶: The algorithm that is used with the key.

property key_ops: List[int]¶: A set of permissible operations that the key is to be used for.

property base_iv: Optional[bytes]¶: Base IV to be xor-ed with Partial IVs.

property key: bytes¶: The body of the key as bytes.

to_dict() → Dict[int, Any][source]¶

Returns the CBOR-like structure (Dict[int, Any]) of the COSE key.

Returns: The CBOR-like structure of the COSE key.
Return type: Dict[int, Any]

generate_nonce() → bytes[source]¶

Returns a nonce with the size suitable for the algorithm. This function will be called internally in CWT when no nonce is specified by the application. This function adopts secrets.token_bytes() to generate a nonce. If you do not want to use it, you should explicitly set a nonce to CWT functions (e.g., encode_and_encrypt).

Returns: A byte string of the generated nonce.
Return type: bytes
Raises: NotImplementedError – Not implemented.

sign(msg: bytes) → bytes[source]¶

Returns a digital signature for the specified message using the specified key value.

Parameters

msg (bytes) – A message to be signed.

Returns

The byte string of the encoded CWT.

Return type

bytes

Raises

NotImplementedError – Not implemented.
ValueError – Invalid arguments.
EncodeError – Failed to sign the message.

verify(msg: bytes, sig: bytes)[source]¶

Verifies that the specified digital signature is valid for the specified message.

Parameters

msg (bytes) – A message to be verified.
sig (bytes) – A digital signature of the message.

Returns

The byte string of the encoded CWT.

Return type

bytes

Raises

NotImplementedError – Not implemented.
ValueError – Invalid arguments.
VerifyError – Failed to verify.

encrypt(msg: bytes, nonce: bytes, aad: bytes) → bytes[source]¶

Encrypts the specified message.

Parameters

msg (bytes) – A message to be encrypted.
nonce (bytes) – A nonce for encryption.
aad (bytes) – Additional authenticated data.

Returns

The byte string of encrypted data.

Return type

bytes

Raises

NotImplementedError – Not implemented.
ValueError – Invalid arguments.
EncodeError – Failed to encrypt the message.

decrypt(msg: bytes, nonce: bytes, aad: bytes) → bytes[source]¶

Decrypts the specified message.

Parameters

msg (bytes) – An encrypted message.
nonce (bytes) – A nonce for encryption.
aad (bytes) – Additional authenticated data.

Returns

The byte string of the decrypted data.

Return type

bytes

Raises

NotImplementedError – Not implemented.
ValueError – Invalid arguments.
DecodeError – Failed to decrypt the message.

class cwt.recipient_interface.RecipientInterface(protected: Optional[Dict[int, Any]] = None, unprotected: Optional[Dict[int, Any]] = None, ciphertext: bytes = b'', recipients: List[Any] = [], key_ops: List[int] = [], key: bytes = b'')[source]¶

Bases: cwt.cose_key_interface.COSEKeyInterface

The interface class for a COSE Recipient.

__init__(protected: Optional[Dict[int, Any]] = None, unprotected: Optional[Dict[int, Any]] = None, ciphertext: bytes = b'', recipients: List[Any] = [], key_ops: List[int] = [], key: bytes = b'')[source]¶

Constructor.

Parameters

protected (Optional[Dict[int, Any]]) – Parameters that are to be cryptographically protected.
unprotected (Optional[Dict[int, Any]]) – Parameters that are not cryptographically protected.
ciphertext – A ciphertext encoded as bytes.
recipients – A list of recipient information structures.
key_ops – A list of operations that the key is to be used for.
key – A body of the key as bytes.

property key: bytes¶: The body of the key as bytes.

property protected: Dict[int, Any]¶: The parameters that are to be cryptographically protected.

property unprotected: Dict[int, Any]¶: The parameters that are not cryptographically protected.

property ciphertext: bytes¶: The ciphertext encoded as bytes

property recipients: Optional[List[Any]]¶: The list of recipient information structures.

to_list() → List[Any][source]¶

Returns the recipient information as a COSE recipient structure.

Returns: The recipient structure.
Return type: List[Any]

set_key(key: bytes)[source]¶

Sets a key.

Parameters: key (bytes) – The key as bytes.

derive_key(material: bytes, context: Union[List[Any], Dict[str, Any]]) → cwt.cose_key_interface.COSEKeyInterface [source]¶

Derives a key from a key material.

Parameters

material (bytes) – A key material.
context (Union[List[Any], Dict[str, Any]]) – Context information structure.

Returns

A COSE key derived.

Return type

COSEKeyInterface

Raises

NotImplementedError – Not implemented.
ValueError – Invalid arguments.
EncodeError – Failed to derive key.

verify_key(material: bytes, expected_key: bytes, context: Union[List[Any], Dict[str, Any]])[source]¶

Verifies a key with a key material and an expected key.

Parameters

material (bytes) – A key material.
expected_key (bytes) – A byte string of the expected key.
context (Union[List[Any], Dict[str, Any]]) – Context information structure.

Raises

NotImplementedError – Not implemented.
ValueError – Invalid arguments.
VerifyError – Failed to verify the key.

wrap_key(key_to_wrap: bytes)[source]¶

Wraps a key and keeps it internally as the ciphertext.

Parameters

key_to_wrap (bytes) – A key to be wrapped.

Raises

NotImplementedError – Not implemented.
ValueError – Invalid arguments.
EncodeError – Failed to encode(wrap) key.

unwrap_key(alg: int) → cwt.cose_key_interface.COSEKeyInterface [source]¶

Unwraps the key stored as the ciphertext.

Parameters

alg (int) – The algorithm of the wrapped key.

Returns

An unwrapped key.

Return type

COSEKeyInterface

Raises

NotImplementedError – Not implemented.
ValueError – Invalid arguments.
DecodeError – Failed to decode(unwrap) the key.