/* $OpenLDAP: pkg/ldap/servers/slapd/back-sql/back-sql.h,v 1.30.2.10 2007/01/02 21:44:07 kurt Exp $ *//* This work is part of OpenLDAP Software <http://www.openldap.org/>. * * Copyright 1999-2007 The OpenLDAP Foundation. * Portions Copyright 1999 Dmitry Kovalev. * Portions Copyright 2002 Pierangelo Mararati. * Portions Copyright 2004 Mark Adamson. * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted only as authorized by the OpenLDAP * Public License. * * A copy of this license is available in the file LICENSE in the * top-level directory of the distribution or, alternatively, at * <http://www.OpenLDAP.org/license.html>. *//* ACKNOWLEDGEMENTS: * This work was initially developed by Dmitry Kovalev for inclusion * by OpenLDAP Software.  Additional significant contributors include * Pierangelo Masarati and Mark Adamson. *//* * The following changes have been addressed: *	  * Enhancements: *   - re-styled code for better readability *   - upgraded backend API to reflect recent changes *   - LDAP schema is checked when loading SQL/LDAP mapping *   - AttributeDescription/ObjectClass pointers used for more efficient *     mapping lookup *   - bervals used where string length is required often *   - atomized write operations by committing at the end of each operation *     and defaulting connection closure to rollback *   - added LDAP access control to write operations *   - fully implemented modrdn (with rdn attrs change, deleteoldrdn, *     access check, parent/children check and more) *   - added parent access control, children control to delete operation *   - added structuralObjectClass operational attribute check and *     value return on search *   - added hasSubordinate operational attribute on demand *   - search limits are appropriately enforced *   - function backsql_strcat() has been made more efficient *   - concat function has been made configurable by means of a pattern *   - added config switches: *       - fail_if_no_mapping	write operations fail if there is no mapping *       - has_ldapinfo_dn_ru	overrides autodetect *       - concat_pattern	a string containing two '?' is used * 				(note that "?||?" should be more portable * 				than builtin function "CONCAT(?,?)") *       - strcast_func		cast of string constants in "SELECT DISTINCT *				statements (needed by PostgreSQL) *       - upper_needs_cast	cast the argument of upper when required * 				(basically when building dn substring queries) *   - added noop control *   - added values return filter control *   - hasSubordinate can be used in search filters (with limitations) *   - eliminated oc->name; use oc->oc->soc_cname instead *  * Todo: *   - add security checks for SQL statements that can be injected (?) *   - re-test with previously supported RDBMs *   - replace dn_ru and so with normalized dn (no need for upper() and so *     in dn match) *   - implement a backsql_normalize() function to replace the upper() *     conversion routines *   - note that subtree deletion, subtree renaming and so could be easily *     implemented (rollback and consistency checks are available :) *   - implement "lastmod" and other operational stuff (ldap_entries table ?) *   - check how to allow multiple operations with one statement, to remove *     BACKSQL_REALLOC_STMT from modify.c (a more recent unixODBC lib?) *//* * Improvements submitted by (ITS#3432) * * 1. id_query.patch		applied (with changes) * 2. shortcut.patch		applied (reworked) * 3. create_hint.patch		applied * 4. count_query.patch		applied (reworked) * 5. returncodes.patch		applied (with sanity checks) * 6. connpool.patch		under evaluation * 7. modoc.patch		under evaluation (requires * 				manageDSAit and "manage" * 				access privileges) * 8. miscfixes.patch		applied (reworked; other *				operations need to load the *				entire entry for ACL purposes; *				see ITS#3480, now fixed) * * original description:         Changes that were made to the SQL backend.The patches were made against 2.2.18 and can be applied individually,but would best be applied in the numerical order of the file names.A synopsis of each patch is given here:1. Added an option to set SQL query for the "id_query" operation.2. Added an option to the SQL backend called "use_subtree_shortcut".When a search is performed, the SQL query includes a WHERE clausewhich says the DN must be "LIKE %<searchbase>".  The LIKE operationcan be slow in an RDBM. This shortcut option says that if thesearchbase of the LDAP search is the root DN of the SQL backend,and thus all objects will match the LIKE operator, do not includethe "LIKE %<searchbase>" clause in the SQL query (it is replacedinstead by the always true "1=1" clause to keep the "AND"'s working correctly).  This option is off by default, and should beturned on only if all objects to be found in the RDBM are under thesame root DN. Multiple backends working within the same RDBM tablespace would encounter problems. LDAP searches whose searchbase arenot at the root DN will bypass this shortcut and employ the LIKE clause.3. Added a "create_hint" column to ldap_oc_mappings table. Allowstaking the value of an attr named in "create_hint" and passing it tothe create_proc procedure.  This is necessary for when an objectClass'stable is partition indexed by some indexing column and thus the valuein that indexing column cannot change after the row is created. Thevalue for the indexed column is passed into the create_proc, whichuses it to fill in the indexed column as the new row is created.4. When loading the values of an attribute, the count(*) of the numberof values is fetched first and memory is allocated for the array ofvalues and normalized values. The old system of loading the values oneby one and running realloc() on the array of values and normalizedvalues each time was badly fragmenting memory. The array of values andnormalized values would be side by side in memory, and realloc()'ingthem over and over would force them to leapfrog each other through allof available memory. Attrs with a large number of values could not beloaded without crashing the slapd daemon.5. Added code to interpret the value returned by stored procedureswhich have expect_return set. Returned value is interpreted as an LDAPreturn code. This allows the distinction between the SQL failing toexecute and the SQL running to completion and returning an error codewhich can indicate a policy violation.6. Added RDBM connection pooling. Once an operation is finished theconnection to the RDBM is returned to a pool rather than closing.Allows the next operation to skip the initialization and authenticationphases of contacting the RDBM. Also, if licensing with ODBC placesa limit on the number of connections, an LDAP thread can block waitingfor another thread to finish, so that no LDAP errors are returnedfor having more LDAP connections than allowed RDBM connections. AnRDBM connection which receives an SQL error is marked as "tainted"so that it will be closed rather than returned to the pool.  Also, RDBM connections must be bound to a given LDAP connection ANDoperation number, and NOT just the connection number.  AsynchronousLDAP clients can have multiple simultaneous LDAP operations whichshould not share the same RDBM connection.  A given LDAP operation caneven make multiple SQL operations (e.g. a BIND operation whichrequires SASL to perform an LDAP search to convert the SASL ID to anLDAP DN), so each RDBM connection now has a refcount that must reachzero before the connection is returned to the free pool.7. Added ability to change the objectClass of an object. Required considerable work to copy all attributes out of old object and intonew object.  Does a schema check before proceeding.  Creates a newobject, fills it in, deletes the old object, then changes the oc_map_id and keyval of the entry in the "ldap_entries" table.8.  Generic fixes. Includes initializing pointers before theyget used in error branch cases, pointer checks before dereferencing,resetting a return code to success after a COMPARE op, sealingmemory leaks, and in search.c, changing some of the "1=1" tests to"2=2", "3=3", etc so that when reading slapd trace output, the location in the source code where the x=x test was added to the SQLcan be easily distinguished. */#ifndef __BACKSQL_H__#define __BACKSQL_H__/* former sql-types.h */#include <sql.h>#include <sqlext.h>typedef struct {	SWORD		ncols;	BerVarray	col_names;	UDWORD		*col_prec;	char		**cols;	SQLINTEGER	*value_len;} BACKSQL_ROW_NTS;/* * Better use the standard length of 8192 (as of slap.h)? * * NOTE: must be consistent with definition in ldap_entries table *//* #define BACKSQL_MAX_DN_LEN	SLAP_LDAPDN_MAXLEN */#define BACKSQL_MAX_DN_LEN	255/* * define to enable very extensive trace logging (debug only) */#undef BACKSQL_TRACE/* * define if using MS SQL and workaround needed (see sql-wrap.c) */#undef BACKSQL_MSSQL_WORKAROUND/* * define to enable values counting for attributes */#define BACKSQL_COUNTQUERY/* * define to enable prettification/validation of values */#define BACKSQL_PRETTY_VALIDATE/* * define to enable varchars as unique keys in user tables * * by default integers are used (and recommended) * for performances.  Integers are used anyway in back-sql * related tables. */#undef BACKSQL_ARBITRARY_KEY/* * define to enable support for syncprov overlay */#define BACKSQL_SYNCPROV/* * define to the appropriate aliasing string * * some RDBMSes tolerate (or require) that " AS " is not used * when aliasing tables/columns */#define BACKSQL_ALIASING	"AS "/* #define	BACKSQL_ALIASING	"" *//* * define to the appropriate quoting char * * some RDBMSes tolerate/require that the aliases be enclosed * in quotes.  This is especially true for those that do not * allow keywords used as aliases. */#define BACKSQL_ALIASING_QUOTE	""/* #define BACKSQL_ALIASING_QUOTE	"\"" *//* #define BACKSQL_ALIASING_QUOTE	"'" *//* * API * * a simple mechanism to allow DN mucking between the LDAP * and the stored string representation. */typedef struct backsql_api {	char			*ba_name;	int 			(*ba_config)( struct backsql_api *self, int argc, char *argv[] );	int			(*ba_destroy)( struct backsql_api *self );	int 			(*ba_dn2odbc)( Operation *op, SlapReply *rs, struct berval *dn );	int 			(*ba_odbc2dn)( Operation *op, SlapReply *rs, struct berval *dn );	void			*ba_private;	struct backsql_api	*ba_next;} backsql_api;/* * Entry ID structure */typedef struct backsql_entryID {	/* #define BACKSQL_ARBITRARY_KEY to allow a non-numeric key.	 * It is required by some special applications that use	 * strings as keys for the main table.	 * In this case, #define BACKSQL_MAX_KEY_LEN consistently	 * with the key size definition */#ifdef BACKSQL_ARBITRARY_KEY	struct berval		eid_id;	struct berval		eid_keyval;#define BACKSQL_MAX_KEY_LEN	64#else /* ! BACKSQL_ARBITRARY_KEY */	/* The original numeric key is maintained as default. */	unsigned long		eid_id;	unsigned long		eid_keyval;#endif /* ! BACKSQL_ARBITRARY_KEY */	unsigned long		eid_oc_id;	struct berval		eid_dn;	struct berval		eid_ndn;	struct backsql_entryID	*eid_next;} backsql_entryID;#ifdef BACKSQL_ARBITRARY_KEY#define BACKSQL_ENTRYID_INIT { BER_BVNULL, BER_BVNULL, 0, BER_BVNULL, BER_BVNULL, NULL }