Single-shot API

Single-shot seal/open and export APIs (RFC 9180 §6).

class rfc9180.single_shot.HPKESingleShot(setup)[source]

Bases: object

Single-shot HPKE APIs (RFC 9180 §6).

Provides convenient single-shot encryption/decryption operations that combine setup and encryption/decryption in one call.

Parameters:

setup (HPKESetup) – HPKE setup instance for context creation.

setup

HPKE setup instance.

Type:

HPKESetup

__init__(setup)[source]
seal_base(pkR, info, aad, pt)[source]

Seal (encrypt) a message using Base mode.

Parameters:

  • pkR (Key Object) – Recipient’s public key.

  • info (bytes) – Application-supplied information.

  • aad (bytes) – Additional authenticated data.

  • pt (bytes) – Plaintext to encrypt.

Returns:

Tuple of (encapsulated key, ciphertext).

Return type:

tuple

open_base(enc, skR, info, aad, ct)[source]

Open (decrypt) a message using Base mode.

Parameters:

  • enc (bytes) – Encapsulated public key.

  • skR (Key Object) – Recipient’s private key.

  • info (bytes) – Application-supplied information.

  • aad (bytes) – Additional authenticated data.

  • ct (bytes) – Ciphertext to decrypt.

Returns:

Decrypted plaintext.

Return type:

bytes

Raises:

OpenError – If decryption fails.

seal_psk(pkR, info, aad, pt, psk, psk_id)[source]

Seal (encrypt) a message using PSK mode.

Parameters:

  • pkR (Key Object) – Recipient’s public key.

  • info (bytes) – Application-supplied information.

  • aad (bytes) – Additional authenticated data.

  • pt (bytes) – Plaintext to encrypt.

  • psk (bytes) – Pre-shared key (must have at least 32 bytes of entropy).

  • psk_id (bytes) – Pre-shared key identifier.

Returns:

Tuple of (encapsulated key, ciphertext).

Return type:

tuple

Raises:

ValueError – If PSK has insufficient entropy.

open_psk(enc, skR, info, aad, ct, psk, psk_id)[source]

Open (decrypt) a message using PSK mode.

Parameters:

  • enc (bytes) – Encapsulated public key.

  • skR (Key Object) – Recipient’s private key.

  • info (bytes) – Application-supplied information.

  • aad (bytes) – Additional authenticated data.

  • ct (bytes) – Ciphertext to decrypt.

  • psk (bytes) – Pre-shared key (must have at least 32 bytes of entropy).

  • psk_id (bytes) – Pre-shared key identifier.

Returns:

Decrypted plaintext.

Return type:

bytes

Raises:
seal_auth(pkR, info, aad, pt, skS)[source]

Seal (encrypt) a message using Auth mode.

Parameters:

  • pkR (Key Object) – Recipient’s public key.

  • info (bytes) – Application-supplied information.

  • aad (bytes) – Additional authenticated data.

  • pt (bytes) – Plaintext to encrypt.

  • skS (Key Object) – Sender’s private key.

Returns:

Tuple of (encapsulated key, ciphertext).

Return type:

tuple

open_auth(enc, skR, info, aad, ct, pkS)[source]

Open (decrypt) a message using Auth mode.

Parameters:

  • enc (bytes) – Encapsulated public key.

  • skR (Key Object) – Recipient’s private key.

  • info (bytes) – Application-supplied information.

  • aad (bytes) – Additional authenticated data.

  • ct (bytes) – Ciphertext to decrypt.

  • pkS (Key Object) – Sender’s public key.

Returns:

Decrypted plaintext.

Return type:

bytes

Raises:

OpenError – If decryption fails.

seal_auth_psk(pkR, info, aad, pt, psk, psk_id, skS)[source]

Seal (encrypt) a message using AuthPSK mode.

Parameters:

  • pkR (Key Object) – Recipient’s public key.

  • info (bytes) – Application-supplied information.

  • aad (bytes) – Additional authenticated data.

  • pt (bytes) – Plaintext to encrypt.

  • psk (bytes) – Pre-shared key (must have at least 32 bytes of entropy).

  • psk_id (bytes) – Pre-shared key identifier.

  • skS (Key Object) – Sender’s private key.

Returns:

Tuple of (encapsulated key, ciphertext).

Return type:

tuple

Raises:

ValueError – If PSK has insufficient entropy.

open_auth_psk(enc, skR, info, aad, ct, psk, psk_id, pkS)[source]

Open (decrypt) a message using AuthPSK mode.

Parameters:

  • enc (bytes) – Encapsulated public key.

  • skR (Key Object) – Recipient’s private key.

  • info (bytes) – Application-supplied information.

  • aad (bytes) – Additional authenticated data.

  • ct (bytes) – Ciphertext to decrypt.

  • psk (bytes) – Pre-shared key (must have at least 32 bytes of entropy).

  • psk_id (bytes) – Pre-shared key identifier.

  • pkS (Key Object) – Sender’s public key.

Returns:

Decrypted plaintext.

Return type:

bytes

Raises:
send_export_base(pkR, info, exporter_context, L)[source]

Export a secret using Base mode (sender side).

Parameters:

  • pkR (Key Object) – Recipient’s public key.

  • info (bytes) – Application-supplied information.

  • exporter_context (bytes) – Exporter context.

  • L (int) – Length of exported secret in bytes.

Returns:

Tuple of (encapsulated key, exported secret).

Return type:

tuple

receive_export_base(enc, skR, info, exporter_context, L)[source]

Export a secret using Base mode (recipient side).

Parameters:

  • enc (bytes) – Encapsulated public key.

  • skR (Key Object) – Recipient’s private key.

  • info (bytes) – Application-supplied information.

  • exporter_context (bytes) – Exporter context.

  • L (int) – Length of exported secret in bytes.

Returns:

Exported secret.

Return type:

bytes

send_export_psk(pkR, info, exporter_context, L, psk, psk_id)[source]

Export a secret using PSK mode (sender side).

Parameters:

  • pkR (Key Object) – Recipient’s public key.

  • info (bytes) – Application-supplied information.

  • exporter_context (bytes) – Exporter context.

  • L (int) – Length of exported secret in bytes.

  • psk (bytes) – Pre-shared key (must have at least 32 bytes of entropy).

  • psk_id (bytes) – Pre-shared key identifier.

Returns:

Tuple of (encapsulated key, exported secret).

Return type:

tuple

Raises:

ValueError – If PSK has insufficient entropy.

receive_export_psk(enc, skR, info, exporter_context, L, psk, psk_id)[source]

Export a secret using PSK mode (recipient side).

Parameters:

  • enc (bytes) – Encapsulated public key.

  • skR (Key Object) – Recipient’s private key.

  • info (bytes) – Application-supplied information.

  • exporter_context (bytes) – Exporter context.

  • L (int) – Length of exported secret in bytes.

  • psk (bytes) – Pre-shared key (must have at least 32 bytes of entropy).

  • psk_id (bytes) – Pre-shared key identifier.

Returns:

Exported secret.

Return type:

bytes

Raises:

ValueError – If PSK has insufficient entropy.

send_export_auth(pkR, info, exporter_context, L, skS)[source]

Export a secret using Auth mode (sender side).

Parameters:

  • pkR (Key Object) – Recipient’s public key.

  • info (bytes) – Application-supplied information.

  • exporter_context (bytes) – Exporter context.

  • L (int) – Length of exported secret in bytes.

  • skS (Key Object) – Sender’s private key.

Returns:

Tuple of (encapsulated key, exported secret).

Return type:

tuple

receive_export_auth(enc, skR, info, exporter_context, L, pkS)[source]

Export a secret using Auth mode (recipient side).

Parameters:

  • enc (bytes) – Encapsulated public key.

  • skR (Key Object) – Recipient’s private key.

  • info (bytes) – Application-supplied information.

  • exporter_context (bytes) – Exporter context.

  • L (int) – Length of exported secret in bytes.

  • pkS (Key Object) – Sender’s public key.

Returns:

Exported secret.

Return type:

bytes

send_export_auth_psk(pkR, info, exporter_context, L, psk, psk_id, skS)[source]

Export a secret using AuthPSK mode (sender side).

Parameters:

  • pkR (Key Object) – Recipient’s public key.

  • info (bytes) – Application-supplied information.

  • exporter_context (bytes) – Exporter context.

  • L (int) – Length of exported secret in bytes.

  • psk (bytes) – Pre-shared key (must have at least 32 bytes of entropy).

  • psk_id (bytes) – Pre-shared key identifier.

  • skS (Key Object) – Sender’s private key.

Returns:

Tuple of (encapsulated key, exported secret).

Return type:

tuple

Raises:

ValueError – If PSK has insufficient entropy.

receive_export_auth_psk(enc, skR, info, exporter_context, L, psk, psk_id, pkS)[source]

Export a secret using AuthPSK mode (recipient side).

Parameters:

  • enc (bytes) – Encapsulated public key.

  • skR (Key Object) – Recipient’s private key.

  • info (bytes) – Application-supplied information.

  • exporter_context (bytes) – Exporter context.

  • L (int) – Length of exported secret in bytes.

  • psk (bytes) – Pre-shared key (must have at least 32 bytes of entropy).

  • psk_id (bytes) – Pre-shared key identifier.

  • pkS (Key Object) – Sender’s public key.

Returns:

Exported secret.

Return type:

bytes

Raises:

ValueError – If PSK has insufficient entropy.