From 42de8352c8992073cce2f494afed23e625bffee5 Mon Sep 17 00:00:00 2001 From: Matthew Vivian Date: Wed, 20 Nov 2024 14:06:40 +0000 Subject: [PATCH] docs: Certificate revocation documentation --- documentation/ssl-guide.html | 172 ++++++++++++++++++++++++++++++++++- documentation/style.css | 5 + 2 files changed, 174 insertions(+), 3 deletions(-) diff --git a/documentation/ssl-guide.html b/documentation/ssl-guide.html index cab0e7bc8a..db7e4903e2 100644 --- a/documentation/ssl-guide.html +++ b/documentation/ssl-guide.html @@ -46,6 +46,7 @@

Introduction

@@ -82,7 +83,7 @@

Background

If you only require light security, are deploying for internal use on trusted networks, etc. you can use "self-signed" certificates. Self-signed certificates encrypts the communication channel between - client and server. However the client must verify the legitimacy of the + client and server. However, the client must verify the legitimacy of the self-signed certificate through some other channel. The most common client reaction to a self-signed certificate is to ask the user whether to trust the certificate, or to silently trust the certificate is @@ -182,7 +183,7 @@

2. Create a self-signed server certificate

to complete with your server's name when asked for your first and last name. After you have entered all the required information, keytool will ask you to verify the information and set a key password. - You must use the same key password as the store password. By default + You must use the same key password as the store password. By default, you get this by simply hitting 'enter' when prompted for a key password.

@@ -297,13 +298,178 @@

7. Configure Openfire

+ +
+

Certificate Revocation

+ +

This section covers the configuration of certificate revocation checking in Openfire, including OCSP + (Online Certificate Status Protocol) and CRL (Certificate Revocation List) mechanisms. This applies to + both roles that Openfire can assume in TLS connections:

+ +
    +
  1. As a server when: +
      +
    • Accepting client connections (C2S)
      • +
    • Accepting incoming server-to-server (S2S) connections
      • +
    +
    2. +
  2. As a client when: +
      +
    • Initiating outbound server-to-server (S2S) connections
      • +
    +
    3. +
+ +

Overview of Revocation Checking Methods

+ +

Openfire supports three methods for checking certificate revocation status:

+ +
    +
  1. OCSP Stapling: The server attaches ("staples") the OCSP response to its certificate + during the TLS handshake. +
      +
    • Most efficient method
      • +
    • Reduces load on OCSP responders
      • +
    • Supported in both client and server roles
      • +
    +
    2. + +
  2. Client-driven OCSP: Direct OCSP responder queries to verify certificate status. +
      +
    • Real-time verification
      • +
    • Higher network overhead
      • +
    • Increased latency during TLS handshake
      • +
    +
    3. + +
  3. Certificate Revocation Lists (CRL): Downloadable lists of revoked certificates. +
      +
    • Periodic updates
      • +
    • Can be cached locally
      • +
    • Larger bandwidth requirements
      • +
    • Can be used as a fallback method
      • +
    +
    4. +
+ +

Configuring Revocation Checking

+ +

To enable certificate revocation checking:

+ +
    +
  1. Go to the Openfire admin console.
    2. +
  2. Navigate to "Server / Server Settings / Server to Server" or "Server / Server Settings / Client Connections".
    3. +
  3. In the "Certificate chain checking" section, locate the option labelled "Verify that certificates have not been revoked (by checking Certificate Revocation Lists and OCSP)".
    4. +
  4. Enable the option to verify certificates against Certificate Revocation Lists (CRL) and through Online Certificate Status Protocol (OCSP).
    5. +
+ +

When this option is enabled, Openfire will check the revocation status of certificates used in server-to-server + (S2S) and client-to-server (C2S) connections to ensure they have not been revoked.

+ +

Fallback behavior when Openfire is the Client (S2S Connections)

+ +

When revocation checking is enabled, Openfire employs a multistep process to verify certificate validity + using both OCSP and CRLs. When Openfire acts as a client during the TLS handshake and receives certificates + from a server, it performs the following revocation checking process:

+
    +
  1. Check OCSP stapled response (if available)
    2. +
  2. Attempt client-driven OCSP query if no stapled response is present
    3. +
  3. Check CRL (if OCSP is unavailable)
    4. +
  4. Fail the connection if all methods fail
    5. +
+ +

OCSP Stapling

+ +

Openfire, when operating as a TLS server and presenting its own certificate, will attempt to staple OCSP + responses when both of these conditions are met:

+ + + +

If an OCSP response cannot be obtained, Openfire will present the certificate without an OCSP staple. + OCSP stapling improves performance by eliminating the need for clients to make separate requests to + verify certificate revocation status.

+ +

OCSP stapling is enabled by default. If you need to disable it for any reason, you can set the Java + system property jdk.tls.server.enableStatusRequestExtension to false.

+ +

+ The following configuration options allow you to customise OCSP stapling behavior: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PropertyDescriptionOpenfire Default Value
jdk.tls.server.enableStatusRequestExtensionEnables the server-side support for OCSP stapling.True
jdk.tls.stapling.responseTimeout +

Controls the maximum amount of time the server will use to obtain OCSP responses, whether from the cache or by contacting an OCSP responder.

+

The responses that are already received will be sent in a CertificateStatus message, if applicable based on the type of stapling being done.

+ 		5000 (integer value in milliseconds)
jdk.tls.stapling.cacheSize +

Controls the maximum cache size in entries.

+

If the cache is full and a new response needs to be cached, then the least recently used cache entry will be replaced with the new one. A value of zero or less for this property means that the cache will have no upper bound on the number of responses it can contain.

+ 		256 objects
jdk.tls.stapling.cacheLifetime +

Controls the maximum life of a cached response.

+

It is possible for responses to have shorter lifetimes than the value set with this property if the response has a nextUpdate field that expires sooner than the cache lifetime. A value of zero or less for this property disables the cache lifetime. If an object has no nextUpdate value and cache lifetimes are disabled, then the response will not be cached.

+ 		3600 seconds (1 hour)
jdk.tls.stapling.responderURI +

Enables the administrator to set a default URI in the event that certificates used for TLS do not have the Authority Info Access (AIA) extension.

+

It will not override the Authority Info Access extension value unless the jdk.tls.stapling.responderOverride property is set.

+ 		Not set
jdk.tls.stapling.responderOverride +

Enables a URI provided through the jdk.tls.stapling.responderURI property to override any AIA extension value.

+ 		False
jdk.tls.stapling.ignoreExtensions +

Disables the forwarding of OCSP extensions specified in the status_request or status_request_v2 TLS extensions.

+ 		False
+ +
+

Other options

You can also use OpenSSL to create new private keys and generate certificate requests for your CA to issue new certificates. Also, check out the new Certificate Manager plugin, - which allows to setup a hotdeploy directory for new certificates deployment, which in turn combined with Let's Encrypt certbot + which allows to set up a hotdeploy directory for new certificates deployment, which in turn combined with Let's Encrypt certbot allows dynamic certificates renewal without administrator intervention.

diff --git a/documentation/style.css b/documentation/style.css index f7030e020e..78d7be49b1 100644 --- a/documentation/style.css +++ b/documentation/style.css @@ -338,6 +338,11 @@ fieldset { right: .5em; } +table.general { + margin-top: 3em; + margin-left: 3em; + border : 1px #ccc solid; +} table.dbtable { margin-top: 3em;