contrib/apr-util/include/apr_ldap_init.h

   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_init.h
  19  * @brief  APR-UTIL LDAP ldap_init() functions
  20  */
  21 #ifndef APR_LDAP_INIT_H
  22 #define APR_LDAP_INIT_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
  34 extern "C" {
  35 #endif /* __cplusplus */
  36
  37
  38 /**
  39  * Macro to detect security related return values.
  40  */
  41 #if defined(LDAP_INSUFFICIENT_ACCESS)
  42 #define APU_LDAP_INSUFFICIENT_ACCESS LDAP_INSUFFICIENT_ACCESS
  43 #elif defined(LDAP_INSUFFICIENT_RIGHTS)
  44 #define APU_LDAP_INSUFFICIENT_ACCESS LDAP_INSUFFICIENT_RIGHTS
  45 #elif defined(APR_HAS_MICROSOFT_LDAPSDK)
  46 /* The macros above fail to contemplate that LDAP_RETCODE values
  47  * may be represented by an enum.  autoconf tests would be much
  48  * more robust.
  49  */
  50 #define APU_LDAP_INSUFFICIENT_ACCESS LDAP_INSUFFICIENT_RIGHTS
  51 #else
  52 #error The security return codes must be added to support this LDAP toolkit.
  53 #endif
  54
  55 #if defined(LDAP_SECURITY_ERROR)
  56 #define APU_LDAP_SECURITY_ERROR LDAP_SECURITY_ERROR
  57 #else
  58 #define APU_LDAP_SECURITY_ERROR(n)      \
  59     (LDAP_INAPPROPRIATE_AUTH == n) ? 1 \
  60     : (LDAP_INVALID_CREDENTIALS == n) ? 1 \
  61     : (APU_LDAP_INSUFFICIENT_ACCESS == n) ? 1 \
  62     : 0
  63 #endif
  64
  65
  66 /**
  67  * APR LDAP SSL Initialise function
  68  *
  69  * This function initialises SSL on the underlying LDAP toolkit
  70  * if this is necessary.
  71  *
  72  * If a CA certificate is provided, this is set, however the setting
  73  * of certificates via this method has been deprecated and will be removed in
  74  * APR v2.0.
  75  *
  76  * The apr_ldap_set_option() function with the APR_LDAP_OPT_TLS_CERT option
  77  * should be used instead to set certificates.
  78  *
  79  * If SSL support is not available on this platform, or a problem
  80  * was encountered while trying to set the certificate, the function
  81  * will return APR_EGENERAL. Further LDAP specific error information
  82  * can be found in result_err.
  83  * @param pool The pool to use
  84  * @param cert_auth_file The name of the certificate to use, can be NULL
  85  * @param cert_file_type The type of certificate specified. See the
  86  * apr_ldap_set_option() APR_LDAP_OPT_TLS_CERT option for details.
  87  * @param result_err The returned result
  88  */
  89 APU_DECLARE_LDAP(int) apr_ldap_ssl_init(apr_pool_t *pool,
  90                                         const char *cert_auth_file,
  91                                         int cert_file_type,
  92                                         apr_ldap_err_t **result_err);
  93
  94 /**
  95  * APR LDAP SSL De-Initialise function
  96  *
  97  * This function tears down any SSL certificate setup previously
  98  * set using apr_ldap_ssl_init(). It should be called to clean
  99  * up if a graceful restart of a service is attempted.
 100  * @todo currently we do not check whether apr_ldap_ssl_init()
 101  * has been called first - we probably should.
 102  */
 103 APU_DECLARE_LDAP(int) apr_ldap_ssl_deinit(void);
 104
 105 /**
 106  * APR LDAP initialise function
 107  *
 108  * This function is responsible for initialising an LDAP
 109  * connection in a toolkit independant way. It does the
 110  * job of ldap_init() from the C api.
 111  *
 112  * It handles both the SSL and non-SSL case, and attempts
 113  * to hide the complexity setup from the user. This function
 114  * assumes that any certificate setup necessary has already
 115  * been done.
 116  *
 117  * If SSL or STARTTLS needs to be enabled, and the underlying
 118  * toolkit supports it, the following values are accepted for
 119  * secure:
 120  *
 121  * APR_LDAP_NONE: No encryption
 122  * APR_LDAP_SSL: SSL encryption (ldaps://)
 123  * APR_LDAP_STARTTLS: Force STARTTLS on ldap://
 124  * @remark The Novell toolkit is only able to set the SSL mode via this
 125  * function. To work around this limitation, set the SSL mode here if no
 126  * per connection client certificates are present, otherwise set secure
 127  * APR_LDAP_NONE here, then set the per connection client certificates,
 128  * followed by setting the SSL mode via apr_ldap_set_option(). As Novell
 129  * does not support per connection client certificates, this problem is
 130  * worked around while still being compatible with other LDAP toolkits.
 131  * @param pool The pool to use
 132  * @param ldap The LDAP handle
 133  * @param hostname The name of the host to connect to. This can be either a
 134  * DNS name, or an IP address.
 135  * @param portno The port to connect to
 136  * @param secure The security mode to set
 137  * @param result_err The returned result
 138  */
 139 APU_DECLARE_LDAP(int) apr_ldap_init(apr_pool_t *pool,
 140                                     LDAP **ldap,
 141                                     const char *hostname,
 142                                     int portno,
 143                                     int secure,
 144                                     apr_ldap_err_t **result_err);
 145
 146 /**
 147  * APR LDAP info function
 148  *
 149  * This function returns a string describing the LDAP toolkit
 150  * currently in use. The string is placed inside result_err->reason.
 151  * @param pool The pool to use
 152  * @param result_err The returned result
 153  */
 154 APU_DECLARE_LDAP(int) apr_ldap_info(apr_pool_t *pool,
 155                                     apr_ldap_err_t **result_err);
 156
 157 #ifdef __cplusplus
 158 }
 159 #endif
 160
 161 #endif /* APR_HAS_LDAP */
 162
 163 /** @} */
 164
 165 #endif /* APR_LDAP_URL_H */