--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Documentation/Source/eric5.Utilities.crypto.py3AES.html Sun Jun 19 15:19:46 2011 +0200 @@ -0,0 +1,710 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN' +'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'> +<html><head> +<title>eric5.Utilities.crypto.py3AES</title> +<style> +body { + background: #EDECE6; + margin: 0em 1em 10em 1em; + color: black; +} + +h1 { color: white; background: #85774A; } +h2 { color: white; background: #85774A; } +h3 { color: white; background: #9D936E; } +h4 { color: white; background: #9D936E; } + +a { color: #BA6D36; } + +</style> +</head> +<body><a NAME="top" ID="top"></a> +<h1>eric5.Utilities.crypto.py3AES</h1> +<p> +Module implementing classes for encryption according +Advanced Encryption Standard. +</p> +<h3>Global Attributes</h3> +<table> +<tr><td>None</td></tr> +</table> +<h3>Classes</h3> +<table> +<tr> +<td><a href="#AES">AES</a></td> +<td>Class implementing the Advanced Encryption Standard algorithm.</td> +</tr><tr> +<td><a href="#AESModeOfOperation">AESModeOfOperation</a></td> +<td>Class implementing the different AES mode of operations.</td> +</tr> +</table> +<h3>Functions</h3> +<table> +<tr> +<td><a href="#append_PKCS7_padding">append_PKCS7_padding</a></td> +<td>Function to pad the given data to a multiple of 16-bytes by PKCS7 padding.</td> +</tr><tr> +<td><a href="#decryptData">decryptData</a></td> +<td>Module function to decrypt the given data with the given key.</td> +</tr><tr> +<td><a href="#encryptData">encryptData</a></td> +<td>Module function to encrypt the given data with the given key.</td> +</tr><tr> +<td><a href="#strip_PKCS7_padding">strip_PKCS7_padding</a></td> +<td>Function to strip off PKCS7 padding.</td> +</tr> +</table> +<hr /><hr /> +<a NAME="AES" ID="AES"></a> +<h2>AES</h2> +<p> + Class implementing the Advanced Encryption Standard algorithm. +</p> +<h3>Derived from</h3> +object +<h3>Class Attributes</h3> +<table> +<tr><td>KeySize</td></tr><tr><td>Rcon</td></tr><tr><td>rsbox</td></tr><tr><td>sbox</td></tr> +</table> +<h3>Methods</h3> +<table> +<tr> +<td><a href="#AES.__addRoundKey">__addRoundKey</a></td> +<td>Private method to add (XORs) the round key to the state.</td> +</tr><tr> +<td><a href="#AES.__aes_invMain">__aes_invMain</a></td> +<td>Private method to perform the initial operations, the standard round, and the final operations of the inverse AES, creating a round key for each round.</td> +</tr><tr> +<td><a href="#AES.__aes_invRound">__aes_invRound</a></td> +<td>Private method to apply the 4 operations of the inverse round in sequence.</td> +</tr><tr> +<td><a href="#AES.__aes_main">__aes_main</a></td> +<td>Private method to perform the initial operations, the standard round, and the final operations of the forward AES, creating a round key for each round.</td> +</tr><tr> +<td><a href="#AES.__aes_round">__aes_round</a></td> +<td>Private method to apply the 4 operations of the forward round in sequence.</td> +</tr><tr> +<td><a href="#AES.__core">__core</a></td> +<td>Private method performing the key schedule core operation.</td> +</tr><tr> +<td><a href="#AES.__createRoundKey">__createRoundKey</a></td> +<td>Private method to create a round key.</td> +</tr><tr> +<td><a href="#AES.__expandKey">__expandKey</a></td> +<td>Private method performing Rijndael's key expansion.</td> +</tr><tr> +<td><a href="#AES.__galois_multiplication">__galois_multiplication</a></td> +<td>Private method to perform a Galois multiplication of 8 bit characters a and b.</td> +</tr><tr> +<td><a href="#AES.__getRconValue">__getRconValue</a></td> +<td>Private method to retrieve a given Rcon value.</td> +</tr><tr> +<td><a href="#AES.__getSBoxInvert">__getSBoxInvert</a></td> +<td>Private method to retrieve a given Inverted S-Box value.</td> +</tr><tr> +<td><a href="#AES.__getSBoxValue">__getSBoxValue</a></td> +<td>Private method to retrieve a given S-Box value.</td> +</tr><tr> +<td><a href="#AES.__mixColumn">__mixColumn</a></td> +<td>Private method to perform a galois multiplication of 1 column the 4x4 matrix.</td> +</tr><tr> +<td><a href="#AES.__mixColumns">__mixColumns</a></td> +<td>Private method to perform a galois multiplication of the 4x4 matrix.</td> +</tr><tr> +<td><a href="#AES.__rotate">__rotate</a></td> +<td>Private method performing Rijndael's key schedule rotate operation.</td> +</tr><tr> +<td><a href="#AES.__shiftRow">__shiftRow</a></td> +<td>Private method to shift the bytes of a row to the left.</td> +</tr><tr> +<td><a href="#AES.__shiftRows">__shiftRows</a></td> +<td>Private method to iterate over the 4 rows and call __shiftRow() with that row.</td> +</tr><tr> +<td><a href="#AES.__subBytes">__subBytes</a></td> +<td>Private method to substitute all the values from the state with the value in the SBox using the state value as index for the SBox.</td> +</tr><tr> +<td><a href="#AES.decrypt">decrypt</a></td> +<td>Public method to decrypt a 128 bit input block against the given key of size specified.</td> +</tr><tr> +<td><a href="#AES.encrypt">encrypt</a></td> +<td>Public method to encrypt a 128 bit input block against the given key of size specified.</td> +</tr> +</table> +<a NAME="AES.__addRoundKey" ID="AES.__addRoundKey"></a> +<h4>AES.__addRoundKey</h4> +<b>__addRoundKey</b>(<i>state, roundKey</i>) +<p> + Private method to add (XORs) the round key to the state. +</p><dl> +<dt><i>state</i></dt> +<dd> +state to be changed (bytearray) +</dd><dt><i>roundKey</i></dt> +<dd> +key to be used for the modification (bytearray) +</dd> +</dl><dl> +<dt>Returns:</dt> +<dd> +modified state (bytearray) +</dd> +</dl><a NAME="AES.__aes_invMain" ID="AES.__aes_invMain"></a> +<h4>AES.__aes_invMain</h4> +<b>__aes_invMain</b>(<i>state, expandedKey, nbrRounds</i>) +<p> + Private method to perform the initial operations, the standard round, and the + final operations of the inverse AES, creating a round key for each round. +</p><dl> +<dt><i>state</i></dt> +<dd> +state to be worked on (bytearray) +</dd><dt><i>expandedKey</i></dt> +<dd> +expanded key to be used (bytearray) +</dd><dt><i>nbrRounds</i></dt> +<dd> +number of rounds to be done (integer) +</dd> +</dl><dl> +<dt>Returns:</dt> +<dd> +modified state (bytearray) +</dd> +</dl><a NAME="AES.__aes_invRound" ID="AES.__aes_invRound"></a> +<h4>AES.__aes_invRound</h4> +<b>__aes_invRound</b>(<i>state, roundKey</i>) +<p> + Private method to apply the 4 operations of the inverse round in sequence. +</p><dl> +<dt><i>state</i></dt> +<dd> +state to be worked on (bytearray) +</dd><dt><i>roundKey</i></dt> +<dd> +round key to be used (bytearray) +</dd> +</dl><dl> +<dt>Returns:</dt> +<dd> +modified state (bytearray) +</dd> +</dl><a NAME="AES.__aes_main" ID="AES.__aes_main"></a> +<h4>AES.__aes_main</h4> +<b>__aes_main</b>(<i>state, expandedKey, nbrRounds</i>) +<p> + Private method to perform the initial operations, the standard round, and the + final operations of the forward AES, creating a round key for each round. +</p><dl> +<dt><i>state</i></dt> +<dd> +state to be worked on (bytearray) +</dd><dt><i>expandedKey</i></dt> +<dd> +expanded key to be used (bytearray) +</dd><dt><i>nbrRounds</i></dt> +<dd> +number of rounds to be done (integer) +</dd> +</dl><dl> +<dt>Returns:</dt> +<dd> +modified state (bytearray) +</dd> +</dl><a NAME="AES.__aes_round" ID="AES.__aes_round"></a> +<h4>AES.__aes_round</h4> +<b>__aes_round</b>(<i>state, roundKey</i>) +<p> + Private method to apply the 4 operations of the forward round in sequence. +</p><dl> +<dt><i>state</i></dt> +<dd> +state to be worked on (bytearray) +</dd><dt><i>roundKey</i></dt> +<dd> +round key to be used (bytearray) +</dd> +</dl><dl> +<dt>Returns:</dt> +<dd> +modified state (bytearray) +</dd> +</dl><a NAME="AES.__core" ID="AES.__core"></a> +<h4>AES.__core</h4> +<b>__core</b>(<i>data, iteration</i>) +<p> + Private method performing the key schedule core operation. +</p><dl> +<dt><i>data</i></dt> +<dd> +data to operate on (bytearray) +</dd><dt><i>iteration</i></dt> +<dd> +iteration counter (integer) +</dd> +</dl><dl> +<dt>Returns:</dt> +<dd> +modified data (bytearray) +</dd> +</dl><a NAME="AES.__createRoundKey" ID="AES.__createRoundKey"></a> +<h4>AES.__createRoundKey</h4> +<b>__createRoundKey</b>(<i>expandedKey, roundKeyPointer</i>) +<p> + Private method to create a round key. +</p><dl> +<dt><i>expandedKey</i></dt> +<dd> +expanded key to be used (bytearray) +</dd><dt><i>roundKeyPointer</i></dt> +<dd> +position within the expanded key (integer) +</dd> +</dl><dl> +<dt>Returns:</dt> +<dd> +round key (bytearray) +</dd> +</dl><a NAME="AES.__expandKey" ID="AES.__expandKey"></a> +<h4>AES.__expandKey</h4> +<b>__expandKey</b>(<i>key, size, expandedKeySize</i>) +<p> + Private method performing Rijndael's key expansion. +</p><p> + Expands a 128, 192 or 256 bit key into a 176, 208 or 240 bit key. +</p><dl> +<dt><i>key</i></dt> +<dd> +key to be expanded (bytes or bytearray) +</dd><dt><i>size</i></dt> +<dd> +size of the key in bytes (16, 24 or 32) +</dd><dt><i>expandedKeySize</i></dt> +<dd> +size of the expanded key (integer) +</dd> +</dl><dl> +<dt>Returns:</dt> +<dd> +expanded key (bytearray) +</dd> +</dl><a NAME="AES.__galois_multiplication" ID="AES.__galois_multiplication"></a> +<h4>AES.__galois_multiplication</h4> +<b>__galois_multiplication</b>(<i>a, b</i>) +<p> + Private method to perform a Galois multiplication of 8 bit characters a and b. +</p><dl> +<dt><i>a</i></dt> +<dd> +first factor (byte) +</dd><dt><i>b</i></dt> +<dd> +second factor (byte) +</dd> +</dl><dl> +<dt>Returns:</dt> +<dd> +result (byte) +</dd> +</dl><a NAME="AES.__getRconValue" ID="AES.__getRconValue"></a> +<h4>AES.__getRconValue</h4> +<b>__getRconValue</b>(<i>num</i>) +<p> + Private method to retrieve a given Rcon value. +</p><dl> +<dt><i>num</i></dt> +<dd> +position of the value (integer) +</dd> +</dl><dl> +<dt>Returns:</dt> +<dd> +Rcon value (integer) +</dd> +</dl><a NAME="AES.__getSBoxInvert" ID="AES.__getSBoxInvert"></a> +<h4>AES.__getSBoxInvert</h4> +<b>__getSBoxInvert</b>(<i>num</i>) +<p> + Private method to retrieve a given Inverted S-Box value. +</p><dl> +<dt><i>num</i></dt> +<dd> +position of the value (integer) +</dd> +</dl><dl> +<dt>Returns:</dt> +<dd> +value of the Inverted S-Box (integer) +</dd> +</dl><a NAME="AES.__getSBoxValue" ID="AES.__getSBoxValue"></a> +<h4>AES.__getSBoxValue</h4> +<b>__getSBoxValue</b>(<i>num</i>) +<p> + Private method to retrieve a given S-Box value. +</p><dl> +<dt><i>num</i></dt> +<dd> +position of the value (integer) +</dd> +</dl><dl> +<dt>Returns:</dt> +<dd> +value of the S-Box (integer) +</dd> +</dl><a NAME="AES.__mixColumn" ID="AES.__mixColumn"></a> +<h4>AES.__mixColumn</h4> +<b>__mixColumn</b>(<i>column, isInv</i>) +<p> + Private method to perform a galois multiplication of 1 column the 4x4 matrix. +</p><dl> +<dt><i>column</i></dt> +<dd> +column to be worked on (bytearray) +</dd><dt><i>isInv</i></dt> +<dd> +flag indicating an inverse operation (boolean) +</dd> +</dl><dl> +<dt>Returns:</dt> +<dd> +modified column (bytearray) +</dd> +</dl><a NAME="AES.__mixColumns" ID="AES.__mixColumns"></a> +<h4>AES.__mixColumns</h4> +<b>__mixColumns</b>(<i>state, isInv</i>) +<p> + Private method to perform a galois multiplication of the 4x4 matrix. +</p><dl> +<dt><i>state</i></dt> +<dd> +state to be worked on (bytearray) +</dd><dt><i>isInv</i></dt> +<dd> +flag indicating an inverse operation (boolean) +</dd> +</dl><dl> +<dt>Returns:</dt> +<dd> +modified state (bytearray) +</dd> +</dl><a NAME="AES.__rotate" ID="AES.__rotate"></a> +<h4>AES.__rotate</h4> +<b>__rotate</b>(<i>data</i>) +<p> + Private method performing Rijndael's key schedule rotate operation. +</p><p> + Rotate the data word eight bits to the left: eg, rotate(1d2c3a4f) == 2c3a4f1d. +</p><dl> +<dt><i>data</i></dt> +<dd> +data of size 4 (bytearray) +</dd> +</dl><a NAME="AES.__shiftRow" ID="AES.__shiftRow"></a> +<h4>AES.__shiftRow</h4> +<b>__shiftRow</b>(<i>state, statePointer, nbr, isInv</i>) +<p> + Private method to shift the bytes of a row to the left. +</p><dl> +<dt><i>state</i></dt> +<dd> +state to be worked on (bytearray) +</dd><dt><i>statePointer</i></dt> +<dd> +index into the state (integer) +</dd><dt><i>nbr</i></dt> +<dd> +number of positions to shift (integer) +</dd><dt><i>isInv</i></dt> +<dd> +flag indicating an inverse operation (boolean) +</dd> +</dl><dl> +<dt>Returns:</dt> +<dd> +modified state (bytearray) +</dd> +</dl><a NAME="AES.__shiftRows" ID="AES.__shiftRows"></a> +<h4>AES.__shiftRows</h4> +<b>__shiftRows</b>(<i>state, isInv</i>) +<p> + Private method to iterate over the 4 rows and call __shiftRow() with + that row. +</p><dl> +<dt><i>state</i></dt> +<dd> +state to be worked on (bytearray) +</dd><dt><i>isInv</i></dt> +<dd> +flag indicating an inverse operation (boolean) +</dd> +</dl><dl> +<dt>Returns:</dt> +<dd> +modified state (bytearray) +</dd> +</dl><a NAME="AES.__subBytes" ID="AES.__subBytes"></a> +<h4>AES.__subBytes</h4> +<b>__subBytes</b>(<i>state, isInv</i>) +<p> + Private method to substitute all the values from the state with the value in + the SBox using the state value as index for the SBox. +</p><dl> +<dt><i>state</i></dt> +<dd> +state to be worked on (bytearray) +</dd><dt><i>isInv</i></dt> +<dd> +flag indicating an inverse operation (boolean) +</dd> +</dl><dl> +<dt>Returns:</dt> +<dd> +modified state (bytearray) +</dd> +</dl><a NAME="AES.decrypt" ID="AES.decrypt"></a> +<h4>AES.decrypt</h4> +<b>decrypt</b>(<i>iput, key, size</i>) +<p> + Public method to decrypt a 128 bit input block against the given key of size + specified. +</p><dl> +<dt><i>iput</i></dt> +<dd> +input data (bytearray) +</dd><dt><i>key</i></dt> +<dd> +key to be used (bytes or bytearray) +</dd><dt><i>size</i></dt> +<dd> +key size (16, 24 or 32) +</dd> +</dl><dl> +<dt>Returns:</dt> +<dd> +decrypted data (bytes) +</dd> +</dl><a NAME="AES.encrypt" ID="AES.encrypt"></a> +<h4>AES.encrypt</h4> +<b>encrypt</b>(<i>iput, key, size</i>) +<p> + Public method to encrypt a 128 bit input block against the given key of size + specified. +</p><dl> +<dt><i>iput</i></dt> +<dd> +input data (bytearray) +</dd><dt><i>key</i></dt> +<dd> +key to be used (bytes or bytearray) +</dd><dt><i>size</i></dt> +<dd> +key size (16, 24 or 32) +</dd> +</dl><dl> +<dt>Returns:</dt> +<dd> +encrypted data (bytes) +</dd> +</dl> +<div align="right"><a href="#top">Up</a></div> +<hr /><hr /> +<a NAME="AESModeOfOperation" ID="AESModeOfOperation"></a> +<h2>AESModeOfOperation</h2> +<p> + Class implementing the different AES mode of operations. +</p> +<h3>Derived from</h3> +object +<h3>Class Attributes</h3> +<table> +<tr><td>ModeOfOperation</td></tr><tr><td>aes</td></tr> +</table> +<h3>Methods</h3> +<table> +<tr> +<td><a href="#AESModeOfOperation.__extractBytes">__extractBytes</a></td> +<td>Private method to extract a range of bytes from the input.</td> +</tr><tr> +<td><a href="#AESModeOfOperation.decrypt">decrypt</a></td> +<td>Public method to perform the decryption operation.</td> +</tr><tr> +<td><a href="#AESModeOfOperation.encrypt">encrypt</a></td> +<td>Public method to perform the encryption operation.</td> +</tr> +</table> +<a NAME="AESModeOfOperation.__extractBytes" ID="AESModeOfOperation.__extractBytes"></a> +<h4>AESModeOfOperation.__extractBytes</h4> +<b>__extractBytes</b>(<i>input, start, end, mode</i>) +<p> + Private method to extract a range of bytes from the input. +</p><dl> +<dt><i>input</i></dt> +<dd> +input data (bytes) +</dd><dt><i>start</i></dt> +<dd> +start index (integer) +</dd><dt><i>end</i></dt> +<dd> +end index (integer) +</dd><dt><i>mode</i></dt> +<dd> +mode of operation (0, 1, 2) +</dd> +</dl><dl> +<dt>Returns:</dt> +<dd> +extracted bytes (bytearray) +</dd> +</dl><a NAME="AESModeOfOperation.decrypt" ID="AESModeOfOperation.decrypt"></a> +<h4>AESModeOfOperation.decrypt</h4> +<b>decrypt</b>(<i>cipherIn, originalsize, mode, key, size, IV</i>) +<p> + Public method to perform the decryption operation. +</p><dl> +<dt><i>input</i></dt> +<dd> +data to be encrypted (bytes) +</dd><dt><i>originalsize</i></dt> +<dd> +unencrypted string length (required for CBC) + (integer) +</dd><dt><i>mode</i></dt> +<dd> +mode of operation (0, 1 or 2) +</dd><dt><i>key</i></dt> +<dd> +key to be used (bytes) +</dd><dt><i>size</i></dt> +<dd> +length of the key (integer) +</dd><dt><i>IV</i></dt> +<dd> +initialisation vector (bytearray) +</dd> +</dl><dl> +<dt>Returns:</dt> +<dd> +decrypted data (bytes) +</dd> +</dl><a NAME="AESModeOfOperation.encrypt" ID="AESModeOfOperation.encrypt"></a> +<h4>AESModeOfOperation.encrypt</h4> +<b>encrypt</b>(<i>input, mode, key, size, IV</i>) +<p> + Public method to perform the encryption operation. +</p><dl> +<dt><i>input</i></dt> +<dd> +data to be encrypted (bytes) +</dd><dt><i>mode</i></dt> +<dd> +mode of operation (0, 1 or 2) +</dd><dt><i>key</i></dt> +<dd> +key to be used (bytes) +</dd><dt><i>size</i></dt> +<dd> +length of the key (integer) +</dd><dt><i>IV</i></dt> +<dd> +initialisation vector (bytearray) +</dd> +</dl><dl> +<dt>Returns:</dt> +<dd> +tuple with mode of operation, length of the input and + the encrypted data (integer, integer, bytes) +</dd> +</dl> +<div align="right"><a href="#top">Up</a></div> +<hr /><hr /> +<a NAME="append_PKCS7_padding" ID="append_PKCS7_padding"></a> +<h2>append_PKCS7_padding</h2> +<b>append_PKCS7_padding</b>(<i>b</i>) +<p> + Function to pad the given data to a multiple of 16-bytes by PKCS7 padding. +</p><dl> +<dt><i>b</i></dt> +<dd> +data to be padded (bytes) +</dd> +</dl><dl> +<dt>Returns:</dt> +<dd> +padded data (bytes) +</dd> +</dl> +<div align="right"><a href="#top">Up</a></div> +<hr /><hr /> +<a NAME="decryptData" ID="decryptData"></a> +<h2>decryptData</h2> +<b>decryptData</b>(<i>key, data, mode=AESModeOfOperation.ModeOfOperation["CBC"]</i>) +<p> + Module function to decrypt the given data with the given key. +</p><dl> +<dt><i>key</i></dt> +<dd> +key to be used for decryption (bytes) +</dd><dt><i>data</i></dt> +<dd> +data to be decrypted (with initialization vector prepended) (bytes) +</dd><dt><i>mode</i></dt> +<dd> +mode of operations (0, 1 or 2) +</dd> +</dl><dl> +<dt>Returns:</dt> +<dd> +decrypted data (bytes) +</dd> +</dl><dl> +<dt>Raises <b>ValueError</b>:</dt> +<dd> +key size is invalid or decrypted data is invalid +</dd> +</dl> +<div align="right"><a href="#top">Up</a></div> +<hr /><hr /> +<a NAME="encryptData" ID="encryptData"></a> +<h2>encryptData</h2> +<b>encryptData</b>(<i>key, data, mode=AESModeOfOperation.ModeOfOperation["CBC"]</i>) +<p> + Module function to encrypt the given data with the given key. +</p><dl> +<dt><i>key</i></dt> +<dd> +key to be used for encryption (bytes) +</dd><dt><i>data</i></dt> +<dd> +data to be encrypted (bytes) +</dd><dt><i>mode</i></dt> +<dd> +mode of operations (0, 1 or 2) +</dd> +</dl><dl> +<dt>Returns:</dt> +<dd> +encrypted data prepended with the initialization vector (bytes) +</dd> +</dl> +<div align="right"><a href="#top">Up</a></div> +<hr /><hr /> +<a NAME="strip_PKCS7_padding" ID="strip_PKCS7_padding"></a> +<h2>strip_PKCS7_padding</h2> +<b>strip_PKCS7_padding</b>(<i>b</i>) +<p> + Function to strip off PKCS7 padding. +</p><dl> +<dt><i>b</i></dt> +<dd> +data to be stripped (bytes) +</dd> +</dl><dl> +<dt>Returns:</dt> +<dd> +stripped data (bytes) +</dd> +</dl> +<div align="right"><a href="#top">Up</a></div> +<hr /> +</body></html> \ No newline at end of file