diff --git a/docs/asymmetric.rst b/docs/asymmetric.rst index d7ba7bd..941958b 100644 --- a/docs/asymmetric.rst +++ b/docs/asymmetric.rst @@ -1,2 +1,74 @@ Asymmetric Key Algorithms ========================= + +.. module:: wolfcrypt.ciphers + +**Asymmetric key algorithms** are encryption algorithms that use **a pair +of cryptographic keys**, one for data encryption and signing and the other +one for data decryption and signature verification. + +``wolfcrypt`` provides access to the following **Asymmetric Key Ciphers**: + +Asymmetric Key Encryption Classes +--------------------------------- + +.. autoclass:: RsaPublic + :members: + :inherited-members: + +.. autoclass:: RsaPrivate + :members: + :inherited-members: + + +Example +------- + + >>> from wolfcrypt.ciphers import RsaPrivate, RsaPublic + >>> from wolfcrypt.utils import h2b + >>> + >>> private = "3082025C02010002818100BC730EA849F374A2A9EF18A5DA559921F9C8ECB36D" \ + ... + "48E53535757737ECD161905F3ED9E4D5DF94CAC1A9D719DA86C9E84DC4613682" \ + ... + "FEABAD7E7725BB8D11A5BC623AA838CC39A20466B4F7F7F3AADA4D020EBB5E8D" \ + ... + "6948DC77C9280E22E96BA426BA4CE8C1FD4A6F2B1FEF8AAEF69062E5641EEB2B" \ + ... + "3C67C8DC2700F6916865A902030100010281801397EAE8387825A25C04CE0D40" \ + ... + "7C31E5C470CD9B823B5809863B665FDC3190F14FD5DB15DDDED73B9593311831" \ + ... + "0E5EA3D6A21A716E81481C4BCFDB8E7A866132DCFB55C1166D279224458BF1B8" \ + ... + "48B14B1DACDEDADD8E2FC291FBA5A96EF83A6AF1FD5018EF9FE7C3CA78EA56D3" \ + ... + "D3725B96DD4E064E3AC3D9BE72B66507074C01024100FA47D47A7C923C55EF81" \ + ... + "F041302DA3CF8F1CE6872705700DDF9835D6F18B382F24B5D084B6794F712994" \ + ... + "5AF0646AACE772C6ED4D59983E673AF3742CF9611769024100C0C1820D0CEBC6" \ + ... + "2FDC92F99D821A31E9E9F74BF282871CEE166AD11D188270F3C0B62FF6F3F71D" \ + ... + "F18623C84EEB8F568E8FF5BFF1F72BB5CC3DC657390C1B54410241009D7E05DE" \ + ... + "EDF4B7B2FBFC304B551DE32F0147966905CD0E2E2CBD8363B6AB7CB76DCA5B64" \ + ... + "A7CEBE86DF3B53DE61D21EEBA5F637EDACAB78D94CE755FBD71199C102401898" \ + ... + "1829E61E2739702168AC0A2FA172C121869538C65890A0579CBAE3A7B115C8DE" \ + ... + "F61BC2612376EFB09D1C44BE1343396717C89DCAFBF545648B38822CF2810240" \ + ... + "3989E59C195530BAB7488C48140EF49F7E779743E1B419353123759C3B44AD69" \ + ... + "1256EE0061641666D37C742B15B4A2FEBF086B1A5D3F9012B105863129DBD9E2" + >>> + >>> prv = RsaPrivate(h2b(private)) + >>> + >>> public = "30819F300D06092A864886F70D010101050003818D0030818902818100BC730E" \ + ... + "A849F374A2A9EF18A5DA559921F9C8ECB36D48E53535757737ECD161905F3ED9" \ + ... + "E4D5DF94CAC1A9D719DA86C9E84DC4613682FEABAD7E7725BB8D11A5BC623AA8" \ + ... + "38CC39A20466B4F7F7F3AADA4D020EBB5E8D6948DC77C9280E22E96BA426BA4C" \ + ... + "E8C1FD4A6F2B1FEF8AAEF69062E5641EEB2B3C67C8DC2700F6916865A90203010001" + >>> + >>> pub = RsaPublic(h2b(public)) + >>> + >>> plaintext = b"Everyone gets Friday off." + >>> + >>> ciphertext = pub.encrypt(plaintext) + >>> ciphertext + b'e\xb7\xc2\xad\x0c\x04.\xefU8\x17QB\x852\x03\x01\xef\xbe=\xb4\xaf\xaf\x97\x9e4\x96\x9f\xc3\x8e\x87\x9a8o$.|_e\x1d\xa2yi?\x83\x18\xf9Yr|\x1fQ\x1a\x18\x1e\xab\xd17\xc5\x8c\xae\x08c)\xbc\nIr\x8d\xc3\x88\x7f\xde\x1f\x1a^lB\r\xf1\xc0\xfd0\xdeA\xf3\xd2\xe5q\x9a0\xee\xb4,\x97\x80\xa4|U;\xe6\x11\xf0\xc2Q\x987\xe1>F\xf5\x14\x186@G~(Q\xf2;\xcb\x05\xee\x88\x0b\xd8\xa7' + >>> + >>> prv.decrypt(ciphertext) + b'Everyone gets Friday off.' + >>> + >>> signature = prv.sign(plaintext) + >>> signature + b'~\xc4\xe65\x15\xb17\x7fX\xaf,\xc2lw\xbd\x8f\t\x9d\xbf\xac\xdez\x90\xb4\x9f\x1aM\x88#Z\xea\xcb\xa6\xdb\x99\xf55\xd0\xfe|Mu\xb6\xb79(t\x81+h\xf2\xcd\x88v\xa8\xbaM\x86\xcfk\xe8\xf3\x0b\xb8\x8ew\xda>\xf8\xd5[H\xeaAh\xc6\xdaQlo]\xdd\xf8w\xe7#M-\x12f\xae,\xdd\xa6d FP<;R\xa2\x96hJ\xee_\x1fh\xaa\xc8\xdfAJ\xa5\xdd\x05\xc4\x89\x0c\xd7\xa0C\xb7u"U\x03' + >>> + >>> pub.verify(signature) + b'Everyone gets Friday off.' diff --git a/docs/random.rst b/docs/random.rst index f038be2..0be5c6c 100644 --- a/docs/random.rst +++ b/docs/random.rst @@ -19,8 +19,6 @@ vectors can result in major security issues depending on the algorithms in use. Example ------- -.. doctest:: - >>> from wolfcrypt.random import Random >>> >>> r = Random() diff --git a/docs/symmetric.rst b/docs/symmetric.rst index 0e42417..0535080 100644 --- a/docs/symmetric.rst +++ b/docs/symmetric.rst @@ -1,7 +1,44 @@ Symmetric Key Algorithms ======================== +.. module:: wolfcrypt.ciphers + **Symmetric key algorithms** are encryption algorithms that use the **same cryptographic keys** for both encryption and decryption of data. This operation is also known as **Symmetric Key Encryption**. -``wolfcrypt`` algorithms: + +``wolfcrypt`` provides access to the following **Symmetric Key Ciphers**: + +Symmetric Key Encryption Classes +-------------------------------- + +Interface +~~~~~~~~~ + +All **Symmetric Key Ciphers** available in this module implements the following +interface: + +.. autoclass:: _Cipher + :members: + +Classes +~~~~~~~ + +.. autoclass:: Aes + +.. autoclass:: Des3 + + +Example +------- + +.. doctest:: + + >>> from wolfcrypt.ciphers import Aes, MODE_CBC + >>> + >>> cipher = Aes(b'0123456789abcdef', MODE_CBC, b'1234567890abcdef') + >>> ciphertext = cipher.encrypt('now is the time ') + >>> ciphertext + b'\x95\x94\x92W_B\x81S,\xcc\x9dFw\xa23\xcb' + >>> cipher.decrypt(ciphertext) + b'now is the time ' diff --git a/wolfcrypt/ciphers.py b/wolfcrypt/ciphers.py index e933590..4084e6b 100644 --- a/wolfcrypt/ciphers.py +++ b/wolfcrypt/ciphers.py @@ -42,7 +42,8 @@ _FEEDBACK_MODES = [MODE_ECB, MODE_CBC, MODE_CFB, MODE_OFB, MODE_CTR] class _Cipher(object): """ - A PEP 272 compliant Block Encryption Algorithm. + A **PEP 272: Block Encryption Algorithms** compliant + **Symmetric Key Cipher**. """ def __init__(self, key, mode, IV=None): if mode not in _FEEDBACK_MODES: @@ -82,12 +83,12 @@ class _Cipher(object): def new(cls, key, mode, IV=None, **kwargs): """ Returns a ciphering object, using the secret key contained in - the string 'key', and using the feedback mode 'mode', which + the string **key**, and using the feedback mode **mode**, which must be one of MODE_* defined in this module. - If 'mode' is MODE_CBC or MODE_CFB, 'IV' must be provided and + If **mode** is MODE_CBC or MODE_CFB, **IV** must be provided and must be a string of the same length as the block size. Not - providing a value of 'IV' will result in a ValueError exception + providing a value of **IV** will result in a ValueError exception being raised. """ return cls(key, mode, IV) @@ -123,7 +124,7 @@ class _Cipher(object): def decrypt(self, string): """ - Decrypts 'string', using the key-dependent data in the + Decrypts **string**, using the key-dependent data in the object and with the appropriate feedback mode. The string's length must be an exact multiple of the algorithm's block size or, in CFB mode, of the segment size. Returns a string @@ -150,6 +151,10 @@ class _Cipher(object): class Aes(_Cipher): + """ + The **Advanced Encryption Standard** (AES), a.k.a. Rijndael, is + a symmetric-key cipher standardized by **NIST**. + """ block_size = 16 key_size = None # 16, 24, 32 _key_sizes = [16, 24, 32] @@ -174,6 +179,12 @@ class Aes(_Cipher): class Des3(_Cipher): + """ + **Triple DES** (3DES) is the common name for the **Triple Data + Encryption Algorithm** (TDEA or Triple DEA) symmetric-key block + cipher, which applies the **Data Encryption Standard** (DES) + cipher algorithm three times to each data block. + """ block_size = 8 key_size = 24 _native_type = "Des3 *" @@ -231,9 +242,11 @@ class RsaPublic(_Rsa): def encrypt(self, plaintext): """ - Encrypts plaintext, using the public key data in the + Encrypts **plaintext**, using the public key data in the object. The plaintext's length must not be greater than: - self.output_size - self.RSA_MIN_PAD_SIZE + + **self.output_size - self.RSA_MIN_PAD_SIZE** + Returns a string containing the ciphertext. """ @@ -253,9 +266,11 @@ class RsaPublic(_Rsa): def verify(self, signature): """ - Verifies signature, using the public key data in the + Verifies **signature**, using the public key data in the object. The signature's length must be equal to: - self.output_size + + **self.output_size** + Returns a string containing the plaintext. """ signature = t2b(signature) @@ -291,9 +306,11 @@ class RsaPrivate(RsaPublic): def decrypt(self, ciphertext): """ - Decrypts ciphertext, using the private key data in the + Decrypts **ciphertext**, using the private key data in the object. The ciphertext's length must be equal to: - self.output_size + + **self.output_size** + Returns a string containing the plaintext. """ ciphertext = t2b(ciphertext) @@ -311,9 +328,11 @@ class RsaPrivate(RsaPublic): def sign(self, plaintext): """ - Signs plaintext, using the private key data in the object. + Signs **plaintext**, using the private key data in the object. The plaintext's length must not be greater than: - self.output_size - self.RSA_MIN_PAD_SIZE + + **self.output_size - self.RSA_MIN_PAD_SIZE** + Returns a string containing the signature. """ plaintext = t2b(plaintext) diff --git a/wolfcrypt/hashes.py b/wolfcrypt/hashes.py index c02bc02..816f205 100644 --- a/wolfcrypt/hashes.py +++ b/wolfcrypt/hashes.py @@ -25,7 +25,7 @@ from wolfcrypt.exceptions import * class _Hash(object): """ - A **PEP 247: Cryptographic Hash Function** compliant + A **PEP 247: Cryptographic Hash Functions** compliant **Hash Function Interface**. """ def __init__(self, string=None): @@ -65,7 +65,7 @@ class _Hash(object): def update(self, string): """ - Hashes 'string' into the current state of the hashing + Hashes **string** into the current state of the hashing object. update() can be called any number of times during a hashing object's lifetime. """ @@ -132,8 +132,8 @@ class Sha(_Hash): class Sha256(_Hash): """ - **SHA-256** is a cryptographic hash function from the **SHA-2 family** and - is standardized by **NIST**. + **SHA-256** is a cryptographic hash function from the + **SHA-2 family** and is standardized by **NIST**. It produces a [ **256-bit | 32 bytes** ] message digest. """ @@ -156,8 +156,8 @@ class Sha256(_Hash): class Sha384(_Hash): """ - **SHA-384** is a cryptographic hash function from the **SHA-2 family** and - is standardized by **NIST**. + **SHA-384** is a cryptographic hash function from the + **SHA-2 family** and is standardized by **NIST**. It produces a [ **384-bit | 48 bytes** ] message digest. """ @@ -180,8 +180,8 @@ class Sha384(_Hash): class Sha512(_Hash): """ - **SHA-512** is a cryptographic hash function from the **SHA-2 family** and - is standardized by **NIST**. + **SHA-512** is a cryptographic hash function from the + **SHA-2 family** and is standardized by **NIST**. It produces a [ **512-bit | 64 bytes** ] message digest. """ @@ -213,7 +213,7 @@ _HMAC_TYPES = [_TYPE_SHA, _TYPE_SHA256, _TYPE_SHA384, _TYPE_SHA512] class _Hmac(_Hash): """ - A **PEP 247: Cryptographic Hash Function** compliant + A **PEP 247: Cryptographic Hash Functions** compliant **Keyed Hash Function Interface**. """ digest_size = None @@ -237,8 +237,8 @@ class _Hmac(_Hash): @classmethod def new(cls, key, string=None): """ - Creates a new hashing object and returns it. **key** is a - required parameter containing a string giving the key + Creates a new hashing object and returns it. **key** is + a required parameter containing a string giving the key to use. The optional **string** parameter, if supplied, will be immediately hashed into the object's starting state, as if obj.update(string) was called. @@ -260,7 +260,8 @@ class _Hmac(_Hash): class HmacSha(_Hmac): """ - A HMAC function using **SHA-1** as it's cryptographic hash function. + A HMAC function using **SHA-1** as it's cryptographic + hash function. It produces a [ **512-bit | 64 bytes** ] message digest. """ @@ -270,7 +271,8 @@ class HmacSha(_Hmac): class HmacSha256(_Hmac): """ - A HMAC function using **SHA-256** as it's cryptographic hash function. + A HMAC function using **SHA-256** as it's cryptographic + hash function. It produces a [ **512-bit | 64 bytes** ] message digest. """ @@ -280,7 +282,8 @@ class HmacSha256(_Hmac): class HmacSha384(_Hmac): """ - A HMAC function using **SHA-384** as it's cryptographic hash function. + A HMAC function using **SHA-384** as it's cryptographic + hash function. It produces a [ **512-bit | 64 bytes** ] message digest. """ @@ -290,7 +293,8 @@ class HmacSha384(_Hmac): class HmacSha512(_Hmac): """ - A HMAC function using **SHA-512** as it's cryptographic hash function. + A HMAC function using **SHA-512** as it's cryptographic + hash function. It produces a [ **512-bit | 64 bytes** ] message digest. """