From af5500c45bf8683fcbdcd9780aea9a018ee9d24b Mon Sep 17 00:00:00 2001 From: Prarthona Paul Date: Tue, 23 Apr 2024 12:53:23 -0400 Subject: [PATCH] [WFLY-19269] OCSP stapling support --- elytron/WFLY-19269-OCSP-stapling-support.adoc | 199 ++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 elytron/WFLY-19269-OCSP-stapling-support.adoc diff --git a/elytron/WFLY-19269-OCSP-stapling-support.adoc b/elytron/WFLY-19269-OCSP-stapling-support.adoc new file mode 100644 index 00000000..fee9e5d5 --- /dev/null +++ b/elytron/WFLY-19269-OCSP-stapling-support.adoc @@ -0,0 +1,199 @@ +--- +categories: +# Add any category for this proposal +# if missing, add it to _data/widfly-categories and use its id +--- += [Experimental|Preview|Community|default]Template +:author: Prarthona Paul +:email: prpaul@redhat.com +:toc: left +:icons: font +:idprefix: +:idseparator: - + +== Overview +Online Certificate Status Protocol (OCSP) is one of the methods of checking whether or not a certificate presented by a client is valid or not. It is a protocol for determining the status of a certificate and is described in http://www.ietf.org/rfc/rfc2560.txt[RFC 2560]. +There are two methods of checking the revocation status of certificates: Certificate Revocation List(s), and through OCSP, Currently WildFly server allows for both CRLs and traditional OCSP. However, it does not have support for OCSP stapling. + +Traditional OCSP relies on the client to communicate with the OCSP server upon receiving a certificate to query the revocation status of the certificate. While this is still a valid approach, it impacts performance and privacy due to the direct client queries. OCSP stapling helps with this, as the server takes the responsibility of querying the CA's OCSP responder and "staples" the response to the certificate when sharing it during a TLS handshake. This feature implements the stapling support for OCSP for TLS handshakes. + +Benefits of OCSP stapling includes improved performance due to lower delays during OCSP SSL negotiation as there is no need for a separate network connection to a CA's responder. Additionally, the ability to cache the responses can also improve performance. Lastly, since OCSP stapling requires WildFly to directly send revocation requests to the Certificate Authority, this addressed any privacy concerns with the traditional approach. + +== Issue Metadata + +=== Issue + +* https://issues.redhat.com/browse/WFCORE[WFCORE-XXXX] + +=== Related Issues + +* https://issues.redhat.com/browse/WFLY-19269[WFLY-19269] +* https://issues.redhat.com/browse/ELY-434[ELY-434] + +=== Stability Level +// Choose the planned stability level for the proposed functionality +* [ ] Experimental + +* [x] Preview + +* [ ] Community + +* [ ] default + +=== Dev Contacts + +* mailto:{email}[{author}] + +=== QE Contacts + +=== Testing By +// Put an x in the relevant field to indicate if testing will be done by Engineering or QE. +// Discuss with QE during the Kickoff state to decide this +* [x] Engineering + +* [ ] QE + +=== Affected Projects or Components + +=== Other Interested Projects + +=== Relevant Installation Types +// Remove the x next to the relevant field if the feature in question is not relevant +// to that kind of WildFly installation +* [x] Traditional standalone server (unzipped or provisioned by Galleon) + +* [x] Managed domain + +* [x] OpenShift s2i + +* [x] Bootable jar + +== Requirements + +=== Hard Requirements +* Existing OCSP support for WildFly's Elytron subsystem would be extended to allow for OCSP stapling. A new attribute, called `enable-stapling`, would be added to `elytron/key-manager` to allow for stapling support. + +** This attribute would be of type boolean. To allow for backwards compatibility, this attribute's value would be false by default, which would allow for traditional OCSP support. + +Current Subsystem Configuration: +``` + + + + +``` + +Proposed Subsystem Configuration: +``` + + + + +``` + +* This feature would make use of the existing `X509RevocationTrustManager` class to check the revocation status of the certificate. + +** This class makes use of the https://docs.oracle.com/javase/8/docs/api/java/security/cert/PKIXRevocationChecker.html[PKIXRevocationChecker] class, which checks the revocation status of the PKIX algorithm. + +** This response is sent to the client using the `Certificate Status Request` extension response defined in https://datatracker.ietf.org/doc/html/rfc6961[RFC 6961]. + +* The Elytron Client Configurations would be updated to also add a new element under the `ssl-context` tag to add the a configuration to enable OCSP stapling. + +** This functionality would be the same as server configuration, and the default value for this would be set to `false`. + +** Elytron Client Configuration schema would need to be bumped to version 1.8. + +Current client configuration: +``` + + + + + + +``` + +Proposed client configuration: +``` + + + + + + +``` + +=== Nice-to-Have Requirements +// Requirements in this section do not have to be met to merge the proposed functionality. +// Note: Nice-to-have requirements that don't end up being implemented as part of +// the work covered by this proposal should be moved to the 'Future Work' section. +* The response from the OCSP responder may be cached to avoid redundant and repeated queries to the CA, and improve performance. + +=== Non-Requirements +// Use this section to explicitly discuss things that readers might think are required +// but which are not required. + +=== Future Work +// Use this section to discuss requirements that are not addressed by this proposal +// but which may be addressed in later proposals. + +== Backwards Compatibility + +// Does this enhancement affect backwards compatibility with previously released +// versions of WildFly? +// Can the identified incompatibility be avoided? +* For backwards compatibility, the `enable-stapling` attribute (element for Elytron client configuration) would be set to `false` by default to allow for traditional OCSP if that is enabled as the primary or the fall-back revocation checking protocol. + +=== Default Configuration +* The `enable-stapling` attribute (element for Elytron client configuration) would be set to `false` by default to allow for traditional OCSP if that is enabled as the primary or the fall-back revocation checking protocol. + +=== Importing Existing Configuration + +=== Deployments + +=== Interoperability + +//== Implementation Plan +//// +Delete if not needed. The intent is if you have a complex feature which can +not be delivered all in one go to suggest the strategy. If your feature falls +into this category, please mention the Release Coordinators on the pull +request so they are aware. +//// + +== Security Considerations + +//// +Identification if any security implications that may need to be considered with this feature +or a confirmation that there are no security implications to consider. +//// + +* This feature would improve the privacy of revocation checking as the CA would be receiving queries directly from the server, as opposed to the client. +* The performance would also be improved due to reduced latencies during the TLS handshake. +** Additional performance improvements can be achieved through caching. + +== Test Plan + +* Tests for OCSP stapling would be implemented using a mock OCSP provider inside the Elytron TestSuite. +* Additional integration tests may be added to the WildFly Core testsuite. +* Client configuration tests may be added to check for parsing. + +== Community Documentation +//// +Generally a feature should have documentation as part of the PR to wildfly master, or as a follow up PR if the feature is in wildfly-core. In some cases though the documentation belongs more in a component, or does not need any documentation. Indicate which of these will happen. +//// + +* Documentation will be added in the "Configure OCSP certificate revocation" section in the WildFly documentation to indicate that OCSP stapling can be used by defining the `enable-stapling` attribute. The documentation should mention the limitations around communications with the Certificate Authority's OCSP responder. + +* The ` - WildFly Elytron` section of the WildFly Client Configuration Guide would also be updated with information on how to enable OCSP stapling for the Elytron Client. + +== Release Note Content +//// +Draft verbiage for up to a few sentences on the feature for inclusion in the +Release Note blog article for the release that first includes this feature. +Example article: http://wildfly.org/news/2018/08/30/WildFly14-Final-Released/. +This content will be edited, so there is no need to make it perfect or discuss +what release it appears in. "See Overview" is acceptable if the overview is +suitable. For simple features best covered as an item in a bullet-point list +of features containing a few words on each, use "Bullet point: " +//// \ No newline at end of file