API Reference¶
A Python implementation of PASETO <https://pyseto.readthedocs.io>
- pyseto.encode(key: pyseto.key_interface.KeyInterface, payload: Union[bytes, str, dict], footer: Union[bytes, str] = b'', implicit_assertion: Union[bytes, str] = b'', nonce: bytes = b'', serializer: Any = <module 'json' from '/home/docs/.pyenv/versions/3.7.9/lib/python3.7/json/__init__.py'>) 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
orv4
.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 usesecrets.token_bytes()
, you can specify it via this parameter explicitly.serializer (Any) – A serializer which is used when the type of
payload
isobject
. It must have adumps()
function to serialize the payload. Typically, you can usejson
orcbor2
.
- 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: Union[pyseto.key_interface.KeyInterface, List[pyseto.key_interface.KeyInterface]], token: Union[bytes, str], implicit_assertion: Union[bytes, str] = b'', deserializer: Optional[Any] = None) pyseto.token.Token [source]¶
Decodes a PASETO token with a key for decryption and/or verifying.
- Parameters
key (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
orv4
.deserializer (Optional[Any]) – A deserializer which is used when you want to deserialize a
payload
attribute in the response object. It must have aloads()
function to deserialize the payload. Typically, you can usejson
orcbor2
.
- Returns
A parsed PASETO token object.
- Return type
- 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: Union[bytes, str] = b'') pyseto.key_interface.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
or4
.purpose (str) – The purpose of the key. It will be
public
orlocal
.key (Union[bytes, str]) – A key itself or keying material.
- Returns
A PASETO key object.
- Return type
- Raises
ValueError – Invalid arguments.
- classmethod from_paserk(paserk: str, wrapping_key: Union[bytes, str] = b'', password: Union[bytes, str] = b'', unsealing_key: Union[bytes, str] = b'') pyseto.key_interface.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
- Raises
ValueError – Invalid arguments.
- static from_asymmetric_key_params(version: int, x: bytes = b'', y: bytes = b'', d: bytes = b'') pyseto.key_interface.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
or4
.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
- Raises
ValueError – Invalid arguments.
- exception pyseto.DecryptError[source]¶
Bases:
pyseto.exceptions.PysetoError
An Exception occurred when an decryption process failed.
- exception pyseto.EncryptError[source]¶
Bases:
pyseto.exceptions.PysetoError
An Exception occurred when an encryption process failed.
- exception pyseto.NotSupportedError[source]¶
Bases:
pyseto.exceptions.PysetoError
An Exception occurred when the function is not supported for the key object.
- exception pyseto.SignError[source]¶
Bases:
pyseto.exceptions.PysetoError
An Exception occurred when a signing process failed.
- exception pyseto.VerifyError[source]¶
Bases:
pyseto.exceptions.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
or4
.
- 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."
.
- to_paserk(wrapping_key: Union[bytes, str] = b'', password: Union[bytes, str] = b'', sealing_key: Union[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
- 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
orv4
.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
orv4
.
- 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
orv4
.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
orv4
.
- 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, footer: bytes = b'')[source]¶
Bases:
object
The parsed token object which is a return value of
pyseto.decode
.- 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¶
The payload of the token which is a decoded binary string. It’s not Base64 encoded data.
The footer of the token which is a decoded binary string. It’s not Base64 encoded data.