include/apr_ldap_option.h

   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
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  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.
  15  */
  16
  17 /**
  18  * @file apr_ldap_option.h
  19  * @brief  APR-UTIL LDAP ldap_*_option() functions
  20  */
  21 #ifndef APR_LDAP_OPTION_H
  22 #define APR_LDAP_OPTION_H
  23
  24 /**
  25  * @defgroup APR_Util_LDAP LDAP
  26  * @ingroup APR_Util
  27  * @{
  28  */
  29
  30 #include "apr_ldap.h"
  31
  32 #if APR_HAS_LDAP
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif /* __cplusplus */
  37
  38 /*
  39  * The following defines handle the different TLS certificate
  40  * options available. If these options are missing, APR will try and
  41  * emulate support for this using the deprecated ldap_start_tls_s()
  42  * function.
  43  */
  44 /**
  45  * Set SSL mode to one of APR_LDAP_NONE, APR_LDAP_SSL, APR_LDAP_STARTTLS
  46  * or APR_LDAP_STOPTLS.
  47  */
  48 #define APR_LDAP_OPT_TLS 0x6fff
  49 /**
  50  * Set zero or more CA certificates, client certificates or private
  51  * keys globally, or per connection (where supported).
  52  */
  53 #define APR_LDAP_OPT_TLS_CERT 0x6ffe
  54 /**
  55  * Set the LDAP library to no verify the server certificate.  This means
  56  * all servers are considered trusted.
  57  */
  58 #define APR_LDAP_OPT_VERIFY_CERT 0x6ffd
  59 /**
  60  * Set the LDAP library to indicate if referrals should be chased during
  61  * LDAP searches.
  62  */
  63 #define APR_LDAP_OPT_REFERRALS 0x6ffc
  64 /**
  65  * Set the LDAP library to indicate a maximum number of referral hops to
  66  * chase before giving up on the search.
  67  */
  68 #define APR_LDAP_OPT_REFHOPLIMIT 0x6ffb
  69
  70 /**
  71  * Structures for the apr_set_option() cases
  72  */
  73
  74 /**
  75  * APR_LDAP_OPT_TLS_CERT
  76  *
  77  * This structure includes possible options to set certificates on
  78  * system initialisation. Different SDKs have different certificate
  79  * requirements, and to achieve this multiple certificates must be
  80  * specified at once passed as an (apr_array_header_t *).
  81  *
  82  * Netscape:
  83  * Needs the CA cert database (cert7.db), the client cert database (key3.db)
  84  * and the security module file (secmod.db) set at the system initialisation
  85  * time. Three types are supported: APR_LDAP_CERT7_DB, APR_LDAP_KEY3_DB and
  86  * APR_LDAP_SECMOD.
  87  *
  88  * To specify a client cert connection, a certificate nickname needs to be
  89  * provided with a type of APR_LDAP_CERT.
  90  * int ldapssl_enable_clientauth( LDAP *ld, char *keynickname,
  91  * char *keypasswd, char *certnickname );
  92  * keynickname is currently not used, and should be set to ""
  93  *
  94  * Novell:
  95  * Needs CA certificates and client certificates set at system initialisation
  96  * time. Three types are supported: APR_LDAP_CA*, APR_LDAP_CERT* and
  97  * APR_LDAP_KEY*.
  98  *
  99  * Certificates cannot be specified per connection.
 100  *
 101  * The functions used are:
 102  * ldapssl_add_trusted_cert(serverTrustedRoot, serverTrustedRootEncoding);
 103  * Clients certs and keys are set at system initialisation time with
 104  * int ldapssl_set_client_cert (
 105  *  void   *cert,
 106  *  int     type
 107  *  void   *password);
 108  * type can be LDAPSSL_CERT_FILETYPE_B64 or LDAPSSL_CERT_FILETYPE_DER
 109  *  ldapssl_set_client_private_key(clientPrivateKey,
 110  *                                 clientPrivateKeyEncoding,
 111  *                                 clientPrivateKeyPassword);
 112  *
 113  * OpenSSL:
 114  * Needs one or more CA certificates to be set at system initialisation time
 115  * with a type of APR_LDAP_CA*.
 116  *
 117  * May have one or more client certificates set per connection with a type of
 118  * APR_LDAP_CERT*, and keys with APR_LDAP_KEY*.
 119  */
 120 /** CA certificate type unknown */
 121 #define APR_LDAP_CA_TYPE_UNKNOWN    0
 122 /** binary DER encoded CA certificate */
 123 #define APR_LDAP_CA_TYPE_DER        1
 124 /** PEM encoded CA certificate */
 125 #define APR_LDAP_CA_TYPE_BASE64     2
 126 /** Netscape/Mozilla cert7.db CA certificate database */
 127 #define APR_LDAP_CA_TYPE_CERT7_DB   3
 128 /** Netscape/Mozilla secmod file */
 129 #define APR_LDAP_CA_TYPE_SECMOD     4
 130 /** Client certificate type unknown */
 131 #define APR_LDAP_CERT_TYPE_UNKNOWN  5
 132 /** binary DER encoded client certificate */
 133 #define APR_LDAP_CERT_TYPE_DER      6
 134 /** PEM encoded client certificate */
 135 #define APR_LDAP_CERT_TYPE_BASE64   7
 136 /** Netscape/Mozilla key3.db client certificate database */
 137 #define APR_LDAP_CERT_TYPE_KEY3_DB  8
 138 /** Netscape/Mozilla client certificate nickname */
 139 #define APR_LDAP_CERT_TYPE_NICKNAME 9
 140 /** Private key type unknown */
 141 #define APR_LDAP_KEY_TYPE_UNKNOWN   10
 142 /** binary DER encoded private key */
 143 #define APR_LDAP_KEY_TYPE_DER       11
 144 /** PEM encoded private key */
 145 #define APR_LDAP_KEY_TYPE_BASE64    12
 146 /** PKCS#12 encoded client certificate */
 147 #define APR_LDAP_CERT_TYPE_PFX      13
 148 /** PKCS#12 encoded private key */
 149 #define APR_LDAP_KEY_TYPE_PFX       14
 150 /** Openldap directory full of base64-encoded cert
 151  * authorities with hashes in corresponding .0 directory
 152  */
 153 #define APR_LDAP_CA_TYPE_CACERTDIR_BASE64 15
 154
 155
 156 /**
 157  * Certificate structure.
 158  *
 159  * This structure is used to store certificate details. An array of
 160  * these structures is passed to apr_ldap_set_option() to set CA
 161  * and client certificates.
 162  * @param type Type of certificate APR_LDAP_*_TYPE_*
 163  * @param path Path, file or nickname of the certificate
 164  * @param password Optional password, can be NULL
 165  */
 166 typedef struct apr_ldap_opt_tls_cert_t apr_ldap_opt_tls_cert_t;
 167 struct apr_ldap_opt_tls_cert_t {
 168     int type;
 169     const char *path;
 170     const char *password;
 171 };
 172
 173 /**
 174  * APR_LDAP_OPT_TLS
 175  *
 176  * This sets the SSL level on the LDAP handle.
 177  *
 178  * Netscape/Mozilla:
 179  * Supports SSL, but not STARTTLS
 180  * SSL is enabled by calling ldapssl_install_routines().
 181  *
 182  * Novell:
 183  * Supports SSL and STARTTLS.
 184  * SSL is enabled by calling ldapssl_install_routines(). Note that calling
 185  * other ldap functions before ldapssl_install_routines() may cause this
 186  * function to fail.
 187  * STARTTLS is enabled by calling ldapssl_start_tls_s() after calling
 188  * ldapssl_install_routines() (check this).
 189  *
 190  * OpenLDAP:
 191  * Supports SSL and supports STARTTLS, but none of this is documented:
 192  * http://www.openldap.org/lists/openldap-software/200409/msg00618.html
 193  * Documentation for both SSL support and STARTTLS has been deleted from
 194  * the OpenLDAP documentation and website.
 195  */
 196
 197 /** No encryption */
 198 #define APR_LDAP_NONE 0
 199 /** SSL encryption (ldaps://) */
 200 #define APR_LDAP_SSL 1
 201 /** TLS encryption (STARTTLS) */
 202 #define APR_LDAP_STARTTLS 2
 203 /** end TLS encryption (STOPTLS) */
 204 #define APR_LDAP_STOPTLS 3
 205
 206 /**
 207  * APR LDAP get option function
 208  *
 209  * This function gets option values from a given LDAP session if
 210  * one was specified. It maps to the native ldap_get_option() function.
 211  * @param pool The pool to use
 212  * @param ldap The LDAP handle
 213  * @param option The LDAP_OPT_* option to return
 214  * @param outvalue The value returned (if any)
 215  * @param result_err The apr_ldap_err_t structure contained detailed results
 216  *        of the operation.
 217  */
 218 APU_DECLARE_LDAP(int) apr_ldap_get_option(apr_pool_t *pool,
 219                                           LDAP *ldap,
 220                                           int option,
 221                                           void *outvalue,
 222                                           apr_ldap_err_t **result_err);
 223
 224 /**
 225  * APR LDAP set option function
 226  *
 227  * This function sets option values to a given LDAP session if
 228  * one was specified. It maps to the native ldap_set_option() function.
 229  *
 230  * Where an option is not supported by an LDAP toolkit, this function
 231  * will try and apply legacy functions to achieve the same effect,
 232  * depending on the platform.
 233  * @param pool The pool to use
 234  * @param ldap The LDAP handle
 235  * @param option The LDAP_OPT_* option to set
 236  * @param invalue The value to set
 237  * @param result_err The apr_ldap_err_t structure contained detailed results
 238  *        of the operation.
 239  */
 240 APU_DECLARE_LDAP(int) apr_ldap_set_option(apr_pool_t *pool,
 241                                           LDAP *ldap,
 242                                           int option,
 243                                           const void *invalue,
 244                                           apr_ldap_err_t **result_err);
 245
 246 #ifdef __cplusplus
 247 }
 248 #endif
 249
 250 #endif /* APR_HAS_LDAP */
 251
 252 /** @} */
 253
 254 #endif /* APR_LDAP_OPTION_H */
 255