Apache Portable Runtime
|
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