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 34extern "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 */ 165typedef struct apr_ldap_opt_tls_cert_t apr_ldap_opt_tls_cert_t; 166struct 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 */ 217APU_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 */ 239APU_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 255