age.primitives package

Submodules

age.primitives.bech32 module

Reference implementation for Bech32 and segwit addresses.

age.primitives.bech32.bech32_decode(bech)

Validate a Bech32 string, and determine HRP and data.

Parameters

bech (str) –

Return type

Tuple[str, bytes]

age.primitives.bech32.bech32_encode(hrp, payload)

Compute a Bech32 string given HRP and data values.

Parameters
Return type

str

age.primitives.encode module

age.primitives.encode.decode(data)

Decode base64url (RFC 4648) encoded text

Parameters

data (str) – Base64-encoded data

Return type

bytes

Returns

Raw data

Raises

  • TypeError – if data is not a string

  • ValueError – if base64-decoding fails (e.g. if data contains non-base64 characters)

>>> decode('dGVzdA')
b'test'
age.primitives.encode.encode(data)

Encode data to base64url (RFC 4648) text

Parameters

data (bytes) – Raw data

Return type

str

Returns

Base64-encoded data

Raises

TypeError – if data is not a bytes instance

>>> encode(b'test')
'dGVzdA'

age.primitives.encrypt module

age.primitives.encrypt.decrypt(key, ciphertext)

Decrypt plaintext with the 32 byte key ChaCha20 + Poly1305 (RFC 7539) using a zero nonce.

Parameters

  • key (bytes) – 32-byte key

  • ciphertext (bytes) – Ciphertext

Return type

bytes

Returns

Decrypted data

Raises

cryptography.exceptions.InvalidTag – if authentication fails

age.primitives.encrypt.encrypt(key, plaintext)

Encrypt plaintext with the 32 byte key using ChaCha20 + Poly1305 (RFC 7539) using a zero nonce.

Parameters

  • key (bytes) – 32-byte key

  • plaintext (bytes) – Data to encrypt

Return type

bytes

Returns

Ciphertext

age.primitives.hashes module

age.primitives.hashes.sha256(data)

Compute the SHA-256 digest

Parameters

data (bytes) – Data to hash

Return type

bytes

Returns

Raw digest (32 byte)

>>> h = sha256(b'test')
>>> len(h)
32
>>> h.hex()
'9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08'

age.primitives.hkdf module

age.primitives.hkdf.hkdf(salt, label, key, len)

Derive a key of len len using HKDF (RFC 5869) using HMAC SHA-256

Parameters

  • salt (bytes) – Salt

  • label (bytes) – Label

  • key (bytes) – Key

  • len (int) – Length of key to generate

Return type

bytes

Returns

Key of length len

>>> key = hkdf(b'', b'label', b'secret', 16)
>>> len(key)
16
>>> key.hex()
'112fefb269ce7dcb2ea6c7e952c104c1'

age.primitives.hmac module

class age.primitives.hmac.HMAC(key)

Bases: object

HMAC-SHA256 from RFC 2104

Parameters

key (bytes) – Shared symmetrical key, used for authentication, needed for authentication checks

generate(message)

Generate authentication value for the given message

Parameters

message (bytes) – Message to authenticate

Return type

bytes

Returns

32-byte authentication tag (HMAC)

is_valid(message, tag)

Check whether authentication value for the given message is correct (returning the authentication result)

Parameters
Return type

bool

Returns

True if validation succeeds, False otherwise

verify(message, tag)

Verify authentication value for the given message (raising an exception on failure)

Parameters
Raises

cryptography.exceptions.InvalidSignature – on failed validation

Return type

None

age.primitives.random module

age.primitives.random.random(n)

Generate n random bytes suitable for cryptographic use

Implemented through os.urandom()

Parameters

n (int) – Number of random bytes to generate

Return type

bytes

Returns

Random bytes

age.primitives.rsa_oaep module

age.primitives.rsa_oaep.rsa_decrypt(private_key, label, ciphertext)

Deccrypt ciphertext using RSA with OAEP padding (RFC 8017)

Parameters
Return type

bytes

Returns

Plaintext

Raises

ValueError – if decryption fails

age.primitives.rsa_oaep.rsa_encrypt(public_key, label, plaintext)

Encrypt plaintext using RSA with OAEP padding (RFC 8017)

Parameters

  • public_key (RSAPublicKey) – Public key to encrypt to

  • label (bytes) – Extra data, stored in OAEP padding

  • plaintext (bytes) – Data to encrypt

Return type

bytes

Returns

Ciphertext

age.primitives.scrypt module

age.primitives.scrypt.scrypt(salt, N, password)

Derive a key from password and salt

For the choise of N, see https://blog.filippo.io/the-scrypt-parameters/.

Parameters

  • salt (bytes) – Salt

  • N (int) – Scrypt cost

  • password (bytes) – Password

Return type

bytes

age.primitives.x25519 module

age.primitives.x25519.ECPoint

Curve25519 point (commonly called P), as bytes instance of length 32

alias of bytes

age.primitives.x25519.ECScalar

Curve25519 scalar (commonly called n), as bytes instance of length 32

alias of bytes

age.primitives.x25519.x25519_reduce(k)

Reduce the scalar k in the Curve25519 field

Corresponds to the following calculation: \(r = k % (2^252 + \text{0x14DEF9DEA2F79CD65812631A5CF5D3ED})\)

Parameters

k (NewType()(ECScalar, bytes)) – Arbitrary scalar in bytes representation (ECScalar)

Return type

NewType()(ECScalar, bytes)

Returns

Reduced scalar in bytes representation (ECScalar)

age.primitives.x25519.x25519_scalarmult(secret_scalar, point)

Scalar multiplication of point with (secret) scalar

Parameters
Return type

NewType()(ECPoint, bytes)

Returns

New point on curve: \(nP = P + P + P + P + P + \text{...}\) (n times)

age.primitives.x25519.x25519_scalarmult_base(scalar)

Scalar multiplication of the ED25519 base point with scalar

The base point according to the Curve25519 paper is \(P = 9\). This function is commonly used to generate a public key (point) from a private scalar.

Parameters

scalar (NewType()(ECScalar, bytes)) – Scalar (integer) n, in byte representation (ECScalar)

Return type

NewType()(ECPoint, bytes)

Returns

Point on curve, commonly interpreted as public key (if n is the private key)

Module contents

This module defines encryption primitives used within age