[Pkg-openldap-devel] r1147 - in openldap/vendor/openldap-release: . build contrib/slapd-modules contrib/slapd-modules/nops contrib/slapd-modules/smbk5pwd doc doc/drafts doc/guide doc/guide/admin doc/guide/release doc/man/man5 doc/rfc libraries/libldap libraries/libldap_r servers/slapd servers/slapd/back-bdb servers/slapd/back-ldap servers/slapd/back-meta servers/slapd/back-monitor servers/slapd/overlays servers/slapd/schema servers/slapd/slapi
vorlon at alioth.debian.org
vorlon at alioth.debian.org
Sat Jun 28 09:30:00 UTC 2008
Author: vorlon
Date: 2008-06-28 09:29:58 +0000 (Sat, 28 Jun 2008)
New Revision: 1147
Added:
openldap/vendor/openldap-release/contrib/slapd-modules/nops/
openldap/vendor/openldap-release/contrib/slapd-modules/nops/Makefile
openldap/vendor/openldap-release/contrib/slapd-modules/nops/nops.c
openldap/vendor/openldap-release/contrib/slapd-modules/nops/slapo-nops.5
openldap/vendor/openldap-release/doc/drafts/
openldap/vendor/openldap-release/doc/drafts/README
openldap/vendor/openldap-release/doc/drafts/draft-behera-ldap-password-policy-xx.txt
openldap/vendor/openldap-release/doc/drafts/draft-chu-ldap-csn-xx.txt
openldap/vendor/openldap-release/doc/drafts/draft-haripriya-dynamicgroup-xx.txt
openldap/vendor/openldap-release/doc/drafts/draft-ietf-ldapext-acl-model-xx.txt
openldap/vendor/openldap-release/doc/drafts/draft-ietf-ldapext-ldap-c-api-xx.txt
openldap/vendor/openldap-release/doc/drafts/draft-ietf-ldapext-ldapv3-dupent-xx.txt
openldap/vendor/openldap-release/doc/drafts/draft-ietf-ldapext-ldapv3-vlv-xx.txt
openldap/vendor/openldap-release/doc/drafts/draft-ietf-ldapext-locate-xx.txt
openldap/vendor/openldap-release/doc/drafts/draft-joslin-config-schema-xx.txt
openldap/vendor/openldap-release/doc/drafts/draft-lachman-laser-ldap-mail-routing-xx.txt
openldap/vendor/openldap-release/doc/drafts/draft-legg-ldap-acm-admin-xx.txt
openldap/vendor/openldap-release/doc/drafts/draft-legg-ldap-acm-bac-xx.txt
openldap/vendor/openldap-release/doc/drafts/draft-legg-ldap-admin-xx.txt
openldap/vendor/openldap-release/doc/drafts/draft-legg-ldap-transfer-xx.txt
openldap/vendor/openldap-release/doc/drafts/draft-sermersheim-ldap-chaining-xx.txt
openldap/vendor/openldap-release/doc/drafts/draft-sermersheim-ldap-csn-xx.txt
openldap/vendor/openldap-release/doc/drafts/draft-sermersheim-ldap-distproc-xx.txt
openldap/vendor/openldap-release/doc/drafts/draft-sermersheim-ldap-subordinate-scope-xx.txt
openldap/vendor/openldap-release/doc/drafts/draft-wahl-ldap-session-xx.txt
openldap/vendor/openldap-release/doc/drafts/draft-zeilenga-ldap-dontusecopy-xx.txt
openldap/vendor/openldap-release/doc/drafts/draft-zeilenga-ldap-noop-xx.txt
openldap/vendor/openldap-release/doc/drafts/draft-zeilenga-ldap-relax.txt
openldap/vendor/openldap-release/doc/drafts/draft-zeilenga-ldap-txn-xx.txt
openldap/vendor/openldap-release/doc/rfc/
openldap/vendor/openldap-release/doc/rfc/INDEX
openldap/vendor/openldap-release/doc/rfc/rfc2079.txt
openldap/vendor/openldap-release/doc/rfc/rfc2247.txt
openldap/vendor/openldap-release/doc/rfc/rfc2293.txt
openldap/vendor/openldap-release/doc/rfc/rfc2294.txt
openldap/vendor/openldap-release/doc/rfc/rfc2307.txt
openldap/vendor/openldap-release/doc/rfc/rfc2377.txt
openldap/vendor/openldap-release/doc/rfc/rfc2589.txt
openldap/vendor/openldap-release/doc/rfc/rfc2649.txt
openldap/vendor/openldap-release/doc/rfc/rfc2696.txt
openldap/vendor/openldap-release/doc/rfc/rfc2713.txt
openldap/vendor/openldap-release/doc/rfc/rfc2714.txt
openldap/vendor/openldap-release/doc/rfc/rfc2798.txt
openldap/vendor/openldap-release/doc/rfc/rfc2849.txt
openldap/vendor/openldap-release/doc/rfc/rfc2891.txt
openldap/vendor/openldap-release/doc/rfc/rfc2926.txt
openldap/vendor/openldap-release/doc/rfc/rfc3045.txt
openldap/vendor/openldap-release/doc/rfc/rfc3062.txt
openldap/vendor/openldap-release/doc/rfc/rfc3088.txt
openldap/vendor/openldap-release/doc/rfc/rfc3112.txt
openldap/vendor/openldap-release/doc/rfc/rfc3296.txt
openldap/vendor/openldap-release/doc/rfc/rfc3663.txt
openldap/vendor/openldap-release/doc/rfc/rfc3671.txt
openldap/vendor/openldap-release/doc/rfc/rfc3672.txt
openldap/vendor/openldap-release/doc/rfc/rfc3673.txt
openldap/vendor/openldap-release/doc/rfc/rfc3687.txt
openldap/vendor/openldap-release/doc/rfc/rfc3698.txt
openldap/vendor/openldap-release/doc/rfc/rfc3703.txt
openldap/vendor/openldap-release/doc/rfc/rfc3712.txt
openldap/vendor/openldap-release/doc/rfc/rfc3727.txt
openldap/vendor/openldap-release/doc/rfc/rfc3829.txt
openldap/vendor/openldap-release/doc/rfc/rfc3866.txt
openldap/vendor/openldap-release/doc/rfc/rfc3876.txt
openldap/vendor/openldap-release/doc/rfc/rfc3909.txt
openldap/vendor/openldap-release/doc/rfc/rfc3928.txt
openldap/vendor/openldap-release/doc/rfc/rfc4013.txt
openldap/vendor/openldap-release/doc/rfc/rfc4370.txt
openldap/vendor/openldap-release/doc/rfc/rfc4373.txt
openldap/vendor/openldap-release/doc/rfc/rfc4403.txt
openldap/vendor/openldap-release/doc/rfc/rfc4510.txt
openldap/vendor/openldap-release/doc/rfc/rfc4511.txt
openldap/vendor/openldap-release/doc/rfc/rfc4512.txt
openldap/vendor/openldap-release/doc/rfc/rfc4513.txt
openldap/vendor/openldap-release/doc/rfc/rfc4514.txt
openldap/vendor/openldap-release/doc/rfc/rfc4515.txt
openldap/vendor/openldap-release/doc/rfc/rfc4516.txt
openldap/vendor/openldap-release/doc/rfc/rfc4517.txt
openldap/vendor/openldap-release/doc/rfc/rfc4518.txt
openldap/vendor/openldap-release/doc/rfc/rfc4519.txt
openldap/vendor/openldap-release/doc/rfc/rfc4520.txt
openldap/vendor/openldap-release/doc/rfc/rfc4521.txt
openldap/vendor/openldap-release/doc/rfc/rfc4522.txt
openldap/vendor/openldap-release/doc/rfc/rfc4523.txt
openldap/vendor/openldap-release/doc/rfc/rfc4524.txt
openldap/vendor/openldap-release/doc/rfc/rfc4525.txt
openldap/vendor/openldap-release/doc/rfc/rfc4526.txt
openldap/vendor/openldap-release/doc/rfc/rfc4527.txt
openldap/vendor/openldap-release/doc/rfc/rfc4528.txt
openldap/vendor/openldap-release/doc/rfc/rfc4529.txt
openldap/vendor/openldap-release/doc/rfc/rfc4530.txt
openldap/vendor/openldap-release/doc/rfc/rfc4531.txt
openldap/vendor/openldap-release/doc/rfc/rfc4532.txt
openldap/vendor/openldap-release/doc/rfc/rfc4533.txt
openldap/vendor/openldap-release/doc/rfc/rfc5020.txt
openldap/vendor/openldap-release/servers/slapd/schema/collective.schema
openldap/vendor/openldap-release/servers/slapd/schema/corba.schema
openldap/vendor/openldap-release/servers/slapd/schema/core.ldif
openldap/vendor/openldap-release/servers/slapd/schema/core.schema
openldap/vendor/openldap-release/servers/slapd/schema/cosine.schema
openldap/vendor/openldap-release/servers/slapd/schema/java.schema
openldap/vendor/openldap-release/servers/slapd/schema/ppolicy.schema
Modified:
openldap/vendor/openldap-release/CHANGES
openldap/vendor/openldap-release/COPYRIGHT
openldap/vendor/openldap-release/build/version.var
openldap/vendor/openldap-release/contrib/slapd-modules/smbk5pwd/smbk5pwd.c
openldap/vendor/openldap-release/doc/guide/COPYRIGHT
openldap/vendor/openldap-release/doc/guide/admin/access-control.sdf
openldap/vendor/openldap-release/doc/guide/admin/appendix-upgrading.sdf
openldap/vendor/openldap-release/doc/guide/admin/aspell.en.pws
openldap/vendor/openldap-release/doc/guide/admin/guide.html
openldap/vendor/openldap-release/doc/guide/admin/preface.sdf
openldap/vendor/openldap-release/doc/guide/admin/security.sdf
openldap/vendor/openldap-release/doc/guide/release/copyright.sdf
openldap/vendor/openldap-release/doc/man/man5/slapd-config.5
openldap/vendor/openldap-release/doc/man/man5/slapd.conf.5
openldap/vendor/openldap-release/doc/man/man5/slapo-constraint.5
openldap/vendor/openldap-release/doc/man/man5/slapo-refint.5
openldap/vendor/openldap-release/doc/man/man5/slapo-rwm.5
openldap/vendor/openldap-release/libraries/libldap/os-ip.c
openldap/vendor/openldap-release/libraries/libldap/os-local.c
openldap/vendor/openldap-release/libraries/libldap/request.c
openldap/vendor/openldap-release/libraries/libldap/result.c
openldap/vendor/openldap-release/libraries/libldap/t61.c
openldap/vendor/openldap-release/libraries/libldap_r/thr_stub.c
openldap/vendor/openldap-release/servers/slapd/acl.c
openldap/vendor/openldap-release/servers/slapd/back-bdb/attr.c
openldap/vendor/openldap-release/servers/slapd/back-bdb/dn2id.c
openldap/vendor/openldap-release/servers/slapd/back-bdb/monitor.c
openldap/vendor/openldap-release/servers/slapd/back-ldap/search.c
openldap/vendor/openldap-release/servers/slapd/back-meta/config.c
openldap/vendor/openldap-release/servers/slapd/back-monitor/database.c
openldap/vendor/openldap-release/servers/slapd/backglue.c
openldap/vendor/openldap-release/servers/slapd/backover.c
openldap/vendor/openldap-release/servers/slapd/bconfig.c
openldap/vendor/openldap-release/servers/slapd/daemon.c
openldap/vendor/openldap-release/servers/slapd/main.c
openldap/vendor/openldap-release/servers/slapd/overlays/constraint.c
openldap/vendor/openldap-release/servers/slapd/overlays/ppolicy.c
openldap/vendor/openldap-release/servers/slapd/overlays/refint.c
openldap/vendor/openldap-release/servers/slapd/overlays/syncprov.c
openldap/vendor/openldap-release/servers/slapd/overlays/unique.c
openldap/vendor/openldap-release/servers/slapd/proto-slap.h
openldap/vendor/openldap-release/servers/slapd/result.c
openldap/vendor/openldap-release/servers/slapd/schema_init.c
openldap/vendor/openldap-release/servers/slapd/sets.h
openldap/vendor/openldap-release/servers/slapd/slap.h
openldap/vendor/openldap-release/servers/slapd/slapi/plugin.c
openldap/vendor/openldap-release/servers/slapd/slapi/proto-slapi.h
openldap/vendor/openldap-release/servers/slapd/slapi/slapi_overlay.c
openldap/vendor/openldap-release/servers/slapd/syncrepl.c
Log:
Load openldap-2.4.10 into openldap/vendor/openldap-release.
Modified: openldap/vendor/openldap-release/CHANGES
===================================================================
--- openldap/vendor/openldap-release/CHANGES 2008-06-10 19:53:50 UTC (rev 1146)
+++ openldap/vendor/openldap-release/CHANGES 2008-06-28 09:29:58 UTC (rev 1147)
@@ -1,5 +1,34 @@
OpenLDAP 2.4 Change Log
+OpenLDAP 2.4.10 Release (2008/06/08)
+ Fixed libldap file descriptor leak with SELinux (ITS#5507)
+ Fixed libldap ld_defconn cleanup if it was freed (ITS#5518, ITS#5525)
+ Fixed libldap msgid handling (ITS#5318)
+ Fixed libldap t61 infinite loop (ITS#5542)
+ Fixed libldap_r missing stubs (ITS#5519)
+ Fixed slapd initialization of sr_msgid, rs->sr_tag (ITS#5461)
+ Fixed slapd missing termination of integerFilter keys (ITS#5503)
+ Fixed slapd multiple attrs in URI (ITS#5516)
+ Fixed slapd sasl_ssf retrieval (ITS#5403)
+ Fixed slapd socket assert (ITS#5489)
+ Fixed slapd syncrepl cookie (ITS#5536)
+ Fixed slapd-bdb/hdb MAXPATHLEN (ITS#5531)
+ Fixed slapd-bdb indexing in single ADD/MOD (ITS#5521)
+ Fixed slapd-ldap entry_get() op-dependent behavior (ITS#5513)
+ Fixed slapd-meta quarantine crasher (ITS#5522)
+ Fixed slapo-refint to allow setting modifiers name (ITS#5505)
+ Fixed slapo-syncprov contextCSN passing on syncprov consumers (ITS#5488)
+ Fixed slapo-syncprov csn update with delta-syncrepl (ITS#5493)
+ Fixed slapo-syncprov op2.o_extra reset (ITS#5501, #5506)
+ Fixed slapo-syncprov searching wrong backend (ITS#5487)
+ Fixed slapo-syncprov sending ops without queued CSNs (ITS#5465)
+ Fixed slapo-syncprov max csn search on startup (ITS#5537)
+ Fixed slapo-unique config structs (ITS#5526)
+ Fixed slapo-unique filter terminator (ITS#5511)
+ Documentation
+ Add search privileges documentation (ITS#5512)
+ admin24 security document updates (ITS#5524)
+
OpenLDAP 2.4.9 Release (2008/05/07)
Fixed libldap to use unsigned port (ITS#5436)
Fixed libldap error message for missing close paren (ITS#5458)
Modified: openldap/vendor/openldap-release/COPYRIGHT
===================================================================
--- openldap/vendor/openldap-release/COPYRIGHT 2008-06-10 19:53:50 UTC (rev 1146)
+++ openldap/vendor/openldap-release/COPYRIGHT 2008-06-28 09:29:58 UTC (rev 1147)
@@ -36,11 +36,11 @@
---
-Portions Copyright 1999-2007 Howard Y.H. Chu.
-Portions Copyright 1999-2007 Symas Corporation.
+Portions Copyright 1999-2008 Howard Y.H. Chu.
+Portions Copyright 1999-2008 Symas Corporation.
Portions Copyright 1998-2003 Hallvard B. Furuseth.
-Portions Copyright 2008 Gavin Henry
-Portions Copyright 2008 Suretec Systems
+Portions Copyright 2008 Gavin Henry.
+Portions Copyright 2008 Suretec Systems.
All rights reserved.
Redistribution and use in source and binary forms, with or without
Modified: openldap/vendor/openldap-release/build/version.var
===================================================================
--- openldap/vendor/openldap-release/build/version.var 2008-06-10 19:53:50 UTC (rev 1146)
+++ openldap/vendor/openldap-release/build/version.var 2008-06-28 09:29:58 UTC (rev 1147)
@@ -1,5 +1,5 @@
#! /bin/sh
-# $OpenLDAP: pkg/ldap/build/version.var,v 1.9.2.26 2008/05/07 19:26:02 kurt Exp $
+# $OpenLDAP: pkg/ldap/build/version.var,v 1.9.2.32 2008/06/08 19:04:43 kurt Exp $
## This work is part of OpenLDAP Software <http://www.openldap.org/>.
##
## Copyright 1998-2008 The OpenLDAP Foundation.
@@ -15,9 +15,9 @@
ol_package=OpenLDAP
ol_major=2
ol_minor=4
-ol_patch=9
-ol_api_inc=20409
+ol_patch=10
+ol_api_inc=20410
ol_api_current=2
-ol_api_revision=5
+ol_api_revision=6
ol_api_age=0
-ol_release_date="2008/05/07"
+ol_release_date="2008/06/10"
Added: openldap/vendor/openldap-release/contrib/slapd-modules/nops/Makefile
===================================================================
--- openldap/vendor/openldap-release/contrib/slapd-modules/nops/Makefile (rev 0)
+++ openldap/vendor/openldap-release/contrib/slapd-modules/nops/Makefile 2008-06-28 09:29:58 UTC (rev 1147)
@@ -0,0 +1,9 @@
+CPPFLAGS+=-I../../../include -I../../../servers/slapd
+
+all: nops.so
+
+nops.so: nops.c
+ $(CC) -shared $(CPPFLAGS) -Wall -o $@ $?
+
+clean:
+ rm nops.so
Added: openldap/vendor/openldap-release/contrib/slapd-modules/nops/nops.c
===================================================================
--- openldap/vendor/openldap-release/contrib/slapd-modules/nops/nops.c (rev 0)
+++ openldap/vendor/openldap-release/contrib/slapd-modules/nops/nops.c 2008-06-28 09:29:58 UTC (rev 1147)
@@ -0,0 +1,168 @@
+/* $OpenLDAP: pkg/ldap/contrib/slapd-modules/nops/nops.c,v 1.1.2.1 2008/05/27 20:00:51 quanah Exp $ */
+/* nops.c - Overlay to filter idempotent operations */
+/*
+ * Copyright 2008 Emmanuel Dreyfus
+ * 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>.
+ */
+#include "portable.h"
+
+#ifdef SLAPD_OVER_NOPS
+
+#include <stdio.h>
+
+#include <ac/string.h>
+#include <ac/socket.h>
+
+#include "lutil.h"
+#include "slap.h"
+#include "config.h"
+
+static ConfigDriver nops_cf_gen;
+
+static int nops_cf_gen( ConfigArgs *c ) { return 0; }
+
+static void
+nops_rm_mod( Modifications **mods, Modifications *mod ) {
+ Modifications *next, *m;
+
+ next = mod->sml_next;
+ if (*mods == mod) {
+ *mods = next;
+ } else {
+ Modifications *m;
+
+ for (m = *mods; m; m = m->sml_next) {
+ if (m->sml_next == mod) {
+ m->sml_next = next;
+ break;
+ }
+ }
+ }
+
+ for (m = *mods; m; m = m->sml_next)
+ mod->sml_next = NULL;
+ slap_mods_free(mod, 1);
+
+ return;
+}
+
+static int
+nops_modify( Operation *op, SlapReply *rs )
+{
+ slap_overinst *on = (slap_overinst *) op->o_bd->bd_info;
+ Backend *be = op->o_bd;
+ Entry *target_entry = NULL;
+ Modifications *m;
+ int rc;
+
+ if ((m = op->orm_modlist) == NULL) {
+ op->o_bd->bd_info = (BackendInfo *)(on->on_info);
+ send_ldap_error(op, rs, LDAP_INVALID_SYNTAX,
+ "nops() got null orm_modlist");
+ return(rs->sr_err);
+ }
+
+ op->o_bd = on->on_info->oi_origdb;
+ rc = be_entry_get_rw(op, &op->o_req_ndn, NULL, NULL, 0, &target_entry);
+ op->o_bd = be;
+
+ if (rc != 0 || target_entry == NULL)
+ return 0;
+
+ /*
+ * For each attribute modification, check if the
+ * modification and the old entry are the same.
+ */
+ while (m) {
+ int i, j;
+ int found;
+ Attribute *a;
+ BerVarray bm;
+ BerVarray bt;
+ Modifications *mc;
+
+ mc = m;
+ m = m->sml_next;
+
+ /* Check only replace sub-operations */
+ if ((mc->sml_op & LDAP_MOD_OP) != LDAP_MOD_REPLACE)
+ continue;
+
+ /* If there is no values, skip */
+ if (((bm = mc->sml_values ) == NULL ) || (bm[0].bv_val == NULL))
+ continue;
+
+ /* If the attribute does not exist in old entry, skip */
+ if ((a = attr_find(target_entry->e_attrs, mc->sml_desc)) == NULL)
+ continue;
+ if ((bt = a->a_vals) == NULL)
+ continue;
+
+ /* For each value replaced, do we find it in old entry? */
+ found = 0;
+ for (i = 0; bm[i].bv_val; i++) {
+ for (j = 0; bt[j].bv_val; j++) {
+ if (bm[i].bv_len != bt[j].bv_len)
+ continue;
+ if (memcmp(bm[i].bv_val, bt[j].bv_val, bt[j].bv_len) != 0)
+ continue;
+
+ found++;
+ break;
+ }
+ }
+
+ /* Did we find as many values as we had in old entry? */
+ if (i != a->a_numvals || found != a->a_numvals)
+ continue;
+
+ /* This is a nop, remove it */
+ Debug(LDAP_DEBUG_TRACE, "removing nop on %s%s%s",
+ a->a_desc->ad_cname.bv_val, "", "");
+
+ nops_rm_mod(&op->orm_modlist, mc);
+ }
+ if (target_entry) {
+ op->o_bd = on->on_info->oi_origdb;
+ be_entry_release_r(op, target_entry);
+ op->o_bd = be;
+ }
+
+ if ((m = op->orm_modlist) == NULL) {
+ op->o_bd->bd_info = (BackendInfo *)(on->on_info);
+ send_ldap_error(op, rs, LDAP_SUCCESS, "");
+ return(rs->sr_err);
+ return (rs->sr_err);
+ }
+
+ return SLAP_CB_CONTINUE;
+}
+
+static slap_overinst nops_ovl;
+
+#if SLAPD_OVER_NOPS == SLAPD_MOD_DYNAMIC
+static
+#endif
+int
+nops_initialize( void ) {
+ nops_ovl.on_bi.bi_type = "nops";
+ nops_ovl.on_bi.bi_op_modify = nops_modify;
+ return overlay_register( &nops_ovl );
+}
+
+#if SLAPD_OVER_NOPS == SLAPD_MOD_DYNAMIC
+int init_module(int argc, char *argv[]) {
+ return nops_initialize();
+}
+#endif
+
+#endif /* defined(SLAPD_OVER_NOPS) */
+
Added: openldap/vendor/openldap-release/contrib/slapd-modules/nops/slapo-nops.5
===================================================================
--- openldap/vendor/openldap-release/contrib/slapd-modules/nops/slapo-nops.5 (rev 0)
+++ openldap/vendor/openldap-release/contrib/slapd-modules/nops/slapo-nops.5 2008-06-28 09:29:58 UTC (rev 1147)
@@ -0,0 +1,32 @@
+.TH SLAPO-NOPS 5 "RELEASEDATE" "OpenLDAP LDVERSION"
+.\" Copyright 2008 Emmanuel Dreyfus
+.\" Copying restrictions apply. See COPYRIGHT/LICENSE.
+.\" $OpenLDAP: pkg/ldap/contrib/slapd-modules/nops/slapo-nops.5,v 1.1.2.1 2008/05/27 20:00:51 quanah Exp $
+.SH NAME
+slapo-nops \- Remove Null Operations Overlay to slapd
+.SH SYNOPSIS
+ETCDIR/slapd.conf
+.SH DESCRIPTION
+Some broken client tend to implement modifications as replace operations
+where all attributes are replaced, most of the time by the same values
+they had before. This can cause undesirable load on logs, ACL evaluation,
+or replication trafic.
+
+This overlay detects idempotent replace operations and filter them out.
+.SH CONFIGURATION
+This overlay had no specific configuration.
+.SH EXAMPLES
+.LP
+.RS
+.nf
+overlay nops
+.RE
+.SH FILES
+.TP
+ETCDIR/slapd.conf
+default slapd configuration file
+.SH SEE ALSO
+.BR slapd.conf (5).
+.SH ACKNOWLEDGEMENTS
+This module was written in 2008 by Emmanuel Dreyfus.
+.so ../Project
Modified: openldap/vendor/openldap-release/contrib/slapd-modules/smbk5pwd/smbk5pwd.c
===================================================================
--- openldap/vendor/openldap-release/contrib/slapd-modules/smbk5pwd/smbk5pwd.c 2008-06-10 19:53:50 UTC (rev 1146)
+++ openldap/vendor/openldap-release/contrib/slapd-modules/smbk5pwd/smbk5pwd.c 2008-06-28 09:29:58 UTC (rev 1147)
@@ -1,5 +1,5 @@
/* smbk5pwd.c - Overlay for managing Samba and Heimdal passwords */
-/* $OpenLDAP: pkg/ldap/contrib/slapd-modules/smbk5pwd/smbk5pwd.c,v 1.17.2.10 2008/04/14 21:58:37 quanah Exp $ */
+/* $OpenLDAP: pkg/ldap/contrib/slapd-modules/smbk5pwd/smbk5pwd.c,v 1.17.2.11 2008/05/27 20:01:46 quanah Exp $ */
/*
* Copyright 2004-2005 by Howard Chu, Symas Corp.
* All rights reserved.
@@ -114,7 +114,7 @@
/* From liblutil/passwd.c... */
static void lmPasswd_to_key(
const char *lmPasswd,
- des_cblock *key)
+ DES_cblock *key)
{
const unsigned char *lpw = (const unsigned char *)lmPasswd;
unsigned char *k = (unsigned char *)key;
@@ -162,10 +162,10 @@
)
{
char UcasePassword[15];
- des_cblock key;
- des_key_schedule schedule;
- des_cblock StdText = "KGS!@#$%";
- des_cblock hbuf[2];
+ DES_cblock key;
+ DES_key_schedule schedule;
+ DES_cblock StdText = "KGS!@#$%";
+ DES_cblock hbuf[2];
strncpy( UcasePassword, passwd->bv_val, 14 );
UcasePassword[14] = '\0';
Added: openldap/vendor/openldap-release/doc/drafts/README
===================================================================
--- openldap/vendor/openldap-release/doc/drafts/README (rev 0)
+++ openldap/vendor/openldap-release/doc/drafts/README 2008-06-28 09:29:58 UTC (rev 1147)
@@ -0,0 +1,18 @@
+Internet-Drafts (I-Ds) are working documents of the Internet
+Engineering Task Force (IETF), its areas, its working groups, and
+individual contributors.
+
+I-Ds are only valid for a maximum of six months and may be updated,
+replaced, or obsoleted by other documents at any time. It is
+inappropriate to use I-Ds as reference material or to cite them
+other than as "work in progress."
+
+The OpenLDAP Project maintains copies of I-D for which we find
+interesting. Existance here does not necessarily imply any support
+nor any plans to support for the I-D. The I-Ds found in this
+directory may be stale, expired, or otherwise out of date.
+
+Please go to <http://www.ietf.org/> for latest revisions (and
+status).
+
+$OpenLDAP: pkg/ldap/doc/drafts/README,v 1.8 2003/12/07 06:54:38 kurt Exp $
Added: openldap/vendor/openldap-release/doc/drafts/draft-behera-ldap-password-policy-xx.txt
===================================================================
--- openldap/vendor/openldap-release/doc/drafts/draft-behera-ldap-password-policy-xx.txt (rev 0)
+++ openldap/vendor/openldap-release/doc/drafts/draft-behera-ldap-password-policy-xx.txt 2008-06-28 09:29:58 UTC (rev 1147)
@@ -0,0 +1,2298 @@
+
+
+
+
+Network Working Group J. Sermersheim
+Internet-Draft Novell, Inc
+Expires: January 18, 2006 L. Poitou
+ Sun Microsystems
+ July 17, 2005
+
+
+ Password Policy for LDAP Directories
+ draft-behera-ldap-password-policy-09.txt
+
+Status of this Memo
+
+ By submitting this Internet-Draft, each author represents that any
+ applicable patent or other IPR claims of which he or she is aware
+ have been or will be disclosed, and any of which he or she becomes
+ aware will be disclosed, in accordance with Section 6 of BCP 79.
+
+ Internet-Drafts are working documents of the Internet Engineering
+ Task Force (IETF), its areas, and its working groups. Note that
+ other groups may also distribute working documents as Internet-
+ Drafts.
+
+ Internet-Drafts are draft documents valid for a maximum of six months
+ and may be updated, replaced, or obsoleted by other documents at any
+ time. It is inappropriate to use Internet-Drafts as reference
+ material or to cite them other than as "work in progress."
+
+ The list of current Internet-Drafts can be accessed at
+ http://www.ietf.org/ietf/1id-abstracts.txt.
+
+ The list of Internet-Draft Shadow Directories can be accessed at
+ http://www.ietf.org/shadow.html.
+
+ This Internet-Draft will expire on January 18, 2006.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (2005).
+
+Abstract
+
+ Password policy as described in this document is a set of rules that
+ controls how passwords are used and administered in Lightweight
+ Directory Access Protocol (LDAP) based directories. In order to
+ improve the security of LDAP directories and make it difficult for
+ password cracking programs to break into directories, it is desirable
+ to enforce a set of rules on password usage. These rules are made to
+ ensure that users change their passwords periodically, passwords meet
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 1]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+ construction requirements, the re-use of old password is restricted,
+ and users are locked out after a certain number of failed attempts.
+
+Discussion Forum
+
+ Technical discussion of this document will take place on the IETF
+ LDAP Extensions mailing list <ldapext at ietf.org>. Please send
+ editorial comments directly to the authors.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 2]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+Table of Contents
+
+ 1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
+ 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 5
+ 3. Application of password policy . . . . . . . . . . . . . . . . 6
+ 4. Articles of password policy . . . . . . . . . . . . . . . . . 7
+ 4.1 Password Usage Policy . . . . . . . . . . . . . . . . . . . . 7
+ 4.2 Password Modification Policy . . . . . . . . . . . . . . . . . 7
+ 4.3 Restriction of the Password Policy . . . . . . . . . . . . . . 10
+ 5. Schema used for Password Policy . . . . . . . . . . . . . . . 11
+ 5.1 The pwdPolicy Object Class . . . . . . . . . . . . . . . . . . 11
+ 5.2 Attribute Types used in the pwdPolicy ObjectClass . . . . . . 11
+ 5.3 Attribute Types for Password Policy State Information . . . . 16
+ 6. Controls used for Password Policy . . . . . . . . . . . . . . 21
+ 6.1 Request Control . . . . . . . . . . . . . . . . . . . . . . . 21
+ 6.2 Response Control . . . . . . . . . . . . . . . . . . . . . . . 21
+ 7. Policy Decision Points . . . . . . . . . . . . . . . . . . . . 23
+ 7.1 Locked Account Check . . . . . . . . . . . . . . . . . . . . . 23
+ 7.2 Password Must be Changed Now Check . . . . . . . . . . . . . . 23
+ 7.3 Password Expiration Check . . . . . . . . . . . . . . . . . . 23
+ 7.4 Remaining Grace AuthN Check . . . . . . . . . . . . . . . . . 23
+ 7.5 Time Before Expiration Check . . . . . . . . . . . . . . . . . 24
+ 7.6 Intruder Detection Check . . . . . . . . . . . . . . . . . . . 24
+ 7.7 Password Too Young Check . . . . . . . . . . . . . . . . . . . 24
+ 8. Server Policy Enforcement Points . . . . . . . . . . . . . . . 25
+ 8.1 Password-based Authentication . . . . . . . . . . . . . . . . 25
+ 8.2 Password Update Operations . . . . . . . . . . . . . . . . . . 27
+ 8.3 Other Operations . . . . . . . . . . . . . . . . . . . . . . . 30
+ 9. Client Policy Enforcement Points . . . . . . . . . . . . . . . 31
+ 9.1 Bind Operation . . . . . . . . . . . . . . . . . . . . . . . . 31
+ 9.2 Modify Operations . . . . . . . . . . . . . . . . . . . . . . 32
+ 9.3 Add Operation . . . . . . . . . . . . . . . . . . . . . . . . 33
+ 9.4 Compare Operation . . . . . . . . . . . . . . . . . . . . . . 33
+ 9.5 Other Operations . . . . . . . . . . . . . . . . . . . . . . . 34
+ 10. Administration of the Password Policy . . . . . . . . . . . . 35
+ 11. Password Policy and Replication . . . . . . . . . . . . . . . 36
+ 12. Security Considerations . . . . . . . . . . . . . . . . . . . 37
+ 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38
+ 14. Acknowledgement . . . . . . . . . . . . . . . . . . . . . . . 39
+ 15. Normative References . . . . . . . . . . . . . . . . . . . . . 39
+ Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 40
+ Intellectual Property and Copyright Statements . . . . . . . . 41
+
+
+
+
+
+
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 3]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+1. Overview
+
+ LDAP-based directory services are currently accepted by many
+ organizations as the access protocol for directories. The ability to
+ ensure the secure read and update access to directory information
+ throughout the network is essential to the successful deployment.
+ Most LDAP implementations support many authentication schemes - the
+ most basic and widely used is the simple authentication i.e., user DN
+ and password. In this case, many LDAP servers have implemented some
+ kind of policy related to the password used to authenticate. Among
+ other things, this policy includes:
+
+ o Whether and when passwords expire.
+
+ o Whether failed bind attempts cause the account to be locked.
+
+ o If and how users are able to change their passwords.
+
+ In order to achieve greater security protection and ensure
+ interoperability in a heterogeneous environment, LDAP needs to
+ standardize on a common password policy model. This is critical to
+ the successful deployment of LDAP directories.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 4]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+2. Conventions
+
+ Imperative keywords defined in [RFC2119] are used in this document,
+ and carry the meanings described there.
+
+ All Basic Encoding Rules (BER) [X690] encodings follow the
+ conventions found in Section 5.1 of [RFC2251].
+
+ The term "password administrator" refers to a user that has
+ sufficient access control privileges to modify users' passwords. The
+ term "password policy administrator" refers to a user that has
+ sufficient access control privileges to modify the pwdPolicy object
+ defined in this document. The access control that is used to
+ determine whether an identity is a password administrator or password
+ policy administrator is beyond the scope of this document, but
+ typically implies that the password administrator has 'write'
+ privileges to the password attribute.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 5]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+3. Application of password policy
+
+ The password policy defined in this document can be applied to any
+ attribute holding a user's password used for an authenticated LDAP
+ bind operation. In this document, the term "user" represents any
+ LDAP client application that has an identity in the directory.
+
+ This policy is typically applied to the userPassword attribute in the
+ case of the LDAP simple authentication method [RFC2251] or the case
+ of password based SASL [RFC2222] authentication such as CRAM-MD5
+ [RFC2195] and DIGEST-MD5 [RFC2831].
+
+ The policy described in this document assumes that the password
+ attribute holds a single value. No considerations are made for
+ directories or systems that allow a user to maintain multi-valued
+ password attributes.
+
+ Server implementations MAY institute internal policy whereby certain
+ identities (such as directory administrators) are not forced to
+ comply with any of password policy. In this case, the password for a
+ directory administrator never expires; the account is never locked,
+ etc.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 6]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+4. Articles of password policy
+
+ The following sections explain in general terms each aspect of the
+ password policy defined in this document as well as the need for
+ each. These policies are subdivided into the general groups of
+ password usage and password modification. Implementation details are
+ presented in Section 8 and Section 9.
+
+4.1 Password Usage Policy
+
+ This section describes policy enforced when a password is used to
+ authenticate. The general focus of this policy is to minimize the
+ threat of intruders once a password is in use.
+
+4.1.1 Password Guessing Limit
+
+ In order to prevent intruders from guessing a user's password, a
+ mechanism exists to track the number of consecutive failed
+ authentication attempts, and take action when a limit is reached.
+ This policy consists of five parts:
+
+ o A configurable limit on failed authentication attempts.
+
+ o A counter to track the number of failed authentication attempts.
+
+ o A timeframe in which the limit of consecutive failed
+ authentication attempts must happen before action is taken.
+
+ o The action to be taken when the limit is reached. The action will
+ either be nothing, or the account will be locked.
+
+ o An amount of time the account is locked (if it is to be locked).
+ This can be indefinite.
+
+
+4.2 Password Modification Policy
+
+ This section describes policy enforced while users are modifying
+ passwords. The general focus of this policy is to ensure that when
+ users add or change their passwords, the security and effectiveness
+ of their passwords is maximized. In this document, the term "modify
+ password operation" refers to any operation that is used to add or
+ modify a password attribute. Often this is done by updating the
+ password attribute during an add or modify operation, but MAY be done
+ by other means such as an extended operation.
+
+
+
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 7]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+4.2.1 Password Expiration, Expiration Warning, and Grace
+ Authentications
+
+ One of the key properties of a password is the fact that it is not
+ well known. If a password is frequently changed, the chances of that
+ user's account being broken into are minimized.
+
+ Password policy administrators may deploy a password policy that
+ causes passwords to expire after a given amount of time - thus
+ forcing users to change their passwords periodically.
+
+ As a side effect, there needs to be a way in which users are made
+ aware of this need to change their password before actually being
+ locked out of their accounts. One or both of the following methods
+ handle this:
+
+ o A warning may be returned to the user sometime before his password
+ is due to expire. If the user fails to heed this warning before
+ the expiration time, his account will be locked.
+
+ o The user may bind to the directory a preset number of times after
+ her password has expired. If she fails to change her password
+ during one of her 'grace' authentications, her account will be
+ locked.
+
+
+4.2.2 Password History
+
+ When the Password Expiration policy is used, an additional mechanism
+ may be employed to prevent users from simply re-using a previous
+ password (as this would effectively circumvent the expiration
+ policy).
+
+ In order to do this; a history of used passwords is kept. The
+ password policy administrator sets the number of passwords to be
+ stored at any given time. Passwords are stored in this history
+ whenever the password is changed. Users aren't allowed to specify
+ any passwords that are in the history list while changing passwords.
+
+4.2.3 Password Minimum Age
+
+ Users may circumvent the Password History mechanism by quickly
+ performing a series of password changes. If they change their
+ password enough times, their 'favorite' password will be pushed out
+ of the history list.
+
+ This process may be made less attractive to users by employing a
+ minimum age for passwords. If users are forced to wait 24 hours
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 8]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+ between password changes, they may be less likely to cycle through a
+ history of 10 passwords.
+
+4.2.4 Password Quality and Minimum length
+
+ In order to prevent users from creating or updating passwords that
+ are easy to guess, a password quality policy may be employed. This
+ policy consists of two general mechanisms - ensuring that passwords
+ conform to a defined quality criterion and ensuring that they are of
+ a minimum length.
+
+ Forcing a password to comply with the quality policy may imply a
+ variety of things including:
+
+ o Disallowing trivial or well-known words make up the password.
+
+ o Forcing a certain number of digits be used.
+
+ o Disallowing anagrams of the user's name.
+
+ The implementation of this policy meets with the following problems:
+
+ o If the password to be added or updated is encrypted by the client
+ before being sent, the server has no way of enforcing this policy.
+ Therefore, the onus of enforcing this policy falls upon client
+ implementations.
+
+ o There are no specific definitions of what 'quality checking'
+ means. This can lead to unexpected behavior in a heterogeneous
+ environment.
+
+
+4.2.5 User Defined Passwords
+
+ In some cases, it is desirable to disallow users from adding and
+ updating their own passwords. This policy makes this functionality
+ possible.
+
+4.2.6 Password Change after Reset
+
+ This policy forces the user to update her password after it has been
+ set for the first time, or has been reset by a password
+ administrator.
+
+ This is needed in scenarios where a password administrator has set or
+ reset the password to a well-known value.
+
+
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 9]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+4.2.7 Safe Modification
+
+ As directories become more commonly used, it will not be unusual for
+ clients to connect to a directory and leave the connection open for
+ an extended period. This opens up the possibility for an intruder to
+ make modifications to a user's password while that user's computer is
+ connected but unattended.
+
+ This policy forces the user to prove his identity by specifying the
+ old password during a password modify operation.
+
+ {TODO: This allows a dictionary attack unless we specify that this is
+ also subject to intruder detection. One solution is to require users
+ to authN prior to changing password. Another solution is to perform
+ intruder detection checks when the password for a non-authenticated
+ identity is being updated}
+
+4.3 Restriction of the Password Policy
+
+ The password policy defined in this document can apply to any
+ attribute containing a password. Password policy state information
+ is held in the user's entry, and applies to a password attribute, not
+ a particular password attribute value. Thus the server SHOULD
+ enforce that the password attribute subject to password policy,
+ contains one and only one password value.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 10]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+5. Schema used for Password Policy
+
+ The schema elements defined here fall into two general categories. A
+ password policy object class is defined which contains a set of
+ administrative password policy attributes, and a set of operational
+ attributes are defined that hold general password policy state
+ information for each user.
+
+5.1 The pwdPolicy Object Class
+
+ This object class contains the attributes defining a password policy
+ in effect for a set of users. Section 10 describes the
+ administration of this object, and the relationship between it and
+ particular objects.
+
+ ( 1.3.6.1.4.1.42.2.27.8.2.1
+ NAME 'pwdPolicy'
+ SUP top
+ AUXILIARY
+ MUST ( pwdAttribute )
+ MAY ( pwdMinAge $ pwdMaxAge $ pwdInHistory $ pwdCheckQuality $
+ pwdMinLength $ pwdExpireWarning $ pwdGraceAuthNLimit $ pwdLockout
+ $ pwdLockoutDuration $ pwdMaxFailure $ pwdFailureCountInterval $
+ pwdMustChange $ pwdAllowUserChange $ pwdSafeModify ) )
+
+
+5.2 Attribute Types used in the pwdPolicy ObjectClass
+
+ Following are the attribute types used by the pwdPolicy object class.
+
+5.2.1 pwdAttribute
+
+ This holds the name of the attribute to which the password policy is
+ applied. For example, the password policy may be applied to the
+ userPassword attribute.
+
+ ( 1.3.6.1.4.1.42.2.27.8.1.1
+ NAME 'pwdAttribute'
+ EQUALITY objectIdentifierMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )
+
+
+5.2.2 pwdMinAge
+
+ This attribute holds the number of seconds that must elapse between
+ modifications to the password. If this attribute is not present, 0
+ seconds is assumed.
+
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 11]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+ ( 1.3.6.1.4.1.42.2.27.8.1.2
+ NAME 'pwdMinAge'
+ EQUALITY integerMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
+ SINGLE-VALUE )
+
+
+5.2.3 pwdMaxAge
+
+ This attribute holds the number of seconds after which a modified
+ password will expire.
+
+ If this attribute is not present, or if the value is 0 the password
+ does not expire. If not 0, the value must be greater than or equal
+ to the value of the pwdMinAge.
+
+ ( 1.3.6.1.4.1.42.2.27.8.1.3
+ NAME 'pwdMaxAge'
+ EQUALITY integerMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
+ SINGLE-VALUE )
+
+
+5.2.4 pwdInHistory
+
+ This attribute specifies the maximum number of used passwords stored
+ in the pwdHistory attribute.
+
+ If this attribute is not present, or if the value is 0, used
+ passwords are not stored in the pwdHistory attribute and thus may be
+ reused.
+
+ ( 1.3.6.1.4.1.42.2.27.8.1.4
+ NAME 'pwdInHistory'
+ EQUALITY integerMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
+ SINGLE-VALUE )
+
+
+5.2.5 pwdCheckQuality
+
+ {TODO: Consider changing the syntax to OID. Each OID will list a
+ quality rule (like min len, # of special characters, etc). These
+ rules can be specified outside this document.}
+
+ {TODO: Note that even though this is meant to be a check that happens
+ during password modification, it may also be allowed to happen during
+ authN. This is useful for situations where the password is encrypted
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 12]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+ when modified, but decrypted when used to authN.}
+
+ This attribute indicates how the password quality will be verified
+ while being modified or added. If this attribute is not present, or
+ if the value is '0', quality checking will not be enforced. A value
+ of '1' indicates that the server will check the quality, and if the
+ server is unable to check it (due to a hashed password or other
+ reasons) it will be accepted. A value of '2' indicates that the
+ server will check the quality, and if the server is unable to verify
+ it, it will return an error refusing the password.
+
+ ( 1.3.6.1.4.1.42.2.27.8.1.5
+ NAME 'pwdCheckQuality'
+ EQUALITY integerMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
+ SINGLE-VALUE )
+
+
+5.2.6 pwdMinLength
+
+ When quality checking is enabled, this attribute holds the minimum
+ number of characters that must be used in a password. If this
+ attribute is not present, no minimum password length will be
+ enforced. If the server is unable to check the length (due to a
+ hashed password or otherwise), the server will, depending on the
+ value of the pwdCheckQuality attribute, either accept the password
+ without checking it ('0' or '1') or refuse it ('2').
+
+ ( 1.3.6.1.4.1.42.2.27.8.1.6
+ NAME 'pwdMinLength'
+ EQUALITY integerMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
+ SINGLE-VALUE )
+
+
+5.2.7 pwdExpireWarning
+
+ This attribute specifies the maximum number of seconds before a
+ password is due to expire that expiration warning messages will be
+ returned to an authenticating user.
+
+ If this attribute is not present, or if the value is 0 no warnings
+ will be returned. If not 0, the value must be smaller than the value
+ of the pwdMaxAge attribute.
+
+ ( 1.3.6.1.4.1.42.2.27.8.1.7
+ NAME 'pwdExpireWarning'
+ EQUALITY integerMatch
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 13]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
+ SINGLE-VALUE )
+
+
+5.2.8 pwdGraceAuthNLimit
+
+ This attribute specifies the number of times an expired password can
+ be used to authenticate. If this attribute is not present or if the
+ value is 0, authentication will fail.
+
+ ( 1.3.6.1.4.1.42.2.27.8.1.8
+ NAME 'pwdGraceAuthNLimit'
+ EQUALITY integerMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
+ SINGLE-VALUE )
+
+
+5.2.9 pwdLockout
+
+ This attribute indicates, when its value is "TRUE", that the password
+ may not be used to authenticate after a specified number of
+ consecutive failed bind attempts. The maximum number of consecutive
+ failed bind attempts is specified in pwdMaxFailure.
+
+ If this attribute is not present, or if the value is "FALSE", the
+ password may be used to authenticate when the number of failed bind
+ attempts has been reached.
+
+ ( 1.3.6.1.4.1.42.2.27.8.1.9
+ NAME 'pwdLockout'
+ EQUALITY booleanMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
+ SINGLE-VALUE )
+
+
+5.2.10 pwdLockoutDuration
+
+ This attribute holds the number of seconds that the password cannot
+ be used to authenticate due to too many failed bind attempts. If
+ this attribute is not present, or if the value is 0 the password
+ cannot be used to authenticate until reset by a password
+ administrator.
+
+ ( 1.3.6.1.4.1.42.2.27.8.1.10
+ NAME 'pwdLockoutDuration'
+ EQUALITY integerMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
+ SINGLE-VALUE )
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 14]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+5.2.11 pwdMaxFailure
+
+ This attribute specifies the number of consecutive failed bind
+ attempts after which the password may not be used to authenticate.
+ If this attribute is not present, or if the value is 0, this policy
+ is not checked, and the value of pwdLockout will be ignored.
+
+ ( 1.3.6.1.4.1.42.2.27.8.1.11
+ NAME 'pwdMaxFailure'
+ EQUALITY integerMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
+ SINGLE-VALUE )
+
+
+5.2.12 pwdFailureCountInterval
+
+ This attribute holds the number of seconds after which the password
+ failures are purged from the failure counter, even though no
+ successful authentication occurred.
+
+ If this attribute is not present, or if its value is 0, the failure
+ counter is only reset by a successful authentication.
+
+ ( 1.3.6.1.4.1.42.2.27.8.1.12
+ NAME 'pwdFailureCountInterval'
+ EQUALITY integerMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
+ SINGLE-VALUE )
+
+
+5.2.13 pwdMustChange
+
+ This attribute specifies with a value of "TRUE" that users must
+ change their passwords when they first bind to the directory after a
+ password is set or reset by a password administrator. If this
+ attribute is not present, or if the value is "FALSE", users are not
+ required to change their password upon binding after the password
+ administrator sets or resets the password. This attribute is not set
+ due to any actions specified by this document, it is typically set by
+ a password administrator after resetting a user's password.
+
+ ( 1.3.6.1.4.1.42.2.27.8.1.13
+ NAME 'pwdMustChange'
+ EQUALITY booleanMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
+ SINGLE-VALUE )
+
+
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 15]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+5.2.14 pwdAllowUserChange
+
+ This attribute indicates whether users can change their own
+ passwords, although the change operation is still subject to access
+ control. If this attribute is not present, a value of "TRUE" is
+ assumed. This attribute is intended to be used in the absense of an
+ access control mechanism.
+
+ ( 1.3.6.1.4.1.42.2.27.8.1.14
+ NAME 'pwdAllowUserChange'
+ EQUALITY booleanMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
+ SINGLE-VALUE )
+
+
+5.2.15 pwdSafeModify
+
+ This attribute specifies whether or not the existing password must be
+ sent along with the new password when being changed. If this
+ attribute is not present, a "FALSE" value is assumed.
+
+ ( 1.3.6.1.4.1.42.2.27.8.1.15
+ NAME 'pwdSafeModify'
+ EQUALITY booleanMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
+ SINGLE-VALUE )
+
+
+5.3 Attribute Types for Password Policy State Information
+
+ Password policy state information must be maintained for each user.
+ The information is located in each user entry as a set of operational
+ attributes. These operational attributes are: pwdChangedTime,
+ pwdAccountLockedTime, pwdFailureTime, pwdHistory, pwdGraceUseTime,
+ pwdReset, pwdPolicySubEntry.
+
+5.3.1 Password Policy State Attribute Option
+
+ Since the password policy could apply to several attributes used to
+ store passwords, each of the above operational attributes must have
+ an option to specify which pwdAttribute it applies to. The password
+ policy option is defined as the following:
+
+ pwd-<passwordAttribute>
+
+ where passwordAttribute a string following the OID syntax
+ (1.3.6.1.4.1.1466.115.121.1.38). The attribute type descriptor
+ (short name) MUST be used.
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 16]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+ For example, if the pwdPolicy object has for pwdAttribute
+ "userPassword" then the pwdChangedTime operational attribute, in a
+ user entry, will be:
+
+ pwdChangedTime;pwd-userPassword: 20000103121520Z
+
+ This attribute option follows sub-typing semantics. If a client
+ requests a password policy state attribute to be returned in a search
+ operation, and does not specify an option, all subtypes of that
+ policy state attribute are returned.
+
+5.3.2 pwdChangedTime
+
+ This attribute specifies the last time the entry's password was
+ changed. This is used by the password expiration policy. If this
+ attribute does not exist, the password will never expire.
+
+ ( 1.3.6.1.4.1.42.2.27.8.1.16
+ NAME 'pwdChangedTime'
+ DESC 'The time the password was last changed'
+ EQUALITY generalizedTimeMatch
+ ORDERING generalizedTimeOrderingMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
+ SINGLE-VALUE
+ NO-USER-MODIFICATION
+ USAGE directoryOperation )
+
+
+5.3.3 pwdAccountLockedTime
+
+ This attribute holds the time that the user's account was locked. A
+ locked account means that the password may no longer be used to
+ authenticate. A 000001010000Z value means that the account has been
+ locked permanently, and that only a password administrator can unlock
+ the account.
+
+ ( 1.3.6.1.4.1.42.2.27.8.1.17
+ NAME 'pwdAccountLockedTime'
+ DESC 'The time an user account was locked'
+ EQUALITY generalizedTimeMatch
+ ORDERING generalizedTimeOrderingMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
+ SINGLE-VALUE
+ NO-USER-MODIFICATION
+ USAGE directoryOperation )
+
+
+
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 17]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+5.3.4 pwdFailureTime
+
+ This attribute holds the timestamps of the consecutive authentication
+ failures.
+
+ ( 1.3.6.1.4.1.42.2.27.8.1.19
+ NAME 'pwdFailureTime'
+ DESC 'The timestamps of the last consecutive authentication
+ failures'
+ EQUALITY generalizedTimeMatch
+ ORDERING generalizedTimeOrderingMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
+ NO-USER-MODIFICATION
+ USAGE directoryOperation )
+
+
+5.3.5 pwdHistory
+
+ This attribute holds a history of previously used passwords. Values
+ of this attribute are transmitted in string format as given by the
+ following ABNF:
+
+ pwdHistory = time "#" syntaxOID "#" length "#" data
+
+ time = <generalizedTimeString as specified in 6.14
+ of [RFC2252]>
+
+ syntaxOID = numericoid ; the string representation of the
+ ; dotted-decimal OID that defines the
+ ; syntax used to store the password.
+ ; numericoid is described in 4.1
+ ; of [RFC2252].
+
+ length = numericstring ; the number of octets in data.
+ ; numericstring is described in 4.1
+ ; of [RFC2252].
+
+ data = <octets representing the password in the format
+ specified by syntaxOID>.
+
+ This format allows the server to store, and transmit a history of
+ passwords that have been used. In order for equality matching to
+ function properly, the time field needs to adhere to a consistent
+ format. For this purpose, the time field MUST be in GMT format.
+
+ ( 1.3.6.1.4.1.42.2.27.8.1.20
+ NAME 'pwdHistory'
+ DESC 'The history of user s passwords'
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 18]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+ EQUALITY octetStringMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
+ NO-USER-MODIFICATION
+ USAGE directoryOperation )
+
+
+5.3.6 pwdGraceUseTime
+
+ This attribute holds the timestamps of grace authentications after a
+ password has expired.
+
+ ( 1.3.6.1.4.1.42.2.27.8.1.21
+ NAME 'pwdGraceUseTime'
+ DESC 'The timestamps of the grace authentication after the
+ password has expired'
+ EQUALITY generalizedTimeMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
+ NO-USER-MODIFICATION
+ USAGE directoryOperation )
+
+
+5.3.7 pwdReset
+
+ This attribute holds a flag to indicate (when TRUE) that the password
+ has been updated by the password administrator and must be changed by
+ the user.
+
+ ( 1.3.6.1.4.1.42.2.27.8.1.22
+ NAME 'pwdReset'
+ DESC 'The indication that the password has been reset'
+ EQUALITY booleanMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
+ SINGLE-VALUE
+ USAGE directoryOperation )
+
+
+5.3.8 pwdPolicySubentry
+
+ This attribute points to the pwdPolicy subentry in effect for this
+ object.
+
+ ( 1.3.6.1.4.1.42.2.27.8.1.23
+ NAME 'pwdPolicySubentry'
+ DESC 'The pwdPolicy subentry in effect for this object'
+ EQUALITY distinguishedNameMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
+ SINGLE-VALUE
+ NO-USER-MODIFICATION
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 19]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+ USAGE directoryOperation )
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 20]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+6. Controls used for Password Policy
+
+ This section details the controls used while enforcing password
+ policy. A request control is defined that is sent by a client with a
+ request operation in order to elicit a response control. The
+ response control contains various warnings and errors associated with
+ password policy.
+
+ {TODO: add a note about advertisement and discovery}
+
+6.1 Request Control
+
+ This control MAY be sent with any LDAP request message in order to
+ convey to the server that this client is aware of, and can process
+ the response control described in this document. When a server
+ receives this control, it will return the response control when
+ appropriate and with the proper data.
+
+ The controlType is 1.3.6.1.4.1.42.2.27.8.5.1 and the criticality may
+ be TRUE or FALSE. There is no controlValue.
+
+6.2 Response Control
+
+ If the client has sent a passwordPolicyRequest control, the server
+ (when solicited by the inclusion of the request control) sends this
+ control with the following operation responses: bindResponse,
+ modifyResponse, addResponse, compareResponse and possibly
+ extendedResponse, to inform of various conditions, and MAY be sent
+ with other operations (in the case of the changeAfterReset error).
+ The controlType is 1.3.6.1.4.1.42.2.27.8.5.1 and the controlValue is
+ the BER encoding of the following type:
+
+ PasswordPolicyResponseValue ::= SEQUENCE {
+ warning [0] CHOICE {
+ timeBeforeExpiration [0] INTEGER (0 .. maxInt),
+ graceAuthNsRemaining [1] INTEGER (0 .. maxInt) } OPTIONAL,
+ error [1] ENUMERATED {
+ passwordExpired (0),
+ accountLocked (1),
+ changeAfterReset (2),
+ passwordModNotAllowed (3),
+ mustSupplyOldPassword (4),
+ insufficientPasswordQuality (5),
+ passwordTooShort (6),
+ passwordTooYoung (7),
+ passwordInHistory (8) } OPTIONAL }
+
+ The timeBeforeExpiration warning specifies the number of seconds
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 21]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+ before a password will expire. The graceAuthNsRemaining warning
+ specifies the remaining number of times a user will be allowed to
+ authenticate with an expired password. The passwordExpired error
+ signifies that the password has expired and must be reset. The
+ changeAfterReset error signifies that the password must be changed
+ before the user will be allowed to perform any operation other than
+ bind and modify. The passwordModNotAllowed error is set when a user
+ is restricted from changing her password. The
+ insufficientPasswordQuality error is set when a password doesn't pass
+ quality checking. The passwordTooYoung error is set if the age of
+ the password to be modified is not yet old enough.
+
+ Typically, only either a warning or an error will be encoded though
+ there may be exceptions. For example, if the user is required to
+ change a password after the password administrator set it, and the
+ password will expire in a short amount of time, the control may
+ include the timeBeforeExpiration warning and the changeAfterReset
+ error.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 22]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+7. Policy Decision Points
+
+ Following are a number of procedures used to make policy decisions.
+ These procedures are typically performed by the server while
+ processing an operation.
+
+ The following sections contain detailed instructions that refer to
+ attributes of the pwdPolicy object class. When doing so, the
+ attribute of the pwdPolicy object that governs the entry being
+ discussed is implied.
+
+7.1 Locked Account Check
+
+ A status of true is returned to indicate that the account is locked
+ if any of these conditions are met:
+
+ o The value of the pwdAccountLockedTime attribute is 000001010000Z.
+
+ o The current time is less than the value of the
+ pwdAccountLockedTime attribute added to the value of the
+ pwdLockoutDuration.
+
+ Otherwise a status of false is returned.
+
+7.2 Password Must be Changed Now Check
+
+ A status of true is returned to indicate that the account is locked
+ if all of these conditions are met:
+
+ The pwdMustChange attribute is set to TRUE.
+
+ The pwdReset attribute is set to TRUE.
+
+ Otherwise a status of false is returned.
+
+7.3 Password Expiration Check
+
+ A status of true is returned indicating that the password has expired
+ if the current time minus the value of pwdChangedTime is greater than
+ the value of the pwdMaxAge.
+
+ Otherwise, a status of false is returned.
+
+7.4 Remaining Grace AuthN Check
+
+ If the pwdGraceUseTime attribute is present, the number of values in
+ that attribute subtracted from the value of pwdGraceAuthNLimit is
+ returned. Otherwise zero is returned. A positive result specifies
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 23]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+ the number of remaining grace authentications.
+
+7.5 Time Before Expiration Check
+
+ If the pwdExpireWarning attribute is not present a zero status is
+ returned. Otherwise the following steps are followed:
+
+ Subtract the time stored in pwdChangedTime from the current time to
+ arrive at the password's age. If the password's age is greater than
+ than the value of the pwdMaxAge attribute, a zero status is returned.
+ Subtract the value of the pwdExpireWarning attribute from the value
+ of the pwdMaxAge attribute to arrive at the warning age. If the
+ password's age is equal to or greater than the warning age, the value
+ of pwdMaxAge minus the password's age is returned.
+
+7.6 Intruder Detection Check
+
+ A status of true indicating that an intruder has been detected is
+ returned if the following conditions are met:
+
+ The pwdLockout attribute is TRUE.
+
+ The number of values in the pwdFailureTime attribute that are
+ younger than pwdFailureCountInterval is greater or equal to the
+ pwdMaxFailure attribute.
+
+ Otherwise a status of false is returned.
+
+ While performing this check, values of pwdFailureTime that are old by
+ more than pwdFailureCountInterval are purged and not counted.
+
+7.7 Password Too Young Check
+
+ A status of true indicating that not enough time has passed since the
+ password was last updated is returned if:
+
+ The value of pwdMinAge is non-zero and pwdChangedTime is present.
+
+ The value of pwdMinAge is greater than the current time minus the
+ value of pwdChangedTime.
+
+ Otherwise a false status is returned.
+
+
+
+
+
+
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 24]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+8. Server Policy Enforcement Points
+
+ The server SHOULD enforce that the password attribute subject to a
+ password policy as defined in this document, contains one and only
+ one password value.
+
+ The scenarios in the following operations assume that the client has
+ attached a passwordPolicyRequest control to the request message of
+ the operation. In the event that the passwordPolicyRequest control
+ was not sent, no passwordPolicyResponse control is returned. All
+ other instructions remain the same.
+
+ For successfuly completed operations, unless otherwise stated, no
+ passwordPolicyResponse control is returned.
+
+8.1 Password-based Authentication
+
+ This section contains the policy enforcement rules and policy data
+ updates used while validating a password. Operations that validate
+ passwords include, but are not limited to, the Bind operation where
+ the simple choice specifies a password, and the compare operation
+ where the attribute being compared holds a password. Note that while
+ the compare operation does not authenticate a user to the LDAP
+ server, it may be used by an external application for purposes of
+ authentication.
+
+8.1.1 Fail if the account is locked
+
+ If the account is locked as specified in Section 7.1, the server
+ fails the operation with an appropriate resultCode (i.e.
+ invalidCredentials (49) in the case of a bind operation, compareFalse
+ (5) in the case of a compare operation, etc.). The server MAY set
+ the error: accountLocked (1) in the passwordPolicyResponse in the
+ controls field of the message.
+
+8.1.2 Validated Password Procedures
+
+ If the validation operation indicates that the password validated,
+ these procedures are followed in order:
+
+8.1.2.1 Policy state updates
+
+ Delete the pwdFailureTime and pwdAccountLockedTime attributes.
+
+8.1.2.2 Password must be changed now
+
+ If the decision in Section 7.2 returns true, the server sends to the
+ client a response with an appropriate successful resultCode (i.e.
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 25]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+ success (0), compareTrue (6), etc.), and includes the
+ passwordPolicyResponse in the controls field of the bindResponse
+ message with the warning: changeAfterReset specified.
+
+ For bind, the server MUST then disallow all operations issued by this
+ user except modify password, bind, unbind, abandon and StartTLS
+ extended operation.
+
+8.1.2.3 Expired password
+
+ If the password has expired as per Section 7.3, the server either
+ returns a success or failure based on the state of grace
+ authentications.
+
+8.1.2.3.1 Remaining Grace Authentications
+
+ If there are remaining grace authentications as per Section 7.4, the
+ server adds a new value with the current time in pwdGraceUseTime.
+ Then it sends to the client a response with an appropriate successful
+ resultCode (i.e. success (0), compareTrue (6), etc.), and includes
+ the passwordPolicyResponse in the controls field of the response
+ message with the warning: graceAuthNsRemaining choice set to the
+ number of grace authentications left.
+
+ Implementor's note: The system time of the host machine may be more
+ granular than is needed to ensure unique values of this attribute.
+ It is recommended that a mechanism is used to ensure unique
+ generalized time values. The fractional seconds field may be used
+ for this purpose.
+
+8.1.2.3.2 No Remaining Grace Authentications
+
+ If there are no remaining grace authentications, the server fails the
+ operation with an appropriate resultCode (invalidCredentials (49),
+ compareFalse (5), etc.), and includes the passwordPolicyResponse in
+ the controls field of the bindResponse message with the error:
+ passwordExpired (0) set.
+
+8.1.2.4 Expiration Warning
+
+ If the result of Section 7.5 is a positive number, the server sends
+ to the client a response with an appropriate successful resultCode
+ (i.e. success (0), compareTrue (6), etc.), and includes the
+ passwordPolicyResponse in the controls field of the bindResponse
+ message with the warning: timeBeforeExiration set to the value as
+ described above. Otherwise, the server sends a successful response,
+ and omits the passwordPolicyResponse.
+
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 26]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+8.1.2.5 AuthN Failed Procedures
+
+ If the authentication process indicates that the password failed
+ validation due to invalid credentials, these procedures are followed:
+
+8.1.2.5.1 Policy state update
+
+ Add the current time as a value of the pwdFailureTime attribute.
+
+ Implementor's note: The system time of the host machine may be more
+ granular than is needed to ensure unique values of this attribute.
+ It is recommended that a mechanism is used to ensure unique
+ generalized time values. The fractional seconds field may be used
+ for this purpose.
+
+8.1.2.5.2 Lock on intruder detection
+
+ If the check in Section 7.6 returns a true state, the server locks
+ the account by setting the value of the pwdAccountLockedTime
+ attribute to the current time. After locking the account, the server
+ fails the operation with an appropriate resultCode
+ (invalidCredentials (49), compareFalse (5), etc.), and includes the
+ passwordPolicyResponse in the controls field of the message with the
+ error: accountLocked (1).
+
+8.2 Password Update Operations
+
+ Because the password is stored in an attribute, various operations
+ (like add and modify) may be used to create or update a password.
+ But some alternate mechanisms have been defined or may be defined,
+ such as the LDAP Password Modify Extended Operation [RFC3062].
+
+ While processing a password update, the server performs the following
+ steps:
+
+8.2.1 Safe Modification
+
+ If pwdSafeModify is set to TRUE and if there is an existing password
+ value, the server ensures that the password update operation includes
+ the user's existing password.
+
+ When the LDAP modify operation is used to modify a password, this is
+ done by specifying both a delete action and an add or replace action,
+ where the delete action specifies the existing password, and the add
+ or replace action specifies the new password. Other password update
+ operations SHOULD employ a similar mechanism. Otherwise this policy
+ will fail.
+
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 27]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+ If the existing password is not specified, the server does not
+ process the operation and sends the appropriate response message to
+ the client with the resultCode: insufficientAccessRights (50), and
+ includes the passwordPolicyResponse in the controls field of the
+ response message with the error: mustSupplyOldPassword (4).
+
+8.2.2 Change After Reset
+
+ If the decision in Section 7.2 returns true, the server ensures that
+ the password update operation contains no modifications other than
+ the modification of the password attribute. If other modifications
+ exist, the server sends a response message to the client with the
+ resultCode: insufficientAccessRights (50), and includes the
+ passwordPolicyResponse in the controls field of the response message
+ with the error: changeAfterReset (2).
+
+8.2.3 Rights Check
+
+ Check to see whether the bound identity has sufficient rights to
+ update the password. If the bound identity is a user changing its
+ own password, this MAY be done by checking the pwdAllowUserChange
+ attribute or using an access control mechanism. The determination of
+ this is implementation specific. If the user is not allowed to
+ update her password, the server sends a response message to the
+ client with the resultCode: insufficientAccessRights (50), and
+ includes the passwordPolicyResponse in the controls field of the
+ response message with the error: passwordModNotAllowed (3).
+
+8.2.4 Too Early to Update
+
+ If the check in Section 7.7 results in a true status The server sends
+ a response message to the client with the resultCode:
+ constraintViolation (19), and includes the passwordPolicyResponse in
+ the controls field of the response message with the error:
+ passwordTooYoung (7).
+
+8.2.5 Password Quality
+
+ Check the value of the pwdCheckQuality attribute. If the value is
+ non-zero, the server:
+
+ o Ensure that the password meets the quality criteria enforced by
+ the server. This enforcement is implementation specific.
+ If the server is unable to check the quality (due to a hashed
+ password or otherwise), the value of pwdCheckQuality is evaluated.
+ If the value is 1, operation continues. If the value is 2, the
+ server sends a response message to the client with the resultCode:
+ constraintViolation (19), and includes the passwordPolicyResponse
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 28]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+ in the controls field of the response message with the error:
+ insufficientPasswordQuality (5).
+ If the server is able to check the password quality, and the check
+ fails, the server sends a response message to the client with the
+ resultCode: constraintViolation (19), and includes the
+ passwordPolicyResponse in the controls field of the response
+ message with the error: insufficientPasswordQuality (5).
+
+ o checks the value of the pwdMinLength attribute. If the value is
+ non-zero, it ensures that the new password is of at least the
+ minimum length.
+ If the server is unable to check the length (due to a hashed
+ password or otherwise), the value of pwdCheckQuality is evaluated.
+ If the value is 1, operation continues. If the value is 2, the
+ server sends a response message to the client with the resultCode:
+ constraintViolation (19), and includes the passwordPolicyResponse
+ in the controls field of the response message with the error:
+ passwordTooShort (6).
+ If the server is able to check the password length, and the check
+ fails, the server sends a response message to the client with the
+ resultCode: constraintViolation (19), and includes the
+ passwordPolicyResponse in the controls field of the response
+ message with the error: passwordTooShort (6).
+
+
+8.2.6 Invalid Reuse
+
+ If pwdInHistory is present and its value is non-zero, the server
+ checks whether this password exists in the entry's pwdHistory
+ attribute or in the current password attribute. If the password does
+ exist in the pwdHistory attribute or in the current password
+ attribute, the server sends a response message to the client with the
+ resultCode: constraintViolation (19), and includes the
+ passwordPolicyResponse in the controls field of the response message
+ with the error: passwordInHistory (8).
+
+8.2.7 Policy State Updates
+
+ If the steps have completed without causing an error condition, the
+ server performs the following steps in order to update the necessary
+ password policy state attributes:
+
+ If the value of either pwdMaxAge or pwdMinAge is non-zero, the server
+ updates the pwdChangedTime attribute on the entry to the current
+ time.
+
+ If the value of pwdInHistory is non-zero, the server adds the
+ previous password (if one existed) to the pwdHistory attribute. If
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 29]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+ the number of attributes held in the pwdHistory attribute exceeds the
+ value of pwdInHistory, the server removes the oldest excess
+ passwords.
+
+ If the value the pwdMustChange is TRUE and the modification is
+ performed by a password administrator, then the pwdReset attribute is
+ set to TRUE. Otherwise, the pwdReset is removed from the user's
+ entry if it exists.
+
+ The pwdFailureTime and pwdGraceUseTime attributes is removed from the
+ user's entry if they exist.
+
+8.3 Other Operations
+
+ For operations other than bind, password update, unbind, abandon or
+ StartTLS, if the decision in Section 7.2 returns true, the server
+ sends a response message to the client with the resultCode:
+ insufficientAccessRights (50), and includes the
+ passwordPolicyResponse in the controls field of the response message
+ with the error: changeAfterReset (2).
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 30]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+9. Client Policy Enforcement Points
+
+ These sections illustrate possible scenarios for each LDAP operation
+ and define the types of responses that identify those scenarios.
+
+ The scenarios in the following operations assume that the client
+ attached a passwordPolicyRequest control to the request message of
+ the operation, and thus may receive a passwordPolicyResponse control
+ in the response message. In the event that the passwordPolicyRequest
+ control was not sent, no passwordPolicyResponse control is returned.
+ All other instructions remain the same.
+
+9.1 Bind Operation
+
+ For every bind response received, the client checks the resultCode of
+ the bindResponse and checks for a passwordPolicyResponse control to
+ determine if any of the following conditions are true and MAY prompt
+ the user accordingly.
+
+ o bindResponse.resultCode = insufficientAccessRights (50),
+ passwordPolicyResponse.error = accountLocked (1): The password
+ failure limit has been reached and the account is locked. The
+ user needs to retry later or contact the password administrator to
+ reset the password.
+
+ o bindResponse.resultCode = success (0),
+ passwordPolicyResponse.error = changeAfterReset (2): The user is
+ binding for the first time after the password administrator set
+ the password. In this scenario, the client SHOULD prompt the user
+ to change his password immediately.
+
+ o bindResponse.resultCode = success (0),
+ passwordPolicyResponse.warning = graceAuthNsRemaining: The
+ password has expired but there are remaining grace
+ authentications. The user needs to change it.
+
+ o bindResponse.resultCode = invalidCredentials (49),
+ passwordPolicyResponse.error = passwordExpired (0): The password
+ has expired and there are no more grace authentications. The user
+ contacts the password administrator in order to have its password
+ reset.
+
+ o bindResponse.resultCode = success (0),
+ passwordPolicyResponse.warning = timeBeforeExpiration: The user's
+ password will expire in n number of seconds.
+
+
+
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 31]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+9.2 Modify Operations
+
+9.2.1 Modify Request
+
+ If the application or client encrypts the password prior to sending
+ it in a password modification operation (whether done through
+ modifyRequest or another password modification mechanism), it SHOULD
+ check the values of the pwdMinLength, and pwdCheckQuality attributes
+ and SHOULD enforce these policies.
+
+9.2.2 Modify Response
+
+ If the modifyRequest operation was used to change the password, or if
+ another mechanism is used --such as an extendedRequest-- the
+ modifyResponse or other appropriate response MAY contain information
+ pertinent to password policy. The client checks the resultCode of
+ the response and checks for a passwordPolicyResponse control to
+ determine if any of the following conditions are true and optionally
+ notify the user of the condition.
+
+ o <pwdModResponse>.resultCode = insufficientAccessRights (50),
+ passwordPolicyResponse.error = mustSupplyOldPassword (4): The user
+ attempted to change her password without specifying the old
+ password but the password policy requires this.
+
+ o <pwdModResponse>.resultCode = insufficientAccessRights (50),
+ passwordPolicyResponse.error = changeAfterReset (2): The user must
+ change her password before submitting any other LDAP requests.
+
+ o <pwdModResponse>.resultCode = insufficientAccessRights (50),
+ passwordPolicyResponse.error = passwordModNotAllowed (3): The user
+ doesn't have sufficient rights to change his password.
+
+ o <pwdModResponse>.resultCode = constraintViolation (19),
+ passwordPolicyResponse.error = passwordTooYoung (7): It is too
+ soon after the last password modification to change the password.
+
+ o <pwdModResponse>.resultCode = constraintViolation (19),
+ passwordPolicyResponse.error = insufficientPasswordQuality (5):
+ The password failed quality checking.
+
+ o <pwdModResponse>.resultCode = constraintViolation (19),
+ passwordPolicyResponse.error = passwordTooShort (6): The length of
+ the password is too short.
+
+ o <pwdModResponse>.resultCode = constraintViolation (19),
+ passwordPolicyResponse.error = passwordInHistory (8): The password
+ has already been used; the user must choose a different one.
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 32]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+9.3 Add Operation
+
+ If a password is specified in an addRequest, the client checks the
+ resultCode of the addResponse and checks for a passwordPolicyResponse
+ control to determine if any of the following conditions are true and
+ may prompt the user accordingly.
+
+ o addResponse.resultCode = insufficientAccessRights (50),
+ passwordPolicyResponse.error = passwordModNotAllowed (3): The user
+ doesn't have sufficient rights to add this password.
+
+ o addResponse.resultCode = constraintViolation (19),
+ passwordPolicyResponse.error = insufficientPasswordQuality (5):
+ The password failed quality checking.
+
+ o addResponse.resultCode = constraintViolation (19),
+ passwordPolicyResponse.error = passwordTooShort (6): The length of
+ the password is too short.
+
+
+9.4 Compare Operation
+
+ When a compare operation is used to compare a password, the client
+ checks the resultCode of the compareResponse and checks for a
+ passwordPolicyResponse to determine if any of the following
+ conditions are true and MAY prompt the user accordingly. These
+ conditions assume that the result of the comparison was true.
+
+ o compareResponse.resultCode = compareFalse (5),
+ passwordPolicyResponse.error = accountLocked (1): The password
+ failure limit has been reached and the account is locked. The
+ user needs to retry later or contact the password administrator to
+ reset the password.
+
+ o compareResponse.resultCode = compareTrue (6),
+ passwordPolicyResponse.warning = graceAuthNsRemaining: The
+ password has expired but there are remaining grace
+ authentications. The user needs to change it.
+
+ o compareResponse.resultCode = compareFalse (5),
+ passwordPolicyResponse.error = passwordExpired (0): The password
+ has expired and there are no more grace authentications. The user
+ must contact the password administrator to reset the password.
+
+ o compareResponse.resultCode = compareTrue (6),
+ passwordPolicyResponse.warning = timeBeforeExpiration: The user's
+ password will expire in n number of seconds.
+
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 33]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+9.5 Other Operations
+
+ For operations other than bind, unbind, abandon or StartTLS, the
+ client checks the following result code and control to determine if
+ the user needs to change the password immediately.
+
+ o <Response>.resultCode = insufficientAccessRights (50),
+ passwordPolicyResponse.error = : changeAfterReset (2)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 34]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+10. Administration of the Password Policy
+
+ {TODO: Need to define an administrativeRole (need OID). Need to
+ describe whether pwdPolicy admin areas can overlap}
+
+ A password policy is defined for a particular subtree of the DIT by
+ adding to an LDAP subentry whose immediate superior is the root of
+ the subtree, the pwdPolicy auxiliary object class. The scope of the
+ password policy is defined by the SubtreeSpecification attribute of
+ the LDAP subentry as specified in [RFC3672].
+
+ It is possible to define password policies for different password
+ attributes within the same pwdPolicy entry, by specifying multiple
+ values of the pwdAttribute. But password policies could also be in
+ separate sub entries as long as they are contained under the same
+ LDAP subentry.
+
+ Modifying the password policy MUST NOT result in any change in users'
+ entries to which the policy applies.
+
+ It SHOULD be possible to overwrite the password policy for one user
+ by defining a new policy in a subentry of the user entry.
+
+ Each object that is controlled by password policy advertises the
+ subentry that is being used to control its policy in its
+ pwdPolicySubentry attribute. Clients wishing to examine or manage
+ password policy for an object may interrogate the pwdPolicySubentry
+ for that object in order to arrive at the proper pwdPolicy subentry.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 35]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+11. Password Policy and Replication
+
+ {TODO: This section needs to be changed to highlight the pitfals of
+ replication, sugest some implementation choices to overcome those
+ pitfals, but remove prescriptive language relating to the update of
+ state information}
+
+ The pwdPolicy object defines the password policy for a portion of the
+ DIT and MUST be replicated on all the replicas of this subtree, as
+ any subentry would be, in order to have a consistent policy among all
+ replicated servers.
+
+ The elements of the password policy that are related to the users are
+ stored in the entry themselves as operational attributes. As these
+ attributes are subject to modifications even on a read-only replica,
+ replicating them must be carefully considered.
+
+ The pwdChangedTime attribute MUST be replicated on all replicas, to
+ allow expiration of the password.
+
+ The pwdReset attribute MUST be replicated on all replicas, to deny
+ access to operations other than bind and modify password.
+
+ The pwdHistory attribute MUST be replicated to writable replicas. It
+ doesn't have to be replicated to a read-only replica, since the
+ password will never be directly modified on this server.
+
+ The pwdAccountLockedTime, pwdFailureTime and pwdGraceUseTime
+ attributes MUST be replicated to writable replicas, making the
+ password policy global for all servers. When the user entry is
+ replicated to a read-only replica, these attributes SHOULD NOT be
+ replicated. This means that the number of failures, of grace
+ authentications and the locking will take place on each replicated
+ server. For example, the effective number of failed attempts on a
+ user password will be N x M (where N is the number of servers and M
+ the value of pwdMaxFailure attribute). Replicating these attributes
+ to a read-only replica MAY reduce the number of tries globally but
+ MAY also introduce some inconstancies in the way the password policy
+ is applied.
+
+ Servers participating in a loosely consistent multi-master
+ replication agreement SHOULD employ a mechanism which ensures
+ uniqueness of values when populating the attributes pwdFailureTime
+ and pwdGraceUseTime. The method of achieving this is a local matter
+ and may consist of using a single authoritative source for the
+ generation of unique time values, or may consist of the use of the
+ fractional seconds part to hold a replica identifier.
+
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 36]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+12. Security Considerations
+
+ This document defines a set of rules to implement in an LDAP server,
+ in order to mitigate some of the security risks associated with the
+ use of passwords and to make it difficult for password cracking
+ programs to break into directories.
+
+ Authentication with a password MUST follow the recommendations made
+ in [RFC2829].
+
+ Modifications of passwords SHOULD only occur when the connection is
+ protected with confidentiality and secure authentication.
+
+ Access controls SHOULD be used to restrict access to the password
+ policy attributes. The attributes defined to maintain the password
+ policy state information SHOULD only be modifiable by the password
+ administrator or higher authority. The pwdHistory attribute MUST be
+ subject to the same level of access control as the attrbute holding
+ the password.
+
+ As it is possible to define a password policy for one specific user
+ by adding a subentry immediately under the user's entry, Access
+ Controls SHOULD be used to restrict the use of the pwdPolicy object
+ class or the LDAP subentry object class.
+
+ When the intruder detection password policy is enforced, the LDAP
+ directory is subject to a denial of service attack. A malicious user
+ could deliberately lock out one specific user's account (or all of
+ them) by sending bind requests with wrong passwords. There is no way
+ to protect against this kind of attack. The LDAP directory server
+ SHOULD log as much information as it can (such as client IP address)
+ whenever an account is locked, in order to be able to identify the
+ origin of the attack. Denying anonymous access to the LDAP directory
+ is also a way to restrict this kind of attack.
+
+ Returning certain status codes (such as passwordPolicyResponse.error
+ = accountLocked) allows a denial of service attacker to know that it
+ has successfully denied service to an account. Servers SHOULD
+ implement additional checks which return the same status when it is
+ sensed that some number of failed authentication requests has occured
+ on a single connection, or from a client address. Server
+ implementors are encouraged to invent other checks similar to this in
+ order to thwart this type of DoS attack.
+
+
+
+
+
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 37]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+13. IANA Considerations
+
+ <<<TBD>>>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 38]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+14. Acknowledgement
+
+ This document is based in part on prior work done by Valerie Chu from
+ Netscape Communications Corp, published as
+ draft-vchu-ldap-pwd-policy-00.txt (December 1998). Prasanta Behera
+ participated in early revisions of this document.
+
+15. Normative References
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [RFC2195] Klensin, J., Catoe, R., and P. Krumviede, "IMAP/POP
+ AUTHorize Extension for Simple Challenge/Response",
+ RFC 2195, September 1997.
+
+ [RFC2222] Myers, J., "Simple Authentication and Security Layer
+ (SASL)", RFC 2222, October 1997.
+
+ [RFC2251] Wahl, M., Howes, T., and S. Kille, "Lightweight Directory
+ Access Protocol (v3)", RFC 2251, December 1997.
+
+ [RFC2252] Wahl, M., Coulbeck, A., Howes, T., and S. Kille,
+ "Lightweight Directory Access Protocol (v3): Attribute
+ Syntax Definitions", RFC 2252, December 1997.
+
+ [RFC2829] Wahl, M., Alvestrand, H., Hodges, J., and R. Morgan,
+ "Authentication Methods for LDAP", RFC 2829, May 2000.
+
+ [RFC2831] Leach, P. and C. Newman, "Using Digest Authentication as a
+ SASL Mechanism", RFC 2831, May 2000.
+
+ [RFC3062] Zeilenga, K., "LDAP Password Modify Extended Operation",
+ RFC 3062, February 2001.
+
+ [RFC3383] Zeilenga, K., "Internet Assigned Numbers Authority (IANA)
+ Considerations for the Lightweight Directory Access
+ Protocol (LDAP)", BCP 64, RFC 3383, September 2002.
+
+ [RFC3672] Zeilenga, K., "Subentries in the Lightweight Directory
+ Access Protocol (LDAP)", RFC 3672, December 2003.
+
+ [X680] International Telecommunications Union, "Abstract Syntax
+ Notation One (ASN.1): Specification of basic notation",
+ ITU-T Recommendation X.680, July 2002.
+
+ [X690] International Telecommunications Union, "Information
+ Technology - ASN.1 encoding rules: Specification of Basic
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 39]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+ Encoding Rules (BER), Canonical Encoding Rules (CER) and
+ Distinguished Encoding Rules (DER)", ITU-T Recommendation
+ X.690, July 2002.
+
+
+Authors' Addresses
+
+ Jim Sermersheim
+ Novell, Inc
+ 1800 South Novell Place
+ Provo, Utah 84606
+ USA
+
+ Phone: +1 801 861-3088
+ Email: jimse at novell.com
+
+
+ Ludovic Poitou
+ Sun Microsystems
+ 180, Avenue de l'Europe
+ Zirst de Montbonnot, 38334 Saint Ismier cedex
+ France
+
+ Phone: +33 476 188 212
+ Email: ludovic.poitou at sun.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 40]
+
+Internet-Draft Password Policy for LDAP Directories July 2005
+
+
+Intellectual Property Statement
+
+ The IETF takes no position regarding the validity or scope of any
+ Intellectual Property Rights or other rights that might be claimed to
+ pertain to the implementation or use of the technology described in
+ this document or the extent to which any license under such rights
+ might or might not be available; nor does it represent that it has
+ made any independent effort to identify any such rights. Information
+ on the procedures with respect to rights in RFC documents can be
+ found in BCP 78 and BCP 79.
+
+ Copies of IPR disclosures made to the IETF Secretariat and any
+ assurances of licenses to be made available, or the result of an
+ attempt made to obtain a general license or permission for the use of
+ such proprietary rights by implementers or users of this
+ specification can be obtained from the IETF on-line IPR repository at
+ http://www.ietf.org/ipr.
+
+ The IETF invites any interested party to bring to its attention any
+ copyrights, patents or patent applications, or other proprietary
+ rights that may cover technology that may be required to implement
+ this standard. Please address the information to the IETF at
+ ietf-ipr at ietf.org.
+
+
+Disclaimer of Validity
+
+ This document and the information contained herein are provided on an
+ "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
+ OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
+ ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
+ INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
+ INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
+ WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+
+Copyright Statement
+
+ Copyright (C) The Internet Society (2005). This document is subject
+ to the rights, licenses and restrictions contained in BCP 78, and
+ except as set forth therein, the authors retain all their rights.
+
+
+Acknowledgment
+
+ Funding for the RFC Editor function is currently provided by the
+ Internet Society.
+
+
+
+
+Sermersheim & Poitou Expires January 18, 2006 [Page 41]
+
+
Added: openldap/vendor/openldap-release/doc/drafts/draft-chu-ldap-csn-xx.txt
===================================================================
--- openldap/vendor/openldap-release/doc/drafts/draft-chu-ldap-csn-xx.txt (rev 0)
+++ openldap/vendor/openldap-release/doc/drafts/draft-chu-ldap-csn-xx.txt 2008-06-28 09:29:58 UTC (rev 1147)
@@ -0,0 +1,424 @@
+
+
+
+
+
+
+INTERNET-DRAFT Howard Y. Chu
+Intended Category: Standard Track Symas Corporation
+Expires in six months 1 December 2004
+
+
+ Change Sequence Numbers for LDAP
+ <draft-chu-ldap-csn-00.txt>
+
+
+Status of this Memo
+
+ This document is an Internet-Draft and is in full conformance with all
+ provisions of Section 10 of RFC2026.
+
+ This document is intended to be, after appropriate review and
+ revision, submitted to the RFC Editor as an Standard Track document.
+ Distribution of this memo is unlimited. Technical discussion of this
+ document will take place on the IETF LDAP Extensions mailing list
+ <ldapext at ietf.org>. Please send editorial comments directly to the
+ author <Kurt at OpenLDAP.org>.
+
+ Internet-Drafts are working documents of the Internet Engineering Task
+ Force (IETF), its areas, and its working groups. Note that other
+ groups may also distribute working documents as Internet-Drafts.
+ Internet-Drafts are draft documents valid for a maximum of six months
+ and may be updated, replaced, or obsoleted by other documents at any
+ time. It is inappropriate to use Internet-Drafts as reference
+ material or to cite them other than as ``work in progress.''
+
+ The list of current Internet-Drafts can be accessed at
+ <http://www.ietf.org/ietf/1id-abstracts.txt>. The list of
+ Internet-Draft Shadow Directories can be accessed at
+ <http://www.ietf.org/shadow.html>.
+
+ Copyright (C) The Internet Society (2004). All Rights Reserved.
+
+ Please see the Full Copyright section near the end of this document
+ for more information.
+
+
+Abstract
+
+ This document describes the LDAP/X.500 Change Sequence Number 'CSN'
+ syntax and matching rules and associated attributes. CSNs are used
+ to impose a total ordering upon the sequence of updates applied
+ to a directory.
+
+
+
+
+Chu draft-chu-ldap-csn-00 [Page 1]
+
+INTERNET-DRAFT LDAP CSN 1 December 2004
+
+
+1. Background and Intended Use
+
+ In X.500 Directory Services [X.501], updates to a directory may need
+ to be distributed to multiple servers. The 'modifyTimeStamp' is already
+ defined for recording the time of an update, but it may be inadequate in
+ an environment where multiple servers with loosely synchronized clocks
+ are interoperating.
+
+ This document describes the 'CSN' syntax which augments a timestamp with
+ additional information to assist in coordinating updates among multiple
+ directory servers. This document describes the 'entryCSN' operational
+ attribute which carries the CSN of the last update applied to an entry
+ and also the 'contextCSN' operational attribute which carries the
+ greatest CSN of all updates applied to a directory context. Directory
+ clients and servers may use these attributes to assist in synchronizing
+ shadowed copies of directory information.
+
+ This document describes the 'csnMatch' and 'csnOrderingMatch' matching
+ rules corresponding to the 'CSN' syntax.
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in BCP 14 [RFC2119].
+
+ Schema definitions are provided using LDAP description formats
+ [RFC2252]. Definitions provided here are formatted (line wrapped) for
+ readability.
+
+
+2. CSN Schema Elements
+
+2.1 CSN Syntax
+
+ Values in this syntax are encoded according to the following BNF:
+
+ CSN = timestamp '#' operation-counter '#' replica-id
+
+ timestamp = <generalizedTimeString as specified in 6.14 of [RFC2252]>
+
+ operation-counter = 6hex-digit
+
+ replica-id = 2hex-digit
+
+ The timestamp SHALL use GMT and SHALL NOT include fractional seconds.
+
+ The operation-counter is set to zero at the start of each second, and
+ incremented by one for each update operation that occurs within that
+ second.
+
+ The replica-id is an identifier that represents a specific Replica in
+ a collection of cooperating servers.
+
+ The following is a LDAP syntax description [RFC2252] suitable for
+ publication in the subschema.
+
+ ( IANA-ASSIGNED-OID.1 DESC 'CSN' )
+
+
+
+
+
+Chu draft-chu-ldap-csn-00 [Page 2]
+
+INTERNET-DRAFT LDAP CSN 1 December 2004
+
+
+2.2 'csnMatch' Matching Rule
+
+ The 'csnMatch' matching rule compares an asserted CSN with a stored
+ CSN for equality. Its semantics are same as the octetStringMatch
+ [X.520][RFC2252] matching rule.
+
+ The following is a LDAP matching rule description [RFC2252] suitable
+ for publication in the subschema.
+
+ ( IANA-ASSIGNED-OID.2 NAME 'csnMatch'
+ SYNTAX IANA-ASSIGNED-OID.1 )
+
+
+2.3 'csnOrderingMatch' Matching Rule
+
+ The 'csnOrderingMatch' matching rule compares an asserted CSN
+ with a stored CSN for ordering. Its semantics are the same as the
+ octetStringOrderingMatch [X.520][RFC2252] matching rule.
+
+ The following is a LDAP matching rule description [RFC2252] suitable
+ for publication in the subschema.
+
+ ( IANA-ASSIGNED-OID.3 NAME 'csnOrderingMatch'
+ SYNTAX IANA-ASSIGNED-OID.1 )
+
+
+2.4. 'entryCSN' attribute
+
+ The 'entryCSN' operational attribute provides the CSN of the last
+ update applied to the entry.
+
+ The following is a LDAP attribute type description [RFC2252] suitable
+ for publication in the subschema.
+
+ ( IANA-ASSIGNED-OID.4 NAME 'entryCSN'
+ DESC 'CSN of the entry content'
+ EQUALITY csnMatch
+ ORDERING csnOrderingMatch
+
+
+
+Chu draft-chu-ldap-csn-00 [Page 3]
+
+INTERNET-DRAFT LDAP CSN 1 December 2004
+
+
+ SYNTAX IANA-ASSIGNED-OID.1
+ SINGLE-VALUE
+ NO-USER-MODIFICATION
+ USAGE directoryOperation )
+
+ Servers SHALL assign a CSN to each entry upon its addition to the
+ directory and provide the entry's CSN as the value of the
+ 'entryCSN' operational attribute. The entryCSN attribute SHOULD be
+ updated upon every update of the entry.
+
+2.5. 'contextCSN' attribute
+
+ The 'contextCSN' operational attribute provides the greatest CSN of
+ all the updates applied to a context.
+
+ The following is a LDAP attribute type description [RFC2252] suitable
+ for publication in the subschema.
+
+ ( IANA-ASSIGNED-OID.5 NAME 'contextCSN'
+ DESC 'the largest committed CSN of a context'
+ EQUALITY csnMatch
+ ORDERING csnOrderingMatch
+ SYNTAX IANA-ASSIGNED-OID.1
+ SINGLE-VALUE
+ NO-USER-MODIFICATION
+ USAGE directoryOperation )
+
+ Servers SHALL record the greatest CSN of all updates applied to a
+ context in the root entry of the context.
+
+
+3. Security Considerations
+
+
+ General LDAP security considerations [RFC3377] apply.
+
+
+4. IANA Considerations
+
+4.1. Object Identifier Registration
+
+ It is requested that IANA register upon Standards Action an LDAP
+ Object Identifier for use in this technical specification.
+
+ Subject: Request for LDAP OID Registration
+ Person & email address to contact for further information:
+ Howard Chu <hyc at symas.com>
+ Specification: RFC XXXX
+ Author/Change Controller: IESG
+ Comments:
+ Identifies the CSN schema elements
+
+
+4.2. Registration of the csnMatch descriptor
+
+ It is requested that IANA register upon Standards Action the LDAP
+ 'csnMatch' descriptor.
+
+ Subject: Request for LDAP Descriptor Registration
+ Descriptor (short name): csnMatch
+ Object Identifier: IANA-ASSIGNED-OID.2
+ Person & email address to contact for further information:
+ Howard Chu <hyc at symas.com>
+ Usage: Matching Rule
+ Specification: RFC XXXX
+ Author/Change Controller: IESG
+
+
+
+
+Chu draft-chu-ldap-csn-00 [Page 4]
+
+INTERNET-DRAFT LDAP CSN 1 December 2004
+
+
+4.3. Registration of the csnOrderingMatch descriptor
+
+ It is requested that IANA register upon Standards Action the LDAP
+ 'csnOrderingMatch' descriptor.
+
+ Subject: Request for LDAP Descriptor Registration
+ Descriptor (short name): csnOrderingMatch
+ Object Identifier: IANA-ASSIGNED-OID.3
+ Person & email address to contact for further information:
+ Howard Chu <hyc at symas.com>
+ Usage: Matching Rule
+ Specification: RFC XXXX
+ Author/Change Controller: IESG
+
+
+4.4. Registration of the entryCSN descriptor
+
+ It is requested that IANA register upon Standards Action the LDAP
+ 'entryCSN' descriptor.
+
+ Subject: Request for LDAP Descriptor Registration
+ Descriptor (short name): entryCSN
+ Object Identifier: IANA-ASSIGNED-OID.4
+ Person & email address to contact for further information:
+ Howard Chu <hyc at symas.com>
+ Usage: Attribute Type
+ Specification: RFC XXXX
+ Author/Change Controller: IESG
+
+
+4.5. Registration of the contextCSN descriptor
+
+ It is requested that IANA register upon Standards Action the LDAP
+ 'contextCSN' descriptor.
+
+ Subject: Request for LDAP Descriptor Registration
+ Descriptor (short name): contextCSN
+ Object Identifier: IANA-ASSIGNED-OID.5
+ Person & email address to contact for further information:
+ Howard Chu <hyc at symas.com>
+ Usage: Attribute Type
+ Specification: RFC XXXX
+ Author/Change Controller: IESG
+
+
+5. Acknowledgments
+
+ This document is based on prior work from the IETF LDUP working
+ group including the LDAP Replication Architecture [LDUPMODEL]
+ and the LDAP Content Synchronization Operation [LDUPSYNC].
+
+
+6. Author's Addresses
+
+ Howard Y. Chu
+ Symas Corporation
+ <hyc at symas.com>
+
+ Kurt D. Zeilenga
+ OpenLDAP Foundation
+ <Kurt at OpenLDAP.org>
+
+
+7. Normative References
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14 (also RFC 2119), March 1997.
+
+
+
+Chu draft-chu-ldap-csn-00 [Page 5]
+
+INTERNET-DRAFT LDAP CSN 1 December 2004
+
+
+ [RFC2252] Wahl, M., A. Coulbeck, T. Howes, and S. Kille,
+ "Lightweight Directory Access Protocol (v3): Attribute
+ Syntax Definitions", RFC 2252, December 1997.
+
+ [RFC3377] Hodges, J. and R. Morgan, "Lightweight Directory Access
+ Protocol (v3): Technical Specification", RFC 3377,
+ September 2002.
+
+ [X.501] International Telecommunication Union -
+ Telecommunication Standardization Sector, "The Directory
+ -- Models," X.501(1993) (also ISO/IEC 9594-2:1994).
+
+ [X.520] International Telecommunication Union -
+ Telecommunication Standardization Sector, "The
+ Directory: Selected Attribute Types", X.520(1993) (also
+ ISO/IEC 9594-6:1994).
+
+ [X.680] International Telecommunication Union -
+ Telecommunication Standardization Sector, "Abstract
+ Syntax Notation One (ASN.1) - Specification of Basic
+ Notation", X.680(1997) (also ISO/IEC 8824-1:1998).
+
+ [LDUPSYNC] Zeilenga, K. and Choi, J-H "LDAP Content Synchronization
+ Operation", draft-zeilenga-ldup-sync-05.txt, a work in
+ progress.
+
+
+8. Informative References
+
+ [RFC3383] Zeilenga, K., "IANA Considerations for LDAP", BCP 64
+ (also RFC 3383), September 2002.
+
+ [LDUPMODEL] Merrellls, J., Srinivasan, U., and Reed, E., "LDAP
+ Replication Architecture", draft-ietf-ldup-model-09.txt.
+
+
+
+Intellectual Property Rights
+
+ The IETF takes no position regarding the validity or scope of any
+
+
+
+Chu draft-chu-ldap-csn-00 [Page 6]
+
+INTERNET-DRAFT LDAP CSN 1 December 2004
+
+
+ intellectual property or other rights that might be claimed to pertain
+ to the implementation or use of the technology described in this
+ document or the extent to which any license under such rights might or
+ might not be available; neither does it represent that it has made any
+ effort to identify any such rights. Information on the IETF's
+ procedures with respect to rights in standards-track and
+ standards-related documentation can be found in BCP-11. Copies of
+ claims of rights made available for publication and any assurances of
+ licenses to be made available, or the result of an attempt made to
+ obtain a general license or permission for the use of such proprietary
+ rights by implementors or users of this specification can be obtained
+ from the IETF Secretariat.
+
+ The IETF invites any interested party to bring to its attention any
+ copyrights, patents or patent applications, or other proprietary
+ rights which may cover technology that may be required to practice
+ this standard. Please address the information to the IETF Executive
+ Director.
+
+
+
+Full Copyright
+
+ Copyright (C) The Internet Society (2004). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implmentation may be prepared, copied, published and
+ distributed, in whole or in part, without restriction of any kind,
+ provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be followed,
+ or as required to translate it into languages other than English.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Chu draft-chu-ldap-csn-00 [Page 7]
+
Added: openldap/vendor/openldap-release/doc/drafts/draft-haripriya-dynamicgroup-xx.txt
===================================================================
--- openldap/vendor/openldap-release/doc/drafts/draft-haripriya-dynamicgroup-xx.txt (rev 0)
+++ openldap/vendor/openldap-release/doc/drafts/draft-haripriya-dynamicgroup-xx.txt 2008-06-28 09:29:58 UTC (rev 1147)
@@ -0,0 +1,1400 @@
+
+
+
+Network Working Group S. Haripriya
+Internet-Draft Jaimon. Jose, Ed.
+Updates: 02 (if approved) Jim. Sermersheim
+Intended status: Standards Track Novell, Inc.
+Expires: July 9, 2007 January 5, 2007
+
+
+ LDAP: Dynamic Groups for LDAPv3
+ draft-haripriya-dynamicgroup-02
+
+Status of this Memo
+
+ By submitting this Internet-Draft, each author represents that any
+ applicable patent or other IPR claims of which he or she is aware
+ have been or will be disclosed, and any of which he or she becomes
+ aware will be disclosed, in accordance with Section 6 of BCP 79.
+
+ Internet-Drafts are working documents of the Internet Engineering
+ Task Force (IETF), its areas, and its working groups. Note that
+ other groups may also distribute working documents as Internet-
+ Drafts.
+
+ Internet-Drafts are draft documents valid for a maximum of six months
+ and may be updated, replaced, or obsoleted by other documents at any
+ time. It is inappropriate to use Internet-Drafts as reference
+ material or to cite them other than as "work in progress."
+
+ The list of current Internet-Drafts can be accessed at
+ http://www.ietf.org/ietf/1id-abstracts.txt.
+
+ The list of Internet-Draft Shadow Directories can be accessed at
+ http://www.ietf.org/shadow.html.
+
+ This Internet-Draft will expire on July 9, 2007.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (2007).
+
+
+
+
+
+
+
+
+
+
+
+
+
+Haripriya, et al. Expires July 9, 2007 [Page 1]
+
+Internet-Draft LDAP: Dynamic Groups for LDAPv3 January 2007
+
+
+Abstract
+
+ This document describes the requirements, semantics, schema elements,
+ and operations needed for a dynamic group feature in LDAP. A dynamic
+ group is defined here as a group object with a membership list of
+ distinguished names that is dynamically generated using LDAP search
+ criteria. The dynamic membership list may then be interrogated by
+ LDAP search and compare operations, and may also be used to find the
+ groups that an object is a member of. This feature eliminates a huge
+ amount of the administrative effort required today for maintaining
+ group memberships and role-based operations in large enterprises.
+
+
+Table of Contents
+
+ 1. Conventions used in this document . . . . . . . . . . . . . . 4
+ 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5
+ 3. Requirements of a dynamic group feature . . . . . . . . . . . 6
+ 4. Schema and Semantic Definitions for Dynamic Groups . . . . . . 7
+ 4.1. Object Classes . . . . . . . . . . . . . . . . . . . . . . 7
+ 4.1.1. dynamicGroup . . . . . . . . . . . . . . . . . . . . . 7
+ 4.1.2. dynamicGroupOfUniqueNames . . . . . . . . . . . . . . 7
+ 4.1.3. dynamicGroupAux . . . . . . . . . . . . . . . . . . . 7
+ 4.1.4. dynamicGroupOfUniqueNamesAux . . . . . . . . . . . . . 7
+ 4.2. Attributes . . . . . . . . . . . . . . . . . . . . . . . . 8
+ 4.2.1. memberQueryURL . . . . . . . . . . . . . . . . . . . . 8
+ 4.2.2. excludedMember . . . . . . . . . . . . . . . . . . . . 11
+ 4.3. member . . . . . . . . . . . . . . . . . . . . . . . . . . 11
+ 4.4. uniqueMember . . . . . . . . . . . . . . . . . . . . . . . 11
+ 4.5. dgIdentity . . . . . . . . . . . . . . . . . . . . . . . . 11
+ 4.5.1. dgIdentity - Security implications . . . . . . . . . . 12
+ 5. Advertisement of support for dynamic groups . . . . . . . . . 13
+ 6. Dynamic Group Operations . . . . . . . . . . . . . . . . . . . 14
+ 6.1. Existing Operations . . . . . . . . . . . . . . . . . . . 14
+ 6.1.1. Access to resources in the directory . . . . . . . . . 14
+ 6.1.2. Reading a dynamic group object . . . . . . . . . . . . 14
+ 6.1.3. 'Is Member Of' functionality . . . . . . . . . . . . . 15
+ 6.2. New Extensions . . . . . . . . . . . . . . . . . . . . . . 16
+ 6.2.1. Managing the static members of a dynamic group . . . . 16
+ 7. Performance Considerations . . . . . . . . . . . . . . . . . . 17
+ 7.1. Caching of Dynamic Members . . . . . . . . . . . . . . . . 17
+ 8. Security Considerations . . . . . . . . . . . . . . . . . . . 18
+ 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19
+ 10. Conclusions . . . . . . . . . . . . . . . . . . . . . . . . . 20
+ 11. Normative References . . . . . . . . . . . . . . . . . . . . . 21
+ Appendix A. Example Values for memberQueryURL . . . . . . . . . . 22
+ Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . . 23
+ Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 24
+
+
+
+Haripriya, et al. Expires July 9, 2007 [Page 2]
+
+Internet-Draft LDAP: Dynamic Groups for LDAPv3 January 2007
+
+
+ Intellectual Property and Copyright Statements . . . . . . . . . . 25
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Haripriya, et al. Expires July 9, 2007 [Page 3]
+
+Internet-Draft LDAP: Dynamic Groups for LDAPv3 January 2007
+
+
+1. Conventions used in this document
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in [1].
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Haripriya, et al. Expires July 9, 2007 [Page 4]
+
+Internet-Draft LDAP: Dynamic Groups for LDAPv3 January 2007
+
+
+2. Introduction
+
+ The LDAP schema described in [4] defines two object classes:
+ 'groupOfNames', and 'groupOfUniqueNames', that hold a static list of
+ distinguished names in their 'member' or 'uniqueMember' attributes
+ respectively, and are typically used to describe a group of objects
+ for various functions. These grouping functions range from simple
+ group membership applications such as email distribution lists to
+ describing common authorization for a set of users The administration
+ and updating of these membership lists must be done by specifically
+ modifying the DN values in the member or uniqueMember attributes.
+ Thus, each time a change in membership happens, a process must exist
+ which adds or removes the particular entry's DN from the member
+ attribute. For example, consider an organization, where the access
+ to its facilities is controlled by membership in a directory group.
+ Assume that all employees in a department have been added to the
+ group that provides access to the required department facility. If
+ an employee moves from one department to another, the administrator
+ must remove the employee from one group and add him to another.
+ Similarly consider an organization that wants to provide access to
+ its facility, to both interns and employees on weekdays, but only to
+ employees on weekends. It would be effort-consuming to achieve this
+ with static groups.
+
+ "Dynamic groups" are like normal groups, but they let one specify
+ criteria to be used for evaluating membership to a group; the
+ membership of the group is determined dynamically by the directory
+ servers involved. This lets the group administrator define the
+ membership in terms of attributes, and let the DSAs worry about who
+ are the actual members. This solution is more scalable and reduces
+ administrative costs. This can also supplement static groups in LDAP
+ to provide flexibility to the user.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Haripriya, et al. Expires July 9, 2007 [Page 5]
+
+Internet-Draft LDAP: Dynamic Groups for LDAPv3 January 2007
+
+
+3. Requirements of a dynamic group feature
+
+ The following requirements SHOULD be met by a proposal for the
+ dynamic groups feature:
+
+ 1. Creation and administration of dynamic groups should be done
+ using normal LDAP operations.
+
+ 2. Applications must be able to use dynamic groups in the same way
+ that they are able to use static groups for listing members and
+ for membership evaluation.
+
+ 3. Interrogation of a dynamic group's membership should be done
+ using normal LDAP operations, and should be consistent. This
+ means that all authorization identities with the same permission
+ to the membership attribute of a dynamic group (such as 'read')
+ should be presented with the same membership list.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Haripriya, et al. Expires July 9, 2007 [Page 6]
+
+Internet-Draft LDAP: Dynamic Groups for LDAPv3 January 2007
+
+
+4. Schema and Semantic Definitions for Dynamic Groups
+
+ The dynamic group classes are defined by the following schema
+
+4.1. Object Classes
+
+ The following object classes MUST be supported, and their semantics
+ understood by the server, for it to support the dynamic groups
+ feature.
+
+4.1.1. dynamicGroup
+
+ ( <OID.TBD> NAME 'dynamicGroup' SUP groupOfNames STRUCTURAL MAY
+ (memberQueryURL $ excludedMember $ dgIdentity ))
+
+ This structural object class is used to create a dynamic group
+ object. It is derived from groupOfNames, which is defined in [4].
+
+4.1.2. dynamicGroupOfUniqueNames
+
+ ( <OID.TBD> NAME 'dynamicGroupOfUniqueNames' SUP groupOfUniqueNames
+ STRUCTURAL MAY (memberQueryURL $ excludedMember $ dgIdentity ))
+
+ This structural object class is used to create a dynamic group object
+ whose membership list is held in a uniqueMember attribute. It is
+ derived from groupOfUniqueNames, which is defined in [4].
+
+4.1.3. dynamicGroupAux
+
+ ( <OID.TBD> NAME 'dynamicGroupAux' SUP groupOfNames AUXILIARY MAY
+ (memberQueryURL $ excludedMember $ dgIdentity ))
+
+ This auxiliary object class is used to convert an existing object to
+ a dynamic group or to create an object of another object class but
+ with dynamic group capabilities. This is derived from groupOfNames
+ which is defined in [4].
+
+4.1.4. dynamicGroupOfUniqueNamesAux
+
+ ( <OID.TBD> NAME 'dynamicGroupOfUniqueNamesAux' SUP groupOfUniqueNames
+ AUXILIARY MAY (memberQueryURL $ excludedMember $ dgIdentity ))
+
+ This auxiliary object class is used to convert an existing object to
+ a dynamic group of unique names or to create an object of another
+ object class but with dynamic group capabilities. This is derived
+ from groupOfUniqueNames which is defined in [4].
+
+
+
+
+
+Haripriya, et al. Expires July 9, 2007 [Page 7]
+
+Internet-Draft LDAP: Dynamic Groups for LDAPv3 January 2007
+
+
+4.2. Attributes
+
+ The following attribute names MUST be supported by the server.
+
+4.2.1. memberQueryURL
+
+ This attribute describes the membership of the list using an LDAPURL
+ [3].
+
+ (<OID.TBD> NAME 'memberQueryURL' SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
+
+ The value of memberQueryURL is encoded as an LDAPURL [3]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Haripriya, et al. Expires July 9, 2007 [Page 8]
+
+Internet-Draft LDAP: Dynamic Groups for LDAPv3 January 2007
+
+
+ The BNF from [3] is listed here for reference.
+ldapurl = scheme COLON SLASH SLASH [host [COLON port]] [SLASH dn
+ [QUESTION [attributes] [QUESTION [scope] [QUESTION [filter] [QUESTION
+ extensions]]]]]
+ ; <host> and <port> are defined
+ ; in Sections 3.2.2 and 3.2.3
+ ; of [RFC3986].
+ ; <filter> is from Section 3 of
+ ; [RFC4515], subject to the
+ ; provisions of the
+ ; "Percent-Encoding" section
+ ; below.
+scheme = "ldap"
+dn = distinguishedName ; From Section 3 of [RFC4514],
+ ; subject to the provisions of
+ ; the "Percent-Encoding"
+ ; section below.
+attributes = attrdesc *(COMMA attrdesc)
+attrdesc = selector *(COMMA selector)
+selector = attributeSelector ; From Section 4.5.1 of
+ ; [RFC4511], subject to the
+ ; provisions of the
+ ; "Percent-Encoding" section
+ ; below.
+scope = "base" / "one" / "sub"
+extensions = extension *(COMMA extension)
+extension = [EXCLAMATION] extype [EQUALS exvalue]
+extype = oid ; From section 1.4 of [RFC4512].
+exvalue = LDAPString ; From section 4.1.2 of
+ ; [RFC4511], subject to the
+ ; provisions of the
+ ; "Percent-Encoding" section
+ ; below.
+EXCLAMATION = %x21 ; exclamation mark ("!")
+SLASH = %x2F ; forward slash ("/")
+COLON = %x3A ; colon (":")
+QUESTION = %x3F ; question mark ("?")
+
+
+ For the purpose of evaluating dynamic members, the directory server
+ uses only the dn, scope, filter and extensions fields. All remaining
+ fields are ignored if specified. If other fields are specified, the
+ server SHALL ignore them and MAY omit them when presenting the value
+ to a client. The dn is used to specify the base dn from which to
+ start the search for dynamic members. The scope specifies the scope
+ with respect to the dn in which to search for dynamic members. The
+ filter specifies the criteria with which to select objects for
+ dynamic membership.
+
+
+
+Haripriya, et al. Expires July 9, 2007 [Page 9]
+
+Internet-Draft LDAP: Dynamic Groups for LDAPv3 January 2007
+
+
+4.2.1.1. The x-chain extension
+
+ A new extension is defined for use of the memberQueryURL in dynamic
+ groups, named 'x-chain'. x-chain does not take a value. When x-chain
+ is present, the server must follow any search continuation references
+ to other servers while searching for dynamic members. When x-chain
+ is absent, the dynamic members computed will be only those that are
+ present on the server from which the search is made. A directory
+ server supporting the memberQueryURL MAY support the x-chain
+ extension, thus the x-chain extension could be critical or non-
+ critical as specified by the '!' prefix to the extension type.
+
+4.2.1.2. Semantics of multiple values for memberQueryURL
+
+ The memberQueryURL MAY have multiple values, and in that case, the
+ members of the dynamic group will be the union of the members
+ computed using each individual URL value. This is useful in
+ specifying a group membership that is made up from subtrees rooted at
+ different base DNs, and possibly using different filters.
+
+4.2.1.3. Condition of membership
+
+ An object O is a member of a dynamic group G if and only if
+
+ (( O is a value of the 'member' or 'uniqueMember' attribute of G)
+
+ OR
+
+ (( O is selected by the membership criteria specified in the
+ 'memberQueryURL' attribute values of G)
+
+ AND
+
+ ( O is not listed in the 'excludedMember' attribute of G) ))
+
+ If a member M of a dynamic group G happens to be a dynamic or a
+ static group, the static or dynamic members of M SHALL NOT be
+ considered as members of G. M is a member of G though.
+
+ The last condition is imposed because
+
+ o Recursively evaluating members of members may degrade the
+ performance of the server drastically.
+
+ o Looping may occur particularly in situations where the search
+ chains across multiple-servers.
+
+
+
+
+
+Haripriya, et al. Expires July 9, 2007 [Page 10]
+
+Internet-Draft LDAP: Dynamic Groups for LDAPv3 January 2007
+
+
+ o Dynamic membership assertions (compare operation) cannot be
+ optimized if recursive memberships are allowed. Without
+ recursion, comparisons can be made light-weight.
+
+4.2.2. excludedMember
+
+ ( <OID.TBD> NAME 'excludedMember' SUP distinguishedName )
+
+ This attribute is used to exclude entries from being a dynamic member
+ of a dynamic group. Thus an entry is a dynamic member of a dynamic
+ group if and only if it is selected by the member criteria specified
+ by the 'memberQueryURL' attribute or explicitly added to the member
+ or uniqueMember attribute, and it is not listed in the
+ 'excludedMember' attribute.
+
+4.3. member
+
+ ( 2.5.4.31 NAME 'member' SUP distinguishedName )
+
+ Defined in [4], this attribute is overloaded when used in the context
+ of a dynamic group. It is used to explicitly specify static members
+ of a dynamic group. If the same entry is listed in both the 'member'
+ and 'excludedMember' attributes, the 'member' overrides the
+ 'excludedMember', and the entry is considered to be a member of the
+ group. This attribute is also used to interrogate both the static
+ and dynamic member values of a dynamic group object. Subclasses of
+ this attribute are NOT considered in this manner.
+
+4.4. uniqueMember
+
+ ( 2.5.4.32 NAME 'uniqueMember' SUP distinguishedName )
+
+ Defined in [4], this attribute is overloaded when used in the context
+ of a dynamic group. It is used to specify the static members of a
+ dynamic group. If the same entry is listed in both the
+ 'uniqueMember' and 'excludedMember' attributes, the 'uniqueMember'
+ overrides the 'excludedMember', and the entry is considered to be a
+ member of the group. This attribute is also used to interrogate both
+ the static and dynamic member values of a dynamic group object.
+ Subclasses of this attribute are NOT considered in this manner.
+
+4.5. dgIdentity
+
+ ( <OID.TBD> NAME 'identity' SUP distinguishedName SINGLE-VALUE )
+
+ In order to provide consistent results when processing the search
+ criteria, the server must use a single authorization identity. If
+ the authorization of the bound identity is used, the membership list
+
+
+
+Haripriya, et al. Expires July 9, 2007 [Page 11]
+
+Internet-Draft LDAP: Dynamic Groups for LDAPv3 January 2007
+
+
+ will vary, from identity to identity due to differing access
+ controls. This may either be done by the server authenticating as
+ the dgIdentity prior to performing a search or compare operation, or
+ may be done by simply assuming the authorization of the dgIdentity
+ when performing those operations. As server implementations vary, so
+ may the mechanisms to achieve consistent results through the use of
+ the dgIdentity. In the case that the server authenticates as the
+ dgIdentity, it may be required by the server that this identity have
+ proper authentication credentials, and it may be required that this
+ identity reside in the DIB of the local server.
+
+ In the absence of an identity value, or in case the identity value
+ cannot be used, the server will process the memberQueryURL as the
+ anonymous identity. This attribute MAY be supported, and represents
+ the identity the server will use for processing the memberQueryURL.
+
+4.5.1. dgIdentity - Security implications
+
+ Because this attribute indirectly but effectively grants anyone with
+ read or compare access to the member or uniqueMember attribute
+ sufficient permission to gain a DN result set from the
+ memberQueryURL, server implementations SHOULD NOT allow this
+ attribute to be populated with the DN of any object that is not
+ administered by the identity making the change to this attribute.
+ For purposes of this document, to "administer an object" indicates
+ that the administrative identity has the ability to fully update the
+ access control mechanism in place the object in question. As of this
+ writing, there is no way to describe further what it means to be
+ fully able to administer the access control mechanism for an object,
+ so this definition is left as implementation-specific.
+
+ This requirement will allow an entity that has privileges to
+ administer a particular subtree (meaning that entity can add, delete,
+ and update objects in that subtree), to place in the dgIdentity DNs
+ of only those objects it administers.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Haripriya, et al. Expires July 9, 2007 [Page 12]
+
+Internet-Draft LDAP: Dynamic Groups for LDAPv3 January 2007
+
+
+5. Advertisement of support for dynamic groups
+
+ If the dynamic groups schema is not present on an LDAP server, it
+ MUST be assumed that the dynamic groups feature is not supported.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Haripriya, et al. Expires July 9, 2007 [Page 13]
+
+Internet-Draft LDAP: Dynamic Groups for LDAPv3 January 2007
+
+
+6. Dynamic Group Operations
+
+6.1. Existing Operations
+
+ The following operations SHOULD expose the dynamic groups
+ functionality. These operations do not require any change in the
+ LDAP protocol to be exchanged between the client and server.
+
+6.1.1. Access to resources in the directory
+
+ If access control items are set on a target resource object in the
+ directory, with the subject being a dynamic group object, then all
+ the members of the group object, including the dynamic members, will
+ get the same permissions on the target entry. This would be the most
+ useful application of dynamic groups as seen by an administrator
+ because it lets the server control access to resources based on
+ dynamic membership to a trustee (subject of ACI) of the resource.
+ The way to specify a dynamic ACL is currently implementation
+ specific, as there is no common ACL definition for LDAP, and hence
+ will be dealt with in a separate document or later (TO BE DONE).
+
+6.1.2. Reading a dynamic group object
+
+ When the member attributes of a dynamic group object is listed by the
+ client using an LDAP search operation, the member values returned
+ SHOULD contain both the static and dynamic members of the group
+ object. This functionality will not require a change to the
+ protocol, and the clients need not be aware of dynamic groups to
+ exploit this functionality. This feature is useful for clients that
+ determine access privileges to a resource by themselves, by reading
+ the members of a group object. It will also be useful to
+ administrators who want to see the result of the query URL that they
+ set on the dynamic group entry. Note that this overloads the
+ semantics of the 'member' and 'uniqueMember' attributes. This could
+ lead to some surprises for the client .
+
+ for example: Clients that read the member attribute of a dynamic
+ group object and then attempt to remove values (which were dynamic)
+ could get an error specifying such a value was not there.
+
+ Example:
+
+ Let cn=dg1,o=myorg be a dynamic group object with the following
+ attributes stored in the directory.
+
+
+
+
+
+
+
+Haripriya, et al. Expires July 9, 2007 [Page 14]
+
+Internet-Draft LDAP: Dynamic Groups for LDAPv3 January 2007
+
+
+ member: cn=admin,o=myorg
+
+ excludedMember: cn=guest,ou=finance,o=myorg
+
+ excludedMember: cn=robin,ou=finance,o=myorg
+
+ memberQueryURL:
+ ldap:///ou=finance,o=myorg??sub?(objectclass=organizationalPerson)
+
+ If there are 5 organizationalPerson objects under ou=finance,o=myorg
+ with common names bob, alice, john, robin, and guest, then the output
+ of a base-scope LDAP search at cn=dg1,o=myorg, with the attribute
+ list containing 'member' will be as follows:
+
+ dn: cn=dg1,o=myorg
+
+ member: cn=admin,o=myorg
+
+ member: cn=bob,ou=finance,o=myorg
+
+ member: cn=alice,ou=finance,o=myorg
+
+ member: cn=john,ou=finance,o=myorg
+
+6.1.3. 'Is Member Of' functionality
+
+ The LDAP compare operation allows one to discover whether a given DN
+ is in the membership list of a dynamic group. Again, the server
+ SHOULD produce consistent results among different authorization
+ identities when processing this request, as long as those identities
+ have the same access to the member or uniqueMember attribute. Using
+ the data from the example in Section 6.1.2, a compare on
+ cn=dg1,o=myorg, for the AVA member=cn=bob,ou=finance,o=myorg would
+ result in a response of compareTrue (assuming the bound identity was
+ authorized to compare the member attribute of cn=dg1,o=myorg).
+
+ Likewise, a search operation that contains an equalityMatch or
+ presence filter, naming the member or uniqueMember attribute as the
+ attribute (such as (member= cn=bob,ou=finance,o=myorg), or
+ (member=*)), will cause the server to evaluate this filter against
+ the rules given in Section 4.2.1.3 in the event that the search is
+ performed on a dynamic group object. As of this writing, no other
+ matching rules exist for the distinguished name syntax, thus no
+ requirements beyond equalityMatch are given here.
+
+
+
+
+
+
+
+Haripriya, et al. Expires July 9, 2007 [Page 15]
+
+Internet-Draft LDAP: Dynamic Groups for LDAPv3 January 2007
+
+
+6.2. New Extensions
+
+ The following new extensions are added for dynamic group support.
+
+6.2.1. Managing the static members of a dynamic group
+
+ Because a dynamic group overloads the semantics of the member and
+ uniqueMember attributes, a mechanism is needed to retrieve the static
+ values found in these attributes for management purposes. To serve
+ this need, a new attribute option is defined here called 'x-static'.
+ Attribute options are discussed in Section 2.5 of [2]. This option
+ SHALL only be specified with the 'member' or 'uniqueMember'
+ attribute. When the LDAP server does not understand the semantics of
+ this option on a given attribute, the option SHOULD be ignored. This
+ attribute option is only used to affect the transmitted values, and
+ does not impose sub-typing semantics on the attribute.
+
+ This option MAY be specified by a client during a search request in
+ the list of attributes to be returned, i.e. member;x-static. In this
+ case, the server SHALL only return those members of the dynamic group
+ that are statically listed as values of the member or uniqueMember
+ attribute. The evaluation process listed in Section 9 SHALL NOT be
+ used to populate the values to be returned.
+
+ This option MAY be specified is either an equalityMatch or presence
+ search filter. In this case, the server evaluates only the values
+ statically listed in the member or uniqueMember attribute, and does
+ not apply the evaluation process listed in Section 9.
+
+ This option MAY be specified in update operations such as add and
+ modify, but SHOULD be ignored, as its presence is semantically the
+ same as its non-presence.
+
+ Note to user: Performing a search to read a dynamic group, with a
+ filter item such as (member=*), and specifying member;x-static, may
+ result in a search result entry that has no member attribute. This
+ may seem counter-intuitive.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Haripriya, et al. Expires July 9, 2007 [Page 16]
+
+Internet-Draft LDAP: Dynamic Groups for LDAPv3 January 2007
+
+
+7. Performance Considerations
+
+ When the x-chain extension is present on the memberQueryURL, the
+ server MUST follow any search continuation references to other
+ servers while searching for dynamic members. This may be expensive
+ and slow in a true distributed environment. The dynamicGroup
+ implementation can consider a distributed caching feature to improve
+ the performance. An outline of such a distributed caching is given
+ below.
+
+7.1. Caching of Dynamic Members
+
+ Since the dynamic members of a group are computed every time the
+ group is accessed, the performance could be affected. An
+ implementation of dynamic groups can get around this problem by
+ caching the computed members of a dynamic group locally and using the
+ cached data subsequently. One way to do this is to create pseudo-
+ objects for each dynamic group on every server that holds an object
+ that is a dynamic member of the group. With this, the computation of
+ the dynamic members of a group reduces to the task of reading the
+ pseudo-objects from each server. These pseudo-objects need to be
+ linked from the original dynamic group to speed up the member
+ computation. Also, since these are cached objects, appropriate
+ timeouts need to be associated with the cache after which the cache
+ should be invalidated or refreshed
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Haripriya, et al. Expires July 9, 2007 [Page 17]
+
+Internet-Draft LDAP: Dynamic Groups for LDAPv3 January 2007
+
+
+8. Security Considerations
+
+ This document discusses the use of one object as the identity
+ (Section 4.5) with which to read information for another object. If
+ the creation of the dgIdentity attribute is uncontrolled, an intruder
+ could potentially create a dynamic group with the identity of, say,
+ the administrator, to be able to read the directory as the
+ administrator, and see information which would be otherwise
+ unavailable to him. Thus, a person adding an object as identity of a
+ dynamic group should have appropriate permissions on the object being
+ added as identity.
+
+ This document also discusses using dynamic memberships to provide
+ access for resources in a directory. As the dynamic members are not
+ created by the administrator, there could be surprises for the
+ administrator in the form of certain objects getting access to
+ certain resources through dynamic membership, which the administrator
+ never intended. So the administrator should be wary of such
+ problems. The administrator could view the memberships and make sure
+ that anybody who is not supposed to be a member of a group is added
+ to the excludedMember list.
+
+ Denial of service attacks can be launched on an LDAP server, by
+ repeatedly searching for a dynamic group with a large membership list
+ and listing the member attribute. A more effective form of denial of
+ service attack could be launched by making searches of the form
+ (member="somedn") at the top of tree and closing the client
+ connection as soon as the search starts. Some administrative limits
+ be imposed to avoid such situations.
+
+ The dynamic groups feature could be potentially misused by a user to
+ circumvent any administrative size-limit restriction placed on the
+ server. In order to search an LDAP server and obtain the names of
+ all the objects on the server irrespective of admin size-limit
+ restriction on the server, the LDAP user could create a dynamic group
+ with a memberQueryURL which matches all objects in the tree, and list
+ just that one object.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Haripriya, et al. Expires July 9, 2007 [Page 18]
+
+Internet-Draft LDAP: Dynamic Groups for LDAPv3 January 2007
+
+
+9. IANA Considerations
+
+ There are no IANA considerations.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Haripriya, et al. Expires July 9, 2007 [Page 19]
+
+Internet-Draft LDAP: Dynamic Groups for LDAPv3 January 2007
+
+
+10. Conclusions
+
+ This document discusses the syntax, semantics and usage of dynamic
+ groups in LDAPv3.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Haripriya, et al. Expires July 9, 2007 [Page 20]
+
+Internet-Draft LDAP: Dynamic Groups for LDAPv3 January 2007
+
+
+11. Normative References
+
+ [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement
+ Levels", BCP 14, RFC 2119, March 1997.
+
+ [2] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP):
+ Directory Information Models", RFC 4512, June 2006.
+
+ [3] Smith, M. and T. Howes, "Lightweight Directory Access Protocol
+ (LDAP): Uniform Resource Locator", RFC 4516, June 2006.
+
+ [4] Sciberras, A., "Lightweight Directory Access Protocol (LDAP):
+ Schema for User Applications", RFC 4519, June 2006.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Haripriya, et al. Expires July 9, 2007 [Page 21]
+
+Internet-Draft LDAP: Dynamic Groups for LDAPv3 January 2007
+
+
+Appendix A. Example Values for memberQueryURL
+
+ 1. This memberQueryURL value specifies the membership criteria for a
+ dynamic group entry as "all inetorgperson entries that also have
+ their title attribute set to 'manager', and are in the DIT-wide
+ subtree under ou=hr,o=myorg ".
+
+ memberQueryURL: ldap:///
+ ou=hr,o=myorg??sub?(&
+ (objectclass=inetorgperson)(title=manager))? x-chain
+
+ 2. This value lets the user specify the membership criteria for a
+ dynamic group entry as "all entries on the local server, that
+ either have unix accounts or belong to the unix department, and
+ are under the engineering container ".
+
+ memberQueryURL: ldap:///ou=eng,o=myorg??sub?
+ (|(objectclass=posixaccount)(department=unix))
+
+ 3. These values let the user specify the membership criteria as "all
+ inetorgperson entries on the local server, in either the
+ ou=eng,o=myorg or ou=support,o=myorg" subtrees.
+
+ memberQueryURL:
+ ldap:///ou=eng,o=myorg??sub?(objectclass=inetorgperson)
+
+ memberQueryURL:
+ ldap:///ou=support,o=myorg??sub?(objectclass=inetorgperson)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Haripriya, et al. Expires July 9, 2007 [Page 22]
+
+Internet-Draft LDAP: Dynamic Groups for LDAPv3 January 2007
+
+
+Appendix B. Acknowledgments
+
+ Funding for the RFC Editor function is currently provided by the
+ Internet Society.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Haripriya, et al. Expires July 9, 2007 [Page 23]
+
+Internet-Draft LDAP: Dynamic Groups for LDAPv3 January 2007
+
+
+Authors' Addresses
+
+ Haripriya S
+ Novell, Inc.
+ 49/1 & 49/3 Garvebhavi Palya,
+ 7th Mile, Hosur Road
+ Bangalore, Karnataka 560068
+ India
+
+ Email: sharipriya at novell.com
+
+
+ Jaimon Jose (editor)
+ Novell, Inc.
+ 49/1 & 49/3 Garvebhavi Palya,
+ 7th Mile, Hosur Road
+ Bangalore, Karnataka 560068
+ India
+
+ Email: jjaimon at novell.com
+
+
+ Jim Sermersheim
+ Novell, Inc.
+ 1800 South Novell Place
+ Provo, Utah 84606
+ US
+
+ Email: jimse at novell.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Haripriya, et al. Expires July 9, 2007 [Page 24]
+
+Internet-Draft LDAP: Dynamic Groups for LDAPv3 January 2007
+
+
+Full Copyright Statement
+
+ Copyright (C) The Internet Society (2007).
+
+ This document is subject to the rights, licenses and restrictions
+ contained in BCP 78, and except as set forth therein, the authors
+ retain all their rights.
+
+ This document and the information contained herein are provided on an
+ "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
+ OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
+ ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
+ INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
+ INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
+ WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+
+Intellectual Property
+
+ The IETF takes no position regarding the validity or scope of any
+ Intellectual Property Rights or other rights that might be claimed to
+ pertain to the implementation or use of the technology described in
+ this document or the extent to which any license under such rights
+ might or might not be available; nor does it represent that it has
+ made any independent effort to identify any such rights. Information
+ on the procedures with respect to rights in RFC documents can be
+ found in BCP 78 and BCP 79.
+
+ Copies of IPR disclosures made to the IETF Secretariat and any
+ assurances of licenses to be made available, or the result of an
+ attempt made to obtain a general license or permission for the use of
+ such proprietary rights by implementers or users of this
+ specification can be obtained from the IETF on-line IPR repository at
+ http://www.ietf.org/ipr.
+
+ The IETF invites any interested party to bring to its attention any
+ copyrights, patents or patent applications, or other proprietary
+ rights that may cover technology that may be required to implement
+ this standard. Please address the information to the IETF at
+ ietf-ipr at ietf.org.
+
+
+Acknowledgment
+
+ Funding for the RFC Editor function is provided by the IETF
+ Administrative Support Activity (IASA).
+
+
+
+
+
+Haripriya, et al. Expires July 9, 2007 [Page 25]
+
Added: openldap/vendor/openldap-release/doc/drafts/draft-ietf-ldapext-acl-model-xx.txt
===================================================================
--- openldap/vendor/openldap-release/doc/drafts/draft-ietf-ldapext-acl-model-xx.txt (rev 0)
+++ openldap/vendor/openldap-release/doc/drafts/draft-ietf-ldapext-acl-model-xx.txt 2008-06-28 09:29:58 UTC (rev 1147)
@@ -0,0 +1,2886 @@
+
+
+
+
+
+
+
+Internet-Draft E. Stokes
+LDAP Extensions WG B. Blakley
+Intended Category: Standards Track Tivoli Systems
+Expires: 14 January 2001 D. Rinkevich
+ IBM
+ R. Byrne
+ Sun Microsystems
+ 14 July 2000
+
+ Access Control Model for LDAPv3
+ <draft-ietf-ldapext-acl-model-06.txt>
+
+STATUS OF THIS MEMO
+
+This document is an Internet-Draft and is in full
+conformance with all provisions of Section 10 of RFC2026.
+
+Internet-Drafts are working documents of the Internet
+Engineering Task Force (IETF), its areas, and its working
+groups. Note that other groups may also distribute working
+documents as Internet-Drafts. Internet-Drafts are draft
+documents valid for a maximum of six months and may be
+updated, replaced, or obsoleted by other documents at any
+time. It is inappropriate to use Internet-Drafts as
+reference material or to cite them other than as "work in
+progress."
+
+The list of current Internet-Drafts can be accessed at
+http://www.ietf.org/ietf/1id-abstracts.txt
+
+The list of Internet-Draft Shadow Directories can be
+accessed at http://www.ietf.org/shadow.html.
+
+Comments and suggestions on this document are encouraged.
+Comments on this document should be sent to the LDAPEXT
+working group discussion list:
+
+ ietf-ldapext at netscape.com
+
+COPYRIGHT NOTICE
+
+Copyright (C) The Internet Society (2000). All Rights
+Reserved.
+
+ABSTRACT
+
+This document describes the access control model for the
+Lightweight Directory Application Protocol V3 (LDAPv3)
+directory service. It includes a description of the model,
+the LDAP controls, and the extended operations to the LDAP
+protocol. The current LDAP APIs are sufficient for most
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 1]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+access control operations. An API (in a separate document)
+is needed for the extended operation getEffectiveAccess. A
+separate requirements document for access control exists
+[REQTS]. The access control model used the requirements
+documents as a guideline for the development of this
+specification and are reflected in this specification to the
+extent that the working group could agree on an access
+control model.
+
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
+"SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", and
+"MAY" used in this document are to be interpreted as
+described in [Bradner97].
+
+
+
+1. Introduction
+
+The ability to securely access (replicate and distribute)
+directory information throughout the network is necessary
+for successful deployment. LDAP's acceptance as an access
+protocol for directory information is driving the need to
+provide an access control model definition for LDAP
+directory content among servers within an enterprise and the
+Internet. Currently LDAP does not define an access control
+model, but one is needed to ensure consistent secure access,
+replication, and management across heterogeneous LDAP
+implementations. The major objective is to provide a simple,
+usable, and implementable, but secure and efficient access
+control model for LDAP while also providing the appropriate
+flexibility to meet the needs of both the Internet and
+enterprise environments and policies. This document defines
+the model and the protocol extensions (controls and extended
+operations).
+
+This draft does not (and cannot) fully specify the behavior
+of the Access Control Model in a distributed environment
+(e.g. propagating access control information across servers
+and ACI administration) because there is no LDAP standard
+defining how to distribute directory data between LDAP
+servers. The behavior of the Access Control Model in
+distributed environments is beyond the scope of this draft.
+
+
+
+2. The LDAPv3 Access Control Model
+
+Access Control mechanisms evaluate requests for access to
+protected resources and make decisions about whether those
+requests should be granted or denied. In order to make a
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 2]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+grant/deny decision about a request for access to a
+protected resource, an access control mechanism needs to
+evaluate policy data. This policy data describes security-
+relevant characteristics of the requesting subject and the
+rules which govern the use of the target object.
+
+No mechanism is defined in this document for storage of
+access control information at the server beyond indicating
+that the attribute holding access control information is an
+operational attribute.
+
+The access control mechanisms specified in this document are
+neutral with respect to policy inheritance mechanisms,
+explicit vs. implicit denial, and group nesting.
+
+The access control model defines
+
+ - What flows on the wire for interoperability
+
+ The existing LDAP protocol flows for ldap operations
+ are used to manipulate access control information. A
+ set of permissions and their semantics with respect to
+ ldap operations is defined. The permissions parallel
+ the types of ldap operations defined. What is
+ transmitted is exactly what is read back. Encoding of
+ access control information on the wire is per the
+ LDAPv3 specifications.
+
+ There is an additional LDAP control and extended
+ protocol operation defined, getEffectiveRights. LDAP
+ clients use the control and extended operation to
+ manage and administer access control policy enforced by
+ LDAP servers.
+
+ Servers may store access control information in any way
+ they choose. In particular, servers may use the access
+ control mechanisms of their datastores to store and
+ enforce LDAP access control, or they may implement
+ access control managers external to their datastores.
+ Datastores and external access control managers MAY
+ implement any access control rule syntax and semantics
+ they choose, but the semantics MUST be compatible with
+ those defined in the section titled "Operational
+ Semantics of Access Control Operations".
+
+ - Attributes and classes for application portability of
+ access control information
+
+ An access control information attribute (ldapACI) for
+ application portability: This attribute is used as
+ input to the LDAP APIs so access control information
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 3]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+ can be addressed uniformly independent of how that
+ information is addressed and stored at the server.
+ This same attribute appears in LDIF output for
+ interchange of access control information.
+
+ An access control information subentry class
+ (ldapACISubEntry) and a set of attributes
+ (supportedAccessControlSchemes which is used in the
+ rootDSE and accessControlSchemes which is used in the
+ subentry ldapACISubEntry) to identity the access
+ control mechanisms supported by a server and in a given
+ part of the namespace, respectively.
+
+ - An attribute in the rootDSE, discloseOnError, to
+ control whether it is permissible for the server to
+ return the name of an entry or attribute in an error
+ (or empty set) operation result. This closes a hole on
+ the ability to discover information you are not
+ authorized to discover.
+
+ - A mechanism to control access to access control
+ information: The access control information attribute,
+ ldapACI, is used to control access to access control
+ information (controls access to itself). How to get an
+ initial ldapACI in the directory is server specific and
+ beyond the scope of this model.
+
+Servers can support multiple access control mechanisms, but
+MUST be capable of supporting the LDAP Mechanism in the DIT
+scoped by the rootDSE (entire server's DIT) for that server
+and SHOULD be capable of supporting the LDAP mechanism in an
+arbitrary part (subtree) of the DIT.
+
+The accessControlSchemes attribute in the ldapACISubEntry
+indicates which access control mechanism is in effect for
+the scope of that ldapACISubEntry. The
+supportedAccessControlSchemes attribute in the rootDSE
+indicates which acess control mechanisms are supported by
+the server; those mechanisms are in effect in that server's
+DIT unless overridden by a mechanism defined in a
+ldapACISubEntry elsewhere in that DIT.
+
+Changing the value(s) of either the
+supportedAccessControlSchemes or accessControlSchemes
+attributes changes the mechanism(s) in effect for the scope
+of those attributes (where scope is either that of the
+rootDSE or ldapACISubEntry).
+
+Through the use of the mechanism rootDSE attribute and
+ldapACI subentry, it is possible to run multiple mechanisms
+in either the same subtree or separate subtrees. If two
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 4]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+mechanisms are run in the same subtree, it is desirable that
+the result be the same independent of mechanism, but
+definition and discussion of this is beyond the scope of
+this model.
+
+
+
+3. Access Control Mechanism Attributes
+
+Two attributes are defined to identify which access control
+mechanisms are supported by a given server and by a given
+subtree: supportedAccessControlSchemes and
+accessControlSchemes. (We chose these names based on the
+X.500 attribute, AccessControlScheme which is single-valued
+and defined in X.501).
+
+
+3.1 Root DSE Attribute for Access Control Mechanism
+
+The server advertises which access control mechanisms it
+supports by inclusion of the 'supportedAccessControlSchemes'
+attribute in the root DSE. This attribute is a list of
+OIDs, each of which identify an access control mechanism
+supported by the server. By default, these are also the
+mechanisms in effect in subtrees beneath the root in that
+server unless overridden by a ldapACISubEntry (see section
+"Subentry Class Access Control Mechanism").
+
+ (<OID to be assigned>
+ NAME 'supportedAccessControlSchemes'
+ DESC list of access control mechanisms supported
+ by this directory server
+ SYNTAX LDAPOID
+ USAGE dSAOperation
+ )
+
+The access control mechanism defined is:
+ LDAPv3 <OID to be assigned>
+
+Other vendor access control mechanisms MAY be defined (by
+OID) and are the responsibility of those vendors to provide
+the definition and OID.
+
+
+3.2 Root DSE Attribute for Control of Disclosing Errors
+
+The server specifies whether it is permissible for the name
+of an entry or attribute to be disclosed in an error (or
+empty) operation result. This rootDSE attribute is
+discloseOnError. The default for discloseOnError is false
+(0) or not to disclose on error. The lack of this attribute
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 5]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+in the rootDSE is interpreted as the default.
+
+ (<OID to be assigned>
+ NAME 'discloseOnError'
+ DESC specify whether to return the name of an
+ entry or attribute in an error (or
+ empty) operation result; 0=do not
+ disclose (default); 1=disclose
+ SYNTAX LDAPString
+ USAGE dSAOperation
+
+
+3.3 Subentry Class Access Control Mechanism
+
+A given naming context MUST provide information about which
+access control mechanisms are in effect for that portion of
+the namespace. This information is contained in a subentry
+(ldapACISubEntry class), derived from [SUBENTRY].
+ldapACISubEntry MAY be used to define the scope of an access
+control mechanism. The value(s) held in the rootDSE
+attribute, supportedAccessControlSchemes, are the mechanisms
+in effect in subtrees beneath the root in that server unless
+overridden in a ldapACISubEntry further down the tree held
+by that server. The scope of that ldapACISubEntry is to the
+end of the subtree held by that server or until another
+ldapACISubEntry is encountered in that subtree held by that
+server. The ldapACISubEntry class is defined as:
+
+
+ ( <OID to be assigned>
+ NAME 'ldapACISubEntry'
+ DESC 'LDAP ACI Subentry class'
+ SUP ldapSubEntry STRUCTURAL
+ MUST ( accessControlSchemes )
+ )
+
+The accessControlSchemes attribute MUST be in each ldap
+access control subentry entry associated with a naming
+context whose access control mechanism is different from
+adjacent naming contexts supported by that directory server.
+accessControlSchemes lists the values (list of OIDs) that
+define the access control mechanisms in effect for the scope
+of that ldap access control subentry. Although, in general,
+this attribute will define only a single mechanism (single
+value), more than one mechanism MAY be in effect for the
+scope of that subentry.
+
+ (<OID to be assigned>
+ NAME 'accessControlSchemes'
+ DESC list of access control mechanisms supported
+ in this subtree
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 6]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+ SYNTAX LDAPOID
+ USAGE dSAOperation
+ )
+
+
+
+4. The Access Control Information Attribute (ldapACI)
+
+The access control information attribute, ldapACI, is
+defined as:
+
+ (<OID to be assigned>
+ NAME 'ldapACI'
+ DESC 'ldap access control information'
+ EQUALITY caseIgnoreMatch
+ SYNTAX directoryString
+ USAGE directoryOperation
+ )
+
+The intent of the attribute definition is to design a common
+interchange format. Any given LDAP server should be able to
+translate the below defined attribute into meaningful
+operation requests. Each server should be able to understand
+the attribute; there should not be any ambiguity into what
+any part of the syntax means.
+
+While the end goal is to have a common behavior model
+between different LDAP server implementations, the attribute
+definition alone will not ensure identical ACL processing
+behavior between servers. The semantics of how a server
+interprets the ACI syntax are defined in the "Operational
+Semantics of Access Control" section of this document.
+Additionally, while the server must recognize and act on the
+attribute when received over the wire, there are no
+requirements for the server to physically store this
+attribute.
+
+The attribute definition maintains an assumption that the
+receiving server supports inheritance within the security
+model. If the server does not support inheritance, the
+receiving server must expand any inherited information based
+on the scope flag. If the server does not support partial
+inheritance and both the entry and subtree scope are used,
+then entry is the prevailing scope. (It is possible for two
+values in the ldapACI attribute to have different scopes
+given the syntax of ldapACI; one might contain 'entry' and
+another might contain 'subtree'. This implies that some
+ldapACI values inherit down the DIT and othersdo not - hence
+partial inheritance of the ldapACI attribute.)
+
+The attribute is defined so access control information (ACI)
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 7]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+can be addressed in a server independent of server
+implementation. This attribute is used in typical LDAP APIs
+and in LDIF output of ACI. This attribute may be queried or
+set on all directory objects. The BNF and definitions are
+given below.
+
+
+4.1 The BNF
+
+
+4.1.1 ACI String Representation
+
+ Values of this syntax are encoded according to the
+ following BNF which follows the BNF encoding
+ conventions described in [ABNF]:
+
+ ldapACI = scope "#" rights "#" attr "#" subject
+
+ scope = "entry" / "subtree"
+
+ rights = (("grant:" / "deny:") permissions) /
+ ("grant:" permissions ";deny:" permissions)
+
+ permissions = [permission *("," permission)]
+
+ permission = "a" / ; add
+ "d" / ; delete
+ "e" / ; export
+ "i" / ; import
+ "n" / ; renameDN
+ "b" / ; browseDN
+ "t" / ; returnDN
+ "r" / ; read
+ "s" / ; search
+ "w" / ; write (mod-add)
+ "o" / ; obliterate (mod-del)
+ "c" / ; compare
+ "m" / ; make
+
+ attr = "[all]" / "[entry]" / (attribute *("," attribute))
+
+ attribute = ; OID syntax (1.3.6.1.4.1.1466.115.121.1.38)
+ ; from [ATTR]
+
+ subject = ["authnLevel:" authnLevel ":"]
+ (("authzID-" authzID) /
+ ("role:" dn) /
+ ("group:" dn) /
+ ("subtree:" dn) /
+ ("ipAddress:" ipAddress) /
+ "public:" /
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 8]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+ "this:")
+
+ authnLevel = "any" /
+ "simple" /
+ sasl
+
+ sasl = "sasl:"
+ ("any" /
+ mechanism)
+
+ mechanism = ; sasl mechanism from 4.2 of [LDAPv3]
+
+ authzID = ; authzID from [AuthMeth] repeated below
+ ; for convenience
+
+ authzId = dnAuthzId / uAuthzId
+
+ ; distinguished-name-based authz id.
+ dnAuthzId = "dn:" dn
+
+ dn = utf8string ; with syntax defined in [UTF]
+
+ ; unspecified userid, UTF-8 encoded.
+ uAuthzId = "u:" userid
+ userid = utf8string ; syntax unspecified
+
+ ipAddress = printableString
+ ; dotted decimal form (e.g. 10.0.0.6)
+ ; or use wildcards such as 12.3.45.* to
+ ; specify a specific subnetwork
+ ; or 123.45.6.*+255.255.255.115 to
+ ; specify a subnetmask
+ ; or use a wildcard domain name such as
+ ; *.airius.com to specify a specific
+ ; DNS domain
+
+ printableString ; printableString syntax from [ATTR]
+
+
+Note that the colon following the "public" and "this"
+subject options exist only to simplify string parsing.
+
+Note also that per [AuthMeth], authzID may be expanded in
+the future.
+
+See section titled 'ACI Examples' for examples of the string
+representation.
+
+
+
+
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 9]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+4.1.2 ACI Binary Representation
+
+ The following ASN.1 data type is used to represent this
+ syntax when transferred in binary form:
+
+ ldapACI ::= SEQUENCE {
+ scope ENUMERATED {
+ entry (0),
+ subtree (1) },
+ rights SEQUENCE OF CHOICE {
+ grant [0] Permissions,
+ deny [1] Permissions },
+ attr CHOICE {
+ all [0] NULL,
+ entry [1] NULL,
+ attributes [2] SEQUENCE OF Attribute },
+ subject SEQUENCE {
+ authnLevel CHOICE {
+ any [0] NULL,
+ simple [1] NULL,
+ sasl [2] CHOICE {
+ any [0] NULL,
+ mechanism [1] LDAPString -- from [LDAPv3]
+ }
+ },
+ subject CHOICE {
+ dn [0] DN,
+ user [1] utf8String
+ role [1] DN,
+ group [2] DN,
+ subtree [3] DN,
+ ipAddress [4] IPAddress,
+ public [6] NULL,
+ this [7] NULL }, } -- may be expanded
+ per [AuthMeth]
+
+ Permissions ::= SEQUENCE OF ENUMERATED {
+ add (0),
+ delete (1),
+ export (2),
+ import (3),
+ renameDN (4),
+ browseDN (5),
+ returnDN (6),
+ read (7),
+ search (8),
+ write (9),
+ obliterate (10),
+ compare (11),
+ make (12) }
+
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 10]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+ Attribute ::= AttributeType -- from [LDAPv3]
+
+ IPAddress ::= PrintableString -- (e.g. 10.0.0.6)
+
+
+
+4.2 The Components of ldapACI Attribute
+
+This section defines components that comprise the access
+control information attribute, ldapACI.
+
+
+4.2.1 Scope
+
+Two scopes for access control information are defined:
+
+ - entry - the access control information in the ldapACI
+ attribute applies only to the entry in which it is
+ contained
+
+ - subtree - the access control information in the ldapACI
+ attribute applies to each entry down the subtree unless
+ it is overridden by an entry-specific ldapACI whose
+ values are more specific.
+
+Use of prescriptive ACIs and scoping via use of a
+ldapACISubEntry is outside the scope of this document.
+
+
+4.2.2 Access Rights and Permissions
+
+Access rights can apply to an entire object or to attributes
+of the object. Access can be granted or denied. Either or
+both of the actions "grant" | "deny" may be used when
+creating or updating ldapACI.
+
+Each of the LDAP access permissions are discrete. One
+permission does not imply another permission. The
+permissions which apply to attributes and the entry parallel
+the type of ldap operations that can be performed.
+
+Permissions which apply to attributes:
+
+ r Read Read attribute values
+ w Write Modify-add values
+ o Obliterate Modify-delete values
+ s Search Search entries with specified attributes
+ c Compare Compare attributes
+ m Make Make attributes on a new entry below
+ this entry
+
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 11]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+ 1. r Read
+
+ If granted, permits attributes and values to be
+ returned in a read or search operation.
+
+ 2. w Write
+
+ If granted, permits attributes and values to be added
+ in a modify operation.
+
+ 3. o Obliterate
+
+ If granted, permits attributes and values to be
+ deleted in a modify operation.
+
+ 4. s Search
+
+ If granted, permits attributes and values to be
+ included in a search operation.
+
+ 5. c Compare
+
+ If granted, permites attributes and value to be used
+ in a compare operation.
+
+ 6. m Make
+
+ The attribute permission "m" is required for all
+ attributes that are placed on an object when it is
+ created. Just as the "w" and "o" permissions are used
+ in the Modify operation, the "m" permission is used in
+ the Add operation. Additionally, note that "w" and "o"
+ have no bearing on the Add operation and "m" has no
+ bearing on the Modify operation. Since a new object
+ does not yet exist, the "a" and "m" permissions needed
+ to create it must be granted on the new object's
+ parent. This differs from "w" and "o" which must be
+ granted on the object being modified. The "m"
+ permission is distinct and separate from the "w" and
+ "o" permissions so that there is no conflict between
+ the permissions needed to add new children to an entry
+ and the permissions needed to modify existing children
+ of the same entry.
+
+Note: Modify-replace values of an attribute requires "w"
+and "o" permission.
+
+Permissions that apply to an entire entry:
+
+
+ a Add Add an entry below this entry
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 12]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+ d Delete Delete this entry
+ e Export Export entry & subordinates to new
+ location
+ i Import Import entry & subordinates from some
+ location
+ n RenameDN Rename an entry's DN
+ b BrowseDN Browse an entry's DN
+ t ReturnDN Allows DN of entry to be disclosed in
+ an operation result
+
+
+ 1. a Add
+
+ If granted, permits creation of an entry in the DIT
+ subject to control on all attributes and values to be
+ placed in the new entry at time of creation. In order
+ to add an entry, permission must also be granted to
+ add at least the mandatory attributes.
+
+ 2. d Delete
+
+ If granted, permits the entry to be removed from the
+ DIT regardless of controls on attributes within the
+ entry.
+
+ 3. e Export
+
+ If granted, permits an entry and its subordinates (if
+ any) to be exported; that is, removed from the current
+ location and placed in a new location subject to the
+ granting of suitable permission at the destination.
+ If the last RDN is changed, Rename is also required at
+ the current location. In order to export an entry or
+ its subordinates, there are no prerequisite
+ permissions to contained attributed, including the RDN
+ attributes; this is true even when the operation
+ causes new attribute values to be added or removed as
+ the result of the changes of RDN.
+
+ 4. i Import
+
+ If granted, permits an entry and its suordinates (if
+ any) to be imported; that is, removed from some other
+ location and placed a t the location to which the
+ permission applies subject to the granting of suitable
+ permissions at the source location. In order to
+ import an entry or its subordinates, there are no
+ prerequisite permissions to contained attributed,
+ including the RDN attributes; this is true even when
+ the operation causes new attribute values to be added
+ or removed as the result of the changes of RDN.
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 13]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+ 5. n RenameDN
+
+ Granting Rename is necessary for an entry to be
+ renamed with a new RDN, taking into account
+ consequential changes to the distinguished names of
+ subordinate entries, if any; if the name of the
+ superior is unchanged, the grant is sufficient. In
+ order to rename an entry, there are no prerequisite
+ permissions to contained attributed, including the RDN
+ attributes; this is true even when the operation
+ causes new attribute values to be added or removed as
+ the result of the changes of RDN.
+
+ 6. b BrowseDN
+
+ If granted, permits entries to be accessed using
+ directory operations which do not explicitly provide
+ the name of the entry.
+
+ 7. t ReturnDN
+
+ If granted, allows the distinguished name of the entry
+ to be disclosed in the operation result.
+
+All permissions (for grant and deny) for an attribute/entry
+and a given subject MUST be contained within one ldapACI
+value, i.e. (in abbreviated form)
+
+ ldapACI: ...grant OID.attr1 subjectA
+ ldapACI: ...deny OID.attr1 subjectA
+
+must be ldapACI: ...grant ... deny... OID.attr1 subjectA
+
+Using the defined BNF it is possible for the permission
+string to be empty. The ACI
+
+ ldapACI: subtree#grant#OID.attr1#group:cn=Dept XYZ,c=US
+
+ ldapACI: subtree#grant:r,s#[all]#group:cn=Dept XYZ,c=US
+
+means that this group (Dept XYZ) is granted permission to
+read and search all attributes except OID.attr1 because
+OID.attr1 is more specific than "[all]".
+
+
+4.2.3 Attributes
+
+Attribute describes an attribute name in the form of a
+dotted decimal OID for that <attr>. If the string (OID)
+refers to an attribute not defined in the given server's
+schema, the server SHOULD report an error. "[entry]" means
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 14]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+the permissions apply to the entire object. This could mean
+actions such as delete the object, or add a child object.
+"[all]" means the permission set apply to all attributes of
+the entry.
+
+If the keyword "[all]" and another attribute are both
+specified within an ACI, the more specific permission set
+for the attribute overrides the less specific permission set
+for "[all]".
+
+
+4.2.4 Subjects and Associated Authentication
+
+The following subjects are defined and MUST be supported:
+
+ - authzID, defined per [authmeth]
+
+ - group, defined as the distinguished name of a
+ groupOfNames or groupOfUniqueNames entry
+
+ - role
+
+ - subtree, defined as the distinguished name of a non-
+ leaf node in the DIT
+
+ - ipAddress,
+
+ - public, defined as public access
+
+ - this, defined as the user whose name matches that of
+ the entry being accessed
+
+Other parties MAY define other subjects. It is the
+responsibility of those parties to provide the definition.
+
+A subject may be qualified by the type of authentication
+required for access to a given attribute(s) or entry. If no
+authnLevel is present, then no specific type of
+authentication is additionally required for access. If
+authnLevel is specified, then that type of authentication is
+additionally required for access. The authnLevels parallel
+the authentication mechanisms specified for LDAPv3: simple,
+SASL (any type of SASL mechanism), and a SASL-specific
+mechanism. The authnLevel of is not an acceptable mechanism
+for this case) as part of obtaining access.
+
+
+4.3 Grant/Deny Evaluation Rules
+
+The decision whether to grant or deny a client access to a
+particular piece of information is based on several pieces
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 15]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+of information found within the ldapaci value. Throughout
+the decision making process, there are guiding principals.
+
+ - Specificity: More specific policies MUST override less
+ specific ones (e.g. individual user entry in ACI takes
+ precedence over group entry).
+
+ - Deny takes precedence over Grant.
+
+ - When there are conflicting ACI values, deny takes
+ precedence over grant.
+
+ - Deny is the default when there is no access control
+ information.
+
+Precendence of Scope Types (highest to lowest)
+
+ - entry
+
+ - subtree
+
+Precedence of Subjects within a Scope (highest to lowest):
+
+ - ipAddress
+
+ - authzID, this
+
+ - group, role, this, public
+
+ - subtree, public
+
+Although other types MAY be defined given the BNF, use of
+the well-known types aids in interoperability and
+operational consistency.
+
+Access Decision algorithm:
+
+ 1. Determine all the ldapACI values which could apply to
+ the target DN which is being accessed. This is the DN
+ of the entry which is being queried in a search,
+ modified, deleted, etc. When determining all the
+ ldapACI values, the scope field should be used. All
+ ldapACI values with a scope of 'entry' take precedence
+ over ldapACI values with a scope of 'subtree'.
+
+ 2. Determine which ldapACI (of the set determined in step
+ 1) apply to the bound DN. This is determined by
+ looking at the subject (combination of subject type
+ and subject value) and bind type. If no bind is in
+ effect (this is possible in ldapv3), then treat this
+ lack of bind as if bound as anonymous. Start with the
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 16]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+ most specific subject type. If at any time, at least
+ one ldapACI value exists for a specificity level, then
+ processing stops; the exception here is 'this' because
+ this may also be combined with group to use power of
+ 'this'. Evaluation should take place on set of
+ ldapACI values which are all of the same specificity
+ level. Subjects of the same precedence are combined
+ using union semantics.
+
+ 3. Evaluate the remaining ldapACI values and determine a
+ grant/deny decision. If conflicting ldapACI value
+ exists for the same attribute, or attributes (i.e. one
+ ldapACI grants permission and another denies
+ permission), then deny takes precedence over grant.
+ For example, if one is granted permission to
+ "objectclass" in one ldapACI value by being a member
+ of group cn=Admin, and denied permission by being a
+ member of cn = NontrustedAdmins, then the bound user
+ would not receive permission to objectclass.
+
+ The rule of specificity also applies to the
+ attributes. If one is denied permission to "[ all ]"
+ attributes, but granted permission to "objectclass"
+ then the more specific value of "objectclass" takes
+ precedence over the less specific value of "[ all ] ".
+ In this case the user would be granted permission to
+ "objectclass" but denied permission to all other
+ attributes.
+
+
+
+5. Required Permissions for each LDAP Operation
+
+This section defines the required permissions for each LDAP
+operation but even if these requirements are satisfied the
+server MAY refuse to carry out the operation due to other
+implementation specific security considerations. For
+example, a server may refuse to modify an entry because the
+database where that entry resides is in read only mode.
+Another example might be that although the access control is
+available to the userPassword attribute a server may refuse
+modifications due to some server specific policy governing
+access to passwords.
+
+Here, we specify the rights required by a user when
+performing an LDAP operation in terms of the LDAP
+permissions specified in section 6.1. Recall that "a, d,
+e, i, n, b,t" are permissions that apply to entries as a
+whole while permissions "r, s, w, o, c, m" apply to
+attributes within entries.
+
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 17]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+Required permissions for LDAP extended operations and LDAP
+controls are beyond the scope of this draft.
+
+There is a requirement that a user should not be able to
+infer the existence of data in the Directory, if the user
+does not have the required access rights to that data. An
+example of this requirement would be in a hosting
+environment where you would not want any users from the coke
+subtree to be able to even discover that the pepsi tree was
+hosted on the same server. This "discloseOnError" feature
+will be set once for server in the rootDSE advertised by the
+attribute discloseOnError. The default for discloseOnError
+is false (0). The lack of this attribute in the rootDSE is
+interpreted as the default. The details of its effects are
+addressed below, operation by operation.
+
+For the following, assume that the authorization identity of
+the user doing the operation is authzID.
+
+
+5.1 Bind Operation
+
+This draft does not require any permissions to allow a bind
+operation to proceed.
+
+
+5.2 Search Operation
+
+Recall that the parameters of the Search operation per RFC
+2251 [LDAPv3] Section 4.5 are:
+
+ SearchRequest ::= [APPLICATION 3] SEQUENCE {
+ baseObject LDAPDN,
+ scope ENUMERATED {
+ baseObject (0),
+ singleLevel (1),
+ wholeSubtree (2) },
+ derefAliases ENUMERATED {
+ neverDerefAliases (0),
+ derefInSearching (1),
+ derefFindingBaseObj (2),
+ derefAlways (3) },
+ sizeLimit INTEGER (0 .. maxInt),
+ timeLimit INTEGER (0 .. maxInt),
+ typesOnly BOOLEAN,
+ filter Filter,
+ attributes AttributeDescriptionList }
+
+Suppose a server is processing a search request from user
+authzID with parameters as above and is processing the entry
+with dn candidateDN to decide if it may be returned or not.
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 18]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+Then the permissions required by authzID that need to be
+evaluated are as follows:
+
+
+ 1. permission "b" to the entry candidateDN
+
+ If this permission is not granted then the dn
+ candidateDN MUST not be returned nor any attribute
+ type nor attribute value from this entry.
+
+ If this permission is granted then the dn candidateDN
+ MAY be returned.
+
+ Note: The idea of the "b" permission is to say "a user
+ has discovery rights" at a certain entry in the
+ directory. Assuming that the further required
+ permissions below are satisfied then having "b" right
+ is enough to allow the server to return candidateDN.
+ Of course candidateDN contains in it's components,
+ attributes and attribute values for all the ancestors
+ of candidateDN. This can lead to the slightly odd
+ situation that we can discover the naming attribute of
+ an entry and that attribute's value by virtue of
+ having the required searching permissions to it's
+ child but not by searching the entry directly.
+
+ 2. permission "s" to each attribute appearing in a
+ presence test during the evaluation of the search
+ filter. permission "r" to each attribute appearing in
+ non-presence tests (see rfc1960, section 3:
+ equalityMatch, substrings, greaterOrEquial,
+ lessOrEqual, present, approxMatch, extensibleMatch)
+ during the evaluation of the search filter.
+
+ The above statement covers the case where the
+ attributes are being evaluated as part of an
+ extensibleMatch (RFC 2251 section 4.5.1) which appears
+ in the filter. In the case where the dnAttributes
+ field of the extensibleMatch is true then we do not
+ require any access checks to the attributes of the dn
+ candidateDN as access to these is taken to be granted
+ by the "b" permission, which has already been required
+ above.
+
+ If there is an attribute in a filter element to which
+ the required permission is not granted then that
+ filter element evaluates to "Undefined" of the three-
+ valued-logic of X.511(93).
+
+ Note A: Although both "r" and "s" permissions will
+ typically be granted to attributes we keep both
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 19]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+ permissions as there are cases where the distinction
+ is useful. For example, the ability to grant the
+ right to discover that a user entry contains a
+ userPassword attribute, but not to read it's value
+ ("s" but not "r"). The converse, granting "r" but not
+ "s" permission is less easy to motivate.
+
+ Note B: There is an unusual behaviour with respect to
+ naming attributes illustrated in the following
+ example:
+
+ Suppose I have "b" rights to cn=fred,o=sun.com and "r"
+ rights to attribute objectclass but not "r" rights to
+ cn then with search filter (objectclass=*) I get back
+ the dn and objectclass (and so can see the value of
+ cn), but with a search filter of (cn=fred) I do not
+ get anything.
+
+ 3. permission "r" to each attribute in the attribute list
+
+ AttributeDescriptionList (or all attributes in the
+ entry candidateDN if AttributeDescriptionList is *)
+ whose type and/or value will be returned.
+
+ Note: The presence of an attribute in an entry is only
+ ever volunteered by the server if "r" permission is
+ granted to it, though a user may infer the presence of
+ an attribute with "s" permission by using a presence
+ test on that attribute in the search filter.
+
+ 4. permission "t" to the entry candidateDN
+
+ If this permission is not granted then the dn
+ candidateDN MUST NOT be returned. If the server knows
+ of an alias for the entry, this alias may be returned
+ instead. If no alias name is available then the entry
+ candidateDN MUST be omitted from the search results.
+
+
+ 5. Disclose on error for the Search operation
+
+ If every entry in the scope of the search fails to
+ satisfy item 1 (browse right on the candidate entry)
+ or item 2 (right to use the filter on that entry) and
+ if discloseOnError is not granted to the baseObject
+ entry then the operation MUST fail with a "no such
+ object error" and the matchedDN of the LDAPResult MUST
+ be set to "". If every entry in the scope of the
+ search fails to satisfy items 1 or 2 above and
+ discloseOnError is granted to the baseObject then the
+ empty set of results is returned.
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 20]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+5.3 Modify Operation
+
+Recall that the parameters of the Modify operation per
+RFC2251 [LDAPv3] Section 4.6 are:
+
+ ModifyRequest ::= [APPLICATION 6] SEQUENCE {
+ object LDAPDN,
+ modification SEQUENCE OF SEQUENCE {
+ operation ENUMERATED {
+ add (0),
+ delete (1),
+ replace (2) },
+ modification AttributeTypeAndValues } }
+
+
+ AttributeTypeAndValues ::= SEQUENCE {
+ type AttributeDescription,
+ vals SET OF AttributeValue }
+
+Then the permissions required by authzID that need to be
+evaluated are as follows:
+
+
+ 1. permission "w" to each attribute being added to object
+
+ If this permission is not granted to such an
+ attribute, then the operation MUST fail. In this
+ case, if discloseOnError is not granted to the entry
+ then "no such object" error is returned; if
+ discloseOnError is granted to the entry and a
+ duplicate attribute value is being added then
+ "attribute value already exists" error is returned; if
+ discloseOnError is granted to the entry and no
+ duplicate value is being added then an "insufficient
+ access" error is returned.
+
+ 2. permission "o" to each attribute for which a value is
+ being deleted from object
+
+ If this permission is not granted to such an attribute
+ then the operation MUST fail. In this case, if
+ discloseOnError is not granted to the entry then "no
+ such object" error is returned; if discloseOnError is
+ granted to the entry and the attribute or one of the
+ values to be deleted does not exist then a "no such
+ attribute or value" error is returned; if
+ discloseOnError is granted to the entry and the
+ attribute and all values specified to be deleted exist
+ then an "insufficient access" error is returned.
+
+
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 21]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+ 3. permissions "o" and "w" to each attribute being
+ replaced in object
+
+ If one of these these permissions is not granted to
+ such an attribute then the operation MUST fail. In
+ this case, if discloseOnError is not granted to the
+ entry then a "no such object" error is returned; if
+ discloseOnError is granted to the entry then
+ "insufficient access" error is returned.
+
+
+5.4 Add Operation
+
+Recall that the parameters of the Add operation per RFC2251
+[LDAPv3] Section 4.7 are:
+
+ AddRequest ::= [APPLICATION 8] SEQUENCE {
+ entry LDAPDN,
+ attributes AttributeList }
+
+
+ AttributeList ::= SEQUENCE OF SEQUENCE {
+ type AttributeDescription,
+ vals SET OF AttributeValue }
+
+Then the permissions required by authzID that need to be
+evaluated are as follows:
+
+ permission "a" to the parent of entry
+
+ The access rights required for the creation of a root
+ entry in the Directory are beyond the scope of this
+ document. They will be vendor specific.
+
+ 1. permission "m" to the parent of entry for each
+ attribute being added to entry
+
+If any of these permissions are not granted then the
+operation MUST fail. In this case if discloseOnError is on
+and the entry to be added does not already exist then
+"insufficient access" is returned. If it does exist then
+"Entry already exists" is returned. If discloseOnError is
+off then "No such object" is returned (meaning the parent
+object).
+
+If they are all granted then the operation MAY proceed.
+
+Note: We require "m" permission to each attribute to prevent
+an entry from aquiring "unintended" rights (via group or
+role membership), to stop a "rogue" ACI being added that
+would prevent even admins deleting the entry and general
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 22]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+consistency with the MODIFY operation.
+
+Note: The access rights required for the creation of the
+first entry in the directory are beyond the scope of this
+document.
+
+
+5.5 Delete Operation
+
+Recall that the parameters of the Delete operation per
+RFC2251 [LDAPv3] Section 4.10 are:
+
+ DelRequest ::= [APPLICATION 10] LDAPDN
+
+Then the permissions required by authzID that need to be
+evaluated are as follows:
+
+
+ 1. permission "d" to the entry in the Delete request
+
+If this permission is not granted, then the operation MUST
+fail. In this case if discloseOnError is on and the entry
+to be deleted exists then "insufficient access" is returned.
+If it does not exist then "No such Object" is returned. If
+discloseOnError is off then "No such object" is returned
+(meaning the parent object).
+
+If this permission is granted, then the operation MAY
+proceed.
+
+Note: One could also require the "o" permission to be
+granted to allow the operation to proceed, but customer
+experience has shown that the requirement of the additional
+permission is not useful nor expected, and X.500 requires
+only the "d" permission.
+
+
+5.6 Modify DN Operation
+
+Recall that the parameters of the Modify DN operation per
+RFC2251 [LDAPv3] Section 4.6 are:
+
+ ModifyDNRequest ::= [APPLICATION 12] SEQUENCE {
+ entry LDAPDN,
+ newrdn RelativeLDAPDN,
+ deleteoldrdn BOOLEAN,
+ newSuperior [0] LDAPDN OPTIONAL }
+
+Then the permissions required by authzID that need to be
+evaluated are as follows:
+
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 23]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+ 1. If newSuperior is not present (ie. only the RDN is
+ being renamed) then permission "n" to entry is
+ required.
+
+ 2. If newSuperior is present then permission "e" to entry
+ and permission "i" to newSuperior are required.
+
+If any of these permissions are not granted then the
+operation MUST fail. In this case, if discloseOnError is on
+then an "insufficient access error" is returned. Otherwise,
+"No such object" is returned.
+
+If they are all granted then the operation MAY proceed.
+
+Note A: We do not require any additional permissions in the
+case where deleteoldrdn is TRUE.
+
+Note B: These permissions allow the naming attribute of an
+entry (or entries) to be changed even though "o" and "w"
+permissions are not available on the entry. Distinguishing
+the permissions like this allows us to grant permissions for
+the ModifyDN operation, but not the Modify operation and
+vice versa.
+
+
+5.7 Compare Operation
+
+Recall that the parameters of the Compare operation per
+RFC2251 [LDAPv3] Section 4.10 are:
+
+ CompareRequest ::= [APPLICATION 14] SEQUENCE {
+ entry LDAPDN,
+ ava AttributeValueAssertion }
+
+Then the permissions required by authzID that need to be
+evaluated are as follows:
+
+
+ 1. permission "c" to the attribute in entry on which the
+ comparison is being made.
+
+If any of these permissions are not granted then the
+operation MUST fail. In this case, if discloseOnError is on
+then an "insufficient access error" is returned. Otherwise,
+"No such object" is returned.
+
+If they are all granted then the operation MAY proceed.
+
+
+
+
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 24]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+5.8 Abandon Operation
+
+Recall that the parameters of the Abandon operation per
+RFC2251 [LDAPv3] Section 4.6 are:
+
+ AbandonRequest ::= [APPLICATION 16] MessageID
+
+authzID always has the right to send an Abandon Operation
+for an operation he previously initiated.
+
+
+5.9 Extended Operation
+
+Recall that the parameters of the Extended operation per
+RFC2251 [LDA{v3] Section 4.12 are:
+
+ ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
+ requestName [0] LDAPOID,
+ requestValue [1] OCTET STRING OPTIONAL }
+
+The access required for an Extended Operation is beyond the
+scope of this document. The required access will normally
+be defined by the implementor of the extended request.
+
+
+
+6. Required Permissions for Handling Aliases and References
+
+
+Use of aliases and referrals are part of LDAPv3. However,
+neither is particularly well-defined. Alias
+objects/attributes are defined in RFC 2256 as derived from
+X.500, but LDAPv3 does not explicitly define its semantics
+or behavior. X.500 does define alias semantics and behavior
+with respect to access control; we define its behavior in
+LDAPv3 based on the X.511, section 7.11.1. Referrals and
+knowledge information are still under design in LDAPv3; they
+are defined in X.500, however, X.500 punts on their
+semantics and behavior with respect to access control. We
+define their semantics and behavior in LDAPv3 in terms that
+should be independent of the future LDAPv3 definition of
+referrals and knowledge information.
+
+
+6.1 ACI Distribution
+
+Currently there is no LDAP standard defining how to
+distribute directory data between LDAP servers. Consequently
+this draft cannot fully specify the behavior of the Access
+Control Model in a distributed environment. The case of
+distribution via referrals is treated in the "Referrals"
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 25]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+section below. In the case of chaining (where one LDAP
+server forwards a request to another on behalf of a client)
+then it is server specific how the access control model
+behaves in this environment. Similarly it is server specific
+how the server determines whether the chaining of an
+operation is permitted in the first place. For example, the
+implementation may choose to regard the local naming context
+and the remote subordinate naming context as seperate Access
+Control Specific Areas, or it may regard the DIT as one
+Access Control Specific Area and implement mechanisms to
+propagate access control information between the two
+servers. The behavior of the Access Control Model in
+distributed environments such as these is beyond the scope
+of this draft.
+
+
+6.2 Aliases
+
+There are two things to protect with respect to aliases:
+the real name of the aliased object and the location of the
+server holding it.
+
+If alias de-referencing is required in the process of
+locating a target entry, no specifc permissions are
+necessary for alias de-referencing to take place. Access
+control is enforced at the object pointed to by the alias.
+
+If alias de-referencing would result in a
+continuationReference (e.g. from a search operation), then
+browse permission is required to the alias entry and read
+permission is required to the 'aliasedObjectName' attribute.
+Requiring these permission closes the hole of discovery.
+
+
+6.3 Referrals
+
+If a referral is to be followed, no specifc permissions are
+necessary for the ldap client to follow the referral. Access
+control is enforced at the referenced object. If a referral
+is returned, then browse is required on the entry and read
+permission is required to the attribute containing the
+referral (we cannot name this attribute exactly today
+because there are no RFCs on this - only drafts). If the
+server implements a default referral, then no special
+permissions are required to read and return that referral.
+Requiring these permissions closes the hole of discovery.
+In the default case, it is assumed that a default referral
+is public.
+
+
+
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 26]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+7. Controlling Access to Access Control Information
+
+The ldapACI attribute is used to specify control for who has
+permission to set/change access control information
+(ldapACI). The ldapACI attribute/OID is just another
+attribute described with a scope, set of rights and
+permissions, and subject as a value of the ldapACI
+attribute. (See the example in the "ACI Examples" section).
+
+If the policy for controlling the ldapACI attribute is not
+specified for any object in the tree, behavior is
+implementation defined. For instance, if no object anywhere
+in the tree defines the access for ldapACI within the
+ldapACI attribute, then the server could simply assert that
+the 'root DN' is considered the policy owner (controller for
+controlling access control) for all objects.
+
+
+
+8. ACI Examples
+
+Note that in the examples, the form "OID.<attrname>" refers
+to the OID in dotted decimal form for the attribute
+<attrname>. This shorthand notation is used only for the
+examples. In implementation, the dotted decimal form of the
+OID is used.
+
+
+8.1 Attribute Definition
+
+The following examples show the access required to control
+access to the ldapACI attribute. The first example shows
+controlling the access control on an individual entry and
+its attributes. The second example shows controlling the
+access control on a subtree.
+
+ ldapACI: entry#grant:r,w#
+ OID.ldapACI#authnLevel:any:role:cn=aciAdmin
+
+ ldapACI: subtree#grant:r,w#
+ OID.ldapACI#authnLevel:any:role:cn=aciAdmin
+
+The next example shows a ldapACI attribute where a group
+"cn=Dept XYZ, c=US" is being given permissions to read,
+search, and compare attribute attr1. The permission applies
+to the entire subtree below the node containing this ACI.
+Authentication of a specified type is not required.
+
+ ldapACI:subtree#grant;r,s,c#
+ OID.attr1#group:cn=Dept XYZ,c=US
+
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 27]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+The next example shows an ACI attribute where a role
+"cn=SysAdmins,o=Company" is being given permissions to add
+objects below this node and read, search, and compare
+attributes attr2 and attr3. The permission applies to the
+entire subtree below the node containing this ACI.
+
+ ldapACI: subtree#grant:a#
+ [entry]#role:cn=SysAdmins,o=Company
+
+ ldapACI: subtree#grant:r,s,c#
+ OID.attr2#role:cn=SysAdmins,o=Company
+
+ ldapACI: subtree#grant:r,s,c#
+ OID.attr3#role:cn=SysAdmins,o=Company
+
+
+8.2 Modifying the ldapACI Values
+
+Modify-Replace works as defined in the ldap operation
+modify. If the attribute value does not exist, create the
+value. If the attribute does exist, replace the value. If
+the ldapACI value is replaced, all ldapACI values are
+replaced.
+
+A given ldapACI for an entry:
+
+ ldapACI: subtree#deny:r,w#[all]#group:cn=Dept ABC
+
+ ldapACI: subtree#grant:r#OID.attr1#group:cn=Dept XYZ
+
+perform the following change:
+
+ dn: cn=someEntry
+ changetype: modify
+ replace: ldapACI
+ ldapACI: subtree#grant:r,w#[all]#group:cn=Dept LMN
+
+The resulting ACI is:
+
+ldapACI: subtree#grant:r,w#[all]#group:cn=Dept LMN
+
+( ldapACI values for Dept XYZ and ABC are lost through the
+replace )
+
+During an ldapmodify-add, if the ACI does not exist, the
+create the ACI with the specific ldapACI value(s). If the
+ACI does exist, then add the specified values to the given
+ldapACI. For example a given ACI:
+
+ldapACI: subtree#grant:r,w#[all]#group:cn=Dept XYZ
+
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 28]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+with a modification:
+
+ dn: cn=someEntry
+ changetype: modify
+ add: ldapACI
+ ldapACI: subtree#grant:r#OID.attr1#group:cn=Dept XYZ
+
+would yield an multi-valued ACI of:
+
+ ldapACI: subtree#grant:r,w#[all]#group:cn=Dept XYZ
+
+ ldapACI: subtree#grant:r#OID.attr1#group:cn=Dept XYZ
+
+To delete a particular ACI value, use the regular ldapmodify
+- delete syntax
+
+Given an ACI of:
+
+ ldapACI: subtree#grant:r,w#[all]#group:cn=Dept XYZ
+ ldapACI: subtree#grant:r#OID.attr1#group:cn=Dept XYZ
+
+ dn: cn = some Entry
+ changetype: modify
+ delete: ldapACI
+ ldapACI: subtree#grant:r#OID.attr1#group:cn=Dept XYZ
+
+would yield a remaining ACI on the server of
+
+ldapACI: subtree#grant:r,w#[all]#group:cn=Dept XYZ
+
+The attributes which are defined for access control
+interchange may be used in all LDAP operations.
+
+Within the ldapmodify-delete operation, the entire acl may
+be deleted by specifying
+
+ dn: cn = some Entry
+ changetype: modify
+ delete: ldapACI
+
+In this case, the entry would then inherit its ACI from some
+other node in the tree depending on the server inheritance
+model.
+
+Similarly, if all values of ldapACI are deleted, then the
+access control information for that entry is defined by that
+implementation's inheritance model.
+
+
+
+
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 29]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+8.3 Evaluation
+
+These examples assume that the ldapACI entries listed in
+each example are the only ACI which applies to the entry in
+question; if backing-store ACI also exists, the effective
+policy may be different from that listed in each example.
+See section 10 for a discussion of the semantics of ldapACI
+entries when backing-store ACI administration is also used.
+
+Assume cn=jsmith is a member of group cn=G1. Assume
+cn=jsmith is a member of group cn=G2.
+
+ Example #1
+ dn: o=XYZ, c=US
+ ldapACI: subtree#grant:r#attr1
+ #authzID-dn:cn=jsmith,ou=ABC,o=XYZ,c=US
+ ldapACI: subtree#grant:w#attr1
+ #group:cn=G1,ou=ABC,o=XYZ,c=US
+
+ What rights does cn=jsmith have to attr1 of o=XYZ,c=US?
+ Read (r) access; authzID is higher precedence than
+ group.
+
+
+ Example #2
+ dn: o=XYZ, c=US
+ ldapACI: subtree#grant:r#attr2
+ #group:cn=G1,ou=ABC,o=XYZ,c=US
+ ldapACI: subtree#grant:w#attr2
+ #group:cn=G2,ou=ABC,o=XYZ,c=US
+
+ What rights does cn=jsmith have to attr2 of o=XYZ,c=US?
+ Read-write (r,w) access; ACI is combined because both
+ subjects (group) have same precedence.
+
+
+ Example #3
+ dn: o=XYZ, c=US
+ ldapACI: subtree#grant:r,w#attr3
+ #group:cn=G1,ou=ABC,o=XYZ,c=US
+ ldapACI: subtree#deny:w#attr3#group:cn=G2,ou=ABC,o=XYZ,c=US
+
+ What rights does cn=jsmith have to attr3 of o=XYZ, c=US?
+ Read access; write is denied (deny has precedence over
+ grant).
+
+
+ Example #4
+ dn: o=XYZ, c=US
+ ldapACI: subtree#grant:w#attr4
+ #authzID-dn:cn=jsmith,ou=ABC,o=XYZ,c=US
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 30]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+ ldapACI: subtree#grant:r#attr4#subtree:ou=ABC,ou=XYZ,c=US
+
+ What rights does cn=jsmith have to attr4 of o=XYZ, c=US?
+ Write (w); rights given to an authzID take precedence
+ over those given to a subtree.
+
+
+ Example #5
+ dn: o=XYZ, c=US
+ ldapACI: subtree#grant:m#OID.attr5
+ #authzID-dn:cn=jsmith,o=ABC,c=US
+ ldapACI: subtree#grant:m#OID.cn
+ #authzID-dn:cn=jsmith,o=ABC,c=US
+ ldapACI: subtree#grant:m#OID.sn
+ #authzID-dn:cn=jsmith,o=ABC,c=US
+ ldapACI: subtree#grant:a#[entry]
+ #authzID-dn:#cn=jsmith,o=ABC,c=US
+
+ What rights does cn=jsmith have to o=XYZ, c=US?
+ Make(m) on attributes attr5, cn, and sn and Add(a)
+ on the entry. These are the minimal yet sufficient
+ permissions to create a new object,
+ cn=New, o=XYZ, c=US with values for the attr5, cn,
+ and sn attributes. This example illustrates how the
+ "m" permission can be used to limit the attributes
+ that can be created on a new entry.
+
+ Example #6
+ dn: c=US
+ ldapACI: subtree#grant:m#[all]#subtree:c=US
+ dn: o=XYZ, c=US
+ ldapACI: subtree#grant:a#[entry]#
+ authzID-dn:cn=jsmith,o=ABC,c=US
+
+ What rights does cn=jsmith have to o=XYZ, c=US?
+ Make(m) on attributes all attributes and Add(a) on the
+ entry. These are sufficient permissions to create a new
+ object, cn=New, o=XYZ, c=US with values any desired
+ attributes. For administrators who do not wish to limit
+ the attributes that can be created on new entries, this
+ example shows how a single ldapACI at the top of the
+ domain solves the problem.
+
+
+
+9. Operational Semantics of Access Control Operations
+
+The semantics of access control operations described in this
+document are defined operationally in terms of "histories".
+A history is a sequence of actions (x1, x2, ..., xN).
+
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 31]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+9.1 Types of actions
+
+We consider five types of actions:
+
+ - LDAP Access Control Policy Update actions: invocations
+ of ldap modify when used to add, delete, or replace the
+ aci attribute; invocations of ldap add when used to add
+ an entry with an aci attribute. A LDAP Access Control
+ Policy Update action may replace the policy (by
+ completely replacing the aci attribute with new policy
+ information) or it may grant or deny specific rights
+ while leaving others unaffected.
+
+ - LDAP Access Control Policy Query operations:
+ invocations of ldap search when used to retrieve the
+ aci attribute; invocations of ldap search with the
+ getEffectiveRightsRequest control; invocations of the
+ ldapGetEffectiveRightsRequest extended operation.
+
+ - Datastore Access Control Policy Update Actions: any
+ operation implemented by the server which LDAP is using
+ as its datastore which changes the access policy
+ enforced with respect to attempts to access LDAP
+ directory entries and their attributes.
+
+ - LDAP Access Request operations: invocations of LDAP
+ entry or attribute access operations (Read, Update,
+ Search, Compare, etc...).
+
+ - Other operations: anything else, including Datastore
+ operations which do not change the access policy
+ enforced by the server.
+
+
+9.2 Semantics of Histories
+
+The semantics of histories are defined as follows:
+
+ - LDAP Update (Replace), LDAP Query
+
+ The Query will show that the subject has all rights
+ granted by the Update operation, and no rights not
+ granted by the Update operation.
+
+ - LDAP Update (Grant), LDAP Query
+
+ The Query will show that the subject has all rights
+ granted by the Update operation. The Query may show
+ that the subject also has other rights not granted by
+ the Update operation, depending on the policy in force
+ before the Update operation.
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 32]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+ - LDAP Update (Deny), LDAP Query
+
+ The Query will show that the subject does not have any
+ right denied by the Update operation. The Query may
+ show that the subject has rights not denied by the
+ Update operation, depending on the policy in force
+ before the Update operation.
+
+ - LDAP Update (Replace), LDAP Access Request
+
+ The Request will succeed if it requires only rights
+ granted to the requesting subject by the Update
+ operation. The Request will fail if it requires any
+ right not granted by the Update operation.
+
+ - LDAP Update (Grant), LDAP Access Request
+
+ The Request will succeed if it requires only rights
+ granted to the requesting subject by the Update
+ operation. The Request may succeed if it requires
+ rights not granted by the Update operation, depending
+ on the policy in force before the Update operation.
+
+ - LDAP Update (Deny), LDAP Access Request
+
+ The Request will fail if it requires any right denied
+ to the requesting subject by the Update operation. If
+ the Request requires only rights which were not denied
+ by the Update operation, it may succeed, depending on
+ the policy in force before the Update operation.
+
+ - LDAP Update (Replace), Other, LDAP Query
+
+ The Query will show that the subject has all rights
+ granted by the Update operation, and no rights not
+ granted by the Update operation.
+
+ - LDAP Update (Grant), Other, LDAP Query
+
+ The Query will show that the subject has all rights
+ granted by the Update operation. The Query may show
+ that the subject also has other rights not granted by
+ the Update operation, depending on the policy in force
+ before the Update operation.
+
+ - LDAP Update (Deny), Other, LDAP Query
+
+ The Query will show that the subject does not have any
+ right denied by the Update operation. The Query may
+ show that the subject has rights not denied by the
+ Update operation, depending on the policy in force
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 33]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+ before the Update operation.
+
+ - LDAP Update (Replace), Other, LDAP Access Request
+
+ The Request will succeed if it requires only rights
+ granted to the requesting subject by the Update
+ operation. The Request will fail if it requires any
+ right not granted by the Update operation.
+
+ - LDAP Update (Grant), Other, LDAP Access Request
+
+ The Request will succeed if it requires only rights
+ granted to the requesting subject by the Update
+ operation. The Request may succeed if it requires
+ rights not granted by the Update operation, depending
+ on the policy in force before the Update operation.
+
+ - LDAP Update (Deny), Other, LDAP Access Request
+
+ The Request will fail if it requires any right denied
+ to the requesting subject by the Update operation. If
+ the Request requires only rights which were not denied
+ by the Update operation, it may succeed, depending on
+ the policy in force before the Update operation.
+
+ - LDAP Update (Replace), Datastore Policy Update, LDAP
+ Query
+
+ The result of the Query is not defined.
+
+ - LDAP Update (Grant), Datastore Policy Update, LDAP
+ Query
+
+ The result of the Query is not defined.
+
+ - LDAP Update (Deny), Datastore Policy Update, LDAP Query
+
+ The result of the Query is not defined.
+
+ - LDAP Update (Replace), Datastore Policy Update, LDAP
+ Access Request
+
+ The result of the Access Request is not defined.
+
+ - LDAP Update (Grant), Datastore Policy Update, LDAP
+ Access Request
+
+ The result of the Access Request is not defined.
+
+ - LDAP Update (Deny), Datastore Policy Update, LDAP
+ Access Request
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 34]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+ The result of the Access Request is not defined.
+
+
+
+10. Access Control Parameters for LDAP Controls & Extended
+Operations
+
+This section defines the parameters used in the access
+control LDAP controls and extended operations in this
+document.
+
+targetDN specifies the initial directory entry in DN syntax
+on which the control or extended operation is performed.
+
+whichObject specifies whether the access control information
+(in the get effective rights control) which is retrieved is
+for the target directory entry (ENTRY) or the target
+directory entry and its subtree (SUBTREE).
+
+rights in the get effective rights control or extended
+operation response is of the form specified in the BNF for
+<rights>.
+
+subject is a LDAP string that defines the subject. Access
+control is get/set on a subject. The syntax of the subject
+is the same as the subject field in the BNF.
+
+
+
+11. Access Control Information (ACI) Controls
+
+The access control information controls provide a way to
+manipulate access control information in conjunction with a
+LDAP operation. One LDAP control is defined. This control
+allows access control information to be retrieved while
+manipulating other directory information for that entry.
+The control is:
+
+ - getEffectiveRights to obtain the effective rights for a
+ given directory entry(s) for a given subject during a
+ ldap_search operation
+
+11.1 getEffectiveRights Control
+
+
+11.1.1 Request Control
+
+This control may only be included in the ldap_search
+message as part of the controls field of the
+LDAPMessage, as defined in Section 4.1.12 of [LDAPv3].
+
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 35]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+The controlType is set to <OID to be assigned>. The
+criticality MAY be either TRUE or FALSE (where absent is
+also equivalent to FALSE) at the client's option. The
+controlValue is an OCTET STRING, whose value is the BER
+encoding of a value of the following SEQUENCE:
+
+ getEffectiveRightsRequest ::= SEQUENCE {
+ effectiveRightsRequest SEQUENCE OF SEQUENCE {
+ whichObject ENUMERATED {
+ LDAP_ENTRY (1),
+ LDAP_SUBTREE (2)
+ },
+ subject <see <subject > in BNF> | "*"
+ }
+ }
+
+The effectiveRightsRequest is a set of sequences that state
+the whichObject (entry or entry plus subtree) and specifics
+of the control request to be performed. A "*" in the subject
+field specifies that all DN types are to be used in
+returning the effective rights. This control is applied to
+the filter and scope set by the ldap_search operation, i.e.
+base, one-level, subtree. So the attributes/values returned
+are defined by the ldap_search operation.
+
+11.1.2 Response Control
+
+This control is included in the ldap_search_response message
+as part of the controls field of the LDAPMessage, as defined
+in Section 4.1.12 of [LDAPv3].
+
+The controlType is set to <OID to be assigned>. There is no
+need to set the criticality on the response. The
+controlValue is an OCTET STRING, whose value is the BER
+encoding of a value of the following SEQUENCE:
+
+ getEffectiveRightsResponse ::= {
+ result ENUMERATED {
+ success (0),
+ operationsError (1),
+ unavailableCriticalExtension (12),
+ noSuchAttribute (16),
+ undefinedAttributeType (17),
+ invalidAttributeSyntax (21),
+ insufficientRights (50),
+ unavailable (52),
+ unwillingToPerform (53),
+ other (80)
+ }
+ }
+
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 36]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+The effective rights returned are returned with each entry
+returned by the search result. The control response for
+ldap_search is:
+
+ PartialEffectiveRightsList ::= SEQUENCE OF SEQUENCE {
+ rights <see <rights> in BNF>,
+ whichObject ENUMERATED {
+ LDAP_ENTRY (1),
+ LDAP_SUBTREE (2)
+ },
+ subject < see <subject> in BNF >
+ }
+
+Although this extends the search operation, there are no
+incompatibilities between versions. LDAPv2 cannot send a
+control, hence the above structure cannot be returned to a
+LDAPv2 client. A LDAPv3 client cannot send this request to
+a LDAPv2 server. A LDAPv3 server not supporting this
+control cannot return the additional data.
+
+11.1.3 Client-Server Interaction
+
+The getEffectiveRightsRequest control requests the rights
+that MUST be in effect for requested directory
+entry/attribute based on the subject DN. The server that
+consumes the search operation looks up the rights for the
+returned directory information based on the subject DN and
+returns that rights information.
+
+There are six possible scenarios that may occur as a result
+of the getEffectiveRights control being included on the
+search request:
+
+
+ 1. If the server does not support this control and the
+ client specified TRUE for the control's criticality
+ field, then the server MUST return
+ unavailableCriticalExtension as a return code in the
+ searchResponse message and not send back any other
+ results. This behavior is specified in section 4.1.12
+ of [LDAPv3].
+
+ 2. If the server does not support this control and the
+ client specified FALSE for the control's criticality
+ field, then the server MUST ignore the control and
+ process the request as if it were not present. This
+ behavior is specified in section 4.1.12 of [LDAPv3].
+
+ 3. If the server supports this control but for some
+ reason such as cannot process specified family and the
+ client specified TRUE for the control's criticality
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 37]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+ field, then the server SHOULD do the following: return
+ unavailableCriticalExtension as a return code in the
+ searchResult message.
+
+ 4. If the server supports this control but for some
+ reason such as cannot process specified family and the
+ client specified FALSE for the control's criticality
+ field, then the server should process as 'no rights
+ returned for that family' and include the result
+ Unavailable in the getEffectiveRightsResponse control
+ in the searchResult message.
+
+ 5. If the server supports this control and can return the
+ rights per the family information, then it should
+ include the getEffectiveRightsResponse control in the
+ searchResult message with a result of success.
+
+ 6. If the search request failed for any other reason,
+ then the server SHOULD omit the
+ getEffectiveRightsResponse control from the
+ searchResult message.
+
+The client application is assured that the correct rights
+are returned for scope of the search operation if and only
+if the getEffectiveRightsResponse control returns the
+rights. If the server omits the getEffectiveRightsResponse
+control from the searchResult message, the client SHOULD
+assume that the control was ignored by the server.
+
+The getEffectiveRightsResponse control, if included by the
+server in the searchResponse message, should have the
+getEffectiveRightsResult set to either success if the rights
+are returned or set to the appropriate error code as to why
+the rights could not be returned.
+
+The server may not be able to return a right because it may
+not exist in that directory object's attribute; in this
+case, the rights request is ignored with success.
+
+
+12. Access Control Extended Operation
+
+An extended operation, get effective rights, is defined to
+obtain the effective rights for a given directory entry for
+a given subject. This operation may help with the
+management of access control information independent of
+manipulating other directory information.
+
+
+
+
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 38]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+12.1 LDAP Get Effective Rights Operation
+
+ldapGetEffectiveRightsRequest ::= [APPLICATION 23] SEQUENCE
+{
+ requestName [0] <OID to be assigned>,
+ requestValue [1] OCTET STRING OPTIONAL }
+
+ where
+
+ requestValue ::= SEQUENCE {
+ targetDN LDAPDN,
+ updates SEQUENCE OF SEQUENCE {
+ whichObject ENUMERATED {
+ LDAP_ENTRY (1),
+ LDAP_SUBTREE (2)
+ },
+ attr SEQUENCE {
+ attr <see <attr> in BNF >
+ },
+ subject < see <subject> in BNF > | "*"
+ }
+ }
+
+
+The requestName is a dotted-decimal representation of the
+OBJECT IDENTIFIER corresponding to the request. The
+requestValue is information in a form defined by that
+request, encapsulated inside an OCTET STRING.
+
+The server will respond to this with an LDAPMessage
+containing the ExtendedResponse which is a rights list.
+
+ldapGetEffectiveRightsResponse ::= [APPLICATION 24] SEQUENCE
+{
+ COMPONENTS OF LDAPResult,
+ responseName [10] <OID to be assigned> OPTIONAL,
+ effectiveRights [11] OCTET STRING OPTIONAL }
+
+ where
+
+ effectiveRights ::= SEQUENCE OF SEQUENCE {
+ rights <see <rights> in BNF>,
+ whichObject ENUMERATED {
+ LDAP_ENTRY (1),
+ LDAP_SUBTREE (2)
+ },
+ subject < see <subject> in BNF >
+ }
+
+If the server does not recognize the request name, it MUST
+return only the response fields from LDAPResult, containing
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 39]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+the protocolError result code.
+
+
+
+13. Security Considerations
+
+This document proposes protocol elements for transmission of
+security policy information. Security considerations are
+discussed throughout this draft. Because subject security
+attribute information is used to evaluate decision requests,
+it is security-sensitive information and must be protected
+against unauthorized modification whenever it is stored or
+transmitted.
+
+Interaction of access control with other directory functions
+(other than the ones defined in this document) are not
+defined in this document, but instead in the documents where
+those directory functions are defined. For example, the
+directory replication documents should address the
+interaction of access control with the replication function.
+
+
+
+14. References
+
+[LDAPv3] M. Wahl, T. Howes, S. Kille, "Lightweight Directory
+Access Protocol (v3)", RFC 2251, December 1997.
+
+[ECMA] ECMA, "Security in Open Systems: A Security
+Framework" ECMA TR/46, July 1988.
+
+[REQTS] Stokes, Byrne, Blakley, "Access Control Requirements
+for LDAP", RFC 2820, May 2000.
+
+[ATTR] M.Wahl, A, Coulbeck, T. Howes, S. Kille, "Lightweight
+Directory Access Protocol (v3)": Attribute Syntax
+Definitions, RFC 2252, December 1997.
+
+[UTF] M. Wahl, S. Kille, "Lightweight Directory Access
+Protocol (v3)": A UTF-8 String Representation of
+Distinguished Names", RFC 2253, December 1997.
+
+[Bradner97] Bradner, Scott, "Key Words for use in RFCs to
+Indicate Requirement Levels", RFC 2119.
+
+[AuthMeth] Wahl, M., Alvestrand, H., Hodges, J. and R.
+Morgan, "Authentication Methods for LDAP", RFC 2829, May
+2000.
+
+[ABNF] D. Crocker, P. Overell, "Augmented BNF for Syntax
+Specifications: ABNF", RFC 2234, November 1997.
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 40]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+ACKNOWLEDGEMENT
+
+This is to acknowledge the numerous companies and individuals who have
+contributed their valuable help and insights to the development of this
+specification.
+
+
+AUTHOR(S) ADDRESS
+
+ Ellen Stokes Bob Blakley
+ Tivoli Systems Tivoli Systems
+ 6300 Bridgepoint Parkway 6300 Bridgepoint Parkway
+ Austin, TX 78731 Austin, TX 78731
+ USA USA
+ mail-to: estokes at tivoli.com mail-to: blakley at tivoli.com
+ phone: +1 512 436 9098 phone: +1 512 436 1564
+ fax: +1 512 436 1199 fax: +1 512 436 1199
+
+
+ Debbie Rinkevich Robert Byrne
+ IBM Sun Microsystems
+ 11400 Burnet Rd 29 Chemin du Vieux Chene
+ Austin, TX 78758 Meylan ZIRST 38240
+ USA France
+ mail-to: djbrink at us.ibm.com mail-to: rbyrne at france.sun.com
+ phone: +1 512 838 1960 phone: +33 (0)4 76 41 42 05
+ fax: +1 512 838 8597
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 41]
+
+
+
+
+
+Internet-Draft Access Control Model 14 July 2000
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Stokes, et al Expires 14 January 2001 [Page 42]
+
+
+
+
+
+
+
+
+
+ CONTENTS
+
+
+ 1. Introduction....................................... 2
+
+ 2. The LDAPv3 Access Control Model.................... 2
+
+ 3. Access Control Mechanism Attributes................ 5
+ 3.1 Root DSE Attribute for Access Control
+ Mechanism.................................... 5
+ 3.2 Root DSE Attribute for Control of Disclosing
+ Errors....................................... 5
+ 3.3 Subentry Class Access Control Mechanism...... 6
+
+ 4. The Access Control Information Attribute
+ (ldapACI).......................................... 7
+ 4.1 The BNF...................................... 8
+ 4.1.1 ACI String Representation 8
+ 4.1.2 ACI Binary Representation 10
+ 4.2 The Components of ldapACI Attribute.......... 11
+ 4.2.1 Scope 11
+ 4.2.2 Access Rights and Permissions 11
+ 4.2.3 Attributes 14
+ 4.2.4 Subjects and Associated
+ Authentication 15
+ 4.3 Grant/Deny Evaluation Rules.................. 15
+
+ 5. Required Permissions for each LDAP Operation....... 17
+ 5.1 Bind Operation............................... 18
+ 5.2 Search Operation............................. 18
+ 5.3 Modify Operation............................. 21
+ 5.4 Add Operation................................ 22
+ 5.5 Delete Operation............................. 23
+ 5.6 Modify DN Operation.......................... 23
+ 5.7 Compare Operation............................ 24
+ 5.8 Abandon Operation............................ 25
+ 5.9 Extended Operation........................... 25
+
+ 6. Required Permissions for Handling Aliases and
+ References......................................... 25
+ 6.1 ACI Distribution............................. 25
+ 6.2 Aliases...................................... 26
+ 6.3 Referrals.................................... 26
+
+ 7. Controlling Access to Access Control
+ Information........................................ 27
+
+ 8. ACI Examples....................................... 27
+ 8.1 Attribute Definition......................... 27
+ 8.2 Modifying the ldapACI Values................. 28
+ 8.3 Evaluation................................... 30
+
+
+
+ - i -
+
+
+
+
+
+
+
+
+
+
+
+ 9. Operational Semantics of Access Control
+ Operations......................................... 31
+ 9.1 Types of actions............................. 32
+ 9.2 Semantics of Histories....................... 32
+
+10. Access Control Parameters for LDAP Controls &
+ Extended Operations................................ 35
+
+11. Access Control Information (ACI) Controls.......... 35
+ 11.1 getEffectiveRights Control................... 35
+ 11.1.1 Request Control 35
+ 11.1.2 Response Control 36
+ 11.1.3 Client-Server Interaction 37
+
+12. Access Control Extended Operation.................. 38
+ 12.1 LDAP Get Effective Rights Operation.......... 39
+
+13. Security Considerations............................ 40
+
+14. References......................................... 40
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ - ii -
+
+
+
+
+
+
+
+
+
+
+
+Full Copyright Statement
+
+Copyright (C) The Internet Society (2000).á All Rights
+Reserved.
+
+This document and translations of it may be copied and
+furnished to others, and derivative works that comment on or
+otherwise explain it or assist in its implementation may be
+prepared, copied, published and distributed, in whole or in
+part, without restriction of any kind, provided that the
+above copyright notice and this paragraph are included on
+all such copies and derivative works.á However, this
+document itself may not be modified in any way, such as by
+removing the copyright notice or references to the Internet
+Society or other Internet organizations, except as needed
+for the purpose of developing Internet standards in which
+case the procedures for copyrights defined in the Internet
+Standards process must be followed, or as required to
+translate it into languages other than English.
+
+The limited permissions granted above are perpetual and will
+not be revoked by the Internet Society or its successors or
+assigns.
+
+This document and the information contained herein is
+provided on an "AS IS" basis and THE INTERNET SOCIETY AND
+THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL
+WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
+ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT
+INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ - iii -
+
+
+
+
Added: openldap/vendor/openldap-release/doc/drafts/draft-ietf-ldapext-ldap-c-api-xx.txt
===================================================================
--- openldap/vendor/openldap-release/doc/drafts/draft-ietf-ldapext-ldap-c-api-xx.txt (rev 0)
+++ openldap/vendor/openldap-release/doc/drafts/draft-ietf-ldapext-ldap-c-api-xx.txt 2008-06-28 09:29:58 UTC (rev 1147)
@@ -0,0 +1,4647 @@
+
+
+Network Working Group M. Smith, Editor
+INTERNET-DRAFT Netscape Communications Corp.
+Intended Category: Standards Track T. Howes
+Obsoletes: RFC 1823 Loudcloud, Inc.
+Expires: May 2001 A. Herron
+ Microsoft Corp.
+ M. Wahl
+ Sun Microsystems, Inc.
+ A. Anantha
+ Microsoft Corp.
+
+
+ 17 November 2000
+
+ The C LDAP Application Program Interface
+ <draft-ietf-ldapext-ldap-c-api-05.txt>
+
+
+1. Status of this Memo
+
+This document is an Internet-Draft and is in full conformance with all
+provisions of Section 10 of RFC2026. Internet-Drafts are working docu-
+ments of the Internet Engineering Task Force (IETF), its areas, and its
+working groups. Note that other groups may also distribute working
+documents as Internet-Drafts.
+
+Internet-Drafts are draft documents valid for a maximum of six months
+and may be updated, replaced, or obsoleted by other documents at any
+time. It is inappropriate to use Internet-Drafts as reference material
+or to cite them other than as "work in progress."
+
+The list of current Internet-Drafts can be accessed at
+http://www.ietf.org/ietf/1id-abstracts.txt.
+
+The list of Internet-Draft Shadow Directories can be accessed at
+http://www.ietf.org/shadow.html.
+
+This draft document will be submitted to the RFC Editor as a Standards
+Track document. Distribution of this memo is unlimited. Technical dis-
+cussion of this document will take place on the IETF LDAP Extension
+Working Group mailing list <ietf-ldapext at netscape.com>. Please send
+editorial comments directly to the authors.
+
+Copyright (C) The Internet Society (1997-1999). All Rights Reserved.
+
+Please see the Copyright section near the end of this document for more
+information.
+
+
+
+
+Expires: May 2001 [Page 1]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+2. Introduction
+
+This document defines a C language application program interface (API)
+to the Lightweight Directory Access Protocol (LDAP). This document
+replaces the previous definition of this API, defined in RFC 1823,
+updating it to include support for features found in version 3 of the
+LDAP protocol. New extended operation functions were added to support
+LDAPv3 features such as controls. In addition, other LDAP API changes
+were made to support information hiding and thread safety.
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+document are to be interpreted as described in RFC 2119[1].
+
+The C LDAP API is designed to be powerful, yet simple to use. It defines
+compatible synchronous and asynchronous interfaces to LDAP to suit a
+wide variety of applications. This document gives a brief overview of
+the LDAP model, then an overview of how the API is used by an applica-
+tion program to obtain LDAP information. The API calls are described in
+detail, followed by appendices that provide example code demonstrating
+use of the API, the namespace consumed by the API, a summary of require-
+ments for API extensions, known incompatibilities with RFC 1823, and a
+list of changes made since the last revision of this document.
+
+
+3. Table of Contents
+
+1. Status of this Memo............................................1
+2. Introduction...................................................2
+3. Table of Contents..............................................2
+4. Overview of the LDAP Model.....................................4
+5. Overview of LDAP API Use and General Requirements..............4
+6. Header Requirements............................................6
+7. Common Data Structures and Types...............................7
+8. Memory Handling Overview.......................................9
+9. Retrieving Information About the API Implementation............9
+9.1. Retrieving Information at Compile Time......................10
+9.2. Retrieving Information During Execution.....................11
+10. Result Codes...................................................14
+11. Performing LDAP Operations.....................................16
+11.1. Initializing an LDAP Session................................16
+11.2. LDAP Session Handle Options.................................17
+11.3. Working With Controls.......................................23
+11.3.1. A Client Control That Governs Referral Processing........24
+11.4. Authenticating to the directory.............................25
+11.5. Closing the session.........................................27
+11.6. Searching...................................................28
+11.7. Reading an Entry............................................32
+
+
+
+Expires: May 2001 [Page 2]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+
+11.8. Listing the Children of an Entry............................32
+11.9. Comparing a Value Against an Entry..........................33
+11.10. Modifying an entry..........................................35
+11.11. Modifying the Name of an Entry..............................37
+11.12. Adding an entry.............................................39
+11.13. Deleting an entry...........................................41
+11.14. Extended Operations.........................................43
+12. Abandoning An Operation........................................44
+13. Obtaining Results and Peeking Inside LDAP Messages.............45
+14. Handling Errors and Parsing Results............................47
+15. Stepping Through a List of Results.............................51
+16. Parsing Search Results.........................................51
+16.1. Stepping Through a List of Entries or References............52
+16.2. Stepping Through the Attributes of an Entry.................53
+16.3. Retrieving the Values of an Attribute.......................54
+16.4. Retrieving the name of an entry.............................55
+16.5. Retrieving controls from an entry...........................56
+16.6. Parsing References..........................................57
+17. Encoded ASN.1 Value Manipulation...............................58
+17.1. BER Data Structures and Types...............................58
+17.2. Memory Disposal and Utility Functions.......................60
+17.3. Encoding....................................................60
+17.4. Encoding Example............................................63
+17.5. Decoding....................................................64
+17.6. Decoding Example............................................67
+18. Security Considerations........................................70
+19. Acknowledgements...............................................70
+20. Copyright......................................................70
+21. Bibliography...................................................71
+22. Authors' Addresses.............................................72
+23. Appendix A - Sample C LDAP API Code............................73
+24. Appendix B - Namespace Consumed By This Specification..........74
+25. Appendix C - Summary of Requirements for API Extensions........75
+25.1. Compatibility...............................................75
+25.2. Style.......................................................75
+25.3. Dependence on Externally Defined Types......................75
+25.4. Compile Time Information....................................76
+25.5. Runtime Information.........................................76
+25.6. Values Used for Session Handle Options......................76
+26. Appendix D - Known Incompatibilities with RFC 1823.............76
+26.1. Opaque LDAP Structure.......................................76
+26.2. Additional Result Codes.....................................77
+26.3. Freeing of String Data with ldap_memfree()..................77
+26.4. Changes to ldap_result()....................................77
+26.5. Changes to ldap_first_attribute() and ldap_next_attribute...77
+26.6. Changes to ldap_modrdn() and ldap_modrdn_s() Functions......78
+26.7. Changes to the berval structure.............................78
+26.8. API Specification Clarified.................................78
+
+
+Expires: May 2001 [Page 3]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+26.9. Deprecated Functions........................................78
+27. Appendix E - Data Types and Legacy Implementations.............79
+28. Appendix F - Changes Made Since Last Document Revision.........80
+28.1. API Changes.................................................80
+28.2. Editorial Changes and Clarifications........................81
+
+
+4. Overview of the LDAP Model
+
+LDAP is the lightweight directory access protocol, described in [2] and
+[3]. It can provide a lightweight frontend to the X.500 directory [4],
+or a stand-alone service. In either mode, LDAP is based on a client-
+server model in which a client makes a TCP connection to an LDAP server,
+over which it sends requests and receives responses.
+
+The LDAP information model is based on the entry, which contains infor-
+mation about some object (e.g., a person). Entries are composed of
+attributes, which have a type and one or more values. Each attribute has
+a syntax that determines what kinds of values are allowed in the attri-
+bute (e.g., ASCII characters, a jpeg photograph, etc.) and how those
+values behave during directory operations (e.g., is case significant
+during comparisons).
+
+Entries may be organized in a tree structure, usually based on politi-
+cal, geographical, and organizational boundaries. Each entry is uniquely
+named relative to its sibling entries by its relative distinguished name
+(RDN) consisting of one or more distinguished attribute values from the
+entry. At most one value from each attribute may be used in the RDN.
+For example, the entry for the person Babs Jensen might be named with
+the "Barbara Jensen" value from the commonName attribute.
+
+A globally unique name for an entry, called a distinguished name or DN,
+is constructed by concatenating the sequence of RDNs from the entry up
+to the root of the tree. For example, if Babs worked for the University
+of Michigan, the DN of her U-M entry might be "cn=Barbara Jensen,
+o=University of Michigan, c=US". The DN format used by LDAP is defined
+in [5].
+
+Operations are provided to authenticate, search for and retrieve infor-
+mation, modify information, and add and delete entries from the tree.
+The next sections give an overview of how the API is used and detailed
+descriptions of the LDAP API calls that implement all of these func-
+tions.
+
+
+5. Overview of LDAP API Use and General Requirements
+
+An application generally uses the C LDAP API in four simple steps.
+
+
+
+Expires: May 2001 [Page 4]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ 1. Initialize an LDAP session with a primary LDAP server. The
+ ldap_init() function returns a handle to the session, allowing
+ multiple connections to be open at once.
+
+ 2. Authenticate to the LDAP server. The ldap_sasl_bind() function
+ and friends support a variety of authentication methods.
+
+ 3. Perform some LDAP operations and obtain some results.
+ ldap_search() and friends return results which can be parsed by
+ ldap_parse_result(), ldap_first_entry(), ldap_next_entry(), etc.
+
+ 4. Close the session. The ldap_unbind() function closes the connec-
+ tion.
+
+Operations can be performed either synchronously or asynchronously. The
+names of the synchronous functions end in _s. For example, a synchronous
+search can be completed by calling ldap_search_s(). An asynchronous
+search can be initiated by calling ldap_search(). All synchronous rou-
+tines return an indication of the outcome of the operation (e.g, the
+constant LDAP_SUCCESS or some other result code). The asynchronous rou-
+tines make available to the caller the message id of the operation ini-
+tiated. This id can be used in subsequent calls to ldap_result() to
+obtain the result(s) of the operation. An asynchronous operation can be
+abandoned by calling ldap_abandon() or ldap_abandon_ext(). Note that
+there is no requirement that an LDAP API implementation not block when
+handling asynchronous API functions; the term "asynchronous" as used in
+this document refers to the fact that the sending of LDAP requests can
+be separated from the receiving of LDAP responses.
+
+Results and errors are returned in an opaque structure called LDAPMes-
+sage. Routines are provided to parse this structure, step through
+entries and attributes returned, etc. Routines are also provided to
+interpret errors. Later sections of this document describe these rou-
+tines in more detail.
+
+LDAP version 3 servers can return referrals and references to other
+servers. By default, implementations of this API will attempt to follow
+referrals automatically for the application. This behavior can be dis-
+abled globally (using the ldap_set_option() call) or on a per-request
+basis through the use of a client control.
+
+All DN and string attribute values passed into or produced by this C
+LDAP API are represented using the character set of the underlying LDAP
+protocol version in use. When this API is used with LDAPv3, DN and
+string values are represented as UTF-8[6] characters. When this API is
+used with LDAPv2, the US-ASCII[7] or T.61[7] character set are used.
+Future documents MAY specify additional APIs supporting other character
+sets.
+
+
+
+Expires: May 2001 [Page 5]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+For compatibility with existing applications, implementations of this
+API will by default use version 2 of the LDAP protocol. Applications
+that intend to take advantage of LDAP version 3 features will need to
+use the ldap_set_option() call with a LDAP_OPT_PROTOCOL_VERSION to
+switch to version 3.
+
+Unless otherwise indicated, conformant implementations of this specifi-
+cation MUST implement all of the C LDAP API functions as described in
+this document, and they MUST use the function prototypes, macro defini-
+tions, and types defined in this document.
+
+Note that this API is designed for use in environments where the 'int'
+type is at least 32 bits in size.
+
+
+6. Header Requirements
+
+To promote portability of applications, the following requirements are
+imposed on the headers used by applications to access the services of
+this API:
+
+Name and Inclusion
+ Applications only need to include a single header named ldap.h
+ to access all of the API services described in this document.
+ Therefore, the following C source program MUST compile and exe-
+ cute without errors:
+
+ #include <ldap.h>
+
+ int
+ main()
+ {
+ return 0;
+ }
+
+ The ldap.h header MAY include other implementation-specific
+ headers.
+
+Implementations SHOULD also provide a header named lber.h to facilitate
+development of applications desiring compatibility with older LDAP
+implementations. The lber.h header MAY be empty. Old applications that
+include lber.h in order to use BER facilities will need to include
+ldap.h.
+
+
+Idempotence
+ All headers SHOULD be idempotent; that is, if they are included
+ more than once the effect is as if they had only been included
+
+
+
+Expires: May 2001 [Page 6]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ once.
+
+Must Be Included Before API Is Used
+ An application MUST include the ldap.h header before referencing
+ any of the function or type definitions described in this API
+ specification.
+
+Mutual Independence
+ Headers SHOULD be mutually independent with minimal dependence
+ on system or any other headers.
+
+Use of the 'const' Keyword
+ This API specification is defined in terms of ISO C[8]. It
+ makes use of function prototypes and the 'const' keyword. The
+ use of 'const' in this specification is limited to simple, non-
+ array function parameters to avoid forcing applications to
+ declare parameters and variables that accept return values from
+ LDAP API functions as 'const.' Implementations specifically
+ designed to be used with non-ISO C translators SHOULD provide
+ function declarations without prototypes or function prototypes
+ without specification of 'const' arguments.
+
+Definition of 'struct timeval'
+ This API specification uses the 'struct timeval' type. Imple-
+ mentations of this API MUST ensure that the struct timeval type
+ is by default defined as a consequence of including the ldap.h
+ header. Because struct timeval is usually defined in one or
+ more system headers, it is possible for header conflicts to
+ occur if ldap.h also defines it or arranges for it to be defined
+ by including another header. Therefore, applications MAY want
+ to arrange for struct timeval to be defined before they include
+ ldap.h. To support this, the ldap.h header MUST NOT itself
+ define struct timeval if the preprocessor symbol
+ LDAP_TYPE_TIMEVAL_DEFINED is defined before ldap.h is included.
+
+
+7. Common Data Structures and Types
+
+Data structures and types that are common to several LDAP API functions
+are defined here:
+
+ typedef struct ldap LDAP;
+
+ typedef struct ldapmsg LDAPMessage;
+
+ typedef struct berelement BerElement;
+
+ typedef <impl_len_t> ber_len_t;
+
+
+
+Expires: May 2001 [Page 7]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ typedef struct berval {
+ ber_len_t bv_len;
+ char *bv_val;
+ } BerValue;
+
+ struct timeval {
+ <impl_sec_t> tv_sec;
+ <impl_usec_t> tv_usec;
+ };
+
+The LDAP structure is an opaque data type that represents an LDAP ses-
+sion Typically this corresponds to a connection to a single server, but
+it MAY encompass several server connections in the face of LDAPv3 refer-
+rals.
+
+The LDAPMessage structure is an opaque data type that is used to return
+entry, reference, result, and error information. An LDAPMessage struc-
+ture can represent the beginning of a list, or chain of messages that
+consists of a series of entries, references, and result messages as
+returned by LDAP operations such as search. LDAP API functions such as
+ldap_parse_result() that operate on message chains that can contain more
+than one result message always operate on the first result message in
+the chain. See the "Obtaining Results and Peeking Inside LDAP Messages"
+section of this document for more information.
+
+The BerElement structure is an opaque data type that is used to hold
+data and state information about encoded data. It is described in more
+detail in the section "Encoded ASN.1 Value Manipulation" later in this
+document.
+
+The `ber_len_t' type is an unsigned integral data type that is large
+enough to contain the length of the largest piece of data supported by
+the API implementation. The `<impl_len_t>' in the `ber_len_t' typedef
+MUST be replaced with an appropriate type. The width (number of signi-
+ficant bits) of `ber_len_t' MUST be at least 32 and no larger than that
+of `unsigned long'. See the appendix "Data Types and Legacy Implementa-
+tions" for additional considerations.
+
+The BerValue structure is used to represent arbitrary binary data and
+its fields have the following meanings:
+
+bv_len Length of data in bytes.
+
+bv_val A pointer to the data itself.
+
+
+The timeval structure is used to represent an interval of time and its
+fields have the following meanings:
+
+
+
+Expires: May 2001 [Page 8]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+tv_sec Seconds component of time interval.
+
+tv_usec Microseconds component of time interval.
+
+Note that because the struct timeval definition typically is derived
+from a system header, the types used for the tv_sec and tv_usec com-
+ponents are implementation-specific integral types. Therefore,
+`<impl_sec_t>' and `<impl_usec_t>' in the struct timeval definition MUST
+be replaced with appropriate types. See the earlier section "Header
+Requirements" for more information on struct timeval.
+
+
+8. Memory Handling Overview
+
+All memory that is allocated by a function in this C LDAP API and
+returned to the caller SHOULD be disposed of by calling the appropriate
+"free" function provided by this API. The correct "free" function to
+call is documented in each section of this document where a function
+that allocates memory is described.
+
+Memory that is allocated through means outside of the C LDAP API MUST
+NOT be disposed of using a function provided by this API.
+
+If a pointer value passed to one of the C LDAP API "free" functions is
+NULL, graceful failure (i.e, ignoring of the NULL pointer) MUST occur.
+
+The complete list of "free" functions that are used to dispose of allo-
+cated memory is:
+
+ ber_bvecfree()
+ ber_bvfree()
+ ber_free()
+ ldap_control_free()
+ ldap_controls_free()
+ ldap_memfree()
+ ldap_msgfree()
+ ldap_value_free()
+ ldap_value_free_len()
+
+
+9. Retrieving Information About the API Implementation
+
+Applications developed to this specification need to be able to deter-
+mine information about the particular API implementation they are using
+both at compile time and during execution.
+
+
+
+
+
+
+Expires: May 2001 [Page 9]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+9.1. Retrieving Information at Compile Time
+
+All conformant implementations MUST include the following five defini-
+tions in a header so compile time tests can be done by LDAP software
+developers:
+
+ #define LDAP_API_VERSION level
+ #define LDAP_VERSION_MIN min-version
+ #define LDAP_VERSION_MAX max-version
+ #define LDAP_VENDOR_NAME "vend-name"
+ #define LDAP_VENDOR_VERSION vend-version
+
+where:
+
+ "level" is replaced with the RFC number given to this C LDAP API
+ specification when it is published as a standards track RFC.
+
+ min-version is replaced with the lowest LDAP protocol version sup-
+ ported by the implementation.
+
+ max-version is replaced with the highest LDAP protocol version sup-
+ ported by the implementation. This SHOULD be 3.
+
+ "vend-name" is replaced with a text string that identifies the
+ party that supplies the API implementation.
+
+ "vend-version" is a supplier-specific version number multiplied
+ times 100.
+
+Note that the LDAP_VENDOR_NAME macro SHOULD be defined as "" if no ven-
+dor name is available and the LDAP_VENDOR_VERSION macro SHOULD be
+defined as 0 if no vendor-specific version information is available.
+
+For example, if this specification is published as RFC 88888, Netscape
+Communication's version 4.0 implementation that supports LDAPv2 and v3
+might include macro definitions like these:
+
+ #define LDAP_API_VERSION 88888 /* RFC 88888 compliant */
+ #define LDAP_VERSION_MIN 2
+ #define LDAP_VERSION_MAX 3
+ #define LDAP_VENDOR_NAME "Netscape Communications Corp."
+ #define LDAP_VENDOR_VERSION 400 /* version 4.0 */
+
+and application code can test the C LDAP API version level using a
+construct such as this one:
+
+ #if (LDAP_API_VERSION >= 88888)
+ /* use features supported in RFC 88888 or later */
+
+
+
+Expires: May 2001 [Page 10]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ #endif
+
+Until such time as this document is published as an RFC, implementations
+SHOULD use the value 2000 plus the revision number of this draft for
+LDAP_API_VERSION. For example, the correct value for LDAP_API_VERSION
+for revision 05 of this draft is 2005.
+
+Documents that extend this specification SHOULD define a macro of the
+form:
+
+ #define LDAP_API_FEATURE_x level
+
+where "x" is replaced with a name (textual identifier) for the feature
+and "level" is replaced with the number of the RFC that specifies the
+API extension. The name SHOULD NOT begin with the string "X_".
+
+For example, if C LDAP API extensions for Transport Layer Security [9]
+were published in RFC 99999, that RFC might require conformant implemen-
+tations to define a macro like this:
+
+ #define LDAP_API_FEATURE_TLS 99999
+
+
+Private or experimental API extensions SHOULD be indicated by defining a
+macro of this same form where "x" (the extension's name) begins with the
+string "X_" and "level" is replaced with a integer number that is
+specific to the extension.
+
+It is RECOMMENDED that private or experimental API extensions use only
+the following prefixes for macros, types, and function names:
+ LDAP_X_
+ LBER_X_
+ ldap_x_
+ ber_x_
+and that these prefixes not be used by standard extensions.
+
+
+9.2. Retrieving Information During Execution
+
+The ldap_get_option() call (described in greater detail later in this
+document) can be used during execution in conjunction with an option
+parameter value of LDAP_OPT_API_INFO (0x00) to retrieve some basic
+information about the API and about the specific implementation being
+used. The ld parameter to ldap_get_option() can be either NULL or a
+valid LDAP session handle which was obtained by calling ldap_init().
+The optdata parameter to ldap_get_option() SHOULD be the address of an
+LDAPAPIInfo structure which is defined as follows:
+
+
+
+
+Expires: May 2001 [Page 11]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ typedef struct ldapapiinfo {
+ int ldapai_info_version; /* version of this struct (1) */
+ int ldapai_api_version; /* revision of API supported */
+ int ldapai_protocol_version; /* highest LDAP version supported */
+ char **ldapai_extensions; /* names of API extensions */
+ char *ldapai_vendor_name; /* name of supplier */
+ int ldapai_vendor_version; /* supplier-specific version times 100 */
+ } LDAPAPIInfo;
+
+In addition, API implementations MUST include the following macro defin-
+ition:
+
+ #define LDAP_API_INFO_VERSION 1
+
+Note that the ldapai_info_version field of the LDAPAPIInfo structure
+SHOULD be set to the value LDAP_API_INFO_VERSION (1) before calling
+ldap_get_option() so that it can be checked for consistency. All other
+fields are set by the ldap_get_option() function.
+
+The members of the LDAPAPIInfo structure are:
+
+ldapai_info_version
+ A number that identifies the version of the LDAPAPIInfo struc-
+ ture. This SHOULD be set to the value LDAP_API_INFO_VERSION
+ (1) before calling ldap_get_option(). If the value received
+ is not recognized by the API implementation, the
+ ldap_get_option() function sets ldapai_info_version to a valid
+ value that would be recognized, sets the ldapai_api_version to
+ the correct value, and returns an error without filling in any
+ of the other fields in the LDAPAPIInfo structure.
+
+ldapai_api_version
+ A number that matches that assigned to the C LDAP API RFC sup-
+ ported by the API implementation. This SHOULD match the value
+ of the LDAP_API_VERSION macro defined earlier.
+
+ldapai_protocol_version
+ The highest LDAP protocol version supported by the implementa-
+ tion. For example, if LDAPv3 is the highest version supported
+ then this field will be set to 3.
+
+ldapai_vendor_name
+ A zero-terminated string that contains the name of the party
+ that produced the LDAP API implementation. This field may be
+ set to NULL if no name is available. If non-NULL, the caller
+ is responsible for disposing of the memory occupied by passing
+ this pointer to ldap_memfree() which is described later in
+ this document. This value SHOULD match the value of the
+
+
+
+Expires: May 2001 [Page 12]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ LDAP_VENDOR_NAME macro described earlier in this document.
+
+ldapai_vendor_version
+ An implementation-specific version number multiplied by 100.
+ For example, if the implementation version is 4.0 then this
+ field will be set to 400. If no version information is avail-
+ able, this field will be set to 0. This value SHOULD match
+ the value of the LDAP_VENDOR_VERSION macro described earlier
+ in this document.
+
+ldapai_extensions
+ A NULL-terminated array of character strings that lists the
+ names of the API extensions supported by the LDAP API imple-
+ mentation. These names will typically match the textual iden-
+ tifiers that appear in the "x" portion of the
+ LDAP_API_FEATURE_x macros described above, although the pre-
+ cise value MUST be defined by documents that specify C LDAP
+ API extensions. If no API extensions are supported, this
+ field will be set to NULL. The caller is responsible for
+ disposing of the memory occupied by this array by passing it
+ to ldap_value_free() which is described later in this docu-
+ ment. To retrieve more information about a particular exten-
+ sion, the ldap_get_option() call can be used with an option
+ parameter value of LDAP_OPT_API_FEATURE_INFO (0x15). The opt-
+ data parameter to the ldap_get_option() SHOULD be the address
+ of an LDAPAPIFeatureInfo structure which is defined as fol-
+ lows:
+
+ typedef struct ldap_apifeature_info {
+ int ldapaif_info_version; /* version of this struct (1) */
+ char *ldapaif_name; /* name of supported feature */
+ int ldapaif_version; /* revision of supported feature */
+ } LDAPAPIFeatureInfo;
+
+ In addition, API implementations MUST include the following
+ macro definition:
+
+ #define LDAP_FEATURE_INFO_VERSION 1
+
+ Note that the ldapaif_info_version field of the LDAPAPI-
+ FeatureInfo structure SHOULD be set to the value
+ LDAP_FEATURE_INFO_VERSION (1) and the ldapaif_name field
+ SHOULD be set to the extension name string as described below
+ before ldap_get_option() is called. The call will fill in the
+ ldapaif_version field of the LDAPAPIFeatureInfo structure.
+
+ The members of the LDAPAPIFeatureInfo structure are:
+
+
+
+
+Expires: May 2001 [Page 13]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ ldapaif_info_version
+ A number that identifies the version of the LDAPAPI-
+ FeatureInfo structure. This SHOULD be set to the value
+ LDAP_FEATURE_INFO_VERSION (1) before calling
+ ldap_get_option(). If the value received is not recognized
+ by the API implementation, the ldap_get_option() function
+ sets ldapaif_info_version to a valid value that would be
+ recognized and returns an error without filling in the
+ ldapaif_version field in the LDAPAPIFeatureInfo structure.
+
+ ldapaif_name
+ The name of an extension, as returned in the
+ ldapai_extensions array of the LDAPAPIInfo structure and as
+ specified in the document that describes the extension.
+
+ ldapaif_version
+ This field will be set as a result of calling
+ ldap_get_option(). It is a number that matches that
+ assigned to the C LDAP API extension RFC supported for this
+ extension. For private or experimental API extensions, the
+ value is extension-specific. In either case, the value of
+ ldapaxi_ext_version SHOULD be identical to the value of the
+ LDAP_API_FEATURE_x macro defined for the extension
+ (described above).
+
+
+10. Result Codes
+
+Many of the LDAP API routines return result codes, some of which indi-
+cate local API errors and some of which are LDAP resultCodes that are
+returned by servers. All of the result codes are non-negative integers.
+Supported result codes are as follows (hexadecimal values are given in
+parentheses after the constant):
+
+ LDAP_SUCCESS (0x00)
+ LDAP_OPERATIONS_ERROR (0x01)
+ LDAP_PROTOCOL_ERROR (0x02)
+ LDAP_TIMELIMIT_EXCEEDED (0x03)
+ LDAP_SIZELIMIT_EXCEEDED (0x04)
+ LDAP_COMPARE_FALSE (0x05)
+ LDAP_COMPARE_TRUE (0x06)
+ LDAP_STRONG_AUTH_NOT_SUPPORTED (0x07)
+ LDAP_STRONG_AUTH_REQUIRED (0x08)
+ LDAP_REFERRAL (0x0a) -- new in LDAPv3
+ LDAP_ADMINLIMIT_EXCEEDED (0x0b) -- new in LDAPv3
+ LDAP_UNAVAILABLE_CRITICAL_EXTENSION (0x0c) -- new in LDAPv3
+ LDAP_CONFIDENTIALITY_REQUIRED (0x0d) -- new in LDAPv3
+ LDAP_SASL_BIND_IN_PROGRESS (0x0e) -- new in LDAPv3
+
+
+
+Expires: May 2001 [Page 14]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ LDAP_NO_SUCH_ATTRIBUTE (0x10)
+ LDAP_UNDEFINED_TYPE (0x11)
+ LDAP_INAPPROPRIATE_MATCHING (0x12)
+ LDAP_CONSTRAINT_VIOLATION (0x13)
+ LDAP_TYPE_OR_VALUE_EXISTS (0x14)
+ LDAP_INVALID_SYNTAX (0x15)
+ LDAP_NO_SUCH_OBJECT (0x20)
+ LDAP_ALIAS_PROBLEM (0x21)
+ LDAP_INVALID_DN_SYNTAX (0x22)
+ LDAP_IS_LEAF (0x23) -- not used in LDAPv3
+ LDAP_ALIAS_DEREF_PROBLEM (0x24)
+ LDAP_INAPPROPRIATE_AUTH (0x30)
+ LDAP_INVALID_CREDENTIALS (0x31)
+ LDAP_INSUFFICIENT_ACCESS (0x32)
+ LDAP_BUSY (0x33)
+ LDAP_UNAVAILABLE (0x34)
+ LDAP_UNWILLING_TO_PERFORM (0x35)
+ LDAP_LOOP_DETECT (0x36)
+ LDAP_NAMING_VIOLATION (0x40)
+ LDAP_OBJECT_CLASS_VIOLATION (0x41)
+ LDAP_NOT_ALLOWED_ON_NONLEAF (0x42)
+ LDAP_NOT_ALLOWED_ON_RDN (0x43)
+ LDAP_ALREADY_EXISTS (0x44)
+ LDAP_NO_OBJECT_CLASS_MODS (0x45)
+ LDAP_RESULTS_TOO_LARGE (0x46) -- reserved for CLDAP
+ LDAP_AFFECTS_MULTIPLE_DSAS (0x47) -- new in LDAPv3
+ LDAP_OTHER (0x50)
+ LDAP_SERVER_DOWN (0x51)
+ LDAP_LOCAL_ERROR (0x52)
+ LDAP_ENCODING_ERROR (0x53)
+ LDAP_DECODING_ERROR (0x54)
+ LDAP_TIMEOUT (0x55)
+ LDAP_AUTH_UNKNOWN (0x56)
+ LDAP_FILTER_ERROR (0x57)
+ LDAP_USER_CANCELLED (0x58)
+ LDAP_PARAM_ERROR (0x59)
+ LDAP_NO_MEMORY (0x5a)
+ LDAP_CONNECT_ERROR (0x5b)
+ LDAP_NOT_SUPPORTED (0x5c)
+ LDAP_CONTROL_NOT_FOUND (0x5d)
+ LDAP_NO_RESULTS_RETURNED (0x5e)
+ LDAP_MORE_RESULTS_TO_RETURN (0x5f)
+ LDAP_CLIENT_LOOP (0x60)
+ LDAP_REFERRAL_LIMIT_EXCEEDED (0x61)
+
+
+
+
+
+
+
+Expires: May 2001 [Page 15]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+11. Performing LDAP Operations
+
+This section describes each LDAP operation API call in detail. Most
+functions take a "session handle," a pointer to an LDAP structure con-
+taining per-connection information. Many routines return results in an
+LDAPMessage structure. These structures and others are described as
+needed below.
+
+
+11.1. Initializing an LDAP Session
+
+ldap_init() initializes a session with an LDAP server. The server is not
+actually contacted until an operation is performed that requires it,
+allowing various options to be set after initialization.
+
+ LDAP *ldap_init(
+ const char *hostname,
+ int portno
+ );
+
+Use of the following routine is deprecated:
+
+ LDAP *ldap_open(
+ const char *hostname,
+ int portno
+ );
+
+Unlike ldap_init(), ldap_open() attempts to make a server connection
+before returning to the caller. A more complete description can be
+found in RFC 1823.
+
+Parameters are:
+
+hostname Contains a space-separated list of hostnames or dotted strings
+ representing the IP address of hosts running an LDAP server to
+ connect to. Each hostname in the list MAY include a port number
+ which is separated from the host itself with a colon (:) char-
+ acter. The hosts will be tried in the order listed, stopping
+ with the first one to which a successful connection is made.
+
+ Note: A suitable representation for including a literal IPv6[10]
+ address in the hostname parameter is desired, but has not yet been
+ determined or implemented in practice.
+
+portno Contains the TCP port number to connect to. The default LDAP
+ port of 389 can be obtained by supplying the value zero (0) or
+ the macro LDAP_PORT (389). If a host includes a port number
+ then this parameter is ignored.
+
+
+
+Expires: May 2001 [Page 16]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ldap_init() and ldap_open() both return a "session handle," a pointer to
+an opaque structure that MUST be passed to subsequent calls pertaining
+to the session. These routines return NULL if the session cannot be ini-
+tialized in which case the operating system error reporting mechanism
+can be checked to see why the call failed.
+
+Note that if you connect to an LDAPv2 server, one of the LDAP bind calls
+described below SHOULD be completed before other operations can be per-
+formed on the session. LDAPv3 does not require that a bind operation be
+completed before other operations can be performed.
+
+The calling program can set various attributes of the session by calling
+the routines described in the next section.
+
+
+11.2. LDAP Session Handle Options
+
+The LDAP session handle returned by ldap_init() is a pointer to an
+opaque data type representing an LDAP session. In RFC 1823 this data
+type was a structure exposed to the caller, and various fields in the
+structure could be set to control aspects of the session, such as size
+and time limits on searches.
+
+In the interest of insulating callers from inevitable changes to this
+structure, these aspects of the session are now accessed through a pair
+of accessor functions, described below.
+
+ldap_get_option() is used to access the current value of various
+session-wide parameters. ldap_set_option() is used to set the value of
+these parameters. Note that some options are READ-ONLY and cannot be
+set; it is an error to call ldap_set_option() and attempt to set a
+READ-ONLY option.
+
+Note that if automatic referral following is enabled (the default), any
+connections created during the course of following referrals will
+inherit the options associated with the session that sent the original
+request that caused the referrals to be returned.
+
+ int ldap_get_option(
+ LDAP *ld,
+ int option,
+ void *outvalue
+ );
+
+ int ldap_set_option(
+ LDAP *ld,
+ int option,
+ const void *invalue
+
+
+
+Expires: May 2001 [Page 17]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ );
+
+ #define LDAP_OPT_ON (<impl_void_star_value>)
+ #define LDAP_OPT_OFF ((void *)0)
+
+ LDAP_OPT_ON MUST be defined as a non-null pointer to void; that is,
+ <impl_void_star_value> MUST be replaced with a non-null pointer to
+ void, e.g., one could use:
+ #define LDAP_OPT_ON ((void *)1)
+ if that value is safe to use on the architecture where the API is
+ implemented.
+
+Parameters are:
+
+ld The session handle. If this is NULL, a set of global defaults is
+ accessed. New LDAP session handles created with ldap_init() or
+ ldap_open() inherit their characteristics from these global
+ defaults.
+
+option The name of the option being accessed or set. This parameter
+ SHOULD be one of the following constants, which have the indi-
+ cated meanings. After the constant the actual hexadecimal value
+ of the constant is listed in parentheses.
+
+
+ LDAP_OPT_API_INFO (0x00)
+ Type for invalue parameter: not applicable (option is READ-ONLY)
+
+ Type for outvalue parameter: LDAPAPIInfo *
+
+ Description:
+ Used to retrieve some basic information about the LDAP API
+ implementation at execution time. See the section "Retriev-
+ ing Information About the API Implementation" above for more
+ information. This option is READ-ONLY and cannot be set.
+
+ LDAP_OPT_DEREF (0x02)
+ Type for invalue parameter: int *
+
+ Type for outvalue parameter: int *
+
+ Description:
+ Determines how aliases are handled during search. It SHOULD
+ have one of the following values: LDAP_DEREF_NEVER (0x00),
+ LDAP_DEREF_SEARCHING (0x01), LDAP_DEREF_FINDING (0x02), or
+ LDAP_DEREF_ALWAYS (0x03). The LDAP_DEREF_SEARCHING value
+ means aliases are dereferenced during the search but not when
+ locating the base object of the search. The
+
+
+
+Expires: May 2001 [Page 18]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ LDAP_DEREF_FINDING value means aliases are dereferenced when
+ locating the base object but not during the search. The
+ default value for this option is LDAP_DEREF_NEVER.
+
+ LDAP_OPT_SIZELIMIT (0x03)
+ Type for invalue parameter: int *
+
+ Type for outvalue parameter: int *
+
+ Description:
+ A limit on the number of entries to return from a search. A
+ value of LDAP_NO_LIMIT (0) means no limit. The default value
+ for this option is LDAP_NO_LIMIT.
+
+ LDAP_OPT_TIMELIMIT (0x04)
+ Type for invalue parameter: int *
+
+ Type for outvalue parameter: int *
+
+ Description:
+ A limit on the number of seconds to spend on a search. A
+ value of LDAP_NO_LIMIT (0) means no limit. The default value
+ for this option is LDAP_NO_LIMIT. This value is passed to
+ the server in the search request only; it does not affect how
+ long the C LDAP API implementation itself will wait locally
+ for search results. Note that the timeout parameter passed
+ to the ldap_search_ext_s() or ldap_result() functions can be
+ used to specify a limit on how long the API implementation
+ will wait for results.
+
+ LDAP_OPT_REFERRALS (0x08)
+ Type for invalue parameter: void * (LDAP_OPT_ON or LDAP_OPT_OFF)
+
+ Type for outvalue parameter: int *
+
+ Description:
+ Determines whether the LDAP library automatically follows
+ referrals returned by LDAP servers or not. It MAY be set to
+ one of the constants LDAP_OPT_ON or LDAP_OPT_OFF; any non-
+ NULL pointer value passed to ldap_set_option() enables this
+ option. When reading the current setting using
+ ldap_get_option(), a zero value means OFF and any non-zero
+ value means ON. By default, this option is ON.
+
+ LDAP_OPT_RESTART (0x09)
+ Type for invalue parameter: void * (LDAP_OPT_ON or LDAP_OPT_OFF)
+
+ Type for outvalue parameter: int *
+
+
+
+Expires: May 2001 [Page 19]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ Description:
+ Determines whether LDAP I/O operations are automatically res-
+ tarted if they abort prematurely. It MAY be set to one of the
+ constants LDAP_OPT_ON or LDAP_OPT_OFF; any non-NULL pointer
+ value passed to ldap_set_option() enables this option. When
+ reading the current setting using ldap_get_option(), a zero
+ value means OFF and any non-zero value means ON. This option
+ is useful if an LDAP I/O operation can be interrupted prema-
+ turely, for example by a timer going off, or other interrupt.
+ By default, this option is OFF.
+
+ LDAP_OPT_PROTOCOL_VERSION (0x11)
+ Type for invalue parameter: int *
+
+ Type for outvalue parameter: int *
+
+ Description:
+ This option indicates the version of the LDAP protocol used
+ when communicating with the primary LDAP server. It SHOULD be
+ one of the constants LDAP_VERSION2 (2) or LDAP_VERSION3 (3).
+ If no version is set the default is LDAP_VERSION2 (2).
+
+ LDAP_OPT_SERVER_CONTROLS (0x12)
+ Type for invalue parameter: LDAPControl **
+
+ Type for outvalue parameter: LDAPControl ***
+
+ Description:
+ A default list of LDAP server controls to be sent with each
+ request. See the Working With Controls section below.
+
+ LDAP_OPT_CLIENT_CONTROLS (0x13)
+ Type for invalue parameter: LDAPControl **
+
+ Type for outvalue parameter: LDAPControl ***
+
+ Description:
+ A default list of client controls that affect the LDAP ses-
+ sion. See the Working With Controls section below.
+
+ LDAP_OPT_API_FEATURE_INFO (0x15)
+ Type for invalue parameter: not applicable (option is READ-ONLY)
+
+ Type for outvalue parameter: LDAPAPIFeatureInfo *
+
+ Description:
+ Used to retrieve version information about LDAP API extended
+ features at execution time. See the section "Retrieving
+
+
+
+Expires: May 2001 [Page 20]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ Information About the API Implementation" above for more
+ information. This option is READ-ONLY and cannot be set.
+
+ LDAP_OPT_HOST_NAME (0x30)
+ Type for invalue parameter: char *
+
+ Type for outvalue parameter: char **
+
+ Description:
+ The host name (or list of hosts) for the primary LDAP server.
+ See the definition of the hostname parameter to ldap_init()
+ for the allowed syntax. Note that if the portno parameter
+ passed to ldap_init() is a value other than 0 or 389
+ (LDAP_PORT), this value SHOULD include a string like
+ ":portno" after each hostname or IP address that did not have
+ one in the original hostname parameter that was passed to
+ ldap_init(). For example, if this hostname value was passed
+ to ldap_init():
+
+ "ldap.example.com:389 ldap2.example.com"
+
+ and the portno parameter passed to ldap_init() was 6389, then
+ the value returned for the LDAP_OPT_HOST_NAME option SHOULD
+ be:
+
+ "ldap.example.com:389 ldap2.example.com:6389"
+
+
+ LDAP_OPT_RESULT_CODE (0x31)
+ Type for invalue parameter: int *
+
+ Type for outvalue parameter: int *
+
+ Description:
+ The most recent local (API generated) or server returned LDAP
+ result code that occurred for this session.
+
+ LDAP_OPT_ERROR_STRING (0x32)
+ Type for invalue parameter: char *
+
+ Type for outvalue parameter: char **
+
+ Description:
+ The message returned with the most recent LDAP error that
+ occurred for this session.
+
+ LDAP_OPT_MATCHED_DN (0x33)
+ Type for invalue parameter: char *
+
+
+
+Expires: May 2001 [Page 21]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ Type for outvalue parameter: char **
+
+ Description:
+ The matched DN value returned with the most recent LDAP error
+ that occurred for this session.
+
+
+outvalue The address of a place to put the value of the option. The
+ actual type of this parameter depends on the setting of the
+ option parameter. For outvalues of type char ** and LDAPCon-
+ trol **, a copy of the data that is associated with the LDAP
+ session ld is returned; callers should dispose of the memory by
+ calling ldap_memfree() or ldap_controls_free(), depending on
+ the type of data returned.
+
+invalue A pointer to the value the option is to be given. The actual
+ type of this parameter depends on the setting of the option
+ parameter. The data associated with invalue is copied by the
+ API implementation to allow callers of the API to dispose of or
+ otherwise change their copy of the data after a successful call
+ to ldap_set_option(). If a value passed for invalue is invalid
+ or cannot be accepted by the implementation, ldap_set_option()
+ should return -1 to indicate an error.
+
+Both ldap_get_option() and ldap_set_option() return 0 if successful and
+-1 if an error occurs. If -1 is returned by either function, a specific
+result code MAY be retrieved by calling ldap_get_option() with an option
+value of LDAP_OPT_RESULT_CODE. Note that there is no way to retrieve a
+more specific result code if a call to ldap_get_option() with an option
+value of LDAP_OPT_RESULT_CODE fails.
+
+When a call to ldap_get_option() succeeds, the API implementation MUST
+NOT change the state of the LDAP session handle or the state of the
+underlying implementation in a way that affects the behavior of future
+LDAP API calls. When a call to ldap_get_option() fails, the only ses-
+sion handle change permitted is setting the LDAP result code (as
+returned by the LDAP_OPT_RESULT_CODE option).
+
+When a call to ldap_set_option() fails, it MUST NOT change the state of
+the LDAP session handle or the state of the underlying implementation in
+a way that affects the behavior of future LDAP API calls.
+
+Standards track documents that extend this specification and specify new
+options SHOULD use values for option macros that are between 0x1000 and
+0x3FFF inclusive. Private and experimental extensions SHOULD use values
+for the option macros that are between 0x4000 and 0x7FFF inclusive. All
+values below 0x1000 and above 0x7FFF that are not defined in this docu-
+ment are reserved and SHOULD NOT be used. The following macro MUST be
+
+
+
+Expires: May 2001 [Page 22]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+defined by C LDAP API implementations to aid extension implementors:
+ #define LDAP_OPT_PRIVATE_EXTENSION_BASE 0x4000 /* to 0x7FFF inclusive */
+
+
+
+11.3. Working With Controls
+
+LDAPv3 operations can be extended through the use of controls. Controls
+can be sent to a server or returned to the client with any LDAP message.
+These controls are referred to as server controls.
+
+The LDAP API also supports a client-side extension mechanism through the
+use of client controls. These controls affect the behavior of the LDAP
+API only and are never sent to a server. A common data structure is
+used to represent both types of controls:
+
+ typedef struct ldapcontrol {
+ char *ldctl_oid;
+ struct berval ldctl_value;
+ char ldctl_iscritical;
+ } LDAPControl;
+
+The fields in the ldapcontrol structure have the following meanings:
+
+ldctl_oid The control type, represented as a string.
+
+ldctl_value The data associated with the control (if any). To
+ specify a zero-length value, set ldctl_value.bv_len to
+ zero and ldctl_value.bv_val to a zero-length string.
+ To indicate that no data is associated with the con-
+ trol, set ldctl_value.bv_val to NULL.
+
+ldctl_iscritical Indicates whether the control is critical of not. If
+ this field is non-zero, the operation will only be car-
+ ried out if the control is recognized by the server
+ and/or client. Note that the LDAP unbind and abandon
+ operations have no server response, so clients SHOULD
+ NOT mark server controls critical when used with these
+ two operations.
+
+Some LDAP API calls allocate an ldapcontrol structure or a NULL-
+terminated array of ldapcontrol structures. The following routines can
+be used to dispose of a single control or an array of controls:
+
+ void ldap_control_free( LDAPControl *ctrl );
+ void ldap_controls_free( LDAPControl **ctrls );
+If the ctrl or ctrls parameter is NULL, these calls do nothing.
+
+
+
+
+Expires: May 2001 [Page 23]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+A set of controls that affect the entire session can be set using the
+ldap_set_option() function (see above). A list of controls can also be
+passed directly to some LDAP API calls such as ldap_search_ext(), in
+which case any controls set for the session through the use of
+ldap_set_option() are ignored. Control lists are represented as a NULL-
+terminated array of pointers to ldapcontrol structures.
+
+Server controls are defined by LDAPv3 protocol extension documents; for
+example, a control has been proposed to support server-side sorting of
+search results [11].
+
+One client control is defined in this document (described in the follow-
+ing section). Other client controls MAY be defined in future revisions
+of this document or in documents that extend this API.
+
+
+11.3.1. A Client Control That Governs Referral Processing
+
+As described previously in the section "LDAP Session Handle Options,"
+applications can enable and disable automatic chasing of referrals on a
+session-wide basic by using the ldap_set_option() function with the
+LDAP_OPT_REFERRALS option. It is also useful to govern automatic refer-
+ral chasing on per-request basis. A client control with an OID of
+1.2.840.113556.1.4.616 exists to provide this functionality.
+
+ /* OID for referrals client control */
+ #define LDAP_CONTROL_REFERRALS "1.2.840.113556.1.4.616"
+
+ /* Flags for referrals client control value */
+ #define LDAP_CHASE_SUBORDINATE_REFERRALS 0x00000020U
+ #define LDAP_CHASE_EXTERNAL_REFERRALS 0x00000040U
+
+To create a referrals client control, the ldctl_oid field of an LDAPCon-
+trol structure MUST be set to LDAP_CONTROL_REFERRALS
+("1.2.840.113556.1.4.616") and the ldctl_value field MUST be set to a
+value that contains a set of flags. The ldctl_value.bv_len field MUST
+be set to sizeof(ber_uint_t), and the ldctl_value.bv_val field MUST
+point to a ber_uint_t which contains the flags value." The ber_uint_t
+type is define in the section "BER Data Structures and Types" below.
+
+The flags value can be set to zero to disable automatic chasing of
+referrals and LDAPv3 references altogether. Alternatively, the flags
+value can be set to the value LDAP_CHASE_SUBORDINATE_REFERRALS
+(0x00000020U) to indicate that only LDAPv3 search continuation refer-
+ences are to be automatically chased by the API implementation, to the
+value LDAP_CHASE_EXTERNAL_REFERRALS (0x00000040U) to indicate that only
+LDAPv3 referrals are to be automatically chased, or the logical OR of
+the two flag values (0x00000060U) to indicate that both referrals and
+
+
+
+Expires: May 2001 [Page 24]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+references are to be automatically chased.
+
+
+11.4. Authenticating to the directory
+
+The following functions are used to authenticate an LDAP client to an
+LDAP directory server.
+
+The ldap_sasl_bind() and ldap_sasl_bind_s() functions can be used to do
+general and extensible authentication over LDAP through the use of the
+Simple Authentication Security Layer [12]. The routines both take the
+dn to bind as, the method to use, as a dotted-string representation of
+an OID identifying the method, and a struct berval holding the creden-
+tials. The special constant value LDAP_SASL_SIMPLE (NULL) can be passed
+to request simple authentication, or the simplified routines
+ldap_simple_bind() or ldap_simple_bind_s() can be used.
+
+ int ldap_sasl_bind(
+ LDAP *ld,
+ const char *dn,
+ const char *mechanism,
+ const struct berval *cred,
+ LDAPControl **serverctrls,
+ LDAPControl **clientctrls,
+ int *msgidp
+ );
+
+ int ldap_sasl_bind_s(
+ LDAP *ld,
+ const char *dn,
+ const char *mechanism,
+ const struct berval *cred,
+ LDAPControl **serverctrls,
+ LDAPControl **clientctrls,
+ struct berval **servercredp
+ );
+
+ int ldap_simple_bind(
+ LDAP *ld,
+ const char *dn,
+ const char *passwd
+ );
+
+ int ldap_simple_bind_s(
+ LDAP *ld,
+ const char *dn,
+ const char *passwd
+ );
+
+
+
+Expires: May 2001 [Page 25]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ The use of the following routines is deprecated and more complete
+ descriptions can be found in RFC 1823:
+
+ int ldap_bind( LDAP *ld, const char *dn, const char *cred,
+ int method );
+
+ int ldap_bind_s( LDAP *ld, const char *dn, const char *cred,
+ int method );
+
+ int ldap_kerberos_bind( LDAP *ld, const char *dn );
+
+ int ldap_kerberos_bind_s( LDAP *ld, const char *dn );
+
+Parameters are:
+
+ld The session handle.
+
+dn The name of the entry to bind as. If NULL, a zero length
+ DN is sent to the server.
+
+mechanism Either LDAP_SASL_SIMPLE (NULL) to get simple authentica-
+ tion, or a text string identifying the SASL method.
+
+cred The credentials with which to authenticate. Arbitrary
+ credentials can be passed using this parameter. The format
+ and content of the credentials depends on the setting of
+ the mechanism parameter. If the cred parameter is NULL and
+ the mechanism is LDAP_SASL_SIMPLE, a zero-length octet
+ string is sent to the server in the simple credentials
+ field of the bind request. If the cred parameter is NULL
+ and the mechanism is anything else, no credentials are sent
+ to the server in the bind request.
+
+passwd For ldap_simple_bind(), the password that is sent to the
+ server in the simple credentials field of the bind request.
+ If NULL, a zero length password is sent to the server.
+
+serverctrls List of LDAP server controls, or NULL if no server controls
+ are used.
+
+clientctrls List of client controls, or NULL if no client controls are
+ used.
+
+msgidp This result parameter will be set to the message id of the
+ request if the ldap_sasl_bind() call succeeds. The value
+ is undefined if a value other than LDAP_SUCCESS is
+ returned.
+
+
+
+
+Expires: May 2001 [Page 26]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+servercredp This result parameter will be filled in with the creden-
+ tials passed back by the server for mutual authentication,
+ if given. An allocated berval structure is returned that
+ SHOULD be disposed of by calling ber_bvfree(). NULL SHOULD
+ be passed to ignore this field. If an API error occurs or
+ the server did not return any credentials, *servercredp is
+ set to NULL.
+
+Additional parameters for the deprecated routines are not described.
+Interested readers are referred to RFC 1823.
+
+The ldap_sasl_bind() function initiates an asynchronous bind operation
+and returns the constant LDAP_SUCCESS if the request was successfully
+sent, or another LDAP result code if not. See the section below on
+error handling for more information about possible errors and how to
+interpret them. If successful, ldap_sasl_bind() places the message id
+of the request in *msgidp. A subsequent call to ldap_result(), described
+below, can be used to obtain the result of the bind.
+
+The ldap_simple_bind() function initiates a simple asynchronous bind
+operation and returns the message id of the operation initiated. A sub-
+sequent call to ldap_result(), described below, can be used to obtain
+the result of the bind. In case of error, ldap_simple_bind() will return
+-1, setting the session error parameters in the LDAP structure appropri-
+ately.
+
+The synchronous ldap_sasl_bind_s() and ldap_simple_bind_s() functions
+both return the result of the operation, either the constant
+LDAP_SUCCESS if the operation was successful, or another LDAP result
+code if it was not. See the section below on error handling for more
+information about possible errors and how to interpret them.
+
+Note that if an LDAPv2 server is contacted, no other operations over the
+connection can be attempted before a bind call has successfully com-
+pleted.
+
+Subsequent bind calls can be used to re-authenticate over the same con-
+nection, and multistep SASL sequences can be accomplished through a
+sequence of calls to ldap_sasl_bind() or ldap_sasl_bind_s().
+
+
+11.5. Closing the session
+
+The following functions are used to unbind from the directory, close
+open connections, and dispose of the session handle.
+
+ int ldap_unbind_ext( LDAP *ld, LDAPControl **serverctrls,
+ LDAPControl **clientctrls );
+
+
+
+Expires: May 2001 [Page 27]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ int ldap_unbind( LDAP *ld );
+
+ int ldap_unbind_s( LDAP *ld );
+
+Parameters are:
+
+ld The session handle.
+
+serverctrls List of LDAP server controls, or NULL if no server controls
+ are to be used.
+
+clientctrls List of client controls, or NULL if no client controls are
+ to be used.
+
+The ldap_unbind_ext(), ldap_unbind() and ldap_unbind_s() all work syn-
+chronously in the sense that they send an unbind request to the server,
+close all open connections associated with the LDAP session handle, and
+dispose of all resources associated with the session handle before
+returning. Note, however, that there is no server response to an LDAP
+unbind operation. All three of the unbind functions return LDAP_SUCCESS
+(or another LDAP result code if the request cannot be sent to the LDAP
+server). After a call to one of the unbind functions, the session han-
+dle ld is invalid and it is illegal to make any further LDAP API calls
+using ld.
+
+The ldap_unbind() and ldap_unbind_s() functions behave identically. The
+ldap_unbind_ext() function allows server and client controls to be
+included explicitly, but note that since there is no server response to
+an unbind request there is no way to receive a response to a server con-
+trol sent with an unbind request.
+
+
+
+11.6. Searching
+
+The following functions are used to search the LDAP directory, returning
+a requested set of attributes for each entry matched. There are five
+variations.
+
+ int ldap_search_ext(
+ LDAP *ld,
+ const char *base,
+ int scope,
+ const char *filter,
+ char **attrs,
+ int attrsonly,
+ LDAPControl **serverctrls,
+ LDAPControl **clientctrls,
+
+
+
+Expires: May 2001 [Page 28]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ struct timeval *timeout,
+ int sizelimit,
+ int *msgidp
+ );
+
+ int ldap_search_ext_s(
+ LDAP *ld,
+ const char *base,
+ int scope,
+ const char *filter,
+ char **attrs,
+ int attrsonly,
+ LDAPControl **serverctrls,
+ LDAPControl **clientctrls,
+ struct timeval *timeout,
+ int sizelimit,
+ LDAPMessage **res
+ );
+
+ int ldap_search(
+ LDAP *ld,
+ const char *base,
+ int scope,
+ const char *filter,
+ char **attrs,
+ int attrsonly
+ );
+
+ int ldap_search_s(
+ LDAP *ld,
+ const char *base,
+ int scope,
+ const char *filter,
+ char **attrs,
+ int attrsonly,
+ LDAPMessage **res
+ );
+
+ int ldap_search_st(
+ LDAP *ld,
+ const char *base,
+ int scope,
+ const char *filter,
+ char **attrs,
+ int attrsonly,
+ struct timeval *timeout,
+ LDAPMessage **res
+ );
+
+
+
+Expires: May 2001 [Page 29]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+Parameters are:
+
+ld The session handle.
+
+base The dn of the entry at which to start the search. If NULL,
+ a zero length DN is sent to the server.
+
+scope One of LDAP_SCOPE_BASE (0x00), LDAP_SCOPE_ONELEVEL (0x01),
+ or LDAP_SCOPE_SUBTREE (0x02), indicating the scope of the
+ search.
+
+filter A character string as described in [13], representing the
+ search filter. The value NULL can be passed to indicate
+ that the filter "(objectclass=*)" which matches all entries
+ is to be used. Note that if the caller of the API is using
+ LDAPv2, only a subset of the filter functionality described
+ in [13] can be successfully used.
+
+attrs A NULL-terminated array of strings indicating which attri-
+ butes to return for each matching entry. Passing NULL for
+ this parameter causes all available user attributes to be
+ retrieved. The special constant string LDAP_NO_ATTRS
+ ("1.1") MAY be used as the only string in the array to
+ indicate that no attribute types are to be returned by the
+ server. The special constant string LDAP_ALL_USER_ATTRS
+ ("*") can be used in the attrs array along with the names
+ of some operational attributes to indicate that all user
+ attributes plus the listed operational attributes are to be
+ returned.
+
+attrsonly A boolean value that MUST be zero if both attribute types
+ and values are to be returned, and non-zero if only types
+ are wanted.
+
+timeout For the ldap_search_st() function, this specifies the local
+ search timeout value (if it is NULL, the timeout is infin-
+ ite). If a zero timeout (where tv_sec and tv_usec are both
+ zero) is passed, API implementations SHOULD return
+ LDAP_PARAM_ERROR.
+
+ For the ldap_search_ext() and ldap_search_ext_s() func-
+ tions, the timeout parameter specifies both the local
+ search timeout value and the operation time limit that is
+ sent to the server within the search request. Passing a
+ NULL value for timeout causes the default timeout stored in
+ the LDAP session handle (set by using ldap_set_option()
+ with the LDAP_OPT_TIMELIMIT parameter) to be sent to the
+ server with the request but an infinite local search
+
+
+
+Expires: May 2001 [Page 30]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ timeout to be used. If a zero timeout (where tv_sec and
+ tv_usec are both zero) is passed in, API implementations
+ SHOULD return LDAP_PARAM_ERROR. If a zero value for tv_sec
+ is used but tv_usec is non-zero, an operation time limit of
+ 1 SHOULD be passed to the LDAP server as the operation time
+ limit. For other values of tv_sec, the tv_sec value itself
+ SHOULD be passed to the LDAP server.
+
+sizelimit For the ldap_search_ext() and ldap_search_ext_s() calls,
+ this is a limit on the number of entries to return from the
+ search. A value of LDAP_NO_LIMIT (0) means no limit. A
+ value of LDAP_DEFAULT_SIZELIMIT (-1) means use the default
+ timeout from the LDAP session handle (which is set by cal-
+ ling ldap_set_option() with the LDAP_OPT_SIZELIMIT parame-
+ ter).
+
+res For the synchronous calls, this is a result parameter which
+ will contain the results of the search upon completion of
+ the call. If an API error occurs or no results are
+ returned, *res is set to NULL.
+
+serverctrls List of LDAP server controls, or NULL if no server controls
+ are to be used.
+
+clientctrls List of client controls, or NULL if no client controls are
+ to be used.
+
+msgidp This result parameter will be set to the message id of the
+ request if the ldap_search_ext() call succeeds. The value
+ is undefined if a value other than LDAP_SUCCESS is
+ returned.
+
+There are three options in the session handle ld which potentially
+affect how the search is performed. They are:
+
+ LDAP_OPT_SIZELIMIT
+ LDAP_OPT_TIMELIMIT
+ LDAP_OPT_DEREF
+
+These options are fully described in the earlier section "LDAP Session
+Handle Options."
+
+The ldap_search_ext() function initiates an asynchronous search opera-
+tion and returns the constant LDAP_SUCCESS if the request was success-
+fully sent, or another LDAP result code if not. See the section below
+on error handling for more information about possible errors and how to
+interpret them. If successful, ldap_search_ext() places the message id
+of the request in *msgidp. A subsequent call to ldap_result(), described
+
+
+
+Expires: May 2001 [Page 31]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+below, can be used to obtain the results from the search. These results
+can be parsed using the result parsing routines described in detail
+later.
+
+Similar to ldap_search_ext(), the ldap_search() function initiates an
+asynchronous search operation and returns the message id of the opera-
+tion initiated. As for ldap_search_ext(), a subsequent call to
+ldap_result(), described below, can be used to obtain the result of the
+bind. In case of error, ldap_search() will return -1, setting the ses-
+sion error parameters in the LDAP structure appropriately.
+
+The synchronous ldap_search_ext_s(), ldap_search_s(), and
+ldap_search_st() functions all return the result of the operation,
+either the constant LDAP_SUCCESS if the operation was successful, or
+another LDAP result code if it was not. See the section below on error
+handling for more information about possible errors and how to interpret
+them. Entries returned from the search (if any) are contained in the
+res parameter. This parameter is opaque to the caller. Entries, attri-
+butes, values, etc., can be extracted by calling the parsing routines
+described below. The results contained in res SHOULD be freed when no
+longer in use by calling ldap_msgfree(), described later.
+
+The ldap_search_ext() and ldap_search_ext_s() functions support LDAPv3
+server controls, client controls, and allow varying size and time limits
+to be easily specified for each search operation. The ldap_search_st()
+function is identical to ldap_search_s() except that it takes an addi-
+tional parameter specifying a local timeout for the search. The local
+search timeout is used to limit the amount of time the API implementa-
+tion will wait for a search to complete. After the local search timeout
+expires, the API implementation will send an abandon operation to abort
+the search operation.
+
+11.7. Reading an Entry
+
+LDAP does not support a read operation directly. Instead, this operation
+is emulated by a search with base set to the DN of the entry to read,
+scope set to LDAP_SCOPE_BASE, and filter set to "(objectclass=*)" or
+NULL. attrs contains the list of attributes to return.
+
+
+11.8. Listing the Children of an Entry
+
+LDAP does not support a list operation directly. Instead, this operation
+is emulated by a search with base set to the DN of the entry to list,
+scope set to LDAP_SCOPE_ONELEVEL, and filter set to "(objectclass=*)" or
+NULL. attrs contains the list of attributes to return for each child
+entry.
+
+
+
+
+Expires: May 2001 [Page 32]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+11.9. Comparing a Value Against an Entry
+
+The following routines are used to compare a given attribute value
+assertion against an LDAP entry. There are four variations:
+
+ int ldap_compare_ext(
+ LDAP *ld,
+ const char *dn,
+ const char *attr,
+ const struct berval *bvalue,
+ LDAPControl **serverctrls,
+ LDAPControl **clientctrls,
+ int *msgidp
+ );
+
+ int ldap_compare_ext_s(
+ LDAP *ld,
+ const char *dn,
+ const char *attr,
+ const struct berval *bvalue,
+ LDAPControl **serverctrls,
+ LDAPControl **clientctrls
+ );
+
+ int ldap_compare(
+ LDAP *ld,
+ const char *dn,
+ const char *attr,
+ const char *value
+ );
+
+ int ldap_compare_s(
+ LDAP *ld,
+ const char *dn,
+ const char *attr,
+ const char *value
+ );
+
+Parameters are:
+
+ld The session handle.
+
+dn The name of the entry to compare against. If NULL, a zero
+ length DN is sent to the server.
+
+attr The attribute to compare against.
+
+bvalue The attribute value to compare against those found in the
+
+
+
+Expires: May 2001 [Page 33]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ given entry. This parameter is used in the extended rou-
+ tines and is a pointer to a struct berval so it is possible
+ to compare binary values.
+
+value A string attribute value to compare against, used by the
+ ldap_compare() and ldap_compare_s() functions. Use
+ ldap_compare_ext() or ldap_compare_ext_s() if you need to
+ compare binary values.
+
+serverctrls List of LDAP server controls, or NULL if no server controls
+ are to be used.
+
+clientctrls List of client controls, or NULL if no client controls are
+ to be used.
+
+msgidp This result parameter will be set to the message id of the
+ request if the ldap_compare_ext() call succeeds. The value
+ is undefined if a value other than LDAP_SUCCESS is
+ returned.
+
+The ldap_compare_ext() function initiates an asynchronous compare opera-
+tion and returns the constant LDAP_SUCCESS if the request was success-
+fully sent, or another LDAP result code if not. See the section below
+on error handling for more information about possible errors and how to
+interpret them. If successful, ldap_compare_ext() places the message id
+of the request in *msgidp. A subsequent call to ldap_result(), described
+below, can be used to obtain the result of the compare.
+
+Similar to ldap_compare_ext(), the ldap_compare() function initiates an
+asynchronous compare operation and returns the message id of the opera-
+tion initiated. As for ldap_compare_ext(), a subsequent call to
+ldap_result(), described below, can be used to obtain the result of the
+bind. In case of error, ldap_compare() will return -1, setting the ses-
+sion error parameters in the LDAP structure appropriately.
+
+The synchronous ldap_compare_ext_s() and ldap_compare_s() functions both
+return the result of the operation: one of the constants
+LDAP_COMPARE_TRUE or LDAP_COMPARE_FALSE if the operation was successful,
+or another LDAP result code if it was not. See the section below on
+error handling for more information about possible errors and how to
+interpret them.
+
+The ldap_compare_ext() and ldap_compare_ext_s() functions support LDAPv3
+server controls and client controls.
+
+
+
+
+
+
+
+Expires: May 2001 [Page 34]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+11.10. Modifying an entry
+
+The following routines are used to modify an existing LDAP entry. There
+are four variations:
+
+ typedef union mod_vals_u {
+ char **modv_strvals;
+ struct berval **modv_bvals;
+ } mod_vals_u_t;
+
+ typedef struct ldapmod {
+ int mod_op;
+ char *mod_type;
+ mod_vals_u_t mod_vals;
+ } LDAPMod;
+ #define mod_values mod_vals.modv_strvals
+ #define mod_bvalues mod_vals.modv_bvals
+
+ int ldap_modify_ext(
+ LDAP *ld,
+ const char *dn,
+ LDAPMod **mods,
+ LDAPControl **serverctrls,
+ LDAPControl **clientctrls,
+ int *msgidp
+ );
+
+ int ldap_modify_ext_s(
+ LDAP *ld,
+ const char *dn,
+ LDAPMod **mods,
+ LDAPControl **serverctrls,
+ LDAPControl **clientctrls
+ );
+
+ int ldap_modify(
+ LDAP *ld,
+ const char *dn,
+ LDAPMod **mods
+ );
+
+ int ldap_modify_s(
+ LDAP *ld,
+ const char *dn,
+ LDAPMod **mods
+ );
+
+Parameters are:
+
+
+
+Expires: May 2001 [Page 35]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ld The session handle.
+
+dn The name of the entry to modify. If NULL, a zero length DN
+ is sent to the server.
+
+mods A NULL-terminated array of modifications to make to the
+ entry.
+
+serverctrls List of LDAP server controls, or NULL if no server controls
+ are to be used.
+
+clientctrls List of client controls, or NULL if no client controls are
+ to be used.
+
+msgidp This result parameter will be set to the message id of the
+ request if the ldap_modify_ext() call succeeds. The value
+ is undefined if a value other than LDAP_SUCCESS is
+ returned.
+
+The fields in the LDAPMod structure have the following meanings:
+
+mod_op The modification operation to perform. It MUST be one of
+ LDAP_MOD_ADD (0x00), LDAP_MOD_DELETE (0x01), or
+ LDAP_MOD_REPLACE (0x02). This field also indicates the
+ type of values included in the mod_vals union. It is logi-
+ cally ORed with LDAP_MOD_BVALUES (0x80) to select the
+ mod_bvalues form. Otherwise, the mod_values form is used.
+
+mod_type The type of the attribute to modify.
+
+mod_vals The values (if any) to add, delete, or replace. Only one of
+ the mod_values or mod_bvalues variants can be used,
+ selected by ORing the mod_op field with the constant
+ LDAP_MOD_BVALUES. mod_values is a NULL-terminated array of
+ zero-terminated strings and mod_bvalues is a NULL-
+ terminated array of berval structures that can be used to
+ pass binary values such as images.
+
+For LDAP_MOD_ADD modifications, the given values are added to the
+entry, creating the attribute if necessary.
+
+For LDAP_MOD_DELETE modifications, the given values are deleted from the
+entry, removing the attribute if no values remain. If the entire attri-
+bute is to be deleted, the mod_vals field can be set to NULL.
+
+For LDAP_MOD_REPLACE modifications, the attribute will have the listed
+values after the modification, having been created if necessary, or
+removed if the mod_vals field is NULL. All modifications are performed
+
+
+
+Expires: May 2001 [Page 36]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+in the order in which they are listed.
+
+The ldap_modify_ext() function initiates an asynchronous modify opera-
+tion and returns the constant LDAP_SUCCESS if the request was success-
+fully sent, or another LDAP result code if not. See the section below
+on error handling for more information about possible errors and how to
+interpret them. If successful, ldap_modify_ext() places the message id
+of the request in *msgidp. A subsequent call to ldap_result(), described
+below, can be used to obtain the result of the modify.
+
+Similar to ldap_modify_ext(), the ldap_modify() function initiates an
+asynchronous modify operation and returns the message id of the opera-
+tion initiated. As for ldap_modify_ext(), a subsequent call to
+ldap_result(), described below, can be used to obtain the result of the
+modify. In case of error, ldap_modify() will return -1, setting the ses-
+sion error parameters in the LDAP structure appropriately.
+
+The synchronous ldap_modify_ext_s() and ldap_modify_s() functions both
+return the result of the operation, either the constant LDAP_SUCCESS if
+the operation was successful, or another LDAP result code if it was not.
+See the section below on error handling for more information about pos-
+sible errors and how to interpret them.
+
+The ldap_modify_ext() and ldap_modify_ext_s() functions support LDAPv3
+server controls and client controls.
+
+
+11.11. Modifying the Name of an Entry
+
+In LDAPv2, the ldap_modrdn(), ldap_modrdn_s(), ldap_modrdn2(), and
+ldap_modrdn2_s() routines were used to change the name of an LDAP entry.
+They could only be used to change the least significant component of a
+name (the RDN or relative distinguished name). LDAPv3 provides the
+Modify DN protocol operation that allows more general name change
+access. The ldap_rename() and ldap_rename_s() routines are used to
+change the name of an entry, and the use of the ldap_modrdn(),
+ldap_modrdn_s(), ldap_modrdn2(), and ldap_modrdn2_s() routines is depre-
+cated.
+
+ int ldap_rename(
+ LDAP *ld,
+ const char *dn,
+ const char *newrdn,
+ const char *newparent,
+ int deleteoldrdn,
+ LDAPControl **serverctrls,
+ LDAPControl **clientctrls,
+ int *msgidp
+
+
+
+Expires: May 2001 [Page 37]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ );
+ int ldap_rename_s(
+ LDAP *ld,
+ const char *dn,
+ const char *newrdn,
+ const char *newparent,
+ int deleteoldrdn,
+ LDAPControl **serverctrls,
+ LDAPControl **clientctrls
+ );
+
+ The use of the following routines is deprecated and more complete
+ descriptions can be found in RFC 1823:
+
+ int ldap_modrdn(
+ LDAP *ld,
+ const char *dn,
+ const char *newrdn
+ );
+ int ldap_modrdn_s(
+ LDAP *ld,
+ const char *dn,
+ const char *newrdn
+ );
+ int ldap_modrdn2(
+ LDAP *ld,
+ const char *dn,
+ const char *newrdn,
+ int deleteoldrdn
+ );
+ int ldap_modrdn2_s(
+ LDAP *ld,
+ const char *dn,
+ const char *newrdn,
+ int deleteoldrdn
+ );
+
+Parameters are:
+
+ld The session handle.
+
+dn The name of the entry whose DN is to be changed. If NULL,
+ a zero length DN is sent to the server.
+
+newrdn The new RDN to give the entry.
+
+newparent The new parent, or superior entry. If this parameter is
+ NULL, only the RDN of the entry is changed. The root DN
+
+
+
+Expires: May 2001 [Page 38]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ SHOULD be specified by passing a zero length string, "".
+ The newparent parameter SHOULD always be NULL when using
+ version 2 of the LDAP protocol; otherwise the server's
+ behavior is undefined.
+
+deleteoldrdn This parameter only has meaning on the rename routines if
+ newrdn is different than the old RDN. It is a boolean
+ value, if non-zero indicating that the old RDN value(s) is
+ to be removed, if zero indicating that the old RDN value(s)
+ is to be retained as non-distinguished values of the entry.
+
+serverctrls List of LDAP server controls, or NULL if no server controls
+ are to be used.
+
+clientctrls List of client controls, or NULL if no client controls are
+ to be used.
+
+msgidp This result parameter will be set to the message id of the
+ request if the ldap_rename() call succeeds. The value is
+ undefined if a value other than LDAP_SUCCESS is returned.
+
+The ldap_rename() function initiates an asynchronous modify DN operation
+and returns the constant LDAP_SUCCESS if the request was successfully
+sent, or another LDAP result code if not. See the section below on
+error handling for more information about possible errors and how to
+interpret them. If successful, ldap_rename() places the DN message id
+of the request in *msgidp. A subsequent call to ldap_result(), described
+below, can be used to obtain the result of the rename.
+
+The synchronous ldap_rename_s() returns the result of the operation,
+either the constant LDAP_SUCCESS if the operation was successful, or
+another LDAP result code if it was not. See the section below on error
+handling for more information about possible errors and how to interpret
+them.
+
+The ldap_rename() and ldap_rename_s() functions both support LDAPv3
+server controls and client controls.
+
+
+11.12. Adding an entry
+
+The following functions are used to add entries to the LDAP directory.
+There are four variations:
+
+ int ldap_add_ext(
+ LDAP *ld,
+ const char *dn,
+ LDAPMod **attrs,
+
+
+
+Expires: May 2001 [Page 39]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ LDAPControl **serverctrls,
+ LDAPControl **clientctrls,
+ int *msgidp
+ );
+
+ int ldap_add_ext_s(
+ LDAP *ld,
+ const char *dn,
+ LDAPMod **attrs,
+ LDAPControl **serverctrls,
+ LDAPControl **clientctrls
+ );
+
+ int ldap_add(
+ LDAP *ld,
+ const char *dn,
+ LDAPMod **attrs
+ );
+
+ int ldap_add_s(
+ LDAP *ld,
+ const char *dn,
+ LDAPMod **attrs
+ );
+
+Parameters are:
+
+ld The session handle.
+
+dn The name of the entry to add. If NULL, a zero length DN is
+ sent to the server.
+
+attrs The entry's attributes, specified using the LDAPMod struc-
+ ture defined for ldap_modify(). The mod_type and mod_vals
+ fields MUST be filled in. The mod_op field is ignored
+ unless ORed with the constant LDAP_MOD_BVALUES, used to
+ select the mod_bvalues case of the mod_vals union.
+
+serverctrls List of LDAP server controls, or NULL if no server controls
+ are to be used.
+
+clientctrls List of client controls, or NULL if no client controls are
+ to be used.
+
+msgidp This result parameter will be set to the message id of the
+ request if the ldap_add_ext() call succeeds. The value is
+ undefined if a value other than LDAP_SUCCESS is returned.
+
+
+
+
+Expires: May 2001 [Page 40]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+Note that the parent of the entry being added must already exist or the
+parent must be empty (i.e., equal to the root DN) for an add to succeed.
+
+The ldap_add_ext() function initiates an asynchronous add operation and
+returns the constant LDAP_SUCCESS if the request was successfully sent,
+or another LDAP result code if not. See the section below on error han-
+dling for more information about possible errors and how to interpret
+them. If successful, ldap_add_ext() places the message id of the
+request in *msgidp. A subsequent call to ldap_result(), described below,
+can be used to obtain the result of the add.
+
+Similar to ldap_add_ext(), the ldap_add() function initiates an asyn-
+chronous add operation and returns the message id of the operation ini-
+tiated. As for ldap_add_ext(), a subsequent call to ldap_result(),
+described below, can be used to obtain the result of the add. In case of
+error, ldap_add() will return -1, setting the session error parameters
+in the LDAP structure appropriately.
+
+The synchronous ldap_add_ext_s() and ldap_add_s() functions both return
+the result of the operation, either the constant LDAP_SUCCESS if the
+operation was successful, or another LDAP result code if it was not.
+See the section below on error handling for more information about pos-
+sible errors and how to interpret them.
+
+The ldap_add_ext() and ldap_add_ext_s() functions support LDAPv3 server
+controls and client controls.
+
+
+
+11.13. Deleting an entry
+
+The following functions are used to delete a leaf entry from the LDAP
+directory. There are four variations:
+
+ int ldap_delete_ext(
+ LDAP *ld,
+ const char *dn,
+ LDAPControl **serverctrls,
+ LDAPControl **clientctrls,
+ int *msgidp
+ );
+
+ int ldap_delete_ext_s(
+ LDAP *ld,
+ const char *dn,
+ LDAPControl **serverctrls,
+ LDAPControl **clientctrls
+ );
+
+
+
+Expires: May 2001 [Page 41]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+
+ int ldap_delete(
+ LDAP *ld,
+ const char *dn
+ );
+
+ int ldap_delete_s(
+ LDAP *ld,
+ const char *dn
+ );
+
+Parameters are:
+
+ld The session handle.
+
+dn The name of the entry to delete. If NULL, a zero length DN
+ is sent to the server.
+
+serverctrls List of LDAP server controls, or NULL if no server controls
+ are to be used.
+
+clientctrls List of client controls, or NULL if no client controls are
+ to be used.
+
+msgidp This result parameter will be set to the message id of the
+ request if the ldap_delete_ext() call succeeds. The value
+ is undefined if a value other than LDAP_SUCCESS is
+ returned.
+
+Note that the entry to delete must be a leaf entry (i.e., it must have
+no children). Deletion of entire subtrees in a single operation is not
+supported by LDAP.
+
+The ldap_delete_ext() function initiates an asynchronous delete opera-
+tion and returns the constant LDAP_SUCCESS if the request was success-
+fully sent, or another LDAP result code if not. See the section below
+on error handling for more information about possible errors and how to
+interpret them. If successful, ldap_delete_ext() places the message id
+of the request in *msgidp. A subsequent call to ldap_result(), described
+below, can be used to obtain the result of the delete.
+
+Similar to ldap_delete_ext(), the ldap_delete() function initiates an
+asynchronous delete operation and returns the message id of the opera-
+tion initiated. As for ldap_delete_ext(), a subsequent call to
+ldap_result(), described below, can be used to obtain the result of the
+delete. In case of error, ldap_delete() will return -1, setting the ses-
+sion error parameters in the LDAP structure appropriately.
+
+
+
+
+Expires: May 2001 [Page 42]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+The synchronous ldap_delete_ext_s() and ldap_delete_s() functions both
+return the result of the operation, either the constant LDAP_SUCCESS if
+the operation was successful, or another LDAP result code if it was not.
+See the section below on error handling for more information about pos-
+sible errors and how to interpret them.
+
+The ldap_delete_ext() and ldap_delete_ext_s() functions support LDAPv3
+server controls and client controls.
+
+
+11.14. Extended Operations
+
+The ldap_extended_operation() and ldap_extended_operation_s() routines
+allow extended LDAP operations to be passed to the server, providing a
+general protocol extensibility mechanism.
+
+ int ldap_extended_operation(
+ LDAP *ld,
+ const char *requestoid,
+ const struct berval *requestdata,
+ LDAPControl **serverctrls,
+ LDAPControl **clientctrls,
+ int *msgidp
+ );
+
+ int ldap_extended_operation_s(
+ LDAP *ld,
+ const char *requestoid,
+ const struct berval *requestdata,
+ LDAPControl **serverctrls,
+ LDAPControl **clientctrls,
+ char **retoidp,
+ struct berval **retdatap
+ );
+
+Parameters are:
+
+ld The session handle.
+
+requestoid The dotted-OID text string naming the request.
+
+requestdata The arbitrary data needed by the operation (if NULL, no
+ data is sent to the server).
+
+serverctrls List of LDAP server controls, or NULL if no server controls
+ are to be used.
+
+clientctrls List of client controls, or NULL if no client controls are
+
+
+
+Expires: May 2001 [Page 43]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ to be used.
+
+msgidp This result parameter will be set to the message id of the
+ request if the ldap_extended_operation() call succeeds. The
+ value is undefined if a value other than LDAP_SUCCESS is
+ returned.
+
+retoidp Pointer to a character string that will be set to an allo-
+ cated, dotted-OID text string returned by the server. This
+ string SHOULD be disposed of using the ldap_memfree() func-
+ tion. If an API error occurs or no OID is returned by the
+ server, *retoidp is set to NULL.
+
+retdatap Pointer to a berval structure pointer that will be set an
+ allocated copy of the data returned by the server. This
+ struct berval SHOULD be disposed of using ber_bvfree(). If
+ an API error occurs or no data is returned by the server,
+ *retdatap is set to NULL.
+
+The ldap_extended_operation() function initiates an asynchronous
+extended operation and returns the constant LDAP_SUCCESS if the request
+was successfully sent, or another LDAP result code if not. See the sec-
+tion below on error handling for more information about possible errors
+and how to interpret them. If successful, ldap_extended_operation()
+places the message id of the request in *msgidp. A subsequent call to
+ldap_result(), described below, can be used to obtain the result of the
+extended operation which can be passed to ldap_parse_extended_result()
+to obtain the OID and data contained in the response.
+
+The synchronous ldap_extended_operation_s() function returns the result
+of the operation, either the constant LDAP_SUCCESS if the operation was
+successful, or another LDAP result code if it was not. See the section
+below on error handling for more information about possible errors and
+how to interpret them. The retoid and retdata parameters are filled in
+with the OID and data from the response.
+
+The ldap_extended_operation() and ldap_extended_operation_s() functions
+both support LDAPv3 server controls and client controls.
+
+
+12. Abandoning An Operation
+
+The following calls are used to abandon an operation in progress:
+
+ int ldap_abandon_ext(
+ LDAP *ld,
+ int msgid,
+ LDAPControl **serverctrls,
+
+
+
+Expires: May 2001 [Page 44]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ LDAPControl **clientctrls
+ );
+
+ int ldap_abandon(
+ LDAP *ld,
+ int msgid
+ );
+
+
+ld The session handle.
+
+msgid The message id of the request to be abandoned.
+
+serverctrls List of LDAP server controls, or NULL if no server controls
+ are to be used.
+
+clientctrls List of client controls, or NULL if no client controls are
+ to be used.
+
+ldap_abandon_ext() abandons the operation with message id msgid and
+returns the constant LDAP_SUCCESS if the abandon was successful or
+another LDAP result code if not. See the section below on error han-
+dling for more information about possible errors and how to interpret
+them.
+
+ldap_abandon() is identical to ldap_abandon_ext() except that it does
+not accept client or server controls and it returns zero if the abandon
+was successful, -1 otherwise.
+
+After a successful call to ldap_abandon() or ldap_abandon_ext(), results
+with the given message id are never returned from a subsequent call to
+ldap_result(). There is no server response to LDAP abandon operations.
+
+
+13. Obtaining Results and Peeking Inside LDAP Messages
+
+ldap_result() is used to obtain the result of a previous asynchronously
+initiated operation. Note that depending on how it is called,
+ldap_result() can actually return a list or "chain" of result messages.
+The ldap_result() function only returns messages for a single request,
+so for all LDAP operations other than search only one result message is
+expected; that is, the only time the "result chain" can contain more
+than one message is if results from a search operation are returned.
+Once a chain of messages has been returned to the caller, it is no
+longer tied in any caller-visible way to the LDAP request that produced
+it. However, it MAY be tied to the session handle. Therefore, a chain
+of messages returned by calling ldap_result() or by calling a synchro-
+nous search routine will never be affected by subsequent LDAP API calls
+
+
+
+Expires: May 2001 [Page 45]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+except for ldap_msgfree() (which is used to dispose of a chain of mes-
+sages) and the unbind calls (which dispose of a session handle):
+ldap_unbind(), ldap_unbind_s(), or ldap_unbind_ext(), or functions
+defined by extensions of this API.
+
+ldap_msgfree() frees the result messages (possibly an entire chain of
+messages) obtained from a previous call to ldap_result() or from a call
+to a synchronous search routine.
+
+ldap_msgtype() returns the type of an LDAP message.
+
+ldap_msgid() returns the message ID of an LDAP message.
+
+ int ldap_result(
+ LDAP *ld,
+ int msgid,
+ int all,
+ struct timeval *timeout,
+ LDAPMessage **res
+ );
+
+ int ldap_msgfree( LDAPMessage *res );
+
+ int ldap_msgtype( LDAPMessage *res );
+
+ int ldap_msgid( LDAPMessage *res );
+
+Parameters are:
+
+ld The session handle.
+
+msgid The message id of the operation whose results are to be
+ returned, the constant LDAP_RES_UNSOLICITED (0) if an unsoli-
+ cited result is desired, or or the constant LDAP_RES_ANY (-1)
+ if any result is desired.
+
+all Specifies how many messages will be retrieved in a single call
+ to ldap_result(). This parameter only has meaning for search
+ results. Pass the constant LDAP_MSG_ONE (0x00) to retrieve one
+ message at a time. Pass LDAP_MSG_ALL (0x01) to request that
+ all results of a search be received before returning all
+ results in a single chain. Pass LDAP_MSG_RECEIVED (0x02) to
+ indicate that all messages retrieved so far are to be returned
+ in the result chain.
+
+timeout A timeout specifying how long to wait for results to be
+ returned. A NULL value causes ldap_result() to block until
+ results are available. A timeout value of zero seconds
+
+
+
+Expires: May 2001 [Page 46]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ specifies a polling behavior.
+
+res For ldap_result(), a result parameter that will contain the
+ result(s) of the operation. If an API error occurs or no
+ results are returned, *res is set to NULL. For ldap_msgfree(),
+ the result chain to be freed, obtained from a previous call to
+ ldap_result(), ldap_search_s(), or ldap_search_st(). If res is
+ NULL, nothing is done and ldap_msgfree() returns zero.
+
+Upon successful completion, ldap_result() returns the type of the first
+result returned in the res parameter. This will be one of the following
+constants.
+
+ LDAP_RES_BIND (0x61)
+ LDAP_RES_SEARCH_ENTRY (0x64)
+ LDAP_RES_SEARCH_REFERENCE (0x73) -- new in LDAPv3
+ LDAP_RES_SEARCH_RESULT (0x65)
+ LDAP_RES_MODIFY (0x67)
+ LDAP_RES_ADD (0x69)
+ LDAP_RES_DELETE (0x6B)
+ LDAP_RES_MODDN (0x6D)
+ LDAP_RES_COMPARE (0x6F)
+ LDAP_RES_EXTENDED (0x78) -- new in LDAPv3
+
+ldap_result() returns 0 if the timeout expired and -1 if an error
+occurs, in which case the error parameters of the LDAP session handle
+will be set accordingly.
+
+ldap_msgfree() frees each message in the result chain pointed to by res
+and returns the type of the last message in the chain. If res is NULL,
+nothing is done and the value zero is returned.
+
+ldap_msgtype() returns the type of the LDAP message it is passed as a
+parameter. The type will be one of the types listed above, or -1 on
+error.
+
+ldap_msgid() returns the message ID associated with the LDAP message
+passed as a parameter, or -1 on error.
+
+
+14. Handling Errors and Parsing Results
+
+The following calls are used to extract information from results and
+handle errors returned by other LDAP API routines. Note that
+ldap_parse_sasl_bind_result() and ldap_parse_extended_result() must typ-
+ically be used in addition to ldap_parse_result() to retrieve all the
+result information from SASL Bind and Extended Operations respectively.
+
+
+
+
+Expires: May 2001 [Page 47]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ int ldap_parse_result(
+ LDAP *ld,
+ LDAPMessage *res,
+ int *errcodep,
+ char **matcheddnp,
+ char **errmsgp,
+ char ***referralsp,
+ LDAPControl ***serverctrlsp,
+ int freeit
+ );
+
+ int ldap_parse_sasl_bind_result(
+ LDAP *ld,
+ LDAPMessage *res,
+ struct berval **servercredp,
+ int freeit
+ );
+
+ int ldap_parse_extended_result(
+ LDAP *ld,
+ LDAPMessage *res,
+ char **retoidp,
+ struct berval **retdatap,
+ int freeit
+ );
+
+ #define LDAP_NOTICE_OF_DISCONNECTION "1.3.6.1.4.1.1466.20036"
+
+ char *ldap_err2string( int err );
+
+ The use of the following routines is deprecated and more complete
+ descriptions can be found in RFC 1823:
+
+ int ldap_result2error(
+ LDAP *ld,
+ LDAPMessage *res,
+ int freeit
+ );
+
+ void ldap_perror( LDAP *ld, const char *msg );
+
+Parameters are:
+
+ld The session handle.
+
+res The result of an LDAP operation as returned by
+ ldap_result() or one of the synchronous API operation
+ calls.
+
+
+
+Expires: May 2001 [Page 48]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+errcodep This result parameter will be filled in with the LDAP
+ resultCode field from the LDAPMessage message. This is the
+ indication from the server of the outcome of the operation.
+ NULL SHOULD be passed to ignore this field.
+
+matcheddnp If the server returned a matchedDN string to indicate how
+ much of a name passed in a request was recognized, this
+ result parameter will be filled in with that matchedDN
+ string. Otherwise, this field will be set to NULL. NULL
+ SHOULD be passed to ignore this field. The matched DN
+ string SHOULD be freed by calling ldap_memfree() which is
+ described later in this document. Note that the server may
+ return a zero length matchedDN (in which case *matchednp is
+ set to an allocated copy of "") which is different than not
+ returning a value at all (in which case *matcheddnp is set
+ to NULL).
+
+errmsgp This result parameter will be filled in with the contents
+ of the error message field from the LDAPMessage message.
+ The error message string SHOULD be freed by calling
+ ldap_memfree() which is described later in this document.
+ NULL SHOULD be passed to ignore this field.
+
+referralsp This result parameter will be filled in with the contents
+ of the referrals field from the LDAPMessage message, indi-
+ cating zero or more alternate LDAP servers where the
+ request is to be retried. The referrals array SHOULD be
+ freed by calling ldap_value_free() which is described later
+ in this document. NULL SHOULD be passed to ignore this
+ field. If no referrals were returned, *referralsp is set
+ to NULL.
+
+serverctrlsp This result parameter will be filled in with an allocated
+ array of controls copied out of the LDAPMessage message.
+ If serverctrlsp is NULL, no controls are returned. The
+ control array SHOULD be freed by calling
+ ldap_controls_free() which was described earlier. If no
+ controls were returned, *serverctrlsp is set to NULL.
+
+freeit A boolean that determines whether the res parameter is
+ disposed of or not. Pass any non-zero value to have these
+ routines free res after extracting the requested informa-
+ tion. This is provided as a convenience; you can also use
+ ldap_msgfree() to free the result later. If freeit is
+ non-zero, the entire chain of messages represented by res
+ is disposed of.
+
+servercredp For SASL bind results, this result parameter will be filled
+
+
+
+Expires: May 2001 [Page 49]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ in with the credentials passed back by the server for
+ mutual authentication, if given. An allocated berval struc-
+ ture is returned that SHOULD be disposed of by calling
+ ber_bvfree(). NULL SHOULD be passed to ignore this field.
+
+retoidp For extended results, this result parameter will be filled
+ in with the dotted-OID text representation of the name of
+ the extended operation response. This string SHOULD be
+ disposed of by calling ldap_memfree(). NULL SHOULD be
+ passed to ignore this field. If no OID was returned,
+ *retoidp is set to NULL. The LDAP_NOTICE_OF_DISCONNECTION
+ macro is defined as a convenience for clients that wish to
+ check an OID to see if it matches the one used for the
+ unsolicited Notice of Disconnection (defined in RFC 2251[2]
+ section 4.4.1).
+
+retdatap For extended results, this result parameter will be filled
+ in with a pointer to a struct berval containing the data in
+ the extended operation response. It SHOULD be disposed of
+ by calling ber_bvfree(). NULL SHOULD be passed to ignore
+ this field. If no data is returned, *retdatap is set to
+ NULL.
+
+err For ldap_err2string(), an LDAP result code, as returned by
+ ldap_parse_result() or another LDAP API call.
+
+Additional parameters for the deprecated routines are not described.
+Interested readers are referred to RFC 1823.
+
+The ldap_parse_result(), ldap_parse_sasl_bind_result(), and
+ldap_parse_extended_result() functions all skip over messages of type
+LDAP_RES_SEARCH_ENTRY and LDAP_RES_SEARCH_REFERENCE when looking for a
+result message to parse. They return the constant LDAP_SUCCESS if the
+result was successfully parsed and another LDAP API result code if not.
+If a value other than LDAP_SUCCESS is returned, the values of all the
+result parameters are undefined. Note that the LDAP result code that
+indicates the outcome of the operation performed by the server is placed
+in the errcodep ldap_parse_result() parameter. If a chain of messages
+that contains more than one result message is passed to these routines
+they always operate on the first result in the chain.
+
+ldap_err2string() is used to convert a numeric LDAP result code, as
+returned by ldap_parse_result(), ldap_parse_sasl_bind_result(),
+ldap_parse_extended_result() or one of the synchronous API operation
+calls, into an informative zero-terminated character string message
+describing the error. It returns a pointer to static data and it MUST
+NOT return NULL; the value returned is always a valid null-terminated
+"C" string.
+
+
+
+Expires: May 2001 [Page 50]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+15. Stepping Through a List of Results
+
+The ldap_first_message() and ldap_next_message() routines are used to
+step through the list of messages in a result chain returned by
+ldap_result(). For search operations, the result chain can actually
+include referral messages, entry messages, and result messages.
+ldap_count_messages() is used to count the number of messages returned.
+The ldap_msgtype() function, described above, can be used to distinguish
+between the different message types.
+
+ LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *res );
+
+ LDAPMessage *ldap_next_message( LDAP *ld, LDAPMessage *msg );
+
+ int ldap_count_messages( LDAP *ld, LDAPMessage *res );
+
+Parameters are:
+
+ld The session handle.
+
+res The result chain, as obtained by a call to one of the synchronous
+ search routines or ldap_result().
+
+msg The message returned by a previous call to ldap_first_message()
+ or ldap_next_message().
+
+ldap_first_message() and ldap_next_message() will return NULL when no
+more messages exist in the result set to be returned. NULL is also
+returned if an error occurs while stepping through the entries, in which
+case the error parameters in the session handle ld will be set to indi-
+cate the error.
+
+If successful, ldap_count_messages() returns the number of messages con-
+tained in a chain of results; if an error occurs such as the res parame-
+ter being invalid, -1 is returned. The ldap_count_messages() call can
+also be used to count the number of messages that remain in a chain if
+called with a message, entry, or reference returned by
+ldap_first_message(), ldap_next_message(), ldap_first_entry(),
+ldap_next_entry(), ldap_first_reference(), ldap_next_reference().
+
+
+16. Parsing Search Results
+
+The following calls are used to parse the entries and references
+returned by ldap_search() and friends. These results are returned in an
+opaque structure that MAY be accessed by calling the routines described
+below. Routines are provided to step through the entries and references
+returned, step through the attributes of an entry, retrieve the name of
+
+
+
+Expires: May 2001 [Page 51]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+an entry, and retrieve the values associated with a given attribute in
+an entry.
+
+
+16.1. Stepping Through a List of Entries or References
+
+The ldap_first_entry() and ldap_next_entry() routines are used to step
+through and retrieve the list of entries from a search result chain.
+The ldap_first_reference() and ldap_next_reference() routines are used
+to step through and retrieve the list of continuation references from a
+search result chain. ldap_count_entries() is used to count the number
+of entries returned. ldap_count_references() is used to count the number
+of references returned.
+
+ LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *res );
+
+ LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry );
+
+ LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *res );
+
+ LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *ref );
+
+ int ldap_count_entries( LDAP *ld, LDAPMessage *res );
+
+ int ldap_count_references( LDAP *ld, LDAPMessage *res );
+
+Parameters are:
+
+ld The session handle.
+
+res The search result, as obtained by a call to one of the synchro-
+ nous search routines or ldap_result().
+
+entry The entry returned by a previous call to ldap_first_entry() or
+ ldap_next_entry().
+
+ref The reference returned by a previous call to
+ ldap_first_reference() or ldap_next_reference().
+
+ldap_first_entry(), ldap_next_entry(), ldap_first_reference() and
+ldap_next_reference() all return NULL when no more entries or references
+exist in the result set to be returned. NULL is also returned if an
+error occurs while stepping through the entries or references, in which
+case the error parameters in the session handle ld will be set to indi-
+cate the error.
+
+ldap_count_entries() returns the number of entries contained in a chain
+of entries; if an error occurs such as the res parameter being invalid,
+
+
+
+Expires: May 2001 [Page 52]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+-1 is returned. The ldap_count_entries() call can also be used to count
+the number of entries that remain in a chain if called with a message,
+entry or reference returned by ldap_first_message(),
+ldap_next_message(), ldap_first_entry(), ldap_next_entry(),
+ldap_first_reference(), ldap_next_reference().
+
+ldap_count_references() returns the number of references contained in a
+chain of search results; if an error occurs such as the res parameter
+being invalid, -1 is returned. The ldap_count_references() call can
+also be used to count the number of references that remain in a chain.
+
+
+16.2. Stepping Through the Attributes of an Entry
+
+The ldap_first_attribute() and ldap_next_attribute() calls are used to
+step through the list of attribute types returned with an entry.
+
+ char *ldap_first_attribute(
+ LDAP *ld,
+ LDAPMessage *entry,
+ BerElement **ptr
+ );
+
+ char *ldap_next_attribute(
+ LDAP *ld,
+ LDAPMessage *entry,
+ BerElement *ptr
+ );
+
+ void ldap_memfree( char *mem );
+
+Parameters are:
+
+ld The session handle.
+
+entry The entry whose attributes are to be stepped through, as returned
+ by ldap_first_entry() or ldap_next_entry().
+
+ptr In ldap_first_attribute(), the address of a pointer used inter-
+ nally to keep track of the current position in the entry. In
+ ldap_next_attribute(), the pointer returned by a previous call to
+ ldap_first_attribute(). The BerElement type itself is an opaque
+ structure that is described in more detail later in this document
+ in the section "Encoded ASN.1 Value Manipulation".
+
+mem A pointer to memory allocated by the LDAP library, such as the
+ attribute type names returned by ldap_first_attribute() and
+ ldap_next_attribute, or the DN returned by ldap_get_dn(). If mem
+
+
+
+Expires: May 2001 [Page 53]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ is NULL, the ldap_memfree() call does nothing.
+
+ldap_first_attribute() and ldap_next_attribute() will return NULL when
+the end of the attributes is reached, or if there is an error, in which
+case the error parameters in the session handle ld will be set to indi-
+cate the error.
+
+Both routines return a pointer to an allocated buffer containing the
+current attribute name. This SHOULD be freed when no longer in use by
+calling ldap_memfree().
+
+ldap_first_attribute() will allocate and return in ptr a pointer to a
+BerElement used to keep track of the current position. This pointer MAY
+be passed in subsequent calls to ldap_next_attribute() to step through
+the entry's attributes. After a set of calls to ldap_first_attribute()
+and ldap_next_attribute(), if ptr is non-NULL, it SHOULD be freed by
+calling ber_free( ptr, 0 ). Note that it is very important to pass the
+second parameter as 0 (zero) in this call, since the buffer associated
+with the BerElement does not point to separately allocated memory.
+
+The attribute type names returned are suitable for passing in a call to
+ldap_get_values() and friends to retrieve the associated values.
+
+
+16.3. Retrieving the Values of an Attribute
+
+ldap_get_values() and ldap_get_values_len() are used to retrieve the
+values of a given attribute from an entry. ldap_count_values() and
+ldap_count_values_len() are used to count the returned values.
+ldap_value_free() and ldap_value_free_len() are used to free the values.
+
+ char **ldap_get_values(
+ LDAP *ld,
+ LDAPMessage *entry,
+ const char *attr
+ );
+
+ struct berval **ldap_get_values_len(
+ LDAP *ld,
+ LDAPMessage *entry,
+ const char *attr
+ );
+
+ int ldap_count_values( char **vals );
+
+ int ldap_count_values_len( struct berval **vals );
+
+ void ldap_value_free( char **vals );
+
+
+
+Expires: May 2001 [Page 54]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ void ldap_value_free_len( struct berval **vals );
+
+Parameters are:
+
+ld The session handle.
+
+entry The entry from which to retrieve values, as returned by
+ ldap_first_entry() or ldap_next_entry().
+
+attr The attribute whose values are to be retrieved, as returned by
+ ldap_first_attribute() or ldap_next_attribute(), or a caller-
+ supplied string (e.g., "mail").
+
+vals The values returned by a previous call to ldap_get_values() or
+ ldap_get_values_len().
+
+Two forms of the various calls are provided. The first form is only
+suitable for use with non-binary character string data. The second _len
+form is used with any kind of data.
+
+ldap_get_values() and ldap_get_values_len() return NULL if no values are
+found for attr or if an error occurs.
+
+ldap_count_values() and ldap_count_values_len() return -1 if an error
+occurs such as the vals parameter being invalid.
+
+If a NULL vals parameter is passed to ldap_value_free() or
+ldap_value_free_len(), nothing is done.
+
+Note that the values returned are dynamically allocated and SHOULD be
+freed by calling either ldap_value_free() or ldap_value_free_len() when
+no longer in use.
+
+
+16.4. Retrieving the name of an entry
+
+ldap_get_dn() is used to retrieve the name of an entry.
+ldap_explode_dn() and ldap_explode_rdn() are used to break up a name
+into its component parts. ldap_dn2ufn() is used to convert the name into
+a more "user friendly" format.
+
+ char *ldap_get_dn( LDAP *ld, LDAPMessage *entry );
+
+ char **ldap_explode_dn( const char *dn, int notypes );
+
+ char **ldap_explode_rdn( const char *rdn, int notypes );
+
+ char *ldap_dn2ufn( const char *dn );
+
+
+
+Expires: May 2001 [Page 55]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+Parameters are:
+
+ld The session handle.
+
+entry The entry whose name is to be retrieved, as returned by
+ ldap_first_entry() or ldap_next_entry().
+
+dn The dn to explode, such as returned by ldap_get_dn(). If NULL,
+ a zero length DN is used.
+
+rdn The rdn to explode, such as returned in the components of the
+ array returned by ldap_explode_dn(). If NULL, a zero length DN
+ is used.
+
+notypes A boolean parameter, if non-zero indicating that the dn or rdn
+ components are to have their type information stripped off
+ (i.e., "cn=Babs" would become "Babs").
+
+ldap_get_dn() will return NULL if there is some error parsing the dn,
+setting error parameters in the session handle ld to indicate the error.
+It returns a pointer to newly allocated space that the caller SHOULD
+free by calling ldap_memfree() when it is no longer in use. Note the
+format of the DNs returned is given by [5]. The root DN is returned as
+a zero length string ("").
+
+ldap_explode_dn() returns a NULL-terminated char * array containing the
+RDN components of the DN supplied, with or without types as indicated by
+the notypes parameter. The components are returned in the order they
+appear in the dn. The array returned SHOULD be freed when it is no
+longer in use by calling ldap_value_free().
+
+ldap_explode_rdn() returns a NULL-terminated char * array containing the
+components of the RDN supplied, with or without types as indicated by
+the notypes parameter. The components are returned in the order they
+appear in the rdn. The array returned SHOULD be freed when it is no
+longer in use by calling ldap_value_free().
+
+ldap_dn2ufn() converts the DN into the user friendly format described in
+[14]. The UFN returned is newly allocated space that SHOULD be freed by
+a call to ldap_memfree() when no longer in use.
+
+
+16.5. Retrieving controls from an entry
+
+ldap_get_entry_controls() is used to extract LDAP controls from an
+entry.
+
+
+
+
+
+Expires: May 2001 [Page 56]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ int ldap_get_entry_controls(
+ LDAP *ld,
+ LDAPMessage *entry,
+ LDAPControl ***serverctrlsp
+ );
+
+Parameters are:
+
+ld The session handle.
+
+entry The entry to extract controls from, as returned by
+ ldap_first_entry() or ldap_next_entry().
+
+serverctrlsp This result parameter will be filled in with an allocated
+ array of controls copied out of entry. The control array
+ SHOULD be freed by calling ldap_controls_free(). If ser-
+ verctrlsp is NULL, no controls are returned. If no con-
+ trols were returned, *serverctrlsp is set to NULL.
+
+ldap_get_entry_controls() returns an LDAP result code that indicates
+whether the reference could be successfully parsed (LDAP_SUCCESS if all
+goes well). If ldap_get_entry_controls() returns a value other than
+LDAP_SUCCESS, the value of the serverctrlsp output parameter is unde-
+fined.
+
+
+
+16.6. Parsing References
+
+ldap_parse_reference() is used to extract referrals and controls from a
+SearchResultReference message.
+
+
+ int ldap_parse_reference(
+ LDAP *ld,
+ LDAPMessage *ref,
+ char ***referralsp,
+ LDAPControl ***serverctrlsp,
+ int freeit
+ );
+
+Parameters are:
+
+ld The session handle.
+
+ref The reference to parse, as returned by ldap_result(),
+ ldap_first_reference(), or ldap_next_reference().
+
+
+
+
+Expires: May 2001 [Page 57]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+referralsp This result parameter will be filled in with an allocated
+ array of character strings. The elements of the array are
+ the referrals (typically LDAP URLs) contained in ref. The
+ array SHOULD be freed when no longer in used by calling
+ ldap_value_free(). If referralsp is NULL, the referral
+ URLs are not returned. If no referrals were returned,
+ *referralsp is set to NULL.
+
+serverctrlsp This result parameter will be filled in with an allocated
+ array of controls copied out of ref. The control array
+ SHOULD be freed by calling ldap_controls_free(). If ser-
+ verctrlsp is NULL, no controls are returned. If no con-
+ trols were returned, *serverctrlsp is set to NULL.
+
+freeit A boolean that determines whether the ref parameter is
+ disposed of or not. Pass any non-zero value to have this
+ routine free ref after extracting the requested informa-
+ tion. This is provided as a convenience; you can also use
+ ldap_msgfree() to free the result later.
+
+ldap_parse_reference() returns an LDAP result code that indicates
+whether the reference could be successfully parsed (LDAP_SUCCESS if all
+goes well). If a value other than LDAP_SUCCESS is returned, the value
+of the referralsp and serverctrlsp result parameters are undefined.
+
+
+
+17. Encoded ASN.1 Value Manipulation
+
+This section describes routines which MAY be used to encode and decode
+BER-encoded ASN.1 values, which are often used inside of control and
+extension values.
+
+With the exceptions of two new functions ber_flatten() and ber_init(),
+these functions are compatible with the University of Michigan LDAP 3.3
+implementation of BER.
+
+Note that the functions defined in this section all provide a method for
+determining success or failure but generally do not provide access to
+specific error codes. Therefore, applications that require precise
+error information when encoding or decoding ASN.1 values SHOULD NOT use
+these functions.
+
+
+17.1. BER Data Structures and Types
+
+The following additional integral types are defined for use in manipula-
+tion of BER encoded ASN.1 values:
+
+
+
+Expires: May 2001 [Page 58]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ typedef <impl_tag_t> ber_tag_t; /* for BER tags */
+
+ typedef <impl_int_t> ber_int_t; /* for BER ints, enums, and Booleans */
+
+ typedef <impl_unit_t> ber_uint_t; /* unsigned equivalent of ber_uint_t */
+
+ typedef <impl_slen_t> ber_slen_t; /* signed equivalent of ber_len_t */
+
+Note that the actual definition for these four integral types is imple-
+mentation specific; that is, `<impl_tag_t>', `<impl_int_t>',
+`<impl_uint_t>', and `<impl_slen_t>' MUST each be replaced with an
+appropriate implementation-specific type.
+
+The `ber_tag_t' type is an unsigned integral data type that is large
+enough to hold the largest BER tag supported by the API implementation.
+The width (number of significant bits) of `ber_tag_t' MUST be at least
+32, greater than or equal to that of `unsigned int' (so that integer
+promotions won't promote it to `int'), and no wider than that of
+`unsigned long'.
+
+The `ber_int_t' and `ber_uint_t' types are the signed and unsigned vari-
+ants of an integral type that is large enough to hold integers for pur-
+poses of BER encoding and decoding. The width of `ber_int_t' MUST be at
+least 32 and no larger than that of `long'.
+
+The `ber_slen_t' type is the signed variant of the `ber_len_t' integral
+type, i.e. if `ber_len_t' is unsigned long, then `ber_slen_t' is signed
+long. The `<impl_slen_t>' in the `ber_len_t' typedef MUST be replaced
+with an appropriate type. Note that `ber_slen_t' is not used directly
+in the C LDAP API but is provided for the convenience of application
+developers and for use by extensions to the API.
+
+ typedef struct berval {
+ ber_len_t bv_len;
+ char *bv_val;
+ } BerValue;
+
+As defined earlier in the section "Common Data Structures", a berval
+structure contains an arbitrary sequence of bytes and an indication of
+its length. The bv_len element is an unsigned integer. The bv_val is
+not necessarily zero-terminated. Applications MAY allocate their own
+berval structures.
+
+As defined earlier in the section "Common Data Structures", the BerEle-
+ment structure is an opaque structure:
+
+ typedef struct berelement BerElement;
+
+
+
+
+Expires: May 2001 [Page 59]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+It contains not only a copy of the encoded value, but also state infor-
+mation used in encoding or decoding. Applications cannot allocate their
+own BerElement structures. The internal state is neither thread-
+specific nor locked, so two threads SHOULD NOT manipulate the same
+BerElement value simultaneously.
+
+A single BerElement value cannot be used for both encoding and decoding.
+
+17.2. Memory Disposal and Utility Functions
+
+ void ber_bvfree( struct berval *bv );
+
+ber_bvfree() frees a berval structure returned from this API. Both the
+bv->bv_val string and the berval structure itself are freed. If bv is
+NULL, this call does nothing.
+
+ void ber_bvecfree( struct berval **bv );
+
+ber_bvecfree() frees an array of berval structures returned from this
+API. Each of the berval structures in the array are freed using
+ber_bvfree(), then the array itself is freed. If bv is NULL, this call
+does nothing.
+
+ struct berval *ber_bvdup( const struct berval *bv );
+
+ber_bvdup() returns a copy of a berval structure. The bv_val field in
+the returned berval structure points to a different area of memory than
+the bv_val field in the bv argument. The NULL pointer is returned on
+error (e.g. out of memory).
+
+ void ber_free( BerElement *ber, int fbuf );
+
+ber_free() frees a BerElement which is returned from the API calls
+ber_alloc_t() or ber_init(). Each BerElement SHOULD be freed by the
+caller. The second argument fbuf SHOULD always be set to 1 to ensure
+that the internal buffer used by the BER functions is freed as well as
+the BerElement container itself. If ber is NULL, this call does noth-
+ing.
+
+
+17.3. Encoding
+
+ BerElement *ber_alloc_t( int options );
+
+ber_alloc_t() constructs and returns BerElement. The NULL pointer is
+returned on error. The options field contains a bitwise-or of options
+which are to be used when generating the encoding of this BerElement.
+One option is defined and SHOULD always be supplied:
+
+
+
+Expires: May 2001 [Page 60]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ #define LBER_USE_DER 0x01
+
+When this option is present, lengths will always be encoded in the
+minimum number of octets. Note that this option does not cause values
+of sets to be rearranged in tag and byte order or default values to be
+removed, so these functions are not sufficient for generating DER output
+as defined in X.509 and X.680. If the caller takes responsibility for
+ordering values of sets correctly and removing default values, DER out-
+put as defined in X.509 and X.680 can be produced.
+
+Unrecognized option bits are ignored.
+
+The BerElement returned by ber_alloc_t() is initially empty. Calls to
+ber_printf() will append bytes to the end of the ber_alloc_t().
+
+ int ber_printf( BerElement *ber, const char *fmt, ... );
+
+The ber_printf() routine is used to encode a BER element in much the
+same way that sprintf() works. One important difference, though, is
+that state information is kept in the ber argument so that multiple
+calls can be made to ber_printf() to append to the end of the BER ele-
+ment. ber MUST be a pointer to a BerElement returned by ber_alloc_t().
+ber_printf() interprets and formats its arguments according to the for-
+mat string fmt. ber_printf() returns -1 if there is an error during
+encoding and a non-negative number if successful. As with sprintf(),
+each character in fmt refers to an argument to ber_printf().
+
+The format string can contain the following format characters:
+
+'t' Tag. The next argument is a ber_tag_t specifying the tag to
+ override the next element to be written to the ber. This works
+ across calls. The integer tag value SHOULD contain the tag
+ class, constructed bit, and tag value. For example, a tag of
+ "[3]" for a constructed type is 0xA3U. All implementations MUST
+ support tags that fit in a single octet (i.e., where the tag
+ value is less than 32) and they MAY support larger tags.
+
+'b' Boolean. The next argument is an ber_int_t, containing either 0
+ for FALSE or 0xff for TRUE. A boolean element is output. If
+ this format character is not preceded by the 't' format modif-
+ ier, the tag 0x01U is used for the element.
+
+'e' Enumerated. The next argument is a ber_int_t, containing the
+ enumerated value in the host's byte order. An enumerated ele-
+ ment is output. If this format character is not preceded by the
+ 't' format modifier, the tag 0x0AU is used for the element.
+
+'i' Integer. The next argument is a ber_int_t, containing the
+
+
+
+Expires: May 2001 [Page 61]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ integer in the host's byte order. An integer element is output.
+ If this format character is not preceded by the 't' format
+ modifier, the tag 0x02U is used for the element.
+
+'B' Bitstring. The next two arguments are a char * pointer to the
+ start of the bitstring, followed by a ber_len_t containing the
+ number of bits in the bitstring. A bitstring element is output,
+ in primitive form. If this format character is not preceded by
+ the 't' format modifier, the tag 0x03U is used for the element.
+
+'X' Reserved and not to be used. In older revisions of this specif-
+ ication,
+
+'n' Null. No argument is needed. An ASN.1 NULL element is output.
+ If this format character is not preceded by the 't' format
+ modifier, the tag 0x05U is used for the element.
+
+'o' Octet string. The next two arguments are a char *, followed by
+ a ber_len_t with the length of the string. The string MAY con-
+ tain null bytes and are do not have to be zero-terminated. An
+ octet string element is output, in primitive form. If this for-
+ mat character is not preceded by the 't' format modifier, the
+ tag 0x04U is used for the element.
+
+'s' Octet string. The next argument is a char * pointing to a
+ zero-terminated string. An octet string element in primitive
+ form is output, which does not include the trailing '\0' (null)
+ byte. If this format character is not preceded by the 't' format
+ modifier, the tag 0x04U is used for the element.
+
+'v' Several octet strings. The next argument is a char **, an array
+ of char * pointers to zero-terminated strings. The last element
+ in the array MUST be a NULL pointer. The octet strings do not
+ include the trailing '\0' (null) byte. Note that a construct
+ like '{v}' is used to get an actual SEQUENCE OF octet strings.
+ The 't' format modifier cannot be used with this format charac-
+ ter.
+
+'V' Several octet strings. A NULL-terminated array of struct berval
+ *'s is supplied. Note that a construct like '{V}' is used to
+ get an actual SEQUENCE OF octet strings. The 't' format modifier
+ cannot be used with this format character.
+
+'{' Begin sequence. No argument is needed. If this format charac-
+ ter is not preceded by the 't' format modifier, the tag 0x30U is
+ used.
+
+'}' End sequence. No argument is needed. The 't' format modifier
+
+
+
+Expires: May 2001 [Page 62]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ cannot be used with this format character.
+
+'[' Begin set. No argument is needed. If this format character is
+ not preceded by the 't' format modifier, the tag 0x31U is used.
+
+']' End set. No argument is needed. The 't' format modifier cannot
+ be used with this format character.
+
+Each use of a '{' format character SHOULD be matched by a '}' character,
+either later in the format string, or in the format string of a subse-
+quent call to ber_printf() for that BerElement. The same applies to the
+'[' and ']' format characters.
+
+Sequences and sets nest, and implementations of this API MUST maintain
+internal state to be able to properly calculate the lengths.
+
+ int ber_flatten( BerElement *ber, struct berval **bvPtr );
+
+The ber_flatten routine allocates a struct berval whose contents are a
+BER encoding taken from the ber argument. The bvPtr pointer points to
+the returned berval structure, which SHOULD be freed using ber_bvfree().
+This routine returns 0 on success and -1 on error.
+
+The ber_flatten API call is not present in U-M LDAP 3.3.
+
+The use of ber_flatten on a BerElement in which all '{' and '}' format
+modifiers have not been properly matched is an error (i.e., -1 will be
+returned by ber_flatten() if this situation is exists).
+
+
+17.4. Encoding Example
+
+The following is an example of encoding the following ASN.1 data type:
+
+ Example1Request ::= SEQUENCE {
+ s OCTET STRING, -- must be printable
+ val1 INTEGER,
+ val2 [0] INTEGER DEFAULT 0
+ }
+
+
+ int encode_example1(const char *s, ber_int_t val1, ber_int_t val2,
+ struct berval **bvPtr)
+ {
+ BerElement *ber;
+ int rc = -1;
+
+ *bvPtr = NULL; /* in case of error */
+
+
+
+Expires: May 2001 [Page 63]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ ber = ber_alloc_t(LBER_USE_DER);
+
+ if (ber == NULL) return -1;
+
+ if (ber_printf(ber,"{si",s,val1) == -1) {
+ goto done;
+ }
+
+ if (val2 != 0) {
+ if (ber_printf(ber,"ti",(ber_tag_t)0x80,val2) == -1) {
+ goto done;
+ }
+ }
+
+ if (ber_printf(ber,"}") == -1) {
+ goto done;
+ }
+
+ rc = ber_flatten(ber,bvPtr);
+
+ done:
+ ber_free(ber,1);
+ return rc;
+ }
+
+
+17.5. Decoding
+
+The following two macros are available to applications: LBER_ERROR and
+LBER_DEFAULT. Both of these macros MUST be #define'd as ber_tag_t
+integral values that are treated as invalid tags by the API implementa-
+tion. It is RECOMMENDED that the values of LBER_ERROR and LBER_DEFAULT
+be the same and that they be defined as values where all octets have the
+value 0xFF. ISO C guarantees that these definitions will work:
+
+ #define LBER_ERROR ((ber_tag_t)-1)
+ #define LBER_DEFAULT ((ber_tag_t)-1)
+
+The intent is that LBER_ERROR and LBER_DEFAULT are both defined as the
+integer value that has all octets set to 0xFF, as such a value is not a
+valid BER tag.
+
+ BerElement *ber_init( const struct berval *bv );
+
+The ber_init function constructs a BerElement and returns a new BerEle-
+ment containing a copy of the data in the bv argument. ber_init returns
+the NULL pointer on error.
+
+
+
+
+Expires: May 2001 [Page 64]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ ber_tag_t ber_scanf( BerElement *ber, const char *fmt, ... );
+
+The ber_scanf() routine is used to decode a BER element in much the same
+way that sscanf() works. One important difference, though, is that some
+state information is kept with the ber argument so that multiple calls
+can be made to ber_scanf() to sequentially read from the BER element.
+The ber argument SHOULD be a pointer to a BerElement returned by
+ber_init(). ber_scanf interprets the bytes according to the format
+string fmt, and stores the results in its additional arguments.
+ber_scanf() returns LBER_ERROR on error, and a different value on suc-
+cess. If an error occurred, the values of all the result parameters are
+undefined.
+
+The format string contains conversion specifications which are used to
+direct the interpretation of the BER element. The format string can
+contain the following characters:
+
+'a' Octet string. A char ** argument MUST be supplied. Memory is
+ allocated, filled with the contents of the octet string, zero-
+ terminated, and the pointer to the string is stored in the argu-
+ ment. The returned value SHOULD be freed using ldap_memfree.
+ The tag of the element MUST indicate the primitive form (con-
+ structed strings are not supported) but is otherwise ignored and
+ discarded during the decoding. This format cannot be used with
+ octet strings which could contain null bytes.
+
+'O' Octet string. A struct berval ** argument MUST be supplied,
+ which upon return points to an allocated struct berval contain-
+ ing the octet string and its length. ber_bvfree() SHOULD be
+ called to free the allocated memory. The tag of the element
+ MUST indicate the primitive form (constructed strings are not
+ supported) but is otherwise ignored during the decoding.
+
+'b' Boolean. A pointer to a ber_int_t MUST be supplied. The
+ ber_int_t value stored will be 0 for FALSE or nonzero for TRUE.
+ The tag of the element MUST indicate the primitive form but is
+ otherwise ignored during the decoding.
+
+'e' Enumerated. A pointer to a ber_int_t MUST be supplied. The
+ enumerated value stored will be in host byte order. The tag of
+ the element MUST indicate the primitive form but is otherwise
+ ignored during the decoding. ber_scanf() will return an error
+ if the value of the enumerated value cannot be stored in a
+ ber_int_t.
+
+'i' Integer. A pointer to a ber_int_t MUST be supplied. The
+ ber_int_t value stored will be in host byte order. The tag of
+ the element MUST indicate the primitive form but is otherwise
+
+
+
+Expires: May 2001 [Page 65]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ ignored during the decoding. ber_scanf() will return an error
+ if the integer cannot be stored in a ber_int_t.
+
+'B' Bitstring. A char ** argument MUST be supplied which will point
+ to the allocated bits, followed by a ber_len_t * argument, which
+ will point to the length (in bits) of the bitstring returned.
+ ldap_memfree SHOULD be called to free the bitstring. The tag of
+ the element MUST indicate the primitive form (constructed bit-
+ strings are not supported) but is otherwise ignored during the
+ decoding.
+
+'n' Null. No argument is needed. The element is verified to have a
+ zero-length value and is skipped. The tag is ignored.
+
+'t' Tag. A pointer to a ber_tag_t MUST be supplied. The ber_tag_t
+ value stored will be the tag of the next element in the BerEle-
+ ment ber, represented so it can be written using the 't' format
+ of ber_printf(). The decoding position within the ber argument
+ is unchanged by this; that is, the fact that the tag has been
+ retrieved does not affect future use of ber.
+
+'v' Several octet strings. A char *** argument MUST be supplied,
+ which upon return points to an allocated NULL-terminated array
+ of char *'s containing the octet strings. NULL is stored if the
+ sequence is empty. ldap_memfree SHOULD be called to free each
+ element of the array and the array itself. The tag of the
+ sequence and of the octet strings are ignored.
+
+'V' Several octet strings (which could contain null bytes). A
+ struct berval *** MUST be supplied, which upon return points to
+ a allocated NULL-terminated array of struct berval *'s contain-
+ ing the octet strings and their lengths. NULL is stored if the
+ sequence is empty. ber_bvecfree() can be called to free the
+ allocated memory. The tag of the sequence and of the octet
+ strings are ignored.
+
+'x' Skip element. The next element is skipped. No argument is
+ needed.
+
+'{' Begin sequence. No argument is needed. The initial sequence
+ tag and length are skipped.
+
+'}' End sequence. No argument is needed.
+
+'[' Begin set. No argument is needed. The initial set tag and
+ length are skipped.
+
+']' End set. No argument is needed.
+
+
+
+Expires: May 2001 [Page 66]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ ber_tag_t ber_peek_tag( BerElement *ber,
+ ber_len_t *lenPtr );
+
+ber_peek_tag() returns the tag of the next element to be parsed in the
+BerElement argument. The length of this element is stored in the
+*lenPtr argument. LBER_DEFAULT is returned if there is no further data
+to be read. The decoding position within the ber argument is unchanged
+by this call; that is, the fact that ber_peek_tag() has been called does
+not affect future use of ber.
+
+ ber_tag_t ber_skip_tag( BerElement *ber, ber_len_t *lenPtr );
+
+ber_skip_tag() is similar to ber_peek_tag(), except that the state
+pointer in the BerElement argument is advanced past the first tag and
+length, and is pointed to the value part of the next element. This rou-
+tine SHOULD only be used with constructed types and situations when a
+BER encoding is used as the value of an OCTET STRING. The length of the
+value is stored in *lenPtr.
+
+ ber_tag_t ber_first_element( BerElement *ber,
+ ber_len_t *lenPtr, char **opaquePtr );
+
+ ber_tag_t ber_next_element( BerElement *ber,
+ ber_len_t *lenPtr, char *opaque );
+
+ber_first_element() and ber_next_element() are used to traverse a SET,
+SET OF, SEQUENCE or SEQUENCE OF data value. ber_first_element() calls
+ber_skip_tag(), stores internal information in *lenPtr and *opaquePtr,
+and calls ber_peek_tag() for the first element inside the constructed
+value. LBER_DEFAULT is returned if the constructed value is empty.
+ber_next_element() positions the state at the start of the next element
+in the constructed type. LBER_DEFAULT is returned if there are no
+further values.
+
+The len and opaque values SHOULD NOT be used by applications other than
+as arguments to ber_next_element(), as shown in the example below.
+
+
+17.6. Decoding Example
+
+The following is an example of decoding an ASN.1 data type:
+
+ Example2Request ::= SEQUENCE {
+ dn OCTET STRING, -- must be printable
+ scope ENUMERATED { b (0), s (1), w (2) },
+ ali ENUMERATED { n (0), s (1), f (2), a (3) },
+ size INTEGER,
+ time INTEGER,
+
+
+
+Expires: May 2001 [Page 67]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ tonly BOOLEAN,
+ attrs SEQUENCE OF OCTET STRING, -- must be printable
+ [0] SEQUENCE OF SEQUENCE {
+ type OCTET STRING -- must be printable,
+ crit BOOLEAN DEFAULT FALSE,
+ value OCTET STRING
+ } OPTIONAL }
+
+ #define TAG_CONTROL_LIST 0xA0U /* context specific cons 0 */
+
+ int decode_example2(struct berval *bv)
+ {
+ BerElement *ber;
+ ber_len_t len;
+ ber_tag_t res;
+ ber_int_t scope, ali, size, time, tonly;
+ char *dn = NULL, **attrs = NULL;
+ int i,rc = 0;
+
+ ber = ber_init(bv);
+ if (ber == NULL) {
+ fputs("ERROR ber_init failed\n", stderr);
+ return -1;
+ }
+
+ res = ber_scanf(ber,"{aiiiib{v}",&dn,&scope,&ali,
+ &size,&time,&tonly,&attrs);
+
+ if (res == LBER_ERROR) {
+ fputs("ERROR ber_scanf failed\n", stderr);
+ ber_free(ber,1);
+ return -1;
+ }
+
+ /* *** use dn */
+ ldap_memfree(dn);
+
+ for (i = 0; attrs != NULL && attrs[i] != NULL; i++) {
+ /* *** use attrs[i] */
+ ldap_memfree(attrs[i]);
+ }
+ ldap_memfree((char *)attrs);
+
+ if (ber_peek_tag(ber,&len) == TAG_CONTROL_LIST) {
+ char *opaque;
+ ber_tag_t tag;
+
+ for (tag = ber_first_element(ber,&len,&opaque);
+
+
+
+Expires: May 2001 [Page 68]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ tag != LBER_DEFAULT;
+ tag = ber_next_element (ber,&len,opaque)) {
+
+ ber_len_t tlen;
+ ber_tag_t ttag;
+ char *type;
+ ber_int_t crit;
+ struct berval *value;
+
+ if (ber_scanf(ber,"{a",&type) == LBER_ERROR) {
+ fputs("ERROR cannot parse type\n", stderr);
+ break;
+ }
+ /* *** use type */
+ ldap_memfree(type);
+
+ ttag = ber_peek_tag(ber,&tlen);
+ if (ttag == 0x01U) { /* boolean */
+ if (ber_scanf(ber,"b",
+ &crit) == LBER_ERROR) {
+ fputs("ERROR cannot parse crit\n",
+ stderr);
+ rc = -1;
+ break;
+ }
+ } else if (ttag == 0x04U) { /* octet string */
+ crit = 0;
+ } else {
+ fputs("ERROR extra field in controls\n",
+ stderr );
+ break;
+ }
+
+ if (ber_scanf(ber,"O}",&value) == LBER_ERROR) {
+ fputs("ERROR cannot parse value\n", stderr);
+ rc = -1;
+ break;
+ }
+ /* *** use value */
+ ber_bvfree(value);
+ }
+ }
+
+ if ( rc == 0 ) { /* no errors so far */
+ if (ber_scanf(ber,"}") == LBER_ERROR) {
+ rc = -1;
+ }
+ }
+
+
+
+Expires: May 2001 [Page 69]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ ber_free(ber,1);
+
+ return rc;
+ }
+
+
+
+18. Security Considerations
+
+LDAPv2 supports security through protocol-level authentication using
+clear-text passwords. LDAPv3 adds support for SASL [12] (Simple Authen-
+tication Security Layer) methods. LDAPv3 also supports operation over a
+secure transport layer using Transport Layer Security TLS [9]. Readers
+are referred to the protocol documents for discussion of related secu-
+rity considerations.
+
+Implementations of this API SHOULD be cautious when handling authentica-
+tion credentials. In particular, keeping long-lived copies of creden-
+tials without the application's knowledge is discouraged.
+
+
+19. Acknowledgements
+
+Many members of the IETF ASID and LDAPEXT working groups as well as
+members of the Internet at large have provided useful comments and
+suggestions that have been incorporated into this document. Chris
+Weider deserves special mention for his contributions as co-author of
+earlier revisions of this document.
+
+The original material upon which this specification is based was sup-
+ported by the National Science Foundation under Grant No. NCR-9416667.
+
+
+20. Copyright
+
+Copyright (C) The Internet Society (1997-2000). All Rights Reserved.
+
+This document and translations of it may be copied and furnished to oth-
+ers, and derivative works that comment on or otherwise explain it or
+assist in its implementation may be prepared, copied, published and dis-
+tributed, in whole or in part, without restriction of any kind, provided
+that the above copyright notice and this paragraph are included on all
+such copies and derivative works. However, this document itself may not
+be modified in any way, such as by removing the copyright notice or
+references to the Internet Society or other Internet organizations,
+except as needed for the purpose of developing Internet standards in
+which case the procedures for copyrights defined in the Internet Stan-
+dards process must be followed, or as required to translate it into
+
+
+
+Expires: May 2001 [Page 70]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+languages other than English.
+
+The limited permissions granted above are perpetual and will not be
+revoked by the Internet Society or its successors or assigns.
+
+This document and the information contained herein is provided on an "AS
+IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK
+FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT
+INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FIT-
+NESS FOR A PARTICULAR PURPOSE.
+
+
+21. Bibliography
+
+[1] Bradner, S., "Key words for use in RFCs to Indicate Requirement
+ Levels", RFC 2119, March 1997.
+
+[2] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol
+ (v3)", RFC 2251, December 1997.
+
+[3] M. Wahl, A. Coulbeck, T. Howes, S. Kille, W. Yeong, C. Robbins,
+ "Lightweight Directory Access Protocol (v3): Attribute Syntax
+ Definitions", RFC 2252, December 1997.
+
+[4] The Directory: Selected Attribute Syntaxes. CCITT, Recommendation
+ X.520.
+
+[5] M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access Protocol
+ (v3): A UTF-8 String Representation of Distinguished Names", RFC
+ 2253, December 1997.
+
+[6] F. Yergeau, "UTF-8, a transformation format of Unicode and ISO
+ 10646", RFC 2044, October 1996.
+
+[7] K. Simonsen, "Character Mnemonics and Character Sets," RFC 1345,
+ June 1992.
+
+[8] "Programming Languages - C", ANSI/ISO Standard 9899, revised 1997.
+
+[9] J. Hodges, R. Morgan, M. Wahl, "Lightweight Directory Access Proto-
+ col (v3): Extension for Transport Layer Security", INTERNET-DRAFT
+ (work in progress) <draft-ietf-ldapext-ldapv3-tls-05.txt>, June
+ 1999.
+
+[10] R. Hinden, S. Deering, "IP Version 6 Addressing Architecture," RFC
+ 1884, December 1995.
+
+
+
+
+Expires: May 2001 [Page 71]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+[11] A. Herron, T. Howes, M. Wahl, A. Anantha, "LDAP Control Extension
+ for Server Side Sorting of Search Results", INTERNET-DRAFT (work in
+ progress) <draft-ietf-ldapext-sorting-02.txt>, 5 April 1999.
+
+[12] J. Meyers, "Simple Authentication and Security Layer (SASL)", RFC
+ 2222, October 1997.
+
+[13] T. Howes, "The String Representation of LDAP Search Filters," RFC
+ 2254, December 1997.
+
+[14] S. Kille, "Using the OSI Directory to Achieve User Friendly Nam-
+ ing," RFC 1781, March 1995.
+
+
+22. Authors' Addresses
+
+ Mark Smith (document editor)
+ Netscape Communications Corp.
+ 901 San Antonio Rd.
+ Palo Alto, CA 94303-4900
+ Mail Stop SCA17 - 201
+ USA
+ +1 650 937-3477
+ mcs at netscape.com
+
+ Tim Howes
+ Loudcloud, Inc.
+ 599 N. Mathilda Avenue
+ Sunnyvale, CA 94085
+ USA
+ +1 408 744-7300
+ howes at loudcloud.com
+
+ Andy Herron
+ Microsoft Corp.
+ 1 Microsoft Way
+ Redmond, WA 98052
+ USA
+ +1 425 882-8080
+ andyhe at microsoft.com
+
+ Mark Wahl
+ Sun Microsystems, Inc.
+ 8911 Capital of Texas Hwy, Suite 4140
+ Austin, TX 78759
+ USA
+ +1 626 919 3600
+ Mark.Wahl at sun.com
+
+
+
+Expires: May 2001 [Page 72]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ Anoop Anantha
+ Microsoft Corp.
+ 1 Microsoft Way
+ Redmond, WA 98052
+ USA
+ +1 425 882-8080
+ anoopa at microsoft.com
+
+
+23. Appendix A - Sample C LDAP API Code
+
+ #include <stdio.h>
+ #include <ldap.h>
+
+ main()
+ {
+ LDAP *ld;
+ LDAPMessage *res, *e;
+ int i, rc;
+ char *a, *dn;
+ BerElement *ptr;
+ char **vals;
+
+ /* open an LDAP session */
+ if ( (ld = ldap_init( "dotted.host.name", LDAP_PORT )) == NULL )
+ return 1;
+
+ /* authenticate as nobody */
+ if (( rc = ldap_simple_bind_s( ld, NULL, NULL )) != LDAP_SUCCESS ) {
+ fprintf( stderr, "ldap_simple_bind_s: %s\n",
+ ldap_err2string( rc ));
+ ldap_unbind( ld );
+ return 1;
+ }
+
+ /* search for entries with cn of "Babs Jensen", return all attrs */
+ if (( rc = ldap_search_s( ld, "o=University of Michigan, c=US",
+ LDAP_SCOPE_SUBTREE, "(cn=Babs Jensen)", NULL, 0, &res ))
+ != LDAP_SUCCESS ) {
+ fprintf( stderr, "ldap_search_s: %s\n",
+ ldap_err2string( rc ));
+ if ( res == NULL ) {
+ ldap_unbind( ld );
+ return 1;
+ }
+ }
+
+ /* step through each entry returned */
+
+
+
+Expires: May 2001 [Page 73]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ for ( e = ldap_first_entry( ld, res ); e != NULL;
+ e = ldap_next_entry( ld, e ) ) {
+ /* print its name */
+ dn = ldap_get_dn( ld, e );
+ printf( "dn: %s\n", dn );
+ ldap_memfree( dn );
+
+ /* print each attribute */
+ for ( a = ldap_first_attribute( ld, e, &ptr ); a != NULL;
+ a = ldap_next_attribute( ld, e, ptr ) ) {
+ printf( "\tattribute: %s\n", a );
+
+ /* print each value */
+ vals = ldap_get_values( ld, e, a );
+ for ( i = 0; vals[i] != NULL; i++ ) {
+ printf( "\t\tvalue: %s\n", vals[i] );
+ }
+ ldap_value_free( vals );
+ ldap_memfree( a );
+ }
+ if ( ptr != NULL ) {
+ ber_free( ptr, 0 );
+ }
+ }
+ /* free the search results */
+ ldap_msgfree( res );
+
+ /* close and free connection resources */
+ ldap_unbind( ld );
+
+ return 0;
+ }
+
+
+24. Appendix B - Namespace Consumed By This Specification
+
+The following 2 prefixes are used in this specification to name func-
+tions:
+ ldap_
+ ber_
+
+The following 6 prefixes are used in this specification to name struc-
+tures, unions, and typedefs:
+ ldap
+ LDAP
+ mod_vals_u
+ ber
+ Ber
+
+
+
+Expires: May 2001 [Page 74]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ timeval
+
+The following 3 prefixes are used in this specification to name #defined
+macros:
+ LDAP
+ LBER_
+ mod_
+
+
+25. Appendix C - Summary of Requirements for API Extensions
+
+As the LDAP protocol is extended, this C LDAP API will need to be
+extended as well. For example, an LDAPv3 control extension has already
+been defined for server-side sorting of search results [7]. This appen-
+dix summarizes the requirements for extending this API.
+
+25.1. Compatibility
+
+Extensions to this document SHOULD NOT, by default, alter the behavior
+of any of the APIs specified in this document. If an extension option-
+ally changes the behavior of any existing C LDAP API function calls, the
+behavior change MUST be well documented. If an extension that operates
+on an LDAP session affects a chain of messages that was previously
+obtained by a call to ldap_result() or by calling a synchronous search
+routine, this MUST be well documented.
+
+25.2. Style
+
+Extensions to this API SHOULD follow the general style and naming con-
+ventions used in this document. For example, function names SHOULD
+start with "ldap_" or "ber_" and consist entirely of lowercase letters,
+digits, and underscore ('_') characters. It is RECOMMENDED that private
+and experimental extensions use only the following prefixes for macros,
+types, and function names:
+ LDAP_X_
+ LBER_X_
+ ldap_x_
+ ber_x_
+and that these prefixes not be used by standard extensions.
+
+25.3. Dependence on Externally Defined Types
+
+Extensions to this API SHOULD minimize dependencies on types and macros
+that are defined in system headers and generally use only intrinsic
+types that are part of the C language, types defined in this specifica-
+tion, or types defined in the extension document itself.
+
+
+
+
+
+Expires: May 2001 [Page 75]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+25.4. Compile Time Information
+
+Extensions to this API SHOULD conform to the requirements contained in
+the "Retrieving Information at Compile Time" section of this document.
+That is, extensions SHOULD define a macro of the form:
+
+ #define LDAP_API_FEATURE_x level
+
+so that applications can detect the presence or absence of the extension
+at compile time and also test the version or level of the extension pro-
+vided by an API implementation.
+
+25.5. Runtime Information
+
+Extensions to this API SHOULD conform to the requirements contained in
+the "Retrieving Information During Execution" section of this document.
+That is, each extension SHOULD be given a character string name and that
+name SHOULD appear in the ldapai_extensions array field of the LDAPAPI-
+Info structure following a successful call to ldap_get_option() with an
+option parameter value of LDAP_OPT_API_INFO. In addition, information
+about the extension SHOULD be available via a call to ldap_get_option()
+with an option parameter value of LDAP_OPT_API_FEATURE_INFO.
+
+25.6. Values Used for Session Handle Options
+
+Extensions to this API that add new session options (for use with the
+ldap_get_option() and ldap_set_option() functions) SHOULD meet the
+requirements contained in the last paragraph of the "LDAP Session Handle
+Options" section of this document. Specifically, standards track docu-
+ments MUST use values for option macros that are between 0x1000 and
+0x3FFF inclusive and private and experimental extensions MUST use values
+for the option macros that are between 0x4000 and 0x7FFF inclusive.
+
+
+26. Appendix D - Known Incompatibilities with RFC 1823
+
+This appendix lists known incompatibilities between this API specifica-
+tion and the one contained in RFC 1823, beyond the additional API func-
+tions added in support of LDAPv3.
+
+
+26.1. Opaque LDAP Structure
+
+In RFC 1823, some fields in the LDAP structure were exposed to applica-
+tion programmers. To provide a cleaner interface and to make it easier
+for implementations to evolve over time without sacrificing binary com-
+patibility with older applications, the LDAP structure is now entirely
+opaque. The new ldap_set_option() and ldap_get_option() calls can be
+
+
+
+Expires: May 2001 [Page 76]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+used to manipulate per-session and global options.
+
+
+26.2. Additional Result Codes
+
+The following new result code macros were introduced to support LDAPv3:
+ LDAP_REFERRAL
+ LDAP_ADMINLIMIT_EXCEEDED
+ LDAP_UNAVAILABLE_CRITICAL_EXTENSION
+ LDAP_CONFIDENTIALITY_REQUIRED
+ LDAP_SASL_BIND_IN_PROGRESS
+ LDAP_AFFECTS_MULTIPLE_DSAS
+ LDAP_CONNECT_ERROR
+ LDAP_NOT_SUPPORTED
+ LDAP_CONTROL_NOT_FOUND
+ LDAP_NO_RESULTS_RETURNED
+ LDAP_MORE_RESULTS_TO_RETURN
+ LDAP_CLIENT_LOOP
+ LDAP_REFERRAL_LIMIT_EXCEEDED
+
+
+26.3. Freeing of String Data with ldap_memfree()
+
+All strings received from the API (e.g., those returned by the
+ldap_get_dn() or ldap_dn2ufn() functions) SHOULD be freed by calling
+ldap_memfree() not free(). RFC 1823 did not define an ldap_memfree()
+function.
+
+
+26.4. Changes to ldap_result()
+
+The meaning of the all parameter to ldap_result has changed slightly.
+Nonzero values from RFC 1823 correspond to LDAP_MSG_ALL (0x01). There
+is also a new possible value, LDAP_MSG_RECEIVED (0x02).
+
+The result type LDAP_RES_MODDN is now returned where RFC 1823 returned
+LDAP_RES_MODRDN. The actual value for these two macros is the same
+(0x6D).
+
+
+26.5. Changes to ldap_first_attribute() and ldap_next_attribute
+
+Each non-NULL return value SHOULD be freed by calling ldap_memfree()
+after use. In RFC 1823, these two functions returned a pointer to a
+per-session buffer, which was not very thread-friendly.
+
+After the last call to ldap_first_attribute() or ldap_next_attribute(),
+the value set in the ptr parameter SHOULD be freed by calling ber_free(
+
+
+
+Expires: May 2001 [Page 77]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ptr, 0 ). RFC 1823 did not mention that the ptr value SHOULD be freed.
+
+The type of the ptr parameter was changed from void * to BerElement *.
+
+
+26.6. Changes to ldap_modrdn() and ldap_modrdn_s() Functions
+
+In RFC 1823, the ldap_modrdn() and ldap_modrdn_s() functions include a
+parameter called deleteoldrdn. This does not match the great majority
+of implementations, so in this specification the deleteoldrdn parameter
+was removed from ldap_modrdn() and ldap_modrdn_s(). Two additional
+functions that support deleteoldrdn and are widely implemented as well
+were added to this specification: ldap_modrdn2() and ldap_modrdn2_s().
+
+
+26.7. Changes to the berval structure
+
+In RFC 1823, the bv_len element of the berval structure was defined as
+an `unsigned long'. In this specification, the type is implementation-
+specific, although it MUST be an unsigned integral type that is at least
+32 bits in size. See the appendix "Data Types and Legacy Implementa-
+tions" for additional considerations.
+
+
+26.8. API Specification Clarified
+
+RFC 1823 left many things unspecified, including behavior of various
+memory disposal functions when a NULL pointer is presented, requirements
+for headers, values of many macros, and so on. This specification is
+more complete and generally tighter than the one in RFC 1823.
+
+
+26.9. Deprecated Functions
+
+A number of functions that are in RFC 1823 are labeled as "deprecated"
+in this specification. In most cases, a replacement that provides
+equivalent functionality has been defined. The deprecated functions
+are:
+
+ ldap_bind()
+ Use ldap_simple_bind() or ldap_sasl_bind() instead.
+
+ ldap_bind_s()
+ Use ldap_simple_bind_s() or ldap_sasl_bind_s() instead.
+
+ ldap_kerberos_bind() and ldap_kerberos_bind_s()
+ No equivalent functions are provided.
+
+
+
+
+Expires: May 2001 [Page 78]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ ldap_modrdn() and ldap_modrdn2()
+ Use ldap_rename() instead.
+
+ ldap_modrdn_s() and ldap_modrdn2_s()
+ Use ldap_rename_s() instead.
+
+ ldap_open()
+ Use ldap_init() instead.
+
+ ldap_perror()
+ Use ldap_get_option( ld, LDAP_OPT_RESULT_CODE, &rc ) followed
+ by fprintf( stderr, "%s: %s", msg, ldap_err2string( rc ))
+ instead.
+
+ ldap_result2error()
+ Use ldap_parse_result() instead.
+
+
+27. Appendix E - Data Types and Legacy Implementations
+
+The data types associated with the length of a ber value (ber_len_t),
+and the tag (ber_tag_t) have been defined in this specification as
+unsigned integral types of implementation-specific size. The data type
+used for encoding and decoding ber integer, enumerated, and boolean
+values has been defined in this specification as a signed integral type
+of implementation-specific size. This was done so that source and
+binary compatibility of the C LDAP API can be maintained across ILP32
+environments (where int, long, and pointers are all 32 bits in size) and
+LP64 environments (where ints remain 32 bits but longs and pointers grow
+to 64 bits).
+
+In older implementations of the C LDAP API, such as those based on RFC
+1823, implementors may have chosen to use an `unsigned long' for length
+and tag values. If a long data type was used for either of these items,
+a port of an application to a 64-bit operating system using the LP64
+data model would find the size of the types used by the C LDAP API to
+increase. Also, if the legacy implementation had chosen to implement
+the tag and types as an unsigned int, adoption of a specification that
+mandated use of unsigned longs would cause a source incompatibility in
+an LP64 application. By using implementation-specific data types, the C
+LDAP API implementation is free to choose the correct data type and the
+ability to maintain source compatibility.
+
+For example, suppose a legacy implementation chose to define the return
+value of ber_skip_tag() as an unsigned long but wishes to have the
+library return a 32-bit quantity in both ILP32 and LP64 data models.
+The following typedefs for ber_tag_t will provide a fixed sized data
+structure while preserving existing ILP32 source -- all without
+
+
+
+Expires: May 2001 [Page 79]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+generating compiler warnings:
+ #include <limits.h> /* provides UINT_MAX in ISO C */
+ #if UINT_MAX >= 0xffffffffU
+ typedef unsigned int ber_tag_t;
+ #else
+ typedef unsigned long ber_tag_t;
+ #endif
+
+Similar code can be used to define appropriate ber_len_t, ber_int_t,
+ber_slen_t and ber_uint_t types.
+
+
+28. Appendix F - Changes Made Since Last Document Revision
+
+The previous version of this document was draft-ietf-ldapext-ldap-c-
+api-04.txt, dated 8 October 1999. This appendix lists all of the
+changes made to that document to produce this one.
+
+28.1. API Changes
+
+ "Header Requirements" section: added requirement that the simple pro-
+ gram provided must execute as well as compile without errors.
+
+ "LDAP Session Handle Options" section: changed the name of the
+ LDAP_OPT_ERROR_NUMBER option to LDAP_OPT_RESULT_CODE. Allow
+ LDAP_OPT_ON to be defined as an implementation specific value (to
+ avoid problems on architectures where the value ((void *)1) is not
+ usable).
+
+ "Initializing an LDAP Session" section: allow use of the value zero
+ for the `portno' parameter to mean "use port 389."
+
+ "Searching" section: added LDAP_DEFAULT_SIZELIMIT (-1) to allow
+ application programmers to use the sizelimit from the LDAP session
+ handle with ldap_search_ext() and ldap_search_ext_s().
+
+ "Modifying an entry" section: moved mod_vals union out of LDAPMod and
+ added mod_vals_u_t typedef so users of the API can declare variables
+ using the union type. "Handling Errors and Parsing Results" section:
+ added text to require that ldap_err2string() MUST NOT return NULL.
+
+ "A Client Control That Governs Referral Processing" section: modified
+ the text to specify that a ber_uint_t value should be used to hold
+ the flags.
+
+
+
+
+
+
+
+Expires: May 2001 [Page 80]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+28.2. Editorial Changes and Clarifications
+
+ "Overview of LDAP API Use and General Requirements" section: added
+ text to clarify our use of the term "asynchronous."
+
+ "Retrieving Information During Execution" section: added text
+ describing the `ldapai_vendor_name' and `ldapai_vendor_version'
+ fields (text was accidently deleted during a previous round of
+ edits).
+
+ "LDAP Session Handle Options" section: improved the text that
+ describes the LDAP_OPT_TIMELIMIT, LDAP_OPT_SIZELIMIT, and
+ LDAP_OPT_RESULT_CODE options. Provided details and an example of the
+ correct LDAP_OPT_HOST_NAME string to return when the `portno' passed
+ to ldap_init() is not zero or 389.
+
+ "Result Codes" section: renamed section (was "LDAP Error Codes").
+
+ "Authenticating to the directory" section: clarified that the `dn',
+ `cred', and `passwd' parameters can be NULL. Added text indicate
+ that the `servercredp' is set to NULL if an API error occurs.
+
+ "Performing LDAP Operations" section: replaced "All functions take a
+ session handle" with "Most functions...."
+
+ "Search" section: removed the detailed discussion of the session han-
+ dle options (already covered in the "Retrieving Information During
+ Execution" section). Also removed the word "global" when discussing
+ the session default value for the `timeout' parameter. Also clari-
+ fied that a NULL `base' parameter means use a zero-length string for
+ the base DN.
+
+ "Comparing a Value Against an Entry" section: corrected the "success-
+ ful" return codes for ldap_compare_ext_s() and ldap_compare_s() (was
+ LDAP_SUCCESS; changed to LDAP_COMPARE_TRUE or LDAP_COMPARE_FALSE).
+
+ "Extended Operations" section: added text to indicate that the
+ `retoidp' and `retdatap' result parameters are set to NULL if an API
+ error occurs in ldap_extended_operation_s().
+
+ "Handling Errors and Parsing Results" section: added text to say that
+ the `matcheddnp' result parameter will be set to NULL if the server
+ does not return a matched DN string. Added text to indicate that
+ serverctrlsp can be NULL. Added text to indicate that *retoidpp,
+ *retdatap, *referralsp, and *serverctrlsp will be set to NULL if no
+ items of that type are returned. Removed specific reference to
+ LDAP_NO_SUCH_OBJECT result code when discussing the `matcheddnp'
+ result parameter and added clarifying note about "" vs. NULL.
+
+
+
+Expires: May 2001 [Page 81]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ "Parsing References" section: added text to indicate that *refer-
+ ralsp, and *serverctrlsp will be set to NULL if no items of that type
+ are returned.
+
+ "Obtaining Results and Peeking Inside LDAP Messages" section: added
+ text to say that LDAPMessage chains MAY be tied to a session handle.
+
+ "BER Data Structures and Types" section: removed note about
+ ber_uint_t not being used in this document (it is now). Changed text
+ to simplify the description of ber_slen_t. Removed misleading sen-
+ tence about the width of ber_uint_t.
+
+ "Encoded ASN.1 Value Manipulation / Encoding" section: added note
+ that 'X' is reserved. Also fixed a few small bugs in the example
+ code.
+
+ "Encoded ASN.1 Value Manipulation / Decoding" section: clarified the
+ requirements for LBER_ERROR and LBER_DEFAULT (expressed using octets
+ instead of bits). Also fixed a few small bugs in the example code.
+
+ Added the following text to all descriptions of the `serverctrls' and
+ `clientctrls' parameters: ", or NULL if no <server/client> controls
+ are to be used."
+
+ Added the following text to the description of all `dn' and `rdn'
+ parameters: "If NULL, a zero length DN is sent to the server."
+
+ Replaced many occurrences of the phrase "error code" with "result
+ code" throughout the document.
+
+ Added text to indicate that the value of the `msgidp' result parame-
+ ter is undefined if an error occurs in the following functions:
+ ldap_sasl_bind(), ldap_search_ext(), ldap_compare_ext(),
+ ldap_modify_ext(), ldap_add_ext(), ldap_delete_ext(),
+ ldap_extended_operation().
+
+ Added text to indicate that the `res' result parameter is set to NULL
+ if an API error occurs in the following functions: ldap_result(),
+ ldap_search_s(), ldap_search_st().
+
+ Added text to indicate that all result parameters have undefined
+ values if an API error is returned by the following functions:
+ ldap_parse_result(), ldap_parse_sasl_bind_result(),
+ ldap_parse_extended_result(), ldap_parse_reference(), ber_scanf().
+
+ Added angle brackets around ficticious impl_XXX_t types to make it
+ more obvious that these are not real "C" types, e.g., typedef
+ <impl_len_t> ber_len_t'.
+
+
+
+Expires: May 2001 [Page 82]
+
+C LDAP API C LDAP Application Program Interface 17 November 2000
+
+
+ Appendix B: Added mod_vals_u and removed PLDAP from the struct,
+ unions, and typedefs prefix list.
+
+ Appendix C: Added note in "Compatibility" section about extensions
+ possible affecting chains of messages and the fact that that must be
+ well documented. Appendix D: Improved text for ldap_perror() (what
+ to use instead).
+
+ "Authors" section: updated contact information for Mark Smith, Tim
+ Howes, and Mark Wahl.
+
+ Fixed a few obvious typos, improved indentation, added missing blank
+ lines, and so on.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Expires: May 2001 [Page 83]
+
Added: openldap/vendor/openldap-release/doc/drafts/draft-ietf-ldapext-ldapv3-dupent-xx.txt
===================================================================
--- openldap/vendor/openldap-release/doc/drafts/draft-ietf-ldapext-ldapv3-dupent-xx.txt (rev 0)
+++ openldap/vendor/openldap-release/doc/drafts/draft-ietf-ldapext-ldapv3-dupent-xx.txt 2008-06-28 09:29:58 UTC (rev 1147)
@@ -0,0 +1,522 @@
+
+
+LDAPEXT Working Group J. Sermersheim
+Internet Draft Novell, Inc
+Document: draft-ietf-ldapext-ldapv3-dupent-08.txt Sept 2002
+Intended Category: Standard Track
+
+
+ LDAP Control for a Duplicate Entry Representation of Search Results
+
+
+1. Status of this Memo
+
+ This document is an Internet-Draft and is in full conformance with
+ all provisions of Section 10 of RFC2026 [1].
+
+ Internet-Drafts are working documents of the Internet Engineering
+ Task Force (IETF), its areas, and its working groups. Note that
+ other groups may also distribute working documents as Internet-
+ Drafts. Internet-Drafts are draft documents valid for a maximum of
+ six months and may be updated, replaced, or obsoleted by other
+ documents at any time. It is inappropriate to use Internet- Drafts
+ as reference material or to cite them other than as "work in
+ progress."
+
+ The list of current Internet-Drafts can be accessed at
+ http://www.ietf.org/ietf/1id-abstracts.txt
+
+ The list of Internet-Draft Shadow Directories can be accessed at
+ http://www.ietf.org/shadow.html.
+
+2. Abstract
+
+ This document describes a Duplicate Entry Representation control
+ extension for the LDAP Search operation. By using the control with
+ an LDAP search, a client requests that the server return separate
+ entries for each value held in the specified attribute(s). For
+ instance, if a specified attribute of an entry holds multiple
+ values, the search operation will return multiple instances of that
+ entry, each instance holding a separate single value in that
+ attribute.
+
+3. Introduction
+
+ This document describes controls, which allow duplicate entries to
+ be returned in the result set of search operation. Each duplicated
+ entry represents a distinct value (or combination of values) of the
+ set of specified multi-valued attributes.
+
+ For example, an application may need to produce an ordered list of
+ entries, sorted by a multi-valued attribute, where each attribute
+ value is represented in the list. The Server-Side Sorting control
+ [RFC2891] allows the server to order search result entries based on
+ attribute values (sort keys). But it does not allow one to specify
+ behavior when an attribute contains multiple values. The default
+
+
+Sermersheim Internet-Draft - Expires Mar 2003 Page 1
+LDAP Control for a Duplicate Entry Representation of Search Results
+
+
+ behavior, as outlined in 7.9 of [X.511], is to use the smallest
+ order value as the sort key.
+
+ In order to produce an ordered list, where each value of a multi-
+ valued attribute is sorted into the list, a separate control is
+ needed which causes the set of entries to be expanded sufficiently
+ to represent each attribute value prior to sorting.
+
+
+
+ An example of this would be a sorted list of all telephone numbers
+ in an organization. Because any entry may have multiple telephone
+ numbers, and the list is to be sorted by telephone number, the list
+ must be able to contain duplicate entries, each with its own unique
+ telephone number.
+
+ Another example would be an application that needs to display an
+ ordered list of all members of a group. It would use this control
+ to create a result set of duplicate groupOfNames entries, each with
+ a single, unique value in its member attribute.
+
+4. Conventions
+
+ The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
+ used in this document carry the meanings described in [RFC2119].
+
+ All controlValue data is represented as ASN.1 in this document, and
+ is to be BER encoded as stated in Section 5.1 of [RFC2251].
+
+5. The Controls
+
+ Support for the controls is advertised by the presence of their OID
+ in the supportedControl attribute of a server's root DSE. The OID
+ for the request control is "2.16.840.1.113719.1.27.101.1" and the
+ OIDs for the response controls are "2.16.840.1.113719.1.27.101.2"
+ and "2.16.840.1.113719.1.27.101.3".
+
+5.1 Request Control
+
+ This control is included in the searchRequest message as part of the
+ controls field of the LDAPMessage, as defined in Section 4.1.12 of
+ [RFC2251].
+
+ The controlType is set to "2.16.840.1.113719.1.27.101.1". The
+ criticality MAY be set to either TRUE or FALSE. The controlValue is
+ defined as the following DuplicateEntryRequest:
+
+ DuplicateEntryRequest ::= SEQUENCE {
+ AttributeDescriptionList, -- from [RFC2251]
+ PartialApplicationAllowed BOOLEAN DEFAULT TRUE }
+
+
+5.1.1 AttributeDescriptionList Semantics
+
+Sermersheim Internet-Draft - Expires Mar 2003 Page 2
+LDAP Control for a Duplicate Entry Representation of Search Results
+
+
+
+ The AttributeDescriptionList data type is described in 4.1.5 of
+ [RFC2251] and describes a list of zero or more AttributeDescription
+ types as also described in 4.1.5 of [RFC2251]. Both definitions are
+ repeated here for convenience:
+
+ AttributeDescriptionList ::= SEQUENCE OF
+ AttributeDescription
+
+ AttributeDescription ::= LDAPString
+
+ A value of AttributeDescription is based on the following BNF:
+
+ attributeDescription = AttributeType [ ";" <options> ]
+
+ While processing a search request, a server implementation examines
+ this list. If a specified attribute or attribute subtype exists in
+ an entry to be returned by the search operation, and that attribute
+ holds multiple values, the server treats the entry as if it were
+ multiple, duplicate entries -- the specified attributes each holding
+ a single, unique value from the original set of values of that
+ attribute. Note that this may result in search result entries that
+ no longer match the search filter.
+
+ Specifying an attribute supertype has the effect of treating all
+ values of that attribute's subtypes as if they were values of the
+ specified attribute supertype. See Section 6.2 for an example of
+ this.
+
+ When attribute descriptions contain subtyping options, they are
+ treated in the same manner as is described in Section 4.1.5 of
+ [RFC2251]. Semantics are undefined if an attribute description
+ contains a non-subtyping option, and SHOULD NOT be specified by
+ clients.
+
+ When two or more attributes are specified by this control, the
+ number of duplicate entries is the combination of all values in each
+ attribute. Because of the potential complexity involved in servicing
+ multiple attributes, server implementations MAY choose to support a
+ limited number of attributes in the control.
+
+ There is a special case where either no attributes are specified, or
+ an attribute description value of "*" is specified. In this case,
+ all attributes are used. (The "*" allows the client to request all
+ user attributes in addition to specific operational attributes).
+
+ If an attribute is unrecognized, that attribute is ignored when
+ processing the control.
+
+5.1.2 PartialApplicationAllowed Semantics
+
+ The PartialApplicationAllowed field is used to specify whether the
+ client will allow the server to apply this control to a subset of
+
+Sermersheim Internet-Draft - Expires Mar 2003 Page 3
+LDAP Control for a Duplicate Entry Representation of Search Results
+
+
+ the search result set. If TRUE, the server is free to arbitrarily
+ apply this control to no, any, or all search results. If FALSE, the
+ server MUST either apply the control to all search results or fail
+ to support the control at all.
+
+ Client implementations use the DuplicateSearchResult control to
+ discover which search results have been affected by this control.
+
+5.2 Response Controls
+
+ Two response controls are defined to provide feedback while the
+ search results are being processed; DuplicateSearchResult and
+ DuplicateEntryResponseDone.
+
+ The DuplicateSearchResult control is sent with all SearchResultEntry
+ operations that contain search results which have been modified by
+ the DuplicateEntryRequest control.
+
+ The DuplicateEntryResponseDone control is sent with the
+ SearchResultDone operation in order to convey completion
+ information.
+
+5.2.1 The DuplicateSearchResult control
+
+ This control is included in the SearchResultEntry message of any
+ search result that holds an entry that has been modified by the
+ DuplicateEntryRequest control as part of the controls field of the
+ LDAPMessage, as defined in Section 4.1.12 of [RFC2251]. This control
+ is absent on search results that are unaffected by
+ DuplicateEntryRequest control.
+
+ The controlType is set to "2.16.840.1.113719.1.27.101.2". The
+ controlValue is not included.
+
+5.2.2 The DuplicateEntryResponseDone control
+
+ This control is included in the searchResultDone message as part of
+ the controls field of the LDAPMessage, as defined in Section 4.1.12
+ of [RFC2251].
+
+ The controlType is set to "2.16.840.1.113719.1.27.101.3". The
+ controlValue is defined as the following DuplicateEntryResponseDone:
+
+ DuplicateEntryResponseDone ::= SEQUENCE {
+ resultCode, -- From [RFC2251]
+ errorMessage [0] LDAPString OPTIONAL,
+ attribute [1] AttributeDescription OPTIONAL }
+
+ A resultCode field is provided here to allow the server to convey to
+ the client that an error resulted due to the control being serviced.
+ For example, a search that would ordinarily complete successfully
+ may fail with a sizeLimitExceeded error due to this control being
+
+
+Sermersheim Internet-Draft - Expires Mar 2003 Page 4
+LDAP Control for a Duplicate Entry Representation of Search Results
+
+
+ processed. If the operation is successfull, the value will be
+ success (0).
+
+ The errorMessage field MAY be populated with a human-readable string
+ in the event of an erroneous result code.
+
+ The attribute field MAY be set to the value of the first attribute
+ specified by the DuplicateEntryRequest that was in error. The
+ client MUST ignore the attribute field if the result is success.
+
+6. Protocol Examples
+
+6.1 Simple example
+
+ This example will show this control being used to produce a list of
+ all telephone numbers in the dc=example,dc=net container. Let's say
+ the following three entries exist in this container;
+
+ dn: cn=User1,dc=example,dc=net
+ telephoneNumber: 555-0123
+
+ dn: cn=User2,dc=example,dc=net
+ telephoneNumber: 555-8854
+ telephoneNumber: 555-4588
+ telephoneNumber: 555-5884
+
+ dn: cn=User3,dc=example,dc=net
+ telephoneNumber: 555-9425
+ telephoneNumber: 555-7992
+
+ First an LDAP search is specified with a baseDN of
+ "dc=example,dc=net", subtree scope, filter set to
+ "(telephoneNumber=*)". A DuplicateEntryRequest control is attached
+ to the search, specifying "telephoneNumber" as the attribute
+ description, and the search request is sent to the server.
+
+ The set of search results returned by the server would then consist
+ of the following entries:
+
+ dn: cn=User1,dc=example,dc=net
+ telephoneNumber: 555-0123
+ <no DuplicateSearchResult control sent with search result>
+
+ dn: cn=User2,dc=example,dc=net
+ telephoneNumber: 555-8854
+ control: 2.16.840.1.113719.1.27.101.2
+
+ dn: cn=User2,dc=example,dc=net
+ telephoneNumber: 555-4588
+ control: 2.16.840.1.113719.1.27.101.2
+
+ dn: cn=User2,dc=example,dc=net
+ telephoneNumber: 555-5884
+
+Sermersheim Internet-Draft - Expires Mar 2003 Page 5
+LDAP Control for a Duplicate Entry Representation of Search Results
+
+
+ control: 2.16.840.1.113719.1.27.101.2
+
+ dn: cn=User3,dc=example,dc=net
+ telephoneNumber: 555-9425
+ control: 2.16.840.1.113719.1.27.101.2
+
+ dn: cn=User3,dc=example,dc=net
+ telephoneNumber: 555-7992
+ control: 2.16.840.1.113719.1.27.101.2
+
+ All but the first entry are accompanied by the DuplicateSearchResult
+ control when sent from the server.
+
+ Note that it is not necessary to use an attribute in this control
+ that is specified in the search filter. This example only does so,
+ because the result was to obtain a list of telephone numbers.
+
+6.2 Specifying multiple attributes
+
+ A more complicated example involving multiple attributes will result
+ in more entries. If we assume these entries in the directory:
+
+ dn: cn=User1,dc=example,dc=net
+ cn: User1
+ givenName: User One
+ mail: user1 at example.net
+
+ dn: cn=User2,dc=example,dc=net
+ cn: User2
+ givenName: User Two
+ mail: user2 at example.net
+ mail: usertwo at example.net
+
+ In this example, we specify mail and name in the attribute list. By
+ specifying name, all attribute subtypes of name will also be
+ considered. Following is the resulting set of entries:
+
+ dn: cn=User1,dc=example,dc=net
+ cn: User1
+ mail: user1 at example.net
+ control: 2.16.840.1.113719.1.27.101.2
+
+ dn: cn=User1,dc=example,dc=net
+ givenName: User One
+ mail: user1 at example.net
+ control: 2.16.840.1.113719.1.27.101.2
+
+ dn: cn=User2,dc=example,dc=net
+ cn: User2
+ mail: user2 at example.net
+ control: 2.16.840.1.113719.1.27.101.2
+
+ dn: cn=User2,dc=example,dc=net
+
+Sermersheim Internet-Draft - Expires Mar 2003 Page 6
+LDAP Control for a Duplicate Entry Representation of Search Results
+
+
+ cn: User2
+ mail: usertwo at example.net
+ control: 2.16.840.1.113719.1.27.101.2
+
+ dn: cn=User2,dc=example,dc=net
+ givenName: User Two
+ mail: user2 at example.net
+ control: 2.16.840.1.113719.1.27.101.2
+
+ dn: cn=User2,dc=example,dc=net
+ givenName: User Two
+ mail: usertwo at example.net
+ control: 2.16.840.1.113719.1.27.101.2
+
+6.3 Listing the members of a groupOfNames
+
+ This example shows how the controls can be used to turn a single
+ groupOfNames entry into multiple duplicate entries. Let's say this
+ is our groupOfNames entry:
+
+ dn: cn=Administrators,dc=example,dc=net
+ cn: Administrators
+ member: cn=aBaker,dc=example,dc=net
+ member: cn=cDavis,dc=example,dc=net
+ member: cn=bChilds,dc=example,dc=net
+ member: cn=dEvans,dc=example,dc=net
+
+ We could set our search base to "cn=Administrators,dc=example,dc=net
+ ", filter to "(objectClass=*)", use an object scope (to restrict it
+ to this entry) and send the duplicateEntryRequest control with
+ "member" as its attribute value. The resulting set would look like
+ this:
+
+ dn: cn=Administrators,dc=example,dc=net
+ member: cn=aBaker,dc=example,dc=net
+ control: 2.16.840.1.113719.1.27.101.2
+
+ dn: cn=Administrators,dc=example,dc=net
+ member: cn=cDavis,dc=example,dc=net
+ control: 2.16.840.1.113719.1.27.101.2
+
+ dn: cn=Administrators,dc=example,dc=net
+ member: cn=bChilds,dc=example,dc=net
+ control: 2.16.840.1.113719.1.27.101.2
+
+ dn: cn=Administrators,dc=example,dc=net
+ member: cn=dEvans,dc=example,dc=net
+ control: 2.16.840.1.113719.1.27.101.2
+
+ This list can then be sorted by member and displayed (also by
+ member) in a list.
+
+7. Relationship to other controls
+
+Sermersheim Internet-Draft - Expires Mar 2003 Page 7
+LDAP Control for a Duplicate Entry Representation of Search Results
+
+
+
+ This control is intended (but not limited) to be used with the
+ Server Side Sorting control [RFC2891]. By pairing this control with
+ the Server Side Sorting control, One can produce a set of entries,
+ sorted by attribute values, where each attribute value is
+ represented in the sorted set. Server implementations MUST ensure
+ that this control is processed before sorting the result of a
+ search, as this control alters the result set of search.
+
+ This control MAY also be used with the Virtual List View [VLV]
+ control (which has a dependency on the Server Side Sort control).
+ The nature of the dependency between the VLV control and the Sort
+ control is such that the Sorting takes place first. Because the sort
+ happens first, and because this control is processed before the sort
+ control, the impact of this control on the VLV control is minimal.
+ Some server implementations may need to carefully consider how to
+ handle the typedown functionality of the VLV control when paired
+ with this control. The details of this are heavily implementation
+ dependent and are beyond the scope of this document.
+
+8. Notes for Implementers
+
+ Both client and server implementations MUST be aware that using this
+ control could potentially result in a very large set of search
+ results. Servers MAY return an adminLimitExceeded result in the
+ response control due to inordinate consumption of resources. This
+ may be due to some a priori knowledge such as a server restriction
+ of the number of attributes in the request control that it's willing
+ to service, or it may be due to the server attempting to service the
+ control and running out of resources.
+
+ Client implementations MUST be aware that when using this control,
+ search entries returned will contain a subset of the values of any
+ specified attribute.
+
+ If this control is used in a chained environment, servers SHOULD NOT
+ pass this control to other servers. Instead they SHOULD gather
+ results and apply this control themselves.
+
+9. Security Considerations
+
+ This control allows finer control of the result set returned by an
+ LDAP search operation and as such may be used in a denial of service
+ attack. See Section 8 for more information on how this is detected
+ and handled.
+
+10. Acknowledgments
+
+ The author gratefully thanks the input and support of participants
+ of the LDAP-EXT working group.
+
+11. References
+
+
+Sermersheim Internet-Draft - Expires Mar 2003 Page 8
+LDAP Control for a Duplicate Entry Representation of Search Results
+
+
+ [RFC2251]
+ Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access
+ Protocol (v3)", Internet RFC, December, 1997.
+ Available as RFC 2251.
+
+ [RFC2891]
+ Wahl, M, A. Herron and T. Howes, "LDAP Control Extension for Server
+ Side Sorting of Search Results", Internet RFC, August, 2000.
+ Available as RFC 2891.
+
+ [VLV]
+ Boreham, D, Sermersheim, J, Anantha, A, Armijo, M, "LDAP Extensions
+ for Scrolling View Browsing of Search Results", Internet Draft,
+ April, 2000.
+ Available as draft-ietf-ldapext-ldapv3-vlv-xx.txt.
+
+ [X.511]
+ ITU-T Rec. X.511, "The Directory: Abstract Service Definition",
+ 1993.
+
+ [RFC2119]
+ Bradner, Scott, "Key Words for use in RFCs to Indicate Requirement
+ Levels", Internet Draft, March, 1997.
+ Available as RFC 2119.
+
+12. Author's Address
+
+ Jim Sermersheim
+ Novell, Inc.
+ 1800 South Novell Place
+ Provo, Utah 84606, USA
+ jimse at novell.com
+ +1 801 861-3088
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Sermersheim Internet-Draft - Expires Mar 2003 Page 9
Added: openldap/vendor/openldap-release/doc/drafts/draft-ietf-ldapext-ldapv3-vlv-xx.txt
===================================================================
--- openldap/vendor/openldap-release/doc/drafts/draft-ietf-ldapext-ldapv3-vlv-xx.txt (rev 0)
+++ openldap/vendor/openldap-release/doc/drafts/draft-ietf-ldapext-ldapv3-vlv-xx.txt 2008-06-28 09:29:58 UTC (rev 1147)
@@ -0,0 +1,625 @@
+
+Internet-Draft D. Boreham, Bozeman Pass
+LDAPext Working Group J. Sermersheim, Novell
+Intended Category: Standards Track A. Kashi, Microsoft
+<draft-ietf-ldapext-ldapv3-vlv-06.txt>
+Expires: Nov 2002 May 2002
+
+
+ LDAP Extensions for Scrolling View Browsing of Search Results
+
+
+1. Status of this Memo
+
+ This document is an Internet-Draft and is in full conformance with
+ all provisions of Section 10 of RFC2026.
+
+ Internet-Drafts are working documents of the Internet Engineering
+ Task Force (IETF), its areas, and its working groups. Note that other
+ groups may also distribute working documents as Internet-Drafts.
+
+ Internet-Drafts are draft documents valid for a maximum of six months
+ and may be updated, replaced, or obsoleted by other documents at any
+ time. It is inappropriate to use Internet-Drafts as reference
+ material or to cite them other than as "work in progress."
+
+ The list of current Internet-Drafts can be accessed at
+ http://www.ietf.org/ietf/1id-abstracts.txt
+
+ The list of Internet-Draft Shadow Directories can be accessed at
+ http://www.ietf.org/shadow.html.
+
+ This document is intended to be submitted, after review and revision,
+ as a Standards Track document. Distribution of this memo is
+ unlimited.
+ Please send comments to the authors.
+
+
+2. Abstract
+
+ This document describes a Virtual List View control extension for the
+ Lightweight Directory Access Protocol (LDAP) Search operation. This
+ control is designed to allow the "virtual list box" feature, common
+ in existing commercial e-mail address book applications, to be
+ supported efficiently by LDAP servers. LDAP servers' inability to
+ support this client feature is a significant impediment to LDAP
+ replacing proprietary protocols in commercial e-mail systems.
+
+ The control allows a client to specify that the server return, for a
+ given LDAP search with associated sort keys, a contiguous subset of
+ the search result set. This subset is specified in terms of offsets
+ into the ordered list, or in terms of a greater than or equal
+ comparison value.
+
+
+ Boreham et al Internet-Draft 1
+
+ LDAP Extensions for Scrolling View May 2002
+ Browsing of Search Results
+
+3. Conventions used in this document
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are
+ to be interpreted as described in RFC 2119 [Bradner97].
+
+
+4. Background
+
+ A Virtual List is a graphical user interface technique employed where
+ ordered lists containing a large number of entries need to be
+ displayed. A window containing a small number of visible list entries
+ is drawn. The visible portion of the list may be relocated to
+ different points within the list by means of user input. This input
+ can be to a scroll bar slider; from cursor keys; from page up/down
+ keys; from alphanumeric keys for "typedown". The user is given the
+ impression that they may browse the complete list at will, even
+ though it may contain millions of entries. It is the fact that the
+ complete list contents are never required at any one time that
+ characterizes Virtual List View. Rather than fetch the complete list
+ from wherever it is stored (typically from disk or a remote server),
+ only that information which is required to display the part of the
+ list currently in view is fetched. The subject of this document is
+ the interaction between client and server required to implement this
+ functionality in the context of the results from a sorted LDAP search
+ request.
+
+ For example, suppose an e-mail address book application displays a
+ list view onto the list containing the names of all the holders of e-
+ mail accounts at a large university. The list is sorted
+ alphabetically. While there may be tens of thousands of entries in
+ this list, the address book list view displays only 20 such accounts
+ at any one time. The list has an accompanying scroll bar and text
+ input window for type-down. When first displayed, the list view shows
+ the first 20 entries in the list, and the scroll bar slider is
+ positioned at the top of its range. Should the user drag the slider
+ to the bottom of its range, the displayed contents of the list view
+ should be updated to show the last 20 entries in the list. Similarly,
+ if the slider is positioned somewhere in the middle of its travel,
+ the displayed contents of the list view should be updated to contain
+ the 20 entries located at that relative position within the complete
+ list. Starting from any display point, if the user uses the cursor
+ keys or clicks on the scroll bar to request that the list be scrolled
+ up or down by one entry, the displayed contents should be updated to
+ reflect this. Similarly the list should be displayed correctly when
+ the user requests a page scroll up or down. Finally, when the user
+ types characters in the type-down window, the displayed contents of
+ the list should "jump" or "seek" to the appropriate point within the
+ list. For example, if the user types "B", the displayed list could
+ center around the first user with a name beginning with the letter
+ "B". When this happens, the scroll bar slider should also be updated
+ to reflect the new relative location within the list.
+
+ Boreham et al Internet-Draft 2
+
+ LDAP Extensions for Scrolling View May 2002
+ Browsing of Search Results
+
+
+ This document defines a request control which extends the LDAP search
+ operation. Always used in conjunction with the server side sorting
+ control [SSS], this allows a client to retrieve selected portions of
+ large search result set in a fashion suitable for the implementation
+ of a virtual list view.
+
+
+5. Client-Server Interaction
+
+ The Virtual List View control extends a regular LDAP Search operation
+ which must also include a server-side sorting control [SSS]. Rather
+ than returning the complete set of appropriate SearchResultEntry
+ messages, the server is instructed to return a contiguous subset of
+ those entries, taken from the sorted result set, centered around a
+ particular target entry. Henceforth, in the interests of brevity, the
+ sorted search result set will be referred to as "the list".
+
+ The sort control MAY contain any sort specification valid for the
+ server. The attributeType field in the first SortKeyList sequence
+ element has special significance for "typedown".
+
+ The desired target entry and the number of entries to be returned,
+ both before and after that target entry in the list, are determined
+ by the client's VirtualListViewRequest control.
+
+ When the server returns the set of entries to the client, it attaches
+ a VirtualListViewResponse control to the SearchResultDone message.
+ The server returns in this control: its current estimate for the list
+ content count, the location within the list corresponding to the
+ target entry, any error codes, and optionally a context identifier.
+
+ The target entry is specified in the VirtualListViewRequest control
+ by one of two methods. The first method is for the client to indicate
+ the target entry's offset within the list. The second way is for the
+ client to supply an attribute assertion value. The value is compared
+ against the values of the attribute specified as the primary sort key
+ in the sort control attached to the search operation. The first sort
+ key in the SortKeyList is the primary sort key. The target entry is
+ the first entry in the list with value greater than or equal to (in
+ the primary sort order), the presented value. The order is determined
+ by rules defined in [SSS]. Selection of the target entry by this
+ means is designed to implement "typedown". Note that it is possible
+ that no entry satisfies these conditions, in which case there is no
+ target entry. This condition is indicated by the server returning the
+ special value contentCount + 1 in the target position field.
+
+ Because the server may not have an accurate estimate of the number of
+ entries in the list, and to take account of cases where the list size
+ is changing during the time the user browses the list, and because
+ the client needs a way to indicate specific list targets "beginning"
+
+ Boreham et al Internet-Draft 3
+
+ LDAP Extensions for Scrolling View May 2002
+ Browsing of Search Results
+
+ and "end", offsets within the list are transmitted between client and
+ server as ratios---offset to content count. The server sends its
+ latest estimate as to the number of entries in the list (content
+ count) to the client in every response control. The client sends its
+ assumed value for the content count in every request control. The
+ server examines the content count and offsets presented by the client
+ and computes the corresponding offsets within the list, based on its
+ own idea of the content count.
+
+ Si = Sc * (Ci / Cc)
+
+ Where:
+ Si is the actual list offset used by the server
+ Sc is the server's estimate for content count
+ Ci is the client's submitted offset
+ Cc is the client's submitted content count
+ The result is rounded to the nearest integer.
+
+ If the content count is stable, and the client returns to the server
+ the content count most recently received, Cc = Sc and the offsets
+ transmitted become the actual server list offsets.
+
+ The following special cases exist when the client is specifying the
+ offset and content count:
+ - an offset of one and a content count of non-one (Ci = 1, Cc != 1)
+ indicates that the target is the first entry in the list.
+ - equivalent values (Ci = Cc) indicate that the target is the last
+ entry in the list.
+ - a content count of zero, and a non-zero offset (Cc = 0, Ci != 0)
+ means the client has no idea what the content count is, the server
+ MUST use its own content count estimate in place of the client's.
+
+ Because the server always returns contentCount and targetPosition,
+ the client can always determine which of the returned entries is the
+ target entry. Where the number of entries returned is the same as the
+ number requested, the client is able to identify the target by simple
+ arithmetic. Where the number of entries returned is not the same as
+ the number requested (because the requested range crosses the
+ beginning or end of the list, or both), the client must use the
+ target position and content count values returned by the server to
+ identify the target entry. For example, suppose that 10 entries
+ before and 10 after the target were requested, but the server returns
+ 13 entries, a content count of 100 and a target position of 3. The
+ client can determine that the first entry must be entry number 1 in
+ the list, therefore the 13 entries returned are the first 13 entries
+ in the list, and the target is the third one.
+
+ A server-generated context identifier MAY be returned to clients. A
+ client receiving a context identifier SHOULD return it unchanged in a
+ subsequent request which relates to the same list. The purpose of
+
+
+ Boreham et al Internet-Draft 4
+
+ LDAP Extensions for Scrolling View May 2002
+ Browsing of Search Results
+
+ this interaction is to enhance the performance and effectiveness of
+ servers which employ approximate positioning.
+
+
+6. The Controls
+
+ Support for the virtual list view control extension is indicated by
+ the presence of the OID "2.16.840.1.113730.3.4.9" in the
+ supportedControl attribute of a server's root DSE.
+
+6.1. Request Control
+
+ This control is included in the SearchRequest message as part of the
+ controls field of the LDAPMessage, as defined in Section 4.1.12 of
+ [LDAPv3]. The controlType is set to "2.16.840.1.113730.3.4.9". The
+ criticality SHOULD be set to TRUE. If this control is included in a
+ SearchRequest message, a Server Side Sorting request control [SSS]
+ MUST also be present in the message. The controlValue is an OCTET
+ STRING whose value is the BER-encoding of the following SEQUENCE:
+
+ VirtualListViewRequest ::= SEQUENCE {
+ beforeCount INTEGER (0..maxInt),
+ afterCount INTEGER (0..maxInt),
+ CHOICE {
+ byoffset [0] SEQUENCE {
+ offset INTEGER (0 .. maxInt),
+ contentCount INTEGER (0 .. maxInt) },
+ greaterThanOrEqual [1] AssertionValue },
+ contextID OCTET STRING OPTIONAL }
+
+ beforeCount indicates how many entries before the target entry the
+ client wants the server to send. afterCount indicates the number of
+ entries after the target entry the client wants the server to send.
+ offset and contentCount identify the target entry as detailed in
+ section 4. greaterThanOrEqual is an attribute assertion value defined
+ in [LDAPv3]. If present, the value supplied in greaterThanOrEqual is
+ used to determine the target entry by comparison with the values of
+ the attribute specified as the primary sort key. The first list entry
+ who's value is no less than (less than or equal to when the sort
+ order is reversed) the supplied value is the target entry. If
+ present, the contextID field contains the value of the most recently
+ received contextID field from a VirtualListViewResponse control. The
+ type AssertionValue and value maxInt are defined in [LDAPv3].
+ contextID values have no validity outwith the connection on which
+ they were received. That is, a client should not submit a contextID
+ which it received from another connection, a connection now closed,
+ or a different server.
+
+
+6.2. Response Control
+
+
+ Boreham et al Internet-Draft 5
+
+ LDAP Extensions for Scrolling View May 2002
+ Browsing of Search Results
+
+ This control is included in the SearchResultDone message as part of
+ the controls field of the LDAPMessage, as defined in Section 4.1.12
+ of [LDAPv3].
+
+ The controlType is set to "2.16.840.1.113730.3.4.10". The criticality
+ is FALSE (MAY be absent). The controlValue is an OCTET STRING, whose
+ value is the BER encoding of a value of the following SEQUENCE:
+
+ VirtualListViewResponse ::= SEQUENCE {
+ targetPosition INTEGER (0 .. maxInt),
+ contentCount INTEGER (0 .. maxInt),
+ virtualListViewResult ENUMERATED {
+ success (0),
+ operationsError (1),
+ unwillingToPerform (53),
+ insufficientAccessRights (50),
+ busy (51),
+ timeLimitExceeded (3),
+ adminLimitExceeded (11),
+ sortControlMissing (60),
+ offsetRangeError (61),
+ other (80) },
+ contextID OCTET STRING OPTIONAL }
+
+ targetPosition gives the list offset for the target entry.
+ contentCount gives the server's estimate of the current number of
+ entries in the list. Together these give sufficient information for
+ the client to update a list box slider position to match the newly
+ retrieved entries and identify the target entry. The contentCount
+ value returned SHOULD be used in a subsequent VirtualListViewRequest
+ control. contextID is a server-defined octet string. If present, the
+ contents of the contextID field SHOULD be returned to the server by a
+ client in a subsequent VirtualListViewRequest control.
+
+ The virtualListViewResult codes which are common to the LDAP
+ searchResponse (adminLimitExceeded, timeLimitExceeded, busy,
+ operationsError, unwillingToPerform, insufficientAccessRights) have
+ the same meanings as defined in [LDAPv3], but they pertain
+ specifically to the VLV operation. For example, the server could
+ exceed an administration limit processing a SearchRequest with a
+ VirtualListViewRequest control. However, the same administration
+ limit would not be exceeded should the same SearchRequest be
+ submitted by the client without the VirtualListViewRequest control.
+ In this case, the client can determine that an administration limit
+ has been exceeded in servicing the VLV request, and can if it chooses
+ resubmit the SearchRequest without the VirtualListViewRequest
+ control.
+
+ insufficientAccessRights means that the server denied the client
+ permission to perform the VLV operation.
+
+
+ Boreham et al Internet-Draft 6
+
+ LDAP Extensions for Scrolling View May 2002
+ Browsing of Search Results
+
+ If the server determines that the results of the search presented
+ exceed the range specified in INTEGER values, it MUST return
+ offsetRangeError.
+
+6.2.1 virtualListViewError
+
+ A new LDAP error is introduced called virtualListViewError. Its value
+ is 76.
+ [Note to the IESG/IANA/RFC Editor: the value 76 has been suggested by
+ experts, had expert review, and is currently being used by some
+ implementations. The intent is to have this number designated as an
+ official IANA assigned LDAP Result Code (see draft-ietf-ldapbis-iana-
+ xx.txt, Section 3.5)]
+
+ If the server returns any code other than success (0) for
+ virtualListViewResult, then the server SHOULD return
+ virtualListViewError as the resultCode of the SearchResultDone
+ message.
+
+
+7. Protocol Example
+
+ Here we walk through the client-server interaction for a specific
+ virtual list view example: The task is to display a list of all 78564
+ people in the US company "Ace Industry". This will be done by
+ creating a graphical user interface object to display the list
+ contents, and by repeatedly sending different versions of the same
+ virtual list view search request to the server. The list view
+ displays 20 entries on the screen at a time.
+
+ We form a search with baseDN "o=Ace Industry, c=us"; search scope
+ subtree; filter "objectClass=inetOrgPerson". We attach a server sort
+ order control to the search, specifying ascending sort on attribute
+ "cn". To this base search, we attach a virtual list view request
+ control with contents determined by the user activity and send the
+ search to the server. We display the results from each search in the
+ list window and update the slider position.
+
+ When the list view is first displayed, we want to initialize the
+ contents showing the beginning of the list. Therefore, we set
+ beforeCount = 0, afterCount = 19, contentCount = 0, offset = 1 and
+ send the request to the server. The server duly returns the first 20
+ entries in the list, plus the content count = 78564 and
+ targetPosition = 1. We therefore leave the scroll bar slider at its
+ current location (the top of its range).
+
+ Say that next the user drags the scroll bar slider down to the bottom
+ of its range. We now wish to display the last 20 entries in the list,
+ so we set beforeCount = 19, afterCount = 0, contentCount = 78564,
+ offset = 78564 and send the request to the server. The server returns
+
+
+ Boreham et al Internet-Draft 7
+
+ LDAP Extensions for Scrolling View May 2002
+ Browsing of Search Results
+
+ the last 20 entries in the list, plus the content count = 78564 and
+ targetPosition = 78564.
+
+ Next the user presses a page up key. Our page size is 20, so we set
+ beforeCount = 0, afterCount = 19, contentCount = 78564, offset =
+ 78564-19-20 and send the request to the server. The server returns
+ the preceding 20 entries in the list, plus the content count = 78564
+ and targetPosition = 78525.
+
+ Now the user grabs the scroll bar slider and drags it to 68% of the
+ way down its travel. 68% of 78564 is 53424 so we set beforeCount = 9,
+ afterCount = 10, contentCount = 78564, offset = 53424 and send the
+ request to the server. The server returns the preceding 20 entries in
+ the list, plus the content count = 78564 and targetPosition = 53424.
+
+ Lastly, the user types the letter "B". We set beforeCount = 9,
+ afterCount = 10 and greaterThanOrEqual = "B". The server finds the
+ first entry in the list not less than "B", let's say "Babs Jensen",
+ and returns the nine preceding entries, the target entry, and the
+ proceeding 10 entries. The server returns content count = 78564 and
+ targetPosition = 5234 and so the client updates its scroll bar slider
+ to 6.7% of full scale.
+
+
+8. Notes for Implementers
+
+ While the feature is expected to be generally useful for arbitrary
+ search and sort specifications, it is specifically designed for those
+ cases where the result set is very large. The intention is that this
+ feature be implemented efficiently by means of pre-computed indices
+ pertaining to a set of specific cases. For example, an offset
+ relating to "all the employees in the local organization, sorted by
+ surname" would be a common case.
+
+ The intention for client software is that the feature should fit
+ easily with the host platform's graphical user interface facilities
+ for the display of scrolling lists. Thus the task of the client
+ implementers should be one of reformatting up the requests for
+ information received from the list view code to match the format of
+ the virtual list view request and response controls.
+
+ Client implementers should note that any offset value returned by the
+ server may be approximate. Do not design clients > which only operate
+ correctly when offsets are exact.
+
+ Server implementers using indexing technology which features
+ approximate positioning should consider returning context identifiers
+ to clients. The use of a context identifier will allow the server to
+ distinguish between client requests which relate to different
+ displayed lists on the client. Consequently the server can decide
+ more intelligently whether to reposition an existing database cursor
+
+ Boreham et al Internet-Draft 8
+
+ LDAP Extensions for Scrolling View May 2002
+ Browsing of Search Results
+
+ accurately to within a short distance of its current position, or to
+ reposition to an approximate position. Thus the client will see
+ precise offsets for "short" repositioning (e.g. paging up or down),
+ but approximate offsets for a "long" reposition (e.g. a slider
+ movement).
+
+ Server implementers are free to return status code unwillingToPerform
+ should their server be unable to service any particular VLV search.
+ This might be because the resolution of the search is computationally
+ infeasible, or because excessive server resources would be required
+ to service the search.
+
+ Client implementers should note that this control is only defined on
+ a client interaction with a single server. If a server returns
+ referrals as a part of its response to the search request, the client
+ is responsible for deciding when and how to apply this control to the
+ referred-to servers, and how to collate the results from multiple
+ servers.
+
+
+9. Relationship to "Simple Paged Results"
+
+ These controls are designed to support the virtual list view, which
+ has proved hard to implement with the Simple Paged Results mechanism
+ [SPaged]. However, the controls described here support any operation
+ possible with the Simple Paged Results mechanism. The two mechanisms
+ are not complementary; rather one has a superset of the other's
+ features. One area where the mechanism presented here is not a strict
+ superset of the Simple Paged Results scheme is that here we require a
+ sort order to be specified. No such requirement is made for paged
+ results.
+
+
+10. Security Considerations
+
+ Server implementers may wish to consider whether clients are able to
+ consume excessive server resources in requesting virtual list
+ operations. Access control to the feature itself; configuration
+ options limiting the featureÆs use to certain predetermined search
+ base DNs and filters; throttling mechanisms designed to limit the
+ ability for one client to soak up server resources, may be
+ appropriate.
+
+ Consideration should be given as to whether a client will be able to
+ retrieve the complete contents, or a significant subset of the
+ complete contents of the directory using this feature. This may be
+ undesirable in some circumstances and consequently it may be
+ necessary to enforce some access control.
+
+
+
+
+ Boreham et al Internet-Draft 9
+
+ LDAP Extensions for Scrolling View May 2002
+ Browsing of Search Results
+
+ Clients can, using this control, determine how many entries are
+ contained within a portion of the DIT. This may constitute a security
+ hazard. Again, access controls may be appropriate.
+
+ Server implementers SHOULD exercise caution concerning the content of
+ the contextID. Should the contextID contain internal server state, it
+ may be possible for a malicious client to use that information to
+ gain unauthorized access to information.
+
+
+11. Acknowledgements
+
+ Chris Weider, Anoop Anantha, and Michael Armijo of Microsoft co-
+ authored previous versions of this document.
+
+
+12. References
+
+
+ [LDAPv3] Wahl, M., Kille, S. and T. Howes, "Lightweight Directory
+ Access Protocol (v3)", Internet Standard, RFC 2251,
+ December, 1997.
+
+ [SPaged] Weider, C., Herron, A., Anantha, A. and T. Howes, "LDAP
+ Control Extension for Simple Paged Results Manipulation",
+ RFC2696, September 1999.
+
+ [SSS] Wahl, M., Herron, A. and T. Howes, "LDAP Control
+ Extension for Server Side Sorting of Search Results",
+ RFC 2891, August, 2000.
+
+ [Bradner97] Bradner, S., "Key Words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Boreham et al Internet-Draft 10
+
+ LDAP Extensions for Scrolling View May 2002
+ Browsing of Search Results
+
+13. Authors' Addresses
+
+ David Boreham
+ Bozeman Pass, Inc
+ +1 406 222 7093
+ david at bozemanpass.com
+
+ Jim Sermersheim
+ Novell, Inc
+ 1800 South Novell Place
+ Provo, Utah 84606, USA
+ jimse at novell.com
+
+ Asaf Kashi
+ Microsoft Corporation
+ 1 Microsoft Way
+ Redmond, WA 98052, USA
+ +1 425 882-8080
+ asafk at microsoft.com
+
+
+14. Full Copyright Statement
+
+ Copyright (C) The Internet Society (2002). All Rights Reserved.
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English. The limited permissions granted above are perpetual and will
+ not be revoked by the Internet Society or its successors or assigns.
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE
+ INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
+ THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
+ WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE."
+
+
+
+
+
+
+
+
+ Boreham et al Internet-Draft 11
\ No newline at end of file
Added: openldap/vendor/openldap-release/doc/drafts/draft-ietf-ldapext-locate-xx.txt
===================================================================
--- openldap/vendor/openldap-release/doc/drafts/draft-ietf-ldapext-locate-xx.txt (rev 0)
+++ openldap/vendor/openldap-release/doc/drafts/draft-ietf-ldapext-locate-xx.txt 2008-06-28 09:29:58 UTC (rev 1147)
@@ -0,0 +1,362 @@
+
+
+INTERNET-DRAFT Michael P. Armijo
+<draft-ietf-ldapext-locate-08.txt> Levon Esibov
+June 5, 2002 Paul Leach
+Expires: December 5, 2002 Microsoft Corporation
+ R.L. Morgan
+ University of Washington
+
+ Discovering LDAP Services with DNS
+
+Status of this Memo
+
+ This document is an Internet-Draft and is in full conformance with
+ all provisions of Section 10 of RFC2026.
+
+ Internet-Drafts are working documents of the Internet Engineering
+ Task Force (IETF), its areas, and its working groups. Note that
+ other groups may also distribute working documents as Internet-
+ Drafts.
+
+ Internet-Drafts are draft documents valid for a maximum of six months
+ and may be updated, replaced, or obsoleted by other documents at any
+ time. It is inappropriate to use Internet- Drafts as reference
+ material or to cite them other than as "work in progress."
+
+ The list of current Internet-Drafts can be accessed at
+ http://www.ietf.org/ietf/1id-abstracts.txt
+
+ The list of Internet-Draft Shadow Directories can be accessed at
+ http://www.ietf.org/shadow.html.
+
+ Distribution of this memo is unlimited. It is filed as <draft-
+ ietf-ldapext-locate-08.txt>, and expires on December 5, 2002.
+ Please send comments to the authors.
+
+ Copyright Notice
+
+ Copyright (C) The Internet Society (2001). All Rights Reserved.
+
+
+Abstract
+
+ A Lightweight Directory Access Protocol (LDAP) request must be
+ directed to an appropriate server for processing. This document
+ specifies a method for discovering such servers using information in
+ the Domain Name System.
+
+
+
+
+
+
+
+
+
+Armijo, Esibov, Leach and Morgan [Page 1]
+
+INTERNET-DRAFT Discovering LDAP Services with DNS June 5, 2002
+
+
+
+1. Introduction
+
+ The LDAPv3 protocol [1] is designed to be a lightweight access
+ protocol for directory services supporting X.500 models. As a
+ distributed directory service, the complete set of directory
+ information (known as the Directory Information Base) is spread
+ across many different servers. Hence there is the need to
+ determine, when initiating or processing a request, which servers
+ hold the relevant information. In LDAP, the Search, Modify, Add,
+ Delete, ModifyDN, and Compare operations all specify a Distinguished
+ Name (DN) [2] on which the operation is performed. A client, or a
+ server acting on behalf of a client, must be able to determine the
+ server(s) that hold the naming context containing that DN, since
+ that server (or one of that set of servers) must receive and process
+ the request. This determination process is called "server
+ location". To support dynamic distributed operation, the
+ information needed to support server location must be available via
+ lookups done at request processing time, rather than, for example,
+ as static data configured into each client or server.
+
+ It is possible to maintain the information needed to support server
+ location in the directory itself, and X.500 directory deployments
+ typically do so. In practice, however, this only permits location
+ of servers within a limited X.500-connected set. LDAP-specific
+ methods of maintaining server location information in the directory
+ have not yet been standardized. This document defines an
+ alternative method of managing server location information using the
+ Domain Name System. This method takes advantage of the global
+ deployment of the DNS, by allowing LDAP server location information
+ for any existing DNS domain to be published by creating the records
+ described below. A full discussion of the benefits and drawbacks of
+ the various directory location and naming methods is beyond the
+ scope of this document.
+
+ RFC 2247[3] defines an algorithm for mapping DNS domain names into
+ DNs. This document defines the inverse mapping, from DNs to DNS
+ domain names, based on the conventions in [3], for use in this
+ server location method. The server location method described in
+ this document is only defined for DNs that can be so mapped, i.e.,
+ those DNs that are based on domain names. In practice this is
+ reasonable because many objects of interest are named with domain
+ names, and use of domain-name-based DNs is becoming common.
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in RFC 2119 [9].
+
+
+
+
+
+
+Armijo, Esibov, Leach and Morgan [Page 2]
+
+INTERNET-DRAFT Discovering LDAP Services with DNS June 5, 2002
+
+
+2. Mapping Distinguished Names into Domain Names
+
+ This section defines a method of converting a DN into a DNS domain
+ name for use in the server location method described below. Some
+ DNs cannot be converted into a domain name. Converted DNs result
+ in a fully qualified domain name.
+
+
+ The output domain name is initially empty. The DN is processed in
+ right-to-left order (i.e., beginning with the first RDN in the
+ sequence of RDNs). An RDN is able to be converted if it (1)
+ consists of a single AttributeTypeAndValue; (2) the attribute type
+ is "DC"; and (3) the attribute value is non-null. If it can be
+ converted, the attribute value is used as a domain name component
+ (label). The first such value becomes the rightmost (i.e., most
+ significant) domain name component, and successive converted RDN
+ values extend to the left. If an RDN cannot be converted,
+ processing stops. If the output domain name is empty when
+ processing stops, the DN cannot be converted into a domain name.
+
+ For DN:
+
+ cn=John Doe,ou=accounting,dc=example,dc=net
+
+ The client would convert the DC components as defined above into
+ DNS name:
+
+ example.net
+
+ The determined DNS name will be submitted as a DNS query using the
+ algorithm defined in section 3.
+
+
+
+3. Locating LDAPv3 servers through DNS
+
+ LDAPv3 server location information is to be stored using DNS Service
+ Location Record (SRV)[5]. The data in a SRV record contains the DNS
+ name of the server that provides the LDAP service, corresponding
+ Port number, and parameters that enable the client to choose an
+ appropriate server from multiple servers according to the algorithm
+ described in [5]. The name of this record has the following format:
+
+ _<Service>._<Proto>.<Domain>.
+
+ where <Service> is "ldap", and <Proto> is "tcp". <Domain> is the
+ domain name formed by converting the DN of a naming context mastered
+ by the LDAP Server into a domain name using the algorithm in
+ Section 2. Note that "ldap" is the symbolic name for the LDAP
+ service in Assigned Numbers[6], as required by [5].
+
+
+
+Armijo, Esibov, Leach and Morgan [Page 3]
+
+INTERNET-DRAFT Discovering LDAP Services with DNS June 5, 2002
+
+
+ Presence of such records enables clients to find the LDAP servers
+ using standard DNS query [4]. A client (or server) seeking an LDAP
+ server for a particular DN converts that DN to a domain name using
+ the algorithm of Section 2, does a SRV record query using the DNS
+ name formed as described in the preceding paragraph, and interprets
+ the response as described in [5] to determine a host (or hosts) to
+ contact. As an example, a client that searches for an LDAP server
+ for the DN "ou=foo,dc=example,dc=net" that supports the TCP protocol
+ will submit a DNS query for a set of SRV records with owner name:
+
+ _ldap._tcp.example.net.
+
+ The client will receive the list of SRV records published in DNS
+ that satisfy the requested criteria. The following is an example of
+ such a record:
+
+ _ldap._tcp.example.net. IN SRV 0 0 389 phoenix.example.net.
+
+ The set of returned records may contain multiple records in the case
+ where multiple LDAP servers serve the same domain. If there are no
+ matching SRV records available for the converted DN the client SHOULD
+ NOT attempt to 'walk the tree' by removing the least significant
+ portion of the constructed fully qualified domain name.
+
+
+4. IANA Considerations
+
+ This document does not require any IANA actions.
+
+
+5. Security Considerations
+
+ DNS responses can typically be easily spoofed. Clients using this
+ location method SHOULD ensure, via use of strong security
+ mechanisms, that the LDAP server they contact is the one they
+ intended to contact. See [7] for more information on security
+ threats and security mechanisms.
+
+ When using LDAP with TLS the client MUST check the server's name,
+ as described in section 3.6 of [RFC 2830]. As specified there, the
+ name the client checks for is the server's name before any
+ potentially insecure transformations, including the SRV record
+ lookup specified in this memo. Thus the name the client MUST check
+ for is the name obtained by doing the mapping step defined in
+ section 2 above. For example, if the DN "cn=John
+ Doe,ou=accounting,dc=example,dc=net" is converted to the DNS name
+ "example.net", the server's name MUST match "example.net".
+
+ This document describes a method that uses DNS SRV records to
+ discover LDAP servers. All security considerations related to DNS
+ SRV records are inherited by this document. See the security
+ considerations section in [5] for more details.
+
+Armijo, Esibov, Leach and Morgan [Page 4]
+
+INTERNET-DRAFT Discovering LDAP Services with DNS June 5, 2002
+
+
+6. References
+
+ [1] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access
+ Protocol(v3)", RFC 2251, December 1997.
+
+ [2] Wahl, M., Kille, S. and T. Howes, "Lightweight Directory Access
+ Protocol (v3): UTF-8 String Representation of Distinguished
+ Names", RFC 2253, December 1997.
+
+ [3] Kille, S. and M. Wahl, "Using Domains in LDAP/X.500
+ Distinguished Names", RFC 2247, January 1998.
+
+ [4] Mockapetris, P., "DOMAIN NAMES - CONCEPTS AND FACILITIES", RFC
+ 1034, STD 13, November 1987.
+
+ [5] Gulbrandsen, A., Vixie, P. and L. Esibov, "A DNS RR for
+ specifying the location of services (DNS SRV)", RFC 2782,
+ February 2000.
+
+ [6] Reynolds, J. and J. Postel, "Assigned Numbers", STD 2, RFC
+ 1700, October 1994.
+
+ [7] Wahl, M., Alvestrand, H., Hodges, J. and Morgan, R.,
+ "Authentication Methods for LDAP", RFC 2829, May 2000.
+
+ [8] Hodges, J., Morgan, R., Wahl, M., "Lightweight Directory Access
+ Protocol (v3): Extension for Transport Layer Security",
+ RFC 2830, May 2000.
+
+ [9] Bradner, S., "Key words for use in RFCs to Indicate Requirement
+ Levels", BCP 14, RFC 2119, March 1997.
+
+
+
+
+7. Authors' Addresses
+
+ Michael P. Armijo
+ One Microsoft Way
+ Redmond, WA 98052
+ micharm at microsoft.com
+
+ Paul Leach
+ One Microsoft Way
+ Redmond, WA 98052
+ paulle at microsoft.com
+
+ Levon Esibov
+ One Microsoft Way
+ Redmond, WA 98052
+ levone at microsoft.com
+
+
+Armijo, Esibov, Leach and Morgan [Page 5]
+
+INTERNET-DRAFT Discovering LDAP Services with DNS June 5, 2002
+
+ RL "Bob" Morgan
+ University of Washington
+ 4545 15th Ave NE
+ Seattle, WA 98105
+ US
+
+ Phone: +1 206 221 3307
+ EMail: rlmorgan at washington.edu
+ URI: http://staff.washington.edu/rlmorgan/
+
+
+8. Intellectual Property Statement
+
+The IETF takes no position regarding the validity or scope of any
+intellectual property or other rights that might be claimed to pertain
+to the implementation or use of the technology described in this
+document or the extent to which any license under such rights might or
+might not be available; neither does it represent that it has made any
+effort to identify any such rights. Information on the IETF's
+procedures with respect to rights in standards-track and standards-
+related documentation can be found in BCP-11. Copies of claims of
+rights made available for publication and any assurances of licenses to
+be made available, or the result of an attempt made to obtain a general
+license or permission for the use of such proprietary rights by
+implementors or users of this specification can be obtained from the
+IETF Secretariat.
+
+The IETF invites any interested party to bring to its attention any
+copyrights, patents or patent applications, or other proprietary rights
+which may cover technology that may be required to practice this
+standard. Please address the information to the IETF Executive
+Director.
+
+
+9. Full Copyright Statement
+
+Copyright (C) The Internet Society (2001). All Rights Reserved.
+This document and translations of it may be copied and furnished to
+others, and derivative works that comment on or otherwise explain it or
+assist in its implementation may be prepared, copied, published and
+distributed, in whole or in part, without restriction of any kind,
+provided that the above copyright notice and this paragraph are included
+on all such copies and derivative works. However, this document itself
+may not be modified in any way, such as by removing the copyright notice
+or references to the Internet Society or other Internet organizations,
+except as needed for the purpose of developing Internet standards in
+which case the procedures for copyrights defined in the Internet
+Standards process must be followed, or as required to translate it into
+languages other than English. The limited permissions granted above are
+perpetual and will not be revoked by the Internet Society or its
+successors or assigns. This document and the information contained
+herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE
+
+
+Armijo, Esibov, Leach and Morgan [Page 6]
+
+INTERNET-DRAFT Discovering LDAP Services with DNS June 5, 2002
+
+INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
+INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
+WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE."
+
+
+10. Expiration Date
+
+ This document is filed as <draft-ietf-ldapext-locate-08.txt>, and
+ expires December 5, 2002.
+
+Armijo, Esibov, Leach and Morgan [Page 7]
\ No newline at end of file
Added: openldap/vendor/openldap-release/doc/drafts/draft-joslin-config-schema-xx.txt
===================================================================
--- openldap/vendor/openldap-release/doc/drafts/draft-joslin-config-schema-xx.txt (rev 0)
+++ openldap/vendor/openldap-release/doc/drafts/draft-joslin-config-schema-xx.txt 2008-06-28 09:29:58 UTC (rev 1147)
@@ -0,0 +1,1790 @@
+
+INTERNET-DRAFT M. Ansari
+draft-joslin-config-schema-10.txt Infoblox
+Category: Informational L. Howard
+Expires: September 2005 PADL Software Pty. Ltd.
+ B. Neal-Joslin, Editor
+ Hewlett-Packard Company
+ 4 March, 2005
+
+
+ A Configuration Schema for LDAP Based
+ Directory User Agents
+
+
+Status of this Memo
+
+ Copyright (C) The Internet Society (2005). This document is subject
+ to the rights, licenses and restrictions contained in BCP 78, and
+ except as set forth therein, the authors retain all their rights.
+
+ This document and the information contained herein are provided on
+ an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE
+ REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND
+ THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES,
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT
+ THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR
+ ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A
+ PARTICULAR PURPOSE.
+
+ Internet-Drafts are working documents of the Internet Engineering
+ Task Force (IETF), its areas, and its working groups. Note that
+ other groups may also distribute working documents as Internet-
+ Drafts.
+
+ Internet-Drafts are draft documents valid for a maximum of six
+ months and may be updated, replaced, or obsoleted by other
+ documents at any time. It is inappropriate to use Internet-Drafts
+ as reference material or to cite them other than as "work in
+ progress."
+
+ The list of current Internet-Drafts can be accessed at
+ http://www.ietf.org/1id-abstracts.html
+
+ The list of Internet-Draft Shadow Directories can be accessed at
+ http://www.ietf.org/shadow.html
+
+IPR Statement
+
+ By submitting this Internet-Draft, I certify that any applicable
+
+
+
+Neal-Joslin [Page 1]
+
+Internet-Draft DUA Configuration Schema March 2005
+
+
+ patent or other IPR claims of which I am aware have been disclosed,
+ or will be disclosed, and any of which I become aware will be
+ disclosed, in accordance with RFC 3668.
+
+ The IETF takes no position regarding the validity or scope of any
+ Intellectual Property Rights or other rights that might be claimed
+ to pertain to the implementation or use of the technology described
+ in this document or the extent to which any license under such
+ rights might or might not be available; nor does it represent that
+ it has made any independent effort to identify any such rights.
+ Information on the procedures with respect to rights in RFC
+ documents can be found in BCP 78 and BCP 79.
+
+ The IETF invites any interested party to bring to its attention any
+ copyrights, patents or patent applications, or other proprietary
+ rights that may cover technology that may be required to implement
+ this standard. Please address the information to the IETF at
+ ietf-ipr at ietf.org.
+
+ Copies of IPR disclosures made to the IETF Secretariat and any
+ assurances of licenses to be made available, or the result of an
+ attempt made to obtain a general license or permission for the use
+ of such proprietary rights by implementers or users of this
+ specification can be obtained from the IETF on-line IPR repository
+ at http://www.ietf.org/ipr.
+
+
+
+
+
+Abstract
+
+ This document describes a mechanism for distributed configuration
+ of similar directory user agents. This document defines a schema
+ for configuration of these DUAs that may be discovered using the
+ Lightweight Directory Access Protocol in RFC 2251[1]. A set of
+ attribute types and an objectclass are proposed, along with
+ specific guidelines for interpreting them. A proposal of using
+ attribute and objectclass mapping allows DUAs to re-configure their
+ schema to that of the end user's environment. This document is
+ intended to be a skeleton for future documents that describe
+ configuration of specific DUA services.
+
+
+
+
+
+
+
+
+
+Neal-Joslin [Page 2]
+
+Internet-Draft DUA Configuration Schema March 2005
+
+
+ Table of Contents
+
+ 1. Background & Motivation ...................................... 4
+ 2. General Issues ............................................... 5
+ 2.1 Terminology .................................................. 5
+ 2.2 Attributes ................................................... 5
+ 2.3 Object Classes ............................................... 6
+ 2.4 Syntax Definitions ........................................... 6
+ 3. Attribute Definitions ........................................ 6
+ 4. Class Definition ............................................. 8
+ 5. Implementation Details ....................................... 9
+ 5.1.1 Interpreting the preferredServerList attribute ............. 9
+ 5.1.2 Interpreting the defaultServerList attribute ............... 10
+ 5.1.3 Interpreting the defaultSearchBase attribute ............... 11
+ 5.1.4 Interpreting the authenticationMethod attribute ............ 12
+ 5.1.5 Interpreting the credentialLevel attribute ................. 13
+ 5.1.6 Interpreting the serviceSearchDescriptor attribute ......... 14
+ 5.1.7 Interpreting the attributeMap attribute .................... 17
+ 5.1.8 Interpreting the searchTimeLimit attribute ................. 20
+ 5.1.9 Interpreting the bindTimeLimit attribute ................... 20
+ 5.1.10 Interpreting the followReferrals attribute ................ 21
+ 5.1.11 Interpreting the dereferenceAliases attribute ............. 21
+ 5.1.12 Interpreting the profileTTL attribute ..................... 21
+ 5.1.13 Interpreting the objectclassMap attribute ................. 22
+ 5.1.14 Interpreting the defaultSearchScope attribute ............. 24
+ 5.1.15 Interpreting the serviceAuthenticationMethod attribute .... 24
+ 5.1.16 Interpreting the serviceCredentialLevel attribute ......... 25
+ 5.2 Binding to the Directory Server .............................. 26
+ 6. Security Considerations ...................................... 26
+ 7. Acknowledgments .............................................. 27
+ 8. References ................................................... 27
+ 8.1 Normative References ......................................... 27
+ 8.2 Informative References ....................................... 28
+ 9. Examples ..................................................... 29
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Neal-Joslin [Page 3]
+
+Internet-Draft DUA Configuration Schema March 2005
+
+
+1. Background & Motivation
+
+ The LDAP protocol has brought about a new and nearly ubiquitous
+ acceptance of the directory server. Many new client applications
+ (DUAs) are being created that use LDAP directories for many
+ different services. And although the LDAP protocol has eased the
+ development of these applications, some challenges still exist for
+ both developers and directory administrators.
+
+ The authors of this document are implementers of DUAs described by
+ RFC 2307 [2]. In developing these agents, we felt there are
+ several issues that still need to be addressed to ease the
+ deployment and configuration of a large network of these DUAs.
+
+ One of these challenges stems from the lack of a utopian schema. A
+ utopian schema would be one that every application developer could
+ agree upon and that would support every application. Unfortunately
+ today, many DUAs define their own schema (like RFC 2307 vs.
+ Microsoft's Services for Unix [3]) containing similar attributes,
+ but with different attribute names. This can lead to data
+ redundancy within directory entries and give directory
+ administrators unwanted challenges, updating schemas and
+ synchronizing data.
+
+ So, one goal of this document is to eliminate data redundancy by
+ having DUAs configure themselves to the schema of the deployed
+ directory, instead of forcing its own schema on the directory.
+
+ Another goal of this document is to provide the DUA with enough
+ configuration information so that it can discover how to retrieve
+ its data in the directory, such as what locations to search in the
+ directory tree.
+
+ Finally, this document intends to describe a configuration method
+ for DUAs that can be shared among many DUAs, on various platforms,
+ providing as such, a configuration profile, the purpose is to
+ centralize and simplify management of DUAs.
+
+ This document is intended to provide the skeleton framework for
+ future drafts, which will describe the individual implementation
+ details for the particular services provided by that DUA. The
+ authors of this document plan to develop such a document for the
+ Network Information Service DUA, described by RFC 2307 or its
+ successor.
+
+ We expect that as DUAs take advantage of this configuration scheme,
+ each DUA will require additional configuration parameters, not
+ specified by this document. Thus, we would expect that new
+
+
+
+Neal-Joslin [Page 4]
+
+Internet-Draft DUA Configuration Schema March 2005
+
+
+ auxiliary object classes, containing new configuration attributes
+ will be created, and then joined with the structural class defined
+ by this document to create a configuration profile for a particular
+ DUA service. And that by joining various auxiliary objectclasses
+ for different DUA services, that configuration of various DUA
+ services can be controlled by a single configuration profile entry.
+
+
+2. General Issues
+
+ The schema defined by this document is defined under the "DUA
+ Configuration Schema." This schema is derived from the OID: iso
+ (1) org (3) dod (6) internet (1) private (4) enterprises (1)
+ Hewlett-Packard Company (11) directory (1) LDAP-UX Integration
+ Project (3) DUA Configuration Schema (1). This OID is represented
+ in this document by the keystring "DUAConfSchemaOID"
+ (1.3.6.1.4.1.11.1.3.1).
+
+2.1 Terminology
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in
+ this document are to be interpreted as described in BCP 14 (RFC
+ 2119) [4].
+
+2.2 Attributes
+
+ The attributes and classes defined in this document are summarized
+ below.
+
+ The following attributes are defined in this document:
+
+ preferredServerList
+ defaultServerList
+ defaultSearchBase
+ defaultSearchScope
+ authenticationMethod
+ credentialLevel
+ serviceSearchDescriptor
+ serviceCredentialLevel
+ serviceAuthenticationMethod
+ attributeMap
+ objectclassMap
+ searchTimeLimit
+ bindTimeLimit
+ followReferrals
+ dereferenceAliases
+ profileTTL
+
+
+
+Neal-Joslin [Page 5]
+
+Internet-Draft DUA Configuration Schema March 2005
+
+
+2.3 Object Classes
+
+ The following object class is defined in this document:
+
+ DUAConfigProfile
+
+2.4 Syntax Definitions
+
+ The following syntax definitions are used throughout this document.
+ This document does not define new syntaxes that must be supported
+ by the directory server. The string encoding used by the
+ attributes defined in this document can be found section 5.
+
+ keystring as defined by RFC 2252 [5]
+ descr as defined by RFC 2252 section 4.1
+ a as defined by RFC 2252 section 4.1
+ d as defined by RFC 2252 section 4.1
+ space as defined by RFC 2252 section 4.1
+ whsp as defined by RFC 2252 section 4.1
+ base as defined by RFC 2253 [6]
+ DistinguishedName as defined by RFC 2253 section 2
+ RelativeDistinguishedName as defined by RFC 2253 section 2
+ scope as defined by RFC 2255 [7]
+ host as defined by RFC 3986
+ section 3.2.2 [8]
+ hostport host [":" port ]
+ port as defined by RFC 3986
+ section 3.2.3 [8]
+ serviceID = keystring
+
+
+3. Attribute Definitions
+
+ This section contains attribute definitions to be used by DUAs when
+ discovering their configuration.
+
+ ( DUAConfSchemaOID.1.0 NAME 'defaultServerList'
+ DESC 'Default LDAP server host addresses used by a DUA'
+ EQUALITY caseIgnoreMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
+ SINGLE-VALUE )
+
+ ( DUAConfSchemaOID.1.1 NAME 'defaultSearchBase'
+ DESC 'Default LDAP base DN used by a DUA'
+ EQUALITY distinguishedNameMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
+ SINGLE-VALUE )
+
+
+
+
+Neal-Joslin [Page 6]
+
+Internet-Draft DUA Configuration Schema March 2005
+
+
+ ( DUAConfSchemaOID.1.2 NAME 'preferredServerList'
+ DESC 'Preferred LDAP server host addresses to be used by a
+ DUA'
+ EQUALITY caseIgnoreMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
+ SINGLE-VALUE )
+
+ ( DUAConfSchemaOID.1.3 NAME 'searchTimeLimit'
+ DESC 'Maximum time in seconds a DUA should allow for a
+ search to complete'
+ EQUALITY integerMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
+ SINGLE-VALUE )
+
+ ( DUAConfSchemaOID.1.4 NAME 'bindTimeLimit'
+ DESC 'Maximum time in seconds a DUA should allow for the
+ bind operation to complete'
+ EQUALIT