Apache Portable Runtime

apr_ldap_option.h

Go to the documentation of this file.
00001 /* Licensed to the Apache Software Foundation (ASF) under one or more
00002  * contributor license agreements.  See the NOTICE file distributed with
00003  * this work for additional information regarding copyright ownership.
00004  * The ASF licenses this file to You under the Apache License, Version 2.0
00005  * (the "License"); you may not use this file except in compliance with
00006  * the License.  You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 /**
00018  * @file apr_ldap_option.h
00019  * @brief  APR-UTIL LDAP ldap_*_option() functions
00020  */
00021 #ifndef APR_LDAP_OPTION_H
00022 #define APR_LDAP_OPTION_H
00023 
00024 /**
00025  * @addtogroup APR_Util_LDAP
00026  * @{
00027  */
00028 
00029 #include "apr_ldap.h"
00030 
00031 #if APR_HAS_LDAP
00032 
00033 #ifdef __cplusplus
00034 extern "C" {
00035 #endif /* __cplusplus */
00036 
00037 /*
00038  * The following defines handle the different TLS certificate
00039  * options available. If these options are missing, APR will try and
00040  * emulate support for this using the deprecated ldap_start_tls_s()
00041  * function.
00042  */
00043 /**
00044  * Set SSL mode to one of APR_LDAP_NONE, APR_LDAP_SSL, APR_LDAP_STARTTLS
00045  * or APR_LDAP_STOPTLS.
00046  */
00047 #define APR_LDAP_OPT_TLS 0x6fff
00048 /**
00049  * Set zero or more CA certificates, client certificates or private
00050  * keys globally, or per connection (where supported).
00051  */
00052 #define APR_LDAP_OPT_TLS_CERT 0x6ffe
00053 /**
00054  * Set the LDAP library to no verify the server certificate.  This means
00055  * all servers are considered trusted.
00056  */
00057 #define APR_LDAP_OPT_VERIFY_CERT 0x6ffd
00058 /**
00059  * Set the LDAP library to indicate if referrals should be chased during
00060  * LDAP searches.
00061  */
00062 #define APR_LDAP_OPT_REFERRALS 0x6ffc
00063 /**
00064  * Set the LDAP library to indicate a maximum number of referral hops to
00065  * chase before giving up on the search.
00066  */
00067 #define APR_LDAP_OPT_REFHOPLIMIT 0x6ffb
00068 
00069 /**
00070  * Structures for the apr_set_option() cases
00071  */
00072 
00073 /**
00074  * APR_LDAP_OPT_TLS_CERT
00075  *
00076  * This structure includes possible options to set certificates on
00077  * system initialisation. Different SDKs have different certificate
00078  * requirements, and to achieve this multiple certificates must be
00079  * specified at once passed as an (apr_array_header_t *).
00080  *
00081  * Netscape:
00082  * Needs the CA cert database (cert7.db), the client cert database (key3.db)
00083  * and the security module file (secmod.db) set at the system initialisation
00084  * time. Three types are supported: APR_LDAP_CERT7_DB, APR_LDAP_KEY3_DB and
00085  * APR_LDAP_SECMOD.
00086  *
00087  * To specify a client cert connection, a certificate nickname needs to be
00088  * provided with a type of APR_LDAP_CERT.
00089  * int ldapssl_enable_clientauth( LDAP *ld, char *keynickname,
00090  * char *keypasswd, char *certnickname );
00091  * keynickname is currently not used, and should be set to ""
00092  *
00093  * Novell:
00094  * Needs CA certificates and client certificates set at system initialisation
00095  * time. Three types are supported: APR_LDAP_CA*, APR_LDAP_CERT* and
00096  * APR_LDAP_KEY*.
00097  *
00098  * Certificates cannot be specified per connection.
00099  *
00100  * The functions used are:
00101  * ldapssl_add_trusted_cert(serverTrustedRoot, serverTrustedRootEncoding);
00102  * Clients certs and keys are set at system initialisation time with
00103  * int ldapssl_set_client_cert (
00104  *  void   *cert,
00105  *  int     type
00106  *  void   *password); 
00107  * type can be LDAPSSL_CERT_FILETYPE_B64 or LDAPSSL_CERT_FILETYPE_DER
00108  *  ldapssl_set_client_private_key(clientPrivateKey,
00109  *                                 clientPrivateKeyEncoding,
00110  *                                 clientPrivateKeyPassword);
00111  *
00112  * OpenSSL:
00113  * Needs one or more CA certificates to be set at system initialisation time
00114  * with a type of APR_LDAP_CA*.
00115  *
00116  * May have one or more client certificates set per connection with a type of
00117  * APR_LDAP_CERT*, and keys with APR_LDAP_KEY*.
00118  */
00119 /** CA certificate type unknown */
00120 #define APR_LDAP_CA_TYPE_UNKNOWN    0
00121 /** binary DER encoded CA certificate */
00122 #define APR_LDAP_CA_TYPE_DER        1
00123 /** PEM encoded CA certificate */
00124 #define APR_LDAP_CA_TYPE_BASE64     2
00125 /** Netscape/Mozilla cert7.db CA certificate database */
00126 #define APR_LDAP_CA_TYPE_CERT7_DB   3
00127 /** Netscape/Mozilla secmod file */
00128 #define APR_LDAP_CA_TYPE_SECMOD     4
00129 /** Client certificate type unknown */
00130 #define APR_LDAP_CERT_TYPE_UNKNOWN  5
00131 /** binary DER encoded client certificate */
00132 #define APR_LDAP_CERT_TYPE_DER      6
00133 /** PEM encoded client certificate */
00134 #define APR_LDAP_CERT_TYPE_BASE64   7
00135 /** Netscape/Mozilla key3.db client certificate database */
00136 #define APR_LDAP_CERT_TYPE_KEY3_DB  8
00137 /** Netscape/Mozilla client certificate nickname */
00138 #define APR_LDAP_CERT_TYPE_NICKNAME 9
00139 /** Private key type unknown */
00140 #define APR_LDAP_KEY_TYPE_UNKNOWN   10
00141 /** binary DER encoded private key */
00142 #define APR_LDAP_KEY_TYPE_DER       11
00143 /** PEM encoded private key */
00144 #define APR_LDAP_KEY_TYPE_BASE64    12
00145 /** PKCS#12 encoded client certificate */
00146 #define APR_LDAP_CERT_TYPE_PFX      13
00147 /** PKCS#12 encoded private key */
00148 #define APR_LDAP_KEY_TYPE_PFX       14
00149 /** Openldap directory full of base64-encoded cert 
00150  * authorities with hashes in corresponding .0 directory
00151  */
00152 #define APR_LDAP_CA_TYPE_CACERTDIR_BASE64 15
00153 
00154 
00155 /**
00156  * Certificate structure.
00157  *
00158  * This structure is used to store certificate details. An array of
00159  * these structures is passed to apr_ldap_set_option() to set CA
00160  * and client certificates.
00161  * @param type Type of certificate APR_LDAP_*_TYPE_*
00162  * @param path Path, file or nickname of the certificate
00163  * @param password Optional password, can be NULL
00164  */
00165 typedef struct apr_ldap_opt_tls_cert_t apr_ldap_opt_tls_cert_t;
00166 struct apr_ldap_opt_tls_cert_t {
00167     int type;
00168     const char *path;
00169     const char *password;
00170 };
00171 
00172 /**
00173  * APR_LDAP_OPT_TLS
00174  *
00175  * This sets the SSL level on the LDAP handle.
00176  *
00177  * Netscape/Mozilla:
00178  * Supports SSL, but not STARTTLS
00179  * SSL is enabled by calling ldapssl_install_routines().
00180  *
00181  * Novell:
00182  * Supports SSL and STARTTLS.
00183  * SSL is enabled by calling ldapssl_install_routines(). Note that calling
00184  * other ldap functions before ldapssl_install_routines() may cause this
00185  * function to fail.
00186  * STARTTLS is enabled by calling ldapssl_start_tls_s() after calling
00187  * ldapssl_install_routines() (check this).
00188  *
00189  * OpenLDAP:
00190  * Supports SSL and supports STARTTLS, but none of this is documented:
00191  * http://www.openldap.org/lists/openldap-software/200409/msg00618.html
00192  * Documentation for both SSL support and STARTTLS has been deleted from
00193  * the OpenLDAP documentation and website.
00194  */
00195 
00196 /** No encryption */
00197 #define APR_LDAP_NONE 0
00198 /** SSL encryption (ldaps://) */
00199 #define APR_LDAP_SSL 1
00200 /** TLS encryption (STARTTLS) */
00201 #define APR_LDAP_STARTTLS 2
00202 /** end TLS encryption (STOPTLS) */
00203 #define APR_LDAP_STOPTLS 3
00204 
00205 /**
00206  * APR LDAP get option function
00207  *
00208  * This function gets option values from a given LDAP session if
00209  * one was specified. It maps to the native ldap_get_option() function.
00210  * @param pool The pool to use
00211  * @param ldap The LDAP handle
00212  * @param option The LDAP_OPT_* option to return
00213  * @param outvalue The value returned (if any)
00214  * @param result_err The apr_ldap_err_t structure contained detailed results
00215  *        of the operation.
00216  */
00217 APU_DECLARE_LDAP(int) apr_ldap_get_option(apr_pool_t *pool,
00218                                           LDAP *ldap,
00219                                           int option,
00220                                           void *outvalue,
00221                                           apr_ldap_err_t **result_err);
00222 
00223 /**
00224  * APR LDAP set option function
00225  * 
00226  * This function sets option values to a given LDAP session if
00227  * one was specified. It maps to the native ldap_set_option() function.
00228  * 
00229  * Where an option is not supported by an LDAP toolkit, this function
00230  * will try and apply legacy functions to achieve the same effect,
00231  * depending on the platform.
00232  * @param pool The pool to use
00233  * @param ldap The LDAP handle
00234  * @param option The LDAP_OPT_* option to set
00235  * @param invalue The value to set
00236  * @param result_err The apr_ldap_err_t structure contained detailed results
00237  *        of the operation.
00238  */
00239 APU_DECLARE_LDAP(int) apr_ldap_set_option(apr_pool_t *pool,
00240                                           LDAP *ldap,
00241                                           int option,
00242                                           const void *invalue,
00243                                           apr_ldap_err_t **result_err);
00244 
00245 #ifdef __cplusplus
00246 }
00247 #endif
00248 
00249 #endif /* APR_HAS_LDAP */
00250 
00251 /** @} */
00252 
00253 #endif /* APR_LDAP_OPTION_H */
00254 
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Defines