WolfSSL
/
wolfcrypt-py
mirror of https://github.com/wolfSSL/wolfcrypt-py.git
1
0
Fork 0
Code Issues Releases Wiki Activity

finished docs for v0.1.0 rc1

gh-pages
Moisés Guimarães 2016-05-03 00:01:18 -03:00
parent 6f202cdfe3
commit f84d395d69
5 changed files with 161 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
docs/asymmetric.rst
View File

@ -1,2 +1,74 @@
Asymmetric Key Algorithms 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.'

2
docs/random.rst
View File

@ -19,8 +19,6 @@ vectors can result in major security issues depending on the algorithms in use.
Example Example
------- -------
.. doctest::
>>> from wolfcrypt.random import Random >>> from wolfcrypt.random import Random
>>> >>>
>>> r = Random() >>> r = Random()

39
docs/symmetric.rst
View File

@ -1,7 +1,44 @@
Symmetric Key Algorithms Symmetric Key Algorithms
======================== ========================
.. module:: wolfcrypt.ciphers
**Symmetric key algorithms** are encryption algorithms that use the **same **Symmetric key algorithms** are encryption algorithms that use the **same
cryptographic keys** for both encryption and decryption of data. cryptographic keys** for both encryption and decryption of data.
This operation is also known as **Symmetric Key Encryption**. 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 '

45
wolfcrypt/ciphers.py
View File

@ -42,7 +42,8 @@ _FEEDBACK_MODES = [MODE_ECB, MODE_CBC, MODE_CFB, MODE_OFB, MODE_CTR]
class _Cipher(object): 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): def __init__(self, key, mode, IV=None):
if mode not in _FEEDBACK_MODES: if mode not in _FEEDBACK_MODES:
@ -82,12 +83,12 @@ class _Cipher(object):
def new(cls, key, mode, IV=None, **kwargs): def new(cls, key, mode, IV=None, **kwargs):
""" """
Returns a ciphering object, using the secret key contained in 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. 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 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. being raised.
""" """
return cls(key, mode, IV) return cls(key, mode, IV)
@ -123,7 +124,7 @@ class _Cipher(object):
def decrypt(self, string): 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 object and with the appropriate feedback mode. The string's
length must be an exact multiple of the algorithm's block length must be an exact multiple of the algorithm's block
size or, in CFB mode, of the segment size. Returns a string size or, in CFB mode, of the segment size. Returns a string
@ -150,6 +151,10 @@ class _Cipher(object):
class Aes(_Cipher): class Aes(_Cipher):
"""
The **Advanced Encryption Standard** (AES), a.k.a. Rijndael, is
a symmetric-key cipher standardized by **NIST**.
"""
block_size = 16 block_size = 16
key_size = None # 16, 24, 32 key_size = None # 16, 24, 32
_key_sizes = [16, 24, 32] _key_sizes = [16, 24, 32]
@ -174,6 +179,12 @@ class Aes(_Cipher):
class Des3(_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 block_size = 8
key_size = 24 key_size = 24
_native_type = "Des3 *" _native_type = "Des3 *"
@ -231,9 +242,11 @@ class RsaPublic(_Rsa):
def encrypt(self, plaintext): 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: 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. Returns a string containing the ciphertext.
""" """
@ -253,9 +266,11 @@ class RsaPublic(_Rsa):
def verify(self, signature): 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: object. The signature's length must be equal to:
self.output_size
**self.output_size**
Returns a string containing the plaintext. Returns a string containing the plaintext.
""" """
signature = t2b(signature) signature = t2b(signature)
@ -291,9 +306,11 @@ class RsaPrivate(RsaPublic):
def decrypt(self, ciphertext): 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: object. The ciphertext's length must be equal to:
self.output_size
**self.output_size**
Returns a string containing the plaintext. Returns a string containing the plaintext.
""" """
ciphertext = t2b(ciphertext) ciphertext = t2b(ciphertext)
@ -311,9 +328,11 @@ class RsaPrivate(RsaPublic):
def sign(self, plaintext): 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: 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. Returns a string containing the signature.
""" """
plaintext = t2b(plaintext) plaintext = t2b(plaintext)

34
wolfcrypt/hashes.py
View File

@ -25,7 +25,7 @@ from wolfcrypt.exceptions import *
class _Hash(object): class _Hash(object):
""" """
A **PEP 247: Cryptographic Hash Function** compliant A **PEP 247: Cryptographic Hash Functions** compliant
**Hash Function Interface**. **Hash Function Interface**.
""" """
def __init__(self, string=None): def __init__(self, string=None):
@ -65,7 +65,7 @@ class _Hash(object):
def update(self, string): 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 object. update() can be called any number of times during
a hashing object's lifetime. a hashing object's lifetime.
""" """
@ -132,8 +132,8 @@ class Sha(_Hash):
class Sha256(_Hash): class Sha256(_Hash):
""" """
**SHA-256** is a cryptographic hash function from the **SHA-2 family** and **SHA-256** is a cryptographic hash function from the
is standardized by **NIST**. **SHA-2 family** and is standardized by **NIST**.
It produces a [ **256-bit | 32 bytes** ] message digest. It produces a [ **256-bit | 32 bytes** ] message digest.
""" """
@ -156,8 +156,8 @@ class Sha256(_Hash):
class Sha384(_Hash): class Sha384(_Hash):
""" """
**SHA-384** is a cryptographic hash function from the **SHA-2 family** and **SHA-384** is a cryptographic hash function from the
is standardized by **NIST**. **SHA-2 family** and is standardized by **NIST**.
It produces a [ **384-bit | 48 bytes** ] message digest. It produces a [ **384-bit | 48 bytes** ] message digest.
""" """
@ -180,8 +180,8 @@ class Sha384(_Hash):
class Sha512(_Hash): class Sha512(_Hash):
""" """
**SHA-512** is a cryptographic hash function from the **SHA-2 family** and **SHA-512** is a cryptographic hash function from the
is standardized by **NIST**. **SHA-2 family** and is standardized by **NIST**.
It produces a [ **512-bit | 64 bytes** ] message digest. 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): class _Hmac(_Hash):
""" """
A **PEP 247: Cryptographic Hash Function** compliant A **PEP 247: Cryptographic Hash Functions** compliant
**Keyed Hash Function Interface**. **Keyed Hash Function Interface**.
""" """
digest_size = None digest_size = None
@ -237,8 +237,8 @@ class _Hmac(_Hash):
@classmethod @classmethod
def new(cls, key, string=None): def new(cls, key, string=None):
""" """
Creates a new hashing object and returns it. **key** is a Creates a new hashing object and returns it. **key** is
required parameter containing a string giving the key a required parameter containing a string giving the key
to use. The optional **string** parameter, if supplied, to use. The optional **string** parameter, if supplied,
will be immediately hashed into the object's starting will be immediately hashed into the object's starting
state, as if obj.update(string) was called. state, as if obj.update(string) was called.
@ -260,7 +260,8 @@ class _Hmac(_Hash):
class HmacSha(_Hmac): 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. It produces a [ **512-bit | 64 bytes** ] message digest.
""" """
@ -270,7 +271,8 @@ class HmacSha(_Hmac):
class HmacSha256(_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. It produces a [ **512-bit | 64 bytes** ] message digest.
""" """
@ -280,7 +282,8 @@ class HmacSha256(_Hmac):
class HmacSha384(_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. It produces a [ **512-bit | 64 bytes** ] message digest.
""" """
@ -290,7 +293,8 @@ class HmacSha384(_Hmac):
class HmacSha512(_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. It produces a [ **512-bit | 64 bytes** ] message digest.
""" """