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