From 7ae0775514b8ae0e1da365d1e0761da19b29e4c6 Mon Sep 17 00:00:00 2001 From: Michal Kit Date: Fri, 29 Jun 2018 08:13:43 +0100 Subject: [PATCH] CORDA-1688 Updating CRL config docs (#3472) * CORDA-1688 Updating CRL config docs * Addressing review comments --- docs/source/corda-configuration-file.rst | 25 ++++++++++++++++++++++-- docs/source/upgrade-notes.rst | 17 ++++++++++++++++ 2 files changed, 40 insertions(+), 2 deletions(-) diff --git a/docs/source/corda-configuration-file.rst b/docs/source/corda-configuration-file.rst index 2c64e7ab7f..8293a062e2 100644 --- a/docs/source/corda-configuration-file.rst +++ b/docs/source/corda-configuration-file.rst @@ -230,11 +230,13 @@ absolute path to the node's base directory. .. note:: This is temporary feature for onboarding network participants that limits their visibility for privacy reasons. :tlsCertCrlDistPoint: CRL distribution point (i.e. URL) for the TLS certificate. Default value is NULL, which indicates no CRL availability for the TLS certificate. - Note: If crlCheckSoftFail is FALSE (meaning that there is the strict CRL checking mode) this value needs to be set. + + .. note:: This needs to be set if crlCheckSoftFail is false (i.e. strict CRL checking is on). :tlsCertCrlIssuer: CRL issuer (given in the X500 name format) for the TLS certificate. Default value is NULL, which indicates that the issuer of the TLS certificate is also the issuer of the CRL. - Note: If this parameter is set then the tlsCertCrlDistPoint needs to be set as well. + + .. note:: If this parameter is set then `tlsCertCrlDistPoint` needs to be set as well. :flowMonitorPeriodMillis: ``Duration`` of the period suspended flows waiting for IO are logged. Default value is ``60 seconds``. @@ -281,3 +283,22 @@ This is an example of adding/overriding the keyStore password : .. sourcecode:: shell java -Dcorda.rpcSettings.ssl.keyStorePassword=mypassword -jar node.jar + +CRL Configuration +----------------- +The Corda Network provides an endpoint serving an empty certificate revocation list for the TLS-level certificates. +This is intended for deployments that do not provide a CRL infrastructure but still require a strict CRL mode checking. +In such a case use the following URL in `tlsCertCrlDistPoint` option configuration: + + .. sourcecode:: kotlin + + "https://crl.cordaconnect.org/cordatls.crl" + +Together with the above configuration `tlsCertCrlIssuer` option needs to be set to the following value: + + .. sourcecode:: kotlin + + "C=US, L=New York, O=R3 HoldCo LLC, OU=Corda, CN=Corda Root CA" + +This set-up ensures that the TLS-level certificates are embedded with the CRL distribution point referencing the CRL issued by R3. +In cases where a proprietary CRL infrastructure is provided those values need to be changed accordingly. diff --git a/docs/source/upgrade-notes.rst b/docs/source/upgrade-notes.rst index c7f90a8eca..fa01427ec4 100644 --- a/docs/source/upgrade-notes.rst +++ b/docs/source/upgrade-notes.rst @@ -227,6 +227,23 @@ Also, the property `rpcPort` is now deprecated, so it would be preferable to sub Equivalent changes should be performed on classes extending ``CordformDefinition``. +* Certificate Revocation List (CRL) support: + + The newly added feature of certificate revocation (see :doc:`certificate-revocation`) introduces few changes to the node configuration. + In the configuration file it is required to explicitly specify what mode of the CRL check the node should apply. For that purpose the `crlCheckSoftFail` + parameter is now expected to be set explicitly in the node's SSL configuration. + Setting the `crlCheckSoftFail` to true, relaxes the CRL checking policy. In this mode, the SSL communication + will fail only when the certificate revocation status can be checked and the certificate is revoked. Otherwise it will succeed. + If `crlCheckSoftFail` is false, then the SSL failure will occur also if the certificate revocation status cannot be checked (e.g. due to a network failure). + + Older versions of Corda do not have CRL distribution points embedded in the SSL certificates. + As such, in order to be able to reuse node and SSL certificates generated in those versions of Corda, the `crlCheckSoftFail` needs + to be set to true. This is required due to the fact that node and SSL certificates produced in the older versions of Corda miss attributes + required for the CRL check process. In this mode, if the CRL is unavailable for whatever reason, the check will still pass and the SSL connection will be allowed. + + .. note:: The support for the mitigating this issue and being able to use the `strict` mode (i.e. with `crlCheckSoftFail` = false) + of the CRL checking with the certificates generated in the previous versions of Corda is going to be added in the near future. + Testing ^^^^^^^