Skip to content

Key Derivation

class MasterKey

Bases: BaseKey

A MasterKey can be used to derive subkeys, derive a key from a password, or hash passwords for storage.

__bool__()

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

Returns:

  • bool –

    True if the key is not zero, False otherwise.

__init__(key=None)

Initialize a MasterKey.

Parameters:

  • key (str | bytes | Self | Buffer | None, default: None ) –

    A bytes-like object, a base64 encoded string, or another MasterKey. If None, initializes a zero MasterKey.

Raises:

  • TypeError –

    If the key is of an unsupported type.

  • ValueError –

    If the key is empty or invalid.

__str__()

Returns a base64-encoded representation of the key.

Returns:

  • str –

    A string representing the key in base64 encoding.

derive_key_from_password(password, ctx=None, opslimit=10000)

Derive a high entropy key from a password, using the master key.

The derived key is returned as a BaseKey. You can then convert the derived key to a specific key type if needed.

Parameters:

  • password (bytes | Buffer) –

    The password to derive the key from.

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

    Optional context for the derivation.

  • opslimit (int, default: 10000 ) –

    The number of operations limit for the derivation.

Returns:

  • BaseKey –

    The derived key as a BaseKey.

Raises:

derive_key_from_password_with_length(password, length=32, ctx=None, opslimit=10000)

Derive a high entropy key from a password using the master key.

You can choose the length of the derived key. It is returned as bytes.

Parameters:

  • password (bytes | Buffer) –

    The password to derive the key from.

  • length (int, default: 32 ) –

    The length of the derived key in bytes (default is 32).

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

    Optional context for the derivation.

  • opslimit (int, default: 10000 ) –

    The number of operations limit for the derivation.

Returns:

  • bytes –

    The derived key as bytes.

Raises:

derive_kx_keypair()

Derive a key exchange pair from the master key.

Useful for tests.

Returns:

  • KxPair –

    A KxPair derived from the master key.

derive_sign_keypair()

Derive a sign keypair from the master key.

Useful for tests.

Returns:

  • SignKeyPair –

    A SignKeyPair derived from the master key.

derive_subkey(subkey_id, ctx=None)

Derive a subkey from the master key using the subkey_id.

The derived key is returned as a BaseKey. You can then convert the derived key to a specific key type if needed.

Parameters:

  • subkey_id (int) –

    The identifier for the subkey to derive.

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

    Optional context for the derivation.

Returns:

  • BaseKey –

    The derived subkey as a BaseKey.

Raises:

derive_subkey_with_length(subkey_id, length=32, ctx=None)

Derive a subkey from the master key using the subkey_id.

You can choose the length of the derived subkey. It is returned as bytes.

Parameters:

  • subkey_id (int) –

    The identifier for the subkey to derive.

  • length (int, default: 32 ) –

    The length of the derived subkey in bytes (default is 32).

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

    Optional context for the derivation.

Returns:

  • bytes –

    The derived subkey as bytes.

Raises:

  • ValueError –

    If the master key is zero, or if length is not in the valid range (16 to 65535).

  • DeriveException –

    If the derivation fails.

gen() classmethod

Generate a new BaseKey with random bytes.

Returns:

  • Self –

    A new instance of BaseKey.

gen_random_buffer(size)

Generates a buffer of size bytes, indistinguishable from random bytes without knowing the master key.

For a given seed, this function will always output the same sequence.

This function is mainly useful for writing tests.

Parameters:

  • size (int) –

    The size of the buffer to generate.

Returns:

  • bytes –

    A bytes object of the specified size containing pseudo-random data.

hash_password(password, opslimit=10000)

Returns a representation of the password suitable for storage.

This method hashes the password using the master key and returns a 128 byte long bytes.

Parameters:

  • password (bytes | Buffer) –

    The password to hash.

  • opslimit (int, default: 10000 ) –

    The number of operations limit for the hashing.

Returns:

  • bytes –

    A bytes object containing the hashed password (128 bytes).

Raises:

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.

verify_password(password, stored, opslimit=10000)

Verify a password against a stored hash.

The stored hash should have been previously created using the hash_password method.

Parameters:

  • password (bytes | Buffer) –

    The password to verify.

  • stored (bytes | Buffer) –

    The stored hash to verify against (should be 128 bytes long).

  • opslimit (int, default: 10000 ) –

    The number of operations limit for the verification.

Returns:

  • bool –

    True if the password matches the stored hash, False otherwise.

Raises:

  • ValueError –

    If the password or stored hash is None, empty, or if the stored hash is not 128 bytes long.

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.