docs: Add security

zjkmxy · zjkmxy · commit 42439039bbf1 · 2019-11-20T23:39:15.000-08:00
diff --git a/AUTHORS.rst b/AUTHORS.rst
@@ -1,4 +1,5 @@
 Authors
--------
+=======
 
 * Xinyu Ma
+* Zhaoning Kong
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -0,0 +1,7 @@
+Changelog
+=========
+
+0.2b1 (2019-11-20)
+++++++++++++++++++
+
+The initial release.
diff --git a/Makefile b/Makefile
@@ -9,10 +9,9 @@ upload:
 	python3 setup.py sdist bdist_wheel
 	python3 -m twine upload dist/*
 
-install-edit:
-	venv/bin/pip3 install -e .
-
-venv:
-	python3.6 -m venv venv	
-	./venv/bin/pip3 install pytest pytest-cov
-
+lint:
+	# exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
+	flake8 src --exclude=src/ndn/contrib --count --ignore=F403,F405,W503,E226 \
+		--exit-zero --max-complexity=20 --max-line-length=120 --statistics
+	flake8 tests --count --ignore=F403,F405,W503,E226,E222,W504 \
+		--exit-zero --max-complexity=50 --max-line-length=120 --statistics
diff --git a/README.rst b/README.rst
@@ -8,24 +8,9 @@ python-ndn
 
 A Named Data Networking client library with AsyncIO support in Python 3.
 
-Instructions for developer
---------------------------
-
-To setup python3.6 virtual environment:
-
-.. code-block:: bash
-
-  python3.6 -m venv venv
-  . venv/bin/activate
-  pip3 install -e .
-  pip3 install pytest pytest-cov
-
-To do unit tests:
-
-.. code-block:: bash
-
-  make test
+It supports Python >=3.6 and PyPy3 >=7.1.1.
 
+Please see our documentation_ if you have any issues.
 
 .. |Test Badge| image:: https://github.com/zjkmxy/python-ndn/workflows/test/badge.svg
     :target: https://github.com/zjkmxy/python-ndn
@@ -42,3 +27,5 @@ To do unit tests:
 .. |Doc Badge| image:: https://readthedocs.org/projects/python-ndn/badge/?version=latest
     :target: https://python-ndn.readthedocs.io/en/latest/?badge=latest
     :alt: Doc Status
+
+.. _documentation: https://python-ndn.readthedocs.io/en/latest
diff --git a/docs/index.rst b/docs/index.rst
@@ -22,6 +22,7 @@ Table Of Contents
    src/contribute_support
    src/future
    src/authors
+   src/changelog
 
 
 Indices and tables
diff --git a/docs/src/changelog.rst b/docs/src/changelog.rst
@@ -0,0 +1 @@
+.. include:: ../../CHANGELOG.rst
diff --git a/docs/src/contribute_support.rst b/docs/src/contribute_support.rst
@@ -1,2 +1,13 @@
 Contribute and Support
 ======================
+
+- Please submit any changes via `GitHub`_ pull requests.
+- If you use any existing code, please make sure it is compatible to *LGPL v3*
+- Ensure that your code complies to `PEP8`_.
+- Ensure that your code works with *Python 3.6* and *PyPy 7.1.1*.
+- Please contact the author first if your changes are not back compatible or import new dependencies.
+- Write unit tests. There is no need to cover all code, but please cover as much as you can.
+- Add your name to ``AUTHORS.rst``.
+
+.. _GitHub: https://github.com/zjkmxy/python-ndn
+.. _PEP8: https://www.python.org/dev/peps/pep-0008/
diff --git a/docs/src/installation.rst b/docs/src/installation.rst
@@ -2,6 +2,44 @@
 Installation
 ============
 
-Install the package with pip::
+Install the latest release with pip::
 
     $ pip install python-ndn
+
+Install the latest development version::
+
+    $ pip install -U git+https://github.com/zjkmxy/python-ndn.git
+
+Instructions for developer
+--------------------------
+
+Setup python3.6 virtual environment with editable installation:
+
+.. code-block:: bash
+
+    python3.6 -m venv venv
+    . venv/bin/activate
+    pip3 install -e .
+    pip3 install pytest pytest-cov flake8
+
+Run all tests:
+
+.. code-block:: bash
+
+    make test
+
+Run static analysis:
+
+.. code-block:: bash
+
+    make lint
+
+Please use python 3.7 or 3.8 to generate the documentation.
+
+.. code-block:: bash
+
+    pip install Sphinx sphinx-autodoc-typehints readthedocs-sphinx-ext \
+        sphinx-rtd-theme pycryptodomex pygtrie
+
+    cd docs && make html
+    open _build/html/index.html
diff --git a/docs/src/security/security.rst b/docs/src/security/security.rst
@@ -5,3 +5,41 @@ Introduction
 ------------
 
 The :mod:`ndn.security` package provides basic tools for security use.
+
+Signer
+------
+
+A :any:`Signer` is a class used to sign a packet during encoding.
+
+.. autoclass:: ndn.encoding.Signer
+  :members:
+
+Validator
+---------
+
+A :any:`Validator` is a async function called to validate an Interest or Data packet.
+It takes 2 arguments: a :any:`FormalName` and a :any:`SignaturePtrs`,
+and returns whether the packet is validated.
+
+Keychain
+--------
+
+A :any:`Keychain` is a class which contains Identities, Keys associated with Identities and associated Certificates.
+
+.. autoclass:: ndn.security.keychain.Keychain
+  :members:
+
+
+KeychainDigest
+~~~~~~~~~~~~~~
+.. automodule:: ndn.security.keychain.keychain_digest
+  :members:
+
+
+KeychainSqlite3
+~~~~~~~~~~~~~~~
+
+This is the default Keychain.
+
+.. automodule:: ndn.security.keychain.keychain_sqlite3
+  :members:
diff --git a/setup.py b/setup.py
@@ -16,7 +16,7 @@
     description='An NDN client library with AsyncIO support in Python 3',
     url='https://github.com/zjkmxy/python-ndn',
     author='Xinyu Ma',
-    author_email='xinyu.ma@cs.ucla.edu',
+    author_email='ma.xinyu.26a@kyoto-u.jp',
     download_url='https://pypi.python.org/pypi/python-ndn',
     project_urls={
         "Bug Tracker": "https://github.com/zjkmxy/python-ndn/issues",
@@ -26,16 +26,18 @@
     license='LGPLv3',
     # See https://pypi.python.org/pypi?%3Aaction=list_classifiers
     classifiers=[
-        'Development Status :: 3 - Alpha',
+        'Development Status :: 4 - Beta',
 
         'Intended Audience :: Developers',
         'Topic :: Software Development :: Libraries',
+        'Topic :: Internet',
+        'Topic :: System :: Networking',
 
         'License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)',
 
         'Programming Language :: Python :: 3.6',
         'Programming Language :: Python :: 3.7',
-        'Programming Language :: Python :: 3.8'
+        'Programming Language :: Python :: 3.8',
     ],
 
     keywords='NDN',
diff --git a/src/ndn/app.py b/src/ndn/app.py
@@ -294,7 +294,11 @@ def route(self, name: NonStrictName, validator: Optional[Validator] = None):
         :param name: the Name prefix for this route.
         :type name: :any:`NonStrictName`
         :param validator: the Validator used to validate coming Interests.
-            Interests which fails to be validated will be dropped without raising any exception.
+            An Interest without ApplicationParameters and SignatureInfo will be considered valid without
+            calling validator.
+            Interests with malformed ParametersSha256DigestComponent will be dropped before going into the validator.
+            Otherwise NDNApp will try to validate the Interest with the validator.
+            Interests which fail to be validated will be dropped without raising any exception.
         :type validator: Optional[:any:`Validator`]
 
         :examples:
diff --git a/src/ndn/encoding/signer.py b/src/ndn/encoding/signer.py
@@ -27,12 +27,32 @@
 class Signer(metaclass=abc.ABCMeta):
     @abc.abstractmethod
     def write_signature_info(self, signature_info):
+        """
+        Fill in the fields of SignatureInfo.
+
+        :param signature_info: a blank SignatureInfo object.
+        """
         pass
 
     @abc.abstractmethod
     def get_signature_value_size(self) -> int:
+        """
+        Get the size of SignatureValue.
+        If the size is variable, return the maximum possible value.
+
+        :return: the size of SignatureValue.
+        """
         pass
 
     @abc.abstractmethod
     def write_signature_value(self, wire: VarBinaryStr, contents: List[VarBinaryStr]) -> int:
+        """
+        Calculate the SignatureValue and write it into wire.
+        The length of wire is exactly what :meth:`get_signature_value_size` returns.
+        Basically this function should return the same value except for ECDSA.
+
+        :param wire: the buffer to contain SignatureValue.
+        :param contents: a list of memory blocks that needs to be covered.
+        :return: the actual size of SignatureValue.
+        """
         pass
diff --git a/src/ndn/security/keychain/keychain.py b/src/ndn/security/keychain/keychain.py
@@ -22,6 +22,21 @@
 
 
 class Keychain(collections.abc.Mapping):
+    """
+    The abstract Keychain class, derived from :class:`collections.abc.Mapping`.
+    It behaves like an immutable dict from :any:`FormalName` to Identity.
+    The implementation of Identity varies with concrete implementations.
+    Generally, its methods should also accept :any:`NonStrictName` as inputs.
+    This includes operators such as ``in`` and ``[]``.
+    """
+    # __getitem__ will be called extra times, but there is no need to optimize for performance
     @abc.abstractmethod
     def get_signer(self, sign_args: Dict[str, Any]):
+        """
+        Get a signer from sign_args.
+
+        :param sign_args: the signing arguments provided by the application.
+        :return: a signer.
+        :rtype: :any:`Signer`
+        """
         pass
diff --git a/src/ndn/security/keychain/keychain_digest.py b/src/ndn/security/keychain/keychain_digest.py
@@ -22,6 +22,9 @@
 
 
 class KeychainDigest(Keychain):
+    """
+    A signer which has no Identity and always returns a SHA-256 digest signer.
+    """
     def get_signer(self, sign_args: Dict[str, Any]):
         if sign_args.pop('no_signature', False):
             return None
diff --git a/src/ndn/security/keychain/keychain_sqlite3.py b/src/ndn/security/keychain/keychain_sqlite3.py

-Original file line number
+Diff line change
@@ @@ -1,4 +1,5 @@ @@
 Authors
 --------
 +=======
 * Xinyu Ma
 +* Zhaoning Kong