source: mod_gnutls/src/gnutls_hooks.c @ cb6476c

debian/masterproxy-ticket
Last change on this file since cb6476c was cb6476c, checked in by Fiona Klute <fiona.klute@…>, 2 years ago

Enable OCSP stapling by default if possible

If the user hasn't explicitly disabled OCSP stapling try to enable it,
and disable if that fails.

  • Property mode set to 100644
File size: 79.2 KB
Line 
1/*
2 *  Copyright 2004-2005 Paul Querna
3 *  Copyright 2008, 2014 Nikos Mavrogiannopoulos
4 *  Copyright 2011 Dash Shendy
5 *  Copyright 2013-2014 Daniel Kahn Gillmor
6 *  Copyright 2015-2018 Fiona Klute
7 *
8 *  Licensed under the Apache License, Version 2.0 (the "License");
9 *  you may not use this file except in compliance with the License.
10 *  You may obtain a copy of the License at
11 *
12 *      http://www.apache.org/licenses/LICENSE-2.0
13 *
14 *  Unless required by applicable law or agreed to in writing, software
15 *  distributed under the License is distributed on an "AS IS" BASIS,
16 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17 *  See the License for the specific language governing permissions and
18 *  limitations under the License.
19 */
20
21#include "mod_gnutls.h"
22#include "gnutls_cache.h"
23#include "gnutls_config.h"
24#include "gnutls_ocsp.h"
25#include "gnutls_util.h"
26#include "gnutls_watchdog.h"
27
28#include "http_vhost.h"
29#include "ap_mpm.h"
30#include "mod_status.h"
31#include <util_mutex.h>
32#include <apr_escape.h>
33
34#ifdef ENABLE_MSVA
35#include <msv/msv.h>
36#endif
37
38#ifdef APLOG_USE_MODULE
39APLOG_USE_MODULE(gnutls);
40#endif
41
42#if MOD_GNUTLS_DEBUG
43static apr_file_t *debug_log_fp;
44#endif
45
46#define IS_PROXY_STR(c) \
47    ((c->is_proxy == GNUTLS_ENABLED_TRUE) ? "proxy " : "")
48
49/** Key to encrypt session tickets. Must be kept secret. This key is
50 * generated in the `pre_config` hook and thus constant across
51 * forks. The problem with this approach is that it does not support
52 * regular key rotation. */
53static gnutls_datum_t session_ticket_key = {NULL, 0};
54
55static int mgs_cert_verify(request_rec * r, mgs_handle_t * ctxt);
56/* use side==0 for server and side==1 for client */
57static void mgs_add_common_cert_vars(request_rec * r, gnutls_x509_crt_t cert, int side, size_t export_cert_size);
58static int mgs_status_hook(request_rec *r, int flags);
59#ifdef ENABLE_MSVA
60static const char* mgs_x509_construct_uid(request_rec * pool, gnutls_x509_crt_t cert);
61#endif
62static int load_proxy_x509_credentials(apr_pool_t *pconf, apr_pool_t *ptemp, server_rec *s)
63    __attribute__((nonnull));
64
65/* Pool Cleanup Function */
66apr_status_t mgs_cleanup_pre_config(void *data __attribute__((unused)))
67{
68    /* Free session ticket master key */
69#if GNUTLS_VERSION_NUMBER >= 0x030400
70    gnutls_memset(session_ticket_key.data, 0, session_ticket_key.size);
71#endif
72    gnutls_free(session_ticket_key.data);
73    session_ticket_key.data = NULL;
74    session_ticket_key.size = 0;
75    return APR_SUCCESS;
76}
77
78/* Logging Function for Maintainers */
79#if MOD_GNUTLS_DEBUG
80static void gnutls_debug_log_all(int level, const char *str) {
81    apr_file_printf(debug_log_fp, "<%d> %s", level, str);
82}
83#define _gnutls_log apr_file_printf
84#else
85#define _gnutls_log(...)
86#endif
87
88static const char* mgs_readable_cvm(mgs_client_verification_method_e m) {
89    switch(m) {
90    case mgs_cvm_unset:
91        return "unset";
92    case mgs_cvm_cartel:
93        return "cartel";
94    case mgs_cvm_msva:
95        return "msva";
96    }
97    return "unknown";
98}
99
100/* Pre-Configuration HOOK: Runs First */
101int mgs_hook_pre_config(apr_pool_t * pconf, apr_pool_t * plog, apr_pool_t * ptemp __attribute__((unused))) {
102
103/* Maintainer Logging */
104#if MOD_GNUTLS_DEBUG
105    apr_file_open(&debug_log_fp, "/tmp/gnutls_debug", APR_APPEND | APR_WRITE | APR_CREATE, APR_OS_DEFAULT, pconf);
106    _gnutls_log(debug_log_fp, "%s: %d\n", __func__, __LINE__);
107    gnutls_global_set_log_level(9);
108    gnutls_global_set_log_function(gnutls_debug_log_all);
109    _gnutls_log(debug_log_fp, "gnutls: %s\n", gnutls_check_version(NULL));
110#endif
111
112    int ret;
113
114        /* Check for required GnuTLS Library Version */
115    if (gnutls_check_version(LIBGNUTLS_VERSION) == NULL) {
116                ap_log_perror(APLOG_MARK, APLOG_EMERG, 0, plog, "gnutls_check_version() failed. Required: "
117                                        "gnutls-%s Found: gnutls-%s", LIBGNUTLS_VERSION, gnutls_check_version(NULL));
118        return DONE;
119    }
120
121        /* Generate a Session Key */
122    ret = gnutls_session_ticket_key_generate(&session_ticket_key);
123    if (ret < 0) {
124                ap_log_perror(APLOG_MARK, APLOG_EMERG, 0, plog, "gnutls_session_ticket_key_generate: %s", gnutls_strerror(ret));
125                return DONE;
126    }
127
128    AP_OPTIONAL_HOOK(status_hook, mgs_status_hook, NULL, NULL, APR_HOOK_MIDDLE);
129
130    ap_mutex_register(pconf, MGS_CACHE_MUTEX_NAME, NULL, APR_LOCK_DEFAULT, 0);
131    ap_mutex_register(pconf, MGS_OCSP_MUTEX_NAME, NULL, APR_LOCK_DEFAULT, 0);
132    ap_mutex_register(pconf, MGS_OCSP_CACHE_MUTEX_NAME, NULL,
133                      APR_LOCK_DEFAULT, 0);
134
135    /* Register a pool clean-up function */
136    apr_pool_cleanup_register(pconf, NULL, mgs_cleanup_pre_config, apr_pool_cleanup_null);
137
138    return OK;
139}
140
141
142
143/**
144 * Get the list of available protocols for this connection and add it
145 * to the GnuTLS session. Must run before the client hello function.
146 */
147static void prepare_alpn_proposals(mgs_handle_t *ctxt)
148{
149    /* Check if any protocol upgrades are available
150     *
151     * The "report_all" parameter to ap_get_protocol_upgrades() is 0
152     * (report only more preferable protocols) because setting it to 1
153     * doesn't actually report ALL protocols, but only all except the
154     * current one. This way we can at least list the current one as
155     * available by appending it without potentially negotiating a
156     * less preferred protocol. */
157    const apr_array_header_t *pupgrades = NULL;
158    apr_status_t ret =
159        ap_get_protocol_upgrades(ctxt->c, NULL, ctxt->c->base_server,
160                                 /*report_all*/ 0, &pupgrades);
161    if (ret != APR_SUCCESS)
162    {
163        ap_log_cerror(APLOG_MARK, APLOG_WARNING, 0, ctxt->c,
164                      "%s: ap_get_protocol_upgrades() failed, "
165                      "cannot configure ALPN!", __func__);
166        return;
167    }
168
169    if (pupgrades == NULL || pupgrades->nelts == 0)
170    {
171        ap_log_cerror(APLOG_MARK, APLOG_TRACE1, 0, ctxt->c,
172                      "%s: No protocol upgrades available.", __func__);
173        return;
174    }
175
176    ap_log_cerror(APLOG_MARK, APLOG_DEBUG, 0, ctxt->c,
177                  "%s: Found %d protocol upgrade(s) for ALPN: %s",
178                  __func__, pupgrades->nelts,
179                  apr_array_pstrcat(ctxt->c->pool, pupgrades, ','));
180    gnutls_datum_t *alpn_protos =
181        apr_palloc(ctxt->c->pool,
182                   (pupgrades->nelts + 1) * sizeof(gnutls_datum_t));
183    for (int i = 0; i < pupgrades->nelts; i++)
184    {
185        alpn_protos[i].data = (void *) APR_ARRAY_IDX(pupgrades, i, char *);
186        alpn_protos[i].size =
187            strnlen(APR_ARRAY_IDX(pupgrades, i, char *),
188                    pupgrades->elt_size);
189    }
190
191    /* Add the current (default) protocol at the end of the list */
192    alpn_protos[pupgrades->nelts].data =
193        (void*) apr_pstrdup(ctxt->c->pool, ap_get_protocol(ctxt->c));
194    alpn_protos[pupgrades->nelts].size =
195        strlen((char*) alpn_protos[pupgrades->nelts].data);
196    ap_log_cerror(APLOG_MARK, APLOG_TRACE1, 0, ctxt->c,
197                  "%s: Adding current protocol %s to ALPN set.",
198                  __func__, alpn_protos[pupgrades->nelts].data);
199
200    gnutls_alpn_set_protocols(ctxt->session,
201                              alpn_protos,
202                              pupgrades->nelts,
203                              GNUTLS_ALPN_SERVER_PRECEDENCE);
204}
205
206
207
208/**
209 * Check if ALPN selected any protocol upgrade, try to switch if so.
210 */
211static int process_alpn_result(mgs_handle_t *ctxt)
212{
213    int ret = 0;
214    gnutls_datum_t alpn_proto;
215    ret = gnutls_alpn_get_selected_protocol(ctxt->session, &alpn_proto);
216    if (ret != GNUTLS_E_SUCCESS)
217    {
218        ap_log_cerror(APLOG_MARK, APLOG_TRACE1, APR_SUCCESS, ctxt->c,
219                      "%s: No ALPN result: %s (%d)",
220                      __func__, gnutls_strerror(ret), ret);
221        return GNUTLS_E_SUCCESS;
222    }
223
224    apr_array_header_t *client_protos =
225        apr_array_make(ctxt->c->pool, 1, sizeof(char *));
226    /* apr_pstrndup to ensure that the protocol is null terminated */
227    APR_ARRAY_PUSH(client_protos, char *) =
228        apr_pstrndup(ctxt->c->pool, (char*) alpn_proto.data, alpn_proto.size);
229    const char *selected =
230        ap_select_protocol(ctxt->c, NULL, ctxt->c->base_server,
231                           client_protos);
232
233    /* ap_select_protocol() will return NULL if none of the ALPN
234     * proposals matched. GnuTLS negotiated alpn_proto based on the
235     * list provided by the server, but the vhost might have changed
236     * based on SNI. Apache seems to adjust the proposal list to avoid
237     * such issues though.
238     *
239     * GnuTLS will return a fatal "no_application_protocol" alert as
240     * required by RFC 7301 if the post client hello function returns
241     * GNUTLS_E_NO_APPLICATION_PROTOCOL. */
242    if (!selected)
243    {
244        ap_log_cerror(APLOG_MARK, APLOG_ERR, APR_EGENERAL, ctxt->c,
245                      "%s: ap_select_protocol() returned NULL! Please "
246                      "make sure any overlapping vhosts have the same "
247                      "protocols available.",
248                      __func__);
249        return GNUTLS_E_NO_APPLICATION_PROTOCOL;
250    }
251
252    if (strcmp(selected, ap_get_protocol(ctxt->c)) == 0)
253    {
254        ap_log_cerror(APLOG_MARK, APLOG_TRACE1, APR_SUCCESS, ctxt->c,
255                      "%s: Already using protocol '%s', nothing to do.",
256                      __func__, selected);
257        return GNUTLS_E_SUCCESS;
258    }
259
260    ap_log_cerror(APLOG_MARK, APLOG_DEBUG, APR_SUCCESS, ctxt->c,
261                  "%s: Switching protocol to '%s' based on ALPN.",
262                  __func__, selected);
263    apr_status_t status = ap_switch_protocol(ctxt->c, NULL,
264                                             ctxt->c->base_server,
265                                             selected);
266    if (status != APR_SUCCESS)
267    {
268        ap_log_cerror(APLOG_MARK, APLOG_ERR, status, ctxt->c,
269                      "%s: Protocol switch to '%s' failed!",
270                      __func__, selected);
271        return GNUTLS_E_NO_APPLICATION_PROTOCOL;
272    }
273    /* ALPN done! */
274    return GNUTLS_E_SUCCESS;
275}
276
277
278
279/**
280 * Post client hello function for GnuTLS, used to configure the TLS
281 * server based on virtual host configuration. Uses SNI to select the
282 * virtual host if available.
283 *
284 * @param session the TLS session
285 *
286 * @return zero or a GnuTLS error code, as required by GnuTLS hook
287 * definition
288 */
289static int mgs_select_virtual_server_cb(gnutls_session_t session)
290{
291    int ret = 0;
292    mgs_handle_t *ctxt = gnutls_session_get_ptr(session);
293
294    /* try to find a virtual host */
295    mgs_srvconf_rec *tsc = mgs_find_sni_server(session);
296    if (tsc != NULL)
297    {
298        /* Found a TLS vhost based on the SNI, configure the
299         * connection context. */
300        ctxt->sc = tsc;
301        }
302
303    gnutls_certificate_server_set_request(session, ctxt->sc->client_verify_mode);
304
305    /* Set x509 credentials */
306    gnutls_credentials_set(session, GNUTLS_CRD_CERTIFICATE, ctxt->sc->certs);
307    /* Set Anon credentials */
308    gnutls_credentials_set(session, GNUTLS_CRD_ANON, ctxt->sc->anon_creds);
309
310#ifdef ENABLE_SRP
311        /* Set SRP credentials */
312    if (ctxt->sc->srp_tpasswd_conf_file != NULL && ctxt->sc->srp_tpasswd_file != NULL) {
313        gnutls_credentials_set(session, GNUTLS_CRD_SRP, ctxt->sc->srp_creds);
314    }
315#endif
316
317    ret = process_alpn_result(ctxt);
318    if (ret != GNUTLS_E_SUCCESS)
319        return ret;
320
321    /* Update the priorities - to avoid negotiating a ciphersuite that is not
322     * enabled on this virtual server. Note that here we ignore the version
323     * negotiation. */
324    ret = gnutls_priority_set(session, ctxt->sc->priorities);
325
326    /* actually it shouldn't fail since we have checked at startup */
327    return ret;
328}
329
330static int cert_retrieve_fn(gnutls_session_t session,
331                            const gnutls_datum_t * req_ca_rdn __attribute__((unused)),
332                            int nreqs __attribute__((unused)),
333                            const gnutls_pk_algorithm_t * pk_algos __attribute__((unused)),
334                            int pk_algos_length __attribute__((unused)),
335                            gnutls_pcert_st **pcerts,
336                            unsigned int *pcert_length,
337                            gnutls_privkey_t *privkey)
338{
339    _gnutls_log(debug_log_fp, "%s: %d\n", __func__, __LINE__);
340
341    mgs_handle_t *ctxt;
342
343    if (session == NULL) {
344                // ERROR INVALID SESSION
345        return -1;
346    }
347
348    ctxt = gnutls_transport_get_ptr(session);
349
350    if (gnutls_certificate_type_get(session) == GNUTLS_CRT_X509) {
351                // X509 CERTIFICATE
352        *pcerts = ctxt->sc->certs_x509_chain;
353        *pcert_length = ctxt->sc->certs_x509_chain_num;
354        *privkey = ctxt->sc->privkey_x509;
355        return 0;
356    } else {
357                // UNKNOWN CERTIFICATE
358            return -1;
359        }
360}
361
362/* Read the common name or the alternative name of the certificate.
363 * We only support a single name per certificate.
364 *
365 * Returns negative on error.
366 */
367static int read_crt_cn(server_rec * s, apr_pool_t * p, gnutls_x509_crt_t cert, char **cert_cn) {
368
369    int rv = 0;
370    size_t data_len;
371
372
373    _gnutls_log(debug_log_fp, "%s: %d\n", __func__, __LINE__);
374    *cert_cn = NULL;
375
376    data_len = 0;
377    rv = gnutls_x509_crt_get_dn_by_oid(cert, GNUTLS_OID_X520_COMMON_NAME, 0, 0, NULL, &data_len);
378
379    if (rv == GNUTLS_E_SHORT_MEMORY_BUFFER && data_len > 1) {
380        *cert_cn = apr_palloc(p, data_len);
381        rv = gnutls_x509_crt_get_dn_by_oid(cert,
382                GNUTLS_OID_X520_COMMON_NAME,
383                0, 0, *cert_cn,
384                &data_len);
385    } else { /* No CN return subject alternative name */
386        ap_log_error(APLOG_MARK, APLOG_DEBUG, 0, s,
387                "No common name found in certificate for '%s:%d'. Looking for subject alternative name...",
388                s->server_hostname, s->port);
389        rv = 0;
390        /* read subject alternative name */
391        for (int i = 0; !(rv < 0); i++)
392        {
393            data_len = 0;
394            rv = gnutls_x509_crt_get_subject_alt_name(cert, i,
395                    NULL,
396                    &data_len,
397                    NULL);
398
399            if (rv == GNUTLS_E_SHORT_MEMORY_BUFFER
400                    && data_len > 1) {
401                /* FIXME: not very efficient. What if we have several alt names
402                 * before DNSName?
403                 */
404                *cert_cn = apr_palloc(p, data_len + 1);
405
406                rv = gnutls_x509_crt_get_subject_alt_name
407                        (cert, i, *cert_cn, &data_len, NULL);
408                (*cert_cn)[data_len] = 0;
409
410                if (rv == GNUTLS_SAN_DNSNAME)
411                    break;
412            }
413        }
414    }
415
416    return rv;
417}
418
419
420
421#if GNUTLS_VERSION_NUMBER >= 0x030506
422#define HAVE_KNOWN_DH_GROUPS 1
423#endif
424#ifdef HAVE_KNOWN_DH_GROUPS
425/**
426 * Try to estimate a GnuTLS security parameter based on the given
427 * private key. Any errors are logged.
428 *
429 * @param s The `server_rec` to use for logging
430 *
431 * @param key The private key to use
432 *
433 * @return `gnutls_sec_param_t` as returned by
434 * `gnutls_pk_bits_to_sec_param` for the key properties, or
435 * GNUTLS_SEC_PARAM_UNKNOWN in case of error
436 */
437static gnutls_sec_param_t sec_param_from_privkey(server_rec *server,
438                                                 gnutls_privkey_t key)
439{
440    unsigned int bits = 0;
441    int pk_algo = gnutls_privkey_get_pk_algorithm(key, &bits);
442    if (pk_algo < 0)
443    {
444        ap_log_error(APLOG_MARK, APLOG_ERR, APR_EGENERAL, server,
445                     "%s: Could not get private key parameters: %s (%d)",
446                     __func__, gnutls_strerror(pk_algo), pk_algo);
447        return GNUTLS_SEC_PARAM_UNKNOWN;
448    }
449    return gnutls_pk_bits_to_sec_param(pk_algo, bits);
450}
451#else
452/** ffdhe2048 DH group as defined in RFC 7919, Appendix A.1. This is
453 * the default DH group if mod_gnutls is compiled agains a GnuTLS
454 * version that does not provide known DH groups based on security
455 * parameters (before 3.5.6). */
456static const char FFDHE2048_PKCS3[] =
457    "-----BEGIN DH PARAMETERS-----\n"
458    "MIIBDAKCAQEA//////////+t+FRYortKmq/cViAnPTzx2LnFg84tNpWp4TZBFGQz\n"
459    "+8yTnc4kmz75fS/jY2MMddj2gbICrsRhetPfHtXV/WVhJDP1H18GbtCFY2VVPe0a\n"
460    "87VXE15/V8k1mE8McODmi3fipona8+/och3xWKE2rec1MKzKT0g6eXq8CrGCsyT7\n"
461    "YdEIqUuyyOP7uWrat2DX9GgdT0Kj3jlN9K5W7edjcrsZCwenyO4KbXCeAvzhzffi\n"
462    "7MA0BM0oNC9hkXL+nOmFg/+OTxIy7vKBg8P+OxtMb61zO7X8vC7CIAXFjvGDfRaD\n"
463    "ssbzSibBsu/6iGtCOGEoXJf//////////wIBAgICAQA=\n"
464    "-----END DH PARAMETERS-----\n";
465const gnutls_datum_t default_dh_params = {
466    (void *) FFDHE2048_PKCS3,
467    sizeof(FFDHE2048_PKCS3)
468};
469#endif
470
471
472
473/**
474 * Configure the default DH groups to use for the given server. When
475 * compiled against GnuTLS version 3.5.6 or newer the known DH group
476 * matching the GnuTLS security parameter estimated from the private
477 * key is used. Otherwise the ffdhe2048 DH group as defined in RFC
478 * 7919, Appendix A.1 is the default.
479 *
480 * @param server the host to configure
481 *
482 * @return `OK` on success, `HTTP_UNAUTHORIZED` otherwise
483 */
484static int set_default_dh_param(server_rec *server)
485{
486    mgs_srvconf_rec *sc = (mgs_srvconf_rec *)
487        ap_get_module_config(server->module_config, &gnutls_module);
488
489#ifdef HAVE_KNOWN_DH_GROUPS
490    gnutls_sec_param_t seclevel = GNUTLS_SEC_PARAM_UNKNOWN;
491    if (sc->privkey_x509)
492    {
493        seclevel = sec_param_from_privkey(server, sc->privkey_x509);
494        ap_log_error(APLOG_MARK, APLOG_TRACE1, APR_SUCCESS, server,
495                     "%s: GnuTLS security param estimated based on "
496                     "private key '%s': %s",
497                     __func__, sc->x509_key_file,
498                     gnutls_sec_param_get_name(seclevel));
499    }
500
501    if (seclevel == GNUTLS_SEC_PARAM_UNKNOWN)
502        seclevel = GNUTLS_SEC_PARAM_MEDIUM;
503    ap_log_error(APLOG_MARK, APLOG_DEBUG, APR_SUCCESS, server,
504                 "%s: Setting DH params for security level '%s'.",
505                 __func__, gnutls_sec_param_get_name(seclevel));
506
507    int ret = gnutls_certificate_set_known_dh_params(sc->certs, seclevel);
508    if (ret < 0)
509    {
510        ap_log_error(APLOG_MARK, APLOG_EMERG, APR_EGENERAL, server,
511                     "%s: setting known DH params failed: %s (%d)",
512                     __func__, gnutls_strerror(ret), ret);
513        return HTTP_UNAUTHORIZED;
514    }
515    ret = gnutls_anon_set_server_known_dh_params(sc->anon_creds, seclevel);
516    if (ret < 0)
517    {
518        ap_log_error(APLOG_MARK, APLOG_EMERG, APR_EGENERAL, server,
519                     "%s: setting known DH params failed: %s (%d)",
520                     __func__, gnutls_strerror(ret), ret);
521        return HTTP_UNAUTHORIZED;
522    }
523#else
524    int ret = gnutls_dh_params_init(&sc->dh_params);
525    if (ret < 0)
526    {
527        ap_log_error(APLOG_MARK, APLOG_STARTUP, 0, server,
528                     "%s: Failed to initialize DH params structure: "
529                     "%s (%d)", __func__, gnutls_strerror(ret), ret);
530        return HTTP_UNAUTHORIZED;
531    }
532    ret = gnutls_dh_params_import_pkcs3(sc->dh_params, &default_dh_params,
533                                        GNUTLS_X509_FMT_PEM);
534    if (ret < 0)
535    {
536        ap_log_error(APLOG_MARK, APLOG_STARTUP, 0, server,
537                     "%s: Failed to import default DH params: %s (%d)",
538                     __func__, gnutls_strerror(ret), ret);
539        return HTTP_UNAUTHORIZED;
540    }
541
542    gnutls_certificate_set_dh_params(sc->certs, sc->dh_params);
543    gnutls_anon_set_server_dh_params(sc->anon_creds, sc->dh_params);
544#endif
545
546    return OK;
547}
548
549
550
551/**
552 * Post config hook.
553 *
554 * Must return OK or DECLINED on success, something else on
555 * error. These codes are defined in Apache httpd.h along with the
556 * HTTP status codes, so I'm going to use HTTP error codes both for
557 * fun (and to avoid conflicts).
558 */
559int mgs_hook_post_config(apr_pool_t *pconf,
560                         apr_pool_t *plog __attribute__((unused)),
561                         apr_pool_t *ptemp,
562                         server_rec *base_server)
563{
564    int rv;
565    server_rec *s;
566    mgs_srvconf_rec *sc;
567    mgs_srvconf_rec *sc_base;
568    void *data = NULL;
569    const char *userdata_key = "mgs_init";
570
571    _gnutls_log(debug_log_fp, "%s: %d\n", __func__, __LINE__);
572
573    apr_pool_userdata_get(&data, userdata_key, base_server->process->pool);
574    if (data == NULL) {
575        apr_pool_userdata_set((const void *) 1, userdata_key, apr_pool_cleanup_null, base_server->process->pool);
576    }
577
578    s = base_server;
579    sc_base = (mgs_srvconf_rec *) ap_get_module_config(s->module_config, &gnutls_module);
580
581
582    rv = mgs_cache_post_config(pconf, ptemp, s, sc_base);
583    if (rv != APR_SUCCESS)
584    {
585        ap_log_error(APLOG_MARK, APLOG_STARTUP, rv, s,
586                     "Post config for cache failed.");
587        return HTTP_INSUFFICIENT_STORAGE;
588    }
589
590    if (sc_base->ocsp_mutex == NULL)
591    {
592        rv = ap_global_mutex_create(&sc_base->ocsp_mutex, NULL,
593                                    MGS_OCSP_MUTEX_NAME, NULL,
594                                    base_server, pconf, 0);
595        if (rv != APR_SUCCESS)
596            return rv;
597    }
598
599    /* If GnuTLSP11Module is set, load the listed PKCS #11
600     * modules. Otherwise system defaults will be used. */
601    if (sc_base->p11_modules != NULL)
602    {
603        rv = gnutls_pkcs11_init(GNUTLS_PKCS11_FLAG_MANUAL, NULL);
604        if (rv < 0)
605        {
606            ap_log_error(APLOG_MARK, APLOG_STARTUP, 0, s,
607                         "GnuTLS: Initializing PKCS #11 "
608                         "failed: %s (%d).",
609                         gnutls_strerror(rv), rv);
610        }
611        else
612        {
613            for (int i = 0; i < sc_base->p11_modules->nelts; i++)
614            {
615                char *p11_module =
616                    APR_ARRAY_IDX(sc_base->p11_modules, i, char *);
617                rv = gnutls_pkcs11_add_provider(p11_module, NULL);
618                if (rv != GNUTLS_E_SUCCESS)
619                    ap_log_error(APLOG_MARK, APLOG_STARTUP, 0, s,
620                                 "GnuTLS: Loading PKCS #11 provider module %s "
621                                 "failed: %s (%d).",
622                                 p11_module, gnutls_strerror(rv), rv);
623            }
624        }
625    }
626
627    sc_base->singleton_wd =
628        mgs_new_singleton_watchdog(base_server, MGS_SINGLETON_WATCHDOG, pconf);
629
630    for (s = base_server; s; s = s->next)
631    {
632        sc = (mgs_srvconf_rec *) ap_get_module_config(s->module_config, &gnutls_module);
633        sc->cache_enable = sc_base->cache_enable;
634        sc->cache = sc_base->cache;
635        if (sc->cache_timeout == MGS_TIMEOUT_UNSET)
636            sc->cache_timeout = sc_base->cache_timeout;
637        sc->ocsp_cache = sc_base->ocsp_cache;
638
639        sc->singleton_wd = sc_base->singleton_wd;
640
641        rv = mgs_load_files(pconf, ptemp, s);
642        if (rv != 0) {
643            ap_log_error(APLOG_MARK, APLOG_STARTUP, 0, s,
644                "GnuTLS: Loading required files failed."
645                " Shutting Down.");
646            return HTTP_NOT_FOUND;
647        }
648
649        /* defaults for unset values: */
650        if (sc->enabled == GNUTLS_ENABLED_UNSET)
651            sc->enabled = GNUTLS_ENABLED_FALSE;
652        if (sc->tickets == GNUTLS_ENABLED_UNSET)
653            sc->tickets = GNUTLS_ENABLED_FALSE;
654        if (sc->export_certificates_size < 0)
655            sc->export_certificates_size = 0;
656        if (sc->client_verify_mode == -1)
657            sc->client_verify_mode = GNUTLS_CERT_IGNORE;
658        if (sc->client_verify_method == mgs_cvm_unset)
659            sc->client_verify_method = mgs_cvm_cartel;
660
661        // TODO: None of the stuff below (and neither some above)
662        // makes sense if sc->enabled == GNUTLS_ENABLED_FALSE, we
663        // should just continue to the next host. All code below could
664        // then safely assume sc->enabled == GNUTLS_ENABLED_TRUE.
665
666        sc->ocsp_mutex = sc_base->ocsp_mutex;
667        /* init OCSP configuration unless explicitly disabled */
668        if (sc->enabled && sc->ocsp_staple != GNUTLS_ENABLED_FALSE)
669        {
670            const char *err = mgs_ocsp_configure_stapling(pconf, ptemp, s);
671            if (err != NULL)
672            {
673                /* If OCSP stapling is enabled only by default ignore
674                 * error and disable stapling */
675                if (sc->ocsp_staple == GNUTLS_ENABLED_UNSET)
676                {
677                    ap_log_error(APLOG_MARK, APLOG_INFO, APR_SUCCESS, s,
678                                 "Cannnot enable OCSP stapling for "
679                                 "host '%s:%d': %s",
680                                 s->server_hostname, s->addrs->host_port, err);
681                    sc->ocsp_staple = GNUTLS_ENABLED_FALSE;
682                }
683                /* If OCSP stapling is explicitly enabled this is a
684                 * critical error. */
685                else
686                {
687                    ap_log_error(APLOG_MARK, APLOG_STARTUP, APR_EINVAL, s,
688                                 "OCSP stapling configuration failed for "
689                                 "host '%s:%d': %s",
690                                 s->server_hostname, s->addrs->host_port, err);
691                    return HTTP_INTERNAL_SERVER_ERROR;
692                }
693            }
694            else
695            {
696                /* Might already be set */
697                sc->ocsp_staple = GNUTLS_ENABLED_TRUE;
698                /* Set up stapling */
699                rv = mgs_ocsp_enable_stapling(pconf, ptemp, s);
700                if (rv != OK && rv != DECLINED)
701                    return rv;
702            }
703        }
704
705        /* Check if the priorities have been set */
706        if (sc->priorities == NULL && sc->enabled == GNUTLS_ENABLED_TRUE) {
707            ap_log_error(APLOG_MARK, APLOG_STARTUP, 0, s,
708                    "GnuTLS: Host '%s:%d' is missing the GnuTLSPriorities directive!",
709                    s->server_hostname, s->port);
710            return HTTP_NOT_ACCEPTABLE;
711        }
712
713        /* Set host DH params from user configuration or defaults */
714        if (sc->dh_params != NULL) {
715            gnutls_certificate_set_dh_params(sc->certs, sc->dh_params);
716            gnutls_anon_set_server_dh_params(sc->anon_creds, sc->dh_params);
717        } else {
718            rv = set_default_dh_param(s);
719            if (rv != OK)
720                return rv;
721        }
722
723        /* The call after this comment is a workaround for bug in
724         * gnutls_certificate_set_retrieve_function2 that ignores
725         * supported certificate types. Should be fixed in GnuTLS
726         * 3.3.12.
727         *
728         * Details:
729         * https://lists.gnupg.org/pipermail/gnutls-devel/2015-January/007377.html
730         * Workaround from:
731         * https://github.com/vanrein/tlspool/commit/4938102d3d1b086491d147e6c8e4e2a02825fc12 */
732#if GNUTLS_VERSION_NUMBER < 0x030312
733        gnutls_certificate_set_retrieve_function(sc->certs, (void *) exit);
734#endif
735
736        gnutls_certificate_set_retrieve_function2(sc->certs, cert_retrieve_fn);
737
738        if ((sc->certs_x509_chain == NULL || sc->certs_x509_chain_num < 1) &&
739            sc->enabled == GNUTLS_ENABLED_TRUE) {
740                        ap_log_error(APLOG_MARK, APLOG_STARTUP, 0, s,
741                                                "GnuTLS: Host '%s:%d' is missing a Certificate File!",
742                                                s->server_hostname, s->port);
743            return HTTP_UNAUTHORIZED;
744        }
745        if (sc->enabled == GNUTLS_ENABLED_TRUE &&
746            (sc->certs_x509_chain_num > 0 && sc->privkey_x509 == NULL))
747        {
748                        ap_log_error(APLOG_MARK, APLOG_STARTUP, 0, s,
749                                                "GnuTLS: Host '%s:%d' is missing a Private Key File!",
750                                                s->server_hostname, s->port);
751            return HTTP_UNAUTHORIZED;
752        }
753
754        if (sc->enabled == GNUTLS_ENABLED_TRUE) {
755            rv = -1;
756            if (sc->certs_x509_chain_num > 0) {
757                rv = read_crt_cn(s, pconf, sc->certs_x509_crt_chain[0], &sc->cert_cn);
758            }
759
760            if (rv < 0) {
761                ap_log_error(APLOG_MARK, APLOG_STARTUP, 0, s,
762                                                        "GnuTLS: Cannot find a certificate for host '%s:%d'!",
763                                                        s->server_hostname, s->port);
764                sc->cert_cn = NULL;
765                continue;
766            }
767        }
768
769        if (sc->enabled == GNUTLS_ENABLED_TRUE
770            && sc->proxy_enabled == GNUTLS_ENABLED_TRUE
771            && load_proxy_x509_credentials(pconf, ptemp, s) != APR_SUCCESS)
772        {
773            ap_log_error(APLOG_MARK, APLOG_STARTUP, 0, s,
774                         "%s: loading proxy credentials for host "
775                         "'%s:%d' failed, exiting!",
776                         __func__, s->server_hostname, s->port);
777            return HTTP_PROXY_AUTHENTICATION_REQUIRED;
778        }
779    }
780
781
782    ap_add_version_component(pconf, "mod_gnutls/" MOD_GNUTLS_VERSION);
783
784    {
785        const char* libvers = gnutls_check_version(NULL);
786        char* gnutls_version = NULL;
787        if(libvers && (gnutls_version = apr_psprintf(pconf, "GnuTLS/%s", libvers))) {
788            ap_add_version_component(pconf, gnutls_version);
789        } else {
790            // In case we could not create the above string go for the static version instead
791            ap_add_version_component(pconf, "GnuTLS/" GNUTLS_VERSION "-static");
792        }
793    }
794
795    return OK;
796}
797
798void mgs_hook_child_init(apr_pool_t *p, server_rec *s)
799{
800    apr_status_t rv = APR_SUCCESS;
801    mgs_srvconf_rec *sc = (mgs_srvconf_rec *)
802        ap_get_module_config(s->module_config, &gnutls_module);
803
804    _gnutls_log(debug_log_fp, "%s: %d\n", __func__, __LINE__);
805
806    /* if we use PKCS #11 reinitialize it */
807    if (mgs_pkcs11_reinit(s) < 0) {
808            ap_log_error(APLOG_MARK, APLOG_EMERG, 0, s,
809                    "GnuTLS: Failed to reinitialize PKCS #11");
810            exit(-1);
811    }
812
813    if (sc->cache_enable == GNUTLS_ENABLED_TRUE)
814    {
815        rv = mgs_cache_child_init(p, s, sc->cache, MGS_CACHE_MUTEX_NAME);
816        if (rv != APR_SUCCESS)
817            ap_log_error(APLOG_MARK, APLOG_EMERG, rv, s,
818                    "Child init for session cache failed!");
819    }
820
821    if (sc->ocsp_cache != NULL)
822    {
823        rv = mgs_cache_child_init(p, s, sc->ocsp_cache,
824                                  MGS_OCSP_CACHE_MUTEX_NAME);
825        if (rv != APR_SUCCESS)
826            ap_log_error(APLOG_MARK, APLOG_EMERG, rv, s,
827                    "Child init for OCSP cache failed!");
828    }
829
830    /* reinit OCSP request mutex */
831    const char *lockfile = apr_global_mutex_lockfile(sc->ocsp_mutex);
832    rv = apr_global_mutex_child_init(&sc->ocsp_mutex, lockfile, p);
833    if (rv != APR_SUCCESS)
834        ap_log_error(APLOG_MARK, APLOG_EMERG, rv, s,
835                     "Failed to reinit mutex '" MGS_OCSP_MUTEX_NAME "'.");
836
837    /* Block SIGPIPE Signals */
838    rv = apr_signal_block(SIGPIPE);
839    if(rv != APR_SUCCESS) {
840        /* error sending output */
841        ap_log_error(APLOG_MARK, APLOG_EMERG, rv, s,
842                "GnuTLS: Error Blocking SIGPIPE Signal!");
843    }
844}
845
846const char *mgs_hook_http_scheme(const request_rec * r) {
847    mgs_srvconf_rec *sc;
848
849    if (r == NULL)
850        return NULL;
851
852    sc = (mgs_srvconf_rec *) ap_get_module_config(r->
853            server->module_config,
854            &gnutls_module);
855
856    _gnutls_log(debug_log_fp, "%s: %d\n", __func__, __LINE__);
857    if (sc->enabled == GNUTLS_ENABLED_FALSE) {
858        return NULL;
859    }
860
861    return "https";
862}
863
864apr_port_t mgs_hook_default_port(const request_rec * r) {
865    mgs_srvconf_rec *sc;
866
867    if (r == NULL)
868        return 0;
869
870    sc = (mgs_srvconf_rec *) ap_get_module_config(r->
871            server->module_config,
872            &gnutls_module);
873
874    _gnutls_log(debug_log_fp, "%s: %d\n", __func__, __LINE__);
875    if (sc->enabled == GNUTLS_ENABLED_FALSE) {
876        return 0;
877    }
878
879    return 443;
880}
881
882/**
883 * Default buffer size for SNI data, including the terminating NULL
884 * byte. The size matches what gnutls-cli uses initially.
885 */
886#define DEFAULT_SNI_HOST_LEN 256
887
888typedef struct {
889    mgs_handle_t *ctxt;
890    mgs_srvconf_rec *sc;
891    const char *sni_name;
892} vhost_cb_rec;
893
894/**
895 * Matches the current vhost's ServerAlias directives
896 *
897 * @param x vhost callback record
898 * @param s server record
899 * @param tsc mod_gnutls server data for `s`
900 *
901 * @return true if a match, false otherwise
902 *
903 */
904int check_server_aliases(vhost_cb_rec *x, server_rec * s, mgs_srvconf_rec *tsc)
905{
906        apr_array_header_t *names;
907        int rv = 0;
908        char ** name;
909
910        /* Check ServerName First! */
911        if(apr_strnatcasecmp(x->sni_name, s->server_hostname) == 0) {
912                // We have a match, save this server configuration
913                x->sc = tsc;
914                rv = 1;
915        /* Check any ServerAlias directives */
916        } else if(s->names->nelts) {
917                names = s->names;
918                name = (char **)names->elts;
919                for (int i = 0; i < names->nelts; ++i)
920        {
921                        if (!name[i]) { continue; }
922                                if (apr_strnatcasecmp(x->sni_name, name[i]) == 0) {
923                                        // We have a match, save this server configuration
924                                        x->sc = tsc;
925                                        rv = 1;
926                        }
927                }
928        /* Wild any ServerAlias Directives */
929        } else if(s->wild_names->nelts) {
930                names = s->wild_names;
931        name = (char **)names->elts;
932                for (int i = 0; i < names->nelts; ++i)
933        {
934                        if (!name[i]) { continue; }
935                                if(apr_fnmatch(name[i], x->sni_name ,
936                                                                APR_FNM_CASE_BLIND|
937                                                                APR_FNM_PERIOD|
938                                                                APR_FNM_PATHNAME|
939                                                                APR_FNM_NOESCAPE) == APR_SUCCESS) {
940                                x->sc = tsc;
941                                rv = 1;
942                        }
943                }
944        }
945        return rv;
946}
947
948static int vhost_cb(void *baton, conn_rec *conn, server_rec * s)
949{
950    mgs_srvconf_rec *tsc;
951    vhost_cb_rec *x = baton;
952    int ret;
953
954    _gnutls_log(debug_log_fp, "%s: %d\n", __func__, __LINE__);
955    tsc = (mgs_srvconf_rec *) ap_get_module_config(s->module_config,
956            &gnutls_module);
957
958    if (tsc->enabled != GNUTLS_ENABLED_TRUE || tsc->cert_cn == NULL) {
959        return 0;
960    }
961
962    if (tsc->certs_x509_chain_num > 0) {
963        /* this check is there to warn administrator of any missing hostname
964         * in the certificate. */
965        ret = gnutls_x509_crt_check_hostname(tsc->certs_x509_crt_chain[0], s->server_hostname);
966        if (0 == ret)
967            ap_log_cerror(APLOG_MARK, APLOG_DEBUG, 0, conn,
968                          "GnuTLS: the certificate doesn't match requested "
969                          "hostname '%s'", s->server_hostname);
970    } else {
971        ap_log_cerror(APLOG_MARK, APLOG_INFO, 0, conn,
972                      "GnuTLS: SNI request for '%s' but no X.509 certs "
973                      "available at all",
974                      s->server_hostname);
975    }
976        return check_server_aliases(x, s, tsc);
977}
978
979/**
980 * Get SNI data from GnuTLS (if any) and search for a matching virtual
981 * host configuration. This method is called from the post client
982 * hello function.
983 *
984 * @param session the GnuTLS session
985 *
986 * @return either the matching mod_gnutls server config, or `NULL`
987 */
988mgs_srvconf_rec *mgs_find_sni_server(gnutls_session_t session)
989{
990    mgs_handle_t *ctxt = gnutls_session_get_ptr(session);
991
992    char *sni_name = apr_palloc(ctxt->c->pool, DEFAULT_SNI_HOST_LEN);
993    size_t sni_len = DEFAULT_SNI_HOST_LEN;
994    unsigned int sni_type;
995
996    /* Search for a DNS SNI element. Note that RFC 6066 prohibits more
997     * than one server name per type. */
998    int sni_index = -1;
999    int rv = 0;
1000    do {
1001        /* The sni_index is incremented before each use, so if the
1002         * loop terminates with a type match we will have the right
1003         * one stored. */
1004        rv = gnutls_server_name_get(session, sni_name,
1005                                    &sni_len, &sni_type, ++sni_index);
1006        if (rv == GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE)
1007        {
1008            ap_log_cerror(APLOG_MARK, APLOG_TRACE1, APR_EGENERAL, ctxt->c,
1009                          "%s: no DNS SNI found (last index: %d).",
1010                          __func__, sni_index);
1011            return NULL;
1012        }
1013    } while (sni_type != GNUTLS_NAME_DNS);
1014    /* The (rv == GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE) path inside
1015     * the loop above returns, so if we reach this point we have a DNS
1016     * SNI at the current index. */
1017
1018    if (rv == GNUTLS_E_SHORT_MEMORY_BUFFER)
1019    {
1020        /* Allocate a new buffer of the right size and retry */
1021        sni_name = apr_palloc(ctxt->c->pool, sni_len);
1022        ap_log_cerror(APLOG_MARK, APLOG_TRACE1, APR_SUCCESS, ctxt->c,
1023                      "%s: reallocated SNI data buffer for %" APR_SIZE_T_FMT
1024                      " bytes.", __func__, sni_len);
1025        rv = gnutls_server_name_get(session, sni_name,
1026                                    &sni_len, &sni_type, sni_index);
1027    }
1028
1029    /* Unless there's a bug in the GnuTLS API only GNUTLS_E_IDNA_ERROR
1030     * can occur here, but a catch all is safer and no more
1031     * complicated. */
1032    if (rv != GNUTLS_E_SUCCESS)
1033    {
1034        ap_log_cerror(APLOG_MARK, APLOG_INFO, APR_EGENERAL, ctxt->c,
1035                      "%s: error while getting SNI DNS data: '%s' (%d).",
1036                      __func__, gnutls_strerror(rv), rv);
1037        return NULL;
1038    }
1039
1040    ap_log_cerror(APLOG_MARK, APLOG_TRACE1, APR_SUCCESS, ctxt->c,
1041                  "%s: client requested server '%s'.",
1042                  __func__, sni_name);
1043
1044    /* Search for vhosts matching connection parameters and the
1045     * SNI. If a match is found, cbx.sc will contain the mod_gnutls
1046     * server config for the vhost. */
1047    vhost_cb_rec cbx = {
1048        .ctxt = ctxt,
1049        .sc = NULL,
1050        .sni_name = sni_name
1051    };
1052    rv = ap_vhost_iterate_given_conn(ctxt->c, vhost_cb, &cbx);
1053    if (rv == 1) {
1054        return cbx.sc;
1055    }
1056    return NULL;
1057}
1058
1059/**
1060 * This function is intended as a cleanup handler for connections
1061 * using GnuTLS. If attached to the connection pool, it ensures that
1062 * session resources are released with the connection pool even if the
1063 * session wasn't terminated properly.
1064 *
1065 * @param data must point to the mgs_handle_t associated with the
1066 * connection
1067 */
1068static apr_status_t cleanup_gnutls_session(void *data)
1069{
1070    /* nothing to do */
1071    if (data == NULL)
1072        return APR_SUCCESS;
1073
1074    /* check if session needs closing */
1075    mgs_handle_t *ctxt = (mgs_handle_t *) data;
1076    if (ctxt->session != NULL)
1077    {
1078        ap_log_cerror(APLOG_MARK, APLOG_WARNING, APR_ECONNABORTED, ctxt->c,
1079                      "%s: connection pool cleanup in progress but %sTLS "
1080                      "session hasn't been terminated, trying to close",
1081                      __func__, IS_PROXY_STR(ctxt));
1082        int ret;
1083        /* Try A Clean Shutdown */
1084        do
1085            ret = gnutls_bye(ctxt->session, GNUTLS_SHUT_WR);
1086        while (ret == GNUTLS_E_INTERRUPTED || ret == GNUTLS_E_AGAIN);
1087        if (ret != GNUTLS_E_SUCCESS)
1088            ap_log_cerror(APLOG_MARK, APLOG_INFO, APR_EGENERAL, ctxt->c,
1089                          "%s: error while closing TLS %sconnection: %s (%d)",
1090                          __func__, IS_PROXY_STR(ctxt),
1091                          gnutls_strerror(ret), ret);
1092        else
1093            ap_log_cerror(APLOG_MARK, APLOG_DEBUG, APR_SUCCESS, ctxt->c,
1094                          "%s: TLS %sconnection closed.",
1095                          __func__, IS_PROXY_STR(ctxt));
1096        /* De-Initialize Session */
1097        gnutls_deinit(ctxt->session);
1098        ctxt->session = NULL;
1099    }
1100    return APR_SUCCESS;
1101}
1102
1103static void create_gnutls_handle(conn_rec * c)
1104{
1105    _gnutls_log(debug_log_fp, "%s: %d\n", __func__, __LINE__);
1106
1107    /* Get connection specific configuration */
1108    mgs_handle_t *ctxt = init_gnutls_ctxt(c);
1109    ctxt->enabled = GNUTLS_ENABLED_TRUE;
1110    ctxt->status = 0;
1111    ctxt->input_rc = APR_SUCCESS;
1112    ctxt->input_bb = apr_brigade_create(c->pool, c->bucket_alloc);
1113    ctxt->input_cbuf.length = 0;
1114    ctxt->output_rc = APR_SUCCESS;
1115    ctxt->output_bb = apr_brigade_create(c->pool, c->bucket_alloc);
1116    ctxt->output_blen = 0;
1117    ctxt->output_length = 0;
1118
1119    /* Initialize GnuTLS Library */
1120    int err = 0;
1121    if (ctxt->is_proxy == GNUTLS_ENABLED_TRUE)
1122    {
1123        /* this is an outgoing proxy connection, client mode */
1124        err = gnutls_init(&ctxt->session, GNUTLS_CLIENT);
1125        if (err != GNUTLS_E_SUCCESS)
1126            ap_log_cerror(APLOG_MARK, APLOG_ERR, err, c,
1127                          "gnutls_init for proxy connection failed: %s (%d)",
1128                          gnutls_strerror(err), err);
1129    }
1130    else
1131    {
1132        /* incoming connection, server mode */
1133        err = gnutls_init(&ctxt->session, GNUTLS_SERVER);
1134        if (err != GNUTLS_E_SUCCESS)
1135            ap_log_cerror(APLOG_MARK, APLOG_ERR, err, c,
1136                          "gnutls_init for server side failed: %s (%d)",
1137                          gnutls_strerror(err), err);
1138        /* Initialize Session Tickets */
1139        if (session_ticket_key.data != NULL &&
1140            ctxt->sc->tickets == GNUTLS_ENABLED_TRUE)
1141        {
1142            err = gnutls_session_ticket_enable_server(ctxt->session, &session_ticket_key);
1143            if (err != GNUTLS_E_SUCCESS)
1144                ap_log_cerror(APLOG_MARK, APLOG_ERR, err, c,
1145                              "gnutls_session_ticket_enable_server failed: %s (%d)",
1146                              gnutls_strerror(err), err);
1147        }
1148    }
1149
1150    /* Ensure TLS session resources are released when the connection
1151     * pool is cleared, if the filters haven't done that already. */
1152    apr_pool_pre_cleanup_register(c->pool, ctxt, cleanup_gnutls_session);
1153
1154    /* Set Default Priority */
1155        err = gnutls_priority_set_direct(ctxt->session, "NORMAL", NULL);
1156    if (err != GNUTLS_E_SUCCESS)
1157        ap_log_cerror(APLOG_MARK, APLOG_ERR, err, c, "gnutls_priority_set_direct failed!");
1158    /* Set Handshake function */
1159    gnutls_handshake_set_post_client_hello_function(ctxt->session,
1160            mgs_select_virtual_server_cb);
1161
1162    /* Set GnuTLS user pointer, so we can access the module session
1163     * context in GnuTLS callbacks */
1164    gnutls_session_set_ptr(ctxt->session, ctxt);
1165
1166    /* If mod_gnutls is the TLS server, mgs_select_virtual_server_cb
1167     * will load appropriate credentials during handshake. However,
1168     * when handling a proxy backend connection, mod_gnutls acts as
1169     * TLS client and credentials must be loaded here. */
1170    if (ctxt->is_proxy == GNUTLS_ENABLED_TRUE)
1171    {
1172        /* Set anonymous client credentials for proxy connections */
1173        gnutls_credentials_set(ctxt->session, GNUTLS_CRD_ANON,
1174                               ctxt->sc->anon_client_creds);
1175        /* Set x509 credentials */
1176        gnutls_credentials_set(ctxt->session, GNUTLS_CRD_CERTIFICATE,
1177                               ctxt->sc->proxy_x509_creds);
1178        /* Load priorities from the server configuration */
1179        err = gnutls_priority_set(ctxt->session, ctxt->sc->proxy_priorities);
1180        if (err != GNUTLS_E_SUCCESS)
1181            ap_log_cerror(APLOG_MARK, APLOG_ERR, err, c,
1182                          "%s: setting priorities for proxy connection "
1183                          "failed: %s (%d)",
1184                          __func__, gnutls_strerror(err), err);
1185    }
1186
1187    prepare_alpn_proposals(ctxt);
1188
1189    /* Initialize Session Cache */
1190    mgs_cache_session_init(ctxt);
1191
1192    /* Set pull, push & ptr functions */
1193    gnutls_transport_set_pull_function(ctxt->session,
1194            mgs_transport_read);
1195    gnutls_transport_set_push_function(ctxt->session,
1196            mgs_transport_write);
1197    gnutls_transport_set_ptr(ctxt->session, ctxt);
1198    /* Add IO filters */
1199    ctxt->input_filter = ap_add_input_filter(GNUTLS_INPUT_FILTER_NAME,
1200            ctxt, NULL, c);
1201    ctxt->output_filter = ap_add_output_filter(GNUTLS_OUTPUT_FILTER_NAME,
1202            ctxt, NULL, c);
1203}
1204
1205int mgs_hook_pre_connection(conn_rec * c, void *csd __attribute__((unused)))
1206{
1207    _gnutls_log(debug_log_fp, "%s: %d\n", __func__, __LINE__);
1208
1209    if (c->master)
1210    {
1211        ap_log_cerror(APLOG_MARK, APLOG_TRACE1, 0, c,
1212                      "%s declined secondary connection", __func__);
1213        return DECLINED;
1214    }
1215
1216    mgs_srvconf_rec *sc = (mgs_srvconf_rec *)
1217        ap_get_module_config(c->base_server->module_config, &gnutls_module);
1218    mgs_handle_t *ctxt = (mgs_handle_t *)
1219        ap_get_module_config(c->conn_config, &gnutls_module);
1220
1221    if ((sc && (!sc->enabled))
1222        || (ctxt && ctxt->enabled == GNUTLS_ENABLED_FALSE))
1223    {
1224        ap_log_cerror(APLOG_MARK, APLOG_DEBUG, 0, c, "%s declined connection",
1225                      __func__);
1226        return DECLINED;
1227    }
1228
1229    create_gnutls_handle(c);
1230    return OK;
1231}
1232
1233
1234
1235/**
1236 * process_connection hook: Do a zero byte read to trigger the
1237 * handshake. Doesn't change anything for traditional protocols that
1238 * just do reads, but HTTP/2 needs the TLS handshake and ALPN to
1239 * happen before its process_connection hook runs.
1240 */
1241int mgs_hook_process_connection(conn_rec* c)
1242{
1243    mgs_handle_t *ctxt = (mgs_handle_t *)
1244        ap_get_module_config(c->conn_config, &gnutls_module);
1245
1246    if ((ctxt != NULL) && (ctxt->enabled == GNUTLS_ENABLED_TRUE))
1247    {
1248        /* This connection is supposed to use TLS. Give the filters a
1249         * kick with a zero byte read to trigger the handshake. */
1250        apr_bucket_brigade* temp =
1251            apr_brigade_create(c->pool, c->bucket_alloc);
1252        ap_get_brigade(c->input_filters, temp,
1253                       AP_MODE_INIT, APR_BLOCK_READ, 0);
1254        apr_brigade_destroy(temp);
1255    }
1256    return DECLINED;
1257}
1258
1259
1260
1261int mgs_hook_fixups(request_rec * r) {
1262    unsigned char sbuf[GNUTLS_MAX_SESSION_ID];
1263    const char *tmp;
1264    size_t len;
1265    mgs_handle_t *ctxt;
1266    int rv = OK;
1267
1268    if (r == NULL)
1269        return DECLINED;
1270
1271    _gnutls_log(debug_log_fp, "%s: %d\n", __func__, __LINE__);
1272    apr_table_t *env = r->subprocess_env;
1273
1274    ctxt = get_effective_gnutls_ctxt(r->connection);
1275
1276    if (!ctxt || ctxt->enabled != GNUTLS_ENABLED_TRUE || ctxt->session == NULL)
1277    {
1278        ap_log_rerror(APLOG_MARK, APLOG_DEBUG, 0, r, "request declined in %s", __func__);
1279        return DECLINED;
1280    }
1281
1282    apr_table_setn(env, "HTTPS", "on");
1283
1284    apr_table_setn(env, "SSL_VERSION_LIBRARY",
1285            "GnuTLS/" LIBGNUTLS_VERSION);
1286    apr_table_setn(env, "SSL_VERSION_INTERFACE",
1287            "mod_gnutls/" MOD_GNUTLS_VERSION);
1288
1289    apr_table_setn(env, "SSL_PROTOCOL",
1290            gnutls_protocol_get_name(gnutls_protocol_get_version(ctxt->session)));
1291
1292    /* should have been called SSL_CIPHERSUITE instead */
1293    apr_table_setn(env, "SSL_CIPHER",
1294            gnutls_cipher_suite_get_name(gnutls_kx_get(ctxt->session),
1295                                         gnutls_cipher_get(ctxt->session),
1296                                         gnutls_mac_get(ctxt->session)));
1297
1298#if GNUTLS_VERSION_NUMBER >= 0x030600
1299    /* Compression support has been removed since GnuTLS 3.6.0 */
1300    apr_table_setn(env, "SSL_COMPRESS_METHOD", "NULL");
1301#else
1302    apr_table_setn(env, "SSL_COMPRESS_METHOD",
1303            gnutls_compression_get_name(gnutls_compression_get(ctxt->session)));
1304#endif
1305
1306#ifdef ENABLE_SRP
1307    if (ctxt->sc->srp_tpasswd_conf_file != NULL && ctxt->sc->srp_tpasswd_file != NULL) {
1308        tmp = gnutls_srp_server_get_username(ctxt->session);
1309        apr_table_setn(env, "SSL_SRP_USER", (tmp != NULL) ? tmp : "");
1310    } else {
1311        apr_table_unset(env, "SSL_SRP_USER");
1312    }
1313#endif
1314
1315    if (apr_table_get(env, "SSL_CLIENT_VERIFY") == NULL)
1316        apr_table_setn(env, "SSL_CLIENT_VERIFY", "NONE");
1317
1318    unsigned int key_size = 8 * gnutls_cipher_get_key_size(gnutls_cipher_get(ctxt->session));
1319    tmp = apr_psprintf(r->pool, "%u", key_size);
1320
1321    apr_table_setn(env, "SSL_CIPHER_USEKEYSIZE", tmp);
1322
1323    apr_table_setn(env, "SSL_CIPHER_ALGKEYSIZE", tmp);
1324
1325    apr_table_setn(env, "SSL_CIPHER_EXPORT",
1326            (key_size <= 40) ? "true" : "false");
1327
1328    int dhsize = gnutls_dh_get_prime_bits(ctxt->session);
1329    if (dhsize > 0) {
1330        tmp = apr_psprintf(r->pool, "%d", dhsize);
1331        apr_table_setn(env, "SSL_DH_PRIME_BITS", tmp);
1332    }
1333
1334    len = sizeof (sbuf);
1335    gnutls_session_get_id(ctxt->session, sbuf, &len);
1336    apr_table_setn(env, "SSL_SESSION_ID",
1337                   apr_pescape_hex(r->pool, sbuf, len, 0));
1338
1339    if (gnutls_certificate_type_get(ctxt->session) == GNUTLS_CRT_X509) {
1340        mgs_add_common_cert_vars(r, ctxt->sc->certs_x509_crt_chain[0], 0,
1341                                 ctxt->sc->export_certificates_size);
1342    }
1343
1344    return rv;
1345}
1346
1347int mgs_hook_authz(request_rec * r) {
1348    int rv;
1349    mgs_handle_t *ctxt;
1350    mgs_dirconf_rec *dc;
1351
1352    if (r == NULL)
1353        return DECLINED;
1354
1355    dc = ap_get_module_config(r->per_dir_config, &gnutls_module);
1356
1357    _gnutls_log(debug_log_fp, "%s: %d\n", __func__, __LINE__);
1358    ctxt = get_effective_gnutls_ctxt(r->connection);
1359
1360    if (!ctxt || ctxt->session == NULL) {
1361        return DECLINED;
1362    }
1363
1364    if (dc->client_verify_mode == GNUTLS_CERT_IGNORE) {
1365        ap_log_rerror(APLOG_MARK, APLOG_DEBUG, 0, r,
1366                "GnuTLS: Directory set to Ignore Client Certificate!");
1367    } else {
1368        if (ctxt->sc->client_verify_mode < dc->client_verify_mode) {
1369            ap_log_rerror(APLOG_MARK, APLOG_DEBUG, 0, r,
1370                    "GnuTLS: Attempting to rehandshake with peer. %d %d",
1371                    ctxt->sc->client_verify_mode,
1372                    dc->client_verify_mode);
1373
1374            /* If we already have a client certificate, there's no point in
1375             * re-handshaking... */
1376            rv = mgs_cert_verify(r, ctxt);
1377            if (rv != DECLINED && rv != HTTP_FORBIDDEN)
1378                return rv;
1379
1380            gnutls_certificate_server_set_request
1381                    (ctxt->session, dc->client_verify_mode);
1382
1383            if (mgs_rehandshake(ctxt) != 0) {
1384                return HTTP_FORBIDDEN;
1385            }
1386        } else if (ctxt->sc->client_verify_mode ==
1387                GNUTLS_CERT_IGNORE) {
1388#if MOD_GNUTLS_DEBUG
1389            ap_log_rerror(APLOG_MARK, APLOG_INFO, 0, r,
1390                    "GnuTLS: Peer is set to IGNORE");
1391#endif
1392            return DECLINED;
1393        }
1394        rv = mgs_cert_verify(r, ctxt);
1395        if (rv != DECLINED
1396            && (rv != HTTP_FORBIDDEN
1397                || dc->client_verify_mode == GNUTLS_CERT_REQUIRE
1398                || (dc->client_verify_mode == -1
1399                    && ctxt->sc->client_verify_mode == GNUTLS_CERT_REQUIRE)))
1400        {
1401            return rv;
1402        }
1403    }
1404
1405    return DECLINED;
1406}
1407
1408/* variables that are not sent by default:
1409 *
1410 * SSL_CLIENT_CERT      string  PEM-encoded client certificate
1411 * SSL_SERVER_CERT      string  PEM-encoded client certificate
1412 */
1413
1414/* @param side is either 0 for SERVER or 1 for CLIENT
1415 *
1416 * @param export_cert_size (int) maximum size for environment variable
1417 * to use for the PEM-encoded certificate (0 means do not export)
1418 */
1419#define MGS_SIDE(suffix) ((side==0) ? "SSL_SERVER" suffix : "SSL_CLIENT" suffix)
1420
1421static void mgs_add_common_cert_vars(request_rec * r, gnutls_x509_crt_t cert, int side, size_t export_cert_size) {
1422    unsigned char sbuf[64]; /* buffer to hold serials */
1423    char buf[AP_IOBUFSIZE];
1424    const char *tmp;
1425    char *tmp2;
1426    size_t len;
1427    int ret;
1428
1429    if (r == NULL)
1430        return;
1431
1432    apr_table_t *env = r->subprocess_env;
1433
1434    _gnutls_log(debug_log_fp, "%s: %d\n", __func__, __LINE__);
1435    if (export_cert_size > 0) {
1436        len = 0;
1437        ret = gnutls_x509_crt_export(cert, GNUTLS_X509_FMT_PEM, NULL, &len);
1438        if (ret == GNUTLS_E_SHORT_MEMORY_BUFFER) {
1439            if (len >= export_cert_size) {
1440                apr_table_setn(env, MGS_SIDE("_CERT"), "GNUTLS_CERTIFICATE_SIZE_LIMIT_EXCEEDED");
1441                ap_log_rerror(APLOG_MARK, APLOG_INFO, 0, r,
1442                              "GnuTLS: Failed to export too-large X.509 certificate to environment");
1443            } else {
1444                char* cert_buf = apr_palloc(r->pool, len + 1);
1445                if (cert_buf != NULL && gnutls_x509_crt_export(cert, GNUTLS_X509_FMT_PEM, cert_buf, &len) >= 0) {
1446                    cert_buf[len] = 0;
1447                    apr_table_setn(env, MGS_SIDE("_CERT"), cert_buf);
1448                } else {
1449                    ap_log_rerror(APLOG_MARK, APLOG_WARNING, 0, r,
1450                                  "GnuTLS: failed to export X.509 certificate");
1451                }
1452            }
1453        } else {
1454            ap_log_rerror(APLOG_MARK, APLOG_WARNING, 0, r,
1455                          "GnuTLS: dazed and confused about X.509 certificate size");
1456        }
1457    }
1458
1459    len = sizeof (buf);
1460    gnutls_x509_crt_get_dn(cert, buf, &len);
1461    apr_table_setn(env, MGS_SIDE("_S_DN"), apr_pstrmemdup(r->pool, buf, len));
1462
1463    len = sizeof (buf);
1464    gnutls_x509_crt_get_issuer_dn(cert, buf, &len);
1465    apr_table_setn(env, MGS_SIDE("_I_DN"), apr_pstrmemdup(r->pool, buf, len));
1466
1467    len = sizeof (sbuf);
1468    gnutls_x509_crt_get_serial(cert, sbuf, &len);
1469    apr_table_setn(env, MGS_SIDE("_M_SERIAL"),
1470                   apr_pescape_hex(r->pool, sbuf, len, 0));
1471
1472    ret = gnutls_x509_crt_get_version(cert);
1473    if (ret > 0)
1474        apr_table_setn(env, MGS_SIDE("_M_VERSION"),
1475                       apr_psprintf(r->pool, "%u", ret));
1476
1477    apr_table_setn(env, MGS_SIDE("_CERT_TYPE"), "X.509");
1478
1479    tmp =
1480            mgs_time2sz(gnutls_x509_crt_get_expiration_time
1481            (cert), buf, sizeof (buf));
1482    apr_table_setn(env, MGS_SIDE("_V_END"), apr_pstrdup(r->pool, tmp));
1483
1484    tmp =
1485            mgs_time2sz(gnutls_x509_crt_get_activation_time
1486            (cert), buf, sizeof (buf));
1487    apr_table_setn(env, MGS_SIDE("_V_START"), apr_pstrdup(r->pool, tmp));
1488
1489    ret = gnutls_x509_crt_get_signature_algorithm(cert);
1490    if (ret >= 0) {
1491        apr_table_setn(env, MGS_SIDE("_A_SIG"),
1492                gnutls_sign_algorithm_get_name(ret));
1493    }
1494
1495    ret = gnutls_x509_crt_get_pk_algorithm(cert, NULL);
1496    if (ret >= 0) {
1497        apr_table_setn(env, MGS_SIDE("_A_KEY"),
1498                gnutls_pk_algorithm_get_name(ret));
1499    }
1500
1501    /* export all the alternative names (DNS, RFC822 and URI) */
1502    for (int i = 0; !(ret < 0); i++)
1503    {
1504        const char *san, *sanlabel;
1505        len = 0;
1506        ret = gnutls_x509_crt_get_subject_alt_name(cert, i,
1507                NULL, &len,
1508                NULL);
1509
1510        if (ret == GNUTLS_E_SHORT_MEMORY_BUFFER && len > 1) {
1511            tmp2 = apr_palloc(r->pool, len + 1);
1512
1513            ret =
1514                    gnutls_x509_crt_get_subject_alt_name(cert, i,
1515                    tmp2,
1516                    &len,
1517                    NULL);
1518            tmp2[len] = 0;
1519
1520            sanlabel = apr_psprintf(r->pool, "%s%u", MGS_SIDE("_S_AN"), i);
1521            if (ret == GNUTLS_SAN_DNSNAME) {
1522                san = apr_psprintf(r->pool, "DNSNAME:%s", tmp2);
1523            } else if (ret == GNUTLS_SAN_RFC822NAME) {
1524                san = apr_psprintf(r->pool, "RFC822NAME:%s", tmp2);
1525            } else if (ret == GNUTLS_SAN_URI) {
1526                san = apr_psprintf(r->pool, "URI:%s", tmp2);
1527            } else {
1528                san = "UNSUPPORTED";
1529            }
1530            apr_table_setn(env, sanlabel, san);
1531        }
1532    }
1533}
1534
1535
1536
1537/* TODO: Allow client sending a X.509 certificate chain */
1538static int mgs_cert_verify(request_rec * r, mgs_handle_t * ctxt) {
1539    const gnutls_datum_t *cert_list;
1540    unsigned int cert_list_size;
1541    /* assume the certificate is invalid unless explicitly set
1542     * otherwise */
1543    unsigned int status = GNUTLS_CERT_INVALID;
1544    int rv = GNUTLS_E_NO_CERTIFICATE_FOUND, ret;
1545    unsigned int ch_size = 0;
1546
1547    // TODO: union no longer needed here after removing its "pgp" component.
1548    union {
1549        gnutls_x509_crt_t x509[MAX_CHAIN_SIZE];
1550    } cert;
1551    apr_time_t expiration_time, cur_time;
1552
1553    if (r == NULL || ctxt == NULL || ctxt->session == NULL)
1554        return HTTP_FORBIDDEN;
1555
1556    _gnutls_log(debug_log_fp, "%s: %d\n", __func__, __LINE__);
1557    cert_list =
1558            gnutls_certificate_get_peers(ctxt->session, &cert_list_size);
1559
1560    if (cert_list == NULL || cert_list_size == 0) {
1561        /* It is perfectly OK for a client not to send a certificate if on REQUEST mode
1562         */
1563        if (ctxt->sc->client_verify_mode == GNUTLS_CERT_REQUEST)
1564            return OK;
1565
1566        /* no certificate provided by the client, but one was required. */
1567        ap_log_rerror(APLOG_MARK, APLOG_INFO, 0, r,
1568                "GnuTLS: Failed to Verify Peer: "
1569                "Client did not submit a certificate");
1570        return HTTP_FORBIDDEN;
1571    }
1572
1573    if (gnutls_certificate_type_get(ctxt->session) == GNUTLS_CRT_X509) {
1574        ap_log_rerror(APLOG_MARK, APLOG_DEBUG, 0, r,
1575                "GnuTLS: A Chain of %d certificate(s) was provided for validation",
1576                cert_list_size);
1577
1578        for (ch_size = 0; ch_size < cert_list_size; ch_size++) {
1579            gnutls_x509_crt_init(&cert.x509[ch_size]);
1580            rv = gnutls_x509_crt_import(cert.x509[ch_size],
1581                    &cert_list[ch_size],
1582                    GNUTLS_X509_FMT_DER);
1583            // When failure to import, leave the loop
1584            if (rv != GNUTLS_E_SUCCESS) {
1585                if (ch_size < 1) {
1586                    ap_log_rerror(APLOG_MARK,
1587                            APLOG_INFO, 0, r,
1588                            "GnuTLS: Failed to Verify Peer: "
1589                            "Failed to import peer certificates.");
1590                    ret = HTTP_FORBIDDEN;
1591                    goto exit;
1592                }
1593                ap_log_rerror(APLOG_MARK, APLOG_INFO, 0, r,
1594                        "GnuTLS: Failed to import some peer certificates. Using %d certificates",
1595                        ch_size);
1596                rv = GNUTLS_E_SUCCESS;
1597                break;
1598            }
1599        }
1600    } else
1601        return HTTP_FORBIDDEN;
1602
1603    if (rv < 0) {
1604        ap_log_rerror(APLOG_MARK, APLOG_INFO, 0, r,
1605                "GnuTLS: Failed to Verify Peer: "
1606                "Failed to import peer certificates.");
1607        ret = HTTP_FORBIDDEN;
1608        goto exit;
1609    }
1610
1611    if (gnutls_certificate_type_get(ctxt->session) == GNUTLS_CRT_X509) {
1612        apr_time_ansi_put(&expiration_time,
1613                gnutls_x509_crt_get_expiration_time
1614                (cert.x509[0]));
1615
1616        ap_log_rerror(APLOG_MARK, APLOG_DEBUG, 0, r,
1617                      "GnuTLS: Verifying list of %d certificate(s) via method '%s'",
1618                      ch_size, mgs_readable_cvm(ctxt->sc->client_verify_method));
1619        switch(ctxt->sc->client_verify_method) {
1620        case mgs_cvm_cartel:
1621            rv = gnutls_x509_crt_list_verify(cert.x509, ch_size,
1622                                             ctxt->sc->ca_list,
1623                                             ctxt->sc->ca_list_size,
1624                                             NULL, 0, 0, &status);
1625            break;
1626#ifdef ENABLE_MSVA
1627        case mgs_cvm_msva:
1628        {
1629            struct msv_response* resp = NULL;
1630            struct msv_query q = { .context="https", .peertype="client", .pkctype="x509pem" };
1631            msv_ctxt_t ctx = msv_ctxt_init(NULL);
1632            char cert_pem_buf[10 * 1024];
1633            size_t len = sizeof (cert_pem_buf);
1634
1635            rv = 0;
1636            if (gnutls_x509_crt_export(cert.x509[0], GNUTLS_X509_FMT_PEM, cert_pem_buf, &len) >= 0) {
1637                /* FIXME : put together a name from the cert we received, instead of hard-coding this value: */
1638                q.peername = mgs_x509_construct_uid(r, cert.x509[0]);
1639                q.pkcdata = cert_pem_buf;
1640                rv = msv_query_agent(ctx, q, &resp);
1641                if (rv == LIBMSV_ERROR_SUCCESS) {
1642                    status = 0;
1643                } else if (rv == LIBMSV_ERROR_INVALID) {
1644                    ap_log_rerror(APLOG_MARK, APLOG_DEBUG, 0, r,
1645                                  "GnuTLS: Monkeysphere validation failed: (message: %s)", resp->message);
1646                    status = GNUTLS_CERT_INVALID;
1647                } else {
1648                    ap_log_rerror(APLOG_MARK, APLOG_DEBUG, 0, r,
1649                                  "GnuTLS: Error communicating with the Monkeysphere Validation Agent: (%d) %s", rv, msv_strerror(ctx, rv));
1650                    status = GNUTLS_CERT_INVALID;
1651                    rv = -1;
1652                }
1653            } else {
1654                ap_log_rerror(APLOG_MARK, APLOG_INFO, 0, r,
1655                              "GnuTLS: Could not convert the client certificate to PEM format");
1656                status = GNUTLS_CERT_INVALID;
1657                rv = GNUTLS_E_ASN1_ELEMENT_NOT_FOUND;
1658            }
1659            msv_response_destroy(resp);
1660            msv_ctxt_destroy(ctx);
1661        }
1662            break;
1663#endif
1664        default:
1665            /* If this block is reached, that indicates a
1666             * configuration error or bug in mod_gnutls (invalid value
1667             * of ctxt->sc->client_verify_method). */
1668            ap_log_rerror(APLOG_MARK, APLOG_INFO, 0, r,
1669                          "GnuTLS: Failed to Verify X.509 Peer: method '%s' is not supported",
1670                          mgs_readable_cvm(ctxt->sc->client_verify_method));
1671            rv = GNUTLS_E_UNIMPLEMENTED_FEATURE;
1672        }
1673
1674    } else {
1675        /* Unknown certificate type */
1676        rv = GNUTLS_E_UNIMPLEMENTED_FEATURE;
1677    }
1678
1679    /* "goto exit" at the end of this block skips evaluation of the
1680     * "status" variable */
1681    if (rv < 0) {
1682        ap_log_rerror(APLOG_MARK, APLOG_INFO, 0, r,
1683                "GnuTLS: Failed to Verify Peer certificate: (%d) %s",
1684                rv, gnutls_strerror(rv));
1685        if (rv == GNUTLS_E_NO_CERTIFICATE_FOUND)
1686            ap_log_rerror(APLOG_MARK, APLOG_EMERG, 0, r,
1687                "GnuTLS: No certificate was found for verification. Did you set the GnuTLSClientCAFile directive?");
1688        ret = HTTP_FORBIDDEN;
1689        goto exit;
1690    }
1691
1692    /* TODO: X509 CRL Verification. */
1693    /* May add later if anyone needs it.
1694     */
1695    /* ret = gnutls_x509_crt_check_revocation(crt, crl_list, crl_list_size); */
1696
1697    cur_time = apr_time_now();
1698
1699    if (status & GNUTLS_CERT_SIGNER_NOT_FOUND) {
1700        ap_log_rerror(APLOG_MARK, APLOG_INFO, 0, r,
1701                "GnuTLS: Could not find Signer for Peer Certificate");
1702    }
1703
1704    if (status & GNUTLS_CERT_SIGNER_NOT_CA) {
1705        ap_log_rerror(APLOG_MARK, APLOG_INFO, 0, r,
1706                "GnuTLS: Peer's Certificate signer is not a CA");
1707    }
1708
1709    if (status & GNUTLS_CERT_INSECURE_ALGORITHM) {
1710        ap_log_rerror(APLOG_MARK, APLOG_INFO, 0, r,
1711                "GnuTLS: Peer's Certificate is using insecure algorithms");
1712    }
1713
1714    if (status & GNUTLS_CERT_EXPIRED
1715            || status & GNUTLS_CERT_NOT_ACTIVATED) {
1716        ap_log_rerror(APLOG_MARK, APLOG_INFO, 0, r,
1717                "GnuTLS: Peer's Certificate signer is expired or not yet activated");
1718    }
1719
1720    if (status & GNUTLS_CERT_INVALID) {
1721        ap_log_rerror(APLOG_MARK, APLOG_INFO, 0, r,
1722                "GnuTLS: Peer Certificate is invalid.");
1723    } else if (status & GNUTLS_CERT_REVOKED) {
1724        ap_log_rerror(APLOG_MARK, APLOG_INFO, 0, r,
1725                "GnuTLS: Peer Certificate is revoked.");
1726    }
1727
1728    mgs_add_common_cert_vars(r, cert.x509[0], 1, ctxt->sc->export_certificates_size);
1729
1730    {
1731        /* days remaining */
1732        unsigned long remain =
1733                (apr_time_sec(expiration_time) -
1734                apr_time_sec(cur_time)) / 86400;
1735        apr_table_setn(r->subprocess_env, "SSL_CLIENT_V_REMAIN",
1736                apr_psprintf(r->pool, "%lu", remain));
1737    }
1738
1739    if (status == 0) {
1740        apr_table_setn(r->subprocess_env, "SSL_CLIENT_VERIFY",
1741                "SUCCESS");
1742        ret = OK;
1743    } else {
1744        apr_table_setn(r->subprocess_env, "SSL_CLIENT_VERIFY",
1745                "FAILED");
1746        if (ctxt->sc->client_verify_mode == GNUTLS_CERT_REQUEST)
1747            ret = OK;
1748        else
1749            ret = HTTP_FORBIDDEN;
1750    }
1751
1752exit:
1753    if (gnutls_certificate_type_get(ctxt->session) == GNUTLS_CRT_X509)
1754        for (unsigned int i = 0; i < ch_size; i++)
1755            gnutls_x509_crt_deinit(cert.x509[i]);
1756
1757    return ret;
1758}
1759
1760
1761
1762#ifdef ENABLE_MSVA
1763/* this section of code is used only when trying to talk to the MSVA */
1764static const char* mgs_x509_leaf_oid_from_dn(apr_pool_t *pool, const char* oid, gnutls_x509_crt_t cert) {
1765    int rv=GNUTLS_E_SUCCESS, i;
1766    size_t sz=0, lastsz=0;
1767    char* data=NULL;
1768
1769    i = -1;
1770    while(rv != GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE) {
1771        i++;
1772        lastsz=sz;
1773        sz=0;
1774        rv = gnutls_x509_crt_get_dn_by_oid (cert, oid, i, 0, NULL, &sz);
1775    }
1776    if (i > 0) {
1777        data = apr_palloc(pool, lastsz);
1778        sz=lastsz;
1779        rv = gnutls_x509_crt_get_dn_by_oid (cert, oid, i-1, 0, data, &sz);
1780        if (rv == GNUTLS_E_SUCCESS)
1781            return data;
1782    }
1783    return NULL;
1784}
1785
1786static const char* mgs_x509_first_type_from_san(apr_pool_t *pool, gnutls_x509_subject_alt_name_t target, gnutls_x509_crt_t cert) {
1787    int rv=GNUTLS_E_SUCCESS;
1788    size_t sz;
1789    char* data=NULL;
1790    unsigned int i;
1791    gnutls_x509_subject_alt_name_t thistype;
1792
1793    i = 0;
1794    while(rv != GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE) {
1795        sz = 0;
1796        rv = gnutls_x509_crt_get_subject_alt_name2(cert, i, NULL, &sz, &thistype, NULL);
1797        if (rv == GNUTLS_E_SHORT_MEMORY_BUFFER && thistype == target) {
1798            data = apr_palloc(pool, sz);
1799            rv = gnutls_x509_crt_get_subject_alt_name2(cert, i, data, &sz, &thistype, NULL);
1800            if (rv >=0 && (thistype == target))
1801                return data;
1802        }
1803        i++;
1804    }
1805    return NULL;
1806}
1807
1808
1809/* Create a string representing a candidate User ID from an X.509
1810 * certificate
1811
1812 * We need this for client certification because a client gives us a
1813 * certificate, but doesn't tell us (in any other way) who they are
1814 * trying to authenticate as.
1815
1816 * one complaint might be "but the user wanted to be another identity,
1817 * which is also in the certificate (e.g. in a SubjectAltName)"
1818 * However, given that any user can regenerate their own X.509
1819 * certificate with their own public key content, they should just do
1820 * so, and not expect us to guess at their identity :)
1821
1822 * This function allocates it's response from the pool given it.  When
1823 * that pool is reclaimed, the response will also be deallocated.
1824
1825 * FIXME: what about extracting a server-style cert
1826 *        (e.g. https://imposter.example) from the DN or any sAN?
1827
1828 * FIXME: what if we want to call this outside the context of a
1829 *        request?  That complicates the logging.
1830 */
1831static const char* mgs_x509_construct_uid(request_rec *r, gnutls_x509_crt_t cert) {
1832    /* basic strategy, assuming humans are the users: we are going to
1833     * try to reconstruct a "conventional" User ID by pulling in a
1834     * name, comment, and e-mail address.
1835     */
1836    apr_pool_t *pool = r->pool;
1837    const char *name=NULL, *comment=NULL, *email=NULL;
1838    const char *ret=NULL;
1839    /* subpool for temporary allocation: */
1840    apr_pool_t *sp=NULL;
1841
1842    if (APR_SUCCESS != apr_pool_create(&sp, pool))
1843        return NULL; /* i'm assuming that libapr would log this kind
1844                      * of error on its own */
1845
1846     /* Name
1847
1848     the name comes from the leaf commonName of the cert's Subject.
1849
1850     (MAYBE: should we look at trying to assemble a candidate from
1851             givenName, surName, suffix, etc?  the "name" field
1852             appears to be case-insensitive, which seems problematic
1853             from what we expect; see:
1854             http://www.itu.int/rec/T-REC-X.520-200102-s/e )
1855
1856     (MAYBE: should we try pulling a commonName or otherName or
1857             something from subjectAltName? see:
1858             https://tools.ietf.org/html/rfc5280#section-4.2.1.6
1859             GnuTLS does not support looking for Common Names in the
1860             SAN yet)
1861     */
1862    name = mgs_x509_leaf_oid_from_dn(sp, GNUTLS_OID_X520_COMMON_NAME, cert);
1863
1864    /* Comment
1865
1866       I am inclined to punt on this for now, as Comment has been so
1867       atrociously misused in OpenPGP.  Perhaps if there is a
1868       pseudonym (OID 2.5.4.65, aka GNUTLS_OID_X520_PSEUDONYM) field
1869       in the subject or sAN?
1870    */
1871    comment = mgs_x509_leaf_oid_from_dn(sp, GNUTLS_OID_X520_PSEUDONYM, cert);
1872
1873    /* E-mail
1874
1875       This should be the the first rfc822Name from the sAN.
1876
1877       failing that, we'll take the leaf email in the certificate's
1878       subject; this is a deprecated use though.
1879     */
1880    email = mgs_x509_first_type_from_san(sp, GNUTLS_SAN_RFC822NAME, cert);
1881    if (email == NULL)
1882        email = mgs_x509_leaf_oid_from_dn(sp, GNUTLS_OID_PKCS9_EMAIL, cert);
1883
1884    /* assemble all the parts: */
1885
1886    /* must have at least a name or an e-mail. */
1887    if (name == NULL && email == NULL) {
1888        ap_log_rerror(APLOG_MARK, APLOG_INFO, 0, r,
1889                "GnuTLS: Need either a name or an e-mail address to get a User ID from an X.509 certificate.");
1890        goto end;
1891    }
1892    if (name) {
1893        if (comment) {
1894            if (email) {
1895                ret = apr_psprintf(pool, "%s (%s) <%s>", name, comment, email);
1896            } else {
1897                ret = apr_psprintf(pool, "%s (%s)", name, comment);
1898            }
1899        } else {
1900            if (email) {
1901                ret = apr_psprintf(pool, "%s <%s>", name, email);
1902            } else {
1903                ret = apr_pstrdup(pool, name);
1904            }
1905        }
1906    } else {
1907        if (comment) {
1908            ret = apr_psprintf(pool, "(%s) <%s>", comment, email);
1909        } else {
1910            ret = apr_psprintf(pool, "<%s>", email);
1911        }
1912    }
1913
1914end:
1915    apr_pool_destroy(sp);
1916    return ret;
1917}
1918#endif /* ENABLE_MSVA */
1919
1920
1921
1922/*
1923 * This hook writes the mod_gnutls status message for a mod_status
1924 * report. According to the comments in mod_status.h, the "flags"
1925 * parameter is a bitwise OR of the AP_STATUS_ flags.
1926 *
1927 * Note that this implementation gives flags explicitly requesting a
1928 * simple response priority, e.g. if AP_STATUS_SHORT is set, flags
1929 * requesting an HTML report will be ignored. As of Apache 2.4.10, the
1930 * following flags were defined in mod_status.h:
1931 *
1932 * AP_STATUS_SHORT (short, non-HTML report requested)
1933 * AP_STATUS_NOTABLE (HTML report without tables)
1934 * AP_STATUS_EXTENDED (detailed report)
1935 */
1936static int mgs_status_hook(request_rec *r, int flags)
1937{
1938    if (r == NULL)
1939        return OK;
1940
1941    mgs_srvconf_rec *sc = (mgs_srvconf_rec *)
1942        ap_get_module_config(r->server->module_config, &gnutls_module);
1943
1944    _gnutls_log(debug_log_fp, "%s: %d\n", __func__, __LINE__);
1945
1946    if (flags & AP_STATUS_SHORT)
1947    {
1948        ap_rprintf(r, "Using GnuTLS version: %s\n", gnutls_check_version(NULL));
1949        ap_rputs("Built against GnuTLS version: " GNUTLS_VERSION "\n", r);
1950    }
1951    else
1952    {
1953        ap_rputs("<hr>\n", r);
1954        ap_rputs("<h2>GnuTLS Information:</h2>\n<dl>\n", r);
1955
1956        ap_rprintf(r, "<dt>Using GnuTLS version:</dt><dd>%s</dd>\n",
1957                   gnutls_check_version(NULL));
1958        ap_rputs("<dt>Built against GnuTLS version:</dt><dd>"
1959                 GNUTLS_VERSION "</dd>\n", r);
1960        ap_rprintf(r, "<dt>Using TLS:</dt><dd>%s</dd>\n",
1961                   (sc->enabled == GNUTLS_ENABLED_FALSE ? "no" : "yes"));
1962    }
1963
1964    if (sc->enabled != GNUTLS_ENABLED_FALSE)
1965    {
1966        mgs_handle_t* ctxt = get_effective_gnutls_ctxt(r->connection);
1967        if (ctxt && ctxt->session != NULL)
1968        {
1969            char* s_info = gnutls_session_get_desc(ctxt->session);
1970            if (s_info)
1971            {
1972                if (flags & AP_STATUS_SHORT)
1973                    ap_rprintf(r, "Current TLS session: %s\n", s_info);
1974                else
1975                    ap_rprintf(r, "<dt>Current TLS session:</dt><dd>%s</dd>\n",
1976                               s_info);
1977                gnutls_free(s_info);
1978            }
1979        }
1980    }
1981
1982    if (!(flags & AP_STATUS_SHORT))
1983        ap_rputs("</dl>\n", r);
1984
1985    return OK;
1986}
1987
1988
1989
1990/*
1991 * Callback to check the server certificate for proxy HTTPS
1992 * connections, to be used with
1993 * gnutls_certificate_set_verify_function.
1994
1995 * Returns: 0 if certificate check was successful (certificate
1996 * trusted), non-zero otherwise (error during check or untrusted
1997 * certificate).
1998 */
1999static int gtls_check_server_cert(gnutls_session_t session)
2000{
2001    mgs_handle_t *ctxt = (mgs_handle_t *) gnutls_session_get_ptr(session);
2002    unsigned int status;
2003
2004    /* Get peer hostname from a note left by mod_proxy */
2005    const char *peer_hostname =
2006        apr_table_get(ctxt->c->notes, PROXY_SNI_NOTE);
2007    if (peer_hostname == NULL)
2008        ap_log_cerror(APLOG_MARK, APLOG_WARNING, 0, ctxt->c,
2009                      "%s: " PROXY_SNI_NOTE " NULL, cannot check "
2010                      "peer's hostname", __func__);
2011
2012    /* Verify certificate, including hostname match. Should
2013     * peer_hostname be NULL for some reason, the name is not
2014     * checked. */
2015    int err = gnutls_certificate_verify_peers3(session, peer_hostname,
2016                                               &status);
2017    if (err != GNUTLS_E_SUCCESS)
2018    {
2019        ap_log_cerror(APLOG_MARK, APLOG_INFO, 0, ctxt->c,
2020                      "%s: server certificate check failed: %s (%d)",
2021                      __func__, gnutls_strerror(err), err);
2022        return err;
2023    }
2024
2025    if (status == 0)
2026        ap_log_cerror(APLOG_MARK, APLOG_DEBUG, 0, ctxt->c,
2027                      "%s: server certificate is trusted.",
2028                      __func__);
2029    else
2030    {
2031        gnutls_datum_t out;
2032        /* GNUTLS_CRT_X509: ATM, only X509 is supported for proxy
2033         * certs 0: according to function API, the last argument
2034         * should be 0 */
2035        err = gnutls_certificate_verification_status_print(status,
2036                                                           GNUTLS_CRT_X509,
2037                                                           &out, 0);
2038        if (err != GNUTLS_E_SUCCESS)
2039            ap_log_cerror(APLOG_MARK, APLOG_ERR, 0, ctxt->c,
2040                          "%s: server verify print failed: %s (%d)",
2041                          __func__, gnutls_strerror(err), err);
2042        else
2043            ap_log_cerror(APLOG_MARK, APLOG_WARNING, 0, ctxt->c,
2044                          "%s: %s",
2045                          __func__, out.data);
2046        gnutls_free(out.data);
2047    }
2048
2049    return status;
2050}
2051
2052
2053
2054static apr_status_t cleanup_proxy_x509_credentials(void *arg)
2055{
2056    mgs_srvconf_rec *sc = (mgs_srvconf_rec *) arg;
2057
2058    if (sc->proxy_x509_creds)
2059    {
2060        /* This implicitly releases the associated trust list
2061         * sc->proxy_x509_tl, too. */
2062        gnutls_certificate_free_credentials(sc->proxy_x509_creds);
2063        sc->proxy_x509_creds = NULL;
2064        sc->proxy_x509_tl = NULL;
2065    }
2066
2067    if (sc->anon_client_creds)
2068    {
2069        gnutls_anon_free_client_credentials(sc->anon_client_creds);
2070        sc->anon_client_creds = NULL;
2071    }
2072
2073    if (sc->proxy_priorities)
2074    {
2075        gnutls_priority_deinit(sc->proxy_priorities);
2076        sc->proxy_priorities = NULL;
2077    }
2078
2079    return APR_SUCCESS;
2080}
2081
2082
2083
2084static apr_status_t load_proxy_x509_credentials(apr_pool_t *pconf,
2085                                                apr_pool_t *ptemp,
2086                                                server_rec *s)
2087{
2088    mgs_srvconf_rec *sc = (mgs_srvconf_rec *)
2089        ap_get_module_config(s->module_config, &gnutls_module);
2090
2091    if (sc == NULL)
2092        return APR_EGENERAL;
2093
2094    apr_status_t ret = APR_EINIT;
2095    int err = GNUTLS_E_SUCCESS;
2096
2097    /* Cleanup function for the GnuTLS structures allocated below */
2098    apr_pool_cleanup_register(pconf, sc, cleanup_proxy_x509_credentials,
2099                              apr_pool_cleanup_null);
2100
2101    /* Function pool, gets destroyed before exit. */
2102    apr_pool_t *pool;
2103    ret = apr_pool_create(&pool, ptemp);
2104    if (ret != APR_SUCCESS)
2105    {
2106        ap_log_error(APLOG_MARK, APLOG_ERR, ret, s,
2107                     "%s: failed to allocate function memory pool.", __func__);
2108        return ret;
2109    }
2110
2111    /* allocate credentials structures */
2112    err = gnutls_certificate_allocate_credentials(&sc->proxy_x509_creds);
2113    if (err != GNUTLS_E_SUCCESS)
2114    {
2115        ap_log_error(APLOG_MARK, APLOG_ERR, 0, s,
2116                     "%s: Failed to initialize proxy credentials: (%d) %s",
2117                     __func__, err, gnutls_strerror(err));
2118        return APR_EGENERAL;
2119    }
2120    err = gnutls_anon_allocate_client_credentials(&sc->anon_client_creds);
2121    if (err != GNUTLS_E_SUCCESS)
2122    {
2123        ap_log_error(APLOG_MARK, APLOG_ERR, 0, s,
2124                     "%s: Failed to initialize anon credentials for proxy: "
2125                     "(%d) %s", __func__, err, gnutls_strerror(err));
2126        return APR_EGENERAL;
2127    }
2128
2129    /* Check if the proxy priorities have been set, fail immediately
2130     * if not */
2131    if (sc->proxy_priorities_str == NULL)
2132    {
2133        ap_log_error(APLOG_MARK, APLOG_STARTUP, 0, s,
2134                     "Host '%s:%d' is missing the GnuTLSProxyPriorities "
2135                     "directive!",
2136                     s->server_hostname, s->port);
2137        return APR_EGENERAL;
2138    }
2139    /* parse proxy priorities */
2140    const char *err_pos = NULL;
2141    err = gnutls_priority_init(&sc->proxy_priorities,
2142                               sc->proxy_priorities_str, &err_pos);
2143    if (err != GNUTLS_E_SUCCESS)
2144    {
2145        if (ret == GNUTLS_E_INVALID_REQUEST)
2146            ap_log_error(APLOG_MARK, APLOG_ERR, 0, s,
2147                         "%s: Syntax error parsing proxy priorities "
2148                         "string at: %s",
2149                         __func__, err_pos);
2150        else
2151            ap_log_error(APLOG_MARK, APLOG_ERR, 0, s,
2152                         "Error setting proxy priorities: %s (%d)",
2153                         gnutls_strerror(err), err);
2154        ret = APR_EGENERAL;
2155    }
2156
2157    /* load certificate and key for client auth, if configured */
2158    if (sc->proxy_x509_key_file && sc->proxy_x509_cert_file)
2159    {
2160        char* cert_file = ap_server_root_relative(pool,
2161                                                  sc->proxy_x509_cert_file);
2162        char* key_file = ap_server_root_relative(pool,
2163                                                 sc->proxy_x509_key_file);
2164        err = gnutls_certificate_set_x509_key_file(sc->proxy_x509_creds,
2165                                                   cert_file,
2166                                                   key_file,
2167                                                   GNUTLS_X509_FMT_PEM);
2168        if (err != GNUTLS_E_SUCCESS)
2169        {
2170            ap_log_error(APLOG_MARK, APLOG_ERR, 0, s,
2171                         "%s: loading proxy client credentials failed: %s (%d)",
2172                         __func__, gnutls_strerror(err), err);
2173            ret = APR_EGENERAL;
2174        }
2175    }
2176    else if (!sc->proxy_x509_key_file && sc->proxy_x509_cert_file)
2177    {
2178        ap_log_error(APLOG_MARK, APLOG_WARNING, 0, s,
2179                     "%s: proxy key file not set!", __func__);
2180        ret = APR_EGENERAL;
2181    }
2182    else if (!sc->proxy_x509_cert_file && sc->proxy_x509_key_file)
2183    {
2184        ap_log_error(APLOG_MARK, APLOG_WARNING, 0, s,
2185                     "%s: proxy certificate file not set!", __func__);
2186        ret = APR_EGENERAL;
2187    }
2188    else
2189        /* if both key and cert are NULL, client auth is not used */
2190        ap_log_error(APLOG_MARK, APLOG_INFO, 0, s,
2191                     "%s: no client credentials for proxy", __func__);
2192
2193    /* must be set if the server certificate is to be checked */
2194    if (sc->proxy_x509_ca_file)
2195    {
2196        /* initialize the trust list */
2197        err = gnutls_x509_trust_list_init(&sc->proxy_x509_tl, 0);
2198        if (err != GNUTLS_E_SUCCESS)
2199        {
2200            ap_log_error(APLOG_MARK, APLOG_ERR, 0, s,
2201                         "%s: gnutls_x509_trust_list_init failed: %s (%d)",
2202                         __func__, gnutls_strerror(err), err);
2203            ret = APR_EGENERAL;
2204        }
2205
2206        char* ca_file = ap_server_root_relative(pool,
2207                                                sc->proxy_x509_ca_file);
2208        /* if no CRL is used, sc->proxy_x509_crl_file is NULL */
2209        char* crl_file = NULL;
2210        if (sc->proxy_x509_crl_file)
2211            crl_file = ap_server_root_relative(pool,
2212                                               sc->proxy_x509_crl_file);
2213
2214        /* returns number of loaded elements */
2215        err = gnutls_x509_trust_list_add_trust_file(sc->proxy_x509_tl,
2216                                                    ca_file,
2217                                                    crl_file,
2218                                                    GNUTLS_X509_FMT_PEM,
2219                                                    0 /* tl_flags */,
2220                                                    0 /* tl_vflags */);
2221        if (err > 0)
2222            ap_log_error(APLOG_MARK, APLOG_DEBUG, 0, s,
2223                         "%s: proxy CA trust list: %d structures loaded",
2224                         __func__, err);
2225        else if (err == 0)
2226            ap_log_error(APLOG_MARK, APLOG_WARNING, 0, s,
2227                         "%s: proxy CA trust list is empty (%d)",
2228                         __func__, err);
2229        else /* err < 0 */
2230        {
2231            ap_log_error(APLOG_MARK, APLOG_ERR, 0, s,
2232                         "%s: error loading proxy CA trust list: %s (%d)",
2233                         __func__, gnutls_strerror(err), err);
2234            ret = APR_EGENERAL;
2235        }
2236
2237        /* attach trust list to credentials */
2238        gnutls_certificate_set_trust_list(sc->proxy_x509_creds,
2239                                          sc->proxy_x509_tl, 0);
2240    }
2241    else
2242        ap_log_error(APLOG_MARK, APLOG_WARNING, 0, s,
2243                     "%s: no CA trust list for proxy connections, "
2244                     "TLS connections will fail!", __func__);
2245
2246    gnutls_certificate_set_verify_function(sc->proxy_x509_creds,
2247                                           gtls_check_server_cert);
2248    apr_pool_destroy(pool);
2249    return ret;
2250}
Note: See TracBrowser for help on using the repository browser.