Secretbox

class SecretBoxKey

Bases: BaseKey

SecretBoxKey represents a key for the secretbox API.

The secretbox API is used for authenticated encryption of messages.

__bool__()

Returns True if the key is not zero, False otherwise.

Returns:

• bool –

  True if the key is not zero, False otherwise.

__init__(key)

Initialize the SecretBoxKey with a key.

Parameters:

• key (bytes | str | Self | Buffer) –

  32-bytes-like object, a base64 encoded string, or another SecretBoxKey.

Raises:

• ValueError –

  If the key is None.

• TypeError –

  If the key is of an unsupported type.

__str__()

Returns a base64-encoded representation of the key.

Returns:

• str –

  A string representing the key in base64 encoding.

from_password(password, *, master_key=None, ctx=None, opslimit=...) classmethod

Derive a key from a password using the provided master key.

This class method is used to create a high entropy key from a password. This is useful for example to encrypt a file using a password.

Parameters:

• password (bytes | Buffer) –

  The password to derive the key from.

• master_key (bytes | str | Buffer | MasterKey | None, default: None ) –

  Optional master key to use for derivation. If None, a default master key is used.

• ctx (bytes | str | Context | Buffer | None, default: None ) –

  Optional context for the key derivation.

• opslimit (int, default: ... ) –

  Optional operation limit for the key derivation. The higher the opslimit the more secure the key derivation is, but it will take longer to compute. Default is 10000 operations.

Returns:

• Self –

  A new SecretBoxKey instance derived from the password.

gen() classmethod

Generate a new BaseKey with random bytes.

Returns:

• Self –

  A new instance of BaseKey.

is_zero()

Checks if the key is the zero key.

Returns:

• bool –

  True if the key is zero, False otherwise.

read_from(reader) classmethod

Create a key from a reader.

Parameters:

• reader (Reader) –

  A reader object that supports the read method.

Returns:

• Self –

  A new instance of BaseKey read from the provided reader.

Raises:

• TypeError –

  If the provided reader does not have a 'read' method.

• ValueError –

  If the read data is not 32 bytes long.

secretbox(ctx=None)

Create a SecretBox instance with the current key and context.

Parameters:

• ctx (bytes | str | Context | Buffer | None, default: None ) –

  Optional context for the secret box. If None, a default context is used.

Returns:

• SecretBox –

  A new SecretBox instance initialized with the current key and context.

writeto(out)

Write the key to a writer.

Parameters:

• out (Writer) –

  A writer object that supports the write method.

Returns:

• int –

  The number of bytes written, which should be 32.

Raises:

• TypeError –

  If the provided writer does not have a 'write' method.

zero() classmethod

Generate a new BaseKey initialized to zero.

Returns:

• Self –

  A new instance of BaseKey initialized to zero.

class SecretBox

SecretBox is a class for encrypting and decrypting messages using a secret key.

All attributes are readonly after initialization.

Attributes:

• key (SecretBoxKey) –

  The SecretBoxKey used for encryption and decryption.

• ctx (Context) –

  The context for the secret box operations.

__init__(key, *, ctx=None)

Initialize the secret box with a key and context.

Parameters:

• key (bytes | str | SecretBoxKey | Buffer) –

  The key to use for encryption and decryption.

• ctx (bytes | str | Context | Buffer | None, default: None ) –

  Optional context for the secret box. If None, a default context is used.

Raises:

• ValueError –

  If the key is None or the context is invalid.

• TypeError –

  If the key has an unsupported type.

decrypt(ciphertext, msg_id=0, max_msg_size=None)

Decrypt the ciphertext using the secret box key, an optional context and message ID.

The optional msg_id must match the one used during encryption.

Parameters:

• ciphertext (bytes | Buffer | EncryptedMessage) –

  The ciphertext to decrypt. Can be an EncryptedMessage or a bytes-like object.

• msg_id (int, default: 0 ) –

  Optional message ID to verify against the ciphertext. Default is 0.

• max_msg_size (int | None, default: None ) –

  Optional maximum size of the plaintext. If provided, raises cydrogen.MessageTooBigException if the plaintext size exceeds this limit.

Returns:

• bytes –

  The decrypted plaintext as bytes.

Raises:

• ValueError –

  If the ciphertext is None or if the ciphertext is too short.

• MessageTooBigException –

  If the decrypted plaintext is too long.

• TypeError –

  If the out object does not support writing.

• DecryptException –

  If decryption fails.

decrypt_file(src, dst)

Decrypt a file-like object and write the plaintext to another file-like object.

Parameters:

• src (str | PathLike | BinaryIO) –

  The source file-like object to read the ciphertext from.

• dst (str | PathLike | BinaryIO) –

  The destination file-like object to write the plaintext to.

Returns:

• int –

  The total number of bytes written to the destination file.

Raises:

• ValueError –

  If the source or destination file objects are None.

• TypeError –

  If the source or destination file objects are not file-like/path-like objects.

• OSError –

  If reading from the source file or writing to the destination file fails.

• DecryptException –

  If decryption fails.

encrypt(plaintext, msg_id=0, max_msg_size=None)

Encrypt the plaintext using the secret box key, context and message ID.

Parameters:

• plaintext (bytes | Buffer) –

  The plaintext to encrypt.

• msg_id (int, default: 0 ) –

  Optional message ID to associate with the encrypted message. Default is 0.

• max_msg_size (int | None, default: None ) –

  Optional maximum size of the plaintext. If provided, raises cydrogen.MessageTooBigException if the plaintext size exceeds this limit.

Returns:

• bytes –

  The encrypted message as bytes (not framed).

Raises:

• ValueError –

  If the plaintext is None.

• MessageTooBigException –

  If the plaintext is too long.

• TypeError –

  if the out object does not support writing.

• EncryptException –

  If encryption fails.

encrypt_file(src, dst, chunk_size=8192)

Encrypt a file-like/path-like object and write the ciphertext to another file-like object.

Parameters:

• src (str | PathLike | BinaryIO) –

  The source file-like/path-like object to read the plaintext from.

• dst (str | PathLike | BinaryIO) –

  The destination file-like/path-like object to write the ciphertext to.

• chunk_size (int, default: 8192 ) –

  Optional size of the chunks to read from the source file.

Returns:

• int –

  The total number of bytes written to the destination file.

Raises:

• ValueError –

  If the source or destination file objects are None.

• TypeError –

  If the source or destination file objects are not file-like/path-like objects.

• OSError –

  If reading from the source file or writing to the destination file fails.

• EncryptException –

  If encryption fails.

class EncryptedMessage

EncryptedMessage represents an encrypted message.

EncryptedMessage encapsulates the ciphertext and the message ID. It is used to serialize an encrypted message to a bytes object that can be sent over the wire.

The serialized format is as follows: - The first 4 bytes are a magic header (ENC_MSG_HEADER). - The next 8 bytes are the length (N) of the encrypted message. - The next 8 bytes are the message ID. - The rest is the encrypted message (N bytes).

All attributes are readonly after initialization.

Attributes:

• ciphertext (Buffer) –

  The encrypted message itself.

• msg_id (int) –

  The message ID associated with the encrypted message.

• session_keys_idx (int) –

  the index of the crypto material that was used to encrypt the message.

__bytes__()

Return the serialized form of the encrypted message as bytes.

Returns:

• bytes ( bytes ) –

  The serialized encrypted message.

__init__(ctext, msg_id, session_keys_idx=0)

Initialize the encrypted message.

Parameters:

• ctext (Buffer) –

  The ciphertext of the encrypted message.

• msg_id (int) –

  The message ID associated with the encrypted message.

• session_keys_idx (int, default: 0 ) –

  the index of the crypto material

Raises:

• ValueError –

  If ctext is None.

__len__()

Return the length of the framed, encrypted message in bytes, including the header and message ID.

Returns:

• int ( int ) –

  The length of the encrypted message.

awriteto(out) async

Asynchronously write the framed encrypted message to an async writer.

Parameters:

• out (AsyncWriter) –

  An async writer to write the message to.

Raises:

• ValueError –

  If the async writer is None.

• TypeError –

  If the async writer is not an async writer.

from_bytes(framed, *, max_msg_size=None) classmethod

Create an EncryptedMessage from a framed bytes object.

Parameters:

• framed (bytes | Buffer) –

  A bytes-like object containing the framed ciphertext.

• max_msg_size (int | None, default: None ) –

  Optional maximum size of the message. If provided, raises ValueError if the message size exceeds this limit.

Returns:

• Self –

  An instance of EncryptedMessage.

Raises:

• ValueError –

  If the framed message is None or if parsing fails.

• OSError –

  If reading the message header or message fails.

writeto(out)

Write the framed encrypted message to a file-like/path-like object.

Parameters:

• out (Writer) –

  A file-like object to write the message to.

Returns:

• int –

  The number of bytes written to the file object.

Raises:

• ValueError –

  If the file object is None.

• TypeError –

  If the file object is not a file-like/path-like object.

• OSError –

  If the write operation fails.