← Back to branch summary

~hexmode/+junk/main

« back to all changes in this revision

Viewing changes to install-files/bin/apache/apache2.2.6/include/util_ldap.h

  • Committer: Mark A. Hershberger
  • Date: 2008-01-05 19:38:56 UTC
  • Revision ID: hershberger@spawn-xp-20080105193856-6rnzgwa4nehue3qj
initial commit

Show diffs side-by-side

added added

removed removed

Lines of Context:
install-files/bin/apache/apache2.2.6/include/util_ldap.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 util_ldap.h
 
19
 * @brief Apache LDAP library
 
20
 */
 
21
 
 
22
#ifndef UTIL_LDAP_H
 
23
#define UTIL_LDAP_H
 
24
 
 
25
/* APR header files */
 
26
#include "apr.h"
 
27
#include "apr_thread_mutex.h"
 
28
#include "apr_thread_rwlock.h"
 
29
#include "apr_tables.h"
 
30
#include "apr_time.h"
 
31
#include "apr_ldap.h"
 
32
 
 
33
#if APR_HAS_SHARED_MEMORY
 
34
#include "apr_rmm.h"
 
35
#include "apr_shm.h"
 
36
#endif
 
37
 
 
38
/* this whole thing disappears if LDAP is not enabled */
 
39
#if APR_HAS_LDAP
 
40
 
 
41
/* Apache header files */
 
42
#include "ap_config.h"
 
43
#include "httpd.h"
 
44
#include "http_config.h"
 
45
#include "http_core.h"
 
46
#include "http_log.h"
 
47
#include "http_protocol.h"
 
48
#include "http_request.h"
 
49
#include "apr_optional.h"
 
50
 
 
51
/* Create a set of LDAP_DECLARE macros with appropriate export 
 
52
 * and import tags for the platform
 
53
 */
 
54
#if !defined(WIN32)
 
55
#define LDAP_DECLARE(type)            type
 
56
#define LDAP_DECLARE_NONSTD(type)     type
 
57
#define LDAP_DECLARE_DATA
 
58
#elif defined(LDAP_DECLARE_STATIC)
 
59
#define LDAP_DECLARE(type)            type __stdcall
 
60
#define LDAP_DECLARE_NONSTD(type)     type
 
61
#define LDAP_DECLARE_DATA
 
62
#elif defined(LDAP_DECLARE_EXPORT)
 
63
#define LDAP_DECLARE(type)            __declspec(dllexport) type __stdcall
 
64
#define LDAP_DECLARE_NONSTD(type)     __declspec(dllexport) type
 
65
#define LDAP_DECLARE_DATA             __declspec(dllexport)
 
66
#else
 
67
#define LDAP_DECLARE(type)            __declspec(dllimport) type __stdcall
 
68
#define LDAP_DECLARE_NONSTD(type)     __declspec(dllimport) type
 
69
#define LDAP_DECLARE_DATA             __declspec(dllimport)
 
70
#endif
 
71
 
 
72
#ifdef __cplusplus
 
73
extern "C" {
 
74
#endif
 
75
 
 
76
/*
 
77
 * LDAP Connections
 
78
 */
 
79
 
 
80
/* Values that the deref member can have */
 
81
typedef enum {
 
82
    never=LDAP_DEREF_NEVER, 
 
83
    searching=LDAP_DEREF_SEARCHING, 
 
84
    finding=LDAP_DEREF_FINDING, 
 
85
    always=LDAP_DEREF_ALWAYS
 
86
} deref_options;
 
87
 
 
88
/* Structure representing an LDAP connection */
 
89
typedef struct util_ldap_connection_t {
 
90
    LDAP *ldap;
 
91
    apr_pool_t *pool;                   /* Pool from which this connection is created */
 
92
#if APR_HAS_THREADS
 
93
    apr_thread_mutex_t *lock;           /* Lock to indicate this connection is in use */
 
94
#endif
 
95
    int bound;                          /* Flag to indicate whether this connection is bound yet */
 
96
 
 
97
    const char *host;                   /* Name of the LDAP server (or space separated list) */
 
98
    int port;                           /* Port of the LDAP server */
 
99
    deref_options deref;                /* how to handle alias dereferening */
 
100
 
 
101
    const char *binddn;                 /* DN to bind to server (can be NULL) */
 
102
    const char *bindpw;                 /* Password to bind to server (can be NULL) */
 
103
 
 
104
    int secure;                         /* SSL/TLS mode of the connection */
 
105
    apr_array_header_t *client_certs;   /* Client certificates on this connection */
 
106
 
 
107
    const char *reason;                 /* Reason for an error failure */
 
108
 
 
109
    struct util_ldap_connection_t *next;
 
110
} util_ldap_connection_t;
 
111
 
 
112
/* LDAP cache state information */ 
 
113
typedef struct util_ldap_state_t {
 
114
    apr_pool_t *pool;           /* pool from which this state is allocated */
 
115
#if APR_HAS_THREADS
 
116
    apr_thread_mutex_t *mutex;          /* mutex lock for the connection list */
 
117
#endif
 
118
    apr_global_mutex_t *util_ldap_cache_lock;
 
119
 
 
120
    apr_size_t cache_bytes;     /* Size (in bytes) of shared memory cache */
 
121
    char *cache_file;           /* filename for shm */
 
122
    long search_cache_ttl;      /* TTL for search cache */
 
123
    long search_cache_size;     /* Size (in entries) of search cache */
 
124
    long compare_cache_ttl;     /* TTL for compare cache */
 
125
    long compare_cache_size;    /* Size (in entries) of compare cache */
 
126
 
 
127
    struct util_ldap_connection_t *connections;
 
128
    int   ssl_supported;
 
129
    apr_array_header_t *global_certs;  /* Global CA certificates */
 
130
    apr_array_header_t *client_certs;  /* Client certificates */
 
131
    int   secure;
 
132
    int   secure_set;
 
133
 
 
134
#if APR_HAS_SHARED_MEMORY
 
135
    apr_shm_t *cache_shm;
 
136
    apr_rmm_t *cache_rmm;
 
137
#endif
 
138
 
 
139
    /* cache ald */
 
140
    void *util_ldap_cache;
 
141
    char *lock_file;           /* filename for shm lock mutex */
 
142
    long  connectionTimeout;
 
143
    int   verify_svr_cert;
 
144
 
 
145
} util_ldap_state_t;
 
146
 
 
147
 
 
148
/**
 
149
 * Open a connection to an LDAP server
 
150
 * @param ldc A structure containing the expanded details of the server
 
151
 *            to connect to. The handle to the LDAP connection is returned
 
152
 *            as ldc->ldap.
 
153
 * @tip This function connects to the LDAP server and binds. It does not
 
154
 *      connect if already connected (ldc->ldap != NULL). Does not bind
 
155
 *      if already bound.
 
156
 * @return If successful LDAP_SUCCESS is returned.
 
157
 * @deffunc int util_ldap_connection_open(request_rec *r,
 
158
 *                                        util_ldap_connection_t *ldc)
 
159
 */
 
160
APR_DECLARE_OPTIONAL_FN(int,uldap_connection_open,(request_rec *r, 
 
161
                                            util_ldap_connection_t *ldc));
 
162
 
 
163
/**
 
164
 * Close a connection to an LDAP server
 
165
 * @param ldc A structure containing the expanded details of the server
 
166
 *            that was connected.
 
167
 * @tip This function unbinds from the LDAP server, and clears ldc->ldap.
 
168
 *      It is possible to rebind to this server again using the same ldc
 
169
 *      structure, using apr_ldap_open_connection().
 
170
 * @deffunc util_ldap_close_connection(util_ldap_connection_t *ldc)
 
171
 */
 
172
APR_DECLARE_OPTIONAL_FN(void,uldap_connection_close,(util_ldap_connection_t *ldc));
 
173
 
 
174
/**
 
175
 * Unbind a connection to an LDAP server
 
176
 * @param ldc A structure containing the expanded details of the server
 
177
 *            that was connected.
 
178
 * @tip This function unbinds the LDAP connection, and disconnects from
 
179
 *      the server. It is used during error conditions, to bring the LDAP
 
180
 *      connection back to a known state.
 
181
 * @deffunc apr_status_t util_ldap_connection_unbind(util_ldap_connection_t *ldc)
 
182
 */
 
183
APR_DECLARE_OPTIONAL_FN(apr_status_t,uldap_connection_unbind,(void *param));
 
184
 
 
185
/**
 
186
 * Cleanup a connection to an LDAP server
 
187
 * @param ldc A structure containing the expanded details of the server
 
188
 *            that was connected.
 
189
 * @tip This function is registered with the pool cleanup to close down the
 
190
 *      LDAP connections when the server is finished with them.
 
191
 * @deffunc apr_status_t util_ldap_connection_cleanup(util_ldap_connection_t *ldc)
 
192
 */
 
193
APR_DECLARE_OPTIONAL_FN(apr_status_t,uldap_connection_cleanup,(void *param));
 
194
 
 
195
/**
 
196
 * Find a connection in a list of connections
 
197
 * @param r The request record
 
198
 * @param host The hostname to connect to (multiple hosts space separated)
 
199
 * @param port The port to connect to
 
200
 * @param binddn The DN to bind with
 
201
 * @param bindpw The password to bind with
 
202
 * @param deref The dereferencing behavior
 
203
 * @param secure use SSL on the connection 
 
204
 * @tip Once a connection is found and returned, a lock will be acquired to
 
205
 *      lock that particular connection, so that another thread does not try and
 
206
 *      use this connection while it is busy. Once you are finished with a connection,
 
207
 *      apr_ldap_connection_close() must be called to release this connection.
 
208
 * @deffunc util_ldap_connection_t *util_ldap_connection_find(request_rec *r, const char *host, int port,
 
209
 *                                                           const char *binddn, const char *bindpw, deref_options deref,
 
210
 *                                                           int netscapessl, int starttls)
 
211
 */
 
212
APR_DECLARE_OPTIONAL_FN(util_ldap_connection_t *,uldap_connection_find,(request_rec *r, const char *host, int port,
 
213
                                                  const char *binddn, const char *bindpw, deref_options deref,
 
214
                                                  int secure));
 
215
 
 
216
/**
 
217
 * Compare two DNs for sameness
 
218
 * @param r The request record
 
219
 * @param ldc The LDAP connection being used.
 
220
 * @param url The URL of the LDAP connection - used for deciding which cache to use.
 
221
 * @param dn The first DN to compare.
 
222
 * @param reqdn The DN to compare the first DN to.
 
223
 * @param compare_dn_on_server Flag to determine whether the DNs should be checked using
 
224
 *                             LDAP calls or with a direct string comparision. A direct
 
225
 *                             string comparison is faster, but not as accurate - false
 
226
 *                             negative comparisons are possible.
 
227
 * @tip Two DNs can be equal and still fail a string comparison. Eg "dc=example,dc=com"
 
228
 *      and "dc=example, dc=com". Use the compare_dn_on_server unless there are serious
 
229
 *      performance issues.
 
230
 * @deffunc int util_ldap_cache_comparedn(request_rec *r, util_ldap_connection_t *ldc,
 
231
 *                                        const char *url, const char *dn, const char *reqdn,
 
232
 *                                        int compare_dn_on_server)
 
233
 */
 
234
APR_DECLARE_OPTIONAL_FN(int,uldap_cache_comparedn,(request_rec *r, util_ldap_connection_t *ldc, 
 
235
                              const char *url, const char *dn, const char *reqdn, 
 
236
                              int compare_dn_on_server));
 
237
 
 
238
/**
 
239
 * A generic LDAP compare function
 
240
 * @param r The request record
 
241
 * @param ldc The LDAP connection being used.
 
242
 * @param url The URL of the LDAP connection - used for deciding which cache to use.
 
243
 * @param dn The DN of the object in which we do the compare.
 
244
 * @param attrib The attribute within the object we are comparing for.
 
245
 * @param value The value of the attribute we are trying to compare for. 
 
246
 * @tip Use this function to determine whether an attribute/value pair exists within an
 
247
 *      object. Typically this would be used to determine LDAP group membership.
 
248
 * @deffunc int util_ldap_cache_compare(request_rec *r, util_ldap_connection_t *ldc,
 
249
 *                                      const char *url, const char *dn, const char *attrib, const char *value)
 
250
 */
 
251
APR_DECLARE_OPTIONAL_FN(int,uldap_cache_compare,(request_rec *r, util_ldap_connection_t *ldc,
 
252
                            const char *url, const char *dn, const char *attrib, const char *value));
 
253
 
 
254
/**
 
255
 * Checks a username/password combination by binding to the LDAP server
 
256
 * @param r The request record
 
257
 * @param ldc The LDAP connection being used.
 
258
 * @param url The URL of the LDAP connection - used for deciding which cache to use.
 
259
 * @param basedn The Base DN to search for the user in.
 
260
 * @param scope LDAP scope of the search.
 
261
 * @param attrs LDAP attributes to return in search.
 
262
 * @param filter The user to search for in the form of an LDAP filter. This filter must return
 
263
 *               exactly one user for the check to be successful.
 
264
 * @param bindpw The user password to bind as.
 
265
 * @param binddn The DN of the user will be returned in this variable.
 
266
 * @param retvals The values corresponding to the attributes requested in the attrs array.
 
267
 * @tip The filter supplied will be searched for. If a single entry is returned, an attempt
 
268
 *      is made to bind as that user. If this bind succeeds, the user is not validated.
 
269
 * @deffunc int util_ldap_cache_checkuserid(request_rec *r, util_ldap_connection_t *ldc,
 
270
 *                                          char *url, const char *basedn, int scope, char **attrs,
 
271
 *                                          char *filter, char *bindpw, char **binddn, char ***retvals)
 
272
 */
 
273
APR_DECLARE_OPTIONAL_FN(int,uldap_cache_checkuserid,(request_rec *r, util_ldap_connection_t *ldc,
 
274
                              const char *url, const char *basedn, int scope, char **attrs,
 
275
                              const char *filter, const char *bindpw, const char **binddn, const char ***retvals));
 
276
 
 
277
/**
 
278
 * Searches for a specified user object in an LDAP directory
 
279
 * @param r The request record
 
280
 * @param ldc The LDAP connection being used.
 
281
 * @param url The URL of the LDAP connection - used for deciding which cache to use.
 
282
 * @param basedn The Base DN to search for the user in.
 
283
 * @param scope LDAP scope of the search.
 
284
 * @param attrs LDAP attributes to return in search.
 
285
 * @param filter The user to search for in the form of an LDAP filter. This filter must return
 
286
 *               exactly one user for the check to be successful.
 
287
 * @param binddn The DN of the user will be returned in this variable.
 
288
 * @param retvals The values corresponding to the attributes requested in the attrs array.
 
289
 * @tip The filter supplied will be searched for. If a single entry is returned, an attempt
 
290
 *      is made to bind as that user. If this bind succeeds, the user is not validated.
 
291
 * @deffunc int util_ldap_cache_getuserdn(request_rec *r, util_ldap_connection_t *ldc,
 
292
 *                                          char *url, const char *basedn, int scope, char **attrs,
 
293
 *                                          char *filter, char **binddn, char ***retvals)
 
294
 */
 
295
APR_DECLARE_OPTIONAL_FN(int,uldap_cache_getuserdn,(request_rec *r, util_ldap_connection_t *ldc,
 
296
                              const char *url, const char *basedn, int scope, char **attrs,
 
297
                              const char *filter, const char **binddn, const char ***retvals));
 
298
 
 
299
/**
 
300
 * Checks if SSL support is available in mod_ldap
 
301
 * @deffunc int util_ldap_ssl_supported(request_rec *r)
 
302
 */
 
303
APR_DECLARE_OPTIONAL_FN(int,uldap_ssl_supported,(request_rec *r));
 
304
 
 
305
/* from apr_ldap_cache.c */
 
306
 
 
307
/**
 
308
 * Init the LDAP cache
 
309
 * @param pool The pool to use to initialise the cache
 
310
 * @param reqsize The size of the shared memory segement to request. A size
 
311
 *                of zero requests the max size possible from
 
312
 *                apr_shmem_init()
 
313
 * @deffunc void util_ldap_cache_init(apr_pool_t *p, util_ldap_state_t *st)
 
314
 * @return The status code returned is the status code of the
 
315
 *         apr_smmem_init() call. Regardless of the status, the cache
 
316
 *         will be set up at least for in-process or in-thread operation.
 
317
 */
 
318
apr_status_t util_ldap_cache_init(apr_pool_t *pool, util_ldap_state_t *st);
 
319
 
 
320
/* from apr_ldap_cache_mgr.c */
 
321
 
 
322
/**
 
323
 * Display formatted stats for cache
 
324
 * @param The pool to allocate the returned string from
 
325
 * @tip This function returns a string allocated from the provided pool that describes
 
326
 *      various stats about the cache.
 
327
 * @deffunc char *util_ald_cache_display(apr_pool_t *pool, util_ldap_state_t *st)
 
328
 */
 
329
char *util_ald_cache_display(request_rec *r, util_ldap_state_t *st);
 
330
#ifdef __cplusplus
 
331
}
 
332
#endif
 
333
#endif /* APR_HAS_LDAP */
 
334
#endif /* UTIL_LDAP_H */