aboutsummaryrefslogtreecommitdiffstats
path: root/docs/hazmat/primitives/symmetric-encryption.rst
diff options
context:
space:
mode:
authorPaul Kehrer <paul.l.kehrer@gmail.com>2017-02-16 22:20:38 -0600
committerAlex Gaynor <alex.gaynor@gmail.com>2017-02-16 23:20:38 -0500
commit9b34ca92c3ac061aee2301728dc1280a83890814 (patch)
tree250f7f978b69b1b933e2152a76477f0936705c0d /docs/hazmat/primitives/symmetric-encryption.rst
parent83d3adee771593f3b90a74ff2c2e1a7a2d98b668 (diff)
downloadcryptography-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/primitives/symmetric-encryption.rst')
-rw-r--r--docs/hazmat/primitives/symmetric-encryption.rst43
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.