|
Packit |
6bd9ab |
/*
|
|
Packit |
6bd9ab |
myldap.h - simple interface to do LDAP requests
|
|
Packit |
6bd9ab |
This file is part of the nss-pam-ldapd library.
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
Copyright (C) 2007-2017 Arthur de Jong
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
This library is free software; you can redistribute it and/or
|
|
Packit |
6bd9ab |
modify it under the terms of the GNU Lesser General Public
|
|
Packit |
6bd9ab |
License as published by the Free Software Foundation; either
|
|
Packit |
6bd9ab |
version 2.1 of the License, or (at your option) any later version.
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
This library is distributed in the hope that it will be useful,
|
|
Packit |
6bd9ab |
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
Packit |
6bd9ab |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
Packit |
6bd9ab |
Lesser General Public License for more details.
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
You should have received a copy of the GNU Lesser General Public
|
|
Packit |
6bd9ab |
License along with this library; if not, write to the Free Software
|
|
Packit |
6bd9ab |
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
|
|
Packit |
6bd9ab |
02110-1301 USA
|
|
Packit |
6bd9ab |
*/
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
/*
|
|
Packit |
6bd9ab |
This file describes the API of the myldap module which takes the complexity
|
|
Packit |
6bd9ab |
out of using the OpenLDAP library. Memory management, paging, reconnect
|
|
Packit |
6bd9ab |
logic, idle timeout of connections, etc is taken care of by the module.
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
Use of this module is very straightforeward. You first have to create a
|
|
Packit |
6bd9ab |
session (with myldap_create_session()), with this session you can start
|
|
Packit |
6bd9ab |
searches (with myldap_search()), from a search you can get entries (with
|
|
Packit |
6bd9ab |
myldap_get_entry()) from the LDAP database and from these entries you can
|
|
Packit |
6bd9ab |
get attribute values (with myldap_get_values()).
|
|
Packit |
6bd9ab |
*/
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
#ifndef NSLCD__MYLDAP_H
|
|
Packit |
6bd9ab |
#define NSLCD__MYLDAP_H
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
/* for size_t */
|
|
Packit |
6bd9ab |
#include <stdlib.h>
|
|
Packit |
6bd9ab |
/* for LDAP_SCOPE_* */
|
|
Packit |
6bd9ab |
#include <lber.h>
|
|
Packit |
6bd9ab |
#include <ldap.h>
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
#include "compat/attrs.h"
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
#ifndef LDAP_SCOPE_DEFAULT
|
|
Packit |
6bd9ab |
#define LDAP_SCOPE_DEFAULT LDAP_SCOPE_SUBTREE
|
|
Packit |
6bd9ab |
#endif /* not LDAP_SCOPE_DEFAULT */
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
/* This a a generic session handle. */
|
|
Packit |
6bd9ab |
typedef struct ldap_session MYLDAP_SESSION;
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
/* Note that this session handle may be used within one thread only. No
|
|
Packit |
6bd9ab |
locking is performed to prevent concurrent modifications. Most LDAP
|
|
Packit |
6bd9ab |
libraries also are not thread-safe in that a single connection may be
|
|
Packit |
6bd9ab |
shared by multiple threads. It seems however that OpenLDAP at least does
|
|
Packit |
6bd9ab |
not have any problems with an LDAP *ld per thread.
|
|
Packit |
6bd9ab |
http://www.openldap.org/lists/openldap-software/200606/msg00252.html */
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
/* A result set as returned by myldap_search(). */
|
|
Packit |
6bd9ab |
typedef struct myldap_search MYLDAP_SEARCH;
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
/* A single entry from the LDAP database as returned by myldap_get_entry(). */
|
|
Packit |
6bd9ab |
typedef struct myldap_entry MYLDAP_ENTRY;
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
/* Create a new session, this does not yet connect to the LDAP server. The
|
|
Packit |
6bd9ab |
connection to the server is made on-demand when a search is performed. This
|
|
Packit |
6bd9ab |
uses the configuration to find the URLs to attempt connections to. */
|
|
Packit |
6bd9ab |
MUST_USE MYLDAP_SESSION *myldap_create_session(void);
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
/* Perform a simple bind operation and return the ppolicy results.
|
|
Packit |
6bd9ab |
This function returns an LDAP status code while response is an NSLCD_PAM_*
|
|
Packit |
6bd9ab |
code with accompanying message. */
|
|
Packit |
6bd9ab |
MUST_USE int myldap_bind(MYLDAP_SESSION *session, const char *dn,
|
|
Packit |
6bd9ab |
const char *password,
|
|
Packit |
6bd9ab |
int *response, const char **message);
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
/* Closes all pending searches and deallocates any memory that is allocated
|
|
Packit |
6bd9ab |
with these searches. This does not close the session. */
|
|
Packit |
6bd9ab |
void myldap_session_cleanup(MYLDAP_SESSION *session);
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
/* This checks the timeout value of the session and closes the connection
|
|
Packit |
6bd9ab |
to the LDAP server if the timeout has expired and there are no pending
|
|
Packit |
6bd9ab |
searches. */
|
|
Packit |
6bd9ab |
void myldap_session_check(MYLDAP_SESSION *session);
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
/* Close the session and free all the resources allocated for the session.
|
|
Packit |
6bd9ab |
After a call to this function the referenced handle is invalid. */
|
|
Packit |
6bd9ab |
void myldap_session_close(MYLDAP_SESSION *session);
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
/* Mark all failing LDAP servers as needing quick retries. This ensures that the
|
|
Packit |
6bd9ab |
reconnect_sleeptime and reconnect_retrytime sleeping period is cut short. */
|
|
Packit |
6bd9ab |
void myldap_immediate_reconnect(void);
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
/* Do an LDAP search and return a reference to the results (returns NULL on
|
|
Packit |
6bd9ab |
error). This function uses paging, and does reconnects to the configured
|
|
Packit |
6bd9ab |
URLs transparently. The function returns an LDAP status code in the
|
|
Packit |
6bd9ab |
location pointed to by rcp if it is non-NULL. */
|
|
Packit |
6bd9ab |
MUST_USE MYLDAP_SEARCH *myldap_search(MYLDAP_SESSION *session,
|
|
Packit |
6bd9ab |
const char *base, int scope,
|
|
Packit |
6bd9ab |
const char *filter, const char **attrs,
|
|
Packit |
6bd9ab |
int *rcp);
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
/* Close the specified search. This frees all the memory that was allocated
|
|
Packit |
6bd9ab |
for the search and its results. */
|
|
Packit |
6bd9ab |
void myldap_search_close(MYLDAP_SEARCH *search);
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
/* Get an entry from the result set, going over all results (returns NULL if
|
|
Packit |
6bd9ab |
no more entries are available). Note that any memory allocated to return
|
|
Packit |
6bd9ab |
information about the previous entry (e.g. with myldap_get_values()) is
|
|
Packit |
6bd9ab |
freed with this call. The search is autoamtically closed when no more
|
|
Packit |
6bd9ab |
results are available. The function returns an LDAP status code in the
|
|
Packit |
6bd9ab |
location pointed to by rcp if it is non-NULL. */
|
|
Packit |
6bd9ab |
MUST_USE MYLDAP_ENTRY *myldap_get_entry(MYLDAP_SEARCH *search, int *rcp);
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
/* Get the DN from the entry. This function does not return NULL (on error
|
|
Packit |
6bd9ab |
"unknown" is returned). */
|
|
Packit |
6bd9ab |
MUST_USE const char *myldap_get_dn(MYLDAP_ENTRY *entry);
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
/* Just like myldap_get_dn() but copies the result into the buffer. */
|
|
Packit |
6bd9ab |
char *myldap_cpy_dn(MYLDAP_ENTRY *entry, char *buf, size_t buflen);
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
/* Get the attribute values from a certain entry as a NULL terminated list.
|
|
Packit |
6bd9ab |
May return NULL or an empty array. */
|
|
Packit |
6bd9ab |
MUST_USE const char **myldap_get_values(MYLDAP_ENTRY *entry, const char *attr);
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
/* Get the attribute values from a certain entry as a NULL terminated list.
|
|
Packit |
6bd9ab |
May return NULL or an empty array. */
|
|
Packit |
6bd9ab |
MUST_USE const char **myldap_get_values_len(MYLDAP_ENTRY *entry, const char *attr);
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
/* Checks to see if the entry has the specified object class. */
|
|
Packit |
6bd9ab |
MUST_USE int myldap_has_objectclass(MYLDAP_ENTRY *entry, const char *objectclass);
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
/* See if the entry has any deref controls attached to it and deref attr
|
|
Packit |
6bd9ab |
derefattr to get the getattr values. Will return two lists of attribute
|
|
Packit |
6bd9ab |
values. One list of deref'ed attribute values and one list of original
|
|
Packit |
6bd9ab |
attribute values that could not be deref'ed. */
|
|
Packit |
6bd9ab |
MUST_USE const char ***myldap_get_deref_values(MYLDAP_ENTRY *entry,
|
|
Packit |
6bd9ab |
const char *derefattr, const char *getattr);
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
/* Get the RDN's value: eg. if the DN was cn=lukeh, ou=People, dc=example,
|
|
Packit |
6bd9ab |
dc=com getrdnvalue(entry, cn) would return lukeh. If the attribute was not
|
|
Packit |
6bd9ab |
found in the DN or if some error occurs NULL is returned. This method may
|
|
Packit |
6bd9ab |
be used to get the "most authorative" value for an attribute. */
|
|
Packit |
6bd9ab |
MUST_USE const char *myldap_get_rdn_value(MYLDAP_ENTRY *entry, const char *attr);
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
/* Just like myldap_get_rdn_value() but use the supplied character sequence
|
|
Packit |
6bd9ab |
and copies the result into the buffer.
|
|
Packit |
6bd9ab |
Returns a pointer to the start of the string on success and NULL on
|
|
Packit |
6bd9ab |
failure. */
|
|
Packit |
6bd9ab |
MUST_USE const char *myldap_cpy_rdn_value(const char *dn, const char *attr,
|
|
Packit |
6bd9ab |
char *buf, size_t buflen);
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
/* Escapes characters in a string for use in a search filter. */
|
|
Packit |
6bd9ab |
MUST_USE int myldap_escape(const char *src, char *buffer, size_t buflen);
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
/* Set the debug level globally. Returns an LDAP status code. */
|
|
Packit |
6bd9ab |
int myldap_set_debuglevel(int level);
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
/* Perform an EXOP password modification call. Returns an LDAP status code. */
|
|
Packit |
6bd9ab |
int myldap_passwd(MYLDAP_SESSION *session,
|
|
Packit |
6bd9ab |
const char *userdn, const char *oldpassword,
|
|
Packit |
6bd9ab |
const char *newpasswd);
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
/* Perform an LDAP modification request. Returns an LDAP status code. */
|
|
Packit |
6bd9ab |
int myldap_modify(MYLDAP_SESSION *session, const char *dn, LDAPMod * mods[]);
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
/* Get an LDAP error message from the supplied rc and optionally any extra
|
|
Packit |
6bd9ab |
information in the connection. */
|
|
Packit |
6bd9ab |
int myldap_error_message(MYLDAP_SESSION *session, int rc,
|
|
Packit |
6bd9ab |
char *buffer, size_t buflen);
|
|
Packit |
6bd9ab |
|
|
Packit |
6bd9ab |
#endif /* not NSLCD__MYLDAP_H */
|