API Reference¶

A Python implementation of PASETO/PASERK. <https://pyseto.readthedocs.io>

pyseto.encode(key: ~pyseto.key_interface.KeyInterface, payload: bytes | str | dict, footer: bytes | str = b'', implicit_assertion: bytes | str = b'', nonce: bytes = b'', serializer: ~typing.Any = <module 'json' from '/home/docs/.asdf/installs/python/3.11.6/lib/python3.11/json/__init__.py'>, exp: int = 0) → bytes[source]¶

Encodes a message to a PASETO token with a key for encryption or signing.

Parameters:

key (KeyInterface) – A key for encryption or signing.
payload (Union[bytes, str, dict]) – A message to be encrypted or signed.
footer (Union[bytes, str]) – A footer.
implicit_assertion (Union[bytes, str]) – An implicit assertion. It is only used in v3 or v4.
nonce (bytes) – A nonce. If omitted(it’s recommended), a nonce will be generated with secrets.token_bytes() internally. If you don’t want ot use secrets.token_bytes(), you can specify it via this parameter explicitly.
serializer (Any) – A serializer which is used when the type of payload is object. It must have a dumps() function to serialize the payload. Typically, you can use json or cbor2.
exp (int) – An expiration time (seconds) of the PASETO token. It will be set in the payload as the registered exp claim when serializer is json and this value > 0. If the value <= 0, the exp claim will not be set.

Returns:

A PASETO token.

Return type:

bytes

Raises:

ValueError – Invalid arguments.
EncryptError – Failed to encrypt the message.
SignError – Failed to sign the message.

pyseto.decode(keys: KeyInterface | List[KeyInterface], token: bytes | str, implicit_assertion: bytes | str = b'', deserializer: Any | None = None, aud: str = '') → Token[source]¶

Decodes a PASETO token with a key for decryption and/or verifying.

Parameters:

keys (KeyInterface) – A key for decryption or verifying the signature in the token.
token (Union[bytes, str]) – A PASETO token to be decrypted or verified.
implicit_assertion (Union[bytes, str]) – An implicit assertion. It is only used in v3 or v4.
deserializer (Optional[Any]) – A deserializer which is used when you want to deserialize a payload attribute in the response object. It must have a loads() function to deserialize the payload. Typically, you can use json or cbor2.
aud (str) – An audience claim value for the token verification. If deserializer=json and the payload of the token does not include an aud value that matches this value, the verification will fail.

Returns:

A parsed PASETO token object.

Return type:

Token

Raises:

ValueError – Invalid arguments.
DecryptError – Failed to decrypt the message.
VerifyError – Failed to verify the message.

class pyseto.Key[source]¶

Bases: object

Tha factory methods for PASETO keys.

classmethod new(version: int, purpose: str, key: bytes | str = b'') → KeyInterface[source]¶

Constructor of a PASETO key object which has KeyInterface.

Parameters:

version (int) – The version of the key. It will be 1, 2, 3 or 4.
purpose (str) – The purpose of the key. It will be public or local.
key (Union[bytes, str]) – A key itself or keying material.

Returns:

A PASETO key object.

Return type:

KeyInterface

Raises:

ValueError – Invalid arguments.

classmethod from_paserk(paserk: str, wrapping_key: bytes | str = b'', password: bytes | str = b'', unsealing_key: bytes | str = b'') → KeyInterface[source]¶

Generates a PASETO key object which has KeyInterface from PASERK.

Parameters:

paserk (str) – A PASERK string.
wrapping_key (Union[bytes, str]) – A wrapping key. If the wrapping_key is specified, password should not be specified.
password (Union[bytes, str]) – A password for key wrapping. If the password is specified, wrapping_key should not be specified.
unsealing_key (Union[bytes, str]) – A password for key wrapping. If the password is specified, wrapping_key should not be specified.

Returns:

A PASETO key object.

Return type:

KeyInterface

Raises:

ValueError – Invalid arguments.

static from_asymmetric_key_params(version: int, x: bytes = b'', y: bytes = b'', d: bytes = b'') → KeyInterface[source]¶

Constructor of a PASETO key object which has KeyInterface wth asymmetric key parameters (x-coordinate, y-coordinate, and/or private key). This is intended to be used to generate keys for PASETO from JWK and other sources.

Parameters:

version (int) – The version of the key. It will be 1, 2, 3 or 4.
x (bytes) – The x coordinate of the key.
y (bytes) – The y coordinate of the key.
d (bytes) – The private key component of the key.

Returns:

A PASETO key object.

Return type:

KeyInterface

Raises:

ValueError – Invalid arguments.

class pyseto.KeyInterface(version: int, purpose: str, key: Any)[source]¶

Bases: object

The key interface class for PASETO.

pyseto.Key.new returns an object which has this interface.

property version: int¶: The version of the key. It will be 1, 2, 3 or 4.

property purpose: str¶: The purpose of the key. It will be "local" or "public".

property header: bytes¶: The header value for a PASETO token. It will be "v<version>.<purpose>.". For example, "v1.local.".

property is_secret: bool¶: If it is True, the key is a symmetric key or an asymmetric secret key.

to_paserk(wrapping_key: bytes | str = b'', password: bytes | str = b'', sealing_key: bytes | str = b'', iteration: int = 100000, memory_cost: int = 15360, time_cost: int = 2, parallelism: int = 1) → str[source]¶

Returns the PASERK expression of the key.

Parameters:

wrapping_key (Union[bytes, str]) – A wrapping key to wrap the key. If the wrapping_key is specified, password should not be specified.
password (Union[bytes, str]) – A password to wrap the key. If the password is specified, wrapping_key should not be specified.
iteration (int) – An iteration count used for password-based key wrapping. This argument will only be used when the password is specified.
memory_cost (int) – Amount of memory to use for password-based key wrapping using argon2. This argument will only be used when the password is specified for v2/v4 key.
time_cost (int) – Number of iterations to perform for password-based key wrapping using argon2. This argument will only be used when the password is specified for v2/v4 key.
parallelism (int) – Degree of parallelism for password-based key wrapping using argon2. This argument will only be used when the password is specified for v2/v4 key.

Returns:

A PASERK string.

Return type:

str

Raises:

ValueError – Invalid arguments.
EncryptError – Failed to wrap the key.

to_paserk_id() → str[source]¶

Returns the PASERK ID of the key.

Returns:: A PASERK ID string.
Return type:: str

to_peer_paserk_id() → str[source]¶

Returns the peer(public) PASERK ID of the key. It can be used only in case that the key is k2.secret or k4.secret.

Returns:

A peer PASERK ID string. If the key is neither k2.secret nor: k4.secret, an empty string will be returned.

Return type:

str

encrypt(payload: bytes, footer: bytes = b'', implicit_assertion: bytes = b'', nonce: bytes = b'') → bytes[source]¶

Encrypts a message to a PASETO token with the key.

This function is calld in pyseto.encode so you don’t need to call it directly.

Parameters:

payload (bytes) – A message to be encrypted which will be the payload part of the PASETO token.
footer (bytes) – A footer.
implicit_assertion (Union[bytes, str]) – An implicit assertion. It is only used in v3 or v4.
nonce (bytes) – A nonce.

Returns:

A PASETO token.

Return type:

bytes

Raises:

ValueError – Invalid arguments.
EncryptError – Failed to encrypt the message.
NotSupportedError – The key does not support the operation.

decrypt(payload: bytes, footer: bytes = b'', implicit_assertion: bytes = b'') → bytes[source]¶

Decrypts an encrypted PASETO token with the key.

This function is calld in pyseto.decode so you don’t need to call it directly.

Parameters:

payload (bytes) – A message to be decrypted which is the payload part of the PASETO token.
footer (bytes) – A footer.
implicit_assertion (Union[bytes, str]) – An implicit assertion. It is only used in v3 or v4.

Returns:

A dcrypted payload.

Return type:

bytes

Raises:

ValueError – Invalid arguments.
DecryptError – Failed to decrypt the message.
NotSupportedError – The key does not support the operation.

sign(payload: bytes, footer: bytes = b'', implicit_assertion: bytes = b'') → bytes[source]¶

Signs a message with the key and makes a PASETO token.

This function is calld in pyseto.encode so you don’t need to call it directly.

Parameters:

payload (bytes) – A message to be signed and encoded which will be the payload part of the PASETO token.
footer (bytes) – A footer.
implicit_assertion (Union[bytes, str]) – An implicit assertion. It is only used in v3 or v4.
nonce (bytes) – A nonce.

Returns:

A PASETO token.

Return type:

bytes

Raises:

ValueError – Invalid arguments.
EncryptError – Failed to sign the message.
NotSupportedError – The key does not support the operation.

verify(payload: bytes, footer: bytes = b'', implicit_assertion: bytes = b'') → bytes[source]¶

Verifies and decodes a signed PASETO token with the key.

This function is calld in pyseto.decode so you don’t need to call it directly.

Parameters:

payload (bytes) – A message to be verified and decoded which is the payload part of the PASETO token.
footer (bytes) – A footer.
implicit_assertion (Union[bytes, str]) – An implicit assertion. It is only used in v3 or v4.

Returns:

A verified and decoded payload.

Return type:

bytes

Raises:

ValueError – Invalid arguments.
DecryptError – Failed to verify the message.
NotSupportedError – The key does not support the operation.

class pyseto.Paseto(exp: int = 0, include_iat: bool = False, leeway: int = 0)[source]¶

Bases: object

A PASETO processor which can be used as a PASETO encoder/decoder.

classmethod new(exp: int = 0, include_iat: bool = False, leeway: int = 0)[source]¶

Constructor of PASETO processor.

Parameters:

exp (int) – A default expiration time (seconds) of PASETO tokens. It will be set in the payload as the registered exp claim when calling encode() with serializer=``json`` and this value > 0. If the value <= 0, the exp claim will not be set. In addition, this value can be overwritten by the exp parameter of encode(). The default value is 0.
include_iat (bool) – If this value is True, PASETO tokens which are created through encode() include an iat claim when calling encode() with serializer=``json``. The default value is False.
leeway (int) – The leeway in seconds for validating exp and nbf. The default value is 0.

Returns:

A PASETO processor object.

Return type:

bytes

encode(key: ~pyseto.key_interface.KeyInterface, payload: bytes | str | dict, footer: bytes | str | dict = b'', implicit_assertion: bytes | str = b'', nonce: bytes = b'', serializer: ~typing.Any = <module 'json' from '/home/docs/.asdf/installs/python/3.11.6/lib/python3.11/json/__init__.py'>, exp: int = 0) → bytes[source]¶

Encodes a message to a PASETO token with a key for encryption or signing.

Parameters:

key (KeyInterface) – A key for encryption or signing.
payload (Union[bytes, str, dict]) – A message to be encrypted or signed.
footer (Union[bytes, str, dict]) – A footer.
implicit_assertion (Union[bytes, str]) – An implicit assertion. It is only used in v3 or v4.
nonce (bytes) – A nonce. If omitted(it’s recommended), a nonce will be generated with secrets.token_bytes() internally. If you don’t want ot use secrets.token_bytes(), you can specify it via this parameter explicitly.
serializer (Any) – A serializer which is used when the type of payload and/or footer is dict. It must have a dumps() function to serialize the payload. Typically, you can use json or cbor2.
exp (int) – An expiration time (seconds) of the PASETO token. It will be set in the payload as the registered exp claim when serializer is json and this value > 0. If the value <= 0, the exp claim will not be set.

Returns:

A PASETO token.

Return type:

bytes

Raises:

ValueError – Invalid arguments.
EncryptError – Failed to encrypt the message.
SignError – Failed to sign the message.

decode(keys: KeyInterface | List[KeyInterface], token: bytes | str, implicit_assertion: bytes | str = b'', deserializer: Any | None = None, aud: str = '') → Token[source]¶

Decodes a PASETO token with a key for decryption and/or verifying.

Parameters:

keys (KeyInterface) – A key for decryption or verifying the signature in the token.
token (Union[bytes, str]) – A PASETO token to be decrypted or verified.
implicit_assertion (Union[bytes, str]) – An implicit assertion. It is only used in v3 or v4.
deserializer (Optional[Any]) – A deserializer which is used when you want to deserialize a payload attribute in the response object. It must have a loads() function to deserialize the payload. Typically, you can use json or cbor2.
aud (str) – An audience claim value for the token verification. If deserializer=json and the payload of the token does not include an aud value that matches this value, the verification will fail.

Returns:

A parsed PASETO token object.

Return type:

Token

Raises:

ValueError – Invalid arguments.
DecryptError – Failed to decrypt the message.
VerifyError – Failed to verify the message.

exception pyseto.PysetoError[source]¶

Bases: Exception

Base class for all exceptions.

class pyseto.Token(version: str, purpose: str, payload: bytes | dict, footer: bytes | dict = b'')[source]¶

Bases: object

The parsed token object which is a return value of pyseto.decode.

classmethod new(token: bytes | str)[source]¶

property version: str¶: The version of the token. It will be "v1", "v2", "v3" or "v4".

property purpose: str¶: The purpose of the token. It will be "local" or "public".

property header: bytes¶: The header of the token. It will be "<version>.<type>.". For example, "v1.local.".

property payload: bytes | dict¶: The payload of the token which is a decoded binary string. It’s not Base64 encoded data.

property footer: bytes | dict¶: The footer of the token which is a decoded binary string. It’s not Base64 encoded data.

exception pyseto.DecryptError[source]¶

Bases: PysetoError

An Exception occurred when an decryption process failed.

exception pyseto.EncryptError[source]¶

Bases: PysetoError

An Exception occurred when an encryption process failed.

exception pyseto.NotSupportedError[source]¶

Bases: PysetoError

An Exception occurred when the function is not supported for the key object.

exception pyseto.SignError[source]¶

Bases: PysetoError

An Exception occurred when a signing process failed.

exception pyseto.VerifyError[source]¶

Bases: PysetoError

An Exception occurred when a verification process failed.

class pyseto.key_interface.KeyInterface(version: int, purpose: str, key: Any)[source]¶

Bases: object

The key interface class for PASETO.

pyseto.Key.new returns an object which has this interface.

property version: int¶: The version of the key. It will be 1, 2, 3 or 4.

property purpose: str¶: The purpose of the key. It will be "local" or "public".

property header: bytes¶: The header value for a PASETO token. It will be "v<version>.<purpose>.". For example, "v1.local.".

property is_secret: bool¶: If it is True, the key is a symmetric key or an asymmetric secret key.

to_paserk(wrapping_key: bytes | str = b'', password: bytes | str = b'', sealing_key: bytes | str = b'', iteration: int = 100000, memory_cost: int = 15360, time_cost: int = 2, parallelism: int = 1) → str[source]¶

Returns the PASERK expression of the key.

Parameters:

wrapping_key (Union[bytes, str]) – A wrapping key to wrap the key. If the wrapping_key is specified, password should not be specified.
password (Union[bytes, str]) – A password to wrap the key. If the password is specified, wrapping_key should not be specified.
iteration (int) – An iteration count used for password-based key wrapping. This argument will only be used when the password is specified.
memory_cost (int) – Amount of memory to use for password-based key wrapping using argon2. This argument will only be used when the password is specified for v2/v4 key.
time_cost (int) – Number of iterations to perform for password-based key wrapping using argon2. This argument will only be used when the password is specified for v2/v4 key.
parallelism (int) – Degree of parallelism for password-based key wrapping using argon2. This argument will only be used when the password is specified for v2/v4 key.

Returns:

A PASERK string.

Return type:

str

Raises:

ValueError – Invalid arguments.
EncryptError – Failed to wrap the key.

to_paserk_id() → str[source]¶

Returns the PASERK ID of the key.

Returns:: A PASERK ID string.
Return type:: str

to_peer_paserk_id() → str[source]¶

Returns the peer(public) PASERK ID of the key. It can be used only in case that the key is k2.secret or k4.secret.

Returns:

A peer PASERK ID string. If the key is neither k2.secret nor: k4.secret, an empty string will be returned.

Return type:

str

encrypt(payload: bytes, footer: bytes = b'', implicit_assertion: bytes = b'', nonce: bytes = b'') → bytes[source]¶

Encrypts a message to a PASETO token with the key.

This function is calld in pyseto.encode so you don’t need to call it directly.

Parameters:

payload (bytes) – A message to be encrypted which will be the payload part of the PASETO token.
footer (bytes) – A footer.
implicit_assertion (Union[bytes, str]) – An implicit assertion. It is only used in v3 or v4.
nonce (bytes) – A nonce.

Returns:

A PASETO token.

Return type:

bytes

Raises:

ValueError – Invalid arguments.
EncryptError – Failed to encrypt the message.
NotSupportedError – The key does not support the operation.

decrypt(payload: bytes, footer: bytes = b'', implicit_assertion: bytes = b'') → bytes[source]¶

Decrypts an encrypted PASETO token with the key.

This function is calld in pyseto.decode so you don’t need to call it directly.

Parameters:

payload (bytes) – A message to be decrypted which is the payload part of the PASETO token.
footer (bytes) – A footer.
implicit_assertion (Union[bytes, str]) – An implicit assertion. It is only used in v3 or v4.

Returns:

A dcrypted payload.

Return type:

bytes

Raises:

ValueError – Invalid arguments.
DecryptError – Failed to decrypt the message.
NotSupportedError – The key does not support the operation.

sign(payload: bytes, footer: bytes = b'', implicit_assertion: bytes = b'') → bytes[source]¶

Signs a message with the key and makes a PASETO token.

This function is calld in pyseto.encode so you don’t need to call it directly.

Parameters:

payload (bytes) – A message to be signed and encoded which will be the payload part of the PASETO token.
footer (bytes) – A footer.
implicit_assertion (Union[bytes, str]) – An implicit assertion. It is only used in v3 or v4.
nonce (bytes) – A nonce.

Returns:

A PASETO token.

Return type:

bytes

Raises:

ValueError – Invalid arguments.
EncryptError – Failed to sign the message.
NotSupportedError – The key does not support the operation.

verify(payload: bytes, footer: bytes = b'', implicit_assertion: bytes = b'') → bytes[source]¶

Verifies and decodes a signed PASETO token with the key.

This function is calld in pyseto.decode so you don’t need to call it directly.

Parameters:

payload (bytes) – A message to be verified and decoded which is the payload part of the PASETO token.
footer (bytes) – A footer.
implicit_assertion (Union[bytes, str]) – An implicit assertion. It is only used in v3 or v4.

Returns:

A verified and decoded payload.

Return type:

bytes

Raises:

ValueError – Invalid arguments.
DecryptError – Failed to verify the message.
NotSupportedError – The key does not support the operation.

class pyseto.token.Token(version: str, purpose: str, payload: bytes | dict, footer: bytes | dict = b'')[source]¶

Bases: object

The parsed token object which is a return value of pyseto.decode.

classmethod new(token: bytes | str)[source]¶

property version: str¶: The version of the token. It will be "v1", "v2", "v3" or "v4".

property purpose: str¶: The purpose of the token. It will be "local" or "public".

property header: bytes¶: The header of the token. It will be "<version>.<type>.". For example, "v1.local.".

property payload: bytes | dict¶: The payload of the token which is a decoded binary string. It’s not Base64 encoded data.

property footer: bytes | dict¶: The footer of the token which is a decoded binary string. It’s not Base64 encoded data.