diff --git a/docs/asymmetric.rst b/docs/asymmetric.rst new file mode 100644 index 0000000..d7ba7bd --- /dev/null +++ b/docs/asymmetric.rst @@ -0,0 +1,2 @@ +Asymmetric Key Algorithms +========================= diff --git a/docs/ciphers/aes.rst b/docs/ciphers/aes.rst deleted file mode 100644 index 686c82e..0000000 --- a/docs/ciphers/aes.rst +++ /dev/null @@ -1,2 +0,0 @@ -AES -=== diff --git a/docs/ciphers/asymmetric.rst b/docs/ciphers/asymmetric.rst deleted file mode 100644 index 245ce68..0000000 --- a/docs/ciphers/asymmetric.rst +++ /dev/null @@ -1,7 +0,0 @@ -Symmetric Key Algorithms -======================== - -.. toctree:: - :maxdepth: 1 - - rsa diff --git a/docs/ciphers/des3.rst b/docs/ciphers/des3.rst deleted file mode 100644 index cf8302b..0000000 --- a/docs/ciphers/des3.rst +++ /dev/null @@ -1,2 +0,0 @@ -DES3 -==== diff --git a/docs/ciphers/rsa.rst b/docs/ciphers/rsa.rst deleted file mode 100644 index 5ee2498..0000000 --- a/docs/ciphers/rsa.rst +++ /dev/null @@ -1,2 +0,0 @@ -RSA -=== diff --git a/docs/ciphers/symmetric.rst b/docs/ciphers/symmetric.rst deleted file mode 100644 index bcb168a..0000000 --- a/docs/ciphers/symmetric.rst +++ /dev/null @@ -1,8 +0,0 @@ -Symmetric Key Algorithms -======================== - -.. toctree:: - :maxdepth: 1 - - aes - des3 diff --git a/docs/conf.py b/docs/conf.py index 155696d..b9d4b4a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -294,3 +294,6 @@ texinfo_documents = [ # If true, do not generate a @detailmenu in the "Top" node's menu. #texinfo_no_detailmenu = False + +# Preserves the order of the members, doesn't sorts them alphabetically. +autodoc_member_order = 'bysource' diff --git a/docs/digest.rst b/docs/digest.rst new file mode 100644 index 0000000..0d79f8e --- /dev/null +++ b/docs/digest.rst @@ -0,0 +1,71 @@ +Message Digests +=============== + +.. module:: wolfcrypt.hashes + +A **message digest** is the output of a **cryptographic hash function** +containing a string of bytes created by a **one-way formula** using the +original message as input. + +Message digests are designed to protect the integrity of a piece of data or +media to detect changes and alterations to any part of a message. + + +Hashing Classes +--------------- + +Interface +~~~~~~~~~ + +All Hashing Functions available in this module implements the following +interface: + +.. autoclass:: _Hash + :members: + +SHA-1 +~~~~~ + +.. attention:: + + NIST has deprecated SHA-1 in favor of the SHA-2 variants. New applications + are strongly suggested to use SHA-2 over SHA-1. + +.. autoclass:: Sha + +SHA-2 family +~~~~~~~~~~~~ + +.. autoclass:: Sha256 + + +.. autoclass:: Sha384 + + +.. autoclass:: Sha512 + + +Example +------- + +.. doctest:: + + >>> from wolfcrypt.hashes import Sha256 + >>> + >>> s = Sha256() + >>> s.update(b'wolf') + >>> s.update(b'crypt') + >>> s.digest() + b'\x96\xe0.{\x1c\xbc\xd6\xf1\x04\xfe\x1f\xdbFR\x02zU\x05\xb6\x86R\xb7\x00\x95\xc61\x8f\x9d\xce\r\x18D' + >>> s.hexdigest() + b'96e02e7b1cbcd6f104fe1fdb4652027a5505b68652b70095c6318f9dce0d1844' + >>> + >>> s.update(b'rocks') + >>> s.hexdigest() + b'e1a50df419d65715c48316bdc6a6f7f0485f4b26c1b107228faf17988b61c83f' + >>> + >>> Sha256(b'wolfcryptrocks').hexdigest() + b'e1a50df419d65715c48316bdc6a6f7f0485f4b26c1b107228faf17988b61c83f' + >>> + >>> Sha256.new(b'wolfcryptrocks').hexdigest() + b'e1a50df419d65715c48316bdc6a6f7f0485f4b26c1b107228faf17988b61c83f' diff --git a/docs/hashes/hmac.rst b/docs/hashes/hmac.rst deleted file mode 100644 index f16efe2..0000000 --- a/docs/hashes/hmac.rst +++ /dev/null @@ -1,2 +0,0 @@ -Hmac -==== diff --git a/docs/hashes/index.rst b/docs/hashes/index.rst deleted file mode 100644 index bf05adb..0000000 --- a/docs/hashes/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -Hashing Functions -================= - - -.. toctree:: - :maxdepth: 1 - - sha - sha256 - sha384 - sha512 diff --git a/docs/hashes/sha.rst b/docs/hashes/sha.rst deleted file mode 100644 index 34b4b16..0000000 --- a/docs/hashes/sha.rst +++ /dev/null @@ -1,2 +0,0 @@ -SHA -=== diff --git a/docs/hashes/sha256.rst b/docs/hashes/sha256.rst deleted file mode 100644 index 20256c3..0000000 --- a/docs/hashes/sha256.rst +++ /dev/null @@ -1,2 +0,0 @@ -SHA256 -====== diff --git a/docs/hashes/sha384.rst b/docs/hashes/sha384.rst deleted file mode 100644 index 2c5dcea..0000000 --- a/docs/hashes/sha384.rst +++ /dev/null @@ -1,2 +0,0 @@ -SHA384 -====== diff --git a/docs/hashes/sha512.rst b/docs/hashes/sha512.rst deleted file mode 100644 index a7c26a3..0000000 --- a/docs/hashes/sha512.rst +++ /dev/null @@ -1,2 +0,0 @@ -SHA512 -====== diff --git a/docs/index.rst b/docs/index.rst index b02b774..9b796b1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,7 +1,8 @@ -wolfcrypt Python Documentation -============================== +wolfCrypt Python Documentation +================================== -**wolfcrypt** is a Python library that encapsulates **wolfSSL's wolfCrypt API**. +**wolfCrypt Python**, a.k.a. ``wolfcrypt`` is a Python library that encapsulates +**wolfSSL's wolfCrypt API**. **wolfCrypt** is a lightweight, portable, C-language-based crypto library targeted at IoT, embedded, and RTOS environments primarily because of its size, @@ -9,22 +10,37 @@ speed, and feature set. It works seamlessly in desktop, enterprise, and cloud environments as well. Summary -======= +------- .. toctree:: - :maxdepth: 2 + :maxdepth: 1 + symmetric + asymmetric + digest + mac random - hashes/index - hashes/hmac - ciphers/symmetric - ciphers/asymmetric +Licensing +--------- +wolfSSL’s software is available under two distinct licensing models: +open source and standard commercial licensing. Please see the relevant +section below for information on each type of license. -Indices and tables -================== +Open Source +~~~~~~~~~~~ -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` +wolfCrypt and wolfSSL software are free software downloads and may be modified +to the needs of the user as long as the user adheres to version two of the GPL +License. The GPLv2 license can be found on the `gnu.org website +`_. + +Commercial Licensing +~~~~~~~~~~~~~~~~~~~~ + +Businesses and enterprises who wish to incorporate wolfSSL products into +proprietary appliances or other commercial software products for +re-distribution must license commercial versions. Licenses are generally issued +for one product and include unlimited royalty-free distribution. Custom +licensing terms are also available at licensing@wolfssl.com. diff --git a/docs/mac.rst b/docs/mac.rst new file mode 100644 index 0000000..14b39cd --- /dev/null +++ b/docs/mac.rst @@ -0,0 +1,74 @@ +Message Authentication Codes +============================ + +.. module:: wolfcrypt.hashes + +A **message authentication code** (MAC) is a short piece of information used +to authenticate a message — in other words, to confirm that the message came +from the stated sender (its authenticity) and has not been changed in transit +(its integrity). + +``wolfcrypt`` implements the **Hash-based message authentication code** (HMAC), +which uses a cryptographic hash function coupled with a secret key to produce +**message authentication codes**. + + +Hmac Classes +------------ + +Interface +~~~~~~~~~ + +All Hmac classes available in this module implements the following +interface: + +.. autoclass:: _Hmac + :members: + :inherited-members: + +SHA-1 +~~~~~ + +.. attention:: + + NIST has deprecated SHA-1 in favor of the SHA-2 variants. New applications + are strongly suggested to use SHA-2 over SHA-1. + +.. autoclass:: HmacSha + +SHA-2 family +~~~~~~~~~~~~ + +.. autoclass:: HmacSha256 + + +.. autoclass:: HmacSha384 + + +.. autoclass:: HmacSha512 + + +Example +------- + +.. doctest:: + + >>> from wolfcrypt.hashes import HmacSha256 + >>> + >>> h = HmacSha256('secret') + >>> h.update("wolf") + >>> h.update("crypt") + >>> h.digest() + b'\x18\xbf*\t9\xa2o\xdf\\\xc8\xe0\xc2U\x94,\x8dY\x02;\x1c>> h.hexdigest() + b'18bf2a0939a26fdf5cc8e0c255942c8d59023b1c3c51df8ddb8633fbc166236f' + >>> + >>> h.update("rocks") + >>> h.hexdigest() + b'85dc8c1995d20b17942d52773d8a597d028ad958e5736beafb59a4742f63889e' + >>> + >>> HmacSha256('secret', 'wolfcryptrocks').hexdigest() + b'85dc8c1995d20b17942d52773d8a597d028ad958e5736beafb59a4742f63889e' + >>> + >>> HmacSha256.new('secret', 'wolfcryptrocks').hexdigest() + b'85dc8c1995d20b17942d52773d8a597d028ad958e5736beafb59a4742f63889e' diff --git a/docs/random.rst b/docs/random.rst index 1a004f0..f038be2 100644 --- a/docs/random.rst +++ b/docs/random.rst @@ -1,2 +1,30 @@ Random Number Generation ======================== + +A **cryptographically secure pseudo-random number generator** (CSPRNG) is a +**pseudo-random number generator** (PRNG) with properties that make it suitable +for use in cryptography. + +Using the standard random module APIs for cryptographic keys or initialization +vectors can result in major security issues depending on the algorithms in use. + +``wolfcrypt`` provides the following CSPRNG implementation: + +.. module:: wolfcrypt.random + +.. autoclass:: Random + :members: + + +Example +------- + +.. doctest:: + + >>> from wolfcrypt.random import Random + >>> + >>> r = Random() + >>> r.byte() + b'\x8c' + >>> r.bytes(16) + b']\x93nk\x95\xbc@\xffX\xab\xdcB\xda\x11\xf7\x03' diff --git a/docs/symmetric.rst b/docs/symmetric.rst new file mode 100644 index 0000000..0e42417 --- /dev/null +++ b/docs/symmetric.rst @@ -0,0 +1,7 @@ +Symmetric Key Algorithms +======================== + +**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: diff --git a/wolfcrypt/hashes.py b/wolfcrypt/hashes.py index 88481e5..c02bc02 100644 --- a/wolfcrypt/hashes.py +++ b/wolfcrypt/hashes.py @@ -25,7 +25,8 @@ from wolfcrypt.exceptions import * class _Hash(object): """ - A PEP 247 compliant Cryptographic Hash Function. + A **PEP 247: Cryptographic Hash Function** compliant + **Hash Function Interface**. """ def __init__(self, string=None): self._native_object = _ffi.new(self._native_type) @@ -33,22 +34,19 @@ class _Hash(object): if ret < 0: raise WolfCryptError("Hash init error (%d)" % ret) + if (string): + self.update(string) + @classmethod def new(cls, string=None): """ Creates a new hashing object and returns it. The optional - 'string' parameter, if supplied, will be immediately hashed - into the object's starting state, as if obj.update(string) - was called. + **string** parameter, if supplied, will be immediately + hashed into the object's starting state, as if + obj.update(string) was called. """ - self = cls(string) - - if (string): - self.update(string) - - return self - + return cls(string) def copy(self): @@ -110,6 +108,11 @@ class _Hash(object): class Sha(_Hash): + """ + **SHA-1** is a cryptographic hash function standardized by **NIST**. + + It produces an [ **160-bit | 20 bytes** ] message digest. + """ digest_size = 20 _native_type = "Sha *" _native_size = _ffi.sizeof("Sha") @@ -128,6 +131,12 @@ class Sha(_Hash): class Sha256(_Hash): + """ + **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. + """ digest_size = 32 _native_type = "Sha256 *" _native_size = _ffi.sizeof("Sha256") @@ -146,6 +155,12 @@ class Sha256(_Hash): class Sha384(_Hash): + """ + **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. + """ digest_size = 48 _native_type = "Sha384 *" _native_size = _ffi.sizeof("Sha384") @@ -164,6 +179,12 @@ class Sha384(_Hash): class Sha512(_Hash): + """ + **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. + """ digest_size = 64 _native_type = "Sha512 *" _native_size = _ffi.sizeof("Sha512") @@ -191,12 +212,16 @@ _HMAC_TYPES = [_TYPE_SHA, _TYPE_SHA256, _TYPE_SHA384, _TYPE_SHA512] class _Hmac(_Hash): + """ + A **PEP 247: Cryptographic Hash Function** compliant + **Keyed Hash Function Interface**. + """ digest_size = None _native_type = "Hmac *" _native_size = _ffi.sizeof("Hmac") - def __init__(self, key): + def __init__(self, key, string=None): key = t2b(key) self._native_object = _ffi.new(self._native_type) @@ -204,22 +229,21 @@ class _Hmac(_Hash): if ret < 0: raise WolfCryptError("Hmac init error (%d)" % ret) + if (string): + self.update(string) + + @classmethod 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 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. + 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. """ - self = cls(key) - - if (string): - self.update(string) - - return self + return cls(key, string) def _init(self, type, key): @@ -235,20 +259,40 @@ class _Hmac(_Hash): class HmacSha(_Hmac): + """ + A HMAC function using **SHA-1** as it's cryptographic hash function. + + It produces a [ **512-bit | 64 bytes** ] message digest. + """ _type = _TYPE_SHA digest_size = Sha.digest_size class HmacSha256(_Hmac): + """ + A HMAC function using **SHA-256** as it's cryptographic hash function. + + It produces a [ **512-bit | 64 bytes** ] message digest. + """ _type = _TYPE_SHA256 digest_size = Sha256.digest_size class HmacSha384(_Hmac): + """ + A HMAC function using **SHA-384** as it's cryptographic hash function. + + It produces a [ **512-bit | 64 bytes** ] message digest. + """ _type = _TYPE_SHA384 digest_size = Sha384.digest_size class HmacSha512(_Hmac): + """ + A HMAC function using **SHA-512** as it's cryptographic hash function. + + It produces a [ **512-bit | 64 bytes** ] message digest. + """ _type = _TYPE_SHA512 digest_size = Sha512.digest_size