apr_ldap_option.h

Go to the documentation of this file.
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 /**
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 

Generated on Sat Jan 19 01:49:04 2008 for Apache Portable Runtime by  doxygen 1.5.4