[WFCORE-5744] Improve key-store certificate health checks

elytron/WFCORE-5744-ssl-certificate-expiration-warning.adoc

@@ -0,0 +1,223 @@
+---
+categories:
+ - core
+ - management
+ - elytron
+# Specify the stability level of the feature.
+# Values can be one of: experimental preview community default
+stability-level: community
+issue:
+ - https://github.com/wildfly/wildfly-proposals/issues/685
+feature-team:
+ developer: bbaranow@redhat.com
+ sme:
+  - dlofthou@redhat.com
+ outside-perspective:
+  - frainone@redhat.com
+  - ropalka@redhat.com
+# If this issue tracks the promotion to a higher stability level of a previously
+# completed feature, provide the URL of the https://github.com/wildfly/wildfly-proposals/issues
+# issue that was used to track the previous feature.
+promotes:
+# This should be blank during initial development of a feature. It may be used
+# after the feature is completed if a subsequent issue is field to track promotion
+# of this feature to a higher stability level
+promoted-by:
+---
+= Display warning for expiring ssl ceritificates
+:author:            Bartosz Baranowski
+:email:             bbaranow@redhat.com
+:toc:               left
+:icons:             font
+:idprefix:
+:idseparator:       -
+
+__<The entire document should be one to two pages long. We will write each analysis document as if it is a conversation with a future developer. This requires a good writing style, with full sentences organized into paragraphs. Bullets are acceptable only for visual style, not as an excuse for writing sentence fragments.>__
+
+== Overview
+
+Goal of this RFE is two fold, to formalize and improve ways to get feedback on state of SSL certificates in server and to add periodic check, based on configuration.
+
+Periodic check is more or less self explanatory. Currently upon startup elytron subsystem will will print out information about certificates that expired. There are few problems with this. Firstly its exception driven and lacks a bit of information( ie keystore). Secondly its one-off on startup, this operation potentially should be performed periodically.
+
+Secondly currently there exist dedicated command _should-renew-certificate(date_date_to_check)_ . It would be good to provide such detail along with _read-alias/s_ command output.
+The _read-alias_ will will provide health indication with fixed TTL( of 7 days at least), while _should-renew-certificate_ will allow detailed inerogration on certificate health.
+
+
+=== User Stories
+
+Long runing server, with periodic information on certificates will allow admins to not only setup tools to warn them about potential security risk, but also schedule maintanence window based on this.
+
+== Issue Metadata
+
+
+
+=== Related Issues
+
+* https://issues.redhat.com/browse/WFCORE-5744[WFCORE-5744]
+
+=== Affected Projects or Components
+
+ * Elytron integration
+
+=== Other Interested Projects
+
+=== Relevant Installation Types
+
+* Traditional standalone server (unzipped or provisioned by Galleon)
+* Managed domain
+* OpenShift Source-to-Image (S2I)
+* Bootable jar
+
+== Requirements
+
+ * create output format that is not driven by exception, so possibly it can be easily digested via log munching, mail notification or any other mechanism users see fit to employ over log handler.
+ * read-alias command will have additional KVP "Validity=[valid, EXPIRED, about to expire, not yet]"
+ ** Validity semantics:
+ *** not yet - ceritifacete is still too young
+ *** EXPIRED - current date is after expiration
+ *** about to expire - certificate is still valid. currentData+expiration-watermark.after(cert.getNotAfter))
+ *** valid - anything else not covered above
+ * add config options to handle:
+ ** frequency of warning(expiration-check-delay)
+ *** 0 - turn off - one time check on startup as in previous version
+ *** n+ - minutes between periodic checks
+ *** Default value: 12h
+ *** Unit: minutes
+ ** expiration threshold(expiration-watermark)
+ *** attribute (expressed in minutes) which will mark control how much time till expiration is considered degradation of health(warning)
+ *** Default value: 7 days
+ *** Unit: minutes
+
+=== Changed requirements
+
+N/A
+
+
+=== Non-Requirements
+
+N/A
+
+=== Future Work
+
+N/A
+
+== Backwards Compatibility
+
+No. This feature should not introduce incompatibility, since its just logging, which is simple config adjustment.
+
+NOTE: above is subject to change based on feedback( default to 0, turn-off periodic so its essentially like this change wasnt introduced)
+
+=== Default Configuration
+
+__<Does the proposed work change the default value of any current configuration attributes? Does it change the configuration generated by any current Galleon layers?>__
+
+=== Importing Existing Configuration
+
+Should default to predefined values.
+
+=== Deployments
+
+No impact.
+
+=== Interoperability
+
+__<Is this feature impacting interoperability?>__
+No.
+
+== Implementation Plan
+
+N/A
+
+== Admin Clients
+
+CLI should not be affected. However, HAL will most likely require follow up, since this feature will introduce new model params/context. Given defaults, its not a breaking change.
+
+== Security Considerations
+
+Slightly increase security risk compared to current state. If attacker has access to log/events it will provide view of current health of server, rather than possible peek on startup. Convenient, but not something that could not be circumvented without this feature.
+
+[[test_plan]]
+== Test Plan
+
+Integration tests should be fairly acceptable.
+
+=== Manual Test
+
+==== Defined keystore
+* Generate certificates:
+
+[quote, shell]
+----
+keytool -genkeypair -alias localhost -keyalg RSA -keysize 2048 -validity 1 -keystore server.keystore -dname "cn=Server Administrator,o=Acme,c=GB" -keypass secret -storepass secret
+keytool -genkeypair -alias drone-1-1 -keyalg RSA -keysize 2048 -validity 365 -keystore server.keystore -dname "cn=Server Administrator,o=Acme,c=GB" -keypass secret -storepass secret
+keytool -v -list -keystore server.keystore
+keytool -importkeystore -srckeystore server.keystore -destkeystore server.keystore -deststoretype pkcs12
+cp server.keystore ${SRV_HOME}/standalone/configuration/
+----
+
+* Enable keystore:
+
+[quote, JBoss CLI]
+----
+/subsystem=elytron/key-store=demoKeyStore:add(path=server.keystore,relative-to=jboss.server.config.dir, credential-reference={clear-text=secret},type=JKS)
+/subsystem=elytron/key-manager=demoKeyManager:add(key-store=demoKeyStore,credential-reference={clear-text=secret})
+/subsystem=elytron/server-ssl-context=demoSSLContext:add(key-manager=demoKeyManager,protocols=["TLSv1.2"])
+/subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=ssl-context,value=demoSSLContext)
+:reload
+----
+
+===== Periodic
+
+* Keystore config:
+
+[quote, JBoss CLI]
+----
+/subsystem=elytron/key-store=demoKeyManager:write-attribute(name=expiration-check-delay, value=1000)
+/subsystem=elytron/key-store=demoKeyManager:write-attribute(name=expiration-watermark, value=60)
+:reload
+----
+
+
+===== Read alias
+
+[quote, JBoss CLI]
+----
+/subsystem=elytron/key-store=demoKeyStore:read-alias(alias=localhost)
+----
+
+[quote, JBoss CLI]
+----
+{
+    "outcome" => "success",
+    "result" => {
+        "alias" => "localhost",
+        "entry-type" => "PrivateKeyEntry",
+        "creation-date" => "2025-02-11T15:25:40.316+0100",
+        "certificate-chain" => [{
+            "type" => "X.509",
+            "algorithm" => "RSA",
+            "format" => "X.509",
+            "public-key" => "...",
+            ...
+            "not-before" => "2025-02-11T15:22:47.000+0100",
+            "not-after" => "2025-02-12T15:22:47.000+0100",
+            ...
+            "validity" => "EXPIRED"
+        }]
+    }
+}
+----
+
+* Global config:
+
+== Community Documentation
+
+Model/XSD description should be enough as change is not deep and only introudce simple config parameter and additional output KVP in existing command.
+However, it might be good to have dedicated paragraph explaining change, since in current proposal periodic check is active.
+
+== 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: https://www.wildfly.org/news/2024/01/25/WildFly31-Released/.__
+__This content will be edited, so there is no need to make it perfect or discuss what release it appears in.>__