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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
18 * @file apr_ldap_option.h
19 * @brief APR-UTIL LDAP ldap_*_option() functions
21 #ifndef APR_LDAP_OPTION_H
22 #define APR_LDAP_OPTION_H
25 * @addtogroup APR_Util_LDAP
35 #endif /* __cplusplus */
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()
44 * Set SSL mode to one of APR_LDAP_NONE, APR_LDAP_SSL, APR_LDAP_STARTTLS
45 * or APR_LDAP_STOPTLS.
47 #define APR_LDAP_OPT_TLS 0x6fff
49 * Set zero or more CA certificates, client certificates or private
50 * keys globally, or per connection (where supported).
52 #define APR_LDAP_OPT_TLS_CERT 0x6ffe
54 * Set the LDAP library to no verify the server certificate. This means
55 * all servers are considered trusted.
57 #define APR_LDAP_OPT_VERIFY_CERT 0x6ffd
59 * Set the LDAP library to indicate if referrals should be chased during
62 #define APR_LDAP_OPT_REFERRALS 0x6ffc
64 * Set the LDAP library to indicate a maximum number of referral hops to
65 * chase before giving up on the search.
67 #define APR_LDAP_OPT_REFHOPLIMIT 0x6ffb
70 * Structures for the apr_set_option() cases
74 * APR_LDAP_OPT_TLS_CERT
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 *).
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
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 ""
94 * Needs CA certificates and client certificates set at system initialisation
95 * time. Three types are supported: APR_LDAP_CA*, APR_LDAP_CERT* and
98 * Certificates cannot be specified per connection.
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 (
107 * type can be LDAPSSL_CERT_FILETYPE_B64 or LDAPSSL_CERT_FILETYPE_DER
108 * ldapssl_set_client_private_key(clientPrivateKey,
109 * clientPrivateKeyEncoding,
110 * clientPrivateKeyPassword);
113 * Needs one or more CA certificates to be set at system initialisation time
114 * with a type of APR_LDAP_CA*.
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*.
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
152 #define APR_LDAP_CA_TYPE_CACERTDIR_BASE64 15
156 * Certificate structure.
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
165 typedef struct apr_ldap_opt_tls_cert_t apr_ldap_opt_tls_cert_t;
166 struct apr_ldap_opt_tls_cert_t {
169 const char *password;
175 * This sets the SSL level on the LDAP handle.
178 * Supports SSL, but not STARTTLS
179 * SSL is enabled by calling ldapssl_install_routines().
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
186 * STARTTLS is enabled by calling ldapssl_start_tls_s() after calling
187 * ldapssl_install_routines() (check this).
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.
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
206 * APR LDAP get option function
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
217 APU_DECLARE_LDAP(int) apr_ldap_get_option(apr_pool_t *pool,
221 apr_ldap_err_t **result_err);
224 * APR LDAP set option function
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.
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
239 APU_DECLARE_LDAP(int) apr_ldap_set_option(apr_pool_t *pool,
243 apr_ldap_err_t **result_err);
249 #endif /* APR_HAS_LDAP */
253 #endif /* APR_LDAP_OPTION_H */