diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/architecture.rst | 6 | ||||
| -rw-r--r-- | docs/community.rst | 12 | ||||
| -rw-r--r-- | docs/index.rst | 1 | ||||
| -rw-r--r-- | docs/primitives/index.rst | 7 | ||||
| -rw-r--r-- | docs/primitives/symmetric-encryption.rst | 69 |
5 files changed, 87 insertions, 8 deletions
diff --git a/docs/architecture.rst b/docs/architecture.rst index 7b394950..0a9550c0 100644 --- a/docs/architecture.rst +++ b/docs/architecture.rst @@ -8,11 +8,11 @@ Architecture ``cryptography`` has three different layers: -* ``cryptography.c``: This package contains bindings to low level cryptographic - libraries. Our initial target will be OpenSSL. +* ``cryptography.bindings``: This package contains bindings to low level + cryptographic libraries. Our initial target will be OpenSSL. * ``cryptography.primitives``: This packages contains low level algorithms, things like ``AES`` or ``SHA1``. This is implemented on top of - ``cryptography.c``. + ``cryptography.bindings``. * ``cryptography``: This package contains higher level recipes, for example "encrypt and then MAC". This is implemented on top of ``cryptography.primitives``. diff --git a/docs/community.rst b/docs/community.rst index 0cefd279..809ffd12 100644 --- a/docs/community.rst +++ b/docs/community.rst @@ -1,13 +1,15 @@ Community ========= -You can find ``crytography`` all over the web: +You can find ``cryptography`` all over the web: * `Mailing list`_ * `Source code`_ * `Issue tracker`_ -* IRC: ``#crytography-dev`` on ``irc.freenode.net`` +* `Documentation`_ +* IRC: ``#cryptography-dev`` on ``irc.freenode.net`` -.. _`Mailing list`: http://mail.python.org/mailman/listinfo/cryptography-dev -.. _`Source code`: https://github.com/alex/crytopgraphy -.. _`Issue tracker`: https://github.com/alex/crytopgraphy/issues +.. _`Mailing list`: https://mail.python.org/mailman/listinfo/cryptography-dev +.. _`Source code`: https://github.com/alex/cryptography +.. _`Issue tracker`: https://github.com/alex/cryptography/issues +.. _`Documentation`: https://cryptography.readthedocs.org/ diff --git a/docs/index.rst b/docs/index.rst index 28975f30..1d8ffda6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,4 +14,5 @@ Contents: :maxdepth: 2 architecture + primitives/index community diff --git a/docs/primitives/index.rst b/docs/primitives/index.rst new file mode 100644 index 00000000..1066e30e --- /dev/null +++ b/docs/primitives/index.rst @@ -0,0 +1,7 @@ +Primitives +========== + +.. toctree:: + :maxdepth: 1 + + symmetric-encryption diff --git a/docs/primitives/symmetric-encryption.rst b/docs/primitives/symmetric-encryption.rst new file mode 100644 index 00000000..fe074f3e --- /dev/null +++ b/docs/primitives/symmetric-encryption.rst @@ -0,0 +1,69 @@ +Symmetric Encryption +==================== + +Symmetric encryption is a way to encrypt (hide the plaintext value) material +where the encrypter and decrypter both use the same key. + +.. class:: cryptography.primitives.block.BlockCipher(cipher, mode) + + Block ciphers work by encrypting content in chunks, often 64- or 128-bits. + They combine an underlying algorithm (such as AES), with a mode (such as + CBC, CTR, or GCM). A simple example of encrypting content with AES is: + + .. code-block:: pycon + + >>> from cryptography.primitives.block import BlockCipher, cipher, mode, padding + >>> cipher = BlockCipher(cipher.AES(key), mode.CBC(iv, padding.PKCS7())) + >>> cipher.encrypt("my secret message") + cipher.finalize() + # The ciphertext + [...] + + :param cipher: One of the ciphers described below. + :param mode: One of the modes described below. + + ``encrypt()`` should be called repeatedly with new plaintext, and once the + full plaintext is fed in, ``finalize()`` should be called. + + .. method:: encrypt(plaintext) + + :param bytes plaintext: The text you wish to encrypt. + :return bytes: Returns the ciphertext that was added. + + .. method:: finalize() + + :return bytes: Returns the remainder of the ciphertext. + +Ciphers +~~~~~~~ + +.. class:: cryptography.primitives.block.cipher.AES(key) + + AES (Advanced Encryption Standard) is a block cipher standardized by NIST. + AES is both fast, and cryptographically strong. It is a good default + choice for encryption. + + :param bytes key: The secret key, either ``128``, ``192``, or ``256`` bits. + This must be kept secret. + + +Modes +~~~~~ + +.. class:: cryptography.primitives.block.mode.CBC(initialization_vector, padding) + + CBC (Cipher block chaining) is a mode of operation for block ciphers. It is + considered cryptographically strong. + + :param bytes initialization_vector: Must be random bytes. They do not need + to be kept secret (they can be included + in a transmitted message). Must be the + same number of bytes as the + ``block_size`` of the cipher. Do not + reuse an ``initialization_vector`` with + a given ``key``. + :param padding: One of the paddings described below. + +Paddings +~~~~~~~~ + +.. class:: cryptography.primitives.block.padding.PKCS7() |