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
=========================
.. 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
-------
.. doctest::
>>> from wolfcrypt.random import Random
>>>
>>> r = Random()

39
docs/symmetric.rst
View File

@ -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 '

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):
"""
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)

34
wolfcrypt/hashes.py
View File

@ -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.
"""