Merge pull request #593 from sarabrajsingh/receptor-names-documentation

adding documentation around skipreceptornamescheck and new certificate validation in receptor

docs/source/tls.rst

@@ -4,6 +4,7 @@ TLS support
 Receptor supports mutual TLS authentication and encryption for above and below the
 mesh connections.
 
+
 Configuring TLS
 ^^^^^^^^^^^^^^^
 
@@ -113,7 +114,48 @@ To find the fingerprint of a given certificate, use the following OpenSSL comman
 
 SHA256 and SHA512 fingerprints are supported.  SHA1 fingerprints are not supported due to the insecurity of the SHA1 algorithm.
 
+
 Above the mesh TLS
 ^^^^^^^^^^^^^^^^^^
 
 Below-the-mesh TLS deals with connections that are being made to an IP address or DNS name, and so it can use normal X.509 certificates which include DNS names or IP addresses in their subjectAltName field.  However, above-the-mesh TLS deals with connections whose endpoint addresses are receptor node IDs.  This requires generating certificates that include receptor node IDs as names in the subjectAltName extension.  To do this, the otherName field of subjectAltName can be utilized.  This field is designed to accept arbitrary names of any type, and includes an ISO Object Identifier (OID) that defines what type of name this is, followed by arbitrary data that is meaningful for that type.  Red Hat has its own OID namespace, which is controlled by RHANANA, the Red Hat Assigned Names And Number Authority.  Receptor has an assignment within the overall Red Hat namespace.
+
+If you decide to consume TLS authentication in your mesh, the certificates OIDs (1.3.6.1.4.1.2312.19.1) will be verified against the `node.id` specified in the configuration file. If there is no match, the receptor binary will hard exit. If you need to get around this check, visit the `Skip Certificate Validation`_ section for more details.
+
+
+Skip Certificate Validation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Depending on the specifics of your environment(s), if you need to turn off certificate validation, you can add a `skipreceptornamescheck` key-value pair in your configuration file for `tls-server`, `tls-config`, or both.
+The default behaviour for this option is `false` which means that the certificate's OIDs will be verified against the node ID.
+
+.. code-block:: yaml
+
+    ---
+    - node:
+        id: bar
+
+    - log-level:
+        level: Debug
+
+    - tls-client:
+        name: myclient
+        rootcas: /full/path/ca.crt
+        insecureskipverify: false
+        cert: /full/path/bar.crt
+        key: /full/path/bar.key
+        skipreceptornamescheck: true
+
+    - tls-server:
+        name: myserver
+        cert: /full/path/foo.crt
+        key: /full/path/foo.key
+        requireclientcert: true
+        clientcas: /full/path/ca.crt
+        pinnedclientcert:
+          - E6:9B:98:A7:A5:DB:17:D6:E4:2C:DE:76:45:42:A8:79:A3:0A:C5:6D:10:42:7A:6A:C4:54:57:83:F1:0F:E2:95
+        skipreceptornamescheck: true
+
+    - tcp-peer:
+        address: localhost:2222
+        tls: myclient