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 * @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 * APR LDAP SSL Initialise function 00040 * 00041 * This function initialises SSL on the underlying LDAP toolkit 00042 * if this is necessary. 00043 * 00044 * If a CA certificate is provided, this is set, however the setting 00045 * of certificates via this method has been deprecated and will be removed in 00046 * APR v2.0. 00047 * 00048 * The apr_ldap_set_option() function with the APR_LDAP_OPT_TLS_CERT option 00049 * should be used instead to set certificates. 00050 * 00051 * If SSL support is not available on this platform, or a problem 00052 * was encountered while trying to set the certificate, the function 00053 * will return APR_EGENERAL. Further LDAP specific error information 00054 * can be found in result_err. 00055 * @param pool The pool to use 00056 * @param cert_auth_file The name of the certificate to use, can be NULL 00057 * @param cert_file_type The type of certificate specified. See the 00058 * apr_ldap_set_option() APR_LDAP_OPT_TLS_CERT option for details. 00059 * @param result_err The returned result 00060 */ 00061 APU_DECLARE(int) apr_ldap_ssl_init(apr_pool_t *pool, 00062 const char *cert_auth_file, 00063 int cert_file_type, 00064 apr_ldap_err_t **result_err); 00065 00066 /** 00067 * APR LDAP SSL De-Initialise function 00068 * 00069 * This function tears down any SSL certificate setup previously 00070 * set using apr_ldap_ssl_init(). It should be called to clean 00071 * up if a graceful restart of a service is attempted. 00072 * @todo currently we do not check whether apr_ldap_ssl_init() 00073 * has been called first - we probably should. 00074 */ 00075 APU_DECLARE(int) apr_ldap_ssl_deinit(void); 00076 00077 /** 00078 * APR LDAP initialise function 00079 * 00080 * This function is responsible for initialising an LDAP 00081 * connection in a toolkit independant way. It does the 00082 * job of ldap_init() from the C api. 00083 * 00084 * It handles both the SSL and non-SSL case, and attempts 00085 * to hide the complexity setup from the user. This function 00086 * assumes that any certificate setup necessary has already 00087 * been done. 00088 * 00089 * If SSL or STARTTLS needs to be enabled, and the underlying 00090 * toolkit supports it, the following values are accepted for 00091 * secure: 00092 * 00093 * APR_LDAP_NONE: No encryption 00094 * APR_LDAP_SSL: SSL encryption (ldaps://) 00095 * APR_LDAP_STARTTLS: Force STARTTLS on ldap:// 00096 * @remark The Novell toolkit is only able to set the SSL mode via this 00097 * function. To work around this limitation, set the SSL mode here if no 00098 * per connection client certificates are present, otherwise set secure 00099 * APR_LDAP_NONE here, then set the per connection client certificates, 00100 * followed by setting the SSL mode via apr_ldap_set_option(). As Novell 00101 * does not support per connection client certificates, this problem is 00102 * worked around while still being compatible with other LDAP toolkits. 00103 * @param pool The pool to use 00104 * @param ldap The LDAP handle 00105 * @param hostname The name of the host to connect to. This can be either a 00106 * DNS name, or an IP address. 00107 * @param portno The port to connect to 00108 * @param secure The security mode to set 00109 * @param result_err The returned result 00110 */ 00111 APU_DECLARE(int) apr_ldap_init(apr_pool_t *pool, 00112 LDAP **ldap, 00113 const char *hostname, 00114 int portno, 00115 int secure, 00116 apr_ldap_err_t **result_err); 00117 00118 /** 00119 * APR LDAP info function 00120 * 00121 * This function returns a string describing the LDAP toolkit 00122 * currently in use. The string is placed inside result_err->reason. 00123 * @param pool The pool to use 00124 * @param result_err The returned result 00125 */ 00126 APU_DECLARE(int) apr_ldap_info(apr_pool_t *pool, 00127 apr_ldap_err_t **result_err); 00128 00129 #ifdef __cplusplus 00130 } 00131 #endif 00132 00133 #endif /* APR_HAS_LDAP */ 00134 00135 /** @} */ 00136 00137 #endif /* APR_LDAP_URL_H */