- API documentation
Crypto.Cipherpackage- Edit on GitHub
Introduction¶
The Crypto.Cipher package contains algorithms for protecting the confidentialityof data.
There are three types of encryption algorithms:
- Symmetric ciphers: all parties use the same key, for bothdecrypting and encrypting data.Symmetric ciphers are typically very fast and can processvery large amount of data.
- Asymmetric ciphers: senders and receivers use different keys.Senders encrypt with public keys (non-secret) whereas receiversdecrypt with private keys (secret).Asymmetric ciphers are typically very slow and can processonly very small payloads. Example: PKCS#1 OAEP (RSA).
- Hybrid ciphers: the two types of ciphers above can be combinedin a construction that inherits the benefits of both.An asymmetric cipher is used to protect a short-livedsymmetric key,and a symmetric cipher (under that key) encryptsthe actual message.
API principles¶
Fig. 1 Generic state diagram for a cipher object
The base API of a cipher is fairly simple:
You instantiate a cipher object by calling the
new()function from the relevant cipher module (e.g.Crypto.Cipher.AES.new()).The first parameter is always the cryptographic key;its length depends on the particular cipher.You can (and sometimes must) pass additional cipher- or mode-specific parameterstonew()(such as a nonce or a mode of operation).For encrypting data, you call the
encrypt()method of the cipherobject with the plaintext. The method returns the piece of ciphertext.Alternatively, with theoutputparameter you can specifya pre-allocated buffer for the result.For most algorithms, you may call
encrypt()multiple times(i.e. once for each piece of plaintext).For decrypting data, you call the
decrypt()method of the cipherobject with the ciphertext. The method returns the piece of plaintext.Theoutputparameter can be passed here too.For most algorithms, you may call
decrypt()multiple times(i.e. once for each piece of ciphertext).
Note
Plaintexts and ciphertexts (input/output) can only be bytes,bytearray or memoryview.In Python 3, you cannot pass strings.In Python 2, you cannot pass Unicode strings.
Often, the sender has to deliver to the receiver other data in additionto ciphertext alone (e.g. initialization vectors or nonces, MAC tags, etc).
This is a basic example:
>>> from Crypto.Cipher import Salsa20>>>>>> key = b'0123456789012345'>>> cipher = Salsa20.new(key)>>> ciphertext = cipher.encrypt(b'The secret I want to send.')>>> ciphertext += cipher.encrypt(b'The second part of the secret.')>>> print cipher.nonce # A byte string you must send to the receiver too
Symmetric ciphers¶
There are two types of symmetric ciphers:
Stream ciphers: the most natural kind of ciphers:they encrypt data one byte at a time.See ChaCha20 and XChaCha20 and Salsa20.
Block ciphers: ciphers that can only operate on a fixed amountof data. The most important block cipher is AES, which hasa block size of 128 bits (16 bytes).
In general, a block cipher is mostly useful only together witha mode of operation, which allows one to encrypta variable amount of data. Some modes (like CTR) effectively turna block cipher into a stream cipher.
The widespread consensus is that ciphers that provideonly confidentiality, without any form of authentication, are undesirable.Instead, primitives have been defined to integrate symmetric encryption andauthentication (MAC). For instance:
- Modern modes of operation for block ciphers (like GCM).
- Stream ciphers paired with a MAC function, like ChaCha20-Poly1305 and XChaCha20-Poly1305.
Legacy ciphers¶
A number of ciphers are implemented in this library purely for backward compatibility purposes.They are deprecated or even fully broken and should not be used in new designs.
- Single DES and Triple DES (block ciphers)
- RC2 (block cipher)
- ARC4 (stream cipher)
- Blowfish (block cipher)
- CAST-128 (block cipher)
- PKCS#1 v1.5 encryption (RSA) (asymmetric cipher)
