Merge pull request #636 from tomato42/more-docs

More documentation

.github/styles/vocab.txt

@@ -1,16 +1,23 @@
 alog
 cavp
 ecdsa
+fuzzer
+fuzzers
+GnuTLS
 http
 kario
 khaitovich
+OpenSSL
 plaintext
 py
 pycrypto
 rsa
 sosedkin
 ssl
 tls
+tlsfuzzer
+tlslite
+tlslite-ng
 tripledes
 utf
 varga

.vale.ini

@@ -3,3 +3,9 @@ MinAlertLevel = suggestion
 
 [*.{md,rst,py}]
 BasedOnStyles = Vale, write-good, Google
+
+# tlsfuzzer isn't a google web "app" so the wordlist doesn't apply
+Google.WordList = NO
+
+# latine loquor
+Google.Latin = NO

docs/source/glossary.rst

@@ -0,0 +1,53 @@
+.. _glossary:
+
+Glossary
+========
+
+.. glossary::
+   :sorted:
+
+   TLS
+     Transport Layer Security is a cryptographic network protocol defined
+     in a series of :term:`RFC` documents, newest of which is RFC8446.
+
+   RFC
+     Request For Comments are standards published by Internet Engineering Task
+     Force (IETF), an open standards organisation.
+
+   SSL
+     Secure Sockets Layer is an old cryptographic network protocol. It has
+     orginated in Netscape in the early 1990's. Currently replaced by
+     :term:`TLS`.
+
+   SUT
+     System Under Test is the device or implementation that
+     the tests are verifying. Excludes tlsfuzzer itself or systems necessary
+     to execute it or tlsfuzzer.
+
+   RSA
+     Rivest Shamir Adleman is an asymmetric cryptosystem commonly used for
+     signing messages or encrypting keys.
+
+   ECDSA
+     Elliptic Curve Digital Signature Algorithm uses the Digital Signature
+     Algorithm with elliptic curves instead of finite field groups.
+     It's an asymmetric cryptosystem, similar to RSA.
+
+   ECDHE
+     Implementation of Diffie-Hellman key exchange algorithm over elliptic
+     curves.
+
+   AES-GCM
+     Advanced Encryption Standard in Galois Counter Mode is an :term:`AEAD`
+     cipher, it encrypts and authenticates data with one operation.
+
+   AEAD
+     Authenticated Encryption with Associated Data, a mode of operation
+     for symmetric ciphers that processes messages and optional additional
+     data as atomic objects: the decryption provides data only if
+     integrity of data is verified, encryption provides ciphertext only
+     when all the data was provided to the encryption function.
+
+   PKIX
+     Public Key Infrastructure for the Internet, described use of X.509
+     certificates in Internet protocols

docs/source/index.rst

@@ -6,23 +6,25 @@
 Welcome to tlsfuzzer!
 =====================
 
-``tlsfuzzer`` is a framework for testing SSL and TLS implementations.
+``tlsfuzzer`` tests :term:`SSL` and :term:`TLS` implementations.
 
 It allows for testing standards-compliance of a given implementation, testing
-for presence of known vulnerabilities as well as fuzzing of the SSL and TLS
-connections.
-
-Ready-to-use scripts are already provided for testing significant parts of
-the TLS protocols.
-
-This framework is commonly used to test OpenSSL, GnuTLS,
-`NSS <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS>`_ and many
-other implementations.
-
-While not all features standardised for TLS are supported (it's a work
-in progress), the most common features are fully supported:
-TLS 1.2, TLS 1.3, RSA certificates, ECDSA certificates, ECDHE key exchange,
-client certificates, AES-GCM, Chacha20-Poly1305 ciphers, etc. See the
+for presence of known vulnerabilities as well as fuzzing of the :term:`SSL`
+and :term:`TLS` connections.
+
+You can find ready to use scripts that test significant parts of :term:`TLS`
+protocols in the source repository.
+
+The testing of OpenSSL, GnuTLS,
+`NSS <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS>`_, and
+other implementations commonly includes running tlsfuzzer test cases.
+
+While tlsfuzzer doesn't support some features of :term:`TLS`,
+it includes the most commonly used ones:
+:term:`TLS` 1.2, :term:`TLS` 1.3, :term:`RSA` certificates, :term:`ECDSA`
+certificates, :term:`ECDHE` key exchange, client certificates, :term:`AES-GCM`,
+Chacha20-Poly1305 ciphers, etc.
+See the
 `issue tracker <https://github.com/tomato42/tlsfuzzer/issues>`_ on GitHub
 to see wanted, but not yet implemented features.
 
@@ -32,7 +34,10 @@ to see wanted, but not yet implemented features.
    :caption: Contents:
    :hidden:
 
+   quickstart
    installation
+   theory
+   glossary
    modules
 
 
@@ -41,4 +46,5 @@ Indices and tables
 
 * :ref:`genindex`
 * :ref:`modindex`
+* :ref:`glossary`
 * :ref:`search`

docs/source/installation.rst

@@ -1,3 +1,5 @@
+.. _installation:
+
 ============
 Installation
 ============

docs/source/modules.rst

@@ -1,5 +1,5 @@
-tlsfuzzer
-=========
+tlsfuzzer API
+=============
 
 .. toctree::
    :maxdepth: 4