Verified Commit 73d9520e authored by Pavol Žáčik's avatar Pavol Žáčik
Browse files

Polish docs of the symmetric module

parent cf79eb41

pv080_crypto/symmetric.py

+22 −23
Original line number Diff line number Diff line
@@ -210,8 +210,8 @@ def chacha20_encrypt(key: bytes, nonce: bytes, plaintext: bytes) -> bytes: 
    """

    Use ChaCha20 to encrypt ``plaintext`` using ``key`` and ``nonce``.



    :param key: The bytes of the key (size 32 bytes)

    :param nonce: The bytes of the nonce (size 16 bytes)

    :param key: The bytes of the key (size 32 bytes).

    :param nonce: The bytes of the nonce (size 16 bytes).



    :returns: The bytes of the ciphertext.
@@ -231,8 +231,8 @@ def chacha20_decrypt(key: bytes, nonce: bytes, ciphertext: bytes) -> bytes: 
    """

    Use ChaCha20 to decrypt ``ciphertext`` using ``key`` and ``nonce``.



    :param key: The bytes of the key (size 32 bytes)

    :param nonce: The bytes of the nonce (size 16 bytes)

    :param key: The bytes of the key (size 32 bytes).

    :param nonce: The bytes of the nonce (size 16 bytes).



    :returns: The bytes of the plaintext.
@@ -250,13 +250,13 @@ def chacha20_decrypt(key: bytes, nonce: bytes, ciphertext: bytes) -> bytes: 
    return decryptor.update(ciphertext) + decryptor.finalize()





# FIXME 2023: unify key, message vs key, plaintext in RSA

def aes_encrypt(key: bytes, message: bytes) -> bytes:

def aes_encrypt(key: bytes, plaintext: bytes) -> bytes:

    """

    Use AES-CBC to encrypt ``message`` using ``key``.

    Use AES-CBC to encrypt ``plaintext`` using ``key``. The function also

    appends PKCS#7 padding and prepends a random IV to the ciphertext.



    :param key: The bytes of the key (16, 24, 32 bytes in size).

    :param message: The message bytes to be encrypted.

    :param key: The bytes of the key (16, 24, or 32 bytes in size).

    :param plaintext: The plaintext bytes to be encrypted.



    :returns: The bytes of the ciphertext.
@@ -264,10 +264,10 @@ def aes_encrypt(key: bytes, message: bytes) -> bytes: 


    >>> import secrets

    >>> key = secrets.token_bytes(16)

    >>> ciphertext = aes_encrypt(key=key, message=b"my message")

    >>> ciphertext = aes_encrypt(key=key, plaintext=b"my message")

    """

    padder = padding_symmetric.PKCS7(128).padder()

    padded_msg = padder.update(message) + padder.finalize()

    padded_msg = padder.update(plaintext) + padder.finalize()



    iv = secrets.token_bytes(16)

    cipher = Cipher(algorithms.AES(key=key), mode=modes.CBC(iv))
@@ -277,14 +277,13 @@ def aes_encrypt(key: bytes, message: bytes) -> bytes: 
    return iv + ciphertext





# FIXME argument is ciphertext, but the docs say message

def aes_decrypt(key: bytes, ciphertext: bytes) -> bytes:

    """

    Use AES-CBC to decrypt ``ciphertext`` using ``key``.

    Use AES-CBC to decrypt ``ciphertext`` using ``key``. The ``ciphertext``

    should be encrypted using :py:func:`aes_encrypt <pv080_crypto.symmetric.aes_encrypt>`.





    :param key: The bytes of the key (16, 24, 32 bytes in size).

    :param message: The ciphertext bytes to be decrypted/

    :param key: The bytes of the key (16, 24, or 32 bytes).

    :param ciphertext: The ciphertext bytes to be decrypted.



    :returns: The bytes of the plaintext.
@@ -293,7 +292,7 @@ def aes_decrypt(key: bytes, ciphertext: bytes) -> bytes: 
    >>> import secrets

    >>> key = secrets.token_bytes(16)

    >>> message = b"hello world"

    >>> ciphertext = aes_encrypt(key=key, message=message)

    >>> ciphertext = aes_encrypt(key=key, plaintext=message)

    >>> assert message == aes_decrypt(key=key, ciphertext=ciphertext)

    """

    iv = ciphertext[:16]
@@ -312,10 +311,10 @@ def create_mac(key: bytes, data: bytes) -> bytes: 
    encrypt ``data`` using ``key`` and AES-CBC with initialization vector

    equal to zero bytes.



    :param key: Is the AES symmetric key.

    :param data: Is the data that will be MAC'ed.

    :param key: The bytes of the key (16, 24, or 32 bytes).

    :param data: The data that will be MAC'd.



    :returns: 16 bytes long MAC value.

    :returns: The MAC value (16 bytes).



    Example:
@@ -342,9 +341,9 @@ def verify_mac(key: bytes, data: bytes, mac: bytes) -> bool: 
    """

    Verify that the MAC (using AES-CBC) of ``data`` matches ``mac``.



    :param key: Is the AES symmetric key.

    :param data: Is the data that will be MAC'ed.

    :param mac: Is the value against which we verify.

    :param key: The bytes of the key (16, 24, or 32 bytes).

    :param data: The data that will be MAC'ed.

    :param mac: The value against which we verify (16 bytes).



    :returns: ``True`` if the verification succeeds, ``False`` otherwise.

tests/test_pv080_crypto.py

+1 −1
Original line number Diff line number Diff line
@@ -60,7 +60,7 @@ def test_aes_encrypt_decrypt_roundtrip(key_size: int): 


        key = secrets.token_bytes(key_size)

        # test encrypt/decrypt roundtrip

        ciphertext = aes_encrypt(key=key, message=message)

        ciphertext = aes_encrypt(key=key, plaintext=message)

        plaintext = aes_decrypt(key=key, ciphertext=ciphertext)

        assert message == plaintext