1 /* Licensed to the Apache Software Foundation (ASF) under one or more
2 * contributor license agreements. See the NOTICE file distributed with
3 * this work for additional information regarding copyright ownership.
4 * The ASF licenses this file to You under the Apache License, Version 2.0
5 * (the "License"); you may not use this file except in compliance with
6 * the License. You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
18 * _ __ ___ ___ __| | ___ ___| | mod_ssl
19 * | '_ ` _ \ / _ \ / _` | / __/ __| | Apache Interface to OpenSSL
20 * | | | | | | (_) | (_| | \__ \__ \ |
21 * |_| |_| |_|\___/ \__,_|___|___/___/_|
24 * Apache API interface structures
27 #include "ssl_private.h"
30 #include "util_mutex.h"
31 #include "ap_provider.h"
36 * the table of configuration directives we provide
39 #define SSL_CMD_ALL(name, args, desc) \
40 AP_INIT_##args("SSL"#name, ssl_cmd_SSL##name, \
41 NULL, RSRC_CONF|OR_AUTHCFG, desc),
43 #define SSL_CMD_SRV(name, args, desc) \
44 AP_INIT_##args("SSL"#name, ssl_cmd_SSL##name, \
45 NULL, RSRC_CONF, desc),
47 #define SSL_CMD_DIR(name, type, args, desc) \
48 AP_INIT_##args("SSL"#name, ssl_cmd_SSL##name, \
49 NULL, OR_##type, desc),
51 #define AP_END_CMD { NULL }
53 static const command_rec ssl_config_cmds[] = {
55 * Global (main-server) context configuration directives
57 SSL_CMD_SRV(PassPhraseDialog, TAKE1,
58 "SSL dialog mechanism for the pass phrase query "
59 "('builtin', '|/path/to/pipe_program', "
60 "or 'exec:/path/to/cgi_program')")
61 SSL_CMD_SRV(SessionCache, TAKE1,
62 "SSL Session Cache storage "
63 "('none', 'nonenotnull', 'dbm:/path/to/file')")
64 #if defined(HAVE_OPENSSL_ENGINE_H) && defined(HAVE_ENGINE_INIT)
65 SSL_CMD_SRV(CryptoDevice, TAKE1,
66 "SSL external Crypto Device usage "
69 SSL_CMD_SRV(RandomSeed, TAKE23,
70 "SSL Pseudo Random Number Generator (PRNG) seeding source "
71 "('startup|connect builtin|file:/path|exec:/path [bytes]')")
74 * Per-server context configuration directives
76 SSL_CMD_SRV(Engine, TAKE1,
77 "SSL switch for the protocol engine "
79 SSL_CMD_SRV(FIPS, FLAG,
80 "Enable FIPS-140 mode "
82 SSL_CMD_ALL(CipherSuite, TAKE1,
83 "Colon-delimited list of permitted SSL Ciphers "
84 "('XXX:...:XXX' - see manual)")
85 SSL_CMD_SRV(CertificateFile, TAKE1,
86 "SSL Server Certificate file "
87 "('/path/to/file' - PEM or DER encoded)")
88 SSL_CMD_SRV(CertificateKeyFile, TAKE1,
89 "SSL Server Private Key file "
90 "('/path/to/file' - PEM or DER encoded)")
91 SSL_CMD_SRV(CertificateChainFile, TAKE1,
92 "SSL Server CA Certificate Chain file "
93 "('/path/to/file' - PEM encoded)")
94 SSL_CMD_SRV(PKCS7CertificateFile, TAKE1,
95 "PKCS#7 file containing server certificate and chain"
96 " certificates ('/path/to/file' - PEM encoded)")
97 SSL_CMD_ALL(CACertificatePath, TAKE1,
98 "SSL CA Certificate path "
99 "('/path/to/dir' - contains PEM encoded files)")
100 SSL_CMD_ALL(CACertificateFile, TAKE1,
101 "SSL CA Certificate file "
102 "('/path/to/file' - PEM encoded)")
103 SSL_CMD_SRV(CADNRequestPath, TAKE1,
104 "SSL CA Distinguished Name path "
105 "('/path/to/dir' - symlink hashes to PEM of acceptable CA names to request)")
106 SSL_CMD_SRV(CADNRequestFile, TAKE1,
107 "SSL CA Distinguished Name file "
108 "('/path/to/file' - PEM encoded to derive acceptable CA names to request)")
109 SSL_CMD_SRV(CARevocationPath, TAKE1,
110 "SSL CA Certificate Revocation List (CRL) path "
111 "('/path/to/dir' - contains PEM encoded files)")
112 SSL_CMD_SRV(CARevocationFile, TAKE1,
113 "SSL CA Certificate Revocation List (CRL) file "
114 "('/path/to/file' - PEM encoded)")
115 SSL_CMD_ALL(VerifyClient, TAKE1,
116 "SSL Client verify type "
117 "('none', 'optional', 'require', 'optional_no_ca')")
118 SSL_CMD_ALL(VerifyDepth, TAKE1,
119 "SSL Client verify depth "
120 "('N' - number of intermediate certificates)")
121 SSL_CMD_SRV(SessionCacheTimeout, TAKE1,
122 "SSL Session Cache object lifetime "
123 "('N' - number of seconds)")
124 SSL_CMD_SRV(Protocol, RAW_ARGS,
125 "Enable or disable various SSL protocols"
126 "('[+-][SSLv2|SSLv3|TLSv1] ...' - see manual)")
127 SSL_CMD_SRV(HonorCipherOrder, FLAG,
128 "Use the server's cipher ordering preference")
129 SSL_CMD_SRV(InsecureRenegotiation, FLAG,
130 "Enable support for insecure renegotiation")
131 SSL_CMD_ALL(UserName, TAKE1,
132 "Set user name to SSL variable value")
133 SSL_CMD_SRV(StrictSNIVHostCheck, FLAG,
134 "Strict SNI virtual host checking")
137 * Proxy configuration for remote SSL connections
139 SSL_CMD_SRV(ProxyEngine, FLAG,
140 "SSL switch for the proxy protocol engine "
142 SSL_CMD_SRV(ProxyProtocol, RAW_ARGS,
143 "SSL Proxy: enable or disable SSL protocol flavors "
144 "('[+-][SSLv2|SSLv3|TLSv1] ...' - see manual)")
145 SSL_CMD_SRV(ProxyCipherSuite, TAKE1,
146 "SSL Proxy: colon-delimited list of permitted SSL ciphers "
147 "('XXX:...:XXX' - see manual)")
148 SSL_CMD_SRV(ProxyVerify, TAKE1,
149 "SSL Proxy: whether to verify the remote certificate "
151 SSL_CMD_SRV(ProxyVerifyDepth, TAKE1,
152 "SSL Proxy: maximum certificate verification depth "
153 "('N' - number of intermediate certificates)")
154 SSL_CMD_SRV(ProxyCACertificateFile, TAKE1,
155 "SSL Proxy: file containing server certificates "
156 "('/path/to/file' - PEM encoded certificates)")
157 SSL_CMD_SRV(ProxyCACertificatePath, TAKE1,
158 "SSL Proxy: directory containing server certificates "
159 "('/path/to/dir' - contains PEM encoded certificates)")
160 SSL_CMD_SRV(ProxyCARevocationPath, TAKE1,
161 "SSL Proxy: CA Certificate Revocation List (CRL) path "
162 "('/path/to/dir' - contains PEM encoded files)")
163 SSL_CMD_SRV(ProxyCARevocationFile, TAKE1,
164 "SSL Proxy: CA Certificate Revocation List (CRL) file "
165 "('/path/to/file' - PEM encoded)")
166 SSL_CMD_SRV(ProxyMachineCertificateFile, TAKE1,
167 "SSL Proxy: file containing client certificates "
168 "('/path/to/file' - PEM encoded certificates)")
169 SSL_CMD_SRV(ProxyMachineCertificatePath, TAKE1,
170 "SSL Proxy: directory containing client certificates "
171 "('/path/to/dir' - contains PEM encoded certificates)")
172 SSL_CMD_SRV(ProxyCheckPeerExpire, FLAG,
173 "SSL Proxy: check the peers certificate expiration date")
174 SSL_CMD_SRV(ProxyCheckPeerCN, FLAG,
175 "SSL Proxy: check the peers certificate CN")
178 * Per-directory context configuration directives
180 SSL_CMD_DIR(Options, OPTIONS, RAW_ARGS,
181 "Set one or more options to configure the SSL engine"
182 "('[+-]option[=value] ...' - see manual)")
183 SSL_CMD_DIR(RequireSSL, AUTHCFG, NO_ARGS,
184 "Require the SSL protocol for the per-directory context "
186 SSL_CMD_DIR(Require, AUTHCFG, RAW_ARGS,
187 "Require a boolean expression to evaluate to true for granting access"
188 "(arbitrary complex boolean expression - see manual)")
189 SSL_CMD_DIR(RenegBufferSize, AUTHCFG, TAKE1,
190 "Configure the amount of memory that will be used for buffering the "
191 "request body if a per-location SSL renegotiation is required due to "
192 "changed access control requirements")
194 SSL_CMD_SRV(OCSPEnable, FLAG,
195 "Enable use of OCSP to verify certificate revocation ('on', 'off')")
196 SSL_CMD_SRV(OCSPDefaultResponder, TAKE1,
197 "URL of the default OCSP Responder")
198 SSL_CMD_SRV(OCSPOverrideResponder, FLAG,
199 "Force use of the default responder URL ('on', 'off')")
201 #ifdef HAVE_OCSP_STAPLING
203 * OCSP Stapling options
205 SSL_CMD_SRV(StaplingCache, TAKE1,
206 "SSL Stapling Response Cache storage "
207 "(`dbm:/path/to/file')")
208 SSL_CMD_SRV(UseStapling, FLAG,
209 "SSL switch for the OCSP Stapling protocol " "(`on', `off')")
210 SSL_CMD_SRV(StaplingResponseTimeSkew, TAKE1,
211 "SSL stapling option for maximum time difference in OCSP responses")
212 SSL_CMD_SRV(StaplingResponderTimeout, TAKE1,
213 "SSL stapling option for OCSP responder timeout")
214 SSL_CMD_SRV(StaplingResponseMaxAge, TAKE1,
215 "SSL stapling option for maximum age of OCSP responses")
216 SSL_CMD_SRV(StaplingStandardCacheTimeout, TAKE1,
217 "SSL stapling option for normal OCSP Response Cache Lifetime")
218 SSL_CMD_SRV(StaplingReturnResponderErrors, FLAG,
219 "SSL stapling switch to return Status Errors Back to Client"
221 SSL_CMD_SRV(StaplingFakeTryLater, FLAG,
222 "SSL stapling switch to send tryLater response to client on error "
224 SSL_CMD_SRV(StaplingErrorCacheTimeout, TAKE1,
225 "SSL stapling option for OCSP Response Error Cache Lifetime")
226 SSL_CMD_SRV(StaplingForceURL, TAKE1,
227 "SSL stapling option to Force the OCSP Stapling URL")
230 /* Deprecated directives. */
231 AP_INIT_RAW_ARGS("SSLLog", ap_set_deprecated, NULL, OR_ALL,
232 "SSLLog directive is no longer supported - use ErrorLog."),
233 AP_INIT_RAW_ARGS("SSLLogLevel", ap_set_deprecated, NULL, OR_ALL,
234 "SSLLogLevel directive is no longer supported - use LogLevel."),
240 * the various processing hooks
242 static apr_status_t ssl_cleanup_pre_config(void *data)
245 * Try to kill the internals of the SSL library.
248 #if OPENSSL_VERSION_NUMBER >= 0x00907001
249 /* Corresponds to OPENSSL_load_builtin_modules():
250 * XXX: borrowed from apps.h, but why not CONF_modules_free()
251 * which also invokes CONF_modules_finish()?
253 CONF_modules_unload(1);
256 /* Corresponds to SSL_library_init: */
258 #if HAVE_ENGINE_LOAD_BUILTIN_ENGINES
263 /* Don't call ERR_free_strings here; ERR_load_*_strings only
264 * actually load the error strings once per process due to static
265 * variable abuse in OpenSSL. */
267 /* Also don't call CRYPTO_cleanup_all_ex_data here; any registered
268 * ex_data indices may have been cached in static variables in
269 * OpenSSL; removing them may cause havoc. Notably, with OpenSSL
270 * versions >= 0.9.8f, COMP_CTX cleanups would not be run, which
271 * could result in a per-connection memory leak (!). */
274 * TODO: determine somewhere we can safely shove out diagnostics
275 * (when enabled) at this late stage in the game:
276 * CRYPTO_mem_leaks_fp(stderr);
281 static int ssl_hook_pre_config(apr_pool_t *pconf,
285 /* We must register the library in full, to ensure our configuration
286 * code can successfully test the SSL environment.
288 CRYPTO_malloc_init();
290 ERR_load_crypto_strings();
292 SSL_load_error_strings();
294 #if HAVE_ENGINE_LOAD_BUILTIN_ENGINES
295 ENGINE_load_builtin_engines();
298 OpenSSL_add_all_algorithms();
299 #if OPENSSL_VERSION_NUMBER >= 0x00907001
300 OPENSSL_load_builtin_modules();
305 * Let us cleanup the ssl library when the module is unloaded
307 apr_pool_cleanup_register(pconf, NULL, ssl_cleanup_pre_config,
308 apr_pool_cleanup_null);
310 /* Register us to handle mod_log_config %c/%x variables */
311 ssl_var_log_config_register(pconf);
313 /* Register to handle mod_status status page generation */
314 ssl_scache_status_register(pconf);
316 /* Register mutex type names so they can be configured with Mutex */
317 ap_mutex_register(pconf, SSL_CACHE_MUTEX_TYPE, NULL, APR_LOCK_DEFAULT, 0);
318 #ifdef HAVE_OCSP_STAPLING
319 ap_mutex_register(pconf, SSL_STAPLING_MUTEX_TYPE, NULL, APR_LOCK_DEFAULT, 0);
325 static SSLConnRec *ssl_init_connection_ctx(conn_rec *c)
327 SSLConnRec *sslconn = myConnConfig(c);
333 sslconn = apr_pcalloc(c->pool, sizeof(*sslconn));
335 sslconn->server = c->base_server;
337 myConnConfigSet(c, sslconn);
342 int ssl_proxy_enable(conn_rec *c)
346 SSLConnRec *sslconn = ssl_init_connection_ctx(c);
347 sc = mySrvConfig(sslconn->server);
349 if (!sc->proxy_enabled) {
350 ap_log_cerror(APLOG_MARK, APLOG_ERR, 0, c,
351 "SSL Proxy requested for %s but not enabled "
352 "[Hint: SSLProxyEngine]", sc->vhost_id);
357 sslconn->is_proxy = 1;
358 sslconn->disabled = 0;
363 int ssl_engine_disable(conn_rec *c)
367 SSLConnRec *sslconn = myConnConfig(c);
370 sc = mySrvConfig(sslconn->server);
373 sc = mySrvConfig(c->base_server);
375 if (sc->enabled == SSL_ENABLED_FALSE) {
379 sslconn = ssl_init_connection_ctx(c);
381 sslconn->disabled = 1;
386 int ssl_init_ssl_connection(conn_rec *c, request_rec *r)
390 SSLConnRec *sslconn = myConnConfig(c);
396 sslconn = ssl_init_connection_ctx(c);
398 server = sslconn->server;
399 sc = mySrvConfig(server);
402 * Seed the Pseudo Random Number Generator (PRNG)
404 ssl_rand_seed(server, c->pool, SSL_RSCTX_CONNECT, "");
406 mctx = sslconn->is_proxy ? sc->proxy : sc->server;
409 * Create a new SSL connection with the configured server SSL context and
410 * attach this to the socket. Additionally we register this attachment
411 * so we can detach later.
413 if (!(ssl = SSL_new(mctx->ssl_ctx))) {
414 ap_log_cerror(APLOG_MARK, APLOG_ERR, 0, c,
415 "Unable to create a new SSL connection from the SSL "
417 ssl_log_ssl_error(SSLLOG_MARK, APLOG_ERR, server);
421 return DECLINED; /* XXX */
424 vhost_md5 = ap_md5_binary(c->pool, (unsigned char *)sc->vhost_id,
427 if (!SSL_set_session_id_context(ssl, (unsigned char *)vhost_md5,
428 APR_MD5_DIGESTSIZE*2))
430 ap_log_cerror(APLOG_MARK, APLOG_ERR, 0, c,
431 "Unable to set session id context to '%s'", vhost_md5);
432 ssl_log_ssl_error(SSLLOG_MARK, APLOG_ERR, server);
436 return DECLINED; /* XXX */
439 SSL_set_app_data(ssl, c);
440 SSL_set_app_data2(ssl, NULL); /* will be request_rec */
445 * Configure callbacks for SSL connection
447 SSL_set_tmp_rsa_callback(ssl, ssl_callback_TmpRSA);
448 SSL_set_tmp_dh_callback(ssl, ssl_callback_TmpDH);
449 #ifndef OPENSSL_NO_EC
450 SSL_set_tmp_ecdh_callback(ssl, ssl_callback_TmpECDH);
453 SSL_set_verify_result(ssl, X509_V_OK);
455 ssl_io_filter_init(c, r, ssl);
460 static const char *ssl_hook_http_scheme(const request_rec *r)
462 SSLSrvConfigRec *sc = mySrvConfig(r->server);
464 if (sc->enabled == SSL_ENABLED_FALSE || sc->enabled == SSL_ENABLED_OPTIONAL) {
471 static apr_port_t ssl_hook_default_port(const request_rec *r)
473 SSLSrvConfigRec *sc = mySrvConfig(r->server);
475 if (sc->enabled == SSL_ENABLED_FALSE || sc->enabled == SSL_ENABLED_OPTIONAL) {
482 static int ssl_hook_pre_connection(conn_rec *c, void *csd)
485 SSLConnRec *sslconn = myConnConfig(c);
488 sc = mySrvConfig(sslconn->server);
491 sc = mySrvConfig(c->base_server);
494 * Immediately stop processing if SSL is disabled for this connection
496 if (!(sc && (sc->enabled == SSL_ENABLED_TRUE ||
497 (sslconn && sslconn->is_proxy))))
506 sslconn = ssl_init_connection_ctx(c);
509 if (sslconn->disabled) {
514 * Remember the connection information for
515 * later access inside callback functions
518 ap_log_cerror(APLOG_MARK, APLOG_INFO, 0, c,
519 "Connection to child %ld established "
520 "(server %s)", c->id, sc->vhost_id);
522 return ssl_init_ssl_connection(c, NULL);
526 * the module registration phase
529 static void ssl_register_hooks(apr_pool_t *p)
531 /* ssl_hook_ReadReq needs to use the BrowserMatch settings so must
532 * run after mod_setenvif's post_read_request hook. */
533 static const char *pre_prr[] = { "mod_setenvif.c", NULL };
535 ssl_io_filter_register(p);
537 ap_hook_pre_connection(ssl_hook_pre_connection,NULL,NULL, APR_HOOK_MIDDLE);
538 ap_hook_test_config (ssl_hook_ConfigTest, NULL,NULL, APR_HOOK_MIDDLE);
539 ap_hook_post_config (ssl_init_Module, NULL,NULL, APR_HOOK_MIDDLE);
540 ap_hook_http_scheme (ssl_hook_http_scheme, NULL,NULL, APR_HOOK_MIDDLE);
541 ap_hook_default_port (ssl_hook_default_port, NULL,NULL, APR_HOOK_MIDDLE);
542 ap_hook_pre_config (ssl_hook_pre_config, NULL,NULL, APR_HOOK_MIDDLE);
543 ap_hook_child_init (ssl_init_Child, NULL,NULL, APR_HOOK_MIDDLE);
544 ap_hook_check_authn (ssl_hook_UserCheck, NULL,NULL, APR_HOOK_FIRST,
545 AP_AUTH_INTERNAL_PER_CONF);
546 ap_hook_fixups (ssl_hook_Fixup, NULL,NULL, APR_HOOK_MIDDLE);
547 ap_hook_check_access (ssl_hook_Access, NULL,NULL, APR_HOOK_MIDDLE,
548 AP_AUTH_INTERNAL_PER_CONF);
549 ap_hook_check_authz (ssl_hook_Auth, NULL,NULL, APR_HOOK_MIDDLE,
550 AP_AUTH_INTERNAL_PER_CONF);
551 ap_hook_post_read_request(ssl_hook_ReadReq, pre_prr,NULL, APR_HOOK_MIDDLE);
555 APR_REGISTER_OPTIONAL_FN(ssl_proxy_enable);
556 APR_REGISTER_OPTIONAL_FN(ssl_engine_disable);
558 ap_register_auth_provider(p, AUTHZ_PROVIDER_GROUP, "ssl",
559 AUTHZ_PROVIDER_VERSION,
560 &ssl_authz_provider_require_ssl,
561 AP_AUTH_INTERNAL_PER_CONF);
563 ap_register_auth_provider(p, AUTHZ_PROVIDER_GROUP, "ssl-verify-client",
564 AUTHZ_PROVIDER_VERSION,
565 &ssl_authz_provider_verify_client,
566 AP_AUTH_INTERNAL_PER_CONF);
570 module AP_MODULE_DECLARE_DATA ssl_module = {
571 STANDARD20_MODULE_STUFF,
572 ssl_config_perdir_create, /* create per-dir config structures */
573 ssl_config_perdir_merge, /* merge per-dir config structures */
574 ssl_config_server_create, /* create per-server config structures */
575 ssl_config_server_merge, /* merge per-server config structures */
576 ssl_config_cmds, /* table of configuration directives */
577 ssl_register_hooks /* register hooks */