adds docs

This commit is contained in:
Moisés Guimarães
2016-05-03 00:41:54 -03:00
parent 69ac477976
commit 3181731404
23 changed files with 882 additions and 453 deletions

View File

@@ -96,9 +96,9 @@ qthelp:
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/wolfCrypt.qhcp"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/wolfcrypt.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/wolfCrypt.qhc"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/wolfcrypt.qhc"
.PHONY: applehelp
applehelp:
@@ -115,8 +115,8 @@ devhelp:
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/wolfCrypt"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/wolfCrypt"
@echo "# mkdir -p $$HOME/.local/share/devhelp/wolfcrypt"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/wolfcrypt"
@echo "# devhelp"
.PHONY: epub

View File

@@ -0,0 +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 # doctest: +SKIP
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 # doctest: +SKIP
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.'

View File

@@ -1,7 +1,7 @@
# -*- coding: utf-8 -*-
#
# wolfCrypt documentation build configuration file, created by
# sphinx-quickstart on Fri Apr 29 16:04:23 2016.
# wolfcrypt documentation build configuration file, created by
# sphinx-quickstart on Fri Apr 29 16:47:53 2016.
#
# This file is execfile()d with the current directory set to its
# containing dir.
@@ -31,8 +31,10 @@ import sphinx_rtd_theme
# ones.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx.ext.coverage',
'sphinx.ext.viewcode',
'sphinx.ext.githubpages',
]
# Add any paths that contain templates here, relative to this directory.
@@ -50,18 +52,21 @@ source_suffix = '.rst'
master_doc = 'index'
# General information about the project.
project = u'wolfCrypt'
copyright = u'2016, wolfSSL'
project = u'wolfcrypt'
copyright = u'2016, wolfSSL Inc. All rights reserved'
author = u'wolfSSL'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = u'0.0'
# The full version, including alpha/beta/rc tags.
release = u'0.0.1'
base_dir = os.path.join(os.path.dirname(__file__), os.pardir)
about = {}
with open(os.path.join(base_dir, "wolfcrypt", "about.py")) as f:
exec(f.read(), about)
version = release = about["__version__"]
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
@@ -125,7 +130,7 @@ html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# The name for this set of Sphinx documents.
# "<project> v<release> documentation" by default.
#html_title = u'wolfCrypt v0.0.1'
#html_title = u'%s v%s' % (project, release)
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
@@ -207,7 +212,7 @@ html_static_path = ['_static']
#html_search_scorer = 'scorer.js'
# Output file base name for HTML help builder.
htmlhelp_basename = 'wolfCryptdoc'
htmlhelp_basename = 'wolfcrypt-pydoc'
# -- Options for LaTeX output ---------------------------------------------
@@ -229,7 +234,7 @@ latex_elements = {
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'wolfCrypt.tex', u'wolfCrypt Documentation',
(master_doc, 'wolfcrypt.tex', u'wolfcrypt Python Documentation',
u'wolfSSL', 'manual'),
]
@@ -259,7 +264,7 @@ latex_documents = [
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'wolfcrypt', u'wolfCrypt Documentation',
(master_doc, 'wolfcrypt', u'wolfcrypt Python Documentation',
[author], 1)
]
@@ -273,8 +278,8 @@ man_pages = [
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'wolfCrypt', u'wolfCrypt Documentation',
author, 'wolfCrypt', 'One line description of project.',
(master_doc, 'wolfcrypt', u'wolfcrypt Python Documentation',
author, 'wolfcrypt', 'One line description of project.',
'Miscellaneous'),
]
@@ -289,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'

View File

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

View File

@@ -1,22 +1,46 @@
.. wolfCrypt documentation master file, created by
sphinx-quickstart on Fri Apr 29 16:04:23 2016.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
wolfCrypt Python Documentation
==================================
Welcome to wolfCrypt's documentation!
=====================================
**wolfCrypt Python**, a.k.a. ``wolfcrypt`` is a Python library that encapsulates
**wolfSSL's wolfCrypt API**.
Contents:
**wolfCrypt** is a lightweight, portable, C-language-based crypto library
targeted at IoT, embedded, and RTOS environments primarily because of its size,
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
Licensing
---------
Indices and tables
==================
wolfSSLs 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.
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
Open Source
~~~~~~~~~~~
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
<http://www.gnu.org/licenses/old-licenses/gpl-2.0.html>`_.
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.

View File

@@ -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<Q\xdf\x8d\xdb\x863\xfb\xc1f#o'
>>> h.hexdigest()
b'18bf2a0939a26fdf5cc8e0c255942c8d59023b1c3c51df8ddb8633fbc166236f'
>>>
>>> h.update("rocks")
>>> h.hexdigest()
b'85dc8c1995d20b17942d52773d8a597d028ad958e5736beafb59a4742f63889e'
>>>
>>> HmacSha256('secret', 'wolfcryptrocks').hexdigest()
b'85dc8c1995d20b17942d52773d8a597d028ad958e5736beafb59a4742f63889e'
>>>
>>> HmacSha256.new('secret', 'wolfcryptrocks').hexdigest()
b'85dc8c1995d20b17942d52773d8a597d028ad958e5736beafb59a4742f63889e'

View File

@@ -0,0 +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
-------
>>> from wolfcrypt.random import Random
>>>
>>> r = Random()
>>> b = r.byte()
>>> b # doctest: +SKIP
b'\x8c'
>>> b16 = r.bytes(16)
>>> b16 # doctest: +SKIP
b']\x93nk\x95\xbc@\xffX\xab\xdcB\xda\x11\xf7\x03'

View File

@@ -0,0 +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`` 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 '