Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/Crypto/Cipher/AES.py: 82%

1# -*- coding: utf-8 -*-

3# Cipher/AES.py : AES

5# ===================================================================

6# The contents of this file are dedicated to the public domain. To

7# the extent that dedication to the public domain is not available,

8# everyone is granted a worldwide, perpetual, royalty-free,

9# non-exclusive license to exercise all rights associated with the

10# contents of this file for any purpose whatsoever.

11# No rights are reserved.

12#

13# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,

14# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF

15# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND

16# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS

17# BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN

18# ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN

19# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

20# SOFTWARE.

21# ===================================================================

22"""AES symmetric cipher

24AES `(Advanced Encryption Standard)`__ is a symmetric block cipher standardized

25by NIST_ . It has a fixed data block size of 16 bytes.

26Its keys can be 128, 192, or 256 bits long.

28AES is very fast and secure, and it is the de facto standard for symmetric

29encryption.

31As an example, encryption can be done as follows:

33 >>> from Crypto.Cipher import AES

34 >>> from Crypto.Random import get_random_bytes

35 >>>

36 >>> key = b'Sixteen byte key'

37 >>> iv = get_random_bytes(16)

38 >>> cipher = AES.new(key, AES.MODE_CFB, iv)

39 >>> msg = iv + cipher.encrypt(b'Attack at dawn')

41A more complicated example is based on CCM, (see `MODE_CCM`) an `AEAD`_ mode

42that provides both confidentiality and authentication for a message.

44It optionally allows the header of the message to remain in the clear, whilst still

45being authenticated. The encryption is done as follows:

47 >>> from Crypto.Cipher import AES

48 >>> from Crypto.Random import get_random_bytes

49 >>>

50 >>>

51 >>> hdr = b'To your eyes only'

52 >>> plaintext = b'Attack at dawn'

53 >>> key = b'Sixteen byte key'

54 >>> nonce = get_random_bytes(11)

55 >>> cipher = AES.new(key, AES.MODE_CCM, nonce)

56 >>> cipher.update(hdr)

57 >>> msg = nonce, hdr, cipher.encrypt(plaintext), cipher.digest()

59We assume that the tuple ``msg`` is transmitted to the receiver:

61 >>> nonce, hdr, ciphertext, mac = msg

62 >>> key = b'Sixteen byte key'

63 >>> cipher = AES.new(key, AES.MODE_CCM, nonce)

64 >>> cipher.update(hdr)

65 >>> plaintext = cipher.decrypt(ciphertext)

66 >>> try:

67 >>> cipher.verify(mac)

68 >>> print "The message is authentic: hdr=%s, pt=%s" % (hdr, plaintext)

69 >>> except ValueError:

70 >>> print "Key incorrect or message corrupted"

72.. __: http://en.wikipedia.org/wiki/Advanced_Encryption_Standard

73.. _NIST: http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf

74.. _AEAD: http://blog.cryptographyengineering.com/2012/05/how-to-choose-authenticated-encryption.html

76:undocumented: __revision__, __package__

77"""

79__revision__ = "$Id$"

81import sys

82if sys.version_info[0] == 2 and sys.version_info[1] == 1:

83 from Crypto.Util.py21compat import *

84from Crypto.Cipher import blockalgo

85from Crypto.Cipher import _AES

86from Crypto.Util import cpuid

87# Import _AESNI. If AES-NI is not available or _AESNI has not been built, set

88# _AESNI to None.

89try:

90 if cpuid.have_aes_ni():

91 from Crypto.Cipher import _AESNI

92 else:

93 _AESNI = None

94except ImportError:

95 _AESNI = None

97class AESCipher (blockalgo.BlockAlgo):

98 """AES cipher object"""

100 def __init__(self, key, *args, **kwargs):

101 """Initialize an AES cipher object

102

103 See also `new()` at the module level."""

104

105 # Check if the use_aesni was specified.

106 use_aesni = True

107 if 'use_aesni' in kwargs:

108 use_aesni = kwargs['use_aesni']

109 del kwargs['use_aesni']

110

111 # Use _AESNI if the user requested AES-NI and it's available

112 if _AESNI is not None and use_aesni:

113 blockalgo.BlockAlgo.__init__(self, _AESNI, key, *args, **kwargs)

114 else:

115 blockalgo.BlockAlgo.__init__(self, _AES, key, *args, **kwargs)

116

117def new(key, *args, **kwargs):

118 """Create a new AES cipher

119

120 :Parameters:

121 key : byte string

122 The secret key to use in the symmetric cipher.

123 It must be 16 (*AES-128*), 24 (*AES-192*), or 32 (*AES-256*) bytes long.

124

125 Only in `MODE_SIV`, it needs to be 32, 48, or 64 bytes long.

126 :Keywords:

127 mode : a *MODE_** constant

128 The chaining mode to use for encryption or decryption.

129 Default is `MODE_ECB`.

130 IV : byte string

131 (*Only* `MODE_CBC`, `MODE_CFB`, `MODE_OFB`, `MODE_OPENPGP`).

132

133 The initialization vector to use for encryption or decryption.

134

135 It is ignored for `MODE_ECB` and `MODE_CTR`.

136

137 For `MODE_OPENPGP`, IV must be `block_size` bytes long for encryption

138 and `block_size` +2 bytes for decryption (in the latter case, it is

139 actually the *encrypted* IV which was prefixed to the ciphertext).

140 It is mandatory.

141

142 For all other modes, it must be 16 bytes long.

143 nonce : byte string

144 (*Only* `MODE_CCM`, `MODE_EAX`, `MODE_GCM`, `MODE_SIV`).

145

146 A mandatory value that must never be reused for any other encryption.

147

148 For `MODE_CCM`, its length must be in the range ``[7..13]``.

149 11 or 12 bytes are reasonable values in general. Bear in

150 mind that with CCM there is a trade-off between nonce length and

151 maximum message size.

152

153 For the other modes, there are no restrictions on its length,

154 but it is recommended to use at least 16 bytes.

155 counter : callable

156 (*Only* `MODE_CTR`). A stateful function that returns the next

157 *counter block*, which is a byte string of `block_size` bytes.

158 For better performance, use `Crypto.Util.Counter`.

159 segment_size : integer

160 (*Only* `MODE_CFB`).The number of bits the plaintext and ciphertext

161 are segmented in.

162 It must be a multiple of 8. If 0 or not specified, it will be assumed to be 8.

163 mac_len : integer

164 (*Only* `MODE_CCM`). Length of the MAC, in bytes. It must be even and in

165 the range ``[4..16]``. The default is 16.

166

167 (*Only* `MODE_EAX` and `MODE_GCM`). Length of the MAC, in bytes. It must be no

168 larger than 16 bytes (which is the default).

169 msg_len : integer

170 (*Only* `MODE_CCM`). Length of the message to (de)cipher.

171 If not specified, ``encrypt`` or ``decrypt`` may only be called once.

172 assoc_len : integer

173 (*Only* `MODE_CCM`). Length of the associated data.

174 If not specified, all data is internally buffered.

175 use_aesni : boolean

176 Use AES-NI if available.

177

178 :Return: an `AESCipher` object

179 """

180 return AESCipher(key, *args, **kwargs)

181

182#: Electronic Code Book (ECB). See `blockalgo.MODE_ECB`.

183MODE_ECB = 1

184#: Cipher-Block Chaining (CBC). See `blockalgo.MODE_CBC`.

185MODE_CBC = 2

186#: Cipher FeedBack (CFB). See `blockalgo.MODE_CFB`.

187MODE_CFB = 3

188#: This mode should not be used.

189MODE_PGP = 4

190#: Output FeedBack (OFB). See `blockalgo.MODE_OFB`.

191MODE_OFB = 5

192#: CounTer Mode (CTR). See `blockalgo.MODE_CTR`.

193MODE_CTR = 6

194#: OpenPGP Mode. See `blockalgo.MODE_OPENPGP`.

195MODE_OPENPGP = 7

196#: Counter with CBC-MAC (CCM) Mode. See `blockalgo.MODE_CCM`.

197MODE_CCM = 8

198#: EAX Mode. See `blockalgo.MODE_EAX`.

199MODE_EAX = 9

200#: Syntethic Initialization Vector (SIV). See `blockalgo.MODE_SIV`.

201MODE_SIV = 10

202#: Galois Counter Mode (GCM). See `blockalgo.MODE_GCM`.

203MODE_GCM = 11

204#: Size of a data block (in bytes)

205block_size = 16

206#: Size of a key (in bytes)

207key_size = ( 16, 24, 32 )

208