diff --git a/source/concepts/netstrm_drvr.rst b/source/concepts/netstrm_drvr.rst index 182fcdf9..1c4b984a 100644 --- a/source/concepts/netstrm_drvr.rst +++ b/source/concepts/netstrm_drvr.rst @@ -19,3 +19,4 @@ Current Network Stream Drivers ns_ptcp ns_gtls ns_ossl + ns_mbedtls diff --git a/source/concepts/ns_mbedtls.rst b/source/concepts/ns_mbedtls.rst new file mode 100644 index 00000000..f79a0363 --- /dev/null +++ b/source/concepts/ns_mbedtls.rst @@ -0,0 +1,88 @@ +***************************** +mbedtls Network Stream Driver +***************************** + +=========================== =========================================================================== +**Driver Name:**  **mbedtls** +**Author:** Stéphane Adenot +**Available since:** +=========================== =========================================================================== + + +Purpose +======= + +This network stream driver implements a TLS protected transport +via the `MbedTLS library `_. + + +Supported Driver Modes +====================== + +- **0** - unencrypted transmission (just like `ptcp `_ driver) +- **1** - TLS-protected operation + +.. note:: + + Mode 0 does not provide any benefit over the ptcp driver. This + mode exists for technical reasons, but should not be used. It may be + removed in the future. + + +Supported Authentication Modes +============================== + +- **anon** - anonymous authentication as described in IETF's + draft-ietf-syslog-transport-tls-12 Internet draft + +- **x509/fingerprint** - certificate fingerprint authentication as + described in IETF's draft-ietf-syslog-transport-tls-12 Internet draft. + The fingerprint must be provided as the SHA1 or the SHA256 hex string of + the certificate. Multiple values must be separated by comma (,). + A valid configuration would be e.G. + :: + + StreamDriverPermittedPeers="SHA256:10:C4:26:1D:CB:3C:AB:12:DB:1A:F0:47:37:AE:6D:D2:DE:66:B5:71:B7:2E:5B:BB:AE:0C:7E:7F:5F:0D:E9:64,SHA1:DD:23:E3:E7:70:F5:B4:13:44:16:78:A5:5A:8C:39:48:53:A6:DD:25" + +- **x509/certvalid** - certificate validation only. x509/certvalid is + a nonstandard mode. It validates the remote peers certificate, but + does not check the subject name. This is weak authentication that may + be useful in scenarios where multiple devices are deployed and it is + sufficient proof of authenticity when their certificates are signed by + the CA the server trusts. This is better than anon authentication, but + still not recommended. **Known Problems** + +- **x509/name** - certificate validation and subject name authentication as + described in IETF's draft-ietf-syslog-transport-tls-12 Internet draft + +.. note:: + + "anon" does not permit to authenticate the remote peer. As such, + this mode is vulnerable to man in the middle attacks as well as + unauthorized access. It is recommended NOT to use this mode. + A certificate / key does not need to be configured in this authmode. + + +CheckExtendedKeyPurpose +======================= + +- **off** - by default this binary argument is turned off, which means + that Extended Key Usage extension of certificates is ignored + in cert validation. + +- **on** - if you turn this option on, it will check that peer's certificate + contains the value for "TLS WWW Client" or "TLS WWW Server" + respectively, depending whether we are on sending or receiving end of a + connection. + +PrioritizeSAN +============= + +- **off** - by default this binary argument is turned off, which means + that validation of names in certificates goes per older RFC 5280 and either + Subject Alternative Name or Common Name match is good and connection is + allowed. + +- **on** - if you turn this option on, it will perform stricter name checking + as per newer RFC 6125, where, if any SAN is found, contents of CN are + completely ignored and name validity is decided based on SAN only. diff --git a/source/configuration/modules/omfwd.rst b/source/configuration/modules/omfwd.rst index 3276c6e4..037f2f28 100644 --- a/source/configuration/modules/omfwd.rst +++ b/source/configuration/modules/omfwd.rst @@ -177,7 +177,7 @@ Type of protocol to use for forwarding. Note that ``tcp`` includes both legacy plain TCP syslog and `RFC5425 `_-based TLS-encrypted syslog. The selection depends on the StreamDriver parameter. If StreamDriver is -set to "ossl" or "gtls", it will use TLS-encrypted syslog. +set to "ossl", "gtls" or "mbedtls", it will use TLS-encrypted syslog. NetworkNamespace @@ -538,7 +538,7 @@ StreamDriver The recommended alias, compatible with imtcp, is "StreamDriver.Name". Choose the stream driver to be used. Default is plain tcp, but -you can also choose "ossl" or "gtls" for TLS encryption. +you can also choose "ossl" "gtls" or "mbedtls" for TLS encryption. Note: aliases help, but are not a great solution. They may cause confusion if both names are used together in a single diff --git a/source/rainerscript/global.rst b/source/rainerscript/global.rst index 9f070f2e..64397977 100644 --- a/source/rainerscript/global.rst +++ b/source/rainerscript/global.rst @@ -140,7 +140,7 @@ The following parameters can be set: - **defaultNetstreamDriver** - Set it to "ossl" or "gtls" to enable TLS. + Set it to "ossl", "gtls" or "mbedtls" to enable TLS. This `guide `_ shows how to use TLS.