00001 /* Copyright 2000-2005 The Apache Software Foundation or its licensors, as 00002 * applicable. 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"); 00005 * you may not use this file except in compliance with the License. 00006 * 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 /** 00061 * Structures for the apr_set_option() cases 00062 */ 00063 00064 /** 00065 * APR_LDAP_OPT_TLS_CERT 00066 * 00067 * This structure includes possible options to set certificates on 00068 * system initialisation. Different SDKs have different certificate 00069 * requirements, and to achieve this multiple certificates must be 00070 * specified at once passed as an (apr_array_header_t *). 00071 * 00072 * Netscape: 00073 * Needs the CA cert database (cert7.db), the client cert database (key3.db) 00074 * and the security module file (secmod.db) set at the system initialisation 00075 * time. Three types are supported: APR_LDAP_CERT7_DB, APR_LDAP_KEY3_DB and 00076 * APR_LDAP_SECMOD. 00077 * 00078 * To specify a client cert connection, a certificate nickname needs to be 00079 * provided with a type of APR_LDAP_CERT. 00080 * int ldapssl_enable_clientauth( LDAP *ld, char *keynickname, 00081 * char *keypasswd, char *certnickname ); 00082 * keynickname is currently not used, and should be set to "" 00083 * 00084 * Novell: 00085 * Needs CA certificates and client certificates set at system initialisation 00086 * time. Three types are supported: APR_LDAP_CA*, APR_LDAP_CERT* and 00087 * APR_LDAP_KEY*. 00088 * 00089 * Certificates cannot be specified per connection. 00090 * 00091 * The functions used are: 00092 * ldapssl_add_trusted_cert(serverTrustedRoot, serverTrustedRootEncoding); 00093 * Clients certs and keys are set at system initialisation time with 00094 * int ldapssl_set_client_cert ( 00095 * void *cert, 00096 * int type 00097 * void *password); 00098 * type can be LDAPSSL_CERT_FILETYPE_B64 or LDAPSSL_CERT_FILETYPE_DER 00099 * ldapssl_set_client_private_key(clientPrivateKey, 00100 * clientPrivateKeyEncoding, 00101 * clientPrivateKeyPassword); 00102 * 00103 * OpenSSL: 00104 * Needs one or more CA certificates to be set at system initialisation time 00105 * with a type of APR_LDAP_CA*. 00106 * 00107 * May have one or more client certificates set per connection with a type of 00108 * APR_LDAP_CERT*, and keys with APR_LDAP_KEY*. 00109 */ 00110 /** CA certificate type unknown */ 00111 #define APR_LDAP_CA_TYPE_UNKNOWN 0 00112 /** binary DER encoded CA certificate */ 00113 #define APR_LDAP_CA_TYPE_DER 1 00114 /** PEM encoded CA certificate */ 00115 #define APR_LDAP_CA_TYPE_BASE64 2 00116 /** Netscape/Mozilla cert7.db CA certificate database */ 00117 #define APR_LDAP_CA_TYPE_CERT7_DB 3 00118 /** Netscape/Mozilla secmod file */ 00119 #define APR_LDAP_CA_TYPE_SECMOD 4 00120 /** Client certificate type unknown */ 00121 #define APR_LDAP_CERT_TYPE_UNKNOWN 5 00122 /** binary DER encoded client certificate */ 00123 #define APR_LDAP_CERT_TYPE_DER 6 00124 /** PEM encoded client certificate */ 00125 #define APR_LDAP_CERT_TYPE_BASE64 7 00126 /** Netscape/Mozilla key3.db client certificate database */ 00127 #define APR_LDAP_CERT_TYPE_KEY3_DB 8 00128 /** Netscape/Mozilla client certificate nickname */ 00129 #define APR_LDAP_CERT_TYPE_NICKNAME 9 00130 /** Private key type unknown */ 00131 #define APR_LDAP_KEY_TYPE_UNKNOWN 10 00132 /** binary DER encoded private key */ 00133 #define APR_LDAP_KEY_TYPE_DER 11 00134 /** PEM encoded private key */ 00135 #define APR_LDAP_KEY_TYPE_BASE64 12 00136 /** PKCS#12 encoded client certificate */ 00137 #define APR_LDAP_CERT_TYPE_PFX 13 00138 /** PKCS#12 encoded private key */ 00139 #define APR_LDAP_KEY_TYPE_PFX 14 00140 00141 /** 00142 * Certificate structure. 00143 * 00144 * This structure is used to store certificate details. An array of 00145 * these structures is passed to apr_ldap_set_option() to set CA 00146 * and client certificates. 00147 * @param type Type of certificate APR_LDAP_*_TYPE_* 00148 * @param path Path, file or nickname of the certificate 00149 * @param password Optional password, can be NULL 00150 */ 00151 typedef struct apr_ldap_opt_tls_cert_t apr_ldap_opt_tls_cert_t; 00152 struct apr_ldap_opt_tls_cert_t { 00153 int type; 00154 const char *path; 00155 const char *password; 00156 }; 00157 00158 /** 00159 * APR_LDAP_OPT_TLS 00160 * 00161 * This sets the SSL level on the LDAP handle. 00162 * 00163 * Netscape/Mozilla: 00164 * Supports SSL, but not STARTTLS 00165 * SSL is enabled by calling ldapssl_install_routines(). 00166 * 00167 * Novell: 00168 * Supports SSL and STARTTLS. 00169 * SSL is enabled by calling ldapssl_install_routines(). Note that calling 00170 * other ldap functions before ldapssl_install_routines() may cause this 00171 * function to fail. 00172 * STARTTLS is enabled by calling ldapssl_start_tls_s() after calling 00173 * ldapssl_install_routines() (check this). 00174 * 00175 * OpenLDAP: 00176 * Supports SSL and supports STARTTLS, but none of this is documented: 00177 * http://www.openldap.org/lists/openldap-software/200409/msg00618.html 00178 * Documentation for both SSL support and STARTTLS has been deleted from 00179 * the OpenLDAP documentation and website. 00180 */ 00181 00182 /** No encryption */ 00183 #define APR_LDAP_NONE 0 00184 /** SSL encryption (ldaps://) */ 00185 #define APR_LDAP_SSL 1 00186 /** TLS encryption (STARTTLS) */ 00187 #define APR_LDAP_STARTTLS 2 00188 /** end TLS encryption (STOPTLS) */ 00189 #define APR_LDAP_STOPTLS 3 00190 00191 /** 00192 * APR LDAP get option function 00193 * 00194 * This function gets option values from a given LDAP session if 00195 * one was specified. It maps to the native ldap_get_option() function. 00196 * @param pool The pool to use 00197 * @param ldap The LDAP handle 00198 * @param option The LDAP_OPT_* option to return 00199 * @param outvalue The value returned (if any) 00200 * @param result_err The apr_ldap_err_t structure contained detailed results 00201 * of the operation. 00202 */ 00203 APU_DECLARE(int) apr_ldap_get_option(apr_pool_t *pool, 00204 LDAP *ldap, 00205 int option, 00206 void *outvalue, 00207 apr_ldap_err_t **result_err); 00208 00209 /** 00210 * APR LDAP set option function 00211 * 00212 * This function sets option values to a given LDAP session if 00213 * one was specified. It maps to the native ldap_set_option() function. 00214 * 00215 * Where an option is not supported by an LDAP toolkit, this function 00216 * will try and apply legacy functions to achieve the same effect, 00217 * depending on the platform. 00218 * @param pool The pool to use 00219 * @param ldap The LDAP handle 00220 * @param option The LDAP_OPT_* option to set 00221 * @param invalue The value to set 00222 * @param result_err The apr_ldap_err_t structure contained detailed results 00223 * of the operation. 00224 */ 00225 APU_DECLARE(int) apr_ldap_set_option(apr_pool_t *pool, 00226 LDAP *ldap, 00227 int option, 00228 const void *invalue, 00229 apr_ldap_err_t **result_err); 00230 00231 #ifdef __cplusplus 00232 } 00233 #endif 00234 00235 #endif /* APR_HAS_LDAP */ 00236 00237 /** @} */ 00238 00239 #endif /* APR_LDAP_OPTION_H */ 00240