from typing import Any, Union
from .exceptions import NotSupportedError
[docs]class KeyInterface:
"""
The key interface class for PASETO.
:func:`pyseto.Key.new <pyseto.Key.new>` returns an object which has this interface.
"""
_VERSION = 0
_TYPE = ""
def __init__(self, version: int, purpose: str, key: Any):
self._version = version
self._purpose = purpose
self._header = (f"v{self._version}." + self._purpose + ".").encode("utf-8")
self._sig_size = 0
self._key: Any = key
if not self._key:
raise ValueError("key must be specified.")
return
@property
def version(self) -> int:
"""
The version of the key. It will be ``1``, ``2``, ``3`` or ``4``.
"""
return self._version
@property
def purpose(self) -> str:
"""
The purpose of the key. It will be ``"local"`` or ``"public"``.
"""
return self._purpose
@property
def header(self) -> bytes:
"""
The header value for a PASETO token. It will be ``"v<version>.<purpose>."``.
For example, ``"v1.local."``.
"""
return self._header
# @property
# def key(self) -> Any:
# """
# Byte string or pyca/cryptography key object of the key.
# If the key is ``public``, the key object is one of the pyca/cryptography objects bellow:
# - ``RSAPrivateKey``
# - ``RSAPublicKey``
# - ``Ed25519PrivateKey``
# - ``Ed25519PublicKey``
# - ``EllipticCurvePrivateKey``
# - ``EllipticCurvePublicKey``
# """
# return self._key
[docs] def to_paserk(
self,
wrapping_key: Union[bytes, str] = b"",
password: Union[bytes, str] = b"",
iteration: int = 100000,
memory_cost: int = 15 * 1024,
time_cost: int = 2,
parallelism: int = 1,
) -> str:
"""
Returns the PASERK expression of the key.
Args:
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.
Returns:
str: A PASERK string.
Raise:
ValueError: Invalid arguments.
EncryptError: Failed to wrap the key.
"""
raise NotImplementedError(
"The PASERK expression for the key is not supported yet."
)
[docs] def to_paserk_id(self) -> str:
"""
Returns the PASERK ID of the key.
Returns:
str: A PASERK ID string.
"""
raise NotImplementedError("The PASERK ID for the key is not supported yet.")
[docs] def encrypt(
self,
payload: bytes,
footer: bytes = b"",
implicit_assertion: bytes = b"",
nonce: bytes = b"",
) -> bytes:
"""
Encrypts a message to a PASETO token with the key.
This function is calld in :func:`pyseto.encode <pyseto.encode>` so you
don't need to call it directly.
Args:
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:
bytes: A PASETO token.
Raise:
ValueError: Invalid arguments.
EncryptError: Failed to encrypt the message.
NotSupportedError: The key does not support the operation.
"""
raise NotSupportedError("A key for public does not have encrypt().")
[docs] def decrypt(
self, payload: bytes, footer: bytes = b"", implicit_assertion: bytes = b""
) -> bytes:
"""
Decrypts an encrypted PASETO token with the key.
This function is calld in :func:`pyseto.decode <pyseto.decode>` so you
don't need to call it directly.
Args:
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:
bytes: A dcrypted payload.
Raise:
ValueError: Invalid arguments.
DecryptError: Failed to decrypt the message.
NotSupportedError: The key does not support the operation.
"""
raise NotSupportedError("A key for public does not have decrypt().")
[docs] def sign(
self, payload: bytes, footer: bytes = b"", implicit_assertion: bytes = b""
) -> bytes:
"""
Signs a message with the key and makes a PASETO token.
This function is calld in :func:`pyseto.encode <pyseto.encode>` so you
don't need to call it directly.
Args:
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:
bytes: A PASETO token.
Raise:
ValueError: Invalid arguments.
EncryptError: Failed to sign the message.
NotSupportedError: The key does not support the operation.
"""
raise NotSupportedError("A key for local does not have sign().")
[docs] def verify(
self, payload: bytes, footer: bytes = b"", implicit_assertion: bytes = b""
) -> bytes:
"""
Verifies and decodes a signed PASETO token with the key.
This function is calld in :func:`pyseto.decode <pyseto.decode>` so you
don't need to call it directly.
Args:
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:
bytes: A verified and decoded payload.
Raise:
ValueError: Invalid arguments.
DecryptError: Failed to verify the message.
NotSupportedError: The key does not support the operation.
"""
raise NotSupportedError("A key for local does not have verify().")