Merge pull request #55977 from adellape/mtls_crl

Author: adellape

modules/nw-ingress-controller-configuration-parameters.adoc

@@ -148,6 +148,7 @@ The Ingress Operator converts the TLS `1.0` of an `Old` or `Custom` profile to `
 `clientTLS` has the required subfields, `spec.clientTLS.clientCertificatePolicy` and `spec.clientTLS.ClientCA`.
 
 The `ClientCertificatePolicy` subfield accepts one of the two values: `Required` or `Optional`. The `ClientCA` subfield specifies a config map that is in the openshift-config namespace. The config map should contain a CA certificate bundle.
+
 The `AllowedSubjectPatterns` is an optional value that specifies a list of regular expressions, which are matched against the distinguished name on a valid client certificate to filter requests. The regular expressions must use PCRE syntax. At least one pattern must match a client certificate's distinguished name; otherwise, the Ingress Controller rejects the certificate and denies the connection. If not specified, the Ingress Controller does not reject certificates based on the distinguished name.
 
 |`routeAdmission`
@@ -207,15 +208,15 @@ For request headers, these adjustments are applied only for routes that have the
 |`httpErrorCodePages` specifies custom HTTP error code response pages. By default, an IngressController uses error pages built into the IngressController image.
 
 |`httpCaptureCookies`
-|`httpCaptureCookies` specifies HTTP cookies that you want to capture in access logs. If the `httpCaptureCookies` field is empty, the access logs do not capture the cookies. 
+|`httpCaptureCookies` specifies HTTP cookies that you want to capture in access logs. If the `httpCaptureCookies` field is empty, the access logs do not capture the cookies.
 
 For any cookie that you want to capture, the following parameters must be in your `IngressController` configuration:
 
 * `name` specifies the name of the cookie.
 * `maxLength` specifies tha maximum length of the cookie.
 * `matchType` specifies if the field `name` of the cookie exactly matches the capture cookie setting or is a prefix of the capture cookie setting. The `matchType` field uses the `Exact` and `Prefix` parameters.
 
-For example: 
+For example:
 [source,yaml]
 ----
   httpCaptureCookies:
@@ -225,7 +226,7 @@ For example:
 ----
 
 |`httpCaptureHeaders`
-|`httpCaptureHeaders` specifies the HTTP headers that you want to capture in the access logs. If the `httpCaptureHeaders` field is empty, the access logs do not capture the headers. 
+|`httpCaptureHeaders` specifies the HTTP headers that you want to capture in the access logs. If the `httpCaptureHeaders` field is empty, the access logs do not capture the headers.
 
 `httpCaptureHeaders` contains two lists of headers to capture in the access logs. The two lists of header fields are `request` and `response`. In both lists, the `name` field must specify the header name and the `maxlength` field must specify the maximum length of the header. For example:
 

modules/nw-mutual-tls-auth.adoc

@@ -1,31 +1,40 @@
 // Module included in the following assemblies:
 //
-// * ingress/ingress-operator.adoc
+// * networking/ingress-operator.adoc
 
 :_content-type: PROCEDURE
 [id=nw-mutual-tls-auth_{context}]
 = Configuring mutual TLS authentication
 
-You can configure the Ingress Controller to enable mutual TLS (mTLS) authentication by setting a `spec.clientTLS` value. The `clientTLS` value configures the Ingress Controller to verify client certificates. This configuration includes setting a `clientCA` value, which is a reference to a config map. The config map contains the PEM-encoded CA certificate bundle that is used to verify a client's certificate. Optionally, you can configure a list of certificate subject filters.
+You can configure the Ingress Controller to enable mutual TLS (mTLS) authentication by setting a `spec.clientTLS` value. The `clientTLS` value configures the Ingress Controller to verify client certificates. This configuration includes setting a `clientCA` value, which is a reference to a config map. The config map contains the PEM-encoded CA certificate bundle that is used to verify a client's certificate. Optionally, you can also configure a list of certificate subject filters.
 
-If the `clientCA` value specifies an X509v3 certificate revocation list (CRL) distribution point, the Ingress Operator downloads the CRL and configures the Ingress Controller to acknowledge it. Requests that do not provide valid certificates are rejected.
+If the `clientCA` value specifies an X509v3 certificate revocation list (CRL) distribution point, the Ingress Operator downloads and manages a CRL config map based on the HTTP URI X509v3 `CRL Distribution Point` specified in each provided certificate. The Ingress Controller uses this config map during mTLS/TLS negotiation. Requests that do not provide valid certificates are rejected.
 
 .Prerequisites
 
 * You have access to the cluster as a user with the `cluster-admin` role.
+* You have a PEM-encoded CA certificate bundle.
+* If your CA bundle references a CRL distribution point, you must have also included the end-entity or leaf certificate to the client CA bundle. This certificate must have included an HTTP URI under `CRL Distribution Points`, as described in RFC 5280. For example:
++
+[source,terminal]
+----
+ Issuer: C=US, O=Example Inc, CN=Example Global G2 TLS RSA SHA256 2020 CA1
+         Subject: SOME SIGNED CERT            X509v3 CRL Distribution Points:
+                Full Name:
+                  URI:http://crl.example.com/example.crl
+----
 
 .Procedure
-. Create a config map that is in the `openshift-config` namespace:
+. In the `openshift-config` namespace, create a config map from your CA bundle:
 +
 [source,terminal]
 ----
-$ oc create configmap router-ca-certs-default --from-file=ca-bundle.pem=client-ca.crt -n openshift-config
+$ oc create configmap \
+   router-ca-certs-default \
+   --from-file=ca-bundle.pem=client-ca.crt \// <1>
+   -n openshift-config
 ----
-+
-[NOTE]
-====
-The config map data key must be `ca-bundle.pem`, and the data value must be a CA certificate in PEM format.
-====
+<1> The config map data key must be `ca-bundle.pem`, and the data value must be a CA certificate in PEM format.
 
 . Edit the `IngressController` resource in the `openshift-ingress-operator` project:
 +
@@ -34,7 +43,7 @@ The config map data key must be `ca-bundle.pem`, and the data value must be a CA
 $ oc edit IngressController default -n openshift-ingress-operator
 ----
 
-. Add the spec.clientTLS field and subfields to configure mutual TLS:
+. Add the `spec.clientTLS` field and subfields to configure mutual TLS:
 +
 .Sample `IngressController` CR for a `clientTLS` profile that specifies filtering patterns
 [source,yaml]