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