openssh_key.cipher.integrity.ChaCha20Poly1305Cipher

class openssh_key.cipher.integrity.ChaCha20Poly1305Cipher

Bases: openssh_key.cipher.integrity.ConfidentialityIntegrityCipher

The ChaCha20 encryption algorithm with a Poly1305 authentication tag.

When encrypting private keys, OpenSSH uses only the first 32 bytes of the 64-byte key derived from the key derivation function as the ChaCha20 encryption key; then it proceeds as in RFC 8439 section 2.8, except that:

  • the nonce is replaced by the constant byte string of sixteen zero bytes

  • there are no additional authenticated data

  • the Poly1305 authentication tag is computed on a message that consists of only the ciphertext (in particular, OpenSSH does not add padding or encode message lengths to compute the Poly1305 authentication tag).

__init__()

Methods

__init__()

decrypt(kdf, passphrase, cipher_bytes)

Decrypts the given ciphertext bytes using the given options of a key derivation function and the given passphrase to derive the encryption key.

decrypt_with_key_iv(cipher_bytes, ...)

Decrypts the given ciphertext bytes using the given cipher key and initialization vector.

encrypt(kdf, passphrase, plain_bytes)

Encrypts the given plaintext bytes using the given options of a key derivation function and the given passphrase to derive the encryption key.

encrypt_with_key_iv(plain_bytes, cipher_key, ...)

Encrypts the given plaintext bytes using the given cipher key and initialization vector.

get_block_size()

The value 8, the block size in bytes of the ChaCha20Poly1305 cipher for padding ciphertext.

get_chacha20_cipher_text_block_size()

The value 64, the block size in bytes of the ChaCha20 encryption algorithm.

get_chacha20_initial_counter_nonce()

The byte string consisting of sixteen zero bytes.

get_chacha20_key_length()

The value 32, the length in bytes of the ChaCha20 encryption key.

get_iv_length()

The value 0.

get_key_length()

The value 64, the length in bytes of the key obtained from the key derivation function.

get_poly1305_key_length()

The value 32, the length in bytes of the Poly1305 key.

get_tag_length()

The value 16, the Poly1305 tag length in bytes.

Attributes

BLOCK_SIZE

The block size for this cipher.

CHACHA20_CIPHER_TEXT_BLOCK_SIZE

The value 64, the block size in bytes of the ChaCha20 encryption algorithm.

CHACHA20_INITIAL_COUNTER_NONCE

The byte string consisting of sixteen zero bytes.

CHACHA20_KEY_LENGTH

The value 32, the length in bytes of the ChaCha20 encryption key.

IV_LENGTH

The initialization vector length for this cipher in bytes.

KEY_LENGTH

The key length for this cipher in bytes.

POLY1305_KEY_LENGTH

The value 32, the length in bytes of the Poly1305 key.

TAG_LENGTH

The length of the authentication tag of this cipher in bytes.
CHACHA20_CIPHER_TEXT_BLOCK_SIZE = 64

The value 64, the block size in bytes of the ChaCha20 encryption algorithm.

CHACHA20_INITIAL_COUNTER_NONCE = b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00'

The byte string consisting of sixteen zero bytes.

When encrypting private keys, OpenSSH replaces the ChaCha20 nonce by the constant byte string consisting of sixteen zero bytes. Therefore, no initialization vector needs to be obtained from the key derivation function.

CHACHA20_KEY_LENGTH = 32

The value 32, the length in bytes of the ChaCha20 encryption key.

POLY1305_KEY_LENGTH = 32

The value 32, the length in bytes of the Poly1305 key.

classmethod decrypt(kdf, passphrase, cipher_bytes)

Decrypts the given ciphertext bytes using the given options of a key derivation function and the given passphrase to derive the encryption key.

Parameters

  • kdf (KDFOptions) – The options of a key derivation function.

  • passphrase (str) – The passphrase from which the cipher key is derived.

  • cipher_bytes (bytes) – Ciphertext bytes to be decrypted.

Return type

bytes

Returns

Plaintext bytes.

classmethod decrypt_with_key_iv(cipher_bytes, cipher_key, initialization_vector)

Decrypts the given ciphertext bytes using the given cipher key and initialization vector.

Parameters

  • cipher_bytes (bytes) – Ciphertext bytes to be encrypted.

  • cipher_key (bytes) – The cipher key.

  • initialization_vector (bytes) – The initialization vector. For some ciphers, this need only be a nonce.

Return type

bytes

Returns

Plaintext bytes.

classmethod encrypt(kdf, passphrase, plain_bytes)

Encrypts the given plaintext bytes using the given options of a key derivation function and the given passphrase to derive the encryption key.

Parameters

  • kdf (KDFOptions) – The options of a key derivation function.

  • passphrase (str) – The passphrase from which the cipher key is derived.

  • plain_bytes (bytes) – Plaintext bytes to be encrypted.

Return type

bytes

Returns

Ciphertext bytes.

classmethod encrypt_with_key_iv(plain_bytes, cipher_key, initialization_vector)

Encrypts the given plaintext bytes using the given cipher key and initialization vector.

Parameters

  • plain_bytes (bytes) – Plaintext bytes to be encrypted.

  • cipher_key (bytes) – The cipher key.

  • initialization_vector (bytes) – The initialization vector. For some ciphers, this need only be a nonce.

Return type

bytes

Returns

Ciphertext bytes.

classmethod get_block_size()

The value 8, the block size in bytes of the ChaCha20Poly1305 cipher for padding ciphertext.

Return type

int

classmethod get_chacha20_cipher_text_block_size()

The value 64, the block size in bytes of the ChaCha20 encryption algorithm.

Return type

int

classmethod get_chacha20_initial_counter_nonce()

The byte string consisting of sixteen zero bytes.

When encrypting private keys, OpenSSH replaces the ChaCha20 nonce by the constant byte string consisting of sixteen zero bytes. Therefore, no initialization vector needs to be obtained from the key derivation function.

Return type

bytes

classmethod get_chacha20_key_length()

The value 32, the length in bytes of the ChaCha20 encryption key.

Return type

int

classmethod get_iv_length()

The value 0.

When encrypting private keys, OpenSSH replaces the ChaCha20 nonce by the constant byte string consisting of sixteen zero bytes. Therefore, no initialization vector needs to be obtained from the key derivation function.

Return type

int

classmethod get_key_length()

The value 64, the length in bytes of the key obtained from the key derivation function.

OpenSSH uses only the first 32 bytes as the ChaCha20 encryption key.

Return type

int

classmethod get_poly1305_key_length()

The value 32, the length in bytes of the Poly1305 key.

Return type

int

classmethod get_tag_length()

The value 16, the Poly1305 tag length in bytes.

Return type

int