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