Apache Portable Runtime

apr_ldap_init.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_init.h
00019  * @brief  APR-UTIL LDAP ldap_init() functions
00020  */
00021 #ifndef APR_LDAP_INIT_H
00022 #define APR_LDAP_INIT_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 /**
00039  * Macro to detect security related return values.
00040  */
00041 #if defined(LDAP_INSUFFICIENT_ACCESS)
00042 #define APU_LDAP_INSUFFICIENT_ACCESS LDAP_INSUFFICIENT_ACCESS
00043 #elif defined(LDAP_INSUFFICIENT_RIGHTS)
00044 #define APU_LDAP_INSUFFICIENT_ACCESS LDAP_INSUFFICIENT_RIGHTS
00045 #elif defined(APR_HAS_MICROSOFT_LDAPSDK)
00046 /* The macros above fail to contemplate that LDAP_RETCODE values
00047  * may be represented by an enum.  autoconf tests would be much
00048  * more robust.
00049  */
00050 #define APU_LDAP_INSUFFICIENT_ACCESS LDAP_INSUFFICIENT_RIGHTS
00051 #else
00052 #error The security return codes must be added to support this LDAP toolkit.
00053 #endif
00054 
00055 #if defined(LDAP_SECURITY_ERROR)
00056 #define APU_LDAP_SECURITY_ERROR LDAP_SECURITY_ERROR
00057 #else
00058 #define APU_LDAP_SECURITY_ERROR(n)      \
00059     (LDAP_INAPPROPRIATE_AUTH == n) ? 1 \
00060     : (LDAP_INVALID_CREDENTIALS == n) ? 1 \
00061     : (APU_LDAP_INSUFFICIENT_ACCESS == n) ? 1 \
00062     : 0
00063 #endif
00064 
00065 
00066 /**
00067  * APR LDAP SSL Initialise function
00068  *
00069  * This function initialises SSL on the underlying LDAP toolkit
00070  * if this is necessary.
00071  *
00072  * If a CA certificate is provided, this is set, however the setting
00073  * of certificates via this method has been deprecated and will be removed in
00074  * APR v2.0.
00075  *
00076  * The apr_ldap_set_option() function with the APR_LDAP_OPT_TLS_CERT option
00077  * should be used instead to set certificates.
00078  *
00079  * If SSL support is not available on this platform, or a problem
00080  * was encountered while trying to set the certificate, the function
00081  * will return APR_EGENERAL. Further LDAP specific error information
00082  * can be found in result_err.
00083  * @param pool The pool to use
00084  * @param cert_auth_file The name of the certificate to use, can be NULL
00085  * @param cert_file_type The type of certificate specified. See the
00086  * apr_ldap_set_option() APR_LDAP_OPT_TLS_CERT option for details.
00087  * @param result_err The returned result
00088  */
00089 APU_DECLARE_LDAP(int) apr_ldap_ssl_init(apr_pool_t *pool,
00090                                         const char *cert_auth_file,
00091                                         int cert_file_type,
00092                                         apr_ldap_err_t **result_err);
00093 
00094 /**
00095  * APR LDAP SSL De-Initialise function
00096  *
00097  * This function tears down any SSL certificate setup previously
00098  * set using apr_ldap_ssl_init(). It should be called to clean
00099  * up if a graceful restart of a service is attempted.
00100  * @todo currently we do not check whether apr_ldap_ssl_init()
00101  * has been called first - we probably should.
00102  */
00103 APU_DECLARE_LDAP(int) apr_ldap_ssl_deinit(void);
00104 
00105 /**
00106  * APR LDAP initialise function
00107  *
00108  * This function is responsible for initialising an LDAP
00109  * connection in a toolkit independant way. It does the
00110  * job of ldap_init() from the C api.
00111  *
00112  * It handles both the SSL and non-SSL case, and attempts
00113  * to hide the complexity setup from the user. This function
00114  * assumes that any certificate setup necessary has already
00115  * been done.
00116  *
00117  * If SSL or STARTTLS needs to be enabled, and the underlying
00118  * toolkit supports it, the following values are accepted for
00119  * secure:
00120  *
00121  * APR_LDAP_NONE: No encryption
00122  * APR_LDAP_SSL: SSL encryption (ldaps://)
00123  * APR_LDAP_STARTTLS: Force STARTTLS on ldap://
00124  * @remark The Novell toolkit is only able to set the SSL mode via this
00125  * function. To work around this limitation, set the SSL mode here if no
00126  * per connection client certificates are present, otherwise set secure
00127  * APR_LDAP_NONE here, then set the per connection client certificates,
00128  * followed by setting the SSL mode via apr_ldap_set_option(). As Novell
00129  * does not support per connection client certificates, this problem is
00130  * worked around while still being compatible with other LDAP toolkits.
00131  * @param pool The pool to use
00132  * @param ldap The LDAP handle
00133  * @param hostname The name of the host to connect to. This can be either a
00134  * DNS name, or an IP address.
00135  * @param portno The port to connect to
00136  * @param secure The security mode to set
00137  * @param result_err The returned result
00138  */
00139 APU_DECLARE_LDAP(int) apr_ldap_init(apr_pool_t *pool,
00140                                     LDAP **ldap,
00141                                     const char *hostname,
00142                                     int portno,
00143                                     int secure,
00144                                     apr_ldap_err_t **result_err);
00145 
00146 /**
00147  * APR LDAP info function
00148  *
00149  * This function returns a string describing the LDAP toolkit
00150  * currently in use. The string is placed inside result_err->reason.
00151  * @param pool The pool to use
00152  * @param result_err The returned result
00153  */
00154 APU_DECLARE_LDAP(int) apr_ldap_info(apr_pool_t *pool,
00155                                     apr_ldap_err_t **result_err);
00156 
00157 #ifdef __cplusplus
00158 }
00159 #endif
00160 
00161 #endif /* APR_HAS_LDAP */
00162 
00163 /** @} */
00164 
00165 #endif /* APR_LDAP_URL_H */
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Defines