diff options
author | Paul Kehrer <paul.l.kehrer@gmail.com> | 2017-02-16 22:20:38 -0600 |
---|---|---|
committer | Alex Gaynor <alex.gaynor@gmail.com> | 2017-02-16 23:20:38 -0500 |
commit | 9b34ca92c3ac061aee2301728dc1280a83890814 (patch) | |
tree | 250f7f978b69b1b933e2152a76477f0936705c0d /docs/hazmat | |
parent | 83d3adee771593f3b90a74ff2c2e1a7a2d98b668 (diff) | |
download | cryptography-9b34ca92c3ac061aee2301728dc1280a83890814.tar.gz cryptography-9b34ca92c3ac061aee2301728dc1280a83890814.tar.bz2 cryptography-9b34ca92c3ac061aee2301728dc1280a83890814.zip |
add support for update_into on CipherContext (#3190)
* add support for update_into on CipherContext
This allows you to provide your own buffer (like recv_into) to improve
performance when repeatedly calling encrypt/decrypt on large payloads.
* another skip_if
* more skip_if complexity
* maybe do this right
* correct number of args
* coverage for the coverage gods
* add a cffi minimum test tox target and travis builder
This tests against macOS so we capture some commoncrypto branches
* extra arg
* need to actually install py35
* fix
* coverage for GCM decrypt in CC
* no longer relevant
* 1.8 now
* pep8
* dramatically simplify
* update docs
* remove unneeded test
* changelog entry
* test improvements
* coverage fix
* add some comments to example
* move the comments to their own line
* fix and move comment
Diffstat (limited to 'docs/hazmat')
-rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 43 |
1 files changed, 43 insertions, 0 deletions
diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 24b2c045..1fd5a546 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -456,6 +456,49 @@ Interfaces return bytes immediately, however in other modes it will return chunks whose size is determined by the cipher's block size. + .. method:: update_into(data, buf) + + .. versionadded:: 1.8 + + .. warning:: + + This method allows you to avoid a memory copy by passing a writable + buffer and reading the resulting data. You are responsible for + correctly sizing the buffer and properly handling the data. This + method should only be used when extremely high performance is a + requirement and you will be making many small calls to + ``update_into``. + + :param bytes data: The data you wish to pass into the context. + :param buf: A writable Python buffer that the data will be written + into. This buffer should be ``len(data) + n - 1`` bytes where ``n`` + is the block size (in bytes) of the cipher and mode combination. + :return int: Number of bytes written. + :raises NotImplementedError: This is raised if the version of ``cffi`` + used is too old (this can happen on older PyPy releases). + :raises ValueError: This is raised if the supplied buffer is too small. + + .. doctest:: + + >>> import os + >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes + >>> from cryptography.hazmat.backends import default_backend + >>> backend = default_backend() + >>> key = os.urandom(32) + >>> iv = os.urandom(16) + >>> cipher = Cipher(algorithms.AES(key), modes.CBC(iv), backend=backend) + >>> encryptor = cipher.encryptor() + >>> # the buffer needs to be at least len(data) + n - 1 where n is cipher/mode block size in bytes + >>> buf = bytearray(31) + >>> len_encrypted = encryptor.update_into(b"a secret message", buf) + >>> # get the ciphertext from the buffer reading only the bytes written to it (len_encrypted) + >>> ct = bytes(buf[:len_encrypted]) + encryptor.finalize() + >>> decryptor = cipher.decryptor() + >>> len_decrypted = decryptor.update_into(ct, buf) + >>> # get the plaintext from the buffer reading only the bytes written (len_decrypted) + >>> bytes(buf[:len_decrypted]) + decryptor.finalize() + 'a secret message' + .. method:: finalize() :return bytes: Returns the remainder of the data. |