def new(key, mode, *args, **kwargs):
"""Create a new CAST-128 cipher
:Parameters:
key : byte string
The secret key to use in the symmetric cipher.
Its length may vary from 5 to 16 bytes.
The recommended length is 16 bytes.
mode : a *MODE_** constant
The chaining mode to use for encryption or decryption.
:Keywords:
iv : byte string
(*Only* `MODE_CBC`, `MODE_CFB`, `MODE_OFB`, `MODE_OPENPGP`).
The initialization vector to use for encryption or decryption.
For `MODE_OPENPGP`, IV must be 8 bytes long for encryption
and 10 bytes for decryption (in the latter case, it is
actually the *encrypted* IV which was prefixed to the ciphertext).
For all other modes, it must be 8 bytes long.
If not provided, a random byte string will be generated (you can
read it back via the ``iv`` attribute).
nonce : byte string
(*Only* `MODE_EAX` and `MODE_CTR`)
A mandatory value that must never be reused for any other encryption.
For `MODE_CTR`, its length must be in the range ``[0..7]``.
For `MODE_EAX`, there are no restrictions, but it is recommended to
use at least 16 bytes.
If not provided for `MODE_EAX`, a random 16 byte string will be
generated (you can read it back via the ``nonce`` attribute).
mac_len : integer
(*Only* `MODE_EAX`). Length of the authentication tag, in bytes.
It must be no larger than 8 (which is the default).
segment_size : integer
(*Only* `MODE_CFB`).The number of **bits** the plaintext and ciphertext
are segmented in. It must be a multiple of 8.
If not specified, it will be assumed to be 8.
initial_value : integer
(*Only* `MODE_CTR`). The initial value for the counter within
the counter block. By default it is 0.
:Return: a CAST cipher object, of the applicable mode.
"""
return _create_cipher(sys.modules[__name__], key, mode, *args, **kwargs)
def new(key, mode, *args, **kwargs):
"""Create a new RC2 cipher
:Parameters:
key : byte string
The secret key to use in the symmetric cipher.
Its length can vary from 1 to 128 bytes.
mode : a *MODE_** constant
The chaining mode to use for encryption or decryption.
:Keywords:
IV : byte string
(*Only* `MODE_CBC`, `MODE_CFB`, `MODE_OFB`, `MODE_OPENPGP`).
The initialization vector to use for encryption or decryption.
It is ignored for `MODE_ECB` and `MODE_CTR`.
For `MODE_OPENPGP`, IV must be `block_size` bytes long for encryption
and `block_size` +2 bytes for decryption (in the latter case, it is
actually the *encrypted* IV which was prefixed to the ciphertext).
It is mandatory.
For all other modes, it must be 8 bytes long.
nonce : byte string
(*Only* `MODE_EAX`).
A mandatory value that must never be reused for any other encryption.
There are no restrictions on its length, but it is recommended to
use at least 16 bytes.
counter : callable
(*Only* `MODE_CTR`). A stateful function that returns the next
*counter block*, which is a byte string of `block_size` bytes.
For better performance, use `Crypto.Util.Counter`.
mac_len : integer
(*Only* `MODE_EAX`). Length of the MAC, in bytes.
It must be no larger than 8 (which is the default).
segment_size : integer
(*Only* `MODE_CFB`).The number of bits the plaintext and ciphertext
are segmented in.
It must be a multiple of 8. If 0 or not specified, it will be assumed
to be 8.
effective_keylen : integer
Maximum cryptographic strength of the key, in bits.
It can vary from 0 to 1024. The default value is 1024.
:Return: an RC2 cipher object, of the applicable mode.
"""
return _create_cipher(sys.modules[__name__], key, mode, *args, **kwargs)
def new(key, mode, *args, **kwargs):
"""Create a new TDES cipher
:Parameters:
key : byte string
The secret key to use in the symmetric cipher.
It must be 16 or 24 bytes long. The parity bits will be ignored.
mode : a *MODE_** constant
The chaining mode to use for encryption or decryption.
:Keywords:
IV : byte string
(*Only* `MODE_CBC`, `MODE_CFB`, `MODE_OFB`, `MODE_OPENPGP`).
The initialization vector to use for encryption or decryption.
It is ignored for `MODE_ECB` and `MODE_CTR`.
For `MODE_OPENPGP`, IV must be `block_size` bytes long for encryption
and `block_size` +2 bytes for decryption (in the latter case, it is
actually the *encrypted* IV which was prefixed to the ciphertext).
It is mandatory.
For all other modes, it must be 8 bytes long.
nonce : byte string
(*Only* `MODE_EAX`).
A mandatory value that must never be reused for any other encryption.
There are no restrictions on its length, but it is recommended to
use at least 16 bytes.
counter : object
(*Only* `MODE_CTR`). An object created by `Crypto.Util.Counter`.
mac_len : integer
(*Only* `MODE_EAX`). Length of the MAC, in bytes.
It must be no larger than 8 (which is the default).
segment_size : integer
(*Only* `MODE_CFB`).The number of bits the plaintext and ciphertext
are segmented in.
It must be a multiple of 8. If not specified, it will be assumed to be 8.
:Attention: it is important that all 8 byte subkeys are different,
otherwise TDES would degrade to single `DES`.
:Return: a DES cipher object, of the applicable mode.
"""
return _create_cipher(sys.modules[__name__], key, mode, *args, **kwargs)
def new(key, mode, *args, **kwargs):
"""Create a new Triple DES cipher.
:param key:
The secret key to use in the symmetric cipher.
It must be 8 byte long. The parity bits will be ignored.
:type key: bytes/bytearray/memoryview
:param mode:
The chaining mode to use for encryption or decryption.
:type mode: One of the supported ``MODE_*`` constants
:Keyword Arguments:
* **iv** (*bytes*, *bytearray*, *memoryview*) --
(Only applicable for ``MODE_CBC``, ``MODE_CFB``, ``MODE_OFB``,
and ``MODE_OPENPGP`` modes).
The initialization vector to use for encryption or decryption.
For ``MODE_CBC``, ``MODE_CFB``, and ``MODE_OFB`` it must be 8 bytes long.
For ``MODE_OPENPGP`` mode only,
it must be 8 bytes long for encryption
and 10 bytes for decryption (in the latter case, it is
actually the *encrypted* IV which was prefixed to the ciphertext).
If not provided, a random byte string is generated (you must then
read its value with the :attr:`iv` attribute).
* **nonce** (*bytes*, *bytearray*, *memoryview*) --
(Only applicable for ``MODE_EAX`` and ``MODE_CTR``).
A value that must never be reused for any other encryption done
with this key.
For ``MODE_EAX`` there are no
restrictions on its length (recommended: **16** bytes).
For ``MODE_CTR``, its length must be in the range **[0..7]**.
If not provided for ``MODE_EAX``, a random byte string is generated (you
can read it back via the ``nonce`` attribute).
* **segment_size** (*integer*) --
(Only ``MODE_CFB``).The number of **bits** the plaintext and ciphertext
are segmented in. It must be a multiple of 8.
If not specified, it will be assumed to be 8.
* **mac_len** : (*integer*) --
(Only ``MODE_EAX``)
Length of the authentication tag, in bytes.
It must be no longer than 8 (default).
* **initial_value** : (*integer*) --
(Only ``MODE_CTR``). The initial value for the counter within
the counter block. By default it is **0**.
:Return: a Triple DES object, of the applicable mode.
"""
return _create_cipher(sys.modules[__name__], key, mode, *args, **kwargs)
def new(key, mode, *args, **kwargs):
"""Create a new Blowfish cipher
:Parameters:
key : byte string
The secret key to use in the symmetric cipher.
Its length can vary from 5 to 56 bytes.
mode : a *MODE_** constant
The chaining mode to use for encryption or decryption.
:Keywords:
iv : byte string
(*Only* `MODE_CBC`, `MODE_CFB`, `MODE_OFB`, `MODE_OPENPGP`).
The initialization vector to use for encryption or decryption.
For `MODE_OPENPGP`, IV must be 8 bytes long for encryption
and 10 bytes for decryption (in the latter case, it is
actually the *encrypted* IV which was prefixed to the ciphertext).
For all other modes, it must be 8 bytes long.
If not provided, a random byte string will be generated (you must
read it back via the ``iv`` attribute).
nonce : byte string
(*Only* `MODE_EAX` and `MODE_CTR`).
A value that must never be reused for any other encryption.
For `MODE_CTR`, its length must be in the range ``[0..7]``.
For `MODE_EAX`, there are no restrictions, but it is recommended to
use at least 16 bytes.
If not provided for `MODE_EAX`, a 16 byte random string will be used
(you can read it back via the ``nonce`` attribute).
mac_len : integer
(*Only* `MODE_EAX`). Length of the authentication tag, in bytes.
It must be no larger than 8 (which is the default).
segment_size : integer
(*Only* `MODE_CFB`).The number of bits the plaintext and ciphertext
are segmented in. It must be a multiple of 8.
If not specified, it will be assumed to be 8.
initial_value : integer
(*Only* `MODE_CTR`). The initial value for the counter within
the counter block. By default it is 0.
:Return: a Blowfish cipher object, of the applicable mode:
- CBC_ mode
- CFB_ mode
- CTR_ mode
- EAX_ mode
- ECB_ mode
- OFB_ mode
- OpenPgp_ mode
.. _CBC: Crypto.Cipher._mode_cbc.CbcMode-class.html
.. _CFB: Crypto.Cipher._mode_cfb.CfbMode-class.html
.. _CTR: Crypto.Cipher._mode_ctr.CtrMode-class.html
.. _EAX: Crypto.Cipher._mode_eax.EaxMode-class.html
.. _ECB: Crypto.Cipher._mode_ecb.EcbMode-class.html
.. _OFB: Crypto.Cipher._mode_ofb.OfbMode-class.html
.. _OpenPgp: Crypto.Cipher._mode_openpgp.OpenPgpMode-class.html
"""
return _create_cipher(sys.modules[__name__], key, mode, *args, **kwargs)
def new(key, mode, *args, **kwargs):
"""Create a new AES cipher.
:param key:
The secret key to use in the symmetric cipher.
It must be 16, 24 or 32 bytes long (respectively for *AES-128*,
*AES-192* or *AES-256*).
For ``MODE_SIV`` only, it doubles to 32, 48, or 64 bytes.
:type key: bytes/bytearray/memoryview
:param mode:
The chaining mode to use for encryption or decryption.
If in doubt, use ``MODE_EAX``.
:type mode: One of the supported ``MODE_*`` constants
:Keyword Arguments:
* **iv** (*bytes*, *bytearray*, *memoryview*) --
(Only applicable for ``MODE_CBC``, ``MODE_CFB``, ``MODE_OFB``,
and ``MODE_OPENPGP`` modes).
The initialization vector to use for encryption or decryption.
For ``MODE_CBC``, ``MODE_CFB``, and ``MODE_OFB`` it must be 16 bytes long.
For ``MODE_OPENPGP`` mode only,
it must be 16 bytes long for encryption
and 18 bytes for decryption (in the latter case, it is
actually the *encrypted* IV which was prefixed to the ciphertext).
If not provided, a random byte string is generated (you must then
read its value with the :attr:`iv` attribute).
* **nonce** (*bytes*, *bytearray*, *memoryview*) --
(Only applicable for ``MODE_CCM``, ``MODE_EAX``, ``MODE_GCM``,
``MODE_SIV``, ``MODE_OCB``, and ``MODE_CTR``).
A value that must never be reused for any other encryption done
with this key.
For ``MODE_EAX``, ``MODE_GCM`` and ``MODE_SIV`` there are no
restrictions on its length (recommended: **16** bytes).
For ``MODE_CCM``, its length must be in the range **[7..13]**.
Bear in mind that with CCM there is a trade-off between nonce
length and maximum message size. Recommendation: **11** bytes.
For ``MODE_OCB``, its length must be in the range **[1..15]**
(recommended: **15**).
For ``MODE_CTR``, its length must be in the range **[0..15]**
(recommended: **8**).
In not provided, a random byte string of the recommended
length is used (you must then read its value with the :attr:`nonce`
attribute).
* **segment_size** (*integer*) --
(Only ``MODE_CFB``).The number of **bits** the plaintext and ciphertext
are segmented in. It must be a multiple of 8.
If not specified, it will be assumed to be 8.
* **mac_len** : (*integer*) --
(Only ``MODE_EAX``, ``MODE_GCM``, ``MODE_OCB``, ``MODE_CCM``)
Length of the authentication tag, in bytes.
It must be even and in the range **[4..16]**.
The recommended value (and the default, if not specified) is **16**.
* **msg_len** : (*integer*) --
(Only ``MODE_CCM``). Length of the message to (de)cipher.
If not specified, ``encrypt`` must be called with the entire message.
Similarly, ``decrypt`` can only be called once.
* **assoc_len** : (*integer*) --
(Only ``MODE_CCM``). Length of the associated data.
If not specified, all associated data is buffered internally,
which may represent a problem for very large messages.
* **initial_value** : (*integer*) --
(Only ``MODE_CTR``). The initial value for the counter within
the counter block. By default it is **0**.
* **use_aesni** : (*boolean*) --
Use Intel AES-NI hardware extensions (default: use if available).
:Return: an AES object, of the applicable mode.
"""
kwargs["add_aes_modes"] = True
return _create_cipher(sys.modules[__name__], key, mode, *args, **kwargs)
def new(key, mode, *args, **kwargs):
"""Create a new TDES cipher
:Parameters:
key : byte string
The secret key to use in the symmetric cipher.
It must be 16 or 24 bytes long. The parity bits will be ignored.
The condition K1 != K2 != K3 must hold.
mode : a *MODE_** constant
The chaining mode to use for encryption or decryption.
:Keywords:
iv : byte string
(*Only* `MODE_CBC`, `MODE_CFB`, `MODE_OFB`, `MODE_OPENPGP`).
The initialization vector to use for encryption or decryption.
For `MODE_OPENPGP`, IV must be 8 bytes long for encryption
and 10 bytes for decryption (in the latter case, it is
actually the *encrypted* IV which was prefixed to the ciphertext).
For all other modes, it must be 8 bytes long.
If not provided, a random byte string will be generated (you can read
it back via the ``iv`` attribute).
nonce : byte string
(*Only* `MODE_EAX` and `MODE_CTR`)
A value that must never be reused for any other encryption.
For `MODE_CTR`, its length must be in the range ``[0..7]``.
For `MODE_EAX`, there are no restrictions, but it is recommended to
use at least 16 bytes.
If not provided for `MODE_EAX`, a random 16 byte string is generated
(you can read it back via the ``nonce`` attribute).
mac_len : integer
(*Only* `MODE_EAX`). Length of the authentication tag, in bytes.
It must be no larger than 8 (which is the default).
segment_size : integer
(*Only* `MODE_CFB`).The number of **bits** the plaintext and ciphertext
are segmented in. It must be a multiple of 8.
If not specified, it will be assumed to be 8.
initial_value : integer
(*Only* `MODE_CTR`). The initial value for the counter within
the counter block. By default it is 0.
:Attention: it is important that all 8 byte subkeys are different,
otherwise TDES would degrade to single `DES`.
:Raise ValueError:
when the key degrades to Single DES.
:Return: a DES cipher object, of the applicable mode.
"""
return _create_cipher(sys.modules[__name__], key, mode, *args, **kwargs)
def new(key, mode, *args, **kwargs):
"""Create a new AES cipher
:Parameters:
key : byte string
The secret key to use in the symmetric cipher.
It must be 16 (*AES-128*), 24 (*AES-192*), or 32 (*AES-256*)
bytes long.
Only in `MODE_SIV`, it needs to be 32, 48, or 64 bytes long.
mode : a *MODE_** constant
The chaining mode to use for encryption or decryption.
:Keywords:
IV : byte string
(*Only* `MODE_CBC`, `MODE_CFB`, `MODE_OFB`, `MODE_OPENPGP`).
The initialization vector to use for encryption or decryption.
It is ignored for `MODE_ECB` and `MODE_CTR`.
For `MODE_OPENPGP`, IV must be `block_size` bytes long for encryption
and `block_size` +2 bytes for decryption (in the latter case, it is
actually the *encrypted* IV which was prefixed to the ciphertext).
It is mandatory.
For all other modes, it must be 16 bytes long.
nonce : byte string
(*Only* `MODE_CCM`, `MODE_EAX`, `MODE_GCM`, `MODE_SIV`).
A mandatory value that must never be reused for any other encryption.
For `MODE_CCM`, its length must be in the range ``[7..13]``.
11 or 12 bytes are reasonable values in general. Bear in
mind that with CCM there is a trade-off between nonce length and
maximum message size.
For the other modes, there are no restrictions on its length,
but it is recommended to use at least 16 bytes.
counter : callable
(*Only* `MODE_CTR`). A stateful function that returns the next
*counter block*, which is a byte string of `block_size` bytes.
For better performance, use `Crypto.Util.Counter`.
segment_size : integer
(*Only* `MODE_CFB`).The number of bits the plaintext and ciphertext
are segmented in.
It must be a multiple of 8. If 0 or not specified,
it will be assumed to be 8.
mac_len : integer
(*Only* `MODE_CCM`). Length of the MAC, in bytes. It must be even
and in the range ``[4..16]``. The default is 16.
(*Only* `MODE_EAX` and `MODE_GCM`). Length of the MAC, in bytes.
It must be no larger than 16 bytes (which is the default).
msg_len : integer
(*Only* `MODE_CCM`). Length of the message to (de)cipher.
If not specified, ``encrypt`` or ``decrypt`` may only be called once.
assoc_len : integer
(*Only* `MODE_CCM`). Length of the associated data.
If not specified, all data is internally buffered.
use_aesni : boolean
Use AES-NI if available.
:Return: an AES object, of the applicable mode.
"""
kwargs["add_aes_modes"] = True
return _create_cipher(sys.modules[__name__], key, mode, *args, **kwargs)
def new(key, mode, *args, **kwargs):
"""Create a new AES cipher
:Parameters:
key : byte string
The secret key to use in the symmetric cipher.
It must be 16 (*AES-128*), 24 (*AES-192*), or 32 (*AES-256*)
bytes long.
Only in `MODE_SIV`, it needs to be 32, 48, or 64 bytes long.
mode : a *MODE_** constant
The chaining mode to use for encryption or decryption.
If in doubt, use `MODE_EAX`.
:Keywords:
iv : byte string
(*Only* `MODE_CBC`, `MODE_CFB`, `MODE_OFB`, `MODE_OPENPGP`).
The initialization vector to use for encryption or decryption.
For `MODE_OPENPGP`, it must be 16 bytes long for encryption
and 18 bytes for decryption (in the latter case, it is
actually the *encrypted* IV which was prefixed to the ciphertext).
For all other modes, it must be 16 bytes long.
In not provided, a random byte string is used (you must then
read its value with the ``iv`` attribute).
nonce : byte string
(*Only* `MODE_CCM`, `MODE_EAX`, `MODE_GCM`, `MODE_SIV`, `MODE_OCB`,
`MODE_CTR`).
A value that must never be reused for any other encryption done
with this key.
For `MODE_CCM`, its length must be in the range ``[7..13]``.
Bear in mind that with CCM there is a trade-off between nonce
length and maximum message size.
For `MODE_OCB`, its length must be in the range ``[1..15]``.
For `MODE_CTR`, its length must be in the range ``[0..15]``.
For the other modes, there are no restrictions on its length.
The recommended length depends on the mode: 8 bytes for `MODE_CTR`,
11 bytes for `MODE_CCM`, 15 bytes for `MODE_OCB` and 16 bytes
for the remaining modes.
In not provided, a random byte string of the recommended
length is used (you must then read its value with the ``nonce`` attribute).
segment_size : integer
(*Only* `MODE_CFB`).The number of **bits** the plaintext and ciphertext
are segmented in. It must be a multiple of 8.
If not specified, it will be assumed to be 8.
mac_len : integer
(*Only* `MODE_EAX`, `MODE_GCM`, `MODE_OCB`, `MODE_CCM`)
Length of the authentication tag, in bytes.
It must be even and in the range ``[4..16]``.
The recommended value (and the default, if not specified) is 16.
msg_len : integer
(*Only* `MODE_CCM`). Length of the message to (de)cipher.
If not specified, ``encrypt`` must be called with the entire message.
Similarly, ``decrypt`` can only be called once.
assoc_len : integer
(*Only* `MODE_CCM`). Length of the associated data.
If not specified, all associated data is buffered internally,
which may represent a problem for very large messages.
initial_value : integer
(*Only* `MODE_CTR`). The initial value for the counter within
the counter block. By default it is 0.
use_aesni : boolean
Use Intel AES-NI hardware extensions if available.
:Return: an AES object, of the applicable mode.
"""
kwargs["add_aes_modes"] = True
return _create_cipher(sys.modules[__name__], key, mode, *args, **kwargs)
def new(key, mode, *args, **kwargs):
"""Create a new AES cipher.
:param key:
The secret key to use in the symmetric cipher.
It must be 16, 24 or 32 bytes long (respectively for *AES-128*,
*AES-192* or *AES-256*).
For ``MODE_SIV`` only, it doubles to 32, 48, or 64 bytes.
:type key: bytes/bytearray/memoryview
:param mode:
The chaining mode to use for encryption or decryption.
If in doubt, use ``MODE_EAX``.
:type mode: One of the supported ``MODE_*`` constants
:Keyword Arguments:
* **iv** (*bytes*, *bytearray*, *memoryview*) --
(Only applicable for ``MODE_CBC``, ``MODE_CFB``, ``MODE_OFB``,
and ``MODE_OPENPGP`` modes).
The initialization vector to use for encryption or decryption.
For ``MODE_CBC``, ``MODE_CFB``, and ``MODE_OFB`` it must be 16 bytes long.
For ``MODE_OPENPGP`` mode only,
it must be 16 bytes long for encryption
and 18 bytes for decryption (in the latter case, it is
actually the *encrypted* IV which was prefixed to the ciphertext).
If not provided, a random byte string is generated (you must then
read its value with the :attr:`iv` attribute).
* **nonce** (*bytes*, *bytearray*, *memoryview*) --
(Only applicable for ``MODE_CCM``, ``MODE_EAX``, ``MODE_GCM``,
``MODE_SIV``, ``MODE_OCB``, and ``MODE_CTR``).
A value that must never be reused for any other encryption done
with this key (except possibly for ``MODE_SIV``, see below).
For ``MODE_EAX``, ``MODE_GCM`` and ``MODE_SIV`` there are no
restrictions on its length (recommended: **16** bytes).
For ``MODE_CCM``, its length must be in the range **[7..13]**.
Bear in mind that with CCM there is a trade-off between nonce
length and maximum message size. Recommendation: **11** bytes.
For ``MODE_OCB``, its length must be in the range **[1..15]**
(recommended: **15**).
For ``MODE_CTR``, its length must be in the range **[0..15]**
(recommended: **8**).
For ``MODE_SIV``, the nonce is optional, if it is not specified,
then no nonce is being used, which renders the encryption
deterministic.
If not provided, for modes other than ``MODE_SIV```, a random
byte string of the recommended length is used (you must then
read its value with the :attr:`nonce` attribute).
* **segment_size** (*integer*) --
(Only ``MODE_CFB``).The number of **bits** the plaintext and ciphertext
are segmented in. It must be a multiple of 8.
If not specified, it will be assumed to be 8.
* **mac_len** : (*integer*) --
(Only ``MODE_EAX``, ``MODE_GCM``, ``MODE_OCB``, ``MODE_CCM``)
Length of the authentication tag, in bytes.
It must be even and in the range **[4..16]**.
The recommended value (and the default, if not specified) is **16**.
* **msg_len** : (*integer*) --
(Only ``MODE_CCM``). Length of the message to (de)cipher.
If not specified, ``encrypt`` must be called with the entire message.
Similarly, ``decrypt`` can only be called once.
* **assoc_len** : (*integer*) --
(Only ``MODE_CCM``). Length of the associated data.
If not specified, all associated data is buffered internally,
which may represent a problem for very large messages.
* **initial_value** : (*integer*) --
(Only ``MODE_CTR``). The initial value for the counter within
the counter block. By default it is **0**.
* **use_aesni** : (*boolean*) --
Use Intel AES-NI hardware extensions (default: use if available).
:Return: an AES object, of the applicable mode.
"""
kwargs["add_aes_modes"] = True
return _create_cipher(sys.modules[__name__], key, mode, *args, **kwargs)
def new(key, mode, *args, **kwargs):
"""Create a new RC2 cipher.
:param key:
The secret key to use in the symmetric cipher.
Its length can vary from 5 to 128 bytes.
:type key: bytes, bytearray, memoryview
:param mode:
The chaining mode to use for encryption or decryption.
:type mode: One of the supported ``MODE_*`` constants
:Keyword Arguments:
* **iv** (*bytes*, *bytearray*, *memoryview*) --
(Only applicable for ``MODE_CBC``, ``MODE_CFB``, ``MODE_OFB``,
and ``MODE_OPENPGP`` modes).
The initialization vector to use for encryption or decryption.
For ``MODE_CBC``, ``MODE_CFB``, and ``MODE_OFB`` it must be 8 bytes long.
For ``MODE_OPENPGP`` mode only,
it must be 8 bytes long for encryption
and 10 bytes for decryption (in the latter case, it is
actually the *encrypted* IV which was prefixed to the ciphertext).
If not provided, a random byte string is generated (you must then
read its value with the :attr:`iv` attribute).
* **nonce** (*bytes*, *bytearray*, *memoryview*) --
(Only applicable for ``MODE_EAX`` and ``MODE_CTR``).
A value that must never be reused for any other encryption done
with this key.
For ``MODE_EAX`` there are no
restrictions on its length (recommended: **16** bytes).
For ``MODE_CTR``, its length must be in the range **[0..7]**.
If not provided for ``MODE_EAX``, a random byte string is generated (you
can read it back via the ``nonce`` attribute).
* **segment_size** (*integer*) --
(Only ``MODE_CFB``).The number of **bits** the plaintext and ciphertext
are segmented in. It must be a multiple of 8.
If not specified, it will be assumed to be 8.
* **mac_len** : (*integer*) --
(Only ``MODE_EAX``)
Length of the authentication tag, in bytes.
It must be no longer than 8 (default).
* **initial_value** : (*integer*) --
(Only ``MODE_CTR``). The initial value for the counter within
the counter block. By default it is **0**.
:Return: an ARC2 object, of the applicable mode.
"""
return _create_cipher(sys.modules[__name__], key, mode, *args, **kwargs)
def new(key, mode, *args, **kwargs):
"""Create a new CAST-128 cipher
:Parameters:
key : byte string
The secret key to use in the symmetric cipher.
Its length may vary from 5 to 16 bytes.
The recommended length is 16 bytes.
mode : a *MODE_** constant
The chaining mode to use for encryption or decryption.
:Keywords:
iv : byte string
(*Only* `MODE_CBC`, `MODE_CFB`, `MODE_OFB`, `MODE_OPENPGP`).
The initialization vector to use for encryption or decryption.
For `MODE_OPENPGP`, IV must be 8 bytes long for encryption
and 10 bytes for decryption (in the latter case, it is
actually the *encrypted* IV which was prefixed to the ciphertext).
For all other modes, it must be 8 bytes long.
If not provided, a random byte string will be generated (you can
read it back via the ``iv`` attribute).
nonce : byte string
(*Only* `MODE_EAX` and `MODE_CTR`)
A mandatory value that must never be reused for any other encryption.
For `MODE_CTR`, its length must be in the range ``[0..7]``.
For `MODE_EAX`, there are no restrictions, but it is recommended to
use at least 16 bytes.
If not provided for `MODE_EAX`, a random 16 byte string will be
generated (you can read it back via the ``nonce`` attribute).
mac_len : integer
(*Only* `MODE_EAX`). Length of the authentication tag, in bytes.
It must be no larger than 8 (which is the default).
segment_size : integer
(*Only* `MODE_CFB`).The number of **bits** the plaintext and ciphertext
are segmented in. It must be a multiple of 8.
If not specified, it will be assumed to be 8.
initial_value : integer
(*Only* `MODE_CTR`). The initial value for the counter within
the counter block. By default it is 0.
:Return: a CAST cipher object, of the applicable mode:
- CBC_ mode
- CFB_ mode
- CTR_ mode
- EAX_ mode
- ECB_ mode
- OFB_ mode
- OpenPgp_ mode
.. _CBC: Crypto.Cipher._mode_cbc.CbcMode-class.html
.. _CFB: Crypto.Cipher._mode_cfb.CfbMode-class.html
.. _CTR: Crypto.Cipher._mode_ctr.CtrMode-class.html
.. _EAX: Crypto.Cipher._mode_eax.EaxMode-class.html
.. _ECB: Crypto.Cipher._mode_ecb.EcbMode-class.html
.. _OFB: Crypto.Cipher._mode_ofb.OfbMode-class.html
.. _OpenPgp: Crypto.Cipher._mode_openpgp.OpenPgpMode-class.html
"""
return _create_cipher(sys.modules[__name__], key, mode, *args, **kwargs)
def new(key, mode, *args, **kwargs):
"""Create a new AES cipher
:Parameters:
key : byte string
The secret key to use in the symmetric cipher.
It must be 16 (*AES-128*), 24 (*AES-192*), or 32 (*AES-256*)
bytes long.
Only in `MODE_SIV`, it needs to be 32, 48, or 64 bytes long.
mode : a *MODE_** constant
The chaining mode to use for encryption or decryption.
:Keywords:
IV : byte string
(*Only* `MODE_CBC`, `MODE_CFB`, `MODE_OFB`, `MODE_OPENPGP`).
The initialization vector to use for encryption or decryption.
It is ignored for `MODE_ECB` and `MODE_CTR`.
For `MODE_OPENPGP`, IV must be `block_size` bytes long for encryption
and `block_size` +2 bytes for decryption (in the latter case, it is
actually the *encrypted* IV which was prefixed to the ciphertext).
It is mandatory.
For all other modes, it must be 16 bytes long.
nonce : byte string
(*Only* `MODE_CCM`, `MODE_EAX`, `MODE_GCM`, `MODE_SIV`, `MODE_OCB`).
A mandatory value that must never be reused for any other encryption.
For `MODE_CCM`, its length must be in the range ``[7..13]``.
11 or 12 bytes are reasonable values in general. Bear in
mind that with CCM there is a trade-off between nonce length and
maximum message size.
For `MODE_OCB`, its length must be in the range ``[1..15]``.
It is recommended to use 15 bytes.
For the other modes, there are no restrictions on its length,
but it is recommended to use at least 16 bytes.
counter : callable
(*Only* `MODE_CTR`). A stateful function that returns the next
*counter block*, which is a byte string of `block_size` bytes.
For better performance, use `Crypto.Util.Counter`.
segment_size : integer
(*Only* `MODE_CFB`).The number of bits the plaintext and ciphertext
are segmented in.
It must be a multiple of 8. If 0 or not specified,
it will be assumed to be 8.
mac_len : integer
(*Only* `MODE_CCM`). Length of the MAC, in bytes. It must be even
and in the range ``[4..16]``. The default is 16.
(*Only* `MODE_EAX`, `MODE_GCM`, `MODE_OCB`). Length of the MAC, in bytes.
It must be no larger than 16 bytes (which is the default).
msg_len : integer
(*Only* `MODE_CCM`). Length of the message to (de)cipher.
If not specified, ``encrypt`` or ``decrypt`` may only be called once.
assoc_len : integer
(*Only* `MODE_CCM`). Length of the associated data.
If not specified, all data is internally buffered.
use_aesni : boolean
Use AES-NI if available.
:Return: an AES object, of the applicable mode.
"""
kwargs["add_aes_modes"] = True
return _create_cipher(sys.modules[__name__], key, mode, *args, **kwargs)
