py2crypt 1.0

This library provides a top-level interface to the cryptography.io module.

1. AES

The AES class uses the AES-CTR algorithm (counter mode) to encrypt and decrypt data.

1.1. AES methods & parameters

AES(key: bytes)

The required key parameter of AES class must be bytes type and will be used to encrypt or decrypt data.

AES(key: bytes).encrypt(plaintext: bytes) -> bytes

The encrypt method is used to encrypt data and return a bytes type object that contains the ciphertext of the plaintext parameter.

AES(key: bytes).decrypt(ciphertext: bytes) -> bytes

The decrypt method is used to decrypt data and return a bytes type object that contains the plaintext of the ciphertext parameter.

1.2. AES useful variables

There are three possible lengths of keys for AES: 128-bit, 192-bit, and 256-bit. The constants AES128_SIZE, AES192_SIZE, AES256_SIZE hold those values. The constant IV_SIZE holds the length of the IV.

These constants can be imported directly from the library .

1.3. AES example

from py2crypt import AES, AES256_SIZE
from os import urandom

plain_text = b'Hello World!'
shared_key = urandom(AES256_SIZE)

sender = AES(shared_key)
receiver = AES(shared_key)

encrypted_text = sender.encrypt(plain_text)
decrypted_text = receiver.decrypt(encrypted_text)

print('Encrypted message:', encrypted_text.hex())
print('Decrypted message:', decrypted_text.decode('utf-8'))

The output:

Encrypted message: 6875fdb9774b10c5ca8aa51ac0f75662926552fb2320fa53d6345bb6c09d20
Decrypted message: Hello World!

2. ECDH

The ECDH class is used to exchange keys using Elliptic Curve Diffie-Hellman algorithm.

2.1. ECDH curves

All curves can be imported directly from the library.

SECP192R1: NIST P-192

SECP224R1: NIST P-224

SECP256R1: NIST P-256

SECP384R1: NIST P-384

SECP521R1: NIST P-521

2.2. ECDH methods & parameters

The ECDH class uses by default the SECP521R1 curve (NIST P-521), but others can be used instead:

from py2crypt import ECDH, SECP192R1, SECP224R1, SECP256R1, SECP384R1, SECP521R1

dh = ECDH(SECP256R1)

ECDH.private_key() -> _EllipticCurvePrivateKey

The private_key method is used to return the private key object.

ECDH.public_key() -> _EllipticCurvePublicKey

The public_key method is used to return the public key object.

ECDH.exchange(public_key: _EllipticCurvePublicKey) -> bytes

The exchange method requires the public_key parameter (the peer public key) that must be the same object type returned by the public_key method.

2.3. ECDH example

from py2crypt import ECDH

alice = ECDH()
bob = ECDH()

alice_key = alice.exchange(bob.public_key())
bob_key = bob.exchange(alice.public_key())

print('Alice key:', alice_key.hex())
print('Bob key:', bob_key.hex())

The output:

Alice key: 01ae679b954c796ed030e0b658e20f8670d1bcea9778508b4036a91849353b9b4567723fe7a360612f355bb362bcbbc1885ada0aaea76ada2b71278bfc6d32a19be2
Bob key: 01ae679b954c796ed030e0b658e20f8670d1bcea9778508b4036a91849353b9b4567723fe7a360612f355bb362bcbbc1885ada0aaea76ada2b71278bfc6d32a19be2

3. HKDF

HKDF converts a secret into key material suitable for use in encryption, integrity checking or authentication. It is suitable for deriving keys of a fixed size used for other cryptographic operations.

3.1. HKDF methods & parameters

HKDF(info: bytes, length: int = 32)

The info parameter objective is to bind the derived key material to application. It is not recommended using it as a salt.

The length parameter specify the length to the output of the derived material. The default value is 32.

HKDF.derive(material: bytes, salt: bytes|None = None)

The material parameter is the input key material.

The salt parameter must be randomly generated or defined as None.

3.2. HKDF useful variables

You may want to change the default digest algorithm. It is possible to use SHA256, SHA384, and SHA512. The default digest is SHA512.

3.3. HKDF example

from py2crypt import HKDF, SHA256, SHA384, SHA512

key = b'Material for KDF'

kdf = HKDF(info = b'HKDF', length = 32)

# Define SHA256 as the digest
kdf.digest = SHA256()

print('HKDF:', kdf.derive(key).hex())
print('HKDF salted:', kdf.derive(key, salt=b'salt').hex())

The output:

HKDF: 5acb02152e347b8d4515af7c4b99d050f75998354ea32df299f8f344044d58ff
HKDF salted: dcb3c321cc90f67bbb642db33a1bad0332f0632c7a6fa8b4d821021d9f4dfbdb

4. HKDFExpand

HKDF consists of two stages, extract and expand. This class exposes an expand only version of HKDF that is suitable when the key material is already cryptographically strong. HKDFExpand should only be used if the key material is cryptographically strong. You should use HKDF if you are unsure.

4.1. HKDFExpand methods & parameters

HKDFExpand(info: bytes, length: int = 32)

The info parameter objective is to bind the derived key material to application. It is not recommended using it as a salt.

The length parameter specify the length to the output of the derived material. The default value is 32.

HKDFExpand.derive(material: bytes)

The material parameter is the input key material.

4.2. HKDFExpand example

from py2crypt import HKDFExpand, SHA256, SHA384, SHA512

key = b'Material for KDF'

kdf = HKDFExpand(info=b'HKDF', length=64)

# Define SHA256 as the digest
kdf.digest = SHA256()

print('HKDF expanded:', kdf.derive(key).hex())

The output:

HKDF expanded: 69b89488c7a33d4a2a129be7e5bb3f22ed395029ea6d61c97f6a67565a31eff45ed24bb7f24ba2eb3a1bd4dd22110e849caad5b710aeac328857ac7c0979c667

5. HMAC

HMAC may be used to simultaneously verify both the data integrity and authenticity of a message.

5.1. HMAC methods & parameters

HMAC(key: bytes)

The key is a bytes object giving the secret key.

HMAC.digest(message: bytes)

The digest method return digest of message for given secret key and digest.

5.2. HMAC useful variables

You may want to change the default digest algorithm. It is possible to use sha256, sha384, and sha512. The default digest is sha512.

5.3. hmac_compare

hmac_compare(message: bytes, key: bytes, hmac: bytes, digest=sha512)

It will compare the digest of message for given secret key and digest with another hmac.

5.4. HMAC examples

from py2crypt import HMAC, hmac_compare, sha256, sha384, sha512

shared_key = b'ThisIsASecret'
message = b'The message'

hmac = HMAC(shared_key)

# Define sha256 as the digest
hmac.hash_algorithm = sha256

hmac_digest = hmac.digest(message)

print('HMAC:', hmac_digest.hex())
print('Is valid?', hmac_compare(message, shared_key, hmac_digest, sha256))

The output:

HMAC: 71fa6d82dba7ee1653c4a524f948a9ffd3ed97f3edf1fa39806da0e7d6639cb9
Is valid? True

6. RSA

Generates a local wallet that contains an RSA Private Key.

6.1. RSA methods & parameters

RSA(private_key = None, length: int = 4096)

Use a previous generated RSA private key in private_key parameter or set as None. The length parameter defines the length of the private key it will generate if private key parameter is None.

RSA.private_key()

Return the private key object.

RSA.public_key()

Return the private key object.

RSA.encrypt(public_key, plaintext: bytes) -> bytes

Encrypt plaintext using a giving public_key.

RSA.decrypt(ciphertext: bytes) -> bytes

Decrypt ciphertext using the object private key.

RSA.sign(content: bytes)

Sign content using the object private key. The content will be hashed using the algorithm specified in hash_algorithm (default is SHA512).

RSA.verify(public_key, signature: bytes, content: bytes) -> bool

Verify the signature of the content using the giving public_key.

6.2. RSA useful variables

You may want to change the default digest algorithm. It is possible to use SHA256, SHA384, and SHA512. The default digest is SHA512.

6.3. RSA example

from py2crypt import RSA, SHA256, SHA384, SHA512

alice = RSA()
alice.hash_algorithm = SHA256()

bob = RSA()
bob.hash_algorithm = SHA256()

alice_encrypts_msg = alice.encrypt(bob.public_key(), b'Hello bob')
print('Alice encrypted msg:', alice_encrypts_msg.hex()[::6], end='\n\n')

alice_sign_msg = alice.sign(alice_encrypts_msg)
print('Alice signature:', alice_sign_msg.hex()[::6], end='\n\n')

bob_checks_alice_signature = bob.verify(alice.public_key(), alice_sign_msg, alice_encrypts_msg)
print('Is signature valid?', bob_checks_alice_signature, end='\n\n')

bob_decrypts_alice_msg = bob.decrypt(alice_encrypts_msg)
print('Bob decrypts msg:', bob_decrypts_alice_msg)

The output:

Alice encrypted msg: 526c76786a777df93dea64ad09c07d36d73926d27682ecf6149a83c885765dfaeb035676fbf590948c29b52376cbb3fd358b655ce1e2e19bfcba4ff7b7100e0ac65d8f8f3ef435d63efd04d50734be479027b812f27

Alice signature: 9c311b10a4613ef8bd78813fc6c320b8b859c5fdf3256c42910bc77477126eebbb9a17425a7692560d711f6df1a00bc1e8f5409362057243b8a0e000bc414d509ae6936616e8c33b96e36221fc590d74f05101c0b09

Is signature valid? True

Bob decrypts msg: b'Hello bob'

7. Import/Export

export_private_key(private_key) -> bytes

Export a private key object as a bytes type.

export_public_key(public_key) -> bytes

Export a public key object as a bytes type.

import_private_key(private_key: bytes)

Import a bytes type private key as a private key object.

import_public_key(public_key: bytes)

Import a bytes type public key as a public key object.

7.1. Import/Export examples

from py2crypt import RSA, export_private_key, export_public_key, import_private_key, import_public_key

rsa = RSA()

output_private_key = export_private_key(rsa.private_key())
output_public_key = export_public_key(rsa.public_key())

input_private_key = import_private_key(output_private_key)
input_public_key = import_public_key(output_public_key)

print('output_private_key:', type(output_private_key))
print('output_public_key:', type(output_public_key))
print('input_private_key:', type(input_private_key))
print('input_public_key:', type(input_public_key))

The output:

output_private_key: <class 'bytes'>
output_public_key: <class 'bytes'>
input_private_key: <class 'cryptography.hazmat.backends.openssl.rsa._RSAPrivateKey'>
input_public_key: <class 'cryptography.hazmat.backends.openssl.rsa._RSAPublicKey'>