Adding more ap_ssl_* functions and hooks to the core server.

     - ap_ssl_add_cert_files() to enable other modules like mod_md to provide
       certificate and keys for an SSL module like mod_ssl.
     - ap_ssl_add_fallback_cert_files() to enable other modules like mod_md to
       provide a fallback certificate in case no 'proper' certificate is
       available for an SSL module like mod_ssl.
     - ap_ssl_answer_challenge() to enable other modules like mod_md to
       provide a certificate as used in the RFC 8555 'tls-alpn-01' challenge
       for the ACME protocol for an SSL module like mod_ssl.
    - Hooks for 'ssl_add_cert_files', 'ssl_add_fallback_cert_files' and
      'ssl_answer_challenge' where modules like mod_md can provide providers
      to the above mentioned functions.



git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1887085 13f79535-47bb-0310-9956-ffa450edef68

2 files changed, 87 insertions, 1 deletions

diff --git a/include/ap_mmn.h b/include/ap_mmn.h
index f6a6d2597a..1106c2f37e 100644
--- a/include/ap_mmn.h
+++ b/include/ap_mmn.h
@@ -665,6 +665,7 @@
  * 20200705.4 (2.5.1-dev)  Add ap_get_status_line_ex()
  * 20201214.0 (2.5.1-dev)  Axe struct core_net_rec
  * 20201214.1 (2.5.1-dev)  Add ap_ssl_conn_is_ssl()/ap_ssl_var_lookup() and hooks
+ * 20201214.2 (2.5.1-dev)  Add ap_ssl_add_cert_files, ap_ssl_add_fallback_cert_files
  */
 
 #define MODULE_MAGIC_COOKIE 0x41503235UL /* "AP25" */
@@ -672,7 +673,7 @@
 #ifndef MODULE_MAGIC_NUMBER_MAJOR
 #define MODULE_MAGIC_NUMBER_MAJOR 20201214
 #endif
-#define MODULE_MAGIC_NUMBER_MINOR 1             /* 0...n */
+#define MODULE_MAGIC_NUMBER_MINOR 2             /* 0...n */
 
 /**
  * Determine if the server's current MODULE_MAGIC_NUMBER is at least a
diff --git a/include/http_protocol.h b/include/http_protocol.h
index 5c57a85181..c4f064a7c8 100644
--- a/include/http_protocol.h
+++ b/include/http_protocol.h
@@ -1108,6 +1108,91 @@ AP_DECLARE(const char *) ap_ssl_var_lookup(apr_pool_t *p, server_rec *s,
                                            conn_rec *c, request_rec *r,
                                            const char *name);                                           
 
+/**
+ * Register to provide certificate/key files for servers. Certificate files are
+ * exepcted to contain the certificate chain, beginning with the server's certificate,
+ * excluding the trust anchor, in PEM format. 
+ * They must be accompanied by a private key file, also in PEM format.
+ *  
+ * @param s the server certificates are collected for
+ * @param p the pool to use for allocations
+ * @param cert_file and array of const char* with the path to the certificate chain
+ * @param key_file and array of const char* with the path to the private key file
+ * @return OK if files were added, DECLINED if not, or other for error.
+ */
+
+AP_DECLARE_HOOK(int, ssl_add_cert_files, (server_rec *s, apr_pool_t *p,
+                                          apr_array_header_t *cert_files,
+                                          apr_array_header_t *key_files))
+
+/**
+ * Collect certificate/key files from all providers registered. This includes
+ * providers registered at the global 'ssl_add_cert_files', as well as those
+ * installed in the OPTIONAL 'ssl_add_cert_files' hook as may be provided by 
+ * ssl modules.
+ *  
+ * @param s the server certificates are collected for
+ * @param p the pool to use for allocations
+ * @param cert_file and array of const char* with the path to the certificate chain
+ * @param key_file and array of const char* with the path to the private key file
+ */
+AP_DECLARE(apr_status_t) ap_ssl_add_cert_files(server_rec *s, apr_pool_t *p,
+                                               apr_array_header_t *cert_files,
+                                               apr_array_header_t *key_files);         
+
+
+/** 
+ * Register to provide 'fallback' certificates in case no 'real' certificates
+ * have been configured/added by other providers. Modules using these certificates
+ * are encouraged to answer requests to this server with a 503 response code.
+ * 
+ * @param s the server certificates are collected for
+ * @param p the pool to use for allocations
+ * @param cert_file and array of const char* with the path to the certificate chain
+ * @param key_file and array of const char* with the path to the private key file
+ * @return OK if files were added, DECLINED if not, or other for error.
+ */
+AP_DECLARE_HOOK(int, ssl_add_fallback_cert_files, (server_rec *s, apr_pool_t *p,
+                                                   apr_array_header_t *cert_files,
+                                                   apr_array_header_t *key_files))
+
+/**
+ * Collect 'fallback' certificate/key files from all registered providers, either
+ * in the global 'ssl_add_fallback_cert_files' hook or the optional one of similar
+ * name as provided by mod_ssl and sorts.
+ * Certificates obtained this way are commonly self signed, temporary crutches.
+ * To be used to the time it takes to retrieve a 'read', trusted certificate. 
+ * A module using fallbacks is encouraged to answer all requests with a 503.
+ * 
+ * @param s the server certificates are collected for
+ * @param p the pool to use for allocations
+ * @param cert_file and array of const char* with the path to the certificate chain
+ * @param key_file and array of const char* with the path to the private key file
+ */
+AP_DECLARE(apr_status_t) ap_ssl_add_fallback_cert_files(server_rec *s, apr_pool_t *p,
+                                                        apr_array_header_t *cert_files,
+                                                        apr_array_header_t *key_files);         
+
+
+/** 
+ * On TLS connections that do not relate to a configured virtual host,
+ * allow modules to provide a certificate and key to
+ * be used on the connection. 
+ */
+AP_DECLARE_HOOK(int, ssl_answer_challenge, (conn_rec *c, const char *server_name, 
+                                            const char **pcert_file, const char **pkey_file))
+
+/**
+ * Returns != 0 iff the connection is a challenge to the server, for example
+ * as defined in RFC 8555 for the 'tls-alpn-01' domain verification, and needs
+ * a specific certificate as answer in the handshake.
+ * ALPN protocol negotiation via the hooks 'protocol_propose' and 'protocol_switch'
+ * need to have run before this call is made.
+ */
+AP_DECLARE(int) ap_ssl_answer_challenge(conn_rec *c, const char *server_name, 
+                                        const char **pcert_file, const char **pkey_file);
+
+
 #ifdef __cplusplus
 }
 #endif