D7net
Home
Console
Upload
information
Create File
Create Folder
About
Tools
:
/
proc
/
self
/
root
/
home
/
vblioqus
/
karachi777.vip
/
images
/
494334
/
65412
/
Filename :
share.zip
back
Copy
PK Ɠc\ m�&$ $ man/man3/ld_errno.3nu �[��� .lf 1 stdin .TH LDAP_ERROR 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_perror, ld_errno, ldap_result2error, ldap_errlist, ldap_err2string \- LDAP protocol error handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_err2string( int \fIerr\fB ); .SH DESCRIPTION The .B ldap_err2string() routine provides short description of the various codes returned by routines in this library. The returned string is a pointer to a static area that should not be modified. These codes are either negative, indicating an API error code; positive, indicating an LDAP resultCode other than \'success' (0), or - zero, indicating both successful use of the API and the LDAP resultCode \'success' (0). The code associated with an LDAP session is accessible using .BR ldap_get_option (3) and .BR ldap_set_option (3) with the .B LDAP_OPT_RESULT_CODE option (previously called .BR LDAP_OPT_ERROR_NUMBER ). .SH PROTOCOL RESULT CODES This section provides a partial list of protocol codes recognized by the library. As LDAP is extensible, additional values may be returned. A complete listing of \fIregistered\fP LDAP result codes can be obtained from the \fIInternet Assigned Numbers Authority\fP <http://www.iana.org>. .LP .TP 20 .SM LDAP_SUCCESS The request was successful. .TP .SM LDAP_OPERATIONS_ERROR An operations error occurred. .TP .SM LDAP_PROTOCOL_ERROR A protocol violation was detected. .TP .SM LDAP_TIMELIMIT_EXCEEDED An LDAP time limit was exceeded. .TP .SM LDAP_SIZELIMIT_EXCEEDED An LDAP size limit was exceeded. .TP .SM LDAP_COMPARE_FALSE A compare operation returned false. .TP .SM LDAP_COMPARE_TRUE A compare operation returned true. .TP .SM LDAP_STRONG_AUTH_NOT_SUPPORTED The LDAP server does not support strong authentication. .TP .SM LDAP_STRONG_AUTH_REQUIRED Strong authentication is required for the operation. .TP .SM LDAP_PARTIAL_RESULTS Partial results only returned. .TP .SM LDAP_NO_SUCH_ATTRIBUTE The attribute type specified does not exist in the entry. .TP .SM LDAP_UNDEFINED_TYPE The attribute type specified is invalid. .TP .SM LDAP_INAPPROPRIATE_MATCHING Filter type not supported for the specified attribute. .TP .SM LDAP_CONSTRAINT_VIOLATION An attribute value specified violates some constraint (e.g., a postalAddress has too many lines, or a line that is too long). .TP .SM LDAP_TYPE_OR_VALUE_EXISTS An attribute type or attribute value specified already exists in the entry. .TP .SM LDAP_INVALID_SYNTAX An invalid attribute value was specified. .TP .SM LDAP_NO_SUCH_OBJECT The specified object does not exist in The Directory. .TP .SM LDAP_ALIAS_PROBLEM An alias in The Directory points to a nonexistent entry. .TP .SM LDAP_INVALID_DN_SYNTAX A syntactically invalid DN was specified. .TP .SM LDAP_IS_LEAF The object specified is a leaf. .TP .SM LDAP_ALIAS_DEREF_PROBLEM A problem was encountered when dereferencing an alias. .TP .SM LDAP_INAPPROPRIATE_AUTH Inappropriate authentication was specified (e.g., LDAP_AUTH_SIMPLE was specified and the entry does not have a userPassword attribute). .TP .SM LDAP_INVALID_CREDENTIALS Invalid credentials were presented (e.g., the wrong password). .TP .SM LDAP_INSUFFICIENT_ACCESS The user has insufficient access to perform the operation. .TP .SM LDAP_BUSY The DSA is busy. .TP .SM LDAP_UNAVAILABLE The DSA is unavailable. .TP .SM LDAP_UNWILLING_TO_PERFORM The DSA is unwilling to perform the operation. .TP .SM LDAP_LOOP_DETECT A loop was detected. .TP .SM LDAP_NAMING_VIOLATION A naming violation occurred. .TP .SM LDAP_OBJECT_CLASS_VIOLATION An object class violation occurred (e.g., a "must" attribute was missing from the entry). .TP .SM LDAP_NOT_ALLOWED_ON_NONLEAF The operation is not allowed on a nonleaf object. .TP .SM LDAP_NOT_ALLOWED_ON_RDN The operation is not allowed on an RDN. .TP .SM LDAP_ALREADY_EXISTS The entry already exists. .TP .SM LDAP_NO_OBJECT_CLASS_MODS Object class modifications are not allowed. .TP .SM LDAP_OTHER An unknown error occurred. .SH API ERROR CODES This section provides a complete list of API error codes recognized by the library. Note that LDAP_SUCCESS indicates success of an API call in addition to representing the return of the LDAP \'success' resultCode. .LP .TP 20 .SM LDAP_SERVER_DOWN The LDAP library can't contact the LDAP server. .TP .SM LDAP_LOCAL_ERROR Some local error occurred. This is usually a failed dynamic memory allocation. .TP .SM LDAP_ENCODING_ERROR An error was encountered encoding parameters to send to the LDAP server. .TP .SM LDAP_DECODING_ERROR An error was encountered decoding a result from the LDAP server. .TP .SM LDAP_TIMEOUT A timelimit was exceeded while waiting for a result. .TP .SM LDAP_AUTH_UNKNOWN The authentication method specified to ldap_bind() is not known. .TP .SM LDAP_FILTER_ERROR An invalid filter was supplied to ldap_search() (e.g., unbalanced parentheses). .TP .SM LDAP_PARAM_ERROR An ldap routine was called with a bad parameter. .TP .SM LDAP_NO_MEMORY An memory allocation (e.g., malloc(3) or other dynamic memory allocator) call failed in an ldap library routine. .TP .SM LDAP_USER_CANCELED Indicates the user cancelled the operation. .TP .SM LDAP_CONNECT_ERROR Indicates a connection problem. .TP .SM LDAP_NOT_SUPPORTED Indicates the routine was called in a manner not supported by the library. .TP .SM LDAP_CONTROL_NOT_FOUND Indicates the control provided is unknown to the client library. .TP .SM LDAP_NO_RESULTS_RETURNED Indicates no results returned. .TP .SM LDAP_MORE_RESULTS_TO_RETURN Indicates more results could be returned. .TP .SM LDAP_CLIENT_LOOP Indicates the library has detected a loop in its processing. .TP .SM LDAP_REFERRAL_LIMIT_EXCEEDED Indicates the referral limit has been exceeded. .SH DEPRECATED .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 220 stdin .SH SEE ALSO .BR ldap (3), .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 225 stdin PK Ɠc\�շY� � man/man3/ber_bvfree.3nu �[��� .lf 1 stdin .TH LBER_TYPES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_int_t, ber_uint_t, ber_len_t, ber_slen_t, ber_tag_t, struct berval, BerValue, BerVarray, BerElement, ber_bvfree, ber_bvecfree, ber_bvecadd, ber_bvarray_free, ber_bvarray_add, ber_bvdup, ber_dupbv, ber_bvstr, ber_bvstrdup, ber_str2bv, ber_alloc_t, ber_init, ber_init2, ber_free \- OpenLDAP LBER types and allocation functions .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .nf .ft B typedef impl_tag_t ber_tag_t; typedef impl_int_t ber_int_t; typedef impl_uint_t ber_uint_t; typedef impl_len_t ber_len_t; typedef impl_slen_t ber_slen_t; typedef struct berval { ber_len_t bv_len; char *bv_val; } BerValue, *BerVarray; typedef struct berelement BerElement; .ft .fi .LP .BI "void ber_bvfree(struct berval *" bv ");" .LP .BI "void ber_bvecfree(struct berval **" bvec ");" .LP .BI "void ber_bvecadd(struct berval ***" bvec ", struct berval *" bv ");" .LP .BI "void ber_bvarray_free(struct berval *" bvarray ");" .LP .BI "void ber_bvarray_add(BerVarray *" bvarray ", BerValue *" bv ");" .LP .BI "struct berval *ber_bvdup(const struct berval *" bv ");" .LP .BI "struct berval *ber_dupbv(const struct berval *" dst ", struct berval *" src ");" .LP .BI "struct berval *ber_bvstr(const char *" str ");" .LP .BI "struct berval *ber_bvstrdup(const char *" str ");" .LP .BI "struct berval *ber_str2bv(const char *" str ", ber_len_t " len ", int " dup ", struct berval *" bv ");" .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "BerElement *ber_init(struct berval *" bv ");" .LP .BI "void ber_init2(BerElement *" ber ", struct berval *" bv ", int " options ");" .LP .BI "void ber_free(BerElement *" ber ", int " freebuf ");" .SH DESCRIPTION .LP The following are the basic types and structures defined for use with the Lightweight BER library. .LP .B ber_int_t is a signed integer of at least 32 bits. It is commonly equivalent to .BR int . .B ber_uint_t is the unsigned variant of .BR ber_int_t . .LP .B ber_len_t is an unsigned integer of at least 32 bits used to represent a length. It is commonly equivalent to a .BR size_t . .B ber_slen_t is the signed variant to .BR ber_len_t . .LP .B ber_tag_t is an unsigned integer of at least 32 bits used to represent a BER tag. It is commonly equivalent to a .BR unsigned\ long . .LP The actual definitions of the integral impl_TYPE_t types are platform specific. .LP .BR BerValue , commonly used as .BR struct\ berval , is used to hold an arbitrary sequence of octets. .B bv_val points to .B bv_len octets. .B bv_val is not necessarily terminated by a NULL (zero) octet. .BR ber_bvfree () frees a BerValue, pointed to by \fIbv\fP, returned from this API. If \fIbv\fP is NULL, the routine does nothing. .LP .BR ber_bvecfree () frees an array of BerValues (and the array), pointed to by \fIbvec\fP, returned from this API. If \fIbvec\fP is NULL, the routine does nothing. .BR ber_bvecadd () appends the \fIbv\fP pointer to the \fIbvec\fP array. Space for the array is allocated as needed. The end of the array is marked by a NULL pointer. .LP .BR ber_bvarray_free () frees an array of BerValues (and the array), pointed to by \fIbvarray\fP, returned from this API. If \fIbvarray\fP is NULL, the routine does nothing. .BR ber_bvarray_add () appends the contents of the BerValue pointed to by \fIbv\fP to the \fIbvarray\fP array. Space for the new element is allocated as needed. The end of the array is marked by a BerValue with a NULL bv_val field. .LP .BR ber_bvdup () returns a copy of a BerValue. The routine returns NULL upon error (e.g. out of memory). The caller should use .BR ber_bvfree () to deallocate the resulting BerValue. .BR ber_dupbv () copies a BerValue from \fIsrc\fP to \fIdst\fP. If \fIdst\fP is NULL a new BerValue will be allocated to hold the copy. The routine returns NULL upon error, otherwise it returns a pointer to the copy. If \fIdst\fP is NULL the caller should use .BR ber_bvfree () to deallocate the resulting BerValue, otherwise .BR ber_memfree () should be used to deallocate the \fIdst->bv_val\fP. (The .BR ber_bvdup () function is internally implemented as ber_dupbv(NULL, bv). .BR ber_bvdup () is provided only for compatibility with an expired draft of the LDAP C API; .BR ber_dupbv () is the preferred interface.) .LP .BR ber_bvstr () returns a BerValue containing the string pointed to by \fIstr\fP. .BR ber_bvstrdup () returns a BerValue containing a copy of the string pointed to by \fIstr\fP. .BR ber_str2bv () returns a BerValue containing the string pointed to by \fIstr\fP, whose length may be optionally specified in \fIlen\fP. If \fIdup\fP is non-zero, the BerValue will contain a copy of \fIstr\fP. If \fIlen\fP is zero, the number of bytes to copy will be determined by .BR strlen (3), otherwise \fIlen\fP bytes will be copied. If \fIbv\fP is non-NULL, the result will be stored in the given BerValue, otherwise a new BerValue will be allocated to store the result. NOTE: Both .BR ber_bvstr () and .BR ber_bvstrdup () are implemented as macros using .BR ber_str2bv () in this version of the library. .LP .B BerElement is an opaque structure used to maintain state information used in encoding and decoding. .BR ber_alloc_t () is used to create an empty BerElement structure. If .B LBER_USE_DER is specified for the .I options parameter then data lengths for data written to the BerElement will be encoded in the minimal number of octets required, otherwise they will always be written as four byte values. .BR ber_init () creates a BerElement structure that is initialized with a copy of the data in its .I bv parameter. .BR ber_init2 () initializes an existing BerElement .I ber using the data in the .I bv parameter. The data is referenced directly, not copied. The .I options parameter is the same as for .BR ber_alloc_t (). .BR ber_free () frees a BerElement pointed to by \fIber\fP. If \fIber\fP is NULL, the routine does nothing. If \fIfreebuf\fP is zero, the internal buffer is not freed. .SH SEE ALSO .BR lber-encode (3), .BR lber-decode (3), .BR lber-memory (3) .LP .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 189 stdin PK Ǔc\�4�� � man/man3/ldap_modify_s.3nu �[��� .lf 1 stdin .TH LDAP_MODIFY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_modify_ext, ldap_modify_ext_s \- Perform an LDAP modify operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_modify_ext( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, LDAPMod *\fImods[]\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB, int *\fImsgidp\fB ); .RE .LP .nf .ft B int ldap_modify_ext_s( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, LDAPMod *\fImods[]\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB ); .RE .LP .nf .ft B void ldap_mods_free( .RS .ft B LDAPMod **\fImods\fB, int \fIfreemods\fB ); .RE .SH DESCRIPTION The routine .B ldap_modify_ext_s() is used to perform an LDAP modify operation. \fIdn\fP is the DN of the entry to modify, and \fImods\fP is a null-terminated array of modifications to make to the entry. Each element of the \fImods\fP array is a pointer to an LDAPMod structure, which is defined below. .LP .nf typedef struct ldapmod { int mod_op; char *mod_type; union { char **modv_strvals; struct berval **modv_bvals; } mod_vals; struct ldapmod *mod_next; } LDAPMod; #define mod_values mod_vals.modv_strvals #define mod_bvalues mod_vals.modv_bvals .ft .fi .LP The \fImod_op\fP field is used to specify the type of modification to perform and should be one of LDAP_MOD_ADD, LDAP_MOD_DELETE, or LDAP_MOD_REPLACE. The \fImod_type\fP and \fImod_values\fP fields specify the attribute type to modify and a null-terminated array of values to add, delete, or replace respectively. The \fImod_next\fP field is used only by the LDAP server and may be ignored by the client. .LP If you need to specify a non-string value (e.g., to add a photo or audio attribute value), you should set \fImod_op\fP to the logical OR of the operation as above (e.g., LDAP_MOD_REPLACE) and the constant LDAP_MOD_BVALUES. In this case, \fImod_bvalues\fP should be used instead of \fImod_values\fP, and it should point to a null-terminated array of struct bervals, as defined in <lber.h>. .LP 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 attribute is to be deleted, the \fImod_values\fP field should be set to NULL. For LDAP_MOD_REPLACE modifications, the attribute will have the listed values after the modification, having been created if necessary. All modifications are performed in the order in which they are listed. .LP .B ldap_mods_free() can be used to free each element of a NULL-terminated array of mod structures. If \fIfreemods\fP is non-zero, the \fImods\fP pointer itself is freed as well. .LP .B ldap_modify_ext_s() returns a code indicating success or, in the case of failure, indicating the nature of the failure. See .BR ldap_error (3) for details .LP The .B ldap_modify_ext() operation works the same way as .BR ldap_modify_ext_s() , except that it is asynchronous. The integer that \fImsgidp\fP points to is set to the message id of the modify request. The result of the operation can be obtained by calling .BR ldap_result (3). .LP Both .B ldap_modify_ext() and .B ldap_modify_ext_s() allows server and client controls to be passed in via the sctrls and cctrls parameters, respectively. .SH DEPRECATED INTERFACES The .B ldap_modify() and .B ldap_modify_s() routines are deprecated in favor of the .B ldap_modify_ext() and .B ldap_modify_ext_s() routines, respectively. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 132 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 137 stdin PK Ǔc\��1ܽ � man/man3/ldap_control_create.3nu �[��� .lf 1 stdin .TH LDAP_CONTROLS 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_control_create, ldap_control_find, ldap_control_dup, ldap_controls_dup, ldap_control_free, ldap_controls_free \- LDAP control manipulation routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "int ldap_control_create(const char *" oid ", int " iscritical ", struct berval *" value ", int " dupval ", LDAPControl **" ctrlp ");" .LP .BI "LDAPControl *ldap_control_find( const char *" oid ", LDAPControl **" ctrls ", LDAPControl ***" nextctrlp ");" .LP .BI "LDAPControl *ldap_control_dup(LDAPControl *" ctrl ");" .LP .BI "LDAPControl **ldap_controls_dup(LDAPControl **" ctrls ");" .LP .BI "void ldap_control_free(LDAPControl *" ctrl ");" .LP .BI "void ldap_controls_free(LDAPControl **" ctrls ");" .SH DESCRIPTION These routines are used to manipulate structures used for LDAP controls. .BR ldap_control_create () creates a control with the specified .I OID using the contents of the .I value parameter for the control value, if any. The content of .I value is duplicated if .I dupval is non-zero. The .I iscritical parameter must be non-zero for a critical control. The created control is returned in the .I ctrlp parameter. The routine returns .B LDAP_SUCCESS on success or some other error code on failure. The content of .IR value , for supported control types, can be prepared using helpers provided by this implementation of libldap, usually in the form .BR "ldap_create_<control name>_control_value" (). Otherwise, it can be BER-encoded using the functionalities of liblber. .BR ldap_control_find () searches the NULL-terminated .I ctrls array for a control whose OID matches the .I oid parameter. The routine returns a pointer to the control if found, NULL otherwise. If the parameter .I nextctrlp is not NULL, on return it will point to the next control in the array, and can be passed to the .BR ldap_control_find () routine for subsequent calls, to find further occurrences of the same control type. The use of this function is discouraged; the recommended way of handling controls in responses consists in going through the array of controls, dealing with each of them in the returned order, since it could matter. .BR ldap_control_dup () duplicates an individual control structure, and .BR ldap_controls_dup () duplicates a NULL-terminated array of controls. .BR ldap_control_free () frees an individual control structure, and .BR ldap_controls_free () frees a NULL-terminated array of controls. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 85 stdin PK ȓc\���0 0 man/man3/ldap_memfree.3nu �[��� .lf 1 stdin .TH LDAP_MEMORY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_memfree, ldap_memvfree, ldap_memalloc, ldap_memcalloc, ldap_memrealloc, ldap_strdup \- LDAP memory allocation routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "void ldap_memfree(void *" p ");" .LP .BI "void ldap_memvfree(void **" v ");" .LP .BI "void *ldap_memalloc(ber_len_t " s ");" .LP .BI "void *ldap_memcalloc(ber_len_t " n ", ber_len_t " s ");" .LP .BI "void *ldap_memrealloc(void *" p ", ber_len_t " s ");" .LP .BI "char *ldap_strdup(LDAP_CONST char *" p ");" .SH DESCRIPTION These routines are used to allocate/deallocate memory used/returned by the LDAP library. .BR ldap_memalloc (), .BR ldap_memcalloc (), .BR ldap_memrealloc (), and .BR ldap_memfree () are used exactly like the standard .BR malloc (3), .BR calloc (3), .BR realloc (3), and .BR free (3) routines, respectively. The .BR ldap_memvfree () routine is used to free a dynamically allocated array of pointers to arbitrary dynamically allocated objects. The .BR ldap_strdup () routine is used exactly like the standard .BR strdup (3) routine. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 51 stdin PK ȓc\���0 0 man/man3/ldap_memcalloc.3nu �[��� .lf 1 stdin .TH LDAP_MEMORY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_memfree, ldap_memvfree, ldap_memalloc, ldap_memcalloc, ldap_memrealloc, ldap_strdup \- LDAP memory allocation routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "void ldap_memfree(void *" p ");" .LP .BI "void ldap_memvfree(void **" v ");" .LP .BI "void *ldap_memalloc(ber_len_t " s ");" .LP .BI "void *ldap_memcalloc(ber_len_t " n ", ber_len_t " s ");" .LP .BI "void *ldap_memrealloc(void *" p ", ber_len_t " s ");" .LP .BI "char *ldap_strdup(LDAP_CONST char *" p ");" .SH DESCRIPTION These routines are used to allocate/deallocate memory used/returned by the LDAP library. .BR ldap_memalloc (), .BR ldap_memcalloc (), .BR ldap_memrealloc (), and .BR ldap_memfree () are used exactly like the standard .BR malloc (3), .BR calloc (3), .BR realloc (3), and .BR free (3) routines, respectively. The .BR ldap_memvfree () routine is used to free a dynamically allocated array of pointers to arbitrary dynamically allocated objects. The .BR ldap_strdup () routine is used exactly like the standard .BR strdup (3) routine. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 51 stdin PK ɓc\� �q q man/man3/ldap_explode_dn.3nu �[��� .lf 1 stdin .TH LDAP_GET_DN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn \- LDAP DN handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ) .LP .ft B int ldap_str2dn( const char *str, LDAPDN *dn, unsigned flags ) .LP .ft B void ldap_dnfree( LDAPDN dn ) .LP .ft B int ldap_dn2str( LDAPDN dn, char **str, unsigned flags ) .LP .ft B char **ldap_explode_dn( const char *dn, int notypes ) .LP .ft B char **ldap_explode_rdn( const char *rdn, int notypes ) .LP .ft B char *ldap_dn2ufn( const char * dn ) .LP .ft B char *ldap_dn2dcedn( const char * dn ) .LP .ft B char *ldap_dcedn2dn( const char * dn ) .LP .ft B char *ldap_dn2ad_canonical( const char * dn ) .SH DESCRIPTION These routines allow LDAP entry names (Distinguished Names, or DNs) to be obtained, parsed, converted to a user-friendly form, and tested. A DN has the form described in RFC 4414 "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names". .LP The .B ldap_get_dn() routine takes an \fIentry\fP as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3) and returns a copy of the entry's DN. Space for the DN will be obtained dynamically and should be freed by the caller using .BR ldap_memfree (3). .LP .B ldap_str2dn() parses a string representation of a distinguished name contained in .B str into its components, which are stored in .B dn as .B ldap_ava structures, arranged in .B LDAPAVA, .B LDAPRDN, and .B LDAPDN terms. Space for .B dn will be obtained dynamically and should be freed by the caller using .BR ldap_dnfree (3). The .B LDAPDN is defined as: .nf .ft B typedef struct ldap_ava { struct berval la_attr; struct berval la_value; unsigned la_flags; } LDAPAVA; typedef LDAPAVA** LDAPRDN; typedef LDAPRDN* LDAPDN; .ft .fi The attribute types and the attribute values are not normalized. The .B la_flags can be either .B LDAP_AVA_STRING or .B LDAP_AVA_BINARY, the latter meaning that the value is BER/DER encoded and thus must be represented as, quoting from RFC 4514, " ... an octothorpe character ('#' ASCII 35) followed by the hexadecimal representation of each of the bytes of the BER encoding of the X.500 AttributeValue." The .B flags parameter to .B ldap_str2dn() can be .LP .nf LDAP_DN_FORMAT_LDAPV3 LDAP_DN_FORMAT_LDAPV2 LDAP_DN_FORMAT_DCE .fi which defines what DN syntax is expected (according to RFC 4514, RFC 1779 and DCE, respectively). The format can be \fIOR\fPed to the flags .LP .nf LDAP_DN_P_NO_SPACES LDAP_DN_P_NO_SPACE_AFTER_RDN ... LDAP_DN_PEDANTIC .fi The latter is a shortcut for all the previous limitations. .LP .B LDAP_DN_P_NO_SPACES does not allow extra spaces in the dn; the default is to silently eliminate spaces around AVA separators ('='), RDN component separators ('+' for LDAPv3/LDAPv2 or ',' for DCE) and RDN separators (',' LDAPv3/LDAPv2 or '/' for DCE). .LP .B LDAP_DN_P_NO_SPACE_AFTER_RDN does not allow a single space after RDN separators. .LP .B ldap_dn2str() performs the inverse operation, yielding in .B str a string representation of .B dn. It allows the same values for .B flags as .B ldap_str2dn(), plus .LP .nf LDAP_DN_FORMAT_UFN LDAP_DN_FORMAT_AD_CANONICAL .fi for user-friendly naming (RFC 1781) and AD canonical. .LP The following routines are viewed as deprecated in favor of .B ldap_str2dn() and .BR ldap_dn2str(). They are provided to support legacy applications. .LP The .B ldap_explode_dn() routine takes a DN as returned by .B ldap_get_dn() and breaks it up into its component parts. Each part is known as a Relative Distinguished Name, or RDN. .B ldap_explode_dn() returns a NULL-terminated array, each component of which contains an RDN from the DN. The \fInotypes\fP parameter is used to request that only the RDN values be returned, not their types. For example, the DN "cn=Bob, c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob", "US", NULL }, depending on whether notypes was 0 or 1, respectively. Assertion values in RDN strings may included escaped characters. The result can be freed by calling .BR ldap_value_free (3). .LP Similarly, the .B ldap_explode_rdn() routine takes an RDN as returned by .B ldap_explode_dn(dn,0) and breaks it up into its "type=value" component parts (or just "value", if the \fInotypes\fP parameter is set). Note the value is not unescaped. The result can be freed by calling .BR ldap_value_free (3). .LP .B ldap_dn2ufn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a more user-friendly form, stripping off all type names. See "Using the Directory to Achieve User Friendly Naming" (RFC 1781) for more details on the UFN format. Due to the ambiguous nature of the format, it is generally only used for display purposes. The space for the UFN returned is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .LP .B ldap_dn2dcedn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a DCE-style DN, e.g. a string with most-significant to least significant rdns separated by slashes ('/'); rdn components are separated by commas (','). Only printable chars (e.g. LDAPv2 printable string) are allowed, at least in this implementation. .B ldap_dcedn2dn() performs the opposite operation. .B ldap_dn2ad_canonical() turns a DN into a AD canonical name, which is basically a DCE dn with attribute types omitted. The trailing domain, if present, is turned in a DNS-like domain. The space for the returned value is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .SH ERRORS If an error occurs in .BR ldap_get_dn() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .BR ldap_explode_dn() , .BR ldap_explode_rdn() , .B ldap_dn2ufn(), .B ldap_dn2dcedn(), .B ldap_dcedn2dn(), and .B ldap_dn2ad_canonical() will return NULL with .BR errno (3) set appropriately in case of trouble. .SH NOTES These routines dynamically allocate memory that the caller must free. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_first_entry (3), .BR ldap_memfree (3), .BR ldap_value_free (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 247 stdin PK ɓc\�շY� � man/man3/ber_bvecadd.3nu �[��� .lf 1 stdin .TH LBER_TYPES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_int_t, ber_uint_t, ber_len_t, ber_slen_t, ber_tag_t, struct berval, BerValue, BerVarray, BerElement, ber_bvfree, ber_bvecfree, ber_bvecadd, ber_bvarray_free, ber_bvarray_add, ber_bvdup, ber_dupbv, ber_bvstr, ber_bvstrdup, ber_str2bv, ber_alloc_t, ber_init, ber_init2, ber_free \- OpenLDAP LBER types and allocation functions .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .nf .ft B typedef impl_tag_t ber_tag_t; typedef impl_int_t ber_int_t; typedef impl_uint_t ber_uint_t; typedef impl_len_t ber_len_t; typedef impl_slen_t ber_slen_t; typedef struct berval { ber_len_t bv_len; char *bv_val; } BerValue, *BerVarray; typedef struct berelement BerElement; .ft .fi .LP .BI "void ber_bvfree(struct berval *" bv ");" .LP .BI "void ber_bvecfree(struct berval **" bvec ");" .LP .BI "void ber_bvecadd(struct berval ***" bvec ", struct berval *" bv ");" .LP .BI "void ber_bvarray_free(struct berval *" bvarray ");" .LP .BI "void ber_bvarray_add(BerVarray *" bvarray ", BerValue *" bv ");" .LP .BI "struct berval *ber_bvdup(const struct berval *" bv ");" .LP .BI "struct berval *ber_dupbv(const struct berval *" dst ", struct berval *" src ");" .LP .BI "struct berval *ber_bvstr(const char *" str ");" .LP .BI "struct berval *ber_bvstrdup(const char *" str ");" .LP .BI "struct berval *ber_str2bv(const char *" str ", ber_len_t " len ", int " dup ", struct berval *" bv ");" .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "BerElement *ber_init(struct berval *" bv ");" .LP .BI "void ber_init2(BerElement *" ber ", struct berval *" bv ", int " options ");" .LP .BI "void ber_free(BerElement *" ber ", int " freebuf ");" .SH DESCRIPTION .LP The following are the basic types and structures defined for use with the Lightweight BER library. .LP .B ber_int_t is a signed integer of at least 32 bits. It is commonly equivalent to .BR int . .B ber_uint_t is the unsigned variant of .BR ber_int_t . .LP .B ber_len_t is an unsigned integer of at least 32 bits used to represent a length. It is commonly equivalent to a .BR size_t . .B ber_slen_t is the signed variant to .BR ber_len_t . .LP .B ber_tag_t is an unsigned integer of at least 32 bits used to represent a BER tag. It is commonly equivalent to a .BR unsigned\ long . .LP The actual definitions of the integral impl_TYPE_t types are platform specific. .LP .BR BerValue , commonly used as .BR struct\ berval , is used to hold an arbitrary sequence of octets. .B bv_val points to .B bv_len octets. .B bv_val is not necessarily terminated by a NULL (zero) octet. .BR ber_bvfree () frees a BerValue, pointed to by \fIbv\fP, returned from this API. If \fIbv\fP is NULL, the routine does nothing. .LP .BR ber_bvecfree () frees an array of BerValues (and the array), pointed to by \fIbvec\fP, returned from this API. If \fIbvec\fP is NULL, the routine does nothing. .BR ber_bvecadd () appends the \fIbv\fP pointer to the \fIbvec\fP array. Space for the array is allocated as needed. The end of the array is marked by a NULL pointer. .LP .BR ber_bvarray_free () frees an array of BerValues (and the array), pointed to by \fIbvarray\fP, returned from this API. If \fIbvarray\fP is NULL, the routine does nothing. .BR ber_bvarray_add () appends the contents of the BerValue pointed to by \fIbv\fP to the \fIbvarray\fP array. Space for the new element is allocated as needed. The end of the array is marked by a BerValue with a NULL bv_val field. .LP .BR ber_bvdup () returns a copy of a BerValue. The routine returns NULL upon error (e.g. out of memory). The caller should use .BR ber_bvfree () to deallocate the resulting BerValue. .BR ber_dupbv () copies a BerValue from \fIsrc\fP to \fIdst\fP. If \fIdst\fP is NULL a new BerValue will be allocated to hold the copy. The routine returns NULL upon error, otherwise it returns a pointer to the copy. If \fIdst\fP is NULL the caller should use .BR ber_bvfree () to deallocate the resulting BerValue, otherwise .BR ber_memfree () should be used to deallocate the \fIdst->bv_val\fP. (The .BR ber_bvdup () function is internally implemented as ber_dupbv(NULL, bv). .BR ber_bvdup () is provided only for compatibility with an expired draft of the LDAP C API; .BR ber_dupbv () is the preferred interface.) .LP .BR ber_bvstr () returns a BerValue containing the string pointed to by \fIstr\fP. .BR ber_bvstrdup () returns a BerValue containing a copy of the string pointed to by \fIstr\fP. .BR ber_str2bv () returns a BerValue containing the string pointed to by \fIstr\fP, whose length may be optionally specified in \fIlen\fP. If \fIdup\fP is non-zero, the BerValue will contain a copy of \fIstr\fP. If \fIlen\fP is zero, the number of bytes to copy will be determined by .BR strlen (3), otherwise \fIlen\fP bytes will be copied. If \fIbv\fP is non-NULL, the result will be stored in the given BerValue, otherwise a new BerValue will be allocated to store the result. NOTE: Both .BR ber_bvstr () and .BR ber_bvstrdup () are implemented as macros using .BR ber_str2bv () in this version of the library. .LP .B BerElement is an opaque structure used to maintain state information used in encoding and decoding. .BR ber_alloc_t () is used to create an empty BerElement structure. If .B LBER_USE_DER is specified for the .I options parameter then data lengths for data written to the BerElement will be encoded in the minimal number of octets required, otherwise they will always be written as four byte values. .BR ber_init () creates a BerElement structure that is initialized with a copy of the data in its .I bv parameter. .BR ber_init2 () initializes an existing BerElement .I ber using the data in the .I bv parameter. The data is referenced directly, not copied. The .I options parameter is the same as for .BR ber_alloc_t (). .BR ber_free () frees a BerElement pointed to by \fIber\fP. If \fIber\fP is NULL, the routine does nothing. If \fIfreebuf\fP is zero, the internal buffer is not freed. .SH SEE ALSO .BR lber-encode (3), .BR lber-decode (3), .BR lber-memory (3) .LP .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 189 stdin PK ʓc\}�q � � man/man3/ldap_add.3nu �[��� .lf 1 stdin .TH LDAP_ADD 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_add_ext, ldap_add_ext_s \- Perform an LDAP add operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .ft B #include <ldap.h> .LP .ft B .nf int ldap_add_ext( .RS .ft B LDAP *\fIld, const char *\fIdn\fB, LDAPMod **\fIattrs\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB, int *\fImsgidp\fB ); .RE .LP .ft B .nf int ldap_add_ext_s( .RS LDAP *\fIld\fB, const char *\fIdn\fB, LDAPMod **\fIattrs\fB, LDAPControl *\fIsctrls\fB, LDAPControl *\fIcctrls\fB ); .RE .fi .SH DESCRIPTION The .B ldap_add_ext_s() routine is used to perform an LDAP add operation. It takes \fIdn\fP, the DN of the entry to add, and \fIattrs\fP, a null-terminated array of the entry's attributes. The LDAPMod structure is used to represent attributes, with the \fImod_type\fP and \fImod_values\fP fields being used as described under .BR ldap_modify_ext (3), and the \fIldap_op\fP field being used only if you need to specify the LDAP_MOD_BVALUES option. Otherwise, it should be set to zero. .LP Note that all entries except that specified by the last component in the given DN must already exist. .B ldap_add_ext_s() returns an code indicating success or, in the case of failure, indicating the nature of failure of the operation. See .BR ldap_error (3) for more details. .LP The .B ldap_add_ext() routine works just like .BR ldap_add_ext_s() , but it is asynchronous. It returns the message id of the request it initiated. The result of this operation can be obtained by calling .BR ldap_result (3). .SH DEPRECATED INTERFACES The .BR ldap_add () and .BR ldap_add_s () routines are deprecated in favor of the .BR ldap_add_ext () and .BR ldap_add_ext_s () routines, respectively. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 76 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_modify (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 82 stdin PK ʓc\� �q q man/man3/ldap_dn2dcedn.3nu �[��� .lf 1 stdin .TH LDAP_GET_DN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn \- LDAP DN handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ) .LP .ft B int ldap_str2dn( const char *str, LDAPDN *dn, unsigned flags ) .LP .ft B void ldap_dnfree( LDAPDN dn ) .LP .ft B int ldap_dn2str( LDAPDN dn, char **str, unsigned flags ) .LP .ft B char **ldap_explode_dn( const char *dn, int notypes ) .LP .ft B char **ldap_explode_rdn( const char *rdn, int notypes ) .LP .ft B char *ldap_dn2ufn( const char * dn ) .LP .ft B char *ldap_dn2dcedn( const char * dn ) .LP .ft B char *ldap_dcedn2dn( const char * dn ) .LP .ft B char *ldap_dn2ad_canonical( const char * dn ) .SH DESCRIPTION These routines allow LDAP entry names (Distinguished Names, or DNs) to be obtained, parsed, converted to a user-friendly form, and tested. A DN has the form described in RFC 4414 "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names". .LP The .B ldap_get_dn() routine takes an \fIentry\fP as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3) and returns a copy of the entry's DN. Space for the DN will be obtained dynamically and should be freed by the caller using .BR ldap_memfree (3). .LP .B ldap_str2dn() parses a string representation of a distinguished name contained in .B str into its components, which are stored in .B dn as .B ldap_ava structures, arranged in .B LDAPAVA, .B LDAPRDN, and .B LDAPDN terms. Space for .B dn will be obtained dynamically and should be freed by the caller using .BR ldap_dnfree (3). The .B LDAPDN is defined as: .nf .ft B typedef struct ldap_ava { struct berval la_attr; struct berval la_value; unsigned la_flags; } LDAPAVA; typedef LDAPAVA** LDAPRDN; typedef LDAPRDN* LDAPDN; .ft .fi The attribute types and the attribute values are not normalized. The .B la_flags can be either .B LDAP_AVA_STRING or .B LDAP_AVA_BINARY, the latter meaning that the value is BER/DER encoded and thus must be represented as, quoting from RFC 4514, " ... an octothorpe character ('#' ASCII 35) followed by the hexadecimal representation of each of the bytes of the BER encoding of the X.500 AttributeValue." The .B flags parameter to .B ldap_str2dn() can be .LP .nf LDAP_DN_FORMAT_LDAPV3 LDAP_DN_FORMAT_LDAPV2 LDAP_DN_FORMAT_DCE .fi which defines what DN syntax is expected (according to RFC 4514, RFC 1779 and DCE, respectively). The format can be \fIOR\fPed to the flags .LP .nf LDAP_DN_P_NO_SPACES LDAP_DN_P_NO_SPACE_AFTER_RDN ... LDAP_DN_PEDANTIC .fi The latter is a shortcut for all the previous limitations. .LP .B LDAP_DN_P_NO_SPACES does not allow extra spaces in the dn; the default is to silently eliminate spaces around AVA separators ('='), RDN component separators ('+' for LDAPv3/LDAPv2 or ',' for DCE) and RDN separators (',' LDAPv3/LDAPv2 or '/' for DCE). .LP .B LDAP_DN_P_NO_SPACE_AFTER_RDN does not allow a single space after RDN separators. .LP .B ldap_dn2str() performs the inverse operation, yielding in .B str a string representation of .B dn. It allows the same values for .B flags as .B ldap_str2dn(), plus .LP .nf LDAP_DN_FORMAT_UFN LDAP_DN_FORMAT_AD_CANONICAL .fi for user-friendly naming (RFC 1781) and AD canonical. .LP The following routines are viewed as deprecated in favor of .B ldap_str2dn() and .BR ldap_dn2str(). They are provided to support legacy applications. .LP The .B ldap_explode_dn() routine takes a DN as returned by .B ldap_get_dn() and breaks it up into its component parts. Each part is known as a Relative Distinguished Name, or RDN. .B ldap_explode_dn() returns a NULL-terminated array, each component of which contains an RDN from the DN. The \fInotypes\fP parameter is used to request that only the RDN values be returned, not their types. For example, the DN "cn=Bob, c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob", "US", NULL }, depending on whether notypes was 0 or 1, respectively. Assertion values in RDN strings may included escaped characters. The result can be freed by calling .BR ldap_value_free (3). .LP Similarly, the .B ldap_explode_rdn() routine takes an RDN as returned by .B ldap_explode_dn(dn,0) and breaks it up into its "type=value" component parts (or just "value", if the \fInotypes\fP parameter is set). Note the value is not unescaped. The result can be freed by calling .BR ldap_value_free (3). .LP .B ldap_dn2ufn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a more user-friendly form, stripping off all type names. See "Using the Directory to Achieve User Friendly Naming" (RFC 1781) for more details on the UFN format. Due to the ambiguous nature of the format, it is generally only used for display purposes. The space for the UFN returned is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .LP .B ldap_dn2dcedn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a DCE-style DN, e.g. a string with most-significant to least significant rdns separated by slashes ('/'); rdn components are separated by commas (','). Only printable chars (e.g. LDAPv2 printable string) are allowed, at least in this implementation. .B ldap_dcedn2dn() performs the opposite operation. .B ldap_dn2ad_canonical() turns a DN into a AD canonical name, which is basically a DCE dn with attribute types omitted. The trailing domain, if present, is turned in a DNS-like domain. The space for the returned value is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .SH ERRORS If an error occurs in .BR ldap_get_dn() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .BR ldap_explode_dn() , .BR ldap_explode_rdn() , .B ldap_dn2ufn(), .B ldap_dn2dcedn(), .B ldap_dcedn2dn(), and .B ldap_dn2ad_canonical() will return NULL with .BR errno (3) set appropriately in case of trouble. .SH NOTES These routines dynamically allocate memory that the caller must free. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_first_entry (3), .BR ldap_memfree (3), .BR ldap_value_free (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 247 stdin PK ˓c\���0 0 man/man3/ldap_memrealloc.3nu �[��� .lf 1 stdin .TH LDAP_MEMORY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_memfree, ldap_memvfree, ldap_memalloc, ldap_memcalloc, ldap_memrealloc, ldap_strdup \- LDAP memory allocation routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "void ldap_memfree(void *" p ");" .LP .BI "void ldap_memvfree(void **" v ");" .LP .BI "void *ldap_memalloc(ber_len_t " s ");" .LP .BI "void *ldap_memcalloc(ber_len_t " n ", ber_len_t " s ");" .LP .BI "void *ldap_memrealloc(void *" p ", ber_len_t " s ");" .LP .BI "char *ldap_strdup(LDAP_CONST char *" p ");" .SH DESCRIPTION These routines are used to allocate/deallocate memory used/returned by the LDAP library. .BR ldap_memalloc (), .BR ldap_memcalloc (), .BR ldap_memrealloc (), and .BR ldap_memfree () are used exactly like the standard .BR malloc (3), .BR calloc (3), .BR realloc (3), and .BR free (3) routines, respectively. The .BR ldap_memvfree () routine is used to free a dynamically allocated array of pointers to arbitrary dynamically allocated objects. The .BR ldap_strdup () routine is used exactly like the standard .BR strdup (3) routine. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 51 stdin PK ˓c\�5^#v1 v1 man/man3/ber_get_stringa.3nu �[��� .lf 1 stdin .TH LBER_DECODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");" .LP .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");" .LP .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");" .LP .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");" .LP .BI "ber_tag_t ber_get_null(BerElement *" ber ");" .LP .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");" .LP .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");" .LP .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");" .LP .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the decoding routines in the lber library. See .BR lber-encode (3) for details on the corresponding encoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_get_next () to get the next BER element and .BR ber_scanf () to do the actual decoding. In some cases, .BR ber_peek_tag () may also need to be called in normal usage. The other routines are provided for those applications that need more control than .BR ber_scanf () provides. In general, these routines return the tag of the element decoded, or LBER_ERROR if an error occurred. .LP The .BR ber_get_next () routine is used to read the next BER element from the given Sockbuf, \fIsb\fP. It strips off and returns the leading tag, strips off and returns the length of the entire element in \fIlen\fP, and sets up \fIber\fP for subsequent calls to .BR ber_scanf () et al to decode the element. See .BR lber-sockbuf (3) for details of the Sockbuf implementation of the \fIsb\fP parameter. .LP The .BR ber_scanf () routine is used to decode a BER element in much the same way that .BR scanf (3) works. It reads from \fIber\fP, a pointer to a BerElement such as returned by .BR ber_get_next (), interprets the bytes according to the format string \fIfmt\fP, and stores the results in its additional arguments. 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. .RS .LP .TP 3 .B a Octet string. A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter. The caller should free the returned string using .BR ber_memfree (). .TP .B A Octet string. A variant of "\fBa\fP". A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter, unless a zero-length string would result; in that case, the arg is set to NULL. The caller should free the returned string using .BR ber_memfree (). .TP .B s Octet string. A char * buffer should be supplied, followed by a pointer to a ber_len_t initialized to the size of the buffer. Upon return, the null-terminated octet string is put into the buffer, and the ber_len_t is set to the actual size of the octet string. .TP .B O Octet string. A struct ber_val ** should be supplied, which upon return points to a dynamically allocated struct berval containing the octet string and its length. The caller should free the returned structure using .BR ber_bvfree (). .TP .B o Octet string. A struct ber_val * should be supplied, which upon return contains the dynamically allocated octet string and its length. The caller should free the returned octet string using .BR ber_memfree (). .TP .B m Octet string. A struct ber_val * should be supplied, which upon return contains the octet string and its length. The string resides in memory assigned to the BerElement, and must not be freed by the caller. .TP .B b Boolean. A pointer to a ber_int_t should be supplied. .TP .B e Enumeration. A pointer to a ber_int_t should be supplied. .TP .B i Integer. A pointer to a ber_int_t should be supplied. .TP .B B Bitstring. A char ** should be supplied which will point to the dynamically allocated bits, followed by a ber_len_t *, which will point to the length (in bits) of the bitstring returned. .TP .B n Null. No parameter is required. The element is simply skipped if it is recognized. .TP .B v Sequence of octet strings. A char *** should be supplied, which upon return points to a dynamically allocated null-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty. The caller should free the returned array and octet strings using .BR ber_memvfree (). .TP .B V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon return points to a dynamically allocated null-terminated array of struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvecfree (). .TP .B W Sequence of octet strings with lengths. A BerVarray * should be supplied, which upon return points to a dynamically allocated array of struct berval's containing the octet strings and their lengths. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvarray_free (). .TP .B M Sequence of octet strings with lengths. This is a generalized form of the previous three formats. A void ** (ptr) should be supplied, followed by a ber_len_t * (len) and a ber_len_t (off). Upon return (ptr) will point to a dynamically allocated array whose elements are all of size (*len). A struct berval will be filled starting at offset (off) in each element. The strings in each struct berval reside in memory assigned to the BerElement and must not be freed by the caller. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The number of elements in the array is also stored in (*len) on return. The caller should free the returned array using .BR ber_memfree (). .TP .B l Length of the next element. A pointer to a ber_len_t should be supplied. .TP .B t Tag of the next element. A pointer to a ber_tag_t should be supplied. .TP .B T Skip element and return its tag. A pointer to a ber_tag_t should be supplied. .TP .B x Skip element. The next element is skipped. .TP .B { Begin sequence. No parameter is required. The initial sequence tag and length are skipped. .TP .B } End sequence. No parameter is required and no action is taken. .TP .B [ Begin set. No parameter is required. The initial set tag and length are skipped. .TP .B ] End set. No parameter is required and no action is taken. .RE .LP The .BR ber_get_int () routine tries to interpret the next element as an integer, returning the result in \fInum\fP. The tag of whatever it finds is returned on success, LBER_ERROR (\-1) on failure. .LP The .BR ber_get_stringb () routine is used to read an octet string into a preallocated buffer. The \fIlen\fP parameter should be initialized to the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte. .LP The .BR ber_get_stringa () routine is used to dynamically allocate space into which an octet string is read. The caller should free the returned string using .BR ber_memfree(). .LP The .BR ber_get_stringal () routine is used to dynamically allocate space into which an octet string and its length are read. It takes a struct berval **, and returns the result in this parameter. The caller should free the returned structure using .BR ber_bvfree(). .LP The .BR ber_get_stringbv () routine is used to read an octet string and its length into the provided struct berval *. If the \fIalloc\fP parameter is zero, the string will reside in memory assigned to the BerElement, and must not be freed by the caller. If the \fIalloc\fP parameter is non-zero, the string will be copied into dynamically allocated space which should be returned using .BR ber_memfree (). .LP The .BR ber_get_null () routine is used to read a NULL element. It returns the tag of the element it skips over. .LP The .BR ber_get_boolean () routine is used to read a boolean value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_enum () routine is used to read a enumeration value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_bitstringa () routine is used to read a bitstring value. It takes a char ** which will hold the dynamically allocated bits, followed by an ber_len_t *, which will point to the length (in bits) of the bitstring returned. The caller should free the returned string using .BR ber_memfree (). .LP The .BR ber_first_element () routine is used to return the tag and length of the first element in a set or sequence. It also returns in \fIcookie\fP a magic cookie parameter that should be passed to subsequent calls to ber_next_element(), which returns similar information. .SH EXAMPLES Assume the variable \fIber\fP contains a lightweight BER encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP The element can be decoded using .BR ber_scanf () as follows. .LP .nf ber_int_t scope, deref, size, time, attrsonly; char *dn, **attrs; ber_tag_t tag; tag = ber_scanf( ber, "{aeeiib{v}}", &dn, &scope, &deref, &size, &time, &attrsonly, &attrs ); if( tag == LBER_ERROR ) { /* error */ } else { /* success */ } ber_memfree( dn ); ber_memvfree( attrs ); .fi .SH ERRORS If an error occurs during decoding, generally these routines return LBER_ERROR ((ber_tag_t)\-1). .LP .SH NOTES .LP The return values for all of these functions are declared in the .B <lber.h> header file. Some routines may dynamically allocate memory which must be freed by the caller using supplied deallocation routines. .SH SEE ALSO .BR lber-encode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 358 stdin PK ̓c\��n� � man/man3/ldap_init_fd.3nu �[��� .lf 1 stdin .TH LDAP_OPEN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_init, ldap_initialize, ldap_open \- Initialize the LDAP library and open a connection to an LDAP server .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B LDAP *ldap_open(host, port) .ft char *host; int port; .LP .ft B LDAP *ldap_init(host, port) .ft char *host; int port; .LP .ft B int ldap_initialize(ldp, uri) .ft LDAP **ldp; char *uri; .LP .ft B int ldap_set_urllist_proc(ld, proc, params) .ft LDAP *ld; LDAP_URLLIST_PROC *proc; void *params; .LP .ft B int (LDAP_URLLIST_PROC)(ld, urllist, url, params); .ft LDAP *ld; LDAPURLDesc **urllist; LDAPURLDesc **url; void *params; .LP .ft B #include <ldap_pvt.h> .LP .ft B int ldap_init_fd(fd, proto, uri, ldp) .ft ber_socket_t fd; int proto; char *uri; LDAP **ldp; .SH DESCRIPTION .LP .B ldap_open() opens a connection to an LDAP server and allocates an LDAP structure which is used to identify the connection and to maintain per-connection information. .B ldap_init() allocates an LDAP structure but does not open an initial connection. .B ldap_initialize() allocates an LDAP structure but does not open an initial connection. .B ldap_init_fd() allocates an LDAP structure using an existing connection on the provided socket. One of these routines must be called before any operations are attempted. .LP .B ldap_open() takes \fIhost\fP, the hostname on which the LDAP server is running, and \fIport\fP, the port number to which to connect. If the default IANA-assigned port of 389 is desired, LDAP_PORT should be specified for \fIport\fP. The \fIhost\fP parameter may contain a blank-separated list of hosts to try to connect to, and each host may optionally by of the form \fIhost:port\fP. If present, the \fI:port\fP overrides the \fIport\fP parameter to .BR ldap_open() . Upon successfully making a connection to an LDAP server, .B ldap_open() returns a pointer to an opaque LDAP structure, which should be passed to subsequent calls to .BR ldap_bind() , .BR ldap_search() , etc. Certain fields in the LDAP structure can be set to indicate size limit, time limit, and how aliases are handled during operations; read and write access to those fields must occur by calling .BR ldap_get_option (3) and .BR ldap_set_option (3) respectively, whenever possible. .LP .B ldap_init() acts just like .BR ldap_open() , but does not open a connection to the LDAP server. The actual connection open will occur when the first operation is attempted. .LP .B ldap_initialize() acts like .BR ldap_init() , but it returns an integer indicating either success or the failure reason, and it allows to specify details for the connection in the schema portion of the URI. The .I uri parameter may be a comma- or whitespace-separated list of URIs containing only the .IR schema , the .IR host , and the .I port fields. Apart from .BR ldap , other (non-standard) recognized values of the .I schema field are .B ldaps (LDAP over TLS), .B ldapi (LDAP over IPC), and .B cldap (connectionless LDAP). If other fields are present, the behavior is undefined. .LP At this time, .B ldap_open() and .B ldap_init() are deprecated in favor of .BR ldap_initialize() , essentially because the latter allows to specify a schema in the URI and it explicitly returns an error code. .LP .B ldap_init_fd() allows an LDAP structure to be initialized using an already-opened connection. The .I proto parameter should be one of LDAP_PROTO_TCP, LDAP_PROTO_UDP, or LDAP_PROTO_IPC for a connection using TCP, UDP, or IPC, respectively. The value LDAP_PROTO_EXT may also be specified if user-supplied sockbuf handlers are going to be used. Note that support for UDP is not implemented unless libldap was built with LDAP_CONNECTIONLESS defined. The .I uri parameter may optionally be provided for informational purposes. .LP .B ldap_set_urllist_proc() allows to set a function .I proc of type .I LDAP_URLLIST_PROC that is called when a successful connection can be established. This function receives the list of URIs parsed from the .I uri string originally passed to .BR ldap_initialize() , and the one that successfully connected. The function may manipulate the URI list; the typical use consists in moving the successful URI to the head of the list, so that subsequent attempts to connect to one of the URIs using the same LDAP handle will try it first. If .I ld is null, .I proc is set as a global parameter that is inherited by all handlers within the process that are created after the call to .BR ldap_set_urllist_proc() . By default, no .I LDAP_URLLIST_PROC is set. In a multithreaded environment, .B ldap_set_urllist_proc() must be called before any concurrent operation using the LDAP handle is started. Note: the first call into the LDAP library also initializes the global options for the library. As such the first call should be single-threaded or otherwise protected to insure that only one call is active. It is recommended that .BR ldap_get_option () or .BR ldap_set_option () be used in the program's main thread before any additional threads are created. See .BR ldap_get_option (3). .SH ERRORS If an error occurs, .B ldap_open() and .B ldap_init() will return NULL and .I errno should be set appropriately. .B ldap_initialize() and .B ldap_init_fd() will directly return the LDAP code associated to the error (or .I LDAP_SUCCESS in case of success); .I errno should be set as well whenever appropriate. .B ldap_set_urllist_proc() returns LDAP_OPT_ERROR on error, and LDAP_OPT_SUCCESS on success. .SH SEE ALSO .BR ldap (3), .BR ldap_bind (3), .BR ldap_get_option (3), .BR ldap_set_option (3), .BR lber-sockbuf (3), .BR errno (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 226 stdin PK ̓c\�5^#v1 v1 man/man3/ber_get_next.3nu �[��� .lf 1 stdin .TH LBER_DECODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");" .LP .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");" .LP .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");" .LP .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");" .LP .BI "ber_tag_t ber_get_null(BerElement *" ber ");" .LP .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");" .LP .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");" .LP .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");" .LP .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the decoding routines in the lber library. See .BR lber-encode (3) for details on the corresponding encoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_get_next () to get the next BER element and .BR ber_scanf () to do the actual decoding. In some cases, .BR ber_peek_tag () may also need to be called in normal usage. The other routines are provided for those applications that need more control than .BR ber_scanf () provides. In general, these routines return the tag of the element decoded, or LBER_ERROR if an error occurred. .LP The .BR ber_get_next () routine is used to read the next BER element from the given Sockbuf, \fIsb\fP. It strips off and returns the leading tag, strips off and returns the length of the entire element in \fIlen\fP, and sets up \fIber\fP for subsequent calls to .BR ber_scanf () et al to decode the element. See .BR lber-sockbuf (3) for details of the Sockbuf implementation of the \fIsb\fP parameter. .LP The .BR ber_scanf () routine is used to decode a BER element in much the same way that .BR scanf (3) works. It reads from \fIber\fP, a pointer to a BerElement such as returned by .BR ber_get_next (), interprets the bytes according to the format string \fIfmt\fP, and stores the results in its additional arguments. 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. .RS .LP .TP 3 .B a Octet string. A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter. The caller should free the returned string using .BR ber_memfree (). .TP .B A Octet string. A variant of "\fBa\fP". A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter, unless a zero-length string would result; in that case, the arg is set to NULL. The caller should free the returned string using .BR ber_memfree (). .TP .B s Octet string. A char * buffer should be supplied, followed by a pointer to a ber_len_t initialized to the size of the buffer. Upon return, the null-terminated octet string is put into the buffer, and the ber_len_t is set to the actual size of the octet string. .TP .B O Octet string. A struct ber_val ** should be supplied, which upon return points to a dynamically allocated struct berval containing the octet string and its length. The caller should free the returned structure using .BR ber_bvfree (). .TP .B o Octet string. A struct ber_val * should be supplied, which upon return contains the dynamically allocated octet string and its length. The caller should free the returned octet string using .BR ber_memfree (). .TP .B m Octet string. A struct ber_val * should be supplied, which upon return contains the octet string and its length. The string resides in memory assigned to the BerElement, and must not be freed by the caller. .TP .B b Boolean. A pointer to a ber_int_t should be supplied. .TP .B e Enumeration. A pointer to a ber_int_t should be supplied. .TP .B i Integer. A pointer to a ber_int_t should be supplied. .TP .B B Bitstring. A char ** should be supplied which will point to the dynamically allocated bits, followed by a ber_len_t *, which will point to the length (in bits) of the bitstring returned. .TP .B n Null. No parameter is required. The element is simply skipped if it is recognized. .TP .B v Sequence of octet strings. A char *** should be supplied, which upon return points to a dynamically allocated null-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty. The caller should free the returned array and octet strings using .BR ber_memvfree (). .TP .B V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon return points to a dynamically allocated null-terminated array of struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvecfree (). .TP .B W Sequence of octet strings with lengths. A BerVarray * should be supplied, which upon return points to a dynamically allocated array of struct berval's containing the octet strings and their lengths. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvarray_free (). .TP .B M Sequence of octet strings with lengths. This is a generalized form of the previous three formats. A void ** (ptr) should be supplied, followed by a ber_len_t * (len) and a ber_len_t (off). Upon return (ptr) will point to a dynamically allocated array whose elements are all of size (*len). A struct berval will be filled starting at offset (off) in each element. The strings in each struct berval reside in memory assigned to the BerElement and must not be freed by the caller. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The number of elements in the array is also stored in (*len) on return. The caller should free the returned array using .BR ber_memfree (). .TP .B l Length of the next element. A pointer to a ber_len_t should be supplied. .TP .B t Tag of the next element. A pointer to a ber_tag_t should be supplied. .TP .B T Skip element and return its tag. A pointer to a ber_tag_t should be supplied. .TP .B x Skip element. The next element is skipped. .TP .B { Begin sequence. No parameter is required. The initial sequence tag and length are skipped. .TP .B } End sequence. No parameter is required and no action is taken. .TP .B [ Begin set. No parameter is required. The initial set tag and length are skipped. .TP .B ] End set. No parameter is required and no action is taken. .RE .LP The .BR ber_get_int () routine tries to interpret the next element as an integer, returning the result in \fInum\fP. The tag of whatever it finds is returned on success, LBER_ERROR (\-1) on failure. .LP The .BR ber_get_stringb () routine is used to read an octet string into a preallocated buffer. The \fIlen\fP parameter should be initialized to the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte. .LP The .BR ber_get_stringa () routine is used to dynamically allocate space into which an octet string is read. The caller should free the returned string using .BR ber_memfree(). .LP The .BR ber_get_stringal () routine is used to dynamically allocate space into which an octet string and its length are read. It takes a struct berval **, and returns the result in this parameter. The caller should free the returned structure using .BR ber_bvfree(). .LP The .BR ber_get_stringbv () routine is used to read an octet string and its length into the provided struct berval *. If the \fIalloc\fP parameter is zero, the string will reside in memory assigned to the BerElement, and must not be freed by the caller. If the \fIalloc\fP parameter is non-zero, the string will be copied into dynamically allocated space which should be returned using .BR ber_memfree (). .LP The .BR ber_get_null () routine is used to read a NULL element. It returns the tag of the element it skips over. .LP The .BR ber_get_boolean () routine is used to read a boolean value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_enum () routine is used to read a enumeration value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_bitstringa () routine is used to read a bitstring value. It takes a char ** which will hold the dynamically allocated bits, followed by an ber_len_t *, which will point to the length (in bits) of the bitstring returned. The caller should free the returned string using .BR ber_memfree (). .LP The .BR ber_first_element () routine is used to return the tag and length of the first element in a set or sequence. It also returns in \fIcookie\fP a magic cookie parameter that should be passed to subsequent calls to ber_next_element(), which returns similar information. .SH EXAMPLES Assume the variable \fIber\fP contains a lightweight BER encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP The element can be decoded using .BR ber_scanf () as follows. .LP .nf ber_int_t scope, deref, size, time, attrsonly; char *dn, **attrs; ber_tag_t tag; tag = ber_scanf( ber, "{aeeiib{v}}", &dn, &scope, &deref, &size, &time, &attrsonly, &attrs ); if( tag == LBER_ERROR ) { /* error */ } else { /* success */ } ber_memfree( dn ); ber_memvfree( attrs ); .fi .SH ERRORS If an error occurs during decoding, generally these routines return LBER_ERROR ((ber_tag_t)\-1). .LP .SH NOTES .LP The return values for all of these functions are declared in the .B <lber.h> header file. Some routines may dynamically allocate memory which must be freed by the caller using supplied deallocation routines. .SH SEE ALSO .BR lber-encode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 358 stdin PK ͓c\ V�H- - man/man3/ldap_abandon_ext.3nu �[��� .lf 1 stdin .TH LDAP_ABANDON 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_abandon_ext \- Abandon an LDAP operation in progress .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .ft B int ldap_abandon_ext( .RS .ft B LDAP *\fIld\fB, Bint \fImsgid\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB ); .RE .fi .SH DESCRIPTION The .B ldap_abandon_ext() routine is used to send a LDAP Abandon request for an operation in progress. The \fImsgid\fP passed should be the message id of an outstanding LDAP operation, such as returned by .BR ldap_search_ext (3). .LP .BR ldap_abandon_ext () checks to see if the result of the operation has already come in. If it has, it deletes it from the queue of pending messages. If not, it sends an LDAP abandon request to the LDAP server. .LP The caller can expect that the result of an abandoned operation will not be returned from a future call to .BR ldap_result (3). .LP .B ldap_abandon_ext() allows server and client controls to be passed in via the .I sctrls and .I cctrls parameters, respectively. .LP .B ldap_abandon_ext() returns a code indicating success or, in the case of failure, the nature of the failure. See .BR ldap_error (3) for details. .SH DEPRECATED INTERFACES The .B ldap_abandon() routine is deprecated in favor of the .B ldap_abandon_ext() routine. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 61 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_result (3), .BR ldap_search_ext (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 69 stdin PK ͓c\�� �. �. man/man3/ldap_unbind_s.3nu �[��� .lf 1 stdin .TH LDAP_BIND 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_bind, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_sasl_bind, ldap_sasl_bind_s, ldap_sasl_interactive_bind_s, ldap_parse_sasl_bind_result, ldap_unbind, ldap_unbind_s, ldap_unbind_ext, ldap_unbind_ext_s, ldap_set_rebind_proc \- LDAP bind routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .BI "int ldap_bind(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_bind_s(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_simple_bind(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_simple_bind_s(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_sasl_bind(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], int *" msgidp ");" .RE .LP .BI "int ldap_sasl_bind_s(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], struct berval **" servercredp ");" .RE .LP .BI "int ldap_parse_sasl_bind_result(LDAP *" ld ", LDAPMessage *" res "," .RS .BI "struct berval **" servercredp ", int " freeit ");" .RE .LP .BI "int ldap_sasl_interactive_bind_s(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ");" .RE .LP .BI "int ldap_sasl_interactive_bind(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ", LDAPMessage *" result "," .BI "const char **" rmechp ", int *" msgidp ");" .RE .LP .BI "int (LDAP_SASL_INTERACT_PROC)(LDAP *" ld ", unsigned " flags ", void *" defaults ", void *" sasl_interact ");" .LP .BI "int ldap_unbind(LDAP *" ld ");" .LP .BI "int ldap_unbind_s(LDAP *" ld ");" .LP .BI "int ldap_unbind_ext(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_unbind_ext_s(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_set_rebind_proc (LDAP *" ld ", LDAP_REBIND_PROC *" ldap_proc ", void *" params ");" .LP .BI "int (LDAP_REBIND_PROC)(LDAP *" ld ", LDAP_CONST char *" url ", ber_tag_t " request ", ber_int_t " msgid ", void *" params ");" .SH DESCRIPTION .LP These routines provide various interfaces to the LDAP bind operation. After an association with an LDAP server is made using .BR ldap_init (3), an LDAP bind operation should be performed before other operations are attempted over the connection. An LDAP bind is required when using Version 2 of the LDAP protocol; it is optional for Version 3 but is usually needed due to security considerations. .LP There are three types of bind calls, ones providing simple authentication, ones providing SASL authentication, and general routines capable of doing either simple or SASL authentication. .LP .B SASL (Simple Authentication and Security Layer) can negotiate one of many different kinds of authentication. Both synchronous and asynchronous versions of each variant of the bind call are provided. All routines take \fIld\fP as their first parameter, as returned from .BR ldap_init (3). .SH SIMPLE AUTHENTICATION The simplest form of the bind call is .BR ldap_simple_bind_s() . It takes the DN to bind as in \fIwho\fP, and the userPassword associated with the entry in \fIpasswd\fP. It returns an LDAP error indication (see .BR ldap_error (3)). The .B ldap_simple_bind() call is asynchronous, taking the same parameters but only initiating the bind operation and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The .B ldap_sasl_bind_s() and asynchronous .B ldap_sasl_bind() functions can also be used to make a simple bind by using LDAP_SASL_SIMPLE as the SASL mechanism. .SH GENERAL AUTHENTICATION The .B ldap_bind() and .B ldap_bind_s() routines can be used when the authentication method to use needs to be selected at runtime. They both take an extra \fImethod\fP parameter selecting the authentication method to use. It should be set to LDAP_AUTH_SIMPLE to select simple authentication. .B ldap_bind() returns the message id of the request it initiates. .B ldap_bind_s() returns an LDAP error indication. .SH SASL AUTHENTICATION For SASL binds the server always ignores any provided DN, so the .I dn parameter should always be NULL. .BR ldap_sasl_bind_s () sends a single SASL bind request with the given SASL .I mechanism and credentials in the .I cred parameter. The format of the credentials depends on the particular SASL mechanism in use. For mechanisms that provide mutual authentication the server's credentials will be returned in the .I servercredp parameter. The routine returns an LDAP error indication (see .BR ldap_error (3)). The .BR ldap_sasl_bind () call is asynchronous, taking the same parameters but only sending the request and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The result must be additionally parsed by .BR ldap_parse_sasl_bind_result () to obtain any server credentials sent from the server. .LP Many SASL mechanisms require multiple message exchanges to perform a complete authentication. Applications should generally use .BR ldap_sasl_interactive_bind_s () rather than calling the basic .BR ldap_sasl_bind () functions directly. The .I mechs parameter should contain a space-separated list of candidate mechanisms to use. If this parameter is NULL or empty the library will query the supportedSASLMechanisms attribute from the server's rootDSE for the list of SASL mechanisms the server supports. The .I flags parameter controls the interaction used to retrieve any necessary SASL authentication parameters and should be one of: .TP LDAP_SASL_AUTOMATIC use defaults if available, prompt otherwise .TP LDAP_SASL_INTERACTIVE always prompt .TP LDAP_SASL_QUIET never prompt .LP The .I interact function uses the provided .I defaults to handle requests from the SASL library for particular authentication parameters. There is no defined format for the .I defaults information; it is up to the caller to use whatever format is appropriate for the supplied .I interact function. The .I sasl_interact parameter comes from the underlying SASL library. When used with Cyrus SASL this is an array of .B sasl_interact_t structures. The Cyrus SASL library will prompt for a variety of inputs, including: .TP SASL_CB_GETREALM the realm for the authentication attempt .TP SASL_CB_AUTHNAME the username to authenticate .TP SASL_CB_PASS the password for the provided username .TP SASL_CB_USER the username to use for proxy authorization .TP SASL_CB_NOECHOPROMPT generic prompt for input with input echoing disabled .TP SASL_CB_ECHOPROMPT generic prompt for input with input echoing enabled .TP SASL_CB_LIST_END indicates the end of the array of prompts .LP See the Cyrus SASL documentation for more details. .LP Applications which need to manage connections asynchronously may use .BR ldap_sasl_interactive_bind () instead of the synchronous version. A valid mechs parameter must be supplied, otherwise the library will be forced to query the server for a list of supported mechanisms, and this query will be performed synchronously. The other parameters are the same as for the synchronous function, with three additional parameters. The actual SASL mechanism that was used, and the message ID for use with .BR ldap_result () will be returned in rmechp and msgidp, respectively. The value in rmechp must not be modified by the caller and must be passed back on each subsequent call. The message obtained from .BR ldap_result () must be passed in the result parameter. This parameter must be NULL when initiating a new Bind. The caller must free the result message after each call using .BR ldap_msgfree (). The .BR ldap_sasl_interactive_bind () function returns an LDAP result code. If the code is LDAP_SASL_BIND_IN_PROGRESS then the Bind is not complete yet, and this function must be called again with the next result from the server. .SH REBINDING .LP The .B ldap_set_rebind_proc function() sets the process to use for binding when an operation returns a referral. This function is used when an application needs to bind to another server in order to follow a referral or search continuation reference. .LP The function takes \fIld\fP, the \fIrebind\fP function, and the \fIparams\fP, the arbitrary data like state information which the client might need to properly rebind. The LDAP_OPT_REFERRALS option in the \fIld\fP must be set to ON for the libraries to use the rebind function. Use the .BR ldap_set_option function to set the value. .LP The rebind function parameters are as follows: .LP The \fIld\fP parameter must be used by the application when binding to the referred server if the application wants the libraries to follow the referral. .LP The \fIurl\fP parameter points to the URL referral string received from the LDAP server. The LDAP application can use the .BR ldap_url_parse (3) function to parse the string into its components. .LP The \fIrequest\fP parameter specifies the type of request that generated the referral. .LP The \fImsgid\fP parameter specifies the message ID of the request generating the referral. .LP The \fIparams\fP parameter is the same value as passed originally to the .BR ldap_set_rebind_proc () function. .LP The LDAP libraries set all the parameters when they call the rebind function. The application should not attempt to free either the ld or the url structures in the rebind function. .LP The application must supply to the rebind function the required authentication information such as, user name, password, and certificates. The rebind function must use a synchronous bind method. .SH UNBINDING The .B ldap_unbind() call is used to unbind from the directory, terminate the current association, and free the resources contained in the \fIld\fP structure. Once it is called, the connection to the LDAP server is closed, and the \fIld\fP structure is invalid. The .B ldap_unbind_s() call is just another name for .BR ldap_unbind() ; both of these calls are synchronous in nature. .LP The .B ldap_unbind_ext() and .B ldap_unbind_ext_s() allows the operations to specify controls. .SH ERRORS Asynchronous routines will return \-1 in case of error, setting the \fIld_errno\fP parameter of the \fIld\fP structure. Synchronous routines return whatever \fIld_errno\fP is set to. See .BR ldap_error (3) for more information. .SH NOTES If an anonymous bind is sufficient for the application, the rebind process need not be provided. The LDAP libraries with the LDAP_OPT_REFERRALS option set to ON (default value) will automatically follow referrals using an anonymous bind. .LP If the application needs stronger authentication than an anonymous bind, you need to provide a rebind process for that authentication method. The bind method must be synchronous. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_open (3), .BR ldap_set_option (3), .BR ldap_url_parse (3) .B RFC 4422 (http://www.rfc-editor.org), .B Cyrus SASL (http://asg.web.cmu.edu/sasl/) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 335 stdin PK Γc\'�t!� � man/man3/ldap_start_tls.3nu �[��� .lf 1 stdin .TH LDAP_TLS 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_start_tls, ldap_start_tls_s, ldap_tls_inplace, ldap_install_tls \- LDAP TLS initialization routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "int ldap_start_tls(LDAP *" ld ");" .LP .BI "int ldap_start_tls_s(LDAP *" ld ", LDAPControl **" serverctrls ", LDAPControl **" clientctrls ");" .LP .BI "int ldap_tls_inplace(LDAP *" ld ");" .LP .BI "int ldap_install_tls(LDAP *" ld ");" .SH DESCRIPTION These routines are used to initiate TLS processing on an LDAP session. .BR ldap_start_tls_s () sends a StartTLS request to a server, waits for the reply, and then installs TLS handlers on the session if the request succeeded. The routine returns .B LDAP_SUCCESS if everything succeeded, otherwise it returns an LDAP error code. .BR ldap_start_tls () sends a StartTLS request to a server and does nothing else. It returns .B LDAP_SUCCESS if the request was sent successfully. .BR ldap_tls_inplace () returns 1 if TLS handlers have been installed on the specified session, 0 otherwise. .BR ldap_install_tls () installs the TLS handlers on the given session. It returns .B LDAP_LOCAL_ERROR if TLS is already installed. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 42 stdin PK Γc\� �q q man/man3/ldap_str2dn.3nu �[��� .lf 1 stdin .TH LDAP_GET_DN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn \- LDAP DN handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ) .LP .ft B int ldap_str2dn( const char *str, LDAPDN *dn, unsigned flags ) .LP .ft B void ldap_dnfree( LDAPDN dn ) .LP .ft B int ldap_dn2str( LDAPDN dn, char **str, unsigned flags ) .LP .ft B char **ldap_explode_dn( const char *dn, int notypes ) .LP .ft B char **ldap_explode_rdn( const char *rdn, int notypes ) .LP .ft B char *ldap_dn2ufn( const char * dn ) .LP .ft B char *ldap_dn2dcedn( const char * dn ) .LP .ft B char *ldap_dcedn2dn( const char * dn ) .LP .ft B char *ldap_dn2ad_canonical( const char * dn ) .SH DESCRIPTION These routines allow LDAP entry names (Distinguished Names, or DNs) to be obtained, parsed, converted to a user-friendly form, and tested. A DN has the form described in RFC 4414 "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names". .LP The .B ldap_get_dn() routine takes an \fIentry\fP as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3) and returns a copy of the entry's DN. Space for the DN will be obtained dynamically and should be freed by the caller using .BR ldap_memfree (3). .LP .B ldap_str2dn() parses a string representation of a distinguished name contained in .B str into its components, which are stored in .B dn as .B ldap_ava structures, arranged in .B LDAPAVA, .B LDAPRDN, and .B LDAPDN terms. Space for .B dn will be obtained dynamically and should be freed by the caller using .BR ldap_dnfree (3). The .B LDAPDN is defined as: .nf .ft B typedef struct ldap_ava { struct berval la_attr; struct berval la_value; unsigned la_flags; } LDAPAVA; typedef LDAPAVA** LDAPRDN; typedef LDAPRDN* LDAPDN; .ft .fi The attribute types and the attribute values are not normalized. The .B la_flags can be either .B LDAP_AVA_STRING or .B LDAP_AVA_BINARY, the latter meaning that the value is BER/DER encoded and thus must be represented as, quoting from RFC 4514, " ... an octothorpe character ('#' ASCII 35) followed by the hexadecimal representation of each of the bytes of the BER encoding of the X.500 AttributeValue." The .B flags parameter to .B ldap_str2dn() can be .LP .nf LDAP_DN_FORMAT_LDAPV3 LDAP_DN_FORMAT_LDAPV2 LDAP_DN_FORMAT_DCE .fi which defines what DN syntax is expected (according to RFC 4514, RFC 1779 and DCE, respectively). The format can be \fIOR\fPed to the flags .LP .nf LDAP_DN_P_NO_SPACES LDAP_DN_P_NO_SPACE_AFTER_RDN ... LDAP_DN_PEDANTIC .fi The latter is a shortcut for all the previous limitations. .LP .B LDAP_DN_P_NO_SPACES does not allow extra spaces in the dn; the default is to silently eliminate spaces around AVA separators ('='), RDN component separators ('+' for LDAPv3/LDAPv2 or ',' for DCE) and RDN separators (',' LDAPv3/LDAPv2 or '/' for DCE). .LP .B LDAP_DN_P_NO_SPACE_AFTER_RDN does not allow a single space after RDN separators. .LP .B ldap_dn2str() performs the inverse operation, yielding in .B str a string representation of .B dn. It allows the same values for .B flags as .B ldap_str2dn(), plus .LP .nf LDAP_DN_FORMAT_UFN LDAP_DN_FORMAT_AD_CANONICAL .fi for user-friendly naming (RFC 1781) and AD canonical. .LP The following routines are viewed as deprecated in favor of .B ldap_str2dn() and .BR ldap_dn2str(). They are provided to support legacy applications. .LP The .B ldap_explode_dn() routine takes a DN as returned by .B ldap_get_dn() and breaks it up into its component parts. Each part is known as a Relative Distinguished Name, or RDN. .B ldap_explode_dn() returns a NULL-terminated array, each component of which contains an RDN from the DN. The \fInotypes\fP parameter is used to request that only the RDN values be returned, not their types. For example, the DN "cn=Bob, c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob", "US", NULL }, depending on whether notypes was 0 or 1, respectively. Assertion values in RDN strings may included escaped characters. The result can be freed by calling .BR ldap_value_free (3). .LP Similarly, the .B ldap_explode_rdn() routine takes an RDN as returned by .B ldap_explode_dn(dn,0) and breaks it up into its "type=value" component parts (or just "value", if the \fInotypes\fP parameter is set). Note the value is not unescaped. The result can be freed by calling .BR ldap_value_free (3). .LP .B ldap_dn2ufn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a more user-friendly form, stripping off all type names. See "Using the Directory to Achieve User Friendly Naming" (RFC 1781) for more details on the UFN format. Due to the ambiguous nature of the format, it is generally only used for display purposes. The space for the UFN returned is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .LP .B ldap_dn2dcedn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a DCE-style DN, e.g. a string with most-significant to least significant rdns separated by slashes ('/'); rdn components are separated by commas (','). Only printable chars (e.g. LDAPv2 printable string) are allowed, at least in this implementation. .B ldap_dcedn2dn() performs the opposite operation. .B ldap_dn2ad_canonical() turns a DN into a AD canonical name, which is basically a DCE dn with attribute types omitted. The trailing domain, if present, is turned in a DNS-like domain. The space for the returned value is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .SH ERRORS If an error occurs in .BR ldap_get_dn() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .BR ldap_explode_dn() , .BR ldap_explode_rdn() , .B ldap_dn2ufn(), .B ldap_dn2dcedn(), .B ldap_dcedn2dn(), and .B ldap_dn2ad_canonical() will return NULL with .BR errno (3) set appropriately in case of trouble. .SH NOTES These routines dynamically allocate memory that the caller must free. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_first_entry (3), .BR ldap_memfree (3), .BR ldap_value_free (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 247 stdin PK ϓc\g�d"# "# man/man3/ldap_str2objectclass.3nu �[��� .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin PK ϓc\�5^#v1 v1 man/man3/ber_peek_tag.3nu �[��� .lf 1 stdin .TH LBER_DECODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");" .LP .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");" .LP .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");" .LP .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");" .LP .BI "ber_tag_t ber_get_null(BerElement *" ber ");" .LP .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");" .LP .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");" .LP .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");" .LP .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the decoding routines in the lber library. See .BR lber-encode (3) for details on the corresponding encoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_get_next () to get the next BER element and .BR ber_scanf () to do the actual decoding. In some cases, .BR ber_peek_tag () may also need to be called in normal usage. The other routines are provided for those applications that need more control than .BR ber_scanf () provides. In general, these routines return the tag of the element decoded, or LBER_ERROR if an error occurred. .LP The .BR ber_get_next () routine is used to read the next BER element from the given Sockbuf, \fIsb\fP. It strips off and returns the leading tag, strips off and returns the length of the entire element in \fIlen\fP, and sets up \fIber\fP for subsequent calls to .BR ber_scanf () et al to decode the element. See .BR lber-sockbuf (3) for details of the Sockbuf implementation of the \fIsb\fP parameter. .LP The .BR ber_scanf () routine is used to decode a BER element in much the same way that .BR scanf (3) works. It reads from \fIber\fP, a pointer to a BerElement such as returned by .BR ber_get_next (), interprets the bytes according to the format string \fIfmt\fP, and stores the results in its additional arguments. 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. .RS .LP .TP 3 .B a Octet string. A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter. The caller should free the returned string using .BR ber_memfree (). .TP .B A Octet string. A variant of "\fBa\fP". A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter, unless a zero-length string would result; in that case, the arg is set to NULL. The caller should free the returned string using .BR ber_memfree (). .TP .B s Octet string. A char * buffer should be supplied, followed by a pointer to a ber_len_t initialized to the size of the buffer. Upon return, the null-terminated octet string is put into the buffer, and the ber_len_t is set to the actual size of the octet string. .TP .B O Octet string. A struct ber_val ** should be supplied, which upon return points to a dynamically allocated struct berval containing the octet string and its length. The caller should free the returned structure using .BR ber_bvfree (). .TP .B o Octet string. A struct ber_val * should be supplied, which upon return contains the dynamically allocated octet string and its length. The caller should free the returned octet string using .BR ber_memfree (). .TP .B m Octet string. A struct ber_val * should be supplied, which upon return contains the octet string and its length. The string resides in memory assigned to the BerElement, and must not be freed by the caller. .TP .B b Boolean. A pointer to a ber_int_t should be supplied. .TP .B e Enumeration. A pointer to a ber_int_t should be supplied. .TP .B i Integer. A pointer to a ber_int_t should be supplied. .TP .B B Bitstring. A char ** should be supplied which will point to the dynamically allocated bits, followed by a ber_len_t *, which will point to the length (in bits) of the bitstring returned. .TP .B n Null. No parameter is required. The element is simply skipped if it is recognized. .TP .B v Sequence of octet strings. A char *** should be supplied, which upon return points to a dynamically allocated null-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty. The caller should free the returned array and octet strings using .BR ber_memvfree (). .TP .B V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon return points to a dynamically allocated null-terminated array of struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvecfree (). .TP .B W Sequence of octet strings with lengths. A BerVarray * should be supplied, which upon return points to a dynamically allocated array of struct berval's containing the octet strings and their lengths. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvarray_free (). .TP .B M Sequence of octet strings with lengths. This is a generalized form of the previous three formats. A void ** (ptr) should be supplied, followed by a ber_len_t * (len) and a ber_len_t (off). Upon return (ptr) will point to a dynamically allocated array whose elements are all of size (*len). A struct berval will be filled starting at offset (off) in each element. The strings in each struct berval reside in memory assigned to the BerElement and must not be freed by the caller. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The number of elements in the array is also stored in (*len) on return. The caller should free the returned array using .BR ber_memfree (). .TP .B l Length of the next element. A pointer to a ber_len_t should be supplied. .TP .B t Tag of the next element. A pointer to a ber_tag_t should be supplied. .TP .B T Skip element and return its tag. A pointer to a ber_tag_t should be supplied. .TP .B x Skip element. The next element is skipped. .TP .B { Begin sequence. No parameter is required. The initial sequence tag and length are skipped. .TP .B } End sequence. No parameter is required and no action is taken. .TP .B [ Begin set. No parameter is required. The initial set tag and length are skipped. .TP .B ] End set. No parameter is required and no action is taken. .RE .LP The .BR ber_get_int () routine tries to interpret the next element as an integer, returning the result in \fInum\fP. The tag of whatever it finds is returned on success, LBER_ERROR (\-1) on failure. .LP The .BR ber_get_stringb () routine is used to read an octet string into a preallocated buffer. The \fIlen\fP parameter should be initialized to the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte. .LP The .BR ber_get_stringa () routine is used to dynamically allocate space into which an octet string is read. The caller should free the returned string using .BR ber_memfree(). .LP The .BR ber_get_stringal () routine is used to dynamically allocate space into which an octet string and its length are read. It takes a struct berval **, and returns the result in this parameter. The caller should free the returned structure using .BR ber_bvfree(). .LP The .BR ber_get_stringbv () routine is used to read an octet string and its length into the provided struct berval *. If the \fIalloc\fP parameter is zero, the string will reside in memory assigned to the BerElement, and must not be freed by the caller. If the \fIalloc\fP parameter is non-zero, the string will be copied into dynamically allocated space which should be returned using .BR ber_memfree (). .LP The .BR ber_get_null () routine is used to read a NULL element. It returns the tag of the element it skips over. .LP The .BR ber_get_boolean () routine is used to read a boolean value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_enum () routine is used to read a enumeration value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_bitstringa () routine is used to read a bitstring value. It takes a char ** which will hold the dynamically allocated bits, followed by an ber_len_t *, which will point to the length (in bits) of the bitstring returned. The caller should free the returned string using .BR ber_memfree (). .LP The .BR ber_first_element () routine is used to return the tag and length of the first element in a set or sequence. It also returns in \fIcookie\fP a magic cookie parameter that should be passed to subsequent calls to ber_next_element(), which returns similar information. .SH EXAMPLES Assume the variable \fIber\fP contains a lightweight BER encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP The element can be decoded using .BR ber_scanf () as follows. .LP .nf ber_int_t scope, deref, size, time, attrsonly; char *dn, **attrs; ber_tag_t tag; tag = ber_scanf( ber, "{aeeiib{v}}", &dn, &scope, &deref, &size, &time, &attrsonly, &attrs ); if( tag == LBER_ERROR ) { /* error */ } else { /* success */ } ber_memfree( dn ); ber_memvfree( attrs ); .fi .SH ERRORS If an error occurs during decoding, generally these routines return LBER_ERROR ((ber_tag_t)\-1). .LP .SH NOTES .LP The return values for all of these functions are declared in the .B <lber.h> header file. Some routines may dynamically allocate memory which must be freed by the caller using supplied deallocation routines. .SH SEE ALSO .BR lber-encode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 358 stdin PK Гc\�5^#v1 v1 man/man3/ber_get_boolean.3nu �[��� .lf 1 stdin .TH LBER_DECODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");" .LP .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");" .LP .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");" .LP .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");" .LP .BI "ber_tag_t ber_get_null(BerElement *" ber ");" .LP .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");" .LP .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");" .LP .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");" .LP .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the decoding routines in the lber library. See .BR lber-encode (3) for details on the corresponding encoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_get_next () to get the next BER element and .BR ber_scanf () to do the actual decoding. In some cases, .BR ber_peek_tag () may also need to be called in normal usage. The other routines are provided for those applications that need more control than .BR ber_scanf () provides. In general, these routines return the tag of the element decoded, or LBER_ERROR if an error occurred. .LP The .BR ber_get_next () routine is used to read the next BER element from the given Sockbuf, \fIsb\fP. It strips off and returns the leading tag, strips off and returns the length of the entire element in \fIlen\fP, and sets up \fIber\fP for subsequent calls to .BR ber_scanf () et al to decode the element. See .BR lber-sockbuf (3) for details of the Sockbuf implementation of the \fIsb\fP parameter. .LP The .BR ber_scanf () routine is used to decode a BER element in much the same way that .BR scanf (3) works. It reads from \fIber\fP, a pointer to a BerElement such as returned by .BR ber_get_next (), interprets the bytes according to the format string \fIfmt\fP, and stores the results in its additional arguments. 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. .RS .LP .TP 3 .B a Octet string. A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter. The caller should free the returned string using .BR ber_memfree (). .TP .B A Octet string. A variant of "\fBa\fP". A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter, unless a zero-length string would result; in that case, the arg is set to NULL. The caller should free the returned string using .BR ber_memfree (). .TP .B s Octet string. A char * buffer should be supplied, followed by a pointer to a ber_len_t initialized to the size of the buffer. Upon return, the null-terminated octet string is put into the buffer, and the ber_len_t is set to the actual size of the octet string. .TP .B O Octet string. A struct ber_val ** should be supplied, which upon return points to a dynamically allocated struct berval containing the octet string and its length. The caller should free the returned structure using .BR ber_bvfree (). .TP .B o Octet string. A struct ber_val * should be supplied, which upon return contains the dynamically allocated octet string and its length. The caller should free the returned octet string using .BR ber_memfree (). .TP .B m Octet string. A struct ber_val * should be supplied, which upon return contains the octet string and its length. The string resides in memory assigned to the BerElement, and must not be freed by the caller. .TP .B b Boolean. A pointer to a ber_int_t should be supplied. .TP .B e Enumeration. A pointer to a ber_int_t should be supplied. .TP .B i Integer. A pointer to a ber_int_t should be supplied. .TP .B B Bitstring. A char ** should be supplied which will point to the dynamically allocated bits, followed by a ber_len_t *, which will point to the length (in bits) of the bitstring returned. .TP .B n Null. No parameter is required. The element is simply skipped if it is recognized. .TP .B v Sequence of octet strings. A char *** should be supplied, which upon return points to a dynamically allocated null-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty. The caller should free the returned array and octet strings using .BR ber_memvfree (). .TP .B V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon return points to a dynamically allocated null-terminated array of struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvecfree (). .TP .B W Sequence of octet strings with lengths. A BerVarray * should be supplied, which upon return points to a dynamically allocated array of struct berval's containing the octet strings and their lengths. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvarray_free (). .TP .B M Sequence of octet strings with lengths. This is a generalized form of the previous three formats. A void ** (ptr) should be supplied, followed by a ber_len_t * (len) and a ber_len_t (off). Upon return (ptr) will point to a dynamically allocated array whose elements are all of size (*len). A struct berval will be filled starting at offset (off) in each element. The strings in each struct berval reside in memory assigned to the BerElement and must not be freed by the caller. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The number of elements in the array is also stored in (*len) on return. The caller should free the returned array using .BR ber_memfree (). .TP .B l Length of the next element. A pointer to a ber_len_t should be supplied. .TP .B t Tag of the next element. A pointer to a ber_tag_t should be supplied. .TP .B T Skip element and return its tag. A pointer to a ber_tag_t should be supplied. .TP .B x Skip element. The next element is skipped. .TP .B { Begin sequence. No parameter is required. The initial sequence tag and length are skipped. .TP .B } End sequence. No parameter is required and no action is taken. .TP .B [ Begin set. No parameter is required. The initial set tag and length are skipped. .TP .B ] End set. No parameter is required and no action is taken. .RE .LP The .BR ber_get_int () routine tries to interpret the next element as an integer, returning the result in \fInum\fP. The tag of whatever it finds is returned on success, LBER_ERROR (\-1) on failure. .LP The .BR ber_get_stringb () routine is used to read an octet string into a preallocated buffer. The \fIlen\fP parameter should be initialized to the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte. .LP The .BR ber_get_stringa () routine is used to dynamically allocate space into which an octet string is read. The caller should free the returned string using .BR ber_memfree(). .LP The .BR ber_get_stringal () routine is used to dynamically allocate space into which an octet string and its length are read. It takes a struct berval **, and returns the result in this parameter. The caller should free the returned structure using .BR ber_bvfree(). .LP The .BR ber_get_stringbv () routine is used to read an octet string and its length into the provided struct berval *. If the \fIalloc\fP parameter is zero, the string will reside in memory assigned to the BerElement, and must not be freed by the caller. If the \fIalloc\fP parameter is non-zero, the string will be copied into dynamically allocated space which should be returned using .BR ber_memfree (). .LP The .BR ber_get_null () routine is used to read a NULL element. It returns the tag of the element it skips over. .LP The .BR ber_get_boolean () routine is used to read a boolean value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_enum () routine is used to read a enumeration value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_bitstringa () routine is used to read a bitstring value. It takes a char ** which will hold the dynamically allocated bits, followed by an ber_len_t *, which will point to the length (in bits) of the bitstring returned. The caller should free the returned string using .BR ber_memfree (). .LP The .BR ber_first_element () routine is used to return the tag and length of the first element in a set or sequence. It also returns in \fIcookie\fP a magic cookie parameter that should be passed to subsequent calls to ber_next_element(), which returns similar information. .SH EXAMPLES Assume the variable \fIber\fP contains a lightweight BER encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP The element can be decoded using .BR ber_scanf () as follows. .LP .nf ber_int_t scope, deref, size, time, attrsonly; char *dn, **attrs; ber_tag_t tag; tag = ber_scanf( ber, "{aeeiib{v}}", &dn, &scope, &deref, &size, &time, &attrsonly, &attrs ); if( tag == LBER_ERROR ) { /* error */ } else { /* success */ } ber_memfree( dn ); ber_memvfree( attrs ); .fi .SH ERRORS If an error occurs during decoding, generally these routines return LBER_ERROR ((ber_tag_t)\-1). .LP .SH NOTES .LP The return values for all of these functions are declared in the .B <lber.h> header file. Some routines may dynamically allocate memory which must be freed by the caller using supplied deallocation routines. .SH SEE ALSO .BR lber-encode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 358 stdin PK ѓc\����� � man/man3/ldap_get_values.3nu �[��� .lf 1 stdin .TH LDAP_GET_VALUES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_values, ldap_get_values_len, ldap_count_values \- LDAP attribute value handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char **ldap_get_values(ld, entry, attr) .ft LDAP *ld; LDAPMessage *entry; char *attr; .LP .ft B struct berval **ldap_get_values_len(ld, entry, attr) .ft LDAP *ld; LDAPMessage *entry; char *attr; .LP .ft B int ldap_count_values(vals) .ft char **vals; .LP .ft B int ldap_count_values_len(vals) .ft struct berval **vals; .LP .ft B void ldap_value_free(vals) .ft char **vals; .LP .ft B void ldap_value_free_len(vals) .ft struct berval **vals; .SH DESCRIPTION These routines are used to retrieve and manipulate attribute values from an LDAP entry as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3). .B ldap_get_values() takes the \fIentry\fP and the attribute \fIattr\fP whose values are desired and returns a NULL-terminated array of the attribute's values. \fIattr\fP may be an attribute type as returned from .BR ldap_first_attribute (3) or .BR ldap_next_attribute (3), or if the attribute type is known it can simply be given. .LP The number of values in the array can be counted by calling .BR ldap_count_values() . The array of values returned can be freed by calling .BR ldap_value_free() . .LP If the attribute values are binary in nature, and thus not suitable to be returned as an array of char *'s, the .B ldap_get_values_len() routine can be used instead. It takes the same parameters as .BR ldap_get_values() , but returns a NULL-terminated array of pointers to berval structures, each containing the length of and a pointer to a value. .LP The number of values in the array can be counted by calling .BR ldap_count_values_len() . The array of values returned can be freed by calling .BR ldap_value_free_len() . .SH ERRORS If an error occurs in .B ldap_get_values() or .BR ldap_get_values_len() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .SH NOTES These routines dynamically allocate memory which the caller must free using the supplied routines. .SH SEE ALSO .BR ldap (3), .BR ldap_first_entry (3), .BR ldap_first_attribute (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 103 stdin PK ғc\��A man/man3/ldap_modrdn2_s.3nu �[��� .lf 1 stdin .TH LDAP_MODRDN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_modrdn, ldap_modrdn_s, ldap_modrdn2, ldap_modrdn2_s \- Perform an LDAP modify RDN operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_modrdn(ld, dn, newrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; .LP .ft B .LP .ft B int ldap_modrdn_s(ld, dn, newrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; .LP .ft B int ldap_modrdn2(ld, dn, newrdn, deleteoldrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; int deleteoldrdn; .LP .ft B int ldap_modrdn2_s(ld, dn, newrdn, deleteoldrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; int deleteoldrdn; .SH DESCRIPTION The .B ldap_modrdn() and .B ldap_modrdn_s() routines perform an LDAP modify RDN operation. They both take \fIdn\fP, the DN of the entry whose RDN is to be changed, and \fInewrdn\fP, the new RDN to give the entry. The old RDN of the entry is never kept as an attribute of the entry. .B ldap_modrdn() is asynchronous, returning the message id of the operation it initiates. .B ldap_modrdn_s() is synchronous, returning the LDAP error code indicating the success or failure of the operation. Use of these routines is deprecated. Use the versions described below instead. .LP The .B ldap_modrdn2() and .B ldap_modrdn2_s() routines also perform an LDAP modify RDN operation, taking the same parameters as above. In addition, they both take the \fIdeleteoldrdn\fP parameter which is used as a boolean value to indicate whether the old RDN values should be deleted from the entry or not. .SH ERRORS The synchronous (_s) versions of these routines return an LDAP error code, either LDAP_SUCCESS or an error if there was trouble. The asynchronous versions return \-1 in case of trouble, setting the .B ld_errno field of \fIld\fP. See .BR ldap_error (3) for more details. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 82 stdin PK ғc\]�Ib� � man/man3/ldap_delete_ext_s.3nu �[��� .lf 1 stdin .TH LDAP_DELETE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_delete, ldap_delete_s, ldap_delete_ext, ldap_delete_ext_s \- Perform an LDAP delete operation. .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_delete_s(ld, dn) .ft LDAP *ld; char *dn; .LP .ft B int ldap_delete(ld, dn) .ft LDAP *ld; char *dn; .LP .ft B int ldap_delete_ext(ld, dn, serverctrls, clientctrls, msgidp) .ft LDAP *ld; char *dn; LDAPControl **serverctrls, **clientctrls; int *msgidp; .LP .ft B int ldap_delete_ext_s(ld, dn, serverctrls, clientctrls) .ft LDAP *ld; char *dn; LDAPControl **serverctrls, **clientctrls; .SH DESCRIPTION The .B ldap_delete_s() routine is used to perform an LDAP delete operation synchronously. It takes \fIdn\fP, the DN of the entry to be deleted. It returns an LDAP error code, indicating the success or failure of the operation. .LP The .B ldap_delete() routine is used to perform an LDAP delete operation asynchronously. It takes the same parameters as .BR ldap_delete_s(), but returns the message id of the request it initiated. The result of the delete can be obtained by a subsequent call to .BR ldap_result (3). .LP The .B ldap_delete_ext() routine allows server and client controls to be specified to extend the delete request. This routine is asynchronous like ldap_delete(), but its return value is an LDAP error code. It stores the message id of the request in the integer pointed to by msgidp. .LP The .B ldap_delete_ext_s() routine is the synchronous version of .BR ldap_delete_ext(). It also returns an LDAP error code indicating success or failure of the operation. .SH ERRORS .B ldap_delete_s() returns an LDAP error code which can be interpreted by calling one of .BR ldap_perror (3) and friends. .B ldap_delete() returns \-1 if something went wrong initiating the request. It returns the non-negative message id of the request if things went ok. .LP .B ldap_delete_ext() and .B ldap_delete_ext_s() return some Non-zero value if something went wrong initiating the request, else return 0. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 90 stdin PK ӓc\��n� � man/man3/ldap_initialize.3nu �[��� .lf 1 stdin .TH LDAP_OPEN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_init, ldap_initialize, ldap_open \- Initialize the LDAP library and open a connection to an LDAP server .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B LDAP *ldap_open(host, port) .ft char *host; int port; .LP .ft B LDAP *ldap_init(host, port) .ft char *host; int port; .LP .ft B int ldap_initialize(ldp, uri) .ft LDAP **ldp; char *uri; .LP .ft B int ldap_set_urllist_proc(ld, proc, params) .ft LDAP *ld; LDAP_URLLIST_PROC *proc; void *params; .LP .ft B int (LDAP_URLLIST_PROC)(ld, urllist, url, params); .ft LDAP *ld; LDAPURLDesc **urllist; LDAPURLDesc **url; void *params; .LP .ft B #include <ldap_pvt.h> .LP .ft B int ldap_init_fd(fd, proto, uri, ldp) .ft ber_socket_t fd; int proto; char *uri; LDAP **ldp; .SH DESCRIPTION .LP .B ldap_open() opens a connection to an LDAP server and allocates an LDAP structure which is used to identify the connection and to maintain per-connection information. .B ldap_init() allocates an LDAP structure but does not open an initial connection. .B ldap_initialize() allocates an LDAP structure but does not open an initial connection. .B ldap_init_fd() allocates an LDAP structure using an existing connection on the provided socket. One of these routines must be called before any operations are attempted. .LP .B ldap_open() takes \fIhost\fP, the hostname on which the LDAP server is running, and \fIport\fP, the port number to which to connect. If the default IANA-assigned port of 389 is desired, LDAP_PORT should be specified for \fIport\fP. The \fIhost\fP parameter may contain a blank-separated list of hosts to try to connect to, and each host may optionally by of the form \fIhost:port\fP. If present, the \fI:port\fP overrides the \fIport\fP parameter to .BR ldap_open() . Upon successfully making a connection to an LDAP server, .B ldap_open() returns a pointer to an opaque LDAP structure, which should be passed to subsequent calls to .BR ldap_bind() , .BR ldap_search() , etc. Certain fields in the LDAP structure can be set to indicate size limit, time limit, and how aliases are handled during operations; read and write access to those fields must occur by calling .BR ldap_get_option (3) and .BR ldap_set_option (3) respectively, whenever possible. .LP .B ldap_init() acts just like .BR ldap_open() , but does not open a connection to the LDAP server. The actual connection open will occur when the first operation is attempted. .LP .B ldap_initialize() acts like .BR ldap_init() , but it returns an integer indicating either success or the failure reason, and it allows to specify details for the connection in the schema portion of the URI. The .I uri parameter may be a comma- or whitespace-separated list of URIs containing only the .IR schema , the .IR host , and the .I port fields. Apart from .BR ldap , other (non-standard) recognized values of the .I schema field are .B ldaps (LDAP over TLS), .B ldapi (LDAP over IPC), and .B cldap (connectionless LDAP). If other fields are present, the behavior is undefined. .LP At this time, .B ldap_open() and .B ldap_init() are deprecated in favor of .BR ldap_initialize() , essentially because the latter allows to specify a schema in the URI and it explicitly returns an error code. .LP .B ldap_init_fd() allows an LDAP structure to be initialized using an already-opened connection. The .I proto parameter should be one of LDAP_PROTO_TCP, LDAP_PROTO_UDP, or LDAP_PROTO_IPC for a connection using TCP, UDP, or IPC, respectively. The value LDAP_PROTO_EXT may also be specified if user-supplied sockbuf handlers are going to be used. Note that support for UDP is not implemented unless libldap was built with LDAP_CONNECTIONLESS defined. The .I uri parameter may optionally be provided for informational purposes. .LP .B ldap_set_urllist_proc() allows to set a function .I proc of type .I LDAP_URLLIST_PROC that is called when a successful connection can be established. This function receives the list of URIs parsed from the .I uri string originally passed to .BR ldap_initialize() , and the one that successfully connected. The function may manipulate the URI list; the typical use consists in moving the successful URI to the head of the list, so that subsequent attempts to connect to one of the URIs using the same LDAP handle will try it first. If .I ld is null, .I proc is set as a global parameter that is inherited by all handlers within the process that are created after the call to .BR ldap_set_urllist_proc() . By default, no .I LDAP_URLLIST_PROC is set. In a multithreaded environment, .B ldap_set_urllist_proc() must be called before any concurrent operation using the LDAP handle is started. Note: the first call into the LDAP library also initializes the global options for the library. As such the first call should be single-threaded or otherwise protected to insure that only one call is active. It is recommended that .BR ldap_get_option () or .BR ldap_set_option () be used in the program's main thread before any additional threads are created. See .BR ldap_get_option (3). .SH ERRORS If an error occurs, .B ldap_open() and .B ldap_init() will return NULL and .I errno should be set appropriately. .B ldap_initialize() and .B ldap_init_fd() will directly return the LDAP code associated to the error (or .I LDAP_SUCCESS in case of success); .I errno should be set as well whenever appropriate. .B ldap_set_urllist_proc() returns LDAP_OPT_ERROR on error, and LDAP_OPT_SUCCESS on success. .SH SEE ALSO .BR ldap (3), .BR ldap_bind (3), .BR ldap_get_option (3), .BR ldap_set_option (3), .BR lber-sockbuf (3), .BR errno (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 226 stdin PK ԓc\ ��� � & man/man3/ldap_parse_sasl_bind_result.3nu �[��� .lf 1 stdin .TH LDAP_PARSE_RESULT 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_parse_result \- Parsing results .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_parse_result( LDAP *ld, LDAPMessage *result, int *errcodep, char **matcheddnp, char **errmsgp, char ***referralsp, LDAPControl ***serverctrlsp, int freeit ) .LP .ft B int ldap_parse_sasl_bind_result( LDAP *ld, LDAPMessage *result, struct berval **servercredp, int freeit ) .LP .ft B int ldap_parse_extended_result( LDAP *ld, LDAPMessage *result, char **retoidp, struct berval **retdatap, int freeit ) .SH DESCRIPTION .LP These routines are used to extract information from a result message. They will operate on the first result message in a chain of search results (skipping past other message types). They take the \fIresult\fP as returned by a call to .BR ldap_result (3), .BR ldap_search_s (3) or .BR ldap_search_st (3). In addition to .BR ldap_parse_result() , the routines .B ldap_parse_sasl_bind_result() and .B ldap_parse_extended_result() are used to get all the result information from SASL bind and extended operations. .LP The \fIerrcodep\fP parameter will be filled in with the result code from the result message. .LP The server might supply a matched DN string in the message indicating how much of a name in a request was recognized. The \fImatcheddnp\fP parameter will be filled in with this string if supplied, else it will be NULL. If a string is returned, it should be freed using .BR ldap_memfree (3). .LP The \fIerrmsgp\fP parameter will be filled in with the error message field from the parsed message. This string should be freed using .BR ldap_memfree (3). .LP The \fIreferralsp\fP parameter will be filled in with an allocated array of referral strings from the parsed message. This array should be freed using .BR ldap_memvfree (3). If no referrals were returned, \fI*referralsp\fP is set to NULL. .LP The \fIserverctrlsp\fP parameter will be filled in with an allocated array of controls copied from the parsed message. The array should be freed using .BR ldap_controls_free (3). If no controls were returned, \fI*serverctrlsp\fP is set to NULL. .LP The \fIfreeit\fP parameter determines whether the parsed message is freed or not after the extraction. Any non-zero value will make it free the message. The .BR ldap_msgfree (3) routine can also be used to free the message later. .LP For SASL bind results, the \fIservercredp\fP parameter will be filled in with an allocated berval structure containing the credentials from the server if present. The structure should be freed using .BR ber_bvfree (3). .LP For extended results, the \fIretoidp\fP parameter will be filled in with the dotted-OID text representation of the name of the extended operation response. The string should be freed using .BR ldap_memfree (3). If no OID was returned, \fI*retoidp\fP is set to NULL. .LP For extended results, the \fIretdatap\fP parameter will be filled in with a pointer to a berval structure containing the data from the extended operation response. The structure should be freed using .BR ber_bvfree (3). If no data were returned, \fI*retdatap\fP is set to NULL. .LP For all the above result parameters, NULL values can be used in calls in order to ignore certain fields. .SH ERRORS Upon success LDAP_SUCCESS is returned. Otherwise the values of the result parameters are undefined. .SH SEE ALSO .BR ldap (3), .BR ldap_result (3), .BR ldap_search (3), .BR ldap_memfree (3), .BR ldap_memvfree (3), .BR ldap_get_values (3), .BR ldap_controls_free (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 108 stdin PK Փc\�C�B� � man/man3/ldap_compare_ext.3nu �[��� .lf 1 stdin .TH LDAP_COMPARE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_compare, ldap_compare_s, ldap_compare_ext, ldap_compare_ext_s \- Perform an LDAP compare operation. .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_compare_ext( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, char *\fIattr\fB, const struct berval *\fIbvalue\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB, int *\fImsgidp\fB ); .RE .LP .ft B int ldap_compare_ext_s( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, char *\fIattr\fB, const struct berval *\fIbvalue\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB ); .RE .SH DESCRIPTION The .B ldap_compare_ext_s() routine is used to perform an LDAP compare operation synchronously. It takes \fIdn\fP, the DN of the entry upon which to perform the compare, and \fIattr\fP and \fIvalue\fP, the attribute description and value to compare to those found in the entry. It returns a code, which will be LDAP_COMPARE_TRUE if the entry contains the attribute value and LDAP_COMPARE_FALSE if it does not. Otherwise, an error code is returned that indicates the nature of the problem. See .BR ldap (3) for details. .LP The .B ldap_compare_ext() routine is used to perform an LDAP compare operation asynchronously. It takes the same parameters as .BR ldap_compare_ext_s() , but provides the message id of the request it initiated in the integer pointed to \fImsgidp\fP. The result of the compare can be obtained by a subsequent call to .BR ldap_result (3). .LP Both routines allow server and client controls to be specified to extend the compare request. .SH DEPRECATED INTERFACES The routines .BR ldap_compare () and .BR ldap_compare_s () are deprecated in favor of .BR ldap_compare_ext () and .BR ldap_compare_ext_s (), respectively. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 75 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 80 stdin PK Փc\S/�6 6 man/man3/ldap_next_attribute.3nu �[��� .lf 1 stdin .TH LDAP_FIRST_ATTRIBUTE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_first_attribute, ldap_next_attribute \- step through LDAP entry attributes .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_first_attribute( LDAP *ld, LDAPMessage *entry, BerElement **berptr ) .LP .ft B char *ldap_next_attribute( LDAP *ld, LDAPMessage *entry, BerElement *ber ) .SH DESCRIPTION The .B ldap_first_attribute() and .B ldap_next_attribute() routines are used to step through the attributes in an LDAP entry. .B ldap_first_attribute() takes an \fIentry\fP as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3) and returns a pointer to character string containing the first attribute description in the entry. .B ldap_next_attribute() returns the next attribute description in the entry. .LP It also returns, in \fIberptr\fP, a pointer to a BerElement it has allocated to keep track of its current position. This pointer should be passed to subsequent calls to .B ldap_next_attribute() and is used to effectively step through the entry's attributes. The caller is solely responsible for freeing the BerElement pointed to by \fIberptr\fP when it is no longer needed by calling .BR ber_free (3). When calling .BR ber_free (3) in this instance, be sure the second argument is 0. .LP The attribute names returned are suitable for inclusion in a call to .BR ldap_get_values (3) to retrieve the attribute's values. .SH ERRORS If an error occurs, NULL is returned and the ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .SH NOTES The .B ldap_first_attribute() and .B ldap_next_attribute() return dynamically allocated memory that must be freed by the caller via .BR ldap_memfree (3). .SH SEE ALSO .BR ldap (3), .BR ldap_first_entry (3), .BR ldap_get_values (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 74 stdin PK ֓c\ ݴ� man/man3/ldap_free_urldesc.3nu �[��� .lf 1 stdin .TH LDAP_URL 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_is_ldap_url, ldap_url_parse, ldap_free_urldesc \- LDAP Uniform Resource Locator routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_is_ldap_url( const char *url ) .LP .ft B int ldap_url_parse( const char *url, LDAPURLDesc **ludpp ) .LP typedef struct ldap_url_desc { char * lud_scheme; /* URI scheme */ char * lud_host; /* LDAP host to contact */ int lud_port; /* port on host */ char * lud_dn; /* base for search */ char ** lud_attrs; /* list of attributes */ int lud_scope; /* a LDAP_SCOPE_... value */ char * lud_filter; /* LDAP search filter */ char ** lud_exts; /* LDAP extensions */ int lud_crit_exts; /* true if any extension is critical */ /* may contain additional fields for internal use */ } LDAPURLDesc; .LP .ft B void ldap_free_urldesc( LDAPURLDesc *ludp ); .SH DESCRIPTION These routines support the use of LDAP URLs (Uniform Resource Locators) as detailed in RFC 4516. LDAP URLs look like this: .nf \fBldap://\fP\fIhostport\fP\fB/\fP\fIdn\fP[\fB?\fP\fIattrs\fP[\fB?\fP\fIscope\fP[\fB?\fP\fIfilter\fP[\fB?\fP\fIexts\fP]]]] where: \fIhostport\fP is a host name with an optional ":portnumber" \fIdn\fP is the search base \fIattrs\fP is a comma separated list of attributes to request \fIscope\fP is one of these three strings: base one sub (default=base) \fIfilter\fP is filter \fIexts\fP are recognized set of LDAP and/or API extensions. Example: ldap://ldap.example.net/dc=example,dc=net?cn,sn?sub?(cn=*) .fi .LP URLs that are wrapped in angle-brackets and/or preceded by "URL:" are also tolerated. Alternative LDAP schemes such as ldaps:// and ldapi:// may be parsed using the below routines as well. .LP .B ldap_is_ldap_url() returns a non-zero value if \fIurl\fP looks like an LDAP URL (as opposed to some other kind of URL). It can be used as a quick check for an LDAP URL; the .B ldap_url_parse() routine should be used if a more thorough check is needed. .LP .B ldap_url_parse() breaks down an LDAP URL passed in \fIurl\fP into its component pieces. If successful, zero is returned, an LDAP URL description is allocated, filled in, and \fIludpp\fP is set to point to it. If an error occurs, a non-zero URL error code is returned. .LP .B ldap_free_urldesc() should be called to free an LDAP URL description that was obtained from a call to .B ldap_url_parse(). .SH SEE ALSO .nf .BR ldap (3) .BR "RFC 4516" " <http://www.rfc-editor.org/rfc/rfc4516.txt>" .SH ACKNOWLEDGEMENTS .fi .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 84 stdin PK דc\��MK$ K$ man/man3/ber_put_int.3nu �[��� .lf 1 stdin .TH LBER_ENCODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_alloc_t, ber_flush, ber_flush2, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring, ber_put_string, ber_put_null, ber_put_boolean, ber_put_bitstring, ber_start_seq, ber_start_set, ber_put_seq, ber_put_set \- OpenLDAP LBER simplified Basic Encoding Rules library routines for encoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_flush2(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_printf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "int ber_put_int(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_enum(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_ostring(BerElement *" ber ", const char *" str ", ber_len_t " len ", ber_tag_t " tag ");" .LP .BI "int ber_put_string(BerElement *" ber ", const char *" str ", ber_tag_t " tag ");" .LP .BI "int ber_put_null(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_boolean(BerElement *" ber ", ber_int_t " bool ", ber_tag_t " tag ");" .LP .BI "int ber_put_bitstring(BerElement *" ber ", const char *" str ", ber_len_t " blen ", ber_tag_t " tag ");" .LP .BI "int ber_start_seq(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_start_set(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_seq(BerElement *" ber ");" .LP .BI "int ber_put_set(BerElement *" ber ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the encoding routines in the lber library. See .BR lber-decode (3) for details on the corresponding decoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_alloc_t () to allocate a BER element for encoding, .BR ber_printf () to do the actual encoding, and .BR ber_flush2 () to actually write the element. The other routines are provided for those applications that need more control than .BR ber_printf () provides. In general, these routines return the length of the element encoded, or \-1 if an error occurred. .LP The .BR ber_alloc_t () routine is used to allocate a new BER element. It should be called with an argument of LBER_USE_DER. .LP The .BR ber_flush2 () routine is used to actually write the element to a socket (or file) descriptor, once it has been fully encoded (using .BR ber_printf () and friends). See .BR lber-sockbuf (3) for more details on the Sockbuf implementation of the \fIsb\fP parameter. If the \fIfreeit\fP parameter is non-zero, the supplied \fIber\fP will be freed. If \fILBER_FLUSH_FREE_ON_SUCCESS\fP is used, the \fIber\fP is only freed when successfully flushed, otherwise it is left intact; if \fILBER_FLUSH_FREE_ON_ERROR\fP is used, the \fIber\fP is only freed when an error occurs, otherwise it is left intact; if \fILBER_FLUSH_FREE_ALWAYS\fP is used, the \fIber\fP is freed anyway. This function differs from the original .BR ber_flush (3) function, whose behavior corresponds to that indicated for \fILBER_FLUSH_FREE_ON_SUCCESS\fP. Note that in the future, the behavior of .BR ber_flush (3) with \fIfreeit\fP non-zero might change into that of .BR ber_flush2 (3) with \fIfreeit\fP set to \fILBER_FLUSH_FREE_ALWAYS\fP. .LP The .BR ber_printf () routine is used to encode a BER element in much the same way that .BR sprintf (3) works. One important difference, though, is that some state information is kept with the \fIber\fP parameter so that multiple calls can be made to .BR ber_printf () to append things to the end of the BER element. .BR Ber_printf () writes to \fIber\fP, a pointer to a BerElement such as returned by .BR ber_alloc_t (). It interprets and formats its arguments according to the format string \fIfmt\fP. The format string can contain the following characters: .RS .LP .TP 3 .B b Boolean. An ber_int_t parameter should be supplied. A boolean element is output. .TP .B e Enumeration. An ber_int_t parameter should be supplied. An enumeration element is output. .TP .B i Integer. An ber_int_t parameter should be supplied. An integer element is output. .TP .B B Bitstring. A char * pointer to the start of the bitstring is supplied, followed by the number of bits in the bitstring. A bitstring element is output. .TP .B n Null. No parameter is required. A null element is output. .TP .B o Octet string. A char * is supplied, followed by the length of the string pointed to. An octet string element is output. .TP .B O Octet string. A struct berval * is supplied. An octet string element is output. .TP .B s Octet string. A null-terminated string is supplied. An octet string element is output, not including the trailing NULL octet. .TP .B t Tag. A ber_tag_t specifying the tag to give the next element is provided. This works across calls. .TP .B v Several octet strings. A null-terminated array of char *'s is supplied. Note that a construct like '{v}' is required to get an actual SEQUENCE OF octet strings. .TP .B V Several octet strings. A null-terminated array of struct berval *'s is supplied. Note that a construct like '{V}' is required to get an actual SEQUENCE OF octet strings. .TP .B W Several octet strings. An array of struct berval's is supplied. The array is terminated by a struct berval with a NULL bv_val. Note that a construct like '{W}' is required to get an actual SEQUENCE OF octet strings. .TP .B { Begin sequence. No parameter is required. .TP .B } End sequence. No parameter is required. .TP .B [ Begin set. No parameter is required. .TP .B ] End set. No parameter is required. .RE .LP The .BR ber_put_int () routine writes the integer element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_enum () routine writes the enumeration element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_boolean () routine writes the boolean value given by \fIbool\fP to the BER element. .LP The .BR ber_put_bitstring () routine writes \fIblen\fP bits starting at \fIstr\fP as a bitstring value to the given BER element. Note that \fIblen\fP is the length \fIin bits\fP of the bitstring. .LP The .BR ber_put_ostring () routine writes \fIlen\fP bytes starting at \fIstr\fP to the BER element as an octet string. .LP The .BR ber_put_string () routine writes the null-terminated string (minus the terminating '\0') to the BER element as an octet string. .LP The .BR ber_put_null () routine writes a NULL element to the BER element. .LP The .BR ber_start_seq () routine is used to start a sequence in the BER element. The .BR ber_start_set () routine works similarly. The end of the sequence or set is marked by the nearest matching call to .BR ber_put_seq () or .BR ber_put_set (), respectively. .SH EXAMPLES Assuming the following variable declarations, and that the variables have been assigned appropriately, an lber encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP can be achieved like so: .LP .nf int rc; ber_int_t scope, ali, size, time, attrsonly; char *dn, **attrs; BerElement *ber; /* ... fill in values ... */ ber = ber_alloc_t( LBER_USE_DER ); if ( ber == NULL ) { /* error */ } rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali, size, time, attrsonly, attrs ); if( rc == \-1 ) { /* error */ } else { /* success */ } .fi .SH ERRORS If an error occurs during encoding, generally these routines return \-1. .LP .SH NOTES .LP The return values for all of these functions are declared in the <lber.h> header file. .SH SEE ALSO .BR lber-decode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 289 stdin PK דc\ ȵ�� � man/man3/ldap_sort_entries.3nu �[��� .lf 1 stdin .TH LDAP_SORT 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_sort_entries, ldap_sort_values, ldap_sort_strcasecmp \- LDAP sorting routines (deprecated) .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH DESCRIPTION The .BR ldap_sort_entries (), .BR ldap_sort_values (), and .BR ldap_sort_strcasecmp () are deprecated. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 18 stdin .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 22 stdin PK ؓc\a��j j man/man3/ldap_count_entries.3nu �[��� .lf 1 stdin .TH LDAP_FIRST_ENTRY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_first_entry, ldap_next_entry, ldap_count_entries \- LDAP result entry parsing and counting routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_count_entries( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry ) .SH DESCRIPTION .LP These routines are used to parse results received from .BR ldap_result (3) or the synchronous LDAP search operation routines .BR ldap_search_s (3) and .BR ldap_search_st (3). .LP The .B ldap_first_entry() routine is used to retrieve the first entry in a chain of search results. It takes the \fIresult\fP as returned by a call to .BR ldap_result (3) or .BR ldap_search_s (3) or .BR ldap_search_st (3) and returns a pointer to the first entry in the result. .LP This pointer should be supplied on a subsequent call to .B ldap_next_entry() to get the next entry, the result of which should be supplied to the next call to .BR ldap_next_entry() , etc. .B ldap_next_entry() will return NULL when there are no more entries. The entries returned from these calls are used in calls to the routines described in .BR ldap_get_dn (3), .BR ldap_first_attribute (3), .BR ldap_get_values (3), etc. .LP A count of the number of entries in the search result can be obtained by calling .BR ldap_count_entries() . .SH ERRORS If an error occurs in .B ldap_first_entry() or .BR ldap_next_entry() , NULL is returned and the ld_errno field in the \fIld\fP parameter is set to indicate the error. If an error occurs in .BR ldap_count_entries() , -1 is returned, and .B ld_errno is set appropriately. See .BR ldap_error (3) for a description of possible error codes. .SH SEE ALSO .BR ldap (3), .BR ldap_result (3), .BR ldap_search (3), .BR ldap_first_attribute (3), .BR ldap_get_values (3), .BR ldap_get_dn (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 81 stdin PK ٓc\%�&}. . man/man3/ldap_dup.3nu �[��� .lf 1 stdin .TH LDAP_OPEN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_dup, ldap_destroy, \- Duplicate and destroy LDAP session handles .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B LDAP *ldap_dup( .RS .ft B LDAP *\fIold\fB ); .RE .LP .ft B int ldap_destroy( .RS .ft B LDAP *\fIold\fB ); .RE .SH DESCRIPTION .LP .B ldap_dup() duplicates an existing LDAP .RB ( "LDAP *" ) session handle. The new session handle may be used concurrently with the original session handle. In a threaded environment, different threads may execute concurrent requests on the same connection/session without fear of contamination. Each session handle manages its own private error results. .LP .B ldap_destroy() destroys an existing session handle. .LP The .B ldap_dup() and .B ldap_destroy() functions are used in conjunction with a "thread safe" version of .B libldap .RB ( libldap_r ) to enable operation thread safe API calls, so that a single session may be simultaneously used across multiple threads with consistent error handling. .LP When a session is created through the use of one of the session creation functions including .BR ldap_open (3), .BR ldap_init (3), .BR ldap_initialize (3) or .BR ldap_init_fd (3) an .B "LDAP *" session handle is returned to the application. The session handle may be shared amongst threads, however the error codes are unique to a session handle. Multiple threads performing different operations using the same session handle will result in inconsistent error codes and return values. .LP To prevent this confusion, .B ldap_dup() is used duplicate an existing session handle so that multiple threads can share the session, and maintain consistent error information and results. .LP The message queues for a session are shared between sibling session handles. Results of operations on a sibling session handles are accessible to all the sibling session handles. Applications desiring results associated with a specific operation should provide the appropriate msgid to .BR ldap_result() . Applications should avoid calling .B ldap_result() with .B LDAP_RES_ANY as that may "steal" and return results in the calling thread that another operation in a different thread, using a different session handle, may require to complete. .LP When .B ldap_unbind() is called on a session handle with siblings, all the siblings become invalid. .LP Siblings must be destroyed using .BR ldap_destroy() . Session handle resources associated with the original .RB ( "LDAP *" ) will be freed when the last session handle is destroyed or when .B ldap_unbind() is called, if no other session handles currently exist. .SH ERRORS If an error occurs, .B ldap_dup() will return NULL and .I errno should be set appropriately. .B ldap_destroy() will directly return the LDAP code associated to the error (or .I LDAP_SUCCESS in case of success); .I errno should be set as well whenever appropriate. .SH SEE ALSO .BR ldap_open (3), .BR ldap_init (3), .BR ldap_initialize (3), .BR ldap_init_fd (3), .BR errno (3) .SH ACKNOWLEDGEMENTS This work is based on the previously proposed .B LDAP C API Concurrency Extensions draft .BR ( draft-zeilenga-ldap-c-api-concurrency-00.txt ) effort. .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 127 stdin PK ړc\�T man/man3/lber-memory.3nu �[��� .lf 1 stdin .TH LBER_MEMORY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_memalloc, ber_memcalloc, ber_memrealloc, ber_memfree, ber_memvfree \- OpenLDAP LBER memory allocators .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "void *ber_memalloc(ber_len_t " bytes ");" .LP .BI "void *ber_memcalloc(ber_len_t " nelems ", ber_len_t " bytes ");" .LP .BI "void *ber_memrealloc(void *" ptr ", ber_len_t " bytes ");" .LP .BI "void ber_memfree(void *" ptr ");" .LP .BI "void ber_memvfree(void **" vec ");" .SH DESCRIPTION .LP These routines are used to allocate/deallocate memory used/returned by the Lightweight BER library as required by .BR lber-encode (3) and .BR lber-decode (3). .BR ber_memalloc (), .BR ber_memcalloc (), .BR ber_memrealloc (), and .BR ber_memfree () are used exactly like the standard .BR malloc (3), .BR calloc (3), .BR realloc (3), and .BR free (3) routines, respectively. The .BR ber_memvfree () routine is used to free a dynamically allocated array of pointers to arbitrary dynamically allocated objects. .SH SEE ALSO .BR lber-decode (3), .BR lber-encode (3), .BR lber-types (3) .LP .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 50 stdin PK ړc\��1ܽ � man/man3/ldap_controls_dup.3nu �[��� .lf 1 stdin .TH LDAP_CONTROLS 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_control_create, ldap_control_find, ldap_control_dup, ldap_controls_dup, ldap_control_free, ldap_controls_free \- LDAP control manipulation routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "int ldap_control_create(const char *" oid ", int " iscritical ", struct berval *" value ", int " dupval ", LDAPControl **" ctrlp ");" .LP .BI "LDAPControl *ldap_control_find( const char *" oid ", LDAPControl **" ctrls ", LDAPControl ***" nextctrlp ");" .LP .BI "LDAPControl *ldap_control_dup(LDAPControl *" ctrl ");" .LP .BI "LDAPControl **ldap_controls_dup(LDAPControl **" ctrls ");" .LP .BI "void ldap_control_free(LDAPControl *" ctrl ");" .LP .BI "void ldap_controls_free(LDAPControl **" ctrls ");" .SH DESCRIPTION These routines are used to manipulate structures used for LDAP controls. .BR ldap_control_create () creates a control with the specified .I OID using the contents of the .I value parameter for the control value, if any. The content of .I value is duplicated if .I dupval is non-zero. The .I iscritical parameter must be non-zero for a critical control. The created control is returned in the .I ctrlp parameter. The routine returns .B LDAP_SUCCESS on success or some other error code on failure. The content of .IR value , for supported control types, can be prepared using helpers provided by this implementation of libldap, usually in the form .BR "ldap_create_<control name>_control_value" (). Otherwise, it can be BER-encoded using the functionalities of liblber. .BR ldap_control_find () searches the NULL-terminated .I ctrls array for a control whose OID matches the .I oid parameter. The routine returns a pointer to the control if found, NULL otherwise. If the parameter .I nextctrlp is not NULL, on return it will point to the next control in the array, and can be passed to the .BR ldap_control_find () routine for subsequent calls, to find further occurrences of the same control type. The use of this function is discouraged; the recommended way of handling controls in responses consists in going through the array of controls, dealing with each of them in the returned order, since it could matter. .BR ldap_control_dup () duplicates an individual control structure, and .BR ldap_controls_dup () duplicates a NULL-terminated array of controls. .BR ldap_control_free () frees an individual control structure, and .BR ldap_controls_free () frees a NULL-terminated array of controls. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 85 stdin PK ۓc\�� �. �. man/man3/ldap_unbind_ext_s.3nu �[��� .lf 1 stdin .TH LDAP_BIND 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_bind, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_sasl_bind, ldap_sasl_bind_s, ldap_sasl_interactive_bind_s, ldap_parse_sasl_bind_result, ldap_unbind, ldap_unbind_s, ldap_unbind_ext, ldap_unbind_ext_s, ldap_set_rebind_proc \- LDAP bind routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .BI "int ldap_bind(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_bind_s(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_simple_bind(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_simple_bind_s(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_sasl_bind(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], int *" msgidp ");" .RE .LP .BI "int ldap_sasl_bind_s(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], struct berval **" servercredp ");" .RE .LP .BI "int ldap_parse_sasl_bind_result(LDAP *" ld ", LDAPMessage *" res "," .RS .BI "struct berval **" servercredp ", int " freeit ");" .RE .LP .BI "int ldap_sasl_interactive_bind_s(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ");" .RE .LP .BI "int ldap_sasl_interactive_bind(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ", LDAPMessage *" result "," .BI "const char **" rmechp ", int *" msgidp ");" .RE .LP .BI "int (LDAP_SASL_INTERACT_PROC)(LDAP *" ld ", unsigned " flags ", void *" defaults ", void *" sasl_interact ");" .LP .BI "int ldap_unbind(LDAP *" ld ");" .LP .BI "int ldap_unbind_s(LDAP *" ld ");" .LP .BI "int ldap_unbind_ext(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_unbind_ext_s(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_set_rebind_proc (LDAP *" ld ", LDAP_REBIND_PROC *" ldap_proc ", void *" params ");" .LP .BI "int (LDAP_REBIND_PROC)(LDAP *" ld ", LDAP_CONST char *" url ", ber_tag_t " request ", ber_int_t " msgid ", void *" params ");" .SH DESCRIPTION .LP These routines provide various interfaces to the LDAP bind operation. After an association with an LDAP server is made using .BR ldap_init (3), an LDAP bind operation should be performed before other operations are attempted over the connection. An LDAP bind is required when using Version 2 of the LDAP protocol; it is optional for Version 3 but is usually needed due to security considerations. .LP There are three types of bind calls, ones providing simple authentication, ones providing SASL authentication, and general routines capable of doing either simple or SASL authentication. .LP .B SASL (Simple Authentication and Security Layer) can negotiate one of many different kinds of authentication. Both synchronous and asynchronous versions of each variant of the bind call are provided. All routines take \fIld\fP as their first parameter, as returned from .BR ldap_init (3). .SH SIMPLE AUTHENTICATION The simplest form of the bind call is .BR ldap_simple_bind_s() . It takes the DN to bind as in \fIwho\fP, and the userPassword associated with the entry in \fIpasswd\fP. It returns an LDAP error indication (see .BR ldap_error (3)). The .B ldap_simple_bind() call is asynchronous, taking the same parameters but only initiating the bind operation and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The .B ldap_sasl_bind_s() and asynchronous .B ldap_sasl_bind() functions can also be used to make a simple bind by using LDAP_SASL_SIMPLE as the SASL mechanism. .SH GENERAL AUTHENTICATION The .B ldap_bind() and .B ldap_bind_s() routines can be used when the authentication method to use needs to be selected at runtime. They both take an extra \fImethod\fP parameter selecting the authentication method to use. It should be set to LDAP_AUTH_SIMPLE to select simple authentication. .B ldap_bind() returns the message id of the request it initiates. .B ldap_bind_s() returns an LDAP error indication. .SH SASL AUTHENTICATION For SASL binds the server always ignores any provided DN, so the .I dn parameter should always be NULL. .BR ldap_sasl_bind_s () sends a single SASL bind request with the given SASL .I mechanism and credentials in the .I cred parameter. The format of the credentials depends on the particular SASL mechanism in use. For mechanisms that provide mutual authentication the server's credentials will be returned in the .I servercredp parameter. The routine returns an LDAP error indication (see .BR ldap_error (3)). The .BR ldap_sasl_bind () call is asynchronous, taking the same parameters but only sending the request and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The result must be additionally parsed by .BR ldap_parse_sasl_bind_result () to obtain any server credentials sent from the server. .LP Many SASL mechanisms require multiple message exchanges to perform a complete authentication. Applications should generally use .BR ldap_sasl_interactive_bind_s () rather than calling the basic .BR ldap_sasl_bind () functions directly. The .I mechs parameter should contain a space-separated list of candidate mechanisms to use. If this parameter is NULL or empty the library will query the supportedSASLMechanisms attribute from the server's rootDSE for the list of SASL mechanisms the server supports. The .I flags parameter controls the interaction used to retrieve any necessary SASL authentication parameters and should be one of: .TP LDAP_SASL_AUTOMATIC use defaults if available, prompt otherwise .TP LDAP_SASL_INTERACTIVE always prompt .TP LDAP_SASL_QUIET never prompt .LP The .I interact function uses the provided .I defaults to handle requests from the SASL library for particular authentication parameters. There is no defined format for the .I defaults information; it is up to the caller to use whatever format is appropriate for the supplied .I interact function. The .I sasl_interact parameter comes from the underlying SASL library. When used with Cyrus SASL this is an array of .B sasl_interact_t structures. The Cyrus SASL library will prompt for a variety of inputs, including: .TP SASL_CB_GETREALM the realm for the authentication attempt .TP SASL_CB_AUTHNAME the username to authenticate .TP SASL_CB_PASS the password for the provided username .TP SASL_CB_USER the username to use for proxy authorization .TP SASL_CB_NOECHOPROMPT generic prompt for input with input echoing disabled .TP SASL_CB_ECHOPROMPT generic prompt for input with input echoing enabled .TP SASL_CB_LIST_END indicates the end of the array of prompts .LP See the Cyrus SASL documentation for more details. .LP Applications which need to manage connections asynchronously may use .BR ldap_sasl_interactive_bind () instead of the synchronous version. A valid mechs parameter must be supplied, otherwise the library will be forced to query the server for a list of supported mechanisms, and this query will be performed synchronously. The other parameters are the same as for the synchronous function, with three additional parameters. The actual SASL mechanism that was used, and the message ID for use with .BR ldap_result () will be returned in rmechp and msgidp, respectively. The value in rmechp must not be modified by the caller and must be passed back on each subsequent call. The message obtained from .BR ldap_result () must be passed in the result parameter. This parameter must be NULL when initiating a new Bind. The caller must free the result message after each call using .BR ldap_msgfree (). The .BR ldap_sasl_interactive_bind () function returns an LDAP result code. If the code is LDAP_SASL_BIND_IN_PROGRESS then the Bind is not complete yet, and this function must be called again with the next result from the server. .SH REBINDING .LP The .B ldap_set_rebind_proc function() sets the process to use for binding when an operation returns a referral. This function is used when an application needs to bind to another server in order to follow a referral or search continuation reference. .LP The function takes \fIld\fP, the \fIrebind\fP function, and the \fIparams\fP, the arbitrary data like state information which the client might need to properly rebind. The LDAP_OPT_REFERRALS option in the \fIld\fP must be set to ON for the libraries to use the rebind function. Use the .BR ldap_set_option function to set the value. .LP The rebind function parameters are as follows: .LP The \fIld\fP parameter must be used by the application when binding to the referred server if the application wants the libraries to follow the referral. .LP The \fIurl\fP parameter points to the URL referral string received from the LDAP server. The LDAP application can use the .BR ldap_url_parse (3) function to parse the string into its components. .LP The \fIrequest\fP parameter specifies the type of request that generated the referral. .LP The \fImsgid\fP parameter specifies the message ID of the request generating the referral. .LP The \fIparams\fP parameter is the same value as passed originally to the .BR ldap_set_rebind_proc () function. .LP The LDAP libraries set all the parameters when they call the rebind function. The application should not attempt to free either the ld or the url structures in the rebind function. .LP The application must supply to the rebind function the required authentication information such as, user name, password, and certificates. The rebind function must use a synchronous bind method. .SH UNBINDING The .B ldap_unbind() call is used to unbind from the directory, terminate the current association, and free the resources contained in the \fIld\fP structure. Once it is called, the connection to the LDAP server is closed, and the \fIld\fP structure is invalid. The .B ldap_unbind_s() call is just another name for .BR ldap_unbind() ; both of these calls are synchronous in nature. .LP The .B ldap_unbind_ext() and .B ldap_unbind_ext_s() allows the operations to specify controls. .SH ERRORS Asynchronous routines will return \-1 in case of error, setting the \fIld_errno\fP parameter of the \fIld\fP structure. Synchronous routines return whatever \fIld_errno\fP is set to. See .BR ldap_error (3) for more information. .SH NOTES If an anonymous bind is sufficient for the application, the rebind process need not be provided. The LDAP libraries with the LDAP_OPT_REFERRALS option set to ON (default value) will automatically follow referrals using an anonymous bind. .LP If the application needs stronger authentication than an anonymous bind, you need to provide a rebind process for that authentication method. The bind method must be synchronous. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_open (3), .BR ldap_set_option (3), .BR ldap_url_parse (3) .B RFC 4422 (http://www.rfc-editor.org), .B Cyrus SASL (http://asg.web.cmu.edu/sasl/) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 335 stdin PK ܓc\�� �. �. man/man3/ldap_simple_bind_s.3nu �[��� .lf 1 stdin .TH LDAP_BIND 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_bind, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_sasl_bind, ldap_sasl_bind_s, ldap_sasl_interactive_bind_s, ldap_parse_sasl_bind_result, ldap_unbind, ldap_unbind_s, ldap_unbind_ext, ldap_unbind_ext_s, ldap_set_rebind_proc \- LDAP bind routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .BI "int ldap_bind(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_bind_s(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_simple_bind(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_simple_bind_s(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_sasl_bind(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], int *" msgidp ");" .RE .LP .BI "int ldap_sasl_bind_s(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], struct berval **" servercredp ");" .RE .LP .BI "int ldap_parse_sasl_bind_result(LDAP *" ld ", LDAPMessage *" res "," .RS .BI "struct berval **" servercredp ", int " freeit ");" .RE .LP .BI "int ldap_sasl_interactive_bind_s(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ");" .RE .LP .BI "int ldap_sasl_interactive_bind(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ", LDAPMessage *" result "," .BI "const char **" rmechp ", int *" msgidp ");" .RE .LP .BI "int (LDAP_SASL_INTERACT_PROC)(LDAP *" ld ", unsigned " flags ", void *" defaults ", void *" sasl_interact ");" .LP .BI "int ldap_unbind(LDAP *" ld ");" .LP .BI "int ldap_unbind_s(LDAP *" ld ");" .LP .BI "int ldap_unbind_ext(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_unbind_ext_s(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_set_rebind_proc (LDAP *" ld ", LDAP_REBIND_PROC *" ldap_proc ", void *" params ");" .LP .BI "int (LDAP_REBIND_PROC)(LDAP *" ld ", LDAP_CONST char *" url ", ber_tag_t " request ", ber_int_t " msgid ", void *" params ");" .SH DESCRIPTION .LP These routines provide various interfaces to the LDAP bind operation. After an association with an LDAP server is made using .BR ldap_init (3), an LDAP bind operation should be performed before other operations are attempted over the connection. An LDAP bind is required when using Version 2 of the LDAP protocol; it is optional for Version 3 but is usually needed due to security considerations. .LP There are three types of bind calls, ones providing simple authentication, ones providing SASL authentication, and general routines capable of doing either simple or SASL authentication. .LP .B SASL (Simple Authentication and Security Layer) can negotiate one of many different kinds of authentication. Both synchronous and asynchronous versions of each variant of the bind call are provided. All routines take \fIld\fP as their first parameter, as returned from .BR ldap_init (3). .SH SIMPLE AUTHENTICATION The simplest form of the bind call is .BR ldap_simple_bind_s() . It takes the DN to bind as in \fIwho\fP, and the userPassword associated with the entry in \fIpasswd\fP. It returns an LDAP error indication (see .BR ldap_error (3)). The .B ldap_simple_bind() call is asynchronous, taking the same parameters but only initiating the bind operation and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The .B ldap_sasl_bind_s() and asynchronous .B ldap_sasl_bind() functions can also be used to make a simple bind by using LDAP_SASL_SIMPLE as the SASL mechanism. .SH GENERAL AUTHENTICATION The .B ldap_bind() and .B ldap_bind_s() routines can be used when the authentication method to use needs to be selected at runtime. They both take an extra \fImethod\fP parameter selecting the authentication method to use. It should be set to LDAP_AUTH_SIMPLE to select simple authentication. .B ldap_bind() returns the message id of the request it initiates. .B ldap_bind_s() returns an LDAP error indication. .SH SASL AUTHENTICATION For SASL binds the server always ignores any provided DN, so the .I dn parameter should always be NULL. .BR ldap_sasl_bind_s () sends a single SASL bind request with the given SASL .I mechanism and credentials in the .I cred parameter. The format of the credentials depends on the particular SASL mechanism in use. For mechanisms that provide mutual authentication the server's credentials will be returned in the .I servercredp parameter. The routine returns an LDAP error indication (see .BR ldap_error (3)). The .BR ldap_sasl_bind () call is asynchronous, taking the same parameters but only sending the request and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The result must be additionally parsed by .BR ldap_parse_sasl_bind_result () to obtain any server credentials sent from the server. .LP Many SASL mechanisms require multiple message exchanges to perform a complete authentication. Applications should generally use .BR ldap_sasl_interactive_bind_s () rather than calling the basic .BR ldap_sasl_bind () functions directly. The .I mechs parameter should contain a space-separated list of candidate mechanisms to use. If this parameter is NULL or empty the library will query the supportedSASLMechanisms attribute from the server's rootDSE for the list of SASL mechanisms the server supports. The .I flags parameter controls the interaction used to retrieve any necessary SASL authentication parameters and should be one of: .TP LDAP_SASL_AUTOMATIC use defaults if available, prompt otherwise .TP LDAP_SASL_INTERACTIVE always prompt .TP LDAP_SASL_QUIET never prompt .LP The .I interact function uses the provided .I defaults to handle requests from the SASL library for particular authentication parameters. There is no defined format for the .I defaults information; it is up to the caller to use whatever format is appropriate for the supplied .I interact function. The .I sasl_interact parameter comes from the underlying SASL library. When used with Cyrus SASL this is an array of .B sasl_interact_t structures. The Cyrus SASL library will prompt for a variety of inputs, including: .TP SASL_CB_GETREALM the realm for the authentication attempt .TP SASL_CB_AUTHNAME the username to authenticate .TP SASL_CB_PASS the password for the provided username .TP SASL_CB_USER the username to use for proxy authorization .TP SASL_CB_NOECHOPROMPT generic prompt for input with input echoing disabled .TP SASL_CB_ECHOPROMPT generic prompt for input with input echoing enabled .TP SASL_CB_LIST_END indicates the end of the array of prompts .LP See the Cyrus SASL documentation for more details. .LP Applications which need to manage connections asynchronously may use .BR ldap_sasl_interactive_bind () instead of the synchronous version. A valid mechs parameter must be supplied, otherwise the library will be forced to query the server for a list of supported mechanisms, and this query will be performed synchronously. The other parameters are the same as for the synchronous function, with three additional parameters. The actual SASL mechanism that was used, and the message ID for use with .BR ldap_result () will be returned in rmechp and msgidp, respectively. The value in rmechp must not be modified by the caller and must be passed back on each subsequent call. The message obtained from .BR ldap_result () must be passed in the result parameter. This parameter must be NULL when initiating a new Bind. The caller must free the result message after each call using .BR ldap_msgfree (). The .BR ldap_sasl_interactive_bind () function returns an LDAP result code. If the code is LDAP_SASL_BIND_IN_PROGRESS then the Bind is not complete yet, and this function must be called again with the next result from the server. .SH REBINDING .LP The .B ldap_set_rebind_proc function() sets the process to use for binding when an operation returns a referral. This function is used when an application needs to bind to another server in order to follow a referral or search continuation reference. .LP The function takes \fIld\fP, the \fIrebind\fP function, and the \fIparams\fP, the arbitrary data like state information which the client might need to properly rebind. The LDAP_OPT_REFERRALS option in the \fIld\fP must be set to ON for the libraries to use the rebind function. Use the .BR ldap_set_option function to set the value. .LP The rebind function parameters are as follows: .LP The \fIld\fP parameter must be used by the application when binding to the referred server if the application wants the libraries to follow the referral. .LP The \fIurl\fP parameter points to the URL referral string received from the LDAP server. The LDAP application can use the .BR ldap_url_parse (3) function to parse the string into its components. .LP The \fIrequest\fP parameter specifies the type of request that generated the referral. .LP The \fImsgid\fP parameter specifies the message ID of the request generating the referral. .LP The \fIparams\fP parameter is the same value as passed originally to the .BR ldap_set_rebind_proc () function. .LP The LDAP libraries set all the parameters when they call the rebind function. The application should not attempt to free either the ld or the url structures in the rebind function. .LP The application must supply to the rebind function the required authentication information such as, user name, password, and certificates. The rebind function must use a synchronous bind method. .SH UNBINDING The .B ldap_unbind() call is used to unbind from the directory, terminate the current association, and free the resources contained in the \fIld\fP structure. Once it is called, the connection to the LDAP server is closed, and the \fIld\fP structure is invalid. The .B ldap_unbind_s() call is just another name for .BR ldap_unbind() ; both of these calls are synchronous in nature. .LP The .B ldap_unbind_ext() and .B ldap_unbind_ext_s() allows the operations to specify controls. .SH ERRORS Asynchronous routines will return \-1 in case of error, setting the \fIld_errno\fP parameter of the \fIld\fP structure. Synchronous routines return whatever \fIld_errno\fP is set to. See .BR ldap_error (3) for more information. .SH NOTES If an anonymous bind is sufficient for the application, the rebind process need not be provided. The LDAP libraries with the LDAP_OPT_REFERRALS option set to ON (default value) will automatically follow referrals using an anonymous bind. .LP If the application needs stronger authentication than an anonymous bind, you need to provide a rebind process for that authentication method. The bind method must be synchronous. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_open (3), .BR ldap_set_option (3), .BR ldap_url_parse (3) .B RFC 4422 (http://www.rfc-editor.org), .B Cyrus SASL (http://asg.web.cmu.edu/sasl/) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 335 stdin PK ݓc\ ݴ� man/man3/ldap_url_parse.3nu �[��� .lf 1 stdin .TH LDAP_URL 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_is_ldap_url, ldap_url_parse, ldap_free_urldesc \- LDAP Uniform Resource Locator routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_is_ldap_url( const char *url ) .LP .ft B int ldap_url_parse( const char *url, LDAPURLDesc **ludpp ) .LP typedef struct ldap_url_desc { char * lud_scheme; /* URI scheme */ char * lud_host; /* LDAP host to contact */ int lud_port; /* port on host */ char * lud_dn; /* base for search */ char ** lud_attrs; /* list of attributes */ int lud_scope; /* a LDAP_SCOPE_... value */ char * lud_filter; /* LDAP search filter */ char ** lud_exts; /* LDAP extensions */ int lud_crit_exts; /* true if any extension is critical */ /* may contain additional fields for internal use */ } LDAPURLDesc; .LP .ft B void ldap_free_urldesc( LDAPURLDesc *ludp ); .SH DESCRIPTION These routines support the use of LDAP URLs (Uniform Resource Locators) as detailed in RFC 4516. LDAP URLs look like this: .nf \fBldap://\fP\fIhostport\fP\fB/\fP\fIdn\fP[\fB?\fP\fIattrs\fP[\fB?\fP\fIscope\fP[\fB?\fP\fIfilter\fP[\fB?\fP\fIexts\fP]]]] where: \fIhostport\fP is a host name with an optional ":portnumber" \fIdn\fP is the search base \fIattrs\fP is a comma separated list of attributes to request \fIscope\fP is one of these three strings: base one sub (default=base) \fIfilter\fP is filter \fIexts\fP are recognized set of LDAP and/or API extensions. Example: ldap://ldap.example.net/dc=example,dc=net?cn,sn?sub?(cn=*) .fi .LP URLs that are wrapped in angle-brackets and/or preceded by "URL:" are also tolerated. Alternative LDAP schemes such as ldaps:// and ldapi:// may be parsed using the below routines as well. .LP .B ldap_is_ldap_url() returns a non-zero value if \fIurl\fP looks like an LDAP URL (as opposed to some other kind of URL). It can be used as a quick check for an LDAP URL; the .B ldap_url_parse() routine should be used if a more thorough check is needed. .LP .B ldap_url_parse() breaks down an LDAP URL passed in \fIurl\fP into its component pieces. If successful, zero is returned, an LDAP URL description is allocated, filled in, and \fIludpp\fP is set to point to it. If an error occurs, a non-zero URL error code is returned. .LP .B ldap_free_urldesc() should be called to free an LDAP URL description that was obtained from a call to .B ldap_url_parse(). .SH SEE ALSO .nf .BR ldap (3) .BR "RFC 4516" " <http://www.rfc-editor.org/rfc/rfc4516.txt>" .SH ACKNOWLEDGEMENTS .fi .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 84 stdin PK ݓc\�^�E/ / man/man3/ldap_parse_reference.3nu �[��� .lf 1 stdin .TH LDAP_PARSE_REFERENCE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_parse_reference \- Extract referrals and controls from a reference message .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_parse_reference( LDAP *ld, LDAPMessage *reference, char ***referralsp, LDAPControl ***serverctrlsp, int freeit ) .SH DESCRIPTION .LP The .B ldap_parse_reference() routine is used to extract referrals and controls from a reference message. The \fIreference\fP parameter is a reference message as returned by a call to .BR ldap_first_reference (3) , .BR ldap_next_reference (3) , .BR ldap_first_message (3) , .BR ldap_next_message (3) , or .BR ldap_result (3) . .LP The \fIreferralsp\fP parameter will be filled in with an allocated array of character strings. The strings are copies of the referrals contained in the parsed message. The array should be freed by calling .BR ldap_value_free (3) . If \fIreferralsp\fP is NULL, no referrals are returned. If no referrals were returned, \fI*referralsp\fP is set to NULL. .LP The \fIserverctrlsp\fP parameter will be filled in with an allocated array of controls copied from the parsed message. The array should be freed by calling .BR ldap_controls_free (3). If \fIserverctrlsp\fP is NULL, no controls are returned. If no controls were returned, \fI*serverctrlsp\fP is set to NULL. .LP The \fIfreeit\fP parameter determines whether the parsed message is freed or not after the extraction. Any non-zero value will make it free the message. The .BR ldap_msgfree (3) routine can also be used to free the message later. .SH ERRORS Upon success LDAP_SUCCESS is returned. Otherwise the values of the \fIreferralsp\fP and \fIserverctrlsp\fP parameters are undefined. .SH SEE ALSO .BR ldap (3), .BR ldap_first_reference (3), .BR ldap_first_message (3), .BR ldap_result (3), .BR ldap_get_values (3), .BR ldap_controls_free (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 62 stdin PK �c\�շY� � man/man3/ber_dupbv.3nu �[��� .lf 1 stdin .TH LBER_TYPES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_int_t, ber_uint_t, ber_len_t, ber_slen_t, ber_tag_t, struct berval, BerValue, BerVarray, BerElement, ber_bvfree, ber_bvecfree, ber_bvecadd, ber_bvarray_free, ber_bvarray_add, ber_bvdup, ber_dupbv, ber_bvstr, ber_bvstrdup, ber_str2bv, ber_alloc_t, ber_init, ber_init2, ber_free \- OpenLDAP LBER types and allocation functions .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .nf .ft B typedef impl_tag_t ber_tag_t; typedef impl_int_t ber_int_t; typedef impl_uint_t ber_uint_t; typedef impl_len_t ber_len_t; typedef impl_slen_t ber_slen_t; typedef struct berval { ber_len_t bv_len; char *bv_val; } BerValue, *BerVarray; typedef struct berelement BerElement; .ft .fi .LP .BI "void ber_bvfree(struct berval *" bv ");" .LP .BI "void ber_bvecfree(struct berval **" bvec ");" .LP .BI "void ber_bvecadd(struct berval ***" bvec ", struct berval *" bv ");" .LP .BI "void ber_bvarray_free(struct berval *" bvarray ");" .LP .BI "void ber_bvarray_add(BerVarray *" bvarray ", BerValue *" bv ");" .LP .BI "struct berval *ber_bvdup(const struct berval *" bv ");" .LP .BI "struct berval *ber_dupbv(const struct berval *" dst ", struct berval *" src ");" .LP .BI "struct berval *ber_bvstr(const char *" str ");" .LP .BI "struct berval *ber_bvstrdup(const char *" str ");" .LP .BI "struct berval *ber_str2bv(const char *" str ", ber_len_t " len ", int " dup ", struct berval *" bv ");" .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "BerElement *ber_init(struct berval *" bv ");" .LP .BI "void ber_init2(BerElement *" ber ", struct berval *" bv ", int " options ");" .LP .BI "void ber_free(BerElement *" ber ", int " freebuf ");" .SH DESCRIPTION .LP The following are the basic types and structures defined for use with the Lightweight BER library. .LP .B ber_int_t is a signed integer of at least 32 bits. It is commonly equivalent to .BR int . .B ber_uint_t is the unsigned variant of .BR ber_int_t . .LP .B ber_len_t is an unsigned integer of at least 32 bits used to represent a length. It is commonly equivalent to a .BR size_t . .B ber_slen_t is the signed variant to .BR ber_len_t . .LP .B ber_tag_t is an unsigned integer of at least 32 bits used to represent a BER tag. It is commonly equivalent to a .BR unsigned\ long . .LP The actual definitions of the integral impl_TYPE_t types are platform specific. .LP .BR BerValue , commonly used as .BR struct\ berval , is used to hold an arbitrary sequence of octets. .B bv_val points to .B bv_len octets. .B bv_val is not necessarily terminated by a NULL (zero) octet. .BR ber_bvfree () frees a BerValue, pointed to by \fIbv\fP, returned from this API. If \fIbv\fP is NULL, the routine does nothing. .LP .BR ber_bvecfree () frees an array of BerValues (and the array), pointed to by \fIbvec\fP, returned from this API. If \fIbvec\fP is NULL, the routine does nothing. .BR ber_bvecadd () appends the \fIbv\fP pointer to the \fIbvec\fP array. Space for the array is allocated as needed. The end of the array is marked by a NULL pointer. .LP .BR ber_bvarray_free () frees an array of BerValues (and the array), pointed to by \fIbvarray\fP, returned from this API. If \fIbvarray\fP is NULL, the routine does nothing. .BR ber_bvarray_add () appends the contents of the BerValue pointed to by \fIbv\fP to the \fIbvarray\fP array. Space for the new element is allocated as needed. The end of the array is marked by a BerValue with a NULL bv_val field. .LP .BR ber_bvdup () returns a copy of a BerValue. The routine returns NULL upon error (e.g. out of memory). The caller should use .BR ber_bvfree () to deallocate the resulting BerValue. .BR ber_dupbv () copies a BerValue from \fIsrc\fP to \fIdst\fP. If \fIdst\fP is NULL a new BerValue will be allocated to hold the copy. The routine returns NULL upon error, otherwise it returns a pointer to the copy. If \fIdst\fP is NULL the caller should use .BR ber_bvfree () to deallocate the resulting BerValue, otherwise .BR ber_memfree () should be used to deallocate the \fIdst->bv_val\fP. (The .BR ber_bvdup () function is internally implemented as ber_dupbv(NULL, bv). .BR ber_bvdup () is provided only for compatibility with an expired draft of the LDAP C API; .BR ber_dupbv () is the preferred interface.) .LP .BR ber_bvstr () returns a BerValue containing the string pointed to by \fIstr\fP. .BR ber_bvstrdup () returns a BerValue containing a copy of the string pointed to by \fIstr\fP. .BR ber_str2bv () returns a BerValue containing the string pointed to by \fIstr\fP, whose length may be optionally specified in \fIlen\fP. If \fIdup\fP is non-zero, the BerValue will contain a copy of \fIstr\fP. If \fIlen\fP is zero, the number of bytes to copy will be determined by .BR strlen (3), otherwise \fIlen\fP bytes will be copied. If \fIbv\fP is non-NULL, the result will be stored in the given BerValue, otherwise a new BerValue will be allocated to store the result. NOTE: Both .BR ber_bvstr () and .BR ber_bvstrdup () are implemented as macros using .BR ber_str2bv () in this version of the library. .LP .B BerElement is an opaque structure used to maintain state information used in encoding and decoding. .BR ber_alloc_t () is used to create an empty BerElement structure. If .B LBER_USE_DER is specified for the .I options parameter then data lengths for data written to the BerElement will be encoded in the minimal number of octets required, otherwise they will always be written as four byte values. .BR ber_init () creates a BerElement structure that is initialized with a copy of the data in its .I bv parameter. .BR ber_init2 () initializes an existing BerElement .I ber using the data in the .I bv parameter. The data is referenced directly, not copied. The .I options parameter is the same as for .BR ber_alloc_t (). .BR ber_free () frees a BerElement pointed to by \fIber\fP. If \fIber\fP is NULL, the routine does nothing. If \fIfreebuf\fP is zero, the internal buffer is not freed. .SH SEE ALSO .BR lber-encode (3), .BR lber-decode (3), .BR lber-memory (3) .LP .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 189 stdin PK �c\��MK$ K$ man/man3/ber_put_enum.3nu �[��� .lf 1 stdin .TH LBER_ENCODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_alloc_t, ber_flush, ber_flush2, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring, ber_put_string, ber_put_null, ber_put_boolean, ber_put_bitstring, ber_start_seq, ber_start_set, ber_put_seq, ber_put_set \- OpenLDAP LBER simplified Basic Encoding Rules library routines for encoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_flush2(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_printf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "int ber_put_int(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_enum(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_ostring(BerElement *" ber ", const char *" str ", ber_len_t " len ", ber_tag_t " tag ");" .LP .BI "int ber_put_string(BerElement *" ber ", const char *" str ", ber_tag_t " tag ");" .LP .BI "int ber_put_null(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_boolean(BerElement *" ber ", ber_int_t " bool ", ber_tag_t " tag ");" .LP .BI "int ber_put_bitstring(BerElement *" ber ", const char *" str ", ber_len_t " blen ", ber_tag_t " tag ");" .LP .BI "int ber_start_seq(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_start_set(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_seq(BerElement *" ber ");" .LP .BI "int ber_put_set(BerElement *" ber ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the encoding routines in the lber library. See .BR lber-decode (3) for details on the corresponding decoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_alloc_t () to allocate a BER element for encoding, .BR ber_printf () to do the actual encoding, and .BR ber_flush2 () to actually write the element. The other routines are provided for those applications that need more control than .BR ber_printf () provides. In general, these routines return the length of the element encoded, or \-1 if an error occurred. .LP The .BR ber_alloc_t () routine is used to allocate a new BER element. It should be called with an argument of LBER_USE_DER. .LP The .BR ber_flush2 () routine is used to actually write the element to a socket (or file) descriptor, once it has been fully encoded (using .BR ber_printf () and friends). See .BR lber-sockbuf (3) for more details on the Sockbuf implementation of the \fIsb\fP parameter. If the \fIfreeit\fP parameter is non-zero, the supplied \fIber\fP will be freed. If \fILBER_FLUSH_FREE_ON_SUCCESS\fP is used, the \fIber\fP is only freed when successfully flushed, otherwise it is left intact; if \fILBER_FLUSH_FREE_ON_ERROR\fP is used, the \fIber\fP is only freed when an error occurs, otherwise it is left intact; if \fILBER_FLUSH_FREE_ALWAYS\fP is used, the \fIber\fP is freed anyway. This function differs from the original .BR ber_flush (3) function, whose behavior corresponds to that indicated for \fILBER_FLUSH_FREE_ON_SUCCESS\fP. Note that in the future, the behavior of .BR ber_flush (3) with \fIfreeit\fP non-zero might change into that of .BR ber_flush2 (3) with \fIfreeit\fP set to \fILBER_FLUSH_FREE_ALWAYS\fP. .LP The .BR ber_printf () routine is used to encode a BER element in much the same way that .BR sprintf (3) works. One important difference, though, is that some state information is kept with the \fIber\fP parameter so that multiple calls can be made to .BR ber_printf () to append things to the end of the BER element. .BR Ber_printf () writes to \fIber\fP, a pointer to a BerElement such as returned by .BR ber_alloc_t (). It interprets and formats its arguments according to the format string \fIfmt\fP. The format string can contain the following characters: .RS .LP .TP 3 .B b Boolean. An ber_int_t parameter should be supplied. A boolean element is output. .TP .B e Enumeration. An ber_int_t parameter should be supplied. An enumeration element is output. .TP .B i Integer. An ber_int_t parameter should be supplied. An integer element is output. .TP .B B Bitstring. A char * pointer to the start of the bitstring is supplied, followed by the number of bits in the bitstring. A bitstring element is output. .TP .B n Null. No parameter is required. A null element is output. .TP .B o Octet string. A char * is supplied, followed by the length of the string pointed to. An octet string element is output. .TP .B O Octet string. A struct berval * is supplied. An octet string element is output. .TP .B s Octet string. A null-terminated string is supplied. An octet string element is output, not including the trailing NULL octet. .TP .B t Tag. A ber_tag_t specifying the tag to give the next element is provided. This works across calls. .TP .B v Several octet strings. A null-terminated array of char *'s is supplied. Note that a construct like '{v}' is required to get an actual SEQUENCE OF octet strings. .TP .B V Several octet strings. A null-terminated array of struct berval *'s is supplied. Note that a construct like '{V}' is required to get an actual SEQUENCE OF octet strings. .TP .B W Several octet strings. An array of struct berval's is supplied. The array is terminated by a struct berval with a NULL bv_val. Note that a construct like '{W}' is required to get an actual SEQUENCE OF octet strings. .TP .B { Begin sequence. No parameter is required. .TP .B } End sequence. No parameter is required. .TP .B [ Begin set. No parameter is required. .TP .B ] End set. No parameter is required. .RE .LP The .BR ber_put_int () routine writes the integer element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_enum () routine writes the enumeration element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_boolean () routine writes the boolean value given by \fIbool\fP to the BER element. .LP The .BR ber_put_bitstring () routine writes \fIblen\fP bits starting at \fIstr\fP as a bitstring value to the given BER element. Note that \fIblen\fP is the length \fIin bits\fP of the bitstring. .LP The .BR ber_put_ostring () routine writes \fIlen\fP bytes starting at \fIstr\fP to the BER element as an octet string. .LP The .BR ber_put_string () routine writes the null-terminated string (minus the terminating '\0') to the BER element as an octet string. .LP The .BR ber_put_null () routine writes a NULL element to the BER element. .LP The .BR ber_start_seq () routine is used to start a sequence in the BER element. The .BR ber_start_set () routine works similarly. The end of the sequence or set is marked by the nearest matching call to .BR ber_put_seq () or .BR ber_put_set (), respectively. .SH EXAMPLES Assuming the following variable declarations, and that the variables have been assigned appropriately, an lber encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP can be achieved like so: .LP .nf int rc; ber_int_t scope, ali, size, time, attrsonly; char *dn, **attrs; BerElement *ber; /* ... fill in values ... */ ber = ber_alloc_t( LBER_USE_DER ); if ( ber == NULL ) { /* error */ } rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali, size, time, attrsonly, attrs ); if( rc == \-1 ) { /* error */ } else { /* success */ } .fi .SH ERRORS If an error occurs during encoding, generally these routines return \-1. .LP .SH NOTES .LP The return values for all of these functions are declared in the <lber.h> header file. .SH SEE ALSO .BR lber-decode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 289 stdin PK �c\ ȵ�� � man/man3/ldap_sort_values.3nu �[��� .lf 1 stdin .TH LDAP_SORT 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_sort_entries, ldap_sort_values, ldap_sort_strcasecmp \- LDAP sorting routines (deprecated) .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH DESCRIPTION The .BR ldap_sort_entries (), .BR ldap_sort_values (), and .BR ldap_sort_strcasecmp () are deprecated. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 18 stdin .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 22 stdin PK �c\� �q q man/man3/ldap_dnfree.3nu �[��� .lf 1 stdin .TH LDAP_GET_DN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn \- LDAP DN handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ) .LP .ft B int ldap_str2dn( const char *str, LDAPDN *dn, unsigned flags ) .LP .ft B void ldap_dnfree( LDAPDN dn ) .LP .ft B int ldap_dn2str( LDAPDN dn, char **str, unsigned flags ) .LP .ft B char **ldap_explode_dn( const char *dn, int notypes ) .LP .ft B char **ldap_explode_rdn( const char *rdn, int notypes ) .LP .ft B char *ldap_dn2ufn( const char * dn ) .LP .ft B char *ldap_dn2dcedn( const char * dn ) .LP .ft B char *ldap_dcedn2dn( const char * dn ) .LP .ft B char *ldap_dn2ad_canonical( const char * dn ) .SH DESCRIPTION These routines allow LDAP entry names (Distinguished Names, or DNs) to be obtained, parsed, converted to a user-friendly form, and tested. A DN has the form described in RFC 4414 "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names". .LP The .B ldap_get_dn() routine takes an \fIentry\fP as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3) and returns a copy of the entry's DN. Space for the DN will be obtained dynamically and should be freed by the caller using .BR ldap_memfree (3). .LP .B ldap_str2dn() parses a string representation of a distinguished name contained in .B str into its components, which are stored in .B dn as .B ldap_ava structures, arranged in .B LDAPAVA, .B LDAPRDN, and .B LDAPDN terms. Space for .B dn will be obtained dynamically and should be freed by the caller using .BR ldap_dnfree (3). The .B LDAPDN is defined as: .nf .ft B typedef struct ldap_ava { struct berval la_attr; struct berval la_value; unsigned la_flags; } LDAPAVA; typedef LDAPAVA** LDAPRDN; typedef LDAPRDN* LDAPDN; .ft .fi The attribute types and the attribute values are not normalized. The .B la_flags can be either .B LDAP_AVA_STRING or .B LDAP_AVA_BINARY, the latter meaning that the value is BER/DER encoded and thus must be represented as, quoting from RFC 4514, " ... an octothorpe character ('#' ASCII 35) followed by the hexadecimal representation of each of the bytes of the BER encoding of the X.500 AttributeValue." The .B flags parameter to .B ldap_str2dn() can be .LP .nf LDAP_DN_FORMAT_LDAPV3 LDAP_DN_FORMAT_LDAPV2 LDAP_DN_FORMAT_DCE .fi which defines what DN syntax is expected (according to RFC 4514, RFC 1779 and DCE, respectively). The format can be \fIOR\fPed to the flags .LP .nf LDAP_DN_P_NO_SPACES LDAP_DN_P_NO_SPACE_AFTER_RDN ... LDAP_DN_PEDANTIC .fi The latter is a shortcut for all the previous limitations. .LP .B LDAP_DN_P_NO_SPACES does not allow extra spaces in the dn; the default is to silently eliminate spaces around AVA separators ('='), RDN component separators ('+' for LDAPv3/LDAPv2 or ',' for DCE) and RDN separators (',' LDAPv3/LDAPv2 or '/' for DCE). .LP .B LDAP_DN_P_NO_SPACE_AFTER_RDN does not allow a single space after RDN separators. .LP .B ldap_dn2str() performs the inverse operation, yielding in .B str a string representation of .B dn. It allows the same values for .B flags as .B ldap_str2dn(), plus .LP .nf LDAP_DN_FORMAT_UFN LDAP_DN_FORMAT_AD_CANONICAL .fi for user-friendly naming (RFC 1781) and AD canonical. .LP The following routines are viewed as deprecated in favor of .B ldap_str2dn() and .BR ldap_dn2str(). They are provided to support legacy applications. .LP The .B ldap_explode_dn() routine takes a DN as returned by .B ldap_get_dn() and breaks it up into its component parts. Each part is known as a Relative Distinguished Name, or RDN. .B ldap_explode_dn() returns a NULL-terminated array, each component of which contains an RDN from the DN. The \fInotypes\fP parameter is used to request that only the RDN values be returned, not their types. For example, the DN "cn=Bob, c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob", "US", NULL }, depending on whether notypes was 0 or 1, respectively. Assertion values in RDN strings may included escaped characters. The result can be freed by calling .BR ldap_value_free (3). .LP Similarly, the .B ldap_explode_rdn() routine takes an RDN as returned by .B ldap_explode_dn(dn,0) and breaks it up into its "type=value" component parts (or just "value", if the \fInotypes\fP parameter is set). Note the value is not unescaped. The result can be freed by calling .BR ldap_value_free (3). .LP .B ldap_dn2ufn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a more user-friendly form, stripping off all type names. See "Using the Directory to Achieve User Friendly Naming" (RFC 1781) for more details on the UFN format. Due to the ambiguous nature of the format, it is generally only used for display purposes. The space for the UFN returned is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .LP .B ldap_dn2dcedn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a DCE-style DN, e.g. a string with most-significant to least significant rdns separated by slashes ('/'); rdn components are separated by commas (','). Only printable chars (e.g. LDAPv2 printable string) are allowed, at least in this implementation. .B ldap_dcedn2dn() performs the opposite operation. .B ldap_dn2ad_canonical() turns a DN into a AD canonical name, which is basically a DCE dn with attribute types omitted. The trailing domain, if present, is turned in a DNS-like domain. The space for the returned value is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .SH ERRORS If an error occurs in .BR ldap_get_dn() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .BR ldap_explode_dn() , .BR ldap_explode_rdn() , .B ldap_dn2ufn(), .B ldap_dn2dcedn(), .B ldap_dcedn2dn(), and .B ldap_dn2ad_canonical() will return NULL with .BR errno (3) set appropriately in case of trouble. .SH NOTES These routines dynamically allocate memory that the caller must free. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_first_entry (3), .BR ldap_memfree (3), .BR ldap_value_free (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 247 stdin PK �c\a��j j man/man3/ldap_next_entry.3nu �[��� .lf 1 stdin .TH LDAP_FIRST_ENTRY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_first_entry, ldap_next_entry, ldap_count_entries \- LDAP result entry parsing and counting routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_count_entries( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry ) .SH DESCRIPTION .LP These routines are used to parse results received from .BR ldap_result (3) or the synchronous LDAP search operation routines .BR ldap_search_s (3) and .BR ldap_search_st (3). .LP The .B ldap_first_entry() routine is used to retrieve the first entry in a chain of search results. It takes the \fIresult\fP as returned by a call to .BR ldap_result (3) or .BR ldap_search_s (3) or .BR ldap_search_st (3) and returns a pointer to the first entry in the result. .LP This pointer should be supplied on a subsequent call to .B ldap_next_entry() to get the next entry, the result of which should be supplied to the next call to .BR ldap_next_entry() , etc. .B ldap_next_entry() will return NULL when there are no more entries. The entries returned from these calls are used in calls to the routines described in .BR ldap_get_dn (3), .BR ldap_first_attribute (3), .BR ldap_get_values (3), etc. .LP A count of the number of entries in the search result can be obtained by calling .BR ldap_count_entries() . .SH ERRORS If an error occurs in .B ldap_first_entry() or .BR ldap_next_entry() , NULL is returned and the ld_errno field in the \fIld\fP parameter is set to indicate the error. If an error occurs in .BR ldap_count_entries() , -1 is returned, and .B ld_errno is set appropriately. See .BR ldap_error (3) for a description of possible error codes. .SH SEE ALSO .BR ldap (3), .BR ldap_result (3), .BR ldap_search (3), .BR ldap_first_attribute (3), .BR ldap_get_values (3), .BR ldap_get_dn (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 81 stdin PK �c\g�d"# "# man/man3/ldap_syntax2str.3nu �[��� .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin PK �c\����� � man/man3/ldap_count_values_len.3nu �[��� .lf 1 stdin .TH LDAP_GET_VALUES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_values, ldap_get_values_len, ldap_count_values \- LDAP attribute value handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char **ldap_get_values(ld, entry, attr) .ft LDAP *ld; LDAPMessage *entry; char *attr; .LP .ft B struct berval **ldap_get_values_len(ld, entry, attr) .ft LDAP *ld; LDAPMessage *entry; char *attr; .LP .ft B int ldap_count_values(vals) .ft char **vals; .LP .ft B int ldap_count_values_len(vals) .ft struct berval **vals; .LP .ft B void ldap_value_free(vals) .ft char **vals; .LP .ft B void ldap_value_free_len(vals) .ft struct berval **vals; .SH DESCRIPTION These routines are used to retrieve and manipulate attribute values from an LDAP entry as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3). .B ldap_get_values() takes the \fIentry\fP and the attribute \fIattr\fP whose values are desired and returns a NULL-terminated array of the attribute's values. \fIattr\fP may be an attribute type as returned from .BR ldap_first_attribute (3) or .BR ldap_next_attribute (3), or if the attribute type is known it can simply be given. .LP The number of values in the array can be counted by calling .BR ldap_count_values() . The array of values returned can be freed by calling .BR ldap_value_free() . .LP If the attribute values are binary in nature, and thus not suitable to be returned as an array of char *'s, the .B ldap_get_values_len() routine can be used instead. It takes the same parameters as .BR ldap_get_values() , but returns a NULL-terminated array of pointers to berval structures, each containing the length of and a pointer to a value. .LP The number of values in the array can be counted by calling .BR ldap_count_values_len() . The array of values returned can be freed by calling .BR ldap_value_free_len() . .SH ERRORS If an error occurs in .B ldap_get_values() or .BR ldap_get_values_len() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .SH NOTES These routines dynamically allocate memory which the caller must free using the supplied routines. .SH SEE ALSO .BR ldap (3), .BR ldap_first_entry (3), .BR ldap_first_attribute (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 103 stdin PK �c\��A man/man3/ldap_modrdn.3nu �[��� .lf 1 stdin .TH LDAP_MODRDN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_modrdn, ldap_modrdn_s, ldap_modrdn2, ldap_modrdn2_s \- Perform an LDAP modify RDN operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_modrdn(ld, dn, newrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; .LP .ft B .LP .ft B int ldap_modrdn_s(ld, dn, newrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; .LP .ft B int ldap_modrdn2(ld, dn, newrdn, deleteoldrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; int deleteoldrdn; .LP .ft B int ldap_modrdn2_s(ld, dn, newrdn, deleteoldrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; int deleteoldrdn; .SH DESCRIPTION The .B ldap_modrdn() and .B ldap_modrdn_s() routines perform an LDAP modify RDN operation. They both take \fIdn\fP, the DN of the entry whose RDN is to be changed, and \fInewrdn\fP, the new RDN to give the entry. The old RDN of the entry is never kept as an attribute of the entry. .B ldap_modrdn() is asynchronous, returning the message id of the operation it initiates. .B ldap_modrdn_s() is synchronous, returning the LDAP error code indicating the success or failure of the operation. Use of these routines is deprecated. Use the versions described below instead. .LP The .B ldap_modrdn2() and .B ldap_modrdn2_s() routines also perform an LDAP modify RDN operation, taking the same parameters as above. In addition, they both take the \fIdeleteoldrdn\fP parameter which is used as a boolean value to indicate whether the old RDN values should be deleted from the entry or not. .SH ERRORS The synchronous (_s) versions of these routines return an LDAP error code, either LDAP_SUCCESS or an error if there was trouble. The asynchronous versions return \-1 in case of trouble, setting the .B ld_errno field of \fIld\fP. See .BR ldap_error (3) for more details. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 82 stdin PK �c\g�d"# "# man/man3/ldap_syntax2name.3nu �[��� .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin PK �c\��MK$ K$ man/man3/ber_put_string.3nu �[��� .lf 1 stdin .TH LBER_ENCODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_alloc_t, ber_flush, ber_flush2, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring, ber_put_string, ber_put_null, ber_put_boolean, ber_put_bitstring, ber_start_seq, ber_start_set, ber_put_seq, ber_put_set \- OpenLDAP LBER simplified Basic Encoding Rules library routines for encoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_flush2(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_printf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "int ber_put_int(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_enum(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_ostring(BerElement *" ber ", const char *" str ", ber_len_t " len ", ber_tag_t " tag ");" .LP .BI "int ber_put_string(BerElement *" ber ", const char *" str ", ber_tag_t " tag ");" .LP .BI "int ber_put_null(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_boolean(BerElement *" ber ", ber_int_t " bool ", ber_tag_t " tag ");" .LP .BI "int ber_put_bitstring(BerElement *" ber ", const char *" str ", ber_len_t " blen ", ber_tag_t " tag ");" .LP .BI "int ber_start_seq(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_start_set(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_seq(BerElement *" ber ");" .LP .BI "int ber_put_set(BerElement *" ber ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the encoding routines in the lber library. See .BR lber-decode (3) for details on the corresponding decoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_alloc_t () to allocate a BER element for encoding, .BR ber_printf () to do the actual encoding, and .BR ber_flush2 () to actually write the element. The other routines are provided for those applications that need more control than .BR ber_printf () provides. In general, these routines return the length of the element encoded, or \-1 if an error occurred. .LP The .BR ber_alloc_t () routine is used to allocate a new BER element. It should be called with an argument of LBER_USE_DER. .LP The .BR ber_flush2 () routine is used to actually write the element to a socket (or file) descriptor, once it has been fully encoded (using .BR ber_printf () and friends). See .BR lber-sockbuf (3) for more details on the Sockbuf implementation of the \fIsb\fP parameter. If the \fIfreeit\fP parameter is non-zero, the supplied \fIber\fP will be freed. If \fILBER_FLUSH_FREE_ON_SUCCESS\fP is used, the \fIber\fP is only freed when successfully flushed, otherwise it is left intact; if \fILBER_FLUSH_FREE_ON_ERROR\fP is used, the \fIber\fP is only freed when an error occurs, otherwise it is left intact; if \fILBER_FLUSH_FREE_ALWAYS\fP is used, the \fIber\fP is freed anyway. This function differs from the original .BR ber_flush (3) function, whose behavior corresponds to that indicated for \fILBER_FLUSH_FREE_ON_SUCCESS\fP. Note that in the future, the behavior of .BR ber_flush (3) with \fIfreeit\fP non-zero might change into that of .BR ber_flush2 (3) with \fIfreeit\fP set to \fILBER_FLUSH_FREE_ALWAYS\fP. .LP The .BR ber_printf () routine is used to encode a BER element in much the same way that .BR sprintf (3) works. One important difference, though, is that some state information is kept with the \fIber\fP parameter so that multiple calls can be made to .BR ber_printf () to append things to the end of the BER element. .BR Ber_printf () writes to \fIber\fP, a pointer to a BerElement such as returned by .BR ber_alloc_t (). It interprets and formats its arguments according to the format string \fIfmt\fP. The format string can contain the following characters: .RS .LP .TP 3 .B b Boolean. An ber_int_t parameter should be supplied. A boolean element is output. .TP .B e Enumeration. An ber_int_t parameter should be supplied. An enumeration element is output. .TP .B i Integer. An ber_int_t parameter should be supplied. An integer element is output. .TP .B B Bitstring. A char * pointer to the start of the bitstring is supplied, followed by the number of bits in the bitstring. A bitstring element is output. .TP .B n Null. No parameter is required. A null element is output. .TP .B o Octet string. A char * is supplied, followed by the length of the string pointed to. An octet string element is output. .TP .B O Octet string. A struct berval * is supplied. An octet string element is output. .TP .B s Octet string. A null-terminated string is supplied. An octet string element is output, not including the trailing NULL octet. .TP .B t Tag. A ber_tag_t specifying the tag to give the next element is provided. This works across calls. .TP .B v Several octet strings. A null-terminated array of char *'s is supplied. Note that a construct like '{v}' is required to get an actual SEQUENCE OF octet strings. .TP .B V Several octet strings. A null-terminated array of struct berval *'s is supplied. Note that a construct like '{V}' is required to get an actual SEQUENCE OF octet strings. .TP .B W Several octet strings. An array of struct berval's is supplied. The array is terminated by a struct berval with a NULL bv_val. Note that a construct like '{W}' is required to get an actual SEQUENCE OF octet strings. .TP .B { Begin sequence. No parameter is required. .TP .B } End sequence. No parameter is required. .TP .B [ Begin set. No parameter is required. .TP .B ] End set. No parameter is required. .RE .LP The .BR ber_put_int () routine writes the integer element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_enum () routine writes the enumeration element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_boolean () routine writes the boolean value given by \fIbool\fP to the BER element. .LP The .BR ber_put_bitstring () routine writes \fIblen\fP bits starting at \fIstr\fP as a bitstring value to the given BER element. Note that \fIblen\fP is the length \fIin bits\fP of the bitstring. .LP The .BR ber_put_ostring () routine writes \fIlen\fP bytes starting at \fIstr\fP to the BER element as an octet string. .LP The .BR ber_put_string () routine writes the null-terminated string (minus the terminating '\0') to the BER element as an octet string. .LP The .BR ber_put_null () routine writes a NULL element to the BER element. .LP The .BR ber_start_seq () routine is used to start a sequence in the BER element. The .BR ber_start_set () routine works similarly. The end of the sequence or set is marked by the nearest matching call to .BR ber_put_seq () or .BR ber_put_set (), respectively. .SH EXAMPLES Assuming the following variable declarations, and that the variables have been assigned appropriately, an lber encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP can be achieved like so: .LP .nf int rc; ber_int_t scope, ali, size, time, attrsonly; char *dn, **attrs; BerElement *ber; /* ... fill in values ... */ ber = ber_alloc_t( LBER_USE_DER ); if ( ber == NULL ) { /* error */ } rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali, size, time, attrsonly, attrs ); if( rc == \-1 ) { /* error */ } else { /* success */ } .fi .SH ERRORS If an error occurs during encoding, generally these routines return \-1. .LP .SH NOTES .LP The return values for all of these functions are declared in the <lber.h> header file. .SH SEE ALSO .BR lber-decode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 289 stdin PK �c\�շY� � man/man3/ber_bvarray_add.3nu �[��� .lf 1 stdin .TH LBER_TYPES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_int_t, ber_uint_t, ber_len_t, ber_slen_t, ber_tag_t, struct berval, BerValue, BerVarray, BerElement, ber_bvfree, ber_bvecfree, ber_bvecadd, ber_bvarray_free, ber_bvarray_add, ber_bvdup, ber_dupbv, ber_bvstr, ber_bvstrdup, ber_str2bv, ber_alloc_t, ber_init, ber_init2, ber_free \- OpenLDAP LBER types and allocation functions .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .nf .ft B typedef impl_tag_t ber_tag_t; typedef impl_int_t ber_int_t; typedef impl_uint_t ber_uint_t; typedef impl_len_t ber_len_t; typedef impl_slen_t ber_slen_t; typedef struct berval { ber_len_t bv_len; char *bv_val; } BerValue, *BerVarray; typedef struct berelement BerElement; .ft .fi .LP .BI "void ber_bvfree(struct berval *" bv ");" .LP .BI "void ber_bvecfree(struct berval **" bvec ");" .LP .BI "void ber_bvecadd(struct berval ***" bvec ", struct berval *" bv ");" .LP .BI "void ber_bvarray_free(struct berval *" bvarray ");" .LP .BI "void ber_bvarray_add(BerVarray *" bvarray ", BerValue *" bv ");" .LP .BI "struct berval *ber_bvdup(const struct berval *" bv ");" .LP .BI "struct berval *ber_dupbv(const struct berval *" dst ", struct berval *" src ");" .LP .BI "struct berval *ber_bvstr(const char *" str ");" .LP .BI "struct berval *ber_bvstrdup(const char *" str ");" .LP .BI "struct berval *ber_str2bv(const char *" str ", ber_len_t " len ", int " dup ", struct berval *" bv ");" .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "BerElement *ber_init(struct berval *" bv ");" .LP .BI "void ber_init2(BerElement *" ber ", struct berval *" bv ", int " options ");" .LP .BI "void ber_free(BerElement *" ber ", int " freebuf ");" .SH DESCRIPTION .LP The following are the basic types and structures defined for use with the Lightweight BER library. .LP .B ber_int_t is a signed integer of at least 32 bits. It is commonly equivalent to .BR int . .B ber_uint_t is the unsigned variant of .BR ber_int_t . .LP .B ber_len_t is an unsigned integer of at least 32 bits used to represent a length. It is commonly equivalent to a .BR size_t . .B ber_slen_t is the signed variant to .BR ber_len_t . .LP .B ber_tag_t is an unsigned integer of at least 32 bits used to represent a BER tag. It is commonly equivalent to a .BR unsigned\ long . .LP The actual definitions of the integral impl_TYPE_t types are platform specific. .LP .BR BerValue , commonly used as .BR struct\ berval , is used to hold an arbitrary sequence of octets. .B bv_val points to .B bv_len octets. .B bv_val is not necessarily terminated by a NULL (zero) octet. .BR ber_bvfree () frees a BerValue, pointed to by \fIbv\fP, returned from this API. If \fIbv\fP is NULL, the routine does nothing. .LP .BR ber_bvecfree () frees an array of BerValues (and the array), pointed to by \fIbvec\fP, returned from this API. If \fIbvec\fP is NULL, the routine does nothing. .BR ber_bvecadd () appends the \fIbv\fP pointer to the \fIbvec\fP array. Space for the array is allocated as needed. The end of the array is marked by a NULL pointer. .LP .BR ber_bvarray_free () frees an array of BerValues (and the array), pointed to by \fIbvarray\fP, returned from this API. If \fIbvarray\fP is NULL, the routine does nothing. .BR ber_bvarray_add () appends the contents of the BerValue pointed to by \fIbv\fP to the \fIbvarray\fP array. Space for the new element is allocated as needed. The end of the array is marked by a BerValue with a NULL bv_val field. .LP .BR ber_bvdup () returns a copy of a BerValue. The routine returns NULL upon error (e.g. out of memory). The caller should use .BR ber_bvfree () to deallocate the resulting BerValue. .BR ber_dupbv () copies a BerValue from \fIsrc\fP to \fIdst\fP. If \fIdst\fP is NULL a new BerValue will be allocated to hold the copy. The routine returns NULL upon error, otherwise it returns a pointer to the copy. If \fIdst\fP is NULL the caller should use .BR ber_bvfree () to deallocate the resulting BerValue, otherwise .BR ber_memfree () should be used to deallocate the \fIdst->bv_val\fP. (The .BR ber_bvdup () function is internally implemented as ber_dupbv(NULL, bv). .BR ber_bvdup () is provided only for compatibility with an expired draft of the LDAP C API; .BR ber_dupbv () is the preferred interface.) .LP .BR ber_bvstr () returns a BerValue containing the string pointed to by \fIstr\fP. .BR ber_bvstrdup () returns a BerValue containing a copy of the string pointed to by \fIstr\fP. .BR ber_str2bv () returns a BerValue containing the string pointed to by \fIstr\fP, whose length may be optionally specified in \fIlen\fP. If \fIdup\fP is non-zero, the BerValue will contain a copy of \fIstr\fP. If \fIlen\fP is zero, the number of bytes to copy will be determined by .BR strlen (3), otherwise \fIlen\fP bytes will be copied. If \fIbv\fP is non-NULL, the result will be stored in the given BerValue, otherwise a new BerValue will be allocated to store the result. NOTE: Both .BR ber_bvstr () and .BR ber_bvstrdup () are implemented as macros using .BR ber_str2bv () in this version of the library. .LP .B BerElement is an opaque structure used to maintain state information used in encoding and decoding. .BR ber_alloc_t () is used to create an empty BerElement structure. If .B LBER_USE_DER is specified for the .I options parameter then data lengths for data written to the BerElement will be encoded in the minimal number of octets required, otherwise they will always be written as four byte values. .BR ber_init () creates a BerElement structure that is initialized with a copy of the data in its .I bv parameter. .BR ber_init2 () initializes an existing BerElement .I ber using the data in the .I bv parameter. The data is referenced directly, not copied. The .I options parameter is the same as for .BR ber_alloc_t (). .BR ber_free () frees a BerElement pointed to by \fIber\fP. If \fIber\fP is NULL, the routine does nothing. If \fIfreebuf\fP is zero, the internal buffer is not freed. .SH SEE ALSO .BR lber-encode (3), .BR lber-decode (3), .BR lber-memory (3) .LP .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 189 stdin PK �c\'�t!� � man/man3/ldap_tls.3nu �[��� .lf 1 stdin .TH LDAP_TLS 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_start_tls, ldap_start_tls_s, ldap_tls_inplace, ldap_install_tls \- LDAP TLS initialization routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "int ldap_start_tls(LDAP *" ld ");" .LP .BI "int ldap_start_tls_s(LDAP *" ld ", LDAPControl **" serverctrls ", LDAPControl **" clientctrls ");" .LP .BI "int ldap_tls_inplace(LDAP *" ld ");" .LP .BI "int ldap_install_tls(LDAP *" ld ");" .SH DESCRIPTION These routines are used to initiate TLS processing on an LDAP session. .BR ldap_start_tls_s () sends a StartTLS request to a server, waits for the reply, and then installs TLS handlers on the session if the request succeeded. The routine returns .B LDAP_SUCCESS if everything succeeded, otherwise it returns an LDAP error code. .BR ldap_start_tls () sends a StartTLS request to a server and does nothing else. It returns .B LDAP_SUCCESS if the request was sent successfully. .BR ldap_tls_inplace () returns 1 if TLS handlers have been installed on the specified session, 0 otherwise. .BR ldap_install_tls () installs the TLS handlers on the given session. It returns .B LDAP_LOCAL_ERROR if TLS is already installed. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 42 stdin PK �c\M7��R# R# man/man3/ldap.3nu �[��� .lf 1 stdin .TH LDAP 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap \- OpenLDAP Lightweight Directory Access Protocol API .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .ft .fi .SH DESCRIPTION .LP The Lightweight Directory Access Protocol (LDAP) (RFC 4510) provides access to X.500 directory services. These services may be stand\-alone or part of a distributed directory service. This client API supports LDAP over TCP (RFC 4511), LDAP over TLS/SSL, and LDAP over IPC (UNIX domain sockets). This API supports SASL (RFC 4513) and Start TLS (RFC 4513) as well as a number of protocol extensions. This API is loosely based upon IETF/LDAPEXT C LDAP API draft specification, a (orphaned) work in progress. .LP The OpenLDAP Software package includes a stand\-alone server in .BR slapd (8), various LDAP clients, and an LDAP client library used to provide programmatic access to the LDAP protocol. This man page gives an overview of the LDAP library routines. .LP Both synchronous and asynchronous APIs are provided. Also included are various routines to parse the results returned from these routines. These routines are found in the \-lldap library. .LP The basic interaction is as follows. A session handle is created using .BR ldap_initialize (3) and set the protocol version to 3 by calling .BR ldap_set_option (3). The underlying session is established first operation is issued. This would generally be a Start TLS or Bind operation, or a Search operation to read attributes of the Root DSE. A Start TLS operation is performed by calling .BR ldap_start_tls_s (3). A LDAP bind operation is performed by calling .BR ldap_sasl_bind (3) or one of its friends. A Search operation is performed by calling ldap_search_ext_s(3) or one of its friends. Subsequently, additional operations are performed by calling one of the synchronous or asynchronous routines (e.g., .BR ldap_compare_ext_s (3) or .BR ldap_compare_ext (3) followed by .BR ldap_result (3)). Results returned from these routines are interpreted by calling the LDAP parsing routines such as .BR ldap_parse_result (3). The LDAP association and underlying connection is terminated by calling .BR ldap_unbind_ext (3). Errors can be interpreted by calling .BR ldap_err2string (3). .SH LDAP versions This library supports version 3 of the Lightweight Directory Access Protocol (LDAPv3) as defined in RFC 4510. It also supports a variant of version 2 of LDAP as defined by U-Mich LDAP and, to some degree, RFC 1777. Version 2 (all variants) are considered obsolete. Version 3 should be used instead. .LP For backwards compatibility reasons, the library defaults to version 2. Hence, all new applications (and all actively maintained applications) should use .BR ldap_set_option (3) to select version 3. The library manual pages assume version 3 has been selected. .SH INPUT and OUTPUT PARAMETERS All character string input/output is expected to be/is UTF-8 encoded Unicode (version 3.2). .LP Distinguished names (DN) (and relative distinguished names (RDN) to be passed to the LDAP routines should conform to RFC 4514 UTF-8 string representation. .LP Search filters to be passed to the search routines are to be constructed by hand and should conform to RFC 4515 UTF-8 string representation. .LP LDAP URLs to be passed to routines are expected to conform to RFC 4516 format. The .BR ldap_url (3) routines can be used to work with LDAP URLs. .LP LDAP controls to be passed to routines can be manipulated using the .BR ldap_controls (3) routines. .SH DISPLAYING RESULTS Results obtained from the search routines can be output by hand, by calling .BR ldap_first_entry (3) and .BR ldap_next_entry (3) to step through the entries returned, .BR ldap_first_attribute (3) and .BR ldap_next_attribute (3) to step through an entry's attributes, and .BR ldap_get_values (3) to retrieve a given attribute's values. Attribute values may or may not be displayable. .SH UTILITY ROUTINES Also provided are various utility routines. The .BR ldap_sort (3) routines are used to sort the entries and values returned via the ldap search routines. .SH DEPRECATED INTERFACES A number of interfaces are now considered deprecated. For instance, ldap_add(3) is deprecated in favor of ldap_add_ext(3). .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 123 stdin .SH BER LIBRARY Also included in the distribution is a set of lightweight Basic Encoding Rules routines. These routines are used by the LDAP library routines to encode and decode LDAP protocol elements using the (slightly simplified) Basic Encoding Rules defined by LDAP. They are not normally used directly by an LDAP application program except in the handling of controls and extended operations. The routines provide a printf and scanf\-like interface, as well as lower\-level access. These routines are discussed in .BR lber\-decode (3), .BR lber\-encode (3), .BR lber\-memory (3), and .BR lber\-types (3). .SH INDEX .TP 20 .SM ldap_initialize(3) initialize the LDAP library without opening a connection to a server .TP .SM ldap_result(3) wait for the result from an asynchronous operation .TP .SM ldap_abandon_ext(3) abandon (abort) an asynchronous operation .TP .SM ldap_add_ext(3) asynchronously add an entry .TP .SM ldap_add_ext_s(3) synchronously add an entry .TP .SM ldap_sasl_bind(3) asynchronously bind to the directory .TP .SM ldap_sasl_bind_s(3) synchronously bind to the directory .TP .SM ldap_unbind_ext(3) synchronously unbind from the LDAP server and close the connection .TP .SM ldap_unbind(3) and ldap_unbind_s(3) are equivalent to .BR ldap_unbind_ext (3) .TP .SM ldap_memfree(3) dispose of memory allocated by LDAP routines. .TP .SM ldap_compare_ext(3) asynchronously compare to a directory entry .TP .SM ldap_compare_ext_s(3) synchronously compare to a directory entry .TP .SM ldap_delete_ext(3) asynchronously delete an entry .TP .SM ldap_delete_ext_s(3) synchronously delete an entry .TP .SM ld_errno(3) LDAP error indication .TP .SM ldap_errlist(3) list of LDAP errors and their meanings .TP .SM ldap_err2string(3) convert LDAP error indication to a string .TP .SM ldap_extended_operation(3) asynchronously perform an arbitrary extended operation .TP .SM ldap_extended_operation_s(3) synchronously perform an arbitrary extended operation .TP .SM ldap_first_attribute(3) return first attribute name in an entry .TP .SM ldap_next_attribute(3) return next attribute name in an entry .TP .SM ldap_first_entry(3) return first entry in a chain of search results .TP .SM ldap_next_entry(3) return next entry in a chain of search results .TP .SM ldap_count_entries(3) return number of entries in a search result .TP .SM ldap_get_dn(3) extract the DN from an entry .TP .SM ldap_get_values_len(3) return an attribute's values with lengths .TP .SM ldap_value_free_len(3) free memory allocated by ldap_get_values_len(3) .TP .SM ldap_count_values_len(3) return number of values .TP .SM ldap_modify_ext(3) asynchronously modify an entry .TP .SM ldap_modify_ext_s(3) synchronously modify an entry .TP .SM ldap_mods_free(3) free array of pointers to mod structures used by ldap_modify_ext(3) .TP .SM ldap_rename(3) asynchronously rename an entry .TP .SM ldap_rename_s(3) synchronously rename an entry .TP .SM ldap_msgfree(3) free results allocated by ldap_result(3) .TP .SM ldap_msgtype(3) return the message type of a message from ldap_result(3) .TP .SM ldap_msgid(3) return the message id of a message from ldap_result(3) .TP .SM ldap_search_ext(3) asynchronously search the directory .TP .SM ldap_search_ext_s(3) synchronously search the directory .TP .SM ldap_is_ldap_url(3) check a URL string to see if it is an LDAP URL .TP .SM ldap_url_parse(3) break up an LDAP URL string into its components .TP .SM ldap_sort_entries(3) sort a list of search results .TP .SM ldap_sort_values(3) sort a list of attribute values .TP .SM ldap_sort_strcasecmp(3) case insensitive string comparison .SH SEE ALSO .BR ldap.conf (5), .BR slapd (8), .BR draft-ietf-ldapext-ldap-c-api-xx.txt \ <http://www.ietf.org> .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 274 stdin .LP These API manual pages are loosely based upon descriptions provided in the IETF/LDAPEXT C LDAP API Internet Draft, a (orphaned) work in progress. PK �c\OPh�� � man/man3/ldap_rename_s.3nu �[��� .lf 1 stdin .TH LDAP_RENAME 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_rename, ldap_rename_s \- Renames the specified entry. .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_rename( ld, dn, newrdn, newparent, deleteoldrdn, sctrls[], cctrls[], msgidp ); .ft LDAP *ld; const char *dn, *newrdn, *newparent; int deleteoldrdn; LDAPControl *sctrls[], *cctrls[]; int *msgidp); .LP .ft B int ldap_rename_s( ld, dn, newrdn, newparent, deleteoldrdn, sctrls[], cctrls[] ); .ft LDAP *ld; const char *dn, *newrdn, *newparent; int deleteoldrdn; LDAPControl *sctrls[], *cctrls[]; .SH DESCRIPTION These routines are used to perform a LDAP rename operation. The function changes the leaf component of an entry's distinguished name and optionally moves the entry to a new parent container. The .B ldap_rename_s performs a rename operation synchronously. The method takes \fIdn\fP, which points to the distinguished name of the entry whose attribute is being compared, \fInewparent\fP,the distinguished name of the entry's new parent. If this parameter is NULL, only the RDN is changed. The root DN is specified by passing a zero length string, "". \fIdeleteoldrdn\fP specifies whether the old RDN should be retained or deleted. Zero indicates that the old RDN should be retained. If you choose this option, the attribute will contain both names (the old and the new). Non-zero indicates that the old RDN should be deleted. \fIserverctrls\fP points to an array of LDAPControl structures that list the client controls to use with this extended operation. Use NULL to specify no client controls. \fIclientctrls\fP points to an array of LDAPControl structures that list the client controls to use with the search. .LP .B ldap_rename works just like .B ldap_rename_s, but the operation is asynchronous. It returns the message id of the request it initiated. The result of this operation can be obtained by calling .BR ldap_result(3). .SH ERRORS .B ldap_rename() returns \-1 in case of error initiating the request, and will set the \fIld_errno\fP field in the \fIld\fP parameter to indicate the error. .BR ldap_rename_s() returns the LDAP error code resulting from the rename operation. .SH SEE ALSO .BR ldap (3), .BR ldap_modify (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 67 stdin PK �c\g�d"# "# man/man3/ldap_objectclass2str.3nu �[��� .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin PK �c\g�d"# "# " man/man3/ldap_attributetype2name.3nu �[��� .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin PK �c\�� �. �. man/man3/ldap_unbind_ext.3nu �[��� .lf 1 stdin .TH LDAP_BIND 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_bind, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_sasl_bind, ldap_sasl_bind_s, ldap_sasl_interactive_bind_s, ldap_parse_sasl_bind_result, ldap_unbind, ldap_unbind_s, ldap_unbind_ext, ldap_unbind_ext_s, ldap_set_rebind_proc \- LDAP bind routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .BI "int ldap_bind(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_bind_s(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_simple_bind(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_simple_bind_s(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_sasl_bind(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], int *" msgidp ");" .RE .LP .BI "int ldap_sasl_bind_s(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], struct berval **" servercredp ");" .RE .LP .BI "int ldap_parse_sasl_bind_result(LDAP *" ld ", LDAPMessage *" res "," .RS .BI "struct berval **" servercredp ", int " freeit ");" .RE .LP .BI "int ldap_sasl_interactive_bind_s(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ");" .RE .LP .BI "int ldap_sasl_interactive_bind(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ", LDAPMessage *" result "," .BI "const char **" rmechp ", int *" msgidp ");" .RE .LP .BI "int (LDAP_SASL_INTERACT_PROC)(LDAP *" ld ", unsigned " flags ", void *" defaults ", void *" sasl_interact ");" .LP .BI "int ldap_unbind(LDAP *" ld ");" .LP .BI "int ldap_unbind_s(LDAP *" ld ");" .LP .BI "int ldap_unbind_ext(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_unbind_ext_s(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_set_rebind_proc (LDAP *" ld ", LDAP_REBIND_PROC *" ldap_proc ", void *" params ");" .LP .BI "int (LDAP_REBIND_PROC)(LDAP *" ld ", LDAP_CONST char *" url ", ber_tag_t " request ", ber_int_t " msgid ", void *" params ");" .SH DESCRIPTION .LP These routines provide various interfaces to the LDAP bind operation. After an association with an LDAP server is made using .BR ldap_init (3), an LDAP bind operation should be performed before other operations are attempted over the connection. An LDAP bind is required when using Version 2 of the LDAP protocol; it is optional for Version 3 but is usually needed due to security considerations. .LP There are three types of bind calls, ones providing simple authentication, ones providing SASL authentication, and general routines capable of doing either simple or SASL authentication. .LP .B SASL (Simple Authentication and Security Layer) can negotiate one of many different kinds of authentication. Both synchronous and asynchronous versions of each variant of the bind call are provided. All routines take \fIld\fP as their first parameter, as returned from .BR ldap_init (3). .SH SIMPLE AUTHENTICATION The simplest form of the bind call is .BR ldap_simple_bind_s() . It takes the DN to bind as in \fIwho\fP, and the userPassword associated with the entry in \fIpasswd\fP. It returns an LDAP error indication (see .BR ldap_error (3)). The .B ldap_simple_bind() call is asynchronous, taking the same parameters but only initiating the bind operation and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The .B ldap_sasl_bind_s() and asynchronous .B ldap_sasl_bind() functions can also be used to make a simple bind by using LDAP_SASL_SIMPLE as the SASL mechanism. .SH GENERAL AUTHENTICATION The .B ldap_bind() and .B ldap_bind_s() routines can be used when the authentication method to use needs to be selected at runtime. They both take an extra \fImethod\fP parameter selecting the authentication method to use. It should be set to LDAP_AUTH_SIMPLE to select simple authentication. .B ldap_bind() returns the message id of the request it initiates. .B ldap_bind_s() returns an LDAP error indication. .SH SASL AUTHENTICATION For SASL binds the server always ignores any provided DN, so the .I dn parameter should always be NULL. .BR ldap_sasl_bind_s () sends a single SASL bind request with the given SASL .I mechanism and credentials in the .I cred parameter. The format of the credentials depends on the particular SASL mechanism in use. For mechanisms that provide mutual authentication the server's credentials will be returned in the .I servercredp parameter. The routine returns an LDAP error indication (see .BR ldap_error (3)). The .BR ldap_sasl_bind () call is asynchronous, taking the same parameters but only sending the request and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The result must be additionally parsed by .BR ldap_parse_sasl_bind_result () to obtain any server credentials sent from the server. .LP Many SASL mechanisms require multiple message exchanges to perform a complete authentication. Applications should generally use .BR ldap_sasl_interactive_bind_s () rather than calling the basic .BR ldap_sasl_bind () functions directly. The .I mechs parameter should contain a space-separated list of candidate mechanisms to use. If this parameter is NULL or empty the library will query the supportedSASLMechanisms attribute from the server's rootDSE for the list of SASL mechanisms the server supports. The .I flags parameter controls the interaction used to retrieve any necessary SASL authentication parameters and should be one of: .TP LDAP_SASL_AUTOMATIC use defaults if available, prompt otherwise .TP LDAP_SASL_INTERACTIVE always prompt .TP LDAP_SASL_QUIET never prompt .LP The .I interact function uses the provided .I defaults to handle requests from the SASL library for particular authentication parameters. There is no defined format for the .I defaults information; it is up to the caller to use whatever format is appropriate for the supplied .I interact function. The .I sasl_interact parameter comes from the underlying SASL library. When used with Cyrus SASL this is an array of .B sasl_interact_t structures. The Cyrus SASL library will prompt for a variety of inputs, including: .TP SASL_CB_GETREALM the realm for the authentication attempt .TP SASL_CB_AUTHNAME the username to authenticate .TP SASL_CB_PASS the password for the provided username .TP SASL_CB_USER the username to use for proxy authorization .TP SASL_CB_NOECHOPROMPT generic prompt for input with input echoing disabled .TP SASL_CB_ECHOPROMPT generic prompt for input with input echoing enabled .TP SASL_CB_LIST_END indicates the end of the array of prompts .LP See the Cyrus SASL documentation for more details. .LP Applications which need to manage connections asynchronously may use .BR ldap_sasl_interactive_bind () instead of the synchronous version. A valid mechs parameter must be supplied, otherwise the library will be forced to query the server for a list of supported mechanisms, and this query will be performed synchronously. The other parameters are the same as for the synchronous function, with three additional parameters. The actual SASL mechanism that was used, and the message ID for use with .BR ldap_result () will be returned in rmechp and msgidp, respectively. The value in rmechp must not be modified by the caller and must be passed back on each subsequent call. The message obtained from .BR ldap_result () must be passed in the result parameter. This parameter must be NULL when initiating a new Bind. The caller must free the result message after each call using .BR ldap_msgfree (). The .BR ldap_sasl_interactive_bind () function returns an LDAP result code. If the code is LDAP_SASL_BIND_IN_PROGRESS then the Bind is not complete yet, and this function must be called again with the next result from the server. .SH REBINDING .LP The .B ldap_set_rebind_proc function() sets the process to use for binding when an operation returns a referral. This function is used when an application needs to bind to another server in order to follow a referral or search continuation reference. .LP The function takes \fIld\fP, the \fIrebind\fP function, and the \fIparams\fP, the arbitrary data like state information which the client might need to properly rebind. The LDAP_OPT_REFERRALS option in the \fIld\fP must be set to ON for the libraries to use the rebind function. Use the .BR ldap_set_option function to set the value. .LP The rebind function parameters are as follows: .LP The \fIld\fP parameter must be used by the application when binding to the referred server if the application wants the libraries to follow the referral. .LP The \fIurl\fP parameter points to the URL referral string received from the LDAP server. The LDAP application can use the .BR ldap_url_parse (3) function to parse the string into its components. .LP The \fIrequest\fP parameter specifies the type of request that generated the referral. .LP The \fImsgid\fP parameter specifies the message ID of the request generating the referral. .LP The \fIparams\fP parameter is the same value as passed originally to the .BR ldap_set_rebind_proc () function. .LP The LDAP libraries set all the parameters when they call the rebind function. The application should not attempt to free either the ld or the url structures in the rebind function. .LP The application must supply to the rebind function the required authentication information such as, user name, password, and certificates. The rebind function must use a synchronous bind method. .SH UNBINDING The .B ldap_unbind() call is used to unbind from the directory, terminate the current association, and free the resources contained in the \fIld\fP structure. Once it is called, the connection to the LDAP server is closed, and the \fIld\fP structure is invalid. The .B ldap_unbind_s() call is just another name for .BR ldap_unbind() ; both of these calls are synchronous in nature. .LP The .B ldap_unbind_ext() and .B ldap_unbind_ext_s() allows the operations to specify controls. .SH ERRORS Asynchronous routines will return \-1 in case of error, setting the \fIld_errno\fP parameter of the \fIld\fP structure. Synchronous routines return whatever \fIld_errno\fP is set to. See .BR ldap_error (3) for more information. .SH NOTES If an anonymous bind is sufficient for the application, the rebind process need not be provided. The LDAP libraries with the LDAP_OPT_REFERRALS option set to ON (default value) will automatically follow referrals using an anonymous bind. .LP If the application needs stronger authentication than an anonymous bind, you need to provide a rebind process for that authentication method. The bind method must be synchronous. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_open (3), .BR ldap_set_option (3), .BR ldap_url_parse (3) .B RFC 4422 (http://www.rfc-editor.org), .B Cyrus SASL (http://asg.web.cmu.edu/sasl/) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 335 stdin PK �c\����� � man/man3/ldap_count_values.3nu �[��� .lf 1 stdin .TH LDAP_GET_VALUES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_values, ldap_get_values_len, ldap_count_values \- LDAP attribute value handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char **ldap_get_values(ld, entry, attr) .ft LDAP *ld; LDAPMessage *entry; char *attr; .LP .ft B struct berval **ldap_get_values_len(ld, entry, attr) .ft LDAP *ld; LDAPMessage *entry; char *attr; .LP .ft B int ldap_count_values(vals) .ft char **vals; .LP .ft B int ldap_count_values_len(vals) .ft struct berval **vals; .LP .ft B void ldap_value_free(vals) .ft char **vals; .LP .ft B void ldap_value_free_len(vals) .ft struct berval **vals; .SH DESCRIPTION These routines are used to retrieve and manipulate attribute values from an LDAP entry as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3). .B ldap_get_values() takes the \fIentry\fP and the attribute \fIattr\fP whose values are desired and returns a NULL-terminated array of the attribute's values. \fIattr\fP may be an attribute type as returned from .BR ldap_first_attribute (3) or .BR ldap_next_attribute (3), or if the attribute type is known it can simply be given. .LP The number of values in the array can be counted by calling .BR ldap_count_values() . The array of values returned can be freed by calling .BR ldap_value_free() . .LP If the attribute values are binary in nature, and thus not suitable to be returned as an array of char *'s, the .B ldap_get_values_len() routine can be used instead. It takes the same parameters as .BR ldap_get_values() , but returns a NULL-terminated array of pointers to berval structures, each containing the length of and a pointer to a value. .LP The number of values in the array can be counted by calling .BR ldap_count_values_len() . The array of values returned can be freed by calling .BR ldap_value_free_len() . .SH ERRORS If an error occurs in .B ldap_get_values() or .BR ldap_get_values_len() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .SH NOTES These routines dynamically allocate memory which the caller must free using the supplied routines. .SH SEE ALSO .BR ldap (3), .BR ldap_first_entry (3), .BR ldap_first_attribute (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 103 stdin PK �c\��MK$ K$ man/man3/ber_flush.3nu �[��� .lf 1 stdin .TH LBER_ENCODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_alloc_t, ber_flush, ber_flush2, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring, ber_put_string, ber_put_null, ber_put_boolean, ber_put_bitstring, ber_start_seq, ber_start_set, ber_put_seq, ber_put_set \- OpenLDAP LBER simplified Basic Encoding Rules library routines for encoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_flush2(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_printf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "int ber_put_int(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_enum(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_ostring(BerElement *" ber ", const char *" str ", ber_len_t " len ", ber_tag_t " tag ");" .LP .BI "int ber_put_string(BerElement *" ber ", const char *" str ", ber_tag_t " tag ");" .LP .BI "int ber_put_null(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_boolean(BerElement *" ber ", ber_int_t " bool ", ber_tag_t " tag ");" .LP .BI "int ber_put_bitstring(BerElement *" ber ", const char *" str ", ber_len_t " blen ", ber_tag_t " tag ");" .LP .BI "int ber_start_seq(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_start_set(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_seq(BerElement *" ber ");" .LP .BI "int ber_put_set(BerElement *" ber ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the encoding routines in the lber library. See .BR lber-decode (3) for details on the corresponding decoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_alloc_t () to allocate a BER element for encoding, .BR ber_printf () to do the actual encoding, and .BR ber_flush2 () to actually write the element. The other routines are provided for those applications that need more control than .BR ber_printf () provides. In general, these routines return the length of the element encoded, or \-1 if an error occurred. .LP The .BR ber_alloc_t () routine is used to allocate a new BER element. It should be called with an argument of LBER_USE_DER. .LP The .BR ber_flush2 () routine is used to actually write the element to a socket (or file) descriptor, once it has been fully encoded (using .BR ber_printf () and friends). See .BR lber-sockbuf (3) for more details on the Sockbuf implementation of the \fIsb\fP parameter. If the \fIfreeit\fP parameter is non-zero, the supplied \fIber\fP will be freed. If \fILBER_FLUSH_FREE_ON_SUCCESS\fP is used, the \fIber\fP is only freed when successfully flushed, otherwise it is left intact; if \fILBER_FLUSH_FREE_ON_ERROR\fP is used, the \fIber\fP is only freed when an error occurs, otherwise it is left intact; if \fILBER_FLUSH_FREE_ALWAYS\fP is used, the \fIber\fP is freed anyway. This function differs from the original .BR ber_flush (3) function, whose behavior corresponds to that indicated for \fILBER_FLUSH_FREE_ON_SUCCESS\fP. Note that in the future, the behavior of .BR ber_flush (3) with \fIfreeit\fP non-zero might change into that of .BR ber_flush2 (3) with \fIfreeit\fP set to \fILBER_FLUSH_FREE_ALWAYS\fP. .LP The .BR ber_printf () routine is used to encode a BER element in much the same way that .BR sprintf (3) works. One important difference, though, is that some state information is kept with the \fIber\fP parameter so that multiple calls can be made to .BR ber_printf () to append things to the end of the BER element. .BR Ber_printf () writes to \fIber\fP, a pointer to a BerElement such as returned by .BR ber_alloc_t (). It interprets and formats its arguments according to the format string \fIfmt\fP. The format string can contain the following characters: .RS .LP .TP 3 .B b Boolean. An ber_int_t parameter should be supplied. A boolean element is output. .TP .B e Enumeration. An ber_int_t parameter should be supplied. An enumeration element is output. .TP .B i Integer. An ber_int_t parameter should be supplied. An integer element is output. .TP .B B Bitstring. A char * pointer to the start of the bitstring is supplied, followed by the number of bits in the bitstring. A bitstring element is output. .TP .B n Null. No parameter is required. A null element is output. .TP .B o Octet string. A char * is supplied, followed by the length of the string pointed to. An octet string element is output. .TP .B O Octet string. A struct berval * is supplied. An octet string element is output. .TP .B s Octet string. A null-terminated string is supplied. An octet string element is output, not including the trailing NULL octet. .TP .B t Tag. A ber_tag_t specifying the tag to give the next element is provided. This works across calls. .TP .B v Several octet strings. A null-terminated array of char *'s is supplied. Note that a construct like '{v}' is required to get an actual SEQUENCE OF octet strings. .TP .B V Several octet strings. A null-terminated array of struct berval *'s is supplied. Note that a construct like '{V}' is required to get an actual SEQUENCE OF octet strings. .TP .B W Several octet strings. An array of struct berval's is supplied. The array is terminated by a struct berval with a NULL bv_val. Note that a construct like '{W}' is required to get an actual SEQUENCE OF octet strings. .TP .B { Begin sequence. No parameter is required. .TP .B } End sequence. No parameter is required. .TP .B [ Begin set. No parameter is required. .TP .B ] End set. No parameter is required. .RE .LP The .BR ber_put_int () routine writes the integer element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_enum () routine writes the enumeration element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_boolean () routine writes the boolean value given by \fIbool\fP to the BER element. .LP The .BR ber_put_bitstring () routine writes \fIblen\fP bits starting at \fIstr\fP as a bitstring value to the given BER element. Note that \fIblen\fP is the length \fIin bits\fP of the bitstring. .LP The .BR ber_put_ostring () routine writes \fIlen\fP bytes starting at \fIstr\fP to the BER element as an octet string. .LP The .BR ber_put_string () routine writes the null-terminated string (minus the terminating '\0') to the BER element as an octet string. .LP The .BR ber_put_null () routine writes a NULL element to the BER element. .LP The .BR ber_start_seq () routine is used to start a sequence in the BER element. The .BR ber_start_set () routine works similarly. The end of the sequence or set is marked by the nearest matching call to .BR ber_put_seq () or .BR ber_put_set (), respectively. .SH EXAMPLES Assuming the following variable declarations, and that the variables have been assigned appropriately, an lber encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP can be achieved like so: .LP .nf int rc; ber_int_t scope, ali, size, time, attrsonly; char *dn, **attrs; BerElement *ber; /* ... fill in values ... */ ber = ber_alloc_t( LBER_USE_DER ); if ( ber == NULL ) { /* error */ } rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali, size, time, attrsonly, attrs ); if( rc == \-1 ) { /* error */ } else { /* success */ } .fi .SH ERRORS If an error occurs during encoding, generally these routines return \-1. .LP .SH NOTES .LP The return values for all of these functions are declared in the <lber.h> header file. .SH SEE ALSO .BR lber-decode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 289 stdin PK �c\���0 0 man/man3/ldap_memory.3nu �[��� .lf 1 stdin .TH LDAP_MEMORY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_memfree, ldap_memvfree, ldap_memalloc, ldap_memcalloc, ldap_memrealloc, ldap_strdup \- LDAP memory allocation routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "void ldap_memfree(void *" p ");" .LP .BI "void ldap_memvfree(void **" v ");" .LP .BI "void *ldap_memalloc(ber_len_t " s ");" .LP .BI "void *ldap_memcalloc(ber_len_t " n ", ber_len_t " s ");" .LP .BI "void *ldap_memrealloc(void *" p ", ber_len_t " s ");" .LP .BI "char *ldap_strdup(LDAP_CONST char *" p ");" .SH DESCRIPTION These routines are used to allocate/deallocate memory used/returned by the LDAP library. .BR ldap_memalloc (), .BR ldap_memcalloc (), .BR ldap_memrealloc (), and .BR ldap_memfree () are used exactly like the standard .BR malloc (3), .BR calloc (3), .BR realloc (3), and .BR free (3) routines, respectively. The .BR ldap_memvfree () routine is used to free a dynamically allocated array of pointers to arbitrary dynamically allocated objects. The .BR ldap_strdup () routine is used exactly like the standard .BR strdup (3) routine. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 51 stdin PK �c\a��j j man/man3/ldap_first_entry.3nu �[��� .lf 1 stdin .TH LDAP_FIRST_ENTRY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_first_entry, ldap_next_entry, ldap_count_entries \- LDAP result entry parsing and counting routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_count_entries( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_first_entry( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_next_entry( LDAP *ld, LDAPMessage *entry ) .SH DESCRIPTION .LP These routines are used to parse results received from .BR ldap_result (3) or the synchronous LDAP search operation routines .BR ldap_search_s (3) and .BR ldap_search_st (3). .LP The .B ldap_first_entry() routine is used to retrieve the first entry in a chain of search results. It takes the \fIresult\fP as returned by a call to .BR ldap_result (3) or .BR ldap_search_s (3) or .BR ldap_search_st (3) and returns a pointer to the first entry in the result. .LP This pointer should be supplied on a subsequent call to .B ldap_next_entry() to get the next entry, the result of which should be supplied to the next call to .BR ldap_next_entry() , etc. .B ldap_next_entry() will return NULL when there are no more entries. The entries returned from these calls are used in calls to the routines described in .BR ldap_get_dn (3), .BR ldap_first_attribute (3), .BR ldap_get_values (3), etc. .LP A count of the number of entries in the search result can be obtained by calling .BR ldap_count_entries() . .SH ERRORS If an error occurs in .B ldap_first_entry() or .BR ldap_next_entry() , NULL is returned and the ld_errno field in the \fIld\fP parameter is set to indicate the error. If an error occurs in .BR ldap_count_entries() , -1 is returned, and .B ld_errno is set appropriately. See .BR ldap_error (3) for a description of possible error codes. .SH SEE ALSO .BR ldap (3), .BR ldap_result (3), .BR ldap_search (3), .BR ldap_first_attribute (3), .BR ldap_get_values (3), .BR ldap_get_dn (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 81 stdin PK �c\J�s* * ! man/man3/ldap_parse_vlv_control.3nu �[��� .lf 1 stdin .TH LDAP_PARSE_VLV_CONTROL 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_parse_vlv_control \- Decode the information returned from a search operation that used a VLV (virtual list view) control .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_parse_vlv_control( ld, ctrlp, target_posp, list_countp, contextp, errcodep ) .ft LDAP *ld; LDAPControl **ctrlp; unsigned long *target_posp, *list_countp; struct berval **contextp; int *errcodep; .SH DESCRIPTION The .B ldap_parse_vlv_control is used to decode the information returned from a search operation that used a VLV (virtual list view)control. It takes a null terminated array of LDAPControl structures, usually obtained by a call to the .BR ldap_parse_result function, a \fItarget_pos\fP which points to the list index of the target entry. If this parameter is NULL, the target position is not returned. The index returned is an approximation of the position of the target entry. It is not guaranteed to be exact. The parameter \fIlist_countp\fP points to the server's estimate of the size of the list. If this parameter is NULL, the size is not returned. \fIcontextp\fP is a pointer to the address of a berval structure that contains a server-generated context identifier if server returns one. If server does not return a context identifier, the server returns a NULL in this parameter. If this parameter is set to NULL, the context identifier is not returned. You should use this returned context in the next call to create a VLV control. When the berval structure is no longer needed, you should free the memory by calling the \fIber_bvfree function.e\fP \fIerrcodep\fP is an output parameter, which points to the result code returned by the server. If this parameter is NULL, the result code is not returned. .LP See ldap.h for a list of possible return codes. .SH SEE ALSO .BR ldap_search (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 50 stdin PK �c\�C�B� � man/man3/ldap_compare_s.3nu �[��� .lf 1 stdin .TH LDAP_COMPARE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_compare, ldap_compare_s, ldap_compare_ext, ldap_compare_ext_s \- Perform an LDAP compare operation. .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_compare_ext( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, char *\fIattr\fB, const struct berval *\fIbvalue\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB, int *\fImsgidp\fB ); .RE .LP .ft B int ldap_compare_ext_s( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, char *\fIattr\fB, const struct berval *\fIbvalue\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB ); .RE .SH DESCRIPTION The .B ldap_compare_ext_s() routine is used to perform an LDAP compare operation synchronously. It takes \fIdn\fP, the DN of the entry upon which to perform the compare, and \fIattr\fP and \fIvalue\fP, the attribute description and value to compare to those found in the entry. It returns a code, which will be LDAP_COMPARE_TRUE if the entry contains the attribute value and LDAP_COMPARE_FALSE if it does not. Otherwise, an error code is returned that indicates the nature of the problem. See .BR ldap (3) for details. .LP The .B ldap_compare_ext() routine is used to perform an LDAP compare operation asynchronously. It takes the same parameters as .BR ldap_compare_ext_s() , but provides the message id of the request it initiated in the integer pointed to \fImsgidp\fP. The result of the compare can be obtained by a subsequent call to .BR ldap_result (3). .LP Both routines allow server and client controls to be specified to extend the compare request. .SH DEPRECATED INTERFACES The routines .BR ldap_compare () and .BR ldap_compare_s () are deprecated in favor of .BR ldap_compare_ext () and .BR ldap_compare_ext_s (), respectively. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 75 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 80 stdin PK �c\�c%u u man/man3/ldap_search_st.3nu �[��� .lf 1 stdin .TH LDAP_SEARCH 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_search, ldap_search_s, ldap_search_st, ldap_search_ext, ldap_search_ext_s \- Perform an LDAP search operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <sys/types.h> #include <ldap.h> .LP .ft B int ldap_search_ext( .RS LDAP *\fIld\fB, char *\fIbase\fB, int \fIscope\fB, char *\fIfilter\fB, char *\fIattrs\fB[], int \fIattrsonly\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB, struct timeval *\fItimeout\fB, int \fIsizelimit\fB, int *\fImsgidp\fB ); .RE .LP .ft B int ldap_search_ext_s( .RS LDAP *\fIld\fB, char *\fIbase\fB, int \fIscope\fB, char *\fIfilter\fB, char *\fIattrs\fB[], int \fIattrsonly\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB, struct timeval *\fItimeout\fB, int \fIsizelimit\fB, LDAPMessage **\fIres\fB ); .RE .SH DESCRIPTION These routines are used to perform LDAP search operations. The .B ldap_search_ext_s() routine does the search synchronously (i.e., not returning until the operation completes), providing a pointer to the resulting LDAP messages at the location pointed to by the \fIres\fP parameter. .LP The .B ldap_search_ext() routine is the asynchronous version, initiating the search and returning the message id of the operation it initiated in the integer pointed to by the \fImsgidp\fP parameter. .LP The \fIbase\fP parameter is the DN of the entry at which to start the search. .LP The \fIscope\fP parameter is the scope of the search and should be one of LDAP_SCOPE_BASE, to search the object itself, LDAP_SCOPE_ONELEVEL, to search the object's immediate children, LDAP_SCOPE_SUBTREE, to search the object and all its descendants, or LDAP_SCOPE_CHILDREN, to search all of the descendants. Note that the latter requires the server support the LDAP Subordinates Search Scope extension. .LP The \fIfilter\fP is a string representation of the filter to apply in the search. The string should conform to the format specified in RFC 4515 as extended by RFC 4526. For instance, "(cn=Jane Doe)". Note that use of the extension requires the server to support the LDAP Absolute True/False Filter extension. NULL may be specified to indicate the library should send the filter (objectClass=*). .LP The \fIattrs\fP parameter is a null-terminated array of attribute descriptions to return from matching entries. If NULL is specified, the return of all user attributes is requested. The description "*" (LDAP_ALL_USER_ATTRIBUTES) may be used to request all user attributes to be returned. The description "+"(LDAP_ALL_OPERATIONAL_ATTRIBUTES) may be used to request all operational attributes to be returned. Note that this requires the server to support the LDAP All Operational Attribute extension. To request no attributes, the description "1.1" (LDAP_NO_ATTRS) should be listed by itself. .LP The \fIattrsonly\fP parameter should be set to a non-zero value if only attribute descriptions are wanted. It should be set to zero (0) if both attributes descriptions and attribute values are wanted. .LP The \fIserverctrls\fP and \fIclientctrls\fP parameters may be used to specify server and client controls, respectively. .LP The .B ldap_search_ext_s() routine is the synchronous version of .BR ldap_search_ext(). .LP It also returns a code indicating success or, in the case of failure, indicating the nature of the failure of the operation. See .BR ldap_error (3) for details. .SH NOTES Note that both read and list functionality are subsumed by these routines, by using a filter like "(objectclass=*)" and a scope of LDAP_SCOPE_BASE (to emulate read) or LDAP_SCOPE_ONELEVEL (to emulate list). .LP These routines may dynamically allocate memory. The caller is responsible for freeing such memory using supplied deallocation routines. Return values are contained in <ldap.h>. .LP Note that \fIres\fR parameter of .B ldap_search_ext_s() and .B ldap_search_s() should be freed with .B ldap_msgfree() regardless of return value of these functions. .SH DEPRECATED INTERFACES The .B ldap_search() routine is deprecated in favor of the .B ldap_search_ext() routine. The .B ldap_search_s() and .B ldap_search_st() routines are deprecated in favor of the .B ldap_search_ext_s() routine. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 139 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_result (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 145 stdin PK �c\}�q � � man/man3/ldap_add_ext_s.3nu �[��� .lf 1 stdin .TH LDAP_ADD 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_add_ext, ldap_add_ext_s \- Perform an LDAP add operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .ft B #include <ldap.h> .LP .ft B .nf int ldap_add_ext( .RS .ft B LDAP *\fIld, const char *\fIdn\fB, LDAPMod **\fIattrs\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB, int *\fImsgidp\fB ); .RE .LP .ft B .nf int ldap_add_ext_s( .RS LDAP *\fIld\fB, const char *\fIdn\fB, LDAPMod **\fIattrs\fB, LDAPControl *\fIsctrls\fB, LDAPControl *\fIcctrls\fB ); .RE .fi .SH DESCRIPTION The .B ldap_add_ext_s() routine is used to perform an LDAP add operation. It takes \fIdn\fP, the DN of the entry to add, and \fIattrs\fP, a null-terminated array of the entry's attributes. The LDAPMod structure is used to represent attributes, with the \fImod_type\fP and \fImod_values\fP fields being used as described under .BR ldap_modify_ext (3), and the \fIldap_op\fP field being used only if you need to specify the LDAP_MOD_BVALUES option. Otherwise, it should be set to zero. .LP Note that all entries except that specified by the last component in the given DN must already exist. .B ldap_add_ext_s() returns an code indicating success or, in the case of failure, indicating the nature of failure of the operation. See .BR ldap_error (3) for more details. .LP The .B ldap_add_ext() routine works just like .BR ldap_add_ext_s() , but it is asynchronous. It returns the message id of the request it initiated. The result of this operation can be obtained by calling .BR ldap_result (3). .SH DEPRECATED INTERFACES The .BR ldap_add () and .BR ldap_add_s () routines are deprecated in favor of the .BR ldap_add_ext () and .BR ldap_add_ext_s () routines, respectively. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 76 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_modify (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 82 stdin PK �c\Y��X<L <L man/man3/ldap_get_option.3nu �[��� .lf 1 stdin .TH LDAP_GET_OPTION 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_option, ldap_set_option \- LDAP option handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .BI "int ldap_get_option(LDAP *" ld ", int " option ", void *" outvalue ");" .LP .BI "int ldap_set_option(LDAP *" ld ", int " option ", const void *" invalue ");" .SH DESCRIPTION .LP These routines provide access to options stored either in a LDAP handle or as global options, where applicable. They make use of a neutral interface, where the type of the value either retrieved by .BR ldap_get_option (3) or set by .BR ldap_set_option (3) is cast to .BR "void *" . The actual type is determined based on the value of the .B option argument. Global options are set/retrieved by passing a NULL LDAP handle. LDAP handles inherit their default settings from the global options in effect at the time the handle is created. .TP .B LDAP_OPT_API_FEATURE_INFO Fills-in a .BR "LDAPAPIFeatureInfo" ; .BR outvalue must be a .BR "LDAPAPIFeatureInfo *" , pointing to an already allocated struct. The .B ldapaif_info_version field of the struct must be initialized to .B LDAP_FEATURE_INFO_VERSION before making the call. The .B ldapaif_name field must be set to the name of a feature to query. This is a read-only option. .TP .B LDAP_OPT_API_INFO Fills-in a .BR "LDAPAPIInfo" ; .BR outvalue must be a .BR "LDAPAPIInfo *" , pointing to an already allocated struct. The .B ldapai_info_version field of the struct must be initialized to .B LDAP_API_INFO_VERSION before making the call. If the version passed in does not match the current library version, the expected version number will be stored in the struct and the call will fail. The caller is responsible for freeing the elements of the .B ldapai_extensions array and the array itself using .BR ldap_memfree (3). The caller must also free the .BR ldapi_vendor_name . This is a read-only option. .TP .B LDAP_OPT_CLIENT_CONTROLS Sets/gets the client-side controls to be used for all operations. This is now deprecated as modern LDAP C API provides replacements for all main operations which accepts client-side controls as explicit arguments; see for example .BR ldap_search_ext (3), .BR ldap_add_ext (3), .BR ldap_modify_ext (3) and so on. .BR outvalue must be .BR "LDAPControl ***" , and the caller is responsible of freeing the returned controls, if any, by calling .BR ldap_controls_free (3), while .BR invalue must be .BR "LDAPControl *const *" ; the library duplicates the controls passed via .BR invalue . .TP .B LDAP_OPT_CONNECT_ASYNC Sets/gets the status of the asynchronous connect flag. .BR invalue should either be .BR LDAP_OPT_OFF or .BR LDAP_OPT_ON ; .BR outvalue must be .BR "int *" . When set, the library will call .BR connect (2) and return, without waiting for response. This leaves the handle in a connecting state. Subsequent calls to library routines will poll for completion of the connect before performing further operations. As a consequence, library calls that need to establish a connection with a DSA do not block even for the network timeout (option .BR LDAP_OPT_NETWORK_TIMEOUT ). This option is OpenLDAP specific. .TP .B LDAP_OPT_CONNECT_CB This option allows to set a connect callback. .B invalue must be a .BR "const struct ldap_conncb *" . Callbacks are executed in last in-first served order. Handle-specific callbacks are executed first, followed by global ones. Right before freeing the callback structure, the .B lc_del callback handler is passed a .B NULL .BR Sockbuf . Calling .BR ldap_get_option (3) for this option removes the callback whose pointer matches .BR outvalue . This option is OpenLDAP specific. .TP .B LDAP_OPT_DEBUG_LEVEL Sets/gets the debug level of the client library. .BR invalue must be a .BR "const int *" ; .BR outvalue must be a .BR "int *" . Valid debug levels are .BR LDAP_DEBUG_ANY , .BR LDAP_DEBUG_ARGS , .BR LDAP_DEBUG_BER , .BR LDAP_DEBUG_CONNS , .BR LDAP_DEBUG_NONE , .BR LDAP_DEBUG_PACKETS , .BR LDAP_DEBUG_PARSE , and .BR LDAP_DEBUG_TRACE . This option is OpenLDAP specific. .TP .B LDAP_OPT_DEFBASE Sets/gets a string containing the DN to be used as default base for search operations. .BR outvalue must be a .BR "char **" , and the caller is responsible of freeing the returned string by calling .BR ldap_memfree (3), while .BR invalue must be a .BR "const char *" ; the library duplicates the corresponding string. This option is OpenLDAP specific. .TP .B LDAP_OPT_DEREF Sets/gets the value that defines when alias dereferencing must occur. .BR invalue must be .BR "const int *" ; .BR outvalue must be .BR "int *" . They cannot be NULL. The value of .BR *invalue should be one of .BR LDAP_DEREF_NEVER (the default), .BR LDAP_DEREF_SEARCHING , .BR LDAP_DEREF_FINDING , or .BR LDAP_DEREF_ALWAYS . Note that this has ever been the only means to determine alias dereferencing within search operations. .TP .B LDAP_OPT_DESC Returns the file descriptor associated to the socket buffer of the LDAP handle passed in as .BR ld ; .BR outvalue must be a .BR "int *" . This is a read-only, handle-specific option. .TP .B LDAP_OPT_DIAGNOSTIC_MESSAGE Sets/gets a string containing the error string associated to the LDAP handle. This option was formerly known as .BR LDAP_OPT_ERROR_STRING . .BR outvalue must be a .BR "char **" , and the caller is responsible of freeing the returned string by calling .BR ldap_memfree (3), while .BR invalue must be a .BR "char *" ; the library duplicates the corresponding string. .TP .B LDAP_OPT_HOST_NAME Sets/gets a space-separated list of hosts to be contacted by the library when trying to establish a connection. This is now deprecated in favor of .BR LDAP_OPT_URI . .BR outvalue must be a .BR "char **" , and the caller is responsible of freeing the resulting string by calling .BR ldap_memfree (3), while .BR invalue must be a .BR "const char *" ; the library duplicates the corresponding string. .TP .B LDAP_OPT_MATCHED_DN Sets/gets a string containing the matched DN associated to the LDAP handle. .BR outvalue must be a .BR "char **" , and the caller is responsible of freeing the returned string by calling .BR ldap_memfree (3), while .BR invalue must be a .BR "const char *" ; the library duplicates the corresponding string. .TP .B LDAP_OPT_NETWORK_TIMEOUT Sets/gets the network timeout value after which .BR poll (2)/ select (2) following a .BR connect (2) returns in case of no activity. .B outvalue must be a .BR "struct timeval **" (the caller has to free .BR *outvalue ) , and .B invalue must be a .BR "const struct timeval *" . They cannot be NULL. Using a struct with seconds set to \-1 results in an infinite timeout, which is the default. This option is OpenLDAP specific. .TP .B LDAP_OPT_PROTOCOL_VERSION Sets/gets the protocol version. .BR outvalue and .BR invalue must be .BR "int *" . .TP .B LDAP_OPT_REFERRAL_URLS Sets/gets an array containing the referral URIs associated to the LDAP handle. .BR outvalue must be a .BR "char ***" , and the caller is responsible of freeing the returned string by calling .BR ldap_memvfree (3), while .BR invalue must be a NULL-terminated .BR "char *const *" ; the library duplicates the corresponding string. This option is OpenLDAP specific. .TP .B LDAP_OPT_REFERRALS Determines whether the library should implicitly chase referrals or not. .BR invalue must be .BR "const int *" ; its value should either be .BR LDAP_OPT_OFF or .BR LDAP_OPT_ON . .BR outvalue must be .BR "int *" . .\".TP .\".B LDAP_OPT_REFHOPLIMIT .\"This option is OpenLDAP specific. .\"It is not currently implemented. .TP .B LDAP_OPT_RESTART Determines whether the library should implicitly restart connections (FIXME). .BR invalue must be .BR "const int *" ; its value should either be .BR LDAP_OPT_OFF or .BR LDAP_OPT_ON . .BR outvalue must be .BR "int *" . .TP .B LDAP_OPT_RESULT_CODE Sets/gets the LDAP result code associated to the handle. This option was formerly known as .BR LDAP_OPT_ERROR_NUMBER . .BR invalue must be a .BR "const int *" . .BR outvalue must be a .BR "int *" . .TP .B LDAP_OPT_SERVER_CONTROLS Sets/gets the server-side controls to be used for all operations. This is now deprecated as modern LDAP C API provides replacements for all main operations which accepts server-side controls as explicit arguments; see for example .BR ldap_search_ext (3), .BR ldap_add_ext (3), .BR ldap_modify_ext (3) and so on. .BR outvalue must be .BR "LDAPControl ***" , and the caller is responsible of freeing the returned controls, if any, by calling .BR ldap_controls_free (3), while .BR invalue must be .BR "LDAPControl *const *" ; the library duplicates the controls passed via .BR invalue . .TP .B LDAP_OPT_SESSION_REFCNT Returns the reference count associated with the LDAP handle passed in as .BR ld ; .BR outvalue must be a .BR "int *" . This is a read-only, handle-specific option. This option is OpenLDAP specific. .TP .B LDAP_OPT_SIZELIMIT Sets/gets the value that defines the maximum number of entries to be returned by a search operation. .BR invalue must be .BR "const int *" , while .BR outvalue must be .BR "int *" ; They cannot be NULL. .TP .B LDAP_OPT_SOCKBUF Returns a pointer to the socket buffer of the LDAP handle passed in as .BR ld ; .BR outvalue must be a .BR "Sockbuf **" . This is a read-only, handle-specific option. This option is OpenLDAP specific. .TP .B LDAP_OPT_TIMELIMIT Sets/gets the value that defines the time limit after which a search operation should be terminated by the server. .BR invalue must be .BR "const int *" , while .BR outvalue must be .BR "int *" , and they cannot be NULL. .TP .B LDAP_OPT_TIMEOUT Sets/gets a timeout value for the synchronous API calls. .B outvalue must be a .BR "struct timeval **" (the caller has to free .BR *outvalue ) , and .B invalue must be a .BR "struct timeval *" , and they cannot be NULL. Using a struct with seconds set to \-1 results in an infinite timeout, which is the default. This option is OpenLDAP specific. .TP .B LDAP_OPT_URI Sets/gets a comma- or space-separated list of URIs to be contacted by the library when trying to establish a connection. .BR outvalue must be a .BR "char **" , and the caller is responsible of freeing the resulting string by calling .BR ldap_memfree (3), while .BR invalue must be a .BR "const char *" ; the library parses the string into a list of .BR LDAPURLDesc structures, so the invocation of .BR ldap_set_option (3) may fail if URL parsing fails. URIs may only contain the .BR schema , the .BR host , and the .BR port fields. This option is OpenLDAP specific. .SH SASL OPTIONS The SASL options are OpenLDAP specific. .TP .B LDAP_OPT_X_SASL_AUTHCID Gets the SASL authentication identity; .BR outvalue must be a .BR "char **" , its content needs to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_SASL_AUTHZID Gets the SASL authorization identity; .BR outvalue must be a .BR "char **" , its content needs to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_SASL_MAXBUFSIZE Gets/sets SASL maximum buffer size; .BR invalue must be .BR "const ber_len_t *" , while .BR outvalue must be .BR "ber_len_t *" . See also .BR LDAP_OPT_X_SASL_SECPROPS . .TP .B LDAP_OPT_X_SASL_MECH Gets the SASL mechanism; .BR outvalue must be a .BR "char **" , its content needs to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_SASL_MECHLIST Gets the list of the available mechanisms, in form of a NULL-terminated array of strings; .BR outvalue must be .BR "char ***" . The caller must not free or otherwise muck with it. .TP .B LDAP_OPT_X_SASL_NOCANON Sets/gets the NOCANON flag. When unset, the hostname is canonicalized. .BR invalue must be .BR "const int *" ; its value should either be .BR LDAP_OPT_OFF or .BR LDAP_OPT_ON . .BR outvalue must be .BR "int *" . .TP .B LDAP_OPT_X_SASL_REALM Gets the SASL realm; .BR outvalue must be a .BR "char **" , its content needs to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_SASL_SECPROPS Sets the SASL secprops; .BR invalue must be a .BR "char *" , containing a comma-separated list of properties. Legal values are: .BR none , .BR nodict , .BR noplain , .BR noactive , .BR passcred , .BR forwardsec , .BR noanonymous , .BR minssf=<minssf> , .BR maxssf=<maxssf> , .BR maxbufsize=<maxbufsize> . .TP .B LDAP_OPT_X_SASL_SSF Gets the SASL SSF; .BR outvalue must be a .BR "ber_len_t *" . .TP .B LDAP_OPT_X_SASL_SSF_EXTERNAL Sets the SASL SSF value related to an authentication performed using an EXTERNAL mechanism; .BR invalue must be a .BR "const ber_len_t *" . .TP .B LDAP_OPT_X_SASL_SSF_MAX Gets/sets SASL maximum SSF; .BR invalue must be .BR "const ber_len_t *" , while .BR outvalue must be .BR "ber_len_t *" . See also .BR LDAP_OPT_X_SASL_SECPROPS . .TP .B LDAP_OPT_X_SASL_SSF_MIN Gets/sets SASL minimum SSF; .BR invalue must be .BR "const ber_len_t *" , while .BR outvalue must be .BR "ber_len_t *" . See also .BR LDAP_OPT_X_SASL_SECPROPS . .TP .B LDAP_OPT_X_SASL_USERNAME Gets the SASL username; .BR outvalue must be a .BR "char **" . Its content needs to be freed by the caller using .BR ldap_memfree (3). .SH TCP OPTIONS The TCP options are OpenLDAP specific. Mainly intended for use with Linux, they may not be portable. .TP .B LDAP_OPT_X_KEEPALIVE_IDLE Sets/gets the number of seconds a connection needs to remain idle before TCP starts sending keepalive probes. .BR invalue must be .BR "const int *" ; .BR outvalue must be .BR "int *" . .TP .B LDAP_OPT_X_KEEPALIVE_PROBES Sets/gets the maximum number of keepalive probes TCP should send before dropping the connection. .BR invalue must be .BR "const int *" ; .BR outvalue must be .BR "int *" . .TP .B LDAP_OPT_X_KEEPALIVE_INTERVAL Sets/gets the interval in seconds between individual keepalive probes. .BR invalue must be .BR "const int *" ; .BR outvalue must be .BR "int *" . .SH TLS OPTIONS The TLS options are OpenLDAP specific. .\".TP .\".B LDAP_OPT_X_TLS .\"Sets/gets the TLS mode. .TP .B LDAP_OPT_X_TLS_CACERTDIR Sets/gets the path of the directory containing CA certificates. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_TLS_CACERTFILE Sets/gets the full-path of the CA certificate file. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_TLS_CERTFILE Sets/gets the full-path of the certificate file. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_TLS_CIPHER_SUITE Sets/gets the allowed cipher suite. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_TLS_CONNECT_ARG Sets/gets the connection callback argument. .BR invalue must be .BR "const void *" ; .BR outvalue must be .BR "void **" . .TP .B LDAP_OPT_X_TLS_CONNECT_CB Sets/gets the connection callback handle. .BR invalue must be .BR "const LDAP_TLS_CONNECT_CB *" ; .BR outvalue must be .BR "LDAP_TLS_CONNECT_CB **" . .TP .B LDAP_OPT_X_TLS_CRLCHECK Sets/gets the CRL evaluation strategy, one of .BR LDAP_OPT_X_TLS_CRL_NONE , .BR LDAP_OPT_X_TLS_CRL_PEER , or .BR LDAP_OPT_X_TLS_CRL_ALL . .BR invalue must be .BR "const int *" ; .BR outvalue must be .BR "int *" . Requires OpenSSL. .TP .B LDAP_OPT_X_TLS_CRLFILE Sets/gets the full-path of the CRL file. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). This option is only valid for GnuTLS. .TP .B LDAP_OPT_X_TLS_CTX Sets/gets the TLS library context. New TLS sessions will inherit their default settings from this library context. .BR invalue must be .BR "const void *" ; .BR outvalue must be .BR "void **" . When using the OpenSSL library this is an SSL_CTX*. When using other crypto libraries this is a pointer to an OpenLDAP private structure. Applications generally should not use this option or attempt to manipulate this structure. .TP .B LDAP_OPT_X_TLS_DHFILE Gets/sets the full-path of the file containing the parameters for Diffie-Hellman ephemeral key exchange. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). Ignored by GnuTLS and Mozilla NSS. .TP .B LDAP_OPT_X_TLS_KEYFILE Sets/gets the full-path of the certificate key file. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_TLS_NEWCTX Instructs the library to create a new TLS library context. .BR invalue must be .BR "const int *" . A non-zero value pointed to by .BR invalue tells the library to create a context for a server. .TP .B LDAP_OPT_X_TLS_PROTOCOL_MIN Sets/gets the minimum protocol version. .BR invalue must be .BR "const int *" ; .BR outvalue must be .BR "int *" . .TP .B LDAP_OPT_X_TLS_RANDOM_FILE Sets/gets the random file when .B /dev/random and .B /dev/urandom are not available. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). Ignored by GnuTLS older than version 2.2. Ignored by Mozilla NSS. .TP .B LDAP_OPT_X_TLS_REQUIRE_CERT Sets/gets the peer certificate checking strategy, one of .BR LDAP_OPT_X_TLS_NEVER , .BR LDAP_OPT_X_TLS_HARD , .BR LDAP_OPT_X_TLS_DEMAND , .BR LDAP_OPT_X_TLS_ALLOW , .BR LDAP_OPT_X_TLS_TRY . .TP .B LDAP_OPT_X_TLS_SSL_CTX Gets the TLS session context associated with this handle. .BR outvalue must be .BR "void **" . When using the OpenSSL library this is an SSL*. When using other crypto libraries this is a pointer to an OpenLDAP private structure. Applications generally should not use this option. .SH ERRORS On success, the functions return .BR LDAP_OPT_SUCCESS , while they may return .B LDAP_OPT_ERROR to indicate a generic option handling error. Occasionally, more specific errors can be returned, like .B LDAP_NO_MEMORY to indicate a failure in memory allocation. .SH NOTES The LDAP libraries with the .B LDAP_OPT_REFERRALS option set to .B LDAP_OPT_ON (default value) automatically follow referrals using an anonymous bind. Application developers are encouraged to either implement consistent referral chasing features, or explicitly disable referral chasing by setting that option to .BR LDAP_OPT_OFF . .P The protocol version used by the library defaults to LDAPv2 (now historic), which corresponds to the .B LDAP_VERSION2 macro. Application developers are encouraged to explicitly set .B LDAP_OPT_PROTOCOL_VERSION to LDAPv3, using the .B LDAP_VERSION3 macro, or to allow users to select the protocol version. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .B RFC 4422 (http://www.rfc-editor.org), .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 811 stdin PK �c\�5^#v1 v1 man/man3/ber_next_element.3nu �[��� .lf 1 stdin .TH LBER_DECODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");" .LP .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");" .LP .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");" .LP .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");" .LP .BI "ber_tag_t ber_get_null(BerElement *" ber ");" .LP .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");" .LP .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");" .LP .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");" .LP .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the decoding routines in the lber library. See .BR lber-encode (3) for details on the corresponding encoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_get_next () to get the next BER element and .BR ber_scanf () to do the actual decoding. In some cases, .BR ber_peek_tag () may also need to be called in normal usage. The other routines are provided for those applications that need more control than .BR ber_scanf () provides. In general, these routines return the tag of the element decoded, or LBER_ERROR if an error occurred. .LP The .BR ber_get_next () routine is used to read the next BER element from the given Sockbuf, \fIsb\fP. It strips off and returns the leading tag, strips off and returns the length of the entire element in \fIlen\fP, and sets up \fIber\fP for subsequent calls to .BR ber_scanf () et al to decode the element. See .BR lber-sockbuf (3) for details of the Sockbuf implementation of the \fIsb\fP parameter. .LP The .BR ber_scanf () routine is used to decode a BER element in much the same way that .BR scanf (3) works. It reads from \fIber\fP, a pointer to a BerElement such as returned by .BR ber_get_next (), interprets the bytes according to the format string \fIfmt\fP, and stores the results in its additional arguments. 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. .RS .LP .TP 3 .B a Octet string. A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter. The caller should free the returned string using .BR ber_memfree (). .TP .B A Octet string. A variant of "\fBa\fP". A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter, unless a zero-length string would result; in that case, the arg is set to NULL. The caller should free the returned string using .BR ber_memfree (). .TP .B s Octet string. A char * buffer should be supplied, followed by a pointer to a ber_len_t initialized to the size of the buffer. Upon return, the null-terminated octet string is put into the buffer, and the ber_len_t is set to the actual size of the octet string. .TP .B O Octet string. A struct ber_val ** should be supplied, which upon return points to a dynamically allocated struct berval containing the octet string and its length. The caller should free the returned structure using .BR ber_bvfree (). .TP .B o Octet string. A struct ber_val * should be supplied, which upon return contains the dynamically allocated octet string and its length. The caller should free the returned octet string using .BR ber_memfree (). .TP .B m Octet string. A struct ber_val * should be supplied, which upon return contains the octet string and its length. The string resides in memory assigned to the BerElement, and must not be freed by the caller. .TP .B b Boolean. A pointer to a ber_int_t should be supplied. .TP .B e Enumeration. A pointer to a ber_int_t should be supplied. .TP .B i Integer. A pointer to a ber_int_t should be supplied. .TP .B B Bitstring. A char ** should be supplied which will point to the dynamically allocated bits, followed by a ber_len_t *, which will point to the length (in bits) of the bitstring returned. .TP .B n Null. No parameter is required. The element is simply skipped if it is recognized. .TP .B v Sequence of octet strings. A char *** should be supplied, which upon return points to a dynamically allocated null-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty. The caller should free the returned array and octet strings using .BR ber_memvfree (). .TP .B V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon return points to a dynamically allocated null-terminated array of struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvecfree (). .TP .B W Sequence of octet strings with lengths. A BerVarray * should be supplied, which upon return points to a dynamically allocated array of struct berval's containing the octet strings and their lengths. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvarray_free (). .TP .B M Sequence of octet strings with lengths. This is a generalized form of the previous three formats. A void ** (ptr) should be supplied, followed by a ber_len_t * (len) and a ber_len_t (off). Upon return (ptr) will point to a dynamically allocated array whose elements are all of size (*len). A struct berval will be filled starting at offset (off) in each element. The strings in each struct berval reside in memory assigned to the BerElement and must not be freed by the caller. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The number of elements in the array is also stored in (*len) on return. The caller should free the returned array using .BR ber_memfree (). .TP .B l Length of the next element. A pointer to a ber_len_t should be supplied. .TP .B t Tag of the next element. A pointer to a ber_tag_t should be supplied. .TP .B T Skip element and return its tag. A pointer to a ber_tag_t should be supplied. .TP .B x Skip element. The next element is skipped. .TP .B { Begin sequence. No parameter is required. The initial sequence tag and length are skipped. .TP .B } End sequence. No parameter is required and no action is taken. .TP .B [ Begin set. No parameter is required. The initial set tag and length are skipped. .TP .B ] End set. No parameter is required and no action is taken. .RE .LP The .BR ber_get_int () routine tries to interpret the next element as an integer, returning the result in \fInum\fP. The tag of whatever it finds is returned on success, LBER_ERROR (\-1) on failure. .LP The .BR ber_get_stringb () routine is used to read an octet string into a preallocated buffer. The \fIlen\fP parameter should be initialized to the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte. .LP The .BR ber_get_stringa () routine is used to dynamically allocate space into which an octet string is read. The caller should free the returned string using .BR ber_memfree(). .LP The .BR ber_get_stringal () routine is used to dynamically allocate space into which an octet string and its length are read. It takes a struct berval **, and returns the result in this parameter. The caller should free the returned structure using .BR ber_bvfree(). .LP The .BR ber_get_stringbv () routine is used to read an octet string and its length into the provided struct berval *. If the \fIalloc\fP parameter is zero, the string will reside in memory assigned to the BerElement, and must not be freed by the caller. If the \fIalloc\fP parameter is non-zero, the string will be copied into dynamically allocated space which should be returned using .BR ber_memfree (). .LP The .BR ber_get_null () routine is used to read a NULL element. It returns the tag of the element it skips over. .LP The .BR ber_get_boolean () routine is used to read a boolean value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_enum () routine is used to read a enumeration value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_bitstringa () routine is used to read a bitstring value. It takes a char ** which will hold the dynamically allocated bits, followed by an ber_len_t *, which will point to the length (in bits) of the bitstring returned. The caller should free the returned string using .BR ber_memfree (). .LP The .BR ber_first_element () routine is used to return the tag and length of the first element in a set or sequence. It also returns in \fIcookie\fP a magic cookie parameter that should be passed to subsequent calls to ber_next_element(), which returns similar information. .SH EXAMPLES Assume the variable \fIber\fP contains a lightweight BER encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP The element can be decoded using .BR ber_scanf () as follows. .LP .nf ber_int_t scope, deref, size, time, attrsonly; char *dn, **attrs; ber_tag_t tag; tag = ber_scanf( ber, "{aeeiib{v}}", &dn, &scope, &deref, &size, &time, &attrsonly, &attrs ); if( tag == LBER_ERROR ) { /* error */ } else { /* success */ } ber_memfree( dn ); ber_memvfree( attrs ); .fi .SH ERRORS If an error occurs during decoding, generally these routines return LBER_ERROR ((ber_tag_t)\-1). .LP .SH NOTES .LP The return values for all of these functions are declared in the .B <lber.h> header file. Some routines may dynamically allocate memory which must be freed by the caller using supplied deallocation routines. .SH SEE ALSO .BR lber-encode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 358 stdin PK �c\g�d"# "# man/man3/ldap_str2matchingrule.3nu �[��� .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin PK �c\�5^#v1 v1 man/man3/ber_get_bitstring.3nu �[��� .lf 1 stdin .TH LBER_DECODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");" .LP .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");" .LP .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");" .LP .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");" .LP .BI "ber_tag_t ber_get_null(BerElement *" ber ");" .LP .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");" .LP .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");" .LP .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");" .LP .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the decoding routines in the lber library. See .BR lber-encode (3) for details on the corresponding encoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_get_next () to get the next BER element and .BR ber_scanf () to do the actual decoding. In some cases, .BR ber_peek_tag () may also need to be called in normal usage. The other routines are provided for those applications that need more control than .BR ber_scanf () provides. In general, these routines return the tag of the element decoded, or LBER_ERROR if an error occurred. .LP The .BR ber_get_next () routine is used to read the next BER element from the given Sockbuf, \fIsb\fP. It strips off and returns the leading tag, strips off and returns the length of the entire element in \fIlen\fP, and sets up \fIber\fP for subsequent calls to .BR ber_scanf () et al to decode the element. See .BR lber-sockbuf (3) for details of the Sockbuf implementation of the \fIsb\fP parameter. .LP The .BR ber_scanf () routine is used to decode a BER element in much the same way that .BR scanf (3) works. It reads from \fIber\fP, a pointer to a BerElement such as returned by .BR ber_get_next (), interprets the bytes according to the format string \fIfmt\fP, and stores the results in its additional arguments. 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. .RS .LP .TP 3 .B a Octet string. A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter. The caller should free the returned string using .BR ber_memfree (). .TP .B A Octet string. A variant of "\fBa\fP". A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter, unless a zero-length string would result; in that case, the arg is set to NULL. The caller should free the returned string using .BR ber_memfree (). .TP .B s Octet string. A char * buffer should be supplied, followed by a pointer to a ber_len_t initialized to the size of the buffer. Upon return, the null-terminated octet string is put into the buffer, and the ber_len_t is set to the actual size of the octet string. .TP .B O Octet string. A struct ber_val ** should be supplied, which upon return points to a dynamically allocated struct berval containing the octet string and its length. The caller should free the returned structure using .BR ber_bvfree (). .TP .B o Octet string. A struct ber_val * should be supplied, which upon return contains the dynamically allocated octet string and its length. The caller should free the returned octet string using .BR ber_memfree (). .TP .B m Octet string. A struct ber_val * should be supplied, which upon return contains the octet string and its length. The string resides in memory assigned to the BerElement, and must not be freed by the caller. .TP .B b Boolean. A pointer to a ber_int_t should be supplied. .TP .B e Enumeration. A pointer to a ber_int_t should be supplied. .TP .B i Integer. A pointer to a ber_int_t should be supplied. .TP .B B Bitstring. A char ** should be supplied which will point to the dynamically allocated bits, followed by a ber_len_t *, which will point to the length (in bits) of the bitstring returned. .TP .B n Null. No parameter is required. The element is simply skipped if it is recognized. .TP .B v Sequence of octet strings. A char *** should be supplied, which upon return points to a dynamically allocated null-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty. The caller should free the returned array and octet strings using .BR ber_memvfree (). .TP .B V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon return points to a dynamically allocated null-terminated array of struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvecfree (). .TP .B W Sequence of octet strings with lengths. A BerVarray * should be supplied, which upon return points to a dynamically allocated array of struct berval's containing the octet strings and their lengths. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvarray_free (). .TP .B M Sequence of octet strings with lengths. This is a generalized form of the previous three formats. A void ** (ptr) should be supplied, followed by a ber_len_t * (len) and a ber_len_t (off). Upon return (ptr) will point to a dynamically allocated array whose elements are all of size (*len). A struct berval will be filled starting at offset (off) in each element. The strings in each struct berval reside in memory assigned to the BerElement and must not be freed by the caller. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The number of elements in the array is also stored in (*len) on return. The caller should free the returned array using .BR ber_memfree (). .TP .B l Length of the next element. A pointer to a ber_len_t should be supplied. .TP .B t Tag of the next element. A pointer to a ber_tag_t should be supplied. .TP .B T Skip element and return its tag. A pointer to a ber_tag_t should be supplied. .TP .B x Skip element. The next element is skipped. .TP .B { Begin sequence. No parameter is required. The initial sequence tag and length are skipped. .TP .B } End sequence. No parameter is required and no action is taken. .TP .B [ Begin set. No parameter is required. The initial set tag and length are skipped. .TP .B ] End set. No parameter is required and no action is taken. .RE .LP The .BR ber_get_int () routine tries to interpret the next element as an integer, returning the result in \fInum\fP. The tag of whatever it finds is returned on success, LBER_ERROR (\-1) on failure. .LP The .BR ber_get_stringb () routine is used to read an octet string into a preallocated buffer. The \fIlen\fP parameter should be initialized to the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte. .LP The .BR ber_get_stringa () routine is used to dynamically allocate space into which an octet string is read. The caller should free the returned string using .BR ber_memfree(). .LP The .BR ber_get_stringal () routine is used to dynamically allocate space into which an octet string and its length are read. It takes a struct berval **, and returns the result in this parameter. The caller should free the returned structure using .BR ber_bvfree(). .LP The .BR ber_get_stringbv () routine is used to read an octet string and its length into the provided struct berval *. If the \fIalloc\fP parameter is zero, the string will reside in memory assigned to the BerElement, and must not be freed by the caller. If the \fIalloc\fP parameter is non-zero, the string will be copied into dynamically allocated space which should be returned using .BR ber_memfree (). .LP The .BR ber_get_null () routine is used to read a NULL element. It returns the tag of the element it skips over. .LP The .BR ber_get_boolean () routine is used to read a boolean value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_enum () routine is used to read a enumeration value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_bitstringa () routine is used to read a bitstring value. It takes a char ** which will hold the dynamically allocated bits, followed by an ber_len_t *, which will point to the length (in bits) of the bitstring returned. The caller should free the returned string using .BR ber_memfree (). .LP The .BR ber_first_element () routine is used to return the tag and length of the first element in a set or sequence. It also returns in \fIcookie\fP a magic cookie parameter that should be passed to subsequent calls to ber_next_element(), which returns similar information. .SH EXAMPLES Assume the variable \fIber\fP contains a lightweight BER encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP The element can be decoded using .BR ber_scanf () as follows. .LP .nf ber_int_t scope, deref, size, time, attrsonly; char *dn, **attrs; ber_tag_t tag; tag = ber_scanf( ber, "{aeeiib{v}}", &dn, &scope, &deref, &size, &time, &attrsonly, &attrs ); if( tag == LBER_ERROR ) { /* error */ } else { /* success */ } ber_memfree( dn ); ber_memvfree( attrs ); .fi .SH ERRORS If an error occurs during decoding, generally these routines return LBER_ERROR ((ber_tag_t)\-1). .LP .SH NOTES .LP The return values for all of these functions are declared in the .B <lber.h> header file. Some routines may dynamically allocate memory which must be freed by the caller using supplied deallocation routines. .SH SEE ALSO .BR lber-encode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 358 stdin PK �c\� �q q man/man3/ldap_dn2ufn.3nu �[��� .lf 1 stdin .TH LDAP_GET_DN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn \- LDAP DN handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ) .LP .ft B int ldap_str2dn( const char *str, LDAPDN *dn, unsigned flags ) .LP .ft B void ldap_dnfree( LDAPDN dn ) .LP .ft B int ldap_dn2str( LDAPDN dn, char **str, unsigned flags ) .LP .ft B char **ldap_explode_dn( const char *dn, int notypes ) .LP .ft B char **ldap_explode_rdn( const char *rdn, int notypes ) .LP .ft B char *ldap_dn2ufn( const char * dn ) .LP .ft B char *ldap_dn2dcedn( const char * dn ) .LP .ft B char *ldap_dcedn2dn( const char * dn ) .LP .ft B char *ldap_dn2ad_canonical( const char * dn ) .SH DESCRIPTION These routines allow LDAP entry names (Distinguished Names, or DNs) to be obtained, parsed, converted to a user-friendly form, and tested. A DN has the form described in RFC 4414 "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names". .LP The .B ldap_get_dn() routine takes an \fIentry\fP as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3) and returns a copy of the entry's DN. Space for the DN will be obtained dynamically and should be freed by the caller using .BR ldap_memfree (3). .LP .B ldap_str2dn() parses a string representation of a distinguished name contained in .B str into its components, which are stored in .B dn as .B ldap_ava structures, arranged in .B LDAPAVA, .B LDAPRDN, and .B LDAPDN terms. Space for .B dn will be obtained dynamically and should be freed by the caller using .BR ldap_dnfree (3). The .B LDAPDN is defined as: .nf .ft B typedef struct ldap_ava { struct berval la_attr; struct berval la_value; unsigned la_flags; } LDAPAVA; typedef LDAPAVA** LDAPRDN; typedef LDAPRDN* LDAPDN; .ft .fi The attribute types and the attribute values are not normalized. The .B la_flags can be either .B LDAP_AVA_STRING or .B LDAP_AVA_BINARY, the latter meaning that the value is BER/DER encoded and thus must be represented as, quoting from RFC 4514, " ... an octothorpe character ('#' ASCII 35) followed by the hexadecimal representation of each of the bytes of the BER encoding of the X.500 AttributeValue." The .B flags parameter to .B ldap_str2dn() can be .LP .nf LDAP_DN_FORMAT_LDAPV3 LDAP_DN_FORMAT_LDAPV2 LDAP_DN_FORMAT_DCE .fi which defines what DN syntax is expected (according to RFC 4514, RFC 1779 and DCE, respectively). The format can be \fIOR\fPed to the flags .LP .nf LDAP_DN_P_NO_SPACES LDAP_DN_P_NO_SPACE_AFTER_RDN ... LDAP_DN_PEDANTIC .fi The latter is a shortcut for all the previous limitations. .LP .B LDAP_DN_P_NO_SPACES does not allow extra spaces in the dn; the default is to silently eliminate spaces around AVA separators ('='), RDN component separators ('+' for LDAPv3/LDAPv2 or ',' for DCE) and RDN separators (',' LDAPv3/LDAPv2 or '/' for DCE). .LP .B LDAP_DN_P_NO_SPACE_AFTER_RDN does not allow a single space after RDN separators. .LP .B ldap_dn2str() performs the inverse operation, yielding in .B str a string representation of .B dn. It allows the same values for .B flags as .B ldap_str2dn(), plus .LP .nf LDAP_DN_FORMAT_UFN LDAP_DN_FORMAT_AD_CANONICAL .fi for user-friendly naming (RFC 1781) and AD canonical. .LP The following routines are viewed as deprecated in favor of .B ldap_str2dn() and .BR ldap_dn2str(). They are provided to support legacy applications. .LP The .B ldap_explode_dn() routine takes a DN as returned by .B ldap_get_dn() and breaks it up into its component parts. Each part is known as a Relative Distinguished Name, or RDN. .B ldap_explode_dn() returns a NULL-terminated array, each component of which contains an RDN from the DN. The \fInotypes\fP parameter is used to request that only the RDN values be returned, not their types. For example, the DN "cn=Bob, c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob", "US", NULL }, depending on whether notypes was 0 or 1, respectively. Assertion values in RDN strings may included escaped characters. The result can be freed by calling .BR ldap_value_free (3). .LP Similarly, the .B ldap_explode_rdn() routine takes an RDN as returned by .B ldap_explode_dn(dn,0) and breaks it up into its "type=value" component parts (or just "value", if the \fInotypes\fP parameter is set). Note the value is not unescaped. The result can be freed by calling .BR ldap_value_free (3). .LP .B ldap_dn2ufn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a more user-friendly form, stripping off all type names. See "Using the Directory to Achieve User Friendly Naming" (RFC 1781) for more details on the UFN format. Due to the ambiguous nature of the format, it is generally only used for display purposes. The space for the UFN returned is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .LP .B ldap_dn2dcedn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a DCE-style DN, e.g. a string with most-significant to least significant rdns separated by slashes ('/'); rdn components are separated by commas (','). Only printable chars (e.g. LDAPv2 printable string) are allowed, at least in this implementation. .B ldap_dcedn2dn() performs the opposite operation. .B ldap_dn2ad_canonical() turns a DN into a AD canonical name, which is basically a DCE dn with attribute types omitted. The trailing domain, if present, is turned in a DNS-like domain. The space for the returned value is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .SH ERRORS If an error occurs in .BR ldap_get_dn() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .BR ldap_explode_dn() , .BR ldap_explode_rdn() , .B ldap_dn2ufn(), .B ldap_dn2dcedn(), .B ldap_dcedn2dn(), and .B ldap_dn2ad_canonical() will return NULL with .BR errno (3) set appropriately in case of trouble. .SH NOTES These routines dynamically allocate memory that the caller must free. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_first_entry (3), .BR ldap_memfree (3), .BR ldap_value_free (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 247 stdin PK �c\��MK$ K$ man/man3/ber_put_null.3nu �[��� .lf 1 stdin .TH LBER_ENCODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_alloc_t, ber_flush, ber_flush2, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring, ber_put_string, ber_put_null, ber_put_boolean, ber_put_bitstring, ber_start_seq, ber_start_set, ber_put_seq, ber_put_set \- OpenLDAP LBER simplified Basic Encoding Rules library routines for encoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_flush2(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_printf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "int ber_put_int(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_enum(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_ostring(BerElement *" ber ", const char *" str ", ber_len_t " len ", ber_tag_t " tag ");" .LP .BI "int ber_put_string(BerElement *" ber ", const char *" str ", ber_tag_t " tag ");" .LP .BI "int ber_put_null(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_boolean(BerElement *" ber ", ber_int_t " bool ", ber_tag_t " tag ");" .LP .BI "int ber_put_bitstring(BerElement *" ber ", const char *" str ", ber_len_t " blen ", ber_tag_t " tag ");" .LP .BI "int ber_start_seq(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_start_set(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_seq(BerElement *" ber ");" .LP .BI "int ber_put_set(BerElement *" ber ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the encoding routines in the lber library. See .BR lber-decode (3) for details on the corresponding decoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_alloc_t () to allocate a BER element for encoding, .BR ber_printf () to do the actual encoding, and .BR ber_flush2 () to actually write the element. The other routines are provided for those applications that need more control than .BR ber_printf () provides. In general, these routines return the length of the element encoded, or \-1 if an error occurred. .LP The .BR ber_alloc_t () routine is used to allocate a new BER element. It should be called with an argument of LBER_USE_DER. .LP The .BR ber_flush2 () routine is used to actually write the element to a socket (or file) descriptor, once it has been fully encoded (using .BR ber_printf () and friends). See .BR lber-sockbuf (3) for more details on the Sockbuf implementation of the \fIsb\fP parameter. If the \fIfreeit\fP parameter is non-zero, the supplied \fIber\fP will be freed. If \fILBER_FLUSH_FREE_ON_SUCCESS\fP is used, the \fIber\fP is only freed when successfully flushed, otherwise it is left intact; if \fILBER_FLUSH_FREE_ON_ERROR\fP is used, the \fIber\fP is only freed when an error occurs, otherwise it is left intact; if \fILBER_FLUSH_FREE_ALWAYS\fP is used, the \fIber\fP is freed anyway. This function differs from the original .BR ber_flush (3) function, whose behavior corresponds to that indicated for \fILBER_FLUSH_FREE_ON_SUCCESS\fP. Note that in the future, the behavior of .BR ber_flush (3) with \fIfreeit\fP non-zero might change into that of .BR ber_flush2 (3) with \fIfreeit\fP set to \fILBER_FLUSH_FREE_ALWAYS\fP. .LP The .BR ber_printf () routine is used to encode a BER element in much the same way that .BR sprintf (3) works. One important difference, though, is that some state information is kept with the \fIber\fP parameter so that multiple calls can be made to .BR ber_printf () to append things to the end of the BER element. .BR Ber_printf () writes to \fIber\fP, a pointer to a BerElement such as returned by .BR ber_alloc_t (). It interprets and formats its arguments according to the format string \fIfmt\fP. The format string can contain the following characters: .RS .LP .TP 3 .B b Boolean. An ber_int_t parameter should be supplied. A boolean element is output. .TP .B e Enumeration. An ber_int_t parameter should be supplied. An enumeration element is output. .TP .B i Integer. An ber_int_t parameter should be supplied. An integer element is output. .TP .B B Bitstring. A char * pointer to the start of the bitstring is supplied, followed by the number of bits in the bitstring. A bitstring element is output. .TP .B n Null. No parameter is required. A null element is output. .TP .B o Octet string. A char * is supplied, followed by the length of the string pointed to. An octet string element is output. .TP .B O Octet string. A struct berval * is supplied. An octet string element is output. .TP .B s Octet string. A null-terminated string is supplied. An octet string element is output, not including the trailing NULL octet. .TP .B t Tag. A ber_tag_t specifying the tag to give the next element is provided. This works across calls. .TP .B v Several octet strings. A null-terminated array of char *'s is supplied. Note that a construct like '{v}' is required to get an actual SEQUENCE OF octet strings. .TP .B V Several octet strings. A null-terminated array of struct berval *'s is supplied. Note that a construct like '{V}' is required to get an actual SEQUENCE OF octet strings. .TP .B W Several octet strings. An array of struct berval's is supplied. The array is terminated by a struct berval with a NULL bv_val. Note that a construct like '{W}' is required to get an actual SEQUENCE OF octet strings. .TP .B { Begin sequence. No parameter is required. .TP .B } End sequence. No parameter is required. .TP .B [ Begin set. No parameter is required. .TP .B ] End set. No parameter is required. .RE .LP The .BR ber_put_int () routine writes the integer element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_enum () routine writes the enumeration element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_boolean () routine writes the boolean value given by \fIbool\fP to the BER element. .LP The .BR ber_put_bitstring () routine writes \fIblen\fP bits starting at \fIstr\fP as a bitstring value to the given BER element. Note that \fIblen\fP is the length \fIin bits\fP of the bitstring. .LP The .BR ber_put_ostring () routine writes \fIlen\fP bytes starting at \fIstr\fP to the BER element as an octet string. .LP The .BR ber_put_string () routine writes the null-terminated string (minus the terminating '\0') to the BER element as an octet string. .LP The .BR ber_put_null () routine writes a NULL element to the BER element. .LP The .BR ber_start_seq () routine is used to start a sequence in the BER element. The .BR ber_start_set () routine works similarly. The end of the sequence or set is marked by the nearest matching call to .BR ber_put_seq () or .BR ber_put_set (), respectively. .SH EXAMPLES Assuming the following variable declarations, and that the variables have been assigned appropriately, an lber encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP can be achieved like so: .LP .nf int rc; ber_int_t scope, ali, size, time, attrsonly; char *dn, **attrs; BerElement *ber; /* ... fill in values ... */ ber = ber_alloc_t( LBER_USE_DER ); if ( ber == NULL ) { /* error */ } rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali, size, time, attrsonly, attrs ); if( rc == \-1 ) { /* error */ } else { /* success */ } .fi .SH ERRORS If an error occurs during encoding, generally these routines return \-1. .LP .SH NOTES .LP The return values for all of these functions are declared in the <lber.h> header file. .SH SEE ALSO .BR lber-decode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 289 stdin PK �c\}�q � � man/man3/ldap_add_s.3nu �[��� .lf 1 stdin .TH LDAP_ADD 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_add_ext, ldap_add_ext_s \- Perform an LDAP add operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .ft B #include <ldap.h> .LP .ft B .nf int ldap_add_ext( .RS .ft B LDAP *\fIld, const char *\fIdn\fB, LDAPMod **\fIattrs\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB, int *\fImsgidp\fB ); .RE .LP .ft B .nf int ldap_add_ext_s( .RS LDAP *\fIld\fB, const char *\fIdn\fB, LDAPMod **\fIattrs\fB, LDAPControl *\fIsctrls\fB, LDAPControl *\fIcctrls\fB ); .RE .fi .SH DESCRIPTION The .B ldap_add_ext_s() routine is used to perform an LDAP add operation. It takes \fIdn\fP, the DN of the entry to add, and \fIattrs\fP, a null-terminated array of the entry's attributes. The LDAPMod structure is used to represent attributes, with the \fImod_type\fP and \fImod_values\fP fields being used as described under .BR ldap_modify_ext (3), and the \fIldap_op\fP field being used only if you need to specify the LDAP_MOD_BVALUES option. Otherwise, it should be set to zero. .LP Note that all entries except that specified by the last component in the given DN must already exist. .B ldap_add_ext_s() returns an code indicating success or, in the case of failure, indicating the nature of failure of the operation. See .BR ldap_error (3) for more details. .LP The .B ldap_add_ext() routine works just like .BR ldap_add_ext_s() , but it is asynchronous. It returns the message id of the request it initiated. The result of this operation can be obtained by calling .BR ldap_result (3). .SH DEPRECATED INTERFACES The .BR ldap_add () and .BR ldap_add_s () routines are deprecated in favor of the .BR ldap_add_ext () and .BR ldap_add_ext_s () routines, respectively. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 76 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_modify (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 82 stdin PK �c\��� � $ man/man3/ldap_extended_operation_s.3nu �[��� .lf 1 stdin .TH LDAP_EXTENDED_OPERATION 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_extended_operation, ldap_extended_operation_s \- Extends the LDAP operations to the LDAP server. .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_extended_operation( .RS .ft B LDAP *\fIld\fB, const char *\fIrequestoid\fB, const struct berval *\fIrequestdata\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB, int *\fImsgidp\fB ); .RE .LP .ft B int ldap_extended_operation_s( .RS .ft B LDAP *\fIld\fB, const char *\fIrequestoid\fB, const struct berval *\fIrequestdata\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB, char **\fIretoidp\fB, struct berval **\fIretdatap\fB ); .RE .SH DESCRIPTION The .B ldap_extended_operation_s() routine is used to synchronously perform an LDAP extended operation. It takes \fIrequestoid\fP, which points to a dotted-decimal OID string identifying the extended operation to perform. \fIrequestdata\fP is the data required for the request, \fIsctrls\fP is an array of LDAPControl structures to use with this extended operation, \fIcctrls\fP is an array of LDAPControl structures that list the client controls to use with this extended operation. .LP The output parameter \fIretoidp\fP points to a dotted-decimal OID string returned by the LDAP server. The memory used by the string should be freed with the .BR ldap_memfree (3) function. The output parameter \fIretdatap\fP points to a pointer to a berval structure that contains the returned data. If no data is returned by the server, the pointer is set this to NULL. The memory used by this structure should be freed with the .BR ber_bvfree (3) function. .LP The .B ldap_extended_operation() works just like .BR ldap_extended_operation_s() , but the operation is asynchronous. It provides the message id of the request it initiated in the integer pointed to be \fImsgidp\fP. The result of this operation can be obtained by calling .BR ldap_result(3). .SH SEE ALSO .BR ber_bvfree (3), .BR ldap_memfree (3), .BR ldap_parse_extended_result (3), .BR ldap_result (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 76 stdin PK �c\��1ܽ � man/man3/ldap_control_dup.3nu �[��� .lf 1 stdin .TH LDAP_CONTROLS 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_control_create, ldap_control_find, ldap_control_dup, ldap_controls_dup, ldap_control_free, ldap_controls_free \- LDAP control manipulation routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "int ldap_control_create(const char *" oid ", int " iscritical ", struct berval *" value ", int " dupval ", LDAPControl **" ctrlp ");" .LP .BI "LDAPControl *ldap_control_find( const char *" oid ", LDAPControl **" ctrls ", LDAPControl ***" nextctrlp ");" .LP .BI "LDAPControl *ldap_control_dup(LDAPControl *" ctrl ");" .LP .BI "LDAPControl **ldap_controls_dup(LDAPControl **" ctrls ");" .LP .BI "void ldap_control_free(LDAPControl *" ctrl ");" .LP .BI "void ldap_controls_free(LDAPControl **" ctrls ");" .SH DESCRIPTION These routines are used to manipulate structures used for LDAP controls. .BR ldap_control_create () creates a control with the specified .I OID using the contents of the .I value parameter for the control value, if any. The content of .I value is duplicated if .I dupval is non-zero. The .I iscritical parameter must be non-zero for a critical control. The created control is returned in the .I ctrlp parameter. The routine returns .B LDAP_SUCCESS on success or some other error code on failure. The content of .IR value , for supported control types, can be prepared using helpers provided by this implementation of libldap, usually in the form .BR "ldap_create_<control name>_control_value" (). Otherwise, it can be BER-encoded using the functionalities of liblber. .BR ldap_control_find () searches the NULL-terminated .I ctrls array for a control whose OID matches the .I oid parameter. The routine returns a pointer to the control if found, NULL otherwise. If the parameter .I nextctrlp is not NULL, on return it will point to the next control in the array, and can be passed to the .BR ldap_control_find () routine for subsequent calls, to find further occurrences of the same control type. The use of this function is discouraged; the recommended way of handling controls in responses consists in going through the array of controls, dealing with each of them in the returned order, since it could matter. .BR ldap_control_dup () duplicates an individual control structure, and .BR ldap_controls_dup () duplicates a NULL-terminated array of controls. .BR ldap_control_free () frees an individual control structure, and .BR ldap_controls_free () frees a NULL-terminated array of controls. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 85 stdin PK �c\��1ܽ � man/man3/ldap_controls.3nu �[��� .lf 1 stdin .TH LDAP_CONTROLS 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_control_create, ldap_control_find, ldap_control_dup, ldap_controls_dup, ldap_control_free, ldap_controls_free \- LDAP control manipulation routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "int ldap_control_create(const char *" oid ", int " iscritical ", struct berval *" value ", int " dupval ", LDAPControl **" ctrlp ");" .LP .BI "LDAPControl *ldap_control_find( const char *" oid ", LDAPControl **" ctrls ", LDAPControl ***" nextctrlp ");" .LP .BI "LDAPControl *ldap_control_dup(LDAPControl *" ctrl ");" .LP .BI "LDAPControl **ldap_controls_dup(LDAPControl **" ctrls ");" .LP .BI "void ldap_control_free(LDAPControl *" ctrl ");" .LP .BI "void ldap_controls_free(LDAPControl **" ctrls ");" .SH DESCRIPTION These routines are used to manipulate structures used for LDAP controls. .BR ldap_control_create () creates a control with the specified .I OID using the contents of the .I value parameter for the control value, if any. The content of .I value is duplicated if .I dupval is non-zero. The .I iscritical parameter must be non-zero for a critical control. The created control is returned in the .I ctrlp parameter. The routine returns .B LDAP_SUCCESS on success or some other error code on failure. The content of .IR value , for supported control types, can be prepared using helpers provided by this implementation of libldap, usually in the form .BR "ldap_create_<control name>_control_value" (). Otherwise, it can be BER-encoded using the functionalities of liblber. .BR ldap_control_find () searches the NULL-terminated .I ctrls array for a control whose OID matches the .I oid parameter. The routine returns a pointer to the control if found, NULL otherwise. If the parameter .I nextctrlp is not NULL, on return it will point to the next control in the array, and can be passed to the .BR ldap_control_find () routine for subsequent calls, to find further occurrences of the same control type. The use of this function is discouraged; the recommended way of handling controls in responses consists in going through the array of controls, dealing with each of them in the returned order, since it could matter. .BR ldap_control_dup () duplicates an individual control structure, and .BR ldap_controls_dup () duplicates a NULL-terminated array of controls. .BR ldap_control_free () frees an individual control structure, and .BR ldap_controls_free () frees a NULL-terminated array of controls. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 85 stdin PK �c\g�d"# "# man/man3/ldap_schema.3nu �[��� .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin PK �c\���0 0 man/man3/ldap_strdup.3nu �[��� .lf 1 stdin .TH LDAP_MEMORY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_memfree, ldap_memvfree, ldap_memalloc, ldap_memcalloc, ldap_memrealloc, ldap_strdup \- LDAP memory allocation routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "void ldap_memfree(void *" p ");" .LP .BI "void ldap_memvfree(void **" v ");" .LP .BI "void *ldap_memalloc(ber_len_t " s ");" .LP .BI "void *ldap_memcalloc(ber_len_t " n ", ber_len_t " s ");" .LP .BI "void *ldap_memrealloc(void *" p ", ber_len_t " s ");" .LP .BI "char *ldap_strdup(LDAP_CONST char *" p ");" .SH DESCRIPTION These routines are used to allocate/deallocate memory used/returned by the LDAP library. .BR ldap_memalloc (), .BR ldap_memcalloc (), .BR ldap_memrealloc (), and .BR ldap_memfree () are used exactly like the standard .BR malloc (3), .BR calloc (3), .BR realloc (3), and .BR free (3) routines, respectively. The .BR ldap_memvfree () routine is used to free a dynamically allocated array of pointers to arbitrary dynamically allocated objects. The .BR ldap_strdup () routine is used exactly like the standard .BR strdup (3) routine. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 51 stdin PK �c\�շY� � man/man3/ber_bvdup.3nu �[��� .lf 1 stdin .TH LBER_TYPES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_int_t, ber_uint_t, ber_len_t, ber_slen_t, ber_tag_t, struct berval, BerValue, BerVarray, BerElement, ber_bvfree, ber_bvecfree, ber_bvecadd, ber_bvarray_free, ber_bvarray_add, ber_bvdup, ber_dupbv, ber_bvstr, ber_bvstrdup, ber_str2bv, ber_alloc_t, ber_init, ber_init2, ber_free \- OpenLDAP LBER types and allocation functions .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .nf .ft B typedef impl_tag_t ber_tag_t; typedef impl_int_t ber_int_t; typedef impl_uint_t ber_uint_t; typedef impl_len_t ber_len_t; typedef impl_slen_t ber_slen_t; typedef struct berval { ber_len_t bv_len; char *bv_val; } BerValue, *BerVarray; typedef struct berelement BerElement; .ft .fi .LP .BI "void ber_bvfree(struct berval *" bv ");" .LP .BI "void ber_bvecfree(struct berval **" bvec ");" .LP .BI "void ber_bvecadd(struct berval ***" bvec ", struct berval *" bv ");" .LP .BI "void ber_bvarray_free(struct berval *" bvarray ");" .LP .BI "void ber_bvarray_add(BerVarray *" bvarray ", BerValue *" bv ");" .LP .BI "struct berval *ber_bvdup(const struct berval *" bv ");" .LP .BI "struct berval *ber_dupbv(const struct berval *" dst ", struct berval *" src ");" .LP .BI "struct berval *ber_bvstr(const char *" str ");" .LP .BI "struct berval *ber_bvstrdup(const char *" str ");" .LP .BI "struct berval *ber_str2bv(const char *" str ", ber_len_t " len ", int " dup ", struct berval *" bv ");" .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "BerElement *ber_init(struct berval *" bv ");" .LP .BI "void ber_init2(BerElement *" ber ", struct berval *" bv ", int " options ");" .LP .BI "void ber_free(BerElement *" ber ", int " freebuf ");" .SH DESCRIPTION .LP The following are the basic types and structures defined for use with the Lightweight BER library. .LP .B ber_int_t is a signed integer of at least 32 bits. It is commonly equivalent to .BR int . .B ber_uint_t is the unsigned variant of .BR ber_int_t . .LP .B ber_len_t is an unsigned integer of at least 32 bits used to represent a length. It is commonly equivalent to a .BR size_t . .B ber_slen_t is the signed variant to .BR ber_len_t . .LP .B ber_tag_t is an unsigned integer of at least 32 bits used to represent a BER tag. It is commonly equivalent to a .BR unsigned\ long . .LP The actual definitions of the integral impl_TYPE_t types are platform specific. .LP .BR BerValue , commonly used as .BR struct\ berval , is used to hold an arbitrary sequence of octets. .B bv_val points to .B bv_len octets. .B bv_val is not necessarily terminated by a NULL (zero) octet. .BR ber_bvfree () frees a BerValue, pointed to by \fIbv\fP, returned from this API. If \fIbv\fP is NULL, the routine does nothing. .LP .BR ber_bvecfree () frees an array of BerValues (and the array), pointed to by \fIbvec\fP, returned from this API. If \fIbvec\fP is NULL, the routine does nothing. .BR ber_bvecadd () appends the \fIbv\fP pointer to the \fIbvec\fP array. Space for the array is allocated as needed. The end of the array is marked by a NULL pointer. .LP .BR ber_bvarray_free () frees an array of BerValues (and the array), pointed to by \fIbvarray\fP, returned from this API. If \fIbvarray\fP is NULL, the routine does nothing. .BR ber_bvarray_add () appends the contents of the BerValue pointed to by \fIbv\fP to the \fIbvarray\fP array. Space for the new element is allocated as needed. The end of the array is marked by a BerValue with a NULL bv_val field. .LP .BR ber_bvdup () returns a copy of a BerValue. The routine returns NULL upon error (e.g. out of memory). The caller should use .BR ber_bvfree () to deallocate the resulting BerValue. .BR ber_dupbv () copies a BerValue from \fIsrc\fP to \fIdst\fP. If \fIdst\fP is NULL a new BerValue will be allocated to hold the copy. The routine returns NULL upon error, otherwise it returns a pointer to the copy. If \fIdst\fP is NULL the caller should use .BR ber_bvfree () to deallocate the resulting BerValue, otherwise .BR ber_memfree () should be used to deallocate the \fIdst->bv_val\fP. (The .BR ber_bvdup () function is internally implemented as ber_dupbv(NULL, bv). .BR ber_bvdup () is provided only for compatibility with an expired draft of the LDAP C API; .BR ber_dupbv () is the preferred interface.) .LP .BR ber_bvstr () returns a BerValue containing the string pointed to by \fIstr\fP. .BR ber_bvstrdup () returns a BerValue containing a copy of the string pointed to by \fIstr\fP. .BR ber_str2bv () returns a BerValue containing the string pointed to by \fIstr\fP, whose length may be optionally specified in \fIlen\fP. If \fIdup\fP is non-zero, the BerValue will contain a copy of \fIstr\fP. If \fIlen\fP is zero, the number of bytes to copy will be determined by .BR strlen (3), otherwise \fIlen\fP bytes will be copied. If \fIbv\fP is non-NULL, the result will be stored in the given BerValue, otherwise a new BerValue will be allocated to store the result. NOTE: Both .BR ber_bvstr () and .BR ber_bvstrdup () are implemented as macros using .BR ber_str2bv () in this version of the library. .LP .B BerElement is an opaque structure used to maintain state information used in encoding and decoding. .BR ber_alloc_t () is used to create an empty BerElement structure. If .B LBER_USE_DER is specified for the .I options parameter then data lengths for data written to the BerElement will be encoded in the minimal number of octets required, otherwise they will always be written as four byte values. .BR ber_init () creates a BerElement structure that is initialized with a copy of the data in its .I bv parameter. .BR ber_init2 () initializes an existing BerElement .I ber using the data in the .I bv parameter. The data is referenced directly, not copied. The .I options parameter is the same as for .BR ber_alloc_t (). .BR ber_free () frees a BerElement pointed to by \fIber\fP. If \fIber\fP is NULL, the routine does nothing. If \fIfreebuf\fP is zero, the internal buffer is not freed. .SH SEE ALSO .BR lber-encode (3), .BR lber-decode (3), .BR lber-memory (3) .LP .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 189 stdin PK �c\�Q�} & & man/man3/ldap_sync.3nu �[��� .lf 1 stdin .TH LDAP_SYNC 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2006-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_sync_init, ldap_sync_init_refresh_only, ldap_sync_init_refresh_and_persist, ldap_sync_poll \- LDAP sync routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .BI "int ldap_sync_init(ldap_sync_t *" ls ", int " mode ");" .LP .BI "int ldap_sync_init_refresh_only(ldap_sync_t *" ls ");" .LP .BI "int ldap_sync_init_refresh_and_persist(ldap_sync_t *" ls ");" .LP .BI "int ldap_sync_poll(ldap_sync_t *" ls ");" .LP .BI "ldap_sync_t * ldap_sync_initialize(ldap_sync_t *" ls ");" .LP .BI "void ldap_sync_destroy(ldap_sync_t *" ls ", int " freeit ");" .LP .BI "typedef int (*" ldap_sync_search_entry_f ")(ldap_sync_t *" ls "," .RS .BI "LDAPMessage *" msg ", struct berval *" entryUUID "," .BI "ldap_sync_refresh_t " phase ");" .RE .LP .BI "typedef int (*" ldap_sync_search_reference_f ")(ldap_sync_t *" ls "," .RS .BI "LDAPMessage *" msg ");" .RE .LP .BI "typedef int (*" ldap_sync_intermediate_f ")(ldap_sync_t *" ls "," .RS .BI "LDAPMessage *" msg ", BerVarray " syncUUIDs "," .BI "ldap_sync_refresh_t " phase ");" .RE .LP .BI "typedef int (*" ldap_sync_search_result_f ")(ldap_sync_t *" ls "," .RS .BI "LDAPMessage *" msg ", int " refreshDeletes ");" .RE .SH DESCRIPTION .LP These routines provide an interface to the LDAP Content Synchronization operation (RFC 4533). They require an .BR ldap_sync_t structure to be set up with parameters required for various phases of the operation; this includes setting some handlers for special events. All handlers take a pointer to the \fBldap_sync_t\fP structure as the first argument, and a pointer to the \fBLDAPMessage\fP structure as received from the server by the client library, plus, occasionally, other specific arguments. The members of the \fBldap_sync_t\fP structure are: .TP .BI "char *" ls_base The search base; by default, the .B BASE option in .BR ldap.conf (5). .TP .BI "int " ls_scope The search scope (one of .BR LDAP_SCOPE_BASE , .BR LDAP_SCOPE_ONELEVEL , .BR LDAP_SCOPE_SUBORDINATE or .BR LDAP_SCOPE_SUBTREE ; see .B ldap.h for details). .TP .BI "char *" ls_filter The filter (RFC 4515); by default, .BR (objectClass=*) . .TP .BI "char **" ls_attrs The requested attributes; by default .BR NULL , indicating all user attributes. .TP .BI "int " ls_timelimit The requested time limit (in seconds); by default .BR 0 , to indicate no limit. .TP .BI "int " ls_sizelimit The requested size limit (in entries); by default .BR 0 , to indicate no limit. .TP .BI "int " ls_timeout The desired timeout during polling with .BR ldap_sync_poll (3). A value of .BR \-1 means that polling is blocking, so .BR ldap_sync_poll (3) will not return until a message is received; a value of .BR 0 means that polling returns immediately, no matter if any response is available or not; a positive value represents the timeout the .BR ldap_sync_poll (3) function will wait for response before returning, unless a message is received; in that case, .BR ldap_sync_poll (3) returns as soon as the message is available. .TP .BI "ldap_sync_search_entry_f " ls_search_entry A function that is called whenever an entry is returned. The .BR msg argument is the .BR LDAPMessage that contains the searchResultEntry; it can be parsed using the regular client API routines, like .BR ldap_get_dn (3), .BR ldap_first_attribute (3), and so on. The .BR entryUUID argument contains the entryUUID of the entry. The .BR phase argument indicates the type of operation: one of .BR LDAP_SYNC_CAPI_PRESENT , .BR LDAP_SYNC_CAPI_ADD , .BR LDAP_SYNC_CAPI_MODIFY , .BR LDAP_SYNC_CAPI_DELETE ; in case of .BR LDAP_SYNC_CAPI_PRESENT or .BR LDAP_SYNC_CAPI_DELETE , only the DN is contained in the .IR LDAPMessage ; in case of .BR LDAP_SYNC_CAPI_MODIFY , the whole entry is contained in the .IR LDAPMessage , and the application is responsible of determining the differences between the new view of the entry provided by the caller and the data already known. .TP .BI "ldap_sync_search_reference_f " ls_search_reference A function that is called whenever a search reference is returned. The .BR msg argument is the .BR LDAPMessage that contains the searchResultReference; it can be parsed using the regular client API routines, like .BR ldap_parse_reference (3). .TP .BI "ldap_sync_intermediate_f " ls_intermediate A function that is called whenever something relevant occurs during the refresh phase of the search, which is marked by an \fIintermediateResponse\fP message type. The .BR msg argument is the .BR LDAPMessage that contains the intermediate response; it can be parsed using the regular client API routines, like .BR ldap_parse_intermediate (3). The .BR syncUUIDs argument contains an array of UUIDs of the entries that depends on the value of the .BR phase argument. In case of .BR LDAP_SYNC_CAPI_PRESENTS , the "present" phase is being entered; this means that the following sequence of results will consist in entries in "present" sync state. In case of .BR LDAP_SYNC_CAPI_DELETES , the "deletes" phase is being entered; this means that the following sequence of results will consist in entries in "delete" sync state. In case of .BR LDAP_SYNC_CAPI_PRESENTS_IDSET , the message contains a set of UUIDs of entries that are present; it replaces a "presents" phase. In case of .BR LDAP_SYNC_CAPI_DELETES_IDSET , the message contains a set of UUIDs of entries that have been deleted; it replaces a "deletes" phase. In case of .BR LDAP_SYNC_CAPI_DONE, a "presents" phase with "refreshDone" set to "TRUE" has been returned to indicate that the refresh phase of refreshAndPersist is over, and the client should start polling. Except for the .BR LDAP_SYNC_CAPI_PRESENTS_IDSET and .BR LDAP_SYNC_CAPI_DELETES_IDSET cases, .BR syncUUIDs is NULL. .BR .TP .BI "ldap_sync_search_result_f " ls_search_result A function that is called whenever a searchResultDone is returned. In refreshAndPersist this can only occur when the server decides that the search must be interrupted. The .BR msg argument is the .BR LDAPMessage that contains the response; it can be parsed using the regular client API routines, like .BR ldap_parse_result (3). The .BR refreshDeletes argument is not relevant in this case; it should always be \-1. .TP .BI "void *" ls_private A pointer to private data. The client may register here a pointer to data the handlers above may need. .TP .BI "LDAP *" ls_ld A pointer to a LDAP structure that is used to connect to the server. It is the responsibility of the client to initialize the structure and to provide appropriate authentication and security in place. .SH "GENERAL USE" A .B ldap_sync_t structure is initialized by calling .BR ldap_sync_initialize(3). This simply clears out the contents of an already existing .B ldap_sync_t structure, and sets appropriate values for some members. After that, the caller is responsible for setting up the connection (member .BR ls_ld ), eventually setting up transport security (TLS), for binding and any other initialization. The caller must also fill all the documented search-related fields of the .B ldap_sync_t structure. At the end of a session, the structure can be cleaned up by calling .BR ldap_sync_destroy (3), which takes care of freeing all data assuming it was allocated by .BR ldap_mem* (3) routines. Otherwise, the caller should take care of destroying and zeroing out the documented search-related fields, and call .BR ldap_sync_destroy (3) to free undocumented members set by the API. .SH "REFRESH ONLY" The .BR refreshOnly functionality is obtained by periodically calling .BR ldap_sync_init (3) with mode set to .BR LDAP_SYNC_REFRESH_ONLY , or, which is equivalent, by directly calling .BR ldap_sync_init_refresh_only (3). The state of the search, and the consistency of the search parameters, is preserved across calls by passing the .B ldap_sync_t structure as left by the previous call. .SH "REFRESH AND PERSIST" The .BR refreshAndPersist functionality is obtained by calling .BR ldap_sync_init (3) with mode set to .BR LDAP_SYNC_REFRESH_AND_PERSIST , or, which is equivalent, by directly calling .BR ldap_sync_init_refresh_and_persist (3) and, after a successful return, by repeatedly polling with .BR ldap_sync_poll (3) according to the desired pattern. A client may insert a call to .BR ldap_sync_poll (3) into an external loop to check if any modification was returned; in this case, it might be appropriate to set .BR ls_timeout to 0, or to set it to a finite, small value. Otherwise, if the client's main purpose consists in waiting for responses, a timeout of \-1 is most suitable, so that the function only returns after some data has been received and handled. .SH ERRORS All routines return any LDAP error resulting from a lower-level error in the API calls they are based on, or LDAP_SUCCESS in case of success. .BR ldap_sync_poll (3) may return .BR LDAP_SYNC_REFRESH_REQUIRED if a full refresh is requested by the server. In this case, it is appropriate to call .BR ldap_sync_init (3) again, passing the same .B ldap_sync_t structure as resulted from any previous call. .SH NOTES .SH SEE ALSO .BR ldap (3), .BR ldap_search_ext (3), .BR ldap_result (3) ; .B RFC 4533 (http://www.rfc-editor.org), .SH AUTHOR Designed and implemented by Pierangelo Masarati, based on RFC 4533 and loosely inspired by syncrepl code in .BR slapd (8). .SH ACKNOWLEDGEMENTS Initially developed by .BR "SysNet s.n.c." .B OpenLDAP is developed and maintained by The OpenLDAP Project (http://www.openldap.org/). .B OpenLDAP is derived from University of Michigan LDAP 3.3 Release. PK �c\'�t!� � man/man3/ldap_install_tls.3nu �[��� .lf 1 stdin .TH LDAP_TLS 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_start_tls, ldap_start_tls_s, ldap_tls_inplace, ldap_install_tls \- LDAP TLS initialization routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "int ldap_start_tls(LDAP *" ld ");" .LP .BI "int ldap_start_tls_s(LDAP *" ld ", LDAPControl **" serverctrls ", LDAPControl **" clientctrls ");" .LP .BI "int ldap_tls_inplace(LDAP *" ld ");" .LP .BI "int ldap_install_tls(LDAP *" ld ");" .SH DESCRIPTION These routines are used to initiate TLS processing on an LDAP session. .BR ldap_start_tls_s () sends a StartTLS request to a server, waits for the reply, and then installs TLS handlers on the session if the request succeeded. The routine returns .B LDAP_SUCCESS if everything succeeded, otherwise it returns an LDAP error code. .BR ldap_start_tls () sends a StartTLS request to a server and does nothing else. It returns .B LDAP_SUCCESS if the request was sent successfully. .BR ldap_tls_inplace () returns 1 if TLS handlers have been installed on the specified session, 0 otherwise. .BR ldap_install_tls () installs the TLS handlers on the given session. It returns .B LDAP_LOCAL_ERROR if TLS is already installed. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 42 stdin PK �c\�c%u u man/man3/ldap_search_ext_s.3nu �[��� .lf 1 stdin .TH LDAP_SEARCH 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_search, ldap_search_s, ldap_search_st, ldap_search_ext, ldap_search_ext_s \- Perform an LDAP search operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <sys/types.h> #include <ldap.h> .LP .ft B int ldap_search_ext( .RS LDAP *\fIld\fB, char *\fIbase\fB, int \fIscope\fB, char *\fIfilter\fB, char *\fIattrs\fB[], int \fIattrsonly\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB, struct timeval *\fItimeout\fB, int \fIsizelimit\fB, int *\fImsgidp\fB ); .RE .LP .ft B int ldap_search_ext_s( .RS LDAP *\fIld\fB, char *\fIbase\fB, int \fIscope\fB, char *\fIfilter\fB, char *\fIattrs\fB[], int \fIattrsonly\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB, struct timeval *\fItimeout\fB, int \fIsizelimit\fB, LDAPMessage **\fIres\fB ); .RE .SH DESCRIPTION These routines are used to perform LDAP search operations. The .B ldap_search_ext_s() routine does the search synchronously (i.e., not returning until the operation completes), providing a pointer to the resulting LDAP messages at the location pointed to by the \fIres\fP parameter. .LP The .B ldap_search_ext() routine is the asynchronous version, initiating the search and returning the message id of the operation it initiated in the integer pointed to by the \fImsgidp\fP parameter. .LP The \fIbase\fP parameter is the DN of the entry at which to start the search. .LP The \fIscope\fP parameter is the scope of the search and should be one of LDAP_SCOPE_BASE, to search the object itself, LDAP_SCOPE_ONELEVEL, to search the object's immediate children, LDAP_SCOPE_SUBTREE, to search the object and all its descendants, or LDAP_SCOPE_CHILDREN, to search all of the descendants. Note that the latter requires the server support the LDAP Subordinates Search Scope extension. .LP The \fIfilter\fP is a string representation of the filter to apply in the search. The string should conform to the format specified in RFC 4515 as extended by RFC 4526. For instance, "(cn=Jane Doe)". Note that use of the extension requires the server to support the LDAP Absolute True/False Filter extension. NULL may be specified to indicate the library should send the filter (objectClass=*). .LP The \fIattrs\fP parameter is a null-terminated array of attribute descriptions to return from matching entries. If NULL is specified, the return of all user attributes is requested. The description "*" (LDAP_ALL_USER_ATTRIBUTES) may be used to request all user attributes to be returned. The description "+"(LDAP_ALL_OPERATIONAL_ATTRIBUTES) may be used to request all operational attributes to be returned. Note that this requires the server to support the LDAP All Operational Attribute extension. To request no attributes, the description "1.1" (LDAP_NO_ATTRS) should be listed by itself. .LP The \fIattrsonly\fP parameter should be set to a non-zero value if only attribute descriptions are wanted. It should be set to zero (0) if both attributes descriptions and attribute values are wanted. .LP The \fIserverctrls\fP and \fIclientctrls\fP parameters may be used to specify server and client controls, respectively. .LP The .B ldap_search_ext_s() routine is the synchronous version of .BR ldap_search_ext(). .LP It also returns a code indicating success or, in the case of failure, indicating the nature of the failure of the operation. See .BR ldap_error (3) for details. .SH NOTES Note that both read and list functionality are subsumed by these routines, by using a filter like "(objectclass=*)" and a scope of LDAP_SCOPE_BASE (to emulate read) or LDAP_SCOPE_ONELEVEL (to emulate list). .LP These routines may dynamically allocate memory. The caller is responsible for freeing such memory using supplied deallocation routines. Return values are contained in <ldap.h>. .LP Note that \fIres\fR parameter of .B ldap_search_ext_s() and .B ldap_search_s() should be freed with .B ldap_msgfree() regardless of return value of these functions. .SH DEPRECATED INTERFACES The .B ldap_search() routine is deprecated in favor of the .B ldap_search_ext() routine. The .B ldap_search_s() and .B ldap_search_st() routines are deprecated in favor of the .B ldap_search_ext_s() routine. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 139 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_result (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 145 stdin PK �c\ ݴ� man/man3/ldap_url.3nu �[��� .lf 1 stdin .TH LDAP_URL 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_is_ldap_url, ldap_url_parse, ldap_free_urldesc \- LDAP Uniform Resource Locator routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_is_ldap_url( const char *url ) .LP .ft B int ldap_url_parse( const char *url, LDAPURLDesc **ludpp ) .LP typedef struct ldap_url_desc { char * lud_scheme; /* URI scheme */ char * lud_host; /* LDAP host to contact */ int lud_port; /* port on host */ char * lud_dn; /* base for search */ char ** lud_attrs; /* list of attributes */ int lud_scope; /* a LDAP_SCOPE_... value */ char * lud_filter; /* LDAP search filter */ char ** lud_exts; /* LDAP extensions */ int lud_crit_exts; /* true if any extension is critical */ /* may contain additional fields for internal use */ } LDAPURLDesc; .LP .ft B void ldap_free_urldesc( LDAPURLDesc *ludp ); .SH DESCRIPTION These routines support the use of LDAP URLs (Uniform Resource Locators) as detailed in RFC 4516. LDAP URLs look like this: .nf \fBldap://\fP\fIhostport\fP\fB/\fP\fIdn\fP[\fB?\fP\fIattrs\fP[\fB?\fP\fIscope\fP[\fB?\fP\fIfilter\fP[\fB?\fP\fIexts\fP]]]] where: \fIhostport\fP is a host name with an optional ":portnumber" \fIdn\fP is the search base \fIattrs\fP is a comma separated list of attributes to request \fIscope\fP is one of these three strings: base one sub (default=base) \fIfilter\fP is filter \fIexts\fP are recognized set of LDAP and/or API extensions. Example: ldap://ldap.example.net/dc=example,dc=net?cn,sn?sub?(cn=*) .fi .LP URLs that are wrapped in angle-brackets and/or preceded by "URL:" are also tolerated. Alternative LDAP schemes such as ldaps:// and ldapi:// may be parsed using the below routines as well. .LP .B ldap_is_ldap_url() returns a non-zero value if \fIurl\fP looks like an LDAP URL (as opposed to some other kind of URL). It can be used as a quick check for an LDAP URL; the .B ldap_url_parse() routine should be used if a more thorough check is needed. .LP .B ldap_url_parse() breaks down an LDAP URL passed in \fIurl\fP into its component pieces. If successful, zero is returned, an LDAP URL description is allocated, filled in, and \fIludpp\fP is set to point to it. If an error occurs, a non-zero URL error code is returned. .LP .B ldap_free_urldesc() should be called to free an LDAP URL description that was obtained from a call to .B ldap_url_parse(). .SH SEE ALSO .nf .BR ldap (3) .BR "RFC 4516" " <http://www.rfc-editor.org/rfc/rfc4516.txt>" .SH ACKNOWLEDGEMENTS .fi .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 84 stdin PK �c\�� �. �. man/man3/ldap_sasl_bind.3nu �[��� .lf 1 stdin .TH LDAP_BIND 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_bind, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_sasl_bind, ldap_sasl_bind_s, ldap_sasl_interactive_bind_s, ldap_parse_sasl_bind_result, ldap_unbind, ldap_unbind_s, ldap_unbind_ext, ldap_unbind_ext_s, ldap_set_rebind_proc \- LDAP bind routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .BI "int ldap_bind(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_bind_s(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_simple_bind(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_simple_bind_s(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_sasl_bind(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], int *" msgidp ");" .RE .LP .BI "int ldap_sasl_bind_s(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], struct berval **" servercredp ");" .RE .LP .BI "int ldap_parse_sasl_bind_result(LDAP *" ld ", LDAPMessage *" res "," .RS .BI "struct berval **" servercredp ", int " freeit ");" .RE .LP .BI "int ldap_sasl_interactive_bind_s(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ");" .RE .LP .BI "int ldap_sasl_interactive_bind(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ", LDAPMessage *" result "," .BI "const char **" rmechp ", int *" msgidp ");" .RE .LP .BI "int (LDAP_SASL_INTERACT_PROC)(LDAP *" ld ", unsigned " flags ", void *" defaults ", void *" sasl_interact ");" .LP .BI "int ldap_unbind(LDAP *" ld ");" .LP .BI "int ldap_unbind_s(LDAP *" ld ");" .LP .BI "int ldap_unbind_ext(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_unbind_ext_s(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_set_rebind_proc (LDAP *" ld ", LDAP_REBIND_PROC *" ldap_proc ", void *" params ");" .LP .BI "int (LDAP_REBIND_PROC)(LDAP *" ld ", LDAP_CONST char *" url ", ber_tag_t " request ", ber_int_t " msgid ", void *" params ");" .SH DESCRIPTION .LP These routines provide various interfaces to the LDAP bind operation. After an association with an LDAP server is made using .BR ldap_init (3), an LDAP bind operation should be performed before other operations are attempted over the connection. An LDAP bind is required when using Version 2 of the LDAP protocol; it is optional for Version 3 but is usually needed due to security considerations. .LP There are three types of bind calls, ones providing simple authentication, ones providing SASL authentication, and general routines capable of doing either simple or SASL authentication. .LP .B SASL (Simple Authentication and Security Layer) can negotiate one of many different kinds of authentication. Both synchronous and asynchronous versions of each variant of the bind call are provided. All routines take \fIld\fP as their first parameter, as returned from .BR ldap_init (3). .SH SIMPLE AUTHENTICATION The simplest form of the bind call is .BR ldap_simple_bind_s() . It takes the DN to bind as in \fIwho\fP, and the userPassword associated with the entry in \fIpasswd\fP. It returns an LDAP error indication (see .BR ldap_error (3)). The .B ldap_simple_bind() call is asynchronous, taking the same parameters but only initiating the bind operation and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The .B ldap_sasl_bind_s() and asynchronous .B ldap_sasl_bind() functions can also be used to make a simple bind by using LDAP_SASL_SIMPLE as the SASL mechanism. .SH GENERAL AUTHENTICATION The .B ldap_bind() and .B ldap_bind_s() routines can be used when the authentication method to use needs to be selected at runtime. They both take an extra \fImethod\fP parameter selecting the authentication method to use. It should be set to LDAP_AUTH_SIMPLE to select simple authentication. .B ldap_bind() returns the message id of the request it initiates. .B ldap_bind_s() returns an LDAP error indication. .SH SASL AUTHENTICATION For SASL binds the server always ignores any provided DN, so the .I dn parameter should always be NULL. .BR ldap_sasl_bind_s () sends a single SASL bind request with the given SASL .I mechanism and credentials in the .I cred parameter. The format of the credentials depends on the particular SASL mechanism in use. For mechanisms that provide mutual authentication the server's credentials will be returned in the .I servercredp parameter. The routine returns an LDAP error indication (see .BR ldap_error (3)). The .BR ldap_sasl_bind () call is asynchronous, taking the same parameters but only sending the request and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The result must be additionally parsed by .BR ldap_parse_sasl_bind_result () to obtain any server credentials sent from the server. .LP Many SASL mechanisms require multiple message exchanges to perform a complete authentication. Applications should generally use .BR ldap_sasl_interactive_bind_s () rather than calling the basic .BR ldap_sasl_bind () functions directly. The .I mechs parameter should contain a space-separated list of candidate mechanisms to use. If this parameter is NULL or empty the library will query the supportedSASLMechanisms attribute from the server's rootDSE for the list of SASL mechanisms the server supports. The .I flags parameter controls the interaction used to retrieve any necessary SASL authentication parameters and should be one of: .TP LDAP_SASL_AUTOMATIC use defaults if available, prompt otherwise .TP LDAP_SASL_INTERACTIVE always prompt .TP LDAP_SASL_QUIET never prompt .LP The .I interact function uses the provided .I defaults to handle requests from the SASL library for particular authentication parameters. There is no defined format for the .I defaults information; it is up to the caller to use whatever format is appropriate for the supplied .I interact function. The .I sasl_interact parameter comes from the underlying SASL library. When used with Cyrus SASL this is an array of .B sasl_interact_t structures. The Cyrus SASL library will prompt for a variety of inputs, including: .TP SASL_CB_GETREALM the realm for the authentication attempt .TP SASL_CB_AUTHNAME the username to authenticate .TP SASL_CB_PASS the password for the provided username .TP SASL_CB_USER the username to use for proxy authorization .TP SASL_CB_NOECHOPROMPT generic prompt for input with input echoing disabled .TP SASL_CB_ECHOPROMPT generic prompt for input with input echoing enabled .TP SASL_CB_LIST_END indicates the end of the array of prompts .LP See the Cyrus SASL documentation for more details. .LP Applications which need to manage connections asynchronously may use .BR ldap_sasl_interactive_bind () instead of the synchronous version. A valid mechs parameter must be supplied, otherwise the library will be forced to query the server for a list of supported mechanisms, and this query will be performed synchronously. The other parameters are the same as for the synchronous function, with three additional parameters. The actual SASL mechanism that was used, and the message ID for use with .BR ldap_result () will be returned in rmechp and msgidp, respectively. The value in rmechp must not be modified by the caller and must be passed back on each subsequent call. The message obtained from .BR ldap_result () must be passed in the result parameter. This parameter must be NULL when initiating a new Bind. The caller must free the result message after each call using .BR ldap_msgfree (). The .BR ldap_sasl_interactive_bind () function returns an LDAP result code. If the code is LDAP_SASL_BIND_IN_PROGRESS then the Bind is not complete yet, and this function must be called again with the next result from the server. .SH REBINDING .LP The .B ldap_set_rebind_proc function() sets the process to use for binding when an operation returns a referral. This function is used when an application needs to bind to another server in order to follow a referral or search continuation reference. .LP The function takes \fIld\fP, the \fIrebind\fP function, and the \fIparams\fP, the arbitrary data like state information which the client might need to properly rebind. The LDAP_OPT_REFERRALS option in the \fIld\fP must be set to ON for the libraries to use the rebind function. Use the .BR ldap_set_option function to set the value. .LP The rebind function parameters are as follows: .LP The \fIld\fP parameter must be used by the application when binding to the referred server if the application wants the libraries to follow the referral. .LP The \fIurl\fP parameter points to the URL referral string received from the LDAP server. The LDAP application can use the .BR ldap_url_parse (3) function to parse the string into its components. .LP The \fIrequest\fP parameter specifies the type of request that generated the referral. .LP The \fImsgid\fP parameter specifies the message ID of the request generating the referral. .LP The \fIparams\fP parameter is the same value as passed originally to the .BR ldap_set_rebind_proc () function. .LP The LDAP libraries set all the parameters when they call the rebind function. The application should not attempt to free either the ld or the url structures in the rebind function. .LP The application must supply to the rebind function the required authentication information such as, user name, password, and certificates. The rebind function must use a synchronous bind method. .SH UNBINDING The .B ldap_unbind() call is used to unbind from the directory, terminate the current association, and free the resources contained in the \fIld\fP structure. Once it is called, the connection to the LDAP server is closed, and the \fIld\fP structure is invalid. The .B ldap_unbind_s() call is just another name for .BR ldap_unbind() ; both of these calls are synchronous in nature. .LP The .B ldap_unbind_ext() and .B ldap_unbind_ext_s() allows the operations to specify controls. .SH ERRORS Asynchronous routines will return \-1 in case of error, setting the \fIld_errno\fP parameter of the \fIld\fP structure. Synchronous routines return whatever \fIld_errno\fP is set to. See .BR ldap_error (3) for more information. .SH NOTES If an anonymous bind is sufficient for the application, the rebind process need not be provided. The LDAP libraries with the LDAP_OPT_REFERRALS option set to ON (default value) will automatically follow referrals using an anonymous bind. .LP If the application needs stronger authentication than an anonymous bind, you need to provide a rebind process for that authentication method. The bind method must be synchronous. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_open (3), .BR ldap_set_option (3), .BR ldap_url_parse (3) .B RFC 4422 (http://www.rfc-editor.org), .B Cyrus SASL (http://asg.web.cmu.edu/sasl/) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 335 stdin PK �c\�w;+- - man/man3/ldap_count_references.3nu �[��� .lf 1 stdin .TH LDAP_FIRST_REFERENCE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_first_reference, ldap_next_reference, ldap_count_references \- Stepping through continuation references in a result chain .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_count_references( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *reference ) .SH DESCRIPTION .LP These routines are used to step through the continuation references in a result chain received from .BR ldap_result (3) or the synchronous LDAP search operation routines. .LP The .B ldap_first_reference() routine is used to retrieve the first reference message in a result chain. It takes the \fIresult\fP as returned by a call to .BR ldap_result (3) , .BR ldap_search_s (3) or .BR ldap_search_st (3) and returns a pointer to the first reference message in the result chain. .LP This pointer should be supplied on a subsequent call to .B ldap_next_reference() to get the next reference message, the result of which should be supplied to the next call to .BR ldap_next_reference() , etc. .B ldap_next_reference() will return NULL when there are no more reference messages. The reference messages returned from these calls are used by .BR ldap_parse_reference (3) to extract referrals and controls. .LP A count of the number of reference messages in the search result can be obtained by calling .BR ldap_count_references() . It can also be used to count the number of reference messages remaining in a result chain. .SH ERRORS If an error occurs in .B ldap_first_reference() or .BR ldap_next_reference() , NULL is returned. If an error occurs in .BR ldap_count_references() , -1 is returned. .SH SEE ALSO .BR ldap (3), .BR ldap_result (3), .BR ldap_search (3), .BR ldap_parse_reference (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 72 stdin PK �c\��� � " man/man3/ldap_extended_operation.3nu �[��� .lf 1 stdin .TH LDAP_EXTENDED_OPERATION 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_extended_operation, ldap_extended_operation_s \- Extends the LDAP operations to the LDAP server. .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_extended_operation( .RS .ft B LDAP *\fIld\fB, const char *\fIrequestoid\fB, const struct berval *\fIrequestdata\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB, int *\fImsgidp\fB ); .RE .LP .ft B int ldap_extended_operation_s( .RS .ft B LDAP *\fIld\fB, const char *\fIrequestoid\fB, const struct berval *\fIrequestdata\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB, char **\fIretoidp\fB, struct berval **\fIretdatap\fB ); .RE .SH DESCRIPTION The .B ldap_extended_operation_s() routine is used to synchronously perform an LDAP extended operation. It takes \fIrequestoid\fP, which points to a dotted-decimal OID string identifying the extended operation to perform. \fIrequestdata\fP is the data required for the request, \fIsctrls\fP is an array of LDAPControl structures to use with this extended operation, \fIcctrls\fP is an array of LDAPControl structures that list the client controls to use with this extended operation. .LP The output parameter \fIretoidp\fP points to a dotted-decimal OID string returned by the LDAP server. The memory used by the string should be freed with the .BR ldap_memfree (3) function. The output parameter \fIretdatap\fP points to a pointer to a berval structure that contains the returned data. If no data is returned by the server, the pointer is set this to NULL. The memory used by this structure should be freed with the .BR ber_bvfree (3) function. .LP The .B ldap_extended_operation() works just like .BR ldap_extended_operation_s() , but the operation is asynchronous. It provides the message id of the request it initiated in the integer pointed to be \fImsgidp\fP. The result of this operation can be obtained by calling .BR ldap_result(3). .SH SEE ALSO .BR ber_bvfree (3), .BR ldap_memfree (3), .BR ldap_parse_extended_result (3), .BR ldap_result (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 76 stdin PK �c\�4�� � man/man3/ldap_modify_ext_s.3nu �[��� .lf 1 stdin .TH LDAP_MODIFY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_modify_ext, ldap_modify_ext_s \- Perform an LDAP modify operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_modify_ext( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, LDAPMod *\fImods[]\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB, int *\fImsgidp\fB ); .RE .LP .nf .ft B int ldap_modify_ext_s( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, LDAPMod *\fImods[]\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB ); .RE .LP .nf .ft B void ldap_mods_free( .RS .ft B LDAPMod **\fImods\fB, int \fIfreemods\fB ); .RE .SH DESCRIPTION The routine .B ldap_modify_ext_s() is used to perform an LDAP modify operation. \fIdn\fP is the DN of the entry to modify, and \fImods\fP is a null-terminated array of modifications to make to the entry. Each element of the \fImods\fP array is a pointer to an LDAPMod structure, which is defined below. .LP .nf typedef struct ldapmod { int mod_op; char *mod_type; union { char **modv_strvals; struct berval **modv_bvals; } mod_vals; struct ldapmod *mod_next; } LDAPMod; #define mod_values mod_vals.modv_strvals #define mod_bvalues mod_vals.modv_bvals .ft .fi .LP The \fImod_op\fP field is used to specify the type of modification to perform and should be one of LDAP_MOD_ADD, LDAP_MOD_DELETE, or LDAP_MOD_REPLACE. The \fImod_type\fP and \fImod_values\fP fields specify the attribute type to modify and a null-terminated array of values to add, delete, or replace respectively. The \fImod_next\fP field is used only by the LDAP server and may be ignored by the client. .LP If you need to specify a non-string value (e.g., to add a photo or audio attribute value), you should set \fImod_op\fP to the logical OR of the operation as above (e.g., LDAP_MOD_REPLACE) and the constant LDAP_MOD_BVALUES. In this case, \fImod_bvalues\fP should be used instead of \fImod_values\fP, and it should point to a null-terminated array of struct bervals, as defined in <lber.h>. .LP 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 attribute is to be deleted, the \fImod_values\fP field should be set to NULL. For LDAP_MOD_REPLACE modifications, the attribute will have the listed values after the modification, having been created if necessary. All modifications are performed in the order in which they are listed. .LP .B ldap_mods_free() can be used to free each element of a NULL-terminated array of mod structures. If \fIfreemods\fP is non-zero, the \fImods\fP pointer itself is freed as well. .LP .B ldap_modify_ext_s() returns a code indicating success or, in the case of failure, indicating the nature of the failure. See .BR ldap_error (3) for details .LP The .B ldap_modify_ext() operation works the same way as .BR ldap_modify_ext_s() , except that it is asynchronous. The integer that \fImsgidp\fP points to is set to the message id of the modify request. The result of the operation can be obtained by calling .BR ldap_result (3). .LP Both .B ldap_modify_ext() and .B ldap_modify_ext_s() allows server and client controls to be passed in via the sctrls and cctrls parameters, respectively. .SH DEPRECATED INTERFACES The .B ldap_modify() and .B ldap_modify_s() routines are deprecated in favor of the .B ldap_modify_ext() and .B ldap_modify_ext_s() routines, respectively. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 132 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 137 stdin PK �c\� �q q man/man3/ldap_dn2ad_canonical.3nu �[��� .lf 1 stdin .TH LDAP_GET_DN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn \- LDAP DN handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ) .LP .ft B int ldap_str2dn( const char *str, LDAPDN *dn, unsigned flags ) .LP .ft B void ldap_dnfree( LDAPDN dn ) .LP .ft B int ldap_dn2str( LDAPDN dn, char **str, unsigned flags ) .LP .ft B char **ldap_explode_dn( const char *dn, int notypes ) .LP .ft B char **ldap_explode_rdn( const char *rdn, int notypes ) .LP .ft B char *ldap_dn2ufn( const char * dn ) .LP .ft B char *ldap_dn2dcedn( const char * dn ) .LP .ft B char *ldap_dcedn2dn( const char * dn ) .LP .ft B char *ldap_dn2ad_canonical( const char * dn ) .SH DESCRIPTION These routines allow LDAP entry names (Distinguished Names, or DNs) to be obtained, parsed, converted to a user-friendly form, and tested. A DN has the form described in RFC 4414 "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names". .LP The .B ldap_get_dn() routine takes an \fIentry\fP as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3) and returns a copy of the entry's DN. Space for the DN will be obtained dynamically and should be freed by the caller using .BR ldap_memfree (3). .LP .B ldap_str2dn() parses a string representation of a distinguished name contained in .B str into its components, which are stored in .B dn as .B ldap_ava structures, arranged in .B LDAPAVA, .B LDAPRDN, and .B LDAPDN terms. Space for .B dn will be obtained dynamically and should be freed by the caller using .BR ldap_dnfree (3). The .B LDAPDN is defined as: .nf .ft B typedef struct ldap_ava { struct berval la_attr; struct berval la_value; unsigned la_flags; } LDAPAVA; typedef LDAPAVA** LDAPRDN; typedef LDAPRDN* LDAPDN; .ft .fi The attribute types and the attribute values are not normalized. The .B la_flags can be either .B LDAP_AVA_STRING or .B LDAP_AVA_BINARY, the latter meaning that the value is BER/DER encoded and thus must be represented as, quoting from RFC 4514, " ... an octothorpe character ('#' ASCII 35) followed by the hexadecimal representation of each of the bytes of the BER encoding of the X.500 AttributeValue." The .B flags parameter to .B ldap_str2dn() can be .LP .nf LDAP_DN_FORMAT_LDAPV3 LDAP_DN_FORMAT_LDAPV2 LDAP_DN_FORMAT_DCE .fi which defines what DN syntax is expected (according to RFC 4514, RFC 1779 and DCE, respectively). The format can be \fIOR\fPed to the flags .LP .nf LDAP_DN_P_NO_SPACES LDAP_DN_P_NO_SPACE_AFTER_RDN ... LDAP_DN_PEDANTIC .fi The latter is a shortcut for all the previous limitations. .LP .B LDAP_DN_P_NO_SPACES does not allow extra spaces in the dn; the default is to silently eliminate spaces around AVA separators ('='), RDN component separators ('+' for LDAPv3/LDAPv2 or ',' for DCE) and RDN separators (',' LDAPv3/LDAPv2 or '/' for DCE). .LP .B LDAP_DN_P_NO_SPACE_AFTER_RDN does not allow a single space after RDN separators. .LP .B ldap_dn2str() performs the inverse operation, yielding in .B str a string representation of .B dn. It allows the same values for .B flags as .B ldap_str2dn(), plus .LP .nf LDAP_DN_FORMAT_UFN LDAP_DN_FORMAT_AD_CANONICAL .fi for user-friendly naming (RFC 1781) and AD canonical. .LP The following routines are viewed as deprecated in favor of .B ldap_str2dn() and .BR ldap_dn2str(). They are provided to support legacy applications. .LP The .B ldap_explode_dn() routine takes a DN as returned by .B ldap_get_dn() and breaks it up into its component parts. Each part is known as a Relative Distinguished Name, or RDN. .B ldap_explode_dn() returns a NULL-terminated array, each component of which contains an RDN from the DN. The \fInotypes\fP parameter is used to request that only the RDN values be returned, not their types. For example, the DN "cn=Bob, c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob", "US", NULL }, depending on whether notypes was 0 or 1, respectively. Assertion values in RDN strings may included escaped characters. The result can be freed by calling .BR ldap_value_free (3). .LP Similarly, the .B ldap_explode_rdn() routine takes an RDN as returned by .B ldap_explode_dn(dn,0) and breaks it up into its "type=value" component parts (or just "value", if the \fInotypes\fP parameter is set). Note the value is not unescaped. The result can be freed by calling .BR ldap_value_free (3). .LP .B ldap_dn2ufn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a more user-friendly form, stripping off all type names. See "Using the Directory to Achieve User Friendly Naming" (RFC 1781) for more details on the UFN format. Due to the ambiguous nature of the format, it is generally only used for display purposes. The space for the UFN returned is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .LP .B ldap_dn2dcedn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a DCE-style DN, e.g. a string with most-significant to least significant rdns separated by slashes ('/'); rdn components are separated by commas (','). Only printable chars (e.g. LDAPv2 printable string) are allowed, at least in this implementation. .B ldap_dcedn2dn() performs the opposite operation. .B ldap_dn2ad_canonical() turns a DN into a AD canonical name, which is basically a DCE dn with attribute types omitted. The trailing domain, if present, is turned in a DNS-like domain. The space for the returned value is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .SH ERRORS If an error occurs in .BR ldap_get_dn() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .BR ldap_explode_dn() , .BR ldap_explode_rdn() , .B ldap_dn2ufn(), .B ldap_dn2dcedn(), .B ldap_dcedn2dn(), and .B ldap_dn2ad_canonical() will return NULL with .BR errno (3) set appropriately in case of trouble. .SH NOTES These routines dynamically allocate memory that the caller must free. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_first_entry (3), .BR ldap_memfree (3), .BR ldap_value_free (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 247 stdin PK �c\g�d"# "# man/man3/ldap_scherr2str.3nu �[��� .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin PK �c\�4�� � man/man3/ldap_modify.3nu �[��� .lf 1 stdin .TH LDAP_MODIFY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_modify_ext, ldap_modify_ext_s \- Perform an LDAP modify operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_modify_ext( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, LDAPMod *\fImods[]\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB, int *\fImsgidp\fB ); .RE .LP .nf .ft B int ldap_modify_ext_s( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, LDAPMod *\fImods[]\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB ); .RE .LP .nf .ft B void ldap_mods_free( .RS .ft B LDAPMod **\fImods\fB, int \fIfreemods\fB ); .RE .SH DESCRIPTION The routine .B ldap_modify_ext_s() is used to perform an LDAP modify operation. \fIdn\fP is the DN of the entry to modify, and \fImods\fP is a null-terminated array of modifications to make to the entry. Each element of the \fImods\fP array is a pointer to an LDAPMod structure, which is defined below. .LP .nf typedef struct ldapmod { int mod_op; char *mod_type; union { char **modv_strvals; struct berval **modv_bvals; } mod_vals; struct ldapmod *mod_next; } LDAPMod; #define mod_values mod_vals.modv_strvals #define mod_bvalues mod_vals.modv_bvals .ft .fi .LP The \fImod_op\fP field is used to specify the type of modification to perform and should be one of LDAP_MOD_ADD, LDAP_MOD_DELETE, or LDAP_MOD_REPLACE. The \fImod_type\fP and \fImod_values\fP fields specify the attribute type to modify and a null-terminated array of values to add, delete, or replace respectively. The \fImod_next\fP field is used only by the LDAP server and may be ignored by the client. .LP If you need to specify a non-string value (e.g., to add a photo or audio attribute value), you should set \fImod_op\fP to the logical OR of the operation as above (e.g., LDAP_MOD_REPLACE) and the constant LDAP_MOD_BVALUES. In this case, \fImod_bvalues\fP should be used instead of \fImod_values\fP, and it should point to a null-terminated array of struct bervals, as defined in <lber.h>. .LP 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 attribute is to be deleted, the \fImod_values\fP field should be set to NULL. For LDAP_MOD_REPLACE modifications, the attribute will have the listed values after the modification, having been created if necessary. All modifications are performed in the order in which they are listed. .LP .B ldap_mods_free() can be used to free each element of a NULL-terminated array of mod structures. If \fIfreemods\fP is non-zero, the \fImods\fP pointer itself is freed as well. .LP .B ldap_modify_ext_s() returns a code indicating success or, in the case of failure, indicating the nature of the failure. See .BR ldap_error (3) for details .LP The .B ldap_modify_ext() operation works the same way as .BR ldap_modify_ext_s() , except that it is asynchronous. The integer that \fImsgidp\fP points to is set to the message id of the modify request. The result of the operation can be obtained by calling .BR ldap_result (3). .LP Both .B ldap_modify_ext() and .B ldap_modify_ext_s() allows server and client controls to be passed in via the sctrls and cctrls parameters, respectively. .SH DEPRECATED INTERFACES The .B ldap_modify() and .B ldap_modify_s() routines are deprecated in favor of the .B ldap_modify_ext() and .B ldap_modify_ext_s() routines, respectively. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 132 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 137 stdin PK �c\ V�H- - man/man3/ldap_abandon.3nu �[��� .lf 1 stdin .TH LDAP_ABANDON 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_abandon_ext \- Abandon an LDAP operation in progress .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .ft B int ldap_abandon_ext( .RS .ft B LDAP *\fIld\fB, Bint \fImsgid\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB ); .RE .fi .SH DESCRIPTION The .B ldap_abandon_ext() routine is used to send a LDAP Abandon request for an operation in progress. The \fImsgid\fP passed should be the message id of an outstanding LDAP operation, such as returned by .BR ldap_search_ext (3). .LP .BR ldap_abandon_ext () checks to see if the result of the operation has already come in. If it has, it deletes it from the queue of pending messages. If not, it sends an LDAP abandon request to the LDAP server. .LP The caller can expect that the result of an abandoned operation will not be returned from a future call to .BR ldap_result (3). .LP .B ldap_abandon_ext() allows server and client controls to be passed in via the .I sctrls and .I cctrls parameters, respectively. .LP .B ldap_abandon_ext() returns a code indicating success or, in the case of failure, the nature of the failure. See .BR ldap_error (3) for details. .SH DEPRECATED INTERFACES The .B ldap_abandon() routine is deprecated in favor of the .B ldap_abandon_ext() routine. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 61 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_result (3), .BR ldap_search_ext (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 69 stdin PK �c\Y��X<L <L man/man3/ldap_set_option.3nu �[��� .lf 1 stdin .TH LDAP_GET_OPTION 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_option, ldap_set_option \- LDAP option handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .BI "int ldap_get_option(LDAP *" ld ", int " option ", void *" outvalue ");" .LP .BI "int ldap_set_option(LDAP *" ld ", int " option ", const void *" invalue ");" .SH DESCRIPTION .LP These routines provide access to options stored either in a LDAP handle or as global options, where applicable. They make use of a neutral interface, where the type of the value either retrieved by .BR ldap_get_option (3) or set by .BR ldap_set_option (3) is cast to .BR "void *" . The actual type is determined based on the value of the .B option argument. Global options are set/retrieved by passing a NULL LDAP handle. LDAP handles inherit their default settings from the global options in effect at the time the handle is created. .TP .B LDAP_OPT_API_FEATURE_INFO Fills-in a .BR "LDAPAPIFeatureInfo" ; .BR outvalue must be a .BR "LDAPAPIFeatureInfo *" , pointing to an already allocated struct. The .B ldapaif_info_version field of the struct must be initialized to .B LDAP_FEATURE_INFO_VERSION before making the call. The .B ldapaif_name field must be set to the name of a feature to query. This is a read-only option. .TP .B LDAP_OPT_API_INFO Fills-in a .BR "LDAPAPIInfo" ; .BR outvalue must be a .BR "LDAPAPIInfo *" , pointing to an already allocated struct. The .B ldapai_info_version field of the struct must be initialized to .B LDAP_API_INFO_VERSION before making the call. If the version passed in does not match the current library version, the expected version number will be stored in the struct and the call will fail. The caller is responsible for freeing the elements of the .B ldapai_extensions array and the array itself using .BR ldap_memfree (3). The caller must also free the .BR ldapi_vendor_name . This is a read-only option. .TP .B LDAP_OPT_CLIENT_CONTROLS Sets/gets the client-side controls to be used for all operations. This is now deprecated as modern LDAP C API provides replacements for all main operations which accepts client-side controls as explicit arguments; see for example .BR ldap_search_ext (3), .BR ldap_add_ext (3), .BR ldap_modify_ext (3) and so on. .BR outvalue must be .BR "LDAPControl ***" , and the caller is responsible of freeing the returned controls, if any, by calling .BR ldap_controls_free (3), while .BR invalue must be .BR "LDAPControl *const *" ; the library duplicates the controls passed via .BR invalue . .TP .B LDAP_OPT_CONNECT_ASYNC Sets/gets the status of the asynchronous connect flag. .BR invalue should either be .BR LDAP_OPT_OFF or .BR LDAP_OPT_ON ; .BR outvalue must be .BR "int *" . When set, the library will call .BR connect (2) and return, without waiting for response. This leaves the handle in a connecting state. Subsequent calls to library routines will poll for completion of the connect before performing further operations. As a consequence, library calls that need to establish a connection with a DSA do not block even for the network timeout (option .BR LDAP_OPT_NETWORK_TIMEOUT ). This option is OpenLDAP specific. .TP .B LDAP_OPT_CONNECT_CB This option allows to set a connect callback. .B invalue must be a .BR "const struct ldap_conncb *" . Callbacks are executed in last in-first served order. Handle-specific callbacks are executed first, followed by global ones. Right before freeing the callback structure, the .B lc_del callback handler is passed a .B NULL .BR Sockbuf . Calling .BR ldap_get_option (3) for this option removes the callback whose pointer matches .BR outvalue . This option is OpenLDAP specific. .TP .B LDAP_OPT_DEBUG_LEVEL Sets/gets the debug level of the client library. .BR invalue must be a .BR "const int *" ; .BR outvalue must be a .BR "int *" . Valid debug levels are .BR LDAP_DEBUG_ANY , .BR LDAP_DEBUG_ARGS , .BR LDAP_DEBUG_BER , .BR LDAP_DEBUG_CONNS , .BR LDAP_DEBUG_NONE , .BR LDAP_DEBUG_PACKETS , .BR LDAP_DEBUG_PARSE , and .BR LDAP_DEBUG_TRACE . This option is OpenLDAP specific. .TP .B LDAP_OPT_DEFBASE Sets/gets a string containing the DN to be used as default base for search operations. .BR outvalue must be a .BR "char **" , and the caller is responsible of freeing the returned string by calling .BR ldap_memfree (3), while .BR invalue must be a .BR "const char *" ; the library duplicates the corresponding string. This option is OpenLDAP specific. .TP .B LDAP_OPT_DEREF Sets/gets the value that defines when alias dereferencing must occur. .BR invalue must be .BR "const int *" ; .BR outvalue must be .BR "int *" . They cannot be NULL. The value of .BR *invalue should be one of .BR LDAP_DEREF_NEVER (the default), .BR LDAP_DEREF_SEARCHING , .BR LDAP_DEREF_FINDING , or .BR LDAP_DEREF_ALWAYS . Note that this has ever been the only means to determine alias dereferencing within search operations. .TP .B LDAP_OPT_DESC Returns the file descriptor associated to the socket buffer of the LDAP handle passed in as .BR ld ; .BR outvalue must be a .BR "int *" . This is a read-only, handle-specific option. .TP .B LDAP_OPT_DIAGNOSTIC_MESSAGE Sets/gets a string containing the error string associated to the LDAP handle. This option was formerly known as .BR LDAP_OPT_ERROR_STRING . .BR outvalue must be a .BR "char **" , and the caller is responsible of freeing the returned string by calling .BR ldap_memfree (3), while .BR invalue must be a .BR "char *" ; the library duplicates the corresponding string. .TP .B LDAP_OPT_HOST_NAME Sets/gets a space-separated list of hosts to be contacted by the library when trying to establish a connection. This is now deprecated in favor of .BR LDAP_OPT_URI . .BR outvalue must be a .BR "char **" , and the caller is responsible of freeing the resulting string by calling .BR ldap_memfree (3), while .BR invalue must be a .BR "const char *" ; the library duplicates the corresponding string. .TP .B LDAP_OPT_MATCHED_DN Sets/gets a string containing the matched DN associated to the LDAP handle. .BR outvalue must be a .BR "char **" , and the caller is responsible of freeing the returned string by calling .BR ldap_memfree (3), while .BR invalue must be a .BR "const char *" ; the library duplicates the corresponding string. .TP .B LDAP_OPT_NETWORK_TIMEOUT Sets/gets the network timeout value after which .BR poll (2)/ select (2) following a .BR connect (2) returns in case of no activity. .B outvalue must be a .BR "struct timeval **" (the caller has to free .BR *outvalue ) , and .B invalue must be a .BR "const struct timeval *" . They cannot be NULL. Using a struct with seconds set to \-1 results in an infinite timeout, which is the default. This option is OpenLDAP specific. .TP .B LDAP_OPT_PROTOCOL_VERSION Sets/gets the protocol version. .BR outvalue and .BR invalue must be .BR "int *" . .TP .B LDAP_OPT_REFERRAL_URLS Sets/gets an array containing the referral URIs associated to the LDAP handle. .BR outvalue must be a .BR "char ***" , and the caller is responsible of freeing the returned string by calling .BR ldap_memvfree (3), while .BR invalue must be a NULL-terminated .BR "char *const *" ; the library duplicates the corresponding string. This option is OpenLDAP specific. .TP .B LDAP_OPT_REFERRALS Determines whether the library should implicitly chase referrals or not. .BR invalue must be .BR "const int *" ; its value should either be .BR LDAP_OPT_OFF or .BR LDAP_OPT_ON . .BR outvalue must be .BR "int *" . .\".TP .\".B LDAP_OPT_REFHOPLIMIT .\"This option is OpenLDAP specific. .\"It is not currently implemented. .TP .B LDAP_OPT_RESTART Determines whether the library should implicitly restart connections (FIXME). .BR invalue must be .BR "const int *" ; its value should either be .BR LDAP_OPT_OFF or .BR LDAP_OPT_ON . .BR outvalue must be .BR "int *" . .TP .B LDAP_OPT_RESULT_CODE Sets/gets the LDAP result code associated to the handle. This option was formerly known as .BR LDAP_OPT_ERROR_NUMBER . .BR invalue must be a .BR "const int *" . .BR outvalue must be a .BR "int *" . .TP .B LDAP_OPT_SERVER_CONTROLS Sets/gets the server-side controls to be used for all operations. This is now deprecated as modern LDAP C API provides replacements for all main operations which accepts server-side controls as explicit arguments; see for example .BR ldap_search_ext (3), .BR ldap_add_ext (3), .BR ldap_modify_ext (3) and so on. .BR outvalue must be .BR "LDAPControl ***" , and the caller is responsible of freeing the returned controls, if any, by calling .BR ldap_controls_free (3), while .BR invalue must be .BR "LDAPControl *const *" ; the library duplicates the controls passed via .BR invalue . .TP .B LDAP_OPT_SESSION_REFCNT Returns the reference count associated with the LDAP handle passed in as .BR ld ; .BR outvalue must be a .BR "int *" . This is a read-only, handle-specific option. This option is OpenLDAP specific. .TP .B LDAP_OPT_SIZELIMIT Sets/gets the value that defines the maximum number of entries to be returned by a search operation. .BR invalue must be .BR "const int *" , while .BR outvalue must be .BR "int *" ; They cannot be NULL. .TP .B LDAP_OPT_SOCKBUF Returns a pointer to the socket buffer of the LDAP handle passed in as .BR ld ; .BR outvalue must be a .BR "Sockbuf **" . This is a read-only, handle-specific option. This option is OpenLDAP specific. .TP .B LDAP_OPT_TIMELIMIT Sets/gets the value that defines the time limit after which a search operation should be terminated by the server. .BR invalue must be .BR "const int *" , while .BR outvalue must be .BR "int *" , and they cannot be NULL. .TP .B LDAP_OPT_TIMEOUT Sets/gets a timeout value for the synchronous API calls. .B outvalue must be a .BR "struct timeval **" (the caller has to free .BR *outvalue ) , and .B invalue must be a .BR "struct timeval *" , and they cannot be NULL. Using a struct with seconds set to \-1 results in an infinite timeout, which is the default. This option is OpenLDAP specific. .TP .B LDAP_OPT_URI Sets/gets a comma- or space-separated list of URIs to be contacted by the library when trying to establish a connection. .BR outvalue must be a .BR "char **" , and the caller is responsible of freeing the resulting string by calling .BR ldap_memfree (3), while .BR invalue must be a .BR "const char *" ; the library parses the string into a list of .BR LDAPURLDesc structures, so the invocation of .BR ldap_set_option (3) may fail if URL parsing fails. URIs may only contain the .BR schema , the .BR host , and the .BR port fields. This option is OpenLDAP specific. .SH SASL OPTIONS The SASL options are OpenLDAP specific. .TP .B LDAP_OPT_X_SASL_AUTHCID Gets the SASL authentication identity; .BR outvalue must be a .BR "char **" , its content needs to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_SASL_AUTHZID Gets the SASL authorization identity; .BR outvalue must be a .BR "char **" , its content needs to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_SASL_MAXBUFSIZE Gets/sets SASL maximum buffer size; .BR invalue must be .BR "const ber_len_t *" , while .BR outvalue must be .BR "ber_len_t *" . See also .BR LDAP_OPT_X_SASL_SECPROPS . .TP .B LDAP_OPT_X_SASL_MECH Gets the SASL mechanism; .BR outvalue must be a .BR "char **" , its content needs to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_SASL_MECHLIST Gets the list of the available mechanisms, in form of a NULL-terminated array of strings; .BR outvalue must be .BR "char ***" . The caller must not free or otherwise muck with it. .TP .B LDAP_OPT_X_SASL_NOCANON Sets/gets the NOCANON flag. When unset, the hostname is canonicalized. .BR invalue must be .BR "const int *" ; its value should either be .BR LDAP_OPT_OFF or .BR LDAP_OPT_ON . .BR outvalue must be .BR "int *" . .TP .B LDAP_OPT_X_SASL_REALM Gets the SASL realm; .BR outvalue must be a .BR "char **" , its content needs to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_SASL_SECPROPS Sets the SASL secprops; .BR invalue must be a .BR "char *" , containing a comma-separated list of properties. Legal values are: .BR none , .BR nodict , .BR noplain , .BR noactive , .BR passcred , .BR forwardsec , .BR noanonymous , .BR minssf=<minssf> , .BR maxssf=<maxssf> , .BR maxbufsize=<maxbufsize> . .TP .B LDAP_OPT_X_SASL_SSF Gets the SASL SSF; .BR outvalue must be a .BR "ber_len_t *" . .TP .B LDAP_OPT_X_SASL_SSF_EXTERNAL Sets the SASL SSF value related to an authentication performed using an EXTERNAL mechanism; .BR invalue must be a .BR "const ber_len_t *" . .TP .B LDAP_OPT_X_SASL_SSF_MAX Gets/sets SASL maximum SSF; .BR invalue must be .BR "const ber_len_t *" , while .BR outvalue must be .BR "ber_len_t *" . See also .BR LDAP_OPT_X_SASL_SECPROPS . .TP .B LDAP_OPT_X_SASL_SSF_MIN Gets/sets SASL minimum SSF; .BR invalue must be .BR "const ber_len_t *" , while .BR outvalue must be .BR "ber_len_t *" . See also .BR LDAP_OPT_X_SASL_SECPROPS . .TP .B LDAP_OPT_X_SASL_USERNAME Gets the SASL username; .BR outvalue must be a .BR "char **" . Its content needs to be freed by the caller using .BR ldap_memfree (3). .SH TCP OPTIONS The TCP options are OpenLDAP specific. Mainly intended for use with Linux, they may not be portable. .TP .B LDAP_OPT_X_KEEPALIVE_IDLE Sets/gets the number of seconds a connection needs to remain idle before TCP starts sending keepalive probes. .BR invalue must be .BR "const int *" ; .BR outvalue must be .BR "int *" . .TP .B LDAP_OPT_X_KEEPALIVE_PROBES Sets/gets the maximum number of keepalive probes TCP should send before dropping the connection. .BR invalue must be .BR "const int *" ; .BR outvalue must be .BR "int *" . .TP .B LDAP_OPT_X_KEEPALIVE_INTERVAL Sets/gets the interval in seconds between individual keepalive probes. .BR invalue must be .BR "const int *" ; .BR outvalue must be .BR "int *" . .SH TLS OPTIONS The TLS options are OpenLDAP specific. .\".TP .\".B LDAP_OPT_X_TLS .\"Sets/gets the TLS mode. .TP .B LDAP_OPT_X_TLS_CACERTDIR Sets/gets the path of the directory containing CA certificates. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_TLS_CACERTFILE Sets/gets the full-path of the CA certificate file. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_TLS_CERTFILE Sets/gets the full-path of the certificate file. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_TLS_CIPHER_SUITE Sets/gets the allowed cipher suite. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_TLS_CONNECT_ARG Sets/gets the connection callback argument. .BR invalue must be .BR "const void *" ; .BR outvalue must be .BR "void **" . .TP .B LDAP_OPT_X_TLS_CONNECT_CB Sets/gets the connection callback handle. .BR invalue must be .BR "const LDAP_TLS_CONNECT_CB *" ; .BR outvalue must be .BR "LDAP_TLS_CONNECT_CB **" . .TP .B LDAP_OPT_X_TLS_CRLCHECK Sets/gets the CRL evaluation strategy, one of .BR LDAP_OPT_X_TLS_CRL_NONE , .BR LDAP_OPT_X_TLS_CRL_PEER , or .BR LDAP_OPT_X_TLS_CRL_ALL . .BR invalue must be .BR "const int *" ; .BR outvalue must be .BR "int *" . Requires OpenSSL. .TP .B LDAP_OPT_X_TLS_CRLFILE Sets/gets the full-path of the CRL file. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). This option is only valid for GnuTLS. .TP .B LDAP_OPT_X_TLS_CTX Sets/gets the TLS library context. New TLS sessions will inherit their default settings from this library context. .BR invalue must be .BR "const void *" ; .BR outvalue must be .BR "void **" . When using the OpenSSL library this is an SSL_CTX*. When using other crypto libraries this is a pointer to an OpenLDAP private structure. Applications generally should not use this option or attempt to manipulate this structure. .TP .B LDAP_OPT_X_TLS_DHFILE Gets/sets the full-path of the file containing the parameters for Diffie-Hellman ephemeral key exchange. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). Ignored by GnuTLS and Mozilla NSS. .TP .B LDAP_OPT_X_TLS_KEYFILE Sets/gets the full-path of the certificate key file. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). .TP .B LDAP_OPT_X_TLS_NEWCTX Instructs the library to create a new TLS library context. .BR invalue must be .BR "const int *" . A non-zero value pointed to by .BR invalue tells the library to create a context for a server. .TP .B LDAP_OPT_X_TLS_PROTOCOL_MIN Sets/gets the minimum protocol version. .BR invalue must be .BR "const int *" ; .BR outvalue must be .BR "int *" . .TP .B LDAP_OPT_X_TLS_RANDOM_FILE Sets/gets the random file when .B /dev/random and .B /dev/urandom are not available. .BR invalue must be .BR "const char *" ; .BR outvalue must be .BR "char **" , and its contents need to be freed by the caller using .BR ldap_memfree (3). Ignored by GnuTLS older than version 2.2. Ignored by Mozilla NSS. .TP .B LDAP_OPT_X_TLS_REQUIRE_CERT Sets/gets the peer certificate checking strategy, one of .BR LDAP_OPT_X_TLS_NEVER , .BR LDAP_OPT_X_TLS_HARD , .BR LDAP_OPT_X_TLS_DEMAND , .BR LDAP_OPT_X_TLS_ALLOW , .BR LDAP_OPT_X_TLS_TRY . .TP .B LDAP_OPT_X_TLS_SSL_CTX Gets the TLS session context associated with this handle. .BR outvalue must be .BR "void **" . When using the OpenSSL library this is an SSL*. When using other crypto libraries this is a pointer to an OpenLDAP private structure. Applications generally should not use this option. .SH ERRORS On success, the functions return .BR LDAP_OPT_SUCCESS , while they may return .B LDAP_OPT_ERROR to indicate a generic option handling error. Occasionally, more specific errors can be returned, like .B LDAP_NO_MEMORY to indicate a failure in memory allocation. .SH NOTES The LDAP libraries with the .B LDAP_OPT_REFERRALS option set to .B LDAP_OPT_ON (default value) automatically follow referrals using an anonymous bind. Application developers are encouraged to either implement consistent referral chasing features, or explicitly disable referral chasing by setting that option to .BR LDAP_OPT_OFF . .P The protocol version used by the library defaults to LDAPv2 (now historic), which corresponds to the .B LDAP_VERSION2 macro. Application developers are encouraged to explicitly set .B LDAP_OPT_PROTOCOL_VERSION to LDAPv3, using the .B LDAP_VERSION3 macro, or to allow users to select the protocol version. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .B RFC 4422 (http://www.rfc-editor.org), .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 811 stdin PK �c\ ȵ�� � man/man3/ldap_sort_strcasecmp.3nu �[��� .lf 1 stdin .TH LDAP_SORT 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_sort_entries, ldap_sort_values, ldap_sort_strcasecmp \- LDAP sorting routines (deprecated) .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH DESCRIPTION The .BR ldap_sort_entries (), .BR ldap_sort_values (), and .BR ldap_sort_strcasecmp () are deprecated. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 18 stdin .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 22 stdin PK �c\�5^#v1 v1 man/man3/ber_get_null.3nu �[��� .lf 1 stdin .TH LBER_DECODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");" .LP .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");" .LP .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");" .LP .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");" .LP .BI "ber_tag_t ber_get_null(BerElement *" ber ");" .LP .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");" .LP .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");" .LP .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");" .LP .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the decoding routines in the lber library. See .BR lber-encode (3) for details on the corresponding encoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_get_next () to get the next BER element and .BR ber_scanf () to do the actual decoding. In some cases, .BR ber_peek_tag () may also need to be called in normal usage. The other routines are provided for those applications that need more control than .BR ber_scanf () provides. In general, these routines return the tag of the element decoded, or LBER_ERROR if an error occurred. .LP The .BR ber_get_next () routine is used to read the next BER element from the given Sockbuf, \fIsb\fP. It strips off and returns the leading tag, strips off and returns the length of the entire element in \fIlen\fP, and sets up \fIber\fP for subsequent calls to .BR ber_scanf () et al to decode the element. See .BR lber-sockbuf (3) for details of the Sockbuf implementation of the \fIsb\fP parameter. .LP The .BR ber_scanf () routine is used to decode a BER element in much the same way that .BR scanf (3) works. It reads from \fIber\fP, a pointer to a BerElement such as returned by .BR ber_get_next (), interprets the bytes according to the format string \fIfmt\fP, and stores the results in its additional arguments. 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. .RS .LP .TP 3 .B a Octet string. A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter. The caller should free the returned string using .BR ber_memfree (). .TP .B A Octet string. A variant of "\fBa\fP". A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter, unless a zero-length string would result; in that case, the arg is set to NULL. The caller should free the returned string using .BR ber_memfree (). .TP .B s Octet string. A char * buffer should be supplied, followed by a pointer to a ber_len_t initialized to the size of the buffer. Upon return, the null-terminated octet string is put into the buffer, and the ber_len_t is set to the actual size of the octet string. .TP .B O Octet string. A struct ber_val ** should be supplied, which upon return points to a dynamically allocated struct berval containing the octet string and its length. The caller should free the returned structure using .BR ber_bvfree (). .TP .B o Octet string. A struct ber_val * should be supplied, which upon return contains the dynamically allocated octet string and its length. The caller should free the returned octet string using .BR ber_memfree (). .TP .B m Octet string. A struct ber_val * should be supplied, which upon return contains the octet string and its length. The string resides in memory assigned to the BerElement, and must not be freed by the caller. .TP .B b Boolean. A pointer to a ber_int_t should be supplied. .TP .B e Enumeration. A pointer to a ber_int_t should be supplied. .TP .B i Integer. A pointer to a ber_int_t should be supplied. .TP .B B Bitstring. A char ** should be supplied which will point to the dynamically allocated bits, followed by a ber_len_t *, which will point to the length (in bits) of the bitstring returned. .TP .B n Null. No parameter is required. The element is simply skipped if it is recognized. .TP .B v Sequence of octet strings. A char *** should be supplied, which upon return points to a dynamically allocated null-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty. The caller should free the returned array and octet strings using .BR ber_memvfree (). .TP .B V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon return points to a dynamically allocated null-terminated array of struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvecfree (). .TP .B W Sequence of octet strings with lengths. A BerVarray * should be supplied, which upon return points to a dynamically allocated array of struct berval's containing the octet strings and their lengths. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvarray_free (). .TP .B M Sequence of octet strings with lengths. This is a generalized form of the previous three formats. A void ** (ptr) should be supplied, followed by a ber_len_t * (len) and a ber_len_t (off). Upon return (ptr) will point to a dynamically allocated array whose elements are all of size (*len). A struct berval will be filled starting at offset (off) in each element. The strings in each struct berval reside in memory assigned to the BerElement and must not be freed by the caller. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The number of elements in the array is also stored in (*len) on return. The caller should free the returned array using .BR ber_memfree (). .TP .B l Length of the next element. A pointer to a ber_len_t should be supplied. .TP .B t Tag of the next element. A pointer to a ber_tag_t should be supplied. .TP .B T Skip element and return its tag. A pointer to a ber_tag_t should be supplied. .TP .B x Skip element. The next element is skipped. .TP .B { Begin sequence. No parameter is required. The initial sequence tag and length are skipped. .TP .B } End sequence. No parameter is required and no action is taken. .TP .B [ Begin set. No parameter is required. The initial set tag and length are skipped. .TP .B ] End set. No parameter is required and no action is taken. .RE .LP The .BR ber_get_int () routine tries to interpret the next element as an integer, returning the result in \fInum\fP. The tag of whatever it finds is returned on success, LBER_ERROR (\-1) on failure. .LP The .BR ber_get_stringb () routine is used to read an octet string into a preallocated buffer. The \fIlen\fP parameter should be initialized to the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte. .LP The .BR ber_get_stringa () routine is used to dynamically allocate space into which an octet string is read. The caller should free the returned string using .BR ber_memfree(). .LP The .BR ber_get_stringal () routine is used to dynamically allocate space into which an octet string and its length are read. It takes a struct berval **, and returns the result in this parameter. The caller should free the returned structure using .BR ber_bvfree(). .LP The .BR ber_get_stringbv () routine is used to read an octet string and its length into the provided struct berval *. If the \fIalloc\fP parameter is zero, the string will reside in memory assigned to the BerElement, and must not be freed by the caller. If the \fIalloc\fP parameter is non-zero, the string will be copied into dynamically allocated space which should be returned using .BR ber_memfree (). .LP The .BR ber_get_null () routine is used to read a NULL element. It returns the tag of the element it skips over. .LP The .BR ber_get_boolean () routine is used to read a boolean value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_enum () routine is used to read a enumeration value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_bitstringa () routine is used to read a bitstring value. It takes a char ** which will hold the dynamically allocated bits, followed by an ber_len_t *, which will point to the length (in bits) of the bitstring returned. The caller should free the returned string using .BR ber_memfree (). .LP The .BR ber_first_element () routine is used to return the tag and length of the first element in a set or sequence. It also returns in \fIcookie\fP a magic cookie parameter that should be passed to subsequent calls to ber_next_element(), which returns similar information. .SH EXAMPLES Assume the variable \fIber\fP contains a lightweight BER encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP The element can be decoded using .BR ber_scanf () as follows. .LP .nf ber_int_t scope, deref, size, time, attrsonly; char *dn, **attrs; ber_tag_t tag; tag = ber_scanf( ber, "{aeeiib{v}}", &dn, &scope, &deref, &size, &time, &attrsonly, &attrs ); if( tag == LBER_ERROR ) { /* error */ } else { /* success */ } ber_memfree( dn ); ber_memvfree( attrs ); .fi .SH ERRORS If an error occurs during decoding, generally these routines return LBER_ERROR ((ber_tag_t)\-1). .LP .SH NOTES .LP The return values for all of these functions are declared in the .B <lber.h> header file. Some routines may dynamically allocate memory which must be freed by the caller using supplied deallocation routines. .SH SEE ALSO .BR lber-encode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 358 stdin PK �c\]�Ib� � man/man3/ldap_delete_s.3nu �[��� .lf 1 stdin .TH LDAP_DELETE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_delete, ldap_delete_s, ldap_delete_ext, ldap_delete_ext_s \- Perform an LDAP delete operation. .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_delete_s(ld, dn) .ft LDAP *ld; char *dn; .LP .ft B int ldap_delete(ld, dn) .ft LDAP *ld; char *dn; .LP .ft B int ldap_delete_ext(ld, dn, serverctrls, clientctrls, msgidp) .ft LDAP *ld; char *dn; LDAPControl **serverctrls, **clientctrls; int *msgidp; .LP .ft B int ldap_delete_ext_s(ld, dn, serverctrls, clientctrls) .ft LDAP *ld; char *dn; LDAPControl **serverctrls, **clientctrls; .SH DESCRIPTION The .B ldap_delete_s() routine is used to perform an LDAP delete operation synchronously. It takes \fIdn\fP, the DN of the entry to be deleted. It returns an LDAP error code, indicating the success or failure of the operation. .LP The .B ldap_delete() routine is used to perform an LDAP delete operation asynchronously. It takes the same parameters as .BR ldap_delete_s(), but returns the message id of the request it initiated. The result of the delete can be obtained by a subsequent call to .BR ldap_result (3). .LP The .B ldap_delete_ext() routine allows server and client controls to be specified to extend the delete request. This routine is asynchronous like ldap_delete(), but its return value is an LDAP error code. It stores the message id of the request in the integer pointed to by msgidp. .LP The .B ldap_delete_ext_s() routine is the synchronous version of .BR ldap_delete_ext(). It also returns an LDAP error code indicating success or failure of the operation. .SH ERRORS .B ldap_delete_s() returns an LDAP error code which can be interpreted by calling one of .BR ldap_perror (3) and friends. .B ldap_delete() returns \-1 if something went wrong initiating the request. It returns the non-negative message id of the request if things went ok. .LP .B ldap_delete_ext() and .B ldap_delete_ext_s() return some Non-zero value if something went wrong initiating the request, else return 0. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 90 stdin PK �c\��MK$ K$ man/man3/ber_put_seq.3nu �[��� .lf 1 stdin .TH LBER_ENCODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_alloc_t, ber_flush, ber_flush2, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring, ber_put_string, ber_put_null, ber_put_boolean, ber_put_bitstring, ber_start_seq, ber_start_set, ber_put_seq, ber_put_set \- OpenLDAP LBER simplified Basic Encoding Rules library routines for encoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_flush2(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_printf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "int ber_put_int(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_enum(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_ostring(BerElement *" ber ", const char *" str ", ber_len_t " len ", ber_tag_t " tag ");" .LP .BI "int ber_put_string(BerElement *" ber ", const char *" str ", ber_tag_t " tag ");" .LP .BI "int ber_put_null(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_boolean(BerElement *" ber ", ber_int_t " bool ", ber_tag_t " tag ");" .LP .BI "int ber_put_bitstring(BerElement *" ber ", const char *" str ", ber_len_t " blen ", ber_tag_t " tag ");" .LP .BI "int ber_start_seq(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_start_set(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_seq(BerElement *" ber ");" .LP .BI "int ber_put_set(BerElement *" ber ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the encoding routines in the lber library. See .BR lber-decode (3) for details on the corresponding decoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_alloc_t () to allocate a BER element for encoding, .BR ber_printf () to do the actual encoding, and .BR ber_flush2 () to actually write the element. The other routines are provided for those applications that need more control than .BR ber_printf () provides. In general, these routines return the length of the element encoded, or \-1 if an error occurred. .LP The .BR ber_alloc_t () routine is used to allocate a new BER element. It should be called with an argument of LBER_USE_DER. .LP The .BR ber_flush2 () routine is used to actually write the element to a socket (or file) descriptor, once it has been fully encoded (using .BR ber_printf () and friends). See .BR lber-sockbuf (3) for more details on the Sockbuf implementation of the \fIsb\fP parameter. If the \fIfreeit\fP parameter is non-zero, the supplied \fIber\fP will be freed. If \fILBER_FLUSH_FREE_ON_SUCCESS\fP is used, the \fIber\fP is only freed when successfully flushed, otherwise it is left intact; if \fILBER_FLUSH_FREE_ON_ERROR\fP is used, the \fIber\fP is only freed when an error occurs, otherwise it is left intact; if \fILBER_FLUSH_FREE_ALWAYS\fP is used, the \fIber\fP is freed anyway. This function differs from the original .BR ber_flush (3) function, whose behavior corresponds to that indicated for \fILBER_FLUSH_FREE_ON_SUCCESS\fP. Note that in the future, the behavior of .BR ber_flush (3) with \fIfreeit\fP non-zero might change into that of .BR ber_flush2 (3) with \fIfreeit\fP set to \fILBER_FLUSH_FREE_ALWAYS\fP. .LP The .BR ber_printf () routine is used to encode a BER element in much the same way that .BR sprintf (3) works. One important difference, though, is that some state information is kept with the \fIber\fP parameter so that multiple calls can be made to .BR ber_printf () to append things to the end of the BER element. .BR Ber_printf () writes to \fIber\fP, a pointer to a BerElement such as returned by .BR ber_alloc_t (). It interprets and formats its arguments according to the format string \fIfmt\fP. The format string can contain the following characters: .RS .LP .TP 3 .B b Boolean. An ber_int_t parameter should be supplied. A boolean element is output. .TP .B e Enumeration. An ber_int_t parameter should be supplied. An enumeration element is output. .TP .B i Integer. An ber_int_t parameter should be supplied. An integer element is output. .TP .B B Bitstring. A char * pointer to the start of the bitstring is supplied, followed by the number of bits in the bitstring. A bitstring element is output. .TP .B n Null. No parameter is required. A null element is output. .TP .B o Octet string. A char * is supplied, followed by the length of the string pointed to. An octet string element is output. .TP .B O Octet string. A struct berval * is supplied. An octet string element is output. .TP .B s Octet string. A null-terminated string is supplied. An octet string element is output, not including the trailing NULL octet. .TP .B t Tag. A ber_tag_t specifying the tag to give the next element is provided. This works across calls. .TP .B v Several octet strings. A null-terminated array of char *'s is supplied. Note that a construct like '{v}' is required to get an actual SEQUENCE OF octet strings. .TP .B V Several octet strings. A null-terminated array of struct berval *'s is supplied. Note that a construct like '{V}' is required to get an actual SEQUENCE OF octet strings. .TP .B W Several octet strings. An array of struct berval's is supplied. The array is terminated by a struct berval with a NULL bv_val. Note that a construct like '{W}' is required to get an actual SEQUENCE OF octet strings. .TP .B { Begin sequence. No parameter is required. .TP .B } End sequence. No parameter is required. .TP .B [ Begin set. No parameter is required. .TP .B ] End set. No parameter is required. .RE .LP The .BR ber_put_int () routine writes the integer element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_enum () routine writes the enumeration element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_boolean () routine writes the boolean value given by \fIbool\fP to the BER element. .LP The .BR ber_put_bitstring () routine writes \fIblen\fP bits starting at \fIstr\fP as a bitstring value to the given BER element. Note that \fIblen\fP is the length \fIin bits\fP of the bitstring. .LP The .BR ber_put_ostring () routine writes \fIlen\fP bytes starting at \fIstr\fP to the BER element as an octet string. .LP The .BR ber_put_string () routine writes the null-terminated string (minus the terminating '\0') to the BER element as an octet string. .LP The .BR ber_put_null () routine writes a NULL element to the BER element. .LP The .BR ber_start_seq () routine is used to start a sequence in the BER element. The .BR ber_start_set () routine works similarly. The end of the sequence or set is marked by the nearest matching call to .BR ber_put_seq () or .BR ber_put_set (), respectively. .SH EXAMPLES Assuming the following variable declarations, and that the variables have been assigned appropriately, an lber encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP can be achieved like so: .LP .nf int rc; ber_int_t scope, ali, size, time, attrsonly; char *dn, **attrs; BerElement *ber; /* ... fill in values ... */ ber = ber_alloc_t( LBER_USE_DER ); if ( ber == NULL ) { /* error */ } rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali, size, time, attrsonly, attrs ); if( rc == \-1 ) { /* error */ } else { /* success */ } .fi .SH ERRORS If an error occurs during encoding, generally these routines return \-1. .LP .SH NOTES .LP The return values for all of these functions are declared in the <lber.h> header file. .SH SEE ALSO .BR lber-decode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 289 stdin PK �c\t5d�� � man/man3/lber-sockbuf.3nu �[��� .lf 1 stdin .TH LBER_SOCKBUF 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_sockbuf_alloc, ber_sockbuf_free, ber_sockbuf_ctrl, ber_sockbuf_add_io, ber_sockbuf_remove_io, Sockbuf_IO \- OpenLDAP LBER I/O infrastructure .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .B Sockbuf *ber_sockbuf_alloc( void ); .LP .BI "void ber_sockbuf_free(Sockbuf *" sb ");" .LP .BI "int ber_sockbuf_ctrl(Sockbuf *" sb ", int " opt ", void *" arg ");" .LP .BI "int ber_sockbuf_add_io(Sockbuf *" sb ", Sockbuf_IO *" sbio ", int " layer ", void *" arg ");" .LP .BI "int ber_sockbuf_remove_io(Sockbuf *" sb ", Sockbuf_IO *" sbio ", int " layer ");" .LP .nf .B typedef struct sockbuf_io_desc { .BI "int " sbiod_level ";" .BI "Sockbuf *" sbiod_sb ";" .BI "Sockbuf_IO *" sbiod_io ";" .BI "void *" sbiod_pvt ";" .BI "struct sockbuf_io_desc *" sbiod_next ";" .B } Sockbuf_IO_Desc; .LP .B typedef struct sockbuf_io { .BI "int (*" sbi_setup ")(Sockbuf_IO_Desc *" sbiod ", void *" arg ");" .BI "int (*" sbi_remove ")(Sockbuf_IO_Desc *" sbiod ");" .BI "int (*" sbi_ctrl ")(Sockbuf_IO_Desc *" sbiod ", int " opt ", void *" arg ");" .BI "ber_slen_t (*" sbi_read ")(Sockbuf_IO_Desc *" sbiod ", void *" buf ", ber_len_t " len ");" .BI "ber_slen_t (*" sbi_write ")(Sockbuf_IO_Desc *" sbiod ", void *" buf ", ber_len_t " len ");" .BI "int (*" sbi_close ")(Sockbuf_IO_Desc *" sbiod ");" .B } Sockbuf_IO; .SH DESCRIPTION .LP These routines are used to manage the low level I/O operations performed by the Lightweight BER library. They are called implicitly by the other libraries and usually do not need to be called directly from applications. The I/O framework is modularized and new transport layers can be supported by appropriately defining a .B Sockbuf_IO structure and installing it onto an existing .BR Sockbuf . .B Sockbuf structures are allocated and freed by .BR ber_sockbuf_alloc () and .BR ber_sockbuf_free (), respectively. The .BR ber_sockbuf_ctrl () function is used to get and set options related to a .B Sockbuf or to a specific I/O layer of the .BR Sockbuf . The .BR ber_sockbuf_add_io () and .BR ber_sockbuf_remove_io () functions are used to add and remove specific I/O layers on a .BR Sockbuf . Options for .BR ber_sockbuf_ctrl () include: .TP .B LBER_SB_OPT_HAS_IO Takes a .B Sockbuf_IO * argument and returns 1 if the given handler is installed on the .BR Sockbuf , otherwise returns 0. .TP .B LBER_SB_OPT_GET_FD Retrieves the file descriptor associated to the .BR Sockbuf ; .B arg must be a .BR "ber_socket_t *" . The return value will be 1 if a valid descriptor was present, \-1 otherwise. .TP .B LBER_SB_OPT_SET_FD Sets the file descriptor of the .B Sockbuf to the descriptor pointed to by .BR arg ; .B arg must be a .BR "ber_socket_t *" . The return value will always be 1. .TP .B LBER_SB_OPT_SET_NONBLOCK Toggles the non-blocking state of the file descriptor associated to the .BR Sockbuf . .B arg should be NULL to disable and non-NULL to enable the non-blocking state. The return value will be 1 for success, \-1 otherwise. .TP .B LBER_SB_OPT_DRAIN Flush (read and discard) all available input on the .BR Sockbuf . The return value will be 1. .TP .B LBER_SB_OPT_NEEDS_READ Returns non-zero if input is waiting to be read. .TP .B LBER_SB_OPT_NEEDS_WRITE Returns non-zero if the .B Sockbuf is ready to be written. .TP .B LBER_SB_OPT_GET_MAX_INCOMING Returns the maximum allowed size of an incoming message; .B arg must be a .BR "ber_len_t *" . The return value will be 1. .TP .B LBER_SB_OPT_SET_MAX_INCOMING Sets the maximum allowed size of an incoming message; .B arg must be a .BR "ber_len_t *" . The return value will be 1. .LP Options not in this list will be passed down to each .B Sockbuf_IO handler in turn until one of them processes it. If the option is not handled .BR ber_sockbuf_ctrl () will return 0. .LP Multiple .B Sockbuf_IO handlers can be stacked in multiple layers to provide various functionality. Currently defined layers include .TP .B LBER_SBIOD_LEVEL_PROVIDER the lowest layer, talking directly to a network .TP .B LBER_SBIOD_LEVEL_TRANSPORT an intermediate layer .TP .B LBER_SBIOD_LEVEL_APPLICATION a higher layer .LP Currently defined .B Sockbuf_IO handlers in liblber include .TP .B ber_sockbuf_io_tcp The default stream-oriented provider .TP .B ber_sockbuf_io_fd A stream-oriented provider for local IPC sockets .TP .B ber_sockbuf_io_dgram A datagram-oriented provider. This handler is only present if the liblber library was built with LDAP_CONNECTIONLESS defined. .TP .B ber_sockbuf_io_readahead A buffering layer, usually used with a datagram provider to hide the datagram semantics from upper layers. .TP .B ber_sockbuf_io_debug A generic handler that outputs hex dumps of all traffic. This handler may be inserted multiple times at arbitrary layers to show the flow of data between other handlers. .LP Additional handlers may be present in libldap if support for them was enabled: .TP .B ldap_pvt_sockbuf_io_sasl An application layer handler for SASL encoding/decoding. .TP .B sb_tls_sbio A transport layer handler for SSL/TLS encoding/decoding. Note that this handler is private to the library and is not exposed in the API. .LP The provided handlers are all instantiated implicitly by libldap, and applications generally will not need to directly manipulate them. .SH SEE ALSO .BR lber-decode (3), .BR lber-encode (3), .BR lber-types (3), .BR ldap_get_option (3) .LP .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 200 stdin PK �c\�E͡ � man/man3/ldap_result.3nu �[��� .lf 1 stdin .TH LDAP_RESULT 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_result \- Wait for the result of an LDAP operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_result( LDAP *ld, int msgid, int all, struct timeval *timeout, LDAPMessage **result ); int ldap_msgfree( LDAPMessage *msg ); int ldap_msgtype( LDAPMessage *msg ); int ldap_msgid( LDAPMessage *msg ); .ft .SH DESCRIPTION The .B ldap_result() routine is used to wait for and return the result of an operation previously initiated by one of the LDAP asynchronous operation routines (e.g., .BR ldap_search_ext (3), .BR ldap_modify_ext (3), etc.). Those routines all return \-1 in case of error, and an invocation identifier upon successful initiation of the operation. The invocation identifier is picked by the library and is guaranteed to be unique across the LDAP session. It can be used to request the result of a specific operation from .B ldap_result() through the \fImsgid\fP parameter. .LP The .B ldap_result() routine will block or not, depending upon the setting of the \fItimeout\fP parameter. If timeout is not a NULL pointer, it specifies a maximum interval to wait for the selection to complete. If timeout is a NULL pointer, the LDAP_OPT_TIMEOUT value set by .BR ldap_set_option (3) is used. With the default setting, the select blocks indefinitely. To effect a poll, the timeout argument should be a non-NULL pointer, pointing to a zero-valued timeval structure. To obtain the behavior of the default setting, bypassing any value set by .BR ldap_set_option (3), set to -1 the \fItv_sec\fP field of the \fItimeout\fP parameter. See .BR select (2) for further details. .LP If the result of a specific operation is required, \fImsgid\fP should be set to the invocation identifier returned when the operation was initiated, otherwise LDAP_RES_ANY or LDAP_RES_UNSOLICITED should be supplied to wait for any or unsolicited response. .LP The \fIall\fP parameter, if non-zero, causes .B ldap_result() to return all responses with msgid, otherwise only the next response is returned. This is commonly used to obtain all the responses of a search operation. .LP A search response is made up of zero or more search entries, zero or more search references, and zero or more extended partial responses followed by a search result. If \fIall\fP is set to 0, search entries will be returned one at a time as they come in, via separate calls to .BR ldap_result() . If it's set to 1, the search response will only be returned in its entirety, i.e., after all entries, all references, all extended partial responses, and the final search result have been received. .SH RETURN VALUE Upon success, the type of the result received is returned and the \fIresult\fP parameter will contain the result of the operation; otherwise, the \fIresult\fP parameter is undefined. This result should be passed to the LDAP parsing routines, .BR ldap_first_message (3) and friends, for interpretation. .LP The possible result types returned are: .LP .nf LDAP_RES_BIND (0x61) LDAP_RES_SEARCH_ENTRY (0x64) LDAP_RES_SEARCH_REFERENCE (0x73) 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) LDAP_RES_INTERMEDIATE (0x79) .fi .LP The .B ldap_msgfree() routine is used to free the memory allocated for result(s) by .B ldap_result() or .BR ldap_search_ext_s (3) and friends. It takes a pointer to the result or result chain to be freed and returns the type of the last message in the chain. If the parameter is NULL, the function does nothing and returns zero. .LP The .B ldap_msgtype() routine returns the type of a message. .LP The .B ldap_msgid() routine returns the message id of a message. .SH ERRORS .B ldap_result() returns \-1 if something bad happens, and zero if the timeout specified was exceeded. .B ldap_msgtype() and .B ldap_msgid() return \-1 on error. .SH SEE ALSO .BR ldap (3), .BR ldap_first_message (3), .BR select (2) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 137 stdin PK �c\ NO O man/man3/ldap_first_message.3nu �[��� .lf 1 stdin .TH LDAP_FIRST_MESSAGE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_first_message, ldap_next_message, ldap_count_messages \- Stepping through messages in a result chain .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_count_messages( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_next_message( LDAP *ld, LDAPMessage *message ) .SH DESCRIPTION .LP These routines are used to step through the messages in a result chain received from .BR ldap_result (3) . For search operations, the result chain can contain referral, entry and result messages. The .BR ldap_msgtype (3) function can be used to distinguish between the different message types. .LP The .B ldap_first_message() routine is used to retrieve the first message in a result chain. It takes the \fIresult\fP as returned by a call to .BR ldap_result (3) , .BR ldap_search_s (3) or .BR ldap_search_st (3) and returns a pointer to the first message in the result chain. .LP This pointer should be supplied on a subsequent call to .B ldap_next_message() to get the next message, the result of which should be supplied to the next call to .BR ldap_next_message() , etc. .B ldap_next_message() will return NULL when there are no more messages. .LP These functions are useful when using routines like .BR ldap_parse_result (3) that only operate on the first result in the chain. .LP A count of the number of messages in the result chain can be obtained by calling .BR ldap_count_messages() . It can also be used to count the number of remaining messages in a chain if called with a message, entry or reference returned by .B ldap_first_message() , .B ldap_next_message() , .BR ldap_first_entry (3) , .BR ldap_next_entry (3) , .BR ldap_first_reference (3) , .BR ldap_next_reference (3) . .SH ERRORS If an error occurs in .B ldap_first_message() or .BR ldap_next_message() , NULL is returned. If an error occurs in .BR ldap_count_messages() , -1 is returned. .SH SEE ALSO .BR ldap (3), .BR ldap_search (3), .BR ldap_result (3), .BR ldap_parse_result (3), .BR ldap_first_entry (3), .BR ldap_first_reference (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 83 stdin PK �c\���0 0 man/man3/ldap_memalloc.3nu �[��� .lf 1 stdin .TH LDAP_MEMORY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_memfree, ldap_memvfree, ldap_memalloc, ldap_memcalloc, ldap_memrealloc, ldap_strdup \- LDAP memory allocation routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "void ldap_memfree(void *" p ");" .LP .BI "void ldap_memvfree(void **" v ");" .LP .BI "void *ldap_memalloc(ber_len_t " s ");" .LP .BI "void *ldap_memcalloc(ber_len_t " n ", ber_len_t " s ");" .LP .BI "void *ldap_memrealloc(void *" p ", ber_len_t " s ");" .LP .BI "char *ldap_strdup(LDAP_CONST char *" p ");" .SH DESCRIPTION These routines are used to allocate/deallocate memory used/returned by the LDAP library. .BR ldap_memalloc (), .BR ldap_memcalloc (), .BR ldap_memrealloc (), and .BR ldap_memfree () are used exactly like the standard .BR malloc (3), .BR calloc (3), .BR realloc (3), and .BR free (3) routines, respectively. The .BR ldap_memvfree () routine is used to free a dynamically allocated array of pointers to arbitrary dynamically allocated objects. The .BR ldap_strdup () routine is used exactly like the standard .BR strdup (3) routine. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 51 stdin PK �c\�� �. �. man/man3/ldap_simple_bind.3nu �[��� .lf 1 stdin .TH LDAP_BIND 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_bind, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_sasl_bind, ldap_sasl_bind_s, ldap_sasl_interactive_bind_s, ldap_parse_sasl_bind_result, ldap_unbind, ldap_unbind_s, ldap_unbind_ext, ldap_unbind_ext_s, ldap_set_rebind_proc \- LDAP bind routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .BI "int ldap_bind(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_bind_s(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_simple_bind(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_simple_bind_s(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_sasl_bind(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], int *" msgidp ");" .RE .LP .BI "int ldap_sasl_bind_s(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], struct berval **" servercredp ");" .RE .LP .BI "int ldap_parse_sasl_bind_result(LDAP *" ld ", LDAPMessage *" res "," .RS .BI "struct berval **" servercredp ", int " freeit ");" .RE .LP .BI "int ldap_sasl_interactive_bind_s(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ");" .RE .LP .BI "int ldap_sasl_interactive_bind(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ", LDAPMessage *" result "," .BI "const char **" rmechp ", int *" msgidp ");" .RE .LP .BI "int (LDAP_SASL_INTERACT_PROC)(LDAP *" ld ", unsigned " flags ", void *" defaults ", void *" sasl_interact ");" .LP .BI "int ldap_unbind(LDAP *" ld ");" .LP .BI "int ldap_unbind_s(LDAP *" ld ");" .LP .BI "int ldap_unbind_ext(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_unbind_ext_s(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_set_rebind_proc (LDAP *" ld ", LDAP_REBIND_PROC *" ldap_proc ", void *" params ");" .LP .BI "int (LDAP_REBIND_PROC)(LDAP *" ld ", LDAP_CONST char *" url ", ber_tag_t " request ", ber_int_t " msgid ", void *" params ");" .SH DESCRIPTION .LP These routines provide various interfaces to the LDAP bind operation. After an association with an LDAP server is made using .BR ldap_init (3), an LDAP bind operation should be performed before other operations are attempted over the connection. An LDAP bind is required when using Version 2 of the LDAP protocol; it is optional for Version 3 but is usually needed due to security considerations. .LP There are three types of bind calls, ones providing simple authentication, ones providing SASL authentication, and general routines capable of doing either simple or SASL authentication. .LP .B SASL (Simple Authentication and Security Layer) can negotiate one of many different kinds of authentication. Both synchronous and asynchronous versions of each variant of the bind call are provided. All routines take \fIld\fP as their first parameter, as returned from .BR ldap_init (3). .SH SIMPLE AUTHENTICATION The simplest form of the bind call is .BR ldap_simple_bind_s() . It takes the DN to bind as in \fIwho\fP, and the userPassword associated with the entry in \fIpasswd\fP. It returns an LDAP error indication (see .BR ldap_error (3)). The .B ldap_simple_bind() call is asynchronous, taking the same parameters but only initiating the bind operation and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The .B ldap_sasl_bind_s() and asynchronous .B ldap_sasl_bind() functions can also be used to make a simple bind by using LDAP_SASL_SIMPLE as the SASL mechanism. .SH GENERAL AUTHENTICATION The .B ldap_bind() and .B ldap_bind_s() routines can be used when the authentication method to use needs to be selected at runtime. They both take an extra \fImethod\fP parameter selecting the authentication method to use. It should be set to LDAP_AUTH_SIMPLE to select simple authentication. .B ldap_bind() returns the message id of the request it initiates. .B ldap_bind_s() returns an LDAP error indication. .SH SASL AUTHENTICATION For SASL binds the server always ignores any provided DN, so the .I dn parameter should always be NULL. .BR ldap_sasl_bind_s () sends a single SASL bind request with the given SASL .I mechanism and credentials in the .I cred parameter. The format of the credentials depends on the particular SASL mechanism in use. For mechanisms that provide mutual authentication the server's credentials will be returned in the .I servercredp parameter. The routine returns an LDAP error indication (see .BR ldap_error (3)). The .BR ldap_sasl_bind () call is asynchronous, taking the same parameters but only sending the request and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The result must be additionally parsed by .BR ldap_parse_sasl_bind_result () to obtain any server credentials sent from the server. .LP Many SASL mechanisms require multiple message exchanges to perform a complete authentication. Applications should generally use .BR ldap_sasl_interactive_bind_s () rather than calling the basic .BR ldap_sasl_bind () functions directly. The .I mechs parameter should contain a space-separated list of candidate mechanisms to use. If this parameter is NULL or empty the library will query the supportedSASLMechanisms attribute from the server's rootDSE for the list of SASL mechanisms the server supports. The .I flags parameter controls the interaction used to retrieve any necessary SASL authentication parameters and should be one of: .TP LDAP_SASL_AUTOMATIC use defaults if available, prompt otherwise .TP LDAP_SASL_INTERACTIVE always prompt .TP LDAP_SASL_QUIET never prompt .LP The .I interact function uses the provided .I defaults to handle requests from the SASL library for particular authentication parameters. There is no defined format for the .I defaults information; it is up to the caller to use whatever format is appropriate for the supplied .I interact function. The .I sasl_interact parameter comes from the underlying SASL library. When used with Cyrus SASL this is an array of .B sasl_interact_t structures. The Cyrus SASL library will prompt for a variety of inputs, including: .TP SASL_CB_GETREALM the realm for the authentication attempt .TP SASL_CB_AUTHNAME the username to authenticate .TP SASL_CB_PASS the password for the provided username .TP SASL_CB_USER the username to use for proxy authorization .TP SASL_CB_NOECHOPROMPT generic prompt for input with input echoing disabled .TP SASL_CB_ECHOPROMPT generic prompt for input with input echoing enabled .TP SASL_CB_LIST_END indicates the end of the array of prompts .LP See the Cyrus SASL documentation for more details. .LP Applications which need to manage connections asynchronously may use .BR ldap_sasl_interactive_bind () instead of the synchronous version. A valid mechs parameter must be supplied, otherwise the library will be forced to query the server for a list of supported mechanisms, and this query will be performed synchronously. The other parameters are the same as for the synchronous function, with three additional parameters. The actual SASL mechanism that was used, and the message ID for use with .BR ldap_result () will be returned in rmechp and msgidp, respectively. The value in rmechp must not be modified by the caller and must be passed back on each subsequent call. The message obtained from .BR ldap_result () must be passed in the result parameter. This parameter must be NULL when initiating a new Bind. The caller must free the result message after each call using .BR ldap_msgfree (). The .BR ldap_sasl_interactive_bind () function returns an LDAP result code. If the code is LDAP_SASL_BIND_IN_PROGRESS then the Bind is not complete yet, and this function must be called again with the next result from the server. .SH REBINDING .LP The .B ldap_set_rebind_proc function() sets the process to use for binding when an operation returns a referral. This function is used when an application needs to bind to another server in order to follow a referral or search continuation reference. .LP The function takes \fIld\fP, the \fIrebind\fP function, and the \fIparams\fP, the arbitrary data like state information which the client might need to properly rebind. The LDAP_OPT_REFERRALS option in the \fIld\fP must be set to ON for the libraries to use the rebind function. Use the .BR ldap_set_option function to set the value. .LP The rebind function parameters are as follows: .LP The \fIld\fP parameter must be used by the application when binding to the referred server if the application wants the libraries to follow the referral. .LP The \fIurl\fP parameter points to the URL referral string received from the LDAP server. The LDAP application can use the .BR ldap_url_parse (3) function to parse the string into its components. .LP The \fIrequest\fP parameter specifies the type of request that generated the referral. .LP The \fImsgid\fP parameter specifies the message ID of the request generating the referral. .LP The \fIparams\fP parameter is the same value as passed originally to the .BR ldap_set_rebind_proc () function. .LP The LDAP libraries set all the parameters when they call the rebind function. The application should not attempt to free either the ld or the url structures in the rebind function. .LP The application must supply to the rebind function the required authentication information such as, user name, password, and certificates. The rebind function must use a synchronous bind method. .SH UNBINDING The .B ldap_unbind() call is used to unbind from the directory, terminate the current association, and free the resources contained in the \fIld\fP structure. Once it is called, the connection to the LDAP server is closed, and the \fIld\fP structure is invalid. The .B ldap_unbind_s() call is just another name for .BR ldap_unbind() ; both of these calls are synchronous in nature. .LP The .B ldap_unbind_ext() and .B ldap_unbind_ext_s() allows the operations to specify controls. .SH ERRORS Asynchronous routines will return \-1 in case of error, setting the \fIld_errno\fP parameter of the \fIld\fP structure. Synchronous routines return whatever \fIld_errno\fP is set to. See .BR ldap_error (3) for more information. .SH NOTES If an anonymous bind is sufficient for the application, the rebind process need not be provided. The LDAP libraries with the LDAP_OPT_REFERRALS option set to ON (default value) will automatically follow referrals using an anonymous bind. .LP If the application needs stronger authentication than an anonymous bind, you need to provide a rebind process for that authentication method. The bind method must be synchronous. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_open (3), .BR ldap_set_option (3), .BR ldap_url_parse (3) .B RFC 4422 (http://www.rfc-editor.org), .B Cyrus SASL (http://asg.web.cmu.edu/sasl/) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 335 stdin PK �c\��A man/man3/ldap_modrdn_s.3nu �[��� .lf 1 stdin .TH LDAP_MODRDN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_modrdn, ldap_modrdn_s, ldap_modrdn2, ldap_modrdn2_s \- Perform an LDAP modify RDN operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_modrdn(ld, dn, newrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; .LP .ft B .LP .ft B int ldap_modrdn_s(ld, dn, newrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; .LP .ft B int ldap_modrdn2(ld, dn, newrdn, deleteoldrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; int deleteoldrdn; .LP .ft B int ldap_modrdn2_s(ld, dn, newrdn, deleteoldrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; int deleteoldrdn; .SH DESCRIPTION The .B ldap_modrdn() and .B ldap_modrdn_s() routines perform an LDAP modify RDN operation. They both take \fIdn\fP, the DN of the entry whose RDN is to be changed, and \fInewrdn\fP, the new RDN to give the entry. The old RDN of the entry is never kept as an attribute of the entry. .B ldap_modrdn() is asynchronous, returning the message id of the operation it initiates. .B ldap_modrdn_s() is synchronous, returning the LDAP error code indicating the success or failure of the operation. Use of these routines is deprecated. Use the versions described below instead. .LP The .B ldap_modrdn2() and .B ldap_modrdn2_s() routines also perform an LDAP modify RDN operation, taking the same parameters as above. In addition, they both take the \fIdeleteoldrdn\fP parameter which is used as a boolean value to indicate whether the old RDN values should be deleted from the entry or not. .SH ERRORS The synchronous (_s) versions of these routines return an LDAP error code, either LDAP_SUCCESS or an error if there was trouble. The asynchronous versions return \-1 in case of trouble, setting the .B ld_errno field of \fIld\fP. See .BR ldap_error (3) for more details. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 82 stdin PK �c\�շY� � man/man3/ber_free.3nu �[��� .lf 1 stdin .TH LBER_TYPES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_int_t, ber_uint_t, ber_len_t, ber_slen_t, ber_tag_t, struct berval, BerValue, BerVarray, BerElement, ber_bvfree, ber_bvecfree, ber_bvecadd, ber_bvarray_free, ber_bvarray_add, ber_bvdup, ber_dupbv, ber_bvstr, ber_bvstrdup, ber_str2bv, ber_alloc_t, ber_init, ber_init2, ber_free \- OpenLDAP LBER types and allocation functions .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .nf .ft B typedef impl_tag_t ber_tag_t; typedef impl_int_t ber_int_t; typedef impl_uint_t ber_uint_t; typedef impl_len_t ber_len_t; typedef impl_slen_t ber_slen_t; typedef struct berval { ber_len_t bv_len; char *bv_val; } BerValue, *BerVarray; typedef struct berelement BerElement; .ft .fi .LP .BI "void ber_bvfree(struct berval *" bv ");" .LP .BI "void ber_bvecfree(struct berval **" bvec ");" .LP .BI "void ber_bvecadd(struct berval ***" bvec ", struct berval *" bv ");" .LP .BI "void ber_bvarray_free(struct berval *" bvarray ");" .LP .BI "void ber_bvarray_add(BerVarray *" bvarray ", BerValue *" bv ");" .LP .BI "struct berval *ber_bvdup(const struct berval *" bv ");" .LP .BI "struct berval *ber_dupbv(const struct berval *" dst ", struct berval *" src ");" .LP .BI "struct berval *ber_bvstr(const char *" str ");" .LP .BI "struct berval *ber_bvstrdup(const char *" str ");" .LP .BI "struct berval *ber_str2bv(const char *" str ", ber_len_t " len ", int " dup ", struct berval *" bv ");" .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "BerElement *ber_init(struct berval *" bv ");" .LP .BI "void ber_init2(BerElement *" ber ", struct berval *" bv ", int " options ");" .LP .BI "void ber_free(BerElement *" ber ", int " freebuf ");" .SH DESCRIPTION .LP The following are the basic types and structures defined for use with the Lightweight BER library. .LP .B ber_int_t is a signed integer of at least 32 bits. It is commonly equivalent to .BR int . .B ber_uint_t is the unsigned variant of .BR ber_int_t . .LP .B ber_len_t is an unsigned integer of at least 32 bits used to represent a length. It is commonly equivalent to a .BR size_t . .B ber_slen_t is the signed variant to .BR ber_len_t . .LP .B ber_tag_t is an unsigned integer of at least 32 bits used to represent a BER tag. It is commonly equivalent to a .BR unsigned\ long . .LP The actual definitions of the integral impl_TYPE_t types are platform specific. .LP .BR BerValue , commonly used as .BR struct\ berval , is used to hold an arbitrary sequence of octets. .B bv_val points to .B bv_len octets. .B bv_val is not necessarily terminated by a NULL (zero) octet. .BR ber_bvfree () frees a BerValue, pointed to by \fIbv\fP, returned from this API. If \fIbv\fP is NULL, the routine does nothing. .LP .BR ber_bvecfree () frees an array of BerValues (and the array), pointed to by \fIbvec\fP, returned from this API. If \fIbvec\fP is NULL, the routine does nothing. .BR ber_bvecadd () appends the \fIbv\fP pointer to the \fIbvec\fP array. Space for the array is allocated as needed. The end of the array is marked by a NULL pointer. .LP .BR ber_bvarray_free () frees an array of BerValues (and the array), pointed to by \fIbvarray\fP, returned from this API. If \fIbvarray\fP is NULL, the routine does nothing. .BR ber_bvarray_add () appends the contents of the BerValue pointed to by \fIbv\fP to the \fIbvarray\fP array. Space for the new element is allocated as needed. The end of the array is marked by a BerValue with a NULL bv_val field. .LP .BR ber_bvdup () returns a copy of a BerValue. The routine returns NULL upon error (e.g. out of memory). The caller should use .BR ber_bvfree () to deallocate the resulting BerValue. .BR ber_dupbv () copies a BerValue from \fIsrc\fP to \fIdst\fP. If \fIdst\fP is NULL a new BerValue will be allocated to hold the copy. The routine returns NULL upon error, otherwise it returns a pointer to the copy. If \fIdst\fP is NULL the caller should use .BR ber_bvfree () to deallocate the resulting BerValue, otherwise .BR ber_memfree () should be used to deallocate the \fIdst->bv_val\fP. (The .BR ber_bvdup () function is internally implemented as ber_dupbv(NULL, bv). .BR ber_bvdup () is provided only for compatibility with an expired draft of the LDAP C API; .BR ber_dupbv () is the preferred interface.) .LP .BR ber_bvstr () returns a BerValue containing the string pointed to by \fIstr\fP. .BR ber_bvstrdup () returns a BerValue containing a copy of the string pointed to by \fIstr\fP. .BR ber_str2bv () returns a BerValue containing the string pointed to by \fIstr\fP, whose length may be optionally specified in \fIlen\fP. If \fIdup\fP is non-zero, the BerValue will contain a copy of \fIstr\fP. If \fIlen\fP is zero, the number of bytes to copy will be determined by .BR strlen (3), otherwise \fIlen\fP bytes will be copied. If \fIbv\fP is non-NULL, the result will be stored in the given BerValue, otherwise a new BerValue will be allocated to store the result. NOTE: Both .BR ber_bvstr () and .BR ber_bvstrdup () are implemented as macros using .BR ber_str2bv () in this version of the library. .LP .B BerElement is an opaque structure used to maintain state information used in encoding and decoding. .BR ber_alloc_t () is used to create an empty BerElement structure. If .B LBER_USE_DER is specified for the .I options parameter then data lengths for data written to the BerElement will be encoded in the minimal number of octets required, otherwise they will always be written as four byte values. .BR ber_init () creates a BerElement structure that is initialized with a copy of the data in its .I bv parameter. .BR ber_init2 () initializes an existing BerElement .I ber using the data in the .I bv parameter. The data is referenced directly, not copied. The .I options parameter is the same as for .BR ber_alloc_t (). .BR ber_free () frees a BerElement pointed to by \fIber\fP. If \fIber\fP is NULL, the routine does nothing. If \fIfreebuf\fP is zero, the internal buffer is not freed. .SH SEE ALSO .BR lber-encode (3), .BR lber-decode (3), .BR lber-memory (3) .LP .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 189 stdin PK ��c\�w;+- - man/man3/ldap_next_reference.3nu �[��� .lf 1 stdin .TH LDAP_FIRST_REFERENCE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_first_reference, ldap_next_reference, ldap_count_references \- Stepping through continuation references in a result chain .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_count_references( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *reference ) .SH DESCRIPTION .LP These routines are used to step through the continuation references in a result chain received from .BR ldap_result (3) or the synchronous LDAP search operation routines. .LP The .B ldap_first_reference() routine is used to retrieve the first reference message in a result chain. It takes the \fIresult\fP as returned by a call to .BR ldap_result (3) , .BR ldap_search_s (3) or .BR ldap_search_st (3) and returns a pointer to the first reference message in the result chain. .LP This pointer should be supplied on a subsequent call to .B ldap_next_reference() to get the next reference message, the result of which should be supplied to the next call to .BR ldap_next_reference() , etc. .B ldap_next_reference() will return NULL when there are no more reference messages. The reference messages returned from these calls are used by .BR ldap_parse_reference (3) to extract referrals and controls. .LP A count of the number of reference messages in the search result can be obtained by calling .BR ldap_count_references() . It can also be used to count the number of reference messages remaining in a result chain. .SH ERRORS If an error occurs in .B ldap_first_reference() or .BR ldap_next_reference() , NULL is returned. If an error occurs in .BR ldap_count_references() , -1 is returned. .SH SEE ALSO .BR ldap (3), .BR ldap_result (3), .BR ldap_search (3), .BR ldap_parse_reference (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 72 stdin PK ��c\�c%u u man/man3/ldap_search_s.3nu �[��� .lf 1 stdin .TH LDAP_SEARCH 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_search, ldap_search_s, ldap_search_st, ldap_search_ext, ldap_search_ext_s \- Perform an LDAP search operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <sys/types.h> #include <ldap.h> .LP .ft B int ldap_search_ext( .RS LDAP *\fIld\fB, char *\fIbase\fB, int \fIscope\fB, char *\fIfilter\fB, char *\fIattrs\fB[], int \fIattrsonly\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB, struct timeval *\fItimeout\fB, int \fIsizelimit\fB, int *\fImsgidp\fB ); .RE .LP .ft B int ldap_search_ext_s( .RS LDAP *\fIld\fB, char *\fIbase\fB, int \fIscope\fB, char *\fIfilter\fB, char *\fIattrs\fB[], int \fIattrsonly\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB, struct timeval *\fItimeout\fB, int \fIsizelimit\fB, LDAPMessage **\fIres\fB ); .RE .SH DESCRIPTION These routines are used to perform LDAP search operations. The .B ldap_search_ext_s() routine does the search synchronously (i.e., not returning until the operation completes), providing a pointer to the resulting LDAP messages at the location pointed to by the \fIres\fP parameter. .LP The .B ldap_search_ext() routine is the asynchronous version, initiating the search and returning the message id of the operation it initiated in the integer pointed to by the \fImsgidp\fP parameter. .LP The \fIbase\fP parameter is the DN of the entry at which to start the search. .LP The \fIscope\fP parameter is the scope of the search and should be one of LDAP_SCOPE_BASE, to search the object itself, LDAP_SCOPE_ONELEVEL, to search the object's immediate children, LDAP_SCOPE_SUBTREE, to search the object and all its descendants, or LDAP_SCOPE_CHILDREN, to search all of the descendants. Note that the latter requires the server support the LDAP Subordinates Search Scope extension. .LP The \fIfilter\fP is a string representation of the filter to apply in the search. The string should conform to the format specified in RFC 4515 as extended by RFC 4526. For instance, "(cn=Jane Doe)". Note that use of the extension requires the server to support the LDAP Absolute True/False Filter extension. NULL may be specified to indicate the library should send the filter (objectClass=*). .LP The \fIattrs\fP parameter is a null-terminated array of attribute descriptions to return from matching entries. If NULL is specified, the return of all user attributes is requested. The description "*" (LDAP_ALL_USER_ATTRIBUTES) may be used to request all user attributes to be returned. The description "+"(LDAP_ALL_OPERATIONAL_ATTRIBUTES) may be used to request all operational attributes to be returned. Note that this requires the server to support the LDAP All Operational Attribute extension. To request no attributes, the description "1.1" (LDAP_NO_ATTRS) should be listed by itself. .LP The \fIattrsonly\fP parameter should be set to a non-zero value if only attribute descriptions are wanted. It should be set to zero (0) if both attributes descriptions and attribute values are wanted. .LP The \fIserverctrls\fP and \fIclientctrls\fP parameters may be used to specify server and client controls, respectively. .LP The .B ldap_search_ext_s() routine is the synchronous version of .BR ldap_search_ext(). .LP It also returns a code indicating success or, in the case of failure, indicating the nature of the failure of the operation. See .BR ldap_error (3) for details. .SH NOTES Note that both read and list functionality are subsumed by these routines, by using a filter like "(objectclass=*)" and a scope of LDAP_SCOPE_BASE (to emulate read) or LDAP_SCOPE_ONELEVEL (to emulate list). .LP These routines may dynamically allocate memory. The caller is responsible for freeing such memory using supplied deallocation routines. Return values are contained in <ldap.h>. .LP Note that \fIres\fR parameter of .B ldap_search_ext_s() and .B ldap_search_s() should be freed with .B ldap_msgfree() regardless of return value of these functions. .SH DEPRECATED INTERFACES The .B ldap_search() routine is deprecated in favor of the .B ldap_search_ext() routine. The .B ldap_search_s() and .B ldap_search_st() routines are deprecated in favor of the .B ldap_search_ext_s() routine. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 139 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_result (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 145 stdin PK ��c\�c%u u man/man3/ldap_search_ext.3nu �[��� .lf 1 stdin .TH LDAP_SEARCH 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_search, ldap_search_s, ldap_search_st, ldap_search_ext, ldap_search_ext_s \- Perform an LDAP search operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <sys/types.h> #include <ldap.h> .LP .ft B int ldap_search_ext( .RS LDAP *\fIld\fB, char *\fIbase\fB, int \fIscope\fB, char *\fIfilter\fB, char *\fIattrs\fB[], int \fIattrsonly\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB, struct timeval *\fItimeout\fB, int \fIsizelimit\fB, int *\fImsgidp\fB ); .RE .LP .ft B int ldap_search_ext_s( .RS LDAP *\fIld\fB, char *\fIbase\fB, int \fIscope\fB, char *\fIfilter\fB, char *\fIattrs\fB[], int \fIattrsonly\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB, struct timeval *\fItimeout\fB, int \fIsizelimit\fB, LDAPMessage **\fIres\fB ); .RE .SH DESCRIPTION These routines are used to perform LDAP search operations. The .B ldap_search_ext_s() routine does the search synchronously (i.e., not returning until the operation completes), providing a pointer to the resulting LDAP messages at the location pointed to by the \fIres\fP parameter. .LP The .B ldap_search_ext() routine is the asynchronous version, initiating the search and returning the message id of the operation it initiated in the integer pointed to by the \fImsgidp\fP parameter. .LP The \fIbase\fP parameter is the DN of the entry at which to start the search. .LP The \fIscope\fP parameter is the scope of the search and should be one of LDAP_SCOPE_BASE, to search the object itself, LDAP_SCOPE_ONELEVEL, to search the object's immediate children, LDAP_SCOPE_SUBTREE, to search the object and all its descendants, or LDAP_SCOPE_CHILDREN, to search all of the descendants. Note that the latter requires the server support the LDAP Subordinates Search Scope extension. .LP The \fIfilter\fP is a string representation of the filter to apply in the search. The string should conform to the format specified in RFC 4515 as extended by RFC 4526. For instance, "(cn=Jane Doe)". Note that use of the extension requires the server to support the LDAP Absolute True/False Filter extension. NULL may be specified to indicate the library should send the filter (objectClass=*). .LP The \fIattrs\fP parameter is a null-terminated array of attribute descriptions to return from matching entries. If NULL is specified, the return of all user attributes is requested. The description "*" (LDAP_ALL_USER_ATTRIBUTES) may be used to request all user attributes to be returned. The description "+"(LDAP_ALL_OPERATIONAL_ATTRIBUTES) may be used to request all operational attributes to be returned. Note that this requires the server to support the LDAP All Operational Attribute extension. To request no attributes, the description "1.1" (LDAP_NO_ATTRS) should be listed by itself. .LP The \fIattrsonly\fP parameter should be set to a non-zero value if only attribute descriptions are wanted. It should be set to zero (0) if both attributes descriptions and attribute values are wanted. .LP The \fIserverctrls\fP and \fIclientctrls\fP parameters may be used to specify server and client controls, respectively. .LP The .B ldap_search_ext_s() routine is the synchronous version of .BR ldap_search_ext(). .LP It also returns a code indicating success or, in the case of failure, indicating the nature of the failure of the operation. See .BR ldap_error (3) for details. .SH NOTES Note that both read and list functionality are subsumed by these routines, by using a filter like "(objectclass=*)" and a scope of LDAP_SCOPE_BASE (to emulate read) or LDAP_SCOPE_ONELEVEL (to emulate list). .LP These routines may dynamically allocate memory. The caller is responsible for freeing such memory using supplied deallocation routines. Return values are contained in <ldap.h>. .LP Note that \fIres\fR parameter of .B ldap_search_ext_s() and .B ldap_search_s() should be freed with .B ldap_msgfree() regardless of return value of these functions. .SH DEPRECATED INTERFACES The .B ldap_search() routine is deprecated in favor of the .B ldap_search_ext() routine. The .B ldap_search_s() and .B ldap_search_st() routines are deprecated in favor of the .B ldap_search_ext_s() routine. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 139 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_result (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 145 stdin PK ��c\�C�B� � man/man3/ldap_compare.3nu �[��� .lf 1 stdin .TH LDAP_COMPARE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_compare, ldap_compare_s, ldap_compare_ext, ldap_compare_ext_s \- Perform an LDAP compare operation. .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_compare_ext( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, char *\fIattr\fB, const struct berval *\fIbvalue\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB, int *\fImsgidp\fB ); .RE .LP .ft B int ldap_compare_ext_s( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, char *\fIattr\fB, const struct berval *\fIbvalue\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB ); .RE .SH DESCRIPTION The .B ldap_compare_ext_s() routine is used to perform an LDAP compare operation synchronously. It takes \fIdn\fP, the DN of the entry upon which to perform the compare, and \fIattr\fP and \fIvalue\fP, the attribute description and value to compare to those found in the entry. It returns a code, which will be LDAP_COMPARE_TRUE if the entry contains the attribute value and LDAP_COMPARE_FALSE if it does not. Otherwise, an error code is returned that indicates the nature of the problem. See .BR ldap (3) for details. .LP The .B ldap_compare_ext() routine is used to perform an LDAP compare operation asynchronously. It takes the same parameters as .BR ldap_compare_ext_s() , but provides the message id of the request it initiated in the integer pointed to \fImsgidp\fP. The result of the compare can be obtained by a subsequent call to .BR ldap_result (3). .LP Both routines allow server and client controls to be specified to extend the compare request. .SH DEPRECATED INTERFACES The routines .BR ldap_compare () and .BR ldap_compare_s () are deprecated in favor of .BR ldap_compare_ext () and .BR ldap_compare_ext_s (), respectively. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 75 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 80 stdin PK ��c\�շY� � man/man3/ber_bvarray_free.3nu �[��� .lf 1 stdin .TH LBER_TYPES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_int_t, ber_uint_t, ber_len_t, ber_slen_t, ber_tag_t, struct berval, BerValue, BerVarray, BerElement, ber_bvfree, ber_bvecfree, ber_bvecadd, ber_bvarray_free, ber_bvarray_add, ber_bvdup, ber_dupbv, ber_bvstr, ber_bvstrdup, ber_str2bv, ber_alloc_t, ber_init, ber_init2, ber_free \- OpenLDAP LBER types and allocation functions .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .nf .ft B typedef impl_tag_t ber_tag_t; typedef impl_int_t ber_int_t; typedef impl_uint_t ber_uint_t; typedef impl_len_t ber_len_t; typedef impl_slen_t ber_slen_t; typedef struct berval { ber_len_t bv_len; char *bv_val; } BerValue, *BerVarray; typedef struct berelement BerElement; .ft .fi .LP .BI "void ber_bvfree(struct berval *" bv ");" .LP .BI "void ber_bvecfree(struct berval **" bvec ");" .LP .BI "void ber_bvecadd(struct berval ***" bvec ", struct berval *" bv ");" .LP .BI "void ber_bvarray_free(struct berval *" bvarray ");" .LP .BI "void ber_bvarray_add(BerVarray *" bvarray ", BerValue *" bv ");" .LP .BI "struct berval *ber_bvdup(const struct berval *" bv ");" .LP .BI "struct berval *ber_dupbv(const struct berval *" dst ", struct berval *" src ");" .LP .BI "struct berval *ber_bvstr(const char *" str ");" .LP .BI "struct berval *ber_bvstrdup(const char *" str ");" .LP .BI "struct berval *ber_str2bv(const char *" str ", ber_len_t " len ", int " dup ", struct berval *" bv ");" .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "BerElement *ber_init(struct berval *" bv ");" .LP .BI "void ber_init2(BerElement *" ber ", struct berval *" bv ", int " options ");" .LP .BI "void ber_free(BerElement *" ber ", int " freebuf ");" .SH DESCRIPTION .LP The following are the basic types and structures defined for use with the Lightweight BER library. .LP .B ber_int_t is a signed integer of at least 32 bits. It is commonly equivalent to .BR int . .B ber_uint_t is the unsigned variant of .BR ber_int_t . .LP .B ber_len_t is an unsigned integer of at least 32 bits used to represent a length. It is commonly equivalent to a .BR size_t . .B ber_slen_t is the signed variant to .BR ber_len_t . .LP .B ber_tag_t is an unsigned integer of at least 32 bits used to represent a BER tag. It is commonly equivalent to a .BR unsigned\ long . .LP The actual definitions of the integral impl_TYPE_t types are platform specific. .LP .BR BerValue , commonly used as .BR struct\ berval , is used to hold an arbitrary sequence of octets. .B bv_val points to .B bv_len octets. .B bv_val is not necessarily terminated by a NULL (zero) octet. .BR ber_bvfree () frees a BerValue, pointed to by \fIbv\fP, returned from this API. If \fIbv\fP is NULL, the routine does nothing. .LP .BR ber_bvecfree () frees an array of BerValues (and the array), pointed to by \fIbvec\fP, returned from this API. If \fIbvec\fP is NULL, the routine does nothing. .BR ber_bvecadd () appends the \fIbv\fP pointer to the \fIbvec\fP array. Space for the array is allocated as needed. The end of the array is marked by a NULL pointer. .LP .BR ber_bvarray_free () frees an array of BerValues (and the array), pointed to by \fIbvarray\fP, returned from this API. If \fIbvarray\fP is NULL, the routine does nothing. .BR ber_bvarray_add () appends the contents of the BerValue pointed to by \fIbv\fP to the \fIbvarray\fP array. Space for the new element is allocated as needed. The end of the array is marked by a BerValue with a NULL bv_val field. .LP .BR ber_bvdup () returns a copy of a BerValue. The routine returns NULL upon error (e.g. out of memory). The caller should use .BR ber_bvfree () to deallocate the resulting BerValue. .BR ber_dupbv () copies a BerValue from \fIsrc\fP to \fIdst\fP. If \fIdst\fP is NULL a new BerValue will be allocated to hold the copy. The routine returns NULL upon error, otherwise it returns a pointer to the copy. If \fIdst\fP is NULL the caller should use .BR ber_bvfree () to deallocate the resulting BerValue, otherwise .BR ber_memfree () should be used to deallocate the \fIdst->bv_val\fP. (The .BR ber_bvdup () function is internally implemented as ber_dupbv(NULL, bv). .BR ber_bvdup () is provided only for compatibility with an expired draft of the LDAP C API; .BR ber_dupbv () is the preferred interface.) .LP .BR ber_bvstr () returns a BerValue containing the string pointed to by \fIstr\fP. .BR ber_bvstrdup () returns a BerValue containing a copy of the string pointed to by \fIstr\fP. .BR ber_str2bv () returns a BerValue containing the string pointed to by \fIstr\fP, whose length may be optionally specified in \fIlen\fP. If \fIdup\fP is non-zero, the BerValue will contain a copy of \fIstr\fP. If \fIlen\fP is zero, the number of bytes to copy will be determined by .BR strlen (3), otherwise \fIlen\fP bytes will be copied. If \fIbv\fP is non-NULL, the result will be stored in the given BerValue, otherwise a new BerValue will be allocated to store the result. NOTE: Both .BR ber_bvstr () and .BR ber_bvstrdup () are implemented as macros using .BR ber_str2bv () in this version of the library. .LP .B BerElement is an opaque structure used to maintain state information used in encoding and decoding. .BR ber_alloc_t () is used to create an empty BerElement structure. If .B LBER_USE_DER is specified for the .I options parameter then data lengths for data written to the BerElement will be encoded in the minimal number of octets required, otherwise they will always be written as four byte values. .BR ber_init () creates a BerElement structure that is initialized with a copy of the data in its .I bv parameter. .BR ber_init2 () initializes an existing BerElement .I ber using the data in the .I bv parameter. The data is referenced directly, not copied. The .I options parameter is the same as for .BR ber_alloc_t (). .BR ber_free () frees a BerElement pointed to by \fIber\fP. If \fIber\fP is NULL, the routine does nothing. If \fIfreebuf\fP is zero, the internal buffer is not freed. .SH SEE ALSO .BR lber-encode (3), .BR lber-decode (3), .BR lber-memory (3) .LP .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 189 stdin PK ��c\g�d"# "# man/man3/ldap_objectclass2name.3nu �[��� .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin PK ��c\�շY� � man/man3/ber_str2bv.3nu �[��� .lf 1 stdin .TH LBER_TYPES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_int_t, ber_uint_t, ber_len_t, ber_slen_t, ber_tag_t, struct berval, BerValue, BerVarray, BerElement, ber_bvfree, ber_bvecfree, ber_bvecadd, ber_bvarray_free, ber_bvarray_add, ber_bvdup, ber_dupbv, ber_bvstr, ber_bvstrdup, ber_str2bv, ber_alloc_t, ber_init, ber_init2, ber_free \- OpenLDAP LBER types and allocation functions .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .nf .ft B typedef impl_tag_t ber_tag_t; typedef impl_int_t ber_int_t; typedef impl_uint_t ber_uint_t; typedef impl_len_t ber_len_t; typedef impl_slen_t ber_slen_t; typedef struct berval { ber_len_t bv_len; char *bv_val; } BerValue, *BerVarray; typedef struct berelement BerElement; .ft .fi .LP .BI "void ber_bvfree(struct berval *" bv ");" .LP .BI "void ber_bvecfree(struct berval **" bvec ");" .LP .BI "void ber_bvecadd(struct berval ***" bvec ", struct berval *" bv ");" .LP .BI "void ber_bvarray_free(struct berval *" bvarray ");" .LP .BI "void ber_bvarray_add(BerVarray *" bvarray ", BerValue *" bv ");" .LP .BI "struct berval *ber_bvdup(const struct berval *" bv ");" .LP .BI "struct berval *ber_dupbv(const struct berval *" dst ", struct berval *" src ");" .LP .BI "struct berval *ber_bvstr(const char *" str ");" .LP .BI "struct berval *ber_bvstrdup(const char *" str ");" .LP .BI "struct berval *ber_str2bv(const char *" str ", ber_len_t " len ", int " dup ", struct berval *" bv ");" .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "BerElement *ber_init(struct berval *" bv ");" .LP .BI "void ber_init2(BerElement *" ber ", struct berval *" bv ", int " options ");" .LP .BI "void ber_free(BerElement *" ber ", int " freebuf ");" .SH DESCRIPTION .LP The following are the basic types and structures defined for use with the Lightweight BER library. .LP .B ber_int_t is a signed integer of at least 32 bits. It is commonly equivalent to .BR int . .B ber_uint_t is the unsigned variant of .BR ber_int_t . .LP .B ber_len_t is an unsigned integer of at least 32 bits used to represent a length. It is commonly equivalent to a .BR size_t . .B ber_slen_t is the signed variant to .BR ber_len_t . .LP .B ber_tag_t is an unsigned integer of at least 32 bits used to represent a BER tag. It is commonly equivalent to a .BR unsigned\ long . .LP The actual definitions of the integral impl_TYPE_t types are platform specific. .LP .BR BerValue , commonly used as .BR struct\ berval , is used to hold an arbitrary sequence of octets. .B bv_val points to .B bv_len octets. .B bv_val is not necessarily terminated by a NULL (zero) octet. .BR ber_bvfree () frees a BerValue, pointed to by \fIbv\fP, returned from this API. If \fIbv\fP is NULL, the routine does nothing. .LP .BR ber_bvecfree () frees an array of BerValues (and the array), pointed to by \fIbvec\fP, returned from this API. If \fIbvec\fP is NULL, the routine does nothing. .BR ber_bvecadd () appends the \fIbv\fP pointer to the \fIbvec\fP array. Space for the array is allocated as needed. The end of the array is marked by a NULL pointer. .LP .BR ber_bvarray_free () frees an array of BerValues (and the array), pointed to by \fIbvarray\fP, returned from this API. If \fIbvarray\fP is NULL, the routine does nothing. .BR ber_bvarray_add () appends the contents of the BerValue pointed to by \fIbv\fP to the \fIbvarray\fP array. Space for the new element is allocated as needed. The end of the array is marked by a BerValue with a NULL bv_val field. .LP .BR ber_bvdup () returns a copy of a BerValue. The routine returns NULL upon error (e.g. out of memory). The caller should use .BR ber_bvfree () to deallocate the resulting BerValue. .BR ber_dupbv () copies a BerValue from \fIsrc\fP to \fIdst\fP. If \fIdst\fP is NULL a new BerValue will be allocated to hold the copy. The routine returns NULL upon error, otherwise it returns a pointer to the copy. If \fIdst\fP is NULL the caller should use .BR ber_bvfree () to deallocate the resulting BerValue, otherwise .BR ber_memfree () should be used to deallocate the \fIdst->bv_val\fP. (The .BR ber_bvdup () function is internally implemented as ber_dupbv(NULL, bv). .BR ber_bvdup () is provided only for compatibility with an expired draft of the LDAP C API; .BR ber_dupbv () is the preferred interface.) .LP .BR ber_bvstr () returns a BerValue containing the string pointed to by \fIstr\fP. .BR ber_bvstrdup () returns a BerValue containing a copy of the string pointed to by \fIstr\fP. .BR ber_str2bv () returns a BerValue containing the string pointed to by \fIstr\fP, whose length may be optionally specified in \fIlen\fP. If \fIdup\fP is non-zero, the BerValue will contain a copy of \fIstr\fP. If \fIlen\fP is zero, the number of bytes to copy will be determined by .BR strlen (3), otherwise \fIlen\fP bytes will be copied. If \fIbv\fP is non-NULL, the result will be stored in the given BerValue, otherwise a new BerValue will be allocated to store the result. NOTE: Both .BR ber_bvstr () and .BR ber_bvstrdup () are implemented as macros using .BR ber_str2bv () in this version of the library. .LP .B BerElement is an opaque structure used to maintain state information used in encoding and decoding. .BR ber_alloc_t () is used to create an empty BerElement structure. If .B LBER_USE_DER is specified for the .I options parameter then data lengths for data written to the BerElement will be encoded in the minimal number of octets required, otherwise they will always be written as four byte values. .BR ber_init () creates a BerElement structure that is initialized with a copy of the data in its .I bv parameter. .BR ber_init2 () initializes an existing BerElement .I ber using the data in the .I bv parameter. The data is referenced directly, not copied. The .I options parameter is the same as for .BR ber_alloc_t (). .BR ber_free () frees a BerElement pointed to by \fIber\fP. If \fIber\fP is NULL, the routine does nothing. If \fIfreebuf\fP is zero, the internal buffer is not freed. .SH SEE ALSO .BR lber-encode (3), .BR lber-decode (3), .BR lber-memory (3) .LP .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 189 stdin PK ��c\ ȵ�� � man/man3/ldap_sort.3nu �[��� .lf 1 stdin .TH LDAP_SORT 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_sort_entries, ldap_sort_values, ldap_sort_strcasecmp \- LDAP sorting routines (deprecated) .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH DESCRIPTION The .BR ldap_sort_entries (), .BR ldap_sort_values (), and .BR ldap_sort_strcasecmp () are deprecated. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 18 stdin .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 22 stdin PK ��c\�4�� � man/man3/ldap_modify_ext.3nu �[��� .lf 1 stdin .TH LDAP_MODIFY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_modify_ext, ldap_modify_ext_s \- Perform an LDAP modify operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_modify_ext( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, LDAPMod *\fImods[]\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB, int *\fImsgidp\fB ); .RE .LP .nf .ft B int ldap_modify_ext_s( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, LDAPMod *\fImods[]\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB ); .RE .LP .nf .ft B void ldap_mods_free( .RS .ft B LDAPMod **\fImods\fB, int \fIfreemods\fB ); .RE .SH DESCRIPTION The routine .B ldap_modify_ext_s() is used to perform an LDAP modify operation. \fIdn\fP is the DN of the entry to modify, and \fImods\fP is a null-terminated array of modifications to make to the entry. Each element of the \fImods\fP array is a pointer to an LDAPMod structure, which is defined below. .LP .nf typedef struct ldapmod { int mod_op; char *mod_type; union { char **modv_strvals; struct berval **modv_bvals; } mod_vals; struct ldapmod *mod_next; } LDAPMod; #define mod_values mod_vals.modv_strvals #define mod_bvalues mod_vals.modv_bvals .ft .fi .LP The \fImod_op\fP field is used to specify the type of modification to perform and should be one of LDAP_MOD_ADD, LDAP_MOD_DELETE, or LDAP_MOD_REPLACE. The \fImod_type\fP and \fImod_values\fP fields specify the attribute type to modify and a null-terminated array of values to add, delete, or replace respectively. The \fImod_next\fP field is used only by the LDAP server and may be ignored by the client. .LP If you need to specify a non-string value (e.g., to add a photo or audio attribute value), you should set \fImod_op\fP to the logical OR of the operation as above (e.g., LDAP_MOD_REPLACE) and the constant LDAP_MOD_BVALUES. In this case, \fImod_bvalues\fP should be used instead of \fImod_values\fP, and it should point to a null-terminated array of struct bervals, as defined in <lber.h>. .LP 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 attribute is to be deleted, the \fImod_values\fP field should be set to NULL. For LDAP_MOD_REPLACE modifications, the attribute will have the listed values after the modification, having been created if necessary. All modifications are performed in the order in which they are listed. .LP .B ldap_mods_free() can be used to free each element of a NULL-terminated array of mod structures. If \fIfreemods\fP is non-zero, the \fImods\fP pointer itself is freed as well. .LP .B ldap_modify_ext_s() returns a code indicating success or, in the case of failure, indicating the nature of the failure. See .BR ldap_error (3) for details .LP The .B ldap_modify_ext() operation works the same way as .BR ldap_modify_ext_s() , except that it is asynchronous. The integer that \fImsgidp\fP points to is set to the message id of the modify request. The result of the operation can be obtained by calling .BR ldap_result (3). .LP Both .B ldap_modify_ext() and .B ldap_modify_ext_s() allows server and client controls to be passed in via the sctrls and cctrls parameters, respectively. .SH DEPRECATED INTERFACES The .B ldap_modify() and .B ldap_modify_s() routines are deprecated in favor of the .B ldap_modify_ext() and .B ldap_modify_ext_s() routines, respectively. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 132 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 137 stdin PK ��c\����� � man/man3/ldap_get_values_len.3nu �[��� .lf 1 stdin .TH LDAP_GET_VALUES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_values, ldap_get_values_len, ldap_count_values \- LDAP attribute value handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char **ldap_get_values(ld, entry, attr) .ft LDAP *ld; LDAPMessage *entry; char *attr; .LP .ft B struct berval **ldap_get_values_len(ld, entry, attr) .ft LDAP *ld; LDAPMessage *entry; char *attr; .LP .ft B int ldap_count_values(vals) .ft char **vals; .LP .ft B int ldap_count_values_len(vals) .ft struct berval **vals; .LP .ft B void ldap_value_free(vals) .ft char **vals; .LP .ft B void ldap_value_free_len(vals) .ft struct berval **vals; .SH DESCRIPTION These routines are used to retrieve and manipulate attribute values from an LDAP entry as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3). .B ldap_get_values() takes the \fIentry\fP and the attribute \fIattr\fP whose values are desired and returns a NULL-terminated array of the attribute's values. \fIattr\fP may be an attribute type as returned from .BR ldap_first_attribute (3) or .BR ldap_next_attribute (3), or if the attribute type is known it can simply be given. .LP The number of values in the array can be counted by calling .BR ldap_count_values() . The array of values returned can be freed by calling .BR ldap_value_free() . .LP If the attribute values are binary in nature, and thus not suitable to be returned as an array of char *'s, the .B ldap_get_values_len() routine can be used instead. It takes the same parameters as .BR ldap_get_values() , but returns a NULL-terminated array of pointers to berval structures, each containing the length of and a pointer to a value. .LP The number of values in the array can be counted by calling .BR ldap_count_values_len() . The array of values returned can be freed by calling .BR ldap_value_free_len() . .SH ERRORS If an error occurs in .B ldap_get_values() or .BR ldap_get_values_len() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .SH NOTES These routines dynamically allocate memory which the caller must free using the supplied routines. .SH SEE ALSO .BR ldap (3), .BR ldap_first_entry (3), .BR ldap_first_attribute (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 103 stdin PK ��c\�E͡ � man/man3/ldap_msgfree.3nu �[��� .lf 1 stdin .TH LDAP_RESULT 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_result \- Wait for the result of an LDAP operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_result( LDAP *ld, int msgid, int all, struct timeval *timeout, LDAPMessage **result ); int ldap_msgfree( LDAPMessage *msg ); int ldap_msgtype( LDAPMessage *msg ); int ldap_msgid( LDAPMessage *msg ); .ft .SH DESCRIPTION The .B ldap_result() routine is used to wait for and return the result of an operation previously initiated by one of the LDAP asynchronous operation routines (e.g., .BR ldap_search_ext (3), .BR ldap_modify_ext (3), etc.). Those routines all return \-1 in case of error, and an invocation identifier upon successful initiation of the operation. The invocation identifier is picked by the library and is guaranteed to be unique across the LDAP session. It can be used to request the result of a specific operation from .B ldap_result() through the \fImsgid\fP parameter. .LP The .B ldap_result() routine will block or not, depending upon the setting of the \fItimeout\fP parameter. If timeout is not a NULL pointer, it specifies a maximum interval to wait for the selection to complete. If timeout is a NULL pointer, the LDAP_OPT_TIMEOUT value set by .BR ldap_set_option (3) is used. With the default setting, the select blocks indefinitely. To effect a poll, the timeout argument should be a non-NULL pointer, pointing to a zero-valued timeval structure. To obtain the behavior of the default setting, bypassing any value set by .BR ldap_set_option (3), set to -1 the \fItv_sec\fP field of the \fItimeout\fP parameter. See .BR select (2) for further details. .LP If the result of a specific operation is required, \fImsgid\fP should be set to the invocation identifier returned when the operation was initiated, otherwise LDAP_RES_ANY or LDAP_RES_UNSOLICITED should be supplied to wait for any or unsolicited response. .LP The \fIall\fP parameter, if non-zero, causes .B ldap_result() to return all responses with msgid, otherwise only the next response is returned. This is commonly used to obtain all the responses of a search operation. .LP A search response is made up of zero or more search entries, zero or more search references, and zero or more extended partial responses followed by a search result. If \fIall\fP is set to 0, search entries will be returned one at a time as they come in, via separate calls to .BR ldap_result() . If it's set to 1, the search response will only be returned in its entirety, i.e., after all entries, all references, all extended partial responses, and the final search result have been received. .SH RETURN VALUE Upon success, the type of the result received is returned and the \fIresult\fP parameter will contain the result of the operation; otherwise, the \fIresult\fP parameter is undefined. This result should be passed to the LDAP parsing routines, .BR ldap_first_message (3) and friends, for interpretation. .LP The possible result types returned are: .LP .nf LDAP_RES_BIND (0x61) LDAP_RES_SEARCH_ENTRY (0x64) LDAP_RES_SEARCH_REFERENCE (0x73) 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) LDAP_RES_INTERMEDIATE (0x79) .fi .LP The .B ldap_msgfree() routine is used to free the memory allocated for result(s) by .B ldap_result() or .BR ldap_search_ext_s (3) and friends. It takes a pointer to the result or result chain to be freed and returns the type of the last message in the chain. If the parameter is NULL, the function does nothing and returns zero. .LP The .B ldap_msgtype() routine returns the type of a message. .LP The .B ldap_msgid() routine returns the message id of a message. .SH ERRORS .B ldap_result() returns \-1 if something bad happens, and zero if the timeout specified was exceeded. .B ldap_msgtype() and .B ldap_msgid() return \-1 on error. .SH SEE ALSO .BR ldap (3), .BR ldap_first_message (3), .BR select (2) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 137 stdin PK ��c\g�d"# "# ! man/man3/ldap_str2attributetype.3nu �[��� .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin PK ��c\ NO O man/man3/ldap_count_messages.3nu �[��� .lf 1 stdin .TH LDAP_FIRST_MESSAGE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_first_message, ldap_next_message, ldap_count_messages \- Stepping through messages in a result chain .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_count_messages( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_next_message( LDAP *ld, LDAPMessage *message ) .SH DESCRIPTION .LP These routines are used to step through the messages in a result chain received from .BR ldap_result (3) . For search operations, the result chain can contain referral, entry and result messages. The .BR ldap_msgtype (3) function can be used to distinguish between the different message types. .LP The .B ldap_first_message() routine is used to retrieve the first message in a result chain. It takes the \fIresult\fP as returned by a call to .BR ldap_result (3) , .BR ldap_search_s (3) or .BR ldap_search_st (3) and returns a pointer to the first message in the result chain. .LP This pointer should be supplied on a subsequent call to .B ldap_next_message() to get the next message, the result of which should be supplied to the next call to .BR ldap_next_message() , etc. .B ldap_next_message() will return NULL when there are no more messages. .LP These functions are useful when using routines like .BR ldap_parse_result (3) that only operate on the first result in the chain. .LP A count of the number of messages in the result chain can be obtained by calling .BR ldap_count_messages() . It can also be used to count the number of remaining messages in a chain if called with a message, entry or reference returned by .B ldap_first_message() , .B ldap_next_message() , .BR ldap_first_entry (3) , .BR ldap_next_entry (3) , .BR ldap_first_reference (3) , .BR ldap_next_reference (3) . .SH ERRORS If an error occurs in .B ldap_first_message() or .BR ldap_next_message() , NULL is returned. If an error occurs in .BR ldap_count_messages() , -1 is returned. .SH SEE ALSO .BR ldap (3), .BR ldap_search (3), .BR ldap_result (3), .BR ldap_parse_result (3), .BR ldap_first_entry (3), .BR ldap_first_reference (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 83 stdin PK ��c\��1ܽ � man/man3/ldap_controls_free.3nu �[��� .lf 1 stdin .TH LDAP_CONTROLS 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_control_create, ldap_control_find, ldap_control_dup, ldap_controls_dup, ldap_control_free, ldap_controls_free \- LDAP control manipulation routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "int ldap_control_create(const char *" oid ", int " iscritical ", struct berval *" value ", int " dupval ", LDAPControl **" ctrlp ");" .LP .BI "LDAPControl *ldap_control_find( const char *" oid ", LDAPControl **" ctrls ", LDAPControl ***" nextctrlp ");" .LP .BI "LDAPControl *ldap_control_dup(LDAPControl *" ctrl ");" .LP .BI "LDAPControl **ldap_controls_dup(LDAPControl **" ctrls ");" .LP .BI "void ldap_control_free(LDAPControl *" ctrl ");" .LP .BI "void ldap_controls_free(LDAPControl **" ctrls ");" .SH DESCRIPTION These routines are used to manipulate structures used for LDAP controls. .BR ldap_control_create () creates a control with the specified .I OID using the contents of the .I value parameter for the control value, if any. The content of .I value is duplicated if .I dupval is non-zero. The .I iscritical parameter must be non-zero for a critical control. The created control is returned in the .I ctrlp parameter. The routine returns .B LDAP_SUCCESS on success or some other error code on failure. The content of .IR value , for supported control types, can be prepared using helpers provided by this implementation of libldap, usually in the form .BR "ldap_create_<control name>_control_value" (). Otherwise, it can be BER-encoded using the functionalities of liblber. .BR ldap_control_find () searches the NULL-terminated .I ctrls array for a control whose OID matches the .I oid parameter. The routine returns a pointer to the control if found, NULL otherwise. If the parameter .I nextctrlp is not NULL, on return it will point to the next control in the array, and can be passed to the .BR ldap_control_find () routine for subsequent calls, to find further occurrences of the same control type. The use of this function is discouraged; the recommended way of handling controls in responses consists in going through the array of controls, dealing with each of them in the returned order, since it could matter. .BR ldap_control_dup () duplicates an individual control structure, and .BR ldap_controls_dup () duplicates a NULL-terminated array of controls. .BR ldap_control_free () frees an individual control structure, and .BR ldap_controls_free () frees a NULL-terminated array of controls. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 85 stdin PK ��c\�5^#v1 v1 man/man3/ber_scanf.3nu �[��� .lf 1 stdin .TH LBER_DECODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");" .LP .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");" .LP .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");" .LP .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");" .LP .BI "ber_tag_t ber_get_null(BerElement *" ber ");" .LP .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");" .LP .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");" .LP .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");" .LP .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the decoding routines in the lber library. See .BR lber-encode (3) for details on the corresponding encoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_get_next () to get the next BER element and .BR ber_scanf () to do the actual decoding. In some cases, .BR ber_peek_tag () may also need to be called in normal usage. The other routines are provided for those applications that need more control than .BR ber_scanf () provides. In general, these routines return the tag of the element decoded, or LBER_ERROR if an error occurred. .LP The .BR ber_get_next () routine is used to read the next BER element from the given Sockbuf, \fIsb\fP. It strips off and returns the leading tag, strips off and returns the length of the entire element in \fIlen\fP, and sets up \fIber\fP for subsequent calls to .BR ber_scanf () et al to decode the element. See .BR lber-sockbuf (3) for details of the Sockbuf implementation of the \fIsb\fP parameter. .LP The .BR ber_scanf () routine is used to decode a BER element in much the same way that .BR scanf (3) works. It reads from \fIber\fP, a pointer to a BerElement such as returned by .BR ber_get_next (), interprets the bytes according to the format string \fIfmt\fP, and stores the results in its additional arguments. 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. .RS .LP .TP 3 .B a Octet string. A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter. The caller should free the returned string using .BR ber_memfree (). .TP .B A Octet string. A variant of "\fBa\fP". A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter, unless a zero-length string would result; in that case, the arg is set to NULL. The caller should free the returned string using .BR ber_memfree (). .TP .B s Octet string. A char * buffer should be supplied, followed by a pointer to a ber_len_t initialized to the size of the buffer. Upon return, the null-terminated octet string is put into the buffer, and the ber_len_t is set to the actual size of the octet string. .TP .B O Octet string. A struct ber_val ** should be supplied, which upon return points to a dynamically allocated struct berval containing the octet string and its length. The caller should free the returned structure using .BR ber_bvfree (). .TP .B o Octet string. A struct ber_val * should be supplied, which upon return contains the dynamically allocated octet string and its length. The caller should free the returned octet string using .BR ber_memfree (). .TP .B m Octet string. A struct ber_val * should be supplied, which upon return contains the octet string and its length. The string resides in memory assigned to the BerElement, and must not be freed by the caller. .TP .B b Boolean. A pointer to a ber_int_t should be supplied. .TP .B e Enumeration. A pointer to a ber_int_t should be supplied. .TP .B i Integer. A pointer to a ber_int_t should be supplied. .TP .B B Bitstring. A char ** should be supplied which will point to the dynamically allocated bits, followed by a ber_len_t *, which will point to the length (in bits) of the bitstring returned. .TP .B n Null. No parameter is required. The element is simply skipped if it is recognized. .TP .B v Sequence of octet strings. A char *** should be supplied, which upon return points to a dynamically allocated null-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty. The caller should free the returned array and octet strings using .BR ber_memvfree (). .TP .B V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon return points to a dynamically allocated null-terminated array of struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvecfree (). .TP .B W Sequence of octet strings with lengths. A BerVarray * should be supplied, which upon return points to a dynamically allocated array of struct berval's containing the octet strings and their lengths. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvarray_free (). .TP .B M Sequence of octet strings with lengths. This is a generalized form of the previous three formats. A void ** (ptr) should be supplied, followed by a ber_len_t * (len) and a ber_len_t (off). Upon return (ptr) will point to a dynamically allocated array whose elements are all of size (*len). A struct berval will be filled starting at offset (off) in each element. The strings in each struct berval reside in memory assigned to the BerElement and must not be freed by the caller. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The number of elements in the array is also stored in (*len) on return. The caller should free the returned array using .BR ber_memfree (). .TP .B l Length of the next element. A pointer to a ber_len_t should be supplied. .TP .B t Tag of the next element. A pointer to a ber_tag_t should be supplied. .TP .B T Skip element and return its tag. A pointer to a ber_tag_t should be supplied. .TP .B x Skip element. The next element is skipped. .TP .B { Begin sequence. No parameter is required. The initial sequence tag and length are skipped. .TP .B } End sequence. No parameter is required and no action is taken. .TP .B [ Begin set. No parameter is required. The initial set tag and length are skipped. .TP .B ] End set. No parameter is required and no action is taken. .RE .LP The .BR ber_get_int () routine tries to interpret the next element as an integer, returning the result in \fInum\fP. The tag of whatever it finds is returned on success, LBER_ERROR (\-1) on failure. .LP The .BR ber_get_stringb () routine is used to read an octet string into a preallocated buffer. The \fIlen\fP parameter should be initialized to the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte. .LP The .BR ber_get_stringa () routine is used to dynamically allocate space into which an octet string is read. The caller should free the returned string using .BR ber_memfree(). .LP The .BR ber_get_stringal () routine is used to dynamically allocate space into which an octet string and its length are read. It takes a struct berval **, and returns the result in this parameter. The caller should free the returned structure using .BR ber_bvfree(). .LP The .BR ber_get_stringbv () routine is used to read an octet string and its length into the provided struct berval *. If the \fIalloc\fP parameter is zero, the string will reside in memory assigned to the BerElement, and must not be freed by the caller. If the \fIalloc\fP parameter is non-zero, the string will be copied into dynamically allocated space which should be returned using .BR ber_memfree (). .LP The .BR ber_get_null () routine is used to read a NULL element. It returns the tag of the element it skips over. .LP The .BR ber_get_boolean () routine is used to read a boolean value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_enum () routine is used to read a enumeration value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_bitstringa () routine is used to read a bitstring value. It takes a char ** which will hold the dynamically allocated bits, followed by an ber_len_t *, which will point to the length (in bits) of the bitstring returned. The caller should free the returned string using .BR ber_memfree (). .LP The .BR ber_first_element () routine is used to return the tag and length of the first element in a set or sequence. It also returns in \fIcookie\fP a magic cookie parameter that should be passed to subsequent calls to ber_next_element(), which returns similar information. .SH EXAMPLES Assume the variable \fIber\fP contains a lightweight BER encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP The element can be decoded using .BR ber_scanf () as follows. .LP .nf ber_int_t scope, deref, size, time, attrsonly; char *dn, **attrs; ber_tag_t tag; tag = ber_scanf( ber, "{aeeiib{v}}", &dn, &scope, &deref, &size, &time, &attrsonly, &attrs ); if( tag == LBER_ERROR ) { /* error */ } else { /* success */ } ber_memfree( dn ); ber_memvfree( attrs ); .fi .SH ERRORS If an error occurs during decoding, generally these routines return LBER_ERROR ((ber_tag_t)\-1). .LP .SH NOTES .LP The return values for all of these functions are declared in the .B <lber.h> header file. Some routines may dynamically allocate memory which must be freed by the caller using supplied deallocation routines. .SH SEE ALSO .BR lber-encode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 358 stdin PK ��c\g�d"# "# man/man3/ldap_matchingrule2str.3nu �[��� .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin PK ��c\g�d"# "# man/man3/ldap_objectclass_free.3nu �[��� .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin PK ��c\��MK$ K$ man/man3/ber_put_ostring.3nu �[��� .lf 1 stdin .TH LBER_ENCODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_alloc_t, ber_flush, ber_flush2, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring, ber_put_string, ber_put_null, ber_put_boolean, ber_put_bitstring, ber_start_seq, ber_start_set, ber_put_seq, ber_put_set \- OpenLDAP LBER simplified Basic Encoding Rules library routines for encoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_flush2(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_printf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "int ber_put_int(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_enum(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_ostring(BerElement *" ber ", const char *" str ", ber_len_t " len ", ber_tag_t " tag ");" .LP .BI "int ber_put_string(BerElement *" ber ", const char *" str ", ber_tag_t " tag ");" .LP .BI "int ber_put_null(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_boolean(BerElement *" ber ", ber_int_t " bool ", ber_tag_t " tag ");" .LP .BI "int ber_put_bitstring(BerElement *" ber ", const char *" str ", ber_len_t " blen ", ber_tag_t " tag ");" .LP .BI "int ber_start_seq(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_start_set(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_seq(BerElement *" ber ");" .LP .BI "int ber_put_set(BerElement *" ber ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the encoding routines in the lber library. See .BR lber-decode (3) for details on the corresponding decoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_alloc_t () to allocate a BER element for encoding, .BR ber_printf () to do the actual encoding, and .BR ber_flush2 () to actually write the element. The other routines are provided for those applications that need more control than .BR ber_printf () provides. In general, these routines return the length of the element encoded, or \-1 if an error occurred. .LP The .BR ber_alloc_t () routine is used to allocate a new BER element. It should be called with an argument of LBER_USE_DER. .LP The .BR ber_flush2 () routine is used to actually write the element to a socket (or file) descriptor, once it has been fully encoded (using .BR ber_printf () and friends). See .BR lber-sockbuf (3) for more details on the Sockbuf implementation of the \fIsb\fP parameter. If the \fIfreeit\fP parameter is non-zero, the supplied \fIber\fP will be freed. If \fILBER_FLUSH_FREE_ON_SUCCESS\fP is used, the \fIber\fP is only freed when successfully flushed, otherwise it is left intact; if \fILBER_FLUSH_FREE_ON_ERROR\fP is used, the \fIber\fP is only freed when an error occurs, otherwise it is left intact; if \fILBER_FLUSH_FREE_ALWAYS\fP is used, the \fIber\fP is freed anyway. This function differs from the original .BR ber_flush (3) function, whose behavior corresponds to that indicated for \fILBER_FLUSH_FREE_ON_SUCCESS\fP. Note that in the future, the behavior of .BR ber_flush (3) with \fIfreeit\fP non-zero might change into that of .BR ber_flush2 (3) with \fIfreeit\fP set to \fILBER_FLUSH_FREE_ALWAYS\fP. .LP The .BR ber_printf () routine is used to encode a BER element in much the same way that .BR sprintf (3) works. One important difference, though, is that some state information is kept with the \fIber\fP parameter so that multiple calls can be made to .BR ber_printf () to append things to the end of the BER element. .BR Ber_printf () writes to \fIber\fP, a pointer to a BerElement such as returned by .BR ber_alloc_t (). It interprets and formats its arguments according to the format string \fIfmt\fP. The format string can contain the following characters: .RS .LP .TP 3 .B b Boolean. An ber_int_t parameter should be supplied. A boolean element is output. .TP .B e Enumeration. An ber_int_t parameter should be supplied. An enumeration element is output. .TP .B i Integer. An ber_int_t parameter should be supplied. An integer element is output. .TP .B B Bitstring. A char * pointer to the start of the bitstring is supplied, followed by the number of bits in the bitstring. A bitstring element is output. .TP .B n Null. No parameter is required. A null element is output. .TP .B o Octet string. A char * is supplied, followed by the length of the string pointed to. An octet string element is output. .TP .B O Octet string. A struct berval * is supplied. An octet string element is output. .TP .B s Octet string. A null-terminated string is supplied. An octet string element is output, not including the trailing NULL octet. .TP .B t Tag. A ber_tag_t specifying the tag to give the next element is provided. This works across calls. .TP .B v Several octet strings. A null-terminated array of char *'s is supplied. Note that a construct like '{v}' is required to get an actual SEQUENCE OF octet strings. .TP .B V Several octet strings. A null-terminated array of struct berval *'s is supplied. Note that a construct like '{V}' is required to get an actual SEQUENCE OF octet strings. .TP .B W Several octet strings. An array of struct berval's is supplied. The array is terminated by a struct berval with a NULL bv_val. Note that a construct like '{W}' is required to get an actual SEQUENCE OF octet strings. .TP .B { Begin sequence. No parameter is required. .TP .B } End sequence. No parameter is required. .TP .B [ Begin set. No parameter is required. .TP .B ] End set. No parameter is required. .RE .LP The .BR ber_put_int () routine writes the integer element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_enum () routine writes the enumeration element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_boolean () routine writes the boolean value given by \fIbool\fP to the BER element. .LP The .BR ber_put_bitstring () routine writes \fIblen\fP bits starting at \fIstr\fP as a bitstring value to the given BER element. Note that \fIblen\fP is the length \fIin bits\fP of the bitstring. .LP The .BR ber_put_ostring () routine writes \fIlen\fP bytes starting at \fIstr\fP to the BER element as an octet string. .LP The .BR ber_put_string () routine writes the null-terminated string (minus the terminating '\0') to the BER element as an octet string. .LP The .BR ber_put_null () routine writes a NULL element to the BER element. .LP The .BR ber_start_seq () routine is used to start a sequence in the BER element. The .BR ber_start_set () routine works similarly. The end of the sequence or set is marked by the nearest matching call to .BR ber_put_seq () or .BR ber_put_set (), respectively. .SH EXAMPLES Assuming the following variable declarations, and that the variables have been assigned appropriately, an lber encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP can be achieved like so: .LP .nf int rc; ber_int_t scope, ali, size, time, attrsonly; char *dn, **attrs; BerElement *ber; /* ... fill in values ... */ ber = ber_alloc_t( LBER_USE_DER ); if ( ber == NULL ) { /* error */ } rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali, size, time, attrsonly, attrs ); if( rc == \-1 ) { /* error */ } else { /* success */ } .fi .SH ERRORS If an error occurs during encoding, generally these routines return \-1. .LP .SH NOTES .LP The return values for all of these functions are declared in the <lber.h> header file. .SH SEE ALSO .BR lber-decode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 289 stdin PK ��c\OPh�� � man/man3/ldap_rename.3nu �[��� .lf 1 stdin .TH LDAP_RENAME 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_rename, ldap_rename_s \- Renames the specified entry. .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_rename( ld, dn, newrdn, newparent, deleteoldrdn, sctrls[], cctrls[], msgidp ); .ft LDAP *ld; const char *dn, *newrdn, *newparent; int deleteoldrdn; LDAPControl *sctrls[], *cctrls[]; int *msgidp); .LP .ft B int ldap_rename_s( ld, dn, newrdn, newparent, deleteoldrdn, sctrls[], cctrls[] ); .ft LDAP *ld; const char *dn, *newrdn, *newparent; int deleteoldrdn; LDAPControl *sctrls[], *cctrls[]; .SH DESCRIPTION These routines are used to perform a LDAP rename operation. The function changes the leaf component of an entry's distinguished name and optionally moves the entry to a new parent container. The .B ldap_rename_s performs a rename operation synchronously. The method takes \fIdn\fP, which points to the distinguished name of the entry whose attribute is being compared, \fInewparent\fP,the distinguished name of the entry's new parent. If this parameter is NULL, only the RDN is changed. The root DN is specified by passing a zero length string, "". \fIdeleteoldrdn\fP specifies whether the old RDN should be retained or deleted. Zero indicates that the old RDN should be retained. If you choose this option, the attribute will contain both names (the old and the new). Non-zero indicates that the old RDN should be deleted. \fIserverctrls\fP points to an array of LDAPControl structures that list the client controls to use with this extended operation. Use NULL to specify no client controls. \fIclientctrls\fP points to an array of LDAPControl structures that list the client controls to use with the search. .LP .B ldap_rename works just like .B ldap_rename_s, but the operation is asynchronous. It returns the message id of the request it initiated. The result of this operation can be obtained by calling .BR ldap_result(3). .SH ERRORS .B ldap_rename() returns \-1 in case of error initiating the request, and will set the \fIld_errno\fP field in the \fIld\fP parameter to indicate the error. .BR ldap_rename_s() returns the LDAP error code resulting from the rename operation. .SH SEE ALSO .BR ldap (3), .BR ldap_modify (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 67 stdin PK ��c\g�d"# "# " man/man3/ldap_attributetype_free.3nu �[��� .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin PK ��c\�� �. �. man/man3/ldap_set_rebind_proc.3nu �[��� .lf 1 stdin .TH LDAP_BIND 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_bind, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_sasl_bind, ldap_sasl_bind_s, ldap_sasl_interactive_bind_s, ldap_parse_sasl_bind_result, ldap_unbind, ldap_unbind_s, ldap_unbind_ext, ldap_unbind_ext_s, ldap_set_rebind_proc \- LDAP bind routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .BI "int ldap_bind(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_bind_s(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_simple_bind(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_simple_bind_s(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_sasl_bind(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], int *" msgidp ");" .RE .LP .BI "int ldap_sasl_bind_s(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], struct berval **" servercredp ");" .RE .LP .BI "int ldap_parse_sasl_bind_result(LDAP *" ld ", LDAPMessage *" res "," .RS .BI "struct berval **" servercredp ", int " freeit ");" .RE .LP .BI "int ldap_sasl_interactive_bind_s(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ");" .RE .LP .BI "int ldap_sasl_interactive_bind(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ", LDAPMessage *" result "," .BI "const char **" rmechp ", int *" msgidp ");" .RE .LP .BI "int (LDAP_SASL_INTERACT_PROC)(LDAP *" ld ", unsigned " flags ", void *" defaults ", void *" sasl_interact ");" .LP .BI "int ldap_unbind(LDAP *" ld ");" .LP .BI "int ldap_unbind_s(LDAP *" ld ");" .LP .BI "int ldap_unbind_ext(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_unbind_ext_s(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_set_rebind_proc (LDAP *" ld ", LDAP_REBIND_PROC *" ldap_proc ", void *" params ");" .LP .BI "int (LDAP_REBIND_PROC)(LDAP *" ld ", LDAP_CONST char *" url ", ber_tag_t " request ", ber_int_t " msgid ", void *" params ");" .SH DESCRIPTION .LP These routines provide various interfaces to the LDAP bind operation. After an association with an LDAP server is made using .BR ldap_init (3), an LDAP bind operation should be performed before other operations are attempted over the connection. An LDAP bind is required when using Version 2 of the LDAP protocol; it is optional for Version 3 but is usually needed due to security considerations. .LP There are three types of bind calls, ones providing simple authentication, ones providing SASL authentication, and general routines capable of doing either simple or SASL authentication. .LP .B SASL (Simple Authentication and Security Layer) can negotiate one of many different kinds of authentication. Both synchronous and asynchronous versions of each variant of the bind call are provided. All routines take \fIld\fP as their first parameter, as returned from .BR ldap_init (3). .SH SIMPLE AUTHENTICATION The simplest form of the bind call is .BR ldap_simple_bind_s() . It takes the DN to bind as in \fIwho\fP, and the userPassword associated with the entry in \fIpasswd\fP. It returns an LDAP error indication (see .BR ldap_error (3)). The .B ldap_simple_bind() call is asynchronous, taking the same parameters but only initiating the bind operation and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The .B ldap_sasl_bind_s() and asynchronous .B ldap_sasl_bind() functions can also be used to make a simple bind by using LDAP_SASL_SIMPLE as the SASL mechanism. .SH GENERAL AUTHENTICATION The .B ldap_bind() and .B ldap_bind_s() routines can be used when the authentication method to use needs to be selected at runtime. They both take an extra \fImethod\fP parameter selecting the authentication method to use. It should be set to LDAP_AUTH_SIMPLE to select simple authentication. .B ldap_bind() returns the message id of the request it initiates. .B ldap_bind_s() returns an LDAP error indication. .SH SASL AUTHENTICATION For SASL binds the server always ignores any provided DN, so the .I dn parameter should always be NULL. .BR ldap_sasl_bind_s () sends a single SASL bind request with the given SASL .I mechanism and credentials in the .I cred parameter. The format of the credentials depends on the particular SASL mechanism in use. For mechanisms that provide mutual authentication the server's credentials will be returned in the .I servercredp parameter. The routine returns an LDAP error indication (see .BR ldap_error (3)). The .BR ldap_sasl_bind () call is asynchronous, taking the same parameters but only sending the request and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The result must be additionally parsed by .BR ldap_parse_sasl_bind_result () to obtain any server credentials sent from the server. .LP Many SASL mechanisms require multiple message exchanges to perform a complete authentication. Applications should generally use .BR ldap_sasl_interactive_bind_s () rather than calling the basic .BR ldap_sasl_bind () functions directly. The .I mechs parameter should contain a space-separated list of candidate mechanisms to use. If this parameter is NULL or empty the library will query the supportedSASLMechanisms attribute from the server's rootDSE for the list of SASL mechanisms the server supports. The .I flags parameter controls the interaction used to retrieve any necessary SASL authentication parameters and should be one of: .TP LDAP_SASL_AUTOMATIC use defaults if available, prompt otherwise .TP LDAP_SASL_INTERACTIVE always prompt .TP LDAP_SASL_QUIET never prompt .LP The .I interact function uses the provided .I defaults to handle requests from the SASL library for particular authentication parameters. There is no defined format for the .I defaults information; it is up to the caller to use whatever format is appropriate for the supplied .I interact function. The .I sasl_interact parameter comes from the underlying SASL library. When used with Cyrus SASL this is an array of .B sasl_interact_t structures. The Cyrus SASL library will prompt for a variety of inputs, including: .TP SASL_CB_GETREALM the realm for the authentication attempt .TP SASL_CB_AUTHNAME the username to authenticate .TP SASL_CB_PASS the password for the provided username .TP SASL_CB_USER the username to use for proxy authorization .TP SASL_CB_NOECHOPROMPT generic prompt for input with input echoing disabled .TP SASL_CB_ECHOPROMPT generic prompt for input with input echoing enabled .TP SASL_CB_LIST_END indicates the end of the array of prompts .LP See the Cyrus SASL documentation for more details. .LP Applications which need to manage connections asynchronously may use .BR ldap_sasl_interactive_bind () instead of the synchronous version. A valid mechs parameter must be supplied, otherwise the library will be forced to query the server for a list of supported mechanisms, and this query will be performed synchronously. The other parameters are the same as for the synchronous function, with three additional parameters. The actual SASL mechanism that was used, and the message ID for use with .BR ldap_result () will be returned in rmechp and msgidp, respectively. The value in rmechp must not be modified by the caller and must be passed back on each subsequent call. The message obtained from .BR ldap_result () must be passed in the result parameter. This parameter must be NULL when initiating a new Bind. The caller must free the result message after each call using .BR ldap_msgfree (). The .BR ldap_sasl_interactive_bind () function returns an LDAP result code. If the code is LDAP_SASL_BIND_IN_PROGRESS then the Bind is not complete yet, and this function must be called again with the next result from the server. .SH REBINDING .LP The .B ldap_set_rebind_proc function() sets the process to use for binding when an operation returns a referral. This function is used when an application needs to bind to another server in order to follow a referral or search continuation reference. .LP The function takes \fIld\fP, the \fIrebind\fP function, and the \fIparams\fP, the arbitrary data like state information which the client might need to properly rebind. The LDAP_OPT_REFERRALS option in the \fIld\fP must be set to ON for the libraries to use the rebind function. Use the .BR ldap_set_option function to set the value. .LP The rebind function parameters are as follows: .LP The \fIld\fP parameter must be used by the application when binding to the referred server if the application wants the libraries to follow the referral. .LP The \fIurl\fP parameter points to the URL referral string received from the LDAP server. The LDAP application can use the .BR ldap_url_parse (3) function to parse the string into its components. .LP The \fIrequest\fP parameter specifies the type of request that generated the referral. .LP The \fImsgid\fP parameter specifies the message ID of the request generating the referral. .LP The \fIparams\fP parameter is the same value as passed originally to the .BR ldap_set_rebind_proc () function. .LP The LDAP libraries set all the parameters when they call the rebind function. The application should not attempt to free either the ld or the url structures in the rebind function. .LP The application must supply to the rebind function the required authentication information such as, user name, password, and certificates. The rebind function must use a synchronous bind method. .SH UNBINDING The .B ldap_unbind() call is used to unbind from the directory, terminate the current association, and free the resources contained in the \fIld\fP structure. Once it is called, the connection to the LDAP server is closed, and the \fIld\fP structure is invalid. The .B ldap_unbind_s() call is just another name for .BR ldap_unbind() ; both of these calls are synchronous in nature. .LP The .B ldap_unbind_ext() and .B ldap_unbind_ext_s() allows the operations to specify controls. .SH ERRORS Asynchronous routines will return \-1 in case of error, setting the \fIld_errno\fP parameter of the \fIld\fP structure. Synchronous routines return whatever \fIld_errno\fP is set to. See .BR ldap_error (3) for more information. .SH NOTES If an anonymous bind is sufficient for the application, the rebind process need not be provided. The LDAP libraries with the LDAP_OPT_REFERRALS option set to ON (default value) will automatically follow referrals using an anonymous bind. .LP If the application needs stronger authentication than an anonymous bind, you need to provide a rebind process for that authentication method. The bind method must be synchronous. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_open (3), .BR ldap_set_option (3), .BR ldap_url_parse (3) .B RFC 4422 (http://www.rfc-editor.org), .B Cyrus SASL (http://asg.web.cmu.edu/sasl/) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 335 stdin PK ��c\����� � man/man3/ldap_value_free_len.3nu �[��� .lf 1 stdin .TH LDAP_GET_VALUES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_values, ldap_get_values_len, ldap_count_values \- LDAP attribute value handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char **ldap_get_values(ld, entry, attr) .ft LDAP *ld; LDAPMessage *entry; char *attr; .LP .ft B struct berval **ldap_get_values_len(ld, entry, attr) .ft LDAP *ld; LDAPMessage *entry; char *attr; .LP .ft B int ldap_count_values(vals) .ft char **vals; .LP .ft B int ldap_count_values_len(vals) .ft struct berval **vals; .LP .ft B void ldap_value_free(vals) .ft char **vals; .LP .ft B void ldap_value_free_len(vals) .ft struct berval **vals; .SH DESCRIPTION These routines are used to retrieve and manipulate attribute values from an LDAP entry as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3). .B ldap_get_values() takes the \fIentry\fP and the attribute \fIattr\fP whose values are desired and returns a NULL-terminated array of the attribute's values. \fIattr\fP may be an attribute type as returned from .BR ldap_first_attribute (3) or .BR ldap_next_attribute (3), or if the attribute type is known it can simply be given. .LP The number of values in the array can be counted by calling .BR ldap_count_values() . The array of values returned can be freed by calling .BR ldap_value_free() . .LP If the attribute values are binary in nature, and thus not suitable to be returned as an array of char *'s, the .B ldap_get_values_len() routine can be used instead. It takes the same parameters as .BR ldap_get_values() , but returns a NULL-terminated array of pointers to berval structures, each containing the length of and a pointer to a value. .LP The number of values in the array can be counted by calling .BR ldap_count_values_len() . The array of values returned can be freed by calling .BR ldap_value_free_len() . .SH ERRORS If an error occurs in .B ldap_get_values() or .BR ldap_get_values_len() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .SH NOTES These routines dynamically allocate memory which the caller must free using the supplied routines. .SH SEE ALSO .BR ldap (3), .BR ldap_first_entry (3), .BR ldap_first_attribute (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 103 stdin PK ��c\��MK$ K$ man/man3/ber_printf.3nu �[��� .lf 1 stdin .TH LBER_ENCODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_alloc_t, ber_flush, ber_flush2, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring, ber_put_string, ber_put_null, ber_put_boolean, ber_put_bitstring, ber_start_seq, ber_start_set, ber_put_seq, ber_put_set \- OpenLDAP LBER simplified Basic Encoding Rules library routines for encoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_flush2(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_printf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "int ber_put_int(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_enum(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_ostring(BerElement *" ber ", const char *" str ", ber_len_t " len ", ber_tag_t " tag ");" .LP .BI "int ber_put_string(BerElement *" ber ", const char *" str ", ber_tag_t " tag ");" .LP .BI "int ber_put_null(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_boolean(BerElement *" ber ", ber_int_t " bool ", ber_tag_t " tag ");" .LP .BI "int ber_put_bitstring(BerElement *" ber ", const char *" str ", ber_len_t " blen ", ber_tag_t " tag ");" .LP .BI "int ber_start_seq(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_start_set(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_seq(BerElement *" ber ");" .LP .BI "int ber_put_set(BerElement *" ber ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the encoding routines in the lber library. See .BR lber-decode (3) for details on the corresponding decoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_alloc_t () to allocate a BER element for encoding, .BR ber_printf () to do the actual encoding, and .BR ber_flush2 () to actually write the element. The other routines are provided for those applications that need more control than .BR ber_printf () provides. In general, these routines return the length of the element encoded, or \-1 if an error occurred. .LP The .BR ber_alloc_t () routine is used to allocate a new BER element. It should be called with an argument of LBER_USE_DER. .LP The .BR ber_flush2 () routine is used to actually write the element to a socket (or file) descriptor, once it has been fully encoded (using .BR ber_printf () and friends). See .BR lber-sockbuf (3) for more details on the Sockbuf implementation of the \fIsb\fP parameter. If the \fIfreeit\fP parameter is non-zero, the supplied \fIber\fP will be freed. If \fILBER_FLUSH_FREE_ON_SUCCESS\fP is used, the \fIber\fP is only freed when successfully flushed, otherwise it is left intact; if \fILBER_FLUSH_FREE_ON_ERROR\fP is used, the \fIber\fP is only freed when an error occurs, otherwise it is left intact; if \fILBER_FLUSH_FREE_ALWAYS\fP is used, the \fIber\fP is freed anyway. This function differs from the original .BR ber_flush (3) function, whose behavior corresponds to that indicated for \fILBER_FLUSH_FREE_ON_SUCCESS\fP. Note that in the future, the behavior of .BR ber_flush (3) with \fIfreeit\fP non-zero might change into that of .BR ber_flush2 (3) with \fIfreeit\fP set to \fILBER_FLUSH_FREE_ALWAYS\fP. .LP The .BR ber_printf () routine is used to encode a BER element in much the same way that .BR sprintf (3) works. One important difference, though, is that some state information is kept with the \fIber\fP parameter so that multiple calls can be made to .BR ber_printf () to append things to the end of the BER element. .BR Ber_printf () writes to \fIber\fP, a pointer to a BerElement such as returned by .BR ber_alloc_t (). It interprets and formats its arguments according to the format string \fIfmt\fP. The format string can contain the following characters: .RS .LP .TP 3 .B b Boolean. An ber_int_t parameter should be supplied. A boolean element is output. .TP .B e Enumeration. An ber_int_t parameter should be supplied. An enumeration element is output. .TP .B i Integer. An ber_int_t parameter should be supplied. An integer element is output. .TP .B B Bitstring. A char * pointer to the start of the bitstring is supplied, followed by the number of bits in the bitstring. A bitstring element is output. .TP .B n Null. No parameter is required. A null element is output. .TP .B o Octet string. A char * is supplied, followed by the length of the string pointed to. An octet string element is output. .TP .B O Octet string. A struct berval * is supplied. An octet string element is output. .TP .B s Octet string. A null-terminated string is supplied. An octet string element is output, not including the trailing NULL octet. .TP .B t Tag. A ber_tag_t specifying the tag to give the next element is provided. This works across calls. .TP .B v Several octet strings. A null-terminated array of char *'s is supplied. Note that a construct like '{v}' is required to get an actual SEQUENCE OF octet strings. .TP .B V Several octet strings. A null-terminated array of struct berval *'s is supplied. Note that a construct like '{V}' is required to get an actual SEQUENCE OF octet strings. .TP .B W Several octet strings. An array of struct berval's is supplied. The array is terminated by a struct berval with a NULL bv_val. Note that a construct like '{W}' is required to get an actual SEQUENCE OF octet strings. .TP .B { Begin sequence. No parameter is required. .TP .B } End sequence. No parameter is required. .TP .B [ Begin set. No parameter is required. .TP .B ] End set. No parameter is required. .RE .LP The .BR ber_put_int () routine writes the integer element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_enum () routine writes the enumeration element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_boolean () routine writes the boolean value given by \fIbool\fP to the BER element. .LP The .BR ber_put_bitstring () routine writes \fIblen\fP bits starting at \fIstr\fP as a bitstring value to the given BER element. Note that \fIblen\fP is the length \fIin bits\fP of the bitstring. .LP The .BR ber_put_ostring () routine writes \fIlen\fP bytes starting at \fIstr\fP to the BER element as an octet string. .LP The .BR ber_put_string () routine writes the null-terminated string (minus the terminating '\0') to the BER element as an octet string. .LP The .BR ber_put_null () routine writes a NULL element to the BER element. .LP The .BR ber_start_seq () routine is used to start a sequence in the BER element. The .BR ber_start_set () routine works similarly. The end of the sequence or set is marked by the nearest matching call to .BR ber_put_seq () or .BR ber_put_set (), respectively. .SH EXAMPLES Assuming the following variable declarations, and that the variables have been assigned appropriately, an lber encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP can be achieved like so: .LP .nf int rc; ber_int_t scope, ali, size, time, attrsonly; char *dn, **attrs; BerElement *ber; /* ... fill in values ... */ ber = ber_alloc_t( LBER_USE_DER ); if ( ber == NULL ) { /* error */ } rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali, size, time, attrsonly, attrs ); if( rc == \-1 ) { /* error */ } else { /* success */ } .fi .SH ERRORS If an error occurs during encoding, generally these routines return \-1. .LP .SH NOTES .LP The return values for all of these functions are declared in the <lber.h> header file. .SH SEE ALSO .BR lber-decode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 289 stdin PK ��c\� �q q man/man3/ldap_dn2str.3nu �[��� .lf 1 stdin .TH LDAP_GET_DN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn \- LDAP DN handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ) .LP .ft B int ldap_str2dn( const char *str, LDAPDN *dn, unsigned flags ) .LP .ft B void ldap_dnfree( LDAPDN dn ) .LP .ft B int ldap_dn2str( LDAPDN dn, char **str, unsigned flags ) .LP .ft B char **ldap_explode_dn( const char *dn, int notypes ) .LP .ft B char **ldap_explode_rdn( const char *rdn, int notypes ) .LP .ft B char *ldap_dn2ufn( const char * dn ) .LP .ft B char *ldap_dn2dcedn( const char * dn ) .LP .ft B char *ldap_dcedn2dn( const char * dn ) .LP .ft B char *ldap_dn2ad_canonical( const char * dn ) .SH DESCRIPTION These routines allow LDAP entry names (Distinguished Names, or DNs) to be obtained, parsed, converted to a user-friendly form, and tested. A DN has the form described in RFC 4414 "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names". .LP The .B ldap_get_dn() routine takes an \fIentry\fP as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3) and returns a copy of the entry's DN. Space for the DN will be obtained dynamically and should be freed by the caller using .BR ldap_memfree (3). .LP .B ldap_str2dn() parses a string representation of a distinguished name contained in .B str into its components, which are stored in .B dn as .B ldap_ava structures, arranged in .B LDAPAVA, .B LDAPRDN, and .B LDAPDN terms. Space for .B dn will be obtained dynamically and should be freed by the caller using .BR ldap_dnfree (3). The .B LDAPDN is defined as: .nf .ft B typedef struct ldap_ava { struct berval la_attr; struct berval la_value; unsigned la_flags; } LDAPAVA; typedef LDAPAVA** LDAPRDN; typedef LDAPRDN* LDAPDN; .ft .fi The attribute types and the attribute values are not normalized. The .B la_flags can be either .B LDAP_AVA_STRING or .B LDAP_AVA_BINARY, the latter meaning that the value is BER/DER encoded and thus must be represented as, quoting from RFC 4514, " ... an octothorpe character ('#' ASCII 35) followed by the hexadecimal representation of each of the bytes of the BER encoding of the X.500 AttributeValue." The .B flags parameter to .B ldap_str2dn() can be .LP .nf LDAP_DN_FORMAT_LDAPV3 LDAP_DN_FORMAT_LDAPV2 LDAP_DN_FORMAT_DCE .fi which defines what DN syntax is expected (according to RFC 4514, RFC 1779 and DCE, respectively). The format can be \fIOR\fPed to the flags .LP .nf LDAP_DN_P_NO_SPACES LDAP_DN_P_NO_SPACE_AFTER_RDN ... LDAP_DN_PEDANTIC .fi The latter is a shortcut for all the previous limitations. .LP .B LDAP_DN_P_NO_SPACES does not allow extra spaces in the dn; the default is to silently eliminate spaces around AVA separators ('='), RDN component separators ('+' for LDAPv3/LDAPv2 or ',' for DCE) and RDN separators (',' LDAPv3/LDAPv2 or '/' for DCE). .LP .B LDAP_DN_P_NO_SPACE_AFTER_RDN does not allow a single space after RDN separators. .LP .B ldap_dn2str() performs the inverse operation, yielding in .B str a string representation of .B dn. It allows the same values for .B flags as .B ldap_str2dn(), plus .LP .nf LDAP_DN_FORMAT_UFN LDAP_DN_FORMAT_AD_CANONICAL .fi for user-friendly naming (RFC 1781) and AD canonical. .LP The following routines are viewed as deprecated in favor of .B ldap_str2dn() and .BR ldap_dn2str(). They are provided to support legacy applications. .LP The .B ldap_explode_dn() routine takes a DN as returned by .B ldap_get_dn() and breaks it up into its component parts. Each part is known as a Relative Distinguished Name, or RDN. .B ldap_explode_dn() returns a NULL-terminated array, each component of which contains an RDN from the DN. The \fInotypes\fP parameter is used to request that only the RDN values be returned, not their types. For example, the DN "cn=Bob, c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob", "US", NULL }, depending on whether notypes was 0 or 1, respectively. Assertion values in RDN strings may included escaped characters. The result can be freed by calling .BR ldap_value_free (3). .LP Similarly, the .B ldap_explode_rdn() routine takes an RDN as returned by .B ldap_explode_dn(dn,0) and breaks it up into its "type=value" component parts (or just "value", if the \fInotypes\fP parameter is set). Note the value is not unescaped. The result can be freed by calling .BR ldap_value_free (3). .LP .B ldap_dn2ufn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a more user-friendly form, stripping off all type names. See "Using the Directory to Achieve User Friendly Naming" (RFC 1781) for more details on the UFN format. Due to the ambiguous nature of the format, it is generally only used for display purposes. The space for the UFN returned is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .LP .B ldap_dn2dcedn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a DCE-style DN, e.g. a string with most-significant to least significant rdns separated by slashes ('/'); rdn components are separated by commas (','). Only printable chars (e.g. LDAPv2 printable string) are allowed, at least in this implementation. .B ldap_dcedn2dn() performs the opposite operation. .B ldap_dn2ad_canonical() turns a DN into a AD canonical name, which is basically a DCE dn with attribute types omitted. The trailing domain, if present, is turned in a DNS-like domain. The space for the returned value is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .SH ERRORS If an error occurs in .BR ldap_get_dn() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .BR ldap_explode_dn() , .BR ldap_explode_rdn() , .B ldap_dn2ufn(), .B ldap_dn2dcedn(), .B ldap_dcedn2dn(), and .B ldap_dn2ad_canonical() will return NULL with .BR errno (3) set appropriately in case of trouble. .SH NOTES These routines dynamically allocate memory that the caller must free. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_first_entry (3), .BR ldap_memfree (3), .BR ldap_value_free (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 247 stdin PK ��c\g�d"# "# ! man/man3/ldap_matchingrule_free.3nu �[��� .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin PK ��c\�� �. �. man/man3/ldap_sasl_bind_s.3nu �[��� .lf 1 stdin .TH LDAP_BIND 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_bind, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_sasl_bind, ldap_sasl_bind_s, ldap_sasl_interactive_bind_s, ldap_parse_sasl_bind_result, ldap_unbind, ldap_unbind_s, ldap_unbind_ext, ldap_unbind_ext_s, ldap_set_rebind_proc \- LDAP bind routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .BI "int ldap_bind(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_bind_s(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_simple_bind(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_simple_bind_s(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_sasl_bind(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], int *" msgidp ");" .RE .LP .BI "int ldap_sasl_bind_s(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], struct berval **" servercredp ");" .RE .LP .BI "int ldap_parse_sasl_bind_result(LDAP *" ld ", LDAPMessage *" res "," .RS .BI "struct berval **" servercredp ", int " freeit ");" .RE .LP .BI "int ldap_sasl_interactive_bind_s(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ");" .RE .LP .BI "int ldap_sasl_interactive_bind(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ", LDAPMessage *" result "," .BI "const char **" rmechp ", int *" msgidp ");" .RE .LP .BI "int (LDAP_SASL_INTERACT_PROC)(LDAP *" ld ", unsigned " flags ", void *" defaults ", void *" sasl_interact ");" .LP .BI "int ldap_unbind(LDAP *" ld ");" .LP .BI "int ldap_unbind_s(LDAP *" ld ");" .LP .BI "int ldap_unbind_ext(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_unbind_ext_s(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_set_rebind_proc (LDAP *" ld ", LDAP_REBIND_PROC *" ldap_proc ", void *" params ");" .LP .BI "int (LDAP_REBIND_PROC)(LDAP *" ld ", LDAP_CONST char *" url ", ber_tag_t " request ", ber_int_t " msgid ", void *" params ");" .SH DESCRIPTION .LP These routines provide various interfaces to the LDAP bind operation. After an association with an LDAP server is made using .BR ldap_init (3), an LDAP bind operation should be performed before other operations are attempted over the connection. An LDAP bind is required when using Version 2 of the LDAP protocol; it is optional for Version 3 but is usually needed due to security considerations. .LP There are three types of bind calls, ones providing simple authentication, ones providing SASL authentication, and general routines capable of doing either simple or SASL authentication. .LP .B SASL (Simple Authentication and Security Layer) can negotiate one of many different kinds of authentication. Both synchronous and asynchronous versions of each variant of the bind call are provided. All routines take \fIld\fP as their first parameter, as returned from .BR ldap_init (3). .SH SIMPLE AUTHENTICATION The simplest form of the bind call is .BR ldap_simple_bind_s() . It takes the DN to bind as in \fIwho\fP, and the userPassword associated with the entry in \fIpasswd\fP. It returns an LDAP error indication (see .BR ldap_error (3)). The .B ldap_simple_bind() call is asynchronous, taking the same parameters but only initiating the bind operation and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The .B ldap_sasl_bind_s() and asynchronous .B ldap_sasl_bind() functions can also be used to make a simple bind by using LDAP_SASL_SIMPLE as the SASL mechanism. .SH GENERAL AUTHENTICATION The .B ldap_bind() and .B ldap_bind_s() routines can be used when the authentication method to use needs to be selected at runtime. They both take an extra \fImethod\fP parameter selecting the authentication method to use. It should be set to LDAP_AUTH_SIMPLE to select simple authentication. .B ldap_bind() returns the message id of the request it initiates. .B ldap_bind_s() returns an LDAP error indication. .SH SASL AUTHENTICATION For SASL binds the server always ignores any provided DN, so the .I dn parameter should always be NULL. .BR ldap_sasl_bind_s () sends a single SASL bind request with the given SASL .I mechanism and credentials in the .I cred parameter. The format of the credentials depends on the particular SASL mechanism in use. For mechanisms that provide mutual authentication the server's credentials will be returned in the .I servercredp parameter. The routine returns an LDAP error indication (see .BR ldap_error (3)). The .BR ldap_sasl_bind () call is asynchronous, taking the same parameters but only sending the request and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The result must be additionally parsed by .BR ldap_parse_sasl_bind_result () to obtain any server credentials sent from the server. .LP Many SASL mechanisms require multiple message exchanges to perform a complete authentication. Applications should generally use .BR ldap_sasl_interactive_bind_s () rather than calling the basic .BR ldap_sasl_bind () functions directly. The .I mechs parameter should contain a space-separated list of candidate mechanisms to use. If this parameter is NULL or empty the library will query the supportedSASLMechanisms attribute from the server's rootDSE for the list of SASL mechanisms the server supports. The .I flags parameter controls the interaction used to retrieve any necessary SASL authentication parameters and should be one of: .TP LDAP_SASL_AUTOMATIC use defaults if available, prompt otherwise .TP LDAP_SASL_INTERACTIVE always prompt .TP LDAP_SASL_QUIET never prompt .LP The .I interact function uses the provided .I defaults to handle requests from the SASL library for particular authentication parameters. There is no defined format for the .I defaults information; it is up to the caller to use whatever format is appropriate for the supplied .I interact function. The .I sasl_interact parameter comes from the underlying SASL library. When used with Cyrus SASL this is an array of .B sasl_interact_t structures. The Cyrus SASL library will prompt for a variety of inputs, including: .TP SASL_CB_GETREALM the realm for the authentication attempt .TP SASL_CB_AUTHNAME the username to authenticate .TP SASL_CB_PASS the password for the provided username .TP SASL_CB_USER the username to use for proxy authorization .TP SASL_CB_NOECHOPROMPT generic prompt for input with input echoing disabled .TP SASL_CB_ECHOPROMPT generic prompt for input with input echoing enabled .TP SASL_CB_LIST_END indicates the end of the array of prompts .LP See the Cyrus SASL documentation for more details. .LP Applications which need to manage connections asynchronously may use .BR ldap_sasl_interactive_bind () instead of the synchronous version. A valid mechs parameter must be supplied, otherwise the library will be forced to query the server for a list of supported mechanisms, and this query will be performed synchronously. The other parameters are the same as for the synchronous function, with three additional parameters. The actual SASL mechanism that was used, and the message ID for use with .BR ldap_result () will be returned in rmechp and msgidp, respectively. The value in rmechp must not be modified by the caller and must be passed back on each subsequent call. The message obtained from .BR ldap_result () must be passed in the result parameter. This parameter must be NULL when initiating a new Bind. The caller must free the result message after each call using .BR ldap_msgfree (). The .BR ldap_sasl_interactive_bind () function returns an LDAP result code. If the code is LDAP_SASL_BIND_IN_PROGRESS then the Bind is not complete yet, and this function must be called again with the next result from the server. .SH REBINDING .LP The .B ldap_set_rebind_proc function() sets the process to use for binding when an operation returns a referral. This function is used when an application needs to bind to another server in order to follow a referral or search continuation reference. .LP The function takes \fIld\fP, the \fIrebind\fP function, and the \fIparams\fP, the arbitrary data like state information which the client might need to properly rebind. The LDAP_OPT_REFERRALS option in the \fIld\fP must be set to ON for the libraries to use the rebind function. Use the .BR ldap_set_option function to set the value. .LP The rebind function parameters are as follows: .LP The \fIld\fP parameter must be used by the application when binding to the referred server if the application wants the libraries to follow the referral. .LP The \fIurl\fP parameter points to the URL referral string received from the LDAP server. The LDAP application can use the .BR ldap_url_parse (3) function to parse the string into its components. .LP The \fIrequest\fP parameter specifies the type of request that generated the referral. .LP The \fImsgid\fP parameter specifies the message ID of the request generating the referral. .LP The \fIparams\fP parameter is the same value as passed originally to the .BR ldap_set_rebind_proc () function. .LP The LDAP libraries set all the parameters when they call the rebind function. The application should not attempt to free either the ld or the url structures in the rebind function. .LP The application must supply to the rebind function the required authentication information such as, user name, password, and certificates. The rebind function must use a synchronous bind method. .SH UNBINDING The .B ldap_unbind() call is used to unbind from the directory, terminate the current association, and free the resources contained in the \fIld\fP structure. Once it is called, the connection to the LDAP server is closed, and the \fIld\fP structure is invalid. The .B ldap_unbind_s() call is just another name for .BR ldap_unbind() ; both of these calls are synchronous in nature. .LP The .B ldap_unbind_ext() and .B ldap_unbind_ext_s() allows the operations to specify controls. .SH ERRORS Asynchronous routines will return \-1 in case of error, setting the \fIld_errno\fP parameter of the \fIld\fP structure. Synchronous routines return whatever \fIld_errno\fP is set to. See .BR ldap_error (3) for more information. .SH NOTES If an anonymous bind is sufficient for the application, the rebind process need not be provided. The LDAP libraries with the LDAP_OPT_REFERRALS option set to ON (default value) will automatically follow referrals using an anonymous bind. .LP If the application needs stronger authentication than an anonymous bind, you need to provide a rebind process for that authentication method. The bind method must be synchronous. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_open (3), .BR ldap_set_option (3), .BR ldap_url_parse (3) .B RFC 4422 (http://www.rfc-editor.org), .B Cyrus SASL (http://asg.web.cmu.edu/sasl/) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 335 stdin PK ��c\��n� � man/man3/ldap_open.3nu �[��� .lf 1 stdin .TH LDAP_OPEN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_init, ldap_initialize, ldap_open \- Initialize the LDAP library and open a connection to an LDAP server .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B LDAP *ldap_open(host, port) .ft char *host; int port; .LP .ft B LDAP *ldap_init(host, port) .ft char *host; int port; .LP .ft B int ldap_initialize(ldp, uri) .ft LDAP **ldp; char *uri; .LP .ft B int ldap_set_urllist_proc(ld, proc, params) .ft LDAP *ld; LDAP_URLLIST_PROC *proc; void *params; .LP .ft B int (LDAP_URLLIST_PROC)(ld, urllist, url, params); .ft LDAP *ld; LDAPURLDesc **urllist; LDAPURLDesc **url; void *params; .LP .ft B #include <ldap_pvt.h> .LP .ft B int ldap_init_fd(fd, proto, uri, ldp) .ft ber_socket_t fd; int proto; char *uri; LDAP **ldp; .SH DESCRIPTION .LP .B ldap_open() opens a connection to an LDAP server and allocates an LDAP structure which is used to identify the connection and to maintain per-connection information. .B ldap_init() allocates an LDAP structure but does not open an initial connection. .B ldap_initialize() allocates an LDAP structure but does not open an initial connection. .B ldap_init_fd() allocates an LDAP structure using an existing connection on the provided socket. One of these routines must be called before any operations are attempted. .LP .B ldap_open() takes \fIhost\fP, the hostname on which the LDAP server is running, and \fIport\fP, the port number to which to connect. If the default IANA-assigned port of 389 is desired, LDAP_PORT should be specified for \fIport\fP. The \fIhost\fP parameter may contain a blank-separated list of hosts to try to connect to, and each host may optionally by of the form \fIhost:port\fP. If present, the \fI:port\fP overrides the \fIport\fP parameter to .BR ldap_open() . Upon successfully making a connection to an LDAP server, .B ldap_open() returns a pointer to an opaque LDAP structure, which should be passed to subsequent calls to .BR ldap_bind() , .BR ldap_search() , etc. Certain fields in the LDAP structure can be set to indicate size limit, time limit, and how aliases are handled during operations; read and write access to those fields must occur by calling .BR ldap_get_option (3) and .BR ldap_set_option (3) respectively, whenever possible. .LP .B ldap_init() acts just like .BR ldap_open() , but does not open a connection to the LDAP server. The actual connection open will occur when the first operation is attempted. .LP .B ldap_initialize() acts like .BR ldap_init() , but it returns an integer indicating either success or the failure reason, and it allows to specify details for the connection in the schema portion of the URI. The .I uri parameter may be a comma- or whitespace-separated list of URIs containing only the .IR schema , the .IR host , and the .I port fields. Apart from .BR ldap , other (non-standard) recognized values of the .I schema field are .B ldaps (LDAP over TLS), .B ldapi (LDAP over IPC), and .B cldap (connectionless LDAP). If other fields are present, the behavior is undefined. .LP At this time, .B ldap_open() and .B ldap_init() are deprecated in favor of .BR ldap_initialize() , essentially because the latter allows to specify a schema in the URI and it explicitly returns an error code. .LP .B ldap_init_fd() allows an LDAP structure to be initialized using an already-opened connection. The .I proto parameter should be one of LDAP_PROTO_TCP, LDAP_PROTO_UDP, or LDAP_PROTO_IPC for a connection using TCP, UDP, or IPC, respectively. The value LDAP_PROTO_EXT may also be specified if user-supplied sockbuf handlers are going to be used. Note that support for UDP is not implemented unless libldap was built with LDAP_CONNECTIONLESS defined. The .I uri parameter may optionally be provided for informational purposes. .LP .B ldap_set_urllist_proc() allows to set a function .I proc of type .I LDAP_URLLIST_PROC that is called when a successful connection can be established. This function receives the list of URIs parsed from the .I uri string originally passed to .BR ldap_initialize() , and the one that successfully connected. The function may manipulate the URI list; the typical use consists in moving the successful URI to the head of the list, so that subsequent attempts to connect to one of the URIs using the same LDAP handle will try it first. If .I ld is null, .I proc is set as a global parameter that is inherited by all handlers within the process that are created after the call to .BR ldap_set_urllist_proc() . By default, no .I LDAP_URLLIST_PROC is set. In a multithreaded environment, .B ldap_set_urllist_proc() must be called before any concurrent operation using the LDAP handle is started. Note: the first call into the LDAP library also initializes the global options for the library. As such the first call should be single-threaded or otherwise protected to insure that only one call is active. It is recommended that .BR ldap_get_option () or .BR ldap_set_option () be used in the program's main thread before any additional threads are created. See .BR ldap_get_option (3). .SH ERRORS If an error occurs, .B ldap_open() and .B ldap_init() will return NULL and .I errno should be set appropriately. .B ldap_initialize() and .B ldap_init_fd() will directly return the LDAP code associated to the error (or .I LDAP_SUCCESS in case of success); .I errno should be set as well whenever appropriate. .B ldap_set_urllist_proc() returns LDAP_OPT_ERROR on error, and LDAP_OPT_SUCCESS on success. .SH SEE ALSO .BR ldap (3), .BR ldap_bind (3), .BR ldap_get_option (3), .BR ldap_set_option (3), .BR lber-sockbuf (3), .BR errno (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 226 stdin PK �c\�c%u u man/man3/ldap_search.3nu �[��� .lf 1 stdin .TH LDAP_SEARCH 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_search, ldap_search_s, ldap_search_st, ldap_search_ext, ldap_search_ext_s \- Perform an LDAP search operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <sys/types.h> #include <ldap.h> .LP .ft B int ldap_search_ext( .RS LDAP *\fIld\fB, char *\fIbase\fB, int \fIscope\fB, char *\fIfilter\fB, char *\fIattrs\fB[], int \fIattrsonly\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB, struct timeval *\fItimeout\fB, int \fIsizelimit\fB, int *\fImsgidp\fB ); .RE .LP .ft B int ldap_search_ext_s( .RS LDAP *\fIld\fB, char *\fIbase\fB, int \fIscope\fB, char *\fIfilter\fB, char *\fIattrs\fB[], int \fIattrsonly\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB, struct timeval *\fItimeout\fB, int \fIsizelimit\fB, LDAPMessage **\fIres\fB ); .RE .SH DESCRIPTION These routines are used to perform LDAP search operations. The .B ldap_search_ext_s() routine does the search synchronously (i.e., not returning until the operation completes), providing a pointer to the resulting LDAP messages at the location pointed to by the \fIres\fP parameter. .LP The .B ldap_search_ext() routine is the asynchronous version, initiating the search and returning the message id of the operation it initiated in the integer pointed to by the \fImsgidp\fP parameter. .LP The \fIbase\fP parameter is the DN of the entry at which to start the search. .LP The \fIscope\fP parameter is the scope of the search and should be one of LDAP_SCOPE_BASE, to search the object itself, LDAP_SCOPE_ONELEVEL, to search the object's immediate children, LDAP_SCOPE_SUBTREE, to search the object and all its descendants, or LDAP_SCOPE_CHILDREN, to search all of the descendants. Note that the latter requires the server support the LDAP Subordinates Search Scope extension. .LP The \fIfilter\fP is a string representation of the filter to apply in the search. The string should conform to the format specified in RFC 4515 as extended by RFC 4526. For instance, "(cn=Jane Doe)". Note that use of the extension requires the server to support the LDAP Absolute True/False Filter extension. NULL may be specified to indicate the library should send the filter (objectClass=*). .LP The \fIattrs\fP parameter is a null-terminated array of attribute descriptions to return from matching entries. If NULL is specified, the return of all user attributes is requested. The description "*" (LDAP_ALL_USER_ATTRIBUTES) may be used to request all user attributes to be returned. The description "+"(LDAP_ALL_OPERATIONAL_ATTRIBUTES) may be used to request all operational attributes to be returned. Note that this requires the server to support the LDAP All Operational Attribute extension. To request no attributes, the description "1.1" (LDAP_NO_ATTRS) should be listed by itself. .LP The \fIattrsonly\fP parameter should be set to a non-zero value if only attribute descriptions are wanted. It should be set to zero (0) if both attributes descriptions and attribute values are wanted. .LP The \fIserverctrls\fP and \fIclientctrls\fP parameters may be used to specify server and client controls, respectively. .LP The .B ldap_search_ext_s() routine is the synchronous version of .BR ldap_search_ext(). .LP It also returns a code indicating success or, in the case of failure, indicating the nature of the failure of the operation. See .BR ldap_error (3) for details. .SH NOTES Note that both read and list functionality are subsumed by these routines, by using a filter like "(objectclass=*)" and a scope of LDAP_SCOPE_BASE (to emulate read) or LDAP_SCOPE_ONELEVEL (to emulate list). .LP These routines may dynamically allocate memory. The caller is responsible for freeing such memory using supplied deallocation routines. Return values are contained in <ldap.h>. .LP Note that \fIres\fR parameter of .B ldap_search_ext_s() and .B ldap_search_s() should be freed with .B ldap_msgfree() regardless of return value of these functions. .SH DEPRECATED INTERFACES The .B ldap_search() routine is deprecated in favor of the .B ldap_search_ext() routine. The .B ldap_search_s() and .B ldap_search_st() routines are deprecated in favor of the .B ldap_search_ext_s() routine. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 139 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_result (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 145 stdin PK �c\�5^#v1 v1 man/man3/ber_get_stringb.3nu �[��� .lf 1 stdin .TH LBER_DECODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");" .LP .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");" .LP .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");" .LP .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");" .LP .BI "ber_tag_t ber_get_null(BerElement *" ber ");" .LP .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");" .LP .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");" .LP .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");" .LP .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the decoding routines in the lber library. See .BR lber-encode (3) for details on the corresponding encoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_get_next () to get the next BER element and .BR ber_scanf () to do the actual decoding. In some cases, .BR ber_peek_tag () may also need to be called in normal usage. The other routines are provided for those applications that need more control than .BR ber_scanf () provides. In general, these routines return the tag of the element decoded, or LBER_ERROR if an error occurred. .LP The .BR ber_get_next () routine is used to read the next BER element from the given Sockbuf, \fIsb\fP. It strips off and returns the leading tag, strips off and returns the length of the entire element in \fIlen\fP, and sets up \fIber\fP for subsequent calls to .BR ber_scanf () et al to decode the element. See .BR lber-sockbuf (3) for details of the Sockbuf implementation of the \fIsb\fP parameter. .LP The .BR ber_scanf () routine is used to decode a BER element in much the same way that .BR scanf (3) works. It reads from \fIber\fP, a pointer to a BerElement such as returned by .BR ber_get_next (), interprets the bytes according to the format string \fIfmt\fP, and stores the results in its additional arguments. 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. .RS .LP .TP 3 .B a Octet string. A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter. The caller should free the returned string using .BR ber_memfree (). .TP .B A Octet string. A variant of "\fBa\fP". A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter, unless a zero-length string would result; in that case, the arg is set to NULL. The caller should free the returned string using .BR ber_memfree (). .TP .B s Octet string. A char * buffer should be supplied, followed by a pointer to a ber_len_t initialized to the size of the buffer. Upon return, the null-terminated octet string is put into the buffer, and the ber_len_t is set to the actual size of the octet string. .TP .B O Octet string. A struct ber_val ** should be supplied, which upon return points to a dynamically allocated struct berval containing the octet string and its length. The caller should free the returned structure using .BR ber_bvfree (). .TP .B o Octet string. A struct ber_val * should be supplied, which upon return contains the dynamically allocated octet string and its length. The caller should free the returned octet string using .BR ber_memfree (). .TP .B m Octet string. A struct ber_val * should be supplied, which upon return contains the octet string and its length. The string resides in memory assigned to the BerElement, and must not be freed by the caller. .TP .B b Boolean. A pointer to a ber_int_t should be supplied. .TP .B e Enumeration. A pointer to a ber_int_t should be supplied. .TP .B i Integer. A pointer to a ber_int_t should be supplied. .TP .B B Bitstring. A char ** should be supplied which will point to the dynamically allocated bits, followed by a ber_len_t *, which will point to the length (in bits) of the bitstring returned. .TP .B n Null. No parameter is required. The element is simply skipped if it is recognized. .TP .B v Sequence of octet strings. A char *** should be supplied, which upon return points to a dynamically allocated null-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty. The caller should free the returned array and octet strings using .BR ber_memvfree (). .TP .B V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon return points to a dynamically allocated null-terminated array of struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvecfree (). .TP .B W Sequence of octet strings with lengths. A BerVarray * should be supplied, which upon return points to a dynamically allocated array of struct berval's containing the octet strings and their lengths. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvarray_free (). .TP .B M Sequence of octet strings with lengths. This is a generalized form of the previous three formats. A void ** (ptr) should be supplied, followed by a ber_len_t * (len) and a ber_len_t (off). Upon return (ptr) will point to a dynamically allocated array whose elements are all of size (*len). A struct berval will be filled starting at offset (off) in each element. The strings in each struct berval reside in memory assigned to the BerElement and must not be freed by the caller. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The number of elements in the array is also stored in (*len) on return. The caller should free the returned array using .BR ber_memfree (). .TP .B l Length of the next element. A pointer to a ber_len_t should be supplied. .TP .B t Tag of the next element. A pointer to a ber_tag_t should be supplied. .TP .B T Skip element and return its tag. A pointer to a ber_tag_t should be supplied. .TP .B x Skip element. The next element is skipped. .TP .B { Begin sequence. No parameter is required. The initial sequence tag and length are skipped. .TP .B } End sequence. No parameter is required and no action is taken. .TP .B [ Begin set. No parameter is required. The initial set tag and length are skipped. .TP .B ] End set. No parameter is required and no action is taken. .RE .LP The .BR ber_get_int () routine tries to interpret the next element as an integer, returning the result in \fInum\fP. The tag of whatever it finds is returned on success, LBER_ERROR (\-1) on failure. .LP The .BR ber_get_stringb () routine is used to read an octet string into a preallocated buffer. The \fIlen\fP parameter should be initialized to the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte. .LP The .BR ber_get_stringa () routine is used to dynamically allocate space into which an octet string is read. The caller should free the returned string using .BR ber_memfree(). .LP The .BR ber_get_stringal () routine is used to dynamically allocate space into which an octet string and its length are read. It takes a struct berval **, and returns the result in this parameter. The caller should free the returned structure using .BR ber_bvfree(). .LP The .BR ber_get_stringbv () routine is used to read an octet string and its length into the provided struct berval *. If the \fIalloc\fP parameter is zero, the string will reside in memory assigned to the BerElement, and must not be freed by the caller. If the \fIalloc\fP parameter is non-zero, the string will be copied into dynamically allocated space which should be returned using .BR ber_memfree (). .LP The .BR ber_get_null () routine is used to read a NULL element. It returns the tag of the element it skips over. .LP The .BR ber_get_boolean () routine is used to read a boolean value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_enum () routine is used to read a enumeration value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_bitstringa () routine is used to read a bitstring value. It takes a char ** which will hold the dynamically allocated bits, followed by an ber_len_t *, which will point to the length (in bits) of the bitstring returned. The caller should free the returned string using .BR ber_memfree (). .LP The .BR ber_first_element () routine is used to return the tag and length of the first element in a set or sequence. It also returns in \fIcookie\fP a magic cookie parameter that should be passed to subsequent calls to ber_next_element(), which returns similar information. .SH EXAMPLES Assume the variable \fIber\fP contains a lightweight BER encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP The element can be decoded using .BR ber_scanf () as follows. .LP .nf ber_int_t scope, deref, size, time, attrsonly; char *dn, **attrs; ber_tag_t tag; tag = ber_scanf( ber, "{aeeiib{v}}", &dn, &scope, &deref, &size, &time, &attrsonly, &attrs ); if( tag == LBER_ERROR ) { /* error */ } else { /* success */ } ber_memfree( dn ); ber_memvfree( attrs ); .fi .SH ERRORS If an error occurs during decoding, generally these routines return LBER_ERROR ((ber_tag_t)\-1). .LP .SH NOTES .LP The return values for all of these functions are declared in the .B <lber.h> header file. Some routines may dynamically allocate memory which must be freed by the caller using supplied deallocation routines. .SH SEE ALSO .BR lber-encode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 358 stdin PK �c\��n� � man/man3/ldap_set_urllist_proc.3nu �[��� .lf 1 stdin .TH LDAP_OPEN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_init, ldap_initialize, ldap_open \- Initialize the LDAP library and open a connection to an LDAP server .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B LDAP *ldap_open(host, port) .ft char *host; int port; .LP .ft B LDAP *ldap_init(host, port) .ft char *host; int port; .LP .ft B int ldap_initialize(ldp, uri) .ft LDAP **ldp; char *uri; .LP .ft B int ldap_set_urllist_proc(ld, proc, params) .ft LDAP *ld; LDAP_URLLIST_PROC *proc; void *params; .LP .ft B int (LDAP_URLLIST_PROC)(ld, urllist, url, params); .ft LDAP *ld; LDAPURLDesc **urllist; LDAPURLDesc **url; void *params; .LP .ft B #include <ldap_pvt.h> .LP .ft B int ldap_init_fd(fd, proto, uri, ldp) .ft ber_socket_t fd; int proto; char *uri; LDAP **ldp; .SH DESCRIPTION .LP .B ldap_open() opens a connection to an LDAP server and allocates an LDAP structure which is used to identify the connection and to maintain per-connection information. .B ldap_init() allocates an LDAP structure but does not open an initial connection. .B ldap_initialize() allocates an LDAP structure but does not open an initial connection. .B ldap_init_fd() allocates an LDAP structure using an existing connection on the provided socket. One of these routines must be called before any operations are attempted. .LP .B ldap_open() takes \fIhost\fP, the hostname on which the LDAP server is running, and \fIport\fP, the port number to which to connect. If the default IANA-assigned port of 389 is desired, LDAP_PORT should be specified for \fIport\fP. The \fIhost\fP parameter may contain a blank-separated list of hosts to try to connect to, and each host may optionally by of the form \fIhost:port\fP. If present, the \fI:port\fP overrides the \fIport\fP parameter to .BR ldap_open() . Upon successfully making a connection to an LDAP server, .B ldap_open() returns a pointer to an opaque LDAP structure, which should be passed to subsequent calls to .BR ldap_bind() , .BR ldap_search() , etc. Certain fields in the LDAP structure can be set to indicate size limit, time limit, and how aliases are handled during operations; read and write access to those fields must occur by calling .BR ldap_get_option (3) and .BR ldap_set_option (3) respectively, whenever possible. .LP .B ldap_init() acts just like .BR ldap_open() , but does not open a connection to the LDAP server. The actual connection open will occur when the first operation is attempted. .LP .B ldap_initialize() acts like .BR ldap_init() , but it returns an integer indicating either success or the failure reason, and it allows to specify details for the connection in the schema portion of the URI. The .I uri parameter may be a comma- or whitespace-separated list of URIs containing only the .IR schema , the .IR host , and the .I port fields. Apart from .BR ldap , other (non-standard) recognized values of the .I schema field are .B ldaps (LDAP over TLS), .B ldapi (LDAP over IPC), and .B cldap (connectionless LDAP). If other fields are present, the behavior is undefined. .LP At this time, .B ldap_open() and .B ldap_init() are deprecated in favor of .BR ldap_initialize() , essentially because the latter allows to specify a schema in the URI and it explicitly returns an error code. .LP .B ldap_init_fd() allows an LDAP structure to be initialized using an already-opened connection. The .I proto parameter should be one of LDAP_PROTO_TCP, LDAP_PROTO_UDP, or LDAP_PROTO_IPC for a connection using TCP, UDP, or IPC, respectively. The value LDAP_PROTO_EXT may also be specified if user-supplied sockbuf handlers are going to be used. Note that support for UDP is not implemented unless libldap was built with LDAP_CONNECTIONLESS defined. The .I uri parameter may optionally be provided for informational purposes. .LP .B ldap_set_urllist_proc() allows to set a function .I proc of type .I LDAP_URLLIST_PROC that is called when a successful connection can be established. This function receives the list of URIs parsed from the .I uri string originally passed to .BR ldap_initialize() , and the one that successfully connected. The function may manipulate the URI list; the typical use consists in moving the successful URI to the head of the list, so that subsequent attempts to connect to one of the URIs using the same LDAP handle will try it first. If .I ld is null, .I proc is set as a global parameter that is inherited by all handlers within the process that are created after the call to .BR ldap_set_urllist_proc() . By default, no .I LDAP_URLLIST_PROC is set. In a multithreaded environment, .B ldap_set_urllist_proc() must be called before any concurrent operation using the LDAP handle is started. Note: the first call into the LDAP library also initializes the global options for the library. As such the first call should be single-threaded or otherwise protected to insure that only one call is active. It is recommended that .BR ldap_get_option () or .BR ldap_set_option () be used in the program's main thread before any additional threads are created. See .BR ldap_get_option (3). .SH ERRORS If an error occurs, .B ldap_open() and .B ldap_init() will return NULL and .I errno should be set appropriately. .B ldap_initialize() and .B ldap_init_fd() will directly return the LDAP code associated to the error (or .I LDAP_SUCCESS in case of success); .I errno should be set as well whenever appropriate. .B ldap_set_urllist_proc() returns LDAP_OPT_ERROR on error, and LDAP_OPT_SUCCESS on success. .SH SEE ALSO .BR ldap (3), .BR ldap_bind (3), .BR ldap_get_option (3), .BR ldap_set_option (3), .BR lber-sockbuf (3), .BR errno (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 226 stdin PK �c\ m�&$ $ man/man3/ldap_perror.3nu �[��� .lf 1 stdin .TH LDAP_ERROR 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_perror, ld_errno, ldap_result2error, ldap_errlist, ldap_err2string \- LDAP protocol error handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_err2string( int \fIerr\fB ); .SH DESCRIPTION The .B ldap_err2string() routine provides short description of the various codes returned by routines in this library. The returned string is a pointer to a static area that should not be modified. These codes are either negative, indicating an API error code; positive, indicating an LDAP resultCode other than \'success' (0), or - zero, indicating both successful use of the API and the LDAP resultCode \'success' (0). The code associated with an LDAP session is accessible using .BR ldap_get_option (3) and .BR ldap_set_option (3) with the .B LDAP_OPT_RESULT_CODE option (previously called .BR LDAP_OPT_ERROR_NUMBER ). .SH PROTOCOL RESULT CODES This section provides a partial list of protocol codes recognized by the library. As LDAP is extensible, additional values may be returned. A complete listing of \fIregistered\fP LDAP result codes can be obtained from the \fIInternet Assigned Numbers Authority\fP <http://www.iana.org>. .LP .TP 20 .SM LDAP_SUCCESS The request was successful. .TP .SM LDAP_OPERATIONS_ERROR An operations error occurred. .TP .SM LDAP_PROTOCOL_ERROR A protocol violation was detected. .TP .SM LDAP_TIMELIMIT_EXCEEDED An LDAP time limit was exceeded. .TP .SM LDAP_SIZELIMIT_EXCEEDED An LDAP size limit was exceeded. .TP .SM LDAP_COMPARE_FALSE A compare operation returned false. .TP .SM LDAP_COMPARE_TRUE A compare operation returned true. .TP .SM LDAP_STRONG_AUTH_NOT_SUPPORTED The LDAP server does not support strong authentication. .TP .SM LDAP_STRONG_AUTH_REQUIRED Strong authentication is required for the operation. .TP .SM LDAP_PARTIAL_RESULTS Partial results only returned. .TP .SM LDAP_NO_SUCH_ATTRIBUTE The attribute type specified does not exist in the entry. .TP .SM LDAP_UNDEFINED_TYPE The attribute type specified is invalid. .TP .SM LDAP_INAPPROPRIATE_MATCHING Filter type not supported for the specified attribute. .TP .SM LDAP_CONSTRAINT_VIOLATION An attribute value specified violates some constraint (e.g., a postalAddress has too many lines, or a line that is too long). .TP .SM LDAP_TYPE_OR_VALUE_EXISTS An attribute type or attribute value specified already exists in the entry. .TP .SM LDAP_INVALID_SYNTAX An invalid attribute value was specified. .TP .SM LDAP_NO_SUCH_OBJECT The specified object does not exist in The Directory. .TP .SM LDAP_ALIAS_PROBLEM An alias in The Directory points to a nonexistent entry. .TP .SM LDAP_INVALID_DN_SYNTAX A syntactically invalid DN was specified. .TP .SM LDAP_IS_LEAF The object specified is a leaf. .TP .SM LDAP_ALIAS_DEREF_PROBLEM A problem was encountered when dereferencing an alias. .TP .SM LDAP_INAPPROPRIATE_AUTH Inappropriate authentication was specified (e.g., LDAP_AUTH_SIMPLE was specified and the entry does not have a userPassword attribute). .TP .SM LDAP_INVALID_CREDENTIALS Invalid credentials were presented (e.g., the wrong password). .TP .SM LDAP_INSUFFICIENT_ACCESS The user has insufficient access to perform the operation. .TP .SM LDAP_BUSY The DSA is busy. .TP .SM LDAP_UNAVAILABLE The DSA is unavailable. .TP .SM LDAP_UNWILLING_TO_PERFORM The DSA is unwilling to perform the operation. .TP .SM LDAP_LOOP_DETECT A loop was detected. .TP .SM LDAP_NAMING_VIOLATION A naming violation occurred. .TP .SM LDAP_OBJECT_CLASS_VIOLATION An object class violation occurred (e.g., a "must" attribute was missing from the entry). .TP .SM LDAP_NOT_ALLOWED_ON_NONLEAF The operation is not allowed on a nonleaf object. .TP .SM LDAP_NOT_ALLOWED_ON_RDN The operation is not allowed on an RDN. .TP .SM LDAP_ALREADY_EXISTS The entry already exists. .TP .SM LDAP_NO_OBJECT_CLASS_MODS Object class modifications are not allowed. .TP .SM LDAP_OTHER An unknown error occurred. .SH API ERROR CODES This section provides a complete list of API error codes recognized by the library. Note that LDAP_SUCCESS indicates success of an API call in addition to representing the return of the LDAP \'success' resultCode. .LP .TP 20 .SM LDAP_SERVER_DOWN The LDAP library can't contact the LDAP server. .TP .SM LDAP_LOCAL_ERROR Some local error occurred. This is usually a failed dynamic memory allocation. .TP .SM LDAP_ENCODING_ERROR An error was encountered encoding parameters to send to the LDAP server. .TP .SM LDAP_DECODING_ERROR An error was encountered decoding a result from the LDAP server. .TP .SM LDAP_TIMEOUT A timelimit was exceeded while waiting for a result. .TP .SM LDAP_AUTH_UNKNOWN The authentication method specified to ldap_bind() is not known. .TP .SM LDAP_FILTER_ERROR An invalid filter was supplied to ldap_search() (e.g., unbalanced parentheses). .TP .SM LDAP_PARAM_ERROR An ldap routine was called with a bad parameter. .TP .SM LDAP_NO_MEMORY An memory allocation (e.g., malloc(3) or other dynamic memory allocator) call failed in an ldap library routine. .TP .SM LDAP_USER_CANCELED Indicates the user cancelled the operation. .TP .SM LDAP_CONNECT_ERROR Indicates a connection problem. .TP .SM LDAP_NOT_SUPPORTED Indicates the routine was called in a manner not supported by the library. .TP .SM LDAP_CONTROL_NOT_FOUND Indicates the control provided is unknown to the client library. .TP .SM LDAP_NO_RESULTS_RETURNED Indicates no results returned. .TP .SM LDAP_MORE_RESULTS_TO_RETURN Indicates more results could be returned. .TP .SM LDAP_CLIENT_LOOP Indicates the library has detected a loop in its processing. .TP .SM LDAP_REFERRAL_LIMIT_EXCEEDED Indicates the referral limit has been exceeded. .SH DEPRECATED .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 220 stdin .SH SEE ALSO .BR ldap (3), .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 225 stdin PK �c\'�t!� � man/man3/ldap_start_tls_s.3nu �[��� .lf 1 stdin .TH LDAP_TLS 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_start_tls, ldap_start_tls_s, ldap_tls_inplace, ldap_install_tls \- LDAP TLS initialization routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "int ldap_start_tls(LDAP *" ld ");" .LP .BI "int ldap_start_tls_s(LDAP *" ld ", LDAPControl **" serverctrls ", LDAPControl **" clientctrls ");" .LP .BI "int ldap_tls_inplace(LDAP *" ld ");" .LP .BI "int ldap_install_tls(LDAP *" ld ");" .SH DESCRIPTION These routines are used to initiate TLS processing on an LDAP session. .BR ldap_start_tls_s () sends a StartTLS request to a server, waits for the reply, and then installs TLS handlers on the session if the request succeeded. The routine returns .B LDAP_SUCCESS if everything succeeded, otherwise it returns an LDAP error code. .BR ldap_start_tls () sends a StartTLS request to a server and does nothing else. It returns .B LDAP_SUCCESS if the request was sent successfully. .BR ldap_tls_inplace () returns 1 if TLS handlers have been installed on the specified session, 0 otherwise. .BR ldap_install_tls () installs the TLS handlers on the given session. It returns .B LDAP_LOCAL_ERROR if TLS is already installed. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 42 stdin PK �c\ m�&$ $ man/man3/ldap_error.3nu �[��� .lf 1 stdin .TH LDAP_ERROR 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_perror, ld_errno, ldap_result2error, ldap_errlist, ldap_err2string \- LDAP protocol error handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_err2string( int \fIerr\fB ); .SH DESCRIPTION The .B ldap_err2string() routine provides short description of the various codes returned by routines in this library. The returned string is a pointer to a static area that should not be modified. These codes are either negative, indicating an API error code; positive, indicating an LDAP resultCode other than \'success' (0), or - zero, indicating both successful use of the API and the LDAP resultCode \'success' (0). The code associated with an LDAP session is accessible using .BR ldap_get_option (3) and .BR ldap_set_option (3) with the .B LDAP_OPT_RESULT_CODE option (previously called .BR LDAP_OPT_ERROR_NUMBER ). .SH PROTOCOL RESULT CODES This section provides a partial list of protocol codes recognized by the library. As LDAP is extensible, additional values may be returned. A complete listing of \fIregistered\fP LDAP result codes can be obtained from the \fIInternet Assigned Numbers Authority\fP <http://www.iana.org>. .LP .TP 20 .SM LDAP_SUCCESS The request was successful. .TP .SM LDAP_OPERATIONS_ERROR An operations error occurred. .TP .SM LDAP_PROTOCOL_ERROR A protocol violation was detected. .TP .SM LDAP_TIMELIMIT_EXCEEDED An LDAP time limit was exceeded. .TP .SM LDAP_SIZELIMIT_EXCEEDED An LDAP size limit was exceeded. .TP .SM LDAP_COMPARE_FALSE A compare operation returned false. .TP .SM LDAP_COMPARE_TRUE A compare operation returned true. .TP .SM LDAP_STRONG_AUTH_NOT_SUPPORTED The LDAP server does not support strong authentication. .TP .SM LDAP_STRONG_AUTH_REQUIRED Strong authentication is required for the operation. .TP .SM LDAP_PARTIAL_RESULTS Partial results only returned. .TP .SM LDAP_NO_SUCH_ATTRIBUTE The attribute type specified does not exist in the entry. .TP .SM LDAP_UNDEFINED_TYPE The attribute type specified is invalid. .TP .SM LDAP_INAPPROPRIATE_MATCHING Filter type not supported for the specified attribute. .TP .SM LDAP_CONSTRAINT_VIOLATION An attribute value specified violates some constraint (e.g., a postalAddress has too many lines, or a line that is too long). .TP .SM LDAP_TYPE_OR_VALUE_EXISTS An attribute type or attribute value specified already exists in the entry. .TP .SM LDAP_INVALID_SYNTAX An invalid attribute value was specified. .TP .SM LDAP_NO_SUCH_OBJECT The specified object does not exist in The Directory. .TP .SM LDAP_ALIAS_PROBLEM An alias in The Directory points to a nonexistent entry. .TP .SM LDAP_INVALID_DN_SYNTAX A syntactically invalid DN was specified. .TP .SM LDAP_IS_LEAF The object specified is a leaf. .TP .SM LDAP_ALIAS_DEREF_PROBLEM A problem was encountered when dereferencing an alias. .TP .SM LDAP_INAPPROPRIATE_AUTH Inappropriate authentication was specified (e.g., LDAP_AUTH_SIMPLE was specified and the entry does not have a userPassword attribute). .TP .SM LDAP_INVALID_CREDENTIALS Invalid credentials were presented (e.g., the wrong password). .TP .SM LDAP_INSUFFICIENT_ACCESS The user has insufficient access to perform the operation. .TP .SM LDAP_BUSY The DSA is busy. .TP .SM LDAP_UNAVAILABLE The DSA is unavailable. .TP .SM LDAP_UNWILLING_TO_PERFORM The DSA is unwilling to perform the operation. .TP .SM LDAP_LOOP_DETECT A loop was detected. .TP .SM LDAP_NAMING_VIOLATION A naming violation occurred. .TP .SM LDAP_OBJECT_CLASS_VIOLATION An object class violation occurred (e.g., a "must" attribute was missing from the entry). .TP .SM LDAP_NOT_ALLOWED_ON_NONLEAF The operation is not allowed on a nonleaf object. .TP .SM LDAP_NOT_ALLOWED_ON_RDN The operation is not allowed on an RDN. .TP .SM LDAP_ALREADY_EXISTS The entry already exists. .TP .SM LDAP_NO_OBJECT_CLASS_MODS Object class modifications are not allowed. .TP .SM LDAP_OTHER An unknown error occurred. .SH API ERROR CODES This section provides a complete list of API error codes recognized by the library. Note that LDAP_SUCCESS indicates success of an API call in addition to representing the return of the LDAP \'success' resultCode. .LP .TP 20 .SM LDAP_SERVER_DOWN The LDAP library can't contact the LDAP server. .TP .SM LDAP_LOCAL_ERROR Some local error occurred. This is usually a failed dynamic memory allocation. .TP .SM LDAP_ENCODING_ERROR An error was encountered encoding parameters to send to the LDAP server. .TP .SM LDAP_DECODING_ERROR An error was encountered decoding a result from the LDAP server. .TP .SM LDAP_TIMEOUT A timelimit was exceeded while waiting for a result. .TP .SM LDAP_AUTH_UNKNOWN The authentication method specified to ldap_bind() is not known. .TP .SM LDAP_FILTER_ERROR An invalid filter was supplied to ldap_search() (e.g., unbalanced parentheses). .TP .SM LDAP_PARAM_ERROR An ldap routine was called with a bad parameter. .TP .SM LDAP_NO_MEMORY An memory allocation (e.g., malloc(3) or other dynamic memory allocator) call failed in an ldap library routine. .TP .SM LDAP_USER_CANCELED Indicates the user cancelled the operation. .TP .SM LDAP_CONNECT_ERROR Indicates a connection problem. .TP .SM LDAP_NOT_SUPPORTED Indicates the routine was called in a manner not supported by the library. .TP .SM LDAP_CONTROL_NOT_FOUND Indicates the control provided is unknown to the client library. .TP .SM LDAP_NO_RESULTS_RETURNED Indicates no results returned. .TP .SM LDAP_MORE_RESULTS_TO_RETURN Indicates more results could be returned. .TP .SM LDAP_CLIENT_LOOP Indicates the library has detected a loop in its processing. .TP .SM LDAP_REFERRAL_LIMIT_EXCEEDED Indicates the referral limit has been exceeded. .SH DEPRECATED .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 220 stdin .SH SEE ALSO .BR ldap (3), .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 225 stdin PK �c\����� � man/man3/ldap_value_free.3nu �[��� .lf 1 stdin .TH LDAP_GET_VALUES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_values, ldap_get_values_len, ldap_count_values \- LDAP attribute value handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char **ldap_get_values(ld, entry, attr) .ft LDAP *ld; LDAPMessage *entry; char *attr; .LP .ft B struct berval **ldap_get_values_len(ld, entry, attr) .ft LDAP *ld; LDAPMessage *entry; char *attr; .LP .ft B int ldap_count_values(vals) .ft char **vals; .LP .ft B int ldap_count_values_len(vals) .ft struct berval **vals; .LP .ft B void ldap_value_free(vals) .ft char **vals; .LP .ft B void ldap_value_free_len(vals) .ft struct berval **vals; .SH DESCRIPTION These routines are used to retrieve and manipulate attribute values from an LDAP entry as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3). .B ldap_get_values() takes the \fIentry\fP and the attribute \fIattr\fP whose values are desired and returns a NULL-terminated array of the attribute's values. \fIattr\fP may be an attribute type as returned from .BR ldap_first_attribute (3) or .BR ldap_next_attribute (3), or if the attribute type is known it can simply be given. .LP The number of values in the array can be counted by calling .BR ldap_count_values() . The array of values returned can be freed by calling .BR ldap_value_free() . .LP If the attribute values are binary in nature, and thus not suitable to be returned as an array of char *'s, the .B ldap_get_values_len() routine can be used instead. It takes the same parameters as .BR ldap_get_values() , but returns a NULL-terminated array of pointers to berval structures, each containing the length of and a pointer to a value. .LP The number of values in the array can be counted by calling .BR ldap_count_values_len() . The array of values returned can be freed by calling .BR ldap_value_free_len() . .SH ERRORS If an error occurs in .B ldap_get_values() or .BR ldap_get_values_len() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .SH NOTES These routines dynamically allocate memory which the caller must free using the supplied routines. .SH SEE ALSO .BR ldap (3), .BR ldap_first_entry (3), .BR ldap_first_attribute (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 103 stdin PK �c\�շY� � man/man3/ber_bvecfree.3nu �[��� .lf 1 stdin .TH LBER_TYPES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_int_t, ber_uint_t, ber_len_t, ber_slen_t, ber_tag_t, struct berval, BerValue, BerVarray, BerElement, ber_bvfree, ber_bvecfree, ber_bvecadd, ber_bvarray_free, ber_bvarray_add, ber_bvdup, ber_dupbv, ber_bvstr, ber_bvstrdup, ber_str2bv, ber_alloc_t, ber_init, ber_init2, ber_free \- OpenLDAP LBER types and allocation functions .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .nf .ft B typedef impl_tag_t ber_tag_t; typedef impl_int_t ber_int_t; typedef impl_uint_t ber_uint_t; typedef impl_len_t ber_len_t; typedef impl_slen_t ber_slen_t; typedef struct berval { ber_len_t bv_len; char *bv_val; } BerValue, *BerVarray; typedef struct berelement BerElement; .ft .fi .LP .BI "void ber_bvfree(struct berval *" bv ");" .LP .BI "void ber_bvecfree(struct berval **" bvec ");" .LP .BI "void ber_bvecadd(struct berval ***" bvec ", struct berval *" bv ");" .LP .BI "void ber_bvarray_free(struct berval *" bvarray ");" .LP .BI "void ber_bvarray_add(BerVarray *" bvarray ", BerValue *" bv ");" .LP .BI "struct berval *ber_bvdup(const struct berval *" bv ");" .LP .BI "struct berval *ber_dupbv(const struct berval *" dst ", struct berval *" src ");" .LP .BI "struct berval *ber_bvstr(const char *" str ");" .LP .BI "struct berval *ber_bvstrdup(const char *" str ");" .LP .BI "struct berval *ber_str2bv(const char *" str ", ber_len_t " len ", int " dup ", struct berval *" bv ");" .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "BerElement *ber_init(struct berval *" bv ");" .LP .BI "void ber_init2(BerElement *" ber ", struct berval *" bv ", int " options ");" .LP .BI "void ber_free(BerElement *" ber ", int " freebuf ");" .SH DESCRIPTION .LP The following are the basic types and structures defined for use with the Lightweight BER library. .LP .B ber_int_t is a signed integer of at least 32 bits. It is commonly equivalent to .BR int . .B ber_uint_t is the unsigned variant of .BR ber_int_t . .LP .B ber_len_t is an unsigned integer of at least 32 bits used to represent a length. It is commonly equivalent to a .BR size_t . .B ber_slen_t is the signed variant to .BR ber_len_t . .LP .B ber_tag_t is an unsigned integer of at least 32 bits used to represent a BER tag. It is commonly equivalent to a .BR unsigned\ long . .LP The actual definitions of the integral impl_TYPE_t types are platform specific. .LP .BR BerValue , commonly used as .BR struct\ berval , is used to hold an arbitrary sequence of octets. .B bv_val points to .B bv_len octets. .B bv_val is not necessarily terminated by a NULL (zero) octet. .BR ber_bvfree () frees a BerValue, pointed to by \fIbv\fP, returned from this API. If \fIbv\fP is NULL, the routine does nothing. .LP .BR ber_bvecfree () frees an array of BerValues (and the array), pointed to by \fIbvec\fP, returned from this API. If \fIbvec\fP is NULL, the routine does nothing. .BR ber_bvecadd () appends the \fIbv\fP pointer to the \fIbvec\fP array. Space for the array is allocated as needed. The end of the array is marked by a NULL pointer. .LP .BR ber_bvarray_free () frees an array of BerValues (and the array), pointed to by \fIbvarray\fP, returned from this API. If \fIbvarray\fP is NULL, the routine does nothing. .BR ber_bvarray_add () appends the contents of the BerValue pointed to by \fIbv\fP to the \fIbvarray\fP array. Space for the new element is allocated as needed. The end of the array is marked by a BerValue with a NULL bv_val field. .LP .BR ber_bvdup () returns a copy of a BerValue. The routine returns NULL upon error (e.g. out of memory). The caller should use .BR ber_bvfree () to deallocate the resulting BerValue. .BR ber_dupbv () copies a BerValue from \fIsrc\fP to \fIdst\fP. If \fIdst\fP is NULL a new BerValue will be allocated to hold the copy. The routine returns NULL upon error, otherwise it returns a pointer to the copy. If \fIdst\fP is NULL the caller should use .BR ber_bvfree () to deallocate the resulting BerValue, otherwise .BR ber_memfree () should be used to deallocate the \fIdst->bv_val\fP. (The .BR ber_bvdup () function is internally implemented as ber_dupbv(NULL, bv). .BR ber_bvdup () is provided only for compatibility with an expired draft of the LDAP C API; .BR ber_dupbv () is the preferred interface.) .LP .BR ber_bvstr () returns a BerValue containing the string pointed to by \fIstr\fP. .BR ber_bvstrdup () returns a BerValue containing a copy of the string pointed to by \fIstr\fP. .BR ber_str2bv () returns a BerValue containing the string pointed to by \fIstr\fP, whose length may be optionally specified in \fIlen\fP. If \fIdup\fP is non-zero, the BerValue will contain a copy of \fIstr\fP. If \fIlen\fP is zero, the number of bytes to copy will be determined by .BR strlen (3), otherwise \fIlen\fP bytes will be copied. If \fIbv\fP is non-NULL, the result will be stored in the given BerValue, otherwise a new BerValue will be allocated to store the result. NOTE: Both .BR ber_bvstr () and .BR ber_bvstrdup () are implemented as macros using .BR ber_str2bv () in this version of the library. .LP .B BerElement is an opaque structure used to maintain state information used in encoding and decoding. .BR ber_alloc_t () is used to create an empty BerElement structure. If .B LBER_USE_DER is specified for the .I options parameter then data lengths for data written to the BerElement will be encoded in the minimal number of octets required, otherwise they will always be written as four byte values. .BR ber_init () creates a BerElement structure that is initialized with a copy of the data in its .I bv parameter. .BR ber_init2 () initializes an existing BerElement .I ber using the data in the .I bv parameter. The data is referenced directly, not copied. The .I options parameter is the same as for .BR ber_alloc_t (). .BR ber_free () frees a BerElement pointed to by \fIber\fP. If \fIber\fP is NULL, the routine does nothing. If \fIfreebuf\fP is zero, the internal buffer is not freed. .SH SEE ALSO .BR lber-encode (3), .BR lber-decode (3), .BR lber-memory (3) .LP .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 189 stdin PK �c\]�Ib� � man/man3/ldap_delete_ext.3nu �[��� .lf 1 stdin .TH LDAP_DELETE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_delete, ldap_delete_s, ldap_delete_ext, ldap_delete_ext_s \- Perform an LDAP delete operation. .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_delete_s(ld, dn) .ft LDAP *ld; char *dn; .LP .ft B int ldap_delete(ld, dn) .ft LDAP *ld; char *dn; .LP .ft B int ldap_delete_ext(ld, dn, serverctrls, clientctrls, msgidp) .ft LDAP *ld; char *dn; LDAPControl **serverctrls, **clientctrls; int *msgidp; .LP .ft B int ldap_delete_ext_s(ld, dn, serverctrls, clientctrls) .ft LDAP *ld; char *dn; LDAPControl **serverctrls, **clientctrls; .SH DESCRIPTION The .B ldap_delete_s() routine is used to perform an LDAP delete operation synchronously. It takes \fIdn\fP, the DN of the entry to be deleted. It returns an LDAP error code, indicating the success or failure of the operation. .LP The .B ldap_delete() routine is used to perform an LDAP delete operation asynchronously. It takes the same parameters as .BR ldap_delete_s(), but returns the message id of the request it initiated. The result of the delete can be obtained by a subsequent call to .BR ldap_result (3). .LP The .B ldap_delete_ext() routine allows server and client controls to be specified to extend the delete request. This routine is asynchronous like ldap_delete(), but its return value is an LDAP error code. It stores the message id of the request in the integer pointed to by msgidp. .LP The .B ldap_delete_ext_s() routine is the synchronous version of .BR ldap_delete_ext(). It also returns an LDAP error code indicating success or failure of the operation. .SH ERRORS .B ldap_delete_s() returns an LDAP error code which can be interpreted by calling one of .BR ldap_perror (3) and friends. .B ldap_delete() returns \-1 if something went wrong initiating the request. It returns the non-negative message id of the request if things went ok. .LP .B ldap_delete_ext() and .B ldap_delete_ext_s() return some Non-zero value if something went wrong initiating the request, else return 0. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 90 stdin PK �c\�� �. �. man/man3/ldap_bind_s.3nu �[��� .lf 1 stdin .TH LDAP_BIND 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_bind, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_sasl_bind, ldap_sasl_bind_s, ldap_sasl_interactive_bind_s, ldap_parse_sasl_bind_result, ldap_unbind, ldap_unbind_s, ldap_unbind_ext, ldap_unbind_ext_s, ldap_set_rebind_proc \- LDAP bind routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .BI "int ldap_bind(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_bind_s(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_simple_bind(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_simple_bind_s(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_sasl_bind(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], int *" msgidp ");" .RE .LP .BI "int ldap_sasl_bind_s(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], struct berval **" servercredp ");" .RE .LP .BI "int ldap_parse_sasl_bind_result(LDAP *" ld ", LDAPMessage *" res "," .RS .BI "struct berval **" servercredp ", int " freeit ");" .RE .LP .BI "int ldap_sasl_interactive_bind_s(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ");" .RE .LP .BI "int ldap_sasl_interactive_bind(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ", LDAPMessage *" result "," .BI "const char **" rmechp ", int *" msgidp ");" .RE .LP .BI "int (LDAP_SASL_INTERACT_PROC)(LDAP *" ld ", unsigned " flags ", void *" defaults ", void *" sasl_interact ");" .LP .BI "int ldap_unbind(LDAP *" ld ");" .LP .BI "int ldap_unbind_s(LDAP *" ld ");" .LP .BI "int ldap_unbind_ext(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_unbind_ext_s(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_set_rebind_proc (LDAP *" ld ", LDAP_REBIND_PROC *" ldap_proc ", void *" params ");" .LP .BI "int (LDAP_REBIND_PROC)(LDAP *" ld ", LDAP_CONST char *" url ", ber_tag_t " request ", ber_int_t " msgid ", void *" params ");" .SH DESCRIPTION .LP These routines provide various interfaces to the LDAP bind operation. After an association with an LDAP server is made using .BR ldap_init (3), an LDAP bind operation should be performed before other operations are attempted over the connection. An LDAP bind is required when using Version 2 of the LDAP protocol; it is optional for Version 3 but is usually needed due to security considerations. .LP There are three types of bind calls, ones providing simple authentication, ones providing SASL authentication, and general routines capable of doing either simple or SASL authentication. .LP .B SASL (Simple Authentication and Security Layer) can negotiate one of many different kinds of authentication. Both synchronous and asynchronous versions of each variant of the bind call are provided. All routines take \fIld\fP as their first parameter, as returned from .BR ldap_init (3). .SH SIMPLE AUTHENTICATION The simplest form of the bind call is .BR ldap_simple_bind_s() . It takes the DN to bind as in \fIwho\fP, and the userPassword associated with the entry in \fIpasswd\fP. It returns an LDAP error indication (see .BR ldap_error (3)). The .B ldap_simple_bind() call is asynchronous, taking the same parameters but only initiating the bind operation and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The .B ldap_sasl_bind_s() and asynchronous .B ldap_sasl_bind() functions can also be used to make a simple bind by using LDAP_SASL_SIMPLE as the SASL mechanism. .SH GENERAL AUTHENTICATION The .B ldap_bind() and .B ldap_bind_s() routines can be used when the authentication method to use needs to be selected at runtime. They both take an extra \fImethod\fP parameter selecting the authentication method to use. It should be set to LDAP_AUTH_SIMPLE to select simple authentication. .B ldap_bind() returns the message id of the request it initiates. .B ldap_bind_s() returns an LDAP error indication. .SH SASL AUTHENTICATION For SASL binds the server always ignores any provided DN, so the .I dn parameter should always be NULL. .BR ldap_sasl_bind_s () sends a single SASL bind request with the given SASL .I mechanism and credentials in the .I cred parameter. The format of the credentials depends on the particular SASL mechanism in use. For mechanisms that provide mutual authentication the server's credentials will be returned in the .I servercredp parameter. The routine returns an LDAP error indication (see .BR ldap_error (3)). The .BR ldap_sasl_bind () call is asynchronous, taking the same parameters but only sending the request and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The result must be additionally parsed by .BR ldap_parse_sasl_bind_result () to obtain any server credentials sent from the server. .LP Many SASL mechanisms require multiple message exchanges to perform a complete authentication. Applications should generally use .BR ldap_sasl_interactive_bind_s () rather than calling the basic .BR ldap_sasl_bind () functions directly. The .I mechs parameter should contain a space-separated list of candidate mechanisms to use. If this parameter is NULL or empty the library will query the supportedSASLMechanisms attribute from the server's rootDSE for the list of SASL mechanisms the server supports. The .I flags parameter controls the interaction used to retrieve any necessary SASL authentication parameters and should be one of: .TP LDAP_SASL_AUTOMATIC use defaults if available, prompt otherwise .TP LDAP_SASL_INTERACTIVE always prompt .TP LDAP_SASL_QUIET never prompt .LP The .I interact function uses the provided .I defaults to handle requests from the SASL library for particular authentication parameters. There is no defined format for the .I defaults information; it is up to the caller to use whatever format is appropriate for the supplied .I interact function. The .I sasl_interact parameter comes from the underlying SASL library. When used with Cyrus SASL this is an array of .B sasl_interact_t structures. The Cyrus SASL library will prompt for a variety of inputs, including: .TP SASL_CB_GETREALM the realm for the authentication attempt .TP SASL_CB_AUTHNAME the username to authenticate .TP SASL_CB_PASS the password for the provided username .TP SASL_CB_USER the username to use for proxy authorization .TP SASL_CB_NOECHOPROMPT generic prompt for input with input echoing disabled .TP SASL_CB_ECHOPROMPT generic prompt for input with input echoing enabled .TP SASL_CB_LIST_END indicates the end of the array of prompts .LP See the Cyrus SASL documentation for more details. .LP Applications which need to manage connections asynchronously may use .BR ldap_sasl_interactive_bind () instead of the synchronous version. A valid mechs parameter must be supplied, otherwise the library will be forced to query the server for a list of supported mechanisms, and this query will be performed synchronously. The other parameters are the same as for the synchronous function, with three additional parameters. The actual SASL mechanism that was used, and the message ID for use with .BR ldap_result () will be returned in rmechp and msgidp, respectively. The value in rmechp must not be modified by the caller and must be passed back on each subsequent call. The message obtained from .BR ldap_result () must be passed in the result parameter. This parameter must be NULL when initiating a new Bind. The caller must free the result message after each call using .BR ldap_msgfree (). The .BR ldap_sasl_interactive_bind () function returns an LDAP result code. If the code is LDAP_SASL_BIND_IN_PROGRESS then the Bind is not complete yet, and this function must be called again with the next result from the server. .SH REBINDING .LP The .B ldap_set_rebind_proc function() sets the process to use for binding when an operation returns a referral. This function is used when an application needs to bind to another server in order to follow a referral or search continuation reference. .LP The function takes \fIld\fP, the \fIrebind\fP function, and the \fIparams\fP, the arbitrary data like state information which the client might need to properly rebind. The LDAP_OPT_REFERRALS option in the \fIld\fP must be set to ON for the libraries to use the rebind function. Use the .BR ldap_set_option function to set the value. .LP The rebind function parameters are as follows: .LP The \fIld\fP parameter must be used by the application when binding to the referred server if the application wants the libraries to follow the referral. .LP The \fIurl\fP parameter points to the URL referral string received from the LDAP server. The LDAP application can use the .BR ldap_url_parse (3) function to parse the string into its components. .LP The \fIrequest\fP parameter specifies the type of request that generated the referral. .LP The \fImsgid\fP parameter specifies the message ID of the request generating the referral. .LP The \fIparams\fP parameter is the same value as passed originally to the .BR ldap_set_rebind_proc () function. .LP The LDAP libraries set all the parameters when they call the rebind function. The application should not attempt to free either the ld or the url structures in the rebind function. .LP The application must supply to the rebind function the required authentication information such as, user name, password, and certificates. The rebind function must use a synchronous bind method. .SH UNBINDING The .B ldap_unbind() call is used to unbind from the directory, terminate the current association, and free the resources contained in the \fIld\fP structure. Once it is called, the connection to the LDAP server is closed, and the \fIld\fP structure is invalid. The .B ldap_unbind_s() call is just another name for .BR ldap_unbind() ; both of these calls are synchronous in nature. .LP The .B ldap_unbind_ext() and .B ldap_unbind_ext_s() allows the operations to specify controls. .SH ERRORS Asynchronous routines will return \-1 in case of error, setting the \fIld_errno\fP parameter of the \fIld\fP structure. Synchronous routines return whatever \fIld_errno\fP is set to. See .BR ldap_error (3) for more information. .SH NOTES If an anonymous bind is sufficient for the application, the rebind process need not be provided. The LDAP libraries with the LDAP_OPT_REFERRALS option set to ON (default value) will automatically follow referrals using an anonymous bind. .LP If the application needs stronger authentication than an anonymous bind, you need to provide a rebind process for that authentication method. The bind method must be synchronous. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_open (3), .BR ldap_set_option (3), .BR ldap_url_parse (3) .B RFC 4422 (http://www.rfc-editor.org), .B Cyrus SASL (http://asg.web.cmu.edu/sasl/) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 335 stdin PK �c\�E͡ � man/man3/ldap_msgtype.3nu �[��� .lf 1 stdin .TH LDAP_RESULT 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_result \- Wait for the result of an LDAP operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_result( LDAP *ld, int msgid, int all, struct timeval *timeout, LDAPMessage **result ); int ldap_msgfree( LDAPMessage *msg ); int ldap_msgtype( LDAPMessage *msg ); int ldap_msgid( LDAPMessage *msg ); .ft .SH DESCRIPTION The .B ldap_result() routine is used to wait for and return the result of an operation previously initiated by one of the LDAP asynchronous operation routines (e.g., .BR ldap_search_ext (3), .BR ldap_modify_ext (3), etc.). Those routines all return \-1 in case of error, and an invocation identifier upon successful initiation of the operation. The invocation identifier is picked by the library and is guaranteed to be unique across the LDAP session. It can be used to request the result of a specific operation from .B ldap_result() through the \fImsgid\fP parameter. .LP The .B ldap_result() routine will block or not, depending upon the setting of the \fItimeout\fP parameter. If timeout is not a NULL pointer, it specifies a maximum interval to wait for the selection to complete. If timeout is a NULL pointer, the LDAP_OPT_TIMEOUT value set by .BR ldap_set_option (3) is used. With the default setting, the select blocks indefinitely. To effect a poll, the timeout argument should be a non-NULL pointer, pointing to a zero-valued timeval structure. To obtain the behavior of the default setting, bypassing any value set by .BR ldap_set_option (3), set to -1 the \fItv_sec\fP field of the \fItimeout\fP parameter. See .BR select (2) for further details. .LP If the result of a specific operation is required, \fImsgid\fP should be set to the invocation identifier returned when the operation was initiated, otherwise LDAP_RES_ANY or LDAP_RES_UNSOLICITED should be supplied to wait for any or unsolicited response. .LP The \fIall\fP parameter, if non-zero, causes .B ldap_result() to return all responses with msgid, otherwise only the next response is returned. This is commonly used to obtain all the responses of a search operation. .LP A search response is made up of zero or more search entries, zero or more search references, and zero or more extended partial responses followed by a search result. If \fIall\fP is set to 0, search entries will be returned one at a time as they come in, via separate calls to .BR ldap_result() . If it's set to 1, the search response will only be returned in its entirety, i.e., after all entries, all references, all extended partial responses, and the final search result have been received. .SH RETURN VALUE Upon success, the type of the result received is returned and the \fIresult\fP parameter will contain the result of the operation; otherwise, the \fIresult\fP parameter is undefined. This result should be passed to the LDAP parsing routines, .BR ldap_first_message (3) and friends, for interpretation. .LP The possible result types returned are: .LP .nf LDAP_RES_BIND (0x61) LDAP_RES_SEARCH_ENTRY (0x64) LDAP_RES_SEARCH_REFERENCE (0x73) 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) LDAP_RES_INTERMEDIATE (0x79) .fi .LP The .B ldap_msgfree() routine is used to free the memory allocated for result(s) by .B ldap_result() or .BR ldap_search_ext_s (3) and friends. It takes a pointer to the result or result chain to be freed and returns the type of the last message in the chain. If the parameter is NULL, the function does nothing and returns zero. .LP The .B ldap_msgtype() routine returns the type of a message. .LP The .B ldap_msgid() routine returns the message id of a message. .SH ERRORS .B ldap_result() returns \-1 if something bad happens, and zero if the timeout specified was exceeded. .B ldap_msgtype() and .B ldap_msgid() return \-1 on error. .SH SEE ALSO .BR ldap (3), .BR ldap_first_message (3), .BR select (2) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 137 stdin PK �c\�C�B� � man/man3/ldap_compare_ext_s.3nu �[��� .lf 1 stdin .TH LDAP_COMPARE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_compare, ldap_compare_s, ldap_compare_ext, ldap_compare_ext_s \- Perform an LDAP compare operation. .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_compare_ext( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, char *\fIattr\fB, const struct berval *\fIbvalue\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB, int *\fImsgidp\fB ); .RE .LP .ft B int ldap_compare_ext_s( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, char *\fIattr\fB, const struct berval *\fIbvalue\fB, LDAPControl **\fIserverctrls\fB, LDAPControl **\fIclientctrls\fB ); .RE .SH DESCRIPTION The .B ldap_compare_ext_s() routine is used to perform an LDAP compare operation synchronously. It takes \fIdn\fP, the DN of the entry upon which to perform the compare, and \fIattr\fP and \fIvalue\fP, the attribute description and value to compare to those found in the entry. It returns a code, which will be LDAP_COMPARE_TRUE if the entry contains the attribute value and LDAP_COMPARE_FALSE if it does not. Otherwise, an error code is returned that indicates the nature of the problem. See .BR ldap (3) for details. .LP The .B ldap_compare_ext() routine is used to perform an LDAP compare operation asynchronously. It takes the same parameters as .BR ldap_compare_ext_s() , but provides the message id of the request it initiated in the integer pointed to \fImsgidp\fP. The result of the compare can be obtained by a subsequent call to .BR ldap_result (3). .LP Both routines allow server and client controls to be specified to extend the compare request. .SH DEPRECATED INTERFACES The routines .BR ldap_compare () and .BR ldap_compare_s () are deprecated in favor of .BR ldap_compare_ext () and .BR ldap_compare_ext_s (), respectively. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 75 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 80 stdin PK �c\S/�6 6 man/man3/ldap_first_attribute.3nu �[��� .lf 1 stdin .TH LDAP_FIRST_ATTRIBUTE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_first_attribute, ldap_next_attribute \- step through LDAP entry attributes .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_first_attribute( LDAP *ld, LDAPMessage *entry, BerElement **berptr ) .LP .ft B char *ldap_next_attribute( LDAP *ld, LDAPMessage *entry, BerElement *ber ) .SH DESCRIPTION The .B ldap_first_attribute() and .B ldap_next_attribute() routines are used to step through the attributes in an LDAP entry. .B ldap_first_attribute() takes an \fIentry\fP as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3) and returns a pointer to character string containing the first attribute description in the entry. .B ldap_next_attribute() returns the next attribute description in the entry. .LP It also returns, in \fIberptr\fP, a pointer to a BerElement it has allocated to keep track of its current position. This pointer should be passed to subsequent calls to .B ldap_next_attribute() and is used to effectively step through the entry's attributes. The caller is solely responsible for freeing the BerElement pointed to by \fIberptr\fP when it is no longer needed by calling .BR ber_free (3). When calling .BR ber_free (3) in this instance, be sure the second argument is 0. .LP The attribute names returned are suitable for inclusion in a call to .BR ldap_get_values (3) to retrieve the attribute's values. .SH ERRORS If an error occurs, NULL is returned and the ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .SH NOTES The .B ldap_first_attribute() and .B ldap_next_attribute() return dynamically allocated memory that must be freed by the caller via .BR ldap_memfree (3). .SH SEE ALSO .BR ldap (3), .BR ldap_first_entry (3), .BR ldap_get_values (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 74 stdin PK �c\��MK$ K$ man/man3/ber_put_set.3nu �[��� .lf 1 stdin .TH LBER_ENCODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_alloc_t, ber_flush, ber_flush2, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring, ber_put_string, ber_put_null, ber_put_boolean, ber_put_bitstring, ber_start_seq, ber_start_set, ber_put_seq, ber_put_set \- OpenLDAP LBER simplified Basic Encoding Rules library routines for encoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_flush2(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_printf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "int ber_put_int(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_enum(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_ostring(BerElement *" ber ", const char *" str ", ber_len_t " len ", ber_tag_t " tag ");" .LP .BI "int ber_put_string(BerElement *" ber ", const char *" str ", ber_tag_t " tag ");" .LP .BI "int ber_put_null(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_boolean(BerElement *" ber ", ber_int_t " bool ", ber_tag_t " tag ");" .LP .BI "int ber_put_bitstring(BerElement *" ber ", const char *" str ", ber_len_t " blen ", ber_tag_t " tag ");" .LP .BI "int ber_start_seq(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_start_set(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_seq(BerElement *" ber ");" .LP .BI "int ber_put_set(BerElement *" ber ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the encoding routines in the lber library. See .BR lber-decode (3) for details on the corresponding decoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_alloc_t () to allocate a BER element for encoding, .BR ber_printf () to do the actual encoding, and .BR ber_flush2 () to actually write the element. The other routines are provided for those applications that need more control than .BR ber_printf () provides. In general, these routines return the length of the element encoded, or \-1 if an error occurred. .LP The .BR ber_alloc_t () routine is used to allocate a new BER element. It should be called with an argument of LBER_USE_DER. .LP The .BR ber_flush2 () routine is used to actually write the element to a socket (or file) descriptor, once it has been fully encoded (using .BR ber_printf () and friends). See .BR lber-sockbuf (3) for more details on the Sockbuf implementation of the \fIsb\fP parameter. If the \fIfreeit\fP parameter is non-zero, the supplied \fIber\fP will be freed. If \fILBER_FLUSH_FREE_ON_SUCCESS\fP is used, the \fIber\fP is only freed when successfully flushed, otherwise it is left intact; if \fILBER_FLUSH_FREE_ON_ERROR\fP is used, the \fIber\fP is only freed when an error occurs, otherwise it is left intact; if \fILBER_FLUSH_FREE_ALWAYS\fP is used, the \fIber\fP is freed anyway. This function differs from the original .BR ber_flush (3) function, whose behavior corresponds to that indicated for \fILBER_FLUSH_FREE_ON_SUCCESS\fP. Note that in the future, the behavior of .BR ber_flush (3) with \fIfreeit\fP non-zero might change into that of .BR ber_flush2 (3) with \fIfreeit\fP set to \fILBER_FLUSH_FREE_ALWAYS\fP. .LP The .BR ber_printf () routine is used to encode a BER element in much the same way that .BR sprintf (3) works. One important difference, though, is that some state information is kept with the \fIber\fP parameter so that multiple calls can be made to .BR ber_printf () to append things to the end of the BER element. .BR Ber_printf () writes to \fIber\fP, a pointer to a BerElement such as returned by .BR ber_alloc_t (). It interprets and formats its arguments according to the format string \fIfmt\fP. The format string can contain the following characters: .RS .LP .TP 3 .B b Boolean. An ber_int_t parameter should be supplied. A boolean element is output. .TP .B e Enumeration. An ber_int_t parameter should be supplied. An enumeration element is output. .TP .B i Integer. An ber_int_t parameter should be supplied. An integer element is output. .TP .B B Bitstring. A char * pointer to the start of the bitstring is supplied, followed by the number of bits in the bitstring. A bitstring element is output. .TP .B n Null. No parameter is required. A null element is output. .TP .B o Octet string. A char * is supplied, followed by the length of the string pointed to. An octet string element is output. .TP .B O Octet string. A struct berval * is supplied. An octet string element is output. .TP .B s Octet string. A null-terminated string is supplied. An octet string element is output, not including the trailing NULL octet. .TP .B t Tag. A ber_tag_t specifying the tag to give the next element is provided. This works across calls. .TP .B v Several octet strings. A null-terminated array of char *'s is supplied. Note that a construct like '{v}' is required to get an actual SEQUENCE OF octet strings. .TP .B V Several octet strings. A null-terminated array of struct berval *'s is supplied. Note that a construct like '{V}' is required to get an actual SEQUENCE OF octet strings. .TP .B W Several octet strings. An array of struct berval's is supplied. The array is terminated by a struct berval with a NULL bv_val. Note that a construct like '{W}' is required to get an actual SEQUENCE OF octet strings. .TP .B { Begin sequence. No parameter is required. .TP .B } End sequence. No parameter is required. .TP .B [ Begin set. No parameter is required. .TP .B ] End set. No parameter is required. .RE .LP The .BR ber_put_int () routine writes the integer element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_enum () routine writes the enumeration element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_boolean () routine writes the boolean value given by \fIbool\fP to the BER element. .LP The .BR ber_put_bitstring () routine writes \fIblen\fP bits starting at \fIstr\fP as a bitstring value to the given BER element. Note that \fIblen\fP is the length \fIin bits\fP of the bitstring. .LP The .BR ber_put_ostring () routine writes \fIlen\fP bytes starting at \fIstr\fP to the BER element as an octet string. .LP The .BR ber_put_string () routine writes the null-terminated string (minus the terminating '\0') to the BER element as an octet string. .LP The .BR ber_put_null () routine writes a NULL element to the BER element. .LP The .BR ber_start_seq () routine is used to start a sequence in the BER element. The .BR ber_start_set () routine works similarly. The end of the sequence or set is marked by the nearest matching call to .BR ber_put_seq () or .BR ber_put_set (), respectively. .SH EXAMPLES Assuming the following variable declarations, and that the variables have been assigned appropriately, an lber encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP can be achieved like so: .LP .nf int rc; ber_int_t scope, ali, size, time, attrsonly; char *dn, **attrs; BerElement *ber; /* ... fill in values ... */ ber = ber_alloc_t( LBER_USE_DER ); if ( ber == NULL ) { /* error */ } rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali, size, time, attrsonly, attrs ); if( rc == \-1 ) { /* error */ } else { /* success */ } .fi .SH ERRORS If an error occurs during encoding, generally these routines return \-1. .LP .SH NOTES .LP The return values for all of these functions are declared in the <lber.h> header file. .SH SEE ALSO .BR lber-decode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 289 stdin PK �c\�4�� � man/man3/ldap_mods_free.3nu �[��� .lf 1 stdin .TH LDAP_MODIFY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_modify_ext, ldap_modify_ext_s \- Perform an LDAP modify operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_modify_ext( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, LDAPMod *\fImods[]\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB, int *\fImsgidp\fB ); .RE .LP .nf .ft B int ldap_modify_ext_s( .RS .ft B LDAP *\fIld\fB, char *\fIdn\fB, LDAPMod *\fImods[]\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB ); .RE .LP .nf .ft B void ldap_mods_free( .RS .ft B LDAPMod **\fImods\fB, int \fIfreemods\fB ); .RE .SH DESCRIPTION The routine .B ldap_modify_ext_s() is used to perform an LDAP modify operation. \fIdn\fP is the DN of the entry to modify, and \fImods\fP is a null-terminated array of modifications to make to the entry. Each element of the \fImods\fP array is a pointer to an LDAPMod structure, which is defined below. .LP .nf typedef struct ldapmod { int mod_op; char *mod_type; union { char **modv_strvals; struct berval **modv_bvals; } mod_vals; struct ldapmod *mod_next; } LDAPMod; #define mod_values mod_vals.modv_strvals #define mod_bvalues mod_vals.modv_bvals .ft .fi .LP The \fImod_op\fP field is used to specify the type of modification to perform and should be one of LDAP_MOD_ADD, LDAP_MOD_DELETE, or LDAP_MOD_REPLACE. The \fImod_type\fP and \fImod_values\fP fields specify the attribute type to modify and a null-terminated array of values to add, delete, or replace respectively. The \fImod_next\fP field is used only by the LDAP server and may be ignored by the client. .LP If you need to specify a non-string value (e.g., to add a photo or audio attribute value), you should set \fImod_op\fP to the logical OR of the operation as above (e.g., LDAP_MOD_REPLACE) and the constant LDAP_MOD_BVALUES. In this case, \fImod_bvalues\fP should be used instead of \fImod_values\fP, and it should point to a null-terminated array of struct bervals, as defined in <lber.h>. .LP 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 attribute is to be deleted, the \fImod_values\fP field should be set to NULL. For LDAP_MOD_REPLACE modifications, the attribute will have the listed values after the modification, having been created if necessary. All modifications are performed in the order in which they are listed. .LP .B ldap_mods_free() can be used to free each element of a NULL-terminated array of mod structures. If \fIfreemods\fP is non-zero, the \fImods\fP pointer itself is freed as well. .LP .B ldap_modify_ext_s() returns a code indicating success or, in the case of failure, indicating the nature of the failure. See .BR ldap_error (3) for details .LP The .B ldap_modify_ext() operation works the same way as .BR ldap_modify_ext_s() , except that it is asynchronous. The integer that \fImsgidp\fP points to is set to the message id of the modify request. The result of the operation can be obtained by calling .BR ldap_result (3). .LP Both .B ldap_modify_ext() and .B ldap_modify_ext_s() allows server and client controls to be passed in via the sctrls and cctrls parameters, respectively. .SH DEPRECATED INTERFACES The .B ldap_modify() and .B ldap_modify_s() routines are deprecated in favor of the .B ldap_modify_ext() and .B ldap_modify_ext_s() routines, respectively. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 132 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 137 stdin PK �c\��MK$ K$ man/man3/ber_start_set.3nu �[��� .lf 1 stdin .TH LBER_ENCODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_alloc_t, ber_flush, ber_flush2, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring, ber_put_string, ber_put_null, ber_put_boolean, ber_put_bitstring, ber_start_seq, ber_start_set, ber_put_seq, ber_put_set \- OpenLDAP LBER simplified Basic Encoding Rules library routines for encoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_flush2(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_printf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "int ber_put_int(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_enum(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_ostring(BerElement *" ber ", const char *" str ", ber_len_t " len ", ber_tag_t " tag ");" .LP .BI "int ber_put_string(BerElement *" ber ", const char *" str ", ber_tag_t " tag ");" .LP .BI "int ber_put_null(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_boolean(BerElement *" ber ", ber_int_t " bool ", ber_tag_t " tag ");" .LP .BI "int ber_put_bitstring(BerElement *" ber ", const char *" str ", ber_len_t " blen ", ber_tag_t " tag ");" .LP .BI "int ber_start_seq(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_start_set(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_seq(BerElement *" ber ");" .LP .BI "int ber_put_set(BerElement *" ber ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the encoding routines in the lber library. See .BR lber-decode (3) for details on the corresponding decoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_alloc_t () to allocate a BER element for encoding, .BR ber_printf () to do the actual encoding, and .BR ber_flush2 () to actually write the element. The other routines are provided for those applications that need more control than .BR ber_printf () provides. In general, these routines return the length of the element encoded, or \-1 if an error occurred. .LP The .BR ber_alloc_t () routine is used to allocate a new BER element. It should be called with an argument of LBER_USE_DER. .LP The .BR ber_flush2 () routine is used to actually write the element to a socket (or file) descriptor, once it has been fully encoded (using .BR ber_printf () and friends). See .BR lber-sockbuf (3) for more details on the Sockbuf implementation of the \fIsb\fP parameter. If the \fIfreeit\fP parameter is non-zero, the supplied \fIber\fP will be freed. If \fILBER_FLUSH_FREE_ON_SUCCESS\fP is used, the \fIber\fP is only freed when successfully flushed, otherwise it is left intact; if \fILBER_FLUSH_FREE_ON_ERROR\fP is used, the \fIber\fP is only freed when an error occurs, otherwise it is left intact; if \fILBER_FLUSH_FREE_ALWAYS\fP is used, the \fIber\fP is freed anyway. This function differs from the original .BR ber_flush (3) function, whose behavior corresponds to that indicated for \fILBER_FLUSH_FREE_ON_SUCCESS\fP. Note that in the future, the behavior of .BR ber_flush (3) with \fIfreeit\fP non-zero might change into that of .BR ber_flush2 (3) with \fIfreeit\fP set to \fILBER_FLUSH_FREE_ALWAYS\fP. .LP The .BR ber_printf () routine is used to encode a BER element in much the same way that .BR sprintf (3) works. One important difference, though, is that some state information is kept with the \fIber\fP parameter so that multiple calls can be made to .BR ber_printf () to append things to the end of the BER element. .BR Ber_printf () writes to \fIber\fP, a pointer to a BerElement such as returned by .BR ber_alloc_t (). It interprets and formats its arguments according to the format string \fIfmt\fP. The format string can contain the following characters: .RS .LP .TP 3 .B b Boolean. An ber_int_t parameter should be supplied. A boolean element is output. .TP .B e Enumeration. An ber_int_t parameter should be supplied. An enumeration element is output. .TP .B i Integer. An ber_int_t parameter should be supplied. An integer element is output. .TP .B B Bitstring. A char * pointer to the start of the bitstring is supplied, followed by the number of bits in the bitstring. A bitstring element is output. .TP .B n Null. No parameter is required. A null element is output. .TP .B o Octet string. A char * is supplied, followed by the length of the string pointed to. An octet string element is output. .TP .B O Octet string. A struct berval * is supplied. An octet string element is output. .TP .B s Octet string. A null-terminated string is supplied. An octet string element is output, not including the trailing NULL octet. .TP .B t Tag. A ber_tag_t specifying the tag to give the next element is provided. This works across calls. .TP .B v Several octet strings. A null-terminated array of char *'s is supplied. Note that a construct like '{v}' is required to get an actual SEQUENCE OF octet strings. .TP .B V Several octet strings. A null-terminated array of struct berval *'s is supplied. Note that a construct like '{V}' is required to get an actual SEQUENCE OF octet strings. .TP .B W Several octet strings. An array of struct berval's is supplied. The array is terminated by a struct berval with a NULL bv_val. Note that a construct like '{W}' is required to get an actual SEQUENCE OF octet strings. .TP .B { Begin sequence. No parameter is required. .TP .B } End sequence. No parameter is required. .TP .B [ Begin set. No parameter is required. .TP .B ] End set. No parameter is required. .RE .LP The .BR ber_put_int () routine writes the integer element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_enum () routine writes the enumeration element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_boolean () routine writes the boolean value given by \fIbool\fP to the BER element. .LP The .BR ber_put_bitstring () routine writes \fIblen\fP bits starting at \fIstr\fP as a bitstring value to the given BER element. Note that \fIblen\fP is the length \fIin bits\fP of the bitstring. .LP The .BR ber_put_ostring () routine writes \fIlen\fP bytes starting at \fIstr\fP to the BER element as an octet string. .LP The .BR ber_put_string () routine writes the null-terminated string (minus the terminating '\0') to the BER element as an octet string. .LP The .BR ber_put_null () routine writes a NULL element to the BER element. .LP The .BR ber_start_seq () routine is used to start a sequence in the BER element. The .BR ber_start_set () routine works similarly. The end of the sequence or set is marked by the nearest matching call to .BR ber_put_seq () or .BR ber_put_set (), respectively. .SH EXAMPLES Assuming the following variable declarations, and that the variables have been assigned appropriately, an lber encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP can be achieved like so: .LP .nf int rc; ber_int_t scope, ali, size, time, attrsonly; char *dn, **attrs; BerElement *ber; /* ... fill in values ... */ ber = ber_alloc_t( LBER_USE_DER ); if ( ber == NULL ) { /* error */ } rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali, size, time, attrsonly, attrs ); if( rc == \-1 ) { /* error */ } else { /* success */ } .fi .SH ERRORS If an error occurs during encoding, generally these routines return \-1. .LP .SH NOTES .LP The return values for all of these functions are declared in the <lber.h> header file. .SH SEE ALSO .BR lber-decode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 289 stdin PK �c\g�d"# "# man/man3/ldap_str2syntax.3nu �[��� .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin PK �c\ m�&$ $ man/man3/ldap_result2error.3nu �[��� .lf 1 stdin .TH LDAP_ERROR 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_perror, ld_errno, ldap_result2error, ldap_errlist, ldap_err2string \- LDAP protocol error handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_err2string( int \fIerr\fB ); .SH DESCRIPTION The .B ldap_err2string() routine provides short description of the various codes returned by routines in this library. The returned string is a pointer to a static area that should not be modified. These codes are either negative, indicating an API error code; positive, indicating an LDAP resultCode other than \'success' (0), or - zero, indicating both successful use of the API and the LDAP resultCode \'success' (0). The code associated with an LDAP session is accessible using .BR ldap_get_option (3) and .BR ldap_set_option (3) with the .B LDAP_OPT_RESULT_CODE option (previously called .BR LDAP_OPT_ERROR_NUMBER ). .SH PROTOCOL RESULT CODES This section provides a partial list of protocol codes recognized by the library. As LDAP is extensible, additional values may be returned. A complete listing of \fIregistered\fP LDAP result codes can be obtained from the \fIInternet Assigned Numbers Authority\fP <http://www.iana.org>. .LP .TP 20 .SM LDAP_SUCCESS The request was successful. .TP .SM LDAP_OPERATIONS_ERROR An operations error occurred. .TP .SM LDAP_PROTOCOL_ERROR A protocol violation was detected. .TP .SM LDAP_TIMELIMIT_EXCEEDED An LDAP time limit was exceeded. .TP .SM LDAP_SIZELIMIT_EXCEEDED An LDAP size limit was exceeded. .TP .SM LDAP_COMPARE_FALSE A compare operation returned false. .TP .SM LDAP_COMPARE_TRUE A compare operation returned true. .TP .SM LDAP_STRONG_AUTH_NOT_SUPPORTED The LDAP server does not support strong authentication. .TP .SM LDAP_STRONG_AUTH_REQUIRED Strong authentication is required for the operation. .TP .SM LDAP_PARTIAL_RESULTS Partial results only returned. .TP .SM LDAP_NO_SUCH_ATTRIBUTE The attribute type specified does not exist in the entry. .TP .SM LDAP_UNDEFINED_TYPE The attribute type specified is invalid. .TP .SM LDAP_INAPPROPRIATE_MATCHING Filter type not supported for the specified attribute. .TP .SM LDAP_CONSTRAINT_VIOLATION An attribute value specified violates some constraint (e.g., a postalAddress has too many lines, or a line that is too long). .TP .SM LDAP_TYPE_OR_VALUE_EXISTS An attribute type or attribute value specified already exists in the entry. .TP .SM LDAP_INVALID_SYNTAX An invalid attribute value was specified. .TP .SM LDAP_NO_SUCH_OBJECT The specified object does not exist in The Directory. .TP .SM LDAP_ALIAS_PROBLEM An alias in The Directory points to a nonexistent entry. .TP .SM LDAP_INVALID_DN_SYNTAX A syntactically invalid DN was specified. .TP .SM LDAP_IS_LEAF The object specified is a leaf. .TP .SM LDAP_ALIAS_DEREF_PROBLEM A problem was encountered when dereferencing an alias. .TP .SM LDAP_INAPPROPRIATE_AUTH Inappropriate authentication was specified (e.g., LDAP_AUTH_SIMPLE was specified and the entry does not have a userPassword attribute). .TP .SM LDAP_INVALID_CREDENTIALS Invalid credentials were presented (e.g., the wrong password). .TP .SM LDAP_INSUFFICIENT_ACCESS The user has insufficient access to perform the operation. .TP .SM LDAP_BUSY The DSA is busy. .TP .SM LDAP_UNAVAILABLE The DSA is unavailable. .TP .SM LDAP_UNWILLING_TO_PERFORM The DSA is unwilling to perform the operation. .TP .SM LDAP_LOOP_DETECT A loop was detected. .TP .SM LDAP_NAMING_VIOLATION A naming violation occurred. .TP .SM LDAP_OBJECT_CLASS_VIOLATION An object class violation occurred (e.g., a "must" attribute was missing from the entry). .TP .SM LDAP_NOT_ALLOWED_ON_NONLEAF The operation is not allowed on a nonleaf object. .TP .SM LDAP_NOT_ALLOWED_ON_RDN The operation is not allowed on an RDN. .TP .SM LDAP_ALREADY_EXISTS The entry already exists. .TP .SM LDAP_NO_OBJECT_CLASS_MODS Object class modifications are not allowed. .TP .SM LDAP_OTHER An unknown error occurred. .SH API ERROR CODES This section provides a complete list of API error codes recognized by the library. Note that LDAP_SUCCESS indicates success of an API call in addition to representing the return of the LDAP \'success' resultCode. .LP .TP 20 .SM LDAP_SERVER_DOWN The LDAP library can't contact the LDAP server. .TP .SM LDAP_LOCAL_ERROR Some local error occurred. This is usually a failed dynamic memory allocation. .TP .SM LDAP_ENCODING_ERROR An error was encountered encoding parameters to send to the LDAP server. .TP .SM LDAP_DECODING_ERROR An error was encountered decoding a result from the LDAP server. .TP .SM LDAP_TIMEOUT A timelimit was exceeded while waiting for a result. .TP .SM LDAP_AUTH_UNKNOWN The authentication method specified to ldap_bind() is not known. .TP .SM LDAP_FILTER_ERROR An invalid filter was supplied to ldap_search() (e.g., unbalanced parentheses). .TP .SM LDAP_PARAM_ERROR An ldap routine was called with a bad parameter. .TP .SM LDAP_NO_MEMORY An memory allocation (e.g., malloc(3) or other dynamic memory allocator) call failed in an ldap library routine. .TP .SM LDAP_USER_CANCELED Indicates the user cancelled the operation. .TP .SM LDAP_CONNECT_ERROR Indicates a connection problem. .TP .SM LDAP_NOT_SUPPORTED Indicates the routine was called in a manner not supported by the library. .TP .SM LDAP_CONTROL_NOT_FOUND Indicates the control provided is unknown to the client library. .TP .SM LDAP_NO_RESULTS_RETURNED Indicates no results returned. .TP .SM LDAP_MORE_RESULTS_TO_RETURN Indicates more results could be returned. .TP .SM LDAP_CLIENT_LOOP Indicates the library has detected a loop in its processing. .TP .SM LDAP_REFERRAL_LIMIT_EXCEEDED Indicates the referral limit has been exceeded. .SH DEPRECATED .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 220 stdin .SH SEE ALSO .BR ldap (3), .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 225 stdin PK �c\�E͡ � man/man3/ldap_msgid.3nu �[��� .lf 1 stdin .TH LDAP_RESULT 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_result \- Wait for the result of an LDAP operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_result( LDAP *ld, int msgid, int all, struct timeval *timeout, LDAPMessage **result ); int ldap_msgfree( LDAPMessage *msg ); int ldap_msgtype( LDAPMessage *msg ); int ldap_msgid( LDAPMessage *msg ); .ft .SH DESCRIPTION The .B ldap_result() routine is used to wait for and return the result of an operation previously initiated by one of the LDAP asynchronous operation routines (e.g., .BR ldap_search_ext (3), .BR ldap_modify_ext (3), etc.). Those routines all return \-1 in case of error, and an invocation identifier upon successful initiation of the operation. The invocation identifier is picked by the library and is guaranteed to be unique across the LDAP session. It can be used to request the result of a specific operation from .B ldap_result() through the \fImsgid\fP parameter. .LP The .B ldap_result() routine will block or not, depending upon the setting of the \fItimeout\fP parameter. If timeout is not a NULL pointer, it specifies a maximum interval to wait for the selection to complete. If timeout is a NULL pointer, the LDAP_OPT_TIMEOUT value set by .BR ldap_set_option (3) is used. With the default setting, the select blocks indefinitely. To effect a poll, the timeout argument should be a non-NULL pointer, pointing to a zero-valued timeval structure. To obtain the behavior of the default setting, bypassing any value set by .BR ldap_set_option (3), set to -1 the \fItv_sec\fP field of the \fItimeout\fP parameter. See .BR select (2) for further details. .LP If the result of a specific operation is required, \fImsgid\fP should be set to the invocation identifier returned when the operation was initiated, otherwise LDAP_RES_ANY or LDAP_RES_UNSOLICITED should be supplied to wait for any or unsolicited response. .LP The \fIall\fP parameter, if non-zero, causes .B ldap_result() to return all responses with msgid, otherwise only the next response is returned. This is commonly used to obtain all the responses of a search operation. .LP A search response is made up of zero or more search entries, zero or more search references, and zero or more extended partial responses followed by a search result. If \fIall\fP is set to 0, search entries will be returned one at a time as they come in, via separate calls to .BR ldap_result() . If it's set to 1, the search response will only be returned in its entirety, i.e., after all entries, all references, all extended partial responses, and the final search result have been received. .SH RETURN VALUE Upon success, the type of the result received is returned and the \fIresult\fP parameter will contain the result of the operation; otherwise, the \fIresult\fP parameter is undefined. This result should be passed to the LDAP parsing routines, .BR ldap_first_message (3) and friends, for interpretation. .LP The possible result types returned are: .LP .nf LDAP_RES_BIND (0x61) LDAP_RES_SEARCH_ENTRY (0x64) LDAP_RES_SEARCH_REFERENCE (0x73) 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) LDAP_RES_INTERMEDIATE (0x79) .fi .LP The .B ldap_msgfree() routine is used to free the memory allocated for result(s) by .B ldap_result() or .BR ldap_search_ext_s (3) and friends. It takes a pointer to the result or result chain to be freed and returns the type of the last message in the chain. If the parameter is NULL, the function does nothing and returns zero. .LP The .B ldap_msgtype() routine returns the type of a message. .LP The .B ldap_msgid() routine returns the message id of a message. .SH ERRORS .B ldap_result() returns \-1 if something bad happens, and zero if the timeout specified was exceeded. .B ldap_msgtype() and .B ldap_msgid() return \-1 on error. .SH SEE ALSO .BR ldap (3), .BR ldap_first_message (3), .BR select (2) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 137 stdin PK �c\%�&}. . man/man3/ldap_destroy.3nu �[��� .lf 1 stdin .TH LDAP_OPEN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_dup, ldap_destroy, \- Duplicate and destroy LDAP session handles .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B LDAP *ldap_dup( .RS .ft B LDAP *\fIold\fB ); .RE .LP .ft B int ldap_destroy( .RS .ft B LDAP *\fIold\fB ); .RE .SH DESCRIPTION .LP .B ldap_dup() duplicates an existing LDAP .RB ( "LDAP *" ) session handle. The new session handle may be used concurrently with the original session handle. In a threaded environment, different threads may execute concurrent requests on the same connection/session without fear of contamination. Each session handle manages its own private error results. .LP .B ldap_destroy() destroys an existing session handle. .LP The .B ldap_dup() and .B ldap_destroy() functions are used in conjunction with a "thread safe" version of .B libldap .RB ( libldap_r ) to enable operation thread safe API calls, so that a single session may be simultaneously used across multiple threads with consistent error handling. .LP When a session is created through the use of one of the session creation functions including .BR ldap_open (3), .BR ldap_init (3), .BR ldap_initialize (3) or .BR ldap_init_fd (3) an .B "LDAP *" session handle is returned to the application. The session handle may be shared amongst threads, however the error codes are unique to a session handle. Multiple threads performing different operations using the same session handle will result in inconsistent error codes and return values. .LP To prevent this confusion, .B ldap_dup() is used duplicate an existing session handle so that multiple threads can share the session, and maintain consistent error information and results. .LP The message queues for a session are shared between sibling session handles. Results of operations on a sibling session handles are accessible to all the sibling session handles. Applications desiring results associated with a specific operation should provide the appropriate msgid to .BR ldap_result() . Applications should avoid calling .B ldap_result() with .B LDAP_RES_ANY as that may "steal" and return results in the calling thread that another operation in a different thread, using a different session handle, may require to complete. .LP When .B ldap_unbind() is called on a session handle with siblings, all the siblings become invalid. .LP Siblings must be destroyed using .BR ldap_destroy() . Session handle resources associated with the original .RB ( "LDAP *" ) will be freed when the last session handle is destroyed or when .B ldap_unbind() is called, if no other session handles currently exist. .SH ERRORS If an error occurs, .B ldap_dup() will return NULL and .I errno should be set appropriately. .B ldap_destroy() will directly return the LDAP code associated to the error (or .I LDAP_SUCCESS in case of success); .I errno should be set as well whenever appropriate. .SH SEE ALSO .BR ldap_open (3), .BR ldap_init (3), .BR ldap_initialize (3), .BR ldap_init_fd (3), .BR errno (3) .SH ACKNOWLEDGEMENTS This work is based on the previously proposed .B LDAP C API Concurrency Extensions draft .BR ( draft-zeilenga-ldap-c-api-concurrency-00.txt ) effort. .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 127 stdin PK �c\� �q q man/man3/ldap_get_dn.3nu �[��� .lf 1 stdin .TH LDAP_GET_DN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn \- LDAP DN handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ) .LP .ft B int ldap_str2dn( const char *str, LDAPDN *dn, unsigned flags ) .LP .ft B void ldap_dnfree( LDAPDN dn ) .LP .ft B int ldap_dn2str( LDAPDN dn, char **str, unsigned flags ) .LP .ft B char **ldap_explode_dn( const char *dn, int notypes ) .LP .ft B char **ldap_explode_rdn( const char *rdn, int notypes ) .LP .ft B char *ldap_dn2ufn( const char * dn ) .LP .ft B char *ldap_dn2dcedn( const char * dn ) .LP .ft B char *ldap_dcedn2dn( const char * dn ) .LP .ft B char *ldap_dn2ad_canonical( const char * dn ) .SH DESCRIPTION These routines allow LDAP entry names (Distinguished Names, or DNs) to be obtained, parsed, converted to a user-friendly form, and tested. A DN has the form described in RFC 4414 "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names". .LP The .B ldap_get_dn() routine takes an \fIentry\fP as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3) and returns a copy of the entry's DN. Space for the DN will be obtained dynamically and should be freed by the caller using .BR ldap_memfree (3). .LP .B ldap_str2dn() parses a string representation of a distinguished name contained in .B str into its components, which are stored in .B dn as .B ldap_ava structures, arranged in .B LDAPAVA, .B LDAPRDN, and .B LDAPDN terms. Space for .B dn will be obtained dynamically and should be freed by the caller using .BR ldap_dnfree (3). The .B LDAPDN is defined as: .nf .ft B typedef struct ldap_ava { struct berval la_attr; struct berval la_value; unsigned la_flags; } LDAPAVA; typedef LDAPAVA** LDAPRDN; typedef LDAPRDN* LDAPDN; .ft .fi The attribute types and the attribute values are not normalized. The .B la_flags can be either .B LDAP_AVA_STRING or .B LDAP_AVA_BINARY, the latter meaning that the value is BER/DER encoded and thus must be represented as, quoting from RFC 4514, " ... an octothorpe character ('#' ASCII 35) followed by the hexadecimal representation of each of the bytes of the BER encoding of the X.500 AttributeValue." The .B flags parameter to .B ldap_str2dn() can be .LP .nf LDAP_DN_FORMAT_LDAPV3 LDAP_DN_FORMAT_LDAPV2 LDAP_DN_FORMAT_DCE .fi which defines what DN syntax is expected (according to RFC 4514, RFC 1779 and DCE, respectively). The format can be \fIOR\fPed to the flags .LP .nf LDAP_DN_P_NO_SPACES LDAP_DN_P_NO_SPACE_AFTER_RDN ... LDAP_DN_PEDANTIC .fi The latter is a shortcut for all the previous limitations. .LP .B LDAP_DN_P_NO_SPACES does not allow extra spaces in the dn; the default is to silently eliminate spaces around AVA separators ('='), RDN component separators ('+' for LDAPv3/LDAPv2 or ',' for DCE) and RDN separators (',' LDAPv3/LDAPv2 or '/' for DCE). .LP .B LDAP_DN_P_NO_SPACE_AFTER_RDN does not allow a single space after RDN separators. .LP .B ldap_dn2str() performs the inverse operation, yielding in .B str a string representation of .B dn. It allows the same values for .B flags as .B ldap_str2dn(), plus .LP .nf LDAP_DN_FORMAT_UFN LDAP_DN_FORMAT_AD_CANONICAL .fi for user-friendly naming (RFC 1781) and AD canonical. .LP The following routines are viewed as deprecated in favor of .B ldap_str2dn() and .BR ldap_dn2str(). They are provided to support legacy applications. .LP The .B ldap_explode_dn() routine takes a DN as returned by .B ldap_get_dn() and breaks it up into its component parts. Each part is known as a Relative Distinguished Name, or RDN. .B ldap_explode_dn() returns a NULL-terminated array, each component of which contains an RDN from the DN. The \fInotypes\fP parameter is used to request that only the RDN values be returned, not their types. For example, the DN "cn=Bob, c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob", "US", NULL }, depending on whether notypes was 0 or 1, respectively. Assertion values in RDN strings may included escaped characters. The result can be freed by calling .BR ldap_value_free (3). .LP Similarly, the .B ldap_explode_rdn() routine takes an RDN as returned by .B ldap_explode_dn(dn,0) and breaks it up into its "type=value" component parts (or just "value", if the \fInotypes\fP parameter is set). Note the value is not unescaped. The result can be freed by calling .BR ldap_value_free (3). .LP .B ldap_dn2ufn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a more user-friendly form, stripping off all type names. See "Using the Directory to Achieve User Friendly Naming" (RFC 1781) for more details on the UFN format. Due to the ambiguous nature of the format, it is generally only used for display purposes. The space for the UFN returned is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .LP .B ldap_dn2dcedn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a DCE-style DN, e.g. a string with most-significant to least significant rdns separated by slashes ('/'); rdn components are separated by commas (','). Only printable chars (e.g. LDAPv2 printable string) are allowed, at least in this implementation. .B ldap_dcedn2dn() performs the opposite operation. .B ldap_dn2ad_canonical() turns a DN into a AD canonical name, which is basically a DCE dn with attribute types omitted. The trailing domain, if present, is turned in a DNS-like domain. The space for the returned value is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .SH ERRORS If an error occurs in .BR ldap_get_dn() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .BR ldap_explode_dn() , .BR ldap_explode_rdn() , .B ldap_dn2ufn(), .B ldap_dn2dcedn(), .B ldap_dcedn2dn(), and .B ldap_dn2ad_canonical() will return NULL with .BR errno (3) set appropriately in case of trouble. .SH NOTES These routines dynamically allocate memory that the caller must free. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_first_entry (3), .BR ldap_memfree (3), .BR ldap_value_free (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 247 stdin PK �c\�� �. �. man/man3/ldap_unbind.3nu �[��� .lf 1 stdin .TH LDAP_BIND 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_bind, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_sasl_bind, ldap_sasl_bind_s, ldap_sasl_interactive_bind_s, ldap_parse_sasl_bind_result, ldap_unbind, ldap_unbind_s, ldap_unbind_ext, ldap_unbind_ext_s, ldap_set_rebind_proc \- LDAP bind routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .BI "int ldap_bind(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_bind_s(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_simple_bind(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_simple_bind_s(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_sasl_bind(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], int *" msgidp ");" .RE .LP .BI "int ldap_sasl_bind_s(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], struct berval **" servercredp ");" .RE .LP .BI "int ldap_parse_sasl_bind_result(LDAP *" ld ", LDAPMessage *" res "," .RS .BI "struct berval **" servercredp ", int " freeit ");" .RE .LP .BI "int ldap_sasl_interactive_bind_s(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ");" .RE .LP .BI "int ldap_sasl_interactive_bind(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ", LDAPMessage *" result "," .BI "const char **" rmechp ", int *" msgidp ");" .RE .LP .BI "int (LDAP_SASL_INTERACT_PROC)(LDAP *" ld ", unsigned " flags ", void *" defaults ", void *" sasl_interact ");" .LP .BI "int ldap_unbind(LDAP *" ld ");" .LP .BI "int ldap_unbind_s(LDAP *" ld ");" .LP .BI "int ldap_unbind_ext(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_unbind_ext_s(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_set_rebind_proc (LDAP *" ld ", LDAP_REBIND_PROC *" ldap_proc ", void *" params ");" .LP .BI "int (LDAP_REBIND_PROC)(LDAP *" ld ", LDAP_CONST char *" url ", ber_tag_t " request ", ber_int_t " msgid ", void *" params ");" .SH DESCRIPTION .LP These routines provide various interfaces to the LDAP bind operation. After an association with an LDAP server is made using .BR ldap_init (3), an LDAP bind operation should be performed before other operations are attempted over the connection. An LDAP bind is required when using Version 2 of the LDAP protocol; it is optional for Version 3 but is usually needed due to security considerations. .LP There are three types of bind calls, ones providing simple authentication, ones providing SASL authentication, and general routines capable of doing either simple or SASL authentication. .LP .B SASL (Simple Authentication and Security Layer) can negotiate one of many different kinds of authentication. Both synchronous and asynchronous versions of each variant of the bind call are provided. All routines take \fIld\fP as their first parameter, as returned from .BR ldap_init (3). .SH SIMPLE AUTHENTICATION The simplest form of the bind call is .BR ldap_simple_bind_s() . It takes the DN to bind as in \fIwho\fP, and the userPassword associated with the entry in \fIpasswd\fP. It returns an LDAP error indication (see .BR ldap_error (3)). The .B ldap_simple_bind() call is asynchronous, taking the same parameters but only initiating the bind operation and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The .B ldap_sasl_bind_s() and asynchronous .B ldap_sasl_bind() functions can also be used to make a simple bind by using LDAP_SASL_SIMPLE as the SASL mechanism. .SH GENERAL AUTHENTICATION The .B ldap_bind() and .B ldap_bind_s() routines can be used when the authentication method to use needs to be selected at runtime. They both take an extra \fImethod\fP parameter selecting the authentication method to use. It should be set to LDAP_AUTH_SIMPLE to select simple authentication. .B ldap_bind() returns the message id of the request it initiates. .B ldap_bind_s() returns an LDAP error indication. .SH SASL AUTHENTICATION For SASL binds the server always ignores any provided DN, so the .I dn parameter should always be NULL. .BR ldap_sasl_bind_s () sends a single SASL bind request with the given SASL .I mechanism and credentials in the .I cred parameter. The format of the credentials depends on the particular SASL mechanism in use. For mechanisms that provide mutual authentication the server's credentials will be returned in the .I servercredp parameter. The routine returns an LDAP error indication (see .BR ldap_error (3)). The .BR ldap_sasl_bind () call is asynchronous, taking the same parameters but only sending the request and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The result must be additionally parsed by .BR ldap_parse_sasl_bind_result () to obtain any server credentials sent from the server. .LP Many SASL mechanisms require multiple message exchanges to perform a complete authentication. Applications should generally use .BR ldap_sasl_interactive_bind_s () rather than calling the basic .BR ldap_sasl_bind () functions directly. The .I mechs parameter should contain a space-separated list of candidate mechanisms to use. If this parameter is NULL or empty the library will query the supportedSASLMechanisms attribute from the server's rootDSE for the list of SASL mechanisms the server supports. The .I flags parameter controls the interaction used to retrieve any necessary SASL authentication parameters and should be one of: .TP LDAP_SASL_AUTOMATIC use defaults if available, prompt otherwise .TP LDAP_SASL_INTERACTIVE always prompt .TP LDAP_SASL_QUIET never prompt .LP The .I interact function uses the provided .I defaults to handle requests from the SASL library for particular authentication parameters. There is no defined format for the .I defaults information; it is up to the caller to use whatever format is appropriate for the supplied .I interact function. The .I sasl_interact parameter comes from the underlying SASL library. When used with Cyrus SASL this is an array of .B sasl_interact_t structures. The Cyrus SASL library will prompt for a variety of inputs, including: .TP SASL_CB_GETREALM the realm for the authentication attempt .TP SASL_CB_AUTHNAME the username to authenticate .TP SASL_CB_PASS the password for the provided username .TP SASL_CB_USER the username to use for proxy authorization .TP SASL_CB_NOECHOPROMPT generic prompt for input with input echoing disabled .TP SASL_CB_ECHOPROMPT generic prompt for input with input echoing enabled .TP SASL_CB_LIST_END indicates the end of the array of prompts .LP See the Cyrus SASL documentation for more details. .LP Applications which need to manage connections asynchronously may use .BR ldap_sasl_interactive_bind () instead of the synchronous version. A valid mechs parameter must be supplied, otherwise the library will be forced to query the server for a list of supported mechanisms, and this query will be performed synchronously. The other parameters are the same as for the synchronous function, with three additional parameters. The actual SASL mechanism that was used, and the message ID for use with .BR ldap_result () will be returned in rmechp and msgidp, respectively. The value in rmechp must not be modified by the caller and must be passed back on each subsequent call. The message obtained from .BR ldap_result () must be passed in the result parameter. This parameter must be NULL when initiating a new Bind. The caller must free the result message after each call using .BR ldap_msgfree (). The .BR ldap_sasl_interactive_bind () function returns an LDAP result code. If the code is LDAP_SASL_BIND_IN_PROGRESS then the Bind is not complete yet, and this function must be called again with the next result from the server. .SH REBINDING .LP The .B ldap_set_rebind_proc function() sets the process to use for binding when an operation returns a referral. This function is used when an application needs to bind to another server in order to follow a referral or search continuation reference. .LP The function takes \fIld\fP, the \fIrebind\fP function, and the \fIparams\fP, the arbitrary data like state information which the client might need to properly rebind. The LDAP_OPT_REFERRALS option in the \fIld\fP must be set to ON for the libraries to use the rebind function. Use the .BR ldap_set_option function to set the value. .LP The rebind function parameters are as follows: .LP The \fIld\fP parameter must be used by the application when binding to the referred server if the application wants the libraries to follow the referral. .LP The \fIurl\fP parameter points to the URL referral string received from the LDAP server. The LDAP application can use the .BR ldap_url_parse (3) function to parse the string into its components. .LP The \fIrequest\fP parameter specifies the type of request that generated the referral. .LP The \fImsgid\fP parameter specifies the message ID of the request generating the referral. .LP The \fIparams\fP parameter is the same value as passed originally to the .BR ldap_set_rebind_proc () function. .LP The LDAP libraries set all the parameters when they call the rebind function. The application should not attempt to free either the ld or the url structures in the rebind function. .LP The application must supply to the rebind function the required authentication information such as, user name, password, and certificates. The rebind function must use a synchronous bind method. .SH UNBINDING The .B ldap_unbind() call is used to unbind from the directory, terminate the current association, and free the resources contained in the \fIld\fP structure. Once it is called, the connection to the LDAP server is closed, and the \fIld\fP structure is invalid. The .B ldap_unbind_s() call is just another name for .BR ldap_unbind() ; both of these calls are synchronous in nature. .LP The .B ldap_unbind_ext() and .B ldap_unbind_ext_s() allows the operations to specify controls. .SH ERRORS Asynchronous routines will return \-1 in case of error, setting the \fIld_errno\fP parameter of the \fIld\fP structure. Synchronous routines return whatever \fIld_errno\fP is set to. See .BR ldap_error (3) for more information. .SH NOTES If an anonymous bind is sufficient for the application, the rebind process need not be provided. The LDAP libraries with the LDAP_OPT_REFERRALS option set to ON (default value) will automatically follow referrals using an anonymous bind. .LP If the application needs stronger authentication than an anonymous bind, you need to provide a rebind process for that authentication method. The bind method must be synchronous. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_open (3), .BR ldap_set_option (3), .BR ldap_url_parse (3) .B RFC 4422 (http://www.rfc-editor.org), .B Cyrus SASL (http://asg.web.cmu.edu/sasl/) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 335 stdin PK �c\��n� � man/man3/ldap_init.3nu �[��� .lf 1 stdin .TH LDAP_OPEN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_init, ldap_initialize, ldap_open \- Initialize the LDAP library and open a connection to an LDAP server .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B LDAP *ldap_open(host, port) .ft char *host; int port; .LP .ft B LDAP *ldap_init(host, port) .ft char *host; int port; .LP .ft B int ldap_initialize(ldp, uri) .ft LDAP **ldp; char *uri; .LP .ft B int ldap_set_urllist_proc(ld, proc, params) .ft LDAP *ld; LDAP_URLLIST_PROC *proc; void *params; .LP .ft B int (LDAP_URLLIST_PROC)(ld, urllist, url, params); .ft LDAP *ld; LDAPURLDesc **urllist; LDAPURLDesc **url; void *params; .LP .ft B #include <ldap_pvt.h> .LP .ft B int ldap_init_fd(fd, proto, uri, ldp) .ft ber_socket_t fd; int proto; char *uri; LDAP **ldp; .SH DESCRIPTION .LP .B ldap_open() opens a connection to an LDAP server and allocates an LDAP structure which is used to identify the connection and to maintain per-connection information. .B ldap_init() allocates an LDAP structure but does not open an initial connection. .B ldap_initialize() allocates an LDAP structure but does not open an initial connection. .B ldap_init_fd() allocates an LDAP structure using an existing connection on the provided socket. One of these routines must be called before any operations are attempted. .LP .B ldap_open() takes \fIhost\fP, the hostname on which the LDAP server is running, and \fIport\fP, the port number to which to connect. If the default IANA-assigned port of 389 is desired, LDAP_PORT should be specified for \fIport\fP. The \fIhost\fP parameter may contain a blank-separated list of hosts to try to connect to, and each host may optionally by of the form \fIhost:port\fP. If present, the \fI:port\fP overrides the \fIport\fP parameter to .BR ldap_open() . Upon successfully making a connection to an LDAP server, .B ldap_open() returns a pointer to an opaque LDAP structure, which should be passed to subsequent calls to .BR ldap_bind() , .BR ldap_search() , etc. Certain fields in the LDAP structure can be set to indicate size limit, time limit, and how aliases are handled during operations; read and write access to those fields must occur by calling .BR ldap_get_option (3) and .BR ldap_set_option (3) respectively, whenever possible. .LP .B ldap_init() acts just like .BR ldap_open() , but does not open a connection to the LDAP server. The actual connection open will occur when the first operation is attempted. .LP .B ldap_initialize() acts like .BR ldap_init() , but it returns an integer indicating either success or the failure reason, and it allows to specify details for the connection in the schema portion of the URI. The .I uri parameter may be a comma- or whitespace-separated list of URIs containing only the .IR schema , the .IR host , and the .I port fields. Apart from .BR ldap , other (non-standard) recognized values of the .I schema field are .B ldaps (LDAP over TLS), .B ldapi (LDAP over IPC), and .B cldap (connectionless LDAP). If other fields are present, the behavior is undefined. .LP At this time, .B ldap_open() and .B ldap_init() are deprecated in favor of .BR ldap_initialize() , essentially because the latter allows to specify a schema in the URI and it explicitly returns an error code. .LP .B ldap_init_fd() allows an LDAP structure to be initialized using an already-opened connection. The .I proto parameter should be one of LDAP_PROTO_TCP, LDAP_PROTO_UDP, or LDAP_PROTO_IPC for a connection using TCP, UDP, or IPC, respectively. The value LDAP_PROTO_EXT may also be specified if user-supplied sockbuf handlers are going to be used. Note that support for UDP is not implemented unless libldap was built with LDAP_CONNECTIONLESS defined. The .I uri parameter may optionally be provided for informational purposes. .LP .B ldap_set_urllist_proc() allows to set a function .I proc of type .I LDAP_URLLIST_PROC that is called when a successful connection can be established. This function receives the list of URIs parsed from the .I uri string originally passed to .BR ldap_initialize() , and the one that successfully connected. The function may manipulate the URI list; the typical use consists in moving the successful URI to the head of the list, so that subsequent attempts to connect to one of the URIs using the same LDAP handle will try it first. If .I ld is null, .I proc is set as a global parameter that is inherited by all handlers within the process that are created after the call to .BR ldap_set_urllist_proc() . By default, no .I LDAP_URLLIST_PROC is set. In a multithreaded environment, .B ldap_set_urllist_proc() must be called before any concurrent operation using the LDAP handle is started. Note: the first call into the LDAP library also initializes the global options for the library. As such the first call should be single-threaded or otherwise protected to insure that only one call is active. It is recommended that .BR ldap_get_option () or .BR ldap_set_option () be used in the program's main thread before any additional threads are created. See .BR ldap_get_option (3). .SH ERRORS If an error occurs, .B ldap_open() and .B ldap_init() will return NULL and .I errno should be set appropriately. .B ldap_initialize() and .B ldap_init_fd() will directly return the LDAP code associated to the error (or .I LDAP_SUCCESS in case of success); .I errno should be set as well whenever appropriate. .B ldap_set_urllist_proc() returns LDAP_OPT_ERROR on error, and LDAP_OPT_SUCCESS on success. .SH SEE ALSO .BR ldap (3), .BR ldap_bind (3), .BR ldap_get_option (3), .BR ldap_set_option (3), .BR lber-sockbuf (3), .BR errno (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 226 stdin PK �c\ NO O man/man3/ldap_next_message.3nu �[��� .lf 1 stdin .TH LDAP_FIRST_MESSAGE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_first_message, ldap_next_message, ldap_count_messages \- Stepping through messages in a result chain .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_count_messages( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_first_message( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_next_message( LDAP *ld, LDAPMessage *message ) .SH DESCRIPTION .LP These routines are used to step through the messages in a result chain received from .BR ldap_result (3) . For search operations, the result chain can contain referral, entry and result messages. The .BR ldap_msgtype (3) function can be used to distinguish between the different message types. .LP The .B ldap_first_message() routine is used to retrieve the first message in a result chain. It takes the \fIresult\fP as returned by a call to .BR ldap_result (3) , .BR ldap_search_s (3) or .BR ldap_search_st (3) and returns a pointer to the first message in the result chain. .LP This pointer should be supplied on a subsequent call to .B ldap_next_message() to get the next message, the result of which should be supplied to the next call to .BR ldap_next_message() , etc. .B ldap_next_message() will return NULL when there are no more messages. .LP These functions are useful when using routines like .BR ldap_parse_result (3) that only operate on the first result in the chain. .LP A count of the number of messages in the result chain can be obtained by calling .BR ldap_count_messages() . It can also be used to count the number of remaining messages in a chain if called with a message, entry or reference returned by .B ldap_first_message() , .B ldap_next_message() , .BR ldap_first_entry (3) , .BR ldap_next_entry (3) , .BR ldap_first_reference (3) , .BR ldap_next_reference (3) . .SH ERRORS If an error occurs in .B ldap_first_message() or .BR ldap_next_message() , NULL is returned. If an error occurs in .BR ldap_count_messages() , -1 is returned. .SH SEE ALSO .BR ldap (3), .BR ldap_search (3), .BR ldap_result (3), .BR ldap_parse_result (3), .BR ldap_first_entry (3), .BR ldap_first_reference (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 83 stdin PK �c\�w;+- - man/man3/ldap_first_reference.3nu �[��� .lf 1 stdin .TH LDAP_FIRST_REFERENCE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_first_reference, ldap_next_reference, ldap_count_references \- Stepping through continuation references in a result chain .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_count_references( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_first_reference( LDAP *ld, LDAPMessage *result ) .LP .ft B LDAPMessage *ldap_next_reference( LDAP *ld, LDAPMessage *reference ) .SH DESCRIPTION .LP These routines are used to step through the continuation references in a result chain received from .BR ldap_result (3) or the synchronous LDAP search operation routines. .LP The .B ldap_first_reference() routine is used to retrieve the first reference message in a result chain. It takes the \fIresult\fP as returned by a call to .BR ldap_result (3) , .BR ldap_search_s (3) or .BR ldap_search_st (3) and returns a pointer to the first reference message in the result chain. .LP This pointer should be supplied on a subsequent call to .B ldap_next_reference() to get the next reference message, the result of which should be supplied to the next call to .BR ldap_next_reference() , etc. .B ldap_next_reference() will return NULL when there are no more reference messages. The reference messages returned from these calls are used by .BR ldap_parse_reference (3) to extract referrals and controls. .LP A count of the number of reference messages in the search result can be obtained by calling .BR ldap_count_references() . It can also be used to count the number of reference messages remaining in a result chain. .SH ERRORS If an error occurs in .B ldap_first_reference() or .BR ldap_next_reference() , NULL is returned. If an error occurs in .BR ldap_count_references() , -1 is returned. .SH SEE ALSO .BR ldap (3), .BR ldap_result (3), .BR ldap_search (3), .BR ldap_parse_reference (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 72 stdin PK �c\}�q � � man/man3/ldap_add_ext.3nu �[��� .lf 1 stdin .TH LDAP_ADD 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_add_ext, ldap_add_ext_s \- Perform an LDAP add operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .ft B #include <ldap.h> .LP .ft B .nf int ldap_add_ext( .RS .ft B LDAP *\fIld, const char *\fIdn\fB, LDAPMod **\fIattrs\fB, LDAPControl **\fIsctrls\fB, LDAPControl **\fIcctrls\fB, int *\fImsgidp\fB ); .RE .LP .ft B .nf int ldap_add_ext_s( .RS LDAP *\fIld\fB, const char *\fIdn\fB, LDAPMod **\fIattrs\fB, LDAPControl *\fIsctrls\fB, LDAPControl *\fIcctrls\fB ); .RE .fi .SH DESCRIPTION The .B ldap_add_ext_s() routine is used to perform an LDAP add operation. It takes \fIdn\fP, the DN of the entry to add, and \fIattrs\fP, a null-terminated array of the entry's attributes. The LDAPMod structure is used to represent attributes, with the \fImod_type\fP and \fImod_values\fP fields being used as described under .BR ldap_modify_ext (3), and the \fIldap_op\fP field being used only if you need to specify the LDAP_MOD_BVALUES option. Otherwise, it should be set to zero. .LP Note that all entries except that specified by the last component in the given DN must already exist. .B ldap_add_ext_s() returns an code indicating success or, in the case of failure, indicating the nature of failure of the operation. See .BR ldap_error (3) for more details. .LP The .B ldap_add_ext() routine works just like .BR ldap_add_ext_s() , but it is asynchronous. It returns the message id of the request it initiated. The result of this operation can be obtained by calling .BR ldap_result (3). .SH DEPRECATED INTERFACES The .BR ldap_add () and .BR ldap_add_s () routines are deprecated in favor of the .BR ldap_add_ext () and .BR ldap_add_ext_s () routines, respectively. .LP .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 76 stdin .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_modify (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 82 stdin PK �c\ m�&$ $ man/man3/ldap_err2string.3nu �[��� .lf 1 stdin .TH LDAP_ERROR 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_perror, ld_errno, ldap_result2error, ldap_errlist, ldap_err2string \- LDAP protocol error handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_err2string( int \fIerr\fB ); .SH DESCRIPTION The .B ldap_err2string() routine provides short description of the various codes returned by routines in this library. The returned string is a pointer to a static area that should not be modified. These codes are either negative, indicating an API error code; positive, indicating an LDAP resultCode other than \'success' (0), or - zero, indicating both successful use of the API and the LDAP resultCode \'success' (0). The code associated with an LDAP session is accessible using .BR ldap_get_option (3) and .BR ldap_set_option (3) with the .B LDAP_OPT_RESULT_CODE option (previously called .BR LDAP_OPT_ERROR_NUMBER ). .SH PROTOCOL RESULT CODES This section provides a partial list of protocol codes recognized by the library. As LDAP is extensible, additional values may be returned. A complete listing of \fIregistered\fP LDAP result codes can be obtained from the \fIInternet Assigned Numbers Authority\fP <http://www.iana.org>. .LP .TP 20 .SM LDAP_SUCCESS The request was successful. .TP .SM LDAP_OPERATIONS_ERROR An operations error occurred. .TP .SM LDAP_PROTOCOL_ERROR A protocol violation was detected. .TP .SM LDAP_TIMELIMIT_EXCEEDED An LDAP time limit was exceeded. .TP .SM LDAP_SIZELIMIT_EXCEEDED An LDAP size limit was exceeded. .TP .SM LDAP_COMPARE_FALSE A compare operation returned false. .TP .SM LDAP_COMPARE_TRUE A compare operation returned true. .TP .SM LDAP_STRONG_AUTH_NOT_SUPPORTED The LDAP server does not support strong authentication. .TP .SM LDAP_STRONG_AUTH_REQUIRED Strong authentication is required for the operation. .TP .SM LDAP_PARTIAL_RESULTS Partial results only returned. .TP .SM LDAP_NO_SUCH_ATTRIBUTE The attribute type specified does not exist in the entry. .TP .SM LDAP_UNDEFINED_TYPE The attribute type specified is invalid. .TP .SM LDAP_INAPPROPRIATE_MATCHING Filter type not supported for the specified attribute. .TP .SM LDAP_CONSTRAINT_VIOLATION An attribute value specified violates some constraint (e.g., a postalAddress has too many lines, or a line that is too long). .TP .SM LDAP_TYPE_OR_VALUE_EXISTS An attribute type or attribute value specified already exists in the entry. .TP .SM LDAP_INVALID_SYNTAX An invalid attribute value was specified. .TP .SM LDAP_NO_SUCH_OBJECT The specified object does not exist in The Directory. .TP .SM LDAP_ALIAS_PROBLEM An alias in The Directory points to a nonexistent entry. .TP .SM LDAP_INVALID_DN_SYNTAX A syntactically invalid DN was specified. .TP .SM LDAP_IS_LEAF The object specified is a leaf. .TP .SM LDAP_ALIAS_DEREF_PROBLEM A problem was encountered when dereferencing an alias. .TP .SM LDAP_INAPPROPRIATE_AUTH Inappropriate authentication was specified (e.g., LDAP_AUTH_SIMPLE was specified and the entry does not have a userPassword attribute). .TP .SM LDAP_INVALID_CREDENTIALS Invalid credentials were presented (e.g., the wrong password). .TP .SM LDAP_INSUFFICIENT_ACCESS The user has insufficient access to perform the operation. .TP .SM LDAP_BUSY The DSA is busy. .TP .SM LDAP_UNAVAILABLE The DSA is unavailable. .TP .SM LDAP_UNWILLING_TO_PERFORM The DSA is unwilling to perform the operation. .TP .SM LDAP_LOOP_DETECT A loop was detected. .TP .SM LDAP_NAMING_VIOLATION A naming violation occurred. .TP .SM LDAP_OBJECT_CLASS_VIOLATION An object class violation occurred (e.g., a "must" attribute was missing from the entry). .TP .SM LDAP_NOT_ALLOWED_ON_NONLEAF The operation is not allowed on a nonleaf object. .TP .SM LDAP_NOT_ALLOWED_ON_RDN The operation is not allowed on an RDN. .TP .SM LDAP_ALREADY_EXISTS The entry already exists. .TP .SM LDAP_NO_OBJECT_CLASS_MODS Object class modifications are not allowed. .TP .SM LDAP_OTHER An unknown error occurred. .SH API ERROR CODES This section provides a complete list of API error codes recognized by the library. Note that LDAP_SUCCESS indicates success of an API call in addition to representing the return of the LDAP \'success' resultCode. .LP .TP 20 .SM LDAP_SERVER_DOWN The LDAP library can't contact the LDAP server. .TP .SM LDAP_LOCAL_ERROR Some local error occurred. This is usually a failed dynamic memory allocation. .TP .SM LDAP_ENCODING_ERROR An error was encountered encoding parameters to send to the LDAP server. .TP .SM LDAP_DECODING_ERROR An error was encountered decoding a result from the LDAP server. .TP .SM LDAP_TIMEOUT A timelimit was exceeded while waiting for a result. .TP .SM LDAP_AUTH_UNKNOWN The authentication method specified to ldap_bind() is not known. .TP .SM LDAP_FILTER_ERROR An invalid filter was supplied to ldap_search() (e.g., unbalanced parentheses). .TP .SM LDAP_PARAM_ERROR An ldap routine was called with a bad parameter. .TP .SM LDAP_NO_MEMORY An memory allocation (e.g., malloc(3) or other dynamic memory allocator) call failed in an ldap library routine. .TP .SM LDAP_USER_CANCELED Indicates the user cancelled the operation. .TP .SM LDAP_CONNECT_ERROR Indicates a connection problem. .TP .SM LDAP_NOT_SUPPORTED Indicates the routine was called in a manner not supported by the library. .TP .SM LDAP_CONTROL_NOT_FOUND Indicates the control provided is unknown to the client library. .TP .SM LDAP_NO_RESULTS_RETURNED Indicates no results returned. .TP .SM LDAP_MORE_RESULTS_TO_RETURN Indicates more results could be returned. .TP .SM LDAP_CLIENT_LOOP Indicates the library has detected a loop in its processing. .TP .SM LDAP_REFERRAL_LIMIT_EXCEEDED Indicates the referral limit has been exceeded. .SH DEPRECATED .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 220 stdin .SH SEE ALSO .BR ldap (3), .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 225 stdin PK �c\g�d"# "# ! man/man3/ldap_attributetype2str.3nu �[��� .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin PK �c\g�d"# "# ! man/man3/ldap_matchingrule2name.3nu �[��� .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin PK �c\�6+� � " man/man3/ldap_parse_sort_control.3nu �[��� .lf 1 stdin .TH LDAP_PARSE_SORT-CONTROL 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_parse_sort_control \- Decode the information returned from a search operation that used a server-side sort control .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_parse_sort_control(ld, ctrls, returnCode, attribute) .ft LDAP *ld; LDAPControl **ctrls; unsigned long *returnCode; char **attribute; .SH DESCRIPTION This function is used to parse the results returned in a search operation that uses a server-side sort control. .LP It takes a null terminated array of LDAPControl structures usually obtained by a call to the .BR ldap_parse_result function. A returncode which points to the sort control result code,and an array of LDAPControl structures that list the client controls to use with the search. The function also takes an out parameter \fIattribute\fP and if the sort operation fails, the server may return a string that indicates the first attribute in the sortKey list that caused the failure. If this parameter is NULL, no string is returned. If a string is returned, the memory should be freed by calling the ldap_memfree function. .SH NOTES .SH SEE ALSO .BR ldap_result (3), .BR ldap_controls_free (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 41 stdin PK �c\�5^#v1 v1 man/man3/ber_get_int.3nu �[��� .lf 1 stdin .TH LBER_DECODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");" .LP .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");" .LP .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");" .LP .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");" .LP .BI "ber_tag_t ber_get_null(BerElement *" ber ");" .LP .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");" .LP .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");" .LP .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");" .LP .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the decoding routines in the lber library. See .BR lber-encode (3) for details on the corresponding encoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_get_next () to get the next BER element and .BR ber_scanf () to do the actual decoding. In some cases, .BR ber_peek_tag () may also need to be called in normal usage. The other routines are provided for those applications that need more control than .BR ber_scanf () provides. In general, these routines return the tag of the element decoded, or LBER_ERROR if an error occurred. .LP The .BR ber_get_next () routine is used to read the next BER element from the given Sockbuf, \fIsb\fP. It strips off and returns the leading tag, strips off and returns the length of the entire element in \fIlen\fP, and sets up \fIber\fP for subsequent calls to .BR ber_scanf () et al to decode the element. See .BR lber-sockbuf (3) for details of the Sockbuf implementation of the \fIsb\fP parameter. .LP The .BR ber_scanf () routine is used to decode a BER element in much the same way that .BR scanf (3) works. It reads from \fIber\fP, a pointer to a BerElement such as returned by .BR ber_get_next (), interprets the bytes according to the format string \fIfmt\fP, and stores the results in its additional arguments. 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. .RS .LP .TP 3 .B a Octet string. A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter. The caller should free the returned string using .BR ber_memfree (). .TP .B A Octet string. A variant of "\fBa\fP". A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter, unless a zero-length string would result; in that case, the arg is set to NULL. The caller should free the returned string using .BR ber_memfree (). .TP .B s Octet string. A char * buffer should be supplied, followed by a pointer to a ber_len_t initialized to the size of the buffer. Upon return, the null-terminated octet string is put into the buffer, and the ber_len_t is set to the actual size of the octet string. .TP .B O Octet string. A struct ber_val ** should be supplied, which upon return points to a dynamically allocated struct berval containing the octet string and its length. The caller should free the returned structure using .BR ber_bvfree (). .TP .B o Octet string. A struct ber_val * should be supplied, which upon return contains the dynamically allocated octet string and its length. The caller should free the returned octet string using .BR ber_memfree (). .TP .B m Octet string. A struct ber_val * should be supplied, which upon return contains the octet string and its length. The string resides in memory assigned to the BerElement, and must not be freed by the caller. .TP .B b Boolean. A pointer to a ber_int_t should be supplied. .TP .B e Enumeration. A pointer to a ber_int_t should be supplied. .TP .B i Integer. A pointer to a ber_int_t should be supplied. .TP .B B Bitstring. A char ** should be supplied which will point to the dynamically allocated bits, followed by a ber_len_t *, which will point to the length (in bits) of the bitstring returned. .TP .B n Null. No parameter is required. The element is simply skipped if it is recognized. .TP .B v Sequence of octet strings. A char *** should be supplied, which upon return points to a dynamically allocated null-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty. The caller should free the returned array and octet strings using .BR ber_memvfree (). .TP .B V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon return points to a dynamically allocated null-terminated array of struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvecfree (). .TP .B W Sequence of octet strings with lengths. A BerVarray * should be supplied, which upon return points to a dynamically allocated array of struct berval's containing the octet strings and their lengths. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvarray_free (). .TP .B M Sequence of octet strings with lengths. This is a generalized form of the previous three formats. A void ** (ptr) should be supplied, followed by a ber_len_t * (len) and a ber_len_t (off). Upon return (ptr) will point to a dynamically allocated array whose elements are all of size (*len). A struct berval will be filled starting at offset (off) in each element. The strings in each struct berval reside in memory assigned to the BerElement and must not be freed by the caller. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The number of elements in the array is also stored in (*len) on return. The caller should free the returned array using .BR ber_memfree (). .TP .B l Length of the next element. A pointer to a ber_len_t should be supplied. .TP .B t Tag of the next element. A pointer to a ber_tag_t should be supplied. .TP .B T Skip element and return its tag. A pointer to a ber_tag_t should be supplied. .TP .B x Skip element. The next element is skipped. .TP .B { Begin sequence. No parameter is required. The initial sequence tag and length are skipped. .TP .B } End sequence. No parameter is required and no action is taken. .TP .B [ Begin set. No parameter is required. The initial set tag and length are skipped. .TP .B ] End set. No parameter is required and no action is taken. .RE .LP The .BR ber_get_int () routine tries to interpret the next element as an integer, returning the result in \fInum\fP. The tag of whatever it finds is returned on success, LBER_ERROR (\-1) on failure. .LP The .BR ber_get_stringb () routine is used to read an octet string into a preallocated buffer. The \fIlen\fP parameter should be initialized to the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte. .LP The .BR ber_get_stringa () routine is used to dynamically allocate space into which an octet string is read. The caller should free the returned string using .BR ber_memfree(). .LP The .BR ber_get_stringal () routine is used to dynamically allocate space into which an octet string and its length are read. It takes a struct berval **, and returns the result in this parameter. The caller should free the returned structure using .BR ber_bvfree(). .LP The .BR ber_get_stringbv () routine is used to read an octet string and its length into the provided struct berval *. If the \fIalloc\fP parameter is zero, the string will reside in memory assigned to the BerElement, and must not be freed by the caller. If the \fIalloc\fP parameter is non-zero, the string will be copied into dynamically allocated space which should be returned using .BR ber_memfree (). .LP The .BR ber_get_null () routine is used to read a NULL element. It returns the tag of the element it skips over. .LP The .BR ber_get_boolean () routine is used to read a boolean value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_enum () routine is used to read a enumeration value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_bitstringa () routine is used to read a bitstring value. It takes a char ** which will hold the dynamically allocated bits, followed by an ber_len_t *, which will point to the length (in bits) of the bitstring returned. The caller should free the returned string using .BR ber_memfree (). .LP The .BR ber_first_element () routine is used to return the tag and length of the first element in a set or sequence. It also returns in \fIcookie\fP a magic cookie parameter that should be passed to subsequent calls to ber_next_element(), which returns similar information. .SH EXAMPLES Assume the variable \fIber\fP contains a lightweight BER encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP The element can be decoded using .BR ber_scanf () as follows. .LP .nf ber_int_t scope, deref, size, time, attrsonly; char *dn, **attrs; ber_tag_t tag; tag = ber_scanf( ber, "{aeeiib{v}}", &dn, &scope, &deref, &size, &time, &attrsonly, &attrs ); if( tag == LBER_ERROR ) { /* error */ } else { /* success */ } ber_memfree( dn ); ber_memvfree( attrs ); .fi .SH ERRORS If an error occurs during decoding, generally these routines return LBER_ERROR ((ber_tag_t)\-1). .LP .SH NOTES .LP The return values for all of these functions are declared in the .B <lber.h> header file. Some routines may dynamically allocate memory which must be freed by the caller using supplied deallocation routines. .SH SEE ALSO .BR lber-encode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 358 stdin PK �c\ ݴ� man/man3/ldap_is_ldap_url.3nu �[��� .lf 1 stdin .TH LDAP_URL 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_is_ldap_url, ldap_url_parse, ldap_free_urldesc \- LDAP Uniform Resource Locator routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_is_ldap_url( const char *url ) .LP .ft B int ldap_url_parse( const char *url, LDAPURLDesc **ludpp ) .LP typedef struct ldap_url_desc { char * lud_scheme; /* URI scheme */ char * lud_host; /* LDAP host to contact */ int lud_port; /* port on host */ char * lud_dn; /* base for search */ char ** lud_attrs; /* list of attributes */ int lud_scope; /* a LDAP_SCOPE_... value */ char * lud_filter; /* LDAP search filter */ char ** lud_exts; /* LDAP extensions */ int lud_crit_exts; /* true if any extension is critical */ /* may contain additional fields for internal use */ } LDAPURLDesc; .LP .ft B void ldap_free_urldesc( LDAPURLDesc *ludp ); .SH DESCRIPTION These routines support the use of LDAP URLs (Uniform Resource Locators) as detailed in RFC 4516. LDAP URLs look like this: .nf \fBldap://\fP\fIhostport\fP\fB/\fP\fIdn\fP[\fB?\fP\fIattrs\fP[\fB?\fP\fIscope\fP[\fB?\fP\fIfilter\fP[\fB?\fP\fIexts\fP]]]] where: \fIhostport\fP is a host name with an optional ":portnumber" \fIdn\fP is the search base \fIattrs\fP is a comma separated list of attributes to request \fIscope\fP is one of these three strings: base one sub (default=base) \fIfilter\fP is filter \fIexts\fP are recognized set of LDAP and/or API extensions. Example: ldap://ldap.example.net/dc=example,dc=net?cn,sn?sub?(cn=*) .fi .LP URLs that are wrapped in angle-brackets and/or preceded by "URL:" are also tolerated. Alternative LDAP schemes such as ldaps:// and ldapi:// may be parsed using the below routines as well. .LP .B ldap_is_ldap_url() returns a non-zero value if \fIurl\fP looks like an LDAP URL (as opposed to some other kind of URL). It can be used as a quick check for an LDAP URL; the .B ldap_url_parse() routine should be used if a more thorough check is needed. .LP .B ldap_url_parse() breaks down an LDAP URL passed in \fIurl\fP into its component pieces. If successful, zero is returned, an LDAP URL description is allocated, filled in, and \fIludpp\fP is set to point to it. If an error occurs, a non-zero URL error code is returned. .LP .B ldap_free_urldesc() should be called to free an LDAP URL description that was obtained from a call to .B ldap_url_parse(). .SH SEE ALSO .nf .BR ldap (3) .BR "RFC 4516" " <http://www.rfc-editor.org/rfc/rfc4516.txt>" .SH ACKNOWLEDGEMENTS .fi .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 84 stdin PK �c\ ��� � % man/man3/ldap_parse_extended_result.3nu �[��� .lf 1 stdin .TH LDAP_PARSE_RESULT 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_parse_result \- Parsing results .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_parse_result( LDAP *ld, LDAPMessage *result, int *errcodep, char **matcheddnp, char **errmsgp, char ***referralsp, LDAPControl ***serverctrlsp, int freeit ) .LP .ft B int ldap_parse_sasl_bind_result( LDAP *ld, LDAPMessage *result, struct berval **servercredp, int freeit ) .LP .ft B int ldap_parse_extended_result( LDAP *ld, LDAPMessage *result, char **retoidp, struct berval **retdatap, int freeit ) .SH DESCRIPTION .LP These routines are used to extract information from a result message. They will operate on the first result message in a chain of search results (skipping past other message types). They take the \fIresult\fP as returned by a call to .BR ldap_result (3), .BR ldap_search_s (3) or .BR ldap_search_st (3). In addition to .BR ldap_parse_result() , the routines .B ldap_parse_sasl_bind_result() and .B ldap_parse_extended_result() are used to get all the result information from SASL bind and extended operations. .LP The \fIerrcodep\fP parameter will be filled in with the result code from the result message. .LP The server might supply a matched DN string in the message indicating how much of a name in a request was recognized. The \fImatcheddnp\fP parameter will be filled in with this string if supplied, else it will be NULL. If a string is returned, it should be freed using .BR ldap_memfree (3). .LP The \fIerrmsgp\fP parameter will be filled in with the error message field from the parsed message. This string should be freed using .BR ldap_memfree (3). .LP The \fIreferralsp\fP parameter will be filled in with an allocated array of referral strings from the parsed message. This array should be freed using .BR ldap_memvfree (3). If no referrals were returned, \fI*referralsp\fP is set to NULL. .LP The \fIserverctrlsp\fP parameter will be filled in with an allocated array of controls copied from the parsed message. The array should be freed using .BR ldap_controls_free (3). If no controls were returned, \fI*serverctrlsp\fP is set to NULL. .LP The \fIfreeit\fP parameter determines whether the parsed message is freed or not after the extraction. Any non-zero value will make it free the message. The .BR ldap_msgfree (3) routine can also be used to free the message later. .LP For SASL bind results, the \fIservercredp\fP parameter will be filled in with an allocated berval structure containing the credentials from the server if present. The structure should be freed using .BR ber_bvfree (3). .LP For extended results, the \fIretoidp\fP parameter will be filled in with the dotted-OID text representation of the name of the extended operation response. The string should be freed using .BR ldap_memfree (3). If no OID was returned, \fI*retoidp\fP is set to NULL. .LP For extended results, the \fIretdatap\fP parameter will be filled in with a pointer to a berval structure containing the data from the extended operation response. The structure should be freed using .BR ber_bvfree (3). If no data were returned, \fI*retdatap\fP is set to NULL. .LP For all the above result parameters, NULL values can be used in calls in order to ignore certain fields. .SH ERRORS Upon success LDAP_SUCCESS is returned. Otherwise the values of the result parameters are undefined. .SH SEE ALSO .BR ldap (3), .BR ldap_result (3), .BR ldap_search (3), .BR ldap_memfree (3), .BR ldap_memvfree (3), .BR ldap_get_values (3), .BR ldap_controls_free (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 108 stdin PK �c\�5^#v1 v1 man/man3/lber-decode.3nu �[��� .lf 1 stdin .TH LBER_DECODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");" .LP .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");" .LP .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");" .LP .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");" .LP .BI "ber_tag_t ber_get_null(BerElement *" ber ");" .LP .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");" .LP .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");" .LP .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");" .LP .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the decoding routines in the lber library. See .BR lber-encode (3) for details on the corresponding encoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_get_next () to get the next BER element and .BR ber_scanf () to do the actual decoding. In some cases, .BR ber_peek_tag () may also need to be called in normal usage. The other routines are provided for those applications that need more control than .BR ber_scanf () provides. In general, these routines return the tag of the element decoded, or LBER_ERROR if an error occurred. .LP The .BR ber_get_next () routine is used to read the next BER element from the given Sockbuf, \fIsb\fP. It strips off and returns the leading tag, strips off and returns the length of the entire element in \fIlen\fP, and sets up \fIber\fP for subsequent calls to .BR ber_scanf () et al to decode the element. See .BR lber-sockbuf (3) for details of the Sockbuf implementation of the \fIsb\fP parameter. .LP The .BR ber_scanf () routine is used to decode a BER element in much the same way that .BR scanf (3) works. It reads from \fIber\fP, a pointer to a BerElement such as returned by .BR ber_get_next (), interprets the bytes according to the format string \fIfmt\fP, and stores the results in its additional arguments. 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. .RS .LP .TP 3 .B a Octet string. A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter. The caller should free the returned string using .BR ber_memfree (). .TP .B A Octet string. A variant of "\fBa\fP". A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter, unless a zero-length string would result; in that case, the arg is set to NULL. The caller should free the returned string using .BR ber_memfree (). .TP .B s Octet string. A char * buffer should be supplied, followed by a pointer to a ber_len_t initialized to the size of the buffer. Upon return, the null-terminated octet string is put into the buffer, and the ber_len_t is set to the actual size of the octet string. .TP .B O Octet string. A struct ber_val ** should be supplied, which upon return points to a dynamically allocated struct berval containing the octet string and its length. The caller should free the returned structure using .BR ber_bvfree (). .TP .B o Octet string. A struct ber_val * should be supplied, which upon return contains the dynamically allocated octet string and its length. The caller should free the returned octet string using .BR ber_memfree (). .TP .B m Octet string. A struct ber_val * should be supplied, which upon return contains the octet string and its length. The string resides in memory assigned to the BerElement, and must not be freed by the caller. .TP .B b Boolean. A pointer to a ber_int_t should be supplied. .TP .B e Enumeration. A pointer to a ber_int_t should be supplied. .TP .B i Integer. A pointer to a ber_int_t should be supplied. .TP .B B Bitstring. A char ** should be supplied which will point to the dynamically allocated bits, followed by a ber_len_t *, which will point to the length (in bits) of the bitstring returned. .TP .B n Null. No parameter is required. The element is simply skipped if it is recognized. .TP .B v Sequence of octet strings. A char *** should be supplied, which upon return points to a dynamically allocated null-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty. The caller should free the returned array and octet strings using .BR ber_memvfree (). .TP .B V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon return points to a dynamically allocated null-terminated array of struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvecfree (). .TP .B W Sequence of octet strings with lengths. A BerVarray * should be supplied, which upon return points to a dynamically allocated array of struct berval's containing the octet strings and their lengths. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvarray_free (). .TP .B M Sequence of octet strings with lengths. This is a generalized form of the previous three formats. A void ** (ptr) should be supplied, followed by a ber_len_t * (len) and a ber_len_t (off). Upon return (ptr) will point to a dynamically allocated array whose elements are all of size (*len). A struct berval will be filled starting at offset (off) in each element. The strings in each struct berval reside in memory assigned to the BerElement and must not be freed by the caller. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The number of elements in the array is also stored in (*len) on return. The caller should free the returned array using .BR ber_memfree (). .TP .B l Length of the next element. A pointer to a ber_len_t should be supplied. .TP .B t Tag of the next element. A pointer to a ber_tag_t should be supplied. .TP .B T Skip element and return its tag. A pointer to a ber_tag_t should be supplied. .TP .B x Skip element. The next element is skipped. .TP .B { Begin sequence. No parameter is required. The initial sequence tag and length are skipped. .TP .B } End sequence. No parameter is required and no action is taken. .TP .B [ Begin set. No parameter is required. The initial set tag and length are skipped. .TP .B ] End set. No parameter is required and no action is taken. .RE .LP The .BR ber_get_int () routine tries to interpret the next element as an integer, returning the result in \fInum\fP. The tag of whatever it finds is returned on success, LBER_ERROR (\-1) on failure. .LP The .BR ber_get_stringb () routine is used to read an octet string into a preallocated buffer. The \fIlen\fP parameter should be initialized to the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte. .LP The .BR ber_get_stringa () routine is used to dynamically allocate space into which an octet string is read. The caller should free the returned string using .BR ber_memfree(). .LP The .BR ber_get_stringal () routine is used to dynamically allocate space into which an octet string and its length are read. It takes a struct berval **, and returns the result in this parameter. The caller should free the returned structure using .BR ber_bvfree(). .LP The .BR ber_get_stringbv () routine is used to read an octet string and its length into the provided struct berval *. If the \fIalloc\fP parameter is zero, the string will reside in memory assigned to the BerElement, and must not be freed by the caller. If the \fIalloc\fP parameter is non-zero, the string will be copied into dynamically allocated space which should be returned using .BR ber_memfree (). .LP The .BR ber_get_null () routine is used to read a NULL element. It returns the tag of the element it skips over. .LP The .BR ber_get_boolean () routine is used to read a boolean value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_enum () routine is used to read a enumeration value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_bitstringa () routine is used to read a bitstring value. It takes a char ** which will hold the dynamically allocated bits, followed by an ber_len_t *, which will point to the length (in bits) of the bitstring returned. The caller should free the returned string using .BR ber_memfree (). .LP The .BR ber_first_element () routine is used to return the tag and length of the first element in a set or sequence. It also returns in \fIcookie\fP a magic cookie parameter that should be passed to subsequent calls to ber_next_element(), which returns similar information. .SH EXAMPLES Assume the variable \fIber\fP contains a lightweight BER encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP The element can be decoded using .BR ber_scanf () as follows. .LP .nf ber_int_t scope, deref, size, time, attrsonly; char *dn, **attrs; ber_tag_t tag; tag = ber_scanf( ber, "{aeeiib{v}}", &dn, &scope, &deref, &size, &time, &attrsonly, &attrs ); if( tag == LBER_ERROR ) { /* error */ } else { /* success */ } ber_memfree( dn ); ber_memvfree( attrs ); .fi .SH ERRORS If an error occurs during decoding, generally these routines return LBER_ERROR ((ber_tag_t)\-1). .LP .SH NOTES .LP The return values for all of these functions are declared in the .B <lber.h> header file. Some routines may dynamically allocate memory which must be freed by the caller using supplied deallocation routines. .SH SEE ALSO .BR lber-encode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 358 stdin PK �c\�5^#v1 v1 man/man3/ber_get_enum.3nu �[��� .lf 1 stdin .TH LBER_DECODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");" .LP .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");" .LP .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");" .LP .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");" .LP .BI "ber_tag_t ber_get_null(BerElement *" ber ");" .LP .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");" .LP .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");" .LP .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");" .LP .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the decoding routines in the lber library. See .BR lber-encode (3) for details on the corresponding encoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_get_next () to get the next BER element and .BR ber_scanf () to do the actual decoding. In some cases, .BR ber_peek_tag () may also need to be called in normal usage. The other routines are provided for those applications that need more control than .BR ber_scanf () provides. In general, these routines return the tag of the element decoded, or LBER_ERROR if an error occurred. .LP The .BR ber_get_next () routine is used to read the next BER element from the given Sockbuf, \fIsb\fP. It strips off and returns the leading tag, strips off and returns the length of the entire element in \fIlen\fP, and sets up \fIber\fP for subsequent calls to .BR ber_scanf () et al to decode the element. See .BR lber-sockbuf (3) for details of the Sockbuf implementation of the \fIsb\fP parameter. .LP The .BR ber_scanf () routine is used to decode a BER element in much the same way that .BR scanf (3) works. It reads from \fIber\fP, a pointer to a BerElement such as returned by .BR ber_get_next (), interprets the bytes according to the format string \fIfmt\fP, and stores the results in its additional arguments. 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. .RS .LP .TP 3 .B a Octet string. A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter. The caller should free the returned string using .BR ber_memfree (). .TP .B A Octet string. A variant of "\fBa\fP". A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter, unless a zero-length string would result; in that case, the arg is set to NULL. The caller should free the returned string using .BR ber_memfree (). .TP .B s Octet string. A char * buffer should be supplied, followed by a pointer to a ber_len_t initialized to the size of the buffer. Upon return, the null-terminated octet string is put into the buffer, and the ber_len_t is set to the actual size of the octet string. .TP .B O Octet string. A struct ber_val ** should be supplied, which upon return points to a dynamically allocated struct berval containing the octet string and its length. The caller should free the returned structure using .BR ber_bvfree (). .TP .B o Octet string. A struct ber_val * should be supplied, which upon return contains the dynamically allocated octet string and its length. The caller should free the returned octet string using .BR ber_memfree (). .TP .B m Octet string. A struct ber_val * should be supplied, which upon return contains the octet string and its length. The string resides in memory assigned to the BerElement, and must not be freed by the caller. .TP .B b Boolean. A pointer to a ber_int_t should be supplied. .TP .B e Enumeration. A pointer to a ber_int_t should be supplied. .TP .B i Integer. A pointer to a ber_int_t should be supplied. .TP .B B Bitstring. A char ** should be supplied which will point to the dynamically allocated bits, followed by a ber_len_t *, which will point to the length (in bits) of the bitstring returned. .TP .B n Null. No parameter is required. The element is simply skipped if it is recognized. .TP .B v Sequence of octet strings. A char *** should be supplied, which upon return points to a dynamically allocated null-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty. The caller should free the returned array and octet strings using .BR ber_memvfree (). .TP .B V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon return points to a dynamically allocated null-terminated array of struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvecfree (). .TP .B W Sequence of octet strings with lengths. A BerVarray * should be supplied, which upon return points to a dynamically allocated array of struct berval's containing the octet strings and their lengths. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvarray_free (). .TP .B M Sequence of octet strings with lengths. This is a generalized form of the previous three formats. A void ** (ptr) should be supplied, followed by a ber_len_t * (len) and a ber_len_t (off). Upon return (ptr) will point to a dynamically allocated array whose elements are all of size (*len). A struct berval will be filled starting at offset (off) in each element. The strings in each struct berval reside in memory assigned to the BerElement and must not be freed by the caller. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The number of elements in the array is also stored in (*len) on return. The caller should free the returned array using .BR ber_memfree (). .TP .B l Length of the next element. A pointer to a ber_len_t should be supplied. .TP .B t Tag of the next element. A pointer to a ber_tag_t should be supplied. .TP .B T Skip element and return its tag. A pointer to a ber_tag_t should be supplied. .TP .B x Skip element. The next element is skipped. .TP .B { Begin sequence. No parameter is required. The initial sequence tag and length are skipped. .TP .B } End sequence. No parameter is required and no action is taken. .TP .B [ Begin set. No parameter is required. The initial set tag and length are skipped. .TP .B ] End set. No parameter is required and no action is taken. .RE .LP The .BR ber_get_int () routine tries to interpret the next element as an integer, returning the result in \fInum\fP. The tag of whatever it finds is returned on success, LBER_ERROR (\-1) on failure. .LP The .BR ber_get_stringb () routine is used to read an octet string into a preallocated buffer. The \fIlen\fP parameter should be initialized to the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte. .LP The .BR ber_get_stringa () routine is used to dynamically allocate space into which an octet string is read. The caller should free the returned string using .BR ber_memfree(). .LP The .BR ber_get_stringal () routine is used to dynamically allocate space into which an octet string and its length are read. It takes a struct berval **, and returns the result in this parameter. The caller should free the returned structure using .BR ber_bvfree(). .LP The .BR ber_get_stringbv () routine is used to read an octet string and its length into the provided struct berval *. If the \fIalloc\fP parameter is zero, the string will reside in memory assigned to the BerElement, and must not be freed by the caller. If the \fIalloc\fP parameter is non-zero, the string will be copied into dynamically allocated space which should be returned using .BR ber_memfree (). .LP The .BR ber_get_null () routine is used to read a NULL element. It returns the tag of the element it skips over. .LP The .BR ber_get_boolean () routine is used to read a boolean value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_enum () routine is used to read a enumeration value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_bitstringa () routine is used to read a bitstring value. It takes a char ** which will hold the dynamically allocated bits, followed by an ber_len_t *, which will point to the length (in bits) of the bitstring returned. The caller should free the returned string using .BR ber_memfree (). .LP The .BR ber_first_element () routine is used to return the tag and length of the first element in a set or sequence. It also returns in \fIcookie\fP a magic cookie parameter that should be passed to subsequent calls to ber_next_element(), which returns similar information. .SH EXAMPLES Assume the variable \fIber\fP contains a lightweight BER encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP The element can be decoded using .BR ber_scanf () as follows. .LP .nf ber_int_t scope, deref, size, time, attrsonly; char *dn, **attrs; ber_tag_t tag; tag = ber_scanf( ber, "{aeeiib{v}}", &dn, &scope, &deref, &size, &time, &attrsonly, &attrs ); if( tag == LBER_ERROR ) { /* error */ } else { /* success */ } ber_memfree( dn ); ber_memvfree( attrs ); .fi .SH ERRORS If an error occurs during decoding, generally these routines return LBER_ERROR ((ber_tag_t)\-1). .LP .SH NOTES .LP The return values for all of these functions are declared in the .B <lber.h> header file. Some routines may dynamically allocate memory which must be freed by the caller using supplied deallocation routines. .SH SEE ALSO .BR lber-encode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 358 stdin PK �c\��1ܽ � man/man3/ldap_control_free.3nu �[��� .lf 1 stdin .TH LDAP_CONTROLS 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_control_create, ldap_control_find, ldap_control_dup, ldap_controls_dup, ldap_control_free, ldap_controls_free \- LDAP control manipulation routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "int ldap_control_create(const char *" oid ", int " iscritical ", struct berval *" value ", int " dupval ", LDAPControl **" ctrlp ");" .LP .BI "LDAPControl *ldap_control_find( const char *" oid ", LDAPControl **" ctrls ", LDAPControl ***" nextctrlp ");" .LP .BI "LDAPControl *ldap_control_dup(LDAPControl *" ctrl ");" .LP .BI "LDAPControl **ldap_controls_dup(LDAPControl **" ctrls ");" .LP .BI "void ldap_control_free(LDAPControl *" ctrl ");" .LP .BI "void ldap_controls_free(LDAPControl **" ctrls ");" .SH DESCRIPTION These routines are used to manipulate structures used for LDAP controls. .BR ldap_control_create () creates a control with the specified .I OID using the contents of the .I value parameter for the control value, if any. The content of .I value is duplicated if .I dupval is non-zero. The .I iscritical parameter must be non-zero for a critical control. The created control is returned in the .I ctrlp parameter. The routine returns .B LDAP_SUCCESS on success or some other error code on failure. The content of .IR value , for supported control types, can be prepared using helpers provided by this implementation of libldap, usually in the form .BR "ldap_create_<control name>_control_value" (). Otherwise, it can be BER-encoded using the functionalities of liblber. .BR ldap_control_find () searches the NULL-terminated .I ctrls array for a control whose OID matches the .I oid parameter. The routine returns a pointer to the control if found, NULL otherwise. If the parameter .I nextctrlp is not NULL, on return it will point to the next control in the array, and can be passed to the .BR ldap_control_find () routine for subsequent calls, to find further occurrences of the same control type. The use of this function is discouraged; the recommended way of handling controls in responses consists in going through the array of controls, dealing with each of them in the returned order, since it could matter. .BR ldap_control_dup () duplicates an individual control structure, and .BR ldap_controls_dup () duplicates a NULL-terminated array of controls. .BR ldap_control_free () frees an individual control structure, and .BR ldap_controls_free () frees a NULL-terminated array of controls. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 85 stdin PK �c\�շY� � man/man3/ber_bvstr.3nu �[��� .lf 1 stdin .TH LBER_TYPES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_int_t, ber_uint_t, ber_len_t, ber_slen_t, ber_tag_t, struct berval, BerValue, BerVarray, BerElement, ber_bvfree, ber_bvecfree, ber_bvecadd, ber_bvarray_free, ber_bvarray_add, ber_bvdup, ber_dupbv, ber_bvstr, ber_bvstrdup, ber_str2bv, ber_alloc_t, ber_init, ber_init2, ber_free \- OpenLDAP LBER types and allocation functions .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .nf .ft B typedef impl_tag_t ber_tag_t; typedef impl_int_t ber_int_t; typedef impl_uint_t ber_uint_t; typedef impl_len_t ber_len_t; typedef impl_slen_t ber_slen_t; typedef struct berval { ber_len_t bv_len; char *bv_val; } BerValue, *BerVarray; typedef struct berelement BerElement; .ft .fi .LP .BI "void ber_bvfree(struct berval *" bv ");" .LP .BI "void ber_bvecfree(struct berval **" bvec ");" .LP .BI "void ber_bvecadd(struct berval ***" bvec ", struct berval *" bv ");" .LP .BI "void ber_bvarray_free(struct berval *" bvarray ");" .LP .BI "void ber_bvarray_add(BerVarray *" bvarray ", BerValue *" bv ");" .LP .BI "struct berval *ber_bvdup(const struct berval *" bv ");" .LP .BI "struct berval *ber_dupbv(const struct berval *" dst ", struct berval *" src ");" .LP .BI "struct berval *ber_bvstr(const char *" str ");" .LP .BI "struct berval *ber_bvstrdup(const char *" str ");" .LP .BI "struct berval *ber_str2bv(const char *" str ", ber_len_t " len ", int " dup ", struct berval *" bv ");" .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "BerElement *ber_init(struct berval *" bv ");" .LP .BI "void ber_init2(BerElement *" ber ", struct berval *" bv ", int " options ");" .LP .BI "void ber_free(BerElement *" ber ", int " freebuf ");" .SH DESCRIPTION .LP The following are the basic types and structures defined for use with the Lightweight BER library. .LP .B ber_int_t is a signed integer of at least 32 bits. It is commonly equivalent to .BR int . .B ber_uint_t is the unsigned variant of .BR ber_int_t . .LP .B ber_len_t is an unsigned integer of at least 32 bits used to represent a length. It is commonly equivalent to a .BR size_t . .B ber_slen_t is the signed variant to .BR ber_len_t . .LP .B ber_tag_t is an unsigned integer of at least 32 bits used to represent a BER tag. It is commonly equivalent to a .BR unsigned\ long . .LP The actual definitions of the integral impl_TYPE_t types are platform specific. .LP .BR BerValue , commonly used as .BR struct\ berval , is used to hold an arbitrary sequence of octets. .B bv_val points to .B bv_len octets. .B bv_val is not necessarily terminated by a NULL (zero) octet. .BR ber_bvfree () frees a BerValue, pointed to by \fIbv\fP, returned from this API. If \fIbv\fP is NULL, the routine does nothing. .LP .BR ber_bvecfree () frees an array of BerValues (and the array), pointed to by \fIbvec\fP, returned from this API. If \fIbvec\fP is NULL, the routine does nothing. .BR ber_bvecadd () appends the \fIbv\fP pointer to the \fIbvec\fP array. Space for the array is allocated as needed. The end of the array is marked by a NULL pointer. .LP .BR ber_bvarray_free () frees an array of BerValues (and the array), pointed to by \fIbvarray\fP, returned from this API. If \fIbvarray\fP is NULL, the routine does nothing. .BR ber_bvarray_add () appends the contents of the BerValue pointed to by \fIbv\fP to the \fIbvarray\fP array. Space for the new element is allocated as needed. The end of the array is marked by a BerValue with a NULL bv_val field. .LP .BR ber_bvdup () returns a copy of a BerValue. The routine returns NULL upon error (e.g. out of memory). The caller should use .BR ber_bvfree () to deallocate the resulting BerValue. .BR ber_dupbv () copies a BerValue from \fIsrc\fP to \fIdst\fP. If \fIdst\fP is NULL a new BerValue will be allocated to hold the copy. The routine returns NULL upon error, otherwise it returns a pointer to the copy. If \fIdst\fP is NULL the caller should use .BR ber_bvfree () to deallocate the resulting BerValue, otherwise .BR ber_memfree () should be used to deallocate the \fIdst->bv_val\fP. (The .BR ber_bvdup () function is internally implemented as ber_dupbv(NULL, bv). .BR ber_bvdup () is provided only for compatibility with an expired draft of the LDAP C API; .BR ber_dupbv () is the preferred interface.) .LP .BR ber_bvstr () returns a BerValue containing the string pointed to by \fIstr\fP. .BR ber_bvstrdup () returns a BerValue containing a copy of the string pointed to by \fIstr\fP. .BR ber_str2bv () returns a BerValue containing the string pointed to by \fIstr\fP, whose length may be optionally specified in \fIlen\fP. If \fIdup\fP is non-zero, the BerValue will contain a copy of \fIstr\fP. If \fIlen\fP is zero, the number of bytes to copy will be determined by .BR strlen (3), otherwise \fIlen\fP bytes will be copied. If \fIbv\fP is non-NULL, the result will be stored in the given BerValue, otherwise a new BerValue will be allocated to store the result. NOTE: Both .BR ber_bvstr () and .BR ber_bvstrdup () are implemented as macros using .BR ber_str2bv () in this version of the library. .LP .B BerElement is an opaque structure used to maintain state information used in encoding and decoding. .BR ber_alloc_t () is used to create an empty BerElement structure. If .B LBER_USE_DER is specified for the .I options parameter then data lengths for data written to the BerElement will be encoded in the minimal number of octets required, otherwise they will always be written as four byte values. .BR ber_init () creates a BerElement structure that is initialized with a copy of the data in its .I bv parameter. .BR ber_init2 () initializes an existing BerElement .I ber using the data in the .I bv parameter. The data is referenced directly, not copied. The .I options parameter is the same as for .BR ber_alloc_t (). .BR ber_free () frees a BerElement pointed to by \fIber\fP. If \fIber\fP is NULL, the routine does nothing. If \fIfreebuf\fP is zero, the internal buffer is not freed. .SH SEE ALSO .BR lber-encode (3), .BR lber-decode (3), .BR lber-memory (3) .LP .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 189 stdin PK �c\]�Ib� � man/man3/ldap_delete.3nu �[��� .lf 1 stdin .TH LDAP_DELETE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_delete, ldap_delete_s, ldap_delete_ext, ldap_delete_ext_s \- Perform an LDAP delete operation. .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_delete_s(ld, dn) .ft LDAP *ld; char *dn; .LP .ft B int ldap_delete(ld, dn) .ft LDAP *ld; char *dn; .LP .ft B int ldap_delete_ext(ld, dn, serverctrls, clientctrls, msgidp) .ft LDAP *ld; char *dn; LDAPControl **serverctrls, **clientctrls; int *msgidp; .LP .ft B int ldap_delete_ext_s(ld, dn, serverctrls, clientctrls) .ft LDAP *ld; char *dn; LDAPControl **serverctrls, **clientctrls; .SH DESCRIPTION The .B ldap_delete_s() routine is used to perform an LDAP delete operation synchronously. It takes \fIdn\fP, the DN of the entry to be deleted. It returns an LDAP error code, indicating the success or failure of the operation. .LP The .B ldap_delete() routine is used to perform an LDAP delete operation asynchronously. It takes the same parameters as .BR ldap_delete_s(), but returns the message id of the request it initiated. The result of the delete can be obtained by a subsequent call to .BR ldap_result (3). .LP The .B ldap_delete_ext() routine allows server and client controls to be specified to extend the delete request. This routine is asynchronous like ldap_delete(), but its return value is an LDAP error code. It stores the message id of the request in the integer pointed to by msgidp. .LP The .B ldap_delete_ext_s() routine is the synchronous version of .BR ldap_delete_ext(). It also returns an LDAP error code indicating success or failure of the operation. .SH ERRORS .B ldap_delete_s() returns an LDAP error code which can be interpreted by calling one of .BR ldap_perror (3) and friends. .B ldap_delete() returns \-1 if something went wrong initiating the request. It returns the non-negative message id of the request if things went ok. .LP .B ldap_delete_ext() and .B ldap_delete_ext_s() return some Non-zero value if something went wrong initiating the request, else return 0. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 90 stdin PK �c\�շY� � man/man3/ber_bvstrdup.3nu �[��� .lf 1 stdin .TH LBER_TYPES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_int_t, ber_uint_t, ber_len_t, ber_slen_t, ber_tag_t, struct berval, BerValue, BerVarray, BerElement, ber_bvfree, ber_bvecfree, ber_bvecadd, ber_bvarray_free, ber_bvarray_add, ber_bvdup, ber_dupbv, ber_bvstr, ber_bvstrdup, ber_str2bv, ber_alloc_t, ber_init, ber_init2, ber_free \- OpenLDAP LBER types and allocation functions .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .nf .ft B typedef impl_tag_t ber_tag_t; typedef impl_int_t ber_int_t; typedef impl_uint_t ber_uint_t; typedef impl_len_t ber_len_t; typedef impl_slen_t ber_slen_t; typedef struct berval { ber_len_t bv_len; char *bv_val; } BerValue, *BerVarray; typedef struct berelement BerElement; .ft .fi .LP .BI "void ber_bvfree(struct berval *" bv ");" .LP .BI "void ber_bvecfree(struct berval **" bvec ");" .LP .BI "void ber_bvecadd(struct berval ***" bvec ", struct berval *" bv ");" .LP .BI "void ber_bvarray_free(struct berval *" bvarray ");" .LP .BI "void ber_bvarray_add(BerVarray *" bvarray ", BerValue *" bv ");" .LP .BI "struct berval *ber_bvdup(const struct berval *" bv ");" .LP .BI "struct berval *ber_dupbv(const struct berval *" dst ", struct berval *" src ");" .LP .BI "struct berval *ber_bvstr(const char *" str ");" .LP .BI "struct berval *ber_bvstrdup(const char *" str ");" .LP .BI "struct berval *ber_str2bv(const char *" str ", ber_len_t " len ", int " dup ", struct berval *" bv ");" .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "BerElement *ber_init(struct berval *" bv ");" .LP .BI "void ber_init2(BerElement *" ber ", struct berval *" bv ", int " options ");" .LP .BI "void ber_free(BerElement *" ber ", int " freebuf ");" .SH DESCRIPTION .LP The following are the basic types and structures defined for use with the Lightweight BER library. .LP .B ber_int_t is a signed integer of at least 32 bits. It is commonly equivalent to .BR int . .B ber_uint_t is the unsigned variant of .BR ber_int_t . .LP .B ber_len_t is an unsigned integer of at least 32 bits used to represent a length. It is commonly equivalent to a .BR size_t . .B ber_slen_t is the signed variant to .BR ber_len_t . .LP .B ber_tag_t is an unsigned integer of at least 32 bits used to represent a BER tag. It is commonly equivalent to a .BR unsigned\ long . .LP The actual definitions of the integral impl_TYPE_t types are platform specific. .LP .BR BerValue , commonly used as .BR struct\ berval , is used to hold an arbitrary sequence of octets. .B bv_val points to .B bv_len octets. .B bv_val is not necessarily terminated by a NULL (zero) octet. .BR ber_bvfree () frees a BerValue, pointed to by \fIbv\fP, returned from this API. If \fIbv\fP is NULL, the routine does nothing. .LP .BR ber_bvecfree () frees an array of BerValues (and the array), pointed to by \fIbvec\fP, returned from this API. If \fIbvec\fP is NULL, the routine does nothing. .BR ber_bvecadd () appends the \fIbv\fP pointer to the \fIbvec\fP array. Space for the array is allocated as needed. The end of the array is marked by a NULL pointer. .LP .BR ber_bvarray_free () frees an array of BerValues (and the array), pointed to by \fIbvarray\fP, returned from this API. If \fIbvarray\fP is NULL, the routine does nothing. .BR ber_bvarray_add () appends the contents of the BerValue pointed to by \fIbv\fP to the \fIbvarray\fP array. Space for the new element is allocated as needed. The end of the array is marked by a BerValue with a NULL bv_val field. .LP .BR ber_bvdup () returns a copy of a BerValue. The routine returns NULL upon error (e.g. out of memory). The caller should use .BR ber_bvfree () to deallocate the resulting BerValue. .BR ber_dupbv () copies a BerValue from \fIsrc\fP to \fIdst\fP. If \fIdst\fP is NULL a new BerValue will be allocated to hold the copy. The routine returns NULL upon error, otherwise it returns a pointer to the copy. If \fIdst\fP is NULL the caller should use .BR ber_bvfree () to deallocate the resulting BerValue, otherwise .BR ber_memfree () should be used to deallocate the \fIdst->bv_val\fP. (The .BR ber_bvdup () function is internally implemented as ber_dupbv(NULL, bv). .BR ber_bvdup () is provided only for compatibility with an expired draft of the LDAP C API; .BR ber_dupbv () is the preferred interface.) .LP .BR ber_bvstr () returns a BerValue containing the string pointed to by \fIstr\fP. .BR ber_bvstrdup () returns a BerValue containing a copy of the string pointed to by \fIstr\fP. .BR ber_str2bv () returns a BerValue containing the string pointed to by \fIstr\fP, whose length may be optionally specified in \fIlen\fP. If \fIdup\fP is non-zero, the BerValue will contain a copy of \fIstr\fP. If \fIlen\fP is zero, the number of bytes to copy will be determined by .BR strlen (3), otherwise \fIlen\fP bytes will be copied. If \fIbv\fP is non-NULL, the result will be stored in the given BerValue, otherwise a new BerValue will be allocated to store the result. NOTE: Both .BR ber_bvstr () and .BR ber_bvstrdup () are implemented as macros using .BR ber_str2bv () in this version of the library. .LP .B BerElement is an opaque structure used to maintain state information used in encoding and decoding. .BR ber_alloc_t () is used to create an empty BerElement structure. If .B LBER_USE_DER is specified for the .I options parameter then data lengths for data written to the BerElement will be encoded in the minimal number of octets required, otherwise they will always be written as four byte values. .BR ber_init () creates a BerElement structure that is initialized with a copy of the data in its .I bv parameter. .BR ber_init2 () initializes an existing BerElement .I ber using the data in the .I bv parameter. The data is referenced directly, not copied. The .I options parameter is the same as for .BR ber_alloc_t (). .BR ber_free () frees a BerElement pointed to by \fIber\fP. If \fIber\fP is NULL, the routine does nothing. If \fIfreebuf\fP is zero, the internal buffer is not freed. .SH SEE ALSO .BR lber-encode (3), .BR lber-decode (3), .BR lber-memory (3) .LP .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 189 stdin PK �c\� �q q man/man3/ldap_dcedn2dn.3nu �[��� .lf 1 stdin .TH LDAP_GET_DN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn \- LDAP DN handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ) .LP .ft B int ldap_str2dn( const char *str, LDAPDN *dn, unsigned flags ) .LP .ft B void ldap_dnfree( LDAPDN dn ) .LP .ft B int ldap_dn2str( LDAPDN dn, char **str, unsigned flags ) .LP .ft B char **ldap_explode_dn( const char *dn, int notypes ) .LP .ft B char **ldap_explode_rdn( const char *rdn, int notypes ) .LP .ft B char *ldap_dn2ufn( const char * dn ) .LP .ft B char *ldap_dn2dcedn( const char * dn ) .LP .ft B char *ldap_dcedn2dn( const char * dn ) .LP .ft B char *ldap_dn2ad_canonical( const char * dn ) .SH DESCRIPTION These routines allow LDAP entry names (Distinguished Names, or DNs) to be obtained, parsed, converted to a user-friendly form, and tested. A DN has the form described in RFC 4414 "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names". .LP The .B ldap_get_dn() routine takes an \fIentry\fP as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3) and returns a copy of the entry's DN. Space for the DN will be obtained dynamically and should be freed by the caller using .BR ldap_memfree (3). .LP .B ldap_str2dn() parses a string representation of a distinguished name contained in .B str into its components, which are stored in .B dn as .B ldap_ava structures, arranged in .B LDAPAVA, .B LDAPRDN, and .B LDAPDN terms. Space for .B dn will be obtained dynamically and should be freed by the caller using .BR ldap_dnfree (3). The .B LDAPDN is defined as: .nf .ft B typedef struct ldap_ava { struct berval la_attr; struct berval la_value; unsigned la_flags; } LDAPAVA; typedef LDAPAVA** LDAPRDN; typedef LDAPRDN* LDAPDN; .ft .fi The attribute types and the attribute values are not normalized. The .B la_flags can be either .B LDAP_AVA_STRING or .B LDAP_AVA_BINARY, the latter meaning that the value is BER/DER encoded and thus must be represented as, quoting from RFC 4514, " ... an octothorpe character ('#' ASCII 35) followed by the hexadecimal representation of each of the bytes of the BER encoding of the X.500 AttributeValue." The .B flags parameter to .B ldap_str2dn() can be .LP .nf LDAP_DN_FORMAT_LDAPV3 LDAP_DN_FORMAT_LDAPV2 LDAP_DN_FORMAT_DCE .fi which defines what DN syntax is expected (according to RFC 4514, RFC 1779 and DCE, respectively). The format can be \fIOR\fPed to the flags .LP .nf LDAP_DN_P_NO_SPACES LDAP_DN_P_NO_SPACE_AFTER_RDN ... LDAP_DN_PEDANTIC .fi The latter is a shortcut for all the previous limitations. .LP .B LDAP_DN_P_NO_SPACES does not allow extra spaces in the dn; the default is to silently eliminate spaces around AVA separators ('='), RDN component separators ('+' for LDAPv3/LDAPv2 or ',' for DCE) and RDN separators (',' LDAPv3/LDAPv2 or '/' for DCE). .LP .B LDAP_DN_P_NO_SPACE_AFTER_RDN does not allow a single space after RDN separators. .LP .B ldap_dn2str() performs the inverse operation, yielding in .B str a string representation of .B dn. It allows the same values for .B flags as .B ldap_str2dn(), plus .LP .nf LDAP_DN_FORMAT_UFN LDAP_DN_FORMAT_AD_CANONICAL .fi for user-friendly naming (RFC 1781) and AD canonical. .LP The following routines are viewed as deprecated in favor of .B ldap_str2dn() and .BR ldap_dn2str(). They are provided to support legacy applications. .LP The .B ldap_explode_dn() routine takes a DN as returned by .B ldap_get_dn() and breaks it up into its component parts. Each part is known as a Relative Distinguished Name, or RDN. .B ldap_explode_dn() returns a NULL-terminated array, each component of which contains an RDN from the DN. The \fInotypes\fP parameter is used to request that only the RDN values be returned, not their types. For example, the DN "cn=Bob, c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob", "US", NULL }, depending on whether notypes was 0 or 1, respectively. Assertion values in RDN strings may included escaped characters. The result can be freed by calling .BR ldap_value_free (3). .LP Similarly, the .B ldap_explode_rdn() routine takes an RDN as returned by .B ldap_explode_dn(dn,0) and breaks it up into its "type=value" component parts (or just "value", if the \fInotypes\fP parameter is set). Note the value is not unescaped. The result can be freed by calling .BR ldap_value_free (3). .LP .B ldap_dn2ufn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a more user-friendly form, stripping off all type names. See "Using the Directory to Achieve User Friendly Naming" (RFC 1781) for more details on the UFN format. Due to the ambiguous nature of the format, it is generally only used for display purposes. The space for the UFN returned is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .LP .B ldap_dn2dcedn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a DCE-style DN, e.g. a string with most-significant to least significant rdns separated by slashes ('/'); rdn components are separated by commas (','). Only printable chars (e.g. LDAPv2 printable string) are allowed, at least in this implementation. .B ldap_dcedn2dn() performs the opposite operation. .B ldap_dn2ad_canonical() turns a DN into a AD canonical name, which is basically a DCE dn with attribute types omitted. The trailing domain, if present, is turned in a DNS-like domain. The space for the returned value is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .SH ERRORS If an error occurs in .BR ldap_get_dn() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .BR ldap_explode_dn() , .BR ldap_explode_rdn() , .B ldap_dn2ufn(), .B ldap_dn2dcedn(), .B ldap_dcedn2dn(), and .B ldap_dn2ad_canonical() will return NULL with .BR errno (3) set appropriately in case of trouble. .SH NOTES These routines dynamically allocate memory that the caller must free. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_first_entry (3), .BR ldap_memfree (3), .BR ldap_value_free (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 247 stdin PK �c\'�t!� � man/man3/ldap_tls_inplace.3nu �[��� .lf 1 stdin .TH LDAP_TLS 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_start_tls, ldap_start_tls_s, ldap_tls_inplace, ldap_install_tls \- LDAP TLS initialization routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "int ldap_start_tls(LDAP *" ld ");" .LP .BI "int ldap_start_tls_s(LDAP *" ld ", LDAPControl **" serverctrls ", LDAPControl **" clientctrls ");" .LP .BI "int ldap_tls_inplace(LDAP *" ld ");" .LP .BI "int ldap_install_tls(LDAP *" ld ");" .SH DESCRIPTION These routines are used to initiate TLS processing on an LDAP session. .BR ldap_start_tls_s () sends a StartTLS request to a server, waits for the reply, and then installs TLS handlers on the session if the request succeeded. The routine returns .B LDAP_SUCCESS if everything succeeded, otherwise it returns an LDAP error code. .BR ldap_start_tls () sends a StartTLS request to a server and does nothing else. It returns .B LDAP_SUCCESS if the request was sent successfully. .BR ldap_tls_inplace () returns 1 if TLS handlers have been installed on the specified session, 0 otherwise. .BR ldap_install_tls () installs the TLS handlers on the given session. It returns .B LDAP_LOCAL_ERROR if TLS is already installed. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 42 stdin PK �c\���0 0 man/man3/ldap_memvfree.3nu �[��� .lf 1 stdin .TH LDAP_MEMORY 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_memfree, ldap_memvfree, ldap_memalloc, ldap_memcalloc, ldap_memrealloc, ldap_strdup \- LDAP memory allocation routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "void ldap_memfree(void *" p ");" .LP .BI "void ldap_memvfree(void **" v ");" .LP .BI "void *ldap_memalloc(ber_len_t " s ");" .LP .BI "void *ldap_memcalloc(ber_len_t " n ", ber_len_t " s ");" .LP .BI "void *ldap_memrealloc(void *" p ", ber_len_t " s ");" .LP .BI "char *ldap_strdup(LDAP_CONST char *" p ");" .SH DESCRIPTION These routines are used to allocate/deallocate memory used/returned by the LDAP library. .BR ldap_memalloc (), .BR ldap_memcalloc (), .BR ldap_memrealloc (), and .BR ldap_memfree () are used exactly like the standard .BR malloc (3), .BR calloc (3), .BR realloc (3), and .BR free (3) routines, respectively. The .BR ldap_memvfree () routine is used to free a dynamically allocated array of pointers to arbitrary dynamically allocated objects. The .BR ldap_strdup () routine is used exactly like the standard .BR strdup (3) routine. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 51 stdin PK �c\g�d"# "# man/man3/ldap_syntax_free.3nu �[��� .lf 1 stdin .TH LDAP_SCHEMA 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 2000-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_str2syntax, ldap_syntax2str, ldap_syntax2name, ldap_syntax_free, ldap_str2matchingrule, ldap_matchingrule2str, ldap_matchingrule2name, ldap_matchingrule_free, ldap_str2attributetype, ldap_attributetype2str, ldap_attributetype2name, ldap_attributetype_free, ldap_str2objectclass, ldap_objectclass2str, ldap_objectclass2name, ldap_objectclass_free, ldap_scherr2str \- Schema definition handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> #include <ldap_schema.h> .LP .ft B LDAPSyntax * ldap_str2syntax(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_syntax2str(syn) .ft const LDAPSyntax * syn; .LP .ft B const char * ldap_syntax2name(syn) .ft LDAPSyntax * syn; .LP .ft B ldap_syntax_free(syn) .ft LDAPSyntax * syn; .LP .ft B LDAPMatchingRule * ldap_str2matchingrule(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_matchingrule2str(mr); .ft const LDAPMatchingRule * mr; .LP .ft B const char * ldap_matchingrule2name(mr) .ft LDAPMatchingRule * mr; .LP .ft B ldap_matchingrule_free(mr) .ft LDAPMatchingRule * mr; .LP .ft B LDAPAttributeType * ldap_str2attributetype(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_attributetype2str(at) .ft const LDAPAttributeType * at; .LP .ft B const char * ldap_attributetype2name(at) .ft LDAPAttributeType * at; .LP .ft B ldap_attributetype_free(at) .ft LDAPAttributeType * at; .LP .ft B LDAPObjectClass * ldap_str2objectclass(s, code, errp, flags) .ft const char * s; int * code; const char ** errp; const int flags; .LP .ft B char * ldap_objectclass2str(oc) .ft const LDAPObjectClass * oc; .LP .ft B const char * ldap_objectclass2name(oc) .ft LDAPObjectClass * oc; .LP .ft B ldap_objectclass_free(oc) .ft LDAPObjectClass * oc; .LP .ft B char * ldap_scherr2str(code) .ft int code; .SH DESCRIPTION These routines are used to parse schema definitions in the syntax defined in RFC 4512 into structs and handle these structs. These routines handle four kinds of definitions: syntaxes, matching rules, attribute types and object classes. For each definition kind, four routines are provided. .LP .B ldap_str2xxx() takes a definition in RFC 4512 format in argument .IR s as a NUL-terminated string and returns, if possible, a pointer to a newly allocated struct of the appropriate kind. The caller is responsible for freeing the struct by calling .B ldap_xxx_free() when not needed any longer. The routine returns NULL if some problem happened. In this case, the integer pointed at by argument .IR code will receive an error code (see below the description of .B ldap_scherr2str() for an explanation of the values) and a pointer to a NUL-terminated string will be placed where requested by argument .IR errp , indicating where in argument .IR s the error happened, so it must not be freed by the caller. Argument .IR flags is a bit mask of parsing options controlling the relaxation of the syntax recognized. The following values are defined: .TP .B LDAP_SCHEMA_ALLOW_NONE strict parsing according to RFC 4512. .TP .B LDAP_SCHEMA_ALLOW_NO_OID permit definitions that do not contain an initial OID. .TP .B LDAP_SCHEMA_ALLOW_QUOTED permit quotes around some items that should not have them. .TP .B LDAP_SCHEMA_ALLOW_DESCR permit a .B descr instead of a numeric OID in places where the syntax expect the latter. .TP .B LDAP_SCHEMA_ALLOW_DESCR_PREFIX permit that the initial numeric OID contains a prefix in .B descr format. .TP .B LDAP_SCHEMA_ALLOW_ALL be very liberal, include all options. .LP The structures returned are as follows: .sp .RS .nf .ne 7 .ta 8n 16n 32n typedef struct ldap_schema_extension_item { char *lsei_name; /* Extension name */ char **lsei_values; /* Extension values */ } LDAPSchemaExtensionItem; typedef struct ldap_syntax { char *syn_oid; /* OID */ char **syn_names; /* Names */ char *syn_desc; /* Description */ LDAPSchemaExtensionItem **syn_extensions; /* Extension */ } LDAPSyntax; typedef struct ldap_matchingrule { char *mr_oid; /* OID */ char **mr_names; /* Names */ char *mr_desc; /* Description */ int mr_obsolete; /* Is obsolete? */ char *mr_syntax_oid; /* Syntax of asserted values */ LDAPSchemaExtensionItem **mr_extensions; /* Extensions */ } LDAPMatchingRule; typedef struct ldap_attributetype { char *at_oid; /* OID */ char **at_names; /* Names */ char *at_desc; /* Description */ int at_obsolete; /* Is obsolete? */ char *at_sup_oid; /* OID of superior type */ char *at_equality_oid; /* OID of equality matching rule */ char *at_ordering_oid; /* OID of ordering matching rule */ char *at_substr_oid; /* OID of substrings matching rule */ char *at_syntax_oid; /* OID of syntax of values */ int at_syntax_len; /* Suggested minimum maximum length */ int at_single_value; /* Is single-valued? */ int at_collective; /* Is collective? */ int at_no_user_mod; /* Are changes forbidden through LDAP? */ int at_usage; /* Usage, see below */ LDAPSchemaExtensionItem **at_extensions; /* Extensions */ } LDAPAttributeType; typedef struct ldap_objectclass { char *oc_oid; /* OID */ char **oc_names; /* Names */ char *oc_desc; /* Description */ int oc_obsolete; /* Is obsolete? */ char **oc_sup_oids; /* OIDs of superior classes */ int oc_kind; /* Kind, see below */ char **oc_at_oids_must; /* OIDs of required attribute types */ char **oc_at_oids_may; /* OIDs of optional attribute types */ LDAPSchemaExtensionItem **oc_extensions; /* Extensions */ } LDAPObjectClass; .ta .fi .RE .PP Some integer fields (those described with a question mark) have a truth value, for these fields the possible values are: .TP .B LDAP_SCHEMA_NO The answer to the question is no. .TP .B LDAP_SCHEMA_YES The answer to the question is yes. .LP For attribute types, the following usages are possible: .TP .B LDAP_SCHEMA_USER_APPLICATIONS the attribute type is non-operational. .TP .B LDAP_SCHEMA_DIRECTORY_OPERATION the attribute type is operational and is pertinent to the directory itself, i.e. it has the same value on all servers that master the entry containing this attribute type. .TP .B LDAP_SCHEMA_DISTRIBUTED_OPERATION the attribute type is operational and is pertinent to replication, shadowing or other distributed directory aspect. TBC. .TP .B LDAP_SCHEMA_DSA_OPERATION the attribute type is operational and is pertinent to the directory server itself, i.e. it may have different values for the same entry when retrieved from different servers that master the entry. .LP Object classes can be of three kinds: .TP .B LDAP_SCHEMA_ABSTRACT the object class is abstract, i.e. there cannot be entries of this class alone. .TP .B LDAP_SCHEMA_STRUCTURAL the object class is structural, i.e. it describes the main role of the entry. On some servers, once the entry is created the set of structural object classes assigned cannot be changed: none of those present can be removed and none other can be added. .TP .B LDAP_SCHEMA_AUXILIARY the object class is auxiliary, i.e. it is intended to go with other, structural, object classes. These can be added or removed at any time if attribute types are added or removed at the same time as needed by the set of object classes resulting from the operation. .LP Routines .B ldap_xxx2name() return a canonical name for the definition. .LP Routines .B ldap_xxx2str() return a string representation in the format described by RFC 4512 of the struct passed in the argument. The string is a newly allocated string that must be freed by the caller. These routines may return NULL if no memory can be allocated for the string. .LP .B ldap_scherr2str() returns a NUL-terminated string with a text description of the error found. This is a pointer to a static area, so it must not be freed by the caller. The argument .IR code comes from one of the parsing routines and can adopt the following values: .TP .B LDAP_SCHERR_OUTOFMEM Out of memory. .TP .B LDAP_SCHERR_UNEXPTOKEN Unexpected token. .TP .B LDAP_SCHERR_NOLEFTPAREN Missing opening parenthesis. .TP .B LDAP_SCHERR_NORIGHTPAREN Missing closing parenthesis. .TP .B LDAP_SCHERR_NODIGIT Expecting digit. .TP .B LDAP_SCHERR_BADNAME Expecting a name. .TP .B LDAP_SCHERR_BADDESC Bad description. .TP .B LDAP_SCHERR_BADSUP Bad superiors. .TP .B LDAP_SCHERR_DUPOPT Duplicate option. .TP .B LDAP_SCHERR_EMPTY Unexpected end of data. .SH SEE ALSO .BR ldap (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 321 stdin PK �c\��A man/man3/ldap_modrdn2.3nu �[��� .lf 1 stdin .TH LDAP_MODRDN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_modrdn, ldap_modrdn_s, ldap_modrdn2, ldap_modrdn2_s \- Perform an LDAP modify RDN operation .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_modrdn(ld, dn, newrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; .LP .ft B .LP .ft B int ldap_modrdn_s(ld, dn, newrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; .LP .ft B int ldap_modrdn2(ld, dn, newrdn, deleteoldrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; int deleteoldrdn; .LP .ft B int ldap_modrdn2_s(ld, dn, newrdn, deleteoldrdn) .ft LDAP \(**ld; char \(**dn, \(**newrdn; int deleteoldrdn; .SH DESCRIPTION The .B ldap_modrdn() and .B ldap_modrdn_s() routines perform an LDAP modify RDN operation. They both take \fIdn\fP, the DN of the entry whose RDN is to be changed, and \fInewrdn\fP, the new RDN to give the entry. The old RDN of the entry is never kept as an attribute of the entry. .B ldap_modrdn() is asynchronous, returning the message id of the operation it initiates. .B ldap_modrdn_s() is synchronous, returning the LDAP error code indicating the success or failure of the operation. Use of these routines is deprecated. Use the versions described below instead. .LP The .B ldap_modrdn2() and .B ldap_modrdn2_s() routines also perform an LDAP modify RDN operation, taking the same parameters as above. In addition, they both take the \fIdeleteoldrdn\fP parameter which is used as a boolean value to indicate whether the old RDN values should be deleted from the entry or not. .SH ERRORS The synchronous (_s) versions of these routines return an LDAP error code, either LDAP_SUCCESS or an error if there was trouble. The asynchronous versions return \-1 in case of trouble, setting the .B ld_errno field of \fIld\fP. See .BR ldap_error (3) for more details. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 82 stdin PK �c\��MK$ K$ man/man3/ber_alloc_t.3nu �[��� .lf 1 stdin .TH LBER_ENCODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_alloc_t, ber_flush, ber_flush2, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring, ber_put_string, ber_put_null, ber_put_boolean, ber_put_bitstring, ber_start_seq, ber_start_set, ber_put_seq, ber_put_set \- OpenLDAP LBER simplified Basic Encoding Rules library routines for encoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_flush2(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_printf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "int ber_put_int(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_enum(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_ostring(BerElement *" ber ", const char *" str ", ber_len_t " len ", ber_tag_t " tag ");" .LP .BI "int ber_put_string(BerElement *" ber ", const char *" str ", ber_tag_t " tag ");" .LP .BI "int ber_put_null(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_boolean(BerElement *" ber ", ber_int_t " bool ", ber_tag_t " tag ");" .LP .BI "int ber_put_bitstring(BerElement *" ber ", const char *" str ", ber_len_t " blen ", ber_tag_t " tag ");" .LP .BI "int ber_start_seq(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_start_set(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_seq(BerElement *" ber ");" .LP .BI "int ber_put_set(BerElement *" ber ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the encoding routines in the lber library. See .BR lber-decode (3) for details on the corresponding decoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_alloc_t () to allocate a BER element for encoding, .BR ber_printf () to do the actual encoding, and .BR ber_flush2 () to actually write the element. The other routines are provided for those applications that need more control than .BR ber_printf () provides. In general, these routines return the length of the element encoded, or \-1 if an error occurred. .LP The .BR ber_alloc_t () routine is used to allocate a new BER element. It should be called with an argument of LBER_USE_DER. .LP The .BR ber_flush2 () routine is used to actually write the element to a socket (or file) descriptor, once it has been fully encoded (using .BR ber_printf () and friends). See .BR lber-sockbuf (3) for more details on the Sockbuf implementation of the \fIsb\fP parameter. If the \fIfreeit\fP parameter is non-zero, the supplied \fIber\fP will be freed. If \fILBER_FLUSH_FREE_ON_SUCCESS\fP is used, the \fIber\fP is only freed when successfully flushed, otherwise it is left intact; if \fILBER_FLUSH_FREE_ON_ERROR\fP is used, the \fIber\fP is only freed when an error occurs, otherwise it is left intact; if \fILBER_FLUSH_FREE_ALWAYS\fP is used, the \fIber\fP is freed anyway. This function differs from the original .BR ber_flush (3) function, whose behavior corresponds to that indicated for \fILBER_FLUSH_FREE_ON_SUCCESS\fP. Note that in the future, the behavior of .BR ber_flush (3) with \fIfreeit\fP non-zero might change into that of .BR ber_flush2 (3) with \fIfreeit\fP set to \fILBER_FLUSH_FREE_ALWAYS\fP. .LP The .BR ber_printf () routine is used to encode a BER element in much the same way that .BR sprintf (3) works. One important difference, though, is that some state information is kept with the \fIber\fP parameter so that multiple calls can be made to .BR ber_printf () to append things to the end of the BER element. .BR Ber_printf () writes to \fIber\fP, a pointer to a BerElement such as returned by .BR ber_alloc_t (). It interprets and formats its arguments according to the format string \fIfmt\fP. The format string can contain the following characters: .RS .LP .TP 3 .B b Boolean. An ber_int_t parameter should be supplied. A boolean element is output. .TP .B e Enumeration. An ber_int_t parameter should be supplied. An enumeration element is output. .TP .B i Integer. An ber_int_t parameter should be supplied. An integer element is output. .TP .B B Bitstring. A char * pointer to the start of the bitstring is supplied, followed by the number of bits in the bitstring. A bitstring element is output. .TP .B n Null. No parameter is required. A null element is output. .TP .B o Octet string. A char * is supplied, followed by the length of the string pointed to. An octet string element is output. .TP .B O Octet string. A struct berval * is supplied. An octet string element is output. .TP .B s Octet string. A null-terminated string is supplied. An octet string element is output, not including the trailing NULL octet. .TP .B t Tag. A ber_tag_t specifying the tag to give the next element is provided. This works across calls. .TP .B v Several octet strings. A null-terminated array of char *'s is supplied. Note that a construct like '{v}' is required to get an actual SEQUENCE OF octet strings. .TP .B V Several octet strings. A null-terminated array of struct berval *'s is supplied. Note that a construct like '{V}' is required to get an actual SEQUENCE OF octet strings. .TP .B W Several octet strings. An array of struct berval's is supplied. The array is terminated by a struct berval with a NULL bv_val. Note that a construct like '{W}' is required to get an actual SEQUENCE OF octet strings. .TP .B { Begin sequence. No parameter is required. .TP .B } End sequence. No parameter is required. .TP .B [ Begin set. No parameter is required. .TP .B ] End set. No parameter is required. .RE .LP The .BR ber_put_int () routine writes the integer element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_enum () routine writes the enumeration element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_boolean () routine writes the boolean value given by \fIbool\fP to the BER element. .LP The .BR ber_put_bitstring () routine writes \fIblen\fP bits starting at \fIstr\fP as a bitstring value to the given BER element. Note that \fIblen\fP is the length \fIin bits\fP of the bitstring. .LP The .BR ber_put_ostring () routine writes \fIlen\fP bytes starting at \fIstr\fP to the BER element as an octet string. .LP The .BR ber_put_string () routine writes the null-terminated string (minus the terminating '\0') to the BER element as an octet string. .LP The .BR ber_put_null () routine writes a NULL element to the BER element. .LP The .BR ber_start_seq () routine is used to start a sequence in the BER element. The .BR ber_start_set () routine works similarly. The end of the sequence or set is marked by the nearest matching call to .BR ber_put_seq () or .BR ber_put_set (), respectively. .SH EXAMPLES Assuming the following variable declarations, and that the variables have been assigned appropriately, an lber encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP can be achieved like so: .LP .nf int rc; ber_int_t scope, ali, size, time, attrsonly; char *dn, **attrs; BerElement *ber; /* ... fill in values ... */ ber = ber_alloc_t( LBER_USE_DER ); if ( ber == NULL ) { /* error */ } rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali, size, time, attrsonly, attrs ); if( rc == \-1 ) { /* error */ } else { /* success */ } .fi .SH ERRORS If an error occurs during encoding, generally these routines return \-1. .LP .SH NOTES .LP The return values for all of these functions are declared in the <lber.h> header file. .SH SEE ALSO .BR lber-decode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 289 stdin PK �c\�� �. �. man/man3/ldap_bind.3nu �[��� .lf 1 stdin .TH LDAP_BIND 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_bind, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_sasl_bind, ldap_sasl_bind_s, ldap_sasl_interactive_bind_s, ldap_parse_sasl_bind_result, ldap_unbind, ldap_unbind_s, ldap_unbind_ext, ldap_unbind_ext_s, ldap_set_rebind_proc \- LDAP bind routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .B #include <ldap.h> .LP .BI "int ldap_bind(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_bind_s(LDAP *" ld ", const char *" who ", const char *" cred "," .RS .BI "int " method ");" .RE .LP .BI "int ldap_simple_bind(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_simple_bind_s(LDAP *" ld ", const char *" who ", const char *" passwd ");" .LP .BI "int ldap_sasl_bind(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], int *" msgidp ");" .RE .LP .BI "int ldap_sasl_bind_s(LDAP *" ld ", const char *" dn ", const char *" mechanism "," .RS .BI "struct berval *" cred ", LDAPControl *" sctrls "[]," .BI "LDAPControl *" cctrls "[], struct berval **" servercredp ");" .RE .LP .BI "int ldap_parse_sasl_bind_result(LDAP *" ld ", LDAPMessage *" res "," .RS .BI "struct berval **" servercredp ", int " freeit ");" .RE .LP .BI "int ldap_sasl_interactive_bind_s(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ");" .RE .LP .BI "int ldap_sasl_interactive_bind(LDAP *" ld ", const char *" dn "," .RS .BI "const char *" mechs "," .BI "LDAPControl *" sctrls "[], LDAPControl *" cctrls "[]," .BI "unsigned " flags ", LDAP_SASL_INTERACT_PROC *" interact "," .BI "void *" defaults ", LDAPMessage *" result "," .BI "const char **" rmechp ", int *" msgidp ");" .RE .LP .BI "int (LDAP_SASL_INTERACT_PROC)(LDAP *" ld ", unsigned " flags ", void *" defaults ", void *" sasl_interact ");" .LP .BI "int ldap_unbind(LDAP *" ld ");" .LP .BI "int ldap_unbind_s(LDAP *" ld ");" .LP .BI "int ldap_unbind_ext(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_unbind_ext_s(LDAP *" ld ", LDAPControl *" sctrls "[]," .RS .BI "LDAPControl *" cctrls "[]);" .RE .LP .BI "int ldap_set_rebind_proc (LDAP *" ld ", LDAP_REBIND_PROC *" ldap_proc ", void *" params ");" .LP .BI "int (LDAP_REBIND_PROC)(LDAP *" ld ", LDAP_CONST char *" url ", ber_tag_t " request ", ber_int_t " msgid ", void *" params ");" .SH DESCRIPTION .LP These routines provide various interfaces to the LDAP bind operation. After an association with an LDAP server is made using .BR ldap_init (3), an LDAP bind operation should be performed before other operations are attempted over the connection. An LDAP bind is required when using Version 2 of the LDAP protocol; it is optional for Version 3 but is usually needed due to security considerations. .LP There are three types of bind calls, ones providing simple authentication, ones providing SASL authentication, and general routines capable of doing either simple or SASL authentication. .LP .B SASL (Simple Authentication and Security Layer) can negotiate one of many different kinds of authentication. Both synchronous and asynchronous versions of each variant of the bind call are provided. All routines take \fIld\fP as their first parameter, as returned from .BR ldap_init (3). .SH SIMPLE AUTHENTICATION The simplest form of the bind call is .BR ldap_simple_bind_s() . It takes the DN to bind as in \fIwho\fP, and the userPassword associated with the entry in \fIpasswd\fP. It returns an LDAP error indication (see .BR ldap_error (3)). The .B ldap_simple_bind() call is asynchronous, taking the same parameters but only initiating the bind operation and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The .B ldap_sasl_bind_s() and asynchronous .B ldap_sasl_bind() functions can also be used to make a simple bind by using LDAP_SASL_SIMPLE as the SASL mechanism. .SH GENERAL AUTHENTICATION The .B ldap_bind() and .B ldap_bind_s() routines can be used when the authentication method to use needs to be selected at runtime. They both take an extra \fImethod\fP parameter selecting the authentication method to use. It should be set to LDAP_AUTH_SIMPLE to select simple authentication. .B ldap_bind() returns the message id of the request it initiates. .B ldap_bind_s() returns an LDAP error indication. .SH SASL AUTHENTICATION For SASL binds the server always ignores any provided DN, so the .I dn parameter should always be NULL. .BR ldap_sasl_bind_s () sends a single SASL bind request with the given SASL .I mechanism and credentials in the .I cred parameter. The format of the credentials depends on the particular SASL mechanism in use. For mechanisms that provide mutual authentication the server's credentials will be returned in the .I servercredp parameter. The routine returns an LDAP error indication (see .BR ldap_error (3)). The .BR ldap_sasl_bind () call is asynchronous, taking the same parameters but only sending the request and returning the message id of the request it sent. The result of the operation can be obtained by a subsequent call to .BR ldap_result (3). The result must be additionally parsed by .BR ldap_parse_sasl_bind_result () to obtain any server credentials sent from the server. .LP Many SASL mechanisms require multiple message exchanges to perform a complete authentication. Applications should generally use .BR ldap_sasl_interactive_bind_s () rather than calling the basic .BR ldap_sasl_bind () functions directly. The .I mechs parameter should contain a space-separated list of candidate mechanisms to use. If this parameter is NULL or empty the library will query the supportedSASLMechanisms attribute from the server's rootDSE for the list of SASL mechanisms the server supports. The .I flags parameter controls the interaction used to retrieve any necessary SASL authentication parameters and should be one of: .TP LDAP_SASL_AUTOMATIC use defaults if available, prompt otherwise .TP LDAP_SASL_INTERACTIVE always prompt .TP LDAP_SASL_QUIET never prompt .LP The .I interact function uses the provided .I defaults to handle requests from the SASL library for particular authentication parameters. There is no defined format for the .I defaults information; it is up to the caller to use whatever format is appropriate for the supplied .I interact function. The .I sasl_interact parameter comes from the underlying SASL library. When used with Cyrus SASL this is an array of .B sasl_interact_t structures. The Cyrus SASL library will prompt for a variety of inputs, including: .TP SASL_CB_GETREALM the realm for the authentication attempt .TP SASL_CB_AUTHNAME the username to authenticate .TP SASL_CB_PASS the password for the provided username .TP SASL_CB_USER the username to use for proxy authorization .TP SASL_CB_NOECHOPROMPT generic prompt for input with input echoing disabled .TP SASL_CB_ECHOPROMPT generic prompt for input with input echoing enabled .TP SASL_CB_LIST_END indicates the end of the array of prompts .LP See the Cyrus SASL documentation for more details. .LP Applications which need to manage connections asynchronously may use .BR ldap_sasl_interactive_bind () instead of the synchronous version. A valid mechs parameter must be supplied, otherwise the library will be forced to query the server for a list of supported mechanisms, and this query will be performed synchronously. The other parameters are the same as for the synchronous function, with three additional parameters. The actual SASL mechanism that was used, and the message ID for use with .BR ldap_result () will be returned in rmechp and msgidp, respectively. The value in rmechp must not be modified by the caller and must be passed back on each subsequent call. The message obtained from .BR ldap_result () must be passed in the result parameter. This parameter must be NULL when initiating a new Bind. The caller must free the result message after each call using .BR ldap_msgfree (). The .BR ldap_sasl_interactive_bind () function returns an LDAP result code. If the code is LDAP_SASL_BIND_IN_PROGRESS then the Bind is not complete yet, and this function must be called again with the next result from the server. .SH REBINDING .LP The .B ldap_set_rebind_proc function() sets the process to use for binding when an operation returns a referral. This function is used when an application needs to bind to another server in order to follow a referral or search continuation reference. .LP The function takes \fIld\fP, the \fIrebind\fP function, and the \fIparams\fP, the arbitrary data like state information which the client might need to properly rebind. The LDAP_OPT_REFERRALS option in the \fIld\fP must be set to ON for the libraries to use the rebind function. Use the .BR ldap_set_option function to set the value. .LP The rebind function parameters are as follows: .LP The \fIld\fP parameter must be used by the application when binding to the referred server if the application wants the libraries to follow the referral. .LP The \fIurl\fP parameter points to the URL referral string received from the LDAP server. The LDAP application can use the .BR ldap_url_parse (3) function to parse the string into its components. .LP The \fIrequest\fP parameter specifies the type of request that generated the referral. .LP The \fImsgid\fP parameter specifies the message ID of the request generating the referral. .LP The \fIparams\fP parameter is the same value as passed originally to the .BR ldap_set_rebind_proc () function. .LP The LDAP libraries set all the parameters when they call the rebind function. The application should not attempt to free either the ld or the url structures in the rebind function. .LP The application must supply to the rebind function the required authentication information such as, user name, password, and certificates. The rebind function must use a synchronous bind method. .SH UNBINDING The .B ldap_unbind() call is used to unbind from the directory, terminate the current association, and free the resources contained in the \fIld\fP structure. Once it is called, the connection to the LDAP server is closed, and the \fIld\fP structure is invalid. The .B ldap_unbind_s() call is just another name for .BR ldap_unbind() ; both of these calls are synchronous in nature. .LP The .B ldap_unbind_ext() and .B ldap_unbind_ext_s() allows the operations to specify controls. .SH ERRORS Asynchronous routines will return \-1 in case of error, setting the \fIld_errno\fP parameter of the \fIld\fP structure. Synchronous routines return whatever \fIld_errno\fP is set to. See .BR ldap_error (3) for more information. .SH NOTES If an anonymous bind is sufficient for the application, the rebind process need not be provided. The LDAP libraries with the LDAP_OPT_REFERRALS option set to ON (default value) will automatically follow referrals using an anonymous bind. .LP If the application needs stronger authentication than an anonymous bind, you need to provide a rebind process for that authentication method. The bind method must be synchronous. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_open (3), .BR ldap_set_option (3), .BR ldap_url_parse (3) .B RFC 4422 (http://www.rfc-editor.org), .B Cyrus SASL (http://asg.web.cmu.edu/sasl/) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 335 stdin PK �c\ ��� � man/man3/ldap_parse_result.3nu �[��� .lf 1 stdin .TH LDAP_PARSE_RESULT 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_parse_result \- Parsing results .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B int ldap_parse_result( LDAP *ld, LDAPMessage *result, int *errcodep, char **matcheddnp, char **errmsgp, char ***referralsp, LDAPControl ***serverctrlsp, int freeit ) .LP .ft B int ldap_parse_sasl_bind_result( LDAP *ld, LDAPMessage *result, struct berval **servercredp, int freeit ) .LP .ft B int ldap_parse_extended_result( LDAP *ld, LDAPMessage *result, char **retoidp, struct berval **retdatap, int freeit ) .SH DESCRIPTION .LP These routines are used to extract information from a result message. They will operate on the first result message in a chain of search results (skipping past other message types). They take the \fIresult\fP as returned by a call to .BR ldap_result (3), .BR ldap_search_s (3) or .BR ldap_search_st (3). In addition to .BR ldap_parse_result() , the routines .B ldap_parse_sasl_bind_result() and .B ldap_parse_extended_result() are used to get all the result information from SASL bind and extended operations. .LP The \fIerrcodep\fP parameter will be filled in with the result code from the result message. .LP The server might supply a matched DN string in the message indicating how much of a name in a request was recognized. The \fImatcheddnp\fP parameter will be filled in with this string if supplied, else it will be NULL. If a string is returned, it should be freed using .BR ldap_memfree (3). .LP The \fIerrmsgp\fP parameter will be filled in with the error message field from the parsed message. This string should be freed using .BR ldap_memfree (3). .LP The \fIreferralsp\fP parameter will be filled in with an allocated array of referral strings from the parsed message. This array should be freed using .BR ldap_memvfree (3). If no referrals were returned, \fI*referralsp\fP is set to NULL. .LP The \fIserverctrlsp\fP parameter will be filled in with an allocated array of controls copied from the parsed message. The array should be freed using .BR ldap_controls_free (3). If no controls were returned, \fI*serverctrlsp\fP is set to NULL. .LP The \fIfreeit\fP parameter determines whether the parsed message is freed or not after the extraction. Any non-zero value will make it free the message. The .BR ldap_msgfree (3) routine can also be used to free the message later. .LP For SASL bind results, the \fIservercredp\fP parameter will be filled in with an allocated berval structure containing the credentials from the server if present. The structure should be freed using .BR ber_bvfree (3). .LP For extended results, the \fIretoidp\fP parameter will be filled in with the dotted-OID text representation of the name of the extended operation response. The string should be freed using .BR ldap_memfree (3). If no OID was returned, \fI*retoidp\fP is set to NULL. .LP For extended results, the \fIretdatap\fP parameter will be filled in with a pointer to a berval structure containing the data from the extended operation response. The structure should be freed using .BR ber_bvfree (3). If no data were returned, \fI*retdatap\fP is set to NULL. .LP For all the above result parameters, NULL values can be used in calls in order to ignore certain fields. .SH ERRORS Upon success LDAP_SUCCESS is returned. Otherwise the values of the result parameters are undefined. .SH SEE ALSO .BR ldap (3), .BR ldap_result (3), .BR ldap_search (3), .BR ldap_memfree (3), .BR ldap_memvfree (3), .BR ldap_get_values (3), .BR ldap_controls_free (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 108 stdin PK �c\�5^#v1 v1 man/man3/ber_first_element.3nu �[��� .lf 1 stdin .TH LBER_DECODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");" .LP .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");" .LP .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");" .LP .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");" .LP .BI "ber_tag_t ber_get_null(BerElement *" ber ");" .LP .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");" .LP .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");" .LP .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");" .LP .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the decoding routines in the lber library. See .BR lber-encode (3) for details on the corresponding encoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_get_next () to get the next BER element and .BR ber_scanf () to do the actual decoding. In some cases, .BR ber_peek_tag () may also need to be called in normal usage. The other routines are provided for those applications that need more control than .BR ber_scanf () provides. In general, these routines return the tag of the element decoded, or LBER_ERROR if an error occurred. .LP The .BR ber_get_next () routine is used to read the next BER element from the given Sockbuf, \fIsb\fP. It strips off and returns the leading tag, strips off and returns the length of the entire element in \fIlen\fP, and sets up \fIber\fP for subsequent calls to .BR ber_scanf () et al to decode the element. See .BR lber-sockbuf (3) for details of the Sockbuf implementation of the \fIsb\fP parameter. .LP The .BR ber_scanf () routine is used to decode a BER element in much the same way that .BR scanf (3) works. It reads from \fIber\fP, a pointer to a BerElement such as returned by .BR ber_get_next (), interprets the bytes according to the format string \fIfmt\fP, and stores the results in its additional arguments. 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. .RS .LP .TP 3 .B a Octet string. A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter. The caller should free the returned string using .BR ber_memfree (). .TP .B A Octet string. A variant of "\fBa\fP". A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter, unless a zero-length string would result; in that case, the arg is set to NULL. The caller should free the returned string using .BR ber_memfree (). .TP .B s Octet string. A char * buffer should be supplied, followed by a pointer to a ber_len_t initialized to the size of the buffer. Upon return, the null-terminated octet string is put into the buffer, and the ber_len_t is set to the actual size of the octet string. .TP .B O Octet string. A struct ber_val ** should be supplied, which upon return points to a dynamically allocated struct berval containing the octet string and its length. The caller should free the returned structure using .BR ber_bvfree (). .TP .B o Octet string. A struct ber_val * should be supplied, which upon return contains the dynamically allocated octet string and its length. The caller should free the returned octet string using .BR ber_memfree (). .TP .B m Octet string. A struct ber_val * should be supplied, which upon return contains the octet string and its length. The string resides in memory assigned to the BerElement, and must not be freed by the caller. .TP .B b Boolean. A pointer to a ber_int_t should be supplied. .TP .B e Enumeration. A pointer to a ber_int_t should be supplied. .TP .B i Integer. A pointer to a ber_int_t should be supplied. .TP .B B Bitstring. A char ** should be supplied which will point to the dynamically allocated bits, followed by a ber_len_t *, which will point to the length (in bits) of the bitstring returned. .TP .B n Null. No parameter is required. The element is simply skipped if it is recognized. .TP .B v Sequence of octet strings. A char *** should be supplied, which upon return points to a dynamically allocated null-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty. The caller should free the returned array and octet strings using .BR ber_memvfree (). .TP .B V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon return points to a dynamically allocated null-terminated array of struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvecfree (). .TP .B W Sequence of octet strings with lengths. A BerVarray * should be supplied, which upon return points to a dynamically allocated array of struct berval's containing the octet strings and their lengths. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvarray_free (). .TP .B M Sequence of octet strings with lengths. This is a generalized form of the previous three formats. A void ** (ptr) should be supplied, followed by a ber_len_t * (len) and a ber_len_t (off). Upon return (ptr) will point to a dynamically allocated array whose elements are all of size (*len). A struct berval will be filled starting at offset (off) in each element. The strings in each struct berval reside in memory assigned to the BerElement and must not be freed by the caller. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The number of elements in the array is also stored in (*len) on return. The caller should free the returned array using .BR ber_memfree (). .TP .B l Length of the next element. A pointer to a ber_len_t should be supplied. .TP .B t Tag of the next element. A pointer to a ber_tag_t should be supplied. .TP .B T Skip element and return its tag. A pointer to a ber_tag_t should be supplied. .TP .B x Skip element. The next element is skipped. .TP .B { Begin sequence. No parameter is required. The initial sequence tag and length are skipped. .TP .B } End sequence. No parameter is required and no action is taken. .TP .B [ Begin set. No parameter is required. The initial set tag and length are skipped. .TP .B ] End set. No parameter is required and no action is taken. .RE .LP The .BR ber_get_int () routine tries to interpret the next element as an integer, returning the result in \fInum\fP. The tag of whatever it finds is returned on success, LBER_ERROR (\-1) on failure. .LP The .BR ber_get_stringb () routine is used to read an octet string into a preallocated buffer. The \fIlen\fP parameter should be initialized to the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte. .LP The .BR ber_get_stringa () routine is used to dynamically allocate space into which an octet string is read. The caller should free the returned string using .BR ber_memfree(). .LP The .BR ber_get_stringal () routine is used to dynamically allocate space into which an octet string and its length are read. It takes a struct berval **, and returns the result in this parameter. The caller should free the returned structure using .BR ber_bvfree(). .LP The .BR ber_get_stringbv () routine is used to read an octet string and its length into the provided struct berval *. If the \fIalloc\fP parameter is zero, the string will reside in memory assigned to the BerElement, and must not be freed by the caller. If the \fIalloc\fP parameter is non-zero, the string will be copied into dynamically allocated space which should be returned using .BR ber_memfree (). .LP The .BR ber_get_null () routine is used to read a NULL element. It returns the tag of the element it skips over. .LP The .BR ber_get_boolean () routine is used to read a boolean value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_enum () routine is used to read a enumeration value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_bitstringa () routine is used to read a bitstring value. It takes a char ** which will hold the dynamically allocated bits, followed by an ber_len_t *, which will point to the length (in bits) of the bitstring returned. The caller should free the returned string using .BR ber_memfree (). .LP The .BR ber_first_element () routine is used to return the tag and length of the first element in a set or sequence. It also returns in \fIcookie\fP a magic cookie parameter that should be passed to subsequent calls to ber_next_element(), which returns similar information. .SH EXAMPLES Assume the variable \fIber\fP contains a lightweight BER encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP The element can be decoded using .BR ber_scanf () as follows. .LP .nf ber_int_t scope, deref, size, time, attrsonly; char *dn, **attrs; ber_tag_t tag; tag = ber_scanf( ber, "{aeeiib{v}}", &dn, &scope, &deref, &size, &time, &attrsonly, &attrs ); if( tag == LBER_ERROR ) { /* error */ } else { /* success */ } ber_memfree( dn ); ber_memvfree( attrs ); .fi .SH ERRORS If an error occurs during decoding, generally these routines return LBER_ERROR ((ber_tag_t)\-1). .LP .SH NOTES .LP The return values for all of these functions are declared in the .B <lber.h> header file. Some routines may dynamically allocate memory which must be freed by the caller using supplied deallocation routines. .SH SEE ALSO .BR lber-encode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 358 stdin PK �c\��MK$ K$ man/man3/lber-encode.3nu �[��� .lf 1 stdin .TH LBER_ENCODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_alloc_t, ber_flush, ber_flush2, ber_printf, ber_put_int, ber_put_enum, ber_put_ostring, ber_put_string, ber_put_null, ber_put_boolean, ber_put_bitstring, ber_start_seq, ber_start_set, ber_put_seq, ber_put_set \- OpenLDAP LBER simplified Basic Encoding Rules library routines for encoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "int ber_flush(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_flush2(Sockbuf *" sb ", BerElement *" ber ", int " freeit ");" .LP .BI "int ber_printf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "int ber_put_int(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_enum(BerElement *" ber ", ber_int_t " num ", ber_tag_t " tag ");" .LP .BI "int ber_put_ostring(BerElement *" ber ", const char *" str ", ber_len_t " len ", ber_tag_t " tag ");" .LP .BI "int ber_put_string(BerElement *" ber ", const char *" str ", ber_tag_t " tag ");" .LP .BI "int ber_put_null(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_boolean(BerElement *" ber ", ber_int_t " bool ", ber_tag_t " tag ");" .LP .BI "int ber_put_bitstring(BerElement *" ber ", const char *" str ", ber_len_t " blen ", ber_tag_t " tag ");" .LP .BI "int ber_start_seq(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_start_set(BerElement *" ber ", ber_tag_t " tag ");" .LP .BI "int ber_put_seq(BerElement *" ber ");" .LP .BI "int ber_put_set(BerElement *" ber ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the encoding routines in the lber library. See .BR lber-decode (3) for details on the corresponding decoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_alloc_t () to allocate a BER element for encoding, .BR ber_printf () to do the actual encoding, and .BR ber_flush2 () to actually write the element. The other routines are provided for those applications that need more control than .BR ber_printf () provides. In general, these routines return the length of the element encoded, or \-1 if an error occurred. .LP The .BR ber_alloc_t () routine is used to allocate a new BER element. It should be called with an argument of LBER_USE_DER. .LP The .BR ber_flush2 () routine is used to actually write the element to a socket (or file) descriptor, once it has been fully encoded (using .BR ber_printf () and friends). See .BR lber-sockbuf (3) for more details on the Sockbuf implementation of the \fIsb\fP parameter. If the \fIfreeit\fP parameter is non-zero, the supplied \fIber\fP will be freed. If \fILBER_FLUSH_FREE_ON_SUCCESS\fP is used, the \fIber\fP is only freed when successfully flushed, otherwise it is left intact; if \fILBER_FLUSH_FREE_ON_ERROR\fP is used, the \fIber\fP is only freed when an error occurs, otherwise it is left intact; if \fILBER_FLUSH_FREE_ALWAYS\fP is used, the \fIber\fP is freed anyway. This function differs from the original .BR ber_flush (3) function, whose behavior corresponds to that indicated for \fILBER_FLUSH_FREE_ON_SUCCESS\fP. Note that in the future, the behavior of .BR ber_flush (3) with \fIfreeit\fP non-zero might change into that of .BR ber_flush2 (3) with \fIfreeit\fP set to \fILBER_FLUSH_FREE_ALWAYS\fP. .LP The .BR ber_printf () routine is used to encode a BER element in much the same way that .BR sprintf (3) works. One important difference, though, is that some state information is kept with the \fIber\fP parameter so that multiple calls can be made to .BR ber_printf () to append things to the end of the BER element. .BR Ber_printf () writes to \fIber\fP, a pointer to a BerElement such as returned by .BR ber_alloc_t (). It interprets and formats its arguments according to the format string \fIfmt\fP. The format string can contain the following characters: .RS .LP .TP 3 .B b Boolean. An ber_int_t parameter should be supplied. A boolean element is output. .TP .B e Enumeration. An ber_int_t parameter should be supplied. An enumeration element is output. .TP .B i Integer. An ber_int_t parameter should be supplied. An integer element is output. .TP .B B Bitstring. A char * pointer to the start of the bitstring is supplied, followed by the number of bits in the bitstring. A bitstring element is output. .TP .B n Null. No parameter is required. A null element is output. .TP .B o Octet string. A char * is supplied, followed by the length of the string pointed to. An octet string element is output. .TP .B O Octet string. A struct berval * is supplied. An octet string element is output. .TP .B s Octet string. A null-terminated string is supplied. An octet string element is output, not including the trailing NULL octet. .TP .B t Tag. A ber_tag_t specifying the tag to give the next element is provided. This works across calls. .TP .B v Several octet strings. A null-terminated array of char *'s is supplied. Note that a construct like '{v}' is required to get an actual SEQUENCE OF octet strings. .TP .B V Several octet strings. A null-terminated array of struct berval *'s is supplied. Note that a construct like '{V}' is required to get an actual SEQUENCE OF octet strings. .TP .B W Several octet strings. An array of struct berval's is supplied. The array is terminated by a struct berval with a NULL bv_val. Note that a construct like '{W}' is required to get an actual SEQUENCE OF octet strings. .TP .B { Begin sequence. No parameter is required. .TP .B } End sequence. No parameter is required. .TP .B [ Begin set. No parameter is required. .TP .B ] End set. No parameter is required. .RE .LP The .BR ber_put_int () routine writes the integer element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_enum () routine writes the enumeration element \fInum\fP to the BER element \fIber\fP. .LP The .BR ber_put_boolean () routine writes the boolean value given by \fIbool\fP to the BER element. .LP The .BR ber_put_bitstring () routine writes \fIblen\fP bits starting at \fIstr\fP as a bitstring value to the given BER element. Note that \fIblen\fP is the length \fIin bits\fP of the bitstring. .LP The .BR ber_put_ostring () routine writes \fIlen\fP bytes starting at \fIstr\fP to the BER element as an octet string. .LP The .BR ber_put_string () routine writes the null-terminated string (minus the terminating '\0') to the BER element as an octet string. .LP The .BR ber_put_null () routine writes a NULL element to the BER element. .LP The .BR ber_start_seq () routine is used to start a sequence in the BER element. The .BR ber_start_set () routine works similarly. The end of the sequence or set is marked by the nearest matching call to .BR ber_put_seq () or .BR ber_put_set (), respectively. .SH EXAMPLES Assuming the following variable declarations, and that the variables have been assigned appropriately, an lber encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP can be achieved like so: .LP .nf int rc; ber_int_t scope, ali, size, time, attrsonly; char *dn, **attrs; BerElement *ber; /* ... fill in values ... */ ber = ber_alloc_t( LBER_USE_DER ); if ( ber == NULL ) { /* error */ } rc = ber_printf( ber, "{siiiib{v}}", dn, scope, ali, size, time, attrsonly, attrs ); if( rc == \-1 ) { /* error */ } else { /* success */ } .fi .SH ERRORS If an error occurs during encoding, generally these routines return \-1. .LP .SH NOTES .LP The return values for all of these functions are declared in the <lber.h> header file. .SH SEE ALSO .BR lber-decode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 289 stdin PK �c\� �q q man/man3/ldap_explode_rdn.3nu �[��� .lf 1 stdin .TH LDAP_GET_DN 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_get_dn, ldap_explode_dn, ldap_explode_rdn, ldap_dn2ufn \- LDAP DN handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_get_dn( LDAP *ld, LDAPMessage *entry ) .LP .ft B int ldap_str2dn( const char *str, LDAPDN *dn, unsigned flags ) .LP .ft B void ldap_dnfree( LDAPDN dn ) .LP .ft B int ldap_dn2str( LDAPDN dn, char **str, unsigned flags ) .LP .ft B char **ldap_explode_dn( const char *dn, int notypes ) .LP .ft B char **ldap_explode_rdn( const char *rdn, int notypes ) .LP .ft B char *ldap_dn2ufn( const char * dn ) .LP .ft B char *ldap_dn2dcedn( const char * dn ) .LP .ft B char *ldap_dcedn2dn( const char * dn ) .LP .ft B char *ldap_dn2ad_canonical( const char * dn ) .SH DESCRIPTION These routines allow LDAP entry names (Distinguished Names, or DNs) to be obtained, parsed, converted to a user-friendly form, and tested. A DN has the form described in RFC 4414 "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names". .LP The .B ldap_get_dn() routine takes an \fIentry\fP as returned by .BR ldap_first_entry (3) or .BR ldap_next_entry (3) and returns a copy of the entry's DN. Space for the DN will be obtained dynamically and should be freed by the caller using .BR ldap_memfree (3). .LP .B ldap_str2dn() parses a string representation of a distinguished name contained in .B str into its components, which are stored in .B dn as .B ldap_ava structures, arranged in .B LDAPAVA, .B LDAPRDN, and .B LDAPDN terms. Space for .B dn will be obtained dynamically and should be freed by the caller using .BR ldap_dnfree (3). The .B LDAPDN is defined as: .nf .ft B typedef struct ldap_ava { struct berval la_attr; struct berval la_value; unsigned la_flags; } LDAPAVA; typedef LDAPAVA** LDAPRDN; typedef LDAPRDN* LDAPDN; .ft .fi The attribute types and the attribute values are not normalized. The .B la_flags can be either .B LDAP_AVA_STRING or .B LDAP_AVA_BINARY, the latter meaning that the value is BER/DER encoded and thus must be represented as, quoting from RFC 4514, " ... an octothorpe character ('#' ASCII 35) followed by the hexadecimal representation of each of the bytes of the BER encoding of the X.500 AttributeValue." The .B flags parameter to .B ldap_str2dn() can be .LP .nf LDAP_DN_FORMAT_LDAPV3 LDAP_DN_FORMAT_LDAPV2 LDAP_DN_FORMAT_DCE .fi which defines what DN syntax is expected (according to RFC 4514, RFC 1779 and DCE, respectively). The format can be \fIOR\fPed to the flags .LP .nf LDAP_DN_P_NO_SPACES LDAP_DN_P_NO_SPACE_AFTER_RDN ... LDAP_DN_PEDANTIC .fi The latter is a shortcut for all the previous limitations. .LP .B LDAP_DN_P_NO_SPACES does not allow extra spaces in the dn; the default is to silently eliminate spaces around AVA separators ('='), RDN component separators ('+' for LDAPv3/LDAPv2 or ',' for DCE) and RDN separators (',' LDAPv3/LDAPv2 or '/' for DCE). .LP .B LDAP_DN_P_NO_SPACE_AFTER_RDN does not allow a single space after RDN separators. .LP .B ldap_dn2str() performs the inverse operation, yielding in .B str a string representation of .B dn. It allows the same values for .B flags as .B ldap_str2dn(), plus .LP .nf LDAP_DN_FORMAT_UFN LDAP_DN_FORMAT_AD_CANONICAL .fi for user-friendly naming (RFC 1781) and AD canonical. .LP The following routines are viewed as deprecated in favor of .B ldap_str2dn() and .BR ldap_dn2str(). They are provided to support legacy applications. .LP The .B ldap_explode_dn() routine takes a DN as returned by .B ldap_get_dn() and breaks it up into its component parts. Each part is known as a Relative Distinguished Name, or RDN. .B ldap_explode_dn() returns a NULL-terminated array, each component of which contains an RDN from the DN. The \fInotypes\fP parameter is used to request that only the RDN values be returned, not their types. For example, the DN "cn=Bob, c=US" would return as either { "cn=Bob", "c=US", NULL } or { "Bob", "US", NULL }, depending on whether notypes was 0 or 1, respectively. Assertion values in RDN strings may included escaped characters. The result can be freed by calling .BR ldap_value_free (3). .LP Similarly, the .B ldap_explode_rdn() routine takes an RDN as returned by .B ldap_explode_dn(dn,0) and breaks it up into its "type=value" component parts (or just "value", if the \fInotypes\fP parameter is set). Note the value is not unescaped. The result can be freed by calling .BR ldap_value_free (3). .LP .B ldap_dn2ufn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a more user-friendly form, stripping off all type names. See "Using the Directory to Achieve User Friendly Naming" (RFC 1781) for more details on the UFN format. Due to the ambiguous nature of the format, it is generally only used for display purposes. The space for the UFN returned is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .LP .B ldap_dn2dcedn() is used to turn a DN as returned by .BR ldap_get_dn (3) into a DCE-style DN, e.g. a string with most-significant to least significant rdns separated by slashes ('/'); rdn components are separated by commas (','). Only printable chars (e.g. LDAPv2 printable string) are allowed, at least in this implementation. .B ldap_dcedn2dn() performs the opposite operation. .B ldap_dn2ad_canonical() turns a DN into a AD canonical name, which is basically a DCE dn with attribute types omitted. The trailing domain, if present, is turned in a DNS-like domain. The space for the returned value is obtained dynamically and the user is responsible for freeing it via a call to .BR ldap_memfree (3). .SH ERRORS If an error occurs in .BR ldap_get_dn() , NULL is returned and the .B ld_errno field in the \fIld\fP parameter is set to indicate the error. See .BR ldap_error (3) for a description of possible error codes. .BR ldap_explode_dn() , .BR ldap_explode_rdn() , .B ldap_dn2ufn(), .B ldap_dn2dcedn(), .B ldap_dcedn2dn(), and .B ldap_dn2ad_canonical() will return NULL with .BR errno (3) set appropriately in case of trouble. .SH NOTES These routines dynamically allocate memory that the caller must free. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3), .BR ldap_first_entry (3), .BR ldap_memfree (3), .BR ldap_value_free (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 247 stdin PK �c\��1ܽ � man/man3/ldap_control_find.3nu �[��� .lf 1 stdin .TH LDAP_CONTROLS 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_control_create, ldap_control_find, ldap_control_dup, ldap_controls_dup, ldap_control_free, ldap_controls_free \- LDAP control manipulation routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .B #include <ldap.h> .LP .BI "int ldap_control_create(const char *" oid ", int " iscritical ", struct berval *" value ", int " dupval ", LDAPControl **" ctrlp ");" .LP .BI "LDAPControl *ldap_control_find( const char *" oid ", LDAPControl **" ctrls ", LDAPControl ***" nextctrlp ");" .LP .BI "LDAPControl *ldap_control_dup(LDAPControl *" ctrl ");" .LP .BI "LDAPControl **ldap_controls_dup(LDAPControl **" ctrls ");" .LP .BI "void ldap_control_free(LDAPControl *" ctrl ");" .LP .BI "void ldap_controls_free(LDAPControl **" ctrls ");" .SH DESCRIPTION These routines are used to manipulate structures used for LDAP controls. .BR ldap_control_create () creates a control with the specified .I OID using the contents of the .I value parameter for the control value, if any. The content of .I value is duplicated if .I dupval is non-zero. The .I iscritical parameter must be non-zero for a critical control. The created control is returned in the .I ctrlp parameter. The routine returns .B LDAP_SUCCESS on success or some other error code on failure. The content of .IR value , for supported control types, can be prepared using helpers provided by this implementation of libldap, usually in the form .BR "ldap_create_<control name>_control_value" (). Otherwise, it can be BER-encoded using the functionalities of liblber. .BR ldap_control_find () searches the NULL-terminated .I ctrls array for a control whose OID matches the .I oid parameter. The routine returns a pointer to the control if found, NULL otherwise. If the parameter .I nextctrlp is not NULL, on return it will point to the next control in the array, and can be passed to the .BR ldap_control_find () routine for subsequent calls, to find further occurrences of the same control type. The use of this function is discouraged; the recommended way of handling controls in responses consists in going through the array of controls, dealing with each of them in the returned order, since it could matter. .BR ldap_control_dup () duplicates an individual control structure, and .BR ldap_controls_dup () duplicates a NULL-terminated array of controls. .BR ldap_control_free () frees an individual control structure, and .BR ldap_controls_free () frees a NULL-terminated array of controls. .SH SEE ALSO .BR ldap (3), .BR ldap_error (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 85 stdin PK �c\�5^#v1 v1 man/man3/ber_skip_tag.3nu �[��� .lf 1 stdin .TH LBER_DECODE 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_get_next, ber_skip_tag, ber_peek_tag, ber_scanf, ber_get_int, ber_get_enum, ber_get_stringb, ber_get_stringa, ber_get_stringal, ber_get_stringbv, ber_get_null, ber_get_boolean, ber_get_bitstring, ber_first_element, ber_next_element \- OpenLDAP LBER simplified Basic Encoding Rules library routines for decoding .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .BI "ber_tag_t ber_get_next(Sockbuf *" sb ", ber_len_t *" len ", BerElement *" ber ");" .LP .BI "ber_tag_t ber_skip_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_peek_tag(BerElement *" ber ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_scanf(BerElement *" ber ", const char *" fmt ", ...);" .LP .BI "ber_tag_t ber_get_int(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_enum(BerElement *" ber ", ber_int_t *" num ");" .LP .BI "ber_tag_t ber_get_stringb(BerElement *" ber ", char *" buf ", ber_len_t *" len ");" .LP .BI "ber_tag_t ber_get_stringa(BerElement *" ber ", char **" buf ");" .LP .BI "ber_tag_t ber_get_stringal(BerElement *" ber ", struct berval **" bv ");" .LP .BI "ber_tag_t ber_get_stringbv(BerElement *" ber ", struct berval *" bv ", int " alloc ");" .LP .BI "ber_tag_t ber_get_null(BerElement *" ber ");" .LP .BI "ber_tag_t ber_get_boolean(BerElement *" ber ", ber_int_t *" bool ");" .LP .BI "ber_tag_t ber_get_bitstringa(BerElement *" ber ", char **" buf ", ber_len_t *" blen ");" .LP .BI "ber_tag_t ber_first_element(BerElement *" ber ", ber_len_t *" len ", char **" cookie ");" .LP .BI "ber_tag_t ber_next_element(BerElement *" ber ", ber_len_t *" len ", const char *" cookie ");" .SH DESCRIPTION .LP These routines provide a subroutine interface to a simplified implementation of the Basic Encoding Rules of ASN.1. The version of BER these routines support is the one defined for the LDAP protocol. The encoding rules are the same as BER, except that only definite form lengths are used, and bitstrings and octet strings are always encoded in primitive form. This man page describes the decoding routines in the lber library. See .BR lber-encode (3) for details on the corresponding encoding routines. Consult .BR lber-types (3) for information about types, allocators, and deallocators. .LP Normally, the only routines that need to be called by an application are .BR ber_get_next () to get the next BER element and .BR ber_scanf () to do the actual decoding. In some cases, .BR ber_peek_tag () may also need to be called in normal usage. The other routines are provided for those applications that need more control than .BR ber_scanf () provides. In general, these routines return the tag of the element decoded, or LBER_ERROR if an error occurred. .LP The .BR ber_get_next () routine is used to read the next BER element from the given Sockbuf, \fIsb\fP. It strips off and returns the leading tag, strips off and returns the length of the entire element in \fIlen\fP, and sets up \fIber\fP for subsequent calls to .BR ber_scanf () et al to decode the element. See .BR lber-sockbuf (3) for details of the Sockbuf implementation of the \fIsb\fP parameter. .LP The .BR ber_scanf () routine is used to decode a BER element in much the same way that .BR scanf (3) works. It reads from \fIber\fP, a pointer to a BerElement such as returned by .BR ber_get_next (), interprets the bytes according to the format string \fIfmt\fP, and stores the results in its additional arguments. 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. .RS .LP .TP 3 .B a Octet string. A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter. The caller should free the returned string using .BR ber_memfree (). .TP .B A Octet string. A variant of "\fBa\fP". A char ** should be supplied. Memory is allocated, filled with the contents of the octet string, null-terminated, and returned in the parameter, unless a zero-length string would result; in that case, the arg is set to NULL. The caller should free the returned string using .BR ber_memfree (). .TP .B s Octet string. A char * buffer should be supplied, followed by a pointer to a ber_len_t initialized to the size of the buffer. Upon return, the null-terminated octet string is put into the buffer, and the ber_len_t is set to the actual size of the octet string. .TP .B O Octet string. A struct ber_val ** should be supplied, which upon return points to a dynamically allocated struct berval containing the octet string and its length. The caller should free the returned structure using .BR ber_bvfree (). .TP .B o Octet string. A struct ber_val * should be supplied, which upon return contains the dynamically allocated octet string and its length. The caller should free the returned octet string using .BR ber_memfree (). .TP .B m Octet string. A struct ber_val * should be supplied, which upon return contains the octet string and its length. The string resides in memory assigned to the BerElement, and must not be freed by the caller. .TP .B b Boolean. A pointer to a ber_int_t should be supplied. .TP .B e Enumeration. A pointer to a ber_int_t should be supplied. .TP .B i Integer. A pointer to a ber_int_t should be supplied. .TP .B B Bitstring. A char ** should be supplied which will point to the dynamically allocated bits, followed by a ber_len_t *, which will point to the length (in bits) of the bitstring returned. .TP .B n Null. No parameter is required. The element is simply skipped if it is recognized. .TP .B v Sequence of octet strings. A char *** should be supplied, which upon return points to a dynamically allocated null-terminated array of char *'s containing the octet strings. NULL is returned if the sequence is empty. The caller should free the returned array and octet strings using .BR ber_memvfree (). .TP .B V Sequence of octet strings with lengths. A struct berval *** should be supplied, which upon return points to a dynamically allocated null-terminated array of struct berval *'s containing the octet strings and their lengths. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvecfree (). .TP .B W Sequence of octet strings with lengths. A BerVarray * should be supplied, which upon return points to a dynamically allocated array of struct berval's containing the octet strings and their lengths. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The caller should free the returned structures using .BR ber_bvarray_free (). .TP .B M Sequence of octet strings with lengths. This is a generalized form of the previous three formats. A void ** (ptr) should be supplied, followed by a ber_len_t * (len) and a ber_len_t (off). Upon return (ptr) will point to a dynamically allocated array whose elements are all of size (*len). A struct berval will be filled starting at offset (off) in each element. The strings in each struct berval reside in memory assigned to the BerElement and must not be freed by the caller. The array is terminated by a struct berval with a NULL bv_val string pointer. NULL is returned if the sequence is empty. The number of elements in the array is also stored in (*len) on return. The caller should free the returned array using .BR ber_memfree (). .TP .B l Length of the next element. A pointer to a ber_len_t should be supplied. .TP .B t Tag of the next element. A pointer to a ber_tag_t should be supplied. .TP .B T Skip element and return its tag. A pointer to a ber_tag_t should be supplied. .TP .B x Skip element. The next element is skipped. .TP .B { Begin sequence. No parameter is required. The initial sequence tag and length are skipped. .TP .B } End sequence. No parameter is required and no action is taken. .TP .B [ Begin set. No parameter is required. The initial set tag and length are skipped. .TP .B ] End set. No parameter is required and no action is taken. .RE .LP The .BR ber_get_int () routine tries to interpret the next element as an integer, returning the result in \fInum\fP. The tag of whatever it finds is returned on success, LBER_ERROR (\-1) on failure. .LP The .BR ber_get_stringb () routine is used to read an octet string into a preallocated buffer. The \fIlen\fP parameter should be initialized to the size of the buffer, and will contain the length of the octet string read upon return. The buffer should be big enough to take the octet string value plus a terminating NULL byte. .LP The .BR ber_get_stringa () routine is used to dynamically allocate space into which an octet string is read. The caller should free the returned string using .BR ber_memfree(). .LP The .BR ber_get_stringal () routine is used to dynamically allocate space into which an octet string and its length are read. It takes a struct berval **, and returns the result in this parameter. The caller should free the returned structure using .BR ber_bvfree(). .LP The .BR ber_get_stringbv () routine is used to read an octet string and its length into the provided struct berval *. If the \fIalloc\fP parameter is zero, the string will reside in memory assigned to the BerElement, and must not be freed by the caller. If the \fIalloc\fP parameter is non-zero, the string will be copied into dynamically allocated space which should be returned using .BR ber_memfree (). .LP The .BR ber_get_null () routine is used to read a NULL element. It returns the tag of the element it skips over. .LP The .BR ber_get_boolean () routine is used to read a boolean value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_enum () routine is used to read a enumeration value. It is called the same way that .BR ber_get_int () is called. .LP The .BR ber_get_bitstringa () routine is used to read a bitstring value. It takes a char ** which will hold the dynamically allocated bits, followed by an ber_len_t *, which will point to the length (in bits) of the bitstring returned. The caller should free the returned string using .BR ber_memfree (). .LP The .BR ber_first_element () routine is used to return the tag and length of the first element in a set or sequence. It also returns in \fIcookie\fP a magic cookie parameter that should be passed to subsequent calls to ber_next_element(), which returns similar information. .SH EXAMPLES Assume the variable \fIber\fP contains a lightweight BER encoding of the following ASN.1 object: .LP .nf AlmostASearchRequest := SEQUENCE { baseObject DistinguishedName, scope ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2) }, derefAliases ENUMERATED { neverDerefaliases (0), derefInSearching (1), derefFindingBaseObj (2), alwaysDerefAliases (3) }, sizelimit INTEGER (0 .. 65535), timelimit INTEGER (0 .. 65535), attrsOnly BOOLEAN, attributes SEQUENCE OF AttributeType } .fi .LP The element can be decoded using .BR ber_scanf () as follows. .LP .nf ber_int_t scope, deref, size, time, attrsonly; char *dn, **attrs; ber_tag_t tag; tag = ber_scanf( ber, "{aeeiib{v}}", &dn, &scope, &deref, &size, &time, &attrsonly, &attrs ); if( tag == LBER_ERROR ) { /* error */ } else { /* success */ } ber_memfree( dn ); ber_memvfree( attrs ); .fi .SH ERRORS If an error occurs during decoding, generally these routines return LBER_ERROR ((ber_tag_t)\-1). .LP .SH NOTES .LP The return values for all of these functions are declared in the .B <lber.h> header file. Some routines may dynamically allocate memory which must be freed by the caller using supplied deallocation routines. .SH SEE ALSO .BR lber-encode (3), .BR lber-memory (3), .BR lber-sockbuf (3), .BR lber-types (3) .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 358 stdin PK �c\�շY� � man/man3/lber-types.3nu �[��� .lf 1 stdin .TH LBER_TYPES 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ber_int_t, ber_uint_t, ber_len_t, ber_slen_t, ber_tag_t, struct berval, BerValue, BerVarray, BerElement, ber_bvfree, ber_bvecfree, ber_bvecadd, ber_bvarray_free, ber_bvarray_add, ber_bvdup, ber_dupbv, ber_bvstr, ber_bvstrdup, ber_str2bv, ber_alloc_t, ber_init, ber_init2, ber_free \- OpenLDAP LBER types and allocation functions .SH LIBRARY OpenLDAP LBER (liblber, \-llber) .SH SYNOPSIS .B #include <lber.h> .LP .nf .ft B typedef impl_tag_t ber_tag_t; typedef impl_int_t ber_int_t; typedef impl_uint_t ber_uint_t; typedef impl_len_t ber_len_t; typedef impl_slen_t ber_slen_t; typedef struct berval { ber_len_t bv_len; char *bv_val; } BerValue, *BerVarray; typedef struct berelement BerElement; .ft .fi .LP .BI "void ber_bvfree(struct berval *" bv ");" .LP .BI "void ber_bvecfree(struct berval **" bvec ");" .LP .BI "void ber_bvecadd(struct berval ***" bvec ", struct berval *" bv ");" .LP .BI "void ber_bvarray_free(struct berval *" bvarray ");" .LP .BI "void ber_bvarray_add(BerVarray *" bvarray ", BerValue *" bv ");" .LP .BI "struct berval *ber_bvdup(const struct berval *" bv ");" .LP .BI "struct berval *ber_dupbv(const struct berval *" dst ", struct berval *" src ");" .LP .BI "struct berval *ber_bvstr(const char *" str ");" .LP .BI "struct berval *ber_bvstrdup(const char *" str ");" .LP .BI "struct berval *ber_str2bv(const char *" str ", ber_len_t " len ", int " dup ", struct berval *" bv ");" .LP .BI "BerElement *ber_alloc_t(int " options ");" .LP .BI "BerElement *ber_init(struct berval *" bv ");" .LP .BI "void ber_init2(BerElement *" ber ", struct berval *" bv ", int " options ");" .LP .BI "void ber_free(BerElement *" ber ", int " freebuf ");" .SH DESCRIPTION .LP The following are the basic types and structures defined for use with the Lightweight BER library. .LP .B ber_int_t is a signed integer of at least 32 bits. It is commonly equivalent to .BR int . .B ber_uint_t is the unsigned variant of .BR ber_int_t . .LP .B ber_len_t is an unsigned integer of at least 32 bits used to represent a length. It is commonly equivalent to a .BR size_t . .B ber_slen_t is the signed variant to .BR ber_len_t . .LP .B ber_tag_t is an unsigned integer of at least 32 bits used to represent a BER tag. It is commonly equivalent to a .BR unsigned\ long . .LP The actual definitions of the integral impl_TYPE_t types are platform specific. .LP .BR BerValue , commonly used as .BR struct\ berval , is used to hold an arbitrary sequence of octets. .B bv_val points to .B bv_len octets. .B bv_val is not necessarily terminated by a NULL (zero) octet. .BR ber_bvfree () frees a BerValue, pointed to by \fIbv\fP, returned from this API. If \fIbv\fP is NULL, the routine does nothing. .LP .BR ber_bvecfree () frees an array of BerValues (and the array), pointed to by \fIbvec\fP, returned from this API. If \fIbvec\fP is NULL, the routine does nothing. .BR ber_bvecadd () appends the \fIbv\fP pointer to the \fIbvec\fP array. Space for the array is allocated as needed. The end of the array is marked by a NULL pointer. .LP .BR ber_bvarray_free () frees an array of BerValues (and the array), pointed to by \fIbvarray\fP, returned from this API. If \fIbvarray\fP is NULL, the routine does nothing. .BR ber_bvarray_add () appends the contents of the BerValue pointed to by \fIbv\fP to the \fIbvarray\fP array. Space for the new element is allocated as needed. The end of the array is marked by a BerValue with a NULL bv_val field. .LP .BR ber_bvdup () returns a copy of a BerValue. The routine returns NULL upon error (e.g. out of memory). The caller should use .BR ber_bvfree () to deallocate the resulting BerValue. .BR ber_dupbv () copies a BerValue from \fIsrc\fP to \fIdst\fP. If \fIdst\fP is NULL a new BerValue will be allocated to hold the copy. The routine returns NULL upon error, otherwise it returns a pointer to the copy. If \fIdst\fP is NULL the caller should use .BR ber_bvfree () to deallocate the resulting BerValue, otherwise .BR ber_memfree () should be used to deallocate the \fIdst->bv_val\fP. (The .BR ber_bvdup () function is internally implemented as ber_dupbv(NULL, bv). .BR ber_bvdup () is provided only for compatibility with an expired draft of the LDAP C API; .BR ber_dupbv () is the preferred interface.) .LP .BR ber_bvstr () returns a BerValue containing the string pointed to by \fIstr\fP. .BR ber_bvstrdup () returns a BerValue containing a copy of the string pointed to by \fIstr\fP. .BR ber_str2bv () returns a BerValue containing the string pointed to by \fIstr\fP, whose length may be optionally specified in \fIlen\fP. If \fIdup\fP is non-zero, the BerValue will contain a copy of \fIstr\fP. If \fIlen\fP is zero, the number of bytes to copy will be determined by .BR strlen (3), otherwise \fIlen\fP bytes will be copied. If \fIbv\fP is non-NULL, the result will be stored in the given BerValue, otherwise a new BerValue will be allocated to store the result. NOTE: Both .BR ber_bvstr () and .BR ber_bvstrdup () are implemented as macros using .BR ber_str2bv () in this version of the library. .LP .B BerElement is an opaque structure used to maintain state information used in encoding and decoding. .BR ber_alloc_t () is used to create an empty BerElement structure. If .B LBER_USE_DER is specified for the .I options parameter then data lengths for data written to the BerElement will be encoded in the minimal number of octets required, otherwise they will always be written as four byte values. .BR ber_init () creates a BerElement structure that is initialized with a copy of the data in its .I bv parameter. .BR ber_init2 () initializes an existing BerElement .I ber using the data in the .I bv parameter. The data is referenced directly, not copied. The .I options parameter is the same as for .BR ber_alloc_t (). .BR ber_free () frees a BerElement pointed to by \fIber\fP. If \fIber\fP is NULL, the routine does nothing. If \fIfreebuf\fP is zero, the internal buffer is not freed. .SH SEE ALSO .BR lber-encode (3), .BR lber-decode (3), .BR lber-memory (3) .LP .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 189 stdin PK �c\ m�&$ $ man/man3/ldap_errlist.3nu �[��� .lf 1 stdin .TH LDAP_ERROR 3 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap_perror, ld_errno, ldap_result2error, ldap_errlist, ldap_err2string \- LDAP protocol error handling routines .SH LIBRARY OpenLDAP LDAP (libldap, \-lldap) .SH SYNOPSIS .nf .ft B #include <ldap.h> .LP .ft B char *ldap_err2string( int \fIerr\fB ); .SH DESCRIPTION The .B ldap_err2string() routine provides short description of the various codes returned by routines in this library. The returned string is a pointer to a static area that should not be modified. These codes are either negative, indicating an API error code; positive, indicating an LDAP resultCode other than \'success' (0), or - zero, indicating both successful use of the API and the LDAP resultCode \'success' (0). The code associated with an LDAP session is accessible using .BR ldap_get_option (3) and .BR ldap_set_option (3) with the .B LDAP_OPT_RESULT_CODE option (previously called .BR LDAP_OPT_ERROR_NUMBER ). .SH PROTOCOL RESULT CODES This section provides a partial list of protocol codes recognized by the library. As LDAP is extensible, additional values may be returned. A complete listing of \fIregistered\fP LDAP result codes can be obtained from the \fIInternet Assigned Numbers Authority\fP <http://www.iana.org>. .LP .TP 20 .SM LDAP_SUCCESS The request was successful. .TP .SM LDAP_OPERATIONS_ERROR An operations error occurred. .TP .SM LDAP_PROTOCOL_ERROR A protocol violation was detected. .TP .SM LDAP_TIMELIMIT_EXCEEDED An LDAP time limit was exceeded. .TP .SM LDAP_SIZELIMIT_EXCEEDED An LDAP size limit was exceeded. .TP .SM LDAP_COMPARE_FALSE A compare operation returned false. .TP .SM LDAP_COMPARE_TRUE A compare operation returned true. .TP .SM LDAP_STRONG_AUTH_NOT_SUPPORTED The LDAP server does not support strong authentication. .TP .SM LDAP_STRONG_AUTH_REQUIRED Strong authentication is required for the operation. .TP .SM LDAP_PARTIAL_RESULTS Partial results only returned. .TP .SM LDAP_NO_SUCH_ATTRIBUTE The attribute type specified does not exist in the entry. .TP .SM LDAP_UNDEFINED_TYPE The attribute type specified is invalid. .TP .SM LDAP_INAPPROPRIATE_MATCHING Filter type not supported for the specified attribute. .TP .SM LDAP_CONSTRAINT_VIOLATION An attribute value specified violates some constraint (e.g., a postalAddress has too many lines, or a line that is too long). .TP .SM LDAP_TYPE_OR_VALUE_EXISTS An attribute type or attribute value specified already exists in the entry. .TP .SM LDAP_INVALID_SYNTAX An invalid attribute value was specified. .TP .SM LDAP_NO_SUCH_OBJECT The specified object does not exist in The Directory. .TP .SM LDAP_ALIAS_PROBLEM An alias in The Directory points to a nonexistent entry. .TP .SM LDAP_INVALID_DN_SYNTAX A syntactically invalid DN was specified. .TP .SM LDAP_IS_LEAF The object specified is a leaf. .TP .SM LDAP_ALIAS_DEREF_PROBLEM A problem was encountered when dereferencing an alias. .TP .SM LDAP_INAPPROPRIATE_AUTH Inappropriate authentication was specified (e.g., LDAP_AUTH_SIMPLE was specified and the entry does not have a userPassword attribute). .TP .SM LDAP_INVALID_CREDENTIALS Invalid credentials were presented (e.g., the wrong password). .TP .SM LDAP_INSUFFICIENT_ACCESS The user has insufficient access to perform the operation. .TP .SM LDAP_BUSY The DSA is busy. .TP .SM LDAP_UNAVAILABLE The DSA is unavailable. .TP .SM LDAP_UNWILLING_TO_PERFORM The DSA is unwilling to perform the operation. .TP .SM LDAP_LOOP_DETECT A loop was detected. .TP .SM LDAP_NAMING_VIOLATION A naming violation occurred. .TP .SM LDAP_OBJECT_CLASS_VIOLATION An object class violation occurred (e.g., a "must" attribute was missing from the entry). .TP .SM LDAP_NOT_ALLOWED_ON_NONLEAF The operation is not allowed on a nonleaf object. .TP .SM LDAP_NOT_ALLOWED_ON_RDN The operation is not allowed on an RDN. .TP .SM LDAP_ALREADY_EXISTS The entry already exists. .TP .SM LDAP_NO_OBJECT_CLASS_MODS Object class modifications are not allowed. .TP .SM LDAP_OTHER An unknown error occurred. .SH API ERROR CODES This section provides a complete list of API error codes recognized by the library. Note that LDAP_SUCCESS indicates success of an API call in addition to representing the return of the LDAP \'success' resultCode. .LP .TP 20 .SM LDAP_SERVER_DOWN The LDAP library can't contact the LDAP server. .TP .SM LDAP_LOCAL_ERROR Some local error occurred. This is usually a failed dynamic memory allocation. .TP .SM LDAP_ENCODING_ERROR An error was encountered encoding parameters to send to the LDAP server. .TP .SM LDAP_DECODING_ERROR An error was encountered decoding a result from the LDAP server. .TP .SM LDAP_TIMEOUT A timelimit was exceeded while waiting for a result. .TP .SM LDAP_AUTH_UNKNOWN The authentication method specified to ldap_bind() is not known. .TP .SM LDAP_FILTER_ERROR An invalid filter was supplied to ldap_search() (e.g., unbalanced parentheses). .TP .SM LDAP_PARAM_ERROR An ldap routine was called with a bad parameter. .TP .SM LDAP_NO_MEMORY An memory allocation (e.g., malloc(3) or other dynamic memory allocator) call failed in an ldap library routine. .TP .SM LDAP_USER_CANCELED Indicates the user cancelled the operation. .TP .SM LDAP_CONNECT_ERROR Indicates a connection problem. .TP .SM LDAP_NOT_SUPPORTED Indicates the routine was called in a manner not supported by the library. .TP .SM LDAP_CONTROL_NOT_FOUND Indicates the control provided is unknown to the client library. .TP .SM LDAP_NO_RESULTS_RETURNED Indicates no results returned. .TP .SM LDAP_MORE_RESULTS_TO_RETURN Indicates more results could be returned. .TP .SM LDAP_CLIENT_LOOP Indicates the library has detected a loop in its processing. .TP .SM LDAP_REFERRAL_LIMIT_EXCEEDED Indicates the referral limit has been exceeded. .SH DEPRECATED .lf 1 ./Deprecated Deprecated interfaces generally remain in the library. The macro LDAP_DEPRECATED can be defined to a non-zero value (e.g., -DLDAP_DEPRECATED=1) when compiling program designed to use deprecated interfaces. It is recommended that developers writing new programs, or updating old programs, avoid use of deprecated interfaces. Over time, it is expected that documentation (and, eventually, support) for deprecated interfaces to be eliminated. .lf 220 stdin .SH SEE ALSO .BR ldap (3), .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 225 stdin PK �c\�"l��B �B man/man5/ldap.conf.5nu �[��� .lf 1 stdin .TH LDAP.CONF 5 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldap.conf, .ldaprc \- LDAP configuration file/environment variables .SH SYNOPSIS /opt/alt/openldap11/etc/openldap/ldap.conf, ldaprc, .ldaprc, $LDAP<option-name> .SH DESCRIPTION If the environment variable \fBLDAPNOINIT\fP is defined, all defaulting is disabled. .LP The .I ldap.conf configuration file is used to set system-wide defaults to be applied when running .I ldap clients. .LP Users may create an optional configuration file, .I ldaprc or .IR .ldaprc , in their home directory which will be used to override the system-wide defaults file. The file .I ldaprc in the current working directory is also used. .LP .LP Additional configuration files can be specified using the \fBLDAPCONF\fP and \fBLDAPRC\fP environment variables. \fBLDAPCONF\fP may be set to the path of a configuration file. This path can be absolute or relative to the current working directory. The \fBLDAPRC\fP, if defined, should be the basename of a file in the current working directory or in the user's home directory. .LP Environmental variables may also be used to augment the file based defaults. The name of the variable is the option name with an added prefix of \fBLDAP\fP. For example, to define \fBBASE\fP via the environment, set the variable \fBLDAPBASE\fP to the desired value. .LP Some options are user-only. Such options are ignored if present in the .I ldap.conf (or file specified by .BR LDAPCONF ). .LP Thus the following files and variables are read, in order: .nf variable $LDAPNOINIT, and if that is not set: system file /opt/alt/openldap11/etc/openldap/ldap.conf, user files $HOME/ldaprc, $HOME/.ldaprc, ./ldaprc, system file $LDAPCONF, user files $HOME/$LDAPRC, $HOME/.$LDAPRC, ./$LDAPRC, variables $LDAP<uppercase option name>. .fi Settings late in the list override earlier ones. .SH SYNTAX The configuration options are case-insensitive; their value, on a case by case basis, may be case-sensitive. .LP Blank lines are ignored. .br Lines beginning with a hash mark (`#') are comments, and ignored. .LP Valid lines are made of an option's name (a sequence of non-blanks, conventionally written in uppercase, although not required), followed by a value. The value starts with the first non-blank character after the option's name, and terminates at the end of the line, or at the last sequence of blanks before the end of the line. The tokenization of the value, if any, is delegated to the handler(s) for that option, if any. Quoting values that contain blanks may be incorrect, as the quotes would become part of the value. For example, .nf # Wrong - erroneous quotes: URI "ldap:// ldaps://" # Right - space-separated list of URIs, without quotes: URI ldap:// ldaps:// # Right - DN syntax needs quoting for Example, Inc: BASE ou=IT staff,o="Example, Inc",c=US # or: BASE ou=IT staff,o=Example2C Inc,c=US # Wrong - comment on same line as option: DEREF never # Never follow aliases .fi .LP A line cannot be longer than LINE_MAX, which should be more than 2000 bytes on all platforms. There is no mechanism to split a long line on multiple lines, either for beautification or to overcome the above limit. .SH OPTIONS The different configuration options are: .TP .B URI <ldap[si]://[name[:port]] ...> Specifies the URI(s) of an LDAP server(s) to which the .I LDAP library should connect. The URI scheme may be any of .BR ldap , .B ldaps or .BR ldapi , which refer to LDAP over TCP, LDAP over SSL (TLS) and LDAP over IPC (UNIX domain sockets), respectively. Each server's name can be specified as a domain-style name or an IP address literal. Optionally, the server's name can followed by a ':' and the port number the LDAP server is listening on. If no port number is provided, the default port for the scheme is used (389 for ldap://, 636 for ldaps://). For LDAP over IPC, .B name is the name of the socket, and no .B port is required, nor allowed; note that directory separators must be URL-encoded, like any other characters that are special to URLs; so the socket /usr/local/var/ldapi must be specified as ldapi://%2Fusr%2Flocal%2Fvar%2Fldapi A space separated list of URIs may be provided. .TP .B BASE <base> Specifies the default base DN to use when performing ldap operations. The base must be specified as a Distinguished Name in LDAP format. .TP .B BINDDN <dn> Specifies the default bind DN to use when performing ldap operations. The bind DN must be specified as a Distinguished Name in LDAP format. .B This is a user-only option. .TP .B DEREF <when> Specifies how alias dereferencing is done when performing a search. The .B <when> can be specified as one of the following keywords: .RS .TP .B never Aliases are never dereferenced. This is the default. .TP .B searching Aliases are dereferenced in subordinates of the base object, but not in locating the base object of the search. .TP .B finding Aliases are only dereferenced when locating the base object of the search. .TP .B always Aliases are dereferenced both in searching and in locating the base object of the search. .RE .TP .TP .B HOST <name[:port] ...> Specifies the name(s) of an LDAP server(s) to which the .I LDAP library should connect. Each server's name can be specified as a domain-style name or an IP address and optionally followed by a ':' and the port number the ldap server is listening on. A space separated list of hosts may be provided. .B HOST is deprecated in favor of .BR URI . .TP .B NETWORK_TIMEOUT <integer> Specifies the timeout (in seconds) after which the poll(2)/select(2) following a connect(2) returns in case of no activity. .TP .B PORT <port> Specifies the default port used when connecting to LDAP servers(s). The port may be specified as a number. .B PORT is deprecated in favor of .BR URI. .TP .B REFERRALS <on/true/yes/off/false/no> Specifies if the client should automatically follow referrals returned by LDAP servers. The default is on. Note that the command line tools .BR ldapsearch (1) &co always override this option. .\" This should only be allowed via ldap_set_option(3) .\".TP .\".B RESTART <on/true/yes/off/false/no> .\"Determines whether the library should implicitly restart connections (FIXME). .TP .B SIZELIMIT <integer> Specifies a size limit (number of entries) to use when performing searches. The number should be a non-negative integer. \fISIZELIMIT\fP of zero (0) specifies a request for unlimited search size. Please note that the server may still apply any server-side limit on the amount of entries that can be returned by a search operation. .TP .B TIMELIMIT <integer> Specifies a time limit (in seconds) to use when performing searches. The number should be a non-negative integer. \fITIMELIMIT\fP of zero (0) specifies unlimited search time to be used. Please note that the server may still apply any server-side limit on the duration of a search operation. .B VERSION {2|3} Specifies what version of the LDAP protocol should be used. .TP .B TIMEOUT <integer> Specifies a timeout (in seconds) after which calls to synchronous LDAP APIs will abort if no response is received. Also used for any .BR ldap_result (3) calls where a NULL timeout parameter is supplied. .SH SASL OPTIONS If OpenLDAP is built with Simple Authentication and Security Layer support, there are more options you can specify. .TP .B SASL_MECH <mechanism> Specifies the SASL mechanism to use. .TP .B SASL_REALM <realm> Specifies the SASL realm. .TP .B SASL_AUTHCID <authcid> Specifies the authentication identity. .B This is a user-only option. .TP .B SASL_AUTHZID <authcid> Specifies the proxy authorization identity. .B This is a user-only option. .TP .B SASL_SECPROPS <properties> Specifies Cyrus SASL security properties. The .B <properties> can be specified as a comma-separated list of the following: .RS .TP .B none (without any other properties) causes the properties defaults ("noanonymous,noplain") to be cleared. .TP .B noplain disables mechanisms susceptible to simple passive attacks. .TP .B noactive disables mechanisms susceptible to active attacks. .TP .B nodict disables mechanisms susceptible to passive dictionary attacks. .TP .B noanonymous disables mechanisms which support anonymous login. .TP .B forwardsec requires forward secrecy between sessions. .TP .B passcred requires mechanisms which pass client credentials (and allows mechanisms which can pass credentials to do so). .TP .B minssf=<factor> specifies the minimum acceptable .I security strength factor as an integer approximating the effective key length used for encryption. 0 (zero) implies no protection, 1 implies integrity protection only, 56 allows DES or other weak ciphers, 112 allows triple DES and other strong ciphers, 128 allows RC4, Blowfish and other modern strong ciphers. The default is 0. .TP .B maxssf=<factor> specifies the maximum acceptable .I security strength factor as an integer (see .B minssf description). The default is .BR INT_MAX . .TP .B maxbufsize=<factor> specifies the maximum security layer receive buffer size allowed. 0 disables security layers. The default is 65536. .RE .TP .B SASL_NOCANON <on/true/yes/off/false/no> Do not perform reverse DNS lookups to canonicalize SASL host names. The default is off. .SH GSSAPI OPTIONS If OpenLDAP is built with Generic Security Services Application Programming Interface support, there are more options you can specify. .TP .B GSSAPI_SIGN <on/true/yes/off/false/no> Specifies if GSSAPI signing (GSS_C_INTEG_FLAG) should be used. The default is off. .TP .B GSSAPI_ENCRYPT <on/true/yes/off/false/no> Specifies if GSSAPI encryption (GSS_C_INTEG_FLAG and GSS_C_CONF_FLAG) should be used. The default is off. .TP .B GSSAPI_ALLOW_REMOTE_PRINCIPAL <on/true/yes/off/false/no> Specifies if GSSAPI based authentication should try to form the target principal name out of the ldapServiceName or dnsHostName attribute of the targets RootDSE entry. The default is off. .SH TLS OPTIONS If OpenLDAP is built with Transport Layer Security support, there are more options you can specify. These options are used when an .B ldaps:// URI is selected (by default or otherwise) or when the application negotiates TLS by issuing the LDAP StartTLS operation. .LP When using OpenSSL, if neither \fBTLS_CACERT\fP nor \fBTLS_CACERTDIR\fP is set, the system-wide default set of CA certificates is used. .TP .B TLS_CACERT <filename> Specifies the file that contains certificates for all of the Certificate Authorities the client will recognize. .TP .B TLS_CACERTDIR <path> Specifies the path of a directory that contains Certificate Authority certificates in separate individual files. The .B TLS_CACERT is always used before .B TLS_CACERTDIR. The specified directory must be managed with the OpenSSL c_rehash utility. This parameter is ignored with GnuTLS. When using Mozilla NSS, <path> may contain a Mozilla NSS cert/key database. If <path> contains a Mozilla NSS cert/key database and CA cert files, OpenLDAP will use the cert/key database and will ignore the CA cert files. .TP .B TLS_CERT <filename> Specifies the file that contains the client certificate. .B This is a user-only option. When using Mozilla NSS, if using a cert/key database (specified with TLS_CACERTDIR), TLS_CERT specifies the name of the certificate to use: .nf TLS_CERT Certificate for Sam Carter .fi If using a token other than the internal built in token, specify the token name first, followed by a colon: .nf TLS_CERT my hardware device:Certificate for Sam Carter .fi Use certutil \-L to list the certificates by name: .nf certutil \-d /path/to/certdbdir \-L .fi .TP .B TLS_KEY <filename> Specifies the file that contains the private key that matches the certificate stored in the .B TLS_CERT file. Currently, the private key must not be protected with a password, so it is of critical importance that the key file is protected carefully. .B This is a user-only option. When using Mozilla NSS, TLS_KEY specifies the name of a file that contains the password for the key for the certificate specified with TLS_CERT. The modutil command can be used to turn off password protection for the cert/key database. For example, if TLS_CACERTDIR specifies /home/scarter/.moznss as the location of the cert/key database, use modutil to change the password to the empty string: .nf modutil \-dbdir ~/.moznss \-changepw 'NSS Certificate DB' .fi You must have the old password, if any. Ignore the WARNING about the running browser. Press 'Enter' for the new password. .TP .B TLS_CIPHER_SUITE <cipher-suite-spec> Specifies acceptable cipher suite and preference order. <cipher-suite-spec> should be a cipher specification for the TLS library in use (OpenSSL, GnuTLS, or Mozilla NSS). Example: .RS .RS .TP .I OpenSSL: TLS_CIPHER_SUITE HIGH:MEDIUM:+SSLv2 .TP .I GnuTLS: TLS_CIPHER_SUITE SECURE256:!AES-128-CBC .RE To check what ciphers a given spec selects in OpenSSL, use: .nf openssl ciphers \-v <cipher-suite-spec> .fi With GnuTLS the available specs can be found in the manual page of .BR gnutls\-cli (1) (see the description of the option .BR \-\-priority ). In older versions of GnuTLS, where gnutls\-cli does not support the option \-\-priority, you can obtain the \(em more limited \(em list of ciphers by calling: .nf gnutls\-cli \-l .fi When using Mozilla NSS, the OpenSSL cipher suite specifications are used and translated into the format used internally by Mozilla NSS. There isn't an easy way to list the cipher suites from the command line. The authoritative list is in the source code for Mozilla NSS in the file sslinfo.c in the structure .nf static const SSLCipherSuiteInfo suiteInfo[] .fi .RE .TP .B TLS_PROTOCOL_MIN <major>[.<minor>] Specifies minimum SSL/TLS protocol version that will be negotiated. If the server doesn't support at least that version, the SSL handshake will fail. To require TLS 1.x or higher, set this option to 3.(x+1), e.g., .nf TLS_PROTOCOL_MIN 3.2 .fi would require TLS 1.1. Specifying a minimum that is higher than that supported by the OpenLDAP implementation will result in it requiring the highest level that it does support. This parameter is ignored with GnuTLS. .TP .B TLS_RANDFILE <filename> Specifies the file to obtain random bits from when /dev/[u]random is not available. Generally set to the name of the EGD/PRNGD socket. The environment variable RANDFILE can also be used to specify the filename. This parameter is ignored with GnuTLS and Mozilla NSS. .TP .B TLS_REQCERT <level> Specifies what checks to perform on server certificates in a TLS session, if any. The .B <level> can be specified as one of the following keywords: .RS .TP .B never The client will not request or check any server certificate. .TP .B allow The server certificate is requested. If no certificate is provided, the session proceeds normally. If a bad certificate is provided, it will be ignored and the session proceeds normally. .TP .B try The server certificate is requested. If no certificate is provided, the session proceeds normally. If a bad certificate is provided, the session is immediately terminated. .TP .B demand | hard These keywords are equivalent. The server certificate is requested. If no certificate is provided, or a bad certificate is provided, the session is immediately terminated. This is the default setting. .RE .TP .B TLS_CRLCHECK <level> Specifies if the Certificate Revocation List (CRL) of the CA should be used to verify if the server certificates have not been revoked. This requires .B TLS_CACERTDIR parameter to be set. This parameter is ignored with GnuTLS and Mozilla NSS. .B <level> can be specified as one of the following keywords: .RS .TP .B none No CRL checks are performed .TP .B peer Check the CRL of the peer certificate .TP .B all Check the CRL for a whole certificate chain .RE .TP .B TLS_CRLFILE <filename> Specifies the file containing a Certificate Revocation List to be used to verify if the server certificates have not been revoked. This parameter is only supported with GnuTLS and Mozilla NSS. .SH "ENVIRONMENT VARIABLES" .TP LDAPNOINIT disable all defaulting .TP LDAPCONF path of a configuration file .TP LDAPRC basename of ldaprc file in $HOME or $CWD .TP LDAP<option-name> Set <option-name> as from ldap.conf .SH FILES .TP .I /opt/alt/openldap11/etc/openldap/ldap.conf system-wide ldap configuration file .TP .I $HOME/ldaprc, $HOME/.ldaprc user ldap configuration file .TP .I $CWD/ldaprc local ldap configuration file .SH "SEE ALSO" .BR ldap (3), .BR ldap_set_option (3), .BR ldap_result (3), .BR openssl (1), .BR sasl (3) .SH AUTHOR Kurt Zeilenga, The OpenLDAP Project .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 521 stdin PK �c\��lN N man/man5/ldif.5nu �[��� .lf 1 stdin .TH LDIF 5 "2018/03/22" "OpenLDAP 2.4.46" .\" $OpenLDAP$ .\" Copyright 1998-2018 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldif \- LDAP Data Interchange Format .SH DESCRIPTION The LDAP Data Interchange Format (LDIF) is used to represent LDAP entries and change records in text form. LDAP tools, such as .BR ldapadd (1) and .BR ldapsearch (1), read and write LDIF entry records. .BR ldapmodify (1) reads LDIF change records. .LP This manual page provides a basic description of LDIF. A formal specification of LDIF is published in RFC 2849. .SH ENTRY RECORDS .LP LDIF entry records are used to represent directory entries. The basic form of an entry record is: .LP .nf .ft tt dn: <distinguished name> <attrdesc>: <attrvalue> <attrdesc>: <attrvalue> <attrdesc>:: <base64-encoded-value> <attrdesc>:< <URL> ... .ft .fi .LP The value may be specified as UTF-8 text or as base64 encoded data, or a URI may be provided to the location of the attribute value. .LP A line may be continued by starting the next line with a single space or tab, e.g., .LP .nf .ft tt dn: cn=Barbara J Jensen,dc=exam ple,dc=com .ft .fi .LP Lines beginning with a sharp sign ('#') are ignored. .LP Multiple attribute values are specified on separate lines, e.g., .LP .nf .ft tt cn: Barbara J Jensen cn: Babs Jensen .ft .fi .LP If an value contains a non-printing character, or begins with a space or a colon ':', the <attrtype> is followed by a double colon and the value is encoded in base 64 notation. e.g., the value " begins with a space" would be encoded like this: .LP .nf .ft tt cn:: IGJlZ2lucyB3aXRoIGEgc3BhY2U= .ft .fi .LP If the attribute value is located in a file, the <attrtype> is followed by a ':<' and a file: URI. e.g., the value contained in the file /tmp/value would be listed like this: .LP .nf .ft tt cn:< file:///tmp/value .ft .fi Other URI schemes (ftp,http) may be supported as well. .LP Multiple entries within the same LDIF file are separated by blank lines. .SH ENTRY RECORD EXAMPLE Here is an example of an LDIF file containing three entries. .LP .nf .ft tt dn: cn=Barbara J Jensen,dc=example,dc=com cn: Barbara J Jensen cn: Babs Jensen objectclass: person description:< file:///tmp/babs sn: Jensen dn: cn=Bjorn J Jensen,dc=example,dc=com cn: Bjorn J Jensen cn: Bjorn Jensen objectclass: person sn: Jensen dn: cn=Jennifer J Jensen,dc=example,dc=com cn: Jennifer J Jensen cn: Jennifer Jensen objectclass: person sn: Jensen jpegPhoto:: /9j/4AAQSkZJRgABAAAAAQABAAD/2wBDABALD A4MChAODQ4SERATGCgaGBYWGDEjJR0oOjM9PDkzODdASFxOQ ERXRTc4UG1RV19iZ2hnPk1xeXBkeFxlZ2P/2wBDARESEhgVG ... .ft .fi .LP Note that the description in Barbara Jensen's entry is read from file:///tmp/babs and the jpegPhoto in Jennifer Jensen's entry is encoded using base 64. .SH CHANGE RECORDS LDIF change records are used to represent directory change requests. Each change record starts with line indicating the distinguished name of the entry being changed: .LP .nf dn: <distinguishedname> .fi .LP .nf changetype: <[modify|add|delete|modrdn]> .fi .LP Finally, the change information itself is given, the format of which depends on what kind of change was specified above. For a \fIchangetype\fP of \fImodify\fP, the format is one or more of the following: .LP .nf add: <attributetype> <attrdesc>: <value1> <attrdesc>: <value2> ... \- .fi .LP Or, for a replace modification: .LP .nf replace: <attributetype> <attrdesc>: <value1> <attrdesc>: <value2> ... \- .fi .LP If no \fIattributetype\fP lines are given to replace, the entire attribute is to be deleted (if present). .LP Or, for a delete modification: .LP .nf delete: <attributetype> <attrdesc>: <value1> <attrdesc>: <value2> ... \- .fi .LP If no \fIattributetype\fP lines are given to delete, the entire attribute is to be deleted. .LP For a \fIchangetype\fP of \fIadd\fP, the format is: .LP .nf <attrdesc1>: <value1> <attrdesc1>: <value2> ... <attrdescN>: <value1> <attrdescN>: <value2> .fi .LP For a \fIchangetype\fP of \fImodrdn\fP or \fImoddn\fP, the format is: .LP .nf newrdn: <newrdn> deleteoldrdn: 0 | 1 newsuperior: <DN> .fi .LP where a value of 1 for deleteoldrdn means to delete the values forming the old rdn from the entry, and a value of 0 means to leave the values as non-distinguished attributes in the entry. The newsuperior line is optional and, if present, specifies the new superior to move the entry to. .LP For a \fIchangetype\fP of \fIdelete\fP, no additional information is needed in the record. .LP Note that attribute values may be presented using base64 or in files as described for entry records. Lines in change records may be continued in the manner described for entry records as well. .SH CHANGE RECORD EXAMPLE The following sample LDIF file contains a change record of each type of change. .LP .nf dn: cn=Babs Jensen,dc=example,dc=com changetype: add objectclass: person objectclass: extensibleObject cn: babs cn: babs jensen sn: jensen dn: cn=Babs Jensen,dc=example,dc=com changetype: modify add: givenName givenName: Barbara givenName: babs \- replace: description description: the fabulous babs \- delete: sn sn: jensen \- dn: cn=Babs Jensen,dc=example,dc=com changetype: modrdn newrdn: cn=Barbara J Jensen deleteoldrdn: 0 newsuperior: ou=People,dc=example,dc=com dn: cn=Barbara J Jensen,ou=People,dc=example,dc=com changetype: delete .fi .SH INCLUDE STATEMENT The LDIF parser has been extended to support an .B include statement for referencing other LDIF files. The .B include statement must be separated from other records by a blank line. The referenced file is specified using a file: URI and all of its contents are incorporated as if they were part of the original LDIF file. As above, other URI schemes may be supported. For example: .LP .nf dn: dc=example,dc=com objectclass: domain dc: example include: file:///tmp/example.com.ldif dn: dc=example,dc=org objectclass: domain dc: example .fi This feature is not part of the LDIF specification in RFC 2849 but is expected to appear in a future revision of this spec. It is supported by the .BR ldapadd (1), .BR ldapmodify (1), and .BR slapadd (8) commands. .SH SEE ALSO .BR ldap (3), .BR ldapsearch (1), .BR ldapadd (1), .BR ldapmodify (1), .BR slapadd (8), .BR slapcat (8), .BR slapd\-ldif (5). .LP "LDAP Data Interchange Format," Good, G., RFC 2849. .SH ACKNOWLEDGEMENTS .lf 1 ./../Project .\" Shared Project Acknowledgement Text .B "OpenLDAP Software" is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. .B "OpenLDAP Software" is derived from the University of Michigan LDAP 3.3 Release. .lf 278 stdin PK �c\T?Ц � licenses/alt-openldap11/LICENSEnu �[��� The OpenLDAP Public License Version 2.8, 17 August 2003 Redistribution and use of this software and associated documentation ("Software"), with or without modification, are permitted provided that the following conditions are met: 1. Redistributions in source form must retain copyright statements and notices, 2. Redistributions in binary form must reproduce applicable copyright statements and notices, this list of conditions, and the following disclaimer in the documentation and/or other materials provided with the distribution, and 3. Redistributions must contain a verbatim copy of this document. The OpenLDAP Foundation may revise this license from time to time. Each revision is distinguished by a version number. You may use this Software under terms of this license revision or under the terms of any subsequent revision of the license. THIS SOFTWARE IS PROVIDED BY THE OPENLDAP FOUNDATION AND ITS CONTRIBUTORS ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OPENLDAP FOUNDATION, ITS CONTRIBUTORS, OR THE AUTHOR(S) OR OWNER(S) OF THE SOFTWARE BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. The names of the authors and copyright holders must not be used in advertising or otherwise to promote the sale, use or other dealing in this Software without specific, written prior permission. Title to copyright in this Software shall at all times remain with copyright holders. OpenLDAP is a registered trademark of the OpenLDAP Foundation. Copyright 1999-2003 The OpenLDAP Foundation, Redwood City, California, USA. All Rights Reserved. Permission to copy and distribute verbatim copies of this document is granted. PK �c\`)��) ) ! licenses/alt-openldap11/COPYRIGHTnu �[��� Copyright 1998-2018 The OpenLDAP Foundation 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>. OpenLDAP is a registered trademark of the OpenLDAP Foundation. Individual files and/or contributed packages may be copyright by other parties and/or subject to additional restrictions. This work is derived from the University of Michigan LDAP v3.3 distribution. Information concerning this software is available at <http://www.umich.edu/~dirsvcs/ldap/ldap.html>. This work also contains materials derived from public sources. Additional information about OpenLDAP can be obtained at <http://www.openldap.org/>. --- Portions Copyright 1998-2012 Kurt D. Zeilenga. Portions Copyright 1998-2006 Net Boolean Incorporated. Portions Copyright 2001-2006 IBM Corporation. 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. --- Portions Copyright 1999-2008 Howard Y.H. Chu. Portions Copyright 1999-2008 Symas Corporation. Portions Copyright 1998-2003 Hallvard B. Furuseth. Portions Copyright 2007-2011 Gavin Henry. Portions Copyright 2007-2011 Suretec Systems Ltd. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that this notice is preserved. The names of the copyright holders may not be used to endorse or promote products derived from this software without their specific prior written permission. This software is provided ``as is'' without express or implied warranty. --- Portions Copyright (c) 1992-1996 Regents of the University of Michigan. All rights reserved. Redistribution and use in source and binary forms are permitted provided that this notice is preserved and that due credit is given to the University of Michigan at Ann Arbor. The name of the University may not be used to endorse or promote products derived from this software without specific prior written permission. This software is provided ``as is'' without express or implied warranty. PK "�c\C���k �k doc/alt-openldap11/CHANGESnu �[��� OpenLDAP 2.4 Change Log OpenLDAP 2.4.46 Release (2018/03/22) Fixed libldap connection delete callbacks when TLS fails to start (ITS#8717) Fixed libldap to not reuse tls_session if TLS hostname check fails (ITS#7373) Fixed libldap cross-compiling with OpenSSL 1.1 (ITS#8687) Fixed libldap OpenSSL 1.1.1 compatibility with BIO_method (ITS#8791) Fixed libldap MozNSS CA certificate hash matching (ITS#7374) Fixed libldap MozNSS with PEM certs when also using an NSS cert db (ITS#7389) Fixed libldap MozNSS initialization (ITS#8484) Fixed libldap GnuTLS with GNUTLS_E_AGAIN (ITS#8650) Fixed libldap memory leak with cancel operations (ITS#8782) Fixed slapd Eventlog registry key creation on 64-bit Windows (ITS#8705) Fixed slapd to maintain SSF across SASL binds (ITS#8796) Fixed slapd syncrepl deadlock when updating cookie (ITS#8752) Fixed slapd syncrepl callback to always be last in the stack (ITS#8752) Fixed slapd telephoneNumberNormalize when the value is spaces and hyphens (ITS#8778) Fixed slapd CSN queue processing (ITS#8801) Fixed slapd-ldap TLS connection timeout with high latency connections (ITS#8720) Fixed slapd-ldap to ignore unknown schema when omit-unknown-schema is set (ITS#7520) Fixed slapd-mdb with an optimization for long lived read transactions (ITS#8226) Fixed slapd-meta assert when olcDbRewrite is modified (ITS#8404) Fixed slapd-sock with LDAP_MOD_INCREMENT operations (ITS#8692) Fixed slapo-accesslog cleanup to only occur on failed operations (ITS#8752) Fixed slapo-dds entryTTL to actually decrease as per RFC 2589 (ITS#7100) Fixed slapo-syncprov memory leak with delete operations (ITS#8690) Fixed slapo-syncprov to not clear pending operation when checkpointing (ITS#8444) Fixed slapo-syncprov to correctly record contextCSN values in the accesslog (ITS#8100) Fixed slapo-syncprov not to log checkpoints to accesslog db (ITS#8607) Fixed slapo-syncprov to process changes from this SID on REFRESH (ITS#8800) Fixed slapo-syncprov session log parsing to not block other operations (ITS#8486) Build Environment Fixed Windows build with newer MINGW version (ITS#8697) Fixed compiler warnings and removed unused variables (ITS#8578) Contrib Fixed ldapc++ Control structure (ITS#8583) Documentation Delete stub manpage for back-ldbm (ITS#8713) Fixed ldap_bind(3) to mention the LDAP_SASL_SIMPLE mechanism (ITS#8121) Fixed ldap.conf(5) to note SASL_MECH/SASL_REALM are no longer user-only (ITS#8818) Fixed slapd-config(5) typo for olcTLSCipherSuite (ITS#8715) Fixed slapo-syncprov(5) indexing requirements (ITS#5048) OpenLDAP 2.4.45 Release (2017/06/01) Added slapd support for OpenSSL 1.1.0 series (ITS#8353, ITS#8533, ITS#8634) Fixed libldap to fail ldap_result if the handle is already bad (ITS#8585) Fixed libldap to expose error if user specified CA doesn't exist (ITS#8529) Fixed libldap handling of Diffie-Hellman parameters (ITS#7506) Fixed libldap GnuTLS use after free (ITS#8385) Fixed libldap SASL initialization (ITS#8648) Fixed slapd bconfig rDN escape handling (ITS#8574) Fixed slapd segfault with invalid hostname (ITS#8631) Fixed slapd sasl SEGV rebind in same session (ITS#8568) Fixed slapd syncrepl filter handling (ITS#8413) Fixed slapd syncrepl infinite looping mods with delta-sync MMR (ITS#8432) Fixed slapd callback struct so older modules without writewait should function. Custom modules may need to be updated for sc_writewait callback (ITS#8435) Fixed slapd-ldap/meta broken LDAP_TAILQ macro (ITS#8576) Fixed slapd-mdb so it passes ITS6794 regression test (ITS#6794) Fixed slapd-mdb double free with size zero paged result (ITS#8655) Fixed slapd-meta uninitialized diagnostic message (ITS#8442) Fixed slapo-accesslog to honor pauses during purge for cn=config update (ITS#8423) Fixed slapo-accesslog with multiple modifications to the same attribute (ITS#6545) Fixed slapo-relay to correctly initialize sc_writewait (ITS#8428) Fixed slapo-sssvlv double free (ITS#8592) Fixed slapo-unique with empty modifications (ITS#8266) Build Environment Added test065 for proxyauthz (ITS#8571) Fix test008 to be portable (ITS#8414) Fix test064 to wait for slapd to start (ITS#8644) Fix its4336 regression test (ITS#8534) Fix its4337 regression test (ITS#8535) Fix regression tests to execute on all backends (ITS#8539) Contrib Added slapo-autogroup(5) man page (ITS#8569) Added passwd missing conversion scripts for apr1 (ITS#6826) Fixed contrib modules where the writewait callback was not correctly initialized (ITS#8435) Fixed smbk5pwd to build with newer OpenSSL releases (ITS#8525) Documentation admin24 fixed tls_cipher_suite bindconf option (ITS#8099) admin24 fixed typo cn=config to be slapd.d (ITS#8449) admin24 fixed slapo-syncprov information to be current (ITS#8253) admin24 fixed typo in access control docs (ITS#7341, ITS#8391) admin24 fixed minor typo in tuning guide (ITS#8499) admin24 fixed information about the limits option (ITS#7700) admin24 fixed missing options for syncrepl configuration (ITS#7700) admin24 fixed accesslog documentation to note it should not be replicated (ITS#8344) Fixed ldap.conf(5) missing information on SASL_NOCANON option (ITS#7177) Fixed ldapsearch(1) information on the V[V] flag behavior (ITS#7177, ITS#6339) Fixed slapd-config(5), slapd.conf(5) clarification on interval keyword for refreshAndPersist (ITS#8538) Fixed slapd-config(5), slapd.conf(5) clarify serverID requirements (ITS#8635) Fixed slapd-config(5), slapd.conf(5) clarification on loglevel settings (ITS#8123) Fixed slapo-ppolicy(5) to clearly note rootdn requirement (ITS#8565) Fixed slapo-memberof(5) to note it is not safe to use with replication (ITS#8613) Fixed slapo-syncprov(5) documentation to be current (ITS#8253) Fixed slapadd(8) manpage to note slapd-mdb (ITS#8215) Fixed various minor grammar issues in the man pages (ITS#8544) Fixed various typos (ITS#8587) OpenLDAP 2.4.44 Release (2016/02/05) Fixed slapd-bdb/hdb missing olcDbChecksum config attr (ITS#8337) Fixed slapd-mdb behavior with long lived read transactions (ITS#8226) Fixed slapd-mdb cleanup after failed transaction (ITS#8360) Fixed slapd-sql missing id_query/olcSqlIdQuery (ITS#8329) Fixed slapo-accesslog callback initialization (ITS#8351) Fixed slapo-ppolicy pwdMaxRecordedFailure must never be zero (ITS#8327) Fixed slapo-syncprov abandon processing (ITS#8354) Fixed slapo-syncprov ctxcsn snapshot on refresh (ITS#8281, ITS#8365) Documentation admin24 Stop linking to Berkeley DB downloads (ITS#8362) admin24 Update documentation for LMDB preference OpenLDAP 2.4.43 Release (2015/11/30) Fixed liblber remove obsolete assert (ITS#8240, ITS#8301) Fixed libldap file URLs on windows (ITS#8273) Fixed libldap microsecond timer for windows (ITS#8295) Fixed slap tools minor one time memory leak (ITS#8082) Fixed slapd to avoid redundant processing of abandon ops (ITS#8232) Fixed slapd syncrepl SEGV when present list is NULL (ITS#8231, ITS#8042) Fixed slapd segfault with invalid SASL URI (ITS#8218) Fixed slapd configuration parser with unbalanced quotes (ITS#8233) Fixed slapd syncrepl check with config db on windows (ITS#8277) Fixed slapd with mod Increment and inherited attribute type (ITS#8289) Fixed slapd-ldap SEGV after failed retry (ITS#8173) Fixed slapd-ldap to skip client controls in ldap_back_entry_get (ITS#8244) Fixed slapd-null to have an option to return a search entry (ITS#8249) Fixed slapd-relay to correctly handle quoted options (ITS#8284) Fixed slapo-accesslog delta-sync MMR with interrupted refresh phase (ITS#8281) Fixed slapo-dds segfault when using slapo-memberof (ITS#8133) Fixed slapo-ppolicy to allow purging of stale pwdFailureTime attributes (ITS#8185) Fixed slapo-ppolicy to release entry on failure (ITS#7537) Fixed slapo-ppolicy to fall back to default policy if there is a parsing error (ITS#8234) Fixed slapo-syncprov with interrupted refresh phase (ITS#8281) Fixed slapo-refint with subtree renames (ITS#8220) Fixed slapo-rwm missing olcDropUnrequested attribute (ITS#7889) Fixed slapo-rwm parsing to avoid double-escaping rewrite rules (ITS#7964) Build Environment Fixed ldif-filter option parsing (ITS#8292) Fixed slapd-tester EOL handling in test output for windows (ITS#8280) Fixed slapd-tester executable suffix for windows (ITS#8216) Fixed test061 timing issues (ITS#8297) Contrib Added libnettle support to pw-pbkdf2 (ITS#8198) Fixed smbk5pwd compiler warnings with libnettle (ITS#8235) Fixed passwd symbol collisions with other crypto libraries (ITS#8294) Documentation Updated guide to reflect changes to how TLS is handled with syncrepl (ITS#7897) OpenLDAP 2.4.42 Release (2015/08/14) Fixed liblber address length for CLDAP (ITS#8158) Fixed libldap dnssrv potential overflow with port number (ITS#7027,ITS#8195) Fixed slapd cn=config when updating olcAttributeTypes (ITS#8199) Fixed slapd-mdb to correctly update search candidates for scoped searches (ITS#8203) Fixed slapo-ppolicy with redundant mod ops on glued trees (ITS#8184) Fixed slapo-rwm crash when deleting rewrite rules (ITS#8213) Build Environment Fixed libdb detection with gcc 5.x (ITS#8056) OpenLDAP 2.4.41 Release (2015/06/21) Fixed ldapsearch to explicitly flush its buffer (ITS#8118) Fixed libldap async connections (ITS#8090) Fixed libldap double free of request during abandon (ITS#7967) Fixed libldap error string for LDAP_X_CONNECTING (ITS#8093) Fixed libldap segfault in ldap_sync_initialize (ITS#8001) Fixed libldap ldif-wrap off by one error (ITS#8003) Fixed libldap handling of TLS in async mode (ITS#8022) Fixed libldap null pointer dereference (ITS#8028) Fixed libldap mutex handling with LDAP_OPT_SESSION_REFCNT (ITS#8050) Fixed slapd slapadd config db import of minimal frontend entry (ITS#8150) Fixed slapd slapadd onetime leak with -w (ITS#8014) Fixed slapd sasl auxprop crash with invalid config (ITS#8092) Fixed slapd syncrepl delta-mmr issue with overlays and slapd.conf (ITS#7976) Fixed slapd syncrepl mutex for cookie state (ITS#7968) Fixed slapd syncrepl memory leaks (ITS#8035) Fixed slapd syncrepl to free presentlist at end of refresh mode (ITS#8038) Fixed slapd syncrepl to streamline presentlist (ITS#8042) Fixed slapd syncrepl concurrency when CHECK_CSN is enabled (ITS#8120) Fixed slapd rootdn checks for hidden backends (ITS#8108) Fixed slapd segfault when using matched values control (ITS#8046) Fixed slapd-ldap reconnection behavior on remote failure (ITS#8142) Fixed slapd-mdb minor case typo (ITS#8049) Fixed slapd-mdb one-level search (ITS#7975) Fixed slapd-mdb heap corruption (ITS#7965) Fixed slapd-mdb crash after deleting in-use schema (ITS#7995) Fixed slapd-mdb minor code cleanup (ITS#8011) Fixed slapd-mdb to return errors when using incorrect env flags (ITS#8016) Fixed slapd-mdb to correctly update search candidates (ITS#8036, ITS#7904) Fixed slapd-mdb when there were more than 65535 aliases in scope (ITS#8103) Fixed slapd-mdb alias deref when objectClass is not indexed (ITS#8146) Fixed slapd-meta TLS initialization with ldaps URIs (ITS#8022) Fixed slapd-meta to have better error logging (ITS#8131) Fixed slapd-perl conversion to cn=config (ITS#8105) Fixed slapd-sql autocommit config variable (ITS#8129,ITS#6613) Fixed slapo-collect segfault (ITS#7797) Fixed slapo-constraint with 0 count constraint (ITS#7780,ITS#7781) Fixed slapo-deref with empty attribute list (ITS#8027) Fixed slapo-memberof to correctly reject invalid members (ITS#8107) Fixed slapo-sock result parser for CONTINUE (ITS#8048) Fixed slapo-syncprov synprov_matchops usage of test_filter (ITS#8013) Fixed slapo-syncprov segfault on disconnect/abandon (ITS#5452,ITS#8012) Fixed slapo-syncprov memory leak (ITS#8039) Fixed slapo-syncprov segfault on disconnect/abandon (ITS#8043) Fixed slapo-syncprov deadlock when autogroup is in use (ITS#8063) Fixed slapo-syncprov potential loss of changes when under load (ITS#8081) Fixed slapo-unique enforcement of uniqueness with manageDSAit control (ITS#8057) Build Environment Fixed ftello reference for Win32 (ITS#8127) Enhanced contrib modules build paths (ITS#7782) Fixed contrib/autogroup internal operation identity (ITS#8006) Fixed contrib/autogroup to skip internal ops with accesslog (ITS#8065) Fixed contrib/passwd/sha2 compiler warning (ITS#8000) Fixed contrib/noopsrch compiler warning (ITS#7998) Fixed contrib/dupent compiler warnings (ITS#7997) Test suite: Added vrFilter test (ITS#8046) Contrib Added pbkdf2 sha256 and sha512 schemes (ITS#7977) Fixed autogroup modification callback responses (ITS#6970) Fixed nssov compare with usergroup (ITS#8079) Fixed nssov password change behavior (ITS#8080) Fixed nssov updated to 0.9.4 (ITS#8097) Documentation Added ldap_get_option(3) LDAP_FEATURE_INFO_VERSION information (ITS#8032) Added ldap_get_option(3) LDAP_OPT_API_INFO_VERSION information (ITS#8032) Fixed slapd-config(5), slapd.conf(5) tls_cipher_suite option (ITS#8099) Fixed slapd-meta(5), slapd-ldap(5) tls_cipher_suite option (ITS#8099) Fixed slapd-meta(5) fix minor typo (ITS#7769) OpenLDAP 2.4.40 Release (2014/09/20) Fixed libldap DNS SRV priority handling (ITS#7027) Fixed libldap don't leak libldap err codes (ITS#7676) Fixed libldap CR/LF handling (ITS#4635) Fixed libldap ldif-wrap length (ITS#7871) Fixed libldap GnuTLS ciphersuite parsing (ITS#7500) Fixed libldap GnuTLS with newer versions (ITS#7430,ITS#6359) Fixed libldif to correctly handle 4096 character lines (ITS#7859) Fixed librewrite reference counting (ITS#7723) Fixed slapacl with back-mdb reader transactions (ITS#7920) Fixed slapd syncrepl to send cookie on fallback (ITS#7849) Fixed slapd syncrepl SEGV when abandoning a connection (ITS#7928) Fixed slapd slapcat with external schema (ITS#7895) Fixed slapd schema RDN normalization (ITS#7935) Fixed slapd with repeated language tags (ITS#7941) Fixed slapd modrdn crash on naming attr with no matching rule (ITS#7850) Fixed slapd memory leak in control handling (ITS#7942) Fixed slapd-ldap removed dead code (ITS#7922) Fixed slapd-mdb to work concurrently with slapadd (ITS#7798) Fixed slapd-mdb with paged results (ITS#7705, ITS#7800) Fixed slapd-mdb slapcat with nonexistent indices (ITS#7870) Fixed slapd-mdb long lived reader transactions (ITS#7904) Fixed slapd-mdb memory leak on matchedDN (ITS#7872) Fixed slapd-mdb sorting of attribute values (ITS#7902) Fixed slapd-mdb to flag attribute values as sorted (ITS#7903) Fixed slapd-mdb index config handling (ITS#7912) Fixed slapd-mdb entry release handling (ITS#7915) Fixed slapd-mdb with aliases and referrals (ITS#7927) Fixed slapd-mdb alias dereferencing (ITS#7702) Fixed slapd-sock socket flushing (ITS#7937) Fixed slapo-accesslog attribute normalization (ITS#7934) Fixed slapo-accesslog internal search logging (ITS#7929) Fixed slapo-auditlog connection destroy logic (ITS#7906,ITS#7923) Fixed slapo-chain interaction with slapo-rwm (ITS#7930) Fixed slapo-constraint connection destroy logic (ITS#7906,ITS#7923) Fixed slapo-dds connection destroy logic (ITS#7906,ITS#7923) Fixed slapo-dyngroup connection destroy logic (ITS#7906,ITS#7923) Fixed slapo-memberof attr count (ITS#7893) Fixed slapo-memberof frontendDB handling (ITS#7249) Fixed slapo-memberof internal search logging (ITS#7929) Fixed slapo-pcache config processing (ITS#7919) Fixed slapo-pcache connection destroy logic (ITS#7906,ITS#7923) Added slapo-ppolicy ORDERING rules (ITS#7838) Fixed slapo-ppolicy timestamp resolution to use microseconds (ITS#7161) Fixed slapo-ppolicy connection destroy logic (ITS#7906,ITS#7923) Fixed slapo-refint to check for pauses in cn=config (ITS#7873) Fixed slapo-refint internal search logging (ITS#7929) Fixed slapo-refint connection destroy logic (ITS#7906,ITS#7923) Fixed slapo-seqmod connection destroy logic (ITS#7906,ITS#7923) Fixed slapo-slapover connection destroy logic (ITS#7906,ITS#7923) Fixed slapo-sock db_init (ITS#7868) Fixed slapo-sssvlv fix olcSssVlvMaxPerConn (ITS#7908) Fixed slapo-translucent double free (ITS#7587) Fixed slapo-translucent to work with manageDSAit (ITS#7864) Fixed slapo-translucent to use local backend with local entries (ITS#7915) Fixed slapo-unique connection destroy logic (ITS#7906,ITS#7923) Fixed slapcacl with invalid suffix (ITS#7827) Build Environment Remove support for gcrypt (ITS#7877) BDB 6.0.20 and later is not supported (ITS#7890) Fixed ODBC link check (ITS#7891) Fixed slapd.ldif frontend config (ITS#7933) Contrib Added pbkdf2 module (ITS#7742) Fixed autogroup double free (ITS#7831) Fixed autogroup modification callback responses (ITS#6970) Fixed ldapc++ memory leak in Async connection (ITS#7806) Fixed nssov install path (ITS#7858) Fixed passwd rpath (ITS#7885) Fixed apr1 do_phk_hash argument order (ITS#7869) Fixed slapd-sha2 buffer overrun (ITS#7851) Documentation Fixed slapd.ldif man page reference (ITS#7803) Fixed slapd.conf(5) man page to reference exattrs (ITS#7847) Fixed guide to work with mkrelease (ITS#7887) Fixed ldap_get_dn(3) ldap_ava definition (ITS#7860) OpenLDAP 2.4.39 Release (2014/01/26) Fixed libldap MozNSS crash (ITS#7783) Fixed libldap memory leak with SASL (ITS#7757) Fixed libldap assert in parse_passwdpolicy_control (ITS#7759) Fixed libldap shortcut NULL RDNs (ITS#7762) Fixed libldap deref to use correct control Fixed liblmdb keysizes with mdb_update_key (ITS#7756) Fixed slapd cn=config olcDbConfig modification (ITS#7750) Fixed slapd-bdb/hdb to bail out of search if config is paused (ITS#7761) Fixed slapd-bdb/hdb indexing issue with derived attributes (ITS#7778) Fixed slapd-mdb to bail out of search if config is paused (ITS#7761) Fixed slapd-mdb indexing issue with derived attributes (ITS#7778) Fixed slapd-perl to bail out of search if config is paused (ITS#7761) Fixed slapd-sql to bail out of search if config is paused (ITS#7761) Fixed slapo-constraint handling of softadd/softdel (ITS#7773) Fixed slapo-syncprov assert with findbase (ITS#7749) Build Environment Test suite: Use $(MAKE) for tests (ITS#7753) Documentation admin24 fix TLSDHParamFile to be correct (ITS#7684) OpenLDAP 2.4.38 Release (2013/11/16) Fixed liblmdb nordahead flag (ITS#7734) Fixed liblmdb to check cursor index before cursor_del (ITS#7733) Fixed liblmdb wasted space on split (ITS#7589) Fixed slapd for certs with a NULL issuerDN (ITS#7746) Fixed slapd cn=config with empty nested includes (ITS#7739) Fixed slapd syncrepl memory leak with delta-sync MMR (ITS#7735) Fixed slapd-bdb/hdb to stop processing on dn not found (ITS#7741) Fixed slapd-bdb/hdb with indexed ANDed filters (ITS#7743) Fixed slapd-mdb to stop processing on dn not found (ITS#7741) Fixed slapd-mdb dangling reader (ITS#7662) Fixed slapd-mdb matching rule for OlcDbEnvFlags (ITS#7737) Fixed slapd-mdb with indexed ANDed filters (ITS#7743) Fixed slapd-meta from blocking other threads (ITS#7740) Fixed slapo-syncprov assert with findbase (ITS#7749) OpenLDAP 2.4.37 Release (2013/10/27) Added liblmdb nordahead environment flag (ITS#7725) Fixed client tools CLDAP with IPv6 (ITS#7695) Fixed libldap CLDAP with IPv6 (ITS#7695) Fixed libldap lock ordering with abandon op (ITS#7712) Fixed liblmdb segfault with mdb_cursor_del (ITS#7718) Fixed liblmdb when converting to writemap (ITS#7715) Fixed liblmdb assert on MDB_NEXT with delete (ITS#7722) Fixed liblmdb wasted space on split (ITS#7589) Fixed slapd cn=config with olcTLSProtocolMin (ITS#7685) Fixed slapd-bdb/hdb optimize index updates (ITS#7329) Fixed slapd-ldap chaining with cn=config (ITS#7381, ITS#7434) Fixed slapd-ldap chaining with controls (ITS#7687) Fixed slapd-mdb optimize index updates (ITS#7329) Fixed slapd-meta chaining with cn=config (ITS#7381, ITS#7434) Fixed slapo-constraint to no-op on nonexistent entries (ITS#7692) Fixed slapo-dds assert on startup (ITS#7699) Fixed slapo-memberof to not replicate internal ops (ITS#7710) Fixed slapo-refint to not replicate internal ops (ITS#7710) Build Environment Fixed slapd-mdb ptr arithmetic on void *s (ITS#7720) Documentation ldapsearch(1) minor typo fix (ITS#7680) slapd-passwd(5) minor typo fix (ITS#7680) OpenLDAP 2.4.36 Release (2013/08/17) Added back-meta target filter patterns (ITS#7609) Added liblmdb mdb_txn_env to API (ITS#7660) Fixed libldap CLDAP with uninit'd memory (ITS#7582) Fixed libldap with UDP (ITS#7583) Fixed libldap OpenSSL TLS versions (ITS#7645) Fixed liblmdb MDB_PREV behavior (ITS#7556) Fixed liblmdb transaction issues (ITS#7515) Fixed liblmdb mdb_drop overflow page return (ITS#7561) Fixed liblmdb nested split (ITS#7592) Fixed liblmdb overflow page behavior (ITS#7620) Fixed liblmdb race condition with read and write txns (ITS#7635) Fixed liblmdb mdb_del behavior with MDB_DUPSORT and mdb_del (ITS#7658) Fixed slapd cn=config with unknown schema elements (ITS#7608) Fixed slapd cn=config with loglevel 0 (ITS#7611) Fixed slapd slapi filterlist free behavior (ITS#7636) Fixed slapd slapi control free behavior (ITS#7641) Fixed slapd schema countryString as directoryString (ITS#7659) Fixed slapd schema telephoneNumber as directoryString (ITS#7659) Fixed slapd-bdb/hdb to wait for read locks in tool mode (ITS#6365) Fixed slapd-mdb behavior with alias dereferencing (ITS#7577) Fixed slapd-mdb modrdn and base-scoped searches (ITS#7604) Fixed slapd-mdb refcount behavior (ITS#7628) Fixed slapd-meta binding flag is set (ITS#7524) Fixed slapd-meta with minimal config (ITS#7581) Fixed slapd-meta missing results messages (ITS#7591) Added slapd-meta TCP keepalive support (ITS#7513) Fixed slapo-sssvlv double free (ITS#7588) Fixed slaptest to list -Q option (ITS#7568) Build Environment Fixed slapd-meta declaration warnings (ITS#7654) Contrib Fixed nssov group enumeration bug (ITS#7569) Fixed autogroup when URI has no attrs (ITS#7580) Documentation admin24 Update database backend notes (ITS#7590) ldap.conf(5) fixed typos (ITS#7568) ldapmodify(1) remove replog reference (ITS#7562) ldif(5) remove replog reference (ITS#7562) slapd-config(5) remove replog reference (ITS#7562) slapd.conf(5) remove replog reference (ITS#7562) slapd-config(5) document TLSProtocolMin (ITS#5655,ITS#7645) slapd.conf(5) document TLSProtocolMin (ITS#5655,ITS#7645) OpenLDAP 2.4.35 Release (2013/03/31) Fixed liblmdb mdb_cursor_put with MDB_MULTIPLE (ITS#7551) Fixed liblmdb page rebalance (ITS#7536) Fixed liblmdb missing parens (ITS#7377) Fixed liblmdb mdb_cursor_del crash (ITS#7553) Fixed slapd syncrepl updateCookie status (ITS#7531) Fixed slapd connection logging (ITS#7543) Fixed slapd segfault on modify (ITS#7542, ITS#7432) Fixed slapd-mdb to reject undefined attrs (ITS#7540) Fixed slapo-pcache with +/- attrsets (ITS#7552) Build Environment don't install DB_CONFIG if no BDB backends (ITS#7533) Documentation slapschema(8) fix tool name (ITS#7534) admin24 fixed pcache example (ITS#7546) admin24 fixed config examples (ITS#7522) OpenLDAP 2.4.34 Release (2013/03/01) Fixed libldap connections with EINTR (ITS#7476) Fixed libldap lineno overflow in ldif_read_record (ITS#7497) Fixed liblmdb mdb_env_open flag handling (ITS#7453) Fixed liblmdb mdb_midl_sort array optimization (ITS#7432) Fixed liblmdb freelist with large entries (ITS#7455) Fixed liblmdb to check for filled dirty page list (ITS#7491) Fixed liblmdb to validate data limits (ITS#7485) Fixed liblmdb mdb_update_key for large keys (ITS#7505) Fixed ldapmodify to not core dump with invalid LDIF (ITS#7477) Fixed slapd syncrepl for old entries in MMR setup (ITS#7427) Fixed slapd signedness for index_substr_any_* (ITS#7449) Fixed slapd enforce SLAPD_MAX_DAEMON_THREADS (ITS#7450) Fixed slapd mutex in send_ldap_ber (ITS#6164) Added slapd-ldap onerr option (ITS#7492) Added slapd-ldap keepalive support (ITS#7501) Fixed slapd-ldif with empty dir (ITS#7451) Fixed slapd-mdb to reopen attr DBs after env reopen (ITS#7416) Fixed slapd-mdb handling of missing entries (ITS#7483,7496) Fixed slapd-mdb environment flag setting (ITS#7452) Fixed slapd-mdb with sub db slapcat (ITS#7469) Fixed slapd-mdb to correctly work with toolthreads > 2 (ITS#7488,ITS#7527) Fixed slapd-mdb subtree search speed (ITS#7473) Fixed slapd-meta conversion to cn=config (ITS#7525) Fixed slapd-meta segfault when modifying olcDbUri (ITS#7526) Fixed slapd-sql back-config support (ITS#7499) Fixed slapo-constraint handle uri and restrict correctly (ITS#7418) Fixed slapo-constraint with multi-master replication (ITS#7426) Fixed slapo-constraint segfault (ITS#7431) Fixed slapo-deref control initialization (ITS#7436) Fixed slapo-deref control exposure (ITS#7445) Fixed slapo-memberof with internal ops (ITS#7487) Fixed slapo-pcache matching rules for config db (ITS#7459) Fixed slapo-rwm modrdn cleanup (ITS#7414) Fixed slapo-sssvlv maxperconn parameter (ITS#7484) Build Environment Fixed slapo-constraint test suite (ITS#7423) Contrib Added nssov nssov_config support (ITS#7518) Added nssov password_prohibit_message (ITS#7518) Fixed ldapc++ with gcc-4.7 (ITS#7281,ITS#7304) Fixed nssov olcNssPamSession handling (ITS#7481) Fixed nssov connection DN (ITS#7518) Add missing Makefile for various modules (ITS#7308) Unify Makefile structure for modules (ITS#7309) Fixed slapo-allowed attribute replication (ITS#7493) Fixed slapo-passwd SHA2 to correctly zero buffer (ITS#7490) Documentation ldapurl(1) fix example usage (ITS#7454) ldap_get_option(3) fixed trailing whitespace (ITS#7411) slapd-config(5) olcExtraAttrs is per db (ITS#7421) slapd-overlays(5) update manpage index (ITS#7489) slapo-dynlist(5) Search behavior notes (ITS#7486) slapo-valsort(5) Document valsort control syntax (ITS#7523) OpenLDAP 2.4.33 Release (2012/10/10) Added slapd-meta cn=config support Fixed libldap MozNSS slot picking (ITS#7359) Fixed libldap MozNSS with tokenname:certnickname format (ITS#7360) Fixed liblmdb POSIX semaphore cleanup on environment close (ITS#7364) Fixed liblmdb mdb_page_split (ITS#7385, ITS#7229) Fixed slapd alock handling on Windows (ITS#7361) Fixed slapd acl handling with zero-length values (ITS#7350) Fixed slapd syncprov to not reference ops inside a lock (ITS#7172) Fixed slapd delta-syncrepl MMR with large attribute values (ITS#7354) Fixed slapd slapd_rw_destroy function (ITS#7390) Fixed slapd-ldap idassert bind handling (ITS#7403) Fixed slapd-mdb slapadd -q -w double free (ITS#7356) Fixed slapd-mdb to close read txn in reindex commit (ITS#7386) Fixed slapo-constraint with multiple modifications (ITS#7168) Build Environment Fixed build with Visual Studio (ITS#7358) Fixed liblmdb posix semaphore use on BSD system (ITS#7363) Add slapo-constraint test suite (ITS#7344, ITS#7366) Contrib Updated radius passwd module for NAS-Identifier (ITS#7357) Documentation slapo-refint(5) Note that refint is not replicated (ITS#7405) OpenLDAP 2.4.32 Release (2012/07/31) Added slappasswd loadable module support (ITS#7284) Fixed tools to not clobber SASL_NOCANON (ITS#7271) Fixed libldap function declarations (ITS#7293) Fixed libldap double free (ITS#7270) Fixed libldap debug level setting (ITS#7290) Fixed libldap MozNSS PEM/certdb handling (ITS#7276) Fixed libldap MozNSS cipher suite selection (ITS#7285) Fixed libldap MozNSS error handling (ITS#7287) Fixed libldap MozNSS cipher suite being ignored (ITS#7289) Fixed libldap MozNSS infinite loop (ITS#7291) Fixed libldap MozNSS context token for certdb (ITS#7312) Fixed libldap MozNSS store certificate object (ITS#7313) Fixed libldap MozNSS fix init and cleanup (ITS#7314) Fixed libldap MozNSS slot and pin usage (ITS#7315) Fixed libldap MozNSS to avoid infinite loop (ITS#7316) Fixed libldap MozNSS untrusted issuer error (ITS#7331) Fixed libldap gettime() regression (ITS#6262) Fixed libldap sasl handling (ITS#7118, ITS#7133) Fixed libldap to correctly free socket with TLS (ITS#7241) Fixed liblmdb leaf node handling (ITS#7266) Fixed liblmdb mutexes on Apple/Windows (ITS#7251) Fixed slapd config index renumbering (ITS#6987) Fixed slapd duplicate error response (ITS#7076) Fixed slapd parsing of PermissiveModify control (ITS#7298) Fixed slapd-bdb/hdb cache hang under high load (ITS#7222) Fixed slapd-bdb/hdb alias checking (ITS#7303) Fixed slapd-bdb/hdb olcDbConfig changes work immediately (ITS#7338) Fixed slapd-ldap to encode user DN during password change (ITS#7319) Fixed slapd-ldap assertion when proxying to MS AD (ITS#6851) Fixed slapd-ldap monitoring (ITS#7182, ITS#7225) Fixed slapd-mdb with tool mode (ITS#7255) Fixed slapd-mdb with approx indexing (ITS#7279) Fixed slapd-mdb dn2id delete (ITS#7302) Fixed slapd-mdb memory leak in online indexer (ITS#7323) Fixed slapd-mdb db corruption when hitting maxsize (ITS#7337) Fixed slapd-mdb aborts with online indexing (ITS#7339) Fixed slapd-perl panic (ITS#7325) Fixed slapo-accesslog memory leaks with sync replication (ITS#7292) Fixed slapo-syncprov memory leaks with sync replication (ITS#7292) Fixed contrib/smbk5pwd to not compile with MozNSS (ITS#7327) Fixed contrib/sha2 portability (ITS#7267) Fixed contrib/sha2 thread safety (ITS#7269) Added contrib/sha2 {SSHA256}, {SSHA384}, {SSHA512} support (ITS#7278) Build Environment Fixed test057 timing issues (ITS#7317) Fixed compilation with MS Visual Studio (ITS#7332) Contrib Added slapi_[get|free]_client_ip() (ITS#7305) Documentation slapo-sssvlv Added note about criticality (ITS#7253) admin24 Fix peername.regex typo (ITS#7282) Fixed slapd-config file include example (ITS#7318) slapd-ldap(5) Reference RFC4526 (ITS#7294) slapd-meta(5) Reference RFC4526 (ITS#7294) OpenLDAP 2.4.31 Release (2012/04/21) Added slapo-accesslog support for reqEntryUUID (ITS#6656) Fixed libldap IPv6 URL detection (ITS#7194) Fixed libldap rebinding on failed connection (ITS#7207) Fixed liblmdb alignment of MDB_db members (ITS#7191) Fixed liblmdb branch page merging on deletes (ITS#7190) Fixed liblmdb page split with MDB_APPEND (ITS#7213) Fixed liblmdb free page usage with entry deletion (ITS#7210) Fixed liblmdb to use IOV_MAX if it is defined and small (ITS#7196) Fixed liblmdb key alignment (ITS#7219) Fixed liblmdb mdb_page_split (ITS#7229) Fixed liblmdb with zero length IDLs (ITS#7230) Fixed slapd listener initialization (ITS#7233) Fixed slapd cn=config with olcTLSVerifyClient (ITS#7197) Fixed slapd delta-syncrepl fallback on non-leaf error (ITS#7195) Fixed slapd to reject MMR setups with bad serverID setting (ITS#7200) Fixed slapd approxIndexer key generation (ITS#7203) Fixed slapd modification of olcSuffix (ITS#7205) Fixed slapd schema validation with missing definitions (ITS#7224) Fixed slapd syncrepl -c with supplied CSN values (ITS#7245) Fixed slapd-bdb/hdb idlcache with only one element (ITS#7231) Fixed slapd-perl modify with binary values (ITS#7149) Fixed slapd-shell cn=config support (ITS#7201) Fixed slapd-shell modify with binary values (ITS#7149) Fixed slapo-accesslog deadlock with non-logged write ops (ITS#7088) Fixed slapo-syncprov sessionlog check (ITS#7218) Fixed slapo-syncprov entry leak (ITS#7234) Fixed slapo-syncprov startup initialization (ITS#7235) Build Environment Fixed test022 to check ldapsearch results (ITS#7228) Fixed test044 when back-monitor is disabled (ITS#7204) Documentation Fixed slapschema(8) formatting (ITS#7188) Fixed limdb functionality documentation (ITS#7238) Fixed ldap_get_option(3) note inheritance behavior (ITS#7240) OpenLDAP 2.4.30 Release (2012/02/29) Fixed libldap socket polling for writes (ITS#7167) Fixed liblutil string modifications (ITS#7174) Fixed slapd crash when attrsOnly is true (ITS#7143) Fixed slapd syncrepl delete handling (ITS#7052,ITS#7162) Fixed slapd-mdb slapadd with -q (ITS#7170) Fixed slapd-mdb slapadd with -w (ITS#7180) Fixed slapd-mdb slapindex with -q and -t (ITS#7176) Fixed slapo-pcache time-to-refesh handling (ITS#7178) Fixed slapo-syncprov loop detection (ITS#6024) Build Environment Fixed POSIX make support (ITS#7160) Fixed slapd-mdb build on POSIX (ITS#7160) Documentation Added option "-o" to ldap*(1) pages (ITS#7152) Fixed ldap*(1) page cleanup (ITS#7177) Fixed ldap_modify(3) prototypes (ITS#7173) OpenLDAP 2.4.29 Release (2012/02/12) Fixed libldap MozNSS deferred initialization handling (ITS#7136) Fixed libldap MozNSS with TLSCertificateKeyFile not set (ITS#7135) Fixed slapd cn=config modification of first schema element (ITS#7098) Fixed slapd operation reuse (ITS#7107) Fixed slapd blocked writers to not interfere with pool pause (ITS#7115) Fixed slapd connection loop connindex usage (ITS#7131) Fixed slapd double mutex unlock via connection_done (ITS#7125) Fixed slapd check order in connection_write (ITS#7113) Fixed slapd slapadd to exit on failure (ITS#7142) Fixed slapd syncrepl reference to freed memory (ITS#7127,ITS#7132) Fixed slapd syncrepl to ignore some errors on delete (ITS#7052) Fixed slapd syncrepl to handle missing oldRDN (ITS#7144) Fixed slapd-mdb to handle overlays in tool mode (ITS#7099) Fixed slapd-mdb segfaults with page splits (ITS#7121) Fixed slapd-mdb cleanup on transaction abort (ITS#7140) Fixed slapd-mdb with attribute descriptions (ITS#7146) Fixed slapd-meta to correctly handle multiple targets (ITS#7050) Fixed slapd-monitor compare op to update cached entry (ITS#7123) Fixed slapd-perl initialization (ITS#7075) Fixed slapd-sql to properly initialize be_cf_ocs (ITS#7158) Fixed slapo-dds to properly exit when in tool mode (ITS#7099) Fixed slapo-rwm not leave empty lots with normalized attrs (ITS#7143) Fixed slapo-syncprov with already abandoned operation (ITS#7150) Fixed contrib/smbk5pwd uninitialized keys in shadowLastChange (ITS#7138) Build Environment Fixed ldapsearch build on windows (ITS#7156) Fixed test001 to skip back-ldif (ITS#7101) Documentation admin24 Fix typo (ITS#7117) OpenLDAP 2.4.28 Release (2011/11/26) Fixed back-mdb out of order slapadd (ITS#7090) OpenLDAP 2.4.27 Release (2011/11/24) Added libldap support for draft-wahl-ldap-session (ITS#6984) Added slapd support for draft-wahl-ldap-session (ITS#6984) Added slapadd pipelining capability (ITS#7078) Added slapd Add-if-not-present (ITS#6561) Added slapd delta-syncrepl MMR (ITS#6734,ITS#7029,ITS#7031) Added slapd-mdb experimental backend (ITS#7079) Added slapd-passwd dynamic config support Added slapd-perl dynamic config support Added slapd-shell dynamic config support Added slapd-sock support as an overlay (ITS#6666) Added slapd-sql dynamic config support Added contrib/passwd APR1 support (ITS#6826) Fixed slapi linking on AIX (ITS#3272) Fixed ldapmodify crash with LDIF controls (ITS#7039) Fixed ldapsearch to honor timeout and timelimit (ITS#7009) Fixed libldap endless looping (ITS#7035) Fixed libldap TLS to not check hostname when using 'allow' (ITS#7014) Fixed libldap GnuTLS cert dn parse (ITS#7051) Fixed libldap MozNSS correctly destroy SSL_PeerCertificate (ITS#6980) Fixed libldap MozNSS with issuer expiration and verify never (ITS#6998) Fixed libldap MozNSS memory leak (ITS#7001) Fixed libldap MozNSS allow/try behavior (ITS#7002) Fixed libldap MozNSS to be thread safe (ITS#7022) Fixed libldap MozNSS SSL_ForceHandshake to use a mutex (ITS#7034) Fixed libldap MozNSS with wildcard certs (ITS#7006) Fixed liblutil MD5 initialization (ITS#6982) Fixed slapadd common code into slapcommon (ITS#6737) Fixed slapd backend connection initialization (ITS#6993) Fixed slapd frontend DB parsing in cn=config (ITS#7016) Fixed slapd hang with {numbered} overlay insertion (ITS#7030) Fixed slapd inet_ntop usage (ITS#6925) Fixed slapd cn=config deletion of bitmasks (ITS#7083) Fixed slapd cn=config modify replace/delete crash (ITS#7065) Fixed slapd schema UTF8StringNormalize with 0 length values (ITS#7059) Fixed slapd with dynamic acls for cn=config (ITS#7066) Fixed slapd response callbacks (ITS#6059,ITS#7062) Fixed slapd no_connection warnings with ldapi (ITS#6548,ITS#7092) Fixed slapd return code processing (ITS#7060) Fixed slapd sl_malloc various issues (ITS#6437) Fixed slapd startup behavior (ITS#6848) Fixed slapd syncrepl crash with non-replicated ops (ITS#6892) Fixed slapd syncrepl with modrdn (ITS#7000,ITS#6472) Fixed slapd syncrepl timeout when using refreshAndPersist (ITS#6999) Fixed slapd syncrepl deletes need a non-empty CSN (ITS#7052) Fixed slapd syncrepl glue for empty suffix (ITS#7037) Fixed slapd results cleanup (ITS#6763,ITS#7053) Fixed slapd validation of args for TLSCertificateFile (ITS#7012) Fixed slapd-bdb/hdb to build entry DN based on parent DN (ITS#5326) Fixed slapd-hdb with zero-length entries (ITS#7073) Fixed slapd-hdb duplicate entries in subtree IDL cache (ITS#6983) Fixed slapo-constraint conversion to back-config (ITS#6986) Fixed slapo-dds tag in refresh response (ITS#6886) Fixed slapo-dds TTL tolerance (ITS#7017) Fixed slapo-lastbind so authTimestamp is manageable (ITS#6873) Fixed slapo-pcache response cleanup (ITS#6981) Fixed slapo-ppolicy pwdAllowUserChange behavior (ITS#7021) Fixed slapo-sssvlv issue with greaterThanorEqual (ITS#6985) Fixed slapo-sssvlv to only return requested attrs (ITS#7061) Fixed slapo-syncprov DSA attribute filtering for Persist mode (ITS#7019) Fixed slapo-syncprov when consumer has newer state of our SID (ITS#7040) Fixed slapo-syncprov crash (ITS#7025) Fixed slapo-unique URI checking of "host" portion (ITS#7018) Fixed contrib/autogroup double-free (ITS#6972) Fixed contrib/smbk5pwd cn=config deletion of bitmasks (ITS#7083) Fixed contrib/smbk5pwd on 64-bit systems (ITS#7082) Build Environment Added missing LDIF form of schema files (ITS#7063) Fixed build for Solaris native compilers (ITS#6992) Fixed creation and installation of slapd.ldif (ITS#7015) Fixed libnet linking (ITS#7071) Documentation admin24 Fix table numbering (ITS#7003) slapd.conf(5) Fixed TLSCACertificateFile information (ITS#7023) ldapmodify(1) Fixed minor typo in -S option description (ITS#7086) ldap_sync(3) Document ldap_sync_destroy (ITS#7028) slapo-unique(5) Fix keyword quoting (ITS#7028) OpenLDAP 2.4.26 Release (2011/06/30) Added libldap LDAP_OPT_X_TLS_PACKAGE (ITS#6969) Fixed libldap MozNSS with CACertDir (ITS#6975) Fixed libldap MozNSS with PR_SetEnv (ITS#6862) Fixed libldap descriptor leak (ITS#6929) Fixed libldap socket leak (ITS#6930) Fixed libldap get option crash (ITS#6931) Fixed libldap lockup (ITS#6898) Fixed libldap ASYNC TLS setup (ITS#6828) Fixed libldap with missing \n terminations (ITS#6947) Fixed tools double free (ITS#6946) Fixed tools verbose output (ITS#6977) Fixed ldapmodify SEGV on invalid LDIF (ITS#6978) Added slapd extra_attrs database option (ITS#6513) Fixed slapd asserts (ITS#6932) Fixed slapd configfile param on windows (ITS#6933) Fixed slapd config with global chaining (ITS#6843) Fixed slapd uninitialized variables (ITS#6935) Fixed slapd config objectclass is readonly (ITS#6963) Fixed slapd entry response with control (ITS#6899) Fixed slapd with unknown attrs (ITS#6819) Fixed slapd normalization of schema RDN (ITS#6967) Fixed slapd operations cache to 10 op limit (ITS#6944) Fixed slapd syncrepl crash with non-replicated ops (ITS#6892) Fixed slapd-bdb/hdb with sparse index ranges (ITS#6961) Fixed slapd-monitor stray code cleanup (ITS#6974) Fixed back-ldap ppolicy updates (ITS#6711) Fixed back-ldap with id-assert (ITS#6817) Fixed slapd-meta reentry issues (ITS#6909) Fixed slapd-sql length of data type (ITS#6657,ITS#6691) Added slapo-accesslog filter matching (ITS#6815) Fixed slapo-accesslog with invalid attrs (ITS#6819) Added slapo-auditlog connID and peername logging (ITS#6936) Fixed slapo-memberof with accesslog (ITS#6329,ITS#6766,ITS#6915) Fixed slapo-pcache with unknown attrs (ITS#6823) Fixed slapo-pcache with '1.1', '+', and '*' attrs (ITS#6950) Fixed slapo-pcache buffersize issues (ITS#6951) Fixed slapo-pcache refresh (ITS#6953) Fixed slapo-pcache with pCacheBind (ITS#6954) Fixed slapo-pcache database corruption (ITS#6831) Fixed slapo-rwm with attributes with no equality rule (ITS#6943) Fixed slapo-sssvlv limits check when global (ITS#6973) Fixed slapo-syncprov with replicated subtrees (ITS#6872) Fixed slapo-unique with managedsait (ITS#6641) Fixed slapo-unique filter with zero-length values (ITS#6901) Added contrib/acl GSS naming extensions ACL module Fixed contrib/smbk5pwd with shadowLastChange (ITS#6955) Build Environment Fixed builds that do not have GETTIMEOFDAY (ITS#6885) Fixed libldap libfetch dependancy (ITS#6889) Documentation ldap_get_dn(3) add man page (ITS#6959) slapd-backends(5) update recommended database backend (ITS#6904) slapd-bdb(5) update recommended database backend (ITS#6904) slapd-hdb(5) update recommended database backend (ITS#6904) slapo-nssov(5) Fixed typo (ITS#6934) admin24 update that cn=config is preferred (ITS#6905) admin24 update information about indexes (ITS#6906) admin24 fix --enable-wrappers option (ITS#6971) admin24 fix typos (ITS#8562) admin24 fix replication sections to include back-mdb (ITS#8563) OpenLDAP 2.4.25 Release (2011/03/26) Fixed ldapsearch pagedresults loop (ITS#6755) Fixed tools for incompatible args (ITS#6849) Fixed libldap MozNSS crash (ITS#6863) Fixed slapd add objectclasses in order (ITS#6837) Added slapd ordering for uidNumber and gidNumber (ITS#6852) Fixed slapd segfault when adding values out of order (ITS#6858) Fixed slapd sortval handling (ITS#6845) Fixed slapd-bdb with slapadd/index quick option (ITS#6853) Fixed slapd-ldap chain cn=config support (ITS#6837) Fixed slapd-ldap chain with slapd.conf (ITS#6857) Fixed slapd-meta deadlock (ITS#6846) Fixed slapo-sssvlv with multiple requests (ITS#6850) Fixed contrib/lastbind install rules (ITS#6238) Fixed contrib/cloak install rules (ITS#6877) Build Environment Fixed windows NT threads build (ITS#6859) Fixed libldap/lberl/util if/else usage (ITS#6832) Fixed Windows odbc32 detection (ITS#6125) Fixed Windows msys build (ITS#6870) Fixed test020 exit codes (ITS#6404) Documentation admin24 guide ldapi usage (ITS#6839) admin24 guide conversion notes (ITS#6834) admin24 guide fix drawback math for syncrepl (ITS#6866) admin24 guide note manpages are definitive (ITS#6855) OpenLDAP 2.4.24 Release (2011/02/10) Added LDIF line wrapping setting (ITS#6645) Added MozNSS support (ITS#6714,ITS#6742,ITS#6790,ITS#6791) Added MozNSS support (ITS#6802,ITS#6811,ITS#6816,ITS#5696) Added libldap cert x500UniqueIdentifier handling (ITS#6741) Added libldap_r,libldap formal concurrency API (ITS#6625,ITS#5421) Added slapadd attribute value checking (ITS#6592) Added slapcat continue mode for problematic DBs (ITS#6482) Added slapd syncrepl suffixmassage support (ITS#6781) Added slapd multiple listener threads (ITS#6780) Added slapd extensible match for ordering rules (ITS#6532) Added slapd-meta paged results control forwarding (ITS#6664) Added slapd-meta subtree-include support (ITS#6801) Added slapd-null back-config support (ITS#6624) Added slapd-sql autocommit support (ITS#6612) Added slapd-sql support for long long keys (ITS#6617) Added slapo-sssvlv multiple sorts per connection (ITS#6686) Added contrib/autogroup LDAP URI with attribute filter (ITS#6536) Added contrib/dupent module (ITS#6630) Added contrib/lastbind (ITS#6238) Added contrib/kinit for kerberos tickets Added contrib/noopsrch for entry counting (ITS#6598) Fixed client tools control logging (ITS#6775) Fixed client tools one time leak (ITS#6778) Fixed liblber to not close invalid sockets (ITS#6585) Fixed liblber unmatched brace handling (ITS#6764) Fixed liblber error setting (ITS#6732) Fixed liblber memory debugging (ITS#6733) Fixed libldap connectionless warnings (ITS#6747) Fixed libldap dnssrv port format specifier (ITS#6644) Fixed libldap EOF handling (ITS#6723) Fixed libldap GnuTLS hang on socket close (ITS#6673) Fixed libldap sasl partial write handling (ITS#6639) Fixed libldap search leak (ITS#6453) Fixed libldap referral chasing (ITS#6602) Fixed libldap leak when chasing referrals (ITS#6744) Fixed libldap url parsing with NULL host (ITS#6653) Fixed libldap ldap_open_internal_connection (ITS#6788) Fixed libldap sync checking for BER errors (ITS#6738) Fixed libldap variable usage (ITS#6813) Fixed liblutil getpass prompts (ITS#6702) Fixed ldapsearch segfault with deref (ITS#6638) Fixed ldapsearch multiple controls parsing (ITS#6651) Fixed slapd SlapReply usage (ITS#6758) Fixed slapd acl parsing overflow (ITS#6611) Fixed slapd acl when resuming parsing (ITS#6804) Fixed slapd Compare operation (ITS#6753) Fixed slapd default config acls with overlays (ITS#6822) Fixed slapd assert control (ITS#5862) Fixed slapd assertions and debugging (ITS#6759) Fixed slapd config leak with olcDbDirectory (ITS#6634) Fixed slapd connectionless warnings (ITS#6747) Fixed slapd listeners destruction (ITS#6736) Fixed slapd to free controls if needed (ITS#6629) Fixed slapd to stop if given unknown options (ITS#6754) Fixed slapd filter leak (ITS#6635) Fixed slapd matching rules for strict ordering (ITS#6722) Fixed slapd when first acl is value dependent (ITS#6693) Fixed slapd modify to return actual error (ITS#6581) Fixed slapd modrdn with empty DN (ITS#6768) Fixed slapd c_authz_backend setting (ITS#6824) Fixed slapd sortvals of attributes with 1 value (ITS#6715) Fixed slapd syncrepl reuse of presence list (ITS#6707) Fixed slapd syncrepl uninitialized return code (ITS#6719) Fixed slapd syncrepl variable initialization (ITS#6739) Fixed slapd syncrepl refresh to use complete cookie (ITS#6807) Fixed slapd-bdb hasSubordinates generation (ITS#6712) Fixed slapd-bdb entry cache delete failure (ITS#6577) Fixed slapd-bdb entry cache leak on multi-core systems (ITS#6660) Fixed slapd-bdb error propagation to overlays (ITS#6633) Fixed slapd-bdb slapadd -q with glued dbs (ITS#6794) Fixed slapd-ldap debug output of timeout (ITS#6721) Fixed slapd-ldap DNSSRV referral chaining (ITS#6565) Fixed slapd-ldap chaining with bind failures (ITS#6607) Fixed slapd-ldap chaining with onelevel scope (ITS#6699) Fixed slapd-ldap chaining with ppolicy (ITS#6540) Fixed slapd-ldap with SASL/EXTERNAL (ITS#6642) Fixed slapd-ldap crasher on matchedDN (ITS#6793) Fixed slapd-ldap with unknown objectClasses (ITS#6814) Fixed slapd-ldif error strings (ITS#6731) Fixed slapd-ndb to honor rootpw setting (ITS#6661) Fixed slapd-ndb hasSubordinates generation (ITS#6712) Fixed slapd-ndb variable initialization (ITS#6806) Fixed slapd-ndb with out of order attributes (ITS#6821) Fixed slapd-meta anon retry with failed auth method (ITS#6643) Fixed slapd-meta rebind proc (ITS#6665) Fixed slapd-meta to correctly rebind as user (ITS#6574) Fixed slapd-meta with SASL/EXTERNAL (ITS#6642) Fixed slapd-meta matchedDN return code (ITS#6774) Fixed slapd-meta candidate selection (ITS#6799) Fixed slapd-meta attribute normalization (ITS#6818) Fixed slapd-monitor hasSubordinates generation (ITS#6712) Fixed slapd-monitor abandon processing (ITS#6783) Fixed slapd-monitor entry locks (ITS#6787) Fixed slapd-sock missing newline in Compare operation (ITS#6809) Fixed slapd-sql with null objectClass (ITS#6616) Fixed slapd-sql hasSubordinates generation (ITS#6712) Fixed slapo-accesslog with controls (ITS#6652) Fixed slapo-dynlist Compare operation (ITS#6752) Fixed slapo-dynlist entry handling (ITS#6752) Fixed slapo-memberof CSN generation (ITS#6766) Fixed slapo-memberof log messages (ITS#6748) Fixed slapo-memberof with an empty groupOfNames (ITS#6670) Fixed slapo-memberof with modrdn operations (ITS#6700) Fixed slapo-pcache callback freeing (ITS#6640) Fixed slapo-pcache to ignore undefined attrs (ITS#6600) Fixed slapo-pcache pointer freeing (ITS#6797) Fixed slapo-pcache with negative caching (ITS#6796) Fixed slapo-pcache monitoring cleanup (ITS#6808) Fixed slapo-ppolicy don't update opattrs on consumers (ITS#6608) Fixed slapo-ppolicy to allow userPassword deletion (ITS#6620) Fixed slapo-refint when last group member is deleted (ITS#6663) Fixed slapo-refint with subtree rename (ITS#6730) Fixed slapo-rwm double free (ITS#6720) Fixed slapo-rwm crasher (ITS#6632,ITS#6727) Fixed slapo-rwm entry handling (ITS#6760) Fixed slapo-rwm response hang (ITS#6792) Fixed slapo-sssvlv initialization (ITS#6649) Fixed slapo-sssvlv to not advertise when unused (ITS#6647) Fixed slapo-sssvlv result code (ITS#6685) Fixed slapo-syncprov to send error if consumer is newer (ITS#6606) Fixed slapo-syncprov filter race condition (ITS#6708) Fixed slapo-syncprov active mod race (ITS#6709) Fixed slapo-syncprov to refresh if context is dirty (ITS#6710) Fixed slapo-syncprov CSN updates to all replicas (ITS#6718) Fixed slapo-syncprov sessionlog ordering (ITS#6716) Fixed slapo-syncprov sessionlog with adds (ITS#6503) Fixed slapo-syncprov mutex (ITS#6438) Fixed slapo-syncprov mincsn check with MMR (ITS#6717) Fixed slapo-syncprov control leak (ITS#6795) Fixed slapo-syncprov error codes (ITS#6812) Fixed slapo-translucent entry leak (ITS#6746) Fixed contrib/autogroup install location (ITS#6684) Fixed contrib/autogroup crash with ppolicy (ITS#6684) Fixed contrib/autogroup with non-DN URIs (ITS#6684) Fixed contrib/autogroup with memberOf overlay (ITS#6684) Fixed contrib/cloak when returning multiple entries (ITS#6762) Fixed contrib/nssov to only close socket on shutdown (ITS#6676) Fixed contrib/nssov multi platform support (ITS#6604) Build Environment Added support for [unsigned] long long (ITS#6622) Added slapd support for BDB 5.0+ (ITS#6698) Fixed config.guess/sub to pick up newer OSes (ITS#6547) Fixed libldap mutex code - cleanup (ITS#6672) Fixed libldap unnecessary ifdef's (ITS#6603) Fixed slapd-tester EOF handling (ITS#6723) Fixed slapd-tester filter initialization (ITS#6735) Fixed test scripts with alternate testdir (ITS#6782) Removed antiquated SunOS LWP support (ITS#6669) Documentation admin24 guide fix examples (ITS#6681) admin24 guide typo fixes (ITS#6609) admin24 guide refint rootdn requirement (ITS#6364) admin24 add pcache overlay section (ITS#6521) ldap_open(3) document ldap_set_urllist_proc (ITS#6601) ldap.conf(5) GnuTLS cipher spec info (ITS#6525) slapd.conf(5) GnlTLS cipher spec info (ITS#6525) slapd.conf(5) multi-listener support (ITS#6780) slapd-config(5) GnuTLS cipher spec info (ITS#6525) slapd-config(5) multi-listener support (ITS#6780) slapd-meta(5) note deprecated items (ITS#6800) slapd-meta(5) document subtree-include (ITS#6801) slapo-pcache(5) note rootdn requirement (ITS#6522) slapo-refint(5) rootdn requirement (ITS#6364) OpenLDAP 2.4.23 Release (2010/06/30) Fixed libldap to return server's error code (ITS#6569) Fixed libldap memleaks (ITS#6568) Fixed liblutil off-by-one with delta (ITS#6541) Fixed slapd acls with glued databases (ITS#6468) Fixed slapd syncrepl rid logging (ITS#6533) Fixed slapd modrdn handling of invalid values (ITS#6570) Fixed slapd-bdb hasSubordinates computation (ITS#6549) Fixed slapd-bdb to use memcpy instead for strcpy (ITS#6474) Fixed slapd-bdb entry cache delete failure (ITS#6577) Fixed slapd-ldap to return control responses (ITS#6530) Fixed slapo-ppolicy to use Debug (ITS#6566) Fixed slapo-refint to zero out freed DN vals (ITS#6572) Fixed slapo-rwm to use Debug (ITS#6566) Fixed slapo-sssvlv to use Debug (ITS#6566) Fixed slapo-syncprov lost deletes in refresh phase (ITS#6555) Fixed slapo-valsort to use Debug (ITS#6566) Fixed contrib/nssov network.c missing patch (ITS#6562) Build Environment Fixed test043 attribute sorting (ITS#6553) Documentation slapd-config(5) note default rootdn (ITS#6546) OpenLDAP 2.4.22 Release (2010/04/24) Added slapd SLAP_SCHEMA_EXPOSE flag for hidden schema elements (ITS#6435) Added slapd tools selective iterations (ITS#6442) Added slapd syncrepl TCP keepalive (ITS#6389) Added slapo-ldap idassert-passthru (ITS#6456) Added slapo-pbind Fixed libldap gmtime re-entrancy (ITS#6262) Fixed libldap gssapi off by one error (ITS#6223) Fixed libldap GnuTLS serial length (ITS#6460) Fixed libldap MozNSS context and PEM support (ITS#6432) Fixed libldap referral on bind behavior(ITS#6510) Fixed slapd acl non-entry internal searches (ITS#6481) Fixed slapd acl attrval style initialization (ITS#6520) Fixed slapd certificateListValidate (ITS#6466) Fixed slapd empty URI parsing (ITS#6465) Fixed slapd glued misplaced entries (ITS#6506) Fixed slapd glued paged cookies (ITS#6507) Fixed slapd glued paged results (ITS#6504) Fixed slapd gmtime re-entrancy (ITS#6262) Fixed slapd to ignore controls with unrecognized flags (ITS#6480) Fixed slapd entry ownership (ITS#5340) Fixed slapd sasl auxprop_lookup (ITS#6441) Fixed slapd sasl auxprop ssf (ITS#5195) Fixed slapd syncrepl for attributes with no matching rule (ITS#6458) Fixed slapd syncrepl for unknown attrs and delta-sync (ITS#6473) Fixed slapd syncrepl loop with moddn (ITS#6472) Fixed slapo-accesslog to not replicate internal purges (ITS#6519) Fixed slapd-bdb contextCSN updates from updatedn (ITS#6469) Fixed slapd-bdb lockobj zeroing (ITS#6501) Fixed slapd-ldap/meta control criticality (ITS#6523) Fixed slapd-ldap/meta with ordered values (ITS#6516) Fixed slapo-collect entry ownership (ITS#5340,ITS#6423) Fixed slapo-dds with NULL backend (ITS#6490) Fixed slapo-dynlist entry ownership (ITS#5340,ITS#6423) Fixed slapo-memberof attr count (ITS#6508) Fixed slapo-pcache to release its own entries (ITS#6484) Fixed slapo-pcache with NULL backend (ITS#6490) Fixed slapo-rwm entry release handling (ITS#6484) Fixed slapo-rwm memory handling with rewrites (ITS#6526) Fixed slapo-rwm olcRwmMap handling (ITS#6436) Fixed slapo-rwm entry ownership (ITS#5340,ITS#6423) Fixed slapo-syncprov memory leak (ITS#6459) Fixed slapo-translucent counter increment (ITS#6497) Fixed slapo-valsort entry ownership (ITS#5340,ITS#6423) Fixed contrib/sha2 adds mechs for more hashes (ITS#6433) Fixed contrib/nssov to use nss-pam-ldapd (ITS#6488) Build Environment Added back-ldif, back-null test support (ITS#5810) Documentation admin24 avoid explicit moduleload statements (ITS#6486) admin24 broken link fixes (ITS#6493,ITS#6515) slapd.access(5) val.regex explanation (ITS#5804) OpenLDAP 2.4.21 Release (2009/12/20) Fixed liblutil for negative microsecond offsets (ITS#6405) Fixed slapd global settings to work without restart (ITS#6428) Fixed slapd looping with SSL/TLS connections (ITS#6412) Fixed slapd syncrepl freeing tasks from queue (ITS#6413) Fixed slapd syncrepl parsing of tls defaults (ITS#6419) Fixed slapd syncrepl uninitialized variables (ITS#6425) Fixed slapd-config Adds with Abstract classes (ITS#6408) Fixed slapo-dynlist behavior with simple filters (ITS#6421) Fixed slapd-ldif access outside database directory (ITS#6414) Fixed slapd-null extraneous assert (ITS#6403) Fixed slapo-translucent with back-null (ITS#6403) Fixed slapo-unique criteria checking (ITS#6270) Build Environment Deleted broken LBER_INVALID macro (ITS#6402) Fixed test058 kill usage (ITS#6420) Fixed meta regression test (ITS#6418) Documentation slapd-meta(5) Note deprecated functions (ITS#6424) admin24 fix set example for group of groups (ITS#6382) admin24 fix dynamic group documentation (ITS#6290) OpenLDAP 2.4.20 Release (2009/11/27) Fixed client tools with LDAP options (ITS#6283) Fixed liblber embedded NUL values in BerValues (ITS#6353) Fixed liblber inverted LBER_USE_DER test (ITS#6348) Fixed liblber to return failure on certain failures (ITS#6344) Fixed libldap connection initialization (ITS#6386) Fixed libldap sasl buffer sizing (ITS#6327,ITS#6334) Fixed libldap uninitialized return value (ITS#6355) Fixed libldap unlimited timeout (ITS#6388) Added slapd handling of hex server IDs (ITS#6297) Added slapd syncrepl contextCSN storing in subentry (ITS#6373) Fixed slapd asserts in minimal environment (ITS#6361) Fixed slapd authid-rewrite parsing (ITS#6392) Fixed slapd checks of str2filter (ITS#6391) Fixed slapd configArgs initialization (ITS#6363) Fixed slapd debug handling of LDAP_DEBUG_ANY (ITS#6324) Fixed slapd db_open with connection_fake_init (ITS#6381) Fixed slapd with embedded \0 in bervals (ITS#6378,ITS#6379) Fixed slapd inclusion of ac/unistd.h (ITS#6342) Fixed slapd invalid dn log message (ITS#6309) Fixed slapd lockup on shutdown (ITS#6372) Fixed slapd onetime leak (ITS#6398) Fixed slapd RID range to be decimal only (ITS#6394) Fixed slapd sl_free to better reclaim memory (ITS#6380) Fixed slapd syncrepl deletes in MirrorMode (ITS#6368) Fixed slapd syncrepl to use correct SID (ITS#6367) Fixed slapd termination for one level DNs (ITS#6338) Fixed slapd tls_accept to retry in certain cases (ITS#6304) Fixed slapd-bdb/hdb cache corruption (ITS#6341) Fixed slapd-bdb/hdb entry cache (ITS#6360) Fixed slapd-ldap leak (ITS#6326) Fixed slapd-relay bind segfault (ITS#6337) Fixed slapo-accesslog ensure CSNs are normalized (ITS#6400) Fixed slapo-memberof operational attr updates (ITS#6329) Fixed slapo-pcache entry dupe (ITS#6310) Fixed slapo-syncprov checkpoint conversion (ITS#6370) Fixed slapo-syncprov deadlock (ITS#6335) Fixed slapo-syncprov memory leak (ITS#6376) Fixed slapo-syncprov out of order changes (ITS#6346) Fixed slapo-syncprov psearch with stale cookie (ITS#6397) Build Environment Added additional operations for ITS#6332 Fixed memrchr define (ITS#6351) Fixed slapd MAXPATHLEN handling (ITS#6342) Added test050 rapid add/mod/del sequence (ITS#6368) Fixed test057 handling of memberof/refint (ITS#6343) Fixed slapd test error ignoring (ITS#6345) Fixed liblutil constant (ITS#5909) Documentation admin24 fix RFC4511 and other references (ITS#6399) ldap_get_dn(3) typos (ITS#5366) ldap.conf(5) clarify comment usage (ITS#6384) slapd.conf(5) note hex server IDs (ITS#6297) slapd-config(5) note hex server IDs (ITS#6297) OpenLDAP 2.4.19 Release (2009/10/06) Fixed client tools with null timeouts (ITS#6282) Fixed slapadd to warn about missing attrs for replicas (ITS#6281) Fixed slapd acl cache (ITS#6287) Fixed slapd tools to allow -n for conversion (ITS#6258) Fixed slapd-ldap with null timeouts (ITS#6282) Fixed slapd-ldap with strong binds with relay/translucent (ITS#6296) Fixed slapd-ldif buffer overflow (ITS#6303) Fixed slapo-auditlog comments when modifying (ITS#6286) Fixed slapo-dynlist lock leak (ITS#6308) Fixed slapo-pcache cache corruption (ITS#6242) Fixed slapo-sssvlv sort control dereferencing (ITS#6288) Fixed contrib/autogroup segfaults (ITS#6279) Fixed contrib/nssov getgroupbymembers (ITS#6291) Fixed contrib/smbk5pwd rpath linking (ITS#6323) Build Environment Fixed --enable-deref support (ITS#6311) Fixed contrib/autogroup default libtool path (ITS#6284) Deleted nadf.schema (ITS#6140) OpenLDAP 2.4.18 Release (2009/09/06) Fixed client tools common options (ITS#6049) Fixed liblber speed and other problems (ITS#6215) Added libldap MozNSS PEM support (ITS#6278) Added libldap option for SASL_USERNAME (ITS#6257) Fixed libldap error parsing (ITS#6197) Fixed libldap native getpass usage (ITS#4643) Fixed libldap tls_check_hostname for OpenSSL and MozNSS (ITS#6239) Added slapd tcp buffers support (ITS#6234) Fixed slapd allow mirrormode to be set to FALSE (ITS#5946) Fixed slapd certificate list parsing (ITS#6241) Fixed slapd writers blocking (ITS#6276) Fixed slapd dncachesize behavior to unlimited by default (ITS#6222) Fixed slapd incorrectly applying writetimeout when not set (ITS#6220) Fixed slapd with duplicate empty lines for olcDbConfig (ITS#6240) Fixed slapd server URL matching (ITS#5942) Fixed slapd subordinate needs a suffix (ITS#6216) Fixed slapd syncrepl decrement on possible NULL value (ITS#6256) Fixed slapd tools to properly close database (ITS#6214) Fixed slapd uninitialized SlapReply components (ITS#6101) Fixed slapd-meta starttls with targets (ITS#6190) Fixed slapd-monitor stats with glued subordinates (ITS#6243) Fixed slapd-ndb startup (ITS#6203) Fixed slapd-relay various issues (ITS#6133) Fixed slapd-relay response/cleanup callback mismatch (ITS#6154) Fixed slapd-sql with baseObject query (ITS#6172) Fixed slapd-sql with empty attribute (ITS#6163) Fixed slapo-dynlist uninitialized var (ITS#6266) Fixed slapo-pcache multiple enhancements (ITS#6152,ITS#5178) Fixed slapo-ppolicy updating operational attributes (ITS#6265) Fixed slapo-translucent attribute return (ITS#6254) Fixed slapo-translucent filter matching (ITS#6255) Fixed slapo-translucent to honor sizelimit (ITS#6253) Fixed slapo-unique filter matching (ITS#6077) Fixed tools off by one error (ITS#6233) Fixed tools resource leaks (ITS#6145) Added contrib/allowed (ITS#4730) Fixed contrib/autogroup with RE24 (ITS#6227) Fixed contrib/nss symbols (ITS#6273) Build Environment Tests note which backend is being tested (ITS#5810) Fixed test056-monitor with custom ports (ITS#6213) Documentation admin24 fix broken link (ITS#6264) ldap_open(3) document URI (ITS#6261) ldap_set/get_option(3) SASL/TLS options added (ITS#6260) man page format updates (ITS#6023) OpenLDAP 2.4.17 Release (2009/07/13) Fixed liblber to use ber_strnlen (ITS#6080) Fixed libldap GnuTLS private key init (ITS#6053) Fixed libldap openssl digest initialization (ITS#6192) Fixed libldap tls NULL error messages (ITS#6079) Fixed libldap_r missing stub (ITS#6188) Fixed liblutil opendir/closedir on windows (ITS#6041) Fixed liblutil for _GNU_SOURCE (ITS#5464,ITS#5666) Added slapd sasl auxprop support (ITS#6147) Added slapd schema checking tool (ITS#6150) Added slapd writetimeout keyword (ITS#5836) Fixed slapd abandon/cancel handling for some ops (ITS#6157) Fixed slapd access setstyle to expand (ITS#6179) Fixed slapd assert with closing connections (ITS#6111) Fixed slapd bind race condition (ITS#6189) Fixed slapd cancel behavior (ITS#6137) Fixed slapd cert validation (ITS#6098) Fixed slapd connection_destroy assert (ITS#6089) Fixed slapd csn normalization (ITS#6195) Fixed slapd errno handling (ITS#6037) Fixed slapd global alloc handling (ITS#6054) Fixed slapd hung writers (ITS#5836) Fixed slapd ldapi issues (ITS#6056) Fixed slapd moduleload with static backends and modules (ITS#6016) Fixed slapd normalization of updated schema attributes (ITS#5540) Fixed slapd olcLimits handling (ITS#6159) Fixed slapd olcLogLevel with hex levels (ITS#6162) Fixed slapd pagedresults stacked control with overlays (ITS#6056) Fixed slapd password-hash incorrect limit on arg length (ITS#6139) Fixed slapd readonly restrictions (ITS#6109) Fixed slapd sending cancelled operations results (ITS#6103) Fixed slapd slapi_entry_has_children (ITS#6132) Fixed slapd sockets usage on windows (ITS#6039) Fixed slapd some abandon and cancel race conditions (ITS#6104) Fixed slapd tls context after changes (ITS#6135) Fixed slapd-bdb/hdb adjust dncachesize if too low (ITS#6176) Fixed slapd-bdb/hdb crashes during delete (ITS#6177) Fixed slapd-bdb/hdb multiple olcIndex for same attr (ITS#6196) Fixed slapd-hdb freeing of already freed entries (ITS#6074) Fixed slapd-hdb entryinfo cleanup (ITS#6088) Fixed slapd-hdb dncache lockups (ITS#6095) Fixed slapd-ldap deadlock with non-responsive TLS URIs (ITS#6167) Fixed slapd-relay to return failure on failure (ITS#5328) Fixed slapd-sql with BACKSQL_ARBITRARY_KEY defined (ITS#6100) Fixed slapo-collect collectinfo ordering (ITS#6076) Fixed slapo-collect missing equality match rule (ITS#6075) Fixed slapo-dds entry expiration (ITS#6169) Fixed slapo-perl symbols (ITS#5658) Fixed slapo-ppolicy to honor pwdLockout (ITS#6168) Fixed slapo-ppolicy to return check modules error message (ITS#6082) Fixed slapo-refint refint_repair handling (ITS#6056) Added slapo-rwm rwm-drop-unrequested-attrs config option (ITS#6057) Fixed slapo-rwm dn passing (ITS#6070) Fixed slapo-rwm entry free (ITS#6058) Fixed slapo-rwm entry release (ITS#6081) Fixed slapo-translucent entry gathering (ITS#6156) Fixed tools returning ldif errors (ITS#5892) Fixed contrib/smbk5pwd use of private functions (ITS#5535) Build Environment Added test056-monitor (ITS#5540) Added test057-memberof-refint (ITS#5395) Fixed winsock detection for windows (ITS#6102, ITS#6078) Removed GSSAPI configure option (ITS#6091,ITS#6092,ITS#6093,ITS#5369) Documentation admin24 relocate configuration examples (ITS#6183) admin24 fixed example regex (ITS#6052) admin24 removed temporary back-monitor note (ITS#6130) admin24 slapd.conf to cn=config conversion process (ITS#6060) man page consistency fixes (ITS#6023) ldapcompare(1) note -e option (ITS#6107) ldapdelete(1) note -e option (ITS#6107) ldapmodify(1) note -e option (ITS#6107) ldapmodrdn(1) note -e option (ITS#6107) ldapsearch(1) output format description (ITS#6146) ldapurl(1) note -e option (ITS#6107) ldapwhoami(1) note -e option (ITS#6107) ldap_result(3) Add RETURN VALUE heading (ITS#6180) ldap.conf(5) improve sizelimit/timelimit limits (ITS#6127) slapd.access(5) Fix <setstyle> to use expand (ITS#6179) slapd.conf(5) document default modulepath (ITS#5829) slapd.conf(5) pidfile/argsfile description fix (ITS#5975) slapd-config(5) document default modulepath (ITS#5829) slapd-config(5) pidfile/argsfile description fix (ITS#5975) slapo-constraint(5) clarify URI example (ITS#6118) slapo-unique(5) explicitly note rootdn requirement (ITS#6108) slapadd(8) note it does indexing (ITS#6160) OpenLDAP 2.4.16 Release (2009/04/05) Fixed libldap GnuTLS with x509v1 CA certs (ITS#5992) Fixed libldap GnuTLS with CA chains (ITS#5991) Fixed libldap GnuTLS TLSVerifyClient try (ITS#5981) Fixed libldap segfault in checking cert/DN (ITS#5976) Fixed libldap peer cert double free (ITS#5849) Fixed libldap referral chasing (ITS#5980) Fixed slapd backglue with empty DBs (ITS#5986) Fixed slapd ctxcsn race condition (ITS#6001) Fixed slapd debug message (ITS#6027) Fixed slapd redundant module loading (ITS#6030) Fixed slapd schema_init freed value (ITS#6036) Fixed slapd syncrepl newCookie sync messages (ITS#5972) Fixed slapd syncrepl hang during shutdown (ITS#6011) Fixed slapd syncrepl too many MMR messages (ITS#6020) Fixed slapd syncrepl skipped entries with MMR (ITS#5988) Fixed slapd-bdb/hdb cachesize handling (ITS#5860) Fixed slapd-bdb/hdb with slapcat with empty dn (ITS#6006) Fixed slapd-bdb/hdb with NULL transactions (ITS#6012) Fixed slapd-ldap incorrect referral handling (ITS#6003,ITS#5916) Fixed slapd-ldap/meta with broken AD results (ITS#5977) Fixed slapd-ldap/meta with invalid attrs again (ITS#5959) Fixed slapo-accesslog interaction with ppolicy (ITS#5979) Fixed slapo-dynlist conversion to cn=config (ITS#6002) Fixed slapo-syncprov newCookie sync messages (ITS#5972) Fixed slapd-syncprov too many MMR messages (ITS#6020) Fixed slapo-syncprov replica lockout (ITS#5985) Fixed slapo-syncprov modtarget tracking (ITS#5999) Fixed slapo-syncprov multiple CSN propagation (ITS#5973) Fixed slapo-syncprov race condition (ITS#6045) Fixed slapo-syncprov sending cookies without CSN (ITS#6024) Fixed slapo-syncprov skipped entries with MMR (ITS#5988) Fixed tools passphrase free (ITS#6014) Build Environment Cleaned up alloc/free functions for Windows (ITS#6005) Fixed running of autosave files in testsuite (ITS#6026) Documentation admin24 clarified MMR URI requirements (ITS#5942,ITS#5987) Added ldapexop(1) manual page (ITS#5982) slapd-ldap/meta(5) added missing TLS options (ITS#5989) OpenLDAP 2.4.15 Release (2009/02/24) Fixed libldap alias dereferencing in C API again (ITS#5916) Fixed libldap GnuTLS compilation (ITS#5955) Fixed slapd bconfig conversion again (ITS#5346) Fixed slapd behavior with superior objectClasses again (ITS#5517) Fixed slapd RFC4512 behavior with same attr in RDN (ITS#5968) Fixed slapd corrupt contextCSN (ITS#5947) Fixed slapd syncrepl order to match on add/delete (ITS#5954) Fixed slapd adding rdn with other values (ITS#5965) Fixed slapd-bdb/hdb behavior with unallocatable shm (ITS#5956) Fixed slapd-ldap/meta with entries with invalid attrs (ITS#5959) Fixed slapd-relay control initialization (ITS#5724) Fixed slapo-pcache caching invalid entries (ITS#5927) Fixed slapo-syncprov csn updates (ITS#5969) Fixed slapo-rwm objectClass preservation (ITS#5760) Fixed slapo-rwm rwm_bva_rewrite handling (ITS#5960) Build Environment Fixed tester library linking for windows (ITS#5740) OpenLDAP 2.4.14 Release (2009/02/14) Added libldap option to disable SASL host canonicalization (ITS#5812) Added libldap TLS_PROTOCOL_MIN (ITS#5655) Added libldap GnuTLS support for TLS_CIPHER_SUITE (ITS#5887) Added libldap GnuTLS setting random file (ITS#5462) Added libldap alias dereferencing in C API (ITS#5916) Fixed libldap chasing multiple referrals (ITS#5853) Fixed libldap deref handling (ITS#5768) Fixed libldap NULL pointer deref (ITS#5934) Fixed libldap peer cert memory leak (ITS#5849) Fixed libldap interaction with GnuTLS CN IP-based matches (ITS#5789) Fixed libldap intermediate response behavior (ITS#5896) Fixed libldap IPv6 address handling (ITS#5937) Fixed libldap_r deref building (ITS#5768) Fixed libldap_r slapd lockup when paused during shutdown (ITS#5841) Added slapd syncrepl default retry setting (ITS#5825) Added slapd val.regex expansion (ITS#5804) Added slapd TLS_PROTOCOL_MIN (ITS#5655) Added slapd slapi_pw_find (ITS#2615,ITS#4359) Added slapd compatibility with MSAD ranged values (ITS#5927) Fixed slapd bconfig to return error codes (ITS#5867) Fixed slapd bconfig encoding incorrectly (ITS#5897) Fixed slapd bconfig dangling pointers (ITS#5924) Fixed slapd behavior with superior objectClasses (ITS#5517) Fixed slapd connection assert (ITS#5835) Fixed slapd epoll handling (ITS#5886) Fixed slapd frontend/backend options handling (ITS#5857) Fixed slapd glue with MMR (ITS#5925) Fixed slapd logging on Windows (ITS#5392) Fixed slapd listener comparison (ITS#5613) Fixed slapd manageDSAit with glue entries (ITS#5921) Fixed slapd relax behavior with structuralObjectClass (ITS#5792) Fixed slapd syncrepl rename handling (ITS#5809) Fixed slapd syncrepl MMR when adding new server (ITS#5850) Fixed slapd syncrepl MMR with deleted entries (ITS#5843) Fixed slapd syncrepl replication with glued DB (ITS#5866) Fixed slapd syncrepl replication with moddn (ITS#5901) Fixed slapd syncrepl replication with referrals (ITS#5881) Fixed slapd syncrepl replication with config tree (ITS#5935) Fixed slapd wake_sds close on Windows (ITS#5855) Fixed slapd-bdb/hdb dncachesize handling (ITS#5860) Fixed slapd-bdb/hdb RFC4528 control support (ITS#5861) Fixed slapd-bdb/hdb trickle task usage (ITS#5864) Fixed slapd-hdb idlcache with empty suffix (ITS#5859) Fixed slapd-ldap idassert-bind validity checking (ITS#5863) Fixed slapd-ldap/meta RFC4525 increment support (ITS#5912) Fixed slapd-ldap/meta search dereferencing (ITS#5916) Fixed slapd-ldap/meta with intermediate response (ITS#5931) Fixed slapd-ldif numerous bugs (ITS#5408) Fixed slapd-ldif rename on same DN (ITS#5319) Fixed slapd-ldif deadlock (ITS#5329) Fixed slapd-meta double response sending (ITS#5854) Fixed slapd-meta alias deref for retry (ITS#5889) Fixed slapd-relay recursion detection (ITS#5943) Fixed slapd-sock descriptor leak (ITS#5939) Fixed slapo-accesslog on glued dbs (ITS#5907) Fixed slapo-dynlist handling of flags (ITS#5898) Fixed slapo-memberof multiple instantiation (ITS#5903) Fixed slapo-pcache filter sorting (ITS#5756) Fixed slapo-ppolicy to not be global (ITS#5858) Fixed slapo-rwm double free (ITS#5923) Fixed slapo-rwm with back-config (ITS#5906) Fixed slapo-rwm olcRwmRewrite modification (ITS#5940) Added slapo-rwm newRDN rewriting (ITS#5834) Added slapadd progress meter (ITS#5922) Updated contrib/addpartial module (ITS#5764) Added contrib/cloak module (ITS#5872) Added contrib/smbk5pwd gcrypt support (ITS#5410) Added contrib/passwd sha2 support (ITS#5660) Build Environment Fixed test006 appending to log file (ITS#5910) Fixed test036,test039 behavior on error (ITS#5893) Fixed test048 sed pathname substitution (ITS#5910) Fixed test049,test050 to work on windows (ITS#5842) Updated test017,test018,test019 to cover more cases (ITS#5883) Removed patch for BerkeleyDB 4.7.25 (Official patch available) Fixed MSVC 9.0 build issues (ITS#5888) Fixed gss detection on Solaris (ITS#5846) Fixed uuid_create/uuid_unparse_lower detection (ITS#5905) Fixed liblutil tavl_delete to macroize constants (ITS#5909) Documentation admin24 added limits chapter (ITS#5818) admin24 access-control clarify global ACLS (ITS#5851,ITS#5852) admin24 search on nested naming contexts (ITS#5788) admin24 consistent loglevel documentation (ITS#5904) slapd-bdb/hdb expansion on dncachesize behavior (ITS#5721) slapo-constraint(5) example fix (ITS#5895) slap*(8) man pages should mention slapd-config (ITS#5828) slapacl(8c) fix wording (ITS#5918) slapd(8) document sid (ITS#5873) slapd.access(5) clarify global ACLS (ITS#5851,ITS#5852) slapadd/cat/index(8) note -n 0 for slapd-config (ITS#5891) Added SEE ALSO slapd-config(5) to relevant man pages (ITS#5914) OpenLDAP 2.4.13 Release (2008/11/24) Added libldap dereference control support (ITS#5768) Fixed libldap parameter checking (ITS#5817) Fixed liblutil hex conversion (ITS#5699) Fixed liblutil returning undefined data (ITS#5748) Fixed libldap error code return (ITS#5762) Fixed libldap interaction with GnuTLS CN IP-based matches (ITS#5789) Fixed libldap MAXHOSTNAMELEN typo (ITS#5815) Fixed libldap Ipv6 detection (ITS#5739) Fixed libldap setuid usage with .ldaprc (ITS#4750) Fixed slapacl crasher (ITS#5820) Fixed slapd acl checks on ADD (ITS#4556,ITS#5723) Fixed slapd acl application to newly created backends (ITS#5572) Fixed slapd #if/#elif issues in thread includes (ITS#5824) Added slapd keyword add_content_acl for add checks (ITS#4556,ITS#5723) Fixed slapd concurrent access to connections (ITS#5814) Fixed slapd config backend olcLogFile support (ITS#5765) Fixed slapd contextCSN pending list (ITS#5709) Fixed slapd control criticality (ITS#5785) Added slapd dn.this search limits (ITS#5734) Fixed slapd error status on shutdown (ITS#5745) Fixed slapd filter substring handling (ITS#5803) Fixed slapd nameUIDPretty bitstring parsing (ITS#5750) Fixed slapd null termination of password (ITS#5794) Fixed slapd overlay/database open with real structure (ITS#5724) Fixed slapd parsing of read entry control (ITS#5741) Added slapd PMI schema (ITS#5695) Added slapd private databases in global overlays (ITS#5735,ITS#5736) Fixed slapd rdn generation when it isn't specified (ITS#5819) Fixed slapd slapd.conf validation to LDIF (ITS#5755) Fixed slapd startup scan for CSN (ITS#5640) Fixed slapd statslog printing of released entry (ITS#5775) Added slapd support for certificateListExactMatch (ITS#5700) Fixed slapd syncrepl event loss (ITS#5710) Fixed slapd syncrepl MOD of attrs with no EQ rule (ITS#5781) Fixed slapd syncrepl rename handling (ITS#5809) Fixed slapd syncrepl schema checking (ITS#5798) Fixed slapd syncrepl filter leak (ITS#5826) Fixed slapd undef promote (ITS#5783,ITS#5795) Added slapd What failed? control (ITS#5784) Fixed slapd-bdb/hdb invalid db crash (ITS#5698) Added slapd-bdb/hdb dbpagesize keyword Added slapd-bdb/hdb checksum keyword Fixed slapd-bdb/hdb indexing of entryDN (ITS#5790) Fixed slapd-bdb/hdb lookup of entryDN with equality (ITS#5791) Fixed slapd-bdb/hdb uninitialized bli_flag Fixed slapd-ldap snprintf buffer overflow test (ITS#4467) Fixed slapd-ldap search stop on minor failure (ITS#5816) Fixed slapd-ldif file rename on windows (ITS#5774) Fixed slapd-null read controls support (ITS#5757) Fixed slapd-sql value length with right index (ITS#5779) Fixed slapo-chain/translucent back-config support (ITS#5736) Fixed slapo-chain SEGV with search references (ITS#5742) Fixed slapo-collect compile with C89 (ITS#5747) Added slapo-constraint support for LDAP URI constraints (ITS#5704) Added slapo-constraint support for constraining rename (ITS#5703) Added slapo-constraint support for relax control (ITS#5705) Added slapo-constraint "set" type (ITS#5702) Fixed slapo-constraint filter parsing error (ITS#5751) Added slapo-dynlist URI restriction ability (ITS#5761) Fixed slapo-ppolicy unaligned BerElement (ITS#5770) Fixed slapo-rwm objectClass preservation (ITS#5760) Fixed slapo-rwm rewriting undefined filter (ITS#5731) Fixed slapo-rwm rewritten DN-valued attrs (ITS#5772) Fixed slapo-rwm reusing freed filter (ITS#5732) Fixed slapo-rwm entry get (ITS#5773) Fixed slapo-syncprov runqueue removal (ITS#5776) Fixed slapo-syncprov unreplicatable ops (ITS#5709) Fixed slapo-syncprov psearch leak (ITS#5827) Added slapo-translucent try local bind when remote fails (ITS#5656) Added slapo-translucent support for PasswordModify exop (ITS#5656) Fixed tools simple bind without SASL (ITS#5753) Fixed tools unaligned BerElement (ITS#5770) Fixed contrib nssov crash on empty groups (ITS#5800) Fixed contrib nssov crash with nssov-map (ITS#5801) Fixed contrib nssov filter and search limits (ITS#5802) Added contrib smbk5pwd honor principal expiration (ITS#5766) Build Environment Added ldapurl command Added slapd GSSAPI refactoring (ITS#5369) Added slapo-deref overlay (ITS#5768) Documentation admin24 added olcLimits to example (ITS#5746) admin24 consolidated on whitespace (ITS#5759) slapd.conf,config(5) subordinate/olcSubordinate keyword (ITS#5788) slapd.conf(5) fixed disable keyword for limits (ITS#5821) slapo-dds(5) manageDIT to relax (ITS#5780) slapo-dds(5) rootdn requirement added (ITS#5811) slapo-syncprov(5) sessionlog clarification (ITS#5806) OpenLDAP 2.4.12 Release (2008/10/12) Fixed libldap ldap_utf8_strchar arguments (ITS#5720) Fixed libldap TLS_CRLFILE (ITS#5677) Fixed liblutil executables on Windows (ITS#5604) Fixed liblutil microsecond overflows on Windows (ITS#5668) Fixed librewrite memory handling (ITS#5691) Fixed slapd aci performance (ITS#5636) Fixed slapd aci's with sets (ITS#5627) Fixed slapd attribute leak (ITS#5683) Fixed slapd config backend with index greater than sibs (ITS#5684) Fixed slapd custom attribute inheritance (ITS#5642) Fixed slapd dynacl mask handling (ITS#5637) Fixed slapd firstComponentMatch normalization (ITS#5634) Added slapd caseIgnoreListMatch (ITS#5608) Fixed slapd connection events enabled twice (ITS#5725) Fixed slapd memory handling (ITS#5691) Fixed slapd objectClass canonicalization (ITS#5681) Fixed slapd objectClass termination (ITS#5682) Fixed slapd overlay control registration (ITS#5649) Fixed slapd runqueue checking (ITS#5726) Fixed slapd spurious text output (ITS#5688) Fixed slapd socket closing on Windows (ITS#5606) Fixed slapd sortvals comparison (ITS#5578) Added slapd substitute syntax support (ITS#5663) Fixed slapd syncrepl contextCSN detection (ITS#5675) Fixed slapd syncrepl error logging (ITS#5618) Fixed slapd syncrepl runqueue interval (ITS#5719) Fixed slapd-bdb entry return if attr not present (ITS#5650) Fixed slapd-bdb olcDbMode syntax (ITS#5713) Fixed slapd-bdb/hdb release search entries earlier (ITS#5728,ITS#5730) Fixed slapd-bdb/hdb subtree search with empty suffix (ITS#5729) Fixed slapd-dnssrv memory handling (ITS#5691) Fixed slapd-ldap,slapd-meta invalid filter behavior (ITS#5614) Fixed slapd-meta memory handling (ITS#5691) Fixed slapd-meta objectClass filtering (ITS#5647) Fixed slapd-meta quarantine behavior (ITS#5592) Added slapd-ndb experimental backend Fixed slapd-relay initialization (ITS#5643) Fixed slapd-sql freeing of connection (ITS#5607) Fixed slapd-sql fault on NULL fields (ITS#5653) Fixed slapo-accesslog entryCSN generation on purge (ITS#5694) Fixed slapo-constraint string termination (ITS#5609) Fixed slapo-dynlist expansion with mapped attributes (ITS#5717) Fixed slapo-memberof internal operations DN (ITS#5622) Fixed slapo-pcache attrset crash (ITS#5665) Fixed slapo-pcache caching with invalid schema (ITS#5680) Fixed slapo-ppolicy control return on password modify exop (ITS#5711) Fixed slapo-rwm callback cleanup (ITS#5601,ITS#5687) Fixed slapo-rwm attr mapping and merging (ITS#5624) Fixed slapo-rwm objectClass filtering (ITS#5647) Fixed slapo-translucent back-config support (ITS#5689) Fixed slapo-translucent filter usage on merged entries (ITS#5679) Fixed slapo-unique filter validation (ITS#5581) Fixed slapo-unique suffix testing (ITS#5641) Build Environment Fixed ODBC library detection (ITS#5602) Removed pre-BerkeleyDB 4.4 support Added BerkeleyDB 4.7 support (ITS#5523) Included patch for BerkeleyDB 4.7.25 (build/db.4.7.25.patch) Added slapo-collect overlay with enhancements(ITS#5659) Documentation Added slapd-ldap(5), slapd-meta(5) noundeffilter (ITS#5614) Fixed slapd-ldap(5), slapd-meta(5), slapo-pcache(5) schema requirements (ITS#5680) Added slapo-collect(5) man page (ITS#5706) Added slapo-pcache(5) proxycheckcacheability option (ITS#5680) Added slapo-retcode(5) retcode.conf location (ITS#5633) admin24 dontusecopy control update (ITS#5718) admin24 guide updates (ITS#5616) admin24 octetString fix (ITS#5670) OpenLDAP 2.4.11 Release (2008/07/16) Fixed liblber ber_get_next length decoding (ITS#5580) Added libldap assertion control (ITS#5560) Fixed libldap GnuTLS CRL result handling (ITS#5577) Fixed libldap GnuTLS SSF computation (ITS#5585) Fixed liblutil missing return code (ITS#5615) Fixed slapd cert serial number parsing (ITS#5588) Fixed slapd check for structural_class failures (ITS#5540) Fixed slapd config backend renumbering (ITS#5571) Fixed slapd configContext OID (ITS#5383) Fixed slapd crash with no listeners (ITS#5563) Fixed slapd equality rules for olcRootDN/olcSchemaDN (ITS#5540) Fixed slapd sets memory leak (ITS#5557) Fixed slapd sortvals binary search (ITS#5578) Fixed slapd syncrepl updates with multiple masters (ITS#5597) Fixed slapd syncrepl superior objectClass delete/add (ITS#5600) Fixed slapd syncrepl/slapo-syncprov contextCSN updates as internal ops (ITS#5596) Added slapd-ldap/slapd-meta option to filter out search references (ITS#5593) Fixed slapd-meta link to slapd-ldap (ITS#5355) Fixed slapd-sock, back-shell buffer count (ITS#5558) Fixed slapo-dynlist dg attrs lookup (ITS#5583) Fixed slapo-dynlist entry release (ITS#5135) Fixed slapo-memberof replace handling (ITS#5584) Added slapo-nssov contrib module Fixed slapo-pcache handling of negative search caches (ITS#5546) Fixed slapo-ppolicy DNs with whitespaces (ITS#5552) Fixed slapo-ppolicy modify with internal ops (ITS#5569) Fixed slapo-syncprov ACL evaluation (ITS#5548) Fixed slapo-syncprov crash with delcsn (ITS#5589) Fixed slapo-syncprov full reload (ITS#5564) Fixed slapo-syncprov missing olcSpReloadHint attr(ITS#5591) Fixed slapo-unique filter normalization (ITS#5581) Fixed contrib smbk5pwd terminator (ITS#5575) Build Environment Fixed test048 to skip if threads is not available (ITS#5529) Documentation Added slapo-pcache(5) sizelimit caching (ITS#5559) Added slapd-access(5) add and delete privs (ITS#5566) admin24 GnuTLS documentation (ITS#5554) 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) Fixed libldap_r tpool pause checks (ITS#5364, #5407) Fixed slapcat error checking (ITS#5387) Fixed slapd abstract objectClass inheritance check (ITS#5474) Fixed slapd add operations requiring naming attrs (ITS#5412) Fixed slapd connection handling (ITS#5469) Fixed slapd delta-syncrepl resync (ITS#5378) Fixed slapd frontendDB backend selection (ITS#5419) Fixed slapd pagedresults stale state (ITS#5409) Fixed slapd pointer dereference (ITS#5388) Fixed slapd null argument dereference (ITS#5435) Fixed slapd REP_ENTRY flags (ITS#5340) Fixed slapd sets attribute description parsing (ITS#5402) Fixed slapd syncrepl hang on back-config (ITS#5407) Fixed slapd syncrepl compare_csns crash (ITS#5413) Fixed slapd syncrepl contextCSN update clash (ITS#5426) Fixed slapd syncrepl/glue failure (ITS#5430) Fixed slapd syncrepl crash on empty CSN (ITS#5432) Fixed slapd syncrepl refreshAndPersist (ITS#5454) Fixed slapd syncrepl modrdn processing (ITS#5397) Fixed slapd syncrepl MMR partial refresh (ITS#5470) Fixed slapd value list termination (ITS#5450) Fixed slapd/slapo-accesslog rq mutex usage (ITS#5442) Fixed slapd-bdb ID_NOCACHE handling (ITS#5439) Fixed slapd-bdb entryinfo state if db_lock fails (ITS#5455) Fixed slapd-bdb referral rewrite (ITS#5339) Fixed slapd-config overlay stacking (ITS#5346) Fixed slapd-config attribute publishing (ITS#5383) Fixed slapd-ldap connection handler (ITS#5404) Fixed slapd-ldif file name handling & multi-suffix/dir catch (ITS#5408) Fixed slapd-meta connections on error (ITS#5440) Fixed slapd-meta crash on search (ITS#5481) Fixed slapo-accesslog null callback stack crash (ITS#5490) Fixed slapo-auditlog unnecessary syscall (ITS#5441) Added slapo-dynlist mapping to dynamic attrs generation (ITS#5466) Fixed slapo-refint dnSubtreeMatch (ITS#5427) Fixed slapo-refint global referential integrity (ITS#5428) Fixed slapo-syncprov psearch on closed connection (ITS#5401) Fixed slapo-syncprov psearch task delay (ITS#5405) Fixed slapo-syncprov psearch filter identity (ITS#5418, #5486) Fixed slapo-syncprov/glue contextCSN update (ITS#5433) Fixed slapo-syncprov/glue search ops (ITS#5434) Fixed slapo-syncprov null cookie (ITS#5437,#5444) Fixed slapo-syncprov double-free (ITS#5445) Fixed slapo-syncprov free syncop correctly (ITS#5484) Fixed slapo-syncprov glue deadlock (ITS#5451) Build Environment Fixed leave function naming for OSF1 (ITS#5411) Documentation Fixed slapd.access(5) authz-regexp documented behavior (ITS#5400) Fixed slapd.meta(5) idassert-* documentation (ITS#5406) admin24 delta-syncrepl documentation (ITS#5476) admin24 set documentation (ITS#5278,ITS#5279,ITS#5281) admin24 slapo-ppolicy documentation (ITS#5479) admin24 syncrepl directives update (ITS#5425) OpenLDAP 2.4.8 Release (2008/02/19) Fixed ldapmodify verbose logging (ITS#5247) Fixed ldapdelete with sizelimit (ITS#5294) Fixed ldapdelete with subentries control (ITS#5293) Fixed ldapsearch exit code init (ITS#5317) Fixed libldap extended decoding (ITS#5304) Fixed libldap filter abort (ITS#5300) Fixed libldap ldap_parse_sasl_bind_result (ITS#5263) Fixed libldap result codes for open (ITS#5338) Fixed libldap search timeout crash (ITS#5291) Fixed libldap paged results crash (ITS#5315) Fixed libldap cipher suite with GnuTLS (ITS#5341) Fixed slapd support for 2.1 CSN (ITS#5348) Fixed slapd include handling (ITS#5276) Fixed slapd modrdn check for valid new DN (ITS#5344) Fixed slapd multi-step SASL binds (ITS#5298) Fixed slapd non-atomic signal variables (ITS#5248) Fixed slapd overlay ordering when moving to slapd.d (ITS#5284) Fixed slapd NULL printf (ITS#5264) Fixed slapd NULL set values (ITS#5286) Fixed slapd SEGV with SASL/OTP (ITS#5259) Fixed slapd timestamp race condition (ITS#5370) Fixed slapd cn=config crash on delete (ITS#5343) Fixed slapd cn=config global acls (ITS#5352) Fixed slapd truncated cookie (ITS#5362) Fixed slapd sasl with CLEARTEXT (ITS#5368) Fixed slapd str2entry with no attrs (ITS#5308) Fixed slapd TLSVerifyClient default (ITS#5360) Fixed slapd HAVE_TLS dependency (ITS#5379) Fixed slapd delta-syncrepl refresh mode (ITS#5376) Fixed slapd ACL sets URI attrs (ITS#5384) Fixed slapd invalid entryUUID filter (ITS#5386) Fixed slapd-bdb idlcache on adds (ITS#5086) Fixed slapd-bdb crash with modrdn (ITS#5358) Fixed slapd-bdb SEGV with bdb4.6 (ITS#5322) Fixed slapd-bdb modrdn to same dn (ITS#5319) Fixed slapd-bdb MMR (ITS#5332) Added slapd-bdb/slapd-hdb DB encryption (ITS#5359) Fixed slapd-ldif delete (ITS#5265) Fixed slapd-meta link to slapd-ldap (ITS#5355) Fixed slapd-meta setting of sm_nvalues (ITS#5375) Fixed slapd-monitor crash (ITS#5311) Fixed slapd-relay compare (ITS#4937) Added slapd-sock (ITS#4094) Fixed slapo-accesslog cleanup on successful response (ITS#5374) Added slapo-autogroup contrib module (ITS#5145) Added slapo-constraint cross-attribute constraints (ITS#4987) Fixed slapo-memberof objectClass inheritance (ITS#5299) Added slapo-memberof global overlay support (ITS#5301) Fixed slapo-memberof leak (ITS#5302) Fixed slapo-ppolicy only password check with policy (ITS#5285) Fixed slapo-ppolicy del/replace password without new one (ITS#5373) Fixed slapo-syncprov hang on checkpoint (ITS#5261) Added slapo-translucent local searching (ITS#5283) Removed lint Build Environment Fixed libldap_r threaded library linking (ITS#4982) Fixed libldap use of %n (ITS#5324) Fixed test047 to skip if rwm is not available (ITS#5292) Documentation DB_CONFIG.example URL wrong in comments (ITS#5288) Add cn=config example for auditlog (ITS#5245) ldapmodify(1) clarification for RFC2849 (ITS#5312) OpenLDAP 2.4.7 Release (2007/12/14) Added slapd ordered indexing of integer attributes (ITS#5239) Fixed slapd paged results control handling (ITS#5191) Fixed slapd sasl-host parsing (ITS#5209) Fixed slapd filter normalization (ITS#5212) Fixed slapd multiple suffix checking (ITS#5186) Fixed slapd paged results handling when using rootdn (ITS#5230) Fixed slapd syncrepl presentlist handling (ITS#5231) Fixed slapd core schema 'c' definition for RFC4519 (ITS#5236) Fixed slapd 3-way Multi-Master Replication (ITS#5238) Fixed slapd hash collisions in index slots (ITS#5183) Fixed slapd replication of dSAOperation attributes (ITS#5268) Fixed slapadd contextCSN updating (ITS#5225) Fixed slapd-bdb/hdb to report and fail on internal errors (ITS#5232) Fixed slapd-bdb/hdb dn2entry lock bug (ITS#5257) Fixed slapd-bdb/hdb dn2id lock bug (ITS#5262) Fixed slapd-hdb caching on rename ops (ITS#5221) Fixed slapo-accesslog abandoned op cleanup (ITS#5161) Fixed slapo-dds deleting from nonexistent db (ITS#5267) Fixed slapo-memberOf deleted values saving (ITS#5258) Fixed slapo-pcache op->o_abandon handling (ITS#5187) Fixed slapo-ppolicy single password check on modify (ITS#5146) Fixed slapo-ppolicy internal search (ITS#5235) Fixed slapo-syncprov refresh and persist cookie sending (ITS#5210) Fixed slapo-syncprov ignore invalid cookies (ITS#5211) Fixed slapo-translucent interaction with slapo-rwm (ITS#4889) Updated contrib addpartial module (ITS#3593) Build Environment Fixed liblber socket library linking (ITS#5224) Fixed Windows slapd.def rules (ITS#5215) Documentation Fixed grammar errors (ITS#5223) Refint overlay doc contribution (ITS#5217) Dynamic Lists doc contribution to the admin guide (ITS#5216) Fixed ldappasswd(1) and ldapmodify(1) typos (ITS#5269) Fixed domain factor typos (ITS#5237) Fixed slapd.conf(5) maxderefdepth default value typo (ITS#5200) Clarified slapd.conf(5) limits issues in syncrepl (ITS#5243) Fixed slapd-config(5) maxderefdepth default value typo (ITS#5200) Patches for minor typos in man pages (ITS#5228) admin24/replication.sdf spelling (ITS#5270) OpenLDAP 2.4.6 Release (2007/10/31) Initial release for "general use". PK "�c\�ѥ� � doc/alt-openldap11/ANNOUNCEMENTnu �[��� A N N O U N C E M E N T -- OpenLDAP 2.4 The OpenLDAP Project is pleased to announce the availability of OpenLDAP Software 2.4, a suite of the Lightweight Directory Access Protocol (v3) servers, clients, utilities, and development tools. This release contains the following major enhancements: * Slapd(8) enhancements - Syncrepl enhancements, including push-mode and Multi-Master support - Dynamic configuration enhancements, including online schema editing and full access control - Dynamic monitoring enhancements, including cache usage information * New overlays - Attribute value constraints - Dynamic Directory Services (RFC2589) - Reverse Group Membership maintenance (memberof) * Clients and tools - Full support of request/response controls - New ldapexop tool for arbitrary extend operations - Support of DNS SRV records for default server * Significant performance enhancements throughout the client and server code base * Multiple new features in libldap and liblber * Expanded documentation - Function-complete manual pages - Numerous new examples in the Admin Guide This release includes the following major components: * slapd - a stand-alone LDAP directory server * -lldap - a LDAP client library * -llber - a lightweight BER/DER encoding/decoding library * LDIF tools - data conversion tools for use with slapd * LDAP tools - A collection of command line LDAP utilities * Admin Guide, Manual Pages - associated documentation In addition, there are some contributed components: * LDAPC++ - a LDAP C++ SDK * Various slapd modules and slapi plugins ACKNOWLEDGEMENTS OpenLDAP Software is developed by the OpenLDAP Project. The Project consists of a team of volunteers who use the Internet to coordinate their activities. The Project is an organized activity of the OpenLDAP Foundation. OpenLDAP Software is derived from University of Michigan LDAP, release 3.3. AVAILABILITY This software is available under the OpenLDAP Public License, an non-restrictive, "free", open-source license. Download information is available at: http://www.OpenLDAP.org/software/download/ SUPPORT OpenLDAP Software is user supported: http://www.openldap.org/support/ The OpenLDAP Administrator's Guide, which includes quick start instructions, is available at: http://www.openldap.org/doc/admin/ The project maintains a FAQ which you may find useful: http://www.openldap.org/faq/ In addition, there are also a number of discussion lists related to OpenLDAP Software. A list of mailing lists is available at: http://www.OpenLDAP.org/lists/ To report bugs, please use project's Issue Tracking System: http://www.openldap.org/its/ The OpenLDAP home page containing lots of interesting information and online documentation is available at this URL: http://www.OpenLDAP.org/ SUPPORTED PLATFORMS This release has been ported to many UNIX (and UNIX-like) platforms including Darwin, FreeBSD, Linux, NetBSD, OpenBSD and most commercial UNIX systems. The release has also been ported (in part or in whole) to other platforms including Apple MacOS X, IBM zOS, and Microsoft Windows NT/2000/etc. --- OpenLDAP is a registered trademark of the OpenLDAP Foundation. Copyright 1999-2018 The OpenLDAP Foundation, Redwood City, California, USA. All Rights Reserved. Permission to copy and distribute verbatim copies of this document is granted. PK "�c\�1�L� � doc/alt-openldap11/READMEnu �[��� OpenLDAP 2.4 README For a description of what this distribution contains, see the ANNOUNCEMENT file in this directory. For a description of changes from previous releases, see the CHANGES file in this directory. This is 2.4 release, it includes significant changes from prior releases. REQUIRED SOFTWARE Building OpenLDAP Software requires a number of software packages to be preinstalled. Additional information regarding prerequisite software can be found in the OpenLDAP Administrator's Guide. Base system (libraries and tools): Standard C compiler (required) Cyrus SASL 2.1.21+ (recommended) OpenSSL 0.9.7+ (recommended) Reentrant POSIX REGEX software (required) SLAPD: BDB and HDB backends require Oracle Berkeley DB 4.4 - 4.8, or 5.0 - 5.1. It is highly recommended to apply the patches from Oracle for a given release. CLIENTS/CONTRIB ware: Depends on package. See per package README. MAKING AND INSTALLING THE DISTRIBUTION Please see the INSTALL file for basic instructions. More detailed instructions can be found in the OpenLDAP Admnistrator's Guide (see DOCUMENTATION section). DOCUMENTATION The OpenLDAP Administrator's Guide is available in the guide.html file in the doc/guide/admin directory. The guide and a number of other documents are available at <http://www.openldap.org/doc/admin/guide.html>. The distribution also includes manual pages for most programs and library APIs. See ldap(3) for details. The OpenLDAP website is available and contains the latest LDAP news, releases announcements, pointers to other LDAP resources, etc.. It is located at <http://www.OpenLDAP.org/>. The OpenLDAP Software FAQ is available at <http://www.openldap.org/faq/>. SUPPORT / FEEDBACK / PROBLEM REPORTS / DISCUSSIONS OpenLDAP Software is user supported. If you have problems, please review the OpenLDAP FAQ <http://www.openldap.org/faq/> and archives of the OpenLDAP-software and OpenLDAP-bugs mailing lists <http://www.openldap.org/lists/>. If you cannot find the answer, please enquire on the OpenLDAP-software list. Issues, such as bug reports, should be reported using our Issue Tracking System <http://www.OpenLDAP.org/its/>. Do not use this system for software enquiries. Please direct these to an appropriate mailing list. CONTRIBUTING See <http://www.openldap.org/devel/contributing.html> for information regarding how to contribute code or documentation to the OpenLDAP Project for inclusion in OpenLDAP Software. While you are encouraged to coordinate and discuss the development activities on the <openldap-devel@openldap.org> mailing list prior to submission, it is noted that contributions must be submitted using the Issue Tracking System <http://www.openldap.org/its/> to be considered. --- $OpenLDAP$ This work is part of OpenLDAP Software <http://www.openldap.org/>. Copyright 1998-2018 The OpenLDAP Foundation. 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>. OpenLDAP is a registered trademark of the OpenLDAP Foundation. PK #�c\!��+V +V ( doc/alt-openldap11-devel/rfc/rfc2294.txtnu �[��� Network Working Group S. Kille Request for Comments: 2294 Isode Ltd. Obsoletes: 1836 March 1998 Category: Standards Track Representing the O/R Address hierarchy in the X.500 Directory Information Tree Status of this Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (1998). All Rights Reserved. Abstract This document defines a representation of the O/R Address hierarchy in the Directory Information Tree [6, 1]. This is useful for a range of purposes, including: o Support for MHS Routing [4]. o Support for X.400/RFC 822 address mappings [2, 5]. Please send comments to the author or to the discussion group <mhs- ds@mercury.udev.cdc.com>. Kille Standards Track [Page 1] RFC 2294 Directory Information Tree March 1998 Object Class Mandatory ------------ --------- mHSCountry M aDMD M pRMD O mHSX121 O mHSNumericUserIdentifier O mHSOrganization O mHSOrganizationalUnit O mHSPerson O mHSNamedObject O mHSTerminalID O mHSDomainDefinedAttribute O Table 1: Order of O/R Address Directory Components 1 The O/R Address Hierarchy An O/R Address hierarchy is represented in the X.500 directory by associating directory name components with O/R Address components. An example of this is given in Figure 1. The object classes and attributes required to support this representation are defined in Figure 2. The schema, which defines the hierarchy in which these objects are represented in the directory information tree is specified in Table 1. A given object class defined in the table will always be higher in the DIT than an object class defined lower down the table. Valid combinations of O/R Address components are defined in X.400. Kille Standards Track [Page 2] RFC 2294 Directory Information Tree March 1998 /\ / \ C=GB / \ Numeric-C=234 / \ / \ / \ +------------+<----------------+----+ | Country | | | +------------+ +----+ /\ / \ / \ / \ ADMD=" " / \ ADMD=Gold 400 +-------------+ +------------+ | ADMD | | ADMD | +-------------+ +------------+ \ \ \ \ \ PRMD=UK.AC \ PRMD=UK.AC \ \ +----------+ +----+ | PRMD |< -----------| | +----------+ +----+ / / O=UCL / / +------------+ | MHS-Org | +------------+ \ \ OU=CS \ \ +-----------+ | MHS-OU | +-----------+ Figure 1: Example O/R Address Tree Kille Standards Track [Page 3] RFC 2294 Directory Information Tree March 1998 IMPORTS ub-domain-name-length, ub-organization-name-length, ub-organizational-unit-name-length, ub-common-name-length, ub-x121-address-length, ub-domain-defined-attribute-type-length, ub-domain-defined-attribute-value-length, ub-terminal-id-length, ub-numeric-user-id-length, ub-country-name-numeric-length, ub-surname-length, ub-given-name-length, ub-initials-length, ub-generation-qualifier-length FROM MTSUpperBounds {joint-iso-ccitt mhs-motis(6) mts(3) 10 modules(0) upper-bounds(3) }; mHSCountry OBJECT-CLASS ::= { SUBCLASS OF {country} MAY CONTAIN {mHSNumericCountryName} ID oc-mhs-country} mHSNumericCountryName ATTRIBUTE ::= { WITH SYNTAX NumericString (SIZE (1..ub-country-name-numeric-length)) SINGLE VALUE 20 ID at-mhs-numeric-country-name} aDMD OBJECT-CLASS ::= { SUBCLASS OF {top} MUST CONTAIN {aDMDName} ID oc-admd} aDMDName ATTRIBUTE ::= { SUBTYPE OF name WITH SYNTAX DirectoryString {ub-domain-name-length} 30 ID at-admd-name} pRMD OBJECT-CLASS ::= { SUBCLASS OF {top} MUST CONTAIN {pRMDName} ID oc-prmd} pRMDName ATTRIBUTE ::= { SUBTYPE OF name WITH SYNTAX DirectoryString {ub-domain-name-length} 40 ID at-prmd-name} mHSOrganization OBJECT-CLASS ::= { SUBCLASS OF {top} MUST CONTAIN {mHSOrganizationName } ID oc-mhs-organization} Kille Standards Track [Page 4] RFC 2294 Directory Information Tree March 1998 mHSOrganizationName ATTRIBUTE ::= { SUBTYPE OF organizationName WITH SYNTAX DirectoryString {ub-organization-name-length} 50 ID at-mhs-organization-name} mHSOrganizationalUnit OBJECT-CLASS ::= { SUBCLASS OF {top} MUST CONTAIN {mHSOrganizationalUnitName} ID oc-mhs-organizational-unit} mHSOrganizationalUnitName ATTRIBUTE ::= { SUBTYPE OF organizationalUnitName 60 WITH SYNTAX DirectoryString {ub-organizational-unit-name-length} ID at-mhs-organizational-unit-name} mHSPerson OBJECT-CLASS ::= { SUBCLASS OF {top} MUST CONTAIN {mHSSurname} MAY CONTAIN {mHSGivenName| mHSInitials| mHSGenerationalQualifier} ID oc-mhs-person} 70 mHSSurname ATTRIBUTE ::= { SUBTYPE OF surname WITH SYNTAX DirectoryString {ub-surname-length} ID at-mhs-surname} mHSGivenName ATTRIBUTE ::= { SUBTYPE OF givenName WITH SYNTAX DirectoryString {ub-given-name-length} ID at-mhs-given-name} 80 mHSInitials ATTRIBUTE ::= { SUBTYPE OF initials WITH SYNTAX DirectoryString {ub-initials-length} ID at-mhs-initials} mHSGenerationQualifier ATTRIBUTE ::= { SUBTYPE OF generationQualifier WITH SYNTAX DirectoryString {ub-generation-qualifier-length} ID at-mhs-generation-qualifier} 90 mHSNamedObject OBJECT-CLASS ::= { SUBCLASS OF {top} MUST CONTAIN {mHSCommonName} ID oc-mhs-named-object} Kille Standards Track [Page 5] RFC 2294 Directory Information Tree March 1998 mHSCommonName ATTRIBUTE ::= { SUBTYPE OF commonName WITH SYNTAX DirectoryString {ub-common-name-length} ID at-mhs-common-name} 100 mHSX121 OBJECT-CLASS ::= { SUBCLASS OF {top} MUST CONTAIN {mHSX121Address} ID oc-mhs-x121} mHSX121Address ATTRIBUTE ::= { SUBTYPE OF name WITH SYNTAX DirectoryString {ub-x121-address-length} ID at-x121-address} 110 mHSDomainDefinedAttribute OBJECT-CLASS ::= { SUBCLASS OF {top} MUST CONTAIN { mHSDomainDefinedAttributeType| mHSDomainDefinedAttributeValue} ID oc-mhs-domain-defined-attribute} mHSDomainDefinedAttributeType ATTRIBUTE ::= { SUBTYPE OF name 120 WITH SYNTAX DirectoryString {ub-domain-defined-attribute-type-length} SINGLE VALUE ID at-mhs-domain-defined-attribute-type} mHSDomainDefinedAttributeValue ATTRIBUTE ::= { SUBTYPE OF name WITH SYNTAX DirectoryString {ub-domain-defined-attribute-value-length} SINGLE VALUE ID at-mhs-domain-defined-attribute-value} 130 mHSTerminalID OBJECT-CLASS ::= { SUBCLASS OF {top} MUST CONTAIN {mHSTerminalIDName} ID oc-mhs-terminal-id} mHSTerminalIDName ATTRIBUTE ::= { SUBTYPE OF name WITH SYNTAX DirectoryString {ub-terminal-id-length} ID at-mhs-terminal-id-name} 140 Kille Standards Track [Page 6] RFC 2294 Directory Information Tree March 1998 mHSNumericUserIdentifier OBJECT-CLASS ::= { SUBCLASS OF {top} MUST CONTAIN {mHSNumericUserIdentifierName} ID oc-mhs-numeric-user-id} mHSNumericeUserIdentifierName ATTRIBUTE ::= { SUBTYPE OF name WITH SYNTAX DirectoryString {ub-numeric-user-id-length} 150 ID at-mhs-numeric-user-id-name} Figure 2: O/R Address Hierarchy The hierarchy is defined so that: 1. The representation is defined so that it is straightforward to make a mechanical transformation in either direction. This requires that each node is named by an attribute whose type can determine the mapping. 2. Where there are multiple domain defined attributes, the first in the sequence is the most significant. 3. Physical Delivery (postal) addresses are not represented in this hierarchy. This is primarily because physical delivery can be handled by the Access Unit routing mechanisms defined in [4], and there is no need for this representation. 4. Terminal and network forms of address are not handled, except for X.121 form, which is useful for addressing faxes. 5. MHSCountry is defined as a subclass of Country, and so the same entry will be used for MHS Routing as for the rest of the DIT. 6. The numeric country code will be an alias. 7. ADMD will always be present in the hierarchy. This is true in the case of " " and of "0". This facilitates an easy mechanical transformation between the two forms of address. 8. Each node is named by the relevant part of the O/R Address. 9. Aliases may be used in other parts of the tree, in order to normalize alternate values. Where an alias is used, the value of the alias should be present as an alternate value in the node aliased to. Aliases may not be used for domain defined attributes. Kille Standards Track [Page 7] RFC 2294 Directory Information Tree March 1998 10. Domain Defined Attributes are named by a multi-valued RDN (Relative Distinguished Name), consisting of the type and value. This is done so that standard attribute syntaxes can be used. 11. Where an O/R Address has a valid Printable String and T.61 form, both must be present, with one as an alias for the other. This is so that direct lookup of the name will work, independent of the variant used. When both are present in an O/R Address being looked up, either may be used to construct the distinguished name. 12. Personal name is handled by use of the mHSPerson object class. Each of the components of the personal name will be present in the relative distinguished name, which will usually be multi- valued. The relationship between X.400 O/R Addresses and the X.400 Entries (Attribute Type and Object Class) are given in Table 2. Where there are multiple Organizational Units or Domain Defined Attributes, each component is mapped onto a single X.500 entry. Note: When an X.121 address is used for addressing fax transmission, this may only be done relative to the PRMD or ADMD. This is in line with the current X.400 standards position. This means that it is not possible to use this form of addressing for an organizational or departmental fax gateway service. O/R Address Object Class Naming Attribute ----------- ------------ ---------------- C mHSCountry countryName or mHSNumericCountryName A aDMD aDMDName P pRMD pRMDName O mHSOrganization mHSOrganizationName OU/OU1/OU2 mHSOrganizationalUnit mHSOrganizationalUnitName OU3/OU4 PN mHSPerson personName CN mHSNamedObject mHSCommonName X121 mHSX121 mHSX121Address T-ID mHSTerminalID mHSTerminalIDName UA-ID mHSNumericUserIdentifier mHSNumericUserIdentifierName DDA mHSDomainDefinedAttribute mHSDomainDefinedAttributeType and mHSDomainDefinedAttributeValue Table 2: O/R Address relationship to Directory Name Kille Standards Track [Page 8] RFC 2294 Directory Information Tree March 1998 2 Notation O/R Addresses are written in the standard X.400 Notation. Distinguished Names use the string representation of distinguished names defined in [3]. The keywords used for the attributes defined in this specification are given in Table 3. 3 Example Representation The O/R Address: I=S; S=Kille; OU1=CS; O=UCL, P=UK.AC; A=Gold 400; C=GB; would be represented in the directory as: MHS-I=S + MHS-S=Kille, MHS-OU=CS, MHS-O=UCL, Attribute Keyword --------- ------- mHSNumericCountryName MHS-Numeric-Country aDMDName ADMD pRMDName PRMD mHSOrganizationName MHS-O mHSOrganizationalUnitName MHS-OU mHSSurname MHS-S mHSGivenName MHS-G mHSInitials MHS-I mHSGenerationalQualifier MHS-GQ mHSCommonName MHS-CN mHSX121Address MHS-X121 mHSDomainDefinedAttributeType MHS-DDA-Type mHSDomainDefinedAttributeValue MHS-DDA-Value mHSTerminalIDName MHS-T-ID mHSNumericeUserIdentifierName MHS-UA-ID Table 3: Keywords for String DN Representation PRMD=UK.AC, ADMD=Gold 400, C=GB 4 Mapping from O/R Address to Directory Name The primary application of this mapping is to take an X.400 encoded O/R Address and to generate an equivalent directory name. This mapping is only used for selected types of O/R Address: Kille Standards Track [Page 9] RFC 2294 Directory Information Tree March 1998 o Mnemonic form o Numeric form o Terminal form, where country is present and X121 addressing is used Other forms of O/R address are handled by Access Unit mechanisms. The O/R Address is treated as an ordered list, with the order as defined in Table 1. For each O/R Address attribute, generate the equivalent directory naming attribute. In most cases, the mapping is mechanical. Printable String or Teletex encodings are chosen as appropriate. Where both forms are present in the O/R Address, either form may be used to generate the distinguished name. Both will be represented in the DIT. There are two special cases: 1. A DDA generates a multi-valued RDN 2. The Personal Name is mapped to a multi-valued RDN In many cases, an O/R Address will be provided, and only the higher components of the address will be represented in the DIT. In this case, the "longest possible match" should be returned. 5 Mapping from Directory Name to O/R Address The reverse mapping is also needed in some cases. All of the naming attributes are unique, so the mapping is mechanically reversible. 6 Acknowledgments Acknowledgments for work on this document are given in [4]. References [1] The Directory --- overview of concepts, models and services, 1993. CCITT X.500 Series Recommendations. [2] Kille, S., "MIXER (Mime Internet X.400 Enhanced Relay): Mapping between X.400 and RFC 822/MIME", RFC 2156, January 1998. [3] Kille, S., "A String Representation of Distinguished Names", RFC 1779, March 1995. [4] Kille, S., "Use of an X.500/LDAP directory to support MIXER address mapping", RFC 2164, January 1998. Kille Standards Track [Page 10] RFC 2294 Directory Information Tree March 1998 [5] Kille, S., "X.400-MHS use of the X.500 directory to support X.400-MHS routing", RFC 1801, June 1995. [6] CCITT recommendations X.400 / ISO 10021, April 1988. CCITT SG 5/VII / ISO/IEC JTC1, Message Handling: System and Service Overview. 7 Security Considerations This protocol introduces no known security risks. 8 Author's Address Steve Kille Isode Ltd. The Dome The Square Richmond TW9 1DT England Phone: +44-181-332-9091 EMail: S.Kille@ISODE.COM X.400: I=S; S=Kille; P=ISODE; A=Mailnet; C=FI; Kille Standards Track [Page 11] RFC 2294 Directory Information Tree March 1998 A Object Identifier Assignment mhs-ds OBJECT IDENTIFIER ::= {iso(1) org(3) dod(6) internet(1) private(4) enterprises(1) isode-consortium (453) mhs-ds (7)} tree OBJECT IDENTIFIER ::= {mhs-ds 2} oc OBJECT IDENTIFIER ::= {tree 1} at OBJECT IDENTIFIER ::= {tree 2} oc-admd OBJECT IDENTIFIER ::= {oc 1} 10 oc-mhs-country OBJECT IDENTIFIER ::= {oc 2} oc-mhs-domain-defined-attribute OBJECT IDENTIFIER ::= {oc 3} oc-mhs-named-object OBJECT IDENTIFIER ::= {oc 4} oc-mhs-organization OBJECT IDENTIFIER ::= {oc 5} oc-mhs-organizational-unit OBJECT IDENTIFIER ::= {oc 6} oc-mhs-person OBJECT IDENTIFIER ::= {oc 7} oc-mhs-x121 OBJECT IDENTIFIER ::= {oc 8} oc-prmd OBJECT IDENTIFIER ::= {oc 9} oc-mhs-terminal-id OBJECT IDENTIFIER ::= {oc 10} oc-mhs-numeric-user-id OBJECT IDENTIFIER ::= {oc 11} 20 at-admd-name OBJECT IDENTIFIER ::= {at 1} at-mhs-common-name OBJECT IDENTIFIER ::= {at 2} at-mhs-domain-defined-attribute-type OBJECT IDENTIFIER ::= {at 3} at-mhs-domain-defined-attribute-value OBJECT IDENTIFIER ::= {at 4} at-mhs-numeric-country-name OBJECT IDENTIFIER ::= {at 5} at-mhs-organization-name OBJECT IDENTIFIER ::= {at 6} at-mhs-organizational-unit-name OBJECT IDENTIFIER ::= {at 7} at-prmd-name OBJECT IDENTIFIER ::= {at 10} at-x121-address OBJECT IDENTIFIER ::= {at 12} 30 at-mhs-terminal-id-name OBJECT IDENTIFIER ::= {at 13} at-mhs-numeric-user-id-name OBJECT IDENTIFIER ::= {at 14} at-mhs-surname OBJECT IDENTIFIER ::= {at 15} at-mhs-given-name OBJECT IDENTIFIER ::= {at 16} at-mhs-initials OBJECT IDENTIFIER ::= {at 17} at-mhs-generation-qualifier OBJECT IDENTIFIER ::= {at 18} Figure 3: Object Identifier Assignment Kille Standards Track [Page 12] RFC 2294 Directory Information Tree March 1998 Full Copyright Statement Copyright (C) The Internet Society (1998). 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. Kille Standards Track [Page 13] PK $�c\ֽ�� � ( doc/alt-openldap11-devel/rfc/rfc4523.txtnu �[��� Network Working Group K. Zeilenga Request for Comments: 4523 OpenLDAP Foundation Obsoletes: 2252, 2256, 2587 June 2006 Category: Standards Track Lightweight Directory Access Protocol (LDAP) Schema Definitions for X.509 Certificates Status of This Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2006). Abstract This document describes schema for representing X.509 certificates, X.521 security information, and related elements in directories accessible using the Lightweight Directory Access Protocol (LDAP). The LDAP definitions for these X.509 and X.521 schema elements replace those provided in RFCs 2252 and 2256. 1. Introduction This document provides LDAP [RFC4510] schema definitions [RFC4512] for a subset of elements specified in X.509 [X.509] and X.521 [X.521], including attribute types for certificates, cross certificate pairs, and certificate revocation lists; matching rules to be used with these attribute types; and related object classes. LDAP syntax definitions are also provided for associated assertion and attribute values. As the semantics of these elements are as defined in X.509 and X.521, knowledge of X.509 and X.521 is necessary to make use of the LDAP schema definitions provided herein. This document, together with [RFC4510], obsoletes RFCs 2252 and 2256 in their entirety. The changes (in this document) made since RFC 2252 and RFC 2256 include: - addition of pkiUser, pkiCA, and deltaCRL classes; Zeilenga Standards Track [Page 1] RFC 4523 LDAP X.509 Schema June 2006 - update of attribute types to include equality matching rules in accordance with their X.500 specifications; - addition of certificate, certificate pair, certificate list, and algorithm identifier matching rules; and - addition of LDAP syntax for assertion syntaxes for these matching rules. This document obsoletes RFC 2587. The X.509 schema descriptions for LDAPv2 [RFC1777] are Historic, as is LDAPv2 [RFC3494]. 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 [RFC4512]. Definitions provided here are formatted (line wrapped) for readability. 2. Syntaxes This section describes various syntaxes used in LDAP to transfer certificates and related data types. 2.1. Certificate ( 1.3.6.1.4.1.1466.115.121.1.8 DESC 'X.509 Certificate' ) A value of this syntax is an X.509 Certificate [X.509, clause 7]. Due to changes made to the definition of a Certificate through time, no LDAP-specific encoding is defined for this syntax. Values of this syntax SHOULD be encoded using Distinguished Encoding Rules (DER) [X.690] and MUST only be transferred using the ;binary transfer option [RFC4522]; that is, by requesting and returning values using attribute descriptions such as "userCertificate;binary". As values of this syntax contain digitally signed data, values of this syntax and the form of each value MUST be preserved as presented. 2.2. CertificateList ( 1.3.6.1.4.1.1466.115.121.1.9 DESC 'X.509 Certificate List' ) A value of this syntax is an X.509 CertificateList [X.509, clause 7.3]. Zeilenga Standards Track [Page 2] RFC 4523 LDAP X.509 Schema June 2006 Due to changes made to the definition of a CertificateList through time, no LDAP-specific encoding is defined for this syntax. Values of this syntax SHOULD be encoded using DER [X.690] and MUST only be transferred using the ;binary transfer option [RFC4522]; that is, by requesting and returning values using attribute descriptions such as "certificateRevocationList;binary". As values of this syntax contain digitally signed data, values of this syntax and the form of each value MUST be preserved as presented. 2.3. CertificatePair ( 1.3.6.1.4.1.1466.115.121.1.10 DESC 'X.509 Certificate Pair' ) A value of this syntax is an X.509 CertificatePair [X.509, clause 11.2.3]. Due to changes made to the definition of an X.509 CertificatePair through time, no LDAP-specific encoding is defined for this syntax. Values of this syntax SHOULD be encoded using DER [X.690] and MUST only be transferred using the ;binary transfer option [RFC4522]; that is, by requesting and returning values using attribute descriptions such as "crossCertificatePair;binary". As values of this syntax contain digitally signed data, values of this syntax and the form of each value MUST be preserved as presented. 2.4. SupportedAlgorithm ( 1.3.6.1.4.1.1466.115.121.1.49 DESC 'X.509 Supported Algorithm' ) A value of this syntax is an X.509 SupportedAlgorithm [X.509, clause 11.2.7]. Due to changes made to the definition of an X.509 SupportedAlgorithm through time, no LDAP-specific encoding is defined for this syntax. Values of this syntax SHOULD be encoded using DER [X.690] and MUST only be transferred using the ;binary transfer option [RFC4522]; that is, by requesting and returning values using attribute descriptions such as "supportedAlgorithms;binary". As values of this syntax contain digitally signed data, values of this syntax and the form of the value MUST be preserved as presented. Zeilenga Standards Track [Page 3] RFC 4523 LDAP X.509 Schema June 2006 2.5. CertificateExactAssertion ( 1.3.6.1.1.15.1 DESC 'X.509 Certificate Exact Assertion' ) A value of this syntax is an X.509 CertificateExactAssertion [X.509, clause 11.3.1]. Values of this syntax MUST be encoded using the Generic String Encoding Rules (GSER) [RFC3641]. Appendix A.1 provides an equivalent Augmented Backus-Naur Form (ABNF) [RFC4234] grammar for this syntax. 2.6. CertificateAssertion ( 1.3.6.1.1.15.2 DESC 'X.509 Certificate Assertion' ) A value of this syntax is an X.509 CertificateAssertion [X.509, clause 11.3.2]. Values of this syntax MUST be encoded using GSER [RFC3641]. Appendix A.2 provides an equivalent ABNF [RFC4234] grammar for this syntax. 2.7. CertificatePairExactAssertion ( 1.3.6.1.1.15.3 DESC 'X.509 Certificate Pair Exact Assertion' ) A value of this syntax is an X.509 CertificatePairExactAssertion [X.509, clause 11.3.3]. Values of this syntax MUST be encoded using GSER [RFC3641]. Appendix A.3 provides an equivalent ABNF [RFC4234] grammar for this syntax. 2.8. CertificatePairAssertion ( 1.3.6.1.1.15.4 DESC 'X.509 Certificate Pair Assertion' ) A value of this syntax is an X.509 CertificatePairAssertion [X.509, clause 11.3.4]. Values of this syntax MUST be encoded using GSER [RFC3641]. Appendix A.4 provides an equivalent ABNF [RFC4234] grammar for this syntax. 2.9. CertificateListExactAssertion ( 1.3.6.1.1.15.5 DESC 'X.509 Certificate List Exact Assertion' ) A value of this syntax is an X.509 CertificateListExactAssertion [X.509, clause 11.3.5]. Values of this syntax MUST be encoded using GSER [RFC3641]. Appendix A.5 provides an equivalent ABNF grammar for this syntax. Zeilenga Standards Track [Page 4] RFC 4523 LDAP X.509 Schema June 2006 2.10. CertificateListAssertion ( 1.3.6.1.1.15.6 DESC 'X.509 Certificate List Assertion' ) A value of this syntax is an X.509 CertificateListAssertion [X.509, clause 11.3.6]. Values of this syntax MUST be encoded using GSER [RFC3641]. Appendix A.6 provides an equivalent ABNF [RFC4234] grammar for this syntax. 2.11. AlgorithmIdentifier ( 1.3.6.1.1.15.7 DESC 'X.509 Algorithm Identifier' ) A value of this syntax is an X.509 AlgorithmIdentifier [X.509, Clause 7]. Values of this syntax MUST be encoded using GSER [RFC3641]. Appendix A.7 provides an equivalent ABNF [RFC4234] grammar for this syntax. 3. Matching Rules This section introduces a set of certificate and related matching rules for use in LDAP. These rules are intended to act in accordance with their X.500 counterparts. 3.1. certificateExactMatch The certificateExactMatch matching rule compares the presented certificate exact assertion value with an attribute value of the certificate syntax as described in clause 11.3.1 of [X.509]. ( 2.5.13.34 NAME 'certificateExactMatch' DESC 'X.509 Certificate Exact Match' SYNTAX 1.3.6.1.1.15.1 ) 3.2. certificateMatch The certificateMatch matching rule compares the presented certificate assertion value with an attribute value of the certificate syntax as described in clause 11.3.2 of [X.509]. ( 2.5.13.35 NAME 'certificateMatch' DESC 'X.509 Certificate Match' SYNTAX 1.3.6.1.1.15.2 ) Zeilenga Standards Track [Page 5] RFC 4523 LDAP X.509 Schema June 2006 3.3. certificatePairExactMatch The certificatePairExactMatch matching rule compares the presented certificate pair exact assertion value with an attribute value of the certificate pair syntax as described in clause 11.3.3 of [X.509]. ( 2.5.13.36 NAME 'certificatePairExactMatch' DESC 'X.509 Certificate Pair Exact Match' SYNTAX 1.3.6.1.1.15.3 ) 3.4. certificatePairMatch The certificatePairMatch matching rule compares the presented certificate pair assertion value with an attribute value of the certificate pair syntax as described in clause 11.3.4 of [X.509]. ( 2.5.13.37 NAME 'certificatePairMatch' DESC 'X.509 Certificate Pair Match' SYNTAX 1.3.6.1.1.15.4 ) 3.5. certificateListExactMatch The certificateListExactMatch matching rule compares the presented certificate list exact assertion value with an attribute value of the certificate pair syntax as described in clause 11.3.5 of [X.509]. ( 2.5.13.38 NAME 'certificateListExactMatch' DESC 'X.509 Certificate List Exact Match' SYNTAX 1.3.6.1.1.15.5 ) 3.6. certificateListMatch The certificateListMatch matching rule compares the presented certificate list assertion value with an attribute value of the certificate pair syntax as described in clause 11.3.6 of [X.509]. ( 2.5.13.39 NAME 'certificateListMatch' DESC 'X.509 Certificate List Match' SYNTAX 1.3.6.1.1.15.6 ) Zeilenga Standards Track [Page 6] RFC 4523 LDAP X.509 Schema June 2006 3.7. algorithmIdentifierMatch The algorithmIdentifierMatch mating rule compares a presented algorithm identifier with an attribute value of the supported algorithm as described in clause 11.3.7 of [X.509]. ( 2.5.13.40 NAME 'algorithmIdentifier' DESC 'X.509 Algorithm Identifier Match' SYNTAX 1.3.6.1.1.15.7 ) 4. Attribute Types This section details a set of certificate and related attribute types for use in LDAP. 4.1. userCertificate The userCertificate attribute holds the X.509 certificates issued to the user by one or more certificate authorities, as discussed in clause 11.2.1 of [X.509]. ( 2.5.4.36 NAME 'userCertificate' DESC 'X.509 user certificate' EQUALITY certificateExactMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.8 ) As required by this attribute type's syntax, values of this attribute are requested and transferred using the attribute description "userCertificate;binary". 4.2. cACertificate The cACertificate attribute holds the X.509 certificates issued to the certificate authority (CA), as discussed in clause 11.2.2 of [X.509]. ( 2.5.4.37 NAME 'cACertificate' DESC 'X.509 CA certificate' EQUALITY certificateExactMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.8 ) As required by this attribute type's syntax, values of this attribute are requested and transferred using the attribute description "cACertificate;binary". Zeilenga Standards Track [Page 7] RFC 4523 LDAP X.509 Schema June 2006 4.3. crossCertificatePair The crossCertificatePair attribute holds an X.509 certificate pair, as discussed in clause 11.2.3 of [X.509]. ( 2.5.4.40 NAME 'crossCertificatePair' DESC 'X.509 cross certificate pair' EQUALITY certificatePairExactMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.10 ) As required by this attribute type's syntax, values of this attribute are requested and transferred using the attribute description "crossCertificatePair;binary". 4.4. certificateRevocationList The certificateRevocationList attribute holds certificate lists, as discussed in 11.2.4 of [X.509]. ( 2.5.4.39 NAME 'certificateRevocationList' DESC 'X.509 certificate revocation list' EQUALITY certificateListExactMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.9 ) As required by this attribute type's syntax, values of this attribute are requested and transferred using the attribute description "certificateRevocationList;binary". 4.5. authorityRevocationList The authorityRevocationList attribute holds certificate lists, as discussed in 11.2.5 of [X.509]. ( 2.5.4.38 NAME 'authorityRevocationList' DESC 'X.509 authority revocation list' EQUALITY certificateListExactMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.9 ) As required by this attribute type's syntax, values of this attribute are requested and transferred using the attribute description "authorityRevocationList;binary". Zeilenga Standards Track [Page 8] RFC 4523 LDAP X.509 Schema June 2006 4.6. deltaRevocationList The deltaRevocationList attribute holds certificate lists, as discussed in 11.2.6 of [X.509]. ( 2.5.4.53 NAME 'deltaRevocationList' DESC 'X.509 delta revocation list' EQUALITY certificateListExactMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.9 ) As required by this attribute type's syntax, values of this attribute MUST be requested and transferred using the attribute description "deltaRevocationList;binary". 4.7. supportedAlgorithms The supportedAlgorithms attribute holds supported algorithms, as discussed in 11.2.7 of [X.509]. ( 2.5.4.52 NAME 'supportedAlgorithms' DESC 'X.509 supported algorithms' EQUALITY algorithmIdentifierMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.49 ) As required by this attribute type's syntax, values of this attribute MUST be requested and transferred using the attribute description "supportedAlgorithms;binary". 5. Object Classes This section details a set of certificate-related object classes for use in LDAP. 5.1. pkiUser This object class is used in augment entries for objects that may be subject to certificates, as defined in clause 11.1.1 of [X.509]. ( 2.5.6.21 NAME 'pkiUser' DESC 'X.509 PKI User' SUP top AUXILIARY MAY userCertificate ) Zeilenga Standards Track [Page 9] RFC 4523 LDAP X.509 Schema June 2006 5.2. pkiCA This object class is used to augment entries for objects that act as certificate authorities, as defined in clause 11.1.2 of [X.509] ( 2.5.6.22 NAME 'pkiCA' DESC 'X.509 PKI Certificate Authority' SUP top AUXILIARY MAY ( cACertificate $ certificateRevocationList $ authorityRevocationList $ crossCertificatePair ) ) 5.3. cRLDistributionPoint This class is used to represent objects that act as CRL distribution points, as discussed in clause 11.1.3 of [X.509]. ( 2.5.6.19 NAME 'cRLDistributionPoint' DESC 'X.509 CRL distribution point' SUP top STRUCTURAL MUST cn MAY ( certificateRevocationList $ authorityRevocationList $ deltaRevocationList ) ) 5.4. deltaCRL The deltaCRL object class is used to augment entries to hold delta revocation lists, as discussed in clause 11.1.4 of [X.509]. ( 2.5.6.23 NAME 'deltaCRL' DESC 'X.509 delta CRL' SUP top AUXILIARY MAY deltaRevocationList ) 5.5. strongAuthenticationUser This object class is used to augment entries for objects participating in certificate-based authentication, as defined in clause 6.15 of [X.521]. This object class is deprecated in favor of pkiUser. ( 2.5.6.15 NAME 'strongAuthenticationUser' DESC 'X.521 strong authentication user' SUP top AUXILIARY MUST userCertificate ) Zeilenga Standards Track [Page 10] RFC 4523 LDAP X.509 Schema June 2006 5.6. userSecurityInformation This object class is used to augment entries with needed additional associated security information, as defined in clause 6.16 of [X.521]. ( 2.5.6.18 NAME 'userSecurityInformation' DESC 'X.521 user security information' SUP top AUXILIARY MAY ( supportedAlgorithms ) ) 5.7. certificationAuthority This object class is used to augment entries for objects that act as certificate authorities, as defined in clause 6.17 of [X.521]. This object class is deprecated in favor of pkiCA. ( 2.5.6.16 NAME 'certificationAuthority' DESC 'X.509 certificate authority' SUP top AUXILIARY MUST ( authorityRevocationList $ certificateRevocationList $ cACertificate ) MAY crossCertificatePair ) 5.8. certificationAuthority-V2 This object class is used to augment entries for objects that act as certificate authorities, as defined in clause 6.18 of [X.521]. This object class is deprecated in favor of pkiCA. ( 2.5.6.16.2 NAME 'certificationAuthority-V2' DESC 'X.509 certificate authority, version 2' SUP certificationAuthority AUXILIARY MAY deltaRevocationList ) 6. Security Considerations General certificate considerations [RFC3280] apply to LDAP-aware certificate applications. General LDAP security considerations [RFC4510] apply as well. While elements of certificate information are commonly signed, these signatures only protect the integrity of the signed information. In the absence of data integrity protections in LDAP (or lower layer, e.g., IPsec), a server is not assured that client certificate request (or other request) was unaltered in transit. Likewise, a client cannot be assured that the results of the query were unaltered in Zeilenga Standards Track [Page 11] RFC 4523 LDAP X.509 Schema June 2006 transit. Hence, it is generally recommended that implementations make use of authentication and data integrity services in LDAP [RFC4513][RFC4511]. 7. IANA Considerations 7.1. Object Identifier Registration The IANA has registered an LDAP Object Identifier [RFC4520] for use in this technical specification. Subject: Request for LDAP OID Registration Person & email address to contact for further information: Kurt Zeilenga <kurt@OpenLDAP.org> Specification: RFC 4523 Author/Change Controller: IESG Comments: Identifies the LDAP X.509 Certificate schema elements introduced in this document. 7.2. Descriptor Registration The IANA has updated the LDAP Descriptor registry [RFC44520] as indicated below. Subject: Request for LDAP Descriptor Registration Descriptor (short name): see table Object Identifier: see table Person & email address to contact for further information: Kurt Zeilenga <kurt@OpenLDAP.org> Usage: see table Specification: RFC 4523 Author/Change Controller: IESG algorithmIdentifierMatch M 2.5.13.40 authorityRevocationList A 2.5.4.38 * cACertificate A 2.5.4.37 * cRLDistributionPoint O 2.5.6.19 * certificateExactMatch M 2.5.13.34 certificateListExactMatch M 2.5.13.38 certificateListMatch M 2.5.13.39 certificateMatch M 2.5.13.35 certificatePairExactMatch M 2.5.13.36 certificatePairMatch M 2.5.13.37 certificateRevocationList A 2.5.4.39 * certificationAuthority O 2.5.6.16 * certificationAuthority-V2 O 2.5.6.16.2 * crossCertificatePair A 2.5.4.40 * Zeilenga Standards Track [Page 12] RFC 4523 LDAP X.509 Schema June 2006 deltaCRL O 2.5.6.23 * deltaRevocationList A 2.5.4.53 * pkiCA O 2.5.6.22 * pkiUser O 2.5.6.21 * strongAuthenticationUser O 2.5.6.15 * supportedAlgorithms A 2.5.4.52 * userCertificate A 2.5.4.36 * userSecurityInformation O 2.5.6.18 * * Updates previous registration 8. Acknowledgements This document is based on X.509, a product of the ITU-T. A number of LDAP schema definitions were based on those found in RFCs 2252 and 2256, both products of the IETF ASID WG. The ABNF productions in Appendix A were provided by Steven Legg. Additional material was borrowed from prior works by David Chadwick and Steven Legg to refine the LDAP X.509 schema. 9. References 9.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC3641] Legg, S., "Generic String Encoding Rules (GSER) for ASN.1 Types", RFC 3641, October 2003. [RFC4510] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006. [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006. [RFC4522] Legg, S., "Lightweight Directory Access Protocol (LDAP): The Binary Encoding Option", RFC 4522, June 2006. [X.509] International Telecommunication Union - Telecommunication Standardization Sector, "The Directory: Authentication Framework", X.509(2000). Zeilenga Standards Track [Page 13] RFC 4523 LDAP X.509 Schema June 2006 [X.521] International Telecommunication Union - Telecommunication Standardization Sector, "The Directory: Selected Object Classes", X.521(2000). [X.690] International Telecommunication Union - Telecommunication Standardization Sector, "Specification of ASN.1 encoding rules: Basic Encoding Rules (BER), Canonical Encoding Rules (CER), and Distinguished Encoding Rules (DER)", X.690(2002) (also ISO/IEC 8825-1:2002). 9.2. Informative References [RFC1777] Yeong, W., Howes, T., and S. Kille, "Lightweight Directory Access Protocol", RFC 1777, March 1995. [RFC2156] Kille, S., "MIXER (Mime Internet X.400 Enhanced Relay): Mapping between X.400 and RFC 822/MIME", RFC 2156, January 1998. [RFC3280] Housley, R., Polk, W., Ford, W., and D. Solo, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 3280, April 2002. [RFC3494] Zeilenga, K., "Lightweight Directory Access Protocol version 2 (LDAPv2) to Historic Status", RFC 3494, March 2003. [RFC3642] Legg, S., "Common Elements of Generic String Encoding Rules (GSER) Encodings", RFC 3642, October 2003. [RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 4234, October 2005. [RFC4511] Sermersheim, J., Ed., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006. [RFC4513] Harrison, R. Ed., "Lightweight Directory Access Protocol (LDAP): Authentication Methods and Security Mechanisms", RFC 4513, June 2006. [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006. Zeilenga Standards Track [Page 14] RFC 4523 LDAP X.509 Schema June 2006 Appendix A. This appendix is informative. This appendix provides ABNF [RFC4234] grammars for GSER-based [RFC3641] LDAP-specific encodings specified in this document. These grammars where produced using, and relying on, Common Elements for GSER Encodings [RFC3642]. A.1. CertificateExactAssertion CertificateExactAssertion = "{" sp cea-serialNumber "," sp cea-issuer sp "}" cea-serialNumber = id-serialNumber msp CertificateSerialNumber cea-issuer = id-issuer msp Name id-serialNumber = %x73.65.72.69.61.6C.4E.75.6D.62.65.72 ; 'serialNumber' id-issuer = %x69.73.73.75.65.72 ; 'issuer' Name = id-rdnSequence ":" RDNSequence id-rdnSequence = %x72.64.6E.53.65.71.75.65.6E.63.65 ; 'rdnSequence' CertificateSerialNumber = INTEGER A.2. CertificateAssertion CertificateAssertion = "{" [ sp ca-serialNumber ] [ sep sp ca-issuer ] [ sep sp ca-subjectKeyIdentifier ] [ sep sp ca-authorityKeyIdentifier ] [ sep sp ca-certificateValid ] [ sep sp ca-privateKeyValid ] [ sep sp ca-subjectPublicKeyAlgID ] [ sep sp ca-keyUsage ] [ sep sp ca-subjectAltName ] [ sep sp ca-policy ] [ sep sp ca-pathToName ] [ sep sp ca-subject ] [ sep sp ca-nameConstraints ] sp "}" ca-serialNumber = id-serialNumber msp CertificateSerialNumber ca-issuer = id-issuer msp Name ca-subjectKeyIdentifier = id-subjectKeyIdentifier msp SubjectKeyIdentifier ca-authorityKeyIdentifier = id-authorityKeyIdentifier msp AuthorityKeyIdentifier Zeilenga Standards Track [Page 15] RFC 4523 LDAP X.509 Schema June 2006 ca-certificateValid = id-certificateValid msp Time ca-privateKeyValid = id-privateKeyValid msp GeneralizedTime ca-subjectPublicKeyAlgID = id-subjectPublicKeyAlgID msp OBJECT-IDENTIFIER ca-keyUsage = id-keyUsage msp KeyUsage ca-subjectAltName = id-subjectAltName msp AltNameType ca-policy = id-policy msp CertPolicySet ca-pathToName = id-pathToName msp Name ca-subject = id-subject msp Name ca-nameConstraints = id-nameConstraints msp NameConstraintsSyntax id-subjectKeyIdentifier = %x73.75.62.6A.65.63.74.4B.65.79.49.64.65.6E.74.69.66.69.65.72 ; 'subjectKeyIdentifier' id-authorityKeyIdentifier = %x61.75.74.68.6F.72.69.74.79.4B.65.79.49.64.65.6E.74.69.66.69.65.72 ; 'authorityKeyIdentifier' id-certificateValid = %x63.65.72.74.69.66.69.63.61.74.65.56.61.6C.69.64 ; 'certificateValid' id-privateKeyValid = %x70.72.69.76.61.74.65.4B.65.79.56.61.6C.69.64 ; 'privateKeyValid' id-subjectPublicKeyAlgID = %x73.75.62.6A.65.63.74.50.75.62.6C.69.63.4B.65.79.41.6C.67.49.44 ; 'subjectPublicKeyAlgID' id-keyUsage = %x6B.65.79.55.73.61.67.65 ; 'keyUsage' id-subjectAltName = %x73.75.62.6A.65.63.74.41.6C.74.4E.61.6D.65 ; 'subjectAltName' id-policy = %x70.6F.6C.69.63.79 ; 'policy' id-pathToName = %x70.61.74.68.54.6F.4E.61.6D.65 ; 'pathToName' id-subject = %x73.75.62.6A.65.63.74 ; 'subject' id-nameConstraints = %x6E.61.6D.65.43.6F.6E.73.74.72.61.69.6E.74.73 ; 'nameConstraints' SubjectKeyIdentifier = KeyIdentifier KeyIdentifier = OCTET-STRING AuthorityKeyIdentifier = "{" [ sp aki-keyIdentifier ] [ sep sp aki-authorityCertIssuer ] [ sep sp aki-authorityCertSerialNumber ] sp "}" aki-keyIdentifier = id-keyIdentifier msp KeyIdentifier aki-authorityCertIssuer = id-authorityCertIssuer msp GeneralNames GeneralNames = "{" sp GeneralName *( "," sp GeneralName ) sp "}" GeneralName = gn-otherName / gn-rfc822Name / gn-dNSName Zeilenga Standards Track [Page 16] RFC 4523 LDAP X.509 Schema June 2006 / gn-x400Address / gn-directoryName / gn-ediPartyName / gn-uniformResourceIdentifier / gn-iPAddress / gn-registeredID gn-otherName = id-otherName ":" OtherName gn-rfc822Name = id-rfc822Name ":" IA5String gn-dNSName = id-dNSName ":" IA5String gn-x400Address = id-x400Address ":" ORAddress gn-directoryName = id-directoryName ":" Name gn-ediPartyName = id-ediPartyName ":" EDIPartyName gn-iPAddress = id-iPAddress ":" OCTET-STRING gn-registeredID = gn-id-registeredID ":" OBJECT-IDENTIFIER gn-uniformResourceIdentifier = id-uniformResourceIdentifier ":" IA5String id-otherName = %x6F.74.68.65.72.4E.61.6D.65 ; 'otherName' gn-id-registeredID = %x72.65.67.69.73.74.65.72.65.64.49.44 ; 'registeredID' OtherName = "{" sp on-type-id "," sp on-value sp "}" on-type-id = id-type-id msp OBJECT-IDENTIFIER on-value = id-value msp Value ;; <Value> as defined in Section 3 of [RFC3641] id-type-id = %x74.79.70.65.2D.69.64 ; 'type-id' id-value = %x76.61.6C.75.65 ; 'value' ORAddress = dquote *SafeIA5Character dquote SafeIA5Character = %x01-21 / %x23-7F / ; ASCII minus dquote dquote dquote ; escaped double quote dquote = %x22 ; '"' (double quote) ;; Note: The <ORAddress> rule encodes the x400Address component ;; of a GeneralName as a character string between double quotes. ;; The character string is first derived according to Section 4.1 ;; of [RFC2156], and then any embedded double quotes are escaped ;; by being repeated. This resulting string is output between ;; double quotes. EDIPartyName = "{" [ sp nameAssigner "," ] sp partyName sp "}" nameAssigner = id-nameAssigner msp DirectoryString partyName = id-partyName msp DirectoryString id-nameAssigner = %x6E.61.6D.65.41.73.73.69.67.6E.65.72 ; 'nameAssigner' Zeilenga Standards Track [Page 17] RFC 4523 LDAP X.509 Schema June 2006 id-partyName = %x70.61.72.74.79.4E.61.6D.65 ; 'partyName' aki-authorityCertSerialNumber = id-authorityCertSerialNumber msp CertificateSerialNumber id-keyIdentifier = %x6B.65.79.49.64.65.6E.74.69.66.69.65.72 ; 'keyIdentifier' id-authorityCertIssuer = %x61.75.74.68.6F.72.69.74.79.43.65.72.74.49.73.73.75.65.72 ; 'authorityCertIssuer' id-authorityCertSerialNumber = %x61.75.74.68.6F.72.69.74.79.43 %x65.72.74.53.65.72.69.61.6C.4E.75.6D.62.65.72 ; 'authorityCertSerialNumber' Time = time-utcTime / time-generalizedTime time-utcTime = id-utcTime ":" UTCTime time-generalizedTime = id-generalizedTime ":" GeneralizedTime id-utcTime = %x75.74.63.54.69.6D.65 ; 'utcTime' id-generalizedTime = %x67.65.6E.65.72.61.6C.69.7A.65.64.54.69.6D.65 ; 'generalizedTime' KeyUsage = BIT-STRING / key-usage-bit-list key-usage-bit-list = "{" [ sp key-usage *( "," sp key-usage ) ] sp "}" ;; Note: The <key-usage-bit-list> rule encodes the one bits in ;; a KeyUsage value as a comma separated list of identifiers. key-usage = id-digitalSignature / id-nonRepudiation / id-keyEncipherment / id-dataEncipherment / id-keyAgreement / id-keyCertSign / id-cRLSign / id-encipherOnly / id-decipherOnly id-digitalSignature = %x64.69.67.69.74.61.6C.53.69.67.6E.61.74 %x75.72.65 ; 'digitalSignature' id-nonRepudiation = %x6E.6F.6E.52.65.70.75.64.69.61.74.69.6F.6E ; 'nonRepudiation' id-keyEncipherment = %x6B.65.79.45.6E.63.69.70.68.65.72.6D.65.6E.74 ; 'keyEncipherment' id-dataEncipherment = %x64.61.74.61.45.6E.63.69.70.68.65.72.6D.65.6E %x74 ; "dataEncipherment' id-keyAgreement = %x6B.65.79.41.67.72.65.65.6D.65.6E.74 ; 'keyAgreement' Zeilenga Standards Track [Page 18] RFC 4523 LDAP X.509 Schema June 2006 id-keyCertSign = %x6B.65.79.43.65.72.74.53.69.67.6E ; 'keyCertSign' id-cRLSign = %x63.52.4C.53.69.67.6E ; "cRLSign" id-encipherOnly = %x65.6E.63.69.70.68.65.72.4F.6E.6C.79 ; 'encipherOnly' id-decipherOnly = %x64.65.63.69.70.68.65.72.4F.6E.6C.79 ; 'decipherOnly' AltNameType = ant-builtinNameForm / ant-otherNameForm ant-builtinNameForm = id-builtinNameForm ":" BuiltinNameForm ant-otherNameForm = id-otherNameForm ":" OBJECT-IDENTIFIER id-builtinNameForm = %x62.75.69.6C.74.69.6E.4E.61.6D.65.46.6F.72.6D ; 'builtinNameForm' id-otherNameForm = %x6F.74.68.65.72.4E.61.6D.65.46.6F.72.6D ; 'otherNameForm' BuiltinNameForm = id-rfc822Name / id-dNSName / id-x400Address / id-directoryName / id-ediPartyName / id-uniformResourceIdentifier / id-iPAddress / id-registeredId id-rfc822Name = %x72.66.63.38.32.32.4E.61.6D.65 ; 'rfc822Name' id-dNSName = %x64.4E.53.4E.61.6D.65 ; 'dNSName' id-x400Address = %x78.34.30.30.41.64.64.72.65.73.73 ; 'x400Address' id-directoryName = %x64.69.72.65.63.74.6F.72.79.4E.61.6D.65 ; 'directoryName' id-ediPartyName = %x65.64.69.50.61.72.74.79.4E.61.6D.65 ; 'ediPartyName' id-iPAddress = %x69.50.41.64.64.72.65.73.73 ; 'iPAddress' id-registeredId = %x72.65.67.69.73.74.65.72.65.64.49.64 ; 'registeredId' id-uniformResourceIdentifier = %x75.6E.69.66.6F.72.6D.52.65.73.6F.75 %x72.63.65.49.64.65.6E.74.69.66.69.65.72 ; 'uniformResourceIdentifier' CertPolicySet = "{" sp CertPolicyId *( "," sp CertPolicyId ) sp "}" CertPolicyId = OBJECT-IDENTIFIER NameConstraintsSyntax = "{" [ sp ncs-permittedSubtrees ] [ sep sp ncs-excludedSubtrees ] sp "}" Zeilenga Standards Track [Page 19] RFC 4523 LDAP X.509 Schema June 2006 ncs-permittedSubtrees = id-permittedSubtrees msp GeneralSubtrees ncs-excludedSubtrees = id-excludedSubtrees msp GeneralSubtrees id-permittedSubtrees = %x70.65.72.6D.69.74.74.65.64.53.75.62.74.72.65.65.73 ; 'permittedSubtrees' id-excludedSubtrees = %x65.78.63.6C.75.64.65.64.53.75.62.74.72.65.65.73 ; 'excludedSubtrees' GeneralSubtrees = "{" sp GeneralSubtree *( "," sp GeneralSubtree ) sp "}" GeneralSubtree = "{" sp gs-base [ "," sp gs-minimum ] [ "," sp gs-maximum ] sp "}" gs-base = id-base msp GeneralName gs-minimum = id-minimum msp BaseDistance gs-maximum = id-maximum msp BaseDistance id-base = %x62.61.73.65 ; 'base' id-minimum = %x6D.69.6E.69.6D.75.6D ; 'minimum' id-maximum = %x6D.61.78.69.6D.75.6D ; 'maximum' BaseDistance = INTEGER-0-MAX A.3. CertificatePairExactAssertion CertificatePairExactAssertion = "{" [ sp cpea-issuedTo ] [sep sp cpea-issuedBy ] sp "}" ;; At least one of <cpea-issuedTo> or <cpea-issuedBy> MUST be present. cpea-issuedTo = id-issuedToThisCAAssertion msp CertificateExactAssertion cpea-issuedBy = id-issuedByThisCAAssertion msp CertificateExactAssertion id-issuedToThisCAAssertion = %x69.73.73.75.65.64.54.6F.54.68.69.73 %x43.41.41.73.73.65.72.74.69.6F.6E ; 'issuedToThisCAAssertion' id-issuedByThisCAAssertion = %x69.73.73.75.65.64.42.79.54.68.69.73 %x43.41.41.73.73.65.72.74.69.6F.6E ; 'issuedByThisCAAssertion' Zeilenga Standards Track [Page 20] RFC 4523 LDAP X.509 Schema June 2006 A.4. CertificatePairAssertion CertificatePairAssertion = "{" [ sp cpa-issuedTo ] [sep sp cpa-issuedBy ] sp "}" ;; At least one of <cpa-issuedTo> and <cpa-issuedBy> MUST be present. cpa-issuedTo = id-issuedToThisCAAssertion msp CertificateAssertion cpa-issuedBy = id-issuedByThisCAAssertion msp CertificateAssertion A.5. CertificateListExactAssertion CertificateListExactAssertion = "{" sp clea-issuer "," sp clea-thisUpdate [ "," sp clea-distributionPoint ] sp "}" clea-issuer = id-issuer msp Name clea-thisUpdate = id-thisUpdate msp Time clea-distributionPoint = id-distributionPoint msp DistributionPointName id-thisUpdate = %x74.68.69.73.55.70.64.61.74.65 ; 'thisUpdate' id-distributionPoint = %x64.69.73.74.72.69.62.75.74.69.6F.6E.50.6F.69.6E.74 ; 'distributionPoint' DistributionPointName = dpn-fullName / dpn-nameRelativeToCRLIssuer dpn-fullName = id-fullName ":" GeneralNames dpn-nameRelativeToCRLIssuer = id-nameRelativeToCRLIssuer ":" RelativeDistinguishedName id-fullName = %x66.75.6C.6C.4E.61.6D.65 ; 'fullName' id-nameRelativeToCRLIssuer = %x6E.61.6D.65.52.65.6C.61.74.69.76.65 %x54.6F.43.52.4C.49.73.73.75.65.72 ; 'nameRelativeToCRLIssuer' A.6. CertificateListAssertion CertificateListAssertion = "{" [ sp cla-issuer ] [ sep sp cla-minCRLNumber ] [ sep sp cla-maxCRLNumber ] [ sep sp cla-reasonFlags ] [ sep sp cla-dateAndTime ] [ sep sp cla-distributionPoint ] [ sep sp cla-authorityKeyIdentifier ] sp "}" cla-issuer = id-issuer msp Name cla-minCRLNumber = id-minCRLNumber msp CRLNumber cla-maxCRLNumber = id-maxCRLNumber msp CRLNumber Zeilenga Standards Track [Page 21] RFC 4523 LDAP X.509 Schema June 2006 cla-reasonFlags = id-reasonFlags msp ReasonFlags cla-dateAndTime = id-dateAndTime msp Time cla-distributionPoint = id-distributionPoint msp DistributionPointName cla-authorityKeyIdentifier = id-authorityKeyIdentifier msp AuthorityKeyIdentifier id-minCRLNumber = %x6D.69.6E.43.52.4C.4E.75.6D.62.65.72 ; 'minCRLNumber' id-maxCRLNumber = %x6D.61.78.43.52.4C.4E.75.6D.62.65.72 ; 'maxCRLNumber' id-reasonFlags = %x72.65.61.73.6F.6E.46.6C.61.67.73 ; 'reasonFlags' id-dateAndTime = %x64.61.74.65.41.6E.64.54.69.6D.65 ; 'dateAndTime' CRLNumber = INTEGER-0-MAX ReasonFlags = BIT-STRING / "{" [ sp reason-flag *( "," sp reason-flag ) ] sp "}" reason-flag = id-unused / id-keyCompromise / id-cACompromise / id-affiliationChanged / id-superseded / id-cessationOfOperation / id-certificateHold / id-privilegeWithdrawn / id-aACompromise id-unused = %x75.6E.75.73.65.64 ; 'unused' id-keyCompromise = %x6B.65.79.43.6F.6D.70.72.6F.6D.69.73.65 ; 'keyCompromise' id-cACompromise = %x63.41.43.6F.6D.70.72.6F.6D.69.73.65 ; 'cACompromise' id-affiliationChanged = %x61.66.66.69.6C.69.61.74.69.6F.6E.43.68.61.6E.67.65.64 ; 'affiliationChanged' id-superseded = %x73.75.70.65.72.73.65.64.65.64 ; 'superseded' id-cessationOfOperation = %x63.65.73.73.61.74.69.6F.6E.4F.66.4F.70.65.72.61.74.69.6F.6E ; 'cessationOfOperation' id-certificateHold = %x63.65.72.74.69.66.69.63.61.74.65.48.6F.6C.64 ; 'certificateHold' id-privilegeWithdrawn = %x70.72.69.76.69.6C.65.67.65.57.69.74.68.64.72.61.77.6E ; 'privilegeWithdrawn' Zeilenga Standards Track [Page 22] RFC 4523 LDAP X.509 Schema June 2006 id-aACompromise = %x61.41.43.6F.6D.70.72.6F.6D.69.73.65 ; 'aACompromise' A.7. AlgorithmIdentifier AlgorithmIdentifier = "{" sp ai-algorithm [ "," sp ai-parameters ] sp "}" ai-algorithm = id-algorithm msp OBJECT-IDENTIFIER ai-parameters = id-parameters msp Value id-algorithm = %x61.6C.67.6F.72.69.74.68.6D ; 'algorithm' id-parameters = %x70.61.72.61.6D.65.74.65.72.73 ; 'parameters' Author's Address Kurt D. Zeilenga OpenLDAP Foundation EMail: Kurt@OpenLDAP.org Zeilenga Standards Track [Page 23] RFC 4523 LDAP X.509 Schema June 2006 Full Copyright Statement Copyright (C) The Internet Society (2006). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Zeilenga Standards Track [Page 24] PK $�c\I!�y{0 {0 ( doc/alt-openldap11-devel/rfc/rfc2247.txtnu �[��� Network Working Group S. Kille Request for Comments: 2247 Isode Ltd. Category: Standards Track M. Wahl Critical Angle Inc. A. Grimstad AT&T R. Huber AT&T S. Sataluri AT&T January 1998 Using Domains in LDAP/X.500 Distinguished Names Status of this Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (1998). All Rights Reserved. 1. Abstract The Lightweight Directory Access Protocol (LDAP) uses X.500- compatible distinguished names [3] for providing unique identification of entries. This document defines an algorithm by which a name registered with the Internet Domain Name Service [2] can be represented as an LDAP distinguished name. 2. Background The Domain (Nameserver) System (DNS) provides a hierarchical resource labeling system. A name is made up of an ordered set of components, each of which are short strings. An example domain name with two components would be "CRITICAL-ANGLE.COM". Kille, et. al. Standards Track [Page 1] RFC 2247 Using Domains in LDAP/X.500 January 1998 LDAP-based directories provide a more general hierarchical naming framework. A primary difference in specification of distinguished names from domain names is that each component of an distinguished name has an explicit attribute type indication. X.500 does not mandate any particular naming structure. It does contain suggested naming structures which are based on geographic and national regions, however there is not currently an established registration infrastructure in many regions which would be able to assign or ensure uniqueness of names. The mechanism described in this document automatically provides an enterprise a distinguished name for each domain name it has obtained for use in the Internet. These distinguished names may be used to identify objects in an LDAP directory. An example distinguished name represented in the LDAP string format [3] is "DC=CRITICAL-ANGLE,DC=COM". As with a domain name, the most significant component, closest to the root of the namespace, is written last. This document does not define how to represent objects which do not have domain names. Nor does this document define the procedure to locate an enterprise's LDAP directory server, given their domain name. Such procedures may be defined in future RFCs. 3. Mapping Domain Names into Distinguished Names This section defines a subset of the possible distinguished name structures for use in representing names allocated in the Internet Domain Name System. It is possible to algorithmically transform any Internet domain name into a distinguished name, and to convert these distinguished names back into the original domain names. The algorithm for transforming a domain name is to begin with an empty distinguished name (DN) and then attach Relative Distinguished Names (RDNs) for each component of the domain, most significant (e.g. rightmost) first. Each of these RDNs is a single AttributeTypeAndValue, where the type is the attribute "DC" and the value is an IA5 string containing the domain name component. Thus the domain name "CS.UCL.AC.UK" can be transformed into DC=CS,DC=UCL,DC=AC,DC=UK Kille, et. al. Standards Track [Page 2] RFC 2247 Using Domains in LDAP/X.500 January 1998 Distinguished names in which there are one or more RDNs, all containing only the attribute type DC, can be mapped back into domain names. Note that this document does not define a domain name equivalence for any other distinguished names. 4. Attribute Type Definition The DC (short for domainComponent) attribute type is defined as follows: ( 0.9.2342.19200300.100.1.25 NAME 'dc' EQUALITY caseIgnoreIA5Match SUBSTR caseIgnoreIA5SubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 SINGLE-VALUE ) The value of this attribute is a string holding one component of a domain name. The encoding of IA5String for use in LDAP is simply the characters of the string itself. The equality matching rule is case insensitive, as is today's DNS. 5. Object Class Definitions An object with a name derived from its domain name using the algorithm of section 3 is represented as an entry in the directory. The "DC" attribute is present in the entry and used as the RDN. An attribute can only be present in an entry held by an LDAP server when that attribute is permitted by the entry's object class. This section defines two object classes. The first, dcObject, is intended to be used in entries for which there is an appropriate structural object class. For example, if the domain represents a particular organization, the entry would have as its structural object class 'organization', and the 'dcObject' class would be an auxiliary class. The second, domain, is a structural object class used for entries in which no other information is being stored. The domain object class is typically used for entries that are placeholders or whose domains do not correspond to real-world entities. 5.1. The dcObject object class The dcObject object class permits the dc attribute to be present in an entry. This object class is defined as auxiliary, as it would typically be used in conjunction with an existing structural object class, such as organization, organizationalUnit or locality. The following object class, along with the dc attribute, can be added to any entry. Kille, et. al. Standards Track [Page 3] RFC 2247 Using Domains in LDAP/X.500 January 1998 ( 1.3.6.1.4.1.1466.344 NAME 'dcObject' SUP top AUXILIARY MUST dc ) An example entry would be: dn: dc=critical-angle,dc=com objectClass: top objectClass: organization objectClass: dcObject dc: critical-angle o: Critical Angle Inc. 5.2. The domain object class If the entry does not correspond to an organization, organizational unit or other type of object for which an object class has been defined, then the "domain" object class can be used. The "domain" object class requires that the "DC" attribute be present, and permits several other attributes to be present in the entry. The entry will have as its structural object class the "domain" object class. ( 0.9.2342.19200300.100.4.13 NAME 'domain' SUP top STRUCTURAL MUST dc MAY ( userPassword $ searchGuide $ seeAlso $ businessCategory $ x121Address $ registeredAddress $ destinationIndicator $ preferredDeliveryMethod $ telexNumber $ teletexTerminalIdentifier $ telephoneNumber $ internationaliSDNNumber $ facsimileTelephoneNumber $ street $ postOfficeBox $ postalCode $ postalAddress $ physicalDeliveryOfficeName $ st $ l $ description $ o $ associatedName ) ) The optional attributes of the domain class are used for describing the object represented by this domain, and may also be useful when searching. These attributes are already defined for use with LDAP [4]. An example entry would be: dn: dc=tcp,dc=critical-angle,dc=com objectClass: top objectClass: domain dc: tcp description: a placeholder entry used with SRV records The DC attribute is used for naming entries of the domain class, and this can be represented in X.500 servers by the following name form rule. Kille, et. al. Standards Track [Page 4] RFC 2247 Using Domains in LDAP/X.500 January 1998 ( 1.3.6.1.4.1.1466.345 NAME 'domainNameForm' OC domain MUST ( dc ) ) 6. References [1] The Directory: Selected Attribute Types. ITU-T Recommendation X.520, 1993. [2] Mockapetris, P., " Domain Names - Concepts and Facilities," STD 13, RFC 1034, November 1987. [3] Kille, S., and M. Wahl, " Lightweight Directory Access Protocol (v3): UTF-8 String Representation of Distinguished Names", RFC 2253, December 1997. [4] Wahl, M., "A Summary of the X.500(96) User Schema for use with LDAP", RFC 2256, December 1997. 7. Security Considerations This memo describes how attributes of objects may be discovered and retrieved. Servers should ensure that an appropriate security policy is maintained. An enterprise is not restricted in the information which it may store in DNS or LDAP servers. A client which contacts an untrusted server may have incorrect or misleading information returned (e.g. an organization's server may claim to hold naming contexts representing domain names which have not been delegated to that organization). 8. Authors' Addresses Steve Kille Isode Ltd. The Dome The Square Richmond, Surrey TW9 1DT England Phone: +44-181-332-9091 EMail: S.Kille@ISODE.COM Kille, et. al. Standards Track [Page 5] RFC 2247 Using Domains in LDAP/X.500 January 1998 Mark Wahl Critical Angle Inc. 4815 W. Braker Lane #502-385 Austin, TX 78759 USA Phone: (1) 512 372 3160 EMail: M.Wahl@critical-angle.com Al Grimstad AT&T Room 1C-429, 101 Crawfords Corner Road Holmdel, NJ 07733-3030 USA EMail: alg@att.com Rick Huber AT&T Room 1B-433, 101 Crawfords Corner Road Holmdel, NJ 07733-3030 USA EMail: rvh@att.com Sri Sataluri AT&T Room 4G-202, 101 Crawfords Corner Road Holmdel, NJ 07733-3030 USA EMail: sri@att.com Kille, et. al. Standards Track [Page 6] RFC 2247 Using Domains in LDAP/X.500 January 1998 9. Full Copyright Statement Copyright (C) The Internet Society (1998). 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. Kille, et. al. Standards Track [Page 7] PK %�c\�x͡e �e ( doc/alt-openldap11-devel/rfc/rfc2849.txtnu �[��� Network Working Group G. Good Request for Comments: 2849 iPlanet e-commerce Solutions Category: Standards Track June 2000 The LDAP Data Interchange Format (LDIF) - Technical Specification Status of this Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2000). All Rights Reserved. Abstract This document describes a file format suitable for describing directory information or modifications made to directory information. The file format, known as LDIF, for LDAP Data Interchange Format, is typically used to import and export directory information between LDAP-based directory servers, or to describe a set of changes which are to be applied to a directory. Background and Intended Usage There are a number of situations where a common interchange format is desirable. For example, one might wish to export a copy of the contents of a directory server to a file, move that file to a different machine, and import the contents into a second directory server. Additionally, by using a well-defined interchange format, development of data import tools from legacy systems is facilitated. A fairly simple set of tools written in awk or perl can, for example, convert a database of personnel information into an LDIF file. This file can then be imported into a directory server, regardless of the internal database representation the target directory server uses. The LDIF format was originally developed and used in the University of Michigan LDAP implementation. The first use of LDIF was in describing directory entries. Later, the format was expanded to allow representation of changes to directory entries. Good Standards Track [Page 1] RFC 2849 LDAP Data Interchange Format June 2000 Relationship to the application/directory MIME content-type: The application/directory MIME content-type [1] is a general framework and format for conveying directory information, and is independent of any particular directory service. The LDIF format is a simpler format which is perhaps easier to create, and may also be used, as noted, to describe a set of changes to be applied to a directory. The key words "MUST", "MUST NOT", "MAY", "SHOULD", and "SHOULD NOT" used in this document are to be interpreted as described in [7]. Definition of the LDAP Data Interchange Format The LDIF format is used to convey directory information, or a description of a set of changes made to directory entries. An LDIF file consists of a series of records separated by line separators. A record consists of a sequence of lines describing a directory entry, or a sequence of lines describing a set of changes to a directory entry. An LDIF file specifies a set of directory entries, or a set of changes to be applied to directory entries, but not both. There is a one-to-one correlation between LDAP operations that modify the directory (add, delete, modify, and modrdn), and the types of changerecords described below ("add", "delete", "modify", and "modrdn" or "moddn"). This correspondence is intentional, and permits a straightforward translation from LDIF changerecords to protocol operations. Formal Syntax Definition of LDIF The following definition uses the augmented Backus-Naur Form specified in RFC 2234 [2]. ldif-file = ldif-content / ldif-changes ldif-content = version-spec 1*(1*SEP ldif-attrval-record) ldif-changes = version-spec 1*(1*SEP ldif-change-record) ldif-attrval-record = dn-spec SEP 1*attrval-spec ldif-change-record = dn-spec SEP *control changerecord version-spec = "version:" FILL version-number Good Standards Track [Page 2] RFC 2849 LDAP Data Interchange Format June 2000 version-number = 1*DIGIT ; version-number MUST be "1" for the ; LDIF format described in this document. dn-spec = "dn:" (FILL distinguishedName / ":" FILL base64-distinguishedName) distinguishedName = SAFE-STRING ; a distinguished name, as defined in [3] base64-distinguishedName = BASE64-UTF8-STRING ; a distinguishedName which has been base64 ; encoded (see note 10, below) rdn = SAFE-STRING ; a relative distinguished name, defined as ; <name-component> in [3] base64-rdn = BASE64-UTF8-STRING ; an rdn which has been base64 encoded (see ; note 10, below) control = "control:" FILL ldap-oid ; controlType 0*1(1*SPACE ("true" / "false")) ; criticality 0*1(value-spec) ; controlValue SEP ; (See note 9, below) ldap-oid = 1*DIGIT 0*1("." 1*DIGIT) ; An LDAPOID, as defined in [4] attrval-spec = AttributeDescription value-spec SEP value-spec = ":" ( FILL 0*1(SAFE-STRING) / ":" FILL (BASE64-STRING) / "<" FILL url) ; See notes 7 and 8, below url = <a Uniform Resource Locator, as defined in [6]> ; (See Note 6, below) AttributeDescription = AttributeType [";" options] ; Definition taken from [4] AttributeType = ldap-oid / (ALPHA *(attr-type-chars)) options = option / (option ";" options) Good Standards Track [Page 3] RFC 2849 LDAP Data Interchange Format June 2000 option = 1*opt-char attr-type-chars = ALPHA / DIGIT / "-" opt-char = attr-type-chars changerecord = "changetype:" FILL (change-add / change-delete / change-modify / change-moddn) change-add = "add" SEP 1*attrval-spec change-delete = "delete" SEP change-moddn = ("modrdn" / "moddn") SEP "newrdn:" ( FILL rdn / ":" FILL base64-rdn) SEP "deleteoldrdn:" FILL ("0" / "1") SEP 0*1("newsuperior:" ( FILL distinguishedName / ":" FILL base64-distinguishedName) SEP) change-modify = "modify" SEP *mod-spec mod-spec = ("add:" / "delete:" / "replace:") FILL AttributeDescription SEP *attrval-spec "-" SEP SPACE = %x20 ; ASCII SP, space FILL = *SPACE SEP = (CR LF / LF) CR = %x0D ; ASCII CR, carriage return LF = %x0A ; ASCII LF, line feed ALPHA = %x41-5A / %x61-7A ; A-Z / a-z DIGIT = %x30-39 ; 0-9 Good Standards Track [Page 4] RFC 2849 LDAP Data Interchange Format June 2000 UTF8-1 = %x80-BF UTF8-2 = %xC0-DF UTF8-1 UTF8-3 = %xE0-EF 2UTF8-1 UTF8-4 = %xF0-F7 3UTF8-1 UTF8-5 = %xF8-FB 4UTF8-1 UTF8-6 = %xFC-FD 5UTF8-1 SAFE-CHAR = %x01-09 / %x0B-0C / %x0E-7F ; any value <= 127 decimal except NUL, LF, ; and CR SAFE-INIT-CHAR = %x01-09 / %x0B-0C / %x0E-1F / %x21-39 / %x3B / %x3D-7F ; any value <= 127 except NUL, LF, CR, ; SPACE, colon (":", ASCII 58 decimal) ; and less-than ("<" , ASCII 60 decimal) SAFE-STRING = [SAFE-INIT-CHAR *SAFE-CHAR] UTF8-CHAR = SAFE-CHAR / UTF8-2 / UTF8-3 / UTF8-4 / UTF8-5 / UTF8-6 UTF8-STRING = *UTF8-CHAR BASE64-UTF8-STRING = BASE64-STRING ; MUST be the base64 encoding of a ; UTF8-STRING BASE64-CHAR = %x2B / %x2F / %x30-39 / %x3D / %x41-5A / %x61-7A ; +, /, 0-9, =, A-Z, and a-z ; as specified in [5] BASE64-STRING = [*(BASE64-CHAR)] Notes on LDIF Syntax 1) For the LDIF format described in this document, the version number MUST be "1". If the version number is absent, implementations MAY choose to interpret the contents as an older LDIF file format, supported by the University of Michigan ldap-3.3 implementation [8]. Good Standards Track [Page 5] RFC 2849 LDAP Data Interchange Format June 2000 2) Any non-empty line, including comment lines, in an LDIF file MAY be folded by inserting a line separator (SEP) and a SPACE. Folding MUST NOT occur before the first character of the line. In other words, folding a line into two lines, the first of which is empty, is not permitted. Any line that begins with a single space MUST be treated as a continuation of the previous (non-empty) line. When joining folded lines, exactly one space character at the beginning of each continued line must be discarded. Implementations SHOULD NOT fold lines in the middle of a multi-byte UTF-8 character. 3) Any line that begins with a pound-sign ("#", ASCII 35) is a comment line, and MUST be ignored when parsing an LDIF file. 4) Any dn or rdn that contains characters other than those defined as "SAFE-UTF8-CHAR", or begins with a character other than those defined as "SAFE-INIT-UTF8-CHAR", above, MUST be base-64 encoded. Other values MAY be base-64 encoded. Any value that contains characters other than those defined as "SAFE-CHAR", or begins with a character other than those defined as "SAFE-INIT-CHAR", above, MUST be base-64 encoded. Other values MAY be base-64 encoded. 5) When a zero-length attribute value is to be included directly in an LDIF file, it MUST be represented as AttributeDescription ":" FILL SEP. For example, "seeAlso:" followed by a newline represents a zero-length "seeAlso" attribute value. It is also permissible for the value referred to by a URL to be of zero length. 6) When a URL is specified in an attrval-spec, the following conventions apply: a) Implementations SHOULD support the file:// URL format. The contents of the referenced file are to be included verbatim in the interpreted output of the LDIF file. b) Implementations MAY support other URL formats. The semantics associated with each supported URL will be documented in an associated Applicability Statement. 7) Distinguished names, relative distinguished names, and attribute values of DirectoryString syntax MUST be valid UTF-8 strings. Implementations that read LDIF MAY interpret files in which these entities are stored in some other character set encoding, but implementations MUST NOT generate LDIF content which does not contain valid UTF-8 data. Good Standards Track [Page 6] RFC 2849 LDAP Data Interchange Format June 2000 8) Values or distinguished names that end with SPACE SHOULD be base-64 encoded. 9) When controls are included in an LDIF file, implementations MAY choose to ignore some or all of them. This may be necessary if the changes described in the LDIF file are being sent on an LDAPv2 connection (LDAPv2 does not support controls), or the particular controls are not supported by the remote server. If the criticality of a control is "true", then the implementation MUST either include the control, or MUST NOT send the operation to a remote server. 10) When an attrval-spec, distinguishedName, or rdn is base64- encoded, the encoding rules specified in [5] are used with the following exceptions: a) The requirement that base64 output streams must be represented as lines of no more than 76 characters is removed. Lines in LDIF files may only be folded according to the folding rules described in note 2, above. b) Base64 strings in [5] may contain characters other than those defined in BASE64-CHAR, and are ignored. LDIF does not permit any extraneous characters, other than those used for line folding. Examples of LDAP Data Interchange Format Example 1: An simple LDAP file with two entries version: 1 dn: cn=Barbara Jensen, ou=Product Development, dc=airius, dc=com objectclass: top objectclass: person objectclass: organizationalPerson cn: Barbara Jensen cn: Barbara J Jensen cn: Babs Jensen sn: Jensen uid: bjensen telephonenumber: +1 408 555 1212 description: A big sailing fan. dn: cn=Bjorn Jensen, ou=Accounting, dc=airius, dc=com objectclass: top objectclass: person objectclass: organizationalPerson cn: Bjorn Jensen sn: Jensen telephonenumber: +1 408 555 1212 Good Standards Track [Page 7] RFC 2849 LDAP Data Interchange Format June 2000 Example 2: A file containing an entry with a folded attribute value version: 1 dn:cn=Barbara Jensen, ou=Product Development, dc=airius, dc=com objectclass:top objectclass:person objectclass:organizationalPerson cn:Barbara Jensen cn:Barbara J Jensen cn:Babs Jensen sn:Jensen uid:bjensen telephonenumber:+1 408 555 1212 description:Babs is a big sailing fan, and travels extensively in sea rch of perfect sailing conditions. title:Product Manager, Rod and Reel Division Example 3: A file containing a base-64-encoded value version: 1 dn: cn=Gern Jensen, ou=Product Testing, dc=airius, dc=com objectclass: top objectclass: person objectclass: organizationalPerson cn: Gern Jensen cn: Gern O Jensen sn: Jensen uid: gernj telephonenumber: +1 408 555 1212 description:: V2hhdCBhIGNhcmVmdWwgcmVhZGVyIHlvdSBhcmUhICBUaGlzIHZhbHVl IGlzIGJhc2UtNjQtZW5jb2RlZCBiZWNhdXNlIGl0IGhhcyBhIGNvbnRyb2wgY2hhcmFjdG VyIGluIGl0IChhIENSKS4NICBCeSB0aGUgd2F5LCB5b3Ugc2hvdWxkIHJlYWxseSBnZXQg b3V0IG1vcmUu Example 4: A file containing an entries with UTF-8-encoded attribute values, including language tags. Comments indicate the contents of UTF-8-encoded attributes and distinguished names. version: 1 dn:: b3U95Za25qWt6YOoLG89QWlyaXVz # dn:: ou=<JapaneseOU>,o=Airius objectclass: top objectclass: organizationalUnit ou:: 5Za25qWt6YOo # ou:: <JapaneseOU> ou;lang-ja:: 5Za25qWt6YOo # ou;lang-ja:: <JapaneseOU> ou;lang-ja;phonetic:: 44GI44GE44GO44KH44GG44G2 Good Standards Track [Page 8] RFC 2849 LDAP Data Interchange Format June 2000 # ou;lang-ja:: <JapaneseOU_in_phonetic_representation> ou;lang-en: Sales description: Japanese office dn:: dWlkPXJvZ2FzYXdhcmEsb3U95Za25qWt6YOoLG89QWlyaXVz # dn:: uid=<uid>,ou=<JapaneseOU>,o=Airius userpassword: {SHA}O3HSv1MusyL4kTjP+HKI5uxuNoM= objectclass: top objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson uid: rogasawara mail: rogasawara@airius.co.jp givenname;lang-ja:: 44Ot44OJ44OL44O8 # givenname;lang-ja:: <JapaneseGivenname> sn;lang-ja:: 5bCP56yg5Y6f # sn;lang-ja:: <JapaneseSn> cn;lang-ja:: 5bCP56yg5Y6fIOODreODieODi+ODvA== # cn;lang-ja:: <JapaneseCn> title;lang-ja:: 5Za25qWt6YOoIOmDqOmVtw== # title;lang-ja:: <JapaneseTitle> preferredlanguage: ja givenname:: 44Ot44OJ44OL44O8 # givenname:: <JapaneseGivenname> sn:: 5bCP56yg5Y6f # sn:: <JapaneseSn> cn:: 5bCP56yg5Y6fIOODreODieODi+ODvA== # cn:: <JapaneseCn> title:: 5Za25qWt6YOoIOmDqOmVtw== # title:: <JapaneseTitle> givenname;lang-ja;phonetic:: 44KN44Gp44Gr44O8 # givenname;lang-ja;phonetic:: <JapaneseGivenname_in_phonetic_representation_kana> sn;lang-ja;phonetic:: 44GK44GM44GV44KP44KJ # sn;lang-ja;phonetic:: <JapaneseSn_in_phonetic_representation_kana> cn;lang-ja;phonetic:: 44GK44GM44GV44KP44KJIOOCjeOBqeOBq+ODvA== # cn;lang-ja;phonetic:: <JapaneseCn_in_phonetic_representation_kana> title;lang-ja;phonetic:: 44GI44GE44GO44KH44GG44G2IOOBtuOBoeOCh+OBhg== # title;lang-ja;phonetic:: # <JapaneseTitle_in_phonetic_representation_kana> givenname;lang-en: Rodney sn;lang-en: Ogasawara cn;lang-en: Rodney Ogasawara title;lang-en: Sales, Director Good Standards Track [Page 9] RFC 2849 LDAP Data Interchange Format June 2000 Example 5: A file containing a reference to an external file version: 1 dn: cn=Horatio Jensen, ou=Product Testing, dc=airius, dc=com objectclass: top objectclass: person objectclass: organizationalPerson cn: Horatio Jensen cn: Horatio N Jensen sn: Jensen uid: hjensen telephonenumber: +1 408 555 1212 jpegphoto:< file:///usr/local/directory/photos/hjensen.jpg Example 6: A file containing a series of change records and comments version: 1 # Add a new entry dn: cn=Fiona Jensen, ou=Marketing, dc=airius, dc=com changetype: add objectclass: top objectclass: person objectclass: organizationalPerson cn: Fiona Jensen sn: Jensen uid: fiona telephonenumber: +1 408 555 1212 jpegphoto:< file:///usr/local/directory/photos/fiona.jpg # Delete an existing entry dn: cn=Robert Jensen, ou=Marketing, dc=airius, dc=com changetype: delete # Modify an entry's relative distinguished name dn: cn=Paul Jensen, ou=Product Development, dc=airius, dc=com changetype: modrdn newrdn: cn=Paula Jensen deleteoldrdn: 1 # Rename an entry and move all of its children to a new location in # the directory tree (only implemented by LDAPv3 servers). dn: ou=PD Accountants, ou=Product Development, dc=airius, dc=com changetype: modrdn newrdn: ou=Product Development Accountants deleteoldrdn: 0 newsuperior: ou=Accounting, dc=airius, dc=com Good Standards Track [Page 10] RFC 2849 LDAP Data Interchange Format June 2000 # Modify an entry: add an additional value to the postaladdress # attribute, completely delete the description attribute, replace # the telephonenumber attribute with two values, and delete a specific # value from the facsimiletelephonenumber attribute dn: cn=Paula Jensen, ou=Product Development, dc=airius, dc=com changetype: modify add: postaladdress postaladdress: 123 Anystreet $ Sunnyvale, CA $ 94086 - delete: description - replace: telephonenumber telephonenumber: +1 408 555 1234 telephonenumber: +1 408 555 5678 - delete: facsimiletelephonenumber facsimiletelephonenumber: +1 408 555 9876 - # Modify an entry: replace the postaladdress attribute with an empty # set of values (which will cause the attribute to be removed), and # delete the entire description attribute. Note that the first will # always succeed, while the second will only succeed if at least # one value for the description attribute is present. dn: cn=Ingrid Jensen, ou=Product Support, dc=airius, dc=com changetype: modify replace: postaladdress - delete: description - Example 7: An LDIF file containing a change record with a control version: 1 # Delete an entry. The operation will attach the LDAPv3 # Tree Delete Control defined in [9]. The criticality # field is "true" and the controlValue field is # absent, as required by [9]. dn: ou=Product Development, dc=airius, dc=com control: 1.2.840.113556.1.4.805 true changetype: delete Good Standards Track [Page 11] RFC 2849 LDAP Data Interchange Format June 2000 Security Considerations Given typical directory applications, an LDIF file is likely to contain sensitive personal data. Appropriate measures should be taken to protect the privacy of those persons whose data is contained in an LDIF file. Since ":<" directives can cause external content to be included when processing an LDIF file, one should be cautious of accepting LDIF files from external sources. A "trojan" LDIF file could name a file with sensitive contents and cause it to be included in a directory entry, which a hostile entity could read via LDAP. LDIF does not provide any method for carrying authentication information with an LDIF file. Users of LDIF files must take care to verify the integrity of an LDIF file received from an external source. Acknowledgments The LDAP Interchange Format was developed as part of the University of Michigan LDAP reference implementation, and was developed by Tim Howes, Mark Smith, and Gordon Good. It is based in part upon work supported by the National Science Foundation under Grant No. NCR- 9416667. Members of the IETF LDAP Extensions Working group provided many helpful suggestions. In particular, Hallvard B. Furuseth of the University of Oslo made many significant contributions to this document, including a thorough review and rewrite of the BNF. References [1] Howes, T. and M. Smith, "A MIME Content-Type for Directory Information", RFC 2425, September 1998. [2] Crocker, D., and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, November 1997. [3] Wahl, M., Kille, S. and T. Howes, "A String Representation of Distinguished Names", RFC 2253, December 1997. [4] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, July 1997. [5] Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", RFC 2045, November 1996. Good Standards Track [Page 12] RFC 2849 LDAP Data Interchange Format June 2000 [6] Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform Resource Locators (URL)", RFC 1738, December 1994. [7] Bradner, S., "Key Words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [8] The SLAPD and SLURPD Administrators Guide. University of Michigan, April 1996. <URL: http://www.umich.edu/~dirsvcs/ldap/doc/guides/slapd/toc.html> [9] M. P. Armijo, "Tree Delete Control", Work in Progress. Author's Address Gordon Good iPlanet e-commerce Solutions 150 Network Circle Mailstop USCA17-201 Santa Clara, CA 95054, USA Phone: +1 408 276 4351 EMail: ggood@netscape.com Good Standards Track [Page 13] RFC 2849 LDAP Data Interchange Format June 2000 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. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Good Standards Track [Page 14] PK %�c\��֓' ' ( doc/alt-openldap11-devel/rfc/rfc3673.txtnu �[��� Network Working Group K. Zeilenga Request for Comments: 3673 OpenLDAP Foundation Category: Standards Track December 2003 Lightweight Directory Access Protocol version 3 (LDAPv3): All Operational Attributes Status of this Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2003). All Rights Reserved. Abstract The Lightweight Directory Access Protocol (LDAP) supports a mechanism for requesting the return of all user attributes but not all operational attributes. This document describes an LDAP extension which clients may use to request the return of all operational attributes. 1. Overview X.500 [X.500] provides a mechanism for clients to request all operational attributes be returned with entries provided in response to a search operation. This mechanism is often used by clients to discover which operational attributes are present in an entry. This documents extends the Lightweight Directory Access Protocol (LDAP) [RFC3377] to provide a simple mechanism which clients may use to request the return of all operational attributes. The mechanism is designed for use with existing general purpose LDAP clients (including web browsers which support LDAP URLs) and existing LDAP APIs. 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]. Zeilenga Standards Track [Page 1] RFC 3673 LDAPv3: All Operational Attributes December 2003 2. All Operational Attributes The presence of the attribute description "+" (ASCII 43) in the list of attributes in a Search Request [RFC2251] SHALL signify a request for the return of all operational attributes. As with all search requests, client implementors should note that results may not include all requested attributes due to access controls or other restrictions. Client implementors should also note that certain operational attributes may be returned only if requested by name even when "+" is present. This is because some operational attributes are very expensive to return. Servers supporting this feature SHOULD publish the Object Identifier 1.3.6.1.4.1.4203.1.5.1 as a value of the 'supportedFeatures' [RFC3674] attribute in the root DSE. 3. Interoperability Considerations This mechanism is specifically designed to allow users to request all operational attributes using existing LDAP clients. In particular, the mechanism is designed to be compatible with existing general purpose LDAP clients including those supporting LDAP URLs [RFC2255]. The addition of this mechanism to LDAP is not believed to cause any significant interoperability issues (this has been confirmed through testing). Servers which have yet to implement this specification should ignore the "+" as an unrecognized attribute description per [RFC2251, Section 4.5.1]. From the client's perspective, a server which does not return all operational attributes when "+" is requested should be viewed as having other restrictions. It is also noted that this mechanism is believed to require no modification of existing LDAP APIs. 4. Security Considerations This document provides a general mechanism which clients may use to discover operational attributes. Prior to the introduction of this mechanism, operational attributes were only returned when requested by name. Some might have viewed this as obscurity feature. However, this feature offers a false sense of security as the attributes were still transferable. Implementations SHOULD implement appropriate access controls mechanisms to restricts access to operational attributes. Zeilenga Standards Track [Page 2] RFC 3673 LDAPv3: All Operational Attributes December 2003 5. IANA Considerations This document uses the OID 1.3.6.1.4.1.4203.1.5.1 to identify the feature described above. This OID was assigned [ASSIGN] by OpenLDAP Foundation, under its IANA-assigned private enterprise allocation [PRIVATE], for use in this specification. Registration of this feature has been completed by IANA [RFC3674], [RFC3383]. Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: 1.3.6.1.4.1.4203.1.5.1 Description: All Op Attrs Person & email address to contact for further information: Kurt Zeilenga <kurt@openldap.org> Usage: Feature Specification: RFC3673 Author/Change Controller: IESG Comments: none 6. Acknowledgment The "+" mechanism is believed to have been first suggested by Bruce Greenblatt in a November 1998 post to the IETF LDAPext Working Group mailing list. 7. 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. Zeilenga Standards Track [Page 3] RFC 3673 LDAPv3: All Operational Attributes December 2003 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. 8. References 8.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2251] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [RFC3377] Hodges, J. and R. Morgan, "Lightweight Directory Access Protocol (v3): Technical Specification", RFC 3377, September 2002. [RFC3674] Zeilenga, K., "Feature Discovery in Lightweight Directory Access Protocol (LDAP)", RFC 3674, December 2003. 8.2. Informative References [RFC2255] Howes, T. and M. Smith, "The LDAP URL Format", RFC 2255, December 1997. [RFC3383] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 3383, September 2002. [X.500] ITU-T Rec. X.500, "The Directory: Overview of Concepts, Models and Service", 1993. [ASSIGN] OpenLDAP Foundation, "OpenLDAP OID Delegations", http://www.openldap.org/foundation/oid-delegate.txt. [PRIVATE] IANA, "Private Enterprise Numbers", http://www.iana.org/assignments/enterprise-numbers. 9. Author's Address Kurt D. Zeilenga OpenLDAP Foundation EMail: Kurt@OpenLDAP.org Zeilenga Standards Track [Page 4] RFC 3673 LDAPv3: All Operational Attributes December 2003 10. Full Copyright Statement Copyright (C) The Internet Society (2003). 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 assignees. 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. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Zeilenga Standards Track [Page 5] PK &�c\5���� � ( doc/alt-openldap11-devel/rfc/rfc3663.txtnu �[��� Network Working Group A. Newton Request for Comments: 3663 VeriSign, Inc. Category: Experimental December 2003 Domain Administrative Data in Lightweight Directory Access Protocol (LDAP) Status of this Memo This memo defines an Experimental Protocol for the Internet community. It does not specify an Internet standard of any kind. Discussion and suggestions for improvement are requested. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2003). All Rights Reserved. Abstract Domain registration data has typically been exposed to the general public via Nicname/Whois for administrative purposes. This document describes the Referral Lightweight Directory Access Protocol (LDAP) Service, an experimental service using LDAP and well-known LDAP types to make domain administrative data available. Newton Experimental [Page 1] RFC 3663 Domain Administrative Data in LDAP December 2003 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Historical Directory Services for Domain Registration Data . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.2. Motivations. . . . . . . . . . . . . . . . . . . . . . . 3 1.3. Abbreviations Used . . . . . . . . . . . . . . . . . . . 4 2. Service Description. . . . . . . . . . . . . . . . . . . . . . 4 3. Registry LDAP Service. . . . . . . . . . . . . . . . . . . . . 6 3.1. TLD DIT. . . . . . . . . . . . . . . . . . . . . . . . . 6 3.1.1. DIT Structure. . . . . . . . . . . . . . . . . . 6 3.1.2. Allowed Searches . . . . . . . . . . . . . . . . 7 3.1.3. Access Control . . . . . . . . . . . . . . . . . 7 3.2. Name Server DIT. . . . . . . . . . . . . . . . . . . . . 8 3.2.1. DIT Structure. . . . . . . . . . . . . . . . . . 8 3.2.2. Allowed Searches . . . . . . . . . . . . . . . . 8 3.3. Registrar Referral DIT . . . . . . . . . . . . . . . . . 9 3.3.1. DIT Structure. . . . . . . . . . . . . . . . . . 9 4. Registrar LDAP Service . . . . . . . . . . . . . . . . . . . . 10 4.1. TLD DIT. . . . . . . . . . . . . . . . . . . . . . . . . 10 4.1.1. DIT Structure. . . . . . . . . . . . . . . . . . 10 4.1.2. Allowed Searches . . . . . . . . . . . . . . . . 11 4.1.3. Access Control . . . . . . . . . . . . . . . . . 11 4.2. Name Server and Contact DIT. . . . . . . . . . . . . . . 12 4.2.1. DIT Structure. . . . . . . . . . . . . . . . . . 12 4.2.2. Allowed Searches . . . . . . . . . . . . . . . . 13 5. Clients. . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 6. Lessons Learned. . . . . . . . . . . . . . . . . . . . . . . . 14 6.1. Intra-Server Referrals . . . . . . . . . . . . . . . . . 14 6.2. Inter-Server Referrals . . . . . . . . . . . . . . . . . 15 6.3. Common DIT . . . . . . . . . . . . . . . . . . . . . . . 15 6.4. Universal Client . . . . . . . . . . . . . . . . . . . . 16 6.5. Targeting Searches by Tier . . . . . . . . . . . . . . . 16 6.6. Data Mining. . . . . . . . . . . . . . . . . . . . . . . 16 7. IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 16 8. Internationalization Considerations. . . . . . . . . . . . . . 16 9. Security Considerations. . . . . . . . . . . . . . . . . . . . 17 10. Intellectual Property Statement. . . . . . . . . . . . . . . . 17 11. Normative References . . . . . . . . . . . . . . . . . . . . . 18 Appendix A. Other Work. . . . . . . . . . . . . . . . . . . . . . 19 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . . 19 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 20 Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 21 Newton Experimental [Page 2] RFC 3663 Domain Administrative Data in LDAP December 2003 1. Introduction This document describes the Referral Lightweight Directory Access Protocol (LDAP) Service, an experimental project launched by VeriSign, Inc., to explore the use of LDAP and LDAP-related technologies for use as a directory service of administrative domain registration information. 1.1. Historical Directory Services for Domain Registration Data The original National Science Foundation contract for the InterNIC called for the creation of an X.500 directory service for the administrative needs of the domain registration data and information. Due to problems with implementations of X.500 server software, a server based on the Nicname/Whois [1] protocol was temporarily erected. In 1994, the Rwhois [3] protocol was introduced to enhance the Nicname/Whois protocol. This directory service never gained wide acceptance for use with domain data. Presently, ICANN requires the operation of Nicname/Whois servers by registries and registrars of generic Top-Level Domains (TLD's). 1.2. Motivations With the recent split in functional responsibilities between registries and registrars, the constant misuse and data-mining of domain registration data, and the difficulties with machine- readability of Nicname/Whois output, the creation of the Referral LDAP Service had the following motivations: o Use a mechanism native to the directory protocol to refer clients from inquiries about specific domains made at a registry to the appropriate domain within the appropriate directory service at a registrar. o Limit access to domain data based on authentication of the client. o Provide structured queries and well-known and structured results. o Use a directory service technology already in general use. Given these general criteria, LDAP [5] was selected as the protocol for this directory service. The decision was also made to restrict the use of LDAP to features most readily available in common implementations. Therefore, a goal was set to not define any new object classes, syntaxes, or matching rules. Newton Experimental [Page 3] RFC 3663 Domain Administrative Data in LDAP December 2003 The experiment was successful in exploring how LDAP might be used in this context and demonstrating the level of customization required for an operational service. Conclusions and observations about this experiment are outlined in Section 6. 1.3. Abbreviations Used The following abbreviations are used to describe the nature of this experiment: TLD: Top-Level Domain. Refers to the domain names just beneath the root in the Domain Name System. This experiment used the TLD's .com, .net, .org, and .edu. SLD: Second-Level Domain. Refers to the domain names just beneath a TLD in the Domain Name System. An example of such a domain name would be "example.com". DIT: Directory Information Tree. One of many hierarchies of data entries in an LDAP server. DN: Distinguished Name. The unique name of an entry in a DIT. cn: common name. See RFC 2256 [7]. dc: domain component. See RFC 2247 [4]. uid: user id. See RFC 2798 [9]. 2. Service Description The service is composed of three distinct server types: a registry LDAP server, registrar LDAP servers, and registrant LDAP servers. The registry LDAP server contains three Directory Information Trees (DIT's). o The Top-Level Domain DIT's follow the DNS hierarchy for domains (e.g., dc=foo,dc=com). o The name server DIT allows a view of the name servers, many of which serve multiple domains. o The registrar-referral DIT provides referrals from the registry into the respective TLD DIT of the registrars (on a TLD basis). Newton Experimental [Page 4] RFC 3663 Domain Administrative Data in LDAP December 2003 The registrar LDAP server contains two types of DIT's. o The TLD DIT follows the DNS hierarchy for domains (e.g., dc=foo,dc=com) and parallels the TLD DIT of the registry. o The name server and contact DIT allow a view of the name servers and contacts, many of which are associated and serve multiple domains. There is no specification on the DIT or schema for the registrant LDAP server. Referrals from the registrar server to the registrant server are provided solely for the purpose of allowing the registrant direct control over extra administrative information as it relates to a particular domain. Access control for this service is merely a demonstration of using a Distinguished Name (DN) and password. Should registries and registrars uniformly adopt LDAP as a means to disseminate domain registration data, standardization of these DN's would need to be undertaken based on each type of user base. Newton Experimental [Page 5] RFC 3663 Domain Administrative Data in LDAP December 2003 3. Registry LDAP Service 3.1. TLD DIT 3.1.1. DIT Structure The registry TLD DIT has the following structural hierarchy: TLD (e.g., dc=net) | | ------------------------------------- | | SLD (e.g., dc=foo,dc=net) SLD (e.g., dc=bar,dc=net) | | --------------------- --------------------- | | | | | | name server | | name server | | (e.g., | | (e.g., | | cn=nameserver1, | | cn=nameserver1, | | dc=foo,dc=net ) | | dc=bar,dc=net ) | | | | | | name server | name server | (e.g., | (e.g., | cn=nameserver2, | cn=nameserver2, | dc=foo,dc=net ) | dc=bar,dc=net ) | | | registrar referral registrar referral (e.g., (e.g., cn=registrar, cn=registrar, dc=foo,dc=net ) dc=bar,dc=net ) Figure 1: Registry DIT Overview The root of a TLD DIT is an entry of objectclass domain as specified by RFC 2247 [4] and represents a top-level domain. The second tier of the DIT represents second-level domains. Each of these entries is of objectclass domain as specified by RFC 2247 [4]. The description attribute on these entries often contains descriptive text giving the name of the registrar through which these domains have been registered. The third tier contains entries specific to each second-level domain. Name server entries are of objectclass ipHost as specified by RFC 2307 [8]. The distinguished names of these name server entries are algorithmically calculated, where the first component is the word Newton Experimental [Page 6] RFC 3663 Domain Administrative Data in LDAP December 2003 "nameserver" concatenated with an index number of the name server entry and the remaining components are the appropriate domain names. There is no specification relating the value of the name server entry to the index it may be assigned other than it is unique and consistent with respect to the client session. This tier also contains the referral from the registry to the registrar. This referral is a direct referral to the entry in the appropriate registrar LDAP server corresponding to the domain name that the referral falls beneath in this DIT. 3.1.2. Allowed Searches Because of the vast number of entries contained within this DIT, only certain types of searches are allowed. Allowing any search expressible via LDAP would lead to expensive searches that would be far too costly for a publicly available service. The searches allowed are as follows: o One-level scoped searches based at the root of the DIT. Substring matching is allowed on dc attributes, but the substring must be at least be 3 characters in length. o Base search based at the root of the DIT. o Base, one-level, and sub-tree searches based at any second level domain name (the second tier) and below. 3.1.3. Access Control The registry TLD DIT only has one access control type. When a client binds with a DN of "cn=trademark" and password of "attorney", the second-level domain entries also take on an objectclass of extensibleObject with the added attributes of "createddate" and "registrationexpirationdate", which are of type Generalized Time, as specified by RFC 2252 [6]. Newton Experimental [Page 7] RFC 3663 Domain Administrative Data in LDAP December 2003 3.2. Name Server DIT 3.2.1. DIT Structure The registry name server DIT has the following structural hierarchy: (o=nsiregistry.com) | | ------------------------------------- | | | name server name server name server (cn=ns1.foo.net) (cn=ns.bar.com) (cn=named.acme.org) Figure 2: Registry DIT Overview The root of a name server DIT is an entry of objectclass organization as specified by RFC 1617 [2]. It has no significance other than to serve as the root of the DIT. The second tier of this DIT represents name servers. Each of these entries is of objectclass ipHost, as specified by RFC 2307 [8]. 3.2.2. Allowed Searches Because of the vast number of entries contained within this DIT, only certain types of searches are allowed. Allowing any search expressible via LDAP would lead to searches far too costly for a publicly available service. The searches allowed are as follows: o One-level and sub-tree scoped searches based at the root of the DIT if a filter on the cn attribute is provided. o Base search based at the root of the DIT. o Base, one-level, and sub-tree searches based at any name server entry. Newton Experimental [Page 8] RFC 3663 Domain Administrative Data in LDAP December 2003 3.3. Registrar Referral DIT 3.3.1. DIT Structure The registry registrar-referral DIT has the following structural hierarchy: (o=tlds) | | ------------------------------- | | | | tld tld tld tld (dc=net) (dc=com) (dc=org) (dc=edu) | | | | : : | : : : | : | --------------------------- | | | referral to referral to referral to registrar 1 registrar 2 registrar n dc=org DIT dc=org DIT dc=org DIT Figure 3: Registry Referral DIT Overview The root of the registrar referral DIT is an entry of objectclass organization, as specified by RFC 1617 [2]. It has no significance other than to serve as the root of this DIT. The second tier of this DIT represents top-level domains. Each of these entries is of objectclass domain, as specified by RFC 2247 [4]. Underneath each TLD entry, the third tier contains referrals to the appropriate TLD DIT of each registrar. Newton Experimental [Page 9] RFC 3663 Domain Administrative Data in LDAP December 2003 4. Registrar LDAP Service 4.1. TLD DIT 4.1.1. DIT Structure The registrar TLD DIT, which is similar to the registry TLD DIT, has the following structural hierarchy: TLD (e.g., dc=net) | | ------------------------------------------------ | | | SLD (e.g., dc=foo,dc=net) : : | : : --------------------------------------------- | | | | | | name server contact referral to (e.g., cn=nameserver1, (e.g., cn=contact1, registrant dc=foo,dc=net ) dc=foo,dc=net ) | | name server contact (e.g., cn=contact, cn=nameserver1, dc=foo,dc=net ) Figure 4: Registrar DIT Overview The root of a TLD DIT is an entry of objectclass domain, as specified by RFC 2247 [4] and represents a top-level domain. The second tier of the DIT represents second-level domains. Each of these entries is of objectclass domain, as specified by RFC 2247 [4]. The third tier contains entries specific to each second-level domain. The entries at this level are as follows: o Name server entries are of objectclass ipHost, as specified by RFC 2307 [8]. The distinguished names of these name server entries are algorithmically calculated where the first component is the word "nameserver" concatenated with an index number of the name server entry and the remaining components are the appropriate domain names. There is no specification relating the value of the name server entry to the index it may be assigned other than it is unique and consistent with respect to the client session. Newton Experimental [Page 10] RFC 3663 Domain Administrative Data in LDAP December 2003 o Contact entries are of objectclass inetOrgPerson, as specified by RFC 2798 [9]. The distinguished names of these contact entries are algorithmically calculated, where the first component is the word "contact" concatenated with an index number of the contact and the remaining components are the appropriate domain names. There is no specification relating the value of the contact entry to the index it may be assigned other than it is unique and consistent with respect to the client session. The description attribute of the entry contains the role for which a contact is related to a domain. These roles are identified as "Admin Contact", "Technical Contact", and "Billing Contact", and may appear in any order. o Finally, this third tier contains the referral from the registrar to the registrant. The fourth tier only contains name server contact entries. These entries are of objectclass inetOrgPerson, as specified by RFC 2798 [9]. 4.1.2. Allowed Searches Because of the vast number of entries contained within this DIT, only certain types of searches are allowed. Allowing any search expressible via LDAP would lead to searches far too costly for a publicly available service. The searches allowed are as follows: o One-level scoped searches based at the root of the DIT. Substring matching is allowed on dc and o attributes, but the substring must be at least 3 characters in length. o Base search based at the root of the DIT. o Base, one-level, and sub-tree searches based at any second level domain name (the second tier) and below. 4.1.3. Access Control The registrar TLD DIT has two access control types. When binding anonymously, a client only sees dc, o, and c attributes of the second-level domain entries. When a client binds with a DN of "cn=trademark" and password of "attorney", all of the other attributes normally available on entries of objectclass domain are visible if they have values. In addition, if a client binds with the DN of a contact and password of "password", all attributes for second-level domain entries for which the bind DN has a relation are visible. Newton Experimental [Page 11] RFC 3663 Domain Administrative Data in LDAP December 2003 4.2. Name Server and Contact DIT 4.2.1. DIT Structure The registrar name server and contact DIT has the following structural hierarchy: (o=nsi.com) | | -------------------------------------- | | Contacts Name Servers (ou=contacts) (ou=name servers) | | ----------------- ------------------------ | | | | | | Contact : : Name Server : : (uid=handle) : : (cn=handle) : : | Name Server Contact (cn=contact1) Figure 5: Registrar DIT Overview The first tier of the name server and contact DIT is an entry of objectclass organization, as specified by RFC 1617 [2]. The second tier of the DIT contains two entries, each of which is of objectclass organizationalUnit, as specified by RFC 2256 [7]. One entry represents the part of the DIT containing contacts and the other entry represents the part of the DIT containing name servers. Entries underneath the contacts organizationalUnit entry are of objectclass inetOrgPerson and represent contacts registered with the registrar. Their RDN is composed of the uid attribute. The uid attribute's value is a unique identifier or handle that is registrar assigned. Entries underneath the name server organizationalUnit entry are of objectclass ipHost and represent name servers registered with the registrar. Their RDN is composed of the cn attribute. The cn attribute's value is a unique identifier or handle that is registrar assigned. Each name server entry may optionally have children entries of objectclass inetOrgPerson. These entries represent the contacts of the name server they fall beneath. Newton Experimental [Page 12] RFC 3663 Domain Administrative Data in LDAP December 2003 4.2.2. Allowed Searches Because of the vast number of entries contained within this DIT, only certain types of searches are allowed. Allowing any search expressible via LDAP would lead to searches far too costly for a publicly available service. The searches allowed are as follows: o One-level and base searches at the root of the DIT. o Sub-tree searches at the root of the DIT using cn and uid attributes as a filter. o Base searches at either entry of the second tier. o One-level and sub-tree searches at either entry of the second tier, using cn or uid attributes as a filter. o Base, one-level, and sub-tree searches based at any contact or name server entry and below. 5. Clients Early scoping and analysis of this project were based on the use of output from command line clients, specifically the "ldapsearch" command present with many implementations of LDAP servers. Our survey of this tool, available from many vendors, showed that referral chasing was difficult to control or predict, and the behavior between these implementations with respect to referral chasing was inconsistent. Based on the limited nature of the expressive capabilities present with just command line tools, searches involving nested queries or advanced referral chasing were deemed the domain of clients making direct use of LDAP client libraries. Three of these types of clients were produced: a web-based client, a cross-platform C-based client, and a Java client. No significant deficiencies or problems were found with the LDAP client libraries in the construction of these clients, and the level of control provided by their programming interfaces was adequate to create the necessary searches. Instead, most of the problems encountered with these clients were based on usability concerns. It was found that the web-based client caused a great amount of confusion for users not familiar with LDAP or Nicname/Whois with respect to the underlying technology and the network model. Thus, many users believed the web-based client to be the only interface to the data and were unaware or confused by the intermediate LDAP protocol. In addition, it was difficult to express to users the Newton Experimental [Page 13] RFC 3663 Domain Administrative Data in LDAP December 2003 registry-registrar-registrant service model in adequate terms from search results where the results could be rendered properly among the various common web browsers. Both the C and Java based clients were built to be both graphical and cross-platform (in the case of the C-based client, the Linux and Windows platforms were chosen as targets). The LDAP client libraries chosen for both clients proved to be quite capable and offered the necessary levels of control for conducting nested queries and advanced referral chasing. Expectations at the outset for construction of both clients, based on past experience, were that the C-based client would not only perform better than the Java client but also have a better appearance. In reality, these assumptions were incorrect as there was no perceivable difference in performance and the look of the Java client was often considered to be far superior to its counter-part. In addition, the Java client required much less time to create. Both clients are available under the terms of an open source license. Though it is impossible to have accurate measurements of their popularity, through monitoring and feedback it was perceived that the web-based client had far greater use. 6. Lessons Learned Based on the experience of piloting this experimental service, feedback from users of the service, and general comments and observations of current and common opinions, the following items have been noted. 6.1. Intra-Server Referrals Original analysis of the data set to be used revealed a high degree of relationships between name servers, contacts, and domains. Storing the data in non-normalized form according to the DIT outlined in this document would make an original relational dataset of roughly 20 million objects explode to over 115 million objects. To combat this problem, the first pass at defining the DIT's made heavy use of referrals between the TLD DIT's and the name server and contact DIT's. The use of the 'alias' objectclass was considered but ruled out in hopes of using referrals for load balancing across servers (i.e., placing each TLD DIT on a separate server, and separate servers for the name server and contact DIT's). However, initial testing with the 'ldapsearch' command found inconsistencies with the interpretation of the referrals and how they were managed. Not only were the results inconsistent between implementations, but many of these clients would easily get caught in referral loops. Newton Experimental [Page 14] RFC 3663 Domain Administrative Data in LDAP December 2003 The final solution to the problem was to create a customized back-end data store containing the data in a normalized form. This gave the client the appearance of having a non-normalized data set which required no intra-server referrals. Aliases may have been a better solution, however our interpretation of their output with implementations of the 'ldapsearch' tool was not satisfactory. It was also later learned that some LDAP server implementations place certain restrictions on aliases that would have conflicted with our overall DIT structure. In the end, it was felt that a customized back-end would be required by any server with a large data-set, but smaller data-sets for less populated domains could easily use off- the-shelf implementations. 6.2. Inter-Server Referrals The modeling of the overall service to provide the split in operational responsibility between registry and registrar required the use of referrals (i.e., the two servers would not be operated by the same organization, therefore would most likely not co-exist on the same physical machine or network). The chief problem with LDAP referrals returned for this purpose grew out of the need to limit data returned to the client and the priority given to referrals. It was quite easy to cause a sub-tree query at certain levels, for instance a TLD level, to return nothing but referrals. This was true because referrals would be returned out of the scope of the supplied search filter and therefore would fill the result set to its limit, normally set to 50 entries. In certain use cases, a result set with nothing but referrals was desired (e.g., o=tlds). However, even in these cases it was possible for some referrals to not be returned due to the size limit. In this case, it was felt that a result set of 50 referrals, the default for the size limit in most cases, was too large for any practical use by a client and was a failing of query distribution in general rather than a limitation of LDAP. 6.3. Common DIT Because of the nature of software development, the graphical and web clients were developed after the development of the server software. The 'ldapsearch' client was used for testing and development during server software creation. It was not until the creation of more advanced clients that it was discovered that the design decision of uniform DIT naming should have been made. Technically, this would have allowed for slightly better software modularization and re-use. In addition, the use of a company name in the DIT structure did not allow the easy integration of another domain registry, as in the registry-registrar model. Not only would clients have to be Newton Experimental [Page 15] RFC 3663 Domain Administrative Data in LDAP December 2003 reconfigured for each new registry operator, but this would most likely have social implications as well. 6.4. Universal Client The construction of the clients revealed yet another misconception. Though this project used a generic directory service technology, the clients required a high-degree of algorithmic knowledge about the DIT structure and schemas being used. The graphical clients could not be used against an LDAP service with another DIT or schema. Therefore, a generic or universal client, one that could be used for all LDAP applications, would either not be able to make full use of the data provided by the service or would be far too complex for operation by the average user. 6.5. Targeting Searches by Tier The network model for this service was divided into three tiers: registry, registrar, and registrant. Despite this, all searches needed to start at the registry level causing overhead for searches that could be targeted at a select tier. This service did not implement a solution to this problem, such as using SRV and/or NAPTR records in DNS to allow a client to find a responsible LDAP server. 6.6. Data Mining Section 3.1.2 and Section 4.1.2 describe the searches allowed by this service. However, the most common question asked by users of the service revolved around getting around these restrictions. Because browsing at the TLD level was not permitted, many users asked about the feasibility of using recursive dictionary queries to circumvent the search restrictions. It should be noted that many operators of Nicname/Whois server consider this practice to be data mining and often refer to it specifically as a dictionary attack. 7. IANA Considerations There are no applicable IANA considerations presented in this document. 8. Internationalization Considerations The domain administrative data in this service did not cover Internationalized Domain Names (IDN's). Newton Experimental [Page 16] RFC 3663 Domain Administrative Data in LDAP December 2003 9. Security Considerations This experiment did not endeavor to use security mechanisms beyond those readily available in LDAP [5]. Section 3.1.3 and Section 4.1.3 describe the various access controls used within the scope of the defined security mechanisms. While these mechanisms were adequate for this experimental deployment, they would not be adequate for a production environment, and they should not be taken as a model for those contemplating deployment on the Internet. 10. 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. Newton Experimental [Page 17] RFC 3663 Domain Administrative Data in LDAP December 2003 11. Normative References [1] Harrenstien, K., Stahl, M. and E. Feinler, "NICNAME/WHOIS", RFC 954, October 1985. [2] Barker, P., Kille, S. and T. Lenggenhager, "Naming and Structuring Guidelines for X.500 Directory Pilots", RFC 1617, May 1994. [3] Williamson, S., Kosters, M., Blacka, D., Singh, J. and K. Zeilstra, "Referral Whois (RWhois) Protocol V1.5", RFC 2167, June 1997. [4] Kille, S., Wahl, M., Grimstad, A., Huber, R. and S. Sataluri, "Using Domains in LDAP/X.500 Distinguished Names", RFC 2247, January 1998. [5] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [6] Wahl, M., Coulbeck, A., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (v3): Attribute Syntax Definitions", RFC 2252, December 1997. [7] Wahl, M., "A Summary of the X.500(96) User Schema for use with LDAPv3", RFC 2256, December 1997. [8] Howard, L., "An Approach for Using LDAP as a Network Information Service", RFC 2307, March 1998. [9] Smith, M., "Definition of the inetOrgPerson LDAP Object Class", RFC 2798, April 2000. Newton Experimental [Page 18] RFC 3663 Domain Administrative Data in LDAP December 2003 Appendix A. Other Work In addition to the deployment of servers and development of clients, VeriSign conducted two sub-projects related to this experiment. The first project was a Nicname/Whois-to-LDAP gateway. The goal of the project was to create an LDAP server for use by registrars to deploy in front of their Nicname/Whois servers. This gateway would take LDAP requests, translate them to Nicname/Whois requests, issue the request to a specific Nicname/Whois server deployed on port 43, interpret the response, and return LDAP result sets. Because of the unspecified nature of Nicname/Whois result sets, the gateway was programmed to specifically recognize only the output of three distinct registrars. While this gateway proved valuable enough to allow domain lookups and limited searches, it was unable to provide consistent contact lookups, nameserver lookups, or registrant referrals. This software was also made publicly available under the terms of an open source license. The second project was an informal survey of registrants with deployed LDAP servers. This was conducted by using the com, net, org, and edu zone files and testing for the existence of an LDAP server on port 389 using the name of the domain, a host named "ldap" in the domain, and a host named "dir" in the domain (e.g., "foo.com", "ldap.foo.com", and "dir.foo.com"). This survey did not attempt to resolve LDAP services using SRV records in DNS. The result of this survey found that roughly 0.5% of active domains had an LDAP server. By profiling a server's root DSA-specific Entry (DSE), the survey found that about 90% of the servers were implementations provided by vendor A, 9% of the servers were implementations provided by vendor B, and 1% of the servers were implementations provided by other vendors. Of the servers queried that were determined to be implementations provided by vendor A, it appeared that about only 10% contained public data (this also led to the assumption that the other 90% were not intended to be publicly queried). Of the servers queried that were determined to be implementations provided by vendor B, it appears that nearly all contained public data. Appendix B. Acknowledgments Significant analysis, design, and implementation for this project were conducted by Brad McMillen, David Blacka, Anna Zhang, and Michael Schiraldi. Mark Kosters and Leslie Daigle provided guidance by reviewing this project, the project's goals, and this document. Newton Experimental [Page 19] RFC 3663 Domain Administrative Data in LDAP December 2003 Author's Address Andrew Newton VeriSign, Inc. 21345 Ridgetop Circle Sterling, VA 20166 USA Phone: +1 703 948 3382 EMail: anewton@verisignlabs.com; anewton@ecotroph.net Newton Experimental [Page 20] RFC 3663 Domain Administrative Data in LDAP December 2003 Full Copyright Statement Copyright (C) The Internet Society (2003). 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 assignees. 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. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Newton Experimental [Page 21] PK &�c\�K�`�^ �^ ( doc/alt-openldap11-devel/rfc/rfc3876.txtnu �[��� Network Working Group D. Chadwick Request for Comments: 3876 University of Salford Category: Standards Track S. Mullan Sun Microsystems September 2004 Returning Matched Values with the Lightweight Directory Access Protocol version 3 (LDAPv3) Status of this Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2004). Abstract This document describes a control for the Lightweight Directory Access Protocol version 3 that is used to return a subset of attribute values from an entry. Specifically, only those values that match a "values return" filter. Without support for this control, a client must retrieve all of an attribute's values and search for specific values locally. 1. Introduction When reading an attribute from an entry using the Lightweight Directory Access Protocol version 3 (LDAPv3) [2], it is normally only possible to read either the attribute type, or the attribute type and all its values. It is not possible to selectively read just a few of the attribute values. If an attribute holds many values, for example, the userCertificate attribute, or the subschema publishing operational attributes objectClasses and attributeTypes [3], then it may be desirable for the user to be able to selectively retrieve a subset of the values, specifically, those attribute values that match some user defined selection criteria. Without the control specified in this document, a client must read all of the attribute's values and filter out the unwanted values, necessitating the client to implement the matching rules. It also requires the client to Chadwick & Mullan Standards Track [Page 1] RFC 3876 Returning Matched Values with LDAPv3 September 2004 potentially read and process many irrelevant values, which can be inefficient if the values are large or complex, or there are many values stored per attribute. This document specifies an LDAPv3 control to enable a user to return only those values that matched (i.e., returned TRUE to) one or more elements of a newly defined "values return" filter. This control can be especially useful when used in conjunction with extensible matching rules that match on one or more components of complex binary attribute values. 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. The valuesReturnFilter Control The valuesReturnFilter control is either critical or non-critical as determined by the user. It only has meaning for the Search operation, and SHOULD only be added to the Search operation by the client. If the server supports the control and it is present on a Search operation, the server MUST obey the control, regardless of the value of the criticality flag. If the control is marked as critical, and either the server does not support the control or the control is applied to an operation other than Search, the server MUST return an unavailableCriticalExtension error. If the control is not marked as critical, and either the server does not support the control or the control is applied to an operation other than Search, then the server MUST ignore the control. The object identifier for this control is 1.2.826.0.1.3344810.2.3. The controlValue is an OCTET STRING, whose value is the BER encoding [6], as per Section 5.1 of RFC 2251 [2], of a value of the ASN.1 [5] type ValuesReturnFilter. ValuesReturnFilter ::= SEQUENCE OF SimpleFilterItem SimpleFilterItem ::= CHOICE { equalityMatch [3] AttributeValueAssertion, substrings [4] SubstringFilter, greaterOrEqual [5] AttributeValueAssertion, lessOrEqual [6] AttributeValueAssertion, present [7] AttributeDescription, approxMatch [8] AttributeValueAssertion, extensibleMatch [9] SimpleMatchingAssertion } Chadwick & Mullan Standards Track [Page 2] RFC 3876 Returning Matched Values with LDAPv3 September 2004 SimpleMatchingAssertion ::= SEQUENCE { matchingRule [1] MatchingRuleId OPTIONAL, type [2] AttributeDescription OPTIONAL, --- at least one of the above must be present matchValue [3] AssertionValue} All the above data types have their standard meanings as defined in [2]. If the server supports this control, the server MUST make use of the control as follows: 1) The Search Filter is first executed in order to determine which entries satisfy the Search criteria (these are the filtered entries). The control has no impact on this step. 2) If the typesOnly parameter of the Search Request is TRUE, the control has no effect and the Search Request is processed as if the control had not been specified. 3) If the attributes parameter of the Search Request consists of a list containing only the attribute with OID "1.1" (specifying that no attributes are to be returned), the control has no effect and the Search Request is processed as if the control had not been specified. 4) For each attribute listed in the attributes parameter of the Search Request, the server MUST apply the control as follows to each entry in the set of filtered entries: i) Every attribute value that evaluates TRUE against one or more elements of the ValuesReturnFilter is placed in the corresponding SearchResultEntry. ii) Every attribute value that evaluates FALSE or undefined against all elements of the ValuesReturnFilter is not placed in the corresponding SearchResultEntry. An attribute that has no values selected is returned with an empty set of values. Note. If the AttributeDescriptionList (see [2]) is empty or comprises "*", then the control MUST be applied against every user attribute. If the AttributeDescriptionList contains a "+", then the control MUST be applied against every operational attribute. Chadwick & Mullan Standards Track [Page 3] RFC 3876 Returning Matched Values with LDAPv3 September 2004 3. Relationship to X.500 The control is a superset of the matchedValuesOnly (MVO) boolean of the X.500 Directory Access Protocol (DAP) [8] Search argument, as amended in the latest version [9]. Close examination of the matchedValuesOnly boolean by the LDAP Extensions (LDAPEXT) Working Group revealed ambiguities and complexities in the MVO boolean that could not easily be resolved. For example, it was not clear if the MVO boolean governed only those attribute values that contributed to the overall truth of the filter, or all of the attribute values, even if the filter item containing the attribute was evaluated as false. For this reason the LDAPEXT group decided to replace the MVO boolean with a simple filter that removes any uncertainty as to whether an attribute value has been selected or not. 4. Relationship to other LDAP Controls The purpose of this control is to select zero, one, or more attribute values from each requested attribute in a filtered entry, and to discard the remainder. Once the attribute values have been discarded by this control, they MUST NOT be re-instated into the Search results by other controls. This control acts independently of other LDAP controls such as server side sorting [13] and duplicate entries [10]. However, there might be interactions between this control and other controls so that a different set of Search Result Entries are returned, or the entries are returned in a different order, depending upon the sequencing of this control and other controls in the LDAP request. For example, with server side sorting, if sorting is done first, and value return filtering second, the set of Search Results may appear to be in the wrong order since the value filtering may remove the attribute values upon which the ordering was done. (The sorting document specifies that entries without any sort key attribute values should be treated as coming after all other attribute values.) Similarly with duplicate entries, if duplication is performed before value filtering, the set of Search Result Entries may contain identical duplicate entries, each with an empty set of attribute values, because the value filtering removed the attribute values that were used to duplicate the results. For these reasons, the ValuesReturnFilter control in a SearchRequest SHOULD precede other controls that affect the number and ordering of SearchResultEntrys. Chadwick & Mullan Standards Track [Page 4] RFC 3876 Returning Matched Values with LDAPv3 September 2004 5. Examples All entries are provided in an LDAP Data Interchange Format (LDIF)[11]. The string representation of the valuesReturnFilter in the examples below uses the following ABNF [15] notation: valuesReturnFilter = "(" 1*simpleFilterItem ")" simpleFilterItem = "(" item ")" where item is as defined below (adapted from RFC2254 [14]). item = simple / present / substring / extensible simple = attr filtertype value filtertype = equal / approx / greater / less equal = "=" approx = "~=" greater = ">=" less = "<=" extensible = attr [":" matchingrule] ":=" value / ":" matchingrule ":=" value present = attr "=*" substring = attr "=" [initial] any [final] initial = value any = "*" *(value "*") final = value attr = AttributeDescription from Section 4.1.5 of [1] matchingrule = MatchingRuleId from Section 4.1.9 of [1] value = AttributeValue from Section 4.1.6 of [1] 1) The first example shows how the control can be set to return all attribute values from one attribute type (e.g., telephoneNumber) and a subset of values from another attribute type (e.g., mail). The entries below represent organizationalPerson object classes located somewhere beneath the distinguished name dc=ac,dc=uk. dn: cn=Sean Mullan,ou=people,dc=sun,dc=ac,dc=uk cn: Sean Mullan sn: Mullan objectClass: organizationalPerson objectClass: person objectClass: inetOrgPerson mail: sean.mullan@hotmail.com mail: mullan@east.sun.com telephoneNumber: + 781 442 0926 telephoneNumber: 555-9999 Chadwick & Mullan Standards Track [Page 5] RFC 3876 Returning Matched Values with LDAPv3 September 2004 dn: cn=David Chadwick,ou=isi,o=salford,dc=ac,dc=uk cn: David Chadwick sn: Chadwick objectClass: organizationalPerson objectClass: person objectClass: inetOrgPerson mail: d.w.chadwick@salford.ac.uk An LDAP search operation is specified with a baseObject set to the DN of the search base (i.e., dc=ac,dc=uk), a subtree scope, a filter set to (sn=mullan), and the list of attributes to be returned set to "mail,telephoneNumber" or "*". In addition, a ValuesReturnFilter control is set to ((mail=*hotmail.com)(telephoneNumber=*)). The search results returned by the server would consist of the following entry: dn: cn=Sean Mullan,ou=people,dc=sun,dc=ac,dc=uk mail: sean.mullan@hotmail.com telephoneNumber: + 781 442 0926 telephoneNumber: 555-9999 Note that the control has no effect on the values returned for the "telephoneNumber" attribute (all of the values are returned), since the control specified that all values should be returned. 2) The second example shows how one might retrieve a single attribute type subschema definition for the "gunk" attribute with OID 1.2.3.4.5 from the subschema subentry. Assume the subschema subentry is held below the root entry with DN cn=subschema subentry,o=myorg and this holds an attributeTypes operational attribute holding the descriptions of the 35 attributes known to this server (each description is held as a single attribute value of the attributeTypes attribute). dn: cn=subschema subentry,o=myorg cn: subschema subentry objectClass: subschema attributeTypes: ( 2.5.4.3 NAME 'cn' SUP name ) attributeTypes: ( 2.5.4.6 NAME 'c' SUP name SINGLE-VALUE ) attributeTypes: ( 2.5.4.0 NAME 'objectClass' EQUALITY obj ectIdentifierMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 ) attributeTypes: ( 2.5.18.2 NAME 'modifyTimestamp' EQUALITY gen eralizedTimeMatch ORDERING generalizedTimeOrderingMatch SYN TAX 1.3.6.1.4.1.1466.115.121.1.24 SINGLE-VALUE NO-USER- MODIFICATION USAGE directoryOperation ) attributeTypes: ( 2.5.21.6 NAME 'objectClasses' EQUALITY obj Chadwick & Mullan Standards Track [Page 6] RFC 3876 Returning Matched Values with LDAPv3 September 2004 ectIdentifierFirstComponentMatch SYNTAX 1.3. 6.1.4.1.1466.115.121.1.37 USAGE directoryOperation ) attributeTypes: ( 1.2.3.4.5 NAME 'gunk' EQUALITY caseIgnoreMat ch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3. 6.1.4.1.1466.115.121.1.44{64} ) attributeTypes: ( 2.5.21.5 NAME 'attributeTypes' EQUALITY obj ectIdentifierFirstComponentMatch SYNTAX 1.3. 6.1.4.1.1466.115.121.1.3 USAGE directoryOperation ) plus another 28 - you get the idea. The user creates an LDAP search operation with a baseObject set to cn=subschema subentry,o=myorg, a scope of base, a filter set to (objectClass=subschema), the list of attributes to be returned set to "attributeTypes", and the ValuesReturnFilter set to ((attributeTypes=1.2.3.4.5)) The search result returned by the server would consist of the following entry: dn: cn=subschema subentry,o=myorg attributeTypes: ( 1.2.3.4.5 NAME 'gunk' EQUALITY caseIgnoreMat ch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3. 6.1.4.1.1466.115.121.1.44{64} ) 3) The final example shows how the control can be used to match on a userCertificate attribute value. Note that this example requires the LDAP server to support the certificateExactMatch matching rule defined in [12] as the EQUALITY matching rule for userCertificate. The entry below represents a pkiUser object class stored in the directory. dn: cn=David Chadwick,ou=people,o=University of Salford,c=gb cn: David Chadwick objectClass: person objectClass: organizationalPerson objectClass: pkiUser objectClass: inetOrgPerson sn: Chadwick mail: d.w.chadwick@salford.ac.uk userCertificate;binary: {binary representation of a certificate with a serial number of 2468 issued by o=truetrust ltd,c=gb} userCertificate;binary: {binary representation of certificate with a serial number of 1357 issued by o=truetrust ltd,c=gb} userCertificate;binary: {binary representation of certificate with a serial number of 1234 issued by dc=certsRus,dc=com} Chadwick & Mullan Standards Track [Page 7] RFC 3876 Returning Matched Values with LDAPv3 September 2004 An LDAP search operation is specified with a baseObject set to o=University of Salford,c=gb, a subtree scope, a filter set to (sn=chadwick), and the list of attributes to be returned set to "userCertificate;binary". In addition, a ValuesReturnFilter control is set to ((userCertificate=1357$o=truetrust ltd,c=gb)). The search result returned by the server would consist of the following entry: dn: cn=David Chadwick,ou=people,o=University of Salford,c=gb userCertificate;binary: {binary representation of certificate with a serial number of 1357 issued by o=truetrust ltd,c=gb} 6. Security Considerations This document does not primarily discuss security issues. Note however that attribute values MUST only be returned if the access controls applied by the LDAP server allow them to be returned, and in this respect the effect of the ValuesReturnFilter control is of no consequence. Note that the ValuesReturnFilter control may have a positive effect on the deployment of public key infrastructures. Certain PKI operations, like searching for specific certificates, become more scalable, and more practical when combined with X.509 certificate matching rules at the server, since the control avoids the downloading of potentially large numbers of irrelevant certificates which would have to be processed and filtered locally (which in some cases is very difficult to perform). 7. IANA Considerations The Matched Values control as an LDAP Protocol Mechanism [7] has been registered as follows: Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: 1.2.826.0.1.3344810.2.3 Description: Matched Values Control Person & email address to contact for further information: David Chadwick <d.w.chadwick@salford.ac.uk> Usage: Control Specification: RFC3876 Author/Change Controller: IESG Comments: none Chadwick & Mullan Standards Track [Page 8] RFC 3876 Returning Matched Values with LDAPv3 September 2004 This document uses the OID 1.2.826.0.1.3344810.2.3 to identify the matchedValues control described here. This OID was assigned by TrueTrust Ltd, under its BSI assigned English/Welsh Registered Company number [16]. 8. Acknowledgements The authors would like to thank members of the LDAPExt list for their constructive comments on earlier versions of this document, and in particular to Harald Alvestrand who first suggested having an attribute return filter and Bruce Greenblatt who first proposed a syntax for this control. 9. References 9.1. Normative References [1] Bradner, S., "The Internet Standards Process -- Revision 3", BCP 9, RFC 2026, October 1996. [2] Wahl, M., Howes, T., and S. Kille, "Lightweight Directory Access Protocol (w3)", RFC 2251, December 1997. [3] Wahl, M., Coulbeck, A., Howes, T., and S. Kille, "Lightweight Directory Access Protocol (v3): Attribute Syntax Definitions", RFC 2252, December 1997. [4] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [5] ITU-T Recommendation X.680 (1997) | ISO/IEC 8824-1:1998, Information Technology - Abstract Syntax Notation One (ASN.1): Specification of Basic Notation [6] ITU-T Recommendation X.690 (1997) | ISO/IEC 8825-1,2,3:1998 Information technology - ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER) [7] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 3383, September 2002. Chadwick & Mullan Standards Track [Page 9] RFC 3876 Returning Matched Values with LDAPv3 September 2004 9.2. Informative References [8] ITU-T Rec. X.511, "The Directory: Abstract Service Definition", 1993. [9] ISO/IEC 9594 / ITU-T Rec X.511 (2001) The Directory: Abstract Service Definition. [10] Sermersheim, J., "LDAP Control for a Duplicate Entry Representation of Search Results", Work in Progress, October 2000. [11] Good, G., "The LDAP Data Interchange Format (LDIF) - Technical Specification", RFC 2849, June 2000. [12] Chadwick, D. and S.Legg, "Internet X.509 Public Key Infrastructure - Additional LDAP Schema for PKIs", Work in Progress, June 2002 [13] Howes, T., Wahl, M., and A. Anantha, "LDAP Control Extension for Server Side Sorting of Search Results", RFC 2891, August 2000. [14] Howes, T., "The String Representation of LDAP Search Filters", RFC 2254, December 1997. [15] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, November 1997. [16] BRITISH STANDARD BS 7453 Part 1. Procedures for UK Registration for Open System Standards Part 1: Procedures for the UK Name Registration Authority. Chadwick & Mullan Standards Track [Page 10] RFC 3876 Returning Matched Values with LDAPv3 September 2004 10. Authors' Addresses David Chadwick IS Institute University of Salford Salford M5 4WT England Phone: +44 161 295 5351 EMail: d.w.chadwick@salford.ac.uk Sean Mullan Sun Microsystems One Network Drive Burlington, MA 01803 USA EMail: sean.mullan@sun.com Chadwick & Mullan Standards Track [Page 11] RFC 3876 Returning Matched Values with LDAPv3 September 2004 11. Full Copyright Statement Copyright (C) The Internet Society (2004). 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/S HE 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 IETF's procedures with respect to rights in IETF 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@ietf.org. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Chadwick & Mullan Standards Track [Page 12] PK &�c\1�y6�� �� ( doc/alt-openldap11-devel/rfc/rfc2798.txtnu �[��� Network Working Group M. Smith Request for Comments: 2798 Netscape Communications Category: Informational April 2000 Definition of the inetOrgPerson LDAP Object Class Status of this Memo This memo provides information for the Internet community. It does not specify an Internet standard of any kind. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2000). All Rights Reserved. Abstract While the X.500 standards define many useful attribute types [X520] and object classes [X521], they do not define a person object class that meets the requirements found in today's Internet and Intranet directory service deployments. We define a new object class called inetOrgPerson for use in LDAP and X.500 directory services that extends the X.521 standard organizationalPerson class to meet these needs. Smith Informational [Page 1] RFC 2798 The LDAP inetOrgPerson Object Class April 2000 Table of Contents 1. Background and Intended Usage...............................2 2. New Attribute Types Used in the inetOrgPerson Object Class..3 2.1. Vehicle license or registration plate....................3 2.2. Department number........................................3 2.3. Display Name.............................................4 2.4. Employee Number..........................................4 2.5. Employee Type............................................4 2.6. JPEG Photograph..........................................5 2.7. Preferred Language.......................................5 2.8. User S/MIME Certificate..................................5 2.9. User PKCS #12............................................6 3. Definition of the inetOrgPerson Object Class................6 4. Example of an inetOrgPerson Entry...........................7 5. Security Considerations.....................................8 6. Acknowledgments.............................................8 7. Bibliography................................................8 8. Author's Address............................................9 9. Appendix A - inetOrgPerson Schema Summary..................10 9.1. Attribute Types..........................................10 9.1.1. New attribute types that are defined in this document.10 9.1.2. Attribute types from RFC 2256.........................12 9.1.3. Attribute types from RFC 1274.........................15 9.1.4. Attribute type from RFC 2079..........................16 9.2. Syntaxes.................................................17 9.2.1. Syntaxes from RFC 2252................................17 9.2.2. Syntaxes from RFC 2256................................17 9.3. Matching Rules...........................................17 9.3.1. Matching rules from RFC 2252..........................17 9.3.2. Matching rule from RFC 2256...........................18 9.3.3. Additional matching rules from X.520..................18 9.3.4. Matching rules not defined in any referenced document.19 10. Full Copyright Statement...................................20 1. Background and Intended Usage The inetOrgPerson object class is a general purpose object class that holds attributes about people. The attributes it holds were chosen to accommodate information requirements found in typical Internet and Intranet directory service deployments. The inetOrgPerson object class is designed to be used within directory services based on the LDAP [RFC2251] and the X.500 family of protocols, and it should be useful in other contexts as well. There is no requirement for directory services implementors to use the inetOrgPerson object class; it is simply presented as well-documented class that implementors can choose to use if they find it useful. Smith Informational [Page 2] RFC 2798 The LDAP inetOrgPerson Object Class April 2000 The attribute type and object class definitions in this document are written using the BNF form of AttributeTypeDescription and ObjectClassDescription given in [RFC2252]. In some cases lines have been folded for readability. Attributes that are referenced but not defined in this document are included in one of the following documents: The COSINE and Internet X.500 Schema [RFC1274] Definition of an X.500 Attribute Type and an Object Class to Hold Uniform Resource Identifiers (URIs) [RFC2079] A Summary of the X.500(96) User Schema for use with LDAPv3 [RFC2256] See Appendix A for a summary of the attribute types, associated syntaxes, and matching rules used in this document. 2. New Attribute Types Used in the inetOrgPerson Object Class 2.1. Vehicle license or registration plate. This multivalued field is used to record the values of the license or registration plate associated with an individual. ( 2.16.840.1.113730.3.1.1 NAME 'carLicense' DESC 'vehicle license or registration plate' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) 2.2. Department number Code for department to which a person belongs. This can also be strictly numeric (e.g., 1234) or alphanumeric (e.g., ABC/123). ( 2.16.840.1.113730.3.1.2 NAME 'departmentNumber' DESC 'identifies a department within an organization' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) Smith Informational [Page 3] RFC 2798 The LDAP inetOrgPerson Object Class April 2000 2.3. Display Name When displaying an entry, especially within a one-line summary list, it is useful to be able to identify a name to be used. Since other attribute types such as 'cn' are multivalued, an additional attribute type is needed. Display name is defined for this purpose. ( 2.16.840.1.113730.3.1.241 NAME 'displayName' DESC 'preferred name of a person to be used when displaying entries' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) 2.4. Employee Number Numeric or alphanumeric identifier assigned to a person, typically based on order of hire or association with an organization. Single valued. ( 2.16.840.1.113730.3.1.3 NAME 'employeeNumber' DESC 'numerically identifies an employee within an organization' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) 2.5. Employee Type Used to identify the employer to employee relationship. Typical values used will be "Contractor", "Employee", "Intern", "Temp", "External", and "Unknown" but any value may be used. ( 2.16.840.1.113730.3.1.4 NAME 'employeeType' DESC 'type of employment for a person' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) Smith Informational [Page 4] RFC 2798 The LDAP inetOrgPerson Object Class April 2000 2.6. JPEG Photograph Used to store one or more images of a person using the JPEG File Interchange Format [JFIF]. ( 0.9.2342.19200300.100.1.60 NAME 'jpegPhoto' DESC 'a JPEG image' SYNTAX 1.3.6.1.4.1.1466.115.121.1.28 ) Note that the jpegPhoto attribute type was defined for use in the Internet X.500 pilots but no referencable definition for it could be located. 2.7. Preferred Language Used to indicate an individual's preferred written or spoken language. This is useful for international correspondence or human- computer interaction. Values for this attribute type MUST conform to the definition of the Accept-Language header field defined in [RFC2068] with one exception: the sequence "Accept-Language" ":" should be omitted. This is a single valued attribute type. ( 2.16.840.1.113730.3.1.39 NAME 'preferredLanguage' DESC 'preferred written or spoken language for a person' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) ) 2.8. User S/MIME Certificate A PKCS#7 [RFC2315] SignedData, where the content that is signed is ignored by consumers of userSMIMECertificate values. It is recommended that values have a `contentType' of data with an absent `content' field. Values of this attribute contain a person's entire certificate chain and an smimeCapabilities field [RFC2633] that at a minimum describes their SMIME algorithm capabilities. Values for this attribute are to be stored and requested in binary form, as 'userSMIMECertificate;binary'. If available, this attribute is preferred over the userCertificate attribute for S/MIME applications. ( 2.16.840.1.113730.3.1.40 NAME 'userSMIMECertificate' DESC 'PKCS#7 SignedData used to support S/MIME' SYNTAX 1.3.6.1.4.1.1466.115.121.1.5 ) Smith Informational [Page 5] RFC 2798 The LDAP inetOrgPerson Object Class April 2000 2.9. User PKCS #12 PKCS #12 [PKCS12] provides a format for exchange of personal identity information. When such information is stored in a directory service, the userPKCS12 attribute should be used. This attribute is to be stored and requested in binary form, as 'userPKCS12;binary'. The attribute values are PFX PDUs stored as binary data. ( 2.16.840.1.113730.3.1.216 NAME 'userPKCS12' DESC 'PKCS #12 PFX PDU for exchange of personal identity information' SYNTAX 1.3.6.1.4.1.1466.115.121.1.5 ) 3. Definition of the inetOrgPerson Object Class The inetOrgPerson represents people who are associated with an organization in some way. It is a structural class and is derived from the organizationalPerson class which is defined in X.521 [X521]. ( 2.16.840.1.113730.3.2.2 NAME 'inetOrgPerson' SUP organizationalPerson STRUCTURAL MAY ( audio $ businessCategory $ carLicense $ departmentNumber $ displayName $ employeeNumber $ employeeType $ givenName $ homePhone $ homePostalAddress $ initials $ jpegPhoto $ labeledURI $ mail $ manager $ mobile $ o $ pager $ photo $ roomNumber $ secretary $ uid $ userCertificate $ x500uniqueIdentifier $ preferredLanguage $ userSMIMECertificate $ userPKCS12 ) ) For reference, we list the following additional attribute types that are part of the inetOrgPerson object class. These attribute types are inherited from organizationalPerson (which in turn is derived from the person object class): Smith Informational [Page 6] RFC 2798 The LDAP inetOrgPerson Object Class April 2000 MUST ( cn $ objectClass $ sn ) MAY ( description $ destinationIndicator $ facsimileTelephoneNumber $ internationaliSDNNumber $ l $ ou $ physicalDeliveryOfficeName $ postalAddress $ postalCode $ postOfficeBox $ preferredDeliveryMethod $ registeredAddress $ seeAlso $ st $ street $ telephoneNumber $ teletexTerminalIdentifier $ telexNumber $ title $ userPassword $ x121Address ) 4. Example of an inetOrgPerson Entry The following example is expressed using the LDIF notation defined in [LDIF]. version: 1 dn: cn=Barbara Jensen,ou=Product Development,dc=siroe,dc=com objectClass: top objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson cn: Barbara Jensen cn: Babs Jensen displayName: Babs Jensen sn: Jensen givenName: Barbara initials: BJJ title: manager, product development uid: bjensen mail: bjensen@siroe.com telephoneNumber: +1 408 555 1862 facsimileTelephoneNumber: +1 408 555 1992 mobile: +1 408 555 1941 roomNumber: 0209 carLicense: 6ABC246 o: Siroe ou: Product Development departmentNumber: 2604 employeeNumber: 42 employeeType: full time preferredLanguage: fr, en-gb;q=0.8, en;q=0.7 labeledURI: http://www.siroe.com/users/bjensen My Home Page Smith Informational [Page 7] RFC 2798 The LDAP inetOrgPerson Object Class April 2000 5. Security Considerations Attributes of directory entries are used to provide descriptive information about the real-world objects they represent, which can be people, organizations or devices. Most countries have privacy laws regarding the publication of information about people. Transfer of cleartext passwords are strongly discouraged where the underlying transport service cannot guarantee confidentiality and may result in disclosure of the password to unauthorized parties. 6. Acknowledgments The Netscape Directory Server team created the inetOrgPerson object class based on experience and customer requirements. Anil Bhavnani and John Kristian in particular deserve credit for all of the early design work. Many members of the Internet community, in particular those in the IETF ASID and LDAPEXT groups, also contributed to the design of this object class. 7. Bibliography [JFIF] E. Hamilton, "JPEG File Interchange Format (Version 1.02)", C-Cube Microsystems, Milpitas, CA, September 1, 1992. [LDIF] G. Good, "The LDAP Data Interchange Format (LDIF) - Technical Specification", Work in Progress. [PKCS12] "PKCS #12: Personal Information Exchange Standard", Version 1.0 Draft, 30 April 1997. [RFC1274] Barker, P. and S. Kille, "The COSINE and Internet X.500 Schema", RFC 1274, November 1991. [RFC1847] Galvin, J., Murphy, S., Crocker, S. and N. Freed, "Security Multiparts for MIME: Multipart/Signed and Multipart/Encrypted", RFC 1847, October 1995. [RFC2068] Fielding, R., Gettys, J., Mogul, J., Frystyk, H. and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2068, January 1997. [RFC2079] Smith, M., "Definition of an X.500 Attribute Type and an Object Class to Hold Uniform Resource Identifiers (URIs)", RFC 2079, January 1997. Smith Informational [Page 8] RFC 2798 The LDAP inetOrgPerson Object Class April 2000 [RFC2251] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [RFC2252] Wahl, M., Coulbeck, A., Howes, T., Kille, S., Yeong, W. and C. Robbins, "Lightweight Directory Access Protocol (v3): Attribute Syntax Definitions", RFC 2252, December 1997. [RFC2256] Wahl, M., "A Summary of the X.500(96) User Schema for use with LDAPv3", RFC 2256, December 1997. [RFC2315] Kaliski, B., "PKCS #7: Cryptographic Message Syntax Version 1.5", RFC 2315, March 1998. [RFC2633] Ramsdell, B., "S/MIME Version 3 Message Specification", RFC 2633, June 1999. [X520] ITU-T Rec. X.520, "The Directory: Selected Attribute Types", 1996. [X521] ITU-T Rec. X.521, "The Directory: Selected Object Classes", 1996. 8. Author's Address Mark Smith Netscape Communications Corp. 501 E. Middlefield Rd., Mailstop MV068 Mountain View, CA 94043, USA Phone: +1 650 937-3477 EMail: mcs@netscape.com Smith Informational [Page 9] RFC 2798 The LDAP inetOrgPerson Object Class April 2000 9. Appendix A - inetOrgPerson Schema Summary This appendix provides definitions of all the attribute types included in the inetOrgPerson object class along with their associated syntaxes and matching rules. 9.1. Attribute Types 9.1.1. New attribute types that are defined in this document ( 2.16.840.1.113730.3.1.1 NAME 'carLicense' DESC 'vehicle license or registration plate' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) ( 2.16.840.1.113730.3.1.2 NAME 'departmentNumber' DESC 'identifies a department within an organization' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) ( 2.16.840.1.113730.3.1.241 NAME 'displayName' DESC 'preferred name of a person to be used when displaying entries' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) ( 2.16.840.1.113730.3.1.3 NAME 'employeeNumber' DESC 'numerically identifies an employee within an organization' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) ( 2.16.840.1.113730.3.1.4 NAME 'employeeType' DESC 'type of employment for a person' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) Smith Informational [Page 10] RFC 2798 The LDAP inetOrgPerson Object Class April 2000 ( 0.9.2342.19200300.100.1.60 NAME 'jpegPhoto' DESC 'a JPEG image' SYNTAX 1.3.6.1.4.1.1466.115.121.1.28 ) Note: The jpegPhoto attribute type was defined for use in the Internet X.500 pilots but no referencable definition for it could be located. ( 2.16.840.1.113730.3.1.39 NAME 'preferredLanguage' DESC 'preferred written or spoken language for a person' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) ( 2.16.840.1.113730.3.1.40 NAME 'userSMIMECertificate' DESC 'signed message used to support S/MIME' SYNTAX 1.3.6.1.4.1.1466.115.121.1.5 ) ( 2.16.840.1.113730.3.1.216 NAME 'userPKCS12' DESC 'PKCS #12 PFX PDU for exchange of personal identity information' SYNTAX 1.3.6.1.4.1.1466.115.121.1.5 ) 9.1.2. Attribute types from RFC 2256 Note that the original definitions of these types can be found in X.520. ( 2.5.4.15 NAME 'businessCategory' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{128} ) ( 2.5.4.3 NAME 'cn' SUP name ) ( 2.5.4.13 NAME 'description' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{1024} ) Smith Informational [Page 11] RFC 2798 The LDAP inetOrgPerson Object Class April 2000 ( 2.5.4.27 NAME 'destinationIndicator' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.44{128} ) ( 2.5.4.23 NAME 'facsimileTelephoneNumber' SYNTAX 1.3.6.1.4.1.1466.115.121.1.22 ) ( 2.5.4.42 NAME 'givenName' SUP name ) ( 2.5.4.43 NAME 'initials' SUP name ) ( 2.5.4.25 NAME 'internationaliSDNNumber' EQUALITY numericStringMatch SUBSTR numericStringSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.36{16} ) ( 2.5.4.7 NAME 'l' SUP name ) ( 2.5.4.0 NAME 'objectClass' EQUALITY objectIdentifierMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 ) ( 2.5.4.10 NAME 'o' SUP name ) ( 2.5.4.11 NAME 'ou' SUP name ) ( 2.5.4.19 NAME 'physicalDeliveryOfficeName' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{128} ) Smith Informational [Page 12] RFC 2798 The LDAP inetOrgPerson Object Class April 2000 ( 2.5.4.18 NAME 'postOfficeBox' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{40} ) ( 2.5.4.16 NAME 'postalAddress' EQUALITY caseIgnoreListMatch SUBSTR caseIgnoreListSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.41 ) ( 2.5.4.17 NAME 'postalCode' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{40} ) ( 2.5.4.28 NAME 'preferredDeliveryMethod' SYNTAX 1.3.6.1.4.1.1466.115.121.1.14 SINGLE-VALUE ) ( 2.5.4.26 NAME 'registeredAddress' SUP postalAddress SYNTAX 1.3.6.1.4.1.1466.115.121.1.41 ) ( 2.5.4.34 NAME 'seeAlso' SUP distinguishedName ) ( 2.5.4.4 NAME 'sn' SUP name ) ( 2.5.4.8 NAME 'st' SUP name ) ( 2.5.4.9 NAME 'street' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{128} ) Smith Informational [Page 13] RFC 2798 The LDAP inetOrgPerson Object Class April 2000 ( 2.5.4.20 NAME 'telephoneNumber' EQUALITY telephoneNumberMatch SUBSTR telephoneNumberSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.50{32} ) ( 2.5.4.22 NAME 'teletexTerminalIdentifier' SYNTAX 1.3.6.1.4.1.1466.115.121.1.51 ) ( 2.5.4.21 NAME 'telexNumber' SYNTAX 1.3.6.1.4.1.1466.115.121.1.52 ) ( 2.5.4.12 NAME 'title' SUP name ) ( 2.5.4.36 NAME 'userCertificate' SYNTAX 1.3.6.1.4.1.1466.115.121.1.8 ) ( 2.5.4.35 NAME 'userPassword' EQUALITY octetStringMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.40{128} ) ( 2.5.4.24 NAME 'x121Address' EQUALITY numericStringMatch SUBSTR numericStringSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.36{15} ) ( 2.5.4.45 NAME 'x500UniqueIdentifier' EQUALITY bitStringMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.6 ) Some attribute types included in inetOrgPerson are derived from the 'name' and 'distinguishedName' attribute supertypes: ( 2.5.4.41 NAME 'name' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{32768} ) Smith Informational [Page 14] RFC 2798 The LDAP inetOrgPerson Object Class April 2000 ( 2.5.4.49 NAME 'distinguishedName' EQUALITY distinguishedNameMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 ) 9.1.3. Attribute types from RFC 1274 ( 0.9.2342.19200300.100.1.55 NAME 'audio' EQUALITY octetStringMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.40{250000} ) Note: The syntax used here for the audio attribute type is Octet String. RFC 1274 uses a syntax called audio which is not defined in RFC 1274. ( 0.9.2342.19200300.100.1.20 NAME 'homePhone' EQUALITY telephoneNumberMatch SUBSTR telephoneNumberSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.50 ) Note: RFC 1274 uses the longer name 'homeTelephoneNumber'. ( 0.9.2342.19200300.100.1.39 NAME 'homePostalAddress' EQUALITY caseIgnoreListMatch SUBSTR caseIgnoreListSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.41 ) ( 0.9.2342.19200300.100.1.3 NAME 'mail' EQUALITY caseIgnoreIA5Match SUBSTR caseIgnoreIA5SubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.26{256} ) Note: RFC 1274 uses the longer name 'rfc822Mailbox' and syntax OID of 0.9.2342.19200300.100.3.5. All recent LDAP documents and most deployed LDAP implementations refer to this attribute as 'mail' and define the IA5 String syntax using using the OID 1.3.6.1.4.1.1466.115.121.1.26, as is done here. ( 0.9.2342.19200300.100.1.10 NAME 'manager' EQUALITY distinguishedNameMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 ) Smith Informational [Page 15] RFC 2798 The LDAP inetOrgPerson Object Class April 2000 ( 0.9.2342.19200300.100.1.41 NAME 'mobile' EQUALITY telephoneNumberMatch SUBSTR telephoneNumberSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.50 ) Note: RFC 1274 uses the longer name 'mobileTelephoneNumber'. ( 0.9.2342.19200300.100.1.42 NAME 'pager' EQUALITY telephoneNumberMatch SUBSTR telephoneNumberSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.50 ) Note: RFC 1274 uses the longer name 'pagerTelephoneNumber'. ( 0.9.2342.19200300.100.1.7 NAME 'photo' ) Note: Photo attribute values are encoded in G3 fax format with an ASN.1 wrapper. Please refer to RFC 1274 section 9.3.7 for detailed syntax information for this attribute. ( 0.9.2342.19200300.100.1.6 NAME 'roomNumber' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{256} ) ( 0.9.2342.19200300.100.1.21 NAME 'secretary' EQUALITY distinguishedNameMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 ) ( 0.9.2342.19200300.100.1.1 NAME 'uid' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{256} ) Note: RFC 1274 uses the longer name 'userid'. 9.1.4. Attribute type from RFC 2079 ( 1.3.6.1.4.1.250.1.57 NAME 'labeledURI' EQUALITY caseExactMatch SUBSTR caseExactSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) Smith Informational [Page 16] RFC 2798 The LDAP inetOrgPerson Object Class April 2000 9.2. Syntaxes 9.2.1. Syntaxes from RFC 2252 ( 1.3.6.1.4.1.1466.115.121.1.5 DESC 'Binary' ) ( 1.3.6.1.4.1.1466.115.121.1.6 DESC 'Bit String' ) ( 1.3.6.1.4.1.1466.115.121.1.8 DESC 'Certificate' ) ( 1.3.6.1.4.1.1466.115.121.1.12 DESC 'DN' ) ( 1.3.6.1.4.1.1466.115.121.1.15 DESC 'Directory String' ) ( 1.3.6.1.4.1.1466.115.121.1.22 DESC 'Facsimile Telephone Number' ) ( 1.3.6.1.4.1.1466.115.121.1.26 DESC 'IA5 String' ) ( 1.3.6.1.4.1.1466.115.121.1.28 DESC 'JPEG' ) ( 1.3.6.1.4.1.1466.115.121.1.36 DESC 'Numeric String' ) ( 1.3.6.1.4.1.1466.115.121.1.38 DESC 'OID' ) ( 1.3.6.1.4.1.1466.115.121.1.41 DESC 'Postal Address' ) ( 1.3.6.1.4.1.1466.115.121.1.44 DESC 'Printable String' ) ( 1.3.6.1.4.1.1466.115.121.1.50 DESC 'Telephone Number' ) 9.2.2. Syntaxes from RFC 2256 ( 1.3.6.1.4.1.1466.115.121.1.14 DESC 'Delivery Method' ) ( 1.3.6.1.4.1.1466.115.121.1.40 DESC 'Octet String' ) ( 1.3.6.1.4.1.1466.115.121.1.51 DESC 'Teletex Terminal Identifier' ) ( 1.3.6.1.4.1.1466.115.121.1.52 DESC 'Telex Number' ) 9.3. Matching Rules 9.3.1. Matching rules from RFC 2252 Note that the original definition of many of these matching rules can be found in X.520. Smith Informational [Page 17] RFC 2798 The LDAP inetOrgPerson Object Class April 2000 ( 2.5.13.16 NAME 'bitStringMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.6 ) ( 1.3.6.1.4.1.1466.109.114.2 NAME 'caseIgnoreIA5Match' SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) ( 2.5.13.11 NAME 'caseIgnoreListMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.41 ) ( 2.5.13.2 NAME 'caseIgnoreMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) ( 2.5.13.1 NAME 'distinguishedNameMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 ) ( 2.5.13.8 NAME 'numericStringMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.36 ) ( 2.5.13.0 NAME 'objectIdentifierMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 ) ( 2.5.13.20 NAME 'telephoneNumberMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.50 ) 9.3.2. Matching rule from RFC 2256 Note that the original definition of this matching rule can be found in X.520. ( 2.5.13.17 NAME 'octetStringMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.40 ) 9.3.3. Additional matching rules from X.520 caseExactMatch ( 2.5.13.5 NAME 'caseExactMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) This rule determines whether a presented string exactly matches an attribute value of syntax DirectoryString. It is identical to caseIgnoreMatch except that case is not ignored. Multiple adjoining whitespace characters are treated the same as an individual space, and leading and trailing whitespace is ignored. Smith Informational [Page 18] RFC 2798 The LDAP inetOrgPerson Object Class April 2000 caseExactSubstringsMatch ( 2.5.13.7 NAME 'caseExactSubstringsMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.58 ) This rules determines whether the initial, any and final substring elements in a presented value are present in an attribute value of syntax DirectoryString. It is identical to caseIgnoreSubstringsMatch except that case is not ignored. caseIgnoreListSubstringsMatch ( 2.5.13.12 NAME 'caseIgnoreListSubstringsMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.58 ) This rule compares a presented substring with an attribute value which is a sequence of DirectoryStrings, but where the case of letters is not significant for comparison purposes. A presented value matches a stored value if and only if the presented value matches the string formed by concatenating the strings of the stored value. Matching is done according to the caseIgnoreSubstringsMatch rule except that none of the initial, final, or any values of the presented value match a substring of the concatenated string which spans more than one of the strings of the stored value. 9.3.4. Matching rules not defined in any referenced document caseIgnoreIA5SubstringsMatch ( 1.3.6.1.4.1.1466.109.114.3 NAME 'caseIgnoreIA5SubstringsMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.58 ) This rules determines whether the initial, any and final substring elements in a presented value are present in an attribute value of syntax IA5 String without regard to the case of the letters in the strings. It is expected that this matching rule will be added to an update of RFC 2252. Smith Informational [Page 19] RFC 2798 The LDAP inetOrgPerson Object Class April 2000 10. 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. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Smith Informational [Page 20] PK '�c\bP+�? �? ( doc/alt-openldap11-devel/rfc/rfc4522.txtnu �[��� Network Working Group S. Legg Request for Comments: 4522 eB2Bcom Category: Standards Track June 2006 Lightweight Directory Access Protocol (LDAP): The Binary Encoding Option Status of This Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2006). Abstract Each attribute stored in a Lightweight Directory Access Protocol (LDAP) directory has a defined syntax (i.e., data type). A syntax definition specifies how attribute values conforming to the syntax are normally represented when transferred in LDAP operations. This representation is referred to as the LDAP-specific encoding to distinguish it from other methods of encoding attribute values. This document defines an attribute option, the binary option, that can be used to specify that the associated attribute values are instead encoded according to the Basic Encoding Rules (BER) used by X.500 directories. Table of Contents 1. Introduction ....................................................2 2. Conventions .....................................................2 3. The Binary Option ...............................................2 4. Syntaxes Requiring Binary Transfer ..............................3 5. Attributes Returned in a Search .................................4 6. All User Attributes .............................................4 7. Conflicting Requests ............................................5 8. Security Considerations .........................................5 9. IANA Considerations .............................................5 10. References .....................................................5 10.1. Normative References ......................................5 10.2. Informative References ....................................6 Legg Standards Track [Page 1] RFC 4522 LDAP: The Binary Encoding Option June 2006 1. Introduction Each attribute stored in a Lightweight Directory Access Protocol (LDAP) directory [RFC4510] has a defined syntax (i.e., data type) which constrains the structure and format of its values. The description of each syntax [RFC4517] specifies how attribute or assertion values [RFC4512] conforming to the syntax are normally represented when transferred in LDAP operations [RFC4511]. This representation is referred to as the LDAP-specific encoding to distinguish it from other methods of encoding attribute values. This document defines an attribute option, the binary option, which can be used in an attribute description [RFC4512] in an LDAP operation to specify that the associated attribute values or assertion values are, or are requested to be, encoded according to the Basic Encoding Rules (BER) [BER] as used by X.500 [X.500] directories, instead of the usual LDAP-specific encoding. The binary option was originally defined in RFC 2251 [RFC2251]. The LDAP technical specification [RFC4510] has obsoleted the previously defined LDAP technical specification [RFC3377], which included RFC 2251. The binary option was not included in the revised LDAP technical specification for a variety of reasons including implementation inconsistencies. No attempt is made here to resolve the known inconsistencies. This document reintroduces the binary option for use with certain attribute syntaxes, such as certificate syntax [RFC4523], that specifically require it. No attempt has been made to address use of the binary option with attributes of syntaxes that do not require its use. Unless addressed in a future specification, this use is to be avoided. 2. Conventions 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 [BCP14]. 3. The Binary Option The binary option is indicated with the attribute option string "binary" in an attribute description. Note that, like all attribute options, the string representing the binary option is case insensitive. Legg Standards Track [Page 2] RFC 4522 LDAP: The Binary Encoding Option June 2006 Where the binary option is present in an attribute description, the associated attribute values or assertion values MUST be BER encoded (otherwise the values are encoded according to the LDAP-specific encoding [RFC4517] for the attribute's syntax). Note that it is possible for a syntax to be defined such that its LDAP-specific encoding is exactly the same as its BER encoding. In terms of the protocol [RFC4511], the binary option specifies that the contents octets of the associated AttributeValue or AssertionValue OCTET STRING are a complete BER encoding of the relevant value. The binary option is not a tagging option [RFC4512], so the presence of the binary option does not specify an attribute subtype. An attribute description containing the binary option references exactly the same attribute as the attribute description without the binary option. The supertype/subtype relationships of attributes with tagging options are not altered in any way by the presence or absence of the binary option. An attribute description SHALL be treated as unrecognized if it contains the binary option and the syntax of the attribute does not have an associated ASN.1 type [RFC4517], or the BER encoding of values of that type is not supported. The presence or absence of the binary option only affects the transfer of attribute and assertion values in the protocol; servers store any particular attribute value in a format of their choosing. 4. Syntaxes Requiring Binary Transfer The attribute values of certain attribute syntaxes are defined without an LDAP-specific encoding and are required to be transferred in the BER-encoded form. For the purposes of this document, these syntaxes are said to have a binary transfer requirement. The certificate, certificate list, certificate pair, and supported algorithm syntaxes [RFC4523] are examples of syntaxes with a binary transfer requirement. These syntaxes also have an additional requirement that the exact BER encoding must be preserved. Note that this is a property of the syntaxes themselves, and not a property of the binary option. In the absence of this requirement, LDAP clients would need to re-encode values using the Distinguished Encoding Rules (DER). Legg Standards Track [Page 3] RFC 4522 LDAP: The Binary Encoding Option June 2006 5. Attributes Returned in a Search An LDAP search request [RFC4511] contains a list of the attributes (the requested attributes list) to be returned from each entry matching the search filter. An attribute description in the requested attributes list also implicitly requests all subtypes of the attribute type in the attribute description, whether through attribute subtyping or attribute tagging option subtyping [RFC4512]. The requested attributes list MAY contain attribute descriptions with the binary option, but MUST NOT contain two attribute descriptions with the same attribute type and the same tagging options (even if only one of them has the binary option). The binary option in an attribute description in the requested attributes list implicitly applies to all the subtypes of the attribute type in the attribute description (however, see Section 7). Attributes of a syntax with the binary transfer requirement, if returned, SHALL be returned in the binary form (i.e., with the binary option in the attribute description and the associated attribute values BER encoded) regardless of whether the binary option was present in the request (for the attribute or for one of its supertypes). Attributes of a syntax without the binary transfer requirement, if returned, SHOULD be returned in the form explicitly requested. That is, if the attribute description in the requested attributes list contains the binary option, then the corresponding attribute in the result SHOULD be in the binary form. If the attribute description in the request does not contain the binary option, then the corresponding attribute in the result SHOULD NOT be in the binary form. A server MAY omit an attribute from the result if it does not support the requested encoding. Regardless of the encoding chosen, a particular attribute value is returned at most once. 6. All User Attributes If the list of attributes in a search request is empty or contains the special attribute description string "*", then all user attributes are requested to be returned. Attributes of a syntax with the binary transfer requirement, if returned, SHALL be returned in the binary form. Legg Standards Track [Page 4] RFC 4522 LDAP: The Binary Encoding Option June 2006 Attributes of a syntax without the binary transfer requirement and having a defined LDAP-specific encoding SHOULD NOT be returned in the binary form. Attributes of a syntax without the binary transfer requirement and without a defined LDAP-specific encoding may be returned in the binary form or omitted from the result. 7. Conflicting Requests A particular attribute could be explicitly requested by an attribute description and/or implicitly requested by the attribute descriptions of one or more of its supertypes, or by the special attribute description string "*". If the binary option is present in at least one, but not all, of these attribute descriptions then the effect of the request with respect to binary transfer is implementation defined. 8. Security Considerations When interpreting security-sensitive fields, and in particular fields used to grant or deny access, implementations MUST ensure that any matching rule comparisons are done on the underlying abstract value, regardless of the particular encoding used. 9. IANA Considerations The Internet Assigned Numbers Authority (IANA) has updated the LDAP attribute description option registry [BCP64] as indicated by the following template: Subject: Request for LDAP Attribute Description Option Registration Option Name: binary Family of Options: NO Person & email address to contact for further information: Steven Legg <steven.legg@eb2bcom.com> Specification: RFC 4522 Author/Change Controller: IESG 10. References 10.1. Normative References [BCP14] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. Legg Standards Track [Page 5] RFC 4522 LDAP: The Binary Encoding Option June 2006 [BCP64] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006. [RFC4510] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC RFC 4510, June 2006. [RFC4511] Sermersheim, J., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006. [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006. [RFC4517] Legg, S., Ed., "Lightweight Directory Access Protocol (LDAP): Syntaxes and Matching Rules", RFC 4517, June 2006. [RFC4523] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP) Schema Definitions for X.509 Certificates", RFC 4523, June 2006. [BER] ITU-T Recommendation X.690 (07/02) | ISO/IEC 8825-1, Information Technology - ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER). 10.2. Informative References [RFC2251] Wahl, M., Howes, T., and S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [RFC3377] Hodges, J. and R. Morgan, "Lightweight Directory Access Protocol (v3): Technical Specification", RFC 3377, September 2002. [X.500] ITU-T Recommendation X.500 (02/01) | ISO/IEC 9594-1:2001, Information technology - Open Systems Interconnection - The Directory: Overview of concepts, models and services Legg Standards Track [Page 6] RFC 4522 LDAP: The Binary Encoding Option June 2006 Author's Address Dr. Steven Legg eB2Bcom Suite 3, Woodhouse Corporate Centre 935 Station Street Box Hill North, Victoria 3129 AUSTRALIA Phone: +61 3 9896 7830 Fax: +61 3 9896 7801 EMail: steven.legg@eb2bcom.com Legg Standards Track [Page 7] RFC 4522 LDAP: The Binary Encoding Option June 2006 Full Copyright Statement Copyright (C) The Internet Society (2006). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Legg Standards Track [Page 8] PK '�c\�H�dJ dJ ( doc/alt-openldap11-devel/rfc/rfc4511.txtnu �[��� Network Working Group J. Sermersheim, Ed. Request for Comments: 4511 Novell, Inc. Obsoletes: 2251, 2830, 3771 June 2006 Category: Standards Track Lightweight Directory Access Protocol (LDAP): The Protocol Status of This Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2006). Abstract This document describes the protocol elements, along with their semantics and encodings, of the Lightweight Directory Access Protocol (LDAP). LDAP provides access to distributed directory services that act in accordance with X.500 data and service models. These protocol elements are based on those described in the X.500 Directory Access Protocol (DAP). Table of Contents 1. Introduction ....................................................3 1.1. Relationship to Other LDAP Specifications ..................3 2. Conventions .....................................................3 3. Protocol Model ..................................................4 3.1. Operation and LDAP Message Layer Relationship ..............5 4. Elements of Protocol ............................................5 4.1. Common Elements ............................................5 4.1.1. Message Envelope ....................................6 4.1.2. String Types ........................................7 4.1.3. Distinguished Name and Relative Distinguished Name ..8 4.1.4. Attribute Descriptions ..............................8 4.1.5. Attribute Value .....................................8 4.1.6. Attribute Value Assertion ...........................9 4.1.7. Attribute and PartialAttribute ......................9 4.1.8. Matching Rule Identifier ...........................10 4.1.9. Result Message .....................................10 4.1.10. Referral ..........................................12 Sermersheim Standards Track [Page 1] RFC 4511 LDAPv3 June 2006 4.1.11. Controls ..........................................14 4.2. Bind Operation ............................................16 4.2.1. Processing of the Bind Request .....................17 4.2.2. Bind Response ......................................18 4.3. Unbind Operation ..........................................18 4.4. Unsolicited Notification ..................................19 4.4.1. Notice of Disconnection ............................19 4.5. Search Operation ..........................................20 4.5.1. Search Request .....................................20 4.5.2. Search Result ......................................27 4.5.3. Continuation References in the Search Result .......28 4.6. Modify Operation ..........................................31 4.7. Add Operation .............................................33 4.8. Delete Operation ..........................................34 4.9. Modify DN Operation .......................................34 4.10. Compare Operation ........................................36 4.11. Abandon Operation ........................................36 4.12. Extended Operation .......................................37 4.13. IntermediateResponse Message .............................39 4.13.1. Usage with LDAP ExtendedRequest and ExtendedResponse ..................................40 4.13.2. Usage with LDAP Request Controls ..................40 4.14. StartTLS Operation .......................................40 4.14.1. StartTLS Request ..................................40 4.14.2. StartTLS Response .................................41 4.14.3. Removal of the TLS Layer ..........................41 5. Protocol Encoding, Connection, and Transfer ....................42 5.1. Protocol Encoding .........................................42 5.2. Transmission Control Protocol (TCP) .......................43 5.3. Termination of the LDAP session ...........................43 6. Security Considerations ........................................43 7. Acknowledgements ...............................................45 8. Normative References ...........................................46 9. Informative References .........................................48 10. IANA Considerations ...........................................48 Appendix A. LDAP Result Codes .....................................49 A.1. Non-Error Result Codes ....................................49 A.2. Result Codes ..............................................49 Appendix B. Complete ASN.1 Definition .............................54 Appendix C. Changes ...............................................60 C.1. Changes Made to RFC 2251 ..................................60 C.2. Changes Made to RFC 2830 ..................................66 C.3. Changes Made to RFC 3771 ..................................66 Sermersheim Standards Track [Page 2] RFC 4511 LDAPv3 June 2006 1. Introduction The Directory is "a collection of open systems cooperating to provide directory services" [X.500]. A directory user, which may be a human or other entity, accesses the Directory through a client (or Directory User Agent (DUA)). The client, on behalf of the directory user, interacts with one or more servers (or Directory System Agents (DSA)). Clients interact with servers using a directory access protocol. This document details the protocol elements of the Lightweight Directory Access Protocol (LDAP), along with their semantics. Following the description of protocol elements, it describes the way in which the protocol elements are encoded and transferred. 1.1. Relationship to Other LDAP Specifications This document is an integral part of the LDAP Technical Specification [RFC4510], which obsoletes the previously defined LDAP technical specification, RFC 3377, in its entirety. This document, together with [RFC4510], [RFC4513], and [RFC4512], obsoletes RFC 2251 in its entirety. Section 3.3 is obsoleted by [RFC4510]. Sections 4.2.1 (portions) and 4.2.2 are obsoleted by [RFC4513]. Sections 3.2, 3.4, 4.1.3 (last paragraph), 4.1.4, 4.1.5, 4.1.5.1, 4.1.9 (last paragraph), 5.1, 6.1, and 6.2 (last paragraph) are obsoleted by [RFC4512]. The remainder of RFC 2251 is obsoleted by this document. Appendix C.1 summarizes substantive changes in the remainder. This document obsoletes RFC 2830, Sections 2 and 4. The remainder of RFC 2830 is obsoleted by [RFC4513]. Appendix C.2 summarizes substantive changes to the remaining sections. This document also obsoletes RFC 3771 in entirety. 2. Conventions 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 [RFC2119]. Character names in this document use the notation for code points and names from the Unicode Standard [Unicode]. For example, the letter "a" may be represented as either <U+0061> or <LATIN SMALL LETTER A>. Sermersheim Standards Track [Page 3] RFC 4511 LDAPv3 June 2006 Note: a glossary of terms used in Unicode can be found in [Glossary]. Information on the Unicode character encoding model can be found in [CharModel]. The term "transport connection" refers to the underlying transport services used to carry the protocol exchange, as well as associations established by these services. The term "TLS layer" refers to Transport Layer Security (TLS) services used in providing security services, as well as associations established by these services. The term "SASL layer" refers to Simply Authentication and Security Layer (SASL) services used in providing security services, as well as associations established by these services. The term "LDAP message layer" refers to the LDAP Message Protocol Data Unit (PDU) services used in providing directory services, as well as associations established by these services. The term "LDAP session" refers to combined services (transport connection, TLS layer, SASL layer, LDAP message layer) and their associations. See the table in Section 5 for an illustration of these four terms. 3. Protocol Model The general model adopted by this protocol is one of clients performing protocol operations against servers. In this model, a client transmits a protocol request describing the operation to be performed to a server. The server is then responsible for performing the necessary operation(s) in the Directory. Upon completion of an operation, the server typically returns a response containing appropriate data to the requesting client. Protocol operations are generally independent of one another. Each operation is processed as an atomic action, leaving the directory in a consistent state. Although servers are required to return responses whenever such responses are defined in the protocol, there is no requirement for synchronous behavior on the part of either clients or servers. Requests and responses for multiple operations generally may be exchanged between a client and server in any order. If required, synchronous behavior may be controlled by client applications. Sermersheim Standards Track [Page 4] RFC 4511 LDAPv3 June 2006 The core protocol operations defined in this document can be mapped to a subset of the X.500 (1993) Directory Abstract Service [X.511]. However, there is not a one-to-one mapping between LDAP operations and X.500 Directory Access Protocol (DAP) operations. Server implementations acting as a gateway to X.500 directories may need to make multiple DAP requests to service a single LDAP request. 3.1. Operation and LDAP Message Layer Relationship Protocol operations are exchanged at the LDAP message layer. When the transport connection is closed, any uncompleted operations at the LDAP message layer are abandoned (when possible) or are completed without transmission of the response (when abandoning them is not possible). Also, when the transport connection is closed, the client MUST NOT assume that any uncompleted update operations have succeeded or failed. 4. Elements of Protocol The protocol is described using Abstract Syntax Notation One ([ASN.1]) and is transferred using a subset of ASN.1 Basic Encoding Rules ([BER]). Section 5 specifies how the protocol elements are encoded and transferred. In order to support future extensions to this protocol, extensibility is implied where it is allowed per ASN.1 (i.e., sequence, set, choice, and enumerated types are extensible). In addition, ellipses (...) have been supplied in ASN.1 types that are explicitly extensible as discussed in [RFC4520]. Because of the implied extensibility, clients and servers MUST (unless otherwise specified) ignore trailing SEQUENCE components whose tags they do not recognize. Changes to the protocol other than through the extension mechanisms described here require a different version number. A client indicates the version it is using as part of the BindRequest, described in Section 4.2. If a client has not sent a Bind, the server MUST assume the client is using version 3 or later. Clients may attempt to determine the protocol versions a server supports by reading the 'supportedLDAPVersion' attribute from the root DSE (DSA-Specific Entry) [RFC4512]. 4.1. Common Elements This section describes the LDAPMessage envelope Protocol Data Unit (PDU) format, as well as data type definitions, which are used in the protocol operations. Sermersheim Standards Track [Page 5] RFC 4511 LDAPv3 June 2006 4.1.1. Message Envelope For the purposes of protocol exchanges, all protocol operations are encapsulated in a common envelope, the LDAPMessage, which is defined as follows: LDAPMessage ::= SEQUENCE { messageID MessageID, protocolOp CHOICE { bindRequest BindRequest, bindResponse BindResponse, unbindRequest UnbindRequest, searchRequest SearchRequest, searchResEntry SearchResultEntry, searchResDone SearchResultDone, searchResRef SearchResultReference, modifyRequest ModifyRequest, modifyResponse ModifyResponse, addRequest AddRequest, addResponse AddResponse, delRequest DelRequest, delResponse DelResponse, modDNRequest ModifyDNRequest, modDNResponse ModifyDNResponse, compareRequest CompareRequest, compareResponse CompareResponse, abandonRequest AbandonRequest, extendedReq ExtendedRequest, extendedResp ExtendedResponse, ..., intermediateResponse IntermediateResponse }, controls [0] Controls OPTIONAL } MessageID ::= INTEGER (0 .. maxInt) maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) -- The ASN.1 type Controls is defined in Section 4.1.11. The function of the LDAPMessage is to provide an envelope containing common fields required in all protocol exchanges. At this time, the only common fields are the messageID and the controls. If the server receives an LDAPMessage from the client in which the LDAPMessage SEQUENCE tag cannot be recognized, the messageID cannot be parsed, the tag of the protocolOp is not recognized as a request, or the encoding structures or lengths of data fields are found to be incorrect, then the server SHOULD return the Notice of Disconnection Sermersheim Standards Track [Page 6] RFC 4511 LDAPv3 June 2006 described in Section 4.4.1, with the resultCode set to protocolError, and MUST immediately terminate the LDAP session as described in Section 5.3. In other cases where the client or server cannot parse an LDAP PDU, it SHOULD abruptly terminate the LDAP session (Section 5.3) where further communication (including providing notice) would be pernicious. Otherwise, server implementations MUST return an appropriate response to the request, with the resultCode set to protocolError. 4.1.1.1. MessageID All LDAPMessage envelopes encapsulating responses contain the messageID value of the corresponding request LDAPMessage. The messageID of a request MUST have a non-zero value different from the messageID of any other request in progress in the same LDAP session. The zero value is reserved for the unsolicited notification message. Typical clients increment a counter for each request. A client MUST NOT send a request with the same messageID as an earlier request in the same LDAP session unless it can be determined that the server is no longer servicing the earlier request (e.g., after the final response is received, or a subsequent Bind completes). Otherwise, the behavior is undefined. For this purpose, note that Abandon and successfully abandoned operations do not send responses. 4.1.2. String Types The LDAPString is a notational convenience to indicate that, although strings of LDAPString type encode as ASN.1 OCTET STRING types, the [ISO10646] character set (a superset of [Unicode]) is used, encoded following the UTF-8 [RFC3629] algorithm. Note that Unicode characters U+0000 through U+007F are the same as ASCII 0 through 127, respectively, and have the same single octet UTF-8 encoding. Other Unicode characters have a multiple octet UTF-8 encoding. LDAPString ::= OCTET STRING -- UTF-8 encoded, -- [ISO10646] characters The LDAPOID is a notational convenience to indicate that the permitted value of this string is a (UTF-8 encoded) dotted-decimal representation of an OBJECT IDENTIFIER. Although an LDAPOID is Sermersheim Standards Track [Page 7] RFC 4511 LDAPv3 June 2006 encoded as an OCTET STRING, values are limited to the definition of <numericoid> given in Section 1.4 of [RFC4512]. LDAPOID ::= OCTET STRING -- Constrained to <numericoid> -- [RFC4512] For example, 1.3.6.1.4.1.1466.1.2.3 4.1.3. Distinguished Name and Relative Distinguished Name An LDAPDN is defined to be the representation of a Distinguished Name (DN) after encoding according to the specification in [RFC4514]. LDAPDN ::= LDAPString -- Constrained to <distinguishedName> [RFC4514] A RelativeLDAPDN is defined to be the representation of a Relative Distinguished Name (RDN) after encoding according to the specification in [RFC4514]. RelativeLDAPDN ::= LDAPString -- Constrained to <name-component> [RFC4514] 4.1.4. Attribute Descriptions The definition and encoding rules for attribute descriptions are defined in Section 2.5 of [RFC4512]. Briefly, an attribute description is an attribute type and zero or more options. AttributeDescription ::= LDAPString -- Constrained to <attributedescription> -- [RFC4512] 4.1.5. Attribute Value A field of type AttributeValue is an OCTET STRING containing an encoded attribute value. The attribute value is encoded according to the LDAP-specific encoding definition of its corresponding syntax. The LDAP-specific encoding definitions for different syntaxes and attribute types may be found in other documents and in particular [RFC4517]. AttributeValue ::= OCTET STRING Sermersheim Standards Track [Page 8] RFC 4511 LDAPv3 June 2006 Note that there is no defined limit on the size of this encoding; thus, protocol values may include multi-megabyte attribute values (e.g., photographs). Attribute values may be defined that have arbitrary and non-printable syntax. Implementations MUST NOT display or attempt to decode an attribute value if its syntax is not known. The implementation may attempt to discover the subschema of the source entry and to retrieve the descriptions of 'attributeTypes' from it [RFC4512]. Clients MUST only send attribute values in a request that are valid according to the syntax defined for the attributes. 4.1.6. Attribute Value Assertion The AttributeValueAssertion (AVA) type definition is similar to the one in the X.500 Directory standards. It contains an attribute description and a matching rule ([RFC4512], Section 4.1.3) assertion value suitable for that type. Elements of this type are typically used to assert that the value in assertionValue matches a value of an attribute. AttributeValueAssertion ::= SEQUENCE { attributeDesc AttributeDescription, assertionValue AssertionValue } AssertionValue ::= OCTET STRING The syntax of the AssertionValue depends on the context of the LDAP operation being performed. For example, the syntax of the EQUALITY matching rule for an attribute is used when performing a Compare operation. Often this is the same syntax used for values of the attribute type, but in some cases the assertion syntax differs from the value syntax. See objectIdentiferFirstComponentMatch in [RFC4517] for an example. 4.1.7. Attribute and PartialAttribute Attributes and partial attributes consist of an attribute description and attribute values. A PartialAttribute allows zero values, while Attribute requires at least one value. PartialAttribute ::= SEQUENCE { type AttributeDescription, vals SET OF value AttributeValue } Sermersheim Standards Track [Page 9] RFC 4511 LDAPv3 June 2006 Attribute ::= PartialAttribute(WITH COMPONENTS { ..., vals (SIZE(1..MAX))}) No two of the attribute values may be equivalent as described by Section 2.2 of [RFC4512]. The set of attribute values is unordered. Implementations MUST NOT rely upon the ordering being repeatable. 4.1.8. Matching Rule Identifier Matching rules are defined in Section 4.1.3 of [RFC4512]. A matching rule is identified in the protocol by the printable representation of either its <numericoid> or one of its short name descriptors [RFC4512], e.g., 'caseIgnoreMatch' or '2.5.13.2'. MatchingRuleId ::= LDAPString 4.1.9. Result Message The LDAPResult is the construct used in this protocol to return success or failure indications from servers to clients. To various requests, servers will return responses containing the elements found in LDAPResult to indicate the final status of the protocol operation request. LDAPResult ::= SEQUENCE { resultCode ENUMERATED { success (0), operationsError (1), protocolError (2), timeLimitExceeded (3), sizeLimitExceeded (4), compareFalse (5), compareTrue (6), authMethodNotSupported (7), strongerAuthRequired (8), -- 9 reserved -- referral (10), adminLimitExceeded (11), unavailableCriticalExtension (12), confidentialityRequired (13), saslBindInProgress (14), noSuchAttribute (16), undefinedAttributeType (17), inappropriateMatching (18), constraintViolation (19), attributeOrValueExists (20), invalidAttributeSyntax (21), Sermersheim Standards Track [Page 10] RFC 4511 LDAPv3 June 2006 -- 22-31 unused -- noSuchObject (32), aliasProblem (33), invalidDNSyntax (34), -- 35 reserved for undefined isLeaf -- aliasDereferencingProblem (36), -- 37-47 unused -- inappropriateAuthentication (48), invalidCredentials (49), insufficientAccessRights (50), busy (51), unavailable (52), unwillingToPerform (53), loopDetect (54), -- 55-63 unused -- namingViolation (64), objectClassViolation (65), notAllowedOnNonLeaf (66), notAllowedOnRDN (67), entryAlreadyExists (68), objectClassModsProhibited (69), -- 70 reserved for CLDAP -- affectsMultipleDSAs (71), -- 72-79 unused -- other (80), ... }, matchedDN LDAPDN, diagnosticMessage LDAPString, referral [3] Referral OPTIONAL } The resultCode enumeration is extensible as defined in Section 3.8 of [RFC4520]. The meanings of the listed result codes are given in Appendix A. If a server detects multiple errors for an operation, only one result code is returned. The server should return the result code that best indicates the nature of the error encountered. Servers may return substituted result codes to prevent unauthorized disclosures. The diagnosticMessage field of this construct may, at the server's option, be used to return a string containing a textual, human- readable diagnostic message (terminal control and page formatting characters should be avoided). As this diagnostic message is not standardized, implementations MUST NOT rely on the values returned. Diagnostic messages typically supplement the resultCode with additional information. If the server chooses not to return a textual diagnostic, the diagnosticMessage field MUST be empty. Sermersheim Standards Track [Page 11] RFC 4511 LDAPv3 June 2006 For certain result codes (typically, but not restricted to noSuchObject, aliasProblem, invalidDNSyntax, and aliasDereferencingProblem), the matchedDN field is set (subject to access controls) to the name of the last entry (object or alias) used in finding the target (or base) object. This will be a truncated form of the provided name or, if an alias was dereferenced while attempting to locate the entry, of the resulting name. Otherwise, the matchedDN field is empty. 4.1.10. Referral The referral result code indicates that the contacted server cannot or will not perform the operation and that one or more other servers may be able to. Reasons for this include: - The target entry of the request is not held locally, but the server has knowledge of its possible existence elsewhere. - The operation is restricted on this server -- perhaps due to a read-only copy of an entry to be modified. The referral field is present in an LDAPResult if the resultCode is set to referral, and it is absent with all other result codes. It contains one or more references to one or more servers or services that may be accessed via LDAP or other protocols. Referrals can be returned in response to any operation request (except Unbind and Abandon, which do not have responses). At least one URI MUST be present in the Referral. During a Search operation, after the baseObject is located, and entries are being evaluated, the referral is not returned. Instead, continuation references, described in Section 4.5.3, are returned when other servers would need to be contacted to complete the operation. Referral ::= SEQUENCE SIZE (1..MAX) OF uri URI URI ::= LDAPString -- limited to characters permitted in -- URIs If the client wishes to progress the operation, it contacts one of the supported services found in the referral. If multiple URIs are present, the client assumes that any supported URI may be used to progress the operation. Clients that follow referrals MUST ensure that they do not loop between servers. They MUST NOT repeatedly contact the same server for the same request with the same parameters. Some clients use a Sermersheim Standards Track [Page 12] RFC 4511 LDAPv3 June 2006 counter that is incremented each time referral handling occurs for an operation, and these kinds of clients MUST be able to handle at least ten nested referrals while progressing the operation. A URI for a server implementing LDAP and accessible via TCP/IP (v4 or v6) [RFC793][RFC791] is written as an LDAP URL according to [RFC4516]. Referral values that are LDAP URLs follow these rules: - If an alias was dereferenced, the <dn> part of the LDAP URL MUST be present, with the new target object name. - It is RECOMMENDED that the <dn> part be present to avoid ambiguity. - If the <dn> part is present, the client uses this name in its next request to progress the operation, and if it is not present the client uses the same name as in the original request. - Some servers (e.g., participating in distributed indexing) may provide a different filter in a URL of a referral for a Search operation. - If the <filter> part of the LDAP URL is present, the client uses this filter in its next request to progress this Search, and if it is not present the client uses the same filter as it used for that Search. - For Search, it is RECOMMENDED that the <scope> part be present to avoid ambiguity. - If the <scope> part is missing, the scope of the original Search is used by the client to progress the operation. - Other aspects of the new request may be the same as or different from the request that generated the referral. Other kinds of URIs may be returned. The syntax and semantics of such URIs is left to future specifications. Clients may ignore URIs that they do not support. UTF-8 encoded characters appearing in the string representation of a DN, search filter, or other fields of the referral value may not be legal for URIs (e.g., spaces) and MUST be escaped using the % method in [RFC3986]. Sermersheim Standards Track [Page 13] RFC 4511 LDAPv3 June 2006 4.1.11. Controls Controls provide a mechanism whereby the semantics and arguments of existing LDAP operations may be extended. One or more controls may be attached to a single LDAP message. A control only affects the semantics of the message it is attached to. Controls sent by clients are termed 'request controls', and those sent by servers are termed 'response controls'. Controls ::= SEQUENCE OF control Control Control ::= SEQUENCE { controlType LDAPOID, criticality BOOLEAN DEFAULT FALSE, controlValue OCTET STRING OPTIONAL } The controlType field is the dotted-decimal representation of an OBJECT IDENTIFIER that uniquely identifies the control. This provides unambiguous naming of controls. Often, response control(s) solicited by a request control share controlType values with the request control. The criticality field only has meaning in controls attached to request messages (except UnbindRequest). For controls attached to response messages and the UnbindRequest, the criticality field SHOULD be FALSE, and MUST be ignored by the receiving protocol peer. A value of TRUE indicates that it is unacceptable to perform the operation without applying the semantics of the control. Specifically, the criticality field is applied as follows: - If the server does not recognize the control type, determines that it is not appropriate for the operation, or is otherwise unwilling to perform the operation with the control, and if the criticality field is TRUE, the server MUST NOT perform the operation, and for operations that have a response message, it MUST return with the resultCode set to unavailableCriticalExtension. - If the server does not recognize the control type, determines that it is not appropriate for the operation, or is otherwise unwilling to perform the operation with the control, and if the criticality field is FALSE, the server MUST ignore the control. - Regardless of criticality, if a control is applied to an operation, it is applied consistently and impartially to the entire operation. Sermersheim Standards Track [Page 14] RFC 4511 LDAPv3 June 2006 The controlValue may contain information associated with the controlType. Its format is defined by the specification of the control. Implementations MUST be prepared to handle arbitrary contents of the controlValue octet string, including zero bytes. It is absent only if there is no value information that is associated with a control of its type. When a controlValue is defined in terms of ASN.1, and BER-encoded according to Section 5.1, it also follows the extensibility rules in Section 4. Servers list the controlType of request controls they recognize in the 'supportedControl' attribute in the root DSE (Section 5.1 of [RFC4512]). Controls SHOULD NOT be combined unless the semantics of the combination has been specified. The semantics of control combinations, if specified, are generally found in the control specification most recently published. When a combination of controls is encountered whose semantics are invalid, not specified (or not known), the message is considered not well-formed; thus, the operation fails with protocolError. Controls with a criticality of FALSE may be ignored in order to arrive at a valid combination. Additionally, unless order-dependent semantics are given in a specification, the order of a combination of controls in the SEQUENCE is ignored. Where the order is to be ignored but cannot be ignored by the server, the message is considered not well-formed, and the operation fails with protocolError. Again, controls with a criticality of FALSE may be ignored in order to arrive at a valid combination. This document does not specify any controls. Controls may be specified in other documents. Documents detailing control extensions are to provide for each control: - the OBJECT IDENTIFIER assigned to the control, - direction as to what value the sender should provide for the criticality field (note: the semantics of the criticality field are defined above should not be altered by the control's specification), - whether the controlValue field is present, and if so, the format of its contents, - the semantics of the control, and - optionally, semantics regarding the combination of the control with other controls. Sermersheim Standards Track [Page 15] RFC 4511 LDAPv3 June 2006 4.2. Bind Operation The function of the Bind operation is to allow authentication information to be exchanged between the client and server. The Bind operation should be thought of as the "authenticate" operation. Operational, authentication, and security-related semantics of this operation are given in [RFC4513]. The Bind request is defined as follows: BindRequest ::= [APPLICATION 0] SEQUENCE { version INTEGER (1 .. 127), name LDAPDN, authentication AuthenticationChoice } AuthenticationChoice ::= CHOICE { simple [0] OCTET STRING, -- 1 and 2 reserved sasl [3] SaslCredentials, ... } SaslCredentials ::= SEQUENCE { mechanism LDAPString, credentials OCTET STRING OPTIONAL } Fields of the BindRequest are: - version: A version number indicating the version of the protocol to be used at the LDAP message layer. This document describes version 3 of the protocol. There is no version negotiation. The client sets this field to the version it desires. If the server does not support the specified version, it MUST respond with a BindResponse where the resultCode is set to protocolError. - name: If not empty, the name of the Directory object that the client wishes to bind as. This field may take on a null value (a zero-length string) for the purposes of anonymous binds ([RFC4513], Section 5.1) or when using SASL [RFC4422] authentication ([RFC4513], Section 5.2). Where the server attempts to locate the named object, it SHALL NOT perform alias dereferencing. - authentication: Information used in authentication. This type is extensible as defined in Section 3.7 of [RFC4520]. Servers that do not support a choice supplied by a client return a BindResponse with the resultCode set to authMethodNotSupported. Sermersheim Standards Track [Page 16] RFC 4511 LDAPv3 June 2006 Textual passwords (consisting of a character sequence with a known character set and encoding) transferred to the server using the simple AuthenticationChoice SHALL be transferred as UTF-8 [RFC3629] encoded [Unicode]. Prior to transfer, clients SHOULD prepare text passwords as "query" strings by applying the SASLprep [RFC4013] profile of the stringprep [RFC3454] algorithm. Passwords consisting of other data (such as random octets) MUST NOT be altered. The determination of whether a password is textual is a local client matter. 4.2.1. Processing of the Bind Request Before processing a BindRequest, all uncompleted operations MUST either complete or be abandoned. The server may either wait for the uncompleted operations to complete, or abandon them. The server then proceeds to authenticate the client in either a single-step or multi-step Bind process. Each step requires the server to return a BindResponse to indicate the status of authentication. After sending a BindRequest, clients MUST NOT send further LDAP PDUs until receiving the BindResponse. Similarly, servers SHOULD NOT process or respond to requests received while processing a BindRequest. If the client did not bind before sending a request and receives an operationsError to that request, it may then send a BindRequest. If this also fails or the client chooses not to bind on the existing LDAP session, it may terminate the LDAP session, re-establish it, and begin again by first sending a BindRequest. This will aid in interoperating with servers implementing other versions of LDAP. Clients may send multiple Bind requests to change the authentication and/or security associations or to complete a multi-stage Bind process. Authentication from earlier binds is subsequently ignored. For some SASL authentication mechanisms, it may be necessary for the client to invoke the BindRequest multiple times ([RFC4513], Section 5.2). Clients MUST NOT invoke operations between two Bind requests made as part of a multi-stage Bind. A client may abort a SASL bind negotiation by sending a BindRequest with a different value in the mechanism field of SaslCredentials, or an AuthenticationChoice other than sasl. Sermersheim Standards Track [Page 17] RFC 4511 LDAPv3 June 2006 If the client sends a BindRequest with the sasl mechanism field as an empty string, the server MUST return a BindResponse with the resultCode set to authMethodNotSupported. This will allow the client to abort a negotiation if it wishes to try again with the same SASL mechanism. 4.2.2. Bind Response The Bind response is defined as follows. BindResponse ::= [APPLICATION 1] SEQUENCE { COMPONENTS OF LDAPResult, serverSaslCreds [7] OCTET STRING OPTIONAL } BindResponse consists simply of an indication from the server of the status of the client's request for authentication. A successful Bind operation is indicated by a BindResponse with a resultCode set to success. Otherwise, an appropriate result code is set in the BindResponse. For BindResponse, the protocolError result code may be used to indicate that the version number supplied by the client is unsupported. If the client receives a BindResponse where the resultCode is set to protocolError, it is to assume that the server does not support this version of LDAP. While the client may be able proceed with another version of this protocol (which may or may not require closing and re-establishing the transport connection), how to proceed with another version of this protocol is beyond the scope of this document. Clients that are unable or unwilling to proceed SHOULD terminate the LDAP session. The serverSaslCreds field is used as part of a SASL-defined bind mechanism to allow the client to authenticate the server to which it is communicating, or to perform "challenge-response" authentication. If the client bound with the simple choice, or the SASL mechanism does not require the server to return information to the client, then this field SHALL NOT be included in the BindResponse. 4.3. Unbind Operation The function of the Unbind operation is to terminate an LDAP session. The Unbind operation is not the antithesis of the Bind operation as the name implies. The naming of these operations are historical. The Unbind operation should be thought of as the "quit" operation. Sermersheim Standards Track [Page 18] RFC 4511 LDAPv3 June 2006 The Unbind operation is defined as follows: UnbindRequest ::= [APPLICATION 2] NULL The client, upon transmission of the UnbindRequest, and the server, upon receipt of the UnbindRequest, are to gracefully terminate the LDAP session as described in Section 5.3. Uncompleted operations are handled as specified in Section 3.1. 4.4. Unsolicited Notification An unsolicited notification is an LDAPMessage sent from the server to the client that is not in response to any LDAPMessage received by the server. It is used to signal an extraordinary condition in the server or in the LDAP session between the client and the server. The notification is of an advisory nature, and the server will not expect any response to be returned from the client. The unsolicited notification is structured as an LDAPMessage in which the messageID is zero and protocolOp is set to the extendedResp choice using the ExtendedResponse type (See Section 4.12). The responseName field of the ExtendedResponse always contains an LDAPOID that is unique for this notification. One unsolicited notification (Notice of Disconnection) is defined in this document. The specification of an unsolicited notification consists of: - the OBJECT IDENTIFIER assigned to the notification (to be specified in the responseName, - the format of the contents of the responseValue (if any), - the circumstances which will cause the notification to be sent, and - the semantics of the message. 4.4.1. Notice of Disconnection This notification may be used by the server to advise the client that the server is about to terminate the LDAP session on its own initiative. This notification is intended to assist clients in distinguishing between an exceptional server condition and a transient network failure. Note that this notification is not a response to an Unbind requested by the client. Uncompleted operations are handled as specified in Section 3.1. Sermersheim Standards Track [Page 19] RFC 4511 LDAPv3 June 2006 The responseName is 1.3.6.1.4.1.1466.20036, the responseValue field is absent, and the resultCode is used to indicate the reason for the disconnection. When the strongerAuthRequired resultCode is returned with this message, it indicates that the server has detected that an established security association between the client and server has unexpectedly failed or been compromised. Upon transmission of the Notice of Disconnection, the server gracefully terminates the LDAP session as described in Section 5.3. 4.5. Search Operation The Search operation is used to request a server to return, subject to access controls and other restrictions, a set of entries matching a complex search criterion. This can be used to read attributes from a single entry, from entries immediately subordinate to a particular entry, or from a whole subtree of entries. 4.5.1. Search Request The Search request is defined as follows: 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 AttributeSelection } AttributeSelection ::= SEQUENCE OF selector LDAPString -- The LDAPString is constrained to -- <attributeSelector> in Section 4.5.1.8 Filter ::= CHOICE { and [0] SET SIZE (1..MAX) OF filter Filter, or [1] SET SIZE (1..MAX) OF filter Filter, not [2] Filter, Sermersheim Standards Track [Page 20] RFC 4511 LDAPv3 June 2006 equalityMatch [3] AttributeValueAssertion, substrings [4] SubstringFilter, greaterOrEqual [5] AttributeValueAssertion, lessOrEqual [6] AttributeValueAssertion, present [7] AttributeDescription, approxMatch [8] AttributeValueAssertion, extensibleMatch [9] MatchingRuleAssertion, ... } SubstringFilter ::= SEQUENCE { type AttributeDescription, substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE { initial [0] AssertionValue, -- can occur at most once any [1] AssertionValue, final [2] AssertionValue } -- can occur at most once } MatchingRuleAssertion ::= SEQUENCE { matchingRule [1] MatchingRuleId OPTIONAL, type [2] AttributeDescription OPTIONAL, matchValue [3] AssertionValue, dnAttributes [4] BOOLEAN DEFAULT FALSE } Note that an X.500 "list"-like operation can be emulated by the client requesting a singleLevel Search operation with a filter checking for the presence of the 'objectClass' attribute, and that an X.500 "read"-like operation can be emulated by a baseObject Search operation with the same filter. A server that provides a gateway to X.500 is not required to use the Read or List operations, although it may choose to do so, and if it does, it must provide the same semantics as the X.500 Search operation. 4.5.1.1. SearchRequest.baseObject The name of the base object entry (or possibly the root) relative to which the Search is to be performed. 4.5.1.2. SearchRequest.scope Specifies the scope of the Search to be performed. The semantics (as described in [X.511]) of the defined values of this field are: baseObject: The scope is constrained to the entry named by baseObject. singleLevel: The scope is constrained to the immediate subordinates of the entry named by baseObject. Sermersheim Standards Track [Page 21] RFC 4511 LDAPv3 June 2006 wholeSubtree: The scope is constrained to the entry named by baseObject and to all its subordinates. 4.5.1.3. SearchRequest.derefAliases An indicator as to whether or not alias entries (as defined in [RFC4512]) are to be dereferenced during stages of the Search operation. The act of dereferencing an alias includes recursively dereferencing aliases that refer to aliases. Servers MUST detect looping while dereferencing aliases in order to prevent denial-of-service attacks of this nature. The semantics of the defined values of this field are: neverDerefAliases: Do not dereference aliases in searching or in locating the base object of the Search. derefInSearching: While searching subordinates of the base object, dereference any alias within the search scope. Dereferenced objects become the vertices of further search scopes where the Search operation is also applied. If the search scope is wholeSubtree, the Search continues in the subtree(s) of any dereferenced object. If the search scope is singleLevel, the search is applied to any dereferenced objects and is not applied to their subordinates. Servers SHOULD eliminate duplicate entries that arise due to alias dereferencing while searching. derefFindingBaseObj: Dereference aliases in locating the base object of the Search, but not when searching subordinates of the base object. derefAlways: Dereference aliases both in searching and in locating the base object of the Search. 4.5.1.4. SearchRequest.sizeLimit A size limit that restricts the maximum number of entries to be returned as a result of the Search. A value of zero in this field indicates that no client-requested size limit restrictions are in effect for the Search. Servers may also enforce a maximum number of entries to return. Sermersheim Standards Track [Page 22] RFC 4511 LDAPv3 June 2006 4.5.1.5. SearchRequest.timeLimit A time limit that restricts the maximum time (in seconds) allowed for a Search. A value of zero in this field indicates that no client- requested time limit restrictions are in effect for the Search. Servers may also enforce a maximum time limit for the Search. 4.5.1.6. SearchRequest.typesOnly An indicator as to whether Search results are to contain both attribute descriptions and values, or just attribute descriptions. Setting this field to TRUE causes only attribute descriptions (and not values) to be returned. Setting this field to FALSE causes both attribute descriptions and values to be returned. 4.5.1.7. SearchRequest.filter A filter that defines the conditions that must be fulfilled in order for the Search to match a given entry. The 'and', 'or', and 'not' choices can be used to form combinations of filters. At least one filter element MUST be present in an 'and' or 'or' choice. The others match against individual attribute values of entries in the scope of the Search. (Implementor's note: the 'not' filter is an example of a tagged choice in an implicitly-tagged module. In BER this is treated as if the tag were explicit.) A server MUST evaluate filters according to the three-valued logic of [X.511] (1993), Clause 7.8.1. In summary, a filter is evaluated to "TRUE", "FALSE", or "Undefined". If the filter evaluates to TRUE for a particular entry, then the attributes of that entry are returned as part of the Search result (subject to any applicable access control restrictions). If the filter evaluates to FALSE or Undefined, then the entry is ignored for the Search. A filter of the "and" choice is TRUE if all the filters in the SET OF evaluate to TRUE, FALSE if at least one filter is FALSE, and Undefined otherwise. A filter of the "or" choice is FALSE if all the filters in the SET OF evaluate to FALSE, TRUE if at least one filter is TRUE, and Undefined otherwise. A filter of the 'not' choice is TRUE if the filter being negated is FALSE, FALSE if it is TRUE, and Undefined if it is Undefined. A filter item evaluates to Undefined when the server would not be able to determine whether the assertion value matches an entry. Examples include: Sermersheim Standards Track [Page 23] RFC 4511 LDAPv3 June 2006 - An attribute description in an equalityMatch, substrings, greaterOrEqual, lessOrEqual, approxMatch, or extensibleMatch filter is not recognized by the server. - The attribute type does not define the appropriate matching rule. - A MatchingRuleId in the extensibleMatch is not recognized by the server or is not valid for the attribute type. - The type of filtering requested is not implemented. - The assertion value is invalid. For example, if a server did not recognize the attribute type shoeSize, the filters (shoeSize=*), (shoeSize=12), (shoeSize>=12), and (shoeSize<=12) would each evaluate to Undefined. Servers MUST NOT return errors if attribute descriptions or matching rule ids are not recognized, assertion values are invalid, or the assertion syntax is not supported. More details of filter processing are given in Clause 7.8 of [X.511]. 4.5.1.7.1. SearchRequest.filter.equalityMatch The matching rule for an equalityMatch filter is defined by the EQUALITY matching rule for the attribute type or subtype. The filter is TRUE when the EQUALITY rule returns TRUE as applied to the attribute or subtype and the asserted value. 4.5.1.7.2. SearchRequest.filter.substrings There SHALL be at most one 'initial' and at most one 'final' in the 'substrings' of a SubstringFilter. If 'initial' is present, it SHALL be the first element of 'substrings'. If 'final' is present, it SHALL be the last element of 'substrings'. The matching rule for an AssertionValue in a substrings filter item is defined by the SUBSTR matching rule for the attribute type or subtype. The filter is TRUE when the SUBSTR rule returns TRUE as applied to the attribute or subtype and the asserted value. Note that the AssertionValue in a substrings filter item conforms to the assertion syntax of the EQUALITY matching rule for the attribute type rather than to the assertion syntax of the SUBSTR matching rule for the attribute type. Conceptually, the entire SubstringFilter is converted into an assertion value of the substrings matching rule prior to applying the rule. Sermersheim Standards Track [Page 24] RFC 4511 LDAPv3 June 2006 4.5.1.7.3. SearchRequest.filter.greaterOrEqual The matching rule for a greaterOrEqual filter is defined by the ORDERING matching rule for the attribute type or subtype. The filter is TRUE when the ORDERING rule returns FALSE as applied to the attribute or subtype and the asserted value. 4.5.1.7.4. SearchRequest.filter.lessOrEqual The matching rules for a lessOrEqual filter are defined by the ORDERING and EQUALITY matching rules for the attribute type or subtype. The filter is TRUE when either the ORDERING or EQUALITY rule returns TRUE as applied to the attribute or subtype and the asserted value. 4.5.1.7.5. SearchRequest.filter.present A present filter is TRUE when there is an attribute or subtype of the specified attribute description present in an entry, FALSE when no attribute or subtype of the specified attribute description is present in an entry, and Undefined otherwise. 4.5.1.7.6. SearchRequest.filter.approxMatch An approxMatch filter is TRUE when there is a value of the attribute type or subtype for which some locally-defined approximate matching algorithm (e.g., spelling variations, phonetic match, etc.) returns TRUE. If a value matches for equality, it also satisfies an approximate match. If approximate matching is not supported for the attribute, this filter item should be treated as an equalityMatch. 4.5.1.7.7. SearchRequest.filter.extensibleMatch The fields of the extensibleMatch filter item are evaluated as follows: - If the matchingRule field is absent, the type field MUST be present, and an equality match is performed for that type. - If the type field is absent and the matchingRule is present, the matchValue is compared against all attributes in an entry that support that matchingRule. - If the type field is present and the matchingRule is present, the matchValue is compared against the specified attribute type and its subtypes. Sermersheim Standards Track [Page 25] RFC 4511 LDAPv3 June 2006 - If the dnAttributes field is set to TRUE, the match is additionally applied against all the AttributeValueAssertions in an entry's distinguished name, and it evaluates to TRUE if there is at least one attribute or subtype in the distinguished name for which the filter item evaluates to TRUE. The dnAttributes field is present to alleviate the need for multiple versions of generic matching rules (such as word matching), where one applies to entries and another applies to entries and DN attributes as well. The matchingRule used for evaluation determines the syntax for the assertion value. Once the matchingRule and attribute(s) have been determined, the filter item evaluates to TRUE if it matches at least one attribute type or subtype in the entry, FALSE if it does not match any attribute type or subtype in the entry, and Undefined if the matchingRule is not recognized, the matchingRule is unsuitable for use with the specified type, or the assertionValue is invalid. 4.5.1.8. SearchRequest.attributes A selection list of the attributes to be returned from each entry that matches the search filter. Attributes that are subtypes of listed attributes are implicitly included. LDAPString values of this field are constrained to the following Augmented Backus-Naur Form (ABNF) [RFC4234]: attributeSelector = attributedescription / selectorspecial selectorspecial = noattrs / alluserattrs noattrs = %x31.2E.31 ; "1.1" alluserattrs = %x2A ; asterisk ("*") The <attributedescription> production is defined in Section 2.5 of [RFC4512]. There are three special cases that may appear in the attributes selection list: 1. An empty list with no attributes requests the return of all user attributes. 2. A list containing "*" (with zero or more attribute descriptions) requests the return of all user attributes in addition to other listed (operational) attributes. Sermersheim Standards Track [Page 26] RFC 4511 LDAPv3 June 2006 3. A list containing only the OID "1.1" indicates that no attributes are to be returned. If "1.1" is provided with other attributeSelector values, the "1.1" attributeSelector is ignored. This OID was chosen because it does not (and can not) correspond to any attribute in use. Client implementors should note that even if all user attributes are requested, some attributes and/or attribute values of the entry may not be included in Search results due to access controls or other restrictions. Furthermore, servers will not return operational attributes, such as objectClasses or attributeTypes, unless they are listed by name. Operational attributes are described in [RFC4512]. Attributes are returned at most once in an entry. If an attribute description is named more than once in the list, the subsequent names are ignored. If an attribute description in the list is not recognized, it is ignored by the server. 4.5.2. Search Result The results of the Search operation are returned as zero or more SearchResultEntry and/or SearchResultReference messages, followed by a single SearchResultDone message. SearchResultEntry ::= [APPLICATION 4] SEQUENCE { objectName LDAPDN, attributes PartialAttributeList } PartialAttributeList ::= SEQUENCE OF partialAttribute PartialAttribute SearchResultReference ::= [APPLICATION 19] SEQUENCE SIZE (1..MAX) OF uri URI SearchResultDone ::= [APPLICATION 5] LDAPResult Each SearchResultEntry represents an entry found during the Search. Each SearchResultReference represents an area not yet explored during the Search. The SearchResultEntry and SearchResultReference messages may come in any order. Following all the SearchResultReference and SearchResultEntry responses, the server returns a SearchResultDone response, which contains an indication of success or details any errors that have occurred. Each entry returned in a SearchResultEntry will contain all appropriate attributes as specified in the attributes field of the Search Request, subject to access control and other administrative policy. Note that the PartialAttributeList may hold zero elements. Sermersheim Standards Track [Page 27] RFC 4511 LDAPv3 June 2006 This may happen when none of the attributes of an entry were requested or could be returned. Note also that the partialAttribute vals set may hold zero elements. This may happen when typesOnly is requested, access controls prevent the return of values, or other reasons. Some attributes may be constructed by the server and appear in a SearchResultEntry attribute list, although they are not stored attributes of an entry. Clients SHOULD NOT assume that all attributes can be modified, even if this is permitted by access control. If the server's schema defines short names [RFC4512] for an attribute type, then the server SHOULD use one of those names in attribute descriptions for that attribute type (in preference to using the <numericoid> [RFC4512] format of the attribute type's object identifier). The server SHOULD NOT use the short name if that name is known by the server to be ambiguous, or if it is otherwise likely to cause interoperability problems. 4.5.3. Continuation References in the Search Result If the server was able to locate the entry referred to by the baseObject but was unable or unwilling to search one or more non- local entries, the server may return one or more SearchResultReference messages, each containing a reference to another set of servers for continuing the operation. A server MUST NOT return any SearchResultReference messages if it has not located the baseObject and thus has not searched any entries. In this case, it would return a SearchResultDone containing either a referral or noSuchObject result code (depending on the server's knowledge of the entry named in the baseObject). If a server holds a copy or partial copy of the subordinate naming context (Section 5 of [RFC4512]), it may use the search filter to determine whether or not to return a SearchResultReference response. Otherwise, SearchResultReference responses are always returned when in scope. The SearchResultReference is of the same data type as the Referral. If the client wishes to progress the Search, it issues a new Search operation for each SearchResultReference that is returned. If multiple URIs are present, the client assumes that any supported URI may be used to progress the operation. Sermersheim Standards Track [Page 28] RFC 4511 LDAPv3 June 2006 Clients that follow search continuation references MUST ensure that they do not loop between servers. They MUST NOT repeatedly contact the same server for the same request with the same parameters. Some clients use a counter that is incremented each time search result reference handling occurs for an operation, and these kinds of clients MUST be able to handle at least ten nested referrals while progressing the operation. Note that the Abandon operation described in Section 4.11 applies only to a particular operation sent at the LDAP message layer between a client and server. The client must individually abandon subsequent Search operations it wishes to. A URI for a server implementing LDAP and accessible via TCP/IP (v4 or v6) [RFC793][RFC791] is written as an LDAP URL according to [RFC4516]. SearchResultReference values that are LDAP URLs follow these rules: - The <dn> part of the LDAP URL MUST be present, with the new target object name. The client uses this name when following the reference. - Some servers (e.g., participating in distributed indexing) may provide a different filter in the LDAP URL. - If the <filter> part of the LDAP URL is present, the client uses this filter in its next request to progress this Search, and if it is not present the client uses the same filter as it used for that Search. - If the originating search scope was singleLevel, the <scope> part of the LDAP URL will be "base". - It is RECOMMENDED that the <scope> part be present to avoid ambiguity. In the absence of a <scope> part, the scope of the original Search request is assumed. - Other aspects of the new Search request may be the same as or different from the Search request that generated the SearchResultReference. - The name of an unexplored subtree in a SearchResultReference need not be subordinate to the base object. Other kinds of URIs may be returned. The syntax and semantics of such URIs is left to future specifications. Clients may ignore URIs that they do not support. Sermersheim Standards Track [Page 29] RFC 4511 LDAPv3 June 2006 UTF-8-encoded characters appearing in the string representation of a DN, search filter, or other fields of the referral value may not be legal for URIs (e.g., spaces) and MUST be escaped using the % method in [RFC3986]. 4.5.3.1. Examples For example, suppose the contacted server (hosta) holds the entry <DC=Example,DC=NET> and the entry <CN=Manager,DC=Example,DC=NET>. It knows that both LDAP servers (hostb) and (hostc) hold <OU=People,DC=Example,DC=NET> (one is the master and the other server a shadow), and that LDAP-capable server (hostd) holds the subtree <OU=Roles,DC=Example,DC=NET>. If a wholeSubtree Search of <DC=Example,DC=NET> is requested to the contacted server, it may return the following: SearchResultEntry for DC=Example,DC=NET SearchResultEntry for CN=Manager,DC=Example,DC=NET SearchResultReference { ldap://hostb/OU=People,DC=Example,DC=NET??sub ldap://hostc/OU=People,DC=Example,DC=NET??sub } SearchResultReference { ldap://hostd/OU=Roles,DC=Example,DC=NET??sub } SearchResultDone (success) Client implementors should note that when following a SearchResultReference, additional SearchResultReference may be generated. Continuing the example, if the client contacted the server (hostb) and issued the Search request for the subtree <OU=People,DC=Example,DC=NET>, the server might respond as follows: SearchResultEntry for OU=People,DC=Example,DC=NET SearchResultReference { ldap://hoste/OU=Managers,OU=People,DC=Example,DC=NET??sub } SearchResultReference { ldap://hostf/OU=Consultants,OU=People,DC=Example,DC=NET??sub } SearchResultDone (success) Similarly, if a singleLevel Search of <DC=Example,DC=NET> is requested to the contacted server, it may return the following: SearchResultEntry for CN=Manager,DC=Example,DC=NET SearchResultReference { ldap://hostb/OU=People,DC=Example,DC=NET??base ldap://hostc/OU=People,DC=Example,DC=NET??base } SearchResultReference { ldap://hostd/OU=Roles,DC=Example,DC=NET??base } SearchResultDone (success) Sermersheim Standards Track [Page 30] RFC 4511 LDAPv3 June 2006 If the contacted server does not hold the base object for the Search, but has knowledge of its possible location, then it may return a referral to the client. In this case, if the client requests a subtree Search of <DC=Example,DC=ORG> to hosta, the server returns a SearchResultDone containing a referral. SearchResultDone (referral) { ldap://hostg/DC=Example,DC=ORG??sub } 4.6. Modify Operation The Modify operation allows a client to request that a modification of an entry be performed on its behalf by a server. The Modify Request is defined as follows: ModifyRequest ::= [APPLICATION 6] SEQUENCE { object LDAPDN, changes SEQUENCE OF change SEQUENCE { operation ENUMERATED { add (0), delete (1), replace (2), ... }, modification PartialAttribute } } Fields of the Modify Request are: - object: The value of this field contains the name of the entry to be modified. The server SHALL NOT perform any alias dereferencing in determining the object to be modified. - changes: A list of modifications to be performed on the entry. The entire list of modifications MUST be performed in the order they are listed as a single atomic operation. While individual modifications may violate certain aspects of the directory schema (such as the object class definition and Directory Information Tree (DIT) content rule), the resulting entry after the entire list of modifications is performed MUST conform to the requirements of the directory model and controlling schema [RFC4512]. - operation: Used to specify the type of modification being performed. Each operation type acts on the following modification. The values of this field have the following semantics, respectively: add: add values listed to the modification attribute, creating the attribute if necessary. Sermersheim Standards Track [Page 31] RFC 4511 LDAPv3 June 2006 delete: delete values listed from the modification attribute. If no values are listed, or if all current values of the attribute are listed, the entire attribute is removed. replace: replace all existing values of the modification attribute with the new values listed, creating the attribute if it did not already exist. A replace with no value will delete the entire attribute if it exists, and it is ignored if the attribute does not exist. - modification: A PartialAttribute (which may have an empty SET of vals) used to hold the attribute type or attribute type and values being modified. Upon receipt of a Modify Request, the server attempts to perform the necessary modifications to the DIT and returns the result in a Modify Response, defined as follows: ModifyResponse ::= [APPLICATION 7] LDAPResult The server will return to the client a single Modify Response indicating either the successful completion of the DIT modification, or the reason that the modification failed. Due to the requirement for atomicity in applying the list of modifications in the Modify Request, the client may expect that no modifications of the DIT have been performed if the Modify Response received indicates any sort of error, and that all requested modifications have been performed if the Modify Response indicates successful completion of the Modify operation. Whether or not the modification was applied cannot be determined by the client if the Modify Response was not received (e.g., the LDAP session was terminated or the Modify operation was abandoned). Servers MUST ensure that entries conform to user and system schema rules or other data model constraints. The Modify operation cannot be used to remove from an entry any of its distinguished values, i.e., those values which form the entry's relative distinguished name. An attempt to do so will result in the server returning the notAllowedOnRDN result code. The Modify DN operation described in Section 4.9 is used to rename an entry. For attribute types that specify no equality matching, the rules in Section 2.5.1 of [RFC4512] are followed. Note that due to the simplifications made in LDAP, there is not a direct mapping of the changes in an LDAP ModifyRequest onto the changes of a DAP ModifyEntry operation, and different implementations Sermersheim Standards Track [Page 32] RFC 4511 LDAPv3 June 2006 of LDAP-DAP gateways may use different means of representing the change. If successful, the final effect of the operations on the entry MUST be identical. 4.7. Add Operation The Add operation allows a client to request the addition of an entry into the Directory. The Add Request is defined as follows: AddRequest ::= [APPLICATION 8] SEQUENCE { entry LDAPDN, attributes AttributeList } AttributeList ::= SEQUENCE OF attribute Attribute Fields of the Add Request are: - entry: the name of the entry to be added. The server SHALL NOT dereference any aliases in locating the entry to be added. - attributes: the list of attributes that, along with those from the RDN, make up the content of the entry being added. Clients MAY or MAY NOT include the RDN attribute(s) in this list. Clients MUST NOT supply NO-USER-MODIFICATION attributes such as the createTimestamp or creatorsName attributes, since the server maintains these automatically. Servers MUST ensure that entries conform to user and system schema rules or other data model constraints. For attribute types that specify no equality matching, the rules in Section 2.5.1 of [RFC4512] are followed (this applies to the naming attribute in addition to any multi-valued attributes being added). The entry named in the entry field of the AddRequest MUST NOT exist for the AddRequest to succeed. The immediate superior (parent) of an object or alias entry to be added MUST exist. For example, if the client attempted to add <CN=JS,DC=Example,DC=NET>, the <DC=Example,DC=NET> entry did not exist, and the <DC=NET> entry did exist, then the server would return the noSuchObject result code with the matchedDN field containing <DC=NET>. Upon receipt of an Add Request, a server will attempt to add the requested entry. The result of the Add attempt will be returned to the client in the Add Response, defined as follows: AddResponse ::= [APPLICATION 9] LDAPResult Sermersheim Standards Track [Page 33] RFC 4511 LDAPv3 June 2006 A response of success indicates that the new entry has been added to the Directory. 4.8. Delete Operation The Delete operation allows a client to request the removal of an entry from the Directory. The Delete Request is defined as follows: DelRequest ::= [APPLICATION 10] LDAPDN The Delete Request consists of the name of the entry to be deleted. The server SHALL NOT dereference aliases while resolving the name of the target entry to be removed. Only leaf entries (those with no subordinate entries) can be deleted with this operation. Upon receipt of a Delete Request, a server will attempt to perform the entry removal requested and return the result in the Delete Response defined as follows: DelResponse ::= [APPLICATION 11] LDAPResult 4.9. Modify DN Operation The Modify DN operation allows a client to change the Relative Distinguished Name (RDN) of an entry in the Directory and/or to move a subtree of entries to a new location in the Directory. The Modify DN Request is defined as follows: ModifyDNRequest ::= [APPLICATION 12] SEQUENCE { entry LDAPDN, newrdn RelativeLDAPDN, deleteoldrdn BOOLEAN, newSuperior [0] LDAPDN OPTIONAL } Fields of the Modify DN Request are: - entry: the name of the entry to be changed. This entry may or may not have subordinate entries. - newrdn: the new RDN of the entry. The value of the old RDN is supplied when moving the entry to a new superior without changing its RDN. Attribute values of the new RDN not matching any attribute value of the entry are added to the entry, and an appropriate error is returned if this fails. Sermersheim Standards Track [Page 34] RFC 4511 LDAPv3 June 2006 - deleteoldrdn: a boolean field that controls whether the old RDN attribute values are to be retained as attributes of the entry or deleted from the entry. - newSuperior: if present, this is the name of an existing object entry that becomes the immediate superior (parent) of the existing entry. The server SHALL NOT dereference any aliases in locating the objects named in entry or newSuperior. Upon receipt of a ModifyDNRequest, a server will attempt to perform the name change and return the result in the Modify DN Response, defined as follows: ModifyDNResponse ::= [APPLICATION 13] LDAPResult For example, if the entry named in the entry field was <cn=John Smith,c=US>, the newrdn field was <cn=John Cougar Smith>, and the newSuperior field was absent, then this operation would attempt to rename the entry as <cn=John Cougar Smith,c=US>. If there was already an entry with that name, the operation would fail with the entryAlreadyExists result code. Servers MUST ensure that entries conform to user and system schema rules or other data model constraints. For attribute types that specify no equality matching, the rules in Section 2.5.1 of [RFC4512] are followed (this pertains to newrdn and deleteoldrdn). The object named in newSuperior MUST exist. For example, if the client attempted to add <CN=JS,DC=Example,DC=NET>, the <DC=Example,DC=NET> entry did not exist, and the <DC=NET> entry did exist, then the server would return the noSuchObject result code with the matchedDN field containing <DC=NET>. If the deleteoldrdn field is TRUE, the attribute values forming the old RDN (but not the new RDN) are deleted from the entry. If the deleteoldrdn field is FALSE, the attribute values forming the old RDN will be retained as non-distinguished attribute values of the entry. Note that X.500 restricts the ModifyDN operation to affect only entries that are contained within a single server. If the LDAP server is mapped onto DAP, then this restriction will apply, and the affectsMultipleDSAs result code will be returned if this error occurred. In general, clients MUST NOT expect to be able to perform arbitrary movements of entries and subtrees between servers or between naming contexts. Sermersheim Standards Track [Page 35] RFC 4511 LDAPv3 June 2006 4.10. Compare Operation The Compare operation allows a client to compare an assertion value with the values of a particular attribute in a particular entry in the Directory. The Compare Request is defined as follows: CompareRequest ::= [APPLICATION 14] SEQUENCE { entry LDAPDN, ava AttributeValueAssertion } Fields of the Compare Request are: - entry: the name of the entry to be compared. The server SHALL NOT dereference any aliases in locating the entry to be compared. - ava: holds the attribute value assertion to be compared. Upon receipt of a Compare Request, a server will attempt to perform the requested comparison and return the result in the Compare Response, defined as follows: CompareResponse ::= [APPLICATION 15] LDAPResult The resultCode is set to compareTrue, compareFalse, or an appropriate error. compareTrue indicates that the assertion value in the ava field matches a value of the attribute or subtype according to the attribute's EQUALITY matching rule. compareFalse indicates that the assertion value in the ava field and the values of the attribute or subtype did not match. Other result codes indicate either that the result of the comparison was Undefined (Section 4.5.1.7), or that some error occurred. Note that some directory systems may establish access controls that permit the values of certain attributes (such as userPassword) to be compared but not interrogated by other means. 4.11. Abandon Operation The function of the Abandon operation is to allow a client to request that the server abandon an uncompleted operation. The Abandon Request is defined as follows: AbandonRequest ::= [APPLICATION 16] MessageID The MessageID is that of an operation that was requested earlier at this LDAP message layer. The Abandon request itself has its own MessageID. This is distinct from the MessageID of the earlier operation being abandoned. Sermersheim Standards Track [Page 36] RFC 4511 LDAPv3 June 2006 There is no response defined in the Abandon operation. Upon receipt of an AbandonRequest, the server MAY abandon the operation identified by the MessageID. Since the client cannot tell the difference between a successfully abandoned operation and an uncompleted operation, the application of the Abandon operation is limited to uses where the client does not require an indication of its outcome. Abandon, Bind, Unbind, and StartTLS operations cannot be abandoned. In the event that a server receives an Abandon Request on a Search operation in the midst of transmitting responses to the Search, that server MUST cease transmitting entry responses to the abandoned request immediately, and it MUST NOT send the SearchResultDone. Of course, the server MUST ensure that only properly encoded LDAPMessage PDUs are transmitted. The ability to abandon other (particularly update) operations is at the discretion of the server. Clients should not send Abandon requests for the same operation multiple times, and they MUST also be prepared to receive results from operations they have abandoned (since these might have been in transit when the Abandon was requested or might not be able to be abandoned). Servers MUST discard Abandon requests for messageIDs they do not recognize, for operations that cannot be abandoned, and for operations that have already been abandoned. 4.12. Extended Operation The Extended operation allows additional operations to be defined for services not already available in the protocol; for example, to Add operations to install transport layer security (see Section 4.14). The Extended operation allows clients to make requests and receive responses with predefined syntaxes and semantics. These may be defined in RFCs or be private to particular implementations. Each Extended operation consists of an Extended request and an Extended response. ExtendedRequest ::= [APPLICATION 23] SEQUENCE { requestName [0] LDAPOID, requestValue [1] OCTET STRING OPTIONAL } Sermersheim Standards Track [Page 37] RFC 4511 LDAPv3 June 2006 The requestName is a dotted-decimal representation of the unique 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 an ExtendedResponse. ExtendedResponse ::= [APPLICATION 24] SEQUENCE { COMPONENTS OF LDAPResult, responseName [10] LDAPOID OPTIONAL, responseValue [11] OCTET STRING OPTIONAL } The responseName field, when present, contains an LDAPOID that is unique for this extended operation or response. This field is optional (even when the extension specification defines an LDAPOID for use in this field). The field will be absent whenever the server is unable or unwilling to determine the appropriate LDAPOID to return, for instance, when the requestName cannot be parsed or its value is not recognized. Where the requestName is not recognized, the server returns protocolError. (The server may return protocolError in other cases.) The requestValue and responseValue fields contain information associated with the operation. The format of these fields is defined by the specification of the Extended operation. Implementations MUST be prepared to handle arbitrary contents of these fields, including zero bytes. Values that are defined in terms of ASN.1 and BER- encoded according to Section 5.1 also follow the extensibility rules in Section 4. Servers list the requestName of Extended Requests they recognize in the 'supportedExtension' attribute in the root DSE (Section 5.1 of [RFC4512]). Extended operations may be specified in other documents. The specification of an Extended operation consists of: - the OBJECT IDENTIFIER assigned to the requestName, - the OBJECT IDENTIFIER (if any) assigned to the responseName (note that the same OBJECT IDENTIFIER may be used for both the requestName and responseName), Sermersheim Standards Track [Page 38] RFC 4511 LDAPv3 June 2006 - the format of the contents of the requestValue and responseValue (if any), and - the semantics of the operation. 4.13. IntermediateResponse Message While the Search operation provides a mechanism to return multiple response messages for a single Search request, other operations, by nature, do not provide for multiple response messages. The IntermediateResponse message provides a general mechanism for defining single-request/multiple-response operations in LDAP. This message is intended to be used in conjunction with the Extended operation to define new single-request/multiple-response operations or in conjunction with a control when extending existing LDAP operations in a way that requires them to return Intermediate response information. It is intended that the definitions and descriptions of Extended operations and controls that make use of the IntermediateResponse message will define the circumstances when an IntermediateResponse message can be sent by a server and the associated meaning of an IntermediateResponse message sent in a particular circumstance. IntermediateResponse ::= [APPLICATION 25] SEQUENCE { responseName [0] LDAPOID OPTIONAL, responseValue [1] OCTET STRING OPTIONAL } IntermediateResponse messages SHALL NOT be returned to the client unless the client issues a request that specifically solicits their return. This document defines two forms of solicitation: Extended operation and request control. IntermediateResponse messages are specified in documents describing the manner in which they are solicited (i.e., in the Extended operation or request control specification that uses them). These specifications include: - the OBJECT IDENTIFIER (if any) assigned to the responseName, - the format of the contents of the responseValue (if any), and - the semantics associated with the IntermediateResponse message. Extensions that allow the return of multiple types of IntermediateResponse messages SHALL identify those types using unique responseName values (note that one of these may specify no value). Sermersheim Standards Track [Page 39] RFC 4511 LDAPv3 June 2006 Sections 4.13.1 and 4.13.2 describe additional requirements on the inclusion of responseName and responseValue in IntermediateResponse messages. 4.13.1. Usage with LDAP ExtendedRequest and ExtendedResponse A single-request/multiple-response operation may be defined using a single ExtendedRequest message to solicit zero or more IntermediateResponse messages of one or more kinds, followed by an ExtendedResponse message. 4.13.2. Usage with LDAP Request Controls A control's semantics may include the return of zero or more IntermediateResponse messages prior to returning the final result code for the operation. One or more kinds of IntermediateResponse messages may be sent in response to a request control. All IntermediateResponse messages associated with request controls SHALL include a responseName. This requirement ensures that the client can correctly identify the source of IntermediateResponse messages when: - two or more controls using IntermediateResponse messages are included in a request for any LDAP operation or - one or more controls using IntermediateResponse messages are included in a request with an LDAP Extended operation that uses IntermediateResponse messages. 4.14. StartTLS Operation The Start Transport Layer Security (StartTLS) operation's purpose is to initiate installation of a TLS layer. The StartTLS operation is defined using the Extended operation mechanism described in Section 4.12. 4.14.1. StartTLS Request A client requests TLS establishment by transmitting a StartTLS request message to the server. The StartTLS request is defined in terms of an ExtendedRequest. The requestName is "1.3.6.1.4.1.1466.20037", and the requestValue field is always absent. Sermersheim Standards Track [Page 40] RFC 4511 LDAPv3 June 2006 The client MUST NOT send any LDAP PDUs at this LDAP message layer following this request until it receives a StartTLS Extended response and, in the case of a successful response, completes TLS negotiations. Detected sequencing problems (particularly those detailed in Section 3.1.1 of [RFC4513]) result in the resultCode being set to operationsError. If the server does not support TLS (whether by design or by current configuration), it returns with the resultCode set to protocolError as described in Section 4.12. 4.14.2. StartTLS Response When a StartTLS request is received, servers supporting the operation MUST return a StartTLS response message to the requestor. The responseName is "1.3.6.1.4.1.1466.20037" when provided (see Section 4.12). The responseValue is always absent. If the server is willing and able to negotiate TLS, it returns the StartTLS response with the resultCode set to success. Upon client receipt of a successful StartTLS response, protocol peers may commence with TLS negotiation as discussed in Section 3 of [RFC4513]. If the server is otherwise unwilling or unable to perform this operation, the server is to return an appropriate result code indicating the nature of the problem. For example, if the TLS subsystem is not presently available, the server may indicate this by returning with the resultCode set to unavailable. In cases where a non-success result code is returned, the LDAP session is left without a TLS layer. 4.14.3. Removal of the TLS Layer Either the client or server MAY remove the TLS layer and leave the LDAP message layer intact by sending and receiving a TLS closure alert. The initiating protocol peer sends the TLS closure alert and MUST wait until it receives a TLS closure alert from the other peer before sending further LDAP PDUs. When a protocol peer receives the initial TLS closure alert, it may choose to allow the LDAP message layer to remain intact. In this case, it MUST immediately transmit a TLS closure alert. Following this, it MAY send and receive LDAP PDUs. Sermersheim Standards Track [Page 41] RFC 4511 LDAPv3 June 2006 Protocol peers MAY terminate the LDAP session after sending or receiving a TLS closure alert. 5. Protocol Encoding, Connection, and Transfer This protocol is designed to run over connection-oriented, reliable transports, where the data stream is divided into octets (8-bit units), with each octet and each bit being significant. One underlying service, LDAP over TCP, is defined in Section 5.2. This service is generally applicable to applications providing or consuming X.500-based directory services on the Internet. This specification was generally written with the TCP mapping in mind. Specifications detailing other mappings may encounter various obstacles. Implementations of LDAP over TCP MUST implement the mapping as described in Section 5.2. This table illustrates the relationship among the different layers involved in an exchange between two protocol peers: +----------------------+ | LDAP message layer | +----------------------+ > LDAP PDUs +----------------------+ < data | SASL layer | +----------------------+ > SASL-protected data +----------------------+ < data | TLS layer | Application +----------------------+ > TLS-protected data ------------+----------------------+ < data Transport | transport connection | +----------------------+ 5.1. Protocol Encoding The protocol elements of LDAP SHALL be encoded for exchange using the Basic Encoding Rules [BER] of [ASN.1] with the following restrictions: - Only the definite form of length encoding is used. - OCTET STRING values are encoded in the primitive form only. - If the value of a BOOLEAN type is true, the encoding of the value octet is set to hex "FF". Sermersheim Standards Track [Page 42] RFC 4511 LDAPv3 June 2006 - If a value of a type is its default value, it is absent. Only some BOOLEAN and INTEGER types have default values in this protocol definition. These restrictions are meant to ease the overhead of encoding and decoding certain elements in BER. These restrictions do not apply to ASN.1 types encapsulated inside of OCTET STRING values, such as attribute values, unless otherwise stated. 5.2. Transmission Control Protocol (TCP) The encoded LDAPMessage PDUs are mapped directly onto the TCP [RFC793] bytestream using the BER-based encoding described in Section 5.1. It is recommended that server implementations running over the TCP provide a protocol listener on the Internet Assigned Numbers Authority (IANA)-assigned LDAP port, 389 [PortReg]. Servers may instead provide a listener on a different port number. Clients MUST support contacting servers on any valid TCP port. 5.3. Termination of the LDAP session Termination of the LDAP session is typically initiated by the client sending an UnbindRequest (Section 4.3), or by the server sending a Notice of Disconnection (Section 4.4.1). In these cases, each protocol peer gracefully terminates the LDAP session by ceasing exchanges at the LDAP message layer, tearing down any SASL layer, tearing down any TLS layer, and closing the transport connection. A protocol peer may determine that the continuation of any communication would be pernicious, and in this case, it may abruptly terminate the session by ceasing communication and closing the transport connection. In either case, when the LDAP session is terminated, uncompleted operations are handled as specified in Section 3.1. 6. Security Considerations This version of the protocol provides facilities for simple authentication using a cleartext password, as well as any SASL [RFC4422] mechanism. Installing SASL and/or TLS layers can provide integrity and other data security services. It is also permitted that the server can return its credentials to the client, if it chooses to do so. Sermersheim Standards Track [Page 43] RFC 4511 LDAPv3 June 2006 Use of cleartext password is strongly discouraged where the underlying transport service cannot guarantee confidentiality and may result in disclosure of the password to unauthorized parties. Servers are encouraged to prevent directory modifications by clients that have authenticated anonymously [RFC4513]. Security considerations for authentication methods, SASL mechanisms, and TLS are described in [RFC4513]. Note that SASL authentication exchanges do not provide data confidentiality or integrity protection for the version or name fields of the BindRequest or the resultCode, diagnosticMessage, or referral fields of the BindResponse, nor for any information contained in controls attached to Bind requests or responses. Thus, information contained in these fields SHOULD NOT be relied on unless it is otherwise protected (such as by establishing protections at the transport layer). Implementors should note that various security factors (including authentication and authorization information and data security services) may change during the course of the LDAP session or even during the performance of a particular operation. For instance, credentials could expire, authorization identities or access controls could change, or the underlying security layer(s) could be replaced or terminated. Implementations should be robust in the handling of changing security factors. In some cases, it may be appropriate to continue the operation even in light of security factor changes. For instance, it may be appropriate to continue an Abandon operation regardless of the change, or to continue an operation when the change upgraded (or maintained) the security factor. In other cases, it may be appropriate to fail or alter the processing of the operation. For instance, if confidential protections were removed, it would be appropriate either to fail a request to return sensitive data or, minimally, to exclude the return of sensitive data. Implementations that cache attributes and entries obtained via LDAP MUST ensure that access controls are maintained if that information is to be provided to multiple clients, since servers may have access control policies that prevent the return of entries or attributes in Search results except to particular authenticated clients. For example, caches could serve result information only to the client whose request caused it to be in the cache. Sermersheim Standards Track [Page 44] RFC 4511 LDAPv3 June 2006 Servers may return referrals or Search result references that redirect clients to peer servers. It is possible for a rogue application to inject such referrals into the data stream in an attempt to redirect a client to a rogue server. Clients are advised to be aware of this and possibly reject referrals when confidentiality measures are not in place. Clients are advised to reject referrals from the StartTLS operation. The matchedDN and diagnosticMessage fields, as well as some resultCode values (e.g., attributeOrValueExists and entryAlreadyExists), could disclose the presence or absence of specific data in the directory that is subject to access and other administrative controls. Server implementations should restrict access to protected information equally under both normal and error conditions. Protocol peers MUST be prepared to handle invalid and arbitrary- length protocol encodings. Invalid protocol encodings include: BER encoding exceptions, format string and UTF-8 encoding exceptions, overflow exceptions, integer value exceptions, and binary mode on/off flag exceptions. The LDAPv3 PROTOS [PROTOS-LDAP] test suite provides excellent examples of these exceptions and test cases used to discover flaws. In the event that a protocol peer senses an attack that in its nature could cause damage due to further communication at any layer in the LDAP session, the protocol peer should abruptly terminate the LDAP session as described in Section 5.3. 7. Acknowledgements This document is based on RFC 2251 by Mark Wahl, Tim Howes, and Steve Kille. RFC 2251 was a product of the IETF ASID Working Group. It is also based on RFC 2830 by Jeff Hodges, RL "Bob" Morgan, and Mark Wahl. RFC 2830 was a product of the IETF LDAPEXT Working Group. It is also based on RFC 3771 by Roger Harrison and Kurt Zeilenga. RFC 3771 was an individual submission to the IETF. This document is a product of the IETF LDAPBIS Working Group. Significant contributors of technical review and content include Kurt Zeilenga, Steven Legg, and Hallvard Furuseth. Sermersheim Standards Track [Page 45] RFC 4511 LDAPv3 June 2006 8. Normative References [ASN.1] ITU-T Recommendation X.680 (07/2002) | ISO/IEC 8824- 1:2002 "Information Technology - Abstract Syntax Notation One (ASN.1): Specification of basic notation". [BER] ITU-T Rec. X.690 (07/2002) | ISO/IEC 8825-1:2002, "Information technology - ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER)", 2002. [ISO10646] Universal Multiple-Octet Coded Character Set (UCS) - Architecture and Basic Multilingual Plane, ISO/IEC 10646-1 : 1993. [RFC791] Postel, J., "Internet Protocol", STD 5, RFC 791, September 1981. [RFC793] Postel, J., "Transmission Control Protocol", STD 7, RFC 793, September 1981. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC3454] Hoffman P. and M. Blanchet, "Preparation of Internationalized Strings ('stringprep')", RFC 3454, December 2002. [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003. [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005. [RFC4013] Zeilenga, K., "SASLprep: Stringprep Profile for User Names and Passwords", RFC 4013, February 2005. [RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 4234, October 2005. [RFC4346] Dierks, T. and E. Rescorla, "The TLS Protocol Version 1.1", RFC 4346, March 2006. [RFC4422] Melnikov, A., Ed. and K. Zeilenga, Ed., "Simple Authentication and Security Layer (SASL)", RFC 4422, June 2006. Sermersheim Standards Track [Page 46] RFC 4511 LDAPv3 June 2006 [RFC4510] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006. [RFC4512] Zeilenga, K., Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006. [RFC4513] Harrison, R., Ed., "Lightweight Directory Access Protocol (LDAP): Authentication Methods and Security Mechanisms", RFC 4513, June 2006. [RFC4514] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names", RFC 4514, June 2006. [RFC4516] Smith, M., Ed. and T. Howes, "Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator", RFC 4516, June 2006. [RFC4517] Legg, S., Ed., "Lightweight Directory Access Protocol (LDAP): Syntaxes and Matching Rules", RFC 4517, June 2006. [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006. [Unicode] The Unicode Consortium, "The Unicode Standard, Version 3.2.0" is defined by "The Unicode Standard, Version 3.0" (Reading, MA, Addison-Wesley, 2000. ISBN 0-201- 61633-5), as amended by the "Unicode Standard Annex #27: Unicode 3.1" (http://www.unicode.org/reports/tr27/) and by the "Unicode Standard Annex #28: Unicode 3.2" (http://www.unicode.org/reports/tr28/). [X.500] ITU-T Rec. X.500, "The Directory: Overview of Concepts, Models and Service", 1993. [X.511] ITU-T Rec. X.511, "The Directory: Abstract Service Definition", 1993. Sermersheim Standards Track [Page 47] RFC 4511 LDAPv3 June 2006 9. Informative References [CharModel] Whistler, K. and M. Davis, "Unicode Technical Report #17, Character Encoding Model", UTR17, <http://www.unicode.org/unicode/reports/tr17/>, August 2000. [Glossary] The Unicode Consortium, "Unicode Glossary", <http://www.unicode.org/glossary/>. [PortReg] IANA, "Port Numbers", <http://www.iana.org/assignments/port-numbers>. [PROTOS-LDAP] University of Oulu, "PROTOS Test-Suite: c06-ldapv3" <http://www.ee.oulu.fi/research/ouspg/protos/testing/ c06/ldapv3/>. 10. IANA Considerations The Internet Assigned Numbers Authority (IANA) has updated the LDAP result code registry to indicate that this document provides the definitive technical specification for result codes 0-36, 48-54, 64- 70, 80-90. It is also noted that one resultCode value (strongAuthRequired) has been renamed (to strongerAuthRequired). The IANA has also updated the LDAP Protocol Mechanism registry to indicate that this document and [RFC4513] provides the definitive technical specification for the StartTLS (1.3.6.1.4.1.1466.20037) Extended operation. IANA has assigned LDAP Object Identifier 18 [RFC4520] to identify the ASN.1 module defined in this document. Subject: Request for LDAP Object Identifier Registration Person & email address to contact for further information: Jim Sermersheim <jimse@novell.com> Specification: RFC 4511 Author/Change Controller: IESG Comments: Identifies the LDAP ASN.1 module Sermersheim Standards Track [Page 48] RFC 4511 LDAPv3 June 2006 Appendix A. LDAP Result Codes This normative appendix details additional considerations regarding LDAP result codes and provides a brief, general description of each LDAP result code enumerated in Section 4.1.9. Additional result codes MAY be defined for use with extensions [RFC4520]. Client implementations SHALL treat any result code that they do not recognize as an unknown error condition. The descriptions provided here do not fully account for result code substitutions used to prevent unauthorized disclosures (such as substitution of noSuchObject for insufficientAccessRights, or invalidCredentials for insufficientAccessRights). A.1. Non-Error Result Codes These result codes (called "non-error" result codes) do not indicate an error condition: success (0), compareFalse (5), compareTrue (6), referral (10), and saslBindInProgress (14). The success, compareTrue, and compareFalse result codes indicate successful completion (and, hence, are referred to as "successful" result codes). The referral and saslBindInProgress result codes indicate the client needs to take additional action to complete the operation. A.2. Result Codes Existing LDAP result codes are described as follows: success (0) Indicates the successful completion of an operation. Note: this code is not used with the Compare operation. See compareFalse (5) and compareTrue (6). Sermersheim Standards Track [Page 49] RFC 4511 LDAPv3 June 2006 operationsError (1) Indicates that the operation is not properly sequenced with relation to other operations (of same or different type). For example, this code is returned if the client attempts to StartTLS [RFC4346] while there are other uncompleted operations or if a TLS layer was already installed. protocolError (2) Indicates the server received data that is not well-formed. For Bind operation only, this code is also used to indicate that the server does not support the requested protocol version. For Extended operations only, this code is also used to indicate that the server does not support (by design or configuration) the Extended operation associated with the requestName. For request operations specifying multiple controls, this may be used to indicate that the server cannot ignore the order of the controls as specified, or that the combination of the specified controls is invalid or unspecified. timeLimitExceeded (3) Indicates that the time limit specified by the client was exceeded before the operation could be completed. sizeLimitExceeded (4) Indicates that the size limit specified by the client was exceeded before the operation could be completed. compareFalse (5) Indicates that the Compare operation has successfully completed and the assertion has evaluated to FALSE or Undefined. compareTrue (6) Indicates that the Compare operation has successfully completed and the assertion has evaluated to TRUE. authMethodNotSupported (7) Indicates that the authentication method or mechanism is not supported. Sermersheim Standards Track [Page 50] RFC 4511 LDAPv3 June 2006 strongerAuthRequired (8) Indicates the server requires strong(er) authentication in order to complete the operation. When used with the Notice of Disconnection operation, this code indicates that the server has detected that an established security association between the client and server has unexpectedly failed or been compromised. referral (10) Indicates that a referral needs to be chased to complete the operation (see Section 4.1.10). adminLimitExceeded (11) Indicates that an administrative limit has been exceeded. unavailableCriticalExtension (12) Indicates a critical control is unrecognized (see Section 4.1.11). confidentialityRequired (13) Indicates that data confidentiality protections are required. saslBindInProgress (14) Indicates the server requires the client to send a new bind request, with the same SASL mechanism, to continue the authentication process (see Section 4.2). noSuchAttribute (16) Indicates that the named entry does not contain the specified attribute or attribute value. undefinedAttributeType (17) Indicates that a request field contains an unrecognized attribute description. inappropriateMatching (18) Indicates that an attempt was made (e.g., in an assertion) to use a matching rule not defined for the attribute type concerned. constraintViolation (19) Indicates that the client supplied an attribute value that does not conform to the constraints placed upon it by the data model. For example, this code is returned when multiple values are supplied to an attribute that has a SINGLE-VALUE constraint. Sermersheim Standards Track [Page 51] RFC 4511 LDAPv3 June 2006 attributeOrValueExists (20) Indicates that the client supplied an attribute or value to be added to an entry, but the attribute or value already exists. invalidAttributeSyntax (21) Indicates that a purported attribute value does not conform to the syntax of the attribute. noSuchObject (32) Indicates that the object does not exist in the DIT. aliasProblem (33) Indicates that an alias problem has occurred. For example, the code may used to indicate an alias has been dereferenced that names no object. invalidDNSyntax (34) Indicates that an LDAPDN or RelativeLDAPDN field (e.g., search base, target entry, ModifyDN newrdn, etc.) of a request does not conform to the required syntax or contains attribute values that do not conform to the syntax of the attribute's type. aliasDereferencingProblem (36) Indicates that a problem occurred while dereferencing an alias. Typically, an alias was encountered in a situation where it was not allowed or where access was denied. inappropriateAuthentication (48) Indicates the server requires the client that had attempted to bind anonymously or without supplying credentials to provide some form of credentials. invalidCredentials (49) Indicates that the provided credentials (e.g., the user's name and password) are invalid. insufficientAccessRights (50) Indicates that the client does not have sufficient access rights to perform the operation. busy (51) Indicates that the server is too busy to service the operation. Sermersheim Standards Track [Page 52] RFC 4511 LDAPv3 June 2006 unavailable (52) Indicates that the server is shutting down or a subsystem necessary to complete the operation is offline. unwillingToPerform (53) Indicates that the server is unwilling to perform the operation. loopDetect (54) Indicates that the server has detected an internal loop (e.g., while dereferencing aliases or chaining an operation). namingViolation (64) Indicates that the entry's name violates naming restrictions. objectClassViolation (65) Indicates that the entry violates object class restrictions. notAllowedOnNonLeaf (66) Indicates that the operation is inappropriately acting upon a non-leaf entry. notAllowedOnRDN (67) Indicates that the operation is inappropriately attempting to remove a value that forms the entry's relative distinguished name. entryAlreadyExists (68) Indicates that the request cannot be fulfilled (added, moved, or renamed) as the target entry already exists. objectClassModsProhibited (69) Indicates that an attempt to modify the object class(es) of an entry's 'objectClass' attribute is prohibited. For example, this code is returned when a client attempts to modify the structural object class of an entry. affectsMultipleDSAs (71) Indicates that the operation cannot be performed as it would affect multiple servers (DSAs). other (80) Indicates the server has encountered an internal error. Sermersheim Standards Track [Page 53] RFC 4511 LDAPv3 June 2006 Appendix B. Complete ASN.1 Definition This appendix is normative. Lightweight-Directory-Access-Protocol-V3 {1 3 6 1 1 18} -- Copyright (C) The Internet Society (2006). This version of -- this ASN.1 module is part of RFC 4511; see the RFC itself -- for full legal notices. DEFINITIONS IMPLICIT TAGS EXTENSIBILITY IMPLIED ::= BEGIN LDAPMessage ::= SEQUENCE { messageID MessageID, protocolOp CHOICE { bindRequest BindRequest, bindResponse BindResponse, unbindRequest UnbindRequest, searchRequest SearchRequest, searchResEntry SearchResultEntry, searchResDone SearchResultDone, searchResRef SearchResultReference, modifyRequest ModifyRequest, modifyResponse ModifyResponse, addRequest AddRequest, addResponse AddResponse, delRequest DelRequest, delResponse DelResponse, modDNRequest ModifyDNRequest, modDNResponse ModifyDNResponse, compareRequest CompareRequest, compareResponse CompareResponse, abandonRequest AbandonRequest, extendedReq ExtendedRequest, extendedResp ExtendedResponse, ..., intermediateResponse IntermediateResponse }, controls [0] Controls OPTIONAL } MessageID ::= INTEGER (0 .. maxInt) maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) -- LDAPString ::= OCTET STRING -- UTF-8 encoded, -- [ISO10646] characters Sermersheim Standards Track [Page 54] RFC 4511 LDAPv3 June 2006 LDAPOID ::= OCTET STRING -- Constrained to <numericoid> -- [RFC4512] LDAPDN ::= LDAPString -- Constrained to <distinguishedName> -- [RFC4514] RelativeLDAPDN ::= LDAPString -- Constrained to <name-component> -- [RFC4514] AttributeDescription ::= LDAPString -- Constrained to <attributedescription> -- [RFC4512] AttributeValue ::= OCTET STRING AttributeValueAssertion ::= SEQUENCE { attributeDesc AttributeDescription, assertionValue AssertionValue } AssertionValue ::= OCTET STRING PartialAttribute ::= SEQUENCE { type AttributeDescription, vals SET OF value AttributeValue } Attribute ::= PartialAttribute(WITH COMPONENTS { ..., vals (SIZE(1..MAX))}) MatchingRuleId ::= LDAPString LDAPResult ::= SEQUENCE { resultCode ENUMERATED { success (0), operationsError (1), protocolError (2), timeLimitExceeded (3), sizeLimitExceeded (4), compareFalse (5), compareTrue (6), authMethodNotSupported (7), strongerAuthRequired (8), -- 9 reserved -- referral (10), adminLimitExceeded (11), unavailableCriticalExtension (12), confidentialityRequired (13), saslBindInProgress (14), Sermersheim Standards Track [Page 55] RFC 4511 LDAPv3 June 2006 noSuchAttribute (16), undefinedAttributeType (17), inappropriateMatching (18), constraintViolation (19), attributeOrValueExists (20), invalidAttributeSyntax (21), -- 22-31 unused -- noSuchObject (32), aliasProblem (33), invalidDNSyntax (34), -- 35 reserved for undefined isLeaf -- aliasDereferencingProblem (36), -- 37-47 unused -- inappropriateAuthentication (48), invalidCredentials (49), insufficientAccessRights (50), busy (51), unavailable (52), unwillingToPerform (53), loopDetect (54), -- 55-63 unused -- namingViolation (64), objectClassViolation (65), notAllowedOnNonLeaf (66), notAllowedOnRDN (67), entryAlreadyExists (68), objectClassModsProhibited (69), -- 70 reserved for CLDAP -- affectsMultipleDSAs (71), -- 72-79 unused -- other (80), ... }, matchedDN LDAPDN, diagnosticMessage LDAPString, referral [3] Referral OPTIONAL } Referral ::= SEQUENCE SIZE (1..MAX) OF uri URI URI ::= LDAPString -- limited to characters permitted in -- URIs Controls ::= SEQUENCE OF control Control Control ::= SEQUENCE { controlType LDAPOID, criticality BOOLEAN DEFAULT FALSE, controlValue OCTET STRING OPTIONAL } Sermersheim Standards Track [Page 56] RFC 4511 LDAPv3 June 2006 BindRequest ::= [APPLICATION 0] SEQUENCE { version INTEGER (1 .. 127), name LDAPDN, authentication AuthenticationChoice } AuthenticationChoice ::= CHOICE { simple [0] OCTET STRING, -- 1 and 2 reserved sasl [3] SaslCredentials, ... } SaslCredentials ::= SEQUENCE { mechanism LDAPString, credentials OCTET STRING OPTIONAL } BindResponse ::= [APPLICATION 1] SEQUENCE { COMPONENTS OF LDAPResult, serverSaslCreds [7] OCTET STRING OPTIONAL } UnbindRequest ::= [APPLICATION 2] NULL 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 AttributeSelection } AttributeSelection ::= SEQUENCE OF selector LDAPString -- The LDAPString is constrained to -- <attributeSelector> in Section 4.5.1.8 Filter ::= CHOICE { and [0] SET SIZE (1..MAX) OF filter Filter, or [1] SET SIZE (1..MAX) OF filter Filter, not [2] Filter, equalityMatch [3] AttributeValueAssertion, Sermersheim Standards Track [Page 57] RFC 4511 LDAPv3 June 2006 substrings [4] SubstringFilter, greaterOrEqual [5] AttributeValueAssertion, lessOrEqual [6] AttributeValueAssertion, present [7] AttributeDescription, approxMatch [8] AttributeValueAssertion, extensibleMatch [9] MatchingRuleAssertion, ... } SubstringFilter ::= SEQUENCE { type AttributeDescription, substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE { initial [0] AssertionValue, -- can occur at most once any [1] AssertionValue, final [2] AssertionValue } -- can occur at most once } MatchingRuleAssertion ::= SEQUENCE { matchingRule [1] MatchingRuleId OPTIONAL, type [2] AttributeDescription OPTIONAL, matchValue [3] AssertionValue, dnAttributes [4] BOOLEAN DEFAULT FALSE } SearchResultEntry ::= [APPLICATION 4] SEQUENCE { objectName LDAPDN, attributes PartialAttributeList } PartialAttributeList ::= SEQUENCE OF partialAttribute PartialAttribute SearchResultReference ::= [APPLICATION 19] SEQUENCE SIZE (1..MAX) OF uri URI SearchResultDone ::= [APPLICATION 5] LDAPResult ModifyRequest ::= [APPLICATION 6] SEQUENCE { object LDAPDN, changes SEQUENCE OF change SEQUENCE { operation ENUMERATED { add (0), delete (1), replace (2), ... }, modification PartialAttribute } } ModifyResponse ::= [APPLICATION 7] LDAPResult Sermersheim Standards Track [Page 58] RFC 4511 LDAPv3 June 2006 AddRequest ::= [APPLICATION 8] SEQUENCE { entry LDAPDN, attributes AttributeList } AttributeList ::= SEQUENCE OF attribute Attribute AddResponse ::= [APPLICATION 9] LDAPResult DelRequest ::= [APPLICATION 10] LDAPDN DelResponse ::= [APPLICATION 11] LDAPResult ModifyDNRequest ::= [APPLICATION 12] SEQUENCE { entry LDAPDN, newrdn RelativeLDAPDN, deleteoldrdn BOOLEAN, newSuperior [0] LDAPDN OPTIONAL } ModifyDNResponse ::= [APPLICATION 13] LDAPResult CompareRequest ::= [APPLICATION 14] SEQUENCE { entry LDAPDN, ava AttributeValueAssertion } CompareResponse ::= [APPLICATION 15] LDAPResult AbandonRequest ::= [APPLICATION 16] MessageID ExtendedRequest ::= [APPLICATION 23] SEQUENCE { requestName [0] LDAPOID, requestValue [1] OCTET STRING OPTIONAL } ExtendedResponse ::= [APPLICATION 24] SEQUENCE { COMPONENTS OF LDAPResult, responseName [10] LDAPOID OPTIONAL, responseValue [11] OCTET STRING OPTIONAL } IntermediateResponse ::= [APPLICATION 25] SEQUENCE { responseName [0] LDAPOID OPTIONAL, responseValue [1] OCTET STRING OPTIONAL } END Sermersheim Standards Track [Page 59] RFC 4511 LDAPv3 June 2006 Appendix C. Changes This appendix is non-normative. This appendix summarizes substantive changes made to RFC 2251, RFC 2830, and RFC 3771. C.1. Changes Made to RFC 2251 This section summarizes the substantive changes made to Sections 1, 2, 3.1, and 4, and the remainder of RFC 2251. Readers should consult [RFC4512] and [RFC4513] for summaries of changes to other sections. C.1.1. Section 1 (Status of this Memo) - Removed IESG note. Post publication of RFC 2251, mandatory LDAP authentication mechanisms have been standardized which are sufficient to remove this note. See [RFC4513] for authentication mechanisms. C.1.2. Section 3.1 (Protocol Model) and others - Removed notes giving history between LDAP v1, v2, and v3. Instead, added sufficient language so that this document can stand on its own. C.1.3. Section 4 (Elements of Protocol) - Clarified where the extensibility features of ASN.1 apply to the protocol. This change affected various ASN.1 types by the inclusion of ellipses (...) to certain elements. - Removed the requirement that servers that implement version 3 or later MUST provide the 'supportedLDAPVersion' attribute. This statement provided no interoperability advantages. C.1.4. Section 4.1.1 (Message Envelope) - There was a mandatory requirement for the server to return a Notice of Disconnection and drop the transport connection when a PDU is malformed in a certain way. This has been updated such that the server SHOULD return the Notice of Disconnection, and it MUST terminate the LDAP Session. C.1.5. Section 4.1.1.1 (Message ID) - Required that the messageID of requests MUST be non-zero as the zero is reserved for Notice of Disconnection. Sermersheim Standards Track [Page 60] RFC 4511 LDAPv3 June 2006 - Specified when it is and isn't appropriate to return an already used messageID. RFC 2251 accidentally imposed synchronous server behavior in its wording of this. C.1.6. Section 4.1.2 (String Types) - Stated that LDAPOID is constrained to <numericoid> from [RFC4512]. C.1.7. Section 4.1.5.1 (Binary Option) and others - Removed the Binary Option from the specification. There are numerous interoperability problems associated with this method of alternate attribute type encoding. Work to specify a suitable replacement is ongoing. C.1.8. Section 4.1.8 (Attribute) - Combined the definitions of PartialAttribute and Attribute here, and defined Attribute in terms of PartialAttribute. C.1.9. Section 4.1.10 (Result Message) - Renamed "errorMessage" to "diagnosticMessage" as it is allowed to be sent for non-error results. - Moved some language into Appendix A, and referred the reader there. - Allowed matchedDN to be present for other result codes than those listed in RFC 2251. - Renamed the code "strongAuthRequired" to "strongerAuthRequired" to clarify that this code may often be returned to indicate that a stronger authentication is needed to perform a given operation. C.1.10. Section 4.1.11 (Referral) - Defined referrals in terms of URIs rather than URLs. - Removed the requirement that all referral URIs MUST be equally capable of progressing the operation. The statement was ambiguous and provided no instructions on how to carry it out. - Added the requirement that clients MUST NOT loop between servers. - Clarified the instructions for using LDAPURLs in referrals, and in doing so added a recommendation that the scope part be present. - Removed imperatives which required clients to use URLs in specific ways to progress an operation. These did nothing for interoperability. Sermersheim Standards Track [Page 61] RFC 4511 LDAPv3 June 2006 C.1.11. Section 4.1.12 (Controls) - Specified how control values defined in terms of ASN.1 are to be encoded. - Noted that the criticality field is only applied to request messages (except UnbindRequest), and must be ignored when present on response messages and UnbindRequest. - Specified that non-critical controls may be ignored at the server's discretion. There was confusion in the original wording which led some to believe that recognized controls may not be ignored as long as they were associated with a proper request. - Added language regarding combinations of controls and the ordering of controls on a message. - Specified that when the semantics of the combination of controls is undefined or unknown, it results in a protocolError. - Changed "The server MUST be prepared" to "Implementations MUST be prepared" in paragraph 8 to reflect that both client and server implementations must be able to handle this (as both parse controls). C.1.12. Section 4.2 (Bind Operation) - Mandated that servers return protocolError when the version is not supported. - Disambiguated behavior when the simple authentication is used, the name is empty, and the password is non-empty. - Required servers to not dereference aliases for Bind. This was added for consistency with other operations and to help ensure data consistency. - Required that textual passwords be transferred as UTF-8 encoded Unicode, and added recommendations on string preparation. This was to help ensure interoperability of passwords being sent from different clients. C.1.13. Section 4.2.1 (Sequencing of the Bind Request) - This section was largely reorganized for readability, and language was added to clarify the authentication state of failed and abandoned Bind operations. - Removed: "If a SASL transfer encryption or integrity mechanism has been negotiated, that mechanism does not support the changing of credentials from one identity to another, then the client MUST instead establish a new connection." If there are dependencies between multiple negotiations of a particular SASL mechanism, the technical specification for that SASL mechanism details how applications are to deal with them. LDAP should not require any special handling. - Dropped MUST imperative in paragraph 3 to align with [RFC2119]. Sermersheim Standards Track [Page 62] RFC 4511 LDAPv3 June 2006 - Mandated that clients not send non-Bind operations while a Bind is in progress, and suggested that servers not process them if they are received. This is needed to ensure proper sequencing of the Bind in relationship to other operations. C.1.14. Section 4.2.3 (Bind Response) - Moved most error-related text to Appendix A, and added text regarding certain errors used in conjunction with the Bind operation. - Prohibited the server from specifying serverSaslCreds when not appropriate. C.1.15. Section 4.3 (Unbind Operation) - Specified that both peers are to cease transmission and terminate the LDAP session for the Unbind operation. C.1.16. Section 4.4 (Unsolicited Notification) - Added instructions for future specifications of Unsolicited Notifications. C.1.17. Section 4.5.1 (Search Request) - SearchRequest attributes is now defined as an AttributeSelection type rather than AttributeDescriptionList, and an ABNF is provided. - SearchRequest attributes may contain duplicate attribute descriptions. This was previously prohibited. Now servers are instructed to ignore subsequent names when they are duplicated. This was relaxed in order to allow different short names and also OIDs to be requested for an attribute. - The present search filter now evaluates to Undefined when the specified attribute is not known to the server. It used to evaluate to FALSE, which caused behavior inconsistent with what most would expect, especially when the 'not' operator was used. - The Filter choice SubstringFilter substrings type is now defined with a lower bound of 1. - The SubstringFilter substrings 'initial, 'any', and 'final' types are now AssertionValue rather than LDAPString. Also, added imperatives stating that 'initial' (if present) must be listed first, and 'final' (if present) must be listed last. - Disambiguated the semantics of the derefAliases choices. There was question as to whether derefInSearching applied to the base object in a wholeSubtree Search. - Added instructions for equalityMatch, substrings, greaterOrEqual, lessOrEqual, and approxMatch. Sermersheim Standards Track [Page 63] RFC 4511 LDAPv3 June 2006 C.1.18. Section 4.5.2 (Search Result) - Recommended that servers not use attribute short names when it knows they are ambiguous or may cause interoperability problems. - Removed all mention of ExtendedResponse due to lack of implementation. C.1.19. Section 4.5.3 (Continuation References in the Search Result) - Made changes similar to those made to Section 4.1.11. C.1.20. Section 4.5.3.1 (Example) - Fixed examples to adhere to changes made to Section 4.5.3. C.1.21. Section 4.6 (Modify Operation) - Replaced AttributeTypeAndValues with Attribute as they are equivalent. - Specified the types of modification changes that might temporarily violate schema. Some readers were under the impression that any temporary schema violation was allowed. C.1.22. Section 4.7 (Add Operation) - Aligned Add operation with X.511 in that the attributes of the RDN are used in conjunction with the listed attributes to create the entry. Previously, Add required that the distinguished values be present in the listed attributes. - Removed requirement that the objectClass attribute MUST be specified as some DSE types do not require this attribute. Instead, generic wording was added, requiring the added entry to adhere to the data model. - Removed recommendation regarding placement of objects. This is covered in the data model document. C.1.23. Section 4.9 (Modify DN Operation) - Required servers to not dereference aliases for Modify DN. This was added for consistency with other operations and to help ensure data consistency. - Allow Modify DN to fail when moving between naming contexts. - Specified what happens when the attributes of the newrdn are not present on the entry. Sermersheim Standards Track [Page 64] RFC 4511 LDAPv3 June 2006 C.1.24. Section 4.10 (Compare Operation) - Specified that compareFalse means that the Compare took place and the result is false. There was confusion that led people to believe that an Undefined match resulted in compareFalse. - Required servers to not dereference aliases for Compare. This was added for consistency with other operations and to help ensure data consistency. C.1.25. Section 4.11 (Abandon Operation) - Explained that since Abandon returns no response, clients should not use it if they need to know the outcome. - Specified that Abandon and Unbind cannot be abandoned. C.1.26. Section 4.12 (Extended Operation) - Specified how values of Extended operations defined in terms of ASN.1 are to be encoded. - Added instructions on what Extended operation specifications consist of. - Added a recommendation that servers advertise supported Extended operations. C.1.27. Section 5.2 (Transfer Protocols) - Moved referral-specific instructions into referral-related sections. C.1.28. Section 7 (Security Considerations) - Reworded notes regarding SASL not protecting certain aspects of the LDAP Bind messages. - Noted that Servers are encouraged to prevent directory modifications by clients that have authenticated anonymously [RFC4513]. - Added a note regarding the possibility of changes to security factors (authentication, authorization, and data confidentiality). - Warned against following referrals that may have been injected in the data stream. - Noted that servers should protect information equally, whether in an error condition or not, and mentioned matchedDN, diagnosticMessage, and resultCodes specifically. - Added a note regarding malformed and long encodings. Sermersheim Standards Track [Page 65] RFC 4511 LDAPv3 June 2006 C.1.29. Appendix A (Complete ASN.1 Definition) - Added "EXTENSIBILITY IMPLIED" to ASN.1 definition. - Removed AttributeType. It is not used. C.2. Changes Made to RFC 2830 This section summarizes the substantive changes made to Sections of RFC 2830. Readers should consult [RFC4513] for summaries of changes to other sections. C.2.1. Section 2.3 (Response other than "success") - Removed wording indicating that referrals can be returned from StartTLS. - Removed requirement that only a narrow set of result codes can be returned. Some result codes are required in certain scenarios, but any other may be returned if appropriate. - Removed requirement that the ExtendedResponse.responseName MUST be present. There are circumstances where this is impossible, and requiring this is at odds with language in Section 4.12. C.2.1. Section 4 (Closing a TLS Connection) - Reworded most of this section to align with definitions of the LDAP protocol layers. - Removed instructions on abrupt closure as this is covered in other areas of the document (specifically, Section 5.3) C.3. Changes Made to RFC 3771 - Rewrote to fit into this document. In general, semantics were preserved. Supporting and background language seen as redundant due to its presence in this document was omitted. - Specified that Intermediate responses to a request may be of different types, and one of the response types may be specified to have no response value. Sermersheim Standards Track [Page 66] RFC 4511 LDAPv3 June 2006 Editor's Address Jim Sermersheim Novell, Inc. 1800 South Novell Place Provo, Utah 84606, USA Phone: +1 801 861-3088 EMail: jimse@novell.com Sermersheim Standards Track [Page 67] RFC 4511 LDAPv3 June 2006 Full Copyright Statement Copyright (C) The Internet Society (2006). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Sermersheim Standards Track [Page 68] PK '�c\��� �. �. ( doc/alt-openldap11-devel/rfc/rfc3829.txtnu �[��� Network Working Group R. Weltman Request for Comments: 3829 America Online Category: Informational M. Smith Pearl Crescent, LLC M. Wahl July 2004 Lightweight Directory Access Protocol (LDAP) Authorization Identity Request and Response Controls Status of this Memo This memo provides information for the Internet community. It does not specify an Internet standard of any kind. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2004). Abstract This document extends the Lightweight Directory Access Protocol (LDAP) bind operation with a mechanism for requesting and returning the authorization identity it establishes. Specifically, this document defines the Authorization Identity Request and Response controls for use with the Bind operation. 1. Introduction This document defines support for the Authorization Identity Request Control and the Authorization Identity Response Control for requesting and returning the authorization established in a bind operation. The Authorization Identity Request Control may be submitted by a client in a bind request if authenticating with version 3 of the Lightweight Directory Access Protocol (LDAP) protocol [LDAPv3]. In the LDAP server's bind response, it may then include an Authorization Identity Response Control. The response control contains the identity assumed by the client. This is useful when there is a mapping step or other indirection during the bind, so that the client can be told what LDAP identity was granted. Client authentication with certificates is the primary situation where this applies. Also, some Simple Authentication and Security Layer [SASL] authentication mechanisms may not involve the client explicitly providing a DN, or may result in an authorization identity which is different from the authentication identity provided by the client [AUTH]. Weltman, et al. Informational [Page 1] RFC 3829 Authorization Identity Bind Control July 2004 The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" used in this document are to be interpreted as described in [RFCKeyWords]. 2. Publishing support for the Authorization Identity Request Control and the Authorization Identity Response Control Support for the Authorization Identity Request Control and the Authorization Identity Response Control is indicated by the presence of the Object Identifiers (OIDs) 2.16.840.1.113730.3.4.16 and 2.16.840.1.113730.3.4.15, respectively, in the supportedControl attribute [LDAPATTRS] of a server's root DSA-specific Entry (DSE). 3. Authorization Identity Request Control This control MAY be included in any bind request which specifies protocol version 3, as part of the controls field of the LDAPMessage as defined in [LDAPPROT]. In a multi-step bind operation, the client MUST provide the control with each bind request. The controlType is "2.16.840.1.113730.3.4.16" and the controlValue is absent. 4. Authorization Identity Response Control This control MAY be included in any final bind response where the first bind request of the bind operation included an Authorization Identity Request Control as part of the controls field of the LDAPMessage as defined in [LDAPPROT]. The controlType is "2.16.840.1.113730.3.4.15". If the bind request succeeded and resulted in an identity (not anonymous), the controlValue contains the authorization identity (authzId), as defined in [AUTH] section 9, granted to the requestor. If the bind request resulted in an anonymous association, the controlValue field is a string of zero length. If the bind request resulted in more than one authzId, the primary authzId is returned in the controlValue field. The control is only included in a bind response if the resultCode for the bind operation is success. If the server requires confidentiality protections to be in place prior to use of this control (see Security Considerations), the server reports failure to have adequate confidentiality protections in place by returning the confidentialityRequired result code. Weltman, et al. Informational [Page 2] RFC 3829 Authorization Identity Bind Control July 2004 If the client has insufficient access rights to the requested authorization information, the server reports this by returning the insufficientAccessRights result code. Identities presented by a client as part of the authentication process may be mapped by the server to one or more authorization identities. The bind response control can be used to retrieve the primary authzId. For example, during client authentication with certificates [AUTH], a client may possess more than one certificate and may not be able to determine which one was ultimately selected for authentication to the server. The subject DN field in the selected certificate may not correspond exactly to a DN in the directory, but rather have gone through a mapping process controlled by the server. Upon completing the certificate-based authentication, the client may issue a SASL [SASL] bind request, specifying the EXTERNAL mechanism and including an Authorization Identity Request Control. The bind response MAY include an Authorization Identity Response Control indicating the DN in the server's Directory Information Tree (DIT) which the certificate was mapped to. 5. Alternative Approach with Extended Operation The LDAP "Who am I?" [AUTHZID] extended operation provides a mechanism to query the authorization identity associated with a bound connection. Using an extended operation, as opposed to a bind response control, allows a client to learn the authorization identity after the bind has established integrity and data confidentiality protections. The disadvantages of the extended operation approach are coordination issues between "Who am I?" requests, bind requests, and other requests, and that an extra operation is required to learn the authorization identity. For multithreaded or high bandwidth server application environments, the bind response approach may be preferable. 6. Security Considerations The Authorization Identity Request and Response Controls are subject to standard LDAP security considerations. The controls may be passed over a secure as well as over an insecure channel. They are not protected by security layers negotiated by the bind operation. The response control allows for an additional authorization identity to be passed. In some deployments, these identities may contain confidential information which require privacy protection. In such deployments, a security layer should be established prior to issuing a bind request with an Authorization Identity Request Control. Weltman, et al. Informational [Page 3] RFC 3829 Authorization Identity Bind Control July 2004 7. IANA Considerations The OIDs 2.16.840.1.113730.3.4.16 and 2.16.840.1.113730.3.4.15 are reserved for the Authorization Identity Request and Response Controls, respectively. The Authorization Identity Request Control has been registered as an LDAP Protocol Mechanism [IANALDAP]. 8. References 8.1. Normative References [LDAPv3] Hodges, J. and R. Morgan, "Lightweight Directory Access Protocol (v3): Technical Specification", RFC 3377, September 2002. [LDAPPROT] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [RFCKeyWords] Bradner, S., "Key Words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [AUTH] Wahl, M., Alvestrand, H., Hodges, J. and R. Morgan, "Authentication Methods for LDAP", RFC 2829, May 2000. [SASL] Myers, J., "Simple Authentication and Security Layer (SASL)", RFC 2222, October 1997. [LDAPATTRS] Wahl, M., Coulbeck, A., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (v3): Attribute Syntax Definitions", RFC 2252, December 1997. [IANALDAP] Hodges, J. and R. Morgan, "Lightweight Directory Access Protocol (v3): Technical Specification", RFC 3377, September 2002. 8.2. Informative References [AUTHZID] Zeilenga, K., "LDAP 'Who am I?' Operation", Work in Progress, April 2002. Weltman, et al. Informational [Page 4] RFC 3829 Authorization Identity Bind Control July 2004 9. Author's Addresses Rob Weltman America Online 360 W. Caribbean Drive Sunnyvale, CA 94089 USA Phone: +1 650 937-3194 EMail: robw@worldspot.com Mark Smith Pearl Crescent, LLC 447 Marlpool Drive Saline, MI 48176 USA Phone: +1 734 944-2856 EMail: mcs@pearlcrescent.com Mark Wahl PO Box 90626 Austin, TX 78709-0626 USA Weltman, et al. Informational [Page 5] RFC 3829 Authorization Identity Bind Control July 2004 10. Full Copyright Statement Copyright (C) The Internet Society (2004). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Weltman, et al. Informational [Page 6] PK '�c\�R˸W; W; ( doc/alt-openldap11-devel/rfc/rfc4530.txtnu �[��� Network Working Group K. Zeilenga Request for Comments: 4530 OpenLDAP Foundation Category: Standards Track June 2006 Lightweight Directory Access Protocol (LDAP) entryUUID Operational Attribute Status of This Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2006). Abstract This document describes the LDAP/X.500 'entryUUID' operational attribute and associated matching rules and syntax. The attribute holds a server-assigned Universally Unique Identifier (UUID) for the object. Directory clients may use this attribute to distinguish objects identified by a distinguished name or to locate an object after renaming. Zeilenga Standards Track [Page 1] RFC 4530 LDAP entryUUID June 2006 Table of Contents 1. Background and Intended Use .....................................2 2. UUID Schema Elements ............................................3 2.1. UUID Syntax ................................................3 2.2. 'uuidMatch' Matching Rule ..................................3 2.3. 'uuidOrderingMatch' Matching Rule ..........................3 2.4. 'entryUUID' Attribute ......................................4 3. Security Considerations .........................................4 4. IANA Considerations .............................................5 4.1. Object Identifier Registration .............................5 4.2. UUID Syntax Registration ...................................5 4.3. 'uuidMatch' Descriptor Registration ........................5 4.4. 'uuidOrderingMatch' Descriptor Registration ................5 4.5. 'entryUUID' Descriptor Registration ........................6 5. Acknowledgements ................................................6 6. References ......................................................6 6.1. Normative References .......................................6 6.2. Informative References .....................................7 1. Background and Intended Use In X.500 Directory Services [X.501], such as those accessible using the Lightweight Directory Access Protocol (LDAP) [RFC4510], an object is identified by its distinguished name (DN). However, DNs are not stable identifiers. That is, a new object may be identified by a DN that previously identified another (now renamed or deleted) object. A Universally Unique Identifier (UUID) is "an identifier unique across both space and time, with respect to the space of all UUIDs" [RFC4122]. UUIDs are used in a wide range of systems. This document describes the 'entryUUID' operational attribute, which holds the UUID assigned to the object by the server. Clients may use this attribute to distinguish objects identified by a particular distinguished name or to locate a particular object after renaming. This document defines the UUID syntax, the 'uuidMatch' and 'uuidOrderingMatch' matching rules, and the 'entryUUID' attribute type. Schema definitions are provided using LDAP description formats [RFC4512]. Definitions provided here are formatted (line wrapped) for readability. Zeilenga Standards Track [Page 2] RFC 4530 LDAP entryUUID June 2006 In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in BCP 14 [RFC2119]. 2. UUID Schema Elements 2.1. UUID Syntax A Universally Unique Identifier (UUID) [RFC4122] is a 16-octet (128- bit) value that identifies an object. The ASN.1 [X.680] type UUID is defined to represent UUIDs as follows: UUID ::= OCTET STRING (SIZE(16)) -- constrained to an UUID [RFC4122] In LDAP, UUID values are encoded using the [ASCII] character string representation described in [RFC4122]. For example, "597ae2f6-16a6-1027-98f4-d28b5365dc14". The following is an LDAP syntax description suitable for publication in subschema subentries. ( 1.3.6.1.1.16.1 DESC 'UUID' ) 2.2. 'uuidMatch' Matching Rule The 'uuidMatch' matching rule compares an asserted UUID with a stored UUID for equality. Its semantics are the same as the 'octetStringMatch' [X.520][RFC4517] matching rule. The rule differs from 'octetStringMatch' in that the assertion value is encoded using the UUID string representation instead of the normal OCTET STRING string representation. The following is an LDAP matching rule description suitable for publication in subschema subentries. ( 1.3.6.1.1.16.2 NAME 'uuidMatch' SYNTAX 1.3.6.1.1.16.1 ) 2.3. 'uuidOrderingMatch' Matching Rule The 'uuidOrderingMatch' matching rule compares an asserted UUID with a stored UUID for ordering. Its semantics are the same as the 'octetStringOrderingMatch' [X.520][RFC4517] matching rule. The rule differs from 'octetStringOrderingMatch' in that the assertion value is encoded using the UUID string representation instead of the normal OCTET STRING string representation. Zeilenga Standards Track [Page 3] RFC 4530 LDAP entryUUID June 2006 The following is an LDAP matching rule description suitable for publication in subschema subentries. ( 1.3.6.1.1.16.3 NAME 'uuidOrderingMatch' SYNTAX 1.3.6.1.1.16.1 ) Note that not all UUID variants have a defined ordering; and even where it does, servers are not obligated to assign UUIDs in any particular order. This matching rule is provided for completeness. 2.4. 'entryUUID' Attribute The 'entryUUID' operational attribute provides the Universally Unique Identifier (UUID) assigned to the entry. The following is an LDAP attribute type description suitable for publication in subschema subentries. ( 1.3.6.1.1.16.4 NAME 'entryUUID' DESC 'UUID of the entry' EQUALITY uuidMatch ORDERING uuidOrderingMatch SYNTAX 1.3.6.1.1.16.1 SINGLE-VALUE NO-USER-MODIFICATION USAGE directoryOperation ) Servers SHALL generate and assign a new UUID to each entry upon its addition to the directory and provide that UUID as the value of the 'entryUUID' operational attribute. An entry's UUID is immutable. UUID are to be generated in accordance with Section 4 of [RFC4122]. In particular, servers MUST ensure that each generated UUID is unique in space and time. 3. Security Considerations An entry's relative distinguish name (RDN) is composed from attribute values of the entry, which are commonly descriptive of the object the entry represents. Although deployers are encouraged to use naming attributes whose values are widely disclosable [RFC4514], entries are often named using information that cannot be disclosed to all parties. As UUIDs do not contain any descriptive information of the object they identify, UUIDs may be used to identify a particular entry without disclosure of its contents. General UUID security considerations [RFC4122] apply. Zeilenga Standards Track [Page 4] RFC 4530 LDAP entryUUID June 2006 General LDAP security considerations [RFC4510] apply. 4. IANA Considerations The IANA has registered the LDAP values [RFC4520] specified in this document. 4.1. Object Identifier Registration Subject: Request for LDAP OID Registration Person & email address to contact for further information: Kurt Zeilenga <kurt@OpenLDAP.org> Specification: RFC 4530 Author/Change Controller: IESG Comments: Identifies the UUID schema elements 4.2. UUID Syntax Registration Subject: Request for LDAP Syntax Registration Object Identifier: 1.3.6.1.1.16.1 Description: UUID Person & email address to contact for further information: Kurt Zeilenga <kurt@OpenLDAP.org> Specification: RFC 4530 Author/Change Controller: IESG Comments: Identifies the UUID syntax 4.3. 'uuidMatch' Descriptor Registration Subject: Request for LDAP Descriptor Registration Descriptor (short name): uuidMatch Object Identifier: 1.3.6.1.1.16.2 Person & email address to contact for further information: Kurt Zeilenga <kurt@OpenLDAP.org> Usage: Matching Rule Specification: RFC 4530 Author/Change Controller: IESG 4.4. 'uuidOrderingMatch' Descriptor Registration Subject: Request for LDAP Descriptor Registration Descriptor (short name): uuidOrderingMatch Object Identifier: 1.3.6.1.1.16.3 Person & email address to contact for further information: Kurt Zeilenga <kurt@OpenLDAP.org> Usage: Matching Rule Zeilenga Standards Track [Page 5] RFC 4530 LDAP entryUUID June 2006 Specification: RFC 4530 Author/Change Controller: IESG 4.5. 'entryUUID' Descriptor Registration The IANA has registered the LDAP 'entryUUID' descriptor. Subject: Request for LDAP Descriptor Registration Descriptor (short name): entryUUID Object Identifier: 1.3.6.1.1.16.4 Person & email address to contact for further information: Kurt Zeilenga <kurt@OpenLDAP.org> Usage: Attribute Type Specification: RFC 4530 Author/Change Controller: IESG 5. Acknowledgements This document is based upon discussions in the LDAP Update and Duplication Protocols (LDUP) WG. Members of the LDAP Directorate provided review. 6. References 6.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally Unique IDentifier (UUID) URN Namespace", RFC 4122, July 2005. [RFC4510] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006. [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006. [RFC4517] Legg, S., Ed., "Lightweight Directory Access Protocol (LDAP): Syntaxes and Matching Rules", RFC 4517, June 2006. [ASCII] Coded Character Set--7-bit American Standard Code for Information Interchange, ANSI X3.4-1986. Zeilenga Standards Track [Page 6] RFC 4530 LDAP entryUUID June 2006 [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(2002) (also ISO/IEC 8824-1:2002). 6.2. Informative References [RFC4514] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names", RFC 4514, June 2006. [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006. Author's Address Kurt D. Zeilenga OpenLDAP Foundation EMail: Kurt@OpenLDAP.org Zeilenga Standards Track [Page 7] RFC 4530 LDAP entryUUID June 2006 Full Copyright Statement Copyright (C) The Internet Society (2006). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Zeilenga Standards Track [Page 8] PK '�c\(��E� � " doc/alt-openldap11-devel/rfc/INDEXnu �[��� This is an index of RFC contained in this directory: rfc2079.txt X.500 Attribute Type and an Object Class to Hold URIs (PS) rfc2247.txt Using Domains in LDAP DNs (PS) rfc2293.txt Tables and Subtrees in the X.500 Directory (PS) rfc2294.txt O/R Address hierarchy in the X.500 DIT (PS) rfc2307.txt LDAP Network Information Services Schema (E) rfc2377.txt LDAP Naming Plan (I) rfc2589.txt LDAPv3: Dynamic Directory Services Extensions (PS) rfc2649.txt LDAPv3 Operational Signatures (E) rfc2696.txt LDAP Simple Paged Result Control (I) rfc2713.txt LDAP Java schema (I) rfc2714.txt LDAP CORBA schema (I) rfc2798.txt LDAP inetOrgPerson schema (I) rfc2849.txt LDIFv1 (PS) rfc2891.txt LDAPv3: Server Side Sorting of Search Results (PS) rfc2926.txt LDAP: Conversion of LDAP Schemas to and from SLP Templates (I) rfc3045.txt Storing Vendor Information in the LDAP root DSE (I) rfc3062.txt LDAP Password Modify Extended Operation (PS) rfc3088.txt OpenLDAP Root Service (E) rfc3112.txt LDAP Authentication Password Schema (I) rfc3296.txt Named Subordinate References in LDAP (PS) rfc3663.txt Domain Administrative Data in LDAP (E) rfc3671.txt Collective Attributes in LDAP (PS) rfc3672.txt Subentries in LDAP (PS) rfc3673.txt LDAPv3: All Operational Attributes (PS) rfc3687.txt LDAP Component Matching Rules (PS) rfc3698.txt LDAP: Additional Matching Rules (PS) rfc3703.txt LDAP: Schema for Policy Core (PS) rfc3712.txt LDAP: Schema for Printer Services (I) rfc3727.txt ASN.1 Module for LDAP Component Matching Rules (PS) rfc3829.txt LDAP Authorization Identity Controls (I) rfc3866.txt Language Tag and Ranges in LDAP (PS) rfc3876.txt Returning Matched Values with LDAP (PS) rfc3909.txt LDAP Cancel Operation (PS) rfc3928.txt LDAP Client Update Protocol (PS) rfc4013.txt SASLprep (PS) rfc4370.txt LDAP Proxied Authorization Control (PS) rfc4373.txt LBURP (I) rfc4403.txt LDAP Schema for UDDI (I) rfc4510.txt LDAP Technical Specification Roadmap (PS) rfc4511.txt LDAP: The Protocol (PS) rfc4512.txt LDAP: Directory Information Models (PS) rfc4513.txt LDAP: Authentication Methods and Security Mechanisms (PS) rfc4514.txt LDAP: DN (PS) rfc4515.txt LDAP: Search Filters (PS) rfc4516.txt LDAP: URL (PS) rfc4517.txt LDAP: Syntaxes and Matching Rules (PS) rfc4518.txt LDAP: Internationalized String Preparation (PS) rfc4519.txt LDAP: User Applications Schema (PS) rfc4520.txt IANA Considerations for LDAP (BCP) rfc4521.txt Considerations for LDAP Extensions (BCP) rfc4522.txt LDAP: Binary Encoding Option (PS) rfc4523.txt LDAP: X.509 Certificate Schema (PS) rfc4524.txt LDAP: COSINE Schema (PS) rfc4525.txt LDAP: Modify-Increment Extension (I) rfc4526.txt LDAP: Absolute True and False Filters (PS) rfc4527.txt LDAP: Read Entry Controls (PS) rfc4528.txt LDAP: Assertion Control (PS) rfc4529.txt LDAP: Requesting Attributes by Object Class rfc4530.txt LDAP: entryUUID (PS) rfc4531.txt LDAP Turn Operation (E) rfc4532.txt LDAP Who am I? Operation (PS) rfc4533.txt LDAP Content Sync Operation (E) rfc5020.txt LDAP 'entryDN' operational attribute (PS) rfc5805.txt LDAP Transactions (E) Legend: STD Standard DS Draft Standard PS Proposed Standard I Information E Experimental FYI For Your Information BCP Best Common Practice Please see http://www.rfc-editor.org/ for up-to-date status information. $OpenLDAP$ PK (�c\� � E� E� ( doc/alt-openldap11-devel/rfc/rfc2926.txtnu �[��� Network Working Group J. Kempf Request for Comments: 2926 Sun Microsystems, Inc. Category: Informational R. Moats Coreon, Inc. P. St. Pierre Sun Microsystems, Inc. September 2000 Conversion of LDAP Schemas to and from SLP Templates Status of this Memo This memo provides information for the Internet community. It does not specify an Internet standard of any kind. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2000). All Rights Reserved. Abstract This document describes a procedure for mapping between Service Location Protocol (SLP) service advertisements and lightweight directory access protocol (LDAP) descriptions of services. The document covers two aspects of the mapping. One aspect is mapping between SLP service type templates and LDAP directory schema. Because the SLP service type template grammar is relatively simple, mapping from service type templates to LDAP types is straightforward. Mapping in the other direction is straightforward if the attributes are restricted to use just a few of the syntaxes defined in RFC 2252. If arbitrary ASN.1 types occur in the schema, then the mapping is more complex and may even be impossible. The second aspect is representation of service information in an LDAP directory. The recommended representation simplifies interoperability with SLP by allowing SLP directory agents to backend into LDAP directory servers. The resulting system allows service advertisements to propagate easily between SLP and LDAP. Kempf, et al. Informational [Page 1] RFC 2926 Conversion of LDAP Schemas September 2000 Table of Contents 1.0 Introduction ................................................ 2 2.0 Mapping SLP Templates to LDAP Schema ........................ 3 2.1 Mapping from SLP Attribute Types to LDAP Attribute Types .. 8 2.1.1 Integer ............................................... 8 2.1.2 String ................................................ 8 2.1.3 Boolean ............................................... 9 2.1.4 Opaque ................................................ 9 2.2 Keyword Attributes ........................................ 9 2.3 Template Flags ............................................ 9 2.3.1 Multi-valued .......................................... 9 2.3.2 Optional .............................................. 10 2.3.3 Literal ............................................... 10 2.3.4 Explicit Matching ..................................... 10 2.4 Default and Allowed Value Lists ........................... 10 2.5 Descriptive Text .......................................... 11 2.6 Generating LDAP Attribute OIDs ............................ 11 2.7 Example ................................................... 11 3.0 Attribute Name Conflicts .................................... 15 4.0 Mapping from Schema to Templates ............................ 15 4.1 Mapping LDAP Attribute Types to SLP Attribute Types ....... 16 4.2 Mapping ASN.1 Types to SLP Types .......................... 17 4.2.1 Integer ............................................... 18 4.2.2 Boolean ............................................... 18 4.2.3 Enumerated ............................................ 18 4.2.4 Object Identifier ..................................... 19 4.2.5 Octet String .......................................... 19 4.2.6 Real .................................................. 19 4.3 Example ASN.1 Schema ...................................... 19 5.0 Representing SLP Service Advertisements in an LDAP DIT ...... 22 6.0 Internationalization Considerations ......................... 24 7.0 Security Considerations ..................................... 24 8.0 References .................................................. 25 9.0 Authors' Addresses .......................................... 26 10.0 Full Copyright Statement ................................... 27 1.0 Introduction SLP templates [1] are intended to create a simple encoding of the syntactic and semantic conventions for individual service types, their attributes, and conventions. They can easily be generated, transmitted, read by humans and parsed by programs, as it is a string based syntax with required comments. Directory schemas serve to formalize directory entry structures for use with LDAP [2] These directories serve to store information about many types of entities. Network services are an example of one such entity. Kempf, et al. Informational [Page 2] RFC 2926 Conversion of LDAP Schemas September 2000 Interoperability between SLP and LDAP is important so clients using one protocol derive benefit from services registered through the other. In addition, LDAP directory servers can serve as the backend for SLP directory agents (DAs) if interoperability is possible In order to facilitate interoperability, this document creates mappings between the SLP template grammar and LDAP directory schema, and establishes some conventions for representing service advertisements in LDAP directories. The goal of the translation is to allow SLPv2 queries (which are syntactically and semantically equivalent to LDAPv3 string queries [7]) to be submitted to an LDAP directory server by an SLP DA backended into LDAP without extensive processing by the DA. The simple notation and syntactic/semantic attribute capabilities of SLP templates map easily into directory schemas, and are easily converted into directory schemas, even by automated means. The reverse may not be true. If the LDAP schema contains attributes with unrecognized or complex syntaxes, the translation may be difficult or impossible. If, however, the LDAP schema only uses a few of the common syntaxes defined in RFC 2252 [8], then the translation is more straightforward. In addition, to foster complete bidirectionality, the mapping must follow a very specific representation in its DESC attributes. This document outlines the correct mappings for SLP templates into the syntactic representation specified for LDAP directory schema by RFC 2252 [8]. This syntax is a subset of the ASN.1/BER described in the X.209 specification [9], and is used by the LDAPv3 [2] directory schema. Likewise, rules and guidelines are proposed to facilitate consistent mapping of ASN.1 based schemas to be translated in the SLP template grammar. Finally, a proposal for a representation of service advertisements in LDAP directory services is made that facilitates SLP interoperability. Except when used as elements in the definition of LDAP schemas, 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 [16]. 2.0 Mapping SLP Templates to LDAP Schema We define the following abstract object class as the parent class for all services. Any specific service type is a subclass of this, with its own attributes: Kempf, et al. Informational [Page 3] RFC 2926 Conversion of LDAP Schemas September 2000 ( 1.3.6.1.4.1.6252.2.27.6.2.1 NAME 'slpService' DESC 'parent superclass for SLP services' ABSTRACT SUP top MUST ( template-major-version-number $ template-minor-version-number $ description $ template-url-syntax $ service-advert-service-type $ service-advert-scopes ) MAY ( service-advert-url-authenticator $ service-advert-attribute-authenticator ) ) The attributes correspond to various parts of the SLP service template and SLP service advertisement. SLP service type templates begin with four definitions that set the context of the template: template-type - This defines the service type of the template. The service type can be a simple service type, like "service:ftp", an abstract service type, like "service:printer" or a concrete service type, like "service:printer:lpr". The type name can additionally include a naming authority, for example "service:printer.sun:local". The name that appears in this field omits the "service:" prefix. template-version - A string containing a major and minor version number, separated by a period. template-description - A block of human readable text describing what the service type does. template-url-syntax - An ABNF [6] grammar describing the service type specific part of the service URL. The SLP template-type definition is used as the name of the LDAP object class for the template, a subclass of the "slpService" class, together with the "service" prefix to indicate that the name is for a service. In the translating service type name, colons and the period separating the naming authority are converted into hyphens. If the template defines an SLP concrete type, the concrete type name is used; the abstract type name is never used. For example, the template for "service:printer:lpr" is translated into an LDAP object class called "service-printer-lpr". Furthermore, if the type name contains a naming authority, the naming authority name must be Kempf, et al. Informational [Page 4] RFC 2926 Conversion of LDAP Schemas September 2000 included. For example, the service type name "service:printer.sun:local" becomes "service-printer-sun-local". The LDAP object class is always "STRUCTURAL". The template-version definition is partitioned into two attributes, template-major-version-number and template-minor-version-number. The LDAP definition for these attributes is: ( 1.3.6.1.4.1.6252.2.27.6.1.1 NAME 'template-major-version-number' DESC 'The major version number of the service type template' EQUALITY integerMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) ( 1.3.6.1.4.1.6252.2.27.6.1.2 NAME 'template-minor-version-number' DESC 'The minor version number of the service type template' EQUALITY integerMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) The template-url-syntax definition in the SLP template is described by the following attribute: ( 1.3.6.1.4.1.6252.2.27.6.1.3 NAME 'template-url-syntax' DESC 'An ABNF grammar describing the service type specific part of the service URL' EQUALITY caseExactIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 SINGLE-VALUE ) The template-description attribute is translated into the X.520 standard attribute "description" [3]. We further establish the convention that SLP template characteristics that can't be translated into LDAP are inserted into the DESC field of the object class definition. The items are separated by empty lines (consisting of two "LINE FEED" characters), are preceded by a LINE FEED character, and are tagged at the beginning of the line to indicate what they represent. This allows the template to be reconstructed from the schema by properly parsing the comments. Kempf, et al. Informational [Page 5] RFC 2926 Conversion of LDAP Schemas September 2000 The bulk of an SLP template consists of attribute definitions. There are four items in an SLP template attribute definition that need to be mapped into LDAP: Attribute Name - Since SLPv2 attribute names are defined to be compatible with LDAPv3, SLP attributes map directly into LDAP attributes with no change. Similarly, LDAP attributes map directly to SLP attributes. Attribute Type - The SLP attribute type is mapped into the LDAP attribute type. Attribute Flags - The SLP attribute flags are mapped into characteristics of the LDAP attribute definition, or into the DESC field if no equivalent LDAP attribute definition characteristic occurs. Default and Allowed Values - These must be handled by the client or a DA enabled to handle templates, as in SLP. For reference, however, they should be included in the DESC field of the LDAP attribute definition. Descriptive Text - The SLP template descriptive text should be mapped into the DESC field. We discuss mapping of types, flags, default and allowed values, and descriptive text in the subsections below. OIDs for SLP template conversion schema elements are standardized under the enterprise number of SrvLoc.Org (6252) [18]. For purposes of representing an SLP entry, we also define two standardized LDAP syntaxes and attributes with standardized OIDs. ( 1.3.6.1.4.1.6252.2.27.6.2.2 DESC 'SLP Service Type' ) Defines the syntax for the service type name. The syntax is defined in the BNF for the service URL in RFC 2609 Section 2.1 [1]. ( 1.3.6.1.4.1.6252.2.27.6.2.3 DESC 'SLP Scope' ) Defines the syntax for the scope name. The syntax is defined in the BNF for scope names in RFC 2608 Section 6.4.1 [5]. Kempf, et al. Informational [Page 6] RFC 2926 Conversion of LDAP Schemas September 2000 ( 1.3.6.1.4.1.6252.2.27.6.1.4 NAME 'service-advert-service-type' DESC 'The service type of the service advertisement, including the "service:" prefix.' EQUALITY caseExactIA5Match SYNTAX 1.3.6.1.4.1.6252.2.27.6.2.2 SINGLE-VALUE ) Defines an attribute for the service type name. ( 1.3.6.1.4.1.6252.2.27.6.1.5 NAME 'service-advert-scopes' DESC 'A list of scopes for a service advertisement.' EQUALITY caseExactIA5Match SYNTAX 1.3.6.1.4.1.6252.2.27.6.2.3 ) Defines a multivalued attribute for the scopes. Searches for abstract types can be made with an LDAP query that wildcards the concrete type. For example, a search for all service advertisements of the printer abstract type can be made with the following query: (service-advert-service-type=service:printer:*) SLP specifies that service URLs and attribute lists can be accompanied by a structured authenticator consisting of a digital signature and information necessary to verify the signature. A syntax and two standardized SLP attributes are defined for this purpose: ( 1.3.6.1.4.1.6252.2.27.6.2.3 DESC 'SLP Authenticator') The syntax of an SLP authenticator is the bytes of the authenticator in network byte order, see RFC 2608, Section 9.2 [5]. ( 1.3.6.1.4.1.6252.2.27.6.1.6 NAME 'service-advert-url-authenticator' DESC 'The authenticator for the URL, null if none.' SYNTAX 1.3.6.1.4.1.6252.2.27.6.2.3 SINGLE-VALUE ) This attribute contains the SLP URL authenticator, as defined in RFC 2608, Section 9.2 [5]. Kempf, et al. Informational [Page 7] RFC 2926 Conversion of LDAP Schemas September 2000 ( 1.3.6.1.4.1.6252.2.27.6.1.7 NAME 'service-advert-attribute-authenticator' DESC 'The authenticator for the attribute list, null if none.' SYNTAX 1.3.6.1.4.1.6252.2.27.6.2.3 SINGLE_VALUE ) This attribute contains the SLP attribute authenticator, as defined in RFC 2608, Section 9.2 [5]. 2.1 Mapping from SLP Attribute Types to LDAP Attribute Types We define the mapping from SLP attribute types to LDAP as follows: SLP Type ASN.1 Type LDAP Type --------------------------------------------------- Integer INTEGER INTEGER String DirectoryString Directory String Boolean BOOLEAN Boolean Opaque OCTET STRING Octet String Keyword (N/A) IA5 String The following subsections discuss further details of the mapping. 2.1.1 Integer SLP integers compare as integers when performing a query. LDAP integers behave similarly. Consequently, the mapping from the SLP integer type to LDAP is INTEGER, with the integerMatch matching rule. 2.1.2 String SLP strings are encoded as described in the SLP protocol specification [5]. All value strings are considered case insensitive for matching operations. SLP strings are not null terminated and are encoded in UTF-8. SLP strings are mapped to the LDAP Directory String type. The Directory String type exactly matches the SLP string type, i.e. it is a non-null terminated UTF-8 string. The caseIgnoreMatch equality rule, caseIgnoreOrderingMatch ordering rule, and caseIgnoreSubstringsMatch substring rule are used for comparing string attribute values. Kempf, et al. Informational [Page 8] RFC 2926 Conversion of LDAP Schemas September 2000 2.1.3 Boolean Boolean attributes may have one of two possible values. In SLP, these values are represented as strings, TRUE and FALSE. In SLP's string encoding of a boolean value, case does not matter. The SLP Boolean type maps directly into an LDAP BOOLEAN. The caseIgnoreMatch rule is used for equality matching. 2.1.4 Opaque SLP attribute values of type Opaque are represented as OCTET STRING in LDAP, and the octetStringMatch matching rule is used to compare them. 2.2 Keyword Attributes SLP service type templates allow the definition of keyword attributes. Keyword attributes are attributes whose only characteristic is their presence. Keyword attributes have no flag information, nor any default or allowed values (since, by definition, they have no values). ASN.1 has no concept of keyword attributes. Keyword attributes are translated into a "May" clause in the ASN.1 class definition for the service type. If the keyword attribute is present, then its value is of no consequence, but for consistency we make it simply the NUL character, "\00". 2.3 Template Flags SLP template flags can be handled as described in the following subsections. 2.3.1 Multi-valued Multi-valued attributes are defined in an SLP template using the one value. All values for a given attribute must be of the same type. LDAP attribute definitions require that a single valued attribute include the SINGLE-VALUE tag if the attribute is single valued. Otherwise, the attribute is assumed to be multivalued by default. Kempf, et al. Informational [Page 9] RFC 2926 Conversion of LDAP Schemas September 2000 2.3.2 Optional SLP uses the 'O' flag to indicate an attribute may or may not be present. These optional attributes are defined using the "May" clause in the ASN.1 definition class definition for the service type. All other attributes must be defined as a "Must". 2.3.3 Literal ASN.1 does not have a mechanism to indicate that the values of an attribute may not be translated from one language to another, since ASN.1 schema are not typically translated. This flag is dropped when translating a template, but presence of the flag should be noted in the DESC field. It should be placed on a separate line and tagged with "Literal:" so the template can be reconstructed from the schema. 2.3.4 Explicit Matching The SLP template syntax uses a flag of 'X' to indicate that an attribute must be present in order for the query to be properly satisfied. There is no provision for requiring that particular attributes be in a query. Consequently, this flag is dropped when translating a template, but presence of the flag should be noted in the DESC field. It should be placed on a separate line and tagged with "Explicit:" so the template can be reconstructed from the schema. 2.4 Default and Allowed Value Lists The SLP template grammar provides the capability to define default and allowed values for an attribute. The SLP protocol does not enforce these restrictions on registered attributes, however. The default and allowed values may be used by client side applications, or alternatively it may also be used by DAs to initialize registrations having no attributes and to limit attribute values to the template allowed values. LDAP servers also do not support default and allowed values on attributes. Therefore, enforcement of default and allowed values in SLP templates is left up to the clients or a DA, if the DA is backending into LDAP. The default and allowed values should be included in the DESC field. The comments should be placed on separate lines and labeled with the "Default:" and "Allowed:" tags to allow reconstruction of the template. Kempf, et al. Informational [Page 10] RFC 2926 Conversion of LDAP Schemas September 2000 2.5 Descriptive Text The descriptive text associated with an attribute definition should be included in the DESC field. It should start on a separate line and begin with the "Description:" tag. 2.6 Generating LDAP Attribute OIDs LDAP attributes require an OID. In general, there is no a priori way that an algorithm can be defined for generating OIDs, because it will depend on the conventions used by the organization developing the template. In some cases, an organization's procedure for generating OIDs may be regular enough that a template developer can algorithmically generate OIDs off of an assigned root. Whatever means is used, the template developer should assure that unique OIDs are assigned to each SLP attribute that is translated into an LDAP attribute. 2.7 Example The template included below is a hypothetical abstract printer service template, similar to that described in [10]. template-type = printer template-version = 0.0 template-description = The printer service template describes the attributes supported by network printing devices. Devices may be either directly connected to a network, or connected to a printer spooler that understands the a network queuing protocol such as IPP, lpr or the Salutation Architecture. template-url-syntax = ;The URL syntax is specific to the printing protocol being ;employed description = STRING # This attribute is a free form string that can contain any # site-specific descriptive information about this printer. printer-security-mechanisms-supported = STRING L M none # This attribute indicates the security mechanisms supported tls, ssl, http-basic, http-digest, none Kempf, et al. Informational [Page 11] RFC 2926 Conversion of LDAP Schemas September 2000 printer-operator = STRING O L M # A person, or persons responsible for maintaining a # printer on a day-to-day basis, including such tasks # as filling empty media trays, emptying full output # trays, replacing toner cartridges, clearing simple # paper jams, etc. printer-location-address = STRING O # Physical/Postal address for this device. Useful for # nailing down a group of printers in a very large corporate # network. For example: 960 Main Street, San Jose, CA 95130 printer-priority-queue = BOOLEAN O FALSE # TRUE indicates this printer or print queue is a priority # queuing device. printer-number-up = INTEGER O 1 # This job attribute specifies the number of source # page-images to impose upon a single side of an instance # of a selected medium. 1, 2, 4 printer-paper-output = STRING M L O standard # This attribute describes the mode in which pages output # are arranged. standard, noncollated sort, collated sort, stack, unknown We assume that the concrete type "service:printer:lpr" for printers that speak the LPR protocol [4] has the following template definition: template-type = printer:lpr template-version = 0.0 template-description = The printer:lpr service template describes the attributes supported by network printing devices that speak the LPR protocol. No new attributes are included. template-url-syntax = queue queue = ;The queue name, see RFC 1179. Kempf, et al. Informational [Page 12] RFC 2926 Conversion of LDAP Schemas September 2000 The LDAP class definition for the "service:printer:lpr" concrete service type is translated as follows: ( ---place the assigned OID here--- NAME 'service-printer-lpr' DESC 'Description: The printer:lpr service template describes the attributes supported by network printing devices that speak the LPR protocol. No new attributes are included. URL Syntax: queue queue = ;The queue name, see RFC 1179.' SUP slpService MUST ( description $ security-mechanisms-supported $ labeledURI) MAY ( operator $ location-address $ priority-queue $ number-up $ paper-output) ) The attribute definitions are translated as follows: ( ---place the assigned OID here--- NAME 'printer-security-mechanisms-supported' DESC 'Description: This attribute indicates the security mechanisms supported. Default: value Allowed: tls, ssl, http-basic, http-digest, none Literal:' EQUALITY caseIgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) ( ---place the assigned OID here--- NAME 'printer-operator' DESC 'Description: A person, or persons responsible for maintaining a printer on a day-to-day basis, including such tasks as filling empty media trays, emptying full output trays, replacing toner cartridges, clearing simple paper jams, etc. Kempf, et al. Informational [Page 13] RFC 2926 Conversion of LDAP Schemas September 2000 Literal:' EQUALITY caseIgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) ( --place the assigned OID here--- NAME 'printer-location-address' DESC 'Description Physical/Postal address for this device. Useful for nailing down a group of printers in a very large corporate network. For example: 960 Main Street, San Jose, CA 95130.' EQUALITY caseIgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) ( ---place the assigned OID here--- NAME 'printer-priority-queue' DESC 'Description: TRUE indicates this printer or print queue is a priority queuing device.' EQUALITY booleanMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 SINGLE-VALUE ) ( ---place the assigned OID here--- NAME 'printer-number-up' DESC 'Description: This job attribute specifies the number of source page-images to impose upon a single side of an instance of a selected medium. This attribute is INTEGER. Default: 1 Allowed: 1, 2, 3, 4' EQUALITY integerMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) Kempf, et al. Informational [Page 14] RFC 2926 Conversion of LDAP Schemas September 2000 ( ---place the assigned OID here--- NAME 'printer-paper-output' DESC 'Description: This attribute describes the mode in which pages output are arranged. Default value is standard. Default: standard Allowed: standard, noncollated sort, collated sort, stack, unknown. Literal:' EQUALITY caseIgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) 3.0 Attribute Name Conflicts LDAP has a flat name space, and attribute names and OIDs must be unique in a directory server. In order to avoid name conflicts in the translation of SLP templates to LDAP schemas, template developers may want to consider prepending the name of the service type to the attribute. Postprocessing attribute names to make them unique when translated is not possible, because it would require the DA to rewrite queries before submitting them to the directory server. In addition, developers should use standard LDAP attributes when such attributes are available. In the above example template, the abstract type name "printer" is prepended to attributes to avoid conflicts. The standard "description" attribute defined by X.520 [3] is used to translate the template description attribute. 4.0 Mapping from Schema to Templates The reverse mapping from LDAP schema to SLP service type templates requires dealing with both LDAP and ASN.1 data types. RFC 2252 defines 33 attribute syntaxes that should be supported by LDAP directory servers. These syntaxes are defined using BNF for strings or using ASN.1 for binary valued attributes defined by X.520. Mapping of the LDAP data types into SLP template types is fairly straightforward, but mapping arbitrary ASN.1 data types is somewhat more complicated and requires encoding the ASN.1 data type into a string. To a certain extent, this masks the ASN.1 data type because it becomes impossible to distinguish between a native string having Kempf, et al. Informational [Page 15] RFC 2926 Conversion of LDAP Schemas September 2000 content equivalent to an encoded ASN.1 string. However, inclusion of the ASN.1 data type in the comment provides additional information should a reverse transformation from SLP to ASN.1 be required. The following subsections deal with both LDAP and ASN.1 attribute data type mappings. 4.1 Mapping LDAP Attribute Syntaxes to SLP Attribute Types The following table contains the mappings for LDAP syntaxes to SLP data types: LDAP Type SLP Type -------------------------------------------------------- ACI Item NA Access Point NA Attribute Type Description NA Audio Opaque Binary ASN.1 escape Bit String String Boolean Boolean Certificate Opaque Certificate List Opaque Certificate Pair Opaque Country String String DN String Data Quality Syntax NA Delivery Method NA Directory String String DIT Content Rule Description NA DIT Structure Rule Description NA DL Submit Permission NA DSA Quality Syntax NA Enhanced Guide NA Facsimile Telephone Number String Fax Opaque Generalized Time String Guide NA IA5 String String INTEGER Integer JPEG Opaque LDAP Syntax Description NA LDAP Schema Definition NA LDAP Schema Description NA Master and Shadow Access Points NA Matching Rule Description NA Matching Rule Use Description NA Mail Preference NA Kempf, et al. Informational [Page 16] RFC 2926 Conversion of LDAP Schemas September 2000 MHS OR Address String Modify Rights NA Name and Optional UID NA Name Form Description NA Numeric String String Object Class Description NA Octet String Opaque OID String Other Mailbox String Postal Address String Protocol Information NA Presentation Address String Printable String String Substring Assertion NA Subtree Specification NA Supplier Information NA Supplier or Consumer NA Supplier And Consumer NA Supported Algorithm NA DSE Type NA Telephone Number String Teletex Terminal Identifier String Telex Number String UTC Time String 4.2 Mapping ASN.1 Types to SLP Types ASN.1 employs a much richer set of data types than provided by SLP. The table below show the mapping of selected ASN.1 data type to their nearest SLP equivalent. Because of the complexity and flexibility of ASN.1, a complete list cannot be provided. As sample of some ASN.1 encodings and their mappings to SLP: ASN.1 type SLP type ----------------------------------------- INTEGER Integer BOOLEAN Boolean ENUMERATED String OBJECT IDENTIFIER String OCTET STRING Opaque REAL String Data types that do not map directly to SLP data types should be defined as either a String, or as Opaque. ASN.1 types that may only contain valid characters for Strings, as defined in X.680 [9] should be encoded as strings. ASN.1 types such as GraphicString that change their character set encoding in part way through a value should not Kempf, et al. Informational [Page 17] RFC 2926 Conversion of LDAP Schemas September 2000 be encoded as strings, however, If such types are required, the SLP Opaque type should be used. In either case, the first line of the help text is used to indicate the original ASN.1 data type. The following subsections describe how to convert from the ASN.1 BER [9] to the SLP template for the different types in the table above. 4.2.1 Integer Both SLP templates and ASN.1 support Integers, so there is a one to one mapping between an SLP Integer attribute and an ASN.1 Integer attribute. Details on the encoding of integers is summarized in the SLP template to ASN.1 section above. 4.2.2 Boolean Boolean values are supported by both SLP and ASN.1, though on wire encodings differ. X.680 [9] specifies zero and non-zero encoding for booleans, where SLP encodes booleans using the strings TRUE and FALSE. In general, most LDAP servers will use the LDAP Boolean type (which is a string), so again the ASN.1 type should be recorded in the comment or it will be lost. 4.2.3 Enumerated SLP templates support the concept of enumerations through the listing of allowed values in the attribute definition. These enumerations are not strictly binding on clients or DAs, but they are similar to the ASN.1 definition of enumerations. BER encodes the ASN.1 enumeration by passing the number of the element's position in the enumeration. This requires both sides to have knowledge of the specific enumeration prior to decoding an enumeration's value. SLP provides no specific support for transmitting enumerations. They are simply String types. Information on the ASN.1 type and ASN.1 encoding of the enumeration values is recorded in the comment. Example: color-supported = STRING M none # ASN.1: Enumeration. # ASN.1 Mapping: none = 0, highlight = 1, three color = 2, # four color = 4, monochromatic = 5 #This attribute specifies whether the Printer supports # color and, if so, what type. none,highlight,three color,four color,monochromatic Kempf, et al. Informational [Page 18] RFC 2926 Conversion of LDAP Schemas September 2000 4.2.4 Object Identifier Object identifiers(OIDs) are commonly used in the ASN.1 world to identify object and attributes. OIDs are a numerical representation of an element's place in the naming hierarchy. Each element at a particular level of a hierarchy has a unique number assigned within that level of the hierarchy. A sample OID would be the naming tree for SNMP MIBs: iso(1) org(3) dod(6) internet(1) mgmt(2) mib(1) would be written as the string "1.3.6.1.2.1". Because this representation reduces down to a string of dot separated numbers, this maps easily to the SLP String type. The help text for this element should indicate it is an ASN.1 OID identifier = STRING # ASN.1: OID # The object identifier for this SNMP agent. 4.2.5 Octet String An ASN.1 octet string should be mapped to an Opaque in an SLP template. An octet string is a sequence of bytes, whereas an Opaque is a a string that encodes a sequence of bytes. Again, the ASN.1 type is lost unless recorded in the comment. 4.2.6 Real There is no direct mapping between floating point numbers and any SLP data types. Attributes having the ASN.1 type of Real are mapped to SLP type String. Comments are added to the attribute help text indicating the value was originally an ASN.1 real. For example: weight = STRING # ASN.1: Real # The objects weight in pounds. 4.3 Example ASN.1 Schema The following is an example schema for an exported filesystem. The section presents it as in ASN.1 and the following section shows the SLP template translation. The template translation does not capture the actual attribute format for the Set type, that would be done in the LDAP client software making the translation. Note that even though the class definition does not conform with the previously defined conventions for SLP classes, the schema can still be translated into an SLP template. The syntax used in this example follows Kempf, et al. Informational [Page 19] RFC 2926 Conversion of LDAP Schemas September 2000 -- Abstraction of a fstab entry (a "mount"). -- These lookups would likely be performed by an -- an automounter type application. mount OBJECT-CLASS ::= { SUBCLASS OF { top } MUST CONTAIN { mountHost | mountDirectory | mountType } MAY CONTAIN { mountOption | mountDumpFrequency | mountPassNo } ID { <oid1> } } - The mount host. mountHost ATTRIBUTE ::= { WITH SYNTAX caseIgnoreString EQUALITY MATCHING RULE caseIgnoreMatch SINGLE VALUE ID { <oid2> } } - The file system to mount. mountDirectory ATTRIBUTE ::= { WITH SYNTAX caseIgnoreString EQUALITY MATCHING RULE caseIgnoreMatch SINGLE VALUE ID { <oid3> } } - The type of file system being mounted. mountType ATTRIBUTE ::= { WITH SYNTAX INTEGER { ufs(1), hsfs(2), nfs(3), rfs(4) } EQUALITY MATCHING RULE integerMatch SINGLE VALUE ID { <oid4> } } Kempf, et al. Informational [Page 20] RFC 2926 Conversion of LDAP Schemas September 2000 - Options for the mount operation. mountOption ATTRIBUTE ::= { WITH SYNTAX caseIgnoreString EQUALITY MATCHING RULE caseIgnoreString ID { <oid5> } } - How often to dump the file system. mountDumpFrequency ATTRIBUTE :: = { WITH SYNTAX INTEGER (0..9) EQUALITY MATCHING RULE integerMatch SINGLE VALUE ID { <oid6> } } - Boot time mount pass number. mountPassNo ATTRIBUTE ::= { WITH SYNTAX INTEGER EQUALITY MATCHING RULE integerMatch SINGLE VALUE ID { <oid7> } } The translated SLP template is: template-type = mount template-version = 1.0 template-description = "Describes a remote filesystem access protocol" template-url-syntax = filesystem = 1*[ DIGIT / ALPHA ] urlpath = "/" filesystem mountHost = STRING L # ASN.1: Case Ignore String, Single Value # The mount host mountDirectory = STRING L # ASN.1: Case Ignore String, Single Value # The filesystem to mount Kempf, et al. Informational [Page 21] RFC 2926 Conversion of LDAP Schemas September 2000 mountType = STRING L ufs # ASN.1: Enumeration, Single Value # ASN.1 Mapping: ufs = 1, hsfs = 2, nfs = 3, rfs = 4 # The type of the filesystem being mounted ufs, hsfs, nfs, rfs mountOption = STRING M O L # ASN.1: Case Ignore String # mount options for this filesystem mountDumpFrequency = INTEGER O 0 # ASN.1: Integer Range, Single Value # How often to dump this filesystem 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 mountPassNo = INTEGER O # ASN.1: Integer, Single Value # Boot time mount pass number 5.0 Representing SLP Service Advertisements in an LDAP DIT In addition to translating between SLP templates and LDAP schema, another area requiring compatibility is the representation of SLP service advertisements in an LDAP DIT. A standardized representation for service information allows SLP DAs to store service advertisements in LDAP, and for LDAP clients to query the DIT for those services. Similarly, if LDAP clients represent service information in the same form, SLP clients can benefit from interoperability. A service advertisement contains the service URL in a 'labeledURI' attribute [11]. The labeledURI attribute in a service advertisement should only contain the service URL for the service, with no additional label. It is recommended that the labeledURI be used as the RDN for the service object in the DIT. Although service advertisements can appear anywhere within the DIT, it is recommended that all services be stored under a single common point, or root node, to facilitate searching in a domain. This allows a client to search for all of advertisements of a particular service type, say, for all printers. The recommended parent entry is one named "ou=service" below the entry which is the representation of the domain, as described in RFC 2247. Kempf, et al. Informational [Page 22] RFC 2926 Conversion of LDAP Schemas September 2000 For example, a printer service with labeledURI of "service:lpr://printsrv/queue1" in the domain foobar.com advertised in the LDAP server that holds the entry "dc=foobar,dc=com" tree has the following DN: "labeledURI=service:lpr://printsrv/queue1, ou=service, dc=foobar, dc=com" While this leads to a flat space of service storage, since SLP uses search filters from LDAP for searches, these filters can be used for one-level searches from the root node. The following example illustrates how an advertisement having a simple service type is represented. The advertisement (in conceptual form) for a printer is: Service Type: service:lpr://printsrv/queue1 Scopes: eng,corp Attributes: description = A general printer for all to use. security-mechanisms-supported = none Authentication: none The RDN of the object is labeledURI=service:lpr://printsrv/queue1, and the following LDAP search filter will return this object, along with any others of the service type "service:lpr" that match the other attributes: (&(service-advert-service-type=service:lpr) (service-advert-scopes=eng) (service-advert-scopes=corp) (description=A general printer for all to use.) (security-mechanisms-supported=none)) Service advertisements in SLP also have a lease time associated with them. In LDAP servers that support the extensions for dynamic directory services [12], the service advertisement entry objectClass should be extended with the dynamicObject class. This allows the service advertisement to time out within the LDAP directory server. If the LDAP directory server does not support the dynamic directory services extension, then advertisement lease timeouts must be handled by the SLP agent. While the service advertisement schema outlined in this section is primarily for SLP DAs that use LDAP as a backing store, if LDAP agents register services using the same format, complete interoperability with SLP is achieved. Kempf, et al. Informational [Page 23] RFC 2926 Conversion of LDAP Schemas September 2000 6.0 Internationalization Considerations SLP specifies that an RFC 1766 [13] language code accompanies every service advertisement. Language codes for service advertisements in LDAP must be represented according to RFC 2596 [14]. RFC 2596 prohibits language codes in DNs, and specifies that a directory server which does not support language codes must treat an attribute with a language code as an unrecognized attributes. According to RFC 2596, language codes are appended to attribute names with a semicolon (";"). For example, the following attribute/value pair is in the German locale: (address;lang-de=44 Bahnhofstrasse, 2365 Weibstadt, Deutschland) An attribute with a language tag in a specific locale is considered a separate attribute from attributes in other locales. If the service advertisement is in the default SLP locale ("en", no dialect), then the language code need not be appended to the attribute name. SLP queries in locales other than the default need not be rewritten to include language tags before being submitted to the directory server. RFC 2596 specifies that all entries that match are returned, including those with language tags, without requiring the language tags to be explicitly present in the query. The SLP DA can then postprocess the result to select the entries from the required locale. 7.0 Security Considerations SLP authenticators are stored with the service advertisement in the DIT, as discussed in Section~7ef{slpdit}. LDAP clients need to use LDAP authentication [15] to assure that they are connecting with a secure server. In particular, SLP DAs that use LDAP as a back end store and that implement SLP authentication MUST use LDAP authentication to assure that the LDAP entries for their service registrations are secure. Acknowledgements Many thanks are due to Mark Wahl whose detailed and insightful comments were instrumental in helping improve the technical accuracy of this document with respect to LDAP. Kempf, et al. Informational [Page 24] RFC 2926 Conversion of LDAP Schemas September 2000 8.0 References [1] Guttman, E., Perkins, C. and J. Kempf, "Service Templates and service: Schemes", RFC 2609, April 1999. [2] Wahl, W., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [3] International Telecommunications Union. The Directory:Selected Attribute Types. ITU Recommendation X.520. August, 1997. [4] McLaughlin, L., "Line Printer Daemon Protocol, RFC 1179, August 1990. [5] Guttman, E., Perkins, C., Veizades, J. and M. Day, "Service Location Protocol Version 2", RFC 2608, April 1999. [6] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, November 1997. [7] Howes, T., "The String Representation of LDAP Search Filters", RFC 2254, December 1997. [8] Wahl, W., Coulbeck, A., Howe, T. and S. Kille, "Lightweight Directory Access Protocol (v3): Attribute Syntax Definition", RFC 2252, December 1997. [9] ITU-T Rec. X.680. Abstract Syntax Notation One (ASN.1) - Specification of Basic Notation. 1994. [10] Fleming, P., Jones, K., Lewis, H., and McDonald, I., "Internet Printing Protocol (IPP): LDAP Schema for Printer Services", Work in Progress. [11] Smith, M., "Definition of an X.500 Attribute Type and an Object Class to Hold Uniform Resource Identifiers (URIs)", RFC 2079, January 1997. [12] Yaacovi, Y., Wahl, M. and T. Genovese, "Lightweight Directory Access Protocol (v3): Extensions for Dynamic Directory Services", RFC 2589, May 1999. [13] Alvestrand, H., "Tags for the Identification of Languages", RFC 1766, December 1997. [14] Wahl, M. and T. Howes, "Use of Language Codes in LDAP", RFC 2596, May 1999. Kempf, et al. Informational [Page 25] RFC 2926 Conversion of LDAP Schemas September 2000 [15] Wahl, M., Alvestrand, H., Hodges, J. and R. Morgan, "Authentication Methods for LDAP", RFC 2829, May 2000. [16] Bradner, S., "Key Words for Use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [17] Dubuisson, O. ASN.1: Communication between Heterogeneous Systems. OSS Nokalva, 2000. [18] http://www.srvloc.org 9.0 Authors' Addresses James Kempf Sun Microsystems 901 San Antonio Avenue Palo Alto, CA 94303 USA Phone: +1 650 786-5890 EMail: james.kempf@sun.com Ryan Moats Coreon, Inc. 15621 Drexel Circle Omaha, NE, 68135 USA EMail: rmoats@coreon.net Pete St. Pierre Sun Microsystems 901 San Antonio Avenue Palo Alto, CA 94303 USA Phone: +1 415 786-5790 EMail: Pete.StPierre@Eng.Sun.COM Kempf, et al. Informational [Page 26] RFC 2926 Conversion of LDAP Schemas September 2000 10. 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. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Kempf, et al. Informational [Page 27] PK (�c\?l� �! �! ( doc/alt-openldap11-devel/rfc/rfc5020.txtnu �[��� Network Working Group K. Zeilenga Request for Comments: 5020 Isode Limited Category: Standards Track August 2007 The Lightweight Directory Access Protocol (LDAP) entryDN Operational Attribute Status of This Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The IETF Trust (2007). Abstract This document describes the Lightweight Directory Access Protocol (LDAP) / X.500 'entryDN' operational attribute. The attribute provides a copy of the entry's distinguished name for use in attribute value assertions. Zeilenga Standards Track [Page 1] RFC 5020 LDAP entryDN August 2007 1. Background and Intended Use In X.500 Directory Services [X.501], such as those accessible using the Lightweight Directory Access Protocol (LDAP) [RFC4510], an entry is identified by its distinguished name (DN) [RFC4512]. However, as an entry's DN is not an attribute of the entry, it is not possible to perform attribute value assertions [RFC4511] against it. This document describes the 'entryDN' operational attribute which holds a copy of the entry's distinguished name. This attribute may be used in search filters. For instance, searching the subtree <dc=example,dc=com> with the filter: (entryDN:componentFilterMatch:=or:{ item:{ component "3", rule rdnMatch, value "ou=A" }, item:{ component "3", rule rdnMatch, value "ou=B" } }) would return entries in the subtree <ou=A,dc=example,dc=com> and entries in subtree <ou=B,dc=example,dc=com>, but would not return any other entries in the subtree <dc=example,dc=com>. In the above paragraph, DNs are presented using the string representation defined in [RFC4514], and the example search filter is presented using the string representation defined in [RFC4515] with whitespace (line breaks and indentation) added to improve readability. The 'componentFilterMatch' and 'rdnMatch' rules are specified in [RFC3687]. Schema definitions are provided using LDAP description formats [RFC4512]. Definitions provided here are formatted (line wrapped) for readability. 2. 'entryDN' Operational Attribute The 'entryDN' operational attribute provides a copy of the entry's current DN. The following is an LDAP attribute type description suitable for publication in subschema subentries. ( 1.3.6.1.1.20 NAME 'entryDN' DESC 'DN of the entry' EQUALITY distinguishedNameMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 SINGLE-VALUE NO-USER-MODIFICATION USAGE directoryOperation ) Zeilenga Standards Track [Page 2] RFC 5020 LDAP entryDN August 2007 Note that the DN of the entry cannot be modified through this attribute. 3. Security Considerations As this attribute only provides an additional mechanism to access an entry's DN, the introduction of this attribute is not believed to introduce new security considerations. 4. IANA Considerations 4.1. Object Identifier Registration IANA has registered (upon Standards Action) an LDAP Object Identifier [RFC4520] for use in this document. Subject: Request for LDAP OID Registration Person & email address to contact for further information: Kurt Zeilenga <Kurt.Zeilenga@Isode.COM> Specification: RFC 5020 Author/Change Controller: IESG Comments: Identifies the 'entryDN' attribute type 4.2. 'entryDN' Descriptor Registration IANA has registered (upon Standards Action) the LDAP 'entryDN' descriptor [RFC4520]. Subject: Request for LDAP Descriptor Registration Descriptor (short name): entryDN Object Identifier: 1.3.6.1.1.20 Person & email address to contact for further information: Kurt Zeilenga <Kurt.Zeilenga@Isode.COM> Usage: Attribute Type Specification: RFC 5020 Author/Change Controller: IESG Zeilenga Standards Track [Page 3] RFC 5020 LDAP entryDN August 2007 5. References 5.1. Normative References [RFC4510] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006. [RFC4512] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006. [X.501] International Telecommunication Union - Telecommunication Standardization Sector, "The Directory -- Models," X.501(1993) (also ISO/IEC 9594-2:1994). 5.2. Informative References [RFC3687] Legg, S., "Lightweight Directory Access Protocol (LDAP) and X.500 Component Matching Rules", RFC 3687, February 2004. [RFC4511] Sermersheim, J., Ed., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006. [RFC4514] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names", RFC 4514, June 2006. [RFC4515] Smith, M., Ed., and T. Howes, "Lightweight Directory Access Protocol (LDAP): String Representation of Search Filters", RFC 4515, June 2006. [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006. Author's Address Kurt D. Zeilenga Isode Limited EMail: Kurt.Zeilenga@Isode.COM Zeilenga Standards Track [Page 4] RFC 5020 LDAP entryDN August 2007 Full Copyright Statement Copyright (C) The IETF Trust (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, THE IETF TRUST 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@ietf.org. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Zeilenga Standards Track [Page 5] PK (�c\�A�\ { { ( doc/alt-openldap11-devel/rfc/rfc3866.txtnu �[��� Network Working Group K. Zeilenga, Ed. Request for Comments: 3866 OpenLDAP Foundation Obsoletes: 2596 July 2004 Category: Standards Track Language Tags and Ranges in the Lightweight Directory Access Protocol (LDAP) Status of this Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2004). Abstract It is often desirable to be able to indicate the natural language associated with values held in a directory and to be able to query the directory for values which fulfill the user's language needs. This document details the use of Language Tags and Ranges in the Lightweight Directory Access Protocol (LDAP). 1. Background and Intended Use The Lightweight Directory Access Protocol (LDAP) [RFC3377] provides a means for clients to interrogate and modify information stored in a distributed directory system. The information in the directory is maintained as attributes of entries. Most of these attributes have syntaxes which are human-readable strings, and it is desirable to be able to indicate the natural language associated with attribute values. This document describes how language tags and ranges [RFC3066] are carried in LDAP and are to be interpreted by LDAP implementations. All LDAP implementations MUST be prepared to accept language tags and ranges. 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]. Zeilenga Standards Track [Page 1] RFC 3866 Language Tags and Ranges in LDAP July 2004 This document replaces RFC 2596. Appendix A summaries changes made since RFC 2596. Appendix B discusses differences from X.500(1997) "contexts" mechanism. Appendix A and B are provided for informational purposes only. The remainder of this section provides a summary of Language Tags, Language Ranges, and Attribute Descriptions. 1.1. Language Tags Section 2 of BCP 47 [RFC3066] describes the language tag format which is used in LDAP. Briefly, it is a string of [ASCII] letters and hyphens. Examples include "fr", "en-US" and "ja-JP". Language tags are case insensitive. That is, the language tag "en-us" is the same as "EN-US". Section 2 of this document details use of language tags in LDAP. 1.2. Language Ranges Section 2.5 of BCP 47 [RFC3066] describes the language ranges. Language ranges are used to specify sets of language tags. A language range matches a language tag if it is exactly equal to the tag, or if it is exactly equal to a prefix of the tag such that the first character following the prefix is "-". That is, the language range "de" matches the language tags "de" and "de-CH" but not "den". The special language range "*" matches all language tags. Due to attribute description option naming restrictions in LDAP, this document defines a different language range syntax. However, the semantics of language ranges in LDAP are consistent with BCP 47. Section 3 of this document details use of language ranges in LDAP. 1.3. Attribute Descriptions This section provides an overview of attribute descriptions in LDAP. LDAP attributes and attribute descriptions are defined in [RFC2251]. An attribute consists of a type, a set of zero or more associated tagging options, and a set of one or more values. The type and the options are combined into the AttributeDescription. Zeilenga Standards Track [Page 2] RFC 3866 Language Tags and Ranges in LDAP July 2004 AttributeDescriptions can also contain options which are not part of the attribute, but indicate some other function (such as range assertion or transfer encoding). An AttributeDescription with one or more tagging options is a direct subtype of each AttributeDescription of the same type with all but one of the tagging options. If the AttributeDescription's type is a direct subtype of some other type, then the AttributeDescription is also a direct subtype of the AttributeDescription which consists of the supertype and all of the tagging options. That is, "CN;x-bar;x-foo" is a direct subtype of "CN;x-bar", "CN;x-foo", and "name;x-bar;x-foo". Note that "CN" is a subtype of "name". 2. Use of Language Tags in LDAP This section describes how LDAP implementations MUST interpret language tags in performing operations. Servers which support storing attributes with language tag options in the Directory Information Tree (DIT) SHOULD allow any attribute type it recognizes that has the Directory String, IA5 String, or other textual string syntaxes to have language tag options associated with it. Servers MAY allow language options to be associated with other attributes types. Clients SHOULD NOT assume servers are capable of storing attributes with language tags in the directory. Implementations MUST NOT otherwise interpret the structure of the tag when comparing two tags, and MUST treat them simply as strings of characters. Implementations MUST allow any arbitrary string which conforms to the syntax defined in BCP 47 [RFC3066] to be used as a language tag. 2.1. Language Tag Options A language tag option associates a natural language with values of an attribute. An attribute description may contain multiple language tag options. An entry may contain multiple attributes with same attribute type but different combinations of language tag (and other) options. A language tag option conforms to the following ABNF [RFC2234]: language-tag-option = "lang-" Language-Tag Zeilenga Standards Track [Page 3] RFC 3866 Language Tags and Ranges in LDAP July 2004 where the Language-Tag production is as defined in BCP 47 [RFC3066]. This production and those it imports from [RFC2234] are provided here for convenience: Language-Tag = Primary-subtag *( "-" Subtag ) Primary-subtag = 1*8ALPHA Subtag = 1*8(ALPHA / DIGIT) ALPHA = %x41-5A / %x61-7A ; A-Z / a-z DIGIT = %x30-39 ; 0-9 A language tag option is a tagging option. A language tag option has no effect on the syntax of the attribute's values nor their transfer encoding. Examples of valid AttributeDescription: givenName;lang-en-US CN;lang-ja SN;lang-de;lang-gem-PFL O;lang-i-klingon;x-foobar description;x-foobar CN Notes: The last two have no language tag options. The x-foobar option is fictious and used for example purposes. 2.2. Search Filter If language tag options are present in an AttributeDescription in an assertion, then for each entry within scope, the values of each attribute whose AttributeDescription consists of the same attribute type or its subtypes and contains each of the presented (and possibly other) options is to be matched. Thus, for example, a filter of an equality match of type "name;lang-en-US" and assertion value "Billy Ray", against the following directory entry: dn: SN=Ray,DC=example,DC=com objectClass: person DOES NOT MATCH (wrong type) objectClass: extensibleObject DOES NOT MATCH (wrong type) name;lang-en-US: Billy Ray MATCHES name;lang-en-US: Billy Bob DOES NOT MATCH (wrong value) CN;lang-en-US: Billy Ray MATCHES Zeilenga Standards Track [Page 4] RFC 3866 Language Tags and Ranges in LDAP July 2004 CN;lang-en-US;x-foobar: Billy Ray MATCHES CN;lang-en;x-foobar: Billy Ray DOES NOT MATCH (differing lang-) CN;x-foobar: Billy Ray DOES NOT MATCH (no lang-) name: Billy Ray DOES NOT MATCH (no lang-) SN;lang-en-GB;lang-en-US: Billy Ray MATCHES SN: Ray DOES NOT MATCH (no lang-, wrong value) Note that "CN" and "SN" are subtypes of "name". It is noted that providing a language tag option in a search filter AttributeDescription will filter out desirable values where the tag does not match exactly. For example, the filter (name;lang-en=Billy Ray) does NOT match the attribute "name;lang-en-US: Billy Ray". If the server does not support storing attributes with language tag options in the DIT, then any assertion which includes a language tag option will not match as such it is an unrecognized attribute type. No error would be returned because of this; a presence assertion would evaluate to FALSE and all other assertions to Undefined. If no options are specified in the assertion, then only the base attribute type and the assertion value need match the value in the directory. Thus, for example, a filter of an equality match of type "name" and assertion value "Billy Ray", against the following directory entry: dn: SN=Ray,DC=example,DC=com objectClass: person DOES NOT MATCH (wrong type) objectClass: extensibleObject DOES NOT MATCH (wrong type) name;lang-en-US: Billy Ray MATCHES name;lang-en-US: Billy Bob DOES NOT MATCH (wrong value) CN;lang-en-US;x-foobar: Billy Ray MATCHES CN;lang-en;x-foobar: Billy Ray MATCHES CN;x-foobar: Billy Ray MATCHES name: Billy Ray MATCHES SN;lang-en-GB;lang-en-US: Billy Ray MATCHES SN: Ray DOES NOT MATCH (wrong value) 2.3. Requested Attributes in Search Clients can provide language tag options in each AttributeDescription in the requested attribute list in a search request. If language tag options are provided in an attribute description, then only attributes in a directory entry whose attribute descriptions have the same attribute type or its subtype and contains Zeilenga Standards Track [Page 5] RFC 3866 Language Tags and Ranges in LDAP July 2004 each of the presented (and possibly other) language tag options are to be returned. Thus if a client requests just the attribute "name;lang-en", the server would return "name;lang-en" and "CN;lang-en;lang-ja" but not "SN" nor "name;lang-fr". Clients can provide in the attribute list multiple AttributeDescriptions which have the same base attribute type but different options. For example, a client could provide both "name;lang-en" and "name;lang-fr", and this would permit an attribute with either language tag option to be returned. Note there would be no need to provide both "name" and "name;lang-en" since all subtypes of name would match "name". If a server does not support storing attributes with language tag options in the DIT, then any attribute descriptions in the list which include language tag options are to be ignored, just as if they were unknown attribute types. If a request is made specifying all attributes or an attribute is requested without providing a language tag option, then all attribute values regardless of their language tag option are returned. For example, if the client requests a "description" attribute, and a matching entry contains the following attributes: objectClass: top objectClass: organization O: Software GmbH description: software products description;lang-en: software products description;lang-de: Softwareprodukte The server would return: description: software products description;lang-en: software products description;lang-de: Softwareprodukte 2.4. Compare Language tag options can be present in an AttributeDescription used in a compare request AttributeValueAssertion. This is to be treated by servers the same as the use of language tag options in a search filter with an equality match, as described in Section 2.2. If there is no attribute in the entry with the same attribute type or its subtype and contains each of the presented (or possibly other) language tag options, the noSuchAttributeType error will be returned. Zeilenga Standards Track [Page 6] RFC 3866 Language Tags and Ranges in LDAP July 2004 Thus, for example, a compare request of type "name" and assertion value "Johann", against an entry containing the following attributes: objectClass: top objectClass: person givenName;lang-de-DE: Johann CN: Johann Sibelius SN: Sibelius would cause the server to return compareTrue. However, if the client issued a compare request of type "name;lang-de" and assertion value "Johann" against the above entry, the request would fail with the noSuchAttributeType error. If the server does not support storing attributes with language tag options in the DIT, then any comparison which includes a language tag option will always fail to locate an attribute, and noSuchAttributeType will be returned. 2.5. Add Operation Clients can provide language options in AttributeDescription in attributes of a new entry to be created. A client can provide multiple attributes with the same attribute type and value, so long as each attribute has a different set of language tag options. For example, the following is a valid request: dn: CN=John Smith,DC=example,DC=com objectClass: residentialPerson CN: John Smith CN;lang-en: John Smith SN: Smith SN;lang-en: Smith streetAddress: 1 University Street streetAddress;lang-en-US: 1 University Street streetAddress;lang-fr: 1 rue Universite houseIdentifier;lang-fr: 9e etage If a server does not support storing language tag options with attribute values in the DIT, then it MUST treat an AttributeDescription with a language tag option as an unrecognized attribute. If the server forbids the addition of unrecognized attributes then it MUST fail the add request with an appropriate result code. Zeilenga Standards Track [Page 7] RFC 3866 Language Tags and Ranges in LDAP July 2004 2.6. Modify Operation A client can provide language tag options in an AttributeDescription as part of a modification element in the modify operation. Attribute types and language tag options MUST match exactly against values stored in the directory. For example, if the modification is a "delete", then if the stored values to be deleted have language tag options, then those language tag options MUST be provided in the modify operation, and if the stored values to be deleted do not have any language tag option, then no language tag option is to be provided. If the server does not support storing language tag options with attribute values in the DIT, then it MUST treat an AttributeDescription with a language tag option as an unrecognized attribute, and MUST fail the request with an appropriate result code. 3. Use of Language Ranges in LDAP Since the publication of RFC 2596, it has become apparent that there is a need to provide a mechanism for a client to request attributes based upon set of language tag options whose tags all begin with the same sequence of language sub-tags. AttributeDescriptions containing language range options are intended to be used in attribute value assertions, search attribute lists, and other places where the client desires to provide an attribute description matching of a range of language tags associated with attributes. A language range option conforms to the following ABNF [RFC2234]: language-range-option = "lang-" [ Language-Tag "-" ] where the Language-Tag production is as defined in BCP 47 [RFC3066]. This production and those it imports from [RFC2234] are provided in Section 2.1 for convenience. A language range option matches a language tag option if the language range option less the trailing "-" matches exactly the language tag or if the language range option (including the trailing "-") matches a prefix of the language tag option. Note that the language range option "lang-" matches all language tag options. Zeilenga Standards Track [Page 8] RFC 3866 Language Tags and Ranges in LDAP July 2004 Examples of valid AttributeDescription containing language range options: givenName;lang-en- CN;lang- SN;lang-de-;lang-gem- O;lang-x-;x-foobar A language range option is not a tagging option. Attributes cannot be stored with language range options. Any attempt to add or update an attribute description with a language range option SHALL be treated as an undefined attribute type and result in an error. A language range option has no effect on the transfer encoding nor on the syntax of the attribute values. Servers SHOULD support assertion of language ranges for any attribute type which they allow to be stored with language tags. 3.1. Search Filter If a language range option is present in an AttributeDescription in an assertion, then for each entry within scope, the values of each attribute whose AttributeDescription consists of the same attribute type or its subtypes and contains a language tag option matching the language range option are to be returned. Thus, for example, a filter of an equality match of type "name;lang-en-" and assertion value "Billy Ray", against the following directory entry: dn: SN=Ray,DC=example,DC=com objectClass: person DOES NOT MATCH (wrong type) objectClass: extensibleObject DOES NOT MATCH (wrong type) name;lang-en-US: Billy Ray MATCHES name;lang-en-US: Billy Bob DOES NOT MATCH (wrong value) CN;lang-en-US: Billy Ray MATCHES CN;lang-en-US;x-foobar: Billy Ray MATCHES CN;lang-en;x-foobar: Billy Ray MATCHES CN;x-foobar: Billy Ray DOES NOT MATCH (no lang-) name: Billy Ray DOES NOT MATCH (no lang-) SN;lang-en-GB;lang-en-US: Billy Ray MATCHES SN: Ray DOES NOT MATCH (no lang-, wrong value) Note that "CN" and "SN" are subtypes of "name". Zeilenga Standards Track [Page 9] RFC 3866 Language Tags and Ranges in LDAP July 2004 If the server does not support storing attributes with language tag options in the DIT, then any assertion which includes a language range option will not match as it is an unrecognized attribute type. No error would be returned because of this; a presence filter would evaluate to FALSE and all other assertions to Undefined. 3.2. Requested Attributes in Search Clients can provide language range options in each AttributeDescription in the requested attribute list in a search request. If a language range option is provided in an attribute description, then only attributes in a directory entry whose attribute descriptions have the same attribute type or its subtype and a language tag option matching the provided language range option are to be returned. Thus if a client requests just the attribute "name;lang-en-", the server would return "name;lang-en-US" and "CN;lang-en;lang-ja" but not "SN" nor "name;lang-fr". Clients can provide in the attribute list multiple AttributeDescriptions which have the same base attribute type but different options. For example a client could provide both "name;lang-en-" and "name;lang-fr-", and this would permit an attribute whose type was name or subtype of name and with a language tag option matching either language range option to be returned. If a server does not support storing attributes with language tag options in the DIT, then any attribute descriptions in the list which include language range options are to be ignored, just as if they were unknown attribute types. 3.3. Compare Language range options can be present in an AttributeDescription used in a compare request AttributeValueAssertion. This is to be treated by servers the same as the use of language range options in a search filter with an equality match, as described in Section 3.1. If there is no attribute in the entry with the same subtype and a matching language tag option, the noSuchAttributeType error will be returned. Thus, for example, a compare request of type "name;lang-" and assertion value "Johann", against the entry with the following attributes: Zeilenga Standards Track [Page 10] RFC 3866 Language Tags and Ranges in LDAP July 2004 objectClass: top objectClass: person givenName;lang-de-DE: Johann CN: Johann Sibelius SN: Sibelius will cause the server to return compareTrue. (Note that the language range option "lang-" matches any language tag option.) However, if the client issued a compare request of type "name;lang-de" and assertion value "Sibelius" against the above entry, the request would fail with the noSuchAttributeType error. If the server does not support storing attributes with language tag options in the DIT, then any comparison which includes a language range option will always fail to locate an attribute, and noSuchAttributeType will be returned. 4. Discovering Language Option Support A server SHOULD indicate that it supports storing attributes with language tag options in the DIT by publishing 1.3.6.1.4.1.4203.1.5.4 as a value of the root DSE. A server SHOULD indicate that it supports language range matching of attributes with language tag options stored in the DIT by publishing 1.3.6.1.4.1.4203.1.5.5 as a value of the "supportedFeatures" [RFC3674] attribute in the root DSE. A server MAY restrict use of language tag options to a subset of the attribute types it recognizes. This document does not define a mechanism for determining which subset of attribute types can be used with language tag options. 5. Interoperability with Non-supporting Implementations Implementators of this specification should take care that their use of language tag options does not impede proper function of implementations which do not support language tags. Per RFC 2251, "an AttributeDescription with one or more options is treated as a subtype of the attribute type without any options." A non-supporting server will treat an AttributeDescription with any language tag options as an unrecognized attribute type. A non- supporting client will either do the same, or will treat the AttributeDescription as it would any other unknown subtype. Typically, non-supporting clients simply ignore unrecognized subtypes (and unrecognized attribute types) of attributes they request. Zeilenga Standards Track [Page 11] RFC 3866 Language Tags and Ranges in LDAP July 2004 To ensure proper function of non-supporting clients, supporting clients SHOULD ensure that entries they populate with tagged values are also populated with non-tagged values. Additionally, supporting clients SHOULD be prepared to handle entries which are not populated with tagged values. 6. Security Considerations Language tags and range options are used solely to indicate the native language of values and in querying the directory for values which fulfill the user's language needed. These options are not known to raise specific security considerations. However, the reader should consider general directory security issues detailed in the LDAP technical specification [RFC3377]. 7. IANA Considerations Registration of these protocol mechanisms [RFC3383] has been completed by the IANA. Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: 1.3.6.1.4.1.4203.1.5.4 Description: Language Tag Options Object Identifier: 1.3.6.1.4.1.4203.1.5.5 Description: Language Range Options Person & email address to contact for further information: Kurt Zeilenga <kurt@openldap.org> Usage: Feature Specification: RFC 3866 Author/Change Controller: IESG Comments: none These OIDs were assigned [ASSIGN] by OpenLDAP Foundation, under its IANA-assigned private enterprise allocation [PRIVATE], for use in this specification. 8. Acknowledgments This document is a revision of RFC 2596 by Mark Wahl and Tim Howes. RFC 2596 was a product of the IETF ASID and LDAPEXT working groups. This document also borrows from a number of IETF documents including BCP 47 by H. Alvestrand. Zeilenga Standards Track [Page 12] RFC 3866 Language Tags and Ranges in LDAP July 2004 9. References 9.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, November 1997. [RFC2251] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [RFC3066] Alvestrand, H., "Tags for the Identification of Languages", BCP 47, RFC 3066, January 2001. [RFC3377] Hodges, J. and R. Morgan, "Lightweight Directory Access Protocol (v3): Technical Specification", RFC 3377, September 2002. [RFC3674] Zeilenga, K., "Feature Discovery in Lightweight Directory Access Protocol (LDAP)", RFC 3674, December 2003. [ASCII] Coded Character Set--7-bit American Standard Code for Information Interchange, ANSI X3.4-1986. 9.2. Informative References [X.501] International Telecommunication Union - Telecommunication Standardization Sector, "The Directory -- Models," X.501(1997). [RFC3383] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 3383, September 2002. [ASSIGN] OpenLDAP Foundation, "OpenLDAP OID Delegations", http://www.openldap.org/foundation/oid-delegate.txt. [PRIVATE] IANA, "Private Enterprise Numbers", http://www.iana.org/assignments/enterprise-numbers. Zeilenga Standards Track [Page 13] RFC 3866 Language Tags and Ranges in LDAP July 2004 Appendix A. Differences from RFC 2596 This document adds support for language ranges, provides a mechanism that a client can use to discover whether a server supports language tags and ranges, and clarifies how attributes with multiple language tags are to be treated. This document is a significant rewrite of RFC 2596. Appendix B. Differences from X.500(1997) X.500(1997) [X.501] defines a different mechanism, contexts, as the means of representing language tags (codes). This section summarizes the major differences in approach. a) An X.500 operation which has specified a language code on a value matches a value in the directory without a language code. b) LDAP references BCP 47 [RFC3066], which allows for IANA registration of new tags as well as unregistered tags. c) LDAP supports language ranges (new in this revision). d) LDAP does not allow language tags (and ranges) in distinguished names. e) X.500 describes subschema administration procedures to allow language codes to be associated with particular attributes types. Editor's Address Kurt D. Zeilenga OpenLDAP Foundation EMail: Kurt@OpenLDAP.org Zeilenga Standards Track [Page 14] RFC 3866 Language Tags and Ranges in LDAP July 2004 Full Copyright Statement Copyright (C) The Internet Society (2004). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Zeilenga Standards Track [Page 15] PK (�c\��PB0 B0 ( doc/alt-openldap11-devel/rfc/rfc4510.txtnu �[��� Network Working Group K. Zeilenga, Ed. Request for Comments: 4510 OpenLDAP Foundation Obsoletes: 2251, 2252, 2253, 2254, 2255, June 2006 2256, 2829, 2830, 3377, 3771 Category: Standards Track Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map Status of This Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2006). Abstract The Lightweight Directory Access Protocol (LDAP) is an Internet protocol for accessing distributed directory services that act in accordance with X.500 data and service models. This document provides a road map of the LDAP Technical Specification. 1. The LDAP Technical Specification The technical specification detailing version 3 of the Lightweight Directory Access Protocol (LDAP), an Internet Protocol, consists of this document and the following documents: LDAP: The Protocol [RFC4511] LDAP: Directory Information Models [RFC4512] LDAP: Authentication Methods and Security Mechanisms [RFC4513] LDAP: String Representation of Distinguished Names [RFC4514] LDAP: String Representation of Search Filters [RFC4515] LDAP: Uniform Resource Locator [RFC4516] LDAP: Syntaxes and Matching Rules [RFC4517] LDAP: Internationalized String Preparation [RFC4518] LDAP: Schema for User Applications [RFC4519] Zeilenga Standards Track [Page 1] RFC 4510 LDAP: TS Road Map June 2006 The terms "LDAP" and "LDAPv3" are commonly used to refer informally to the protocol specified by this technical specification. The LDAP suite, as defined here, should be formally identified in other documents by a normative reference to this document. LDAP is an extensible protocol. Extensions to LDAP may be specified in other documents. Nomenclature denoting such combinations of LDAP-plus-extensions is not defined by this document but may be defined in some future document(s). Extensions are expected to be truly optional. Considerations for the LDAP extensions described in BCP 118, RFC 4521 [RFC4521] fully apply to this revision of the LDAP Technical Specification. IANA (Internet Assigned Numbers Authority) considerations for LDAP described in BCP 64, RFC 4520 [RFC4520] apply fully to this revision of the LDAP technical specification. 1.1. Conventions 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]. 2. Relationship to X.500 This technical specification defines LDAP in terms of [X.500] as an X.500 access mechanism. An LDAP server MUST act in accordance with the X.500 (1993) series of International Telecommunication Union - Telecommunication Standardization (ITU-T) Recommendations when providing the service. However, it is not required that an LDAP server make use of any X.500 protocols in providing this service. For example, LDAP can be mapped onto any other directory system so long as the X.500 data and service models [X.501][X.511], as used in LDAP, are not violated in the LDAP interface. This technical specification explicitly incorporates portions of X.500(93). Later revisions of X.500 do not automatically apply to this technical specification. 3. Relationship to Obsolete Specifications This technical specification, as defined in Section 1, obsoletes entirely the previously defined LDAP technical specification defined in RFC 3377 (and consisting of RFCs 2251-2256, 2829, 2830, 3771, and 3377 itself). The technical specification was significantly reorganized. Zeilenga Standards Track [Page 2] RFC 4510 LDAP: TS Road Map June 2006 This document replaces RFC 3377 as well as Section 3.3 of RFC 2251. [RFC4512] replaces portions of RFC 2251, RFC 2252, and RFC 2256. [RFC4511] replaces the majority RFC 2251, portions of RFC 2252, and all of RFC 3771. [RFC4513] replaces RFC 2829, RFC 2830, and portions of RFC 2251. [RFC4517] replaces the majority of RFC 2252 and portions of RFC 2256. [RFC4519] replaces the majority of RFC 2256. [RFC4514] replaces RFC 2253. [RFC4515] replaces RFC 2254. [RFC4516] replaces RFC 2255. [RFC4518] is new to this revision of the LDAP technical specification. Each document of this specification contains appendices summarizing changes to all sections of the specifications they replace. Appendix A.1 of this document details changes made to RFC 3377. Appendix A.2 of this document details changes made to Section 3.3 of RFC 2251. Additionally, portions of this technical specification update and/or replace a number of other documents not listed above. These relationships are discussed in the documents detailing these portions of this technical specification. 4. Security Considerations LDAP security considerations are discussed in each document comprising the technical specification. 5. Acknowledgements This document is based largely on RFC 3377 by J. Hodges and R. Morgan, a product of the LDAPBIS and LDAPEXT Working Groups. The document also borrows from RFC 2251 by M. Wahl, T. Howes, and S. Kille, a product of the ASID Working Group. This document is a product of the IETF LDAPBIS Working Group. Zeilenga Standards Track [Page 3] RFC 4510 LDAP: TS Road Map June 2006 6. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC4511] Sermersheim, J., Ed., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006. [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006. [RFC4513] Harrison, R., Ed., "Lightweight Directory Access Protocol (LDAP): Authentication Methods and Security Mechanisms", RFC 4513, June 2006. [RFC4514] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names", RFC 4514, June 2006. [RFC4515] Smith, M., Ed. and T. Howes, "Lightweight Directory Access Protocol (LDAP): String Representation of Search Filters", RFC 4515, June 2006. [RFC4516] Smith, M., Ed. and T. Howes, "Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator", RFC 4516, June 2006. [RFC4517] Legg, S., Ed., "Lightweight Directory Access Protocol (LDAP): Syntaxes and Matching Rules", RFC 4517, June 2006. [RFC4518] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Internationalized String Preparation", RFC 4518, June 2006. [RFC4519] Sciberras, A., Ed., "Lightweight Directory Access Protocol (LDAP): Schema for User Applications", RFC 4519, June 2006. [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006. [RFC4521] Zeilenga, K., "Considerations for LDAP Extensions", BCP 118, RFC 4521, June 2006. Zeilenga Standards Track [Page 4] RFC 4510 LDAP: TS Road Map June 2006 [X.500] International Telecommunication Union - Telecommunication Standardization Sector, "The Directory -- Overview of concepts, models and services", X.500(1993) (also ISO/IEC 9594-1:1994). [X.501] International Telecommunication Union - Telecommunication Standardization Sector, "The Directory -- Models", X.501(1993) (also ISO/IEC 9594- 2:1994). [X.511] International Telecommunication Union - Telecommunication Standardization Sector, "The Directory: Abstract Service Definition", X.511(1993) (also ISO/IEC 9594-3:1993). Zeilenga Standards Track [Page 5] RFC 4510 LDAP: TS Road Map June 2006 Appendix A. Changes to Previous Documents This appendix outlines changes this document makes relative to the documents it replaces (in whole or in part). A.1. Changes to RFC 3377 This document is nearly a complete rewrite of RFC 3377 as much of the material of RFC 3377 is no longer applicable. The changes include redefining the terms "LDAP" and "LDAPv3" to refer to this revision of the technical specification. A.2. Changes to Section 3.3 of RFC 2251 The section was modified slightly (the word "document" was replaced with "technical specification") to clarify that it applies to the entire LDAP technical specification. Author's Address Kurt D. Zeilenga OpenLDAP Foundation EMail: Kurt@OpenLDAP.org Zeilenga Standards Track [Page 6] RFC 4510 LDAP: TS Road Map June 2006 Full Copyright Statement Copyright (C) The Internet Society (2006). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Zeilenga Standards Track [Page 7] PK (�c\\��7�: �: ( doc/alt-openldap11-devel/rfc/rfc4513.txtnu �[��� Network Working Group R. Harrison, Ed. Request for Comments: 4513 Novell, Inc. Obsoletes: 2251, 2829, 2830 June 2006 Category: Standards Track Lightweight Directory Access Protocol (LDAP): Authentication Methods and Security Mechanisms Status of This Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2006). Abstract This document describes authentication methods and security mechanisms of the Lightweight Directory Access Protocol (LDAP). This document details establishment of Transport Layer Security (TLS) using the StartTLS operation. This document details the simple Bind authentication method including anonymous, unauthenticated, and name/password mechanisms and the Simple Authentication and Security Layer (SASL) Bind authentication method including the EXTERNAL mechanism. This document discusses various authentication and authorization states through which a session to an LDAP server may pass and the actions that trigger these state changes. This document, together with other documents in the LDAP Technical Specification (see Section 1 of the specification's road map), obsoletes RFC 2251, RFC 2829, and RFC 2830. Harrison Standards Track [Page 1] RFC 4513 LDAP Authentication Methods June 2006 Table of Contents 1. Introduction ....................................................4 1.1. Relationship to Other Documents ............................6 1.2. Conventions ................................................6 2. Implementation Requirements .....................................7 3. StartTLS Operation ..............................................8 3.1. TLS Establishment Procedures ..............................8 3.1.1. StartTLS Request Sequencing .........................8 3.1.2. Client Certificate ..................................9 3.1.3. Server Identity Check ...............................9 3.1.3.1. Comparison of DNS Names ...................10 3.1.3.2. Comparison of IP Addresses ................11 3.1.3.3. Comparison of Other subjectName Types .....11 3.1.4. Discovery of Resultant Security Level ..............11 3.1.5. Refresh of Server Capabilities Information .........11 3.2. Effect of TLS on Authorization State .....................12 3.3. TLS Ciphersuites ..........................................12 4. Authorization State ............................................13 5. Bind Operation .................................................14 5.1. Simple Authentication Method ..............................14 5.1.1. Anonymous Authentication Mechanism of Simple Bind ..14 5.1.2. Unauthenticated Authentication Mechanism of Simple Bind ........................................14 5.1.3. Name/Password Authentication Mechanism of Simple Bind ........................................15 5.2. SASL Authentication Method ................................16 5.2.1. SASL Protocol Profile ..............................16 5.2.1.1. SASL Service Name for LDAP ................16 5.2.1.2. SASL Authentication Initiation and Protocol Exchange .........................16 5.2.1.3. Optional Fields ...........................17 5.2.1.4. Octet Where Negotiated Security Layers Take Effect ........................18 5.2.1.5. Determination of Supported SASL Mechanisms ................................18 5.2.1.6. Rules for Using SASL Layers ...............19 5.2.1.7. Support for Multiple Authentications ......19 5.2.1.8. SASL Authorization Identities .............19 5.2.2. SASL Semantics within LDAP .........................20 5.2.3. SASL EXTERNAL Authentication Mechanism .............20 5.2.3.1. Implicit Assertion ........................21 5.2.3.2. Explicit Assertion ........................21 6. Security Considerations ........................................21 6.1. General LDAP Security Considerations ......................21 6.2. StartTLS Security Considerations ..........................22 6.3. Bind Operation Security Considerations ....................23 6.3.1. Unauthenticated Mechanism Security Considerations ..23 Harrison Standards Track [Page 2] RFC 4513 LDAP Authentication Methods June 2006 6.3.2. Name/Password Mechanism Security Considerations ....23 6.3.3. Password-Related Security Considerations ...........23 6.3.4. Hashed Password Security Considerations ............24 6.4. SASL Security Considerations ..............................24 6.5. Related Security Considerations ...........................25 7. IANA Considerations ............................................25 8. Acknowledgements ...............................................25 9. Normative References ...........................................26 10. Informative References ........................................27 Appendix A. Authentication and Authorization Concepts .............28 A.1. Access Control Policy .....................................28 A.2. Access Control Factors ....................................28 A.3. Authentication, Credentials, Identity .....................28 A.4. Authorization Identity ....................................29 Appendix B. Summary of Changes ....................................29 B.1. Changes Made to RFC 2251 ..................................30 B.1.1. Section 4.2.1 ("Sequencing of the Bind Request") ...30 B.1.2. Section 4.2.2 ("Authentication and Other Security Services") .........................................30 B.2. Changes Made to RFC 2829 ..................................30 B.2.1. Section 4 ("Required security mechanisms") .........30 B.2.2. Section 5.1 ("Anonymous authentication procedure") ........................................31 B.2.3. Section 6 ("Password-based authentication") ........31 B.2.4. Section 6.1 ("Digest authentication") ..............31 B.2.5. Section 6.2 ("'simple' authentication choice under TLS encryption") ...................................31 B.2.6. Section 6.3 ("Other authentication choices with TLS") ..............................................31 B.2.7. Section 7.1 ("Certificate-based authentication with TLS") .........................................31 B.2.8. Section 8 ("Other mechanisms") .....................32 B.2.9. Section 9 ("Authorization Identity") ...............32 B.2.10. Section 10 ("TLS Ciphersuites") ...................32 B.3. Changes Made to RFC 2830 ..................................32 B.3.1. Section 3.6 ("Server Identity Check") ..............32 B.3.2. Section 3.7 ("Refresh of Server Capabilities Information") ......................................33 B.3.3. Section 5 ("Effects of TLS on a Client's Authorization Identity") ...........................33 B.3.4. Section 5.2 ("TLS Connection Closure Effects") .....33 Harrison Standards Track [Page 3] RFC 4513 LDAP Authentication Methods June 2006 1. Introduction The Lightweight Directory Access Protocol (LDAP) [RFC4510] is a powerful protocol for accessing directories. It offers means of searching, retrieving, and manipulating directory content and ways to access a rich set of security functions. It is vital that these security functions be interoperable among all LDAP clients and servers on the Internet; therefore there has to be a minimum subset of security functions that is common to all implementations that claim LDAP conformance. Basic threats to an LDAP directory service include (but are not limited to): (1) Unauthorized access to directory data via data-retrieval operations. (2) Unauthorized access to directory data by monitoring access of others. (3) Unauthorized access to reusable client authentication information by monitoring access of others. (4) Unauthorized modification of directory data. (5) Unauthorized modification of configuration information. (6) Denial of Service: Use of resources (commonly in excess) in a manner intended to deny service to others. (7) Spoofing: Tricking a user or client into believing that information came from the directory when in fact it did not, either by modifying data in transit or misdirecting the client's transport connection. Tricking a user or client into sending privileged information to a hostile entity that appears to be the directory server but is not. Tricking a directory server into believing that information came from a particular client when in fact it came from a hostile entity. (8) Hijacking: An attacker seizes control of an established protocol session. Threats (1), (4), (5), (6), (7), and (8) are active attacks. Threats (2) and (3) are passive attacks. Harrison Standards Track [Page 4] RFC 4513 LDAP Authentication Methods June 2006 Threats (1), (4), (5), and (6) are due to hostile clients. Threats (2), (3), (7), and (8) are due to hostile agents on the path between client and server or hostile agents posing as a server, e.g., IP spoofing. LDAP offers the following security mechanisms: (1) Authentication by means of the Bind operation. The Bind operation provides a simple method that supports anonymous, unauthenticated, and name/password mechanisms, and the Simple Authentication and Security Layer (SASL) method, which supports a wide variety of authentication mechanisms. (2) Mechanisms to support vendor-specific access control facilities (LDAP does not offer a standard access control facility). (3) Data integrity service by means of security layers in Transport Layer Security (TLS) or SASL mechanisms. (4) Data confidentiality service by means of security layers in TLS or SASL mechanisms. (5) Server resource usage limitation by means of administrative limits configured on the server. (6) Server authentication by means of the TLS protocol or SASL mechanisms. LDAP may also be protected by means outside the LDAP protocol, e.g., with IP layer security [RFC4301]. Experience has shown that simply allowing implementations to pick and choose the security mechanisms that will be implemented is not a strategy that leads to interoperability. In the absence of mandates, clients will continue to be written that do not support any security function supported by the server, or worse, they will only support mechanisms that provide inadequate security for most circumstances. It is desirable to allow clients to authenticate using a variety of mechanisms including mechanisms where identities are represented as distinguished names [X.501][RFC4512], in string form [RFC4514], or as used in different systems (e.g., simple user names [RFC4013]). Because some authentication mechanisms transmit credentials in plain text form, and/or do not provide data security services and/or are subject to passive attacks, it is necessary to ensure secure interoperability by identifying a mandatory-to-implement mechanism for establishing transport-layer security services. Harrison Standards Track [Page 5] RFC 4513 LDAP Authentication Methods June 2006 The set of security mechanisms provided in LDAP and described in this document is intended to meet the security needs for a wide range of deployment scenarios and still provide a high degree of interoperability among various LDAP implementations and deployments. 1.1. Relationship to Other Documents This document is an integral part of the LDAP Technical Specification [RFC4510]. This document, together with [RFC4510], [RFC4511], and [RFC4512], obsoletes RFC 2251 in its entirety. Sections 4.2.1 (portions) and 4.2.2 of RFC 2251 are obsoleted by this document. Appendix B.1 summarizes the substantive changes made to RFC 2251 by this document. This document obsoletes RFC 2829 in its entirety. Appendix B.2 summarizes the substantive changes made to RFC 2829 by this document. Sections 2 and 4 of RFC 2830 are obsoleted by [RFC4511]. The remainder of RFC 2830 is obsoleted by this document. Appendix B.3 summarizes the substantive changes made to RFC 2830 by this document. 1.2. Conventions The key words "MUST", "MUST NOT", "SHALL", "SHOULD", "SHOULD NOT", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119]. The term "user" represents any human or application entity that is accessing the directory using a directory client. A directory client (or client) is also known as a directory user agent (DUA). The term "transport connection" refers to the underlying transport services used to carry the protocol exchange, as well as associations established by these services. The term "TLS layer" refers to TLS services used in providing security services, as well as associations established by these services. The term "SASL layer" refers to SASL services used in providing security services, as well as associations established by these services. The term "LDAP message layer" refers to the LDAP Message (PDU) services used in providing directory services, as well as associations established by these services. Harrison Standards Track [Page 6] RFC 4513 LDAP Authentication Methods June 2006 The term "LDAP session" refers to combined services (transport connection, TLS layer, SASL layer, LDAP message layer) and their associations. In general, security terms in this document are used consistently with the definitions provided in [RFC2828]. In addition, several terms and concepts relating to security, authentication, and authorization are presented in Appendix A of this document. While the formal definition of these terms and concepts is outside the scope of this document, an understanding of them is prerequisite to understanding much of the material in this document. Readers who are unfamiliar with security-related concepts are encouraged to review Appendix A before reading the remainder of this document. 2. Implementation Requirements LDAP server implementations MUST support the anonymous authentication mechanism of the simple Bind method (Section 5.1.1). LDAP implementations that support any authentication mechanism other than the anonymous authentication mechanism of the simple Bind method MUST support the name/password authentication mechanism of the simple Bind method (Section 5.1.3) and MUST be capable of protecting this name/password authentication using TLS as established by the StartTLS operation (Section 3). Implementations SHOULD disallow the use of the name/password authentication mechanism by default when suitable data security services are not in place, and they MAY provide other suitable data security services for use with this authentication mechanism. Implementations MAY support additional authentication mechanisms. Some of these mechanisms are discussed below. LDAP server implementations SHOULD support client assertion of authorization identity via the SASL EXTERNAL mechanism (Section 5.2.3). LDAP server implementations that support no authentication mechanism other than the anonymous mechanism of the simple bind method SHOULD support use of TLS as established by the StartTLS operation (Section 3). (Other servers MUST support TLS per the second paragraph of this section.) Harrison Standards Track [Page 7] RFC 4513 LDAP Authentication Methods June 2006 Implementations supporting TLS MUST support the TLS_RSA_WITH_3DES_EDE_CBC_SHA ciphersuite and SHOULD support the TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA ciphersuite. Support for the latter ciphersuite is recommended to encourage interoperability with implementations conforming to earlier LDAP StartTLS specifications. 3. StartTLS Operation The Start Transport Layer Security (StartTLS) operation defined in Section 4.14 of [RFC4511] provides the ability to establish TLS [RFC4346] in an LDAP session. The goals of using the TLS protocol with LDAP are to ensure data confidentiality and integrity, and to optionally provide for authentication. TLS expressly provides these capabilities, although the authentication services of TLS are available to LDAP only in combination with the SASL EXTERNAL authentication method (see Section 5.2.3), and then only if the SASL EXTERNAL implementation chooses to make use of the TLS credentials. 3.1. TLS Establishment Procedures This section describes the overall procedures clients and servers must follow for TLS establishment. These procedures take into consideration various aspects of the TLS layer including discovery of resultant security level and assertion of the client's authorization identity. 3.1.1. StartTLS Request Sequencing A client may send the StartTLS extended request at any time after establishing an LDAP session, except: - when TLS is currently established on the session, - when a multi-stage SASL negotiation is in progress on the session, or - when there are outstanding responses for operation requests previously issued on the session. As described in [RFC4511], Section 4.14.1, a (detected) violation of any of these requirements results in a return of the operationsError resultCode. Client implementers should ensure that they strictly follow these operation sequencing requirements to prevent interoperability issues. Operational experience has shown that violating these requirements Harrison Standards Track [Page 8] RFC 4513 LDAP Authentication Methods June 2006 causes interoperability issues because there are race conditions that prevent servers from detecting some violations of these requirements due to factors such as server hardware speed and network latencies. There is no general requirement that the client have or have not already performed a Bind operation (Section 5) before sending a StartTLS operation request; however, where a client intends to perform both a Bind operation and a StartTLS operation, it SHOULD first perform the StartTLS operation so that the Bind request and response messages are protected by the data security services established by the StartTLS operation. 3.1.2. Client Certificate If an LDAP server requests or demands that a client provide a user certificate during TLS negotiation and the client does not present a suitable user certificate (e.g., one that can be validated), the server may use a local security policy to determine whether to successfully complete TLS negotiation. If a client that has provided a suitable certificate subsequently performs a Bind operation using the SASL EXTERNAL authentication mechanism (Section 5.2.3), information in the certificate may be used by the server to identify and authenticate the client. 3.1.3. Server Identity Check In order to prevent man-in-the-middle attacks, the client MUST verify the server's identity (as presented in the server's Certificate message). In this section, the client's understanding of the server's identity (typically the identity used to establish the transport connection) is called the "reference identity". The client determines the type (e.g., DNS name or IP address) of the reference identity and performs a comparison between the reference identity and each subjectAltName value of the corresponding type until a match is produced. Once a match is produced, the server's identity has been verified, and the server identity check is complete. Different subjectAltName types are matched in different ways. Sections 3.1.3.1 - 3.1.3.3 explain how to compare values of various subjectAltName types. The client may map the reference identity to a different type prior to performing a comparison. Mappings may be performed for all available subjectAltName types to which the reference identity can be mapped; however, the reference identity should only be mapped to types for which the mapping is either inherently secure (e.g., extracting the DNS name from a URI to compare with a subjectAltName Harrison Standards Track [Page 9] RFC 4513 LDAP Authentication Methods June 2006 of type dNSName) or for which the mapping is performed in a secure manner (e.g., using DNSSEC, or using user- or admin-configured host- to-address/address-to-host lookup tables). The server's identity may also be verified by comparing the reference identity to the Common Name (CN) [RFC4519] value in the leaf Relative Distinguished Name (RDN) of the subjectName field of the server's certificate. This comparison is performed using the rules for comparison of DNS names in Section 3.1.3.1, below, with the exception that no wildcard matching is allowed. Although the use of the Common Name value is existing practice, it is deprecated, and Certification Authorities are encouraged to provide subjectAltName values instead. Note that the TLS implementation may represent DNs in certificates according to X.500 or other conventions. For example, some X.500 implementations order the RDNs in a DN using a left-to-right (most significant to least significant) convention instead of LDAP's right-to-left convention. If the server identity check fails, user-oriented clients SHOULD either notify the user (clients may give the user the opportunity to continue with the LDAP session in this case) or close the transport connection and indicate that the server's identity is suspect. Automated clients SHOULD close the transport connection and then return or log an error indicating that the server's identity is suspect or both. Beyond the server identity check described in this section, clients should be prepared to do further checking to ensure that the server is authorized to provide the service it is requested to provide. The client may need to make use of local policy information in making this determination. 3.1.3.1. Comparison of DNS Names If the reference identity is an internationalized domain name, conforming implementations MUST convert it to the ASCII Compatible Encoding (ACE) format as specified in Section 4 of RFC 3490 [RFC3490] before comparison with subjectAltName values of type dNSName. Specifically, conforming implementations MUST perform the conversion operation specified in Section 4 of RFC 3490 as follows: * in step 1, the domain name SHALL be considered a "stored string"; * in step 3, set the flag called "UseSTD3ASCIIRules"; * in step 4, process each label with the "ToASCII" operation; and * in step 5, change all label separators to U+002E (full stop). Harrison Standards Track [Page 10] RFC 4513 LDAP Authentication Methods June 2006 After performing the "to-ASCII" conversion, the DNS labels and names MUST be compared for equality according to the rules specified in Section 3 of RFC3490. The '*' (ASCII 42) wildcard character is allowed in subjectAltName values of type dNSName, and then only as the left-most (least significant) DNS label in that value. This wildcard matches any left-most DNS label in the server name. That is, the subject *.example.com matches the server names a.example.com and b.example.com, but does not match example.com or a.b.example.com. 3.1.3.2. Comparison of IP Addresses When the reference identity is an IP address, the identity MUST be converted to the "network byte order" octet string representation [RFC791][RFC2460]. For IP Version 4, as specified in RFC 791, the octet string will contain exactly four octets. For IP Version 6, as specified in RFC 2460, the octet string will contain exactly sixteen octets. This octet string is then compared against subjectAltName values of type iPAddress. A match occurs if the reference identity octet string and value octet strings are identical. 3.1.3.3. Comparison of Other subjectName Types Client implementations MAY support matching against subjectAltName values of other types as described in other documents. 3.1.4. Discovery of Resultant Security Level After a TLS layer is established in an LDAP session, both parties are to each independently decide whether or not to continue based on local policy and the security level achieved. If either party decides that the security level is inadequate for it to continue, it SHOULD remove the TLS layer immediately after the TLS (re)negotiation has completed (see [RFC4511], Section 4.14.3, and Section 3.2 below). Implementations may reevaluate the security level at any time and, upon finding it inadequate, should remove the TLS layer. 3.1.5. Refresh of Server Capabilities Information After a TLS layer is established in an LDAP session, the client SHOULD discard or refresh all information about the server that it obtained prior to the initiation of the TLS negotiation and that it did not obtain through secure mechanisms. This protects against man-in-the-middle attacks that may have altered any server capabilities information retrieved prior to TLS layer installation. Harrison Standards Track [Page 11] RFC 4513 LDAP Authentication Methods June 2006 The server may advertise different capabilities after installing a TLS layer. In particular, the value of 'supportedSASLMechanisms' may be different after a TLS layer has been installed (specifically, the EXTERNAL and PLAIN [PLAIN] mechanisms are likely to be listed only after a TLS layer has been installed). 3.2. Effect of TLS on Authorization State The establishment, change, and/or closure of TLS may cause the authorization state to move to a new state. This is discussed further in Section 4. 3.3. TLS Ciphersuites Several issues should be considered when selecting TLS ciphersuites that are appropriate for use in a given circumstance. These issues include the following: - The ciphersuite's ability to provide adequate confidentiality protection for passwords and other data sent over the transport connection. Client and server implementers should recognize that some TLS ciphersuites provide no confidentiality protection, while other ciphersuites that do provide confidentiality protection may be vulnerable to being cracked using brute force methods, especially in light of ever- increasing CPU speeds that reduce the time needed to successfully mount such attacks. - Client and server implementers should carefully consider the value of the password or data being protected versus the level of confidentiality protection provided by the ciphersuite to ensure that the level of protection afforded by the ciphersuite is appropriate. - The ciphersuite's vulnerability (or lack thereof) to man-in-the- middle attacks. Ciphersuites vulnerable to man-in-the-middle attacks SHOULD NOT be used to protect passwords or sensitive data, unless the network configuration is such that the danger of a man-in-the-middle attack is negligible. - After a TLS negotiation (either initial or subsequent) is completed, both protocol peers should independently verify that the security services provided by the negotiated ciphersuite are adequate for the intended use of the LDAP session. If they are not, the TLS layer should be closed. Harrison Standards Track [Page 12] RFC 4513 LDAP Authentication Methods June 2006 4. Authorization State Every LDAP session has an associated authorization state. This state is comprised of numerous factors such as what (if any) authentication state has been established, how it was established, and what security services are in place. Some factors may be determined and/or affected by protocol events (e.g., Bind, StartTLS, or TLS closure), and some factors may be determined by external events (e.g., time of day or server load). While it is often convenient to view authorization state in simplistic terms (as we often do in this technical specification) such as "an anonymous state", it is noted that authorization systems in LDAP implementations commonly involve many factors that interrelate in complex manners. Authorization in LDAP is a local matter. One of the key factors in making authorization decisions is authorization identity. The Bind operation (defined in Section 4.2 of [RFC4511] and discussed further in Section 5 below) allows information to be exchanged between the client and server to establish an authorization identity for the LDAP session. The Bind operation may also be used to move the LDAP session to an anonymous authorization state (see Section 5.1.1). Upon initial establishment of the LDAP session, the session has an anonymous authorization identity. Among other things this implies that the client need not send a BindRequest in the first PDU of the LDAP message layer. The client may send any operation request prior to performing a Bind operation, and the server MUST treat it as if it had been performed after an anonymous Bind operation (Section 5.1.1). Upon receipt of a Bind request, the server immediately moves the session to an anonymous authorization state. If the Bind request is successful, the session is moved to the requested authentication state with its associated authorization state. Otherwise, the session remains in an anonymous state. It is noted that other events both internal and external to LDAP may result in the authentication and authorization states being moved to an anonymous one. For instance, the establishment, change, or closure of data security services may result in a move to an anonymous state, or the user's credential information (e.g., certificate) may have expired. The former is an example of an event internal to LDAP, whereas the latter is an example of an event external to LDAP. Harrison Standards Track [Page 13] RFC 4513 LDAP Authentication Methods June 2006 5. Bind Operation The Bind operation ([RFC4511], Section 4.2) allows authentication information to be exchanged between the client and server to establish a new authorization state. The Bind request typically specifies the desired authentication identity. Some Bind mechanisms also allow the client to specify the authorization identity. If the authorization identity is not specified, the server derives it from the authentication identity in an implementation-specific manner. If the authorization identity is specified, the server MUST verify that the client's authentication identity is permitted to assume (e.g., proxy for) the asserted authorization identity. The server MUST reject the Bind operation with an invalidCredentials resultCode in the Bind response if the client is not so authorized. 5.1. Simple Authentication Method The simple authentication method of the Bind Operation provides three authentication mechanisms: - An anonymous authentication mechanism (Section 5.1.1). - An unauthenticated authentication mechanism (Section 5.1.2). - A name/password authentication mechanism using credentials consisting of a name (in the form of an LDAP distinguished name [RFC4514]) and a password (Section 5.1.3). 5.1.1. Anonymous Authentication Mechanism of Simple Bind An LDAP client may use the anonymous authentication mechanism of the simple Bind method to explicitly establish an anonymous authorization state by sending a Bind request with a name value of zero length and specifying the simple authentication choice containing a password value of zero length. 5.1.2. Unauthenticated Authentication Mechanism of Simple Bind An LDAP client may use the unauthenticated authentication mechanism of the simple Bind method to establish an anonymous authorization state by sending a Bind request with a name value (a distinguished name in LDAP string form [RFC4514] of non-zero length) and specifying the simple authentication choice containing a password value of zero length. Harrison Standards Track [Page 14] RFC 4513 LDAP Authentication Methods June 2006 The distinguished name value provided by the client is intended to be used for trace (e.g., logging) purposes only. The value is not to be authenticated or otherwise validated (including verification that the DN refers to an existing directory object). The value is not to be used (directly or indirectly) for authorization purposes. Unauthenticated Bind operations can have significant security issues (see Section 6.3.1). In particular, users intending to perform Name/Password Authentication may inadvertently provide an empty password and thus cause poorly implemented clients to request Unauthenticated access. Clients SHOULD be implemented to require user selection of the Unauthenticated Authentication Mechanism by means other than user input of an empty password. Clients SHOULD disallow an empty password input to a Name/Password Authentication user interface. Additionally, Servers SHOULD by default fail Unauthenticated Bind requests with a resultCode of unwillingToPerform. 5.1.3. Name/Password Authentication Mechanism of Simple Bind An LDAP client may use the name/password authentication mechanism of the simple Bind method to establish an authenticated authorization state by sending a Bind request with a name value (a distinguished name in LDAP string form [RFC4514] of non-zero length) and specifying the simple authentication choice containing an OCTET STRING password value of non-zero length. Servers that map the DN sent in the Bind request to a directory entry with an associated set of one or more passwords used with this mechanism will compare the presented password to that set of passwords. The presented password is considered valid if it matches any member of this set. A resultCode of invalidDNSyntax indicates that the DN sent in the name value is syntactically invalid. A resultCode of invalidCredentials indicates that the DN is syntactically correct but not valid for purposes of authentication, that the password is not valid for the DN, or that the server otherwise considers the credentials invalid. A resultCode of success indicates that the credentials are valid and that the server is willing to provide service to the entity these credentials identify. Server behavior is undefined for Bind requests specifying the name/password authentication mechanism with a zero-length name value and a password value of non-zero length. Harrison Standards Track [Page 15] RFC 4513 LDAP Authentication Methods June 2006 The name/password authentication mechanism of the simple Bind method is not suitable for authentication in environments without confidentiality protection. 5.2. SASL Authentication Method The sasl authentication method of the Bind Operation provides facilities for using any SASL mechanism including authentication mechanisms and other services (e.g., data security services). 5.2.1. SASL Protocol Profile LDAP allows authentication via any SASL mechanism [RFC4422]. As LDAP includes native anonymous and name/password (plain text) authentication methods, the ANONYMOUS [RFC4505] and PLAIN [PLAIN] SASL mechanisms are typically not used with LDAP. Each protocol that utilizes SASL services is required to supply certain information profiling the way they are exposed through the protocol ([RFC4422], Section 4). This section explains how each of these profiling requirements is met by LDAP. 5.2.1.1. SASL Service Name for LDAP The SASL service name for LDAP is "ldap", which has been registered with the IANA as a SASL service name. 5.2.1.2. SASL Authentication Initiation and Protocol Exchange SASL authentication is initiated via a BindRequest message ([RFC4511], Section 4.2) with the following parameters: - The version is 3. - The AuthenticationChoice is sasl. - The mechanism element of the SaslCredentials sequence contains the value of the desired SASL mechanism. - The optional credentials field of the SaslCredentials sequence MAY be used to provide an initial client response for mechanisms that are defined to have the client send data first (see [RFC4422], Sections 3 and 5). In general, a SASL authentication protocol exchange consists of a series of server challenges and client responses, the contents of which are specific to and defined by the SASL mechanism. Thus, for some SASL authentication mechanisms, it may be necessary for the client to respond to one or more server challenges by sending BindRequest messages multiple times. A challenge is indicated by the server sending a BindResponse message with the resultCode set to Harrison Standards Track [Page 16] RFC 4513 LDAP Authentication Methods June 2006 saslBindInProgress. This indicates that the server requires the client to send a new BindRequest message with the same SASL mechanism to continue the authentication process. To the LDAP message layer, these challenges and responses are opaque binary tokens of arbitrary length. LDAP servers use the serverSaslCreds field (an OCTET STRING) in a BindResponse message to transmit each challenge. LDAP clients use the credentials field (an OCTET STRING) in the SaslCredentials sequence of a BindRequest message to transmit each response. Note that unlike some Internet protocols where SASL is used, LDAP is not text based and does not Base64-transform these challenge and response values. Clients sending a BindRequest message with the sasl choice selected SHOULD send a zero-length value in the name field. Servers receiving a BindRequest message with the sasl choice selected SHALL ignore any value in the name field. A client may abort a SASL Bind negotiation by sending a BindRequest message with a different value in the mechanism field of SaslCredentials or with an AuthenticationChoice other than sasl. If the client sends a BindRequest with the sasl mechanism field as an empty string, the server MUST return a BindResponse with a resultCode of authMethodNotSupported. This will allow the client to abort a negotiation if it wishes to try again with the same SASL mechanism. The server indicates completion of the SASL challenge-response exchange by responding with a BindResponse in which the resultCode value is not saslBindInProgress. The serverSaslCreds field in the BindResponse can be used to include an optional challenge with a success notification for mechanisms that are defined to have the server send additional data along with the indication of successful completion. 5.2.1.3. Optional Fields As discussed above, LDAP provides an optional field for carrying an initial response in the message initiating the SASL exchange and provides an optional field for carrying additional data in the message indicating the outcome of the authentication exchange. As the mechanism-specific content in these fields may be zero length, SASL requires protocol specifications to detail how an empty field is distinguished from an absent field. Harrison Standards Track [Page 17] RFC 4513 LDAP Authentication Methods June 2006 Zero-length initial response data is distinguished from no initial response data in the initiating message, a BindRequest PDU, by the presence of the SaslCredentials.credentials OCTET STRING (of length zero) in that PDU. If the client does not intend to send an initial response with the BindRequest initiating the SASL exchange, it MUST omit the SaslCredentials.credentials OCTET STRING (rather than include an zero-length OCTET STRING). Zero-length additional data is distinguished from no additional response data in the outcome message, a BindResponse PDU, by the presence of the serverSaslCreds OCTET STRING (of length zero) in that PDU. If a server does not intend to send additional data in the BindResponse message indicating outcome of the exchange, the server SHALL omit the serverSaslCreds OCTET STRING (rather than including a zero-length OCTET STRING). 5.2.1.4. Octet Where Negotiated Security Layers Take Effect SASL layers take effect following the transmission by the server and reception by the client of the final BindResponse in the SASL exchange with a resultCode of success. Once a SASL layer providing data integrity or confidentiality services takes effect, the layer remains in effect until a new layer is installed (i.e., at the first octet following the final BindResponse of the Bind operation that caused the new layer to take effect). Thus, an established SASL layer is not affected by a failed or non-SASL Bind. 5.2.1.5. Determination of Supported SASL Mechanisms Clients may determine the SASL mechanisms a server supports by reading the 'supportedSASLMechanisms' attribute from the root DSE (DSA-Specific Entry) ([RFC4512], Section 5.1). The values of this attribute, if any, list the mechanisms the server supports in the current LDAP session state. LDAP servers SHOULD allow all clients -- even those with an anonymous authorization -- to retrieve the 'supportedSASLMechanisms' attribute of the root DSE both before and after the SASL authentication exchange. The purpose of the latter is to allow the client to detect possible downgrade attacks (see Section 6.4 and [RFC4422], Section 6.1.2). Because SASL mechanisms provide critical security functions, clients and servers should be configurable to specify what mechanisms are acceptable and allow only those mechanisms to be used. Both clients and servers must confirm that the negotiated security level meets their requirements before proceeding to use the session. Harrison Standards Track [Page 18] RFC 4513 LDAP Authentication Methods June 2006 5.2.1.6. Rules for Using SASL Layers Upon installing a SASL layer, the client SHOULD discard or refresh all information about the server that it obtained prior to the initiation of the SASL negotiation and that it did not obtain through secure mechanisms. If a lower-level security layer (such as TLS) is installed, any SASL layer SHALL be layered on top of such security layers regardless of the order of their negotiation. In all other respects, the SASL layer and other security layers act independently, e.g., if both a TLS layer and a SASL layer are in effect, then removing the TLS layer does not affect the continuing service of the SASL layer. 5.2.1.7. Support for Multiple Authentications LDAP supports multiple SASL authentications as defined in [RFC4422], Section 4. 5.2.1.8. SASL Authorization Identities Some SASL mechanisms allow clients to request a desired authorization identity for the LDAP session ([RFC4422], Section 3.4). The decision to allow or disallow the current authentication identity to have access to the requested authorization identity is a matter of local policy. The authorization identity is a string of UTF-8 [RFC3629] encoded [Unicode] characters corresponding to the following Augmented Backus-Naur Form (ABNF) [RFC4234] grammar: authzId = dnAuthzId / uAuthzId ; distinguished-name-based authz id dnAuthzId = "dn:" distinguishedName ; unspecified authorization id, UTF-8 encoded uAuthzId = "u:" userid userid = *UTF8 ; syntax unspecified where the distinguishedName rule is defined in Section 3 of [RFC4514] and the UTF8 rule is defined in Section 1.4 of [RFC4512]. The dnAuthzId choice is used to assert authorization identities in the form of a distinguished name to be matched in accordance with the distinguishedNameMatch matching rule ([RFC4517], Section 4.2.15). There is no requirement that the asserted distinguishedName value be that of an entry in the directory. Harrison Standards Track [Page 19] RFC 4513 LDAP Authentication Methods June 2006 The uAuthzId choice allows clients to assert an authorization identity that is not in distinguished name form. The format of userid is defined only as a sequence of UTF-8 [RFC3629] encoded [Unicode] characters, and any further interpretation is a local matter. For example, the userid could identify a user of a specific directory service, be a login name, or be an email address. A uAuthzId SHOULD NOT be assumed to be globally unique. To compare uAuthzId values, each uAuthzId value MUST be prepared as a "query" string ([RFC3454], Section 7) using the SASLprep [RFC4013] algorithm, and then the two values are compared octet-wise. The above grammar is extensible. The authzId production may be extended to support additional forms of identities. Each form is distinguished by its unique prefix (see Section 3.12 of [RFC4520] for registration requirements). 5.2.2. SASL Semantics within LDAP Implementers must take care to maintain the semantics of SASL specifications when handling data that has different semantics in the LDAP protocol. For example, the SASL DIGEST-MD5 authentication mechanism [DIGEST-MD5] utilizes an authentication identity and a realm that are syntactically simple strings and semantically simple username [RFC4013] and realm values. These values are not LDAP DNs, and there is no requirement that they be represented or treated as such. 5.2.3. SASL EXTERNAL Authentication Mechanism A client can use the SASL EXTERNAL ([RFC4422], Appendix A) mechanism to request the LDAP server to authenticate and establish a resulting authorization identity using security credentials exchanged by a lower security layer (such as by TLS authentication). If the client's authentication credentials have not been established at a lower security layer, the SASL EXTERNAL Bind MUST fail with a resultCode of inappropriateAuthentication. Although this situation has the effect of leaving the LDAP session in an anonymous state (Section 4), the state of any installed security layer is unaffected. A client may either request that its authorization identity be automatically derived from its authentication credentials exchanged at a lower security layer, or it may explicitly provide a desired authorization identity. The former is known as an implicit assertion, and the latter as an explicit assertion. Harrison Standards Track [Page 20] RFC 4513 LDAP Authentication Methods June 2006 5.2.3.1. Implicit Assertion An implicit authorization identity assertion is performed by invoking a Bind request of the SASL form using the EXTERNAL mechanism name that does not include the optional credentials field (found within the SaslCredentials sequence in the BindRequest). The server will derive the client's authorization identity from the authentication identity supplied by a security layer (e.g., a public key certificate used during TLS layer installation) according to local policy. The underlying mechanics of how this is accomplished are implementation specific. 5.2.3.2. Explicit Assertion An explicit authorization identity assertion is performed by invoking a Bind request of the SASL form using the EXTERNAL mechanism name that includes the credentials field (found within the SaslCredentials sequence in the BindRequest). The value of the credentials field (an OCTET STRING) is the asserted authorization identity and MUST be constructed as documented in Section 5.2.1.8. 6. Security Considerations Security issues are discussed throughout this document. The unsurprising conclusion is that security is an integral and necessary part of LDAP. This section discusses a number of LDAP-related security considerations. 6.1. General LDAP Security Considerations LDAP itself provides no security or protection from accessing or updating the directory by means other than through the LDAP protocol, e.g., from inspection of server database files by database administrators. Sensitive data may be carried in almost any LDAP message, and its disclosure may be subject to privacy laws or other legal regulation in many countries. Implementers should take appropriate measures to protect sensitive data from disclosure to unauthorized entities. A session on which the client has not established data integrity and privacy services (e.g., via StartTLS, IPsec, or a suitable SASL mechanism) is subject to man-in-the-middle attacks to view and modify information in transit. Client and server implementers SHOULD take measures to protect sensitive data in the LDAP session from these attacks by using data protection services as discussed in this document. Clients and servers should provide the ability to be configured to require these protections. A resultCode of Harrison Standards Track [Page 21] RFC 4513 LDAP Authentication Methods June 2006 confidentialityRequired indicates that the server requires establishment of (stronger) data confidentiality protection in order to perform the requested operation. Access control should always be applied when reading sensitive information or updating directory information. Various security factors, including authentication and authorization information and data security services may change during the course of the LDAP session, or even during the performance of a particular operation. Implementations should be robust in the handling of changing security factors. 6.2. StartTLS Security Considerations All security gained via use of the StartTLS operation is gained by the use of TLS itself. The StartTLS operation, on its own, does not provide any additional security. The level of security provided through the use of TLS depends directly on both the quality of the TLS implementation used and the style of usage of that implementation. Additionally, a man-in-the- middle attacker can remove the StartTLS extended operation from the 'supportedExtension' attribute of the root DSE. Both parties SHOULD independently ascertain and consent to the security level achieved once TLS is established and before beginning use of the TLS- protected session. For example, the security level of the TLS layer might have been negotiated down to plaintext. Clients MUST either warn the user when the security level achieved does not provide an acceptable level of data confidentiality and/or data integrity protection, or be configurable to refuse to proceed without an acceptable level of security. As stated in Section 3.1.2, a server may use a local security policy to determine whether to successfully complete TLS negotiation. Information in the user's certificate that is originated or verified by the certification authority should be used by the policy administrator when configuring the identification and authorization policy. Server implementers SHOULD allow server administrators to elect whether and when data confidentiality and integrity are required, as well as elect whether authentication of the client during the TLS handshake is required. Implementers should be aware of and understand TLS security considerations as discussed in the TLS specification [RFC4346]. Harrison Standards Track [Page 22] RFC 4513 LDAP Authentication Methods June 2006 6.3. Bind Operation Security Considerations This section discusses several security considerations relevant to LDAP authentication via the Bind operation. 6.3.1. Unauthenticated Mechanism Security Considerations Operational experience shows that clients can (and frequently do) misuse the unauthenticated authentication mechanism of the simple Bind method (see Section 5.1.2). For example, a client program might make a decision to grant access to non-directory information on the basis of successfully completing a Bind operation. LDAP server implementations may return a success response to an unauthenticated Bind request. This may erroneously leave the client with the impression that the server has successfully authenticated the identity represented by the distinguished name when in reality, an anonymous authorization state has been established. Clients that use the results from a simple Bind operation to make authorization decisions should actively detect unauthenticated Bind requests (by verifying that the supplied password is not empty) and react appropriately. 6.3.2. Name/Password Mechanism Security Considerations The name/password authentication mechanism of the simple Bind method discloses the password to the server, which is an inherent security risk. There are other mechanisms, such as SASL DIGEST-MD5 [DIGEST-MD5], that do not disclose the password to the server. 6.3.3. Password-Related Security Considerations LDAP allows multi-valued password attributes. In systems where entries are expected to have one and only one password, administrative controls should be provided to enforce this behavior. The use of clear text passwords and other unprotected authentication credentials is strongly discouraged over open networks when the underlying transport service cannot guarantee confidentiality. LDAP implementations SHOULD NOT by default support authentication methods using clear text passwords and other unprotected authentication credentials unless the data on the session is protected using TLS or other data confidentiality and data integrity protection. The transmission of passwords in the clear -- typically for authentication or modification -- poses a significant security risk. This risk can be avoided by using SASL authentication [RFC4422] Harrison Standards Track [Page 23] RFC 4513 LDAP Authentication Methods June 2006 mechanisms that do not transmit passwords in the clear or by negotiating transport or session layer data confidentiality services before transmitting password values. To mitigate the security risks associated with the transfer of passwords, a server implementation that supports any password-based authentication mechanism that transmits passwords in the clear MUST support a policy mechanism that at the time of authentication or password modification, requires that: A TLS layer has been successfully installed. OR Some other data confidentiality mechanism that protects the password value from eavesdropping has been provided. OR The server returns a resultCode of confidentialityRequired for the operation (i.e., name/password Bind with password value, SASL Bind transmitting a password value in the clear, add or modify including a userPassword value, etc.), even if the password value is correct. Server implementations may also want to provide policy mechanisms to invalidate or otherwise protect accounts in situations where a server detects that a password for an account has been transmitted in the clear. 6.3.4. Hashed Password Security Considerations Some authentication mechanisms (e.g., DIGEST-MD5) transmit a hash of the password value that may be vulnerable to offline dictionary attacks. Implementers should take care to protect such hashed password values during transmission using TLS or other confidentiality mechanisms. 6.4. SASL Security Considerations Until data integrity service is installed on an LDAP session, an attacker can modify the transmitted values of the 'supportedSASLMechanisms' attribute response and thus downgrade the list of available SASL mechanisms to include only the least secure mechanism. To detect this type of attack, the client may retrieve the SASL mechanisms the server makes available both before and after data integrity service is installed on an LDAP session. If the client finds that the integrity-protected list (the list obtained Harrison Standards Track [Page 24] RFC 4513 LDAP Authentication Methods June 2006 after data integrity service was installed) contains a stronger mechanism than those in the previously obtained list, the client should assume the previously obtained list was modified by an attacker. In this circumstance it is recommended that the client close the underlying transport connection and then reconnect to reestablish the session. 6.5. Related Security Considerations Additional security considerations relating to the various authentication methods and mechanisms discussed in this document apply and can be found in [RFC4422], [RFC4013], [RFC3454], and [RFC3629]. 7. IANA Considerations The IANA has updated the LDAP Protocol Mechanism registry to indicate that this document and [RFC4511] provide the definitive technical specification for the StartTLS (1.3.6.1.4.1.1466.20037) extended operation. The IANA has updated the LDAP LDAPMessage types registry to indicate that this document and [RFC4511] provide the definitive technical specification for the bindRequest (0) and bindResponse (1) message types. The IANA has updated the LDAP Bind Authentication Method registry to indicate that this document and [RFC4511] provide the definitive technical specification for the simple (0) and sasl (3) bind authentication methods. The IANA has updated the LDAP authzid prefixes registry to indicate that this document provides the definitive technical specification for the dnAuthzId (dn:) and uAuthzId (u:) authzid prefixes. 8. Acknowledgements This document combines information originally contained in RFC 2251, RFC 2829, and RFC 2830. RFC 2251 was a product of the Access, Searching, and Indexing of Directories (ASID) Working Group. RFC 2829 and RFC 2830 were products of the LDAP Extensions (LDAPEXT) Working Group. This document is a product of the IETF LDAP Revision (LDAPBIS) working group. Harrison Standards Track [Page 25] RFC 4513 LDAP Authentication Methods June 2006 9. Normative References [RFC791] Postel, J., "Internet Protocol", STD 5, RFC 791, September 1981. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2460] Deering, S. and R. Hinden, "Internet Protocol, Version 6 (IPv6) Specification", RFC 2460, December 1998. [RFC3454] Hoffman, P. and M. Blanchet, "Preparation of Internationalized Strings ("stringprep")", RFC 3454, December 2002. [RFC3490] Faltstrom, P., Hoffman, P., and A. Costello, "Internationalizing Domain Names in Applications (IDNA)", RFC 3490, March 2003. [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003. [RFC4013] Zeilenga, K., "SASLprep: Stringprep Profile for User Names and Passwords", RFC 4013, February 2005. [RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 4234, October 2005. [RFC4346] Dierks, T. and E. Rescorla, "The TLS Protocol Version 1.1", RFC 4346, March 2006. [RFC4422] Melnikov, A., Ed. and K. Zeilenga, Ed., "Simple Authentication and Security Layer (SASL)", RFC 4422, June 2006. [RFC4510] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006. [RFC4511] Sermersheim, J., Ed., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006. [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006. Harrison Standards Track [Page 26] RFC 4513 LDAP Authentication Methods June 2006 [RFC4514] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names", RFC 4514, June 2006. [RFC4517] Legg, S., Ed., "Lightweight Directory Access Protocol (LDAP): Syntaxes and Matching Rules", RFC 4517, June 2006. [RFC4519] Sciberras, A., Ed., "Lightweight Directory Access Protocol (LDAP): Schema for User Applications", RFC 4519, June 2006. [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006. [Unicode] The Unicode Consortium, "The Unicode Standard, Version 3.2.0" is defined by "The Unicode Standard, Version 3.0" (Reading, MA, Addison-Wesley, 2000. ISBN 0-201-61633- 5), as amended by the "Unicode Standard Annex #27: Unicode 3.1" (http://www.unicode.org/reports/tr27/) and by the "Unicode Standard Annex #28: Unicode 3.2" (http://www.unicode.org/reports/tr28/). [X.501] ITU-T Rec. X.501, "The Directory: Models", 1993. 10. Informative References [DIGEST-MD5] Leach, P., Newman, C., and A. Melnikov, "Using Digest Authentication as a SASL Mechanism", Work in Progress, March 2006. [PLAIN] Zeilenga, K., "The Plain SASL Mechanism", Work in Progress, March 2005. [RFC2828] Shirey, R., "Internet Security Glossary", FYI 36, RFC 2828, May 2000. [RFC4301] Kent, S. and K. Seo, "Security Architecture for the Internet Protocol", RFC 4301, December 2005. [RFC4505] Zeilenga, K., "The Anonymous SASL Mechanism", RFC 4505, June 2006. Harrison Standards Track [Page 27] RFC 4513 LDAP Authentication Methods June 2006 Appendix A. Authentication and Authorization Concepts This appendix is non-normative. This appendix defines basic terms, concepts, and interrelationships regarding authentication, authorization, credentials, and identity. These concepts are used in describing how various security approaches are utilized in client authentication and authorization. A.1. Access Control Policy An access control policy is a set of rules defining the protection of resources, generally in terms of the capabilities of persons or other entities accessing those resources. Security objects and mechanisms, such as those described here, enable the expression of access control policies and their enforcement. A.2. Access Control Factors A request, when it is being processed by a server, may be associated with a wide variety of security-related factors. The server uses these factors to determine whether and how to process the request. These are called access control factors (ACFs). They might include source IP address, encryption strength, the type of operation being requested, time of day, etc.. Some factors may be specific to the request itself; others may be associated with the transport connection via which the request is transmitted; and others (e.g., time of day) may be "environmental". Access control policies are expressed in terms of access control factors; for example, "a request having ACFs i,j,k can perform operation Y on resource Z". The set of ACFs that a server makes available for such expressions is implementation specific. A.3. Authentication, Credentials, Identity Authentication credentials are the evidence supplied by one party to another, asserting the identity of the supplying party (e.g., a user) who is attempting to establish a new authorization state with the other party (typically a server). Authentication is the process of generating, transmitting, and verifying these credentials and thus the identity they assert. An authentication identity is the name presented in a credential. There are many forms of authentication credentials. The form used depends upon the particular authentication mechanism negotiated by the parties. X.509 certificates, Kerberos tickets, and simple identity and password pairs are all examples of authentication Harrison Standards Track [Page 28] RFC 4513 LDAP Authentication Methods June 2006 credential forms. Note that an authentication mechanism may constrain the form of authentication identities used with it. A.4. Authorization Identity An authorization identity is one kind of access control factor. It is the name of the user or other entity that requests that operations be performed. Access control policies are often expressed in terms of authorization identities; for example, "entity X can perform operation Y on resource Z". The authorization identity of an LDAP session is often semantically the same as the authentication identity presented by the client, but it may be different. SASL allows clients to specify an authorization identity distinct from the authentication identity asserted by the client's credentials. This permits agents such as proxy servers to authenticate using their own credentials, yet request the access privileges of the identity for which they are proxying [RFC4422]. Also, the form of authentication identity supplied by a service like TLS may not correspond to the authorization identities used to express a server's access control policy, thus requiring a server- specific mapping to be done. The method by which a server composes and validates an authorization identity from the authentication credentials supplied by a client is implementation specific. Appendix B. Summary of Changes This appendix is non-normative. This appendix summarizes substantive changes made to RFC 2251, RFC 2829 and RFC 2830. In addition to the specific changes detailed below, the reader of this document should be aware that numerous general editorial changes have been made to the original content from the source documents. These changes include the following: - The material originally found in RFC 2251 Sections 4.2.1 and 4.2.2, RFC 2829 (all sections except Sections 2 and 4), and RFC 2830 was combined into a single document. - The combined material was substantially reorganized and edited to group related subjects, improve the document flow, and clarify intent. - Changes were made throughout the text to align with definitions of LDAP protocol layers and IETF security terminology. Harrison Standards Track [Page 29] RFC 4513 LDAP Authentication Methods June 2006 - Substantial updates and additions were made to security considerations from both documents based on current operational experience. B.1. Changes Made to RFC 2251 This section summarizes the substantive changes made to Sections 4.2.1 and 4.2.2 of RFC 2251 by this document. Additional substantive changes to Section 4.2.1 of RFC 2251 are also documented in [RFC4511]. B.1.1. Section 4.2.1 ("Sequencing of the Bind Request") - Paragraph 1: Removed the sentence, "If at any stage the client wishes to abort the bind process it MAY unbind and then drop the underlying connection". The Unbind operation still permits this behavior, but it is not documented explicitly. - Clarified that the session is moved to an anonymous state upon receipt of the BindRequest PDU and that it is only moved to a non- anonymous state if and when the Bind request is successful. B.1.2. Section 4.2.2 ("Authentication and Other Security Services") - RFC 2251 states that anonymous authentication MUST be performed using the simple bind method. This specification defines the anonymous authentication mechanism of the simple bind method and requires all conforming implementations to support it. Other authentication mechanisms producing anonymous authentication and authorization state may also be implemented and used by conforming implementations. B.2. Changes Made to RFC 2829 This section summarizes the substantive changes made to RFC 2829. B.2.1. Section 4 ("Required security mechanisms") - The name/password authentication mechanism (see Section B.2.5 below) protected by TLS replaces the SASL DIGEST-MD5 mechanism as LDAP's mandatory-to-implement password-based authentication mechanism. Implementations are encouraged to continue supporting SASL DIGEST-MD5 [DIGEST-MD5]. Harrison Standards Track [Page 30] RFC 4513 LDAP Authentication Methods June 2006 B.2.2. Section 5.1 ("Anonymous authentication procedure") - Clarified that anonymous authentication involves a name value of zero length and a password value of zero length. The unauthenticated authentication mechanism was added to handle simple Bind requests involving a name value with a non-zero length and a password value of zero length. B.2.3. Section 6 ("Password-based authentication") - See Section B.2.1. B.2.4. Section 6.1 ("Digest authentication") - As the SASL-DIGEST-MD5 mechanism is no longer mandatory to implement, this section is now historical and was not included in this document. RFC 2829, Section 6.1, continues to document the SASL DIGEST-MD5 authentication mechanism. B.2.5. Section 6.2 ("'simple' authentication choice under TLS encryption") - Renamed the "simple" authentication mechanism to the name/password authentication mechanism to better describe it. - The use of TLS was generalized to align with definitions of LDAP protocol layers. TLS establishment is now discussed as an independent subject and is generalized for use with all authentication mechanisms and other security layers. - Removed the implication that the userPassword attribute is the sole location for storage of password values to be used in authentication. There is no longer any implied requirement for how or where passwords are stored at the server for use in authentication. B.2.6. Section 6.3 ("Other authentication choices with TLS") - See Section B.2.5. B.2.7. Section 7.1 ("Certificate-based authentication with TLS") - See Section B.2.5. Harrison Standards Track [Page 31] RFC 4513 LDAP Authentication Methods June 2006 B.2.8. Section 8 ("Other mechanisms") - All SASL authentication mechanisms are explicitly allowed within LDAP. Specifically, this means the SASL ANONYMOUS and SASL PLAIN mechanisms are no longer precluded from use within LDAP. B.2.9. Section 9 ("Authorization Identity") - Specified matching rules for dnAuthzId and uAuthzId values. In particular, the DN value in the dnAuthzId form must be matched using DN matching rules, and the uAuthzId value MUST be prepared using SASLprep rules before being compared octet-wise. - Clarified that uAuthzId values should not be assumed to be globally unique. B.2.10. Section 10 ("TLS Ciphersuites") - TLS ciphersuite recommendations are no longer included in this specification. Implementations must now support the TLS_RSA_WITH_3DES_EDE_CBC_SHA ciphersuite and should continue to support the TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA ciphersuite. - Clarified that anonymous authentication involves a name value of zero length and a password value of zero length. The unauthenticated authentication mechanism was added to handle simple Bind requests involving a name value with a non-zero length and a password value of zero length. B.3. Changes Made to RFC 2830 This section summarizes the substantive changes made to Sections 3 and 5 of RFC 2830. Readers should consult [RFC4511] for summaries of changes to other sections. B.3.1. Section 3.6 ("Server Identity Check") - Substantially updated the server identity check algorithm to ensure that it is complete and robust. In particular, the use of all relevant values in the subjectAltName and the subjectName fields are covered by the algorithm and matching rules are specified for each type of value. Mapped (derived) forms of the server identity may now be used when the mapping is performed in a secure fashion. Harrison Standards Track [Page 32] RFC 4513 LDAP Authentication Methods June 2006 B.3.2. Section 3.7 ("Refresh of Server Capabilities Information") - Clients are no longer required to always refresh information about server capabilities following TLS establishment. This is to allow for situations where this information was obtained through a secure mechanism. B.3.3. Section 5 ("Effects of TLS on a Client's Authorization Identity") - Establishing a TLS layer on an LDAP session may now cause the authorization state of the LDAP session to change. B.3.4. Section 5.2 ("TLS Connection Closure Effects") - Closing a TLS layer on an LDAP session changes the authentication and authorization state of the LDAP session based on local policy. Specifically, this means that implementations are not required to change the authentication and authorization states to anonymous upon TLS closure. - Replaced references to RFC 2401 with RFC 4301. Author's Address Roger Harrison Novell, Inc. 1800 S. Novell Place Provo, UT 84606 USA Phone: +1 801 861 2642 EMail: roger_harrison@novell.com Harrison Standards Track [Page 33] RFC 4513 LDAP Authentication Methods June 2006 Full Copyright Statement Copyright (C) The Internet Society (2006). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Harrison Standards Track [Page 34] PK (�c\��x�m� m� ( doc/alt-openldap11-devel/rfc/rfc4517.txtnu �[��� Network Working Group S. Legg, Ed. Request for Comments: 4517 eB2Bcom Obsoletes: 2252, 2256 June 2006 Updates: 3698 Category: Standards Track Lightweight Directory Access Protocol (LDAP): Syntaxes and Matching Rules Status of This Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2006). Abstract Each attribute stored in a Lightweight Directory Access Protocol (LDAP) directory, whose values may be transferred in the LDAP protocol, has a defined syntax that constrains the structure and format of its values. The comparison semantics for values of a syntax are not part of the syntax definition but are instead provided through separately defined matching rules. Matching rules specify an argument, an assertion value, which also has a defined syntax. This document defines a base set of syntaxes and matching rules for use in defining attributes for LDAP directories. Table of Contents 1. Introduction ....................................................3 2. Conventions .....................................................4 3. Syntaxes ........................................................4 3.1. General Considerations .....................................5 3.2. Common Definitions .........................................5 3.3. Syntax Definitions .........................................6 3.3.1. Attribute Type Description ..........................6 3.3.2. Bit String ..........................................6 3.3.3. Boolean .............................................7 3.3.4. Country String ......................................7 3.3.5. Delivery Method .....................................8 Legg Standards Track [Page 1] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 3.3.6. Directory String ....................................8 3.3.7. DIT Content Rule Description ........................9 3.3.8. DIT Structure Rule Description .....................10 3.3.9. DN .................................................10 3.3.10. Enhanced Guide ....................................11 3.3.11. Facsimile Telephone Number ........................12 3.3.12. Fax ...............................................12 3.3.13. Generalized Time ..................................13 3.3.14. Guide .............................................14 3.3.15. IA5 String ........................................15 3.3.16. Integer ...........................................15 3.3.17. JPEG ..............................................15 3.3.18. LDAP Syntax Description ...........................16 3.3.19. Matching Rule Description .........................16 3.3.20. Matching Rule Use Description .....................17 3.3.21. Name and Optional UID .............................17 3.3.22. Name Form Description .............................18 3.3.23. Numeric String ....................................18 3.3.24. Object Class Description ..........................18 3.3.25. Octet String ......................................19 3.3.26. OID ...............................................19 3.3.27. Other Mailbox .....................................20 3.3.28. Postal Address ....................................20 3.3.29. Printable String ..................................21 3.3.30. Substring Assertion ...............................22 3.3.31. Telephone Number ..................................23 3.3.32. Teletex Terminal Identifier .......................23 3.3.33. Telex Number ......................................24 3.3.34. UTC Time ..........................................24 4. Matching Rules .................................................25 4.1. General Considerations ....................................25 4.2. Matching Rule Definitions .................................27 4.2.1. bitStringMatch .....................................27 4.2.2. booleanMatch .......................................28 4.2.3. caseExactIA5Match ..................................28 4.2.4. caseExactMatch .....................................29 4.2.5. caseExactOrderingMatch .............................29 4.2.6. caseExactSubstringsMatch ...........................30 4.2.7. caseIgnoreIA5Match .................................30 4.2.8. caseIgnoreIA5SubstringsMatch .......................31 4.2.9. caseIgnoreListMatch ................................31 4.2.10. caseIgnoreListSubstringsMatch .....................32 4.2.11. caseIgnoreMatch ...................................33 4.2.12. caseIgnoreOrderingMatch ...........................33 4.2.13. caseIgnoreSubstringsMatch .........................34 4.2.14. directoryStringFirstComponentMatch ................34 4.2.15. distinguishedNameMatch ............................35 4.2.16. generalizedTimeMatch ..............................36 Legg Standards Track [Page 2] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 4.2.17. generalizedTimeOrderingMatch ......................36 4.2.18. integerFirstComponentMatch ........................36 4.2.19. integerMatch ......................................37 4.2.20. integerOrderingMatch ..............................37 4.2.21. keywordMatch ......................................38 4.2.22. numericStringMatch ................................38 4.2.23. numericStringOrderingMatch ........................39 4.2.24. numericStringSubstringsMatch ......................39 4.2.25. objectIdentifierFirstComponentMatch ...............40 4.2.26. objectIdentifierMatch .............................40 4.2.27. octetStringMatch ..................................41 4.2.28. octetStringOrderingMatch ..........................41 4.2.29. telephoneNumberMatch ..............................42 4.2.30. telephoneNumberSubstringsMatch ....................42 4.2.31. uniqueMemberMatch .................................43 4.2.32. wordMatch .........................................44 5. Security Considerations ........................................44 6. Acknowledgements ...............................................44 7. IANA Considerations ............................................45 8. References .....................................................46 8.1. Normative References ......................................46 8.2. Informative References ....................................48 Appendix A. Summary of Syntax Object Identifiers ..................49 Appendix B. Changes from RFC 2252 .................................49 1. Introduction Each attribute stored in a Lightweight Directory Access Protocol (LDAP) directory [RFC4510], whose values may be transferred in the LDAP protocol [RFC4511], has a defined syntax (i.e., data type) that constrains the structure and format of its values. The comparison semantics for values of a syntax are not part of the syntax definition but are instead provided through separately defined matching rules. Matching rules specify an argument, an assertion value, which also has a defined syntax. This document defines a base set of syntaxes and matching rules for use in defining attributes for LDAP directories. Readers are advised to familiarize themselves with the Directory Information Models [RFC4512] before reading the rest of this document. Section 3 provides definitions for the base set of LDAP syntaxes. Section 4 provides definitions for the base set of matching rules for LDAP. This document is an integral part of the LDAP technical specification [RFC4510], which obsoletes the previously defined LDAP technical specification, RFC 3377, in its entirety. Legg Standards Track [Page 3] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 Sections 4, 5, and 7 of RFC 2252 are obsoleted by [RFC4512]. The remainder of RFC 2252 is obsoleted by this document. Sections 6 and 8 of RFC 2256 are obsoleted by this document. The remainder of RFC 2256 is obsoleted by [RFC4519] and [RFC4512]. All but Section 2.11 of RFC 3698 is obsoleted by this document. A number of schema elements that were included in the previous revision of the LDAP technical specification are not included in this revision of LDAP. Public Key Infrastructure schema elements are now specified in [RFC4523]. Unless reintroduced in future technical specifications, the remainder are to be considered Historic. The changes with respect to RFC 2252 are described in Appendix B of this document. 2. Conventions In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in BCP 14, RFC 2119 [RFC2119]. Syntax definitions are written according to the <SyntaxDescription> ABNF [RFC4234] rule specified in [RFC4512], and matching rule definitions are written according to the <MatchingRuleDescription> ABNF rule specified in [RFC4512], except that the syntax and matching rule definitions provided in this document are line-wrapped for readability. When such definitions are transferred as attribute values in the LDAP protocol (e.g., as values of the ldapSyntaxes and matchingRules attributes [RFC4512], respectively), then those values would not contain line breaks. 3. Syntaxes Syntax definitions constrain the structure of attribute values stored in an LDAP directory, and determine the representation of attribute and assertion values transferred in the LDAP protocol. Syntaxes that are required for directory operation, or that are in common use, are specified in this section. Servers SHOULD recognize all the syntaxes listed in this document, but are not required to otherwise support them, and MAY recognise or support other syntaxes. However, the definition of additional arbitrary syntaxes is discouraged since it will hinder interoperability. Client and server implementations typically do not have the ability to dynamically recognize new syntaxes. Legg Standards Track [Page 4] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 3.1. General Considerations The description of each syntax specifies how attribute or assertion values conforming to the syntax are to be represented when transferred in the LDAP protocol [RFC4511]. This representation is referred to as the LDAP-specific encoding to distinguish it from other methods of encoding attribute values (e.g., the Basic Encoding Rules (BER) encoding [BER] used by X.500 [X.500] directories). The LDAP-specific encoding of a given attribute syntax always produces octet-aligned values. To the greatest extent possible, encoding rules for LDAP syntaxes should produce character strings that can be displayed with little or no translation by clients implementing LDAP. However, clients MUST NOT assume that the LDAP- specific encoding of a value of an unrecognized syntax is a human- readable character string. There are a few cases (e.g., the JPEG syntax) when it is not reasonable to produce a human-readable representation. Each LDAP syntax is uniquely identified with an object identifier [ASN.1] represented in the dotted-decimal format (short descriptive names are not defined for syntaxes). These object identifiers are not intended to be displayed to users. The object identifiers for the syntaxes defined in this document are summarized in Appendix A. A suggested minimum upper bound on the number of characters in an attribute value with a string-based syntax, or the number of octets in a value for all other syntaxes, MAY be indicated by appending the bound inside of curly braces following the syntax's OBJECT IDENTIFIER in an attribute type definition (see the <noidlen> rule in [RFC4512]). Such a bound is not considered part of the syntax identifier. For example, "1.3.6.1.4.1.1466.115.121.1.15{64}" in an attribute definition suggests that the directory server will allow a value of the attribute to be up to 64 characters long, although it may allow longer character strings. Note that a single character of the Directory String syntax can be encoded in more than one octet, since UTF-8 [RFC3629] is a variable-length encoding. Therefore, a 64- character string may be more than 64 octets in length. 3.2. Common Definitions The following ABNF rules are used in a number of the syntax definitions in Section 3.3. PrintableCharacter = ALPHA / DIGIT / SQUOTE / LPAREN / RPAREN / PLUS / COMMA / HYPHEN / DOT / EQUALS / Legg Standards Track [Page 5] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 SLASH / COLON / QUESTION / SPACE PrintableString = 1*PrintableCharacter IA5String = *(%x00-7F) SLASH = %x2F ; forward slash ("/") COLON = %x3A ; colon (":") QUESTION = %x3F ; question mark ("?") The <ALPHA>, <DIGIT>, <SQUOTE>, <LPAREN>, <RPAREN>, <PLUS>, <COMMA>, <HYPHEN>, <DOT>, <EQUALS>, and <SPACE> rules are defined in [RFC4512]. 3.3. Syntax Definitions 3.3.1. Attribute Type Description A value of the Attribute Type Description syntax is the definition of an attribute type. The LDAP-specific encoding of a value of this syntax is defined by the <AttributeTypeDescription> rule in [RFC4512]. For example, the following definition of the createTimestamp attribute type from [RFC4512] is also a value of the Attribute Type Description syntax. (Note: Line breaks have been added for readability; they are not part of the value when transferred in protocol.) ( 2.5.18.1 NAME 'createTimestamp' EQUALITY generalizedTimeMatch ORDERING generalizedTimeOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 SINGLE-VALUE NO-USER-MODIFICATION USAGE directoryOperation ) The LDAP definition for the Attribute Type Description syntax is: ( 1.3.6.1.4.1.1466.115.121.1.3 DESC 'Attribute Type Description' ) This syntax corresponds to the AttributeTypeDescription ASN.1 type from [X.501]. 3.3.2. Bit String A value of the Bit String syntax is a sequence of binary digits. The LDAP-specific encoding of a value of this syntax is defined by the following ABNF: BitString = SQUOTE *binary-digit SQUOTE "B" binary-digit = "0" / "1" Legg Standards Track [Page 6] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 The <SQUOTE> rule is defined in [RFC4512]. Example: '0101111101'B The LDAP definition for the Bit String syntax is: ( 1.3.6.1.4.1.1466.115.121.1.6 DESC 'Bit String' ) This syntax corresponds to the BIT STRING ASN.1 type from [ASN.1]. 3.3.3. Boolean A value of the Boolean syntax is one of the Boolean values, true or false. The LDAP-specific encoding of a value of this syntax is defined by the following ABNF: Boolean = "TRUE" / "FALSE" The LDAP definition for the Boolean syntax is: ( 1.3.6.1.4.1.1466.115.121.1.7 DESC 'Boolean' ) This syntax corresponds to the BOOLEAN ASN.1 type from [ASN.1]. 3.3.4. Country String A value of the Country String syntax is one of the two-character codes from ISO 3166 [ISO3166] for representing a country. The LDAP- specific encoding of a value of this syntax is defined by the following ABNF: CountryString = 2(PrintableCharacter) The <PrintableCharacter> rule is defined in Section 3.2. Examples: US AU The LDAP definition for the Country String syntax is: ( 1.3.6.1.4.1.1466.115.121.1.11 DESC 'Country String' ) This syntax corresponds to the following ASN.1 type from [X.520]: PrintableString (SIZE (2)) -- ISO 3166 codes only Legg Standards Track [Page 7] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 3.3.5. Delivery Method A value of the Delivery Method syntax is a sequence of items that indicate, in preference order, the service(s) by which an entity is willing and/or capable of receiving messages. The LDAP-specific encoding of a value of this syntax is defined by the following ABNF: DeliveryMethod = pdm *( WSP DOLLAR WSP pdm ) pdm = "any" / "mhs" / "physical" / "telex" / "teletex" / "g3fax" / "g4fax" / "ia5" / "videotex" / "telephone" The <WSP> and <DOLLAR> rules are defined in [RFC4512]. Example: telephone $ videotex The LDAP definition for the Delivery Method syntax is: ( 1.3.6.1.4.1.1466.115.121.1.14 DESC 'Delivery Method' ) This syntax corresponds to the following ASN.1 type from [X.520]: SEQUENCE OF INTEGER { any-delivery-method (0), mhs-delivery (1), physical-delivery (2), telex-delivery (3), teletex-delivery (4), g3-facsimile-delivery (5), g4-facsimile-delivery (6), ia5-terminal-delivery (7), videotex-delivery (8), telephone-delivery (9) } 3.3.6. Directory String A value of the Directory String syntax is a string of one or more arbitrary characters from the Universal Character Set (UCS) [UCS]. A zero-length character string is not permitted. The LDAP-specific encoding of a value of this syntax is the UTF-8 encoding [RFC3629] of the character string. Such encodings conform to the following ABNF: DirectoryString = 1*UTF8 The <UTF8> rule is defined in [RFC4512]. Legg Standards Track [Page 8] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 Example: This is a value of Directory String containing #!%#@. Servers and clients MUST be prepared to receive arbitrary UCS code points, including code points outside the range of printable ASCII and code points not presently assigned to any character. Attribute type definitions using the Directory String syntax should not restrict the format of Directory String values, e.g., by requiring that the character string conforms to specific patterns described by ABNF. A new syntax should be defined in such cases. The LDAP definition for the Directory String syntax is: ( 1.3.6.1.4.1.1466.115.121.1.15 DESC 'Directory String' ) This syntax corresponds to the DirectoryString parameterized ASN.1 type from [X.520]. The DirectoryString ASN.1 type allows a choice between the TeletexString, PrintableString, or UniversalString ASN.1 types from [ASN.1]. However, note that the chosen alternative is not indicated in the LDAP-specific encoding of a Directory String value. Implementations that convert Directory String values from the LDAP- specific encoding to the BER encoding used by X.500 must choose an alternative that permits the particular characters in the string and must convert the characters from the UTF-8 encoding into the character encoding of the chosen alternative. When converting Directory String values from the BER encoding to the LDAP-specific encoding, the characters must be converted from the character encoding of the chosen alternative into the UTF-8 encoding. These conversions SHOULD be done in a manner consistent with the Transcode step of the string preparation algorithms [RFC4518] for LDAP. 3.3.7. DIT Content Rule Description A value of the DIT Content Rule Description syntax is the definition of a DIT (Directory Information Tree) content rule. The LDAP- specific encoding of a value of this syntax is defined by the <DITContentRuleDescription> rule in [RFC4512]. Example: ( 2.5.6.4 DESC 'content rule for organization' NOT ( x121Address $ telexNumber ) ) Note: A line break has been added for readability; it is not part of the value. Legg Standards Track [Page 9] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 The LDAP definition for the DIT Content Rule Description syntax is: ( 1.3.6.1.4.1.1466.115.121.1.16 DESC 'DIT Content Rule Description' ) This syntax corresponds to the DITContentRuleDescription ASN.1 type from [X.501]. 3.3.8. DIT Structure Rule Description A value of the DIT Structure Rule Description syntax is the definition of a DIT structure rule. The LDAP-specific encoding of a value of this syntax is defined by the <DITStructureRuleDescription> rule in [RFC4512]. Example: ( 2 DESC 'organization structure rule' FORM 2.5.15.3 ) The LDAP definition for the DIT Structure Rule Description syntax is: ( 1.3.6.1.4.1.1466.115.121.1.17 DESC 'DIT Structure Rule Description' ) This syntax corresponds to the DITStructureRuleDescription ASN.1 type from [X.501]. 3.3.9. DN A value of the DN syntax is the (purported) distinguished name (DN) of an entry [RFC4512]. The LDAP-specific encoding of a value of this syntax is defined by the <distinguishedName> rule from the string representation of distinguished names [RFC4514]. Examples (from [RFC4514]): UID=jsmith,DC=example,DC=net OU=Sales+CN=J. Smith,DC=example,DC=net CN=John Smith\, III,DC=example,DC=net CN=Before\0dAfter,DC=example,DC=net 1.3.6.1.4.1.1466.0=#04024869,DC=example,DC=com CN=Lu\C4\8Di\C4\87 The LDAP definition for the DN syntax is: ( 1.3.6.1.4.1.1466.115.121.1.12 DESC 'DN' ) The DN syntax corresponds to the DistinguishedName ASN.1 type from [X.501]. Note that a BER encoded distinguished name (as used by X.500) re-encoded into the LDAP-specific encoding is not necessarily Legg Standards Track [Page 10] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 reversible to the original BER encoding since the chosen string type in any DirectoryString components of the distinguished name is not indicated in the LDAP-specific encoding of the distinguished name (see Section 3.3.6). 3.3.10. Enhanced Guide A value of the Enhanced Guide syntax suggests criteria, which consist of combinations of attribute types and filter operators, to be used in constructing filters to search for entries of particular object classes. The Enhanced Guide syntax improves upon the Guide syntax by allowing the recommended depth of the search to be specified. The LDAP-specific encoding of a value of this syntax is defined by the following ABNF: EnhancedGuide = object-class SHARP WSP criteria WSP SHARP WSP subset object-class = WSP oid WSP subset = "baseobject" / "oneLevel" / "wholeSubtree" criteria = and-term *( BAR and-term ) and-term = term *( AMPERSAND term ) term = EXCLAIM term / attributetype DOLLAR match-type / LPAREN criteria RPAREN / true / false match-type = "EQ" / "SUBSTR" / "GE" / "LE" / "APPROX" true = "?true" false = "?false" BAR = %x7C ; vertical bar ("|") AMPERSAND = %x26 ; ampersand ("&") EXCLAIM = %x21 ; exclamation mark ("!") The <SHARP>, <WSP>, <oid>, <LPAREN>, <RPAREN>, <attributetype>, and <DOLLAR> rules are defined in [RFC4512]. The LDAP definition for the Enhanced Guide syntax is: ( 1.3.6.1.4.1.1466.115.121.1.21 DESC 'Enhanced Guide' ) Example: person#(sn$EQ)#oneLevel The Enhanced Guide syntax corresponds to the EnhancedGuide ASN.1 type from [X.520]. The EnhancedGuide type references the Criteria ASN.1 type, also from [X.520]. The <true> rule, above, represents an empty Legg Standards Track [Page 11] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 "and" expression in a value of the Criteria type. The <false> rule, above, represents an empty "or" expression in a value of the Criteria type. 3.3.11. Facsimile Telephone Number A value of the Facsimile Telephone Number syntax is a subscriber number of a facsimile device on the public switched telephone network. The LDAP-specific encoding of a value of this syntax is defined by the following ABNF: fax-number = telephone-number *( DOLLAR fax-parameter ) telephone-number = PrintableString fax-parameter = "twoDimensional" / "fineResolution" / "unlimitedLength" / "b4Length" / "a3Width" / "b4Width" / "uncompressed" The <telephone-number> is a string of printable characters that complies with the internationally agreed format for representing international telephone numbers [E.123]. The <PrintableString> rule is defined in Section 3.2. The <DOLLAR> rule is defined in [RFC4512]. The LDAP definition for the Facsimile Telephone Number syntax is: ( 1.3.6.1.4.1.1466.115.121.1.22 DESC 'Facsimile Telephone Number') The Facsimile Telephone Number syntax corresponds to the FacsimileTelephoneNumber ASN.1 type from [X.520]. 3.3.12. Fax A value of the Fax syntax is an image that is produced using the Group 3 facsimile process [FAX] to duplicate an object, such as a memo. The LDAP-specific encoding of a value of this syntax is the string of octets for a Group 3 Fax image as defined in [FAX]. The LDAP definition for the Fax syntax is: ( 1.3.6.1.4.1.1466.115.121.1.23 DESC 'Fax' ) The ASN.1 type corresponding to the Fax syntax is defined as follows, assuming EXPLICIT TAGS: Legg Standards Track [Page 12] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 Fax ::= CHOICE { g3-facsimile [3] G3FacsimileBodyPart } The G3FacsimileBodyPart ASN.1 type is defined in [X.420]. 3.3.13. Generalized Time A value of the Generalized Time syntax is a character string representing a date and time. The LDAP-specific encoding of a value of this syntax is a restriction of the format defined in [ISO8601], and is described by the following ABNF: GeneralizedTime = century year month day hour [ minute [ second / leap-second ] ] [ fraction ] g-time-zone century = 2(%x30-39) ; "00" to "99" year = 2(%x30-39) ; "00" to "99" month = ( %x30 %x31-39 ) ; "01" (January) to "09" / ( %x31 %x30-32 ) ; "10" to "12" day = ( %x30 %x31-39 ) ; "01" to "09" / ( %x31-32 %x30-39 ) ; "10" to "29" / ( %x33 %x30-31 ) ; "30" to "31" hour = ( %x30-31 %x30-39 ) / ( %x32 %x30-33 ) ; "00" to "23" minute = %x30-35 %x30-39 ; "00" to "59" second = ( %x30-35 %x30-39 ) ; "00" to "59" leap-second = ( %x36 %x30 ) ; "60" fraction = ( DOT / COMMA ) 1*(%x30-39) g-time-zone = %x5A ; "Z" / g-differential g-differential = ( MINUS / PLUS ) hour [ minute ] MINUS = %x2D ; minus sign ("-") The <DOT>, <COMMA>, and <PLUS> rules are defined in [RFC4512]. The above ABNF allows character strings that do not represent valid dates (in the Gregorian calendar) and/or valid times (e.g., February 31, 1994). Such character strings SHOULD be considered invalid for this syntax. The time value represents coordinated universal time (equivalent to Greenwich Mean Time) if the "Z" form of <g-time-zone> is used; otherwise, the value represents a local time in the time zone indicated by <g-differential>. In the latter case, coordinated Legg Standards Track [Page 13] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 universal time can be calculated by subtracting the differential from the local time. The "Z" form of <g-time-zone> SHOULD be used in preference to <g-differential>. If <minute> is omitted, then <fraction> represents a fraction of an hour; otherwise, if <second> and <leap-second> are omitted, then <fraction> represents a fraction of a minute; otherwise, <fraction> represents a fraction of a second. Examples: 199412161032Z 199412160532-0500 Both example values represent the same coordinated universal time: 10:32 AM, December 16, 1994. The LDAP definition for the Generalized Time syntax is: ( 1.3.6.1.4.1.1466.115.121.1.24 DESC 'Generalized Time' ) This syntax corresponds to the GeneralizedTime ASN.1 type from [ASN.1], with the constraint that local time without a differential SHALL NOT be used. 3.3.14. Guide A value of the Guide syntax suggests criteria, which consist of combinations of attribute types and filter operators, to be used in constructing filters to search for entries of particular object classes. The Guide syntax is obsolete and should not be used for defining new attribute types. The LDAP-specific encoding of a value of this syntax is defined by the following ABNF: Guide = [ object-class SHARP ] criteria The <object-class> and <criteria> rules are defined in Section 3.3.10. The <SHARP> rule is defined in [RFC4512]. The LDAP definition for the Guide syntax is: ( 1.3.6.1.4.1.1466.115.121.1.25 DESC 'Guide' ) The Guide syntax corresponds to the Guide ASN.1 type from [X.520]. Legg Standards Track [Page 14] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 3.3.15. IA5 String A value of the IA5 String syntax is a string of zero, one, or more characters from International Alphabet 5 (IA5) [T.50], the international version of the ASCII character set. The LDAP-specific encoding of a value of this syntax is the unconverted string of characters, which conforms to the <IA5String> rule in Section 3.2. The LDAP definition for the IA5 String syntax is: ( 1.3.6.1.4.1.1466.115.121.1.26 DESC 'IA5 String' ) This syntax corresponds to the IA5String ASN.1 type from [ASN.1]. 3.3.16. Integer A value of the Integer syntax is a whole number of unlimited magnitude. The LDAP-specific encoding of a value of this syntax is the optionally signed decimal digit character string representation of the number (for example, the number 1321 is represented by the character string "1321"). The encoding is defined by the following ABNF: Integer = ( HYPHEN LDIGIT *DIGIT ) / number The <HYPHEN>, <LDIGIT>, <DIGIT>, and <number> rules are defined in [RFC4512]. The LDAP definition for the Integer syntax is: ( 1.3.6.1.4.1.1466.115.121.1.27 DESC 'INTEGER' ) This syntax corresponds to the INTEGER ASN.1 type from [ASN.1]. 3.3.17. JPEG A value of the JPEG syntax is an image in the JPEG File Interchange Format (JFIF), as described in [JPEG]. The LDAP-specific encoding of a value of this syntax is the sequence of octets of the JFIF encoding of the image. The LDAP definition for the JPEG syntax is: ( 1.3.6.1.4.1.1466.115.121.1.28 DESC 'JPEG' ) The JPEG syntax corresponds to the following ASN.1 type: Legg Standards Track [Page 15] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 JPEG ::= OCTET STRING (CONSTRAINED BY { -- contents octets are an image in the -- -- JPEG File Interchange Format -- }) 3.3.18. LDAP Syntax Description A value of the LDAP Syntax Description syntax is the description of an LDAP syntax. The LDAP-specific encoding of a value of this syntax is defined by the <SyntaxDescription> rule in [RFC4512]. The LDAP definition for the LDAP Syntax Description syntax is: ( 1.3.6.1.4.1.1466.115.121.1.54 DESC 'LDAP Syntax Description' ) The above LDAP definition for the LDAP Syntax Description syntax is itself a legal value of the LDAP Syntax Description syntax. The ASN.1 type corresponding to the LDAP Syntax Description syntax is defined as follows, assuming EXPLICIT TAGS: LDAPSyntaxDescription ::= SEQUENCE { identifier OBJECT IDENTIFIER, description DirectoryString { ub-schema } OPTIONAL } The DirectoryString parameterized ASN.1 type is defined in [X.520]. The value of ub-schema (an integer) is implementation defined. A non-normative definition appears in [X.520]. 3.3.19. Matching Rule Description A value of the Matching Rule Description syntax is the definition of a matching rule. The LDAP-specific encoding of a value of this syntax is defined by the <MatchingRuleDescription> rule in [RFC4512]. Example: ( 2.5.13.2 NAME 'caseIgnoreMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) Note: A line break has been added for readability; it is not part of the syntax. The LDAP definition for the Matching Rule Description syntax is: ( 1.3.6.1.4.1.1466.115.121.1.30 DESC 'Matching Rule Description' ) This syntax corresponds to the MatchingRuleDescription ASN.1 type from [X.501]. Legg Standards Track [Page 16] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 3.3.20. Matching Rule Use Description A value of the Matching Rule Use Description syntax indicates the attribute types to which a matching rule may be applied in an extensibleMatch search filter [RFC4511]. The LDAP-specific encoding of a value of this syntax is defined by the <MatchingRuleUseDescription> rule in [RFC4512]. Example: ( 2.5.13.16 APPLIES ( givenName $ surname ) ) The LDAP definition for the Matching Rule Use Description syntax is: ( 1.3.6.1.4.1.1466.115.121.1.31 DESC 'Matching Rule Use Description' ) This syntax corresponds to the MatchingRuleUseDescription ASN.1 type from [X.501]. 3.3.21. Name and Optional UID A value of the Name and Optional UID syntax is the distinguished name [RFC4512] of an entity optionally accompanied by a unique identifier that serves to differentiate the entity from others with an identical distinguished name. The LDAP-specific encoding of a value of this syntax is defined by the following ABNF: NameAndOptionalUID = distinguishedName [ SHARP BitString ] The <BitString> rule is defined in Section 3.3.2. The <distinguishedName> rule is defined in [RFC4514]. The <SHARP> rule is defined in [RFC4512]. Note that although the '#' character may occur in the string representation of a distinguished name, no additional escaping of this character is performed when a <distinguishedName> is encoded in a <NameAndOptionalUID>. Example: 1.3.6.1.4.1.1466.0=#04024869,O=Test,C=GB#'0101'B The LDAP definition for the Name and Optional UID syntax is: ( 1.3.6.1.4.1.1466.115.121.1.34 DESC 'Name And Optional UID' ) Legg Standards Track [Page 17] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 This syntax corresponds to the NameAndOptionalUID ASN.1 type from [X.520]. 3.3.22. Name Form Description A value of the Name Form Description syntax is the definition of a name form, which regulates how entries may be named. The LDAP- specific encoding of a value of this syntax is defined by the <NameFormDescription> rule in [RFC4512]. Example: ( 2.5.15.3 NAME 'orgNameForm' OC organization MUST o ) The LDAP definition for the Name Form Description syntax is: ( 1.3.6.1.4.1.1466.115.121.1.35 DESC 'Name Form Description' ) This syntax corresponds to the NameFormDescription ASN.1 type from [X.501]. 3.3.23. Numeric String A value of the Numeric String syntax is a sequence of one or more numerals and spaces. The LDAP-specific encoding of a value of this syntax is the unconverted string of characters, which conforms to the following ABNF: NumericString = 1*(DIGIT / SPACE) The <DIGIT> and <SPACE> rules are defined in [RFC4512]. Example: 15 079 672 281 The LDAP definition for the Numeric String syntax is: ( 1.3.6.1.4.1.1466.115.121.1.36 DESC 'Numeric String' ) This syntax corresponds to the NumericString ASN.1 type from [ASN.1]. 3.3.24. Object Class Description A value of the Object Class Description syntax is the definition of an object class. The LDAP-specific encoding of a value of this syntax is defined by the <ObjectClassDescription> rule in [RFC4512]. Legg Standards Track [Page 18] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 Example: ( 2.5.6.2 NAME 'country' SUP top STRUCTURAL MUST c MAY ( searchGuide $ description ) ) Note: A line break has been added for readability; it is not part of the syntax. The LDAP definition for the Object Class Description syntax is: ( 1.3.6.1.4.1.1466.115.121.1.37 DESC 'Object Class Description' ) This syntax corresponds to the ObjectClassDescription ASN.1 type from [X.501]. 3.3.25. Octet String A value of the Octet String syntax is a sequence of zero, one, or more arbitrary octets. The LDAP-specific encoding of a value of this syntax is the unconverted sequence of octets, which conforms to the following ABNF: OctetString = *OCTET The <OCTET> rule is defined in [RFC4512]. Values of this syntax are not generally human-readable. The LDAP definition for the Octet String syntax is: ( 1.3.6.1.4.1.1466.115.121.1.40 DESC 'Octet String' ) This syntax corresponds to the OCTET STRING ASN.1 type from [ASN.1]. 3.3.26. OID A value of the OID syntax is an object identifier: a sequence of two or more non-negative integers that uniquely identify some object or item of specification. Many of the object identifiers used in LDAP also have IANA registered names [RFC4520]. The LDAP-specific encoding of a value of this syntax is defined by the <oid> rule in [RFC4512]. Examples: 1.2.3.4 cn The LDAP definition for the OID syntax is: Legg Standards Track [Page 19] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 ( 1.3.6.1.4.1.1466.115.121.1.38 DESC 'OID' ) This syntax corresponds to the OBJECT IDENTIFIER ASN.1 type from [ASN.1]. 3.3.27. Other Mailbox A value of the Other Mailbox syntax identifies an electronic mailbox, in a particular named mail system. The LDAP-specific encoding of a value of this syntax is defined by the following ABNF: OtherMailbox = mailbox-type DOLLAR mailbox mailbox-type = PrintableString mailbox = IA5String The <mailbox-type> rule represents the type of mail system in which the mailbox resides (for example, "MCIMail"), and <mailbox> is the actual mailbox in the mail system described by <mailbox-type>. The <PrintableString> and <IA5String> rules are defined in Section 3.2. The <DOLLAR> rule is defined in [RFC4512]. The LDAP definition for the Other Mailbox syntax is: ( 1.3.6.1.4.1.1466.115.121.1.39 DESC 'Other Mailbox' ) The ASN.1 type corresponding to the Other Mailbox syntax is defined as follows, assuming EXPLICIT TAGS: OtherMailbox ::= SEQUENCE { mailboxType PrintableString, mailbox IA5String } 3.3.28. Postal Address A value of the Postal Address syntax is a sequence of strings of one or more arbitrary UCS characters, which form an address in a physical mail system. The LDAP-specific encoding of a value of this syntax is defined by the following ABNF: Legg Standards Track [Page 20] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 PostalAddress = line *( DOLLAR line ) line = 1*line-char line-char = %x00-23 / (%x5C "24") ; escaped "$" / %x25-5B / (%x5C "5C") ; escaped "\" / %x5D-7F / UTFMB Each character string (i.e., <line>) of a postal address value is encoded as a UTF-8 [RFC3629] string, except that "\" and "$" characters, if they occur in the string, are escaped by a "\" character followed by the two hexadecimal digit code for the character. The <DOLLAR> and <UTFMB> rules are defined in [RFC4512]. Many servers limit the postal address to no more than six lines of no more than thirty characters each. Example: 1234 Main St.$Anytown, CA 12345$USA \241,000,000 Sweepstakes$PO Box 1000000$Anytown, CA 12345$USA The LDAP definition for the Postal Address syntax is: ( 1.3.6.1.4.1.1466.115.121.1.41 DESC 'Postal Address' ) This syntax corresponds to the PostalAddress ASN.1 type from [X.520]; that is PostalAddress ::= SEQUENCE SIZE(1..ub-postal-line) OF DirectoryString { ub-postal-string } The values of ub-postal-line and ub-postal-string (both integers) are implementation defined. Non-normative definitions appear in [X.520]. 3.3.29. Printable String A value of the Printable String syntax is a string of one or more latin alphabetic, numeric, and selected punctuation characters as specified by the <PrintableCharacter> rule in Section 3.2. The LDAP-specific encoding of a value of this syntax is the unconverted string of characters, which conforms to the <PrintableString> rule in Section 3.2. Example: This is a PrintableString. Legg Standards Track [Page 21] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 The LDAP definition for the PrintableString syntax is: ( 1.3.6.1.4.1.1466.115.121.1.44 DESC 'Printable String' ) This syntax corresponds to the PrintableString ASN.1 type from [ASN.1]. 3.3.30. Substring Assertion A value of the Substring Assertion syntax is a sequence of zero, one, or more character substrings used as an argument for substring extensible matching of character string attribute values; i.e., as the matchValue of a MatchingRuleAssertion [RFC4511]. Each substring is a string of one or more arbitrary characters from the Universal Character Set (UCS) [UCS]. A zero-length substring is not permitted. The LDAP-specific encoding of a value of this syntax is defined by the following ABNF: SubstringAssertion = [ initial ] any [ final ] initial = substring any = ASTERISK *(substring ASTERISK) final = substring ASTERISK = %x2A ; asterisk ("*") substring = 1*substring-character substring-character = %x00-29 / (%x5C "2A") ; escaped "*" / %x2B-5B / (%x5C "5C") ; escaped "\" / %x5D-7F / UTFMB Each <substring> of a Substring Assertion value is encoded as a UTF-8 [RFC3629] string, except that "\" and "*" characters, if they occur in the substring, are escaped by a "\" character followed by the two hexadecimal digit code for the character. The Substring Assertion syntax is used only as the syntax of assertion values in the extensible match. It is not used as an attribute syntax, or in the SubstringFilter [RFC4511]. The LDAP definition for the Substring Assertion syntax is: ( 1.3.6.1.4.1.1466.115.121.1.58 DESC 'Substring Assertion' ) Legg Standards Track [Page 22] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 This syntax corresponds to the SubstringAssertion ASN.1 type from [X.520]. 3.3.31. Telephone Number A value of the Telephone Number syntax is a string of printable characters that complies with the internationally agreed format for representing international telephone numbers [E.123]. The LDAP-specific encoding of a value of this syntax is the unconverted string of characters, which conforms to the <PrintableString> rule in Section 3.2. Examples: +1 512 315 0280 +1-512-315-0280 +61 3 9896 7830 The LDAP definition for the Telephone Number syntax is: ( 1.3.6.1.4.1.1466.115.121.1.50 DESC 'Telephone Number' ) The Telephone Number syntax corresponds to the following ASN.1 type from [X.520]: PrintableString (SIZE(1..ub-telephone-number)) The value of ub-telephone-number (an integer) is implementation defined. A non-normative definition appears in [X.520]. 3.3.32. Teletex Terminal Identifier A value of this syntax specifies the identifier and (optionally) parameters of a teletex terminal. The LDAP-specific encoding of a value of this syntax is defined by the following ABNF: teletex-id = ttx-term *(DOLLAR ttx-param) ttx-term = PrintableString ; terminal identifier ttx-param = ttx-key COLON ttx-value ; parameter ttx-key = "graphic" / "control" / "misc" / "page" / "private" ttx-value = *ttx-value-octet ttx-value-octet = %x00-23 / (%x5C "24") ; escaped "$" / %x25-5B / (%x5C "5C") ; escaped "\" Legg Standards Track [Page 23] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 / %x5D-FF The <PrintableString> and <COLON> rules are defined in Section 3.2. The <DOLLAR> rule is defined in [RFC4512]. The LDAP definition for the Teletex Terminal Identifier syntax is: ( 1.3.6.1.4.1.1466.115.121.1.51 DESC 'Teletex Terminal Identifier' ) This syntax corresponds to the TeletexTerminalIdentifier ASN.1 type from [X.520]. 3.3.33. Telex Number A value of the Telex Number syntax specifies the telex number, country code, and answerback code of a telex terminal. The LDAP-specific encoding of a value of this syntax is defined by the following ABNF: telex-number = actual-number DOLLAR country-code DOLLAR answerback actual-number = PrintableString country-code = PrintableString answerback = PrintableString The <PrintableString> rule is defined in Section 3.2. The <DOLLAR> rule is defined in [RFC4512]. The LDAP definition for the Telex Number syntax is: ( 1.3.6.1.4.1.1466.115.121.1.52 DESC 'Telex Number' ) This syntax corresponds to the TelexNumber ASN.1 type from [X.520]. 3.3.34. UTC Time A value of the UTC Time syntax is a character string representing a date and time to a precision of one minute or one second. The year is given as a two-digit number. The LDAP-specific encoding of a value of this syntax follows the format defined in [ASN.1] for the UTCTime type and is described by the following ABNF: UTCTime = year month day hour minute [ second ] [ u-time-zone ] u-time-zone = %x5A ; "Z" / u-differential Legg Standards Track [Page 24] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 u-differential = ( MINUS / PLUS ) hour minute The <year>, <month>, <day>, <hour>, <minute>, <second>, and <MINUS> rules are defined in Section 3.3.13. The <PLUS> rule is defined in [RFC4512]. The above ABNF allows character strings that do not represent valid dates (in the Gregorian calendar) and/or valid times. Such character strings SHOULD be considered invalid for this syntax. The time value represents coordinated universal time if the "Z" form of <u-time-zone> is used; otherwise, the value represents a local time. In the latter case, if <u-differential> is provided, then coordinated universal time can be calculated by subtracting the differential from the local time. The <u-time-zone> SHOULD be present in time values, and the "Z" form of <u-time-zone> SHOULD be used in preference to <u-differential>. The LDAP definition for the UTC Time syntax is: ( 1.3.6.1.4.1.1466.115.121.1.53 DESC 'UTC Time' ) Note: This syntax is deprecated in favor of the Generalized Time syntax. The UTC Time syntax corresponds to the UTCTime ASN.1 type from [ASN.1]. 4. Matching Rules Matching rules are used by directory implementations to compare attribute values against assertion values when performing Search and Compare operations [RFC4511]. They are also used when comparing a purported distinguished name [RFC4512] with the name of an entry. When modifying entries, matching rules are used to identify values to be deleted and to prevent an attribute from containing two equal values. Matching rules that are required for directory operation, or that are in common use, are specified in this section. 4.1. General Considerations A matching rule is applied to attribute values through an AttributeValueAssertion or MatchingRuleAssertion [RFC4511]. The conditions under which an AttributeValueAssertion or MatchingRuleAssertion evaluates to Undefined are specified elsewhere [RFC4511]. If an assertion is not Undefined, then the result of the Legg Standards Track [Page 25] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 assertion is the result of applying the selected matching rule. A matching rule evaluates to TRUE, and in some cases Undefined, as specified in the description of the matching rule; otherwise, it evaluates to FALSE. Each assertion contains an assertion value. The definition of each matching rule specifies the syntax for the assertion value. The syntax of the assertion value is typically, but not necessarily, the same as the syntax of the attribute values to which the matching rule may be applied. Note that an AssertionValue in a SubstringFilter [RFC4511] conforms to the assertion syntax of the equality matching rule for the attribute type rather than to the assertion syntax of the substrings matching rule for the attribute type. Conceptually, the entire SubstringFilter is converted into an assertion value of the substrings matching rule prior to applying the rule. The definition of each matching rule indicates the attribute syntaxes to which the rule may be applied, by specifying conditions the corresponding ASN.1 type of a candidate attribute syntax must satisfy. These conditions are also satisfied if the corresponding ASN.1 type is a tagged or constrained derivative of the ASN.1 type explicitly mentioned in the rule description (i.e., ASN.1 tags and constraints are ignored in checking applicability), or is an alternative reference notation for the explicitly mentioned type. Each rule description lists, as examples of applicable attribute syntaxes, the complete list of the syntaxes defined in this document to which the matching rule applies. A matching rule may be applicable to additional syntaxes defined in other documents if those syntaxes satisfy the conditions on the corresponding ASN.1 type. The description of each matching rule indicates whether the rule is suitable for use as the equality matching rule (EQUALITY), ordering matching rule (ORDERING), or substrings matching rule (SUBSTR) in an attribute type definition [RFC4512]. Each matching rule is uniquely identified with an object identifier. The definition of a matching rule should not subsequently be changed. If a change is desirable, then a new matching rule with a different object identifier should be defined instead. Servers MAY implement the wordMatch and keywordMatch matching rules, but they SHOULD implement the other matching rules in Section 4.2. Servers MAY implement additional matching rules. Servers that implement the extensibleMatch filter SHOULD allow the matching rules listed in Section 4.2 to be used in the extensibleMatch filter and SHOULD allow matching rules to be used with all attribute types known to the server, where the assertion Legg Standards Track [Page 26] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 syntax of the matching rule is the same as the value syntax of the attribute. Servers MUST publish, in the matchingRules attribute, the definitions of matching rules referenced by values of the attributeTypes and matchingRuleUse attributes in the same subschema entry. Other unreferenced matching rules MAY be published in the matchingRules attribute. If the server supports the extensibleMatch filter, then the server MAY use the matchingRuleUse attribute to indicate the applicability (in an extensibleMatch filter) of selected matching rules to nominated attribute types. 4.2. Matching Rule Definitions Nominated character strings in assertion and attribute values are prepared according to the string preparation algorithms [RFC4518] for LDAP when evaluating the following matching rules: numericStringMatch, numericStringSubstringsMatch, caseExactMatch, caseExactOrderingMatch, caseExactSubstringsMatch, caseExactIA5Match, caseIgnoreIA5Match, caseIgnoreIA5SubstringsMatch, caseIgnoreListMatch, caseIgnoreListSubstringsMatch, caseIgnoreMatch, caseIgnoreOrderingMatch, caseIgnoreSubstringsMatch, directoryStringFirstComponentMatch, telephoneNumberMatch, telephoneNumberSubstringsMatch and wordMatch. The Transcode, Normalize, Prohibit, and Check bidi steps are the same for each of the matching rules. However, the Map and Insignificant Character Handling steps depend on the specific rule, as detailed in the description of these matching rules in the sections that follow. 4.2.1. bitStringMatch The bitStringMatch rule compares an assertion value of the Bit String syntax to an attribute value of a syntax (e.g., the Bit String syntax) whose corresponding ASN.1 type is BIT STRING. Legg Standards Track [Page 27] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 If the corresponding ASN.1 type of the attribute syntax does not have a named bit list [ASN.1] (which is the case for the Bit String syntax), then the rule evaluates to TRUE if and only if the attribute value has the same number of bits as the assertion value and the bits match on a bitwise basis. If the corresponding ASN.1 type does have a named bit list, then bitStringMatch operates as above, except that trailing zero bits in the attribute and assertion values are treated as absent. The LDAP definition for the bitStringMatch rule is: ( 2.5.13.16 NAME 'bitStringMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.6 ) The bitStringMatch rule is an equality matching rule. 4.2.2. booleanMatch The booleanMatch rule compares an assertion value of the Boolean syntax to an attribute value of a syntax (e.g., the Boolean syntax) whose corresponding ASN.1 type is BOOLEAN. The rule evaluates to TRUE if and only if the attribute value and the assertion value are both TRUE or both FALSE. The LDAP definition for the booleanMatch rule is: ( 2.5.13.13 NAME 'booleanMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 ) The booleanMatch rule is an equality matching rule. 4.2.3. caseExactIA5Match The caseExactIA5Match rule compares an assertion value of the IA5 String syntax to an attribute value of a syntax (e.g., the IA5 String syntax) whose corresponding ASN.1 type is IA5String. The rule evaluates to TRUE if and only if the prepared attribute value character string and the prepared assertion value character string have the same number of characters and corresponding characters have the same code point. In preparing the attribute value and assertion value for comparison, characters are not case folded in the Map preparation step, and only Insignificant Space Handling is applied in the Insignificant Character Handling step. Legg Standards Track [Page 28] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 The LDAP definition for the caseExactIA5Match rule is: ( 1.3.6.1.4.1.1466.109.114.1 NAME 'caseExactIA5Match' SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) The caseExactIA5Match rule is an equality matching rule. 4.2.4. caseExactMatch The caseExactMatch rule compares an assertion value of the Directory String syntax to an attribute value of a syntax (e.g., the Directory String, Printable String, Country String, or Telephone Number syntax) whose corresponding ASN.1 type is DirectoryString or one of the alternative string types of DirectoryString, such as PrintableString (the other alternatives do not correspond to any syntax defined in this document). The rule evaluates to TRUE if and only if the prepared attribute value character string and the prepared assertion value character string have the same number of characters and corresponding characters have the same code point. In preparing the attribute value and assertion value for comparison, characters are not case folded in the Map preparation step, and only Insignificant Space Handling is applied in the Insignificant Character Handling step. The LDAP definition for the caseExactMatch rule is: ( 2.5.13.5 NAME 'caseExactMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) The caseExactMatch rule is an equality matching rule. 4.2.5. caseExactOrderingMatch The caseExactOrderingMatch rule compares an assertion value of the Directory String syntax to an attribute value of a syntax (e.g., the Directory String, Printable String, Country String, or Telephone Number syntax) whose corresponding ASN.1 type is DirectoryString or one of its alternative string types. The rule evaluates to TRUE if and only if, in the code point collation order, the prepared attribute value character string appears earlier than the prepared assertion value character string; i.e., the attribute value is "less than" the assertion value. Legg Standards Track [Page 29] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 In preparing the attribute value and assertion value for comparison, characters are not case folded in the Map preparation step, and only Insignificant Space Handling is applied in the Insignificant Character Handling step. The LDAP definition for the caseExactOrderingMatch rule is: ( 2.5.13.6 NAME 'caseExactOrderingMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) The caseExactOrderingMatch rule is an ordering matching rule. 4.2.6. caseExactSubstringsMatch The caseExactSubstringsMatch rule compares an assertion value of the Substring Assertion syntax to an attribute value of a syntax (e.g., the Directory String, Printable String, Country String, or Telephone Number syntax) whose corresponding ASN.1 type is DirectoryString or one of its alternative string types. The rule evaluates to TRUE if and only if (1) the prepared substrings of the assertion value match disjoint portions of the prepared attribute value character string in the order of the substrings in the assertion value, (2) an <initial> substring, if present, matches the beginning of the prepared attribute value character string, and (3) a <final> substring, if present, matches the end of the prepared attribute value character string. A prepared substring matches a portion of the prepared attribute value character string if corresponding characters have the same code point. In preparing the attribute value and assertion value substrings for comparison, characters are not case folded in the Map preparation step, and only Insignificant Space Handling is applied in the Insignificant Character Handling step. The LDAP definition for the caseExactSubstringsMatch rule is: ( 2.5.13.7 NAME 'caseExactSubstringsMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.58 ) The caseExactSubstringsMatch rule is a substrings matching rule. 4.2.7. caseIgnoreIA5Match The caseIgnoreIA5Match rule compares an assertion value of the IA5 String syntax to an attribute value of a syntax (e.g., the IA5 String syntax) whose corresponding ASN.1 type is IA5String. Legg Standards Track [Page 30] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 The rule evaluates to TRUE if and only if the prepared attribute value character string and the prepared assertion value character string have the same number of characters and corresponding characters have the same code point. In preparing the attribute value and assertion value for comparison, characters are case folded in the Map preparation step, and only Insignificant Space Handling is applied in the Insignificant Character Handling step. The LDAP definition for the caseIgnoreIA5Match rule is: ( 1.3.6.1.4.1.1466.109.114.2 NAME 'caseIgnoreIA5Match' SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) The caseIgnoreIA5Match rule is an equality matching rule. 4.2.8. caseIgnoreIA5SubstringsMatch The caseIgnoreIA5SubstringsMatch rule compares an assertion value of the Substring Assertion syntax to an attribute value of a syntax (e.g., the IA5 String syntax) whose corresponding ASN.1 type is IA5String. The rule evaluates to TRUE if and only if (1) the prepared substrings of the assertion value match disjoint portions of the prepared attribute value character string in the order of the substrings in the assertion value, (2) an <initial> substring, if present, matches the beginning of the prepared attribute value character string, and (3) a <final> substring, if present, matches the end of the prepared attribute value character string. A prepared substring matches a portion of the prepared attribute value character string if corresponding characters have the same code point. In preparing the attribute value and assertion value substrings for comparison, characters are case folded in the Map preparation step, and only Insignificant Space Handling is applied in the Insignificant Character Handling step. ( 1.3.6.1.4.1.1466.109.114.3 NAME 'caseIgnoreIA5SubstringsMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.58 ) The caseIgnoreIA5SubstringsMatch rule is a substrings matching rule. 4.2.9. caseIgnoreListMatch The caseIgnoreListMatch rule compares an assertion value that is a sequence of strings to an attribute value of a syntax (e.g., the Legg Standards Track [Page 31] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 Postal Address syntax) whose corresponding ASN.1 type is a SEQUENCE OF the DirectoryString ASN.1 type. The rule evaluates to TRUE if and only if the attribute value and the assertion value have the same number of strings and corresponding strings (by position) match according to the caseIgnoreMatch matching rule. In [X.520], the assertion syntax for this matching rule is defined to be: SEQUENCE OF DirectoryString {ub-match} That is, it is different from the corresponding type for the Postal Address syntax. The choice of the Postal Address syntax for the assertion syntax of the caseIgnoreListMatch in LDAP should not be seen as limiting the matching rule to apply only to attributes with the Postal Address syntax. The LDAP definition for the caseIgnoreListMatch rule is: ( 2.5.13.11 NAME 'caseIgnoreListMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.41 ) The caseIgnoreListMatch rule is an equality matching rule. 4.2.10. caseIgnoreListSubstringsMatch The caseIgnoreListSubstringsMatch rule compares an assertion value of the Substring Assertion syntax to an attribute value of a syntax (e.g., the Postal Address syntax) whose corresponding ASN.1 type is a SEQUENCE OF the DirectoryString ASN.1 type. The rule evaluates to TRUE if and only if the assertion value matches, per the caseIgnoreSubstringsMatch rule, the character string formed by concatenating the strings of the attribute value, except that none of the <initial>, <any>, or <final> substrings of the assertion value are considered to match a substring of the concatenated string which spans more than one of the original strings of the attribute value. Note that, in terms of the LDAP-specific encoding of the Postal Address syntax, the concatenated string omits the <DOLLAR> line separator and the escaping of "\" and "$" characters. The LDAP definition for the caseIgnoreListSubstringsMatch rule is: ( 2.5.13.12 NAME 'caseIgnoreListSubstringsMatch' Legg Standards Track [Page 32] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 SYNTAX 1.3.6.1.4.1.1466.115.121.1.58 ) The caseIgnoreListSubstringsMatch rule is a substrings matching rule. 4.2.11. caseIgnoreMatch The caseIgnoreMatch rule compares an assertion value of the Directory String syntax to an attribute value of a syntax (e.g., the Directory String, Printable String, Country String, or Telephone Number syntax) whose corresponding ASN.1 type is DirectoryString or one of its alternative string types. The rule evaluates to TRUE if and only if the prepared attribute value character string and the prepared assertion value character string have the same number of characters and corresponding characters have the same code point. In preparing the attribute value and assertion value for comparison, characters are case folded in the Map preparation step, and only Insignificant Space Handling is applied in the Insignificant Character Handling step. The LDAP definition for the caseIgnoreMatch rule is: ( 2.5.13.2 NAME 'caseIgnoreMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) The caseIgnoreMatch rule is an equality matching rule. 4.2.12. caseIgnoreOrderingMatch The caseIgnoreOrderingMatch rule compares an assertion value of the Directory String syntax to an attribute value of a syntax (e.g., the Directory String, Printable String, Country String, or Telephone Number syntax) whose corresponding ASN.1 type is DirectoryString or one of its alternative string types. The rule evaluates to TRUE if and only if, in the code point collation order, the prepared attribute value character string appears earlier than the prepared assertion value character string; i.e., the attribute value is "less than" the assertion value. In preparing the attribute value and assertion value for comparison, characters are case folded in the Map preparation step, and only Insignificant Space Handling is applied in the Insignificant Character Handling step. The LDAP definition for the caseIgnoreOrderingMatch rule is: Legg Standards Track [Page 33] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 ( 2.5.13.3 NAME 'caseIgnoreOrderingMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) The caseIgnoreOrderingMatch rule is an ordering matching rule. 4.2.13. caseIgnoreSubstringsMatch The caseIgnoreSubstringsMatch rule compares an assertion value of the Substring Assertion syntax to an attribute value of a syntax (e.g., the Directory String, Printable String, Country String, or Telephone Number syntax) whose corresponding ASN.1 type is DirectoryString or one of its alternative string types. The rule evaluates to TRUE if and only if (1) the prepared substrings of the assertion value match disjoint portions of the prepared attribute value character string in the order of the substrings in the assertion value, (2) an <initial> substring, if present, matches the beginning of the prepared attribute value character string, and (3) a <final> substring, if present, matches the end of the prepared attribute value character string. A prepared substring matches a portion of the prepared attribute value character string if corresponding characters have the same code point. In preparing the attribute value and assertion value substrings for comparison, characters are case folded in the Map preparation step, and only Insignificant Space Handling is applied in the Insignificant Character Handling step. The LDAP definition for the caseIgnoreSubstringsMatch rule is: ( 2.5.13.4 NAME 'caseIgnoreSubstringsMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.58 ) The caseIgnoreSubstringsMatch rule is a substrings matching rule. 4.2.14. directoryStringFirstComponentMatch The directoryStringFirstComponentMatch rule compares an assertion value of the Directory String syntax to an attribute value of a syntax whose corresponding ASN.1 type is a SEQUENCE with a mandatory first component of the DirectoryString ASN.1 type. Note that the assertion syntax of this matching rule differs from the attribute syntax of attributes for which this is the equality matching rule. Legg Standards Track [Page 34] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 The rule evaluates to TRUE if and only if the assertion value matches the first component of the attribute value using the rules of caseIgnoreMatch. The LDAP definition for the directoryStringFirstComponentMatch matching rule is: ( 2.5.13.31 NAME 'directoryStringFirstComponentMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) The directoryStringFirstComponentMatch rule is an equality matching rule. When using directoryStringFirstComponentMatch to compare two attribute values (of an applicable syntax), an assertion value must first be derived from one of the attribute values. An assertion value can be derived from an attribute value by taking the first component of that attribute value. 4.2.15. distinguishedNameMatch The distinguishedNameMatch rule compares an assertion value of the DN syntax to an attribute value of a syntax (e.g., the DN syntax) whose corresponding ASN.1 type is DistinguishedName. The rule evaluates to TRUE if and only if the attribute value and the assertion value have the same number of relative distinguished names and corresponding relative distinguished names (by position) are the same. A relative distinguished name (RDN) of the assertion value is the same as an RDN of the attribute value if and only if they have the same number of attribute value assertions and each attribute value assertion (AVA) of the first RDN is the same as the AVA of the second RDN with the same attribute type. The order of the AVAs is not significant. Also note that a particular attribute type may appear in at most one AVA in an RDN. Two AVAs with the same attribute type are the same if their values are equal according to the equality matching rule of the attribute type. If one or more of the AVA comparisons evaluate to Undefined and the remaining AVA comparisons return TRUE then the distinguishedNameMatch rule evaluates to Undefined. The LDAP definition for the distinguishedNameMatch rule is: ( 2.5.13.1 NAME 'distinguishedNameMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 ) The distinguishedNameMatch rule is an equality matching rule. Legg Standards Track [Page 35] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 4.2.16. generalizedTimeMatch The generalizedTimeMatch rule compares an assertion value of the Generalized Time syntax to an attribute value of a syntax (e.g., the Generalized Time syntax) whose corresponding ASN.1 type is GeneralizedTime. The rule evaluates to TRUE if and only if the attribute value represents the same universal coordinated time as the assertion value. If a time is specified with the minutes or seconds absent, then the number of minutes or seconds (respectively) is assumed to be zero. The LDAP definition for the generalizedTimeMatch rule is: ( 2.5.13.27 NAME 'generalizedTimeMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 ) The generalizedTimeMatch rule is an equality matching rule. 4.2.17. generalizedTimeOrderingMatch The generalizedTimeOrderingMatch rule compares the time ordering of an assertion value of the Generalized Time syntax to an attribute value of a syntax (e.g., the Generalized Time syntax) whose corresponding ASN.1 type is GeneralizedTime. The rule evaluates to TRUE if and only if the attribute value represents a universal coordinated time that is earlier than the universal coordinated time represented by the assertion value. The LDAP definition for the generalizedTimeOrderingMatch rule is: ( 2.5.13.28 NAME 'generalizedTimeOrderingMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 ) The generalizedTimeOrderingMatch rule is an ordering matching rule. 4.2.18. integerFirstComponentMatch The integerFirstComponentMatch rule compares an assertion value of the Integer syntax to an attribute value of a syntax (e.g., the DIT Structure Rule Description syntax) whose corresponding ASN.1 type is a SEQUENCE with a mandatory first component of the INTEGER ASN.1 type. Legg Standards Track [Page 36] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 Note that the assertion syntax of this matching rule differs from the attribute syntax of attributes for which this is the equality matching rule. The rule evaluates to TRUE if and only if the assertion value and the first component of the attribute value are the same integer value. The LDAP definition for the integerFirstComponentMatch matching rule is: ( 2.5.13.29 NAME 'integerFirstComponentMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 ) The integerFirstComponentMatch rule is an equality matching rule. When using integerFirstComponentMatch to compare two attribute values (of an applicable syntax), an assertion value must first be derived from one of the attribute values. An assertion value can be derived from an attribute value by taking the first component of that attribute value. 4.2.19. integerMatch The integerMatch rule compares an assertion value of the Integer syntax to an attribute value of a syntax (e.g., the Integer syntax) whose corresponding ASN.1 type is INTEGER. The rule evaluates to TRUE if and only if the attribute value and the assertion value are the same integer value. The LDAP definition for the integerMatch matching rule is: ( 2.5.13.14 NAME 'integerMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 ) The integerMatch rule is an equality matching rule. 4.2.20. integerOrderingMatch The integerOrderingMatch rule compares an assertion value of the Integer syntax to an attribute value of a syntax (e.g., the Integer syntax) whose corresponding ASN.1 type is INTEGER. The rule evaluates to TRUE if and only if the integer value of the attribute value is less than the integer value of the assertion value. The LDAP definition for the integerOrderingMatch matching rule is: Legg Standards Track [Page 37] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 ( 2.5.13.15 NAME 'integerOrderingMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 ) The integerOrderingMatch rule is an ordering matching rule. 4.2.21. keywordMatch The keywordMatch rule compares an assertion value of the Directory String syntax to an attribute value of a syntax (e.g., the Directory String syntax) whose corresponding ASN.1 type is DirectoryString. The rule evaluates to TRUE if and only if the assertion value character string matches any keyword in the attribute value. The identification of keywords in the attribute value and the exactness of the match are both implementation specific. The LDAP definition for the keywordMatch rule is: ( 2.5.13.33 NAME 'keywordMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) 4.2.22. numericStringMatch The numericStringMatch rule compares an assertion value of the Numeric String syntax to an attribute value of a syntax (e.g., the Numeric String syntax) whose corresponding ASN.1 type is NumericString. The rule evaluates to TRUE if and only if the prepared attribute value character string and the prepared assertion value character string have the same number of characters and corresponding characters have the same code point. In preparing the attribute value and assertion value for comparison, characters are not case folded in the Map preparation step, and only numericString Insignificant Character Handling is applied in the Insignificant Character Handling step. The LDAP definition for the numericStringMatch matching rule is: ( 2.5.13.8 NAME 'numericStringMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.36 ) The numericStringMatch rule is an equality matching rule. Legg Standards Track [Page 38] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 4.2.23. numericStringOrderingMatch The numericStringOrderingMatch rule compares an assertion value of the Numeric String syntax to an attribute value of a syntax (e.g., the Numeric String syntax) whose corresponding ASN.1 type is NumericString. The rule evaluates to TRUE if and only if, in the code point collation order, the prepared attribute value character string appears earlier than the prepared assertion value character string; i.e., the attribute value is "less than" the assertion value. In preparing the attribute value and assertion value for comparison, characters are not case folded in the Map preparation step, and only numericString Insignificant Character Handling is applied in the Insignificant Character Handling step. The rule is identical to the caseIgnoreOrderingMatch rule except that all space characters are skipped during comparison (case is irrelevant as the characters are numeric). The LDAP definition for the numericStringOrderingMatch matching rule is: ( 2.5.13.9 NAME 'numericStringOrderingMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.36 ) The numericStringOrderingMatch rule is an ordering matching rule. 4.2.24. numericStringSubstringsMatch The numericStringSubstringsMatch rule compares an assertion value of the Substring Assertion syntax to an attribute value of a syntax (e.g., the Numeric String syntax) whose corresponding ASN.1 type is NumericString. The rule evaluates to TRUE if and only if (1) the prepared substrings of the assertion value match disjoint portions of the prepared attribute value character string in the order of the substrings in the assertion value, (2) an <initial> substring, if present, matches the beginning of the prepared attribute value character string, and (3) a <final> substring, if present, matches the end of the prepared attribute value character string. A prepared substring matches a portion of the prepared attribute value character string if corresponding characters have the same code point. In preparing the attribute value and assertion value for comparison, characters are not case folded in the Map preparation step, and only Legg Standards Track [Page 39] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 numericString Insignificant Character Handling is applied in the Insignificant Character Handling step. The LDAP definition for the numericStringSubstringsMatch matching rule is: ( 2.5.13.10 NAME 'numericStringSubstringsMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.58 ) The numericStringSubstringsMatch rule is a substrings matching rule. 4.2.25. objectIdentifierFirstComponentMatch The objectIdentifierFirstComponentMatch rule compares an assertion value of the OID syntax to an attribute value of a syntax (e.g., the Attribute Type Description, DIT Content Rule Description, LDAP Syntax Description, Matching Rule Description, Matching Rule Use Description, Name Form Description, or Object Class Description syntax) whose corresponding ASN.1 type is a SEQUENCE with a mandatory first component of the OBJECT IDENTIFIER ASN.1 type. Note that the assertion syntax of this matching rule differs from the attribute syntax of attributes for which this is the equality matching rule. The rule evaluates to TRUE if and only if the assertion value matches the first component of the attribute value using the rules of objectIdentifierMatch. The LDAP definition for the objectIdentifierFirstComponentMatch matching rule is: ( 2.5.13.30 NAME 'objectIdentifierFirstComponentMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 ) The objectIdentifierFirstComponentMatch rule is an equality matching rule. When using objectIdentifierFirstComponentMatch to compare two attribute values (of an applicable syntax), an assertion value must first be derived from one of the attribute values. An assertion value can be derived from an attribute value by taking the first component of that attribute value. 4.2.26. objectIdentifierMatch The objectIdentifierMatch rule compares an assertion value of the OID syntax to an attribute value of a syntax (e.g., the OID syntax) whose corresponding ASN.1 type is OBJECT IDENTIFIER. Legg Standards Track [Page 40] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 The rule evaluates to TRUE if and only if the assertion value and the attribute value represent the same object identifier; that is, the same sequence of integers, whether represented explicitly in the <numericoid> form of <oid> or implicitly in the <descr> form (see [RFC4512]). If an LDAP client supplies an assertion value in the <descr> form and the chosen descriptor is not recognized by the server, then the objectIdentifierMatch rule evaluates to Undefined. The LDAP definition for the objectIdentifierMatch matching rule is: ( 2.5.13.0 NAME 'objectIdentifierMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 ) The objectIdentifierMatch rule is an equality matching rule. 4.2.27. octetStringMatch The octetStringMatch rule compares an assertion value of the Octet String syntax to an attribute value of a syntax (e.g., the Octet String or JPEG syntax) whose corresponding ASN.1 type is the OCTET STRING ASN.1 type. The rule evaluates to TRUE if and only if the attribute value and the assertion value are the same length and corresponding octets (by position) are the same. The LDAP definition for the octetStringMatch matching rule is: ( 2.5.13.17 NAME 'octetStringMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.40 ) The octetStringMatch rule is an equality matching rule. 4.2.28. octetStringOrderingMatch The octetStringOrderingMatch rule compares an assertion value of the Octet String syntax to an attribute value of a syntax (e.g., the Octet String or JPEG syntax) whose corresponding ASN.1 type is the OCTET STRING ASN.1 type. The rule evaluates to TRUE if and only if the attribute value appears earlier in the collation order than the assertion value. The rule compares octet strings from the first octet to the last octet, and from the most significant bit to the least significant bit within the octet. The first occurrence of a different bit determines the ordering of the strings. A zero bit precedes a one bit. If the Legg Standards Track [Page 41] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 strings contain different numbers of octets but the longer string is identical to the shorter string up to the length of the shorter string, then the shorter string precedes the longer string. The LDAP definition for the octetStringOrderingMatch matching rule is: ( 2.5.13.18 NAME 'octetStringOrderingMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.40 ) The octetStringOrderingMatch rule is an ordering matching rule. 4.2.29. telephoneNumberMatch The telephoneNumberMatch rule compares an assertion value of the Telephone Number syntax to an attribute value of a syntax (e.g., the Telephone Number syntax) whose corresponding ASN.1 type is a PrintableString representing a telephone number. The rule evaluates to TRUE if and only if the prepared attribute value character string and the prepared assertion value character string have the same number of characters and corresponding characters have the same code point. In preparing the attribute value and assertion value for comparison, characters are case folded in the Map preparation step, and only telephoneNumber Insignificant Character Handling is applied in the Insignificant Character Handling step. The LDAP definition for the telephoneNumberMatch matching rule is: ( 2.5.13.20 NAME 'telephoneNumberMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.50 ) The telephoneNumberMatch rule is an equality matching rule. 4.2.30. telephoneNumberSubstringsMatch The telephoneNumberSubstringsMatch rule compares an assertion value of the Substring Assertion syntax to an attribute value of a syntax (e.g., the Telephone Number syntax) whose corresponding ASN.1 type is a PrintableString representing a telephone number. The rule evaluates to TRUE if and only if (1) the prepared substrings of the assertion value match disjoint portions of the prepared attribute value character string in the order of the substrings in the assertion value, (2) an <initial> substring, if present, matches the beginning of the prepared attribute value character string, and Legg Standards Track [Page 42] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 (3) a <final> substring, if present, matches the end of the prepared attribute value character string. A prepared substring matches a portion of the prepared attribute value character string if corresponding characters have the same code point. In preparing the attribute value and assertion value substrings for comparison, characters are case folded in the Map preparation step, and only telephoneNumber Insignificant Character Handling is applied in the Insignificant Character Handling step. The LDAP definition for the telephoneNumberSubstringsMatch matching rule is: ( 2.5.13.21 NAME 'telephoneNumberSubstringsMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.58 ) The telephoneNumberSubstringsMatch rule is a substrings matching rule. 4.2.31. uniqueMemberMatch The uniqueMemberMatch rule compares an assertion value of the Name And Optional UID syntax to an attribute value of a syntax (e.g., the Name And Optional UID syntax) whose corresponding ASN.1 type is NameAndOptionalUID. The rule evaluates to TRUE if and only if the <distinguishedName> components of the assertion value and attribute value match according to the distinguishedNameMatch rule and either, (1) the <BitString> component is absent from both the attribute value and assertion value, or (2) the <BitString> component is present in both the attribute value and the assertion value and the <BitString> component of the assertion value matches the <BitString> component of the attribute value according to the bitStringMatch rule. Note that this matching rule has been altered from its description in X.520 [X.520] in order to make the matching rule commutative. Server implementors should consider using the original X.520 semantics (where the matching was less exact) for approximate matching of attributes with uniqueMemberMatch as the equality matching rule. The LDAP definition for the uniqueMemberMatch matching rule is: ( 2.5.13.23 NAME 'uniqueMemberMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.34 ) The uniqueMemberMatch rule is an equality matching rule. Legg Standards Track [Page 43] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 4.2.32. wordMatch The wordMatch rule compares an assertion value of the Directory String syntax to an attribute value of a syntax (e.g., the Directory String syntax) whose corresponding ASN.1 type is DirectoryString. The rule evaluates to TRUE if and only if the assertion value word matches, according to the semantics of caseIgnoreMatch, any word in the attribute value. The precise definition of a word is implementation specific. The LDAP definition for the wordMatch rule is: ( 2.5.13.32 NAME 'wordMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) 5. Security Considerations In general, the LDAP-specific encodings for syntaxes defined in this document do not define canonical encodings. That is, a transformation from an LDAP-specific encoding into some other encoding (e.g., BER) and back into the LDAP-specific encoding will not necessarily reproduce exactly the original octets of the LDAP- specific encoding. Therefore, an LDAP-specific encoding should not be used where a canonical encoding is required. Furthermore, the LDAP-specific encodings do not necessarily enable an alternative encoding of values of the Directory String and DN syntaxes to be reconstructed; e.g., a transformation from a Distinguished Encoding Rules (DER) [BER] encoding to an LDAP-specific encoding and back to a DER encoding may not reproduce the original DER encoding. Therefore, LDAP-specific encodings should not be used where reversibility to DER is needed; e.g., for the verification of digital signatures. Instead, DER or a DER-reversible encoding should be used. When interpreting security-sensitive fields (in particular, fields used to grant or deny access), implementations MUST ensure that any matching rule comparisons are done on the underlying abstract value, regardless of the particular encoding used. 6. Acknowledgements This document is primarily a revision of RFC 2252 by M. Wahl, A. Coulbeck, T. Howes, and S. Kille. RFC 2252 was a product of the IETF ASID Working Group. Legg Standards Track [Page 44] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 This document is based on input from the IETF LDAPBIS working group. The author would like to thank Kathy Dally for editing the early drafts of this document, and Jim Sermersheim and Kurt Zeilenga for their significant contributions to this revision. 7. IANA Considerations The Internet Assigned Numbers Authority (IANA) has updated the LDAP descriptors registry [BCP64] as indicated by the following templates: Subject: Request for LDAP Descriptor Registration Update Descriptor (short name): see comment Object Identifier: see comment Person & email address to contact for further information: Steven Legg <steven.legg@eb2bcom.com> Usage: see comment Specification: RFC 4517 Author/Change Controller: IESG NAME Type OID ------------------------------------------------------------------ bitStringMatch M 2.5.13.16 booleanMatch M 2.5.13.13 caseExactIA5Match M 1.3.6.1.4.1.1466.109.114.1 caseExactMatch M 2.5.13.5 caseExactOrderingMatch M 2.5.13.6 caseExactSubstringsMatch M 2.5.13.7 caseIgnoreIA5Match M 1.3.6.1.4.1.1466.109.114.2 caseIgnoreListMatch M 2.5.13.11 caseIgnoreListSubstringsMatch M 2.5.13.12 caseIgnoreMatch M 2.5.13.2 caseIgnoreOrderingMatch M 2.5.13.3 caseIgnoreSubstringsMatch M 2.5.13.4 directoryStringFirstComponentMatch M 2.5.13.31 distinguishedNameMatch M 2.5.13.1 generalizedTimeMatch M 2.5.13.27 generalizedTimeOrderingMatch M 2.5.13.28 integerFirstComponentMatch M 2.5.13.29 integerMatch M 2.5.13.14 integerOrderingMatch M 2.5.13.15 keywordMatch M 2.5.13.33 numericStringMatch M 2.5.13.8 numericStringOrderingMatch M 2.5.13.9 numericStringSubstringsMatch M 2.5.13.10 objectIdentifierFirstComponentMatch M 2.5.13.30 octetStringMatch M 2.5.13.17 octetStringOrderingMatch M 2.5.13.18 telephoneNumberMatch M 2.5.13.20 Legg Standards Track [Page 45] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 telephoneNumberSubstringsMatch M 2.5.13.21 uniqueMemberMatch M 2.5.13.23 wordMatch M 2.5.13.32 The descriptor for the object identifier 2.5.13.0 was incorrectly registered as objectIdentifiersMatch (extraneous \`s') in BCP 64. It has been changed to the following, with a reference to RFC 4517. NAME Type OID ------------------------------------------------------------------ objectIdentifierMatch M 2.5.13.0 Subject: Request for LDAP Descriptor Registration Descriptor (short name): caseIgnoreIA5SubstringsMatch Object Identifier: 1.3.6.1.4.1.1466.109.114.3 Person & email address to contact for further information: Steven Legg <steven.legg@eb2bcom.com> Usage: other (M) Specification: RFC 4517 Author/Change Controller: IESG 8. References 8.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003. [RFC4234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 4234, October 2005. [RFC4510] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006. [RFC4511] Sermersheim, J., Ed., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006. [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006. Legg Standards Track [Page 46] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 [RFC4514] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names", RFC 4514, June 2006. [RFC4518] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Internationalized String Preparation", RFC 4518, June 2006. [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006. [E.123] Notation for national and international telephone numbers, ITU-T Recommendation E.123, 1988. [FAX] Standardization of Group 3 facsimile apparatus for document transmission - Terminal Equipment and Protocols for Telematic Services, ITU-T Recommendation T.4, 1993 [T.50] International Reference Alphabet (IRA) (Formerly International Alphabet No. 5 or IA5) Information Technology - 7-Bit Coded Character Set for Information Interchange, ITU-T Recommendation T.50, 1992 [X.420] ITU-T Recommendation X.420 (1996) | ISO/IEC 10021-7:1997, Information Technology - Message Handling Systems (MHS): Interpersonal messaging system [X.501] ITU-T Recommendation X.501 (1993) | ISO/IEC 9594-2:1994, Information Technology - Open Systems Interconnection - The Directory: Models [X.520] ITU-T Recommendation X.520 (1993) | ISO/IEC 9594-6:1994, Information Technology - Open Systems Interconnection - The Directory: Selected attribute types [ASN.1] ITU-T Recommendation X.680 (07/02) | ISO/IEC 8824-1:2002, Information technology - Abstract Syntax Notation One (ASN.1): Specification of basic notation [ISO3166] ISO 3166, "Codes for the representation of names of countries". [ISO8601] ISO 8601:2004, "Data elements and interchange formats -- Information interchange -- Representation of dates and times". Legg Standards Track [Page 47] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 [UCS] Universal Multiple-Octet Coded Character Set (UCS) - Architecture and Basic Multilingual Plane, ISO/IEC 10646- 1: 1993 (with amendments). [JPEG] JPEG File Interchange Format (Version 1.02). Eric Hamilton, C-Cube Microsystems, Milpitas, CA, September 1, 1992. 8.2. Informative References [RFC4519] Sciberras, A., Ed., "Lightweight Directory Access Protocol (LDAP): Schema for User Applications", RFC 4519, June 2006. [RFC4523] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP) Schema Definitions for X.509 Certificates", RFC 4523, June 2006. [X.500] ITU-T Recommendation X.500 (1993) | ISO/IEC 9594-1:1994, Information Technology - Open Systems Interconnection - The Directory: Overview of concepts, models and services [BER] ITU-T Recommendation X.690 (07/02) | ISO/IEC 8825-1:2002, Information technology - ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER) Legg Standards Track [Page 48] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 Appendix A. Summary of Syntax Object Identifiers The following list summarizes the object identifiers assigned to the syntaxes defined in this document. Syntax OBJECT IDENTIFIER ============================================================== Attribute Type Description 1.3.6.1.4.1.1466.115.121.1.3 Bit String 1.3.6.1.4.1.1466.115.121.1.6 Boolean 1.3.6.1.4.1.1466.115.121.1.7 Country String 1.3.6.1.4.1.1466.115.121.1.11 Delivery Method 1.3.6.1.4.1.1466.115.121.1.14 Directory String 1.3.6.1.4.1.1466.115.121.1.15 DIT Content Rule Description 1.3.6.1.4.1.1466.115.121.1.16 DIT Structure Rule Description 1.3.6.1.4.1.1466.115.121.1.17 DN 1.3.6.1.4.1.1466.115.121.1.12 Enhanced Guide 1.3.6.1.4.1.1466.115.121.1.21 Facsimile Telephone Number 1.3.6.1.4.1.1466.115.121.1.22 Fax 1.3.6.1.4.1.1466.115.121.1.23 Generalized Time 1.3.6.1.4.1.1466.115.121.1.24 Guide 1.3.6.1.4.1.1466.115.121.1.25 IA5 String 1.3.6.1.4.1.1466.115.121.1.26 Integer 1.3.6.1.4.1.1466.115.121.1.27 JPEG 1.3.6.1.4.1.1466.115.121.1.28 LDAP Syntax Description 1.3.6.1.4.1.1466.115.121.1.54 Matching Rule Description 1.3.6.1.4.1.1466.115.121.1.30 Matching Rule Use Description 1.3.6.1.4.1.1466.115.121.1.31 Name And Optional UID 1.3.6.1.4.1.1466.115.121.1.34 Name Form Description 1.3.6.1.4.1.1466.115.121.1.35 Numeric String 1.3.6.1.4.1.1466.115.121.1.36 Object Class Description 1.3.6.1.4.1.1466.115.121.1.37 Octet String 1.3.6.1.4.1.1466.115.121.1.40 OID 1.3.6.1.4.1.1466.115.121.1.38 Other Mailbox 1.3.6.1.4.1.1466.115.121.1.39 Postal Address 1.3.6.1.4.1.1466.115.121.1.41 Printable String 1.3.6.1.4.1.1466.115.121.1.44 Substring Assertion 1.3.6.1.4.1.1466.115.121.1.58 Telephone Number 1.3.6.1.4.1.1466.115.121.1.50 Teletex Terminal Identifier 1.3.6.1.4.1.1466.115.121.1.51 Telex Number 1.3.6.1.4.1.1466.115.121.1.52 UTC Time 1.3.6.1.4.1.1466.115.121.1.53 Appendix B. Changes from RFC 2252 This annex lists the significant differences between this specification and RFC 2252. Legg Standards Track [Page 49] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 This annex is provided for informational purposes only. It is not a normative part of this specification. 1. The IESG Note has been removed. 2. The major part of Sections 4, 5 and 7 has been moved to [RFC4512] and revised. Changes to the parts of these sections moved to [RFC4512] are detailed in [RFC4512]. 3. BNF descriptions of syntax formats have been replaced by ABNF [RFC4234] specifications. 4. The ambiguous statement in RFC 2252, Section 4.3 regarding the use of a backslash quoting mechanism to escape separator symbols has been removed. The escaping mechanism is now explicitly represented in the ABNF for the syntaxes where this provision applies. 5. The description of each of the LDAP syntaxes has been expanded so that they are less dependent on knowledge of X.500 for interpretation. 6. The relationship of LDAP syntaxes to corresponding ASN.1 type definitions has been made explicit. 7. The set of characters allowed in a <PrintableString> (formerly <printablestring>) has been corrected to align with the PrintableString ASN.1 type in [ASN.1]. Specifically, the double quote character has been removed and the single quote character and equals sign have been added. 8. Values of the Directory String, Printable String and Telephone Number syntaxes are now required to have at least one character. 9. The <DITContentRuleDescription>, <NameFormDescription> and <DITStructureRuleDescription> rules have been moved to [RFC4512]. 10. The corresponding ASN.1 type for the Other Mailbox syntax has been incorporated from RFC 1274. 11. A corresponding ASN.1 type for the LDAP Syntax Description syntax has been invented. 12. The Binary syntax has been removed because it was not adequately specified, implementations with different incompatible interpretations exist, and it was confused with the ;binary transfer encoding. Legg Standards Track [Page 50] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 13. All discussion of transfer options, including the ";binary" option, has been removed. All imperatives regarding binary transfer of values have been removed. 14. The Delivery Method, Enhanced Guide, Guide, Octet String, Teletex Terminal Identifier and Telex Number syntaxes from RFC 2256 have been incorporated. 15. The <criteria> rule for the Enhanced Guide and Guide syntaxes has been extended to accommodate empty "and" and "or" expressions. 16. An encoding for the <ttx-value> rule in the Teletex Terminal Identifier syntax has been defined. 17. The PKI-related syntaxes (Certificate, Certificate List and Certificate Pair) have been removed. They are reintroduced in [RFC4523] (as is the Supported Algorithm syntax from RFC 2256). 18. The MHS OR Address syntax has been removed since its specification (in RFC 2156) is not at draft standard maturity. 19. The DL Submit Permission syntax has been removed as it depends on the MHS OR Address syntax. 20. The Presentation Address syntax has been removed since its specification (in RFC 1278) is not at draft standard maturity. 21. The ACI Item, Access Point, Audio, Data Quality, DSA Quality, DSE Type, LDAP Schema Description, Master And Shadow Access Points, Modify Rights, Protocol Information, Subtree Specification, Supplier Information, Supplier Or Consumer and Supplier And Consumer syntaxes have been removed. These syntaxes are referenced in RFC 2252, but not defined. 22. The LDAP Schema Definition syntax (defined in RFC 2927) and the Mail Preference syntax have been removed on the grounds that they are out of scope for the core specification. 23. The description of each of the matching rules has been expanded so that they are less dependent on knowledge of X.500 for interpretation. 24. The caseIgnoreIA5SubstringsMatch matching rule from RFC 2798 has been added. 25. The caseIgnoreListSubstringsMatch, caseIgnoreOrderingMatch and caseIgnoreSubstringsMatch matching rules have been added to the list of matching rules for which the provisions for handling Legg Standards Track [Page 51] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 leading, trailing and multiple adjoining whitespace characters apply (now through string preparation). This is consistent with the definitions of these matching rules in X.500. The caseIgnoreIA5SubstringsMatch rule has also been added to the list. 26. The specification of the octetStringMatch matching rule from RFC 2256 has been added to this document. 27. The presentationAddressMatch matching rule has been removed as it depends on an assertion syntax (Presentation Address) that is not at draft standard maturity. 28. The protocolInformationMatch matching rule has been removed as it depends on an undefined assertion syntax (Protocol Information). 29. The definitive reference for ASN.1 has been changed from X.208 to X.680 since X.680 is the version of ASN.1 referred to by X.500. 30. The specification of the caseIgnoreListSubstringsMatch matching rule from RFC 2798 & X.520 has been added. 31. String preparation algorithms have been applied to the character string matching rules. 32. The specifications of the booleanMatch, caseExactMatch, caseExactOrderingMatch, caseExactSubstringsMatch, directoryStringFirstComponentMatch, integerOrderingMatch, keywordMatch, numericStringOrderingMatch, octetStringOrderingMatch and wordMatch matching rules from RFC 3698 & X.520 have been added. Author's Address Steven Legg eB2Bcom Suite3, Woodhouse Corporate Centre 935 Station Street Box Hill North, Victoria 3129 AUSTRALIA Phone: +61 3 9896 7830 Fax: +61 3 9896 7801 EMail: steven.legg@eb2bcom.com Legg Standards Track [Page 52] RFC 4517 LDAP: Syntaxes and Matching Rules June 2006 Full Copyright Statement Copyright (C) The Internet Society (2006). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Legg Standards Track [Page 53] PK (�c\��/�s> s> ( doc/alt-openldap11-devel/rfc/rfc4527.txtnu �[��� Network Working Group K. Zeilenga Request for Comments: 4527 OpenLDAP Foundation Category: Standards Track June 2006 Lightweight Directory Access Protocol (LDAP) Read Entry Controls Status of This Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2006). Abstract This document specifies an extension to the Lightweight Directory Access Protocol (LDAP) to allow the client to read the target entry of an update operation. The client may request to read the entry before and/or after the modifications are applied. These reads are done as an atomic part of the update operation. Table of Contents 1. Background and Intent of Use ....................................2 2. Terminology .....................................................2 3. Read Entry Controls .............................................3 3.1. The Pre-Read Controls ......................................3 3.2. The Post-Read Controls .....................................3 4. Interaction with Other Controls .................................4 5. Security Considerations .........................................4 6. IANA Considerations .............................................5 6.1. Object Identifier ..........................................5 6.2. LDAP Protocol Mechanisms ...................................5 7. Acknowledgement .................................................5 8. References ......................................................6 8.1. Normative References .......................................6 8.2. Informative References .....................................7 Zeilenga Standards Track [Page 1] RFC 4527 LDAP Read Entry Controls June 2006 1. Background and Intent of Use This document specifies an extension to the Lightweight Directory Access Protocol (LDAP) [RFC4510] to allow the client to read the target entry of an update operation (e.g., Add, Delete, Modify, ModifyDN). The extension utilizes controls [RFC4511] attached to update requests to request and return copies of the target entry. One request control, called the Pre-Read request control, indicates that a copy of the entry before application of update is to be returned. Another control, called the Post-Read request control, indicates that a copy of the entry after application of the update is to be returned. Each request control has a corresponding response control used to return the entry. To ensure proper isolation, the controls are processed as an atomic part of the update operation. The functionality offered by these controls is based upon similar functionality in the X.500 Directory Access Protocol (DAP) [X.511]. The Pre-Read controls may be used to obtain replaced or deleted values of modified attributes or a copy of the entry being deleted. The Post-Read controls may be used to obtain values of operational attributes, such as the 'entryUUID' [RFC4530] and 'modifyTimestamp' [RFC4512] attributes, updated by the server as part of the update operation. 2. Terminology Protocol elements are described using ASN.1 [X.680] with implicit tags. The term "BER-encoded" means the element is to be encoded using the Basic Encoding Rules [X.690] under the restrictions detailed in Section 5.1 of [RFC4511]. DN stands for Distinguished Name. DSA stands for Directory System Agent (i.e., a directory server). DSE stands for DSA-specific Entry. In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in BCP 14 [RFC2119]. Zeilenga Standards Track [Page 2] RFC 4527 LDAP Read Entry Controls June 2006 3. Read Entry Controls 3.1. The Pre-Read Controls The Pre-Read request and response controls are identified by the 1.3.6.1.1.13.1 object identifier. Servers implementing these controls SHOULD publish 1.3.6.1.1.13.1 as a value of the 'supportedControl' [RFC4512] in their root DSE. The Pre-Read request control is a LDAP Control [RFC4511] whose controlType is 1.3.6.1.1.13.1 and whose controlValue is a BER-encoded AttributeSelection [RFC4511], as extended by [RFC3673]. The criticality may be TRUE or FALSE. This control is appropriate for the modifyRequest, delRequest, and modDNRequest LDAP messages. The corresponding response control is a LDAP Control whose controlType is 1.3.6.1.1.13.1 and whose the controlValue, an OCTET STRING, contains a BER-encoded SearchResultEntry. The criticality may be TRUE or FALSE. This control is appropriate for the modifyResponse, delResponse, and modDNResponse LDAP messages with a resultCode of success (0). When the request control is attached to an appropriate update LDAP request, the control requests the return of a copy of the target entry prior to the application of the update. The AttributeSelection indicates, as discussed in [RFC4511][RFC3673], which attributes are requested to appear in the copy. The server is to return a SearchResultEntry containing, subject to access controls and other constraints, values of the requested attributes. The normal processing of the update operation and the processing of this control MUST be performed as one atomic action isolated from other update operations. If the update operation fails (in either normal or control processing), no Pre-Read response control is provided. 3.2. The Post-Read Controls The Post-Read request and response controls are identified by the 1.3.6.1.1.13.2 object identifier. Servers implementing these controls SHOULD publish 1.3.6.1.1.13.2 as a value of the 'supportedControl' [RFC4512] in their root DSE. The Post-Read request control is a LDAP Control [RFC4511] whose controlType is 1.3.6.1.1.13.2 and whose controlValue, an OCTET STRING, contains a BER-encoded AttributeSelection [RFC4511], as extended by [RFC3673]. The criticality may be TRUE or FALSE. This Zeilenga Standards Track [Page 3] RFC 4527 LDAP Read Entry Controls June 2006 control is appropriate for the addRequest, modifyRequest, and modDNRequest LDAP messages. The corresponding response control is a LDAP Control whose controlType is 1.3.6.1.1.13.2 and whose controlValue is a BER-encoded SearchResultEntry. The criticality may be TRUE or FALSE. This control is appropriate for the addResponse, modifyResponse, and modDNResponse LDAP messages with a resultCode of success (0). When the request control is attached to an appropriate update LDAP request, the control requests the return of a copy of the target entry after the application of the update. The AttributeSelection indicates, as discussed in [RFC4511][RFC3673], which attributes are requested to appear in the copy. The server is to return a SearchResultEntry containing, subject to access controls and other constraints, values of the requested attributes. The normal processing of the update operation and the processing of this control MUST be performed as one atomic action isolated from other update operations. If the update operation fails (in either normal or control processing), no Post-Read response control is provided. 4. Interaction with Other Controls The Pre-Read and Post-Read controls may be combined with each other and/or with a variety of other controls. When combined with the assertion control [RFC4528] and/or the manageDsaIT control [RFC3296], the semantics of each control included in the combination applies. The Pre-Read and Post-Read controls may be combined with other controls as detailed in other technical specifications. 5. Security Considerations The controls defined in this document extend update operations to support read capabilities. Servers MUST ensure that the client is authorized for reading of the information provided in this control and that the client is authorized to perform the requested directory update. Security considerations for the update operations [RFC4511] extended by this control, as well as general LDAP security considerations [RFC4510], generally apply to implementation and use of this extension Zeilenga Standards Track [Page 4] RFC 4527 LDAP Read Entry Controls June 2006 6. IANA Considerations Registration of the following protocol values [RFC4520] have been completed by the IANA. 6.1. Object Identifier The IANA has registered an LDAP Object Identifier to identify LDAP protocol elements defined in this document. Subject: Request for LDAP Object Identifier Registration Person & email address to contact for further information: Kurt Zeilenga <kurt@OpenLDAP.org> Specification: RFC 4527 Author/Change Controller: IESG Comments: Identifies the LDAP Read Entry Controls 6.2. LDAP Protocol Mechanisms The IANA has registered the LDAP Protocol Mechanism described in this document. Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: 1.3.6.1.1.13.1 Description: LDAP Pre-read Control Person & email address to contact for further information: Kurt Zeilenga <kurt@openldap.org> Usage: Control Specification: RFC 4527 Author/Change Controller: IESG Comments: none Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: 1.3.6.1.1.13.2 Description: LDAP Post-read Control Person & email address to contact for further information: Kurt Zeilenga <kurt@openldap.org> Usage: Control Specification: RFC 4527 Author/Change Controller: IESG Comments: none 7. Acknowledgement The LDAP Pre-Read and Post-Read controls are modeled after similar capabilities offered in the DAP [X.511]. Zeilenga Standards Track [Page 5] RFC 4527 LDAP Read Entry Controls June 2006 8. References 8.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC3296] Zeilenga, K., "Named Subordinate References in Lightweight Directory Access Protocol (LDAP) Directories", RFC 3296, July 2002. [RFC3673] Zeilenga, K., "Lightweight Directory Access Protocol version 3 (LDAPv3): All Operational Attributes", RFC 3673, December 2003. [RFC4510] Zeilenga, K., Ed, "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006. [RFC4511] Sermersheim, J., Ed., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006. [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006. [RFC4528] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP) Assertion Control", RFC 4528, June 2006. [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). [X.690] International Telecommunication Union - Telecommunication Standardization Sector, "Specification of ASN.1 encoding rules: Basic Encoding Rules (BER), Canonical Encoding Rules (CER), and Distinguished Encoding Rules (DER)", X.690(1997) (also ISO/IEC 8825-1:1998). Zeilenga Standards Track [Page 6] RFC 4527 LDAP Read Entry Controls June 2006 8.2. Informative References [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006. [RFC4530] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP) EntryUUID Operational Attribute", RFC 4530, June 2006. [X.511] International Telecommunication Union - Telecommunication Standardization Sector, "The Directory: Abstract Service Definition", X.511(1993) (also ISO/IEC 9594-3:1993). Author's Address Kurt D. Zeilenga OpenLDAP Foundation EMail: Kurt@OpenLDAP.org Zeilenga Standards Track [Page 7] RFC 4527 LDAP Read Entry Controls June 2006 Full Copyright Statement Copyright (C) The Internet Society (2006). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Zeilenga Standards Track [Page 8] PK (�c\ iӑ . . ( doc/alt-openldap11-devel/rfc/rfc3062.txtnu �[��� Network Working Group K. Zeilenga Request for Comments: 3062 OpenLDAP Foundation Category: Standards Track February 2001 LDAP Password Modify Extended Operation Status of this Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2001). All Rights Reserved. Abstract The integration of the Lightweight Directory Access Protocol (LDAP) and external authentication services has introduced non-DN authentication identities and allowed for non-directory storage of passwords. As such, mechanisms which update the directory (e.g., Modify) cannot be used to change a user's password. This document describes an LDAP extended operation to allow modification of user passwords which is not dependent upon the form of the authentication identity nor the password storage mechanism used. 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. 1. Background and Intent of Use Lightweight Directory Access Protocol (LDAP) [RFC2251] is designed to support an number of authentication mechanisms including simple user name/password pairs. Traditionally, LDAP users where identified by the Distinguished Name [RFC2253] of a directory entry and this entry contained a userPassword [RFC2256] attribute containing one or more passwords. The protocol does not mandate that passwords associated with a user be stored in the directory server. The server may use any attribute suitable for password storage (e.g., userPassword), or use non- directory storage. Zeilenga Standards Track [Page 1] RFC 3062 LDAP Password Modify Extended Operation February 2001 The integration [RFC2829] of application neutral SASL [RFC2222] services which support simple username/password mechanisms (such as DIGEST-MD5) has introduced non-LDAP DN authentication identity forms and made storage of passwords the responsibility of the SASL service provider. LDAP update operations are designed to act upon attributes of an entry within the directory. LDAP update operations cannot be used to modify a user's password when the user is not represented by a DN, does not have a entry, or when that password used by the server is not stored as an attribute of an entry. An alternative mechanism is needed. This document describes an LDAP Extended Operation intended to allow directory clients to update user passwords. The user may or may not be associated with a directory entry. The user may or may not be represented as an LDAP DN. The user's password may or may not be stored in the directory. The operation SHOULD NOT be used without adequate security protection as the operation affords no privacy or integrity protect itself. This operation SHALL NOT be used anonymously. 2. Password Modify Request and Response The Password Modify operation is an LDAPv3 Extended Operation [RFC2251, Section 4.12] and is identified by the OBJECT IDENTIFIER passwdModifyOID. This section details the syntax of the protocol request and response. passwdModifyOID OBJECT IDENTIFIER ::= 1.3.6.1.4.1.4203.1.11.1 PasswdModifyRequestValue ::= SEQUENCE { userIdentity [0] OCTET STRING OPTIONAL oldPasswd [1] OCTET STRING OPTIONAL newPasswd [2] OCTET STRING OPTIONAL } PasswdModifyResponseValue ::= SEQUENCE { genPasswd [0] OCTET STRING OPTIONAL } 2.1. Password Modify Request A Password Modify request is an ExtendedRequest with the requestName field containing passwdModifyOID OID and optionally provides a requestValue field. If the requestValue field is provided, it SHALL contain a PasswdModifyRequestValue with one or more fields present. Zeilenga Standards Track [Page 2] RFC 3062 LDAP Password Modify Extended Operation February 2001 The userIdentity field, if present, SHALL contain an octet string representation of the user associated with the request. This string may or may not be an LDAPDN [RFC2253]. If no userIdentity field is present, the request acts up upon the password of the user currently associated with the LDAP session. The oldPasswd field, if present, SHALL contain the user's current password. The newPasswd field, if present, SHALL contain the desired password for this user. 2.2. Password Modify Response A Password Modify response is an ExtendedResponse where the responseName field is absent and the response field is optional. The response field, if present, SHALL contain a PasswdModifyResponseValue with genPasswd field present. The genPasswd field, if present, SHALL contain a generated password for the user. If an resultCode other than success (0) is indicated in the response, the response field MUST be absent. 3. Operation Requirements Clients SHOULD NOT submit a Password Modification request without ensuring adequate security safeguards are in place. Servers SHOULD return a non-success resultCode if sufficient security protection are not in place. Servers SHOULD indicate their support for this extended operation by providing PasswdModifyOID as a value of the supportedExtension attribute type in their root DSE. A server MAY choose to advertise this extension only when the client is authorized and/or has established the necessary security protections to use this operation. Clients SHOULD verify the server implements this extended operation prior to attempting the operation by asserting the supportedExtension attribute contains a value of PasswdModifyOID. The server SHALL only return success upon successfully changing the user's password. The server SHALL leave the password unmodified and return a non-success resultCode otherwise. If the server does not recognize provided fields or does not support the combination of fields provided, it SHALL NOT change the user password. Zeilenga Standards Track [Page 3] RFC 3062 LDAP Password Modify Extended Operation February 2001 If oldPasswd is present and the provided value cannot be verified or is incorrect, the server SHALL NOT change the user password. If oldPasswd is not present, the server MAY use other policy to determine whether or not to change the password. The server SHALL NOT generate a password on behalf of the client if the client has provided a newPasswd. In absence of a client provided newPasswd, the server SHALL either generate a password on behalf of the client or return a non-success result code. The server MUST provide the generated password upon success as the value of the genPasswd field. The server MAY return adminLimitExceeded, busy, confidentialityRequired, operationsError, unavailable, unwillingToPerform, or other non-success resultCode as appropriate to indicate that it was unable to successfully complete the operation. Servers MAY implement administrative policies which restrict this operation. 4. Security Considerations This operation is used to modify user passwords. The operation itself does not provide any security protection to ensure integrity and/or confidentiality of the information. Use of this operation is strongly discouraged when privacy protections are not in place to guarantee confidentiality and may result in the disclosure of the password to unauthorized parties. This extension MUST be used with confidentiality protection, such as Start TLS [RFC 2830]. The NULL cipher suite MUST NOT be used. 5. Bibliography [RFC2219] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 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. Zeilenga Standards Track [Page 4] RFC 3062 LDAP Password Modify Extended Operation February 2001 [RFC2253] Wahl, M., Kille,S. and T. Howes, "Lightweight Directory Access Protocol (v3): UTF-8 String Representation of Distinguished Names", RFC 2253, December 1997. [RFC2256] Wahl, M., "A Summary of the X.500(96) User Schema for use with LDAPv3", RFC 2256, December 1997. [RFC2829] Wahl, M., Alvestrand, H., Hodges, J. and R. Morgan, "Authentication Methods for LDAP", RFC 2829, May 2000. [RFC2830] Hodges, J., Morgan, R. and M. Wahl, "Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security", RFC 2830, May 2000. 6. Acknowledgment This document borrows from a number of IETF documents and is based upon input from the IETF LDAPext working group. 7. Author's Address Kurt D. Zeilenga OpenLDAP Foundation EMail: Kurt@OpenLDAP.org Zeilenga Standards Track [Page 5] RFC 3062 LDAP Password Modify Extended Operation February 2001 8. 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 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. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Zeilenga Standards Track [Page 6] PK (�c\�7�i i ( doc/alt-openldap11-devel/rfc/rfc3727.txtnu �[��� Network Working Group S. Legg Request for Comments: 3727 Adacel Technologies Category: Standards Track February 2004 ASN.1 Module Definition for the LDAP and X.500 Component Matching Rules Status of this Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2004). All Rights Reserved. Abstract This document updates the specification of the component matching rules for Lightweight Directory Access Protocol (LDAP) and X.500 directories (RFC3687) by collecting the Abstract Syntax Notation One (ASN.1) definitions of the component matching rules into an appropriately identified ASN.1 module so that other specifications may reference the component matching rule definitions from within their own ASN.1 modules. 1. Introduction The structure or data type of data held in an attribute of a Lightweight Directory Access Protocol (LDAP) [LDAP] or X.500 [X500] directory is described by the attribute's syntax. Attribute syntaxes range from simple data types, such as text string, integer, or boolean, to complex data types, for example, the syntaxes of the directory schema operational attributes. RFC 3687 [CMR] defines a generic way of matching user selected components in a directory attribute value of any arbitrarily complex attribute syntax. This document updates RFC 3687 by collecting the Abstract Syntax Notation One (ASN.1) [ASN1] definitions of RFC 3687 into an appropriately identified ASN.1 module so that other specifications may reference these definitions from within their own ASN.1 modules. Legg Standards Track [Page 1] RFC 3727 Module for Component Matching February 2004 2. Module Definition for Component Matching ComponentMatching {iso(1) 2 36 79672281 xed(3) module(0) component-matching(4)} -- Copyright (C) The Internet Society (2004). This version of -- this ASN.1 module is part of RFC 3727; see the RFC itself -- for full legal notices. DEFINITIONS EXPLICIT TAGS EXTENSIBILITY IMPLIED ::= BEGIN IMPORTS MATCHING-RULE, RelativeDistinguishedName FROM InformationFramework {joint-iso-itu-t ds(5) module(1) informationFramework(1) 4} ; ComponentAssertion ::= SEQUENCE { component ComponentReference (SIZE(1..MAX)) OPTIONAL, useDefaultValues BOOLEAN DEFAULT TRUE, rule MATCHING-RULE.&id, value MATCHING-RULE.&AssertionType } ComponentReference ::= UTF8String ComponentFilter ::= CHOICE { item [0] ComponentAssertion, and [1] SEQUENCE OF ComponentFilter, or [2] SEQUENCE OF ComponentFilter, not [3] ComponentFilter } componentFilterMatch MATCHING-RULE ::= { SYNTAX ComponentFilter ID { 1 2 36 79672281 1 13 2 } } allComponentsMatch MATCHING-RULE ::= { ID { 1 2 36 79672281 1 13 6 } } directoryComponentsMatch MATCHING-RULE ::= { ID { 1 2 36 79672281 1 13 7 } } -- Additional Useful Matching Rules -- rdnMatch MATCHING-RULE ::= { Legg Standards Track [Page 2] RFC 3727 Module for Component Matching February 2004 SYNTAX RelativeDistinguishedName ID { 1 2 36 79672281 1 13 3 } } presentMatch MATCHING-RULE ::= { SYNTAX NULL ID { 1 2 36 79672281 1 13 5 } } END The InformationFramework ASN.1 module from which the MATCHING-RULE and RelativeDistinguishedName definitions are imported is defined in X.501 [X501]. The object identifiers used in this document have been assigned for use in specifying the component matching rules by Adacel Technologies, under an arc assigned to Adacel by Standards Australia. 3. Security Considerations This document collects together the ASN.1 definitions of the component matching rules into an ASN.1 module, but does not modify those definitions in any way. See RFC 3687 [CMR] for the security considerations of using the component matching rules. 4. References 4.1. Normative References [CMR] Legg, S., "Lightweight Directory Access Protocol (LDAP) and X.500 Component Matching Rules", RFC 3687, February 2004. [X501] ITU-T Recommendation X.501 (1993) | ISO/IEC 9594-2:1994, Information Technology - Open Systems Interconnection - The Directory: Models [ASN1] ITU-T Recommendation X.680 (07/02) | ISO/IEC 8824-1:2002, Information technology - Abstract Syntax Notation One (ASN.1): Specification of basic notation 4.2. Informative References [LDAP] Hodges, J. and R. Morgan, "Lightweight Directory Access Protocol (v3): Technical Specification", RFC 3377, September 2002. [X500] ITU-T Recommendation X.500 (1993) | ISO/IEC 9594-1:1994, Information Technology - Open Systems Interconnection - The Directory: Overview of concepts, models and services Legg Standards Track [Page 3] RFC 3727 Module for Component Matching February 2004 5. Author's Address Steven Legg Adacel Technologies Ltd. 250 Bay Street Brighton, Victoria 3186 AUSTRALIA Phone: +61 3 8530 7710 Fax: +61 3 8530 7888 EMail: steven.legg@adacel.com.au Legg Standards Track [Page 4] RFC 3727 Module for Component Matching February 2004 6. Full Copyright Statement Copyright (C) The Internet Society (2004). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Legg Standards Track [Page 5] PK )�c\��2� x x ( doc/alt-openldap11-devel/rfc/rfc3687.txtnu �[��� Network Working Group S. Legg Request for Comments: 3687 Adacel Technologies Category: Standards Track February 2004 Lightweight Directory Access Protocol (LDAP) and X.500 Component Matching Rules Status of this Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2004). All Rights Reserved. Abstract The syntaxes of attributes in a Lightweight Directory Access Protocol (LDAP) or X.500 directory range from simple data types, such as text string, integer, or boolean, to complex structured data types, such as the syntaxes of the directory schema operational attributes. Matching rules defined for the complex syntaxes usually only provide the most immediately useful matching capability. This document defines generic matching rules that can match any user selected component parts in an attribute value of any arbitrarily complex attribute syntax. Legg Standards Track [Page 1] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. ComponentAssertion . . . . . . . . . . . . . . . . . . . . . . 5 3.1. Component Reference. . . . . . . . . . . . . . . . . . . 6 3.1.1. Component Type Substitutions . . . . . . . . . . 7 3.1.2. Referencing SET, SEQUENCE and CHOICE Components. 8 3.1.3. Referencing SET OF and SEQUENCE OF Components. . 9 3.1.4. Referencing Components of Parameterized Types. . 10 3.1.5. Component Referencing Example. . . . . . . . . . 10 3.1.6. Referencing Components of Open Types . . . . . . 12 3.1.6.1. Open Type Referencing Example . . . . . 12 3.1.7. Referencing Contained Types. . . . . . . . . . . 14 3.1.7.1. Contained Type Referencing Example. . . 14 3.2. Matching of Components . . . . . . . . . . . . . . . . . 15 3.2.1. Applicability of Existing Matching Rules . . . . 17 3.2.1.1. String Matching . . . . . . . . . . . . 17 3.2.1.2. Telephone Number Matching . . . . . . . 17 3.2.1.3. Distinguished Name Matching . . . . . . 18 3.2.2. Additional Useful Matching Rules . . . . . . . . 18 3.2.2.1. The rdnMatch Matching Rule. . . . . . . 18 3.2.2.2. The presentMatch Matching Rule. . . . . 19 3.2.3. Summary of Useful Matching Rules . . . . . . . . 20 4. ComponentFilter. . . . . . . . . . . . . . . . . . . . . . . . 21 5. The componentFilterMatch Matching Rule . . . . . . . . . . . . 22 6. Equality Matching of Complex Components. . . . . . . . . . . . 24 6.1. The OpenAssertionType Syntax . . . . . . . . . . . . . . 24 6.2. The allComponentsMatch Matching Rule . . . . . . . . . . 25 6.3. Deriving Component Equality Matching Rules . . . . . . . 27 6.4. The directoryComponentsMatch Matching Rule . . . . . . . 28 7. Component Matching Examples. . . . . . . . . . . . . . . . . . 30 8. Security Considerations. . . . . . . . . . . . . . . . . . . . 37 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 37 10. IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 37 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 38 11.1. Normative References. . . . . . . . . . . . . . . . . . 38 11.2. Informative References. . . . . . . . . . . . . . . . . 40 12. Intellectual Property Statement. . . . . . . . . . . . . . . . 40 13. Author's Address . . . . . . . . . . . . . . . . . . . . . . . 41 14. Full Copyright Statement . . . . . . . . . . . . . . . . . . . 42 Legg Standards Track [Page 2] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 1. Introduction The structure or data type of data held in an attribute of a Lightweight Directory Access Protocol (LDAP) [7] or X.500 [19] directory is described by the attribute's syntax. Attribute syntaxes range from simple data types, such as text string, integer, or boolean, to complex data types, for example, the syntaxes of the directory schema operational attributes. In X.500, the attribute syntaxes are explicitly described by Abstract Syntax Notation One (ASN.1) [13] type definitions. ASN.1 type notation has a number of simple data types (e.g., PrintableString, INTEGER, BOOLEAN), and combining types (i.e., SET, SEQUENCE, SET OF, SEQUENCE OF, and CHOICE) for constructing arbitrarily complex data types from simpler component types. In LDAP, the attribute syntaxes are usually described in Augmented Backus-Naur Form (ABNF) [2], though there is an implied association between the LDAP attribute syntaxes and the X.500 ASN.1 types. To a large extent, the data types of attribute values in either an LDAP or X.500 directory are described by ASN.1 types. This formal description can be exploited to identify component parts of an attribute value for a variety of purposes. This document addresses attribute value matching. With any complex attribute syntax there is normally a requirement to partially match an attribute value of that syntax by matching only selected components of the value. Typically, matching rules specific to the attribute syntax are defined to fill this need. These highly specific matching rules usually only provide the most immediately useful matching capability. Some complex attribute syntaxes don't even have an equality matching rule let alone any additional matching rules for partial matching. This document defines a generic way of matching user selected components in an attribute value of any arbitrarily complex attribute syntax, where that syntax is described using ASN.1 type notation. All of the type notations defined in X.680 [13] are supported. Section 3 describes the ComponentAssertion, a testable assertion about the value of a component of an attribute value of any complex syntax. Section 4 introduces the ComponentFilter assertion, which is an expression of ComponentAssertions. The ComponentFilter enables more powerful filter matching of components in an attribute value. Section 5 defines the componentFilterMatch matching rule, which enables a ComponentFilter to be evaluated against attribute values. Legg Standards Track [Page 3] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 Section 6 defines matching rules for component-wise equality matching of attribute values of any syntax described by an ASN.1 type definition. Examples showing the usage of componentFilterMatch are in Section 7. For a new attribute syntax, the Generic String Encoding Rules [9] and the specifications in sections 3 to 6 of this document make it possible to fully and precisely define the LDAP-specific encoding, the LDAP and X.500 binary encoding (and possibly other ASN.1 encodings in the future), a suitable equality matching rule, and a comprehensive collection of component matching capabilities, by simply writing down an ASN.1 type definition for the syntax. These implicit definitions are also automatically extended if the ASN.1 type is later extended. The algorithmic relationship between the ASN.1 type definition, the various encodings and the component matching behaviour makes directory server implementation support for the component matching rules amenable to automatic code generation from ASN.1 type definitions. Schema designers have the choice of storing related items of data as a single attribute value of a complex syntax in some entry, or as a subordinate entry where the related data items are stored as separate attribute values of simpler syntaxes. The inability to search component parts of a complex syntax has been used as an argument for favouring the subordinate entries approach. The component matching rules provide the analogous matching capability on an attribute value of a complex syntax that a search filter has on a subordinate entry. Most LDAP syntaxes have corresponding ASN.1 type definitions, though they are usually not reproduced or referenced alongside the formal definition of the LDAP syntax. Syntaxes defined with only a character string encoding, i.e., without an explicit or implied corresponding ASN.1 type definition, cannot use the component matching capabilities described in this document unless and until a semantically equivalent ASN.1 type definition is defined for them. 2. Conventions Throughout this document "type" shall be taken to mean an ASN.1 type unless explicitly qualified as an attribute type, and "value" shall be taken to mean an ASN.1 value unless explicitly qualified as an attribute value. Legg Standards Track [Page 4] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 Note that "ASN.1 value" does not mean a Basic Encoding Rules (BER) [17] encoded value. The ASN.1 value is an abstract concept that is independent of any particular encoding. BER is just one possible encoding of an ASN.1 value. The component matching rules operate at the abstract level without regard for the possible encodings of a value. Attribute type and matching rule definitions in this document are provided in both the X.500 [10] and LDAP [4] description formats. Note that the LDAP descriptions have been rendered with additional white-space and line breaks for the sake of readability. 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 BCP 14, RFC 2119 [1]. The key word "OPTIONAL" is exclusively used with its ASN.1 meaning. 3. ComponentAssertion A ComponentAssertion is an assertion about the presence, or values of, components within an ASN.1 value, i.e., an instance of an ASN.1 type. The ASN.1 value is typically an attribute value, where the ASN.1 type is the syntax of the attribute. However, a ComponentAssertion may also be applied to a component part of an attribute value. The assertion evaluates to either TRUE, FALSE or Undefined for each tested ASN.1 value. A ComponentAssertion is described by the following ASN.1 type (assumed to be defined with "EXPLICIT TAGS" in force): ComponentAssertion ::= SEQUENCE { component ComponentReference (SIZE(1..MAX)) OPTIONAL, useDefaultValues BOOLEAN DEFAULT TRUE, rule MATCHING-RULE.&id, value MATCHING-RULE.&AssertionType } ComponentReference ::= UTF8String MATCHING-RULE.&id equates to the OBJECT IDENTIFIER of a matching rule. MATCHING-RULE.&AssertionType is an open type (formerly known as the ANY type). The "component" field of a ComponentAssertion identifies which component part of a value of some ASN.1 type is to be tested, the "useDefaultValues" field indicates whether DEFAULT values are to be substituted for absent component values, the "rule" field indicates Legg Standards Track [Page 5] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 how the component is to be tested, and the "value" field is an asserted ASN.1 value against which the component is tested. The ASN.1 type of the asserted value is determined by the chosen rule. The fields of a ComponentAssertion are described in detail in the following sections. 3.1. Component Reference The component field in a ComponentAssertion is a UTF-8 character string [6] whose textual content is a component reference, identifying a component part of some ASN.1 type or value. A component reference conforms to the following ABNF [2], which extends the notation defined in Clause 14 of X.680 [13]: component-reference = ComponentId *( "." ComponentId ) ComponentId = identifier / from-beginning / count / from-end / ; extends Clause 14 content / ; extends Clause 14 select / ; extends Clause 14 all identifier = lowercase *alphanumeric *(hyphen 1*alphanumeric) alphanumeric = uppercase / lowercase / decimal-digit uppercase = %x41-5A ; "A" to "Z" lowercase = %x61-7A ; "a" to "z" hyphen = "-" from-beginning = positive-number count = "0" from-end = "-" positive-number content = %x63.6F.6E.74.65.6E.74 ; "content" select = "(" Value *( "," Value ) ")" all = "*" positive-number = non-zero-digit *decimal-digit decimal-digit = %x30-39 ; "0" to "9" non-zero-digit = %x31-39 ; "1" to "9" Legg Standards Track [Page 6] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 An <identifier> conforms to the definition of an identifier in ASN.1 notation (Clause 11.3 of X.680 [13]). It begins with a lowercase letter and is followed by zero or more letters, digits, and hyphens. A hyphen is not permitted to be the last character and a hyphen is not permitted to be followed by another hyphen. The <Value> rule is described by the Generic String Encoding Rules (GSER) [9]. A component reference is a sequence of one or more ComponentIds where each successive ComponentId identifies either an inner component at the next level of nesting of an ASN.1 combining type, i.e., SET, SEQUENCE, SET OF, SEQUENCE OF, or CHOICE, or a specific type within an ASN.1 open type. A component reference is always considered in the context of a particular complex ASN.1 type. When applied to the ASN.1 type the component reference identifies a specific component type. When applied to a value of the ASN.1 type a component reference identifies zero, one or more component values of that component type. The component values are potentially in a DEFAULT value if useDefaultValues is TRUE. The specific component type identified by the component reference determines what matching rules are capable of being used to match the component values. The component field in a ComponentAssertion may also be absent, in which case the identified component type is the ASN.1 type to which the ComponentAssertion is applied, and the identified component value is the whole ASN.1 value. A valid component reference for a particular complex ASN.1 type is constructed by starting with the outermost combining type and repeatedly selecting one of the permissible forms of ComponentId to identify successively deeper nested components. A component reference MAY identify a component with a complex ASN.1 type, i.e., it is not required that the component type identified by a component reference be a simple ASN.1 type. 3.1.1. Component Type Substitutions ASN.1 type notation has a number of constructs for referencing other defined types, and constructs that are irrelevant for matching purposes. These constructs are not represented in a component reference in any way and substitutions of the component type are performed to eliminate them from further consideration. These substitutions automatically occur prior to each ComponentId, whether constructing or interpreting a component reference, but do not occur after the last ComponentId, except as allowed by Section 3.2. Legg Standards Track [Page 7] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 If the ASN.1 type is an ASN.1 type reference then the component type is taken to be the actual definition on the right hand side of the type assignment for the referenced type. If the ASN.1 type is a tagged type then the component type is taken to be the type without the tag. If the ASN.1 type is a constrained type (see X.680 [13] and X.682 [15] for the details of ASN.1 constraint notation) then the component type is taken to be the type without the constraint. If the ASN.1 type is an ObjectClassFieldType (Clause 14 of X.681 [14]) that denotes a specific ASN.1 type (e.g., MATCHING-RULE.&id denotes the OBJECT IDENTIFIER type) then the component type is taken to be the denoted type. Section 3.1.6 describes the case where the ObjectClassFieldType denotes an open type. If the ASN.1 type is a selection type other than one used in the list of components for a SET or SEQUENCE type then the component type is taken to be the selected alternative type from the named CHOICE. If the ASN.1 type is a TypeFromObject (Clause 15 of X.681 [14]) then the component type is taken to be the denoted type. If the ASN.1 type is a ValueSetFromObjects (Clause 15 of X.681 [14]) then the component type is taken to be the governing type of the denoted values. 3.1.2. Referencing SET, SEQUENCE and CHOICE Components If the ASN.1 type is a SET or SEQUENCE type then the <identifier> form of ComponentId may be used to identify the component type within that SET or SEQUENCE having that identifier. If <identifier> references an OPTIONAL component type and that component is not present in a particular value then there are no corresponding component values. If <identifier> references a DEFAULT component type and useDefaultValues is TRUE (the default setting for useDefaultValues) and that component is not present in a particular value then the component value is taken to be the default value. If <identifier> references a DEFAULT component type and useDefaultValues is FALSE and that component is not present in a particular value then there are no corresponding component values. If the ASN.1 type is a CHOICE type then the <identifier> form of ComponentId may be used to identify the alternative type within that CHOICE having that identifier. If <identifier> references an alternative other than the one used in a particular value then there are no corresponding component values. Legg Standards Track [Page 8] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 The COMPONENTS OF notation in Clause 24 of X.680 [13] augments the defined list of components in a SET or SEQUENCE type by including all the components of another defined SET or SEQUENCE type respectively. These included components are referenced directly by identifier as though they were defined in-line in the SET or SEQUENCE type containing the COMPONENTS OF notation. The SelectionType (Clause 29 of X.680 [13]), when used in the list of components for a SET or SEQUENCE type, includes a single component from a defined CHOICE type. This included component is referenced directly by identifier as though it was defined in-line in the SET or SEQUENCE type. The REAL type is treated as though it is the SEQUENCE type defined in Clause 20.5 of X.680 [13]. The EMBEDDED PDV type is treated as though it is the SEQUENCE type defined in Clause 33.5 of X.680 [13]. The EXTERNAL type is treated as though it is the SEQUENCE type defined in Clause 8.18.1 of X.690 [17]. The unrestricted CHARACTER STRING type is treated as though it is the SEQUENCE type defined in Clause 40.5 of X.680 [13]. The INSTANCE OF type is treated as though it is the SEQUENCE type defined in Annex C of X.681 [14]. The <identifier> form MUST NOT be used on any other ASN.1 type. 3.1.3. Referencing SET OF and SEQUENCE OF Components If the ASN.1 type is a SET OF or SEQUENCE OF type then the <from-beginning>, <from-end>, <count> and <all> forms of ComponentId may be used. The <from-beginning> form of ComponentId may be used to identify one instance (i.e., value) of the component type of the SET OF or SEQUENCE OF type (e.g., if Foo ::= SET OF Bar, then Bar is the component type), where the instances are numbered from one upwards. If <from-beginning> references a higher numbered instance than the last instance in a particular value of the SET OF or SEQUENCE OF type then there is no corresponding component value. The <from-end> form of ComponentId may be used to identify one instance of the component type of the SET OF or SEQUENCE OF type, where "-1" is the last instance, "-2" is the second last instance, Legg Standards Track [Page 9] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 and so on. If <from-end> references a lower numbered instance than the first instance in a particular value of the SET OF or SEQUENCE OF type then there is no corresponding component value. The <count> form of ComponentId identifies a notional count of the number of instances of the component type in a value of the SET OF or SEQUENCE OF type. This count is not explicitly represented but for matching purposes it has an assumed ASN.1 type of INTEGER (0..MAX). A ComponentId of the <count> form, if used, MUST be the last ComponentId in a component reference. The <all> form of ComponentId may be used to simultaneously identify all instances of the component type of the SET OF or SEQUENCE OF type. It is through the <all> form that a component reference can identify more than one component value. However, if a particular value of the SET OF or SEQUENCE OF type is an empty list, then there are no corresponding component values. Where multiple component values are identified, the remaining ComponentIds in the component reference, if any, can identify zero, one or more subcomponent values for each of the higher level component values. The corresponding ASN.1 type for the <from-beginning>, <from-end>, and <all> forms of ComponentId is the component type of the SET OF or SEQUENCE OF type. The <from-beginning>, <count>, <from-end> and <all> forms MUST NOT be used on ASN.1 types other than SET OF or SEQUENCE OF. 3.1.4. Referencing Components of Parameterized Types A component reference cannot be formed for a parameterized type unless the type has been used with actual parameters, in which case the type is treated as though the DummyReferences [16] have been substituted with the actual parameters. 3.1.5. Component Referencing Example Consider the following ASN.1 type definitions. ExampleType ::= SEQUENCE { part1 [0] INTEGER, part2 [1] ExampleSet, part3 [2] SET OF OBJECT IDENTIFIER, part4 [3] ExampleChoice } Legg Standards Track [Page 10] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 ExampleSet ::= SET { option PrintableString, setting BOOLEAN } ExampleChoice ::= CHOICE { eeny-meeny BIT STRING, miney-mo OCTET STRING } Following are component references constructed with respect to the type ExampleType. The component reference "part1" identifies a component of a value of ExampleType having the ASN.1 tagged type [0] INTEGER. The component reference "part2" identifies a component of a value of ExampleType having the ASN.1 type of [1] ExampleSet The component reference "part2.option" identifies a component of a value of ExampleType having the ASN.1 type of PrintableString. A ComponentAssertion could also be applied to a value of ASN.1 type ExampleSet, in which case the component reference "option" would identify the same kind of information. The component reference "part3" identifies a component of a value of ExampleType having the ASN.1 type of [2] SET OF OBJECT IDENTIFIER. The component reference "part3.2" identifies the second instance of the part3 SET OF. The instance has the ASN.1 type of OBJECT IDENTIFIER. The component reference "part3.0" identifies the count of the number of instances in the part3 SET OF. The count has the corresponding ASN.1 type of INTEGER (0..MAX). The component reference "part3.*" identifies all the instances in the part3 SET OF. Each instance has the ASN.1 type of OBJECT IDENTIFIER. The component reference "part4" identifies a component of a value of ExampleType having the ASN.1 type of [3] ExampleChoice. The component reference "part4.miney-mo" identifies a component of a value of ExampleType having the ASN.1 type of OCTET STRING. Legg Standards Track [Page 11] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 3.1.6. Referencing Components of Open Types If a sequence of ComponentIds identifies an ObjectClassFieldType denoting an open type (e.g., ATTRIBUTE.&Type denotes an open type) then the ASN.1 type of the component varies. An open type is typically constrained by some other component(s) in an outer enclosing type, either formally through the use of a component relation constraint [15], or informally in the accompanying text, so the actual ASN.1 type of a value of the open type will generally be known. The constraint will also limit the range of permissible types. The <select> form of ComponentId may be used to identify one of these permissible types in an open type. Subcomponents of that type can then be identified with further ComponentIds. The other components constraining the open type are termed the referenced components [15]. The <select> form contains a list of one or more values which take the place of the value(s) of the referenced component(s) to uniquely identify one of the permissible types of the open type. Where the open type is constrained by a component relation constraint, there is a <Value> in the <select> form for each of the referenced components in the component relation constraint, appearing in the same order. The ASN.1 type of each of these values is the same as the ASN.1 type of the corresponding referenced component. The type of a referenced component is potentially any ASN.1 type however it is typically an OBJECT IDENTIFIER or INTEGER, which means that the <Value> in the <select> form of ComponentId will nearly always be an <ObjectIdentifierValue> or <IntegerValue> [9]. Furthermore, component relation constraints typically have only one referenced component. Where the open type is not constrained by a component relation constraint, the specification introducing the syntax containing the open type should explicitly nominate the referenced components and their order, so that the <select> form can be used. If an instance of <select> contains a value other than the value of the referenced component used in a particular value of the outer enclosing type then there are no corresponding component values for the open type. 3.1.6.1. Open Type Referencing Example The ASN.1 type AttributeTypeAndValue [10] describes a single attribute value of a nominated attribute type. Legg Standards Track [Page 12] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 AttributeTypeAndValue ::= SEQUENCE { type ATTRIBUTE.&id ({SupportedAttributes}), value ATTRIBUTE.&Type ({SupportedAttributes}{@type}) } ATTRIBUTE.&id denotes an OBJECT IDENTIFIER and ({SupportedAttributes}) constrains the OBJECT IDENTIFIER to be a supported attribute type. ATTRIBUTE.&Type denotes an open type, in this case an attribute value, and ({SupportedAttributes}{@type}) is a component relation constraint that constrains the open type to be of the attribute syntax for the attribute type. The component relation constraint references only the "type" component, which has the ASN.1 type of OBJECT IDENTIFIER, thus if the <select> form of ComponentId is used to identify attribute values of specific attribute types it will contain a single OBJECT IDENTIFIER value. The component reference "value" on AttributeTypeAndValue refers to the open type. One of the X.500 standard attributes is facsimileTelephoneNumber [12], which is identified with the OBJECT IDENTIFIER 2.5.4.23, and is defined to have the following syntax. FacsimileTelephoneNumber ::= SEQUENCE { telephoneNumber PrintableString(SIZE(1..ub-telephone-number)), parameters G3FacsimileNonBasicParameters OPTIONAL } The component reference "value.(2.5.4.23)" on AttributeTypeAndValue specifies an attribute value with the FacsimileTelephoneNumber syntax. The component reference "value.(2.5.4.23).telephoneNumber" on AttributeTypeAndValue identifies the telephoneNumber component of a facsimileTelephoneNumber attribute value. The component reference "value.(facsimileTelephoneNumber)" is equivalent to "value.(2.5.4.23)". If the AttributeTypeAndValue ASN.1 value contains an attribute type other than facsimileTelephoneNumber then there are no corresponding component values for the component references "value.(2.5.4.23)" and "value.(2.5.4.23).telephoneNumber". Legg Standards Track [Page 13] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 3.1.7. Referencing Contained Types Sometimes the contents of a BIT STRING or OCTET STRING value are required to be the encodings of other ASN.1 values of specific ASN.1 types. For example, the extnValue component of the Extension type component in the Certificate type [11] is an OCTET STRING that is required to contain a Distinguished Encoding Rules (DER) [17] encoding of a certificate extension value. It is useful to be able to refer to the embedded encoded value and its components. An embedded encoded value is here referred to as a contained value and its associated type as the contained type. If the ASN.1 type is a BIT STRING or OCTET STRING type containing encodings of other ASN.1 values then the <content> form of ComponentId may be used to identify the contained type. Subcomponents of that type can then be identified with further ComponentIds. The contained type may be (effectively) an open type, constrained by some other component in an outer enclosing type (e.g., in a certificate Extension, extnValue is constrained by the chosen extnId). In these cases the next ComponentId, if any, MUST be of the <select> form. For the purpose of building component references, the content of the extnValue OCTET STRING in the Extension type is assumed to be an open type having a notional component relation constraint with the extnId component as the single referenced component, i.e., EXTENSION.&ExtnType ({ExtensionSet}{@extnId}) The data-value component of the associated types for the EMBEDDED PDV and CHARACTER STRING types is an OCTET STRING containing the encoding of a data value described by the identification component. For the purpose of building component references, the content of the data-value OCTET STRING in these types is assumed to be an open type having a notional component relation constraint with the identification component as the single referenced component. 3.1.7.1. Contained Type Referencing Example The Extension ASN.1 type [11] describes a single certificate extension value of a nominated extension type. Legg Standards Track [Page 14] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 Extension ::= SEQUENCE { extnId EXTENSION.&id ({ExtensionSet}), critical BOOLEAN DEFAULT FALSE, extnValue OCTET STRING -- contains a DER encoding of a value of type &ExtnType -- for the extension object identified by extnId -- } EXTENSION.&id denotes an OBJECT IDENTIFIER and ({ExtensionSet}) constrains the OBJECT IDENTIFIER to be the identifier of a supported certificate extension. The component reference "extnValue" on Extension refers to a component type of OCTET STRING. The corresponding component values will be OCTET STRING values. The component reference "extnValue.content" on Extension refers to the type of the contained type, which in this case is an open type. One of the X.509 [11] standard extensions is basicConstraints, which is identified with the OBJECT IDENTIFIER 2.5.29.19 and is defined to have the following syntax. BasicConstraintsSyntax ::= SEQUENCE { cA BOOLEAN DEFAULT FALSE, pathLenConstraint INTEGER (0..MAX) OPTIONAL } The component reference "extnValue.content.(2.5.29.19)" on Extension specifies a BasicConstraintsSyntax extension value and the component reference "extnValue.content.(2.5.29.19).cA" identifies the cA component of a BasicConstraintsSyntax extension value. 3.2. Matching of Components The rule in a ComponentAssertion specifies how the zero, one or more component values identified by the component reference are tested by the assertion. Attribute matching rules are used to specify the semantics of the test. Each matching rule has a notional set of attribute syntaxes (typically one), defined as ASN.1 types, to which it may be applied. When used in a ComponentAssertion these matching rules apply to the same ASN.1 types, only in this context the corresponding ASN.1 values are not necessarily complete attribute values. Note that the referenced component type may be a tagged and/or constrained version of the expected attribute syntax (e.g., [0] INTEGER, whereas integerMatch would expect simply INTEGER), or an open type. Additional type substitutions of the kind described in Legg Standards Track [Page 15] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 Section 3.1.1 are performed as required to reduce the component type to the same type as the attribute syntax expected by the matching rule. If a matching rule applies to more than one attribute syntax (e.g., objectIdentifierFirstComponentMatch [12]) then the minimum number of substitutions required to conform to any one of those syntaxes is performed. If a matching rule can apply to any attribute syntax (e.g., the allComponentsMatch rule defined in Section 6.2) then the referenced component type is used as is, with no additional substitutions. The value in a ComponentAssertion will be of the assertion syntax (i.e., ASN.1 type) required by the chosen matching rule. Note that the assertion syntax of a matching rule is not necessarily the same as the attribute syntax(es) to which the rule may be applied. Some matching rules do not have a fixed assertion syntax (e.g., allComponentsMatch). The required assertion syntax is determined in each instance of use by the syntax of the attribute type to which the matching rule is applied. For these rules the ASN.1 type of the referenced component is used in place of an attribute syntax to decide the required assertion syntax. The ComponentAssertion is Undefined if: a) the matching rule in the ComponentAssertion is not known to the evaluating procedure, b) the matching rule is not applicable to the referenced component type, even with the additional type substitutions, c) the value in the ComponentAssertion does not conform to the assertion syntax defined for the matching rule, d) some part of the component reference identifies an open type in the tested value that cannot be decoded, or e) the implementation does not support the particular combination of component reference and matching rule. If the ComponentAssertion is not Undefined then the ComponentAssertion evaluates to TRUE if there is at least one component value for which the matching rule applied to that component value returns TRUE, and evaluates to FALSE otherwise (which includes the case where there are no component values). Legg Standards Track [Page 16] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 3.2.1. Applicability of Existing Matching Rules 3.2.1.1. String Matching ASN.1 has a number of built in restricted character string types with different character sets and/or different character encodings. A directory user generally has little interest in the particular character set or encoding used to represent a character string component value, and some directory server implementations make no distinction between the different string types in their internal representation of values. So rather than define string matching rules for each of the restricted character string types, the existing case ignore and case exact string matching rules are extended to apply to component values of any of the restricted character string types and any ChoiceOfStrings type [9], in addition to component values of the DirectoryString type. This extension is only for the purposes of component matching described in this document. The relevant string matching rules are: caseIgnoreMatch, caseIgnoreOrderingMatch, caseIgnoreSubstringsMatch, caseExactMatch, caseExactOrderingMatch and caseExactSubstringsMatch. The relevant restricted character string types are: NumericString, PrintableString, VisibleString, IA5String, UTF8String, BMPString, UniversalString, TeletexString, VideotexString, GraphicString and GeneralString. A ChoiceOfStrings type is a purely syntactic CHOICE of these ASN.1 string types. Note that GSER [9] declares each and every use of the DirectoryString{} parameterized type to be a ChoiceOfStrings type. The assertion syntax of the string matching rules is still DirectoryString regardless of the string syntax of the component being matched. Thus an implementation will be called upon to compare a DirectoryString value to a value of one of the restricted character string types, or a ChoiceOfStrings type. As is the case when comparing two DirectoryStrings where the chosen alternatives are of different string types, the comparison proceeds so long as the corresponding characters are representable in both character sets. Otherwise matching returns FALSE. 3.2.1.2. Telephone Number Matching Early editions of X.520 [12] gave the syntax of the telephoneNumber attribute as a constrained PrintableString. The fourth edition of X.520 equates the ASN.1 type name TelephoneNumber to the constrained PrintableString and uses TelephoneNumber as the attribute and assertion syntax. For the purposes of component matching, Legg Standards Track [Page 17] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 telephoneNumberMatch and telephoneNumberSubstringsMatch are permitted to be applied to any PrintableString value, as well as to TelephoneNumber values. 3.2.1.3. Distinguished Name Matching The DistinguishedName type is defined by assignment to be the same as the RDNSequence type, however RDNSequence is sometimes directly used in other type definitions. For the purposes of component matching, distinguishedNameMatch is also permitted to be applied to values of the RDNSequence type. 3.2.2. Additional Useful Matching Rules This section defines additional matching rules that may prove useful in ComponentAssertions. These rules may also be used in extensibleMatch search filters [3]. 3.2.2.1. The rdnMatch Matching Rule The distinguishedNameMatch matching rule can match whole distinguished names but it is sometimes useful to be able to match specific Relative Distinguished Names (RDNs) in a Distinguished Name (DN) without regard for the other RDNs in the DN. The rdnMatch matching rule allows component RDNs of a DN to be tested. The LDAP-style definitions for rdnMatch and its assertion syntax are: ( 1.2.36.79672281.1.13.3 NAME 'rdnMatch' SYNTAX 1.2.36.79672281.1.5.0 ) ( 1.2.36.79672281.1.5.0 DESC 'RDN' ) The LDAP-specific encoding for a value of the RDN syntax is given by the <RelativeDistinguishedNameValue> rule [9]. The X.500-style definition for rdnMatch is: rdnMatch MATCHING-RULE ::= { SYNTAX RelativeDistinguishedName ID { 1 2 36 79672281 1 13 3 } } The rdnMatch rule evaluates to true if the component value and assertion value are the same RDN, using the same RDN comparison method as distinguishedNameMatch. Legg Standards Track [Page 18] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 When using rdnMatch to match components of DNs it is important to note that the LDAP-specific encoding of a DN [5] reverses the order of the RDNs. So for the DN represented in LDAP as "cn=Steven Legg,o=Adacel,c=AU", the RDN "cn=Steven Legg" corresponds to the component reference "3", or alternatively, "-1". 3.2.2.2. The presentMatch Matching Rule At times it would be useful to test not if a specific value of a particular component is present, but whether any value of a particular component is present. The presentMatch matching rule allows the presence of a particular component value to be tested. The LDAP-style definitions for presentMatch and its assertion syntax are: ( 1.2.36.79672281.1.13.5 NAME 'presentMatch' SYNTAX 1.2.36.79672281.1.5.1 ) ( 1.2.36.79672281.1.5.1 DESC 'NULL' ) The LDAP-specific encoding for a value of the NULL syntax is given by the <NullValue> rule [9]. The X.500-style definition for presentMatch is: presentMatch MATCHING-RULE ::= { SYNTAX NULL ID { 1 2 36 79672281 1 13 5 } } When used in a extensible match filter item, presentMatch behaves like the "present" case of a regular search filter. In a ComponentAssertion, presentMatch evaluates to TRUE if and only if the component reference identifies one or more component values, regardless of the actual component value contents. Note that if useDefaultValues is TRUE then the identified component values may be (part of) a DEFAULT value. The notional count referenced by the <count> form of ComponentId is taken to be present if the SET OF value is present, and absent otherwise. Note that in ASN.1 notation an absent SET OF value is distinctly different from a SET OF value that is present but empty. It is up to the specification using the ASN.1 notation to decide whether the distinction matters. Often an empty SET OF component and an absent SET OF component are treated as semantically equivalent. If a SET OF value is present, but empty, a presentMatch on the SET OF component SHALL return TRUE and the notional count SHALL be regarded as present and equal to zero. Legg Standards Track [Page 19] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 3.2.3. Summary of Useful Matching Rules The following is a non-exhaustive list of useful matching rules and the ASN.1 types to which they can be applied, taking account of all the extensions described in Section 3.2.1, and the new matching rules defined in Section 3.2.2. +================================+==============================+ | Matching Rule | ASN.1 Type | +================================+==============================+ | bitStringMatch | BIT STRING | +--------------------------------+------------------------------+ | booleanMatch | BOOLEAN | +--------------------------------+------------------------------+ | caseIgnoreMatch | NumericString | | caseIgnoreOrderingMatch | PrintableString | | caseIgnoreSubstringsMatch | VisibleString (ISO646String) | | caseExactMatch | IA5String | | caseExactOrderingMatch | UTF8String | | caseExactSubstringsMatch | BMPString (UCS-2, UNICODE) | | | UniversalString (UCS-4) | | | TeletexString (T61String) | | | VideotexString | | | GraphicString | | | GeneralString | | | any ChoiceOfStrings type | +--------------------------------+------------------------------+ | caseIgnoreIA5Match | IA5String | | caseExactIA5Match | | +--------------------------------+------------------------------+ | distinguishedNameMatch | DistinguishedName | | | RDNSequence | +--------------------------------+------------------------------+ | generalizedTimeMatch | GeneralizedTime | | generalizedTimeOrderingMatch | | +--------------------------------+------------------------------+ | integerMatch | INTEGER | | integerOrderingMatch | | +--------------------------------+------------------------------+ | numericStringMatch | NumericString | | numericStringOrderingMatch | | | numericStringSubstringsMatch | | +--------------------------------+------------------------------+ | objectIdentifierMatch | OBJECT IDENTIFIER | +--------------------------------+------------------------------+ | octetStringMatch | OCTET STRING | | octetStringOrderingMatch | | | octetStringSubstringsMatch | | Legg Standards Track [Page 20] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 +--------------------------------+------------------------------+ | presentMatch | any ASN.1 type | +--------------------------------+------------------------------+ | rdnMatch | RelativeDistinguishedName | +--------------------------------+------------------------------+ | telephoneNumberMatch | PrintableString | | telephoneNumberSubstringsMatch | TelephoneNumber | +--------------------------------+------------------------------+ | uTCTimeMatch | UTCTime | | uTCTimeOrderingMatch | | +--------------------------------+------------------------------+ Note that the allComponentsMatch matching rule defined in Section 6.2 can be used for equality matching of values of the ENUMERATED, NULL, REAL and RELATIVE-OID ASN.1 types, among other things. 4. ComponentFilter The ComponentAssertion allows the value(s) of any one component type in a complex ASN.1 type to be matched, but there is often a desire to match the values of more than one component type. A ComponentFilter is an assertion about the presence, or values of, multiple components within an ASN.1 value. The ComponentFilter assertion, an expression of ComponentAssertions, evaluates to either TRUE, FALSE or Undefined for each tested ASN.1 value. A ComponentFilter is described by the following ASN.1 type (assumed to be defined with "EXPLICIT TAGS" in force): ComponentFilter ::= CHOICE { item [0] ComponentAssertion, and [1] SEQUENCE OF ComponentFilter, or [2] SEQUENCE OF ComponentFilter, not [3] ComponentFilter } Note: despite the use of SEQUENCE OF instead of SET OF for the "and" and "or" alternatives in ComponentFilter, the order of the component filters is not significant. A ComponentFilter that is a ComponentAssertion evaluates to TRUE if the ComponentAssertion is TRUE, evaluates to FALSE if the ComponentAssertion is FALSE, and evaluates to Undefined otherwise. Legg Standards Track [Page 21] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 The "and" of a sequence of component filters evaluates to TRUE if the sequence is empty or if each component filter evaluates to TRUE, evaluates to FALSE if at least one component filter is FALSE, and evaluates to Undefined otherwise. The "or" of a sequence of component filters evaluates to FALSE if the sequence is empty or if each component filter evaluates to FALSE, evaluates to TRUE if at least one component filter is TRUE, and evaluates to Undefined otherwise. The "not" of a component filter evaluates to TRUE if the component filter is FALSE, evaluates to FALSE if the component filter is TRUE, and evaluates to Undefined otherwise. 5. The componentFilterMatch Matching Rule The componentFilterMatch matching rule allows a ComponentFilter to be applied to an attribute value. The result of the matching rule is the result of applying the ComponentFilter to the attribute value. The LDAP-style definitions for componentFilterMatch and its assertion syntax are: ( 1.2.36.79672281.1.13.2 NAME 'componentFilterMatch' SYNTAX 1.2.36.79672281.1.5.2 ) ( 1.2.36.79672281.1.5.2 DESC 'ComponentFilter' ) The LDAP-specific encoding for the ComponentFilter assertion syntax is specified by GSER [9]. As a convenience to implementors, an equivalent ABNF description of the GSER encoding for ComponentFilter is provided here. In the event that there is a discrepancy between this ABNF and the encoding determined by GSER, GSER is to be taken as definitive. The GSER encoding of a ComponentFilter is described by the following equivalent ABNF: ComponentFilter = filter-item / and-filter / or-filter / not-filter filter-item = item-chosen ComponentAssertion and-filter = and-chosen SequenceOfComponentFilter or-filter = or-chosen SequenceOfComponentFilter not-filter = not-chosen ComponentFilter Legg Standards Track [Page 22] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 item-chosen = %x69.74.65.6D.3A ; "item:" and-chosen = %x61.6E.64.3A ; "and:" or-chosen = %x6F.72.3A ; "or:" not-chosen = %x6E.6F.74.3A ; "not:" SequenceOfComponentFilter = "{" [ sp ComponentFilter *( "," sp ComponentFilter) ] sp "}" ComponentAssertion = "{" [ sp component "," ] [ sp useDefaultValues "," ] sp rule "," sp assertion-value sp "}" component = component-label msp StringValue useDefaultValues = use-defaults-label msp BooleanValue rule = rule-label msp ObjectIdentifierValue assertion-value = value-label msp Value component-label = %x63.6F.6D.70.6F.6E.65.6E.74 ; "component" use-defaults-label = %x75.73.65.44.65.66.61.75.6C.74.56.61.6C.75 %x65.73 ; "useDefaultValues" rule-label = %x72.75.6C.65 ; "rule" value-label = %x76.61.6C.75.65 ; "value" sp = *%x20 ; zero, one or more space characters msp = 1*%x20 ; one or more space characters The ABNF for <Value>, <StringValue>, <ObjectIdentifierValue> and <BooleanValue> is defined by GSER [9]. The ABNF descriptions of LDAP-specific encodings for attribute syntaxes typically do not clearly or consistently delineate the component parts of an attribute value. A regular and uniform character string encoding for arbitrary component data types is needed to encode the assertion value in a ComponentAssertion. The <Value> rule from GSER provides a human readable text encoding for a component value of any arbitrary ASN.1 type. The X.500-style definition [10] for componentFilterMatch is: componentFilterMatch MATCHING-RULE ::= { SYNTAX ComponentFilter ID { 1 2 36 79672281 1 13 2 } } A ComponentAssertion can potentially use any matching rule, including componentFilterMatch, so componentFilterMatch may be nested. The component references in a nested componentFilterMatch are relative to Legg Standards Track [Page 23] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 the component corresponding to the containing ComponentAssertion. In Section 7, an example search on the seeAlso attribute shows this usage. 6. Equality Matching of Complex Components It is possible to test if an attribute value of a complex ASN.1 syntax is the same as some purported (i.e., assertion) value by using a complicated ComponentFilter that tests if corresponding components are the same. However, it would be more convenient to be able to present a whole assertion value to a matching rule that could do the component-wise comparison of an attribute value with the assertion value for any arbitrary attribute syntax. Similarly, the ability to do a straightforward equality comparison of a component value that is itself of a complex ASN.1 type would also be convenient. It would be difficult to define a single matching rule that simultaneously satisfies all notions of what the equality matching semantics should be. For example, in some instances a case sensitive comparison of string components may be preferable to a case insensitive comparison. Therefore a basic equality matching rule, allComponentsMatch, is defined in Section 6.2, and the means to derive new matching rules from it with slightly different equality matching semantics are described in Section 6.3. The directoryComponentsMatch defined in Section 6.4 is a derivation of allComponentsMatch that suits typical uses of the directory. Other specifications are free to derive new rules from allComponentsMatch or directoryComponentsMatch, that suit their usage of the directory. The allComponentsMatch rule, the directoryComponentsMatch rule and any matching rules derived from them are collectively called component equality matching rules. 6.1. The OpenAssertionType Syntax The component equality matching rules have a variable assertion syntax. In X.500 this is indicated by omitting the optional SYNTAX field in the MATCHING-RULE information object. The assertion syntax then defaults to the target attribute's syntax in actual usage, unless the description of the matching rule says otherwise. The SYNTAX field in the LDAP-specific encoding of a MatchingRuleDescription is mandatory, so the OpenAssertionType syntax is defined to fill the same role. That is, the OpenAssertionType syntax is semantically equivalent to an omitted SYNTAX field in an X.500 MATCHING-RULE information object. OpenAssertionType MUST NOT be used as the attribute syntax in an attribute type definition. Legg Standards Track [Page 24] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 Unless explicitly varied by the description of a particular matching rule, if an OpenAssertionType assertion value appears in a ComponentAssertion its LDAP-specific encoding is described by the <Value> rule in GSER [9], otherwise its LDAP-specific encoding is the encoding defined for the syntax of the attribute type to which the matching rule with the OpenAssertionType assertion syntax is applied. The LDAP definition for the OpenAssertionType syntax is: ( 1.2.36.79672281.1.5.3 DESC 'OpenAssertionType' ) 6.2. The allComponentsMatch Matching Rule The LDAP-style definition for allComponentsMatch is: ( 1.2.36.79672281.1.13.6 NAME 'allComponentsMatch' SYNTAX 1.2.36.79672281.1.5.3 ) The X.500-style definition for allComponentsMatch is: allComponentsMatch MATCHING-RULE ::= { ID { 1 2 36 79672281 1 13 6 } } When allComponentsMatch is used in a ComponentAssertion the assertion syntax is the same as the ASN.1 type of the identified component. Otherwise, the assertion syntax of allComponentsMatch is the same as the attribute syntax of the attribute to which the matching rule is applied. Broadly speaking, this matching rule evaluates to true if and only if corresponding components of the assertion value and the attribute or component value are the same. In detail, equality is determined by the following cases applied recursively. a) Two values of a SET or SEQUENCE type are the same if and only if, for each component type, the corresponding component values are either, 1) both absent, 2) both present and the same, or 3) absent or the same as the DEFAULT value for the component, if a DEFAULT value is defined. Legg Standards Track [Page 25] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 Values of an EMBEDDED PDV, EXTERNAL, unrestricted CHARACTER STRING, or INSTANCE OF type are compared according to their respective associated SEQUENCE type (see Section 3.1.2). b) Two values of a SEQUENCE OF type are the same if and only if, the values have the same number of (possibly duplicated) instances and corresponding instances are the same. c) Two values of a SET OF type are the same if and only if, the values have the same number of instances and each distinct instance occurs in both values the same number of times, i.e., both values have the same instances, including duplicates, but in any order. d) Two values of a CHOICE type are the same if and only if, both values are of the same chosen alternative and the component values are the same. e) Two BIT STRING values are the same if and only if the values have the same number of bits and corresponding bits are the same. If the BIT STRING type is defined with a named bit list then trailing zero bits in the values are treated as absent for the purposes of this comparison. f) Two BOOLEAN values are the same if and only if both are TRUE or both are FALSE. g) Two values of a string type are the same if and only if the values have the same number of characters and corresponding characters are the same. Letter case is significant. For the purposes of allComponentsMatch, the string types are NumericString, PrintableString, TeletexString (T61String), VideotexString, IA5String, GraphicString, VisibleString (ISO646String), GeneralString, UniversalString, BMPString, UTF8String, GeneralizedTime, UTCTime and ObjectDescriptor. h) Two INTEGER values are the same if and only if the integers are equal. i) Two ENUMERATED values are the same if and only if the enumeration item identifiers are the same (equivalently, if the integer values associated with the identifiers are equal). j) Two NULL values are always the same, unconditionally. k) Two OBJECT IDENTIFIER values are the same if and only if the values have the same number of arcs and corresponding arcs are the same. Legg Standards Track [Page 26] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 l) Two OCTET STRING values are the same if and only if the values have the same number of octets and corresponding octets are the same. m) Two REAL values are the same if and only if they are both the same special value, or neither is a special value and they have the same base and represent the same real number. The special values for REAL are zero, PLUS-INFINITY and MINUS-INFINITY. n) Two RELATIVE-OID values are the same if and only if the values have the same number of arcs and corresponding arcs are the same. The respective starting nodes for the RELATIVE-OID values are disregarded in the comparison, i.e., they are assumed to be the same. o) Two values of an open type are the same if and only if both are of the same ASN.1 type and are the same according to that type. If the actual ASN.1 type of the values is unknown then the allComponentsMatch rule evaluates to Undefined. Tags and constraints, being part of the type definition and not part of the abstract values, are ignored for matching purposes. The allComponentsMatch rule may be used as the defined equality matching rule for an attribute. 6.3. Deriving Component Equality Matching Rules A new component equality matching rule with more refined matching semantics may be derived from allComponentsMatch, or any other component equality matching rule, using the convention described in this section. The matching behaviour of a derived component equality matching rule is specified by nominating, for each of one or more identified components, a commutative equality matching rule that will be used to match values of that component. This overrides the matching that would otherwise occur for values of that component using the base rule for the derivation. These overrides can be conveniently represented as rows in a table of the following form. Component | Matching Rule ============+=============== | | Legg Standards Track [Page 27] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 Usually, all component values of a particular ASN.1 type are to be matched the same way. An ASN.1 type reference (e.g., DistinguishedName) or an ASN.1 built-in type name (e.g., INTEGER) in the Component column of the table specifies that the nominated equality matching rule is to be applied to all values of the named type, regardless of context. An ASN.1 type reference with a component reference appended (separated by a ".") specifies that the nominated matching rule applies only to the identified components of values of the named type. Other component values that happen to be of the same ASN.1 type are not selected. Additional type substitutions as described in Section 3.2 are assumed to be performed to align the component type with the matching rule assertion syntax. Conceptually, the rows in a table for the base rule are appended to the rows in the table for a derived rule for the purpose of deciding the matching semantics of the derived rule. Notionally, allComponentsMatch has an empty table. A row specifying values of an outer containing type (e.g., DistinguishedName) takes precedence over a row specifying values of an inner component type (e.g., RelativeDistinguishedName), regardless of their order in the table. Specifying a row for component values of an inner type is only useful if a value of the type can also appear on its own, or as a component of values of a different outer type. For example, if there is a row for DistinguishedName then a row for RelativeDistinguishedName can only ever apply to RelativeDistinguishedName component values that are not part of a DistinguishedName. A row for values of an outer type in the table for the base rule takes precedence over a row for values of an inner type in the table for the derived rule. Where more than one row applies to a particular component value the earlier row takes precedence over the later row. Thus rows in the table for the derived rule take precedence over any rows for the same component in the table for the base rule. 6.4. The directoryComponentsMatch Matching Rule The directoryComponentsMatch matching rule is derived from the allComponentsMatch matching rule. Legg Standards Track [Page 28] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 The LDAP-style definition for directoryComponentsMatch is: ( 1.2.36.79672281.1.13.7 NAME 'directoryComponentsMatch' SYNTAX 1.2.36.79672281.1.5.3 ) The X.500-style definition for directoryComponentsMatch is: directoryComponentsMatch MATCHING-RULE ::= { ID { 1 2 36 79672281 1 13 7 } } The matching semantics of directoryComponentsMatch are described by the following table, using the convention described in Section 6.3. ASN.1 Type | Matching Rule =========================================+======================== RDNSequence | distinguishedNameMatch RelativeDistinguishedName | rdnMatch TelephoneNumber | telephoneNumberMatch FacsimileTelephoneNumber.telephoneNumber | telephoneNumberMatch NumericString | numericStringMatch GeneralizedTime | generalizedTimeMatch UTCTime | uTCTimeMatch DirectoryString{} | caseIgnoreMatch BMPString | caseIgnoreMatch GeneralString | caseIgnoreMatch GraphicString | caseIgnoreMatch IA5String | caseIgnoreMatch PrintableString | caseIgnoreMatch TeletexString | caseIgnoreMatch UniversalString | caseIgnoreMatch UTF8String | caseIgnoreMatch VideotexString | caseIgnoreMatch VisibleString | caseIgnoreMatch Notes: 1) The DistinguishedName type is defined by assignment to be the same as the RDNSequence type. Some types (e.g., Name and LocalName) directly reference RDNSequence rather than DistinguishedName. Specifying RDNSequence captures all these DN-like types. 2) A RelativeDistinguishedName value is only matched by rdnMatch if it is not part of an RDNSequence value. 3) The telephone number component of the FacsimileTelephoneNumber ASN.1 type [12] is defined as a constrained PrintableString. PrintableString component values that are part of a FacsimileTelephoneNumber value can be identified separately from Legg Standards Track [Page 29] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 other components of PrintableString type by the specifier FacsimileTelephoneNumber.telephoneNumber, so that telephoneNumberMatch can be selectively applied. The fourth edition of X.520 defines the telephoneNumber component of FacsimileTelephoneNumber to be of the type TelephoneNumber, making the row for FacsimileTelephoneNumber.telephoneNumber components redundant. The directoryComponentsMatch rule may be used as the defined equality matching rule for an attribute. 7. Component Matching Examples This section contains examples of search filters using the componentFilterMatch matching rule. The filters are described using the string representation of LDAP search filters [18]. Note that this representation requires asterisks to be escaped in assertion values (in these examples the assertion values are all <ComponentAssertion> encodings). The asterisks have not been escaped in these examples for the sake of clarity, and to avoid confusing the protocol representation of LDAP search filter assertion values, where such escaping does not apply. Line breaks and indenting have been added only as an aid to readability. The example search filters using componentFilterMatch are all single extensible match filter items, though there is no reason why componentFilterMatch can't be used in more complicated search filters. The first examples describe searches over the objectClasses schema operational attribute, which has an attribute syntax described by the ASN.1 type ObjectClassDescription [10], and holds the definitions of the object classes known to a directory server. The definition of ObjectClassDescription is as follows: ObjectClassDescription ::= SEQUENCE { identifier OBJECT-CLASS.&id, name SET OF DirectoryString {ub-schema} OPTIONAL, description DirectoryString {ub-schema} OPTIONAL, obsolete BOOLEAN DEFAULT FALSE, information [0] ObjectClassInformation } ObjectClassInformation ::= SEQUENCE { subclassOf SET OF OBJECT-CLASS.&id OPTIONAL, kind ObjectClassKind DEFAULT structural, mandatories [3] SET OF ATTRIBUTE.&id OPTIONAL, optionals [4] SET OF ATTRIBUTE.&id OPTIONAL } Legg Standards Track [Page 30] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 ObjectClassKind ::= ENUMERATED { abstract (0), structural (1), auxiliary (2) } OBJECT-CLASS.&id and ATTRIBUTE.&id are equivalent to the OBJECT IDENTIFIER ASN.1 type. A value of OBJECT-CLASS.&id is an OBJECT IDENTIFIER for an object class. A value of ATTRIBUTE.&id is an OBJECT IDENTIFIER for an attribute type. The following search filter finds the object class definition for the object class identified by the OBJECT IDENTIFIER 2.5.6.18: (objectClasses:componentFilterMatch:= item:{ component "identifier", rule objectIdentifierMatch, value 2.5.6.18 }) A match on the "identifier" component of objectClasses values is equivalent to the objectIdentifierFirstComponentMatch matching rule applied to attribute values of the objectClasses attribute type. The componentFilterMatch matching rule subsumes the functionality of the objectIdentifierFirstComponentMatch, integerFirstComponentMatch and directoryStringFirstComponentMatch matching rules. The following search filter finds the object class definition for the object class called foobar: (objectClasses:componentFilterMatch:= item:{ component "name.*", rule caseIgnoreMatch, value "foobar" }) An object class definition can have multiple names and the above filter will match an objectClasses value if any one of the names is "foobar". The component reference "name.0" identifies the notional count of the number of names in an object class definition. The following search filter finds object class definitions with exactly one name: (objectClasses:componentFilterMatch:= item:{ component "name.0", rule integerMatch, value 1 }) The "description" component of an ObjectClassDescription is defined to be an OPTIONAL DirectoryString. The following search filter finds object class definitions that have descriptions, regardless of the contents of the description string: Legg Standards Track [Page 31] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 (objectClasses:componentFilterMatch:= item:{ component "description", rule presentMatch, value NULL }) The presentMatch returns TRUE if the description component is present and FALSE otherwise. The following search filter finds object class definitions that don't have descriptions: (objectClasses:componentFilterMatch:= not:item:{ component "description", rule presentMatch, value NULL }) The following search filter finds object class definitions with the word "bogus" in the description: (objectClasses:componentFilterMatch:= item:{ component "description", rule caseIgnoreSubstringsMatch, value { any:"bogus" } }) The assertion value is of the SubstringAssertion syntax, i.e., SubstringAssertion ::= SEQUENCE OF CHOICE { initial [0] DirectoryString {ub-match}, any [1] DirectoryString {ub-match}, final [2] DirectoryString {ub-match} } The "obsolete" component of an ObjectClassDescription is defined to be DEFAULT FALSE. An object class is obsolete if the "obsolete" component is present and set to TRUE. The following search filter finds all obsolete object classes: (objectClasses:componentFilterMatch:= item:{ component "obsolete", rule booleanMatch, value TRUE }) An object class is not obsolete if the "obsolete" component is not present, in which case it defaults to FALSE, or is present but is explicitly set to FALSE. The following search filter finds all non- obsolete object classes: (objectClasses:componentFilterMatch:= item:{ component "obsolete", rule booleanMatch, value FALSE }) The useDefaultValues flag in the ComponentAssertion defaults to TRUE so the componentFilterMatch rule treats an absent "obsolete" component as being present and set to FALSE. The following search Legg Standards Track [Page 32] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 filter finds only object class definitions where the "obsolete" component has been explicitly set to FALSE, rather than implicitly defaulting to FALSE: (objectClasses:componentFilterMatch:= item:{ component "obsolete", useDefaultValues FALSE, rule booleanMatch, value FALSE }) With the useDefaultValues flag set to FALSE, if the "obsolete" component is absent the component reference identifies no component value and the matching rule will return FALSE. The matching rule can only return TRUE if the component is present and set to FALSE. The "information.kind" component of the ObjectClassDescription is an ENUMERATED type. The allComponentsMatch matching rule can be used to match values of an ENUMERATED type. The following search filter finds object class definitions for auxiliary object classes: (objectClasses:componentFilterMatch:= item:{ component "information.kind", rule allComponentsMatch, value auxiliary }) The following search filter finds auxiliary object classes with commonName (cn or 2.5.4.3) as a mandatory attribute: (objectClasses:componentFilterMatch:=and:{ item:{ component "information.kind", rule allComponentsMatch, value auxiliary }, item:{ component "information.mandatories.*", rule objectIdentifierMatch, value cn } }) The following search filter finds auxiliary object classes with commonName as a mandatory or optional attribute: (objectClasses:componentFilterMatch:=and:{ item:{ component "information.kind", rule allComponentsMatch, value auxiliary }, or:{ item:{ component "information.mandatories.*", rule objectIdentifierMatch, value cn }, item:{ component "information.optionals.*", rule objectIdentifierMatch, value cn } } }) Extra care is required when matching optional SEQUENCE OF or SET OF components because of the distinction between an absent list of instances and a present, but empty, list of instances. The following search filter finds object class definitions with less than three Legg Standards Track [Page 33] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 names, including object class definitions with a present but empty list of names, but does not find object class definitions with an absent list of names: (objectClasses:componentFilterMatch:= item:{ component "name.0", rule integerOrderingMatch, value 3 }) If the "name" component is absent the "name.0" component is also considered to be absent and the ComponentAssertion evaluates to FALSE. If the "name" component is present, but empty, the "name.0" component is also present and equal to zero, so the ComponentAssertion evaluates to TRUE. To also find the object class definitions with an absent list of names the following search filter would be used: (objectClasses:componentFilterMatch:=or:{ not:item:{ component "name", rule presentMatch, value NULL }, item:{ component "name.0", rule integerOrderingMatch, value 3 } }) Distinguished names embedded in other syntaxes can be matched with a componentFilterMatch. The uniqueMember attribute type has an attribute syntax described by the ASN.1 type NameAndOptionalUID. NameAndOptionalUID ::= SEQUENCE { dn DistinguishedName, uid UniqueIdentifier OPTIONAL } The following search filter finds values of the uniqueMember attribute containing the author's DN: (uniqueMember:componentFilterMatch:= item:{ component "dn", rule distinguishedNameMatch, value "cn=Steven Legg,o=Adacel,c=AU" }) The DistinguishedName and RelativeDistinguishedName ASN.1 types are also complex ASN.1 types so the component matching rules can be applied to their inner components. DistinguishedName ::= RDNSequence RDNSequence ::= SEQUENCE OF RelativeDistinguishedName RelativeDistinguishedName ::= SET SIZE (1..MAX) OF AttributeTypeAndValue Legg Standards Track [Page 34] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 AttributeTypeAndValue ::= SEQUENCE { type AttributeType ({SupportedAttributes}), value AttributeValue ({SupportedAttributes}{@type}) } AttributeType ::= ATTRIBUTE.&id AttributeValue ::= ATTRIBUTE.&Type ATTRIBUTE.&Type is an open type. A value of ATTRIBUTE.&Type is constrained by the type component of AttributeTypeAndValue to be of the attribute syntax of the nominated attribute type. Note: the fourth edition of X.500 extends and renames the AttributeTypeAndValue SEQUENCE type. The seeAlso attribute has the DistinguishedName syntax. The following search filter finds seeAlso attribute values containing the RDN, "o=Adacel", anywhere in the DN: (seeAlso:componentFilterMatch:= item:{ component "*", rule rdnMatch, value "o=Adacel" }) The following search filter finds all seeAlso attribute values with "cn=Steven Legg" as the RDN of the named entry (i.e., the "first" RDN in an LDAPDN or the "last" RDN in an X.500 DN): (seeAlso:componentFilterMatch:= item:{ component "-1", rule rdnMatch, value "cn=Steven Legg" }) The following search filter finds all seeAlso attribute values naming entries in the DIT subtree of "o=Adacel,c=AU": (seeAlso:componentFilterMatch:=and:{ item:{ component "1", rule rdnMatch, value "c=AU" }, item:{ component "2", rule rdnMatch, value "o=Adacel" } }) The following search filter finds all seeAlso attribute values containing the naming attribute types commonName (cn) and telephoneNumber in the same RDN: (seeAlso:componentFilterMatch:= item:{ component "*", rule componentFilterMatch, value and:{ item:{ component "*.type", rule objectIdentifierMatch, value cn }, item:{ component "*.type", rule objectIdentifierMatch, value telephoneNumber } } }) Legg Standards Track [Page 35] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 The following search filter would find all seeAlso attribute values containing the attribute types commonName and telephoneNumber, but not necessarily in the same RDN: (seeAlso:componentFilterMatch:=and:{ item:{ component "*.*.type", rule objectIdentifierMatch, value cn }, item:{ component "*.*.type", rule objectIdentifierMatch, value telephoneNumber } }) The following search filter finds all seeAlso attribute values containing the word "Adacel" in any organizationalUnitName (ou) attribute value in any AttributeTypeAndValue of any RDN: (seeAlso:componentFilterMatch:= item:{ component "*.*.value.(2.5.4.11)", rule caseIgnoreSubstringsMatch, value { any:"Adacel" } }) The component reference "*.*.value" identifies an open type, in this case an attribute value. In a particular AttributeTypeAndValue, if the attribute type is not organizationalUnitName then the ComponentAssertion evaluates to FALSE. Otherwise the substring assertion is evaluated against the attribute value. Absent component references in ComponentAssertions can be exploited to avoid false positive matches on multi-valued attributes. For example, suppose there is a multi-valued attribute named productCodes, defined to have the Integer syntax (1.3.6.1.4.1.1466.115.121.1.27). Consider the following search filter: (&(!(productCodes:integerOrderingMatch:=3)) (productCodes:integerOrderingMatch:=8)) An entry whose productCodes attribute contains only the values 1 and 10 will match the above filter. The first subfilter is satisfied by the value 10 (10 is not less than 3), and the second subfilter is satisfied by the value 1 (1 is less than 8). The following search filter can be used instead to only match entries that have a productCodes value in the range 3 to 7, because the ComponentFilter is evaluated against each productCodes value in isolation: (productCodes:componentFilterMatch:= and:{ not:item:{ rule integerOrderingMatch, value 3 }, item:{ rule integerOrderingMatch, value 8 } }) Legg Standards Track [Page 36] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 An entry whose productCodes attribute contains only the values 1 and 10 will not match the above filter. 8. Security Considerations The component matching rules described in this document allow for a compact specification of matching capabilities that could otherwise have been defined by a plethora of specific matching rules, i.e., despite their expressiveness and flexibility the component matching rules do not behave in a way uncharacteristic of other matching rules, so the security issues for component matching rules are no different than for any other matching rule. However, because the component matching rules are applicable to any attribute syntax, support for them in a directory server may allow searching of attributes that were previously unsearchable by virtue of there not being a suitable matching rule. Such attribute types ought to be properly protected with appropriate access controls. A generic, interoperable access control mechanism has not yet been developed, however, and implementors should be aware of the interaction of that lack with the increased risk of exposure described above. 9. Acknowledgements The author would like to thank Tom Gindin for private email discussions that clarified and refined the ideas presented in this document. 10. IANA Considerations The Internet Assigned Numbers Authority (IANA) has updated the LDAP descriptors registry [8] as indicated by the following templates: Subject: Request for LDAP Descriptor Registration Descriptor (short name): componentFilterMatch Object Identifier: 1.2.36.79672281.1.13.2 Person & email address to contact for further information: Steven Legg <steven.legg@adacel.com.au> Usage: other (matching rule) Specification: RFC 3687 Author/Change Controller: IESG Legg Standards Track [Page 37] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 Subject: Request for LDAP Descriptor Registration Descriptor (short name): rdnMatch Object Identifier: 1.2.36.79672281.1.13.3 Person & email address to contact for further information: Steven Legg <steven.legg@adacel.com.au> Usage: other (matching rule) Specification: RFC 3687 Author/Change Controller: IESG Subject: Request for LDAP Descriptor Registration Descriptor (short name): presentMatch Object Identifier: 1.2.36.79672281.1.13.5 Person & email address to contact for further information: Steven Legg <steven.legg@adacel.com.au> Usage: other (matching rule) Specification: RFC 3687 Author/Change Controller: IESG Subject: Request for LDAP Descriptor Registration Descriptor (short name): allComponentsMatch Object Identifier: 1.2.36.79672281.1.13.6 Person & email address to contact for further information: Steven Legg <steven.legg@adacel.com.au> Usage: other (matching rule) Specification: RFC 3687 Author/Change Controller: IESG Subject: Request for LDAP Descriptor Registration Descriptor (short name): directoryComponentsMatch Object Identifier: 1.2.36.79672281.1.13.7 Person & email address to contact for further information: Steven Legg <steven.legg@adacel.com.au> Usage: other (matching rule) Specification: RFC 3687 Author/Change Controller: IESG The object identifiers have been assigned for use in this specification by Adacel Technologies, under an arc assigned to Adacel by Standards Australia. 11. References 11.1. Normative References [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. Legg Standards Track [Page 38] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 [2] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, November 1997. [3] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [4] Wahl, M., Coulbeck, A., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (v3): Attribute Syntax Definitions", RFC 2252, December 1997. [5] Wahl, M., Kille S. and T. Howes. "Lightweight Directory Access Protocol (v3): UTF-8 String Representation of Distinguished Names", RFC 2253, December 1997. [6] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003. [7] Hodges, J. and R. Morgan, "Lightweight Directory Access Protocol (v3): Technical Specification", RFC 3377, September 2002. [8] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 3383, September 2002. [9] Legg, S., "Generic String Encoding Rules (GSER) for ASN.1 Types", RFC 3641, October 2003. [10] ITU-T Recommendation X.501 (1993) | ISO/IEC 9594-2:1994, Information Technology - Open Systems Interconnection - The Directory: Models [11] ITU-T Recommendation X.509 (1997) | ISO/IEC 9594-8:1998, Information Technology - Open Systems Interconnection - The Directory: Authentication Framework [12] ITU-T Recommendation X.520 (1993) | ISO/IEC 9594-6:1994, Information technology - Open Systems Interconnection - The Directory: Selected attribute types [13] ITU-T Recommendation X.680 (07/02) | ISO/IEC 8824-1:2002, Information technology - Abstract Syntax Notation One (ASN.1): Specification of basic notation [14] ITU-T Recommendation X.681 (07/02) | ISO/IEC 8824-2:2002, Information technology - Abstract Syntax Notation One (ASN.1): Information object specification Legg Standards Track [Page 39] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 [15] ITU-T Recommendation X.682 (07/02) | ISO/IEC 8824-3:2002, Information technology - Abstract Syntax Notation One (ASN.1): Constraint specification [16] ITU-T Recommendation X.683 (07/02) | ISO/IEC 8824-4:2002, Information technology - Abstract Syntax Notation One (ASN.1): Parameterization of ASN.1 specifications [17] ITU-T Recommendation X.690 (07/02) | ISO/IEC 8825-1, Information technology - ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER) 12.2. Informative References [18] Howes, T., "The String Representation of LDAP Search Filters", RFC 2254, December 1997. [19] ITU-T Recommendation X.500 (1993) | ISO/IEC 9594-1:1994, Information Technology - Open Systems Interconnection - The Directory: Overview of concepts, models and services 12. 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. Legg Standards Track [Page 40] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 13. Author's Address Steven Legg Adacel Technologies Ltd. 250 Bay Street Brighton, Victoria 3186 AUSTRALIA Phone: +61 3 8530 7710 Fax: +61 3 8530 7888 EMail: steven.legg@adacel.com.au Legg Standards Track [Page 41] RFC 3687 LDAP and X.500 Component Matching Rules February 2004 14. Full Copyright Statement 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 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 assignees. 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. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Legg Standards Track [Page 42] PK )�c\|�YL L ( doc/alt-openldap11-devel/rfc/rfc3088.txtnu �[��� Network Working Group K. Zeilenga Request for Comments: 3088 OpenLDAP Foundation Category: Experimental April 2001 OpenLDAP Root Service An experimental LDAP referral service Status of this Memo This memo defines an Experimental Protocol for the Internet community. It does not specify an Internet standard of any kind. Discussion and suggestions for improvement are requested. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2001). All Rights Reserved. Abstract The OpenLDAP Project is operating an experimental LDAP (Lightweight Directory Access Protocol) referral service known as the "OpenLDAP Root Service". The automated system generates referrals based upon service location information published in DNS SRV RRs (Domain Name System location of services resource records). This document describes this service. 1. Background LDAP [RFC2251] directories use a hierarchical naming scheme inherited from X.500 [X500]. Traditionally, X.500 deployments have used a geo-political naming scheme (e.g., CN=Jane Doe,OU=Engineering,O=Example,ST=CA,C=US). However, registration infrastructure and location services in many portions of the naming hierarchical are inadequate or nonexistent. The construction of a global directory requires a robust registration infrastructure and location service. Use of Internet domain-based naming [RFC2247] (e.g., UID=jdoe,DC=eng,DC=example,DC=net) allows LDAP directory services to leverage the existing DNS [RFC1034] registration infrastructure and DNS SRV [RFC2782] resource records can be used to locate services [LOCATE]. Zeilenga Experimental [Page 1] RFC 3088 OpenLDAP Root Service April 2001 1.1. The Glue Most existing LDAP implementations do not support location of directory services using DNS SRV resource records. However, most servers support generation of referrals to "superior" server(s). This service provides a "root" LDAP service which servers may use as their superior referral service. Client may also use the service directly to locate services associated with an arbitrary Distinguished Name [RFC2253] within the domain based hierarchy. Notice: The mechanisms used by service are experimental. The descriptions provided by this document are not definitive. Definitive mechanisms shall be published in a Standard Track document(s). 2. Generating Referrals based upon DNS SRV RRs This service returns referrals generated from DNS SRV resource records [RFC2782]. 2.1. DN to Domain Name Mapping The service maps a DN [RFC2253] to a fully qualified domain name using the following algorithm: domain = null; foreach RDN left-to-right // [1] { if not multi-valued RDN and RDN.type == domainComponent { if ( domain == null || domain == "." ) { // start domain = ""; } else { // append separator domain .= "."; } if ( RDN.value == "." ) { // root domain = "."; } else Zeilenga Experimental [Page 2] RFC 3088 OpenLDAP Root Service April 2001 { // append domainComponent domain .= RDN.value; } continue; } domain = null; } Examples: Distinguished Name Domain ----------------------------- ------------ DC=example,DC=net example.net UID=jdoe,DC=example,DC=net example.net DC=. . [2] DC=example,DC=net,DC=. . [3] DC=example,DC=.,DC=net net [4] DC=example.net example.net [5] CN=Jane Doe,O=example,C=US null UID=jdoe,DC=example,C=US null DC=example,O=example,DC=net net DC=example+O=example,DC=net net DC=example,C=US+DC=net null Notes: 0) A later incarnation will use a Standard Track mechanism. 1) A later incarnation of this service may use a right-to-left algorithm. 2) RFC 2247 does not state how one can map the domain representing the root of the domain tree to a DN. We suggest the root of the domain tree be mapped to "DC=." and that this be reversable. 3) RFC 2247 states that domain "example.net" should be mapped to the DN "DC=example,DC=net", not to "DC=example,DC=net,DC=.". As it is not our intent to introduce or support an alternative domain to DN mapping, the algorithm ignores domainComponents to the left of "DC=.". 4) RFC 2247 states that domain "example.net" should be mapped to the DN "DC=example,DC=net", not to "DC=example,DC=.,DC=net". As it is not our intent to introduce or support an alternative domain to DN mapping, the algorithm ignores domainComponents to the left of "DC=." and "DC=." itself if further domainComponents are found to the right. Zeilenga Experimental [Page 3] RFC 3088 OpenLDAP Root Service April 2001 5) RFC 2247 states that value of an DC attribute type is a domain component. It should not contain multiple domain components. A later incarnation of this service may map this domain to null or be coded to return invalid DN error. If the domain is null or ".", the service aborts further processing and returns noSuchObject. Later incarnation of this service may abort processing if the resulting domain is a top-level domain. 2.2. Locating LDAP services The root service locates services associated with a given fully qualified domain name by querying the Domain Name System for LDAP SRV resource records. For the domain example.net, the service would do a issue a SRV query for the domain "_ldap._tcp.example.net". A successful query will return one or more resource records of the form: _ldap._tcp.example.net. IN SRV 0 0 389 ldap.example.net. If no LDAP SRV resource records are returned or any DNS error occurs, the service aborts further processing and returns noSuchObject. Later incarnations of this service will better handle transient errors. 2.3. Constructing an LDAP Referrals For each DNS SRV resource record returned for the domain, a LDAP URL [RFC2255] is constructed. For the above resource record, the URL would be: ldap://ldap.example.net:389/ These URLs are then returned in the referral. The URLs are currently returned in resolver order. That is, the server itself does not make use of priority or weight information in the SRV resource records. A later incarnation of this service may. 3. Protocol Operations This section describes how the service performs basic LDAP operations. The service supports operations extended through certain controls as described in a later section. Zeilenga Experimental [Page 4] RFC 3088 OpenLDAP Root Service April 2001 3.1. Basic Operations Basic (add, compare, delete, modify, rename, search) operations return a referral result if the target (or base) DN can be mapped to a set of LDAP URLs as described above. Otherwise a noSuchObject response or other appropriate response is returned. 3.2. Bind Operation The service accepts "anonymous" bind specifying version 2 or version 3 of the protocol. All other bind requests will return a non- successful resultCode. In particular, clients which submit clear text credentials will be sent an unwillingToPerform resultCode with a cautionary text regarding providing passwords to strangers. As this service is read-only, LDAPv3 authentication [RFC2829] is not supported. 3.3. Unbind Operations Upon receipt of an unbind request, the server abandons all outstanding requests made by client and disconnects. 3.4. Extended Operations The service currently does recognize any extended operation. Later incarnations of the service may support Start TLS [RFC2830] and other operations. 3.5. Update Operations A later incarnation of this service may return unwillingToPerform for all update operations as this is an unauthenticated service. 4. Controls The service supports the ManageDSAit control. Unsupported controls are serviced per RFC 2251. 4.1. ManageDSAit Control The server recognizes and honors the ManageDSAit control [NAMEDREF] provided with operations. If DNS location information is available for the base DN itself, the service will return unwillingToPerform for non-search operations. For search operations, an entry will be returned if within scope and matches the provided filter. For example: Zeilenga Experimental [Page 5] RFC 3088 OpenLDAP Root Service April 2001 c: searchRequest { base="DC=example,DC=net" scope=base filter=(objectClass=*) ManageDSAit } s: searchEntry { dn: DC=example,DC=net objectClass: referral objectClass: extensibleObject dc: example ref: ldap://ldap.example.net:389/ associatedDomain: example.net } s: searchResult { success } If DNS location information is available for the DC portion of a subordinate entry, the service will return noSuchObject with the matchedDN set to the DC portion of the base for search and update operations. c: searchRequest { base="CN=subordinate,DC=example,DC=net" scope=base filter=(objectClass=*) ManageDSAit } s: searchResult { noSuchObject matchedDN="DC=example,DC=net" } 5. Using the Service Servers may be configured to refer superior requests to <ldap://root.openldap.org:389>. Though clients may use the service directly, this is not encouraged. Clients should use a local service and only use this service when referred to it. The service supports LDAPv3 and LDAPv2+ [LDAPv2+] clients over TCP/IPv4. Future incarnations of this service may support TCP/IPv6 or other transport/internet protocols. Zeilenga Experimental [Page 6] RFC 3088 OpenLDAP Root Service April 2001 6. Lessons Learned 6.1. Scaling / Reliability This service currently runs on a single host. This host and associated network resources are not yet exhausted. If they do become exhausted, we believe we can easily scale to meet the demand through common distributed load balancing technics. The service can also easily be duplicated locally. 6.2. Protocol interoperability This service has able avoided known interoperability issues in supporting variants of LDAP. 6.2.1. LDAPv3 The server implements all features of LDAPv3 [RFC2251] necessary to provide the service. 6.2.2. LDAPv2 LDAPv2 [RFC1777] does not support the return of referrals and hence may not be referred to this service. Though a LDAPv2 client could connect and issue requests to this service, the client would treat any referral returned to it as an unknown error. 6.2.3. LDAPv2+ LDAPv2+ [LDAPv2+] provides a number of extensions to LDAPv2, including referrals. LDAPv2+, like LDAPv3, does not require a bind operation before issuing of other operations. As the referral representation differ between LDAPv2+ and LDAPv3, the service returns LDAPv3 referrals in this case. However, as commonly deployed LDAPv2+ clients issue bind requests (for compatibility with LDAPv2 servers), this has not generated any interoperability issues (yet). A future incarnation of this service may drop support for LDAPv2+ (and LDAPv2). 6.2.4. CLDAP CLDAP [RFC1798] does not support the return of referrals and hence is not supported. Zeilenga Experimental [Page 7] RFC 3088 OpenLDAP Root Service April 2001 7. Security Considerations This service provides information to "anonymous" clients. This information is derived from the public directories, namely the Domain Name System. The use of authentication would require clients to disclose information to the service. This would be an unnecessary invasion of privacy. The lack of encryption allows eavesdropping upon client requests and responses. A later incarnation of this service may support encryption (such as via Start TLS [RFC2830]). Information integrity protection is not provided by the service. The service is subject to varies forms of DNS spoofing and attacks. LDAP session or operation integrity would provide false sense of security concerning the integrity of DNS information. A later incarnation of this service may support DNSSEC and provide integrity protection (via SASL, TLS, or IPSEC). The service is subject to a variety of denial of service attacks. The service is capable of blocking access by a number of factors. This capability have yet to be used and likely would be ineffective in preventing sophisticated attacks. Later incarnations of this service will likely need better protection from such attacks. 8. Conclusions DNS is good glue. By leveraging of the Domain Name System, global LDAP directories may be built without requiring a protocol specific registration infrastructures. In addition, use of DNS service location allows global directories to be built "ad hoc". That is, anyone with a domain name can participate. There is no requirement that the superior domain participate. 9. Additional Information Additional information about the OpenLDAP Project and the OpenLDAP Root Service can be found at <http://www.openldap.org/>. Zeilenga Experimental [Page 8] RFC 3088 OpenLDAP Root Service April 2001 10. Author's Address Kurt Zeilenga OpenLDAP Foundation EMail: kurt@openldap.org 11. Acknowledgments Internet hosting for this experiment is provided by the Internet Software Consortium <http://www.isc.org/>. Computing resources were provided by Net Boolean Incorporated <http://www.boolean.net/>. This experiment would not have been possible without the contributions of numerous volunteers of the open source community. Mechanisms described in this document are based upon those introduced in [RFC2247] and [LOCATE]. References [RFC1034] Mockapetris, P., "Domain Names - Concepts and Facilities", STD 13, RFC 1034, November 1987. [RFC1777] Yeong, W., Howes, T. and S. Kille, "Lightweight Directory Access Protocol", RFC 1777, March 1995. [RFC1798] Young, A., "Connection-less Lightweight Directory Access Protocol", RFC 1798, June 1995. [RFC2119] Bradner, S., "Key Words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2247] Kille, S., Wahl, M., Grimstad, A., Huber, R. and S. Sataluri, "Using Domains in LDAP/X.500 Distinguished Names", RFC 2247, January 1998. [RFC2251] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [RFC2253] Wahl, M., Kille, S. and T. Howes, "Lightweight Directory Access Protocol (v3): UTF-8 String Representation of Distinguished Names", RFC 2253, December 1997. [RFC2255] Howes, T. and M. Smith, "The LDAP URL Format", RFC 2255, December 1997. [RFC2782] Gulbrandsen, A., Vixie, P. and L. Esibov, "A DNS RR for specifying the location of services (DNS SRV)", RFC 2782, February 2000. Zeilenga Experimental [Page 9] RFC 3088 OpenLDAP Root Service April 2001 [RFC2829] Wahl, M., Alvestrand, H., Hodges, J. and R. Morgan, "Authentication Methods for LDAP", RFC 2829, May 2000. [RFC2830] Hodges, J., Morgan, R. and M. Wahl, "Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security", RFC 2830, May 2000. [LOCATE] IETF LDAPext WG, "Discovering LDAP Services with DNS", Work in Progress. [LDAPv2+] University of Michigan LDAP Team, "Referrals within the LDAPv2 Protocol", August 1996. [NAMEDREF] Zeilenga, K. (editor), "Named Subordinate References in LDAP Directories", Work in Progress. [X500] ITU-T Rec. X.500, "The Directory: Overview of Concepts, Models and Service", 1993. Zeilenga Experimental [Page 10] RFC 3088 OpenLDAP Root Service April 2001 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 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. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Zeilenga Experimental [Page 11] PK )�c\S���h �h ( doc/alt-openldap11-devel/rfc/rfc2589.txtnu �[��� Network Working Group Y. Yaacovi Request for Comments: 2589 Microsoft Category: Standards Track M. Wahl Innosoft International, Inc. T. Genovese Microsoft May 1999 Lightweight Directory Access Protocol (v3): Extensions for Dynamic Directory Services Status of this Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (1999). All Rights Reserved. 1. Abstract This document defines the requirements for dynamic directory services and specifies the format of request and response extended operations for supporting client-server interoperation in a dynamic directories environment. The Lightweight Directory Access Protocol (LDAP) [1] supports lightweight access to static directory services, allowing relatively fast search and update access. Static directory services store information about people that persists in its accuracy and value over a long period of time. Dynamic directory services are different in that they store information that only persists in its accuracy and value when it is being periodically refreshed. This information is stored as dynamic entries in the directory. A typical use will be a client or a person that is either online - in which case it has an entry in the directory, or is offline - in which case its entry disappears from the directory. Though the protocol operations and attributes used by dynamic directory services are similar to the ones used for static directory services, clients that store dynamic information in the directory need to periodically refresh this information, in order to prevent it from disappearing. If dynamic entries are not refreshed Yaacovi, et al. Standards Track [Page 1] RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 within a given timeout, they will be removed from the directory. For example, this will happen if the client that set them goes offline. A flow control mechanism from the server is also described that allows a server to inform clients how often they should refresh their presence. 2. Requirements The protocol extensions must allow accessing dynamic information in a directory in a standard LDAP manner, to allow clients to access static and dynamic information in the same way. By definition, dynamic entries are not persistent and clients may go away gracefully or not. The proposed extensions must offer a way for a server to tell if entries are still valid, and to do this in a way that is scalable. There also must be a mechanism for clients to reestablish their entry with the server. There must be a way for clients to find out, in a standard LDAP manner, if servers support the dynamic extensions. Finally, to allow clients to broadly use the dynamic extensions, the extensions need to be registered as standard LDAP extended operations. 3. Description of Approach The Lightweight Directory Access Protocol (LDAP) [1] permits additional operation requests and responses to be added to the protocol. This proposal takes advantage of these to support directories which contain dynamic information in a manner which is fully integrated with LDAP. The approach described in this proposal defines dynamic entries in order to allow implementing directories with dynamic information. An implementation of dynamic directories, must be able to support dynamic directory entries. 3.1. Dynamic Entries and the dynamicObject object class A dynamic entry is an object in the directory tree which has a time- to-live associated with it. This time-to-live is set when the entry is created. The time-to-live is automatically decremented, and when it expires the dynamic entry disappears. By invoking the refresh extended operation (defined below) to re-set the time-to-live, a client can cause the entry to remain present a while longer. Yaacovi, et al. Standards Track [Page 2] RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 A dynamic entry is created by including the objectClass value given in section 5 in the list of attributes when adding an entry. This method is subject to standard access control restrictions. The extended operation covered here, allows a client to refresh a dynamic entry by invoking, at intervals, refresh operations containing that entry's name. Dynamic entries will be treated the same as non-dynamic entries when processing search, compare, add, delete, modify and modifyDN operations. However if clients stop sending refresh operations for an entry, then the server will automatically and without notification remove that entry from the directory. This removal will be treated the same as if the entry had been deleted by an LDAP protocol operation. There is no way to change a static entry into a dynamic one and vice-versa. If the client is using Modify with an objectClass of dynamicObject on a static entry, the server must return a service error either "objectClassModsProhibited" (if the server does not allow objectClass modifications at all) or "objectClassViolation" (if the server does allow objectClass modifications in general). A dynamic entry may be removed by the client using the delete operation. This operation will be subject to access control restrictions. A non-dynamic entry cannot be added subordinate to a dynamic entry: the server must return an appropriate update or service error if this is attempted. The support of dynamic attributes of an otherwise static object, are outside the scope of this document. 3.2 Dynamic meetings (conferences) The way dynamicObject is defined, it has a time-to-live associated with it, and that's about it. Though the most common dynamic object is a person object, there is no specific type associated with the dynamicObject as defined here. By the use of the dynamic object's attributes, one can make this object represent practically anything. Specifically, Meetings (conferences) can be represented by dynamic objects. While full-featured meeting support requires special semantics and handling by the server (and is not in the scope of this document), the extensions described here, provide basic meetings support. A meeting object can be refreshed by the meeting participants, and when it is not, the meeting entry disappears. The one meeting type that is naturally supported by the dynamic extensions is creator-owned meeting. Yaacovi, et al. Standards Track [Page 3] RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 3.2.1 Creator-owned meetings Creator-owned meetings are created by a client that sets the time- to-live attribute for the entry, and it is this client's responsibility to refresh the meeting entry, so that it will not disappear. Others might join the meeting, by modifying the appropriate attribute, but they are not allowed to refresh the entry. When the client that created the entry goes away, it can delete the meeting entry, or it might disappear when its time-to-live expires. This is consistent with the common model for dynamicObject as described above. 4. Protocol Additions 4.1 Refresh Request Refresh is a protocol operation sent by a client to tell the server that the client is still alive and the dynamic directory entry is still accurate and valuable. The client sends a Refresh request periodically based on the value of the client refresh period (CRP). The server can request that the client change this value. As long as the server receives a Refresh request within the timeout period, the directory entry is guaranteed to persist on the server. Client implementers should be aware that since the intervening network between the client and server is unreliable, a Refresh request packet may be delayed or lost while in transit. If this occurs, the entry may disappear, and the client will need to detect this and re-add the entry. A client may request this operation by transmitting an LDAP PDU containing an ExtendedRequest. An LDAP ExtendedRequest is defined as follows: ExtendedRequest ::= [APPLICATION 23] SEQUENCE { requestName [0] LDAPOID, requestValue [1] OCTET STRING OPTIONAL } The requestName field must be set to the string "1.3.6.1.4.1.1466.101.119.1". The requestValue field will contain as a value the DER-encoding of the following ASN.1 data type: SEQUENCE { entryName [0] LDAPDN, requestTtl [1] INTEGER } Yaacovi, et al. Standards Track [Page 4] RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 The entryName field is the UTF-8 string representation of the name of the dynamic entry [3]. This entry must already exist. The requestTtl is a time in seconds (between 1 and 31557600) that the client requests that the entry exists in the directory before being automatically removed. Servers are not required to accept this value and might return a different TTL value to the client. Clients must be able to use this server-dictated value as their CRP. 4.2 Refresh Response If a server implements this extension, then when the request is made it will return an LDAP PDU containing an ExtendedResponse. An LDAP ExtendedResponse is defined as follows: ExtendedResponse ::= [APPLICATION 24] SEQUENCE { COMPONENTS OF LDAPResult, responseName [10] LDAPOID OPTIONAL, response [11] OCTET STRING OPTIONAL } The responseName field contains the same string as that present in the request. The response field will contain as a value the DER-encoding of the following ASN.1 data type: SEQUENCE { responseTtl [1] INTEGER } The responseTtl field is the time in seconds which the server chooses to have as the time-to-live field for that entry. It must not be any smaller than that which the client requested, and it may be larger. However, to allow servers to maintain a relatively accurate directory, and to prevent clients from abusing the dynamic extensions, servers are permitted to shorten a client-requested time-to-live value, down to a minimum of 86400 seconds (one day). If the operation was successful, the errorCode field in the standardResponse part of an ExtendedResponse will be set to success. In case of an error, the responseTtl field will have the value 0, and the errorCode field will contain an appropriate value, as follows: If the entry named by entryName could not be located, the errorCode field will contain "noSuchObject". If the entry is not dynamic, the errorCode field will contain "objectClassViolation". If the requester does not have permission to refresh the entry, the Yaacovi, et al. Standards Track [Page 5] RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 errorCode field will contain "insufficientAccessRights". If the requestTtl field is too large, the errorCode field will contain "sizeLimitExceeded". If a server does not implement this extension, it will return an LDAP PDU containing an ExtendedResponse, which contains only the standardResponse element (the responseName and response elements will be absent). The LDAPResult element will indicate the protocolError result code. This request is permitted to be invoked when LDAP is carried by a connectionless transport. When using a connection-oriented transport, there is no requirement that this operation be on the same particular connection as any other. A client may open multiple connections, or close and then reopen a connection. 4.3 X.500/DAP Modify(97) X.500/DAP servers can map the Refresh request and response operations into the X.500/DAP Modify(97) operation. 5. Schema Additions All dynamic entries must have the dynamicObject value in their objectClass attribute. This object class is defined as follows (using the ObjectClassDescription notation of [2]): ( 1.3.6.1.4.1.1466.101.119.2 NAME 'dynamicObject' DESC 'This class, if present in an entry, indicates that this entry has a limited lifetime and may disappear automatically when its time-to-live has reached 0. There are no mandatory attributes of this class, however if the client has not supplied a value for the entryTtl attribute, the server will provide one.' SUP top AUXILIARY ) Furthermore, the dynamic entry must have the following operational attribute. It is described using the AttributeTypeDescription notation of [2]: ( 1.3.6.1.4.1.1466.101.119.3 NAME 'entryTtl' DESC 'This operational attribute is maintained by the server and appears to be present in every dynamic entry. The attribute is not present when the entry does not contain the dynamicObject object class. The value of this attribute is the time in seconds that the entry will continue to exist Yaacovi, et al. Standards Track [Page 6] RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 before disappearing from the directory. In the absence of intervening refresh operations, the values returned by reading the attribute in two successive searches are guaranteed to be nonincreasing. The smallest permissible value is 0, indicating that the entry may disappear without warning. The attribute is marked NO-USER-MODIFICATION since it may only be changed using the refresh operation.' SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE NO-USER-MODIFICATION USAGE dSAOperation ) To allow servers to support dynamic entries in only a part of the DIT, the following operational attribute is defined. It is described using the AttributeTypeDescription notation of [2]: ( 1.3.6.1.4.1.1466.101.119.4 NAME 'dynamicSubtrees' DESC 'This operational attribute is maintained by the server and is present in the Root DSE, if the server supports the dynamic extensions described in this memo. The attribute contains a list of all the subtrees in this directory for which the server supports the dynamic extensions.' SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 NO-USER-MODIFICATION USAGE dSAOperation ) 6. Client and Server Requirements 6.1 Client Requirements Clients can find out if a server supports the dynamic extensions by checking the supportedExtension field in the root DSE, to see if the OBJECT IDENTIFIER described in section 4 is present. Since servers may select to support the dynamic extensions in only some of the subtrees of the DIT, clients must check the dynamicSubtrees operational attribute in the root DSE to find out if the dynamic extensions are supported on a specific subtree. Once a dynamic entry has been created, clients are responsible for invoking the refresh extended operation, in order to keep that entry present in the directory. Clients must not expect that a dynamic entry will be present in the DIT after it has timed out, however it must not require that the server remove the entry immediately (some servers may only process timing out entries at intervals). If the client wishes to ensure the entry does not exist it should issue a RemoveRequest for that entry. Initially, a client needs to know how often it should send refresh requests to the server. This value is defined as the CRP (Client Refresh Period) and is set by the server based on the entryTtl. Yaacovi, et al. Standards Track [Page 7] RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 Since the LDAP AddRequest operation is left unchanged and is not modified in this proposal to return this value, a client must issue a Refresh extended operation immediately after an Add that created a dynamic entry. The Refresh Response will return the CRP (in responseTtl) to the client. Clients must not issue the refresh request for dynamic entries which they have not created. If an anonymous client attempts to do so, a server is permitted to return insufficientAccessRights (50) in the RefreshResponse, enforcing the client to bind first. Please note that servers which allow anonymous clients to create and refresh dynamic entries will not be able to enforce the above. Clients should always be ready to handle the case in which their entry timed out. In such a case, the Refresh operation will fail with an error code such as noSuchObject, and the client is expected to re-create its entry. Clients should be prepared to experience refresh operations failing with protocolError, even though the add and any previous refresh requests succeeded. This might happen if a proxy between the client and the server goes down, and another proxy is used which does not support the Refresh extended operation. 6.2 Server Requirements Servers are responsible for removing dynamic entries when they time out. Servers are not required to do this immediately. Servers must enforce the structural rules listed in above section 3. Servers must ensure that the operational attribute described in section 5 is present in dynamic entries Servers may permit anonymous users to refresh entries. However, to eliminate the possibility of a malicious use of the Refresh operation, servers may require the refreshing client to bind first. A server implementation can achieve this by presenting ACLs on the entryTtl attribute, and returning insufficientAccessRights (50) in the RefreshResponse, if the client is not allowed to refresh the entry. Doing this, though, might have performance implications on the server and might impact the server's scalability. Servers may require that a client which attempts to create a dynamic entry have a remove permission for that entry. Servers which implement the dynamic extensions must have the OBJECT IDENTIFIER, described above in section 4 for the request and Yaacovi, et al. Standards Track [Page 8] RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 response, present as a value of the supportedExtension field in the root DSE. They must also have as values in the attributeTypes and objectClasses attributes of their subschema subentries, the AttributeTypeDescription and ObjectClassDescription from section 5. Servers can limit the support of the dynamic extensions to only some of the subtrees in the DIT. Servers indicate for which subtrees they support the extensions, by specifying the OIDs for the supported subtrees in the dynamicSubtrees attribute described in section 5. If a server supports the dynamic extensions for all naming contexts it holds, the dynamicSubtrees attribute may be absent. 7. Implementation issues 7.1 Storage of dynamic information Dynamic information is expected to change very often. In addition, Refresh requests are expected to arrive at the server very often. Disk-based databases that static directory services often use are likely inappropriate for storing dynamic information. We recommend that server implementations store dynamic entries in memory sufficient to avoid paging. This is not a requirement. We expect LDAP servers to be able to store static and dynamic entries. If an LDAP server does not support dynamic entries, it should respond with an error code such as objectClassViolation. 7.2 Client refresh behavior In some cases, the client might not get a Refresh response. This may happen as a result of a server crash after receiving the Refresh request, the TCP/IP socket timing out in the connection case, or the UDP packet getting lost in the connection-less case. It is recommended that in such a case, the client will retry the Refresh operation immediately, and if this Refresh request does not get a response as well, it will resort to its original Refresh cycle, i.e. send a Refresh request at its Client Refresh Period (CRP). 7.3 Configuration of refresh times We recommend that servers will provide administrators with the ability to configure the default client refresh period (CRP), and also a minimum and maximum CRP values. This, together with allowing administrators to request that the server will not change the CRP dynamically, will allow administrators to set CRP values which will enforce a low refresh traffic, or - on the other extreme, an highly up-to-date directory. Yaacovi, et al. Standards Track [Page 9] RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 8. Replication Replication is only partially addressed in this memo. There is a separate effort in progress at the IETF on replication of static and dynamic directories. it is allowed to replicate a dynamic entry or a static entry with dynamic attributes. Since the entryTtl is expressed as a relative time (how many seconds till the entry will expire), replicating it means that the replicated entry will be "off" by the replication time. 9. Localization The are no localization issues for this extended operation. 10. Security Considerations Standard LDAP security rules and support apply for the extensions described in this document, and there are no special security issues for these extensions. Please note, though, that servers may permit anonymous clients to refresh entries which they did not create. Servers are also permitted to control a refresh access to an entry by requiring clients to bind before issuing a RefreshRequest. This will have implications on the server performance and scalability. Also, Care should be taken in making use of information obtained from directory servers that has been supplied by client, as it may now be out of date. In many networks, for example, IP addresses are automatically assigned when a host connects to the network, and may be reassigned if that host later disconnects. An IP address obtained from the directory may no longer be assigned to the host that placed the address in the directory. This issue is not specific to LDAP or dynamic directories. 11. Acknowledgments Design ideas included in this document are based on those discussed in ASID and other IETF Working Groups. Yaacovi, et al. Standards Track [Page 10] RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 12. Authors' Addresses Yoram Yaacovi Microsoft One Microsoft way Redmond, WA 98052 USA Phone: +1 206-936-9629 EMail: yoramy@microsoft.com Mark Wahl Innosoft International, Inc. 8911 Capital of Texas Hwy #4140 Austin, TX 78759 USA Email: M.Wahl@innosoft.com Tony Genovese Microsoft One Microsoft way Redmond, WA 98052 USA Phone: +1 206-703-0852 EMail: tonyg@microsoft.com 13. Bibliography [1] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (Version 3)", RFC 2251, December 1997. [2] Wahl, M. Coulbeck, A., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (v3): Attribute Syntax Definitions", RFC 2252, December 1997. [3] Wahl, M. and S. Kille, "Lightweight Directory Access Protocol (v3): UTF-8 String Representation of Distinguished Names", RFC 2253, December 1997. Yaacovi, et al. Standards Track [Page 11] RFC 2589 LDAPv3 Extensions for Dynamic Directory Services May 1999 14. Full Copyright Statement Copyright (C) The Internet Society (1999). 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. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Yaacovi, et al. Standards Track [Page 12] PK )�c\�Œtsy sy ( doc/alt-openldap11-devel/rfc/rfc4373.txtnu �[��� Network Working Group R. Harrison Request for Comments: 4373 J. Sermersheim Category: Informational Novell, Inc. Y. Dong January 2006 Lightweight Directory Access Protocol (LDAP) Bulk Update/Replication Protocol (LBURP) Status of This Memo This memo provides information for the Internet community. It does not specify an Internet standard of any kind. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2006). Abstract The Lightweight Directory Access Protocol (LDAP) Bulk Update/Replication Protocol (LBURP) allows an LDAP client to perform a bulk update to an LDAP server. The protocol frames a sequenced set of update operations within a pair of LDAP extended operations to notify the server that the update operations in the framed set are related in such a way that the ordering of all operations can be preserved during processing even when they are sent asynchronously by the client. Update operations can be grouped within a single protocol message to maximize the efficiency of client-server communication. The protocol is suitable for efficiently making a substantial set of updates to the entries in an LDAP server. Harrison, et al. Informational [Page 1] RFC 4373 LDAP Bulk Update/Replication Protocol January 2006 Table of Contents 1. Introduction ....................................................3 2. Conventions Used in This Document ...............................3 3. Overview of Protocol ............................................3 3.1. Update Initiation ..........................................4 3.2. Update Stream ..............................................4 3.2.1. LBURPUpdateRequest ..................................4 3.2.2. LBURPUpdateResponse .................................4 3.3. Update Termination .........................................4 3.4. Applicability of Protocol ..................................5 4. Description of Protocol Flow ....................................5 5. Elements of Protocol ............................................6 5.1. StartLBURPRequest ..........................................7 5.1.1. updateStyleOID ......................................7 5.2. StartLBURPResponse .........................................7 5.2.1. maxOperations .......................................8 5.3. LBURPUpdateRequest .........................................8 5.3.1. sequenceNumber ......................................8 5.3.2. UpdateOperationList .................................9 5.4. LBURPUpdateResponse ........................................9 5.4.1. OperationResults ...................................10 5.4.1.1. operationNumber ...........................10 5.4.1.2. ldapResult ................................10 5.5. EndLBURPRequest ...........................................10 5.5.1. sequenceNumber .....................................10 5.6. EndLBURPResponse ..........................................11 6. Semantics of the Incremental Update Style ......................11 7. General LBURP Semantics ........................................11 8. Security Considerations ........................................12 9. IANA Considerations ............................................13 9.1. LDAP Object Identifier Registrations ......................13 10. Normative References ..........................................14 11. Informative References ........................................14 Harrison, et al. Informational [Page 2] RFC 4373 LDAP Bulk Update/Replication Protocol January 2006 1. Introduction The Lightweight Directory Access Protocol (LDAP) Bulk Update/Replication Protocol (LBURP) arose from the need to allow an LDAP client to efficiently present large quantities of updates to an LDAP server and have the LDAP server efficiently process them. LBURP introduces a minimum of new operational functionality to the LDAP protocol because the update requests sent by the client encapsulate standard LDAP [RFC2251] update operations. However, this protocol greatly facilitates bulk updates by allowing the client to send the update operations asynchronously and still allow the server to maintain proper ordering of the operations. It also allows the server to recognize the client's intent to perform a potentially large set of update operations and then to change its processing strategy to more efficiently process the operations. 2. Conventions Used in This Document Imperative keywords defined in RFC 2119 [RFC2119] are used in this document, and carry the meanings described there. All Basic Encoding Rules (BER) [X.690] encodings follow the conventions found in section 5.1 of [RFC2251]. The term "supplier" applies to an LDAP client or an LDAP server (acting as a client) that supplies a set of update operations to a consumer. The term "consumer" applies to an LDAP server that consumes (i.e., processes) the sequenced set of update operations sent to it by a supplier. 3. Overview of Protocol LBURP frames a set of update operations within a pair of LDAP extended operations that mark the beginning and end of the update set. These updates are sent via LDAP extended operations, each containing a sequence number and a list of one or more update operations to be performed by the consumer. Except for the fact that they are grouped together as part of a larger LDAP message, the update operations in each subset are encoded as LDAP update operations and use the LDAP Abstract Syntax Notation One (ASN.1) [X.680] message types specified in [RFC2251]. Harrison, et al. Informational [Page 3] RFC 4373 LDAP Bulk Update/Replication Protocol January 2006 3.1. Update Initiation The protocol is initiated when a supplier sends a StartLBURPRequest extended operation to a consumer as a notification that a stream of associated LBURPUpdateRequests will follow. The supplier associates semantics with this stream of requests by including the Object Identifier (OID) of the bulk update/replication style in the StartLBURPRequest. The consumer responds to the StartLBURPRequest with a StartLBURPResponse message. 3.2. Update Stream After the consumer responds with a StartLBURPResponse, the supplier sends a stream of LBURPUpdateRequest messages to the consumer. Messages within this stream may be sent asynchronously to maximize the efficiency of the transfer. The consumer responds to each LBURPUpdateRequest with an LBURPUpdateResponse message. 3.2.1. LBURPUpdateRequest Each LBURPUpdateRequest contains a sequence number identifying its relative position within the update stream and an UpdateOperationList containing an ordered list of LDAP update operations to be applied to the Directory Information Tree (DIT). The sequence number enables the consumer to process LBURPUpdateRequest messages in the order they were sent by the supplier even when they are sent asynchronously. The consumer processes each LBURPUpdateRequest according to the sequence number by applying the LDAP update operations in its UpdateOperationList to the DIT in the order they are listed. 3.2.2. LBURPUpdateResponse When the consumer has processed the update operations from an UpdateOperationList, it sends an LBURPUpdateResponse to the supplier indicating the success or failure of the update operations contained within the corresponding LBURPUpdateRequest. 3.3. Update Termination After the supplier has sent all of its LBURPUpdateRequest messages, it sends an EndLBURPRequest message to the consumer to terminate the update stream. Upon servicing all LBURPOperation requests and receiving the EndLBURPRequest, the consumer responds with an EndLBURPResponse, and the update is complete. Harrison, et al. Informational [Page 4] RFC 4373 LDAP Bulk Update/Replication Protocol January 2006 3.4. Applicability of Protocol LBURP is designed to facilitate the bulk update of LDAP servers. It can also be used to synchronize directory information between a single master and multiple slaves. No attempt is made to deal with the issues associated with multiple- master replication environments (such as keeping modification times of attribute values) so that updates to the same entry on different replicas can be correctly ordered. For this reason, when LBURP alone is used for replication, proper convergence of the data between all replicas can only be assured in a single-master replication environment. 4. Description of Protocol Flow This section describes the LBURP protocol flow and the information contained in each protocol message. Throughout this section, the client or server acting as a supplier is indicated by the letter "S", and the server acting as a consumer is indicated by the letter "C". The construct "S -> C" indicates that the supplier is sending an LDAP message to the consumer, and "C -> S" indicates that the consumer is sending an LDAP message to the supplier. Note that the protocol flow below assumes that a properly authenticated LDAP session has already been established between the supplier and consumer. S -> C: StartLBURPRequest message. The parameter is: 1) OID for the LBURP update style (see section 5.1.1). C -> S: StartLBURPResponse message. The parameter is: 1) An optional maxOperations instruction (see section 5.2.1). S -> C: An update stream consisting of zero or more LBURPUpdateRequest messages. The requests MAY be sent asynchronously. The parameters are: 1) A sequence number specifying the order of this LBURPUpdateRequest with respect to the other LBURPUpdateRequest messages in the update stream (see section 5.3.1). 2) LBURPUpdateRequest.updateOperationList, a list of one or more LDAP update operations (see section 5.3.2). Harrison, et al. Informational [Page 5] RFC 4373 LDAP Bulk Update/Replication Protocol January 2006 The consumer processes the LBURPUpdateRequest messages in the order of their sequence numbers and applies the LDAP update operations contained within each LBURPUpdateRequest to the DIT in the order they are listed. C -> S: LBURPUpdateResponse message. This is sent when the consumer completes processing the update operations from each LBURPUpdateRequest.updateOperationList. S -> C: EndLBURPRequest message. This is sent after the supplier sends all of its LBURPUpdateRequest messages to the consumer. The parameter is: 1) A sequence number that is one greater than the sequence number of the last LBURPUpdateRequest message in the update stream. This allows the EndLBURPRequest to also be sent asynchronously. C -> S: EndLBURPResponse message. This is sent in response to the EndLBURPRequest after the consumer has serviced all LBURPOperation requests. 5. Elements of Protocol LBURP uses two LDAP ExtendedRequest messages--StartLBURPRequest and EndLBURPRequest--to initiate and terminate the protocol. A third LDAP ExtendedRequest message--LBURPUpdateRequest--is used to send update operations from the supplier to the consumer. These three requests along with their corresponding responses comprise the entire protocol. LBURP request messages are defined in terms of the LDAP ExtendedRequest [RFC2251] as follows: ExtendedRequest ::= [APPLICATION 23] SEQUENCE { requestName [0] LDAPOID, requestValue [1] OCTET STRING OPTIONAL } LBURP response messages are defined in terms of the LDAP ExtendedResponse [RFC2251] as follows: ExtendedResponse ::= [APPLICATION 24] SEQUENCE { COMPONENTS of LDAPResult, responseName [10] LDAPOID OPTIONAL, response [11] OCTET STRING OPTIONAL } Harrison, et al. Informational [Page 6] RFC 4373 LDAP Bulk Update/Replication Protocol January 2006 5.1. StartLBURPRequest The requestName value of the StartLBURPRequest is OID 1.3.6.1.1.17.1. The requestValue of the StartLBURPRequest contains the BER-encoding of the following ASN.1: StartLBURPRequestValue ::= SEQUENCE { updateStyleOID LDAPOID } LDAPOID is defined in [RFC2251], section 4.1.2. 5.1.1. updateStyleOID The updateStyleOID is an OID that uniquely identifies the LBURP update style being used. This document defines one LBURP update semantic style that can be transmitted between the StartLBURPRequest and EndLBURPRequest. The updateStyleOID is included in the protocol for future expansion of additional update styles. For example, a future specification might define an update style with semantics to replace all existing entries with a new set of entries and thus only allows the Add operation. The updateStyleOID for the LBURP Incremental Update style is 1.3.6.1.1.17.7. The semantics of this update style are described in section 6. 5.2. StartLBURPResponse The responseName of the StartLBURPResponse is the OID 1.3.6.1.1.17.2. The optional response element contains the BER-encoding of the following ASN.1: StartLBURPResponseValue ::= maxOperations maxOperations ::= INTEGER (0 .. maxInt) maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) -- Harrison, et al. Informational [Page 7] RFC 4373 LDAP Bulk Update/Replication Protocol January 2006 5.2.1. maxOperations When present, the value of maxOperations instructs the supplier to send no more than that number of update operations per LBURPUpdateRequest.updateOperationList (see section 5.3.2). If the consumer does not send a maxOperations value, it MUST be prepared to accept any number of update operations per LBURPUpdateRequest.updateOperationList. The supplier MAY send fewer but MUST NOT send more than maxOperations update operations in a single LBURPUpdateRequest.updateOperationList. 5.3. LBURPUpdateRequest The LBURPUpdateRequest message is used to send a set of zero or more LDAP update operations from the supplier to the consumer along with sequencing information that enables the consumer to maintain the proper sequencing of multiple asynchronous LBURPUpdateRequest messages. The requestName of the LBURPUpdateRequest is the OID 1.3.6.1.1.17.5. The requestValue of an LBURPOperation contains the BER-encoding of the following ASN.1: LBURPUpdateRequestValue ::= SEQUENCE { sequenceNumber INTEGER (1 .. maxInt), updateOperationList UpdateOperationList } 5.3.1. sequenceNumber The sequenceNumber orders associated LBURPOperation requests. This enables the consumer to process LBURPOperation requests in the order specified by the supplier. The supplier MUST set the value of sequenceNumber of the first LBURPUpdateRequest to 1, and MUST increment the value of sequenceNumber by 1 for each succeeding LBURPUpdateRequest. In the unlikely event that the number of LBURPUpdateRequest messages exceeds maxInt, a sequenceNumber value of 1 is deemed to be the succeeding sequence number following a sequence number of maxInt. Harrison, et al. Informational [Page 8] RFC 4373 LDAP Bulk Update/Replication Protocol January 2006 5.3.2. UpdateOperationList The UpdateOperationList is a list of one or more standard LDAP update requests and is defined as follows: UpdateOperationList ::= SEQUENCE OF SEQUENCE{ updateOperation CHOICE { addRequest AddRequest, modifyRequest ModifyRequest, delRequest DelRequest, modDNRequest ModifyDNRequest }, controls [0] Controls OPTIONAL } AddRequest, ModifyRequest, DelRequest, and ModifyDNRequest are defined in [RFC2251], sections 4.6, 4.7, 4.8, and 4.9. The LDAP update requests in the UpdateOperationList MUST be applied to the DIT in the order in which they are listed. 5.4. LBURPUpdateResponse An LBURPUpdateResponse message is sent from the consumer to the supplier to signal that all of the update operations from the UpdateOperationList of an LBURPUpdateRequest have been completed and to give the results for the update operations from that list. The responseName of the LBURPUpdateResponse is the OID 1.3.6.1.1.17.6. If the consumer server cannot successfully decode an LBURPUpdateRequest in its entirety, the resultCode for the corresponding LBURPUpdateResponse is set to protocolError and the response element is omitted. Updates from the LBURPUpdateRequest SHALL NOT be committed to the DIT in this circumstance. If the status of all of the update operations being reported by an LBURPUpdateResponse message is success, the resultCode of the LBURPUpdateResponse message is set to success and the response element is omitted. If the status of any of the update operations being reported by an LBURPUpdateResponse message is something other than success, the resultCode for the entire LBURPUpdateResponse is set to other to signal that the response element is present. Harrison, et al. Informational [Page 9] RFC 4373 LDAP Bulk Update/Replication Protocol January 2006 5.4.1. OperationResults When a response element is included in an LBURPUpdateResponse message, it contains the BER-encoding of the following ASN.1: OperationResults ::= SEQUENCE OF OperationResult OperationResult ::= SEQUENCE { operationNumber INTEGER, ldapResult LDAPResult } An OperationResult is included for each operation from the UpdateOperationList that failed during processing. 5.4.1.1. operationNumber The operationNumber identifies the LDAP update operation from the UpdateOperationList of the LBURPUpdateRequest that failed. Operations are numbered beginning at 1. 5.4.1.2. ldapResult The ldapResult included in the OperationResult is the same ldapResult that would be sent for the update operation that failed if it had failed while being processed as a normal LDAP update operation. LDAPResult is defined in [RFC2251], section 4.1.10. 5.5. EndLBURPRequest The requestName of the EndLBURPRequest is the OID 1.3.6.1.1.17.3. The requestValue contains the BER-encoding of the following ASN.1: EndLBURPRequestValue::= SEQUENCE { sequenceNumber INTEGER (1 .. maxInt) } 5.5.1. sequenceNumber The value in sequenceNumber is one greater than the last LBURPUpdateRequest.sequenceNumber in the update stream. It allows the server to know when it has received all outstanding asynchronous LBURPUpdateRequests. Harrison, et al. Informational [Page 10] RFC 4373 LDAP Bulk Update/Replication Protocol January 2006 5.6. EndLBURPResponse The responseName of the EndLBURPResponse is the OID 1.3.6.1.1.17.4. There is no response element in the EndLBURPResponse message. 6. Semantics of the Incremental Update Style The initial state of entries in the consumer's DIT plus the LBURPUpdateRequest messages in the update stream collectively represent the desired final state of the consumer's DIT. All LDAP update operations defined in [RFC2251]--Add, Modify, Delete, and Modify DN--are allowed in the incremental update stream. All of the semantics of those operations are in effect, so for instance, an attempt to add an entry that already exists will fail just as it would during a normal LDAP Add operation. 7. General LBURP Semantics The consumer server may take any action required to efficiently process the updates sent via LBURP, as long as the final state is equivalent to that which would have been achieved if the updates in the update stream had been applied to the DIT using normal LDAP update operations. The LBURPUpdateRequest messages that form the update stream MAY be sent asynchronously by the supplier to the consumer. This means that the supplier need not wait for an LBURPUpdateResponse message for one LBURPUpdateRequest message before sending the next LBURPUpdateRequest message. When the LBURP update stream contains a request that affects multiple Directory System Agents (DSAs), the consumer MAY choose to perform the request or return a resultCode value of affectsMultipleDSAs. As with any LDAP operation, a consumer MAY send a resultCode value of referral as part of the OperationResult element for any operation on an entry that it does not contain. If the consumer is configured to do so, it MAY chain on behalf of the supplier to complete the update operation instead. While a consumer server is processing an LBURP update stream, it may choose not to service LDAP requests on other connections. This provision is designed to allow implementers the freedom to implement highly-efficient methods of handling the update stream without being constrained by the need to maintain a live, working DIT database while doing so. Harrison, et al. Informational [Page 11] RFC 4373 LDAP Bulk Update/Replication Protocol January 2006 If a consumer chooses to refuse LDAP operation requests from other suppliers during LBURP update, it is RECOMMENDED that the consumer refer those requests to another server that has the appropriate data to complete the operation. Unless attribute values specifying timestamps are included as part of the update stream, updates made using LBURP are treated the same as other LDAP operations wherein they are deemed to occur at the present. Consumers MAY store timestamp values sent by suppliers but are not required to do so. Implementations may choose to perform the operations in the update stream with special permissions to improve performance. Consumer implementations should include functionality to detect and terminate connections on which an LBURP session has been initiated but information (such as the EndLBURPRequest) needed to complete the LBURP session is never received. A timeout is one mechanism that can be used to accomplish this. 8. Security Considerations Implementations should ensure that a supplier making an LBURP request is properly authenticated and authorized to make the updates requested. There is a potential for loss of data if updates are made to the DIT without proper authorization. If LBURP is used for replication, implementers should note that unlike other replication protocols, no existing replication agreement between supplier and consumer is required. These risks increase if the consumer server also processes the update stream with special permissions to improve performance. For these reasons, implementers should carefully consider which permissions should be required to perform LBURP operations and take steps to ensure that only connections with appropriate authorization are allowed to perform them. The data contained in the update stream may contain passwords and other sensitive data. Care should be taken to properly safeguard this information while in transit between supplier and consumer. The StartTLS [RFC2830] operation is one mechanism that can be used to provide data confidentiality and integrity services for this purpose. As with any asynchronous LDAP operation, it may be possible for an LBURP supplier to send asynchronous LBURPUpdateRequest messages to the consumer faster than the consumer can process them. Consumer implementers should take steps to prevent LBURP suppliers from interfering with the normal operation of a consumer server by issuing a rapid stream of asynchronous LBURPUpdateRequest messages. Harrison, et al. Informational [Page 12] RFC 4373 LDAP Bulk Update/Replication Protocol January 2006 9. IANA Considerations Registration of the following values has been made by the IANA [RFC3383]. 9.1. LDAP Object Identifier Registrations The IANA has registered LDAP Object Identifiers identifying the protocol elements defined in this technical specification. The following registration template was provided: Subject: Request for LDAP OID Registration Person & email address to contact for further information: Roger Harrison rharrison@novell.com Specification: RFC 4373 Author/Change Controller: IESG Comments: Seven delegations will be made under the assigned OID. The following 6 OIDs are Protocol Mechanism OIDs of type "E" (supportedExtension): 1.3.6.1.1.17.1 StartLBURPRequest LDAP ExtendedRequest message 1.3.6.1.1.17.2 StartLBURPResponse LDAP ExtendedResponse message 1.3.6.1.1.17.3 EndLBURPRequest LDAP ExtendedRequest message 1.3.6.1.1.17.4 EndLBURPResponse LDAP ExtendedResponse message 1.3.6.1.1.17.5 LBURPUpdateRequest LDAP ExtendedRequest message 1.3.6.1.1.17.6 LBURPUpdateResponse LDAP ExtendedResponse message The following 1 OID is a Protocol Mechanism OID of type "F" (supportedFeature): 1.3.6.1.1.17.7 LBURP Incremental Update style OID Harrison, et al. Informational [Page 13] RFC 4373 LDAP Bulk Update/Replication Protocol January 2006 10. Normative References [RFC2119] Bradner, S., "Key Words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2251] Wahl, M., Howes, T., and S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [RFC3383] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 3383, September 2002. [X.680] ITU-T Recommendation X.680 (07/2002) | ISO/IEC 8824-1:2002 "Information Technology - Abstract Syntax Notation One (ASN.1): Specification of basic notation" [X.690] ITU-T Rec. X.690 (07/2002) | ISO/IEC 8825-1:2002, "Information technology - ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER)", 2002. 11. Informative References [RFC2830] Hodges, J., Morgan, R., and M. Wahl, "Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security", RFC 2830, May 2000. Harrison, et al. Informational [Page 14] RFC 4373 LDAP Bulk Update/Replication Protocol January 2006 Authors' Addresses Roger Harrison Novell, Inc. 1800 S. Novell Place Provo, UT 84606 Phone: +1 801 861 2642 EMail: rharrison@novell.com Jim Sermersheim Novell, Inc. 1800 S. Novell Place Provo, UT 84606 Phone: +1 801 861 3088 EMail: jimse@novell.com Yulin Dong EMail: yulindong@gmail.com Harrison, et al. Informational [Page 15] RFC 4373 LDAP Bulk Update/Replication Protocol January 2006 Full Copyright Statement Copyright (C) The Internet Society (2006). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Harrison, et al. Informational [Page 16] PK )�c\!Z�+� � ( doc/alt-openldap11-devel/rfc/rfc4524.txtnu �[��� Network Working Group K. Zeilenga, Ed. Request for Comments: 4524 OpenLDAP Foundation Obsoletes: 1274 June 2006 Updates: 2247, 2798 Category: Standards Track COSINE LDAP/X.500 Schema Status of This Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2006). Abstract This document provides a collection of schema elements for use with the Lightweight Directory Access Protocol (LDAP) from the COSINE and Internet X.500 pilot projects. This document obsoletes RFC 1274 and updates RFCs 2247 and 2798. Table of Contents 1. Introduction ....................................................3 1.1. Relationship to Other Documents ............................3 1.2. Terminology and Conventions ................................4 2. COSINE Attribute Types ..........................................4 2.1. associatedDomain ...........................................4 2.2. associatedName .............................................5 2.3. buildingName ...............................................5 2.4. co .........................................................5 2.5. documentAuthor .............................................6 2.6. documentIdentifier .........................................6 2.7. documentLocation ...........................................6 2.8. documentPublisher ..........................................7 2.9. documentTitle ..............................................7 2.10. documentVersion ...........................................7 2.11. drink .....................................................8 2.12. homePhone .................................................8 2.13. homePostalAddress .........................................8 Zeilenga Standards Track [Page 1] RFC 4524 COSINE LDAP/X.500 Schema June 2006 2.14. host ......................................................9 2.15. info ......................................................9 2.16. mail ......................................................9 2.17. manager ..................................................10 2.18. mobile ...................................................10 2.19. organizationalStatus .....................................11 2.20. pager ....................................................11 2.21. personalTitle ............................................11 2.22. roomNumber ...............................................12 2.23. secretary ................................................12 2.24. uniqueIdentifier .........................................12 2.25. userClass ................................................13 3. COSINE Object Classes ..........................................13 3.1. account ...................................................13 3.2. document ..................................................14 3.3. documentSeries ............................................14 3.4. domain ....................................................15 3.5. domainRelatedObject .......................................16 3.6. friendlyCountry ...........................................16 3.7. rFC822LocalPart ...........................................17 3.8. room ......................................................18 3.9. simpleSecurityObject ......................................18 4. Security Considerations ........................................18 5. IANA Considerations ............................................19 6. Acknowledgements ...............................................20 7. References .....................................................20 7.1. Normative References ......................................20 7.2. Informative References ....................................21 Appendix A. Changes since RFC 1274 ...............................23 A.1. LDAP Short Names .........................................23 A.2. pilotObject ..............................................23 A.3. pilotPerson ..............................................23 A.4. dNSDomain ................................................24 A.5. pilotDSA and qualityLabelledData .........................24 A.6. Attribute Syntaxes .......................................24 Appendix B. Changes since RFC 2247 ...............................24 Zeilenga Standards Track [Page 2] RFC 4524 COSINE LDAP/X.500 Schema June 2006 1. Introduction In the late 1980s, X.500 Directory Services were standardized by the CCITT (Commite' Consultatif International de Telegraphique et Telephonique), now a part of the ITU (International Telephone Union). This lead to Directory Service piloting activities in the early 1990s, including the COSINE (Co-operation and Open Systems Interconnection in Europe) PARADISE Project pilot [COSINEpilot] in Europe. Motivated by needs for large-scale directory pilots, RFC 1274 was published to standardize the directory schema and naming architecture for use in the COSINE and other Internet X.500 pilots [RFC1274]. In the years that followed, X.500 Directory Services have evolved to incorporate new capabilities and even new protocols. In particular, the Lightweight Directory Access Protocol (LDAP) [RFC4510] was introduced in the early 1990s [RFC1487], with Version 3 of LDAP introduced in the late 1990s [RFC2251] and subsequently revised in 2005 [RFC4510]. While much of the material in RFC 1274 has been superceded by subsequently published ITU-T Recommendations and IETF RFCs, many of the schema elements lack standardized schema descriptions for use in modern X.500 and LDAP directory services despite the fact that these schema elements are in wide use today. As the old schema descriptions cannot be used without adaptation, interoperability issues may arise due to lack of standardized modern schema descriptions. This document addresses these issues by offering standardized schema descriptions, where needed, for widely used COSINE schema elements. 1.1. Relationship to Other Documents This document, together with [RFC4519] and [RFC4517], obsoletes RFC 1274 in its entirety. [RFC4519] replaces Sections 9.3.1 (Userid) and 9.3.21 (Domain Component) of RFC 1274. [RFC4517] replaces Section 9.4 (Generally useful syntaxes) of RFC 1274. This document replaces the remainder of RFC 1274. Appendix A discusses changes since RFC 1274, as well as why certain schema elements were not brought forward in this revision of the COSINE schema. All elements not brought are to be regarded as Historic. The description of the 'domain' object class provided in this document supercedes that found in RFC 2247. That is, Section 3.4 of this document replaces Section 5.2 of [RFC2247]. Zeilenga Standards Track [Page 3] RFC 4524 COSINE LDAP/X.500 Schema June 2006 Some of the schema elements specified here were described in RFC 2798 (inetOrgPerson schema). This document supersedes these descriptions. This document, together with [RFC4519], replaces Section 9.1.3 of RFC 2798. 1.2. Terminology and Conventions 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]. DIT stands for Directory Information Tree. DN stands for Distinguished Name. DSA stands for Directory System Agent, a server. DSE stands for DSA-Specific Entry. DUA stands for Directory User Agent, a client. These terms are discussed in [RFC4512]. Schema definitions are provided using LDAP description formats [RFC4512]. Definitions provided here are formatted (line wrapped) for readability. 2. COSINE Attribute Types This section details COSINE attribute types for use in LDAP. 2.1. associatedDomain The 'associatedDomain' attribute specifies DNS [RFC1034][RFC2181] host names [RFC1123] that are associated with an object. That is, values of this attribute should conform to the following ABNF: domain = root / label *( DOT label ) root = SPACE label = LETDIG [ *61( LETDIG / HYPHEN ) LETDIG ] LETDIG = %x30-39 / %x41-5A / %x61-7A ; "0" - "9" / "A"-"Z" / "a"-"z" SPACE = %x20 ; space (" ") HYPHEN = %x2D ; hyphen ("-") DOT = %x2E ; period (".") For example, the entry in the DIT with a DN <DC=example,DC=com> might have an associated domain of "example.com". ( 0.9.2342.19200300.100.1.37 NAME 'associatedDomain' EQUALITY caseIgnoreIA5Match SUBSTR caseIgnoreIA5SubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) Zeilenga Standards Track [Page 4] RFC 4524 COSINE LDAP/X.500 Schema June 2006 The IA5String (1.3.6.1.4.1.1466.115.121.1.26) syntax and the 'caseIgnoreIA5Match' and 'caseIgnoreIA5SubstringsMatch' rules are described in [RFC4517]. Note that the directory will not ensure that values of this attribute conform to the <domain> production provided above. It is the application's responsibility to ensure that domains it stores in this attribute are appropriately represented. Also note that applications supporting Internationalized Domain Names SHALL use the ToASCII method [RFC3490] to produce <label> components of the <domain> production. 2.2. associatedName The 'associatedName' attribute specifies names of entries in the organizational DIT associated with a DNS domain [RFC1034][RFC2181]. ( 0.9.2342.19200300.100.1.38 NAME 'associatedName' EQUALITY distinguishedNameMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 ) The DistinguishedName (1.3.6.1.4.1.1466.115.121.1.12) syntax and the 'distinguishedNameMatch' rule are described in [RFC4517]. 2.3. buildingName The 'buildingName' attribute specifies names of the buildings where an organization or organizational unit is based, for example, "The White House". ( 0.9.2342.19200300.100.1.48 NAME 'buildingName' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{256} ) The DirectoryString (1.3.6.1.4.1.1466.115.121.1.15) syntax and the 'caseIgnoreMatch' and 'caseIgnoreSubstringsMatch' rules are described in [RFC4517]. 2.4. co The 'co' (Friendly Country Name) attribute specifies names of countries in human-readable format, for example, "Germany" and "Federal Republic of Germany". It is commonly used in conjunction with the 'c' (Country Name) [RFC4519] attribute (whose values are restricted to the two-letter codes defined in [ISO3166]). Zeilenga Standards Track [Page 5] RFC 4524 COSINE LDAP/X.500 Schema June 2006 ( 0.9.2342.19200300.100.1.43 NAME 'co' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) The DirectoryString (1.3.6.1.4.1.1466.115.121.1.15) syntax and the 'caseIgnoreMatch' and 'caseIgnoreSubstringsMatch' rules are described in [RFC4517]. 2.5. documentAuthor The 'documentAuthor' attribute specifies the distinguished names of authors (or editors) of a document. For example, ( 0.9.2342.19200300.100.1.14 NAME 'documentAuthor' EQUALITY distinguishedNameMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 ) The DistinguishedName (1.3.6.1.4.1.1466.115.121.1.12) syntax and the 'distinguishedNameMatch' rule are described in [RFC4517]. 2.6. documentIdentifier The 'documentIdentifier' attribute specifies unique identifiers for a document. A document may be identified by more than one unique identifier. For example, RFC 3383 and BCP 64 are unique identifiers that (presently) refer to the same document. ( 0.9.2342.19200300.100.1.11 NAME 'documentIdentifier' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{256} ) The DirectoryString (1.3.6.1.4.1.1466.115.121.1.15) syntax and the 'caseIgnoreMatch' and 'caseIgnoreSubstringsMatch' rules are described in [RFC4517]. 2.7. documentLocation The 'documentLocation' attribute specifies locations of the document original. ( 0.9.2342.19200300.100.1.15 NAME 'documentLocation' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{256} ) Zeilenga Standards Track [Page 6] RFC 4524 COSINE LDAP/X.500 Schema June 2006 The DirectoryString (1.3.6.1.4.1.1466.115.121.1.15) syntax and the 'caseIgnoreMatch' and 'caseIgnoreSubstringsMatch' rules are described in [RFC4517]. 2.8. documentPublisher The 'documentPublisher' attribute is the persons and/or organizations that published the document. Documents that are jointly published have one value for each publisher. ( 0.9.2342.19200300.100.1.56 NAME 'documentPublisher' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) The DirectoryString (1.3.6.1.4.1.1466.115.121.1.15) syntax and the 'caseIgnoreMatch' and 'caseIgnoreSubstringsMatch' rules are described in [RFC4517]. 2.9. documentTitle The 'documentTitle' attribute specifies the titles of a document. Multiple values are allowed to accommodate both long and short titles, or other situations where a document has multiple titles, for example, "The Lightweight Directory Access Protocol Technical Specification" and "The LDAP Technical Specification". ( 0.9.2342.19200300.100.1.12 NAME 'documentTitle' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{256} ) The DirectoryString (1.3.6.1.4.1.1466.115.121.1.15) syntax and the 'caseIgnoreMatch' and 'caseIgnoreSubstringsMatch' rules are described in [RFC4517]. 2.10. documentVersion The 'documentVersion' attribute specifies the version information of a document. ( 0.9.2342.19200300.100.1.13 NAME 'documentVersion' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{256} ) Zeilenga Standards Track [Page 7] RFC 4524 COSINE LDAP/X.500 Schema June 2006 The DirectoryString (1.3.6.1.4.1.1466.115.121.1.15) syntax and the 'caseIgnoreMatch' and 'caseIgnoreSubstringsMatch' rules are described in [RFC4517]. 2.11. drink The 'drink' (favoriteDrink) attribute specifies the favorite drinks of an object (or person), for instance, "cola" and "beer". ( 0.9.2342.19200300.100.1.5 NAME 'drink' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{256} ) The DirectoryString (1.3.6.1.4.1.1466.115.121.1.15) syntax and the 'caseIgnoreMatch' and 'caseIgnoreSubstringsMatch' rules are described in [RFC4517]. 2.12. homePhone The 'homePhone' (Home Telephone Number) attribute specifies home telephone numbers (e.g., "+1 775 555 1234") associated with a person. ( 0.9.2342.19200300.100.1.20 NAME 'homePhone' EQUALITY telephoneNumberMatch SUBSTR telephoneNumberSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.50 ) The telephoneNumber (1.3.6.1.4.1.1466.115.121.1.50) syntax and the 'telephoneNumberMatch' and 'telephoneNumberSubstringsMatch' rules are described in [RFC4517]. 2.13. homePostalAddress The 'homePostalAddress' attribute specifies home postal addresses for an object. Each value should be limited to up to 6 directory strings of 30 characters each. (Note: It is not intended that the directory service enforce these limits.) ( 0.9.2342.19200300.100.1.39 NAME 'homePostalAddress' EQUALITY caseIgnoreListMatch SUBSTR caseIgnoreListSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.41 ) The PostalAddress (1.3.6.1.4.1.1466.115.121.1.41) syntax and the 'caseIgnoreListMatch' and 'caseIgnoreListSubstringsMatch' rules are described in [RFC4517]. Zeilenga Standards Track [Page 8] RFC 4524 COSINE LDAP/X.500 Schema June 2006 2.14. host The 'host' attribute specifies host computers, generally by their primary fully qualified domain name (e.g., my-host.example.com). ( 0.9.2342.19200300.100.1.9 NAME 'host' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{256} ) The DirectoryString (1.3.6.1.4.1.1466.115.121.1.15) syntax and the 'caseIgnoreMatch' and 'caseIgnoreSubstringsMatch' rules are described in [RFC4517]. 2.15. info The 'info' attribute specifies any general information pertinent to an object. This information is not necessarily descriptive of the object. Applications should not attach specific semantics to values of this attribute. The 'description' attribute [RFC4519] is available for specifying descriptive information pertinent to an object. ( 0.9.2342.19200300.100.1.4 NAME 'info' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{2048} ) The DirectoryString (1.3.6.1.4.1.1466.115.121.1.15) syntax and the 'caseIgnoreMatch' and 'caseIgnoreSubstringsMatch' rules are described in [RFC4517]. 2.16. mail The 'mail' (rfc822mailbox) attribute type holds Internet mail addresses in Mailbox [RFC2821] form (e.g., user@example.com). ( 0.9.2342.19200300.100.1.3 NAME 'mail' EQUALITY caseIgnoreIA5Match SUBSTR caseIgnoreIA5SubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.26{256} ) The IA5String (1.3.6.1.4.1.1466.115.121.1.26) syntax and the 'caseIgnoreIA5Match' and 'caseIgnoreIA5SubstringsMatch' rules are described in [RFC4517]. Zeilenga Standards Track [Page 9] RFC 4524 COSINE LDAP/X.500 Schema June 2006 Note that the directory will not ensure that values of this attribute conform to the <Mailbox> production [RFC2821]. It is the application's responsibility to ensure that domains it stores in this attribute are appropriately represented. Additionally, the directory will compare values per the matching rules named in the above attribute type description. As these rules differ from rules that normally apply to <Mailbox> comparisons, operational issues may arise. For example, the assertion (mail=joe@example.com) will match "JOE@example.com" even though the <local-parts> differ. Also, where a user has two <Mailbox>es whose addresses differ only by case of the <local-part>, both cannot be listed as values of the user's mail attribute (as they are considered equal by the 'caseIgnoreIA5Match' rule). Also note that applications supporting internationalized domain names SHALL use the ToASCII method [RFC3490] to produce <sub-domain> components of the <Mailbox> production. 2.17. manager The 'manager' attribute specifies managers, by distinguished name, of the person (or entity). ( 0.9.2342.19200300.100.1.10 NAME 'manager' EQUALITY distinguishedNameMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 ) The DistinguishedName (1.3.6.1.4.1.1466.115.121.1.12) syntax and the 'distinguishedNameMatch' rule are described in [RFC4517]. 2.18. mobile The 'mobile' (mobileTelephoneNumber) attribute specifies mobile telephone numbers (e.g., "+1 775 555 6789") associated with a person (or entity). ( 0.9.2342.19200300.100.1.41 NAME 'mobile' EQUALITY telephoneNumberMatch SUBSTR telephoneNumberSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.50 ) The telephoneNumber (1.3.6.1.4.1.1466.115.121.1.50) syntax and the 'telephoneNumberMatch' and 'telephoneNumberSubstringsMatch' rules are described in [RFC4517]. Zeilenga Standards Track [Page 10] RFC 4524 COSINE LDAP/X.500 Schema June 2006 2.19. organizationalStatus The 'organizationalStatus' attribute specifies categories by which a person is often referred to in an organization. Examples of usage in academia might include "undergraduate student", "researcher", "professor", and "staff". Multiple values are allowed where the person is in multiple categories. Directory administrators and application designers SHOULD consider carefully the distinctions between this and the 'title' and 'userClass' attributes. ( 0.9.2342.19200300.100.1.45 NAME 'organizationalStatus' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{256} ) The DirectoryString (1.3.6.1.4.1.1466.115.121.1.15) syntax and the 'caseIgnoreMatch' and 'caseIgnoreSubstringsMatch' rules are described in [RFC4517]. 2.20. pager The 'pager' (pagerTelephoneNumber) attribute specifies pager telephone numbers (e.g., "+1 775 555 5555") for an object. ( 0.9.2342.19200300.100.1.42 NAME 'pager' EQUALITY telephoneNumberMatch SUBSTR telephoneNumberSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.50 ) The telephoneNumber (1.3.6.1.4.1.1466.115.121.1.50) syntax and the 'telephoneNumberMatch' and 'telephoneNumberSubstringsMatch' rules are described in [RFC4517]. 2.21. personalTitle The 'personalTitle' attribute specifies personal titles for a person. Examples of personal titles are "Frau", "Dr.", "Herr", and "Professor". ( 0.9.2342.19200300.100.1.40 NAME 'personalTitle' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{256} ) Zeilenga Standards Track [Page 11] RFC 4524 COSINE LDAP/X.500 Schema June 2006 The DirectoryString (1.3.6.1.4.1.1466.115.121.1.15) syntax and the 'caseIgnoreMatch' and 'caseIgnoreSubstringsMatch' rules are described in [RFC4517]. 2.22. roomNumber The 'roomNumber' attribute specifies the room number of an object. During periods of renumbering, or in other circumstances where a room has multiple valid room numbers associated with it, multiple values may be provided. Note that the 'cn' (commonName) attribute type SHOULD be used for naming room objects. ( 0.9.2342.19200300.100.1.6 NAME 'roomNumber' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{256} ) The DirectoryString (1.3.6.1.4.1.1466.115.121.1.15) syntax and the 'caseIgnoreMatch' and 'caseIgnoreSubstringsMatch' rules are described in [RFC4517]. 2.23. secretary The 'secretary' attribute specifies secretaries and/or administrative assistants, by distinguished name. ( 0.9.2342.19200300.100.1.21 NAME 'secretary' EQUALITY distinguishedNameMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 ) The DistinguishedName (1.3.6.1.4.1.1466.115.121.1.12) syntax and the 'distinguishedNameMatch' rule are described in [RFC4517]. 2.24. uniqueIdentifier The 'uniqueIdentifier' attribute specifies a unique identifier for an object represented in the Directory. The domain within which the identifier is unique and the exact semantics of the identifier are for local definition. For a person, this might be an institution- wide payroll number. For an organizational unit, it might be a department code. ( 0.9.2342.19200300.100.1.44 NAME 'uniqueIdentifier' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{256} ) Zeilenga Standards Track [Page 12] RFC 4524 COSINE LDAP/X.500 Schema June 2006 The DirectoryString (1.3.6.1.4.1.1466.115.121.1.15) syntax and the 'caseIgnoreMatch' and 'caseIgnoreSubstringsMatch' rules are described in [RFC4517]. Note: X.520 also describes an attribute called 'uniqueIdentifier' (2.5.4.45), which is called 'x500UniqueIdentifier' in LDAP [RFC4519]. The attribute detailed here ought not be confused with 'x500UniqueIdentifier'. 2.25. userClass The 'userClass' attribute specifies categories of computer or application user. The semantics placed on this attribute are for local interpretation. Examples of current usage of this attribute in academia are "student", "staff", and "faculty". Note that the 'organizationalStatus' attribute type is now often preferred, as it makes no distinction between persons as opposed to users. ( 0.9.2342.19200300.100.1.8 NAME 'userClass' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{256} ) The DirectoryString (1.3.6.1.4.1.1466.115.121.1.15) syntax and the 'caseIgnoreMatch' and 'caseIgnoreSubstringsMatch' rules are described in [RFC4517]. 3. COSINE Object Classes This section details COSINE object classes for use in LDAP. 3.1. account The 'account' object class is used to define entries representing computer accounts. The 'uid' attribute SHOULD be used for naming entries of this object class. ( 0.9.2342.19200300.100.4.5 NAME 'account' SUP top STRUCTURAL MUST uid MAY ( description $ seeAlso $ l $ o $ ou $ host ) ) The 'top' object class is described in [RFC4512]. The 'description', 'seeAlso', 'l', 'o', 'ou', and 'uid' attribute types are described in [RFC4519]. The 'host' attribute type is described in Section 2 of this document. Zeilenga Standards Track [Page 13] RFC 4524 COSINE LDAP/X.500 Schema June 2006 3.3. documentSeriesExample: dn: uid=kdz,cn=Accounts,dc=Example,dc=COM objectClass: account uid: kdz seeAlso: cn=Kurt D. Zeilenga,cn=Persons,dc=Example,dc=COM 3.2. document The 'document' object class is used to define entries that represent documents. ( 0.9.2342.19200300.100.4.6 NAME 'document' SUP top STRUCTURAL MUST documentIdentifier MAY ( cn $ description $ seeAlso $ l $ o $ ou $ documentTitle $ documentVersion $ documentAuthor $ documentLocation $ documentPublisher ) ) The 'top' object class is described in [RFC4512]. The 'cn', 'description', 'seeAlso', 'l', 'o', and 'ou' attribute types are described in [RFC4519]. The 'documentIdentifier', 'documentTitle', 'documentVersion', 'documentAuthor', 'documentLocation', and 'documentPublisher' attribute types are described in Section 2 of this document. Example: dn: documentIdentifier=RFC 4524,cn=RFC,dc=Example,dc=COM objectClass: document documentIdentifier: RFC 4524 documentTitle: COSINE LDAP/X.500 Schema documentAuthor: cn=Kurt D. Zeilenga,cn=Persons,dc=Example,dc=COM documentLocation: http://www.rfc-editor.org/rfc/rfc4524.txt documentPublisher: Internet Engineering Task Force description: A collection of schema elements for use in LDAP description: Obsoletes RFC 1274 seeAlso: documentIdentifier=RFC 4510,cn=RFC,dc=Example,dc=COM seeAlso: documentIdentifier=RFC 1274,cn=RFC,dc=Example,dc=COM 3.3. documentSeries The 'documentSeries' object class is used to define an entry that represents a series of documents (e.g., The Request For Comments memos). Zeilenga Standards Track [Page 14] RFC 4524 COSINE LDAP/X.500 Schema June 2006 ( 0.9.2342.19200300.100.4.9 NAME 'documentSeries' SUP top STRUCTURAL MUST cn MAY ( description $ l $ o $ ou $ seeAlso $ telephonenumber ) ) The 'top' object class is described in [RFC4512]. The 'description', 'l', 'o', 'ou', 'seeAlso', and 'telephoneNumber' attribute types are described in [RFC4519]. Example: dn: cn=RFC,dc=Example,dc=COM objectClass: documentSeries cn: Request for Comments cn: RFC description: a series of memos about the Internet 3.4. domain The 'domain' object class is used to define entries that represent DNS domains for objects that are not organizations, organizational units, or other kinds of objects more appropriately defined using an object class specific to the kind of object being defined (e.g., 'organization', 'organizationUnit'). The 'dc' attribute should be used for naming entries of the 'domain' object class. ( 0.9.2342.19200300.100.4.13 NAME 'domain' SUP top STRUCTURAL MUST dc MAY ( userPassword $ searchGuide $ seeAlso $ businessCategory $ x121Address $ registeredAddress $ destinationIndicator $ preferredDeliveryMethod $ telexNumber $ teletexTerminalIdentifier $ telephoneNumber $ internationaliSDNNumber $ facsimileTelephoneNumber $ street $ postOfficeBox $ postalCode $ postalAddress $ physicalDeliveryOfficeName $ st $ l $ description $ o $ associatedName ) ) The 'top' object class and the 'dc', 'userPassword', 'searchGuide', 'seeAlso', 'businessCategory', 'x121Address', 'registeredAddress', 'destinationIndicator', 'preferredDeliveryMethod', 'telexNumber', 'teletexTerminalIdentifier', 'telephoneNumber', 'internationaliSDNNumber', 'facsimileTelephoneNumber', 'street', 'postOfficeBox', 'postalCode', 'postalAddress', 'physicalDeliveryOfficeName', 'st', 'l', 'description', and 'o' types Zeilenga Standards Track [Page 15] RFC 4524 COSINE LDAP/X.500 Schema June 2006 are described in [RFC4519]. The 'associatedName' attribute type is described in Section 2 of this document. Example: dn: dc=com objectClass: domain dc: com description: the .COM TLD 3.5. domainRelatedObject The 'domainRelatedObject' object class is used to define entries that represent DNS domains that are "equivalent" to an X.500 domain, e.g., an organization or organizational unit. ( 0.9.2342.19200300.100.4.17 NAME 'domainRelatedObject' SUP top AUXILIARY MUST associatedDomain ) The 'top' object class is described in [RFC4512]. The 'associatedDomain' attribute type is described in Section 2 of this document. Example: dn: dc=example,dc=com objectClass: organization objectClass: dcObject objectClass: domainRelatedObject dc: example associatedDomain: example.com o: Example Organization The 'organization' and 'dcObject' object classes and the 'dc' and 'o' attribute types are described in [RFC4519]. 3.6. friendlyCountry The 'friendlyCountry' object class is used to define entries representing countries in the DIT. The object class is used to allow friendlier naming of countries than that allowed by the object class 'country' [RFC4519]. ( 0.9.2342.19200300.100.4.18 NAME 'friendlyCountry' SUP country STRUCTURAL MUST co ) Zeilenga Standards Track [Page 16] RFC 4524 COSINE LDAP/X.500 Schema June 2006 The 'country' object class is described in [RFC4519]. The 'co' attribute type is described in Section 2 of this document. Example: dn: c=DE objectClass: country objectClass: friendlyCountry c: DE co: Deutschland co: Germany co: Federal Republic of Germany co: FRG The 'c' attribute type is described in [RFC4519]. 3.7. rFC822LocalPart The 'rFC822LocalPart' object class is used to define entries that represent the local part of Internet mail addresses [RFC2822]. This treats the local part of the address as a 'domain' object. ( 0.9.2342.19200300.100.4.14 NAME 'rFC822localPart' SUP domain STRUCTURAL MAY ( cn $ description $ destinationIndicator $ facsimileTelephoneNumber $ internationaliSDNNumber $ physicalDeliveryOfficeName $ postalAddress $ postalCode $ postOfficeBox $ preferredDeliveryMethod $ registeredAddress $ seeAlso $ sn $ street $ telephoneNumber $ teletexTerminalIdentifier $ telexNumber $ x121Address ) ) The 'domain' object class is described in Section 3.4 of this document. The 'cn', 'description', 'destinationIndicator', 'facsimileTelephoneNumber', 'internationaliSDNNumber, 'physicalDeliveryOfficeName', 'postalAddress', 'postalCode', 'postOfficeBox', 'preferredDeliveryMethod', 'registeredAddress', 'seeAlso', 'sn, 'street', 'telephoneNumber', 'teletexTerminalIdentifier', 'telexNumber', and 'x121Address' attribute types are described in [RFC4519]. Example: dn: dc=kdz,dc=example,dc=com objectClass: domain objectClass: rFC822LocalPart dc: kdz associatedName: cn=Kurt D. Zeilenga,cn=Persons,dc=Example,dc=COM Zeilenga Standards Track [Page 17] RFC 4524 COSINE LDAP/X.500 Schema June 2006 The 'dc' attribute type is described in [RFC4519]. 3.8. room The 'room' object class is used to define entries representing rooms. The 'cn' (commonName) attribute SHOULD be used for naming entries of this object class. ( 0.9.2342.19200300.100.4.7 NAME 'room' SUP top STRUCTURAL MUST cn MAY ( roomNumber $ description $ seeAlso $ telephoneNumber ) ) The 'top' object class is described in [RFC4512]. The 'cn', 'description', 'seeAlso', and 'telephoneNumber' attribute types are described in [RFC4519]. The 'roomNumber' attribute type is described in Section 2 of this document. dn: cn=conference room,dc=example,dc=com objectClass: room cn: conference room telephoneNumber: +1 755 555 1111 3.9. simpleSecurityObject The 'simpleSecurityObject' object class is used to require an entry to have a 'userPassword' attribute when the entry's structural object class does not require (or allow) the 'userPassword attribute'. ( 0.9.2342.19200300.100.4.19 NAME 'simpleSecurityObject' SUP top AUXILIARY MUST userPassword ) The 'top' object class is described in [RFC4512]. The 'userPassword' attribute type is described in [RFC4519]. dn: dc=kdz,dc=Example,dc=COM objectClass: account objectClass: simpleSecurityObject uid: kdz userPassword: My Password seeAlso: cn=Kurt D. Zeilenga,cn=Persons,dc=Example,dc=COM 4. Security Considerations General LDAP security considerations [RFC4510] are applicable to the use of this schema. Additional considerations are noted above where appropriate. Zeilenga Standards Track [Page 18] RFC 4524 COSINE LDAP/X.500 Schema June 2006 Directories administrators should ensure that access to sensitive information be restricted to authorized entities and that appropriate data security services, including data integrity and data confidentiality, are used to protect against eavesdropping. Simple authentication (e.g., plain text passwords) mechanisms should only be used when adequate data security services are in place. LDAP offers reasonably strong authentication and data security services [RFC4513]. 5. IANA Considerations The Internet Assigned Numbers Authority (IANA) has updated the LDAP descriptors registry [RFC4520] as indicated in the following template: Subject: Request for LDAP Descriptor Registration Update Descriptor (short name): see comment Object Identifier: see comments Person & email address to contact for further information: Kurt Zeilenga <kurt@OpenLDAP.org> Usage: see comments Specification: RFC 4524 Author/Change Controller: IESG Comments: The following descriptors have been updated to refer to RFC 4524. NAME Type OID ------------------------ ---- -------------------------- account O 0.9.2342.19200300.100.4.5 associatedDomain A 0.9.2342.19200300.100.1.37 associatedName A 0.9.2342.19200300.100.1.38 buildingName A 0.9.2342.19200300.100.1.48 co A 0.9.2342.19200300.100.1.43 document O 0.9.2342.19200300.100.4.6 documentAuthor A 0.9.2342.19200300.100.1.14 documentIdentifier A 0.9.2342.19200300.100.1.11 documentLocation A 0.9.2342.19200300.100.1.15 documentPublisher A 0.9.2342.19200300.100.1.56 documentSeries O 0.9.2342.19200300.100.4.8 documentTitle A 0.9.2342.19200300.100.1.12 documentVersion A 0.9.2342.19200300.100.1.13 domain O 0.9.2342.19200300.100.4.13 domainRelatedObject O 0.9.2342.19200300.100.4.17 drink A 0.9.2342.19200300.100.1.5 favouriteDrink A* 0.9.2342.19200300.100.1.5 friendlyCountry O 0.9.2342.19200300.100.4.18 Zeilenga Standards Track [Page 19] RFC 4524 COSINE LDAP/X.500 Schema June 2006 friendlyCountryName A* 0.9.2342.19200300.100.1.43 homePhone A 0.9.2342.19200300.100.1.20 homePostalAddress A 0.9.2342.19200300.100.1.39 homeTelephone A* 0.9.2342.19200300.100.1.20 host A 0.9.2342.19200300.100.1.9 info A 0.9.2342.19200300.100.1.4 mail A 0.9.2342.19200300.100.1.3 manager A 0.9.2342.19200300.100.1.10 mobile A 0.9.2342.19200300.100.1.41 mobileTelephoneNumber A* 0.9.2342.19200300.100.1.41 organizationalStatus A 0.9.2342.19200300.100.1.45 pager A 0.9.2342.19200300.100.1.42 pagerTelephoneNumber A* 0.9.2342.19200300.100.1.42 personalTitle A 0.9.2342.19200300.100.1.40 rFC822LocalPart O 0.9.2342.19200300.100.4.14 rfc822Mailbox A* 0.9.2342.19200300.100.1.3 room O 0.9.2342.19200300.100.4.7 roomNumber A 0.9.2342.19200300.100.1.6 secretary A 0.9.2342.19200300.100.1.21 simpleSecurityObject O 0.9.2342.19200300.100.4.19 singleLevelQuality A 0.9.2342.19200300.100.1.50 uniqueIdentifier A 0.9.2342.19200300.100.1.44 userClass A 0.9.2342.19200300.100.1.8 where Type A is Attribute, Type O is ObjectClass, and * indicates that the registration is historic in nature. 6. Acknowledgements This document is based on RFC 1274, by Paul Barker and Steve Kille, as well as on RFC 2247, by Steve Kill, Mark Wahl, Al Grimstad, Rick Huber, and Sri Satulari. 7. References 7.1. Normative References [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", STD 13, RFC 1034, November 1987. [RFC1123] Braden, R., "Requirements for Internet Hosts - Application and Support", STD 3, RFC 1123, October 1989. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. Zeilenga Standards Track [Page 20] RFC 4524 COSINE LDAP/X.500 Schema June 2006 [RFC2181] Elz, R. and R. Bush, "Clarifications to the DNS Specification", RFC 2181, July 1997. [RFC2247] Kille, S., Wahl, M., Grimstad, A., Huber, R., and S. Sataluri, "Using Domains in LDAP/X.500 Distinguished Names", RFC 2247, January 1998. [RFC2821] Klensin, J., Ed., "Simple Mail Transfer Protocol", RFC 2821, April 2001. [RFC2822] Resnick, P., "Internet Message Format", RFC 2822, April 2001. [RFC3490] Faltstrom, P., Hoffman, P., and A. Costello, "Internationalizing Domain Names in Applications (IDNA)", RFC 3490, March 2003. [RFC4510] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006. [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006. [RFC4513] Harrison, R., "Lightweight Directory Access Protocol (LDAP): Authentication Methods and Security Mechanisms", RFC 4513, June 2006. [RFC4517] Legg, S., Ed., "Lightweight Directory Access Protocol (LDAP): Syntaxes and Matching Rules", RC 4517, June 2006. [RFC4519] Sciberras, A., Ed., "Lightweight Directory Access Protocol (LDAP): Schema for User Applications", RFC 4519, June 2006. [X.501] International Telecommunication Union - Telecommunication Standardization Sector, "The Directory -- Models," X.501(1993) (also ISO/IEC 9594- 2:1994). 7.2. Informative References [COSINEpilot] Goodman, D., "PARADISE" section of the March 1991 INTERNET MONTHLY REPORTS (p. 28-29), http://www.iana.org/periodic-reports/imr-mar91.txt Zeilenga Standards Track [Page 21] RFC 4524 COSINE LDAP/X.500 Schema June 2006 [ISO3166] International Organization for Standardization, "Codes for the representation of names of countries", ISO 3166. [RFC1274] Barker, P. and S. Kille, "The COSINE and Internet X.500 Schema", RFC 1274, November 1991. [RFC1279] Hardcastle-Kille, S., "X.500 and Domains", RFC 1279, November 1991. [RFC1487] Yeong, W., Howes, T., and S. Kille, "X.500 Lightweight Directory Access Protocol", RFC 1487, July 1993. [RFC2251] Wahl, M., Howes, T., and S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [RFC2798] Smith, M., "Definition of the inetOrgPerson LDAP Object Class", RFC 2798, April 2000. [RFC3494] Zeilenga, K., "Lightweight Directory Access Protocol version 2 (LDAPv2) to Historic Status", RFC 3494, March 2003. [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 4520. Zeilenga Standards Track [Page 22] RFC 4524 COSINE LDAP/X.500 Schema June 2006 Appendix A. Changes since RFC 1274 This document represents a substantial rewrite of RFC 1274. The following sections summarize the substantive changes. A.1. LDAP Short Names A number of COSINE attribute types have short names in LDAP. X.500 Name LDAP Short Name ------------- --------------- domainComponent dc favoriteDrink drink friendCountryName co homeTelephoneNumber homePhone mobileTelephoneNumber mobile pagerTelephoneNumber pager rfc822Mailbox mail userid uid While the LDAP short names are generally used in LDAP, some implementations may (for legacy reasons [RFC3494]) recognize the attribute type by its X.500 name. Hence, the X.500 names have been reserved solely for this purpose. Note: 'uid' and 'dc' are described in [RFC4519]. A.2. pilotObject The 'pilotObject' object class was not brought forward as its function is largely replaced by operational attributes introduced in X.500(93) [X.501] and version 3 of LDAP [RFC4512]. For instance, the function of the 'lastModifiedBy' and 'lastModifiedTime' attribute types is now served by the 'creatorsName', 'createTimestamp', 'modifiersName', and 'modifyTimestamp' operational attributes [RFC4512]. A.3. pilotPerson The 'pilotPerson' object class was not brought forward as its function is largely replaced by the 'organizationalPerson' [RFC4512] object class and its subclasses, such as 'inetOrgPerson' [RFC2798]. Most of the related attribute types (e.g., 'mail', 'manager') were brought forward as they are used in other object classes. Zeilenga Standards Track [Page 23] RFC 4524 COSINE LDAP/X.500 Schema June 2006 A.4. dNSDomain The 'dNSDomain' object class and related attribute types were not brought forward as its use is primarily experimental [RFC1279]. A.5. pilotDSA and qualityLabelledData The 'pilotDSA' and 'qualityLabelledData' object classes, as well as related attribute types, were not brought forward as its use is primarily experimental [QoS]. A.6. Attribute Syntaxes RFC 1274 defined and used caseIgnoreIA5StringSyntax attribute syntax. This has been replaced with the IA5String syntax and appropriate matching rules in 'mail' and 'associatedDomain'. RFC 1274 restricted 'mail' to have non-zero length values. This restriction is not reflected in the IA5String syntax used in the definitions provided in this specification. However, as values are to conform to the <Mailbox> production, the 'mail' should not contain zero-length values. Unfortunately, the directory service will not enforce this restriction. Appendix B. Changes since RFC 2247 The 'domainNameForm' name form was not brought forward as specification of name forms used in LDAP is left to a future specification. Editor's Address Kurt D. Zeilenga OpenLDAP Foundation EMail: Kurt@OpenLDAP.org Zeilenga Standards Track [Page 24] RFC 4524 COSINE LDAP/X.500 Schema June 2006 Full Copyright Statement Copyright (C) The Internet Society (2006). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Zeilenga Standards Track [Page 25] PK )�c\��[� � ( doc/alt-openldap11-devel/rfc/rfc3928.txtnu �[��� Network Working Group R. Megginson, Ed. Request for Comments: 3928 Netscape Communications Corp. Category: Standards Track M. Smith Pearl Crescent, LLC O. Natkovich Yahoo J. Parham Microsoft Corporation October 2004 Lightweight Directory Access Protocol (LDAP) Client Update Protocol (LCUP) Status of this Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2004). Abstract This document defines the Lightweight Directory Access Protocol (LDAP) Client Update Protocol (LCUP). The protocol is intended to allow an LDAP client to synchronize with the content of a directory information tree (DIT) stored by an LDAP server and to be notified about the changes to that content. Megginson, et al. Standards Track [Page 1] RFC 3928 LDAP Client Update Protocol October 2004 Table of Contents 1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Applicability. . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Specification of Protocol Elements . . . . . . . . . . . . . . 5 3.1. ASN.1 Considerations . . . . . . . . . . . . . . . . . . 5 3.2. Universally Unique Identifiers . . . . . . . . . . . . . 5 3.3. LCUP Scheme and LCUP Cookie. . . . . . . . . . . . . . . 5 3.4. LCUP Context . . . . . . . . . . . . . . . . . . . . . . 6 3.5. Additional LDAP Result Codes defined by LCUP . . . . . . 6 3.6. Sync Request Control . . . . . . . . . . . . . . . . . . 7 3.7. Sync Update Control. . . . . . . . . . . . . . . . . . . 7 3.8. Sync Done Control. . . . . . . . . . . . . . . . . . . . 8 4. Protocol Usage and Flow. . . . . . . . . . . . . . . . . . . . 8 4.1. LCUP Search Requests . . . . . . . . . . . . . . . . . . 8 4.1.1. Initial Synchronization and Full Resync . . . . . 9 4.1.2. Incremental or Update Synchronization . . . . . . 10 4.1.3. Persistent Only . . . . . . . . . . . . . . . . . 10 4.2. LCUP Search Responses. . . . . . . . . . . . . . . . . . 10 4.2.1. Sync Update Informational Responses . . . . . . . 11 4.2.2. Cookie Return Frequency . . . . . . . . . . . . . 11 4.2.3. Definition of an Entry That Has Entered the Result Set. . . . . . . . . . . . . . . . . . . . 12 4.2.4. Definition of an Entry That Has Changed . . . . . 13 4.2.5. Definition of an Entry That Has Left the Result Set. . . . . . . . . . . . . . . . . . . . 13 4.2.6. Results For Entries Present in the Result Set . . 14 4.2.7. Results For Entries That Have Left the Result Set . . . . . . . . . . . . . . . . . . . . . . . 14 4.3. Responses Requiring Special Consideration . . . . . . . . 15 4.3.1. Returning Results During the Persistent Phase . . 15 4.3.2. No Mixing of Sync Phase with Persist Phase. . . . 16 4.3.3. Returning Updated Results During the Sync Phase . 16 4.3.4. Operational Attributes and Administrative Entries . . . . . . . . . . . . . . . . . . . . . 16 4.3.5. Virtual Attributes. . . . . . . . . . . . . . . . 17 4.3.6. Modify DN and Delete Operations Applied to Subtrees. . . . . . . . . . . . . . . . . . . . . 17 4.3.7. Convergence Guarantees. . . . . . . . . . . . . . 18 4.4. LCUP Search Termination. . . . . . . . . . . . . . . . . 18 4.4.1. Server Initiated Termination. . . . . . . . . . . 18 4.4.2. Client Initiated Termination. . . . . . . . . . . 19 4.5. Size and Time Limits . . . . . . . . . . . . . . . . . . 19 4.6. Operations on the Same Connection. . . . . . . . . . . . 19 4.7. Interactions with Other Controls . . . . . . . . . . . . 19 4.8. Replication Considerations . . . . . . . . . . . . . . . 20 5. Client Side Considerations . . . . . . . . . . . . . . . . . . 20 5.1. Using Cookies with Different Search Criteria . . . . . . 20 Megginson, et al. Standards Track [Page 2] RFC 3928 LDAP Client Update Protocol October 2004 5.2. Renaming the Base Object . . . . . . . . . . . . . . . . 20 5.3. Use of Persistent Searches With Respect to Resources . . 21 5.4. Continuation References to Other LCUP Contexts . . . . . 21 5.5. Referral Handling. . . . . . . . . . . . . . . . . . . . 21 5.6. Multiple Copies of Same Entry During Sync Phase. . . . . 21 5.7. Handling Server Out of Resources Condition . . . . . . . 21 6. Server Implementation Considerations . . . . . . . . . . . . . 22 6.1. Server Support for UUIDs . . . . . . . . . . . . . . . . 22 6.2. Example of Using an RUV as the Cookie Value. . . . . . . 22 6.3. Cookie Support Issues. . . . . . . . . . . . . . . . . . 22 6.3.1. Support for Multiple Cookie Schemes . . . . . . . 22 6.3.2. Information Contained in the Cookie . . . . . . . 23 6.4. Persist Phase Response Time. . . . . . . . . . . . . . . 23 6.5. Scaling Considerations . . . . . . . . . . . . . . . . . 23 6.6. Alias Dereferencing. . . . . . . . . . . . . . . . . . . 24 7. Synchronizing Heterogeneous Data Stores. . . . . . . . . . . . 24 8. IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 24 9. Security Considerations. . . . . . . . . . . . . . . . . . . . 24 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 25 10.1. Normative References . . . . . . . . . . . . . . . . . . 25 10.2. Informative References . . . . . . . . . . . . . . . . . 26 11. Acknowledgments. . . . . . . . . . . . . . . . . . . . . . . . 26 Appendix - Features Left Out of LCUP . . . . . . . . . . . . . . . 27 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 29 Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 30 1. Overview The LCUP protocol is intended to allow LDAP clients to synchronize with the content stored by LDAP servers. The problem areas addressed by the protocol include: - Mobile clients that maintain a local read-only copy of the directory data. While off-line, the client uses the local copy of the data. When the client connects to the network, it synchronizes with the current directory content and can optionally receive notification about the changes that occur while it is on- line. For example, a mail client can maintain a local copy of the corporate address book that it synchronizes with the master copy whenever the client is connected to the corporate network. - Applications intending to synchronize heterogeneous data stores. A meta directory application, for instance, would periodically retrieve a list of modified entries from the directory, construct the changes and apply them to a foreign data store. Megginson, et al. Standards Track [Page 3] RFC 3928 LDAP Client Update Protocol October 2004 - Clients that need to take certain actions when a directory entry is modified. For instance, an electronic mail repository may want to perform a "create mailbox" task when a new person entry is added to an LDAP directory and a "delete mailbox" task when a person entry is removed. The problem areas not being considered: - Directory server to directory server synchronization. The IETF is developing a LDAP replication protocol, called LDUP [RFC3384], which is specifically designed to address this problem area. There are currently several protocols in use for LDAP client server synchronization. While each protocol addresses the needs of a particular group of clients (e.g., on-line clients or off-line clients), none satisfies the requirements of all clients in the target group. For instance, a mobile client that was off-line and wants to become up to date with the server and stay up to date while connected can't be easily supported by any of the existing protocols. LCUP is designed such that the server does not need to maintain state information specific to individual clients. The server may need to maintain additional state information about attribute modifications, deleted entries, and moved/renamed entries. The clients are responsible for storing the information about how up to date they are with respect to the server's content. LCUP design avoids the need for LCUP-specific update agreements to be made between client and server prior to LCUP use. The client decides when and from where to retrieve the changes. LCUP design requires clients to initiate the update session and "pull" the changes from server. LCUP operations are subject to administrative and access control policies enforced by the server. 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 [RFC2119]. 2. Applicability LCUP will work best if the following conditions are met: 1) The server stores some degree of historical state or change information to reduce the amount of wire traffic required for incremental synchronizations. The optimal balance between server state and wire traffic varies amongst implementations and usage scenarios, and is therefore left in the hands of implementers. Megginson, et al. Standards Track [Page 4] RFC 3928 LDAP Client Update Protocol October 2004 2) The client cannot be assumed to understand the physical information model (virtual attributes, operational attributes, subentries, etc.) implemented by the server. Optimizations would be possible if such assumptions could be made. 3) Meta data changes and renames and deletions of large subtrees are very infrequent. LCUP makes these assumptions in order to reduce client complexity required to deal with these special operations, though when they do occur they may result in a large number of incremental update messages or a full resync. 3. Specification of Protocol Elements The following sections define the new elements required to use this protocol. 3.1. ASN.1 Considerations Protocol elements are described using ASN.1 [X.680]. The term "BER- encoded" means the element is to be encoded using the Basic Encoding Rules [X.690] under the restrictions detailed in Section 5.1 of [RFC2251]. All ASN.1 in this document uses implicit tags. 3.2. Universally Unique Identifiers Distinguished names can change, so are therefore unreliable as identifiers. A Universally Unique Identifier (or UUID for short) MUST be used to uniquely identify entries used with LCUP. The UUID is part of the Sync Update control value (see below) returned with each search result. The server SHOULD provide the UUID as a single valued operational attribute of the entry (e.g., "entryUUID"). We RECOMMEND that the server provides a way to do efficient (i.e., indexed) searches for values of UUID, e.g., by using a search filter like (entryUUID=<some UUID value>) to quickly search for and retrieve an entry based on its UUID. Servers SHOULD use a UUID format as specified in [UUID]. The UUID used by LCUP is a value of the following ASN.1 type: LCUPUUID ::= OCTET STRING 3.3. LCUP Scheme and LCUP Cookie The LCUP protocol uses a cookie to hold the state of the client's data with respect to the server's data. Each cookie format is uniquely identified by its scheme. The LCUP Scheme is a value of the following ASN.1 type: LCUPScheme ::= LDAPOID Megginson, et al. Standards Track [Page 5] RFC 3928 LDAP Client Update Protocol October 2004 This is the OID which identifies the format of the LCUP Cookie value. The scheme OID, as all object identifiers, MUST be unique for a given cookie scheme. The cookie value may be opaque or it may be exposed to LCUP clients. For cookie schemes that expose their value, the preferred form of documentation is an RFC. It is expected that there will be one or more standards track cookie schemes where the value format is exposed and described in detail. The LCUP Cookie is a value of the following ASN.1 type: LCUPCookie ::= OCTET STRING This is the actual data describing the state of the client's data. This value may be opaque, or its value may have some well-known format, depending on the scheme. Further uses of the LCUP Cookie value are described below. 3.4. LCUP Context A part of the DIT which is enabled for LCUP is referred to as an LCUP Context. A server may support one or more LCUP Contexts. For example, a server with two naming contexts may support LCUP in one naming context but not the other, or support different LCUP cookie schemes in each naming context. Each LCUP Context MAY use a different cookie scheme. An LCUP search will not cross an LCUP Context boundary, but will instead return a SearchResultReference message, with the LDAP URL specifying the same host and port as currently being searched, and with the baseDN set to the baseDN of the new LCUP Context. The client is then responsible for issuing another search using the new baseDN, and possibly a different cookie if that LCUP Context uses a different cookie. The client is responsible for maintaining a mapping of the LDAP URL to its corresponding cookie. 3.5. Additional LDAP Result Codes defined by LCUP Implementations of this specification SHALL recognize the following additional resultCode values. The LDAP result code names and numbers defined in the following table have been assigned by IANA per RFC 3383 [RFC3383]. lcupResourcesExhausted (113) the server is running out of resources lcupSecurityViolation (114) the client is suspected of malicious actions lcupInvalidData (115) invalid scheme or cookie was supplied by the client Megginson, et al. Standards Track [Page 6] RFC 3928 LDAP Client Update Protocol October 2004 lcupUnsupportedScheme (116) The cookie scheme is a valid OID but is not supported by this server lcupReloadRequired (117) indicates that client data needs to be reinitialized. This reason is returned if the server does not contain sufficient information to synchronize the client or if the server's data was reloaded since the last synchronization session The uses of these codes are described below. 3.6. Sync Request Control The Sync Request Control is an LDAP Control [RFC2251, Section 4.1.2] where the controlType is the object identifier 1.3.6.1.1.7.1 and the controlValue, an OCTET STRING, contains a BER-encoded syncRequestControlValue. syncRequestControlValue ::= SEQUENCE { updateType ENUMERATED { syncOnly (0), syncAndPersist (1), persistOnly (2) }, sendCookieInterval [0] INTEGER OPTIONAL, scheme [1] LCUPScheme OPTIONAL, cookie [2] LCUPCookie OPTIONAL } sendCookieInterval - the server SHOULD send the cookie back in the Sync Update control value (defined below) for every sendCookieInterval number of SearchResultEntry and SearchResultReference PDUs returned to the client. For example, if the value is 5, the server SHOULD send the cookie back in the Sync Update control value for every 5 search results returned to the client. If this value is absent, zero or less than zero, the server chooses the interval. The Sync Request Control is only applicable to the searchRequest message. Use of this control is described below. 3.7. Sync Update Control The Sync Update Control is an LDAP Control [RFC2251, Section 4.1.2] where the controlType is the object identifier 1.3.6.1.1.7.2 and the controlValue, an OCTET STRING, contains a BER-encoded syncUpdateControlValue. Megginson, et al. Standards Track [Page 7] RFC 3928 LDAP Client Update Protocol October 2004 syncUpdateControlValue ::= SEQUENCE { stateUpdate BOOLEAN, entryUUID [0] LCUPUUID OPTIONAL, -- REQUIRED for entries -- UUIDAttribute [1] AttributeType OPTIONAL, entryLeftSet [2] BOOLEAN, persistPhase [3] BOOLEAN, scheme [4] LCUPScheme OPTIONAL, cookie [5] LCUPCookie OPTIONAL } The field UUIDAttribute contains the name or OID of the attribute that the client should use to perform searches for entries based on the UUID. The client should be able to use it in an equality search filter, e.g., "(<uuid attribute>=<entry UUID value>)" and should be able to use it in the attribute list of the search request to return its value. The UUIDAttribute field may be omitted if the server does not support searching on the UUID values. The Sync Update Control is only applicable to SearchResultEntry and SearchResultReference messages. Although entryUUID is OPTIONAL, it MUST be used with SearchResultEntry messages. Use of this control is described below. 3.8. Sync Done Control The Sync Done Control is an LDAP Control [RFC2251, Section 4.1.2] where the controlType is the object identifier 1.3.6.1.1.7.3 and the controlValue contains a BER-encoded syncDoneValue. syncDoneValue ::= SEQUENCE { scheme [0] LCUPScheme OPTIONAL, cookie [1] LCUPCookie OPTIONAL } The Sync Done Control is only applicable to SearchResultDone message. Use of this control is described below. 4. Protocol Usage and Flow 4.1. LCUP Search Requests A client initiates a synchronization or persistent search session with a server by attaching a Sync Request control to an LDAP searchRequest message. The search specification determines the part of the directory information tree (DIT) the client wishes to synchronize with, the set of attributes it is interested in and the amount of data the client is willing to receive. The Sync Request control contains the client's request specification. Megginson, et al. Standards Track [Page 8] RFC 3928 LDAP Client Update Protocol October 2004 If there is an error condition, the server MUST immediately return a SearchResultDone message with the resultCode set to an error code. This table maps a condition to its corresponding behavior and resultCode. Condition Behavior or resultCode Sync Request Control is not Server behaves as [RFC2251, Section supported 4.1.2] - specifically, if the criticality of the control is FALSE, the server will process the request as a normal search request Scheme is not supported lcupUnsupportedScheme A control value field is lcupInvalidData invalid (e.g., illegal updateType, or the scheme is not a valid OID, or the cookie is invalid) Server is running out of lcupResourcesExhausted resources Server suspects client of lcupSecurityViolation malicious behavior (frequent connects/disconnects, etc.) The server cannot bring the lcupReloadRequired client up to date (server data has been reloaded, or other changes prevent convergence) 4.1.1. Initial Synchronization and Full Resync For an initial synchronization or full resync, the fields of the Sync Request control MUST be specified as follows: updateType - MUST be set to syncOnly or syncAndPersist sendCookieInterval - MAY be set scheme - MAY be set - if set, the server MUST use this specified scheme or return lcupUnsupportedScheme (see above) - if not set, the server MAY use any scheme it supports. cookie - MUST NOT be set Megginson, et al. Standards Track [Page 9] RFC 3928 LDAP Client Update Protocol October 2004 If the request was successful, the client will receive results as described in the section "LCUP Search Responses" below. 4.1.2. Incremental or Update Synchronization For an incremental or update synchronization, the fields of the Sync Request control MUST be specified as follows: updateType - MUST be set to syncOnly or syncAndPersist sendCookieInterval - MAY be set scheme - MUST be set cookie - MUST be set The client SHOULD always use the latest cookie it received from the server. If the request was successful, the client will receive results as described in the section "LCUP Search Responses" below. 4.1.3. Persistent Only For persistent only search request, the fields of the Sync Request MUST be specified as follows: updateType - MUST be set to persistOnly sendCookieInterval - MAY be set scheme - MAY be set - if set, the server MUST use this specified scheme or return lcupUnsupportedScheme (see above) - if not set, the server MAY use any scheme it supports. cookie - MAY be set, but the server MUST ignore it If the request was successful, the client will receive results as described in the section "LCUP Search Responses" below. 4.2. LCUP Search Responses In response to the client's LCUP request, the server returns zero or more SearchResultEntry or SearchResultReference PDUs that fit the client's specification, followed by a SearchResultDone PDU. The behavior is as specified in [RFC2251 Section 4.5]. Each SearchResultEntry or SearchResultReference PDU also contains a Sync Update control that describes the LCUP state of the returned entry. The SearchResultDone PDU contains a Sync Done control. The following sections specify behaviors in addition to [RFC2251 Section 4.5]. Megginson, et al. Standards Track [Page 10] RFC 3928 LDAP Client Update Protocol October 2004 4.2.1 Sync Update Informational Responses The server may use the Sync Update control to return information not related to a particular entry. It MAY do this at any time to return a cookie to the client, or to inform the client that the sync phase of a syncAndPersist search is complete and the persist phase has begun. It MAY do this during the persist phase even though no entry has changed that would have normally triggered a response. In order to do this, it is REQUIRED to return the following: - A SearchResultEntry PDU with the objectName field set to the DN of the baseObject of the search request and with an empty attribute list. - A Sync Update control value with the fields set to the following: stateUpdate - MUST be set to TRUE entryUUID - SHOULD be set to the UUID of the baseObject of the search request entryLeftSet - MUST be set to FALSE persistPhase - MUST be FALSE if the search is in the sync phase of a request, and MUST be TRUE if the search is in the persist phase UUIDAttribute - SHOULD only be set if this is either the first result returned or if the attribute has changed scheme - MUST be set if the cookie is set and the cookie format has changed; otherwise, it MAY be omitted cookie - SHOULD be set If the server merely wants to return a cookie to the client, it should return as above with the cookie field set. During a syncAndPersist request, the server MUST return (as above) immediately after the last entry of the sync phase has been sent and before the first entry of the persist phase has been sent. In this case, the persistPhase field MUST be set to TRUE. This allows the client to know that the sync phase is complete and the persist phase is starting. 4.2.2 Cookie Return Frequency The cookie field of the Sync Update control value MAY be set in any returned result, during both the sync phase and the persist phase. The server should return the cookie to the client often enough for the client to resync in a reasonable period of time in case the search is disconnected or otherwise terminated. The sendCookieInterval field in the Sync Request control is a suggestion Megginson, et al. Standards Track [Page 11] RFC 3928 LDAP Client Update Protocol October 2004 to the server of how often to return the cookie in the Sync Update control. The server SHOULD respect this value. The scheme field of the Sync Update control value MUST be set if the cookie is set and the cookie format has changed; otherwise, it MAY be omitted. Some clients may have unreliable connections, for example, a wireless device or a WAN connection. These clients may want to insure that the cookie is returned often in the Sync Update control value, so that if they have to reconnect, they do not have to process many redundant entries. These clients should set the sendCookieInterval in the Sync Request control value to a low number, perhaps even 1. Some clients may have a limited bandwidth connection, and may not want to receive the cookie very often, or even at all (however, the cookie is always sent back in the Sync Done control value upon successful completion). These clients should set the sendCookieInterval in the Sync Request control value to a high number. A reasonable behavior of the server is to return the cookie only when data in the LCUP context has changed, even if the client has specified a frequent sendCookieInterval. If nothing has changed, the server can probably save some bandwidth by not returning the cookie. 4.2.3. Definition of an Entry That Has Entered the Result Set An entry SHALL BE considered to have entered the client's search result set if one of the following conditions is met: - During the sync phase for an incremental sync operation, the entry is present in the search result set but was not present before; this can be due to the entry being added via an LDAP Add operation, or by the entry being moved into the result set by an LDAP Modify DN operation, or by some modification to the entry that causes it to enter the result set (e.g., adding an attribute value that matches the clients search filter), or by some meta- data change that causes the entry to enter the result set (e.g., relaxing of some access control that permits the entry to be visible to the client). - During the persist phase for a persistent search operation, the entry enters the search result set; this can be due to the entry being added via an LDAP Add operation, or by the entry being moved into the result set by an LDAP Modify DN operation, or by some modification to the entry that causes it to enter the result set (e.g., adding an attribute value that matches the clients search filter), or by some meta-data change that causes the entry to Megginson, et al. Standards Track [Page 12] RFC 3928 LDAP Client Update Protocol October 2004 enter the result set (e.g., relaxing of some access control that permits the entry to be visible to the client). 4.2.4. Definition of an Entry That Has Changed An entry SHALL BE considered to be changed if one or more of the attributes in the attribute list in the search request have been modified. For example, if the search request listed the attributes "cn sn uid", and there is an entry in the client's search result set with the "cn" attribute that has been modified, the entry is considered to be modified. The modification may be due to an LDAP Modify operation or by some change to the meta-data for the entry (e.g., virtual attributes) that causes some change to the value of the specified attributes. The converse of this is that an entry SHALL NOT BE considered to be changed if none of the attributes in the attribute list of the search request are modified attributes of the entry. For example, if the search request listed the attributes "cn sn uid", and there is an entry in the client's search result set with the "foo" attribute that has been modified, and none of the "cn" or "sn" or "uid" attributes have been modified, the entry is NOT considered to be changed. 4.2.5. Definition of an Entry That Has Left the Result Set An entry SHALL BE considered to have left the client's search result set if one of the following conditions is met: - During the sync phase for an incremental sync operation, the entry is not present in the search result set but was present before; this can be due to the entry being deleted via an LDAP Delete operation, or by the entry leaving the result set via an LDAP Modify DN operation, or by some modification to the entry that causes it to leave the result set (e.g., changing/removing an attribute value so that it no longer matches the client's search filter), or by some meta-data change that causes the entry to leave the result set (e.g., adding of some access control that denies the entry to be visible to the client). - During the persist phase for a persistent search operation, the entry leaves the search result set; this can be due to the entry being deleted via an LDAP Delete operation, or by the entry leaving the result set via an LDAP Modify DN operation, or by some modification to the entry that causes it to leave the result set (e.g., changing/removing an attribute value so that it no longer matches the client's search filter), or by some meta-data change Megginson, et al. Standards Track [Page 13] RFC 3928 LDAP Client Update Protocol October 2004 that causes the entry to leave the result set (e.g., adding of some access control that denies the entry to be visible to the client). 4.2.6. Results For Entries Present in the Result Set An entry SHOULD be returned as present under the following conditions: - The request is an initial synchronization or full resync request and the entry is present in the client's search result set - The request is an incremental synchronization and the entry has changed or entered the result set since the last sync - The search is in the persist phase and the entry enters the result set or changes For a SearchResultEntry return, the fields of the Sync Update control value MUST be set as follows: stateUpdate - MUST be set to FALSE entryUUID - MUST be set to the UUID of the entry entryLeftSet - MUST be set to FALSE persistPhase - MUST be set to FALSE if during the sync phase or TRUE if during the persist phase UUIDAttribute - SHOULD only be set if this is either the first result returned or if the attribute has changed scheme - as above cookie - as above The searchResultReference return will look the same, except that the entryUUID is not required. If it is specified, it MUST contain the UUID of the DSE holding the reference knowledge. 4.2.7. Results For Entries That Have Left the Result Set An entry SHOULD be returned as having left the result set under the following conditions: - The request is an incremental synchronization during the sync phase and the entry has left the result set - The search is in the persist phase and the entry has left the result set Megginson, et al. Standards Track [Page 14] RFC 3928 LDAP Client Update Protocol October 2004 - The entry has left the result set as a result of an LDAP Delete or LDAP Modify DN operation against the entry itself (i.e., not as a result of an operation against its parent or ancestor) For a SearchResultEntry return where the entry has left the result set, the fields of the Sync Update control value MUST be set as follows: stateUpdate - MUST be set to FALSE entryUUID - MUST be set to the UUID of the entry that left the result set entryLeftSet - MUST be set to TRUE persistPhase - MUST be set to FALSE if during the sync phase or TRUE if during the persist phase UUIDAttribute - SHOULD only be set if this is either the first result returned or if the attribute has changed scheme - as above cookie - as above The searchResultReference return will look the same, except that the entryUUID is not required. If it is specified, it MUST contain the UUID of the DSE holding the reference knowledge. Some server implementations keep track of deleted entries using a tombstone - a hidden entry that keeps track of the state, but not all of the data, of an entry that has been deleted. In this case, the tombstone may not contain all of the original attributes of the entry, and therefore it may be impossible for the server to determine if an entry should be removed from the result set based on the attributes in the client's search request. Servers SHOULD keep enough information about the attributes in the deleted entries to determine if an entry should be removed from the result set. Since this may not be possible, the server MAY return an entry as having left the result set even if it is not or never was in the client's result set. Clients MUST ignore these notifications. 4.3. Responses Requiring Special Consideration The following sections describe special handling that may be required when returning results. 4.3.1. Returning Results During the Persistent Phase During the persistent phase, the server SHOULD return the changed entries to the client as quickly as possible. Megginson, et al. Standards Track [Page 15] RFC 3928 LDAP Client Update Protocol October 2004 4.3.2. No Mixing of Sync Phase with Persist Phase During a sync phase, the server MUST NOT return any entries with the persistPhase flag set to TRUE, and during the persist phase, all entries returned MUST have the persistPhase flag set to TRUE. The server MUST NOT mix and match sync phase entries with persist phase entries. If there are any sync phase entries to return, they MUST be returned before any persist phase entries are returned. 4.3.3. Returning Updated Results During the Sync Phase There may be updates to the entries in the result set of a sync phase search during the actual search operation. If the DSA is under a heavy update load, and it attempts to send all of those updated entries to the client in addition to the other updates it was already planning to send for the sync phase, the server may never get to the end of the sync phase. Therefore, it is left up to the discretion of the server implementation to decide when the client is "in sync" - that is, when to end a syncOnly request, or when to send the Sync Update Informational Response between the sync phase and the persist phase of a syncAndPersist request. The server MAY send the same entry multiple times during the sync phase if the entry changes during the sync phase. A reasonable behavior is for the server to generate a cookie based on the server state at the time the client initiated the LCUP request, and only send entries up to that point during the sync phase. Entries updated after that point will be returned only during the persist phase of a syncAndPersist request, or only upon an incremental synchronization. 4.3.4. Operational Attributes and Administrative Entries An operational attribute SHOULD be returned if it is specified in the attributes list and would normally be returned as subject to the constraints of [RFC2251 Section 4.5]. If the server does not support syncing of operational attributes, the server MUST return a SearchResultDone message with a resultCode of unwillingToPerform. LDAP Subentries [RFC3672] SHOULD be returned if they would normally be returned by the search request. If the server does not support syncing of LDAP Subentries, and the server can determine from the search request that the client has requested LDAP Subentries to be returned (e.g., search control or search filter), the server MUST return a SearchResultDone message with a resultCode of unwillingToPerform. Otherwise, the server MAY simply omit returning LDAP Subentries. Megginson, et al. Standards Track [Page 16] RFC 3928 LDAP Client Update Protocol October 2004 4.3.5. Virtual Attributes An entry may have attributes whose presence in the entry, or presence of values of the attribute, is generated on the fly, possibly by some mechanism outside of the entry, elsewhere in the DIT. An example of this is collective attributes [RFC3671]. These attributes shall be referred to in this document as virtual attributes. LCUP treats these attributes the same way as normal, non-virtual attributes. A virtual attribute SHOULD be returned if it is specified in the attributes list and would normally be returned as subject to the constraints of [RFC2251 Section 4.5]. If the server does not support syncing of virtual attributes, the server MUST return a SearchResultDone message with a resultCode of unwillingToPerform. One consequence of this is that if you change the definition of a virtual attribute such that it makes the value of that attribute change in many entries in the client's search scope, this means that a server may have to return many entries to the client as a result of that one change. It is not anticipated that this will be a frequent occurrence, and the server has the option to simply force the client to resync if necessary. It is also possible that a future LDAP control will allow the client to request only virtual or only non-virtual attributes. 4.3.6. Modify DN and Delete Operations Applied to Subtrees There is a special case where a Modify DN or a Delete operation is applied to the base entry of a subtree, and either that base entry or entries in the subtree are within the scope of an LCUP search request. In this case, all of the entries in the subtree are implicitly renamed or removed. In either of these cases, the server MUST do one of the following: - treat all of these entries as having been renamed or removed and return each entry to the client as such - decide that this would be prohibitively expensive, and force the client to resync If the search base object has been renamed, and the client has received a noSuchObject as the result of a search request, the client MAY use the entryUUID and UUIDAttribute to locate the new DN that is the result of the modify DN operation. Megginson, et al. Standards Track [Page 17] RFC 3928 LDAP Client Update Protocol October 2004 4.3.7. Convergence Guarantees If at any time during an LCUP search, either during the sync phase or the persist phase, the server determines that it cannot guarantee that it can bring the client's copy of the data to eventual convergence, it SHOULD immediately terminate the LCUP search request and return a SearchResultDone message with a resultCode of lcupReloadRequired. This can also happen at the beginning of an incremental synchronization request, if the client presents a cookie that is out of date or otherwise unable to be processed. The client should then issue an initial synchronization request. This can happen, for example, if the data on the server is reloaded, or if there has been some change to the meta-data that makes it impossible for the server to determine if a particular entry should or should not be part of the search result set, or if the meta-data change makes it too resource intensive for the server to calculate the proper result set. The server can also return lcupReloadRequired if it determines that it would be more efficient for the client to perform a reload, for example, if too many entries have changed and a simple reload would be much faster. 4.4. LCUP Search Termination 4.4.1. Server Initiated Termination When the server has successfully finished processing the client's request, it attaches a Sync Done control to the SearchResultDone message and sends it to the client. However, if the SearchResultDone message contains a resultCode that is not success or canceled, the Sync Done control MAY be omitted. Although the LCUP cookie is OPTIONAL in the Sync Done control value, it MUST be set if the SearchResultDone resultCode is success or canceled. The server SHOULD also set the cookie if the resultCode is lcupResourcesExhausted, timeLimitExceeded, sizeLimitExceeded, or adminLimitExceeded. This allows the client to more easily resync later. If some error occurred, either an LDAP search error (e.g., insufficientAccessRights) or an LCUP error (e.g., lcupUnsupportedScheme), the cookie MAY be omitted. If the cookie is set, the scheme MUST be set also if the cookie format has changed, otherwise, it MAY be omitted. If server resources become tight, the server can terminate one or more search operations by sending a SearchResultDone message to the client(s) with a resultCode of lcupResourcesExhausted. The server SHOULD attach a Sync Done control with the cookie set. A server side Megginson, et al. Standards Track [Page 18] RFC 3928 LDAP Client Update Protocol October 2004 policy is used to decide which searches to terminate. This can also be used as a security mechanism to disconnect clients that are suspected of malicious actions, but if the server can infer that the client is malicious, the server SHOULD return lcupSecurityViolation instead. 4.4.2. Client Initiated Termination If the client needs to terminate the synchronization process and it wishes to obtain the cookie that represents the current state of its data, it issues an LDAP Cancel operation [RFC3909]. The server responds immediately with a LDAP Cancel response [RFC3909]. The server MAY send any pending SearchResultEntry or SearchResultReference PDUs if the server cannot easily abort or remove those search results from its outgoing queue. The server SHOULD send as few of these remaining messages as possible. Finally, the server sends the message SearchResultDone with the Sync Done control attached. If the search was successful up to that point, the resultCode field of the SearchResultDone message MUST be canceled [RFC3909], and the cookie MUST be set in the Sync Done control. If there is an error condition, the server MAY return as described in section 4.4.1 above, or MAY return as described in [RFC3909]. If the client is not interested in the state information, it can simply abandon the search operation or disconnect from the server. 4.5. Size and Time Limits The server SHALL support size and time limits as specified in [RFC2251, Section 5]. The server SHOULD ensure that if the operation is terminated due to these conditions, the cookie is sent back to the client. 4.6. Operations on the Same Connection It is permissible for the client to issue other LDAP operations on the connection used by the protocol. Since each LDAP request/response carries a message id there will be no ambiguity about which PDU belongs to which operation. By sharing the connection among multiple operations, the server will be able to conserve its resources. 4.7. Interactions with Other Controls LCUP defines neither restrictions nor guarantees about the ability to use the controls defined in this document in conjunction with other LDAP controls, except for the following: A server MAY ignore non- critical controls supplied with the LCUP control. A server MAY Megginson, et al. Standards Track [Page 19] RFC 3928 LDAP Client Update Protocol October 2004 ignore an LCUP defined control if it is non-critical and it is supplied with other critical controls. If a server receives a critical LCUP control with another critical control, and the server does not support both controls at the same time, the server SHOULD return unavailableCriticalExtension. It is up to the server implementation to determine if the server supports controls such as the Sort or VLV or similar controls that change the order of the entries sent to the client. But note that it may be difficult or impossible for a server to perform an incremental synchronization in the presence of such controls, since the cookie will typically be based off a change number, or Change Sequence Number (CSN), or timestamp, or some criteria other than an alphabetical order. 4.8. Replication Considerations Use of an LCUP cookie with multiple DSAs in a replicated environment is not defined by LCUP. An implementation of LCUP may support continuation of an LCUP session with another DSA holding a replica of the LCUP context. Clients MAY submit cookies returned by one DSA to a different DSA; it is up to the server to determine if a cookie is one they recognize or not and to return an appropriate result code if not. 5. Client Side Considerations 5.1. Using Cookies with Different Search Criteria The cookie received from the server after a synchronization session SHOULD only be used with the same search specification as the search that generated the cookie. Some servers MAY allow the cookie to be used with a more restrictive search specification than the search that generated the cookie. If the server does not support the cookie, it MUST return lcupInvalidCookie. This is because the client can end up with an incomplete data store otherwise. A more restrictive search specification is one that would generate a subset of the data produced by the original search specification. 5.2. Renaming the Base Object Because an LCUP client specifies the area of the tree with which it wishes to synchronize through the standard LDAP search specification, the client can be returned noSuchObject error if the root of the synchronization area was renamed between the synchronization sessions or during a synchronization session. If this condition occurs, the client can attempt to locate the root by using the root's UUID saved in client's local data store. It then can repeat the synchronization Megginson, et al. Standards Track [Page 20] RFC 3928 LDAP Client Update Protocol October 2004 request using the new search base. In general, a client can detect that an entry was renamed and apply the changes received to the right entry by using the UUID rather than DN based addressing. 5.3. Use of Persistent Searches With Respect to Resources Each active persistent operation requires that an open TCP connection be maintained between an LDAP client and an LDAP server that might not otherwise be kept open. Therefore, client implementors are encouraged to avoid using persistent operations for non-essential tasks and to close idle LDAP connections as soon as practical. The server may close connections if server resources become tight. 5.4. Continuation References to Other LCUP Contexts The client MAY receive a continuation reference (SearchResultReference [RFC2251 SECTION 4.5.3]) if the search request spans multiple parts of the DIT, some of which may require a different LCUP cookie, some of which may not even be managed by LCUP. The client SHOULD maintain a cache of the LDAP URLs returned in the continuation references and the cookies associated with them. The client is responsible for performing another LCUP search to follow the references, and SHOULD use the cookie corresponding to the LDAP URL for that reference (if it has a cookie). 5.5. Referral Handling The client may receive a referral (Referral [RFC2251 SECTION 4.1.11]) when the search base is a subordinate reference, and this will end the operation. 5.6. Multiple Copies of Same Entry During Sync Phase The server MAY send the same entry multiple times during a sync phase if the entry changes during the sync phase. The client SHOULD use the last sent copy of the entry as the current one. 5.7. Handling Server Out of Resources Condition If the client receives an lcupResourcesExhausted or lcupSecurityViolation resultCode, the client SHOULD wait at least 5 seconds before attempting another operation. It is RECOMMENDED that the client use an exponential backoff strategy, but different clients may want to use different backoff strategies. Megginson, et al. Standards Track [Page 21] RFC 3928 LDAP Client Update Protocol October 2004 6. Server Implementation Considerations 6.1. Server Support for UUIDs Servers MUST support UUIDs. UUIDs are required in the Sync Update control. Additionally, server implementers SHOULD make the UUID values for the entries available as an attribute of the entry, and provide indexing or other mechanisms to allow clients to search for an entry using the UUID attribute in the search filter. The syncUpdate control provides a field UUIDAttribute to allow the server to let the client know the name or OID of the attribute to use to search for an entry by UUID. 6.2. Example of Using an RUV as the Cookie Value By design, the protocol supports multiple cookie schemes. This is to allow different implementations the flexibility of storing any information applicable to their environment. A reasonable implementation for an LDUP compliant server would be to use the Replica Update Vector (RUV). For each master, RUV contains the largest CSN seen from this master. In addition, RUV implemented by some directory servers (not yet in LDUP) contains replica generation - an opaque string that identifies the replica's data store. The replica generation value changes whenever the replica's data is reloaded. Replica generation is intended to signal the replication/synchronization peers that the replica's data was reloaded and that all other replicas need to be reinitialized. RUV satisfies the three most important properties of the cookie: (1) it uniquely identifies the state of client's data, (2) it can be used to synchronize with multiple servers, and (3) it can be used to detect that the server's data was reloaded. If RUV is used as the cookie, entries last modified by a particular master must be sent to the client in the order of their last modified CSN. This ordering guarantees that the RUV can be updated after each entry is sent. 6.3. Cookie Support Issues 6.3.1. Support for Multiple Cookie Schemes A server may support one or more LCUP cookie schemes. It is expected that schemes will be published along with their OIDs as RFCs. The server's DIT may be partitioned into different sections which may have different cookies associated with them. For example, some servers may use some sort of replication mechanism to support LCUP. If so, the DIT may be partitioned into multiple replicas. A client may send an LCUP search request that spans multiple replicas. Some parts of the DIT spanned by the search request scope may support LCUP and some may not. The server MUST send a SearchResultReference Megginson, et al. Standards Track [Page 22] RFC 3928 LDAP Client Update Protocol October 2004 [RFC2251, SECTION 4.5.3] when the LCUP Context for a returned entry changes. The server SHOULD send all references to other LCUP Contexts in the search scope first, in order to allow the clients to process these searches in parallel. The LDAP URL(s) returned MUST contain the DN(s) of the base of another section of the DIT (however the server implementation has partitioned the DIT). The client will then issue another LCUP search using the LDAP URL returned. Each section of the DIT MAY require a different cookie value, so the client SHOULD maintain a cache, mapping the different LDAP URL values to different cookies. If the cookie changes, the scheme may change as well, but the cookie scheme MUST be the same within a given LCUP Context. 6.3.2. Information Contained in the Cookie The cookie must contain enough information to allow the server to determine whether the cookie can be safely used with the search specification it is attached to. As discussed earlier in the document, the cookie SHOULD only be used with the search specification that is equal to the one for which the cookie was generated, but some servers MAY support using a cookie with a search specification that is more restrictive than the one used to generate the cookie. 6.4. Persist Phase Response Time The specification makes no guarantees about how soon a server should send notification of a changed entry to the client during the persist phase. This is intentional as any specific maximum delay would be impossible to meet in a distributed directory service implementation. Server implementers are encouraged to minimize the delay before sending notifications to ensure that clients' needs for timeliness of change notification are met. 6.5. Scaling Considerations Implementers of servers that support the mechanism described in this document should ensure that their implementation scales well as the number of active persistent operations and the number of changes made in the directory increases. Server implementers are also encouraged to support a large number of client connections if they need to support large numbers of persistent operations. Megginson, et al. Standards Track [Page 23] RFC 3928 LDAP Client Update Protocol October 2004 6.6. Alias Dereferencing LCUP design does not consider issues associated with alias dereferencing in search. Clients MUST specify derefAliases as either neverDerefAliases or derefFindingBaseObj. Servers are to return protocolError if the client specifies either derefInSearching or derefAlways. 7. Synchronizing Heterogeneous Data Stores Clients, like a meta directory join engine, synchronizing multiple writable data stores, will only work correctly if each piece of information comes from a single authoritative data source. In a replicated environment, an LCUP Context should employ the same conflict resolution scheme across all its replicas. This is because different systems have different notions of time and different update resolution procedures. As a result, a change applied on one system can be discarded by the other, thus preventing the data stores from converging. 8. IANA Considerations This document lists several values that have been registered by the IANA. The following LDAP result codes have been assigned by IANA as described in section 3.6 of [RFC3383]: lcupResourcesExhausted 113 lcupSecurityViolation 114 lcupInvalidData 115 lcupUnsupportedScheme 116 lcupReloadRequired 117 The three controls defined in this document have been registered as LDAP Protocol Mechanisms as described in section 3.2 of [RFC3383]. One OID, 1.3.6.1.1.7, has been assigned by IANA as described in section 3.1 of [RFC3383]. The OIDs for the controls defined in this document are derived as follows from the one assigned by IANA: LCUP Sync Request Control 1.3.6.1.1.7.1 LCUP Sync Update Control 1.3.6.1.1.7.2 LCUP Sync Done Control 1.3.6.1.1.7.3 9. Security Considerations In some situations, it may be important to prevent general exposure of information about changes that occur in an LDAP server. Therefore, servers that implement the mechanism described in this document SHOULD provide a means to enforce access control on the entries Megginson, et al. Standards Track [Page 24] RFC 3928 LDAP Client Update Protocol October 2004 returned and MAY also provide specific access control mechanisms to control the use of the controls and extended operations defined in this document. As with normal LDAP search requests, a malicious client can initiate a large number of persistent search requests in an attempt to consume all available server resources and deny service to legitimate clients. The protocol provides the means to stop malicious clients by disconnecting them from the server. The servers that implement the mechanism SHOULD provide the means to detect the malicious clients. In addition, the servers SHOULD provide the means to limit the number of resources that can be consumed by a single client. 10. References 10.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2251] Wahl, M., Howes, T., and S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [RFC3383] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 3383, September 2002. [RFC3909] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP) Cancel Operation", RFC 3909, October 2004. [X.680] ITU-T, "Abstract Syntax Notation One (ASN.1) - Specification of Basic Notation", X.680, 1994. [X.690] ITU-T, "Specification of ASN.1 encoding rules: Basic, Canonical, and Distinguished Encoding Rules", X.690, 1994. [UUID] International Organization for Standardization (ISO), "Information technology - Open Systems Interconnection - Remote Procedure Call", ISO/IEC 11578:1996. Megginson, et al. Standards Track [Page 25] RFC 3928 LDAP Client Update Protocol October 2004 10.2. Informative References [RFC3384] Stokes, E., Weiser, R., Moats, R., and R. Huber, "Lightweight Directory Access Protocol (version 3) Replication Requirements", RFC 3384, October 2002. [RFC3671] Zeilenga, K., "Collective Attributes in the Lightweight Directory Access Protocol (LDAP)", RFC 3671, December 2003. [RFC3672] Zeilenga, K. and S. Legg, "Subentries in the Lightweight Directory Access Protocol (LDAP)", RFC 3672, December 2003. 11. Acknowledgments The LCUP protocol is based in part on the Persistent Search Change Notification Mechanism defined by Mark Smith, Gordon Good, Tim Howes, and Rob Weltman, the LDAPv3 Triggered Search Control defined by Mark Wahl, and the LDAP Control for Directory Synchronization defined by Michael Armijo. The members of the IETF LDUP working group made significant contributions to this document. Megginson, et al. Standards Track [Page 26] RFC 3928 LDAP Client Update Protocol October 2004 Appendix - Features Left Out of LCUP There are several features present in other protocols or considered useful by clients that are currently not included in the protocol primarily because they are difficult to implement on the server. These features are briefly discussed in this section. Triggered Search Change Type This feature is present in the Triggered Search specification. A flag is attached to each entry returned to the client indicating the reason why this entry is returned. The possible reasons from the document are: - notChange: the entry existed in the directory and matched the search at the time the operation is being performed, - enteredSet: the entry entered the result, - leftSet: the entry left the result, - modified: the entry was part of the result set, was modified or renamed, and still is in the result set. The leftSet feature is particularly useful because it indicates to the client that an entry is no longer within the client's search specification and the client can remove the associated data from its data store. Ironically, this feature is the hardest to implement on the server because the server does not keep track of the client's state and has no easy way of telling which entries moved out of scope between synchronization sessions with the client. A compromise could be reached by only providing this feature for the operations that occur while the client is connected to the server. This is easier to accomplish because the decision about the change type can be made based only on the change without need for any historical information. This, however, would add complexity to the protocol. Persistent Search Change Type This feature is present in the Persistent Search specification. Persistent search has the notion of changeTypes. The client specifies which type of updates will cause entries to be returned, and optionally whether the server tags each returned entry with the type of change that caused that entry to be returned. For LCUP, the intention is full synchronization, not partial. Each entry returned by an LCUP search will have some change associated with it that may concern the client. The client may have to have a Megginson, et al. Standards Track [Page 27] RFC 3928 LDAP Client Update Protocol October 2004 local index of entries by DN or UUID to determine if the entry has been added or just modified. It is easy for clients to determine if the entry has been deleted because the entryLeftSet value of the Sync Update control will be TRUE. Sending Changes Some earlier synchronization protocols sent the client(s) only the modified attributes of the entry rather than the entire entry. While this approach can significantly reduce the amount of data returned to the client, it has several disadvantages. First, unless a separate mechanism (like the change type described above) is used to notify the client about entries moving into the search scope, sending only the changes can result in the client having an incomplete version of the data. Let's consider an example. An attribute of an entry is modified. As a result of the change, the entry enters the scope of the client's search. If only the changes are sent, the client would never see the initial data of the entry. Second, this feature is hard to implement since the server might not contain sufficient information to construct the changes based solely on the server's state and the client's cookie. On the other hand, this feature can be easily implemented by the client assuming that the client has the previous version of the data and can perform value by value comparisons. Data Size Limits Some earlier synchronization protocols allowed clients to control the amount of data sent to them in the search response. This feature was intended to allow clients with limited resources to process synchronization data in batches. However, an LDAP search operation already provides the means for the client to specify the size limit by setting the sizeLimit field in the SearchRequest to the maximum number of entries the client is willing to receive. While the granularity is not the same, the assumption is that regular LDAP clients that can deal with the limitations of the LDAP protocol will implement LCUP. Data Ordering Some earlier synchronization protocols allowed a client to specify that parent entries should be sent before the children for add operations and children entries sent before their parents during delete operations. This ordering helps clients to maintain a hierarchical view of the data in their data store. While possibly useful, this feature is relatively hard to implement and is expensive to perform. Megginson, et al. Standards Track [Page 28] RFC 3928 LDAP Client Update Protocol October 2004 Authors' Addresses Rich Megginson Netscape Communications Corp., an America Online company. 360 W. Caribbean Drive Sunnyvale, CA 94089 USA Phone: +1 505 797-7762 EMail: rmegginson0224@aol.com Olga Natkovich Yahoo, Inc. 701 First Ave. Sunnyvale, CA 94089 USA Phone: +1 408 349-6153 EMail: olgan@yahoo-inc.com Mark Smith Pearl Crescent, LLC 447 Marlpool Drive Saline, MI 48176 USA Phone: +1 734 944-2856 EMail: mcs@pearlcrescent.com Jeff Parham Microsoft Corporation One Microsoft Way Redmond, WA 98052-6399 USA Phone: +1 425 882-8080 EMail: jeffparh@microsoft.com Megginson, et al. Standards Track [Page 29] RFC 3928 LDAP Client Update Protocol October 2004 Full Copyright Statement Copyright (C) The Internet Society (2004). This document is subject to the rights, licenses and restrictions contained in BCP 78, and at www.rfc-editor.org, 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 ISOC's procedures with respect to rights in ISOC 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@ietf.org. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Megginson, et al. Standards Track [Page 30] PK )�c\�?I�0 �0 ( doc/alt-openldap11-devel/rfc/rfc4528.txtnu �[��� Network Working Group K. Zeilenga Request for Comments: 4528 OpenLDAP Foundation Category: Standards Track June 2006 Lightweight Directory Access Protocol (LDAP) Assertion Control Status of This Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2006). Abstract This document defines the Lightweight Directory Access Protocol (LDAP) Assertion Control, which allows a client to specify that a directory operation should only be processed if an assertion applied to the target entry of the operation is true. It can be used to construct "test and set", "test and clear", and other conditional operations. Table of Contents 1. Overview ........................................................2 2. Terminology .....................................................2 3. The Assertion Control ...........................................2 4. Security Considerations .........................................3 5. IANA Considerations .............................................4 5.1. Object Identifier ..........................................4 5.2. LDAP Protocol Mechanism ....................................4 5.3. LDAP Result Code ...........................................4 6. Acknowledgements ................................................5 7. References ......................................................5 7.1. Normative References .......................................5 7.2. Informative References .....................................5 Zeilenga Standards Track [Page 1] RFC 4528 LDAP Assertion Control June 2006 1. Overview This document defines the Lightweight Directory Access Protocol (LDAP) [RFC4510] assertion control. The assertion control allows the client to specify a condition that must be true for the operation to be processed normally. Otherwise, the operation is not performed. For instance, the control can be used with the Modify operation [RFC4511] to perform atomic "test and set" and "test and clear" operations. The control may be attached to any update operation to support conditional addition, deletion, modification, and renaming of the target object. The asserted condition is evaluated as an integral part the operation. The control may also be used with the search operation. Here, the assertion is applied to the base object of the search before searching for objects that match the search scope and filter. The control may also be used with the compare operation. Here, it extends the compare operation to allow a more complex assertion. 2. Terminology Protocol elements are described using ASN.1 [X.680] with implicit tags. The term "BER-encoded" means the element is to be encoded using the Basic Encoding Rules [X.690] under the restrictions detailed in Section 5.1 of [RFC4511]. DSA stands for Directory System Agent (or server). DSE stands for DSA-specific Entry. In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in BCP 14 [RFC2119]. 3. The Assertion Control The assertion control is an LDAP Control [RFC4511] whose controlType is 1.3.6.1.1.12 and whose controlValue is a BER-encoded Filter [Protocol, Section 4.5.1]. The criticality may be TRUE or FALSE. There is no corresponding response control. The control is appropriate for both LDAP interrogation and update operations [RFC4511], including Add, Compare, Delete, Modify, ModifyDN (rename), and Search. It is inappropriate for Abandon, Bind, Unbind, and StartTLS operations. Zeilenga Standards Track [Page 2] RFC 4528 LDAP Assertion Control June 2006 When the control is attached to an LDAP request, the processing of the request is conditional on the evaluation of the Filter as applied against the target of the operation. If the Filter evaluates to TRUE, then the request is processed normally. If the Filter evaluates to FALSE or Undefined, then assertionFailed (122) resultCode is returned, and no further processing is performed. For Add, Compare, and ModifyDN operations, the target is indicated by the entry field in the request. For Modify operations, the target is indicated by the object field. For Delete operations, the target is indicated by the DelRequest type. For Compare operations and all update operations, the evaluation of the assertion MUST be performed as an integral part of the operation. That is, the evaluation of the assertion and the normal processing of the operation SHALL be done as one atomic action. For Search operations, the target is indicated by the baseObject field, and the evaluation is done after "finding" but before "searching" [RFC4511]. Hence, no entries or continuations references are returned if the assertion fails. Servers implementing this technical specification SHOULD publish the object identifier 1.3.6.1.1.12 as a value of the 'supportedControl' attribute [RFC4512] in their root DSE. A server MAY choose to advertise this extension only when the client is authorized to use it. Other documents may specify how this control applies to other LDAP operations. In doing so, they must state how the target entry is determined. 4. Security Considerations The filter may, like other components of the request, contain sensitive information. When it does, this information should be appropriately protected. As with any general assertion mechanism, the mechanism can be used to determine directory content. Hence, this mechanism SHOULD be subject to appropriate access controls. Some assertions may be very complex, requiring significant time and resources to evaluate. Hence, this mechanism SHOULD be subject to appropriate administrative controls. Zeilenga Standards Track [Page 3] RFC 4528 LDAP Assertion Control June 2006 Security considerations for the base operations [RFC4511] extended by this control, as well as general LDAP security considerations [RFC4510], generally apply to implementation and use of this extension. 5. IANA Considerations 5.1. Object Identifier The IANA has assigned an LDAP Object Identifier [RFC4520] to identify the LDAP Assertion Control defined in this document. Subject: Request for LDAP Object Identifier Registration Person & email address to contact for further information: Kurt Zeilenga <kurt@OpenLDAP.org> Specification: RFC 4528 Author/Change Controller: IESG Comments: Identifies the LDAP Assertion Control 5.2. LDAP Protocol Mechanism Registration of this protocol mechanism [RFC4520] is requested. Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: 1.3.6.1.1.12 Description: Assertion Control Person & email address to contact for further information: Kurt Zeilenga <kurt@openldap.org> Usage: Control Specification: RFC 4528 Author/Change Controller: IESG Comments: none 5.3. LDAP Result Code The IANA has assigned an LDAP Result Code [RFC4520] called 'assertionFailed' (122). Subject: LDAP Result Code Registration Person & email address to contact for further information: Kurt Zeilenga <kurt@OpenLDAP.org> Result Code Name: assertionFailed Specification: RFC 4528 Author/Change Controller: IESG Comments: none Zeilenga Standards Track [Page 4] RFC 4528 LDAP Assertion Control June 2006 6. Acknowledgements The assertion control concept is attributed to Morteza Ansari. 7. References 7.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC4510] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006. [RFC4511] Sermersheim, J., Ed., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006. [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006. [X.680] International Telecommunication Union - Telecommunication Standardization Sector, "Abstract Syntax Notation One (ASN.1) - Specification of Basic Notation", X.680(2002) (also ISO/IEC 8824-1:2002). [X.690] International Telecommunication Union - Telecommunication Standardization Sector, "Specification of ASN.1 encoding rules: Basic Encoding Rules (BER), Canonical Encoding Rules (CER), and Distinguished Encoding Rules (DER)", X.690(2002) (also ISO/IEC 8825-1:2002). 7.2. Informative References [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006. Author's Address Kurt D. Zeilenga OpenLDAP Foundation EMail: Kurt@OpenLDAP.org Zeilenga Standards Track [Page 5] RFC 4528 LDAP Assertion Control June 2006 Full Copyright Statement Copyright (C) The Internet Society (2006). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Zeilenga Standards Track [Page 6] PK )�c\_��+ �+ ( doc/alt-openldap11-devel/rfc/rfc4525.txtnu �[��� Network Working Group K. Zeilenga Request for Comments: 4525 OpenLDAP Foundation Category: Informational June 2006 Lightweight Directory Access Protocol (LDAP) Modify-Increment Extension Status of This Memo This memo provides information for the Internet community. It does not specify an Internet standard of any kind. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2006). Abstract This document describes an extension to the Lightweight Directory Access Protocol (LDAP) Modify operation to support an increment capability. This extension is useful in provisioning applications, especially when combined with the assertion control and/or the pre- read or post-read control extension. Table of Contents 1. Background and Intended Use .....................................1 2. The Modify-Increment Extension ..................................2 3. LDIF Support ....................................................2 4. Security Considerations .........................................3 5. IANA Considerations .............................................3 5.1. Object Identifier ..........................................3 5.2. LDAP Protocol Mechanism ....................................3 5.3. LDAP Protocol Mechanism ....................................4 6. References ......................................................4 6.1. Normative References .......................................4 6.2. Informative References .....................................5 1. Background and Intended Use The Lightweight Directory Access Protocol (LDAP) [RFC4510] does not currently provide an operation to increment values of an attribute. A client must read the values of the attribute and then modify those values to increment them by the desired amount. As the values may be updated by other clients between this add and modify, the client must Zeilenga Informational [Page 1] RFC 4525 LDAP Modify-Increment Extension June 2006 be careful to construct the modify request so that it fails in this case, and upon failure, to re-read the values and construct a new modify request. This document extends the LDAP Modify Operation [RFC4511] to support an increment values capability. This feature is intended to be used with either the LDAP pre-read or post-read control extensions [RFC4527]. This feature may also be used with the LDAP assertion control extension [RFC4528] to provide test-and-increment functionality. In this document key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in BCP 14 [RFC2119]. 2. The Modify-Increment Extension This document extends the LDAP Modify request to support a increment values capability. Implementations of this extension SHALL support an additional ModifyRequest operation enumeration value increment (3), as described herein. Implementations not supporting this extension will treat this value as they would an unlisted value, e.g., as a protocol error. The increment (3) operation value specifies that an increment values modification is requested. All existing values of the modification attribute are to be incremented by the listed value. The modification attribute must be appropriate for the request (e.g., it must have INTEGER or other increment-able values), and the modification must provide one and only one value. If the attribute is not appropriate for the request, a constraintViolation or other appropriate error is to be returned. If multiple values are provided, a protocolError is to be returned. Servers supporting this feature SHOULD publish the object identifier (OID) 1.3.6.1.1.14 as a value of the 'supportedFeatures' [RFC4512] attribute in the root DSE. Clients supporting this feature SHOULD NOT use the feature unless they know the server supports it. 3. LDIF Support To represent Modify-Increment requests in LDAP Data Interchange Format [RFC2849], the ABNF [RFC4234] production <mod-spec> is extended as follows: mod-spec =/ "increment:" FILL AttributeDescription SEP attrval-spec "-" SEP Zeilenga Informational [Page 2] RFC 4525 LDAP Modify-Increment Extension June 2006 For example, # Increment uidNumber dn: cn=max-assigned uidNumber,dc=example,dc=com changetype: modify increment: uidNumber uidNumber: 1 - This LDIF fragment represents a Modify request to increment the value(s) of uidNumber by 1. 4. Security Considerations General LDAP security considerations [RFC4510], as well as those specific to the LDAP Modify [RFC4511], apply to this Modify-Increment extension. Beyond these considerations, it is noted that introduction of this extension should reduce application complexity (by providing one operation for what presently requires multiple operations) and, hence, it may aid in the production of correct and secure implementations. 5. IANA Considerations Registration of the following values [RFC4520] have been completed. 5.1. Object Identifier The IANA has assigned an LDAP Object Identifier to identify the LDAP Modify-Increment feature, as defined in this document. Subject: Request for LDAP Object Identifier Registration Person & email address to contact for further information: Kurt Zeilenga <kurt@OpenLDAP.org> Specification: RFC 4525 Author/Change Controller: Author Comments: Identifies the LDAP Modify-Increment feature 5.2. LDAP Protocol Mechanism The following LDAP Protocol Mechanism has been registered. Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: 1.3.6.1.1.14 Description: Modify-Increment Person & email address to contact for further information: Kurt Zeilenga <kurt@openldap.org> Zeilenga Informational [Page 3] RFC 4525 LDAP Modify-Increment Extension June 2006 Usage: Feature Specification: RFC 4525 Author/Change Controller: Kurt Zeilenga <kurt@openldap.org> Comments: none 5.3. LDAP Protocol Mechanism The IANA has assigned an LDAP ModifyRequest Operation Type (3) [RFC4520] for use in this document. Subject: Request for LDAP Protocol Mechanism Registration ModifyRequest Operation Name: increment Description: Modify-Increment Person & email address to contact for further information: Kurt Zeilenga <kurt@openldap.org> Usage: Feature Specification: RFC 4525 Author/Change Controller: Kurt Zeilenga <kurt@openldap.org> Comments: none 6. References 6.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 4234, October 2005. [RFC2849] Good, G., "The LDAP Data Interchange Format (LDIF) - Technical Specification", RFC 2849, June 2000. [RFC4510] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006. [RFC4511] Sermersheim, J., Ed., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006. [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006. Zeilenga Informational [Page 4] RFC 4525 LDAP Modify-Increment Extension June 2006 6.2. Informative References [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006. [RFC4527] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP) Read Entry Controls", RFC 4527, June 2006. [RFC4528] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP) Assertion Control", RFC 4528, June 2006. Author's Address Kurt D. Zeilenga OpenLDAP Foundation EMail: Kurt@OpenLDAP.org Zeilenga Informational [Page 5] RFC 4525 LDAP Modify-Increment Extension June 2006 Full Copyright Statement Copyright (C) The Internet Society (2006). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Zeilenga Informational [Page 6] PK )�c\4�5" 5" ( doc/alt-openldap11-devel/rfc/rfc2079.txtnu �[��� Network Working Group M. Smith Request for Comments: 2079 Netscape Communications Category: Standards Track January 1997 Definition of an X.500 Attribute Type and an Object Class to Hold Uniform Resource Identifiers (URIs) Status of this Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Abstract Uniform Resource Locators (URLs) are being widely used to specify the location of Internet resources. There is an urgent need to be able to include URLs in directories that conform to the LDAP and X.500 information models, and a desire to include other types of Uniform Resource Identifiers (URIs) as they are defined. A number of independent groups are already experimenting with the inclusion of URLs in LDAP and X.500 directories. This document builds on the experimentation to date and defines a new attribute type and an auxiliary object class to allow URIs, including URLs, to be stored in directory entries in a standard way. Background and Intended Usage Uniform Resource Locators (URLs) as defined by [1] are the first of several types of Uniform Resource Identifiers (URIs) being defined by the IETF. URIs are widely used on the Internet, most notably within Hypertext Markup Language [2] documents. This document defines an X.500 [3,4] attribute type called labeledURI and an auxiliary object class called labeledURIObject to hold all types of URIs, including URLs. These definitions are designed for use in LDAP and X.500 directories, and may be used in other contexts as well. Smith Standards Track [Page 1] RFC 2079 URI Attribute Type and Object Class January 1997 Schema Definition of the labeledURI Attribute Type Name: labeledURI ShortName: None Description: Uniform Resource Identifier with optional label OID: umichAttributeType.57 (1.3.6.1.4.1.250.1.57) Syntax: caseExactString SizeRestriction: None SingleValued: False Discussion of the labeledURI Attribute Type The labeledURI attribute type has the caseExactString syntax (since URIs are case-sensitive) and it is multivalued. Values placed in the attribute should consist of a URI (at the present time, a URL) optionally followed by one or more space characters and a label. Since space characters are not allowed to appear un-encoded in URIs, there is no ambiguity about where the label begins. At the present time, the URI portion must comply with the URL specification [1]. Multiple labeledURI values will generally indicate different resources that are all related to the X.500 object, but may indicate different locations for the same resource. The label is used to describe the resource to which the URI points, and is intended as a friendly name fit for human consumption. This document does not propose any specific syntax for the label part. In some cases it may be helpful to include in the label some indication of the kind and/or size of the resource referenced by the URI. Note that the label may include any characters allowed by the caseExactString syntax, but that the use of non-IA5 (non-ASCII) characters is discouraged as not all directory clients may handle them in the same manner. If non-IA5 characters are included, they should be represented using the X.500 conventions, not the HTML conventions (e.g., the character that is an "a" with a ring above it should be encoded using the T.61 sequence 0xCA followed by an "a" character; do not use the HTML escape sequence "å"). Examples of labeledURI Attribute Values An example of a labeledURI attribute value that does not include a label: ftp://ds.internic.net/rfc/rfc822.txt Smith Standards Track [Page 2] RFC 2079 URI Attribute Type and Object Class January 1997 An example of a labeledURI attribute value that contains a tilde character in the URL (special characters in a URL must be encoded as specified by the URL document [1]). The label is "LDAP Home Page": http://www.umich.edu/%7Ersug/ldap/ LDAP Home Page Another example. This one includes a hint in the label to help the user realize that the URL points to a photo image. http://champagne.inria.fr/Unites/rennes.gif Rennes [photo] Schema Definition of the labeledURIObject Object Class Name: labeledURIObject Description: object that contains the URI attribute type OID: umichObjectClass.15 (1.3.6.1.4.1.250.3.15) SubclassOf: top MustContain: MayContain: labeledURI Discussion of the labeledURIObject Object Class The labeledURIObject class is a subclass of top and may contain the labeledURI attribute. The intent is that this object class can be added to existing directory objects to allow for inclusion of URI values. This approach does not preclude including the labeledURI attribute type directly in other object classes as appropriate. Security Considerations Security considerations are not discussed in this memo, except to note that blindly inserting the label portion of a labeledURI attribute value into an HTML document is not recommended, as this may allow a malicious individual to include HTML tags in the label that mislead viewers of the entire document in which the labeledURI value was inserted. Acknowledgments Paul-Andre Pays, Martijn Koster, Tim Howes, Rakesh Patel, Russ Wright, and Hallvard Furuseth provided invaluable assistance in the creation of this document. This material is based in part upon work supported by the National Science Foundation under Grant No. NCR-9416667. Smith Standards Track [Page 3] RFC 2079 URI Attribute Type and Object Class January 1997 Appendix: The labeledURL Attribute Type (Deprecated) An earlier draft of this document defined an additional attribute type called labeledURL. This attribute type is deprecated, and should not be used when adding new values to directory entries. The original motivation for including a separate attribute type to hold URLs was that this would better enable efficient progammatic access to specific types of URIs. After some deliberation, the IETF-ASID working group concluded that it was better to simply have one attribute than two. The schema definition for labeledURL is included here for historical reference only. Directory client software may want to support this schema definition (in addition to labeledURI) to ease the transition away from labeledURL for those sites that are using it. Name: labeledURL ShortName: None Description: Uniform Resource Locator with optional label OID: umichAttributeType.41 (1.3.6.1.4.1.250.1.41) Syntax: caseExactString SizeRestriction: None SingleValued: False OID: umichAttributeType.41 (1.3.6.1.4.1.250.1.41) References [1] Berners-Lee, T., Masinter, L., and M. McCahill, "Uniform Resource Locators (URL)", RFC 1738, CERN, Xerox Corporation, University of Minnesota, December 1994. <URL:ftp://ds.internic.net/rfc/rfc1738.txt> [2] Berners-Lee, T., and D. Connolly, "Hypertext Markup Language - 2.0", RFC 1866, <URL:ftp://ds.internic.net/rfc/rfc1866.txt> [3] The Directory: Overview of Concepts, Models and Service. CCITT Recommendation X.500, 1988. [4] Information Processing Systems -- Open Systems Interconnection -- The Directory: Overview of Concepts, Models and Service. ISO/IEC JTC 1/SC21; International Standard 9594-1, 1988. Smith Standards Track [Page 4] RFC 2079 URI Attribute Type and Object Class January 1997 Author's Address Mark Smith Netscape Communications Corp. 501 E. Middlefield Rd. Mountain View, CA 94043, USA Phone: +1 415 937-3477 EMail: mcs@netscape.com Smith Standards Track [Page 5] PK )�c\{��3M] M] ( doc/alt-openldap11-devel/rfc/rfc4515.txtnu �[��� Network Working Group M. Smith, Ed. Request for Comments: 4515 Pearl Crescent, LLC Obsoletes: 2254 T. Howes Category: Standards Track Opsware, Inc. June 2006 Lightweight Directory Access Protocol (LDAP): String Representation of Search Filters Status of This Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2006). Abstract Lightweight Directory Access Protocol (LDAP) search filters are transmitted in the LDAP protocol using a binary representation that is appropriate for use on the network. This document defines a human-readable string representation of LDAP search filters that is appropriate for use in LDAP URLs (RFC 4516) and in other applications. Table of Contents 1. Introduction ....................................................2 2. LDAP Search Filter Definition ...................................2 3. String Search Filter Definition .................................3 4. Examples ........................................................5 5. Security Considerations .........................................7 6. Normative References ............................................7 7. Informative References ..........................................8 8. Acknowledgements ................................................8 Appendix A: Changes Since RFC 2254 .................................9 A.1. Technical Changes ..........................................9 A.2. Editorial Changes ..........................................9 Smith and Howes Standards Track [Page 1] RFC 4515 LDAP: String Representation of Search Filters June 2006 1. Introduction The Lightweight Directory Access Protocol (LDAP) [RFC4510] defines a network representation of a search filter transmitted to an LDAP server. Some applications may find it useful to have a common way of representing these search filters in a human-readable form; LDAP URLs [RFC4516] are an example of one such application. This document defines a human-readable string format for representing the full range of possible LDAP version 3 search filters, including extended match filters. This document is a integral part of the LDAP technical specification [RFC4510], which obsoletes the previously defined LDAP technical specification, RFC 3377, in its entirety. This document replaces RFC 2254. Changes to RFC 2254 are summarized in Appendix A. 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]. 2. LDAP Search Filter Definition An LDAP search filter is defined in Section 4.5.1 of [RFC4511] as follows: Filter ::= CHOICE { and [0] SET SIZE (1..MAX) OF filter Filter, or [1] SET SIZE (1..MAX) OF filter Filter, not [2] Filter, equalityMatch [3] AttributeValueAssertion, substrings [4] SubstringFilter, greaterOrEqual [5] AttributeValueAssertion, lessOrEqual [6] AttributeValueAssertion, present [7] AttributeDescription, approxMatch [8] AttributeValueAssertion, extensibleMatch [9] MatchingRuleAssertion } SubstringFilter ::= SEQUENCE { type AttributeDescription, -- initial and final can occur at most once substrings SEQUENCE SIZE (1..MAX) OF substring CHOICE { initial [0] AssertionValue, any [1] AssertionValue, final [2] AssertionValue } } Smith and Howes Standards Track [Page 2] RFC 4515 LDAP: String Representation of Search Filters June 2006 AttributeValueAssertion ::= SEQUENCE { attributeDesc AttributeDescription, assertionValue AssertionValue } MatchingRuleAssertion ::= SEQUENCE { matchingRule [1] MatchingRuleId OPTIONAL, type [2] AttributeDescription OPTIONAL, matchValue [3] AssertionValue, dnAttributes [4] BOOLEAN DEFAULT FALSE } AttributeDescription ::= LDAPString -- Constrained to <attributedescription> -- [RFC4512] AttributeValue ::= OCTET STRING MatchingRuleId ::= LDAPString AssertionValue ::= OCTET STRING LDAPString ::= OCTET STRING -- UTF-8 encoded, -- [Unicode] characters The AttributeDescription, as defined in [RFC4511], is a string representation of the attribute description that is discussed in [RFC4512]. The AttributeValue and AssertionValue OCTET STRING have the form defined in [RFC4517]. The Filter is encoded for transmission over a network using the Basic Encoding Rules (BER) defined in [X.690], with simplifications described in [RFC4511]. 3. String Search Filter Definition The string representation of an LDAP search filter is a string of UTF-8 [RFC3629] encoded Unicode characters [Unicode] that is defined by the following grammar, following the ABNF notation defined in [RFC4234]. The productions used that are not defined here are defined in Section 1.4 (Common ABNF Productions) of [RFC4512] unless otherwise noted. The filter format uses a prefix notation. filter = LPAREN filtercomp RPAREN filtercomp = and / or / not / item and = AMPERSAND filterlist or = VERTBAR filterlist not = EXCLAMATION filter filterlist = 1*filter item = simple / present / substring / extensible simple = attr filtertype assertionvalue filtertype = equal / approx / greaterorequal / lessorequal Smith and Howes Standards Track [Page 3] RFC 4515 LDAP: String Representation of Search Filters June 2006 equal = EQUALS approx = TILDE EQUALS greaterorequal = RANGLE EQUALS lessorequal = LANGLE EQUALS extensible = ( attr [dnattrs] [matchingrule] COLON EQUALS assertionvalue ) / ( [dnattrs] matchingrule COLON EQUALS assertionvalue ) present = attr EQUALS ASTERISK substring = attr EQUALS [initial] any [final] initial = assertionvalue any = ASTERISK *(assertionvalue ASTERISK) final = assertionvalue attr = attributedescription ; The attributedescription rule is defined in ; Section 2.5 of [RFC4512]. dnattrs = COLON "dn" matchingrule = COLON oid assertionvalue = valueencoding ; The <valueencoding> rule is used to encode an <AssertionValue> ; from Section 4.1.6 of [RFC4511]. valueencoding = 0*(normal / escaped) normal = UTF1SUBSET / UTFMB escaped = ESC HEX HEX UTF1SUBSET = %x01-27 / %x2B-5B / %x5D-7F ; UTF1SUBSET excludes 0x00 (NUL), LPAREN, ; RPAREN, ASTERISK, and ESC. EXCLAMATION = %x21 ; exclamation mark ("!") AMPERSAND = %x26 ; ampersand (or AND symbol) ("&") ASTERISK = %x2A ; asterisk ("*") COLON = %x3A ; colon (":") VERTBAR = %x7C ; vertical bar (or pipe) ("|") TILDE = %x7E ; tilde ("~") Note that although both the <substring> and <present> productions in the grammar above can produce the "attr=*" construct, this construct is used only to denote a presence filter. The <valueencoding> rule ensures that the entire filter string is a valid UTF-8 string and provides that the octets that represent the ASCII characters "*" (ASCII 0x2a), "(" (ASCII 0x28), ")" (ASCII 0x29), "\" (ASCII 0x5c), and NUL (ASCII 0x00) are represented as a backslash "\" (ASCII 0x5c) followed by the two hexadecimal digits representing the value of the encoded octet. Smith and Howes Standards Track [Page 4] RFC 4515 LDAP: String Representation of Search Filters June 2006 This simple escaping mechanism eliminates filter-parsing ambiguities and allows any filter that can be represented in LDAP to be represented as a NUL-terminated string. Other octets that are part of the <normal> set may be escaped using this mechanism, for example, non-printing ASCII characters. For AssertionValues that contain UTF-8 character data, each octet of the character to be escaped is replaced by a backslash and two hex digits, which form a single octet in the code of the character. For example, the filter checking whether the "cn" attribute contained a value with the character "*" anywhere in it would be represented as "(cn=*\2a*)". As indicated by the <valueencoding> rule, implementations MUST escape all octets greater than 0x7F that are not part of a valid UTF-8 encoding sequence when they generate a string representation of a search filter. Implementations SHOULD accept as input strings that are not valid UTF-8 strings. This is necessary because RFC 2254 did not clearly define the term "string representation" (and in particular did not mention that the string representation of an LDAP search filter is a string of UTF-8-encoded Unicode characters). 4. Examples This section gives a few examples of search filters written using this notation. (cn=Babs Jensen) (!(cn=Tim Howes)) (&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*))) (o=univ*of*mich*) (seeAlso=) The following examples illustrate the use of extensible matching. (cn:caseExactMatch:=Fred Flintstone) (cn:=Betty Rubble) (sn:dn:2.4.6.8.10:=Barney Rubble) (o:dn:=Ace Industry) (:1.2.3:=Wilma Flintstone) (:DN:2.4.6.8.10:=Dino) The first example shows use of the matching rule "caseExactMatch." The second example demonstrates use of a MatchingRuleAssertion form without a matchingRule. Smith and Howes Standards Track [Page 5] RFC 4515 LDAP: String Representation of Search Filters June 2006 The third example illustrates the use of the ":oid" notation to indicate that the matching rule identified by the OID "2.4.6.8.10" should be used when making comparisons, and that the attributes of an entry's distinguished name should be considered part of the entry when evaluating the match (indicated by the use of ":dn"). The fourth example denotes an equality match, except that DN components should be considered part of the entry when doing the match. The fifth example is a filter that should be applied to any attribute supporting the matching rule given (since the <attr> has been omitted). The sixth and final example is also a filter that should be applied to any attribute supporting the matching rule given. Attributes supporting the matching rule contained in the DN should also be considered. The following examples illustrate the use of the escaping mechanism. (o=Parens R Us \28for all your parenthetical needs\29) (cn=*\2A*) (filename=C:\5cMyFile) (bin=\00\00\00\04) (sn=Lu\c4\8di\c4\87) (1.3.6.1.4.1.1466.0=\04\02\48\69) The first example shows the use of the escaping mechanism to represent parenthesis characters. The second shows how to represent a "*" in an assertion value, preventing it from being interpreted as a substring indicator. The third illustrates the escaping of the backslash character. The fourth example shows a filter searching for the four-octet value 00 00 00 04 (hex), illustrating the use of the escaping mechanism to represent arbitrary data, including NUL characters. The fifth example illustrates the use of the escaping mechanism to represent various non-ASCII UTF-8 characters. Specifically, there are 5 characters in the <assertionvalue> portion of this example: LATIN CAPITAL LETTER L (U+004C), LATIN SMALL LETTER U (U+0075), LATIN SMALL LETTER C WITH CARON (U+010D), LATIN SMALL LETTER I (U+0069), and LATIN SMALL LETTER C WITH ACUTE (U+0107). The sixth and final example demonstrates assertion of a BER-encoded value. Smith and Howes Standards Track [Page 6] RFC 4515 LDAP: String Representation of Search Filters June 2006 5. Security Considerations This memo describes a string representation of LDAP search filters. While the representation itself has no known security implications, LDAP search filters do. They are interpreted by LDAP servers to select entries from which data is retrieved. LDAP servers should take care to protect the data they maintain from unauthorized access. Please refer to the Security Considerations sections of [RFC4511] and [RFC4513] for more information. 6. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003. [RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 4234, October 2005. [RFC4510] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006. [RFC4511] Sermersheim, J., Ed., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006. [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006. [RFC4513] Harrison, R., Ed., "Lightweight Directory Access Protocol (LDAP): Authentication Methods and Security Mechanisms", RFC 4513, June 2006. [RFC4517] Legg, S., Ed., "Lightweight Directory Access Protocol (LDAP): Syntaxes and Matching Rules", RFC 4517, June 2006. [Unicode] The Unicode Consortium, "The Unicode Standard, Version 3.2.0" is defined by "The Unicode Standard, Version 3.0" (Reading, MA, Addison-Wesley, 2000. ISBN 0-201-61633-5), as amended by the "Unicode Standard Annex #27: Unicode 3.1" (http://www.unicode.org/reports/tr27/) and by the "Unicode Standard Annex #28: Unicode 3.2." Smith and Howes Standards Track [Page 7] RFC 4515 LDAP: String Representation of Search Filters June 2006 7. Informative References [RFC4516] Smith, M., Ed. and T. Howes, "Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator", RFC 4516, June 2006. [X.690] Specification of ASN.1 encoding rules: Basic, Canonical, and Distinguished Encoding Rules, ITU-T Recommendation X.690, 1994. 8. Acknowledgements This document replaces RFC 2254 by Tim Howes. RFC 2254 was a product of the IETF ASID Working Group. Changes included in this revised specification are based upon discussions among the authors, discussions within the LDAP (v3) Revision Working Group (ldapbis), and discussions within other IETF Working Groups. The contributions of individuals in these working groups is gratefully acknowledged. Smith and Howes Standards Track [Page 8] RFC 4515 LDAP: String Representation of Search Filters June 2006 Appendix A: Changes Since RFC 2254 A.1. Technical Changes Replaced [ISO 10646] reference with [Unicode]. The following technical changes were made to the contents of the "String Search Filter Definition" section: Added statement that the string representation is a string of UTF-8- encoded Unicode characters. Revised all of the ABNF to use common productions from [RFC4512]. Replaced the "value" rule with a new "assertionvalue" rule within the "simple", "extensible", and "substring" ("initial", "any", and "final") rules. This matches a change made in [RFC4517]. Added "(" and ")" around the components of the <extensible> subproductions for clarity. Revised the "attr", "matchingrule", and "assertionvalue" ABNF to more precisely reference productions from the [RFC4512] and [RFC4511] documents. "String Search Filter Definition" section: replaced "greater" and "less" with "greaterorequal" and "lessorequal" to avoid confusion. Introduced the "valueencoding" and associated "normal" and "escaped" rules to reduce the dependence on descriptive text. The "normal" production restricts filter strings to valid UTF-8 sequences. Added a statement about expected behavior in light of RFC 2254's lack of a clear definition of "string representation." A.2. Editorial Changes Changed document title to include "LDAP:" prefix. IESG Note: removed note about lack of satisfactory mandatory authentication mechanisms. Header and "Authors' Addresses" sections: added Mark Smith as the document editor and updated affiliation and contact information. "Table of Contents" and "Intellectual Property" sections: added. Copyright: updated per latest IETF guidelines. Smith and Howes Standards Track [Page 9] RFC 4515 LDAP: String Representation of Search Filters June 2006 "Abstract" section: separated from introductory material. "Introduction" section: new section; separated from the Abstract. Updated second paragraph to indicate that RFC 2254 is replaced by this document (instead of RFC 1960). Added reference to the [RFC4510] document. "LDAP Search Filter Definition" section: made corrections to the LDAP search filter ABNF so it matches that used in [RFC4511]. Clarified the definition of 'value' (now 'assertionvalue') to take into account the fact that it is not precisely an AttributeAssertion from [RFC4511] Section 4.1.6 (special handling is required for some characters). Added a note that each octet of a character to be escaped is replaced by a backslash and two hex digits, which represent a single octet. "Examples" section: added four additional examples: (seeAlso=), (cn:=Betty Rubble), (:1.2.3:=Wilma Flintstone), and (1.3.6.1.4.1.1466.0=\04\02\48\69). Replaced one occurrence of "a value" with "an assertion value". Corrected the description of this example: (sn:dn:2.4.6.8.10:=Barney Rubble). Replaced the numeric OID in the first extensible match example with "caseExactMatch" to demonstrate use of the descriptive form. Used "DN" (uppercase) in the last extensible match example to remind the reader to treat the <dnattrs> production as case insensitive. Reworded the description of the fourth escaping mechanism example to avoid making assumptions about byte order. Added text to the fifth escaping mechanism example to spell out what the non-ASCII characters are in Unicode terms. "Security Considerations" section: added references to [RFC4511] and [RFC4513]. "Normative References" section: renamed from "References" per new RFC guidelines. Changed from [1] style to [RFC4511] style throughout the document. Added entries for [Unicode], [RFC2119], [RFC4513], [RFC4512], and [RFC4510] and updated the UTF-8 reference. Replaced RFC 822 reference with a reference to RFC 4234. "Informative References" section: (new section) moved [X.690] to this section. Added a reference to [RFC4516]. "Acknowledgements" section: added. "Appendix A: Changes Since RFC 2254" section: added. Surrounded the names of all ABNF productions with "<" and ">" where they are used in descriptive text. Smith and Howes Standards Track [Page 10] RFC 4515 LDAP: String Representation of Search Filters June 2006 Replaced all occurrences of "LDAPv3" with "LDAP." Authors' Addresses Mark Smith, Editor Pearl Crescent, LLC 447 Marlpool Dr. Saline, MI 48176 USA Phone: +1 734 944-2856 EMail: mcs@pearlcrescent.com Tim Howes Opsware, Inc. 599 N. Mathilda Ave. Sunnyvale, CA 94085 USA Phone: +1 408 744-7509 EMail: howes@opsware.com Smith and Howes Standards Track [Page 11] RFC 4515 LDAP: String Representation of Search Filters June 2006 Full Copyright Statement Copyright (C) The Internet Society (2006). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Smith and Howes Standards Track [Page 12] PK *�c\�䗚�O �O ( doc/alt-openldap11-devel/rfc/rfc2649.txtnu �[��� Network Working Group B. Greenblatt Request for Comments: 2649 P. Richard Category: Experimental August 1999 An LDAP Control and Schema for Holding Operation Signatures Status of this Memo This memo defines an Experimental Protocol for the Internet community. It does not specify an Internet standard of any kind. Discussion and suggestions for improvement are requested. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (1999). All Rights Reserved. Abstract In many environments clients require the ability to validiate the source and integrity of information provided by the directory. This document describes an LDAP message control which allows for the retrieval of digitally signed information. This document defines an LDAP v3 based mechanism for signing directory operations in order to create a secure journal of changes that have been made to each directory entry. Both client and server based signatures are supported. An object class for subsequent retrieval are "journal entries" is also defined. This document specifies LDAP v3 controls that enable this functionality. It also defines an LDAP v3 schema that allows for subsequent browsing of the journal information. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1 Audit Trail Mechanism . . . . . . . . . . . . . . . . . . . 2 1.2. Handling the Delete Operation . . . . . . . . . . . . . . . 5 2. Signed Results Mechanism . . . . . . . . . . . . . . . . . . 6 3. Security Considerations and Other Notes . . . . . . . . . . 7 4. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 5. Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 9 6. Full Copyright Statement . . . . . . . . . . . . . . . . . . 10 Greenblatt & Richard Experimental [Page 1] RFC 2649 LDAP Control and Schema August 1999 1. Introduction In many environments clients require the ability to validiate the source and integrity of information provided by the directory. This document describes an LDAP message control which allows for the retrieval of digitally signed information. The perspective of this document is that the origin of the information that is stored in LDAP v3 accessible directories is the LDAP v3 client that creates the information. The source and integrity of the information is guaranteed by allowing for the digital signing of the operations that make changes to entries in the directory. The source and integrity of an individual LDAP connection can be guaranteed by making use of an underlying session layer that provides such services, such as TLS. Note that the integrity of an individual connection does not, in and of itself guarantee the integrity of the data that comes across the connection. This is due to the fact that the LDAP server is only capable of providing information that it has stored. In distributed and replicated environments, the fact that an entry has been successfully retrieved from a server may not be completely reassuring, if the entry in question was replicated from an untrusted domain. By making use of public key technology, and creating digitally signed transactions that are created by the LDAP v3 client as entries are created and modified, a complete journal of the history of the entry is available. Since each entry in the journal has been digitally signed with the private key of the creator, or modifier of the entry, the source and integrity of the directory entry can be validated by verifying the signature of each entry in the journal. Note that not all of the journal entries will have been signed by the same user. 1.1. Audit Trail Mechanism Signed directory operations is a straightforward application of S/MIME technology that also leverages the extensible framework that is provided by LDAP version 3. LDAP version 3 is defined in [4], and S/MIME is defined in [2]. The security used in S/MIME is based in the definitions in [1]. The basic idea is that the submitter of an LDAP operation that changes the directory information includes an LDAP version 3 control that includes either a signature of the operation, or a request that the LDAP server sign the operation on the behalf of the LDAP client. The result of the operation (in addition to the change of the directory information), is additional information that is attached to directory objects, that includes the audit trail of signed operations. The LDAP control is (OID = 1.2.840.113549.6.0.0): Greenblatt & Richard Experimental [Page 2] RFC 2649 LDAP Control and Schema August 1999 SignedOperation ::= CHOICE { signbyServer NULL, signatureIncluded OCTET STRING } If the SignatureIncluded CHOICE is used, then the OCTET string is just an S/MIME message of the multipart/signed variety, that is composed of a single piece, that is the signature of the directory operation. Multipart/signed MIME objects are defined in [3]. If the SignbyServer CHOICE us used, then the LDAP server creates the signature on behalf of the client, using its own identity and not the identity of the client, in order to produce the audit trail entry. In either case the successful result of processing the control is the creation of additional information in the directory entry that is being modified or created. The signature of the LDAP operation is computed on the LDAPMessage prior to the inclusion of the SignedOperation control. The procedure is as follows: - Build LDAPMessage without the SignedOperation control - Compute signature on the above LDAPMessage - Create new LDAPMessage that includes the old MessageID, protocolOp and any control fields from the previous LDAPMessage, plus the computed signature formatted as an S/MIME message. No control is defined for the server to return in the LDAPResult as defined in [4]. The LDAP server MAY attempt to parse and verify the signature included in the SignedOperation control, but is not required to. The server can accept the signed operation without verifying the signature. Signature verification can be quite a lengthy operation, requiring complex certificate chain traversals. This allows a more timely creation of the audit trail by the server. Any LDAP client browsing the directory that retrieves the 'Changes' (defined in the following paragraphs) attributes, should verify the signature of each value according to the local signature verification policies. Even if the LDAP server verifies the signature contained in the singed operation, the LDAP client has no way of knowing what policies were followed by the server in order to verify the signature. If the LDAP server is unable to verify the signature and wishes to return an error then the error code unwillingToPerform(53) should be returned, and the entire LDAP operation fails. In this situation, an appropriate message (e.g. "Unable to verify signature") MAY be included in the errorMessage of the LDAPResult. The SignedOperation Control MAY be marked CRITICAL, and if it is CRITICAL then if the LDAP Server performs the LDAP operation, then must include the signature in the signedAuditTrail information. Greenblatt & Richard Experimental [Page 3] RFC 2649 LDAP Control and Schema August 1999 The schema definition for the signedAuditTrail information is: ( 1.2.840.113549.6.1.0 NAME 'signedAuditTrail' SUP top AUXILIARY MUST ( Changes ) ) The format of the Changes attribute is: ( 1.2.840.113549.6.2.0 NAME 'Changes' DESC 'a set of changes applied to an entry' SYNTAX 'Binary' ) The actual format of the Changes attribute is: Changes ::= SEQUENCE { sequenceNumber [0] INTEGER (0 .. maxInt), signedOperation [1] OCTET STRING } The SignedOperation attribute is a multipart/signed S/MIME message. Part 1 of the message is the directory operation, and part 2 is the signature. Sequence number 0 (if present) always indicates the starting point directory object as represented by the definitions in "A MIME Content-Type for Directory Information", as defined in [5]. Subsequent sequence numbers indicate the sequence of changes that have been made to this directory object. Note that the sequence of the changes can be verified due to the fact that the signed directory object will have a timestamp as part of the signature object, and that the sequence numbering as part of the change attribute should be considered to be an unverified aid to the LDAP client. Sequence numbers are meaningful only within the context of a single directory entry, and LDAP servers are not expected to maintain these sequence numbers across all entries in the directory. Some LDAP servers will only allow operations that include the SignedOperation control. This is indicated by the inclusion of a 'signedDirectoryOperationSupport' attribute in the rootDSE. This attribute is defined as: Greenblatt & Richard Experimental [Page 4] RFC 2649 LDAP Control and Schema August 1999 1.2.840.113549.6.2.2 NAME 'signedDirectoryOperationSupport' DESC 'how many of the LDAP operations must be signed' SYNTAX 'Integer' SINGLE-VALUE ) The 'signedDirectoryOperationSupport' attribute above may have one of the values, '0', '1' or '2' with the following meanings: - '0' Directory Operations may be signed - '1' Directory Operations must always be signed - '2' Directory Operations must never be signed Some LDAP servers will desire that the audit trail be continuous, and not contain any gaps that would result from unsigned operations. Such server will include a signature on each LDAP operation that changes a directory entry, even when the LDAP client does not include a signed-Operation control. 1.2. Handling the Delete Operation The LDAP Delete operation represents an interesting case for Signed Directory Operations. This is due to the case that subsequent to the successful completion of the Delete Operation, the object that would have held the latest 'Changes' attribute no longer exists. In order to handle this situation, a new object class is defined to represent a directory object that has been deleted. ( 1.2.840.113549.6.1.2 NAME 'zombieObject' SUP top STRUCTURAL MUST ( Cn $ Changes $ OriginalObject ) ) The format of the OriginalObject attribute is: ( 1.2.840.113549.6.2.1 NAME OriginalObject DESC 'The LDAP URL of an object that has been deleted from the directory' SYNTAX 'Binary' ) The OriginalObject attribute contains the URL of the object that was deleted from the directory. It is formatted in accordance with RFC 2255. Directory servers that comply with this specification SHOULD create a zombieObject when performing the delete Operation that contains a SignedOperation LDAPControl. The Cn attribute of the Greenblatt & Richard Experimental [Page 5] RFC 2649 LDAP Control and Schema August 1999 zombieObject is synthesized by the LDAP server, and may or may not be related to the original name of the directory entry that was deleted. All changes attributes that were attached to the original entry are copied over to the zombieObject. In addition the LDAP Server MUST attach the signature of the Delete operation as the last successful change that was made to the entry. 2. Signed Results Mechanism A control is also defined that allows the LDAP v3 client to request that the server sign the results that it returns. It is intended that this control is primarily used in concert with the LDAPSearch operation. This control MAY be marked as CRITICAL. If it is marked as CRITICAL and the LDAP Server supports this operation, then all search results MUST be returned with a signature as attached in the SignedResult control if it is willing to sign results for this user. If the server supports this control but does not wish to sign the results for this user then the error code unwillingToPerform(53) should be returned, and the LDAP search will have failed. In this situation, an appropriate message (e.g. "Unwilling to sign results for you!") MUST be included in the errorMessage of the LDAPResult. If the LDAPSigType has the value FALSE then the client is requesting that the server not sign this operation. This may be done in situations where servers are configured to always sign their operations. The LDAP control to include in the LDAP request is (OID = 1.2.840.113549.6.0.1): DemandSignedResult ::= LDAPSigType LDAPSigType ::= BOOLEAN In response to a DemandSignedResult control, the LDAP v3 server will return a SignedResult control in addition to the normal result as defined by the operation (assuming that the server understands the con- trol, and is willing to perform it). The SignedResult control MUST NOT be marked CRITICAL. Some LDAP v3 servers may be configured to sign all of their operations. In this situation the server always returns a SignedResult control, unless instructed otherwise by the DemandSigne-dResult Control. Since the SignedResult control is not marked critical, the LDAP client is allowed to ignore it. The signature field below includes the signature of the enitre LDAPResult formatted as an S/MIME pkcs-7/signature object, as defined in [2]. Greenblatt & Richard Experimental [Page 6] RFC 2649 LDAP Control and Schema August 1999 The procedure for creating the signature of the signedResult control is the same as the procedure for the creation of the signedOperation control. The LDAP control in the LDAP response is (OID = 1.2.840.113549.6.0.2): SignedResult ::= CHOICE { signature OCTET STRING } 3. Security Considerations and Other Notes The base OIDs are: rsadsiLdap ::= {1 2 840 113549 6} rsadsiLdapControls ::= {1 2 840 113549 6 0} rsadsiLdapObjectClasses ::= {1 2 840 113549 6 1} rsadsiLdapAttributes ::= {1 2 840 113549 6 2} The complete ASN.1 module for this specification is: SIGNEDOPERATIONS DEFINITIONS ::= BEGIN SignedOperation ::= CHOICE { signbyServer NULL, signatureIncluded OCTET STRING } Changes ::= SEQUENCE { sequenceNumber [0] INTEGER (0 .. maxInt), signedOperation [1] OCTET STRING } DemandSignedResult ::= LDAPSigType LDAPSigType ::= BOOLEAN SignedResult ::= CHOICE { signature OCTET STRING } END Greenblatt & Richard Experimental [Page 7] RFC 2649 LDAP Control and Schema August 1999 If any of the controls in this specification are supported by an LDAP v3 server then that server MUST make available its certificate (if any) in the userCertificate attribute of its rootDSE object. The UserCertificate attribute is defined in [6], and contains the public key of the server that is used in the creation of the various signatures defined in this specification. It is not the intention of this specification to provide a mechanism that guarantees the origin and integrity of LDAP v3 operations. Such a service is best provided by the use of an underlying protocol such as TLS [8]. TLS defines additional features such as encryption and compression. This specification does not define support for encrypted operations. This memo proposes protocol elements for transmission and storage of the digital signatures of LDAP operations. Though the LDAP server may have verified the operation signatures prior to their storage and subsequent retrieval, it is prudent for LDAP clients to verify the signatures contained in the chained attribute upon their retrieval. The issuing Certification Authorities of the signer's certificate should also be consulted in order to determine if the signer's private key has been compromised or the certificate has been otherwise revoked. Security considerations are discussed throughout this memo. 4. References [1] Kaliski, B., "PKCS 7: Cryptographic Message Syntax Version 1-5", RFC 2315, March 1998. [2] Dusse, S., Hoffman, P., Ramsdell, B., Lundblade, L. and L. Repka., "S/MIME Version 2 Message Specification", RFC 2311, March 1998. [3] Galvin, J., Murphy, S., Crocker, S. and N. Freed, "Security Multiparts for MIME: Multipart/Signed and Multipart/Encrypted", RFC 1847, October 1995. [4] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [5] Howes, T., Smith, M. and F. Dawson, "A MIME Content-Type for Directory Information", RFC 2425, September 1998. [6] Wahl, M., "A Summary of the X.500(96) User Schema for use with LDAPv3", RFC 2256, December 1997. Greenblatt & Richard Experimental [Page 8] RFC 2649 LDAP Control and Schema August 1999 [7] Howes, T. and M. Smith, "The LDAP URL Format", RFC 2255, December 1997. [8] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", RFC 2246, January 1999. 5. Authors' Addresses Bruce Greenblatt San Jose, CA 95119 USA Phone: +1-408-224-5349 EMail: bgreenblatt@directory-applications.com Pat Richard Xcert Software, Inc. Suite 1001 - 701 W. Georgia Vancouver, BC CANADA V6G 1C9 EMail: patr@xcert.com Greenblatt & Richard Experimental [Page 9] RFC 2649 LDAP Control and Schema August 1999 6. Full Copyright Statement Copyright (C) The Internet Society (1999). 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. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Greenblatt & Richard Experimental [Page 10] PK *�c\fb@�u9 u9 ( doc/alt-openldap11-devel/rfc/rfc2714.txtnu �[��� Network Working Group V. Ryan Request for Comments: 2714 R. Lee Category: Informational S. Seligman Sun Microsystems, Inc. October 1999 Schema for Representing CORBA Object References in an LDAP Directory Status of this Memo This memo provides information for the Internet community. It does not specify an Internet standard of any kind. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (1999). All Rights Reserved. Abstract CORBA [CORBA] is the Common Object Request Broker Architecture defined by the Object Management Group. This document defines the schema for representing CORBA object references in an LDAP directory [LDAPv3]. 1. Introduction This document assumes that the reader has a general understanding of CORBA. Traditionally, LDAP directories have been used to store data. Users and programmers think of the directory as a hierarchy of directory entries, each containing a set of attributes. You look up an entry from the directory and extract the attribute(s) of interest. For example, you can look up a person's telephone number from the directory. Alternatively, you can search the directory for entries with a particular set of attributes. For example, you can search for all persons in the directory with the surname "Smith". CORBA applications require access to CORBA objects. Traditionally, CORBA applications have used the COS Naming service for storage and retrieval of CORBA object references. When deployed in environments with a directory, CORBA applications should be able to use the directory as a repository for CORBA object references. The directory provides a centrally administered, and possibly replicated, service for use by CORBA applications distributed across the network. Ryan, et al. Informational [Page 1] RFC 2714 Schema for CORBA Object References October 1999 For example, an application server may use the directory for "registering" CORBA objects representing the services that it manages, so that a client can later search the directory to locate those services as it needs. The motivation for this document is to define a common way for applications to store and retrieve CORBA object references from the directory. Using this common schema, any CORBA application that needs to read or store CORBA object references in the directory can do so in an interoperable way. Note that this schema is defined for storing CORBA "object references," not CORBA objects in general. There might be other ways to store CORBA objects in an LDAP directory but they are not covered by this schema. 2. Representation of CORBA Object References This document defines schema elements to represent a CORBA object reference in LDAP directory. Applications in possession of a reference to an object can invoke calls on that object. Such a reference is termed an "interoperable object reference," or IOR. Access to CORBA objects by using IORs is achieved transparently to the application, by means of the General Inter-ORB Protocol. A CORBA object reference is represented in the directory by the object class corbaObjectReference. corbaObjectReference is a subclass of the abstract corbaObject object class. corbaObjectReference is an auxiliary object class, which means that it needs to be mixed in with a structural object class. The object class corbaContainer is used in a directory entry which represents a CORBA object or object reference. It is a structural object class, and when representing an object reference, the corbaObjectReference object class would also need to be present in the entry. corbaContainer is not required when a subclass of corbaObject (such as corbaObjectReference) is mixed in with another structural object class. The definitions for the object classes corbaObject, corbaObjectReference, and corbaContainer are presented in Section 4. The corbaObject class has two optional attributes: corbaRepositoryId and description. corbaRepositoryId is a multivalued attribute that is used to store the repository ids of the interfaces implemented by a CORBA object. description is used to store a textual description of a CORBA object. Ryan, et al. Informational [Page 2] RFC 2714 Schema for CORBA Object References October 1999 The corbaObjectReference class has one mandatory attribute: corbaIor. corbaIor is used to store the object's stringified IOR. corbaIor and corbaRepositoryId are defined in Section 3; description is defined in [v3Schema]. 3. Attribute Type Definitions The following attribute types are defined in this document: corbaIor corbaRepositoryId 3.1 corbaIor This attribute stores the string representation of the interoperable object reference (IOR) for a CORBA object. An IOR is an opaque handle for the object which contains the information necessary to locate the object, even if the object is in another ORB. This attribute's syntax is 'IA5 String' and its case is insignificant. ( 1.3.6.1.4.1.42.2.27.4.1.14 NAME 'corbaIor' DESC 'Stringified interoperable object reference of a CORBA object' EQUALITY caseIgnoreIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 SINGLE-VALUE ) 3.2 corbaRepositoryId Each CORBA interface has a unique "repository id" (also called "type id") that identifies the interface. A CORBA object has one or more repository ids, one for each interface that it implements. The format of a repository id can be any string, but the OMG specifies four standard formats: a. IDL-style IDL:Prefix/ModuleName/InterfaceName:VersionNumber Ryan, et al. Informational [Page 3] RFC 2714 Schema for CORBA Object References October 1999 For example, the repository id for the "NamingContext" in OMG's COS Naming module is: "IDL:omg.org/CosNaming/NamingContext:1.0". b. RMI-style RMI:ClassName:HashCode[:SUID] This format is used by RMI-IIOP remote objects [RMI-IIOP]. "ClassName" is the fully qualified name of the class (for example, "java.lang.String"). "HashCode" is the object's hash code (that is, that obtained by invoking the "hashCode()" method). "SUID" is the "stream unique identifier", which is a 64-bit number that uniquely identifies the serialization version of the class; SUID is optional in the repository id. c. DCE-style DCE:UUID This format is used for DCE/CORBA interoperability [CORBA-DCE]. "UUID" represents a DCE UUID. d. "local" This format is defined by the local Object Request Broker (ORB). The corbaRepositoryId attribute is a multivalued attribute; each value records a single repository id of an interface implemented by the CORBA object. This attribute need not contain a complete list of the interfaces implemented by the CORBA object. This attribute's syntax is 'Directory String' and its case is significant. The values of this attribute are encoded using UTF-8. Some values may require translation from their native representation in order to be correctly encoded using UTF-8. ( 1.3.6.1.4.1.42.2.27.4.1.15 NAME 'corbaRepositoryId' DESC 'Repository ids of interfaces implemented by a CORBA object' EQUALITY caseExactMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) Ryan, et al. Informational [Page 4] RFC 2714 Schema for CORBA Object References October 1999 4. Object Class Definitions The following object classes are defined in this document: corbaContainer corbaObject corbaObjectReference 4.1 corbaContainer This structural object class represents a container for a CORBA object. ( 1.3.6.1.4.1.42.2.27.4.2.10 NAME 'corbaContainer' DESC 'Container for a CORBA object' SUP top STRUCTURAL MUST ( cn ) ) 4.2 corbaObject This abstract object class is the root class for representing a CORBA object. ( 1.3.6.1.4.1.42.2.27.4.2.9 NAME 'corbaObject' DESC 'CORBA object representation' SUP top ABSTRACT MAY ( corbaRepositoryId $ description ) ) 4.3 corbaObjectReference This auxiliary object class represents a CORBA object reference. It must be mixed in with a structural object class. ( 1.3.6.1.4.1.42.2.27.4.2.11 NAME 'corbaObjectReference' DESC 'CORBA interoperable object reference' SUP corbaObject AUXILIARY MUST ( corbaIor ) ) Ryan, et al. Informational [Page 5] RFC 2714 Schema for CORBA Object References October 1999 5. Security Considerations Obtaining a reference to an object and storing it in the directory may make a handle to the object available to a wider audience. This may have security implications. 6. Acknowledgements We would like to thank Sanjeev Krishnan of Sun Microsystems, Simon Nash of IBM, and Jeffrey Spirn of Oracle for their comments and suggestions. 7. References [CORBA] The Object Management Group, "Common Object Request Broker Architecture Specification 2.2", http://www.omg.org [CORBA-DCE] Distributed Systems Technology Center and Digital Equipment Corporation, "DCE/CORBA Interworking Specification", May 1998. http://www.omg.org/library/schedule/ DCE_CORBA_Interworking_RFP.html [LDAPv3] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [RMI-IIOP] IBM and Java Software, Sun Microsystems, Inc., "RMI over IIOP", June 1999. http://java.sun.com/products/rmi- iiop/index.html [v3Schema] Wahl, M., "A Summary of the X.500(96) User Schema for use with LDAPv3", RFC 2256, December 1997. Ryan, et al. Informational [Page 6] RFC 2714 Schema for CORBA Object References October 1999 8. Authors' Addresses Vincent Ryan Sun Microsystems, Inc. Mail Stop EDUB03 901 San Antonio Road Palo Alto, CA 94303 USA Phone: +353 1 819 9151 EMail: vincent.ryan@ireland.sun.com Rosanna Lee Sun Microsystems, Inc. Mail Stop UCUP02-206 901 San Antonio Road Palo Alto, CA 94303 USA Phone: +1 408 863 3221 EMail: rosanna.lee@eng.sun.com Scott Seligman Sun Microsystems, Inc. Mail Stop UCUP02-209 901 San Antonio Road Palo Alto, CA 94303 USA Phone: +1 408 863 3222 EMail: scott.seligman@eng.sun.com Ryan, et al. Informational [Page 7] RFC 2714 Schema for CORBA Object References October 1999 9. Appendix - LDAP Schema -- Attribute types -- ( 1.3.6.1.4.1.42.2.27.4.1.14 NAME 'corbaIor' DESC 'Stringified interoperable object reference of a CORBA object' EQUALITY caseIgnoreIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 SINGLE-VALUE ) ( 1.3.6.1.4.1.42.2.27.4.1.15 NAME 'corbaRepositoryId' DESC 'Repository ids of interfaces implemented by a CORBA object' EQUALITY caseExactMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) -- from RFC-2256 -- ( 2.5.4.13 NAME 'description' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{1024} ) -- Object classes -- ( 1.3.6.1.4.1.42.2.27.4.2.9 NAME 'corbaObject' DESC 'CORBA object representation' SUP top ABSTRACT MAY ( corbaRepositoryId $ description ) ) ( 1.3.6.1.4.1.42.2.27.4.2.10 NAME 'corbaContainer' DESC 'Container for a CORBA object' SUP top STRUCTURAL MUST ( cn ) ) Ryan, et al. Informational [Page 8] RFC 2714 Schema for CORBA Object References October 1999 ( 1.3.6.1.4.1.42.2.27.4.2.11 NAME 'corbaObjectReference' DESC 'CORBA interoperable object reference' SUP corbaObject AUXILIARY MUST ( corbaIor ) ) -- Matching rule from ISO X.520 -- ( 2.5.13.5 NAME 'caseExactMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) Ryan, et al. Informational [Page 9] RFC 2714 Schema for CORBA Object References October 1999 10. Full Copyright Statement Copyright (C) The Internet Society (1999). 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. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Ryan, et al. Informational [Page 10] PK *�c\�s| s| ( doc/alt-openldap11-devel/rfc/rfc4514.txtnu �[��� Network Working Group K. Zeilenga, Ed. Request for Comments: 4514 OpenLDAP Foundation Obsoletes: 2253 June 2006 Category: Standards Track Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names Status of This Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2006). Abstract The X.500 Directory uses distinguished names (DNs) as primary keys to entries in the directory. This document defines the string representation used in the Lightweight Directory Access Protocol (LDAP) to transfer distinguished names. The string representation is designed to give a clean representation of commonly used distinguished names, while being able to represent any distinguished name. 1. Background and Intended Usage In X.500-based directory systems [X.500], including those accessed using the Lightweight Directory Access Protocol (LDAP) [RFC4510], distinguished names (DNs) are used to unambiguously refer to directory entries [X.501][RFC4512]. The structure of a DN [X.501] is described in terms of ASN.1 [X.680]. In the X.500 Directory Access Protocol [X.511] (and other ITU-defined directory protocols), DNs are encoded using the Basic Encoding Rules (BER) [X.690]. In LDAP, DNs are represented in the string form described in this document. It is important to have a common format to be able to unambiguously represent a distinguished name. The primary goal of this specification is ease of encoding and decoding. A secondary goal is to have names that are human readable. It is not expected that LDAP Zeilenga Standards Track [Page 1] RFC 4514 LDAP: Distinguished Names June 2006 implementations with a human user interface would display these strings directly to the user, but that they would most likely be performing translations (such as expressing attribute type names in the local national language). This document defines the string representation of Distinguished Names used in LDAP [RFC4511][RFC4517]. Section 2 details the RECOMMENDED algorithm for converting a DN from its ASN.1 structured representation to a string. Section 3 details how to convert a DN from a string to an ASN.1 structured representation. While other documents may define other algorithms for converting a DN from its ASN.1 structured representation to a string, all algorithms MUST produce strings that adhere to the requirements of Section 3. This document does not define a canonical string representation for DNs. Comparison of DNs for equality is to be performed in accordance with the distinguishedNameMatch matching rule [RFC4517]. This document is a integral part of the LDAP technical specification [RFC4510], which obsoletes the previously defined LDAP technical specification, RFC 3377, in its entirety. This document obsoletes RFC 2253. Changes since RFC 2253 are summarized in Appendix B. This specification assumes familiarity with X.500 [X.500] and the concept of Distinguished Name [X.501][RFC4512]. 1.1. Conventions 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]. Character names in this document use the notation for code points and names from the Unicode Standard [Unicode]. For example, the letter "a" may be represented as either <U+0061> or <LATIN SMALL LETTER A>. Note: a glossary of terms used in Unicode can be found in [Glossary]. Information on the Unicode character encoding model can be found in [CharModel]. Zeilenga Standards Track [Page 2] RFC 4514 LDAP: Distinguished Names June 2006 2. Converting DistinguishedName from ASN.1 to a String X.501 [X.501] defines the ASN.1 [X.680] structure of distinguished name. The following is a variant provided for discussion purposes. DistinguishedName ::= RDNSequence RDNSequence ::= SEQUENCE OF RelativeDistinguishedName RelativeDistinguishedName ::= SET SIZE (1..MAX) OF AttributeTypeAndValue AttributeTypeAndValue ::= SEQUENCE { type AttributeType, value AttributeValue } This section defines the RECOMMENDED algorithm for converting a distinguished name from an ASN.1-structured representation to a UTF-8 [RFC3629] encoded Unicode [Unicode] character string representation. Other documents may describe other algorithms for converting a distinguished name to a string, but only strings that conform to the grammar defined in Section 3 SHALL be produced by LDAP implementations. 2.1. Converting the RDNSequence If the RDNSequence is an empty sequence, the result is the empty or zero-length string. Otherwise, the output consists of the string encodings of each RelativeDistinguishedName in the RDNSequence (according to Section 2.2), starting with the last element of the sequence and moving backwards toward the first. The encodings of adjoining RelativeDistinguishedNames are separated by a comma (',' U+002C) character. 2.2. Converting RelativeDistinguishedName When converting from an ASN.1 RelativeDistinguishedName to a string, the output consists of the string encodings of each AttributeTypeAndValue (according to Section 2.3), in any order. Where there is a multi-valued RDN, the outputs from adjoining AttributeTypeAndValues are separated by a plus sign ('+' U+002B) character. Zeilenga Standards Track [Page 3] RFC 4514 LDAP: Distinguished Names June 2006 2.3. Converting AttributeTypeAndValue The AttributeTypeAndValue is encoded as the string representation of the AttributeType, followed by an equals sign ('=' U+003D) character, followed by the string representation of the AttributeValue. The encoding of the AttributeValue is given in Section 2.4. If the AttributeType is defined to have a short name (descriptor) [RFC4512] and that short name is known to be registered [REGISTRY] [RFC4520] as identifying the AttributeType, that short name, a <descr>, is used. Otherwise the AttributeType is encoded as the dotted-decimal encoding, a <numericoid>, of its OBJECT IDENTIFIER. The <descr> and <numericoid> are defined in [RFC4512]. Implementations are not expected to dynamically update their knowledge of registered short names. However, implementations SHOULD provide a mechanism to allow their knowledge of registered short names to be updated. 2.4. Converting an AttributeValue from ASN.1 to a String If the AttributeType is of the dotted-decimal form, the AttributeValue is represented by an number sign ('#' U+0023) character followed by the hexadecimal encoding of each of the octets of the BER encoding of the X.500 AttributeValue. This form is also used when the syntax of the AttributeValue does not have an LDAP- specific ([RFC4517], Section 3.1) string encoding defined for it, or the LDAP-specific string encoding is not restricted to UTF-8-encoded Unicode characters. This form may also be used in other cases, such as when a reversible string representation is desired (see Section 5.2). Otherwise, if the AttributeValue is of a syntax that has a LDAP- specific string encoding, the value is converted first to a UTF-8- encoded Unicode string according to its syntax specification (see [RFC4517], Section 3.3, for examples). If that UTF-8-encoded Unicode string does not have any of the following characters that need escaping, then that string can be used as the string representation of the value. - a space (' ' U+0020) or number sign ('#' U+0023) occurring at the beginning of the string; - a space (' ' U+0020) character occurring at the end of the string; Zeilenga Standards Track [Page 4] RFC 4514 LDAP: Distinguished Names June 2006 - one of the characters '"', '+', ',', ';', '<', '>', or '\' (U+0022, U+002B, U+002C, U+003B, U+003C, U+003E, or U+005C, respectively); - the null (U+0000) character. Other characters may be escaped. Each octet of the character to be escaped is replaced by a backslash and two hex digits, which form a single octet in the code of the character. Alternatively, if and only if the character to be escaped is one of ' ', '"', '#', '+', ',', ';', '<', '=', '>', or '\' (U+0020, U+0022, U+0023, U+002B, U+002C, U+003B, U+003C, U+003D, U+003E, U+005C, respectively) it can be prefixed by a backslash ('\' U+005C). Examples of the escaping mechanism are shown in Section 4. 3. Parsing a String Back to a Distinguished Name The string representation of Distinguished Names is restricted to UTF-8 [RFC3629] encoded Unicode [Unicode] characters. The structure of this string representation is specified using the following Augmented BNF [RFC4234] grammar: distinguishedName = [ relativeDistinguishedName *( COMMA relativeDistinguishedName ) ] relativeDistinguishedName = attributeTypeAndValue *( PLUS attributeTypeAndValue ) attributeTypeAndValue = attributeType EQUALS attributeValue attributeType = descr / numericoid attributeValue = string / hexstring ; The following characters are to be escaped when they appear ; in the value to be encoded: ESC, one of <escaped>, leading ; SHARP or SPACE, trailing SPACE, and NULL. string = [ ( leadchar / pair ) [ *( stringchar / pair ) ( trailchar / pair ) ] ] leadchar = LUTF1 / UTFMB LUTF1 = %x01-1F / %x21 / %x24-2A / %x2D-3A / %x3D / %x3F-5B / %x5D-7F trailchar = TUTF1 / UTFMB TUTF1 = %x01-1F / %x21 / %x23-2A / %x2D-3A / Zeilenga Standards Track [Page 5] RFC 4514 LDAP: Distinguished Names June 2006 %x3D / %x3F-5B / %x5D-7F stringchar = SUTF1 / UTFMB SUTF1 = %x01-21 / %x23-2A / %x2D-3A / %x3D / %x3F-5B / %x5D-7F pair = ESC ( ESC / special / hexpair ) special = escaped / SPACE / SHARP / EQUALS escaped = DQUOTE / PLUS / COMMA / SEMI / LANGLE / RANGLE hexstring = SHARP 1*hexpair hexpair = HEX HEX where the productions <descr>, <numericoid>, <COMMA>, <DQUOTE>, <EQUALS>, <ESC>, <HEX>, <LANGLE>, <NULL>, <PLUS>, <RANGLE>, <SEMI>, <SPACE>, <SHARP>, and <UTFMB> are defined in [RFC4512]. Each <attributeType>, either a <descr> or a <numericoid>, refers to an attribute type of an attribute value assertion (AVA). The <attributeType> is followed by an <EQUALS> and an <attributeValue>. The <attributeValue> is either in <string> or <hexstring> form. If in <string> form, a LDAP string representation asserted value can be obtained by replacing (left to right, non-recursively) each <pair> appearing in the <string> as follows: replace <ESC><ESC> with <ESC>; replace <ESC><special> with <special>; replace <ESC><hexpair> with the octet indicated by the <hexpair>. If in <hexstring> form, a BER representation can be obtained from converting each <hexpair> of the <hexstring> to the octet indicated by the <hexpair>. There is one or more attribute value assertions, separated by <PLUS>, for a relative distinguished name. There is zero or more relative distinguished names, separated by <COMMA>, for a distinguished name. Implementations MUST recognize AttributeType name strings (descriptors) listed in the following table, but MAY recognize other name strings. Zeilenga Standards Track [Page 6] RFC 4514 LDAP: Distinguished Names June 2006 String X.500 AttributeType ------ -------------------------------------------- CN commonName (2.5.4.3) L localityName (2.5.4.7) ST stateOrProvinceName (2.5.4.8) O organizationName (2.5.4.10) OU organizationalUnitName (2.5.4.11) C countryName (2.5.4.6) STREET streetAddress (2.5.4.9) DC domainComponent (0.9.2342.19200300.100.1.25) UID userId (0.9.2342.19200300.100.1.1) These attribute types are described in [RFC4519]. Implementations MAY recognize other DN string representations. However, as there is no requirement that alternative DN string representations be recognized (and, if so, how), implementations SHOULD only generate DN strings in accordance with Section 2 of this document. 4. Examples This notation is designed to be convenient for common forms of name. This section gives a few examples of distinguished names written using this notation. First is a name containing three relative distinguished names (RDNs): UID=jsmith,DC=example,DC=net Here is an example of a name containing three RDNs, in which the first RDN is multi-valued: OU=Sales+CN=J. Smith,DC=example,DC=net This example shows the method of escaping of a special characters appearing in a common name: CN=James \"Jim\" Smith\, III,DC=example,DC=net The following shows the method for encoding a value that contains a carriage return character: CN=Before\0dAfter,DC=example,DC=net In this RDN example, the type in the RDN is unrecognized, and the value is the BER encoding of an OCTET STRING containing two octets, 0x48 and 0x69. Zeilenga Standards Track [Page 7] RFC 4514 LDAP: Distinguished Names June 2006 1.3.6.1.4.1.1466.0=#04024869 Finally, this example shows an RDN whose commonName value consists of 5 letters: Unicode Character Code UTF-8 Escaped ------------------------------- ------ ------ -------- LATIN CAPITAL LETTER L U+004C 0x4C L LATIN SMALL LETTER U U+0075 0x75 u LATIN SMALL LETTER C WITH CARON U+010D 0xC48D \C4\8D LATIN SMALL LETTER I U+0069 0x69 i LATIN SMALL LETTER C WITH ACUTE U+0107 0xC487 \C4\87 This could be encoded in printable ASCII [ASCII] (useful for debugging purposes) as: CN=Lu\C4\8Di\C4\87 5. Security Considerations The following security considerations are specific to the handling of distinguished names. LDAP security considerations are discussed in [RFC4511] and other documents comprising the LDAP Technical Specification [RFC4510]. 5.1. Disclosure Distinguished Names typically consist of descriptive information about the entries they name, which can be people, organizations, devices, or other real-world objects. This frequently includes some of the following kinds of information: - the common name of the object (i.e., a person's full name) - an email or TCP/IP address - its physical location (country, locality, city, street address) - organizational attributes (such as department name or affiliation) In some cases, such information can be considered sensitive. In many countries, privacy laws exist that prohibit disclosure of certain kinds of descriptive information (e.g., email addresses). Hence, server implementers are encouraged to support Directory Information Tree (DIT) structural rules and name forms [RFC4512], as these provide a mechanism for administrators to select appropriate naming attributes for entries. Administrators are encouraged to use mechanisms, access controls, and other administrative controls that may be available to restrict use of attributes containing sensitive information in naming of entries. Additionally, use of Zeilenga Standards Track [Page 8] RFC 4514 LDAP: Distinguished Names June 2006 authentication and data security services in LDAP [RFC4513][RFC4511] should be considered. 5.2. Use of Distinguished Names in Security Applications The transformations of an AttributeValue value from its X.501 form to an LDAP string representation are not always reversible back to the same BER (Basic Encoding Rules) or DER (Distinguished Encoding Rules) form. An example of a situation that requires the DER form of a distinguished name is the verification of an X.509 certificate. For example, a distinguished name consisting of one RDN with one AVA, in which the type is commonName and the value is of the TeletexString choice with the letters 'Sam', would be represented in LDAP as the string <CN=Sam>. Another distinguished name in which the value is still 'Sam', but is of the PrintableString choice, would have the same representation <CN=Sam>. Applications that require the reconstruction of the DER form of the value SHOULD NOT use the string representation of attribute syntaxes when converting a distinguished name to the LDAP format. Instead, they SHOULD use the hexadecimal form prefixed by the number sign ('#' U+0023) as described in the first paragraph of Section 2.4. 6. Acknowledgements This document is an update to RFC 2253, by Mark Wahl, Tim Howes, and Steve Kille. RFC 2253 was a product of the IETF ASID Working Group. This document is a product of the IETF LDAPBIS Working Group. 7. References 7.1. Normative References [REGISTRY] IANA, Object Identifier Descriptors Registry, <http://www.iana.org/assignments/ldap-parameters>. [Unicode] The Unicode Consortium, "The Unicode Standard, Version 3.2.0" is defined by "The Unicode Standard, Version 3.0" (Reading, MA, Addison-Wesley, 2000. ISBN 0-201- 61633-5), as amended by the "Unicode Standard Annex #27: Unicode 3.1" (http://www.unicode.org/reports/tr27/) and by the "Unicode Standard Annex #28: Unicode 3.2" (http://www.unicode.org/reports/tr28/). Zeilenga Standards Track [Page 9] RFC 4514 LDAP: Distinguished Names June 2006 [X.501] International Telecommunication Union - Telecommunication Standardization Sector, "The Directory -- Models," X.501(1993) (also ISO/IEC 9594- 2: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). [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003. [RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 4234, October 2005. [RFC4510] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006. [RFC4511] Sermersheim, J., Ed., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006. [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006. [RFC4513] Harrison, R., Ed., "Lightweight Directory Access Protocol (LDAP): Authentication Methods and Security Mechanisms", RFC 4513, June 2006. [RFC4517] Legg, S., Ed., "Lightweight Directory Access Protocol (LDAP): Syntaxes and Matching Rules", RFC 4517, June 2006. [RFC4519] Sciberras, A., Ed., "Lightweight Directory Access Protocol (LDAP): Schema for User Applications", RFC 4519, June 2006. [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006. Zeilenga Standards Track [Page 10] RFC 4514 LDAP: Distinguished Names June 2006 7.2. Informative References [ASCII] Coded Character Set--7-bit American Standard Code for Information Interchange, ANSI X3.4-1986. [CharModel] Whistler, K. and M. Davis, "Unicode Technical Report #17, Character Encoding Model", UTR17, <http://www.unicode.org/unicode/reports/tr17/>, August 2000. [Glossary] The Unicode Consortium, "Unicode Glossary", <http://www.unicode.org/glossary/>. [X.500] International Telecommunication Union - Telecommunication Standardization Sector, "The Directory -- Overview of concepts, models and services," X.500(1993) (also ISO/IEC 9594-1:1994). [X.511] International Telecommunication Union - Telecommunication Standardization Sector, "The Directory: Abstract Service Definition", X.511(1993) (also ISO/IEC 9594-3:1993). [X.690] International Telecommunication Union - Telecommunication Standardization Sector, "Specification of ASN.1 encoding rules: Basic Encoding Rules (BER), Canonical Encoding Rules (CER), and Distinguished Encoding Rules (DER)", X.690(1997) (also ISO/IEC 8825-1:1998). [RFC2849] Good, G., "The LDAP Data Interchange Format (LDIF) - Technical Specification", RFC 2849, June 2000. Zeilenga Standards Track [Page 11] RFC 4514 LDAP: Distinguished Names June 2006 Appendix A. Presentation Issues This appendix is provided for informational purposes only; it is not a normative part of this specification. The string representation described in this document is not intended to be presented to humans without translation. However, at times it may be desirable to present non-translated DN strings to users. This section discusses presentation issues associated with non-translated DN strings. Issues with presentation of translated DN strings are not discussed in this appendix. Transcoding issues are also not discussed in this appendix. This appendix provides guidance for applications presenting DN strings to users. This section is not comprehensive; it does not discuss all presentation issues that implementers may face. Not all user interfaces are capable of displaying the full set of Unicode characters. Some Unicode characters are not displayable. It is recommended that human interfaces use the optional hex pair escaping mechanism (Section 2.3) to produce a string representation suitable for display to the user. For example, an application can generate a DN string for display that escapes all non-printable characters appearing in the AttributeValue's string representation (as demonstrated in the final example of Section 4). When a DN string is displayed in free-form text, it is often necessary to distinguish the DN string from surrounding text. While this is often done with whitespace (as demonstrated in Section 4), it is noted that DN strings may end with whitespace. Careful readers of Section 3 will note that the characters '<' (U+003C) and '>' (U+003E) may only appear in the DN string if escaped. These characters are intended to be used in free-form text to distinguish a DN string from surrounding text. For example, <CN=Sam\ > distinguishes the string representation of the DN composed of one RDN consisting of the AVA (the commonName (CN) value 'Sam ') from the surrounding text. It should be noted to the user that the wrapping '<' and '>' characters are not part of the DN string. DN strings can be quite long. It is often desirable to line-wrap overly long DN strings in presentations. Line wrapping should be done by inserting whitespace after the RDN separator character or, if necessary, after the AVA separator character. It should be noted to the user that the inserted whitespace is not part of the DN string and is to be removed before use in LDAP. For example, the following DN string is long: Zeilenga Standards Track [Page 12] RFC 4514 LDAP: Distinguished Names June 2006 CN=Kurt D. Zeilenga,OU=Engineering,L=Redwood Shores, O=OpenLDAP Foundation,ST=California,C=US So it has been line-wrapped for readability. The extra whitespace is to be removed before the DN string is used in LDAP. Inserting whitespace is not advised because it may not be obvious to the user which whitespace is part of the DN string and which whitespace was added for readability. Another alternative is to use the LDAP Data Interchange Format (LDIF) [RFC2849]. For example: # This entry has a long DN... dn: CN=Kurt D. Zeilenga,OU=Engineering,L=Redwood Shores, O=OpenLDAP Foundation,ST=California,C=US CN: Kurt D. Zeilenga SN: Zeilenga objectClass: person Appendix B. Changes Made since RFC 2253 This appendix is provided for informational purposes only, it is not a normative part of this specification. The following substantive changes were made to RFC 2253: - Removed IESG Note. The IESG Note has been addressed. - Replaced all references to ISO 10646-1 with [Unicode]. - Clarified (in Section 1) that this document does not define a canonical string representation. - Clarified that Section 2 describes the RECOMMENDED encoding algorithm and that alternative algorithms are allowed. Some encoding options described in RFC 2253 are now treated as alternative algorithms in this specification. - Revised specification (in Section 2) to allow short names of any registered attribute type to appear in string representations of DNs instead of being restricted to a "published table". Removed "as an example" language. Added statement (in Section 3) allowing recognition of additional names but require recognition of those names in the published table. The table now appears in Section 3. - Removed specification of additional requirements for LDAPv2 implementations which also support LDAPv3 (RFC 2253, Section 4) as LDAPv2 is now Historic. - Allowed recognition of alternative string representations. - Updated Section 2.4 to allow hex pair escaping of all characters and clarified escaping for when multiple octet UTF-8 encodings Zeilenga Standards Track [Page 13] RFC 4514 LDAP: Distinguished Names June 2006 are present. Indicated that null (U+0000) character is to be escaped. Indicated that equals sign ('=' U+003D) character may be escaped as '\='. - Rewrote Section 3 to use ABNF as defined in RFC 4234. - Updated the Section 3 ABNF. Changes include: + allowed AttributeType short names of length 1 (e.g., 'L'), + used more restrictive <oid> production in AttributeTypes, + did not require escaping of equals sign ('=' U+003D) characters, + did not require escaping of non-leading number sign ('#' U+0023) characters, + allowed space (' ' U+0020) to be escaped as '\ ', + required hex escaping of null (U+0000) characters, and + removed LDAPv2-only constructs. - Updated Section 3 to describe how to parse elements of the grammar. - Rewrote examples. - Added reference to documentations containing general LDAP security considerations. - Added discussion of presentation issues (Appendix A). - Added this appendix. In addition, numerous editorial changes were made. Editor's Address Kurt D. Zeilenga OpenLDAP Foundation EMail: Kurt@OpenLDAP.org Zeilenga Standards Track [Page 14] RFC 4514 LDAP: Distinguished Names June 2006 Full Copyright Statement Copyright (C) The Internet Society (2006). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Zeilenga Standards Track [Page 15] PK *�c\��%�) �) ( doc/alt-openldap11-devel/rfc/rfc4370.txtnu �[��� Network Working Group R. Weltman Request for Comments: 4370 Yahoo!, Inc. Category: Standards Track February 2006 Lightweight Directory Access Protocol (LDAP) Proxied Authorization Control Status of This Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2006). Abstract This document defines the Lightweight Directory Access Protocol (LDAP) Proxy Authorization Control. The Proxy Authorization Control allows a client to request that an operation be processed under a provided authorization identity instead of under the current authorization identity associated with the connection. 1. Introduction Proxy authorization allows a client to request that an operation be processed under a provided authorization identity instead of under the current authorization identity associated with the connection. This document defines support for proxy authorization using the Control mechanism [RFC2251]. The Lightweight Directory Access Protocol [LDAPV3] supports the use of the Simple Authentication and Security Layer [SASL] for authentication and for supplying an authorization identity distinct from the authentication identity, where the authorization identity applies to the whole LDAP session. The Proxy Authorization Control provides a mechanism for specifying an authorization identity on a per-operation basis, benefiting clients that need to perform operations efficiently on behalf of multiple users. The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" used in this document are to be interpreted as described in [KEYWORDS]. Weltman Standards Track [Page 1] RFC 4370 LDAP Proxied Authorization Control February 2006 2. Publishing Support for the Proxy Authorization Control Support for the Proxy Authorization Control is indicated by the presence of the Object Identifier (OID) "2.16.840.1.113730.3.4.18" in the supportedControl attribute [RFC2252] of a server's root DSA-specific Entry (DSE). 3. Proxy Authorization Control A single Proxy Authorization Control may be included in any search, compare, modify, add, delete, or modify Distinguished Name (DN) or extended operation request message. The exception is any extension that causes a change in authentication, authorization, or data confidentiality [RFC2829], such as Start TLS [LDAPTLS] as part of the controls field of the LDAPMessage, as defined in [RFC2251]. The controlType of the proxy authorization control is "2.16.840.1.113730.3.4.18". The criticality MUST be present and MUST be TRUE. This requirement protects clients from submitting a request that is executed with an unintended authorization identity. Clients MUST include the criticality flag and MUST set it to TRUE. Servers MUST reject any request containing a Proxy Authorization Control without a criticality flag or with the flag set to FALSE with a protocolError error. These requirements protect clients from submitting a request that is executed with an unintended authorization identity. The controlValue SHALL be present and SHALL either contain an authzId [AUTH] representing the authorization identity for the request or be empty if an anonymous association is to be used. The mechanism for determining proxy access rights is specific to the server's proxy authorization policy. If the requested authorization identity is recognized by the server, and the client is authorized to adopt the requested authorization identity, the request will be executed as if submitted by the proxy authorization identity; otherwise, the result code 123 is returned. 4. Implementation Considerations One possible interaction of proxy authorization and normal access control is illustrated here. During evaluation of a search request, an entry that would have been returned for the search (if submitted by the proxy authorization identity directly) may not be returned if Weltman Standards Track [Page 2] RFC 4370 LDAP Proxied Authorization Control February 2006 the server finds that the requester does not have the right to assume the requested identity for searching the entry, even if the entry is within the scope of a search request under a base DN that does imply such rights. This means that fewer results, or no results, may be returned than would be if the proxy authorization identity issued the request directly. An example of such a case may be a system with fine-grained access control, where the proxy right requester has proxy rights at the top of a search tree, but not at or below a point or points within the tree. 5. Security Considerations The Proxy Authorization Control method is subject to general LDAP security considerations [RFC2251] [AUTH] [LDAPTLS]. The control may be passed over a secure channel as well as over an insecure channel. The control allows for an additional authorization identity to be passed. In some deployments, these identities may contain confidential information that requires privacy protection. Note that the server is responsible for determining if a proxy authorization request is to be honored. "Anonymous" users SHOULD NOT be allowed to assume the identity of others. 6. IANA Considerations The OID "2.16.840.1.113730.3.4.18" is reserved for the Proxy Authorization Control. It has been registered as an LDAP Protocol Mechanism [RFC3383]. A result code (123) has been assigned by the IANA for the case where the server does not execute a request using the proxy authorization identity. 7. Acknowledgements Mark Smith, formerly of Netscape Communications Corp., Mark Wahl, formerly of Sun Microsystems, Inc., Kurt Zeilenga of OpenLDAP Foundation, Jim Sermersheim of Novell, and Steven Legg of Adacel have contributed with reviews of this document. Weltman Standards Track [Page 3] RFC 4370 LDAP Proxied Authorization Control February 2006 8. Normative References [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [LDAPV3] Hodges, J. and R. Morgan, "Lightweight Directory Access Protocol (v3): Technical Specification", RFC 3377, September 2002. [SASL] Myers, J., "Simple Authentication and Security Layer (SASL)", RFC 2222, October 1997. [AUTH] Wahl, M., Alvestrand, H., Hodges, J., and R. Morgan, "Authentication Methods for LDAP", RFC 2829, May 2000. [LDAPTLS] Hodges, J., Morgan, R., and M. Wahl, "Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security", RFC 2830, May 2000. [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. [RFC3383] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 3383, September 2002. Author's Address Rob Weltman Yahoo!, Inc. 701 First Avenue Sunnyvale, CA 94089 USA Phone: +1 408 349-5504 EMail: robw@worldspot.com Weltman Standards Track [Page 4] RFC 4370 LDAP Proxied Authorization Control February 2006 Full Copyright Statement Copyright (C) The Internet Society (2006). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Weltman Standards Track [Page 5] PK *�c\d��q' q' ( doc/alt-openldap11-devel/rfc/rfc4526.txtnu �[��� Network Working Group K. Zeilenga Request for Comments: 4526 OpenLDAP Foundation Category: Standards Track June 2006 Lightweight Directory Access Protocol (LDAP) Absolute True and False Filters Status of This Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2006). Abstract This document extends the Lightweight Directory Access Protocol (LDAP) to support absolute True and False filters based upon similar capabilities found in X.500 directory systems. The document also extends the String Representation of LDAP Search Filters to support these filters. Table of Contents 1. Background ......................................................1 2. Absolute True and False Filters .................................2 3. Security Considerations .........................................2 4. IANA Considerations .............................................3 5. References ......................................................3 5.1. Normative References .......................................3 5.2. Informative References .....................................3 1. Background The X.500 Directory Access Protocol (DAP) [X.511] supports absolute True and False assertions. An 'and' filter with zero elements always evaluates to True. An 'or' filter with zero elements always evaluates to False. These filters are commonly used when requesting DSA-specific Entries (DSEs) that do not necessarily have 'objectClass' attributes; that is, where "(objectClass=*)" may evaluate to False. Zeilenga Standards Track [Page 1] RFC 4526 LDAP Absolute True and False Filters June 2006 Although LDAPv2 [RFC1777][RFC3494] placed no restriction on the number of elements in 'and' and 'or' filter sets, the LDAPv2 string representation [RFC1960][RFC3494] could not represent empty 'and' and 'or' filter sets. Due to this, absolute True or False filters were (unfortunately) eliminated from LDAPv3 [RFC4510]. This documents extends LDAPv3 to support absolute True and False assertions by allowing empty 'and' and 'or' in Search filters [RFC4511] and extends the filter string representation [RFC4515] to allow empty filter lists. It is noted that certain search operations, such as those used to retrieve subschema information [RFC4512], require use of particular filters. This document does not change these requirements. This feature is intended to allow a more direct mapping between DAP and LDAP (as needed to implement DAP-to-LDAP gateways). In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in BCP 14 [RFC2119]. 2. Absolute True and False Filters Implementations of this extension SHALL allow 'and' and 'or' choices with zero filter elements. An 'and' filter consisting of an empty set of filters SHALL evaluate to True. This filter is represented by the string "(&)". An 'or' filter consisting of an empty set of filters SHALL evaluate to False. This filter is represented by the string "(|)". Servers supporting this feature SHOULD publish the Object Identifier 1.3.6.1.4.1.4203.1.5.3 as a value of the 'supportedFeatures' [RFC4512] attribute in the root DSE. Clients supporting this feature SHOULD NOT use the feature unless they know that the server supports it. 3. Security Considerations The (re)introduction of absolute True and False filters is not believed to raise any new security considerations. Implementors of this (or any) LDAPv3 extension should be familiar with general LDAPv3 security considerations [RFC4510]. Zeilenga Standards Track [Page 2] RFC 4526 LDAP Absolute True and False Filters June 2006 4. IANA Considerations Registration of this feature has been completed by the IANA [RFC4520]. Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: 1.3.6.1.4.1.4203.1.5.3 Description: True/False filters Person & email address to contact for further information: Kurt Zeilenga <kurt@openldap.org> Usage: Feature Specification: RFC 4526 Author/Change Controller: IESG Comments: none This OID was assigned [ASSIGN] by OpenLDAP Foundation, under its IANA-assigned private enterprise allocation [PRIVATE], for use in this specification. 5. References 5.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC4510] Zeilenga, K., Ed, "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006. [RFC4511] Sermersheim, J., Ed., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006. [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006. [RFC4515] Smith, M., Ed. and T. Howes, "Lightweight Directory Access Protocol (LDAP): String Representation of Search Filters", RFC 4515, June 2006. 5.2. Informative References [RFC1777] Yeong, W., Howes, T., and S. Kille, "Lightweight Directory Access Protocol", RFC 1777, March 1995. [RFC1960] Howes, T., "A String Representation of LDAP Search Filters", RFC 1960, June 1996. [RFC3494] Zeilenga, K., "Lightweight Directory Access Protocol version 2 (LDAPv2) to Historic Status", RFC 3494, March 2003. Zeilenga Standards Track [Page 3] RFC 4526 LDAP Absolute True and False Filters June 2006 [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006. [X.500] International Telecommunication Union - Telecommunication Standardization Sector, "The Directory -- Overview of concepts, models and services," X.500(1993) (also ISO/IEC 9594-1:1994). [X.501] International Telecommunication Union - Telecommunication Standardization Sector, "The Directory -- Models," X.501(1993) (also ISO/IEC 9594- 2:1994). [X.511] International Telecommunication Union - Telecommunication Standardization Sector, "The Directory: Abstract Service Definition", X.511(1993) (also ISO/IEC 9594-3:1993). [ASSIGN] OpenLDAP Foundation, "OpenLDAP OID Delegations", http://www.openldap.org/foundation/oid-delegate.txt. [PRIVATE] IANA, "Private Enterprise Numbers", http://www.iana.org/assignments/enterprise-numbers. Author's Address Kurt D. Zeilenga OpenLDAP Foundation EMail: Kurt@OpenLDAP.org Zeilenga Standards Track [Page 4] RFC 4526 LDAP Absolute True and False Filters June 2006 Full Copyright Statement Copyright (C) The Internet Society (2006). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Zeilenga Standards Track [Page 5] PK *�c\�z*��2 �2 ( doc/alt-openldap11-devel/rfc/rfc4013.txtnu �[��� Network Working Group K. Zeilenga Request for Comments: 4013 OpenLDAP Foundation Category: Standards Track February 2005 SASLprep: Stringprep Profile for User Names and Passwords Status of This Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2005). Abstract This document describes how to prepare Unicode strings representing user names and passwords for comparison. The document defines the "SASLprep" profile of the "stringprep" algorithm to be used for both user names and passwords. This profile is intended to be used by Simple Authentication and Security Layer (SASL) mechanisms (such as PLAIN, CRAM-MD5, and DIGEST-MD5), as well as other protocols exchanging simple user names and/or passwords. 1. Introduction The use of simple user names and passwords in authentication and authorization is pervasive on the Internet. To increase the likelihood that user name and password input and comparison work in ways that make sense for typical users throughout the world, this document defines rules for preparing internationalized user names and passwords for comparison. For simplicity and implementation ease, a single algorithm is defined for both user names and passwords. The algorithm assumes all strings are comprised of characters from the Unicode [Unicode] character set. This document defines the "SASLprep" profile of the "stringprep" algorithm [StringPrep]. The profile is designed for use in Simple Authentication and Security Layer ([SASL]) mechanisms, such as [PLAIN], [CRAM-MD5], and [DIGEST-MD5]. It may be applicable where simple user names and Zeilenga Standards Track [Page 1] RFC 4013 SASLprep February 2005 passwords are used. This profile is not intended for use in preparing identity strings that are not simple user names (e.g., email addresses, domain names, distinguished names), or where identity or password strings that are not character data, or require different handling (e.g., case folding). This document does not alter the technical specification of any existing protocols. Any specification that wishes to use the algorithm described in this document needs to explicitly incorporate this document and provide precise details as to where and how this algorithm is used by implementations of that specification. 2. The SASLprep Profile This section defines the "SASLprep" profile of the "stringprep" algorithm [StringPrep]. This profile is intended for use in preparing strings representing simple user names and passwords. This profile uses Unicode 3.2 [Unicode]. Character names in this document use the notation for code points and names from the Unicode Standard [Unicode]. For example, the letter "a" may be represented as either <U+0061> or <LATIN SMALL LETTER A>. In the lists of mappings and the prohibited characters, the "U+" is left off to make the lists easier to read. The comments for character ranges are shown in square brackets (such as "[CONTROL CHARACTERS]") and do not come from the standard. Note: A glossary of terms used in Unicode can be found in [Glossary]. Information on the Unicode character encoding model can be found in [CharModel]. 2.1. Mapping This profile specifies: - non-ASCII space characters [StringPrep, C.1.2] that can be mapped to SPACE (U+0020), and - the "commonly mapped to nothing" characters [StringPrep, B.1] that can be mapped to nothing. 2.2. Normalization This profile specifies using Unicode normalization form KC, as described in Section 4 of [StringPrep]. Zeilenga Standards Track [Page 2] RFC 4013 SASLprep February 2005 2.3. Prohibited Output This profile specifies the following characters as prohibited input: - Non-ASCII space characters [StringPrep, C.1.2] - ASCII control characters [StringPrep, C.2.1] - Non-ASCII control characters [StringPrep, C.2.2] - Private Use characters [StringPrep, C.3] - Non-character code points [StringPrep, C.4] - Surrogate code points [StringPrep, C.5] - Inappropriate for plain text characters [StringPrep, C.6] - Inappropriate for canonical representation characters [StringPrep, C.7] - Change display properties or deprecated characters [StringPrep, C.8] - Tagging characters [StringPrep, C.9] 2.4. Bidirectional Characters This profile specifies checking bidirectional strings as described in [StringPrep, Section 6]. 2.5. Unassigned Code Points This profile specifies the [StringPrep, A.1] table as its list of unassigned code points. 3. Examples The following table provides examples of how various character data is transformed by the SASLprep string preparation algorithm # Input Output Comments - ----- ------ -------- 1 I<U+00AD>X IX SOFT HYPHEN mapped to nothing 2 user user no transformation 3 USER USER case preserved, will not match #2 4 <U+00AA> a output is NFKC, input in ISO 8859-1 5 <U+2168> IX output is NFKC, will match #1 6 <U+0007> Error - prohibited character 7 <U+0627><U+0031> Error - bidirectional check 4. Security Considerations This profile is intended to prepare simple user name and password strings for comparison or use in cryptographic functions (e.g., message digests). The preparation algorithm was specifically designed such that its output is canonical, and it is well-formed. Zeilenga Standards Track [Page 3] RFC 4013 SASLprep February 2005 However, due to an anomaly [PR29] in the specification of Unicode normalization, canonical equivalence is not guaranteed for a select few character sequences. These sequences, however, do not appear in well-formed text. This specification was published despite this known technical problem. It is expected that this specification will be revised before further progression on the Standards Track (after [Unicode] and/or [StringPrep] specifications have been updated to address this problem). It is not intended for preparing identity strings that are not simple user names (e.g., distinguished names, domain names), nor is the profile intended for use of simple user names that require different handling (such as case folding). Protocols (or applications of those protocols) that have application-specific identity forms and/or comparison algorithms should use mechanisms specifically designed for these forms and algorithms. Application of string preparation may have an impact upon the feasibility of brute force and dictionary attacks. While the number of possible prepared strings is less than the number of possible Unicode strings, the number of usable names and passwords is greater than as if only ASCII was used. Though SASLprep eliminates some Unicode code point sequences as possible prepared strings, that elimination generally makes the (canonical) output forms practicable and prohibits nonsensical inputs. User names and passwords should be protected from eavesdropping. General "stringprep" and Unicode security considerations apply. Both are discussed in [StringPrep]. 5. IANA Considerations This document details the "SASLprep" profile of the [StringPrep] protocol. This profile has been registered in the stringprep profile registry. Name of this profile: SASLprep RFC in which the profile is defined: RFC 4013 Indicator whether or not this is the newest version of the profile: This is the first version of the SASPprep profile. 6. Acknowledgement This document borrows text from "Preparation of Internationalized Strings ('stringprep')" and "Nameprep: A Stringprep Profile for Internationalized Domain Names", both by Paul Hoffman and Marc Blanchet. This document is a product of the IETF SASL WG. Zeilenga Standards Track [Page 4] RFC 4013 SASLprep February 2005 7. Normative References [StringPrep] Hoffman, P. and M. Blanchet, "Preparation of Internationalized Strings ("stringprep")", RFC 3454, December 2002. [Unicode] The Unicode Consortium, "The Unicode Standard, Version 3.2.0" is defined by "The Unicode Standard, Version 3.0" (Reading, MA, Addison-Wesley, 2000. ISBN 0-201- 61633-5), as amended by the "Unicode Standard Annex #27: Unicode 3.1" (http://www.unicode.org/reports/tr27/) and by the "Unicode Standard Annex #28: Unicode 3.2" (http://www.unicode.org/reports/tr28/). 8. Informative References [Glossary] The Unicode Consortium, "Unicode Glossary", <http://www.unicode.org/glossary/>. [CharModel] Whistler, K. and M. Davis, "Unicode Technical Report #17, Character Encoding Model", UTR17, <http://www.unicode.org/unicode/reports/tr17/>, August 2000. [SASL] Melnikov, A., Ed., "Simple Authentication and Security Layer (SASL)", Work in Progress. [CRAM-MD5] Nerenberg, L., "The CRAM-MD5 SASL Mechanism", Work in Progress. [DIGEST-MD5] Leach, P., Newman, C., and A. Melnikov, "Using Digest Authentication as a SASL Mechanism", Work in Progress. [PLAIN] Zeilenga, K., Ed., "The Plain SASL Mechanism", Work in Progress. [PR29] "Public Review Issue #29: Normalization Issue", <http://www.unicode.org/review/pr-29.html>, February 2004. Author's Address Kurt D. Zeilenga OpenLDAP Foundation EMail: Kurt@OpenLDAP.org Zeilenga Standards Track [Page 5] RFC 4013 SASLprep February 2005 Full 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. 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 IETF's procedures with respect to rights in IETF 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@ietf.org. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Zeilenga Standards Track [Page 6] PK *�c\]}SL�E �E ( doc/alt-openldap11-devel/rfc/rfc3671.txtnu �[��� Network Working Group K. Zeilenga Request for Comments: 3671 OpenLDAP Foundation Category: Standards Track December 2003 Collective Attributes in the Lightweight Directory Access Protocol (LDAP) Status of this Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2003). All Rights Reserved. Abstract X.500 collective attributes allow common characteristics to be shared between collections of entries. This document summarizes the X.500 information model for collective attributes and describes use of collective attributes in LDAP (Lightweight Directory Access Protocol). This document provides schema definitions for collective attributes for use in LDAP. 1. Introduction In X.500 [X.500], a collective attribute is "a user attribute whose values are the same for each member of an entry collection" [X.501]. This document details their use in the Lightweight Directory Access Protocol (LDAP) [RFC3377]. 1.1. Entry Collections A collection of entries is a grouping of object and alias entries based upon common properties or shared relationship between the corresponding entries which share certain attributes. An entry collection consists of all entries within scope of a collective attributes subentry [RFC3672]. An entry can belong to several entry collections. Zeilenga Standards Track [Page 1] RFC 3671 Collective Attributes in LDAP December 2003 1.2. Collective Attributes Attributes shared by the entries comprising an entry collection are called collective attributes. Values of collective attributes are visible but not updateable to clients accessing entries within the collection. Collective attributes are updated (i.e., modified) via their associated collective attributes subentry. When an entry belongs to multiple entry collections, the entry's values of each collective attribute are combined such that independent sources of these values are not manifested to clients. Entries can specifically exclude a particular collective attribute by listing the attribute as a value of the collectiveExclusions attribute. Like other user attributes, collective attributes are subject to a variety of controls including access, administrative, and content controls. 1.3. Conventions Schema definitions are provided using LDAPv3 [RFC2251] description formats [RFC2252]. Definitions provided here are formatted (line wrapped) for readability. 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]. 2. System Schema for Collective Attributes The following operational attributes are used to manage Collective Attributes. LDAP servers [RFC3377] MUST act in accordance with the X.500 Directory Models [X.501] when providing this service. 2.1. collectiveAttributeSubentry Subentries of this object class are used to administer collective attributes and are referred to as collective attribute subentries. ( 2.5.17.2 NAME 'collectiveAttributeSubentry' AUXILIARY ) A collective attribute subentry SHOULD contain at least one collective attribute. The collective attributes contained within a collective attribute subentry are available for finding, searching, and comparison at every entry within the scope of the subentry. The collective attributes, however, are administered (e.g., modified) via the subentry. Zeilenga Standards Track [Page 2] RFC 3671 Collective Attributes in LDAP December 2003 Implementations of this specification SHOULD support collective attribute subentries in both collectiveAttributeSpecificArea (2.5.23.5) and collectiveAttributeInnerArea (2.5.23.6) administrative areas [RFC3672][X.501]. 2.2. collectiveAttributeSubentries The collectiveAttributeSubentries operational attribute identifies all collective attribute subentries that affect the entry. ( 2.5.18.12 NAME 'collectiveAttributeSubentries' EQUALITY distinguishedNameMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 USAGE directoryOperation NO-USER-MODIFICATION ) 2.3. collectiveExclusions The collectiveExclusions operational attribute allows particular collective attributes to be excluded from an entry. It MAY appear in any entry and MAY have multiple values. ( 2.5.18.7 NAME 'collectiveExclusions' EQUALITY objectIdentifierMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 USAGE directoryOperation ) The descriptor excludeAllCollectiveAttributes is associated with the OID 2.5.18.0. When this descriptor or OID is present as a value of the collectiveExclusions attribute, all collective attributes are excluded from an entry. 3. Collective Attribute Types A userApplications attribute type can be defined to be COLLECTIVE [RFC2252]. This indicates that the same attribute values will appear in the entries of an entry collection subject to the use of the collectiveExclusions attribute and other administrative controls. These administrative controls MAY include DIT Content Rules, if implemented. Collective attribute types are commonly defined as subtypes of non- collective attribute types. By convention, collective attributes are named by prefixing the name of their non-collective supertype with "c-". For example, the collective telephone attribute is named c-TelephoneNumber after its non-collective supertype telephoneNumber. Non-collective attributes types SHALL NOT subtype collective attributes. Zeilenga Standards Track [Page 3] RFC 3671 Collective Attributes in LDAP December 2003 Collective attributes SHALL NOT be SINGLE-VALUED. Collective attribute types SHALL NOT appear in the attribute types of an object class definition. Operational attributes SHALL NOT be defined to be collective. The remainder of section provides a summary of collective attributes derived from those defined in [X.520]. The SUPerior attribute types are described in [RFC 2256] for use with LDAP. Implementations of this specification SHOULD support the following collective attributes and MAY support additional collective attributes. 3.1. Collective Locality Name The c-l attribute type specifies a locality name for a collection of entries. ( 2.5.4.7.1 NAME 'c-l' SUP l COLLECTIVE ) 3.2. Collective State or Province Name The c-st attribute type specifies a state or province name for a collection of entries. ( 2.5.4.8.1 NAME 'c-st' SUP st COLLECTIVE ) 3.3. Collective Street Address The c-street attribute type specifies a street address for a collection of entries. ( 2.5.4.9.1 NAME 'c-street' SUP street COLLECTIVE ) 3.4. Collective Organization Name The c-o attribute type specifies an organization name for a collection of entries. ( 2.5.4.10.1 NAME 'c-o' SUP o COLLECTIVE ) Zeilenga Standards Track [Page 4] RFC 3671 Collective Attributes in LDAP December 2003 3.5. Collective Organizational Unit Name The c-ou attribute type specifies an organizational unit name for a collection of entries. ( 2.5.4.11.1 NAME 'c-ou' SUP ou COLLECTIVE ) 3.6. Collective Postal Address The c-PostalAddress attribute type specifies a postal address for a collection of entries. ( 2.5.4.16.1 NAME 'c-PostalAddress' SUP postalAddress COLLECTIVE ) 3.7. Collective Postal Code The c-PostalCode attribute type specifies a postal code for a collection of entries. ( 2.5.4.17.1 NAME 'c-PostalCode' SUP postalCode COLLECTIVE ) 3.8. Collective Post Office Box The c-PostOfficeBox attribute type specifies a post office box for a collection of entries. ( 2.5.4.18.1 NAME 'c-PostOfficeBox' SUP postOfficeBox COLLECTIVE ) 3.9. Collective Physical Delivery Office Name The c-PhysicalDeliveryOfficeName attribute type specifies a physical delivery office name for a collection of entries. ( 2.5.4.19.1 NAME 'c-PhysicalDeliveryOfficeName' SUP physicalDeliveryOfficeName COLLECTIVE ) 3.10. Collective Telephone Number The c-TelephoneNumber attribute type specifies a telephone number for a collection of entries. ( 2.5.4.20.1 NAME 'c-TelephoneNumber' SUP telephoneNumber COLLECTIVE ) Zeilenga Standards Track [Page 5] RFC 3671 Collective Attributes in LDAP December 2003 3.11. Collective Telex Number The c-TelexNumber attribute type specifies a telex number for a collection of entries. ( 2.5.4.21.1 NAME 'c-TelexNumber' SUP telexNumber COLLECTIVE ) 3.13. Collective Facsimile Telephone Number The c-FacsimileTelephoneNumber attribute type specifies a facsimile telephone number for a collection of entries. ( 2.5.4.23.1 NAME 'c-FacsimileTelephoneNumber' SUP facsimileTelephoneNumber COLLECTIVE ) 3.14. Collective International ISDN Number The c-InternationalISDNNumber attribute type specifies an international ISDN number for a collection of entries. ( 2.5.4.25.1 NAME 'c-InternationalISDNNumber' SUP internationalISDNNumber COLLECTIVE ) 4. Security Considerations Collective attributes, like other attributes, are subject to access control restrictions and other administrative policy. Generally speaking, collective attributes accessed via an entry in a collection are governed by rules restricting access to attributes of that entry. And collective attributes access via a subentry are governed by rules restricting access to attributes of that subentry. However, as LDAP does not have a standard access model, the particulars of each server's access control system may differ. General LDAP security considerations [RFC3377] also apply. Zeilenga Standards Track [Page 6] RFC 3671 Collective Attributes in LDAP December 2003 5. IANA Considerations The IANA has registered the LDAP descriptors [RFC3383] defined in this technical specification. The following registration template is suggested: Subject: Request for LDAP Descriptor Registration Descriptor see comments Object Identifier: see comment Person & email address to contact for further information: Kurt Zeilenga <kurt@OpenLDAP.org> Usage: see comment Specification: RFC3671 Author/Change Controller: IESG Comments: NAME Type OID ------------------------ ---- ----------------- c-FacsimileTelephoneNumber A 2.5.4.23.1 c-InternationalISDNNumber A 2.5.4.25.1 c-PhysicalDeliveryOffice A 2.5.4.19.1 c-PostOfficeBox A 2.5.4.18.1 c-PostalAddress A 2.5.4.16.1 c-PostalCode A 2.5.4.17.1 c-TelephoneNumber A 2.5.4.20.1 c-TelexNumber A 2.5.4.21.1 c-l A 2.5.4.7.1 c-o A 2.5.4.10.1 c-ou A 2.5.4.11.1 c-st A 2.5.4.8.1 c-street A 2.5.4.9.1 collectiveAttributeSubentries A 2.5.18.12 collectiveAttributeSubentry O 2.5.17.2 collectiveExclusions A 2.5.18.7 where Type A is Attribute and Type O is ObjectClass. The Object Identifiers used in this document were assigned by the ISO/IEC Joint Technical Committee 1 - Subcommittee 6 to identify elements of X.500 schema [X.520]. This document make no OID assignments, it only provides LDAP schema descriptions with existing elements of X.500 schema. Zeilenga Standards Track [Page 7] RFC 3671 Collective Attributes in LDAP December 2003 6. 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. 7. Acknowledgments This document is based upon the ITU Recommendations for the Directory [X.501][X.520]. 8. References 8.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 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. [RFC2256] Wahl, M., "A Summary of the X.500(96) User Schema for use with LDAPv3", RFC 2256, December 1997. [RFC3377] Hodges, J. and R. L. Morgan, "Lightweight Directory Access Protocol (v3): Technical Specification", RFC 3377, September 2002. Zeilenga Standards Track [Page 8] RFC 3671 Collective Attributes in LDAP December 2003 [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. and S. Legg, "Subentries in Lightweight Directory Access Protocol (LDAP)", RFC 3672, December 2003. [X.501] "The Directory: Models", ITU-T Recommendation X.501, 1993. 8.2. Informative References [X.500] "The Directory: Overview of Concepts, Models", ITU-T Recommendation X.500, 1993. [X.520] "The Directory: Selected Attribute Types", ITU-T Recommendation X.520, 1993. 9. Author's Address Kurt D. Zeilenga OpenLDAP Foundation EMail: Kurt@OpenLDAP.org Zeilenga Standards Track [Page 9] RFC 3671 Collective Attributes in LDAP December 2003 10. Full Copyright Statement Copyright (C) The Internet Society (2003). 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 assignees. 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. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Zeilenga Standards Track [Page 10] PK *�c\�p o4 o4 ( doc/alt-openldap11-devel/rfc/rfc3909.txtnu �[��� Network Working Group K. Zeilenga Request for Comments: 3909 OpenLDAP Foundation Category: Standards Track October 2004 Lightweight Directory Access Protocol (LDAP) Cancel Operation Status of this Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2004). Abstract This specification describes a Lightweight Directory Access Protocol (LDAP) extended operation to cancel (or abandon) an outstanding operation. Unlike the LDAP Abandon operation, but like the X.511 Directory Access Protocol (DAP) Abandon operation, this operation has a response which provides an indication of its outcome. 1. Background and Intent of Use The Lightweight Directory Access Protocol (LDAP) [RFC3377] provides an Abandon operation [RFC2251] which clients may use to cancel other operations. The Abandon operation does not have a response and requires no response from the abandoned operation. These semantics provide the client with no clear indication of the outcome of the Abandon operation. The X.511 Directory Access Protocol (DAP) [X.511] provides an Abandon operation which has a response and also requires the abandoned operation to return a response indicating it was canceled. The LDAP Cancel operation is modeled after the DAP Abandon operation. The LDAP Cancel operation SHOULD be used instead of the LDAP Abandon operation when the client needs an indication of the outcome. This operation may be used to cancel both interrogation and update operations. Zeilenga Standards Track [Page 1] RFC 3909 LDAP Cancel Operation October 2004 Protocol elements are described using ASN.1 [X.680] with implicit tags. The term "BER-encoded" means the element is to be encoded using the Basic Encoding Rules [X.690] under the restrictions detailed in Section 5.1 of [RFC2251]. DSA stands for Directory System Agent (or server). DSE stands for DSA-specific Entry. 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]. 2. Cancel Operation The Cancel operation is defined as an LDAP Extended Operation [RFC2251, Section 4.12] identified by the object identifier 1.3.6.1.1.8. This section details the syntax of the Cancel request and response messages and defines additional LDAP resultCodes. 2.1. Cancel Request The Cancel request is an ExtendedRequest with the requestName field containing 1.3.6.1.1.8 and a requestValue field which contains a BER-encoded cancelRequestValue value. cancelRequestValue ::= SEQUENCE { cancelID MessageID -- MessageID is as defined in [RFC2251] } The cancelID field contains the message ID associated with the operation to be canceled. 2.2. Cancel Response A Cancel response is an ExtendedResponse where the responseName and response fields are absent. 2.3. Additional Result Codes Implementations of this specification SHALL recognize the following additional resultCode values: canceled (118) noSuchOperation (119) tooLate (120) cannotCancel (121) Zeilenga Standards Track [Page 2] RFC 3909 LDAP Cancel Operation October 2004 3. Operational Semantics The function of the Cancel Operation is to request that the server cancel an outstanding operation issued within the same session. The client requests the cancelation of an outstanding operation by issuing a Cancel Response with a cancelID set to the message ID of the outstanding operation. The Cancel Request itself has a distinct message ID. Clients SHOULD NOT request the cancelation of an operation multiple times. If the server is willing and able to cancel the outstanding operation identified by the cancelId, the server SHALL return a Cancel Response with a success resultCode, and the canceled operation SHALL fail with canceled resultCode. Otherwise the Cancel Response SHALL have a non-success resultCode and SHALL NOT have an impact upon the outstanding operation (if it exists). The protocolError resultCode is returned if the server is unable to parse the requestValue or the requestValue is absent, The noSuchOperation resultCode is returned if the server has no knowledge of the operation requested for cancelation. The cannotCancel resultCode is returned if the identified operation does not support cancelation or the cancel operation could not be performed. The following classes of operations are not cancelable: - operations which have no response, - operations which create, alter, or destroy authentication and/or authorization associations, - operations which establish, alter, or tear-down security services, and - operations which abandon or cancel other operations. Specifically, the Abandon, Bind, Start TLS [RFC2830], Unbind, and Cancel operations are not cancelable. The Cancel operation cannot be abandoned. The tooLate resultCode is returned to indicate that it is too late to cancel the outstanding operation. For example, the server may return tooLate for a request to cancel an outstanding modify operation which has already committed updates to the underlying data store. Zeilenga Standards Track [Page 3] RFC 3909 LDAP Cancel Operation October 2004 Servers SHOULD indicate their support for this extended operation by providing 1.3.6.1.1.8 as a value of the 'supportedExtension' attribute type in their root DSE. A server MAY choose to advertise this extension only when the client is authorized to use it. 4. Security Considerations This operation is intended to allow a user to cancel operations they previously issued during the current LDAP association. In certain cases, such as when the Proxy Authorization Control is in use, different outstanding operations may be processed under different LDAP associations. Servers MUST NOT allow a user to cancel an operation belonging to another user. Some operations should not be cancelable for security reasons. This specification disallows the cancelation of the Bind operation and Start TLS extended operation so as to avoid adding complexity to authentication, authorization, and security layer semantics. Designers of future extended operations and/or controls should disallow abandonment and cancelation when appropriate. 5. IANA Considerations The following values [RFC3383] have been registered by the IANA. 5.1. Object Identifier The IANA has registered upon Standards Action the LDAP Object Identifier 1.3.6.1.1.8 to identify the LDAP Cancel Operation as defined in this document. Subject: Request for LDAP Object Identifier Registration Person & email address to contact for further information: Kurt Zeilenga <kurt@OpenLDAP.org> Specification: RFC 3909 Author/Change Controller: IESG Comments: Identifies the LDAP Cancel Operation Zeilenga Standards Track [Page 4] RFC 3909 LDAP Cancel Operation October 2004 5.2. LDAP Protocol Mechanism The IANA has registered upon Standards Action the LDAP Protocol Mechanism described in this document. Subject: LDAP Protocol Mechanism Registration Object Identifier: 1.3.6.1.1.8 Description: LDAP Cancel Operation Person & email address to contact for further information: Kurt Zeilenga <kurt@openldap.org> Usage: Extended Operation Specification: RFC 3909 Author/Change Controller: IESG Comments: none 5.3. LDAP Result Codes The IANA has registered upon Standards Action the LDAP Result Codes described in this document. Subject: LDAP Result Code Registration Person & email address to contact for further information: Kurt Zeilenga <kurt@OpenLDAP.org> Result Code Name: canceled (118) Result Code Name: noSuchOperation (119) Result Code Name: tooLate (120) Result Code Name: cannotCancel (121) Specification: RFC 3909 Author/Change Controller: IESG 6. Acknowledgment The LDAP Cancel operation is modeled after the X.511 DAP Abandon operation. Zeilenga Standards Track [Page 5] RFC 3909 LDAP Cancel Operation October 2004 7. References 7.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2251] Wahl, M., Howes, T., and S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [RFC2830] Hodges, J., Morgan, R., and M. Wahl, "Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security", RFC 2830, May 2000. [RFC3377] Hodges, J. and R. Morgan, "Lightweight Directory Access Protocol (v3): Technical Specification", RFC 3377, September 2002. [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). [X.690] International Telecommunication Union - Telecommunication Standardization Sector, "Specification of ASN.1 encoding rules: Basic Encoding Rules (BER), Canonical Encoding Rules (CER), and Distinguished Encoding Rules (DER)", X.690(1997) (also ISO/IEC 8825-1:1998). 7.2. Informative References [RFC3383] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 3383, September 2002. [X.511] International Telecommunication Union - Telecommunication Standardization Sector, "The Directory: Abstract Service Definition", X.511(1993). 8. Author's Address Kurt D. Zeilenga OpenLDAP Foundation EMail: Kurt@OpenLDAP.org Zeilenga Standards Track [Page 6] RFC 3909 LDAP Cancel Operation October 2004 9. Full Copyright Statement Copyright (C) The Internet Society (2004). This document is subject to the rights, licenses and restrictions contained in BCP 78, and at www.rfc-editor.org, 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 ISOC's procedures with respect to rights in ISOC 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@ietf.org. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Zeilenga Standards Track [Page 7] PK *�c\����T �T ( doc/alt-openldap11-devel/rfc/rfc5805.txtnu �[��� Independent Submission K. Zeilenga Request for Comments: 5805 Isode Limited Category: Experimental March 2010 ISSN: 2070-1721 Lightweight Directory Access Protocol (LDAP) Transactions Abstract Lightweight Directory Access Protocol (LDAP) update operations, such as Add, Delete, and Modify operations, have atomic, consistency, isolation, durability (ACID) properties. Each of these update operations act upon an entry. It is often desirable to update two or more entries in a single unit of interaction, a transaction. Transactions are necessary to support a number of applications including resource provisioning. This document extends LDAP to support transactions. Status of This Memo This document is not an Internet Standards Track specification; it is published for examination, experimental implementation, and evaluation. This document defines an Experimental Protocol for the Internet community. This is a contribution to the RFC Series, independently of any other RFC stream. The RFC Editor has chosen to publish this document at its discretion and makes no statement about its value for implementation or deployment. Documents approved for publication by the RFC Editor are not a candidate for any level of Internet Standard; see Section 2 of RFC 5741. Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc5805. Copyright Notice Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Zeilenga Experimental [Page 1] RFC 5805 LDAP Transactions March 2010 1. Overview This document extends the Lightweight Directory Access Protocol (LDAP) [RFC4510] to allow clients to relate a number of update operations [RFC4511] and have them performed as one unit of interaction, a transaction. As with distinct update operations, each transaction has atomic, consistency, isolation, and durability (ACID) properties [ACID]. This extension consists of two extended operations, one control, and one unsolicited notification message. The Start Transaction operation is used to obtain a transaction identifier. This identifier is then attached to multiple update operations to indicate that they belong to the transaction using the Transaction Specification control. The End Transaction is used to settle (commit or abort) the transaction. The Aborted Transaction Notice is provided by the server to notify the client that the server is no longer willing or able to process an outstanding transaction. 1.1. Conventions and 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 RFC 2119 [RFC2119]. Protocol elements are described using ASN.1 [X.680] with implicit tags. The term "BER-encoded" means the element is to be encoded using the Basic Encoding Rules [X.690] under the restrictions detailed in Section 5.1 of [RFC4511]. DSA stands for "Directory System Agent" (a server). DSE stands for "DSA-specific entry". 2. Elements of an LDAP Transaction 2.1. Start Transaction Request and Response A Start Transaction Request is an LDAPMessage of CHOICE extendedReq where the requestName is 1.3.6.1.1.21.1 and the requestValue is absent. A Start Transaction Response is an LDAPMessage of CHOICE extendedRes sent in response to a Start Transaction Request. Its responseName is absent. When the resultCode is success (0), responseValue is present and contains a transaction identifier. Otherwise, the responseValue is absent. Zeilenga Experimental [Page 2] RFC 5805 LDAP Transactions March 2010 2.2. Transaction Specification Control A Transaction Specification Control is an LDAPControl where the controlType is 1.3.6.1.1.21.2, the criticality is TRUE, and the controlValue is a transaction identifier. The control is appropriate for update requests including Add, Delete, Modify, and ModifyDN (Rename) requests [RFC4511], as well as the Password Modify requests [RFC3062]. As discussed in Section 4, the Transaction Specification control can be used in conjunction with request controls appropriate for the update request. 2.3. End Transactions Request and Response An End Transaction Request is an LDAPMessage of CHOICE extendedReq where the requestName is 1.3.6.1.1.21.3 and the requestValue is present and contains a BER-encoded txnEndReq. txnEndReq ::= SEQUENCE { commit BOOLEAN DEFAULT TRUE, identifier OCTET STRING } A commit value of TRUE indicates a request to commit the transaction identified by the identifier. A commit value of FALSE indicates a request to abort the identified transaction. An End Transaction Response is an LDAPMessage sent in response to a End Transaction Request. Its response name is absent. The responseValue when present contains a BER-encoded txnEndRes. txnEndRes ::= SEQUENCE { messageID MessageID OPTIONAL, -- msgid associated with non-success resultCode updatesControls SEQUENCE OF updateControls SEQUENCE { messageID MessageID, -- msgid associated with controls controls Controls } OPTIONAL } -- where MessageID and Controls are as specified in RFC 4511 The txnEndRes.messageID provides the message id of the update request associated with a non-success response. txnEndRes.messageID is absent when resultCode of the End Transaction Response is success (0). Zeilenga Experimental [Page 3] RFC 5805 LDAP Transactions March 2010 The txnEndRes.updatesControls provides a facility for returning response controls that normally (i.e., in the absence of transactions) would be returned in an update response. The updateControls.messageID provides the message id of the update request associated with the response controls provided in updateControls.controls. The txnEndRes.updatesControls is absent when there are no update response controls to return. If both txnEndRes.messageID and txnEndRes.updatesControl are absent, the responseValue of the End Transaction Response is absent. 2.4. Aborted Transaction Notice The Aborted Transaction Notice is an Unsolicited Notification message where the responseName is 1.3.6.1.1.21.4 and responseValue is present and contains a transaction identifier. 3. An LDAP Transaction 3.1. Extension Discovery To allow clients to discover support for this extension, servers implementing this specification SHOULD publish 1.3.6.1.1.21.1 and 1.3.6.1.1.21.3 as values of the 'supportedExtension' attribute [RFC4512] within the Root DSE, and publish the 1.3.6.1.1.21.2 as a value of the 'supportedControl' attribute [RFC4512] of the Root DSE. A server MAY choose to advertise this extension only when the client is authorized to use it. 3.2. Starting a Transaction A client wishing to perform a sequence of directory updates as a transaction issues a Start Transaction Request. A server that is willing and able to support transactions responds to this request with a Start Transaction Response providing a transaction identifier and with a resultCode of success (0). Otherwise, the server responds with a Start Transaction Response with a resultCode other than success indicating the nature of the failure. The transaction identifier provided upon successful start of a transaction is used in subsequent protocol messages to identify this transaction. Zeilenga Experimental [Page 4] RFC 5805 LDAP Transactions March 2010 3.3. Specification of a Transaction The client then can issue one or more update requests, each with a Transaction Specification control containing the transaction identifier indicating the updates are to be processed as part of the transaction. Each of these update requests MUST have a different MessageID value. If the server is unwilling or unable to attempt to process the requested update operation as part of the transaction, the server immediately returns the appropriate response to the request with a resultCode indicating the nature of the failure. Otherwise, the server immediately returns a resultCode of success (0) and the defers further processing of the operation is then deferred until settlement. If the server becomes unwilling or unable to continue the specification of a transaction, the server issues an Aborted Transaction Notice with a non-success resultCode indicating the nature of the failure. All operations that were to be processed as part of the transaction are implicitly abandoned. Upon receipt of an Aborted Transaction Notice, the client is to discontinue all use of the transaction identifier as the transaction is null and void. Any future use of identifier by the client will result in a response containing a non-success resultCode. 3.4. Transaction Settlement A client requests settlement of transaction by issuing an End Transaction Request for the transaction indicating whether it desires the transaction to be committed or aborted. Upon receipt of a request to abort the transaction, the server is to abort the identified transaction (abandoning all operations that are part of the transaction) and indicate that it has done so by returning an End Transaction Response with a resultCode of success (0). Upon receipt of a request to commit the transaction, the server processes all update operations of the transaction as one atomic, durable, isolated, and consistent action with each requested update being processed in turn. Either all of the requested updates are to be successfully applied or none of the requested are to be applied. The server returns an End Transaction Response with a resultCode of success (0) and no responseValue to indicate all the requested updates were applied. Otherwise, the server returns an End Transaction Response with a non-success resultCode indicating the nature of the failure. If the failure is associated with a Zeilenga Experimental [Page 5] RFC 5805 LDAP Transactions March 2010 particular update request, the txnEndRes.messageID in the responseValue is the message id of this update request. If the failure was not associated with any particular update request, no txnEnd.messageID is provided. There is no requirement that a server serialize transactions or updates requested outside of a transaction. That is, a server MAY process multiple commit requests (from one or more clients) acting upon different sets of entries concurrently. A server MUST avoid deadlock. 3.5. Miscellaneous Issues Transactions cannot be nested. Each LDAP transaction should be initiated, specified, and settled within a stable security context. Between the Start Request and the End Response, the peers SHOULD avoid negotiating new security associations and/or layers. Upon receipt of a Bind or Unbind request, the server SHALL abort any and all outstanding transactions without notice and nullify their identifiers. 4. Interaction with Other Extensions The LDAP Transaction extension may be used with many but not all LDAP control extensions designed to extend update (and possibly other) operations. The subsections that follow discuss interaction with a number of control extensions. Interaction with other control extensions may be discussed in other documents, in particular in control extension specifications. 4.1. Assertion Control The Assertion [RFC4528] control is appropriate for use with update requests specified as part of a transaction. The evaluation of the assertion is performed as part of the transaction. The Assertion control is inappropriate for use with either the Start or End Transaction Extended operations. 4.2. ManageDsaIT Control The ManageDsaIT [RFC3296] control is appropriate for use with update requests specified as part of a transaction. Zeilenga Experimental [Page 6] RFC 5805 LDAP Transactions March 2010 The ManageDsaIT control is inappropriate for use with either the Start or End Transaction Extended operations. 4.4. Proxied Authorization Control The Proxied Authorization [RFC4370] control is appropriate for use with the Start Transaction Extended operation, but not the End Transaction Extended operation or any update request specified as part of a transaction. To request that a transaction be performed under a different authorization, the client provides a Proxied Authorization control with the Transaction Start Request. If the client is not authorized to assume the requested authorization identity, the server is to return the authorizationDenied (123) resultCode in its response. Otherwise, further processing of the request and transaction is performed under the requested authorization identity. Any proxied authorization request attached to an update request specified as part of a transaction, or attached to a Transaction End Request, is to be regarded as a protocol error. 4.5. Read Entry Controls The Pre- and Post-Read Entry [RFC4527] request control are appropriate for use with update requests specified as part of a transaction. The response control produced in response to a Pre- or Post-Read Entry request control is returned in the txnEndRes.updatesControls field of responseValue of the End Transaction Response. The Pre- and Post-Read Entry controls are inappropriate for use in the LDAPMessage.controls field of the Transaction Start and End Request and Response messages. 5. Distributed Directory Considerations The LDAP/X.500 models provide for distributed directory operations, including server-side chaining and client-side chasing of referrals. This document does not preclude servers from chaining operations that are part of a transaction. However, if a server does attempt such chaining, it MUST ensure that transaction semantics are provided. The mechanism defined by this document does not support client-side chasing. Transaction identifiers are specific to a particular LDAP association (as established via the LDAP Bind operation). Zeilenga Experimental [Page 7] RFC 5805 LDAP Transactions March 2010 The LDAP/X.500 models provide for a single-master/multiple-shadow replication architecture. There is no requirement that changes made to the directory based upon processing a transaction be replicated as one atomic action. Hence, clients SHOULD NOT assume tight data consistency nor fast data convergence of shadow copies unless they have prior knowledge that these properties are provided. Note that DontUseCopy control [DONTUSECOPY] may be used in conjunction with the LDAP search request to ask for the return of the authoritative copy of the entry. 6. Security Considerations Transaction mechanisms may be the target of denial-of-service attacks, especially where implementations lock shared resources for the duration of a transaction. General security considerations [RFC4510], especially those associated with update operations [RFC4511], apply to this extension. 7. IANA Considerations The Internet Assigned Numbers Authority (IANA) has made the following assignments. 7.1. Object Identifier IANA has assigned an LDAP Object Identifier (21) [RFC4520] to identify the protocol elements specified in this document. Subject: Request for LDAP Object Identifier Registration Person & email address to contact for further information: Kurt Zeilenga <Kurt.Zeilenga@Isode.COM> Specification: RFC 5805 Author/Change Controller: Kurt Zeilenga <Kurt.Zeilenga@Isode.COM> Comments: Identifies protocol elements for LDAP Transactions Zeilenga Experimental [Page 8] RFC 5805 LDAP Transactions March 2010 7.2. LDAP Protocol Mechanism IANA has registered the protocol mechanisms [RFC4520] specified in this document. Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: see table Description: see table Person & email address to contact for further information: Kurt Zeilenga <Kurt.Zeilenga@Isode.COM> Specification: RFC 5805 Author/Change Controller: Kurt Zeilenga <Kurt.Zeilenga@Isode.COM> Comments: Object Identifier Type Description ------------------- ---- ---------------------------------- 1.3.6.1.1.21.1 E Start Transaction Extended Request 1.3.6.1.1.21.2 C Transaction Specification Control 1.3.6.1.1.21.3 E End Transaction Extended Request 1.3.6.1.1.21.4 N Aborted Transaction Notice Legend ------------------------ C => supportedControl E => supportedExtension N => Unsolicited Notice 8. Acknowledgments The author gratefully acknowledges the contributions made by Internet Engineering Task Force participants. 9. References 9.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC3062] Zeilenga, K., "LDAP Password Modify Extended Operation", RFC 3062, February 2001. [RFC3296] Zeilenga, K., "Named Subordinate References in Lightweight Directory Access Protocol (LDAP) Directories", RFC 3296, July 2002. Zeilenga Experimental [Page 9] RFC 5805 LDAP Transactions March 2010 [RFC4370] Weltman, R., "Lightweight Directory Access Protocol (LDAP) Proxied Authorization Control", RFC 4370, February 2006. [RFC4510] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006. [RFC4511] Sermersheim, J., Ed., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006. [RFC4512] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006. [RFC4527] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP) Read Entry Controls", RFC 4527, June 2006. [RFC4528] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP) Assertion Control", RFC 4528, June 2006. [X.680] International Telecommunication Union - Telecommunication Standardization Sector, "Abstract Syntax Notation One (ASN.1) - Specification of Basic Notation", X.680(2002) (also ISO/IEC 8824-1:2002). [X.690] International Telecommunication Union - Telecommunication Standardization Sector, "Specification of ASN.1 encoding rules: Basic Encoding Rules (BER), Canonical Encoding Rules (CER), and Distinguished Encoding Rules (DER)", X.690(2002) (also ISO/IEC 8825-1:2002). 9.2. Informative References [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006. [ACID] "Information technology -- Open Systems Interconnection -- Distributed Transaction Processing -- Part 1: OSI TP Model", Section 4, ISO/IEC 10026-1:1992. [DONTUSECOPY] Zeilenga, K., "The LDAP Don't Use Copy Control", Work in Progress, December 2009. Zeilenga Experimental [Page 10] RFC 5805 LDAP Transactions March 2010 Author's Address Kurt D. Zeilenga Isode Limited EMail: Kurt.Zeilenga@Isode.COM Zeilenga Experimental [Page 11] PK *�c\s Z �- �- ( doc/alt-openldap11-devel/rfc/rfc4529.txtnu �[��� Network Working Group K. Zeilenga Request for Comments: 4529 OpenLDAP Foundation Category: Informational June 2006 Requesting Attributes by Object Class in the Lightweight Directory Access Protocol (LDAP) Status of This Memo This memo provides information for the Internet community. It does not specify an Internet standard of any kind. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2006). Abstract The Lightweight Directory Access Protocol (LDAP) search operation provides mechanisms for clients to request all user application attributes, all operational attributes, and/or attributes selected by their description. This document extends LDAP to support a mechanism that LDAP clients may use to request the return of all attributes of an object class. Table of Contents 1. Background and Intended Use .....................................1 2. Terminology .....................................................2 3. Return of all Attributes of an Object Class .....................2 4. Security Considerations .........................................3 5. IANA Considerations .............................................3 6. References ......................................................4 6.1. Normative References .......................................4 6.2. Informative References .....................................4 1. Background and Intended Use In the Lightweight Directory Access Protocol (LDAP) [RFC4510], the search operation [RFC4511] supports requesting the return of a set of attributes. This set is determined by a list of attribute descriptions. Two special descriptors are defined to request all user attributes ("*") [RFC4511] and all operational attributes ("+") [RFC3673]. However, there is no convenient mechanism for requesting pre-defined sets of attributes such as the set of attributes used to represent a particular class of object. Zeilenga Informational [Page 1] RFC 4529 Requesting Attributes by Object Class June 2006 This document extends LDAP to allow an object class identifier to be specified in attributes lists, such as in Search requests, to request the return of all attributes belonging to an object class. The COMMERCIAL AT ("@", U+0040) character is used to distinguish an object class identifier from an attribute descriptions. For example, the attribute list of "@country" is equivalent to the attribute list of 'c', 'searchGuide', 'description', and 'objectClass'. This object class is described in [RFC4519]. This extension is intended primarily to be used where the user is in direct control of the parameters of the LDAP search operation, for instance when entering an LDAP URL [RFC4516] into a web browser, such as <ldap:///dc=example,dc=com?@organization?base>. 2. Terminology In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in BCP 14 [RFC2119]. DSA stands for Directory System Agent (or server). DSE stands for DSA-specific Entry. 3. Return of All Attributes of an Object Class This extension allows object class identifiers to be provided in the attributes field of the LDAP SearchRequest [RFC4511] or other request values of the AttributeSelection data type (e.g., attributes field in pre/post read controls [ReadEntry]) and/or <attributeSelector> production (e.g., attributes of an LDAP URL [RFC4516]). For each object class identified in the attributes field, the request is to be treated as if each attribute allowed by that class (by "MUST" or "MAY", directly or by "SUP"erior) [RFC4512] were itself listed. This extension extends the <attributeSelector> [RFC4511] production as indicated by the following ABNF [RFC4234]: attributeSelector =/ objectclassdescription objectclassdescription = ATSIGN oid options ATSIGN = %x40 ; COMMERCIAL AT ("@" U+0040) where <oid> and <options> productions are as defined in [RFC4512]. Zeilenga Informational [Page 2] RFC 4529 Requesting Attributes by Object Class June 2006 The <oid> component of an <objectclassdescription> production identifies the object class by short name (descr) or object identifier (numericoid). If the value of the <oid> component is unrecognized or does not refer to an object class, the object class description is to be treated as an unrecognized attribute description. The <options> production is included in the grammar for extensibility purposes. An object class description with an unrecognized or inappropriate option is to be treated as unrecognized. Although object class description options and attribute description options share the same syntax, they are not semantically related. This document does not define any object description option. Servers supporting this feature SHOULD publish the object identifier (OID) 1.3.6.1.4.1.4203.1.5.2 as a value of the 'supportedFeatures' [RFC4512] attribute in the root DSE. Clients supporting this feature SHOULD NOT use the feature unless they know that the server supports it. 4. Security Considerations This extension provides a shorthand for requesting all attributes of an object class. Because these attributes could have been listed individually, introduction of this shorthand is not believed to raise additional security considerations. Implementors of this LDAP extension should be familiar with security considerations applicable to the LDAP search operation [RFC4511], as well as with general LDAP security considerations [RFC4510]. 5. IANA Considerations Registration of the LDAP Protocol Mechanism [RFC4520] defined in this document has been completed. Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: 1.3.6.1.4.1.4203.1.5.2 Description: OC AD Lists Person & email address to contact for further information: Kurt Zeilenga <kurt@openldap.org> Usage: Feature Specification: RFC 4529 Author/Change Controller: Kurt Zeilenga <kurt@openldap.org> Comments: none Zeilenga Informational [Page 3] RFC 4529 Requesting Attributes by Object Class June 2006 This OID was assigned [ASSIGN] by OpenLDAP Foundation, under its IANA-assigned private enterprise allocation [PRIVATE], for use in this specification. 6. References 6.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC4234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 4234, October 2005. [RFC4510] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006. [RFC4511] Sermersheim, J., Ed., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006. [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006. [RFC4516] Smith, M., Ed. and T. Howes, "Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator", RFC 4516, June 2006. [X.680] International Telecommunication Union - Telecommunication Standardization Sector, "Abstract Syntax Notation One (ASN.1) - Specification of Basic Notation", X.680(2002) (also ISO/IEC 8824-1:2002). 6.2. Informative References [RFC3673] Zeilenga, K., "Lightweight Directory Access Protocol version 3 (LDAPv3): All Operational Attributes", RFC 3673, December 2003. [RFC4519] Sciberras, A., Ed., "Lightweight Directory Access Protocol (LDAP): Schema for User Applications", RFC 4519, June 2006. [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006. Zeilenga Informational [Page 4] RFC 4529 Requesting Attributes by Object Class June 2006 [ReadEntry] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP) Read Entry Controls", RFC 4527, June 2006. [ASSIGN] OpenLDAP Foundation, "OpenLDAP OID Delegations", http://www.openldap.org/foundation/oid-delegate.txt. [PRIVATE] IANA, "Private Enterprise Numbers", http://www.iana.org/assignments/enterprise-numbers. Author's Address Kurt D. Zeilenga OpenLDAP Foundation EMail: Kurt@OpenLDAP.org Zeilenga Informational [Page 5] RFC 4529 Requesting Attributes by Object Class June 2006 Full Copyright Statement Copyright (C) The Internet Society (2006). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Zeilenga Informational [Page 6] PK *�c\�N �bw bw ( doc/alt-openldap11-devel/rfc/rfc4516.txtnu �[��� Network Working Group M. Smith, Ed. Request for Comments: 4516 Pearl Crescent, LLC Obsoletes: 2255 T. Howes Category: Standards Track Opsware, Inc. June 2006 Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator Status of This Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2006). Abstract This document describes a format for a Lightweight Directory Access Protocol (LDAP) Uniform Resource Locator (URL). An LDAP URL describes an LDAP search operation that is used to retrieve information from an LDAP directory, or, in the context of an LDAP referral or reference, an LDAP URL describes a service where an LDAP operation may be progressed. Table of Contents 1. Introduction ....................................................2 2. URL Definition ..................................................2 2.1. Percent-Encoding ...........................................4 3. Defaults for Fields of the LDAP URL .............................5 4. Examples ........................................................6 5. Security Considerations .........................................8 6. Normative References ............................................9 7. Informative References .........................................10 8. Acknowledgements ...............................................10 Appendix A: Changes Since RFC 2255 ................................11 A.1. Technical Changes .........................................11 A.2. Editorial Changes .........................................11 Smith & Howes Standards Track [Page 1] RFC 4516 LDAP: Uniform Resource Locator June 2006 1. Introduction LDAP is the Lightweight Directory Access Protocol [RFC4510]. This document specifies the LDAP URL format for version 3 of LDAP and clarifies how LDAP URLs are resolved. This document also defines an extension mechanism for LDAP URLs. This mechanism may be used to provide access to new LDAP extensions. Note that not all the parameters of the LDAP search operation described in [RFC4511] can be expressed using the format defined in this document. Note also that URLs may be used to represent reference knowledge, including that for non-search operations. This document is an integral part of the LDAP technical specification [RFC4510], which obsoletes the previously defined LDAP technical specification, RFC 3377, in its entirety. This document replaces RFC 2255. See Appendix A for a list of changes relative to RFC 2255. 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]. 2. URL Definition An LDAP URL begins with the protocol prefix "ldap" and is defined by the following grammar, following the ABNF notation defined in [RFC4234]. 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" Smith & Howes Standards Track [Page 2] RFC 4516 LDAP: Uniform Resource Locator June 2006 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 ("?") The "ldap" prefix indicates an entry or entries accessible from the LDAP server running on the given hostname at the given portnumber. Note that the <host> may contain literal IPv6 addresses as specified in Section 3.2.2 of [RFC3986]. The <dn> is an LDAP Distinguished Name using the string format described in [RFC4514]. It identifies the base object of the LDAP search or the target of a non-search operation. The <attributes> construct is used to indicate which attributes should be returned from the entry or entries. The <scope> construct is used to specify the scope of the search to perform in the given LDAP server. The allowable scopes are "base" for a base object search, "one" for a one-level search, or "sub" for a subtree search. Smith & Howes Standards Track [Page 3] RFC 4516 LDAP: Uniform Resource Locator June 2006 The <filter> is used to specify the search filter to apply to entries within the specified scope during the search. It has the format specified in [RFC4515]. The <extensions> construct provides the LDAP URL with an extensibility mechanism, allowing the capabilities of the URL to be extended in the future. Extensions are a simple comma-separated list of type=value pairs, where the =value portion MAY be omitted for options not requiring it. Each type=value pair is a separate extension. These LDAP URL extensions are not necessarily related to any of the LDAP extension mechanisms. Extensions may be supported or unsupported by the client resolving the URL. An extension prefixed with a '!' character (ASCII 0x21) is critical. An extension not prefixed with a '!' character is non-critical. If an LDAP URL extension is implemented (that is, if the implementation understands it and is able to use it), the implementation MUST make use of it. If an extension is not implemented and is marked critical, the implementation MUST NOT process the URL. If an extension is not implemented and is not marked critical, the implementation MUST ignore the extension. The extension type (<extype>) MAY be specified using the numeric OID <numericoid> form (e.g., 1.2.3.4) or the descriptor <descr> form (e.g., myLDAPURLExtension). Use of the <descr> form SHOULD be restricted to registered object identifier descriptive names. See [RFC4520] for registration details and usage guidelines for descriptive names. No LDAP URL extensions are defined in this document. Other documents or a future version of this document MAY define one or more extensions. 2.1. Percent-Encoding A generated LDAP URL MUST consist only of the restricted set of characters included in one of the following three productions defined in [RFC3986]: <reserved> <unreserved> <pct-encoded> Implementations SHOULD accept other valid UTF-8 strings [RFC3629] as input. An octet MUST be encoded using the percent-encoding mechanism described in section 2.1 of [RFC3986] in any of these situations: Smith & Howes Standards Track [Page 4] RFC 4516 LDAP: Uniform Resource Locator June 2006 The octet is not in the reserved set defined in section 2.2 of [RFC3986] or in the unreserved set defined in section 2.3 of [RFC3986]. It is the single Reserved character '?' and occurs inside a <dn>, <filter>, or other element of an LDAP URL. It is a comma character ',' that occurs inside an <exvalue>. Note that before the percent-encoding mechanism is applied, the extensions component of the LDAP URL may contain one or more null (zero) bytes. No other component may. 3. Defaults for Fields of the LDAP URL Some fields of the LDAP URL are optional, as described above. In the absence of any other specification, the following general defaults SHOULD be used when a field is absent. Note that other documents MAY specify different defaulting rules; for example, section 4.1.10 of [RFC4511] specifies a different rule for determining the correct DN to use when it is absent in an LDAP URL that is returned as a referral. <host> If no <host> is given, the client must have some a priori knowledge of an appropriate LDAP server to contact. <port> The default LDAP port is TCP port 389. <dn> If no <dn> is given, the default is the zero-length DN, "". <attributes> If the <attributes> part is omitted, all user attributes of the entry or entries should be requested (e.g., by setting the attributes field AttributeDescriptionList in the LDAP search request to a NULL list, or by using the special <alluserattrs> selector "*"). <scope> If <scope> is omitted, a <scope> of "base" is assumed. <filter> If <filter> is omitted, a filter of "(objectClass=*)" is assumed. <extensions> If <extensions> is omitted, no extensions are assumed. Smith & Howes Standards Track [Page 5] RFC 4516 LDAP: Uniform Resource Locator June 2006 4. Examples The following are some example LDAP URLs that use the format defined above. The first example is an LDAP URL referring to the University of Michigan entry, available from an LDAP server of the client's choosing: ldap:///o=University%20of%20Michigan,c=US The next example is an LDAP URL referring to the University of Michigan entry in a particular ldap server: ldap://ldap1.example.net/o=University%20of%20Michigan,c=US Both of these URLs correspond to a base object search of the "o=University of Michigan,c=US" entry using a filter of "(objectclass=*)", requesting all attributes. The next example is an LDAP URL referring to only the postalAddress attribute of the University of Michigan entry: ldap://ldap1.example.net/o=University%20of%20Michigan, c=US?postalAddress The corresponding LDAP search operation is the same as in the previous example, except that only the postalAddress attribute is requested. The next example is an LDAP URL referring to the set of entries found by querying the given LDAP server on port 6666 and doing a subtree search of the University of Michigan for any entry with a common name of "Babs Jensen", retrieving all attributes: ldap://ldap1.example.net:6666/o=University%20of%20Michigan, c=US??sub?(cn=Babs%20Jensen) The next example is an LDAP URL referring to all children of the c=GB entry: LDAP://ldap1.example.com/c=GB?objectClass?ONE The objectClass attribute is requested to be returned along with the entries, and the default filter of "(objectclass=*)" is used. The next example is an LDAP URL to retrieve the mail attribute for the LDAP entry named "o=Question?,c=US", illustrating the use of the percent-encoding mechanism on the reserved character '?'. Smith & Howes Standards Track [Page 6] RFC 4516 LDAP: Uniform Resource Locator June 2006 ldap://ldap2.example.com/o=Question%3f,c=US?mail The next example (which is broken into two lines for readability) illustrates the interaction between the LDAP string representation of the filters-quoting mechanism and the URL-quoting mechanisms. ldap://ldap3.example.com/o=Babsco,c=US ???(four-octet=%5c00%5c00%5c00%5c04) The filter in this example uses the LDAP escaping mechanism of \ to encode three zero or null bytes in the value. In LDAP, the filter would be written as (four-octet=\00\00\00\04). Because the \ character must be escaped in a URL, the \s are percent-encoded as %5c (or %5C) in the URL encoding. The next example illustrates the interaction between the LDAP string representation of the DNs-quoting mechanism and URL-quoting mechanisms. ldap://ldap.example.com/o=An%20Example%5C2C%20Inc.,c=US The DN encoded in the above URL is: o=An Example\2C Inc.,c=US That is, the left-most RDN value is: An Example, Inc. The following three URLs are equivalent, assuming that the defaulting rules specified in Section 3 of this document are used: ldap://ldap.example.net ldap://ldap.example.net/ ldap://ldap.example.net/? These three URLs point to the root DSE on the ldap.example.net server. The final two examples show use of a hypothetical, experimental bind name extension (the value associated with the extension is an LDAP DN). ldap:///??sub??e-bindname=cn=Manager%2cdc=example%2cdc=com ldap:///??sub??!e-bindname=cn=Manager%2cdc=example%2cdc=com Smith & Howes Standards Track [Page 7] RFC 4516 LDAP: Uniform Resource Locator June 2006 The two URLs are the same, except that the second one marks the e-bindname extension as critical. Notice the use of the percent- encoding mechanism to encode the commas within the distinguished name value in the e-bindname extension. 5. Security Considerations The general URL security considerations discussed in [RFC3986] are relevant for LDAP URLs. The use of security mechanisms when processing LDAP URLs requires particular care, since clients may encounter many different servers via URLs, and since URLs are likely to be processed automatically, without user intervention. A client SHOULD have a user-configurable policy that controls which servers the client will establish LDAP sessions with and with which security mechanisms, and SHOULD NOT establish LDAP sessions that are inconsistent with this policy. If a client chooses to reuse an existing LDAP session when resolving one or more LDAP URLs, it MUST ensure that the session is compatible with the URL and that no security policies are violated. Sending authentication information, no matter the mechanism, may violate a user's privacy requirements. In the absence of specific policy permitting authentication information to be sent to a server, a client should use an anonymous LDAP session. (Note that clients conforming to previous LDAP URL specifications, where all LDAP sessions are anonymous and unprotected, are consistent with this specification; they simply have the default security policy.) Simply opening a transport connection to another server may violate some users' privacy requirements, so clients should provide the user with a way to control URL processing. Some authentication methods, in particular, reusable passwords sent to the server, may reveal easily-abused information to the remote server or to eavesdroppers in transit and should not be used in URL processing unless they are explicitly permitted by policy. Confirmation by the human user of the use of authentication information is appropriate in many circumstances. Use of strong authentication methods that do not reveal sensitive information is much preferred. If the URL represents a referral for an update operation, strong authentication methods SHOULD be used. Please refer to the Security Considerations section of [RFC4513] for more information. The LDAP URL format allows the specification of an arbitrary LDAP search operation to be performed when evaluating the LDAP URL. Following an LDAP URL may cause unexpected results, for example, the retrieval of large amounts of data or the initiation of a long-lived Smith & Howes Standards Track [Page 8] RFC 4516 LDAP: Uniform Resource Locator June 2006 search. The security implications of resolving an LDAP URL are the same as those of resolving an LDAP search query. 6. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003. [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005. [RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 4234, October 2005. [RFC4510] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006. [RFC4511] Sermersheim, J., Ed., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006. [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006. [RFC4513] Harrison, R., Ed., "Lightweight Directory Access Protocol (LDAP): Authentication Methods and Security Mechanisms", RFC 4513, June 2006. [RFC4514] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names", RFC 4514, June 2006. [RFC4515] Smith, M. Ed. and T. Howes, "Lightweight Directory Access Protocol (LDAP): String Representation of Search Filters", RFC 4515, June 2006. Smith & Howes Standards Track [Page 9] RFC 4516 LDAP: Uniform Resource Locator June 2006 7. Informative References [RFC2396] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, August 1998. [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006. 8. Acknowledgements The LDAP URL format was originally defined at the University of Michigan. This material is based upon work supported by the National Science Foundation under Grant No. NCR-9416667. The support of both the University of Michigan and the National Science Foundation is gratefully acknowledged. This document obsoletes RFC 2255 by Tim Howes and Mark Smith. Changes included in this revised specification are based upon discussions among the authors, discussions within the LDAP (v3) Revision Working Group (ldapbis), and discussions within other IETF Working Groups. The contributions of individuals in these working groups is gratefully acknowledged. Several people in particular have made valuable comments on this document: RL "Bob" Morgan, Mark Wahl, Kurt Zeilenga, Jim Sermersheim, and Hallvard Furuseth deserve special thanks for their contributions. Smith & Howes Standards Track [Page 10] RFC 4516 LDAP: Uniform Resource Locator June 2006 Appendix A: Changes Since RFC 2255 A.1. Technical Changes The following technical changes were made to the contents of the "URL Definition" section: Revised all of the ABNF to use common productions from [RFC4512]. Replaced references to [RFC2396] with a reference to [RFC3986] (this allows literal IPv6 addresses to be used inside the <host> portion of the URL, and a note was added to remind the reader of this enhancement). Referencing [RFC3986] required changes to the ABNF and text so that productions that are no longer defined by [RFC3986] are not used. For example, <hostport> is not defined by [RFC3986] so it has been replaced with host [COLON port]. Note that [RFC3986] includes new definitions for the "Reserved" and "Unreserved" sets of characters, and the net result is that the following two additional characters should be percent-encoded when they appear anywhere in the data used to construct an LDAP URL: "[" and "]" (these two characters were first added to the Reserved set by RFC 2732). Changed the definition of <attrdesc> to refer to <attributeSelector> from [RFC4511]. This allows the use of "*" in the <attrdesc> part of the URL. It is believed that existing implementations of RFC 2255 already support this. Avoided use of <prose-val> (bracketed-string) productions in the <dn>, <host>, <attrdesc>, and <exvalue> rules. Changed the ABNF for <ldapurl> to group the <dn> component with the preceding <SLASH>. Changed the <extype> rule to be an <oid> from [RFC4512]. Changed the text about extension types so it references [RFC4520]. Reordered rules to more closely follow the order in which the elements appear in the URL. "Bindname Extension": removed due to lack of known implementations. A.2. Editorial Changes Changed document title to include "LDAP:" prefix. IESG Note: removed note about lack of satisfactory mandatory authentication mechanisms. Smith & Howes Standards Track [Page 11] RFC 4516 LDAP: Uniform Resource Locator June 2006 "Status of this Memo" section: updated boilerplate to match current I-D guidelines. "Abstract" section: separated from introductory material. "Table of Contents" and "Intellectual Property" sections: added. "Introduction" section: new section; separated from the Abstract. Changed the text indicate that RFC 2255 is replaced by this document (instead of RFC 1959). Added text to indicate that LDAP URLs are used for references and referrals. Fixed typo (replaced the nonsense phrase "to perform to retrieve" with "used to retrieve"). Added a note to let the reader know that not all of the parameters of the LDAP search operation described in [RFC4511] can be expressed using this format. "URL Definition" section: removed second copy of <ldapurl> grammar and following two paragraphs (editorial error in RFC 2255). Fixed line break within '!' sequence. Reformatted the ABNF to improve readability by aligning comments and adding some blank lines. Replaced "residing in the LDAP server" with "accessible from the LDAP server" in the sentence immediately following the ABNF. Removed the sentence "Individual attrdesc names are as defined for AttributeDescription in [RFC4511]." because [RFC4511]'s <attributeSelector> is now used directly in the ABNF. Reworded last paragraph to clarify which characters must be percent-encoded. Added text to indicate that LDAP URLs are used for references and referrals. Added text that refers to the ABNF from RFC 4234. Clarified and strengthened the requirements with respect to processing of URLs that contain implemented and not implemented extensions (the approach now closely matches that specified in [RFC4511] for LDAP controls). "Defaults for Fields of the LDAP URL" section: added; formed by moving text about defaults out of the "URL Definition" section. Replaced direct reference to the attribute name "*" with a reference to the special <alluserattrs> selector "*" defined in [RFC4511]. "URL Processing" section: removed. "Examples" section: Modified examples to use example.com and example.net hostnames. Added missing '?' to the LDAP URL example whose filter contains three null bytes. Removed space after one comma within a DN. Revised the bindname example to use e-bindname. Changed the name of an attribute used in one example from "int" to "four-octet" to avoid potential confusion. Added an example that demonstrates the interaction between DN escaping and URL percent- encoding. Added some examples to show URL equivalence with respect Smith & Howes Standards Track [Page 12] RFC 4516 LDAP: Uniform Resource Locator June 2006 to the <dn> portion of the URL. Used uppercase in some examples to remind the reader that some tokens are case-insensitive. "Security Considerations" section: Added a note about connection reuse. Added a note about using strong authentication methods for updates. Added a reference to [RFC4513]. Added note that simply opening a connection may violate some users' privacy requirements. Adopted the working group's revised LDAP terminology specification by replacing the word "connection" with "LDAP session" or "LDAP connection" as appropriate. "Acknowledgements" section: added statement that this document obsoletes RFC 2255. Added Kurt Zeilenga, Jim Sermersheim, and Hallvard Furuseth. "Normative References" section: renamed from "References" per new RFC guidelines. Changed from [1] style to [RFC4511] style throughout the document. Added references to RFC 4234 and RFC 3629. Updated all RFC 1738 references to point to the appropriate sections within [RFC3986]. Updated the LDAP references to refer to LDAPBis WG documents. Removed the reference to the LDAP Attribute Syntaxes document and added references to the [RFC4513], [RFC4520], and [RFC4510] documents. "Informative References" section: added. Header and "Authors' Addresses" sections: added "editor" next to Mark Smith's name. Updated affiliation and contact information. Copyright: updated the year. Throughout the document: surrounded the names of all ABNF productions with "<" and ">" where they are used in descriptive text. Smith & Howes Standards Track [Page 13] RFC 4516 LDAP: Uniform Resource Locator June 2006 Authors' Addresses Mark Smith, Editor Pearl Crescent, LLC 447 Marlpool Dr. Saline, MI 48176 USA Phone: +1 734 944-2856 EMail: mcs@pearlcrescent.com Tim Howes Opsware, Inc. 599 N. Mathilda Ave. Sunnyvale, CA 94085 USA Phone: +1 408 744-7509 EMail: howes@opsware.com Smith & Howes Standards Track [Page 14] RFC 4516 LDAP: Uniform Resource Locator June 2006 Full Copyright Statement Copyright (C) The Internet Society (2006). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Smith & Howes Standards Track [Page 15] PK *�c\p=�� �� ( doc/alt-openldap11-devel/rfc/rfc2377.txtnu �[��� Network Working Group A. Grimstad Request for Comments: 2377 R. Huber Category: Informational AT&T S. Sataluri Lucent Technologies M. Wahl Critical Angle Inc. September 1998 Naming Plan for Internet Directory-Enabled Applications Status of this Memo This memo provides information for the Internet community. It does not specify an Internet standard of any kind. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (1998). All Rights Reserved. Abstract Application of the conventional X.500 approach to naming has heretofore, in the experience of the authors, proven to be an obstacle to the wide deployment of directory-enabled applications on the Internet. We propose a new directory naming plan that leverages the strengths of the most popular and successful Internet naming schemes for naming objects in a hierarchical directory. This plan can, we believe, by extending the X.500 approach to naming, facilitate the creation of an Internet White Pages Service (IWPS) and other directory-enabled applications by overcoming the problems encountered by those using the conventional X.500 approach. 1.0 Executive Summary Application of the conventional X.500 approach to naming has heretofore, in the experience of the authors, proven to be an obstacle to the wide deployment of directory-enabled applications on the Internet. The required registration infrastructure is either non-existent or largely ignored. The infrastructure that does exist is cumbersome to use and tends to produce counterproductive results. The attributes used for naming have been confusing for users and inflexible to managers and operators of directory servers. Grimstad, et. al. Informational [Page 1] RFC 2377 A Directory Naming Plan September 1998 This paper describes a directory naming plan for the construction of an Internet directory infrastructure to support directory-enabled applications that can serve as an alternative (or extension) to the conventional X.500 approach. The plan has the following two main features. First, it bases the root and upper portions of the name hierarchy on the existing infrastructure of names from the Domain Name System (DNS). This component of the plan makes use of the ideas described in the companion paper to this plan, "Using Domains in LDAP Distinguished Names" [1]. And second, it provides a number of options for the assignment of names to directory leaf objects such as person objects, including an option that allows the reuse of existing Internet identifiers for people. Just as the conventional X.500 style of naming is not a formal standard, use of the naming plan described here is not obligatory for directory-enabled applications on the Internet. Other approaches are permissible. However, we believe widespread use of this plan will largely eliminate naming as a typically thorny issue when administrators set up an LDAP-based directory service. Further, we strongly encourage developers of directory-enabled products, especially LDAP clients and user interfaces, to assume that this naming plan will see widespread use and design their products accordingly. Here, in summary, is our proposal. The upper portions of the hierarchical directory tree should be constructed using the components of registered DNS names using the domain component attribute "dc". The directory name for the organization having the domain name "acme.com" will then be, e.g., dc=acme, dc=com Organizations can add additional directory structure, for example to support implementation of access control lists or partitioning of their directory information, by using registered subdomains of DNS names, e.g., the subdomain "corporate.acme.com" can be used as the basis for the directory name dc=corporate, dc=acme, dc=com For naming directory leaf objects such as persons, groups, server applications and certification authorities in a hierarchical directory, we propose the use of either the "uid" (user identifier) or the "cn" (common name) attribute for the relative distinguished name. This plan does not constrain how these two attributes are used. Grimstad, et. al. Informational [Page 2] RFC 2377 A Directory Naming Plan September 1998 One approach to their use, for example, is to employ the uid attribute as the RDN when reusing an existing store of identifiers and the cn attribute as the RDN when creating new identifiers specifically for the directory. A convenient existing identification scheme for person objects is the RFC822 mailbox identifier. So an RDN for person employing this store of identifiers would be, e.g., uid=John.Smith@acme.com For leaf objects not conveniently identified with such a scheme, the "cn" attribute is used, e.g., cn=Reading Room Directory distinguished names will thus have the following structure, e.g., uid=John.Smith@acme.com, dc=acme, dc=com uid=Mary.Jones@acme.com, dc=corporate, dc=acme, dc=com uid=J.Smith@worldnet.att.net, dc=legal, dc=acme, dc=com cn=Reading Room, dc=physics, dc=national-lab, dc=edu 2.0 The Problem The X.500 Directory model [2] can be used to create a world-wide distributed directory. The Internet X.500 Directory Pilot has been operational for several years and has grown to a size of about 1.5 million entries of varying quality. The rate of growth of the pilot is far lower than the rate of growth of the Internet during the pilot period. There are a substantial number of contributing factors that have inhibited the growth of this pilot. The common X.500 approach to naming, while not the preponderant problem, has contributed in several ways to limit the growth of an Internet White Pages Service based on X.500. The conventional way to construct names in the X.500 community is documented as an informative (i.e., not officially standardized) Annex B to X.521. The relative distinguished name (RDN) of a user consists of a common name (cn) attribute. This is meant to be what -- in the user's particular society -- is customarily understood to be the name of that user. The distinguished name of a user is the combination of the name of some general object, such as an organization or a geographical unit, with the common name. There are two main problems with this style of name construction. Grimstad, et. al. Informational [Page 3] RFC 2377 A Directory Naming Plan September 1998 First, the common name attribute, while seeming to be user-friendly, cannot be used generally as an RDN in practice. In any significant set of users to be named under the same Directory Information Tree (DIT) node there will be collisions on common name. There is no way to overcome this other than either by forcing uniqueness on common names, something they do not possess, or by using an additional attribute to prevent collisions. This additional attribute normally needs to be unique in a much larger context to have any practical value. The end result is a RDN that is very long and unpopular with users. Second, and more serious, X.500 has not been able to use any significant number of pre-existing names. Since X.500 naming models typically use organization names as part of the hierarchy [2, 3], organization names must be registered. As organization names are frequently tied to trademarks and are used in sales and promotions, registration can be a difficult and acrimonious process. The North American Directory Forum (NADF, now the North Atlantic Directory Forum but still the NADF) proposed to avoid the problem of registration by using names that were already registered in the "civil naming infrastructure" [4][5]. Directory distinguished names would be based on an organization's legal name as recognized by some governmental agency (county clerk, state secretary of state, etc.) or other registering entity such as ANSI. This scheme has the significant advantage of keeping directory service providers out of disputes about the right to use a particular name, but it leads to rather obscure names. Among these obscurities, the legal name almost invariably takes a form that is less familiar and longer than what users typically associate with the organization. For example, in the US a large proportion of legal organization names end with the text ", Inc." as in "Acme, Inc." Moreover, in the case of the US, the civil naming infrastructure does not operate nationally, so the organization names it provides must be located under state and regional DIT nodes, making them difficult to find while browsing the directory. NADF proposes a way to algorithmically derive multi-attribute RDNs which would allow placement of entries or aliases in more convenient places in the DIT, but these derived names are cumbersome and unpopular. For example, suppose Nadir is an organization that is registered in New Jersey civil naming infrastructure under the name "Nadir Networks, Inc." Its civil distinguished name (DN) would then be o="Nadir Networks, Inc.", st=New Jersey, c=US Grimstad, et. al. Informational [Page 4] RFC 2377 A Directory Naming Plan September 1998 while its derived name which is unambiguous under c=US directly is o="Nadir Networks, Inc." + st=New Jersey, c=US More generally, the requirement for registration of organizations in X.500 naming has led to the establishment of national registration authorities whose function is mainly limited to assignment of X.500 organization names. Because of the very limited attraction of X.500, interest in registering an organization with one of these national authorities has been minimal. Finally, multi-national organizations are frustrated by a lack of an international registration authority. 3.0 Requirements A directory naming plan must provide a guide for the construction of names (identifiers, labels) for directory objects that are unambiguous (identify only one directory object) within some context (namespace), at a minimum within one isolated directory server. A directory object is simply a set of attribute values. The association between a real-world object and a directory object is made by directory-enabled applications and is, in the general case, one to many. The following additional naming characteristics are requirements that this naming plan seeks to satisfy: a) hierarchical The Internet, consisting of a very large number of objects and management domains, requires hierarchical names. Such names permit delegation in the name assignment process and partitioning of directory information among directory servers. b) friendly to loose coupling of directory servers One purpose of this naming plan is to define a naming pattern that will facilitate one form or another of loose coupling of potentially autonomous directory servers into a larger system. A name in such a loosely-coupled system should unambiguously identify one real-world object. The real-world object may, however, be represented differently (i.e. by different directory objects having different attributes but the same DN) in different (e.g. independently managed) servers in the loosely-coupled system. The plan does not attempt to produce names to overcome this likely scenario. That is, it does not attempt to produce a single namespace for all directory objects. (This issue is considered in more detail Grimstad, et. al. Informational [Page 5] RFC 2377 A Directory Naming Plan September 1998 in Section 5.1.) c) readily usable by LDAP clients and servers As of this writing, a substantial number of the Lightweight Directory Access Protocol (LDAP) [6][7] implementations are currently available or soon will be. The names specified by this naming plan should be readily usable by these implementations and applications based on them. d) friendly to re-use of existing Internet name registries As described in Section 2 above, creation of new global name registries has been highly problematic. Therefore, a fundamental requirement this plan addresses is to enable the reuse of existing Internet name registries such as DNS names and RFC822 mailbox identifiers when constructing directory names. e) minimally user-friendly Although we expect that user interfaces of directory-enabled applications will avoid exposing users to DNs, it is unlikely that users can be totally insulated from them. For this reason, the naming plan should permit use of familiar information in name construction. Minimally, a user should be capable of recognizing the information encoded in his/her own DN. Names that are totally opaque to users cannot meet this requirement. 4.0 Name Construction The paper assumes familiarity with the terminology and concepts behind the terms distinguished name (DN) and relative distinguished name (RDN) [2][8][9]. We describe how DNs can be constructed using three attribute types, domainComponent (dc), userID (uid) and commonName (cn). They are each described in turn. 4.1 Domain Component (dc) The domain component attribute is defined and registered in RFC1274 [3][10]. It is used in the construction of a DN from a domain name. Details of the construction algorithm is described in "Using Domains in LDAP Distinguished Names" [1]. An organization wishing to deploy a directory following this naming plan would proceed as follows. Consider an organization, for example "Acme, Inc.", having the registered domain name "acme.com". It would Grimstad, et. al. Informational [Page 6] RFC 2377 A Directory Naming Plan September 1998 construct the DN dc=acme, dc=com from its domain name. It would then use this DN as the root of its subtree of directory information. The DN itself can be used to identify a directory organization object that represents information about the organization. The directory schema required to enable this is described below in section 5.2. The subordinates of the DN will be directory objects related to the organization. The domain component attribute can be used to name subdivisions of the organization such as organizational units and localities. Acme, for example, might use the domain names "corporate.acme.com" and "richmond.acme.com" to construct the names dc=corporate, dc=acme, dc=com dc=richmond, dc=acme, dc=com under which to place its directory objects. The directory schema required to name organizationalUnit and locality objects in this way is described below in section 5.2. Note that subdivisions of the organization such as organizational units and localities could also be assigned RDNs using the conventional X.500 naming attributes, e.g. ou=corporate, dc=acme, dc=com l=richmond, dc=acme, dc=com. Use of the dc attribute for the RDN of directory objects of class "domain" is also possible [1]. 4.2 User ID (uid) The userid (uid) attribute is defined and registered in RFC1274 [3][10]. This attribute may be used to construct the RDN for directory objects subordinate to objects named according to the procedure described in Section 4.1. This plan does not constrain how this attribute is used. 4.3 Common Name (cn) The commonName (cn) attribute is defined and registered in X.500 [3][11]. Grimstad, et. al. Informational [Page 7] RFC 2377 A Directory Naming Plan September 1998 This attribute may be used to construct the RDN for directory objects subordinate to objects named according to the procedure described in Section 4.1. This plan does not constrain how this attribute is used. 4.4 Examples of uid and cn Usage Although this plan places no constraints on the use of the uid and cn attributes for name construction, we would like to offer some suggestions by way of examples. In practice, we have used uid for the RDN for person objects were we could make use of an existing registry of names and cn for other objects. Examples of existing registries of identifiers for person objects are RFC822 mailbox identifiers, employee numbers and employee "handles". Aside from the convenience to administrators of re-use of an existing store of identifiers, if it is ever necessary to display to a user his/her DN, there is some hope that it will be recognizable when such identifiers are used. We have found RFC822 mailbox identifiers a particularly convenient source for name construction. When a person has several e-mail addresses, one will be selected for the purpose of user identification. We call this the "distinguished" e-mail address or the "distinguished" RFC822 mailbox identifier for the user. For example, if there is a user affiliated with the organization Acme having distinguished e-mail address J.Smith@acme.com, the uid attribute will be: uid=J.Smith@acme.com The domain component attributes of a user's DN will normally be constructed from the domain name of his/her distinguished e-mail address. That is, for the user uid=J.Smith@acme.com the domain component attributes would typically be: dc=acme, dc=com The full LDAP DN for this user would then be: uid=J.Smith@acme.com, dc=acme, dc=com Directory administrators having several RFC822 identifiers to choose from when constructing a DN for a user should consider the following factors: Grimstad, et. al. Informational [Page 8] RFC 2377 A Directory Naming Plan September 1998 o Machine-independent addresses are likely to be more stable, resulting in directory names that change less. Thus an identifier such as: js@acme.com may well be preferable to one such as: js@blaster.third-floor.acme.com. o Use of some form of "handle" for the "local" part that is distinct from a user's real name may result in fewer collisions and thereby lessen user pain and suffering. Thus the identifier: js@acme.com may well be preferable to one such as: J.Smith@acme.com Practical experience with use of the RFC822 mailbox identifier scheme described here has shown that there are situations where it is convenient to use such identifies for all users in a particular population, although a few users do not, in fact, possess working mailboxes. For example, an organization may have a existing unique identification scheme for all employees that is used as a alias to the employees' real mailboxes -- which may be quite heterogeneous in structure. The identification scheme works for all employees to identify unambiguously each employee; it only works as an e-mail alias for those employees having real mailboxes. For this reason it would be a bad assumption for directory-enabled applications to assume the uid to be a valid mailbox; the value(s) of the mail attribute should always be checked. It is important to emphasize that the elements of the domain name of an RFC822 identifier may, BUT NEED NOT, be the same as the domain components of the DN. This means that the domain components provide a degree of freedom to support access control or other directory structuring requirements that need not be mechanically reflected in the user's e-mail address. We do not want under any condition to force the user's e-mail address to change just to facilitate a new system requirement such as a modification in an access control structure. It should also be noted that while we do not require that the domain components match the RFC822 identifier, we DO require that the concatenated domain components form a registered domain name, that is, one that is represented in the DNS. This automatically avoids name conflicts in the directory hierarchy. Grimstad, et. al. Informational [Page 9] RFC 2377 A Directory Naming Plan September 1998 To provide an example of a DN which deviates from what might be considered the default structure, consider the following scenario. Suppose that J.Smith needs to be granted special permissions to information in the dc=acme, dc=com part of the LDAP DIT. Since it will be, in general, easier to organize special users by their name structure than via groups (an arbitrary collection of DNs), we use subdomains for this purpose. Suppose the special permissions were required by users in the MIS organizational unit. A subdomain "mis.acme.com" is established, if it does not already exist, according to normal DNS procedures. The special permissions will be granted to users with the name structure: uid=*, dc=mis, dc=acme, dc=com The DN of J.Smith in this case will be: uid=J.Smith@acme.com, dc=mis, dc=acme, dc=com In principal, there is nothing to prevent the domain name elements of the RFC822 identifier from being completely different from the domain components of the DN. For instance, the DN for a J.Smith could be: uid=J.Smith@worldnet.att.net, dc=mis, dc=acme, dc=com While we do not REQUIRE that the domain name part of the uid match the dc components of the directory distinguished name, we suggest that this be done where possible. At a minimum, if the most significant pieces of the DN and the uid are the same (i.e., "dc=acme, dc=com" and "acme.com") the likelihood, based on a knowledge of a user's e-mail address, of discovering an appropriate directory system to contact to find information about the user is greatly enhanced. The example above represents a situation where this suggestion isn't possible because some of the users in a population have mailbox identifiers that differ from the pattern of the rest of the users, e.g., most mailboxes are of the form local@acme.com, but a subpopulation have mailboxes from an ISP and therefore mailboxes of the form local@worldnet.att.net. 5.0 Naming Plan and Directories 5.1 Directory Services Considerations We envision the deployment of LDAP-based directory services on the Internet to take the form of loosely coupled LDAP servers. This coupling will occur at two levels. Grimstad, et. al. Informational [Page 10] RFC 2377 A Directory Naming Plan September 1998 Firstly, LDAP servers will be loosely connected into islands (i.e. a set of servers sharing a single DN namespace). The glue connecting the islands will be LDAP referral [12] information configured into the LDAP servers. An LDAP search directed to any server in such an island can be answered, if the information is not available to that server, by an LDAP referral to another, more appropriate server within the same island. Secondly, various techniques will be used span LDAP islands. The concept that enables such techniques is the LDAP URL [13]. By combining a DNS host name and port (corresponding to one or more LDAP servers) with a DN, the LDAP URL provides unified high-level identification scheme (an LDAP URL namespace) for directory objects. Because an LDAP referral is expressed as one or more LDAP URL, these two levels of coupling may not sharply distinguished in practice. We do not envision the X.500 model of a single DIT (i.e. a single DN namespace) to be viable in an environment of competing service providers. This naming plan does not attempt to produce DNs to hide the possibility that a given real-world object may have independently managed directory objects with the same DN associated with it. 5.2 Directory Schema Implications of the Naming Plan The traditional directory schema(s) developed for the X.500 standard and its application to the Internet [4] require extension to be used with the naming plan developed here. The extensions described below attempt to reuse existing schema elements as much as possible. The directory objects for which extensions are required are: organization, organizational unit, and various classes of leaf objects. We describe the schema modifications below for organization, organizationalUnit and selected leaf classes. So as to continue to use existing structural object classes to the extent possible, we propose supplementing entries based on these classes with additional information from two new auxiliary object classes, dcObject and uidObject. They are specified using the notation in Section 4 of [14]. The auxiliary object class dcObject is defined in "Using Domains in LDAP Distinguished Names" [1]. Grimstad, et. al. Informational [Page 11] RFC 2377 A Directory Naming Plan September 1998 The auxiliary object class uidObject is defined as: ( 1.3.6.1.1.3.1 NAME uidObject SUP top AUXILIARY MUST uid ) 5.2.1 Organization Schema The dc attribute is employed to construct the RDN of an organization object. This is enabled by adding the auxiliary class dcObject to the organization's objectClass attribute. 5.2.2 Organizational Unit Schema The dc attribute is employed to construct the RDN of an organizationalUnit object (which is subordinate in the DIT to either an organization or an organizationalUnit object). This is enabled by adding the auxiliary class dcObject to the organizational unit's objectClass attribute. 5.2.3 Person Schema No schema extensions are required for person objects if either the inetOrgPerson [15] (preferred) or the newPilotPerson object classes are used. The attribute uid is permissible in each class. For consistency, the uidObject could be added to person entry objectClass attributes to assist applications filtering on this object class attribute value. Use of other classes for person objects with RDN constructed with the uid attribute such as organizationalPerson requires the use of the uidObject class. It has been traditional in X.500 and LDAP directory services to employ the common name (cn) attribute in naming. While this naming plan doesn't require use of the cn attribute in naming, it should be stressed that it is a required attribute in any class derived from the person class and is still quite important. It will play a significant role in enabling searches to find user entries of interest. 5.2.4 Certification Authority Schema The certification authority (CA) object class is an auxiliary class, meaning it is essentially a set of additional attributes for a base class such as organizationalRole, organization, organizationalUnit or person. Except in the case where the base structural class is inetOrgPerson, use of the uid attribute to construct the RDN of a CA Grimstad, et. al. Informational [Page 12] RFC 2377 A Directory Naming Plan September 1998 will require the auxiliary class uidObject to permit the uid attribute to be used. In the cases where organizationalUnit or organization is the base class for a CA, use of the auxiliary class dcObject will permit the RDN of the CA to be a domain component. 5.2.5 Server and Server Application Schema Servers and server applications are typically represented, for want of anything better, by entries of the object class applicationProcess (or a class derived from it). Sometimes the class applicationEntity is used. In either case, the uid attribute should probably not be employed to construct the RDN of a server or server application object. The standard schema uses the attribute cn for such RDNs. Suppose one wants to use this naming plan both in the construction of DNs for SSL server certificates and for their storage in a directory. It is customary for clients connecting via SSL to compare the server's domain name (e.g. from the URL used to contact the server) with the value of the cn attribute in the subject field (i.e. subject's DN) of the server's certificate. For this reason, it is common practice to set the cn attribute to the server's domain name. The naming and schema to handle this situation is best explained by an example. Consider the server "host.acme.com". Following the algorithm in "Using Domains in LDAP Distinguished Names" [1], the DN dc=host, dc=acme, dc=com is constructed. To conform to the existing practices just described, the server's subject DN for the SSL server certificate should be cn=host.acme.com, dc=host, dc=acme, dc=com and the server's certificate should be stored in a directory entry with this name. This entry should use application process or application entity as its structural object class and strong authentication user as is auxiliary class. 5.2.6 Name Forms For X.500 servers or LDAP servers following the X.500 model, our schema requires the definition of new name forms, structure rules, and DIT content rules. Structure rules and DIT content rules are locally defined, and do not involve a globally significant object identifier. The following name forms are defined using the syntax of section 6.22 of [14] for the convenience of those using such servers. Note that since the structural object classes organization, organizationalUnit, locality and organizationalPerson do not permit inclusion of the dc attribute, an auxiliary object class such as dcObject [1] must be used for instances of these classes.) Grimstad, et. al. Informational [Page 13] RFC 2377 A Directory Naming Plan September 1998 5.2.6.1 Name Form for Domain Objects The OIDs in this group are under the iso.org.dod.internet.directory.NameForm branch of the OID tree (1.3.6.1.1.2). ( 1.3.6.1.1.2.1 NAME domainNameForm OC domain MUST dc ) The domainNameForm name form indicates that objects of structural object class domain have their RDN constructed from a value of the attribute dc. 5.2.6.2 Name Form for Organization Objects ( 1.3.6.1.1.2.2 NAME dcOrganizationNameForm OC organization MUST dc ) The dcOrganizationNameForm name form indicates that objects of structural object class organization have their RDN constructed from a value of the attribute dc. 5.2.6.3 Name Form for Organizational Unit Objects ( 1.3.6.1.1.2.3 NAME dcOrganizationalUnitNameForm OC organizationalUnit MUST dc ) The dcOrganizationalUnitNameForm name form indicates that objects of structural object class organizationalUnit have their RDN constructed from a value of the attribute dc. 5.2.6.4 Name Form for Locality Objects ( 1.3.6.1.1.2.4 NAME dcLocalityNameForm OC locality MUST dc ) The dcLocalityNameForm name form indicates that objects of structural object class locality have their RDN constructed from a value of the attribute dc. Grimstad, et. al. Informational [Page 14] RFC 2377 A Directory Naming Plan September 1998 5.2.6.5 Name Form for Organizational Person Objects ( 1.3.6.1.1.2.5 NAME uidOrganizationalPersonNameForm OC organizationalPerson MUST uid ) The uidOrganizationalPersonNameForm name form indicates that objects of structural object class organizationalPerson have their RDN constructed from a value of the attribute uid. 6.0 Security Considerations Although access controls may be placed on portions of the DIT to deny browse access to unauthorized clients, it may be possible to infer directory names and DIT structure in such sensitive portions of the DIT from the results of DNS queries. Providing public visibility to some portions of the DIT may assist those make such inferences. 7.0 Acknowledgments This plan has emerged in the course of a number of fruitful discussions, especially with David Chadwick, John Dale, Joe Gajewski, Mark Jackson, Ryan Moats, Tom Spencer and Chris Tzu. 8.0 References [1] Kille, S., Wahl, M., Grimstad, A., Huber, R., and S. Sataluri, "Using Domains in LDAP Distinguished Names", RFC 2247, January 1998. [2] X.500: The Directory -- Overview of Concepts, Models, and Service, CCITT Recommendation X.500, December, 1988. [3] Barker, P., and S. Kille, "The COSINE and Internet X.500 Schema", RFC 1274, November 1991. [4] The North American Directory Forum, "A Naming Scheme for c=US", RFC 1255, September 1991. [5] The North American Directory Forum, "NADF Standing Documents: A Brief Overview", RFC 1417, February 1993. [6] Yeong, W., Howes, T., and S. Kille, "Lightweight Directory Access Protocol", RFC 1777, March 1995. [7] Wahl, M., Howes, T., and S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. Grimstad, et. al. Informational [Page 15] RFC 2377 A Directory Naming Plan September 1998 [8] Kille, S., "A String Representation of Distinguished Names", RFC 1779, March 1995. [9] Wahl, M., Kille, S., and T. Howes, "Lightweight Directory Access Protocol (v3): UTF-8 String Representation of Distinguished Names", RFC 2253, December 1997. [10] Wahl, M., "A Summary of the Pilot X.500 Schema for use in LDAPv3", Work in Progress. [11] Wahl, M., "A Summary of the X.500 User Schema for use with LDAPv3", RFC 2256, December 1997. [12] Howes, T., and M. Wahl, "Referrals and Knowledge References in LDAP Directories", Work in Progress. [13] Howes, T., and M. Smith, "The LDAP URL Format", RFC 2255, December 1997. [14] Wahl, M., Coulbeck, A., Howes, T., and S. Kille, "Lightweight Directory Access Protocol (v3): Attribute Syntax Definitions", RFC 2252, December 1997. [15] Smith, M., "Definition of the inetOrgPerson Object Class", Work in Progress. Grimstad, et. al. Informational [Page 16] RFC 2377 A Directory Naming Plan September 1998 12. Authors' Addresses Al Grimstad AT&T Room 1C-429, 101 Crawfords Corner Road Holmdel, NJ 07733-3030 USA EMail: alg@att.com Rick Huber AT&T Room 1B-433, 101 Crawfords Corner Road Holmdel, NJ 07733-3030 USA EMail: rvh@att.com Sri Sataluri Lucent Technologies Room 4D-335, 101 Crawfords Corner Road Holmdel, NJ 07733-3030 USA EMail: srs@lucent.com Mark Wahl Critical Angle Inc. 4815 W Braker Lane #502-385 Austin, TX 78759 USA EMail: M.Wahl@critical-angle.com Grimstad, et. al. Informational [Page 17] RFC 2377 A Directory Naming Plan September 1998 13. Full Copyright Statement Copyright (C) The Internet Society (1998). 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. Grimstad, et. al. Informational [Page 18] PK *�c\��AI) ) ( doc/alt-openldap11-devel/rfc/rfc3045.txtnu �[��� Network Working Group M. Meredith Request for Comments: 3045 Novell Inc. Category: Informational January 2001 Storing Vendor Information in the LDAP root DSE Status of this Memo This memo provides information for the Internet community. It does not specify an Internet standard of any kind. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2001). All Rights Reserved. Abstract This document specifies two Lightweight Directory Access Protocol (LDAP) attributes, vendorName and vendorVersion that MAY be included in the root DSA-specific Entry (DSE) to advertise vendor-specific information. These two attributes supplement the attributes defined in section 3.4 of RFC 2251. The information held in these attributes MAY be used for display and informational purposes and MUST NOT be used for feature advertisement or discovery. 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 [RFC2219] 1. Overview LDAP clients discover server-specific data--such as available controls, extensions, etc.--by reading the root DSE. See section 3.4 of [RFC2251] for details. For display, information, and limited function discovery, it is desirable to be able to query an LDAP server to determine the vendor name of that server and also to see what version of that vendor's code is currently installed. Meredith Informational [Page 1] RFC 3045 LDAP Root DSE to Display Vendor Information January 2001 1.1 Function discovery There are many ways in which a particular version of a vendor's LDAP server implementation may be functionally incomplete, or may contain software anomalies. It is impossible to identify every known shortcoming of an LDAP server with the given set of server data advertisement attributes. Furthermore, often times, the anomalies of an implementation are not found until after the implementation has been distributed, deployed, and is in use. The attributes defined in this document MAY be used by client implementations in order to identify a particular server implementation so that it can 'work around' such anomalies. The attributes defined in this document MUST NOT be used to gather information related to supported features of an LDAP implementation. All LDAP features, mechanisms, and capabilities--if advertised--MUST be advertised through other mechanisms, preferably advertisement mechanisms defined in concert with said features, mechanisms, and capabilities. 2. Attribute Types These attributes are an addition to the Server-specific Data Requirements defined in section 3.4 of [RFC2251]. The associated syntaxes are defined in section 4 of [RFC2252]. Servers MAY restrict access to vendorName or vendorVersion and clients MUST NOT expect these attributes to be available. 2.1 vendorName This attribute contains a single string, which represents the name of the LDAP server implementer. All LDAP server implementations SHOULD maintain a vendorName, which is generally the name of the company that wrote the LDAP Server code like "Novell, Inc." ( 1.3.6.1.1.4 NAME 'vendorName' EQUALITY 1.3.6.1.4.1.1466.109.114.1 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE NO-USER-MODIFICATION USAGE dSAOperation ) 2.2 vendorVersion This attribute contains a string which represents the version of the LDAP server implementation. Meredith Informational [Page 2] RFC 3045 LDAP Root DSE to Display Vendor Information January 2001 All LDAP server implementations SHOULD maintain a vendorVersion. Note that this value is typically a release value--comprised of a string and/or a string of numbers--used by the developer of the LDAP server product (as opposed to the supportedLDAPVersion, which specifies the version of the LDAP protocol supported by this server). This is single-valued so that it will only have one version value. This string MUST be unique between two versions, but there are no other syntactic restrictions on the value or the way it is formatted. ( 1.3.6.1.1.5 NAME 'vendorVersion' EQUALITY 1.3.6.1.4.1.1466.109.114.1 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE NO-USER-MODIFICATION USAGE dSAOperation ) The intent behind the equality match on vendorVersion is to not allow a less than or greater than type of query. Say release "LDAPv3 8.0" has a problem that is fixed in the next release "LDAPv3 8.5", but in the mean time there is also an update release say version "LDAPv3 8.01" that fixes the problem. This will hopefully stop the client from saying it will not work with a version less than "LDAPv3 8.5" when it would also work with "LDAPv3 8.01". With the equality match the client would have to exactly match what it is looking for. 3. Notes to Server Implementers Server implementers may consider tying the vendorVersion attribute value to the build mechanism so that it is automatically updated when the version value changes. 4. Notes to Client Developers As mentioned in section 2.1, the use of vendorName and vendorVersion MUST NOT be used to discover features. It should be noted that an anomalies often on affect subset of implementations reporting the same version information. Most implementations support multiple platforms, have numerous configuration options, and often support plug-ins. Client implementations SHOULD be written in such a way as to accept any value in the vendorName and vendorVersion attributes. If a client implementation does not recognize the specific vendorName or vendorVersion as one it recognizes, then for the purposes of 'working around' anomalies, the client MUST assume that the server is complete and correct. The client MUST work with implementations that do not publish these attributes. Meredith Informational [Page 3] RFC 3045 LDAP Root DSE to Display Vendor Information January 2001 5. Security Considerations The vendorName and vendorVersion attributes are provided only as display or informational mechanisms, or as anomaly identifying mechanisms. Client and application implementers must consider that the existence of a given value in the vendorName or vendorVersion attribute is no guarantee that the server was actually built by the asserted vendor or that its version is the asserted version and should act accordingly. Server implementers should be aware that this information could be used to exploit a security hole a server provides either by feature or flaw. 6. IANA Considerations This document seeks to create two attributes, vendorName and vendorVersion, which the IANA will primarily be responsible. This is a one time effort; there is no need for any recurring assignment after this stage. 7. References [RFC2219] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 3", BCP 9, RFC 2026, October 1996. [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. 8. Acknowledgments The author would like to thank the generous input and review by individuals at Novell including but not limited to Jim Sermersheim, Mark Hinckley, Renea Campbell, and Roger Harrison. Also IETF contributors Kurt Zeilenga, Mark Smith, Mark Wahl, Peter Strong, Thomas Salter, Gordon Good, Paul Leach, Helmut Volpers. Meredith Informational [Page 4] RFC 3045 LDAP Root DSE to Display Vendor Information January 2001 9. Author's Address Mark Meredith Novell Inc. 1800 S. Novell Place Provo, UT 84606 Phone: 801-861-2645 EMail: mark_meredith@novell.com Meredith Informational [Page 5] RFC 3045 LDAP Root DSE to Display Vendor Information January 2001 10. 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 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. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Meredith Informational [Page 6] PK +�c\��*�� �� ( doc/alt-openldap11-devel/rfc/rfc2307.txtnu �[��� Network Working Group L. Howard Request for Comments: 2307 Independent Consultant Category: Experimental March 1998 An Approach for Using LDAP as a Network Information Service Status of this Memo This memo defines an Experimental Protocol for the Internet community. It does not specify an Internet standard of any kind. Discussion and suggestions for improvement are requested. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (1998). All Rights Reserved. Abstract This document describes an experimental mechanism for mapping entities related to TCP/IP and the UNIX system into X.500 [X500] entries so that they may be resolved with the Lightweight Directory Access Protocol [RFC2251]. A set of attribute types and object classes are proposed, along with specific guidelines for interpreting them. The intention is to assist the deployment of LDAP as an organizational nameservice. No proposed solutions are intended as standards for the Internet. Rather, it is hoped that a general consensus will emerge as to the appropriate solution to such problems, leading eventually to the adoption of standards. The proposed mechanism has already been implemented with some success. 1. Background and Motivation The UNIX (R) operating system, and its derivatives (specifically, those which support TCP/IP and conform to the X/Open Single UNIX specification [XOPEN]) require a means of looking up entities, by matching them against search criteria or by enumeration. (Other operating systems that support TCP/IP may provide some means of resolving some of these entities. This schema is applicable to those environments also.) These entities include users, groups, IP services (which map names to IP ports and protocols, and vice versa), IP protocols (which map names to IP protocol numbers and vice versa), RPCs (which map names to ONC Remote Procedure Call [RFC1057] numbers and vice versa), NIS Howard Experimental [Page 1] RFC 2307 Using LDAP as a Network Information Service March 1998 netgroups, booting information (boot parameters and MAC address mappings), filesystem mounts, IP hosts and networks, and RFC822 mail aliases. Resolution requests are made through a set of C functions, provided in the UNIX system's C library. For example, the UNIX system utility "ls", which enumerates the contents of a filesystem directory, uses the C library function getpwuid() in order to map user IDs to login names. Once the request is made, it is resolved using a "nameservice" which is supported by the client library. The nameservice may be, at its simplest, a collection of files in the local filesystem which are opened and searched by the C library. Other common nameservices include the Network Information Service (NIS) and the Domain Name System (DNS). (The latter is typically used for resolving hosts, services and networks.) Both these nameservices have the advantage of being distributed and thus permitting a common set of entities to be shared amongst many clients. LDAP is a distributed, hierarchical directory service access protocol which is used to access repositories of users and other network- related entities. Because LDAP is often not tightly integrated with the host operating system, information such as users may need to be kept both in LDAP and in an operating system supported nameservice such as NIS. By using LDAP as the the primary means of resolving these entities, these redundancy issues are minimized and the scalability of LDAP can be exploited. (By comparison, NIS services based on flat files do not have the scalability or extensibility of LDAP or X.500.) The object classes and attributes defined below are suitable for representing the aforementioned entities in a form compatible with LDAP and X.500 directory services. 2. General Issues 2.1. Terminology The key words "MUST", "SHOULD", and "MAY" used in this document are to be interpreted as described in [RFC2119]. For the purposes of this document, the term "nameservice" refers to a service, such as NIS or flat files, that is used by the operating system to resolve entities within a single, local naming context. Contrast this with a "directory service" such as LDAP, which supports extensible schema and multiple naming contexts. Howard Experimental [Page 2] RFC 2307 Using LDAP as a Network Information Service March 1998 The term "NIS-related entities" broadly refers to entities which are typically resolved using the Network Information Service. (NIS was previously known as YP.) Deploying LDAP for resolving these entities does not imply that NIS be used, as a gateway or otherwise. In particular, the host and network classes are generically applicable, and may be implemented on any system that wishes to use LDAP or X.500 for host and network resolution. The "DUA" (directory user agent) refers to the LDAP client querying these entities, such as an LDAP to NIS gateway or the C library. The "client" refers to the application which ultimately makes use of the information returned by the resolution. It is irrelevant whether the DUA and the client reside within the same address space. The act of the DUA making this information to the client is termed "republishing". To avoid confusion, the term "login name" refers to the user's login name (being the value of the uid attribute) and the term "user ID" refers to he user's integer identification number (being the value of the uidNumber attribute). The phrases "resolving an entity" and "resolution of entities" refer respectively to enumerating NIS-related entities of a given type, and matching them against a given search criterion. One or more entities are returned as a result of successful "resolutions" (a "match" operation will only return one entity). The use of the term UNIX does not confer upon this schema the endorsement of owners of the UNIX trademark. Where necessary, the term "TCP/IP entity" is used to refer to protocols, services, hosts, and networks, and the term "UNIX entity" to its complement. (The former category does not mandate the host operating system supporting the interfaces required for resolving UNIX entities.) The OIDs defined below are derived from iso(1) org(3) dod(6) internet(1) directory(1) nisSchema(1). 2.2. Attributes The attributes and classes defined in this document are summarized below. The following attributes are defined in this document: uidNumber gidNumber gecos homeDirectory Howard Experimental [Page 3] RFC 2307 Using LDAP as a Network Information Service March 1998 loginShell shadowLastChange shadowMin shadowMax shadowWarning shadowInactive shadowExpire shadowFlag memberUid memberNisNetgroup nisNetgroupTriple ipServicePort ipServiceProtocol ipProtocolNumber oncRpcNumber ipHostNumber ipNetworkNumber ipNetmaskNumber macAddress bootParameter bootFile nisMapName nisMapEntry Additionally, some of the attributes defined in [RFC2256] are required. 2.3. Object classes The following object classes are defined in this document: posixAccount shadowAccount posixGroup ipService ipProtocol oncRpc ipHost ipNetwork nisNetgroup nisMap nisObject ieee802Device bootableDevice Additionally, some of the classes defined in [RFC2256] are required. Howard Experimental [Page 4] RFC 2307 Using LDAP as a Network Information Service March 1998 2.4. Syntax definitions The following syntax definitions [RFC2252] are used by this schema. The nisNetgroupTripleSyntax represents NIS netgroup triples: ( nisSchema.0.0 NAME 'nisNetgroupTripleSyntax' DESC 'NIS netgroup triple' ) Values in this syntax are represented by the following: nisnetgrouptriple = "(" hostname "," username "," domainname ")" hostname = "" / "-" / keystring username = "" / "-" / keystring domainname = "" / "-" / keystring X.500 servers may use the following representation of the above syntax: nisNetgroupTripleSyntax ::= SEQUENCE { hostname [0] IA5String OPTIONAL, username [1] IA5String OPTIONAL, domainname [2] IA5String OPTIONAL } The bootParameterSyntax syntax represents boot parameters: ( nisSchema.0.1 NAME 'bootParameterSyntax' DESC 'Boot parameter' ) where: bootparameter = key "=" server ":" path key = keystring server = keystring path = keystring X.500 servers may use the following representation of the above syntax: bootParameterSyntax ::= SEQUENCE { key IA5String, server IA5String, path IA5String } Values adhering to these syntaxes are encoded as strings by LDAP servers. Howard Experimental [Page 5] RFC 2307 Using LDAP as a Network Information Service March 1998 3. Attribute definitions This section contains attribute definitions to be implemented by DUAs supporting this schema. ( nisSchema.1.0 NAME 'uidNumber' DESC 'An integer uniquely identifying a user in an administrative domain' EQUALITY integerMatch SYNTAX 'INTEGER' SINGLE-VALUE ) ( nisSchema.1.1 NAME 'gidNumber' DESC 'An integer uniquely identifying a group in an administrative domain' EQUALITY integerMatch SYNTAX 'INTEGER' SINGLE-VALUE ) ( nisSchema.1.2 NAME 'gecos' DESC 'The GECOS field; the common name' EQUALITY caseIgnoreIA5Match SUBSTRINGS caseIgnoreIA5SubstringsMatch SYNTAX 'IA5String' SINGLE-VALUE ) ( nisSchema.1.3 NAME 'homeDirectory' DESC 'The absolute path to the home directory' EQUALITY caseExactIA5Match SYNTAX 'IA5String' SINGLE-VALUE ) ( nisSchema.1.4 NAME 'loginShell' DESC 'The path to the login shell' EQUALITY caseExactIA5Match SYNTAX 'IA5String' SINGLE-VALUE ) ( nisSchema.1.5 NAME 'shadowLastChange' EQUALITY integerMatch SYNTAX 'INTEGER' SINGLE-VALUE ) ( nisSchema.1.6 NAME 'shadowMin' EQUALITY integerMatch SYNTAX 'INTEGER' SINGLE-VALUE ) ( nisSchema.1.7 NAME 'shadowMax' EQUALITY integerMatch SYNTAX 'INTEGER' SINGLE-VALUE ) ( nisSchema.1.8 NAME 'shadowWarning' EQUALITY integerMatch SYNTAX 'INTEGER' SINGLE-VALUE ) ( nisSchema.1.9 NAME 'shadowInactive' Howard Experimental [Page 6] RFC 2307 Using LDAP as a Network Information Service March 1998 EQUALITY integerMatch SYNTAX 'INTEGER' SINGLE-VALUE ) ( nisSchema.1.10 NAME 'shadowExpire' EQUALITY integerMatch SYNTAX 'INTEGER' SINGLE-VALUE ) ( nisSchema.1.11 NAME 'shadowFlag' EQUALITY integerMatch SYNTAX 'INTEGER' SINGLE-VALUE ) ( nisSchema.1.12 NAME 'memberUid' EQUALITY caseExactIA5Match SUBSTRINGS caseExactIA5SubstringsMatch SYNTAX 'IA5String' ) ( nisSchema.1.13 NAME 'memberNisNetgroup' EQUALITY caseExactIA5Match SUBSTRINGS caseExactIA5SubstringsMatch SYNTAX 'IA5String' ) ( nisSchema.1.14 NAME 'nisNetgroupTriple' DESC 'Netgroup triple' SYNTAX 'nisNetgroupTripleSyntax' ) ( nisSchema.1.15 NAME 'ipServicePort' EQUALITY integerMatch SYNTAX 'INTEGER' SINGLE-VALUE ) ( nisSchema.1.16 NAME 'ipServiceProtocol' SUP name ) ( nisSchema.1.17 NAME 'ipProtocolNumber' EQUALITY integerMatch SYNTAX 'INTEGER' SINGLE-VALUE ) ( nisSchema.1.18 NAME 'oncRpcNumber' EQUALITY integerMatch SYNTAX 'INTEGER' SINGLE-VALUE ) ( nisSchema.1.19 NAME 'ipHostNumber' DESC 'IP address as a dotted decimal, eg. 192.168.1.1, omitting leading zeros' EQUALITY caseIgnoreIA5Match SYNTAX 'IA5String{128}' ) ( nisSchema.1.20 NAME 'ipNetworkNumber' DESC 'IP network as a dotted decimal, eg. 192.168, Howard Experimental [Page 7] RFC 2307 Using LDAP as a Network Information Service March 1998 omitting leading zeros' EQUALITY caseIgnoreIA5Match SYNTAX 'IA5String{128}' SINGLE-VALUE ) ( nisSchema.1.21 NAME 'ipNetmaskNumber' DESC 'IP netmask as a dotted decimal, eg. 255.255.255.0, omitting leading zeros' EQUALITY caseIgnoreIA5Match SYNTAX 'IA5String{128}' SINGLE-VALUE ) ( nisSchema.1.22 NAME 'macAddress' DESC 'MAC address in maximal, colon separated hex notation, eg. 00:00:92:90:ee:e2' EQUALITY caseIgnoreIA5Match SYNTAX 'IA5String{128}' ) ( nisSchema.1.23 NAME 'bootParameter' DESC 'rpc.bootparamd parameter' SYNTAX 'bootParameterSyntax' ) ( nisSchema.1.24 NAME 'bootFile' DESC 'Boot image name' EQUALITY caseExactIA5Match SYNTAX 'IA5String' ) ( nisSchema.1.26 NAME 'nisMapName' SUP name ) ( nisSchema.1.27 NAME 'nisMapEntry' EQUALITY caseExactIA5Match SUBSTRINGS caseExactIA5SubstringsMatch SYNTAX 'IA5String{1024}' SINGLE-VALUE ) 4. Class definitions This section contains class definitions to be implemented by DUAs supporting the schema. The rfc822MailGroup object class MAY be used to represent a mail group for the purpose of alias expansion. Several alternative schemes for mail routing and delivery using LDAP directories, which are outside the scope of this document. ( nisSchema.2.0 NAME 'posixAccount' SUP top AUXILIARY DESC 'Abstraction of an account with POSIX attributes' MUST ( cn $ uid $ uidNumber $ gidNumber $ homeDirectory ) MAY ( userPassword $ loginShell $ gecos $ description ) ) Howard Experimental [Page 8] RFC 2307 Using LDAP as a Network Information Service March 1998 ( nisSchema.2.1 NAME 'shadowAccount' SUP top AUXILIARY DESC 'Additional attributes for shadow passwords' MUST uid MAY ( userPassword $ shadowLastChange $ shadowMin shadowMax $ shadowWarning $ shadowInactive $ shadowExpire $ shadowFlag $ description ) ) ( nisSchema.2.2 NAME 'posixGroup' SUP top STRUCTURAL DESC 'Abstraction of a group of accounts' MUST ( cn $ gidNumber ) MAY ( userPassword $ memberUid $ description ) ) ( nisSchema.2.3 NAME 'ipService' SUP top STRUCTURAL DESC 'Abstraction an Internet Protocol service. Maps an IP port and protocol (such as tcp or udp) to one or more names; the distinguished value of the cn attribute denotes the service's canonical name' MUST ( cn $ ipServicePort $ ipServiceProtocol ) MAY ( description ) ) ( nisSchema.2.4 NAME 'ipProtocol' SUP top STRUCTURAL DESC 'Abstraction of an IP protocol. Maps a protocol number to one or more names. The distinguished value of the cn attribute denotes the protocol's canonical name' MUST ( cn $ ipProtocolNumber $ description ) MAY description ) ( nisSchema.2.5 NAME 'oncRpc' SUP top STRUCTURAL DESC 'Abstraction of an Open Network Computing (ONC) [RFC1057] Remote Procedure Call (RPC) binding. This class maps an ONC RPC number to a name. The distinguished value of the cn attribute denotes the RPC service's canonical name' MUST ( cn $ oncRpcNumber $ description ) MAY description ) ( nisSchema.2.6 NAME 'ipHost' SUP top AUXILIARY DESC 'Abstraction of a host, an IP device. The distinguished value of the cn attribute denotes the host's canonical name. Device SHOULD be used as a structural class' MUST ( cn $ ipHostNumber ) MAY ( l $ description $ manager ) ) ( nisSchema.2.7 NAME 'ipNetwork' SUP top STRUCTURAL DESC 'Abstraction of a network. The distinguished value of the cn attribute denotes the network's canonical name' Howard Experimental [Page 9] RFC 2307 Using LDAP as a Network Information Service March 1998 MUST ( cn $ ipNetworkNumber ) MAY ( ipNetmaskNumber $ l $ description $ manager ) ) ( nisSchema.2.8 NAME 'nisNetgroup' SUP top STRUCTURAL DESC 'Abstraction of a netgroup. May refer to other netgroups' MUST cn MAY ( nisNetgroupTriple $ memberNisNetgroup $ description ) ) ( nisSchema.2.09 NAME 'nisMap' SUP top STRUCTURAL DESC 'A generic abstraction of a NIS map' MUST nisMapName MAY description ) ( nisSchema.2.10 NAME 'nisObject' SUP top STRUCTURAL DESC 'An entry in a NIS map' MUST ( cn $ nisMapEntry $ nisMapName ) MAY description ) ( nisSchema.2.11 NAME 'ieee802Device' SUP top AUXILIARY DESC 'A device with a MAC address; device SHOULD be used as a structural class' MAY macAddress ) ( nisSchema.2.12 NAME 'bootableDevice' SUP top AUXILIARY DESC 'A device with boot parameters; device SHOULD be used as a structural class' MAY ( bootFile $ bootParameter ) ) 5. Implementation details 5.1. Suggested resolution methods The preferred means of directing a client application (one using the shared services of the C library) to use LDAP as its information source for the functions listed in 5.2 is to modify the source code to directly query LDAP. As the source to commercial C libraries and applications is rarely available to the end-user, one could emulate a supported nameservice (such as NIS). (This is also an appropriate opportunity to perform caching of entries across process address spaces.) In the case of NIS, reference implementations are widely available and the RPC interface is well known. The means by which the operating system is directed to use LDAP is implementation dependent. For example, some operating systems and C libraries support end-user extensible resolvers using dynamically loadable libraries and a nameservice "switch". The means in which the DUA locates LDAP servers is also implementation dependent. Howard Experimental [Page 10] RFC 2307 Using LDAP as a Network Information Service March 1998 5.2. Affected library functions The following functions are typically found in the C libraries of most UNIX and POSIX compliant systems. An LDAP search filter [RFC2254] which may be used to satisfy the function call is included alongside each function name. Parameters are denoted by %s and %d for string and integer arguments, respectively. Long lines are broken. getpwnam() (&(objectClass=posixAccount)(uid=%s)) getpwuid() (&(objectClass=posixAccount) (uidNumber=%d)) getpwent() (objectClass=posixAccount) getspnam() (&(objectClass=shadowAccount)(uid=%s)) getspent() (objectClass=shadowAccount) getgrnam() (&(objectClass=posixGroup)(cn=%s)) getgrgid() (&(objectClass=posixGroup) (gidNumber=%d)) getgrent() (objectClass=posixGroup) getservbyname() (&(objectClass=ipService) (cn=%s)(ipServiceProtocol=%s)) getservbyport() (&(objectClass=ipService) (ipServicePort=%d) (ipServiceProtocol=%s)) getservent() (objectClass=ipService) getrpcbyname() (&(objectClass=oncRpc)(cn=%s)) getrpcbynumber() (&(objectClass=oncRpc)(oncRpcNumber=%d)) getrpcent() (objectClass=oncRpc) getprotobyname() (&(objectClass=ipProtocol)(cn=%s)) getprotobynumber() (&(objectClass=ipProtocol) (ipProtocolNumber=%d)) getprotoent() (objectClass=ipProtocol) gethostbyname() (&(objectClass=ipHost)(cn=%s)) gethostbyaddr() (&(objectClass=ipHost)(ipHostNumber=%s)) gethostent() (objectClass=ipHost) getnetbyname() (&(objectClass=ipNetwork)(cn=%s)) getnetbyaddr() (&(objectClass=ipNetwork) (ipNetworkNumber=%s)) getnetent() (objectClass=ipNetwork) setnetgrent() (&(objectClass=nisNetgroup)(cn=%s)) Howard Experimental [Page 11] RFC 2307 Using LDAP as a Network Information Service March 1998 5.3. Interpreting user and group entries User and group resolution is initiated by the functions prefixed by getpw and getgr respectively. The uid attribute contains the user's login name. The cn attribute, in posixGroup entries, contains the group's name. The account object class provides a convenient structural class for posixAccount, and SHOULD be used where additional attributes are not required. It is suggested that uid and cn are used as the RDN attribute type for posixAccount and posixGroup entries, respectively. An account's GECOS field is preferably determined by a value of the gecos attribute. If no gecos attribute exists, the value of the cn attribute MUST be used. (The existence of the gecos attribute allows information embedded in the GECOS field, such as a user's telephone number, to be returned to the client without overloading the cn attribute. It also accommodates directories where the common name does not contain the user's full name.) An entry of class posixAccount, posixGroup, or shadowAccount without a userPassword attribute MUST NOT be used for authentication. The client should be returned a non-matchable password such as "x". userPassword values MUST be represented by following syntax: passwordvalue = schemeprefix encryptedpassword schemeprefix = "{" scheme "}" scheme = "crypt" / "md5" / "sha" / altscheme altscheme = "x-" keystring encryptedpassword = encrypted password The encrypted password contains of a plaintext key hashed using the algorithm scheme. userPassword values which do not adhere to this syntax MUST NOT be used for authentication. The DUA MUST iterate through the values of the attribute until a value matching the above syntax is found. Only if encryptedpassword is an empty string does the user have no password. DUAs are not required to consider encryption schemes which the client will not recognize; in most cases, it may be sufficient to consider only "crypt". Below is an example of a userPassword attribute: userPassword: {crypt}X5/DBrWPOQQaI Howard Experimental [Page 12] RFC 2307 Using LDAP as a Network Information Service March 1998 A future standard may specify LDAP v3 attribute descriptions to represent hashed userPasswords, as noted below. This schema MUST NOT be used with LDAP v2 DUAs and DSAs. attributetype = attributename sep attributeoption attributename = "userPassword" sep = ";" attributeoption = schemeclass "-" scheme schemeclass = "hash" / altschemeclass scheme = "crypt" / "md5" / "sha" / altscheme altschemeclass = "x-" keystring altscheme = keystring Below is an example of a userPassword attribute, represented with an LDAP v3 attribute description: userPassword;hash-crypt: X5/DBrWPOQQaI A DUA MAY utilise the attributes in the shadowAccount class to provide shadow password service (getspnam() and getspent()). In such cases, the DUA MUST NOT make use of the userPassword attribute for getpwnam() et al, and MUST return a non-matchable password (such as "x") to the client instead. 5.4. Interpreting hosts and networks The ipHostNumber and ipNetworkNumber attributes are defined in preference to dNSRecord (defined in [RFC1279]), in order to simplify the DUA's role in interpreting entries in the directory. A dNSRecord expresses a complete resource record, including time to live and class data, which is extraneous to this schema. Additionally, the ipHost and ipNetwork classes permit a host or network (respectively) and all its aliases to be represented by a single entry in the directory. This is not necessarily possible if a DNS resource record is mapped directly to an LDAP entry. Implementations that wish to use LDAP to master DNS zone information are not precluded from doing so, and may simply avoid the ipHost and ipNetwork classes. This document redefines, although not exclusively, the ipNetwork class defined in [RFC1279], in order to achieve consistent naming with ipHost. The ipNetworkNumber attribute is also used in the siteContact object class [ROSE]. Howard Experimental [Page 13] RFC 2307 Using LDAP as a Network Information Service March 1998 The trailing zeros in a network address MUST be omitted. CIDR-style network addresses (eg. 192.168.1/24) MAY be used. Hosts with IPv6 addresses MUST be written in their "preferred" form as defined in section 2.2.1 of [RFC1884], such that all components of the address are indicated and leading zeros are omitted. This provides a consistent means of resolving ipHosts by address. 5.5. Interpreting other entities In general, a one-to-one mapping between entities and LDAP entries is proposed, in that each entity has exactly one representation in the DIT. In some cases this is not feasible; for example, a service which is represented in more than one protocol domain. Consider the following entry: dn: cn=domain, dc=aja, dc=com cn: domain cn: nameserver objectClass: top objectClass: ipService ipServicePort: 53 ipServiceProtocol: tcp ipServiceProtocol: udp This entry MUST map to the following two (2) services entities: domain 53/tcp nameserver domain 53/udp nameserver While the above two entities may be represented as separate LDAP entities, with different distinguished names (such as cn=domain+ipServiceProtocol=tcp, ... and cn=domain+ipServiceProtocol=udp, ...) it is convenient to represent them as a single entry. (If a service is represented in multiple protocol domains with different ports, then multiple entries are required; multivalued RDNs may be used to distinguish them.) With the exception of userPassword values, which are parsed according to the syntax considered in section 5.2, any empty values (consisting of a zero length string) are returned by the DUA to the client. The DUA MUST reject any entries which do not conform to the schema (missing mandatory attributes). Non-conforming entries SHOULD be ignored while enumerating entries. The nisObject object class MAY be used as a generic means of representing NIS entities. Its use is not encouraged; where support for entities not described in this schema is desired, an appropriate Howard Experimental [Page 14] RFC 2307 Using LDAP as a Network Information Service March 1998 schema should be devised. Implementors are strongly advised to support end-user extensible mappings between NIS entities and object classes. (Where the nisObject class is used, the nisMapName attribute may be used as a RDN.) 5.6. Canonicalizing entries with multi-valued naming attributes For entities such as hosts, services, networks, protocols, and RPCs, where there may be one or more aliases, the respective entry's relative distinguished name SHOULD be used to determine the canonical name. Any other values for the same attribute are used as aliases. For example, the service described in section 5.5 has the canonical name "domain" and exactly one alias, "nameserver". The schema in this document generally only defines one attribute per class which is suitable for distinguishing an entity (excluding any attributes with integer syntax; it is assumed that entries will be distinguished on name). Usually, this is the common name (cn) attribute. This aids the DUA in determining the canonical name of an entity, as it can examine the value of the relative distinguished name. Aliases are thus any values of the distinguishing attribute (such as cn) which do not match the canonical name of the entity. In the event that a different attribute is used to distinguish the entry, as may be the case where these object classes are used as auxiliary classes, the entry's canonical name may not be present in the RDN. In this case, the DUA MUST choose one of the non- distinguished values to represent the entity's canonical name. As the directory server guarantees no ordering of attribute values, it may not be possible to distinguish an entry deterministically. This ambiguity SHOULD NOT be resolved by mapping one directory entry into multiple entities. 6. Implementation focus A NIS server which uses LDAP instead of local files has been developed which supports the schema defined in this document. A reference implementation of the C library resolution code has been written for the Free Software Foundation. It may support other C libraries which support the Name Service Switch (NSS) or the Information Retrieval Service (IRS). The author has made available a freely distributable set of scripts which parses local databases such as /etc/passwd and /etc/hosts into a form suitable for loading into an LDAP server. Howard Experimental [Page 15] RFC 2307 Using LDAP as a Network Information Service March 1998 7. Security Considerations The entirety of related security considerations are outside the scope of this document. It is noted that making passwords encrypted with a widely understood hash function (such as crypt()) available to non- privileged users is dangerous because it exposes them to dictionary and brute-force attacks. This is proposed only for compatibility with existing UNIX system implementations. Sites where security is critical SHOULD consider using a strong authentication service for user authentication. Alternatively, the encrypted password could be made available only to a subset of privileged DUAs, which would provide "shadow" password service to client applications. This may be difficult to enforce. Because the schema represents operating system-level entities, access to these entities SHOULD be granted on a discretionary basis. (There is little point in restricting access to data which will be republished without restriction, however.) It is particularly important that only administrators can modify entries defined in this schema, with the exception of allowing a principal to change their password (which may be done on behalf of the user by a client bound as a superior principal, such that password restrictions may be enforced). For example, if a user were allowed to change the value of their uidNumber attribute, they could subvert security by equivalencing their account with the superuser account. A subtree of the DIT which is to be republished by a DUA (such as a NIS gateway) SHOULD be within the same administrative domain that the republishing DUA represents. (For example, principals outside an organization, while conceivably part of the DIT, should not be considered with the same degree of authority as those within the organization.) Finally, care should be exercised with integer attributes of a sensitive nature (particularly the uidNumber and gidNumber attributes) which contain zero-length values. DUAs MAY treat such values as corresponding to the "nobody" or "nogroup" user and group, respectively. 8. Acknowledgements Thanks to Leif Hedstrom of Netscape Communications Corporation, Michael Grant and Rosanna Lee of Sun Microsystems Inc., Ed Reed of Novell Inc., and Mark Wahl of Critical Angle Inc. for their valuable contributions to the development of this schema. Thanks to Andrew Josey of The Open Group for clarifying the use of the UNIX trademark, and to Tim Howes and Peter J. Cherny for their support. Howard Experimental [Page 16] RFC 2307 Using LDAP as a Network Information Service March 1998 UNIX is a registered trademark of The Open Group. 9. References [RFC1057] Sun Microsystems, Inc., "RPC: Remote Procedure Call: Protocol Specification Version 2", RFC 1057, June 1988. [RFC1279] Kille, S., "X.500 and Domains", RFC 1279, November 1991. [RFC1884] Hinden, R., and S. Deering, "IP Version 6 Addressing Architecture", RFC 1884, December 1995. [RFC2119] Bradner, S., "Key Words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 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. [RFC2254] Howes, T., "The String Representation of LDAP Search Filters", RFC 2254, December 1997. [RFC2256] Wahl, M., "A Summary of the X.500(96) User Schema for use with LDAPv3", RFC 2256, December 1997. [ROSE] M. T. Rose, "The Little Black Book: Mail Bonding with OSI Directory Services", ISBN 0-13-683210-5, Prentice-Hall, Inc., 1992. [X500] "Information Processing Systems - Open Systems Interconnection - The Directory: Overview of Concepts, Models and Service", ISO/IEC JTC 1/SC21, International Standard 9594-1, 1988. Howard Experimental [Page 17] RFC 2307 Using LDAP as a Network Information Service March 1998 [XOPEN] ISO/IEC 9945-1:1990, Information Technology - Portable Operating Systems Interface (POSIX) - Part 1: Systems Application Programming Interface (API) [C Language] 10. Author's Address Luke Howard PO Box 59 Central Park Vic 3145 Australia EMail: lukeh@xedoc.com Howard Experimental [Page 18] RFC 2307 Using LDAP as a Network Information Service March 1998 A. Example entries The examples described in this section are provided to illustrate the schema described in this memo. They are not meant to be exhaustive. The following entry is an example of the posixAccount class: dn: uid=lester, dc=aja, dc=com objectClass: top objectClass: account objectClass: posixAccount uid: lester cn: Lester the Nightfly userPassword: {crypt}X5/DBrWPOQQaI gecos: Lester loginShell: /bin/csh uidNumber: 10 gidNumber: 10 homeDirectory: /home/lester This corresponds the UNIX system password file entry: lester:X5/DBrWPOQQaI:10:10:Lester:/home/lester:/bin/sh The following entry is an example of the ipHost class: dn: cn=peg.aja.com, dc=aja, dc=com objectClass: top objectClass: device objectClass: ipHost objectClass: bootableDevice objectClass: ieee802Device cn: peg.aja.com cn: www.aja.com ipHostNumber: 10.0.0.1 macAddress: 00:00:92:90:ee:e2 bootFile: mach bootParameter: root=fs:/nfsroot/peg bootParameter: swap=fs:/nfsswap/peg bootParameter: dump=fs:/nfsdump/peg This entry represents the host canonically peg.aja.com, also known as www.aja.com. The Ethernet address and four boot parameters are also specified. Howard Experimental [Page 19] RFC 2307 Using LDAP as a Network Information Service March 1998 An example of the nisNetgroup class: dn: cn=nightfly, dc=aja, dc=com objectClass: top objectClass: nisNetgroup cn: nightfly nisNetgroupTriple: (charlemagne,peg,dunes.aja.com) nisNetgroupTriple: (lester,-,) memberNisNetgroup: kamakiriad This entry represents the netgroup nightfly, which contains two triples (the user charlemagne, the host peg, and the domain dunes.aja.com; and, the user lester, no host, and any domain) and one netgroup (kamakiriad). Finally, an example of the nisObject class: dn: nisMapName=tracks, dc=dunes, dc=aja, dc=com objectClass: top objectClass: nisMap nisMapName: tracks dn: cn=Maxine, nisMapName=tracks, dc=dunes, dc=aja, dc=com objectClass: top objectClass: nisObject cn: Maxine nisMapName: tracks nisMapEntry: Nightfly$4 This entry represents the NIS map tracks, and a single map entry. Howard Experimental [Page 20] RFC 2307 Using LDAP as a Network Information Service March 1998 Full Copyright Statement Copyright (C) The Internet Society (1998). 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. Howard Experimental [Page 21] PK +�c\ѓ�j�� �� ( doc/alt-openldap11-devel/rfc/rfc4520.txtnu �[��� Network Working Group K. Zeilenga Request for Comments: 4520 OpenLDAP Foundation BCP: 64 June 2006 Obsoletes: 3383 Category: Best Current Practice Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP) Status of This Memo This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2006). Abstract This document provides procedures for registering extensible elements of the Lightweight Directory Access Protocol (LDAP). The document also provides guidelines to the Internet Assigned Numbers Authority (IANA) describing conditions under which new values can be assigned. 1. Introduction The Lightweight Directory Access Protocol [RFC4510] (LDAP) is an extensible protocol. LDAP supports: - the addition of new operations, - the extension of existing operations, and - the extensible schema. This document details procedures for registering values used to unambiguously identify extensible elements of the protocol, including the following: - LDAP message types - LDAP extended operations and controls - LDAP result codes - LDAP authentication methods - LDAP attribute description options - Object Identifier descriptors Zeilenga Best Current Practice [Page 1] RFC 4520 IANA Considerations for LDAP June 2006 These registries are maintained by the Internet Assigned Numbers Authority (IANA). In addition, this document provides guidelines to IANA describing the conditions under which new values can be assigned. This document replaces RFC 3383. 2. Terminology and Conventions This section details terms and conventions used in this document. 2.1. Policy Terminology The terms "IESG Approval", "Standards Action", "IETF Consensus", "Specification Required", "First Come First Served", "Expert Review", and "Private Use" are used as defined in BCP 26 [RFC2434]. The term "registration owner" (or "owner") refers to the party authorized to change a value's registration. 2.2. Requirement 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 [RFC2119]. In this case, "the specification", as used by BCP 14, refers to the processing of protocols being submitted to the IETF standards process. 2.3. Common ABNF Productions A number of syntaxes in this document are described using ABNF [RFC4234]. These syntaxes rely on the following common productions: ALPHA = %x41-5A / %x61-7A ; "A"-"Z" / "a"-"z" LDIGIT = %x31-39 ; "1"-"9" DIGIT = %x30 / LDIGIT ; "0"-"9" HYPHEN = %x2D ; "-" DOT = %x2E ; "." number = DIGIT / ( LDIGIT 1*DIGIT ) keychar = ALPHA / DIGIT / HYPHEN leadkeychar = ALPHA keystring = leadkeychar *keychar keyword = keystring Keywords are case insensitive. Zeilenga Best Current Practice [Page 2] RFC 4520 IANA Considerations for LDAP June 2006 3. IANA Considerations for LDAP This section details each kind of protocol value that can be registered and provides IANA guidelines on how to assign new values. IANA may reject obviously bogus registrations. LDAP values specified in RFCs MUST be registered. Other LDAP values, except those in private-use name spaces, SHOULD be registered. RFCs SHOULD NOT reference, use, or otherwise recognize unregistered LDAP values. 3.1. Object Identifiers Numerous LDAP schema and protocol elements are identified by Object Identifiers (OIDs) [X.680]. Specifications that assign OIDs to elements SHOULD state who delegated the OIDs for their use. For IETF-developed elements, specifications SHOULD use OIDs under "Internet Directory Numbers" (1.3.6.1.1.x). For elements developed by others, any properly delegated OID can be used, including those under "Internet Directory Numbers" (1.3.6.1.1.x) or "Internet Private Enterprise Numbers" (1.3.6.1.4.1.x). Internet Directory Numbers (1.3.6.1.1.x) will be assigned upon Expert Review with Specification Required. Only one OID per specification will be assigned. The specification MAY then assign any number of OIDs within this arc without further coordination with IANA. Internet Private Enterprise Numbers (1.3.6.1.4.1.x) are assigned by IANA <http://www.iana.org/cgi-bin/enterprise.pl>. Practices for IANA assignment of Internet Private Enterprise Numbers are detailed in RFC 2578 [RFC2578]. To avoid interoperability problems between early implementations of a "work in progress" and implementations of the published specification (e.g., the RFC), experimental OIDs SHOULD be used in "works in progress" and early implementations. OIDs under the Internet Experimental OID arc (1.3.6.1.3.x) may be used for this purpose. Practices for IANA assignment of these Internet Experimental numbers are detailed in RFC 2578 [RFC2578]. 3.2. Protocol Mechanisms LDAP provides a number of Root DSA-Specific Entry (DSE) attributes for discovery of protocol mechanisms identified by OIDs, including the supportedControl, supportedExtension, and supportedFeatures attributes [RFC4512]. Zeilenga Best Current Practice [Page 3] RFC 4520 IANA Considerations for LDAP June 2006 A registry of OIDs used for discovery of protocol mechanisms is provided to allow implementors and others to locate the technical specification for these protocol mechanisms. Future specifications of additional Root DSE attributes holding values identifying protocol mechanisms MAY extend this registry for their values. Protocol mechanisms are registered on a First Come First Served basis. 3.3. LDAP Syntaxes This registry provides a listing of LDAP syntaxes [RFC4512]. Each LDAP syntax is identified by an OID. This registry is provided to allow implementors and others to locate the technical specification describing a particular LDAP Syntax. LDAP Syntaxes are registered on a First Come First Served with Specification Required basis. Note: Unlike object classes, attribute types, and various other kinds of schema elements, descriptors are not used in LDAP to identify LDAP Syntaxes. 3.4. Object Identifier Descriptors LDAP allows short descriptive names (or descriptors) to be used instead of a numeric Object Identifier to identify select protocol extensions [RFC4511], schema elements [RFC4512], LDAP URL [RFC4516] extensions, and other objects. Although the protocol allows the same descriptor to refer to different object identifiers in certain cases and the registry supports multiple registrations of the same descriptor (each indicating a different kind of schema element and different object identifier), multiple registrations of the same descriptor are to be avoided. All such multiple registration requests require Expert Review. Descriptors are restricted to strings of UTF-8 [RFC3629] encoded Unicode characters restricted by the following ABNF: name = keystring Descriptors are case insensitive. Multiple names may be assigned to a given OID. For purposes of registration, an OID is to be represented in numeric OID form (e.g., 1.1.0.23.40) conforming to the following ABNF: Zeilenga Best Current Practice [Page 4] RFC 4520 IANA Considerations for LDAP June 2006 numericoid = number 1*( DOT number ) While the protocol places no maximum length restriction upon descriptors, they should be short. Descriptors longer than 48 characters may be viewed as too long to register. A value ending with a hyphen ("-") reserves all descriptors that start with that value. For example, the registration of the option "descrFamily-" reserves all options that start with "descrFamily-" for some related purpose. Descriptors beginning with "x-" are for Private Use and cannot be registered. Descriptors beginning with "e-" are reserved for experiments and will be registered on a First Come First Served basis. All other descriptors require Expert Review to be registered. The registrant need not "own" the OID being named. The OID name space is managed by the ISO/IEC Joint Technical Committee 1 - Subcommittee 6. 3.5. AttributeDescription Options An AttributeDescription [RFC4512] can contain zero or more options specifying additional semantics. An option SHALL be restricted to a string of UTF-8 encoded Unicode characters limited by the following ABNF: option = keystring Options are case insensitive. While the protocol places no maximum length restriction upon option strings, they should be short. Options longer than 24 characters may be viewed as too long to register. Values ending with a hyphen ("-") reserve all option names that start with the name. For example, the registration of the option "optionFamily-" reserves all options that start with "optionFamily-" for some related purpose. Options beginning with "x-" are for Private Use and cannot be registered. Zeilenga Best Current Practice [Page 5] RFC 4520 IANA Considerations for LDAP June 2006 Options beginning with "e-" are reserved for experiments and will be registered on a First Come First Served basis. All other options require Standards Action or Expert Review with Specification Required to be registered. 3.6. LDAP Message Types Each protocol message is encapsulated in an LDAPMessage envelope [RFC4511. The protocolOp CHOICE indicates the type of message encapsulated. Each message type consists of an ASN.1 identifier in the form of a keyword and a non-negative choice number. The choice number is combined with the class (APPLICATION) and data type (CONSTRUCTED or PRIMITIVE) to construct the BER tag in the message's encoding. The choice numbers for existing protocol messages are implicit in the protocol's ASN.1 defined in [RFC4511]. New values will be registered upon Standards Action. Note: LDAP provides extensible messages that reduce but do not eliminate the need to add new message types. 3.7. LDAP Authentication Method The LDAP Bind operation supports multiple authentication methods [RFC4511]. Each authentication choice consists of an ASN.1 identifier in the form of a keyword and a non-negative integer. The registrant SHALL classify the authentication method usage using one of the following terms: COMMON - method is appropriate for common use on the Internet. LIMITED USE - method is appropriate for limited use. OBSOLETE - method has been deprecated or otherwise found to be inappropriate for any use. Methods without publicly available specifications SHALL NOT be classified as COMMON. New registrations of the class OBSOLETE cannot be registered. New authentication method integers in the range 0-1023 require Standards Action to be registered. New authentication method integers in the range 1024-4095 require Expert Review with Specification Required. New authentication method integers in the range 4096-16383 will be registered on a First Come First Served basis. Keywords associated with integers in the range 0-4095 SHALL NOT start with "e-" or "x-". Keywords associated with integers in Zeilenga Best Current Practice [Page 6] RFC 4520 IANA Considerations for LDAP June 2006 the range 4096-16383 SHALL start with "e-". Values greater than or equal to 16384 and keywords starting with "x-" are for Private Use and cannot be registered. Note: LDAP supports Simple Authentication and Security Layers [RFC4422] as an authentication choice. SASL is an extensible authentication framework. 3.8. LDAP Result Codes LDAP result messages carry a resultCode enumerated value to indicate the outcome of the operation [RFC4511]. Each result code consists of an ASN.1 identifier in the form of a keyword and a non-negative integer. New resultCodes integers in the range 0-1023 require Standards Action to be registered. New resultCode integers in the range 1024-4095 require Expert Review with Specification Required. New resultCode integers in the range 4096-16383 will be registered on a First Come First Served basis. Keywords associated with integers in the range 0-4095 SHALL NOT start with "e-" or "x-". Keywords associated with integers in the range 4096-16383 SHALL start with "e-". Values greater than or equal to 16384 and keywords starting with "x-" are for Private Use and cannot be registered. 3.9. LDAP Search Scope LDAP SearchRequest messages carry a scope-enumerated value to indicate the extent of search within the DIT [RFC4511]. Each search value consists of an ASN.1 identifier in the form of a keyword and a non-negative integer. New scope integers in the range 0-1023 require Standards Action to be registered. New scope integers in the range 1024-4095 require Expert Review with Specification Required. New scope integers in the range 4096-16383 will be registered on a First Come First Served basis. Keywords associated with integers in the range 0-4095 SHALL NOT start with "e-" or "x-". Keywords associated with integers in the range 4096-16383 SHALL start with "e-". Values greater than or equal to 16384 and keywords starting with "x-" are for Private Use and cannot be registered. 3.10. LDAP Filter Choice LDAP filters are used in making assertions against an object represented in the directory [RFC4511]. The Filter CHOICE indicates a type of assertion. Each Filter CHOICE consists of an ASN.1 identifier in the form of a keyword and a non-negative choice number. Zeilenga Best Current Practice [Page 7] RFC 4520 IANA Considerations for LDAP June 2006 The choice number is combined with the class (APPLICATION) and data type (CONSTRUCTED or PRIMITIVE) to construct the BER tag in the message's encoding. Note: LDAP provides the extensibleMatching choice, which reduces but does not eliminate the need to add new filter choices. 3.11. LDAP ModifyRequest Operation Type The LDAP ModifyRequest carries a sequence of modification operations [RFC4511]. Each kind (e.g., add, delete, replace) of operation consists of an ASN.1 identifier in the form of a keyword and a non- negative integer. New operation type integers in the range 0-1023 require Standards Action to be registered. New operation type integers in the range 1024-4095 require Expert Review with Specification Required. New operation type integers in the range 4096-16383 will be registered on a First Come First Served basis. Keywords associated with integers in the range 0-4095 SHALL NOT start with "e-" or "x-". Keywords associated with integers in the range 4096-16383 SHALL start with "e-". Values greater than or equal to 16384 and keywords starting with "x-" are for Private Use and cannot be registered. 3.12. LDAP authzId Prefixes Authorization Identities in LDAP are strings conforming to the <authzId> production [RFC4513]. This production is extensible. Each new specific authorization form is identified by a prefix string conforming to the following ABNF: prefix = keystring COLON COLON = %x3A ; COLON (":" U+003A) Prefixes are case insensitive. While the protocol places no maximum length restriction upon prefix strings, they should be short. Prefixes longer than 12 characters may be viewed as too long to register. Prefixes beginning with "x-" are for Private Use and cannot be registered. Prefixes beginning with "e-" are reserved for experiments and will be registered on a First Come First Served basis. All other prefixes require Standards Action or Expert Review with Specification Required to be registered. Zeilenga Best Current Practice [Page 8] RFC 4520 IANA Considerations for LDAP June 2006 3.13. Directory Systems Names The IANA-maintained "Directory Systems Names" registry [IANADSN] of valid keywords for well-known attributes was used in the LDAPv2 string representation of a distinguished name [RFC1779]. LDAPv2 is now Historic [RFC3494]. Directory systems names are not known to be used in any other context. LDAPv3 [RFC4514] uses Object Identifier Descriptors [Section 3.2] (which have a different syntax than directory system names). New Directory System Names will no longer be accepted. For historical purposes, the current list of registered names should remain publicly available. 4. Registration Procedure The procedure given here MUST be used by anyone who wishes to use a new value of a type described in Section 3 of this document. The first step is for the requester to fill out the appropriate form. Templates are provided in Appendix A. If the policy is Standards Action, the completed form SHOULD be provided to the IESG with the request for Standards Action. Upon approval of the Standards Action, the IESG SHALL forward the request (possibly revised) to IANA. The IESG SHALL be regarded as the registration owner of all values requiring Standards Action. If the policy is Expert Review, the requester SHALL post the completed form to the <directory@apps.ietf.org> mailing list for public review. The review period is two (2) weeks. If a revised form is later submitted, the review period is restarted. Anyone may subscribe to this list by sending a request to <directory- request@apps.ietf.org>. During the review, objections may be raised by anyone (including the Expert) on the list. After completion of the review, the Expert, based on public comments, SHALL either approve the request and forward it to the IANA OR deny the request. In either case, the Expert SHALL promptly notify the requester of the action. Actions of the Expert may be appealed [RFC2026]. The Expert is appointed by Applications Area Directors. The requester is viewed as the registration owner of values registered under Expert Review. If the policy is First Come First Served, the requester SHALL submit the completed form directly to the IANA: <iana@iana.org>. The requester is viewed as the registration owner of values registered under First Come First Served. Zeilenga Best Current Practice [Page 9] RFC 4520 IANA Considerations for LDAP June 2006 Neither the Expert nor IANA will take position on the claims of copyright or trademark issues regarding completed forms. Prior to submission of the Internet Draft (I-D) to the RFC Editor but after IESG review and tentative approval, the document editor SHOULD revise the I-D to use registered values. 5. Registration Maintenance This section discusses maintenance of registrations. 5.1. Lists of Registered Values IANA makes lists of registered values readily available to the Internet community on its web site: <http://www.iana.org/>. 5.2. Change Control The registration owner MAY update the registration subject to the same constraints and review as with new registrations. In cases where the registration owner is unable or is unwilling to make necessary updates, the IESG MAY assume ownership of the registration in order to update the registration. 5.3. Comments For cases where others (anyone other than the registration owner) have significant objections to the claims in a registration and the registration owner does not agree to change the registration, comments MAY be attached to a registration upon Expert Review. For registrations owned by the IESG, the objections SHOULD be addressed by initiating a request for Expert Review. The form of these requests is ad hoc, but MUST include the specific objections to be reviewed and SHOULD contain (directly or by reference) materials supporting the objections. 6. Security Considerations The security considerations detailed in BCP 26 [RFC2434] are generally applicable to this document. Additional security considerations specific to each name space are discussed in Section 3, where appropriate. Security considerations for LDAP are discussed in documents comprising the technical specification [RFC4510]. Zeilenga Best Current Practice [Page 10] RFC 4520 IANA Considerations for LDAP June 2006 7. Acknowledgement This document is a product of the IETF LDAP Revision (LDAPBIS) Working Group (WG). This document is a revision of RFC 3383, also a product of the LDAPBIS WG. This document includes text borrowed from "Guidelines for Writing an IANA Considerations Section in RFCs" [RFC2434] by Thomas Narten and Harald Alvestrand. 8. References 8.1. Normative References [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 3", BCP 9, RFC 2026, October 1996. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 2434, October 1998. [RFC2578] McCloghrie, K., Perkins, D., and J. Schoenwaelder, "Structure of Management Information Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003. [RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 4234, October 2005. [RFC4510] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006. [RFC4511] Sermersheim, J., Ed., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006. [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006. [RFC4513] Harrison, R., Ed., "Lightweight Directory Access Protocol (LDAP): Authentication Methods and Security Mechanisms", RFC 4513, June 2006. Zeilenga Best Current Practice [Page 11] RFC 4520 IANA Considerations for LDAP June 2006 [RFC4516] Smith, M., Ed. and T. Howes, "Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator", RFC 4516, June 2006. [Unicode] The Unicode Consortium, "The Unicode Standard, Version 3.2.0" is defined by "The Unicode Standard, Version 3.0" (Reading, MA, Addison-Wesley, 2000. ISBN 0-201-61633-5), as amended by the "Unicode Standard Annex #27: Unicode 3.1" (http://www.unicode.org/reports/tr27/) and by the "Unicode Standard Annex #28: Unicode 3.2" (http://www.unicode.org/reports/tr28/). [X.680] International Telecommunication Union - Telecommunication Standardization Sector, "Abstract Syntax Notation One (ASN.1) - Specification of Basic Notation", X.680(2002) (also ISO/IEC 8824-1:2002). 8.2. Informative References [RFC1779] Kille, S., "A String Representation of Distinguished Names", RFC 1779, March 1995. [RFC3494] Zeilenga, K.,"Lightweight Directory Access Protocol version 2 (LDAPv2) to Historic Status", RFC 3494, March 2003. [RFC4514] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names", RFC 4514, June 2006. [RFC4422] Melnikov, A., Ed. and K. Zeilenga, Ed., "Simple Authentication and Security Layer (SASL)", RFC 4422, June 2006. [IANADSN] IANA, "Directory Systems Names", http://www.iana.org/assignments/directory-system-names. Zeilenga Best Current Practice [Page 12] RFC 4520 IANA Considerations for LDAP June 2006 Appendix A. Registration Templates This appendix provides registration templates for registering new LDAP values. Note that more than one value may be requested by extending the template by listing multiple values, or through use of tables. A.1. LDAP Object Identifier Registration Template Subject: Request for LDAP OID Registration Person & email address to contact for further information: Specification: (I-D) Author/Change Controller: Comments: (Any comments that the requester deems relevant to the request.) A.2. LDAP Protocol Mechanism Registration Template Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: Description: Person & email address to contact for further information: Usage: (One of Control or Extension or Feature or other) Specification: (RFC, I-D, URI) Author/Change Controller: Comments: (Any comments that the requester deems relevant to the request.) Zeilenga Best Current Practice [Page 13] RFC 4520 IANA Considerations for LDAP June 2006 A.3. LDAP Syntax Registration Template Subject: Request for LDAP Syntax Registration Object Identifier: Description: Person & email address to contact for further information: Specification: (RFC, I-D, URI) Author/Change Controller: Comments: (Any comments that the requester deems relevant to the request.) A.4. LDAP Descriptor Registration Template Subject: Request for LDAP Descriptor Registration Descriptor (short name): Object Identifier: Person & email address to contact for further information: Usage: (One of administrative role, attribute type, matching rule, name form, object class, URL extension, or other) Specification: (RFC, I-D, URI) Author/Change Controller: Comments: (Any comments that the requester deems relevant to the request.) Zeilenga Best Current Practice [Page 14] RFC 4520 IANA Considerations for LDAP June 2006 A.5. LDAP Attribute Description Option Registration Template Subject: Request for LDAP Attribute Description Option Registration Option Name: Family of Options: (YES or NO) Person & email address to contact for further information: Specification: (RFC, I-D, URI) Author/Change Controller: Comments: (Any comments that the requester deems relevant to the request.) A.6. LDAP Message Type Registration Template Subject: Request for LDAP Message Type Registration LDAP Message Name: Person & email address to contact for further information: Specification: (Approved I-D) Comments: (Any comments that the requester deems relevant to the request.) A.7. LDAP Authentication Method Registration Template Subject: Request for LDAP Authentication Method Registration Authentication Method Name: Person & email address to contact for further information: Specification: (RFC, I-D, URI) Intended Usage: (One of COMMON, LIMITED-USE, OBSOLETE) Author/Change Controller: Comments: (Any comments that the requester deems relevant to the request.) Zeilenga Best Current Practice [Page 15] RFC 4520 IANA Considerations for LDAP June 2006 A.8. LDAP Result Code Registration Template Subject: Request for LDAP Result Code Registration Result Code Name: Person & email address to contact for further information: Specification: (RFC, I-D, URI) Author/Change Controller: Comments: (Any comments that the requester deems relevant to the request.) A.8. LDAP Search Scope Registration Template Subject: Request for LDAP Search Scope Registration Search Scope Name: Filter Scope String: Person & email address to contact for further information: Specification: (RFC, I-D, URI) Author/Change Controller: Comments: (Any comments that the requester deems relevant to the request.) Zeilenga Best Current Practice [Page 16] RFC 4520 IANA Considerations for LDAP June 2006 A.9. LDAP Filter Choice Registration Template Subject: Request for LDAP Filter Choice Registration Filter Choice Name: Person & email address to contact for further information: Specification: (RFC, I-D, URI) Author/Change Controller: Comments: (Any comments that the requester deems relevant to the request.) A.10. LDAP ModifyRequest Operation Registration Template Subject: Request for LDAP ModifyRequest Operation Registration ModifyRequest Operation Name: Person & email address to contact for further information: Specification: (RFC, I-D, URI) Author/Change Controller: Comments: (Any comments that the requester deems relevant to the request.) Appendix B. Changes since RFC 3383 This informative appendix provides a summary of changes made since RFC 3383. - Object Identifier Descriptors practices were updated to require all descriptors defined in RFCs to be registered and recommending all other descriptors (excepting those in private-use name space) be registered. Additionally, all requests for multiple registrations of the same descriptor are now subject to Expert Review. - Protocol Mechanisms practices were updated to include values of the 'supportedFeatures' attribute type. Zeilenga Best Current Practice [Page 17] RFC 4520 IANA Considerations for LDAP June 2006 - LDAP Syntax, Search Scope, Filter Choice, ModifyRequest operation, and authzId prefixes registries were added. - References to RFCs comprising the LDAP technical specifications have been updated to latest revisions. - References to ISO 10646 have been replaced with [Unicode]. - The "Assigned Values" appendix providing initial registry values was removed. - Numerous editorial changes were made. Author's Address Kurt D. Zeilenga OpenLDAP Foundation EMail: Kurt@OpenLDAP.org Zeilenga Best Current Practice [Page 18] RFC 4520 IANA Considerations for LDAP June 2006 Full Copyright Statement Copyright (C) The Internet Society (2006). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Zeilenga Best Current Practice [Page 19] PK +�c\ ��� � ( doc/alt-openldap11-devel/rfc/rfc4533.txtnu �[��� Network Working Group K. Zeilenga Request for Comments: 4533 OpenLDAP Foundation Category: Experimental J.H. Choi IBM Corporation June 2006 The Lightweight Directory Access Protocol (LDAP) Content Synchronization Operation Status of This Memo This memo defines an Experimental Protocol for the Internet community. It does not specify an Internet standard of any kind. Discussion and suggestions for improvement are requested. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2006). IESG Note The IESG notes that this work was originally discussed in the LDUP working group. The group came to consensus on a different approach, documented in RFC 3928; that document is on the standards track and should be reviewed by those considering implementation of this proposal. Abstract This specification describes the Lightweight Directory Access Protocol (LDAP) Content Synchronization Operation. The operation allows a client to maintain a copy of a fragment of the Directory Information Tree (DIT). It supports both polling for changes and listening for changes. The operation is defined as an extension of the LDAP Search Operation. Zeilenga & Choi Experimental [Page 1] RFC 4533 LDAP Content Synchronization Operation June 2006 Table of Contents 1. Introduction ....................................................3 1.1. Background .................................................3 1.2. Intended Usage .............................................4 1.3. Overview ...................................................5 1.4. Conventions ................................................8 2. Elements of the Sync Operation ..................................8 2.1. Common ASN.1 Elements ......................................9 2.2. Sync Request Control .......................................9 2.3. Sync State Control ........................................10 2.4. Sync Done Control .........................................10 2.5. Sync Info Message .........................................11 2.6. Sync Result Codes .........................................11 3. Content Synchronization ........................................11 3.1. Synchronization Session ...................................12 3.2. Content Determination .....................................12 3.3. refreshOnly Mode ..........................................13 3.4. refreshAndPersist Mode ....................................16 3.5. Search Request Parameters .................................17 3.6. objectName ................................................18 3.7. Canceling the Sync Operation ..............................19 3.8. Refresh Required ..........................................19 3.9. Chattiness Considerations .................................20 3.10. Operation Multiplexing ...................................21 4. Meta Information Considerations ................................22 4.1. Entry DN ..................................................22 4.2. Operational Attributes ....................................22 4.3. Collective Attributes .....................................23 4.4. Access and Other Administrative Controls ..................23 5. Interaction with Other Controls ................................23 5.1. ManageDsaIT Control .......................................24 5.2. Subentries Control ........................................24 6. Shadowing Considerations .......................................24 7. Security Considerations ........................................25 8. IANA Considerations ............................................26 8.1. Object Identifier .........................................26 8.2. LDAP Protocol Mechanism ...................................26 8.3. LDAP Result Codes .........................................26 9. Acknowledgements ...............................................26 10. Normative References ..........................................27 11. Informative References ........................................28 Appendix A. CSN-based Implementation Considerations ..............29 Zeilenga & Choi Experimental [Page 2] RFC 4533 LDAP Content Synchronization Operation June 2006 1. Introduction The Lightweight Directory Access Protocol (LDAP) [RFC4510] provides a mechanism, the search operation [RFC4511], that allows a client to request directory content matching a complex set of assertions and to request that the server return this content, subject to access control and other restrictions, to the client. However, LDAP does not provide (despite the introduction of numerous extensions in this area) an effective and efficient mechanism for maintaining synchronized copies of directory content. This document introduces a new mechanism specifically designed to meet the content synchronization requirements of sophisticated directory applications. This document defines the LDAP Content Synchronization Operation, or Sync Operation for short, which allows a client to maintain a synchronized copy of a fragment of a Directory Information Tree (DIT). The Sync Operation is defined as a set of controls and other protocol elements that extend the Search Operation. 1.1. Background Over the years, a number of content synchronization approaches have been suggested for use in LDAP directory services. These approaches are inadequate for one or more of the following reasons: - failure to ensure a reasonable level of convergence; - failure to detect that convergence cannot be achieved (without reload); - require pre-arranged synchronization agreements; - require the server to maintain histories of past changes to DIT content and/or meta information; - require the server to maintain synchronization state on a per- client basis; and/or - are overly chatty. The Sync Operation provides eventual convergence of synchronized content when possible and, when not, notification that a full reload is required. The Sync Operation does not require pre-arranged synchronization agreements. Zeilenga & Choi Experimental [Page 3] RFC 4533 LDAP Content Synchronization Operation June 2006 The Sync Operation does not require that servers maintain or use any history of past changes to the DIT or to meta information. However, servers may maintain and use histories (e.g., change logs, tombstones, DIT snapshots) to reduce the number of messages generated and to reduce their size. As it is not always feasible to maintain and use histories, the operation may be implemented using purely (current) state-based approaches. The Sync Operation allows use of either the state-based approach or the history-based approach on an operation-by-operation basis to balance the size of history and the amount of traffic. The Sync Operation also allows the combined use of the state-based and the history-based approaches. The Sync Operation does not require that servers maintain synchronization state on a per-client basis. However, servers may maintain and use per-client state information to reduce the number of messages generated and the size of such messages. A synchronization mechanism can be considered overly chatty when synchronization traffic is not reasonably bounded. The Sync Operation traffic is bounded by the size of updated (or new) entries and the number of unchanged entries in the content. The operation is designed to avoid full content exchanges, even when the history information available to the server is insufficient to determine the client's state. The operation is also designed to avoid transmission of out-of-content history information, as its size is not bounded by the content and it is not always feasible to transmit such history information due to security reasons. This document includes a number of non-normative appendices providing additional information to server implementors. 1.2. Intended Usage The Sync Operation is intended to be used in applications requiring eventually-convergent content synchronization. Upon completion of each synchronization stage of the operation, all information to construct a synchronized client copy of the content has been provided to the client or the client has been notified that a complete content reload is necessary. Except for transient inconsistencies due to concurrent operation (or other) processing at the server, the client copy is an accurate reflection of the content held by the server. Transient inconsistencies will be resolved by subsequent synchronization operations. Zeilenga & Choi Experimental [Page 4] RFC 4533 LDAP Content Synchronization Operation June 2006 Possible uses include the following: - White page service applications may use the Sync Operation to maintain a current copy of a DIT fragment, for example, a mail user agent that uses the sync operation to maintain a local copy of an enterprise address book. - Meta-information engines may use the Sync Operation to maintain a copy of a DIT fragment. - Caching proxy services may use the Sync Operation to maintain a coherent content cache. - Lightweight master-slave replication between heterogeneous directory servers. For example, the Sync Operation can be used by a slave server to maintain a shadow copy of a DIT fragment. (Note: The International Telephone Union (ITU) has defined the X.500 Directory [X.500] Information Shadowing Protocol (DISP) [X.525], which may be used for master-slave replication between directory servers. Other experimental LDAP replication protocols also exist.) This protocol is not intended to be used in applications requiring transactional data consistency. As this protocol transfers all visible values of entries belonging to the content upon change instead of change deltas, this protocol is not appropriate for bandwidth-challenged applications or deployments. 1.3. Overview This section provides an overview of basic ways the Sync Operation can be used to maintain a synchronized client copy of a DIT fragment. - Polling for changes: refreshOnly mode - Listening for changes: refreshAndPersist mode 1.3.1. Polling for Changes (refreshOnly) To obtain its initial client copy, the client issues a Sync request: a search request with the Sync Request Control with mode set to refreshOnly. The server, much like it would with a normal search operation, returns (subject to access controls and other restrictions) the content matching the search criteria (baseObject, scope, filter, attributes). Additionally, with each entry returned, the server provides a Sync State Control indicating state add. This control contains the Universally Unique Identifier (UUID) [UUID] of Zeilenga & Choi Experimental [Page 5] RFC 4533 LDAP Content Synchronization Operation June 2006 the entry [RFC4530]. Unlike the Distinguished Name (DN), which may change over time, an entry's UUID is stable. The initial content is followed by a SearchResultDone with a Sync Done Control. The Sync Done Control provides a syncCookie. The syncCookie represents session state. To poll for updates to the client copy, the client reissues the Sync Operation with the syncCookie previously returned. The server, much as it would with a normal search operation, determines which content would be returned as if the operation were a normal search operation. However, using the syncCookie as an indicator of what content the client was sent previously, the server sends copies of entries that have changed with a Sync State Control indicating state add. For each changed entry, all (modified or unmodified) attributes belonging to the content are sent. The server may perform either or both of the two distinct synchronization phases that are distinguished by how to synchronize entries deleted from the content: the present and the delete phases. When the server uses a single phase for the refresh stage, each phase is marked as ended by a SearchResultDone with a Sync Done Control. A present phase is identified by a FALSE refreshDeletes value in the Sync Done Control. A delete phase is identified by a TRUE refreshDeletes value. The present phase may be followed by a delete phase. The two phases are delimited by a refreshPresent Sync Info Message having a FALSE refreshDone value. In the case that both the phases are used, the present phase is used to bring the client copy up to the state at which the subsequent delete phase can begin. In the present phase, the server sends an empty entry (i.e., no attributes) with a Sync State Control indicating state present for each unchanged entry. The delete phase may be used when the server can reliably determine which entries in the prior client copy are no longer present in the content and the number of such entries is less than or equal to the number of unchanged entries. In the delete mode, the server sends an empty entry with a Sync State Control indicating state delete for each entry that is no longer in the content, instead of returning an empty entry with state present for each present entry. The server may send syncIdSet Sync Info Messages containing the set of UUIDs of either unchanged present entries or deleted entries, instead of sending multiple individual messages. If refreshDeletes of syncIdSet is set to FALSE, the UUIDs of unchanged present entries are contained in the syncUUIDs set; if refreshDeletes of syncIdSet is set to TRUE, the UUIDs of the entries no longer present in the content are contained in the syncUUIDs set. An optional cookie can Zeilenga & Choi Experimental [Page 6] RFC 4533 LDAP Content Synchronization Operation June 2006 be included in the syncIdSet to represent the state of the content after synchronizing the presence or the absence of the entries contained in the syncUUIDs set. The synchronized copy of the DIT fragment is constructed by the client. If refreshDeletes of syncDoneValue is FALSE, the new copy includes all changed entries returned by the reissued Sync Operation, as well as all unchanged entries identified as being present by the reissued Sync Operation, but whose content is provided by the previous Sync Operation. The unchanged entries not identified as being present are deleted from the client content. They had been either deleted, moved, or otherwise scoped-out from the content. If refreshDeletes of syncDoneValue is TRUE, the new copy includes all changed entries returned by the reissued Sync Operation, as well as all other entries of the previous copy except for those that are identified as having been deleted from the content. The client can, at some later time, re-poll for changes to this synchronized client copy. 1.3.2. Listening for Changes (refreshAndPersist) Polling for changes can be expensive in terms of server, client, and network resources. The refreshAndPersist mode allows for active updates of changed entries in the content. By selecting the refreshAndPersist mode, the client requests that the server send updates of entries that are changed after the initial refresh content is determined. Instead of sending a SearchResultDone Message as in polling, the server sends a Sync Info Message to the client indicating that the refresh stage is complete and then enters the persist stage. After receipt of this Sync Info Message, the client will construct a synchronized copy as described in Section 1.3.1. The server may then send change notifications as the result of the original Sync search request, which now remains persistent in the server. For entries to be added to the returned content, the server sends a SearchResultEntry (with attributes) with a Sync State Control indicating state add. For entries to be deleted from the content, the server sends a SearchResultEntry containing no attributes and a Sync State Control indicating state delete. For entries to be modified in the return content, the server sends a SearchResultEntry (with attributes) with a Sync State Control indicating state modify. Zeilenga & Choi Experimental [Page 7] RFC 4533 LDAP Content Synchronization Operation June 2006 Upon modification of an entry, all (modified or unmodified) attributes belonging to the content are sent. Note that renaming an entry of the DIT may cause an add state change where the entry is renamed into the content, a delete state change where the entry is renamed out of the content, and a modify state change where the entry remains in the content. Also note that a modification of an entry of the DIT may cause an add, delete, or modify state change to the content. Upon receipt of a change notification, the client updates its copy of the content. If the server desires to update the syncCookie during the persist stage, it may include the syncCookie in any Sync State Control or Sync Info Message returned. The operation persists until canceled [RFC3909] by the client or terminated by the server. A Sync Done Control shall be attached to SearchResultDone Message to provide a new syncCookie. 1.4. Conventions 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]. Protocol elements are described using ASN.1 [X.680] with implicit tags. The term "BER-encoded" means the element is to be encoded using the Basic Encoding Rules [X.690] under the restrictions detailed in Section 5.1 of [RFC4511]. 2. Elements of the Sync Operation The Sync Operation is defined as an extension to the LDAP Search Operation [RFC4511] where the directory user agent (DUA or client) submits a SearchRequest Message with a Sync Request Control and the directory system agent (DSA or server) responds with zero or more SearchResultEntry Messages, each with a Sync State Control; zero or more SearchResultReference Messages, each with a Sync State Control; zero or more Sync Info Intermediate Response Messages; and a SearchResultDone Message with a Sync Done Control. To allow clients to discover support for this operation, servers implementing this operation SHOULD publish 1.3.6.1.4.1.4203.1.9.1.1 as a value of the 'supportedControl' attribute [RFC4512] of the root DSA-specific entry (DSE). A server MAY choose to advertise this extension only when the client is authorized to use it. Zeilenga & Choi Experimental [Page 8] RFC 4533 LDAP Content Synchronization Operation June 2006 2.1. Common ASN.1 Elements 2.1.1. syncUUID The syncUUID data type is an OCTET STRING holding a 128-bit (16-octet) Universally Unique Identifier (UUID) [UUID]. syncUUID ::= OCTET STRING (SIZE(16)) -- constrained to UUID 2.1.2. syncCookie The syncCookie is a notational convenience to indicate that, while the syncCookie type is encoded as an OCTET STRING, its value is an opaque value containing information about the synchronization session and its state. Generally, the session information would include a hash of the operation parameters that the server requires not be changed and the synchronization state information would include a commit (log) sequence number, a change sequence number, or a time stamp. For convenience of description, the term "no cookie" refers either to a null cookie or to a cookie with pre-initialized synchronization state. syncCookie ::= OCTET STRING 2.2. Sync Request Control The Sync Request Control is an LDAP Control [RFC4511] where the controlType is the object identifier 1.3.6.1.4.1.4203.1.9.1.1 and the controlValue, an OCTET STRING, contains a BER-encoded syncRequestValue. The criticality field is either TRUE or FALSE. syncRequestValue ::= SEQUENCE { mode ENUMERATED { -- 0 unused refreshOnly (1), -- 2 reserved refreshAndPersist (3) }, cookie syncCookie OPTIONAL, reloadHint BOOLEAN DEFAULT FALSE } The Sync Request Control is only applicable to the SearchRequest Message. Zeilenga & Choi Experimental [Page 9] RFC 4533 LDAP Content Synchronization Operation June 2006 2.3. Sync State Control The Sync State Control is an LDAP Control [RFC4511] where the controlType is the object identifier 1.3.6.1.4.1.4203.1.9.1.2 and the controlValue, an OCTET STRING, contains a BER-encoded syncStateValue. The criticality is FALSE. syncStateValue ::= SEQUENCE { state ENUMERATED { present (0), add (1), modify (2), delete (3) }, entryUUID syncUUID, cookie syncCookie OPTIONAL } The Sync State Control is only applicable to SearchResultEntry and SearchResultReference Messages. 2.4. Sync Done Control The Sync Done Control is an LDAP Control [RFC4511] where the controlType is the object identifier 1.3.6.1.4.1.4203.1.9.1.3 and the controlValue contains a BER-encoded syncDoneValue. The criticality is FALSE (and hence absent). syncDoneValue ::= SEQUENCE { cookie syncCookie OPTIONAL, refreshDeletes BOOLEAN DEFAULT FALSE } The Sync Done Control is only applicable to the SearchResultDone Message. Zeilenga & Choi Experimental [Page 10] RFC 4533 LDAP Content Synchronization Operation June 2006 2.5. Sync Info Message The Sync Info Message is an LDAP Intermediate Response Message [RFC4511] where responseName is the object identifier 1.3.6.1.4.1.4203.1.9.1.4 and responseValue contains a BER-encoded syncInfoValue. The criticality is FALSE (and hence absent). syncInfoValue ::= CHOICE { newcookie [0] syncCookie, refreshDelete [1] SEQUENCE { cookie syncCookie OPTIONAL, refreshDone BOOLEAN DEFAULT TRUE }, refreshPresent [2] SEQUENCE { cookie syncCookie OPTIONAL, refreshDone BOOLEAN DEFAULT TRUE }, syncIdSet [3] SEQUENCE { cookie syncCookie OPTIONAL, refreshDeletes BOOLEAN DEFAULT FALSE, syncUUIDs SET OF syncUUID } } 2.6. Sync Result Codes The following LDAP resultCode [RFC4511] is defined: e-syncRefreshRequired (4096) 3. Content Synchronization The Sync Operation is invoked when the client sends a SearchRequest Message with a Sync Request Control. The absence of a cookie or an initialized synchronization state in a cookie indicates a request for initial content, while the presence of a cookie representing a state of a client copy indicates a request for a content update. Synchronization Sessions are discussed in Section 3.1. Content Determination is discussed in Section 3.2. The mode is either refreshOnly or refreshAndPersist. The refreshOnly and refreshAndPersist modes are discussed in Sections 3.3 and 3.4, respectively. The refreshOnly mode consists only of a refresh stage, while the refreshAndPersist mode consists of a refresh stage and a subsequent persist stage. Zeilenga & Choi Experimental [Page 11] RFC 4533 LDAP Content Synchronization Operation June 2006 3.1. Synchronization Session A sequence of Sync Operations where the last cookie returned by the server for one operation is provided by the client in the next operation is said to belong to the same Synchronization Session. The client MUST specify the same content-controlling parameters (see Section 3.5) in each Search Request of the session. The client SHOULD also issue each Sync request of a session under the same authentication and authorization associations with equivalent integrity and protections. If the server does not recognize the request cookie or the request is made under different associations or non-equivalent protections, the server SHALL return the initial content as if no cookie had been provided or return an empty content with the e-syncRefreshRequired LDAP result code. The decision between the return of the initial content and the return of the empty content with the e-syncRefreshRequired result code MAY be based on reloadHint in the Sync Request Control from the client. If the server recognizes the request cookie as representing empty or initial synchronization state of the client copy, the server SHALL return the initial content. A Synchronization Session may span multiple LDAP sessions between the client and the server. The client SHOULD issue each Sync request of a session to the same server. (Note: Shadowing considerations are discussed in Section 6.) 3.2. Content Determination The content to be provided is determined by parameters of the Search Request, as described in [RFC4511], and possibly other controls. The same content parameters SHOULD be used in each Sync request of a session. If different content is requested and the server is unwilling or unable to process the request, the server SHALL return the initial content as if no cookie had been provided or return an empty content with the e-syncRefreshRequired LDAP result code. The decision between the return of the initial content and the return of the empty content with the e-syncRefreshRequired result code MAY be based on reloadHint in the Sync Request Control from the client. The content may not necessarily include all entries or references that would be returned by a normal search operation, nor, for those entries included, all attributes returned by a normal search. When the server is unwilling or unable to provide synchronization for any attribute for a set of entries, the server MUST treat all filter components matching against these attributes as Undefined and MUST NOT return these attributes in SearchResultEntry responses. Zeilenga & Choi Experimental [Page 12] RFC 4533 LDAP Content Synchronization Operation June 2006 Servers SHOULD support synchronization for all non-collective user- application attributes for all entries. The server may also return continuation references to other servers or to itself. The latter is allowed as the server may partition the entries it holds into separate synchronization contexts. The client may chase all or some of these continuations, each as a separate content synchronization session. 3.3. refreshOnly Mode A Sync request with mode refreshOnly and with no cookie is a poll for initial content. A Sync request with mode refreshOnly and with a cookie representing a synchronization state is a poll for content update. 3.3.1. Initial Content Poll Upon receipt of the request, the server provides the initial content using a set of zero or more SearchResultEntry and SearchResultReference Messages followed by a SearchResultDone Message. Each SearchResultEntry Message SHALL include a Sync State Control of state add, an entryUUID containing the entry's UUID, and no cookie. Each SearchResultReference Message SHALL include a Sync State Control of state add, an entryUUID containing the UUID associated with the reference (normally the UUID of the associated named referral [RFC3296] object), and no cookie. The SearchResultDone Message SHALL include a Sync Done Control having refreshDeletes set to FALSE. A resultCode value of success indicates that the operation successfully completed. Otherwise, the result code indicates the nature of the failure. The server may return e-syncRefreshRequired result code on the initial content poll if it is safe to do so when it is unable to perform the operation due to various reasons. reloadHint is set to FALSE in the SearchRequest Message requesting the initial content poll. If the operation is successful, a cookie representing the synchronization state of the current client copy SHOULD be returned for use in subsequent Sync Operations. 3.3.2. Content Update Poll Upon receipt of the request, the server provides the content refresh using a set of zero or more SearchResultEntry and Zeilenga & Choi Experimental [Page 13] RFC 4533 LDAP Content Synchronization Operation June 2006 SearchResultReference Messages followed by a SearchResultDone Message. The server is REQUIRED to: a) provide the sequence of messages necessary for eventual convergence of the client's copy of the content to the server's copy, b) treat the request as an initial content request (e.g., ignore the cookie or the synchronization state represented in the cookie), c) indicate that the incremental convergence is not possible by returning e-syncRefreshRequired, d) return a resultCode other than success or e- syncRefreshRequired. A Sync Operation may consist of a single present phase, a single delete phase, or a present phase followed by a delete phase. In each phase, for each entry or reference that has been added to the content or been changed since the previous Sync Operation indicated by the cookie, the server returns a SearchResultEntry or SearchResultReference Message, respectively, each with a Sync State Control consisting of state add, an entryUUID containing the UUID of the entry or reference, and no cookie. Each SearchResultEntry Message represents the current state of a changed entry. Each SearchResultReference Message represents the current state of a changed reference. In the present phase, for each entry that has not been changed since the previous Sync Operation, an empty SearchResultEntry is returned whose objectName reflects the entry's current DN, whose attributes field is empty, and whose Sync State Control consists of state present, an entryUUID containing the UUID of the entry, and no cookie. For each reference that has not been changed since the previous Sync Operation, an empty SearchResultReference containing an empty SEQUENCE OF LDAPURL is returned with a Sync State Control consisting of state present, an entryUUID containing the UUID of the entry, and no cookie. No messages are sent for entries or references that are no longer in the content. Multiple empty entries with a Sync State Control of state present SHOULD be coalesced into one or more Sync Info Messages of syncIdSet value with refreshDeletes set to FALSE. syncUUIDs contain a set of UUIDs of the entries and references unchanged since the last Sync Zeilenga & Choi Experimental [Page 14] RFC 4533 LDAP Content Synchronization Operation June 2006 Operation. syncUUIDs may be empty. The Sync Info Message of syncIdSet may contain a cookie to represent the state of the content after performing the synchronization of the entries in the set. In the delete phase, for each entry no longer in the content, the server returns a SearchResultEntry whose objectName reflects a past DN of the entry or is empty, whose attributes field is empty, and whose Sync State Control consists of state delete, an entryUUID containing the UUID of the deleted entry, and no cookie. For each reference no longer in the content, a SearchResultReference containing an empty SEQUENCE OF LDAPURL is returned with a Sync State Control consisting of state delete, an entryUUID containing the UUID of the deleted reference, and no cookie. Multiple empty entries with a Sync State Control of state delete SHOULD be coalesced into one or more Sync Info Messages of syncIdSet value with refreshDeletes set to TRUE. syncUUIDs contain a set of UUIDs of the entries and references that have been deleted from the content since the last Sync Operation. syncUUIDs may be empty. The Sync Info Message of syncIdSet may contain a cookie to represent the state of the content after performing the synchronization of the entries in the set. When a present phase is followed by a delete phase, the two phases are delimited by a Sync Info Message containing syncInfoValue of refreshPresent, which may contain a cookie representing the state after completing the present phase. The refreshPresent contains refreshDone, which is always FALSE in the refreshOnly mode of Sync Operation because it is followed by a delete phase. If a Sync Operation consists of a single phase, each phase and hence the Sync Operation are marked as ended by a SearchResultDone Message with Sync Done Control, which SHOULD contain a cookie representing the state of the content after completing the Sync Operation. The Sync Done Control contains refreshDeletes, which is set to FALSE for the present phase and set to TRUE for the delete phase. If a Sync Operation consists of a present phase followed by a delete phase, the Sync Operation is marked as ended at the end of the delete phase by a SearchResultDone Message with Sync Done Control, which SHOULD contain a cookie representing the state of the content after completing the Sync Operation. The Sync Done Control contains refreshDeletes, which is set to TRUE. The client can specify whether it prefers to receive an initial content by supplying reloadHint of TRUE or to receive a e- syncRefreshRequired resultCode by supplying reloadHint of FALSE (hence absent), in the case that the server determines that it is Zeilenga & Choi Experimental [Page 15] RFC 4533 LDAP Content Synchronization Operation June 2006 impossible or inefficient to achieve the eventual convergence by continuing the current incremental synchronization thread. A resultCode value of success indicates that the operation is successfully completed. A resultCode value of e-syncRefreshRequired indicates that a full or partial refresh is needed. Otherwise, the result code indicates the nature of failure. A cookie is provided in the Sync Done Control for use in subsequent Sync Operations for incremental synchronization. 3.4. refreshAndPersist Mode A Sync request with mode refreshAndPersist asks for initial content or content update (during the refresh stage) followed by change notifications (during the persist stage). 3.4.1. refresh Stage The content refresh is provided as described in Section 3.3, except that the successful completion of content refresh is indicated by sending a Sync Info Message of refreshDelete or refreshPresent with a refreshDone value set to TRUE instead of a SearchResultDone Message with resultCode success. A cookie SHOULD be returned in the Sync Info Message to represent the state of the content after finishing the refresh stage of the Sync Operation. 3.4.2. persist Stage Change notifications are provided during the persist stage. As updates are made to the DIT, the server notifies the client of changes to the content. DIT updates may cause entries and references to be added to the content, deleted from the content, or modified within the content. DIT updates may also cause references to be added, deleted, or modified within the content. Where DIT updates cause an entry to be added to the content, the server provides a SearchResultEntry Message that represents the entry as it appears in the content. The message SHALL include a Sync State Control with state of add, an entryUUID containing the entry's UUID, and an optional cookie. Where DIT updates cause a reference to be added to the content, the server provides a SearchResultReference Message that represents the reference in the content. The message SHALL include a Sync State Control with state of add, an entryUUID containing the UUID associated with the reference, and an optional cookie. Zeilenga & Choi Experimental [Page 16] RFC 4533 LDAP Content Synchronization Operation June 2006 Where DIT updates cause an entry to be modified within the content, the server provides a SearchResultEntry Message that represents the entry as it appears in the content. The message SHALL include a Sync State Control with state of modify, an entryUUID containing the entry's UUID, and an optional cookie. Where DIT updates cause a reference to be modified within the content, the server provides a SearchResultReference Message that represents the reference in the content. The message SHALL include a Sync State Control with state of modify, an entryUUID containing the UUID associated with the reference, and an optional cookie. Where DIT updates cause an entry to be deleted from the content, the server provides a SearchResultEntry Message with no attributes. The message SHALL include a Sync State Control with state of delete, an entryUUID containing the entry's UUID, and an optional cookie. Where DIT updates cause a reference to be deleted from the content, the server provides a SearchResultReference Message with an empty SEQUENCE OF LDAPURL. The message SHALL include a Sync State Control with state of delete, an entryUUID containing the UUID associated with the reference, and an optional cookie. Multiple empty entries with a Sync State Control of state delete SHOULD be coalesced into one or more Sync Info Messages of syncIdSet value with refreshDeletes set to TRUE. syncUUIDs contain a set of UUIDs of the entries and references that have been deleted from the content. The Sync Info Message of syncIdSet may contain a cookie to represent the state of the content after performing the synchronization of the entries in the set. With each of these messages, the server may provide a new cookie to be used in subsequent Sync Operations. Additionally, the server may also return Sync Info Messages of choice newCookie to provide a new cookie. The client SHOULD use the newest (last) cookie it received from the server in subsequent Sync Operations. 3.5. Search Request Parameters As stated in Section 3.1, the client SHOULD specify the same content-controlling parameters in each Search Request of the session. All fields of the SearchRequest Message are considered content- controlling parameters except for sizeLimit and timeLimit. Zeilenga & Choi Experimental [Page 17] RFC 4533 LDAP Content Synchronization Operation June 2006 3.5.1. baseObject As with the normal search operation, the refresh and persist stages are not isolated from DIT changes. It is possible that the entry referred to by the baseObject is deleted, renamed, or moved. It is also possible that the alias object used in finding the entry referred to by the baseObject is changed such that the baseObject refers to a different entry. If the DIT is updated during processing of the Sync Operation in a manner that causes the baseObject no longer to refer to any entry or in a manner that changes the entry the baseObject refers to, the server SHALL return an appropriate non-success result code, such as noSuchObject, aliasProblem, aliasDereferencingProblem, referral, or e-syncRefreshRequired. 3.5.2. derefAliases This operation does not support alias dereferencing during searching. The client SHALL specify neverDerefAliases or derefFindingBaseObj for the SearchRequest derefAliases parameter. The server SHALL treat other values (e.g., derefInSearching, derefAlways) as protocol errors. 3.5.3. sizeLimit The sizeLimit applies only to entries (regardless of their state in Sync State Control) returned during the refreshOnly operation or the refresh stage of the refreshAndPersist operation. 3.5.4. timeLimit For a refreshOnly Sync Operation, the timeLimit applies to the whole operation. For a refreshAndPersist operation, the timeLimit applies only to the refresh stage including the generation of the Sync Info Message with a refreshDone value of TRUE. 3.5.5. filter The client SHOULD avoid filter assertions that apply to the values of the attributes likely to be considered by the server as ones holding meta-information. See Section 4. 3.6. objectName The Sync Operation uses entryUUID values provided in the Sync State Control as the primary keys to entries. The client MUST use these entryUUIDs to correlate synchronization messages. Zeilenga & Choi Experimental [Page 18] RFC 4533 LDAP Content Synchronization Operation June 2006 In some circumstances, the DN returned may not reflect the entry's current DN. In particular, when the entry is being deleted from the content, the server may provide an empty DN if the server does not wish to disclose the entry's current DN (or, if deleted from the DIT, the entry's last DN). Also note that the entry's DN may be viewed as meta information (see Section 4.1). 3.7. Canceling the Sync Operation Servers MUST implement the LDAP Cancel [RFC3909] Operation and support cancellation of outstanding Sync Operations as described here. To cancel an outstanding Sync Operation, the client issues an LDAP Cancel [RFC3909] Operation. If at any time the server becomes unwilling or unable to continue processing a Sync Operation, the server SHALL return a SearchResultDone with a non-success resultCode indicating the reason for the termination of the operation. Whether the client or the server initiated the termination, the server may provide a cookie in the Sync Done Control for use in subsequent Sync Operations. 3.8. Refresh Required In order to achieve the eventually-convergent synchronization, the server may terminate the Sync Operation in the refresh or persist stages by returning an e-syncRefreshRequired resultCode to the client. If no cookie is provided, a full refresh is needed. If a cookie representing a synchronization state is provided in this response, an incremental refresh is needed. To obtain a full refresh, the client then issues a new synchronization request with no cookie. To obtain an incremental reload, the client issues a new synchronization with the provided cookie. The server may choose to provide a full copy in the refresh stage (e.g., ignore the cookie or the synchronization state represented in the cookie) instead of providing an incremental refresh in order to achieve the eventual convergence. Zeilenga & Choi Experimental [Page 19] RFC 4533 LDAP Content Synchronization Operation June 2006 The decision between the return of the initial content and the return of the e-syncRefreshRequired result code may be based on reloadHint in the Sync Request Control from the client. In the case of persist stage Sync, the server returns the resultCode of e-syncRefreshRequired to the client to indicate that the client needs to issue a new Sync Operation in order to obtain a synchronized copy of the content. If no cookie is provided, a full refresh is needed. If a cookie representing a synchronization state is provided, an incremental refresh is needed. The server may also return e-syncRefreshRequired if it determines that a refresh would be more efficient than sending all the messages required for convergence. Note that the client may receive one or more of SearchResultEntry, SearchResultReference, and/or Sync Info Messages before it receives a SearchResultDone Message with the e-syncRefreshRequired result code. 3.9. Chattiness Considerations The server MUST ensure that the number of entry messages generated to refresh the client content does not exceed the number of entries presently in the content. While there is no requirement for servers to maintain history information, if the server has sufficient history to allow it to reliably determine which entries in the prior client copy are no longer present in the content and the number of such entries is less than or equal to the number of unchanged entries, the server SHOULD generate delete entry messages instead of present entry messages (see Section 3.3.2). When the amount of history information maintained in the server is not enough for the clients to perform infrequent refreshOnly Sync Operations, it is likely that the server has incomplete history information (e.g., due to truncation) by the time those clients connect again. The server SHOULD NOT resort to full reload when the history information is not enough to generate delete entry messages. The server SHOULD generate either present entry messages only or present entry messages followed by delete entry messages to bring the client copy to the current state. In the latter case, the present entry messages bring the client copy to a state covered by the history information maintained in the server. The server SHOULD maintain enough (current or historical) state information (such as a context-wide last modify time stamp) to determine if no changes were made in the context since the content Zeilenga & Choi Experimental [Page 20] RFC 4533 LDAP Content Synchronization Operation June 2006 refresh was provided and, when no changes were made, generate zero delete entry messages instead of present messages. The server SHOULD NOT use the history information when its use does not reduce the synchronization traffic or when its use can expose sensitive information not allowed to be received by the client. The server implementor should also consider chattiness issues that span multiple Sync Operations of a session. As noted in Section 3.8, the server may return e-syncRefreshRequired if it determines that a reload would be more efficient than continuing under the current operation. If reloadHint in the Sync Request is TRUE, the server may initiate a reload without directing the client to request a reload. The server SHOULD transfer a new cookie frequently to avoid having to transfer information already provided to the client. Even where DIT changes do not cause content synchronization changes to be transferred, it may be advantageous to provide a new cookie using a Sync Info Message. However, the server SHOULD avoid overloading the client or network with Sync Info Messages. During persist mode, the server SHOULD coalesce multiple outstanding messages updating the same entry. The server MAY delay generation of an entry update in anticipation of subsequent changes to that entry that could be coalesced. The length of the delay should be long enough to allow coalescing of update requests issued back to back but short enough that the transient inconsistency induced by the delay is corrected in a timely manner. The server SHOULD use the syncIdSet Sync Info Message when there are multiple delete or present messages to reduce the amount of synchronization traffic. Also note that there may be many clients interested in a particular directory change, and that servers attempting to service all of these at once may cause congestion on the network. The congestion issues are magnified when the change requires a large transfer to each interested client. Implementors and deployers of servers should take steps to prevent and manage network congestion. 3.10. Operation Multiplexing The LDAP protocol model [RFC4511] allows operations to be multiplexed over a single LDAP session. Clients SHOULD NOT maintain multiple LDAP sessions with the same server. Servers SHOULD ensure that responses from concurrently processed operations are interleaved fairly. Zeilenga & Choi Experimental [Page 21] RFC 4533 LDAP Content Synchronization Operation June 2006 Clients SHOULD combine Sync Operations whose result set is largely overlapping. This avoids having to return multiple messages, once for each overlapping session, for changes to entries in the overlap. Clients SHOULD NOT combine Sync Operations whose result sets are largely non-overlapping. This ensures that an event requiring an e-syncRefreshRequired response can be limited to as few result sets as possible. 4. Meta Information Considerations 4.1. Entry DN As an entry's DN is constructed from its relative DN (RDN) and the entry's parent's DN, it is often viewed as meta information. While renaming or moving to a new superior causes the entry's DN to change, that change SHOULD NOT, by itself, cause synchronization messages to be sent for that entry. However, if the renaming or the moving could cause the entry to be added or deleted from the content, appropriate synchronization messages should be generated to indicate this to the client. When a server treats the entry's DN as meta information, the server SHALL either - evaluate all MatchingRuleAssertions [RFC4511] to TRUE if matching a value of an attribute of the entry, otherwise Undefined, or - evaluate all MatchingRuleAssertion with dnAttributes of TRUE as Undefined. The latter choice is offered for ease of server implementation. 4.2. Operational Attributes Where values of an operational attribute are determined by values not held as part of the entry it appears in, the operational attribute SHOULD NOT support synchronization of that operational attribute. For example, in servers that implement the X.501 subschema model [X.501], servers should not support synchronization of the subschemaSubentry attribute as its value is determined by values held and administrated in subschema subentries. Zeilenga & Choi Experimental [Page 22] RFC 4533 LDAP Content Synchronization Operation June 2006 As a counter example, servers that implement aliases [RFC4512][X.501] can support synchronization of the aliasedObjectName attribute as its values are held and administrated as part of the alias entries. Servers SHOULD support synchronization of the following operational attributes: createTimestamp, modifyTimestamp, creatorsName, modifiersName [RFC4512]. Servers MAY support synchronization of other operational attributes. 4.3. Collective Attributes A collective attribute is "a user attribute whose values are the same for each member of an entry collection" [X.501]. Use of collective attributes in LDAP is discussed in [RFC3671]. Modification of a collective attribute generally affects the content of multiple entries, which are the members of the collection. It is inefficient to include values of collective attributes visible in entries of the collection, as a single modification of a collective attribute requires transmission of multiple SearchResultEntry (one for each entry of the collection that the modification affected). Servers SHOULD NOT synchronize collective attributes appearing in entries of any collection. Servers MAY support synchronization of collective attributes appearing in collective attribute subentries. 4.4. Access and Other Administrative Controls Entries are commonly subject to access and other administrative Controls. While portions of the policy information governing a particular entry may be held in the entry, policy information is often held elsewhere (in superior entries, in subentries, in the root DSE, in configuration files, etc.). Because of this, changes to policy information make it difficult to ensure eventual convergence during incremental synchronization. Where it is impractical or infeasible to generate content changes resulting from a change to policy information, servers may opt to return e-syncRefreshRequired or to treat the Sync Operation as an initial content request (e.g., ignore the cookie or the synchronization state represented in the cookie). 5. Interaction with Other Controls The Sync Operation may be used with: - ManageDsaIT Control [RFC3296] Zeilenga & Choi Experimental [Page 23] RFC 4533 LDAP Content Synchronization Operation June 2006 - Subentries Control [RFC3672] as described below. The Sync Operation may be used with other LDAP extensions as detailed in other documents. 5.1. ManageDsaIT Control The ManageDsaIT Control [RFC3296] indicates that the operation acts upon the DSA Information Tree and causes referral and other special entries to be treated as object entries with respect to the operation. 5.2. Subentries Control The Subentries Control is used with the search operation "to control the visibility of entries and subentries which are within scope" [RFC3672]. When used with the Sync Operation, the subentries control and other factors (search scope, filter, etc.) are used to determine whether an entry or subentry appears in the content. 6. Shadowing Considerations As noted in [RFC4511], some servers may hold shadow copies of entries that can be used to answer search and comparison queries. Such servers may also support content synchronization requests. This section discusses considerations for implementors and deployers for the implementation and deployment of the Sync operation in shadowed directories. While a client may know of multiple servers that are equally capable of being used to obtain particular directory content from, a client SHOULD NOT assume that each of these servers is equally capable of continuing a content synchronization session. As stated in Section 3.1, the client SHOULD issue each Sync request of a Sync session to the same server. However, through domain naming or IP address redirection or other techniques, multiple physical servers can be made to appear as one logical server to a client. Only servers that are equally capable in regards to their support for the Sync operation and that hold equally complete copies of the entries should be made to appear as one logical server. In particular, each physical server acting as one logical server SHOULD be equally capable of continuing a content synchronization based upon cookies provided by any of the other physical servers without requiring a full reload. Because there is no standard LDAP shadowing mechanism, the specification of how to independently implement equally capable servers (as well as the precise definition of "equally capable") is left to future documents. Zeilenga & Choi Experimental [Page 24] RFC 4533 LDAP Content Synchronization Operation June 2006 Note that it may be difficult for the server to reliably determine what content was provided to the client by another server, especially in the shadowing environments that allow shadowing events to be coalesced. For these servers, the use of the delete phase discussed in Section 3.3.2 may not be applicable. 7. Security Considerations In order to maintain a synchronized copy of the content, a client is to delete information from its copy of the content as described above. However, the client may maintain knowledge of information disclosed to it by the server separate from its copy of the content used for synchronization. Management of this knowledge is beyond the scope of this document. Servers should be careful not to disclose information for content the client is not authorized to have knowledge of and/or about. While the information provided by a series of refreshOnly Sync Operations is similar to that provided by a series of Search Operations, persist stage may disclose additional information. A client may be able to discern information about the particular sequence of update operations that caused content change. Implementors should take precautions against malicious cookie content, including malformed cookies or valid cookies used with different security associations and/or protections in an attempt to obtain unauthorized access to information. Servers may include a digital signature in the cookie to detect tampering. The operation may be the target of direct denial-of-service attacks. Implementors should provide safeguards to ensure the operation is not abused. Servers may place access control or other restrictions upon the use of this operation. Note that even small updates to the directory may cause a significant amount of traffic to be generated to clients using this operation. A user could abuse its update privileges to mount an indirect denial of service to these clients, other clients, and/or portions of the network. Servers should provide safeguards to ensure that update operations are not abused. Implementors of this (or any) LDAP extension should be familiar with general LDAP security considerations [RFC4510]. Zeilenga & Choi Experimental [Page 25] RFC 4533 LDAP Content Synchronization Operation June 2006 8. IANA Considerations Registration of the following values have been completed by the IANA [RFC4520]. 8.1. Object Identifier The OID arc 1.3.6.1.4.1.4203.1.9.1 was assigned [ASSIGN] by the OpenLDAP Foundation, under its IANA-assigned private enterprise allocation [PRIVATE], for use in this specification. 8.2. LDAP Protocol Mechanism The IANA has registered the LDAP Protocol Mechanism described in this document. Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: 1.3.6.1.4.1.4203.1.9.1.1 Description: LDAP Content Synchronization Control Person & email address to contact for further information: Kurt Zeilenga <kurt@openldap.org> Usage: Control Specification: RFC 4533 Author/Change Controller: Kurt D. Zeilenga, Jong Hyuk Choi Comments: none 8.3. LDAP Result Codes The IANA has registered the LDAP Result Code described in this document. Subject: LDAP Result Code Registration Person & email address to contact for further information: Kurt Zeilenga <kurt@OpenLDAP.org> Result Code Name: e-syncRefreshRequired (4096) Specification: RFC 4533 Author/Change Controller: Kurt D. Zeilenga, Jong Hyuk Choi Comments: none 9. Acknowledgements This document borrows significantly from the LDAP Client Update Protocol [RFC3928], a product of the IETF LDUP working group. This document also benefited from Persistent Search [PSEARCH], Triggered Search [TSEARCH], and Directory Synchronization [DIRSYNC] works. This document also borrows from "Lightweight Directory Access Protocol (v3)" [RFC2251]. Zeilenga & Choi Experimental [Page 26] RFC 4533 LDAP Content Synchronization Operation June 2006 10. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC3296] Zeilenga, K., "Named Subordinate References in Lightweight Directory Access Protocol (LDAP) Directories", RFC 3296, July 2002. [RFC3671] Zeilenga, K., "Collective Attributes in the Lightweight Directory Access Protocol (LDAP)", RFC 3671, December 2003. [RFC3672] Zeilenga, K., "Subentries in the Lightweight Directory Access Protocol (LDAP)", RFC 3672, December 2003. [RFC3909] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP) Cancel Operation", RFC 3909, October 2004. [RFC4510] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006. [RFC4511] Sermersheim, J., Ed., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006. [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006. [RFC4530] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP) entryUUID Operational Attribute", RFC 4530, June 2006. [UUID] International Organization for Standardization (ISO), "Information technology - Open Systems Interconnection - Remote Procedure Call", ISO/IEC 11578:1996 [X.501] International Telecommunication Union - Telecommunication Standardization Sector, "The Directory -- Models," X.501(1993) (also ISO/IEC 9594-2: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). Zeilenga & Choi Experimental [Page 27] RFC 4533 LDAP Content Synchronization Operation June 2006 [X.690] International Telecommunication Union - Telecommunication Standardization Sector, "Specification of ASN.1 encoding rules: Basic Encoding Rules (BER), Canonical Encoding Rules (CER), and Distinguished Encoding Rules (DER)", X.690(1997) (also ISO/IEC 8825-1:1998). 11. Informative References [RFC2251] Wahl, M., Howes, T., and S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [RFC3928] Megginson, R., Ed., Smith, M., Natkovich, O., and J. Parham, "Lightweight Directory Access Protocol (LDAP) Client Update Protocol (LCUP)", RFC 3928, October 2004. [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006. [PRIVATE] IANA, "Private Enterprise Numbers", http://www.iana.org/assignments/enterprise-numbers. [ASSIGN] OpenLDAP Foundation, "OpenLDAP OID Delegations", http://www.openldap.org/foundation/oid-delegate.txt. [X.500] International Telecommunication Union - Telecommunication Standardization Sector, "The Directory -- Overview of concepts, models and services," X.500(1993) (also ISO/IEC 9594-1:1994). [X.525] International Telecommunication Union - Telecommunication Standardization Sector, "The Directory: Replication", X.525(1993). [DIRSYNC] Armijo, M., "Microsoft LDAP Control for Directory Synchronization", Work in Progress. [PSEARCH] Smith, M., et al., "Persistent Search: A Simple LDAP Change Notification Mechanism", Work in Progress. [TSEARCH] Wahl, M., "LDAPv3 Triggered Search Control", Work in Progress. Zeilenga & Choi Experimental [Page 28] RFC 4533 LDAP Content Synchronization Operation June 2006 Appendix A. CSN-based Implementation Considerations This appendix is provided for informational purposes only; it is not a normative part of the LDAP Content Synchronization Operation's technical specification. This appendix discusses LDAP Content Synchronization Operation server implementation considerations associated with Change Sequence Number based approaches. Change Sequence Number based approaches are targeted for use in servers that do not maintain history information (e.g., change logs, state snapshots) about changes made to the Directory and hence, must rely on current directory state and minimal synchronization state information embedded in Sync Cookie. Servers that maintain history information should consider other approaches that exploit the history information. A Change Sequence Number is effectively a time stamp that has sufficient granularity to ensure that the precedence relationship in time of two updates to the same object can be determined. Change Sequence Numbers are not to be confused with Commit Sequence Numbers or Commit Log Record Numbers. A Commit Sequence Number allows one to determine how two commits (to the same object or different objects) relate to each other in time. A Change Sequence Number associated with different entries may be committed out of order. In the remainder of this Appendix, the term CSN refers to a Change Sequence Number. In these approaches, the server not only maintains a CSN for each directory entry (the entry CSN) but also maintains a value that we will call the context CSN. The context CSN is the greatest committed entry CSN that is not greater than any outstanding (uncommitted) entry CSNs for all entries in a directory context. The values of context CSN are used in syncCookie values as synchronization state indicators. As search operations are not isolated from individual directory update operations and individual update operations cannot be assumed to be serialized, one cannot assume that the returned content incorporates each relevant change whose change sequence number is less than or equal to the greatest entry CSN in the content. The content incorporates all the relevant changes whose change sequence numbers are less than or equal to context CSN before search processing. The content may also incorporate any subset of the changes whose change sequence number is greater than context CSN before search processing but less than or equal to the context CSN after search processing. The content does not incorporate any of the Zeilenga & Choi Experimental [Page 29] RFC 4533 LDAP Content Synchronization Operation June 2006 changes whose CSN is greater than the context CSN after search processing. A simple server implementation could use the value of the context CSN before search processing to indicate state. Such an implementation would embed this value into each SyncCookie returned. We'll call this the cookie CSN. When a refresh was requested, the server would simply generate "update" messages for all entries in the content whose CSN is greater than the supplied cookie CSN and generate "present" messages for all other entries in the content. However, if the current context CSN is the same as the cookie CSN, the server should instead generate zero "updates" and zero "delete" messages and indicate a refreshDeletes of TRUE, as the directory has not changed. The implementation should also consider the impact of changes to meta information, such as access controls, that affect content determination. One approach is for the server to maintain a context-wide meta information CSN or meta CSN. This meta CSN would be updated whenever meta information affecting content determination was changed. If the value of the meta CSN is greater than the cookie CSN, the server should ignore the cookie and treat the request as an initial request for content. Additionally, servers may want to consider maintaining some per- session history information to reduce the number of messages needed to be transferred during incremental refreshes. Specifically, a server could record information about entries as they leave the scope of a disconnected sync session and later use this information to generate delete messages instead of present messages. When the history information is truncated, the CSN of the latest truncated history information entry may be recorded as the truncated CSN of the history information. The truncated CSN may be used to determine whether a client copy can be covered by the history information by comparing it to the synchronization state contained in the cookie supplied by the client. When there is a large number of sessions, it may make sense to maintain such history only for the selected clients. Also, servers taking this approach need to consider resource consumption issues to ensure reasonable server operation and to protect against abuse. It may be appropriate to restrict this mode of operation by policy. Zeilenga & Choi Experimental [Page 30] RFC 4533 LDAP Content Synchronization Operation June 2006 Authors' Addresses Kurt D. Zeilenga OpenLDAP Foundation EMail: Kurt@OpenLDAP.org Jong Hyuk Choi IBM Corporation EMail: jongchoi@us.ibm.com Zeilenga & Choi Experimental [Page 31] RFC 4533 LDAP Content Synchronization Operation June 2006 Full Copyright Statement Copyright (C) The Internet Society (2006). This document is subject to the rights, licenses and restrictions contained in BCP 78 and at www.rfc-editor.org/copyright.html, 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@ietf.org. Acknowledgement Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Zeilenga & Choi Experimental [Page 32] PK +�c\��ќ�. �. ( doc/alt-openldap11-devel/rfc/rfc3703.txtnu �[��� Network Working Group J. Strassner Request for Comments: 3703 Intelliden Corporation Category: Standards Track B. Moore IBM Corporation R. Moats Lemur Networks, Inc. E. Ellesson February 2004 Policy Core Lightweight Directory Access Protocol (LDAP) Schema Status of this Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2004). All Rights Reserved. Abstract This document defines a mapping of the Policy Core Information Model to a form that can be implemented in a directory that uses Lightweight Directory Access Protocol (LDAP) as its access protocol. This model defines two hierarchies of object classes: structural classes representing information for representing and controlling policy data as specified in RFC 3060, and relationship classes that indicate how instances of the structural classes are related to each other. Classes are also added to the LDAP schema to improve the performance of a client's interactions with an LDAP server when the client is retrieving large amounts of policy-related information. These classes exist only to optimize LDAP retrievals: there are no classes in the information model that correspond to them. Table of Contents 1. Introduction ................................................. 2 2. The Policy Core Information Model ............................ 4 3. Inheritance Hierarchy for the PCLS ........................... 5 4. General Discussion of Mapping the Information Model to LDAP .. 6 4.1. Summary of Class and Association Mappings .............. 7 4.2. Usage of DIT Content and Structure Rules and Name Forms. 9 4.3. Naming Attributes in the PCLS .......................... 10 Strassner, et al. Standards Track [Page 1] RFC 3703 Policy Core LDAP Schema February 2004 4.4. Rule-Specific and Reusable Conditions and Actions ...... 11 4.5. Location and Retrieval of Policy Objects in the Directory .............................................. 16 4.5.1. Aliases and Other DIT-Optimization Techniques .. 19 5. Class Definitions ............................................ 19 5.1. The Abstract Class "pcimPolicy" ........................ 21 5.2. The Three Policy Group Classes ......................... 22 5.3. The Three Policy Rule Classes .......................... 23 5.4. The Class pcimRuleConditionAssociation ................. 30 5.5. The Class pcimRuleValidityAssociation .................. 32 5.6. The Class pcimRuleActionAssociation .................... 34 5.7. The Auxiliary Class pcimConditionAuxClass .............. 36 5.8. The Auxiliary Class pcimTPCAuxClass .................... 36 5.9. The Auxiliary Class pcimConditionVendorAuxClass ........ 40 5.10. The Auxiliary Class pcimActionAuxClass ................. 41 5.11. The Auxiliary Class pcimActionVendorAuxClass ........... 42 5.12. The Class pcimPolicyInstance ........................... 43 5.13. The Auxiliary Class pcimElementAuxClass ................ 44 5.14. The Three Policy Repository Classes .................... 45 5.15. The Auxiliary Class pcimSubtreesPtrAuxClass ............ 46 5.16. The Auxiliary Class pcimGroupContainmentAuxClass ....... 48 5.17. The Auxiliary Class pcimRuleContainmentAuxClass ........ 49 6. Extending the Classes Defined in This Document ............... 50 6.1. Subclassing pcimConditionAuxClass and pcimActionAuxClass 50 6.2. Using the Vendor Policy Attributes ..................... 50 6.3. Using Time Validity Periods ............................ 51 7. Security Considerations ...................................... 51 8. IANA Considerations .......................................... 53 8.1. Object Identifiers ..................................... 53 8.2. Object Identifier Descriptors .......................... 53 9. Acknowledgments .............................................. 56 10. Appendix: Constructing the Value of orderedCIMKeys .......... 57 11. References ................................................... 58 11.1. Normative References ................................... 58 11.2. Informative References ................................. 59 12. Authors' Addresses ........................................... 60 13. Full Copyright Statement ..................................... 61 1. Introduction This document takes as its starting point the object-oriented information model for representing information for representing and controlling policy data as specified in [1]. Lightweight Directory Access Protocol (LDAP) [2] implementers, please note that the use of the term "policy" in this document does not refer to the use of the term "policy" as defined in X.501 [4]. Rather, the use of the term "policy" throughout this document is defined as follows: Strassner, et al. Standards Track [Page 2] RFC 3703 Policy Core LDAP Schema February 2004 Policy is defined as a set of rules to administer, manage, and control access to network resources. This work is currently under joint development in the IETF's Policy Framework working group and in the Policy working group of the Distributed Management Task Force (DMTF). This model defines two hierarchies of object classes: structural classes representing policy information and control of policies, and relationship classes that indicate how instances of the structural classes are related to each other. In general, both of these class hierarchies will need to be mapped to a particular data store. This document defines the mapping of these information model classes to a directory that uses LDAP as its access protocol. Two types of mappings are involved: - For the structural classes in the information model, the mapping is basically one-for-one: information model classes map to LDAP classes, information model properties map to LDAP attributes. - For the relationship classes in the information model, different mappings are possible. In this document, the Policy Core Information Model's (PCIM's) relationship classes and their properties are mapped in three ways: to LDAP auxiliary classes, to attributes representing distinguished name (DN) references, and to superior-subordinate relationships in the Directory Information Tree (DIT). Implementations that use an LDAP directory as their policy repository and want to implement policy information according to RFC 3060 [1] SHALL use the LDAP schema defined in this document, or a schema that subclasses from the schema defined in this document. The use of the information model defined in reference [1] as the starting point enables the inheritance and the relationship class hierarchies to be extensible, such that other types of policy repositories, such as relational databases, can also use this information. This document fits into the overall framework for representing, deploying, and managing policies being developed by the Policy Framework Working Group. The LDAP schema described in this document uses the prefix "pcim" to identify its classes and attributes. It consists of ten very general classes: pcimPolicy (an abstract class), three policy group classes (pcimGroup, pcimGroupAuxClass, and pcimGroupInstance), three policy rule classes (pcimRule, pcimRuleAuxClass, and pcimRuleInstance), and three special auxiliary classes (pcimConditionAuxClass, Strassner, et al. Standards Track [Page 3] RFC 3703 Policy Core LDAP Schema February 2004 pcimTPCAuxClass, and pcimActionAuxClass). (Note that the PolicyTimePeriodCondition auxiliary class defined in [1] would normally have been named pcimTimePeriodConditionAuxClass, but this name is too long for some directories. Therefore, we have abbreviated this name to be pcimTPCAuxClass). The mapping for the PCIM classes pcimGroup and pcimRule is designed to be as flexible as possible. Three classes are defined for these two PCIM classes. First, an abstract superclass is defined that contains all required properties of each PCIM class. Then, both an auxiliary class as well as a structural class are derived from the abstract superclass. This provides maximum flexibility for the developer. The schema also contains two less general classes: pcimConditionVendorAuxClass and pcimActionVendorAuxClass. To achieve the mapping of the information model's relationships, the schema also contains two auxiliary classes: pcimGroupContainmentAuxClass and pcimRuleContainmentAuxClass. Capturing the distinction between rule-specific and reusable policy conditions and policy actions introduces seven other classes: pcimRuleConditionAssociation, pcimRuleValidityAssociation, pcimRuleActionAssociation, pcimPolicyInstance, and three policy repository classes (pcimRepository, pcimRepositoryAuxClass, and pcimRepositoryInstance). Finally, the schema includes two classes (pcimSubtreesPtrAuxClass and pcimElementAuxClass) for optimizing LDAP retrievals. In all, the schema contains 23 classes. Within the context of this document, the term "PCLS" (Policy Core LDAP Schema) is used to refer to the LDAP class definitions that this document contains. The term "PCIM" refers to classes defined in [1]. 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 [10]. 2. The Policy Core Information Model This document contains an LDAP schema representing the classes defined in the companion document "Policy Core Information Model -- Version 1 Specification" [1]. Other documents may subsequently be produced, with mappings of this same PCIM to other storage technologies. Since the detailed semantics of the PCIM classes appear only in [1], that document is a prerequisite for reading and understanding this document. Strassner, et al. Standards Track [Page 4] RFC 3703 Policy Core LDAP Schema February 2004 3. Inheritance Hierarchy for the PCLS The following diagram illustrates the class hierarchy for the LDAP Classes defined in this document: top | +--dlm1ManagedElement (abstract) | | | +--pcimPolicy (abstract) | | | | | +--pcimGroup (abstract) | | | | | | | +--pcimGroupAuxClass (auxiliary) | | | | | | | +--pcimGroupInstance (structural) | | | | | +--pcimRule (abstract) | | | | | | | +--pcimRuleAuxClass (auxiliary) | | | | | | | +--pcimRuleInstance (structural) | | | | | +--pcimRuleConditionAssociation (structural) | | | | | +--pcimRuleValidityAssociation (structural) | | | | | +--pcimRuleActionAssociation (structural) | | | | | +--pcimPolicyInstance (structural) | | | | | +--pcimElementAuxClass (auxiliary) | | | +--dlm1ManagedSystemElement (abstract) | | | +--dlm1LogicalElement (abstract) | | | +--dlm1System (abstract) | | | +--dlm1AdminDomain (abstract) | | | +--pcimRepository (abstract) | | | +--pcimRepositoryAuxClass (auxiliary) Strassner, et al. Standards Track [Page 5] RFC 3703 Policy Core LDAP Schema February 2004 top | | | +--pcimRepositoryInstance | (structural) | +--pcimConditionAuxClass (auxiliary) | | | +---pcimTPCAuxClass (auxiliary) | | | +---pcimConditionVendorAuxClass (auxiliary) | +--pcimActionAuxClass (auxiliary) | | | +---pcimActionVendorAuxClass (auxiliary) | +--pcimSubtreesPtrAuxClass (auxiliary) | +--pcimGroupContainmentAuxClass (auxiliary) | +--pcimRuleContainmentAuxClass (auxiliary) Figure 1. LDAP Class Inheritance Hierarchy for the PCLS 4. General Discussion of Mapping the Information Model to LDAP The classes described in Section 5 below contain certain optimizations for a directory that uses LDAP as its access protocol. One example of this is the use of auxiliary classes to represent some of the associations defined in the information model. Other data stores might need to implement these associations differently. A second example is the introduction of classes specifically designed to optimize retrieval of large amounts of policy-related data from a directory. This section discusses some general topics related to the mapping from the information model to LDAP. The remainder of this section will discuss the following topics. Section 4.1 will discuss the strategy used in mapping the classes and associations defined in [1] to a form that can be represented in a directory that uses LDAP as its access protocol. Section 4.2 discusses DIT content and structure rules, as well as name forms. Section 4.3 describes the strategy used in defining naming attributes for the schema described in Section 5 of this document. Section 4.4 defines the strategy recommended for locating and retrieving PCIM-derived objects in the directory. Strassner, et al. Standards Track [Page 6] RFC 3703 Policy Core LDAP Schema February 2004 4.1. Summary of Class and Association Mappings Fifteen of the classes in the PCLS come directly from the nine corresponding classes in the information model. Note that names of classes begin with an upper case character in the information model (although for CIM in particular, case is not significant in class and property names), but with a lower case character in LDAP. This is because although LDAP doesn't care, X.500 doesn't allow class names to begin with an uppercase character. Note also that the prefix "pcim" is used to identify these LDAP classes. +---------------------------+-------------------------------+ | Information Model | LDAP Class(es) | +---------------------------+-------------------------------+ +---------------------------+-------------------------------+ | Policy | pcimPolicy | +---------------------------+-------------------------------+ | PolicyGroup | pcimGroup | | | pcimGroupAuxClass | | | pcimGroupInstance | +---------------------------+-------------------------------+ | PolicyRule | pcimRule | | | pcimRuleAuxClass | | | pcimRuleInstance | +---------------------------+-------------------------------+ | PolicyCondition | pcimConditionAuxClass | +---------------------------+-------------------------------+ | PolicyAction | pcimActionAuxClass | +---------------------------+-------------------------------+ | VendorPolicyCondition | pcimConditionVendorAuxClass | +---------------------------+-------------------------------+ | VendorPolicyAction | pcimActionVendorAuxClass | +---------------------------+-------------------------------+ | PolicyTimePeriodCondition | pcimTPCAuxClass | +---------------------------+-------------------------------+ | PolicyRepository | pcimRepository | | | pcimRepositoryAuxClass | | | pcimRepositoryInstance | +---------------------------+-------------------------------+ Figure 2. Mapping of Information Model Classes to LDAP The associations in the information model map to attributes that reference DNs (Distinguished Names) or to Directory Information Tree (DIT) containment (i.e., superior-subordinate relationships) in LDAP. Two of the attributes that reference DNs appear in auxiliary classes, which allow each of them to represent several relationships from the information model. Strassner, et al. Standards Track [Page 7] RFC 3703 Policy Core LDAP Schema February 2004 +----------------------------------+----------------------------------+ | Information Model Association | LDAP Attribute / Class | +-----------------------------------+---------------------------------+ +-----------------------------------+---------------------------------+ | PolicyGroupInPolicyGroup | pcimGroupsAuxContainedSet in | | | pcimGroupContainmentAuxClass | +-----------------------------------+---------------------------------+ | PolicyRuleInPolicyGroup | pcimRulesAuxContainedSet in | | | pcimRuleContainmentAuxClass | +-----------------------------------+---------------------------------+ | PolicyConditionInPolicyRule | DIT containment or | | | pcimRuleConditionList in | | | pcimRule or | | | pcimConditionDN in | | | pcimRuleConditionAssociation | +-----------------------------------+---------------------------------+ | PolicyActionInPolicyRule | DIT containment or | | | pcimRuleActionList in | | | pcimRule or | | | pcimActionDN in | | | pcimRuleActionAssociation | +-----------------------------------+---------------------------------+ | PolicyRuleValidityPeriod | pcimRuleValidityPeriodList | | | in pcimRule or (if reusable) | | | referenced through the | | | pcimTimePeriodConditionDN in | | | pcimRuleValidityAssociation | +-----------------------------------+---------------------------------+ | PolicyConditionInPolicyRepository | DIT containment | +-----------------------------------+---------------------------------+ | PolicyActionInPolicyRepository | DIT containment | +-----------------------------------+---------------------------------+ | PolicyRepositoryInPolicyRepository| DIT containment | +-----------------------------------+---------------------------------+ Figure 3. Mapping of Information Model Associations to LDAP Of the remaining classes in the PCLS, two (pcimElementAuxClass and pcimSubtreesPtrAuxClass) are included to make navigation through the DIT and retrieval of the entries found there more efficient. This topic is discussed below in Section 4.5. The remaining four classes in the PCLS, pcimRuleConditionAssociation, pcimRuleValidityAssociation, pcimRuleActionAssociation, and pcimPolicyInstance, are all involved with the representation of policy conditions and policy actions in an LDAP directory. This topic is discussed below in Section 4.4. Strassner, et al. Standards Track [Page 8] RFC 3703 Policy Core LDAP Schema February 2004 4.2. Usage of DIT Content and Structure Rules and Name Forms There are three powerful tools that can be used to help define schemata. The first, DIT content rules, is a way of defining the content of an entry for a structural object class. It can be used to specify the following characteristics of the entry: - additional mandatory attributes that the entries are required to contain - additional optional attributes the entries are allowed to contain - the set of additional auxiliary object classes that these entries are allowed to be members of - any optional attributes from the structural and auxiliary object class definitions that the entries are required to preclude DIT content rules are NOT mandatory for any structural object class. A DIT structure rule, together with a name form, controls the placement and naming of an entry within the scope of a subschema. Name forms define which attribute type(s) are required and are allowed to be used in forming the Relative Distinguished Names (RDNs) of entries. DIT structure rules specify which entries are allowed to be superior to other entries, and hence control the way that RDNs are added together to make DNs. A name form specifies the following: - the structural object class of the entries named by this name form - attributes that are required to be used in forming the RDNs of these entries - attributes that are allowed to be used in forming the RDNs of these entries - an object identifier to uniquely identify this name form Note that name forms can only be specified for structural object classes. However, every entry in the DIT must have a name form controlling it. Unfortunately, current LDAP servers vary quite a lot in their support of these features. There are also three crucial implementation points that must be followed. First, X.500 use of structure rules requires that a structural object class with no superior structure rule be a subschema administrative point. This is exactly NOT what we want for policy information. Second, when an auxiliary class is subclassed, if a content rule exists for the structural class that Strassner, et al. Standards Track [Page 9] RFC 3703 Policy Core LDAP Schema February 2004 the auxiliary class refers to, then that content rule needs to be augmented. Finally, most LDAP servers unfortunately do not support inheritance of structure and content rules. Given these concerns, DIT structure and content rules have been removed from the PCLS. This is because, if included, they would be normative references and would require OIDs. However, we don't want to lose the insight gained in building the structure and content rules of the previous version of the schema. Therefore, we describe where such rules could be used in this schema, what they would control, and what their effect would be. 4.3. Naming Attributes in the PCLS Instances in a directory are identified by distinguished names (DNs), which provide the same type of hierarchical organization that a file system provides in a computer system. A distinguished name is a sequence of RDNs. An RDN provides a unique identifier for an instance within the context of its immediate superior, in the same way that a filename provides a unique identifier for a file within the context of the folder in which it resides. To preserve maximum naming flexibility for policy administrators, three optional (i.e., "MAY") naming attributes have been defined. They are: - Each of the structural classes defined in this schema has its own unique ("MAY") naming attribute. Since the naming attributes are different, a policy administrator can, by using these attributes, guarantee that there will be no name collisions between instances of different classes, even if the same value is assigned to the instances' respective naming attributes. - The LDAP attribute cn (corresponding to X.500's commonName) is included as a MAY attribute in the abstract class pcimPolicy, and thus by inheritance in all of its subclasses. In X.500, commonName typically functions as an RDN attribute, for naming instances of many classes (e.g., X.500's person class). - A special attribute is provided for implementations that expect to map between native CIM and LDAP representations of policy information. This attribute, called orderedCimKeys, is defined in the class dlm1ManagedElement [6]. The value of this attribute is derived algorithmically from values that are already present in a CIM policy instance. The normative reference for this algorithm is contained in [6]. See the appendix of this document for a description of the algorithm. Strassner, et al. Standards Track [Page 10] RFC 3703 Policy Core LDAP Schema February 2004 Since any of these naming attributes MAY be used for naming an instance of a PCLS class, implementations MUST be able to accommodate instances named in any of these ways. Note that it is recommended that two or more of these attributes SHOULD NOT be used together to form a multi-part RDN, since support for multi-part RDNs is limited among existing directory implementations. 4.4. Rule-Specific and Reusable Conditions and Actions The PCIM [1] distinguishes between two types of policy conditions and policy actions: those associated with a single policy rule, and those that are reusable, in the sense that they may be associated with more than one policy rule. While there is no inherent functional difference between a rule-specific condition or action and a reusable one, there is both a usage, as well as, an implementation difference between them. Defining a condition or action as reusable vs. rule-specific reflects a conscious decision on the part of the administrator in defining how they are used. In addition, there are variations that reflect implementing rule-specific vs. reusable policy conditions and actions and how they are treated in a policy repository. The major implementation differences between a rule-specific and a reusable condition or action are delineated below: 1. It is natural for a rule-specific condition or action to be removed from the policy repository at the same time the rule is. It is just the opposite for reusable conditions and actions. This is because the condition or action is conceptually attached to the rule in the rule-specific case, whereas it is referenced (e.g., pointed at) in the reusable case. The persistence of a pcimRepository instance is independent of the persistence of a pcimRule instance. 2. Access permissions for a rule-specific condition or action are usually identical to those for the rule itself. On the other hand, access permissions of reusable conditions and actions must be expressible without reference to a policy rule. 3. Rule-specific conditions and actions require fewer accesses, because the conditions and actions are "attached" to the rule. In contrast, reusable conditions and actions require more accesses, because each condition or action that is reusable requires a separate access. 4. Rule-specific conditions and actions are designed for use by a single rule. As the number of rules that use the same rule-specific condition increase, subtle problems are created (the most obvious being how to keep the rule-specific conditions Strassner, et al. Standards Track [Page 11] RFC 3703 Policy Core LDAP Schema February 2004 and actions updated to reflect the same value). Reusable conditions and actions lend themselves for use by multiple independent rules. 5. Reusable conditions and actions offer an optimization when multiple rules are using the same condition or action. This is because the reusable condition or action only needs be updated once, and by virtue of DN reference, the policy rules will be automatically updated. The preceding paragraph does not contain an exhaustive list of the ways in which reusable and rule-specific conditions should be treated differently. Its purpose is merely to justify making a semantic distinction between rule-specific and reusable, and then reflecting this distinction in the policy repository itself. When the policy repository is realized in an LDAP-accessible directory, the distinction between rule-specific and reusable conditions and actions is realized via placement of auxiliary classes and via DIT containment. Figure 4 illustrates a policy rule Rule1 with one rule-specific condition CA and one rule-specific action AB. +-----+ |Rule1| | | +-----|- -|-----+ | +-----+ | | * * | | * * | | **** **** | | * * | v * * v +--------+ +--------+ | CA+ca | | AB+ab | +--------+ +--------+ +------------------------------+ |LEGEND: | | ***** DIT containment | | + auxiliary attachment | | ----> DN reference | +------------------------------+ Figure 4 Rule-Specific Policy Conditions and Actions Strassner, et al. Standards Track [Page 12] RFC 3703 Policy Core LDAP Schema February 2004 Because the condition and action are specific to Rule1, the auxiliary classes ca and ab that represent them are attached, respectively, to the structural classes CA and AB. These structural classes represent not the condition ca and action ab themselves, but rather the associations between Rule1 and ca, and between Rule1 and ab. As Figure 4 illustrates, Rule1 contains DN references to the structural classes CA and AB that appear below it in the DIT. At first glance it might appear that these DN references are unnecessary, since a subtree search below Rule1 would find all of the structural classes representing the associations between Rule1 and its conditions and actions. Relying only on a subtree search, though, runs the risk of missing conditions or actions that should have appeared in the subtree, but for some reason did not, or of finding conditions or actions that were inadvertently placed in the subtree, or that should have been removed from the subtree, but for some reason were not. Implementation experience has suggested that many (but not all) of these risks are eliminated. However, it must be noted that this comes at a price. The use of DN references, as shown in Figure 4 above, thwarts inheritance of access control information as well as existence dependency information. It also is subject to referential integrity considerations. Therefore, it is being included as an option for the designer. Figure 5 illustrates a second way of representing rule-specific conditions and actions in an LDAP-accessible directory: attachment of the auxiliary classes directly to the instance representing the policy rule. When all of the conditions and actions are attached to a policy rule in this way, the rule is termed a "simple" policy rule. When conditions and actions are not attached directly to a policy rule, the rule is termed a "complex" policy rule. +-----------+ |Rule1+ca+ab| | | +-----------+ +------------------------------+ |LEGEND: | | + auxiliary attachment | +------------------------------+ Figure 5. A Simple Policy Rule Strassner, et al. Standards Track [Page 13] RFC 3703 Policy Core LDAP Schema February 2004 The simple/complex distinction for a policy rule is not all or nothing. A policy rule may have its conditions attached to itself and its actions attached to other entries, or it may have its actions attached to itself and its conditions attached to other entries. However, it SHALL NOT have either its conditions or its actions attached both to itself and to other entries, with one exception: a policy rule may reference its validity periods with the pcimRuleValidityPeriodList attribute, but have its other conditions attached to itself. The tradeoffs between simple and complex policy rules are between the efficiency of simple rules and the flexibility and greater potential for reuse of complex rules. With a simple policy rule, the semantic options are limited: - All conditions are ANDed together. This combination can be represented in two ways in the Disjunctive Normal Form (DNF)/ Conjunctive Normal Form (CNF) (please see [1] for definitions of these terms) expressions characteristic of policy conditions: as a DNF expression with a single AND group, or as a CNF expression with multiple single-condition OR groups. The first of these is arbitrarily chosen as the representation for the ANDed conditions in a simple policy rule. - If multiple actions are included, no order can be specified for them. If a policy administrator needs to combine conditions in some other way, or if there is a set of actions that must be ordered, then the only option is to use a complex policy rule. Finally, Figure 6 illustrates the same policy rule Rule1, but this time its condition and action are reusable. The association classes CA and AB are still present, and they are still DIT contained under Rule1. But rather than having the auxiliary classes ca and ab attached directly to the association classes CA and AB, each now contains DN references to other entries to which these auxiliary classes are attached. These other entries, CIA and AIB, are DIT contained under RepositoryX, which is an instance of the class pcimRepository. Because they are named under an instance of pcimRepository, ca and ab are clearly identified as reusable. Strassner, et al. Standards Track [Page 14] RFC 3703 Policy Core LDAP Schema February 2004 +-----+ +-------------+ |Rule1| | RepositoryX | +-|- -|--+ | | | +-----+ | +-------------+ | * * | * * | * * | * * | *** **** | * * | * * v * * | * +---+ * * | * |AB | +------+ * v * | -|-------->|AIB+ab| * +---+ +---+ +------+ * |CA | +------+ | -|------------------------>|CIA+ca| +---+ +------+ +------------------------------+ |LEGEND: | | ***** DIT containment | | + auxiliary attachment | | ----> DN reference | +------------------------------+ Figure 6. Reusable Policy Conditions and Actions The classes pcimConditionAuxClass and pcimActionAuxClass do not themselves represent actual conditions and actions: these are introduced in their subclasses. What pcimConditionAuxClass and pcimActionAuxClass do introduce are the semantics of being a policy condition or a policy action. These are the semantics that all the subclasses of pcimConditionAuxClass and pcimActionAuxClass inherit. Among these semantics are those of representing either a rule-specific or a reusable policy condition or policy action. In order to preserve the ability to represent a rule-specific or a reusable condition or action, as well as a simple policy rule, all the subclasses of pcimConditionAuxClass and pcimActionAuxClass MUST also be auxiliary classes. Strassner, et al. Standards Track [Page 15] RFC 3703 Policy Core LDAP Schema February 2004 4.5. Location and Retrieval of Policy Objects in the Directory When a Policy Decision Point (PDP) goes to an LDAP directory to retrieve the policy object instances relevant to the Policy Enforcement Points (PEPs) it serves, it is faced with two related problems: - How does it locate and retrieve the directory entries that apply to its PEPs? These entries may include instances of the PCLS classes, instances of domain-specific subclasses of these classes, and instances of other classes modeling such resources as user groups, interfaces, and address ranges. - How does it retrieve the directory entries it needs in an efficient manner, so that retrieval of policy information from the directory does not become a roadblock to scalability? There are two facets to this efficiency: retrieving only the relevant directory entries, and retrieving these entries using as few LDAP calls as possible. The placement of objects in the Directory Information Tree (DIT) involves considerations other than how the policy-related objects will be retrieved by a PDP. Consequently, all that the PCLS can do is to provide a "toolkit" of classes to assist the policy administrator as the DIT is being designed and built. A PDP SHOULD be able to take advantage of any tools that the policy administrator is able to build into the DIT, but it MUST be able to use a less efficient means of retrieval if that is all it has available to it. The basic idea behind the LDAP optimization classes is a simple one: make it possible for a PDP to retrieve all the policy-related objects it needs, and only those objects, using as few LDAP calls as possible. An important assumption underlying this approach is that the policy administrator has sufficient control over the underlying DIT structure to define subtrees for storing policy information. If the policy administrator does not have this level of control over DIT structure, a PDP can still retrieve the policy-related objects it needs individually. But it will require more LDAP access operations to do the retrieval in this way. Figure 7 illustrates how LDAP optimization is accomplished. Strassner, et al. Standards Track [Page 16] RFC 3703 Policy Core LDAP Schema February 2004 +-----+ ---------------->| A | DN reference to | | DN references to subtrees +---+ starting object +-----+ +-------------------------->| C | | o--+----+ +---+ +---+ | o--+------------->| B | / \ +-----+ +---+ / \ / \ / \ / ... \ / \ / \ / \ / ... \ Figure 7. Using the pcimSubtreesPtrAuxClass to Locate Policies The PDP is configured initially with a DN reference to some entry in the DIT. The structural class of this entry is not important; the PDP is interested only in the pcimSubtreesPtrAuxClass attached to it. This auxiliary class contains a multi-valued attribute with DN references to objects that anchor subtrees containing policy-related objects of interest to the PDP. Since pcimSubtreesPtrAuxClass is an auxiliary class, it can be attached to an entry that the PDP would need to access anyway - perhaps an entry containing initial configuration settings for the PDP, or for a PEP that uses the PDP. Once it has retrieved the DN references, the PDP will direct to each of the objects identified by them an LDAP request that all entries in its subtree be evaluated against the selection criteria specified in the request. The LDAP-enabled directory then returns all entries in that subtree that satisfy the specified criteria. The selection criteria always specify that object class="pcimPolicy". Since all classes representing policy rules, policy conditions, and policy actions, both in the PCLS and in any domain-specific schema derived from it, are subclasses of the abstract class policy, this criterion evaluates to TRUE for all instances of these classes. To accommodate special cases where a PDP needs to retrieve objects that are not inherently policy-related (for example, an IP address range object referenced by a subclass of pcimActionAuxClass representing the DHCP action "assign from this address range"), the auxiliary class pcimElementAuxClass can be used to "tag" an entry, so that it will be found by the selection criterion "object class=pcimPolicy". The approach described in the preceding paragraph will not work for certain directory implementations, because these implementations do not support matching of auxiliary classes in the objectClass attribute. For environments where these implementations are expected to be present, the "tagging" of entries as relevant to policy can be Strassner, et al. Standards Track [Page 17] RFC 3703 Policy Core LDAP Schema February 2004 accomplished by inserting the special value "POLICY" into the list of values contained in the pcimKeywords attribute (provided by the pcimPolicy class). If a PDP needs only a subset of the policy-related objects in the indicated subtrees, then it can be configured with additional selection criteria based on the pcimKeywords attribute defined in the pcimPolicy class. This attribute supports both standardized and administrator- defined values. For example, a PDP could be configured to request only those policy-related objects containing the keywords "DHCP" and "Eastern US". To optimize what is expected to be a typical case, the initial request from the client includes not only the object to which its "seed" DN references, but also the subtree contained under this object. The filter for searching this subtree is whatever the client is going to use later to search the other subtrees: object class="pcimPolicy" or the presence of the keyword "POLICY", and/or presence of a more specific value of pcimKeywords (e.g., "QoS Edge Policy"). Returning to the example in Figure 7, we see that in the best case, a PDP can get all the policy-related objects it needs, and only those objects, with exactly three LDAP requests: one to its starting object A to get the references to B and C, as well as the policy-related objects it needs from the subtree under A, and then one each to B and C to get all the policy-related objects that pass the selection criteria with which it was configured. Once it has retrieved all of these objects, the PDP can then traverse their various DN references locally to understand the semantic relationships among them. The PDP should also be prepared to find a reference to another subtree attached to any of the objects it retrieves, and to follow this reference first, before it follows any of the semantically significant references it has received. This recursion permits a structured approach to identifying related policies. In Figure 7, for example, if the subtree under B includes departmental policies and the one under C includes divisional policies, then there might be a reference from the subtree under C to an object D that roots the subtree of corporate-level policies. A PDP SHOULD understand the pcimSubtreesPtrAuxClass class, SHOULD be capable of retrieving and processing the entries in the subtrees it references, and SHOULD be capable of doing all of this recursively. The same requirements apply to any other entity needing to retrieve policy information from the directory. Thus, a Policy Management Tool that retrieves policy entries from the directory in order to perform validation and conflict detection SHOULD also understand and be capable of using the pcimSubtreesPtrAuxClass. All of these Strassner, et al. Standards Track [Page 18] RFC 3703 Policy Core LDAP Schema February 2004 requirements are "SHOULD"s rather than "MUST"s because an LDAP client that doesn't implement them can still access and retrieve the directory entries it needs. The process of doing so will just be less efficient than it would have been if the client had implemented these optimizations. When it is serving as a tool for creating policy entries in the directory, a Policy Management Tool SHOULD support creation of pcimSubtreesPtrAuxClass entries and their references to object instances. 4.5.1. Aliases and Other DIT-Optimization Techniques Additional flexibility in DIT structure is available to the policy administrator via LDAP aliasing and other techniques. Previous versions of this document have used aliases. However, because aliases are experimental, the use of aliases has been removed from this version of this document. This is because the IETF has yet to produce a specification on how aliases are represented in the directory or how server implementations are to process aliases. 5. Class Definitions The semantics for the policy information classes that are to be mapped directly from the information model to an LDAP representation are detailed in [1]. Consequently, all that this document presents for these classes is the specification for how to do the mapping from the information model (which is independent of repository type and access protocol) to a form that can be accessed using LDAP. Remember that some new classes needed to be created (that were not part of [1]) to implement the LDAP mapping. These new LDAP-only classes are fully documented in this document. The formal language for specifying the classes, attributes, and DIT structure and content rules is that defined in reference [3]. If your implementation does not support auxiliary class inheritance, you will have to list auxiliary classes in content rules explicitly or define them in another (implementation-specific) way. The following notes apply to this section in its entirety. Note 1: in the following definitions, the class and attribute definitions follow RFC 2252 [3] but they are line-wrapped to enhance human readability. Note 2: where applicable, the possibilities for specifying DIT structure and content rules are noted. However, care must be taken in specifying DIT structure rules. This is because X.501 [4] states Strassner, et al. Standards Track [Page 19] RFC 3703 Policy Core LDAP Schema February 2004 that an entry may only exist in the DIT as a subordinate to another superior entry (the superior) if a DIT structure rule exists in the governing subschema which: 1) indicates a name form for the structural object class of the subordinate entry, and 2) either includes the entry's superior structure rule as a possible superior structure rule, or 3) does not specify a superior structure rule. If this last case (3) applies, then the entry is defined to be a subschema administrative point. This is not what is desired. Therefore, care must be taken in defining structure rules, and in particular, they must be locally augmented. Note 3: Wherever possible, both an equality and a substring matching rule are defined for a particular attribute (as well as an ordering match rule to enable sorting of matching results). This provides two different choices for the developer for maximum flexibility. For example, consider the pcimRoles attribute (section 5.3). Suppose that a PEP has reported that it is interested in pcimRules for three roles R1, R2, and R3. If the goal is to minimize queries, then the PDP can supply three substring filters containing the three role names. These queries will return all of the pcimRules that apply to the PEP, but they may also get some that do not apply (e.g., ones that contain one of the roles R1, R2, or R3 and one or more other roles present in a role-combination [1]). Another strategy would be for the PDP to use only equality filters. This approach eliminates the extraneous replies, but it requires the PDP to explicitly build the desired role-combinations itself. It also requires extra queries. Note that this approach is practical only because the role names in a role combination are required to appear in alphabetical order. Note 4: in the following definitions, note that all LDAP matching rules are defined in [3] and in [9]. The corresponding X.500 matching rules are defined in [8]. Note 5: some of the following attribute definitions specify additional constraints on various data types (e.g., this integer has values that are valid from 1..10). Text has been added to instruct servers and applications what to do if a value outside of this range Strassner, et al. Standards Track [Page 20] RFC 3703 Policy Core LDAP Schema February 2004 is encountered. In all cases, if a constraint is violated, then the policy rule SHOULD be treated as being disabled, meaning that execution of the policy rule SHOULD be stopped. 5.1. The Abstract Class pcimPolicy The abstract class pcimPolicy is a direct mapping of the abstract class Policy from the PCIM. The class value "pcimPolicy" is also used as the mechanism for identifying policy-related instances in the Directory Information Tree. An instance of any class may be "tagged" with this class value by attaching to it the auxiliary class pcimElementAuxClass. Since pcimPolicy is derived from the class dlm1ManagedElement defined in reference [6], this specification has a normative dependency on that element of reference [6]. The class definition is as follows: ( 1.3.6.1.1.6.1.1 NAME 'pcimPolicy' DESC 'An abstract class that is the base class for all classes that describe policy-related instances.' SUP dlm1ManagedElement ABSTRACT MAY ( cn $ dlmCaption $ dlmDescription $ orderedCimKeys $ pcimKeywords ) ) The attribute cn is defined in RFC 2256 [7]. The dlmCaption, dlmDescription, and orderedCimKeys attributes are defined in [6]. The pcimKeywords attribute is a multi-valued attribute that contains a set of keywords to assist directory clients in locating the policy objects identified by these keywords. It is defined as follows: ( 1.3.6.1.1.6.2.3 NAME 'pcimKeywords' DESC 'A set of keywords to assist directory clients in locating the policy objects applicable to them.' EQUALITY caseIgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) Strassner, et al. Standards Track [Page 21] RFC 3703 Policy Core LDAP Schema February 2004 5.2. The Three Policy Group Classes PCIM [1] defines the PolicyGroup class to serve as a generalized aggregation mechanism, enabling PolicyRules and/or PolicyGroups to be aggregated together. PCLS maps this class into three LDAP classes, called pcimGroup, pcimGroupAuxClass, and pcimGroupInstance. This is done in order to provide maximum flexibility for the DIT designer. The class definitions for the three policy group classes are listed below. These class definitions do not include attributes to realize the PolicyRuleInPolicyGroup and PolicyGroupInPolicyGroup associations from the PCIM. This is because a pcimGroup object refers to instances of pcimGroup and pcimRule via, respectively, the attribute pcimGroupsAuxContainedSet in the pcimGroupContainmentAuxClass object class and the attribute pcimRulesAuxContainedSet in the pcimRuleContainmentAuxClass object class. To maximize flexibility, the pcimGroup class is defined as abstract. The subclass pcimGroupAuxClass provides for auxiliary attachment to another entry, while the structural subclass pcimGroupInstance is available to represent a policy group as a standalone entry. The class definitions are as follows. First, the definition of the abstract class pcimGroup: ( 1.3.6.1.1.6.1.2 NAME 'pcimGroup' DESC 'A container for a set of related pcimRules and/or a set of related pcimGroups.' SUP pcimPolicy ABSTRACT MAY ( pcimGroupName ) ) The one attribute of pcimGroup is pcimGroupName. This attribute is used to define a user-friendly name of this policy group, and may be used as a naming attribute if desired. It is defined as follows: ( 1.3.6.1.1.6.2.4 NAME 'pcimGroupName' DESC 'The user-friendly name of this policy group.' EQUALITY caseIgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) Strassner, et al. Standards Track [Page 22] RFC 3703 Policy Core LDAP Schema February 2004 The two subclasses of pcimGroup are defined as follows. The class pcimGroupAuxClass is an auxiliary class that can be used to collect a set of related pcimRule and/or pcimGroup classes. It is defined as follows: ( 1.3.6.1.1.6.1.3 NAME 'pcimGroupAuxClass' DESC 'An auxiliary class that collects a set of related pcimRule and/or pcimGroup entries.' SUP pcimGroup AUXILIARY ) The class pcimGroupInstance is a structural class that can be used to collect a set of related pcimRule and/or pcimGroup classes. It is defined as follows: ( 1.3.6.1.1.6.1.4 NAME 'pcimGroupInstance' DESC 'A structural class that collects a set of related pcimRule and/or pcimGroup entries.' SUP pcimGroup STRUCTURAL ) A DIT content rule could be written to enable an instance of pcimGroupInstance to have attached to it either references to one or more policy groups (using pcimGroupContainmentAuxClass) or references to one or more policy rules (using pcimRuleContainmentAuxClass). This would be used to formalize the semantics of the PolicyGroup class [1]. Since these semantics do not include specifying any properties of the PolicyGroup class, the content rule would not need to specify any attributes. Similarly, three separate DIT structure rules could be written, each of which would refer to a specific name form that identified one of the three possible naming attributes (i.e., pcimGroupName, cn, and orderedCIMKeys) for the pcimGroup object class. This structure rule SHOULD include a superiorStructureRule (see Note 2 at the beginning of section 5). The three name forms referenced by the three structure rules would each define one of the three naming attributes. 5.3. The Three Policy Rule Classes The information model defines a PolicyRule class to represent the "If Condition then Action" semantics associated with processing policy information. For maximum flexibility, the PCLS maps this class into three LDAP classes. Strassner, et al. Standards Track [Page 23] RFC 3703 Policy Core LDAP Schema February 2004 To maximize flexibility, the pcimRule class is defined as abstract. The subclass pcimRuleAuxClass provides for auxiliary attachment to another entry, while the structural subclass pcimRuleInstance is available to represent a policy rule as a standalone entry. The conditions and actions associated with a policy rule are modeled, respectively, with auxiliary subclasses of the auxiliary classes pcimConditionAuxClass and pcimActionAuxClass. Each of these auxiliary subclasses is attached to an instance of one of three structural classes. A subclass of pcimConditionAuxClass is attached to an instance of pcimRuleInstance, to an instance of pcimRuleConditionAssociation, or to an instance of pcimPolicyInstance. Similarly, a subclass of pcimActionAuxClass is attached to an instance of pcimRuleInstance, to an instance of pcimRuleActionAssociation, or to an instance of pcimPolicyInstance. The pcimRuleValidityPeriodList attribute (defined below) realizes the PolicyRuleValidityPeriod association defined in the PCIM. Since this association has no additional properties besides those that tie the association to its associated objects, this association can be realized by simply using an attribute. Thus, the pcimRuleValidityPeriodList attribute is simply a multi-valued attribute that provides an unordered set of DN references to one or more instances of the pcimTPCAuxClass, indicating when the policy rule is scheduled to be active and when it is scheduled to be inactive. A policy rule is scheduled to be active if it is active according to AT LEAST ONE of the pcimTPCAuxClass instances referenced by this attribute. The PolicyConditionInPolicyRule and PolicyActionInPolicyRule associations, however, do have additional attributes. The association PolicyActionInPolicyRule defines an integer attribute to sequence the actions, and the association PolicyConditionInPolicyRule has both an integer attribute to group the condition terms as well as a Boolean property to specify whether a condition is to be negated. In the PCLS, these additional association attributes are represented as attributes of two classes introduced specifically to model these associations. These classes are the pcimRuleConditionAssociation class and the pcimRuleActionAssociation class, which are defined in Sections 5.4 and 5.5, respectively. Thus, they do not appear as attributes of the class pcimRule. Instead, the pcimRuleConditionList and pcimRuleActionList attributes can be used to reference these classes. Strassner, et al. Standards Track [Page 24] RFC 3703 Policy Core LDAP Schema February 2004 The class definitions for the three pcimRule classes are as follows. The abstract class pcimRule is a base class for representing the "If Condition then Action" semantics associated with a policy rule. It is defined as follows: ( 1.3.6.1.1.6.1.5 NAME 'pcimRule' DESC 'The base class for representing the "If Condition then Action" semantics associated with a policy rule.' SUP pcimPolicy ABSTRACT MAY ( pcimRuleName $ pcimRuleEnabled $ pcimRuleConditionListType $ pcimRuleConditionList $ pcimRuleActionList $ pcimRuleValidityPeriodList $ pcimRuleUsage $ pcimRulePriority $ pcimRuleMandatory $ pcimRuleSequencedActions $ pcimRoles ) ) The PCIM [1] defines seven properties for the PolicyRule class. The PCLS defines eleven attributes for the pcimRule class, which is the LDAP equivalent of the PolicyRule class. Of these eleven attributes, seven are mapped directly from corresponding properties in PCIM's PolicyRule class. The remaining four attributes are a class-specific optional naming attribute, and three attributes used to realize the three associations that the pcimRule class participates in. The pcimRuleName attribute is used as a user-friendly name of this policy rule, and can also serve as the class-specific optional naming attribute. It is defined as follows: ( 1.3.6.1.1.6.2.5 NAME 'pcimRuleName' DESC 'The user-friendly name of this policy rule.' EQUALITY caseIgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) The pcimRuleEnabled attribute is an integer enumeration indicating whether a policy rule is administratively enabled (value=1), administratively disabled (value=2), or enabled for debug (value=3). It is defined as follows: ( 1.3.6.1.1.6.2.6 NAME 'pcimRuleEnabled' DESC 'An integer indicating whether a policy rule is administratively enabled (value=1), disabled Strassner, et al. Standards Track [Page 25] RFC 3703 Policy Core LDAP Schema February 2004 (value=2), or enabled for debug (value=3).' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) Note: All other values for the pcimRuleEnabled attribute are considered errors, and the administrator SHOULD treat this rule as being disabled if an invalid value is found. The pcimRuleConditionListType attribute is used to indicate whether the list of policy conditions associated with this policy rule is in disjunctive normal form (DNF, value=1) or conjunctive normal form (CNF, value=2). It is defined as follows: ( 1.3.6.1.1.6.2.7 NAME 'pcimRuleConditionListType' DESC 'A value of 1 means that this policy rule is in disjunctive normal form; a value of 2 means that this policy rule is in conjunctive normal form.' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) Note: any value other than 1 or 2 for the pcimRuleConditionListType attribute is considered an error. Administrators SHOULD treat this rule as being disabled if an invalid value is found, since it is unclear how to structure the condition list. The pcimRuleConditionList attribute is a multi-valued attribute that is used to realize the policyRuleInPolicyCondition association defined in [1]. It contains a set of DNs of pcimRuleConditionAssociation entries representing associations between this policy rule and its conditions. No order is implied. It is defined as follows: ( 1.3.6.1.1.6.2.8 NAME 'pcimRuleConditionList' DESC 'Unordered set of DNs of pcimRuleConditionAssociation entries representing associations between this policy rule and its conditions.' EQUALITY distinguishedNameMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 ) Strassner, et al. Standards Track [Page 26] RFC 3703 Policy Core LDAP Schema February 2004 The pcimRuleActionList attribute is a multi-valued attribute that is used to realize the policyRuleInPolicyAction association defined in [1]. It contains a set of DNs of pcimRuleActionAssociation entries representing associations between this policy rule and its actions. No order is implied. It is defined as follows: ( 1.3.6.1.1.6.2.9 NAME 'pcimRuleActionList' DESC 'Unordered set of DNs of pcimRuleActionAssociation entries representing associations between this policy rule and its actions.' EQUALITY distinguishedNameMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 ) The pcimRuleValidityPeriodList attribute is a multi-valued attribute that is used to realize the pcimRuleValidityPeriod association that is defined in [1]. It contains a set of DNs of pcimRuleValidityAssociation entries that determine when the pcimRule is scheduled to be active or inactive. No order is implied. It is defined as follows: ( 1.3.6.1.1.6.2.10 NAME 'pcimRuleValidityPeriodList' DESC 'Unordered set of DNs of pcimRuleValidityAssociation entries that determine when the pcimRule is scheduled to be active or inactive.' EQUALITY distinguishedNameMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 ) The pcimRuleUsage attribute is a free-form string providing guidelines on how this policy should be used. It is defined as follows: ( 1.3.6.1.1.6.2.11 NAME 'pcimRuleUsage' DESC 'This attribute is a free-form sting providing guidelines on how this policy should be used.' EQUALITY caseIgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) Strassner, et al. Standards Track [Page 27] RFC 3703 Policy Core LDAP Schema February 2004 The pcimRulePriority attribute is a non-negative integer that is used to prioritize this pcimRule relative to other pcimRules. A larger value indicates a higher priority. It is defined as follows: ( 1.3.6.1.1.6.2.12 NAME 'pcimRulePriority' DESC 'A non-negative integer for prioritizing this pcimRule relative to other pcimRules. A larger value indicates a higher priority.' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) Note: if the value of the pcimRulePriority field is 0, then it SHOULD be treated as "don't care". On the other hand, if the value is negative, then it SHOULD be treated as an error and Administrators SHOULD treat this rule as being disabled. The pcimRuleMandatory attribute is a Boolean attribute that, if TRUE, indicates that for this policy rule, the evaluation of its conditions and execution of its actions (if the condition is satisfied) is required. If it is FALSE, then the evaluation of its conditions and execution of its actions (if the condition is satisfied) is not required. This attribute is defined as follows: ( 1.3.6.1.1.6.2.13 NAME 'pcimRuleMandatory' DESC 'If TRUE, indicates that for this policy rule, the evaluation of its conditions and execution of its actions (if the condition is satisfied) is required.' EQUALITY booleanMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 SINGLE-VALUE ) The pcimRuleSequencedActions attribute is an integer enumeration that is used to indicate that the ordering of actions defined by the pcimActionOrder attribute is either mandatory(value=1), recommended(value=2), or dontCare(value=3). It is defined as follows: ( 1.3.6.1.1.6.2.14 NAME 'pcimRuleSequencedActions' DESC 'An integer enumeration indicating that the ordering of actions defined by the pcimActionOrder attribute is mandatory(1), recommended(2), or dontCare(3).' EQUALITY integerMatch ORDERING integerOrderingMatch Strassner, et al. Standards Track [Page 28] RFC 3703 Policy Core LDAP Schema February 2004 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) Note: if the value of pcimRulesSequencedActions field is not one of these three values, then Administrators SHOULD treat this rule as being disabled. The pcimRoles attribute represents the policyRoles property of [1]. Each value of this attribute represents a role-combination, which is a string of the form: <RoleName>[&&<RoleName>]* where the individual role names appear in alphabetical order according to the collating sequence for UCS-2. This attribute is defined as follows: ( 1.3.6.1.1.6.2.15 NAME 'pcimRoles' DESC 'Each value of this attribute represents a role- combination.' EQUALITY caseIgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) Note: if the value of the pcimRoles attribute does not conform to the format "<RoleName>[&&<RoleName>]*" (see Section 6.3.7 of [1]), then this attribute is malformed and its policy rule SHOULD be treated as being disabled. The two subclasses of the pcimRule class are defined as follows. First, the pcimRuleAuxClass is an auxiliary class for representing the "If Condition then Action" semantics associated with a policy rule. Its class definition is as follows: ( 1.3.6.1.1.6.1.6 NAME 'pcimRuleAuxClass' DESC 'An auxiliary class for representing the "If Condition then Action" semantics associated with a policy rule.' SUP pcimRule AUXILIARY ) The pcimRuleInstance is a structural class for representing the "If Condition then Action" semantics associated with a policy rule. Its class definition is as follows: ( 1.3.6.1.1.6.1.7 NAME 'pcimRuleInstance' DESC 'A structural class for representing the "If Condition then Action" semantics associated with a policy rule.' Strassner, et al. Standards Track [Page 29] RFC 3703 Policy Core LDAP Schema February 2004 SUP pcimRule STRUCTURAL ) A DIT content rule could be written to enable an instance of pcimRuleInstance to have attached to it either references to one or more policy conditions (using pcimConditionAuxClass) or references to one or more policy actions (using pcimActionAuxClass). This would be used to formalize the semantics of the PolicyRule class [1]. Since these semantics do not include specifying any properties of the PolicyRule class, the content rule would not need to specify any attributes. Similarly, three separate DIT structure rules could be written, each of which would refer to a specific name form that identified one of its three possible naming attributes (i.e., pcimRuleName, cn, and orderedCIMKeys). This structure rule SHOULD include a superiorStructureRule (see Note 2 at the beginning of section 5). The three name forms referenced by the three structure rules would each define one of the three naming attributes. 5.4. The Class pcimRuleConditionAssociation This class contains attributes to represent the properties of the PCIM's PolicyConditionInPolicyRule association. Instances of this class are related to an instance of pcimRule via DIT containment. The policy conditions themselves are represented by auxiliary subclasses of the auxiliary class pcimConditionAuxClass. These auxiliary classes are attached directly to instances of pcimRuleConditionAssociation for rule-specific policy conditions. For a reusable policy condition, the policyCondition auxiliary subclass is attached to an instance of the class pcimPolicyInstance (which is presumably associated with a pcimRepository by DIT containment), and the policyConditionDN attribute (of this class) is used to reference the reusable policyCondition instance. The class definition is as follows: ( 1.3.6.1.1.6.1.8 NAME 'pcimRuleConditionAssociation' DESC 'This class contains attributes characterizing the relationship between a policy rule and one of its policy conditions.' SUP pcimPolicy MUST ( pcimConditionGroupNumber $ pcimConditionNegated ) MAY ( pcimConditionName $ pcimConditionDN ) ) Strassner, et al. Standards Track [Page 30] RFC 3703 Policy Core LDAP Schema February 2004 The attributes of this class are defined as follows. The pcimConditionGroupNumber attribute is a non-negative integer. It is used to identify the group to which the condition referenced by this association is assigned. This attribute is defined as follows: ( 1.3.6.1.1.6.2.16 NAME 'pcimConditionGroupNumber' DESC 'The number of the group to which a policy condition belongs. This is used to form the DNF or CNF expression associated with a policy rule.' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) Note that this number is non-negative. A negative value for this attribute is invalid, and any policy rule that refers to an invalid entry SHOULD be treated as being disabled. The pcimConditionNegated attribute is a Boolean attribute that indicates whether this policy condition is to be negated or not. If it is TRUE (FALSE), it indicates that a policy condition IS (IS NOT) negated in the DNF or CNF expression associated with a policy rule. This attribute is defined as follows: ( 1.3.6.1.1.6.2.17 NAME 'pcimConditionNegated' DESC 'If TRUE (FALSE), it indicates that a policy condition IS (IS NOT) negated in the DNF or CNF expression associated with a policy rule.' EQUALITY booleanMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 SINGLE-VALUE ) The pcimConditionName is a user-friendly name for identifying this policy condition, and may be used as a naming attribute if desired. This attribute is defined as follows: ( 1.3.6.1.1.6.2.18 NAME 'pcimConditionName' DESC 'A user-friendly name for a policy condition.' EQUALITY caseIgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR caseIgnoreSubstringsMatch Strassner, et al. Standards Track [Page 31] RFC 3703 Policy Core LDAP Schema February 2004 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) The pcimConditionDN attribute is a DN that references an instance of a reusable policy condition. This attribute is defined as follows: ( 1.3.6.1.1.6.2.19 NAME 'pcimConditionDN' DESC 'A DN that references an instance of a reusable policy condition.' EQUALITY distinguishedNameMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 SINGLE-VALUE ) A DIT content rule could be written to enable an instance of pcimRuleConditionAssociation to have attached to it an instance of the auxiliary class pcimConditionAuxClass, or one of its subclasses. This would be used to formalize the semantics of the PolicyConditionInPolicyRule association. Specifically, this would be used to represent a rule-specific policy condition [1]. Similarly, three separate DIT structure rules could be written. Each of these DIT structure rules would refer to a specific name form that defined two important semantics. First, each name form would identify one of the three possible naming attributes (i.e., pcimConditionName, cn, and orderedCIMKeys) for the pcimRuleConditionAssociation object class. Second, each name form would require that an instance of the pcimRuleConditionAssociation class have as its superior an instance of the pcimRule class. This structure rule SHOULD also include a superiorStructureRule (see Note 2 at the beginning of section 5). 5.5. The Class pcimRuleValidityAssociation The policyRuleValidityPeriod aggregation is mapped to the PCLS pcimRuleValidityAssociation class. This class represents the scheduled activation and deactivation of a policy rule by binding the definition of times that the policy is active to the policy rule itself. The "scheduled" times are either identified through an attached auxiliary class pcimTPCAuxClass, or are referenced through its pcimTimePeriodConditionDN attribute. This class is defined as follows: ( 1.3.6.1.1.6.1.9 NAME 'pcimRuleValidityAssociation' DESC 'This defines the scheduled activation or deactivation of a policy rule.' Strassner, et al. Standards Track [Page 32] RFC 3703 Policy Core LDAP Schema February 2004 SUP pcimPolicy STRUCTURAL MAY ( pcimValidityConditionName $ pcimTimePeriodConditionDN ) ) The attributes of this class are defined as follows: The pcimValidityConditionName attribute is used to define a user-friendly name of this condition, and may be used as a naming attribute if desired. This attribute is defined as follows: ( 1.3.6.1.1.6.2.20 NAME 'pcimValidityConditionName' DESC 'A user-friendly name for identifying an instance of a pcimRuleValidityAssociation entry.' EQUALITY caseIgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) The pcimTimePeriodConditionDN attribute is a DN that references a reusable time period condition. It is defined as follows: ( 1.3.6.1.1.6.2.21 NAME 'pcimTimePeriodConditionDN' DESC 'A reference to a reusable policy time period condition.' EQUALITY distinguishedNameMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 SINGLE-VALUE ) A DIT content rule could be written to enable an instance of pcimRuleValidityAssociation to have attached to it an instance of the auxiliary class pcimTPCAuxClass, or one of its subclasses. This would be used to formalize the semantics of the PolicyRuleValidityPeriod aggregation [1]. Similarly, three separate DIT structure rules could be written. Each of these DIT structure rules would refer to a specific name form that defined two important semantics. First, each name form would identify one of the three possible naming attributes (i.e., pcimValidityConditionName, cn, and orderedCIMKeys) for the pcimRuleValidityAssociation object class. Second, each name form would require that an instance of the pcimRuleValidityAssociation class have as its superior an instance of the pcimRule class. This Strassner, et al. Standards Track [Page 33] RFC 3703 Policy Core LDAP Schema February 2004 structure rule SHOULD also include a superiorStructureRule (see Note 2 at the beginning of section 5). 5.6. The Class pcimRuleActionAssociation This class contains an attribute to represent the one property of the PCIM PolicyActionInPolicyRule association, ActionOrder. This property is used to specify an order for executing the actions associated with a policy rule. Instances of this class are related to an instance of pcimRule via DIT containment. The actions themselves are represented by auxiliary subclasses of the auxiliary class pcimActionAuxClass. These auxiliary classes are attached directly to instances of pcimRuleActionAssociation for rule-specific policy actions. For a reusable policy action, the pcimAction auxiliary subclass is attached to an instance of the class pcimPolicyInstance (which is presumably associated with a pcimRepository by DIT containment), and the pcimActionDN attribute (of this class) is used to reference the reusable pcimCondition instance. The class definition is as follows: ( 1.3.6.1.1.6.1.10 NAME 'pcimRuleActionAssociation' DESC 'This class contains attributes characterizing the relationship between a policy rule and one of its policy actions.' SUP pcimPolicy MUST ( pcimActionOrder ) MAY ( pcimActionName $ pcimActionDN ) ) The pcimActionName attribute is used to define a user-friendly name of this action, and may be used as a naming attribute if desired. This attribute is defined as follows: ( 1.3.6.1.1.6.2.22 NAME 'pcimActionName' DESC 'A user-friendly name for a policy action.' EQUALITY caseIgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) Strassner, et al. Standards Track [Page 34] RFC 3703 Policy Core LDAP Schema February 2004 The pcimActionOrder attribute is an unsigned integer that is used to indicate the relative position of an action in a sequence of actions that are associated with a given policy rule. When this number is positive, it indicates a place in the sequence of actions to be performed, with smaller values indicating earlier positions in the sequence. If the value is zero, then this indicates that the order is irrelevant. Note that if two or more actions have the same non-zero value, they may be performed in any order as long as they are each performed in the correct place in the overall sequence of actions. This attribute is defined as follows: ( 1.3.6.1.1.6.2.23 NAME 'pcimActionOrder' DESC 'An integer indicating the relative order of an action in the context of a policy rule.' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) Note: if the value of the pcimActionOrder field is negative, then it SHOULD be treated as an error and any policy rule that refers to such an entry SHOULD be treated as being disabled. The pcimActionDN attribute is a DN that references a reusable policy action. It is defined as follows: ( 1.3.6.1.1.6.2.24 NAME 'pcimActionDN' DESC 'A DN that references a reusable policy action.' EQUALITY distinguishedNameMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 SINGLE-VALUE ) A DIT content rule could be written to enable an instance of pcimRuleActionAssociation to have attached to it an instance of the auxiliary class pcimActionAuxClass, or one of its subclasses. This would be used to formalize the semantics of the PolicyActionInPolicyRule association. Specifically, this would be used to represent a rule-specific policy action [1]. Similarly, three separate DIT structure rules could be written. Each of these DIT structure rules would refer to a specific name form that defined two important semantics. First, each name form would identify one of the three possible naming attributes (i.e., pcimActionName, cn, and orderedCIMKeys) for the Strassner, et al. Standards Track [Page 35] RFC 3703 Policy Core LDAP Schema February 2004 pcimRuleActionAssociation object class. Second, each name form would require that an instance of the pcimRuleActionAssociation class have as its superior an instance of the pcimRule class. This structure rule should also include a superiorStructureRule (see Note 2 at the beginning of section 5). 5.7. The Auxiliary Class pcimConditionAuxClass The purpose of a policy condition is to determine whether or not the set of actions (contained in the pcimRule that the condition applies to) should be executed or not. This class defines the basic organizational semantics of a policy condition, as specified in [1]. Subclasses of this auxiliary class can be attached to instances of three other classes in the PCLS. When a subclass of this class is attached to an instance of pcimRuleConditionAssociation, or to an instance of pcimRule, it represents a rule-specific policy condition. When a subclass of this class is attached to an instance of pcimPolicyInstance, it represents a reusable policy condition. Since all of the classes to which subclasses of this auxiliary class may be attached are derived from the pcimPolicy class, the attributes of pcimPolicy will already be defined for the entries to which these subclasses attach. Thus, this class is derived directly from "top". The class definition is as follows: ( 1.3.6.1.1.6.1.11 NAME 'pcimConditionAuxClass' DESC 'A class representing a condition to be evaluated in conjunction with a policy rule.' SUP top AUXILIARY ) 5.8. The Auxiliary Class pcimTPCAuxClass The PCIM defines a time period class, PolicyTimePeriodCondition, to provide a means of representing the time periods during which a policy rule is valid, i.e., active. It also defines an aggregation, PolicyRuleValidityPeriod, so that time periods can be associated with a PolicyRule. The LDAP mapping also provides two classes, one for the time condition itself, and one for the aggregation. In the PCIM, the time period class is named PolicyTimePeriodCondition. However, the resulting name of the auxiliary class in this mapping (pcimTimePeriodConditionAuxClass) exceeds the length of a name that some directories can store. Therefore, the name has been shortened to pcimTPCAuxClass. Strassner, et al. Standards Track [Page 36] RFC 3703 Policy Core LDAP Schema February 2004 The class definition is as follows: ( 1.3.6.1.1.6.1.12 NAME 'pcimTPCAuxClass' DESC 'This provides the capability of enabling or disabling a policy rule according to a predetermined schedule.' SUP pcimConditionAuxClass AUXILIARY MAY ( pcimTPCTime $ pcimTPCMonthOfYearMask $ pcimTPCDayOfMonthMask $ pcimTPCDayOfWeekMask $ pcimTPCTimeOfDayMask $ pcimTPCLocalOrUtcTime ) ) The attributes of the pcimTPCAuxClass are defined as follows. The pcimTPCTime attribute represents the time period that a policy rule is enabled for. This attribute is defined as a string in [1] with a special format which defines a time period with a starting date and an ending date separated by a forward slash ("/"), as follows: yyyymmddThhmmss/yyyymmddThhmmss where the first date and time may be replaced with the string "THISANDPRIOR" or the second date and time may be replaced with the string "THISANDFUTURE". This attribute is defined as follows: ( 1.3.6.1.1.6.2.25 NAME 'pcimTPCTime' DESC 'The start and end times on which a policy rule is valid.' EQUALITY caseIgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.44 SINGLE-VALUE ) The value of this attribute SHOULD be checked against its defined format ("yyyymmddThhmmss/yyyymmddThhmmss", where the first and second date strings may be replaced with the strings "THISANDPRIOR" and "THISANDFUTURE"). If the value of this attribute does not conform to this syntax, then this SHOULD be considered an error and the policy rule SHOULD be treated as being disabled. The next four attributes (pcimTPCMonthOfYearMask, pcimTPCDayOfMonthMask, pcimTPCDayOfWeekMask, and pcimTPCTimeOfDayMask) are all defined as octet strings in [1]. However, the semantics of each of these attributes are contained in Strassner, et al. Standards Track [Page 37] RFC 3703 Policy Core LDAP Schema February 2004 bit strings of various fixed lengths. Therefore, the PCLS uses a syntax of Bit String to represent each of them. The definition of these four attributes are as follows. The pcimTPCMonthOfYearMask attribute defines a 12-bit mask identifying the months of the year in which a policy rule is valid. The format is a bit string of length 12, representing the months of the year from January through December. The definition of this attribute is as follows: ( 1.3.6.1.1.6.2.26 NAME 'pcimTPCMonthOfYearMask' DESC 'This identifies the valid months of the year for a policy rule using a 12-bit string that represents the months of the year from January through December.' EQUALITY bitStringMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.6 SINGLE-VALUE ) The value of this attribute SHOULD be checked against its defined format. If the value of this attribute does not conform to this syntax, then this SHOULD be considered an error and the policy rule SHOULD be treated as being disabled. The pcimTPCMonthOfDayMask attribute defines a mask identifying the days of the month on which a policy rule is valid. The format is a bit string of length 62. The first 31 positions represent the days of the month in ascending order, from day 1 to day 31. The next 31 positions represent the days of the month in descending order, from the last day to the day 31 days from the end. The definition of this attribute is as follows: ( 1.3.6.1.1.6.2.27 NAME 'pcimTPCDayOfMonthMask' DESC 'This identifies the valid days of the month for a policy rule using a 62-bit string. The first 31 positions represent the days of the month in ascending order, and the next 31 positions represent the days of the month in descending order.' EQUALITY bitStringMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.6 SINGLE-VALUE ) Strassner, et al. Standards Track [Page 38] RFC 3703 Policy Core LDAP Schema February 2004 The value of this attribute SHOULD be checked against its defined format. If the value of this attribute does not conform to this syntax, then this SHOULD be considered an error and the policy rule SHOULD be treated as being disabled. The pcimTPCDayOfWeekMask attribute defines a mask identifying the days of the week on which a policy rule is valid. The format is a bit string of length 7, representing the days of the week from Sunday through Saturday. The definition of this attribute is as follows: ( 1.3.6.1.1.6.2.28 NAME 'pcimTPCDayOfWeekMask' DESC 'This identifies the valid days of the week for a policy rule using a 7-bit string. This represents the days of the week from Sunday through Saturday.' EQUALITY bitStringMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.6 SINGLE-VALUE ) The value of this attribute SHOULD be checked against its defined format. If the value of this attribute does not conform to this syntax, then this SHOULD be considered an error and the policy rule SHOULD be treated as being disabled. The pcimTPCTimeOfDayMask attribute defines the range of times at which a policy rule is valid. If the second time is earlier than the first, then the interval spans midnight. The format of the string is Thhmmss/Thhmmss. The definition of this attribute is as follows: ( 1.3.6.1.1.6.2.29 NAME 'pcimTPCTimeOfDayMask' DESC 'This identifies the valid range of times for a policy using the format Thhmmss/Thhmmss.' EQUALITY caseIgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.44 SINGLE-VALUE ) The value of this attribute SHOULD be checked against its defined format. If the value of this attribute does not conform to this syntax, then this SHOULD be considered an error and the policy rule SHOULD be treated as being disabled. Strassner, et al. Standards Track [Page 39] RFC 3703 Policy Core LDAP Schema February 2004 Finally, the pcimTPCLocalOrUtcTime attribute is used to choose between local or UTC time representation. This is mapped as a simple integer syntax, with the value of 1 representing local time and the value of 2 representing UTC time. The definition of this attribute is as follows: ( 1.3.6.1.1.6.2.30 NAME 'pcimTPCLocalOrUtcTime' DESC 'This defines whether the times in this instance represent local (value=1) times or UTC (value=2) times.' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) Note: if the value of the pcimTPCLocalOrUtcTime is not 1 or 2, then this SHOULD be considered an error and the policy rule SHOULD be disabled. If the attribute is not present at all, then all times are interpreted as if it were present with the value 2, that is, UTC time. 5.9. The Auxiliary Class pcimConditionVendorAuxClass This class provides a general extension mechanism for representing policy conditions that have not been modeled with specific properties. Instead, its two properties are used to define the content and format of the condition, as explained below. This class is intended for vendor-specific extensions that are not amenable to using pcimCondition; standardized extensions SHOULD NOT use this class. The class definition is as follows: ( 1.3.6.1.1.6.1.13 NAME 'pcimConditionVendorAuxClass' DESC 'A class that defines a registered means to describe a policy condition.' SUP pcimConditionAuxClass AUXILIARY MAY ( pcimVendorConstraintData $ pcimVendorConstraintEncoding ) ) The pcimVendorConstraintData attribute is a multi-valued attribute. It provides a general mechanism for representing policy conditions that have not been modeled as specific attributes. This information is encoded in a set of octet strings. The format of the octet Strassner, et al. Standards Track [Page 40] RFC 3703 Policy Core LDAP Schema February 2004 strings is identified by the OID stored in the pcimVendorConstraintEncoding attribute. This attribute is defined as follows: ( 1.3.6.1.1.6.2.31 NAME 'pcimVendorConstraintData' DESC 'Mechanism for representing constraints that have not been modeled as specific attributes. Their format is identified by the OID stored in the attribute pcimVendorConstraintEncoding.' EQUALITY octetStringMatch ORDERING octetStringOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.40 ) The pcimVendorConstraintEncoding attribute is used to identify the format and semantics for the pcimVendorConstraintData attribute. This attribute is defined as follows: ( 1.3.6.1.1.6.2.32 NAME 'pcimVendorConstraintEncoding' DESC 'An OID identifying the format and semantics for the pcimVendorConstraintData for this instance.' EQUALITY objectIdentifierMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 SINGLE-VALUE ) 5.10. The Auxiliary Class pcimActionAuxClass The purpose of a policy action is to execute one or more operations that will affect network traffic and/or systems, devices, etc. in order to achieve a desired policy state. This class is used to represent an action to be performed as a result of a policy rule whose condition clause was satisfied. Subclasses of this auxiliary class can be attached to instances of three other classes in the PCLS. When a subclass of this class is attached to an instance of pcimRuleActionAssociation, or to an instance of pcimRule, it represents a rule-specific policy action. When a subclass of this class is attached to an instance of pcimPolicyInstance, it represents a reusable policy action. Since all of the classes to which subclasses of this auxiliary class may be attached are derived from the pcimPolicy class, the attributes of the pcimPolicy class will already be defined for the entries to which these subclasses attach. Thus, this class is derived directly from "top". Strassner, et al. Standards Track [Page 41] RFC 3703 Policy Core LDAP Schema February 2004 The class definition is as follows: ( 1.3.6.1.1.6.1.14 NAME 'pcimActionAuxClass' DESC 'A class representing an action to be performed as a result of a policy rule.' SUP top AUXILIARY ) 5.11. The Auxiliary Class pcimActionVendorAuxClass The purpose of this class is to provide a general extension mechanism for representing policy actions that have not been modeled with specific properties. Instead, its two properties are used to define the content and format of the action, as explained below. As its name suggests, this class is intended for vendor-specific extensions that are not amenable to using the standard pcimAction class. Standardized extensions SHOULD NOT use this class. The class definition is as follows: ( 1.3.6.1.1.6.1.15 NAME 'pcimActionVendorAuxClass' DESC 'A class that defines a registered means to describe a policy action.' SUP pcimActionAuxClass AUXILIARY MAY ( pcimVendorActionData $ pcimVendorActionEncoding ) ) The pcimVendorActionData attribute is a multi-valued attribute. It provides a general mechanism for representing policy actions that have not been modeled as specific attributes. This information is encoded in a set of octet strings. The format of the octet strings is identified by the OID stored in the pcimVendorActionEncoding attribute. This attribute is defined as follows: ( 1.3.6.1.1.6.2.33 NAME 'pcimVendorActionData' DESC ' Mechanism for representing policy actions that have not been modeled as specific attributes. Their format is identified by the OID stored in the attribute pcimVendorActionEncoding.' EQUALITY octetStringMatch ORDERING octetStringOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.40 ) Strassner, et al. Standards Track [Page 42] RFC 3703 Policy Core LDAP Schema February 2004 The pcimVendorActionEncoding attribute is used to identify the format and semantics for the pcimVendorActionData attribute. This attribute is defined as follows: ( 1.3.6.1.1.6.2.34 NAME 'pcimVendorActionEncoding' DESC 'An OID identifying the format and semantics for the pcimVendorActionData attribute of this instance.' EQUALITY objectIdentifierMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 SINGLE-VALUE ) 5.12. The Class pcimPolicyInstance This class is not defined in the PCIM. Its role is to serve as a structural class to which auxiliary classes representing policy information are attached when the information is reusable. For auxiliary classes representing policy conditions and policy actions, there are alternative structural classes that may be used. See Section 4.4 for a complete discussion of reusable policy conditions and actions, and of the role that this class plays in how they are represented. The class definition is as follows: ( 1.3.6.1.1.6.1.16 NAME 'pcimPolicyInstance' DESC 'A structural class to which aux classes containing reusable policy information can be attached.' SUP pcimPolicy MAY ( pcimPolicyInstanceName ) ) The pcimPolicyInstanceName attribute is used to define a user-friendly name of this class, and may be used as a naming attribute if desired. It is defined as follows: ( 1.3.6.1.1.6.2.35 NAME 'pcimPolicyInstanceName' DESC 'The user-friendly name of this policy instance.' EQUALITY caseIgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) Strassner, et al. Standards Track [Page 43] RFC 3703 Policy Core LDAP Schema February 2004 A DIT content rule could be written to enable an instance of pcimPolicyInstance to have attached to it either instances of one or more of the auxiliary object classes pcimConditionAuxClass and pcimActionAuxClass. Since these semantics do not include specifying any properties, the content rule would not need to specify any attributes. Note that other content rules could be defined to enable other policy-related auxiliary classes to be attached to pcimPolicyInstance. Similarly, three separate DIT structure rules could be written. Each of these DIT structure rules would refer to a specific name form that defined two important semantics. First, each name form would identify one of the three possible naming attributes (i.e., pcimPolicyInstanceName, cn, and orderedCIMKeys) for this object class. Second, each name form would require that an instance of the pcimPolicyInstance class have as its superior an instance of the pcimRepository class. This structure rule SHOULD also include a superiorStructureRule (see Note 2 at the beginning of section 5). 5.13. The Auxiliary Class pcimElementAuxClass This class introduces no additional attributes, beyond those defined in the class pcimPolicy from which it is derived. Its role is to "tag" an instance of a class defined outside the realm of policy information as represented by PCIM as being nevertheless relevant to a policy specification. This tagging can potentially take place at two levels: - Every instance to which pcimElementAuxClass is attached becomes an instance of the class pcimPolicy, since pcimElementAuxClass is a subclass of pcimPolicy. Searching for object class="pcimPolicy" will return the instance. (As noted earlier, this approach does NOT work for some directory implementations. To accommodate these implementations, policy-related entries SHOULD be tagged with the pcimKeyword "POLICY".) - With the pcimKeywords attribute that it inherits from pcimPolicy, an instance to which pcimElementAuxClass is attached can be tagged as being relevant to a particular type or category of policy information, using standard keywords, administrator-defined keywords, or both. The class definition is as follows: ( 1.3.6.1.1.6.1.17 NAME 'pcimElementAuxClass' DESC 'An auxiliary class used to tag instances of classes defined outside the realm of policy as relevant to a particular policy specification.' Strassner, et al. Standards Track [Page 44] RFC 3703 Policy Core LDAP Schema February 2004 SUP pcimPolicy AUXILIARY ) 5.14. The Three Policy Repository Classes These classes provide a container for reusable policy information, such as reusable policy conditions and/or reusable policy actions. This document is concerned with mapping just the properties that appear in these classes. Conceptually, this may be thought of as a special location in the DIT where policy information may reside. Since pcimRepository is derived from the class dlm1AdminDomain defined in reference [6], this specification has a normative dependency on that element of reference [6] (as well as on its entire derivation hierarchy, which also appears in reference [6]). To maximize flexibility, the pcimRepository class is defined as abstract. A subclass pcimRepositoryAuxClass provides for auxiliary attachment to another entry, while a structural subclass pcimRepositoryInstance is available to represent a policy repository as a standalone entry. The definition for the pcimRepository class is as follows: ( 1.3.6.1.1.6.1.18 NAME 'pcimRepository' DESC 'A container for reusable policy information.' SUP dlm1AdminDomain ABSTRACT MAY ( pcimRepositoryName ) ) The pcimRepositoryName attribute is used to define a user-friendly name of this class, and may be used as a naming attribute if desired. It is defined as follows: ( 1.3.6.1.1.6.2.36 NAME 'pcimRepositoryName' DESC 'The user-friendly name of this policy repository.' EQUALITY caseIgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) Strassner, et al. Standards Track [Page 45] RFC 3703 Policy Core LDAP Schema February 2004 The two subclasses of pcimRepository are defined as follows. First, the pcimRepositoryAuxClass is an auxiliary class that can be used to aggregate reusable policy information. It is defined as follows: ( 1.3.6.1.1.6.1.19 NAME 'pcimRepositoryAuxClass' DESC 'An auxiliary class that can be used to aggregate reusable policy information.' SUP pcimRepository AUXILIARY ) In cases where structural classes are needed instead of an auxiliary class, the pcimRepositoryInstance class is a structural class that can be used to aggregate reusable policy information. It is defined as follows: ( 1.3.6.1.1.6.1.20 NAME 'pcimRepositoryInstance' DESC 'A structural class that can be used to aggregate reusable policy information.' SUP pcimRepository STRUCTURAL ) Three separate DIT structure rules could be written for this class. Each of these DIT structure rules would refer to a specific name form that enabled an instance of the pcimRepository class to be named under any superior using one of the three possible naming attributes (i.e., pcimRepositoryName, cn, and orderedCIMKeys). This structure rule SHOULD also include a superiorStructureRule (see Note 2 at the beginning of section 5). 5.15. The Auxiliary Class pcimSubtreesPtrAuxClass This auxiliary class provides a single, multi-valued attribute that references a set of objects that are at the root of DIT subtrees containing policy-related information. By attaching this attribute to instances of various other classes, a policy administrator has a flexible way of providing an entry point into the directory that allows a client to locate and retrieve the policy information relevant to it. It is intended that these entries are placed in the DIT such that well-known DNs can be used to reference a well-known structural entry that has the pcimSubtreesPtrAuxClass attached to it. In effect, this defines a set of entry points. Each of these entry points can contain and/or reference all related policy entries for Strassner, et al. Standards Track [Page 46] RFC 3703 Policy Core LDAP Schema February 2004 any well-known policy domains. The pcimSubtreesPtrAuxClass functions as a tag to identify portions of the DIT that contain policy information. This object does not provide the semantic linkages between individual policy objects, such as those between a policy group and the policy rules that belong to it. Its only role is to enable efficient bulk retrieval of policy-related objects, as described in Section 4.5. Once the objects have been retrieved, a directory client can determine the semantic linkages by following references contained in multi-valued attributes, such as pcimRulesAuxContainedSet. Since policy-related objects will often be included in the DIT subtree beneath an object to which this auxiliary class is attached, a client SHOULD request the policy-related objects from the subtree under the object with these references at the same time that it requests the references themselves. Since clients are expected to behave in this way, the policy administrator SHOULD make sure that this subtree does not contain so many objects unrelated to policy that an initial search done in this way results in a performance problem. The pcimSubtreesPtrAuxClass SHOULD NOT be attached to the partition root for a large directory partition containing a relatively few number of policy-related objects along with a large number of objects unrelated to policy (again, "policy" here refers to the PCIM, not the X.501, definition and use of "policy"). A better approach would be to introduce a container object immediately below the partition root, attach pcimSubtreesPtrAuxClass to this container object, and then place all of the policy-related objects in that subtree. The class definition is as follows: ( 1.3.6.1.1.6.1.21 NAME 'pcimSubtreesPtrAuxClass' DESC 'An auxiliary class providing DN references to roots of DIT subtrees containing policy-related objects.' SUP top AUXILIARY MAY ( pcimSubtreesAuxContainedSet ) ) Strassner, et al. Standards Track [Page 47] RFC 3703 Policy Core LDAP Schema February 2004 The attribute pcimSubtreesAuxContainedSet provides an unordered set of DN references to instances of one or more objects under which policy-related information is present. The objects referenced may or may not themselves contain policy-related information. The attribute definition is as follows: ( 1.3.6.1.1.6.2.37 NAME 'pcimSubtreesAuxContainedSet' DESC 'DNs of objects that serve as roots for DIT subtrees containing policy-related objects.' EQUALITY distinguishedNameMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 ) Note that the cn attribute does NOT need to be defined for this class. This is because an auxiliary class is used as a means to collect common attributes and treat them as properties of an object. A good analogy is a #include file, except that since an auxiliary class is a class, all the benefits of a class (e.g., inheritance) can be applied to an auxiliary class. 5.16. The Auxiliary Class pcimGroupContainmentAuxClass This auxiliary class provides a single, multi-valued attribute that references a set of pcimGroups. By attaching this attribute to instances of various other classes, a policy administrator has a flexible way of providing an entry point into the directory that allows a client to locate and retrieve the pcimGroups relevant to it. As is the case with pcimRules, a policy administrator might have several different references to a pcimGroup in the overall directory structure. The pcimGroupContainmentAuxClass is the mechanism that makes it possible for the policy administrator to define all these different references. The class definition is as follows: ( 1.3.6.1.1.6.1.22 NAME 'pcimGroupContainmentAuxClass' DESC 'An auxiliary class used to bind pcimGroups to an appropriate container object.' SUP top AUXILIARY MAY ( pcimGroupsAuxContainedSet ) ) Strassner, et al. Standards Track [Page 48] RFC 3703 Policy Core LDAP Schema February 2004 The attribute pcimGroupsAuxContainedSet provides an unordered set of references to instances of one or more pcimGroups associated with the instance of a structural class to which this attribute has been appended. The attribute definition is as follows: ( 1.3.6.1.1.6.2.38 NAME 'pcimGroupsAuxContainedSet' DESC 'DNs of pcimGroups associated in some way with the instance to which this attribute has been appended.' EQUALITY distinguishedNameMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 ) Note that the cn attribute does NOT have to be defined for this class for the same reasons as those given for the pcimSubtreesPtrAuxClass in section 5.15. 5.17. The Auxiliary Class pcimRuleContainmentAuxClass This auxiliary class provides a single, multi-valued attribute that references a set of pcimRules. By attaching this attribute to instances of various other classes, a policy administrator has a flexible way of providing an entry point into the directory that allows a client to locate and retrieve the pcimRules relevant to it. A policy administrator might have several different references to a pcimRule in the overall directory structure. For example, there might be references to all pcimRules for traffic originating in a particular subnet from a directory entry that represents that subnet. At the same time, there might be references to all pcimRules related to a particular DiffServ setting from an instance of a pcimGroup explicitly introduced as a container for DiffServ-related pcimRules. The pcimRuleContainmentAuxClass is the mechanism that makes it possible for the policy administrator to define all these separate references. The class definition is as follows: ( 1.3.6.1.1.6.1.23 NAME 'pcimRuleContainmentAuxClass' DESC 'An auxiliary class used to bind pcimRules to an appropriate container object.' SUP top AUXILIARY MAY ( pcimRulesAuxContainedSet ) ) Strassner, et al. Standards Track [Page 49] RFC 3703 Policy Core LDAP Schema February 2004 The attribute pcimRulesAuxContainedSet provides an unordered set of references to one or more instances of pcimRules associated with the instance of a structural class to which this attribute has been appended. The attribute definition is as follows: ( 1.3.6.1.1.6.2.39 NAME 'pcimRulesAuxContainedSet' DESC 'DNs of pcimRules associated in some way with the instance to which this attribute has been appended.' EQUALITY distinguishedNameMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 ) The cn attribute does NOT have to be defined for this class for the same reasons as those given for the pcimSubtreesPtrAuxClass in section 5.15. 6. Extending the Classes Defined in This Document The following subsections provide general guidance on how to create a domain-specific schema derived from this document, discuss how the vendor classes in the PCLS should be used, and explain how policyTimePeriodConditions are related to other policy conditions. 6.1. Subclassing pcimConditionAuxClass and pcimActionAuxClass In Section 4.4, there is a discussion of how, by representing policy conditions and policy actions as auxiliary classes in a schema, the flexibility is retained to instantiate a particular condition or action as either rule-specific or reusable. This flexibility is lost if a condition or action class is defined as structural rather than auxiliary. For standardized schemata, this document specifies that domain-specific information MUST be expressed in auxiliary subclasses of pcimConditionAuxClass and pcimActionAuxClass. It is RECOMMENDED that non-standardized schemata follow this practice as well. 6.2. Using the Vendor Policy Attributes As discussed Section 5.9, the attributes pcimVendorConstraintData and pcimVendorConstraintEncoding are included in the pcimConditionVendorAuxClass to provide a mechanism for representing vendor-specific policy conditions that are not amenable to being represented with the pcimCondition class (or its subclasses). The attributes pcimVendorActionData and pcimVendorActionEncoding in the pcimActionVendorAuxClass class play the same role with respect to actions. This enables interoperability between different vendors who could not otherwise interoperate. Strassner, et al. Standards Track [Page 50] RFC 3703 Policy Core LDAP Schema February 2004 For example, imagine a network composed of access devices from vendor A, edge and core devices from vendor B, and a policy server from vendor C. It is desirable for this policy server to be able to configure and manage all of the devices from vendors A and B. Unfortunately, these devices will in general have little in common (e.g., different mechanisms, different ways for controlling those mechanisms, different operating systems, different commands, and so forth). The extension conditions provide a way for vendor-specific commands to be encoded as octet strings, so that a single policy server can commonly manage devices from different vendors. 6.3. Using Time Validity Periods Time validity periods are defined as an auxiliary subclass of pcimConditionAuxClass, called pcimTPCAuxClass. This is to allow their inclusion in the AND/OR condition definitions for a pcimRule. Care should be taken not to subclass pcimTPCAuxClass to add domain-specific condition properties. For example, it would be incorrect to add IPsec- or QoS-specific condition properties to the pcimTPCAuxClass class, just because IPsec or QoS includes time in its condition definition. The correct subclassing would be to create IPsec or QoS-specific subclasses of pcimConditionAuxClass and then combine instances of these domain-specific condition classes with the appropriate validity period criteria. This is accomplished using the AND/OR association capabilities for policy conditions in pcimRules. 7. Security Considerations The PCLS, presented in this document, provides a mapping of the object-oriented model for describing policy information (PCIM) into a data model that forms the basic framework for describing the structure of policy data, in the case where the policy repository takes the form of an LDAP-accessible directory. PCLS is not intended to represent any particular system design or implementation. PCLS is not directly useable in a real world system, without the discipline-specific mappings that are works in progress in the Policy Framework Working Group of the IETF. These other derivative documents, which use PCIM and its discipline-specific extensions as a base, will need to convey more specific security considerations (refer to RFC 3060 for more information.) Strassner, et al. Standards Track [Page 51] RFC 3703 Policy Core LDAP Schema February 2004 The reason that PCLS, as defined here, is not representative of any real-world system, is that its object classes were designed to be independent of any specific discipline, or policy domain. For example, DiffServ and IPsec represent two different policy domains. Each document that extends PCIM to one of these domains will derive subclasses from the classes and relationships defined in PCIM, in order to represent extensions of a generic model to cover specific technical domains. PCIM-derived documents will thus subclass the PCIM classes into classes specific to each technical policy domain (QOS, IPsec, etc.), which will, in turn, be mapped, to directory-specific schemata consistent with the PCLS documented here. Even though discipline-specific security requirements are not appropriate for PCLS, specific security requirements MUST be defined for each operational real-world application of PCIM. Just as there will be a wide range of operational, real-world systems using PCIM, there will also be a wide range of security requirements for these systems. Some operational, real-world systems that are deployed using PCLS may have extensive security requirements that impact nearly all object classes utilized by such a system, while other systems' security requirements might have very little impact. The derivative documents, discussed above, will create the context for applying operational, real-world, system-level security requirements against the various models that derive from PCIM, consistent with PCLS. In some real-world scenarios, the values associated with certain properties, within certain instantiated object classes, may represent information associated with scarce, and/or costly (and therefore valuable) resources. It may be the case that these values must not be disclosed to, or manipulated by, unauthorized parties. Since this document forms the basis for the representation of a policy data model in a specific format (an LDAP-accessible directory), it is herein appropriate to reference the data model-specific tools and mechanisms that are available for achieving the authentication and authorization implicit in a requirement that restricts read and/or read- write access to these values stored in a directory. Strassner, et al. Standards Track [Page 52] RFC 3703 Policy Core LDAP Schema February 2004 General LDAP security considerations apply, as documented in RFC 3377 [2]. LDAP-specific authentication and authorization tools and mechanisms are found in the following standards track documents, which are appropriate for application to the management of security applied to policy data models stored in an LDAP-accessible directory: - RFC 2829 (Authentication Methods for LDAP) - RFC 2830 (Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security) Any identified security requirements that are not dealt with in the appropriate discipline-specific information model documents, or in this document, MUST be dealt with in the derivative data model documents which are specific to each discipline. 8. IANA Considerations Refer to RFC 3383, "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)" [16]. 8.1. Object Identifiers The IANA has registered an LDAP Object Identifier for use in this technical specification according to the following template: Subject: Request for LDAP OID Registration Person & email address to contact for further information: Bob Moore (remoore@us.ibm.com) Specification: RFC 3703 Author/Change Controller: IESG Comments: The assigned OID will be used as a base for identifying a number of schema elements defined in this document. IANA has assigned an OID of 1.3.6.1.1.6 with the name of pcimSchema to this registration as recorded in the following registry: http://www.iana.org/assignments/smi-numbers 8.2. Object Identifier Descriptors The IANA has registered the LDAP Descriptors used in this technical specification as detailed in the following template: Subject: Request for LDAP Descriptor Registration Update Descriptor (short name): see comment Object Identifier: see comment Strassner, et al. Standards Track [Page 53] RFC 3703 Policy Core LDAP Schema February 2004 Person & email address to contact for further information: Bob Moore (remoore@us.ibm.com) Usage: see comment Specification: RFC 3703 Author/Change Controller: IESG Comments: The following descriptors have been added: NAME Type OID -------------- ---- ------------ pcimPolicy O 1.3.6.1.1.6.1.1 pcimGroup O 1.3.6.1.1.6.1.2 pcimGroupAuxClass O 1.3.6.1.1.6.1.3 pcimGroupInstance O 1.3.6.1.1.6.1.4 pcimRule O 1.3.6.1.1.6.1.5 pcimRuleAuxClass O 1.3.6.1.1.6.1.6 pcimRuleInstance O 1.3.6.1.1.6.1.7 pcimRuleConditionAssociation O 1.3.6.1.1.6.1.8 pcimRuleValidityAssociation O 1.3.6.1.1.6.1.9 pcimRuleActionAssociation O 1.3.6.1.1.6.1.10 pcimConditionAuxClass O 1.3.6.1.1.6.1.11 pcimTPCAuxClass O 1.3.6.1.1.6.1.12 pcimConditionVendorAuxClass O 1.3.6.1.1.6.1.13 pcimActionAuxClass O 1.3.6.1.1.6.1.14 pcimActionVendorAuxClass O 1.3.6.1.1.6.1.15 pcimPolicyInstance O 1.3.6.1.1.6.1.16 pcimElementAuxClass O 1.3.6.1.1.6.1.17 pcimRepository O 1.3.6.1.1.6.1.18 pcimRepositoryAuxClass O 1.3.6.1.1.6.1.19 pcimRepositoryInstance O 1.3.6.1.1.6.1.20 pcimSubtreesPtrAuxClass O 1.3.6.1.1.6.1.21 pcimGroupContainmentAuxClass O 1.3.6.1.1.6.1.22 pcimRuleContainmentAuxClass O 1.3.6.1.1.6.1.23 pcimKeywords A 1.3.6.1.1.6.2.3 pcimGroupName A 1.3.6.1.1.6.2.4 pcimRuleName A 1.3.6.1.1.6.2.5 pcimRuleEnabled A 1.3.6.1.1.6.2.6 pcimRuleConditionListType A 1.3.6.1.1.6.2.7 pcimRuleConditionList A 1.3.6.1.1.6.2.8 pcimRuleActionList A 1.3.6.1.1.6.2.9 pcimRuleValidityPeriodList A 1.3.6.1.1.6.2.10 pcimRuleUsage A 1.3.6.1.1.6.2.11 pcimRulePriority A 1.3.6.1.1.6.2.12 pcimRuleMandatory A 1.3.6.1.1.6.2.13 pcimRuleSequencedActions A 1.3.6.1.1.6.2.14 pcimRoles A 1.3.6.1.1.6.2.15 pcimConditionGroupNumber A 1.3.6.1.1.6.2.16 Strassner, et al. Standards Track [Page 54] RFC 3703 Policy Core LDAP Schema February 2004 NAME Type OID -------------- ---- ------------ pcimConditionNegated A 1.3.6.1.1.6.2.17 pcimConditionName A 1.3.6.1.1.6.2.18 pcimConditionDN A 1.3.6.1.1.6.2.19 pcimValidityConditionName A 1.3.6.1.1.6.2.20 pcimTimePeriodConditionDN A 1.3.6.1.1.6.2.21 pcimActionName A 1.3.6.1.1.6.2.22 pcimActionOrder A 1.3.6.1.1.6.2.23 pcimActionDN A 1.3.6.1.1.6.2.24 pcimTPCTime A 1.3.6.1.1.6.2.25 pcimTPCMonthOfYearMask A 1.3.6.1.1.6.2.26 pcimTPCDayOfMonthMask A 1.3.6.1.1.6.2.27 pcimTPCDayOfWeekMask A 1.3.6.1.1.6.2.28 pcimTPCTimeOfDayMask A 1.3.6.1.1.6.2.29 pcimTPCLocalOrUtcTime A 1.3.6.1.1.6.2.30 pcimVendorConstraintData A 1.3.6.1.1.6.2.31 pcimVendorConstraintEncoding A 1.3.6.1.1.6.2.32 pcimVendorActionData A 1.3.6.1.1.6.2.33 pcimVendorActionEncoding A 1.3.6.1.1.6.2.34 pcimPolicyInstanceName A 1.3.6.1.1.6.2.35 pcimRepositoryName A 1.3.6.1.1.6.2.36 pcimSubtreesAuxContainedSet A 1.3.6.1.1.6.2.37 pcimGroupsAuxContainedSet A 1.3.6.1.1.6.2.38 pcimRulesAuxContainedSet A 1.3.6.1.1.6.2.39 where Type A is Attribute, Type O is ObjectClass These assignments are recorded in the following registry: http://www.iana.org/assignments/ldap-parameters Strassner, et al. Standards Track [Page 55] RFC 3703 Policy Core LDAP Schema February 2004 9. Acknowledgments We would like to thank Kurt Zeilenga, Roland Hedburg, and Steven Legg for doing a review of this document and making many helpful suggestions and corrections. Several of the policy classes in this model first appeared in early IETF drafts on IPsec policy and QoS policy. The authors of these drafts were Partha Bhattacharya, Rob Adams, William Dixon, Roy Pereira, Raju Rajan, Jean-Christophe Martin, Sanjay Kamat, Michael See, Rajiv Chaudhury, Dinesh Verma, George Powers, and Raj Yavatkar. This document is closely aligned with the work being done in the Distributed Management Task Force (DMTF) Policy and Networks working groups. We would especially like to thank Lee Rafalow, Glenn Waters, David Black, Michael Richardson, Mark Stevens, David Jones, Hugh Mahon, Yoram Snir, and Yoram Ramberg for their helpful comments. Strassner, et al. Standards Track [Page 56] RFC 3703 Policy Core LDAP Schema February 2004 10. Appendix: Constructing the Value of orderedCIMKeys This appendix is non-normative, and is included in this document as a guide to implementers that wish to exchange information between CIM schemata and LDAP schemata. Within a CIM name space, the naming is basically flat; all instances are identified by the values of their key properties, and each combination of key values must be unique. A limited form of hierarchical naming is available in CIM, however, by using weak associations: since a weak association involves propagation of key properties and their values from the superior object to the subordinate one, the subordinate object can be thought of as being named "under" the superior object. Once they have been propagated, however, propagated key properties and their values function in exactly the same way that native key properties and their values do in identifying a CIM instance. The CIM mapping document [6] introduces a special attribute, orderedCIMKeys, to help map from the CIM_ManagedElement class to the LDAP class dlm1ManagedElement. This attribute SHOULD only be used in an environment where it is necessary to map between an LDAP-accessible directory and a CIM repository. For an LDAP environment, other LDAP naming attributes are defined (i.e., cn and a class-specific naming attribute) that SHOULD be used instead. The role of orderedCIMKeys is to represent the information necessary to correlate an entry in an LDAP-accessible directory with an instance in a CIM name space. Depending on how naming of CIM-related entries is handled in an LDAP directory, the value of orderedCIMKeys represents one of two things: - If the DIT hierarchy does not mirror the "weakness hierarchy" of the CIM name space, then orderedCIMKeys represents all the keys of the CIM instance, both native and propagated. - If the DIT hierarchy does mirror the "weakness hierarchy" of the CIM name space, then orderedCIMKeys may represent either all the keys of the instance, or only the native keys. Regardless of which of these alternatives is taken, the syntax of orderedCIMKeys is the same - a DirectoryString of the form <className>.<key>=<value>[,<key>=<value>]* where the <key>=<value> elements are ordered by the names of the key properties, according to the collating sequence for US ASCII. The only spaces allowed in the DirectoryString are those that fall within a <value> element. As with alphabetizing the key properties, the Strassner, et al. Standards Track [Page 57] RFC 3703 Policy Core LDAP Schema February 2004 goal of suppressing the spaces is once again to make the results of string operations predictable. The values of the <value> elements are derived from the various CIM syntaxes according to a grammar specified in [5]. 11. References 11.1. Normative References [1] Moore, B., Ellesson,E., Strassner, J. and A. Westerinen "Policy Core Information Model -- Version 1 Specification", RFC 3060, February 2001. [2] Hodges, J. and R. Morgan, "Lightweight Directory Access Protocol (v3): Technical Specification", RFC 3377, September 2002. [3] Wahl, M., Coulbeck, A., Howes,T. and S. Kille, "Lightweight Directory Access Protocol (v3): Attribute Syntax Definitions", RFC 2252, December 1997. [4] The Directory: Models. ITU-T Recommendation X.501, 2001. [5] Distributed Management Task Force, Inc., "Common Information Model (CIM) Specification", Version 2.2, June 14, 1999. This document is available on the following DMTF web page: http://www.dmtf.org/standards/documents/CIM/DSP0004.pdf [6] Distributed Management Task Force, Inc., "DMTF LDAP Schema for the CIM v2.5 Core Information Model", April 15, 2002. This document is available on the following DMTF web page: http://www.dmtf.org/standards/documents/DEN/DSP0123.pdf [7] Wahl, M., "A Summary of the X.500(96) User Schema for use with LDAPv3", RFC 2256, December 1997. [8] The Directory: Selected Attribute Types. ITU-T Recommendation X.520, 2001. [9] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Additional Matching Rules", RFC 3698, February 2004. [10] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. Strassner, et al. Standards Track [Page 58] RFC 3703 Policy Core LDAP Schema February 2004 11.2. Informative References [11] Hovey, R. and S. Bradner, "The Organizations Involved in the IETF Standards Process", BCP 11, RFC 2028, October 1996. [12] Strassner, J., policy architecture BOF presentation, 42nd IETF Meeting, Chicago, Illinois, October 1998. Minutes of this BOF are available at the following location: http://www.ietf.org/proceedings/98aug/index.html. [13] Yavatkar, R., Guerin, R. and D. Pendarakis, "A Framework for Policy-based Admission Control", RFC 2753, January 2000. [14] Wahl, M., Alvestrand, H., Hodges, J. and R. Morgan, "Authentication Methods for LDAP", RFC 2829, May 2000 [15] Hodges, J., Morgan, R. and M. Wahl, "Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security", RFC 2830, May 2000. [16] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 3383, September 2002. Strassner, et al. Standards Track [Page 59] RFC 3703 Policy Core LDAP Schema February 2004 12. Authors' Addresses John Strassner Intelliden Corporation 90 South Cascade Avenue Colorado Springs, CO 80903 Phone: +1.719.785.0648 Fax: +1.719.785.0644 EMail: john.strassner@intelliden.com Bob Moore IBM Corporation P. O. Box 12195, BRQA/B501/G206 3039 Cornwallis Rd. Research Triangle Park, NC 27709-2195 Phone: +1 919-254-4436 Fax: +1 919-254-6243 EMail: remoore@us.ibm.com Ryan Moats Lemur Networks, Inc. 15621 Drexel Circle Omaha, NE 68135 Phone: +1-402-894-9456 EMail: rmoats@lemurnetworks.net Ed Ellesson 3026 Carriage Trail Hillsborough, NC 27278 Phone: +1 919-644-3977 EMail: ellesson@mindspring.com Strassner, et al. Standards Track [Page 60] RFC 3703 Policy Core LDAP Schema February 2004 13. Full Copyright Statement Copyright (C) The Internet Society (2004). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Strassner, et al. Standards Track [Page 61] PK +�c\��W��B �B ( doc/alt-openldap11-devel/rfc/rfc3112.txtnu �[��� Network Working Group K. Zeilenga Request for Comments: 3112 OpenLDAP Foundation Category: Informational May 2001 LDAP Authentication Password Schema Status of this Memo This memo provides information for the Internet community. It does not specify an Internet standard of any kind. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2001). All Rights Reserved. Abstract This document describes schema in support of user/password authentication in a LDAP (Lightweight Directory Access Protocol) directory including the authPassword attribute type. This attribute type holds values derived from the user's password(s) (commonly using cryptographic strength one-way hash). authPassword is intended to used instead of userPassword. 1. Background and Intended Use The userPassword attribute type [RFC2256] is intended to be used to support the LDAP [RFC2251] "simple" bind operation. However, values of userPassword must be clear text passwords. It is often desirable to store values derived from the user's password(s) instead of actual passwords. The authPassword attribute type is intended to be used to store information used to implement simple password based authentication. The attribute type may be used by LDAP servers to implement the LDAP Bind operation's "simple" authentication method. The attribute type supports multiple storage schemes. A matching rule is provided for use with extensible search filters to allow clients to assert that a clear text password "matches" one of the attribute's values. Storage schemes often use cryptographic strength one-way hashing. Though the use of one-way hashing reduces the potential that exposed values will allow unauthorized access to the Directory (unless the Zeilenga Informational [Page 1] RFC 3112 LDAP Authentication Password Schema May 2001 hash algorithm/implementation is flawed), the hashing of passwords is intended to be as an additional layer of protection. It is RECOMMENDED that hashed values be protected as if they were clear text passwords. This attribute may be used in conjunction with server side password generation mechanisms (such as the LDAP Password Modify [RFC3062] extended operation). Access to this attribute may governed by administrative controls such as those which implement password change policies. 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 [RFC2119]. 2. Schema Definitions The following schema definitions are described in terms of LDAPv3 Attribute Syntax Definitions [RFC2252] with specific syntax detailed using Augmented BNF [RFC2234]. 2.1. authPasswordSyntax ( 1.3.6.1.4.1.4203.1.1.2 DESC 'authentication password syntax' ) Values of this syntax are encoded according to: authPasswordValue = w scheme s authInfo s authValue w scheme = %x30-39 / %x41-5A / %x2D-2F / %x5F ; 0-9, A-Z, "-", ".", "/", or "_" authInfo = schemeSpecificValue authValue = schemeSpecificValue schemeSpecificValue = *( %x21-23 / %x25-7E ) ; printable ASCII less "$" and " " s = w SEP w w = *SP SEP = %x24 ; "$" SP = %x20 ; " " (space) where scheme describes the mechanism and authInfo and authValue are a scheme specific. The authInfo field is often a base64 encoded salt. The authValue field is often a base64 encoded value derived from a user's password(s). Values of this attribute are case sensitive. Zeilenga Informational [Page 2] RFC 3112 LDAP Authentication Password Schema May 2001 Transfer of values of this syntax is strongly discouraged where the underlying transport service cannot guarantee confidentiality and may result in disclosure of the values to unauthorized parties. This document describes a number of schemes, as well as requirements for the scheme naming, in section 3. 2.2. authPasswordExactMatch ( 1.3.6.1.4.1.4203.1.2.2 NAME 'authPasswordExactMatch' DESC 'authentication password exact matching rule' SYNTAX 1.3.6.1.4.1.4203.1.1.2 ) This matching rule allows a client to assert that an asserted authPasswordSyntax value matches authPasswordSyntax values. It is meant to be used as the EQUALITY matching rule of attributes whose SYNTAX is authPasswordSyntax. The assertion is "TRUE" if there is an attribute value which has the same scheme, authInfo, and authValue components as the asserted value; "FALSE" if no attribute value has the same components as the asserted value; and "Undefined" otherwise. 2.3. authPasswordMatch ( 1.3.6.1.4.1.4203.1.2.3 NAME 'authPasswordMatch' DESC 'authentication password matching rule' SYNTAX 1.3.6.1.4.1.1466.115.121.1.40{128} ) This matching rule allows a client to assert that a password matches values of authPasswordSyntax using an extensibleMatch filter component. Each value is matched per its scheme. The assertion is "TRUE" if one or more attribute values matches the asserted value, "FALSE" if all values do not matches, and "Undefined" otherwise. Servers which support use of this matching rule SHOULD publish appropriate matchingRuleUse values per [RFC2252], 4.4. Transfer of authPasswordMatch assertion values is strongly discouraged where the underlying transport service cannot guarantee confidentiality and may result in disclosure of the values to unauthorized parties. Zeilenga Informational [Page 3] RFC 3112 LDAP Authentication Password Schema May 2001 2.4. supportedAuthPasswordSchemes ( 1.3.6.1.4.1.4203.1.3.3 NAME 'supportedAuthPasswordSchemes' DESC 'supported password storage schemes' EQUALITY caseExactIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26{32} USAGE dSAOperation ) The values of this attribute are names of supported authentication password schemes which the server supports. The syntax of a scheme name is described in section 2.1. This attribute may only be present in the root DSE. If the server does not support any password schemes, this attribute will not be present. 2.5. authPassword ( 1.3.6.1.4.1.4203.1.3.4 NAME 'authPassword' DESC 'password authentication information' EQUALITY 1.3.6.1.4.1.4203.1.2.2 SYNTAX 1.3.6.1.4.1.4203.1.1.2 ) The values of this attribute are representative of the user's password(s) and conform to the authPasswordSyntax described in 2.1. The values of this attribute may be used for authentication purposes. Transfer of authPassword values is strongly discouraged where the underlying transport service cannot guarantee confidentiality and may result in disclosure of the values to unauthorized parties. 2.6. authPasswordObject ( 1.3.6.1.4.1.4203.1.4.7 NAME 'authPasswordObject' DESC 'authentication password mix in class' MAY 'authPassword' AUXILIARY ) Entries of this object class may contain authPassword attribute types. 3. Schemes This section describes the "MD5" and "SHA1" schemes. Other schemes may be defined by other documents. Schemes which are not described in an RFC SHOULD be named with a leading "X-" to indicate they are a private or implementation specific scheme, or may be named using the dotted-decimal representation [RFC2252] of an OID assigned to the scheme. Zeilenga Informational [Page 4] RFC 3112 LDAP Authentication Password Schema May 2001 3.1. MD5 scheme The MD5 [RFC1321] scheme name is "MD5". The authValue is the base64 encoding of an MD5 digest of the concatenation the user password and salt. The base64 encoding of the salt is provided in the authInfo field. The salt MUST be at least 64 bits long. Implementations of this scheme MUST support salts up to 128 bits in length. Example: Given a user "joe" who's password is "mary" and a salt of "salt", the authInfo field would be the base64 encoding of "salt" and the authValue field would be the base64 encoding of the MD5 digest of "marysalt". A match against an asserted password and an attribute value of this scheme SHALL be true if and only if the MD5 digest of concatenation of the asserted value and the salt is equal to the MD5 digest contained in AuthValue. The match SHALL be undefined if the server is unable to complete the equality test for any reason. Otherwise the match SHALL be false. Values of this scheme SHOULD only be used to implement simple user/password authentication. 3.2. SHA1 scheme The SHA1 [SHA1] scheme name is "SHA1". The authValue is the base64 encoding of a SHA1 digest of the concatenation the user password and the salt. The base64 encoding of the salt is provided in the authInfo field. The salt MUST be at least 64 bits long. Implementations of this scheme MUST support salts up to 128 bits in length. Example: Given a user "joe" who's password is "mary" and a salt of "salt", the authInfo field would be the base64 encoding of "salt" and the authValue field would be the base64 encoding of the SHA1 digest of "marysalt". A match against an asserted password and an attribute value of this scheme SHALL be true if and only if the SHA1 digest of concatenation of the asserted value and the salt is equal to the SHA1 digest contained in AuthValue. The match SHALL be undefined if the server is unable to complete the equality test for any reason. Otherwise the match SHALL be false. Zeilenga Informational [Page 5] RFC 3112 LDAP Authentication Password Schema May 2001 Values of this scheme SHOULD only be used to implement simple user/password authentication. 4. Implementation Issues For all implementations of this specification: Servers MAY restrict which schemes are used in conjunction with a particular authentication process but SHOULD use all values of selected schemes. If the asserted password matches any of the stored values, the asserted password SHOULD be considered valid. Servers MAY use other authentication storage mechanisms, such as userPassword or an external password store, in conjunction with authPassword to support the authentication process. Servers that support simple bind MUST support the SHA1 scheme and SHOULD support the MD5 scheme. Servers SHOULD NOT publish values of authPassword nor allow operations which expose authPassword values or AuthPasswordMatch assertions to unless confidentiality protection is in place. Clients SHOULD NOT initiate operations which provide or request values of authPassword or make authPasswordMatch assertions unless confidentiality protection is in place. Clients SHOULD NOT assume that a successful AuthPasswordMatch, whether by compare or search, is sufficient to gain directory access. The bind operation MUST be used to authenticate to the directory. 5. Security Considerations This document describes how authentication information may be stored in a directory. Authentication information MUST be adequately protected as unintended disclosure will allow attackers to gain immediate access to the directory as described by [RFC2829]. As flaws may be discovered in the hashing algorithm or with a particular implementation of the algorithm or values could be subject to various attacks if exposed, values of AuthPassword SHOULD be protected as if they were clear text passwords. When values are transferred, privacy protections, such as IPSEC or TLS, SHOULD be in place. Clients SHOULD use strong authentication mechanisms [RFC2829]. Zeilenga Informational [Page 6] RFC 3112 LDAP Authentication Password Schema May 2001 AuthPasswordMatch matching rule allows applications to test the validity of a user password and, hence, may be used to mount an attack. Servers SHOULD take appropriate measures to protect the directory from such attacks. Some password schemes may require CPU intensive operations. Servers SHOULD take appropriate measures to protect against Denial of Service attacks. AuthPassword does not restrict an authentication identity to a single password. An attacker who gains write access to this attribute may store additional values without disabling the user's true password(s). Use of policy aware clients and servers is RECOMMENDED. The level of protection offered against various attacks differ from scheme to scheme. It is RECOMMENDED that servers support scheme selection as a configuration item. This allows for a scheme to be easily disabled if a significant security flaw is discovered. 6. Acknowledgment This document borrows from a number of IETF documents and is based upon input from the IETF LDAPext working group. 7. Bibliography [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, April 1992 [RFC2219] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2234] Crocker, D., Editor, P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, November 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. [RFC2256] Wahl, A., "A Summary of the X.500(96) User Schema for use with LDAPv3", RFC 2256, December 1997. [RFC2307] Howard, L., "An Approach for Using LDAP as a Network Information Service", RFC 2307, March 1998. Zeilenga Informational [Page 7] RFC 3112 LDAP Authentication Password Schema May 2001 [RFC2829] Wahl, M., Alvestrand, H., Hodges, J. and R. Morgan, "Authentication Methods for LDAP", RFC 2829, June 2000. [RFC3062] Zeilenga, K., "LDAP Password Modify Extended Operation", RFC 3062, February 2001. [SHA1] NIST, FIPS PUB 180-1: Secure Hash Standard, April 1995. 8. Author's Address Kurt D. Zeilenga OpenLDAP Foundation EMail: Kurt@OpenLDAP.org Zeilenga Informational [Page 8] RFC 3112 LDAP Authentication Password Schema May 2001 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 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. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Zeilenga Informational [Page 9] PK +�c\�[81Y� Y� ( doc/alt-openldap11-devel/rfc/rfc4512.txtnu �[��� Network Working Group K. Zeilenga Request for Comments: 4512 OpenLDAP Foundation Obsoletes: 2251, 2252, 2256, 3674 June 2006 Category: Standards Track Lightweight Directory Access Protocol (LDAP): Directory Information Models Status of This Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2006). Abstract The Lightweight Directory Access Protocol (LDAP) is an Internet protocol for accessing distributed directory services that act in accordance with X.500 data and service models. This document describes the X.500 Directory Information Models, as used in LDAP. Zeilenga Standards Track [Page 1] RFC 4512 LDAP Models June 2006 Table of Contents 1. Introduction ....................................................3 1.1. Relationship to Other LDAP Specifications ..................3 1.2. Relationship to X.501 ......................................4 1.3. Conventions ................................................4 1.4. Common ABNF Productions ....................................4 2. Model of Directory User Information .............................6 2.1. The Directory Information Tree .............................7 2.2. Structure of an Entry ......................................7 2.3. Naming of Entries ..........................................8 2.4. Object Classes .............................................9 2.5. Attribute Descriptions ....................................12 2.6. Alias Entries .............................................16 3. Directory Administrative and Operational Information ...........17 3.1. Subtrees ..................................................17 3.2. Subentries ................................................18 3.3. The 'objectClass' attribute ...............................18 3.4. Operational Attributes ....................................19 4. Directory Schema ...............................................22 4.1. Schema Definitions ........................................23 4.2. Subschema Subentries ......................................32 4.3. 'extensibleObject' object class ...........................35 4.4. Subschema Discovery .......................................35 5. DSA (Server) Informational Model ...............................36 5.1. Server-Specific Data Requirements .........................36 6. Other Considerations ...........................................40 6.1. Preservation of User Information ..........................40 6.2. Short Names ...............................................41 6.3. Cache and Shadowing .......................................41 7. Implementation Guidelines ......................................42 7.1. Server Guidelines .........................................42 7.2. Client Guidelines .........................................42 8. Security Considerations ........................................43 9. IANA Considerations ............................................43 10. Acknowledgements ..............................................44 11. Normative References ..........................................45 Appendix A. Changes ...............................................47 A.1. Changes to RFC 2251 .......................................47 A.2. Changes to RFC 2252 .......................................49 A.3. Changes to RFC 2256 .......................................50 A.4. Changes to RFC 3674 .......................................51 Zeilenga Standards Track [Page 2] RFC 4512 LDAP Models June 2006 1. Introduction This document discusses the X.500 Directory Information Models [X.501], as used by the Lightweight Directory Access Protocol (LDAP) [RFC4510]. The Directory is "a collection of open systems cooperating to provide directory services" [X.500]. The information held in the Directory is collectively known as the Directory Information Base (DIB). A Directory user, which may be a human or other entity, accesses the Directory through a client (or Directory User Agent (DUA)). The client, on behalf of the directory user, interacts with one or more servers (or Directory System Agents (DSA)). A server holds a fragment of the DIB. The DIB contains two classes of information: 1) user information (e.g., information provided and administrated by users). Section 2 describes the Model of User Information. 2) administrative and operational information (e.g., information used to administer and/or operate the directory). Section 3 describes the model of Directory Administrative and Operational Information. These two models, referred to as the generic Directory Information Models, describe how information is represented in the Directory. These generic models provide a framework for other information models. Section 4 discusses the subschema information model and subschema discovery. Section 5 discusses the DSA (Server) Informational Model. Other X.500 information models (such as access control distribution knowledge and replication knowledge information models) may be adapted for use in LDAP. Specification of how these models apply to LDAP is left to future documents. 1.1. Relationship to Other LDAP Specifications This document is a integral part of the LDAP technical specification [RFC4510], which obsoletes the previously defined LDAP technical specification, RFC 3377, in its entirety. This document obsoletes RFC 2251, Sections 3.2 and 3.4, as well as portions of Sections 4 and 6. Appendix A.1 summarizes changes to these sections. The remainder of RFC 2251 is obsoleted by the [RFC4511], [RFC4513], and [RFC4510] documents. Zeilenga Standards Track [Page 3] RFC 4512 LDAP Models June 2006 This document obsoletes RFC 2252, Sections 4, 5, and 7. Appendix A.2 summarizes changes to these sections. The remainder of RFC 2252 is obsoleted by [RFC4517]. This document obsoletes RFC 2256, Sections 5.1, 5.2, 7.1, and 7.2. Appendix A.3 summarizes changes to these sections. The remainder of RFC 2256 is obsoleted by [RFC4519] and [RFC4517]. This document obsoletes RFC 3674 in its entirety. Appendix A.4 summarizes changes since RFC 3674. 1.2. Relationship to X.501 This document includes material, with and without adaptation, from [X.501] as necessary to describe this protocol. These adaptations (and any other differences herein) apply to this protocol, and only this protocol. 1.3. Conventions 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 (as defined in Section 4.1). Definitions provided here are formatted (line wrapped) for readability. Matching rules and LDAP syntaxes referenced in these definitions are specified in [RFC4517]. 1.4. Common ABNF Productions A number of syntaxes in this document are described using Augmented Backus-Naur Form (ABNF) [RFC4234]. These syntaxes (as well as a number of syntaxes defined in other documents) rely on the following common productions: keystring = leadkeychar *keychar leadkeychar = ALPHA keychar = ALPHA / DIGIT / HYPHEN number = DIGIT / ( LDIGIT 1*DIGIT ) ALPHA = %x41-5A / %x61-7A ; "A"-"Z" / "a"-"z" DIGIT = %x30 / LDIGIT ; "0"-"9" LDIGIT = %x31-39 ; "1"-"9" HEX = DIGIT / %x41-46 / %x61-66 ; "0"-"9" / "A"-"F" / "a"-"f" SP = 1*SPACE ; one or more " " WSP = 0*SPACE ; zero or more " " Zeilenga Standards Track [Page 4] RFC 4512 LDAP Models June 2006 NULL = %x00 ; null (0) SPACE = %x20 ; space (" ") DQUOTE = %x22 ; quote (""") SHARP = %x23 ; octothorpe (or sharp sign) ("#") DOLLAR = %x24 ; dollar sign ("$") SQUOTE = %x27 ; single quote ("'") LPAREN = %x28 ; left paren ("(") RPAREN = %x29 ; right paren (")") PLUS = %x2B ; plus sign ("+") COMMA = %x2C ; comma (",") HYPHEN = %x2D ; hyphen ("-") DOT = %x2E ; period (".") SEMI = %x3B ; semicolon (";") LANGLE = %x3C ; left angle bracket ("<") EQUALS = %x3D ; equals sign ("=") RANGLE = %x3E ; right angle bracket (">") ESC = %x5C ; backslash ("\") USCORE = %x5F ; underscore ("_") LCURLY = %x7B ; left curly brace "{" RCURLY = %x7D ; right curly brace "}" ; Any UTF-8 [RFC3629] encoded Unicode [Unicode] character UTF8 = UTF1 / UTFMB UTFMB = UTF2 / UTF3 / UTF4 UTF0 = %x80-BF UTF1 = %x00-7F UTF2 = %xC2-DF UTF0 UTF3 = %xE0 %xA0-BF UTF0 / %xE1-EC 2(UTF0) / %xED %x80-9F UTF0 / %xEE-EF 2(UTF0) UTF4 = %xF0 %x90-BF 2(UTF0) / %xF1-F3 3(UTF0) / %xF4 %x80-8F 2(UTF0) OCTET = %x00-FF ; Any octet (8-bit data unit) Object identifiers (OIDs) [X.680] are represented in LDAP using a dot-decimal format conforming to the ABNF: numericoid = number 1*( DOT number ) Short names, also known as descriptors, are used as more readable aliases for object identifiers. Short names are case insensitive and conform to the ABNF: descr = keystring Zeilenga Standards Track [Page 5] RFC 4512 LDAP Models June 2006 Where either an object identifier or a short name may be specified, the following production is used: oid = descr / numericoid While the <descr> form is generally preferred when the usage is restricted to short names referring to object identifiers that identify like kinds of objects (e.g., attribute type descriptions, matching rule descriptions, object class descriptions), the <numericoid> form should be used when the object identifiers may identify multiple kinds of objects or when an unambiguous short name (descriptor) is not available. Implementations SHOULD treat short names (descriptors) used in an ambiguous manner (as discussed above) as unrecognized. Short Names (descriptors) are discussed further in Section 6.2. 2. Model of Directory User Information As [X.501] states: The purpose of the Directory is to hold, and provide access to, information about objects of interest (objects) in some 'world'. An object can be anything which is identifiable (can be named). An object class is an identified family of objects, or conceivable objects, which share certain characteristics. Every object belongs to at least one class. An object class may be a subclass of other object classes, in which case the members of the former class, the subclass, are also considered to be members of the latter classes, the superclasses. There may be subclasses of subclasses, etc., to an arbitrary depth. A directory entry, a named collection of information, is the basic unit of information held in the Directory. There are multiple kinds of directory entries. An object entry represents a particular object. An alias entry provides alternative naming. A subentry holds administrative and/or operational information. The set of entries representing the DIB are organized hierarchically in a tree structure known as the Directory Information Tree (DIT). Section 2.1 describes the Directory Information Tree. Section 2.2 discusses the structure of entries. Section 2.3 discusses naming of entries. Zeilenga Standards Track [Page 6] RFC 4512 LDAP Models June 2006 Section 2.4 discusses object classes. Section 2.5 discusses attribute descriptions. Section 2.6 discusses alias entries. 2.1. The Directory Information Tree As noted above, the DIB is composed of a set of entries organized hierarchically in a tree structure known as the Directory Information Tree (DIT); specifically, a tree where vertices are the entries. The arcs between vertices define relations between entries. If an arc exists from X to Y, then the entry at X is the immediate superior of Y, and Y is the immediate subordinate of X. An entry's superiors are the entry's immediate superior and its superiors. An entry's subordinates are all of its immediate subordinates and their subordinates. Similarly, the superior/subordinate relationship between object entries can be used to derive a relation between the objects they represent. DIT structure rules can be used to govern relationships between objects. Note: An entry's immediate superior is also known as the entry's parent, and an entry's immediate subordinate is also known as the entry's child. Entries that have the same parent are known as siblings. 2.2. Structure of an Entry An entry consists of a set of attributes that hold information about the object that the entry represents. Some attributes represent user information and are called user attributes. Other attributes represent operational and/or administrative information and are called operational attributes. An attribute is an attribute description (a type and zero or more options) with one or more associated values. An attribute is often referred to by its attribute description. For example, the 'givenName' attribute is the attribute that consists of the attribute description 'givenName' (the 'givenName' attribute type [RFC4519] and zero options) and one or more associated values. The attribute type governs whether the attribute can have multiple values, the syntax and matching rules used to construct and compare values of that attribute, and other functions. Options indicate subtypes and other functions. Attribute values conform to the defined syntax of the attribute type. Zeilenga Standards Track [Page 7] RFC 4512 LDAP Models June 2006 No two values of an attribute may be equivalent. Two values are considered equivalent if and only if they would match according to the equality matching rule of the attribute type. Or, if the attribute type is defined with no equality matching rule, two values are equivalent if and only if they are identical. (See 2.5.1 for other restrictions.) For example, a 'givenName' attribute can have more than one value, they must be Directory Strings, and they are case insensitive. A 'givenName' attribute cannot hold both "John" and "JOHN", as these are equivalent values per the equality matching rule of the attribute type. Additionally, no attribute is to have a value that is not equivalent to itself. For example, the 'givenName' attribute cannot have as a value a directory string that includes the REPLACEMENT CHARACTER (U+FFFD) code point, as matching involving that directory string is Undefined per this attribute's equality matching rule. When an attribute is used for naming of the entry, one and only one value of the attribute is used in forming the Relative Distinguished Name. This value is known as a distinguished value. 2.3. Naming of Entries 2.3.1. Relative Distinguished Names Each entry is named relative to its immediate superior. This relative name, known as its Relative Distinguished Name (RDN) [X.501], is composed of an unordered set of one or more attribute value assertions (AVA) consisting of an attribute description with zero options and an attribute value. These AVAs are chosen to match attribute values (each a distinguished value) of the entry. An entry's relative distinguished name must be unique among all immediate subordinates of the entry's immediate superior (i.e., all siblings). The following are examples of string representations of RDNs [RFC4514]: UID=12345 OU=Engineering CN=Kurt Zeilenga+L=Redwood Shores The last is an example of a multi-valued RDN; that is, an RDN composed of multiple AVAs. Zeilenga Standards Track [Page 8] RFC 4512 LDAP Models June 2006 2.3.2. Distinguished Names An entry's fully qualified name, known as its Distinguished Name (DN) [X.501], is the concatenation of its RDN and its immediate superior's DN. A Distinguished Name unambiguously refers to an entry in the tree. The following are examples of string representations of DNs [RFC4514]: UID=nobody@example.com,DC=example,DC=com CN=John Smith,OU=Sales,O=ACME Limited,L=Moab,ST=Utah,C=US 2.3.3. Alias Names An alias, or alias name, is "an name for an object, provided by the use of alias entries" [X.501]. Alias entries are described in Section 2.6. 2.4. Object Classes An object class is "an identified family of objects (or conceivable objects) that share certain characteristics" [X.501]. As defined in [X.501]: Object classes are used in the Directory for a number of purposes: - describing and categorizing objects and the entries that correspond to these objects; - where appropriate, controlling the operation of the Directory; - regulating, in conjunction with DIT structure rule specifications, the position of entries in the DIT; - regulating, in conjunction with DIT content rule specifications, the attributes that are contained in entries; - identifying classes of entry that are to be associated with a particular policy by the appropriate administrative authority. An object class (a subclass) may be derived from an object class (its direct superclass) which is itself derived from an even more generic object class. For structural object classes, this process stops at the most generic object class, 'top' (defined in Section 2.4.1). An ordered set of superclasses up to the most superior object class of an object class is its superclass chain. Zeilenga Standards Track [Page 9] RFC 4512 LDAP Models June 2006 An object class may be derived from two or more direct superclasses (superclasses not part of the same superclass chain). This feature of subclassing is termed multiple inheritance. Each object class identifies the set of attributes required to be present in entries belonging to the class and the set of attributes allowed to be present in entries belonging to the class. As an entry of a class must meet the requirements of each class it belongs to, it can be said that an object class inherits the sets of allowed and required attributes from its superclasses. A subclass can identify an attribute allowed by its superclass as being required. If an attribute is a member of both sets, it is required to be present. Each object class is defined to be one of three kinds of object classes: Abstract, Structural, or Auxiliary. Each object class is identified by an object identifier (OID) and, optionally, one or more short names (descriptors). 2.4.1. Abstract Object Classes An abstract object class, as the name implies, provides a base of characteristics from which other object classes can be defined to inherit from. An entry cannot belong to an abstract object class unless it belongs to a structural or auxiliary class that inherits from that abstract class. Abstract object classes cannot derive from structural or auxiliary object classes. All structural object classes derive (directly or indirectly) from the 'top' abstract object class. Auxiliary object classes do not necessarily derive from 'top'. The following is the object class definition (see Section 4.1.1) for the 'top' object class: ( 2.5.6.0 NAME 'top' ABSTRACT MUST objectClass ) All entries belong to the 'top' abstract object class. Zeilenga Standards Track [Page 10] RFC 4512 LDAP Models June 2006 2.4.2. Structural Object Classes As stated in [X.501]: An object class defined for use in the structural specification of the DIT is termed a structural object class. Structural object classes are used in the definition of the structure of the names of the objects for compliant entries. An object or alias entry is characterized by precisely one structural object class superclass chain which has a single structural object class as the most subordinate object class. This structural object class is referred to as the structural object class of the entry. Structural object classes are related to associated entries: - an entry conforming to a structural object class shall represent the real-world object constrained by the object class; - DIT structure rules only refer to structural object classes; the structural object class of an entry is used to specify the position of the entry in the DIT; - the structural object class of an entry is used, along with an associated DIT content rule, to control the content of an entry. The structural object class of an entry shall not be changed. Each structural object class is a (direct or indirect) subclass of the 'top' abstract object class. Structural object classes cannot subclass auxiliary object classes. Each entry is said to belong to its structural object class as well as all classes in its structural object class's superclass chain. 2.4.3. Auxiliary Object Classes Auxiliary object classes are used to augment the characteristics of entries. They are commonly used to augment the sets of attributes required and allowed to be present in an entry. They can be used to describe entries or classes of entries. Auxiliary object classes cannot subclass structural object classes. Zeilenga Standards Track [Page 11] RFC 4512 LDAP Models June 2006 An entry can belong to any subset of the set of auxiliary object classes allowed by the DIT content rule associated with the structural object class of the entry. If no DIT content rule is associated with the structural object class of the entry, the entry cannot belong to any auxiliary object class. The set of auxiliary object classes that an entry belongs to can change over time. 2.5. Attribute Descriptions An attribute description is composed of an attribute type (see Section 2.5.1) and a set of zero or more attribute options (see Section 2.5.2). An attribute description is represented by the ABNF: attributedescription = attributetype options attributetype = oid options = *( SEMI option ) option = 1*keychar where <attributetype> identifies the attribute type and each <option> identifies an attribute option. Both <attributetype> and <option> productions are case insensitive. The order in which <option>s appear is irrelevant. That is, any two <attributedescription>s that consist of the same <attributetype> and same set of <option>s are equivalent. Examples of valid attribute descriptions: 2.5.4.0 cn;lang-de;lang-en owner An attribute description with an unrecognized attribute type is to be treated as unrecognized. Servers SHALL treat an attribute description with an unrecognized attribute option as unrecognized. Clients MAY treat an unrecognized attribute option as a tagging option (see Section 2.5.2.1). All attributes of an entry must have distinct attribute descriptions. 2.5.1. Attribute Types An attribute type governs whether the attribute can have multiple values, the syntax and matching rules used to construct and compare values of that attribute, and other functions. Zeilenga Standards Track [Page 12] RFC 4512 LDAP Models June 2006 If no equality matching is specified for the attribute type: - the attribute (of the type) cannot be used for naming; - when adding the attribute (or replacing all values), no two values may be equivalent (see 2.2); - individual values of a multi-valued attribute are not to be independently added or deleted; - attribute value assertions (such as matching in search filters and comparisons) using values of such a type cannot be performed. Otherwise, the specified equality matching rule is to be used to evaluate attribute value assertions concerning the attribute type. The specified equality rule is to be transitive and commutative. The attribute type indicates whether the attribute is a user attribute or an operational attribute. If operational, the attribute type indicates the operational usage and whether or not the attribute is modifiable by users. Operational attributes are discussed in Section 3.4. An attribute type (a subtype) may derive from a more generic attribute type (a direct supertype). The following restrictions apply to subtyping: - a subtype must have the same usage as its direct supertype, - a subtype's syntax must be the same, or a refinement of, its supertype's syntax, and - a subtype must be collective [RFC3671] if its supertype is collective. An attribute description consisting of a subtype and no options is said to be the direct description subtype of the attribute description consisting of the subtype's direct supertype and no options. Each attribute type is identified by an object identifier (OID) and, optionally, one or more short names (descriptors). 2.5.2. Attribute Options There are multiple kinds of attribute description options. The LDAP technical specification details one kind: tagging options. Not all options can be associated with attributes held in the directory. Tagging options can be. Zeilenga Standards Track [Page 13] RFC 4512 LDAP Models June 2006 Not all options can be used in conjunction with all attribute types. In such cases, the attribute description is to be treated as unrecognized. An attribute description that contains mutually exclusive options shall be treated as unrecognized. That is, "cn;x-bar;x-foo", where "x-foo" and "x-bar" are mutually exclusive, is to be treated as unrecognized. Other kinds of options may be specified in future documents. These documents must detail how new kinds of options they define relate to tagging options. In particular, these documents must detail whether or not new kinds of options can be associated with attributes held in the directory, how new kinds of options affect transfer of attribute values, and how new kinds of options are treated in attribute description hierarchies. Options are represented as short, case-insensitive textual strings conforming to the <option> production defined in Section 2.5 of this document. Procedures for registering options are detailed in BCP 64, RFC 4520 [RFC4520]. 2.5.2.1. Tagging Options Attributes held in the directory can have attribute descriptions with any number of tagging options. Tagging options are never mutually exclusive. An attribute description with N tagging options is a direct (description) subtype of all attribute descriptions of the same attribute type and all but one of the N options. If the attribute type has a supertype, then the attribute description is also a direct (description) subtype of the attribute description of the supertype and the N tagging options. That is, 'cn;lang-de;lang-en' is a direct (description) subtype of 'cn;lang-de', 'cn;lang-en', and 'name;lang-de;lang-en' ('cn' is a subtype of 'name'; both are defined in [RFC4519]). 2.5.3. Attribute Description Hierarchies An attribute description can be the direct subtype of zero or more other attribute descriptions as indicated by attribute type subtyping (as described in Section 2.5.1) or attribute tagging option subtyping (as described in Section 2.5.2.1). These subtyping relationships are used to form hierarchies of attribute descriptions and attributes. Zeilenga Standards Track [Page 14] RFC 4512 LDAP Models June 2006 As adapted from [X.501]: Attribute hierarchies allow access to the DIB with varying degrees of granularity. This is achieved by allowing the value components of attributes to be accessed by using either their specific attribute description (a direct reference to the attribute) or a more generic attribute description (an indirect reference). Semantically related attributes may be placed in a hierarchical relationship, the more specialized being placed subordinate to the more generalized. Searching for or retrieving attributes and their values is made easier by quoting the more generalized attribute description; a filter item so specified is evaluated for the more specialized descriptions as well as for the quoted description. Where subordinate specialized descriptions are selected to be returned as part of a search result these descriptions shall be returned if available. Where the more general descriptions are selected to be returned as part of a search result both the general and the specialized descriptions shall be returned, if available. An attribute value shall always be returned as a value of its own attribute description. All of the attribute descriptions in an attribute hierarchy are treated as distinct and unrelated descriptions for user modification of entry content. An attribute value stored in an object or alias entry is of precisely one attribute description. The description is indicated when the value is originally added to the entry. For the purpose of subschema administration of the entry, a specification that an attribute is required is fulfilled if the entry contains a value of an attribute description belonging to an attribute hierarchy where the attribute type of that description is the same as the required attribute's type. That is, a "MUST name" specification is fulfilled by 'name' or 'name;x-tag-option', but is not fulfilled by 'CN' or 'CN;x-tag-option' (even though 'CN' is a subtype of 'name'). Likewise, an entry may contain a value of an attribute description belonging to an attribute hierarchy where the attribute type of that description is either explicitly included in the definition of an object class to which the entry belongs or allowed by the DIT content rule applicable to that entry. That is, 'name' and 'name;x-tag-option' are allowed by "MAY name" (or by "MUST name"), but 'CN' and 'CN;x-tag-option' are not allowed by "MAY name" (or by "MUST name"). Zeilenga Standards Track [Page 15] RFC 4512 LDAP Models June 2006 For the purposes of other policy administration, unless stated otherwise in the specification of the particular administrative model, all of the attribute descriptions in an attribute hierarchy are treated as distinct and unrelated descriptions. 2.6. Alias Entries As adapted from [X.501]: An alias, or an alias name, for an object is an alternative name for an object or object entry which is provided by the use of alias entries. Each alias entry contains, within the 'aliasedObjectName' attribute (known as the 'aliasedEntryName' attribute in X.500), a name of some object. The distinguished name of the alias entry is thus also a name for this object. NOTE - The name within the 'aliasedObjectName' is said to be pointed to by the alias. It does not have to be the distinguished name of any entry. The conversion of an alias name to an object name is termed (alias) dereferencing and comprises the systematic replacement of alias names, where found within a purported name, by the value of the corresponding 'aliasedObjectName' attribute. The process may require the examination of more than one alias entry. Any particular entry in the DIT may have zero or more alias names. It therefore follows that several alias entries may point to the same entry. An alias entry may point to an entry that is not a leaf entry and may point to another alias entry. An alias entry shall have no subordinates, so that an alias entry is always a leaf entry. Every alias entry shall belong to the 'alias' object class. An entry with the 'alias' object class must also belong to an object class (or classes), or be governed by a DIT content rule, which allows suitable naming attributes to be present. Example: dn: cn=bar,dc=example,dc=com objectClass: top objectClass: alias objectClass: extensibleObject Zeilenga Standards Track [Page 16] RFC 4512 LDAP Models June 2006 cn: bar aliasedObjectName: cn=foo,dc=example,dc=com 2.6.1. 'alias' Object Class Alias entries belong to the 'alias' object class. ( 2.5.6.1 NAME 'alias' SUP top STRUCTURAL MUST aliasedObjectName ) 2.6.2. 'aliasedObjectName' Attribute Type The 'aliasedObjectName' attribute holds the name of the entry an alias points to. The 'aliasedObjectName' attribute is known as the 'aliasedEntryName' attribute in X.500. ( 2.5.4.1 NAME 'aliasedObjectName' EQUALITY distinguishedNameMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 SINGLE-VALUE ) The 'distinguishedNameMatch' matching rule and the DistinguishedName (1.3.6.1.4.1.1466.115.121.1.12) syntax are defined in [RFC4517]. 3. Directory Administrative and Operational Information This section discusses select aspects of the X.500 Directory Administrative and Operational Information model [X.501]. LDAP implementations MAY support other aspects of this model. 3.1. Subtrees As defined in [X.501]: A subtree is a collection of object and alias entries situated at the vertices of a tree. Subtrees do not contain subentries. The prefix sub, in subtree, emphasizes that the base (or root) vertex of this tree is usually subordinate to the root of the DIT. A subtree begins at some vertex and extends to some identifiable lower boundary, possibly extending to leaves. A subtree is always defined within a context which implicitly bounds the subtree. For example, the vertex and lower boundaries of a subtree defining a replicated area are bounded by a naming context. Zeilenga Standards Track [Page 17] RFC 4512 LDAP Models June 2006 3.2. Subentries A subentry is a "special sort of entry, known by the Directory, used to hold information associated with a subtree or subtree refinement" [X.501]. Subentries are used in Directory to hold for administrative and operational purposes as defined in [X.501]. Their use in LDAP is detailed in [RFC3672]. The term "(sub)entry" in this specification indicates that servers implementing X.500(93) models are, in accordance with X.500(93) as described in [RFC3672], to use a subentry and that other servers are to use an object entry belonging to the appropriate auxiliary class normally used with the subentry (e.g., 'subschema' for subschema subentries) to mimic the subentry. This object entry's RDN SHALL be formed from a value of the 'cn' (commonName) attribute [RFC4519] (as all subentries are named with 'cn'). 3.3. The 'objectClass' attribute Each entry in the DIT has an 'objectClass' attribute. ( 2.5.4.0 NAME 'objectClass' EQUALITY objectIdentifierMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 ) The 'objectIdentifierMatch' matching rule and the OBJECT IDENTIFIER (1.3.6.1.4.1.1466.115.121.1.38) syntax are defined in [RFC4517]. The 'objectClass' attribute specifies the object classes of an entry, which (among other things) are used in conjunction with the controlling schema to determine the permitted attributes of an entry. Values of this attribute can be modified by clients, but the 'objectClass' attribute cannot be removed. Servers that follow X.500(93) models SHALL restrict modifications of this attribute to prevent the basic structural class of the entry from being changed. That is, one cannot change a 'person' into a 'country'. When creating an entry or adding an 'objectClass' value to an entry, all superclasses of the named classes SHALL be implicitly added as well if not already present. That is, if the auxiliary class 'x-a' is a subclass of the class 'x-b', adding 'x-a' to 'objectClass' causes 'x-b' to be implicitly added (if is not already present). Servers SHALL restrict modifications of this attribute to prevent superclasses of remaining 'objectClass' values from being deleted. That is, if the auxiliary class 'x-a' is a subclass of the auxiliary Zeilenga Standards Track [Page 18] RFC 4512 LDAP Models June 2006 class 'x-b' and the 'objectClass' attribute contains 'x-a' and 'x-b', an attempt to delete only 'x-b' from the 'objectClass' attribute is an error. 3.4. Operational Attributes Some attributes, termed operational attributes, are used or maintained by servers for administrative and operational purposes. As stated in [X.501]: "There are three varieties of operational attributes: Directory operational attributes, DSA-shared operational attributes, and DSA-specific operational attributes". A directory operational attribute is used to represent operational and/or administrative information in the Directory Information Model. This includes operational attributes maintained by the server (e.g., 'createTimestamp') as well as operational attributes that hold values administrated by the user (e.g., 'ditContentRules'). A DSA-shared operational attribute is used to represent information of the DSA Information Model that is shared between DSAs. A DSA-specific operational attribute is used to represent information of the DSA Information Model that is specific to the DSA (though, in some cases, may be derived from information shared between DSAs; e.g., 'namingContexts'). The DSA Information Model operational attributes are detailed in [X.501]. Operational attributes are not normally visible. They are not returned in search results unless explicitly requested by name. Not all operational attributes are user modifiable. Entries may contain, among others, the following operational attributes: - creatorsName: the Distinguished Name of the user who added this entry to the directory, - createTimestamp: the time this entry was added to the directory, - modifiersName: the Distinguished Name of the user who last modified this entry, and - modifyTimestamp: the time this entry was last modified. Zeilenga Standards Track [Page 19] RFC 4512 LDAP Models June 2006 Servers SHOULD maintain the 'creatorsName', 'createTimestamp', 'modifiersName', and 'modifyTimestamp' attributes for all entries of the DIT. 3.4.1. 'creatorsName' This attribute appears in entries that were added using the protocol (e.g., using the Add operation). The value is the distinguished name of the creator. ( 2.5.18.3 NAME 'creatorsName' EQUALITY distinguishedNameMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 SINGLE-VALUE NO-USER-MODIFICATION USAGE directoryOperation ) The 'distinguishedNameMatch' matching rule and the DistinguishedName (1.3.6.1.4.1.1466.115.121.1.12) syntax are defined in [RFC4517]. 3.4.2. 'createTimestamp' This attribute appears in entries that were added using the protocol (e.g., using the Add operation). The value is the time the entry was added. ( 2.5.18.1 NAME 'createTimestamp' EQUALITY generalizedTimeMatch ORDERING generalizedTimeOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 SINGLE-VALUE NO-USER-MODIFICATION USAGE directoryOperation ) The 'generalizedTimeMatch' and 'generalizedTimeOrderingMatch' matching rules and the GeneralizedTime (1.3.6.1.4.1.1466.115.121.1.24) syntax are defined in [RFC4517]. 3.4.3. 'modifiersName' This attribute appears in entries that have been modified using the protocol (e.g., using the Modify operation). The value is the distinguished name of the last modifier. ( 2.5.18.4 NAME 'modifiersName' EQUALITY distinguishedNameMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 SINGLE-VALUE NO-USER-MODIFICATION USAGE directoryOperation ) Zeilenga Standards Track [Page 20] RFC 4512 LDAP Models June 2006 The 'distinguishedNameMatch' matching rule and the DistinguishedName (1.3.6.1.4.1.1466.115.121.1.12) syntax are defined in [RFC4517]. 3.4.4. 'modifyTimestamp' This attribute appears in entries that have been modified using the protocol (e.g., using the Modify operation). The value is the time the entry was last modified. ( 2.5.18.2 NAME 'modifyTimestamp' EQUALITY generalizedTimeMatch ORDERING generalizedTimeOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 SINGLE-VALUE NO-USER-MODIFICATION USAGE directoryOperation ) The 'generalizedTimeMatch' and 'generalizedTimeOrderingMatch' matching rules and the GeneralizedTime (1.3.6.1.4.1.1466.115.121.1.24) syntax are defined in [RFC4517]. 3.4.5. 'structuralObjectClass' This attribute indicates the structural object class of the entry. ( 2.5.21.9 NAME 'structuralObjectClass' EQUALITY objectIdentifierMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 SINGLE-VALUE NO-USER-MODIFICATION USAGE directoryOperation ) The 'objectIdentifierMatch' matching rule and OBJECT IDENTIFIER (1.3.6.1.4.1.1466.115.121.1.38) syntax is defined in [RFC4517]. 3.4.6. 'governingStructureRule' This attribute indicates the structure rule governing the entry. ( 2.5.21.10 NAME 'governingStructureRule' EQUALITY integerMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE NO-USER-MODIFICATION USAGE directoryOperation ) The 'integerMatch' matching rule and INTEGER (1.3.6.1.4.1.1466.115.121.1.27) syntax is defined in [RFC4517]. Zeilenga Standards Track [Page 21] RFC 4512 LDAP Models June 2006 4. Directory Schema As defined in [X.501]: The Directory Schema is a set of definitions and constraints concerning the structure of the DIT, the possible ways entries are named, the information that can be held in an entry, the attributes used to represent that information and their organization into hierarchies to facilitate search and retrieval of the information and the ways in which values of attributes may be matched in attribute value and matching rule assertions. NOTE 1 - The schema enables the Directory system to, for example: - prevent the creation of subordinate entries of the wrong object-class (e.g., a country as a subordinate of a person); - prevent the addition of attribute-types to an entry inappropriate to the object-class (e.g., a serial number to a person's entry); - prevent the addition of an attribute value of a syntax not matching that defined for the attribute-type (e.g., a printable string to a bit string). Formally, the Directory Schema comprises a set of: a) Name Form definitions that define primitive naming relations for structural object classes; b) DIT Structure Rule definitions that define the names that entries may have and the ways in which the entries may be related to one another in the DIT; c) DIT Content Rule definitions that extend the specification of allowable attributes for entries beyond those indicated by the structural object classes of the entries; d) Object Class definitions that define the basic set of mandatory and optional attributes that shall be present, and may be present, respectively, in an entry of a given class, and which indicate the kind of object class that is being defined; Zeilenga Standards Track [Page 22] RFC 4512 LDAP Models June 2006 e) Attribute Type definitions that identify the object identifier by which an attribute is known, its syntax, associated matching rules, whether it is an operational attribute and if so its type, whether it is a collective attribute, whether it is permitted to have multiple values and whether or not it is derived from another attribute type; f) Matching Rule definitions that define matching rules. And in LDAP: g) LDAP Syntax definitions that define encodings used in LDAP. 4.1. Schema Definitions Schema definitions in this section are described using ABNF and rely on the common productions specified in Section 1.2 as well as these: noidlen = numericoid [ LCURLY len RCURLY ] len = number oids = oid / ( LPAREN WSP oidlist WSP RPAREN ) oidlist = oid *( WSP DOLLAR WSP oid ) extensions = *( SP xstring SP qdstrings ) xstring = "X" HYPHEN 1*( ALPHA / HYPHEN / USCORE ) qdescrs = qdescr / ( LPAREN WSP qdescrlist WSP RPAREN ) qdescrlist = [ qdescr *( SP qdescr ) ] qdescr = SQUOTE descr SQUOTE qdstrings = qdstring / ( LPAREN WSP qdstringlist WSP RPAREN ) qdstringlist = [ qdstring *( SP qdstring ) ] qdstring = SQUOTE dstring SQUOTE dstring = 1*( QS / QQ / QUTF8 ) ; escaped UTF-8 string QQ = ESC %x32 %x37 ; "\27" QS = ESC %x35 ( %x43 / %x63 ) ; "\5C" / "\5c" ; Any UTF-8 encoded Unicode character ; except %x27 ("\'") and %x5C ("\") QUTF8 = QUTF1 / UTFMB ; Any ASCII character except %x27 ("\'") and %x5C ("\") QUTF1 = %x00-26 / %x28-5B / %x5D-7F Schema definitions in this section also share a number of common terms. Zeilenga Standards Track [Page 23] RFC 4512 LDAP Models June 2006 The NAME field provides a set of short names (descriptors) that are to be used as aliases for the OID. The DESC field optionally allows a descriptive string to be provided by the directory administrator and/or implementor. While specifications may suggest a descriptive string, there is no requirement that the suggested (or any) descriptive string be used. The OBSOLETE field, if present, indicates the element is not active. Implementors should note that future versions of this document may expand these definitions to include additional terms. Terms whose identifier begins with "X-" are reserved for private experiments and are followed by <SP> and <qdstrings> tokens. 4.1.1. Object Class Definitions Object Class definitions are written according to the ABNF: ObjectClassDescription = LPAREN WSP numericoid ; object identifier [ SP "NAME" SP qdescrs ] ; short names (descriptors) [ SP "DESC" SP qdstring ] ; description [ SP "OBSOLETE" ] ; not active [ SP "SUP" SP oids ] ; superior object classes [ SP kind ] ; kind of class [ SP "MUST" SP oids ] ; attribute types [ SP "MAY" SP oids ] ; attribute types extensions WSP RPAREN kind = "ABSTRACT" / "STRUCTURAL" / "AUXILIARY" where: <numericoid> is object identifier assigned to this object class; NAME <qdescrs> are short names (descriptors) identifying this object class; DESC <qdstring> is a short descriptive string; OBSOLETE indicates this object class is not active; SUP <oids> specifies the direct superclasses of this object class; the kind of object class is indicated by one of ABSTRACT, STRUCTURAL, or AUXILIARY (the default is STRUCTURAL); MUST and MAY specify the sets of required and allowed attribute types, respectively; and <extensions> describe extensions. Zeilenga Standards Track [Page 24] RFC 4512 LDAP Models June 2006 4.1.2. Attribute Types Attribute Type definitions are written according to the ABNF: AttributeTypeDescription = LPAREN WSP numericoid ; object identifier [ SP "NAME" SP qdescrs ] ; short names (descriptors) [ SP "DESC" SP qdstring ] ; description [ SP "OBSOLETE" ] ; not active [ SP "SUP" SP oid ] ; supertype [ SP "EQUALITY" SP oid ] ; equality matching rule [ SP "ORDERING" SP oid ] ; ordering matching rule [ SP "SUBSTR" SP oid ] ; substrings matching rule [ SP "SYNTAX" SP noidlen ] ; value syntax [ SP "SINGLE-VALUE" ] ; single-value [ SP "COLLECTIVE" ] ; collective [ SP "NO-USER-MODIFICATION" ] ; not user modifiable [ SP "USAGE" SP usage ] ; usage extensions WSP RPAREN ; extensions usage = "userApplications" / ; user "directoryOperation" / ; directory operational "distributedOperation" / ; DSA-shared operational "dSAOperation" ; DSA-specific operational where: <numericoid> is object identifier assigned to this attribute type; NAME <qdescrs> are short names (descriptors) identifying this attribute type; DESC <qdstring> is a short descriptive string; OBSOLETE indicates this attribute type is not active; SUP oid specifies the direct supertype of this type; EQUALITY, ORDERING, and SUBSTR provide the oid of the equality, ordering, and substrings matching rules, respectively; SYNTAX identifies value syntax by object identifier and may suggest a minimum upper bound; SINGLE-VALUE indicates attributes of this type are restricted to a single value; COLLECTIVE indicates this attribute type is collective [X.501][RFC3671]; NO-USER-MODIFICATION indicates this attribute type is not user modifiable; USAGE indicates the application of this attribute type; and <extensions> describe extensions. Each attribute type description must contain at least one of the SUP or SYNTAX fields. If no SYNTAX field is provided, the attribute type description takes its value from the supertype. Zeilenga Standards Track [Page 25] RFC 4512 LDAP Models June 2006 If SUP field is provided, the EQUALITY, ORDERING, and SUBSTRING fields, if not specified, take their value from the supertype. Usage of userApplications, the default, indicates that attributes of this type represent user information. That is, they are user attributes. A usage of directoryOperation, distributedOperation, or dSAOperation indicates that attributes of this type represent operational and/or administrative information. That is, they are operational attributes. directoryOperation usage indicates that the attribute of this type is a directory operational attribute. distributedOperation usage indicates that the attribute of this type is a DSA-shared usage operational attribute. dSAOperation usage indicates that the attribute of this type is a DSA-specific operational attribute. COLLECTIVE requires usage userApplications. Use of collective attribute types in LDAP is discussed in [RFC3671]. NO-USER-MODIFICATION requires an operational usage. Note that the <AttributeTypeDescription> does not list the matching rules that can be used with that attribute type in an extensibleMatch search filter [RFC4511]. This is done using the 'matchingRuleUse' attribute described in Section 4.1.4. This document refines the schema description of X.501 by requiring that the SYNTAX field in an <AttributeTypeDescription> be a string representation of an object identifier for the LDAP string syntax definition, with an optional indication of the suggested minimum bound of a value of this attribute. A suggested minimum upper bound on the number of characters in a value with a string-based syntax, or the number of bytes in a value for all other syntaxes, may be indicated by appending this bound count inside of curly braces following the syntax's OBJECT IDENTIFIER in an Attribute Type Description. This bound is not part of the syntax name itself. For instance, "1.3.6.4.1.1466.0{64}" suggests that server implementations should allow a string to be 64 characters long, although they may allow longer strings. Note that a single character of the Directory String syntax may be encoded in more than one octet since UTF-8 [RFC3629] is a variable-length encoding. Zeilenga Standards Track [Page 26] RFC 4512 LDAP Models June 2006 4.1.3. Matching Rules Matching rules are used in performance of attribute value assertions, such as in performance of a Compare operation. They are also used in evaluating search filters, determining which individual values are to be added or deleted during performance of a Modify operation, and in comparing distinguished names. Each matching rule is identified by an object identifier (OID) and, optionally, one or more short names (descriptors). Matching rule definitions are written according to the ABNF: MatchingRuleDescription = LPAREN WSP numericoid ; object identifier [ SP "NAME" SP qdescrs ] ; short names (descriptors) [ SP "DESC" SP qdstring ] ; description [ SP "OBSOLETE" ] ; not active SP "SYNTAX" SP numericoid ; assertion syntax extensions WSP RPAREN ; extensions where: <numericoid> is object identifier assigned to this matching rule; NAME <qdescrs> are short names (descriptors) identifying this matching rule; DESC <qdstring> is a short descriptive string; OBSOLETE indicates this matching rule is not active; SYNTAX identifies the assertion syntax (the syntax of the assertion value) by object identifier; and <extensions> describe extensions. 4.1.4. Matching Rule Uses A matching rule use lists the attribute types that are suitable for use with an extensibleMatch search filter. Matching rule use descriptions are written according to the following ABNF: MatchingRuleUseDescription = LPAREN WSP numericoid ; object identifier [ SP "NAME" SP qdescrs ] ; short names (descriptors) [ SP "DESC" SP qdstring ] ; description [ SP "OBSOLETE" ] ; not active SP "APPLIES" SP oids ; attribute types extensions WSP RPAREN ; extensions Zeilenga Standards Track [Page 27] RFC 4512 LDAP Models June 2006 where: <numericoid> is the object identifier of the matching rule associated with this matching rule use description; NAME <qdescrs> are short names (descriptors) identifying this matching rule use; DESC <qdstring> is a short descriptive string; OBSOLETE indicates this matching rule use is not active; APPLIES provides a list of attribute types the matching rule applies to; and <extensions> describe extensions. 4.1.5. LDAP Syntaxes LDAP Syntaxes of (attribute and assertion) values are described in terms of ASN.1 [X.680] and, optionally, have an octet string encoding known as the LDAP-specific encoding. Commonly, the LDAP-specific encoding is constrained to a string of Unicode [Unicode] characters in UTF-8 [RFC3629] form. Each LDAP syntax is identified by an object identifier (OID). LDAP syntax definitions are written according to the ABNF: SyntaxDescription = LPAREN WSP numericoid ; object identifier [ SP "DESC" SP qdstring ] ; description extensions WSP RPAREN ; extensions where: <numericoid> is the object identifier assigned to this LDAP syntax; DESC <qdstring> is a short descriptive string; and <extensions> describe extensions. 4.1.6. DIT Content Rules A DIT content rule is a "rule governing the content of entries of a particular structural object class" [X.501]. For DIT entries of a particular structural object class, a DIT content rule specifies which auxiliary object classes the entries are allowed to belong to and which additional attributes (by type) are required, allowed, or not allowed to appear in the entries. The list of precluded attributes cannot include any attribute listed as mandatory in the rule, the structural object class, or any of the allowed auxiliary object classes. Zeilenga Standards Track [Page 28] RFC 4512 LDAP Models June 2006 Each content rule is identified by the object identifier, as well as any short names (descriptors), of the structural object class it applies to. An entry may only belong to auxiliary object classes listed in the governing content rule. An entry must contain all attributes required by the object classes the entry belongs to as well as all attributes required by the governing content rule. An entry may contain any non-precluded attributes allowed by the object classes the entry belongs to as well as all attributes allowed by the governing content rule. An entry cannot include any attribute precluded by the governing content rule. An entry is governed by (if present and active in the subschema) the DIT content rule that applies to the structural object class of the entry (see Section 2.4.2). If no active rule is present for the entry's structural object class, the entry's content is governed by the structural object class (and possibly other aspects of user and system schema). DIT content rules for superclasses of the structural object class of an entry are not applicable to that entry. DIT content rule descriptions are written according to the ABNF: DITContentRuleDescription = LPAREN WSP numericoid ; object identifier [ SP "NAME" SP qdescrs ] ; short names (descriptors) [ SP "DESC" SP qdstring ] ; description [ SP "OBSOLETE" ] ; not active [ SP "AUX" SP oids ] ; auxiliary object classes [ SP "MUST" SP oids ] ; attribute types [ SP "MAY" SP oids ] ; attribute types [ SP "NOT" SP oids ] ; attribute types extensions WSP RPAREN ; extensions where: <numericoid> is the object identifier of the structural object class associated with this DIT content rule; NAME <qdescrs> are short names (descriptors) identifying this DIT content rule; DESC <qdstring> is a short descriptive string; OBSOLETE indicates this DIT content rule use is not active; AUX specifies a list of auxiliary object classes that entries subject to this DIT content rule may belong to; Zeilenga Standards Track [Page 29] RFC 4512 LDAP Models June 2006 MUST, MAY, and NOT specify lists of attribute types that are required, allowed, or precluded, respectively, from appearing in entries subject to this DIT content rule; and <extensions> describe extensions. 4.1.7. DIT Structure Rules and Name Forms It is sometimes desirable to regulate where object and alias entries can be placed in the DIT and how they can be named based upon their structural object class. 4.1.7.1. DIT Structure Rules A DIT structure rule is a "rule governing the structure of the DIT by specifying a permitted superior to subordinate entry relationship. A structure rule relates a name form, and therefore a structural object class, to superior structure rules. This permits entries of the structural object class identified by the name form to exist in the DIT as subordinates to entries governed by the indicated superior structure rules" [X.501]. DIT structure rule descriptions are written according to the ABNF: DITStructureRuleDescription = LPAREN WSP ruleid ; rule identifier [ SP "NAME" SP qdescrs ] ; short names (descriptors) [ SP "DESC" SP qdstring ] ; description [ SP "OBSOLETE" ] ; not active SP "FORM" SP oid ; NameForm [ SP "SUP" ruleids ] ; superior rules extensions WSP RPAREN ; extensions ruleids = ruleid / ( LPAREN WSP ruleidlist WSP RPAREN ) ruleidlist = ruleid *( SP ruleid ) ruleid = number where: <ruleid> is the rule identifier of this DIT structure rule; NAME <qdescrs> are short names (descriptors) identifying this DIT structure rule; DESC <qdstring> is a short descriptive string; OBSOLETE indicates this DIT structure rule use is not active; FORM is specifies the name form associated with this DIT structure rule; SUP identifies superior rules (by rule id); and <extensions> describe extensions. Zeilenga Standards Track [Page 30] RFC 4512 LDAP Models June 2006 If no superior rules are identified, the DIT structure rule applies to an autonomous administrative point (e.g., the root vertex of the subtree controlled by the subschema) [X.501]. 4.1.7.2. Name Forms A name form "specifies a permissible RDN for entries of a particular structural object class. A name form identifies a named object class and one or more attribute types to be used for naming (i.e., for the RDN). Name forms are primitive pieces of specification used in the definition of DIT structure rules" [X.501]. Each name form indicates the structural object class to be named, a set of required attribute types, and a set of allowed attribute types. A particular attribute type cannot be in both sets. Entries governed by the form must be named using a value from each required attribute type and zero or more values from the allowed attribute types. Each name form is identified by an object identifier (OID) and, optionally, one or more short names (descriptors). Name form descriptions are written according to the ABNF: NameFormDescription = LPAREN WSP numericoid ; object identifier [ SP "NAME" SP qdescrs ] ; short names (descriptors) [ SP "DESC" SP qdstring ] ; description [ SP "OBSOLETE" ] ; not active SP "OC" SP oid ; structural object class SP "MUST" SP oids ; attribute types [ SP "MAY" SP oids ] ; attribute types extensions WSP RPAREN ; extensions where: <numericoid> is object identifier that identifies this name form; NAME <qdescrs> are short names (descriptors) identifying this name form; DESC <qdstring> is a short descriptive string; OBSOLETE indicates this name form is not active; OC identifies the structural object class this rule applies to, MUST and MAY specify the sets of required and allowed, respectively, naming attributes for this name form; and <extensions> describe extensions. All attribute types in the required ("MUST") and allowed ("MAY") lists shall be different. Zeilenga Standards Track [Page 31] RFC 4512 LDAP Models June 2006 4.2. Subschema Subentries Subschema (sub)entries are used for administering information about the directory schema. A single subschema (sub)entry contains all schema definitions (see Section 4.1) used by entries in a particular part of the directory tree. Servers that follow X.500(93) models SHOULD implement subschema using the X.500 subschema mechanisms (as detailed in Section 12 of [X.501]), so these are not ordinary object entries but subentries (see Section 3.2). LDAP clients SHOULD NOT assume that servers implement any of the other aspects of X.500 subschema. Servers MAY allow subschema modification. Procedures for subschema modification are discussed in Section 14.5 of [X.501]. A server that masters entries and permits clients to modify these entries SHALL implement and provide access to these subschema (sub)entries including providing a 'subschemaSubentry' attribute in each modifiable entry. This is so clients may discover the attributes and object classes that are permitted to be present. It is strongly RECOMMENDED that all other servers implement this as well. The value of the 'subschemaSubentry' attribute is the name of the subschema (sub)entry holding the subschema controlling the entry. ( 2.5.18.10 NAME 'subschemaSubentry' EQUALITY distinguishedNameMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 SINGLE-VALUE NO-USER-MODIFICATION USAGE directoryOperation ) The 'distinguishedNameMatch' matching rule and the DistinguishedName (1.3.6.1.4.1.1466.115.121.1.12) syntax are defined in [RFC4517]. Subschema is held in (sub)entries belonging to the subschema auxiliary object class. ( 2.5.20.1 NAME 'subschema' AUXILIARY MAY ( dITStructureRules $ nameForms $ ditContentRules $ objectClasses $ attributeTypes $ matchingRules $ matchingRuleUse ) ) The 'ldapSyntaxes' operational attribute may also be present in subschema entries. Zeilenga Standards Track [Page 32] RFC 4512 LDAP Models June 2006 Servers MAY provide additional attributes (described in other documents) in subschema (sub)entries. Servers SHOULD provide the attributes 'createTimestamp' and 'modifyTimestamp' in subschema (sub)entries, in order to allow clients to maintain their caches of schema information. The following subsections provide attribute type definitions for each of schema definition attribute types. 4.2.1. 'objectClasses' This attribute holds definitions of object classes. ( 2.5.21.6 NAME 'objectClasses' EQUALITY objectIdentifierFirstComponentMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.37 USAGE directoryOperation ) The 'objectIdentifierFirstComponentMatch' matching rule and the ObjectClassDescription (1.3.6.1.4.1.1466.115.121.1.37) syntax are defined in [RFC4517]. 4.2.2. 'attributeTypes' This attribute holds definitions of attribute types. ( 2.5.21.5 NAME 'attributeTypes' EQUALITY objectIdentifierFirstComponentMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.3 USAGE directoryOperation ) The 'objectIdentifierFirstComponentMatch' matching rule and the AttributeTypeDescription (1.3.6.1.4.1.1466.115.121.1.3) syntax are defined in [RFC4517]. 4.2.3. 'matchingRules' This attribute holds definitions of matching rules. ( 2.5.21.4 NAME 'matchingRules' EQUALITY objectIdentifierFirstComponentMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.30 USAGE directoryOperation ) The 'objectIdentifierFirstComponentMatch' matching rule and the MatchingRuleDescription (1.3.6.1.4.1.1466.115.121.1.30) syntax are defined in [RFC4517]. Zeilenga Standards Track [Page 33] RFC 4512 LDAP Models June 2006 4.2.4 'matchingRuleUse' This attribute holds definitions of matching rule uses. ( 2.5.21.8 NAME 'matchingRuleUse' EQUALITY objectIdentifierFirstComponentMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.31 USAGE directoryOperation ) The 'objectIdentifierFirstComponentMatch' matching rule and the MatchingRuleUseDescription (1.3.6.1.4.1.1466.115.121.1.31) syntax are defined in [RFC4517]. 4.2.5. 'ldapSyntaxes' This attribute holds definitions of LDAP syntaxes. ( 1.3.6.1.4.1.1466.101.120.16 NAME 'ldapSyntaxes' EQUALITY objectIdentifierFirstComponentMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.54 USAGE directoryOperation ) The 'objectIdentifierFirstComponentMatch' matching rule and the SyntaxDescription (1.3.6.1.4.1.1466.115.121.1.54) syntax are defined in [RFC4517]. 4.2.6. 'dITContentRules' This attribute lists DIT Content Rules that are present in the subschema. ( 2.5.21.2 NAME 'dITContentRules' EQUALITY objectIdentifierFirstComponentMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.16 USAGE directoryOperation ) The 'objectIdentifierFirstComponentMatch' matching rule and the DITContentRuleDescription (1.3.6.1.4.1.1466.115.121.1.16) syntax are defined in [RFC4517]. Zeilenga Standards Track [Page 34] RFC 4512 LDAP Models June 2006 4.2.7. 'dITStructureRules' This attribute lists DIT Structure Rules that are present in the subschema. ( 2.5.21.1 NAME 'dITStructureRules' EQUALITY integerFirstComponentMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.17 USAGE directoryOperation ) The 'integerFirstComponentMatch' matching rule and the DITStructureRuleDescription (1.3.6.1.4.1.1466.115.121.1.17) syntax are defined in [RFC4517]. 4.2.8 'nameForms' This attribute lists Name Forms that are in force. ( 2.5.21.7 NAME 'nameForms' EQUALITY objectIdentifierFirstComponentMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.35 USAGE directoryOperation ) The 'objectIdentifierFirstComponentMatch' matching rule and the NameFormDescription (1.3.6.1.4.1.1466.115.121.1.35) syntax are defined in [RFC4517]. 4.3. 'extensibleObject' object class The 'extensibleObject' auxiliary object class allows entries that belong to it to hold any user attribute. The set of allowed attribute types of this object class is implicitly the set of all attribute types of userApplications usage. ( 1.3.6.1.4.1.1466.101.120.111 NAME 'extensibleObject' SUP top AUXILIARY ) The mandatory attributes of the other object classes of this entry are still required to be present, and any precluded attributes are still not allowed to be present. 4.4. Subschema Discovery To discover the DN of the subschema (sub)entry holding the subschema controlling a particular entry, a client reads that entry's 'subschemaSubentry' operational attribute. To read schema attributes from the subschema (sub)entry, clients MUST issue a Search operation [RFC4511] where baseObject is the DN of the subschema (sub)entry, Zeilenga Standards Track [Page 35] RFC 4512 LDAP Models June 2006 scope is baseObject, filter is "(objectClass=subschema)" [RFC4515], and the attributes field lists the names of the desired schema attributes (as they are operational). Note: the "(objectClass=subschema)" filter allows LDAP servers that gateway to X.500 to detect that subentry information is being requested. Clients SHOULD NOT assume that a published subschema is complete, that the server supports all of the schema elements it publishes, or that the server does not support an unpublished element. 5. DSA (Server) Informational Model The LDAP protocol assumes there are one or more servers that jointly provide access to a Directory Information Tree (DIT). The server holding the original information is called the "master" (for that information). Servers that hold copies of the original information are referred to as "shadowing" or "caching" servers. As defined in [X.501]: context prefix: The sequence of RDNs leading from the Root of the DIT to the initial vertex of a naming context; corresponds to the distinguished name of that vertex. naming context: A subtree of entries held in a single master DSA. That is, a naming context is the largest collection of entries, starting at an entry that is mastered by a particular server, and including all its subordinates and their subordinates, down to the entries that are mastered by different servers. The context prefix is the name of the initial entry. The root of the DIT is a DSA-specific Entry (DSE) and not part of any naming context (or any subtree); each server has different attribute values in the root DSE. 5.1. Server-Specific Data Requirements An LDAP server SHALL provide information about itself and other information that is specific to each server. This is represented as a group of attributes located in the root DSE, which is named with the DN with zero RDNs (whose [RFC4514] representation is as the zero-length string). These attributes are retrievable, subject to access control and other restrictions, if a client performs a Search operation [RFC4511] with an empty baseObject, scope of baseObject, the filter Zeilenga Standards Track [Page 36] RFC 4512 LDAP Models June 2006 "(objectClass=*)" [RFC4515], and the attributes field listing the names of the desired attributes. It is noted that root DSE attributes are operational and, like other operational attributes, are not returned in search requests unless requested by name. The root DSE SHALL NOT be included if the client performs a subtree search starting from the root. Servers may allow clients to modify attributes of the root DSE, where appropriate. The following attributes of the root DSE are defined below. Additional attributes may be defined in other documents. - altServer: alternative servers; - namingContexts: naming contexts; - supportedControl: recognized LDAP controls; - supportedExtension: recognized LDAP extended operations; - supportedFeatures: recognized LDAP features; - supportedLDAPVersion: LDAP versions supported; and - supportedSASLMechanisms: recognized Simple Authentication and Security Layers (SASL) [RFC4422] mechanisms. The values provided for these attributes may depend on session- specific and other factors. For example, a server supporting the SASL EXTERNAL mechanism might only list "EXTERNAL" when the client's identity has been established by a lower level. See [RFC4513]. The root DSE may also include a 'subschemaSubentry' attribute. If it does, the attribute refers to the subschema (sub)entry holding the schema controlling the root DSE. Clients SHOULD NOT assume that this subschema (sub)entry controls other entries held by the server. General subschema discovery procedures are provided in Section 4.4. Zeilenga Standards Track [Page 37] RFC 4512 LDAP Models June 2006 5.1.1. 'altServer' The 'altServer' attribute lists URIs referring to alternative servers that may be contacted when this server becomes unavailable. URIs for servers implementing the LDAP are written according to [RFC4516]. Other kinds of URIs may be provided. If the server does not know of any other servers that could be used, this attribute will be absent. Clients may cache this information in case their preferred server later becomes unavailable. ( 1.3.6.1.4.1.1466.101.120.6 NAME 'altServer' SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 USAGE dSAOperation ) The IA5String (1.3.6.1.4.1.1466.115.121.1.26) syntax is defined in [RFC4517]. 5.1.2. 'namingContexts' The 'namingContexts' attribute lists the context prefixes of the naming contexts the server masters or shadows (in part or in whole). If the server is a first-level DSA [X.501], it should list (in addition) an empty string (indicating the root of the DIT). If the server does not master or shadow any information (e.g., it is an LDAP gateway to a public X.500 directory) this attribute will be absent. If the server believes it masters or shadows the entire directory, the attribute will have a single value, and that value will be the empty string (indicating the root of the DIT). This attribute may be used, for example, to select a suitable entry name for subsequent operations with this server. ( 1.3.6.1.4.1.1466.101.120.5 NAME 'namingContexts' SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 USAGE dSAOperation ) The DistinguishedName (1.3.6.1.4.1.1466.115.121.1.12) syntax is defined in [RFC4517]. 5.1.3. 'supportedControl' The 'supportedControl' attribute lists object identifiers identifying the request controls [RFC4511] the server supports. If the server does not support any request controls, this attribute will be absent. Object identifiers identifying response controls need not be listed. Procedures for registering object identifiers used to discovery of protocol mechanisms are detailed in BCP 64, RFC 4520 [RFC4520]. Zeilenga Standards Track [Page 38] RFC 4512 LDAP Models June 2006 ( 1.3.6.1.4.1.1466.101.120.13 NAME 'supportedControl' SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 USAGE dSAOperation ) The OBJECT IDENTIFIER (1.3.6.1.4.1.1466.115.121.1.38) syntax is defined in [RFC4517]. 5.1.4. 'supportedExtension' The 'supportedExtension' attribute lists object identifiers identifying the extended operations [RFC4511] that the server supports. If the server does not support any extended operations, this attribute will be absent. An extended operation generally consists of an extended request and an extended response but may also include other protocol data units (such as intermediate responses). The object identifier assigned to the extended request is used to identify the extended operation. Other object identifiers used in the extended operation need not be listed as values of this attribute. Procedures for registering object identifiers used to discovery of protocol mechanisms are detailed in BCP 64, RFC 4520 [RFC4520]. ( 1.3.6.1.4.1.1466.101.120.7 NAME 'supportedExtension' SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 USAGE dSAOperation ) The OBJECT IDENTIFIER (1.3.6.1.4.1.1466.115.121.1.38) syntax is defined in [RFC4517]. 5.1.5. 'supportedFeatures' The 'supportedFeatures' attribute lists object identifiers identifying elective features that the server supports. If the server does not support any discoverable elective features, this attribute will be absent. ( 1.3.6.1.4.1.4203.1.3.5 NAME 'supportedFeatures' EQUALITY objectIdentifierMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 USAGE dSAOperation ) Procedures for registering object identifiers used to discovery of protocol mechanisms are detailed in BCP 64, RFC 4520 [RFC4520]. The OBJECT IDENTIFIER (1.3.6.1.4.1.1466.115.121.1.38) syntax and objectIdentifierMatch matching rule are defined in [RFC4517]. Zeilenga Standards Track [Page 39] RFC 4512 LDAP Models June 2006 5.1.6. 'supportedLDAPVersion' The 'supportedLDAPVersion' attribute lists the versions of LDAP that the server supports. ( 1.3.6.1.4.1.1466.101.120.15 NAME 'supportedLDAPVersion' SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 USAGE dSAOperation ) The INTEGER (1.3.6.1.4.1.1466.115.121.1.27) syntax is defined in [RFC4517]. 5.1.7. 'supportedSASLMechanisms' The 'supportedSASLMechanisms' attribute lists the SASL mechanisms [RFC4422] that the server recognizes and/or supports [RFC4513]. The contents of this attribute may depend on the current session state. If the server does not support any SASL mechanisms, this attribute will not be present. ( 1.3.6.1.4.1.1466.101.120.14 NAME 'supportedSASLMechanisms' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 USAGE dSAOperation ) The Directory String (1.3.6.1.4.1.1466.115.121.1.15) syntax is defined in [RFC4517]. 6. Other Considerations 6.1. Preservation of User Information Syntaxes may be defined that have specific value and/or value form (representation) preservation requirements. For example, a syntax containing digitally signed data can mandate that the server preserve both the value and form of value presented to ensure that the signature is not invalidated. Where such requirements have not been explicitly stated, servers SHOULD preserve the value of user information but MAY return the value in a different form. And where a server is unable (or unwilling) to preserve the value of user information, the server SHALL ensure that an equivalent value (per Section 2.3) is returned. Zeilenga Standards Track [Page 40] RFC 4512 LDAP Models June 2006 6.2. Short Names Short names, also known as descriptors, are used as more readable aliases for object identifiers and are used to identify various schema elements. However, it is not expected that LDAP implementations with human user interface would display these short names (or the object identifiers they refer to) to the user. Instead, they would most likely be performing translations (such as expressing the short name in one of the local national languages). For example, the short name "st" (stateOrProvinceName) might be displayed to a German-speaking user as "Land". The same short name might have different meaning in different subschemas, and, within a particular subschema, the same short name might refer to different object identifiers each identifying a different kind of schema element. Implementations MUST be prepared that the same short name might be used in a subschema to refer to the different kinds of schema elements. That is, there might be an object class 'x-fubar' and an attribute type 'x-fubar' in a subschema. Implementations MUST be prepared that the same short name might be used in the different subschemas to refer to the different schema elements. That is, there might be two matching rules 'x-fubar', each in different subschemas. Procedures for registering short names (descriptors) are detailed in BCP 64, RFC 4520 [RFC4520]. 6.3. Cache and Shadowing Some servers may hold cache or shadow copies of entries, which can be used to answer search and comparison queries, but will return referrals or contact other servers if modification operations are requested. Servers that perform shadowing or caching MUST ensure that they do not violate any access control constraints placed on the data by the originating server. Zeilenga Standards Track [Page 41] RFC 4512 LDAP Models June 2006 7. Implementation Guidelines 7.1. Server Guidelines Servers MUST recognize all names of attribute types and object classes defined in this document but, unless stated otherwise, need not support the associated functionality. Servers SHOULD recognize all the names of attribute types and object classes defined in Section 3 and 4, respectively, of [RFC4519]. Servers MUST ensure that entries conform to user and system schema rules or other data model constraints. Servers MAY support DIT Content Rules. Servers MAY support DIT Structure Rules and Name Forms. Servers MAY support alias entries. Servers MAY support the 'extensibleObject' object class. Servers MAY support subentries. If so, they MUST do so in accordance with [RFC3672]. Servers that do not support subentries SHOULD use object entries to mimic subentries as detailed in Section 3.2. Servers MAY implement additional schema elements. Servers SHOULD provide definitions of all schema elements they support in subschema (sub)entries. 7.2. Client Guidelines In the absence of prior agreements with servers, clients SHOULD NOT assume that servers support any particular schema elements beyond those referenced in Section 7.1. The client can retrieve subschema information as described in Section 4.4. Clients MUST NOT display or attempt to decode a value as ASN.1 if the value's syntax is not known. Clients MUST NOT assume the LDAP- specific string encoding is restricted to a UTF-8 encoded string of Unicode characters or any particular subset of Unicode (such as a printable subset) unless such restriction is explicitly stated. Clients SHOULD NOT send attribute values in a request that are not valid according to the syntax defined for the attributes. Zeilenga Standards Track [Page 42] RFC 4512 LDAP Models June 2006 8. Security Considerations Attributes of directory entries are used to provide descriptive information about the real-world objects they represent, which can be people, organizations, or devices. Most countries have privacy laws regarding the publication of information about people. General security considerations for accessing directory information with LDAP are discussed in [RFC4511] and [RFC4513]. 9. IANA Considerations The Internet Assigned Numbers Authority (IANA) has updated the LDAP descriptors registry as indicated in the following template: Subject: Request for LDAP Descriptor Registration Update Descriptor (short name): see comment Object Identifier: see comment Person & email address to contact for further information: Kurt Zeilenga <kurt@OpenLDAP.org> Usage: see comment Specification: RFC 4512 Author/Change Controller: IESG Comments: The following descriptors (short names) has been added to the registry. NAME Type OID ------------------------ ---- ----------------- governingStructureRule A 2.5.21.10 structuralObjectClass A 2.5.21.9 The following descriptors (short names) have been updated to refer to this RFC. NAME Type OID ------------------------ ---- ----------------- alias O 2.5.6.1 aliasedObjectName A 2.5.4.1 altServer A 1.3.6.1.4.1.1466.101.120.6 attributeTypes A 2.5.21.5 createTimestamp A 2.5.18.1 creatorsName A 2.5.18.3 dITContentRules A 2.5.21.2 dITStructureRules A 2.5.21.1 extensibleObject O 1.3.6.1.4.1.1466.101.120.111 ldapSyntaxes A 1.3.6.1.4.1.1466.101.120.16 Zeilenga Standards Track [Page 43] RFC 4512 LDAP Models June 2006 matchingRuleUse A 2.5.21.8 matchingRules A 2.5.21.4 modifiersName A 2.5.18.4 modifyTimestamp A 2.5.18.2 nameForms A 2.5.21.7 namingContexts A 1.3.6.1.4.1.1466.101.120.5 objectClass A 2.5.4.0 objectClasses A 2.5.21.6 subschema O 2.5.20.1 subschemaSubentry A 2.5.18.10 supportedControl A 1.3.6.1.4.1.1466.101.120.13 supportedExtension A 1.3.6.1.4.1.1466.101.120.7 supportedFeatures A 1.3.6.1.4.1.4203.1.3.5 supportedLDAPVersion A 1.3.6.1.4.1.1466.101.120.15 supportedSASLMechanisms A 1.3.6.1.4.1.1466.101.120.14 top O 2.5.6.0 10. Acknowledgements This document is based in part on RFC 2251 by M. Wahl, T. Howes, and S. Kille; RFC 2252 by M. Wahl, A. Coulbeck, T. Howes, S. Kille; and RFC 2556 by M. Wahl, all products of the IETF Access, Searching and Indexing of Directories (ASID) Working Group. This document is also based in part on "The Directory: Models" [X.501], a product of the International Telephone Union (ITU). Additional text was borrowed from RFC 2253 by M. Wahl, T. Howes, and S. Kille. This document is a product of the IETF LDAP Revision (LDAPBIS) Working Group. Zeilenga Standards Track [Page 44] RFC 4512 LDAP Models June 2006 11. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003. [RFC3671] Zeilenga, K., "Collective Attributes in the Lightweight Directory Access Protocol (LDAP)", RFC 3671, December 2003. [RFC3672] Zeilenga, K., "Subentries in the Lightweight Directory Access Protocol (LDAP)", RFC 3672, December 2003. [RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 4234, October 2005. [RFC4422] Melnikov, A., Ed. and K. Zeilenga, Ed., "Simple Authentication and Security Layer (SASL)", RFC 4422, June 2006. [RFC4510] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006. [RFC4511] Sermersheim, J., Ed., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006. [RFC4513] Harrison, R., Ed., "Lightweight Directory Access Protocol (LDAP): Authentication Methods and Security Mechanisms", RFC 4513, June 2006. [RFC4514] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names", RFC 4514, June 2006. [RFC4515] Smith, M., Ed. and T. Howes, "Lightweight Directory Access Protocol (LDAP): String Representation of Search Filters", RFC 4515, June 2006. [RFC4516] Smith, M., Ed. and T. Howes, "Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator", RFC 4516, June 2006. [RFC4517] Legg, S., Ed., "Lightweight Directory Access Protocol (LDAP): Syntaxes and Matching Rules", RFC 4517, June 2006. Zeilenga Standards Track [Page 45] RFC 4512 LDAP Models June 2006 [RFC4519] Sciberras, A., Ed., "Lightweight Directory Access Protocol (LDAP): Schema for User Applications", RFC 4519, June 2006. [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006. [Unicode] The Unicode Consortium, "The Unicode Standard, Version 3.2.0" is defined by "The Unicode Standard, Version 3.0" (Reading, MA, Addison-Wesley, 2000. ISBN 0-201- 61633-5), as amended by the "Unicode Standard Annex #27: Unicode 3.1" (http://www.unicode.org/reports/tr27/) and by the "Unicode Standard Annex #28: Unicode 3.2" (http://www.unicode.org/reports/tr28/). [X.500] International Telecommunication Union - Telecommunication Standardization Sector, "The Directory -- Overview of concepts, models and services," X.500(1993) (also ISO/IEC 9594-1:1994). [X.501] International Telecommunication Union - Telecommunication Standardization Sector, "The Directory -- Models," X.501(1993) (also ISO/IEC 9594- 2:1994). [X.680] International Telecommunication Union - Telecommunication Standardization Sector, "Abstract Syntax Notation One (ASN.1) - Specification of Basic Notation", X.680(2002) (also ISO/IEC 8824-1:2002). Zeilenga Standards Track [Page 46] RFC 4512 LDAP Models June 2006 Appendix A. Changes This appendix is non-normative. This document amounts to nearly a complete rewrite of portions of RFC 2251, RFC 2252, and RFC 2256. This rewrite was undertaken to improve overall clarity of technical specification. This appendix provides a summary of substantive changes made to the portions of these documents incorporated into this document. Readers should consult [RFC4510], [RFC4511], [RFC4517], and [RFC4519] for summaries of remaining portions of these documents. A.1. Changes to RFC 2251 This document incorporates from RFC 2251, Sections 3.2 and 3.4, and portions of Sections 4 and 6 as summarized below. A.1.1. Section 3.2 of RFC 2251 Section 3.2 of RFC 2251 provided a brief introduction to the X.500 data model, as used by LDAP. The previous specification relied on [X.501] but lacked clarity in how X.500 models are adapted for use by LDAP. This document describes the X.500 data models, as used by LDAP, in greater detail, especially in areas where adaptation is needed. Section 3.2.1 of RFC 2251 described an attribute as "a type with one or more associated values". In LDAP, an attribute is better described as an attribute description, a type with zero or more options, and one or more associated values. Section 3.2.2 of RFC 2251 mandated that subschema subentries contain objectClasses and attributeTypes attributes, yet X.500(93) treats these attributes as optional. While generally all implementations that support X.500(93) subschema mechanisms will provide both of these attributes, it is not absolutely required for interoperability that all servers do. The mandate was removed for consistency with X.500(93). The subschema discovery mechanism was also clarified to indicate that subschema controlling an entry is obtained by reading the (sub)entry referred to by that entry's 'subschemaSubentry' attribute. Zeilenga Standards Track [Page 47] RFC 4512 LDAP Models June 2006 A.1.2. Section 3.4 of RFC 2251 Section 3.4 of RFC 2251 provided "Server-specific Data Requirements". This material, with changes, was incorporated in Section 5.1 of this document. Changes: - Clarify that attributes of the root DSE are subject to "other restrictions" in addition to access controls. - Clarify that only recognized extended requests need to be enumerated 'supportedExtension'. - Clarify that only recognized request controls need to be enumerated 'supportedControl'. - Clarify that root DSE attributes are operational and, like other operational attributes, will not be returned in search requests unless requested by name. - Clarify that not all root DSE attributes are user modifiable. - Remove inconsistent text regarding handling of the 'subschemaSubentry' attribute within the root DSE. The previous specification stated that the 'subschemaSubentry' attribute held in the root DSE referred to "subschema entries (or subentries) known by this server". This is inconsistent with the attribute's intended use as well as its formal definition as a single valued attribute [X.501]. It is also noted that a simple (possibly incomplete) list of subschema (sub)entries is not terribly useful. This document (in Section 5.1) specifies that the 'subschemaSubentry' attribute of the root DSE refers to the subschema controlling the root DSE. It is noted that the general subschema discovery mechanism remains available (see Section 4.4 of this document). A.1.3. Section 4 of RFC 2251 Portions of Section 4 of RFC 2251 detailing aspects of the information model used by LDAP were incorporated in this document, including: - Restriction of distinguished values to attributes whose descriptions have no options (from Section 4.1.3); Zeilenga Standards Track [Page 48] RFC 4512 LDAP Models June 2006 - Data model aspects of Attribute Types (from Section 4.1.4), Attribute Descriptions (from 4.1.5), Attribute (from 4.1.8), Matching Rule Identifier (from 4.1.9); and - User schema requirements (from Sections 4.1.6, 4.5.1, and 4.7). Clarifications to these portions include: - Subtyping and AttributeDescriptions with options. A.1.4. Section 6 of RFC 2251 The Section 6.1 and the second paragraph of Section 6.2 of RFC 2251 where incorporated into this document. A.2. Changes to RFC 2252 This document incorporates Sections 4, 5, and 7 from RFC 2252. A.2.1. Section 4 of RFC 2252 The specification was updated to use Augmented BNF [RFC4234]. The string representation of an OBJECT IDENTIFIER was tightened to disallow leading zeros as described in RFC 2252. The <descr> syntax was changed to disallow semicolon (U+003B) characters in order to appear to be consistent its natural language specification "descr is the syntactic representation of an object descriptor, which consists of letters and digits, starting with a letter". In a related change, the statement "an AttributeDescription can be used as the value in a NAME part of an AttributeTypeDescription" was deleted. RFC 2252 provided no specification of the semantics of attribute options appearing in NAME fields. RFC 2252 stated that the <descr> form of <oid> SHOULD be preferred over the <numericoid> form. However, <descr> form can be ambiguous. To address this issue, the imperative was replaced with a statement (in Section 1.4) that while the <descr> form is generally preferred, <numericoid> should be used where an unambiguous <descr> is not available. Additionally, an expanded discussion of descriptor issues is in Section 6.2 ("Short Names"). The ABNF for a quoted string (qdstring) was updated to reflect support for the escaping mechanism described in Section 4.3 of RFC 2252. Zeilenga Standards Track [Page 49] RFC 4512 LDAP Models June 2006 A.2.2. Section 5 of RFC 2252 Definitions of operational attributes provided in Section 5 of RFC 2252 where incorporated into this document. The 'namingContexts' description was clarified. A first-level DSA should publish, in addition to other values, "" indicating the root of the DIT. The 'altServer' description was clarified. It may hold any URI. The 'supportedExtension' description was clarified. A server need only list the OBJECT IDENTIFIERs associated with the extended requests of the extended operations it recognizes. The 'supportedControl' description was clarified. A server need only list the OBJECT IDENTIFIERs associated with the request controls it recognizes. Descriptions for the 'structuralObjectClass' and 'governingStructureRule' operational attribute types were added. The attribute definition of 'subschemaSubentry' was corrected to list the terms SINGLE-VALUE and NO-USER-MODIFICATION in proper order. A.2.3. Section 7 of RFC 2252 Section 7 of RFC 2252 provides definitions of the 'subschema' and 'extensibleObject' object classes. These definitions where integrated into Section 4.2 and Section 4.3 of this document, respectively. Section 7 of RFC 2252 also contained the object class implementation requirement. This was incorporated into Section 7 of this document. The specification of 'extensibleObject' was clarified regarding how it interacts with precluded attributes. A.3. Changes to RFC 2256 This document incorporates Sections 5.1, 5.2, 7.1, and 7.2 of RFC 2256. Section 5.1 of RFC 2256 provided the definition of the 'objectClass' attribute type. This was integrated into Section 2.4.1 of this document. The statement "One of the values is either 'top' or 'alias'" was replaced with statement that one of the values is 'top' as entries belonging to 'alias' also belong to 'top'. Zeilenga Standards Track [Page 50] RFC 4512 LDAP Models June 2006 Section 5.2 of RFC 2256 provided the definition of the 'aliasedObjectName' attribute type. This was integrated into Section 2.6.2 of this document. Section 7.1 of RFC 2256 provided the definition of the 'top' object class. This was integrated into Section 2.4.1 of this document. Section 7.2 of RFC 2256 provided the definition of the 'alias' object class. This was integrated into Section 2.6.1 of this document. A.4. Changes to RFC 3674 This document made no substantive change to the 'supportedFeatures' technical specification provided in RFC 3674. Editor's Address Kurt D. Zeilenga OpenLDAP Foundation EMail: Kurt@OpenLDAP.org Zeilenga Standards Track [Page 51] RFC 4512 LDAP Models June 2006 Full Copyright Statement Copyright (C) The Internet Society (2006). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Zeilenga Standards Track [Page 52] PK +�c\��}.�7 �7 ( doc/alt-openldap11-devel/rfc/rfc4532.txtnu �[��� Network Working Group K. Zeilenga Request for Comments: 4532 OpenLDAP Foundation Category: Standards Track June 2006 Lightweight Directory Access Protocol (LDAP) "Who am I?" Operation Status of This Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2006). Abstract This specification provides a mechanism for Lightweight Directory Access Protocol (LDAP) clients to obtain the authorization identity the server has associated with the user or application entity. This mechanism is specified as an LDAP extended operation called the LDAP "Who am I?" operation. 1. Background and Intent of Use This specification describes a Lightweight Directory Access Protocol (LDAP) [RFC4510] operation that clients can use to obtain the primary authorization identity, in its primary form, that the server has associated with the user or application entity. The operation is called the "Who am I?" operation. This specification is intended to replace the existing Authorization Identity Controls [RFC3829] mechanism, which uses Bind request and response controls to request and return the authorization identity. Bind controls are not protected by security layers established by the Bind operation that includes them. While it is possible to establish security layers using StartTLS [RFC4511][RFC4513] prior to the Bind operation, it is often desirable to use security layers established by the Bind operation. An extended operation sent after a Bind operation is protected by the security layers established by the Bind operation. Zeilenga Standards Track [Page 1] RFC 4532 LDAP "Who am I?" Operation June 2006 There are other cases where it is desirable to request the authorization identity that the server associated with the client separately from the Bind operation. For example, the "Who am I?" operation can be augmented with a Proxied Authorization Control [RFC4370] to determine the authorization identity that the server associates with the identity asserted in the Proxied Authorization Control. The "Who am I?" operation can also be used prior to the Bind operation. Servers often associate multiple authorization identities with the client, and each authorization identity may be represented by multiple authzId [RFC4513] strings. This operation requests and returns the authzId that the server considers primary. In the specification, the term "the authorization identity" and "the authzId" are generally to be read as "the primary authorization identity" and the "the primary authzId", respectively. 1.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 BCP 14 [RFC2119]. 2. The "Who am I?" Operation The "Who am I?" operation is defined as an LDAP Extended Operation [RFC4511] identified by the whoamiOID Object Identifier (OID). This section details the syntax of the operation's whoami request and response messages. whoamiOID ::= "1.3.6.1.4.1.4203.1.11.3" 2.1. The whoami Request The whoami request is an ExtendedRequest with a requestName field containing the whoamiOID OID and an absent requestValue field. For example, a whoami request could be encoded as the sequence of octets (in hex): 30 1e 02 01 02 77 19 80 17 31 2e 33 2e 36 2e 31 2e 34 2e 31 2e 34 32 30 33 2e 31 2e 31 31 2e 33 Zeilenga Standards Track [Page 2] RFC 4532 LDAP "Who am I?" Operation June 2006 2.2. The whoami Response The whoami response is an ExtendedResponse where the responseName field is absent and the response field, if present, is empty or an authzId [RFC4513]. For example, a whoami response returning the authzId "u:xxyyz@EXAMPLE.NET" (in response to the example request) would be encoded as the sequence of octets (in hex): 30 21 02 01 02 78 1c 0a 01 00 04 00 04 00 8b 13 75 3a 78 78 79 79 7a 40 45 58 41 4d 50 4c 45 2e 4e 45 54 3. Operational Semantics The "Who am I?" operation provides a mechanism, a whoami Request, for the client to request that the server return the authorization identity it currently associates with the client. It also provides a mechanism, a whoami Response, for the server to respond to that request. Servers indicate their support for this extended operation by providing a whoamiOID object identifier as a value of the 'supportedExtension' attribute type in their root DSE. The server SHOULD advertise this extension only when the client is willing and able to perform this operation. If the server is willing and able to provide the authorization identity it associates with the client, the server SHALL return a whoami Response with a success resultCode. If the server is treating the client as an anonymous entity, the response field is present but empty. Otherwise, the server provides the authzId [RFC4513] representing the authorization identity it currently associates with the client in the response field. If the server is unwilling or unable to provide the authorization identity it associates with the client, the server SHALL return a whoami Response with an appropriate non-success resultCode (such as operationsError, protocolError, confidentialityRequired, insufficientAccessRights, busy, unavailable, unwillingToPerform, or other) and an absent response field. As described in [RFC4511] and [RFC4513], an LDAP session has an "anonymous" association until the client has been successfully authenticated using the Bind operation. Clients MUST NOT invoke the "Who am I?" operation while any Bind operation is in progress, including between two Bind requests made as part of a multi-stage Zeilenga Standards Track [Page 3] RFC 4532 LDAP "Who am I?" Operation June 2006 Bind operation. Where a whoami Request is received in violation of this absolute prohibition, the server should return a whoami Response with an operationsError resultCode. 4. Extending the "Who am I?" Operation with Controls Future specifications may extend the "Who am I?" operation using the control mechanism [RFC4511]. When extended by controls, the "Who am I?" operation requests and returns the authorization identity the server associates with the client in a particular context indicated by the controls. 4.1. Proxied Authorization Control The Proxied Authorization Control [RFC4370] is used by clients to request that the operation it is attached to operate under the authorization of an assumed identity. The client provides the identity to assume in the Proxied Authorization request control. If the client is authorized to assume the requested identity, the server executes the operation as if the requested identity had issued the operation. As servers often map the asserted authzId to another identity [RFC4513], it is desirable to request that the server provide the authzId it associates with the assumed identity. When a Proxied Authorization Control is be attached to the "Who am I?" operation, the operation requests the return of the authzId the server associates with the identity asserted in the Proxied Authorization Control. The authorizationDenied (123) result code is used to indicate that the server does not allow the client to assume the asserted identity. 5. Security Considerations Identities associated with users may be sensitive information. When they are, security layers [RFC4511][RFC4513] should be established to protect this information. This mechanism is specifically designed to allow security layers established by a Bind operation to protect the integrity and/or confidentiality of the authorization identity. Servers may place access control or other restrictions upon the use of this operation. As stated in Section 3, the server SHOULD advertise this extension when it is willing and able to perform the operation. As with any other extended operations, general LDAP security considerations [RFC4510] apply. Zeilenga Standards Track [Page 4] RFC 4532 LDAP "Who am I?" Operation June 2006 6. IANA Considerations The OID 1.3.6.1.4.1.4203.1.11.3 is used to identify the LDAP "Who am I?" extended operation. This OID was assigned [ASSIGN] by the OpenLDAP Foundation, under its IANA-assigned private enterprise allocation [PRIVATE], for use in this specification. Registration of this protocol mechanism [RFC4520] has been completed by the IANA. Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: 1.3.6.1.4.1.4203.1.11.3 Description: Who am I? Person & email address to contact for further information: Kurt Zeilenga <kurt@openldap.org> Usage: Extended Operation Specification: RFC 4532 Author/Change Controller: IESG Comments: none 7. Acknowledgement This document borrows from prior work in this area, including "Authentication Response Control" [RFC3829] by Rob Weltman, Mark Smith, and Mark Wahl. The LDAP "Who am I?" operation takes it's name from the UNIX whoami(1) command. The whoami(1) command displays the effective user ID. 8. References 8.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC4370] Weltman, R., "Lightweight Directory Access Protocol (LDAP) Proxied Authorization Control", RFC 4370, February 2006. [RFC4510] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006. [RFC4511] Sermersheim, J., Ed., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006. Zeilenga Standards Track [Page 5] RFC 4532 LDAP "Who am I?" Operation June 2006 [RFC4513] Harrison, R., Ed., "Lightweight Directory Access Protocol (LDAP): Authentication Methods and Security Mechanisms", RFC 4513, June 2006. 8.2. Informative References [RFC3829] Weltman, R., Smith, M., and M. Wahl, "Lightweight Directory Access Protocol (LDAP) Authorization Identity Request and Response Controls", RFC 3829, July 2004. [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006. [ASSIGN] OpenLDAP Foundation, "OpenLDAP OID Delegations", http://www.openldap.org/foundation/oid-delegate.txt. [PRIVATE] IANA, "Private Enterprise Numbers", http://www.iana.org/assignments/enterprise-numbers. Author's Address Kurt D. Zeilenga OpenLDAP Foundation EMail: Kurt@OpenLDAP.org Zeilenga Standards Track [Page 6] RFC 4532 LDAP "Who am I?" Operation June 2006 Full Copyright Statement Copyright (C) The Internet Society (2006). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Zeilenga Standards Track [Page 7] PK +�c\ϩ�� 2 2 ( doc/alt-openldap11-devel/rfc/rfc2696.txtnu �[��� Network Working Group C. Weider Request for Comments: 2696 A. Herron Category: Informational A. Anantha Microsoft T. Howes Netscape September 1999 LDAP Control Extension for Simple Paged Results Manipulation Status of this Memo This memo provides information for the Internet community. It does not specify an Internet standard of any kind. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (1999). All Rights Reserved. 1. Abstract This document describes an LDAPv3 control extension for simple paging of search results. This control extension allows a client to control the rate at which an LDAP server returns the results of an LDAP search operation. This control may be useful when the LDAP client has limited resources and may not be able to process the entire result set from a given LDAP query, or when the LDAP client is connected over a low-bandwidth connection. Other operations on the result set are not defined in this extension. This extension is not designed to provide more sophisticated result set management. The key words "MUST", "SHOULD", and "MAY" used in this document are to be interpreted as described in [bradner97]. 2. The Control This control is included in the searchRequest and searchResultDone messages as part of the controls field of the LDAPMessage, as defined in Section 4.1.12 of [LDAPv3]. The structure of this control is as follows: Weider, et al. Informational [Page 1] RFC 2696 LDAP Control Ext. for Simple Paged Results September 1999 pagedResultsControl ::= SEQUENCE { controlType 1.2.840.113556.1.4.319, criticality BOOLEAN DEFAULT FALSE, controlValue searchControlValue } The searchControlValue is an OCTET STRING wrapping the BER-encoded version of the following SEQUENCE: realSearchControlValue ::= SEQUENCE { size INTEGER (0..maxInt), -- requested page size from client -- result set size estimate from server cookie OCTET STRING } 3. Client-Server Interaction An LDAP client application that needs to control the rate at which results are returned MAY specify on the searchRequest a pagedResultsControl with size set to the desired page size and cookie set to the zero-length string. The page size specified MAY be greater than zero and less than the sizeLimit value specified in the searchRequest. If the page size is greater than or equal to the sizeLimit value, the server should ignore the control as the request can be satisfied in a single page. If the server does not support this control, the server MUST return an error of unsupportedCriticalExtension if the client requested it as critical, otherwise the server SHOULD ignore the control. The remainder of this section assumes the server does not ignore the client's pagedResultsControl. Each time the server returns a set of results to the client when processing a search request containing the pagedResultsControl, the server includes the pagedResultsControl control in the searchResultDone message. In the control returned to the client, the size MAY be set to the server's estimate of the total number of entries in the entire result set. Servers that cannot provide such an estimate MAY set this size to zero (0). The cookie MUST be set to an empty value if there are no more entries to return (i.e., the page of search results returned was the last), or, if there are more entries to return, to an octet string of the server's choosing,used to resume the search. The client MUST consider the cookie to be an opaque structure and make no assumptions about its internal organization or value. When the client wants to retrieve more entries for the result set, it MUST Weider, et al. Informational [Page 2] RFC 2696 LDAP Control Ext. for Simple Paged Results September 1999 send to the server a searchRequest with all values identical to the initial request with the exception of the messageID, the cookie, and optionally a modified pageSize. The cookie MUST be the octet string on the last searchResultDone response returned by the server. Returning cookies from previous searchResultDone responses besides the last one is undefined, as the server implementation may restrict cookies from being reused. The server will then return the next set of results from the whole result set. This interaction will continue until the client has retrieved all the results, in which case the cookie in the searchResultDone field will be empty, or until the client abandons the search sequence as described below. Once the paged search sequence has been completed, the cookie is no longer valid and MUST NOT be used. A sequence of paged search requests is abandoned by the client sending a search request containing a pagedResultsControl with the size set to zero (0) and the cookie set to the last cookie returned by the server. A client MAY use the LDAP Abandon operation to abandon one paged search request in progress, but this is discouraged as it MAY invalidate the client's cookie. If, for any reason, the server cannot resume a paged search operation for a client, then it SHOULD return the appropriate error in a searchResultDone entry. If this occurs, both client and server should assume the paged result set is closed and no longer resumable. A client may have any number of outstanding search requests pending, any of which may have used the pagedResultsControl. A server implementation which requires a limit on the number of outstanding paged search requests from a given client MAY either return unwillingToPerform when the client attempts to create a new paged search request, or age out an older result set. If the server implementation ages out an older paged search request, it SHOULD return "unwilling to perform" if the client attempts to resume the paged search that was aged out. A client may safely assume that all entries that satisfy a given search query are returned once and only once during the set of paged search requests/responses necessary to enumerate the entire result set, unless the result set for that query has changed since the searchRequest starting the request/response sequence was processed. In that case, the client may receive a given entry multiple times and/or may not receive all entries matching the given search criteria. Weider, et al. Informational [Page 3] RFC 2696 LDAP Control Ext. for Simple Paged Results September 1999 4. Example The following example illustrates the client-server interaction between a client doing a search requesting a page size limit of 3. The entire result set returned by the server contains 5 entries. Lines beginning with "C:" indicate requests sent from client to server. Lines beginning with "S:" indicate responses sent from server to client. Lines beginning with "--" are comments to help explain the example. -- Client sends a search request asking for paged results -- with a page size of 3. C: SearchRequest + pagedResultsControl(3,"") -- Server responds with three entries plus an indication -- of 5 total entries in the search result and an opaque -- cooking to be used by the client when retrieving subsequent -- pages. S: SearchResultEntry S: SearchResultEntry S: SearchResultEntry S: SearchResultDone + pagedResultsControl(5, "opaque") -- Client sends an identical search request (except for -- message id), returning the opaque cooking, asking for -- the next page. C: SearchRequest + PagedResultsControl(3, "opaque") -- Server responds with two entries plus an indication -- that there are no more entries (null cookie). S: SearchResultEntry S: SearchResultEntry S: SearchResultDone + pagedResultsControl(5,"") 5. Relationship to X.500 For LDAP servers providing a front end to X.500 (93) directories, the paged results control defined in this document may be mapped directly onto the X.500 (93) PagedResultsRequest defined in X.511 [x500]. The size parameter may be mapped onto pageSize. The cookie parameter may be mapped onto queryReference. The sortKeys and reverse fields in the X.500 PagedResultsRequest are excluded. Weider, et al. Informational [Page 4] RFC 2696 LDAP Control Ext. for Simple Paged Results September 1999 6. Security Considerations Server implementors should consider the resources used when clients send searches with the simple paged control, to ensure that a client's misuse of this control does not lock out other legitimate operations. Servers implementations may enforce an overriding sizelimit, to prevent the retrieval of large portions of a publically-accessible directory. Clients can, using this control, determine how many entries match a particular filter, before the entries are returned to the client. This may require special processing in servers which perform access control checks on entries to determine whether the existence of the entry can be disclosed to the client. 7. References [LDAPv3] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [Bradner97] Bradner, S., "Key Words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. Weider, et al. Informational [Page 5] RFC 2696 LDAP Control Ext. for Simple Paged Results September 1999 8. Authors' Addresses Chris Weider Microsoft Corp. 1 Microsoft Way Redmond, WA 98052 USA Phone: +1 425 882-8080 EMail: cweider@microsoft.com Andy Herron Microsoft Corp. 1 Microsoft Way Redmond, WA 98052 USA Phone: +1 425 882-8080 EMail: andyhe@microsoft.com Anoop Anantha Microsoft Corp. 1 Microsoft Way Redmond, WA 98052 USA Phone: +1 425 882-8080 EMail: anoopa@microsoft.com Tim Howes Netscape Communications Corp. 501 E. Middlefield Road Mountain View, CA 94043 USA Phone: +1 415 937-2600 EMail: howes@netscape.com Weider, et al. Informational [Page 6] RFC 2696 LDAP Control Ext. for Simple Paged Results September 1999 9. Full Copyright Statement Copyright (C) The Internet Society (1999). 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. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Weider, et al. Informational [Page 7] PK +�c\���]� ]� ( doc/alt-openldap11-devel/rfc/rfc3712.txtnu �[��� Network Working Group P. Fleming Request for Comments: 3712 IBM Category: Informational I. McDonald High North February 2004 Lightweight Directory Access Protocol (LDAP): Schema for Printer Services Status of this Memo This memo provides information for the Internet community. It does not specify an Internet standard of any kind. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2004). All Rights Reserved. Abstract This document defines a schema, object classes and attributes, for printers and printer services, for use with directories that support Lightweight Directory Access Protocol v3 (LDAP-TS). This document is based on the printer attributes listed in Appendix E of Internet Printing Protocol/1.1 (IPP) (RFC 2911). A few additional printer attributes are based on definitions in the Printer MIB (RFC 1759). Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Rationale for using DirectoryString Syntax . . . . . . . 3 1.2. Rationale for using caseIgnoreMatch. . . . . . . . . . . 4 1.3. Rationale for using caseIgnoreSubstringsMatch. . . . . . 5 2. Terminology and Conventions. . . . . . . . . . . . . . . . . . 5 3. Definition of Object Classes . . . . . . . . . . . . . . . . . 6 3.1. slpServicePrinter. . . . . . . . . . . . . . . . . . . . 6 3.2. printerAbstract. . . . . . . . . . . . . . . . . . . . . 7 3.3. printerService . . . . . . . . . . . . . . . . . . . . . 8 3.4. printerServiceAuxClass . . . . . . . . . . . . . . . . . 8 3.5. printerIPP . . . . . . . . . . . . . . . . . . . . . . . 8 3.6. printerLPR . . . . . . . . . . . . . . . . . . . . . . . 9 4. Definition of Attribute Types. . . . . . . . . . . . . . . . . 9 4.1. printer-uri. . . . . . . . . . . . . . . . . . . . . . . 11 4.2. printer-xri-supported. . . . . . . . . . . . . . . . . . 11 4.3. printer-name . . . . . . . . . . . . . . . . . . . . . . 13 4.4. printer-natural-language-configured. . . . . . . . . . . 13 Fleming & McDonald Informational [Page 1] RFC 3712 LDAP Schema for Printer Services February 2004 4.5. printer-location . . . . . . . . . . . . . . . . . . . . 14 4.6. printer-info . . . . . . . . . . . . . . . . . . . . . . 14 4.7. printer-more-info. . . . . . . . . . . . . . . . . . . . 14 4.8. printer-make-and-model . . . . . . . . . . . . . . . . . 15 4.9. printer-ipp-versions-supported . . . . . . . . . . . . . 15 4.10. printer-multiple-document-jobs-supported . . . . . . . . 16 4.11. printer-charset-configured . . . . . . . . . . . . . . . 16 4.12. printer-charset-supported. . . . . . . . . . . . . . . . 16 4.13. printer-generated-natural-language-supported . . . . . . 17 4.14. printer-document-format-supported. . . . . . . . . . . . 17 4.15. printer-color-supported. . . . . . . . . . . . . . . . . 18 4.16. printer-compression-supported. . . . . . . . . . . . . . 18 4.17. printer-pages-per-minute . . . . . . . . . . . . . . . . 18 4.18. printer-pages-per-minute-color . . . . . . . . . . . . . 19 4.19. printer-finishings-supported . . . . . . . . . . . . . . 19 4.20. printer-number-up-supported. . . . . . . . . . . . . . . 19 4.21. printer-sides-supported. . . . . . . . . . . . . . . . . 20 4.22. printer-media-supported. . . . . . . . . . . . . . . . . 20 4.23. printer-media-local-supported. . . . . . . . . . . . . . 20 4.24. printer-resolution-supported . . . . . . . . . . . . . . 21 4.25. printer-print-quality-supported. . . . . . . . . . . . . 22 4.26. printer-job-priority-supported . . . . . . . . . . . . . 22 4.27. printer-copies-supported . . . . . . . . . . . . . . . . 22 4.28. printer-job-k-octets-supported . . . . . . . . . . . . . 23 4.29. printer-current-operator . . . . . . . . . . . . . . . . 23 4.30. printer-service-person . . . . . . . . . . . . . . . . . 24 4.31. printer-delivery-orientation-supported . . . . . . . . . 24 4.32. printer-stacking-order-supported . . . . . . . . . . . . 24 4.33. printer-output-features-supported. . . . . . . . . . . . 25 4.34. printer-aliases. . . . . . . . . . . . . . . . . . . . . 25 5. Definition of Syntaxes . . . . . . . . . . . . . . . . . . . . 26 6. Definition of Matching Rules . . . . . . . . . . . . . . . . . 26 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 7.1. Registration of Object Classes . . . . . . . . . . . . . 26 7.2. Registration of Attribute Types. . . . . . . . . . . . . 27 8. Internationalization Considerations. . . . . . . . . . . . . . 28 9. Security Considerations. . . . . . . . . . . . . . . . . . . . 29 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 29 10.1. Normative References . . . . . . . . . . . . . . . . . . 29 10.2. Informative References . . . . . . . . . . . . . . . . . 30 11. Acknowledgments. . . . . . . . . . . . . . . . . . . . . . . . 32 12. Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 32 13. Full Copyright Statement . . . . . . . . . . . . . . . . . . . 33 Fleming & McDonald Informational [Page 2] RFC 3712 LDAP Schema for Printer Services February 2004 1. Introduction This document defines several object classes to provide Lightweight Directory Access Protocol v3 [LDAP-TS] applications with flexible options in defining printer information using LDAP schema. Classes are provided for defining directory entries with common printer information as well as for extending existing directory entries with SLPv2 [RFC2608], IPP/1.1 [RFC2911], and LPR [RFC1179] specific information. The schema defined in this document is based on the printer attributes listed in Appendix E 'Generic Directory Schema' of Internet Printing Protocol/1.1 (IPP) [RFC2911]. A few additional printer attributes are based on definitions in the Printer MIB [RFC1759]. The schema defined in this document is technically aligned with the stable IANA-registered 'service:printer:' v2.0 template [SLP-PRT], for compatibility with already deployed Service Location Protocol (SLPv2) [RFC2608] service advertising and discovery infrastructure. The attribute syntaxes are technically aligned with the 'service:printer:' v2.0 template - therefore simpler types are sometimes used (for example, 'DirectoryString' [RFC2252] rather than 'labeledURI' [RFC2079] for the 'printer-uri' attribute). Please send comments directly to the authors at the addresses listed in Section 13 "Authors' Addresses". 1.1. Rationale for using DirectoryString Syntax The attribute syntax 'DirectoryString' (UTF-8 [RFC2279]) defined in [RFC2252] is specified for several groups of string attributes that are defined in this document: 1) URI - printer-uri, printer-xri-supported, printer-more-info The UTF-8 encoding is forward compatible with any future deployment of (UTF-8 based) IRI (Internationalized Resource Identifiers) [W3C-IRI] currently being developed by the W3C Internationalization Working Group. 2) Description - printer-name, printer-location, printer-info, printer-make-and-model Fleming & McDonald Informational [Page 3] RFC 3712 LDAP Schema for Printer Services February 2004 The UTF-8 encoding supports descriptions in any language, conformant with the "IETF Policy on Character Sets and Languages" [RFC2277]. Note: The printer-natural-language-configured attribute contains a language tag [RFC3066] for these description attributes (for example, to support text-to-speech conversions). 3) Keyword - printer-compression-supported, printer-finishings-supported, printer-media-supported, printer-media-local-supported, printer-print-quality-supported The UTF-8 encoding is compatible with the current IPP/1.1 [RFC2911] definition of the equivalent attributes, most of which have the IPP/1.1 union syntax 'keyword or name'. The keyword attributes defined in this document are extensible by site-specific or vendor-specific 'names' which behave like new 'keywords' Note: In IPP/1.1, each value is strongly typed over-the-wire as either 'keyword' or 'name'. This union selector is not preserved in the definitions of these equivalent LDAP attributes. 1.2. Rationale for using caseIgnoreMatch The EQUALITY matching rule 'caseIgnoreMatch' defined in [RFC2252] is specified for several groups of string attributes that are defined in this document: 1) URI These URI attributes specify EQUALITY matching with 'caseIgnoreMatch' (rather than with 'caseExactMatch') in order to conform to the spirit of [RFC2396], which requires case insensitive matching on the host part of a URI versus case sensitive matching on the remainder of a URI. These URI attributes follow existing practice of supporting case insensitive equality matching for host names in the associatedDomain attribute defined in [RFC1274]. Either equality matching rule choice would be a compromise: a) case sensitive whole URI matching may lead to false negative matches and has been shown to be fragile (given deployed client applications that 'pretty up' host names displayed and transferred in URI); Fleming & McDonald Informational [Page 4] RFC 3712 LDAP Schema for Printer Services February 2004 b) case insensitive whole URI matching may lead to false positive matches, although it is a dangerous practice to publish URI that differ only by case (for example, in the path elements). 2) Description Case insensitive equality matching is more user-friendly for description attributes. 3) Keyword Case insensitive equality matching is more user-friendly for keyword attributes. 1.3. Rationale for using caseIgnoreSubstringsMatch The SUBSTR matching rule 'caseIgnoreSubstringsMatch' defined in [RFC2252] is specified for several groups of string attributes that are defined in this document: 1) URI These URI attributes follow existing practice of supporting case insensitive equality matching for host names in the associatedDomain attribute defined in [RFC1274]. 2) Description Support for case insensitive substring matching is more user-friendly for description attributes. 3) Keyword Support for case insensitive substring matching is more user-friendly for keyword attributes. 2. Terminology and Conventions 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 LDAPv3 [LDAP-TS] description formats. Definitions provided here are formatted (line wrapped) for readability. Fleming & McDonald Informational [Page 5] RFC 3712 LDAP Schema for Printer Services February 2004 3. Definition of Object Classes We define the following LDAP object classes for use with both generic printer related information and services specific to SLPv2 [RFC2608], IPP/1.1 [RFC2911], and LPR [RFC1179]. slpServicePrinter - auxiliary class for SLP registered printers printerAbstract - abstract class for all printer classes printerService - structural class for printers printerServiceAuxClass - auxiliary class for printers printerIPP - auxiliary class for IPP printers printerLPR - auxiliary class for LPR printers The following are some examples of how applications may choose to use these classes when creating directory entries: 1) Use printerService for directory entries containing common printer information. 2) Use both printerService and slpServicePrinter for directory entries containing common printer information for SLP registered printers. 3) Use printerService, printerLPR and printerIPP for directory entries containing common printer information for printers that support both LPR and IPP. 4) Use printerServiceAuxClass and object classes not defined by this document for directory entries containing common printer information. In this example, printerServiceAuxClass is used for extending other structural classes defining printer information with common printer information defined in this document. Refer to Section 4 for definition of attribute types referenced by these object classes. We use attribute names instead of OIDs in object class definitions for clarity. Some attribute names described in [RFC2911] have been prefixed with 'printer-' as recommended in [RFC2926] and [SLP-PRT]. 3.1. slpServicePrinter ( 1.3.18.0.2.6.254 NAME 'slpServicePrinter' DESC 'Service Location Protocol (SLP) information.' AUXILIARY SUP slpService ) Fleming & McDonald Informational [Page 6] RFC 3712 LDAP Schema for Printer Services February 2004 This auxiliary class defines Service Location Protocol (SLPv2) [RFC2608] specific information. It should be used with a structural class such as printerService. It may be used to create new or extend existing directory entries with SLP 'service:printer' abstract service type information as defined in [SLP-PRT]. This object class is derived from 'slpService', the parent class for all SLP services, defined in [RFC2926]. 3.2. printerAbstract ( 1.3.18.0.2.6.258 NAME 'printerAbstract' DESC 'Printer related information.' ABSTRACT SUP top MAY ( printer-name $ printer-natural-language-configured $ printer-location $ printer-info $ printer-more-info $ printer-make-and-model $ printer-multiple-document-jobs-supported $ printer-charset-configured $ printer-charset-supported $ printer-generated-natural-language-supported $ printer-document-format-supported $ printer-color-supported $ printer-compression-supported $ printer-pages-per-minute $ printer-pages-per-minute-color $ printer-finishings-supported $ printer-number-up-supported $ printer-sides-supported $ printer-media-supported $ printer-media-local-supported $ printer-resolution-supported $ printer-print-quality-supported $ printer-job-priority-supported $ printer-copies-supported $ printer-job-k-octets-supported $ printer-current-operator $ printer-service-person $ printer-delivery-orientation-supported $ printer-stacking-order-supported $ printer-output-features-supported ) ) This abstract class defines printer information. It is a base class for deriving other printer related classes, such as, but not limited to, classes defined in this document. It defines a common set of printer attributes that are not specific to any one type of service, protocol or operating system. Fleming & McDonald Informational [Page 7] RFC 3712 LDAP Schema for Printer Services February 2004 3.3. printerService ( 1.3.18.0.2.6.255 NAME 'printerService' DESC 'Printer information.' STRUCTURAL SUP printerAbstract MAY ( printer-uri $ printer-xri-supported ) ) This structural class defines printer information. It is derived from class printerAbstract and thus inherits common printer attributes. This class can be used with or without auxiliary classes to define printer information. Auxiliary classes can be used to extend the common printer information with protocol, service or operating system specific information. Note: When extending other structural classes with auxiliary classes, printerService should not be used. 3.4. printerServiceAuxClass ( 1.3.18.0.2.6.257 NAME 'printerServiceAuxClass' DESC 'Printer information.' AUXILIARY SUP printerAbstract MAY ( printer-uri $ printer-xri-supported ) ) This auxiliary class defines printer information. It is derived from class printerAbstract and thus inherits common printer attributes. This class should be used with a structural class. 3.5. printerIPP ( 1.3.18.0.2.6.256 NAME 'printerIPP' DESC 'Internet Printing Protocol (IPP) information.' AUXILIARY SUP top MAY ( printer-ipp-versions-supported $ printer-multiple-document-jobs-supported ) ) Fleming & McDonald Informational [Page 8] RFC 3712 LDAP Schema for Printer Services February 2004 This auxiliary class defines Internet Printing Protocol (IPP/1.1) [RFC2911] information. It should be used with a structural class such as printerService. It is used to extend structural classes with IPP specific printer information. 3.6. printerLPR ( 1.3.18.0.2.6.253 NAME 'printerLPR' DESC 'LPR information.' AUXILIARY SUP top MUST ( printer-name ) MAY ( printer-aliases) ) This auxiliary class defines LPR [RFC1179] information. It should be used with a structural class such as printerService. It is used to identify directory entries that support LPR. 4. Definition of Attribute Types The following attribute types are referenced by the object classes defined in Section 3. The following attribute types reference syntax OIDs defined in Section 6 of [RFC2252] (see Section 5 'Definition of Syntaxes' below). The following attribute types reference matching rule names (instead of OIDs) for clarity (see Section 6 below). For optional attributes, if the printer information is not known, the attribute value should not be set. In the following definitions, referenced matching rules are defined in Section 8 of [RFC2252] and/or Section 2 of [RFC3698] (see Section 6 'Definition of Matching Rules' below). The following table is a summary of the attribute names defined by this document and their corresponding names from [RFC2911]. Some attribute names described in [RFC2911] have been prefixed with 'printer-' as recommended in [RFC2926], to address the flat namespace for LDAP identifiers. Fleming & McDonald Informational [Page 9] RFC 3712 LDAP Schema for Printer Services February 2004 LDAP & SLP Printer Schema IPP Model [RFC2911] ------------------------------ ------------------------------------- printer-uri printer-xri-supported [IPP printer-uri-supported] [IPP uri-authentication-supported] [IPP uri-security-supported] printer-name printer-name printer-natural-language-configured natural-language-configured printer-location printer-location printer-info printer-info printer-more-info printer-more-info printer-make-and-model printer-make-and-model printer-ipp-versions-supported ipp-versions-supported printer-multiple-document-jobs-supported multiple-document-jobs-supported printer-charset-configured charset-configured printer-charset-supported charset-supported printer-generated-natural-language-supported generated-natural-language-supported printer-document-format-supported document-format-supported printer-color-supported color-supported printer-compression-supported compression-supported printer-pages-per-minute pages-per-minute printer-pages-per-minute-color pages-per-minute-color printer-finishings-supported finishings-supported printer-number-up-supported number-up-supported printer-sides-supported sides-supported printer-media-supported media-supported printer-media-local-supported [site names from IPP media-supported] printer-resolution-supported printer-resolution-supported printer-print-quality-supported print-quality-supported printer-job-priority-supported job-priority-supported printer-copies-supported copies-supported printer-job-k-octets-supported job-k-octets-supported printer-current-operator printer-service-person printer-delivery-orientation-supported printer-stacking-order-supported printer-output-features-supported printer-aliases Fleming & McDonald Informational [Page 10] RFC 3712 LDAP Schema for Printer Services February 2004 4.1. printer-uri ( 1.3.18.0.2.4.1140 NAME 'printer-uri' DESC 'A URI supported by this printer.' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) If the printer-xri-supported LDAP attribute is implemented, then this printer-uri value should be listed in printer-xri-supported. Values of URI should conform to [RFC2396], although URI schemes may be defined which do not conform to [RFC2396] (see [RFC2717] and [RFC2718]). Note: LDAP application clients should not attempt to use malformed URI values read from this attribute. LDAP administrative clients should not write malformed URI values into this attribute. Note: For SLP registered printers, the LDAP printer-uri attribute should be set to the value of the SLP-registered URL of the printer, for interworking with SLPv2 [RFC2608] service discovery. Note: See Sections 1.1, 1.2, and 1.3 for rationale for design choices. 4.2. printer-xri-supported ( 1.3.18.0.2.4.1107 NAME 'printer-xri-supported' DESC 'The unordered list of XRI (extended resource identifiers) supported by this printer.' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) A list of XRI (extended resource identifiers) supported by this printer. Each value of this list should consist of a URI (uniform resource identifier) followed by (optional) authentication and security fields. Values of URI should conform to [RFC2396], although URI schemes may be defined which do not conform to [RFC2396] (see [RFC2717] and [RFC2718]). Fleming & McDonald Informational [Page 11] RFC 3712 LDAP Schema for Printer Services February 2004 Note: LDAP application clients should not attempt to use malformed URI values read from this attribute. LDAP administrative clients should not write malformed URI values into this attribute. Note: This attribute is based on 'printer-uri-supported', 'uri- authentication-supported', and `'uri-security-supported' (called the 'Three Musketeers' because they are parallel ordered attributes) defined in IPP/1.1 [RFC2911]. This attribute unfolds those IPP/1.1 attributes and thus avoids the ordering (and same number of values) constraints of the IPP/1.1 separate attributes. Defined keywords for fields include: 'uri' (IPP 'printer-uri-supported') 'auth' (IPP 'uri-authentication-supported') 'sec' (IPP 'uri-security-supported') A missing 'auth' field should be interpreted to mean 'none'. Per IPP/1.1 [RFC2911], defined values of the 'auth' field include: 'none' (no authentication for this URI) 'requesting-user-name' (from operation request) 'basic' (HTTP/1.1 Basic [RFC2617]) 'digest' (HTTP/1.1 Basic, [RFC2617]) 'certificate' (from certificate) A missing 'sec' field should be interpreted to mean 'none'. Per IPP/1.1 [RFC2911], defined values of the 'sec' field include: 'none' (no security for this URI) 'ssl3' (Netscape SSL3) 'tls' (IETF TLS/1.0, [RFC2246]) Each XRI field should be delimited by '<'. For example: 'uri=ipp://foo.com< auth=digest< sec=tls<' 'uri=lpr://bar.com< auth=none< sec=none<' 'uri=mailto:printer@foobar.com< auth=none< sec=none<' Note: The syntax and delimiter for this attribute are aligned with the equivalent attribute in the 'service:printer:' v2.0 template [SLP-PRT]. Whitespace is permitted after (but not before) the delimiter '<'. Note that this delimiter differs from printer- resolution-supported. Note: See Sections 1.1, 1.2, and 1.3 for rationale for design choices. Fleming & McDonald Informational [Page 12] RFC 3712 LDAP Schema for Printer Services February 2004 4.3. printer-name ( 1.3.18.0.2.4.1135 NAME 'printer-name' DESC 'The site-specific administrative name of this printer.' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{127} SINGLE-VALUE ) Values of this attribute should be specified in the language specified in printer-natural-language-configured (for example, to support text-to-speech conversions), although the printer's name may be specified in any language. This name may be the last part of the printer's URI or it may be completely unrelated. This name may contain characters that are not allowed in a conventional URI (see [RFC2396]). 4.4. printer-natural-language-configured ( 1.3.18.0.2.4.1119 NAME 'printer-natural-language-configured' DESC 'The configured natural language in which error and status messages will be generated (by default) by this printer.' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{127} SINGLE-VALUE ) Also, a possible natural language for printer string attributes set by operator, system administrator, or manufacturer. Also, the (declared) natural language of the printer-name, printer-location, printer-info, and printer-make-and-model attributes of this printer. Values of language tags should conform to "Tags for the Identification of Languages" [RFC3066]. For example: 'en-us' (English as spoken in the US) 'fr-fr' (French as spoken in France) For consistency with IPP/1.1 [RFC2911], language tags in this attribute should be lowercase normalized. Fleming & McDonald Informational [Page 13] RFC 3712 LDAP Schema for Printer Services February 2004 4.5. printer-location ( 1.3.18.0.2.4.1136 NAME 'printer-location' DESC 'The physical location of this printer.' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{127} SINGLE-VALUE ) For example: 'Room 123A' 'Second floor of building XYZ' 4.6. printer-info ( 1.3.18.0.2.4.1139 NAME 'printer-info' DESC 'Descriptive information about this printer.' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{127} SINGLE-VALUE ) For example: 'This printer can be used for printing color transparencies for HR presentations' 'Out of courtesy for others, please print only small (1-5 page) jobs at this printer' 'This printer is going away on July 1, 1997, please find a new printer' 4.7. printer-more-info ( 1.3.18.0.2.4.1134 NAME 'printer-more-info' DESC 'A URI for more information about this specific printer.' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) Fleming & McDonald Informational [Page 14] RFC 3712 LDAP Schema for Printer Services February 2004 For example, this could be an HTTP type URI referencing an HTML page accessible to a Web Browser. The information obtained from this URI is intended for end user consumption. Values of URI should conform to [RFC2396], although URI schemes may be defined which do not conform to [RFC2396] (see [RFC2717] and [RFC2718]). Note: LDAP application clients should not attempt to use malformed URI values read from this attribute. LDAP administrative clients should not write malformed URI values into this attribute. Note: See Sections 1.1, 1.2, and 1.3 for rationale for design choices. 4.8. printer-make-and-model ( 1.3.18.0.2.4.1138 NAME 'printer-make-and-model' DESC 'Make and model of this printer.' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{127} SINGLE-VALUE ) Note: The printer manufacturer may initially populate this attribute. 4.9. printer-ipp-versions-supported ( 1.3.18.0.2.4.1133 NAME 'printer-ipp-versions-supported' DESC 'IPP protocol version(s) that this printer supports.' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{127} ) The IPP protocol version(s) should include major and minor versions, i.e., the exact version numbers for which this Printer implementation meets the IPP version-specific conformance requirements. Fleming & McDonald Informational [Page 15] RFC 3712 LDAP Schema for Printer Services February 2004 4.10. printer-multiple-document-jobs-supported ( 1.3.18.0.2.4.1132 NAME 'printer-multiple-document-jobs-supported' DESC 'Indicates whether or not this printer supports more than one document per job.' EQUALITY booleanMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 SINGLE-VALUE ) 4.11. printer-charset-configured ( 1.3.18.0.2.4.1109 NAME 'printer-charset-configured' DESC 'The configured charset in which error and status messages will be generated (by default) by this printer.' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{63} SINGLE-VALUE ) Also, a possible charset for printer string attributes set by operator, system administrator, or manufacturer. For example: 'utf-8' (ISO 10646/Unicode in UTF-8 transform [RFC2279]) 'iso-8859-1' (Latin1) Values of charset tags should be defined in the IANA Registry of Coded Character Sets [IANA-CHAR] (see also [RFC2978]) and the '(preferred MIME name)' should be used as the charset tag in this attribute. For consistency with IPP/1.1 [RFC2911], charset tags in this attribute should be lowercase normalized. 4.12. printer-charset-supported ( 1.3.18.0.2.4.1131 NAME 'printer-charset-supported' DESC 'Set of charsets supported for the attribute values of syntax DirectoryString for this directory entry.' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{63} ) Fleming & McDonald Informational [Page 16] RFC 3712 LDAP Schema for Printer Services February 2004 For example: 'utf-8' (ISO 10646/Unicode in UTF-8 transform [RFC2279]) 'iso-8859-1' (Latin1) Values of charset tags should be defined in the IANA Registry of Coded Character Sets [IANA-CHAR] (see also [RFC2978]) and the '(preferred MIME name)' should be used as the charset tag in this attribute. For consistency with IPP/1.1 [RFC2911], charset tags in this attribute should be lowercase normalized. 4.13. printer-generated-natural-language-supported ( 1.3.18.0.2.4.1137 NAME 'printer-generated-natural-language-supported' DESC 'Natural language(s) supported for this directory entry.' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{63} ) Values of language tags should conform to "Tags for the Identification of Languages" [RFC3066]. For example: 'en-us' (English as spoken in the US) 'fr-fr' (French as spoken in France) For consistency with IPP/1.1 [RFC2911], language tags in this attribute should be lowercase normalized. 4.14. printer-document-format-supported ( 1.3.18.0.2.4.1130 NAME 'printer-document-format-supported' DESC 'The possible source document formats which may be interpreted and printed by this printer.' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{127} ) Values of document formats should be MIME media types defined in the IANA Registry of MIME Media Types [IANA-MIME] (see also [RFC2048]). Fleming & McDonald Informational [Page 17] RFC 3712 LDAP Schema for Printer Services February 2004 4.15. printer-color-supported ( 1.3.18.0.2.4.1129 NAME 'printer-color-supported' DESC 'Indicates whether this printer is capable of any type of color printing at all, including highlight color.' EQUALITY booleanMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 SINGLE-VALUE ) 4.16. printer-compression-supported ( 1.3.18.0.2.4.1128 NAME 'printer-compression-supported' DESC 'Compression algorithms supported by this printer.' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{255} ) Values defined in IPP/1.1 [RFC2911] include: 'none' (no compression is used) 'deflate' (public domain ZIP described in [RFC1951]) 'gzip' (GNU ZIP described in [RFC1952]) 'compress' (UNIX compression described in [RFC1977]) 4.17. printer-pages-per-minute ( 1.3.18.0.2.4.1127 NAME 'printer-pages-per-minute' DESC 'The nominal number of pages per minute which may be output by this printer.' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) This attribute is informative, not a service guarantee. Typically, it is the value used in marketing literature to describe this printer. For example, the value for a simplex or black-and-white print mode. Fleming & McDonald Informational [Page 18] RFC 3712 LDAP Schema for Printer Services February 2004 4.18. printer-pages-per-minute-color ( 1.3.18.0.2.4.1126 NAME 'printer-pages-per-minute-color' DESC 'The nominal number of color pages per minute which may be output by this printer.' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) This attribute is informative, not a service guarantee. Typically, it is the value used in marketing literature to describe this printer. 4.19. printer-finishings-supported ( 1.3.18.0.2.4.1125 NAME 'printer-finishings-supported' DESC 'The possible finishing operations supported by this printer.' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{255} ) Values defined in IPP/1.1 [RFC2911] include: 'none', 'staple', 'punch', 'cover', 'bind', 'saddle-stitch', 'edge-stitch', 'staple-top-left', 'staple-bottom-left', 'staple-top-right', 'staple-bottom-right', 'edge-stitch-left', 'edge-stitch-top', 'edge-stitch-right', 'edge-stitch-bottom', 'staple-dual-left', 'staple-dual-top', 'staple-dual-right', 'staple-dual-bottom'. Note: Implementations may support other values. 4.20. printer-number-up-supported ( 1.3.18.0.2.4.1124 NAME 'printer-number-up-supported' DESC 'The possible numbers of print-stream pages to impose upon a single side of an instance of a selected medium.' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 ) Fleming & McDonald Informational [Page 19] RFC 3712 LDAP Schema for Printer Services February 2004 Values defined in IPP/1.1 [RFC2911] include: '1', '2', and '4'. Note: Implementations may support other values. 4.21. printer-sides-supported ( 1.3.18.0.2.4.1123 NAME 'printer-sides-supported' DESC 'The number of impression sides (one or two) and the two-sided impression rotations supported by this printer.' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{127} ) Values defined in IPP/1.1 [RFC2911] include: 'one-sided', 'two- sided-long-edge', 'two-sided-short-edge'.' 4.22. printer-media-supported ( 1.3.18.0.2.4.1122 NAME 'printer-media-supported' DESC 'The standard names/types/sizes (and optional color suffixes) of the media supported by this printer.' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{255} ) Values are defined in IPP/1.1 [RFC2911] or any IANA registered extensions. For example: 'iso-a4' 'envelope' 'na-letter-white' 4.23. printer-media-local-supported ( 1.3.18.0.2.4.1117 NAME 'printer-media-local-supported' DESC 'Site-specific names of media supported by this printer.' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{255} ) Values should be in the natural language specified by printer- natural-language-configured. Fleming & McDonald Informational [Page 20] RFC 3712 LDAP Schema for Printer Services February 2004 For example: 'purchasing-form' (site-specific name) as opposed to 'na-letter' (standard keyword from IPP/1.1 [RFC2911]) in the printer-media-supported attribute. 4.24. printer-resolution-supported ( 1.3.18.0.2.4.1121 NAME 'printer-resolution-supported' DESC 'List of resolutions supported for printing documents by this printer.' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{255} ) Each resolution value should be a string containing 3 fields: 1) Cross feed direction resolution (positive integer); 2) Feed direction resolution (positive integer); 3) Unit - 'dpi' (dots per inch) or 'dpcm' (dots per centimeter). Each resolution field should be delimited by '>'. For example: '300> 300> dpi>' '600> 600> dpi>' Note: This attribute is based on 'printer-resolution-supported' defined in IPP/1.1 [RFC2911] (which has a binary complex encoding) derived from 'prtMarkerAddressabilityFeedDir', 'prtMarkerAddressabilityXFeedDir', and 'prtMarkerAddressabilityUnit' defined in the Printer MIB [RFC1759] (which have integer encodings). Note: The syntax and delimiter for this attribute are aligned with the equivalent attribute in the 'service:printer:' v2.0 template [SLP-PRT]. Whitespace is permitted after (but not before) the delimiter '>'. Note that this delimiter differs from printer-xri- supported. Fleming & McDonald Informational [Page 21] RFC 3712 LDAP Schema for Printer Services February 2004 4.25. printer-print-quality-supported ( 1.3.18.0.2.4.1120 NAME 'printer-print-quality-supported' DESC 'List of print qualities supported for printing documents on this printer.' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{127} ) Values defined in IPP/1.1 [RFC2911] include: 'unknown' 'draft' 'normal' 'high' 4.26. printer-job-priority-supported ( 1.3.18.0.2.4.1110 NAME 'printer-job-priority-supported' DESC 'Indicates the number of job priority levels supported by this printer.' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) An IPP/1.1 [RFC2911] conformant Printer, which supports job priority, always supports a full range of priorities from '1' to '100' (to ensure consistent behavior), therefore this attribute describes the 'granularity' of priority supported. Values of this attribute are from '1' to '100'. 4.27. printer-copies-supported ( 1.3.18.0.2.4.1118 NAME 'printer-copies-supported' DESC 'The maximum number of copies of a document that may be printed as a single job on this printer.' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) Fleming & McDonald Informational [Page 22] RFC 3712 LDAP Schema for Printer Services February 2004 A positive value indicates the maximum supported copies. A value of '0' indicates no maximum limit. A value of '-1' indicates 'unknown'. Note: The syntax and values for this attribute are aligned with the equivalent attribute in the 'service:printer:' v2.0 template [SLP- PRT]. 4.28. printer-job-k-octets-supported ( 1.3.18.0.2.4.1111 NAME 'printer-job-k-octets-supported' DESC 'The maximum size in kilobytes (1,024 octets actually) incoming print job that this printer will accept.' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) A positive value indicates the maximum supported job size. A value of '0' indicates no maximum limit. A value of '-1' indicates 'unknown'. Note: The syntax and values for this attribute are aligned with the equivalent attribute in the 'service:printer:' v2.0 template [SLP- PRT]. 4.29. printer-current-operator ( 1.3.18.0.2.4.1112 NAME 'printer-current-operator' DESC 'The identity of the current human operator responsible for operating this printer.' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{127} SINGLE-VALUE ) The value of this attribute should include information that would enable other humans to reach the operator, such as a telephone number. Fleming & McDonald Informational [Page 23] RFC 3712 LDAP Schema for Printer Services February 2004 4.30. printer-service-person ( 1.3.18.0.2.4.1113 NAME 'printer-service-person' DESC 'The identity of the current human service person responsible for servicing this printer.' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{127} SINGLE-VALUE ) The value of this attribute should include information that would enable other humans to reach the service person, such as a telephone number. 4.31. printer-delivery-orientation-supported ( 1.3.18.0.2.4.1114 NAME 'printer-delivery-orientation-supported' DESC 'The possible delivery orientations of pages as they are printed and ejected from this printer.' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{127} ) Values defined include: 'unknown' 'face-up' 'face-down' Note: The syntax and values for this attribute are aligned with the equivalent attribute in the 'service:printer:' v2.0 template [SLP- PRT]. 4.32. printer-stacking-order-supported ( 1.3.18.0.2.4.1115 NAME 'printer-stacking-order-supported' DESC 'The possible stacking order of pages as they are printed and ejected from this printer.' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{127} ) Fleming & McDonald Informational [Page 24] RFC 3712 LDAP Schema for Printer Services February 2004 Values defined include: 'unknown' 'first-to-last' 'last-to-first' Note: The syntax and values for this attribute are aligned with the equivalent attribute in the 'service:printer:' v2.0 template [SLP- PRT]. 4.33. printer-output-features-supported ( 1.3.18.0.2.4.1116 NAME 'printer-output-features-supported' DESC 'The possible output features supported by this printer.' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{127} ) Values defined include: 'unknown' 'bursting' 'decollating' 'page-collating' 'offset-stacking' Note: The syntax and values for this attribute are aligned with the equivalent attribute in the 'service:printer:' v2.0 template [SLP- PRT]. Note: Implementations may support other values. 4.34. printer-aliases ( 1.3.18.0.2.4.1108 NAME 'printer-aliases' DESC 'List of site-specific administrative names of this printer in addition to the value specified for printer-name.' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{127} ) Values of this attribute should be specified in the language specified in printer-natural-language-configured (for example, to support text-to-speech conversions), although the printer's alias may be specified in any language. Fleming & McDonald Informational [Page 25] RFC 3712 LDAP Schema for Printer Services February 2004 5. Definition of Syntaxes No new attribute syntaxes are defined by this document. The attribute types defined in Section 4 of this document reference syntax OIDs defined in Section 6 of [RFC2252], which are summarized below: Syntax OID Syntax Description ------------------------------ ------------------ 1.3.6.1.4.1.1466.115.121.1.7 Boolean 1.3.6.1.4.1.1466.115.121.1.15 DirectoryString (UTF-8 [RFC2279]) 1.3.6.1.4.1.1466.115.121.1.27 Integer 6. Definition of Matching Rules No new matching rules are defined by this document. The attribute types defined in Section 4 of this document reference matching rules defined in Section 8 of [RFC2252] and/or Section 2 of [RFC3698], which are summarized below: Matching Rule OID Matching Rule Name Usage ------------------------------ ------------------ ----- 2.5.13.13 booleanMatch EQUALITY 2.5.13.2 caseIgnoreMatch EQUALITY 2.5.13.14 integerMatch EQUALITY 2.5.13.15 integerOrderingMatch ORDERING 2.5.13.4 caseIgnoreSubstringsMatch SUBSTR 7. IANA Considerations This document does not define any new syntaxes or matching rules. This document does define the following Object Identifier Descriptors. They have been registered by the IANA: 7.1. Registration of Object Classes Subject: Request for LDAP Descriptor Registration Descriptor (short name): see table below Object Identifier: see table below Person & email address to contact for further information: see below Usage: object class Fleming & McDonald Informational [Page 26] RFC 3712 LDAP Schema for Printer Services February 2004 Specification: RFC3712 Author/Change Controller: Pat Fleming IBM Highway 52 N Rochester, MN 55901 USA Phone: +1 507-253-7583 EMail: flemingp@us.ibm.com Comments: Object Class OID ------------------------------------ --------------------- slpServicePrinter 1.3.18.0.2.6.254 printerAbstract 1.3.18.0.2.6.258 printerService 1.3.18.0.2.6.255 printerServiceAuxClass 1.3.18.0.2.6.257 printerIPP 1.3.18.0.2.6.256 printerLPR 1.3.18.0.2.6.253 7.2. Registration of Attribute Types Subject: Request for LDAP Descriptor Registration Descriptor (short name): see table below Object Identifier: see table below Person & email address to contact for further information: see below Usage: attribute type Specification: RFC3712 Author/Change Controller: Pat Fleming IBM Highway 52 N Rochester, MN 55901 USA Phone: +1 507-253-7583 EMail: flemingp@us.ibm.com Fleming & McDonald Informational [Page 27] RFC 3712 LDAP Schema for Printer Services February 2004 Comments: Attribute Type OID ------------------------------------ --------------------- printer-uri 1.3.18.0.2.4.1140 printer-xri-supported 1.3.18.0.2.4.1107 printer-name 1.3.18.0.2.4.1135 printer-natural-language-configured 1.3.18.0.2.4.1119 printer-location 1.3.18.0.2.4.1136 printer-info 1.3.18.0.2.4.1139 printer-more-info 1.3.18.0.2.4.1134 printer-make-and-model 1.3.18.0.2.4.1138 printer-ipp-versions-supported 1.3.18.0.2.4.1133 printer-multiple-document-jobs-supported 1.3.18.0.2.4.1132 printer-charset-configured 1.3.18.0.2.4.1109 printer-charset-supported 1.3.18.0.2.4.1131 printer-generated-natural-language-supported 1.3.18.0.2.4.1137 printer-document-format-supported 1.3.18.0.2.4.1130 printer-color-supported 1.3.18.0.2.4.1129 printer-compression-supported 1.3.18.0.2.4.1128 printer-pages-per-minute 1.3.18.0.2.4.1127 printer-pages-per-minute-color 1.3.18.0.2.4.1126 printer-finishings-supported 1.3.18.0.2.4.1125 printer-number-up-supported 1.3.18.0.2.4.1124 printer-sides-supported 1.3.18.0.2.4.1123 printer-media-supported 1.3.18.0.2.4.1122 printer-media-local-supported 1.3.18.0.2.4.1117 printer-resolution-supported 1.3.18.0.2.4.1121 printer-print-quality-supported 1.3.18.0.2.4.1120 printer-job-priority-supported 1.3.18.0.2.4.1110 printer-copies-supported 1.3.18.0.2.4.1118 printer-job-k-octets-supported 1.3.18.0.2.4.1111 printer-current-operator 1.3.18.0.2.4.1112 printer-service-person 1.3.18.0.2.4.1113 printer-delivery-orientation-supported 1.3.18.0.2.4.1114 printer-stacking-order-supported 1.3.18.0.2.4.1115 printer-output-features-supported 1.3.18.0.2.4.1116 printer-aliases 1.3.18.0.2.4.1108 8. Internationalization Considerations All text string attributes defined in this document of syntax [RFC2279], as required by [RFC2252]. A language tag [RFC3066] for all of the text string attributes defined in this document is contained in the printer-natural- language-configured attribute. Fleming & McDonald Informational [Page 28] RFC 3712 LDAP Schema for Printer Services February 2004 Therefore, all object classes defined in this document conform to the "IETF Policy on Character Sets and Languages" [RFC2277]. 9. Security Considerations See [RFC2829] for detailed guidance on authentication methods for LDAP. See [RFC2830] for detailed guidance of using TLS/1.0 [RFC2246] to supply connection confidentiality and data integrity for LDAP sessions. As with any LDAP schema, it is important to protect specific entries and attributes with the appropriate access control. It is particularly important that only administrators can modify entries defined in this LDAP printer schema. Otherwise, an LDAP client might be fooled into diverting print service requests from the original printer (or spooler) to a malicious intruder's host system, thus exposing the information in printed documents. For additional security considerations of deploying printers in an IPP environment, see Section 8 of [RFC2911]. 10. References 10.1. Normative References [IANA-CHAR] IANA Registry of Character Sets http://www.iana.org/assignments/charset-reg/... [IANA-MIME] IANA Registry of MIME Media Types http://www.iana.org/assignments/media-types/... [LDAP-TS] Hodges, J. and R. Morgan, "Lightweight Directory Access Protocol (v3): Technical Specification", RFC 3377, September 2002. [RFC1274] Barker, P. and S. Kille, "The COSINE and Internet X.500 Schema", RFC 1274, November 1991. [RFC1759] Smith, R., Wright, F., Hastings, T., Zilles, S. and J. Gyllenskog, "Printer MIB", RFC 1759, March 1995. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2252] Wahl, M., Coulbeck, T., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (v3): Attribute Syntax Definitions", RFC 2252, December 1997. Fleming & McDonald Informational [Page 29] RFC 3712 LDAP Schema for Printer Services February 2004 [RFC2396] Berners-Lee. T., Fielding, R. and L. Masinter, "URI Generic Syntax", RFC 2396, August 1998. [RFC2829] Wahl, M., Alvestrand, H., Hodges, J. and R. Morgan, "Authentication Methods for LDAP", RFC 2829, May 2000. [RFC2830] Hodges, J., Morgan, R. and M. Wahl, "Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security", RFC 2830, May 2000. [RFC2911] Hastings, T., Ed.., Herrito, R., deBry, R., Isaacson, S. and P. Powell, "Internet Printing Protocol/1.1: Model and Semantics", RFC 2911, September 2000. [RFC2926] Kempf, J., Moats, R. and P. St. Pierre, "Conversion of LDAP Schemas to and from SLP Templates", RFC 2926, September 2000. [RFC3066] Alvestrand, H., "Tags for the Identification of Languages", BCP 47, RFC 3066, January 2001. [RFC3698] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Additional Matching Rules", RFC 3698, February 2004. 10.2. Informative References [IANA-SLPT] IANA Registry of SLP Templates http://www.iana.org/assignments/svrloc-templates/... [RFC1179] McLaughlin, L., "Line Printer Daemon Protocol", RFC 1179, August 1990. [RFC1951] Deutsch, P., "DEFLATE Compressed Data Format Specification Version 1.3", RFC 1951, May 1996. [RFC1952] Deutsch, P., "GZIP File Format Specification Version 4.3", RFC 1952, May 1996. [RFC1977] Schryver, V., "PPP BSD Compression Protocol", RFC 1977, August 1996. [RFC2048] Freed, N., Klensin, J. and J. Postel, "Multipurpose Internet Mail Extensions (MIME) Part Four: Registration Procedures", BCP 13, RFC 2048, November 1996. Fleming & McDonald Informational [Page 30] RFC 3712 LDAP Schema for Printer Services February 2004 [RFC2079] Smith, M., "Definition of an X.500 Attribute Type and an Object Class to Hold Uniform Resource Identifiers (URIs)", RFC 2079, January 1997. [RFC2246] Dierks, T. and C. Allen, "TLS Protocol Version 1.0", RFC 2246, January 1999. [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and Languages", RFC 2277, January 1998. [RFC2279] Yergeau, F., "UTF-8, a Transformation Format of ISO 10646", RFC 2279, January 1998. [RFC2608] Guttman, E., Perkins, C., Veizades, J. and M. Day, "Service Location Protocol v2", RFC 2608, June 1999. [RFC2609] Guttman, E., Perkins, C. and J. Kempf, "Service Templates and Service: Schemes", RFC 2609, June 1999. [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A. and L. Stewart, "HTTP Authentication: Basic and Digest Access Authentication", RFC 2617, June 1999. [RFC2717] Petke, R. and I. King, "Registration Procedures for URL Scheme Names", RFC 2717, November 1999. [RFC2718] Masinter, L., Alvestrand, H., Zigmond, D. and R. Petke, "Guidelines for new URL Schemes", BCP 19, RFC 2718, November 1999. [RFC2978] Freed, N. and J.Postel, "IANA Charset Registration Procedures", RFC2978, October 2000. [SLP-PRT] St. Pierre, Isaacson, McDonald. Definition of the Printer Abstract Service Type v2.0, <durable URL below>, May 2000. Reviewed and approved by IETF SLP Designated Expert, according to Section 5 'IANA Considerations' in [RFC2609]. Archived in the IANA Registry of SLP Templates [IANA- SLPT] at: http://www.iana.org/assignments/svrloc- templates/printer.2.0.en [W3C-IRI] Duerst, Suignard, "Internationalized Resource Identifiers (IRI), Work in Progress. Fleming & McDonald Informational [Page 31] RFC 3712 LDAP Schema for Printer Services February 2004 11. Acknowledgments The editors wish to acknowledge the very significant contributions of Ken Jones (Bytemobile) and Harry Lewis (IBM) during the development of this document. Thanks to Patrik Faltstrom (Cisco), Ryan Moats (Lemur Networks), Robert Moore (IBM), Lee Rafalow (IBM), Kimberly Reger (IBM), Kurt Zeilenga (OpenLDAP), and the members of the IETF IPP Working Group, for review comments and help in preparing this document. 12. Authors' Addresses Please send comments to the authors at the addresses listed below. Pat Fleming IBM Highway 52 N Rochester, MN 55901 USA Phone: +1 507-253-7583 EMail: flemingp@us.ibm.com Ira McDonald High North Inc 221 Ridge Ave Grand Marais, MI 49839 USA Phone: +1 906-494-2434 Email: imcdonald@sharplabs.com Fleming & McDonald Informational [Page 32] RFC 3712 LDAP Schema for Printer Services February 2004 13. Full Copyright Statement Copyright (C) The Internet Society (2004). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Fleming & McDonald Informational [Page 33] PK ,�c\R��d�3 �3 ( doc/alt-openldap11-devel/rfc/rfc4403.txtnu �[��� Network Working Group B. Bergeson Request for Comments: 4403 K. Boogert Category: Informational Novell, Inc. V. Nanjundaswamy Oracle India Pvt. Ltd. February 2006 Lightweight Directory Access Protocol (LDAP) Schema for Universal Description, Discovery, and Integration version 3 (UDDIv3) Status of This Memo This memo provides information for the Internet community. It does not specify an Internet standard of any kind. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2006). Abstract This document defines the Lightweight Directory Access Protocol (LDAPv3) schema for representing Universal Description, Discovery, and Integration (UDDI) data types in an LDAP directory. It defines the LDAP object class and attribute definitions and containment rules to model UDDI entities, defined in the UDDI version 3 information model, in an LDAPv3-compliant directory. Table of Contents 1. Introduction ....................................................2 2. Conventions Used in This Document ...............................2 3. Representation of UDDI Data Structures ..........................2 4. Attribute Type Definitions ......................................6 5. Object Class Definitions .......................................28 6. Name Forms .....................................................32 7. DIT Structure Rules ............................................35 8. Security Considerations ........................................37 9. IANA Considerations ............................................37 10. Normative References ..........................................40 Bergeson, et al. Informational [Page 1] RFC 4403 LDAP Schema for UDDIv3 February 2006 1. Introduction This document defines the Lightweight Directory Access Protocol [LDAPv3] schema elements to represent the core data structures identified in the Universal Description, Discovery, and Integration version 3 [UDDIv3] information model. This includes a businessEntity, a businessService, a bindingTemplate, a tModel, a publisherAssertion, and a Subscription. Portions of [UDDIv3] are repeated here for clarity. 2. Conventions Used in This Document The keywords "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 [RFC2119]. All schema definitions are provided using [RFC2252] descriptions, and are line-wrapped for readability only. 3. Representation of UDDI Data Structures The information that makes up a registration in a UDDI registry consists of these data structure types. This division by information type provides simple partitions to assist in the rapid location and understanding of the different information that makes up a registration. The individual instance data managed by a UDDI registry is sensitive to the parent/child relationships found in the schema. A businessEntity object contains one or more unique businessService objects. Similarly, individual businessService objects contain specific instances of bindingTemplate, which in turn contains information that includes pointers to specific instances of tModel objects. It is important to note that no single instance of a core schema type is ever "contained" by more than one parent instance. This means that only one specific businessEntity object (identified by its unique key value) will ever contain or be used to express information about a specific instance of a businessService object (also identified by its own unique key value). 3.1. businessEntity The businessEntity object represents all known information about a business or entity that publishes descriptive information about the entity as well as the services that it offers. The businessEntity is the top-level container that accommodates holding descriptive Bergeson, et al. Informational [Page 2] RFC 4403 LDAP Schema for UDDIv3 February 2006 information about a business or entity. Service descriptions and technical information are expressed within a businessEntity by a containment relationship. 3.1.1. Representation in the Directory A businessEntity is represented in the directory by the attributes uddiBusinessKey, uddiAuthorizedName, uddiOperator, uddiDiscoveryURLs, uddiName, uddiDescription, uddiIdentifierBag, uddiCategoryBag, and uddiv3DigitalSignature, along with corresponding v3 keys viz. uddiv3BusinessKey, as defined in Section 4. A businessEntity may contain zero or more instances of uddiContact and uddiBusinessService. A mandatory attribute, uddiBusinessKey, contains the unique identifier for a given instance of a businessEntity. businessEntity's definition is given in Section 5. 3.2. businessService The businessService instances represent a logical business service. Each businessService object is the logical child of a single businessEntity object. Each businessService element contains descriptive information in business terms outlining the type of technical services found within each businessService instance. In some cases, businesses would like to share or reuse services, e.g., when a large enterprise publishes separate businessEntity structures. This can be established by using the businessService instance as a projection to an already published businessService. 3.2.1. Representation in the Directory A businessService is represented in the directory by the attributes uddiBusinessKey, uddiServiceKey, uddiName, uddiDescription, uddiCategoryBag, uddiIsProjection, and uddiv3DigitalSignature, along with corresponding v3 keys viz. uddiv3BusinessKey, and uddiv3ServiceKey, as defined in Section 4. A businessService may contain zero or more instances of uddiBindingTemplate. The mandatory attribute, uddiServiceKey, contains the unique identifier for a given instance of a businessService. businessService's definition is given in Section 5. Bergeson, et al. Informational [Page 3] RFC 4403 LDAP Schema for UDDIv3 February 2006 3.3. bindingTemplate Technical descriptions of Web services are accommodated via individual contained instances of bindingTemplate objects. These instances provide support for determining a technical entry point or optionally support remotely hosted services, as well as a lightweight facility for describing unique technical characteristics of a given implementation. Support for technology and application specific parameters and settings files are also supported. Since UDDI's main purpose is to enable description and discovery of Web service information, it is the bindingTemplate that provides the most interesting technical data. With UDDIv3, bindingTemplates also can have categorization information. Each bindingTemplate instance has a single logical businessService parent, which in turn has a single logical businessEntity parent. 3.3.1. Representation in the Directory A bindingTemplate is represented in the directory by the attributes uddiBindingKey, uddiServiceKey, uddiDescription, uddiAccessPoint, uddiHostingRedirector, uddiCategoryBag, and uddiv3DigitalSignature, along with corresponding v3 keys viz. uddiv3ServiceKey and uddiv3BindingKey, as defined in Section 4. A bindingTemplate may contain zero or more instances of uddiTModelInstanceDetails. The mandatory attribute, uddiBindingKey, contains the unique identifier for a given instance of a bindingTemplate. BindingTemplate's definition is given in Section 5. 3.4. tModel The tModel object takes the form of keyed metadata (data about data). In a general sense, the purpose of a tModel within the UDDI registry is to provide a reference system based on abstraction. Thus, the kind of data that a tModel represents is pretty nebulous. In other words, a tModel registration can define just about anything, but in the current revision, two conventions have been applied for using tModels: as sources for determining compatibility and as keyed namespace references. The information that makes up a tModel is quite simple. There are a key, a name, an optional description, and a Uniform Resource Locator [URL] that points somewhere--presumably somewhere where the curious can go to find out more about the actual concept represented by the metadata in the tModel itself. Bergeson, et al. Informational [Page 4] RFC 4403 LDAP Schema for UDDIv3 February 2006 3.4.1. Representation in the Directory A tModel is represented in the directory by the attributes uddiTModelKey, uddiAuthorizedName, uddiOperator, uddiName, uddiDescription, uddiOverviewDescription, uddiOverviewURL, uddiIdentifierBag, uddiCategoryBag, uddiIsHidden, and uddiv3DigitalSignature, along with the corresponding v3 key viz. uddiv3tModelKey, as defined in Section 4. A tModel may also contain a uddiHidden to logically delete a tModel. A mandatory attribute, uddiTModelKey, contains the unique identifier for a given instance of a tModel. tModel's definition is given in Section 5. 3.5. publisherAssertion Many businesses, such as large enterprises or marketplaces, are not effectively represented by a single businessEntity, since their description and discovery are likely to be diverse. As a consequence, several businessEntity instances can be published, representing individual subsidiaries of a large enterprise or individual participants of a marketplace. Nevertheless, they still represent a more or less coupled community and would like to make some of their relationships visible in their UDDI registrations. 3.5.1. Representation in the Directory A publisherAssertion is represented in the directory by the attributes uddiFromKey, uddiToKey, uddiKeyedReference, and uddiUUID, and uddiv3DigitalSignature, as defined in Section 5. A mandatory attribute, uddiUUID, contains the unique identifier for a given instance of a publisherAssertion. publisherAssertion's definition is given in Section 5. 3.6. Operational Information: With UDDIv3, the operational information associated with the core UDDI data structures is maintained in a separate OperationalInfo structure, so that the digital signature specified by the publisher remains valid. The operationalInfo structure is used to convey the operational information for the UDDIv3 core data structures, that is, the businessEntity, businessService, bindingTemplate, and tModel Bergeson, et al. Informational [Page 5] RFC 4403 LDAP Schema for UDDIv3 February 2006 structures. UDDIv3 OperationalInfo consists of 5 elements: created, Modified, modifiedIncludingChildren, nodeId, and authorizedName. Depending on the specific UDDIv3 core data structure, the operationalInformation is represented in the directory as a combination of implicit LDAP Standard Operational attributes: createTimestamp and modifyTimestamp, and the following explicit attributes: uddiAuthorizedName, uddiv3EntityCreationTime, uddiv3EntityModificationTime, and uddiv3NodeId. 4. Attribute Type Definitions The OIDs for the attribute types in this document have been registered by the IANA. 4.1. uddiBusinessKey This is used in uddiBusinessEntity and uddiBusinessService. The uddiBusinessKey is the unique identifier for a given instance of a uddiBusinessEntity. The attribute is optional for businessService instances contained within a fully expressed parent that already contains a businessKey value. If the businessService instance is rendered into the Extensible Markup Language [XML] and has no containing parent that has within its data a businessKey, the value of the businessKey that is the parent of the businessService is required to be provided. This behavior supports the ability to browse through the parent-child relationships given any of the core elements as a starting point. The businessKey may differ from the publishing businessEntity's businessKey to allow service projections. ( 1.3.6.1.1.10.4.1 NAME 'uddiBusinessKey' DESC 'businessEntity unique identifier' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) 4.2. uddiAuthorizedName The uddiAuthorizedName is the recorded name of the individual who published the uddiBusinessEntity or uddiTModel data. This data is generated by the controlling operator and should not be supplied within save_business operations. With UDDIv3, this attribute is part of the "operationalInformation" Bergeson, et al. Informational [Page 6] RFC 4403 LDAP Schema for UDDIv3 February 2006 metadata associated with core data structures. ( 1.3.6.1.1.10.4.2 NAME 'uddiAuthorizedName' DESC 'businessEntity publisher name' EQUALITY distinguishedNameMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 SINGLE-VALUE ) 4.3. uddiOperator The uddiOperator is the certified name of the UDDI registry site operator that manages the master copy of the uddiBusinessEntity or uddiTModel. The controlling operator records this data at the time data is saved. This data is generated and should not be supplied within save_business or save_tModel operations. With UDDIv3, this field is no longer used -- it is replaced by the nodeId (uddiv3NodeId) attribute that is part of the "operationalInformation" metadata. ( 1.3.6.1.1.10.4.3 NAME 'uddiOperator' DESC 'registry site operator of businessEntitys master copy' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) 4.4. uddiName This is used in uddiBusinessEntity, uddiBusinessService, and uddiTModel. These are the human-readable names recorded for the uddiBusinessEntity, uddiBusinessService, or uddiTModel, adorned with a unique xml:lang value to signify the language that they are expressed in. Name search is provided via find_business, find_service, or find_tModel calls. The publishing of several names, e.g., for romanization purposes, is supported. In order to signify the language that the names are expressed in, they carry unique xml:lang values. Not more than one name element may omit specifying its language. Names passed in this way will be assigned the default language code of the registering party. This default language code is established at the time that publishing credentials are established with an individual Operator Bergeson, et al. Informational [Page 7] RFC 4403 LDAP Schema for UDDIv3 February 2006 Site. If no default language is provisioned at the time a publisher signs up, the operator can adopt an appropriate default language code. With UDDIv3, multiple values with the same language code are permitted. ( 1.3.6.1.1.10.4.4 NAME 'uddiName' DESC 'human readable name' EQUALITY caseIgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) The xml:lang value precedes the name value, with the "#" character used as the separator. 4.5. uddiDescription The uddiDescription is an optional repeating element of one or more descriptions. One description is allowed per national language code supplied. With UDDIv3, there is no restriction on the number of descriptions or on what xml:lang value that they may have. ( 1.3.6.1.1.10.4.5 NAME 'uddiDescription' DESC 'short description' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) The xml:lang value precedes the name value, with the "#" character used as the separator. 4.6. uddiDiscoveryURLs This is a list of Uniform Resource Locators (URLs) that point to alternate, file-based service discovery mechanisms. Each recorded uddiBusinessEntity structure is automatically assigned a URL that returns the individual uddiBusinessEntity structure. A URL search is provided via find_business call. The uddiDiscoveryURLs attribute is used to hold pointers to URL- addressable discovery documents. The expected retrieval mechanism for URLs referenced in the data within this structure is via the Hypertext Transfer Protocol [HTTP] HTTP-GET operation. The expected return document is not defined. Rather, a framework for establishing conventions is provided, and two such conventions are defined within Bergeson, et al. Informational [Page 8] RFC 4403 LDAP Schema for UDDIv3 February 2006 UDDI behaviors. It is hoped that other conventions come about and use this structure to accommodate alternate means of discovery. With UDDIv3, a new convention is defined with useType as "homepage". Further, a UDDIv3 server need not generate/add a discoveryURL itself, since this can invalidate the digital signature of signed the Business Entity saved by publishers. ( 1.3.6.1.1.10.4.6 NAME 'uddiDiscoveryURLs' DESC 'URL to retrieve a businessEntity instance' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) The useType value precedes the URL value, with the "#" character used as the separator. 4.7. uddiUseType The uddiUseType is used to describe the type of contact or address in freeform text. Suggested examples for contact include "technical questions", "technical contact", "establish account", "sales contact", etc. Suggested examples for address include "headquarters", "sales office", "billing department", etc. ( 1.3.6.1.1.10.4.7 NAME 'uddiUseType' DESC 'name of convention the referenced document follows' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) 4.8. uddiPersonName The uddiPersonName should list the name of the person or name of the job role that will be available behind the contact. Examples of roles include "administrator" or "webmaster". ( 1.3.6.1.1.10.4.8 NAME 'uddiPersonName' DESC 'name of person or job role available for contact' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) With UDDIv3, uddiPersonName becomes multi-valued and each name can have an xml:lang attribute. The xml:lang value precedes the name value with the "#" character used as the separator. Bergeson, et al. Informational [Page 9] RFC 4403 LDAP Schema for UDDIv3 February 2006 4.9. uddiPhone This is used to hold telephone numbers for the contact. This element can be adorned with an optional uddiUseType attribute for descriptive purposes. If more than one phone element is saved, uddiUseType attributes are required on each. ( 1.3.6.1.1.10.4.9 NAME 'uddiPhone' DESC 'telephone number for contact' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) The useType precedes the telephone number by a separating '#' (e.g., "Work Number#123 456-7890") . 4.10. uddiEMail This is used to hold email addresses for the contact. This element can be adorned with an optional uddiUseType attribute for descriptive purposes. If more than one email element is saved, uddiUseType attributes are required on each. ( 1.3.6.1.1.10.4.10 NAME 'uddiEMail' DESC 'e-mail address for contact' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) The useType precedes the email address by a separating '#' (e.g., "President of the United States #president@whitehouse.gov"). 4.11. uddiSortCode The uddiSortCode is used to drive the behavior of external display mechanisms that sort addresses. The suggested values for uddiSortCode include numeric ordering values (e.g., 1, 2, 3), alphabetic character ordering values (e.g., a, b, c), or the first n positions of relevant data within the address. ( 1.3.6.1.1.10.4.11 NAME 'uddiSortCode' DESC 'specifies an external display mechanism' EQUALITY caseIgnoreMatch ORDERING caseIgnoreOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) Bergeson, et al. Informational [Page 10] RFC 4403 LDAP Schema for UDDIv3 February 2006 With UDDIv3, the sortCode attribute is deprecated because of the guarantee of preserving the document Order. 4.12. uddiTModelKey The uddiTModelKey is the unique identifier for a given instance of an uddiTModel. It is also used in a KeyedReference and in Address structures. When used with a keyed reference, this is the unique key to identify a value set and implies that the keyName keyValue pair in a uddiIdentifier or uddiCategory Bag are to be interpreted by the value set referenced by the tModelKey. When used with Addressline elements, it implies that the keyName keyValue pair given by subsequent uddiAddressLine elements are to be interpreted by the address structure associated with the tModel that is referenced. ( 1.3.6.1.1.10.4.12 NAME 'uddiTModelKey' DESC 'tModel unique identifier' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) 4.13. uddiAddressLine The uddiAddressLine contains the actual address in freeform text. If the address element contains a uddiTModelKey, these uddiAddressLine elements are to be adorned, each with an optional keyName keyValue attribute pair. Together with the uddiTModelKey, keyName and keyValue qualify the uddiAddressLine in order to describe its meaning. The uddiAddressLine elements contain string data with a line length limit of 80 character positions. Each uddiAddressLine element can be adorned with two optional descriptive attributes, keyName and keyValue. Both attributes must be present in each address line if a uddiTModelKey is assigned to the address structure. By doing this, the otherwise arbitrary use of address lines becomes structured. Together with the address' uddiTModelKey, keyName and keyValue virtually build a uddiKeyedReference that represents an address line qualifier, given by the referenced uddiTModel. When no uddiTModelKey is provided for the address structure, the keyName and keyValue attributes can be used without restrictions, for example, to provide descriptive information for each uddiAddressLine Bergeson, et al. Informational [Page 11] RFC 4403 LDAP Schema for UDDIv3 February 2006 by using the keyName attribute. Since both the keyName and the keyValue attributes are optional, address line order is significant and will always be returned by the UDDI-compliant registry in the order originally provided during a call to save_business. ( 1.3.6.1.1.10.4.13 NAME 'uddiAddressLine' DESC 'address' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) The keyName, keyValue, and addressData of this attribute are separated by "#" (e.g., "#"<keyName>"#"<keyValue>"#"<addressData>). The addressData is the only required portion of the attribute. 4.14. uddiIdentifierBag The uddiIdentifierBag element allows uddiBusinessEntity or uddiTModel structures to include information about common forms of identification such as D-U-N-S_ numbers, tax identifiers, etc. This data can be used to signify the identity of the uddiBusinessEntity or can be used to signify the identity of the publishing party. Including data of this sort is optional, but when used greatly enhances the search behaviors exposed via the find_xx messages defined in the UDDI Version 2.0 API Specification [UDDIapi]. For a full description of the structures involved in establishing an identity, see UDDI Version 2.0 Data Structure Specification - Appendix A: Using Identifiers [UDDIdsr]. ( 1.3.6.1.1.10.4.14 NAME 'uddiIdentifierBag' DESC 'identification information' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) The tModel, keyName, and keyValue of this attribute are separated by "#" (e.g., <tModel>"#"<keyName>"#"<keyValue>). The keyValue is the only required portion of the attribute. 4.15. uddiCategoryBag The uddiCategoryBag element allows uddiBusinessEntity, uddiBusinessService, and uddiTModel structures to be categorized according to any of several available taxonomy-based classification schemes. Operator Sites automatically provide validated categorization support for three taxonomies that cover industry codes (via NAICS), product and service classifications (via UNSPC), and geography (via ISO 3166). Including data of this sort is optional, Bergeson, et al. Informational [Page 12] RFC 4403 LDAP Schema for UDDIv3 February 2006 but when used, it greatly enhances the search behaviors exposed by the find_xx messages defined in the UDDI Version 2.0 API Specification [UDDIapi]. For a full description of structures involved in establishing categorization information, see UDDI Version 2.03 Data Structure Specification--Appendix B: Using Categorization [UDDIdsr]. ( 1.3.6.1.1.10.4.15 NAME 'uddiCategoryBag' DESC 'categorization information' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) The tModel, keyName, and keyValue of this attribute are separated by "#" (e.g., <tModel>"#"<keyName>"#"<keyValue>). The keyValue is the only required portion of the attribute. With UDDIv3, uddiBindingTemplates also supports the uddiCategoryBag element and they can also be categorized according to any of several available taxonomy-based classification schemes. 4.16. uddiKeyedReference The uddiKeyedReference is a general-purpose attribute for a name- value pair, with an additional reference to a tModel. ( 1.3.6.1.1.10.4.16 NAME 'uddiKeyedReference' DESC 'categorization information' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) The tModel, keyName, and keyValue of this attribute are separated by "#" (e.g., <tModel>"#"<keyName>"#"<keyValue>). The keyValue is the only required portion of the attribute. With UDDIv3, the tModelKey also becomes a mandatory part of the attribute. Also, UDDIv3 defines KeyedReferenceGroups for CategoryBags. A keyedReferenceGroup contains a tModelKey and a simple list of KeyedReference structures. The uddiKeyedReference attribute will support KeyedReferenceGroups by suffixing the tModelKey for KeyedReferenceGroup to each of the keyedReference values associated with the group. For example, to represent a keyedReference group containing a list of 2 keyed references, the attribute will hold the following 2 strings as its values: Bergeson, et al. Informational [Page 13] RFC 4403 LDAP Schema for UDDIv3 February 2006 tModelKey1#KeyName1#KeyValue1#KeyedReferenceGroup1_tModelKey tModelKey2#KeyName2#KeyValue2#KeyedReferenceGroup1_tModelKey 4.17. uddiServiceKey This is the unique key for a given uddiBusinessService. When saving a new uddiBusinessService structure, pass an empty uddiServiceKey value. This signifies that a UUID value is to be generated. To update an existing uddiBusinessService structure, pass the UUID value that corresponds to the existing service. If a uddiServiceKey is received via an inquiry operation, the key values may not be blank. When saving a new or updated service projection, pass the uddiServiceKey of the referenced uddiBusinessService structure. This attribute is optional when the uddiBindingTemplate data is contained within a fully expressed parent that already contains a uddiServiceKey value. If the uddiBindingTemplate data is rendered into XML and has no containing parent that has within its data a uddiServiceKey, the value of the uddiServiceKey that is the ultimate containing parent of the uddiBindingTemplate is required to be provided. This behavior supports the ability to browse through the parent-child relationships given any of the core elements as a starting point. ( 1.3.6.1.1.10.4.17 NAME 'uddiServiceKey' DESC 'businessService unique identifier' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) 4.18. uddiBindingKey This is the unique key for a given uddiBindingTemplate. When saving a new uddiBindingTemplate structure, pass an empty uddiBindingKey value. This signifies that a UUID value is to be generated. To update an existing uddiBindingTemplate, pass the UUID value that corresponds to the existing uddiBindingTemplate instance. If a uddiBindingKey is received via an inquiry operation, the key values may not be blank. ( 1.3.6.1.1.10.4.18 NAME 'uddiBindingKey' DESC 'bindingTemplate unique identifier' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) Bergeson, et al. Informational [Page 14] RFC 4403 LDAP Schema for UDDIv3 February 2006 4.19. uddiAccessPoint The uddiAccessPoint element is an attribute-qualified pointer to a service entry point. The notion of service at the metadata level seen here is fairly abstract and many types of entry points are accommodated. A single attribute is provided named URLType. Required attribute-qualified element8: This element is a text field that is used to convey the entry point address suitable for calling a particular Web service. This may be a URL, an electronic mail address, or even a telephone number. No assumptions about the type of data in this field can be made without first understanding the technical requirements associated with the Web service. ( 1.3.6.1.1.10.4.19 NAME 'uddiAccessPoint' DESC 'entry point address to call a web service' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) The URLType value precedes the accessPoint value by a separating '#'. With UDDIv3, the "URLType" attribute is replaced by a "UseType" attribute. Using this UseType attribute, the accessPoint attribute can model a hostingRedirector or support indirection to indicate that the accesspoint is specified within a remotely hosted WSDL document. For a UDDIv3 registry that needs to support UDDIv2 clients, the attribute must allow the representation of URLType and UseType values independently. The UDDIv3 spec specifies the following logic for mapping values between URLType and UseType: If an entity is saved with the v3 namespace and a v2 inquiry is made, the URLType will be returned as "other". In the case when a v3 inquiry is made on an entity published with the v2 namespace, the v3 useType attribute will be returned as "endPoint". For implementations that need to explicitly model both forms, the recommended format is as follows: v2URLType#v3UseType#Address 4.20. uddiHostingRedirector The uddiHostingRedirector element is used to designate that a uddiBindingTemplate entry is a pointer to a different uddiBindingTemplate entry. The value in providing this facility is seen when a business or entity wants to expose a service description Bergeson, et al. Informational [Page 15] RFC 4403 LDAP Schema for UDDIv3 February 2006 (e.g., advertise that it has a service available that suits a specific purpose) that is actually a service described in a separate uddiBindingTemplate record. This might occur when a service is remotely hosted (hence the name of this element), or when many service descriptions could benefit from a single service description. The uddiHostingRedirector element has a single attribute and no element content. The attribute is a uddiBindingKey value that is suitable within the same UDDI registry instance for querying and obtaining the uddiBindingDetail data that is to be used. More on the uddiHostingRedirector can be found in the appendices for the UDDI Version 2.0 API Specification [UDDIapi]. Required element if uddiAccessPoint is not provided: This element is adorned with a uddiBindingKey attribute, giving the redirected reference to a different uddiBindingTemplate. If you query a uddiBindingTemplate and find a uddiHostingRedirector value, you should retrieve that uddiBindingTemplate and use it in place of the one containing the uddiHostingRedirector data. ( 1.3.6.1.1.10.4.20 NAME 'uddiHostingRedirector' DESC 'designates a pointer to another bindingTemplate' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) With UDDIv3, the hostingRedirector is a deprecated element, since its functionality is now covered by the accessPoint. For backward- compatibility, it can still be used, but it is not recommended. 4.21. uddiInstanceDescription This is an optional repeating element. This is one or more language-qualified text descriptions that designate what role a uddiTModel reference plays in the overall service description. ( 1.3.6.1.1.10.4.21 NAME 'uddiInstanceDescription' DESC 'instance details description' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) The xml:lang value precedes the name value, with the "#" character used as the separator. Bergeson, et al. Informational [Page 16] RFC 4403 LDAP Schema for UDDIv3 February 2006 4.22. uddiInstanceParms The uddiInstanceParms is an optional element of the uddiInstance. It is used to contain settings parameters or a URL reference to a file that contains settings or parameters required to use a specific facet of a uddiBindingTemplate description. If used to house the parameters themselves, the suggested content is a namespace-qualified XML string using a namespace outside of the UDDI schema. If used to house a URL pointer to a file, the suggested format is a URL that is suitable for retrieving the settings or parameters via HTTP-GET. ( 1.3.6.1.1.10.4.22 NAME 'uddiInstanceParms' DESC 'URL reference to required settings' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) 4.23. uddiOverviewDescription This is an optional repeating element. This language-qualified string is intended to hold a short descriptive overview of how a particular uddiTModel is to be used. ( 1.3.6.1.1.10.4.23 NAME 'uddiOverviewDescription' DESC 'outlines tModel usage' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) The xml:lang value precedes the name value, with the "#" character used as the separator. Bergeson, et al. Informational [Page 17] RFC 4403 LDAP Schema for UDDIv3 February 2006 4.24. uddiOverviewURL This is an optional element. This string data element is to be used to hold a URL reference to a long form of an overview document that covers the way a particular uddiTModel specific reference is used as a component of an overall Web service description. The recommended format for the overviewURL is a URI that is suitable for retrieving the actual overview document with an HTTP-GET operation, for example, via a Web browser. ( 1.3.6.1.1.10.4.24 NAME 'uddiOverviewURL' DESC 'URL reference to overview document' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) With UDDIv3, uddiOverviewURL becomes multi-valued to allow the representation of multiple OverviewDocs within a single InstanceDetail element. Modeling multiple OverviewDocs within an InstanceDetail element: In UDDIv3, the InstanceDetails element in TmodelInstanceInfo can have multiple OverviewDoc's. In UDDIv2, we could have only 1 OverviewDoc. To retain the grouping between a set of overviewDescriptions and overviewURL, we can make both OverviewDoc and OverviewURL multi- valued, and have a "group ID" Prefix to each value (to group OverviewDescriptions and OverviewURL). An example is shown below: Overview Description OverviewURL 1#xml:lang#overviewDescription1 1#UseType#overviewURL 1#xml:lang#overviewDescription2 2#UseType#overviewURL 1#xml:lang#overviewDescription3 4#UseType#overviewURL 3#xml:lang#overviewDescription1 3#xml:lang#overviewDescription2 4#xml:lang#overviewDescription1 This implies that OverviewDoc1 has 3 overview descriptions and an overviewURL. OverviewDoc2 has only an overviewURL. OverviewDoc3 has only 2 overviewDescriptions. OverviewDoc4 also has 1 overview description and an overviewURL. Bergeson, et al. Informational [Page 18] RFC 4403 LDAP Schema for UDDIv3 February 2006 4.25. uddiFromKey The uddiFromKey is a required element. This is the unique key reference to the first uddiBusinessEntity for which the assertion is made. ( 1.3.6.1.1.10.4.25 NAME 'uddiFromKey' DESC 'unique businessEntity key reference' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) 4.26. uddiToKey The uddiToKey is a required element. This is the unique key reference to the second uddiBusinessEntity for which the assertion is made. ( 1.3.6.1.1.10.4.26 NAME 'uddiToKey' DESC 'unique businessEntity key reference' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) 4.27. uddiUUID The uddiUUID is a required element. This is to ensure unique identification of uddiContact, uddiAddress, and uddiPublisherAssertion objects. ( 1.3.6.1.1.10.4.27 NAME 'uddiUUID' DESC 'unique attribute' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) With UDDIv3, this attribute will also be used for unique identification of Subscription-feature-related entities. Bergeson, et al. Informational [Page 19] RFC 4403 LDAP Schema for UDDIv3 February 2006 4.28. uddiIsHidden This is used to provide functionality for the delete_tModel operation. Logical deletion hides the deleted tModels from find_tModel result sets but does not physically delete it. ( 1.3.6.1.1.10.4.28 NAME 'uddiIsHidden' DESC 'isHidden attribute' EQUALITY booleanMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 SINGLE-VALUE ) In case of UDDIv3, this attribute will represent the "deleted" attribute value. 4.29. uddiIsProjection This is used to identify a Business Service that has a Service Projection. ( 1.3.6.1.1.10.4.29 NAME 'uddiIsProjection' DESC 'isServiceProjection attribute' EQUALITY booleanMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 SINGLE-VALUE ) 4.30. uddiLang This is used to model the xml:lang value for the Address structure in UDDIv3. ( 1.3.6.1.1.10.4.30 NAME 'uddiLang' DESC 'xml:lang value in v3 Address structure' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) The following are attribute definitions to model new elements/fields in UDDIv3 information model. These attribute definitions have the "uddiv3" prefix to indicate that these attributes represent UDDI information model elements unique to UDDIv3. Bergeson, et al. Informational [Page 20] RFC 4403 LDAP Schema for UDDIv3 February 2006 4.31. uddiv3BusinessKey This is the unique UDDIv3 identifier for a given instance of uddiBusinessEntity. It is used in uddiBusinessEntity and uddiBusinessService. A uddiBusinessEntity will include the uddiBusinessKey (the v2 form) for unique identification by UDDIv2 clients. The uddiBusinessKey (36-char) will also be the LDAP naming attribute for the uddiBusinessEntity. The uddiBusinessEntity entry MAY also include the uddiv3BusinessKey, the explicit v3 form key, which can be 255 characters long. ( 1.3.6.1.1.10.4.31 NAME 'uddiv3BusinessKey' DESC 'UDDIv3 businessEntity unique identifier' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) 4.32. uddiv3ServiceKey This is the unique UDDIv3 identifier for a given instance of uddiBusinessService. It is used in uddiBusinessService and uddiBindingTemplate. A uddiBusinessService will include the uddiServiceKey (the v2 form) for unique identification by UDDIv2 clients. The uddiServiceKey (36-char) will also be the LDAP naming attribute for the uddiBusinessService entry. The uddiBusinessService entry MAY also include the uddiv3ServiceKey, the explicit v3 form key, which can be 255 characters long. ( 1.3.6.1.1.10.4.32 NAME 'uddiv3ServiceKey' DESC 'UDDIv3 businessService unique identifier' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) 4.33. uddiv3BindingKey This is the unique UDDIv3 identifier for a given instance of uddiBindingTemplate. A uddiBindingTemplate will include the uddiBindingKey (the v2 form) for unique identification by UDDIv2 clients. The uddiBindingKey (36-char) will also be the LDAP naming attribute for the Bergeson, et al. Informational [Page 21] RFC 4403 LDAP Schema for UDDIv3 February 2006 uddiBindingTemplate entry. The uddiBindingTemplate entry MAY also include the uddiv3BindingKey, the explicit v3 form key, which can be 255 characters long. ( 1.3.6.1.1.10.4.33 NAME 'uddiv3BindingKey' DESC 'UDDIv3 BindingTemplate unique identifier' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) 4.34. uddiv3TModelKey This is the unique UDDIv3 identifier for a given instance of a uddiTModel. A uddiTModel will include the uddiTModelKey (the v2 form) for unique identification by UDDIv2 clients. The uddiTModelKey (41-char) will also be the LDAP naming attribute for the uddiTModel entry. The uddiTModel entry MAY also include the uddiv3TModelKey, the explicit v3 form key, which can be 255 characters long. ( 1.3.6.1.1.10.4.34 NAME 'uddiv3TModelKey' DESC 'UDDIv3 TModel unique identifier' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) The tModelKey is also used in a KeyedReference and in Address structures. In all instances where a tModelKey is used as a reference to tModel, the v3 form of the tModel key (viz. uddiv3TModelKey) will be the form used, since using the v2 form key will require translating it to the v3 key by the UDDI Server, which may invalidate the digital signature of the entity. 4.35. uddiv3DigitalSignature The UDDIv3 v3 schema supports the signing of the following UDDI elements using "XML-Signature Syntax and Processing" (see http://www.w3.org/TR/xmldsig-core/). ..businessEntity ..businessService ..bindingTemplate ..tModel ..publisherAssertion Bergeson, et al. Informational [Page 22] RFC 4403 LDAP Schema for UDDIv3 February 2006 This uddiv3DigitalSignature attribute holds the digital signature for the corresponding UDDI entity. ( 1.3.6.1.1.10.4.35 NAME 'uddiv3DigitalSignature' DESC 'UDDIv3 entity digital signature' EQUALITY caseExactMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) A Signature element SHOULD be generated according to the required steps of "Core Generation" in XML-Signature Syntax and Processing. The signature should be calculated on the top-level element that will be stored by the registry as a result of the Publication API call. This element, referred to as the data object in the XML-Signature and Syntax specification, is the businessEntity element for save_business API calls, the businessService element for save_service API calls, the bindingTemplate for save_binding API calls, the tModel for save_tModel API calls, and the publisherAssertion for set_publisherAssertions and add_publisherAssertion API calls. The signature should be generated on the elements before they are added to the body of an API call. Also, according to the signature generation, all children of the element being signed are included in the generation of the signature unless first excluded by application of a transform. Due to the containment of service projections as businessService elements within a businessEntity element, this also means that changes to the projected service will render a signature of the businessEntity containing the projection invalid, unless a businessService element representing a service projection is excluded using a transform. Due to the location of the sequence of Signature elements within an element that is to be signed, the signature is "enveloped". As a result of the enveloping of the signature, it is necessary to apply at least one transformation on the signed entity to exclude the signature or signature(s). The transformation selected by a publisher or the XML-Signature tool is specified in a Transform element inside the Signature element. Bergeson, et al. Informational [Page 23] RFC 4403 LDAP Schema for UDDIv3 February 2006 4.36. uddiv3NodeId This attribute contains the Node Identity for a UDDIv3 node. ( 1.3.6.1.1.10.4.36 NAME 'uddiv3NodeId' DESC 'UDDIv3 Node Identifier' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) 4.37. uddiv3EntityModificationTime This attribute is used to maintain the last modification time for a UDDI entity. It is needed in the context of maintaining the modifiedIncludingChildren element. When a child entity (e.g., uddiBindingTemplate) is updated, the parent entity (e.g., uddiBusinessService) LDAP timestamp also gets updated. The uddiv3EntityModificationTime attribute saves the last modification time of the parent entity (uddiBusinessService in this case). ( 1.3.6.1.1.10.4.37 NAME 'uddiv3EntityModificationTime' DESC 'UDDIv3 Last Modified Time for Entity' EQUALITY generalizedTimeMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 SINGLE-VALUE ) The following attribute definitions define attributes related to the modeling of UDDIv3 subscription-related entities in the LDAP directory. Subscription provides clients, known as subscribers, with the ability to register their interest in receiving information concerning changes made in a UDDI registry. These changes can be scoped based on preferences provided with the request. The uddiv3Subscription object class is used to model registered UDDIv3 subscriptions. Bergeson, et al. Informational [Page 24] RFC 4403 LDAP Schema for UDDIv3 February 2006 4.38. uddiv3SubscriptionKey This is the unique UDDIv3 identifier for a given instance of a uddiv3Subscription entity. ( 1.3.6.1.1.10.4.38 NAME 'uddiv3SubscriptionKey' DESC 'UDDIv3 Subscription unique identifier' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) 4.39. uddiv3SubscriptionFilter This attribute contains the UDDIv3 Subscription Filter, specified as part of the save_subscription API, i.e., the Inquiry API specified as filtering criteria with a registered subscription. The filtering criteria limits the scope of a subscription to a subset of registry records. The get_xx and find_xx APIs are all valid choices for use as a subscriptionFilter. Only one of these can be chosen for each subscription. ( 1.3.6.1.1.10.4.39 NAME 'uddiv3SubscriptionFilter' DESC 'UDDIv3 Subscription Filter' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) 4.40. uddiv3NotificationInterval This attribute contains the Notification Interval string. It is of the type xsd:duration and specifies how often Asynchronous change notifications are to be provided to a subscriber. ( 1.3.6.1.1.10.4.40 NAME 'uddiv3NotificationInterval' DESC 'UDDIv3 Notification Interval' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) Bergeson, et al. Informational [Page 25] RFC 4403 LDAP Schema for UDDIv3 February 2006 4.41. uddiv3MaxEntities This attribute contains the maximum number of entities to be returned as part of a subscription notification. It is an integer and specifies the maximum number of entities in a notification returned to a subscription listener. ( 1.3.6.1.1.10.4.41 NAME 'uddiv3MaxEntities' DESC 'UDDIv3 Subscription maxEntities field' EQUALITY integerMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) 4.42. uddiv3ExpiresAfter This attribute specifies the Expiry Time associated with a subscription. It is of the XML Schema type xsd:dateTime. ( 1.3.6.1.1.10.4.42 NAME 'uddiv3ExpiresAfter' DESC 'UDDIv3 Subscription ExpiresAfter field' EQUALITY generalizedTimeMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 SINGLE-VALUE ) 4.43. uddiv3BriefResponse This attribute is a Boolean flag for Brief Response associated with a subscription entity. It controls the level of detail returned to a subscription listener. The default is "false" when omitted. When set to "true", it indicates that the subscription results are to be returned to the subscriber in the form of a keyBag, listing all of the entities that matched the subscriptionFilter. ( 1.3.6.1.1.10.4.43 NAME 'uddiv3BriefResponse' DESC 'UDDIv3 Subscription ExpiresAfter field' EQUALITY booleanMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 SINGLE-VALUE ) Bergeson, et al. Informational [Page 26] RFC 4403 LDAP Schema for UDDIv3 February 2006 4.44. uddiv3EntityKey This is the unique UDDIv3 identifier for a given instance of a core UDDI data structure that is to be logged as an Obituary entry uddiv3EntityObituary. When a core UDDIv3 Entity is deleted and there is an active subscription registered against this UDDI Entity, an Obituary entry is created, in which the v3 key of the deleted entry is logged as part of the uddiv3EntityKey attribute. ( 1.3.6.1.1.10.4.44 NAME 'uddiv3EntityKey' DESC 'UDDIv3 Entity unique identifier' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) 4.45. uddiv3EntityCreationTime This attribute is used to log the original Creation Time for a UDDI Entity that is deleted in the uddiv3EntityObituary entry. It is also used in uddiBusinessService and uddiBindingTemplate. A Move BS operation needs to delete and recreate BT sub-tree due to lack of support for moving a sub-tree in many LDAPv3 servers. This attribute is used to save the original creation time of the BT during a Move BS. ( 1.3.6.1.1.10.4.45 NAME 'uddiv3EntityCreationTime' DESC 'UDDIv3 Entity Creation Time' EQUALITY generalizedTimeMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 SINGLE-VALUE ) 4.46. uddiv3EntityDeletionTime This attribute is used to log the entity deletion time for a UDDI Entity that is deleted in the uddiv3EntityObituary entry. ( 1.3.6.1.1.10.4.46 NAME 'uddiv3EntityDeletionTime' DESC 'UDDIv3 Entity Deletion Time' EQUALITY generalizedTimeMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 SINGLE-VALUE ) Bergeson, et al. Informational [Page 27] RFC 4403 LDAP Schema for UDDIv3 February 2006 5. Object Class Definitions The OIDs for the object classes in this document have been registered by the IANA. 5.1. uddiBusinessEntity This structural object class represents a businessEntity. ( 1.3.6.1.1.10.6.1 NAME 'uddiBusinessEntity' SUP top STRUCTURAL MUST ( uddiBusinessKey $ uddiName) MAY ( uddiAuthorizedName $ uddiOperator $ uddiDiscoveryURLs $ uddiDescription $ uddiIdentifierBag $ uddiCategoryBag $ uddiv3BusinessKey $ uddiv3DigitalSignature $ uddiv3EntityModificationTime $ uddiv3NodeId) ) 5.2. uddiContact This structural object class represents a contact. It is contained by a uddiBusinessEntity. ( 1.3.6.1.1.10.6.2 NAME 'uddiContact' SUP top STRUCTURAL MUST ( uddiPersonName $ uddiUUID ) MAY ( uddiUseType $ uddiDescription $ uddiPhone $ uddiEMail ) ) Bergeson, et al. Informational [Page 28] RFC 4403 LDAP Schema for UDDIv3 February 2006 5.3. uddiAddress This structural object class represents an address. It is contained by a uddiContact. ( 1.3.6.1.1.10.6.3 NAME 'uddiAddress' SUP top STRUCTURAL MUST ( uddiUUID ) MAY ( uddiUseType $ uddiSortCode $ uddiTModelKey $ uddiv3TmodelKey $ uddiAddressLine $ uddiLang) ) 5.4. uddiBusinessService This structural object class represents a businessService. ( 1.3.6.1.1.10.6.4 NAME 'uddiBusinessService' SUP top STRUCTURAL MUST ( uddiServiceKey ) MAY ( uddiName $ uddiBusinessKey $ uddiDescription $ uddiCategoryBag $ uddiIsProjection $ uddiv3ServiceKey $ uddiv3BusinessKey $ uddiv3DigitalSignature $ uddiv3EntityCreationTime $ uddiv3EntityModificationTime $ uddiv3NodeId) ) Bergeson, et al. Informational [Page 29] RFC 4403 LDAP Schema for UDDIv3 February 2006 5.5. uddiBindingTemplate This structural object class represents a bindingTemplate. ( 1.3.6.1.1.10.6.5 NAME 'uddiBindingTemplate' SUP top STRUCTURAL MUST ( uddiBindingKey ) MAY ( uddiServiceKey $ uddiDescription $ uddiAccessPoint $ uddiHostingRedirector uddiCategoryBag $ uddiv3BindingKey $ uddiv3ServiceKey $ uddiv3DigitalSignature $ uddiv3EntityCreationTime $ uddiv3NodeId) ) 5.6. uddiTModelInstanceInfo This structural object class represents a tModelInstanceInfo. It is contained by a uddiBindingTemplate. ( 1.3.6.1.1.10.6.6 NAME 'uddiTModelInstanceInfo' SUP top STRUCTURAL MUST ( uddiTModelKey ) MAY ( uddiDescription $ uddiInstanceDescription $ uddiInstanceParms $ uddiOverviewDescription $ uddiOverviewURL $ uddiv3TmodelKey) ) Bergeson, et al. Informational [Page 30] RFC 4403 LDAP Schema for UDDIv3 February 2006 5.7. uddiTModel This structural object class represents a tModel. ( 1.3.6.1.1.10.6.7 NAME 'uddiTModel' SUP top STRUCTURAL MUST ( uddiTModelKey $ uddiName ) MAY ( uddiAuthorizedName $ uddiOperator $ uddiDescription $ uddiOverviewDescription $ uddiOverviewURL $ uddiIdentifierBag $ uddiCategoryBag $ uddiIsHidden uddiv3TModelKey $ uddiv3DigitalSignature $ uddiv3NodeId) ) 5.8. uddiPublisherAssertion This structural object class represents a publisherAssertion. ( 1.3.6.1.1.10.6.8 NAME 'uddiPublisherAssertion' SUP top STRUCTURAL MUST ( uddiFromKey $ uddiToKey $ uddiKeyedReference $ uddiUUID ) MAY ( uddiv3DigitalSignature $ uddiv3NodeId) ) The following are object class definitions to model new data structures needed to implement the UDDIv3 information model. These object class definitions have the "uddiv3" prefix to indicate that these attributes represent UDDI information model elements unique to UDDIv3. Bergeson, et al. Informational [Page 31] RFC 4403 LDAP Schema for UDDIv3 February 2006 5.9. uddiv3Subscription This structural object class represents a Subscription entity. ( 1.3.6.1.1.10.6.9 NAME 'uddiv3Subscription' SUP top STRUCTURAL MUST ( uddiv3SubscriptionFilter $ uddiUUID) MAY ( uddiAuthorizedName $ uddiv3SubscriptionKey $ uddiv3BindingKey $ uddiv3NotificationInterval $ uddiv3MaxEntities $ uddiv3ExpiresAfter $ uddiv3BriefResponse $ uddiv3NodeId) ) 5.10. uddiv3EntityObituary This structural object class represents an Obituary entry for and stores obituary information for deleted UDDIv3 entities needed for handling subscriptions. ( 1.3.6.1.1.10.6.10 NAME 'uddiv3EntityObituary' SUP top STRUCTURAL MUST ( uddiv3EntityKey $ uddiUUID) MAY ( uddiAuthorizedName $ uddiv3EntityCreationTime $ uddiv3EntityDeletionTime $ uddiv3NodeId) ) 6. Name Forms This section defines the required hierarchical structure rules and naming attributes for the object classes defined in Section 6. The OIDs for the structure rules in this document have been registered by the IANA. Bergeson, et al. Informational [Page 32] RFC 4403 LDAP Schema for UDDIv3 February 2006 6.1. uddiBusinessEntityNameForm This name form defines the naming attribute for a businessEntity. ( 1.3.6.1.1.10.15.1 NAME 'uddiBusinessEntityNameForm' OC uddiBusinessEntity MUST ( uddiBusinessKey ) ) 6.2. uddiContactNameForm This name form defines the naming attribute for a contact. ( 1.3.6.1.1.10.15.2 NAME 'uddiContactNameForm' OC uddiContact MUST ( uddiUUID ) ) 6.3. uddiAddressNameForm This name form defines the naming attribute for an address. ( 1.3.6.1.1.10.15.3 NAME 'uddiAddressNameForm' OC uddiAddress MUST ( uddiUUID ) ) 6.4. uddiBusinessServiceNameForm This name form defines the naming attribute for a businessService. ( 1.3.6.1.1.10.15.4 NAME 'uddiBusinessServiceNameForm' OC uddiBusinessService MUST ( uddiServiceKey ) ) 6.5. uddiBindingTemplateNameForm This name form defines the naming attribute for a bindingTemplate. ( 1.3.6.1.1.10.15.5 NAME 'uddiBindingTemplateNameForm' OC uddiBindingTemplate MUST ( uddiBindingKey ) ) Bergeson, et al. Informational [Page 33] RFC 4403 LDAP Schema for UDDIv3 February 2006 6.6. uddiTModelInstanceInfoNameForm This name form defines the naming attribute for a tModelInstanceInfo. ( 1.3.6.1.1.10.15.6 NAME 'uddiTModelInstanceInfoNameForm' OC uddiTModelInstanceInfo MUST ( uddiTModelKey ) ) 6.7. uddiTModelNameForm This name form defines the naming attribute for a tModel. ( 1.3.6.1.1.10.15.7 NAME 'uddiTModelNameForm' OC uddiTModel MUST ( uddiTModelKey ) ) 6.8. uddiPublisherAssertionNameForm This name form defines the naming attribute for a publisherAssertion. ( 1.3.6.1.1.10.15.8 NAME 'uddiPublisherAssertionNameForm' OC uddiPublisherAssertion MUST ( uddiUUID ) ) 6.9. uddiv3SubscriptionNameForm This name form defines the naming attribute for a Subscription. ( 1.3.6.1.1.10.15.9 NAME 'uddiv3SubscriptionNameForm' OC uddiv3Subscription MUST ( uddiUUID ) ) 6.10. uddiv3EntityObituaryNameForm This name form defines the naming attribute for an Entity Obituary. ( 1.3.6.1.1.10.15.10 NAME 'uddiv3EntityObituaryNameForm' OC uddiv3EntityObituary MUST ( uddiUUID ) ) Bergeson, et al. Informational [Page 34] RFC 4403 LDAP Schema for UDDIv3 February 2006 7. DIT Structure Rules This section defines the required hierarchical structure rules for the object classes defined in Section 6. Note that rule identifiers defined here show the relationship between structure rules. Implementations may use different identifiers but must follow the same hierarchical model. 7.1. uddiBusinessEntityStructureRule ( 1 NAME 'uddiBusinessEntityStructureRule' FORM uddiBusinessEntityNameForm ) 7.2. uddiContactStructureRule This structure rule defines the object class containment for a contact. ( 2 NAME 'uddiContactStructureRule' FORM uddiContactNameForm SUP ( 1 ) ) 7.3. uddiAddressStructureRule This structure rule defines the object class containment for an address. ( 3 NAME 'uddiAddressStructureRule' FORM uddiAddressNameForm SUP ( 2 ) ) 7.4. uddiBusinessServiceStructureRule This structure rule defines the object class containment for a businessService. ( 4 NAME 'uddiBusinessServiceStructureRule' FORM uddiBusinessServiceNameForm SUP ( 1 ) ) Bergeson, et al. Informational [Page 35] RFC 4403 LDAP Schema for UDDIv3 February 2006 7.5. uddiBindingTemplateStructureRule This structure rule defines the object class containment for a bindingTemplate. ( 5 NAME 'uddiBindingTemplateStructureRule' FORM uddiBindingTemplateNameForm SUP ( 4 ) ) 7.6. uddiTModelInstanceInfoStructureRule This structure rule defines the object class containment for a tModelInstanceInfo. ( 6 NAME 'uddiTModelInstanceInfoStructureRule' FORM uddiTModelInstanceInfoNameForm SUP ( 5 ) ) 7.7. uddiTModelStructureRule ( 7 NAME 'uddiTModelStructureRule' FORM uddiTModelNameForm ) 7.8. uddiPublisherAssertion ( 8 NAME 'uddiPublisherAssertionStructureRule' FORM uddiPublisherAssertionNameForm ) 7.9. uddiv3SubscriptionStructureRule ( 9 NAME 'uddiv3SubscriptionStructureRule' FORM uddiv3SubscriptionNameForm ) Bergeson, et al. Informational [Page 36] RFC 4403 LDAP Schema for UDDIv3 February 2006 7.10. uddiv3EntityObituaryStructureRule ( 10 NAME 'uddiv3EntityObituaryStructureRule' FORM uddiv3EntityObituaryNameForm ) 8. Security Considerations Storing UDDI data into the directory enables the data to be examined and used outside the environment in which it was originally created. The directory entry containing the UDDI data could be read and modified within the constraints imposed by the access control mechanisms of the directory. With UDDIv3 [UDDIv3], publishers can digitally sign UDDI Entities enabling registry clients to validate the integrity of entries read from the UDDIv3 registry by verifying the digital signature. Each UDDI Entity has a uddiAuthorizedName attribute that contains an LDAP DN identifying the publisher/owner. The referenced LDAP object can provide the public key of the signer to a registry client for integrity validation of the UDDI Entity. Other general LDAP [LDAPv3] security considerations apply. Some of the UDDI attributes such as AccessPoints for services may contain sensitive information. Use of strong authentication mechanisms and data integrity/confidentiality services [RFC2829][RFC2830] is advised. 9. IANA Considerations Refer to RFC 3383, "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)" [RFC3383]. Bergeson, et al. Informational [Page 37] RFC 4403 LDAP Schema for UDDIv3 February 2006 9.1. Object Identifier Registration The IANA has registered an LDAP Object Identifier for use in this technical specification, according to the following template: Subject: Request for LDAP OID Registration Person & email address to contact for further information: Bruce Bergeson (bruce.bergeson@novell.com) Specification: RFC 4403 Author/Change Controller: IESG Comments: The assigned OID (10) will be used as a base for identifying a number of UDDI schema elements defined in this document. 9.2. Object Identifier Descriptors The IANA has registered the LDAP Descriptors used in this technical specification as detailed in the following template: Subject: Request for LDAP Descriptor Registration Update Descriptor (short name): see table Object Identifier: see table Person & email address to contact for further information: Bruce Bergeson (bruce.bergeson@novell.com) Usage: see table Specification: RFC 4403 Author/Change Controller: IESG Table: The following descriptors have been added: NAME Type OID -------------- ---- ------------ uddiBusinessKey A 1.3.6.1.1.10.4.1 uddiAuthorizedName A 1.3.6.1.1.10.4.2 uddiOperator A 1.3.6.1.1.10.4.3 uddiName A 1.3.6.1.1.10.4.4 uddiDescription A 1.3.6.1.1.10.4.5 uddiDiscoveryURLs A 1.3.6.1.1.10.4.6 uddiUseType A 1.3.6.1.1.10.4.7 uddiPersonName A 1.3.6.1.1.10.4.8 uddiPhone A 1.3.6.1.1.10.4.9 uddiEMail A 1.3.6.1.1.10.4.10 uddiSortCode A 1.3.6.1.1.10.4.11 uddiTModelKey A 1.3.6.1.1.10.4.12 uddiAddressLine A 1.3.6.1.1.10.4.13 Bergeson, et al. Informational [Page 38] RFC 4403 LDAP Schema for UDDIv3 February 2006 NAME Type OID -------------- ---- ------------ uddiIdentifierBag A 1.3.6.1.1.10.4.14 uddiCategoryBag A 1.3.6.1.1.10.4.15 uddiKeyedReference A 1.3.6.1.1.10.4.16 uddiServiceKey A 1.3.6.1.1.10.4.17 uddiBindingKey A 1.3.6.1.1.10.4.18 uddiAccessPoint A 1.3.6.1.1.10.4.19 uddiHostingRedirector A 1.3.6.1.1.10.4.20 uddiInstanceDescription A 1.3.6.1.1.10.4.21 uddiInstanceParms A 1.3.6.1.1.10.4.22 uddiOverviewDescription A 1.3.6.1.1.10.4.23 uddiOverviewURL A 1.3.6.1.1.10.4.24 uddiFromKey A 1.3.6.1.1.10.4.25 uddiToKey A 1.3.6.1.1.10.4.26 uddiUUID A 1.3.6.1.1.10.4.27 uddiIsHidden A 1.3.6.1.1.10.4.28 uddiIsProjection A 1.3.6.1.1.10.4.29 uddiLang A 1.3.6.1.1.10.4.30 uddiv3BusinessKey A 1.3.6.1.1.10.4.31 uddiv3ServiceKey A 1.3.6.1.1.10.4.32 uddiv3BindingKey A 1.3.6.1.1.10.4.33 uddiv3TmodelKey A 1.3.6.1.1.10.4.34 uddiv3DigitalSignature A 1.3.6.1.1.10.4.35 uddiv3NodeId A 1.3.6.1.1.10.4.36 uddiv3EntityModificationTime A 1.3.6.1.1.10.4.37 uddiv3SubscriptionKey A 1.3.6.1.1.10.4.38 uddiv3SubscriptionFilter A 1.3.6.1.1.10.4.39 uddiv3NotificationInterval A 1.3.6.1.1.10.4.40 uddiv3MaxEntities A 1.3.6.1.1.10.4.41 uddiv3ExpiresAfter A 1.3.6.1.1.10.4.42 uddiv3BriefResponse A 1.3.6.1.1.10.4.43 uddiv3EntityKey A 1.3.6.1.1.10.4.44 uddiv3EntityCreationTime A 1.3.6.1.1.10.4.45 uddiv3EntityDeletionTime A 1.3.6.1.1.10.4.46 uddiBusinessEntity O 1.3.6.1.1.10.6.1 uddiContact O 1.3.6.1.1.10.6.2 uddiAddress O 1.3.6.1.1.10.6.3 uddiBusinessService O 1.3.6.1.1.10.6.4 uddiBindingTemplate O 1.3.6.1.1.10.6.5 uddiTModelInstanceInfo O 1.3.6.1.1.10.6.6 uddiTModel O 1.3.6.1.1.10.6.7 uddiPublisherAssertion O 1.3.6.1.1.10.6.8 uddiv3Subscription O 1.3.6.1.1.10.6.9 uddiv3EntityObituary O 1.3.6.1.1.10.6.10 uddiBusinessEntityNameForm N 1.3.6.1.1.10.15.1 uddiContactNameForm N 1.3.6.1.1.10.15.2 uddiAddressNameForm N 1.3.6.1.1.10.15.3 Bergeson, et al. Informational [Page 39] RFC 4403 LDAP Schema for UDDIv3 February 2006 NAME Type OID -------------- ---- ------------ uddiBusinessServiceNameForm N 1.3.6.1.1.10.15.4 uddiBindingTemplateNameForm N 1.3.6.1.1.10.15.5 uddiTModelInstanceInfoNameForm N 1.3.6.1.1.10.15.6 uddiTModelNameForm N 1.3.6.1.1.10.15.7 uddiPublisherAssertionNameForm N 1.3.6.1.1.10.15.8 uddiv3SubscriptionNameForm N 1.3.6.1.1.10.15.9 uddiv3EntityObituaryNameForm N 1.3.6.1.1.10.15.10 where Type A is Attribute, Type O is ObjectClass, Type N is NameForm These assignments have been recorded in the following registry: http://www.iana.org/assignments/ldap-parameters 10. Normative References [LDAPv3] Hodges, J. and R. Morgan, "Lightweight Directory Access Protocol (v3): Technical Specification", RFC 3377, September 2002. [RFC2252] Wahl, M., Coulbeck, A., Howes, T., and S. Kille, "Lightweight Directory Access Protocol (v3): Attribute Syntax Definitions", RFC 2252, December 1997. [UDDIdsr] UDDI.ORG, "UDDI version 2.03 Data Structure Reference," http://uddi.org/pubs/DataStructure-V2.03-Published- 20020719.htm [UDDIapi] "UDDI Version 2.04 API Specification", http://uddi.org/pubs/ProgrammersAPI-V2.04-Published- 20020719.htm [UDDIv3] UDDI Version 3.0, Published Specification, 19 July 2002 http://uddi.org/pubs/uddi-v3.00-published-20020719.htm [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2829] Wahl, M., Alvestrand, H., Hodges, J., and R. Morgan, "Authentication Methods for LDAP", RFC 2829, May 2000. [RFC2830] Hodges, J., Morgan, R., and M. Wahl, "Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security", RFC 2830, May 2000. Bergeson, et al. Informational [Page 40] RFC 4403 LDAP Schema for UDDIv3 February 2006 [RFC3383] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 3383, September 2002. [XML] Extensible Markup Language (XML) 1.0 (Second Edition) W3C Recommendation 6 October 2000 http://www.w3.org/TR/REC-xml [URL] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005. [HTTP] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. Authors' Addresses Bruce Bergeson Novell, Inc. 1800 S Novell Place Provo, UT 84606 Phone: +1 801 861 3854 EMail: bruce.bergeson@novell.com Kent Boogert Novell, Inc. 1800 S Novell Place Provo, UT 84606 Phone: +1 801 861 3212 EMail: kent.boogert@novell.com Vijay Nanjundaswamy Oracle India Pvt. Ltd. Lexington Towers, Prestige St. John's Woods #18, 2nd Cross Road, Chikka Audugodi, Bangalore 560029 India Phone: +11 9180 4108 5000 EMail: vijay.nanjundaswamy@oracle.com Bergeson, et al. Informational [Page 41] RFC 4403 LDAP Schema for UDDIv3 February 2006 Full Copyright Statement Copyright (C) The Internet Society (2006). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Bergeson, et al. Informational [Page 42] PK ,�c\Ɇ���j �j ( doc/alt-openldap11-devel/rfc/rfc3296.txtnu �[��� Network Working Group K. Zeilenga Request for Comments: 3296 OpenLDAP Foundation Category: Standards Track July 2002 Named Subordinate References in Lightweight Directory Access Protocol (LDAP) Directories Status of this Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2002). All Rights Reserved. Abstract This document details schema and protocol elements for representing and managing named subordinate references in Lightweight Directory Access Protocol (LDAP) Directories. Conventions Schema definitions are provided using LDAPv3 description formats [RFC2252]. Definitions provided here are formatted (line wrapped) for readability. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" used in this document are to be interpreted as described in BCP 14 [RFC2119]. 1. Background and Intended Usage The broadening of interest in LDAP (Lightweight Directory Access Protocol) [RFC2251] directories beyond their use as front ends to X.500 [X.500] directories has created a need to represent knowledge information in a more general way. Knowledge information is information about one or more servers maintained in another server, used to link servers and services together. This document details schema and protocol elements for representing and manipulating named subordinate references in LDAP directories. A referral object is used to hold subordinate reference information in Zeilenga Standards Track [Page 1] RFC 3296 Named Subordinate References in LDAP Directories July 2002 the directory. These referral objects hold one or more URIs [RFC2396] contained in values of the ref attribute type and are used to generate protocol referrals and continuations. A control, ManageDsaIT, is defined to allow manipulation of referral and other special objects as normal objects. As the name of control implies, it is intended to be analogous to the ManageDsaIT service option described in X.511(97) [X.511]. Other forms of knowledge information are not detailed by this document. These forms may be described in subsequent documents. This document details subordinate referral processing requirements for servers. This document does not describe protocol syntax and semantics. This is detailed in RFC 2251 [RFC2251]. This document does not detail use of subordinate knowledge references to support replicated environments nor distributed operations (e.g., chaining of operations from one server to other servers). 2. Schema 2.1. The referral Object Class A referral object is a directory entry whose structural object class is (or is derived from) the referral object class. ( 2.16.840.1.113730.3.2.6 NAME 'referral' DESC 'named subordinate reference object' STRUCTURAL MUST ref ) The referral object class is a structural object class used to represent a subordinate reference in the directory. The referral object class SHOULD be used in conjunction with the extensibleObject object class to support the naming attributes used in the entry's Distinguished Name (DN) [RFC2253]. Referral objects are normally instantiated at DSEs immediately subordinate to object entries within a naming context held by the DSA. Referral objects are analogous to X.500 subordinate knowledge (subr) DSEs [X.501]. Zeilenga Standards Track [Page 2] RFC 3296 Named Subordinate References in LDAP Directories July 2002 In the presence of a ManageDsaIT control, referral objects are treated as normal entries as described in section 3. Note that the ref attribute is operational and will only be returned in a search entry response when requested. In the absence of a ManageDsaIT control, the content of referral objects are used to construct referrals and search references as described in Section 4 and, as such, the referral entries are not themselves visible to clients. 2.2 The ref Attribute Type ( 2.16.840.1.113730.3.1.34 NAME 'ref' DESC 'named reference - a labeledURI' EQUALITY caseExactMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 USAGE distributedOperation ) The ref attribute type has directoryString syntax and is case sensitive. The ref attribute is multi-valued. Values placed in the attribute MUST conform to the specification given for the labeledURI attribute [RFC2079]. The labeledURI specification defines a format that is a URI, optionally followed by whitespace and a label. This document does not make use of the label portion of the syntax. Future documents MAY enable new functionality by imposing additional structure on the label portion of the syntax as it appears in the ref attribute. If the URI contained in a ref attribute value refers to a LDAP [RFC2251] server, it MUST be in the form of a LDAP URL [RFC2255]. The LDAP URL SHOULD NOT contain an explicit scope specifier, filter, attribute description list, or any extensions. The LDAP URL SHOULD contain a non-empty DN. The handling of LDAP URLs with absent or empty DN parts or with explicit scope specifier is not defined by this specification. Other URI schemes MAY be used so long as all operations returning referrals based upon the value could be performed. This document does not detail use of non-LDAP URIs. This is left to future specifications. The referential integrity of the URI SHOULD NOT be validated by the server holding or returning the URI (whether as a value of the attribute or as part of a referral result or search reference response). Zeilenga Standards Track [Page 3] RFC 3296 Named Subordinate References in LDAP Directories July 2002 When returning a referral result or search continuation, the server MUST NOT return the separator or label portions of the attribute values as part of the reference. When the attribute contains multiple values, the URI part of each value is used to construct the referral result or search continuation. The ref attribute values SHOULD NOT be used as a relative name- component of an entry's DN [RFC2253]. This document uses the ref attribute in conjunction with the referral object class to represent subordinate references. The ref attribute may be used for other purposes as defined by other documents. 3. The ManageDsaIT Control The client may provide the ManageDsaIT control with an operation to indicate that the operation is intended to manage objects within the DSA (server) Information Tree. The control causes Directory-specific entries (DSEs), regardless of type, to be treated as normal entries allowing clients to interrogate and update these entries using LDAP operations. A client MAY specify the following control when issuing an add, compare, delete, modify, modifyDN, search request or an extended operation for which the control is defined. The control type is 2.16.840.1.113730.3.4.2. The control criticality may be TRUE or, if FALSE, absent. The control value is absent. When the control is present in the request, the server SHALL NOT generate a referral or continuation reference based upon information held in referral objects and instead SHALL treat the referral object as a normal entry. The server, however, is still free to return referrals for other reasons. When not present, referral objects SHALL be handled as described above. The control MAY cause other objects to be treated as normal entries as defined by subsequent documents. 4. Named Subordinate References A named subordinate reference is constructed by instantiating a referral object in the referencing server with ref attribute values which point to the corresponding subtree maintained in the referenced server. In general, the name of the referral object is the same as the referenced object and this referenced object is a context prefix [X.501]. Zeilenga Standards Track [Page 4] RFC 3296 Named Subordinate References in LDAP Directories July 2002 That is, if server A holds "DC=example,DC=net" and server B holds "DC=sub,DC=example,DC=net", server A may contain a referral object named "DC=sub,DC=example,DC=net" which contains a ref attribute with value of "ldap://B/DC=sub,DC=example,DC=net". dn: DC=sub,DC=example,DC=net dc: sub ref: ldap://B/DC=sub,DC=example,DC=net objectClass: referral objectClass: extensibleObject Typically the DN of the referral object and the DN of the object in the referenced server are the same. If the ref attribute has multiple values, all the DNs contained within the LDAP URLs SHOULD be equivalent. Administrators SHOULD avoid configuring naming loops using referrals. Named references MUST be treated as normal entries if the request includes the ManageDsaIT control as described in section 3. 5. Scenarios The following sections contain specifications of how referral objects should be used in different scenarios followed by examples that illustrate that usage. The scenarios described here consist of referral object handling when finding target of a non-search operation, when finding the base of a search operation, and when generating search references. Lastly, other operation processing considerations are presented. It is to be noted that, in this document, a search operation is conceptually divided into two distinct, sequential phases: (1) finding the base object where the search is to begin, and (2) performing the search itself. The first phase is similar to, but not the same as, finding the target of a non-search operation. It should also be noted that the ref attribute may have multiple values and, where these sections refer to a single ref attribute value, multiple ref attribute values may be substituted and SHOULD be processed and returned (in any order) as a group in a referral or search reference in the same way as described for a single ref attribute value. Search references returned for a given request may be returned in any order. Zeilenga Standards Track [Page 5] RFC 3296 Named Subordinate References in LDAP Directories July 2002 5.1. Example Configuration For example, suppose the contacted server (hosta) holds the entry "O=MNN,C=WW" and the entry "CN=Manager,O=MNN,C=WW" and the following referral objects: dn: OU=People,O=MNN,C=WW ou: People ref: ldap://hostb/OU=People,O=MNN,C=US ref: ldap://hostc/OU=People,O=MNN,C=US objectClass: referral objectClass: extensibleObject dn: OU=Roles,O=MNN,C=WW ou: Roles ref: ldap://hostd/OU=Roles,O=MNN,C=WW objectClass: referral objectClass: extensibleObject The first referral object provides the server with the knowledge that subtree "OU=People,O=MNN,C=WW" is held by hostb and hostc (e.g., one is the master and the other a shadow). The second referral object provides the server with the knowledge that the subtree "OU=Roles,O=MNN,C=WW" is held by hostd. Also, in the context of this document, the "nearest naming context" means the deepest context which the object is within. That is, if the object is within multiple naming contexts, the nearest naming context is the one which is subordinate to all other naming contexts the object is within. 5.2. Target Object Considerations This section details referral handling for add, compare, delete, modify, and modify DN operations. If the client requests any of these operations, there are four cases that the server must handle with respect to the target object. The DN part MUST be modified such that it refers to the appropriate target in the referenced server (as detailed below). Even where the DN to be returned is the same as the target DN, the DN part SHOULD NOT be trimmed. In cases where the URI to be returned is a LDAP URL, the server SHOULD trim any present scope, filter, or attribute list from the URI before returning it. Critical extensions MUST NOT be trimmed or modified. Zeilenga Standards Track [Page 6] RFC 3296 Named Subordinate References in LDAP Directories July 2002 Case 1: The target object is not held by the server and is not within or subordinate to any naming context nor subordinate to any referral object held by the server. The server SHOULD process the request normally as appropriate for a non-existent base which is not within any naming context of the server (generally return noSuchObject or a referral based upon superior knowledge reference information). This document does not detail management or processing of superior knowledge reference information. Case 2: The target object is held by the server and is a referral object. The server SHOULD return the URI value contained in the ref attribute of the referral object appropriately modified as described above. Example: If the client issues a modify request for the target object of "OU=People,O=MNN,c=WW", the server will return: ModifyResponse (referral) { ldap://hostb/OU=People,O=MNN,C=WW ldap://hostc/OU=People,O=MNN,C=WW } Case 3: The target object is not held by the server, but the nearest naming context contains no referral object which the target object is subordinate to. If the nearest naming context contains no referral object which the target is subordinate to, the server SHOULD process the request as appropriate for a nonexistent target (generally return noSuchObject). Case 4: The target object is not held by the server, but the nearest naming context contains a referral object which the target object is subordinate to. If a client requests an operation for which the target object is not held by the server and the nearest naming context contains a referral object which the target object is subordinate to, the server SHOULD return a referral response constructed from the URI portion of the ref value of the referral object. Zeilenga Standards Track [Page 7] RFC 3296 Named Subordinate References in LDAP Directories July 2002 Example: If the client issues an add request where the target object has a DN of "CN=Manager,OU=Roles,O=MNN,C=WW", the server will return: AddResponse (referral) { ldap://hostd/CN=Manager,OU=Roles,O=MNN,C=WW" } Note that the DN part of the LDAP URL is modified such that it refers to the appropriate entry in the referenced server. 5.3. Base Object Considerations This section details referral handling for base object processing within search operations. Like target object considerations for non-search operations, there are the four cases. In cases where the URI to be returned is a LDAP URL, the server MUST provide an explicit scope specifier from the LDAP URL prior to returning it. In addition, the DN part MUST be modified such that it refers to the appropriate target in the referenced server (as detailed below). If aliasing dereferencing was necessary in finding the referral object, the DN part of the URI MUST be replaced with the base DN as modified by the alias dereferencing such that the return URL refers to the new target object per [RFC2251, 4.1.11]. Critical extensions MUST NOT be trimmed nor modified. Case 1: The base object is not held by the server and is not within nor subordinate to any naming context held by the server. The server SHOULD process the request normally as appropriate for a non-existent base which not within any naming context of the server (generally return a superior referral or noSuchObject). This document does not detail management or processing of superior knowledge references. Case 2: The base object is held by the server and is a referral object. The server SHOULD return the URI value contained in the ref attribute of the referral object appropriately modified as described above. Zeilenga Standards Track [Page 8] RFC 3296 Named Subordinate References in LDAP Directories July 2002 Example: If the client issues a subtree search in which the base object is "OU=Roles,O=MNN,C=WW", the server will return SearchResultDone (referral) { ldap://hostd/OU=Roles,O=MNN,C=WW??sub } If the client were to issue a base or oneLevel search instead of subtree, the returned LDAP URL would explicitly specify "base" or "one", respectively, instead of "sub". Case 3: The base object is not held by the server, but the nearest naming context contains no referral object which the base object is subordinate to. If the nearest naming context contains no referral object which the base is subordinate to, the request SHOULD be processed normally as appropriate for a nonexistent base (generally return noSuchObject). Case 4: The base object is not held by the server, but the nearest naming context contains a referral object which the base object is subordinate to. If a client requests an operation for which the target object is not held by the server and the nearest naming context contains a referral object which the target object is subordinate to, the server SHOULD return a referral response which is constructed from the URI portion of the ref value of the referral object. Example: If the client issues a base search request for "CN=Manager,OU=Roles,O=MNN,C=WW", the server will return SearchResultDone (referral) { ldap://hostd/CN=Manager,OU=Roles,O=MNN,C=WW??base" } If the client were to issue a subtree or oneLevel search instead of subtree, the returned LDAP URL would explicitly specify "sub" or "one", respectively, instead of "base". Note that the DN part of the LDAP URL is modified such that it refers to the appropriate entry in the referenced server. Zeilenga Standards Track [Page 9] RFC 3296 Named Subordinate References in LDAP Directories July 2002 5.4. Search Continuation Considerations For search operations, once the base object has been found and determined not to be a referral object, the search may progress. Any entry matching the filter and scope of the search which is not a referral object is returned to the client normally as described in [RFC2251]. For each referral object within the requested scope, regardless of the search filter, the server SHOULD return a SearchResultReference which is constructed from the URI component of values of the ref attribute. If the URI component is not a LDAP URL, it should be returned as is. If the LDAP URL's DN part is absent or empty, the DN part must be modified to contain the DN of the referral object. If the URI component is a LDAP URL, the URI SHOULD be modified to add an explicit scope specifier. Subtree Example: If a client requests a subtree search of "O=MNN,C=WW", then in addition to any entries within scope which match the filter, hosta will also return two search references as the two referral objects are within scope. One possible response might be: SearchEntry for O=MNN,C=WW SearchResultReference { ldap://hostb/OU=People,O=MNN,C=WW??sub ldap://hostc/OU=People,O=MNN,C=WW??sub } SearchEntry for CN=Manager,O=MNN,C=WW SearchResultReference { ldap://hostd/OU=Roles,O=MNN,C=WW??sub } SearchResultDone (success) One Level Example: If a client requests a one level search of "O=MNN,C=WW" then, in addition to any entries one level below the "O=MNN,C=WW" entry matching the filter, the server will also return two search references as the two referral objects are within scope. One possible sequence is shown: Zeilenga Standards Track [Page 10] RFC 3296 Named Subordinate References in LDAP Directories July 2002 SearchResultReference { ldap://hostb/OU=People,O=MNN,C=WW??base ldap://hostc/OU=People,O=MNN,C=WW??base } SearchEntry for CN=Manager,O=MNN,C=WW SearchResultReference { ldap://hostd/OU=Roles,O=MNN,C=WW??base } SearchResultDone (success) Note: Unlike the examples in Section 4.5.3.1 of RFC 2251, the LDAP URLs returned with the SearchResultReference messages contain, as required by this specification, an explicit scope specifier. 5.6. Other Considerations This section details processing considerations for other operations. 5.6.1 Bind Servers SHOULD NOT return referral result code if the bind name (or authentication identity or authorization identity) is (or is subordinate to) a referral object but MAY use the knowledge information to process the bind request (such as in support a future distributed operation specification). Where the server makes no use of the knowledge information, the server processes the request normally as appropriate for a non-existent authentication or authorization identity (e.g., return invalidCredentials). 5.6.2 Modify DN If the newSuperior is a referral object or is subordinate to a referral object, the server SHOULD return affectsMultipleDSAs. If the newRDN already exists but is a referral object, the server SHOULD return affectsMultipleDSAs instead of entryAlreadyExists. 6. Security Considerations This document defines mechanisms that can be used to tie LDAP (and other) servers together. The information used to tie services together should be protected from unauthorized modification. If the server topology information is not public information, it should be protected from unauthorized disclosure as well. Zeilenga Standards Track [Page 11] RFC 3296 Named Subordinate References in LDAP Directories July 2002 7. Acknowledgments This document borrows heavily from previous work by IETF LDAPext Working Group. In particular, this document is based upon "Named Referral in LDAP Directories" (an expired Internet Draft) by Christopher Lukas, Tim Howes, Michael Roszkowski, Mark C. Smith, and Mark Wahl. 8. Normative References [RFC2079] Smith, M., "Definition of an X.500 Attribute Type and an Object Class to Hold Uniform Resource Identifiers (URIs)", RFC 2079, January 1997. [RFC2119] Bradner, S., "Key Words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 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. [RFC2253] Wahl, M., Kille, S. and T. Howes, "Lightweight Directory Access Protocol (v3): UTF-8 String Representation of Distinguished Names", RFC 2253, December 1997. [RFC2255] Howes, T. and M. Smith, "The LDAP URL Format", RFC 2255, December, 1997. [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, August 1998. [X.501] ITU-T, "The Directory: Models", X.501, 1993. 9. Informative References [X.500] ITU-T, "The Directory: Overview of Concepts, Models, and Services", X.500, 1993. [X.511] ITU-T, "The Directory: Abstract Service Definition", X.500, 1997. Zeilenga Standards Track [Page 12] RFC 3296 Named Subordinate References in LDAP Directories July 2002 10. Author's Address Kurt D. Zeilenga OpenLDAP Foundation EMail: Kurt@OpenLDAP.org Zeilenga Standards Track [Page 13] RFC 3296 Named Subordinate References in LDAP Directories July 2002 11. 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. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Zeilenga Standards Track [Page 14] PK -�c\]&�0 �0 ( doc/alt-openldap11-devel/rfc/rfc2293.txtnu �[��� Network Working Group S. Kille Request for Comments: 2293 Isode Ltd. Obsoletes: 1837 March 1998 Category: Standards Track Representing Tables and Subtrees in the X.500 Directory Status of this Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (1998). All Rights Reserved. Abstract This document defines techniques for representing two types of information mapping in the OSI Directory [1]. 1. Mapping from a key to a value (or set of values), as might be done in a table lookup. 2. Mapping from a distinguished name to an associated value (or values), where the values are not defined by the owner of the entry. This is achieved by use of a directory subtree. These techniques were developed for supporting MHS use of Directory [2], but are specified separately as they have more general applicability. Kille Standards Track [Page 1] RFC 2293 Table and Subtrees in the X.500 March 1998 1 Representing Flat Tables Before considering specific function, a general purpose technique for representing tables in the directory is introduced. The schema for this is given in Figure 1. A table can be considered as an unordered set of key to (single or multiple) value mappings, where the key cannot be represented as a global name. There are four reasons why this may occur: 1. The object does not have a natural global name. 2. The object can only be named effectively in the context of being a key to a binding. In this case, the object will be given a natural global name by the table. 3. The object has a global name, and the table is being used to associate parameters with this object, in cases where they cannot be placed in the objects global entry. Reasons why they might not be so placed include: o The object does not have a directory entry o There is no authority to place the parameters in the global entry o The parameters are not global --- they only make sense in the context of the table. 4. It is desirable to group information together as a performance optimization, so that the block of information may be widely replicated. A table is represented as a single level subtree. The root of the subtree is an entry of object class Table. This is named with a common name descriptive of the table. The table will be located somewhere appropriate to its function. If a table is private to an MTA, it will be below the MTA's entry. If it is shared by MTA's in an organization, it will be located under the organization. The generic table entry contains only a description. All instances will be subclassed, and the subclass will define the naming attribute. Two subclasses are defined: Kille Standards Track [Page 2] RFC 2293 Table and Subtrees in the X.500 March 1998 table OBJECT-CLASS ::= { SUBCLASS OF {top} MUST CONTAIN {commonName} MAY CONTAIN {manager} ID oc-table} tableEntry OBJECT-CLASS ::= { SUBCLASS OF {top} MAY CONTAIN {description} 10 ID oc-table-entry} textTableEntry OBJECT-CLASS ::= { SUBCLASS OF {tableEntry} MUST CONTAIN {textTableKey} MAY CONTAIN {textTableValue} ID oc-text-table-entry} textTableKey ATTRIBUTE ::= { SUBTYPE OF name 20 WITH SYNTAX DirectoryString {ub-name} ID at-text-table-key} textTableValue ATTRIBUTE ::= { SUBTYPE OF name WITH SYNTAX DirectoryString {ub-description} ID at-text-table-value} distinguishedNameTableEntry OBJECT-CLASS ::= { SUBCLASS OF {tableEntry} 30 MUST CONTAIN {distinguishedNameTableKey} ID oc-distinguished-name-table-entry} distinguishedNameTableKey ATTRIBUTE ::= { SUBTYPE OF distinguishedName ID at-distinguished-name-table-key} Figure 1: Representing Tables 1. TextEntry, which define table entries with text keys, which may have single or multiple values of any type. An attribute is defined to allow a text value, to support the frequent text key to text value mapping. Additional values may be defined. Kille Standards Track [Page 3] RFC 2293 Table and Subtrees in the X.500 March 1998 2. DistinguishedNameEntry. This is used for associating information with globally defined objects. This approach should be used where the number of objects in the table is small or very sparsely spread over the DIT. In other cases where there are many objects or the objects are tightly clustered in the DIT, the subtree approach defined in Section 2 will be preferable. No value attributes are defined for this type of entry. An application of this will make appropriate subtyping to define the needed values. This is best illustrated by example. Consider the MTA: CN=Bells, OU=Computer Science, O=University College London, C=GB Suppose that the MTA needs a table mapping from private keys to fully qualified domain names (this example is fictitious). The table might be named as: CN=domain-nicknames, CN=Bells, OU=Computer Science, O=University College London, C=GB To represent a mapping in this table from "euclid" to "bloomsbury.ac.uk", the entry: TextTableKey=euclid, CN=domain-nicknames, CN=Bells, OU=Computer Science, O=University College London, C=GB will contain the attribute: TextTableValue=bloomsbury.ac.uk A second example, showing the use of DistinguishedNameEntry is now given. Consider again the MTA: CN=Bells, OU=Computer Science, O=University College London, C=GB Suppose that the MTA needs a table mapping from MTA Name to bilateral agreement information of that MTA. The table might be named as: CN=MTA Bilateral Agreements, CN=Bells, OU=Computer Science, O=University College London, C=GB Kille Standards Track [Page 4] RFC 2293 Table and Subtrees in the X.500 March 1998 To represent information on the MTA which has the Distinguished Name: CN=Q3T21, ADMD=Gold 400, C=GB There would be an entry in this table with the Relative Distinguished Name of the table entry being the Distinguished Name of the MTA being referred to. The MTA Bilateral information would be an attribute in this entry. Using a non-standard notation, the Distinguished Name of the table entry is: DistinguishedNameTableKey=<CN=Q3T21, ADMD=Gold 400, C=GB>, CN=MTA Bilateral Agreements, CN=Bells, OU=Computer Science, O=University College London, C=GB 2 Representing Subtrees A subtree is similar to a table, except that the keys are constructed as a distinguished name hierarchy relative to the location of the subtree in the DIT. The subtree effectively starts a private "root", and has distinguished names relative to this root. Typically, this approach is used to associate local information with global objects. The schema used is defined in Figure 2. Functionally, this is equivalent to a table with distinguished name keys. The table approach is best when the tree is very sparse. This approach is better for subtrees which are more populated. The subtree object class defines the root for a subtree in an analogous means to the table. Information within the subtree will generally be defined in the same way as for the global object, and so subtree OBJECT-CLASS ::= { SUBCLASS OF {top} MUST CONTAIN {commonName} MAY CONTAIN {manager} ID oc-subtree} Figure 2: Representing Subtrees no specific object classes for subtree entries are needed. For example consider University College London. O=University College London, C=GB Kille Standards Track [Page 5] RFC 2293 Table and Subtrees in the X.500 March 1998 Suppose that the UCL needs a private subtree, with interesting information about directory objects. The table might be named as: CN=private subtree, O=University College London, C=GB UCL specific information on Inria might be stored in the entry: O=Inria, C=FR, CN=private subtree, O=University College London, C=GB Practical examples of this mapping are given in [2]. 3 Acknowledgments Acknowledgments for work on this document are given in [2]. References [1] The Directory --- overview of concepts, models and services, 1993. CCITT X.500 Series Recommendations. [2] Kille, S.E., "X.400-MHS use of the X.500 directory to support X.400-MHS routing," RFC 1801, June 1995. 4 Security Considerations Security considerations are not discussed in this memo. 5 Author's Address Steve Kille Isode Ltd The Dome The Square Richmond TW9 1DT England Phone: +44-181-332-9091 EMail: S.Kille@ISODE.COM Kille Standards Track [Page 6] RFC 2293 Table and Subtrees in the X.500 March 1998 A Object Identifier Assignment mhs-ds OBJECT IDENTIFIER ::= {iso(1) org(3) dod(6) internet(1) private(4) enterprises(1) isode-consortium (453) mhs-ds (7)} tables OBJECT IDENTIFIER ::= {mhs-ds 1} oc OBJECT IDENTIFIER ::= {tables 1} at OBJECT IDENTIFIER ::= {tables 2} oc-subtree OBJECT IDENTIFIER ::= {oc 1} oc-table OBJECT IDENTIFIER ::= {oc 2} 10 oc-table-entry OBJECT IDENTIFIER ::= {oc 3} oc-text-table-entry OBJECT IDENTIFIER ::= {oc 4} oc-distinguished-name-table-entry OBJECT IDENTIFIER ::= {oc 5} at-text-table-key OBJECT IDENTIFIER ::= {at 1} at-text-table-value OBJECT IDENTIFIER ::= {at 2} at-distinguished-name-table-key OBJECT IDENTIFIER ::= {at 3} Figure 3: Object Identifier Assignment Kille Standards Track [Page 7] RFC 2293 Table and Subtrees in the X.500 March 1998 Full Copyright Statement Copyright (C) The Internet Society (1998). 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. Kille Standards Track [Page 8] PK .�c\�� � ( doc/alt-openldap11-devel/rfc/rfc4519.txtnu �[��� Network Working Group A. Sciberras, Ed. Request for Comments: 4519 eB2Bcom Obsoletes: 2256 June 2006 Updates: 2247, 2798, 2377 Category: Standards Track Lightweight Directory Access Protocol (LDAP): Schema for User Applications Status of This Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2006). Abstract This document is an integral part of the Lightweight Directory Access Protocol (LDAP) technical specification. It provides a technical specification of attribute types and object classes intended for use by LDAP directory clients for many directory services, such as White Pages. These objects are widely used as a basis for the schema in many LDAP directories. This document does not cover attributes used for the administration of directory servers, nor does it include directory objects defined for specific uses in other documents. Sciberras Standards Track [Page 1] RFC 4519 LDAP: Schema for User Applications June 2006 Table of Contents 1. Introduction ....................................................3 1.1. Relationship with Other Specifications .....................3 1.2. Conventions ................................................4 1.3. General Issues .............................................4 2. Attribute Types .................................................4 2.1. 'businessCategory' .........................................5 2.2. 'c' ........................................................5 2.3. 'cn' .......................................................5 2.4. 'dc' .......................................................6 2.5. 'description' ..............................................6 2.6. 'destinationIndicator' .....................................7 2.7. 'distinguishedName' ........................................7 2.8. 'dnQualifier' ..............................................8 2.9. 'enhancedSearchGuide' ......................................8 2.10. 'facsimileTelephoneNumber' ................................9 2.11. 'generationQualifier' .....................................9 2.12. 'givenName' ...............................................9 2.13. 'houseIdentifier' .........................................9 2.14. 'initials' ...............................................10 2.15. 'internationalISDNNumber' ................................10 2.16. 'l' ......................................................10 2.17. 'member' .................................................11 2.18. 'name' ...................................................11 2.19. 'o' ......................................................11 2.20. 'ou' .....................................................12 2.21. 'owner' ..................................................12 2.22. 'physicalDeliveryOfficeName' .............................12 2.23. 'postalAddress' ..........................................13 2.24. 'postalCode' .............................................13 2.25. 'postOfficeBox' ..........................................14 2.26. 'preferredDeliveryMethod' ................................14 2.27. 'registeredAddress' ......................................14 2.28. 'roleOccupant' ...........................................15 2.29. 'searchGuide' ............................................15 2.30. 'seeAlso' ................................................15 2.31. 'serialNumber' ...........................................16 2.32. 'sn' .....................................................16 2.33. 'st' .....................................................16 2.34. 'street' .................................................17 2.35. 'telephoneNumber' ........................................17 2.36. 'teletexTerminalIdentifier' ..............................17 2.37. 'telexNumber' ............................................18 2.38. 'title' ..................................................18 2.39. 'uid' ....................................................18 2.40. 'uniqueMember' ...........................................19 2.41. 'userPassword' ...........................................19 Sciberras Standards Track [Page 2] RFC 4519 LDAP: Schema for User Applications June 2006 2.42. 'x121Address' ............................................20 2.43. 'x500UniqueIdentifier' ...................................20 3. Object Classes .................................................20 3.1. 'applicationProcess' ......................................21 3.2. 'country' .................................................21 3.3. 'dcObject' ................................................21 3.4. 'device' ..................................................21 3.5. 'groupOfNames' ............................................22 3.6. 'groupOfUniqueNames' ......................................22 3.7. 'locality' ................................................23 3.8. 'organization' ............................................23 3.9. 'organizationalPerson' ....................................24 3.10. 'organizationalRole' .....................................24 3.11. 'organizationalUnit' .....................................24 3.12. 'person' .................................................25 3.13. 'residentialPerson' ......................................25 3.14. 'uidObject' ..............................................26 4. IANA Considerations ............................................26 5. Security Considerations ........................................28 6. Acknowledgements ...............................................28 7. References .....................................................29 7.1. Normative References ......................................29 7.2. Informative References ....................................30 Appendix A Changes Made Since RFC 2256 ...........................32 1. Introduction This document provides an overview of attribute types and object classes intended for use by Lightweight Directory Access Protocol (LDAP) directory clients for many directory services, such as White Pages. Originally specified in the X.500 [X.500] documents, these objects are widely used as a basis for the schema in many LDAP directories. This document does not cover attributes used for the administration of directory servers, nor does it include directory objects defined for specific uses in other documents. 1.1. Relationship with Other Specifications This document is an integral part of the LDAP technical specification [RFC4510], which obsoletes the previously defined LDAP technical specification, RFC 3377, in its entirety. In terms of RFC 2256, Sections 6 and 8 of RFC 2256 are obsoleted by [RFC4517]. Sections 5.1, 5.2, 7.1, and 7.2 of RFC 2256 are obsoleted by [RFC4512]. The remainder of RFC 2256 is obsoleted by this document. The technical specification for the 'dc' attribute type and 'dcObject' object class found in RFC 2247 are superseded by sections 2.4 and 3.3 of this document. The remainder of RFC 2247 remains in force. Sciberras Standards Track [Page 3] RFC 4519 LDAP: Schema for User Applications June 2006 This document updates RFC 2798 by replacing the informative description of the 'uid' attribute type with the definitive description provided in Section 2.39 of this document. This document updates RFC 2377 by replacing the informative description of the 'uidObject' object class with the definitive description provided in Section 3.14 of this document. A number of schema elements that were included in the previous revision of the LDAP Technical Specification are not included in this revision of LDAP. PKI-related schema elements are now specified in [RFC4523]. Unless reintroduced in future technical specifications, the remainder are to be considered Historic. The descriptions in this document SHALL be considered definitive for use in LDAP. 1.2. Conventions 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 [RFC2119]. 1.3. General Issues This document references Syntaxes defined in Section 3 of [RFC4517] and Matching Rules defined in Section 4 of [RFC4517]. The definitions of Attribute Types and Object Classes are written using the Augmented Backus-Naur Form (ABNF) [RFC4234] of AttributeTypeDescription and ObjectClassDescription given in [RFC4512]. Lines have been folded for readability. When such values are transferred as attribute values in the LDAP Protocol, the values will not contain line breaks. 2. Attribute Types The attribute types contained in this section hold user information. There is no requirement that servers implement the 'searchGuide' and 'teletexTerminalIdentifier' attribute types. In fact, their use is greatly discouraged. An LDAP server implementation SHOULD recognize the rest of the attribute types described in this section. Sciberras Standards Track [Page 4] RFC 4519 LDAP: Schema for User Applications June 2006 2.1. 'businessCategory' The 'businessCategory' attribute type describes the kinds of business performed by an organization. Each kind is one value of this multi-valued attribute. (Source: X.520 [X.520]) ( 2.5.4.15 NAME 'businessCategory' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) 1.3.6.1.4.1.1466.115.121.1.15 refers to the Directory String syntax [RFC4517]. Examples: "banking", "transportation", and "real estate". 2.2. 'c' The 'c' ('countryName' in X.500) attribute type contains a two-letter ISO 3166 [ISO3166] country code. (Source: X.520 [X.520]) ( 2.5.4.6 NAME 'c' SUP name SYNTAX 1.3.6.1.4.1.1466.115.121.1.11 SINGLE-VALUE ) 1.3.6.1.4.1.1466.115.121.1.11 refers to the Country String syntax [RFC4517]. Examples: "DE", "AU" and "FR". 2.3. 'cn' The 'cn' ('commonName' in X.500) attribute type contains names of an object. Each name is one value of this multi-valued attribute. If the object corresponds to a person, it is typically the person's full name. (Source: X.520 [X.520]) ( 2.5.4.3 NAME 'cn' SUP name ) Examples: "Martin K Smith", "Marty Smith" and "printer12". Sciberras Standards Track [Page 5] RFC 4519 LDAP: Schema for User Applications June 2006 2.4. 'dc' The 'dc' ('domainComponent' in RFC 1274) attribute type is a string holding one component, a label, of a DNS domain name [RFC1034][RFC2181] naming a host [RFC1123]. That is, a value of this attribute is a string of ASCII characters adhering to the following ABNF [RFC4234]: label = (ALPHA / DIGIT) [*61(ALPHA / DIGIT / HYPHEN) (ALPHA / DIGIT)] ALPHA = %x41-5A / %x61-7A ; "A"-"Z" / "a"-"z" DIGIT = %x30-39 ; "0"-"9" HYPHEN = %x2D ; hyphen ("-") The encoding of IA5String for use in LDAP is simply the characters of the ASCII label. The equality matching rule is case insensitive, as is today's DNS. (Source: RFC 2247 [RFC2247] and RFC 1274 [RFC 1274]) ( 0.9.2342.19200300.100.1.25 NAME 'dc' EQUALITY caseIgnoreIA5Match SUBSTR caseIgnoreIA5SubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 SINGLE-VALUE ) 1.3.6.1.4.1.1466.115.121.1.26 refers to the IA5 String syntax [RFC4517]. Examples: Valid values include "example" and "com" but not "example.com". The latter is invalid as it contains multiple domain components. It is noted that the directory service will not ensure that values of this attribute conform to the host label restrictions [RFC1123] illustrated by the <label> production provided above. It is the directory client's responsibility to ensure that the labels it stores in this attribute are appropriately restricted. Directory applications supporting International Domain Names SHALL use the ToASCII method [RFC3490] to produce the domain component label. The special considerations discussed in Section 4 of RFC 3490 [RFC3490] should be taken, depending on whether the domain component is used for "stored" or "query" purposes. 2.5. 'description' The 'description' attribute type contains human-readable descriptive phrases about the object. Each description is one value of this multi-valued attribute. (Source: X.520 [X.520]) Sciberras Standards Track [Page 6] RFC 4519 LDAP: Schema for User Applications June 2006 ( 2.5.4.13 NAME 'description' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) 1.3.6.1.4.1.1466.115.121.1.15 refers to the Directory String syntax [RFC4517]. Examples: "a color printer", "Maintenance is done every Monday, at 1pm.", and "distribution list for all technical staff". 2.6. 'destinationIndicator' The 'destinationIndicator' attribute type contains country and city strings associated with the object (the addressee) needed to provide the Public Telegram Service. The strings are composed in accordance with CCITT Recommendations F.1 [F.1] and F.31 [F.31]. Each string is one value of this multi-valued attribute. (Source: X.520 [X.520]) ( 2.5.4.27 NAME 'destinationIndicator' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.44 ) 1.3.6.1.4.1.1466.115.121.1.44 refers to the Printable String syntax [RFC4517]. Examples: "AASD" as a destination indicator for Sydney, Australia. "GBLD" as a destination indicator for London, United Kingdom. It is noted that the directory will not ensure that values of this attribute conform to the F.1 and F.31 CCITT Recommendations. It is the application's responsibility to ensure destination indicators that it stores in this attribute are appropriately constructed. 2.7. 'distinguishedName' The 'distinguishedName' attribute type is not used as the name of the object itself, but it is instead a base type from which some user attribute types with a DN syntax can inherit. It is unlikely that values of this type itself will occur in an entry. LDAP server implementations that do not support attribute subtyping need not recognize this attribute in requests. Client implementations MUST NOT assume that LDAP servers are capable of performing attribute subtyping. Sciberras Standards Track [Page 7] RFC 4519 LDAP: Schema for User Applications June 2006 (Source: X.520 [X.520]) ( 2.5.4.49 NAME 'distinguishedName' EQUALITY distinguishedNameMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 ) 1.3.6.1.4.1.1466.115.121.1.12 refers to the DN syntax [RFC4517]. 2.8. 'dnQualifier' The 'dnQualifier' attribute type contains disambiguating information strings to add to the relative distinguished name of an entry. The information is intended for use when merging data from multiple sources in order to prevent conflicts between entries that would otherwise have the same name. Each string is one value of this multi-valued attribute. It is recommended that a value of the 'dnQualifier' attribute be the same for all entries from a particular source. (Source: X.520 [X.520]) ( 2.5.4.46 NAME 'dnQualifier' EQUALITY caseIgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.44 ) 1.3.6.1.4.1.1466.115.121.1.44 refers to the Printable String syntax [RFC4517]. Examples: "20050322123345Z" - timestamps can be used to disambiguate information. "123456A" - serial numbers can be used to disambiguate information. 2.9. 'enhancedSearchGuide' The 'enhancedSearchGuide' attribute type contains sets of information for use by directory clients in constructing search filters. Each set is one value of this multi-valued attribute. (Source: X.520 [X.520]) ( 2.5.4.47 NAME 'enhancedSearchGuide' SYNTAX 1.3.6.1.4.1.1466.115.121.1.21 ) 1.3.6.1.4.1.1466.115.121.1.21 refers to the Enhanced Guide syntax [RFC4517]. Sciberras Standards Track [Page 8] RFC 4519 LDAP: Schema for User Applications June 2006 Examples: "person#(sn$APPROX)#wholeSubtree" and "organizationalUnit#(ou$SUBSTR)#oneLevel". 2.10. 'facsimileTelephoneNumber' The 'facsimileTelephoneNumber' attribute type contains telephone numbers (and, optionally, the parameters) for facsimile terminals. Each telephone number is one value of this multi-valued attribute. (Source: X.520 [X.520]) ( 2.5.4.23 NAME 'facsimileTelephoneNumber' SYNTAX 1.3.6.1.4.1.1466.115.121.1.22 ) 1.3.6.1.4.1.1466.115.121.1.22 refers to the Facsimile Telephone Number syntax [RFC4517]. Examples: "+61 3 9896 7801" and "+81 3 347 7418$fineResolution". 2.11. 'generationQualifier' The 'generationQualifier' attribute type contains name strings that are typically the suffix part of a person's name. Each string is one value of this multi-valued attribute. (Source: X.520 [X.520]) ( 2.5.4.44 NAME 'generationQualifier' SUP name ) Examples: "III", "3rd", and "Jr.". 2.12. 'givenName' The 'givenName' attribute type contains name strings that are the part of a person's name that is not their surname. Each string is one value of this multi-valued attribute. (Source: X.520 [X.520]) ( 2.5.4.42 NAME 'givenName' SUP name ) Examples: "Andrew", "Charles", and "Joanne". 2.13. 'houseIdentifier' The 'houseIdentifier' attribute type contains identifiers for a building within a location. Each identifier is one value of this multi-valued attribute. (Source: X.520 [X.520]) Sciberras Standards Track [Page 9] RFC 4519 LDAP: Schema for User Applications June 2006 ( 2.5.4.51 NAME 'houseIdentifier' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) 1.3.6.1.4.1.1466.115.121.1.15 refers to the Directory String syntax [RFC4517]. Example: "20" to represent the house number 20. 2.14. 'initials' The 'initials' attribute type contains strings of initials of some or all of an individual's names, except the surname(s). Each string is one value of this multi-valued attribute. (Source: X.520 [X.520]) ( 2.5.4.43 NAME 'initials' SUP name ) Examples: "K. A." and "K". 2.15. 'internationalISDNNumber' The 'internationalISDNNumber' attribute type contains Integrated Services Digital Network (ISDN) addresses, as defined in the International Telecommunication Union (ITU) Recommendation E.164 [E.164]. Each address is one value of this multi-valued attribute. (Source: X.520 [X.520]) ( 2.5.4.25 NAME 'internationalISDNNumber' EQUALITY numericStringMatch SUBSTR numericStringSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.36 ) 1.3.6.1.4.1.1466.115.121.1.36 refers to the Numeric String syntax [RFC4517]. Example: "0198 333 333". 2.16. 'l' The 'l' ('localityName' in X.500) attribute type contains names of a locality or place, such as a city, county, or other geographic region. Each name is one value of this multi-valued attribute. (Source: X.520 [X.520]) Sciberras Standards Track [Page 10] RFC 4519 LDAP: Schema for User Applications June 2006 ( 2.5.4.7 NAME 'l' SUP name ) Examples: "Geneva", "Paris", and "Edinburgh". 2.17. 'member' The 'member' attribute type contains the distinguished names of objects that are on a list or in a group. Each name is one value of this multi-valued attribute. (Source: X.520 [X.520]) ( 2.5.4.31 NAME 'member' SUP distinguishedName ) Examples: "cn=James Clarke,ou=Finance,o=Widget\, Inc." and "cn=John Xerri,ou=Finance,o=Widget\, Inc." may be two members of the financial team (group) at Widget, Inc., in which case, both of these distinguished names would be present as individual values of the member attribute. 2.18. 'name' The 'name' attribute type is the attribute supertype from which user attribute types with the name syntax inherit. Such attribute types are typically used for naming. The attribute type is multi-valued. It is unlikely that values of this type itself will occur in an entry. LDAP server implementations that do not support attribute subtyping need not recognize this attribute in requests. Client implementations MUST NOT assume that LDAP servers are capable of performing attribute subtyping. (Source: X.520 [X.520]) ( 2.5.4.41 NAME 'name' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) 1.3.6.1.4.1.1466.115.121.1.15 refers to the Directory String syntax [RFC4517]. 2.19. 'o' The 'o' ('organizationName' in X.500) attribute type contains the names of an organization. Each name is one value of this multi-valued attribute. Sciberras Standards Track [Page 11] RFC 4519 LDAP: Schema for User Applications June 2006 (Source: X.520 [X.520]) ( 2.5.4.10 NAME 'o' SUP name ) Examples: "Widget", "Widget, Inc.", and "Widget, Incorporated.". 2.20. 'ou' The 'ou' ('organizationalUnitName' in X.500) attribute type contains the names of an organizational unit. Each name is one value of this multi-valued attribute. (Source: X.520 [X.520]) ( 2.5.4.11 NAME 'ou' SUP name ) Examples: "Finance", "Human Resources", and "Research and Development". 2.21. 'owner' The 'owner' attribute type contains the distinguished names of objects that have an ownership responsibility for the object that is owned. Each owner's name is one value of this multi-valued attribute. (Source: X.520 [X.520]) ( 2.5.4.32 NAME 'owner' SUP distinguishedName ) Example: The mailing list object, whose DN is "cn=All Employees, ou=Mailing List,o=Widget\, Inc.", is owned by the Human Resources Director. Therefore, the value of the 'owner' attribute within the mailing list object, would be the DN of the director (role): "cn=Human Resources Director,ou=employee,o=Widget\, Inc.". 2.22. 'physicalDeliveryOfficeName' The 'physicalDeliveryOfficeName' attribute type contains names that a Postal Service uses to identify a post office. (Source: X.520 [X.520]) Sciberras Standards Track [Page 12] RFC 4519 LDAP: Schema for User Applications June 2006 ( 2.5.4.19 NAME 'physicalDeliveryOfficeName' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) 1.3.6.1.4.1.1466.115.121.1.15 refers to the Directory String syntax [RFC4517]. Examples: "Bremerhaven, Main" and "Bremerhaven, Bonnstrasse". 2.23. 'postalAddress' The 'postalAddress' attribute type contains addresses used by a Postal Service to perform services for the object. Each address is one value of this multi-valued attribute. (Source: X.520 [X.520]) ( 2.5.4.16 NAME 'postalAddress' EQUALITY caseIgnoreListMatch SUBSTR caseIgnoreListSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.41 ) 1.3.6.1.4.1.1466.115.121.1.41 refers to the Postal Address syntax [RFC4517]. Example: "15 Main St.$Ottawa$Canada". 2.24. 'postalCode' The 'postalCode' attribute type contains codes used by a Postal Service to identify postal service zones. Each code is one value of this multi-valued attribute. (Source: X.520 [X.520]) ( 2.5.4.17 NAME 'postalCode' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) 1.3.6.1.4.1.1466.115.121.1.15 refers to the Directory String syntax [RFC4517]. Example: "22180", to identify Vienna, VA, in the USA. Sciberras Standards Track [Page 13] RFC 4519 LDAP: Schema for User Applications June 2006 2.25. 'postOfficeBox' The 'postOfficeBox' attribute type contains postal box identifiers that a Postal Service uses when a customer arranges to receive mail at a box on the premises of the Postal Service. Each postal box identifier is a single value of this multi-valued attribute. (Source: X.520 [X.520]) ( 2.5.4.18 NAME 'postOfficeBox' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) 1.3.6.1.4.1.1466.115.121.1.15 refers to the Directory String syntax [RFC4517]. Example: "Box 45". 2.26. 'preferredDeliveryMethod' The 'preferredDeliveryMethod' attribute type contains an indication of the preferred method of getting a message to the object. (Source: X.520 [X.520]) ( 2.5.4.28 NAME 'preferredDeliveryMethod' SYNTAX 1.3.6.1.4.1.1466.115.121.1.14 SINGLE-VALUE ) 1.3.6.1.4.1.1466.115.121.1.14 refers to the Delivery Method syntax [RFC4517]. Example: If the mhs-delivery Delivery Method is preferred over telephone-delivery, which is preferred over all other methods, the value would be: "mhs $ telephone". 2.27. 'registeredAddress' The 'registeredAddress' attribute type contains postal addresses suitable for reception of telegrams or expedited documents, where it is necessary to have the recipient accept delivery. Each address is one value of this multi-valued attribute. (Source: X.520 [X.520]) ( 2.5.4.26 NAME 'registeredAddress' SUP postalAddress SYNTAX 1.3.6.1.4.1.1466.115.121.1.41 ) Sciberras Standards Track [Page 14] RFC 4519 LDAP: Schema for User Applications June 2006 1.3.6.1.4.1.1466.115.121.1.41 refers to the Postal Address syntax [RFC4517]. Example: "Receptionist$Widget, Inc.$15 Main St.$Ottawa$Canada". 2.28. 'roleOccupant' The 'roleOccupant' attribute type contains the distinguished names of objects (normally people) that fulfill the responsibilities of a role object. Each distinguished name is one value of this multi-valued attribute. (Source: X.520 [X.520]) ( 2.5.4.33 NAME 'roleOccupant' SUP distinguishedName ) Example: The role object, "cn=Human Resources Director,ou=Position,o=Widget\, Inc.", is fulfilled by two people whose object names are "cn=Mary Smith,ou=employee,o=Widget\, Inc." and "cn=James Brown,ou=employee,o=Widget\, Inc.". The 'roleOccupant' attribute will contain both of these distinguished names, since they are the occupants of this role. 2.29. 'searchGuide' The 'searchGuide' attribute type contains sets of information for use by clients in constructing search filters. It is superseded by 'enhancedSearchGuide', described above in Section 2.9. Each set is one value of this multi-valued attribute. (Source: X.520 [X.520]) ( 2.5.4.14 NAME 'searchGuide' SYNTAX 1.3.6.1.4.1.1466.115.121.1.25 ) 1.3.6.1.4.1.1466.115.121.1.25 refers to the Guide syntax [RFC4517]. Example: "person#sn$EQ". 2.30. 'seeAlso' The 'seeAlso' attribute type contains the distinguished names of objects that are related to the subject object. Each related object name is one value of this multi-valued attribute. (Source: X.520 [X.520]) ( 2.5.4.34 NAME 'seeAlso' SUP distinguishedName ) Sciberras Standards Track [Page 15] RFC 4519 LDAP: Schema for User Applications June 2006 Example: The person object "cn=James Brown,ou=employee,o=Widget\, Inc." is related to the role objects "cn=Football Team Captain,ou=sponsored activities,o=Widget\, Inc." and "cn=Chess Team,ou=sponsored activities,o=Widget\, Inc.". Since the role objects are related to the person object, the 'seeAlso' attribute will contain the distinguished name of each role object as separate values. 2.31. 'serialNumber' The 'serialNumber' attribute type contains the serial numbers of devices. Each serial number is one value of this multi-valued attribute. (Source: X.520 [X.520]) ( 2.5.4.5 NAME 'serialNumber' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.44 ) 1.3.6.1.4.1.1466.115.121.1.44 refers to the Printable String syntax [RFC4517]. Examples: "WI-3005" and "XF551426". 2.32. 'sn' The 'sn' ('surname' in X.500) attribute type contains name strings for the family names of a person. Each string is one value of this multi-valued attribute. (Source: X.520 [X.520]) ( 2.5.4.4 NAME 'sn' SUP name ) Example: "Smith". 2.33. 'st' The 'st' ('stateOrProvinceName' in X.500) attribute type contains the full names of states or provinces. Each name is one value of this multi-valued attribute. (Source: X.520 [X.520]) ( 2.5.4.8 NAME 'st' SUP name ) Example: "California". Sciberras Standards Track [Page 16] RFC 4519 LDAP: Schema for User Applications June 2006 2.34. 'street' The 'street' ('streetAddress' in X.500) attribute type contains site information from a postal address (i.e., the street name, place, avenue, and the house number). Each street is one value of this multi-valued attribute. (Source: X.520 [X.520]) ( 2.5.4.9 NAME 'street' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) 1.3.6.1.4.1.1466.115.121.1.15 refers to the Directory String syntax [RFC4517]. Example: "15 Main St.". 2.35. 'telephoneNumber' The 'telephoneNumber' attribute type contains telephone numbers that comply with the ITU Recommendation E.123 [E.123]. Each number is one value of this multi-valued attribute. (Source: X.520 [X.520]) ( 2.5.4.20 NAME 'telephoneNumber' EQUALITY telephoneNumberMatch SUBSTR telephoneNumberSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.50 ) 1.3.6.1.4.1.1466.115.121.1.50 refers to the Telephone Number syntax [RFC4517]. Example: "+1 234 567 8901". 2.36. 'teletexTerminalIdentifier' The withdrawal of Recommendation F.200 has resulted in the withdrawal of this attribute. (Source: X.520 [X.520]) ( 2.5.4.22 NAME 'teletexTerminalIdentifier' SYNTAX 1.3.6.1.4.1.1466.115.121.1.51 ) 1.3.6.1.4.1.1466.115.121.1.51 refers to the Teletex Terminal Identifier syntax [RFC4517]. Sciberras Standards Track [Page 17] RFC 4519 LDAP: Schema for User Applications June 2006 2.37. 'telexNumber' The 'telexNumber' attribute type contains sets of strings that are a telex number, country code, and answerback code of a telex terminal. Each set is one value of this multi-valued attribute. (Source: X.520 [X.520]) ( 2.5.4.21 NAME 'telexNumber' SYNTAX 1.3.6.1.4.1.1466.115.121.1.52 ) 1.3.6.1.4.1.1466.115.121.1.52 refers to the Telex Number syntax [RFC4517]. Example: "12345$023$ABCDE". 2.38. 'title' The 'title' attribute type contains the title of a person in their organizational context. Each title is one value of this multi-valued attribute. (Source: X.520 [X.520]) ( 2.5.4.12 NAME 'title' SUP name ) Examples: "Vice President", "Software Engineer", and "CEO". 2.39. 'uid' The 'uid' ('userid' in RFC 1274) attribute type contains computer system login names associated with the object. Each name is one value of this multi-valued attribute. (Source: RFC 2798 [RFC2798] and RFC 1274 [RFC1274]) ( 0.9.2342.19200300.100.1.1 NAME 'uid' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) 1.3.6.1.4.1.1466.115.121.1.15 refers to the Directory String syntax [RFC4517]. Examples: "s9709015", "admin", and "Administrator". Sciberras Standards Track [Page 18] RFC 4519 LDAP: Schema for User Applications June 2006 2.40. 'uniqueMember' The 'uniqueMember' attribute type contains the distinguished names of an object that is on a list or in a group, where the relative distinguished names of the object include a value that distinguishes between objects when a distinguished name has been reused. Each distinguished name is one value of this multi-valued attribute. (Source: X.520 [X.520]) ( 2.5.4.50 NAME 'uniqueMember' EQUALITY uniqueMemberMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.34 ) 1.3.6.1.4.1.1466.115.121.1.34 refers to the Name and Optional UID syntax [RFC4517]. Example: If "ou=1st Battalion,o=Defense,c=US" is a battalion that was disbanded, establishing a new battalion with the "same" name would have a unique identifier value added, resulting in "ou=1st Battalion, o=Defense,c=US#'010101'B". 2.41. 'userPassword' The 'userPassword' attribute contains octet strings that are known only to the user and the system to which the user has access. Each string is one value of this multi-valued attribute. The application SHOULD prepare textual strings used as passwords by transcoding them to Unicode, applying SASLprep [RFC4013], and encoding as UTF-8. The determination of whether a password is textual is a local client matter. (Source: X.509 [X.509]) ( 2.5.4.35 NAME 'userPassword' EQUALITY octetStringMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.40 ) 1.3.6.1.4.1.1466.115.121.1.40 refers to the Octet String syntax [RFC4517]. Passwords are stored using an Octet String syntax and are not encrypted. Transfer of cleartext passwords is strongly discouraged where the underlying transport service cannot guarantee confidentiality and may result in disclosure of the password to unauthorized parties. An example of a need for multiple values in the 'userPassword' attribute is an environment where every month the user is expected to Sciberras Standards Track [Page 19] RFC 4519 LDAP: Schema for User Applications June 2006 use a different password generated by some automated system. During transitional periods, like the last and first day of the periods, it may be necessary to allow two passwords for the two consecutive periods to be valid in the system. 2.42. 'x121Address' The 'x121Address' attribute type contains data network addresses as defined by ITU Recommendation X.121 [X.121]. Each address is one value of this multi-valued attribute. (Source: X.520 [X.520]) ( 2.5.4.24 NAME 'x121Address' EQUALITY numericStringMatch SUBSTR numericStringSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.36 ) 1.3.6.1.4.1.1466.115.121.1.36 refers to the Numeric String syntax [RFC4517]. Example: "36111222333444555". 2.43. 'x500UniqueIdentifier' The 'x500UniqueIdentifier' attribute type contains binary strings that are used to distinguish between objects when a distinguished name has been reused. Each string is one value of this multi-valued attribute. In X.520 [X.520], this attribute type is called 'uniqueIdentifier'. This is a different attribute type from both the 'uid' and 'uniqueIdentifier' LDAP attribute types. The 'uniqueIdentifier' attribute type is defined in [RFC4524]. (Source: X.520 [X.520]) ( 2.5.4.45 NAME 'x500UniqueIdentifier' EQUALITY bitStringMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.6 ) 1.3.6.1.4.1.1466.115.121.1.6 refers to the Bit String syntax [RFC4517]. 3. Object Classes LDAP servers SHOULD recognize all the Object Classes listed here as values of the 'objectClass' attribute (see [RFC4512]). Sciberras Standards Track [Page 20] RFC 4519 LDAP: Schema for User Applications June 2006 3.1. 'applicationProcess' The 'applicationProcess' object class definition is the basis of an entry that represents an application executing in a computer system. (Source: X.521 [X.521]) ( 2.5.6.11 NAME 'applicationProcess' SUP top STRUCTURAL MUST cn MAY ( seeAlso $ ou $ l $ description ) ) 3.2. 'country' The 'country' object class definition is the basis of an entry that represents a country. (Source: X.521 [X.521]) ( 2.5.6.2 NAME 'country' SUP top STRUCTURAL MUST c MAY ( searchGuide $ description ) ) 3.3. 'dcObject' The 'dcObject' object class permits an entry to contains domain component information. This object class is defined as auxiliary, because it will be used in conjunction with an existing structural object class. (Source: RFC 2247 [RFC2247]) ( 1.3.6.1.4.1.1466.344 NAME 'dcObject' SUP top AUXILIARY MUST dc ) 3.4. 'device' The 'device' object class is the basis of an entry that represents an appliance, computer, or network element. (Source: X.521 [X.521]) Sciberras Standards Track [Page 21] RFC 4519 LDAP: Schema for User Applications June 2006 ( 2.5.6.14 NAME 'device' SUP top STRUCTURAL MUST cn MAY ( serialNumber $ seeAlso $ owner $ ou $ o $ l $ description ) ) 3.5. 'groupOfNames' The 'groupOfNames' object class is the basis of an entry that represents a set of named objects including information related to the purpose or maintenance of the set. (Source: X.521 [X.521]) ( 2.5.6.9 NAME 'groupOfNames' SUP top STRUCTURAL MUST ( member $ cn ) MAY ( businessCategory $ seeAlso $ owner $ ou $ o $ description ) ) 3.6. 'groupOfUniqueNames' The 'groupOfUniqueNames' object class is the same as the 'groupOfNames' object class except that the object names are not repeated or reassigned within a set scope. (Source: X.521 [X.521]) Sciberras Standards Track [Page 22] RFC 4519 LDAP: Schema for User Applications June 2006 ( 2.5.6.17 NAME 'groupOfUniqueNames' SUP top STRUCTURAL MUST ( uniqueMember $ cn ) MAY ( businessCategory $ seeAlso $ owner $ ou $ o $ description ) ) 3.7. 'locality' The 'locality' object class is the basis of an entry that represents a place in the physical world. (Source: X.521 [X.521]) ( 2.5.6.3 NAME 'locality' SUP top STRUCTURAL MAY ( street $ seeAlso $ searchGuide $ st $ l $ description ) ) 3.8. 'organization' The 'organization' object class is the basis of an entry that represents a structured group of people. (Source: X.521 [X.521]) ( 2.5.6.4 NAME 'organization' SUP top STRUCTURAL MUST o MAY ( userPassword $ searchGuide $ seeAlso $ businessCategory $ x121Address $ registeredAddress $ destinationIndicator $ preferredDeliveryMethod $ telexNumber $ teletexTerminalIdentifier $ telephoneNumber $ internationalISDNNumber $ facsimileTelephoneNumber $ street $ postOfficeBox $ postalCode $ postalAddress $ physicalDeliveryOfficeName $ st $ l $ description ) ) Sciberras Standards Track [Page 23] RFC 4519 LDAP: Schema for User Applications June 2006 3.9. 'organizationalPerson' The 'organizationalPerson' object class is the basis of an entry that represents a person in relation to an organization. (Source: X.521 [X.521]) ( 2.5.6.7 NAME 'organizationalPerson' SUP person STRUCTURAL MAY ( title $ x121Address $ registeredAddress $ destinationIndicator $ preferredDeliveryMethod $ telexNumber $ teletexTerminalIdentifier $ telephoneNumber $ internationalISDNNumber $ facsimileTelephoneNumber $ street $ postOfficeBox $ postalCode $ postalAddress $ physicalDeliveryOfficeName $ ou $ st $ l ) ) 3.10. 'organizationalRole' The 'organizationalRole' object class is the basis of an entry that represents a job, function, or position in an organization. (Source: X.521 [X.521]) ( 2.5.6.8 NAME 'organizationalRole' SUP top STRUCTURAL MUST cn MAY ( x121Address $ registeredAddress $ destinationIndicator $ preferredDeliveryMethod $ telexNumber $ teletexTerminalIdentifier $ telephoneNumber $ internationalISDNNumber $ facsimileTelephoneNumber $ seeAlso $ roleOccupant $ preferredDeliveryMethod $ street $ postOfficeBox $ postalCode $ postalAddress $ physicalDeliveryOfficeName $ ou $ st $ l $ description ) ) 3.11. 'organizationalUnit' The 'organizationalUnit' object class is the basis of an entry that represents a piece of an organization. (Source: X.521 [X.521]) Sciberras Standards Track [Page 24] RFC 4519 LDAP: Schema for User Applications June 2006 ( 2.5.6.5 NAME 'organizationalUnit' SUP top STRUCTURAL MUST ou MAY ( businessCategory $ description $ destinationIndicator $ facsimileTelephoneNumber $ internationalISDNNumber $ l $ physicalDeliveryOfficeName $ postalAddress $ postalCode $ postOfficeBox $ preferredDeliveryMethod $ registeredAddress $ searchGuide $ seeAlso $ st $ street $ telephoneNumber $ teletexTerminalIdentifier $ telexNumber $ userPassword $ x121Address ) ) 3.12 'person' The 'person' object class is the basis of an entry that represents a human being. (Source: X.521 [X.521]) ( 2.5.6.6 NAME 'person' SUP top STRUCTURAL MUST ( sn $ cn ) MAY ( userPassword $ telephoneNumber $ seeAlso $ description ) ) 3.13. 'residentialPerson' The 'residentialPerson' object class is the basis of an entry that includes a person's residence in the representation of the person. (Source: X.521 [X.521]) ( 2.5.6.10 NAME 'residentialPerson' SUP person STRUCTURAL MUST l MAY ( businessCategory $ x121Address $ registeredAddress $ destinationIndicator $ preferredDeliveryMethod $ telexNumber $ teletexTerminalIdentifier $ telephoneNumber $ internationalISDNNumber $ facsimileTelephoneNumber $ preferredDeliveryMethod $ street $ postOfficeBox $ postalCode $ postalAddress $ physicalDeliveryOfficeName $ st $ l ) ) Sciberras Standards Track [Page 25] RFC 4519 LDAP: Schema for User Applications June 2006 3.14. 'uidObject' The 'uidObject' object class permits an entry to contains user identification information. This object class is defined as auxiliary, because it will be used in conjunction with an existing structural object class. (Source: RFC 2377 [RFC2377]) ( 1.3.6.1.1.3.1 NAME 'uidObject' SUP top AUXILIARY MUST uid ) 4. IANA Considerations The Internet Assigned Numbers Authority (IANA) has updated the LDAP descriptors registry as indicated in the following template: Subject: Request for LDAP Descriptor Registration Update Descriptor (short name): see comments Object Identifier: see comments Person & email address to contact for further information: Andrew Sciberras <andrew.sciberras@eb2bcom.com> Usage: (A = attribute type, O = Object Class) see comment Specification: RFC 4519 Author/Change Controller: IESG Comments In the LDAP descriptors registry, the following descriptors (short names) have been updated to refer to RFC 4519. Names that need to be reserved, rather than assigned to an Object Identifier, will contain an Object Identifier value of RESERVED. NAME Type OID ------------------------ ---- ---------------------------- applicationProcess O 2.5.6.11 businessCategory A 2.5.4.15 c A 2.5.4.6 cn A 2.5.4.3 commonName A 2.5.4.3 country O 2.5.6.2 countryName A 2.5.4.6 dc A 0.9.2342.19200300.100.1.25 dcObject O 1.3.6.1.4.1.1466.344 description A 2.5.4.13 destinationIndicator A 2.5.4.27 device O 2.5.6.14 Sciberras Standards Track [Page 26] RFC 4519 LDAP: Schema for User Applications June 2006 NAME Type OID ------------------------ ---- ---------------------------- distinguishedName A 2.5.4.49 dnQualifier A 2.5.4.46 domainComponent A 0.9.2342.19200300.100.1.25 enhancedSearchGuide A 2.5.4.47 facsimileTelephoneNumber A 2.5.4.23 generationQualifier A 2.5.4.44 givenName A 2.5.4.42 gn A RESERVED groupOfNames O 2.5.6.9 groupOfUniqueNames O 2.5.6.17 houseIdentifier A 2.5.4.51 initials A 2.5.4.43 internationalISDNNumber A 2.5.4.25 l A 2.5.4.7 locality O 2.5.6.3 localityName A 2.5.4.7 member A 2.5.4.31 name A 2.5.4.41 o A 2.5.4.10 organization O 2.5.6.4 organizationName A 2.5.4.10 organizationalPerson O 2.5.6.7 organizationalRole O 2.5.6.8 organizationalUnit O 2.5.6.5 organizationalUnitName A 2.5.4.11 ou A 2.5.4.11 owner A 2.5.4.32 person O 2.5.6.6 physicalDeliveryOfficeName A 2.5.4.19 postalAddress A 2.5.4.16 postalCode A 2.5.4.17 postOfficeBox A 2.5.4.18 preferredDeliveryMethod A 2.5.4.28 registeredAddress A 2.5.4.26 residentialPerson O 2.5.6.10 roleOccupant A 2.5.4.33 searchGuide A 2.5.4.14 seeAlso A 2.5.4.34 serialNumber A 2.5.4.5 sn A 2.5.4.4 st A 2.5.4.8 street A 2.5.4.9 surname A 2.5.4.4 telephoneNumber A 2.5.4.20 teletexTerminalIdentifier A 2.5.4.22 telexNumber A 2.5.4.21 Sciberras Standards Track [Page 27] RFC 4519 LDAP: Schema for User Applications June 2006 NAME Type OID ------------------------ ---- ---------------------------- title A 2.5.4.12 uid A 0.9.2342.19200300.100.1.1 uidObject O 1.3.6.1.1.3.1 uniqueMember A 2.5.4.50 userid A 0.9.2342.19200300.100.1.1 userPassword A 2.5.4.35 x121Address A 2.5.4.24 x500UniqueIdentifier A 2.5.4.45 5. Security Considerations Attributes of directory entries are used to provide descriptive information about the real-world objects they represent, which can be people, organizations, or devices. Most countries have privacy laws regarding the publication of information about people. Transfer of cleartext passwords is strongly discouraged where the underlying transport service cannot guarantee confidentiality and integrity, since this may result in disclosure of the password to unauthorized parties. Multiple attribute values for the 'userPassword' attribute need to be used with care. Especially reset/deletion of a password by an administrator without knowing the old user password gets tricky or impossible if multiple values for different applications are present. Certainly, applications that intend to replace the 'userPassword' value(s) with new value(s) should use modify/replaceValues (or modify/deleteAttribute+addAttribute). In addition, server implementations are encouraged to provide administrative controls that, if enabled, restrict the 'userPassword' attribute to one value. Note that when used for authentication purposes [RFC4513], the user need only prove knowledge of one of the values, not all of the values. 6. Acknowledgements The definitions, on which this document is based, have been developed by committees for telecommunications and international standards. This document is an update of RFC 2256 by Mark Wahl. RFC 2256 was a product of the IETF ASID Working Group. Sciberras Standards Track [Page 28] RFC 4519 LDAP: Schema for User Applications June 2006 The 'dc' attribute type definition and the 'dcObject' object class definition in this document supersede the specification in RFC 2247 by S. Kille, M. Wahl, A. Grimstad, R. Huber, and S. Sataluri. The 'uid' attribute type definition in this document supersedes the specification of the 'userid' in RFC 1274 by P. Barker and S. Kille and of the uid in RFC 2798 by M. Smith. The 'uidObject' object class definition in this document supersedes the specification of the 'uidObject' in RFC 2377 by A. Grimstad, R. Huber, S. Sataluri, and M. Wahl. This document is based upon input of the IETF LDAPBIS working group. The author wishes to thank S. Legg and K. Zeilenga for their significant contribution to this update. The author would also like to thank Kathy Dally, who edited early versions of this document. 7. References 7.1. Normative References [E.123] Notation for national and international telephone numbers, ITU-T Recommendation E.123, 1988 [E.164] The international public telecommunication numbering plan, ITU-T Recommendation E.164, 1997 [F.1] Operational Provisions For The International Public Telegram Service Transmission System, CCITT Recommendation F.1, 1992 [F.31] Telegram Retransmission System, CCITT Recommendation F.31, 1988 [ISO3166] ISO 3166, "Codes for the representation of names of countries". [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", STD 13, RFC 1034, November 1987. [RFC1123] Braden, R., "Requirements for Internet Hosts - Application and Support", STD 3, RFC 1123, October 1989. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2181] Elz, R. and R. Bush, "Clarifications to the DNS Specification", RFC 2181, July 1997. Sciberras Standards Track [Page 29] RFC 4519 LDAP: Schema for User Applications June 2006 [RFC3490] Faltstrom, P., Hoffman, P., and A. Costello, "Internationalizing Domain Names in Applications (IDNA)", RFC 3490, March 2003. [RFC4013] Zeilenga, K., "SASLprep: Stringprep Profile for User Names and Passwords", RFC 4013, February 2005. [RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 4234, October 2005. [RFC4510] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006. [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006. [RFC4517] Legg, S., Ed., "Lightweight Directory Access Protocol (LDAP): Syntaxes and Matching Rules", RFC 4517, June 2006. [X.121] International numbering plan for public data networks, ITU-T Recommendation X.121, 1996 [X.509] The Directory: Authentication Framework, ITU-T Recommendation X.509, 1993 [X.520] The Directory: Selected Attribute Types, ITU-T Recommendation X.520, 1993 [X.521] The Directory: Selected Object Classes. ITU-T Recommendation X.521, 1993 7.2. Informative References [RFC1274] Barker, P. and S. Kille, "The COSINE and Internet X.500 Schema", RFC 1274, November 1991. [RFC2247] Kille, S., Wahl, M., Grimstad, A., Huber, R., and S. Sataluri, "Using Domains in LDAP/X.500 Distinguished Names", RFC 2247, January 1998. [RFC2377] Grimstad, A., Huber, R., Sataluri, S., and M. Wahl, "Naming Plan for Internet Directory-Enabled Applications", RFC 2377, September 1998. [RFC2798] Smith, M., "Definition of the inetOrgPerson LDAP Object Class", RFC 2798, April 2000. Sciberras Standards Track [Page 30] RFC 4519 LDAP: Schema for User Applications June 2006 [RFC4513] Harrison R., Ed., "Lightweight Directory Access Protocol (LDAP): Authentication Methods and Security Mechanisms", RFC 4513, June 2006. [RFC4523] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP) Schema Definitions for X.509 Certificates", RFC 4523, June 2006. [RFC4524] Zeilenga, E., Ed., "COSINE LDAP/X.500 Schema", RFC 4524, June 2006. [X.500] ITU-T Recommendations X.500 (1993) | ISO/IEC 9594-1:1994, Information Technology - Open Systems Interconnection - The Directory: Overview of concepts, models and services. Sciberras Standards Track [Page 31] RFC 4519 LDAP: Schema for User Applications June 2006 Appendix A. Changes Made Since RFC 2256 This appendix lists the changes that have been made from RFC 2256 to RFC 4519. This appendix is not a normative part of this specification, which has been provided for informational purposes only. 1. Replaced the document title. 2. Removed the IESG Note. 3. Dependencies on RFC 1274 have been eliminated. 4. Added a Security Considerations section and an IANA Considerations section. 5. Deleted the conformance requirement for subschema object classes in favor of a statement in [RFC4517]. 6. Added explanation to attribute types and to each object class. 7. Removed Section 4, Syntaxes, and Section 6, Matching Rules, (moved to [RFC4517]). 8. Removed the certificate-related attribute types: authorityRevocationList, cACertificate, certificateRevocationList, crossCertificatePair, deltaRevocationList, supportedAlgorithms, and userCertificate. Removed the certificate-related Object Classes: certificationAuthority, certificationAuthority-V2, cRLDistributionPoint, strongAuthenticationUser, and userSecurityInformation LDAP PKI is now discussed in [RFC4523]. 9. Removed the dmdName, knowledgeInformation, presentationAddress, protocolInformation, and supportedApplicationContext attribute types and the dmd, applicationEntity, and dSA object classes. 10. Deleted the aliasedObjectName and objectClass attribute type definitions. Deleted the alias and top object class definitions. They are included in [RFC4512]. Sciberras Standards Track [Page 32] RFC 4519 LDAP: Schema for User Applications June 2006 11. Added the 'dc' attribute type from RFC 2247, making the distinction between 'stored' and 'query' values when preparing IDN strings. 12. Numerous editorial changes. 13. Removed upper bound after the SYNTAX oid in all attribute definitions where it appeared. 14. Added text about Unicode, SASLprep [RFC4013], and UTF-8 for userPassword. 15. Included definitions, comments and references for 'dcObject' and 'uidObject'. 16. Replaced PKI schema references to use RFC 4523. 17. Spelt out and referenced ABNF on first usage. 18. Removed Section 2.4 (Source). Replaced the source table with explicit references for each definition. 19. All references to an attribute type or object class are enclosed in single quotes. 20. The layout of attribute type definitions has been changed to provide consistency throughout the document: > Section Heading > Description of Attribute type > Multivalued description > Source Information > Definition > Example > Additional Comments Adding this consistent output included the addition of examples to some definitions. 21. References to alternate names for attributes types are provided with a reference to where they were originally specified. 22. Clarification of the description of 'distinguishedName' and 'name', in regards to these attribute types being supertypes. 23. Spelt out ISDN on first usage. Sciberras Standards Track [Page 33] RFC 4519 LDAP: Schema for User Applications June 2006 24. Inserted a reference to [RFC4517] for the 'teletexTerminalIdentifier' definition's SYNTAX OID. 25. Additional names were added to the IANA Considerations. Names include 'commonName', 'dcObject', 'domainComponent', 'GN', 'localityName', 'organizationName', 'organizationUnitName', 'surname', 'uidObject' and 'userid'. 26. Renamed all instances of supercede to supersede. 27. Moved [F.1], [F.31] and [RFC4013] from informative to normative references. 28. Changed the 'c' definition to be consistent with X.500. Author's Address Andrew Sciberras eB2Bcom Suite 3, Woodhouse Corporate Centre, 935 Station Street, Box Hill North, Victoria 3129 AUSTRALIA Phone: +61 3 9896 7833 EMail: andrew.sciberras@eb2bcom.com Sciberras Standards Track [Page 34] RFC 4519 LDAP: Schema for User Applications June 2006 Full Copyright Statement Copyright (C) The Internet Society (2006). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Sciberras Standards Track [Page 35] PK .�c\�h _ _ ( doc/alt-openldap11-devel/rfc/rfc3672.txtnu �[��� Network Working Group K. Zeilenga Request for Comments: 3672 OpenLDAP Foundation Category: Standards Track S. Legg Adacel Technologies December 2003 Subentries in the Lightweight Directory Access Protocol (LDAP) Status of this Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2003). All Rights Reserved. Abstract In X.500 directories, subentries are special entries used to hold information associated with a subtree or subtree refinement. This document adapts X.500 subentries mechanisms for use with the Lightweight Directory Access Protocol (LDAP). 1. Overview From [X.501]: A subentry is a special kind of entry immediately subordinate to an administrative point. It contains attributes that pertain to a subtree (or subtree refinement) associated with its administrative point. The subentries and their administrative point are part of the same naming context. A single subentry may serve all or several aspects of administrative authority. Alternatively, a specific aspect of administrative authority may be handled through one or more of its own subentries. Subentries in the Lightweight Directory Access Protocol (LDAP) [RFC3377] SHALL behave in accordance with X.501 unless noted otherwise in this specification. Zeilenga & Legg Standards Track [Page 1] RFC 3672 Subentries in LDAP December 2003 In absence of the subentries control (detailed in Section 3), subentries SHALL NOT be considered in one-level and subtree scope search operations. For all other operations, including base scope search operations, subentries SHALL be considered. 1.1. Conventions Schema definitions are provided using LDAP description formats [RFC2252]. Definitions provided here are formatted (line wrapped) for readability. Protocol elements are described using ASN.1 [X.680]. The term "BER- encoded" means the element is to be encoded using the Basic Encoding Rules [X.690] under the restrictions detailed in Section 5.1 of [RFC2251]. 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]. 2. Subentry Schema 2.1. Subtree Specification Syntax The Subtree Specification syntax provides a general purpose mechanism for the specification of a subset of entries in a subtree of the Directory Information Tree (DIT). A subtree begins at some base entry and includes the subordinates of that entry down to some identified lower boundary, possibly extending to the leaf entries. A subtree specification is always used within a context or scope which implicitly determines the bounds of the subtree. For example, the scope of a subtree specification for a subschema administrative area does not include the subtrees of any subordinate administrative point entries for subschema administration. Where a subtree specification does not identify a contiguous subset of the entries within a single subtree the collection is termed a subtree refinement. This syntax corresponds to the SubtreeSpecification ASN.1 type described in [X.501], Section 11.3. This ASN.1 data type definition is reproduced here for completeness. SubtreeSpecification ::= SEQUENCE { base [0] LocalName DEFAULT { }, COMPONENTS OF ChopSpecification, specificationFilter [4] Refinement OPTIONAL } LocalName ::= RDNSequence Zeilenga & Legg Standards Track [Page 2] RFC 3672 Subentries in LDAP December 2003 ChopSpecification ::= SEQUENCE { specificExclusions [1] SET OF CHOICE { chopBefore [0] LocalName, chopAfter [1] LocalName } OPTIONAL, minimum [2] BaseDistance DEFAULT 0, maximum [3] BaseDistance OPTIONAL } BaseDistance ::= INTEGER (0 .. MAX) Refinement ::= CHOICE { item [0] OBJECT-CLASS.&id, and [1] SET OF Refinement, or [2] SET OF Refinement, not [3] Refinement } The components of SubtreeSpecification are: base, which identifies the base entry of the subtree or subtree refinement, and specificExclusions, minimum, maximum and specificationFilter, which then reduce the set of subordinate entries of the base entry. The subtree or subtree refinement contains all the entries within scope that are not excluded by any of the components of the subtree specification. When all of the components of SubtreeSpecification are absent (i.e., when a value of the Subtree Specification syntax is the empty sequence, {}), the specified subtree implicitly includes all the entries within scope. Any particular use of this mechanism MAY impose limitations or constraints on the components of SubtreeSpecification. The LDAP syntax specification is: ( 1.3.6.1.4.1.1466.115.121.1.45 DESC 'SubtreeSpecification' ) The LDAP-specific encoding of values of this syntax is defined by the Generic String Encoding Rules [RFC3641]. Appendix A provides an equivalent Augmented Backus-Naur Form (ABNF) [RFC2234] for this syntax. 2.1.1. Base The base component of SubtreeSpecification nominates the base entry of the subtree or subtree refinement. The base entry may be an entry which is subordinate to the root entry of the scope in which the subtree specification is used, in which case the base component contains a sequence of Relative Distinguished Names (RDNs) relative to the root entry of the scope, or may be the root entry of the scope itself (the default), in which case the base component is absent or contains an empty sequence of RDNs. Zeilenga & Legg Standards Track [Page 3] RFC 3672 Subentries in LDAP December 2003 Entries that are not subordinates of the base entry are excluded from the subtree or subtree refinement. 2.1.2. Specific Exclusions The specificExclusions component of a ChopSpecification is a list of exclusions that specify entries and their subordinates to be excluded from the subtree or subtree refinement. The entry is specified by a sequence of RDNs relative to the base entry (i.e., a LocalName). Each exclusion is of either the chopBefore or chopAfter form. If the chopBefore form is used then the specified entry and its subordinates are excluded from the subtree or subtree refinement. If the chopAfter form is used then only the subordinates of the specified entry are excluded from the subtree or subtree refinement. 2.1.3. Minimum and Maximum The minimum and maximum components of a ChopSpecification allow the exclusion of entries based on their depth in the DIT. Entries that are less than the minimum number of RDN arcs below the base entry are excluded from the subtree or subtree refinement. A minimum value of zero (the default) corresponds to the base entry. Entries that are more than the maximum number of RDN arcs below the base entry are excluded from the subtree or subtree refinement. An absent maximum component indicates that there is no upper limit on the number of RDN arcs below the base entry for entries in the subtree or subtree refinement. 2.1.4. Specification Filter The specificationFilter component is a boolean expression of assertions about the values of the objectClass attribute of the base entry and its subordinates. A Refinement assertion item evaluates to true for an entry if that entry's objectClass attribute contains the OID nominated in the assertion. Entries for which the overall filter evaluates to false are excluded from the subtree refinement. If the specificationFilter is absent then no entries are excluded from the subtree or subtree refinement because of their objectClass attribute values. Zeilenga & Legg Standards Track [Page 4] RFC 3672 Subentries in LDAP December 2003 2.2. Administrative Role Attribute Type The Administrative Model defined in [X.501], clause 10 requires that administrative entries contain an administrativeRole attribute to indicate that the associated administrative area is concerned with one or more administrative roles. The administrativeRole operational attribute is specified as follows: ( 2.5.18.5 NAME 'administrativeRole' EQUALITY objectIdentifierMatch USAGE directoryOperation SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 ) The possible values of this attribute defined in X.501 are: OID NAME -------- ------------------------------- 2.5.23.1 autonomousArea 2.5.23.2 accessControlSpecificArea 2.5.23.3 accessControlInnerArea 2.5.23.4 subschemaAdminSpecificArea 2.5.23.5 collectiveAttributeSpecificArea 2.5.23.6 collectiveAttributeInnerArea Other values may be defined in other specifications. Names associated with each administrative role are Object Identifier Descriptors [RFC3383]. The administrativeRole operational attribute is also used to regulate the subentries permitted to be subordinate to an administrative entry. A subentry not of a class permitted by the administrativeRole attribute cannot be subordinate to the administrative entry. 2.3. Subtree Specification Attribute Type The subtreeSpecification operational attribute is defined as follows: ( 2.5.18.6 NAME 'subtreeSpecification' SINGLE-VALUE USAGE directoryOperation SYNTAX 1.3.6.1.4.1.1466.115.121.1.45 ) This attribute is present in all subentries. See [X.501], clause 10. Values of the subtreeSpecification attribute nominate collections of entries within the DIT for one or more aspects of administrative authority. Zeilenga & Legg Standards Track [Page 5] RFC 3672 Subentries in LDAP December 2003 2.4. Subentry Object Class The subentry object class is a structural object class. ( 2.5.17.0 NAME 'subentry' SUP top STRUCTURAL MUST ( cn $ subtreeSpecification ) ) 3. Subentries Control The subentries control MAY be sent with a searchRequest to control the visibility of entries and subentries which are within scope. Non-visible entries or subentries are not returned in response to the request. The subentries control is an LDAP Control whose controlType is 1.3.6.1.4.1.4203.1.10.1, criticality is TRUE or FALSE (hence absent), and controlValue contains a BER-encoded BOOLEAN indicating visibility. A controlValue containing the value TRUE indicates that subentries are visible and normal entries are not. A controlValue containing the value FALSE indicates that normal entries are visible and subentries are not. Note that TRUE visibility has the three octet encoding { 01 01 FF } and FALSE visibility has the three octet encoding { 01 01 00 }. The controlValue SHALL NOT be absent. In absence of this control, subentries are not visible to singleLevel and wholeSubtree scope Search requests but are visible to baseObject scope Search requests. There is no corresponding response control. This control is not appropriate for non-Search operations. 4. Security Considerations Subentries often hold administrative information or other sensitive information and should be protected from unauthorized access and disclosure as described in [RFC2829][RFC2830]. General LDAP [RFC3377] security considerations also apply. Zeilenga & Legg Standards Track [Page 6] RFC 3672 Subentries in LDAP December 2003 5. IANA Considerations 5.1. Descriptors The IANA has registered the LDAP descriptors detailed in this technical specification. The following registration template is suggested: Subject: Request for LDAP Descriptor Registration Descriptor (short name): see comment Object Identifier: see comment Person & email address to contact for further information: Kurt Zeilenga <kurt@OpenLDAP.org> Usage: see comment Specification: RFC3672 Author/Change Controller: IESG Comments: NAME Type OID ------------------------ ---- -------- accessControlInnerArea R 2.5.23.3 accessControlSpecificArea R 2.5.23.2 administrativeRole A 2.5.18.5 autonomousArea R 2.5.23.1 collectiveAttributeInnerArea R 2.5.23.6 collectiveAttributeSpecificArea R 2.5.23.5 subentry O 2.5.17.0 subschemaAdminSpecificArea R 2.5.23.4 subtreeSpecification A 2.5.18.6 where Type A is Attribute, Type O is ObjectClass, and Type R is Administrative Role. 5.2. Object Identifiers This document uses the OID 1.3.6.1.4.1.4203.1.10.1 to identify an LDAP protocol element defined herein. This OID was assigned [ASSIGN] by OpenLDAP Foundation, under its IANA-assigned private enterprise allocation [PRIVATE], for use in this specification. Other OIDs which appear in this document were either assigned by the ISO/IEC Joint Technical Committee 1 - Subcommittee 6 to identify elements of X.500 schema or assigned in RFC 2252 for the use described here. Zeilenga & Legg Standards Track [Page 7] RFC 3672 Subentries in LDAP December 2003 5.3. Protocol Mechanisms The IANA has registered the LDAP protocol mechanisms [RFC3383] detailed in this specification. Subject: Request for LDAP Protocol Mechanism Registration Description: Subentries Person & email address to contact for further information: Kurt Zeilenga <kurt@openldap.org> Usage: Control Specification: RFC3672 Author/Change Controller: IESG Comments: none 6. Acknowledgment This document is based on engineering done by IETF LDUP and LDAPext Working Groups including "LDAP Subentry Schema" by Ed Reed. This document also borrows from a number of ITU documents including X.501. 7. 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. Zeilenga & Legg Standards Track [Page 8] RFC 3672 Subentries in LDAP December 2003 A. Subtree Specification ABNF This appendix is non-normative. The LDAP-specific string encoding for the Subtree Specification syntax is specified by the Generic String Encoding Rules [RFC3641]. The ABNF [RFC2234] in this appendix for this syntax is provided only as a convenience and is equivalent to the encoding specified by the application of [RFC3641]. Since the SubtreeSpecification ASN.1 type may be extended in future editions of [X.501], the provided ABNF should be regarded as a snapshot in time. The LDAP-specific encoding for any extension to the SubtreeSpecification ASN.1 type can be determined from [RFC3641]. In the event that there is a discrepancy between this ABNF and the encoding determined by [RFC3641], [RFC3641] is to be taken as definitive. SubtreeSpecification = "{" [ sp ss-base ] [ sep sp ss-specificExclusions ] [ sep sp ss-minimum ] [ sep sp ss-maximum ] [ sep sp ss-specificationFilter ] sp "}" ss-base = id-base msp LocalName ss-specificExclusions = id-specificExclusions msp SpecificExclusions ss-minimum = id-minimum msp BaseDistance ss-maximum = id-maximum msp BaseDistance ss-specificationFilter = id-specificationFilter msp Refinement id-base = %x62.61.73.65 ; "base" id-specificExclusions = %x73.70.65.63.69.66.69.63.45.78.63.6C.75.73 %x69.6F.6E.73 ; "specificExclusions" id-minimum = %x6D.69.6E.69.6D.75.6D ; "minimum" id-maximum = %x6D.61.78.69.6D.75.6D ; "maximum" id-specificationFilter = %x73.70.65.63.69.66.69.63.61.74.69.6F.6E.46 %x69.6C.74.65.72 ; "specificationFilter" SpecificExclusions = "{" [ sp SpecificExclusion *( "," sp SpecificExclusion ) ] sp "}" SpecificExclusion = chopBefore / chopAfter chopBefore = id-chopBefore ":" LocalName chopAfter = id-chopAfter ":" LocalName id-chopBefore = %x63.68.6F.70.42.65.66.6F.72.65 ; "chopBefore" id-chopAfter = %x63.68.6F.70.41.66.74.65.72 ; "chopAfter" Zeilenga & Legg Standards Track [Page 9] RFC 3672 Subentries in LDAP December 2003 Refinement = item / and / or / not item = id-item ":" OBJECT-IDENTIFIER and = id-and ":" Refinements or = id-or ":" Refinements not = id-not ":" Refinement Refinements = "{" [ sp Refinement *( "," sp Refinement ) ] sp "}" id-item = %x69.74.65.6D ; "item" id-and = %x61.6E.64 ; "and" id-or = %x6F.72 ; "or" id-not = %x6E.6F.74 ; "not" BaseDistance = INTEGER-0-MAX The <sp>, <msp>, <sep>, <INTEGER>, <INTEGER-0-MAX>, <OBJECT- IDENTIFIER> and <LocalName> rules are defined in [RFC3642]. Normative References [X.501] ITU-T, "The Directory -- Models," X.501, 1993. [X.680] ITU-T, "Abstract Syntax Notation One (ASN.1) - Specification of Basic Notation", X.680, 1994. [X.690] ITU-T, "Specification of ASN.1 encoding rules: Basic, Canonical, and Distinguished Encoding Rules", X.690, 1994. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 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. [RFC2830] Hodges, J., Morgan, R. and M. Wahl, "Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security", RFC 2830, May 2000. [RFC3377] Hodges, J. and R. Morgan, "Lightweight Directory Access Protocol (v3): Technical Specification", RFC 3377, September 2002. Zeilenga & Legg Standards Track [Page 10] RFC 3672 Subentries in LDAP December 2003 [RFC3383] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", RFC 3383, September 2002. [RFC3641] Legg, S., "Generic String Encoding Rules (GSER) for ASN.1 Types", RFC 3641, October 2003. Informative References [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, November 1997. [RFC3642] Legg, S., "Common Elements of Generic String Encoding Rules (GSER) Encodings", RFC 3642, October 2003. [ASSIGN] OpenLDAP Foundation, "OpenLDAP OID Delegations", http://www.openldap.org/foundation/oid-delegate.txt [PRIVATE] IANA, "Private Enterprise Numbers", http://www.iana.org/assignments/enterprise-numbers Authors' Addresses Kurt D. Zeilenga OpenLDAP Foundation EMail: Kurt@OpenLDAP.org Steven Legg Adacel Technologies Ltd. 250 Bay Street Brighton, Victoria 3186 AUSTRALIA Phone: +61 3 8530 7710 Fax: +61 3 8530 7888 EMail: steven.legg@adacel.com.au Zeilenga & Legg Standards Track [Page 11] RFC 3672 Subentries in LDAP December 2003 Full Copyright Statement Copyright (C) The Internet Society (2003). 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 assignees. 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. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Zeilenga & Legg Standards Track [Page 12] PK .�c\\r��)� )� ( doc/alt-openldap11-devel/rfc/rfc2713.txtnu �[��� Network Working Group V. Ryan Request for Comments: 2713 S. Seligman Category: Informational R. Lee Sun Microsystems, Inc. October 1999 Schema for Representing Java(tm) Objects in an LDAP Directory Status of this Memo This memo provides information for the Internet community. It does not specify an Internet standard of any kind. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (1999). All Rights Reserved. Abstract This document defines the schema for representing Java(tm) objects in an LDAP directory [LDAPv3]. It defines schema elements to represent a Java serialized object [Serial], a Java marshalled object [RMI], a Java remote object [RMI], and a JNDI reference [JNDI]. 1. Introduction This document assumes that the reader has a general knowledge of the Java programming language [Java]. For brevity we use the term "Java object" in place of "object in the Java programming language" throughout this text. Traditionally, LDAP directories have been used to store data. Users and programmers think of the directory as a hierarchy of directory entries, each containing a set of attributes. You look up an entry from the directory and extract the attribute(s) of interest. For example, you can look up a person's telephone number from the directory. Alternatively, you can search the directory for entries with a particular set of attributes. For example, you can search for all persons in the directory with the surname "Smith". For applications written in the Java programming language, a kind of data that is typically shared are Java objects themselves. For such applications, it makes sense to be able to use the directory as a repository for Java objects. The directory provides a centrally administered, and possibly replicated, service for use by Java applications distributed across the network. Ryan, et al. Informational [Page 1] RFC 2713 Schema for Java Objects October 1999 For example, an application server might use the directory for "registering" objects representing the services that it manages, so that a client can later search the directory to locate those services as it needs. The motivation for this document is to define a common way for applications to store and retrieve Java objects from the directory. Using this common schema, any Java application that needs to read or store Java objects in the directory can do so in an interoperable way. 2 Representation of Java Objects This document defines schema elements to represent three types of Java objects: a Java serialized object, a Java marshalled object, and a JNDI reference. A Java remote object is stored as either a Java marshalled object or a JNDI reference. 2.1 Common Representations A Java object is stored in the LDAP directory by using the object class javaObject. This is the base class from which other Java object related classes derive: javaSerializedObject, javaMarshalledObject, and javaNamingReference. javaObject is an abstract object class, which means that a javaObject cannot exist by itself in the directory; only auxiliary or structural subclasses of it can exist in the directory. The object class javaContainer represents a directory entry dedicated to storing a Java object. It is a structural object class. In cases where a subclass of javaObject is mixed in with another structural object class, javaContainer is not required. The definitions for the object classes javaObject and javaContainer are presented in Section 4. The javaObject class has one mandatory attribute (javaClassName) and four optional attributes (javaClassNames, javaCodebase, javaDoc, description). javaClassName is a single valued attribute that is used to store the fully qualified name of the object's Java class (for example, "java.lang.String"). This may be the object's most derived class's name, but does not have to be; that of a superclass or interface in some cases might be most appropriate. This attribute is intended for storing the name of the object's "distinguished" class, that is, the class or interface with which the object should be identified. Ryan, et al. Informational [Page 2] RFC 2713 Schema for Java Objects October 1999 javaClassNames is a multivalued attribute that is used to store the fully qualified names of the object's Java classes and interfaces (for example, "java.lang.Byte"). Like all multivalued attributes, the javaClassNames attribute's values are unordered and so no one value is more "distinguished" than the others. This attribute is intended for storing an object's class and interface names and those of its ancestor classes and interfaces, although the list of values does not have to be complete. If the javaClassNames attribute is present, it should include the value of javaClassName. For example, suppose an object is stored in the directory with a javaClassName attribute of "java.io.FilePermission", and a javaClassNames attribute of {"java.security.Permission", "java.io.FilePermission", "java.security.Guard", "java.io.Serializable"}. An application searching a directory for Java objects might use javaClassName to produce a summary of the names and types of Java objects in that directory. Another application might use the javaClassNames attribute to find, for example, all java.security.Permission objects. javaCodebase is a multivalued attribute that is used to store the location(s) of the object's class definition. javaDoc is used to store a pointer (URL) to the Java documentation for the class. description is used to store a textual description of a Java object and is defined in [v3Schema]. The definitions of these attributes are presented in Section 3. 2.2 Serialized Objects To "serialize" an object means to convert its state into a byte stream in such a way that the byte stream can be converted back into a copy of the object. A Java object is "serializable" if its class or any of its superclasses implements either the java.io.Serializable interface or its subinterface java.io.Externalizable. "Deserialization" is the process of converting the serialized form of an object back into a copy of the object. When an object is serialized, the entire tree of objects rooted at the object is also serialized. When it is deserialized, the tree is reconstructed. For example, suppose a serializable Book object contains (a serializable field of) an array of Page objects. When a Book object is serialized, so is the array of Page objects. The Java platform specifies a default algorithm by which serializable objects are serialized. A Java class can also override this default serialization with its own algorithm. [Serial] describes object serialization in detail. Ryan, et al. Informational [Page 3] RFC 2713 Schema for Java Objects October 1999 When an object is serialized, information that identifies its class is recorded in the serialized stream. However, the class's definition ("class file") itself is not recorded. It is the responsibility of the system that is deserializing the object to determine the mechanism to use for locating and loading the associated class definitions. For example, the Java application might include in its classpath a JAR file containing the class definitions of the serialized object, or load the class definitions using information from the directory, as explained below. 2.2.1 Representation in the Directory A serialized object is represented in the directory by the attributes javaClassName, javaClassNames, javaCodebase, and javaSerializedData, as defined in Section 3. The mandatory attribute, javaSerializedData, contains the serialized form of the object. Although the serialized form already contains the class name, the mandatory javaClassName attribute also records the class name of the serialized object so that applications can determined class information without having to first deserialize the object. The optional javaClassNames attribute is used to record additional class information about the serialized object. The optional javaCodebase attribute is used to record the locations of the class definitions needed to deserialize the serialized object. A directory entry that contains a serialized object is represented by the object class javaSerializedObject, which is a subclass of javaObject. javaSerializedObject is an auxiliary object class, which means that it needs to be mixed in with a structural object class. javaSerializedObject's definition is given in Section 4. 2.3 Marshalled Objects To "marshal" an object means to record its state and codebase(s) in such a way that when the marshalled object is "unmarshalled," a copy of the original object is obtained, possibly by automatically loading the class definitions of the object. You can marshal any object that is serializable or remote (that is, implements the java.rmi.Remote interface). Marshalling is like serialization, except marshalling also records codebases. Marshalling is different from serialization in that marshalling treats remote objects specially. If an object is a java.rmi.Remote object, marshalling records the remote object's "stub" (see Section 2.5), instead of the remote object itself. Like serialization, when an object is marshalled, the entire tree of objects rooted at the object is marshalled. When it is unmarshalled, the tree is reconstructed. Ryan, et al. Informational [Page 4] RFC 2713 Schema for Java Objects October 1999 A "marshalled" object is the represented by the java.rmi.MarshalledObject class. Here's an example of how to create MarshalledObjects for serializable and remote objects: java.io.Serializable sobj = ...; java.rmi.MarshalledObject mobj1 = new java.rmi.MarshalledObject(sobj); java.rmi.Remote robj = ...; java.rmi.MarshalledObject mobj2 = new java.rmi.MarshalledObject(robj); Then, to retrieve the original objects from the MarshalledObjects, do as follows: java.io.Serializable sobj = (java.io.Serializable) mobj1.get(); java.io.Remote rstub = (java.io.Remote) mobj2.get(); MarshalledObject is available only on the Java 2 Platform, Standard Edition, v1.2, and higher releases. 2.3.1 Representation in the Directory A marshalled object is represented in the directory by the attributes javaClassName, javaClassNames, and javaSerializedData, as defined in Section 3. The mandatory attribute, javaSerializedData, contains the serialized form of the marshalled object (that is, the serialized form of a MarshalledObject instance). The mandatory javaClassName attribute records the distinguished class name of the object before it has been marshalled. The optional javaClassNames attribute is used to record additional class information about the object before it has been marshalled. A directory entry that contains a marshalled object is represented by the object class javaMarshalledObject, which is a subclass of javaObject. javaMarshalledObject is an auxiliary object class, which means that it needs to be mixed in with a structural object class. javaMarshalledObject's definition is given in Section 4. As evident in this description, a javaMarshalledObject differs from a javaSerializedObject only in the interpretation of the javaClassName and javaClassNames attributes. Ryan, et al. Informational [Page 5] RFC 2713 Schema for Java Objects October 1999 2.4 JNDI References Java Naming and Directory Interface(tm) (JNDI) is a directory access API specified in the Java programming language [JNDI]. It provides an object-oriented view of the directory, allowing Java objects to be added to and retrieved from the directory without requiring the client to manage data representation issues. JNDI defines the notion of a "reference" for use when an object cannot be stored in the directory directly, or when it is inappropriate or undesirable to do so. An object with an associated reference is stored in the directory indirectly, by storing its reference instead. 2.4.1 Contents of a Reference A JNDI reference is a Java object of class javax.naming.Reference. It consists of class information about the object being referenced and an ordered list of addresses. An address is a Java object of class javax.naming.RefAddr. Each address contains information on how to construct the object. A common use for JNDI references is to represent connections to a network service such as a database, directory, or file system. Each address may then identify a "communications endpoint" for that service, containing information on how to contact the service. Multiple addresses may arise for various reasons, such as replication or the object offering interfaces over more than one communication mechanism. A reference also contains information to assist in the creation of an instance of the object to which the reference refers. It contains the Java class name of that object, and the class name and location of the object factory to be used to create the object. The procedures for creating an object given its reference and the reverse are described in [JNDI]. 2.4.2 Representation in the Directory A JNDI reference is stored in the directory by using the attributes javaClassName, javaClassNames, javaCodebase, javaReferenceAddress, and javaFactory, defined in Section 3. These attributes store information corresponding to the contents of a reference described above. javaReferenceAddress is a multivalued optional attribute for storing reference addresses. javaFactory is the optional attribute for storing the object factory's fully qualified class name. The mandatory javaClassName attribute is used to store the name of the distinguished class of the object. The optional javaClassNames Ryan, et al. Informational [Page 6] RFC 2713 Schema for Java Objects October 1999 attribute is used to record additional class and interface names. The optional javaCodebase attribute is used to store the locations of the object factory's and the object's class definitions. A directory entry containing a JNDI reference is represented by the object class javaNamingReference, which is a subclass of javaObject. javaNamingReference is an auxiliary object class, which means that it needs to be mixed in with a structural object class. javaNamingReference's definition is given in Section 4. 2.5 Remote Objects The Java Remote Method Invocation (RMI) system [RMI] is a mechanism that enables an object on one Java virtual machine to invoke methods on an object in another Java virtual machine. Any object whose methods can be invoked in this way must implement the java.rmi.Remote interface. When such an object is invoked, its arguments are marshalled and sent from the local virtual machine to the remote one, where the arguments are unmarshalled and used. When the method terminates, the results are marshalled from the remote machine and sent to the caller's virtual machine. To make a remote object accessible to other virtual machines, a program typically registers it with the RMI registry. The program supplies to the RMI registry the string name of the remote object and the remote object itself. When a program wants to access a remote object, it supplies the object's string name to the RMI registry on the same machine as the remote object. The RMI registry returns to the caller a reference (called "stub") to the remote object. When the program receives the stub for the remote object, it can invoke methods on the remote object (through the stub). A program can also obtain references to remote objects as a result of remote calls to other remote objects or from other naming services. For example, the program can look up a reference to a remote object from an LDAP server that supports the schema defined in this document. The string name accepted by the RMI registry has the syntax "rmi://hostname:port/remoteObjectName", where "hostname" and "port" identify the machine and port on which the RMI registry is running, respectively, and "remoteObjectName" is the string name of the remote object. "hostname", "port", and the prefix, "rmi:", are optional. If "hostname" is not specified, it defaults to the local host. If "port" is not specified, it defaults to 1099. If "remoteObjectName" is not specified, then the object being named is the RMI registry itself. See [RMI] for details. Ryan, et al. Informational [Page 7] RFC 2713 Schema for Java Objects October 1999 RMI can be supported using different protocols: the Java Remote Method Protocol (JRMP) and the Internet Inter-ORB Protocol (IIOP). The JRMP is a specialized protocol designed for RMI; the IIOP is the standard protocol for communication between CORBA objects [CORBA]. RMI over IIOP allows Java remote objects to communicate with CORBA objects which might be written in a non-Java programming language [RMI-IIOP]. 2.5.1 Representation in the Directory Remote objects that use the IIOP are represented in the directory as CORBA object references [CORBA-LDAP]. Remote objects that use the JRMP are represented in the directory in one of two ways: as a marshalled object, or as a JNDI reference. A marshalled object records the codebases of the remote object's stub and any serializable or remote objects that it references, and replaces remote objects with their stubs. To store a Remote object as a marshalled object (java.rmi.MarshalledObject), you first create a java.rmi.MarshalledObject instance for it. java.rmi.Remote robj = ...; java.rmi.MarshalledObject mobj = new java.rmi.MarshalledObject(robj); You can then store the MarshalledObject instance as a javaMarshalledObject. The javaClassName attribute should contain the fully qualified name of the distinguished class of the remote object. The javaClassNames attribute should contain the names of the classes and interfaces of the remote object. To read the remote object back from the directory, first deserialize the contents of the javaSerializedData to get a MarshalledObject (mobj), then retrieve it from the MarshalledObject as follows: java.rmi.Remote robj = (java.rmi.Remote)mobj.get(); This returns the remote stub, which you can then use to invoke remote methods. MarshalledObject is available only on the Java 2 Platform, Standard Edition, v1.2 and higher releases. Therefore, a remote object stored as a MarshalledObject can only be read by clients using the the Java 2 Platform, Standard Edition, v1.2 or higher releases. Ryan, et al. Informational [Page 8] RFC 2713 Schema for Java Objects October 1999 To store a remote object as a JNDI reference, you first create a javax.naming.Reference object instance for it using the remote object's string name as it has been, or will be, recorded with the RMI registry, with the additional restriction that the "rmi:" prefix must be present. Here's an example: javax.naming.Reference ref = new javax.naming.Reference( obj.getClass().getName(), new javax.naming.StringRefAddr("URL", "rmi://rserver/AppRemoteObjectX")); You then store the javax.naming.Reference instance as a javaNamingReference. The advantage of using a JNDI reference is that this can be done without a reference to the remote object. In fact, the remote object does not have to exist at the time that this recording in the directory is made. The remote object needs to exist and be bound with the RMI registry when the object is looked up from the directory. 2.6 Serialized Objects Vs. Marshalled Objects Vs. References The object classes defined in this document store different aspects of the Java objects. A javaSerializedObject or a serializable object stored as a javaMarshalledObject represents the object itself, while a javaNamingReference or a remote object stored as a javaMarshalledObject represents a "pointer" to the object. When storing a serializable object in the directory, you have a choice of storing it as a javaSerializedObject or a javaMarshalledObject. The javaSerializedObject object class provides the basic way in which to store serializable objects. When you create an LDAP entry using the javaSerializableObject object class, you must explicitly set the javaCodebase attribute if you want readers of that entry to know where to load the class definitions of the object. When you create an LDAP entry using the javaMarshalledObject object class, you use the MarshalledObject class. The MarshalledObject class uses the RMI infrastructure available on the Java platform to automate how codebase information is gathered and recorded, thus freeing you from having to set the javaCodebase attribute. On the other hand, the javaCodebase attribute is human-readable and can be updated easily by using text-based tools without having to change other parts of the entry. This allows you, for instance, to move the class definitions to another location and then update the javaCodebase attribute to reflect the move without having to update the serialized object itself. Ryan, et al. Informational [Page 9] RFC 2713 Schema for Java Objects October 1999 A javaNamingReference provides a way of recording address information about an object which itself is not directly stored in the directory. A remote object stored as a javaMarshalledObject also records address information (the object's "stub") of an object which itself is not directory stored in the directory. In other words, you can think of these as compact representations of the information required to access the object. A javaNamingReference typically consists of a small number of human- readable strings. Standard text-based tools for directory administration may therefore be used to add, read, or modify reference entries -- if so desired -- quite easily. Serialized and marshalled objects are not intended to be read or manipulated directly by humans. 3 Attribute Type Definitions The following attribute types are defined in this document: javaClassName javaClassNames javaCodebase javaSerializedData javaFactory javaReferenceAddress javaDoc 3.1 javaClassName This attribute stores the fully qualified name of the Java object's "distinguished" class or interface (for example, "java.lang.String"). It is a single-valued attribute. This attribute's syntax is ' Directory String' and its case is significant. ( 1.3.6.1.4.1.42.2.27.4.1.6 NAME 'javaClassName' DESC 'Fully qualified name of distinguished Java class or interface' EQUALITY caseExactMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) Ryan, et al. Informational [Page 10] RFC 2713 Schema for Java Objects October 1999 3.2 javaCodebase This attribute stores the Java class definition's locations. It specifies the locations from which to load the class definition for the class specified by the javaClassName attribute. Each value of the attribute contains an ordered list of URLs, separated by spaces. For example, a value of "url1 url2 url3" means that the three (possibly interdependent) URLs (url1, url2, and url3) form the codebase for loading in the Java class definition. If the javaCodebase attribute contains more than one value, each value is an independent codebase. That is, there is no relationship between the URLs in one value and those in another; each value can be viewed as an alternate source for loading the Java class definition. See [Java] for information regarding class loading. This attribute's syntax is 'IA5 String' and its case is significant. ( 1.3.6.1.4.1.42.2.27.4.1.7 NAME 'javaCodebase' DESC 'URL(s) specifying the location of class definition' EQUALITY caseExactIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) 3.3 javaClassNames This attribute stores the Java object's fully qualified class or interface names (for example, "java.lang.String"). It is a multivalued attribute. When more than one value is present, each is the name of a class or interface, or ancestor class or interface, of this object. This attribute's syntax is 'Directory String' and its case is significant. ( 1.3.6.1.4.1.42.2.27.4.1.13 NAME 'javaClassNames' DESC 'Fully qualified Java class or interface name' EQUALITY caseExactMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) Ryan, et al. Informational [Page 11] RFC 2713 Schema for Java Objects October 1999 3.4 javaSerializedData This attribute stores the serialized form of a Java object. The serialized form is described in [Serial]. This attribute's syntax is 'Octet String'. ( 1.3.6.1.4.1.42.2.27.4.1.8 NAME 'javaSerializedData DESC 'Serialized form of a Java object' SYNTAX 1.3.6.1.4.1.1466.115.121.1.40 SINGLE-VALUE ) 3.5 javaFactory This attribute stores the fully qualified class name of the object factory (for example, "com.wiz.jndi.WizObjectFactory") that can be used to create an instance of the object identified by the javaClassName attribute. This attribute's syntax is 'Directory String' and its case is significant. ( 1.3.6.1.4.1.42.2.27.4.1.10 NAME 'javaFactory' DESC 'Fully qualified Java class name of a JNDI object factory' EQUALITY caseExactMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) 3.6 javaReferenceAddress This attribute represents the sequence of addresses of a JNDI reference. Each of its values represents one address, a Java object of type javax.naming.RefAddr. Its value is a concatenation of the address type and address contents, preceded by a sequence number (the order of addresses in a JNDI reference is significant). For example: #0#TypeA#ValA #1#TypeB#ValB #2#TypeC##rO0ABXNyABpq... In more detail, the value is encoded as follows: Ryan, et al. Informational [Page 12] RFC 2713 Schema for Java Objects October 1999 The delimiter is the first character of the value. For readability the character '#' is recommended when it is not otherwise used anywhere in the value, but any character may be used subject to restrictions given below. The first delimiter is followed by the sequence number. The sequence number of an address is its position in the JNDI reference, with the first address being numbered 0. It is represented by its shortest string form, in decimal notation. The sequence number is followed by a delimiter, then by the address type, and then by another delimiter. If the address is of Java class javax.naming.StringRefAddr, then this delimiter is followed by the value of the address contents (which is a string). Otherwise, this delimiter is followed immediately by another delimiter, and then by the Base64 encoding of the serialized form of the entire address. The delimiter may be any character other than a digit or a character contained in the address type. In addition, if the address contents is a string, the delimiter may not be the first character of that string. This attribute's syntax is 'Directory String' and its case is significant. It can contain multiple values. ( 1.3.6.1.4.1.42.2.27.4.1.11 NAME 'javaReferenceAddress' DESC 'Addresses associated with a JNDI Reference' EQUALITY caseExactMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) 3.7 javaDoc This attribute stores a pointer to the Java documentation for the class. It's value is a URL. For example, the following URL points to the specification of the java.lang.String class: http://java.sun.com/products/jdk/1.2/docs/api/java/lang/String.html This attribute's syntax is 'IA5 String' and its case is significant. ( 1.3.6.1.4.1.42.2.27.4.1.12 NAME 'javaDoc' DESC 'The Java documentation for the class' EQUALITY caseExactIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) Ryan, et al. Informational [Page 13] RFC 2713 Schema for Java Objects October 1999 4 Object Class Definitions The following object classes are defined in this document: javaContainer javaObject javaSerializedObject javaMarshalledObject javaNamingReference 4.1 javaContainer This structural object class represents a container for a Java object. ( 1.3.6.1.4.1.42.2.27.4.2.1 NAME 'javaContainer' DESC 'Container for a Java object' SUP top STRUCTURAL MUST ( cn ) ) 4.2 javaObject This abstract object class represents a Java object. A javaObject cannot exist in the directory; only auxiliary or structural subclasses of it can exist in the directory. ( 1.3.6.1.4.1.42.2.27.4.2.4 NAME 'javaObject' DESC 'Java object representation' SUP top ABSTRACT MUST ( javaClassName ) MAY ( javaClassNames $ javaCodebase $ javaDoc $ description ) ) Ryan, et al. Informational [Page 14] RFC 2713 Schema for Java Objects October 1999 4.3 javaSerializedObject This auxiliary object class represents a Java serialized object. It must be mixed in with a structural object class. ( 1.3.6.1.4.1.42.2.27.4.2.5 NAME 'javaSerializedObject' DESC 'Java serialized object' SUP javaObject AUXILIARY MUST ( javaSerializedData ) ) 4.4 javaMarshalledObject This auxiliary object class represents a Java marshalled object. It must be mixed in with a structural object class. ( 1.3.6.1.4.1.42.2.27.4.2.8 NAME 'javaMarshalledObject' DESC 'Java marshalled object' SUP javaObject AUXILIARY MUST ( javaSerializedData ) ) 4.5 javaNamingReference This auxiliary object class represents a JNDI reference. It must be mixed in with a structural object class. ( 1.3.6.1.4.1.42.2.27.4.2.7 NAME 'javaNamingReference' DESC 'JNDI reference' SUP javaObject AUXILIARY MAY ( javaReferenceAddress $ javaFactory ) ) Ryan, et al. Informational [Page 15] RFC 2713 Schema for Java Objects October 1999 5. Security Considerations Serializing an object and storing it into the directory enables (a copy of) the object to be examined and used outside the environment in which it was originally created. The directory entry containing the serialized object could be read and modified within the constraints imposed by the access control mechanisms of the directory. If an object contains sensitive information or information that could be misused outside of the context in which it was created, the object should not be stored in the directory. For more details on security issues relating to serialization in general, see [Serial]. 6. Acknowledgements We would like to thank Joseph Fialli, Peter Jones, Roger Riggs, Bob Scheifler, and Ann Wollrath of Sun Microsystems for their comments and suggestions. 7. References [CORBA] The Object Management Group, "Common Object Request Broker Architecture Specification 2.0," http://www.omg.org [CORBA-LDAP] Ryan, V., Lee, R. and S. Seligman, "Schema for Representing CORBA Object References in an LDAP Directory", RFC 2714, October 1999. [Java] Ken Arnold and James Gosling, "The Java(tm) Programming Language," Second Edition, ISBN 0-201-31006-6. [JNDI] Java Software, Sun Microsystems, Inc., "The Java(tm) Naming and Directory Interface (tm) Specification," February 1998. http://java.sun.com/products/jndi/ [LDAPv3] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [RMI] Java Software, Sun Microsystems, Inc., "Remote Method Invocation," November 1998. http://java.sun.com/products/jdk/1.2/docs/guide/rmi Ryan, et al. Informational [Page 16] RFC 2713 Schema for Java Objects October 1999 [RMI-IIOP] IBM and Java Software, Sun Microsystems, Inc., "RMI over IIOP", June 1999. http://java.sun.com/products/rmi-iiop/ [Serial] Java Software, Sun Microsystems, Inc., "Object Serialization Specification," November 1998. http://java.sun.com/products/jdk/1.2/docs/guide/ serialization [v3Schema] Wahl, M., "A Summary of the X.500(96) User Schema for use with LDAPv3", RFC 2256, December 1997. 8. Authors' Addresses Vincent Ryan Sun Microsystems, Inc. Mail Stop EDUB03 901 San Antonio Road Palo Alto, CA 94303 USA Phone: +353 1 819 9151 EMail: vincent.ryan@ireland.sun.com Scott Seligman Sun Microsystems, Inc. Mail Stop UCUP02-209 901 San Antonio Road Palo Alto, CA 94303 USA Phone: +1 408 863 3222 EMail: scott.seligman@eng.sun.com Rosanna Lee Sun Microsystems, Inc. Mail Stop UCUP02-206 901 San Antonio Road Palo Alto, CA 94303 USA Phone: +1 408 863 3221 EMail: rosanna.lee@eng.sun.com Ryan, et al. Informational [Page 17] RFC 2713 Schema for Java Objects October 1999 Appendix - LDAP Schema -- Attribute types -- ( 1.3.6.1.4.1.42.2.27.4.1.6 NAME 'javaClassName' DESC 'Fully qualified name of distinguished Java class or interface' EQUALITY caseExactMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) ( 1.3.6.1.4.1.42.2.27.4.1.7 NAME 'javaCodebase' DESC 'URL(s) specifying the location of class definition' EQUALITY caseExactIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) ( 1.3.6.1.4.1.42.2.27.4.1.8 NAME 'javaSerializedData' DESC 'Serialized form of a Java object' SYNTAX 1.3.6.1.4.1.1466.115.121.1.40 SINGLE-VALUE ) ( 1.3.6.1.4.1.42.2.27.4.1.10 NAME 'javaFactory' DESC 'Fully qualified Java class name of a JNDI object factory' EQUALITY caseExactMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) ( 1.3.6.1.4.1.42.2.27.4.1.11 NAME 'javaReferenceAddress' DESC 'Addresses associated with a JNDI Reference' EQUALITY caseExactMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) ( 1.3.6.1.4.1.42.2.27.4.1.12 NAME 'javaDoc' DESC 'The Java documentation for the class' EQUALITY caseExactIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) Ryan, et al. Informational [Page 18] RFC 2713 Schema for Java Objects October 1999 ( 1.3.6.1.4.1.42.2.27.4.1.13 NAME 'javaClassNames' DESC 'Fully qualified Java class or interface name' EQUALITY caseExactMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) -- from RFC-2256 -- ( 2.5.4.13 NAME 'description' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{1024} ) -- Object classes -- ( 1.3.6.1.4.1.42.2.27.4.2.1 NAME 'javaContainer' DESC 'Container for a Java object' SUP top STRUCTURAL MUST ( cn ) ) ( 1.3.6.1.4.1.42.2.27.4.2.4 NAME 'javaObject' DESC 'Java object representation' SUP top ABSTRACT MUST ( javaClassName ) MAY ( javaClassNames $ javaCodebase $ javaDoc $ description ) ) ( 1.3.6.1.4.1.42.2.27.4.2.5 NAME 'javaSerializedObject' DESC 'Java serialized object' SUP javaObject AUXILIARY MUST ( javaSerializedData ) ) Ryan, et al. Informational [Page 19] RFC 2713 Schema for Java Objects October 1999 ( 1.3.6.1.4.1.42.2.27.4.2.7 NAME 'javaNamingReference' DESC 'JNDI reference' SUP javaObject AUXILIARY MAY ( javaReferenceAddress $ javaFactory ) ) ( 1.3.6.1.4.1.42.2.27.4.2.8 NAME 'javaMarshalledObject' DESC 'Java marshalled object' SUP javaObject AUXILIARY MUST ( javaSerializedData ) ) -- Matching rule from ISO X.520 -- ( 2.5.13.5 NAME 'caseExactMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) Ryan, et al. Informational [Page 20] RFC 2713 Schema for Java Objects October 1999 Full Copyright Statement Copyright (C) The Internet Society (1999). 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. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Ryan, et al. Informational [Page 21] PK .�c\��� � ( doc/alt-openldap11-devel/rfc/rfc4521.txtnu �[��� Network Working Group K. Zeilenga Request for Comments: 4521 OpenLDAP Foundation BCP: 118 June 2006 Category: Best Current Practice Considerations for Lightweight Directory Access Protocol (LDAP) Extensions Status of This Memo This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2006). Abstract The Lightweight Directory Access Protocol (LDAP) is extensible. It provides mechanisms for adding new operations, extending existing operations, and expanding user and system schemas. This document discusses considerations for designers of LDAP extensions. Zeilenga Best Current Practice [Page 1] RFC 4521 LDAP Extensions June 2006 Table of Contents 1. Introduction ....................................................3 1.1. Terminology ................................................3 2. General Considerations ..........................................4 2.1. Scope of Extension .........................................4 2.2. Interaction between extensions .............................4 2.3. Discovery Mechanism ........................................4 2.4. Internationalization Considerations ........................5 2.5. Use of the Basic Encoding Rules ............................5 2.6. Use of Formal Languages ....................................5 2.7. Examples ...................................................5 2.8. Registration of Protocol Values ............................5 3. LDAP Operation Extensions .......................................6 3.1. Controls ...................................................6 3.1.1. Extending Bind Operation with Controls ..............6 3.1.2. Extending the Start TLS Operation with Controls .....7 3.1.3. Extending the Search Operation with Controls ........7 3.1.4. Extending the Update Operations with Controls .......8 3.1.5. Extending the Responseless Operations with Controls..8 3.2. Extended Operations ........................................8 3.3. Intermediate Responses .....................................8 3.4. Unsolicited Notifications ..................................9 4. Extending the LDAP ASN.1 Definition .............................9 4.1. Result Codes ...............................................9 4.2. LDAP Message Types .........................................9 4.3. Authentication Methods ....................................10 4.4. General ASN.1 Extensibility ...............................10 5. Schema Extensions ..............................................10 5.1. LDAP Syntaxes .............................................11 5.2. Matching Rules ............................................11 5.3. Attribute Types ...........................................12 5.4. Object Classes ............................................12 6. Other Extension Mechanisms .....................................12 6.1. Attribute Description Options .............................12 6.2. Authorization Identities ..................................12 6.3. LDAP URL Extensions .......................................12 7. Security Considerations ........................................12 8. Acknowledgements ...............................................13 9. References .....................................................13 9.1. Normative References ......................................13 9.2. Informative References ....................................15 Zeilenga Best Current Practice [Page 2] RFC 4521 LDAP Extensions June 2006 1. Introduction The Lightweight Directory Access Protocol (LDAP) [RFC4510] is an extensible protocol. LDAP allows for new operations to be added and for existing operations to be enhanced [RFC4511]. LDAP allows additional schema to be defined [RFC4512][RFC4517]. This can include additional object classes, attribute types, matching rules, additional syntaxes, and other elements of schema. LDAP provides an ability to extend attribute types with options [RFC4512]. LDAP supports a Simple Authentication and Security Layer (SASL) authentication method [RFC4511][RFC4513]. SASL [RFC4422] is extensible. LDAP may be extended to support additional authentication methods [RFC4511]. LDAP supports establishment of Transport Layer Security (TLS) [RFC4511][RFC4513]. TLS [RFC4346] is extensible. LDAP has an extensible Uniform Resource Locator (URL) format [RFC4516]. Lastly, LDAP allows for certain extensions to the protocol's Abstract Syntax Notation - One (ASN.1) [X.680] definition to be made. This facilitates a wide range of protocol enhancements, for example, new result codes needed to support extensions to be added through extension of the protocol's ASN.1 definition. This document describes practices that engineers should consider when designing extensions to LDAP. 1.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 [RFC2119]. In this document, "the specification", as used by BCP 14, RFC 2119, refers to the engineering of LDAP extensions. The term "Request Control" refers to a control attached to a client- generated message sent to a server. The term "Response Control" refers to a control attached to a server-generated message sent to a client. Zeilenga Best Current Practice [Page 3] RFC 4521 LDAP Extensions June 2006 DIT stands for Directory Information Tree. DSA stands for Directory System Agent, a server. DSE stands for DSA-Specific Entry. DUA stands for Directory User Agent, a client. DN stands for Distinguished Name. 2. General Considerations 2.1. Scope of Extension Mutually agreeing peers may, within the confines of an extension, agree to significant changes in protocol semantics. However, designers MUST consider the impact of an extension upon protocol peers that have not agreed to implement or otherwise recognize and support the extension. Extensions MUST be "truly optional" [RFC2119]. 2.2. Interaction between extensions Designers SHOULD consider how extensions they engineer interact with other extensions. Designers SHOULD consider the extensibility of extensions they specify. Extensions to LDAP SHOULD themselves be extensible. Except where it is stated otherwise, extensibility is implied. 2.3. Discovery Mechanism Extensions SHOULD provide adequate discovery mechanisms. As LDAP design is based upon the client-request/server-response paradigm, the general discovery approach is for the client to discover the capabilities of the server before utilizing a particular extension. Commonly, this discovery involves querying the root DSE and/or other DSEs for operational information associated with the extension. LDAP provides no mechanism for a server to discover the capabilities of a client. The 'supportedControl' attribute [RFC4512] is used to advertise supported controls. The 'supportedExtension' attribute [RFC4512] is used to advertise supported extended operations. The 'supportedFeatures' attribute [RFC4512] is used to advertise features. Other root DSE attributes MAY be defined to advertise other capabilities. Zeilenga Best Current Practice [Page 4] RFC 4521 LDAP Extensions June 2006 2.4. Internationalization Considerations LDAP is designed to support the full Unicode [Unicode] repertory of characters. Extensions SHOULD avoid unnecessarily restricting applications to subsets of Unicode (e.g., Basic Multilingual Plane, ISO 8859-1, ASCII, Printable String). LDAP Language Tag options [RFC3866] provide a mechanism for tagging text (and other) values with language information. Extensions that define attribute types SHOULD allow use of language tags with these attributes. 2.5. Use of the Basic Encoding Rules Numerous elements of LDAP are described using ASN.1 [X.680] and are encoded using a particular subset [Protocol, Section 5.2] of the Basic Encoding Rules (BER) [X.690]. To allow reuse of parsers/generators used in implementing the LDAP "core" technical specification [RFC4510], it is RECOMMENDED that extension elements (e.g., extension specific contents of controlValue, requestValue, responseValue fields) described by ASN.1 and encoded using BER be subjected to the restrictions of [Protocol, Section 5.2]. 2.6. Use of Formal Languages Formal languages SHOULD be used in specifications in accordance with IESG guidelines [FORMAL]. 2.7. Examples Example DN strings SHOULD conform to the syntax defined in [RFC4518]. Example LDAP filter strings SHOULD conform to the syntax defined in [RFC4515]. Example LDAP URLs SHOULD conform to the syntax defined in [RFC4516]. Entries SHOULD be represented using LDIF [RFC2849]. 2.8. Registration of Protocol Values Designers SHALL register protocol values of their LDAP extensions in accordance with BCP 64, RFC 4520 [RFC4520]. Specifications that create new extensible protocol elements SHALL extend existing registries or establish new registries for values of these elements in accordance with BCP 64, RFC 4520 [RFC4520] and BCP 26, RFC 2434 [RFC2434]. Zeilenga Best Current Practice [Page 5] RFC 4521 LDAP Extensions June 2006 3. LDAP Operation Extensions Extensions SHOULD use controls in defining extensions that complement existing operations. Where the extension to be defined does not complement an existing operation, designers SHOULD consider defining an extended operation instead. For example, a subtree delete operation could be designed as either an extension of the delete operation or as a new operation. As the feature complements the existing delete operation, use of the control mechanism to extend the delete operation is likely more appropriate. As a counter (and contrived) example, a locate services operation (an operation that would return for a DN a set of LDAP URLs to services that may hold the entry named by this DN) could be designed as either a search operation or a new operation. As the feature doesn't complement the search operation (e.g., the operation is not contrived to search for entries held in the Directory Information Tree), it is likely more appropriate to define a new operation using the extended operation mechanism. 3.1. Controls Controls [Protocol, Section 4.1.11] are the RECOMMENDED mechanism for extending existing operations. The existing operation can be a base operation defined in [RFC4511] (e.g., search, modify) , an extended operation (e.g., Start TLS [RFC4511], Password Modify [RFC3062]), or an operation defined as an extension to a base or extended operation. Extensions SHOULD NOT return Response controls unless the server has specific knowledge that the client can make use of the control. Generally, the client requests the return of a particular response control by providing a related request control. An existing operation MAY be extended to return IntermediateResponse messages [Protocol, Section 4.13]. Specifications of controls SHALL NOT attach additional semantics to the criticality of controls beyond those defined in [Protocol, Section 4.1.11]. A specification MAY mandate the criticality take on a particular value (e.g., TRUE or FALSE), where appropriate. 3.1.1. Extending Bind Operation with Controls Controls attached to the request and response messages of a Bind Operation [RFC4511] are not protected by any security layers established by that Bind operation. Zeilenga Best Current Practice [Page 6] RFC 4521 LDAP Extensions June 2006 Specifications detailing controls extending the Bind operation SHALL detail that the Bind negotiated security layers do not protect the information contained in these controls and SHALL detail how the information in these controls is protected or why the information does not need protection. It is RECOMMENDED that designers consider alternative mechanisms for providing the function. For example, an extended operation issued subsequent to the Bind operation (hence, protected by the security layers negotiated by the Bind operation) might be used to provide the desired function. Additionally, designers of Bind control extensions MUST also consider how the controls' semantics interact with individual steps of a multi-step Bind operation. Note that some steps are optional and thus may require special attention in the design. 3.1.2. Extending the Start TLS Operation with Controls Controls attached to the request and response messages of a Start TLS Operation [RFC4511] are not protected by the security layers established by the Start TLS operation. Specifications detailing controls extending the Start TLS operation SHALL detail that the Start TLS negotiated security layers do not protect the information contained in these controls and SHALL detail how the information in these controls is protected or why the information does not need protection. It is RECOMMENDED that designers consider alternative mechanisms for providing the function. For example, an extended operation issued subsequent to the Start TLS operation (hence, protected by the security layers negotiated by the Start TLS operation) might be used to provided the desired function. 3.1.3. Extending the Search Operation with Controls The Search operation processing has two distinct phases: - finding the base object; and - searching for objects at or under that base object. Specifications of controls extending the Search Operation should clearly state in which phase(s) the control's semantics apply. Semantics of controls that are not specific to the Search Operation SHOULD apply in the finding phase. Zeilenga Best Current Practice [Page 7] RFC 4521 LDAP Extensions June 2006 3.1.4. Extending the Update Operations with Controls Update operations have properties of atomicity, consistency, isolation, and durability ([ACID]). - atomicity: All or none of the DIT changes requested are made. - consistency: The resulting DIT state must be conform to schema and other constraints. - isolation: Intermediate states are not exposed. - durability: The resulting DIT state is preserved until subsequently updated. When defining a control that requests additional (or other) DIT changes be made to the DIT, these additional changes SHOULD NOT be treated as part of a separate transaction. The specification MUST be clear as to whether the additional DIT changes are part of the same or a separate transaction as the DIT changes expressed in the request of the base operation. When defining a control that requests additional (or other) DIT changes be made to the DIT, the specification MUST be clear as to the order in which these and the base changes are to be applied to the DIT. 3.1.5. Extending the Responseless Operations with Controls The Abandon and Unbind operations do not include a response message. For this reason, specifications for controls designed to be attached to Abandon and Unbind requests SHOULD mandate that the control's criticality be FALSE. 3.2. Extended Operations Extended Operations [Protocol, Section 4.12] are the RECOMMENDED mechanism for defining new operations. An extended operation consists of an ExtendedRequest message, zero or more IntermediateResponse messages, and an ExtendedResponse message. 3.3. Intermediate Responses Extensions SHALL use IntermediateResponse messages instead of ExtendedResponse messages to return intermediate results. Zeilenga Best Current Practice [Page 8] RFC 4521 LDAP Extensions June 2006 3.4. Unsolicited Notifications Unsolicited notifications [Protocol, Section 4.4] offer a capability for the server to notify the client of events not associated with the operation currently being processed. Extensions SHOULD be designed such that unsolicited notifications are not returned unless the server has specific knowledge that the client can make use of the notification. Generally, the client requests the return of a particular unsolicited notification by performing a related extended operation. For example, a time hack extension could be designed to return unsolicited notifications at regular intervals that were enabled by an extended operation (which possibly specified the desired interval). 4. Extending the LDAP ASN.1 Definition LDAP allows limited extension [Protocol, Section 4] of the LDAP ASN.1 definition [Protocol, Appendix B] to be made. 4.1. Result Codes Extensions that specify new operations or enhance existing operations often need to define new result codes. The extension SHOULD be designed such that a client has a reasonably clear indication of the nature of the successful or non-successful result. Extensions SHOULD use existing result codes to indicate conditions that are consistent with the intended meaning [RFC4511][X.511] of these codes. Extensions MAY introduce new result codes [RFC4520] where no existing result code provides an adequate indication of the nature of the result. Extensions SHALL NOT disallow or otherwise restrict the return of general service result codes, especially those reporting a protocol, service, or security problem, or indicating that the server is unable or unwilling to complete the operation. 4.2. LDAP Message Types While extensions can specify new types of LDAP messages by extending the protocolOp CHOICE of the LDAPMessage SEQUENCE, this is generally unnecessary and inappropriate. Existing operation extension mechanisms (e.g., extended operations, unsolicited notifications, and intermediate responses) SHOULD be used instead. However, there may be cases where an extension does not fit well into these mechanisms. Zeilenga Best Current Practice [Page 9] RFC 4521 LDAP Extensions June 2006 In such cases, a new extension mechanism SHOULD be defined that can be used by multiple extensions that have similar needs. 4.3. Authentication Methods The Bind operation currently supports two authentication methods, simple and SASL. SASL [RFC4422] is an extensible authentication framework used by multiple application-level protocols (e.g., BEEP, IMAP, SMTP). It is RECOMMENDED that new authentication processes be defined as SASL mechanisms. New LDAP authentication methods MAY be added to support new authentication frameworks. The Bind operation's primary function is to establish the LDAP association [RFC4513]. No other operation SHALL be defined (or extended) to establish the LDAP association. However, other operations MAY be defined to establish other security associations (e.g., IPsec). 4.4. General ASN.1 Extensibility Section 4 of [RFC4511] states the following: In order to support future extensions to this protocol, extensibility is implied where it is allowed per ASN.1 (i.e., sequence, set, choice, and enumerated types are extensible). In addition, ellipses (...) have been supplied in ASN.1 types that are explicitly extensible as discussed in [RFC4520]. Because of the implied extensibility, clients and servers MUST (unless otherwise specified) ignore trailing SEQUENCE components whose tags they do not recognize. Designers SHOULD avoid introducing extensions that rely on unsuspecting implementations to ignore trailing components of SEQUENCE whose tags they do not recognize. 5. Schema Extensions Extensions defining LDAP schema elements SHALL provide schema definitions conforming with syntaxes defined in [Models, Section 4.1]. While provided definitions MAY be reformatted (line wrapped) for readability, this SHALL be noted in the specification. For definitions that allow a NAME field, new schema elements SHOULD provide one and only one name. The name SHOULD be short. Each schema definition allows a DESC field. The DESC field, if provided, SHOULD contain a short descriptive phrase. The DESC field MUST be regarded as informational. That is, the specification MUST Zeilenga Best Current Practice [Page 10] RFC 4521 LDAP Extensions June 2006 be written such that its interpretation is the same with and without the provided DESC fields. The extension SHALL NOT mandate that implementations provide the same DESC field in the schema they publish. Implementors MAY replace or remove the DESC field. Published schema elements SHALL NOT be redefined. Replacement schema elements (new OIDs, new NAMEs) SHOULD be defined as needed. Schema designers SHOULD reuse existing schema elements, where appropriate. However, any reuse MUST not alter the semantics of the element. 5.1. LDAP Syntaxes Each LDAP syntax [RFC4517] is defined in terms of ASN.1 [X.680]. Each extension detailing an LDAP syntax MUST specify the ASN.1 data definition associated with the syntax. A distinct LDAP syntax SHOULD be created for each distinct ASN.1 data definition (including constraints). Each LDAP syntax SHOULD have a string encoding defined for it. It is RECOMMENDED that this string encoding be restricted to UTF-8 [RFC3629] encoded Unicode [Unicode] characters. Use of Generic String Encoding Rules (GSER) [RFC3641][RFC3642] or other generic string encoding rules to provide string encodings for complex ASN.1 data definitions is RECOMMENDED. Otherwise, it is RECOMMENDED that the string encoding be described using a formal language (e.g., ABNF [RFC4234]). Formal languages SHOULD be used in specifications in accordance with IESG guidelines [FORMAL]. If no string encoding is defined, the extension SHALL specify how the transfer encoding is to be indicated. Generally, the extension SHOULD mandate use of binary or other transfer encoding option. 5.2. Matching Rules Three basic kinds of matching rules (e.g., EQUALITY, ORDERING, and SUBSTRING) may be associated with an attribute type. In addition, LDAP provides an extensible matching rule mechanism. The matching rule specification SHOULD detail which kind of matching rule it is and SHOULD describe which kinds of values it can be used with. In addition to requirements stated in the LDAP technical specification, equality matching rules SHOULD be commutative. Zeilenga Best Current Practice [Page 11] RFC 4521 LDAP Extensions June 2006 5.3. Attribute Types Designers SHOULD carefully consider how the structure of values is to be restricted. Designers SHOULD consider that servers will only enforce constraints of the attribute's syntax. That is, an attribute intended to hold URIs, but that has directoryString syntax, is not restricted to values that are URIs. Designers SHOULD carefully consider which matching rules, if any, are appropriate for the attribute type. Matching rules specified for an attribute type MUST be compatible with the attribute type's syntax. Extensions specifying operational attributes MUST detail how servers are to maintain and/or utilize values of each operational attribute. 5.4. Object Classes Designers SHOULD carefully consider whether each attribute of an object class is required ("MUST") or allowed ("MAY"). Extensions specifying object classes that allow (or require) operational attributes MUST specify how servers are to maintain and/or utilize entries belonging to these object classes. 6. Other Extension Mechanisms 6.1. Attribute Description Options Each option is identified by a string of letters, numbers, and hyphens. This string SHOULD be short. 6.2. Authorization Identities Extensions interacting with authorization identities SHALL support the LDAP authzId format [RFC4513]. The authzId format is extensible. 6.3. LDAP URL Extensions LDAP URL extensions are identified by a short string, a descriptor. Like other descriptors, the string SHOULD be short. 7. Security Considerations LDAP does not place undue restrictions on the kinds of extensions that can be implemented. While this document attempts to outline some specific issues that designers need to consider, it is not (and Zeilenga Best Current Practice [Page 12] RFC 4521 LDAP Extensions June 2006 cannot be) all encompassing. Designers MUST do their own evaluations of the security considerations applicable to their extensions. Designers MUST NOT assume that the LDAP "core" technical specification [RFC4510] adequately addresses the specific concerns surrounding their extensions or assume that their extensions have no specific concerns. Extension specifications, however, SHOULD note whether security considerations specific to the feature they are extending, as well as general LDAP security considerations, apply to the extension. 8. Acknowledgements The author thanks the IETF LDAP community for their thoughtful comments. This work builds upon "LDAP Extension Style Guide" [GUIDE] by Bruce Greenblatt. 9. References 9.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2434] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 2434, October 1998. [RFC2849] Good, G., "The LDAP Data Interchange Format (LDIF) - Technical Specification", RFC 2849, June 2000. [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003. [RFC3641] Legg, S., "Generic String Encoding Rules (GSER) for ASN.1 Types", RFC 3641, October 2003. [RFC3642] Legg, S., "Common Elements of Generic String Encoding Rules (GSER) Encodings", RFC 3642, October 2003. [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006. Zeilenga Best Current Practice [Page 13] RFC 4521 LDAP Extensions June 2006 [RFC3866] Zeilenga, K., Ed., "Language Tags and Ranges in the Lightweight Directory Access Protocol (LDAP)", RFC 3866, July 2004. [RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 4234, October 2005. [RFC4510] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006. [RFC4511] Sermersheim, J., Ed., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006. [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006. [RFC4513] Harrison, R., Ed., "Lightweight Directory Access Protocol (LDAP): Authentication Methods and Security Mechanisms", RFC 4513, June 2006. [RFC4515] Smith, M., Ed. and T. Howes, "Lightweight Directory Access Protocol (LDAP): String Representation of Search Filters", RFC 4515, June 2006. [RFC4516] Smith, M., Ed. and T. Howes, "Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator", RFC 4516, June 2006. [RFC4517] Legg, S., Ed., "Lightweight Directory Access Protocol (LDAP): Syntaxes and Matching Rules", RFC 4517, June 2006. [RFC4518] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): String Representation of Distinguished Names", RFC 4518, June 2006. [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006. [RFC4422] Melnikov, A., Ed. and K. Zeilenga, Ed., "Simple Authentication and Security Layer (SASL)", RFC 4422, June 2006. Zeilenga Best Current Practice [Page 14] RFC 4521 LDAP Extensions June 2006 [Unicode] The Unicode Consortium, "The Unicode Standard, Version 3.2.0" is defined by "The Unicode Standard, Version 3.0" (Reading, MA, Addison-Wesley, 2000. ISBN 0-201-61633-5), as amended by the "Unicode Standard Annex #27: Unicode 3.1" (http://www.unicode.org/reports/tr27/) and by the "Unicode Standard Annex #28: Unicode 3.2" (http://www.unicode.org/reports/tr28/). [FORMAL] IESG, "Guidelines for the use of formal languages in IETF specifications", <http://www.ietf.org/IESG/STATEMENTS/pseudo-code-in- specs.txt>, 2001. [X.511] International Telecommunication Union - Telecommunication Standardization Sector, "The Directory: Abstract Service Definition", X.511(1993) (also ISO/IEC 9594-3:1993). [X.680] International Telecommunication Union - Telecommunication Standardization Sector, "Abstract Syntax Notation One (ASN.1) - Specification of Basic Notation", X.680(2002) (also ISO/IEC 8824-1:2002). [X.690] International Telecommunication Union - Telecommunication Standardization Sector, "Specification of ASN.1 encoding rules: Basic Encoding Rules (BER), Canonical Encoding Rules (CER), and Distinguished Encoding Rules (DER)", X.690(2002) (also ISO/IEC 8825-1:2002). 9.2. Informative References [ACID] Section 4 of ISO/IEC 10026-1:1992. [GUIDE] Greenblatt, B., "LDAP Extension Style Guide", Work in Progress. [RFC3062] Zeilenga, K., "LDAP Password Modify Extended Operation", RFC 3062, February 2001. [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.1", RFC 4346, April 2006. Author's Address Kurt D. Zeilenga OpenLDAP Foundation EMail: Kurt@OpenLDAP.org Zeilenga Best Current Practice [Page 15] RFC 4521 LDAP Extensions June 2006 Full Copyright Statement Copyright (C) The Internet Society (2006). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Zeilenga Best Current Practice [Page 16] PK .�c\h� ��D �D ( doc/alt-openldap11-devel/rfc/rfc3698.txtnu �[��� Network Working Group K. Zeilenga, Ed. Request for Comments: 3698 OpenLDAP Foundation Updates: 2798 February 2004 Category: Standards Track Lightweight Directory Access Protocol (LDAP): Additional Matching Rules Status of this Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2004). All Rights Reserved. Abstract This document provides a collection of matching rules for use with the Lightweight Directory Access Protocol (LDAP). As these matching rules are simple adaptations of matching rules specified for use with the X.500 Directory, most are already in wide use. Table of Contents 1. Background and Intended Use. . . . . . . . . . . . . . . . . . 2 2. Matching Rules . . . . . . . . . . . . . . . . . . . . . . . . 2 2.1. booleanMatch . . . . . . . . . . . . . . . . . . . . . . 2 2.2. caseExactMatch . . . . . . . . . . . . . . . . . . . . . 2 2.3. caseExactOrderingMatch . . . . . . . . . . . . . . . . . 3 2.4. caseExactSubstringsMatch . . . . . . . . . . . . . . . . 3 2.5. caseIgnoreListSubstringsMatch. . . . . . . . . . . . . . 3 2.6. directoryStringFirstComponentMatch . . . . . . . . . . . 4 2.7. integerOrderingMatch . . . . . . . . . . . . . . . . . . 4 2.8. keywordMatch . . . . . . . . . . . . . . . . . . . . . . 4 2.9. numericStringOrderingMatch . . . . . . . . . . . . . . . 5 2.10. octetStringOrderingMatch . . . . . . . . . . . . . . . . 5 2.11. storedPrefixMatch. . . . . . . . . . . . . . . . . . . . 5 2.12. wordMatch. . . . . . . . . . . . . . . . . . . . . . . . 6 3. Security Considerations. . . . . . . . . . . . . . . . . . . . 6 4. IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 6 5. Acknowledgments. . . . . . . . . . . . . . . . . . . . . . . . 7 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Zeilenga Standards Track [Page 1] RFC 3698 LDAP: Additional Matching Rules February 2004 6.1. Normative References . . . . . . . . . . . . . . . . . . 7 6.2. Informative References . . . . . . . . . . . . . . . . . 7 7. Author's Address . . . . . . . . . . . . . . . . . . . . . . . 8 8. Full Copyright Statement . . . . . . . . . . . . . . . . . . . 9 1. Background and Intended Use This document adapts additional X.500 Directory [X.500] matching rules [X.520] for use with the Lightweight Directory Access Protocol (LDAP) [RFC3377]. Most of these rules are widely used today on the Internet, such as in support of the inetOrgPerson [RFC2798] and Policy Core Information Model [RFC3703] LDAP schemas. The rules are applicable to many other applications. This document supersedes the informational matching rules descriptions provided in RFC 2798 that are now provided in this document. Specifically, section 2 of this document replaces section 9.3.3 of RFC 2798. Schema definitions are provided using LDAP description formats [RFC2252]. Definitions provided here are formatted (line wrapped) for readability. 2. Matching Rules 2.1. booleanMatch The booleanMatch rule compares for equality a asserted Boolean value with an attribute value of BOOLEAN syntax. The rule returns TRUE if and only if the values are the same, i.e., both are TRUE or both are FALSE. (Source: X.520) ( 2.5.13.13 NAME 'booleanMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 ) The BOOLEAN (1.3.6.1.4.1.1466.115.121.1.7) syntax is described in [RFC2252]. 2.2. caseExactMatch The caseExactMatch rule compares for equality the asserted value with an attribute value of DirectoryString syntax. The rule is identical to the caseIgnoreMatch [RFC2252] rule except that case is not ignored. (Source: X.520) Zeilenga Standards Track [Page 2] RFC 3698 LDAP: Additional Matching Rules February 2004 ( 2.5.13.5 NAME 'caseExactMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) The DirectoryString (1.3.6.1.4.1.1466.115.121.1.15) syntax is described in [RFC2252]. 2.3. caseExactOrderingMatch The caseExactOrderingMatch rule compares the collation order of the asserted string with an attribute value of DirectoryString syntax. The rule is identical to the caseIgnoreOrderingMatch [RFC2252] rule except that letters are not folded. (Source: X.520) ( 2.5.13.6 NAME 'caseExactOrderingMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) The DirectoryString (1.3.6.1.4.1.1466.115.121.1.15) syntax is described in [RFC2252]. 2.4. caseExactSubstringsMatch The caseExactSubstringsMatch rule determines whether the asserted value(s) are substrings of an attribute value of DirectoryString syntax. The rule is identical to the caseIgnoreSubstringsMatch [RFC2252] rule except that case is not ignored. (Source: X.520) ( 2.5.13.7 NAME 'caseExactSubstringsMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.58 ) The SubstringsAssertion (1.3.6.1.4.1.1466.115.121.1.58) syntax is described in [RFC2252]. 2.5. caseIgnoreListSubstringsMatch The caseIgnoreListSubstringMatch rule compares the asserted substring with an attribute value which is a sequence of DirectoryStrings, but where the case (upper or lower) is not significant for comparison purposes. The asserted value matches a stored value if and only if the asserted value matches the string formed by concatenating the strings of the stored value. This matching is done according to the caseIgnoreSubstringsMatch [RFC2252] rule; however, none of the initial, any, or final values of the asserted value are considered to match a substring of the concatenated string which spans more than one of the strings of the stored value. (Source: X.520) ( 2.5.13.12 NAME 'caseIgnoreListSubstringsMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.58 ) Zeilenga Standards Track [Page 3] RFC 3698 LDAP: Additional Matching Rules February 2004 The SubstringsAssertion (1.3.6.1.4.1.1466.115.121.1.58) syntax is described in [RFC2252]. 2.6. directoryStringFirstComponentMatch The directoryStringFirstComponentMatch rule compares for equality the asserted DirectoryString value with an attribute value of type SEQUENCE whose first component is mandatory and of type DirectoryString. The rule returns TRUE if and only if the attribute value has a first component whose value matches the asserted DirectoryString using the rules of caseIgnoreMatch [RFC2252]. A value of the assertion syntax is derived from a value of the attribute syntax by using the value of the first component of the SEQUENCE. (Source: X.520) ( 2.5.13.31 NAME 'directoryStringFirstComponentMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) The DirectoryString (1.3.6.1.4.1.1466.115.121.1.15) syntax is described in [RFC2252]. 2.7. integerOrderingMatch The integerOrderingMatch rule compares the ordering of the asserted integer with an attribute value of INTEGER syntax. The rule returns True if the attribute value is less than the asserted value. (Source: X.520) ( 2.5.13.15 NAME 'integerOrderingMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 ) The INTEGER (1.3.6.1.4.1.1466.115.121.1.27) syntax is described in [RFC2252]. 2.8. keywordMatch The keywordMatch rule compares the asserted string with keywords in an attribute value of DirectoryString syntax. The rule returns TRUE if and only if the asserted value matches any keyword in the attribute value. The identification of keywords in an attribute value and of the exactness of match are both implementation specific. (Source: X.520) ( 2.5.13.33 NAME 'keywordMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) The DirectoryString (1.3.6.1.4.1.1466.115.121.1.15) syntax is described in [RFC2252]. Zeilenga Standards Track [Page 4] RFC 3698 LDAP: Additional Matching Rules February 2004 2.9. numericStringOrderingMatch The numericStringOrderingMatch rule compares the collation order of the asserted string with an attribute value of NumericString syntax. The rule is identical to the caseIgnoreOrderingMatch [RFC2252] rule except that all space characters are skipped during comparison (case is irrelevant as characters are numeric). (Source: X.520) ( 2.5.13.9 NAME 'numericStringOrderingMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.36 ) The NumericString (1.3.6.1.4.1.1466.115.121.1.36) syntax is described in [RFC2252]. 2.10. octetStringOrderingMatch The octetStringOrderingMatch rule compares the collation order of the asserted octet string with an attribute value of OCTET STRING syntax. The rule compares octet strings from first octet to last octet, and from the most significant bit to the least significant bit within the octet. The first occurrence of a different bit determines the ordering of the strings. A zero bit precedes a one bit. If the strings are identical but contain different numbers of octets, the shorter string precedes the longer string. (Source: X.520) ( 2.5.13.18 NAME 'octetStringOrderingMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.40 ) The OCTET STRING (1.3.6.1.4.1.1466.115.121.1.40) syntax is described in [RFC2252]. 2.11. storedPrefixMatch The storedPrefixMatch rule determines whether an attribute value, whose syntax is DirectoryString is a prefix (i.e., initial substring) of the asserted value, without regard to the case (upper or lower) of the strings. The rule returns TRUE if and only if the attribute value is an initial substring of the asserted value with corresponding characters identical except possibly with regard to case. (Source: X.520) ( 2.5.13.41 NAME 'storedPrefixMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) Zeilenga Standards Track [Page 5] RFC 3698 LDAP: Additional Matching Rules February 2004 Note: This rule can be used, for example, to compare values in the Directory which are telephone area codes with a purported value which is a telephone number. The DirectoryString (1.3.6.1.4.1.1466.115.121.1.15) syntax is described in [RFC2252]. 2.12. wordMatch The wordMatch rule compares the asserted string with words in an attribute value of DirectoryString syntax. The rule returns TRUE if and only if the asserted word matches any word in the attribute value. Individual word matching is as for the caseIgnoreMatch [RFC2252] matching rule. The precise definition of a "word" is implementation specific. (Source: X.520) ( 2.5.13.32 NAME 'wordMatch' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) The DirectoryString (1.3.6.1.4.1.1466.115.121.1.15) syntax is described in [RFC2252]. 3. Security Considerations General LDAP security considerations [RFC3377] is applicable to the use of this schema. Additional considerations are noted above where appropriate. 4. IANA Considerations The Internet Assigned Numbers Authority (IANA) has updated the LDAP descriptors registry [RFC3383] as indicated in the following template: Subject: Request for LDAP Descriptor Registration Update Descriptor (short name): see comment Object Identifier: see comments Person & email address to contact for further information: Kurt Zeilenga <kurt@OpenLDAP.org> Usage: see comments Specification: RFC 3698 Author/Change Controller: IESG Comments: Zeilenga Standards Track [Page 6] RFC 3698 LDAP: Additional Matching Rules February 2004 The following descriptors have been added: NAME Type OID ------------------------ ---- --------- booleanMatch M 2.5.13.13 caseExactMatch M 2.5.13.5 caseExactOrderingMatch M 2.5.13.6 caseExactSubstringsMatch M 2.5.13.7 caseIgnoreListSubstringsMatch M 2.5.13.12 directoryStringFirstComponentMatch M 2.5.13.31 integerOrderingMatch M 2.5.13.15 keywordMatch M 2.5.13.33 numericStringOrderingMatch M 2.5.13.9 octetStringOrderingMatch M 2.5.13.18 storedPrefixMatch M 2.5.13.41 wordMatch M 2.5.13.32 where Type M is Matching Rule. This document makes no new OID assignments. It only associates LDAP matching rule descriptions with existing X.500 matching rules. 5. Acknowledgments This document borrows from [X.520], an ITU-T Recommendation. 6. References 6.1. Normative References [RFC2252] Wahl, M., Coulbeck, A., Howes, T. 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. 6.2. Informative References [RFC2798] Smith, M., "The LDAP inetOrgPerson Object Class", RFC 2798, April 2000. [RFC3383] Zeilenga, K., "IANA Considerations for LDAP", BCP 64 RFC 3383, September 2002. [RFC3703] Strassner, J., Moore, B., Moats, R. and E. Ellesson, "Policy Core LDAP Schema", RFC 3703, February 2004. Zeilenga Standards Track [Page 7] RFC 3698 LDAP: Additional Matching Rules February 2004 [X.500] International Telecommunication Union - Telecommunication Standardization Sector, "The Directory -- Overview of concepts, models and services," X.500(1993) (also ISO/IEC 9594-1:1994). [X.520] International Telecommunication Union - Telecommunication Standardization Sector, "The Directory: Selected Attribute Types", X.520(1997). 7. Author's Address Kurt D. Zeilenga OpenLDAP Foundation EMail: Kurt@OpenLDAP.org Zeilenga Standards Track [Page 8] RFC 3698 LDAP: Additional Matching Rules February 2004 8. Full Copyright Statement Copyright (C) The Internet Society (2004). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Zeilenga Standards Track [Page 9] PK .�c\��W��= �= ( doc/alt-openldap11-devel/rfc/rfc2891.txtnu �[��� Network Working Group T. Howes Request for Comments: 2891 Loudcloud Category: Standards Track M. Wahl Sun Microsystems A. Anantha Microsoft August 2000 LDAP Control Extension for Server Side Sorting of Search Results Status of this Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2000). All Rights Reserved. Abstract This document describes two LDAPv3 control extensions for server side sorting of search results. These controls allows a client to specify the attribute types and matching rules a server should use when returning the results to an LDAP search request. The controls may be useful when the LDAP client has limited functionality or for some other reason cannot sort the results but still needs them sorted. Other permissible controls on search operations are not defined in this extension. The sort controls allow a server to return a result code for the sorting of the results that is independent of the result code returned for the search operation. The key words "MUST", "SHOULD", and "MAY" used in this document are to be interpreted as described in [bradner97]. Howes, et al. Standards Track [Page 1] RFC 2891 LDAP Control Extension for Server Side Sorting August 2000 1. The Controls 1.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 "1.2.840.113556.1.4.473". 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: SortKeyList ::= SEQUENCE OF SEQUENCE { attributeType AttributeDescription, orderingRule [0] MatchingRuleId OPTIONAL, reverseOrder [1] BOOLEAN DEFAULT FALSE } The SortKeyList sequence is in order of highest to lowest sort key precedence. The MatchingRuleId, as defined in section 4.1.9 of [LDAPv3], SHOULD be one that is valid for the attribute type it applies to. If it is not, the server will return inappropriateMatching. Each attributeType should only occur in the SortKeyList once. If an attributeType is included in the sort key list multiple times, the server should return an error in the sortResult of unwillingToPerform. If the orderingRule is omitted, the ordering MatchingRule defined for use with this attribute MUST be used. Any conformant implementation of this control MUST allow a sort key list with at least one key. 1.2 Response 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 [LDAPv3]. The controlType is set to "1.2.840.113556.1.4.474". 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: Howes, et al. Standards Track [Page 2] RFC 2891 LDAP Control Extension for Server Side Sorting August 2000 SortResult ::= SEQUENCE { sortResult ENUMERATED { success (0), -- results are sorted operationsError (1), -- server internal failure timeLimitExceeded (3), -- timelimit reached before -- sorting was completed strongAuthRequired (8), -- refused to return sorted -- results via insecure -- protocol adminLimitExceeded (11), -- too many matching entries -- for the server to sort noSuchAttribute (16), -- unrecognized attribute -- type in sort key inappropriateMatching (18), -- unrecognized or -- inappropriate matching -- rule in sort key insufficientAccessRights (50), -- refused to return sorted -- results to this client busy (51), -- too busy to process unwillingToPerform (53), -- unable to sort other (80) }, attributeType [0] AttributeDescription OPTIONAL } 2. Client-Server Interaction The sortKeyRequestControl specifies one or more attribute types and matching rules for the results returned by a search request. The server SHOULD return all results for the search request in the order specified by the sort keys. If the reverseOrder field is set to TRUE, then the entries will be presented in reverse sorted order for the specified key. There are six possible scenarios that may occur as a result of the sort control being included on the search request: 1 - If the server does not support this sorting control and the client specified TRUE for the control's criticality field, then the server MUST return unavailableCriticalExtension as a return code in the searchResultDone 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 sorting control and the client specified FALSE for the control's criticality field, then the server MUST ignore the sort control and process the search request as if it were not present. This behavior is specified in section 4.1.12 of [LDAPv3]. Howes, et al. Standards Track [Page 3] RFC 2891 LDAP Control Extension for Server Side Sorting August 2000 3 - If the server supports this sorting control but for some reason cannot sort the search results using the specified sort keys and the client specified TRUE for the control's criticality field, then the server SHOULD do the following: return unavailableCriticalExtension as a return code in the searchResultDone message; include the sortKeyResponseControl in the searchResultDone message, and not send back any search result entries. 4 - If the server supports this sorting control but for some reason cannot sort the search results using the specified sort keys and the client specified FALSE for the control's criticality field, then the server should return all search results unsorted and include the sortKeyResponseControl in the searchResultDone message. 5 - If the server supports this sorting control and can sort the search results using the specified sort keys, then it should include the sortKeyResponseControl in the searchResultDone message with a sortResult of success. 6 - If the search request failed for any reason and/or there are no searchResultEntry messages returned for the search response, then the server SHOULD omit the sortKeyResponseControl from the searchResultDone message. The client application is assured that the results are sorted in the specified key order if and only if the result code in the sortKeyResponseControl is success. If the server omits the sortKeyResponseControl from the searchResultDone message, the client SHOULD assume that the sort control was ignored by the server. The sortKeyResponseControl, if included by the server in the searchResultDone message, should have the sortResult set to either success if the results were sorted in accordance with the keys specified in the sortKeyRequestControl or set to the appropriate error code as to why it could not sort the data (such as noSuchAttribute or inappropriateMatching). Optionally, the server MAY set the attributeType to the first attribute type specified in the SortKeyList that was in error. The client SHOULD ignore the attributeType field if the sortResult is success. The server may not be able to sort the results using the specified sort keys because it may not recognize one of the attribute types, the matching rule associated with an attribute type is not applicable, or none of the attributes in the search response are of these types. Servers may also restrict the number of keys allowed in the control, such as only supporting a single key. Howes, et al. Standards Track [Page 4] RFC 2891 LDAP Control Extension for Server Side Sorting August 2000 Servers that chain requests to other LDAP servers should ensure that the server satisfying the client's request sort the entire result set prior to sending back the results. 2.1 Behavior in a chained environment If a server receives a sort request, the client expects to receive a set of sorted results. If a client submits a sort request to a server which chains the request and gets entries from multiple servers, and the client has set the criticality of the sort extension to TRUE, the server MUST merge sort the results before returning them to the client or MUST return unwillingToPerform. 2.2 Other sort issues An entry that meets the search criteria may be missing one or more of the sort keys. In that case, the entry is considered to have a value of NULL for that key. This standard considers NULL to be a larger value than all other valid values for that key. For example, if only one key is specified, entries which meet the search criteria but do not have that key collate after all the entries which do have that key. If the reverseOrder flag is set, and only one key is specified, entries which meet the search criteria but do not have that key collate BEFORE all the entries which do have that key. If a sort key is a multi-valued attribute, and an entry happens to have multiple values for that attribute and no other controls are present that affect the sorting order, then the server SHOULD use the least value (according to the ORDERING rule for that attribute). 3. Interaction with other search controls When the sortKeyRequestControl control is included with the pagedResultsControl control as specified in [LdapPaged], then the server should send the searchResultEntry messages sorted according to the sort keys applied to the entire result set. The server should not simply sort each page, as this will give erroneous results to the client. The sortKeyList must be present on each searchRequest message for the paged result. It also must not change between searchRequests for the same result set. If the server has sorted the data, then it SHOULD send back a sortKeyResponseControl control on every searchResultDone message for each page. This will allow clients to quickly determine if the result set is sorted, rather than waiting to receive the entire result set. Howes, et al. Standards Track [Page 5] RFC 2891 LDAP Control Extension for Server Side Sorting August 2000 4. Security Considerations Implementors and administrators should be aware that allowing sorting of results could enable the retrieval of a large number of records from a given directory service, regardless of administrative limits set on the maximum number of records to return. A client that desired to pull all records out of a directory service could use a combination of sorting and updating of search filters to retrieve all records in a database in small result sets, thus circumventing administrative limits. This behavior can be overcome by the judicious use of permissions on the directory entries by the administrator and by intelligent implementations of administrative limits on the number of records retrieved by a client. 5. References [LDAPv3] Wahl, M, Kille, S. and T. Howes, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [Bradner97] Bradner, S., "Key Words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [LdapPaged] Weider, C., Herron, A., Anantha, A. and T. Howes, "LDAP Control Extension for Simple Paged Results Manipulation", RFC 2696, September 1999. Howes, et al. Standards Track [Page 6] RFC 2891 LDAP Control Extension for Server Side Sorting August 2000 6. Authors' Addresses Anoop Anantha Microsoft Corp. 1 Microsoft Way Redmond, WA 98052 USA Phone: +1 425 882-8080 EMail: anoopa@microsoft.com Tim Howes Loudcloud, Inc. 615 Tasman Dr. Sunnyvale, CA 94089 USA EMail: howes@loudcloud.com Mark Wahl Sun Microsystems, Inc. 8911 Capital of Texas Hwy Suite 4140 Austin, TX 78759 USA EMail: Mark.Wahl@sun.com Howes, et al. Standards Track [Page 7] RFC 2891 LDAP Control Extension for Server Side Sorting August 2000 7. 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. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Howes, et al. Standards Track [Page 8] PK .�c\V��Dn n ( doc/alt-openldap11-devel/rfc/rfc4518.txtnu �[��� Network Working Group K. Zeilenga Request for Comments: 4518 OpenLDAP Foundation Category: Standards Track June 2006 Lightweight Directory Access Protocol (LDAP): Internationalized String Preparation Status of This Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2006). Abstract The previous Lightweight Directory Access Protocol (LDAP) technical specifications did not precisely define how character string matching is to be performed. This led to a number of usability and interoperability problems. This document defines string preparation algorithms for character-based matching rules defined for use in LDAP. 1. Introduction 1.1. Background A Lightweight Directory Access Protocol (LDAP) [RFC4510] matching rule [RFC4517] defines an algorithm for determining whether a presented value matches an attribute value in accordance with the criteria defined for the rule. The proposition may be evaluated to True, False, or Undefined. True - the attribute contains a matching value, False - the attribute contains no matching value, Undefined - it cannot be determined whether the attribute contains a matching value. Zeilenga Standards Track [Page 1] RFC 4518 LDAP: Internationalized String Preparation June 2006 For instance, the caseIgnoreMatch matching rule may be used to compare whether the commonName attribute contains a particular value without regard for case and insignificant spaces. 1.2. X.500 String Matching Rules "X.520: Selected attribute types" [X.520] provides (among other things) value syntaxes and matching rules for comparing values commonly used in the directory [X.500]. These specifications are inadequate for strings composed of Unicode [Unicode] characters. The caseIgnoreMatch matching rule [X.520], for example, is simply defined as being a case-insensitive comparison where insignificant spaces are ignored. For printableString, there is only one space character and case mapping is bijective, hence this definition is sufficient. However, for Unicode string types such as universalString, this is not sufficient. For example, a case- insensitive matching implementation that folded lowercase characters to uppercase would yield different results than an implementation that used uppercase to lowercase folding. Or one implementation may view space as referring to only SPACE (U+0020), a second implementation may view any character with the space separator (Zs) property as a space, and another implementation may view any character with the whitespace (WS) category as a space. The lack of precise specification for character string matching has led to significant interoperability problems. When used in certificate chain validation, security vulnerabilities can arise. To address these problems, this document defines precise algorithms for preparing character strings for matching. 1.3. Relationship to "stringprep" The character string preparation algorithms described in this document are based upon the "stringprep" approach [RFC3454]. In "stringprep", presented and stored values are first prepared for comparison so that a character-by-character comparison yields the "correct" result. The approach used here is a refinement of the "stringprep" [RFC3454] approach. Each algorithm involves two additional preparation steps. a) Prior to applying the Unicode string preparation steps outlined in "stringprep", the string is transcoded to Unicode. b) After applying the Unicode string preparation steps outlined in "stringprep", the string is modified to appropriately handle characters insignificant to the matching rule. Zeilenga Standards Track [Page 2] RFC 4518 LDAP: Internationalized String Preparation June 2006 Hence, preparation of character strings for X.500 [X.500] matching [X.501] involves the following steps: 1) Transcode 2) Map 3) Normalize 4) Prohibit 5) Check Bidi (Bidirectional) 6) Insignificant Character Handling These steps are described in Section 2. It is noted that while various tables of Unicode characters included or referenced by this specification are derived from Unicode [Unicode] data, these tables are to be considered definitive for the purpose of implementing this specification. 1.4. Relationship to the LDAP Technical Specification This document is an integral part of the LDAP technical specification [RFC4510], which obsoletes the previously defined LDAP technical specification [RFC3377] in its entirety. This document details new LDAP internationalized character string preparation algorithms used by [RFC4517] and possible other technical specifications defining LDAP syntaxes and/or matching rules. 1.5. Relationship to X.500 LDAP is defined [RFC4510] in X.500 terms as an X.500 access mechanism. As such, there is a strong desire for alignment between LDAP and X.500 syntax and semantics. The character string preparation algorithms described in this document are based upon "Internationalized String Matching Rules for X.500" [XMATCH] proposal to ITU/ISO Joint Study Group 2. 1.6. Conventions and Terms 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]. Character names in this document use the notation for code points and names from the Unicode Standard [Unicode]. For example, the letter "a" may be represented as either <U+0061> or <LATIN SMALL LETTER A>. In the lists of mappings and the prohibited characters, the "U+" is Zeilenga Standards Track [Page 3] RFC 4518 LDAP: Internationalized String Preparation June 2006 left off to make the lists easier to read. The comments for character ranges are shown in square brackets (such as "[CONTROL CHARACTERS]") and do not come from the standard. Note: a glossary of terms used in Unicode can be found in [Glossary]. Information on the Unicode character encoding model can be found in [CharModel]. The term "combining mark", as used in this specification, refers to any Unicode [Unicode] code point that has a mark property (Mn, Mc, Me). Appendix A provides a definitive list of combining marks. 2. String Preparation The following six-step process SHALL be applied to each presented and attribute value in preparation for character string matching rule evaluation. 1) Transcode 2) Map 3) Normalize 4) Prohibit 5) Check bidi 6) Insignificant Character Handling Failure in any step causes the assertion to evaluate to Undefined. The character repertoire of this process is Unicode 3.2 [Unicode]. Note that this six-step process specification is intended to describe expected matching behavior. Implementations are free to use alternative processes so long as the matching rule evaluation behavior provided is consistent with the behavior described by this specification. 2.1. Transcode Each non-Unicode string value is transcoded to Unicode. PrintableString [X.680] values are transcoded directly to Unicode. UniversalString, UTF8String, and bmpString [X.680] values need not be transcoded as they are Unicode-based strings (in the case of bmpString, a subset of Unicode). TeletexString [X.680] values are transcoded to Unicode. As there is no standard for mapping TeletexString values to Unicode, the mapping is left a local matter. Zeilenga Standards Track [Page 4] RFC 4518 LDAP: Internationalized String Preparation June 2006 For these and other reasons, use of TeletexString is NOT RECOMMENDED. The output is the transcoded string. 2.2. Map SOFT HYPHEN (U+00AD) and MONGOLIAN TODO SOFT HYPHEN (U+1806) code points are mapped to nothing. COMBINING GRAPHEME JOINER (U+034F) and VARIATION SELECTORs (U+180B-180D, FF00-FE0F) code points are also mapped to nothing. The OBJECT REPLACEMENT CHARACTER (U+FFFC) is mapped to nothing. CHARACTER TABULATION (U+0009), LINE FEED (LF) (U+000A), LINE TABULATION (U+000B), FORM FEED (FF) (U+000C), CARRIAGE RETURN (CR) (U+000D), and NEXT LINE (NEL) (U+0085) are mapped to SPACE (U+0020). All other control code (e.g., Cc) points or code points with a control function (e.g., Cf) are mapped to nothing. The following is a complete list of these code points: U+0000-0008, 000E-001F, 007F- 0084, 0086-009F, 06DD, 070F, 180E, 200C-200F, 202A-202E, 2060-2063, 206A-206F, FEFF, FFF9-FFFB, 1D173-1D17A, E0001, E0020-E007F. ZERO WIDTH SPACE (U+200B) is mapped to nothing. All other code points with Separator (space, line, or paragraph) property (e.g., Zs, Zl, or Zp) are mapped to SPACE (U+0020). The following is a complete list of these code points: U+0020, 00A0, 1680, 2000-200A, 2028-2029, 202F, 205F, 3000. For case ignore, numeric, and stored prefix string matching rules, characters are case folded per B.2 of [RFC3454]. The output is the mapped string. 2.3. Normalize The input string is to be normalized to Unicode Form KC (compatibility composed) as described in [UAX15]. The output is the normalized string. 2.4. Prohibit All Unassigned code points are prohibited. Unassigned code points are listed in Table A.1 of [RFC3454]. Characters that, per Section 5.8 of [RFC3454], change display properties or are deprecated are prohibited. These characters are listed in Table C.8 of [RFC3454]. Zeilenga Standards Track [Page 5] RFC 4518 LDAP: Internationalized String Preparation June 2006 Private Use code points are prohibited. These characters are listed in Table C.3 of [RFC3454]. All non-character code points are prohibited. These code points are listed in Table C.4 of [RFC3454]. Surrogate codes are prohibited. These characters are listed in Table C.5 of [RFC3454]. The REPLACEMENT CHARACTER (U+FFFD) code point is prohibited. The step fails if the input string contains any prohibited code point. Otherwise, the output is the input string. 2.5. Check bidi Bidirectional characters are ignored. 2.6. Insignificant Character Handling In this step, the string is modified to ensure proper handling of characters insignificant to the matching rule. This modification differs from matching rule to matching rule. Section 2.6.1 applies to case ignore and exact string matching. Section 2.6.2 applies to numericString matching. Section 2.6.3 applies to telephoneNumber matching. 2.6.1. Insignificant Space Handling For the purposes of this section, a space is defined to be the SPACE (U+0020) code point followed by no combining marks. NOTE - The previous steps ensure that the string cannot contain any code points in the separator class, other than SPACE (U+0020). For input strings that are attribute values or non-substring assertion values: If the input string contains no non-space character, then the output is exactly two SPACEs. Otherwise (the input string contains at least one non-space character), the string is modified such that the string starts with exactly one space character, ends with exactly one SPACE character, and any inner (non-empty) sequence of space characters is replaced with exactly two SPACE characters. For instance, the input strings "foo<SPACE>bar<SPACE><SPACE>", result in the output "<SPACE>foo<SPACE><SPACE>bar<SPACE>". Zeilenga Standards Track [Page 6] RFC 4518 LDAP: Internationalized String Preparation June 2006 For input strings that are substring assertion values: If the string being prepared contains no non-space characters, then the output string is exactly one SPACE. Otherwise, the following steps are taken: - If the input string is an initial substring, it is modified to start with exactly one SPACE character; - If the input string is an initial or an any substring that ends in one or more space characters, it is modified to end with exactly one SPACE character; - If the input string is an any or a final substring that starts in one or more space characters, it is modified to start with exactly one SPACE character; and - If the input string is a final substring, it is modified to end with exactly one SPACE character. For instance, for the input string "foo<SPACE>bar<SPACE><SPACE>" as an initial substring, the output would be "<SPACE>foo<SPACE><SPACE>bar<SPACE>". As an any or final substring, the same input would result in "foo<SPACE>bar<SPACE>". Appendix B discusses the rationale for the behavior. 2.6.2. numericString Insignificant Character Handling For the purposes of this section, a space is defined to be the SPACE (U+0020) code point followed by no combining marks. All spaces are regarded as insignificant and are to be removed. For example, removal of spaces from the Form KC string: "<SPACE><SPACE>123<SPACE><SPACE>456<SPACE><SPACE>" would result in the output string: "123456" and the Form KC string: "<SPACE><SPACE><SPACE>" would result in the output string: "" (an empty string). 2.6.3. telephoneNumber Insignificant Character Handling For the purposes of this section, a hyphen is defined to be a HYPHEN-MINUS (U+002D), ARMENIAN HYPHEN (U+058A), HYPHEN (U+2010), NON-BREAKING HYPHEN (U+2011), MINUS SIGN (U+2212), SMALL HYPHEN-MINUS (U+FE63), or FULLWIDTH HYPHEN-MINUS (U+FF0D) code point followed by Zeilenga Standards Track [Page 7] RFC 4518 LDAP: Internationalized String Preparation June 2006 no combining marks and a space is defined to be the SPACE (U+0020) code point followed by no combining marks. All hyphens and spaces are considered insignificant and are to be removed. For example, removal of hyphens and spaces from the Form KC string: "<SPACE><HYPHEN>123<SPACE><SPACE>456<SPACE><HYPHEN>" would result in the output string: "123456" and the Form KC string: "<HYPHEN><HYPHEN><HYPHEN>" would result in the (empty) output string: "". 3. Security Considerations "Preparation of Internationalized Strings ("stringprep")" [RFC3454] security considerations generally apply to the algorithms described here. 4. Acknowledgements The approach used in this document is based upon design principles and algorithms described in "Preparation of Internationalized Strings ('stringprep')" [RFC3454] by Paul Hoffman and Marc Blanchet. Some additional guidance was drawn from Unicode Technical Standards, Technical Reports, and Notes. This document is a product of the IETF LDAP Revision (LDAPBIS) Working Group. 5. References 5.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC3454] Hoffman, P. and M. Blanchet, "Preparation of Internationalized Strings ("stringprep")", RFC 3454, December 2002. [RFC4510] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006. Zeilenga Standards Track [Page 8] RFC 4518 LDAP: Internationalized String Preparation June 2006 [RFC4517] Legg, S., Ed., "Lightweight Directory Access Protocol (LDAP): Syntaxes and Matching Rules", RFC 4517, June 2006. [Unicode] The Unicode Consortium, "The Unicode Standard, Version 3.2.0" is defined by "The Unicode Standard, Version 3.0" (Reading, MA, Addison-Wesley, 2000. ISBN 0-201- 61633-5), as amended by the "Unicode Standard Annex #27: Unicode 3.1" (http://www.unicode.org/reports/tr27/) and by the "Unicode Standard Annex #28: Unicode 3.2" (http://www.unicode.org/reports/tr28/). [UAX15] Davis, M. and M. Duerst, "Unicode Standard Annex #15: Unicode Normalization Forms, Version 3.2.0". <http://www.unicode.org/unicode/reports/tr15/tr15- 22.html>, March 2002. [X.680] International Telecommunication Union - Telecommunication Standardization Sector, "Abstract Syntax Notation One (ASN.1) - Specification of Basic Notation", X.680(2002) (also ISO/IEC 8824-1:2002). 5.2. Informative References [X.500] International Telecommunication Union - Telecommunication Standardization Sector, "The Directory -- Overview of concepts, models and services," X.500(1993) (also ISO/IEC 9594-1:1994). [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). [Glossary] The Unicode Consortium, "Unicode Glossary", <http://www.unicode.org/glossary/>. [CharModel] Whistler, K. and M. Davis, "Unicode Technical Report #17, Character Encoding Model", UTR17, <http://www.unicode.org/unicode/reports/tr17/>, August 2000. Zeilenga Standards Track [Page 9] RFC 4518 LDAP: Internationalized String Preparation June 2006 [RFC3377] Hodges, J. and R. Morgan, "Lightweight Directory Access Protocol (v3): Technical Specification", RFC 3377, September 2002. [RFC4515] Smith, M., Ed. and T. Howes, "Lightweight Directory Access Protocol (LDAP): String Representation of Search Filters", RFC 4515, June 2006. [XMATCH] Zeilenga, K., "Internationalized String Matching Rules for X.500", Work in Progress. Zeilenga Standards Track [Page 10] RFC 4518 LDAP: Internationalized String Preparation June 2006 Appendix A. Combining Marks This appendix is normative. This table was derived from Unicode [Unicode] data files; it lists all code points with the Mn, Mc, or Me properties. This table is to be considered definitive for the purposes of implementation of this specification. 0300-034F 0360-036F 0483-0486 0488-0489 0591-05A1 05A3-05B9 05BB-05BC 05BF 05C1-05C2 05C4 064B-0655 0670 06D6-06DC 06DE-06E4 06E7-06E8 06EA-06ED 0711 0730-074A 07A6-07B0 0901-0903 093C 093E-094F 0951-0954 0962-0963 0981-0983 09BC 09BE-09C4 09C7-09C8 09CB-09CD 09D7 09E2-09E3 0A02 0A3C 0A3E-0A42 0A47-0A48 0A4B-0A4D 0A70-0A71 0A81-0A83 0ABC 0ABE-0AC5 0AC7-0AC9 0ACB-0ACD 0B01-0B03 0B3C 0B3E-0B43 0B47-0B48 0B4B-0B4D 0B56-0B57 0B82 0BBE-0BC2 0BC6-0BC8 0BCA-0BCD 0BD7 0C01-0C03 0C3E-0C44 0C46-0C48 0C4A-0C4D 0C55-0C56 0C82-0C83 0CBE-0CC4 0CC6-0CC8 0CCA-0CCD 0CD5-0CD6 0D02-0D03 0D3E-0D43 0D46-0D48 0D4A-0D4D 0D57 0D82-0D83 0DCA 0DCF-0DD4 0DD6 0DD8-0DDF 0DF2-0DF3 0E31 0E34-0E3A 0E47-0E4E 0EB1 0EB4-0EB9 0EBB-0EBC 0EC8-0ECD 0F18-0F19 0F35 0F37 0F39 0F3E-0F3F 0F71-0F84 0F86-0F87 0F90-0F97 0F99-0FBC 0FC6 102C-1032 1036-1039 1056-1059 1712-1714 1732-1734 1752-1753 1772-1773 17B4-17D3 180B-180D 18A9 20D0-20EA 302A-302F 3099-309A FB1E FE00-FE0F FE20-FE23 1D165-1D169 1D16D-1D172 1D17B-1D182 1D185-1D18B 1D1AA-1D1AD Appendix B. Substrings Matching This appendix is non-normative. In the absence of substrings matching, the insignificant space handling for case ignore/exact matching could be simplified. Specifically, the handling could be to require that all sequences of one or more spaces be replaced with one space and, if the string contains non-space characters, removal of all leading spaces and trailing spaces. In the presence of substrings matching, this simplified space handling would lead to unexpected and undesirable matching behavior. For instance: 1) (CN=foo\20*\20bar) would match the CN value "foobar"; Zeilenga Standards Track [Page 11] RFC 4518 LDAP: Internationalized String Preparation June 2006 2) (CN=*\20foobar\20*) would match "foobar", but (CN=*\20*foobar*\20*) would not. Note to readers not familiar with LDAP substrings matching: the LDAP filter [RFC4515] assertion (CN=A*B*C) says to "match any value (of the attribute CN) that begins with A, contains B after A, ends with C where C is also after B." The first case illustrates that this simplified space handling would cause leading and trailing spaces in substrings of the string to be regarded as insignificant. However, only leading and trailing (as well as multiple consecutive spaces) of the string (as a whole) are insignificant. The second case illustrates that this simplified space handling would cause sub-partitioning failures. That is, if a prepared any substring matches a partition of the attribute value, then an assertion constructed by subdividing that substring into multiple substrings should also match. In designing an appropriate approach for space handling for substrings matching, one must study key aspects of X.500 case exact/ignore matching. X.520 [X.520] says: The [substrings] rule returns TRUE if there is a partitioning of the attribute value (into portions) such that: - the specified substrings (initial, any, final) match different portions of the value in the order of the strings sequence; - initial, if present, matches the first portion of the value; - final, if present, matches the last portion of the value; - any, if present, matches some arbitrary portion of the value. That is, the substrings assertion (CN=foo\20*\20bar) matches the attribute value "foo<SPACE><SPACE>bar" as the value can be partitioned into the portions "foo<SPACE>" and "<SPACE>bar" meeting the above requirements. Zeilenga Standards Track [Page 12] RFC 4518 LDAP: Internationalized String Preparation June 2006 X.520 also says: [T]he following spaces are regarded as not significant: - leading spaces (i.e., those preceding the first character that is not a space); - trailing spaces (i.e., those following the last character that is not a space); - multiple consecutive spaces (these are taken as equivalent to a single space character). This statement applies to the assertion values and attribute values as whole strings, and not individually to substrings of an assertion value. In particular, the statements should be taken to mean that if an assertion value and attribute value match without any consideration to insignificant characters, then that assertion value should also match any attribute value that differs only by inclusion nor removal of insignificant characters. Hence the assertion (CN=foo\20*\20bar) matches "foo<SPACE><SPACE><SPACE>bar" and "foo<SPACE>bar" as these values only differ from "foo<SPACE><SPACE>bar" by the inclusion or removal of insignificant spaces. Astute readers of this text will also note that there are special cases where the specified space handling does not ignore spaces that could be considered insignificant. For instance, the assertion (CN=\20*\20*\20) does not match "<SPACE><SPACE><SPACE>" (insignificant spaces present in value) or " " (insignificant spaces not present in value). However, as these cases have no practical application that cannot be met by simple assertions, e.g., (cn=\20), and this minor anomaly can only be fully addressed by a preparation algorithm to be used in conjunction with character-by-character partitioning and matching, the anomaly is considered acceptable. Author's Address Kurt D. Zeilenga OpenLDAP Foundation EMail: Kurt@OpenLDAP.org Zeilenga Standards Track [Page 13] RFC 4518 LDAP: Internationalized String Preparation June 2006 Full Copyright Statement Copyright (C) The Internet Society (2006). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Zeilenga Standards Track [Page 14] PK .�c\�&�*J *J ( doc/alt-openldap11-devel/rfc/rfc4531.txtnu �[��� Network Working Group K. Zeilenga Request for Comments: 4531 OpenLDAP Foundation Category: Experimental June 2006 Lightweight Directory Access Protocol (LDAP) Turn Operation Status of This Memo This memo defines an Experimental Protocol for the Internet community. It does not specify an Internet standard of any kind. Discussion and suggestions for improvement are requested. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2006). Abstract This specification describes a Lightweight Directory Access Protocol (LDAP) extended operation to reverse (or "turn") the roles of client and server for subsequent protocol exchanges in the session, or to enable each peer to act as both client and server with respect to the other. Table of Contents 1. Background and Intent of Use ....................................2 1.1. Terminology ................................................2 2. Turn Operation ..................................................2 2.1. Turn Request ...............................................3 2.2. Turn Response ..............................................3 3. Authentication ..................................................3 3.1. Use with TLS and Simple Authentication .....................4 3.2. Use with TLS and SASL EXTERNAL .............................4 3.3. Use of Mutual Authentication and SASL EXTERNAL .............4 4. TLS and SASL Security Layers ....................................5 5. Security Considerations .........................................6 6. IANA Considerations .............................................6 6.1. Object Identifier ..........................................6 6.2. LDAP Protocol Mechanism ....................................7 7. References ......................................................7 7.1. Normative References .......................................7 7.2. Informative References .....................................8 Zeilenga Experimental [Page 1] RFC 4531 LDAP Turn Operation June 2006 1. Background and Intent of Use The Lightweight Directory Access Protocol (LDAP) [RFC4510][RFC4511] is a client-server protocol that typically operates over reliable octet-stream transports, such as the Transport Control Protocol (TCP). Generally, the client initiates the stream by connecting to the server's listener at some well-known address. There are cases where it is desirable for the server to initiate the stream. Although it certainly is possible to write a technical specification detailing how to implement server-initiated LDAP sessions, this would require the design of new authentication and other security mechanisms to support server-initiated LDAP sessions. Instead, this document introduces an operation, the Turn operation, which may be used to reverse the client-server roles of the protocol peers. This allows the initiating protocol peer to become the server (after the reversal). As an additional feature, the Turn operation may be used to allow both peers to act in both roles. This is useful where both peers are directory servers that desire to request, as LDAP clients, that operations be performed by the other. This may be useful in replicated and/or distributed environments. This operation is intended to be used between protocol peers that have established a mutual agreement, by means outside of the protocol, that requires reversal of client-server roles, or allows both peers to act both as client and server. 1.1. Terminology Protocol elements are described using ASN.1 [X.680] with implicit tags. The term "BER-encoded" means the element is to be encoded using the Basic Encoding Rules [X.690] under the restrictions detailed in Section 5.1 of [RFC4511]. 2. Turn Operation The Turn operation is defined as an LDAP-Extended Operation [Protocol, Section 4.12] identified by the 1.3.6.1.1.19 OID. The function of the Turn Operation is to request that the client-server roles be reversed, or, optionally, to request that both protocol peers be able to act both as client and server in respect to the other. Zeilenga Experimental [Page 2] RFC 4531 LDAP Turn Operation June 2006 2.1. Turn Request The Turn request is an ExtendedRequest where the requestName field contains the 1.3.6.1.1.19 OID and the requestValue field is a BER- encoded turnValue: turnValue ::= SEQUENCE { mutual BOOLEAN DEFAULT FALSE, identifier LDAPString } A TRUE mutual field value indicates a request to allow both peers to act both as client and server. A FALSE mutual field value indicates a request to reserve the client and server roles. The value of the identifier field is a locally defined policy identifier (typically associated with a mutual agreement for which this turn is be executed as part of). 2.2. Turn Response A Turn response is an ExtendedResponse where the responseName and responseValue fields are absent. A resultCode of success is returned if and only if the responder is willing and able to turn the session as requested. Otherwise, a different resultCode is returned. 3. Authentication This extension's authentication model assumes separate authentication of the peers in each of their roles. A separate Bind exchange is expected between the peers in their new roles to establish identities in these roles. Upon completion of the Turn, the responding peer in its new client role has an anonymous association at the initiating peer in its new server role. If the turn was mutual, the authentication association of the initiating peer in its pre-existing client role is left intact at the responding peer in its pre-existing server role. If the turn was not mutual, this association is void. The responding peer may establish its identity in its client role by requesting and successfully completing a Bind operation. The remainder of this section discusses some authentication scenarios. In the protocol exchange illustrations, A refers to the initiating peer (the original client) and B refers to the responding peer (the original server). Zeilenga Experimental [Page 3] RFC 4531 LDAP Turn Operation June 2006 3.1. Use with TLS and Simple Authentication A->B: StartTLS Request B->A: StartTLS(success) Response A->B: Bind(Simple(cn=B,dc=example,dc=net,B's secret)) Request B->A: Bind(success) Response A->B: Turn(TRUE,"XXYYZ") Request B->A: Turn(success) Response B->A: Bind(Simple(cn=A,dc=example,dc=net,A's secret)) Request A->B: Bind(success) Response In this scenario, TLS (Transport Layer Security) [RFC4346] is started and the initiating peer (the original client) establishes its identity with the responding peer prior to the Turn using the DN/password mechanism of the Simple method of the Bind operation. After the turn, the responding peer, in its new client role, establishes its identity with the initiating peer in its new server role. 3.2. Use with TLS and SASL EXTERNAL A->B: StartTLS Request B->A: StartTLS(success) Response A->B: Bind(SASL(EXTERNAL)) Request B->A: Bind(success) Response A->B: Turn(TRUE,"XXYYZ") Request B->A: Turn(success) Response B->A: Bind(SASL(EXTERNAL)) Request A->B: Bind(success) Response In this scenario, TLS is started (with each peer providing a valid certificate), and the initiating peer (the original client) establishes its identity through the use of the EXTERNAL mechanism of the SASL (Simple Authentication and Security Layer) [RFC4422] method of the Bind operation prior to the Turn. After the turn, the responding peer, in its new client role, establishes its identity with the initiating peer in its new server role. 3.3. Use of Mutual Authentication and SASL EXTERNAL A number of SASL mechanisms, such as GSSAPI [SASL-K5], support mutual authentication. The initiating peer, in its new server role, may use the identity of the responding peer, established by a prior authentication exchange, as its source for "external" identity in subsequent EXTERNAL exchange. A->B: Bind(SASL(GSSAPI)) Request <intermediate messages> Zeilenga Experimental [Page 4] RFC 4531 LDAP Turn Operation June 2006 B->A: Bind(success) Response A->B: Turn(TRUE,"XXYYZ") Request B->A: Turn(success) Response B->A: Bind(SASL(EXTERNAL)) Request A->B: Bind(success) Response In this scenario, a GSSAPI mutual-authentication exchange is completed between the initiating peer (the original client) and the responding server (the original server) prior to the turn. After the turn, the responding peer, in its new client role, requests that the initiating peer utilize an "external" identity to establish its LDAP authorization identity. 4. TLS and SASL Security Layers As described in [RFC4511], LDAP supports both Transport Layer Security (TLS) [RFC4346] and Simple Authentication and Security Layer (SASL) [RFC4422] security frameworks. The following table illustrates the relationship between the LDAP message layer, SASL layer, TLS layer, and transport connection within an LDAP session. +----------------------+ | LDAP message layer | +----------------------+ > LDAP PDUs +----------------------+ < data | SASL layer | +----------------------+ > SASL-protected data +----------------------+ < data | TLS layer | Application +----------------------+ > TLS-protected data ------------+----------------------+ < data Transport | transport connection | +----------------------+ This extension does not alter this relationship, nor does it remove the general restriction against multiple TLS layers, nor does it remove the general restriction against multiple SASL layers. As specified in [RFC4511], the StartTLS operation is used to initiate negotiation of a TLS layer. If a TLS is already installed, the StartTLS operation must fail. Upon establishment of the TLS layer, regardless of which peer issued the request to start TLS, the peer that initiated the LDAP session (the original client) performs the "server identity check", as described in Section 3.1.5 of [RFC4513], treating itself as the "client" and its peer as the "server". As specified in [RFC4422], a newly negotiated SASL security layer replaces the installed SASL security layer. Though the client/server Zeilenga Experimental [Page 5] RFC 4531 LDAP Turn Operation June 2006 roles in LDAP, and hence SASL, may be reversed in subsequent exchanges, only one SASL security layer may be installed at any instance. 5. Security Considerations Implementors should be aware that the reversing of client/server roles and/or allowing both peers to act as client and server likely introduces security considerations not foreseen by the authors of this document. In particular, the security implications of the design choices made in the authentication and data security models for this extension (discussed in Sections 3 and 4, respectively) are not fully studied. It is hoped that experimentation with this extension will lead to better understanding of the security implications of these models and other aspects of this extension, and that appropriate considerations will be documented in a future document. The following security considerations are apparent at this time. Implementors should take special care to process LDAP, SASL, TLS, and other events in the appropriate roles for the peers. Note that while the Turn reverses the client/server roles with LDAP, and in SASL authentication exchanges, it does not reverse the roles within the TLS layer or the transport connection. The responding server (the original server) should restrict use of this operation to authorized clients. Client knowledge of a valid identifier should not be the sole factor in determining authorization to turn. Where the peers except to establish TLS, TLS should be started prior to the Turn and any request to authenticate via the Bind operation. LDAP security considerations [RFC4511][RFC4513] generally apply to this extension. 6. IANA Considerations The following values [RFC4520] have been registered by the IANA. 6.1. Object Identifier The IANA has assigned an LDAP Object Identifier to identify the LDAP Turn Operation, as defined in this document. Zeilenga Experimental [Page 6] RFC 4531 LDAP Turn Operation June 2006 Subject: Request for LDAP Object Identifier Registration Person & email address to contact for further information: Kurt Zeilenga <kurt@OpenLDAP.org> Specification: RFC 4531 Author/Change Controller: Author Comments: Identifies the LDAP Turn Operation 6.2. LDAP Protocol Mechanism The IANA has registered the LDAP Protocol Mechanism described in this document. Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: 1.3.6.1.1.19 Description: LDAP Turn Operation Person & email address to contact for further information: Kurt Zeilenga <kurt@openldap.org> Usage: Extended Operation Specification: RFC 4531 Author/Change Controller: Author Comments: none 7. References 7.1. Normative References [RFC4346] Dierks, T. and, E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.1", RFC 4346, April 2006. [RFC4422] Melnikov, A., Ed. and K. Zeilenga, Ed., "Simple Authentication and Security Layer (SASL)", RFC 4422, June 2006. [RFC4510] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006. [RFC4511] Sermersheim, J., Ed., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006. [RFC4513] Harrison, R., Ed., "Lightweight Directory Access Protocol (LDAP): Authentication Methods and Security Mechanisms", RFC 4513, June 2006. Zeilenga Experimental [Page 7] RFC 4531 LDAP Turn Operation June 2006 [X.680] International Telecommunication Union - Telecommunication Standardization Sector, "Abstract Syntax Notation One (ASN.1) - Specification of Basic Notation", X.680(2002) (also ISO/IEC 8824-1:2002). [X.690] International Telecommunication Union - Telecommunication Standardization Sector, "Specification of ASN.1 encoding rules: Basic Encoding Rules (BER), Canonical Encoding Rules (CER), and Distinguished Encoding Rules (DER)", X.690(2002) (also ISO/IEC 8825-1:2002). 7.2. Informative References [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006. [SASL-K5] Melnikov, A., Ed., "The Kerberos V5 ("GSSAPI") SASL Mechanism", Work in Progress, May 2006. Author's Address Kurt D. Zeilenga OpenLDAP Foundation EMail: Kurt@OpenLDAP.org Zeilenga Experimental [Page 8] RFC 4531 LDAP Turn Operation June 2006 Full Copyright Statement Copyright (C) The Internet Society (2006). 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@ietf.org. Acknowledgement Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Zeilenga Experimental [Page 9] PK .�c\���� �� > doc/alt-openldap11-devel/drafts/draft-howard-rfc2307bis-xx.txtnu �[��� Network Working Group L. Howard Internet-Draft PADL Software Obsoletes: 2307 (if approved) H. Chu, Ed. Intended status: Informational Symas Corp. Expires: February 10, 2010 August 9, 2009 An Approach for Using LDAP as a Network Information Service draft-howard-rfc2307bis-02.txt Status of this Memo This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and 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 February 10, 2010. Copyright Notice Copyright (c) 2009 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents in effect on the date of publication of this document (http://trustee.ietf.org/license-info). Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Howard & Chu Expires February 10, 2010 [Page 1] Internet-Draft LDAP NameService Schema August 2009 Abstract This document describes a mechanism for mapping entities related to TCP/IP and the UNIX system [UNIX] into [X.500] entries so that they may be resolved with the Lightweight Directory Access Protocol [RFC4511]. A set of attribute types and object classes are proposed, along with specific guidelines for interpreting them. The intention is to assist the deployment of LDAP as an organizational nameservice. No proposed solutions are intended as standards for the Internet. Rather, it is hoped that a general consensus will emerge as to the appropriate solution to such problems, leading eventually to the adoption of standards. The proposed mechanism has already been implemented with some success. Howard & Chu Expires February 10, 2010 [Page 2] Internet-Draft LDAP NameService Schema August 2009 1. Background and Motivation The UNIX (R) operating system, and its derivatives (specifically, those which support TCP/IP and conform to the X/Open Single UNIX specification [UNIX]) require a means of looking up entities, by matching them against search criteria or by enumeration. (Other operating systems that support TCP/IP may provide some means of resolving some of these entities. This schema is applicable to those environments also.) These entities include users, groups, IP services (which map names to IP ports and protocols, and vice versa), IP protocols (which map names to IP protocol numbers and vice versa), RPCs (which map names to ONC Remote Procedure Call [RFC1057] numbers and vice versa), NIS netgroups, booting information (boot parameters and MAC address mappings), filesystem mounts, IP hosts and networks. Resolution requests are made through a set of C functions, provided in the UNIX system's C library. For example, the UNIX system utility "ls", which enumerates the contents of a filesystem directory, uses the C library function getpwuid() in order to map user IDs to login names. Once the request is made, it is resolved using a "nameservice" which is supported by the client library. The nameservice may be, at its simplest, a collection of files in the local filesystem which are opened and searched by the C library. Other common nameservices include the Network Information Service (NIS) and the Domain Name System (DNS) [RFC1034]. (The latter is typically used for resolving hosts, services and networks.) Both these nameservices have the advantage of being distributed and thus permitting a common set of entities to be shared amongst many clients. LDAP is a distributed, hierarchical directory service access protocol which is used to access repositories of users and other network- related entities. Because LDAP is often not tightly integrated with the host operating system, information such as users may need to be kept both in LDAP and in an operating system supported nameservice such as NIS. By using LDAP as the primary means of resolving these entities, these redundancy issues are minimized and the scalability of LDAP can be exploited. (By comparison, NIS services based on flat files do not have the scalability or extensibility of LDAP or X.500.) The object classes and attributes defined below are suitable for representing the aforementioned entities in a form compatible with LDAP and X.500 directory services. Howard & Chu Expires February 10, 2010 [Page 3] Internet-Draft LDAP NameService Schema August 2009 2. General Issues 2.1. Terminology The key words "MUST", "SHOULD", and "MAY" used in this document are to be interpreted as described in [RFC2119]. For the purposes of this document, the term "nameservice" refers to a service, such as NIS or flat files, that is used by the operating system to resolve entities within a single, local naming context. Contrast this with a "directory service" such as LDAP, which supports extensible schema and multiple naming contexts. The term "NIS-related entities" broadly refers to entities which are typically resolved using the Network Information Service. (NIS was previously known as YP.) Deploying LDAP for resolving these entities does not imply that NIS be used, as a gateway or otherwise. In particular, the host and network classes are generically applicable, and may be implemented on any system that wishes to use LDAP or X.500 for host and network resolution. The "DUA" (directory user agent) refers to the LDAP client querying these entities, such as an LDAP to NIS gateway or the C library. The "client" refers to the application which ultimately makes use of the information returned by the resolution. It is irrelevant whether the DUA and the client reside within the same address space. The act of the DUA making this information to the client is termed "republishing". To avoid confusion, the term "login name" refers to the user's login name (being the value of the uid attribute) and the term "user ID" refers to the user's integer identification number (being the value of the uidNumber attribute). The phrases "resolving an entity" and "resolution of entities" refer respectively to enumerating NIS-related entities of a given type, and matching them against a given search criterion. One or more entities are returned as a result of successful "resolutions" (a "match" operation will only return one entity). The use of the term UNIX does not confer upon this schema the endorsement of owners of the UNIX trademark. Where necessary, the term "TCP/IP entity" is used to refer to protocols, services, hosts, and networks, and the term "UNIX entity" to its complement. (The former category does not mandate the host operating system supporting the interfaces required for resolving UNIX entities.) The OIDs defined below are derived from iso(1) org(3) dod(6) Howard & Chu Expires February 10, 2010 [Page 4] Internet-Draft LDAP NameService Schema August 2009 internet(1) directory(1) nisSchema(1) 2.2. Schema The attributes and classes defined in this document are summarized below. 2.2.1. Attributes The following attributes are defined in this document: uidNumber gidNumber gecos homeDirectory loginShell shadowLastChange shadowMin shadowMax shadowWarning shadowInactive shadowExpire shadowFlag memberUid memberNisNetgroup nisNetgroupTriple ipServicePort ipServiceProtocol ipProtocolNumber oncRpcNumber ipHostNumber ipNetworkNumber ipNetmaskNumber macAddress bootParameter bootFile nisMapName nisMapEntry nisPublicKey nisSecretKey nisDomain automountMapName automountKey automountInformation Additionally, some of the attributes defined in [RFC4519] and [RFC3112] are required. Howard & Chu Expires February 10, 2010 [Page 5] Internet-Draft LDAP NameService Schema August 2009 2.2.2. Attribute Option Centralizing a name service in LDAP allows heterogeneous systems to obtain their information from a single place. However in some cases, this information cannot be used uniformly on all of the client systems. These attribute options are defined to allow system- specific values to be used where necessary. The options are defined as the following: host-<hostname> hostos-<ostype> where hostname is a string representing the name of a specific machine, and ostype is a string representing a particular operating system. For example, a user named "Babs Jensen" may have a different home directory on different machines. This could be represented as: homeDirectory: /home/babsj homeDirectory;hostos-sunos: /export/home/bjensen homeDirectory;host-babshost: /home/root These attribute options follow sub-typing semantics. If a DUA requests an attribute to be returned in a search operation, and does not specify an option, all subtypes of that attribute are returned. 2.2.3. Object Classes The following object classes are defined in this document: posixAccount shadowAccount posixGroup ipService ipProtocol oncRpc ipHost ipNetwork nisNetgroup nisMap nisObject ieee802Device bootableDevice nisKeyObject nisDomainObject automountMap automount Howard & Chu Expires February 10, 2010 [Page 6] Internet-Draft LDAP NameService Schema August 2009 Additionally, some of the attributes defined in [RFC4519] are required. Howard & Chu Expires February 10, 2010 [Page 7] Internet-Draft LDAP NameService Schema August 2009 3. Attribute Definitions This section contains attribute definitions to be implemented by DUAs supporting this schema: ( 1.3.6.1.1.1.1.0 NAME 'uidNumber' DESC 'An integer uniquely identifying a user in an administrative domain' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) ( 1.3.6.1.1.1.1.1 NAME 'gidNumber' DESC 'An integer uniquely identifying a group in an administrative domain' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) ( 1.3.6.1.1.1.1.2 NAME 'gecos' DESC 'The GECOS field; the common name' EQUALITY caseIgnoreMatch SUBSTRINGS caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) ( 1.3.6.1.1.1.1.3 NAME 'homeDirectory' DESC 'The absolute path to the home directory' EQUALITY caseExactIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 SINGLE-VALUE ) ( 1.3.6.1.1.1.1.4 NAME 'loginShell' DESC 'The path to the login shell' EQUALITY caseExactIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 SINGLE-VALUE ) Howard & Chu Expires February 10, 2010 [Page 8] Internet-Draft LDAP NameService Schema August 2009 ( 1.3.6.1.1.1.1.5 NAME 'shadowLastChange' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) ( 1.3.6.1.1.1.1.6 NAME 'shadowMin' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) ( 1.3.6.1.1.1.1.7 NAME 'shadowMax' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) ( 1.3.6.1.1.1.1.8 NAME 'shadowWarning' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) ( 1.3.6.1.1.1.1.9 NAME 'shadowInactive' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) ( 1.3.6.1.1.1.1.10 NAME 'shadowExpire' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) ( 1.3.6.1.1.1.1.11 NAME 'shadowFlag' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) Howard & Chu Expires February 10, 2010 [Page 9] Internet-Draft LDAP NameService Schema August 2009 ( 1.3.6.1.1.1.1.12 NAME 'memberUid' EQUALITY caseExactMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) ( 1.3.6.1.1.1.1.13 NAME 'memberNisNetgroup' EQUALITY caseExactMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) ( 1.3.6.1.1.1.1.14 NAME 'nisNetgroupTriple' DESC 'Netgroup triple' EQUALITY caseIgnoreMatch SUBSTRINGS caseIgnoreSubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) ( 1.3.6.1.1.1.1.15 NAME 'ipServicePort' DESC 'Service port number' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) ( 1.3.6.1.1.1.1.16 NAME 'ipServiceProtocol' DESC 'Service protocol name' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) ( 1.3.6.1.1.1.1.17 NAME 'ipProtocolNumber' DESC 'IP protocol number' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) ( 1.3.6.1.1.1.1.18 NAME 'oncRpcNumber' DESC 'ONC RPC number' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) Howard & Chu Expires February 10, 2010 [Page 10] Internet-Draft LDAP NameService Schema August 2009 ( 1.3.6.1.1.1.1.19 NAME 'ipHostNumber' DESC 'IPv4 addresses as a dotted decimal omitting leading zeros or IPv6 addresses as defined in RFC2373' EQUALITY caseIgnoreIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) ( 1.3.6.1.1.1.1.20 NAME 'ipNetworkNumber' DESC 'IP network omitting leading zeros, eg. 192.168' EQUALITY caseIgnoreIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 SINGLE-VALUE ) ( 1.3.6.1.1.1.1.21 NAME 'ipNetmaskNumber' DESC 'IP netmask omitting leading zeros, eg. 255.255.255.0' EQUALITY caseIgnoreIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 SINGLE-VALUE ) ( 1.3.6.1.1.1.1.22 NAME 'macAddress' DESC 'MAC address in maximal, colon separated hex notation, eg. 00:00:92:90:ee:e2' EQUALITY caseIgnoreIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) ( 1.3.6.1.1.1.1.23 NAME 'bootParameter' DESC 'rpc.bootparamd parameter' EQUALITY caseExactIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) ( 1.3.6.1.1.1.1.24 NAME 'bootFile' DESC 'Boot image name' EQUALITY caseExactIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) ( 1.3.6.1.1.1.1.26 NAME 'nisMapName' DESC 'Name of a generic NIS map' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{64} ) Howard & Chu Expires February 10, 2010 [Page 11] Internet-Draft LDAP NameService Schema August 2009 ( 1.3.6.1.1.1.1.27 NAME 'nisMapEntry' DESC 'A generic NIS entry' EQUALITY caseExactMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{1024} SINGLE-VALUE ) ( 1.3.6.1.1.1.1.28 NAME 'nisPublicKey' DESC 'NIS public key' EQUALITY octetStringMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.40 SINGLE-VALUE ) ( 1.3.6.1.1.1.1.29 NAME 'nisSecretKey' DESC 'NIS secret key' EQUALITY octetStringMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.40 SINGLE-VALUE ) ( 1.3.6.1.1.1.1.30 NAME 'nisDomain' DESC 'NIS domain' EQUALITY caseIgnoreIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26{256} ) ( 1.3.6.1.1.1.1.31 NAME 'automountMapName' DESC 'automount Map Name' EQUALITY caseExactMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) ( 1.3.6.1.1.1.1.32 NAME 'automountKey' DESC 'Automount Key value' EQUALITY caseExactMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) ( 1.3.6.1.1.1.1.33 NAME 'automountInformation' DESC 'Automount information' EQUALITY caseExactMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) Howard & Chu Expires February 10, 2010 [Page 12] Internet-Draft LDAP NameService Schema August 2009 4. Class Definitions This section contains class definitions to be implemented by DUAs supporting the schema. Various schema for mail routing and delivery using LDAP directories have been proposed, and as such this document does not consider schema for representing mail aliases or distribution lists. ( 1.3.6.1.1.1.2.0 NAME 'posixAccount' SUP top AUXILIARY DESC 'Abstraction of an account with POSIX attributes' MUST ( cn $ uid $ uidNumber $ gidNumber $ homeDirectory ) MAY ( authPassword $ userPassword $ loginShell $ gecos $ description ) ) ( 1.3.6.1.1.1.2.1 NAME 'shadowAccount' SUP top AUXILIARY DESC 'Additional attributes for shadow passwords' MUST uid MAY ( authPassword $ userPassword $ description $ shadowLastChange $ shadowMin $ shadowMax $ shadowWarning $ shadowInactive $ shadowExpire $ shadowFlag ) ) ( 1.3.6.1.1.1.2.2 NAME 'posixGroup' SUP top AUXILIARY DESC 'Abstraction of a group of accounts' MUST gidNumber MAY ( authPassword $ userPassword $ memberUid $ description ) ) ( 1.3.6.1.1.1.2.3 NAME 'ipService' SUP top STRUCTURAL DESC 'Abstraction an Internet Protocol service. Maps an IP port and protocol (such as tcp or udp) to one or more names; the distinguished value of the cn attribute denotes the service's canonical name' MUST ( cn $ ipServicePort $ ipServiceProtocol ) MAY description ) ( 1.3.6.1.1.1.2.4 NAME 'ipProtocol' SUP top STRUCTURAL DESC 'Abstraction of an IP protocol. Maps a protocol number to one or more names. The distinguished value of the cn attribute denotes the protocol canonical name' MUST ( cn $ ipProtocolNumber ) MAY description ) Howard & Chu Expires February 10, 2010 [Page 13] Internet-Draft LDAP NameService Schema August 2009 ( 1.3.6.1.1.1.2.5 NAME 'oncRpc' SUP top STRUCTURAL DESC 'Abstraction of an Open Network Computing (ONC) [RFC1057] Remote Procedure Call (RPC) binding. This class maps an ONC RPC number to a name. The distinguished value of the cn attribute denotes the RPC service canonical name' MUST ( cn $ oncRpcNumber ) MAY description ) ( 1.3.6.1.1.1.2.6 NAME 'ipHost' SUP top AUXILIARY DESC 'Abstraction of a host, an IP device. The distinguished value of the cn attribute denotes the host's canonical name. Device SHOULD be used as a structural class' MUST ( cn $ ipHostNumber ) MAY ( authPassword $ userPassword $ l $ description $ manager ) ) ( 1.3.6.1.1.1.2.7 NAME 'ipNetwork' SUP top STRUCTURAL DESC 'Abstraction of a network. The distinguished value of the cn attribute denotes the network canonical name' MUST ipNetworkNumber MAY ( cn $ ipNetmaskNumber $ l $ description $ manager ) ) ( 1.3.6.1.1.1.2.8 NAME 'nisNetgroup' SUP top STRUCTURAL DESC 'Abstraction of a netgroup. May refer to other netgroups' MUST cn MAY ( nisNetgroupTriple $ memberNisNetgroup $ description ) ) ( 1.3.6.1.1.1.2.9 NAME 'nisMap' SUP top STRUCTURAL DESC 'A generic abstraction of a NIS map' MUST nisMapName MAY description ) ( 1.3.6.1.1.1.2.10 NAME 'nisObject' SUP top STRUCTURAL DESC 'An entry in a NIS map' MUST ( cn $ nisMapEntry $ nisMapName ) ( 1.3.6.1.1.1.2.11 NAME 'ieee802Device' SUP top AUXILIARY DESC 'A device with a MAC address; device SHOULD be used as a structural class' MAY macAddress ) Howard & Chu Expires February 10, 2010 [Page 14] Internet-Draft LDAP NameService Schema August 2009 ( 1.3.6.1.1.1.2.12 NAME 'bootableDevice' SUP top AUXILIARY DESC 'A device with boot parameters; device SHOULD be used as a structural class' MAY ( bootFile $ bootParameter ) ) ( 1.3.6.1.1.1.2.14 NAME 'nisKeyObject' SUP top AUXILIARY DESC 'An object with a public and secret key' MUST ( cn $ nisPublicKey $ nisSecretKey ) MAY ( uidNumber $ description ) ) ( 1.3.6.1.1.1.2.15 NAME 'nisDomainObject' SUP top AUXILIARY DESC 'Associates a NIS domain with a naming context' MUST nisDomain ) ( 1.3.6.1.1.1.2.16 NAME 'automountMap' SUP top STRUCTURAL MUST ( automountMapName ) MAY description ) ( 1.3.6.1.1.1.2.17 NAME 'automount' SUP top STRUCTURAL DESC 'Automount information' MUST ( automountKey $ automountInformation ) MAY description ) ( 1.3.6.1.1.1.2.18 NAME 'groupOfMembers' SUP top STRUCTURAL DESC 'A group with members (DNs)' MUST cn MAY ( businessCategory $ seeAlso $ owner $ ou $ o $ description $ member ) ) Howard & Chu Expires February 10, 2010 [Page 15] Internet-Draft LDAP NameService Schema August 2009 5. Implementation Details 5.1. Suggested Resolution Methods The preferred means of directing a client application (one using the shared services of the C library) to use LDAP as its information source for the functions listed in Appendix B is to modify the source code to directly query LDAP. As the source to commercial C libraries and applications is rarely available to the end-user, one could emulate a supported nameservice (such as NIS). (This is also an appropriate opportunity to perform caching of entries across process address spaces.) In the case of NIS, reference implementations are widely available and the RPC interface is well known. The means by which the operating system is directed to use LDAP is implementation dependent. For example, some operating systems and C libraries support end-user extensible resolvers using dynamically loadable libraries and a nameservice "switch" (NSS). The means in which the DUA locates LDAP servers is also implementation dependent. 5.2. Interpreting User and Group Entries User and group resolution is initiated by the functions prefixed by getpw and getgr respectively. The uid attribute contains the user's login name. The cn attribute, in posixGroup entries, contains the group's name. This document preserves the use of the uid attribute even though, being a naming attribute, its syntax is case insensitive. This may cause a problem with existing deployments where there exist login names differing only in case. If DUAs support attribute mapping, a different attribute MAY be used to represent users' login names. The account object class provides a convenient structural class for posixAccount, and SHOULD be used where additional attributes are not required. Likewise, the groupOfMembers object class SHOULD be used for groups. (The groupOfUniqueNames object class is deprecated and SHOULD NOT be used.) It is suggested that uid and cn are used as the naming attribute for posixAccount and posixGroup entries, respectively. Group members may either be login names (values of memberUid) or distinguished names (values of member). In the latter case, the distinguished name must be mapped to one or more login names by examining the name's RDN or, if it is not distinguished by uid, performing a base search on the DN with a filter of "(objectclass=*)". DUAs MAY wish to cache DN to login name mappings. The DUA MAY traverse nested groups. An account's GECOS field is preferably determined by a value of the Howard & Chu Expires February 10, 2010 [Page 16] Internet-Draft LDAP NameService Schema August 2009 gecos attribute. If no gecos attribute exists, the value of the cn attribute MUST be used. (The existence of the gecos attribute allows information embedded in the GECOS field, such as a user's telephone number, to be returned to the client without overloading the cn attribute. It also accommodates directories where the common name does not contain the user's full name.) 5.2.1. Using Attribute Options Some posixAccount attributes may be accompanied by options (Section 2.2.2) identifying particular hosts or operating system types. The attribute with a hostos option matching the operating system of the DUA SHOULD be used in preference to an attribute without any associated options. The attribute with a host option matching the hostname of the DUA SHOULD be used in preference to any other attribute. 5.2.2. Authentication Considerations 5.2.2.1. Using Password Values When authenticating using a NIS to LDAP gateway or using NSS, a lookup is performed to retrieve the password attribute and the value is used in the DUA to authenticate a user. This approach to authentication is deprecated, as it requires that read access to the password attribute be granted across a network. An entry of class posixAccount, posixGroup, or shadowAccount without an authPassword or userPassword attribute MUST NOT be used for authentication. In this case the client SHOULD be returned a non- matchable password such as "x". If userPassword is used, its values MUST be represented by the following syntax: passwordvalue = schemeprefix hashedpasswd schemeprefix = "{" scheme "}" scheme = "crypt" / "md5" / "sha" / "ssha" / altscheme altscheme = "x-" keystring hashedpasswd = hashed password The hashed password contains a plaintext key hashed using the algorithm scheme. If the schema is "sha", the hashed password is the base64 encoding of the SHA-1 digest of the plaintext password. userPassword values which do not adhere to this syntax MUST NOT be used for authentication. The DUA MUST iterate through the values of the attribute until a value matching the above syntax is found. Only Howard & Chu Expires February 10, 2010 [Page 17] Internet-Draft LDAP NameService Schema August 2009 if hashedpassword is an empty string does the user have no password. DUAs are not required to consider hashing schemes which the client will not recognize; in most cases, it may be sufficient to consider only "crypt". DUA MAY use the authPassword attribute instead of userPassword, defined in [RFC3112]. The DUA MUST iterate the values of the authPassword attribute until a value whose scheme is CRYPT is found. The DUA MAY iterate through the values of the userPassword attribute, using the syntax defined here, until a value whose scheme is CRYPT is found. If no conforming value is found, the client MUST be returned a non-matchable password such as "x". Authentication using schemes other than CRYPT is, although advisable, beyond the scope of this document Below is an example of an authPassword attribute: authPassword: CRYPT$X5/DBrWPOQQaI Below is an example of a (deprecated) userPassword attribute: userPassword: {CRYPT}X5/DBrWPOQQaI A DUA MAY utilize the attributes in the shadowAccount class to provide shadow password service (getspnam() and getspent()). In such cases, the DUA MUST NOT make use of the userPassword attribute for getpwnam() et al, and MUST return a non-matchable password (such as "x") to the client instead. 5.2.2.2. Using LDAP Bind The preferred method for authenticating users with LDAP is to perform an LDAP Bind operation with the user's name and password. In this case the method the DSA uses to store and verify the password is completely internal to the DSA and not of any concern to the DUA. Likewise, using the shadowAccount attributes requires the DUA to handle password policy enforcement. However the policies expressed in the shadowAccount are limited in scope, and not uniformly applicable to all the systems that will be using LDAP. The preferred method is to leave password policy enforcement to the DSA, so that it will be uniformly enforced across all of the various systems that rely on the directory. This enforcement occurs implicitly when authenticating using LDAP Bind if the DSA supports the LDAP password policy [I-D.behera-ldap-password-policy] mechanisms. Howard & Chu Expires February 10, 2010 [Page 18] Internet-Draft LDAP NameService Schema August 2009 The means in which authentication in the DUA is configured is implementation dependent. Typically it is accomplished using [PAM]. Further details of authentication are beyond the scope of this document. 5.2.3. Naming Considerations On UNIX systems, users and groups reside in separate name spaces and it is common for the same name to be used by both a user and a group. Since they are in separate name spaces there is no ambiguity and no conflict. However, when integrating a name service into LDAP the directory may be used with other systems besides UNIX and its derivatives. In particular, the Microsoft Windows operating system may also use LDAP for its own name service. In Windows, users and groups reside in a single name space and so one cannot use the same name for both a user and a group. Conflicts in naming conventions may arise in other deployments as well, and should be carefully taken into account when migrating from other naming services into LDAP. 5.3. Interpreting Hosts and Networks The ipHostNumber and ipNetworkNumber attributes are defined in preference to dNSRecord (defined in [RFC1279]), in order to simplify the DUA's role in interpreting entries in the directory. A dNSRecord expresses a complete resource record, including time to live and class data, which is extraneous to this schema. Additionally, the ipHost and ipNetwork classes permit a host or network (respectively) and all its aliases to be represented by a single entry in the directory. This is not necessarily possible if a DNS resource record is mapped directly to an LDAP entry. Implementations that wish to use LDAP to master DNS zone information are not precluded from doing so, and may simply avoid the ipHost and ipNetwork classes. This document redefines, although not exclusively, the ipNetwork class defined in [RFC1279], in order to achieve consistent naming with ipHost. The ipNetworkNumber attribute is also used in the siteContact object class [ROSE]. The authPassword and userPassword attributes are included in ipHost such that hosts MAY be treated as authentication principals. The treatment of these attributes and inherent caveats considered in Section 5.2 apply here also. The trailing zeros in a network address MUST be omitted. CIDR-style Howard & Chu Expires February 10, 2010 [Page 19] Internet-Draft LDAP NameService Schema August 2009 network addresses (eg. 192.168.1/24) MAY be used. Leading zeros MUST be removed from all components of an IPv6 address string as defined by [RFC2373], section 2.2, item 1. The IPv6 address string MUST be further normalized by following the "::" syntax as defined in [RFC2373], section 2.2, item 2. In addition, "::" MUST be used to replace the longest string of zero bits. If there are two or more longest strings of zero bits, then the first string MUST be replaced. In addition, the syntax defined by [RFC2373], section 2.2, item 3 MUST NOT be used. IPv4 addresses MUST be represented by the IPv4 dotted decimal string syntax. For example the following address: 1080:0000:0:0:08:800:200C:417A FF01:0:0:0:0:0:01 0:0:0:0:0:0:0:0001 0:0:0:0:0:0:0:0 MUST be normalized as: 1080::8:800:200C:417A FF01::101 0::1 :: 5.4. Interpreting Other Entities In general, a one-to-one mapping between entities and LDAP entries is proposed, in that each entity has exactly one representation in the DIT. In some cases this is not feasible; for example, a service which is represented in more than one protocol domain. Consider the following entry: dn: cn=domain,ou=services,dc=aja,dc=com objectClass: top objectClass: ipService cn: domain cn: nameserver ipServicePort: 53 ipServiceProtocol: tcp ipServiceProtocol: udp This entry MUST map to the following two (2) services entities: domain 53/tcp nameserver domain 53/udp nameserver While the above two entities may be represented as separate LDAP Howard & Chu Expires February 10, 2010 [Page 20] Internet-Draft LDAP NameService Schema August 2009 entities, with different distinguished names (such as cn=domain+ ipServiceProtocol=tcp, ... and cn=domain+ipServiceProtocol=udp, ...) it is convenient to represent them as a single entry. If a service is represented in multiple protocol domains with different ports, then multiple entries are required; multi-valued RDNs MAY be used to distinguish them.) With the exception of authPassword and userPassword values, empty values (consisting of a zero length string) are returned by the DUA to the client. The DUA MUST reject any entries which do not conform to the schema (missing mandatory attributes). Non-conforming entries SHOULD be ignored while enumerating entries. The nisDomainObject object class is provided to associate a NIS domain with a naming context. A DUA would retrieve the NIS domain name from a configuration file and enumerate the naming contexts served by an LDAP server, searching each naming context for (nisDomain=%s). The first matching entry that is found MAY be used as a search base for configuration profile information or for entries themselves. For example, the following example shows an association between the NIS domain "nis.aja.com" and the naming context "dc=aja,dc=com": dn: dc=aja,dc=com objectClass: top objectClass: domain objectClass: nisDomainObject dc: aja nisDomain: nis.aja.com The nisObject object class MAY be used as a generic means of representing NIS entities. Its use is not encouraged; where support for entities not described in this schema is desired, an appropriate schema should be devised. Implementers are strongly advised to support end-user extensible mappings between NIS entities and object classes. (Where the nisObject class is used, the nisMapName attribute MAY be used as a RDN.) The nisObject class might be used to represent automount information. 5.5. Canonicalizing entries with multi-valued naming attributes For entities such as hosts, services, networks, protocols, and RPCs, where there may be one or more aliases, the respective entry's relative distinguished name SHOULD be used to determine the canonical name. Any other values for the same attribute are used as aliases. For example, the service described in Section 5.4 has the canonical name "domain" and exactly one alias, "nameserver". Howard & Chu Expires February 10, 2010 [Page 21] Internet-Draft LDAP NameService Schema August 2009 The schema in this document generally only defines one attribute per class which is suitable for distinguishing an entity (excluding any attributes with integer syntax; it is assumed that entries will be distinguished on name). Usually, this is the common name (cn) attribute. This aids the DUA in determining the canonical name of an entity, as it can examine the value of the relative distinguished name. Aliases are thus any values of the distinguishing attribute (such as cn) which do not match the canonical name of the entity. In the event that a different attribute is used to distinguish the entry, as may be the case where these object classes are used as auxiliary classes, the entry's canonical name may not be present in the RDN. In this case, the DUA MUST choose one of the non- distinguished values to represent the entity's canonical name. As the directory server guarantees no ordering of attribute values, it may not be possible to distinguish an entry deterministically. This ambiguity SHOULD NOT be resolved by mapping one directory entry into multiple entities. Howard & Chu Expires February 10, 2010 [Page 22] Internet-Draft LDAP NameService Schema August 2009 6. Implementation Focus Gateways between NIS and LDAP have been developed by PADL Software and Sun Microsystems. They both support this schema. An open source implementation of the C library resolution code has been written and is available from PADL Software. It supports C libraries on GNU, BSD, AIX, and Solaris operating systems. PADL have also made available a set of scripts for migrating flat files into a form suitable for loading into an LDAP server. Another open source implementation of the C library code is available from the OpenLDAP Project. Howard & Chu Expires February 10, 2010 [Page 23] Internet-Draft LDAP NameService Schema August 2009 7. Security Considerations The entirety of related security considerations are outside the scope of this document. It is noted that making passwords encrypted with a widely understood hash function (such as crypt()) available to non- privileged users is dangerous because it exposes them to dictionary and brute-force attacks. This is proposed only for compatibility with existing UNIX system implementations. Sites where security is critical SHOULD consider using a strong authentication service for user authentication. Alternatively, the encrypted password could be made available only to a subset of privileged DUAs, which would provide "shadow" password service to client applications. This may be difficult to enforce. Because the schema represents operating system-level entities, access to these entities SHOULD be granted on a discretionary basis. (There is little point in restricting access to data which will be republished without restriction, however.) It is particularly important that only administrators can modify entries defined in this schema, with the exception of allowing a principal to change their password (which MAY be done on behalf of the user by a client bound as a superior principal, such that password restrictions MAY be enforced). For example, if a user were allowed to change the value of their uidNumber attribute, they could subvert security by equivalencing their account with the superuser account. A subtree of the DIT which is to be republished by a DUA (such as a NIS gateway) SHOULD be within the same administrative domain that the republishing DUA represents. (For example, principals outside an organization, while conceivably part of the DIT, should not be considered with the same degree of authority as those within the organization.) Finally, care should be exercised with integer attributes of a sensitive nature (particularly the uidNumber and gidNumber attributes) which contain zero-length values. DUAs MAY treat such values as corresponding to the "nobody" or "nogroup" user and group, respectively. Howard & Chu Expires February 10, 2010 [Page 24] Internet-Draft LDAP NameService Schema August 2009 8. Acknowledgements Thanks to Bob Joslin of the Hewlett Packard Company, and to all those that helped with this document's predecessor, RFC 2307. UNIX is a registered trademark of The Open Group. Howard & Chu Expires February 10, 2010 [Page 25] Internet-Draft LDAP NameService Schema August 2009 9. References [RFC1034] Mockapetris, P., "Domain names - concepts and facilities", STD 13, RFC 1034, November 1987. [RFC1057] Sun Microsystems, Inc., "RPC: Remote Procedure Call Protocol specification: Version 2", RFC 1057, June 1988. [RFC1279] Hardcastle-Kille, S., "X.500 and Domains", RFC 1279, November 1991. [RFC2373] Hinden, R. and S. Deering, "IP Version 6 Addressing Architecture", RFC 2373, July 1998. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC4511] Sermersheim, J., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006. [RFC4515] Smith, M. and T. Howes, "Lightweight Directory Access Protocol (LDAP): String Representation of Search Filters", RFC 4515, June 2006. [RFC4519] Sciberras, A., "Lightweight Directory Access Protocol (LDAP): Schema for User Applications", RFC 4519, June 2006. [RFC3112] Zeilenga, K., "LDAP Authentication Password Schema", RFC 3112, May 2001. [I-D.behera-ldap-password-policy] Sermersheim, J., Poitou, L., and H. Chu, "Password Policy for LDAP Directories", draft-behera-ldap-password-policy-10 (work in progress), August 2009. [ROSE] Rose, M., "The Little Black Book: Mail Bonding with OSI Directory Services", ISBN 0-13-683210-5, 2001. [X.500] ISO/IEC JTC 1/SC21, "Information Processing Systems - Open Systems Interconnection - The Directory: Overview of Concepts, Models and Service", 1988. [UNIX] Institute of Electrical and Electronics Engineers and The Open Group, "IEEE Std 1003.1, 2004 Edition, Single UNIX Specification Version 3", IEEE Standard 1003.1, 2004. Howard & Chu Expires February 10, 2010 [Page 26] Internet-Draft LDAP NameService Schema August 2009 [PAM] Samar, V. and R. Schemers, "Unified Login with Pluggable Authentication Modules (PAM)", OSF RFC 86.0, October 1995. Howard & Chu Expires February 10, 2010 [Page 27] Internet-Draft LDAP NameService Schema August 2009 Appendix A. Example Entries The examples described in this section are provided to illustrate the schema described in this draft. They are not meant to be exhaustive. The following entry is an example of the posixAccount class: dn: uid=lester,ou=people,dc=aja,dc=com objectClass: top objectClass: account objectClass: posixAccount uid: lester cn: Lester the Nightfly gecos: Lester uidNumber: 10 gidNumber: 10 loginShell: /bin/csh userPassword: {crypt}$X5/DBrWPOQQaI homeDirectory: /home/lester This corresponds to the UNIX system password file entry: lester:X5/DBrWPOQQaI:10:10:Lester:/home/lester:/bin/sh The following entry is an example of the ipHost class: dn: cn=josie.aja.com,ou=hosts,dc=aja,dc=com objectClass: top objectClass: device objectClass: ipHost objectClass: bootableDevice objectClass: ieee802Device cn: josie.aja.com cn: www.aja.com ipHostNumber: 10.0.0.1 macAddress: 00:00:92:90:ee:e2 bootFile: mach bootParameter: root=dan.aja.com:/nfsroot/peg bootParameter: swap=dan.aja.com:/nfsswap/peg bootParameter: dump=dan.aja.com:/nfsdump/peg This entry represents the host canonically josie.aja.com, also known as www.aja.com. The Ethernet address and four boot parameters are also specified. An example of the nisNetgroup class: Howard & Chu Expires February 10, 2010 [Page 28] Internet-Draft LDAP NameService Schema August 2009 dn: cn=nightfly,ou=netgroup,dc=aja,dc=com objectClass: top objectClass: nisNetgroup cn: nightfly nisNetgroupTriple: (charlemagne,peg,dunes.aja.com) nisNetgroupTriple: (lester,-,) memberNisNetgroup: kamakiriad This entry represents the netgroup nightfly, which contains two triples (the user charlemagne, the host peg, and the domain dunes.aja.com; and, the user lester, no host, and any domain) and one netgroup (kamakiriad). Finally, an example of the nisObject class: dn: nisMapName=tracks,dc=dunes,dc=aja,dc=com objectClass: top objectClass: nisMap nisMapName: tracks dn: cn=Maxine,nisMapName=tracks,dc=dunes,dc=aja,dc=com objectClass: top objectClass: nisObject cn: Maxine nisMapName: tracks nisMapEntry: Nightfly$4 This represents the NIS map tracks, and a single map entry. Howard & Chu Expires February 10, 2010 [Page 29] Internet-Draft LDAP NameService Schema August 2009 Appendix B. Affected Library Functions The following functions are typically found in the C libraries of most UNIX and POSIX compliant systems [UNIX]. An LDAP search filter string [RFC4515] which may be used to satisfy the function call is included alongside each function name. Parameters are denoted by %s and %d for string and integer arguments, respectively. Long lines are broken: getpwnam() (&(objectClass=posixAccount)(uid=%s)) getpwuid() (&(objectClass=posixAccount)(uidNumber=%d)) getpwent() (objectClass=posixAccount) getspnam() (&(objectClass=shadowAccount)(uid=%s)) getspent() (objectClass=shadowAccount) getgrnam() (&(objectClass=posixGroup)(cn=%s)) getgrgid() (&(objectClass=posixGroup)(gidNumber=%d)) getgrent() (objectClass=posixGroup) getservbyname() (&(objectClass=ipService)(cn=%s) (ipServiceProtocol=%s)) getservbyport() (&(objectClass=ipService)(ipServicePort=%d) (ipServiceProtocol=%s)) getservent() (objectClass=ipService) getrpcbyname() (&(objectClass=oncRpc)(cn=%s)) getrpcbynumber() (&(objectClass=oncRpc)(oncRpcNumber=%d)) getrpcent() (objectClass=oncRpc) getprotobyname() (&(objectClass=ipProtocol)(cn=%s)) getprotobynumber() (&(objectClass=ipProtocol) (ipProtocolNumber=%d)) getprotoent() (objectClass=ipProtocol) gethostbyname() (&(objectClass=ipHost)(cn=%s)) gethostbyaddr() (&(objectClass=ipHost)(ipHostNumber=%s)) gethostent() (objectClass=ipHost) getnetbyname() (&(objectClass=ipNetwork)(cn=%s)) getnetbyaddr() (&(objectClass=ipNetwork)(ipNetworkNumber=%s)) getnetent() (objectClass=ipNetwork) setnetgrent() (&(objectClass=nisNetgroup)(cn=%s)) getpublickey() (&(objectClass=nisKeyObject)(...)) Howard & Chu Expires February 10, 2010 [Page 30] Internet-Draft LDAP NameService Schema August 2009 Appendix C. Suggested DIT structure The cn attribute is typically used to name entities. The ipHostNumber, ipNetworkNumber, and ipServiceProtocol attributes are also naming attributes, such that multi-valued RDNs may be used to distinguish between, for example, different interfaces of a multihomed host. The following DIT structure MAY be used for deploying this schema. It is not required that DC-naming be used, but it is encouraged: Naming context ObjectClass ============================================================ ou=people,dc=... posixAccount shadowAcount ou=group,dc=... posixGroup ou=services,dc=... ipService ou=protocols,dc=... ipProtocol ou=rpc,dc=... oncRpc ou=hosts,dc=... ipHost ou=ethers,dc=... ieee802Device bootableDevice ou=networks,dc=... ipNetwork ou=netgroup,dc=... nisNetgroup nisMapName=...,dc=... nisObject automountMapName=...,dc=... automountMap Howard & Chu Expires February 10, 2010 [Page 31] Internet-Draft LDAP NameService Schema August 2009 Authors' Addresses Luke Howard PADL Software Pty. Ltd. PO Box 59 Central Park, Vic 3145 AU Email: lukeh@padl.com Howard Chu (editor) Symas Corp. 18740 Oxnard Street, Suite 313A Tarzana, California 91356 US Phone: +1 818 757-7087 Email: hyc@symas.com Howard & Chu Expires February 10, 2010 [Page 32] PK /�c\[���j �j L doc/alt-openldap11-devel/drafts/draft-zeilenga-ldap-c-api-concurrency-xx.txtnu �[��� INTERNET-DRAFT Kurt D. Zeilenga Intended Category: Standards Track OpenLDAP Foundation Extends: draft-ietf-ldapext-ldap-c-api-03.txt Expires: 28 March 2000 28 September 1999 LDAP C API Concurrency Extensions <draft-zeilenga-ldap-c-api-concurrency-00.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. This draft document will be submitted to the RFC Editor as a Standards Track document. Distribution of this memo is unlimited. Technical discussion of this document will take place on the IETF LDAP Extension Working Group mailing list <ietf-ldapext@netscape.com>. Please send editorial comments directly to the author <Kurt@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 1999, The Internet Society. All Rights Reserved. Please see the Copyright section near the end of this document for more information. 2. Abstract This document defines extensions to the LDAP C API to support use in concurrent execution environments. The document describes and defines Zeilenga [Page 1] INTERNET-DRAFT LDAP C API Concurrency Extensions 28 September 1999 requirements for multiple concurrency levels: thread safe, session thread safe, and operation thread safe. 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 [KEYW]. 3. Introduction This document extends the LDAP C API [CAPI] specification to support use in concurrent execution environments. The extensions add powerful concurrent processing capabilities to the simple to use CAPI. This document provides an overview of different levels of concurrent execution support and offers a number of CAPI "features" to provide capabilities at these levels. The remainder of this section describes three levels of concurrent execution: thread safe, session thread safe, operation thread safe APIs. 3.1. Thread Safe An implementation which allows applications to safely execute in concurrent execution environments where the application provides necessary synchronization to ensure serialization of CAPI usage is considered to be "thread safe." Applications may execute non-CAPI calls in concurrent execution contexts when using thread safe implementations. 3.2. Session Thread Safe A "thread safe" implementation which allows CAPI calls associated with different LDAP sessions to proceed asychronously is considered to be "session thread safe." 3.3. Operation Thread Safe A "session thread safe" implementation which allows CAPI calls associated with different LDAP operations to proceed asychronously is considered to be "operation thread safe". 4. Basic Thread Safe Feature Zeilenga [Page 2] INTERNET-DRAFT LDAP C API Concurrency Extensions 28 September 1999 This section details requirements for the thread safe CAPI feature. Implementations fulfilling these requirements are said to support the LDAP_API_FEATURE_THREAD_SAFE feature and SHOULD advertise this support as detailed below. This feature SHOULD be provided by implementations. Implementations of this feature MUST implement the LDAP error handling extension [ERRNO]. Implementations of this feature MUST allow non-CAPI calls to proceed asynchronously. Implementations of this feature MUST NOT use any non-thread safe call or mechanism provided by C environment or operating system. An example of non-reentrant calls is the UNIX strtok() function. Example of a non-reentrant mechanism is global (i.e.: non-thread specific) errno. 5. Session Thread Safe Feature This section details requirements for the session thread safe CAPI feature. Implementations fulfilling these requirements are said to support the LDAP_API_FEATURE_SESSION_THREAD_SAFE feature and SHOULD advertise this support as detailed below. This feature is RECOMMENDED. 5.1. Prerequisite Features Implementations providing this feature MUST provide and advertise both LDAP_API_FEATURE_CONTEXT_SPECIFIC_ERRNO [ERRNO] and LDAP_API_FEATURE_THREAD_SAFE. 5.2. Atomic Session Handles Implementations providing this feature SHOULD ensure that operations upon a given session handle are atomic. Implementations which provide atomic session handles SHOULD advertise the feature LDAP_API_FEATURE_ATOMIC_SESSION_HANDLES. 5.3. Concurrency Requirements Implementations providing this feature MUST not restrict CAPI calls acting upon a given LDAP session to a particular execution context. Applications MAY use a session handle on any thread. Applications Zeilenga [Page 3] INTERNET-DRAFT LDAP C API Concurrency Extensions 28 September 1999 MUST NOT assume that operations upon a session are atomic. Implementations providing this feature MUST allow CAPI calls acting upon different LDAP sessions to safely proceed asynchronously. Implementations providing this feature MUST allow CAPI calls not acting upon an LDAP session to safely proceed asynchronously. 6. Operation Thread Safe Feature This section details requirements for the operation thread safe CAPI feature based upon a duplicate session handles mechanism. Implementations fulfilling these requirements are said to support the LDAP_API_FEATURE_DUPLICATE_SESSION_HANDLES feature and SHOULD advertise this support as detailed below. This feature is OPTIONAL. 6.1. Prerequisite Features Implementations of this feature MUST provide and advertise LDAP_API_FEATURE_CONTEXT_SPECIFIC_ERRNO [ERRNO], LDAP_API_FEATURE_THREAD_SAFE, LDAP_API_FEATURE_SESSION_THREAD_SAFE, and LDAP_API_FEATURE_ATOMIC_SESSION_HANDLES. 6.2. Duplicated Session Handles Implementations of this feature MUST support duplicated session handles. As defined in CAPI, a session handle refers to an LDAP session encompassing connections with one or more servers, associated message results, a set of properties (options), and state information. This feature provides a mechanism for a handle to be duplicated. A session handle and its duplicates are considered siblings. Each sibling session handle refers to the same LDAP session and message results. Some properties and state are specific to a handle and others shared between siblings as detailed below. CAPI calls made on a handle are atomic. Calls made on sibling (or other) handles MAY proceed asynchronously. Session handles are duplicated using ldap_dup() and destroyed using ldap_destroy(). Use of duplicated session handles with CAPI calls have the following semantics detailed in the sections below. Zeilenga [Page 4] INTERNET-DRAFT LDAP C API Concurrency Extensions 28 September 1999 6.2.1. Creating and Destroying duplicated sessions Implementations of this feature are required to provide two new routines: LDAP *ldap_dup( ld ); int ldap_destroy( ld ); Parameters are: ld The session handle The ldap_dup() function returns a duplicate of a session handle. The returned session handle may be used concurrently with the original session handle as described below. ldap_dup returns NULL if it is not able to duplicate the session handle and sets LDAP_OPT_ERROR_NUMBER and ldap_errno indicating the nature of the failure. The ldap_destroy() function destroys the session handle. If the session handle has no siblings, ldap_destroy behaves exactly like ldap_unbind. If the session handle has siblings, the resources assocated with the handle are released and the siblings remain valid. ldap_destroy() returns LDAP_SUCCESS or an error number indicating the nature of failure. Regardless of returned value, the handle SHOULD be considered invalid and MUST not be used in subsequent calls. Attempts to use a destroyed session handle MUST NOT result in LDAP_INVALID_SESSION error being reported. Implementations SHOULD report LDAP_PARAM_ERROR in such cases. 6.2.2. ldap_unbind and siblings When ldap_unbind() is called on a session handle with siblings, the siblings become invalid. The siblings must be destroyed using ldap_destroy(). All attempts to obtain the siblings' LDAP_OPT_ERROR_NUMBER will return LDAP_INVALID_SESSION. Any use other than ldap_destroy() or reading LDAP_OPT_ERROR_NUMBER will fail with an LDAP_INVALID_SESSION error being reported. 6.2.3. ldap_result() Message queues are shared between siblings. Results of operations on a duplicated session handles are accessible to all sibling session handles. Applications desiring results associated with a specific operation SHOULD provide the appropriate msgid to ldap_result(). Applications SHOULD avoid calling ldap_result() with LDAP_RES_ANY as such may "steal" and return results which an operation on a sibling requires to complete. Zeilenga [Page 5] INTERNET-DRAFT LDAP C API Concurrency Extensions 28 September 1999 6.2.4. Session Options The following CAPI options access values shared between siblings: LDAP_OPT_API_INFO LDAP_OPT_DESC LDAP_OPT_REFERRALS LDAP_OPT_PROTOCOL_VERSION LDAP_OPT_API_FEATURE_INFO LDAP_OPT_HOST_NAME The following CAPI options access values specific to a sibling: LDAP_OPT_DEREF LDAP_OPT_SIZELIMIT LDAP_OPT_TIMELIMIT LDAP_OPT_RESTART LDAP_OPT_CLIENT_CONTROLS LDAP_OPT_SERVER_CONTROLS LDAP_OPT_ERROR_NUMBER LDAP_OPT_ERROR_STRING LDAP_OPT_MATCHED_DN 6.2.4.1. LDAP_OPT_SESSION_REFCNT In addition, implementations MUST provide the READ-ONLY, shared LDAP_OPT_SESSION_REFCNT option. LDAP_OPT_SESSION_REFCNT returns the reference count associated with the supplied session handle argument. The session handle argument is required. The outvalue argument should be a pointer to an integer. Example use: int refcount(LDAP *ld) { #ifdef LDAP_OPT_SESSION_REFCNT if(ld != NULL) { int refcnt, rc; rc = ldap_get_option(ld, LDAP_OPT_SESSION_REFCNT, &refcnt); if(rc == LDAP_OPT_SUCCESS) { return refcnt; } } #endif return -1; } 7. Advertising Features This document REQUIRES that supported features with the name in the form LDAP_API_FEATURE_x be advertised to consumers of the CAPI as Zeilenga [Page 6] INTERNET-DRAFT LDAP C API Concurrency Extensions 28 September 1999 follows: SHOULD provide the macro LDAP_API_FEATURE_x with the value of 1000 + revision number of this draft (i.e.: 1000+0 for this 0 revision of the draft). MUST provide the CAPI extension "x" when returning API information upon LDAP_OPT_API_INFO option access, and MUST provide feature info for "x" via LDAP_OPT_FEATURE_INFO option mechanism. The feature version provided MUST match the value LDAP_API_FEATURE_x macro where x is replaced appropriately. As implementations may not provide macros for all features, applications SHOULD use LDAP_OPT_API_INFO to determine which features are provided by a given implementation. 8. Changes to the C API specification 8.1. New Symbols This extension introduces the following macros: LDAP_API_FEATURE_ATOMIC_SESSION_HANDLES LDAP_API_FEATURE_DUPLICATE_SESSION_HANDLES LDAP_API_FEATURE_SESSION_THREAD_SAFE LDAP_API_FEATURE_THREAD_SAFE LDAP_API_FEATURE_OPERATION_THREAD_SAFE LDAP_INVALID_SESSION LDAP_OPT_SESSION_REFCNT This extension introduces these new functions: ldap_destroy() ldap_dup() This extension introduces no new typedefs nor structure names. 8.2. Duplicated Session Handles This extension introduces duplicated session handles and requirements for handling duplicated session handles. Semantics of non-duplicated session handles are not affected by this introduction. However, the semantics of calls upon duplicate session handles differs as described in the extension. Zeilenga [Page 7] INTERNET-DRAFT LDAP C API Concurrency Extensions 28 September 1999 9. Security Considerations None taken, none given. 10. Copyright Copyright 1999, The Internet Society. 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 AUTHORS, 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. 11. Bibliography [CAPI] M. Smith, T. Howes, A. Herron, M. Wahl, A. Anantha, "The C LDAP Application Program Interface", INTERNET-DRAFT, <draft- ietf-ldapext-ldap-c-api-03.txt> + LDAPext discussions, June 1999. [ERRNO] K. Zeilenga, "LDAP C API Error Reporting Extension", INTERNET-DRAFT, <draft-zeilenga-ldap-c-api-errno-00.txt>, June 1999. [KEYW] S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, March 1997. Zeilenga [Page 8] INTERNET-DRAFT LDAP C API Concurrency Extensions 28 September 1999 [LDAP] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. 13. Author's Address Kurt D. Zeilenga OpenLDAP Foundation <Kurt@OpenLDAP.org> This document expires on 28 March 2000. Zeilenga [Page 9] --------------------------------------------------------------------- INTERNET-DRAFT Kurt D. Zeilenga Intended Category: Standards Track OpenLDAP Foundation Extends: draft-ietf-ldapext-ldap-c-api-03.txt Expires: 28 March 2000 28 September 1999 LDAP C API Error Reporting Extension <draft-zeilenga-ldap-c-api-errno-00.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. This draft document will be submitted to the RFC Editor as a Standards Track document. Distribution of this memo is unlimited. Technical discussion of this document will take place on the IETF LDAP Extension Working Group mailing list <ietf-ldapext@netscape.com>. Please send editorial comments directly to the author <Kurt@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 1999, The Internet Society. All Rights Reserved. Please see the Copyright section near the end of this document for more information. 2. Abstract This document defines a manatory extension to the LDAP C API to provide error reporting for all API calls. The mechanism is nonintrusive and can, optionally, support concurrent execution environments. Zeilenga [Page 1] INTERNET-DRAFT LDAP C API Error Reporting Extension 28 September 1999 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 [KEYW]. 3. Background and Intent of Use The LDAP [LDAP] C API [CAPI] provides an interface which (due to legacy compatibiity issues) does not provide a consistent mechanism for reporting errors. A large number of the calls within the specification have no mechanism to indicate the nature of a failure. The usefulness of a CAPI without a consistent, easy to use, error reporting mechanism is limited. This document defines an mandatory extension to the CAPI. All implementations of the CAPI MUST provide this extension. The extension details additional requirements for error reporting. Implementations MUST fulfill all other CAPI error reporting requirements. 4. Error Handling Extension This extension provides a mechanism that applications MAY use to obtain an LDAP error number indicating the nature of the failure associated with the last failed CAPI call. Implementations MUST provide access to an LDAP error number (CAPI, Section 9) resulting from the last failed CAPI call via the symbol ldap_errno. The last failed CAPI call may be within the global context or within the current execution context. The ldap_errno MUST evaluate to a modifiable lvalue that has type 'int', the value of which is set to a LDAP error number. It is unspecified whether ldap_errno is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual object, or a program defines an identifier with the name ldap_errno, the behavior is undefined. Applications MUST access ldap_errno within the same concurrent execution context, commonly a thread, in which the failure occurred. The value of ldap_errno is LDAP_SUCCESS (0) if no API failure has occurred within the supported context and the user has not assigned a value within the supported context. Zeilenga [Page 2] INTERNET-DRAFT LDAP C API Error Reporting Extension 28 September 1999 Implementations SHALL NOT update the ldap_errno value upon successful CAPI call completion. Implementations providing a current execution context specific ldap_errno MUST advertise the feature LDAP_API_CONTEXT_SPECIFIC_ERRNO as described in Section 6. Implementation of LDAP_API_CONTEXT_SPECIFIC_ERRNO is RECOMMENDED. 4.1. Reporting Server Errors It is not a CAPI failure for a server to return an error number. Implementations SHALL NOT assign error results returned by servers to ldap_errno. 4.2. Implementation Specific Reporting The CAPI specification stated that the caller may obtain an indication of failure of certain calls (see listed below) using implementation specific and/or operating system specific requirements. Implementations are NOT REQUIRED to support any implementation specific and/or operating system mechanism for ANY call detailed by the CAPI specification or its extensions. Affected calls include ldap_init(), ldap_open(), and ber_*(). 4.3. Example The following is an example showing how an application may obtain the error information resulting from a failed CAPI calls: int msgid; LDAP *ld = ldap_init("localhost", 389); if(ld == NULL) { printf("ldap_init failed, ldap_errno=%d (%s)\n", ldap_errno, ldap_err2string(ldap_errno)); printf("unable to initialize LDAP session\n"); return -1; } msgid = ldap_simple_bind(ld, NULL, NULL); if(msgid == -1) { int err = ldap_errno; if (err != LDAP_SUCCESS ) { Zeilenga [Page 3] INTERNET-DRAFT LDAP C API Error Reporting Extension 28 September 1999 /* API failure */ printf("ldap_simple_bind failure: ldap_errno=%d (%s)\n", err, ldap_err2string(err)); } else { int lderr, rc; printf("ldap_simple_bind failed\n"); rc = ldap_get_option(ld, LDAP_OPT_ERROR_NUMBER, &lderr); if(rc == LDAP_OPT_SUCCESS) { printf(" reason=%d (%s)\n", lderr, ldap_err2string(lderr)); } else { printf("ldap_get_option failed, ldap_errno=%d (%s)\n", ldap_errno, ldap_err2string(ldap_errno)); } } goto unbind; } /* ... */ unbind: if(ldap_unbind(ld) != 0) { printf("ldap_unbind failed, ldap_errno=%d (%s)\n", ldap_errno, ldap_error2str(ldap_errno)); return -1; } return 0; 5. Advertising Features This document REQUIRES that supported features with the name in the form LDAP_API_FEATURE_x be advertised to consumers of the CAPI as follows: SHOULD provide the macro LDAP_API_FEATURE_x with the value of 1000 + revision number of this draft (i.e.: 1000+0 for this 0 revision of the draft). MUST provide the CAPI extension "x" when returning API information upon LDAP_OPT_API_INFO option access, and Zeilenga [Page 4] INTERNET-DRAFT LDAP C API Error Reporting Extension 28 September 1999 MUST provide feature info for "x" via LDAP_OPT_FEATURE_INFO option mechanism. The feature version provided MUST match the value LDAP_API_FEATURE_x macro where x is replaced appropriately. As implementations may not provide macros for all features, applications SHOULD use LDAP_OPT_API_INFO to determine which features are provided by a given implementation. 6. Changes to the LDAP C API This section provides a summary of changes to the CAPI specification. 6.1. LDAP_API_VERSION LDAP_API_VERSION should be set to the RFC number of this extension if and when it is published as a Standards Track RFC. (see purpose of this draft above). Until such time as this document is published as an RFC, implementations should use the value specified by CAPI plus 100 + 10 * the number of this draft. For the third draft of CAPI and this 0 revision of draft, the value of 2103 ((2000+3) + (100+10*0)) should be used. 6.2. New Symbols This extension introduces two new symbols: LDAP_API_FEATURE_CONTEXT_SPECIFIC_ERRNO ldap_errno LDAP_API_FEATURE_CONTEXT_SPECIFIC_ERRNO is a macro. ldap_errno MAY be a MACRO. This extension indroductes no new functions, typedefs, or structure names. 6.3. Implementation/System Specific Error Handling This extensions removes any requirements that implementations to use implementation and/or operating system specific error reporting mechanisms. Zeilenga [Page 5] INTERNET-DRAFT LDAP C API Error Reporting Extension 28 September 1999 7. Security Considerations None taken, none given. 8. Copyright Copyright 1999, The Internet Society. 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 AUTHORS, 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. 9. Bibliography [CAPI] M. Smith, T. Howes, A. Herron, M. Wahl, A. Anantha, "The C LDAP Application Program Interface", INTERNET-DRAFT, <draft-ietf-ldapext-ldap-c-api-03.txt> + LDAPext discussions, June 1999. [KEYW] S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, March 1997. [LDAP] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. Zeilenga [Page 6] INTERNET-DRAFT LDAP C API Error Reporting Extension 28 September 1999 10. Author's Address Kurt D. Zeilenga OpenLDAP Foundation <Kurt@OpenLDAP.org> This document expires on 28 March 2000. Zeilenga [Page 7] PK /�c\�-M�= �= F doc/alt-openldap11-devel/drafts/draft-sermersheim-ldap-chaining-xx.txtnu �[��� Internet Draft J. Sermersheim Personal Submission R. Harrison Intended Category: Standard Track Novell, Inc Document: draft-sermersheim-ldap-chaining-02.txt Feb 2004 LDAP Control to Specify Chaining Behavior 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. Technical discussion of this document will take place on the IETF LDAP Extensions Working Group mailing list <ldapext@ietf.org>. Editorial comments may be sent to the author <jimse@novell.com>. Abstract This document describes a Lightweight Directory Access Protocol (LDAP) request control that allows specification of chaining behavior for LDAP operations. By using the control with various LDAP operations, a directory client (DUA), or directory server (DSA) specifies whether or not a DSA or secondary DSA chains operations to other DSAs or returns referrals and/or search result references to the client. 1. Introduction Many directory servers have the ability through the use of various mechanisms to participate in a distributed directory model. A distributed directory is one where the DIT is distributed over multiple DSAs. One operation completion mechanism used by DSAs in a distributed directory is chaining. Chaining is defined in [X.518], and is the act of one DSA communicating a directory operation that Sermersheim, Harrison Internet-Draft - Exp. Aug 2004 Page 1 LDAP Control to Specify Chaining Behavior originated from a DUA to another DSA in a distributed directory. Contrast this with the act of passing referrals (4.1.11 of [RFC2251]) and SearchResultReferences (4.5.2 of [RFC2251]) back to the client. Chaining may happen during the name resolution part of an operation or during other parts of operations like search which apply to a number of entries in a subtree. This document does not attempt to define the distributed directory model, nor does it attempt to define the manner in which DSAs chain requests. This document defines a request control that the client can use to specify whether parts of an operation should or should not be chained. 2. Conventions The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" used in this document carry the meanings described in [RFC2119]. The term chaining may apply to uni-chaining as well as multi-chaining (see [X.518]) depending on the capabilities and configuration of the DSAs. 3. The Control Support for the control is advertised by the presence of its controlType in the supportedControl attribute of a server's root DSE. This control MAY be included in any LDAP request operation except abandon, unbind, and StartTLS as part of the controls field of the LDAPMessage, as defined in Section 4.1.12 of [RFC2251]: The controlType is set to <IANA-ASSIGNED-OID.1>. The criticality MAY be set to either TRUE or FALSE. The controlValue is an OCTET STRING, whose value is the following ChainingBehavior type, BER encoded following the rules in Section 5.1 of [RFC2251]: ChainingBehavior ::= SEQUENCE { resolveBehavior Behavior OPTIONAL, continuationBehavior Behavior OPTIONAL } Behavior :: = ENUMERATED { chainingPreferred (0), chainingRequired (1), referralsPreferred (2), referralsRequired (3) } resolveBehavior instructs the DSA what to do when a referral is encountered during the local name resolution part of an operation. If this field is not specified, other policy dictates the DSA's behavior. Sermersheim, Harrison Internet-Draft - Exp. Aug 2004 Page 2 LDAP Control to Specify Chaining Behavior continuationBehavior instructs the DSA what to do when a referral is encountered after the name resolution part of an operation has completed. This scenario occurs during search operations, and may occur during yet to be defined future operations. If this field is not specified, other policy dictates the DSA's behavior. Behavior specifies whether the DSA should chain the operation or return referrals when a target object is held by a remote service. chainingPreferred indicates that the preference is that chaining, rather than referrals, be used to provide the service. When this value is set, the server attempts to chain the request but if it can't it returns referrals. chainingRequired indicates that chaining is to be used rather than referrals to service the request. When this value is set, the server MUST NOT return referrals. It either chains the request or fails. referralsPreferred indicates that the client wishes to receive referrals rather than allow the server to chain the operation. When this value is set, the server return referrals and search references when possible, but may chain the operation otherwise. referralsRequired indicates that chaining is prohibited. When this value is set, the server MUST NOT chain the request to other DSAs. Instead it returns referrals as necessary, or fails. The following list assigns meanings to some of the result codes that may occur due to this control being present: - chainingRequired (IANA-ASSIGNED-1) Unable to process without chaining. - cannotChain (IANA-ASSIGNED-2) Unable to chain the request. 4. Notes to Implementors <todo: add some> 4.1 Unbind and Abandon Clients MUST NOT include the ChainingBehavior control with an Abandon operation or an Unbind operation. Servers MUST ignore any chaining control on the abandon and unbind requests. Servers that chain operation are responsible to keep track of where an operation was chained to for the purposes of unbind and abandon. 4.2 StartTLS This operation cannot be chained because the TLS handshake protocol does not allow man-in-the-middle attacks. Sermersheim, Harrison Internet-Draft - Exp. Aug 2004 Page 3 LDAP Control to Specify Chaining Behavior 5. Relationship with other Extensions This control MAY be used with other controls or with extended operations. When it is used with other controls or with extended operations not listed here, server behavior is undefined unless otherwise specified. 5.1 Relationship with ManageDsaIT When this control is used along with the ManageDsaIT control, the resolveBehavior value is evaluated. If resolveBehavior is such that chaining is allowed, the DSA is allowed to chain the operation as necessary until the last RDN is found. For example: DSA1 holds the naming context <dc=net> and a subordinate reference to <dc=example,dc=net>, DSA2 holds the naming context <dc=example,dc=net> and a subordinate reference to <dc=hostc,dc=example,dc=net>. A modify operation accompanied by the ManageDsaIT control alone is sent to DSA1. The base object of the modify operation is set to <dc=hostc,dc=example,dc=net>. Since DSA1 does not hold the <dc=hostc,dc=example,dc=net> IT DSE, a referral is returned for <dc=example,dc=net>. Next, the same modify operation is accompanied by both the ManageDsaIT and the ChainingBehavior control where the ChainingBehavior.resolveBehavior is set to chainingPreferred. In this case, DSA1 chains to DSA2 when it encounters <dc=example,dc=net> and DSA2 continues the operation. Since DSA2 holds the IT DSE <dc=hostc,dc=example,dc=net>, the resolve portion completes, and the rest of the operation proceeds. 6. Security Considerations Because this control directs a DSA to chain requests to other DSAs, it may be used in a denial of service attack. Implementers should be cognizant of this possibility. This control may be used to allow access to hosts and portions of the DIT not normally available to clients. Servers supporting this control should provide sufficient policy to prevent unwanted occurrences of this. 7. IANA Considerations Registration of the following values is requested [RFC3383]. Sermersheim, Harrison Internet-Draft - Exp. Aug 2004 Page 4 LDAP Control to Specify Chaining Behavior 7.1. Object Identifiers It is requested that IANA register upon Standards Action an LDAP Object Identifier in identifying the protocol elements defined in this technical specification. The following registration template is suggested: Subject: Request for LDAP OID Registration Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Specification: RFCXXXX Author/Change Controller: IESG Comments: One delegation will be made under the assigned OID: IANA-ASSIGNED-OID.1 Chaining Behavior Request Control 7.2. LDAP Protocol Mechanism It is requested that IANA register upon Standards Action the LDAP protocol mechanism described in this document. The following registration template is suggested: Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: IANA-ASSIGNED-OID.1 Description: Chaining Behavior Request Control Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Usage: Control Specification: RFCXXXX Author/Change Controller: IESG Comments: none 7.3. LDAP Result Codes It is requested that IANA register upon Standards Action the LDAP result codes: chainingRequired (IANA-ASSIGNED-1) cannotChain (IANA-ASSIGNED-2) The following registration template is suggested: Subject: LDAP Result Code Registration Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Result Code Name: chainingRequired Result Code Name: cannotChain Specification: RFCXXXX Sermersheim, Harrison Internet-Draft - Exp. Aug 2004 Page 5 LDAP Control to Specify Chaining Behavior Author/Change Controller: IESG Comments: request consecutive result codes be assigned 8. Normative References [X.518] 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 RFC2119. [RFC2251] Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access Protocol (v3)", Internet Standard, December, 1997. Available as RFC2251. 9. Authors' Addresses Jim Sermersheim Novell, Inc. 1800 South Novell Place Provo, Utah 84606, USA jimse@novell.com +1 801 861-3088 Roger Harrison Novell, Inc. 1800 South Novell Place Provo, Utah 84606, USA rharrison@novell.com +1 801 861-2642 Sermersheim, Harrison Internet-Draft - Exp. Aug 2004 Page 6 LDAP Control to Specify Chaining Behavior Intellectual Property Rights 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. Full Copyright Statement 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 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. Sermersheim, Harrison Internet-Draft - Exp. Aug 2004 Page 7 PK /�c\�=���I �I C doc/alt-openldap11-devel/drafts/draft-ietf-ldapext-acl-model-xx.txtnu �[��� 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@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@tivoli.com mail-to: blakley@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@us.ibm.com mail-to: rbyrne@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 - PK /�c\�7�yL yL G doc/alt-openldap11-devel/drafts/draft-ietf-ldapext-ldapv3-dupent-xx.txtnu �[��� 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@example.net dn: cn=User2,dc=example,dc=net cn: User2 givenName: User Two mail: user2@example.net mail: usertwo@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@example.net control: 2.16.840.1.113719.1.27.101.2 dn: cn=User1,dc=example,dc=net givenName: User One mail: user1@example.net control: 2.16.840.1.113719.1.27.101.2 dn: cn=User2,dc=example,dc=net cn: User2 mail: user2@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@example.net control: 2.16.840.1.113719.1.27.101.2 dn: cn=User2,dc=example,dc=net givenName: User Two mail: user2@example.net control: 2.16.840.1.113719.1.27.101.2 dn: cn=User2,dc=example,dc=net givenName: User Two mail: usertwo@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@novell.com +1 801 861-3088 Sermersheim Internet-Draft - Expires Mar 2003 Page 9 PK /�c\�Ӑ ( ( F doc/alt-openldap11-devel/drafts/draft-zeilenga-ldap-dontusecopy-xx.txtnu �[��� INTERNET-DRAFT Kurt D. Zeilenga Intended Category: Standard Track Isode Limited Expires in six months 14 February 2007 The LDAP Don't Use Copy Control <draft-zeilenga-ldap-dontusecopy-04.txt> Status of this Memo This document is intended to be, after appropriate review and revision, submitted to the IESG for consideration as a 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@ietf.org>. Please send editorial comments directly to the author <Kurt.Zeilenga@Isode.COM>. 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/1id-abstracts.html. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. Copyright (C) The IETF Trust (2007). All Rights Reserved. Please see the Full Copyright section near the end of this document for more information. Zeilenga LDAP Don't Use Copy Control [Page 1] INTERNET-DRAFT draft-zeilenga-ldap-dontusecopy-04 14 February 2007 Abstract This document defines the Lightweight Directory Access Protocol (LDAP) Don't Use Copy control extension which allows a client to specify that copied information should not be used in providing service. This control is based upon the X.511 dontUseCopy service control option. 1. Background and Intended Usage This document defines the Lightweight Directory Access Protocol (LDAP) [RFC4510] Don't Use Copy control extension. The control may be attached to request messages to indicate that copied (replicated or cached) information [X.500] should not be used in providing service. This control is based upon the X.511 [X.511] dontUseCopy service control option. The Don't Use Copy control is intended to be used where the client requires the service be provided using original (master) information [X.500]. 2. Terminology DSA stands for Directory System Agent (or server). DSE stands for DSA-specific Entry. 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]. 3. The Don't Use Copy Control The Don't Use Copy control is an LDAP Control [RFC4511] whose controlType is IANA-ASSIGNED-OID and controlValue is absent. The criticality MUST be TRUE. There is no corresponding response control. The control is appropriate for both LDAP interrogation operations, including Compare and Search operations [RFC4511]. It is inappropriate for all other operations, including Abandon, Bind, Delete, Modify, ModifyDN, StartTLS, and Unbind operations [RFC4511]. When the control is attached to an LDAP request, the requested operation MUST NOT be performed on copied information. That is, the requested operation MUST be performed on original information. If original information for the target or base object of the operation Zeilenga LDAP Don't Use Copy Control [Page 2] INTERNET-DRAFT draft-zeilenga-ldap-dontusecopy-04 14 February 2007 is not available (either locally or through chaining), the server MUST either return a referral directing the client to a server believed to be better able to service the request or return an appropriate result code (e.g., unwillingToPerform). Servers implementing this technical specification SHOULD publish the object identifier IANA-ASSIGNED-OID as a value of the 'supportedControl' attribute [RFC4512] in their root DSE. A server MAY choose to advertise this extension only when the client is authorized to use it. 4. Security Considerations This control is intended to be provided where providing service using copied information might lead to unexpected application behavior. Designers of directory applications should consider where it is appropriate for clients to provide this control. Designers should consider whether use of copied information, in particular security and policy information, may result insecure behavior. Security considerations for the base operations [RFC4511] extended by this control, as well as general LDAP security considerations [RFC4510], generally apply to implementation and use of this extension. 5. IANA Considerations 5.1. Object Identifier It is requested that IANA assign upon Standards Action an LDAP Object Identifier [RFC4520] to identify the LDAP Don't Use Copy Control defined in this document. Subject: Request for LDAP Object Identifier Registration Person & email address to contact for further information: Kurt Zeilenga <Kurt.Zeilenga@Isode.COM> Specification: RFC XXXX Author/Change Controller: IESG Comments: Identifies the LDAP Don't Use Copy Control 5.2 LDAP Protocol Mechanism Registration of this protocol mechanism [RFC4520] is requested. Subject: Request for LDAP Protocol Mechanism Registration Zeilenga LDAP Don't Use Copy Control [Page 3] INTERNET-DRAFT draft-zeilenga-ldap-dontusecopy-04 14 February 2007 Object Identifier: IANA-ASSIGNED-OID Description: Don't Use Copy Control Person & email address to contact for further information: Kurt Zeilenga <Kurt.Zeilenga@Isode.COM> Usage: Control Specification: RFC XXXX Author/Change Controller: IESG Comments: none 6. Author's Address Kurt D. Zeilenga Isode Limited Email: Kurt.Zeilenga@Isode.COM 7. References [[Note to the RFC Editor: please replace the citation tags used in referencing Internet-Drafts with tags of the form RFCnnnn where possible.]] 7.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14 (also RFC 2119), March 1997. [RFC4510] Zeilenga, K. (editor), "LDAP: Technical Specification Road Map", RFC 4510, June 2006. [RFC4511] Sermersheim, J. (editor), "LDAP: The Protocol", RFC 4511, June 2006. [RFC4512] Zeilenga, K. (editor), "LDAP: Directory Information Models", RFC 4512, June 2006. 7.2. Informative References [X.500] International Telecommunication Union - Telecommunication Standardization Sector, "The Directory -- Overview of concepts, models and services," X.500(1993) (also ISO/IEC 9594-1:1994). Zeilenga LDAP Don't Use Copy Control [Page 4] INTERNET-DRAFT draft-zeilenga-ldap-dontusecopy-04 14 February 2007 [X.511] International Telecommunication Union - Telecommunication Standardization Sector, "The Directory: Abstract Service Definition", X.511(1993) (also ISO/IEC 9594-3:1993). [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", RFC 4520, BCP 64, June 2006. 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@ietf.org. Full Copyright Copyright (C) The IETF Trust (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, THE IETF TRUST AND Zeilenga LDAP Don't Use Copy Control [Page 5] INTERNET-DRAFT draft-zeilenga-ldap-dontusecopy-04 14 February 2007 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. Zeilenga LDAP Don't Use Copy Control [Page 6] PK /�c\��f�1� 1� > doc/alt-openldap11-devel/drafts/draft-wahl-ldap-session-xx.txtnu �[��� Network Working Group M. Wahl Internet-Draft Informed Control Inc. Intended status: Standards Track May 9, 2007 Expires: November 10, 2007 LDAP Session Tracking Control draft-wahl-ldap-session-03 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 November 10, 2007. Copyright Notice Copyright (C) The IETF Trust (2007). Wahl Expires November 10, 2007 [Page 1] Internet-Draft LDAP Session Tracking Control May 2007 Abstract Many network devices, application servers, and middleware components of a enterprise software infrastructure generate some form of session tracking identifiers, which are useful when analyzing activity and accounting logs to group activity relating to a particular session. This document discusses how Lightweight Directory Access Protocol version 3 (LDAP) clients can include session tracking identifiers with their LDAP requests. This information is provided through controls in the requests the clients send to LDAP servers. The LDAP server receiving these controls can include the session tracking identifiers in the log messages it writes, enabling LDAP requests in the LDAP server's logs to be correlated with activity in logs of other components in the infrastructure. The control also enables session tracking information to be generated by LDAP servers and returned to clients and other servers. Three formats of session tracking identifiers are defined in this document. Wahl Expires November 10, 2007 [Page 2] Internet-Draft LDAP Session Tracking Control May 2007 1. Introduction The majority of directory server implementations produce access logs detailing each request they receive. These logs can be read using log parsing tools or specialized log viewer applications. Typically it will be possible, for each request logged by a directory server, to determine the bind DN (or possibly another form of authentication identity) of the client which sent the request to the server, and many servers also log the IP address of the client that sent the request. In the original OSI architecture, it was envisaged that users might interact with a directory service through specialized applications, known as Directory User Agents, which were the clients of the Directory Access Protocol. Similarly, in early Internet directory deployments, a majority of LDAP clients were desktop applications, that used the LDAP protocol to search an enterprise directory for address book/contact information. Today, the majority of LDAP clients are embedded within middleware and server applications. Legacy address book protocols might be gatewayed into LDAP, or a server might consult an LDAP server in order to check a user's password or obtain their preferences. While the LDAP requests might result from a user's activity somewhere on the network, it is rare for the user to be 'driving' the LDAP client, and in most cases the user performing the activity is unaware that LDAP requests are being generated on their behalf. However, this information is important to directory system administrators and auditors. They may wish to determine who is making use of the directory service, or track the source of unusual requests. When a directory server administrator reviews a log file produced by a directory server that has been accessed only by clients that are themselves middleware, where the end user does not interact with the middleware directly, only through other kinds of servers (e.g. application servers or remote access servers), it will be difficult to correlate between the directory server's log and the logs of the servers which made use of this directory to determine why the LDAP requests were made and who were responsible for causing them. Reasons for this include: o Directory servers are capable of performing many hundreds of requests per second or more, and even with time synchronization between the systems on which the directory server and middleware are deployed, times of requests might not be logged accurately Wahl Expires November 10, 2007 [Page 3] Internet-Draft LDAP Session Tracking Control May 2007 enough to be able to correlate based on time: the server's logs might be only to 1-second resolution. o A single function on a middleware server, such as "authenticate a user", may result in multiple LDAP requests being generated in order to perform that request. o Many high performance middleware servers implement connection pooling, managing a set of persistent connections to each directory server and multiplexing operations across the connections. Each connection will have the same source IP address and bind DN. If a particular activity causes multiple LDAP requests to be generated, each LDAP request might be sent on a different connection. Also, as LDAP is an asynchronous protocol, middleware servers may have more than one request in progress on each connection, asynchronously sending requests to the directory server on each connection and processing the responses in whatever order they are received. This document defines a new control for use in LDAPv3 [1] operation requests. This control contains session tracking information that can be used to correlate log information present in the directory server's log with the logs of other middleware servers. The words "MUST", "SHOULD" and "MAY" are used as defined in RFC 2119 [2]. 1.1. Motivation for session tracking A typical enterprise deployment with an application indirectly relying upon the directory might resemble: +------+ +--------+ +----------+ +--------+ | User | | Appli- | | Auth./ | LDAP | LDAP | | +-----+ cation +-------+ Identity +------+ Server | | | | Server | | Provider | | | | A | | B | | C | | D | +------+ +--------+ +----------+ +--------+ In this diagram, a user (A) makes some request of an application server (B). The application server might rely on an integrated or external authentication provider in order to check the user's authentication credentials, or might use an identity provider to obtain profile information about the user. This request might be made through an API or a protocol other than LDAP, e.g. RADIUS, Kerberos, SMB, etc. The authentication/identity provider (C) would Wahl Expires November 10, 2007 [Page 4] Internet-Draft LDAP Session Tracking Control May 2007 generate one or more LDAP requests and send them to an LDAP server (D). The LDAP server has the following information already available to it through the LDAP protocol: the IP address and authentication credentials of the authentication/identity provider (C). If the provider has included the Proxy Authorization Control [11], then the LDAP server might also receive the Distinguished Name or authorization identity of either the user (A) or the application server (B), depending on how the authentication/identity provider (C) uses the directory. In order to obtain this distinguished name however, the authentication/identity provider (C) might need to perform one or more LDAP search or bind requests. If there is no entry in the directory corresponding to the identity of the user (A) or the application server (B), then there is no way in the base LDAP specification or the Proxy Authorization Control for the authentication/identity provider (C) to describe the user (A) or the application server (B) to the LDAP server (D). If either the application server (B) or the authentication/identity provider (C) have generated a session identifier for tracking the interactions of the user (A) for a particular session, then it is useful to include this information with the requests made to the directory server, so that this session identifier will show up in the directory server's logs. That is the purpose of the control defined in the next section. Wahl Expires November 10, 2007 [Page 5] Internet-Draft LDAP Session Tracking Control May 2007 2. Control definition There is currently no standard way of describing a session: there are many different formats for a session identifier, and each application that tracks sessions typically has its own semantics for what a session means. Thus, a control is defined using an extensible model, in order to incorporate many different application's concepts and formats of a session tracking identifier. The value of the session identifier control encapsulates the following four pieces of information: sessionSourceIp, sessionSourceName, formatOID and sessionTrackingIdentifier. The sessionSourceIp field is a US-ASCII string encoding of an IPv4 or IPv6 [3] address of the component of the system which has generated a session tracking identifier. The purpose of this field is to enable the directory server administrator, even if they do not have a log parser that understands a particular session tracking identifier format, to at least be able to identify the server that manages the session. Note that there is no guarantee of IP-level connectivity between the directory server and the system which generated the tracking identifier, and if Network Address Translation is being used, the IP address in this field might be from a private use address range. The sessionSourceName field is a UTF-8 [4] encoded ISO 10646 [5] text string. This field describes the component of the system which has generated a session tracking identifier. The format of this field is determined by the formatOID (discussed below); examples of contents of a sessionSourceName field might be a hostname, a distinguished name, or a web service address. This contents of this field is not intended to identify an end user; instead it identifies the server using a name other than the server's IP address. The formatOID is a US-ASCII encoded dotted decimal representation of an OBJECT IDENTIFIER. The OBJECT IDENTIFIER indicates the scheme that is used to generate the sessionSourceName and sessionTrackingIdentifier fields. As there is currently no standard scheme for session information, it is expected that there will be many different formats carried within this control. The OBJECT IDENTIFIERs for three formats are presented in this document. The sessionTrackingIdentifier field is a UTF-8 encoded ISO 10646 string. The session identifier SHOULD be limited to whitespace and printable characters; non-printing and control characters SHOULD NOT be used, and byte sequences that are not legal UTF-8 MUST NOT be used. The syntax of the session identifier and its semantics (e.g., how values are compared for equality) are governed by the formatOID. Wahl Expires November 10, 2007 [Page 6] Internet-Draft LDAP Session Tracking Control May 2007 For example, the session identifier might be a simple string encoding of a decimal counter, a username, a timestamp, a fragment of XML, or it might be something else, depending on the format. 2.1. Formal definition This document defines a single LDAP control. The controlType is 1.3.6.1.4.1.21008.108.63.1, the criticality MUST be either FALSE or absent, and the controlValue MUST be present. The controlValue OCTET STRING is always present and contains the bytes of the BER [6] encoding of a value of the ASN.1 data type SessionIdentifierControlValue, defined as follows: LDAP-Session-Identifier-Control DEFINITIONS IMPLICIT TAGS ::= BEGIN LDAPString ::= OCTET STRING -- UTF-8 encoded LDAPOID ::= OCTET STRING -- Constrained to numericoid SessionIdentifierControlValue ::= SEQUENCE { sessionSourceIp LDAPString, sessionSourceName LDAPString, formatOID LDAPOID, sessionTrackingIdentifier LDAPString } END The sessionSourceIp element SHOULD NOT be longer than 42 characters (the length necessary for a string representation of an IPv6 address), and MUST NOT be longer than 128 characters. Each character will be encoded into a single byte. If the IP address of the system which generated the session tracking identifier is not known, the sessionSourceIp element SHOULD be of zero length. The sessionSourceName element SHOULD NOT be longer than 1024 characters, and MUST NOT be longer than 65536 bytes. Note that in the UTF-8 encoding a character MAY be encoded into more than one byte. If no other addressing information about that system is known or relevant to the format, the sessionSourceName element SHOULD be of zero length. The formatOID element MUST contain only the US-ASCII encodings of the ISO 10646 characters FULL STOP and DIGIT ZERO through DIGIT NINE (0x2E, 0x30-0x39). The formatOID element MUST NOT be of zero length, and SHOULD NOT be longer than 1024 characters. Wahl Expires November 10, 2007 [Page 7] Internet-Draft LDAP Session Tracking Control May 2007 The sessionTrackingIdentifier field MAY be of zero length (although this might not be useful). There is no upper bound on the sessionTrackingIdentifier, but it is suggested that values SHOULD NOT be longer than 65536 characters without prior agreement with the directory server administrator. Note that in the UTF-8 encoding a character MAY be encoded into more than one byte. 2.2. Use in LDAP The control MAY be included in any LDAP operation. The control has order-dependent semantics. A client might place the control on a message with a bindRequest, searchRequest, modifyRequest, addRequest, delRequest, modDNRequest, compareRequest or extendedReq. A client MAY include multiple controls of this type in a single request. This enables the client to incorporate multiple distinct session tracking identifiers with different formats. When a network service is proxying or chaining LDAP, in which the service receives an incoming LDAP request from a client and from this generates one or more requests to other LDAP servers, the service SHOULD include any controls of this type that it received from clients in requests it generates, without modification. A service MAY silently remove a control if that control would violate security policy. If the service has its own session state identifier, it SHOULD include the session identifier control it generates in the Controls SEQUENCE after any session identifier controls received by clients. (If there are multiple proxies involved, each will add their own session state to the end of the controls list). A server might place the control on message with a bindResponse, searchResDone, modifyResponse, addResponse, delResponse, modDNResponse, compareResponse, extendedResp or intermediateResponse. The server can include the control in the response regardless of whether the client included a control in the request or not. (The control in a response is unsolicited, and a client which does not recognize the control or a session tracking format can safely ignore the control, as discussed in the following section). A server MAY include multiple controls of this type in a response. 2.3. Extensibility considerations The following section of this document defines 3 possible formats, and it is expected that applications MAY define their own formats to represent session tracking identifiers already implemented. An application developer or server developer who wishes to transfer Wahl Expires November 10, 2007 [Page 8] Internet-Draft LDAP Session Tracking Control May 2007 their implementation's format for session tracking identifier within an LDAP control MUST choose a new, unique, OBJECT IDENTIFIER to represent this format. The format determines the semantics of the sessionSourceName string, and the sessionTrackingIdentifier string. In general, when an LDAP server that has session tracking logging enabled receives one or more of these controls with a request, the server SHOULD include all fields of all of the controls with the logging information for the request. A LDAP server that supports third-party or extensible log parsing tools SHOULD NOT reject or ignore a control if the formatOID value is not recognized, as it is expected that applications may include session tracking identifiers and want to make this information available to log parsers for correlation purposes, even if the directory server does not need to make any use of this information. However, if the LDAP server does not recognize the control, the control is not properly formatted, or the LDAP client is not authorized to use this control, the LDAP server SHOULD ignore the control and process the request as if the control had not been included. When an LDAP client receives a response that includes this control, the behavior depends on the client implementation. Clients SHOULD silently ignore controls with formats they do not recognize, and process the response as if the control had not been included. Wahl Expires November 10, 2007 [Page 9] Internet-Draft LDAP Session Tracking Control May 2007 3. Session tracking format definitions This section defines three session tracking formats that can be used within the session tracking control: two for RADIUS accounting, and one based on usernames. Other formats can be defined in other documents. 3.1. Formats for use with RADIUS accounting This section defines two possible session tracking formats, that can be used in LDAP clients that are part of or used by RADIUS servers [7]. With formatOID set to 1.3.6.1.4.1.21008.108.63.1.1 within the control value, the sessionTrackingIdentifier SHOULD contain the value of the Acct-Session-Id RADIUS attribute (type 44), as defined in RFC 2866 [8]. (RFC 2866 section 5.5 states that the Acct-Session-Id SHOULD contain UTF-8 encoded ISO 10646 characters.) With formatOID set to 1.3.6.1.4.1.21008.108.63.1.2 within the control value, the sessionTrackingIdentifier SHOULD contain the value of the Acct-Multi-Session-Id RADIUS attribute (type 50), as defined in RFC 2866 [8]. (RFC 2866 section 5.11 states that the Acct-Multi-Session-Id SHOULD contain UTF-8 encoded ISO 10646 characters.) In both of these two formats, the value of the sessionSourceIp field SHOULD contain either a string encoding value of the IPv4 address from the NAS-IP-Address RADIUS attribute (type 4), or a string encoding of the IPv6 address from the value of the NAS-IPv6-Address RADIUS attribute (type 95) as defined in RFC 3162 [9]. The value of the sessionSourceName field SHOULD contain a string encoding the value of the NAS-Identifier RADIUS attribute (type 32), if present, or be of zero length if the NAS-Identifier RADIUS attribute was not provided or was not in a recognized format. 3.2. Format for username accounting This section defines another possible session tracking format that can be used in LDAP clients that are part of applications which identify users with simple string usernames. With formatOID set to 1.3.6.1.4.1.21008.108.63.1.3 within the control value, the sessionTrackingIdentifier SHOULD contain a username that has already been authenticated by the application that is generating the session. This format SHOULD NOT be used for purported names, where the application has not verified that the username is valid. Wahl Expires November 10, 2007 [Page 10] Internet-Draft LDAP Session Tracking Control May 2007 The sessionSourceName field SHOULD contain the hostname where that application is running, or be of zero length if the hostname is not known. The username SHOULD be a SASL authorization identity string, as described in section 3.4.1 of RFC 4422 [10]. It is expected that these usernames are not globally unique, but are only unique within the context of a particular application or particular enterprise. A username need not be a distinguished name, and an implementation receiving a control in this format MUST NOT assume that the contents of the sessionTrackingIdentifier can be parsed as a distinguished name. A control with this format differs from the Proxied Authorization Control as defined in RFC 4370 [11], as the presence of this session identifier control on a request SHOULD NOT influence the directory server's access control decision of whether or how to perform that request. Note that this format does not provide any information to differentiate between multiple sessions or periods of interaction by the same user. It is primarily intended for deployments which merely need to be able to tie each directory operation to they identity of the user whose activities caused the operation request to be generated, even if the user might not even be represented in the directory where the operations are being performed. 3.2.1. Example For example, if an application server "app.example.com" with IPv4 address "192.0.2.1" had authenticated an user with name "bloggs", and then sent a search request to the LDAP directory in order to obtain some public information on service configuration intending to provide it to that user, the application might include a session identifier control. The SessionIdentifierControlValue would have the following ASN.1 value prior to encoding: { -- SEQUENCE "192.0.2.1", -- sessionSourceIp "app.example.com", -- sessionSourceName "1.3.6.1.4.1.21008.108.63.1.3", -- formatOID "bloggs" -- sessionTrackingIdentifier } Wahl Expires November 10, 2007 [Page 11] Internet-Draft LDAP Session Tracking Control May 2007 The session identifier control would be sent with controlType 1.3.6.1.4.1.21008.108.63.1, criticality FALSE, and the controlValue the BER encoding of the SessionIdentifierControlValue. The control included with the LDAP request would resemble: { -- SEQUENCE "1.3.6.1.4.1.21008.108.63.1", -- controlType FALSE, -- criticality '304204093139322e302e322e31040f6170702e6578616d706c652e636f6d 041c312e332e362e312e342e312e32313030382e3130382e36332e312e33 0406626c6f676773'H -- controlValue } Wahl Expires November 10, 2007 [Page 12] Internet-Draft LDAP Session Tracking Control May 2007 4. Security Considerations The session identifier controls used in this document are not intended as a security control or proxy authentication mechanism, and SHOULD NOT be used within a directory server to influence the operation processing behavior. Malicious clients might attempt to provide false or misleading information in directory server logs through the use of this control. LDAP servers SHOULD implement access checks which limit whether session identifier information provided by a client is logged. LDAP servers which implement this control SHOULD permit the administrator of the directory server to configure that this control is ignored unless the request containing the control was received from a client that been authenticated. LDAP servers which implement this control SHOULD permit the administrator of the directory server to configure that this control is ignored unless the client is authorized to use this or related controls, such as the Proxied Authorization Control [11]. Session identifier information from clients which do not meet the server's access check requirement SHOULD be silently discarded. In some formats, session tracking identifiers may contain personal- identifiable information, such as usernames or client IP addresses. Unless data link, network or transport level encryption is being used, this information might be visible to attackers monitoring the network segments across which this information is being transmitted. Implementations of LDAP clients which include this control in requests sent to directory servers SHOULD support the use of underlying security services that establish connection confidentiality before the control is sent, such as a SASL mechanism that negotiates a security layer, or the Start TLS operation. Correlation of activities across multiple servers can enable administrators and monitoring tools to construct a more accurate picture of user behavior. In particular, this tracking control could be used to determine the set of applications and services with which a particular user has had interactions. Thus, this control would not be appropriate to deployments intending to anonymize directory requests. Session formats containing personal identifiable information SHOULD NOT be used between systems in different organizations where there is no existing agreement between those organizations on privacy protection. A value of the session tracking control might contain internal IP addresses, hostnames and other identifiers that reveal the structure of an enterprise network. A network service that generates its own sessions SHOULD NOT send a session tracking control to a directory server that is under different administration or in a different Wahl Expires November 10, 2007 [Page 13] Internet-Draft LDAP Session Tracking Control May 2007 security enclave from itself. A network service that is an LDAP client and also either receives requests over another protocol that contains session tracking identifiers or is proxying incoming LDAP requests SHOULD NOT forward received session tracking identifiers to a directory server that is under different administration or in a different security enclave from itself. A packet inspecting firewall that permits outgoing LDAP requests from an enterprise network SHOULD silently remove any session tracking controls from requests that are being sent to directory servers outside of the enterprise network for which there is not a preexisting policy configured to allow the session tracking control to be sent to that directory server. Wahl Expires November 10, 2007 [Page 14] Internet-Draft LDAP Session Tracking Control May 2007 5. IANA Considerations This control will be registered as follows: Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: 1.3.6.1.4.1.21008.108.63.1 Description: Session Tracking Identifier Person & email address to contact for further information: Mark Wahl <Mark.Wahl@informed-control.com> Usage: Control Specification: (I-D) RFC XXXX Author/Change Controller: Mark Wahl The OBJECT IDENTIFIER for particular session identifier formats defined for other applications need not be registered with IANA. Wahl Expires November 10, 2007 [Page 15] Internet-Draft LDAP Session Tracking Control May 2007 6. Acknowledgments This control was inspired by conversations with Greg Lavender. Neil Wilson provided useful feedback on this document. Wahl Expires November 10, 2007 [Page 16] Internet-Draft LDAP Session Tracking Control May 2007 7. References 7.1. Normative References [1] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006. [2] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, BCP 14, March 1997. [3] Hinden, R., "IP Version 6 Addressing Architecture", RFC 1884, January 1996. [4] Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC 3629, November 2003. [5] "Universal Multiple-Octet Coded Character Set (UCS) - Architecture and Basic Multilingual Plane, ISO/IEC 10646-1: 1993". [6] "ITU-T Rec. X.690 (07/2002) | ISO/IEC 8825-1:2002, "Information technology - ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER)", 2002.". [7] Rigney, C., "Remote Authentication Dial In User Service (RADIUS)", RFC 2865, June 2000. [8] Rigney, C., "RADIUS Accounting", RFC 2866, June 2000. [9] Aboba, B., "RADIUS and IPv6", RFC 3162, August 2001. [10] Melnikov, A., "Simple Authentication and Security Layer (SASL)", RFC 4422, June 2006. 7.2. Informative References [11] Weltman, R., "Lightweight Directory Access Protocol (LDAP) Proxied Authorization Control", RFC 4370, February 2006. Wahl Expires November 10, 2007 [Page 17] Internet-Draft LDAP Session Tracking Control May 2007 Appendix A. Copyright Copyright (C) The IETF Trust (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. Wahl Expires November 10, 2007 [Page 18] Internet-Draft LDAP Session Tracking Control May 2007 Author's Address Mark Wahl Informed Control Inc. PO Box 90626 Austin, TX 78709 US Email: mark.wahl@informed-control.com Wahl Expires November 10, 2007 [Page 19] Internet-Draft LDAP Session Tracking Control May 2007 Full Copyright Statement Copyright (C) The IETF Trust (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, THE IETF TRUST 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@ietf.org. Acknowledgment Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Wahl Expires November 10, 2007 [Page 20] PK /�c\2��u] ] ? doc/alt-openldap11-devel/drafts/draft-legg-ldap-transfer-xx.txtnu �[��� INTERNET-DRAFT S. Legg draft-legg-ldap-transfer-03.txt Adacel Technologies Intended Category: Standards Track 16 June 2004 Updates: RFC 2252bis Lightweight Directory Access Protocol (LDAP): Transfer Encoding Options Copyright (C) The Internet Society (2004). All Rights Reserved. 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, after appropriate review and revision, submitted to the RFC Editor as a Standard Track document. Distribution of this document is unlimited. Technical discussion of this document should take place on the IETF LDAP Revision Working Group (LDAPbis) mailing list <ietf-ldapbis@openldap.org>. Please send editorial comments directly to the editor <steven.legg@adacel.com.au>. This Internet-Draft expires on 16 December 2004. Abstract Each attribute stored in a Lightweight Directory Access Protocol (LDAP) directory has a defined syntax (i.e., data type). A syntax Legg Expires 16 December 2004 [Page 1] INTERNET-DRAFT LDAP: Transfer Encoding Options June 16, 2004 definition specifies how attribute values conforming to the syntax are normally represented when transferred in LDAP operations. This representation is referred to as the LDAP-specific encoding to distinguish it from other methods of encoding attribute values. This document introduces a new category of attribute options, called transfer encoding options, which can be used to specify that the associated attribute values are encoded according to one of these other methods. Legg Expires 16 December 2004 [Page 2] INTERNET-DRAFT LDAP: Transfer Encoding Options June 16, 2004 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Transfer Encoding Options. . . . . . . . . . . . . . . . . . . 4 4. Defined Transfer Encoding Options. . . . . . . . . . . . . . . 5 5. Attributes Returned in a Search. . . . . . . . . . . . . . . . 6 6. Syntaxes Requiring Binary Transfer . . . . . . . . . . . . . . 7 7. Security Considerations. . . . . . . . . . . . . . . . . . . . 7 8. IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 8 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9 9.1. Normative References . . . . . . . . . . . . . . . . . . 9 9.2. Informative References . . . . . . . . . . . . . . . . . 10 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 10 Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 10 1. Introduction Each attribute stored in a Lightweight Directory Access Protocol (LDAP) directory [ROADMAP] has a defined syntax (i.e., data type) which constrains the structure and format of its values. The description of each syntax [SYNTAX] specifies how attribute or assertion values [MODELS] conforming to the syntax are normally represented when transferred in LDAP operations [PROT]. This representation is referred to as the LDAP-specific encoding to distinguish it from other methods of encoding attribute values. This document introduces a new category of attribute options [MODELS], called transfer encoding options, that allow attribute and assertion values to be transferred using an alternative method of encoding. This document defines several transfer encoding options which can be used in an attribute description [MODELS] in an LDAP operation to specify that the associated attribute values or assertion value are, or are requested to be, encoded according to specific Abstract Syntax Notation One (ASN.1) [X680] encoding rules, instead of the usual LDAP-specific encoding. One option in particular allows Extensible Markup Language (XML) [XML] encodings. 2. Conventions 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 [KEYWORD]. This specification makes use of definitions from the XML Information Set (Infoset) [ISET]. In particular, information item property names Legg Expires 16 December 2004 [Page 3] INTERNET-DRAFT LDAP: Transfer Encoding Options June 16, 2004 are presented per the Infoset, e.g., [local name]. 3. Transfer Encoding Options Transfer encoding options enable attribute and assertion values to be transferred using an alternative method of encoding to the default LDAP-specific encoding. In fact, some attribute and assertion syntaxes do not have a defined LDAP-specific encoding in which case the only way values of those syntaxes can be transferred is by using an alternative encoding. The binary option [BINARY] is not formally regarded as a transfer encoding option, though it has much in common with transfer encoding options. The requirements governing the use of transfer encoding options do not apply to the binary option. The requirements governing the use of the binary option are described elsewhere [BINARY]. In terms of the protocol [PROT], a transfer encoding option specifies that the contents octets of an associated AttributeValue or AssertionValue OCTET STRING are a complete encoding of the relevant value according to the encoding method specified by the option. Where a transfer encoding option is present in an attribute description the associated attribute values or assertion value MUST be encoded according to the encoding method corresponding to the option. Note that it is possible for a syntax to be defined such that its LDAP-specific encoding is exactly the same as its encoding according to some transfer encoding option (e.g., the LDAP-specific encoding might be defined to be the same as the BER encoding). Transfer encoding options are mutually exclusive. An attribute description SHALL NOT contain more than one transfer encoding option, and SHALL NOT contain both a transfer encoding option and the binary option. Transfer encoding options are not tagging options [MODELS] so the presence of a transfer encoding option does not specify an attribute subtype. An attribute description containing a transfer encoding option references exactly the same attribute as the same attribute description without the transfer encoding option. The supertype/subtype relationships of attributes with tagging options are not altered in any way by the presence or absence of transfer encoding options. An attribute description SHALL be treated as unrecognized if it contains a transfer encoding option and the syntax of the attribute does not have an associated ASN.1 type [SYNTAX], or if the nominated Legg Expires 16 December 2004 [Page 4] INTERNET-DRAFT LDAP: Transfer Encoding Options June 16, 2004 encoding is not supported for that type. The presence or absence of a transfer encoding option only affects the transfer of attribute and assertion values in protocol; servers store any particular attribute value in a single format of their choosing. 4. Defined Transfer Encoding Options The attribute option string "transfer-ber" specifies that the associated attribute values or assertion value are (to be) encoded according to the Basic Encoding Rules [X690] of ASN.1. This option is similar to the binary option [BINARY], however servers are more restricted in when they can use "transfer-ber" which leads to more predictability in the results returned to clients who request "transfer-ber". The attribute option string "transfer-der" specifies that the associated attribute values or assertion value are (to be) encoded according to the Distinguished Encoding Rules [X690] of ASN.1. The attribute option string "transfer-gser" specifies that the associated attribute values or assertion value are (to be) encoded according to the Generic String Encoding Rules (GSER) [RFC3641]. The attribute option string "transfer-rxer" specifies that the associated attribute values or assertion value are (to be) encoded as an XML document [XML]. The [local name] of the [document element] of the document information item representing the associated value SHALL be the identifier of the NamedType [X680] in the LDAP ASN.1 specification [PROT] defining the associated attribute value or assertion value, or "item" if the associated value isn't in a NamedType. This means: - for an AttributeValue the identifier is "value" in every case, - for an AssertionValue in an AttributeValueAssertion the identifier is "assertionValue", - for an AssertionValue in a SubstringFilter the identifier is "initial", "any" or "final", as appropriate, - for an AssertionValue in a MatchingRuleAssertion the identifier is "matchValue". The [namespace name] of the [document element] SHALL have no value. The content of the [document element] is the Robust XML Encoding Rules (RXER) [RXER] encoding of the associated attribute or assertion Legg Expires 16 December 2004 [Page 5] INTERNET-DRAFT LDAP: Transfer Encoding Options June 16, 2004 value. Note that the enclosing element for the RXER encoding has the form it would take in an XLDAP operation [XLDAP]. Note that, like all attribute options, the strings representing transfer encoding options are case insensitive. All future registrations of option strings for transfer encoding options should use the "transfer-" prefix so that LDAP clients and servers can recognize that an option is a transfer encoding option even though the particular encoding rules may be unrecognized. 5. Attributes Returned in a Search An LDAP search request [PROT] contains a list of the attributes (the requested attributes list) to be returned from each entry matching the search filter. An attribute description in the requested attributes list also implicitly requests all subtypes of the attribute type in the attribute description, whether through attribute subtyping or attribute tagging option subtyping [MODELS]. The requested attributes list MAY contain attribute descriptions with a transfer encoding option, but MUST NOT contain two attribute descriptions with the same attribute type and the same tagging options (even if only one of them has a transfer encoding option). A transfer encoding option in an attribute description in the requested attributes list implicitly applies to the subtypes of the attribute type in the attribute description. If the list of attributes in a search request is empty, or contains the special attribute description string "*", then all user attributes are requested to be returned. In general, it is possible for a particular attribute to be explicitly requested by an attribute description and/or implicitly requested by the attribute descriptions of one or more of its supertypes. In such cases the effective transfer encoding being requested for a particular attribute is determined by the transfer encoding option (or lack thereof) in the most specific attribute description in the requested attributes list that applies to the attribute. An applicable attribute description with an actual attribute type is more specific than the special attribute description string "*". If the attribute type of one applicable attribute description is a direct or indirect subtype of the attribute type in another applicable attribute description then the former attribute description is more specific than the latter attribute description. Legg Expires 16 December 2004 [Page 6] INTERNET-DRAFT LDAP: Transfer Encoding Options June 16, 2004 If two applicable attribute descriptions have the same attribute type and the tagging options of one attribute description are a superset of the tagging options of the other attribute description then the former attribute description is more specific than the latter attribute description. Attributes MUST either be returned in the effective transfer encoding requested, be returned with no attribute values, or be omitted from the results. An attribute SHALL NOT be returned using an encoding other than the effective transfer encoding requested. Regardless of the encoding chosen, a particular attribute value is returned at most once. 6. Syntaxes Requiring Binary Transfer Certain syntaxes are required to be transferred in the BER encoded form. These syntaxes are said to have a binary transfer requirement. The Certificate, Certificate List, Certificate Pair and Supported Algorithm syntaxes [PKI] are examples of syntaxes with a binary transfer requirement. These syntaxes also have an additional requirement that the exact BER encoding must be preserved. Note that this is a property of the syntaxes themselves, and not a property of the binary option or any of the transfer encoding options. Transfer encoding options SHALL take precedence over the requirement for binary transfer. For example, if the effective transfer encoding requested is say "transfer-gser", then attribute values of a syntax with a binary transfer requirement will be GSER encoded. In the absence of a transfer encoding option the normal rules on binary transfer and the use of the binary option SHALL apply. 7. Security Considerations There is a requirement on some attribute syntaxes that the exact BER encoding of values of that syntax be preserved. In general, a transformation from the BER encoding into some other encoding (e.g., GSER) and back into the BER encoding will not necessarily reproduce exactly the octets of the original BER encoding. Applications needing the original BER encoding to be preserved, e.g., for the verification of digital signatures, MUST NOT request attributes with such a requirement using a transfer encoding option. These attributes MUST be requested explicitly or implicitly with the binary option, or implicitly without the binary option (or any transfer encoding option). When interpreting security-sensitive fields, and in particular fields Legg Expires 16 December 2004 [Page 7] INTERNET-DRAFT LDAP: Transfer Encoding Options June 16, 2004 used to grant or deny access, implementations MUST ensure that any matching rule comparisons are done on the underlying abstract value, regardless of the particular encoding used. 8. IANA Considerations The Internet Assigned Numbers Authority (IANA) is requested to update the LDAP attribute description option registry [BCP64] as indicated by the following templates: Subject: Request for LDAP Attribute Description Option Registration Option Name: transfer-ber Family of Options: NO Person & email address to contact for further information: Steven Legg <steven.legg@adacel.com.au> Specification: RFC XXXX Author/Change Controller: IESG Comments: Subject: Request for LDAP Attribute Description Option Registration Option Name: transfer-der Family of Options: NO Person & email address to contact for further information: Steven Legg <steven.legg@adacel.com.au> Specification: RFC XXXX Author/Change Controller: IESG Comments: Subject: Request for LDAP Attribute Description Option Registration Option Name: transfer-gser Family of Options: NO Person & email address to contact for further information: Steven Legg <steven.legg@adacel.com.au> Specification: RFC XXXX Author/Change Controller: IESG Comments: Subject: Request for LDAP Attribute Description Option Registration Option Name: transfer-rxer Family of Options: NO Person & email address to contact for further information: Steven Legg <steven.legg@adacel.com.au> Specification: RFC XXXX Author/Change Controller: IESG Legg Expires 16 December 2004 [Page 8] INTERNET-DRAFT LDAP: Transfer Encoding Options June 16, 2004 Comments: 9. References 9.1. Normative References [KEYWORD] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [BCP64] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protcol (LDAP)", BCP 64, RFC 3383, September 2002. [ROADMAP] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", draft-ietf-ldapbis-roadmap-xx.txt, a work in progress, June 2004. [MODELS] Zeilenga, K., "LDAP: Directory Information Models", draft-ietf-ldapbis-models-xx.txt, a work in progress, June 2004. [PROT] Sermersheim, J., "LDAP: The Protocol", draft-ietf-ldapbis-protocol-xx.txt, a work in progress, May 2004. [SYNTAX] Legg, S. and K. Dally, "Lightweight Directory Access Protocol (LDAP): Syntaxes and Matching Rules", draft-ietf-ldapbis-syntaxes-xx.txt, a work in progress, May 2004. [RFC3641] Legg, S., "Generic String Encoding Rules (GSER) for ASN.1 Types", RFC 3641, October 2003. [BINARY] Legg, S., "Lightweight Directory Access Protocol (LDAP): The Binary Encoding Option", draft-legg-ldap-binary-xx.txt, a work in progress, June 2004. [RXER] Legg, S. and D. Prager, "Robust XML Encoding Rules for ASN.1 Types", draft-legg-xed-rxer-00.txt, a work in progress, June 2004. [X680] ITU-T Recommendation X.680 (07/02) | ISO/IEC 8824-1, Information technology - Abstract Syntax Notation One (ASN.1): Specification of basic notation. [X690] ITU-T Recommendation X.690 (07/02) | ISO/IEC 8825-1, Legg Expires 16 December 2004 [Page 9] INTERNET-DRAFT LDAP: Transfer Encoding Options June 16, 2004 Information Technology - ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER). [XML] Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E. and F. Yergeau, "Extensible Markup Language (XML) 1.0 (Third Edition)", W3C Recommendation, http://www.w3.org/TR/2004/REC-xml-20040204, February 2004. [ISET] Cowan, J. and R. Tobin, "XML Information Set", http://www.w3.org/TR/2001/REC-xml-infoset-20011024, October 2001. 9.2. Informative References [XLDAP] Legg, S. and D. Prager, "The XML Enabled Directory: Protocols", draft-legg-xed-protocols-xx.txt, a work in progress, May 2004. Author's Address Steven Legg Adacel Technologies Ltd. 250 Bay Street Brighton, Victoria 3186 AUSTRALIA Phone: +61 3 8530 7710 Fax: +61 3 8530 7888 Email: steven.legg@adacel.com.au Full Copyright Statement Copyright (C) The Internet Society (2004). 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 Legg Expires 16 December 2004 [Page 10] INTERNET-DRAFT LDAP: Transfer Encoding Options June 16, 2004 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@ietf.org. Changes in Draft 01 A transfer encoding option for RXER has been added. Changes in Draft 02 The local name of the root element of the XML document representing an attribute value encoded according to the transfer-rxer encoding option has been changed from "item" to "value" to align with revisions to the LDAP protocol specification [PROT]. The Directory XML Encoding Rules (DXER) have been renamed to the Robust XML Encoding Rules (RXER). Changes in Draft 03 The special attribute description strings that consist of the asterisk character followed by a transfer encoding option, e.g., "*;transfer-ber", "*;transfer-gser", have been removed from this specification. An LDAP control will be defined in a separate document to provide equivalent functionality. Legg Expires 16 December 2004 [Page 11] PK /�c\����R+ R+ O doc/alt-openldap11-devel/drafts/draft-sermersheim-ldap-subordinate-scope-xx.txtnu �[��� Network Working Group J;. Sermersheim Internet-Draft Novell, Inc Updates: 2251 (if approved) July 2004 Expires: December 30, 2004 Subordinate Subtree Search Scope for LDAP draft-sermersheim-ldap-subordinate-scope-00.txt Status of this Memo This document is an Internet-Draft and is subject to all provisions of section 3 of RFC 3667. 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 become aware will be disclosed, in accordance with RFC 3668. 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 December 30, 2004. Copyright Notice Copyright (C) The Internet Society (2004). Abstract The Lightweight Directory Application Protocol (LDAP) specification supports three scope values for the search operation -- namely: baseObject, singleLevel, and wholeSubtree. This document introduces a subordinateSubtree scope which constrains the search scope to all subordinates of the named base object. Discussion Forum Sermersheim Expires December 30, 2004 [Page 1] Internet-Draft Subordinate Subtree Search Scope for LDAP July 2004 Technical discussion of this document will take place on the IETF LDAP Extensions mailing list <ldapext@ietf.org>. Please send editorial comments directly to the author. 1. Overview There are a number of reasons which have surfaced for introducing a Lightweight Directory Application Protocol (LDAP) [RFC3377] SearchRequest.scope [RFC2251] which constrains the search scope to all subordinates of the named base object, and does not include the base object (as wholeSubtree does). These reasons range from the obvious utility of allowing an LDAP client application the ability to exclude the base object from a wholeSubtree search scope, to distributed operation applications which require this scope for progressing search sub-operations resulting from an nssr DSE type reference. To meet these needs, the subordinateSubtree scope value is introduced. The subordinateSubtrees cope is applied to the SearchRequest.scope field, the <scope> type and alternately the <extension> type of the LDAP URL [RFC2255] and may be applied to other specifications which include an LDAP search scope. A mechanism is also given which allows LDAP Directory Server Agents (DSA)s to advertise support of this search scope. 2. Application to SearchRequest.scope A new item is added to this ENUMERATED type. The identifier is subordinateSubtree and the number is 4. A DSA which receives and supports the subordinateSubtree SearchRequest.scope constrains the search scope to all subordinate objects. A DSA which receives but does not support the subordinateSubtree SearchRequest.scope returns a protocolError resultCode in the SearchResultDone. 3. LDAP URL applications The LDAP URL [RFC2255] specification allows the conveyance of a search scope. This section intoduces two ways in which the subordinateScope search scope may be conveyed in an LDAP URL. One way is by allowing a new "subord" scope in the <scope> part. Another way is through the introduction of an LDAP URL extension. The LDAP URL extension method is preferred for its criticality semantics. Sermersheim Expires December 30, 2004 [Page 2] Internet-Draft Subordinate Subtree Search Scope for LDAP July 2004 3.1 Application to LDAP URL <scope> A new <scope> value of "subord" is added. Using the <scope> type from LDAP URL [RFC2255], the ABNF is as follows: scope /= "subord" Implementations processing but which do not understand or support the "subord" <scope> of an LDAP URL raise an appropriate error. 3.2 Application to LDAP URL <extension> An LDAP URL <extension> mechanism is introduced here. The <extype> is IANA-ASSIGNED-OID.1 or the descriptor 'subordScope', and the exvalue is omitted. The extension may be marked as either critical or non-critical. If supported, the subordScope extension overrides any value set in the <scope> field. 4. DSA Advertisement of support A DSA may advertise its support of the subordinateSubtree item in the SearchRequest.scope by inclusion of IANA-ASSIGNED-OID.2 in the 'supportedFeatures' attribute of the root DSE. 5. Security Considerations This specification introduces no security concerns above any associated with the existing wholeSubtree search scope value. As with the wholeSubtree search scope, this scope specifies that a search be applied to an entire subtree hierarchy. Implementations should be aware of the relative cost of using or allowing this scope. 6 Normative References [RFC2251] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [RFC2255] Howes, T. and M. Smith, "The LDAP URL Format", RFC 2255, December 1997. [RFC3377] Hodges, J. and R. Morgan, "Lightweight Directory Access Protocol (v3): Technical Specification", RFC 3377, September 2002. [RFC3383] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Sermersheim Expires December 30, 2004 [Page 3] Internet-Draft Subordinate Subtree Search Scope for LDAP July 2004 Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 3383, September 2002. Author's Address Jim Sermersheim Novell, Inc 1800 South Novell Place Provo, Utah 84606 USA Phone: +1 801 861-3088 EMail: jimse@novell.com Appendix A. IANA Considerations Registration of the following values is requested [RFC3383]. A.1 LDAP Object Identifier Registrations It is requested that IANA register upon Standards Action an LDAP Object Identifier in identifying the protocol elements defined in this technical specification. The following registration template is provided: Subject: Request for LDAP OID Registration Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Specification: RFCXXXX Author/Change Controller: IESG Comments: 2 delegations will be made under the assigned OID: IANA-ASSIGNED-OID.1 subordScope LDAP URL extension IANA-ASSIGNED-OID.2 subordinateScope Supported Feature A.2 LDAP Protocol Mechanism Registrations It is requested that IANA register upon Standards Action the LDAP protocol mechanism described in this document. The following registration templates are given: Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: IANA-ASSIGNED-OID.1 Description: subordScope LDAP URL extension Person & email address to contact for further information: Sermersheim Expires December 30, 2004 [Page 4] Internet-Draft Subordinate Subtree Search Scope for LDAP July 2004 Jim Sermersheim jimse@novell.com Usage: Extension Specification: RFCXXXX Author/Change Controller: IESG Comments: none A.3 LDAP Descriptor Registrations It is requested that IANA register upon Standards Action the LDAP descriptors described in this document. The following registration templates are given: Subject: Request for LDAP Descriptor Registration Descriptor (short name): subordScope Object Identifier: IANA-ASSIGNED-OID.1 Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Usage: URL Extension Specification: RFCXXXX Author/Change Controller: IESG Comments: none Sermersheim Expires December 30, 2004 [Page 5] Internet-Draft Subordinate Subtree Search Scope for LDAP July 2004 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@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 (2004). 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 Expires December 30, 2004 [Page 6] PK /�c\U�x��N �N H doc/alt-openldap11-devel/drafts/draft-behera-ldap-password-policy-xx.txtnu �[��� Network Working Group J. Sermersheim Internet-Draft Novell, Inc Intended status: Standards Track L. Poitou Expires: January 19, 2015 Sun Microsystems H. Chu, Ed. Symas Corp. July 18, 2014 Password Policy for LDAP Directories draft-behera-ldap-password-policy-11 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 construction requirements, the re-use of old password is restricted, and to deter password guessing attacks. Status of this Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. 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." This Internet-Draft will expire on January 19, 2015. Copyright Notice Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents Sermersheim, et al. Expires January 19, 2015 [Page 1] Internet-Draft Password Policy for LDAP Directories July 2014 (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Sermersheim, et al. Expires January 19, 2015 [Page 2] Internet-Draft Password Policy for LDAP Directories July 2014 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 . . . . . . . . . . . . . . . . 8 4.3. Restriction of the Password Policy . . . . . . . . . . . . . 10 5. Schema used for Password Policy . . . . . . . . . . . . . . 12 5.1. The pwdPolicy Object Class . . . . . . . . . . . . . . . . . 12 5.2. Attribute Types used in the pwdPolicy ObjectClass . . . . . 12 5.3. Attribute Types for Password Policy State Information . . . 19 6. Controls used for Password Policy . . . . . . . . . . . . . 24 6.1. Request Control . . . . . . . . . . . . . . . . . . . . . . 24 6.2. Response Control . . . . . . . . . . . . . . . . . . . . . . 24 7. Policy Decision Points . . . . . . . . . . . . . . . . . . . 26 7.1. Locked Account Check . . . . . . . . . . . . . . . . . . . . 26 7.2. Password Must be Changed Now Check . . . . . . . . . . . . . 26 7.3. Password Expiration Check . . . . . . . . . . . . . . . . . 27 7.4. Remaining Grace AuthN Check . . . . . . . . . . . . . . . . 27 7.5. Time Before Expiration Check . . . . . . . . . . . . . . . . 27 7.6. Intruder Lockout Check . . . . . . . . . . . . . . . . . . . 27 7.7. Intruder Delay Check . . . . . . . . . . . . . . . . . . . . 28 7.8. Password Too Young Check . . . . . . . . . . . . . . . . . . 28 8. Server Policy Enforcement Points . . . . . . . . . . . . . . 29 8.1. Password-based Authentication . . . . . . . . . . . . . . . 29 8.2. Password Update Operations . . . . . . . . . . . . . . . . . 31 8.3. Other Operations . . . . . . . . . . . . . . . . . . . . . . 34 9. Client Policy Enforcement Points . . . . . . . . . . . . . . 35 9.1. Bind Operation . . . . . . . . . . . . . . . . . . . . . . . 35 9.2. Modify Operations . . . . . . . . . . . . . . . . . . . . . 36 9.3. Add Operation . . . . . . . . . . . . . . . . . . . . . . . 37 9.4. Compare Operation . . . . . . . . . . . . . . . . . . . . . 37 9.5. Other Operations . . . . . . . . . . . . . . . . . . . . . . 38 10. Administration of the Password Policy . . . . . . . . . . . 39 11. Password Policy and Replication . . . . . . . . . . . . . . 40 12. Security Considerations . . . . . . . . . . . . . . . . . . 42 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . 43 13.1. Object Identifiers . . . . . . . . . . . . . . . . . . . . . 43 13.2. LDAP Protocol Mechanisms . . . . . . . . . . . . . . . . . . 43 13.3. LDAP Descriptors . . . . . . . . . . . . . . . . . . . . . . 43 13.4. LDAP AttributeDescription Options . . . . . . . . . . . . . 45 14. Acknowledgement . . . . . . . . . . . . . . . . . . . . . . 46 15. Normative References . . . . . . . . . . . . . . . . . . . . 47 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 48 Sermersheim, et al. Expires January 19, 2015 [Page 3] Internet-Draft Password Policy for LDAP Directories July 2014 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, et al. Expires January 19, 2015 [Page 4] Internet-Draft Password Policy for LDAP Directories July 2014 2. Conventions Imperative keywords defined in [RFC2119] are used in this document, and carry the meanings described there. All ASN.1 [X.680] Basic Encoding Rules (BER) [X.690] encodings follow the conventions found in Section 5.1 of [RFC4511]. 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, et al. Expires January 19, 2015 [Page 5] Internet-Draft Password Policy for LDAP Directories July 2014 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 [RFC4511] or the case of password based SASL [RFC4422] 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, et al. Expires January 19, 2015 [Page 6] Internet-Draft Password Policy for LDAP Directories July 2014 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 Validity Policy These mechanisms allow account usage to be controlled independent of any password expiration policies. The policy defines the absolute period of time for which an account may be used. This allows an administrator to define an absolute starting time after which a password becomes valid, and an absolute ending time after which the password is disabled. A mechanism is also provided to define the period of time for which an account may remain unused before being disabled. 4.1.2. 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 several parts: o A counter to track the number of failed authentication attempts. o The amount of time to delay on the first authentication failure. o The maximum amount of time to delay on subsequent failures. o A timeframe in which the limit of consecutive failed authentication attempts must happen before action is taken. o A configurable limit on failed authentication attempts. o The action to be taken when the limit is reached. The action will either be nothing, or the account will be locked. Sermersheim, et al. Expires January 19, 2015 [Page 7] Internet-Draft Password Policy for LDAP Directories July 2014 o An amount of time the account is locked (if it is to be locked). This can be indefinite. Note that using the account lock feature provides an easy avenue for Denial-of-Service (DoS) attacks on user accounts. While some sites' policies require accounts to be locked, this feature is discouraged in favor of delaying each failed login attempt. The delay time will be doubled on each subsequent failure, until it reaches the maximum time configured. [TBD: we could also provide a syntax for configuring a backoff algorithm. E.g. "+<int>" for linearly incrementing delay, "x<int>" for constant multiplier, "^<int> for geometric. But it's probably overkill to add a calculator language to the server.] 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. 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. Sermersheim, et al. Expires January 19, 2015 [Page 8] Internet-Draft Password Policy for LDAP Directories July 2014 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 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: Sermersheim, et al. Expires January 19, 2015 [Page 9] Internet-Draft Password Policy for LDAP Directories July 2014 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. 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, Sermersheim, et al. Expires January 19, 2015 [Page 10] Internet-Draft Password Policy for LDAP Directories July 2014 contains one and only one password value. Sermersheim, et al. Expires January 19, 2015 [Page 11] Internet-Draft Password Policy for LDAP Directories July 2014 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 $ pwdMaxLength $ pwdExpireWarning $ pwdGraceAuthNLimit $ pwdGraceExpiry $ pwdLockout $ pwdLockoutDuration $ pwdMaxFailure $ pwdFailureCountInterval $ pwdMustChange $ pwdAllowUserChange $ pwdSafeModify $ pwdMinDelay $ pwdMaxDelay $ pwdMaxIdle ) ) 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, et al. Expires January 19, 2015 [Page 12] Internet-Draft Password Policy for LDAP Directories July 2014 ( 1.3.6.1.4.1.42.2.27.8.1.2 NAME 'pwdMinAge' EQUALITY integerMatch ORDERING integerOrderingMatch 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 ORDERING integerOrderingMatch 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 ORDERING integerOrderingMatch 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, et al. Expires January 19, 2015 [Page 13] Internet-Draft Password Policy for LDAP Directories July 2014 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 ORDERING integerOrderingMatch 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 ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) 5.2.7. pwdMaxLength When quality checking is enabled, this attribute holds the maximum number of characters that may be used in a password. If this attribute is not present, no maximum 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'). Sermersheim, et al. Expires January 19, 2015 [Page 14] Internet-Draft Password Policy for LDAP Directories July 2014 ( 1.3.6.1.4.1.42.2.27.8.1.31 NAME 'pwdMaxLength' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) 5.2.8. 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 ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) 5.2.9. 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 ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) 5.2.10. pwdGraceExpiry This attribute specifies the number of seconds the grace authentications are valid. If this attribute is not present or if the value is 0, there is no time limit on the grace authentications. ( 1.3.6.1.4.1.42.2.27.8.1.30 NAME 'pwdGraceExpire' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 Sermersheim, et al. Expires January 19, 2015 [Page 15] Internet-Draft Password Policy for LDAP Directories July 2014 SINGLE-VALUE ) 5.2.11. 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.12. 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 ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) 5.2.13. 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 ORDERING integerOrderingMatch SINGLE-VALUE ) Sermersheim, et al. Expires January 19, 2015 [Page 16] Internet-Draft Password Policy for LDAP Directories July 2014 5.2.14. 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 ORDERING integerOrderingMatch SINGLE-VALUE ) 5.2.15. 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 ) 5.2.16. 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 absence 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 ) Sermersheim, et al. Expires January 19, 2015 [Page 17] Internet-Draft Password Policy for LDAP Directories July 2014 5.2.17. 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.2.18. pwdMinDelay This attribute specifies the number of seconds to delay responding to the first failed authentication attempt. If this attribute is not set or is 0, no delays will be used. pwdMaxDelay must also be specified if pwdMinDelay is set. ( 1.3.6.1.4.1.42.2.27.8.1.24 NAME 'pwdMinDelay' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) 5.2.19. pwdMaxDelay This attribute specifies the maximum number of seconds to delay when responding to a failed authentication attempt. The time specified in pwdMinDelay is used as the starting time and is then doubled on each failure until the delay time is greater than or equal to pwdMaxDelay (or a successful authentication occurs, which resets the failure counter). pwdMinDelay must be specified if pwdMaxDelay is set. ( 1.3.6.1.4.1.42.2.27.8.1.25 NAME 'pwdMaxDelay' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) 5.2.20. pwdMaxIdle This attribute specifies the number of seconds an account may remain unused before it becomes locked. If this attribute is not set or is 0, no check is performed. Sermersheim, et al. Expires January 19, 2015 [Page 18] Internet-Draft Password Policy for LDAP Directories July 2014 ( 1.3.6.1.4.1.42.2.27.8.1.26 NAME 'pwdMaxIdle' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 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, pwdStartTime, pwdEndTime, pwdLastSuccess. 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 is 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. 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. Sermersheim, et al. Expires January 19, 2015 [Page 19] Internet-Draft Password Policy for LDAP Directories July 2014 ( 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 ) 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: Sermersheim, et al. Expires January 19, 2015 [Page 20] Internet-Draft Password Policy for LDAP Directories July 2014 pwdHistory = time "#" syntaxOID "#" length "#" data time = GeneralizedTime syntaxOID = numericoid ; the string representation of the ; dotted-decimal OID that defines the ; syntax used to store the password. length = number ; the number of octets in data. data = <octets representing the password in the format specified by syntaxOID>. GeneralizedTime is specified in 3.3.13 of [RFC4517]. numericoid and number are specified in 1.4 of [RFC4512]. 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' 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. Sermersheim, et al. Expires January 19, 2015 [Page 21] Internet-Draft Password Policy for LDAP Directories July 2014 ( 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 USAGE directoryOperation ) 5.3.9. pwdStartTime This attribute specifies the time the entry's password becomes valid for authentication. Authentication attempts made before this time will fail. If this attribute does not exist, then no restriction applies. ( 1.3.6.1.4.1.42.2.27.8.1.27 NAME 'pwdStartTime' DESC 'The time the password becomes enabled' 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.10. pwdEndTime This attribute specifies the time the entry's password becomes invalid for authentication. Authentication attempts made after this time will fail, regardless of expiration or grace settings. If this attribute does not exist, then this restriction does not apply. Sermersheim, et al. Expires January 19, 2015 [Page 22] Internet-Draft Password Policy for LDAP Directories July 2014 ( 1.3.6.1.4.1.42.2.27.8.1.28 NAME 'pwdEndTime' DESC 'The time the password becomes disabled' EQUALITY generalizedTimeMatch ORDERING generalizedTimeOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 SINGLE-VALUE NO-USER-MODIFICATION USAGE directoryOperation ) Note that pwdStartTime may be set to a time greater than or equal to pwdEndTime; this simply disables the account. 5.3.11. pwdLastSuccess This attribute holds the timestamp of the last successful authentication. ( 1.3.6.1.4.1.42.2.27.8.1.29 NAME 'pwdLastSuccess' DESC 'The timestamp of the last successful authentication' EQUALITY generalizedTimeMatch ORDERING generalizedTimeOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 SINGLE-VALUE NO-USER-MODIFICATION USAGE directoryOperation ) Sermersheim, et al. Expires January 19, 2015 [Page 23] Internet-Draft Password Policy for LDAP Directories July 2014 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, et al. Expires January 19, 2015 [Page 24] Internet-Draft Password Policy for LDAP Directories July 2014 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, et al. Expires January 19, 2015 [Page 25] Internet-Draft Password Policy for LDAP Directories July 2014 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 pwdStartTime attribute. o The current time is greater than or equal to the value of the pwdEndTime attribute. o The current time is greater than or equal to the value of the pwdLastSuccess attribute added to the value of the pwdMaxIdle attribute. 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 password must be changed if all of these conditions are met: o The pwdMustChange attribute is set to TRUE. o The pwdReset attribute is set to TRUE. Otherwise a status of false is returned. Sermersheim, et al. Expires January 19, 2015 [Page 26] Internet-Draft Password Policy for LDAP Directories July 2014 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 pwdGraceExpiry attribute is present, and the current time is greater than the password expiration time plus the pwdGraceExpiry value, zero is returned. 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 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 Lockout Check A status of true indicating that an intruder has been detected is returned if the following conditions are met: o The pwdLockout attribute is TRUE. o 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. Sermersheim, et al. Expires January 19, 2015 [Page 27] Internet-Draft Password Policy for LDAP Directories July 2014 7.7. Intruder Delay Check If the pwdMinDelay attribute is 0 or not set, zero is returned. Otherwise, a delay time is computed based on the number of values in the pwdFailureTime attribute. If the computed value is greater than the pwdMaxDelay attribute, the pwdMaxDelay value is returned. While performing this check, values of pwdFailureTime that are old by more than pwdFailureCountInterval are purged and not counted. 7.8. Password Too Young Check If the Section 7.2 check returned true then this check will return false, to allow the password to be changed. A status of true indicating that not enough time has passed since the password was last updated is returned if: o The value of pwdMinAge is non-zero and pwdChangedTime is present. o The value of pwdMinAge is greater than the current time minus the value of pwdChangedTime. Otherwise a false status is returned. Sermersheim, et al. Expires January 19, 2015 [Page 28] Internet-Draft Password Policy for LDAP Directories July 2014 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. Note: The case where a single password value is stored in multiple formats simultaneously is still considered to be 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 successfully 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. Sermersheim, et al. Expires January 19, 2015 [Page 29] Internet-Draft Password Policy for LDAP Directories July 2014 Set the value of the pwdLastSuccess attribute to the current time. Note: setting pwdLastSuccess is optional, but it is required if the policy has pwdMaxIdle defined. 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. 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. Sermersheim, et al. Expires January 19, 2015 [Page 30] Internet-Draft Password Policy for LDAP Directories July 2014 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. 8.1.3. AuthN Failed Procedures If the authentication process indicates that the password failed validation due to invalid credentials, these procedures are followed: 8.1.3.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.3.2. Handle 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). If the check in Section 7.7 returns a non-zero value, the server waits that number of seconds before sending the authentication response back to the client. 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: Sermersheim, et al. Expires January 19, 2015 [Page 31] Internet-Draft Password Policy for LDAP Directories July 2014 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. 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.8 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). Sermersheim, et al. Expires January 19, 2015 [Page 32] Internet-Draft Password Policy for LDAP Directories July 2014 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 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 Sermersheim, et al. Expires January 19, 2015 [Page 33] Internet-Draft Password Policy for LDAP Directories July 2014 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 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, et al. Expires January 19, 2015 [Page 34] Internet-Draft Password Policy for LDAP Directories July 2014 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, et al. Expires January 19, 2015 [Page 35] Internet-Draft Password Policy for LDAP Directories July 2014 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, et al. Expires January 19, 2015 [Page 36] Internet-Draft Password Policy for LDAP Directories July 2014 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, et al. Expires January 19, 2015 [Page 37] Internet-Draft Password Policy for LDAP Directories July 2014 9.5. Other Operations For operations other than bind, unbind, abandon or StartTLS, the client checks the result code and control to determine if the user needs to change the password immediately. o <Response>.resultCode = insufficientAccessRights (50), passwordPolicyResponse.error = changeAfterReset (2) : The user needs to change the password immediately. Sermersheim, et al. Expires January 19, 2015 [Page 38] Internet-Draft Password Policy for LDAP Directories July 2014 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. Only one policy may be in effect for a given password attribute in any entry. If multiple policies exist which overlap in the range of entries affected, the resulting behavior is undefined. 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, et al. Expires January 19, 2015 [Page 39] Internet-Draft Password Policy for LDAP Directories July 2014 11. Password Policy and Replication {TODO: This section needs to be changed to highlight the pitfalls of replication, suggest some implementation choices to overcome those pitfalls, 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 SHOULD 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. Note: there are some situations where global replication of these state attributes may not be desired. For example, if two clusters of replicas are geographically remote and joined by a slow network link, and their users only login from one of the two locations, it may be unnecessary to propagate all of the state changes from one cluster to the other. Servers SHOULD allow administrators to control which attributes are replicated on a case-by-case basis. Sermersheim, et al. Expires January 19, 2015 [Page 40] Internet-Draft Password Policy for LDAP Directories July 2014 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, et al. Expires January 19, 2015 [Page 41] Internet-Draft Password Policy for LDAP Directories July 2014 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 [RFC4513]. 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. Using the login delay instead of the lockout mechanism will also help avoid this denial of service. 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, et al. Expires January 19, 2015 [Page 42] Internet-Draft Password Policy for LDAP Directories July 2014 13. IANA Considerations In accordance with [RFC4520] the following registrations are requested. 13.1. Object Identifiers The OIDs used in this specification are derived from iso(1) identified-organization(3) dod(6) internet(1) private(4) enterprise(1) Sun(42) products(2) LDAP(27) ppolicy(8). These OIDs have been in use since at least July 2001 when version 04 of this draft was published. No additional OID assignment is being requested. 13.2. LDAP Protocol Mechanisms Registration of the protocol mechanisms specified in this document is requested. Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: 1.3.6.1.4.1.42.2.27.8.5.1 Description: Password Policy Request and Response Control Person & email address to contact for further information: Howard Chu <hyc@symas.com> Usage: Control Specification: (I-D) draft-behera-ldap-password-policy Author/Change Controller: IESG Comments: 13.3. LDAP Descriptors Registration of the descriptors specified in this document is requested. Subject: Request for LDAP Descriptor Registration Descriptor (short name): see table Object Identifier: see table Sermersheim, et al. Expires January 19, 2015 [Page 43] Internet-Draft Password Policy for LDAP Directories July 2014 Description: see table Person & email address to contact for further information: Howard Chu <hyc@symas.com> Specification: (I-D) draft-behera-ldap-password-policy Author/Change Controller: IESG Comments: Name Type OID ----------------------- ---- ------------------------------ pwdPolicy O 1.3.6.1.4.1.42.2.27.8.2.1 pwdAttribute A 1.3.6.1.4.1.42.2.27.8.1.1 pwdMinAge A 1.3.6.1.4.1.42.2.27.8.1.2 pwdMaxAge A 1.3.6.1.4.1.42.2.27.8.1.3 pwdInHistory A 1.3.6.1.4.1.42.2.27.8.1.4 pwdCheckQuality A 1.3.6.1.4.1.42.2.27.8.1.5 pwdMinLength A 1.3.6.1.4.1.42.2.27.8.1.6 pwdMaxLength A 1.3.6.1.4.1.42.2.27.8.1.31 pwdExpireWarning A 1.3.6.1.4.1.42.2.27.8.1.7 pwdGraceAuthNLimit A 1.3.6.1.4.1.42.2.27.8.1.8 pwdGraceExpiry A 1.3.6.1.4.1.42.2.27.8.1.30 pwdLockout A 1.3.6.1.4.1.42.2.27.8.1.9 pwdLockoutDuration A 1.3.6.1.4.1.42.2.27.8.1.10 pwdMaxFailure A 1.3.6.1.4.1.42.2.27.8.1.11 pwdFailureCountInterval A 1.3.6.1.4.1.42.2.27.8.1.12 pwdMustChange A 1.3.6.1.4.1.42.2.27.8.1.13 pwdAllowUserChange A 1.3.6.1.4.1.42.2.27.8.1.14 pwdSafeModify A 1.3.6.1.4.1.42.2.27.8.1.15 pwdMinDelay A 1.3.6.1.4.1.42.2.27.8.1.24 pwdMaxDelay A 1.3.6.1.4.1.42.2.27.8.1.25 pwdMaxIdle A 1.3.6.1.4.1.42.2.27.8.1.26 pwdChangedTime A 1.3.6.1.4.1.42.2.27.8.1.16 pwdAccountLockedTime A 1.3.6.1.4.1.42.2.27.8.1.17 pwdFailureTime A 1.3.6.1.4.1.42.2.27.8.1.19 pwdHistory A 1.3.6.1.4.1.42.2.27.8.1.20 pwdGraceUseTime A 1.3.6.1.4.1.42.2.27.8.1.21 pwdReset A 1.3.6.1.4.1.42.2.27.8.1.22 pwdPolicySubEntry A 1.3.6.1.4.1.42.2.27.8.1.23 pwdStartTime A 1.3.6.1.4.1.42.2.27.8.1.27 pwdEndTime A 1.3.6.1.4.1.42.2.27.8.1.28 pwdLastSuccess A 1.3.6.1.4.1.42.2.27.8.1.29 Sermersheim, et al. Expires January 19, 2015 [Page 44] Internet-Draft Password Policy for LDAP Directories July 2014 Legend -------------------- A => Attribute Type O => Object Class 13.4. LDAP AttributeDescription Options Registration of the AttributeDescription option specified in this document is requested. Subject: Request for LDAP Attribute Description Option Registration Option Name: pwd- Family of Options: YES Person & email address to contact for further information: Howard Chu <hyc@symas.com> Specification: (I-D) draft-behera-ldap-password-policy Author/Change Controller: IESG Comments: Used with policy state attributes to specify to which password attribute the state belongs. Sermersheim, et al. Expires January 19, 2015 [Page 45] Internet-Draft Password Policy for LDAP Directories July 2014 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. Sermersheim, et al. Expires January 19, 2015 [Page 46] Internet-Draft Password Policy for LDAP Directories July 2014 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. [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. [RFC3672] Zeilenga, K., "Subentries in the Lightweight Directory Access Protocol (LDAP)", RFC 3672, December 2003. [RFC4422] Melnikov, A. and K. Zeilenga, "Simple Authentication and Security Layer (SASL)", RFC 4422, June 2006. [RFC4511] Sermersheim, J., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006. [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006. [RFC4513] Harrison, R., "Lightweight Directory Access Protocol (LDAP): Authentication Methods and Security Mechanisms", RFC 4513, June 2006. [RFC4517] Legg, S., "Lightweight Directory Access Protocol (LDAP): Syntaxes and Matching Rules", RFC 4517, June 2006. [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006. [X.680] International Telecommunications Union, "Abstract Syntax Notation One (ASN.1): Specification of basic notation", ITU-T Recommendation X.680, July 2002. [X.690] International Telecommunications Union, "Information Technology - ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER)", ITU-T Recommendation X.690, July 2002. Sermersheim, et al. Expires January 19, 2015 [Page 47] Internet-Draft Password Policy for LDAP Directories July 2014 Authors' Addresses Jim Sermersheim Novell, Inc 1800 South Novell Place Provo, Utah 84606 US Phone: +1 801 861-3088 Email: jimse@novell.com Ludovic Poitou Sun Microsystems 180, Avenue de l'Europe Zirst de Montbonnot, Saint Ismier cedex 38334 FR Phone: +33 476 188 212 Email: ludovic.poitou@sun.com Howard Chu (editor) Symas Corp. 18740 Oxnard Street, Suite 313A Tarzana, California 91356 US Phone: +1 818 757-7087 Email: hyc@symas.com Sermersheim, et al. Expires January 19, 2015 [Page 48] PK /�c\J� I I F doc/alt-openldap11-devel/drafts/draft-sermersheim-ldap-distproc-xx.txtnu �[��� Network Working Group J. Sermersheim Internet-Draft Novell, Inc Expires: August 26, 2005 February 22, 2005 Distributed Procedures for LDAP Operations draft-sermersheim-ldap-distproc-02.txt Status of this Memo This document is an Internet-Draft and is subject to all provisions of Section 3 of RFC 3667. 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 become aware will be disclosed, in accordance with RFC 3668. 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 August 26, 2005. Copyright Notice Copyright (C) The Internet Society (2005). Abstract This document provides the data types and procedures used while servicing Lightweight Directory Access Protocol (LDAP) user operations in order to participate in a distributed directory. In particular, it describes the way in which an LDAP user operation in a distributed directory environment finds its way to the proper DSA(s) for servicing. Sermersheim Expires August 26, 2005 [Page 1] Internet-Draft Distributed Procedures for LDAP Operations February 2005 Discussion Forum Technical discussion of this document will take place on the IETF LDAP Extensions mailing list <ldapext@ietf.org>. Please send editorial comments directly to the author. Table of Contents 1. Distributed Operations Overview . . . . . . . . . . . . . . 3 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Distributed Operation Data Types . . . . . . . . . . . . . . 5 3.1 ContinuationReference . . . . . . . . . . . . . . . . . . . 5 3.2 ChainedRequest . . . . . . . . . . . . . . . . . . . . . . . 9 3.3 Chained Response . . . . . . . . . . . . . . . . . . . . . . 11 4. Distributed Procedures . . . . . . . . . . . . . . . . . . . 14 4.1 Name resolution . . . . . . . . . . . . . . . . . . . . . . 14 4.2 Operation Evaluation . . . . . . . . . . . . . . . . . . . . 16 4.3 Populating the ContinuationReference . . . . . . . . . . . . 19 4.4 Sending a ChainedRequest . . . . . . . . . . . . . . . . . . 21 4.5 Emulating the Sending of a ChainedRequest . . . . . . . . . 23 4.6 Receiving a ChainedRequest . . . . . . . . . . . . . . . . . 24 4.7 Returning a Chained Response . . . . . . . . . . . . . . . . 25 4.8 Receiving a Chained Response . . . . . . . . . . . . . . . . 26 4.9 Returning a Referral or Intermediate Referral . . . . . . . 27 4.10 Acting on a Referral or Intermediate Referral . . . . . . . 30 4.11 Ensuring non-existence of an entry under an nssr . . . . . . 31 4.12 Mapping a referralURI to an LDAP URI . . . . . . . . . . . . 31 4.13 Using the ManageDsaIT control . . . . . . . . . . . . . . . 32 5. Security Considerations . . . . . . . . . . . . . . . . . . 33 6. Normative References . . . . . . . . . . . . . . . . . . . . 33 Author's Address . . . . . . . . . . . . . . . . . . . . . . 34 A. IANA Considerations . . . . . . . . . . . . . . . . . . . . 35 A.1 LDAP Object Identifier Registrations . . . . . . . . . . . . 35 A.2 LDAP Protocol Mechanism Registrations . . . . . . . . . . . 35 A.3 LDAP Descriptor Registrations . . . . . . . . . . . . . . . 37 A.4 LDAP Result Code Registrations . . . . . . . . . . . . . . . 38 Intellectual Property and Copyright Statements . . . . . . . 39 Sermersheim Expires August 26, 2005 [Page 2] Internet-Draft Distributed Procedures for LDAP Operations February 2005 1. Distributed Operations Overview One characteristic of X.500-based directory systems [X500] is that, given a distributed Directory Information Tree (DIT), a user should potentially be able to have any service request satisfied (subject to security, access control, and administrative policies) irrespective of the Directory Service Agent (DSA) to which the request was sent. To accommodate this requirement, it is necessary that any DSA involved in satisfying a particular service request have some knowledge (as specified in {TODO: Link to future Distributed Data Model doc}) of where the requested information is located and either return this knowledge to the requester or attempt to satisfy the request satisfied on the behalf of the requester (the requester may either be a Directory User Agent (DUA) or another DSA). Two modes of operation distribution are defined to meet these requirements, namely "chaining" and "returning referrals". "Chaining" refers to the attempt by a DSA to satisfy a request by sending one or more chained operations to other DSAs. "Returning referrals", is the act of returning distributed knowledge information to the requester, which may then itself interact with the DSA(s) identified by the distributed knowledge information. It is a goal of this document to provide the same level of service whether the chaining or referral mechanism is used to distribute an operation. The processing of an operation is talked about in two major phases, namely "name resolution", and "operation evaluation". Name resolution is the act of locating a local DSE held on a DSA given a distinguished name (DN). Operation evaluation is the act of performing the operation after the name resolution phase is complete. While distributing an operation, a request operation may be decomposed into several sub-operations. The distributed directory operation procedures described in this document assume the absense of the ManageDsaIT control defined in [RFC3296] and described in Section 4.13. Sermersheim Expires August 26, 2005 [Page 3] Internet-Draft Distributed Procedures for LDAP Operations February 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]. Sermersheim Expires August 26, 2005 [Page 4] Internet-Draft Distributed Procedures for LDAP Operations February 2005 3. Distributed Operation Data Types The data types in this section are used by the chaining and referral distributed operation mechanisms described in Section 4 3.1 ContinuationReference As an operation is being processed by a DSA, it is useful to group the information passed between various procedures as a collection of data. The ContinuationReference data type is introduced for this purpose. This data type is populated and consumed by various procedures discussed in various sections of this document. In general, a ContinuationReference is used when indicating that directory information being acted on is not present locally, but may be present elsewhere. A ContinuationReference consists of one or more addresses which identify remote DSAs along with other information pertaining both to the distributed knowledge information held on the local DSA as well as information relevant to the operation. This data type is expressed here in Abstract Syntax Notation One (ASN.1) [X680]. ContinuationReference ::= SET { referralURI [0] SET SIZE (1..MAX) OF URI, localReference [2] LDAPDN, referenceType [3] ReferenceType, remainingName [4] RelativeLDAPDN OPTIONAL, searchScope [5] SearchScope OPTIONAL, searchedSubtrees [6] SearchedSubtrees OPTIONAL, failedName [7] LDAPDN OPTIONAL, ... } <Editor's Note: Planned for addition is a searchCriteria field which is used both for assuring that the remote object is in fact the object originally pointed to (this mechanism provides a security measure), and also to allow moved or renamed remote entries to be found. Typically the search criteria would have a filter value of (entryUUID=<something>)> URI ::= LDAPString -- limited to characters permitted in URIs [RFC2396]. ReferenceType ::= ENUMERATED { superior (0), subordinate (1), cross (2), nonSpecificSubordinate (3), Sermersheim Expires August 26, 2005 [Page 5] Internet-Draft Distributed Procedures for LDAP Operations February 2005 suplier (4), master (5), immediateSuperior (6), self (7), ... } SearchScope ::= ENUMERATED { baseObject (0), singleLevel (1), wholeSubtree (2), subordinateSubtree (3), ... } SearchedSubtrees ::= SET OF RelativeLDAPDN LDAPDN, RelativeLDAPDN, and LDAPString, are defined in [RFC2251]. The following subsections introduce the fields of the ContinuationReference data type, but do not provide in-depth semantics or instructions on the population and consumption of the fields. These topics are discussed as part of the procedural instructions. 3.1.1 ContinuationReference.referralURI The list of referralURI values is used by the receiver to progress the operation. Each value specifies (at minimum) the protocol and address of one or more remote DSA(s) holding the data sought after. URI values which are placed in ContinuationReference.referralURI must allow for certain elements of data to be conveyed. Section 3.1.1.1 describes these data elements. Furthermore, a mapping must exist which relates the parts of a specified URI to these data elements. This document provides such a mapping for the LDAP URL [RFC2255] in Section 4.12. In some cases, a referralURI will contain data which has a counterpart in the fields of the ContinuationReference (an example is where the referralURI is an LDAP URL, holds a <scope> value, and the ContinuationReference.searchScope field is also present). In these cases, the data held on the referralURI overrides the field in the ContinuationReference. Specific examples of this are highlighted in other sections. Providing a means for these values to exist as fields of the ContinuationReference allows one value to be applied to all values of referralURI (as opposed to populating duplicate data on all referralURI values). If a referralURI value identifies an LDAP-enabled DSA [RFC3377], the LDAP URL form is used. Sermersheim Expires August 26, 2005 [Page 6] Internet-Draft Distributed Procedures for LDAP Operations February 2005 3.1.1.1 Elements of referralURI Values The following data elements must be allowed and identified for a specified URI type to be used to convey referral information. Each element is given a name which begins with 'referralURI.' for clarity when referencing the elements conceptually in other parts of this document. o referralURI.protocolIdentifier. There must be an indication of the protocol to be used to contact the DSA identified by the URI. o referralURI.accessPoint. The URI must identify a DSA in a manner that can be used to contact it using the protocol specified in protocolIdentifier. o referralURI.targetObject. Holds the name to be used as the base DN of the operation being progressed. This field must be allowed by the URI specification, but may be omitted in URI instances for various reasons. o referralURI.localReference. See Section 3.1.2. This field must be allowed by the URI specification, but may be omitted in URI instances for various reasons. o referralURI.searchScope. See Section 3.1.5. This field must be allowed by the URI specification, but may be omitted in URI instances for various reasons. o referralURI.searchedSubtrees. See Section 3.1.6. This field must be allowed by the URI specification, but may be omitted in URI instances for various reasons. o referralURI.failedName. See Section 3.1.7. This field must be allowed by the URI specification, but may be omitted in URI instances for various reasons. 3.1.2 ContinuationReference.localReference This names the DSE which was found to hold distributed knowledge information, and thus which caused the ContinuationReference to be formed. This field is primarily used to help convey the new target object name, but may also be used for purposes referential integrity (not discussed here). In the event that the root object holds the distributed knowledge information, this field is present and is populated with an empty DN. 3.1.3 ContinuationReference.referenceType Indicates the DSE Type of the ContinuationReference.localReference. This field may be used to determine how to progress an operations (i.e. if the value is nonSpecificSubordinate, a search continuation will exclude the ContinuationReference.referenceType). Sermersheim Expires August 26, 2005 [Page 7] Internet-Draft Distributed Procedures for LDAP Operations February 2005 3.1.4 ContinuationReference.remainingName In certain scenarios, the localReference does not completely name the DSE to be used as the new target object name. In these cases, remainingName is populated with the RDNSequence relative to the localReference of the target object name being resolved. Some examples of these scenarios include (but are not restricted to): o During name resolution, the name is not fully resolved, but a DSE holding distributed knowledge information is found, causing a ContinuationReference to be generated. o While searching, an alias is dereferenced. The aliasedObjectName points to a DSE of type glue which is subordinate to a DSE holding distributed knowledge information. 3.1.5 ContinuationReference.searchScope Under certain circumstances, when progressing a search operation, a search scope different than that of the original search request must be used. This field facilitates the conveyance of the proper search scope to be used when progressing the distributed operation. The scope of subordinateSubtree has been added to the values allowed by the LDAP SearchRequest.scope field. This scope includes the subtree of entries below the base DN, but does not include the base DN itself. This is used here when progressing distributed search operations caused by the existence of a DSE of type nssr. If a referralURI.searchScope is present, it overrides this field while that referralURI is being operated upon. 3.1.6 ContinuationReference.searchedSubtrees For ContinuationReferences generated while processing a search operation with a scope of wholeSubtree, each value of this field indicates that a particular subtree below the target object has already been searched. Consumers of this data use it to cause the progression of the search operation to exclude these subtrees as a mechanism to avoid receiving duplicate entries. If a referralURI.searchedSubtrees is present, it overrides this field while that referralURI is being operated upon. 3.1.7 ContinuationReference.failedName When an operation requires that multiple names be resolved (as is the case with the ModifyDN operation), this field is used to specify which name was found to be non-local. Sermersheim Expires August 26, 2005 [Page 8] Internet-Draft Distributed Procedures for LDAP Operations February 2005 If a referralURI.failedName is present, it overrides this field while that referralURI is being operated upon. 3.2 ChainedRequest The Chained Request is sent as an LDAP extended operation. The requestName is IANA-ASSIGNED-OID.1. The requestValue is the BER encoding of the following ChainedRequestValue ASN.1 definition: ChainedRequestValue ::= SEQUENCE { chainingArguments ChainingArguments, operationRequest OperationRequest } ChainingArguments ::= SEQUENCE { targetObject [0] LDAPDN OPTIONAL, referenceType [1] ReferenceType, traceInformation [2] ChainingTraceInformation, searchScope [3] SearchScope OPTIONAL, searchedSubtrees [4] SearchedSubtrees OPTIONAL} ChainingTraceInformation ::= SET OF LDAPURL OperationRequest ::= SEQUENCE { Request ::= CHOICE { bindRequest BindRequest, searchRequest SearchRequest, modifyRequest ModifyRequest, addRequest AddRequest, delRequest DelRequest, modDNRequest ModifyDNRequest, compareRequest CompareRequest, extendedReq ExtendedRequest, ... }, controls [0] Controls COPTIONAL } BindRequest, SearchRequest, ModifyRequest, AddRequest, DelRequest, ModifyDNRequest, CompareRequest, ExtendedRequest and Controls are defined in [RFC2251]. 3.2.1 ChainedRequestValue.chainingArguments In general, these fields assist in refining the original operation as it is to be executed on the receiving DSA. Sermersheim Expires August 26, 2005 [Page 9] Internet-Draft Distributed Procedures for LDAP Operations February 2005 3.2.1.1 ChainedRequestValue.chainingArguments.targetObject This field contains the new target (or base) DN for the operation. The sending DSA populates this under different scenarios including the case where an alias has been dereferenced while resolving the DN, and also the case where a referral carries a target name different from the reference object that caused the referral. This field can be omitted only if it would be the the same value as the object or base object parameter in the ChainedRequestValue.operationRequest, in which case its implied value is that value. The receiving DSA examines this field and (if present) uses it rather than the base DN held in the ChainedRequestValue.operationRequest. 3.2.1.2 ChainedRequestValue.chainingArguments.referenceType See Section 3.1.3. If the receiver encounters a value of nonSpecificSubordinate in this field, it indicates that the operation is being chained due to DSE of type nssr. In this case, the receiver allows (and expects) the base DN to name the immediate superior of a context prefix. 3.2.1.3 ChainedRequestValue.chainingArguments.traceInformation This contains a set of URIs. Each value represents the address of a DSA and DN that has already been contacted while attempting to service the operation. This field is used to detect looping while servicing a distributed operation. The sending DSA populates this with its own URI, and also the URIs of any DSAs that have already been chained to. The receiving DSA examines this list of URIs and returns a loopDetect error if it finds that any of the addresses and DNs in the listed URI's represent it's own. 3.2.1.4 ChainedRequestValue.chainingArguments.searchScope See Section 3.1.5. 3.2.1.5 ChainedRequestValue.chainingArguments.searchedSubtrees See Section 3.1.6. Sermersheim Expires August 26, 2005 [Page 10] Internet-Draft Distributed Procedures for LDAP Operations February 2005 3.2.2 ChainedRequestValue.operationRequest This holds the original LDAP operation request. This is restricted to a subset of all LDAP operations. Namely, the following LDAP operation types are not allowed: o Abandon/Cancel operations. When an abandon or cancel operation needs to be chained, it is sent to the remote DSA as-is. This is because there is no need to track it for loop detection or pass on any other information normally found in ChainingArguments. o Unbind. Again, there is no need to send chaining-related information to a DSA to perform an unbind. DSAs which chain operations maintain connections as they see fit. o Chained Operation. When a DSA receives a chained operation, and must again chain that operation to a remote DSA, it sends a ChainedRequest where the ChainedRequestValue.operationRequest is that of the incoming ChainedRequestValue.operationRequest. 3.3 Chained Response The Chained Response is sent as an LDAP IntermediateResponse [RFC3771], or LDAP ExtendedResponse [RFC2251], depending on whether the operation is complete or not. In either case, the responseName is omitted. For intermediate responses, the IntermediateResponse.responseValue is the BER encoding of the ChainedIntermediateResponseValue ASN.1 definition. For completed operations, the ExtendedResponse.value is the BER encoding of the ChainedFinalResponseValue ASN.1 definition. ChainedIntermediateResponseValue ::= SEQUENCE { chainedResults ChainingResults, operationResponse IntermediateResponse } ChainedFinalResponseValue ::= SEQUENCE { chainedResults ChainingResults, operationResponse FinalResponse } ChainingResults ::= SEQUENCE { searchedSubtrees [0] SearchedSubtrees OPTIONAL, ... } IntermediateResponse ::= SEQUENCE { Response ::= CHOICE { Sermersheim Expires August 26, 2005 [Page 11] Internet-Draft Distributed Procedures for LDAP Operations February 2005 searchResEntry SearchResultEntry, searchResRef SearchResultReference, intermediateResponse IntermediateResponse ... }, controls [0] Controls COPTIONAL } FinalResponse ::= SEQUENCE { Response ::= CHOICE { bindResponse BindResponse, searchResDone SearchResultDone, modifyResponse ModifyResponse, addResponse AddResponse, delResponse DelResponse, modDNResponse ModifyDNResponse, compareResponse CompareResponse, extendedResp ExtendedResponse, ... }, controls [0] Controls COPTIONAL } BindResponse, SearchResultEntry, SearchResultDone, SearchResultReference, ModifyResponse, AddResponse, DelResponse, ModifyDNResponse, CompareResponse, ExtendedResponse, and Controls are defined in [RFC2251]. IntermediateResponse is defined in [RFC3771]. 3.3.1 ChainingResults In general, this is used to convey additional information that may needed in the event that the operation needs to be progressed further. 3.3.1.1 ChainingResults.searchedSubtrees Each value of this field indicates that a particular subtree below the target object has already been searched. This is particularly useful while chaining search operations during operation evaluation caused by the presence of a DSA of type nssr. Each DSA referenced by the nssr holds one or more naming contexts subordinate to the nssr DSE. The ChainingResults.searchedSubtrees field allows the DSA being chained to, to inform the sending DSA which subordinate naming contexts have been searched. This information may be passed to further DSAs listed on the nssr in order to reduce the possibility of duplicate entries being returned. Sermersheim Expires August 26, 2005 [Page 12] Internet-Draft Distributed Procedures for LDAP Operations February 2005 3.3.2 ChainedIntermediateResponseValue.intermediateResponse and ChainedFinalResponseValue.finalResponse This holds the directory operation response message tied to the ChainedRequestValue.operationRequest. Sermersheim Expires August 26, 2005 [Page 13] Internet-Draft Distributed Procedures for LDAP Operations February 2005 4. Distributed Procedures For the purposes of describing a distributed operation, operations are said to consist of two major phases -- name resolution and operation evaluation. These terms are adopted from [X518]. Name resolution is the act of locating a DSE said to be held locally by a DSA given a distinguished name (DN). Operation evaluation is the act of performing the operation after the name resolution phase is complete. Furthermore, there are two modes of distributing an operation -- chaining, and returning referrals. Chaining is the act of forwarding an unfinished operation to another DSA for completion (this may happen during name resolution or operation evaluation). In this case, the forwarding DSA sends a chained operation to a receiving DSA, which attempts to complete the operation. Alternately, the DSA may return a referral (or intermediate referral), and the client may use that referral in order to forward the unfinished operation to another DSA. Whether the operation is distributed via chaining or referrals is a decision left to the DSA and or DUA. The term 'intermediate referral' describes a referral returned during the operation evaluation phase of an operation. These include searchResultReferences, referrals returned with an intermediateResponse [RFC3771], or future referrals which indicate that they are intermediate referrals. An operation which is distributed while in the operation evaluation phase is termed a 'sub-operation'. This document inserts a step between the two distributed operation phases in order to commonize the data and processes followed prior to chaining an operation or returning a referral. This step consists of populating a ContinuationReference data type. 4.1 Name resolution Before evaluating (enacting) most directory operations, the DSE named by the target (often called the base DN) of the operation must be located . This is done by evaluating the RDNs of the target DN one at a time, starting at the rootmost RDN. Each RDN is compared to the DSEs held by the DSA until the set of RDNs is exhausted, or an RDN cannot be found. If the DSE named by the target is found to be local, the name resolution phase of the operation completes and the operation evaluation phase begins. Sermersheim Expires August 26, 2005 [Page 14] Internet-Draft Distributed Procedures for LDAP Operations February 2005 If it is found that the target does not name a local DSE nor a DSE that may held by another DSA, it is said that the target does not exist, and the operation fails with noSuchObject (subject to local policy). If it is found that the DSE named by the target is non-local to the DSA, but may reside elsewhere, name resolution is said to be incomplete. In this case, the operation may be distributed by creating a ContinuationReference (Section 4.3) and either chaining the operation (Section 4.4 and Section 4.5)or returning a referral (Section 4.9). 4.1.1 Determining that a named DSE is local to a DSA If a DSE held by a DSA falls within a naming context held by the DSA, or is the root DSE on a first-level DSA, it is said to be local to that DSA 4.1.2 Determining that a named DSE does not exist A named DSE is said to not exist if, during name resolution the DSE is not found, but if found it would fall within a naming context held by the DSA. 4.1.3 Determining that a named DSE is non-local If a named DSE is niether found to be local to the DSA, nor found to not exist, it is said to be non-local to a DSA. In this case, it is indeterminate whether the named DSE exists. When a named DSE is found to be non-local, there should be distributed knowledge information available to be used to either return a referral or chain the operation. 4.1.3.1 Locating distributed knowledge information for a non-local target If it has been determined that a target names a non-local DSE, distributed knowledge information may be found by first examining the DSE named by the target, and subsequently all superior DSEs beginning with the immediate superior and ending with the root, until an examined DSE is one of types: {TODO: should DSE types be all caps? It would be easier to read.} o subr o supr o immsupr Sermersheim Expires August 26, 2005 [Page 15] Internet-Draft Distributed Procedures for LDAP Operations February 2005 o xr o nssr The examined DSE which is of one of these types holds the distributed knowledge information for the non-local named target. This DSE is said to be the found distributed knowledge information of the non-local target. This found distributed knowledge information may then be used to distribute the operation. If no examined DSEs are of any of these types, the distributed knowledge information is mis-configured, and the error invalidReference is returned. 4.1.4 Special case for the Add operation During the name resolution phase of the Add operation, the immediate parent of the base DN is resolved. If the immediate parent of the entry to be added is a DSE of type nssr, then further interrogation is needed to ensure that the entry to be added does not exist. Methods for doing this are found in Section 4.11. {TODO: don't make this mandatory. Also, it doesn't work without transaction semantics. Same prob in the mod dn below.}. 4.1.5 Special case for the ModifyDN operation When the modifyDN operation includes a newSuperior name, it must be resolved as well as the base DN being modified. If either of these result in a non-local name, the name causing the operation to be distributed should be conveyed (Section 4.3.5). {TODO: also mention access control problems, and mention (impl detail) that affectsmultidsa can be used.} If during operation evaluation of a ModifyDN operation, the newSuperior names a DSE type of nssr, then further interrogation is needed to ensure that the entry to be added does not exist. Methods for doing this are found in Section 4.11. 4.2 Operation Evaluation Once name resolution has completed. The DSE named in the target has been found to be local to a DSA. At this point the operation can be carried out. During operation evaluation distributed knowledge information may be found that may cause the DSA to distribute the operation. When this happens, the operation may be distributed by creating a ContinuationReference (Section 4.3) and either chaining the operation (Section 4.4 and Section 4.5)or returning a referral (Section 4.9). Sermersheim Expires August 26, 2005 [Page 16] Internet-Draft Distributed Procedures for LDAP Operations February 2005 If, during the location of the distributed knowledge information, the distributed knowledge information is found to be mis-configured, operation semantics are followed (some operations may call for an error to be returned, while others call for the error to be ignored). {TODO: either make this more specific, or less specific, or just toss it out.} 4.2.1 Search operation During operation evaluation of a search operation, the DSA must determine whether there is distributed knowledge information in the scope of the search. Any DSE in the search scope which is of the following types is considered to be 'found distributed knowledge information' {TODO: use a better term than found distributed knowledge information} in the search scope: o subr o nssr (see nssr note) o xr {TODO: I think xr only qualifies when an alias is dereferenced to an xr. Otherwisw, there should always be a subr above the xr if it falls in the search scope.} Note that due to alias dereferencing, the search scope may expand to include entries outside of the scope originally specified in the search operation. {TODO: note that an aliased object may be glue which needs to result in any subr or xr above it to be found} Nssr Note: A DSE of type nssr is only considered to be found distributed knowledge information when the scope of the search includes entries below it. For example, when the search scope is wholeSubtree or subordinateSubtree and a DSE of type nssr is found in the scope, or if the search scope is singleLevel and the target object names a DSE of type nsssr. {TODO: The following sections are talking about how the continuation reference is to be populated. Move to next secion. Can probably just say that whole subtree or subordinare subtree encountering nssr, and single level rooted at nssr result in a continuation reference. base at, and single level above do not result in a continuation reference.} 4.2.1.1 Search operation with singleLevel scope If distributed knowledge information is found during operation evaluation of a search with a singleLevel scope, it will cause the resulting ContinuationReference.searchScope to be set to baseObject. Sermersheim Expires August 26, 2005 [Page 17] Internet-Draft Distributed Procedures for LDAP Operations February 2005 4.2.1.2 Search operation encountering nssr knowledge reference When a search operation encounters distributed knowledge information which is a DSE type of nssr during operation evaluation, the following instructions are followed: Note that when a search operation is being progressed due to nssr knowledge information, the subsequent distributed progression of the search is caused to be applied to each DSA listed as non-specific knowledge information (This is talked about in Section 4.3.2). In the event that multiple DSAs listed in the knowledge information hold copies of the same directory entries, the 'already searched' and 'duplicate elimination' mechanisms SHOULD be used to prevent duplicate search result entries from ultimately being returned. 4.2.1.2.1 wholeSubtree search scope When the search scope is wholeSubtree, the ContinuationReference.searchScope is set to subordinateSubtree. Because the ContinuationReference.referrenceType is set to nonSpecificSubordinate, the receiving protocol peer allows (and expects) name resolution to stop at an immsupr DSE type which is treated as a local DSE. The subordinateSubtree scope instructs the receiving protocol peer to exclude the target object from the sub-search. 4.2.1.2.2 singleLevel search scope When the search scope is singleLevel, and the base DN is resolved to a DSE of type nssr, subsequent distributed progressions of the search are caused to use the same base DN, and a scope of singleLevel. Receiving protocol peers will only apply the search to entries below the target object. When the search scope is singleLevel and an evaluated DSE is of type nssr, no special handling is required. The search is applied to that DSE if it is of type entry. 4.2.1.2.3 baseObject search scope No special handling is needed when the search scope is baseObject and the base DN is an nssr DSEType. The search is applied to that DSE if it is of type entry. 4.2.1.3 Search operation rooted at an nssr DSE type (TODO: a subordinateSubtree scope needs to change to wholeSubtree if references are found.) Sermersheim Expires August 26, 2005 [Page 18] Internet-Draft Distributed Procedures for LDAP Operations February 2005 4.3 Populating the ContinuationReference When an entry is found to be non-local to a DSA (whether during name resolution or operation evaluation), the DSA prepares for operation distribution by generating a ContinuationReference. This is a conceptual step, given to help explain the interactions that occur between discovering that an operation must be distributing, and actually invoking the operation distribution mechanism. Implementations are not required to perform this step, but will effectively work with the same information. After the ContinuationReference has been created, the DSA may choose to chain the operation or return a referral (or intermediate referral(s)). the ContinuationReference is made up of data held on the found distributed knowledge information, as well as state information gained during name resolution or operation evaluation. 4.3.1 Conveying the Target Object The consumer of the ContinuationReference will examine various fields in order to determine the target object name of the operation being progressed. The fields examined are the localReference and remainingName. If name resolution did not complete, and the found distributed knowledge information names the same DSE as the base DN of the operation, the ContinuationReference MAY omit the localReference and/or remainingName fields. localReference is populated with the name of the found distributed knowledge information DSE. In the event that the root object holds the distributed knowledge information, this field will be populated with an empty DN. Contrast this with the omission of this field. referenceType is populated with a value reflecting the reference type of the localReference DSE. remainingName is populated with the RDNSequence which has not yet been resolved. This is the difference between the localReference value and the name of the DSE to be resolved. In cases where the DSE named by the {TODO, use a dash or different term to make 'found distributed knowledge' more like a single term} found distributed knowledge is not the same as the base DN of the operation, the ContinuationReference must contain the localReference and/or remainingName fields. Such cases include but are not limited Sermersheim Expires August 26, 2005 [Page 19] Internet-Draft Distributed Procedures for LDAP Operations February 2005 to: o Distributed knowledge information is found during operation evaluation. o Aliases were dereferenced during name resolution. o Name resolution did not complete and there were remaining RDNs to be resolved. 4.3.2 Conveying the Remote DSA The referralURI field must contain at least one value. Each referralURI value must hold a referralURI.accessPoint. Other requirements on this field as noted may also apply. Note for nssr DSE types: During operation evaluation, if a DSE of type nssr causes the operation to be distributed (the scenarios in Section 4.2.1.2 are an example), then an intermediate referral {TODO: this is talking about referral/intermediate referral, but this section is only dealing with populating continuation reference} is returned for each value of the ref attribute, where each intermediate referral only holds a single referralURI value. 4.3.3 Conveying new search scope During the evaluation of the search operation, the instructions in Section 4.2.1.2.1 and Section 4.2.1.2.2 are followed and the searchScope field is updated with the new search scope. 4.3.4 Preventing duplicates In order to prevent duplicate entries from being evaluated while progressing a search operation, the searchedSubtrees field is populated with any naming context below the ContinuationReference.targetObject which have been fully searched. During the evaluation of the search operation, if the scope is wholeSubtree, it is possible that the DSA may search the contents of a naming context which is subordinate to another naming context which is subordinate to the search base (See figure). Sermersheim Expires August 26, 2005 [Page 20] Internet-Draft Distributed Procedures for LDAP Operations February 2005 O X / \ / \ / \ / \ \_______O Y /|\ / | \ / | \ / | \ A B O C / \ / \ / \ / \ \_______/ In this figure, the DSA holds the naming context X and C,Y,X, but not Y,X. If the search base was X, an intermediate referral would be returned for Y,X. The DSA holding Y,X may also hold a copy of C,Y,X. In this case, the receiver of the ContinuationReference benefits by knowing that the DSA already searched C,Y,X so that it can prevent other DSAs from returning those entries again. Data already searched is in the form of an RDNSequence, consisting of the RDNs relative to the target object. 4.3.5 Conveying the Failed Name At least one DS operation (modifyDN) requires that multiple DNs be resolved (the entry being modified and the newSuperior entry). In this case, the failedName field will be populated with the DN being resolved which failed name resolution. This may aid in the determination of how the operation is to be progressed. If both names are found to be non-local, this field is omitted. 4.4 Sending a ChainedRequest When an entry is found to be non-local to a DSA (whether during name resolution or operation evaluation), the DSA may progress the operation by sending a chained operation to another DSA (or DSAs). The instructions in this section assume that a ContinuationReference has been generated which will be used to form the ChainedRequest. It is also assumed that it can be determined whether the operation is being progressed due to name resolution or due to operation evaluation. A DSA which is able to chain operations may advertise this by Sermersheim Expires August 26, 2005 [Page 21] Internet-Draft Distributed Procedures for LDAP Operations February 2005 returning a value of IANA-ASSIGNED-OID.2; in the supportedFeatures attribute on the root DSE. {TODO: does this and discovery of the extended op belong in a new 'discovery mechanisms' sections.} 4.4.1 Forming a ChainedRequest The following fields are populated as instructed: 4.4.1.1 ChainedRequestValue.chainingArguments.targetObject The ContinuationReference may convey a new target object. If present, the ContinuationReference.localReference field becomes the candidate target object. Otherwise the candidate target object is assumed to be that of the original directory operation. Note that an empty value in the ContinuationReference.localReference field denotes the root object. After performing the above determination as to the candidate target object, any RDNSequence in ContinuationReference.remainingName is prepended to the determined candidate target object. This value becomes the ChainedRequestValue.chainingArguments.targetObject. If this value matches the value of the original operation, this field may be omitted. 4.4.1.2 ChainedRequestValue.chainingArguments.referenceType This is populated with the ContinuationReference.referralURI.referenceType. 4.4.1.3 ChainedRequestValue.chainingArguments.traceInformation This is populated as specified in Section 3.2.1.3. 4.4.1.4 ChainedRequestValue.chainingArguments.searchScope This is populated with the ContinuationReference.referralURI.searchScope if present, otherwise by the ContinuationReference.searchScope if present, and not populated otherwise. 4.4.1.5 ChainedRequestValue.chainingArguments.searchedSubtrees This is populated with ContinuationReference.searchedSubtrees, as well as any previously received values of ChainedFinalResponseValue.chainingResults.searchedSubtrees or ChainedIntermediateResponseValue.chainingResults.searchedSubtrees which are subordinate, relative to the target object. (If thsi is relative to the target object, it can't contain non-relative Sermersheim Expires August 26, 2005 [Page 22] Internet-Draft Distributed Procedures for LDAP Operations February 2005 subtrees) 4.4.1.6 ChainedRequestValue.operationRequest This is populated with the original directory operation request. 4.4.2 Attempting Each Referral URI A ContinuationReference consists of one or more referralURIs which represent(s a) remote DSA(s). The chaining DSA attempts to chain to each of these DSAs until one succeeds in completing the operation. An operation is considered to be completed if it reaches the remote DSA and a response is sent back that indicates that the operation was executed. Operations which are sent to the remote DSA, but don't complete are indicated by a result code of unavailable or busy. A result code of protocolError may indicate that the DSA does not support the chained operation, and in this case, it is also treated as an uncompleted operation. Other errors may in the future specify that they also indicate non-completion. Note that the response may itself contain referral(s), these are still considered completed operations and thus would subsequently be handled and chained. {TODO: could use soft/hard, or transient/permanent referral/non-referral error terms here.} 4.4.3 Loop Prevention Prior to sending a ChainedRequest, the DSA may attempt to prevent looping scenarios by comparing {TODO: what matching rule is used? Suggest we don't convert dns names to ip addresses due to NATs} the address of the remote DSA and target object to the values of ChainedRequestValue.chainingArguments.traceInformation. If a match is found, the DSA returns a loopDetect error. Note that while this type of loop prevention aids in detecting loops prior to sending data to a remote DSA, it is not a substitute for loop detection (Section Section 4.6.2). This is because the sending DSA is only aware of a single address on which the receiving DSA accepts connections. 4.5 Emulating the Sending of a ChainedRequest When it is determined that the operation cannot be distributed by means of the ChainedRequest, the chaining DSA may instead emulate the steps involved in chaining the operation. These steps consist of performing loop prevention, forming a new directory operation request from the original request and possibly updating the base DN, search scope, and search filter(in order to emulate searchedSubtrees), and, similar to the steps in Section 4.4.2, attempting to send the operation request to each DSA listed in the ContinuationReference.referralURI until one succeeds in completing Sermersheim Expires August 26, 2005 [Page 23] Internet-Draft Distributed Procedures for LDAP Operations February 2005 the operation. {TODO: We need a way (control) to tell the receiver to allow name resolution to end on the parent of a cp (typically an immsupr). This would be sent when the ContinuationReference.referenceType is nonSpecificSubordinate} 4.5.1 Emulated Loop Detection For this step, the loop prevention instructions in Section 4.4.3 are followed. Note that this method of loop detection may actually allow some looping to occur before the loop is detected. 4.5.2 Forming the New Request The new directory operation request is formed from the fields of the original request, and the following fields may be updated: o The base DN is formed from the new target object as determined by following the instructions in Section 4.4.1.1 and using the value which would have been placed in ChainedRequestValue.chainingArguments.targetObject. o For the search operation, the scope is populated with ContinuationReference.searchScope if present, otherwise the scope of the original operation request is used. o For the search operation, if the ContinuationReference.searchedSubtrees field is present, causes the search filter to be augmented by adding a filter item of the 'and' CHOICE. The filter consists of {TODO: weasel Kurt into finishing his entryDN draft and reference the appropriate section there. See <http://www.openldap.org/lists/ietf-ldapext/200407/msg00000.html> for context} o Other fields (such as the messageID, and non-critical controls) may also need to be updated or excluded. If the service being chained to does not support directory operations, other operations may be used as long as they provide the same level as service as those provided by the analogous directory operation. 4.6 Receiving a ChainedRequest A DSA which is able to receive and service a ChainedRequest may advertise this feature by returning a value of IANA-ASSIGNED-OID.1 in the supportedExtension attribute of the root DSE. {TODO: move?} The ChainedRequestValue data type is the requestValue of an Sermersheim Expires August 26, 2005 [Page 24] Internet-Draft Distributed Procedures for LDAP Operations February 2005 extendedRequest. In general, receiving and servicing a ChainedRequest consists of performing loop detection and, using components of the ChainedRequestType.chainingArguments along with the ChainedRequestType.operationRequest, service the request. 4.6.1 Target Object determination Prior to checking for a loop condition, the target object must be determined. If the ChainedRequestType.chainingArguments.targetObject field is present, its value becomes the target object. Otherwise, the base DN found in the ChainedRequestType.operationRequest becomes the target object. 4.6.2 Loop Detection The loop detection check happens when a DSA receives a chained operation, prior to acting on the operation. The DSA compares {TODO: matching rule? DNS expansion?} each value of ChainedRequestValue.traceInformation to the list of addresses at which it accepts directory communications. A value of ChainedRequestValue.traceInformation matches when the DSA accepts directory communications on the address found in the ChainedRequestValue.traceInformation value, and the target object (as determined in Section 4.6.1 matches the DN {TODO: using DN matching?} value found in the ChainedRequestValue.traceInformation value. If a match is found the DSA returns a loopDetect result. 4.6.3 Processing the ChainedRequestValue.operationRequest In processing the operationRequest, the DSA uses the target object determined in Section 4.6.1. For search operations, it uses the scope found in ChainedRequestValue.chainingArguments.searchScope, and excludes any subtrees relative to the target object indicated in ChainedRequestValue.chainingArguments.searchedSubtrees. Responses are returned in the form of a Chained Response. 4.7 Returning a Chained Response When returning responses to a ChainedRequest, the Chained Response as documented in Section 3.3 is used. If the ChainedFinalResponseValue.operationResponse is a searchResultDone, the ChainedFinalResponseValue.chainingResults.searchedSubtrees field is populated with values consisting of the RDNSequence relative to the target object of naming contexts that the DSA searched. See Section 3.3.1.1 for details on why this is done. Sermersheim Expires August 26, 2005 [Page 25] Internet-Draft Distributed Procedures for LDAP Operations February 2005 4.7.1 Chained Response resultCode The resultCode for the Chained Response is distinct from the result code of the ChainedIntermediateResponseValue.intermediateResponse or ChainedFinalResponseValue.finalResponse. If the act of chaining the operation completed, then this value will be success. Other result codes refer to the chained operation itself, and not the result of the embedded operation. 4.7.2 Returning referrals in the Chained Response {TODO: it would be less complicated if rather than using the simple LDAP URL, we used the ContinuationReference type to return referrals and intermediate referrals.} {TODO: We need an example of why we should allow referrals on a chained response. Why not just use the referral field in the operation?} 4.8 Receiving a Chained Response Processing a received Chained Response is generally straight forward -- typically the response is simply extracted and returned, but there are some extra steps to be taken when chaining sub-operations. 4.8.1 Handling Sub-operation controls and result codes When sub-operations are chained, there is the possibility that different result codes will be encountered. Similarly, if controls which elicit response controls were attached to the operation, it's possible that multiple response controls will be encountered. Both of these possibilities require that the chaining DSA take appropriate steps to ensure that the response being returned is correct. In general, when a result code indicating an error is received, the operation will terminate and the error will be returned. In cases where multiple sub-operations are being concurrently serviced, the operation will terminate and the most relevant, or first received result code is returned -- determining the result code to be returned in this case is a local matter. A DSA which chains an operation having a control (or controls) attached must ensure that a properly formed response is returned. This requires that the DSA understand and know how to aggrigate the results of all controls which it allows to remain attached to an operation being chained. If the DSA does not understand or support a control which is marked non-critical, it removes the control prior to chaining the operation. The DSA may return unavailableCriticalExtension for critical controls that it cannot or will not chain. {TODO: give SSS as an example?} Sermersheim Expires August 26, 2005 [Page 26] Internet-Draft Distributed Procedures for LDAP Operations February 2005 4.8.1.1 Handling referrals during sub-operations If a referral is returned in response to a sub-operation, the sending DSA may attempt to further chain the operation. In the event that the DSA does not further chain the sub-operation, it will use the referral to construct an intermediate referral, and return it appropriately. When using a referral to construct an intermediate referral, certain transformations may have to happen. For example, when using a referral to construct a searchResultReference, it must be assured that the <dn> field is present, and that the <scope> field is properly updated. 4.8.2 Duplicate Elimination When search result references cause the DSA to chain a search, it is possible that duplicate objects will be returned by different remote DSAs. These duplicate objects must be sensed and not returned. {TODO: Even though there are costs associated with returning duplicates, is it a worthy exercise to build in an allowance for them to be returned? In other words, do we want to add a way for a client (or administrator) to say "it's ok, return the duplicates, let the client deal with them"? Allowing is seen as a cost benefit to the DSA.} 4.9 Returning a Referral or Intermediate Referral There are two ways in which the fields of the ContinuationReference may be conveyed in a response containing or consisting of referral or intermediate referral. A paired control is introduced for the purpose of soliciting and returning a ContinuationReference. In absence of this control, a referral or intermediate referral may be returned which conveys the information present in the ContinuationReference. A method of converting a ContinuationReference to an LDAP URL is provided for referrals and intermediate referrals which identify LDAP-enabled DSAs. Methods for converting a ContinuationReference to URIs which identify non-LDAP servers is not provided here, but may be specified in future documents, as long as they can represent the data needed to provide the same level of service. 4.9.1 ReturnContinuationReference controls This control is sent when a client wishes to receive a ContinuationReference in the event that a referral or intermediate referral is being returned. If returned, the ContinuationReference will hold all data but the referralURI field. the referralURI values will be held in the referral or intermediate referral (Referral, Sermersheim Expires August 26, 2005 [Page 27] Internet-Draft Distributed Procedures for LDAP Operations February 2005 SearchResultReference, etc.). 4.9.1.1 ReturnContinuationReference request control Solicits the return of a ReturnContinuationReference response control on messages consisting of (or carrying) a referral or intermediate referral. The controlType is IANA-ASSIGNED-OID.3, the criticality is set at the sender's discretion, the controlValue is omitted. 4.9.1.2 ReturnContinuationReference response control In response to the ReturnContinuationReference request control, this holds a ContinuationReference for messages consisting of (or carrying) a referral or intermediate referral. The controlType is IANA-ASSIGNED-OID.3, the controlValue is the BER-encoding of a ContinuationReference. Note that the referralURI field is optionally omitted when the ContinuationReference is sent in this control value. In this event, the URI(s) found in the referral or intermediate referral (Referral, SearchContinuationReference, etc.) are to be used in its stead. {TODO: is returining the referralURI outside an unneeded complication?} 4.9.2 Converting a ContinuationReference to an LDAP URL This section details the way in which an LDAP URL (from the referral or intermediate referral) is used to convey the fields of a ContinuationReference. Where existing LDAP URL fields are insufficient, extensions are introduced. Note that further extensions to the ContinuationReference type require further specifications here. {TODO: explain that each ldap url in the continuation refrerence is examined and converted} These instructions must be applied to each LDAP URL value within the referral or intermediate referral. 4.9.2.1 Conveying the target name If the <dn> part of the LDAP URL is already present, it is determined to be the candidate target object. Otherwise, the candidate target object comes from the ContinuationReference.localReference. Once the candidate target object is determined, the value of ContinuationReference.remainingName is prepended to the candidate target object. This new value becomes the target object and its string value (as specified by <distinguishedName> in [RFC2253]) is placed in the <dn> part of the LDAP URL. Sermersheim Expires August 26, 2005 [Page 28] Internet-Draft Distributed Procedures for LDAP Operations February 2005 4.9.2.2 ContinuationReference.localReference This is conveyed as an extension. The extype is IANA-ASSIGNED-OID.4 or the descriptor 'localReference', and the exvalue is the string DN encoding (as specified by <distinguishedName> in [RFC2253]) of the ContinuationReference.localReference value. 4.9.2.3 ContinuationReference.referenceType This is conveyed as an extension. The extype is IANA-ASSIGNED-OID.5 or the descriptor 'referenceType'. If the ContinuationReference.referenceType is one of superior, subordinate, cross, nonSpecificSubordinate, suplier, master, immediateSuperior, or self, the exvalue 'superior', 'subordinate', 'cross', 'nonSpecificSubordinate', 'suplier', 'master', 'immediateSuperior', or 'self' respectively. 4.9.2.4 ContinuationReference.searchScope If the search scope is one of baseObject, singleLevel, or wholeSubtree, then it may be conveyed in the 'scope' part of the LDAP URL as 'base', 'one', or 'sub' respectively. If the search scope is subordinateSubtree, then it may be conveyed in the <extension> form as documented in [LDAP-SUBORD]. If this extension is present, it MUST be marked critical. This ensures that a receiver which is unaware of this extension uses the proper search scope, or fails to progress the operation. 4.9.2.5 ContinuationReference.searchedSubtrees This field is conveyed as an extension. The extype is IANA-ASSIGNED-OID.6 or the descriptor 'searchedSubtrees', and the exvalue is the ContinuationReference.searchedSubtree value encoded according to the following searchedSubtrees ABNF: searchedSubtrees = 1*(LANGLE searchedSubtree RANGLE) searchedSubtree = <distinguishedName> from [RFC2253] LANGLE = %x3C ; left angle bracket ("<") RANGLE = %x3E ; right angle bracket (">") Each searchedSubtree represents one RDNSequence value in the ContinuationReference.searchedSubtree field. An example of a searchedSubtrees value containing two searched subtrees is: <dc=example,dc=com><cn=ralph,dc=users,dc=example,dc=com>. 4.9.2.6 ContinuationReference.failedName This field is conveyed as an extension. The extype is Sermersheim Expires August 26, 2005 [Page 29] Internet-Draft Distributed Procedures for LDAP Operations February 2005 IANA-ASSIGNED-OID.7 or the descriptor 'failedName', and the exvalue is the string DN encoding (as specified in [RFC2253]) of the ContinuationReference.failedName value. 4.10 Acting on a Referral or Intermediate Referral When a protocol peer receives a referral or intermediate referral, it may distribute the operation either by sending a ChainedRequest, or by emulating the ChainedRequest. Prior to taking these steps, the protocol peer effectively converts the referral or intermediate referral into a ContinuationReference. Then, acting in the same manner as a DSA would, follows the directions in Section 4.4 if sending a ChainedRequest, or Section 4.5 otherwise. 4.10.1 Converting a Referral or Intermediate Referral to a ContinuationReference A referral or intermediate referral may be converted (or conceptually converted) to a ContinuationReference type in order to follow the distributed operation procedures in Section 4.4, or Section 4.5. The following steps may only be used to convert a referral or intermediate referral containing LDAP URL values. Converting other types of URIs may be specified in future documents as long as the conversion provides the same level of service found here. o The ContinuationReference.referralURI is populated with all LDAP URL values in the referral or intermediate referral. o The ContinuationReference.localReference populate with the value of the localReference extension value (Section 4.9.2.2) if one exists. Otherwise it is omitted. o The ContinuationReference.referenceType populate with the value of the referenceType extension value (Section 4.9.2.3) if one exists. Otherwise it is omitted. o The ContinuationReference.remainingName is omitted. o The ContinuationReference.searchScope is populated with subordinateSubtree if the subordScope LDAP URL extension [LDAP-SUBORD] is present. If the <scope> field contains te value 'base', 'one', 'sub', or 'subordinates', this filed is populated with baseObject, singleLevel, wholeSubtree, or subordinateSubtree respectively. Otherwise this field is omitted. o The ContinuationReference.searchedSubtrees is populated with any searchedSubtrees LDAP URI extension Section 4.9.2.5 value found on an LDAP URI in the referral or intermediate referral. If none exist, this field is omitted. o The ContinuationReference.failedName is populated with any failedName LDAP URI extension Section 4.9.2.6 value found on an LDAP URI in the referral or intermediate referral. If none exist, this field is omitted. Sermersheim Expires August 26, 2005 [Page 30] Internet-Draft Distributed Procedures for LDAP Operations February 2005 Note that many fields are simply omitted. This is either because they are conveyed within the LDAP URL values themselves, and subsequent instructions will check for their presence, or because they are not needed (they are redundant or not used in further instructions). 4.11 Ensuring non-existence of an entry under an nssr {TODO: add a huge disclaimer here that says without transactional semantics, you can never be sure that the entry didn't get added. Maybe we should just punt on this and say it's a local matter} In order to ensure there are no entries matching the name of the entry to be added or renamed immediately subordinate to an nssr, these steps may be followed. If the DSA is able and allowed to chain operations, it may contact each of the DSAs listed as access points in the nssr (in the ref attribute) and using a base-level search operation it will determine whether or not the object to be added exists. Note that access control or other policies may hide the entry from the sending DSA. If the entry does not exist on any of the DSAs listed in the nssr, the operation may progress on the local DSA. If the DSA cannot make this determination, the operation fails with affectsMultipleDSAs. 4.12 Mapping a referralURI to an LDAP URI As with any URI specification which is intended to be used as a URI which conveys referral information, the LDAP URI specification is given a mapping to the elements of a referralURI as specified in. Section 3.1.1.1. These mappings are given here using the ABNF identifiers given in [RFC2255]. referralURI to LDAP URI mapping: +---------------------------------+---------------------------------+ | referralURI element | LDAP URL element | +---------------------------------+---------------------------------+ | protocolIdentifier | <scheme> | | | | | accessPoint | <hostport> | | | | | targetObject | <dn>. This must be encoded as a | | | <distinguishedName> as | | | specified in [RFC2253] | | | | | localReference | LDAP URL localReference | Sermersheim Expires August 26, 2005 [Page 31] Internet-Draft Distributed Procedures for LDAP Operations February 2005 | | extension as specified in | | | Section 4.9.2.2 | | | | | referenceType | LDAP URL referenceType | | | extension as specified in | | | Section 4.9.2.3 | | | | | searchScope | <scope> or LDAP URL subordScope | | | extension as specified in | | | Section 4.9.2.4 | | | | | searchedSubtrees | LDAP URL searchedSubtrees | | | extension as specified in | | | Section 4.9.2.5 | | | | | failedName | LDAP URL failedName extension | | | as specified in Section 4.9.2.6 | +---------------------------------+---------------------------------+ 4.13 Using the ManageDsaIT control This control, defined in [RFC3296], allows the management of the distributed knowledge information held by a DSA, and thus overrides the determinations made during name resolution and operation evaluation. When this control is attached to an operation, all resolved and acted upon DSEs are treated as being local to the DSA. This is true regardless of the phase the operation is in. Thus referrals are never returned and chaining never occurs. Sermersheim Expires August 26, 2005 [Page 32] Internet-Draft Distributed Procedures for LDAP Operations February 2005 5. Security Considerations This document introduces a mechanism (chaining) which can be used to propagate directory operation requests to servers which may be inaccessible otherwise. Implementers and deployers of this technology should be aware of this and take appropriate steps such that firewall mechanisms are not compromised. This document introduces the ability to return auxiliary data when returning referrals. Measures should be taken to ensure proper protection of his data. Implementers must ensure that any specified time, size, and administrative limits are not circumvented due to the mechanisms introduced here. 6. Normative References [LDAP-SUBORD] Sermersheim, J., "Subordinate Subtree Search Scope for LDAP", Internet-Draft draft-sermersheim-ldap-subordinate-scope, July 2004. [RFC2079] Smith, M., "Definition of an X.500 Attribute Type and an Object Class to Hold Uniform Resource Identifiers (URIs)", RFC 2079, January 1997. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2251] Wahl, M., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [RFC2253] Wahl, M., Kille, S. and T. Howes, "Lightweight Directory Access Protocol (v3): UTF-8 String Representation of Distinguished Names", RFC 2253, December 1997. [RFC2255] Howes, T. and M. Smith, "The LDAP URL Format", RFC 2255, December 1997. [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, August 1998. [RFC3296] Zeilenga, K., "Named Subordinate References in Lightweight Directory Access Protocol (LDAP) Directories", RFC 3296, July 2002. Sermersheim Expires August 26, 2005 [Page 33] Internet-Draft Distributed Procedures for LDAP Operations February 2005 [RFC3377] Hodges, J. and R. Morgan, "Lightweight Directory Access Protocol (v3): Technical Specification", RFC 3377, September 2002. [RFC3383] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 3383, September 2002. [RFC3771] Harrison, R. and K. Zeilenga, "The Lightweight Directory Access Protocol (LDAP) Intermediate Response Message", RFC 3771, April 2004. [X500] International Telephone and Telegraph Consultative Committee, "The Directory - overview of concepts, models and services", ITU-T Recommendation X.500, November 1993. [X518] International Telephone and Telegraph Consultative Committee, "The Directory - The Directory: Procedures for distributed operation", ITU-T Recommendation X.518, November 1993. [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 Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER)", ITU-T Recommendation X.690, July 2002. Author's Address Jim Sermersheim Novell, Inc 1800 South Novell Place Provo, Utah 84606 USA Phone: +1 801 861-3088 Email: jimse@novell.com Sermersheim Expires August 26, 2005 [Page 34] Internet-Draft Distributed Procedures for LDAP Operations February 2005 Appendix A. IANA Considerations Registration of the following values is requested [RFC3383]. A.1 LDAP Object Identifier Registrations It is requested that IANA register upon Standards Action an LDAP Object Identifier in identifying the protocol elements defined in this technical specification. The following registration template is provided: Subject: Request for LDAP OID Registration Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Specification: RFCXXXX Author/Change Controller: IESG Comments: Seven delegations will be made under the assigned OID: IANA-ASSIGNED-OID.1 ChainedRequest LDAP Extended Operation IANA-ASSIGNED-OID.2 Supported Feature: Can Chain Operations IANA-ASSIGNED-OID.3 ReturnContinuationReference LDAP Controls IANA-ASSIGNED-OID.4 localReference: LDAP URL Extension IANA-ASSIGNED-OID.6 searchedSubtree: LDAP URL Extension IANA-ASSIGNED-OID.7 failedName: LDAP URL Extension A.2 LDAP Protocol Mechanism Registrations It is requested that IANA register upon Standards Action the LDAP protocol mechanism described in this document. The following registration templates are given: Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: IANA-ASSIGNED-OID.1 Description: ChainedRequest LDAP Extended Operation Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Usage: Extension Specification: RFCXXXX Author/Change Controller: IESG Comments: none Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: IANA-ASSIGNED-OID.2 Description: Can Chain Operations Supported Feature Person & email address to contact for further information: Sermersheim Expires August 26, 2005 [Page 35] Internet-Draft Distributed Procedures for LDAP Operations February 2005 Jim Sermersheim jimse@novell.com Usage: Feature Specification: RFCXXXX Author/Change Controller: IESG Comments: none Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: IANA-ASSIGNED-OID.3 Description: ReturnContinuationReference LDAP Controls Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Usage: Control Specification: RFCXXXX Author/Change Controller: IESG Comments: none Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: IANA-ASSIGNED-OID.4 Description: localReference LDAP URL Extension Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Usage: Extension Specification: RFCXXXX Author/Change Controller: IESG Comments: none Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: IANA-ASSIGNED-OID.5 Description: referenceType LDAP URL Extension Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Usage: Extension Specification: RFCXXXX Author/Change Controller: IESG Comments: none Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: IANA-ASSIGNED-OID.6 Description: searchedSubtree LDAP URL Extension Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Usage: Extension Sermersheim Expires August 26, 2005 [Page 36] Internet-Draft Distributed Procedures for LDAP Operations February 2005 Specification: RFCXXXX Author/Change Controller: IESG Comments: none Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: IANA-ASSIGNED-OID.7 Description: failedName LDAP URL Extension Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Usage: Extension Specification: RFCXXXX Author/Change Controller: IESG Comments: none A.3 LDAP Descriptor Registrations It is requested that IANA register upon Standards Action the LDAP descriptors described in this document. The following registration templates are given: Subject: Request for LDAP Descriptor Registration Descriptor (short name): localReference Object Identifier: IANA-ASSIGNED-OID.4 Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Usage: URL Extension Specification: RFCXXXX Author/Change Controller: IESG Comments: none Subject: Request for LDAP Descriptor Registration Descriptor (short name): referenceType Object Identifier: IANA-ASSIGNED-OID.5 Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Usage: URL Extension Specification: RFCXXXX Author/Change Controller: IESG Comments: none Subject: Request for LDAP Descriptor Registration Descriptor (short name): searchedSubtree Object Identifier: IANA-ASSIGNED-OID.6 Person & email address to contact for further information: Sermersheim Expires August 26, 2005 [Page 37] Internet-Draft Distributed Procedures for LDAP Operations February 2005 Jim Sermersheim jimse@novell.com Usage: URL Extension Specification: RFCXXXX Author/Change Controller: IESG Comments: none Subject: Request for LDAP Descriptor Registration Descriptor (short name): failedName Object Identifier: IANA-ASSIGNED-OID.7 Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Usage: URL Extension Specification: RFCXXXX Author/Change Controller: IESG Comments: none A.4 LDAP Result Code Registrations It is requested that IANA register upon Standards Action the LDAP result codes described in this document. The following registration templates are given: Subject: Request for LDAP Result Code Registration Result Code Name: invalidReference Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Usage: URL Extension Specification: RFCXXXX Author/Change Controller: IESG Comments: none Sermersheim Expires August 26, 2005 [Page 38] Internet-Draft Distributed Procedures for LDAP Operations February 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@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 Expires August 26, 2005 [Page 39]PK /�c\�H��� � > doc/alt-openldap11-devel/drafts/draft-legg-ldap-acm-bac-xx.txtnu �[��� INTERNET-DRAFT S. Legg draft-legg-ldap-acm-bac-03.txt Adacel Technologies Intended Category: Standards Track June 16, 2004 Updates: RFC 2252 Lightweight Directory Access Protocol (LDAP): Basic and Simplified Access Control Copyright (C) The Internet Society (2004). All Rights Reserved. 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 document is unlimited. Comments should be sent to the author. This Internet-Draft expires on 16 December 2004. Abstract An access control scheme describes the means by which access to directory information and potentially to access rights themselves may be controlled. This document adapts the X.500 directory Basic Access Control and Simplied Access Control schemes for use by the Lightweight Directory Access Protocol. Legg Expires 16 December 2004 [Page 1] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Basic Access Control . . . . . . . . . . . . . . . . . . . . . 4 3.1. Permissions. . . . . . . . . . . . . . . . . . . . . . . 5 3.1.1. Read . . . . . . . . . . . . . . . . . . . . . . 5 3.1.2. Compare. . . . . . . . . . . . . . . . . . . . . 6 3.1.3. Browse . . . . . . . . . . . . . . . . . . . . . 6 3.1.4. ReturnDN . . . . . . . . . . . . . . . . . . . . 6 3.1.5. FilterMatch. . . . . . . . . . . . . . . . . . . 6 3.1.6. Modify . . . . . . . . . . . . . . . . . . . . . 6 3.1.7. Add. . . . . . . . . . . . . . . . . . . . . . . 6 3.1.8. Remove . . . . . . . . . . . . . . . . . . . . . 7 3.1.9. DiscloseOnError. . . . . . . . . . . . . . . . . 7 3.1.10. Rename . . . . . . . . . . . . . . . . . . . . . 7 3.1.11. Export . . . . . . . . . . . . . . . . . . . . . 7 3.1.12. Import . . . . . . . . . . . . . . . . . . . . . 8 3.1.13. Invoke . . . . . . . . . . . . . . . . . . . . . 8 3.2. Representation of Access Control Information . . . . . . 8 3.2.1. Identification Tag . . . . . . . . . . . . . . . 11 3.2.2. Precedence . . . . . . . . . . . . . . . . . . . 11 3.2.3. Authentication Level . . . . . . . . . . . . . . 11 3.2.4. itemFirst and userFirst Components . . . . . . . 12 3.2.5. Determining Group Membership . . . . . . . . . . 16 3.3. ACI Operational Attributes . . . . . . . . . . . . . . . 17 3.3.1. Prescriptive ACI . . . . . . . . . . . . . . . . 17 3.3.2. Entry ACI. . . . . . . . . . . . . . . . . . . . 17 3.3.3. Subentry ACI . . . . . . . . . . . . . . . . . . 18 3.3.4. Protecting the ACI . . . . . . . . . . . . . . . 18 3.4. Access Control Decision Points for LDAP Operations . . . 18 3.4.1. Common Elements of Procedure . . . . . . . . . . 19 3.4.1.1. Alias Dereferencing. . . . . . . . . . 19 3.4.1.2. Return of Names in Errors. . . . . . . 19 3.4.1.3. Non-disclosure of Entry Existence. . . 20 3.4.2. Compare Operation Decision Points. . . . . . . . 20 3.4.3. Search Operation Decision Points . . . . . . . . 20 3.4.4. Add Operation Decision Points. . . . . . . . . . 23 3.4.5. Delete Operation Decision Points . . . . . . . . 24 3.4.6. Modify Operation Decision Points . . . . . . . . 24 3.4.7. Modify DN Operation Decision Points. . . . . . . 25 3.5. Access Control Decision Function . . . . . . . . . . . . 26 3.5.1. Inputs . . . . . . . . . . . . . . . . . . . . . 26 3.5.2. Tuples . . . . . . . . . . . . . . . . . . . . . 26 3.5.3. Discarding Irrelevant Tuples . . . . . . . . . . 27 3.5.4. Highest Precedence and Specificity . . . . . . . 28 4. Simplified Access Control. . . . . . . . . . . . . . . . . . . 28 5. Security Considerations. . . . . . . . . . . . . . . . . . . . 29 Legg Expires 16 December 2004 [Page 2] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 29 7. IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 29 Appendix A. LDAP Specific Encoding for the ACI Item Syntax . . . . 30 Normative References . . . . . . . . . . . . . . . . . . . . . . . 39 Informative References . . . . . . . . . . . . . . . . . . . . . . 40 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 40 Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 40 1. Introduction An access control scheme describes the means by which access to directory information and potentially to access rights themselves may be controlled. Control of access to information means the prevention of unauthorized detection, disclosure, or modification of that information. The definition of an access control scheme in the context of a Lightweight Directory Access Protocol (LDAP) [RFC3371] directory includes methods to specify Access Control Information (ACI), and to enforce access rights defined by that ACI. This document adapts the X.500 Basic Access Control and Simplied Access Control schemes [X501] for use in LDAP. Both schemes conform to, and make use of, the access control administrative framework for LDAP [ACA]. Section 3 describes the Basic Access Control scheme and defines how it applies to LDAP operations [RFC2251]. Simplified Access Control is a functional subset of the Basic Access Control scheme. This subset is described in Section 4. As a matter of security policy, an implementation supporting Basic Access Control or Simplified Access Control is permitted to grant or deny any form of access to particular attributes (e.g., password attributes) irrespective of access controls which may otherwise apply. However, since such security policy has no standardized representation, it cannot be propagated in replicated information. This document is derived from, and duplicates substantial portions of, Section 8 of X.501 [X501], and selected extracts from X.511 [X511]. 2. Conventions 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 [RFC2119]. Legg Expires 16 December 2004 [Page 3] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 Schema definitions are provided using LDAP description formats [RFC2252]. Note that the LDAP descriptions have been rendered with additional white-space and line breaks for the sake of readability. 3. Basic Access Control This section describes the functionality of the Basic Access Control scheme. When Basic Access Control is used, the accessControlScheme operational attribute [ACA] SHALL have the value basic-access-control (2.5.28.1). This LDAP profile for Basic Access Control defines, for every LDAP operation, one or more points at which access control decisions take place. An access control decision will involve a requestor, protected items, and permissions. A requestor is the user requesting the operation. Basic Access Control requires a user's authorization identity to be represented as a distinguished name (with an optional unique identifier). The mapping of the authentication identity to an authorization identity, and the mapping of the authorization identity to a distinguished name and optional unique identifier, are outside the scope of this document. A protected item is the element of directory information being accessed. The protected items are entries, attributes, attribute values and distinguished names. Access to each protected item can be separately controlled through ACI. A permission is a particular right necessary to complete a portion of the operation. The Access Control Information, which is used to make access control decisions, associates protected items and user classes with permissions. ACI is represented in the directory as values of operational attributes with the ACI Item syntax [RFC2252]. Each such value is referred to as an ACI item. The scope of access controls can be a single entry or a collection of entries that are logically related by being within the scope of an access control subentry of an administrative point (see [ACA]). The Access Control Decision Function (ACDF) (Section 3.5) is used to decide whether a particular requestor has a particular access right by virtue of applicable ACI items. Legg Expires 16 December 2004 [Page 4] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 Access to DSEs and operational attributes is controlled in the same way as for entries and user attributes. For query purposes, collective attributes [COLLECT] that are associated with an entry are protected precisely as if they were attributes actually stored in that entry. For the purposes of modification, collective attributes are associated with the subentry that holds them, not with entries within the scope of the subentry. Modify-related access controls are therefore not relevant to collective attributes, except when they apply to the collective attribute and its values within the subentry. 3.1. Permissions Access is controlled by granting or denying permissions. Access is allowed only when there is an explicitly provided grant present in the ACI used to make the access control decision. The only default access decision provided in the model is to deny access in the absence of explicit ACI that grants access. All other factors being equal, a denial specified in ACI always overrides a grant. Certain combinations of grants or denials are illogical, but it is the responsibility of directory clients, rather than the directory server, to ensure that such combinations are absent. The decision whether or not to permit access to an entry or its contents is strictly determined by the position of the entry in the Directory Information Tree (DIT), in terms of its distinguished name, and is independent of how the directory server locates that entry. The following sections introduce the permissions by indicating the intent associated with the granting of each. The actual influence of a particular granted permission on access control decisions are, however, determined by the ACDF and the access control decision points for each LDAP operation, described in detail in Section 3.4. 3.1.1. Read If granted for an entry, Read permits the entry to be accessed using LDAP Compare and baseObject Search operations, but does not imply access to all the attributes and values. If granted for an attribute type, Read permits the attribute type to be returned as entry information in a Search result. Read or Browse permission for the entry is a prerequisite. If granted for an attribute value, Read permits the attribute value Legg Expires 16 December 2004 [Page 5] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 to be returned as entry information in a Search result. Read or Browse permission for the entry and Read permission for the attribute type are prerequisites. 3.1.2. Compare If granted for an attribute type, Compare permits the attribute type to be tested by the assertion in an LDAP Compare operation. Read permission for the entry is a prerequisite. If granted for an attribute value, Compare permits the value to be tested by the assertion in an LDAP Compare operation. Read permission for the entry and Compare permission for the attribute type are prerequisites. 3.1.3. Browse If granted for an entry, Browse permits the entry to be accessed by the LDAP Search operation, including baseObject searches, but does not imply access to all the attributes and values. 3.1.4. ReturnDN If granted for an entry, ReturnDN allows the distinguished name of the entry to be disclosed in a search result. 3.1.5. FilterMatch If granted for an attribute type, Filtermatch permits the attribute type to satisfy a Filter item. If granted for an attribute value, Filtermatch permits the attribute value to satisfy a Filter item. FilterMatch permission for the attribute type is a prerequisite. 3.1.6. Modify If granted for an entry, Modify permits the information contained within an entry to be modified by the LDAP Modify operation, subject to controls on the attribute types and values. 3.1.7. Add If granted for an entry, Add permits creation of an entry in the DIT, subject to being able to add all specified attributes and attribute values. Add permission granted for an entry is ineffective if Add permission is not also granted for at least the mandatory attributes and their values. There is no specific "add subordinate permission". Legg Expires 16 December 2004 [Page 6] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 Permission to add an entry is controlled using prescriptive ACI. If granted for an attribute type, Add permits adding a new attribute, subject to being able to add all specified attribute values. Add or Modify permission for the entry is a prerequisite. If granted for an attribute value, Add permits adding that value to an existing attribute. Add or Modify permission for the entry is a prerequisite. 3.1.8. Remove If granted for an entry, Remove permits the entry to be removed from the DIT regardless of controls on attributes or attribute values within the entry. If granted for an attribute, Remove permits removing an attribute, subject to being able to remove any explicitly specified attribute values. Remove permission for values not explicitly specified is not required. If granted for an attribute value, Remove permits the attribute value to be removed from an existing attribute. 3.1.9. DiscloseOnError If granted for an entry, DiscloseOnError permits the name of an entry to be disclosed in an error result. If granted for an attribute, DiscloseOnError permits the presence of the attribute to be disclosed by an error. If granted for an attribute value, DiscloseOnError permits the presence of the attribute value to be disclosed by an error. 3.1.10. Rename If granted for an entry, Rename permits an entry to be renamed with a new RDN. No permissions are required for the attributes and values altered by the operation, even if they are added or removed as a result of the changes to the RDN. 3.1.11. Export If granted for an entry, Export permits the entry and its subordinates, if any, to be removed from the current location and placed in a new location, subject to the granting of Import permission at the destination. Legg Expires 16 December 2004 [Page 7] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 If the last RDN is changed, Rename permission at the current location is also required 3.1.12. Import If granted for an entry, Import permits an entry and its subordinates, if any, to be placed at the location to which the permission applies, subject to the granting of Export permission at the source location. 3.1.13. Invoke Invoke, if granted for an operational attribute, or value thereof, permits the directory server to carry out some function associated with the operational attribute on behalf of the user. The specific function carried out by invocation depends on the attribute. No other permissions are required by user for the operational attribute, or on the entry/subentry that holds it, in order for it to be "invoked". 3.2. Representation of Access Control Information Access Control Information is represented as a set of ACI items, where each ACI item grants or denies permissions in regard to certain specified users and protected items. An ACI item is represented as a value of an operational attribute with the ACI Item syntax (1.3.6.1.4.1.1466.115.121.1.1) [RFC2252]. This document updates [RFC2252] by specifying a human-readable LDAP-specific encoding for ACI items. The LDAP-specific encoding of values of the ACI Item syntax is defined by the Generic String Encoding Rules [GSER]. Appendix A provides an equivalent ABNF for this syntax. For convenience in specifying access control policies, the ACI Item syntax provides the means to identify collections of related items, such as attributes in an entry or all attribute values of a given attribute, and to specify a common protection for them. The ACI Item syntax corresponds to the ACIItem ASN.1 [ASN1] type defined in X.501 [X501]. It is reproduced here for convenience: ACIItem ::= SEQUENCE { identificationTag DirectoryString { ub-tag }, precedence Precedence, authenticationLevel AuthenticationLevel, itemOrUserFirst CHOICE { Legg Expires 16 December 2004 [Page 8] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 itemFirst [0] SEQUENCE { protectedItems ProtectedItems, itemPermissions SET OF ItemPermission }, userFirst [1] SEQUENCE { userClasses UserClasses, userPermissions SET OF UserPermission } } } Precedence ::= INTEGER (0..255) ProtectedItems ::= SEQUENCE { entry [0] NULL OPTIONAL, allUserAttributeTypes [1] NULL OPTIONAL, attributeType [2] SET SIZE (1..MAX) OF AttributeType OPTIONAL, allAttributeValues [3] SET SIZE (1..MAX) OF AttributeType OPTIONAL, allUserAttributeTypesAndValues [4] NULL OPTIONAL, attributeValue [5] SET SIZE (1..MAX) OF AttributeTypeAndValue OPTIONAL, selfValue [6] SET SIZE (1..MAX) OF AttributeType OPTIONAL, rangeOfValues [7] Filter OPTIONAL, maxValueCount [8] SET SIZE (1..MAX) OF MaxValueCount OPTIONAL, maxImmSub [9] INTEGER OPTIONAL, restrictedBy [10] SET SIZE (1..MAX) OF RestrictedValue OPTIONAL, contexts [11] SET SIZE (1..MAX) OF ContextAssertion OPTIONAL, classes [12] Refinement OPTIONAL } MaxValueCount ::= SEQUENCE { type AttributeType, maxCount INTEGER } RestrictedValue ::= SEQUENCE { type AttributeType, valuesIn AttributeType } UserClasses ::= SEQUENCE { allUsers [0] NULL OPTIONAL, thisEntry [1] NULL OPTIONAL, name [2] SET SIZE (1..MAX) OF NameAndOptionalUID OPTIONAL, userGroup [3] SET SIZE (1..MAX) OF NameAndOptionalUID OPTIONAL, -- dn component shall be the name of an -- entry of GroupOfUniqueNames subtree [4] SET SIZE (1..MAX) OF SubtreeSpecification OPTIONAL } Legg Expires 16 December 2004 [Page 9] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 NameAndOptionalUID ::= SEQUENCE { dn DistinguishedName, uid UniqueIdentifier OPTIONAL } UniqueIdentifier ::= BIT STRING ItemPermission ::= SEQUENCE { precedence Precedence OPTIONAL, -- defaults to precedence in ACIItem userClasses UserClasses, grantsAndDenials GrantsAndDenials } UserPermission ::= SEQUENCE { precedence Precedence OPTIONAL, -- defaults to precedence in ACIItem protectedItems ProtectedItems, grantsAndDenials GrantsAndDenials } AuthenticationLevel ::= CHOICE { basicLevels SEQUENCE { level ENUMERATED { none(0), simple(1), strong(2) }, localQualifier INTEGER OPTIONAL, signed BOOLEAN DEFAULT FALSE }, other EXTERNAL } GrantsAndDenials ::= BIT STRING { -- permissions that may be used in conjunction -- with any component of ProtectedItems grantAdd (0), denyAdd (1), grantDiscloseOnError (2), denyDiscloseOnError (3), grantRead (4), denyRead (5), grantRemove (6), denyRemove (7), -- permissions that may be used only in conjunction -- with the entry component grantBrowse (8), denyBrowse (9), grantExport (10), denyExport (11), grantImport (12), denyImport (13), grantModify (14), denyModify (15), grantRename (16), denyRename (17), Legg Expires 16 December 2004 [Page 10] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 grantReturnDN (18), denyReturnDN (19), -- permissions that may be used in conjunction -- with any component, except entry, of ProtectedItems grantCompare (20), denyCompare (21), grantFilterMatch (22), denyFilterMatch (23), grantInvoke (24), denyInvoke (25) } AttributeTypeAndValue ::= SEQUENCE { type ATTRIBUTE.&id ({SupportedAttributes}), value ATTRIBUTE.&Type ({SupportedAttributes}{@type}) } The SubtreeSpecification and Refinement ASN.1 types are defined in X.501 [X501], and separately described for LDAP [SUBENTRY]. The following sections describe the components of ACIItem. 3.2.1. Identification Tag identificationTag is used to identify a particular ACI item. This is used to discriminate among individual ACI items for the purposes of protection and administration. 3.2.2. Precedence Precedence is used to control the relative order in which ACI items are considered during the course of making an access control decision using the ACDF. ACI items having higher precedence values prevail over others with lower precedence values, other factors being equal. Precedence values are integers and are compared as such. 3.2.3. Authentication Level AuthenticationLevel defines the minimum requestor authentication level required for this ACI item. It has two forms: 1) basicLevels: which indicates the level of authentication, optionally qualified by positive or negative integer localQualifier. 2) other: an externally defined measure. When basicLevels is used, an AuthenticationLevel consisting of a level and optional localQualifier SHALL be assigned to the requestor by the directory server according to local policy. For a requestor's Legg Expires 16 December 2004 [Page 11] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 authentication level to meet or exceed the minimum requirement, the requestor's level must meet or exceed that specified in the ACI item, and in addition the requestor's localQualifier must be arithmetically greater than or equal to that of the ACI item. Strong authentication of the requestor is considered to exceed a requirement for simple or no authentication, and simple authentication exceeds a requirement for no authentication. For access control purposes, the "simple" authentication level requires at least a password; the case of identification only, with no password supplied, is considered "none". If a localQualifier is not specified in the ACI item, then the requestor need not have a corresponding value (if such a value is present it is ignored). The signed component of basicLevels is ignored for LDAP. When other is used, an appropriate AuthenticationLevel shall be assigned to the requestor by the directory server according to local policy. The form of this AuthenticationLevel and the method by which it is compared with the AuthenticationLevel in the ACI is a local matter. An authentication level associated with an explicit grant indicates the minimum level to which a requestor shall be authenticated in order to be granted access. An authentication level associated with an explicit deny indicates the minimum level to which a requestor shall be authenticated in order not to be denied access. For example, an ACI item that denies access to a particular user class and requires strong authentication will deny access to all requestors who cannot prove, by means of a strongly authenticated identity, that they are not in that user class. The directory server may base authentication level on factors other than values received in protocol exchanges. 3.2.4. itemFirst and userFirst Components Each ACI item contains a choice of itemFirst or userFirst. The choice allows grouping of permissions depending on whether they are most conveniently grouped by user classes or by protected items. The itemFirst and userFirst components are equivalent in the sense that they capture the same access control information; however, they organize that information differently. The choice between them is based on administrative convenience. The subcomponents of itemFirst and userFirst are described below. a) ProtectedItems defines the items to which the specified access Legg Expires 16 December 2004 [Page 12] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 controls apply. It is defined as a set selected from the following: - entry means the entry contents as a whole. It does not necessarily include the information in these entries. This element SHALL be ignored if the classes component is present, since this latter element selects protected entries on the basis of their object class. - allUserAttributeTypes means all user attribute type information associated with the entry, but not values associated with those attributes. - allUserAttributeTypesAndValues means all user attribute information associated with the entry, including all values of all user attributes. The allUserAttributeTypes and allUserAttributeTypesAndValues components do not include operational attributes, which MUST be specified on a per attribute basis, using attributeType, allAttributeValues or attributeValue. - attributeType means attribute type information pertaining to specific attributes but not values associated with the type. - allAttributeValues means all attribute value information pertaining to specific attributes. - attributeValue means specific values of specific attribute types. - selfValue means the attribute values of the specified attribute types that match the distinguished name (and unique identifier) of the requestor. It can only apply in the specific case where the attribute specified is of DN syntax (1.3.6.1.4.1.1466.115.121.1.12) or Name And Optional UID syntax (1.3.6.1.4.1.1466.115.121.1.34) [RFC2252]. - rangeOfValues means any attribute value which matches the specified filter, i.e., for which the specified filter evaluated on that attribute value would return TRUE. The filter is not evaluated on any entries in the DIB, rather it is evaluated using the semantics defined in 7.8 of [X511], operating on a fictitious entry that contains only the single attribute value which is the protected item. Note that the filter is an X.500 search Filter. It has a different syntax from the LDAP search Filter, but the same semantics. Legg Expires 16 December 2004 [Page 13] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 The following items provide constraints that may disable the granting of certain permissions to protected items in the same value of ProtectedItems: - maxValueCount restricts the maximum number of attribute values allowed for a specified attribute type. It is examined if the protected item is an attribute value of the specified type and the permission sought is Add. Values of that attribute in the entry are counted, without regard to attribute options and access control, as though the operation which is attempting to add the values is successful. If the number of values in the attribute exceeds maxCount, the ACI item is treated as not granting Add permission. - maxImmSub restricts the maximum number of immediate subordinates of the superior entry to an entry being added or imported. It is examined if the protected item is an entry, the permission sought is Add or Import, and the immediate superior entry is in the same server as the entry being added or imported. Immediate subordinates of the superior entry are counted, without regard to access control, as though the entry addition or importing is successful. If the number of subordinates exceeds maxImmSub, the ACI item is treated as not granting Add or Import permission. - restrictedBy restricts values added to the attribute type to being values that are already present in the same entry as values of the attribute identified by the valuesIn component. It is examined if the protected item is an attribute value of the specified type and the permission sought is Add. Values of the valuesIn attribute are checked, without regard to attribute options and access control, as though the operation which adds the values is successful. If the value to be added is not present in valuesIn the ACI item is treated as not granting Add permission. - contexts is not used in this version of the LDAP profile for Basic Access Control. - classes means the contents of entries that have object class values that satisfy the predicate defined by Refinement (see [SUBENTRY]). b) UserClasses defines a set of zero or more users the permissions apply to. The set of users is selected from the following: - allUsers means every directory user (with possible requirements for AuthenticationLevel). Legg Expires 16 December 2004 [Page 14] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 - thisEntry means the user with the same distinguished name as the entry being accessed. - name is the set of users with the specified distinguished names (each with an optional unique identifier). - userGroup is the set of users who are members of the groups (i.e., groupOfNames or groupOfUniqueNames entries [RFC2256]) identified by the specified distinguished names (each with an optional unique identifier). Members of a group of unique names are treated as individual user distinguished names, and not as the names of other groups of unique names. How group membership is determined is described in 5.2.5. - subtree is the set of users whose distinguished names fall within the scope of the unrefined subtrees (specificationFilter components SHOULD NOT be used - they SHALL be ignored if present). c) SubtreeSpecification is used to specify a subtree relative to the root DSE, and is not constrained by administrative areas. The specificationFilter component SHOULD NOT be used. It SHALL be ignored if present. A subtree refinement is not allowed because membership in a subtree whose specification includes only base and/or a ChopSpecification can be evaluated in isolation, whereas membership in a subtree definition using specificationFilter can only be evaluated by obtaining information from the user's entry, which is potentially in another directory server. Basic Access Control is designed to avoid remote operations in the course of making an access control decision. d) ItemPermission contains a collection of users and their permissions with respect to ProtectedItems within an itemFirst specification. The permissions are specified in grantsAndDenials as discussed in item f). Each of the permissions specified in grantsAndDenials is considered to have the precedence level specified in precedence for the purpose of the ACDF. If precedence is omitted within ItemPermission, then precedence is taken from the precedence specified for ACIItem. e) UserPermission contains a collection of protected items and the associated permissions with respect to userClasses within a userFirst specification. The associated permissions are specified in grantsAndDenials as discussed in item f). Each of the permissions specified in grantsAndDenials is considered to have the precedence level specified in precedence for the purpose of Legg Expires 16 December 2004 [Page 15] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 the ACDF. If precedence is omitted within UserPermission, the precedence is taken from the precedence specified for ACIItem. f) GrantsAndDenials specify the access rights that are granted or denied by the ACI item. g) UniqueIdentifier may be used by the authentication mechanism to distinguish between instances of distinguished name reuse. If this component is present, then for a requestor's name to match the UserClasses of an ACIItem that grants permissions, in addition to the requirement that the requestor's distinguished name match the specified distinguished name, the authentication of the requestor shall yield an associated unique identifier, and that value shall match for equality with the specified value. 3.2.5. Determining Group Membership Determining whether a given requestor is a group member requires checking two criteria. The determination may also be constrained if the group definition is not known locally. The criteria for membership and the treatment of non-local groups are discussed below. a) A directory server is not required to perform a remote operation to determine whether the requestor belongs to a particular group for the purposes of Basic Access Control. If membership in the group cannot be evaluated, the server shall assume that the requestor does not belong to the group if the ACI item grants the permission sought, and does belong to the group if it denies the permission sought. Access control administrators should beware of basing access controls on membership of non-locally available groups or groups which are available only through replication (and which may, therefore, be out of date). b) In order to determine whether the requestor is a member of a userGroup user class, the following criteria apply: - The entry named by the userGroup specification is an instance of the object class groupOfNames or groupOfUniqueNames. - The name of the requestor is a value of the member or uniqueMember attribute of that entry. Values of the member or uniqueMember attribute that do not match the name of the requestor are ignored, even if they represent the names of groups of which the originator could be found to be a member. Hence, nested groups are not supported when evaluating Legg Expires 16 December 2004 [Page 16] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 access controls. 3.3. ACI Operational Attributes ACI is stored as values of operational attributes of entries and subentries. The operational attributes are multi-valued, which allows ACI to be represented as a set of ACI items. 3.3.1. Prescriptive ACI The prescriptiveACI attribute is defined as an operational attribute of an access control subentry. It contains prescriptive ACI applicable to entries within that subentry's scope. The LDAP description [RFC2252] for the prescriptiveACI operational attribute is: ( 2.5.24.4 NAME 'prescriptiveACI' EQUALITY directoryStringFirstComponentMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.1 USAGE directoryOperation ) The directoryStringFirstComponentMatch matching rule is described in [SCHEMA]. Prescriptive ACI within the subentries of a particular administrative point never applies to the same or any other subentry of that administrative point, but can be applicable to the subentries of subordinate administrative points. Note that prescriptiveACI attributes are not collective attributes. Although the values of a prescriptiveACI attribute contribute to access control decisions for each entry within the scope of the subentry that holds the attribute, the prescriptiveACI attribute does not appear as part of those entries. 3.3.2. Entry ACI The entryACI attribute is defined as an operational attribute of an entry or subentry (not just access control subentries). It contains entry ACI applicable to the entry or subentry in which it appears, and that (sub)entry's contents. The LDAP description [RFC2252] for the entryACI operational attribute is: ( 2.5.24.5 NAME 'entryACI' EQUALITY directoryStringFirstComponentMatch Legg Expires 16 December 2004 [Page 17] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 SYNTAX 1.3.6.1.4.1.1466.115.121.1.1 USAGE directoryOperation ) 3.3.3. Subentry ACI The subentryACI attribute is defined as an operational attribute of administrative entries [ADMIN] (for any aspect of administration). It contains subentry ACI that applies to each of the subentries of the administrative entry in which it appears. Only administrative entries are permitted to contain a subentryACI attribute. The LDAP description [RFC2252] for the subentryACI operational attribute is: ( 2.5.24.6 NAME 'subentryACI' EQUALITY directoryStringFirstComponentMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.1 USAGE directoryOperation ) 3.3.4. Protecting the ACI ACI operational attributes are subject to the same protection mechanisms as other attributes. The identificationTag provides an identifier for each ACI item. This tag can be used to remove a specific ACI item value, or to protect it by prescriptive ACI, entry ACI or subentry ACI. Directory rules ensure that only one ACI item per access control operational attribute possesses any specific identificationTag value. The creation of subentries for an administrative entry may be controlled by means of the subentryACI operational attribute in the administrative entry. The right to create prescriptive access controls may also be governed directly by security policy; this provision is required to create access controls in new autonomous administrative areas [ADMIN]. 3.4. Access Control Decision Points for LDAP Operations Each LDAP operation involves making a series of access control decisions on the various protected items that the operation accesses. For some operations (e.g., the Modify operation), each such access control decision must grant access for the operation to succeed; if access is denied to any protected item, the whole operation fails. For other operations (e.g., the Search operation), protected items to which access is denied are simply omitted from the operation result and processing continues. Legg Expires 16 December 2004 [Page 18] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 If the requested access is denied, further access control decisions may be needed to determine if the user has DiscloseOnError permissions to the protected item. Only if DiscloseOnError permission is granted may the server respond with an error that reveals the existence of the protected item. In all other cases, the server MUST act so as to conceal the existence of the protected item. The permissions required to access each protected item, are specified for each operation in the following sections. The algorithm by which a permission is determined to be granted or not granted is specified in Section 3.5. 3.4.1. Common Elements of Procedure This section defines the elements of procedure that are common to all LDAP operations when Basic Access Control is in effect. 3.4.1.1. Alias Dereferencing If, in the process of locating a target object entry (nominated in an LDAP request), alias dereferencing is required, no specific permissions are necessary for alias dereferencing to take place. However, if alias dereferencing would result in a referral being returned, the following sequence of access controls applies. 1) Read permission is required to the alias entry. If permission is not granted, the operation fails in accordance to the procedure described in 5.4.1.3. 2) Read permission is required to the aliasedEntryName attribute and to the single value that it contains. If permission is not granted, the operation fails and the resultCode aliasDereferencingProblem SHALL be returned. The matchedDN field of the LDAPResult SHALL contain the name of the alias entry. In addition to the access controls described above, security policy may prevent the disclosure of knowledge of other servers which would otherwise be conveyed in a referral. If such a policy is in effect the resultCode insufficientAccessRights SHALL be returned. 3.4.1.2. Return of Names in Errors Certain LDAP result codes, i.e., noSuchObject, aliasProblem, invalidDNSyntax and aliasDereferencingProblem, provide the name of an entry in the matchedDN field of an LDAPResult. The DN of an entry SHALL only be provided in the matchedDN field if DiscloseOnError permission is granted to that entry, otherwise, the matchedDN field of the LDAPResult SHALL either contain the name of the next superior Legg Expires 16 December 2004 [Page 19] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 entry to which DiscloseOnError permission is granted, or, if DiscloseOnError permission is not granted to any superior entry, the name of the root DSE (i.e., a zero-length LDAPDN). 3.4.1.3. Non-disclosure of Entry Existence If, while performing an LDAP operation, the necessary entry level permission is not granted to the specified target object entry - e.g., the entry to be modified - the operation fails; if DiscloseOnError permission is granted to the target entry, the resultCode insufficientAccessRights SHALL be returned, otherwise, the resultCode noSuchObject SHALL be returned. The matchedDN field of the LDAPResult SHALL either contain the name of the next superior entry to which DiscloseOnError permission is granted, or, if DiscloseOnError permission is not granted to any superior entry, the name of the root DSE (i.e., a zero-length LDAPDN). Additionally, whenever the server detects an operational error (including a referral resultCode), it shall ensure that in returning that error it does not compromise the existence of the named target entry and any of its superiors. For example, before returning a resultCode of timeLimitExceeded or notAllowedOnNonLeaf, the server verifies that DiscloseOnError permission is granted to the target entry. If it is not, the procedure described in the paragraph above SHALL be followed. 3.4.2. Compare Operation Decision Points The following sequence of access controls applies for an entry being compared. 1) Read permission for the entry to be compared is required. If permission is not granted, the operation fails in accordance with 5.4.1.3. 2) Compare permission for the attribute to be compared is required. If permission is not granted, the operation fails: if DiscloseOnError permission is granted to the attribute being compared, a resultCode of insufficientAccessRight SHALL be returned, otherwise, the resultCode noSuchAttribute SHALL be returned. 3) If there exists a value within the attribute being compared that matches the purported argument and for which Compare permission is granted, the operation returns the resultCode compareTrue, otherwise the operation returns the resultCode compareFalse. 3.4.3. Search Operation Decision Points Legg Expires 16 December 2004 [Page 20] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 The following sequence of access controls applies for a portion of the DIT being searched. 1) No specific permission is required to the entry identified by the baseObject argument in order to initiate a search. However, if the baseObject is within the scope of the SearchArgument (i.e., when the subset argument specifies baseObject or wholeSubtree) the access controls specified in 2) through 5) will apply. 2) Browse or Read permission is required for the single entry within the scope of a baseObject search. An entry for which neither of these permissions is granted is ignored. This differs from the X.500 DAP Search operation where the Browse permission alone is required. An entry with Read permission but not Browse permission cannot be searched but can still be examined with an X.500 DAP Read operation. LDAP relies on baseObject search operations to provide the functionality of the DAP Read operation. Accepting Read permission for the target entry in a baseObject search gives an LDAP baseObject search the same access rights to the entry as the DAP Read operation. 3) Browse permission is required for an entry within the scope of a singleLevel or wholeSubtree search to be a candidate for consideration. Entries for which this permission is not granted are ignored. 4) The filter argument is applied to each entry left to be considered after taking 2) and 3) into account, in accordance with the following: a) For a present Filter item, if there exists an attribute value such that the attribute type of the value (possibly a subtype of the attribute type in the FilterItem) satisfies the Filter item and FilterMatch permission is granted for the value and for the attribute type then the FilterItem evaluates to TRUE, otherwise, it evaluates to FALSE. If a directory server does not support True/False filters [FILTER] on LDAP searches, or if directory clients do not exploit this capability, then access control administrators SHOULD grant FilterMatch permission for the objectClass attribute over entries where Read permission is also granted so that an LDAP baseObject search with a filter testing for the presence of the objectClass attribute will have the same access rights to the target entry as the DAP Read operation. An LDAP baseObject search with a True filter does not require FilterMatch permission for any particular attribute type. Legg Expires 16 December 2004 [Page 21] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 b) For an equalityMatch, substrings, greaterOrEqual, lessOrEqual, approxMatch or extensibleMatch Filter item, if there exists an attribute value such that the value satisfies the Filter item and FilterMatch permission is granted for the value and for its attribute type (possibly a subtype of the attribute type in the FilterItem) then the FilterItem evaluates to TRUE, otherwise, it evaluates to FALSE. Once the access controls defined in 2) through 4) have been applied, an entry is either selected or discarded. 5) For each selected entry the information returned is as follows: a) ReturnDN permission for an entry is required in order to return its distinguished name in a SearchResultEntry response. If this permission is not granted, the server SHALL either, return the name of a valid alias to the entry, or, omit the entry from the search result. If the base entry of the search was located using an alias, then that alias is known to be a valid alias. Otherwise, how it is ensured that the alias is valid is outside the scope of this specification. Where a server has a choice of alias names available to it for return, it is RECOMMENDED that where possible it choose the same alias name for repeated requests by the same client, in order to provide a consistent service. b) If the typesOnly field of the SearchRequest is TRUE then, for each attribute type that is to be returned, Read permission for the attribute type and Read permission for at least one value of the attribute is required. If permission is not granted, the attribute type is omitted from the attribute list in the SearchResultEntry. If as a consequence of applying these controls no attribute type information is selected, the SearchResultEntry is returned but no attribute type information is conveyed with it (i.e., the attribute list is empty). c) If the typesOnly field of the SearchRequest is FALSE then Read permission is required for each attribute type and for each attribute value that is to be returned. If permission to an attribute type is not granted, the attribute is omitted from the SearchResultEntry. If permission to an attribute value is not granted, the value is omitted from its corresponding attribute. If all values of an attribute are omitted then the attribute type is omitted from the attribute list in the SearchResultEntry. If as a consequence of applying these Legg Expires 16 December 2004 [Page 22] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 controls no attribute information is selected, the SearchResultEntry is returned but no attribute information is conveyed with it (i.e., the attribute list is empty). 6) If as a consequence of applying the above controls to the entire scoped subtree the search result contains no entries (excluding any SearchResultReferences) and if DiscloseOnError permission is not granted to the entry identified by the baseObject argument, the operation fails and the resultCode noSuchObject SHALL be returned. The matchedDN field of the LDAPResult SHALL either contain the name of the next superior entry to which DiscloseOnError permission is granted, or the name of the root DSE (i.e., a zero-length LDAPDN). Otherwise, the operation succeeds but no subordinate information is conveyed with it. Security policy may prevent the disclosure of knowledge of other servers which would otherwise be conveyed as SearchResultReferences. If such a policy is in effect SearchResultReferences are omitted from the search result. No specific permissions are necessary to allow alias dereferencing to take place in the course of a search operation. However, for each alias entry encountered, if alias dereferencing would result in a SearchResultReference being returned, the following access controls apply: Read permission is required to the alias entry, the aliasedEntryName attribute and to the single value that it contains. If any of these permissions is not granted, the SearchResultReference SHALL be omitted from the search result. 3.4.4. Add Operation Decision Points The following sequence of access controls apply for an entry being added. 1) No specific permission is required for the immediate superior of the entry identified by the entry field of the AddRequest. 2) If an entry already exists with a distinguished name equal to the entry field the operation fails; if DiscloseOnError or Add permission is granted to the existing entry, the resultCode entryAlreadyExists SHALL be returned, otherwise, the procedure described in 5.4.1.3 is followed with respect to the entry being added. 3) Add permission is required for the new entry being added. If this permission is not granted, the operation fails; the procedure described in 5.4.1.3 is followed with respect to the entry being added. Legg Expires 16 December 2004 [Page 23] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 The Add permission is provided as prescriptive ACI when attempting to add an entry and as prescriptive ACI or subentry ACI when attempting to add a subentry. Any values of the entryACI attribute in the entry being added SHALL be ignored. 4) Add permission is required for each attribute type and for each value that is to be added. If any permission is absent, the operation fails and the resultCode insufficientAccessRights SHALL be returned. 3.4.5. Delete Operation Decision Points The following sequence of access controls apply for an entry being removed. 1) Remove permission is required for the entry being removed. If this permission is not granted, the operation fails in accordance with 5.4.1.3. 2) No specific permissions are required for any of the attributes and attribute values present within the entry being removed. 3.4.6. Modify Operation Decision Points The following sequence of access controls apply for an entry being modified. 1) Modify permission is required for the entry being modified. If this permission is not granted, the operation fails in accordance with 5.4.1.3. 2) For each of the specified modification arguments applied in sequence, the following permissions are required: a) Add permission is required for each of the attribute values specified in an add modification. If the attribute does not currently exist then Add permission for the attribute type is also required. If these permissions are not granted, or any of the attribute values already exist, the operation fails; if an attribute value already exists and DiscloseOnError or Add is granted to that attribute value, the resultCode attributeOrValueExists SHALL be returned, otherwise, the resultCode insufficientAccessRights SHALL be returned. b) Remove permission is required for the attribute type specified in a delete modification with no listed attribute values. If this permission is not granted, the operation fails; if DiscloseOnError permission is granted to the attribute being Legg Expires 16 December 2004 [Page 24] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 removed and the attribute exists, the resultCode insufficientAccessRights SHALL be returned, otherwise, the resultCode noSuchAttribute SHALL be returned. No specific permissions are required for any of the attribute values present within the attribute being removed. c) Remove permission is required for each of the values in a delete modification with listed attribute values. If all current values of the attribute are specified to be removed (which causes the attribute itself to be removed), then Remove permission for the attribute type is also required. If these permissions are not granted, the operation fails; if DiscloseOnError permission is granted to any of the attribute values being removed, the resultCode insufficientAccessRights SHALL be returned, otherwise, the resultCode noSuchAttribute SHALL be returned. d) Remove and Add permission is required for the attribute type, and Add permission is required for each of the specified attribute values, in a replace modification. If these permissions are not granted the operation fails and the resultCode insufficientAccessRights SHALL be returned. No specific permissions are required to remove any existing attribute values of the attribute being replaced. 3.4.7. Modify DN Operation Decision Points The following sequence of access controls apply for an entry having its DN modified. 1) If the effect of the operation is to change the RDN of the entry then Rename permission (determined with respect to its original name) is required for the entry. If this permission is not granted, the operation fails; the procedure described in 5.4.1.3 is followed with respect to the entry being renamed (considered with its original name). No additional permissions are required even if, as a result of modifying the RDN of the entry, a new distinguished value needs to be added, or an old one removed. No specific permissions are required for the subordinates of the renamed entry. 2) If the effect of the operation is to move an entry to a new superior in the DIT then Export permission (determined with respect to its original name) and Import permission (determined with respect to its new name) are required for the entry. If Legg Expires 16 December 2004 [Page 25] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 either of these permissions is not granted, the operation fails; the procedure described in 5.4.1.3 is followed with respect to the entry being moved (considered with its original name). The Import permission is provided as prescriptive ACI when attempting to move an entry and as prescriptive ACI or subentry ACI when attempting to move a subentry. Any values of the entryACI attribute in the entry or subentry being moved SHALL be ignored. No specific permissions are required for the subordinates of the moved entry. Note that a single Modify DN Operation may simultaneously rename and move an entry. 3.5. Access Control Decision Function This section describes how ACI items are processed in order to decide whether to grant or deny a particular requestor a specified permission to a given protected item. Section 3.5.1 describes the inputs to the ACDF. Sections 3.5.2 through 3.5.4 describe the steps in the ACDF. The output is a decision to grant or deny access to the protected item. 3.5.1. Inputs For each invocation of the ACDF, the inputs are: a) the requestor's Distinguished Name, unique identifier, and authentication level, or as many of these as are available; b) the protected item (an entry, an attribute, or an attribute value) being considered at the current decision point for which the ACDF was invoked; c) the requested permission specified for the current decision point; d) the ACI items applicable to the entry containing (or which is) the protected item. In addition, if the ACI items include any of the protected item constraints described in 5.2.1.4, the whole entry and the number of immediate subordinates of its superior entry may also be required as inputs. 3.5.2. Tuples Legg Expires 16 December 2004 [Page 26] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 For each ACI item, expand the item into a set of tuples, one tuple for each element of the itemPermissions and userPermissions sets, containing the following elements: ( userClasses, authenticationLevel, protectedItems, grantsAndDenials, precedence ) Collect all tuples from all ACI items into a single set. For any tuple whose grantsAndDenials specify both grants and denials, replace the tuple with two tuples - one specifying only grants and the other specifying only denials. 3.5.3. Discarding Irrelevant Tuples Perform the following steps to discard all irrelevant tuples: 1) Discard all tuples that do not include the requestor in the tuple's userClasses as follows: a) For tuples that grant access, discard all tuples that do not include the requestor's identity in the tuples's userClasses element, taking into account UniqueIdentifier elements if relevant. Where a tuple's userClasses specifies a UniqueIdentifier, a matching value shall be present in the requestor's identity if the tuple is not to be discarded. Discard tuples that specify an authentication level higher than that associated with the requestor. b) For tuples that deny access, retain all tuples that include the requestor in the tuple's userClasses element, taking into account uniqueIdentifier elements if relevant. Also retain all tuples that deny access and which specify an authentication level higher than that associated with the requestor. This reflects the fact that the requestor has not adequately proved non-membership in the user class for which the denial is specified. All other tuples that deny access are discarded. 2) Discard all tuples that do not include the protected item in protectedItems. 3) Examine all tuples that include maxValueCount, maxImmSub or restrictedBy. Discard all such tuples which grant access and which do not satisfy any of these constraints. 4) Discard all tuples that do not include the requested permission as one of the set bits in grantsAndDenials. Legg Expires 16 December 2004 [Page 27] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 The order in which tuples are discarded does not change the output of the ACDF. 3.5.4. Highest Precedence and Specificity Perform the following steps to select those tuples of highest precedence and specificity: 1) Discard all tuples having a precedence less than the highest precedence among the remaining tuples. 2) If more than one tuple remains, choose the tuples with the most specific user class. If there are any tuples matching the requestor with UserClasses element name or thisEntry, discard all other tuples. Otherwise if there are any tuples matching UserGroup, discard all other tuples. Otherwise if there are any tuples matching subtree, discard all other tuples. 3) If more than one tuple remains, choose the tuples with the most specific protected item. If the protected item is an attribute and there are tuples that specify the attribute type explicitly, discard all other tuples. If the protected item is an attribute value, and there are tuples that specify the attribute value explicitly, discard all other tuples. A protected item which is a rangeOfValues is to be treated as specifying an attribute value explicitly. Grant access if and only if one or more tuples remain and all grant access. Otherwise deny access. 4. Simplified Access Control This section describes the functionality of the Simplified Access Control scheme. It provides a subset of the functionality found in Basic Access Control. When Simplified Access Control is used, the accessControlScheme operational attribute [ACA] SHALL have the value simplified-access-control (2.5.28.2). The functionality of Simplified Access Control is the same as Basic Access Control except that: 1) Access control decisions shall be made only on the basis of values of prescriptiveACI and subentryACI operational attributes. Values of the entryACI attribute, if present, SHALL NOT be used to make access control decisions. Legg Expires 16 December 2004 [Page 28] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 2) Access Control Inner Areas are not used. Values of prescriptiveACI attributes appearing in subentries of ACIPs SHALL NOT be used to make access control decisions. All other provisions SHALL be as defined for Basic Access Control. 5. Security Considerations Access control administrators should beware of basing access controls on membership of non-locally available groups or groups which are available only through replication (and which may, therefore, be out of date). A particular DSA might not have the ACI governing any data that it caches. Administrators should be aware that a directory server with the capability of caching may pose a significant security risk to other directory servers, in that it may reveal information to unauthorized users. 6. Acknowledgements This document is derived from, and duplicates substantial portions of, Section 8 of X.501 [X501], and selected extracts from X.511 [X511]. 7. IANA Considerations The Internet Assigned Numbers Authority (IANA) is requested to update the LDAP descriptors registry [BCP64] as indicated by the following templates: Subject: Request for LDAP Descriptor Registration Descriptor (short name): basic-access-control Object Identifier: 2.5.28.1 Person & email address to contact for further information: Steven Legg <steven.legg@adacel.com.au> Usage: other (access control scheme) Specification: RFC XXXX Author/Change Controller: IESG Subject: Request for LDAP Descriptor Registration Descriptor (short name): simplified-access-control Object Identifier: 2.5.28.2 Person & email address to contact for further information: Steven Legg <steven.legg@adacel.com.au> Usage: other (access control scheme) Specification: RFC XXXX Author/Change Controller: IESG Legg Expires 16 December 2004 [Page 29] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 Subject: Request for LDAP Descriptor Registration Descriptor (short name): prescriptiveACI Object Identifier: 2.5.24.4 Person & email address to contact for further information: Steven Legg <steven.legg@adacel.com.au> Usage: attribute type Specification: RFC XXXX Author/Change Controller: IESG Subject: Request for LDAP Descriptor Registration Descriptor (short name): entryACI Object Identifier: 2.5.24.5 Person & email address to contact for further information: Steven Legg <steven.legg@adacel.com.au> Usage: attribute type Specification: RFC XXXX Author/Change Controller: IESG Subject: Request for LDAP Descriptor Registration Descriptor (short name): subentryACI Object Identifier: 2.5.24.6 Person & email address to contact for further information: Steven Legg <steven.legg@adacel.com.au> Usage: attribute type Specification: RFC XXXX Author/Change Controller: IESG Appendix A. LDAP Specific Encoding for the ACI Item Syntax This appendix is non-normative. The LDAP-specific encoding for the ACI Item syntax is specified by the Generic String Encoding Rules [GSER]. The ABNF [RFC2234] in this appendix for this syntax is provided only as a convenience and is equivalent to the encoding specified by the application of GSER. Since the ACI Item ASN.1 type may be extended in future editions of X.501 [X501], the provided ABNF should be regarded as a snapshot in time. The LDAP-specific encoding for any extension to the ACI Item ASN.1 type can be determined from the rules of GSER. In the event that there is a discrepancy between this ABNF and the encoding determined by GSER, then GSER is to be taken as definitive. ACIItem = "{" sp aci-identificationTag "," sp aci-precedence "," sp aci-authenticationLevel "," sp aci-itemOrUserFirst sp "}" Legg Expires 16 December 2004 [Page 30] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 aci-identificationTag = id-identificationTag msp DirectoryString aci-precedence = id-precedence msp Precedence aci-authenticationLevel = id-authenticationLevel msp AuthenticationLevel aci-itemOrUserFirst = id-itemOrUserFirst msp ItemOrUserFirst id-identificationTag = %x69.64.65.6E.74.69.66.69.63.61.74.69.6F %x6E.54.61.67 ; "identificationTag" id-precedence = %x70.72.65.63.65.64.65.6E.63.65 ; "precedence" id-authenticationLevel = %x61.75.74.68.65.6E.74.69.63.61.74.69.6F %x6E.4C.65.76.65.6C ; "authenticationLevel" id-itemOrUserFirst = %x69.74.65.6D.4F.72.55.73.65.72.46.69.72 %x73.74 ; "itemOrUserFirst" Precedence = INTEGER-0-MAX ; MUST be less than 256 AuthenticationLevel = al-basicLevels / al-other al-basicLevels = id-basicLevels ":" BasicLevels al-other = id-other ":" EXTERNAL id-basicLevels = %x62.61.73.69.63.4C.65.76.65.6C.73 ; "basicLevels" id-other = %x6F.74.68.65.72 ; "other" BasicLevels = "{" sp bl-level [ "," sp bl-localQualifier ] [ "," sp bl-signed ] sp "}" bl-level = id-level msp Level bl-localQualifier = id-localQualifier msp INTEGER bl-signed = id-signed msp BOOLEAN Level = id-none / id-simple / id-strong id-level = %x6C.65.76.65.6C ; "level" id-localQualifier = %x6C.6F.63.61.6C.51.75.61.6C.69.66.69.65.72 ; "localQualifier" id-signed = %x73.69.67.6E.65.64 ; "signed" id-none = %x6E.6F.6E.65 ; "none" id-simple = %x73.69.6D.70.6C.65 ; "simple" id-strong = %x73.74.72.6F.6E.67 ; "strong" ItemOrUserFirst = ( id-itemFirst ":" ItemFirst ) / ( id-userFirst ":" UserFirst ) id-itemFirst = %x69.74.65.6D.46.69.72.73.74 ; "itemFirst" id-userFirst = %x75.73.65.72.46.69.72.73.74 ; "userFirst" Legg Expires 16 December 2004 [Page 31] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 ItemFirst = "{" sp if-protectedItems "," sp if-itemPermissions sp "}" if-protectedItems = id-protectedItems msp ProtectedItems if-itemPermissions = id-itemPermissions msp ItemPermissions id-protectedItems = %x70.72.6F.74.65.63.74.65.64.49.74.65.6D.73 ; "protectedItems" id-itemPermissions = %x69.74.65.6D.50.65.72.6D.69.73.73.69.6F.6E %x73 ; "itemPermissions" UserFirst = "{" sp uf-userClasses "," sp uf-userPermissions sp "}" uf-userClasses = id-userClasses msp UserClasses uf-userPermissions = id-userPermissions msp UserPermissions id-userClasses = %x75.73.65.72.43.6C.61.73.73.65.73 ; "userClasses" id-userPermissions = %x75.73.65.72.50.65.72.6D.69.73.73.69.6F.6E %x73 ; "userPermissions" ItemPermissions = "{" [ sp ItemPermission *( "," sp ItemPermission ) ] sp "}" ItemPermission = "{" [ sp ip-precedence "," ] sp ip-userClasses "," sp ip-grantsAndDenials sp "}" ip-precedence = id-precedence msp Precedence ip-userClasses = id-userClasses msp UserClasses ip-grantsAndDenials = id-grantsAndDenials msp GrantsAndDenials id-grantsAndDenials = %x67.72.61.6E.74.73.41.6E.64.44.65.6E.69.61 %x6C.73 ; "grantsAndDenials" UserClasses = "{" [ sp uc-allUsers ] [ sep sp uc-thisEntry ] [ sep sp uc-name ] [ sep sp uc-userGroup ] [ sep sp uc-subtree ] sp "}" uc-allUsers = id-allUsers msp NULL uc-thisEntry = id-thisEntry msp NULL uc-name = id-name msp NameAndOptionalUIDs uc-userGroup = id-userGroup msp NameAndOptionalUIDs uc-subtree = id-subtree msp SubtreeSpecifications id-allUsers = %x61.6C.6C.55.73.65.72.73 ; "allUsers" id-thisEntry = %x74.68.69.73.45.6E.74.72.79 ; "thisEntry" id-name = %x6E.61.6D.65 ; "name" id-userGroup = %x75.73.65.72.47.72.6F.75.70 ; "userGroup" id-subtree = %x73.75.62.74.72.65.65 ; "subtree" Legg Expires 16 December 2004 [Page 32] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 NameAndOptionalUIDs = "{" sp NameAndOptionalUID *( "," sp NameAndOptionalUID ) sp "}" NameAndOptionalUID = "{" sp nu-dn [ "," sp nu-uid ] sp "}" nu-dn = id-dn msp DistinguishedName nu-uid = id-uid msp UniqueIdentifier UniqueIdentifier = BIT-STRING id-dn = %x64.6E ; "dn" id-uid = %x75.69.64 ; "uid" SubtreeSpecifications = "{" sp SubtreeSpecification *( "," sp SubtreeSpecification ) sp "}" UserPermissions = "{" [ sp UserPermission *( "," sp UserPermission ) ] sp "}" UserPermission = "{" [ sp up-precedence "," ] sp up-protectedItems "," sp up-grantsAndDenials sp "}" up-precedence = id-precedence msp Precedence up-protectedItems = id-protectedItems msp ProtectedItems up-grantsAndDenials = id-grantsAndDenials msp GrantsAndDenials ProtectedItems = "{" [ sp pi-entry ] [ sep sp pi-allUserAttributeTypes ] [ sep sp pi-attributeType ] [ sep sp pi-allAttributeValues ] [ sep sp pi-allUserTypesAndValues ] [ sep sp pi-attributeValue ] [ sep sp pi-selfValue ] [ sep sp pi-rangeOfValues ] [ sep sp pi-maxValueCount ] [ sep sp pi-maxImmSub ] [ sep sp pi-restrictedBy ] ; contexts omitted [ sep sp pi-classes ] sp "}" pi-entry = id-entry msp NULL pi-allUserAttributeTypes = id-allUserAttributeTypes msp NULL pi-attributeType = id-attributeType msp AttributeTypes pi-allAttributeValues = id-allAttributeValues msp AttributeTypes pi-allUserTypesAndValues = id-allUserAttributeTypesAndValues msp NULL pi-attributeValue = id-attributeValue msp AttributeTypeAndValues Legg Expires 16 December 2004 [Page 33] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 pi-selfValue = id-selfValue msp AttributeTypes pi-rangeOfValues = id-rangeOfValues msp Filter pi-maxValueCount = id-maxValueCount msp MaxValueCounts pi-maxImmSub = id-maxImmSub msp INTEGER pi-restrictedBy = id-restrictedBy msp RestrictedValues pi-classes = id-classes msp Refinement id-entry = %x65.6E.74.72.79 ; "entry" id-allUserAttributeTypes = %x61.6C.6C.55.73.65.72.41.74.74.72.69 %x62.75.74.65.54.79.70.65.73 ; "allUserAttributeTypes" id-attributeType = %x61.74.74.72.69.62.75.74.65.54.79.70 %x65 ; "attributeType" id-allAttributeValues = %x61.6C.6C.41.74.74.72.69.62.75.74.65 %x56.61.6C.75.65.73 ; "allAttributeValues" id-attributeValue = %x61.74.74.72.69.62.75.74.65.56.61.6C %x75.65 ; "attributeValue" id-selfValue = %x73.65.6C.66.56.61.6C.75.65 ; "selfValue" id-rangeOfValues = %x72.61.6E.67.65.4F.66.56.61.6C.75.65 %x73 ; "rangeOfValues" id-maxValueCount = %x6D.61.78.56.61.6C.75.65.43.6F.75.6E %x74 ; "maxValueCount" id-maxImmSub = %x6D.61.78.49.6D.6D.53.75.62 ; "maxImmSub" id-restrictedBy = %x72.65.73.74.72.69.63.74.65.64.42.79 ; "restrictedBy" id-classes = %x63.6C.61.73.73.65.73 ; "classes" id-allUserAttributeTypesAndValues = %x61.6C.6C.55.73.65.72.41.74 %x74.72.69.62.75.74.65.54.79.70.65.73 %x41.6E.64.56.61.6C.75.65.73 ; "allUserAttributeTypesAndValues" AttributeTypes = "{" sp AttributeType *( "," sp AttributeType ) sp "}" AttributeTypeAndValues = "{" sp AttributeTypeAndValue *( "," sp AttributeTypeAndValue ) sp "}" AttributeTypeAndValue = "{" sp atav-type "," sp atav-value sp "}" atav-type = id-type msp AttributeType atav-value = id-value msp Value id-type = %x74.79.70.65 ; "type" id-value = %x76.61.6C.75.65 ; "value" Legg Expires 16 December 2004 [Page 34] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 MaxValueCounts = "{" sp MaxValueCount *( "," sp MaxValueCount ) sp "}" MaxValueCount = "{" sp mvc-type "," sp mvc-maxCount sp "}" mvc-type = id-type msp AttributeType mvc-maxCount = id-maxCount msp INTEGER id-maxCount = %x6D.61.78.43.6F.75.6E.74 ; "maxCount" RestrictedValues = "{" sp RestrictedValue *( "," sp RestrictedValue ) sp "}" RestrictedValue = "{" sp rv-type "," sp rv-valuesin sp "}" rv-type = id-type msp AttributeType rv-valuesin = id-valuesin msp AttributeType id-valuesin = %x76.61.6C.75.65.73.69.6E ; "valuesin" GrantsAndDenials = "{" [ sp grantOrDeny *( "," sp grantOrDeny ) ] sp "}" grantOrDeny = id-grantAdd / id-denyAdd / id-grantDiscloseOnError / id-denyDiscloseOnError / id-grantRead / id-denyRead / id-grantRemove / id-denyRemove / id-grantBrowse / id-denyBrowse / id-grantExport / id-denyExport / id-grantImport / id-denyImport / id-grantModify / id-denyModify / id-grantRename / id-denyRename / id-grantReturnDN / id-denyReturnDN / id-grantCompare / id-denyCompare / id-grantFilterMatch / id-denyFilterMatch ; grantInvoke omitted ; denyInvoke omitted id-grantAdd = %x67.72.61.6E.74.41.64.64 ; "grantAdd" Legg Expires 16 December 2004 [Page 35] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 id-denyAdd = %x64.65.6E.79.41.64.64 ; "denyAdd" id-grantBrowse = %x67.72.61.6E.74.42.72.6F.77.73.65 ; "grantBrowse" id-denyBrowse = %x64.65.6E.79.42.72.6F.77.73.65 ; "denyBrowse" id-grantCompare = %x67.72.61.6E.74.43.6F.6D.70.61.72.65 ; "grantCompare" id-denyCompare = %x64.65.6E.79.43.6F.6D.70.61.72.65 ; "denyCompare" id-grantDiscloseOnError = %x67.72.61.6E.74.44.69.73.63.6C.6F.73.65 %x4F.6E.45.72.72.6F.72 ; "grantDiscloseOnError" id-denyDiscloseOnError = %x64.65.6E.79.44.69.73.63.6C.6F.73.65.4F %x6E.45.72.72.6F.72 ; "denyDiscloseOnError" id-grantExport = %x67.72.61.6E.74.45.78.70.6F.72.74 ; "grantExport" id-denyExport = %x64.65.6E.79.45.78.70.6F.72.74 ; "denyExport" id-grantFilterMatch = %x67.72.61.6E.74.46.69.6C.74.65.72.4D.61.74 %x63.68 ; "grantFilterMatch" id-denyFilterMatch = %x64.65.6E.79.46.69.6C.74.65.72.4D.61.74.63 %x68 ; "denyFilterMatch" id-grantImport = %x67.72.61.6E.74.49.6D.70.6F.72.74 ; "grantImport" id-denyImport = %x64.65.6E.79.49.6D.70.6F.72.74 ; "denyImport" id-grantModify = %x67.72.61.6E.74.4D.6F.64.69.66.79 ; "grantModify" id-denyModify = %x64.65.6E.79.4D.6F.64.69.66.79 ; "denyModify" id-grantRead = %x67.72.61.6E.74.52.65.61.64 ; "grantRead" id-denyRead = %x64.65.6E.79.52.65.61.64 ; "denyRead" id-grantRemove = %x67.72.61.6E.74.52.65.6D.6F.76.65 ; "grantRemove" id-denyRemove = %x64.65.6E.79.52.65.6D.6F.76.65 ; "denyRemove" id-grantRename = %x67.72.61.6E.74.52.65.6E.61.6D.65 ; "grantRename" id-denyRename = %x64.65.6E.79.52.65.6E.61.6D.65 ; "denyRename" id-grantReturnDN = %x67.72.61.6E.74.52.65.74.75.72.6E.44.4E ; "grantReturnDN" id-denyReturnDN = %x64.65.6E.79.52.65.74.75.72.6E.44.4E ; "denyReturnDN" The <sp>, <msp>, <sep>, <AttributeType>, <BIT-STRING>, <BOOLEAN>, Legg Expires 16 December 2004 [Page 36] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 <DirectoryString>, <DistinguishedName>, <EXTERNAL>, <INTEGER>, <INTEGER-0-MAX> and <NULL> rules are described in [GCE]. The <SubtreeSpecification> and <Refinement> rules are described in [SUBENTRY]. The <Value> rule is described in [GSER]. Filter = filter-item / filter-and / filter-or / filter-not filter-item = id-item ":" FilterItem filter-and = id-and ":" SetOfFilter filter-or = id-or ":" SetOfFilter filter-not = id-not ":" Filter id-and = %x61.6E.64 ; "and" id-item = %x69.74.65.6D ; "item" id-not = %x6E.6F.74 ; "not" id-or = %x6F.72 ; "or" SetOfFilter = "{" [ sp Filter *( "," sp Filter ) ] sp "}" FilterItem = fi-equality / fi-substrings / fi-greaterOrEqual / fi-lessOrEqual / fi-present / fi-approximateMatch / fi-extensibleMatch ; contextPresent omitted fi-equality = id-equality ":" AttributeValueAssertion fi-substrings = id-substrings ":" SubstringsAssertion fi-greaterOrEqual = id-greaterOrEqual ":" AttributeValueAssertion fi-lessOrEqual = id-lessOrEqual ":" AttributeValueAssertion fi-present = id-present ":" AttributeType fi-approximateMatch = id-approximateMatch ":" AttributeValueAssertion fi-extensibleMatch = id-extensibleMatch ":" MatchingRuleAssertion id-equality = %x65.71.75.61.6C.69.74.79 ; "equality" id-substrings = %x73.75.62.73.74.72.69.6E.67.73 ; "substrings" id-greaterOrEqual = %x67.72.65.61.74.65.72.4F.72.45.71.75.61.6C ; "greaterOrEqual" id-lessOrEqual = %x6C.65.73.73.4F.72.45.71.75.61.6C ; "lessOrEqual" id-present = %x70.72.65.73.65.6E.74 ; "present" id-approximateMatch = %x61.70.70.72.6F.78.69.6D.61.74.65.4D.61.74 %x63.68 ; "approximateMatch" Legg Expires 16 December 2004 [Page 37] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 id-extensibleMatch = %x65.78.74.65.6E.73.69.62.6C.65.4D.61.74.63 %x68 ; "extensibleMatch" AttributeValueAssertion = "{" sp ava-type "," sp ava-assertion ; assertedContexts omitted sp "}" ava-type = id-type msp AttributeType ava-assertion = id-assertion msp Value id-assertion = %x61.73.73.65.72.74.69.6F.6E ; "assertion" SubstringsAssertion = "{" sp sa-type "," sp sa-strings sp "}" sa-type = id-type msp AttributeType sa-strings = id-strings msp Substrings id-strings = %x73.74.72.69.6E.67.73 ; "strings" Substrings = "{" [ sp Substring *( "," sp Substring ) ] sp "}" Substring = ss-initial / ss-any / ss-final ; control omitted ss-initial = id-initial ":" Value ss-any = id-any ":" Value ss-final = id-final ":" Value id-initial = %x69.6E.69.74.69.61.6C ; "initial" id-any = %x61.6E.79 ; "any" id-final = %x66.69.6E.61.6C ; "final" MatchingRuleAssertion = "{" sp mra-matchingRule [ "," sp mra-type ] "," sp mra-matchValue [ "," sp mra-dnAttributes ] sp "}" mra-matchingRule = id-matchingRule msp MatchingRuleIds mra-type = id-type msp AttributeType mra-matchValue = id-matchValue msp Value mra-dnAttributes = id-dnAttributes msp BOOLEAN id-matchingRule = %x6D.61.74.63.68.69.6E.67.52.75.6C.65 ; "matchingRule" id-matchValue = %x6D.61.74.63.68.56.61.6C.75.65 ; "matchValue" id-dnAttributes = %x64.6E.41.74.74.72.69.62.75.74.65.73 ; "dnAttributes" Legg Expires 16 December 2004 [Page 38] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 MatchingRuleIds = "{" sp MatchingRuleId *( "," sp MatchingRuleId ) sp "}" MatchingRuleId = OBJECT-IDENTIFIER The <OBJECT-IDENTIFIER> rule is described in [GCE]. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 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. [RFC2256] Wahl, M., "A Summary of the X.500(96) User Schema for use with LDAPv3", RFC 2256, December 1997. [RFC3377] Hodges, J. and R. Morgan, "Lightweight Directory Access Protocol (v3): Technical Specification", RFC 3377, September 2002. [BCP64] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protcol (LDAP)", BCP 64, RFC 3383, September 2002. [GSER] Legg, S., "Generic String Encoding Rules for ASN.1 Types", RFC 3641, October 2003. [COLLECT] Zeilenga, K., "Collective Attributes in the Lightweight Directory Access Protocol (LDAP)", RFC 3671, December 2003. [SUBENTRY] Zeilenga, K. and S. Legg, "Subentries in the Lightweight Directory Access Protocol (LDAP)", RFC 3672, December 2003. [SCHEMA] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Additional Matching Rules", RFC 3698, February 2004. [ADMIN] Legg, S., "Lightweight Directory Access Protocol (LDAP): Directory Administrative Model", draft-legg-ldap-admin-xx.txt, a work in progress, June 2004. Legg Expires 16 December 2004 [Page 39] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 [ACA] Legg, S., "Lightweight Directory Access Protocol (LDAP): Access Control Administration", draft-legg-ldap-acm-admin-xx.txt, a work in progress, June 2004. [FILTER] Zeilenga, K., "LDAP Absolute True and False Filters", draft-zeilenga-ldap-t-f-xx.txt, a work in progress, February 2004. [ASN1] ITU-T Recommendation X.680 (07/02) | ISO/IEC 8824-1, Information technology - Abstract Syntax Notation One (ASN.1): Specification of basic notation Informative References [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, November 1997. [GCE] Legg, S., "Common Elements of Generic String Encoding Rules (GSER) Encodings", RFC 3642, October 2003. [X501] ITU-T Recommendation X.501 (02/01) | ISO/IEC 9594-2:2001, Information technology - Open Systems Interconnection - The Directory: Models [X511] ITU-T Recommendation X.511 (02/01) | ISO/IEC 9594-3:2001, Information technology - Open Systems Interconnection - The Directory: Abstract service definition Author's Address Steven Legg Adacel Technologies Ltd. 250 Bay Street Brighton, Victoria 3186 AUSTRALIA Phone: +61 3 8530 7710 Fax: +61 3 8530 7888 EMail: steven.legg@adacel.com.au Full Copyright Statement Copyright (C) The Internet Society (2004). 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 Legg Expires 16 December 2004 [Page 40] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 "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@ietf.org. Changes in Draft 01 The Internet draft draft-legg-ldap-acm-admin-00.txt has been split into two drafts, draft-legg-ldap-admin-00.txt and draft-legg-ldap-acm-admin-01.txt. Section 8 of draft-legg-ldapext-component-matching-06.txt has been extracted to become a separate Internet draft, draft-legg-ldap-gser-xx.txt. The references in this document have been updated accordingly. The term "native LDAP encoding" has been replaced by the term "LDAP-specific encoding" to align with terminology anticipated to be used in the revision of RFC 2252. Changes have been made to the Search Operation Decision Points (Section 3.4.3): In 4) a), the assumed FilterMatch permission for a present match of Legg Expires 16 December 2004 [Page 41] INTERNET-DRAFT Basic and Simplified Access Control June 16, 2004 the objectClass attribute has been removed. An LDAP search with a True filter [FILTER] is the best analogue of the DAP read operation. A True filter does not filter any attribute type and therefore does not require FilterMatch permissions to succeed. In 5) b) and c), there is an additional requirement for Read permission for at least one attribute value before an attribute type can be returned in a search result. Without this change a search result could, in some circumstances, disclose the existence of particular hidden attribute values. Changes in Draft 02 RFC 3377 replaces RFC 2251 as the reference for LDAP. An IANA Considerations section has been added. Changes in Draft 03 The document has been reformatted in line with current practice. Legg Expires 16 December 2004 [Page 42] PK /�c\)��N� N� D doc/alt-openldap11-devel/drafts/draft-ietf-ldapext-ldap-c-api-xx.txtnu �[��� 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@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@netscape.com Tim Howes Loudcloud, Inc. 599 N. Mathilda Avenue Sunnyvale, CA 94085 USA +1 408 744-7300 howes@loudcloud.com Andy Herron Microsoft Corp. 1 Microsoft Way Redmond, WA 98052 USA +1 425 882-8080 andyhe@microsoft.com Mark Wahl Sun Microsystems, Inc. 8911 Capital of Texas Hwy, Suite 4140 Austin, TX 78759 USA +1 626 919 3600 Mark.Wahl@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@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] PK 0�c\��aw�- �- ? doc/alt-openldap11-devel/drafts/draft-zeilenga-ldap-noop-xx.txtnu �[��� INTERNET-DRAFT Kurt D. Zeilenga Intended Category: Standard Track Isode Limited Expires in six months 14 February 2007 The LDAP No-Op Control <draft-zeilenga-ldap-noop-10.txt> Status of this Memo This document is intended to be, after appropriate review and revision, submitted to the IESG for consideration as a 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@ietf.org>. Please send editorial comments directly to the author <Kurt.Zeilenga@Isode.COM>. 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/1id-abstracts.html. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. Copyright (C) The IETF Trust (2007). All Rights Reserved. Please see the Full Copyright section near the end of this document for more information. Zeilenga LDAP No-Op Control [Page 1] INTERNET-DRAFT draft-zeilenga-ldap-noop-10 14 February 2007 Abstract This document defines the Lightweight Directory Access Protocol (LDAP) No-Op control which can be used to disable the normal effect of an operation. The control can be used to discover how a server might react to a particular update request without updating the directory. 1. Overview It is often desirable to be able to determine if a directory operation [RFC4511] would successful complete or not without having the normal effect of the operation take place. For example, an administrative client might want to verify that new user could update their entry (and not other entries) without the directory actually being updated. The mechanism could be used to build more sophisticated security auditing tools. This document defines the Lightweight Directory Access Protocol (LDAP) [RFC4510] No-Op control extension. The presence of the No-Op control in an operation request message disables its normal effect upon the directory which operation would otherwise have. Instead of updating the directory and returning the normal indication of success, the server does not update the directory and indicates so by returning the noOperation resultCode (introduced below). For example, when the No-Op control is present in a LDAP modify operation [RFC4511], the server is do all processing necessary to perform the operation without actually updating the directory. If it detects an error during this processing, it returns a non-success (other than noOperation) resultCode as it normally would. Otherwise, it returns the noOperation. In either case, the directory is left unchanged. This No-Op control is not intended to be to an "effective access" mechanism [RFC2820, U12]. 1.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 [RFC2119]. DN stands for Distinguished Name. DSA stands for Directory System Agent. DSE stands for DSA-specific entry. Zeilenga LDAP No-Op Control [Page 2] INTERNET-DRAFT draft-zeilenga-ldap-noop-10 14 February 2007 2. No-Op Control The No-Op control is an LDAP Control [RFC4511] whose controlType is IANA-ASSIGNED-OID and controlValue is absent. Clients MUST provide a criticality value of TRUE to prevent unintended modification of the directory. The control is appropriate for request messages of LDAP Add, Delete, Modify and ModifyDN operations [RFC4511]. The control is also appropriate for requests of extended operations which update the directory (or other data stores), such as Password Modify Extended Operation [RFC3062]. There is no corresponding response control. When the control is attached to an LDAP request, the server does all normal processing possible for the operation without modification of the directory. That is, when the control is attached to an LDAP request, the directory SHALL NOT be updated and the response SHALL NOT have a resultCode of success (0). A result code other than noOperation (IANA-ASSIGNED-CODE) means that the server is unable or unwilling to complete the processing for the reason indicated by the result code. A result code of noOperation (IANA-ASSIGNED-CODE) indicates that the server discovered no reason why the operation would fail if submitted without the No-Op control. It is noted that there may be reasons why the operation may fail which are only discoverable when submitting without the No-Op control. Servers SHOULD indicate their support for this control by providing IANA-ASSIGNED-OID as a value of the 'supportedControl' attribute type [RFC4512] in their root DSE entry. A server MAY choose to advertise this extension only when the client is authorized to use this operation. 3. Security Considerations The No-Op control mechanism allows directory administrators and users to verify that access control and other administrative policy controls are properly configured. The mechanism may also lead to the development (and deployment) of more effective security auditing tools. Implementors of this LDAP extension should be familiar with security considerations applicable to the LDAP operations [RFC4511] extended by this control, as well as general LDAP security considerations [Roadmap]. Zeilenga LDAP No-Op Control [Page 3] INTERNET-DRAFT draft-zeilenga-ldap-noop-10 14 February 2007 4. IANA Considerations 4.1. Object Identifier It is requested that IANA assign an LDAP Object Identifier [RFC4520] to identify the LDAP No-Op Control defined in this document. Subject: Request for LDAP Object Identifier Registration Person & email address to contact for further information: Kurt Zeilenga <Kurt.Zeilenga@Isode.COM> Specification: RFC XXXX Author/Change Controller: IESG Comments: Identifies the LDAP No-Op Control 4.2 LDAP Protocol Mechanism Registration of this protocol mechanism is requested [RFC4520]. Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: IANA-ASSIGNED-OID Description: No-Op Control Person & email address to contact for further information: Kurt Zeilenga <Kurt.Zeilenga@Isode.COM> Usage: Control Specification: RFC XXXX Author/Change Controller: IESG Comments: none 4.3 LDAP Result Code Assignment of an LDAP Result Code called 'noOperation' is requested. Subject: LDAP Result Code Registration Person & email address to contact for further information: Kurt Zeilenga <Kurt.Zeilenga@Isode.COM> Result Code Name: noOperation Specification: RFC XXXX Author/Change Controller: IESG Comments: none 5. Author's Address Kurt D. Zeilenga Isode Limited Zeilenga LDAP No-Op Control [Page 4] INTERNET-DRAFT draft-zeilenga-ldap-noop-10 14 February 2007 Email: Kurt.Zeilenga@Isode.COM 6. References [[Note to the RFC Editor: please replace the citation tags used in referencing Internet-Drafts with tags of the form RFCnnnn where possible.]] 6.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14 (also RFC 2119), March 1997. [RFC4510] Zeilenga, K. (editor), "LDAP: Technical Specification Road Map", RFC 4510, June 2006. [RFC4511] Sermersheim, J. (editor), "LDAP: The Protocol", RFC 4511, June 2006. [RFC4512] Zeilenga, K. (editor), "LDAP: Directory Information Models", RFC 4512, June 2006. 6.2. Informative References [X.500] International Telecommunication Union - Telecommunication Standardization Sector, "The Directory -- Overview of concepts, models and services," X.500(1993) (also ISO/IEC 9594-1:1994). [RFC2820] Stokes, E., et. al., "Access Control Requirements for LDAP", RFC 2820, May 2000. [RFC3062] Zeilenga, K., "LDAP Password Modify Extended Operation", RFC 3062, February 2000. [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", RFC 4520, BCP 64, June 2006. 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 Zeilenga LDAP No-Op Control [Page 5] INTERNET-DRAFT draft-zeilenga-ldap-noop-10 14 February 2007 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@ietf.org. Full Copyright Copyright (C) The IETF Trust (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, THE IETF TRUST 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. Zeilenga LDAP No-Op Control [Page 6] PK 0�c\�_���Y �Y = doc/alt-openldap11-devel/drafts/draft-zeilenga-ldap-relax.txtnu �[��� INTERNET-DRAFT Kurt D. Zeilenga Intended Category: Experimental Isode Limited Expires in six months 14 February 2007 The LDAP Relax Rules Control <draft-zeilenga-ldap-relax-01.txt> Status of this Memo This document is intended to be, after appropriate review and revision, submitted to the RFC Editor for publication as an Experimental document. Distribution of this memo is unlimited. Technical discussion of this document will take place on the IETF LDAP Extensions mailing list <ldapext@ietf.org>. Please send editorial comments directly to the author <Kurt.Zeilenga@Isode.COM>. This document replaces draft-zeilenga-ldap-managedit-xx.txt. 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/1id-abstracts.html. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. Copyright (C) The IETF Trust (2007). All Rights Reserved. Please see the Full Copyright section near the end of this document for more information. Zeilenga LDAP Relax Rules Control [Page 1] INTERNET-DRAFT draft-zeilenga-ldap-relax-01 14 February 2007 Abstract This document defines the Lightweight Directory Access Protocol (LDAP) Relax Rules Control which allows a directory user agent (a client) to request the directory service temporarily relax enforcement of various data and service model rules. 1. Background and Intended Use Directory servers accessible via Lightweight Directory Access Protocol (LDAP) [RFC4510] are expected to act in accordance with the X.500 [X.500] series of ITU-T Recommendations. In particular, servers are expected to ensure the X.500 data and service models are not violated. An LDAP server is expected to prevent modification of the structural object class of an object [RFC4512]. That is, the X.500 models do not allow a 'person' object to be transformed into an 'organizationalPerson' object through modification of the object. Instead, the 'person' object must be deleted and then a new 'organizationalPerson' object created in its place. This approach, aside from being inconvient, is problematic for a number reasons. First, as LDAP does not have a standardized method for performing the two operations in a single transaction, the intermediate directory state (after the delete, before the add) is visible to other clients, which may lead to undesirable client behavior. Second, attributes such as 'entryUUID' [RFC4530] will reflect the object was replaced, not transformed. An LDAP server is expected to prevent clients from modifying values of NO-USER-MODIFICATION attributes [RFC4512]. For instance, an entry is not allowed to assign or modify the value of the 'entryUUID' attribute. However, where an administrator is restoring a previously existing object, for instance when repartitioning data between directory servers or when migrating from one vendor server product to another, it may be desirable to allow the client to assign or modify the value of the 'entryUUID' attribute. This document defines the LDAP Relax Rules control. This control may be attached to LDAP requests to update the Directory Information Tree (DIT) to request various data and service rules be temporarily relaxed during the performance of the requested DIT update. The server is however to ensure the resulting directory state is valid. Use of this control is expected that use of this extension will be restricted by administrative and/or access controls. It is intended to be used primarily by directory administrators. Zeilenga LDAP Relax Rules Control [Page 2] INTERNET-DRAFT draft-zeilenga-ldap-relax-01 14 February 2007 This extension is considered experimental as it is not yet clear whether it adequately addresses directory administrators' needs for flexible mechanisms for managing directory objects. It is hoped that after suitable amount of time, either this extension or a suitable replacement will be standardization. 1.1. Terminology Protocol elements are described using ASN.1 [X.680] with implicit tags. The term "BER-encoded" means the element is to be encoded using the Basic Encoding Rules [X.690] under the restrictions detailed in Section 5.1 of [RFC4511]. 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]. DSA stands for Directory System Agent, a server. DSE stands for DSA-specific Entry. 2. The Relax Rules Control The Relax Rules control is an LDAP Control [RFC4511] whose controlType is IANA-ASSIGNED-OID, controlValue is empty, and the criticality of TRUE. There is no corresponding response control. The control is appropriate for all LDAP update requests, including add, delete, modify, and modifyDN (rename) [RFC4511]. The presence of the Rules Rules control in an LDAP update request indicates the server temporarily relax X.500 model contraints during performance of the directory update. The server may restrict use of this control and/or limit the extent of the relaxation provided based upon local policy or factors. The server is obligated to ensure the resulting directory state is consistent with the X.500 models. For instance, the server ensure that values of attributes conform to the value syntax. It is noted that while this extension may be used to add or modify objects in a manner which violate the controlling subschema, the presence of objects in the DIT is not inconsistent with the X.500 models. For instance, an object created prior to establshment of a Zeilenga LDAP Relax Rules Control [Page 3] INTERNET-DRAFT draft-zeilenga-ldap-relax-01 14 February 2007 DIT content rule may contain an attribute now precluded by the current controlling DIT Content Rule. Servers implementing this technical specification SHOULD publish the object identifier IANA-ASSIGNED-OID as a value of the 'supportedControl' attribute [RFC4512] in their root DSE. A server MAY choose to advertise this extension only when the client is authorized to use it. 3. Use Cases 3.1. Object metamorphism In absence of this control, an attempt to modify an object's 'objectClass' in a manner which cause a change in the structural object class of the object would normally lead to an objectClassModsProhibited error [RFC4511]. The presence of the Relax Rules control in the modify request requests the change be allowed. If the server is willing and able to allow the change in the structural object class of the object. For instance, to change an 'organization' object into an 'organizationalUnit' object, a client could issue the following LDAP request: dn: o=Unit,dc=example,dc=net control: IANA-ASSIGNED-OID changetype: modify delete: objectClass objectClass: organization - add: objectClass objectClass: organizationalUnit - In this case, the server is expected to either effect the requested change in the structural object class, including updating of the value of the structural object class, or fail the operation. 3.2. Inactive Attribute Types In absence of the Relax Rules control, an attempt to add or modify values to an attribute whose type has been marked inactive in the controlling subschema (its attribute type description contains the OBSOLETE field) [RFC4512] normally results in a failure. Zeilenga LDAP Relax Rules Control [Page 4] INTERNET-DRAFT draft-zeilenga-ldap-relax-01 14 February 2007 In the presence of the Relax Rules control, the server performs the update operation as if the attribute's type is marked active in the controlling subschema (its attribute type description does not contain the OBSOLETE field). 3.3. DIT Content Rules In absence of the Relax Rules control, an attempt to include the name (or OID) of an auxiliary class to an object's 'objectClass' which is not allowed by the controlling DIT Content Rule would be disallowed [RFC4512]. Additionally, an attempt to add values of an attribute not allowed (or explicitly precluded) by the DIT Content Rule would fail. In presence of the Relax Rules control, the server performs the update operation as if the controlling DIT Content Rule allowed any and all known auxiliary classses to be present and allowed any and all known attributes to be present (and precluded no attributes). 3.4. DIT Structure Rules and Name Forms In absence of the Relax Rules control, the service enforces DIT structure rules and name form requirements of the controlling subschema [RFC4512]. In the presence of the Relax Rules control, the server performs the update operation ignoring all DIT structure rules and name forms in the controlling subschema. 3.5. Modification of Nonconformant Objects It is also noted that in absense of this control, modification of an object which presently violates the controlling subschema will fail unless the modification would result in the object conforming to the controlling subschema. That is, modifications of an non-conformant object should result in a conformant object. In the presence of this control, modifications of a non-conformant object need not result in a conformant object. 3.6. NO-USER-MODIFICATION attribute modification In absence of this control, an attempt to modify values of a NO-USER-MODIFICATION attribute [RFC4512] would normally lead to a Zeilenga LDAP Relax Rules Control [Page 5] INTERNET-DRAFT draft-zeilenga-ldap-relax-01 14 February 2007 constraintViolation or other appropriate error [RFC4511]. In the presence of the Relax Rules control in the update request requests the modification be allowed. Relaxation of the NO-USER-MODIFICATION constraint is not appropriate for some operational attribute types. For instance, as the value of the 'structuralObjectClass' is derived by the values of the 'objectClass' attribute, the 'structuralObjectClass' attribute type's NO-USER-MODIFICATION contraint MUST NOT be relaxed. To effect a change in the structuralObjectClass class, values of objectClass should be changed as discussed in Section 3.1. Other attributes for which the NO-USER-MODIFICATION constraint should not be relaxed include 'subschemaSubentry' [RFC4512] and 'collectiveAttributeSubentries' [RFC3671]. The subsections of this section discuss modification of various operational attributes where their NO-USER-MODIFICATION constraint may be relaxed. Future documents may specify where NO-USER-MODIFICATION constraints on other operational attribute may be relaxed. In absence of a document detailing that the NO-USER-MODIFICATION constraint on a particular operational attribute may be relaxed, implementors SHOULD assume relaxation of the constraint is not appropriate for that attribute. 3.1.1. 'entryUUID' attribute To provide a value for the 'entryUUID' [RFC4530] attribute on entry creation, the client should issue an LDAP Add request with a Relax Rules control providing the desired value. For instance: dn: ou=Unit,dc=example,dc=net control: IANA-ASSIGNED-OID changetype: add objectClass: organizationalUnit ou: Unit entryUUID: 597ae2f6-16a6-1027-98f4-d28b5365dc14 In this case, the server is either to add the entry using the provided 'entryUUID' value or fail the request. To provide a replacement value for the 'entryUUID' after entry creation, the client should issue an LDAP Modify request with a Relax Rules control including an approrpiate change. For instance: dn: ou=Unit,dc=example,dc=net control: IANA-ASSIGNED-OID changetype: modify Zeilenga LDAP Relax Rules Control [Page 6] INTERNET-DRAFT draft-zeilenga-ldap-relax-01 14 February 2007 replace: entryUUID entryUUID: 597ae2f6-16a6-1027-98f4-d28b5365dc14 - In this case, the server is either to replace the 'entryUUID' value as requested or fail the request. 3.2.2. createTimestamp To provide a value for the 'createTimestamp' [RFC4512] attribute on entry creation, the client should issue an LDAP Add request with a Relax Rules control providing the desired 'createTimestamp' value. For instance: dn: ou=Unit,dc=example,dc=net control: IANA-ASSIGNED-OID changetype: add objectClass: organizationalUnit ou: Unit createTimestamp: 20060101000000Z In this case, the server is either to add the entry using the provided 'createTimestamp' value or fail the request. To provide a replacement value for the 'createTimestamp' after entry creation, the client should issue an LDAP Modify request with a Relax Rules control including an approrpiate change. For instance: dn: ou=Unit,dc=example,dc=net control: IANA-ASSIGNED-OID changetype: modify replace: createTimestamp createTimestamp: 20060101000000Z - In this case, the server is either to replace the 'createTimestamp' value as requested or fail the request. The server should ensure the requested 'createTimestamp' value is appropriate. In particular, it should fail the request if the requested 'createTimestamp' value is in the future or is greater than the value of the 'modifyTimestamp' attribute. 3.2.3. modifyTimestamp To provide a value for the 'modifyTimestamp' [RFC4512] attribute Zeilenga LDAP Relax Rules Control [Page 7] INTERNET-DRAFT draft-zeilenga-ldap-relax-01 14 February 2007 on entry creation, the client should issue an LDAP Add request with a Relax Rules control providing the desired 'modifyTimestamp' value. For instance: dn: ou=Unit,dc=example,dc=net control: IANA-ASSIGNED-OID changetype: add objectClass: organizationalUnit ou: Unit modifyTimestamp: 20060101000000Z In this case, the server is either to add the entry using the provided 'modifyTimestamp' value or fail the request. To provide a replacement value for the 'modifyTimestamp' after entry creation, the client should issue an LDAP Modify request with a Relax Rules control including an approrpiate change. For instance: dn: ou=Unit,dc=example,dc=net control: IANA-ASSIGNED-OID changetype: modify replace: modifyTimestamp modifyTimestamp: 20060101000000Z - In this case, the server is either to replace the 'modifyTimestamp' value as requested or fail the request. The server should ensure the requested 'modifyTimestamp' value is appropriate. In particular, it should fail the request if the requested 'modifyTimestamp' value is in the future or is less than the value of the 'createTimestamp' attribute. 3.2.3. creatorsName and modifiersName To provide a value for the 'creatorsName' and/or 'modifiersName' [RFC4512] attribute on entry creation, the client should issue an LDAP Add request with a Relax Rules control providing the desired values. For instance: dn: ou=Unit,dc=example,dc=net control: IANA-ASSIGNED-OID changetype: add objectClass: organizationalUnit ou: Unit creatorsName: cn=Jane Doe,dc=example,net Zeilenga LDAP Relax Rules Control [Page 8] INTERNET-DRAFT draft-zeilenga-ldap-relax-01 14 February 2007 modifiersName: cn=Jane Doe,dc=example,net In this case, the server is either to add the entry using the provided values or fail the request. To provide a replacement values after entry creation for either of the 'creatorsName' or 'modifiersName' attributes or both, the client should issue an LDAP Modify request with a Relax Rules control including the approrpiate changes. For instance: dn: ou=Unit,dc=example,dc=net control: IANA-ASSIGNED-OID changetype: modify replace: creatorsName creatorsName: cn=Jane Doe,dc=example,net - replace: modifiersName modifiersName: cn=Jane Doe,dc=example,net - In this case, the server is either to replace the provided values as requested or fail the request. 4. Security Considerations Use of this extension should be subject to appropriate administrative and access controls. Use of this mechanism is intended to be restricted to directory administrators. Security considerations for the base operations [RFC4511] extended by this control, as well as general LDAP security considerations [RFC4510], generally apply to implementation and use of this extension. 5. IANA Considerations 5.1. Object Identifier It is requested that the IANA assign a LDAP Object Identifier [RFC4520] to identify the LDAP Relax Rules Control defined in this document. Subject: Request for LDAP Object Identifier Registration Person & email address to contact for further information: Kurt Zeilenga <Kurt.Zeilenga@Isode.COM> Specification: RFC XXXX Zeilenga LDAP Relax Rules Control [Page 9] INTERNET-DRAFT draft-zeilenga-ldap-relax-01 14 February 2007 Author/Change Controller: Kurt Zeilenga <Kurt.Zeilenga@Isode.COM> Comments: Identifies the LDAP Relax Rules Control 5.2 LDAP Protocol Mechanism Registration of this protocol mechanism [RFC4520] is requested. Subject: Request for LDAP Protocol Mechanism Registration Object Identifier: IANA-ASSIGNED-OID Description: Relax Rules Control Person & email address to contact for further information: Kurt Zeilenga <Kurt.Zeilenga@Isode.COM> Usage: Control Specification: RFC XXXX Author/Change Controller: Kurt Zeilenga <Kurt.Zeilenga@Isode.COM> Comments: none 6. Author's Address Kurt D. Zeilenga Isode Limited Email: Kurt.Zeilenga@Isode.COM 7. References [[Note to the RFC Editor: please replace the citation tags used in referencing Internet-Drafts with tags of the form RFCnnnn where possible.]] 7.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14 (also RFC 2119), March 1997. [RFC3671] Zeilenga, K., "Collective Attributes in LDAP", RFC 3671, December 2003. [RFC4510] Zeilenga, K. (editor), "LDAP: Technical Specification Road Map", RFC 4510, June 2006. [RFC4511] Sermersheim, J. (editor), "LDAP: The Protocol", RFC 4511, June 2006. [RFC4512] Zeilenga, K. (editor), "LDAP: Directory Information Zeilenga LDAP Relax Rules Control [Page 10] INTERNET-DRAFT draft-zeilenga-ldap-relax-01 14 February 2007 Models", RFC 4512, June 2006. [RFC4530] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP) entryUUID Operational Attribute", RFC 4530, June 2006. [X.500] International Telecommunication Union - Telecommunication Standardization Sector, "The Directory -- Overview of concepts, models and services," X.500(1993) (also ISO/IEC 9594-1:1994). 7.2. Informative References [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", RFC 4520, BCP 64, June 2006. 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@ietf.org. Full Copyright Zeilenga LDAP Relax Rules Control [Page 11] INTERNET-DRAFT draft-zeilenga-ldap-relax-01 14 February 2007 Copyright (C) The IETF Trust (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, THE IETF TRUST 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. Zeilenga LDAP Relax Rules Control [Page 12] PK 0�c\?ᕕ\2 \2 E doc/alt-openldap11-devel/drafts/draft-masarati-ldap-whatfailed-xx.txtnu �[��� Network Working Group P. Masarati Internet-Draft Politecnico di Milano Intended status: Standards Track November 19, 2008 Expires: May 23, 2009 LDAP "What Failed?" Control draft-masarati-ldap-whatfailed-00.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 May 23, 2009. Masarati Expires May 23, 2009 [Page 1] Internet-Draft LDAP WHATFAILED November 2008 Abstract This document describes the LDAP "What Failed?" control. This control allows DUAs to request, in response to a failed operation request, the object identifier of those extensions that caused the operation to fail. Table of Contents 1. Background and Intended Use . . . . . . . . . . . . . . . . . 3 2. LDAP "What Failed?" Control . . . . . . . . . . . . . . . . . 4 2.1. Control Semantics . . . . . . . . . . . . . . . . . . . . 4 2.2. Control Request . . . . . . . . . . . . . . . . . . . . . 4 2.3. Control Response . . . . . . . . . . . . . . . . . . . . . 5 3. Implementation Notes . . . . . . . . . . . . . . . . . . . . . 6 4. Security Considerations . . . . . . . . . . . . . . . . . . . 7 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 5.1. Object Identifier Registration . . . . . . . . . . . . . . 8 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 9 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10 7.1. Normative References . . . . . . . . . . . . . . . . . . . 10 7.2. Informative References . . . . . . . . . . . . . . . . . . 10 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 11 Intellectual Property and Copyright Statements . . . . . . . . . . 12 Masarati Expires May 23, 2009 [Page 2] Internet-Draft LDAP WHATFAILED November 2008 1. Background and Intended Use The LDAP Protocol [RFC4510] is extensible. Extensions include controls, extended requests and extensions related to other aspects of the protocol, for example those described in [RFC4526], [RFC4529] and more. Operations may fail for different reasons. The resultCode may help in determining the reason of a failure. The (optional) diagnosticsMessage fields of a LDAPResponse could also be of help. However, according to [RFC4511], implementations MUST NOT rely on the returned values, which are simply intended to be presented as are to human users. In case of failure related to the inability to process a control marked as critical in a request, the specific resultCode unavailableCriticalExtension is returned. In case of failure related to an unrecognized extendedReq, the generic resultCode protocolError is returned. Failures related to handling other extensions may result in other generic resultCode values. As a consequence, DUAs may be unable to exactly determine what extension, if any, caused a failure. The "What Failed?" control represents a means for the DSA to inform DUAs about what specific extensions, if any, caused an error notified by the DSA. 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 [RFC2119]. Masarati Expires May 23, 2009 [Page 3] Internet-Draft LDAP WHATFAILED November 2008 2. LDAP "What Failed?" Control 2.1. Control Semantics The presence of the "What Failed?" LDAP control in a LDAP request indicates that the DUA, in case of error, wishes to receive detailed information about what extension, if any, caused the error. The criticality of the control in the request SHOULD be FALSE. According to the semantics of the criticality field as indicated in [RFC4511], this ensures that in case the control is not recognized by the DSA, it does not cause itself an error. The presence of this control in a request does not guarantee that the DSA will return detailed information about what extensions caused an error. Considering the requirement on the criticality of the control, the DSA MAY simply choose to ignore the control. The DSA MAY hide information about failure in handling an extension to prevent disclosure of other information. The DSA MAY choose to notify an error as soon as it is detected, instead of proceed checking its ability to handle any other extension present in a request. Implementations may choose to check the validity of extensions, including controls, as soon as they are parsed. As a consequence, a critical control might result in an error before thw "What Failed?" control request is parsed. Implementations SHOULD check anyway the presence of this control, unless they detect that the remaining part of the request is malformed. Clients SHOULD NOT rely on any specific ordering of controls handling when requesting the "What Failed?" control. Servers implementing this technical specification SHOULD publish the object identifier whatFailed-oid (IANA assigned; see Section 5) as a value of the 'supportedControl' attribute [RFC4512] in their root DSE. 2.2. Control Request The controlType is whatFailed-oid (IANA assigned; see Section 5); the controlValue MUST be absent; the criticality SHOULD be FALSE. Masarati Expires May 23, 2009 [Page 4] Internet-Draft LDAP WHATFAILED November 2008 2.3. Control Response The controlType is whatFailed-oid (IANA assigned; see Section 5); the controlValue is: controlValue ::= SET OF oid LDAPOID If the set of extension OID is empty, the control is omitted from the response. The criticality MUST be FALSE. Masarati Expires May 23, 2009 [Page 5] Internet-Draft LDAP WHATFAILED November 2008 3. Implementation Notes The "What Failed?" LDAP Control is implemented in OpenLDAP software using the temporary OID 1.3.6.1.4.1.4203.666.5.17 under OpenLDAP's experimental OID arc. Masarati Expires May 23, 2009 [Page 6] Internet-Draft LDAP WHATFAILED November 2008 4. Security Considerations Implementations MUST take measures to prevent the disclosure of sensible information whenever this may result from disclosing what extension caused an error. This can consist in excluding the OID of specific extensions from the controlValue in the response, or in entirely omitting the control in the response. Masarati Expires May 23, 2009 [Page 7] Internet-Draft LDAP WHATFAILED November 2008 5. IANA Considerations 5.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: Pierangelo Masarati <ando@OpenLDAP.org> Specification: (I-D) Author/Change Controller: IESG Comments: Identifies the LDAP "What Failed?" Control request and response Masarati Expires May 23, 2009 [Page 8] Internet-Draft LDAP WHATFAILED November 2008 6. Acknowledgments Masarati Expires May 23, 2009 [Page 9] Internet-Draft LDAP WHATFAILED November 2008 7. References 7.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC4510] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006. [RFC4511] Sermersheim, J., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006. [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006. 7.2. Informative References [RFC4526] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP) Absolute True and False Filters", RFC 4526, June 2006. [RFC4529] Zeilenga, K., "Requesting Attributes by Object Class in the Lightweight Directory Access Protocol", RFC 4529, June 2006. Masarati Expires May 23, 2009 [Page 10] Internet-Draft LDAP WHATFAILED November 2008 Author's Address Pierangelo Masarati Politecnico di Milano Dipartimento di Ingegneria Aerospaziale via La Masa 34 Milano 20156 IT Phone: +39 02 2399 8309 Fax: +39 02 2399 8334 Email: ando@OpenLDAP.org URI: http://www.aero.polimi.it/masarati/ Masarati Expires May 23, 2009 [Page 11] Internet-Draft LDAP WHATFAILED November 2008 Full Copyright Statement Copyright (C) The IETF Trust (2008). 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, THE IETF TRUST 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@ietf.org. Masarati Expires May 23, 2009 [Page 12] PK 0�c\B<u|?6 ?6 9 doc/alt-openldap11-devel/drafts/draft-chu-ldap-csn-xx.txtnu �[��� 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@ietf.org>. Please send editorial comments directly to the author <Kurt@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@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@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@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@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@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@symas.com> Kurt D. Zeilenga OpenLDAP Foundation <Kurt@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] PK 0�c\А{�ˉ ˉ D doc/alt-openldap11-devel/drafts/draft-ietf-ldapext-ldapv3-vlv-xx.txtnu �[��� Internet-Draft D. Boreham, Bozeman Pass LDAPext Working Group J. Sermersheim, Novell Intended Category: Standards Track A. Kashi, Microsoft <draft-ietf-ldapext-ldapv3-vlv-09.txt> Expires: Jun 2003 Nov 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 extension for the Lightweight Directory Access Protocol (LDAP) Search operation. This extension 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 extension 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 Nov 2002 Browsing of Search Results 3. Conventions used in this document The key words "MUST", "SHALL", "SHOULD", "SHOULD NOT", and "MAY" in this document are to be interpreted as described in RFC 2119 [Bradner97]. Protocol elements are described using ASN.1 [X.680]. The term "BER- encoded" means the element is to be encoded using the Basic Encoding Rules [X.690] under the restrictions detailed in Section 5.1 of [LDAPPROT]. The phrase "subsequent virtual list request" is used in this document to describe a search request accompanied by a VirtualListViewRequest control, where the search base, scope, and filter are the same as a previous search request also accompanied by a VirtualListViewRequest control, and where the contextID of the subsequent VirtualListViewRequest control, is set to that of the contextID in the VirtualListViewResponse control that accompanied the previous search response. The phrase "contiguous virtual list request" is used to describe a subsequent virtual list request which is requesting search results adjoining or overlapping the result returned from the prior virtual list request. 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 an ordered [SSS] Lightweight Directory Access Protocol (LDAP) search operation [LDAPPROT]. 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 ordered alphabetically. While there may be tens of thousands of entries in this list, the address book list view displays only 20 such accounts Boreham et al Internet-Draft 2 LDAP Extensions for Scrolling View Nov 2002 Browsing of Search Results 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. 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 ordered result set, centered around a particular target entry. Henceforth, in the interests of brevity, the ordered 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 Virtual List View control acts upon a set of ordered entries and this order must be repeatable for all subsequent virtual list requests. The server- side sorting control is intended to aid in this ordering, but other mechanisms may need to be employed to produce a repeatable order-- especially for entries that don't have a value of the sort key. 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. Boreham et al Internet-Draft 3 LDAP Extensions for Scrolling View Nov 2002 Browsing of Search Results 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" 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. Boreham et al Internet-Draft 4 LDAP Extensions for Scrolling View Nov 2002 Browsing of Search Results - equivalent values (Ci = Cc) indicate that the target is the last entry in the list. - a content count of zero (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 contextID MAY be returned to clients. A client receiving a contextID MUST return it unchanged or not return it at all, in a subsequent request which relates to the same list. The purpose of this interaction is to maintain state information between the client and server. 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 [LDAPPROT]. The controlType is set to "2.16.840.1.113730.3.4.9". 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, an OCTET STRING, is the BER-encoding of the following SEQUENCE: VirtualListViewRequest ::= SEQUENCE { beforeCount INTEGER (0..maxInt), afterCount INTEGER (0..maxInt), target CHOICE { byOffset [0] SEQUENCE { offset INTEGER (1 .. maxInt), contentCount INTEGER (0 .. maxInt) }, Boreham et al Internet-Draft 5 LDAP Extensions for Scrolling View Nov 2002 Browsing of Search Results 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 5. greaterThanOrEqual is a matching rule assertion value defined in [LDAPPROT]. The assertion value is encoded according to the ORDERING matching rule for the attributeDescription in the sort control [SSS]. 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 for the same list view. If the contextID is not known because no contextID has been sent by the server in a VirtualListViewResponse control, it SHALL be omitted. If the server receives a contextID that is invalid, it SHALL fail the search operation and indicate the failure with a protocolError (3) value in the virtualListViewResult field of the VirtualListViewResponse. The contextID provides state information between the client and server. This state information is used by the server to ensure continuity contiguous virtual list requests. When a server receives a VirtualListViewRequest control that includes a contextID, it SHALL determine whether the client has sent a contiguous virtual list request and SHALL provide contiguous entries if possible. If a valid contextID is sent, and the server is unable to determine whether contiguous data is requested, or is unable to provide requested contiguous data, it SHALL fail the search operation and indicate the failure with an unwillingToPerform (53) value in the virtualListViewResult field of the VirtualListViewResponse. contextID values have no validity outside the connection and query with which they were received. A client MUST NOT submit a contextID which it received from a different connection, a different query, or a different server. The type AssertionValue and value maxInt are defined in [LDAPPROT]. 6.2. Response Control Boreham et al Internet-Draft 6 LDAP Extensions for Scrolling View Nov 2002 Browsing of Search Results If the request control is serviced, this response control is included in the SearchResultDone message as part of the controls field of the LDAPMessage, as defined in Section 4.1.12 of [LDAPPROT]. The controlType is set to "2.16.840.1.113730.3.4.10". The controlValue, an OCTET STRING, is the BER-encoding of the following SEQUENCE: VirtualListViewResponse ::= SEQUENCE { targetPosition INTEGER (0 .. maxInt), contentCount INTEGER (0 .. maxInt), virtualListViewResult ENUMERATED { success (0), operationsError (1), protocolError (3), unwillingToPerform (53), insufficientAccessRights (50), timeLimitExceeded (3), adminLimitExceeded (11), innapropriateMatching (18), 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 virtual list request. The presence of a contextID here indicates that the server is willing to return contiguous data from a subsequent search request which uses the same search criteria, accompanied by a VirtualListViewRequest which indicates that the client wishes to receive an adjoining page of data. The virtualListViewResult codes which are common to the LDAP searchResultDone (adminLimitExceeded, timeLimitExceeded, operationsError, unwillingToPerform, insufficientAccessRights, success, other) have the same meanings as defined in [LDAPPROT], but they pertain specifically to the VLV operation. For example, the server could exceed a VLV-specific administrative limit while processing a SearchRequest with a VirtualListViewRequest control. Obviously, the same administrative limit would not be exceeded should Boreham et al Internet-Draft 7 LDAP Extensions for Scrolling View Nov 2002 Browsing of Search Results the same SearchRequest be submitted by the client without the VirtualListViewRequest control. In this case, the client can determine that the administrative limit has been exceeded in servicing the VLV request, and can if it chooses resubmit the SearchRequest without the VirtualListViewRequest control, or with different parameters. insufficientAccessRights means that the server denied the client permission to perform the VLV operation. If the server determines that the results of the search presented exceed the range specified in INTEGER values, or if the client specifies an invalid offset or contentCount, the server MUST set the virtualListViewResult value to offsetRangeError. 6.2.1 virtualListViewError A new LDAP error is introduced called virtualListViewError. Its value is 76. This error indicates that the search operation failed due to the inclusion of the VirtualListViewRequest control. If the resultCode in the SearchResultDone message is set to virtualListViewError (76), then the virtualListViewResult value MUST NOT be success (as virtualListViewResult indicates the specific error condition). If resultCode in the SearchResultDone message is not set to virtualListViewError (76), then the virtualListViewResult value SHOULD be success (0) and its value MUST be ignored. 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 persons 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 baseObject of "o=Ace Industry,c=us"; scope of wholeSubtree; and filter of "(objectClass=person)". We attach a server-side sort control [SSS] to the search request, specifying ascending sort on attribute "cn". To this search request, we attach a virtual list view request control with contents determined by the user activity and send the search request to the server. We display the results from each search result entry 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 to 0, afterCount to 19, contentCount to 0, offset to 1 and send the request to the server. The server duly returns the first Boreham et al Internet-Draft 8 LDAP Extensions for Scrolling View Nov 2002 Browsing of Search Results 20 entries in the list, plus a content count of 78564 and targetPosition of 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 to 19, afterCount to 0, contentCount to 78564, offset to 78564 and send the request to the server. The server returns the last 20 entries in the list, plus a content count of 78564 and a targetPosition of 78564. Next the user presses a page up key. Our page size is 20, so we set beforeCount to 0, afterCount to 19, contentCount to 78564, offset to 78564-19-20 and send the request to the server. The server returns the preceding 20 entries in the list, plus a content count of 78564 and a targetPosition of 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 to 9, afterCount to 10, contentCount to 78564, offset to 53424 and send the request to the server. The server returns the preceding 20 entries in the list, plus a content count of 78564 and a targetPosition of 53424. Lastly, the user types the letter "B". We set beforeCount to 9, afterCount to 10 and greaterThanOrEqual to "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 a content count of 78564 and a targetPosition of 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. Boreham et al Internet-Draft 9 LDAP Extensions for Scrolling View Nov 2002 Browsing of Search Results Client implementers MUST be aware that any offset value returned by the server might be approximate. Do not design clients that only operate correctly when offsets are exact. However, if contextIDs are used, and adjoining pages of information are requested, the server will return contiguous data. Server implementers using indexing technology which features approximate positioning should consider returning contextIDs to clients. The use of a contextID 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 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 an LDAP result code of virtualListViewError and a virtualListViewResult of 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 search scope spans multiple naming contexts that are not held locally, search result references will be returned, and may occur at any point in the search operation. 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 Boreham et al Internet-Draft 10 LDAP Extensions for Scrolling View Nov 2002 Browsing of Search Results 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 or administrative limit. Clients can, using this control, determine how many entries match a particular filter, before the entries are returned to the client. This may require special processing in servers which perform access control checks on entries to determine whether the existence of the entry can be disclosed to the client. 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. IANA Considerations 11.1 Request for LDAP Result Code In accordance with section 3.6 of [LDAPIANA], it is requested that IANA register the LDAP result code virtualListViewError (76) upon Standards Action by the IESG. The value 76 has been suggested by experts, had expert review, and is currently being used by some implementations. If 76 is unavailable on not chosen, the value in the paragraphs in Section 6.2.1 will need to be updated. The following registration template is suggested: Subject: LDAP Result Code Registration Person & email address to contact for further information: Jim Sermersheim Result Code Name: virtualListViewError Specification: RFCXXXX Author/Change Controller: IESG Comments: request LDAP result codes be assigned 12. Acknowledgements Chris Weider, Anoop Anantha, and Michael Armijo of Microsoft co- authored previous versions of this document. Boreham et al Internet-Draft 11 LDAP Extensions for Scrolling View Nov 2002 Browsing of Search Results 13. Normative References [X.680] ITU-T Rec. X.680, "Abstract Syntax Notation One (ASN.1) - Specification of Basic Notation", 1994. [X.690] ITU-T Rec. X.690, "Specification of ASN.1 encoding rules: Basic, Canonical, and Distinguished Encoding Rules", 1994. [LDAPPROT] Wahl, M., Kille, S. and T. Howes, "Lightweight Directory Access Protocol (v3)", Internet Standard, RFC 2251, December, 1997. [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. [LDAPIANA] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", RFC 3383, September 2002. 14. Informative References [SPaged] Weider, C., Herron, A., Anantha, A. and T. Howes, "LDAP Control Extension for Simple Paged Results Manipulation", RFC2696, September 1999. 15. Authors' Addresses David Boreham Bozeman Pass, Inc +1 406 222 7093 david@bozemanpass.com Jim Sermersheim Novell 1800 South Novell Place Provo, Utah 84606, USA jimse@novell.com Asaf Kashi Microsoft Corporation 1 Microsoft Way Redmond, WA 98052, USA +1 425 882-8080 asafk@microsoft.com Boreham et al Internet-Draft 12 LDAP Extensions for Scrolling View Nov 2002 Browsing of Search Results 16. 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 13 PK 0�c\l�ۜ�8 �8 @ doc/alt-openldap11-devel/drafts/draft-ietf-ldapext-locate-xx.txtnu �[��� 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@microsoft.com Paul Leach One Microsoft Way Redmond, WA 98052 paulle@microsoft.com Levon Esibov One Microsoft Way Redmond, WA 98052 levone@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@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]PK 0�c\`Q�< �< ; doc/alt-openldap11-devel/drafts/draft-chu-ldap-ldapi-xx.txtnu �[��� Network Working Group H. Chu Internet-Draft Symas Corp. Intended status: Informational February 28, 2007 Expires: September 1, 2007 Using LDAP Over IPC Mechanisms draft-chu-ldap-ldapi-00.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 September 1, 2007. Copyright Notice Copyright (C) The IETF Trust (2007). Chu Expires September 1, 2007 [Page 1] Internet-Draft LDAP Over IPC February 2007 Abstract When both the LDAP client and server reside on the same machine, communication efficiency can be greatly improved using host- specific IPC mechanisms instead of a TCP session. Such mechanisms can also implicitly provide the client's identity to the server for extremely lightweight authentication. This document describes the implementation of LDAP over Unix IPC that has been in use in OpenLDAP since January 2000, including the URL format used to specify an IPC session. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . 3 2. Conventions . . . . . . . . . . . . . . . . . . . . . 4 3. Motivation . . . . . . . . . . . . . . . . . . . . . . 5 4. User-Visible Specification . . . . . . . . . . . . . . 6 4.1. URL Scheme . . . . . . . . . . . . . . . . . . . . . . 6 5. Implementation Details . . . . . . . . . . . . . . . . 7 5.1. Client Authentication . . . . . . . . . . . . . . . . 7 5.2. Other Platforms . . . . . . . . . . . . . . . . . . . 8 6. Security Considerations . . . . . . . . . . . . . . . 9 7. References . . . . . . . . . . . . . . . . . . . . . . 10 7.1. Normative References . . . . . . . . . . . . . . . . . 10 7.2. Informative References . . . . . . . . . . . . . . . . 10 Appendix A. IANA Considerations . . . . . . . . . . . . . . . . . 11 Author's Address . . . . . . . . . . . . . . . . . . . 12 Intellectual Property and Copyright Statements . . . . 13 Chu Expires September 1, 2007 [Page 2] Internet-Draft LDAP Over IPC February 2007 1. Introduction While LDAP is a distributed access protocol, it is common for clients to be deployed on the same machine that hosts the server. Many applications are built on a tight integration of the client code and a co-resident server. In these tightly integrated deployments, where no actual network traffic is involved in the communication, the use of TCP/IP is overkill. Systems like Unix offer native IPC mechanisms that still provide the stream-oriented semantics of a TCP session, but with much greater efficiency. Since January 2000, OpenLDAP releases have provided the option to establish LDAP sessions over Unix Domain sockets as well as over TCP/IP. Such sessions are inherently as secure as TCP loopback sessions, but they consume fewer system resources, are much faster to establish and tear down, and they also provide secure identification of the client without requiring any additional passwords or other credentials. Chu Expires September 1, 2007 [Page 3] Internet-Draft LDAP Over IPC February 2007 2. Conventions Imperative keywords defined in [RFC2119] are used in this document, and carry the meanings described there. Chu Expires September 1, 2007 [Page 4] Internet-Draft LDAP Over IPC February 2007 3. Motivation Many LDAP sessions consist of just one or two requests. Connection setup and teardown can become a significant portion of the time needed to process these sessions. Also under heavy load, the constraints of the 2MSL limit in TCP become a bottleneck. For example, a modest single processor dual-core AMD64 server running OpenLDAP can handle over 32,000 authentication requests per second on 100Mbps ethernet, with one connection per request. Connected over a host's loopback interface, the rate is much higher, but connections get completely throttled in under one second, because all of the host's port numbers have been used up and are in TIME_WAIT state. So even when the TCP processing overhead is insignificant, the constraints imposed in [RFC0793] create an artificial limit on the server's performance. No such constraints exist when using IPC mechanisms instead of TCP. Chu Expires September 1, 2007 [Page 5] Internet-Draft LDAP Over IPC February 2007 4. User-Visible Specification The only change clients need to implement to use this feature is to use a special URL scheme instead of an ldap:// URL when specifying the target server. Likewise, the server needs to include this URL in the list of addresses on which it will listen. 4.1. URL Scheme The "ldapi:" URL scheme is used to denote an LDAP over IPC session. The address portion of the URL is the name of a Unix Domain socket, which is usually a fully qualified Unix filesystem pathname. Slashes in the pathname must be percent-encoded as described in section 2.1 of [RFC3986] since they do not represent URL path delimiters in this usage. E.g., for a socket named "/var/run/ldapi" the server URL would be "ldapi://%26var%26run%26ldapi/". In all other respects, an ldapi URL conforms to [RFC4516]. If no specific address is supplied, a default address MAY be used implicitly. In OpenLDAP the default address is a compile-time constant and its value is chosen by whoever built the software. Chu Expires September 1, 2007 [Page 6] Internet-Draft LDAP Over IPC February 2007 5. Implementation Details The basic transport uses a stream-oriented Unix Domain socket. The semantics of communication over such a socket are essentially identical to using a TCP session. Aside from the actual connection establishment, no special considerations are needed in the client, libraries, or server. 5.1. Client Authentication Since their introduction in 4.2 BSD Unix, Unix Domain sockets have also allowed passing credentials from one process to another. Modern systems may provide a server with easier means of obtaining the client's identity. The OpenLDAP implementation exploits multiple methods to acquire the client's identity. The discussion that follows is necessarily platform-specific. The OpenLDAP library provides a getpeereid() function to encapsulate all of the mechanisms used to acquire the identity. On FreeBSD and MacOSX the native getpeereid() is used. On modern Solaris systems the getpeerucred() system call is used. On systems like Linux that support the SO_PEERCRED option to getsockopt(), that option is used. On Unix systems lacking these explicit methods, descriptor passing is used. In this case, the client must send a message containing the descriptor as its very first action immediately after the socket is connected. The descriptor is attached to an LDAP Abandon Request [RFC4511] with message ID zero, whose parameter is also message ID zero. This request is a pure no-op, and will be harmlessly ignored by any server that doesn't implement the protocol. For security reasons, the passed descriptor must be tightly controlled. The client creates a pipe and sends the pipe descriptor in the message. The server receives the descriptor and does an fstat() on it to determine the client's identity. The received descriptor MUST be a pipe, and its permission bits MUST only allow access to its owner. The owner uid and gid are then used as the client's identity. Note that these mechanisms are merely used to make the client's identity available to the server. The server will not actually use the identity information unless the client performs a SASL Bind [RFC4513] using the EXTERNAL mechanism. I.e., as with any normal LDAP session, the session remains in the anonymous state until the Chu Expires September 1, 2007 [Page 7] Internet-Draft LDAP Over IPC February 2007 client issues a Bind request. 5.2. Other Platforms It is possible to implement the corresponding functionality on Microsoft Windows-based systems using Named Pipes, but thus far there has been no demand for it, so the implementation has not been written. These are brief notes on the steps required for an implementation. The Pipe should be created in byte-read mode, and the client must specify SECURITY_IMPERSONATION access when it opens the pipe. The server can then retrieve the client's identity using the GetNamedPipeHandleState() function. Since Windows socket handles are not interchangeable with IPC handles, an alternate event handler would have to be provided instead of using Winsock's select() function. Chu Expires September 1, 2007 [Page 8] Internet-Draft LDAP Over IPC February 2007 6. Security Considerations This document describes a mechanism for accessing an LDAP server that is co-resident with the client machine. As such, it is inherently immune to security issues associated with using LDAP across a network. The mechanism also provides a means for a client to authenticate itself to the server without exposing any sensitive passwords. The security of this authentication is equal to the security of the host machine. Chu Expires September 1, 2007 [Page 9] Internet-Draft LDAP Over IPC February 2007 7. References 7.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2717] Petke, R. and I. King, "Registration Procedures for URL Scheme Names", BCP 35, RFC 2717, November 1999. [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005. [RFC4511] Sermersheim, J., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006. [RFC4513] Harrison, R., "Lightweight Directory Access Protocol (LDAP): Authentication Methods and Security Mechanisms", RFC 4513, June 2006. [RFC4516] Smith, M. and T. Howes, "Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator", RFC 4516, June 2006. 7.2. Informative References [RFC0793] Postel, J., "Transmission Control Protocol", STD 7, RFC 793, September 1981. Chu Expires September 1, 2007 [Page 10] Internet-Draft LDAP Over IPC February 2007 Appendix A. IANA Considerations This document satisfies the requirements of [RFC2717] for registration of a new URL scheme. Chu Expires September 1, 2007 [Page 11] Internet-Draft LDAP Over IPC February 2007 Author's Address Howard Chu Symas Corp. 18740 Oxnard Street, Suite 313A Tarzana, California 91356 USA Phone: +1 818 757-7087 Email: hyc@symas.com Chu Expires September 1, 2007 [Page 12] Internet-Draft LDAP Over IPC February 2007 Full Copyright Statement Copyright (C) The IETF Trust (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, THE IETF TRUST 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@ietf.org. Acknowledgment Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Chu Expires September 1, 2007 [Page 13] PK 0�c\��ت; �; < doc/alt-openldap11-devel/drafts/draft-legg-ldap-admin-xx.txtnu �[��� INTERNET-DRAFT S. Legg draft-legg-ldap-admin-02.txt Adacel Technologies Intended Category: Standards Track June 16, 2004 Lightweight Directory Access Protocol (LDAP): Directory Administrative Model Copyright (C) The Internet Society (2004). All Rights Reserved. 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 document is unlimited. Comments should be sent to the author. This Internet-Draft expires on 16 December 2004. Abstract This document adapts the X.500 directory administrative model for use by the Lightweight Directory Access Protocol. The administrative model partitions the Directory Information Tree for various aspects of directory data administration, e.g., subschema, access control and collective attributes. The generic framework that applies to every aspect of administration is described in this document. The definitions that apply for a specific aspect of administration, e.g., access control administration, are described in other documents. Legg Expires 16 December 2004 [Page 1] INTERNET-DRAFT Directory Administrative Model June 16, 2004 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . 2 3. Administrative Areas . . . . . . . . . . . . . . . . . . . . . 2 4. Autonomous Administrative Areas. . . . . . . . . . . . . . . . 3 5. Specific Administrative Areas. . . . . . . . . . . . . . . . . 3 6. Inner Administrative Areas . . . . . . . . . . . . . . . . . . 4 7. Administrative Entries . . . . . . . . . . . . . . . . . . . . 4 8. Security Considerations. . . . . . . . . . . . . . . . . . . . 5 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 5 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 5 10.1. Normative References. . . . . . . . . . . . . . . . . . 5 10.2. Informative References. . . . . . . . . . . . . . . . . 5 11. Author's Address . . . . . . . . . . . . . . . . . . . . . . . 6 Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 6 1. Introduction This document adapts the X.500 directory administrative model [X501] for use by the Lightweight Directory Access Protocol (LDAP) [LDAP]. The administrative model partitions the Directory Information Tree (DIT) for various aspects of directory data administration, e.g., subschema, access control and collective attributes. This document provides the definitions for the generic parts of the administrative model that apply to every aspect of directory data administration. Sections 3 to 7, in conjunction with [SUBENTRY], describe the means by which administrative authority is aportioned and exercised in the DIT. Aspects of administration that conform to the administrative model described in this document are detailed elsewhere, e.g., access control administration is described in [ACA] and collective attribute administration is described in [COLLECT]. This document is derived from, and duplicates substantial portions of, Sections 4 and 8 of X.501 [X501]. 2. Conventions 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 [RFC2119]. 3. Administrative Areas Legg Expires 16 December 2004 [Page 2] INTERNET-DRAFT Directory Administrative Model June 16, 2004 An administrative area is a subtree of the DIT considered from the perspective of administration. The root entry of the subtree is an administrative point. An administrative point is represented by an entry holding an administrativeRole attribute [SUBENTRY]. The values of this attribute identify the kind of administrative point. 4. Autonomous Administrative Areas The DIT may be partitioned into one or more non-overlapping subtrees termed autonomous administrative areas. It is expected that the entries in an autonomous administrative area are all administered by the same administrative authority. An administrative authority may be responsible for several autonomous administrative areas in separated parts of the DIT but it SHOULD NOT arbitrarily partition the collection of entries under its control into autonomous administrative areas (thus creating adjacent autonomous areas administered by the same authority). The root entry of an autonomous administrative area's subtree is called an autonomous administrative point. An autonomous administrative area extends from its autonomous administrative point downwards until another autonomous administrative point is encountered, at which point another autonomous administrative area begins. 5. Specific Administrative Areas Entries in an administrative area may be considered in terms of a specific administrative function. When viewed in this context, an administrative area is termed a specific administrative area. Examples of specific administrative areas are subschema specific administrative areas, access control specific areas and collective attribute specific areas. An autonomous administrative area may be considered as implicitly defining a single specific administrative area for each specific aspect of administration. In this case, there is a precise correspondence between each such specific administrative area and the autonomous administrative area. Alternatively, for each specific aspect of administration, the autonomous administrative area may be partitioned into non-overlapping specific administrative areas. If so partitioned for a particular aspect of administration, each entry of the autonomous administrative area is contained in one and Legg Expires 16 December 2004 [Page 3] INTERNET-DRAFT Directory Administrative Model June 16, 2004 only one specific administrative area for that aspect, i.e., specific administrative areas do not overlap. The root entry of a specific administrative area's subtree is called a specific administrative point. A specific administrative area extends from its specific administrative point downwards until another specific administrative point of the same administrative aspect is encountered, at which point another specific administrative area begins. Specific administrative areas are always bounded by the autonomous administrative area they partition. Where an autonomous administrative area is not partitioned for a specific aspect of administration, the specific administrative area for that aspect coincides with the autonomous administrative area. In this case, the autonomous administrative point is also the specific administrative point for this aspect of administration. A particular administrative point may be the root of an autonomous administrative area and may be the root of one or more specific administrative areas for different aspects of administration. It is not necessary for an administrative point to represent each specific aspect of administrative authority. For example, there might be an administrative point, subordinate to the root of the autonomous administrative area, which is used for access control purposes only. 6. Inner Administrative Areas For some aspects of administration, e.g., access control or collective attributes, inner administrative areas may be defined within the specific administrative areas, to allow a limited form of delegation, or for administrative or operational convenience. An inner administrative area may be nested within another inner administrative area. The rules for nested inner areas are defined as part of the definition of the specific administrative aspect for which they are allowed. The root entry of an inner administrative area's subtree is called an inner administrative point. An inner administrative area (within a specific administrative area) extends from its inner administrative point downwards until a specific administrative point of the same administrative aspect is encountered. An inner administrative area is bounded by the specific administrative area within which it is defined. 7. Administrative Entries Legg Expires 16 December 2004 [Page 4] INTERNET-DRAFT Directory Administrative Model June 16, 2004 An entry located at an administrative point is an administrative entry. Administrative entries MAY have subentries [SUBENTRY] as immediate subordinates. The administrative entry and its associated subentries are used to control the entries encompassed by the associated administrative area. Where inner administrative areas are used, the scopes of these areas may overlap. Therefore, for each specific aspect of administrative authority, a definition is required of the method of combination of administrative information when it is possible for entries to be included in more than one subtree or subtree refinement associated with an inner area defined for that aspect. 8. Security Considerations This document defines a generic framework for employing policy of various kinds, e.g., access controls, to entries in the DIT. Such policy can only be correctly enforced at a directory server holding a replica of a portion of the DIT if the administrative entries for administrative areas that overlap the portion of the DIT being replicated, and the subentries of those administrative entries relevant to any aspect of policy that is required to be enforced at the replica, are included in the replicated information. Administrative entries and subentries SHOULD be protected from unauthorized examination or changes by appropriate access controls. 9. Acknowledgements This document is derived from, and duplicates substantial portions of, Sections 4 and 8 of X.501 [X501]. 10. References 10.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [LDAP] Hodges, J. and R. Morgan, "Lightweight Directory Access Protocol (v3): Technical Specification", RFC 3377, September 2002. [SUBENTRY] Zeilenga, K. and S. Legg, "Subentries in the Lightweight Directory Access Protocol (LDAP)", RFC 3672, December 2003. 10.2. Informative References Legg Expires 16 December 2004 [Page 5] INTERNET-DRAFT Directory Administrative Model June 16, 2004 [COLLECT] Zeilenga, K., "Collective Attributes in the Lightweight Directory Access Protocol (LDAP)", RFC 3671, December 2003. [ACA] Legg, S., "Lightweight Directory Access Protocol (LDAP): Access Control Administration", draft-legg-ldap-acm-admin-xx.txt, a work in progress, June 2004. [X501] ITU-T Recommendation X.501 (02/01) | ISO/IEC 9594-2:2001, Information technology - Open Systems Interconnection - The Directory: Models 11. Author's Address Steven Legg Adacel Technologies Ltd. 250 Bay Street Brighton, Victoria 3186 AUSTRALIA Phone: +61 3 8530 7710 Fax: +61 3 8530 7888 EMail: steven.legg@adacel.com.au Full Copyright Statement Copyright (C) The Internet Society (2004). 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 Legg Expires 16 December 2004 [Page 6] INTERNET-DRAFT Directory Administrative Model June 16, 2004 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@ietf.org. Changes in Draft 00 This document reproduces Section 4 from draft-legg-ldap-acm-admin-00.txt as a standalone document. All changes made are purely editorial. No technical changes have been introduced. Changes in Draft 01 RFC 3377 replaces RFC 2251 as the reference for LDAP. Changes in Draft 02 The document has been reformatted in line with current practice. Legg Expires 16 December 2004 [Page 7] PK 0�c\4ߓ�� �� A doc/alt-openldap11-devel/drafts/draft-joslin-config-schema-xx.txtnu �[��� 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@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' EQUALITY integerMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) ( DUAConfSchemaOID.1.5 NAME 'followReferrals' DESC 'Tells DUA if it should follow referrals returned by a DSA result' EQUALITY booleanMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 SINGLE-VALUE ) ( DUAConfSchemaOID.1.6 NAME 'authenticationMethod' DESC 'A keystring which identifies the type of authentication methods used to contact the DSA' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) ( DUAConfSchemaOID.1.7 NAME 'profileTTL' DESC 'Time to live, in seconds, before a client DUA should re-read this configuration profile' EQUALITY integerMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE ) ( DUAConfSchemaOID.1.9 NAME 'attributeMap' DESC 'Attribute mappings used by a DUA' EQUALITY caseIgnoreIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) ( DUAConfSchemaOID.1.10 NAME 'credentialLevel' Neal-Joslin [Page 7] Internet-Draft DUA Configuration Schema March 2005 DESC 'Identifies type of credentials a DUA should use when binding to the LDAP server' EQUALITY caseIgnoreIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 SINGLE-VALUE ) ( DUAConfSchemaOID.1.11 NAME 'objectclassMap' DESC 'Objectclass mappings used by a DUA' EQUALITY caseIgnoreIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) ( DUAConfSchemaOID.1.12 NAME 'defaultSearchScope' DESC 'Default search scope used by a DUA' EQUALITY caseIgnoreIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 SINGLE-VALUE ) ( DUAConfSchemaOID.1.13 NAME 'serviceCredentialLevel' DESC 'Identifies type of credentials a DUA should use when binding to the LDAP server for a specific service' EQUALITY caseIgnoreIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 ) ( DUAConfSchemaOID.1.14 NAME 'serviceSearchDescriptor' DESC 'LDAP search descriptor list used by a DUA' EQUALITY caseExactMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) ( DUAConfSchemaOID.1.15 NAME 'serviceAuthenticationMethod' DESC 'Identifies type of authentication method a DUA should use when binding to the LDAP server for a specific service' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) ( DUAConfSchemaOID.1.16 NAME 'dereferenceAliases' DESC 'Tells DUA if it should dereference aliases' EQUALITY booleanMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 SINGLE-VALUE ) 4. Class Definition The objectclass below is constructed from the attributes defined in 3, with the exception of the cn attribute, which is defined in RFC 2256 [9]. cn is used to represent the name of the DUA Neal-Joslin [Page 8] Internet-Draft DUA Configuration Schema March 2005 configuration profile. ( DUAConfSchemaOID.2.5 NAME 'DUAConfigProfile' SUP top STRUCTURAL DESC 'Abstraction of a base configuration for a DUA' MUST ( cn ) MAY ( defaultServerList $ preferredServerList $ defaultSearchBase $ defaultSearchScope $ searchTimeLimit $ bindTimeLimit $ credentialLevel $ authenticationMethod $ followReferrals $ dereferenceAliases $ serviceSearchDescriptor $ serviceCredentialLevel $ serviceAuthenticationMethod $ objectclassMap $ attributeMap $ profileTTL ) ) 5. Implementation Details 5.1.1 Interpreting the preferredServerList attribute Interpretation: As described by the syntax, the preferredServerList parameter is a white-space separated list of server addresses and associated port numbers. When the DUA needs to contact a DSA, the DUA MUST first attempt to contact one of the servers listed in the preferredServerList attribute. The DUA MUST contact the DSA specified by the first server address in the list. If that DSA is unavailable, the remaining DSAs MUST be queried in the order provided (left to right) until a connection is established with a DSA. Once a connection with a DSA is established, the DUA SHOULD NOT attempt to establish a connection with the remaining DSAs. The purpose of enumerating multiple DSAs is not for supplemental data, but for high availability of replicated data. This is also the main reason why an LDAP URL[10] syntax was not selected for this document. If the DUA is unable to contact any of the DSAs specified by the preferredServerList, the defaultServerList attribute MUST be examined, as described in 5.1.2. The servers identified by the preferredServerList MUST be contacted before attempting to contact any of the servers specified by the defaultServerList. Syntax: serverList = hostport *(space [hostport]) Neal-Joslin [Page 9] Internet-Draft DUA Configuration Schema March 2005 Default Value: The preferredServerList attribute does not have a default value. Instead a DUA MUST examine the defaultServerList attribute. Other attribute notes: This attribute is used in conjunction with the defaultServerList attribute. Please see section 5.1.2 for additional implementation notes. Determining how the DUA should query the DSAs also depends on the additional configuration attributes, credentialLevel, serviceCredentialLevel, bindTimeLimit, serviceAuthenticationMethod and authenticationMethod. Please review section 5.2 for details on how a DUA should properly bind to a DSA. Example: preferredServerList: 192.168.169.170 ldap1.mycorp.com ldap2:1389 [1080::8:800:200C:417A]:389 5.1.2 Interpreting the defaultServerList attribute Interpretation: The defaultServerList attribute MUST only be examined if the preferredServerList attribute is not provided, or the DUA is unable to establish a connection with one of the DSAs specified by the preferredServerList. If more than one address is provided, the DUA may choose to either accept the order provided, or choose to create its own order, based on what the DUA determines is the "best" order of servers to query. For example, the DUA may choose to examine the server list and choose to query the DSAs in order based on the "closest" server or the server with the least amount of "load." Interpretation of the "best" server order is entirely up to the DUA, and not part of this document. Once the order of server addresses is determined, the DUA contacts the DSA specified by the first server address in the list. If that DSA is unavailable, the remaining DSAs SHOULD be queried until an available DSA is found or no more DSAs are available. If a server address or port is invalid, the DUA SHOULD proceed to the next server address as described just above. Neal-Joslin [Page 10] Internet-Draft DUA Configuration Schema March 2005 Syntax: serverList = hostport *(space [hostport]) Default Value: If a defaultServerList attribute is not provided, the DUA MAY attempt to contact the same DSA that provided the configuration profile entry itself. The default DSA is contacted only if the preferredServerList attribute is also not provided. Other attribute notes: This attribute is used in conjunction with the preferredServerList attribute. Please see section 5.1.1 for additional implementation notes. Determining how the DUA should query the DSAs also depends on the additional configuration attributes, credentialLevel, serviceCredentialLevel, bindTimeLimit, serviceAuthenticationMethod and authenticationMethod. Please review section 5.2 for details on how a DUA should properly contact a DSA. Example: defaultServerList: 192.168.169.170 ldap1.mycorp.com ldap2:1389 [1080::8:800:200C:417A]:5912 5.1.3 Interpreting the defaultSearchBase attribute Interpretation: When a DUA needs to search the DSA for information, this attribute provides the base for the search. This parameter can be overridden or appended by the serviceSearchDescriptor attribute. See section 5.1.6. Syntax: Defined by OID 1.3.6.1.4.1.1466.115.121.1.12 [5] Default Value: There is no default value for the defaultSearchBase. A DUA MAY define its own method for determining the search base, if the defaultSearchBase is not provided. Neal-Joslin [Page 11] Internet-Draft DUA Configuration Schema March 2005 Other attribute notes: This attribute is used in conjunction with the serviceSearchDescriptor attribute. See section 5.1.6. Example: defaultSearchBase: dc=mycompany,dc=com 5.1.4 Interpreting the authenticationMethod attribute Interpretation: The authenticationMethod attribute defines an ordered list of LDAP bind methods to be used when attempting to contact a DSA[11]. The serviceAuthenticationMethod overrides this value for a particular service (see 5.1.15.) Each method MUST be attempted in the order provided by the attribute, until a successful LDAP bind is performed ("none" is assumed to always be successful.) However the DUA MAY skip over one or more methods. See section 5.2 for more information. none - The DUA does not perform an LDAP bind. simple - The DUA performs an LDAP simple bind. sasl - The DUA performs an LDAP SASL[12] bind using the specified SASL mechanism and options. tls - The DUA performs an LDAP StartTLS operation followed by the specified bind method (for more information refer to section 5.1 of RFC 2830 [13]). Syntax: authMethod = method *(";" method) method = none | simple | sasl | tls none = "none" simple = "simple" sasl = "sasl/" saslmech [ ":" sasloption ] sasloption = "auth-conf" | "auth-int" tls = "tls:" (none | simple | sasl) saslmech = SASL mechanism name as defined in [18] Note: Although multiple authentication methods may be specified in the syntax, at most one of each type is allowed. I.E. "simple;simple" is invalid. Default Value: If the authenticationMethod or serviceAuthenticationMethod Neal-Joslin [Page 12] Internet-Draft DUA Configuration Schema March 2005 (for that particular service) attributes are not provided, the DUA MAY choose to bind to the DSA using any method defined by the DUA. However, if either authenticationMethod or serviceAuthenticationMethod are provided, the DUA MUST only use the methods specified. Other attribute notes: When using TLS, the string "tls:sasl/EXTERNAL" implies that two way (DSA and DUA) authentication is to be performed. Any other TLS authentication method implies one way (DSA side credential) authentication. Determining how the DUA should bind to the DSAs also depends on the additional configuration attributes, credentialLevel, serviceCredentialLevel, serviceAuthenticationMethod and bindTimeLimit. Please review section 5.2 for details on how to properly bind to a DSA. Example: authenticationMethod: tls:simple;sasl/DIGEST-MD5 (see [14]) 5.1.5 Interpreting the credentialLevel attribute Interpretation: The credentialLevel attribute defines what type(s) of credential(s) the DUA MUST use when contacting the DSA. The serviceCredentialLevel overrides this value for a particular service (5.1.16.) The credentialLevel can contain more than one credential type, separated by white space. anonymous - The DUA SHOULD NOT use a credential when binding to the DSA. proxy - The DUA SHOULD use a known proxy identity when binding to the DSA. A proxy identity is a specific credential that was created to represent the DUA. This document does not define how the proxy user should be created, or how the DUA should determine what the proxy user's credential is. This functionality is up to each implementation. self - When the DUA is acting on behalf of a known identity, the DUA MUST attempt to bind to the DSA as that identity. The DUA should contain methods to determine the identity of the user such that that identity can be authenticated by the Neal-Joslin [Page 13] Internet-Draft DUA Configuration Schema March 2005 directory server using the defined authentication methods. If the credentialLevel contains more than one credential type, the DUA MUST use the credential types in the order specified. However, the DUA MAY skip over one or more credential types. As soon as the DUA is able to successfully bind to the DSA, the DUA SHOULD NOT attempt to bind using the remaining credential types. Syntax: credentialLevel = level *(space level) level = self | proxy | anonymous self = "self" proxy = "proxy" anonymous = "anonymous" Note: Although multiple credential levels may be specified in the syntax, at most one of each type is allowed. Refer to implementation notes in section 5.2 for additional syntax requirements for the credentialLevel attribute. Default Value: If the credentialLevel attribute is not defined, the DUA SHOULD NOT use a credential when binding to the DSA (also known as anonymous.) Other attribute notes: Determining how the DUA should bind to the DSAs also depends on the additional configuration attributes, authenticationMethod, serviceAuthenticationMethod, serviceCredentialLevel and bindTimeLimit. Please review section 5.2 for details on how to properly bind to a DSA. Example: credentialLevel: proxy anonymous 5.1.6 Interpreting the serviceSearchDescriptor attribute Interpretation: The serviceSearchDescriptor attribute defines how and where a DUA SHOULD search for information for a particular service. The serviceSearchDescriptor contains a serviceID, followed by one or more base-scope-filter triples. These base-scope- Neal-Joslin [Page 14] Internet-Draft DUA Configuration Schema March 2005 filter triples are used to define searches only for the specific service. Multiple base-scope-filters allow the DUA to search for data in multiple locations of the DIT. Although this syntax is very similar to the LDAP URL[8], this draft requires the ability to supply multiple hosts as part of the configuration of the DSA. In addition, an ordered list of search descriptors is required, which can not be specified by the LDAP URL. In addition to the triples, serviceSearchDescriptor might also contain the DN of an entry that will contain an alternate profile. The DSA SHOULD re-evaluate the alternate profile and perform searches as specified by that profile. If the base, as defined in the serviceSearchDescriptor, is followed by the "," (ASCII 0x2C) character, this base is known as a relative base. This relative base may be constructed of one or more RDN components. The DUA MUST define the search base by appending the relative base with the defaultSearchBase. Syntax: serviceSearchList = serviceID ":" serviceSearchDesc *(";" serviceSearchDesc) serviceSearchDesc = confReferral | searchDescriptor searchDescriptor = [base] ["?" [scope] ["?" [filter]]] confReferral = "ref:" DistinguishedName base = DistinguishedName | RelativeBaseName RelativeBaseName = 1*(RelativeDistinguishedName ",") filter = UTF-8 encoded string If the base or filter contains the ";" (ASCII 0x3B) "?" (ASCII 0x3F) """ (ASCII 0x22) or "\" (ASCII 0x5C) characters, those characters MUST be escaped (preceded with the "\" character.) Alternately the DN may be surrounded by quotes (ASCII 0x22.) Refer to RFC 2253, section 4. If the base or filter are surrounded by quotes, only the """ character needs to be escaped. Any character that is preceded by the "\" character, which does not need to be escaped results in both "\" character and the character itself. The usage and syntax of the filter string MUST be defined by the DUA service. A suggested syntax would be that as defined by RFC 2254. If a DUA is performing a search for a particular service, Neal-Joslin [Page 15] Internet-Draft DUA Configuration Schema March 2005 which has a serviceSearchDescriptor defined, the DUA MUST set the base, scope and filter as defined. Each base-scope-filter triple represents a single LDAP search operation. If multiple base-scope-filter triples are provided in the serviceSearchDescriptor, the DUA SHOULD perform multiple search requests and in that case it MUST be in the order specified by the serviceSearchDescriptor. FYI: Service search descriptors do not exactly follow the LDAP URL syntax [7]. The reasoning for this difference is to separate the host name(s) from the filter. This allows the DUA to have a more flexible solution in choosing its DSA. Default Values: If a serviceSearchDescriptor, or an element their-of, is not defined for a particular service, the DUA SHOULD create the base, scope and filter as follows: base - Same as the defaultSearchBase or as defined by the DUA service. scope - Same as the defaultSearchScope or as defined by the DUA service. filter - Use defaults as defined by DUAs service. If the defaultSearchBase or defaultSearchScope are not defined, then the DUA service may use its own default. Other attribute notes: If a serviceSearchDescriptor exists for a given service, the service MUST use at least one base-scope-filter triple in performing searches. It SHOULD perform multiple searches per service if multiple base-scope-filter triples are defined for that service. The details of how the "filter" is interpreted by each DUA's service is defined by that service. This means the filter is NOT REQUIRED to be a legal LDAP filter [15]. Furthermore, determining how attribute and objectclass mapping affects that search filter MUST be defined by the service. I.E. The DUA SHOULD specify if the attributes in the filter have assumed to already have been mapped, or if it is expected that attribute mapping (see 5.1.7) would be applied to the filter. In general practice, implementation and usability suggests that attribute and objectclass mapping (sections 5.1.7 and 5.1.13) SHOULD NOT be applied to the filter defined in the Neal-Joslin [Page 16] Internet-Draft DUA Configuration Schema March 2005 serviceSearchDescriptor. It is assumed the serviceID is unique to a given service within the scope of any DUA that might use the given profile. Example: defaultSearchBase: dc=mycompany,dc=com serviceSearchDescriptor: email:ou=people,ou=org1,? one;ou=contractor,?one; ref:cn=profile,dc=mycompany,dc=com In this example, the DUA MUST search in "ou=people,ou=org1,dc=mycompany,dc=com" first. The DUA then SHOULD search in "ou=contractor,dc=mycompany,dc=com", and finally it SHOULD search other locations as specified in the profile described at "cn=profile,dc=mycompany,dc=com". For more examples, see section 9. 5.1.7 Interpreting the attributeMap attribute Interpretation: A DUA SHOULD perform attribute mapping for all LDAP operations performed for a service that has an attributeMap entry. Because attribute mapping is specific to each service within the DUA, a "serviceID" is required as part of the attributeMap syntax. I.E. not all DUA services should necessarily perform the same attribute mapping. Attribute mapping in general is expected be used to map attributes of similar syntaxes as specified by the service supported by the DUA. However, a DUA is NOT REQUIRED to verify syntaxes of mapped attributes. If the DUA does discover that the syntax of the mapped attribute does not match that of the original attribute, the DUA MAY perform translation between the original syntax and the new syntax. When DUAs do support attribute value translation, the list of capable translations SHOULD be documented in a description of the DUA service. Syntax: attributeMap = serviceID ":" origAttribute "=" attributes origAttribute = attribute Neal-Joslin [Page 17] Internet-Draft DUA Configuration Schema March 2005 attributes = wattribute *( space wattribute ) wattribute = whsp newAttribute whsp newAttribute = descr | "*NULL*" attribute = descr Values of the origAttribute are defined by and SHOULD be documented for the DUA service, as a list of known supported attributes. Default Value: By default, attributes that are used by a DUA service are not mapped unless mapped by the attributeMap attributes. The DUA MUST NOT map an attribute unless it is explicitly defined by an attributeMap attribute. Other attribute notes: When an attribute is mapped to the special keystring "*NULL*", the DUA SHOULD NOT request that attribute from the DSA, when performing a search or compare request. If the DUA is also capable of performing modification on the DSA, the DUA SHOULD NOT attempt to modify any attribute which has been mapped to "*NULL*". It is assumed the serviceID is unique to a given service within the scope of the DSA. A DUA SHOULD support attribute mapping. If it does, the following additional rules apply: 1) The list of attributes that are allowed to be mapped SHOULD defined by and documented for the service. 2) Any supported translation of mapping from attributes of dissimilar syntax SHOULD also be defined and documented. 3) If an attribute may be mapped to multiple attributes the DSA SHOULD define a syntax or usage statement for how the new attribute value will be constructed. Furthermore, the resulting translated syntax of the combined attributes MUST be the same as the attribute being mapped. 4) A DUA MUST support mapping of attributes using the attribute OID. It SHOULD support attribute mapping based on the attribute name. 5) It is recommended that attribute mapping not be applied to Neal-Joslin [Page 18] Internet-Draft DUA Configuration Schema March 2005 parents of the target entries. 6) Attribute mapping is not recursive. In other words, if an attribute has been mapped to a target attribute, that new target attribute MUST NOT be mapped to a third attribute. 7) A given attribute MUST only be mapped once for a given service. Example: Suppose a DUA is acting on behalf of an email service. By default the "email" service uses the "mail", "cn" and "sn" attributes to discover mail addresses. However, the email service has been deployed in an environment that uses "employeeName" instead of "cn." And also instead of using the "mail" attribute for email addresses, the "email" attribute is used for that purpose. In this case, the attribute "cn" can be mapped to "employeeName," allowing the DUA to perform searches using the "employeeName" attribute as part of the search filter, instead of "cn". And "mail" can be mapped to "email" when attempting to retrieve the email address. This mapping is performed by adding the attributeMap attributes to the configuration profile entry as follows (represented in LDIF[16]): attributeMap: email:cn=employeeName attributeMap: email:mail=email As described above, the DUA MAY also map a single attribute to multiple attributes. When mapping a single attribute to more than one attribute, the new syntax or usage of the mapped attribute must be intrinsically defined by the DUAs service. attributeMap: email:cn=firstName lastName In the above example, the DUA creates the new value by generating space separated string using the values of the mapped attributes. In this case, a special mapping must be defined so that a proper search filter can be created. For further information on this example, please refer to section 9. Another possibility for multiple attribute mapping might come in when constructing returned attributes. For example, perhaps all email addresses are of a guaranteed syntax of "uid@domain". And in this example, the uid and domain are Neal-Joslin [Page 19] Internet-Draft DUA Configuration Schema March 2005 separate attributes in the directory. The email service may define that if the "mail" attribute is mapped to two different attributes, it will construct the email address as a concatenation of the uid and domain attributes, placing the "@" character between them. attributeMap: email:mail=uid domain 5.1.8 Interpreting the searchTimeLimit attribute Interpretation: The searchTimeLimit attribute defines the maximum time, in seconds, that a DUA SHOULD allow to perform a search request. Syntax: Defined by OID 1.3.6.1.4.1.1466.115.121.1.27. [5] Default Value: If the searchTimeLimit attribute is not defined or is zero, the search time limit is not enforced by the DUA. Other attribute notes: This time limit only includes the amount of time required to perform the LDAP search operation. If other operations are required, those operations do not need to be considered part of the search time. See bindTimeLimit for the LDAP bind operation. 5.1.9 Interpreting the bindTimeLimit attribute Interpretation: The bindTimeLimit attribute defines the maximum time, in seconds, that a DUA SHOULD allow to perform an LDAP bind request against each server on the preferredServerList or defaultServerList. Syntax: Defined by OID 1.3.6.1.4.1.1466.115.121.1.27. Default Value: Neal-Joslin [Page 20] Internet-Draft DUA Configuration Schema March 2005 If the bindTimeLimit attribute is not defined or is zero, the bind time limit is not enforced by the DUA. Other attribute notes: This time limit only includes the amount of time required to perform the LDAP bind operation. If other operations are required, those operations do not need to be considered part of the bind time. See searchTimeLimit for the LDAP search operation. 5.1.10 Interpreting the followReferrals attribute Interpretation: If set to TRUE, the DUA SHOULD follow any referrals if discovered. If set to FALSE, the DUA MUST NOT follow referrals. Syntax: Defined by OID 1.3.6.1.4.1.1466.115.121.1.7. [5] Default Value: If the followReferrals attribute is not set or set to an invalid value the default value is TRUE. 5.1.11 Interpreting the dereferenceAliases attribute Interpretation: If set to TRUE, the DUA SHOULD enable alias dereferencing. If set to FALSE, the DUA MUST NOT enable alias dereferencing. Syntax: Defined by OID 1.3.6.1.4.1.1466.115.121.1.7. Default Value: If the dereferenceAliases attribute is not set or set to an invalid value the default value is TRUE. 5.1.12 Interpreting the profileTTL attribute Neal-Joslin [Page 21] Internet-Draft DUA Configuration Schema March 2005 Interpretation: The profileTTL attribute defines how often the DUA SHOULD re- load and reconfigure itself using the corresponding configuration profile entry. The value is represented in seconds. Once a DUA reloads the profile entry, it SHOULD re- configure itself with the new values. Syntax: Defined by OID 1.3.6.1.4.1.1466.115.121.1.27. Default Value: If not specified the DUA MAY use its own reconfiguration policy. Other attribute notes: If the profileTTL value is zero, the DUA SHOULD NOT automatically re-load the configuration profile. 5.1.13 Interpreting the objectclassMap attribute Interpretation: A DUA MAY perform objectclass mapping for all LDAP operations performed for a service that has an objectclassMap entry. Because objectclass mapping is specific for each service within the DUA, a "serviceID" is required as part of the objectclassMap syntax. I.E. Not all DUA services should necessarily perform the same objectclass mapping. Objectclass mapping SHOULD be used in conjunction with attribute mapping to map the required schema by the service to an equivalent schema that is available in the directory. Objectclass mapping may or may not be required by a DUA. Often, the objectclass attribute is used in search filters. If a service search descriptor is provided, it is expected that the search filter contains a "correct" search filter (though this is not a requirement,) which does not need to be re-mapped. However, when the service search descriptor is not provided, and the default search filter for that service contains the objectclass attribute, that search filter SHOULD be re-defined by objectclass mapping. If a default search filter is not used, it SHOULD be re-defined through the serviceSearchDescriptor. If a serviceSearchDescriptor is Neal-Joslin [Page 22] Internet-Draft DUA Configuration Schema March 2005 defined for a particular service, it SHOULD NOT be re-mapped by either the objectclassMap or attributeMap values. One condition where the objectclassMap SHOULD be used is when the DUA is providing gateway functionality. In this case, the DUA is acting on behalf of another service, which may pass in a search filter itself. In this type of DUA, the DUA may alter the search filter according to the appropriate attributeMap and objectclassMap values. And in this case, it is also assumed that a serviceSearchDescriptor is not defined. Syntax: objectclassMap = serviceID ":" origObjectclass "=" objectclass origObjectclass = objectclass objectclass = keystring Values of the origObjectclass depend on the type of DUA Service using the objectclass mapping feature. Default Value: The DUA MUST NOT remap an objectclass unless it is explicitly defined by an objectclassMap attribute. Other attribute notes: A DUA SHOULD support objectclass mapping. If it does, the DUA MUST support mapping of objectclasses using the objectclass OID. It SHOULD support objectclass mapping based on the objectclass name. It is assumed the serviceID is unique to a given service within the scope of the DSA. Example: Suppose a DUA is acting on behalf of an email service. By default the "email" service uses the "mail", "cn" and "sn" attributes to discover mail addresses in entries created using inetOrgPerson objectclass[17]. However, the email service has been deployed in an environment that uses entries created using "employee" objectclass. In this case, the attribute "cn" can be mapped to "employeeName", and "inetOrgPerson" can be mapped to "employee", allowing the DUA to perform LDAP operations using the entries that exist in the directory. This mapping is performed by adding attributeMap and Neal-Joslin [Page 23] Internet-Draft DUA Configuration Schema March 2005 objectclassMap attributes to the configuration profile entry as follows (represented in LDIF[16]): attributeMap: email:cn=employeeName objectclassMap: email:inetOrgPerson=employee 5.1.14 Interpreting the defaultSearchScope attribute Interpretation: When a DUA needs to search the DSA for information, this attribute provides the "scope" for the search. This parameter can be overridden by the serviceSearchDescriptor attribute. See section 5.1.6. Syntax: scopeSyntax = "base" | "one" | "sub" Default Value: The default value for the defaultSearchScope SHOULD be defined by the DUA service. If the default search scope for a service is not defined then the scope SHOULD be for the DUA to perform a subtree search. 5.1.15 Interpreting the serviceAuthenticationMethod attribute Interpretation: The serviceAuthenticationMethod attribute defines an ordered list of LDAP bind methods to be used when attempting to contact a DSA for a particular service. Interpretation and use of this attribute is the same as 5.1.4, but specific for each service. Syntax: svAuthMethod = service ":" method *(";" method) Note: Although multiple authentication methods may be specified in the syntax, at most one of each type is allowed. Default Value: If the serviceAuthenticationMethod attribute is not provided, Neal-Joslin [Page 24] Internet-Draft DUA Configuration Schema March 2005 the authenticationMethod SHOULD be followed, or its default. Other attribute notes: Determining how the DUA should bind to the DSAs also depends on the additional configuration attributes, credentialLevel, serviceCredentialLevel and bindTimeLimit. Please review section 5.2 for details on how to properly bind to a DSA. Example: serviceAuthenticationMethod: email:tls:simple;sasl/DIGEST-MD5 5.1.16 Interpreting the serviceCredentialLevel attribute Interpretation: The serviceCredentialLevel attribute defines what type(s) of credential(s) the DUA SHOULD use when contacting the DSA for a particular service. Interpretation and used of this attribute are the same as 5.1.5. Syntax: svCredentialLevel = service ":" level *(space level) Refer to implementation notes in section 5.2 for additional syntax requirements for the credentialLevel attribute. Note: Although multiple credential levels may be specified in the syntax, at most one of each type is allowed. Default Value: If the serviceCredentialLevel attribute is not defined, the DUA MUST examine the credentialLevel attribute, or follow its default if not provided. Other attribute notes: Determining how the DUA should bind to the DSAs also depends on the additional configuration attributes, serviceAuthenticationMethod, authenticationMethod and bindTimeLimit. Please review section 5.2 for details on how to properly bind to a DSA. Example: Neal-Joslin [Page 25] Internet-Draft DUA Configuration Schema March 2005 serviceCredentialLevel: email:proxy anonymous 5.2 Binding to the Directory Server The DUA SHOULD use the following algorithm when binding to the server: for (clevel in credLevel) [see note 1] if (clevel is "anonymous") for (host in hostnames) [see note 2] if (server is responding) return success return failure else for (amethod in authMethod) [see note 3] if (amethod is none) for (host in hostnames) if (server is responding) return success return failure else for (host in hostnames) authenticate using amethod and clevel if (authentication passed) return success return failure Note 1: The credLevel is a list of credential levels as defined in serviceCredentialLevel (section 5.1.16) for a given service. If the serviceCredentialLevel is not defined, the DUA MUST examine the credentialLevel attribute. Note 2: hostnames is the list of servers to contact as defined in 5.1.1 & 5.1.2. Note 3: The authMethod a list of authentication methods as defined in serviceAuthenticationMethod (section 5.1.15) for a given service. If the serviceAuthenticationMethod is not defined, the DUA MUST examine the authenticationMethod attribute. 6. Security Considerations The profile entries MUST be protected against unauthorized modification. Each service needs to consider implications of Neal-Joslin [Page 26] Internet-Draft DUA Configuration Schema March 2005 providing its service configuration as part of this profile and limit access to the profile entries accordingly. The management of the authentication credentials for the DUA is outside the scope of this document and needs to be handled by the DUA. Since the DUA needs to know how to properly bind to the directory server, the access control configuration of the DSA MUST assure that the DSA can view all the elements of the DUAConfigProfile attributes. For example, if the credentialLevel attribute contains "Self" but the DSA is unable to access the credentialLevel attribute, the DUA will instead attempt an anonymous connection to the directory server. The algorithm described by section 5.2 also has security considerations. Altering that design will alter the security aspects of the configuration profile. 7. Acknowledgments There were several additional authors of this document. However we chose to represent only one author per company in the heading. From Sun we also would like to acknowledge Roberto Tam for his design work on Sun's first LDAP name service product and his input for this document. From Hewlett-Packard we'd like to acknowledge Dave Binder for his work architecting Hewlett-Packard's LDAP name service product as well as his design guidance on this document. We'd also like to acknowledge Grace Lu from HP, for her input and implementation of HP's configuration profile manager code. 8. References 8.1 Normative References [4] S. Bradner, "Key Words for use in RFCs to Indicate Requirement Levels", RFC 2119, March 1997. [5] M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight Directory Access Protocol (v3): Attribute Syntax Definitions", RFC 2252, December 1997. [6] M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access Protocol Neal-Joslin [Page 27] Internet-Draft DUA Configuration Schema March 2005 (v3): UTF-8 String Representation of Distinguished Names", RFC 2253, December 1997. [7] T. Howes, M. Smith, "The LDAP URL Format", RFC 2255, December 1997. [8] R. Hinden, B. Carpenter, L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", RFC 3986, January 2005. [9] M. Wahl, "A Summary of the X.500(96) User Schema for use with LDAPv3", RFC 2256, December 1997. [11] M. Wahl, H. Alvestrand, J. Hodges, R. Morgan, "Authentication Methods for LDAP", RFC 2828, May 2000 [13] J. Hodges, R. Morgan, M. Wahl, "Lightweight Directory Access Protocol [v3]: Extension for Transport Layer Security", RFC 2830, May 2000 [18] IANA, "SIMPLE AUTHENTICATION AND SECURITY LAYER (SASL) MECHANISMS", http://www.iana.org/assignments/sasl-mechanisms, April 2004 8.2 Informative References [1] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [2] L. Howard, "An Approach for Using LDAP as a Network Information Service", RFC 2307, March 1998. [3] Microsoft Corporation, "Windows Services for Unix 3.5", http://www.microsoft.com/windows/sfu/default.asp [12] J. Meyers, "Simple Authentication and Security Layer [SASL]", RFC 2222, October 1997 [14] P. Leach, C. Newman, "Using Digest Authentication as a SASL Neal-Joslin [Page 28] Internet-Draft DUA Configuration Schema March 2005 Mechanism", RFC 2831, May 2000 [15] T. Howes, "The String Representation of LDAP Search Filters", RFC 2254, December 1997. [16] G. Good, "The LDAP Data Interchange Format (LDIF) - Technical Specification", RFC 2849, June 2000. [17] M. Smith, "Definition of the inetOrgPerson LDAP Object Class", RFC 2789, April 2000 9. Examples In this section we will describe a fictional DUA which provides one service, called the "email" service. This service would be similar to an email client that uses an LDAP directory to discover email addresses based on a textual representation of the recipient's colloquial name. This email service is defined by default to expect that users with email addresses will be of the "inetOrgPerson" objectclass type [17]. And by default, the "email" service expects the colloquial name to be stored in the "cn" attribute, while it expects the email address to be stored in the "mail" attribute (as one would expect as defined by the inetOrgPerson objectclass.) As a special feature, the "email" service will perform a special type of attribute mapping, when performing searches. If the "cn" attribute has been mapped to two or more attributes, the "email" service will parse the requested search string and map each white- space separated token into the mapped attributes, respectively. The default search filter for the "email" service is "(objectclass=inetOrgPerson)". The email service also defines that when it performs a name to address discovery, it will wrap the search filter inside a complex search filter as follows: (&(<filter>)(cn~=<name string>) or if "cn" has been mapped to multiple attributes, that wrapping would appear as follows: (&(<filter>)(attr1~=<token1>)(attr2~=<token2>)...) Neal-Joslin [Page 29] Internet-Draft DUA Configuration Schema March 2005 The below examples show how the "email" service builds it search requests, based on the defined profile. In all cases, the defaultSearchBase is "o=airius.com" and the defaultSearchScope is undefined. In addition, for all examples, we assume that the "email" service has been requested to discover the email address for "Jane Hernandez." Example 1: serviceSearchDescriptor: email:"ou=marketing," base: ou=marketing,o=airius.com scope: sub filter: (&(objectclass=inetOrgPerson)(cn~=Jane Hernandez)) Example 2: serviceSearchDescriptor: email:"ou=marketing,"?one? (&(objectclass=inetOrgPerson)(c=us)) attributeMap: email:cn=2.5.4.42 sn Note: 2.5.4.42 is the OID that represents the "givenName" attribute. In this example, the email service performs <name string> parsing as described above to generate a complex search filter. The above example results in one search. base: ou=marketing,o=airius.com scope: one filter: (&(&(objectclass=inetOrgPerson)(c=us)) (2.5.4.42~=Jane)(sn~=Hernandez)) Example 3: serviceSearchDescriptor: email:ou=marketing,"?base attributeMap: email:cn=name This example is invalid, because either the quote should have been escaped, or there should have been a leading quote. Example 4: serviceSearchDescriptor: email:ou=\mar\\keting,\"?base attributeMap: email:cn=name Neal-Joslin [Page 30] Internet-Draft DUA Configuration Schema March 2005 base: ou=\mar\keting," scope: base filter (&(objectclass=inetOrgPerson)(name~=Jane Hernandez)) Example 5: serviceSearchDescriptor: email:ou="marketing",o=supercom This example is invalid, since the quote was not a leading quote, and thus should have been escaped. Example 6: serviceSearchDescriptor: email:??(&(objectclass=person) (ou=Org1 \\(temporary\\))) base: o=airius.com scope: sub filter: (&((&(objectclass=person)(ou=Org1 \(Temporary\))) (cn~=Jane Henderson))) Example 7: serviceSearchDescriptor: email:"ou=funny?org," base: ou=funny?org,o=airius.com scope: sub filter (&(objectclass=inetOrgPerson)(cn~=Jane Hernandez)) Author's Addresses Luke Howard PADL Software Pty. Ltd. PO Box 59 Central Park Vic 3145 Australia EMail: lukeh@padl.com Bob Neal-Joslin Hewlett-Packard Company 19420 Homestead RD MS43-LF Cupertino, CA 95014 USA Phone: +1 408 447-3044 Neal-Joslin [Page 31] Internet-Draft DUA Configuration Schema March 2005 EMail: bob_joslin@hp.com Morteza Ansari Infoblox 475 Potrero Avenue Sunnyvale, CA 94085 USA Phone: +1 408-716-4300 EMail: morteza@infoblox.com Expires September 2005 Neal-Joslin [Page 32] PK 0�c\�� ?V ?V A doc/alt-openldap11-devel/drafts/draft-sermersheim-ldap-csn-xx.txtnu �[��� Network Working Group J. Sermersheim Internet-Draft Novell, Inc Expires: August 5, 2005 H. Chu Symas Corp. February 2005 The LDAP Change Sequence Number draft-sermersheim-ldap-csn-02.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 August 5, 2005. Copyright Notice Copyright (C) The Internet Society (2005). Abstract This document defines a syntax schema element for the Lightweight Directory Access Protocol (LDAP) which is used to hold a Change Sequence Number (CSN). In general, a change sequence number represents the place and time that a directory entity was changed. It may be used by various attributes for various LDAP replication, and synchronization applications. Sermersheim & Chu Expires August 5, 2005 [Page 1] Internet-Draft LDAP CSN February 2005 Discussion Forum Technical discussion of this document will take place on the IETF LDAP Extensions mailing list <ldapext@ietf.org>. Please send editorial comments directly to the author(s). Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . 3 2. Conventions . . . . . . . . . . . . . . . . . . . . . 4 3. Syntaxes . . . . . . . . . . . . . . . . . . . . . . . 5 3.1. ChangeSequenceNumber Syntax . . . . . . . . . . . . . 5 3.2. UTF8String . . . . . . . . . . . . . . . . . . . . . . 6 4. Matching Rules . . . . . . . . . . . . . . . . . . . . 7 4.1. changeSequenceNumberMatch Matching Rule . . . . . . . 7 4.2. utf8CodePointMatch Matching Rule . . . . . . . . . . . 7 4.3. changeSequenceNumberOrderingMatch Matching Rule . . . 7 4.4. utf8CodePointOrderingMatch Matching Rule . . . . . . . 8 5. Attributes . . . . . . . . . . . . . . . . . . . . . . 9 5.1. entryCSN Attribute . . . . . . . . . . . . . . . . . . 9 6. Security Considerations . . . . . . . . . . . . . . . 10 7. Normative References . . . . . . . . . . . . . . . . . 10 Appendix A. IANA Considerations . . . . . . . . . . . . . . . . . 11 A.1. LDAP Object Identifier Registrations . . . . . . . . . 11 A.2. LDAP Descriptor Registrations . . . . . . . . . . . . 11 Authors' Addresses . . . . . . . . . . . . . . . . . . 15 Intellectual Property and Copyright Statements . . . . 16 Sermersheim & Chu Expires August 5, 2005 [Page 2] Internet-Draft LDAP CSN February 2005 1. Introduction A number of technologies have been documented, implemented and experimented with which in one way or another seek to replicate, or synchronize directory data. A common need among these technologies is to determine which of two copies of an element represents the latest or most authoritative data. Part of meeting this need involves associating a change sequence number to an element copy at the time of an update to that element. When replication or synchronization occurs, the change sequence numbers associated with directory elements can be used to decide which element's data will be copied to the other element(s). Sermersheim & Chu Expires August 5, 2005 [Page 3] Internet-Draft LDAP CSN February 2005 2. Conventions Imperative keywords defined in [RFC2119] are used in this document, and carry the meanings described there. The General Considerations of [I-D.ietf-ldapbis-syntaxes] apply to the syntax definition in this document. The terms "directory element" and "element" refer to data held in a directory and may apply to an attribute value, attribute, entry, or any other identifiable directory entity. Sermersheim & Chu Expires August 5, 2005 [Page 4] Internet-Draft LDAP CSN February 2005 3. Syntaxes 3.1. ChangeSequenceNumber Syntax A value of the ChangeSequenceNumber syntax is the time of a change along with a replicaID which represents the Directory System Agent (DSA) holding the element when it was changed. There are also two sequence numbers used to disambiguate directory entities that are changed at the same time and place. The Abstract Syntax Notation One (ASN.1)[X680] type corresponding to this syntax is defined as follows: ChangeSequenceNumber ::= SEQUENCE { time GeneralizedTime, timeCount INTEGER (0 .. MaxInt), replicaID UTF8String, changeCount INTEGER (0 .. MaxInt)} MaxInt INTEGER ::= 2147483647 -- (2^^31 - 1) -- GeneralizedTime is defined in [X680]. Local time without a differential SHALL NOT be used. UTF8String is defined below. The LDAP-specific encoding of a value of this syntax is the Generic String Encoding Rules (GSER)[RFC3641] encoding of the ASN.1 type. Example: { time "196701160315-0700", timeCount 0, replicaID "DSA666", changeCount 1 } The following is an LDAP syntax description [RFC2252] suitable for publication in the subschema. ( IANA-ASSIGNED-OID.1 DESC 'ChangeSequenceNumber' ) Sermersheim & Chu Expires August 5, 2005 [Page 5] Internet-Draft LDAP CSN February 2005 3.2. UTF8String The UTF8String syntax is used to express a string of characters from the [ISO.10646-1.1993] character set (a superset of [Unicode]), encoded following the [UTF-8] algorithm. Note that Unicode characters U+0000 through U+007F are the same as ASCII 0 through 127, respectively, and have the same single octet UTF-8 encoding. Other Unicode characters have a multiple octet UTF-8 encoding. UTF8String::= OCTET STRING -- UTF-8 encoded, -- [ISO10646] characters The LDAP-specific encoding of a value of this syntax are the UTF-8 encoded characters themselves. The following is an LDAP syntax description [RFC2252] suitable for publication in the subschema. ( IANA-ASSIGNED-OID.2 DESC 'UTF8String' ) Sermersheim & Chu Expires August 5, 2005 [Page 6] Internet-Draft LDAP CSN February 2005 4. Matching Rules 4.1. changeSequenceNumberMatch Matching Rule The changeSequenceNumberMatch rule compares an assertion value of the ChangeSequenceNumber syntax to a value of a syntax (e.g the ChangeSequenceNumber syntax) whose corresponding ASN.1 type is ChangeSequenceNumber. The rule evaluates to TRUE if and only if each of the components of the two values evaluate to TRUE using the following rules: o The time component uses generalizedTimeMatch. o The timeCount and changeCount components use integerMatch. o The replicaID component uses utf8CodePointMatch. The following is a LDAP matching rule description [RFC2252] suitable for publication in the subschema. ( IANA-ASSIGNED-OID.3 NAME changeSequenceNumberMatch SYNTAX IANA- ASSIGNED-OID.1 ) 4.2. utf8CodePointMatch Matching Rule The utf8CodePointMatch rule compares an assertion value of the UTF8String syntax to a value of a syntax (e.g the UTF8String syntax) whose corresponding ASN.1 type is UTF8String. The rule evaluates to TRUE if and only if the code points [Unicode] of each of the characters is equal. The following is a LDAP matching rule description [RFC2252] suitable for publication in the subschema. ( IANA-ASSIGNED-OID.4 NAME utf8CodePointMatch SYNTAX IANA-ASSIGNED- OID.2 ) 4.3. changeSequenceNumberOrderingMatch Matching Rule The changeSequenceNumberOrderingMatch rule compares the ChangeSequenceNumber ordering of an assertion value of the ChangeSequenceNumber syntax to a value of a syntax (e.g the ChangeSequenceNumber syntax) whose corresponding ASN.1 type is ChangeSequenceNumber. When evaluating ChangeSequenceNumber values for ordering, the components are evaluated in this order: time, timeCount, replicaID, Sermersheim & Chu Expires August 5, 2005 [Page 7] Internet-Draft LDAP CSN February 2005 changeCount. If a component evaluates to TRUE using the appropriate ordering matching rule specified below, then the rule evaluates to TRUE. Otherwise if the component evaluates to TRUE using the equality matching rule specified below, the next component is evaluated. Otherwise the changeSequenceNumberOrderingMatch rule evaluates to FALSE or Undefined as appropriate. o The time components of the two values are evaluated for ordering using GeneralizedTimeOrderingMatch, and evaluated for equality using GeneralizedTimeMatch. o The timeCount and changeCount components of the two values are evaluated for ordering using integerOrderingMatch, and evaluated for equality using integerMatch. o The replicaID components of the two values are evaluated for ordering using utf8CodePointOrderingMatch and evaluated for equality using utf8CodePointMatch. The following is a LDAP matching rule description [RFC2252] suitable for publication in the subschema. ( IANA-ASSIGNED-OID.5 NAME changeSequenceNumberOrderingMatch SYNTAX SYNTAX IANA-ASSIGNED-OID.1 ) 4.4. utf8CodePointOrderingMatch Matching Rule The utf8CodePointOrderingMatch rule compares the ordering of an assertion value of the UTF8String syntax to a stored value of a syntax (e.g. the UTF8String syntax) whose corresponding ASN.1 type is UTF8String. The rule evaluates to TRUE if, and only if, in the code point collation order, the stored value character string appears earlier than the assertion value character string, i.e., the stored value is "less than" the assertion value. The following is a LDAP matching rule description [RFC2252] suitable for publication in the subschema. ( IANA-ASSIGNED-OID.6 NAME utf8CodePointOrderingMatch SYNTAX IANA- ASSIGNED-OID.2 ) Sermersheim & Chu Expires August 5, 2005 [Page 8] Internet-Draft LDAP CSN February 2005 5. Attributes 5.1. 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.7 NAME entryCSN DESC 'CSN of the entry content' EQUALITY changeSequenceNumberMatch ORDERING changeSequenceNumberOrderingMatch SYNTAX IANA-ASSIGNED-OID.1 SINGLE- VALUE NO-USER-MODIFICATION USAGE directoryOperation ) Servers MAY 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. If the entryCSN attribute is assigned, the attribute SHOULD be updated upon every update of the entry. Sermersheim & Chu Expires August 5, 2005 [Page 9] Internet-Draft LDAP CSN February 2005 6. Security Considerations 7. Normative References [I-D.ietf-ldapbis-syntaxes] Legg, S., "Lightweight Directory Access Protocol (LDAP): Syntaxes and Matching Rules", draft-ietf-ldapbis-syntaxes-11 (work in progress), June 2005. [ISO.10646-1.1993] International Organization for Standardization, "Information Technology - Universal Multiple-octet coded Character Set (UCS) - Part 1: Architecture and Basic Multilingual Plane", ISO Standard 10646-1, May 1993. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2252] Wahl, M., Coulbeck, A., Howes, T., and S. Kille, "Lightweight Directory Access Protocol (v3): Attribute Syntax Definitions", RFC 2252, December 1997. [RFC3383] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 3383, September 2002. [RFC3641] Legg, S., "Generic String Encoding Rules (GSER) for ASN.1 Types", RFC 3641, October 2003. [UTF-8] International Organization for Standardization, "Information Technology - Universal Multiple-octet coded Character Set (UCS) - Amendment 2: UCS Transformation Format 8 (UTF-8)", ISO Standard 10646-1 Addendum 2, October 1996. [Unicode] The Unicode Consortium, "The Unicode Standard", 2004. [X680] International Telecommunications Union, "Abstract Syntax Notation One (ASN.1): Specification of basic notation", ITU-T Recommendation X.680, July 2002. Sermersheim & Chu Expires August 5, 2005 [Page 10] Internet-Draft LDAP CSN February 2005 Appendix A. IANA Considerations Registration of the following values is requested [RFC3383]. A.1. LDAP Object Identifier Registrations It is requested that IANA register upon Standards Action an LDAP Object Identifier in identifying the protocol elements defined in this technical specification. The following registration template is provided: Subject: Request for LDAP OID Registration Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Specification: RFCXXXX Author/Change Controller: IESG Comments: Seven delegations will be made under the assigned OID: IANA-ASSIGNED-OID.1 ChangeSequenceNumber: LDAP Syntax IANA-ASSIGNED-OID.2 UTF8String: LDAP Syntax IANA-ASSIGNED-OID.3 changeSequenceNumberMatch: LDAP Matching Rule IANA-ASSIGNED-OID.4 utf8CodePointMatch: LDAP Matching Rule IANA-ASSIGNED-OID.5 changeSequenceNumberOrderingMatch: LDAP Matching Rule IANA-ASSIGNED-OID.6 utf8CodePointOrderingMatch: LDAP Matching Rule IANA-ASSIGNED-OID.7 entryCSN: LDAP Attribute Type A.2. LDAP Descriptor Registrations It is requested that IANA register upon Standards Action the LDAP descriptors described in this document. The following registration templates are given: Sermersheim & Chu Expires August 5, 2005 [Page 11] Internet-Draft LDAP CSN February 2005 Subject: Request for LDAP Descriptor Registration Descriptor (short name): ChangeSequenceNumber Object Identifier: IANA-ASSIGNED-OID.1 Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Usage: other Specification: RFCXXXX Author/Change Controller: IESG Comments: LDAP Syntax Subject: Request for LDAP Descriptor Registration Descriptor (short name): UTF8String Object Identifier: IANA-ASSIGNED-OID.2 Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Usage: other Specification: RFCXXXX Author/Change Controller: IESG Comments: LDAP Syntax Subject: Request for LDAP Descriptor Registration Descriptor (short name): changeSequenceNumberMatch Object Identifier: IANA-ASSIGNED-OID.3 Person & email address to contact for further information: Sermersheim & Chu Expires August 5, 2005 [Page 12] Internet-Draft LDAP CSN February 2005 Jim Sermersheim jimse@novell.com Usage: other Specification: RFCXXXX Author/Change Controller: IESG Comments: LDAP Matching Rule Subject: Request for LDAP Descriptor Registration Descriptor (short name): utf8CodePointMatch Object Identifier: IANA-ASSIGNED-OID.4 Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Usage: other Specification: RFCXXXX Author/Change Controller: IESG Comments: LDAP Matching Rule Subject: Request for LDAP Descriptor Registration Descriptor (short name): changeSequenceNumberOrderingMatch Object Identifier: IANA-ASSIGNED-OID.5 Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Usage: other Specification: RFCXXXX Sermersheim & Chu Expires August 5, 2005 [Page 13] Internet-Draft LDAP CSN February 2005 Author/Change Controller: IESG Comments: LDAP Matching Rule Subject: Request for LDAP Descriptor Registration Descriptor (short name): utf8CodePointOrderingMatch Object Identifier: IANA-ASSIGNED-OID.6 Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Usage: other Specification: RFCXXXX Author/Change Controller: IESG Comments: LDAP Matching Rule Subject: Request for LDAP Descriptor Registration Descriptor (short name): entryCSN Object Identifier: IANA-ASSIGNED-OID.7 Person & email address to contact for further information: Jim Sermersheim jimse@novell.com Usage: Attribute Type Specification: RFCXXXX Author/Change Controller: IESG Comments: LDAP Attribute Type Sermersheim & Chu Expires August 5, 2005 [Page 14] Internet-Draft LDAP CSN February 2005 Authors' Addresses Jim Sermersheim Novell, Inc 1800 South Novell Place Provo, Utah 84606 USA Phone: +1 801 861-3088 Email: jimse@novell.com Howard Chu Symas Corp. 18740 Oxnard Street, Suite 313A Tarzana, California 91356 USA Phone: +1 818 757-7087 Email: hyc@symas.com Sermersheim & Chu Expires August 5, 2005 [Page 15] Internet-Draft LDAP CSN February 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@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 & Chu Expires August 5, 2005 [Page 16] PK 0�c\�Z�(� (� C doc/alt-openldap11-devel/drafts/draft-haripriya-dynamicgroup-xx.txtnu �[��� 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@novell.com Jaimon Jose (editor) Novell, Inc. 49/1 & 49/3 Garvebhavi Palya, 7th Mile, Hosur Road Bangalore, Karnataka 560068 India Email: jjaimon@novell.com Jim Sermersheim Novell, Inc. 1800 South Novell Place Provo, Utah 84606 US Email: jimse@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@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] PK 1�c\g��R5F 5F @ doc/alt-openldap11-devel/drafts/draft-legg-ldap-acm-admin-xx.txtnu �[��� INTERNET-DRAFT S. Legg draft-legg-ldap-acm-admin-03.txt Adacel Technologies Intended Category: Standards Track June 16, 2004 Lightweight Directory Access Protocol (LDAP): Access Control Administration Copyright (C) The Internet Society (2004). All Rights Reserved. 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 document is unlimited. Comments should be sent to the author. This Internet-Draft expires on 16 December 2004. Abstract This document adapts the X.500 directory administrative model, as it pertains to access control administration, for use by the Lightweight Directory Access Protocol. The administrative model partitions the Directory Information Tree for various aspects of directory data administration, e.g., subschema, access control and collective attributes. This document provides the particular definitions that support access control administration, but does not define a particular access control scheme. Legg Expires 16 December 2004 [Page 1] INTERNET-DRAFT Access Control Administration June 16, 2004 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . 2 3. Access Control Administrative Areas. . . . . . . . . . . . . . 3 4. Access Control Scheme Indication . . . . . . . . . . . . . . . 3 5. Access Control Information . . . . . . . . . . . . . . . . . . 4 6. Access Control Subentries. . . . . . . . . . . . . . . . . . . 4 7. Applicable Access Control Information. . . . . . . . . . . . . 5 8. Security Considerations. . . . . . . . . . . . . . . . . . . . 5 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 6 10. IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 6 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 6 11.1. Normative References. . . . . . . . . . . . . . . . . . 6 11.2. Informative References. . . . . . . . . . . . . . . . . 7 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 7 Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 7 1. Introduction This document adapts the X.500 directory administrative model [X501], as it pertains to access control administration, for use by the Lightweight Directory Access Protocol (LDAP) [RFC3377]. The administrative model [ADMIN] partitions the Directory Information Tree (DIT) for various aspects of directory data administration, e.g., subschema, access control and collective attributes. The parts of the administrative model that apply to every aspect of directory data administration are described in [ADMIN]. This document describes the administrative framework for access control. An access control scheme describes the means by which access to directory information, and potentially to access rights themselves, may be controlled. This document describes the framework for employing access control schemes but does not define a particular access control scheme. Two access control schemes known as Basic Access Control and Simplified Access Control are defined by [BAC]. Other access control schemes may be defined by other documents. This document is derived from, and duplicates substantial portions of, Sections 4 and 8 of X.501 [X501]. 2. Conventions 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 [RFC2119]. Legg Expires 16 December 2004 [Page 2] INTERNET-DRAFT Access Control Administration June 16, 2004 Schema definitions are provided using LDAP description formats [RFC2252]. Note that the LDAP descriptions have been rendered with additional white-space and line breaks for the sake of readability. 3. Access Control Administrative Areas The specific administrative area [ADMIN] for access control is termed an Access Control Specific Area (ACSA). The root of the ACSA is termed an Access Control Specific Point (ACSP) and is represented in the DIT by an administrative entry [ADMIN] which includes accessControlSpecificArea as a value of its administrativeRole operational attribute [SUBENTRY]. An ACSA MAY be partitioned into subtrees termed inner administrative areas [ADMIN]. Each such inner area is termed an Access Control Inner Area (ACIA). The root of the ACIA is termed an Access Control Inner Point (ACIP) and is represented in the DIT by an administrative entry which includes accessControlInnerArea as a value of its administrativeRole operational attribute. An administrative entry can never be both an ACSP and an ACIP. The corresponding values can therefore never be present simultaneously in the administrativeRole attribute. Each entry necessarily falls within one and only one ACSA. Each such entry may also fall within one or more ACIAs nested inside the ACSA containing the entry. An ACSP or ACIP has zero, one or more subentries that contain Access Control Information (ACI). 4. Access Control Scheme Indication The access control scheme (e.g., Basic Access Control [BAC]) in force in an ACSA is indicated by the accessControlScheme operational attribute contained in the administrative entry for the relevant ACSP. The LDAP description [RFC2252] for the accessControlScheme operational attribute is: ( 2.5.24.1 NAME 'accessControlScheme' EQUALITY objectIdentifierMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 SINGLE-VALUE USAGE directoryOperation ) An access control scheme conforming to the access control framework described in this document MUST define a distinct OBJECT IDENTIFIER Legg Expires 16 December 2004 [Page 3] INTERNET-DRAFT Access Control Administration June 16, 2004 value to identify it through the accessControlScheme attribute. Object Identifier Descriptors for access control scheme identifiers may be registered with IANA [BCP64]. Only administrative entries for ACSPs are permitted to contain an accessControlScheme attribute. If the accessControlScheme attribute is absent from a given ACSP, the access control scheme in force in the corresponding ACSA, and its effect on operations, results and errors, is implementation defined. Any entry or subentry in an ACSA is permitted to contain ACI if and only if such ACI is permitted by, and consistent with, the access control scheme identified by the value of the accessControlScheme attribute of the ACSP. 5. Access Control Information There are three categories of Access Control Information (ACI): entry, subentry and prescriptive. Entry ACI applies to only the entry or subentry in which it appears, and the contents thereof. Subject to the access control scheme, any entry or subentry MAY hold entry ACI. Subentry ACI applies to only the subentries of the administrative entry in which it appears. Subject to the access control scheme, any administrative entry, for any aspect of administration, MAY hold subentry ACI. Prescriptive ACI applies to all the entries within a subtree or subtree refinement of an administrative area (either an ACSA or an ACIA), as defined by the subtreeSpecification attribute of the subentry in which it appears. Prescriptive ACI is only permitted in subentries of an ACSP or ACIP. Prescriptive ACI in the subentries of a particular administrative point never applies to the same or any other subentry of that administrative point, but does apply to the subentries of subordinate administrative points, where those subentries are within the subtree or subtree refinement. 6. Access Control Subentries Each subentry which contains prescriptive ACI MUST have accessControlSubentry as a value of its objectClass attribute. Such a subentry is called an access control subentry. The LDAP description [RFC2252] for the accessControlSubentry auxiliary object class is: Legg Expires 16 December 2004 [Page 4] INTERNET-DRAFT Access Control Administration June 16, 2004 ( 2.5.17.1 NAME 'accessControlSubentry' AUXILIARY ) A subentry of this object class MUST contain at least one prescriptive ACI attribute of a type consistent with the value of the accessControlScheme attribute of the corresponding ACSP. The subtree or subtree refinement for an access control subentry is termed a Directory Access Control Domain (DACD). A DACD can contain zero entries, and can encompass entries that have not yet been added to the DIT, but does not extend beyond the scope of the ACSA or ACIA with which it is associated. Since a subtreeSpecification may define a subtree refinement, DACDs within a given ACSA may arbitrarily overlap. 7. Applicable Access Control Information Although particular items of ACI may specify attributes or values as the protected items, ACI is logically associated with entries. The ACI that is considered in access control decisions regarding an entry includes: (1) Entry ACI from that particular entry. (2) Prescriptive ACI from access control subentries whose DACDs contain the entry. Each of these access control subentries is necessarily either a subordinate of the ACSP for the ACSA containing the entry, or a subordinate of the ACIP for an ACIA that contains the entry. The ACI that is considered in access control decisions regarding a subentry includes: (1) Entry ACI from that particular subentry. (2) Prescriptive ACI from access control subentries whose DACDs contain the subentry, excluding those belonging to the same administrative point as the subentry for which the decision is being made. (3) Subentry ACI from the administrative point associated with the subentry. 8. Security Considerations This document defines a framework for employing an access control scheme, i.e., the means by which access to directory information and Legg Expires 16 December 2004 [Page 5] INTERNET-DRAFT Access Control Administration June 16, 2004 potentially to access rights themselves may be controlled, but does not itself define any particular access control scheme. The degree of protection provided, and any security risks, are determined by the provisions of the access control schemes (defined elsewhere) making use of this framework. Security considerations that apply to directory administration in general [ADMIN] also apply to access control administration. 9. Acknowledgements This document is derived from, and duplicates substantial portions of, Sections 4 and 8 of X.501 [X501]. 10. IANA Considerations The Internet Assigned Numbers Authority (IANA) is requested to update the LDAP descriptors registry [BCP64] as indicated by the following templates: Subject: Request for LDAP Descriptor Registration Descriptor (short name): accessControlScheme Object Identifier: 2.5.24.1 Person & email address to contact for further information: Steven Legg <steven.legg@adacel.com.au> Usage: attribute type Specification: RFC XXXX Author/Change Controller: IESG Subject: Request for LDAP Descriptor Registration Descriptor (short name): accessControlSubentry Object Identifier: 2.5.17.1 Person & email address to contact for further information: Steven Legg <steven.legg@adacel.com.au> Usage: object class Specification: RFC XXXX Author/Change Controller: IESG 11. References 11.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2252] Wahl, M., Coulbeck, A., Howes, T. and S. Kille, "Lightweight Directory Access Protocol (v3): Attribute Syntax Definitions", RFC 2252, December 1997. Legg Expires 16 December 2004 [Page 6] INTERNET-DRAFT Access Control Administration June 16, 2004 [RFC3377] Hodges, J. and R. Morgan, "Lightweight Directory Access Protocol (v3): Technical Specification", RFC 3377, September 2002. [BCP64] Zeilenga, K., "Internet Assigned Numbers Authority (IANA Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 3383, September 2002. [SUBENTRY] Zeilenga, K. and S. Legg, "Subentries in the Lightweight Directory Access Protocol (LDAP)", RFC 3672, December 2003. [ADMIN] Legg, S., "Lightweight Directory Access Protocol (LDAP): Directory Administrative Model", draft-legg-ldap-admin-xx.txt, a work in progress, June 2004. 11.2. Informative References [COLLECT] Zeilenga, K., "Collective Attributes in the Lightweight Directory Access Protocol (LDAP)", RFC 3671, December 2003. [BAC] Legg, S., "Lightweight Directory Access Protocol (LDAP): Basic and Simplified Access Control", draft-legg-ldap-acm-bac-xx.txt, a work in progress, June 2004. [X501] ITU-T Recommendation X.501 (02/01) | ISO/IEC 9594-2:2001, Information technology - Open Systems Interconnection - The Directory: Models Author's Address Steven Legg Adacel Technologies Ltd. 250 Bay Street Brighton, Victoria 3186 AUSTRALIA Phone: +61 3 8530 7710 Fax: +61 3 8530 7888 EMail: steven.legg@adacel.com.au Full Copyright Statement Copyright (C) The Internet Society (2004). This document is subject to the rights, licenses and restrictions contained in BCP 78, and Legg Expires 16 December 2004 [Page 7] INTERNET-DRAFT Access Control Administration June 16, 2004 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@ietf.org. Changes in Draft 01 Section 4 has been extracted to become a separate Internet draft, draft-legg-ldap-admin-00.txt. The subsections of Section 5 have become the new Sections 3 to 7. Editorial changes have been made to accommodate this split. No technical changes have been introduced. Changes in Draft 02 RFC 3377 replaces RFC 2251 as the reference for LDAP. An IANA Considerations section has been added. Changes in Draft 03 Legg Expires 16 December 2004 [Page 8] INTERNET-DRAFT Access Control Administration June 16, 2004 The document has been reformatted in line with current practice. Legg Expires 16 December 2004 [Page 9] PK 1�c\� h�� � & doc/alt-openldap11-devel/drafts/READMEnu �[��� 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$ PK 1�c\�"��yw yw L doc/alt-openldap11-devel/drafts/draft-lachman-laser-ldap-mail-routing-xx.txtnu �[��� INTERNET-DRAFT H. Lachman Intended Category: Informational Netscape Communications Corp. Filename: draft-lachman-laser-ldap-mail-routing-02.txt G. Shapiro Sendmail, Inc. Expires: July 2001 January 2001 LDAP Schema for Intranet Mail Routing 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 draft is being discussed on the Laser mailing list at <laser@sunroof.eng.sun.com>. Subscription requests can be sent to <laser-request@sunroof.eng.sun.com> (send an email message with the word "subscribe" in the body). More information on the mailing list along with an archive of back messages is available at <http://playground.sun.com/laser/>. [[Section X will be removed before the document is submitted to the IESG.]] Copyright Notice Copyright (C) The Internet Society (1999-2001). All Rights Reserved. Abstract This document defines an LDAP [1] object class called 'inetLocalMailRecipient' and associated attributes that provide a way to designate an LDAP entry as one that represents a local (intra- organizational) email recipient, to specify the recipient's email address(es), and to provide routing information pertinent to the recipient. This is intended to support SMTP [2] message transfer agents in routing RFC 822-based email [3] within a private enterprise only, and is not to be used in the process of routing email across the public Internet. Lachman, et. al. [Page 1] INTERNET-DRAFT LDAP Schema for Intranet Mail Routing January 2001 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 [9]. 2. Background and Motivation LDAP-based directory services are currently being used in many organizations as a repository of information about users and other network entities (such as groups of users, network resources, etc.). In cases where LDAP entries are used to represent entities that are email recipients (e.g., a mail user or a mailing list), the LDAP entries provide a convenient place to store per-recipient data, such as a recipient's email address. In many organizations, an email recipient may have an email address (e.g., "joe@example.com") that does not specify the host that receives mail for that recipient (e.g., "host42.example.com"). A message transfer agent (MTA) responsible for routing mail within the organization needs some way to determine the appropriate target host for such a recipient. A common solution is the sendmail "aliases" database which may contain a record that provides the necessary per- recipient routing information (e.g., "joe: joe@host42"). A drawback of this solution is that if the organization hosts more than one DNS domain (e.g., "example.com" and "example.org", with "joe" in each domain being different recipients), a more explicit mapping is desirable. The schema defined in this document provides a way to represent such mappings in LDAP and X.500 [4] directory services. An LDAP entry that represents an email recipient could conceivably contain a variety of attributes related to email, such as disk quota and delivery preferences. We consider here only attributes that specify address information and routing information; these attributes may be useful to multiple MTAs within the organization since one or more MTAs may be responsible for intra-organizational routing. The various MTAs in an organization may have been developed by different implementors, so a common schema is desirable for such attributes. 3. Overview Email systems deployed in large organizations must scale to support large numbers of users and email servers. This means using email addresses that are independent of particular mailbox server hosts; thus an "email routing server" that receives mail sent to the host-independent (or high-level or top-level or domain ...) address and routes it to the appropriate mailbox server. For scalability there should be many routing servers providing identical service. A set of such servers and the mailbox servers they route to form an "email domain". Lachman, et. al. [Page 2] INTERNET-DRAFT LDAP Schema for Intranet Mail Routing January 2001 This specification describes the basic function of the routing server, including data elements to support per-recipient routing info, and use of LDAP-based directory service to support multiple servers sharing the routing info data. The routing function is distinguished from other MTA-transfer operations. The 'inetLocalMailRecipient' object class and associated attributes identify an LDAP entry as representing an SMTP mail recipient (in the sense "recipient" is used in [2]). A recipient may be a mail user, a mailing list, an auto-responder of some kind (e.g., a mailing list subscription program), a network device such as a printer or fax machine, or other recipient type. Address attributes and routing attributes are provided to aid SMTP MTAs in routing mail within an organization to the appropriate target MTA for each recipient. Once on the target MTA, a message is handled according to local conventions (which may be specified using other auxiliary object classes and is outside the scope of this document). For example, the message may be delivered to a user mailbox, or to a program or network device, and/or forwarded to another recipient. Or, the target MTA may be a gateway to a non-SMTP mail routing and delivery system including non-SMTP MTAs. Note that, in this discussion, "target MTA" refers to the final SMTP destination of messages for the recipient in question, as we are considering routing of mail only among the SMTP MTAs within an organization. Any domain that uses LDAP-based routing MUST support LDAP-based routing at all MTAs responsible for the domain. All other MTAs that do not support LDAP-based routing MUST forward mail for that domain to MTAs that do, using MX records or other local conventions. The target MTA checks to see if the destination domain of the recipient address is one that it is responsible for and that uses LDAP-based routing. If so, the MTA checks for matching e-mail addresses in LDAP by looking up the envelope recipient address in LDAP using the object class described in section 4.1 and the attribute discussed in section 4.2. If an unambiguous match is returned, the MTA interprets the routing attributes as described in section 4.3. Routing of mail between different organizations across the public Internet is outside the scope of this document, as the mechanism for this is already standardized [5,6]. An 'inetLocalMailRecipient' entry represents a mail recipient that is local to the organization in question, not recipients in other organizations. This means that the domain names that appear within the 'mailLocalAddress' and 'mailHost' attribute values in an 'inetLocalMailRecipient' entry must be DNS domain names that are local to the organization. (e.g., within the organization's Intranet or by deemed local by other local conventions outside the scope of this standard). An MTA should not look for or use 'inetLocalMailRecipient' entries or attributes if that MTA is not authoritative for the right-hand side of the recipient address in question. Lachman, et. al. [Page 3] INTERNET-DRAFT LDAP Schema for Intranet Mail Routing January 2001 LDAP entries that are not 'inetLocalMailRecipient' entries should be ignored by MTAs for the purpose of routing. An example is a conference room whose LDAP entry contains contact information (e.g., email address and telephone number) for the person who books reservations for the room; the conference room is not a mail recipient, and can safely be ignored by MTAs doing route determination based on recipient address. 4. Object Class and Attribute Definitions The 'inetLocalMailRecipient' object class and associated attributes are defined (using syntaxes given in [7]) as follows. 4.1 The inetLocalMailRecipient Object Class ( 2.16.840.1.113730.3.2.[[TBD]] NAME 'inetLocalMailRecipient' SUP top AUXILIARY MAY ( mailLocalAddress $ mailHost $ mailRoutingAddress ) ) The 'inetLocalMailRecipient' object class signifies that the entry represents an entity within the organization that can receive SMTP mail, such as a mail user or a mailing list. In any case of an entry containing the 'inetLocalMailRecipient' object class, attributes defined in this document MUST be interpreted as specified in this document. 4.2 Address Attribute ( 2.16.840.1.113730.3.1.13 NAME 'mailLocalAddress' DESC 'RFC 822 email address of this recipient' EQUALITY caseIgnoreIA5Match SYNTAX '1.3.6.1.4.1.1466.115.121.1.26{256}' ) The 'mailLocalAddress' attribute is used to specify email addresses, for the recipient; for example, "nickname@example.com". The address conforms to the syntax of an 'addr-spec' as defined in [3]. The 'mailLocalAddress' attribute MUST contain all local addresses that represent each recipient of the target MTA. Commonly, the value of the 'mail' attribute should also be among the addresses listed in the 'mailLocalAddress' attribute if it is expected to be used for LDAP mail routing. Lachman, et. al. [Page 4] INTERNET-DRAFT LDAP Schema for Intranet Mail Routing January 2001 When determining the disposition of a given message, MTAs using LDAP (directly or indirectly) to route mail MUST search for an entry with object class 'inetLocalMailRecipient' and a 'mailLocalAddress' attribute matching the message's recipient address. If exactly one matching entry is found, MTAs MUST regard the message as being addressed to the entity that is represented by the directory entry. If multiple entries are found, the results of the lookup MUST be treated as unsuccessful and should be handled by the MTA in some locally-appropriate way, such as returning a DSN [10] to the sender. If there is no match found by the above, MTAs SHOULD have the capability of searching for the recipient domain against the 'mailLocalAddress' attribute using the "wildcard domain" address "@<full-local-domain>" , e.g., "@example.org". In other words, if mail arrives for "someone@example.org", and there is no recipient with that address specified as 'mailLocalAddress', then the recipient with the wildcard domain address should receive the mail. MTAs MAY do other searches but only after the above are done. In short, the address attribute 'mailLocalAddress' may be used by an LDAP entry to answer the question "what is/are this account's email address(es)?" 4.3 Routing Attributes ( 2.16.840.1.113730.3.1.18 NAME 'mailHost' DESC 'fully-qualified hostname of the MTA that is the final SMTP destination of messages to this recipient' EQUALITY caseIgnoreIA5Match SYNTAX '1.3.6.1.4.1.1466.115.121.1.26{256}' SINGLE-VALUE ) The 'mailHost' attribute indicates which SMTP MTA considers the recipient's mail to be locally handleable. This information can be used for routing, in that an intermediary MTA may take it to be the destination for messages addressed to this recipient. Normal mail routing requirements (i.e., use of MX records [5]) apply to the specified hostname unless overridden by local conventions. In other words, the mail should be sent to the specified host without changing the recipient address. The hostname is specified as a fully-qualified DNS hostname with no trailing dot (e.g., "host42.example.com"). If the 'inetLocalMailRecipient' object class is present, the 'mailHost' attribute for each entry MAY contain a value. If it does, that value MUST be the fully qualified name of the server containing the host MTA for this person. If 'mailHost' is present then it MUST be taken as the host for this user, and all mail to this user MUST be routed to this machine. Lachman, et. al. [Page 5] INTERNET-DRAFT LDAP Schema for Intranet Mail Routing January 2001 ( 2.16.840.1.113730.3.1.47 NAME 'mailRoutingAddress' DESC 'RFC 822 address to use when routing messages to the SMTP MTA of this recipient' EQUALITY caseIgnoreIA5Match SYNTAX '1.3.6.1.4.1.1466.115.121.1.26{256}' SINGLE-VALUE ) The 'mailRoutingAddress' attribute indicates a routing address for the recipient. The address MUST conform to the syntax of an 'addr-spec' in [3]. An intermediary MTA MUST use this information to route the message to the MTA that handles mail for this recipient, e.g., the envelope address MUST be rewritten to this value. This is useful in cases where, for a given recipient, the target MTA prefers a particular address to appear as the recipient address in the SMTP envelope. 'mailRoutingAddress' MAY be used as an alternative to 'mailHost', and is intended to have the same effect as 'mailHost' except that 'mailRoutingAddress' is an address for rewriting the envelope. With 'mailHost', the envelope address either is not rewritten, or is rewritten according to implementation-specific rules and/or configuration. If both 'mailHost' and 'mailRoutingAddress' are present, MTAs MUST interpret it to mean that messages are to be routed to the host indicated by 'mailHost', while rewriting the envelope as per 'mailRoutingAddress'. In theory, there could be peculiar cases where this is necessary, but this is not normally expected. Absence of both 'mailHost' and 'mailRoutingAddress' MAY be considered an error, unless "location-independent" recipient types are supported by the various MTAs within the organization. This would allow any MTA in the organization to handle the processing of mail for, say, a mailing list. This presumes that the various MTAs all recognize the recipient type in question, suggesting a need to standardize recipient types that could be "location-independent". In short, routing attributes may be used by an LDAP entry to answer the question "how should MTAs route mail to this account?" (analogous to using the sendmail "aliases" database for per-user routing within an organization). This is in contrast with "forwarding"; forwarding and delivery options may be specified in an LDAP entry to answer the question "what happens to mail once it arrives at this account?", which may include forwarding to some other account within or outside the organization (analogous to using the sendmail ".forward" file). Such options are outside the scope of the 'inetLocalMailRecipient' schema definition. Lachman, et. al. [Page 6] INTERNET-DRAFT LDAP Schema for Intranet Mail Routing January 2001 The following possibilities exist as a result of an LDAP lookup on an address: mailHost is mailRoutingAddress is Results in ----------- --------------------- ---------- set to a set mail routed to "local" host mailRoutingAddress set to a not set delivered to "local" host original address set to a set relay to mailHost remote host using mailRoutingAddress set to a not set original address remote host relayed to mailHost not set set mail routed to mailRoutingAddress not set not set error or "location-independent" The term "local" host above means the host specified is one that the local (target) MTA considers to be a local delivery. The local MTA MAY rewrite the original address when mailRoutingAddress is not set if local conventions warrant the change. 5. Examples The following examples illustrate possible uses of the 'inetLocalMailRecipient' object class. Note that the examples include attributes defined outside of this document to demonstrate a complete record. The existence of these attributes in the example is not an indication that these attributes are used for LDAP-based mail routing (e.g., the 'mail' is not used for mail routing). Here is an example of an LDAP entry representing a mail user: dn: uid=joe,o=Example Corp,c=US objectClass: top objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson objectClass: inetLocalMailRecipient objectClass: nsMessagingServerUser cn: Joe User sn: User uid: joe userPassword: {crypt}y2KxtbzMYnApU mail: joe@example.com Lachman, et. al. [Page 7] INTERNET-DRAFT LDAP Schema for Intranet Mail Routing January 2001 mailLocalAddress: joe@example.com mailLocalAddress: joe@another.example.com mailHost: nsmail1.example.com mailDeliveryOption: mailbox mailQuota: 1000000 mailForwardingAddress: mary@example.com Joe User is a user of a hypothetical mail system called NS Messaging. Let's say mail arrives on an MTA called "mx.example.com", addressed to "joe@example.com". That MTA searches the directory for a mail recipient with that address, using an LDAP search filter [8] such as: (&(objectClass=inetLocalMailRecipient) (mailLocalAddress=joe@example.com)) It finds Joe's LDAP entry, and routes the message to the target MTA "nsmail1.example.com", while not rewriting the SMTP envelope recipient address. Then, "nsmail1.example.com" receives the message, searches for and finds the recipient in the directory, ascertains that it is the recipient's target MTA, and handles the message as per other attributes in the recipient's entry and/or the MTA configuration (in this case, the message is delivered to a mailbox, and forwarded to another recipient). Note that this document does not specify the rules an MTA is to use to ascertain whether or not it is the target MTA for a given recipient (it could check the recipient's 'mailHost' value against its own hostname, or check the recipient's 'mailRoutingAddress', or check the MTA configuration, or some combination of these). Here is another example of an LDAP entry representing a mail user: dn: uid=john,o=Example Corp,c=US objectClass: top objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson objectClass: inetLocalMailRecipient objectClass: xyzMailUser cn: John Doe sn: Doe uid: john userPassword: {crypt}y2KxtbzMYnApU mail: john@example.com mailLocalAddress: john@example.com mailRoutingAddress: John_Doe@xyz-gw.example.com xyzPostOfficeName: PO_1 xyzClusterNumber: 3 xyzMessageStoreId: 9 Lachman, et. al. [Page 8] INTERNET-DRAFT LDAP Schema for Intranet Mail Routing January 2001 John Doe is a user of a hypothetical mail system called XYZ Mail. Let's say mail arrives on an MTA called "mx.example.com", addressed to "john@example.com". That MTA searches the directory for a mail recipient with that address, and routes the message to "xyz- gw.example.com", rewriting the SMTP envelope recipient address to "John_Doe@xyz-gw.example.com", as per the 'mailRoutingAddress'. On "xyz-gw.example.com", the message is gatewayed into the XYZ Mail system and then dealt with as per other attributes. Here is an example of an LDAP entry representing a mailing list: dn: cn=Scuba Group,o=Example Corp,c=US objectClass: top objectClass: groupOfUniqueNames objectClass: inetLocalMailRecipient objectClass: mailGroup cn: Scuba Group mail: scuba@example.com mailLocalAddress: scuba@example.com mailHost: host42.example.com mgrpRFC822MailMember: joe@example.com mgrpRFC822MailMember: john@example.com The Scuba Group is a mail group (mailing list) that includes two members. A message addressed to "scuba@example.com" is routed to "host42.example.com" where it is then resent to the mailing list members. Here is an example of an LDAP entry representing a forwarding alias: dn: cn=Jane Roe Forwarding Alias,o=Example,c=US objectClass: top objectClass: inetLocalMailRecipient objectClass: mailForwardingAlias mail: janeroe@example.org mailLocalAddress: janeroe@example.org mailHost: mail.example.org mailForwardingAddress: janeroe@elsewhere.example.com cn: Jane Roe Forwarding Alias This entry uses a hypothetical object class 'mailForwardingAlias' that is not specified here, but is used as an example of how an LDAP entry might represent such a recipient type. A message addressed to "janeroe@example.org" is routed to "mail.example.org" where it is then forwarded. In this case, Jane Roe may be a former member of the Example Organization, and they are forwarding her mail to her new address elsewhere. Lachman, et. al. [Page 9] INTERNET-DRAFT LDAP Schema for Intranet Mail Routing January 2001 6. Security Considerations As in all cases where account information is stored in an LDAP-based directory service, network administrators must be careful to ensure that their directory service controls users' access to the entries and attributes stored therein, according to site policy. In particular, mail routing information should not be accessible from outside the organization, since it is intended for use only by MTAs within the organization. 7. Acknowledgments The 'inetLocalMailRecipient' object class is based on an earlier design done by the Netscape Messaging and Directory Server teams, which was implemented and deployed to customers as part of Netscape Messaging Server. Various team members contributed to the design, including Bill Fitler, Bruce Steinback, Prabhat Keni, Mike Macgirvin, John Myers, John Kristian, Tim Howes, Mark Smith, and Leif Hedstrom. Thanks also to Jeff Hodges of Stanford for contributing to the early design discussions, and to the other participants in the IETF LASER BOF, including, from Sun Microsystems, John Beck, Anil Srivastava, and Darryl Huff. 8. References [1] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [2] J. Postel, "Simple Mail Transfer Protocol", STD 10, RFC 821, August 1982. [3] D. Crocker, "Standard for the Format of ARPA Internet Text Messages", STD 11, RFC 822, August 1982. [4] "Information Processing Systems - Open Systems Interconnection - The Directory: Overview of Concepts, Models and Service", ISO/IEC JTC 1/SC21, International Standard 9594-1, 1988. [5] C. Partridge, "Mail routing and the domain system", STD 14, RFC 974, January 1986. [6] R. Braden, "Requirements for Internet hosts - application and support", STD 3, RFC 1123, October 1989. [7] M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight X.500 Directory Access Protocol (v3): Attribute Syntax Definitions", RFC 2252, December 1997. [8] T. Howes, "The String Representation of LDAP Search Filters", RFC 2254, December 1997. Lachman, et. al. [Page 10] INTERNET-DRAFT LDAP Schema for Intranet Mail Routing January 2001 [9] S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [10] K. Moore, "SMTP Service Extension for Delivery Status Notifications", RCP 1891, January 1996. 9. Authors' Addresses Hans Lachman Netscape Communications Corp. 501 East Middlefield Road Mountain View, CA 94043 Phone: (650) 254-1900 EMail: lachman@netscape.com Gregory Neil Shapiro Sendmail, Inc. 6603 Shellmound Street Emeryville, CA 94608-1042 Phone: +1 510-594-5522 Fax: +1 510-594-5411 EMail: gshapiro@sendmail.org X. Change Summary X.1.1 Substantive changes between draft-lachman-laser-ldap-mail-routing-00.txt and draft-lachman-laser-ldap-mail-routing-01.txt (i) Added Gregory Neil Shapiro as another author. (ii) Changed Draft heaer. (iii) Added "Conventions Used in this Document" section. (iv) Replaced RFC mentions with reference numbers. (v) Add new MUST/SHOULD/MAY sections to bring more in line with RFC documents. (vi) Clarify job of MTA in Overview by adding third paragraph. (vii) mailRoutingAddress can be outside of administrative control. (viii) Eliminated use of 'mail' attribute for mail routing. (ix) Changed name of 'mailAlternateAddress' to 'mailLocalAddress'. (x) Remove "routable" from 'mailLocalAddress' description. (xi) Clarify which addresses MUST be in 'mailLocalAddress'. (xii) Allow for multiple responses if they all have the same routing attribute values. (xiii) Clarify use of MX records on routing attributes. (xiv) Add a table to clarify use of 'mailHost' and 'mailRoutingAddress'. (xv) Remove document weakening statements from section 5. (xvi) Only use reserved domains (example.com, example.org) in examples. (xvii) Clean up references (xviii) Added section X to list the changes between draft versions. Lachman, et. al. [Page 11] INTERNET-DRAFT LDAP Schema for Intranet Mail Routing January 2001 X.1.2 Substantive changes between draft-lachman-laser-ldap-mail-routing-01.txt and draft-lachman-laser-ldap-mail-routing-02.txt (i) Changed Intended Category from Standard Track to Informational. (ii) Removed references to mailGroup document which has expired. (iii) Add additional Overview text from RL 'Bob' Morgan. (iv) If a domain uses LDAP-based routing, require all MTAs in that domain to either use LDAP for routing or forward mail to an MTA which uses LDAP for routing. (v) Add more text regarding "local" domain. (vi) Tighten rules for better interoperability. Multiple, matching results is now treated as an unsuccessful lookup. (vii) Tighten rules for better interoperability. Change the action for a lookup which returns both a 'mailHost' and 'mailRoutingAddress' to a MUST (from a MAY). (viii) Point out that examples contain attributes which are not part of this spec and should not be used for mail routing (specifically, 'mail'). (ix) Clean up text. (x) NOTE: Still need vendor-neutral OIDs for the objectClass and attributes. 10. Full Copyright Statement Copyright (C) The Internet Society (1999-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 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. Lachman, et. al. [Page 12] PK 1�c\n,ʥ5S 5S > doc/alt-openldap11-devel/drafts/draft-chu-ldap-xordered-xx.txtnu �[��� Network Working Group H. Chu Internet-Draft Symas Corp. Intended status: Informational May 2006 Expires: November 2, 2006 Ordered Entries and Values in LDAP draft-chu-ldap-xordered-00.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 November 2, 2006. Copyright Notice Copyright (C) The Internet Society (2006). Chu Expires November 2, 2006 [Page 1] Internet-Draft LDAP Ordering Extension May 2006 Abstract As LDAP is used more extensively for managing various kinds of data, one often encounters a need to preserve both the ordering and the content of data, despite the inherently unordered structure of entries and attribute values in the directory. This document describes a scheme to attach ordering information to attributes in a directory so that the ordering may be preserved and propagated to other LDAP applications. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . 3 2. Conventions . . . . . . . . . . . . . . . . . . . . . 4 3. Ordering Extension . . . . . . . . . . . . . . . . . . 5 3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . 5 3.2. Encoding . . . . . . . . . . . . . . . . . . . . . . . 5 3.3. Ordering Properties . . . . . . . . . . . . . . . . . 6 4. Examples . . . . . . . . . . . . . . . . . . . . . . . 8 4.1. Sample Schema . . . . . . . . . . . . . . . . . . . . 8 4.2. Ordered Values . . . . . . . . . . . . . . . . . . . . 8 4.3. Ordered Siblings . . . . . . . . . . . . . . . . . . . 10 5. Security Considerations . . . . . . . . . . . . . . . 13 6. Normative References . . . . . . . . . . . . . . . . . 14 Appendix A. IANA Considerations . . . . . . . . . . . . . . . . . 15 Author's Address . . . . . . . . . . . . . . . . . . . 16 Intellectual Property and Copyright Statements . . . . 17 Chu Expires November 2, 2006 [Page 2] Internet-Draft LDAP Ordering Extension May 2006 1. Introduction Information in LDAP directories is usually handled by applications in the form of ordered lists, which tends to encourage application developers to assume they are maintained as such, i.e., it is assumed that information stored in a particular order will always be retrieved and presented in that same order. The fact that directory attributes actually store sets of values, which are inherently unordered, often causes grief to users migrating their data into LDAP. Similar concerns arise over the order in which entries themselves are stored and retrieved from the directory. This document describes a schema extension that may be used in LDAP attribute definitions to store ordering information along with the attribute values, so that the ordering can be recovered when retrieved by an LDAP client. The extension also provides automated management of this ordering information to ease manipulation of the ordered values. Chu Expires November 2, 2006 [Page 3] Internet-Draft LDAP Ordering Extension May 2006 2. Conventions Imperative keywords defined in [RFC2119] are used in this document, and carry the meanings described there. Chu Expires November 2, 2006 [Page 4] Internet-Draft LDAP Ordering Extension May 2006 3. Ordering Extension 3.1. Overview The "X-ORDERED" schema extension is added to an AttributeTypeDescription to signify the use of this ordering mechanism. The extension has two variants, selected by either the 'VALUES' or 'SIBLINGS' qdstrings. In general this extension is only compatible with AttributeTypes that have a string-oriented syntax. The "X-ORDERED 'VALUES'" extension is used with multi-valued attributes to maintain the order of multiple values of a given attribute. For example, this feature is useful for storing data such as access control rules, which must be evaluated in a specific order. If the access control information is stored in a multi-valued attribute without a means of preserving the the order of the rules, the access control rules cannot be evaluated properly. As the use of LDAP to store security policy and access control information becomes more prevalent, the necessity of this feature continues to grow. The "X-ORDERED 'SIBLINGS'" extension is used with single-valued attributes to maintain the order of all the onelevel children of a parent entry. That is, ordering will be maintained for all the child entries whose RDNs are all of the same AttributeType. The motivation for this feature is much the same as for the 'VALUES' feature. Sometimes the information with the ordering dependency is too complex or highly structured to be conveniently stored in values of a multi- valued attribute. For example, one could store a prioritized list of servers as a set of separate entries, each entry containing separate attributes for a URL, a set of authentication credentials, and various other parameters. Using the 'SIBLINGS' feature with the attribute in the entries' RDNs would ensure that when obtaining the list of these entries, the list is returned in the intended order. 3.2. Encoding Ordering information is encoded by prepending a value's ordinal index to each value, enclosed in braces. The following BNF specifies the encoding. It uses elements defined in [RFC2252]. d = "0" / "1" / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9" numericstring = 1*d ordering-prefix = "{" numericstring "}" value = <any sequence of octets> Chu Expires November 2, 2006 [Page 5] Internet-Draft LDAP Ordering Extension May 2006 ordered-value = ordering-prefix value The ordinals are zero-based and increment by one for each value. Note that when storing ordered-values into the directory, the ordering-prefix can usually be omitted as it will be generated automatically. But if the original value already begins with a sequence of characters in the form of an ordering-prefix, then an ordering-prefix must always be provided with that value, otherwise the value will be processed and stored incorrectly. Using this extension on an attribute requires that ordering-prefix is a legal value of the LDAP syntax of that attribute. 3.3. Ordering Properties Since the ordering-prefix is stored with the attribute values, it will be propagated to any clients or servers that access the data. Servers implementing this scheme SHOULD sort the values according to their ordering-prefix before returning them in search results. The presence of the ordering extension alters the matching rules that apply to the attribute: When presented with an AssertionValue that does not have an ordering-prefix, the ordering-prefix in the AttributeValue is ignored. When presented with an AssertionValue that consists solely of an ordering-prefix, only the ordering-prefix of the AttributeValue is compared; the remainder of the value is ignored. When presented with an AssertionValue containing both the ordering-prefix and a value, both components are compared to determine a match. A side effect of these properties is that even attributes that normally would have no equality matching rule can be matched by an ordering-prefix. The ordering-prefix may also be used in Modification requests to specify which values to delete, and in which position values should be added. When processing deletions and insertions, all of the ordinals are recounted after each individual modification. If a value being added does not have an ordering-prefix, it is simply appended to the list and the appropriate ordering-prefix is Chu Expires November 2, 2006 [Page 6] Internet-Draft LDAP Ordering Extension May 2006 automatically generated. Likewise if an ordering-prefix is provided that is greater than or equal to the number of existing values. See the examples in the next section. Chu Expires November 2, 2006 [Page 7] Internet-Draft LDAP Ordering Extension May 2006 4. Examples 4.1. Sample Schema This schema is used for all of the examples: ( EXAMPLE_AT.1 NAME 'olcDatabase' EQUALITY caseIgnoreMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE X-ORDERED 'SIBLINGS' ) ( EXAMPLE_AT.2 NAME 'olcSuffix' EQUALITY distinguishedNameMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 X-ORDERED 'VALUES' ) ( EXAMPLE_OC.1 NAME 'olcDatabaseConfig' SUP top STRUCTURAL MAY ( olcDatabase $ olcSuffix ) ) 4.2. Ordered Values Given this entry: dn: olcDatabase={1}bdb,cn=config olcDatabase: {1}bdb objectClass: olcDatabaseConfig olcSuffix: {0}dc=example,dc=com olcSuffix: {1}o=example.com olcSuffix: {2}o=The Example Company olcSuffix: {3}o=example,c=us We can perform these Modify operations: 1. dn: olcDatabase={1}bdb,cn=config changetype: modify delete: olcSuffix olcSuffix: {0} - This operation deletes the first olcSuffix, regardless of its value. All other values are bumped up one position. The olcSuffix attribute will end up containing: olcSuffix: {0}o=example.com olcSuffix: {1}o=The Example Company olcSuffix: {2}o=example,c=us 2. Starting from the original entry, we could issue this change instead: Chu Expires November 2, 2006 [Page 8] Internet-Draft LDAP Ordering Extension May 2006 delete: olcSuffix olcSuffix: o=example.com - This operation deletes the olcSuffix that matches the value, regardless of its ordering-prefix. The olcSuffix attribute will contain: olcSuffix: {0}dc=example,dc=com olcSuffix: {1}o=The Example Company olcSuffix: {2}o=example,c=us 3. Again, starting from the original entry, we could issue this change: delete: olcSuffix olcSuffix: {2}o=The Example Company - Here both the ordering-prefix and the value must match, otherwise the Modify would fail with noSuchAttribute. In this case the olcSuffix attribute results in: olcSuffix: {0}dc=example,dc=com olcSuffix: {1}o=example.com olcSuffix: {2}o=example,c=us 4. Adding a new value without an ordering-prefix simply appends: add: olcSuffix olcSuffix: o=example.org - The resulting attribute would be: olcSuffix: {0}dc=example,dc=com olcSuffix: {1}o=example.com olcSuffix: {2}o=The Example Company olcSuffix: {3}o=example,c=us olcSuffix: {4}o=example.org 5. Adding a new value with an ordering-prefix inserts into the specified position: add: olcSuffix olcSuffix: {0}o=example.org - The resulting attribute would be: olcSuffix: {0}o=example.org olcSuffix: {1}dc=example,dc=com olcSuffix: {2}o=example.com olcSuffix: {3}o=The Example Company olcSuffix: {4}o=example,c=us 6. Modifying multiple values in one operation: add: olcSuffix olcSuffix: {0}ou=Dis,o=example.com Chu Expires November 2, 2006 [Page 9] Internet-Draft LDAP Ordering Extension May 2006 olcSuffix: {0}ou=Dat,o=example,com - delete: olcSuffix: olcSuffix: {2} olcSuffix: {1} - The resulting attribute would be: olcSuffix: {0}ou=Dat,o=example,com olcSuffix: {1}dc=example,dc=com olcSuffix: {2}o=example.com olcSuffix: {3}o=The Example Company olcSuffix: {4}o=example,c=us 7. If the Adds and Deletes in the previous example were done in the opposite order: delete: olcSuffix: olcSuffix: {2} olcSuffix: {1} - add: olcSuffix olcSuffix: {0}ou=Dis,o=example.com olcSuffix: {0}ou=Dat,o=example,com - The result would be: olcSuffix: {0}ou=Dat,o=example,com olcSuffix: {1}ou=Dis,o=example.com olcSuffix: {2}o=example.org olcSuffix: {3}o=The Example Company olcSuffix: {4}o=example,c=us Note that matching against an ordering-prefix can also be done in Compare operations and Search filters. E.g., the filter "(olcSuffix={4})" would match all entries with at least 5 olcSuffix values. 4.3. Ordered Siblings The rules for Ordered Siblings are basically the same as for Ordered Values, except instead of working primarily with the Modify request, the operations of interest here are Add, Delete, and ModRDN. Given these entries: dn: olcDatabase={0}config,cn=config olcDatabase: {0}config objectClass: olcDatabaseConfig olcSuffix: {0}cn=config Chu Expires November 2, 2006 [Page 10] Internet-Draft LDAP Ordering Extension May 2006 dn: olcDatabase={1}bdb,cn=config olcDatabase: {1}bdb objectClass: olcDatabaseConfig olcSuffix: {0}dc=example,dc=com We can perform these operations: 1. Add a new entry with no ordering-prefix: dn: olcDatabase=hdb,cn=config changetype: add olcDatabase: hdb objectClass: olcDatabaseConfig olcSuffix: {0}dc=example,dc=org The resulting entry will be: dn: olcDatabase={2}hdb,cn=config olcDatabase: {2}hdb objectClass: olcDatabaseConfig olcSuffix: {0}dc=example,dc=org 2. Continuing on with these three entries, we can add another entry with a specific ordering-prefix: dn: olcDatabase={1}ldif,cn=config changetype: add olcDatabase: {1}ldif objectClass: olcDatabaseConfig olcSuffix: {0}o=example.com This would give us four entries, whose DNs are: dn: olcDatabase={0}config,cn=config dn: olcDatabase={1}ldif,cn=config dn: olcDatabase={2}bdb,cn=config dn: olcDatabase={3}hdb,cn=config 3. Issuing a ModRDN request will cause multiple entries to be renamed: dn: olcDatabase={1}ldif,cn=config changetype: modrdn newrdn: olcDatabase={99}ldif deleteoldrdn: 1 The resulting entries would be named: dn: olcDatabase={0}config,cn=config dn: olcDatabase={1}bdb,cn=config Chu Expires November 2, 2006 [Page 11] Internet-Draft LDAP Ordering Extension May 2006 dn: olcDatabase={2}hdb,cn=config dn: olcDatabase={3}ldif,cn=config 4. As may be expected, a Delete request will also rename the remaining entries: dn: olcDatabase={1}bdb,cn=config changetype: delete The remaining entries would be named: dn: olcDatabase={0}config,cn=config dn: olcDatabase={1}hdb,cn=config dn: olcDatabase={2}ldif,cn=config Chu Expires November 2, 2006 [Page 12] Internet-Draft LDAP Ordering Extension May 2006 5. Security Considerations General LDAP security considerations [RFC3377] apply. Chu Expires November 2, 2006 [Page 13] Internet-Draft LDAP Ordering Extension May 2006 6. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2252] Wahl, M., Coulbeck, A., Howes, T., 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. [RFC3383] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", RFC 3383, September 2002. [X680] International Telecommunications Union, "Abstract Syntax Notation One (ASN.1): Specification of basic notation", ITU-T Recommendation X.680, July 2002. Chu Expires November 2, 2006 [Page 14] Internet-Draft LDAP Ordering Extension May 2006 Appendix A. IANA Considerations In accordance with [RFC3383] (what needs to be done here?) . We probably need an OID for advertising in supportedFeatures. Chu Expires November 2, 2006 [Page 15] Internet-Draft LDAP Ordering Extension May 2006 Author's Address Howard Chu Symas Corp. 18740 Oxnard Street, Suite 313A Tarzana, California 91356 USA Phone: +1 818 757-7087 Email: hyc@symas.com Chu Expires November 2, 2006 [Page 16] Internet-Draft LDAP Ordering Extension May 2006 Full Copyright Statement Copyright (C) The Internet Society (2006). 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@ietf.org. Acknowledgment Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Chu Expires November 2, 2006 [Page 17] PK 1�c\r��JE< E< @ doc/alt-openldap11-devel/drafts/draft-masarati-ldap-deref-xx.txtnu �[��� Network Working Group P. Masarati Internet-Draft Politecnico di Milano Intended status: Standards Track H. Chu Expires: May 23, 2009 Symas Corp. November 19, 2008 LDAP Dereference Control draft-masarati-ldap-deref-00.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 May 23, 2009. Masarati & Chu Expires May 23, 2009 [Page 1] Internet-Draft LDAP Deref November 2008 Abstract This document describes the Dereference Control for LDAP. This control is intended to provide a concise means to collect extra information related to cross-links present in entries returned as part of search responses. Table of Contents 1. Background and Intended Use . . . . . . . . . . . . . . . . . 3 2. The LDAP Dereference Control . . . . . . . . . . . . . . . . . 4 2.1. Control Semantics . . . . . . . . . . . . . . . . . . . . 4 2.2. Control Request . . . . . . . . . . . . . . . . . . . . . 5 2.3. Control Response . . . . . . . . . . . . . . . . . . . . . 5 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 4. Implementation Notes . . . . . . . . . . . . . . . . . . . . . 7 5. Security Considerations . . . . . . . . . . . . . . . . . . . 8 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 6.1. Object Identifier Registration . . . . . . . . . . . . . . 9 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 10 8. Normative References . . . . . . . . . . . . . . . . . . . . . 11 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12 Intellectual Property and Copyright Statements . . . . . . . . . . 13 Masarati & Chu Expires May 23, 2009 [Page 2] Internet-Draft LDAP Deref November 2008 1. Background and Intended Use Cross-links between entries are often used to describe relationships between entries. To exploit the uniqueness of entries naming, these links are usually represented by the distinguished name (DN) of the linked entries. In many cases, DUAs need to collect information about linked entries. This requires to explicitly dereference each linked entry in order to collect the desired attributes, resulting in the need to perform a specific sequence of search operations, using the links as search base, with a SearchRequest.scope of baseObject [RFC4511]. This document describes a LDAP Control [RFC4511] that allows a DUA to request the DSA to return specific attributes of linked entries along with the link, under the assumption that this operation can be performed by the DSA in a more efficient manner than the DUA would itself by performing the complete sequence of required search operations. 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 [RFC2119]. Masarati & Chu Expires May 23, 2009 [Page 3] Internet-Draft LDAP Deref November 2008 2. The LDAP Dereference Control 2.1. Control Semantics This control allows specifying a dereference attribute and a set of attributes to be dereferenced, as illustrated in Section 2.2. The dereference attribute's syntax MUST be 1.3.6.1.4.1.1466.115.121.1.12 (DN) [RFC4517]. Each value of the dereference attribute in a SearchResultEntry SHOULD result in dereferencing the corresponding entry, collecting the values of the attributes to be dereferenced, and returning them as part of the control value in the SearchResultEntry response, in the format detailed in Section 2.3. The control value may contain dereference attribute values without any dereferenced attribute values, as detailed in Section 2.3. The control semantics does not specify whether this is a consequence of a dangling link or of the application of access restrictions on the values of the attributes to be dereferenced. Attribute description hierarchy [RFC4512] SHALL NOT be exploited when collecting the values of the attributes to be dereferenced. On the contrary, all of the attribute descriptions in an attribute hierarchy SHOULD be treated as distinct and unrelated descriptions. This control is only appropriate for the search operation [RFC4511]. The semantics of the criticality field are specified in [RFC4511]. In detail, the criticality of the control determines whether the control will or will not be used, and if it will not be used, whether the operation will continue without returning the control in the response, or fail, returning unavailableCriticalExtension. If the control is appropriate for an operation and, for any reason, it cannot be applied in its entirety to a single SearchResultEntry response, it MUST NOT be applied to that specific SearchResultEntry response, without affecting its application to any subsequent SearchResultEntry response. Servers implementing this technical specification SHOULD publish the object identifier deref-oid (IANA assigned; see Section 6) as a value of the 'supportedControl' attribute [RFC4512] in their root DSE. This control is totally unrelated to alias dereferencing [RFC4511]. Masarati & Chu Expires May 23, 2009 [Page 4] Internet-Draft LDAP Deref November 2008 2.2. Control Request The control type is deref-oid (IANA assigned; see Section 6). The specification of the Dereference Control request is: controlValue ::= SEQUENCE OF derefSpec DerefSpec DerefSpec ::= SEQUENCE { derefAttr attributeDescription, ; with DN syntax attributes AttributeList } AttributeList ::= SEQUENCE OF attr AttributeDescription Each derefSpec.derefAttr MUST be unique within controlValue. 2.3. Control Response The control type is deref-oid (IANA assigned; see Section 6). The specification of the Dereference Control response is: controlValue ::= SEQUENCE OF derefRes DerefRes DerefRes ::= SEQUENCE { derefAttr AttributeDescription, derefVal LDAPDN, attrVals [0] PartialAttributeList OPTIONAL } PartialAttributeList ::= SEQUENCE OF partialAttribute PartialAttribute PartialAttribute is defined in [RFC4511]; the definition is reported here for clarity: PartialAttribute ::= SEQUENCE { type AttributeDescription, vals SET OF value AttributeValue } If partialAttribute.vals is empty, the corresponding partialAttribute is omitted. If all partialAttribute.vals in attrVals are empty, that derefRes.attrVals is omitted. Masarati & Chu Expires May 23, 2009 [Page 5] Internet-Draft LDAP Deref November 2008 3. Examples Given these entries: dn: cn=Howard Chu,ou=people,dc=example,dc=org objectClass: inetOrgPerson cn: Howard Chu sn: Chu uid: hyc dn: cn=Pierangelo Masarati,ou=people,dc=example,dc=org objectClass: inetOrgPerson cn: Pierangelo Masarati sn: Masarati uid: ando dn: cn=Test Group,ou=groups,dc=example,dc=org objectClass: groupOfNames cn: Test Group member: cn=Howard Chu,ou=people,dc=example,dc=org member: cn=Pierangelo Masarati,ou=people,dc=example,dc=org A search could be performed with a Dereference request control value specified as { member, uid } and the "cn=Test Group" entry would be returned with the response control value { { member, cn=Howard Chu,ou=people,dc=example,dc=org, { { uid, [hyc] } } }, { member, cn=Pierangelo Masarati,ou=people,dc=example,dc=org, { { uid, [ando] } } } } Masarati & Chu Expires May 23, 2009 [Page 6] Internet-Draft LDAP Deref November 2008 4. Implementation Notes This LDAP extension is currently implemented in OpenLDAP software using the temporary OID 1.3.6.1.4.1.4203.666.5.16 under OpenLDAP's experimental OID arc. Masarati & Chu Expires May 23, 2009 [Page 7] Internet-Draft LDAP Deref November 2008 5. Security Considerations The control result MUST NOT disclose information the client's identity could not have accessed by performing the related search operations. The presence of a derefRes.derefVal in the response control, with no derefRes.attrVals, does not imply neither the existence of nor any access privilege to the corresponding entry. It is merely a consequence of the read access the client's identity has on the corresponding value of the derefRes.derefAttr that would be returned as part of the attributes of a SearchResultEntry response [RFC4511]. Security considerations described in documents listed in [RFC4510] apply. Masarati & Chu Expires May 23, 2009 [Page 8] Internet-Draft LDAP Deref November 2008 6. IANA Considerations 6.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: Pierangelo Masarati <ando@OpenLDAP.org> Specification: (I-D) Author/Change Controller: IESG Comments: Identifies the LDAP Dereference Control request and response Masarati & Chu Expires May 23, 2009 [Page 9] Internet-Draft LDAP Deref November 2008 7. Acknowledgments TBD Masarati & Chu Expires May 23, 2009 [Page 10] Internet-Draft LDAP Deref November 2008 8. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC4510] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006. [RFC4511] Sermersheim, J., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006. [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006. [RFC4517] Legg, S., "Lightweight Directory Access Protocol (LDAP): Syntaxes and Matching Rules", RFC 4517, June 2006. Masarati & Chu Expires May 23, 2009 [Page 11] Internet-Draft LDAP Deref November 2008 Authors' Addresses Pierangelo Masarati Politecnico di Milano Dipartimento di Ingegneria Aerospaziale via La Masa 34 Milano 20156 IT Phone: +39 02 2399 8309 Fax: +39 02 2399 8334 Email: ando@OpenLDAP.org URI: http://www.aero.polimi.it/masarati/ Howard Y. Chu Symas Corporation 18740 Oxnard St., Suite 313A Tarzana, California 91356 USA Phone: +1 818 757-7087 Email: hyc@symas.com URI: http://www.symas.com/ Masarati & Chu Expires May 23, 2009 [Page 12] Internet-Draft LDAP Deref November 2008 Full Copyright Statement Copyright (C) The IETF Trust (2008). 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, THE IETF TRUST 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@ietf.org. Masarati & Chu Expires May 23, 2009 [Page 13] PK KWi\�h�W�" �" doc/pycurl/RELEASE-NOTES.rstnu �[��� Release Notes ============= PycURL 7.45.6 - 2025-03-06 -------------------------- The previous release was accidentally built without CA bundle autodetection in Linux wheels - this restores that behavior (no changes to macOS or Linux). PycURL 7.45.5 - 2025-03-06 -------------------------- This release is mainly to update the wheels to incorporate libcurl 8.12.1 for security fixes, as well as enable some additional libraries in wheel builds. PycURL 7.45.4 - 2024-12-12 -------------------------- This release fixes several minor issues and adds support for several libcurl options. Additionally, it fixes several issues with the wheels on Linux/macOS/Windows. PycURL 7.45.3 - 2024-02-17 -------------------------- This release fixes several minor issues and adds support for several libcurl options. Additionally, we are now building wheels for Linux/macOS/Windows. PycURL 7.45.2 - 2022-12-16 -------------------------- This release fixes several minor issues and adds support for several libcurl options. PycURL 7.45.1 - 2022-03-13 -------------------------- This release fixes build when libcurl < 7.64.1 is used. PycURL 7.45.0 - 2022-03-09 -------------------------- This release adds support for SecureTransport SSL backend (MacOS), adds ability to unset a number of multi options, adds ability to duplicate easy handles and permits pycurl classes to be subclassed. PycURL 7.44.1 - 2021-08-15 -------------------------- This release repairs incorrect Python thread initialization logic which caused operations to hang. PycURL 7.44.0 - 2021-08-08 -------------------------- This release reinstates best effort Python 2 support, adds Python 3.9 and Python 3.10 alpha support and implements support for several libcurl options. Official Windows builds are currently not being produced. PycURL 7.43.0.6 - 2020-09-02 ---------------------------- This release improves SSL backend detection on various systems, adds support for libcurl's multiple SSL backend functionality and adds support for several libcurl options. PycURL 7.43.0.5 - 2020-01-29 ---------------------------- This release fixes a build issue on recent Pythons on CentOS/RHEL distributions. It also brings back Windows binaries. Special thank you to Gisle Vanem for contributing the nghttp2 makefile. PycURL 7.43.0.4 - 2020-01-15 ---------------------------- This release improves compatibility with Python 3.8 and removes support for Python 2 and Python 3.4. It also adds wolfSSL support and thread safety of the multi interface. PycURL 7.43.0.3 - 2019-06-17 ---------------------------- This release primarily fixes an OpenSSL-related installation issue, and repairs the ability to use PycURL with newer libcurls compiled without FTP support. Also, mbedTLS support has been contributed by Josef Schlehofer. PycURL 7.43.0.2 - 2018-06-02 ---------------------------- Highlights of this release: 1. Experimental perform_rs and perform_rb methods have been added to Curl objects. They return response body as a string and a byte string, respectively. The goal of these methods is to improve PycURL's usability for typical use cases, specifically removing the need to set up StringIO/BytesIO objects to store the response body. 2. getinfo_raw and errstr_raw methods have been added to Curl objects to return transfer information as byte strings, permitting applications to retrieve transfer information that is not decodable using Python's default encoding. 3. errstr and "fail or error" exceptions now replace undecodable bytes so as to provide usable strings; use errstr_raw to retrieve original byte strings. 4. There is no longer a need to keep references to Curl objects when they are used in CurlMulti objects - PycURL now maintains such references internally. 5. Official Windows builds now include HTTP/2 and international domain name support. 6. PycURL now officially supports BoringSSL. 7. A number of smaller improvements have been made and bugs fixed. PycURL 7.43.0.1 - 2017-12-07 ---------------------------- This release collects fixes and improvements made over the past two years, notably updating Windows dependencies to address DNS resolution and TLS connection issues. PycURL 7.43.0 - 2016-02-02 -------------------------- Highlights of this release: 1. Binary wheels are now built for Windows systems. 2. setopt_string method added to Curl objects to permit setting string libcurl options that PycURL does not know about. 3. curl module can now be imported on Windows again. 4. OPENSOCKETFUNCTION callback is now invoked with the address as bytes on Python 3 as was documented. 5. Support for many libcurl options and constants was added. PycURL 7.21.5 - 2016-01-05 -------------------------- Highlights of this release: 1. Socket callbacks are now fully implemented (``CURLOPT_OPENSOCKETFUNCTION``, ``CURLOPT_SOCKOPTFUNCTION``, ``CURLOPT_CLOSESOCKETFUNCTION``). Unfortunately this required changing ``OPENSOCKETFUNCTION`` API once again in a backwards-incompatible manner. Support for ``SOCKOPTFUNCTION`` and ``CLOSESOCKETFUNCTION`` was added in this release. ``OPENSOCKETFUNCTION`` now supports Unix sockets. 2. Many other libcurl options and constants have been added to PycURL. 3. When ``pycurl`` module initialization fails, ``ImportError`` is raised instead of a fatal error terminating the process. 4. Usability of official Windows builds has been greatly improved: * Dependencies are linked statically, eliminating possible DLL conflicts. * OpenSSL is used instead of WinSSL. * libcurl is linked against C-Ares and libssh2. PycURL 7.19.5.3 - 2015-11-03 ---------------------------- PycURL 7.19.5.2 release did not include some of the test suite files in its manifest, leading to inability to run the test suite from the sdist tarball. This is now fixed thanks to Kamil Dudka. PycURL 7.19.5.2 - 2015-11-02 ---------------------------- Breaking change: DEBUGFUNCTION now takes bytes rather than (Unicode) string as its argument on Python 3. Breaking change: CURLMOPT_* option constants moved from Easy to Multi class. They remain available in pycurl module. SSL library detection improved again, --libcurl-dll option to setup.py added. Options that required tuples now also accept lists, and vice versa. This release fixes several memory leaks and one use after free issue. Support for several new libcurl options and constants has been added. PycURL 7.19.5.1 - 2015-01-06 ---------------------------- This release primarily fixes build breakage against libcurl 7.19.4 through 7.21.1, such as versions shipped with CentOS. PycURL 7.19.5 - 2014-07-12 -------------------------- PycURL C code has been significantly reorganized. Curl, CurlMulti and CurlShare classes are now properly exported, instead of factory functions for the respective objects. PycURL API has not changed. Documentation has been transitioned to Sphinx and reorganized as well. Both docstrings and standalone documentation are now more informative. Documentation is no longer included in released distributions. It can be generated from source by running `make docs`. Tests are no longer included in released distributions. Instead the documentation and quickstart examples should be consulted for sample code. Official Windows builds now are linked against zlib. PycURL 7.19.3.1 - 2014-02-05 ---------------------------- This release restores PycURL's ability to automatically detect SSL library in use in most circumstances, thanks to Andjelko Horvat. PycURL 7.19.3 - 2014-01-09 -------------------------- This release brings official Python 3 support to PycURL. Several GNU/Linux distributions provided Python 3 packages of PycURL previously; these packages were based on patches that were incomplete and in some places incorrect. Behavior of PycURL 7.19.3 and later may therefore differ from behavior of unofficial Python 3 packages of previous PycURL versions. To summarize the behavior under Python 3, PycURL will accept ``bytes`` where it accepted strings under Python 2, and will also accept Unicode strings containing ASCII codepoints only for convenience. Please refer to `Unicode`_ and `file`_ documentation for further details. In the interests of compatibility, PycURL will also accept Unicode data on Python 2 given the same constraints as under Python 3. While Unicode and file handling rules are expected to be sensible for all use cases, and retain backwards compatibility with previous PycURL versions, please treat behavior of this versions under Python 3 as experimental and subject to change. Another potentially disruptive change in PycURL is the requirement for compile time and runtime SSL backends to match. Please see the readme for how to indicate the SSL backend to setup.py. .. _Unicode: doc/unicode.html .. _file: doc/files.html PK KWi\�W�z�/ �/ doc/pycurl/INSTALL.rstnu �[��� .. _install: PycURL Installation =================== NOTE: You need Python and libcurl installed on your system to use or build pycurl. Some RPM distributions of curl/libcurl do not include everything necessary to build pycurl, in which case you need to install the developer specific RPM which is usually called curl-dev. Distutils --------- Build and install pycurl with the following commands:: (if necessary, become root) tar -zxvf pycurl-$VER.tar.gz cd pycurl-$VER python setup.py install $VER should be substituted with the pycurl version number, e.g. 7.10.5. Note that the installation script assumes that 'curl-config' can be located in your path setting. If curl-config is installed outside your path or you want to force installation to use a particular version of curl-config, use the '--curl-config' command line option to specify the location of curl-config. Example:: python setup.py install --curl-config=/usr/local/bin/curl-config If libcurl is linked dynamically with pycurl, you may have to alter the LD_LIBRARY_PATH environment variable accordingly. This normally applies only if there is more than one version of libcurl installed, e.g. one in /usr/lib and one in /usr/local/lib. SSL ^^^ PycURL requires that the SSL library that it is built against is the same one libcurl, and therefore PycURL, uses at runtime. PycURL's ``setup.py`` uses ``curl-config`` to attempt to figure out which SSL library libcurl was compiled against, however this does not always work. If PycURL is unable to determine the SSL library in use it will print a warning similar to the following:: src/pycurl.c:137:4: warning: #warning "libcurl was compiled with SSL support, but configure could not determine which " "library was used; thus no SSL crypto locking callbacks will be set, which may " "cause random crashes on SSL requests" [-Wcpp] It will then fail at runtime as follows:: ImportError: pycurl: libcurl link-time ssl backend (openssl) is different from compile-time ssl backend (none/other) To fix this, you need to tell ``setup.py`` what SSL backend is used:: python setup.py --with-[openssl|gnutls|nss|mbedtls|wolfssl|sectransp|schannel] install Note: as of PycURL 7.21.5, setup.py accepts ``--with-openssl`` option to indicate that libcurl is built against OpenSSL/LibreSSL/BoringSSL. ``--with-ssl`` is an alias for ``--with-openssl`` and continues to be accepted for backwards compatibility. You can also ask ``setup.py`` to obtain SSL backend information from installed libcurl shared library, as follows: python setup.py --libcurl-dll=libcurl.so An unqualified ``libcurl.so`` would use the system libcurl, or you can specify a full path. easy_install / pip ------------------ :: easy_install pycurl pip install pycurl If you need to specify an alternate curl-config, it can be done via an environment variable:: export PYCURL_CURL_CONFIG=/usr/local/bin/curl-config easy_install pycurl The same applies to the SSL backend, if you need to specify it (see the SSL note above):: export PYCURL_SSL_LIBRARY=[openssl|gnutls|nss|mbedtls|sectransp|schannel] easy_install pycurl pip and cached pycurl package ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If you have already installed pycurl and are trying to reinstall it via pip with different SSL options for example, pip may reinstall the package it has previously compiled instead of recompiling pycurl with newly specified options. More details are given in `this Stack Overflow post`_. To force pip to recompile pycurl, run:: # upgrade pip if necessary pip install --upgrade pip # remove current pycurl pip uninstall pycurl # set PYCURL_SSL_LIBRARY export PYCURL_SSL_LIBRARY=nss # recompile and install pycurl pip install --compile pycurl .. _this Stack Overflow post: http://stackoverflow.com/questions/21487278/ssl-error-installing-pycurl-after-ssl-is-set Windows ------- There are currently no official binary Windows packages. You can build PycURL from source or use third-party binary packages. Building From Source ^^^^^^^^^^^^^^^^^^^^ Building PycURL from source is not for the faint of heart due to the multitude of possible dependencies and each of these dependencies having its own directory structure, configuration style, parameters and quirks. Additionally different dependencies have different settings for MSVCRT usage, and an application must have all of its parts agreeing on a single setting. If you decide to build PycURL from source it is advisable to look through the ``winbuild.py`` script - it is used to build the official binaries and contains a wealth of information for compiling PycURL's dependencies on Windows. If you are compiling PycURL from source it is recommended to compile all of its dependencies from source as well. Using precompiled libraries may lead to multiple MSVCRT versions mixed in the resulting PycURL binary, which will not be good. If PycURL is to be linked statically against its dependencies, OpenSSL must be patched to link to the DLL version of MSVCRT. There is a patch for this in ``winbuild`` directory of PycURL source. For a minimum build you will just need libcurl source. Follow its Windows build instructions to build either a static or a DLL version of the library, then configure PycURL as follows to use it:: python setup.py --curl-dir=c:\dev\curl-7.33.0\builds\libcurl-vc-x86-release-dll-ipv6-sspi-spnego-winssl --use-libcurl-dll Note that ``--curl-dir`` must point not to libcurl source but rather to headers and compiled libraries. If libcurl and Python are not linked against the same exact C runtime (version number, static/dll, single-threaded/multi-threaded) you must use ``--avoid-stdio`` option (see below). Additional Windows setup.py options: - ``--use-libcurl-dll``: build against libcurl DLL, if not given PycURL will be built against libcurl statically. - ``--libcurl-lib-name=libcurl_imp.lib``: specify a different name for libcurl import library. The default is ``libcurl.lib`` which is appropriate for static linking and is sometimes the correct choice for dynamic linking as well. The other possibility for dynamic linking is ``libcurl_imp.lib``. - ``--with-openssl``: use OpenSSL/LibreSSL/BoringSSL crypto locks when libcurl was built against these SSL backends. - ``--with-ssl``: legacy alias for ``--with-openssl``. - ``--openssl-lib-name=""``: specify a different name for OpenSSL import library containing CRYPTO_num_locks. For OpenSSL 1.1.0+ this should be set to an empty string as given here. - ``--avoid-stdio``: on Windows, a process and each library it is using may be linked to its own version of the C runtime (MSVCRT). FILE pointers from one C runtime may not be passed to another C runtime. This option prevents direct passing of FILE pointers from Python to libcurl, thus permitting Python and libcurl to be linked against different C runtimes. This option may carry a performance penalty when Python file objects are given directly to PycURL in CURLOPT_READDATA, CURLOPT_WRITEDATA or CURLOPT_WRITEHEADER options. This option applies only on Python 2; on Python 3, file objects no longer expose C library FILE pointers and the C runtime issue does not exist. On Python 3, this option is recognized but does nothing. You can also give ``--avoid-stdio`` option in PYCURL_SETUP_OPTIONS environment variable as follows:: PYCURL_SETUP_OPTIONS=--avoid-stdio pip install pycurl A good ``setup.py`` target to use is ``bdist_wininst`` which produces an executable installer that you can run to install PycURL. You may find the following mailing list posts helpful: - https://curl.haxx.se/mail/curlpython-2009-11/0010.html - https://curl.haxx.se/mail/curlpython-2013-11/0002.html winbuild.py ^^^^^^^^^^^ This script is used to build official PycURL Windows packages. You can use it to build a full complement of packages with your own options or modify it to build a single package you need. Prerequisites: - `Git for Windows`_. - Appropriate `Python versions`_ installed. - MS Visual C++ 9/2008 for Python <= 3.2, MS Visual C++ 10/2010 for Python 3.3 or 3.4, MS Visual C++ 14/2015 for Python 3.5 through 3.8. Express versions of Visual Studio work fine for this, although getting 64 bit compilers to wok in some Express versions involves jumping through several hoops. - NASM if building libcurl against OpenSSL. - ActivePerl if building libcurl against OpenSSL. The perl shipping with Git for Windows handles forward and backslashes in paths in a way that is incompatible with OpenSSL's build scripts. .. _Git for Windows: https://git-for-windows.github.io/ .. _Python versions: http://python.org/download/ ``winbuild.py`` assumes all programs are installed in their default locations, if this is not the case edit it as needed. ``winbuild.py`` itself can be run with any Python it supports. Using PycURL With Custom Python Builds ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ As of version 7.21.5, the official binary packages of PycURL are linked statically against all of its dependencies except MSVCRT. This means that as long as your custom Python build uses the same version of MSVC as the corresponding official Python build as well as the same MSVCRT linking setting (/MD et. al.), an official PycURL package should work. If your Python build uses different MSVCRT settings or a different MSVC version from the official Python builds, you will need to compile PycURL from source. If the C runtime library (MSVCRT.DLL) versions used by PycURL and Python do not match, you will receive a message like the following one when trying to import ``pycurl`` module:: ImportError: DLL load failed: The specified procedure could not be found. To identify which MSVCRT version your Python uses use the `application profiling feature`_ of `Dependency Walker`_ and look for `msvcrt.dll variants`_ being loaded. You may find `the entire thread starting here`_ helpful. .. _application profiling feature: https://curl.haxx.se/mail/curlpython-2014-05/0007.html .. _Dependency Walker: http://www.dependencywalker.com/ .. _msvcrt.dll variants: https://curl.haxx.se/mail/curlpython-2014-05/0010.html .. _the entire thread starting here: https://curl.haxx.se/mail/curlpython-2014-05/0000.html Git Checkout ------------ In order to build PycURL from a Git checkout, some files need to be generated. On Unix systems it is easiest to build PycURL with ``make``:: make To specify which curl or SSL backend to compile against, use the same environment variables as easy_install/pip, namely ``PYCURL_CURL_CONFIG`` and ``PYCURL_SSL_LIBRARY``. To generate generated files only you may run:: make gen This might be handy if you are on Windows. Remember to run ``make gen`` whenever you change sources. To generate documentation, run:: make docs Generating documentation requires `Sphinx`_ to be installed. .. _Sphinx: http://sphinx-doc.org/ A Note Regarding SSL Backends ----------------------------- libcurl's functionality varies depending on which SSL backend it is compiled against. For example, users have `reported`_ `problems`_ with GnuTLS backend. As of this writing, generally speaking, OpenSSL backend has the most functionality as well as the best compatibility with other software. If you experience SSL issues, especially if you are not using OpenSSL backend, you can try rebuilding libcurl and PycURL against another SSL backend. .. _reported: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=515200 .. _problems: https://bugs.launchpad.net/ubuntu/+source/pycurl/+bug/1111673 SSL Certificate Bundle ---------------------- libcurl, and PycURL, by default verify validity of HTTPS servers' SSL certificates. Doing so requires a CA certificate bundle, which libcurl and most SSL libraries do not provide. Here_ is a good resource on how to build your own certificate bundle. certifie.com also has a `prebuilt certificate bundle`_. To use the certificate bundle, use ``CAINFO`` or ``CAPATH`` PycURL options. .. _Here: http://certifie.com/ca-bundle/ .. _prebuilt certificate bundle: http://certifie.com/ca-bundle/ca-bundle.crt.txt PK KWi\1-��p� p� doc/pycurl/ChangeLognu �[��� Version 7.45.6 [requires libcurl-7.19.0 or better] - 2025-03-06 --------------------------------------------------------------- * Re-enable building Linux wheels with CA bundle autodetection Version 7.45.5 [requires libcurl-7.19.0 or better] - 2025-03-06 --------------------------------------------------------------- * Enable GSS-API and brotli support in wheels (patch by Scott Talbert). * Add support for calling getinfo with CURLOPT_*_T arguments (patch by Scott Talbert) * Change wheels to build using shared libraries (vice static libraries) (patch by Scott Talbert) * Build wheels with curl 8.12.1 (mainly for security fixes) Version 7.45.4 [requires libcurl-7.19.0 or better] - 2024-12-12 --------------------------------------------------------------- * Add support for CURLOPT_HAPROXY_CLIENT_IP (patch by Scott Talbert). * Port tests from bottle to flask (patch by Miro Hrončok). * Add constant for CURL_HTTP_VERSION_3ONLY (patch by Pavel Horáček). * Add EFFECTIVE_METHOD info option (patch by Pavel Horáček). * Don't use `-flat_namespace` on macOS (patch by Michael Cho). * Add some missing GIL checks to callback functions (patch by Scott Talbert). * Fix assorted bugs in pycurl tests, including a segfault (patch by Scott Talbert). All tests should now pass on Linux and macOS. * Fix minor bug in examples/multi-socket_action-select.py (patch by Oleg Broytman). * Build all wheels using the latest version of libcurl and its dependencies (patch by Scott Talbert). All wheels should now have openssl, HTTP2, and SSH support. * Implement Certificate Authority path autodetection when building Linux wheels (patch by Scott Talbert). Version 7.45.3 [requires libcurl-7.19.0 or better] - 2024-02-17 --------------------------------------------------------------- * Add CURLOPT_REQUEST_TARGET option (patch by Marcel Brouwers). * Add missing 2nd parameters to METH_NOARGS functions (patch by Scott Talbert). * Add CURLOPT_AWS_SIGV4 option (patch by Scott Talbert). * Add consistent names for newer Curl version constants (patch by Scott Talbert). * Only run HTTP version 3 option constant test if curl supported (patch by Scott Talbert). * Expose COMPILE_SSL_LIB in Python and use for test filtering (patch by Scott Talbert). * Filter tests based on *compile* libcurl version not runtime version (patch by Scott Talbert). * Use print function in callbacks documentation (patch by Scott Talbert). * Add missing shebang to tests/ext/test-suite.sh (patch by Scott Talbert). * Officially declare support for Python 3.12 (patch by Scott Talbert). * Fix curl_multi_info_read flow that loses messages (patch by Dom Sekotill). * Support using environment variables for setup on Windows (patch by Scott Talbert). * Add support for Schannel SSL backend (patch by Scott Talbert) * Skip HTTP2 tests based on a curl support check (patch by Scott Talbert). * Fix fake-curl tests so they work when run out of tree (patch by Scott Talbert). * xfail test_easy_pause_unpause unconditionally (patch by Scott Talbert). * Provide generic error strings in pycurl.error objects (patch by Scott Talbert). * Change URLs to new curl mailing list (patch by Michael C). * Add missing HTTPS proxy options (patch by Jean Hominal). * Add support for setting CURLOPT_SSLCERT_BLOB (patch by Vesa Jääskeläinen). * Add support for setting rest of CURLOPTTYPE_BLOB fields (patch by Vesa Jääskeläinen). * Build wheels on Linux/macOS/Windows (patch by Scott Talbert). Version 7.45.2 [requires libcurl-7.19.0 or better] - 2022-12-16 --------------------------------------------------------------- * Python 3.9 compatibility for Py_TRASHCAN_SAFE_BEGIN (patch by Scott Talbert). * Add support for CURL_HTTP_VERSION_3 (patch by Scott Talbert). * Add CURLOPT_TLS13_CIPHERS and CURLOPT_PROXY_TLS13_CIPHERS options (patch by Scott Talbert). * Added HTTP09_ALLOWED option (patch by Scott Talbert). * Removed use of distutils (patch by Scott Talbert). Version 7.45.1 [requires libcurl-7.19.0 or better] - 2022-03-13 --------------------------------------------------------------- * Fixed build against libcurl < 7.64.1 (patch by Scott Talbert). Version 7.45.0 [requires libcurl-7.64.1 or better] - 2022-03-09 --------------------------------------------------------------- * Add CURLOPT_MAXLIFETIME_CONN (patch by fsbs). * Easy handle duplication support (patch by fsbs). * Support for unsetting a number of multi options (patch by fsbs). * pycurl classes can now be subclassed (patch by fsbs). * Multi callbacks' thread state management fixed (patch by fsbs). * Add CURL_LOCK_DATA_PSL (patch by fsbs). * Add support for SecureTransport SSL backend (MacOS) (patch by Scott Talbert). Version 7.44.1 [requires libcurl-7.19.0 or better] - 2021-08-15 --------------------------------------------------------------- * Fixed Python thread initialization causing hangs on operations (patch by Scott Talbert). Version 7.44.0 [requires libcurl-7.19.0 or better] - 2021-08-08 --------------------------------------------------------------- * getinfo(CURLINFO_FTP_ENTRY_PATH) now handles NULL return from libcurl, returning None in this case. * Python 3.9 is now officially supported (patch by Bill Collins). * Added CURLOPT_DOH_URL (patch by resokou). * Best effort Python 2 support has been reinstated. * Added missing fields to curl_version_info struct (patch by Hasan). * Added CURLINFO_CONDITION_UNMET (patch by Dima Tisnek). * Exposed MAX_CONCURRENT_STREAMS in CurlMulti (patch by Alexandre Pion). * Compilation fixed against Python 3.10 alpha (patch by Kamil Dudka). Version 7.43.0.6 [requires libcurl-7.19.0 or better] - 2020-09-02 ----------------------------------------------------------------- * Fixed offset parameter usage in seek callback (patch by Scott Talbert). * Added support for libcurl SSL backend detection via `curl-config --ssl-backends` (patch by Scott Talbert). * Added support for libcurl MultiSSL (patch by Bo Anderson). * Added ability to unset CURLOPT_PROXY. * Added support for CURLOPT_UPLOAD_BUFFERSIZE (patch by Artur Sobierak). * Added support for CURLOPT_MAXAGE_CONN (patch by Artur Sobierak). * Added support for sharing connection cache in libcurl (patch by Artur Sobierak). * Added support for CURLOPT_HAPROXYPROTOCOL (patch by Russell McConnachie). * CC and CFLAGS environment variables are now respected when building (patch by Michał Górny). * Fixed OpenSSL detection on CentOS 7 and 8 (patch by Nicolas Pauss). * surrogateescape error handler is used in multi_info_read to handle invalid UTF-8. Version 7.43.0.5 [requires libcurl-7.19.0 or better] - 2020-01-29 ----------------------------------------------------------------- * Fixed build with recent Pythons on RHEL/CentOS. Version 7.43.0.4 [requires libcurl-7.19.0 or better] - 2020-01-15 ----------------------------------------------------------------- * Minimum supported Python 3 version is now 3.5. * Python 2 is no longer officially supported. * Improved thread safety of multi code. * Added Python 3.8 support (patch by Michael Treanor). * Fixed link order when linking statically against OpenSSL (patch by Ashley Whetter). * Fixed Darwin detection. * Added support for wolfSSL (patch by Eneas U de Queiroz). * Added PROXY_SSL_VERIFYHOST (patch by Amir Rossert). Version 7.43.0.3 [requires libcurl-7.19.0 or better] - 2019-06-17 ----------------------------------------------------------------- * Fixed use with libcurl 7.65+ when FTP support is disabled. * Added support for mbedTLS (patch by Josef Schlehofer). * Fixed string processing on Python 3 (patch by Dmitriy Taychenachev). * Added CURLOPT_TCP_FASTOPEN and CURL_HTTP_VERSION_2_PRIOR_KNOWLEDGE (patch by Khavish Anshudass Bhundoo). * Repaired inability to install PycURL when libcurl is using an SSL backend other than the ones PycURL explicitly recognizes and handles (OpenSSL, LibreSSL, BoringSSL, GnuTLS, NSS). The requirement for setup.py to detect an SSL backend if libcurl is configured to use SSL, added in 7.43.0.2, has been changed to a warning to allow this. Version 7.43.0.2 [requires libcurl-7.19.0 or better] - 2018-06-02 ----------------------------------------------------------------- * Official Windows builds now include HTTP 2 support via libnghttp2 and international domain name support via WINIDN. * Added perform_rb and perform_rs methods to Curl objects to return response body as byte string and string, respectively. * Added OPT_COOKIELIST constant for consistency with other option constants. * PycURL is now able to report errors triggered by libcurl via CURLOPT_FAILONERROR mechanism when the error messages are not decodable in Python's default encoding (GitHub issue #259). * Added getinfo_raw method to Curl objects to return byte strings as is from libcurl without attempting to decode them (GitHub issue #493). * When adding a Curl easy object to CurlMulti via add_handle, the easy objects now have their reference counts increased so that the application is no longer required to keep references to them to keep them from being garbage collected (GitHub issue #171). * PycURL easy, multi and share objects can now be weak referenced. * Python 3.2 and 3.3 support officially dropped as those versions are end of lifed. * set_ca_certs now accepts byte strings as it should have been all along. * PycURL now skips automatic SSL backend detection if curl-config indicates that libcurl is not built with SSL support, and will warn if an SSL backend is explicitly specified in this case. * PycURL now requires that SSL backend is determined by setup.py to provide earlier failure compared to the existing warning during compilation and failing during module import on mismatched SSL backends. * Use OpenSSL 1.1 and 1.0 specific APIs for controlling thread locks depending on OpenSSL version (patch by Vitaly Murashev). * Fixed a crash when closesocket callback failed (patch by Gisle Vanem and toddrme2178). * Added CURLOPT_PROXY_SSLCERT, CURLOPT_PROXY_SSLCERTTYPE, CURLOPT_PROXY_SSLKEY, CURLOPT_PROXY_SSLKEYTYPE, CURLOPT_PROXY_SSL_VERIFYPEER (libcurl 7.52.0+, patch by Casey Miller). * Added CURLOPT_PRE_PROXY (libcurl 7.52.0+, patch by ziggy). * Support for Python 2.6 officially dropped. * Added SOCKET_BAD constant and it is now recognized as a valid return value from OPENSOCKET callback. * BoringSSL is now recognized as equivalent to OpenSSL backend (patch by Gisle Vanem). Version 7.43.0.1 [requires libcurl-7.19.0 or better] - 2017-12-07 ----------------------------------------------------------------- * WRITEHEADER/WRITEFUNCTION and WRITEDATA/WRITEFUNCTION can now be set on the same handle. The last call will take precedence over previous calls. Previously some combinations were not allowed. * Fixed a crash when using WRITEDATA with a file-like object followed by WRITEDATA with a real file object (patch by Léo El Amri). * Fixed a theoretical memory leak in module initialization (patch by ideal). * Added support for CURL_SSLVERSION_MAX_* constants (libcurl 7.52.0+, patch by Jozef Melicher). * Added support for CURLSSH_AUTH_AGENT (libcurl 7.28.0+, patch by kxrd). * Added support for CURLOPT_CONNECT_TO (patch by Iain R. Learmonth). * Added support for CURLINFO_HTTP_VERSION (patch by Iain R. Learmonth). * Fixed build against OpenSSL l.1 on Windows. * Added set_ca_certs method to the Easy object to set CA certificates from a string (OpenSSL only, patch by Lipin Dmitriy). * Python 3.6 is now officially supported (patch by Samuel Dion-Girardeau). * Added support for CURLOPT_PROXY_CAPATH (libcurl 7.52.0+, patch by Jan Kryl). * C-Ares updated to 1.12.0 in Windows builds, fixing DNS resolution issues on Windows (patch by Wei C). * Added --openssl-lib-name="" option to support building against OpenSSL 1.1.0 on Windows. * Fixed a possible double free situation in all Curl objects due to a misuse of the trashcan API (patch by Benjamin Peterson). * High level Curl objects can now be reused. * LARGE options fixed under Windows and Python 3 (INFILESIZE, MAX_RECV_SPEED_LARGE, MAX_SEND_SPEED_LARGE, MAXFILESIZE, POSTFILESIZE, RESUME_FROM). * Fixed compilation on Solaris (patch by Yiteng Zhang). * ENCODING option can now be unset (patch by Yves Bastide). Version 7.43.0 [requires libcurl-7.19.0 or better] - 2016-02-02 --------------------------------------------------------------- * Added CURLINFO_RTSP_* constants (libcurl 7.20.0+). * Added CURLOPT_XOAUTH2_BEARER (libcurl 7.33.0+). * Added CURLOPT_SASL_IR (libcurl 7.31.0+). * Added CURLOPT_LOGIN_OPTIONS (libcurl 7.34.0+). * Added CURLOPT_FTP_USE_PRET (libcurl 7.20.0+). * Added setopt_string method to Curl objects to set arbitrary string options. * Switched to Bintray for hosting release distributions. * Added CURLOPT_DEFAULT_PROTOCOL (libcurl 7.45.0+). * Added CURLOPT_TLSAUTH_* options (libcurl 7.21.4+). * Added CURLPROTO_SMB and CURLPROTO_SMBS constants (libcurl 7.40.0+). * Added CURL_SOCKOPT_* constants (libcurl 7.21.5+). * Added CURL_HTTP_VERSION_2_0, CURL_HTTP_VERSION_2 and CURL_HTTP_VERSION_2TLS constants for CURLOPT_HTTP_VERSION (various libcurl versions required for these). * winbuild.py can now build binary wheels on Windows. * Added failed memory allocation handling during SSL lock initialization. * CURLOPT_IOCTLDATA option support has been removed. This option is used internally by PycURL and is not settable by applications. * HTTPHEADER and PROXYHEADER options can now be unset. * Added CURLPIPE_* constants (libcurl 7.43.0+). * Added CURLOPT_PIPEWAIT (libcurl 7.43.0+). * Added CURLOPT_PATH_AS_IS (libcurl 7.42.0+). * Added CURLOPT_PROXYHEADER and CURLOPT_HEADEROPT as well as CURLHEADER_UNIFIED and CURLHEADER_SEPARATE (libcurl 7.37.0+). * Added CURLOPT_EXPECT_100_TIMEOUT_MS (libcurl 7.36.0+). * Added CURLOPT_XFERINFOFUNCTION (libcurl 7.32.0+). * Added CURLM_ADDED_ALREADY error constant (libcurl 7.32.1+). * Added remaining CURLE_* constants through libcurl 7.46.0. * Unbroken `curl' module import on Windows - apparently Windows now has a `signal' Python module but no `SIGPIPE' (patch by Gabi Davar). * Added CURLMOPT_PIPELINING_SITE_BL and CURLMOPT_PIPELINING_SERVER_BL options (libcurl 7.30.0+). * Added CURLOPT_TCP_KEEPALIVE, CURLOPT_TCP_KEEPIDLE and CURLOPT_TCP_KEEPINTVL options (libcurl 7.25.0+). * Added CURLOPT_ACCEPTTIMEOUT_MS (libcurl 7.24.0+). * Added CURLOPT_ACCEPT_ENCODING and CURLOPT_TRANSFER_ENCODING options (libcurl 7.21.6+). * OPENSOCKETFUNCTION callback for AF_UNIX sockets was mistakenly invoked with the address as a `string' rather than `bytes' on Python 3. The callback now receives a `bytes' instance as was documented. Version 7.21.5 [requires libcurl-7.19.0 or better] - 2016-01-05 --------------------------------------------------------------- * --with-openssl and its --win-ssl alias setup.py options are now accepted under Windows in order to use OpenSSL's crypto locks when building against OpenSSL. * --with-openssl added as an alias for --with-ssl option to setup.py. * Official Windows builds are now linked against C-Ares and libssh2. * Official Windows builds are now linked against OpenSSL instead of WinSSL. * Official Windows builds are now statically linked against their dependencies (libcurl and zlib). * Added CURLOPT_USE_SSL and CURLUSESSL_* constants. * Added CURLOPT_APPEND, CURLOPT_COOKIESESSION, CURLOPT_DIRLISTONLY, CURLOPT_KEYPASSWD, CURLOPT_TELNETOPTIONS. * Several CURLE_* and CURLM_* constants added. * Add VERSION_* constants, corresponding to CURL_VERSION_*. * Breaking change: OPENSOCKETFUNCTION callback API now mirrors that of libcurl: 1. The callback now takes two arguments, `purpose' and `address`. Previously the callback took `family', `socktype', `protocol` and `addr' arguments. 2. The second argument to the callback, `address', is a `namedtuple' with `family', `socktype', `protocol' and `addr' fields. 3. `addr' field on `address' for AF_INET6 family addresses is a 4-tuple of (address, port, flow info, scope id) which matches Python's `socket.getaddrinfo' API. It seems that libcurl may mishandle error return from an opensocket callback, as would happen when code written for pre-PycURL 7.21.5 API is run with PycURL 7.21.5 or newer, resulting in the application hanging. * OPENSOCKETFUNCTION callback can now be unset. * Added CURLOPT_CLOSESOCKETFUNCTION (libcurl 7.21.7+). CURLOPT_CLOSESOCKETDATA is used internally by PycURL. * Added CURLOPT_SOCKOPTFUNCTION. CURLOPT_SOCKOPTDATA is used internally by PycURL. * Added CURLOPT_SSH_KEYFUNCTION (libcurl 7.19.6+). CURLOPT_SSH_KEYDATA is used internally by PycURL. * Added CURLOPT_SSL_OPTIONS (libcurl 7.25.0+). * Added CURLOPT_KRBLEVEL. * Added CURLOPT_SSL_FALSESTART (libcurl 7.42.0+). * Added CURLOPT_SSL_ENABLE_NPN (libcurl 7.36.0+). * Added CURLOPT_SSL_ENABLE_ALPN (libcurl 7.36.0+). * Added CURLOPT_UNIX_SOCKET_PATH (libcurl 7.40.0+). * Added CURLOPT_WILDCARDMATCH (libcurl 7.21.0+). * C module initialization changed to raise exceptions on failure rather than trigger a fatal error and abort the Python interpreter. * Added CURLOPT_PINNEDPUBLICKEY (libcurl 7.39.0-7.44.0+ depending on SSL backend and encoding algorithm). * Fixed incorrect detection of libcurl 7.19.5 and 7.19.6 (thanks to bataniya). Version 7.19.5.3 [requires libcurl-7.19.0 or better] - 2015-11-03 ----------------------------------------------------------------- * python and nosetests binaries can now be overridden when running the test suite (patch by Kamil Dudka). * Files needed to run the test suite are distributed in sdist (patch by Kamil Dudka). Version 7.19.5.2 [requires libcurl-7.19.0 or better] - 2015-11-02 ----------------------------------------------------------------- * C sources made 64-bit clean on Windows. * Support for building against Python 3.5 added to winbuild.py. * Fixed build on Windows when using MS SDK 8.1+ or MSVC 14/2015 (patch by Gisle Vanem). * Added automatic SSL library detection on CentOS 6 by loading libcurl shared library in setup.py. This automatic detection is meant to permit installing pycurl seamlessly via `pip install pycurl` on CentOS; as such, it is only employed when no other configuration options or configuration environment variables are given to setup.py (original patch by Francisco Alves). * Added --libcurl-dll option to setup.py to take SSL library information out of libcurl shared library (original patch by Francisco Alves). This option is only usable with Python 2.5 or higher. * --with-ssl, --with-gnutls and --with-nss options to setup.py now result in PycURL explicitly linking against the respective SSL library. Previously setup.py relied on curl-config to supply the needed libraries in this case. * List and tuples are now accepted in all positions of HTTPPOST option values. * Tuples are now accepted for options taking list values (e.g. HTTPHEADER). * Fixed a use after free in HTTPPOST when using FORM_BUFFERPTR with a Unicode string (patch by Clint Clayton). * Fixed a memory leak in HTTPPOST for multiple FORM_BUFFERPTR (patch by Clint Clayton). * CURLMOPT_* option constants were mistakenly defined on Curl instances but not on CurlMulti instances. These option constants are now defined on CurlMulti instances and on pycurl module, but not on Curl instances. * Fixed several memory leaks when setting string options to Unicode values failed. * Fixed a memory leak when using POSTFIELDS with unicode objects on Python 2 (patch by Clint Clayton). * Official support for Python 2.4 and 2.5 dropped. PycURL is no longer tested against these Python versions on Travis. * Added CURLAUTH_NEGOTIATE (libcurl 7.38.0+), CURLAUTH_NTLM_WB (libcurl 7.22.0+), CURLAUTH_ONLY (libcurl 7.21.3+), * Added CURLOPT_SERVICE_NAME (libcurl 7.43.0+). * Added CURLOPT_PROXY_SERVICE_NAME (libcurl 7.43.0+). * Added CURLE_SSL_CRL_BADFILE, CURLE_SSL_INVALIDCERTSTATUS (libcurl 7.41.0+), CURLE_SSL_ISSUER_ERROR and CURLE_SSL_PINNEDPUBKEYNOTMATCH (libcurl 7.39.0+). * Added CURLOPT_SSL_VERIFYSTATUS (libcurl 7.41.0+). * Added CURL_SSLVERSION_TLSv1_0, CURL_SSLVERSION_TLSv1_1 and CURL_SSLVERSION_TLSv1_2 (libcurl 7.34.0+). * The second argument of DEBUGFUNCTION callback is now of type bytes on Python 3. When response body contains non-ASCII data and DEBUGFUNCTION is enabled, this argument would receive non-ASCII data. Which encoding this data is in is unknown by PycURL, and e.g. in the case of HTTP requires parsing response headers. GitHub issue #210, patch by Barry Warsaw with help from Gregory Petukhov. * Fixed build on GCC 4.4.5 (patch by Travis Jensen). * Added CURLOPT_GSSAPI_DELEGATION, CURLGSSAPI_DELEGATION_FLAG, CURLGSSAPI_DELEGATION_NONE and CURLGSSAPI_DELEGATION_POLICY_FLAG (libcurl 7.22.0+, patch by Dmitry Ketov). Version 7.19.5.1 [requires libcurl-7.19.0 or better] - 2015-01-06 ----------------------------------------------------------------- * Added CURLPROXY_SOCKS4A and CURLPROXY_SOCKS5_HOSTNAME. * setup.py now prints PycURL-specific option help when -h is used. * LibreSSL is now supported (patch by JiCiT). * Fixed an oversight that broke PycURL building against libcurl 7.19.4 through 7.21.1. The bug was introduced in PycURL 7.19.5. * Tests are now included in source distributions again, thanks to Kamil Dudka and Johan Bergstroem. * Added CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT (libcurl 7.20.0+) and CURLOPT_MAIL_AUTH (libcurl 7.25.0+). Version 7.19.5 [requires libcurl-7.21.2 or better] - 2014-07-12 --------------------------------------------------------------- * Tests removed from source and binary distributions. * Documentation greatly improved. Quickstart guide added. * pycurl.Curl, pycurl.CurlMulti and pycurl.CurlShare are now classes rather than factory functions. Previously, the classes were "hidden" (they were accessible as e.g. type(pycurl.Curl()), but could not be instantiated, nor could class methods be obtained from the classes. Please see this mailing list post for further information: https://curl.haxx.se/mail/curlpython-2014-06/0004.html * When passing a file-like object to READDATA option, PycURL was mistakenly looking for write method on this object. Now read method is looked up, as would be expected. * Python 3.4 is now officially supported. * Windows packages now build libcurl against zlib. * CherryPy is no longer required for the test suite, ssl module from the Python standard library is used instead. * Fixed a reference leak of SOCKET and TIMER callbacks on CurlMulti instances, thanks to Ben Darnell. * Fixed build against openssl on cygwin, where pycurl needs to link against libcrypto rather than libssl. * Added CURLOPT_SSH_KNOWNHOSTS (libcurl 7.19.6+). * Added CURLE_FTP_ACCEPT_FAILED (libcurl 7.24.0+). * Added CURLE_NOT_BUILT_IN and CURLE_UNKNOWN_OPTION (libcurl 7.21.5+). * Added CURL_SEEKFUNC_OK, CURL_SEEKFUNC_FAIL and CURL_SEEKFUNC_CANTSEEK. All constants require libcurl 7.19.5+; numeric values of CURL_SEEKFUNC_OK and CURL_SEEKFUNC_FAIL were understood earlier but constants only exist as of libcurl 7.19.5. * Added CURLINFO_CONDITION_UNMET (libcurl 7.19.4+). * Added CURLPROXY_HTTP_1_0 (libcurl 7.19.4+). * Added CURLOPT_SOCKS5_GSSAPI_SERVICE and CURLOPT_SOCKS5_GSSAPI_NEC (libcurl 7.19.4+). * Added CURLOPT_TFTP_BLKSIZE (libcurl 7.19.4+). * Added CURLOPT_PROTOCOLS, CURLOPT_REDIR_PROTOCOLS and associated CURLPROTO_* constants, which require libcurl 7.19.4+. * Fixed a reference leak of OPENSOCKET and SEEK callbacks, thanks to Ben Darnell. * C source is now split into several files. * Documentation is now processed by sphinx. Version 7.19.3.1 [requires libcurl-7.19.0 or better] - 2014-02-05 ----------------------------------------------------------------- * Added --avoid-stdio setup.py option to avoid passing FILE pointers from Python to libcurl. Applies to Python 2 only. * Added CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE, CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE, CURLMOPT_MAX_HOST_CONNECTIONS CURLMOPT_MAX_PIPELINE_LENGTH, CURLMOPT_MAX_TOTAL_CONNECTIONS multi options (patch by Jakob Truelsen). * SSL detection logic changed to consult `curl-config --static-libs` even if `curl-config --libs` succeeded. This should achieve pre-7.19.3 behavior with respect to automatic SSL detection (patch by Andjelko Horvat). Version 7.19.3 [requires libcurl-7.19.0 or better] - 2014-01-09 --------------------------------------------------------------- * Added CURLOPT_NOPROXY. * Added CURLINFO_LOCAL_PORT, CURLINFO_PRIMARY_PORT and CURLINFO_LOCAL_IP (patch by Adam Jacob Muller). * When running on Python 2.x, for compatibility with Python 3.x, Unicode strings containing ASCII code points only are now accepted in setopt() calls. * PycURL now requires that compile time SSL backend used by libcurl is the same as the one used at runtime. setup.py supports --with-ssl, --with-gnutls and --with-nss options like libcurl does, to specify which backend libcurl uses. On some systems PycURL can automatically figure out libcurl's backend. If the backend is not one for which PycURL provides crypto locks (i.e., any of the other backends supported by libcurl), no runtime SSL backend check is performed. * Default PycURL user agent string is now built at runtime, and will include the user agent string of libcurl loaded at runtime rather than the one present at compile time. * PycURL will now use WSAduplicateSocket rather than dup on Windows to duplicate sockets obtained from OPENSOCKETFUNCTION. Using dup may have caused crashes, OPENSOCKETFUNCTION should now be usable on Windows. * A new script, winbuild.py, was added to build PycURL on Windows against Python 2.6, 2.7, 3.2 and 3.3. * Added CURL_LOCK_DATA_SSL_SESSION (patch by Tom Pierce). * Added E_OPERATION_TIMEDOUT (patch by Romuald Brunet). * setup.py now handles --help argument and will print PycURL-specific configuration options in addition to distutils help. * Windows build configuration has been redone: PYCURL_USE_LIBCURL_DLL #define is gone, use --use-libcurl-dll argument to setup.py to build against a libcurl DLL. CURL_STATICLIB is now #defined only when --use-libcurl-dll is not given to setup.py, and PycURL is built against libcurl statically. --libcurl-lib-name option can be used to override libcurl import library name. * Added CURLAUTH_DIGEST_IE as pycurl.HTTPAUTH_DIGEST_IE. * Added CURLOPT_POSTREDIR option and CURL_REDIR_POST_301, CURL_REDIR_POST_302, CURL_REDIR_POST_303 and CURL_REDIR_POST_ALL constants. CURL_REDIR_POST_303 requires libcurl 7.26.0 or higher, all others require libcurl 7.19.1 or higher. * As part of Python 3 support, WRITEDATA option now accepts any object with a write method on Python 2 and Python 3. For non-file objects, c.setopt(c.WRITEDATA, buf) is equivalent to c.setopt(c.WRITEFUNCTION, buf.write). * PycURL now supports Python 3.1 through 3.3. Python 3.0 might work but it appears to ship with broken distutils, making virtualenv not function on it. * PycURL multi objects now have the multi constants defined on them. Previously the constants were only available on pycurl module. The new behavior matches that of curl and share objects. * PycURL share objects can now be closed via the close() method. * PycURL will no longer call `curl-config --static-libs` if `curl-config --libs` succeeds and returns output. Systems on which neither `curl-config --libs` nor `curl-config --static-libs` do the right thing should provide a `curl-config` wrapper that is sane. * Added CURLFORM_BUFFER and CURLFORM_BUFFERPTR. * pycurl.version and user agent string now include both PycURL version and libcurl version as separate items. * Added CURLOPT_DNS_SERVERS. * PycURL can now be dynamically linked against libcurl on Windows if PYCURL_USE_LIBCURL_DLL is #defined during compilation. * Breaking change: opensocket callback now takes an additional (address, port) tuple argument. Existing callbacks will need to be modified to accept this new argument. https://github.com/pycurl/pycurl/pull/18 Version 7.19.0.3 [requires libcurl-7.19.0 or better] - 2013-12-24 ----------------------------------------------------------------- * Re-release of 7.19.0.2 with minor changes to build Windows packages due to botched 7.19.0.2 files on PyPi. https://curl.haxx.se/mail/curlpython-2013-12/0021.html Version 7.19.0.2 [requires libcurl-7.19.0 or better] - 2013-10-08 ----------------------------------------------------------------- * Fixed a bug in a commit made in 2008 but not released until 7.19.0.1 which caused CURLOPT_POSTFIELDS to not correctly increment reference count of the object being given as its argument, despite libcurl not copying the data provided by said object. * Added support for libcurl pause/unpause functionality, via curl_easy_pause call and returning READFUNC_PAUSE from read callback function. Version 7.19.0.1 [requires libcurl-7.19.0 or better] - 2013-09-23 ----------------------------------------------------------------- * Test matrix tool added to test against all supported Python and libcurl versions. * Python 2.4 is now the minimum required version. * Source code, bugs and patches are now kept on GitHub. * Added CURLINFO_CERTINFO and CURLOPT_CERTINFO. * Added CURLOPT_RESOLVE. * PycURL can now be used with Python binaries without thread support. * gcrypt is no longer initialized when a newer version of gnutls is used. * Marked NSS as supported. * Fixed relative URL request logic. * Fixed a memory leak in util_curl_init. * Added CURLOPT_USERNAME and CURLOPT_PASSWORD. * Fixed handling of big timeout values. * Added GLOBAL_ACK_EINTR. * setopt(..., None) can be used as unsetopt(). * CURLOPT_RANGE can now be unset. * Write callback can return -1 to signal user abort. * Reorganized tests into an automated test suite. * Added CURLOPT_SEEKFUNCTION and CURLOPT_SEEKDATA. * Cleaned up website. * Fix pycurl.reset() (patch by <johansen at sun.com>). * Fix install routine in setup.py where certain platforms (Solaris, Mac OSX, etc) would search for a static copy of libcurl (dbp). * Fixed build on OpenSolaris 0906 and other platforms on which curl-config does not have a --static-libs option. * No longer keep string options copies in the Curl Python objects, since string options are now managed by libcurl. Version 7.19.0 [requires libcurl-7.19.0 or better] -------------------------------------------------- * Added CURLFILE, ADDRESS_SCOPE and ISSUERCERT options, as well as the APPCONNECT_TIME info. * Added PRIMARY_IP info (patch by Yuhui H <eyecat at gmail.com>). * Added support for curl_easy_reset through a new 'reset' method on curl objects (patch by Nick Pilon <npilon at oreilly.com>). * Added support for OPENSOCKET callbacks. See 'tests/test_opensocket.py' for example usage (patch by Thomas Hunger <teh at camvine.com>). Version 7.18.2 -------------- * Added REDIRECT_URL info and M_MAXCONNECTS option (patch by Yuhui H <eyecat at gmail.com>). * Added socket_action() method to CurlMulti objects. See 'tests/test_multi_socket_select.py' for example usage (patch by Yuhui H <eyecat at gmail.com>). * Added AUTOREFERER option. * Allow resetting some list operations (HTTPHEADER, QUOTE, POSTQUOTE, PREQUOTE) by passing an empty list to setopt (patch by Jim Patterson). Version 7.18.1 -------------- * Added POST301, SSH_HOST_PUBLIC_KEY_MD5, COPYPOSTFIELDS and PROXY_TRANSFER_MODE options. * Check for static libs in setup.py to better detect whether libcurl was linked with OpenSSL or GNUTLS. * PycURL is now dual licensed under the LGPL and a license similar to the cURL license (an MIT/X derivative). Version 7.16.4 -------------- * Allow any callable object as the callback function. This change comes handy when you would like to use objects which are callable but are not functions or methods, for example those objects created by the functions in the functools module (patch by Daniel Pena Arteaga <dpena at ph.tum.de>). * Added NEW_DIRECTORY_PERMS and NEW_FILE_PERMS options. Version 7.16.2.1 ---------------- * Added IOCMD_NOP and IOCMD_RESTARTREAD for ioctl callback handling (patch by Mark Eichin). * Use Py_ssize_t where appropriate for Python 2.5 and 64-bit compatibility. This fixes the problem reported by Aaron Hill, where the exception "pycurl.error: (2, '')" is thrown when calling setopt(pycurl.POSTFIELDS,...) on 64-bit platforms. Version 7.16.2 -------------- * Added options HTTP_TRANSFER_DECODING, HTTP_CONTENT_DECODING, TIMEOUT_MS, CONNECTTIMEOUT_MS from libcurl 7.16.2. * Right-strip URLs read from files in the test scripts to avoid sending requests with '\n' at the end. Version 7.16.1 -------------- * Added constants for all libcurl (error) return codes. They are named the same as the macro constants in curl.h but prefixed with E_ instead of CURLE. Return codes for the multi API are prefixed with M_ instead of CURLM. * Added CURLOPT_FTP_SSL_CCC, CURLOPT_SSH_PUBLIC_KEYFILE, CURLOPT_SSH_PRIVATE_KEYFILE, CURLOPT_SSH_AUTH_TYPES. * Removed CLOSEPOLICY and friends since this option is now deprecated in libcurl. * Set the _use_datetime attribute on the CURLTransport class to unbreak xmlrpc_curl.py on Python 2.5. Version 7.16.0 [no public release] -------------- * Added CURLOPT_SSL_SESSIONID_CACHE. * Removed SOURCE_* options since they are no longer supported by libcurl. Version 7.15.5.1 ---------------- * Added test for basic ftp usage (tests/test_ftp.py). * Fix broken ssl mutex lock function when using GNU TLS (Debian bug #380156, fix by Bastian Kleineidam) Version 7.15.5 -------------- * Added CURLOPT_FTP_ALTERNATIVE_TO_USER, CURLOPT_MAX_SEND_SPEED_LARGE, and CURLOPT_MAX_RECV_SPEED_LARGE. Version 7.15.4.2 ---------------- * Use SSL locking callbacks, fixes random crashes for multithreaded SSL connections (patch by Jayne <corvine at gmail.com>). Version 7.15.4.1 ---------------- * Fixed compilation problem with C compilers not allowing declarations in the middle of code blocks (patch by K.S.Sreeram <sreeram at tachyontech.net>). * Fixed bug in curl_multi_fdset wrapping, max_fd < 0 is not an error (patch by K.S.Sreeram <sreeram at tachyontech.net>). Version 7.15.4 -------------- * Added support for libcurl shares, patch from Victor Lascurain <bittor at eleka.net>. See the file tests/test_share.py for example usage. * Added support for CURLINFO_FTP_ENTRY_PATH. Version 7.15.2 -------------- * Added CURLOPT_CONNECT_ONLY, CURLINFO_LASTSOCKET, CURLOPT_LOCALPORT and CURLOPT_LOCALPORTRANGE. Version 7.15.1 -------------- 2006-01-31 Kjetil Jacobsen <kjetilja> * Fixed memory leak for getinfo calls that return a list as result. Patch by Paul Pacheco. Version 7.15.0 -------------- 2005-10-18 Kjetil Jacobsen <kjetilja> * Added CURLOPT_FTP_SKIP_PASV_IP. Version 7.14.1 -------------- 2005-09-05 Kjetil Jacobsen <kjetilja> * Added CURLOPT_IGNORE_CONTENT_LENGTH, CURLOPT_COOKIELIST as COOKIELIST and CURLINFO_COOKIELIST as INFO_COOKIELIST. Version 7.14.0 -------------- 2005-05-18 Kjetil Jacobsen <kjetilja> * Added missing information returned from the info() method in the high-level interface. * Added the FORM_FILENAME option to the CURLFORM API with HTTPPOST. Version 7.13.2 -------------- 2005-03-30 Kjetil Jacobsen <kjetilja> * Unbreak tests/test_gtk.py and require pygtk >= 2.0. 2005-03-15 Kjetil Jacobsen <kjetilja> * Cleaned up several of the examples. 2005-03-11 Kjetil Jacobsen <kjetilja> * WARNING: multi.select() now requires the previously optional timeout parameter. Updated the tests and examples to reflect this change. If the timeout is not set, select could block infinitely and cause problems for the internal timeout handling in the multi stack. The problem was identified by <unknownsoldier93 at yahoo.com>. Version 7.13.1 -------------- 2005-03-04 Kjetil Jacobsen <kjetilja> * Use METH_NOARGS where appropriate. 2005-03-03 Kjetil Jacobsen <kjetilja> * Added support for CURLFORM API with HTTPPOST: Supports a a tuple with pairs of options and values instead of just supporting string contents. See tests/test_post2.py for example usage. Options are FORM_CONTENTS, FORM_FILE and FORM_CONTENTTYPE, corresponding to the CURLFORM_* options, and values are strings. 2005-02-13 Markus F.X.J. Oberhumer <mfx> * Read callbacks (pycurl.READFUNCTION) can now return pycurl.READFUNC_ABORT to immediately abort the current transfer. * The INFILESIZE, MAXFILESIZE, POSTFIELDSIZE and RESUME_FROM options now automatically use the largefile version to handle files > 2GB. * Added missing pycurl.PORT constant. Version 7.13.0 -------------- 2005-02-10 Kjetil Jacobsen <kjetilja> * Added file_upload.py to examples, shows how to upload a file. * Added CURLOPT_IOCTLFUNCTION/DATA. * Added options from libcurl 7.13.0: FTP_ACCOUNT, SOURCE_URL, SOURCE_QUOTE. * Obsoleted options: SOURCE_HOST, SOURCE_PATH, SOURCE_PORT, PASV_HOST. Version 7.12.3 -------------- 2004-12-22 Markus F.X.J. Oberhumer <mfx> * Added CURLINFO_NUM_CONNECTS and CURLINFO_SSL_ENGINES. * Added some other missing constants. * Updated pycurl.version_info() to return a 12-tuple instead of a 9-tuple. Version 7.12.2 -------------- 2004-10-15 Kjetil Jacobsen <kjetilja> * Added CURLOPT_FTPSSLAUTH (and CURLFTPAUTH_*). * Added CURLINFO_OS_ERRNO. 2004-08-17 Kjetil Jacobsen <kjetilja> * Use LONG_LONG instead of PY_LONG_LONG to make pycurl compile on Python versions < 2.3 (fix from Domenico Andreoli <cavok at libero.it>). Version 7.12.1 -------------- 2004-08-02 Kjetil Jacobsen <kjetilja> * Added INFOTYPE_SSL_DATA_IN/OUT. 2004-07-16 Markus F.X.J. Oberhumer <mfx> * WARNING: removed deprecated PROXY_, TIMECOND_ and non-prefixed INFOTYPE constant names. See ChangeLog entry 2003-06-10. 2004-06-21 Kjetil Jacobsen <kjetilja> * Added test program for HTTP post using the read callback (see tests/test_post3.py for details). * Use the new CURL_READFUNC_ABORT return code where appropriate to avoid hanging in perform() when read callbacks are used. * Added support for libcurl 7.12.1 CURLOPT features: SOURCE_HOST, SOURCE_USERPWD, SOURCE_PATH, SOURCE_PORT, PASV_HOST, SOURCE_PREQUOTE, SOURCE_POSTQUOTE. 2004-06-08 Markus F.X.J. Oberhumer <mfx> * Setting CURLOPT_POSTFIELDS now allows binary data and automatically sets CURLOPT_POSTFIELDSIZE for you. If you really want a different size you have to manually set POSTFIELDSIZE after setting POSTFIELDS. (Based on a patch by Martin Muenstermann). 2004-06-05 Markus F.X.J. Oberhumer <mfx> * Added stricter checks within the callback handlers. * Unify the behaviour of int and long parameters where appropriate. Version 7.12 ------------ 2004-05-18 Kjetil Jacobsen <kjetilja> * WARNING: To simplify code maintenance pycurl now requires libcurl 7.11.2 and Python 2.2 or newer to work. * GC support is now always enabled. Version 7.11.3 -------------- 2004-04-30 Kjetil Jacobsen <kjetilja> * Do not use the deprecated curl_formparse function. API CHANGE: HTTPPOST now takes a list of tuples where each tuple contains a form name and a form value, both strings (see test/test_post2.py for example usage). * Found a possible reference count bug in the multithreading code which may have contributed to the long-standing GC segfault which has haunted pycurl. Fingers crossed. Version 7.11.2 -------------- 2004-04-21 Kjetil Jacobsen <kjetilja> * Added support for libcurl 7.11.2 CURLOPT features: CURLOPT_TCP_NODELAY. 2004-03-25 Kjetil Jacobsen <kjetilja> * Store Python longs in off_t with PyLong_AsLongLong instead of PyLong_AsLong. Should make the options which deal with large files behave a little better. Note that this requires the long long support in Python 2.2 or newer to work properly. Version 7.11.1 -------------- 2004-03-16 Kjetil Jacobsen <kjetilja> * WARNING: Removed support for the PASSWDFUNCTION callback, which is no longer supported by libcurl. 2004-03-15 Kjetil Jacobsen <kjetilja> * Added support for libcurl 7.11.1 CURLOPT features: CURLOPT_POSTFIELDSIZE_LARGE. Version 7.11.0 -------------- 2004-02-11 Kjetil Jacobsen <kjetilja> * Added support for libcurl 7.11.0 CURLOPT features: INFILESIZE_LARGE, RESUME_FROM_LARGE, MAXFILESIZE_LARGE and FTP_SSL. * Circular garbage collection support can now be enabled or disabled by passing the '--use-gc=[1|0]' parameter to setup.py when building pycurl. * HTTP_VERSION options are known as CURL_HTTP_VERSION_NONE, CURL_HTTP_VERSION_1_0, CURL_HTTP_VERSION_1_1 and CURL_HTTP_VERSION_LAST. 2003-11-16 Markus F.X.J. Oberhumer <mfx> * Added support for these new libcurl 7.11.0 features: CURLOPT_NETRC_FILE. Version 7.10.8 -------------- 2003-11-04 Markus F.X.J. Oberhumer <mfx> * Added support for these new libcurl 7.10.8 features: CURLOPT_FTP_RESPONSE_TIMEOUT, CURLOPT_IPRESOLVE, CURLOPT_MAXFILESIZE, CURLINFO_HTTPAUTH_AVAIL, CURLINFO_PROXYAUTH_AVAIL, CURL_IPRESOLVE_* constants. * Added support for these new libcurl 7.10.7 features: CURLOPT_FTP_CREATE_MISSING_DIRS, CURLOPT_PROXYAUTH, CURLINFO_HTTP_CONNECTCODE. 2003-10-28 Kjetil Jacobsen <kjetilja> * Added missing CURLOPT_ENCODING option (patch by Martijn Boerwinkel <xim at xs4all.nl>) Version 7.10.6 -------------- 2003-07-29 Markus F.X.J. Oberhumer <mfx> * Started working on support for CURLOPT_SSL_CTX_FUNCTION and CURLOPT_SSL_CTX_DATA (libcurl-7.10.6) - not yet finished. 2003-06-10 Markus F.X.J. Oberhumer <mfx> * Added support for CURLOPT_HTTPAUTH (libcurl-7.10.6), including the new HTTPAUTH_BASIC, HTTPAUTH_DIGEST, HTTPAUTH_GSSNEGOTIATE and HTTPAUTH_NTML constants. * Some constants were renamed for consistency: All curl_infotype constants are now prefixed with "INFOTYPE_", all curl_proxytype constants are prefixed with "PROXYTYPE_" instead of "PROXY_", and all curl_TimeCond constants are now prefixed with "TIMECONDITION_" instead of "TIMECOND_". (The old names are still available but will get removed in a future release.) * WARNING: Removed the deprecated pycurl.init() and pycurl.multi_init() names - use pycurl.Curl() and pycurl.CurlMulti() instead. * WARNING: Removed the deprecated Curl.cleanup() and CurlMulti.cleanup() methods - use Curl.close() and CurlMulti.close() instead. Version 7.10.5 -------------- 2003-05-15 Markus F.X.J. Oberhumer <mfx> * Added support for CURLOPT_FTP_USE_EPRT (libcurl-7.10.5). * Documentation updates. 2003-05-07 Eric S. Raymond <esr> * Lifted all HTML docs to clean XHTML, verified by tidy. 2003-05-02 Markus F.X.J. Oberhumer <mfx> * Fixed some `int' vs. `long' mismatches that affected 64-bit systems. * Fixed wrong pycurl.CAPATH constant. 2003-05-01 Markus F.X.J. Oberhumer <mfx> * Added new method Curl.errstr() which returns the internal libcurl error buffer string of the handle. Version 7.10.4.2 ---------------- 2003-04-15 Markus F.X.J. Oberhumer <mfx> * Allow compilation against the libcurl-7.10.3 release - some recent Linux distributions (e.g. Mandrake 9.1) ship with 7.10.3, and apart from the new CURLOPT_UNRESTRICTED_AUTH option there is no need that we require libcurl-7.10.4. Version 7.10.4 -------------- 2003-04-01 Kjetil Jacobsen <kjetilja> * Markus added CURLOPT_UNRESTRICTED_AUTH (libcurl-7.10.4). 2003-02-25 Kjetil Jacobsen <kjetilja> * Fixed some broken test code and removed the fileupload test since it didn't work properly. 2003-01-28 Kjetil Jacobsen <kjetilja> * Some documentation updates by Markus and me. 2003-01-22 Kjetil Jacobsen <kjetilja> * API CHANGE: the CurlMulti.info_read() method now returns a separate array with handles that failed. Each entry in this array is a tuple with (curl object, error number, error message). This addition makes it simpler to do error checking of individual curl objects when using the multi interface. Version 7.10.3 -------------- 2003-01-13 Kjetil Jacobsen <kjetilja> * PycURL memory usage has been reduced. 2003-01-10 Kjetil Jacobsen <kjetilja> * Added 'examples/retriever-multi.py' which shows how to retrieve a set of URLs concurrently using the multi interface. 2003-01-09 Kjetil Jacobsen <kjetilja> * Added support for CURLOPT_HTTP200ALIASES. 2002-11-22 Kjetil Jacobsen <kjetilja> * Updated pycurl documentation in the 'doc' directory. 2002-11-21 Kjetil Jacobsen <kjetilja> * Updated and improved 'examples/curl.py'. * Added 'tests/test_multi6.py' which shows how to use the info_read method with CurlMulti. 2002-11-19 Kjetil Jacobsen <kjetilja> * Added new method CurlMulti.info_read(). Version 7.10.2 -------------- 2002-11-14 Kjetil Jacobsen <kjetilja> * Free options set with setopt after cleanup is called, as cleanup assumes that options are still valid when invoked. This fixes the bug with COOKIEJAR reported by Bastiaan Naber <bastiaan at ricardis.tudelft.nl>. 2002-11-06 Markus F.X.J. Oberhumer <mfx> * Install documentation under /usr/share/doc instead of /usr/doc. Also, start shipping the (unfinished) HTML docs and some basic test scripts. 2002-10-30 Markus F.X.J. Oberhumer <mfx> * API CHANGE: For integral values, Curl.getinfo() now returns a Python-int instead of a Python-long. Version 7.10.1 -------------- 2002-10-03 Markus F.X.J. Oberhumer <mfx> * Added new module-level function version_info() from libcurl-7.10. Version 7.10 ------------ 2002-09-13 Kjetil Jacobsen <kjetilja> * Added commandline options to setup.py for specifying the path to 'curl-config' (non-windows) and the curl installation directory (windows). See the 'INSTALL' file for details. * Added CURLOPT_ENCODING, CURLOPT_NOSIGNAL and CURLOPT_BUFFERSIZE from libcurl-7.10 (by Markus Oberhumer). Version 7.9.8.4 --------------- 2002-08-28 Kjetil Jacobsen <kjetilja> * Added a simple web-browser example based on gtkhtml and pycurl. See the file 'examples/gtkhtml_demo.py' for details. The example requires a working installation of gnome-python with gtkhtml bindings enabled (pass --with-gtkhtml to gnome-python configure). 2002-08-14 Kjetil Jacobsen <kjetilja> * Added new method 'select' on CurlMulti objects. Example usage in 'tests/test_multi5.py'. This method is just an optimization of the combined use of fdset and select. 2002-08-12 Kjetil Jacobsen <kjetilja> * Added support for curl_multi_fdset. See the file 'tests/test_multi4.py' for example usage. Contributed by Conrad Steenberg <conrad at hep.caltech.edu>. * perform() on multi objects now returns a tuple (result, number of handles) like the libcurl interface does. 2002-08-08 Kjetil Jacobsen <kjetilja> * Added the 'sfquery' script which retrieves a SourceForge XML export object for a given project. See the file 'examples/sfquery.py' for details and usage. 'sfquery' was contributed by Eric S. Raymond <esr at thyrsus.com>. 2002-07-20 Markus F.X.J. Oberhumer <mfx> * API enhancements: added Curl() and CurlMulti() as aliases for init() and multi_init(), and added close() methods as aliases for the cleanup() methods. The new names much better match the actual intended use of the objects, and they also nicely correspond to Python's file object. * Also, all constants for Curl.setopt() and Curl.getinfo() are now visible from within Curl objects. All changes are fully backward-compatible. Version 7.9.8.3 --------------- 2002-07-16 Markus F.X.J. Oberhumer <mfx> * Under Python 2.2 or better, Curl and CurlMulti objects now automatically participate in cyclic garbage collection (using the gc module). Version 7.9.8.2 --------------- 2002-07-05 Markus F.X.J. Oberhumer <mfx> * Curl and CurlMulti objects now support standard Python attributes. See tests/test_multi2.py for an example. 2002-07-02 Kjetil Jacobsen <kjetilja> * Added support for the multi-interface. Version 7.9.8.1 --------------- 2002-06-25 Markus F.X.J. Oberhumer <mfx> * Fixed a couple of `int' vs. `size_t' mismatches in callbacks and Py_BuildValue() calls. 2002-06-25 Kjetil Jacobsen <kjetilja> * Use 'double' type instead of 'size_t' for progress callbacks (by Conrad Steenberg <conrad at hep.caltech.edu>). Also cleaned up some other type mismatches in the callback interfaces. 2002-06-24 Kjetil Jacobsen <kjetilja> * Added example code on how to upload a file using HTTPPOST in pycurl (code by Amit Mongia <amit_mongia at hotmail.com>). See the file 'test_fileupload.py' for details. Version 7.9.8 ------------- 2002-06-24 Kjetil Jacobsen <kjetilja> * Resolved some build problems on Windows (by Markus Oberhumer). 2002-06-19 Kjetil Jacobsen <kjetilja> * Added CURLOPT_CAPATH. * Added option constants for CURLOPT_NETRC: CURL_NETRC_OPTIONAL, CURL_NETRC_IGNORED and CURL_NETRC_REQUIRED. * Added option constants for CURLOPT_TIMECONDITION: TIMECOND_IFMODSINCE and TIMECOND_IFUNMODSINCE. * Added an simple example crawler, which downloads documents listed in a file with a configurable number of worker threads. See the file 'crawler.py' in the 'tests' directory for details. * Removed the redundant 'test_xmlrpc2.py' test script. * Disallow recursive callback invocations (by Markus Oberhumer). 2002-06-18 Kjetil Jacobsen <kjetilja> * Made some changes to setup.py which should fix the build problems on RedHat 7.3 (suggested by Benji <benji at kioza.net>). * Use CURLOPT_READDATA instead of CURLOPT_INFILE, and CURLOPT_WRITEDATA instead of CURLOPT_FILE. Also fixed some reference counting bugs with file objects. * CURLOPT_FILETIME and CURLINFO_FILETIME had a namespace clash which caused them not to work. Use OPT_FILETIME for setopt() and INFO_FILETIME for getinfo(). See example usage in 'test_getinfo.py' for details. Version 7.9.7 ------------- 2002-05-20 Kjetil Jacobsen <kjetilja> * New versioning scheme. Pycurl now has the same version number as the libcurl version it was built with. The pycurl version number thus indicates which version of libcurl is required to run. 2002-05-17 Kjetil Jacobsen <kjetilja> * Added CURLINFO_REDIRECT_TIME and CURLINFO_REDIRECT_COUNT. 2002-04-27 Kjetil Jacobsen <kjetilja> * Fixed potential memory leak and thread race (by Markus Oberhumer). Version 0.4.9 ------------- 2002-04-15 Kjetil Jacobsen <kjetilja> * Added CURLOPT_DEBUGFUNCTION to allow debug callbacks to be specified (see the file 'test_debug.py' for details on how to use debug callbacks). * Added CURLOPT_DNS_USE_GLOBAL_CACHE and CURLOPT_DNS_CACHE_TIMEOUT. * Fixed a segfault when finalizing curl objects in Python 1.5.2. * Now requires libcurl 7.9.6 or greater. 2002-04-12 Kjetil Jacobsen <kjetilja> * Added 'test_post2.py' file which is another example on how to issue POST requests. 2002-04-11 Markus F.X.J. Oberhumer <mfx> * Added the 'test_post.py' file which demonstrates the use of POST requests. Version 0.4.8 ------------- 2002-03-07 Kjetil Jacobsen <kjetilja> * Added CURLOPT_PREQUOTE. * Now requires libcurl 7.9.5 or greater. * Other minor code cleanups and bugfixes. 2002-03-05 Kjetil Jacobsen <kjetilja> * Do not allow WRITEFUNCTION and WRITEHEADER on the same handle. Version 0.4.7 ------------- 2002-02-27 Kjetil Jacobsen <kjetilja> * Abort callback if the thread state of the calling thread cannot be determined. * Check that the installed version of libcurl matches the requirements of pycurl. 2002-02-26 Kjetil Jacobsen <kjetilja> * Clarence Garnder <clarence at silcom.com> found a bug where string arguments to setopt sometimes were prematurely deallocated, this should now be fixed. 2002-02-21 Kjetil Jacobsen <kjetilja> * Added the 'xmlrpc_curl.py' file which implements a transport for xmlrpclib (xmlrpclib is part of Python 2.2). * Added CURLINFO_CONTENT_TYPE. * Added CURLOPT_SSLCERTTYPE, CURLOPT_SSLKEY, CURLOPT_SSLKEYTYPE, CURLOPT_SSLKEYPASSWD, CURLOPT_SSLENGINE and CURLOPT_SSLENGINE_DEFAULT. * When thrown, the pycurl.error exception is now a tuple consisting of the curl error code and the error message. * Now requires libcurl 7.9.4 or greater. 2002-02-19 Kjetil Jacobsen <kjetilja> * Fixed docstring for getopt() function. 2001-12-18 Kjetil Jacobsen <kjetilja> * Updated the INSTALL information for Win32. 2001-12-12 Kjetil Jacobsen <kjetilja> * Added missing link flag to make pycurl build on MacOS X (by Matt King <matt at gnik.com>). 2001-12-06 Kjetil Jacobsen <kjetilja> * Added CURLINFO_STARTTRANSFER_TIME and CURLOPT_FTP_USE_EPSV from libcurl 7.9.2. 2001-12-01 Markus F.X.J. Oberhumer <mfx> * Added the 'test_stringio.py' file which demonstrates the use of StringIO objects as callback. 2001-12-01 Markus F.X.J. Oberhumer <mfx> * setup.py: Do not remove entries from a list while iterating over it. 2001-11-29 Kjetil Jacobsen <kjetilja> * Added code in setup.py to install on Windows. Requires some manual configuration (by Tino Lange <Tino.Lange at gmx.de>). 2001-11-27 Kjetil Jacobsen <kjetilja> * Improved detection of where libcurl is installed in setup.py. Should make it easier to install pycurl when libcurl is not located in regular lib/include paths. 2001-11-05 Kjetil Jacobsen <kjetilja> * Some of the newer options to setopt were missing, this should now be fixed. 2001-11-04 Kjetil Jacobsen <kjetilja> * Exception handling has been improved and should no longer throw spurious exceptions (by Markus F.X.J. Oberhumer <markus at oberhumer.com>). 2001-10-15 Kjetil Jacobsen <kjetilja> * Refactored the test_gtk.py script to avoid global variables. 2001-10-12 Kjetil Jacobsen <kjetilja> * Added module docstrings, terse perhaps, but better than nothing. * Added the 'basicfirst.py' file which is a Python version of the corresponding Perl script by Daniel. * PycURL now works properly under Python 1.5 and 1.6 (by Markus F.X.J. Oberhumer <markus at oberhumer.com>). * Allow C-functions and Python methods as callbacks (by Markus F.X.J. Oberhumer <markus at oberhumer.com>). * Allow None as success result of write, header and progress callback invocations (by Markus F.X.J. Oberhumer <markus at oberhumer.com>). * Added the 'basicfirst2.py' file which demonstrates the use of a class method as callback instead of just a function. 2001-08-21 Kjetil Jacobsen <kjetilja> * Cleaned up the script with GNOME/PycURL integration. 2001-08-20 Kjetil Jacobsen <kjetilja> * Added another test script for shipping XML-RPC requests which uses py-xmlrpc to encode the arguments (tests/test_xmlrpc2.py). 2001-08-20 Kjetil Jacobsen <kjetilja> * Added test script for using PycURL and GNOME (tests/test_gtk.py). 2001-08-20 Kjetil Jacobsen <kjetilja> * Added test script for using XML-RPC (tests/test_xmlrpc.py). * Added more comments to the test sources. 2001-08-06 Kjetil Jacobsen <kjetilja> * Renamed module namespace to pycurl instead of curl. 2001-08-06 Kjetil Jacobsen <kjetilja> * Set CURLOPT_VERBOSE to 0 by default. 2001-06-29 Kjetil Jacobsen <kjetilja> * Updated INSTALL, curl version 7.8 or greater is now mandatory to use pycurl. 2001-06-13 Kjetil Jacobsen <kjetilja> * Set NOPROGRESS to 1 by default. 2001-06-07 Kjetil Jacobsen <kjetilja> * Added global_init/cleanup. 2001-06-06 Kjetil Jacobsen <kjetilja> * Added HEADER/PROGRESSFUNCTION callbacks (see files in tests/). * Added PASSWDFUNCTION callback (untested). * Added READFUNCTION callback (untested). 2001-06-05 Kjetil Jacobsen <kjetilja> * WRITEFUNCTION callbacks now work (see tests/test_cb.py for details). * Preliminary distutils installation. * Added CLOSEPOLICY constants to module namespace. 2001-06-04 Kjetil Jacobsen <kjetilja> * Return -1 on error from Python callback in WRITEFUNCTION callback. 2001-06-01 Kjetil Jacobsen <kjetilja> * Moved source to src and tests to tests directory. 2001-05-31 Kjetil Jacobsen <kjetilja> * Added better type checking for setopt. 2001-05-30 Kjetil Jacobsen <kjetilja> * Moved code to sourceforge. * Added getinfo support. # vi:ts=8:et PK KWi\>X"V�g �g doc/pycurl/COPYING-LGPLnu �[��� GNU LESSER GENERAL PUBLIC LICENSE Version 2.1, February 1999 Copyright (C) 1991, 1999 Free Software Foundation, Inc. 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. [This is the first released version of the Lesser GPL. It also counts as the successor of the GNU Library Public License, version 2, hence the version number 2.1.] Preamble The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public Licenses are intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This license, the Lesser General Public License, applies to some specially designated software packages--typically libraries--of the Free Software Foundation and other authors who decide to use it. You can use it too, but we suggest you first think carefully about whether this license or the ordinary General Public License is the better strategy to use in any particular case, based on the explanations below. When we speak of free software, we are referring to freedom of use, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish); that you receive source code or can get it if you want it; that you can change the software and use pieces of it in new free programs; and that you are informed that you can do these things. To protect your rights, we need to make restrictions that forbid distributors to deny you these rights or to ask you to surrender these rights. These restrictions translate to certain responsibilities for you if you distribute copies of the library or if you modify it. For example, if you distribute copies of the library, whether gratis or for a fee, you must give the recipients all the rights that we gave you. You must make sure that they, too, receive or can get the source code. If you link other code with the library, you must provide complete object files to the recipients, so that they can relink them with the library after making changes to the library and recompiling it. And you must show them these terms so they know their rights. We protect your rights with a two-step method: (1) we copyright the library, and (2) we offer you this license, which gives you legal permission to copy, distribute and/or modify the library. To protect each distributor, we want to make it very clear that there is no warranty for the free library. Also, if the library is modified by someone else and passed on, the recipients should know that what they have is not the original version, so that the original author's reputation will not be affected by problems that might be introduced by others. Finally, software patents pose a constant threat to the existence of any free program. We wish to make sure that a company cannot effectively restrict the users of a free program by obtaining a restrictive license from a patent holder. Therefore, we insist that any patent license obtained for a version of the library must be consistent with the full freedom of use specified in this license. Most GNU software, including some libraries, is covered by the ordinary GNU General Public License. This license, the GNU Lesser General Public License, applies to certain designated libraries, and is quite different from the ordinary General Public License. We use this license for certain libraries in order to permit linking those libraries into non-free programs. When a program is linked with a library, whether statically or using a shared library, the combination of the two is legally speaking a combined work, a derivative of the original library. The ordinary General Public License therefore permits such linking only if the entire combination fits its criteria of freedom. The Lesser General Public License permits more lax criteria for linking other code with the library. We call this license the "Lesser" General Public License because it does Less to protect the user's freedom than the ordinary General Public License. It also provides other free software developers Less of an advantage over competing non-free programs. These disadvantages are the reason we use the ordinary General Public License for many libraries. However, the Lesser license provides advantages in certain special circumstances. For example, on rare occasions, there may be a special need to encourage the widest possible use of a certain library, so that it becomes a de-facto standard. To achieve this, non-free programs must be allowed to use the library. A more frequent case is that a free library does the same job as widely used non-free libraries. In this case, there is little to gain by limiting the free library to free software only, so we use the Lesser General Public License. In other cases, permission to use a particular library in non-free programs enables a greater number of people to use a large body of free software. For example, permission to use the GNU C Library in non-free programs enables many more people to use the whole GNU operating system, as well as its variant, the GNU/Linux operating system. Although the Lesser General Public License is Less protective of the users' freedom, it does ensure that the user of a program that is linked with the Library has the freedom and the wherewithal to run that program using a modified version of the Library. The precise terms and conditions for copying, distribution and modification follow. Pay close attention to the difference between a "work based on the library" and a "work that uses the library". The former contains code derived from the library, whereas the latter must be combined with the library in order to run. GNU LESSER GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 0. This License Agreement applies to any software library or other program which contains a notice placed by the copyright holder or other authorized party saying it may be distributed under the terms of this Lesser General Public License (also called "this License"). Each licensee is addressed as "you". A "library" means a collection of software functions and/or data prepared so as to be conveniently linked with application programs (which use some of those functions and data) to form executables. The "Library", below, refers to any such software library or work which has been distributed under these terms. A "work based on the Library" means either the Library or any derivative work under copyright law: that is to say, a work containing the Library or a portion of it, either verbatim or with modifications and/or translated straightforwardly into another language. (Hereinafter, translation is included without limitation in the term "modification".) "Source code" for a work means the preferred form of the work for making modifications to it. For a library, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the library. Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running a program using the Library is not restricted, and output from such a program is covered only if its contents constitute a work based on the Library (independent of the use of the Library in a tool for writing it). Whether that is true depends on what the Library does and what the program that uses the Library does. 1. You may copy and distribute verbatim copies of the Library's complete source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and distribute a copy of this License along with the Library. You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee. 2. You may modify your copy or copies of the Library or any portion of it, thus forming a work based on the Library, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions: a) The modified work must itself be a software library. b) You must cause the files modified to carry prominent notices stating that you changed the files and the date of any change. c) You must cause the whole of the work to be licensed at no charge to all third parties under the terms of this License. d) If a facility in the modified Library refers to a function or a table of data to be supplied by an application program that uses the facility, other than as an argument passed when the facility is invoked, then you must make a good faith effort to ensure that, in the event an application does not supply such function or table, the facility still operates, and performs whatever part of its purpose remains meaningful. (For example, a function in a library to compute square roots has a purpose that is entirely well-defined independent of the application. Therefore, Subsection 2d requires that any application-supplied function or table used by this function must be optional: if the application does not supply it, the square root function must still compute square roots.) These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Library, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Library, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Library. In addition, mere aggregation of another work not based on the Library with the Library (or with a work based on the Library) on a volume of a storage or distribution medium does not bring the other work under the scope of this License. 3. You may opt to apply the terms of the ordinary GNU General Public License instead of this License to a given copy of the Library. To do this, you must alter all the notices that refer to this License, so that they refer to the ordinary GNU General Public License, version 2, instead of to this License. (If a newer version than version 2 of the ordinary GNU General Public License has appeared, then you can specify that version instead if you wish.) Do not make any other change in these notices. Once this change is made in a given copy, it is irreversible for that copy, so the ordinary GNU General Public License applies to all subsequent copies and derivative works made from that copy. This option is useful when you wish to copy part of the code of the Library into a program that is not a library. 4. You may copy and distribute the Library (or a portion or derivative of it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange. If distribution of object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place satisfies the requirement to distribute the source code, even though third parties are not compelled to copy the source along with the object code. 5. A program that contains no derivative of any portion of the Library, but is designed to work with the Library by being compiled or linked with it, is called a "work that uses the Library". Such a work, in isolation, is not a derivative work of the Library, and therefore falls outside the scope of this License. However, linking a "work that uses the Library" with the Library creates an executable that is a derivative of the Library (because it contains portions of the Library), rather than a "work that uses the library". The executable is therefore covered by this License. Section 6 states terms for distribution of such executables. When a "work that uses the Library" uses material from a header file that is part of the Library, the object code for the work may be a derivative work of the Library even though the source code is not. Whether this is true is especially significant if the work can be linked without the Library, or if the work is itself a library. The threshold for this to be true is not precisely defined by law. If such an object file uses only numerical parameters, data structure layouts and accessors, and small macros and small inline functions (ten lines or less in length), then the use of the object file is unrestricted, regardless of whether it is legally a derivative work. (Executables containing this object code plus portions of the Library will still fall under Section 6.) Otherwise, if the work is a derivative of the Library, you may distribute the object code for the work under the terms of Section 6. Any executables containing that work also fall under Section 6, whether or not they are linked directly with the Library itself. 6. As an exception to the Sections above, you may also combine or link a "work that uses the Library" with the Library to produce a work containing portions of the Library, and distribute that work under terms of your choice, provided that the terms permit modification of the work for the customer's own use and reverse engineering for debugging such modifications. You must give prominent notice with each copy of the work that the Library is used in it and that the Library and its use are covered by this License. You must supply a copy of this License. If the work during execution displays copyright notices, you must include the copyright notice for the Library among them, as well as a reference directing the user to the copy of this License. Also, you must do one of these things: a) Accompany the work with the complete corresponding machine-readable source code for the Library including whatever changes were used in the work (which must be distributed under Sections 1 and 2 above); and, if the work is an executable linked with the Library, with the complete machine-readable "work that uses the Library", as object code and/or source code, so that the user can modify the Library and then relink to produce a modified executable containing the modified Library. (It is understood that the user who changes the contents of definitions files in the Library will not necessarily be able to recompile the application to use the modified definitions.) b) Use a suitable shared library mechanism for linking with the Library. A suitable mechanism is one that (1) uses at run time a copy of the library already present on the user's computer system, rather than copying library functions into the executable, and (2) will operate properly with a modified version of the library, if the user installs one, as long as the modified version is interface-compatible with the version that the work was made with. c) Accompany the work with a written offer, valid for at least three years, to give the same user the materials specified in Subsection 6a, above, for a charge no more than the cost of performing this distribution. d) If distribution of the work is made by offering access to copy from a designated place, offer equivalent access to copy the above specified materials from the same place. e) Verify that the user has already received a copy of these materials or that you have already sent this user a copy. For an executable, the required form of the "work that uses the Library" must include any data and utility programs needed for reproducing the executable from it. However, as a special exception, the materials to be distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. It may happen that this requirement contradicts the license restrictions of other proprietary libraries that do not normally accompany the operating system. Such a contradiction means you cannot use both them and the Library together in an executable that you distribute. 7. You may place library facilities that are a work based on the Library side-by-side in a single library together with other library facilities not covered by this License, and distribute such a combined library, provided that the separate distribution of the work based on the Library and of the other library facilities is otherwise permitted, and provided that you do these two things: a) Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities. This must be distributed under the terms of the Sections above. b) Give prominent notice with the combined library of the fact that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work. 8. You may not copy, modify, sublicense, link with, or distribute the Library except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, link with, or distribute the Library is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 9. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Library or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Library (or any work based on the Library), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Library or works based on it. 10. Each time you redistribute the Library (or any work based on the Library), the recipient automatically receives a license from the original licensor to copy, distribute, link with or modify the Library subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties with this License. 11. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Library at all. For example, if a patent license would not permit royalty-free redistribution of the Library by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Library. If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply, and the section as a whole is intended to apply in other circumstances. It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice. This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License. 12. If the distribution and/or use of the Library is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Library under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License. 13. The Free Software Foundation may publish revised and/or new versions of the Lesser General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Library specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Library does not specify a license version number, you may choose any version ever published by the Free Software Foundation. 14. If you wish to incorporate parts of the Library into other free programs whose distribution conditions are incompatible with these, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. NO WARRANTY 15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. END OF TERMS AND CONDITIONS How to Apply These Terms to Your New Libraries If you develop a new library, and you want it to be of the greatest possible use to the public, we recommend making it free software that everyone can redistribute and change. You can do so by permitting redistribution under these terms (or, alternatively, under the terms of the ordinary General Public License). To apply these terms, attach the following notices to the library. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found. <one line to give the library's name and a brief idea of what it does.> Copyright (C) <year> <name of author> This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA Also add information on how to contact you by electronic and paper mail. You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the library, if necessary. Here is a sample; alter the names: Yoyodyne, Inc., hereby disclaims all copyright interest in the library `Frob' (a library for tweaking knobs) written by James Random Hacker. <signature of Ty Coon>, 1 April 1990 Ty Coon, President of Vice That's all there is to it! PK KWi\FX� U U doc/pycurl/examples/linksys.pynu �[��� #! /usr/bin/env python # -*- coding: utf-8 -*- # vi:ts=4:et # # linksys.py -- program settings on a Linkys router # # This tool is designed to help you recover from the occasional episodes # of catatonia that afflict Linksys boxes. It allows you to batch-program # them rather than manually entering values to the Web interface. Commands # are taken from the command line first, then standard input. # # The somewhat spotty coverage of status queries is because I only did the # ones that were either (a) easy, or (b) necessary. If you want to know the # status of the box, look at the web interface. # # This code has been tested against the following hardware: # # Hardware Firmware # ---------- --------------------- # BEFW11S4v2 1.44.2.1, Dec 20 2002 # # The code is, of course, sensitive to changes in the names of CGI pages # and field names. # # Note: to make the no-arguments form work, you'll need to have the following # entry in your ~/.netrc file. If you have changed the router IP address or # name/password, modify accordingly. # # machine 192.168.1.1 # login "" # password admin # # By Eric S. Raymond, August April 2003. All rites reversed. import sys, re, curl, exceptions def print_stderr(arg): sys.stderr.write(arg) sys.stderr.write("\n") class LinksysError(exceptions.Exception): def __init__(self, *args): self.args = args class LinksysSession: months = 'Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec' WAN_CONNECT_AUTO = '1' WAN_CONNECT_STATIC = '2' WAN_CONNECT_PPOE = '3' WAN_CONNECT_RAS = '4' WAN_CONNECT_PPTP = '5' WAN_CONNECT_HEARTBEAT = '6' # Substrings to check for on each page load. # This may enable us to detect when a firmware change has hosed us. check_strings = { "": "basic setup functions", "Passwd.htm": "For security reasons,", "DHCP.html": "You can configure the router to act as a DHCP", "Log.html": "There are some log settings and lists in this page.", "Forward.htm":"Port forwarding can be used to set up public services", } def __init__(self): self.actions = [] self.host = "http://192.168.1.1" self.verbosity = False self.pagecache = {} def set_verbosity(self, flag): self.verbosity = flag # This is not a performance hack -- we need the page cache to do # sanity checks at configure time. def cache_load(self, page): if page not in self.pagecache: fetch = curl.Curl(self.host) fetch.set_verbosity(self.verbosity) fetch.get(page) self.pagecache[page] = fetch.body() if fetch.answered("401"): raise LinksysError("authorization failure.", True) elif not fetch.answered(LinksysSession.check_strings[page]): del self.pagecache[page] raise LinksysError("check string for page %s missing!" % os.path.join(self.host, page), False) fetch.close() def cache_flush(self): self.pagecache = {} # Primitives def screen_scrape(self, page, template): self.cache_load(page) match = re.compile(template).search(self.pagecache[page]) if match: result = match.group(1) else: result = None return result def get_MAC_address(self, page, prefix): return self.screen_scrape("", prefix+r":[^M]*\(MAC Address: *([^)]*)") def set_flag(self, page, flag, value): if value: self.actions.append(page, flag, "1") else: self.actions.append(page, flag, "0") def set_IP_address(self, page, cgi, role, ip): ind = 0 for octet in ip.split("."): self.actions.append(("", "F1", role + repr(ind+1), octet)) ind += 1 # Scrape configuration data off the main page def get_firmware_version(self): # This is fragile. There is no distinguishing tag before the firmware # version, so we have to key off the pattern of the version number. # Our model is ">1.44.2.1, Dec 20 2002<" return self.screen_scrape("", ">([0-9.v]*, (" + \ LinksysSession.months + ")[^<]*)<", ) def get_LAN_MAC(self): return self.get_MAC_address("", r"LAN IP Address") def get_Wireless_MAC(self): return self.get_MAC_address("", r"Wireless") def get_WAN_MAC(self): return self.get_MAC_address("", r"WAN Connection Type") # Set configuration data on the main page def set_host_name(self, name): self.actions.append(("", "hostName", name)) def set_domain_name(self, name): self.actions.append(("", "DomainName", name)) def set_LAN_IP(self, ip): self.set_IP_address("", "ipAddr", ip) def set_LAN_netmask(self, ip): if not ip.startswith("255.255.255."): raise ValueError lastquad = ip.split(".")[-1] if lastquad not in ("0", "128", "192", "240", "252"): raise ValueError self.actions.append("", "netMask", lastquad) def set_wireless(self, flag): self.set_flag("", "wirelessStatus") def set_SSID(self, ssid): self.actions.append(("", "wirelessESSID", ssid)) def set_SSID_broadcast(self, flag): self.set_flag("", "broadcastSSID") def set_channel(self, channel): self.actions.append(("", "wirelessChannel", channel)) def set_WEP(self, flag): self.set_flag("", "WepType") # FIXME: Add support for setting WEP keys def set_connection_type(self, type): self.actions.append(("", "WANConnectionType", type)) def set_WAN_IP(self, ip): self.set_IP_address("", "aliasIP", ip) def set_WAN_netmask(self, ip): self.set_IP_address("", "aliasMaskIP", ip) def set_WAN_gateway_address(self, ip): self.set_IP_address("", "routerIP", ip) def set_DNS_server(self, index, ip): self.set_IP_address("", "dns" + "ABC"[index], ip) # Set configuration data on the password page def set_password(self, str): self.actions.append("Passwd.htm","sysPasswd", str) self.actions.append("Passwd.htm","sysPasswdConfirm", str) def set_UPnP(self, flag): self.set_flag("Passwd.htm", "UPnP_Work") def reset(self): self.actions.append("Passwd.htm", "FactoryDefaults") # DHCP features def set_DHCP(self, flag): if flag: self.actions.append("DHCP.htm","dhcpStatus","Enable") else: self.actions.append("DHCP.htm","dhcpStatus","Disable") def set_DHCP_starting_IP(self, val): self.actions.append("DHCP.htm","dhcpS4", str(val)) def set_DHCP_users(self, val): self.actions.append("DHCP.htm","dhcpLen", str(val)) def set_DHCP_lease_time(self, val): self.actions.append("DHCP.htm","leaseTime", str(val)) def set_DHCP_DNS_server(self, index, ip): self.set_IP_address("DHCP.htm", "dns" + "ABC"[index], ip) # FIXME: add support for setting WINS key # Logging features def set_logging(self, flag): if flag: self.actions.append("Log.htm", "rLog", "Enable") else: self.actions.append("Log.htm", "rLog", "Disable") def set_log_address(self, val): self.actions.append("DHCP.htm","trapAddr3", str(val)) # The AOL parental control flag is not supported by design. # FIXME: add Filters and other advanced features def configure(self): "Write configuration changes to the Linksys." if self.actions: fields = [] self.cache_flush() for (page, field, value) in self.actions: self.cache_load(page) if self.pagecache[page].find(field) == -1: print_stderr("linksys: field %s not found where expected in page %s!" % (field, os.path.join(self.host, page))) continue else: fields.append((field, value)) # Clearing the action list before fieldsping is deliberate. # Otherwise we could get permanently wedged by a 401. self.actions = [] transaction = curl.Curl(self.host) transaction.set_verbosity(self.verbosity) transaction.get("Gozila.cgi", tuple(fields)) transaction.close() if __name__ == "__main__": import os, cmd class LinksysInterpreter(cmd.Cmd): """Interpret commands to perform LinkSys programming actions.""" def __init__(self): cmd.Cmd.__init__(self) self.session = LinksysSession() if os.isatty(0): print("Type ? or `help' for help.") self.prompt = self.session.host + ": " else: self.prompt = "" print("Bar1") def flag_command(self, func, line): if line.strip() in ("on", "enable", "yes"): func(True) elif line.strip() in ("off", "disable", "no"): func(False) else: print_stderr("linksys: unknown switch value") return 0 def do_connect(self, line): newhost = line.strip() if newhost: self.session.host = newhost self.session.cache_flush() self.prompt = self.session.host + ": " else: print(self.session.host) return 0 def help_connect(self): print("Usage: connect [<hostname-or-IP>]") print("Connect to a Linksys by name or IP address.") print("If no argument is given, print the current host.") def do_status(self, line): self.session.cache_load("") if "" in self.session.pagecache: print("Firmware:", self.session.get_firmware_version()) print("LAN MAC:", self.session.get_LAN_MAC()) print("Wireless MAC:", self.session.get_Wireless_MAC()) print("WAN MAC:", self.session.get_WAN_MAC()) print(".") return 0 def help_status(self): print("Usage: status") print("The status command shows the status of the Linksys.") print("It is mainly useful as a sanity check to make sure") print("the box is responding correctly.") def do_verbose(self, line): self.flag_command(self.session.set_verbosity, line) def help_verbose(self): print("Usage: verbose {on|off|enable|disable|yes|no}") print("Enables display of HTTP requests.") def do_host(self, line): self.session.set_host_name(line) return 0 def help_host(self): print("Usage: host <hostname>") print("Sets the Host field to be queried by the ISP.") def do_domain(self, line): print("Usage: host <domainname>") self.session.set_domain_name(line) return 0 def help_domain(self): print("Sets the Domain field to be queried by the ISP.") def do_lan_address(self, line): self.session.set_LAN_IP(line) return 0 def help_lan_address(self): print("Usage: lan_address <ip-address>") print("Sets the LAN IP address.") def do_lan_netmask(self, line): self.session.set_LAN_netmask(line) return 0 def help_lan_netmask(self): print("Usage: lan_netmask <ip-mask>") print("Sets the LAN subnetwork mask.") def do_wireless(self, line): self.flag_command(self.session.set_wireless, line) return 0 def help_wireless(self): print("Usage: wireless {on|off|enable|disable|yes|no}") print("Switch to enable or disable wireless features.") def do_ssid(self, line): self.session.set_SSID(line) return 0 def help_ssid(self): print("Usage: ssid <string>") print("Sets the SSID used to control wireless access.") def do_ssid_broadcast(self, line): self.flag_command(self.session.set_SSID_broadcast, line) return 0 def help_ssid_broadcast(self): print("Usage: ssid_broadcast {on|off|enable|disable|yes|no}") print("Switch to enable or disable SSID broadcast.") def do_channel(self, line): self.session.set_channel(line) return 0 def help_channel(self): print("Usage: channel <number>") print("Sets the wireless channel.") def do_wep(self, line): self.flag_command(self.session.set_WEP, line) return 0 def help_wep(self): print("Usage: wep {on|off|enable|disable|yes|no}") print("Switch to enable or disable WEP security.") def do_wan_type(self, line): try: type=eval("LinksysSession.WAN_CONNECT_"+line.strip().upper()) self.session.set_connection_type(type) except ValueError: print_stderr("linksys: unknown connection type.") return 0 def help_wan_type(self): print("Usage: wan_type {auto|static|ppoe|ras|pptp|heartbeat}") print("Set the WAN connection type.") def do_wan_address(self, line): self.session.set_WAN_IP(line) return 0 def help_wan_address(self): print("Usage: wan_address <ip-address>") print("Sets the WAN IP address.") def do_wan_netmask(self, line): self.session.set_WAN_netmask(line) return 0 def help_wan_netmask(self): print("Usage: wan_netmask <ip-mask>") print("Sets the WAN subnetwork mask.") def do_wan_gateway(self, line): self.session.set_WAN_gateway(line) return 0 def help_wan_gateway(self): print("Usage: wan_gateway <ip-address>") print("Sets the LAN subnetwork mask.") def do_dns(self, line): (index, address) = line.split() if index in ("1", "2", "3"): self.session.set_DNS_server(eval(index), address) else: print_stderr("linksys: server index out of bounds.") return 0 def help_dns(self): print("Usage: dns {1|2|3} <ip-mask>") print("Sets a primary, secondary, or tertiary DNS server address.") def do_password(self, line): self.session.set_password(line) return 0 def help_password(self): print("Usage: password <string>") print("Sets the router password.") def do_upnp(self, line): self.flag_command(self.session.set_UPnP, line) return 0 def help_upnp(self): print("Usage: upnp {on|off|enable|disable|yes|no}") print("Switch to enable or disable Universal Plug and Play.") def do_reset(self, line): self.session.reset() def help_reset(self): print("Usage: reset") print("Reset Linksys settings to factory defaults.") def do_dhcp(self, line): self.flag_command(self.session.set_DHCP, line) def help_dhcp(self): print("Usage: dhcp {on|off|enable|disable|yes|no}") print("Switch to enable or disable DHCP features.") def do_dhcp_start(self, line): self.session.set_DHCP_starting_IP(line) def help_dhcp_start(self): print("Usage: dhcp_start <number>") print("Set the start address of the DHCP pool.") def do_dhcp_users(self, line): self.session.set_DHCP_users(line) def help_dhcp_users(self): print("Usage: dhcp_users <number>") print("Set number of address slots to allocate in the DHCP pool.") def do_dhcp_lease(self, line): self.session.set_DHCP_lease(line) def help_dhcp_lease(self): print("Usage: dhcp_lease <number>") print("Set number of address slots to allocate in the DHCP pool.") def do_dhcp_dns(self, line): (index, address) = line.split() if index in ("1", "2", "3"): self.session.set_DHCP_DNS_server(eval(index), address) else: print_stderr("linksys: server index out of bounds.") return 0 def help_dhcp_dns(self): print("Usage: dhcp_dns {1|2|3} <ip-mask>") print("Sets primary, secondary, or tertiary DNS server address.") def do_logging(self, line): self.flag_command(self.session.set_logging, line) def help_logging(self): print("Usage: logging {on|off|enable|disable|yes|no}") print("Switch to enable or disable session logging.") def do_log_address(self, line): self.session.set_Log_address(line) def help_log_address(self): print("Usage: log_address <number>") print("Set the last quad of the address to which to log.") def do_configure(self, line): self.session.configure() return 0 def help_configure(self): print("Usage: configure") print("Writes the configuration to the Linksys.") def do_cache(self, line): print(self.session.pagecache) def help_cache(self): print("Usage: cache") print("Display the page cache.") def do_quit(self, line): return 1 def help_quit(self, line): print("The quit command ends your linksys session without") print("writing configuration changes to the Linksys.") def do_EOF(self, line): print("") self.session.configure() return 1 def help_EOF(self): print("The EOF command writes the configuration to the linksys") print("and ends your session.") def default(self, line): """Pass the command through to be executed by the shell.""" os.system(line) return 0 def help_help(self): print("On-line help is available through this command.") print("? is a convenience alias for help.") def help_introduction(self): print("""\ This program supports changing the settings on Linksys blue-box routers. This capability may come in handy when they freeze up and have to be reset. Though it can be used interactively (and will command-prompt when standard input is a terminal) it is really designed to be used in batch mode. Commands are taken from the command line first, then standard input. By default, it is assumed that the Linksys is at http://192.168.1.1, the default LAN address. You can connect to a different address or IP with the 'connect' command. Note that your .netrc must contain correct user/password credentials for the router. The entry corresponding to the defaults is: machine 192.168.1.1 login "" password admin Most commands queue up changes but don't actually send them to the Linksys. You can force pending changes to be written with 'configure'. Otherwise, they will be shipped to the Linksys at the end of session (e.g. when the program running in batch mode encounters end-of-file or you type a control-D). If you end the session with `quit', pending changes will be discarded. For more help, read the topics 'wan', 'lan', and 'wireless'.""") def help_lan(self): print("""\ The `lan_address' and `lan_netmask' commands let you set the IP location of the Linksys on your LAN, or inside. Normally you'll want to leave these untouched.""") def help_wan(self): print("""\ The WAN commands become significant if you are using the BEFSR41 or any of the other Linksys boxes designed as DSL or cable-modem gateways. You will need to use `wan_type' to declare how you expect to get your address. If your ISP has issued you a static address, you'll need to use the `wan_address', `wan_netmask', and `wan_gateway' commands to set the address of the router as seen from the WAN, the outside. In this case you will also need to use the `dns' command to declare which remote servers your DNS requests should be forwarded to. Some ISPs may require you to set host and domain for use with dynamic-address allocation.""") def help_wireless_desc(self): print("""\ The channel, ssid, ssid_broadcast, wep, and wireless commands control wireless routing.""") def help_switches(self): print("Switches may be turned on with 'on', 'enable', or 'yes'.") print("Switches may be turned off with 'off', 'disable', or 'no'.") print("Switch commands include: wireless, ssid_broadcast.") def help_addresses(self): print("An address argument must be a valid IP address;") print("four decimal numbers separated by dots, each ") print("between 0 and 255.") def emptyline(self): pass interpreter = LinksysInterpreter() for arg in sys.argv[1:]: interpreter.onecmd(arg) fatal = False while not fatal: try: interpreter.cmdloop() fatal = True except LinksysError: message, fatal = sys.exc_info()[1].args print("linksys: " + message) # The following sets edit modes for GNU EMACS # Local Variables: # mode:python # End: PK KWi\>�! ? doc/pycurl/examples/__pycache__/retriever-multi.cpython-312.pycnu �[��� � N��g � � � d dl Z d dlZ d dlZd dlmZmZ ej ee� dZ e j d dk( re j j � Z n# e e j d � j � Z e e j � dk\ r e e j d � Zg Ze D ]> Zej% � Zered d k( r� d e e� dz z Zej) eef� �@ esJ d � � e e� Z eee� Zdecxk r d k sJ d � � J d � � edej. ej0 fz � ededed� ej2 � Zg e_ e e� D ]� Z ej< � Z de _ e jC ejD d� e jC ejF d� e jC ejH d� e jC ejJ d� e jC ejL d� ej6 j) e � �� ej6 dd Z'd Z(e(ek �r�er�e'r�ejS d � \ ZZe'jS � Z e ed� e _ e jC ejT e� e jC ejV e j@ � ejY e � ee _ ee _ ere'r�� ej[ � \ Z.Z/e.ej` k7 rn�$ ejc � \ Z2Z3Z4e3D ]} Z e j@ jk � de _ ejm e � ede j& e j" e jo ejp � � e'j) e � � e4D ]i \ Z Z9Z:e j@ jk � de _ ejm e � ede j& e j" e9e:� e'j) e � �k e( e e3� z e e4� z Z(e2d k( rn�� ejw d� e(ek r���ej6 D ]? Z e j@ �!e j@ jk � de _ e jk � �A ejk � y# e$ r Y ��w xY w# ede j d z � e�xY w)� N)�SIGPIPE�SIG_IGN� � �-� � zCUsage: %s <file with URLs to fetch> [<# of concurrent connections>]�#z doc_%03d.datz no URLs giveni' z(invalid number of concurrent connectionsz!PycURL %s (compiled against 0x%x)z ----- Gettingz URLs usingzconnections -----� � i, �wbzSuccess:zFailed: g �?)<�sys�pycurl�signalr r � ImportError�num_conn�argv�stdin� readlines�urls�open�len�int�print� SystemExit�queue�url�strip�filename�append�num_urls�min�version�COMPILE_LIBCURL_VERSION_NUM� CurlMulti�m�handles�range�i�Curl�c�fp�setopt�FOLLOWLOCATION� MAXREDIRS�CONNECTTIMEOUT�TIMEOUT�NOSIGNAL�freelist� num_processed�pop�URL� WRITEDATA� add_handle�perform�ret� num_handles�E_CALL_MULTI_PERFORM� info_read�num_q�ok_list�err_list�close� remove_handle�getinfo� EFFECTIVE_URL�errno�errmsg�select� � �c/opt/hc_python/lib64/python3.12/site-packages/../../../share/doc/pycurl/examples/retriever-multi.py�<module>rK sO �� � �$��'� �F�M�M�'�7�#� �� � �x�x��{�c���y�y�"�"�$���C�H�H�Q�K� �*�*�,�� �3�8�8�}����s�x�x��{�#�� �� �C� �)�)�+�C� �#�a�&�C�-�� ��U��a� �0�H� �L�L�#�x� �!� � � �o� �u� �u�:�� �x�� "���H� �� � I� I� I� � I� I� I� � �)�V�^�^�V�=_�=_�,`�`� a� �o�x� �x�9L� M� �F����� �� � �x� �A��� � � �A� �A�D��H�H�V� "� "�A�&��H�H�V� � �q�!��H�H�V� "� "�B�'��H�H�V�^�^�S�!��H�H�V�_�_�a� ��I�I���Q�� � �9�9�Q�<��� ��h� � �H� � � �!� � ��X� �L�L�N���H�d�#��� ������S�!� ����!�!�1�4�4�(� � � �Q�� �� ���� �H� � �9�9�;���[� �&�-�-� -� � � �#$�;�;�=� ��w���A� �D�D�J�J�L��A�D� �O�O�A� � �*�a�j�j�!�%�%����6�;O�;O�1P� Q� �O�O�A� � � !)� �A�u�f� �D�D�J�J�L��A�D� �O�O�A� � �*�a�j�j�!�%�%��� ?� �O�O�A� � !)� &��G� �4�s�8�}�D� � �A�:� �! �( �H�H�S�M�M �h� �T ���A��t�t�� ��� � � �����G�G�I� � ��� ��Q � �� �� � � O�RU�RZ�RZ�[\�R]� ]�^� ��s � R �A:R, � R)�(R)�, SPK KWi\)i=� 7 doc/pycurl/examples/__pycache__/sfquery.cpython-312.pycnu �[��� � N��g� � � � d dl Z d dlZd dlZ G d� dej � Zedk( �r� ee j � dk( rdZne j d Z ej � j d� Z e \ Z Z Z ed � Zej# d � ej% e e � ej' d � rEe j( j+ d eej- � � z � e j. d� yej' de z � r]ej1 e� e j2 j+ ej- � � ej5 � e j. d � ye j( j+ d eej- � � z � e j. d� yy# ee j � dk r ed e j d z � e�e j d Z e j d Z Y ���xY w)� Nc � � e Zd Zd� Zd� Zd� Zy)�SourceForgeUserSessionc �: � | j dd|fd|fdddf� y)zEstablish a login session.zaccount/login.php�form_loginname�form_pw)� return_to� )� stay_in_ssl�1)�loginzLogin With SSLN)�post)�self�name�passwords �[/opt/hc_python/lib64/python3.12/site-packages/../../../share/doc/pycurl/examples/sfquery.pyr z SourceForgeUserSession.login s1 � � � � �%�)9�4�(@�)2�H�(=�(9�(<�(C� (E� F� c �& � | j d� y)zLog out of SourceForge.zaccount/logout.phpN��get)r s r �logoutz SourceForgeUserSession.logout s � � ���%�&r c �, � | j d|z � y )Nz!export/xml_export.php?group_id=%sr )r �numids r � fetch_xmlz SourceForgeUserSession.fetch_xml s � � ���4�u�<�=r N)�__name__� __module__� __qualname__r r r � r r r r s � �F�'�>r r �__main__� �28236zsourceforge.net� z,Usage: %s <project id> <username> <password>� � zhttps://sourceforge.net/z Invalid Password or User Namez'Login/password not accepted (%d bytes) zPersonal Page For: zUnexpected page (%d bytes) )�sys�netrc�curl�Curlr r �len�argv� project_id�authenticators�authr �accountr �print� SystemExit�session� set_verbosityr �answered�stderr�write�body�exitr �stdoutr r r r �<module>r8 s� �� � � >�T�Y�Y� >� �z�� �3�8�8�}��� � ��X�X�a�[� � ��u�{�{�}�+�+�,=�>��"&� ��g�x� %�%?�@�G� ���!� � �M�M�$��!����7�8� � � ���C�c�'�,�,�.�FY�Y�Z������ � � � �/�$�6� 7����*�%� � � ���� � � �(���������� � � � ���7��G�L�L�N�8K�K�L������ �A �� � �s�x�x�=�1� � �@�3�8�8�A�;�N� O� � ��x�x��{���8�8�A�;��s �&F. �.AH PK KWi\����� � C doc/pycurl/examples/__pycache__/opensocketexception.cpython-312.pycnu �[��� � N��g] � �� � d dl Z d dlZd dlZ G d� de� Zd� Z e j � Zej ej d� de_ ej ej d� � ej � y# e j $ rRZej d e j k( r ej r eej � n ee� Y dZ[yY dZ[ydZ[ww xY w)� Nc � � e Zd Zy)�ConnectionRejectedN)�__name__� __module__� __qualname__� � �g/opt/hc_python/lib64/python3.12/site-packages/../../../share/doc/pycurl/examples/opensocketexception.pyr r s � �r r c � � t j � dk r t d� | _ t j S |\ }}}}t j |||� }|j t j t j d� |S )Ng �?z3Rejecting connection attempt in opensocket callback� ) �randomr � exception�pycurl� SOCKET_BAD�socket� setsockopt� SOL_SOCKET� SO_KEEPALIVE)�curl�purpose� curl_address�family�socktype�protocol�address�ss r � opensocketr sj � � �}�}��� �+�,a�b���� � � �*6�'�F�H�h��� � �f�h��1�A��L�L��"�"�F�$7�$7��;� �Hr zhttp://pycurl.ioc �$ � t t | |� S )N)r �c)r r s r �<lambda>r s � �Z��7�G� <r )r r r � Exceptionr r �Curlr �setopt�URLr �OPENSOCKETFUNCTION�perform�error�e�args�E_COULDNT_CONNECT�printr r r �<module>r, s� �� � � �� � � �F�K�K�M�� ������"� #��� � ���� � �<�>���I�I�K�� �|�|� ��v�v�a�y�F�,�,�,���� �a�k�k�� �a��� ���s �-A> �>C � AC�C PK KWi\��u� � ? doc/pycurl/examples/__pycache__/ssh_keyfunction.cpython-312.pycnu �[��� � N��g. � �8 � d dl Z dZ e j � Zej ej e� ej ej d� d� Zej ej d� ej ej e� ej � y)� Nzsftp://web.sourceforge.netTc �" � t j S )N)�c� KHSTAT_FINE)� known_key� found_key�matchs �c/opt/hc_python/lib64/python3.12/site-packages/../../../share/doc/pycurl/examples/ssh_keyfunction.py� keyfunctionr s � � �=�=�� z .known_hosts) �pycurl� sftp_server�Curlr �setopt�URL�VERBOSEr �SSH_KNOWNHOSTS�SSH_KEYFUNCTION�perform� r r �<module>r sv �� �*� ��F�K�K�M�� ������ � � ������D� �� ���� � �>� *� ���� � �K� (� � � � r PK KWi\��τ�� �� 7 doc/pycurl/examples/__pycache__/linksys.cpython-312.pycnu �[��� � N��g U � � � d dl Z d dlZd dlZd dlZd� Z G d� dej � Z G d� d� Zedk( red dl Z d dl Z G d� d e j � Z e � Z e j d d D ] Ze j! e� � d Zes e j% � d Zes�yyy# e$ r/ e j& � d j( \ ZZ ed ez � Y �9w xY w)� Nc � � t j j | � t j j d� y )N� )�sys�stderr�write)�args �[/opt/hc_python/lib64/python3.12/site-packages/../../../share/doc/pycurl/examples/linksys.py� print_stderrr % s& � ��J�J���S���J�J���T�� c � � e Zd Zd� Zy)� LinksysErrorc � � || _ y �N)�args)�selfr s r �__init__zLinksysError.__init__* s � ��� r N)�__name__� __module__� __qualname__r � r r r r ) s � �r r c � � e Zd ZdZdZdZdZdZdZdZ dd d d d d �Z d� Z d� Z d� Z d� Zd� Zd� Zd� Zd� Zd� Zd� Zd� Zd� Zd� Zd� Zd � Zd � Zd � Zd � Z d � Z d!� Z d"� Z d#� Z d$� Z!d%� Z"d&� Z#d'� Z$d(� Z%d)� Z&d*� Z'd+� Z(d,� Z)d-� Z*d.� Z+d/� Z,d0� Z-d1� Z.d2� Z/y3)4�LinksysSessionz/Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec�1�2�3�4�5�6zbasic setup functionszFor security reasons,z-You can configure the router to act as a DHCPz3There are some log settings and lists in this page.z5Port forwarding can be used to set up public services)� � Passwd.htmz DHCP.htmlzLog.htmlz Forward.htmc �< � g | _ d| _ d| _ i | _ y )Nzhttp://192.168.1.1F)�actions�host� verbosity� pagecache�r s r r zLinksysSession.__init__A s � ��� �(�� � �����r c � � || _ y r )r$ �r �flags r � set_verbosityz LinksysSession.set_verbosityG s � � ��r c � � || j vr�t j | j � }|j | j � |j |� |j � | j |< |j d� r t dd� �|j t j | � sD| j |= t dt j j | j |� z d� �|j � y y )N�401zauthorization failure.Tz!check string for page %s missing!F)r% �curl�Curlr# r* r$ �get�body�answeredr r � check_strings�os�path�join�close)r �page�fetchs r � cache_loadzLinksysSession.cache_loadL s� � � �t�~�~� %��I�I�d�i�i�(�E� � � ���� /� �I�I�d�O�#(�:�:�<�D�N�N�4� ��~�~�e�$�"�#;�T�B�B��^�^�N�$@�$@��$F�G��N�N�4�(�"�#F���� � �VZ�V_�V_�ae�If�#f�hm�n�n� �K�K�M� &r c � � i | _ y r )r% r& s r � cache_flushzLinksysSession.cache_flushX s � ���r c � � | j |� t j |� j | j | � }|r|j d� }|S d }|S �N� )r9 �re�compile�searchr% �group)r r7 �template�match�results r � screen_scrapez LinksysSession.screen_scrape\ sS � � ���� �� � �8�$�+�+�D�N�N�4�,@�A�� ��[�[��^�F� � � �F�� r c �, � | j d|dz � S )Nr z :[^M]*\(MAC Address: *([^)]*))rF )r r7 �prefixs r �get_MAC_addressz LinksysSession.get_MAC_addressd s � ��!�!�"�f�-M�&M�N�Nr c �~ � |r | j j ||d� y | j j ||d� y )Nr �0�r" �append)r r7 r) �values r �set_flagzLinksysSession.set_flagf s1 � � � �L�L� � ��d�C� 0� �L�L� � ��d�C� 0r c � � d}|j d� D ]5 }| j j dd|t |dz � z |f� |dz }�7 y )Nr �.r �F1r> )�splitr" rM �repr)r r7 �cgi�role�ip�ind�octets r �set_IP_addressz LinksysSession.set_IP_addressk sJ � ����X�X�c�]�E� �L�L� � ��T�4�$�s�1�u�+�+=�u� E� F� �1�H�C� #r c �N � | j ddt j z dz � S )Nr z >([0-9.v]*, (z)[^<]*)<)rF r �monthsr& s r �get_firmware_versionz#LinksysSession.get_firmware_versionr s4 � � �!�!�"�o�"0�"7�"7�'8�:D�'E� H� Hr c �& � | j dd� S )Nr zLAN IP Address�rI r& s r � get_LAN_MACzLinksysSession.get_LAN_MACx s � ��#�#�B�(9�:�:r c �& � | j dd� S )Nr �Wirelessr_ r& s r �get_Wireless_MACz LinksysSession.get_Wireless_MACz s � ��#�#�B� �4�4r c �& � | j dd� S )Nr zWAN Connection Typer_ r& s r � get_WAN_MACzLinksysSession.get_WAN_MAC| s � ��#�#�B�(>�?�?r c �@ � | j j dd|f� y )Nr �hostNamerL �r �names r � set_host_namez LinksysSession.set_host_name� s � � � � ���R��T� 2�3r c �@ � | j j dd|f� y )Nr � DomainNamerL rh s r �set_domain_namez LinksysSession.set_domain_name� s � � � � ���R� �t� 4�5r c �* � | j dd|� y )Nr �ipAddr�rZ �r rW s r � set_LAN_IPzLinksysSession.set_LAN_IP� s � � ���B��"�-r c � � |j d� st �|j d� d }|dvrt �| j j dd|� y )Nz 255.255.255.rQ ���)rK �128�192�240�252r �netMask)� startswith� ValueErrorrS r" rM )r rW �lastquads r �set_LAN_netmaskz LinksysSession.set_LAN_netmask� sK � ��}�}�^�,� � ��8�8�C�=��$�� �<� <� � � � � ���B� �8�4r c �( � | j dd� y )Nr �wirelessStatus�rO r( s r � set_wirelesszLinksysSession.set_wireless� s � � � � �b�*�+r c �@ � | j j dd|f� y )Nr � wirelessESSIDrL )r �ssids r �set_SSIDzLinksysSession.set_SSID� s � � � � ���R� �$� 7�8r c �( � | j dd� y )Nr � broadcastSSIDr� r( s r �set_SSID_broadcastz!LinksysSession.set_SSID_broadcast� s � � � � �b�/�*r c �@ � | j j dd|f� y )Nr �wirelessChannelrL )r �channels r � set_channelzLinksysSession.set_channel� s � � � � ���R�!2�G� <�=r c �( � | j dd� y )Nr �WepTyper� r( s r �set_WEPzLinksysSession.set_WEP� s � � � � �b�)�$r c �@ � | j j dd|f� y )Nr �WANConnectionTyperL )r �types r �set_connection_typez"LinksysSession.set_connection_type� s � � � � ���R�!4�d� ;�<r c �* � | j dd|� y )Nr �aliasIPrp rq s r � set_WAN_IPzLinksysSession.set_WAN_IP� s � � ���B� �2�.r c �* � | j dd|� y )Nr � aliasMaskIPrp rq s r �set_WAN_netmaskz LinksysSession.set_WAN_netmask� s � � ���B� �r�2r c �* � | j dd|� y )Nr �routerIPrp rq s r �set_WAN_gateway_addressz&LinksysSession.set_WAN_gateway_address� s � � ���B� �B�/r c �6 � | j ddd| z |� y )Nr �dns�ABCrp �r �indexrW s r �set_DNS_serverz LinksysSession.set_DNS_server� s � � ���B���e� � 4�b�9r c �x � | j j dd|� | j j dd|� y )Nr � sysPasswd�sysPasswdConfirmrL )r �strs r � set_passwordzLinksysSession.set_password� s/ � � � � ���L��c�:� � � ���L�);�S�Ar c �( � | j dd� y )Nr � UPnP_Workr� r( s r �set_UPnPzLinksysSession.set_UPnP� s � � � � �l�K�0r c �< � | j j dd� y )Nr �FactoryDefaultsrL r& s r �resetzLinksysSession.reset� s � � � � ���L�*;�<r c �~ � |r | j j ddd� y | j j ddd� y )N�DHCP.htm� dhcpStatus�Enable�DisablerL r( s r �set_DHCPzLinksysSession.set_DHCP� s1 � � � �L�L� � � �<�� A� �L�L� � � �<� � Br c �P � | j j ddt |� � y )Nr� �dhcpS4�r" rM r� �r �vals r �set_DHCP_starting_IPz#LinksysSession.set_DHCP_starting_IP� s � � � � ���J�x��S��:r c �P � | j j ddt |� � y )Nr� �dhcpLenr� r� s r �set_DHCP_usersz LinksysSession.set_DHCP_users� s � � � � ���J�y�#�c�(�;r c �P � | j j ddt |� � y )Nr� � leaseTimer� r� s r �set_DHCP_lease_timez"LinksysSession.set_DHCP_lease_time� � � � � � ���J�{�C��H�=r c �6 � | j ddd| z |� y )Nr� r� r� rp r� s r �set_DHCP_DNS_serverz"LinksysSession.set_DHCP_DNS_server� s � � ���J���e� �(<�b�Ar c �~ � |r | j j ddd� y | j j ddd� y )NzLog.htm�rLogr� r� rL r( s r � set_loggingzLinksysSession.set_logging� s1 � � � �L�L� � � �6�8� <� �L�L� � � �6�9� =r c �P � | j j ddt |� � y )Nr� � trapAddr3r� r� s r �set_log_addressz LinksysSession.set_log_address� r� r c �F � | j �rg }| j � | j D ]� \ }}}| j |� | j | j |� dk( r;t d|�dt j j | j |� �d�� �t|j ||f� �� g | _ t j | j � }|j | j � |j dt! |� � |j# � yy)z+Write configuration changes to the Linksys.rt zlinksys: field z" not found where expected in page �!z Gozila.cgiN)r" r; r9 r% �findr r3 r4 r5 r# rM r- r. r* r$ r/ �tupler6 )r �fieldsr7 �fieldrN � transactions r � configurezLinksysSession.configure� s� � � �<�<��F� � � � �(,� � �$��u�e�����%��>�>�$�'�,�,�U�3�r�9� �]b�df�dk�dk�dp�dp�qu�qz�qz� }A� eB� "C� D� ��M�M�5�%�.�1� )5� �D�L� �)�)�D�I�I�.�K� � %� %�d�n�n� 5� �O�O�L�%��-� 8� � � � �! r N)0r r r r\ �WAN_CONNECT_AUTO�WAN_CONNECT_STATIC�WAN_CONNECT_PPOE�WAN_CONNECT_RAS�WAN_CONNECT_PPTP�WAN_CONNECT_HEARTBEATr2 r r* r9 r; rF rI rO rZ r] r` rc re rj rm rr r} r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r� r r r r r - s � � >�F��� �����O��� �� .�-�E�K�M� �M� � � � ��O�1� �H� ;�5�@�4�6�.�5�,�9�+�>�%�=�/�3�0�:�B�1�=�C� ;�<�>�B� >� >� r r �__main__c �� � e Zd ZdZd� Zd� Zd� Zd� Zd� Zd� Z d� Z d � Z d � Z d � Z d � Zd � Zd� Zd� Zd� Zd� Zd� Zd� Zd� Zd� Zd� Zd� Zd� Zd� Zd� Z d� Z d � Z d � Z d � Z d � Z!d � Z"d!� Z#d"� Z$d#� Z%d$� Z&d%� Z'd&� Z(d'� Z)d(� Z*d)� Z+d*� Z,d+� Z-d,� Z.d-� Z/d.� Z0d/� Z1d0� Z2d1� Z3d2� Z4d3� Z5d4� Z6d5� Z7d6� Z8d7� Z9d8� Z:d9� Z;d:� Z<d;� Z=d<� Z>d=� Z?d>� Z@d?� ZAd@� ZBdA� ZCdB� ZDdC� ZEdD� ZFdE� ZGdF� ZHdG� ZIdH� ZJdI� ZKdJ� ZLyK)L�LinksysInterpreterz:Interpret commands to perform LinkSys programming actions.c � � t j j | � t � | _ t j d� r*t d� | j j dz | _ y d| _ t d� y )Nr zType ? or `help' for help.�: r �Bar1) �cmd�Cmdr r �sessionr3 �isatty�printr# �promptr& s r r zLinksysInterpreter.__init__� sV � � �G�G� � �T� "�)�+�D�L��y�y��|��2�3� "�l�l� /� /�$� 6�� � �� ��f� r c � � |j � dv r |d� y|j � dv r |d� yt d� y)N)�on�enable�yesT)�off�disable�noFz linksys: unknown switch valuer )�stripr )r �func�lines r � flag_commandz LinksysInterpreter.flag_command� sH � ��z�z�|� 6�6��T� � � ��� �!9�9��U� � � � <�=�r c � � |j � }|rJ|| j _ | j j � | j j dz | _ yt | j j � y)Nr� r )r� r� r# r; r� r� )r r� �newhosts r � do_connectz LinksysInterpreter.do_connect� s^ � ��j�j�l�G��$+�� � �!�� � �(�(�*� "�l�l� /� /�$� 6�� � � �d�l�l�'�'�(�r c �F � t d� t d� t d� y )Nz!Usage: connect [<hostname-or-IP>]z+Connect to a Linksys by name or IP address.z0If no argument is given, print the current host.�r� r& s r � help_connectz LinksysInterpreter.help_connect� s � � �5� 6� �?� @� �D� Er c � � | j j d� d| j j v r�t d| j j � � t d| j j � � t d| j j � � t d| j j � � t d� y)Nr z Firmware:zLAN MAC:z Wireless MAC:zWAN MAC:rQ r )r� r9 r% r� r] r` rc re �r r� s r � do_statusz LinksysInterpreter.do_status s� � � �L�L� #� #�B� '��T�\�\�+�+�+��k�4�<�<�#D�#D�#F�G��j�$�,�,�":�":�"<�=��o�t�|�|�'D�'D�'F�G��j�$�,�,�":�":�"<�=��c� �r c �\ � t d� t d� t d� t d� y )Nz Usage: statusz3The status command shows the status of the Linksys.z2It is mainly useful as a sanity check to make surez the box is responding correctly.r� r& s r � help_statusz LinksysInterpreter.help_status s% � � �/� "� �G� H� �F� G� �4� 5r c �P � | j | j j |� y r )r� r� r* r� s r � do_verbosez LinksysInterpreter.do_verbose s � � � � �d�l�l� 8� 8�$� ?r c �0 � t d� t d� y )Nz-Usage: verbose {on|off|enable|disable|yes|no}z!Enables display of HTTP requests.r� r& s r � help_verbosez LinksysInterpreter.help_verbose s � � �A� B� �5� 6r c �: � | j j |� y�Nr )r� rj r� s r �do_hostzLinksysInterpreter.do_host s � � �L�L� &� &�t� ,�r c �0 � t d� t d� y )NzUsage: host <hostname>z-Sets the Host field to be queried by the ISP.r� r& s r � help_hostz LinksysInterpreter.help_host s � � �*� +� �A� Br c �P � t d� | j j |� y)NzUsage: host <domainname>r )r� r� rm r� s r � do_domainz LinksysInterpreter.do_domain s � � �,� -� �L�L� (� (�� .�r c � � t d� y )Nz/Sets the Domain field to be queried by the ISP.r� r& s r � help_domainz LinksysInterpreter.help_domain# s � � �C� Dr c �: � | j j |� yr� )r� rr r� s r �do_lan_addressz!LinksysInterpreter.do_lan_address& � � � �L�L� #� #�D� )�r c �0 � t d� t d� y )Nz Usage: lan_address <ip-address>zSets the LAN IP address.r� r& s r �help_lan_addressz#LinksysInterpreter.help_lan_address) � � � �3� 4� �,� -r c �: � | j j |� yr� )r� r} r� s r �do_lan_netmaskz!LinksysInterpreter.do_lan_netmask- � � � �L�L� (� (�� .�r c �0 � t d� t d� y )Nz Usage: lan_netmask <ip-mask>� Sets the LAN subnetwork mask.r� r& s r �help_lan_netmaskz#LinksysInterpreter.help_lan_netmask0 � � � �0� 1� �1� 2r c �P � | j | j j |� yr� )r� r� r� r� s r � do_wirelessz LinksysInterpreter.do_wireless4 s � � � � �d�l�l� 7� 7�� >�r c �0 � t d� t d� y )Nz.Usage: wireless {on|off|enable|disable|yes|no}z.Switch to enable or disable wireless features.r� r& s r � help_wirelessz LinksysInterpreter.help_wireless7 s � � �B� C� �B� Cr c �: � | j j |� yr� )r� r� r� s r �do_ssidzLinksysInterpreter.do_ssid; s � � �L�L� !� !�$� '�r c �0 � t d� t d� y )NzUsage: ssid <string>z.Sets the SSID used to control wireless access.r� r& s r � help_ssidz LinksysInterpreter.help_ssid> s � � �(� )� �B� Cr c �P � | j | j j |� yr� )r� r� r� r� s r �do_ssid_broadcastz$LinksysInterpreter.do_ssid_broadcastB s � � � � �d�l�l� =� =�t� D�r c �0 � t d� t d� y )Nz4Usage: ssid_broadcast {on|off|enable|disable|yes|no}z+Switch to enable or disable SSID broadcast.r� r& s r �help_ssid_broadcastz&LinksysInterpreter.help_ssid_broadcastE s � � �H� I� �?� @r c �: � | j j |� yr� )r� r� r� s r � do_channelz LinksysInterpreter.do_channelI s � � �L�L� $� $�T� *�r c �0 � t d� t d� y )NzUsage: channel <number>zSets the wireless channel.r� r& s r � help_channelz LinksysInterpreter.help_channelL s � � �+� ,� �.� /r c �P � | j | j j |� yr� )r� r� r� r� s r �do_wepzLinksysInterpreter.do_wepP s � � � � �d�l�l� 2� 2�D� 9�r c �0 � t d� t d� y )Nz)Usage: wep {on|off|enable|disable|yes|no}z)Switch to enable or disable WEP security.r� r& s r �help_wepzLinksysInterpreter.help_wepS s � � �=� >� �=� >r c �� � t d|j � j � z � }| j j |� y# t $ r t d� Y yw xY w)NzLinksysSession.WAN_CONNECT_z!linksys: unknown connection type.r )�evalr� �upperr� r� r{ r )r r� r� s r � do_wan_typez LinksysInterpreter.do_wan_typeW s] � � B��7�� � � �8J�8J�8L�L�M��� � �0�0��6� �� � B� � @�A�� B�s �AA �A � A c �0 � t d� t d� y )Nz5Usage: wan_type {auto|static|ppoe|ras|pptp|heartbeat}z Set the WAN connection type.r� r& s r � help_wan_typez LinksysInterpreter.help_wan_type^ s � � �I� J� �0� 1r c �: � | j j |� yr� )r� r� r� s r �do_wan_addressz!LinksysInterpreter.do_wan_addressb r r c �0 � t d� t d� y )Nz Usage: wan_address <ip-address>zSets the WAN IP address.r� r& s r �help_wan_addressz#LinksysInterpreter.help_wan_addresse r r c �: � | j j |� yr� )r� r� r� s r �do_wan_netmaskz!LinksysInterpreter.do_wan_netmaski r r c �0 � t d� t d� y )Nz Usage: wan_netmask <ip-mask>z Sets the WAN subnetwork mask.r� r& s r �help_wan_netmaskz#LinksysInterpreter.help_wan_netmaskl r r c �: � | j j |� yr� )r� �set_WAN_gatewayr� s r �do_wan_gatewayz!LinksysInterpreter.do_wan_gatewayp r r c �0 � t d� t d� y )Nz Usage: wan_gateway <ip-address>r r� r& s r �help_wan_gatewayz#LinksysInterpreter.help_wan_gateways s � � �3� 4� �1� 2r c � � |j � \ }}|dv r&| j j t |� |� yt d� y�N)r r r z$linksys: server index out of bounds.r )rS r� r� r( r �r r� r� �addresss r �do_dnszLinksysInterpreter.do_dnsw sE � � #�z�z�|� �U�G���'�� � �+�+�D��K��A� � � C�D�r c �0 � t d� t d� y )Nz Usage: dns {1|2|3} <ip-mask>z:Sets a primary, secondary, or tertiary DNS server address.r� r& s r �help_dnszLinksysInterpreter.help_dns~ s � � �0� 1� �N� Or c �: � | j j |� yr� )r� r� r� s r � do_passwordz LinksysInterpreter.do_password� s � � �L�L� %� %�d� +�r c �0 � t d� t d� y )NzUsage: password <string>zSets the router password.r� r& s r � help_passwordz LinksysInterpreter.help_password� s � � �,� -� �-� .r c �P � | j | j j |� yr� )r� r� r� r� s r �do_upnpzLinksysInterpreter.do_upnp� s � � � � �d�l�l� 3� 3�T� :�r c �0 � t d� t d� y )Nz*Usage: upnp {on|off|enable|disable|yes|no}z4Switch to enable or disable Universal Plug and Play.r� r& s r � help_upnpz LinksysInterpreter.help_upnp� s � � �>� ?� �H� Ir c �8 � | j j � y r )r� r� r� s r �do_resetzLinksysInterpreter.do_reset� s � � �L�L� � � r c �0 � t d� t d� y )Nz Usage: resetz+Reset Linksys settings to factory defaults.r� r& s r � help_resetz LinksysInterpreter.help_reset� s � � �.� !� �?� @r c �P � | j | j j |� y r )r� r� r� r� s r �do_dhcpzLinksysInterpreter.do_dhcp� s � � � � �d�l�l� 3� 3�T� :r c �0 � t d� t d� y )Nz*Usage: dhcp {on|off|enable|disable|yes|no}z*Switch to enable or disable DHCP features.r� r& s r � help_dhcpz LinksysInterpreter.help_dhcp� s � � �>� ?� �>� ?r c �: � | j j |� y r )r� r� r� s r � do_dhcp_startz LinksysInterpreter.do_dhcp_start� s � � �L�L� -� -�d� 3r c �0 � t d� t d� y )NzUsage: dhcp_start <number>z'Set the start address of the DHCP pool.r� r& s r �help_dhcp_startz"LinksysInterpreter.help_dhcp_start� s � � �.� /� �;� <r c �: � | j j |� y r )r� r� r� s r � do_dhcp_usersz LinksysInterpreter.do_dhcp_users� � � � �L�L� '� '�� -r c �0 � t d� t d� y )NzUsage: dhcp_users <number>�9Set number of address slots to allocate in the DHCP pool.r� r& s r �help_dhcp_usersz"LinksysInterpreter.help_dhcp_users� � � � �.� /� �M� Nr c �: � | j j |� y r )r� �set_DHCP_leaser� s r � do_dhcp_leasez LinksysInterpreter.do_dhcp_lease� rW r c �0 � t d� t d� y )NzUsage: dhcp_lease <number>rY r� r& s r �help_dhcp_leasez"LinksysInterpreter.help_dhcp_lease� r[ r c � � |j � \ }}|dv r&| j j t |� |� yt d� yr; )rS r� r� r( r r< s r � do_dhcp_dnsz LinksysInterpreter.do_dhcp_dns� sE � � #�z�z�|� �U�G���'�� � �0�0��e��g�F� � � C�D�r c �0 � t d� t d� y )Nz!Usage: dhcp_dns {1|2|3} <ip-mask>z8Sets primary, secondary, or tertiary DNS server address.r� r& s r � help_dhcp_dnsz LinksysInterpreter.help_dhcp_dns� s � � �5� 6� �L� Mr c �P � | j | j j |� y r )r� r� r� r� s r � do_loggingz LinksysInterpreter.do_logging� s � � � � �d�l�l� 6� 6�� =r c �0 � t d� t d� y )Nz-Usage: logging {on|off|enable|disable|yes|no}z,Switch to enable or disable session logging.r� r& s r � help_loggingz LinksysInterpreter.help_logging� s � � �A� B� �@� Ar c �: � | j j |� y r )r� �set_Log_addressr� s r �do_log_addressz!LinksysInterpreter.do_log_address� s � � �L�L� (� (�� .r c �0 � t d� t d� y )NzUsage: log_address <number>z1Set the last quad of the address to which to log.r� r& s r �help_log_addressz#LinksysInterpreter.help_log_address� s � � �/� 0� �E� Fr c �8 � | j j � yr� )r� r� r� s r � do_configurez LinksysInterpreter.do_configure� s � � �L�L� "� "� $�r c �0 � t d� t d� y )NzUsage: configurez(Writes the configuration to the Linksys.r� r& s r �help_configurez!LinksysInterpreter.help_configure� s � � �$� %� �<� =r c �B � t | j j � y r )r� r� r% r� s r �do_cachezLinksysInterpreter.do_cache� s � � �$�,�,�(�(� )r c �0 � t d� t d� y )Nz Usage: cachezDisplay the page cache.r� r& s r � help_cachez LinksysInterpreter.help_cache� s � � �.� !� �+� ,r c � � yr= r r� s r �do_quitzLinksysInterpreter.do_quit� s � �r c �0 � t d� t d� y )Nz2The quit command ends your linksys session withoutz-writing configuration changes to the Linksys.r� r� s r � help_quitz LinksysInterpreter.help_quit� s � � �F� G� �A� Br c �N � t d� | j j � y)Nr r> )r� r� r� r� s r �do_EOFzLinksysInterpreter.do_EOF� s � � �"�I� �L�L� "� "� $�r c �0 � t d� t d� y )Nz7The EOF command writes the configuration to the linksyszand ends your session.r� r& s r �help_EOFzLinksysInterpreter.help_EOF� s � � �K� L� �*� +r c �. � t j |� y)z5Pass the command through to be executed by the shell.r )r3 �systemr� s r �defaultzLinksysInterpreter.default� s � � �I�I�d�O�r c �0 � t d� t d� y )Nz/On-line help is available through this command.z"? is a convenience alias for help.r� r& s r � help_helpz LinksysInterpreter.help_help� s � � �C� D� �6� 7r c � � t d� y )Na� This program supports changing the settings on Linksys blue-box routers. This capability may come in handy when they freeze up and have to be reset. Though it can be used interactively (and will command-prompt when standard input is a terminal) it is really designed to be used in batch mode. Commands are taken from the command line first, then standard input. By default, it is assumed that the Linksys is at http://192.168.1.1, the default LAN address. You can connect to a different address or IP with the 'connect' command. Note that your .netrc must contain correct user/password credentials for the router. The entry corresponding to the defaults is: machine 192.168.1.1 login "" password admin Most commands queue up changes but don't actually send them to the Linksys. You can force pending changes to be written with 'configure'. Otherwise, they will be shipped to the Linksys at the end of session (e.g. when the program running in batch mode encounters end-of-file or you type a control-D). If you end the session with `quit', pending changes will be discarded. For more help, read the topics 'wan', 'lan', and 'wireless'.r� r& s r �help_introductionz$LinksysInterpreter.help_introduction� s � � � @� Ar c � � t d� y )Nz�The `lan_address' and `lan_netmask' commands let you set the IP location of the Linksys on your LAN, or inside. Normally you'll want to leave these untouched.r� r& s r �help_lanzLinksysInterpreter.help_lan s � � � � r c � � t d� y )Na{ The WAN commands become significant if you are using the BEFSR41 or any of the other Linksys boxes designed as DSL or cable-modem gateways. You will need to use `wan_type' to declare how you expect to get your address. If your ISP has issued you a static address, you'll need to use the `wan_address', `wan_netmask', and `wan_gateway' commands to set the address of the router as seen from the WAN, the outside. In this case you will also need to use the `dns' command to declare which remote servers your DNS requests should be forwarded to. Some ISPs may require you to set host and domain for use with dynamic-address allocation.r� r& s r �help_wanzLinksysInterpreter.help_wan s � � � � r c � � t d� y )NzWThe channel, ssid, ssid_broadcast, wep, and wireless commands control wireless routing.r� r& s r �help_wireless_descz%LinksysInterpreter.help_wireless_desc s � � � � r c �F � t d� t d� t d� y )Nz8Switches may be turned on with 'on', 'enable', or 'yes'.z:Switches may be turned off with 'off', 'disable', or 'no'.z2Switch commands include: wireless, ssid_broadcast.r� r& s r � help_switchesz LinksysInterpreter.help_switches s � � �L� M� �N� O� �F� Gr c �F � t d� t d� t d� y )Nz/An address argument must be a valid IP address;z-four decimal numbers separated by dots, each zbetween 0 and 255.r� r& s r �help_addressesz!LinksysInterpreter.help_addresses! s � � �C� D� �A� B� �&� 'r c � � y r r r& s r � emptylinez LinksysInterpreter.emptyline& s � � r N)Mr r r �__doc__r r� r� r� r� r� r� r� r� r r r r r r r r r r r r r r r" r$ r& r* r, r. r0 r2 r4 r7 r9 r> r@ rB rD rF rH rJ rL rN rP rR rT rV rZ r^ r` rb rd rf rh rk rm ro rq rs ru rw ry r{ r} r� r� r� r� r� r� r� r� r� r r r r� r� � s� � �H� � � � F� � 6� @� 7� � C� � E� � .� � 3� � D� � D� � A� � 0� � ?� � 2� � .� � 3� � 3� � P� � /� � J� !� A� ;� @� 4� =� .� O� .� O� � N� >� B� /� G� � >� *� -� � C� � ,� � 8� A�4 � � � H� (� r r� r> FTz linksys: )r r? r- � exceptionsr � Exceptionr r r r3 r� r� r� � interpreter�argvr �onecmd�fatal�cmdloop�exc_infor �messager� r r r �<module>r� s� ��F !� ���:�'�'� �n � n �` �z���G�S�W�W� G�R %�&�K��x�x���|�����3� � � �E�� )� � � � !��E� �a ��h � )� )�S�\�\�^�A� .� 3� 3�N�G�U� �+��'� (� )�s �B � 1C�CPK KWi\�^ d� � 9 doc/pycurl/examples/__pycache__/retriever.cpython-312.pycnu �[��� � N��gi � �D � d dl Z d dlZ d dlZd dlZ d dlZd dlmZmZ ej ee� dZ e j d dk( re j j � Z n# ee j d � j � Z ee j � dk\ r ee j d � Z ej � Ze D ]H Zej) � Zered d k( r� d eej � dz z Zej- eef� �J ej sJ d � � eej � Z ee e� Z de cxk r d k sJ d � � J d � � edej2 ej4 fz � edede d� G d� dej6 � Z g Z e e � D ]+ Z e e� Z e jC � e jE e � �- e D ] Z#e#jI � � y# e$ r d dlZY ���w xY w# e$ r Y ���w xY w# ede j d z � e�xY w)� N)�SIGPIPE�SIG_IGN� � �-� � zCUsage: %s <file with URLs to fetch> [<# of concurrent connections>]�#z doc_%03d.datz no URLs giveni' z(invalid number of concurrent connectionsz!PycURL %s (compiled against 0x%x)z ----- Gettingz URLs usingzconnections -----c � � e Zd Zd� Zd� Zy)� WorkerThreadc �P � t j j | � || _ y )N)� threading�Thread�__init__�queue)�selfr s �]/opt/hc_python/lib64/python3.12/site-packages/../../../share/doc/pycurl/examples/retriever.pyr zWorkerThread.__init__> s � ����!�!�$�'��� � c �� � | j j � \ }}t |d� }t j � }|j t j |� |j t j d� |j t j d� |j t j d� |j t j d� |j t j d� |j t j |� |j! � |j- � |j- � t& j. j1 d� t& j. j+ � ���# t j $ r t �w xY w# dd l}|j% t& j( �� t& j( j+ � Y ��xY w) Nr �wb� � i, r )�file�.)r � get_nowait�Queue�Empty� SystemExit�open�pycurl�Curl�setopt�URL�FOLLOWLOCATION� MAXREDIRS�CONNECTTIMEOUT�TIMEOUT�NOSIGNAL� WRITEDATA�perform� traceback� print_exc�sys�stderr�flush�close�stdout�write)r �url�filename�fp�curlr+ s r �runzWorkerThread.runB sQ � �� !� $� � � 5� 5� 7� ��X� �h��%�B��;�;�=�D� �K�K�� � �C� (� �K�K��-�-�q� 1� �K�K��(�(�!� ,� �K�K��-�-�r� 2� �K�K����� ,� �K�K����� +� �K�K��(�(�"� -� #�� � �� �J�J�L� �H�H�J� �J�J� � �S� !� �J�J� � � �/ �� �;�;� !� � � !�� #� ��#�#����#�4�� � � � �"�s � F �!F- �F*�-AG3N)�__name__� __module__� __qualname__r r7 � r r r r = s � �� r r )%r- r r � ImportErrorr r �signalr r �num_conn�argv�stdin� readlines�urlsr �len�int�printr r3 �stripr4 �put�num_urls�min�version�COMPILE_LIBCURL_VERSION_NUMr r �threads�range�dummy�t�start�append�thread�joinr; r r �<module>rT s& �� ��� �$��'� �F�M�M�'�7�#� �� � �x�x��{�c���y�y�"�"�$���C�H�H�Q�K� �*�*�,�� �3�8�8�}����s�x�x��{�#�� �� � � �� �C� �)�)�+�C� �#�a�&�C�-�� ��U�[�[�!1�A�!5�6�H� �I�I�s�H�o� � � �{�{� #�O� #�{� �u�{�{� �� �x�� "���H� �� � I� I� I� � I� I� I� � �)�V�^�^�V�=_�=_�,`�`� a� �o�x� �x�9L� M� �9�#�#� �B �� �8�_�E��U��A��G�G�I� �N�N�1�� � �F� �K�K�M� ��s � ���� � �� �� � � O�RU�RZ�RZ�[\�R]� ]�^� ��s. �G' � G7 �A:H �' G4�3G4�7H �?H � H PK KWi\��� � ; doc/pycurl/examples/__pycache__/file_upload.cpython-312.pycnu �[��� � N��g� � �� � d dl Z d dlZd dlZ G d� d� Z eej � dk r edej d z � e�ej d Zej d Z e j j e � s ede z � e� ej � Z e j ej e� e j ej d� e j ej" e ee d � � j& � e j j+ e � Ze j ej. e� ed e �d e��� e j1 � e j3 � y) � Nc � � e Zd Zd� Zd� Zy)� FileReaderc � � || _ y �N)�fp)�selfr s �_/opt/hc_python/lib64/python3.12/site-packages/../../../share/doc/pycurl/examples/file_upload.py�__init__zFileReader.__init__ s � ���� c �8 � | j j |� S r )r �read)r �sizes r � read_callbackzFileReader.read_callback s � ��w�w�|�|�D�!�!r N)�__name__� __module__� __qualname__r r � r r r r s � ��"r r � z Usage: %s <url> <file to upload>� � z#Error: the file '%s' does not exist�rbzUploading file z to url )�os�sys�pycurlr �len�argv�print� SystemExit�url�filename�path�exists�Curl�c�setopt�URL�UPLOAD� READFUNCTION�openr r �getsize�filesize� INFILESIZE�perform�closer r r �<module>r/ s* �� � �"� "� �s�x�x�=�1�� � ,�s�x�x��{� :�;� �� �h�h�q�k�� �8�8�A�;�� �w�w�~�~�h� � � /�(� :�;� �� �F�K�K�M�� ������S� � ���� � �� � ��H�H�V� � �*�T�(�D�-A�"B�"P�"P�Q� �7�7�?�?�8� $�� ���� � �H� %� �x��5� 6� � � � � ��� r PK KWi\X �� � 4 doc/pycurl/examples/__pycache__/smtp.cpython-312.pycnu �[��� � N��gK � �d � d dl mZ ddlZ ddlmZ ddlZej d dkD Z dez Z dZ d Z ej � Zej ej e � ej ej" e � ej ej$ e g� d e �d e �d �Ze rej) d � Z ee� Zej ej* e� ej ej, d� ej ej. d� ej1 � y# e$ r ddlmZ Y �� w xY w)� )� localhost� N)�BytesIO)�StringIO� z smtp://%szsender@example.orgzaddressee@example.netzFrom: z To: z7 Subject: PycURL SMTP example SMTP example via PycURL �asciiT)� r �pycurl�ior � ImportErrorr �sys� version_info�PY3� mail_server� mail_from�mail_to�Curl�c�setopt�URL� MAIL_FROM� MAIL_RCPT�message�encode�READDATA�UPLOAD�VERBOSE�perform� � �X/opt/hc_python/lib64/python3.12/site-packages/../../../share/doc/pycurl/examples/smtp.py�<module>r" s �� � �-�� � ���q��A� ���I�%� � � � !���F�K�K�M�� ������ � � ������i� � ������w�i� � �'� �� ��n�n�W�%�G� �W��� ������R� � ������4� � ������D� � � � � ��K � -�,�,�-�s �D � D/�.D/PK KWi\F��m� � ; doc/pycurl/examples/__pycache__/xmlrpc_curl.cpython-312.pycnu �[��� � N��g� � �0 � d dl Z d dl mZmZ e j ee� d dlmZ d dlZd dl Z d dl Z e j d dkD Z G d� dej � Zedk( rD ej" d e� � � Z ee� eej( j+ d � � yy# e$ r Y ��w xY w# e$ r d dlmZ n# e$ r d dlmZ Y nw xY wY ��w xY w# e$ r d dlm Z Y ��w xY w# ej, $ r e j. � d Z ed e� Y yw xY w) � N)�SIGPIPE�SIG_IGN)�StringIO� c �& � e Zd ZdZdgZdd�Zdd�Zy)� CURLTransportz5Handles a cURL HTTP transaction to an XML-RPC server.zContent-Type: text/xmlNc � � t j � | _ | j j t j d� | j j t j d� | j j t j d� | j j t j | j � |d k7 r4|d k7 r/| j j t j |�d|��� d| _ y )N� � �:F) �pycurl�Curl�c�setopt�POST�NOSIGNAL�CONNECTTIMEOUT� HTTPHEADER�xmlrpc_h�USERPWD� _use_datetime)�self�username�passwords �_/opt/hc_python/lib64/python3.12/site-packages/../../../share/doc/pycurl/examples/xmlrpc_curl.py�__init__zCURLTransport.__init__% s� � ���� ��� ��� � �f�k�k�1�%� ��� � �f�o�o�q�)� ��� � �f�+�+�R�0� ��� � �f�'�'�� � �7� �t� ��D� 0� �F�F�M�M�&�.�.�X�x�*H� I� "��� c �� � t � }| j j t j d|�|��� | j j t j |� | j j t j |j � | j j t j |� || _ | j j � |j% d� | j' |� S # t j $ rK t j � d }t r |j }t! j" ||z |d |d d � �w xY w)Nzhttp://r r )r r r r �URL� POSTFIELDS� WRITEFUNCTION�write�VERBOSE�verbose�perform�error�sys�exc_info�PY3�args� xmlrpclib� ProtocolError�seek�parse_response)r �host�handler� request_bodyr$ �b�vs r �requestzCURLTransport.request/ s � � �J�� ��� � �f�j�j�4��"A�B� ��� � �f�'�'� �6� ��� � �f�*�*�A�G�G�4� ��� � �f�n�n�g�.� �� � � �6�6�>�>� � ���q� ��"�"�1�%�%�� �|�|� �� � ��q�!�A���F�F���)�)��w���!��a��d�D�� � �s � D �A E$)NN)r )�__name__� __module__� __qualname__�__doc__r r r4 � r r r r s � �?�)�+�H�#�&r r �__main__zhttp://betty.userland.com)� transport�) r �ERROR)�signalr r � ImportError� cStringIOr �ior+ � xmlrpc.client�clientr r' � version_infor) � Transportr r5 � ServerProxy�server�print�examples� getStateName�Errorr( r3 r9 r r �<module>rL s1 ��$��'� �F�M�M�'�7�#� �"� &�� � � ���q��A� ��!&�I�'�'� !&�H �z�� "�Y� "� "�#>�-:�_�>�F� �&�M�� �f�o�o�*�*�2�.�/� ��u � �� �� � � �%�� � � � �� �� � &�%�&��f �?�?� � �C�L�L�N�1� �� �g�q���si � B& �B1 �C �!C& �&B.�-B.�1C�7B>�=C�> C � C� C � C�C� C#�"C#�&,D�DPK KWi\I?(� � J doc/pycurl/examples/__pycache__/multi-socket_action-select.cpython-312.pycnu �[��� � N��g? � � � d dl Z d dlZd dlZd dlmZ ee j � dkD re j d ZndZg g dddddd�Zd� Z d� Z d� Z ej � Z e j ej e � e j ej e � ej" � Zej ej& e� ej ej( d � ej ej* d � ej ej, d� e� Zej ej0 e� e j3 e� e j5 ej6 d � Z ed d k( rned Z e � e d � � e e � �!e j? e� ejA � e jA � ed � e d� �ed r e!d eejE � � z � y e!ded ed fz � y)� N)�BytesIO� zhttps://www.python.org)�rlist�wlist�running�timeout�result�code�msgc �� � | t j k( s| t j k( rt d j |� y | t j k( s| t j k( rt d j |� y | t j k( rH|t d v rt d j |� |t d v rt d j |� y y t d| z � �)Nr r zUnknown value of what: %s) �pycurl�POLL_IN� POLL_INOUT�state�append�POLL_OUT� POLL_REMOVE�remove� Exception)�what�sock_fd�multi�socketps �n/opt/hc_python/lib64/python3.12/site-packages/../../../share/doc/pycurl/examples/multi-socket_action-select.py� socket_fnr O s� � � �v�~�~� ���):�):�!:� �g�� � �g�&� �� � � �D�F�,=�,=�$=� �g�� � �g�&� ��#�#� #� �e�G�n� $� �'�N� !� !�'� *� �e�G�n� $� �'�N� !� !�'� *� %� �3�d�:�;�;� c � � t j t d t d t t d � t t d � z | � \ }}}t |� dk( rDt |� dk( r6t |� dk( r(t j t j d� \ }}n�|D ]) }t j |t j � \ }}�+ |D ]) }t j |t j � \ }}�+ |D ]) }t j |t j � \ }}�+ t d ��t d k7 r�t j � \ }}} |dk( sJ �t |� dk( rt | � dk( s t |� dk( rt | � dk( sJ �|r dt d< | r dt d< | d \ } t d < t d < t d< y ) Nr r r r r Tr Fr r ) �selectr �set�lenr � socket_actionr �SOCKET_TIMEOUT� CSELECT_IN� CSELECT_OUT� CSELECT_ERR� info_read) r �rready�wready�xready�_r r �qmsg� successes�failures�_easys r �workr/ \ s� � � #�]�]� �g���g���E�'�N�(;�c�%��.�>Q�(Q�SZ� \��F�F�F� �6�{�a��C��K�1� ,��V���1A� �(�(��)>�)>��B� ��7� �G� �,�,�W�f�6G�6G�H�J�A�w� � �G� �,�,�W�f�6H�6H�I�J�A�w� � �G� �,�,�W�f�6H�6H�I�J�A�w� � �Y��#��5��3C�(C� %*�O�O�$5�!��i�� �q�y��y� �9�~��"�s�8�}��'9� � �N�a� �C��M�Q�$6� 7� 7� � "�E�(�O� � #�E�(�O� 2:�!�� .�E�5��=�%��,� �E�)�r c �: � | dk r d t d< y | dz t d< y )Nr r g @�@)r )� timeout_mss r �timer_fnr2 � s$ � ��A�~� ��i��%��.��i�r � r r z0Need to poll for I/O but the timeout is not set!r z!Script finished without a result!z'Transfer successful, retrieved %d bytesz Transfer failed with code %d: %sr r )#�sysr r �ior r �argv�urlr r r/ r2 � CurlMultir �setopt�M_SOCKETFUNCTION�M_TIMERFUNCTION�Curl�easy�URL�CONNECTTIMEOUT�LOW_SPEED_TIME�LOW_SPEED_LIMIT�_io� WRITEDATA� add_handler! r" �handlesr r � remove_handle�close�print�getvalue� r r �<module>rK s� ��v � � ��s�x�x�=�1�� �(�(�1�+�C� "�C� � ���� � � �� <�4 �l/� ������ � � �V� $� $�i� 0� � � �V� #� #�X� .��v�{�{�}�� � � �F�J�J�� � � � �F� !� !�1� %� � � �F� !� !�1� %� � � �F� "� "�A� &� �i�� � � �F� � �c� "� � � �� � � � �f� 3� 3�Q� 7�� � �Y��1� � � � �"�� �?�� N�O� O� �W� � � � � �D� � � � � � � � � � ��?�� �7� 8�8���?� � 3�c�#�,�,�.�6I� I�J� � ,��f� �u�U�|�/L� L�Mr PK LWi\m��F : doc/pycurl/examples/__pycache__/basicfirst.cpython-312.pycnu �[��� � N��g! � � � d dl Z d dlZe j d dkD Z G d� d� Ze j j dej z � e� Z ej � Z e j e j d� e j e j ej � e j � e j! � eej$ � y)� N� c � � e Zd Zd� Zd� Zy)�Testc �` � d| _ t r!| j j d� | _ y y )N� �ascii)�contents�PY3�encode)�selfs �^/opt/hc_python/lib64/python3.12/site-packages/../../../share/doc/pycurl/examples/basicfirst.py�__init__z Test.__init__ s' � ��� � � �M�M� 0� 0�� 9�D�M� � c �, � | j |z | _ y )N)r )r �bufs r � body_callbackzTest.body_callback s � � � � ��+�� r N)�__name__� __module__� __qualname__r r � r r r r s � �:� ,r r z Testing %s zhttps://curl.haxx.se/dev/)�sys�pycurl� version_infor r �stderr�write�version�t�Curl�c�setopt�URL� WRITEFUNCTIONr �perform�close�printr r r r �<module>r& s� �� � � ���q��A� ��,� ,� � � � � � �&�.�.�0� 1��F���F�K�K�M�� ������+� ,� ���� � �!�/�/� *� � � � � ��� � �a�j�j� r PK LWi\�8�� � " doc/pycurl/examples/xmlrpc_curl.pynu �[��� #! /usr/bin/env python # -*- coding: utf-8 -*- # vi:ts=4:et # We should ignore SIGPIPE when using pycurl.NOSIGNAL - see # the libcurl tutorial for more info. try: import signal from signal import SIGPIPE, SIG_IGN except ImportError: pass else: signal.signal(SIGPIPE, SIG_IGN) try: from cStringIO import StringIO except ImportError: try: from StringIO import StringIO except ImportError: from io import StringIO try: import xmlrpclib except ImportError: import xmlrpc.client as xmlrpclib import pycurl import sys PY3 = sys.version_info[0] > 2 class CURLTransport(xmlrpclib.Transport): """Handles a cURL HTTP transaction to an XML-RPC server.""" xmlrpc_h = [ "Content-Type: text/xml" ] def __init__(self, username=None, password=None): self.c = pycurl.Curl() self.c.setopt(pycurl.POST, 1) self.c.setopt(pycurl.NOSIGNAL, 1) self.c.setopt(pycurl.CONNECTTIMEOUT, 30) self.c.setopt(pycurl.HTTPHEADER, self.xmlrpc_h) if username != None and password != None: self.c.setopt(pycurl.USERPWD, '%s:%s' % (username, password)) self._use_datetime = False def request(self, host, handler, request_body, verbose=0): b = StringIO() self.c.setopt(pycurl.URL, 'http://%s%s' % (host, handler)) self.c.setopt(pycurl.POSTFIELDS, request_body) self.c.setopt(pycurl.WRITEFUNCTION, b.write) self.c.setopt(pycurl.VERBOSE, verbose) self.verbose = verbose try: self.c.perform() except pycurl.error: v = sys.exc_info()[1] if PY3: v = v.args raise xmlrpclib.ProtocolError( host + handler, v[0], v[1], None ) b.seek(0) return self.parse_response(b) if __name__ == "__main__": ## Test server = xmlrpclib.ServerProxy("http://betty.userland.com", transport=CURLTransport()) print(server) try: print(server.examples.getStateName(41)) except xmlrpclib.Error: v = sys.exc_info()[1] print("ERROR", v) PK LWi\ѹ�+� � " doc/pycurl/examples/file_upload.pynu �[��� #! /usr/bin/env python # -*- coding: utf-8 -*- # vi:ts=4:et import os, sys import pycurl # Class which holds a file reference and the read callback class FileReader: def __init__(self, fp): self.fp = fp def read_callback(self, size): return self.fp.read(size) # Check commandline arguments if len(sys.argv) < 3: print("Usage: %s <url> <file to upload>" % sys.argv[0]) raise SystemExit url = sys.argv[1] filename = sys.argv[2] if not os.path.exists(filename): print("Error: the file '%s' does not exist" % filename) raise SystemExit # Initialize pycurl c = pycurl.Curl() c.setopt(pycurl.URL, url) c.setopt(pycurl.UPLOAD, 1) # Two versions with the same semantics here, but the filereader version # is useful when you have to process the data which is read before returning if 1: c.setopt(pycurl.READFUNCTION, FileReader(open(filename, 'rb')).read_callback) else: c.setopt(pycurl.READFUNCTION, open(filename, 'rb').read) # Set size of file to be uploaded. filesize = os.path.getsize(filename) c.setopt(pycurl.INFILESIZE, filesize) # Start transfer print('Uploading file %s to url %s' % (filename, url)) c.perform() c.close() PK LWi\�!#�i i doc/pycurl/examples/retriever.pynu �[��� #! /usr/bin/env python # -*- coding: utf-8 -*- # vi:ts=4:et # # Usage: python retriever.py <file with URLs to fetch> [<# of # concurrent connections>] # import sys, threading try: import Queue except ImportError: import queue as Queue import pycurl # We should ignore SIGPIPE when using pycurl.NOSIGNAL - see # the libcurl tutorial for more info. try: import signal from signal import SIGPIPE, SIG_IGN except ImportError: pass else: signal.signal(SIGPIPE, SIG_IGN) # Get args num_conn = 10 try: if sys.argv[1] == "-": urls = sys.stdin.readlines() else: urls = open(sys.argv[1]).readlines() if len(sys.argv) >= 3: num_conn = int(sys.argv[2]) except: print("Usage: %s <file with URLs to fetch> [<# of concurrent connections>]" % sys.argv[0]) raise SystemExit # Make a queue with (url, filename) tuples queue = Queue.Queue() for url in urls: url = url.strip() if not url or url[0] == "#": continue filename = "doc_%03d.dat" % (len(queue.queue) + 1) queue.put((url, filename)) # Check args assert queue.queue, "no URLs given" num_urls = len(queue.queue) num_conn = min(num_conn, num_urls) assert 1 <= num_conn <= 10000, "invalid number of concurrent connections" print("PycURL %s (compiled against 0x%x)" % (pycurl.version, pycurl.COMPILE_LIBCURL_VERSION_NUM)) print("----- Getting", num_urls, "URLs using", num_conn, "connections -----") class WorkerThread(threading.Thread): def __init__(self, queue): threading.Thread.__init__(self) self.queue = queue def run(self): while 1: try: url, filename = self.queue.get_nowait() except Queue.Empty: raise SystemExit fp = open(filename, "wb") curl = pycurl.Curl() curl.setopt(pycurl.URL, url) curl.setopt(pycurl.FOLLOWLOCATION, 1) curl.setopt(pycurl.MAXREDIRS, 5) curl.setopt(pycurl.CONNECTTIMEOUT, 30) curl.setopt(pycurl.TIMEOUT, 300) curl.setopt(pycurl.NOSIGNAL, 1) curl.setopt(pycurl.WRITEDATA, fp) try: curl.perform() except: import traceback traceback.print_exc(file=sys.stderr) sys.stderr.flush() curl.close() fp.close() sys.stdout.write(".") sys.stdout.flush() # Start a bunch of threads threads = [] for dummy in range(num_conn): t = WorkerThread(queue) t.start() threads.append(t) # Wait for all threads to finish for thread in threads: thread.join() PK LWi\O�X_] ] * doc/pycurl/examples/opensocketexception.pynu �[��� # Exposing rich exception information from callbacks example import pycurl, random, socket class ConnectionRejected(Exception): pass def opensocket(curl, purpose, curl_address): if random.random() < 0.5: curl.exception = ConnectionRejected('Rejecting connection attempt in opensocket callback') return pycurl.SOCKET_BAD family, socktype, protocol, address = curl_address s = socket.socket(family, socktype, protocol) s.setsockopt(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1) return s c = pycurl.Curl() c.setopt(c.URL, 'http://pycurl.io') c.exception = None c.setopt(c.OPENSOCKETFUNCTION, lambda purpose, address: opensocket(c, purpose, address)) try: c.perform() except pycurl.error as e: if e.args[0] == pycurl.E_COULDNT_CONNECT and c.exception: print(c.exception) else: print(e) PK LWi\%�ק & doc/pycurl/examples/retriever-multi.pynu �[��� #! /usr/bin/env python # -*- coding: utf-8 -*- # vi:ts=4:et # # Usage: python retriever-multi.py <file with URLs to fetch> [<# of # concurrent connections>] # import sys import pycurl # We should ignore SIGPIPE when using pycurl.NOSIGNAL - see # the libcurl tutorial for more info. try: import signal from signal import SIGPIPE, SIG_IGN except ImportError: pass else: signal.signal(SIGPIPE, SIG_IGN) # Get args num_conn = 10 try: if sys.argv[1] == "-": urls = sys.stdin.readlines() else: urls = open(sys.argv[1]).readlines() if len(sys.argv) >= 3: num_conn = int(sys.argv[2]) except: print("Usage: %s <file with URLs to fetch> [<# of concurrent connections>]" % sys.argv[0]) raise SystemExit # Make a queue with (url, filename) tuples queue = [] for url in urls: url = url.strip() if not url or url[0] == "#": continue filename = "doc_%03d.dat" % (len(queue) + 1) queue.append((url, filename)) # Check args assert queue, "no URLs given" num_urls = len(queue) num_conn = min(num_conn, num_urls) assert 1 <= num_conn <= 10000, "invalid number of concurrent connections" print("PycURL %s (compiled against 0x%x)" % (pycurl.version, pycurl.COMPILE_LIBCURL_VERSION_NUM)) print("----- Getting", num_urls, "URLs using", num_conn, "connections -----") # Pre-allocate a list of curl objects m = pycurl.CurlMulti() m.handles = [] for i in range(num_conn): c = pycurl.Curl() c.fp = None c.setopt(pycurl.FOLLOWLOCATION, 1) c.setopt(pycurl.MAXREDIRS, 5) c.setopt(pycurl.CONNECTTIMEOUT, 30) c.setopt(pycurl.TIMEOUT, 300) c.setopt(pycurl.NOSIGNAL, 1) m.handles.append(c) # Main loop freelist = m.handles[:] num_processed = 0 while num_processed < num_urls: # If there is an url to process and a free curl object, add to multi stack while queue and freelist: url, filename = queue.pop(0) c = freelist.pop() c.fp = open(filename, "wb") c.setopt(pycurl.URL, url) c.setopt(pycurl.WRITEDATA, c.fp) m.add_handle(c) # store some info c.filename = filename c.url = url # Run the internal curl state machine for the multi stack while 1: ret, num_handles = m.perform() if ret != pycurl.E_CALL_MULTI_PERFORM: break # Check for curl objects which have terminated, and add them to the freelist while 1: num_q, ok_list, err_list = m.info_read() for c in ok_list: c.fp.close() c.fp = None m.remove_handle(c) print("Success:", c.filename, c.url, c.getinfo(pycurl.EFFECTIVE_URL)) freelist.append(c) for c, errno, errmsg in err_list: c.fp.close() c.fp = None m.remove_handle(c) print("Failed: ", c.filename, c.url, errno, errmsg) freelist.append(c) num_processed = num_processed + len(ok_list) + len(err_list) if num_q == 0: break # Currently no more I/O is pending, could do something in the meantime # (display a progress bar, etc.). # We just call select() to sleep until some more data is available. m.select(1.0) # Cleanup for c in m.handles: if c.fp is not None: c.fp.close() c.fp = None c.close() m.close() PK LWi\� � � doc/pycurl/examples/sfquery.pynu �[��� #! /usr/bin/env python # -*- coding: utf-8 -*- # vi:ts=4:et # # sfquery -- Source Forge query script using the ClientCGI high-level interface # # Retrieves a SourceForge XML export object for a given project. # Specify the *numeric* project ID. the user name, and the password, # as arguments. If you have a valid ~/.netrc entry for sourceforge.net, # you can just give the project ID. # # By Eric S. Raymond, August 2002. All rites reversed. import sys, netrc import curl class SourceForgeUserSession(curl.Curl): # SourceForge-specific methods. Sensitive to changes in site design. def login(self, name, password): "Establish a login session." self.post("account/login.php", (("form_loginname", name), ("form_pw", password), ("return_to", ""), ("stay_in_ssl", "1"), ("login", "Login With SSL"))) def logout(self): "Log out of SourceForge." self.get("account/logout.php") def fetch_xml(self, numid): self.get("export/xml_export.php?group_id=%s" % numid) if __name__ == "__main__": if len(sys.argv) == 1: project_id = '28236' # PyCurl project ID else: project_id = sys.argv[1] # Try to grab authenticators out of your .netrc try: auth = netrc.netrc().authenticators("sourceforge.net") name, account, password = auth except: if len(sys.argv) < 4: print("Usage: %s <project id> <username> <password>" % sys.argv[0]) raise SystemExit name = sys.argv[2] password = sys.argv[3] session = SourceForgeUserSession("https://sourceforge.net/") session.set_verbosity(0) session.login(name, password) # Login could fail. if session.answered("Invalid Password or User Name"): sys.stderr.write("Login/password not accepted (%d bytes)\n" % len(session.body())) sys.exit(1) # We'll see this if we get the right thing. elif session.answered("Personal Page For: " + name): session.fetch_xml(project_id) sys.stdout.write(session.body()) session.logout() sys.exit(0) # Or maybe SourceForge has changed its site design so our check strings # are no longer valid. else: sys.stderr.write("Unexpected page (%d bytes)\n"%len(session.body())) sys.exit(1) PK LWi\�p�K K doc/pycurl/examples/smtp.pynu �[��� # Based on the simple libcurl SMTP example: # https://github.com/bagder/curl/blob/master/docs/examples/smtp-mail.c # There are other SMTP examples in that directory that you may find helpful. from . import localhost import pycurl try: from io import BytesIO except ImportError: from StringIO import StringIO as BytesIO import sys PY3 = sys.version_info[0] > 2 mail_server = 'smtp://%s' % localhost mail_from = 'sender@example.org' mail_to = 'addressee@example.net' c = pycurl.Curl() c.setopt(c.URL, mail_server) c.setopt(c.MAIL_FROM, mail_from) c.setopt(c.MAIL_RCPT, [mail_to]) message = '''\ From: %s To: %s Subject: PycURL SMTP example SMTP example via PycURL ''' % (mail_from, mail_to) if PY3: message = message.encode('ascii') # libcurl does not perform buffering, therefore # we need to wrap the message string into a BytesIO or StringIO. io = BytesIO(message) c.setopt(c.READDATA, io) # If UPLOAD is not set, libcurl performs SMTP VRFY. # Setting UPLOAD to True sends a message. c.setopt(c.UPLOAD, True) # Observe SMTP conversation. c.setopt(c.VERBOSE, True) c.perform() PK LWi\�О� � 3 doc/pycurl/examples/quickstart/get_python3_https.pynu �[��� #! /usr/bin/env python # -*- coding: utf-8 -*- # vi:ts=4:et import pycurl import certifi from io import BytesIO buffer = BytesIO() c = pycurl.Curl() c.setopt(c.URL, 'http://pycurl.io/') c.setopt(c.WRITEDATA, buffer) c.setopt(c.CAINFO, certifi.where()) c.perform() c.close() body = buffer.getvalue() # Body is a byte string. # We have to know the encoding in order to print it to a text file # such as standard output. print(body.decode('iso-8859-1')) PK LWi\� b,� � - doc/pycurl/examples/quickstart/get_python2.pynu �[��� #! /usr/bin/env python # -*- coding: utf-8 -*- # vi:ts=4:et import pycurl from StringIO import StringIO buffer = StringIO() c = pycurl.Curl() c.setopt(c.URL, 'http://pycurl.io/') c.setopt(c.WRITEDATA, buffer) # For older PycURL versions: #c.setopt(c.WRITEFUNCTION, buffer.write) c.perform() c.close() body = buffer.getvalue() # Body is a string in some encoding. # In Python 2, we can print it without knowing what the encoding is. print(body) PK LWi\�ԃ+, , * doc/pycurl/examples/quickstart/put_file.pynu �[��� #! /usr/bin/env python # -*- coding: utf-8 -*- # vi:ts=4:et import pycurl c = pycurl.Curl() c.setopt(c.URL, 'https://httpbin.org/put') c.setopt(c.UPLOAD, 1) file = open(__file__) c.setopt(c.READDATA, file) c.perform() c.close() # File must be kept open while Curl object is using it file.close() PK LWi\)ى٭ � L doc/pycurl/examples/quickstart/__pycache__/get_python3_https.cpython-312.pycnu �[��� � N��g� � � � d dl Z d dlZd dlmZ e� Z e j � Zej ej d� ej ej e� ej ej ej � � ej � ej � ej � Z eej# d� � y)� N)�BytesIOzhttp://pycurl.io/z iso-8859-1)�pycurl�certifi�ior �buffer�Curl�c�setopt�URL� WRITEDATA�CAINFO�where�perform�close�getvalue�body�print�decode� � �p/opt/hc_python/lib64/python3.12/site-packages/../../../share/doc/pycurl/examples/quickstart/get_python3_https.py�<module>r s� �� � � � ����F�K�K�M�� ������#� $� ������f� � ������=�7�=�=�?� #� � � � � ��� � ����� �d�k�k�,� � r PK LWi\���_) ) D doc/pycurl/examples/quickstart/__pycache__/form_post.cpython-312.pycnu �[��� � N��g4 � �& � d dl Z d dlmZ e j � Zej ej d� ddiZ ee � Z ej ej e � ej � ej � y# e$ r d dlmZ Y ��w xY w)� N)� urlencodezhttps://httpbin.org/post�field�value)�pycurl� urllib.parser � ImportError�urllib�Curl�c�setopt�URL� post_data� postfields� POSTFIELDS�perform�close� � �h/opt/hc_python/lib64/python3.12/site-packages/../../../share/doc/pycurl/examples/quickstart/form_post.py�<module>r s� �� �!�&� �F�K�K�M�� ������*� +� �g� � � �y� !� � ���� � �z� "� � � � � ��� ��! � !� �!�s �B � B�BPK LWi\\��]| | > doc/pycurl/examples/quickstart/__pycache__/get.cpython-312.pycnu �[��� � N��gG � �j � d dl Z d dlmZ e� Z e j � Zej ej d� ej ej e� ej � ej � ej � Z eej! d� � y# e$ r d dlmZ Y ��w xY w)� N)�BytesIO)�StringIOzhttp://pycurl.io/z iso-8859-1)�pycurl�ior � ImportErrorr �buffer�Curl�c�setopt�URL� WRITEDATA�perform�close�getvalue�body�print�decode� � �b/opt/hc_python/lib64/python3.12/site-packages/../../../share/doc/pycurl/examples/quickstart/get.py�<module>r s� �� �-�� ����F�K�K�M�� ������#� $� ������f� � � � � � ��� � ����� �d�k�k�,� � ��! � -�,�-�s �B$ �$ B2�1B2PK LWi\��G�� � E doc/pycurl/examples/quickstart/__pycache__/put_buffer.cpython-312.pycnu �[��� � N��g� � �x � d dl Z d dlmZ e j � Zej ej d� ej ej d� dZ ee j d� � Z ej ej e � ej � ej � y# e$ r d dlmZ Y ��w xY w)� N)�BytesIO)�StringIOzhttps://httpbin.org/put� z {"json":true}zutf-8)�pycurl�ior � ImportErrorr �Curl�c�setopt�URL�UPLOAD�data�encode�buffer�READDATA�perform�close� � �i/opt/hc_python/lib64/python3.12/site-packages/../../../share/doc/pycurl/examples/quickstart/put_buffer.py�<module>r s� �� �-�� �F�K�K�M�� ������)� *� ������1� ��� ����W�%� &�� ������V� � � � � � ��� �� � -�,�-�s �B+ �+ B9�8B9PK LWi\y �0� � F doc/pycurl/examples/quickstart/__pycache__/get_python2.cpython-312.pycnu �[��� � N��g� � �( � d dl Z d dlmZ e� Z e j � Zej ej d� ej ej e� ej � ej � ej � Z e e � y)� N)�StringIOzhttp://pycurl.io/) �pycurlr �buffer�Curl�c�setopt�URL� WRITEDATA�perform�close�getvalue�body�print� � �j/opt/hc_python/lib64/python3.12/site-packages/../../../share/doc/pycurl/examples/quickstart/get_python2.py�<module>r so �� � � ����F�K�K�M�� ������#� $� ������f� � � � � � ��� � ����� �d� r PK LWi\R�fzp p L doc/pycurl/examples/quickstart/__pycache__/get_python2_https.cpython-312.pycnu �[��� � N��g� � � � d dl Z d dlZd dlmZ e� Z e j � Zej ej d� ej ej e� ej ej ej � � ej � ej � ej � Z ee� y)� N)�StringIOzhttp://pycurl.io/)�pycurl�certifir �buffer�Curl�c�setopt�URL� WRITEDATA�CAINFO�where�perform�close�getvalue�body�print� � �p/opt/hc_python/lib64/python3.12/site-packages/../../../share/doc/pycurl/examples/quickstart/get_python2_https.py�<module>r s� �� � � � ����F�K�K�M�� ������#� $� ������f� � ������=�7�=�=�?� #� � � � � ��� � ����� �d� r PK LWi\t��� � H doc/pycurl/examples/quickstart/__pycache__/response_info.cpython-312.pycnu �[��� � N��g� � � � d dl Z d dlmZ e� Z e j � Zej ej d� ej ej e� ej � e dej ej � z � e dej ej � z � ej! � y# e$ r d dlmZ Y ��w xY w)� N)�BytesIO)�StringIOzhttp://pycurl.io/z Status: %dzTime: %f)�pycurl�ior � ImportErrorr �buffer�Curl�c�setopt�URL� WRITEDATA�perform�print�getinfo� RESPONSE_CODE� TOTAL_TIME�close� � �l/opt/hc_python/lib64/python3.12/site-packages/../../../share/doc/pycurl/examples/quickstart/response_info.py�<module>r s� �� �-�� ����F�K�K�M�� ������#� $� ������f� � � � � � �l�Q�Y�Y�q���/�/� 0� �j�1�9�9�Q�\�\�*�*� +� ��� �� � -�,�-�s �C � C�CPK LWi\~ǞM M J doc/pycurl/examples/quickstart/__pycache__/follow_redirect.cpython-312.pycnu �[��� � N��g� � �� � d dl Z e j � Zej ej d� ej ej d� ej � ej � y)� Nzhttp://www.python.org/T)�pycurl�Curl�c�setopt�URL�FOLLOWLOCATION�perform�close� � �n/opt/hc_python/lib64/python3.12/site-packages/../../../share/doc/pycurl/examples/quickstart/follow_redirect.py�<module>r sP �� ��F�K�K�M�� ������(� )� ���� � �4� � � � � � ��� r PK LWi\g,� F doc/pycurl/examples/quickstart/__pycache__/get_python3.cpython-312.pycnu �[��� � N��g� � �F � d dl Z d dlmZ e� Z e j � Zej ej d� ej ej e� ej � ej � ej � Z e e j d� � y)� N)�BytesIOzhttp://pycurl.io/z iso-8859-1)�pycurl�ior �buffer�Curl�c�setopt�URL� WRITEDATA�perform�close�getvalue�body�print�decode� � �j/opt/hc_python/lib64/python3.12/site-packages/../../../share/doc/pycurl/examples/quickstart/get_python3.py�<module>r sw �� � � ����F�K�K�M�� ������#� $� ������f� � � � � � ��� � ����� �d�k�k�,� � r PK LWi\e%2� � K doc/pycurl/examples/quickstart/__pycache__/file_upload_real.cpython-312.pycnu �[��� � N��g# � � � d dl Z e j � Zej ej d� ej ej dej effg� ej � ej � y)� Nzhttps://httpbin.org/post� fileupload) �pycurl�Curl�c�setopt�URL�HTTPPOST� FORM_FILE�__file__�perform�close� � �o/opt/hc_python/lib64/python3.12/site-packages/../../../share/doc/pycurl/examples/quickstart/file_upload_real.py�<module>r sk �� ��F�K�K�M�� ������*� +� ������� � � �X�� �� � � � � � ��� r PK LWi\���ɴ � E doc/pycurl/examples/quickstart/__pycache__/write_file.cpython-312.pycnu �[��� � N��ge � � � d dl Z edd� 5 Z e j � Zej ej d� ej ej e� ej � ej � ddd� y# 1 sw Y yxY w)� Nzout.html�wbzhttp://pycurl.io/) �pycurl�open�f�Curl�c�setopt�URL� WRITEDATA�perform�close� � �i/opt/hc_python/lib64/python3.12/site-packages/../../../share/doc/pycurl/examples/quickstart/write_file.py�<module>r sh �� � �*�d��q��� � � �A��H�H�Q�U�U�'�(��H�H�Q�[�[�!� ��I�I�K��G�G�I� ���s �A*B�B PK LWi\�� � � K doc/pycurl/examples/quickstart/__pycache__/response_headers.cpython-312.pycnu �[��� � N��g1 � �| � d dl Z d dlZ d dlmZ i Zd� Z e� Z e j � Z e j e j d� e j e j ej � e j e j e� e j! � e j# � dZdev rDed j' � Z ej* de� Zer ej/ d� Z ed ez � e� d Z ed ez � ej3 � Z eej7 e� � y# e$ r d dlmZ Y ��*w xY w) � N)�BytesIO)�StringIOc �� � | j d� } d| vry | j dd� \ }}|j � }|j � }|j � }|t |< y )N� iso-8859-1�:� )�decode�split�strip�lower�headers)� header_line�name�values �o/opt/hc_python/lib64/python3.12/site-packages/../../../share/doc/pycurl/examples/quickstart/response_headers.py�header_functionr si � � �$�$�\�2�K� �+� �� �#�#�C��+�K�D�%� �:�:�<�D� �K�K�M�E� �:�:�<�D� �G�D�M� zhttp://pycurl.ioz content-typez charset=(\S+)r zDecoding using %sr zAssuming encoding is %s) �pycurl�re�ior � ImportErrorr r r �buffer�Curl�c�setopt�URL� WRITEFUNCTION�write�HEADERFUNCTION�perform�close�encodingr � content_type�search�match�group�print�getvalue�bodyr � r r �<module>r+ s( �� � �-�� ���8 ����F�K�K�M�� ������"� #� ���� � �&�,�,� '� ���� � �?� +� � � � � ��� � ���W� ��>�*�0�0�2�L� �B�I�I�o�|� 4�E� ��;�;�q�>�� �!�H�,�-� �� �H� � #�h� .�/� ����� �d�k�k�(�� ��w � -�,�,�-�s �D, �, D;�:D;PK LWi\ #A$4 4 Q doc/pycurl/examples/quickstart/__pycache__/file_upload_real_fancy.cpython-312.pycnu �[��� � N��g� � �, � d dl Z e j � Zej ej d� ej ej dej eej dej dffg� ej � ej � y)� Nzhttps://httpbin.org/post� fileuploadz helloworld.pyzapplication/x-python) �pycurl�Curl�c�setopt�URL�HTTPPOST� FORM_FILE�__file__� FORM_FILENAME�FORM_CONTENTTYPE�perform�close� � �u/opt/hc_python/lib64/python3.12/site-packages/../../../share/doc/pycurl/examples/quickstart/file_upload_real_fancy.py�<module>r s� �� ��F�K�K�M�� ������*� +� ������� � � �X� ��� � ��� 2� � � � � � � � � ��� r PK LWi\��Ő� � M doc/pycurl/examples/quickstart/__pycache__/file_upload_buffer.cpython-312.pycnu �[��� � N��g7 � � � d dl Z e j � Zej ej d� ej ej dej dej dffg� ej � ej � y)� Nzhttps://httpbin.org/post� fileuploadz readme.txtzThis is a fancy readme file) �pycurl�Curl�c�setopt�URL�HTTPPOST� FORM_BUFFER�FORM_BUFFERPTR�perform�close� � �q/opt/hc_python/lib64/python3.12/site-packages/../../../share/doc/pycurl/examples/quickstart/file_upload_buffer.py�<module>r sw �� ��F�K�K�M�� ������*� +� ������� � � �|� ���7�� �� � � � � � ��� r PK LWi\5�os� � C doc/pycurl/examples/quickstart/__pycache__/put_file.cpython-312.pycnu �[��� � N��g, � �F � d dl Z e j � Zej ej d� ej ej d� ee� Zej ej e� ej � ej � ej � y)� Nzhttps://httpbin.org/put� ) �pycurl�Curl�c�setopt�URL�UPLOAD�open�__file__�file�READDATA�perform�close� � �g/opt/hc_python/lib64/python3.12/site-packages/../../../share/doc/pycurl/examples/quickstart/put_file.py�<module>r sr �� ��F�K�K�M�� ������)� *� ������1� � �H�~�� ������T� � � � � � ��� � � � � r PK LWi\[�7 7 4 doc/pycurl/examples/quickstart/file_upload_buffer.pynu �[��� #! /usr/bin/env python # -*- coding: utf-8 -*- # vi:ts=4:et import pycurl c = pycurl.Curl() c.setopt(c.URL, 'https://httpbin.org/post') c.setopt(c.HTTPPOST, [ ('fileupload', ( c.FORM_BUFFER, 'readme.txt', c.FORM_BUFFERPTR, 'This is a fancy readme file', )), ]) c.perform() c.close() PK LWi\�YQ1 1 2 doc/pycurl/examples/quickstart/response_headers.pynu �[��� #! /usr/bin/env python # -*- coding: utf-8 -*- # vi:ts=4:et import pycurl import re try: from io import BytesIO except ImportError: from StringIO import StringIO as BytesIO headers = {} def header_function(header_line): # HTTP standard specifies that headers are encoded in iso-8859-1. # On Python 2, decoding step can be skipped. # On Python 3, decoding step is required. header_line = header_line.decode('iso-8859-1') # Header lines include the first status line (HTTP/1.x ...). # We are going to ignore all lines that don't have a colon in them. # This will botch headers that are split on multiple lines... if ':' not in header_line: return # Break the header line into header name and value. name, value = header_line.split(':', 1) # Remove whitespace that may be present. # Header lines include the trailing newline, and there may be whitespace # around the colon. name = name.strip() value = value.strip() # Header names are case insensitive. # Lowercase name here. name = name.lower() # Now we can actually record the header name and value. headers[name] = value buffer = BytesIO() c = pycurl.Curl() c.setopt(c.URL, 'http://pycurl.io') c.setopt(c.WRITEFUNCTION, buffer.write) # Set our header function. c.setopt(c.HEADERFUNCTION, header_function) c.perform() c.close() # Figure out what encoding was sent with the response, if any. # Check against lowercased header name. encoding = None if 'content-type' in headers: content_type = headers['content-type'].lower() match = re.search('charset=(\S+)', content_type) if match: encoding = match.group(1) print('Decoding using %s' % encoding) if encoding is None: # Default encoding for HTML is iso-8859-1. # Other content types may have different default encoding, # or in case of binary data, may have no encoding at all. encoding = 'iso-8859-1' print('Assuming encoding is %s' % encoding) body = buffer.getvalue() # Decode using the encoding we figured out. print(body.decode(encoding)) PK LWi\i%�� � / doc/pycurl/examples/quickstart/response_info.pynu �[��� #! /usr/bin/env python # -*- coding: utf-8 -*- # vi:ts=4:et import pycurl try: from io import BytesIO except ImportError: from StringIO import StringIO as BytesIO buffer = BytesIO() c = pycurl.Curl() c.setopt(c.URL, 'http://pycurl.io/') c.setopt(c.WRITEDATA, buffer) c.perform() # HTTP response code, e.g. 200. print('Status: %d' % c.getinfo(c.RESPONSE_CODE)) # Elapsed time for the transfer. print('Time: %f' % c.getinfo(c.TOTAL_TIME)) # getinfo must be called before close. c.close() PK LWi\�%� � � 3 doc/pycurl/examples/quickstart/get_python2_https.pynu �[��� #! /usr/bin/env python # -*- coding: utf-8 -*- # vi:ts=4:et import pycurl import certifi from StringIO import StringIO buffer = StringIO() c = pycurl.Curl() c.setopt(c.URL, 'http://pycurl.io/') c.setopt(c.WRITEDATA, buffer) # For older PycURL versions: #c.setopt(c.WRITEFUNCTION, buffer.write) c.setopt(c.CAINFO, certifi.where()) c.perform() c.close() body = buffer.getvalue() # Body is a string in some encoding. # In Python 2, we can print it without knowing what the encoding is. print(body) PK LWi\�� �G G % doc/pycurl/examples/quickstart/get.pynu �[��� #! /usr/bin/env python # -*- coding: utf-8 -*- # vi:ts=4:et import pycurl try: from io import BytesIO except ImportError: from StringIO import StringIO as BytesIO buffer = BytesIO() c = pycurl.Curl() c.setopt(c.URL, 'http://pycurl.io/') c.setopt(c.WRITEDATA, buffer) # For older PycURL versions: #c.setopt(c.WRITEFUNCTION, buffer.write) c.perform() c.close() body = buffer.getvalue() # Body is a string on Python 2 and a byte string on Python 3. # If we know the encoding, we can always decode the body and # end up with a Unicode string. print(body.decode('iso-8859-1')) PK LWi\WJ�A4 4 + doc/pycurl/examples/quickstart/form_post.pynu �[��� #! /usr/bin/env python # -*- coding: utf-8 -*- # vi:ts=4:et import pycurl try: # python 3 from urllib.parse import urlencode except ImportError: # python 2 from urllib import urlencode c = pycurl.Curl() c.setopt(c.URL, 'https://httpbin.org/post') post_data = {'field': 'value'} # Form data must be provided already urlencoded. postfields = urlencode(post_data) # Sets request method to POST, # Content-Type header to application/x-www-form-urlencoded # and data to send in request body. c.setopt(c.POSTFIELDS, postfields) c.perform() c.close() PK LWi\��� � - doc/pycurl/examples/quickstart/get_python3.pynu �[��� #! /usr/bin/env python # -*- coding: utf-8 -*- # vi:ts=4:et import pycurl from io import BytesIO buffer = BytesIO() c = pycurl.Curl() c.setopt(c.URL, 'http://pycurl.io/') c.setopt(c.WRITEDATA, buffer) c.perform() c.close() body = buffer.getvalue() # Body is a byte string. # We have to know the encoding in order to print it to a text file # such as standard output. print(body.decode('iso-8859-1')) PK LWi\p$�� � , doc/pycurl/examples/quickstart/put_buffer.pynu �[��� #! /usr/bin/env python # -*- coding: utf-8 -*- # vi:ts=4:et import pycurl try: from io import BytesIO except ImportError: from StringIO import StringIO as BytesIO c = pycurl.Curl() c.setopt(c.URL, 'https://httpbin.org/put') c.setopt(c.UPLOAD, 1) data = '{"json":true}' # READDATA requires an IO-like object; a string is not accepted # encode() is necessary for Python 3 buffer = BytesIO(data.encode('utf-8')) c.setopt(c.READDATA, buffer) c.perform() c.close() PK LWi\h�PW� � 8 doc/pycurl/examples/quickstart/file_upload_real_fancy.pynu �[��� #! /usr/bin/env python # -*- coding: utf-8 -*- # vi:ts=4:et import pycurl c = pycurl.Curl() c.setopt(c.URL, 'https://httpbin.org/post') c.setopt(c.HTTPPOST, [ ('fileupload', ( # upload the contents of this file c.FORM_FILE, __file__, # specify a different file name for the upload c.FORM_FILENAME, 'helloworld.py', # specify a different content type c.FORM_CONTENTTYPE, 'application/x-python', )), ]) c.perform() c.close() PK LWi\���e e , doc/pycurl/examples/quickstart/write_file.pynu �[��� #! /usr/bin/env python # -*- coding: utf-8 -*- # vi:ts=4:et import pycurl # As long as the file is opened in binary mode, both Python 2 and Python 3 # can write response body to it without decoding. with open('out.html', 'wb') as f: c = pycurl.Curl() c.setopt(c.URL, 'http://pycurl.io/') c.setopt(c.WRITEDATA, f) c.perform() c.close() PK LWi\��~,� � 1 doc/pycurl/examples/quickstart/follow_redirect.pynu �[��� #! /usr/bin/env python # -*- coding: utf-8 -*- # vi:ts=4:et import pycurl c = pycurl.Curl() # Redirects to https://www.python.org/. c.setopt(c.URL, 'http://www.python.org/') # Follow redirect. c.setopt(c.FOLLOWLOCATION, True) c.perform() c.close() PK LWi\�~(�# # 2 doc/pycurl/examples/quickstart/file_upload_real.pynu �[��� #! /usr/bin/env python # -*- coding: utf-8 -*- # vi:ts=4:et import pycurl c = pycurl.Curl() c.setopt(c.URL, 'https://httpbin.org/post') c.setopt(c.HTTPPOST, [ ('fileupload', ( # upload the contents of this file c.FORM_FILE, __file__, )), ]) c.perform() c.close() PK LWi\3���? ? 1 doc/pycurl/examples/multi-socket_action-select.pynu �[��� #! /usr/bin/env python # -*- coding: utf-8 -*- # vi:ts=4:et # Retrieves a single URL using the CurlMulti.socket_action calls, using # select as the I/O polling mechanism: # # First, create a Multi object, and set socket and timer callbacks on it. # Observed side effect: this causes the timer callback to be immediately # invoked with the zero value for the timeout. # # The timer callback is very simple - it stores the timeout value passed # into it in the global state for future use by the select calls that # we will be making. # # The socket callback is more complicated. Its job is to add and remove # socket handles to/from the data structure that we use for waiting for # activity on them. The callback is invoked with a socket handle and the # needed action (add for reading, add for writing or remove). # Since this script utilizes the select call for waiting for activity, # the socket callback updates the list of sockets which we should be # polling for readability and the list that we should be polling for # writability, which are then passed to the select call (and both of the # sets are passed as the sockets to wait for errors/exceptions on). # # Next, create a Curl object (mapping to a libcurl easy handle), set the URL # we are going to retrieve as well as any transfer options. This script sets # the timeout to 5 seconds to be able to test failing transfers easily. # # Add the Curl object to the Multi object. # # Invoke Multi.socket_action to start the retrieval operation. # Observed side effect: this causes the timer callback to be invoked # with a greater than zero value for the timeout. # # By now we should have initialized our own state, which this script does # prior to invoking any libcurl functions. Importantly, the state includes # the timeout value that was communicated to us by libcurl. # # Run a loop which waits for activity on any of the sockets used by libcurl. # The sockets are set that the socket callback has produced as of the # present moment; the timeout is the most recent timeout value received by # the timer callback. # # Importantly, the loop should not simply sleep for the entire # timeout interval, as that would cause the transfer to take a very long time. # It is *required* to use something like a select call to wait for activity # on any of the sockets currently active for *up to* the timeout value. # # The loop terminates when the number of active transfers (handles in libcurl # parlance) reaches zero. This number is provided by each socket_action # call, which is why each call (even the ones that are called due to # timeout being reached, as opposed to any socket activity) must update # the number of running handles. # # After the loop terminates, clean up everything: remove the easy object from # the multi object, close the easy object, close the multi object. import sys, select import pycurl from io import BytesIO if len(sys.argv) > 1: url = sys.argv[1] else: url = 'https://www.python.org' state = { 'rlist': [], 'wlist': [], 'running': None, 'timeout': None, 'result': None, # If the transfer failed, code and msg will be filled in. 'code': None, 'msg': None, } def socket_fn(what, sock_fd, multi, socketp): if what == pycurl.POLL_IN or what == pycurl.POLL_INOUT: state['rlist'].append(sock_fd) elif what == pycurl.POLL_OUT or what == pycurl.POLL_INOUT: state['wlist'].append(sock_fd) elif what == pycurl.POLL_REMOVE: if sock_fd in state['rlist']: state['rlist'].remove(sock_fd) if sock_fd in state['wlist']: state['wlist'].remove(sock_fd) else: raise Exception("Unknown value of what: %s" % what) def work(timeout): rready, wready, xready = select.select( state['rlist'], state['wlist'], set(state['rlist']) | set(state['wlist']), timeout) if len(rready) == 0 and len(wready) == 0 and len(xready) == 0: # The number of running handles must be updated after each # call to socket_action, which includes those with the SOCKET_TIMEOUT # argument (otherwise e.g. a transfer which failed due to # exceeding the connection timeout would hang). _, running = multi.socket_action(pycurl.SOCKET_TIMEOUT, 0) else: for sock_fd in rready: # socket_action returns a tuple whose first element is always the # CURLE_OK value (0), ignore it and use the second element only. _, running = multi.socket_action(sock_fd, pycurl.CSELECT_IN) for sock_fd in wready: _, running = multi.socket_action(sock_fd, pycurl.CSELECT_OUT) for sock_fd in xready: _, running = multi.socket_action(sock_fd, pycurl.CSELECT_ERR) # Since we are only performing a single transfer, we could call # Multi.info_read after the I/O loop terminates. # In practice, you would probably use socket_action with multiple # transfers, and you may want to be notified about transfer completion # as soon as the result is available. if state['running'] is not None and running != state['running']: # Some handle has completed. # # Note that socket_action was potentially called multiple times # in this function (e.g. if both a read handle became ready and a # different write handle became ready), therefore it is possible # that multiple handles have completed. In this particular script # we are only performing a single transfer (one # Curl object / easy handle), therefore only one transfer can ever # possibly complete. qmsg, successes, failures = multi.info_read() # We should have retrieved all of the available statuses, leaving # none in the queue. assert qmsg == 0 # We have only one transfer. assert len(successes) == 1 and len(failures) == 0 or \ len(successes) == 0 and len(failures) == 1 if successes: state['result'] = True if failures: state['result'] = False # The failures array contains tuples of # (easy object, CURLE code, error message). _easy, state['code'], state['msg'] = failures[0] state['running'] = running def timer_fn(timeout_ms): if timeout_ms < 0: # libcurl passes a negative timeout value when no further # calls should be made. state['timeout'] = None else: state['timeout'] = timeout_ms / 1000.0 multi = pycurl.CurlMulti() multi.setopt(pycurl.M_SOCKETFUNCTION, socket_fn) multi.setopt(pycurl.M_TIMERFUNCTION, timer_fn) easy = pycurl.Curl() easy.setopt(pycurl.URL, url) # Uncomment to see what libcurl is doing throughout the transfer. #easy.setopt(pycurl.VERBOSE, 1) easy.setopt(pycurl.CONNECTTIMEOUT, 5) easy.setopt(pycurl.LOW_SPEED_TIME, 5) easy.setopt(pycurl.LOW_SPEED_LIMIT, 1) _io = BytesIO() easy.setopt(pycurl.WRITEDATA, _io) multi.add_handle(easy) handles = multi.socket_action(pycurl.SOCKET_TIMEOUT, 0) # This should invoke the timer function with a timeout value. while True: if state['running'] == 0: break else: # By the time we get here, timer function should have been already # invoked at least once so that we have a libcurl-supplied # timeout value. But in case this hasn't happened, default the timeout # to 1 second. timeout = state['timeout'] if timeout is None: raise Exception('Need to poll for I/O but the timeout is not set!') work(timeout) multi.remove_handle(easy) easy.close() multi.close() # Uncomment to print the retrieved contents. #print(_io.getvalue().decode()) if state['result'] is None: raise Exception('Script finished without a result!') if state['result']: print('Transfer successful, retrieved %d bytes' % len(_io.getvalue())) else: print('Transfer failed with code %d: %s' % (state['code'], state['msg'])) PK LWi\^�7�. . & doc/pycurl/examples/ssh_keyfunction.pynu �[��� import pycurl sftp_server = 'sftp://web.sourceforge.net' c = pycurl.Curl() c.setopt(c.URL, sftp_server) c.setopt(c.VERBOSE, True) def keyfunction(known_key, found_key, match): return c.KHSTAT_FINE c.setopt(c.SSH_KNOWNHOSTS, '.known_hosts') c.setopt(c.SSH_KEYFUNCTION, keyfunction) c.perform() PK LWi\8� ! ! ! doc/pycurl/examples/basicfirst.pynu �[��� #! /usr/bin/env python # -*- coding: utf-8 -*- # vi:ts=4:et import sys import pycurl PY3 = sys.version_info[0] > 2 class Test: def __init__(self): self.contents = '' if PY3: self.contents = self.contents.encode('ascii') def body_callback(self, buf): self.contents = self.contents + buf sys.stderr.write("Testing %s\n" % pycurl.version) t = Test() c = pycurl.Curl() c.setopt(c.URL, 'https://curl.haxx.se/dev/') c.setopt(c.WRITEFUNCTION, t.body_callback) c.perform() c.close() print(t.contents) PK LWi\]��a� � doc/pycurl/AUTHORSnu �[��� Copyright (C) 2001-2008 by Kjetil Jacobsen <kjetilja at gmail.com> Copyright (C) 2001-2008 by Markus F.X.J. Oberhumer <markus at oberhumer.com> Copyright (C) 2013-2022 by Oleg Pudeyev <code at olegp.name> Please see README, COPYING-LGPL and COPYING-MIT for license information. The following individuals contributed code to PycURL: Aaron Hill <visine19 at hotmail.com> Adam Guthrie <therigu at users.sourceforge.net> Adam Jacob Muller <adam at isprime.com> Akiomi Kamakura <akiomik at gmail.com> Alexandre Pion <pion at afnic.fr> Amir Rossert <amir.rossert at safebreach.com> Amit Mongia <amit_mongia at hotmail.com> Andjelko Horvat <comel at vingd.com> Arshad Khan <khan.m.arshad at gmail.com> Artur Sobierak <asobierak at gmail.com> Ashley Whetter <ashleyw at activestate.com> Barry Warsaw <barry at python.org> Bastian Kleineidam Benjamin Peterson <benjamin at python.org> Bill Collins <bill.collins at hp.com> Bo Anderson <mail at boanderson.me> Casey Miller <camiller at linkedin.com> Chih-Hsuan Yen <yan12125 at gmail.com> Christian Clauss <cclauss at me.com> Christopher Warner <cwarner at kernelcode.com> Clint Clayton <clintclayton at me.com> Conrad Steenberg <conrad at hep.caltech.edu> Daniel Pena Arteaga <dpena at ph.tum.de> Daniel Stenberg <daniel at haxx.se> decitre <decitre at gmail.com> Dima Tisnek <dimaqq at gmail.com> Dmitriy Taychenachev <dmitriy.taychenachev at skypicker.com> Dmitry Ketov <dketov at gmail.com> Dom Sekotill <dom.sekotill at kodo.org.uk> Domenico Andreoli <cavok at libero.it> Dominique <curl-and-python at d242.net> Eneas U de Queiroz <cotequeiroz at gmail.com> Eric S. Raymond <esr at thyrsus.com> Felix Yan <felixonmars at archlinux.org> Francisco Alves <chico at corp.globo.com> Gabi Davar <grizzly.nyo at gmail.com> Gisle Vanem <gvanem at yahoo.no> Gregory Petukhov <lorien at lorien.name> Hasan <aliyevH at hotmail.com> Hugo <hugovk at users.noreply.github.com> Iain R. Learmonth <irl at fsfe.org> ideal <idealities at gmail.com> Jakob Truelsen <jakob at scalgo.com> Jakub Wilk <jwilk at jwilk.net> James Deucker <bitwisecook at users.noreply.github.com> Jan Kryl <jan.kryl at nexenta.com> Jayne <corvine at gmail.com> James Deucker <bitwisecook at users.noreply.github.com> Jean Hominal <jhominal at gmail.com> JiCiT <jason at infinitebubble.com> Jim Patterson Josef Schlehofer <pepe.schlehofer at gmail.com> Jozef Melicher <jozef.melicher at eset.sk> K.S.Sreeram <sreeram at tachyontech.net> Kamil Dudka <kdudka at redhat.com> Kevin Ko <kevin.s.ko at gmail.com> Kevin Schlosser <drschlosser at hotmail.com> Khavish Anshudass Bhundoo <khavishbhundoo at users.noreply.github.com> Kian-Meng Ang <kianmeng at cpan.org> kxrd <onyeabor at riseup.net> Lipin Dmitriy <blackwithwhite666 at gmail.com> Léo El Amri <leo at superlel.me> Marc Labranche <mlabranche at developertown.com> Marcel Brouwers <marcel at marcelbrouwers.nl> Marcelo Jorge Vieira <metal at alucinados.com> Marien Zwart <marienz at users.sourceforge.net> Mark Eichin Markus <nepenthesdev at gmail.com> Martin Muenstermann <mamuema at sourceforge.net> Matt King <matt at gnik.com> Michael C <michael at mchang.name> Michael Cho <michael at michaelcho.dev> Michael Coughlin <michael.w.coughlin at gmail.com> Michael Treanor <26148512+skeptycal at users.noreply.github.com> Michał Górny <mgorny at gentoo.org> Miro Hrončok <miro at hroncok.cz> Nelson Chen <crazysim at gmail.com> Nick Pilon <npilon at oreilly.com> Nicolas Pauss <nicolas.pauss at intersec.com> Oleg Broytman <phd at phdru.name> Oren <orenyomtov at users.noreply.github.com> Orion Poplawski <orion at cora.nwra.com> Oskari Saarenmaa <os at ohmu.fi> Paul Pacheco Pavel Horáček <horacek.pavel at protonmail.com> Pierre Grimaud <grimaud.pierre at gmail.com> René Dudfield <renesd at gmail.com> resokou <resokou at gmail.com> Roland Sommer <rol at ndsommer.de> Romuald Brunet <romuald at gandi.net> Romulo A. Ceccon <romuloceccon at gmail.com> Russell McConnachie <okanaganrusty at mcconnachie.ca> Russell McConnachie <pmcconna at cisco.com> Samuel Dion-Girardeau <samuel.diongirardeau at gmail.com> Samuel Henrique <samueloph at debian.org> Scott Talbert <swt at techie.net> Simon Legner <Simon.Legner at gmail.com> Srinivas <spg349 at nyu.edu> Steve Kowalik <steven at wedontsleep.org> Subin <eourm20 at gmail.com> Tal Einat <tal.einat at socialcodeinc.com> Thomas Hunger <teh at camvine.org> Tino Lange <Tino.Lange at gmx.de> toddrme2178 <toddrme2178 at gmail.com> Tom Pierce <tom.pierce0 at gmail.com> Vesa Jääskeläinen <vesa.jaaskelainen at vaisala.com> Victor Lascurain <bittor at eleka.net> Vincent Philippon <Vincent.Philippon at ubisoft.com> Vitaly Murashev <vitaly.murashev at gmail.com> Vitezslav Cizek <vcizek at suse.com> vmurashev <vitaly.murashev at gmail.com> Wei C <gitsouler at users.noreply.github.com> Whitney Sorenson <wsorenson at gmail.com> Wim Lewis <wiml at users.sourceforge.net> Yiteng Zhang <yiteng.zhang at oracle.com> Yuhui H <eyecat at gmail.com> Yuri Ushakov <yuri.ushakov at gmail.com> Yves Bastide <yves at botify.com> Zdenek Pavlas <zpavlas at redhat.com> ziggy <ziggy at elephant-bird.net> PK LWi\H�wf f doc/pycurl/README.rstnu �[��� PycURL -- A Python Interface To The cURL library ================================================ .. image:: https://github.com/pycurl/pycurl/workflows/CI/badge.svg :target: https://github.com/pycurl/pycurl/actions PycURL is a Python interface to `libcurl`_, the multiprotocol file transfer library. Similarly to the urllib_ Python module, PycURL can be used to fetch objects identified by a URL from a Python program. Beyond simple fetches however PycURL exposes most of the functionality of libcurl, including: - Speed - libcurl is very fast and PycURL, being a thin wrapper above libcurl, is very fast as well. PycURL `was benchmarked`_ to be several times faster than requests_. - Features including multiple protocol support, SSL, authentication and proxy options. PycURL supports most of libcurl's callbacks. - Multi_ and share_ interfaces. - Sockets used for network operations, permitting integration of PycURL into the application's I/O loop (e.g., using Tornado_). .. _was benchmarked: http://stackoverflow.com/questions/15461995/python-requests-vs-pycurl-performance .. _requests: http://python-requests.org/ .. _Multi: https://curl.haxx.se/libcurl/c/libcurl-multi.html .. _share: https://curl.haxx.se/libcurl/c/libcurl-share.html .. _Tornado: http://www.tornadoweb.org/ Requirements ------------ - Python 3.5-3.10. - libcurl 7.19.0 or better. Installation ------------ Download source and binary distributions from `PyPI`_. Binary wheels are now available for 32 and 64 bit Windows versions. Please see `INSTALL.rst`_ for installation instructions. If installing from a Git checkout, please follow instruction in the `Git Checkout`_ section of INSTALL.rst. .. _PyPI: https://pypi.python.org/pypi/pycurl .. _INSTALL.rst: http://pycurl.io/docs/latest/install.html .. _Git Checkout: http://pycurl.io/docs/latest/install.html#git-checkout Documentation ------------- Documentation for the most recent PycURL release is available on `PycURL website <http://pycurl.io/docs/latest/>`_. Documentation for the development version of PycURL is available `here <http://pycurl.io/docs/dev/>`_. To build documentation from source, run ``make docs``. Building documentation requires `Sphinx <http://sphinx-doc.org/>`_ to be installed, as well as pycurl extension module built as docstrings are extracted from it. Built documentation is stored in ``build/doc`` subdirectory. Support ------- For support questions please use `curl-and-python mailing list`_. `Mailing list archives`_ are available for your perusal as well. Although not an official support venue, `Stack Overflow`_ has been popular with some PycURL users. Bugs can be reported `via GitHub`_. Please use GitHub only for bug reports and direct questions to our mailing list instead. .. _curl-and-python mailing list: https://lists.haxx.se/listinfo/curl-and-python .. _Stack Overflow: http://stackoverflow.com/questions/tagged/pycurl .. _Mailing list archives: https://curl.haxx.se/mail/list.cgi?list=curl-and-python .. _via GitHub: https://github.com/pycurl/pycurl/issues Automated Tests --------------- PycURL comes with an automated test suite. To run the tests, execute:: make test The suite depends on packages `pytest`_ and `flask`_, as well as `vsftpd`_. Some tests use vsftpd configured to accept anonymous uploads. These tests are not run by default. As configured, vsftpd will allow reads and writes to anything the user running the tests has read and write access. To run vsftpd tests you must explicitly set PYCURL_VSFTPD_PATH variable like so:: # use vsftpd in PATH export PYCURL_VSFTPD_PATH=vsftpd # specify full path to vsftpd export PYCURL_VSFTPD_PATH=/usr/local/libexec/vsftpd .. _pytest: https://pytest.org/ .. _flask: https://flask.palletsprojects.com/ .. _vsftpd: http://vsftpd.beasts.org/ Test Matrix ----------- The test matrix is a separate framework that runs tests on more esoteric configurations. It supports: - Testing against Python 2.4, which bottle does not support. - Testing against Python compiled without threads, which requires an out of process test server. - Testing against locally compiled libcurl with arbitrary options. To use the test matrix, first start the test server from Python 2.5+ by running:: python -m tests.appmanager Then in a different shell, and preferably in a separate user account, run the test matrix:: # run ftp tests, etc. export PYCURL_VSFTPD_PATH=vsftpd # create a new work directory, preferably not under pycurl tree mkdir testmatrix cd testmatrix # run the matrix specifying absolute path python /path/to/pycurl/tests/matrix.py The test matrix will download, build and install supported Python versions and supported libcurl versions, then run pycurl tests against each combination. To see what the combinations are, look in `tests/matrix.py <tests/matrix.py>`_. Contribute ---------- For smaller changes: #. Fork `the repository`_ on Github. #. Create a branch off **master**. #. Make your changes. #. Write a test which shows that the bug was fixed or that the feature works as expected. #. Send a pull request. #. Check back after 10-15 minutes to see if tests passed on Travis CI. PycURL supports old Python and libcurl releases and their support is tested on Travis. For larger changes: #. Join the `mailing list`_. #. Discuss your proposal on the mailing list. #. When consensus is reached, implement it as described above. Please contribute binary distributions for your system to the `downloads repository`_. License ------- :: Copyright (C) 2001-2008 by Kjetil Jacobsen <kjetilja at gmail.com> Copyright (C) 2001-2008 by Markus F.X.J. Oberhumer <markus at oberhumer.com> Copyright (C) 2013-2022 by Oleg Pudeyev <code at olegp.name> All rights reserved. PycURL is dual licensed under the LGPL and an MIT/X derivative license based on the cURL license. A full copy of the LGPL license is included in the file COPYING-LGPL. A full copy of the MIT/X derivative license is included in the file COPYING-MIT. You can redistribute and/or modify PycURL according to the terms of either license. .. _PycURL: http://pycurl.io/ .. _libcurl: https://curl.haxx.se/libcurl/ .. _urllib: http://docs.python.org/library/urllib.html .. _`the repository`: https://github.com/pycurl/pycurl .. _`mailing list`: https://lists.haxx.se/listinfo/curl-and-python .. _`downloads repository`: https://github.com/pycurl/downloads PK LWi\�0l�� � doc/pycurl/COPYING-MITnu �[��� COPYRIGHT AND PERMISSION NOTICE Copyright (C) 2001-2008 by Kjetil Jacobsen <kjetilja at gmail.com> Copyright (C) 2001-2008 by Markus F.X.J. Oberhumer <markus at oberhumer.com> Copyright (C) 2013-2022 by Oleg Pudeyev <code at olegp.name> All rights reserved. Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization of the copyright holder. PK �Yj\���Va a doc/alt-liblqr-1/ChangeLognu �[��� 2009-05-12 Carlo Baldassi <carlobaldassi@gmail.com> * Forgot (undocumented) legacy macro 2009-05-09 Carlo Baldassi <carlobaldassi@gmail.com> * Changed lqr_carver_get_[true_]energy * Added lqr_carver_get_energy_image 2009-05-05 Carlo Baldassi <carlobaldassi@gmail.com> * Updated the example files with the new features 2009-05-04 Carlo Baldassi <carlobaldassi@gmail.com> * Added lqr_carver_bias/rigmask_clear 2009-05-03 Carlo Baldassi <carlobaldassi@gmail.com> * Changed CATCH* macros to LQR_CATCH* * No alpha by default for LQR_CUSTOM_IMAGE * Improved set alpha/black channel * Bias activates energy (for using with lqr_carver_get_energy) * Fixes in lqr_carver_bias/rigmask_add_area * Added lqr_carver_rigmask_add_xy * Don't call transpose when adding rigmasks * Rigmask init set to 0 instead of 1 * Removed energy previews * Added lqr_carvre_get_true_energy 2009-04-28 Carlo Baldassi <carlobaldassi@gmail.com> * Heavily optimised the update_mmap code * Progress report spans whole sessions instead of being divided into steps when enlagement exceeds the enl_step 2009-04-27 Carlo Baldassi <carlobaldassi@gmail.com> * New framework for energy definition, including energy previews * Added lqr_carver_bias_add_xy * Better bias managment (saves memory if bias is not used, no unnecessary transpositions) 2009-04-16 Carlo Baldassi <carlobaldassi@gmail.com> * Added cancel methods and structures * Fixed recursiveness of some calls to lqr_carver_list_foreach * Fixed return value of lqr_carver_resize 2009-04-09 Carlo Baldassi <carlobaldassi@gmail.com> * Added lqr_carver_set_preserve_input_image * Version bump 0.4 2009-04-08 Carlo Baldassi <carlobaldassi@gmail.com> * Fixed bug with 16-bit images 2009-01-26 Carlo Baldassi <carlobaldassi@gmail.com> * Added readouts for current visiblity map 2008-11-01 Carlo Baldassi <carlobaldassi@gmail.com> * Bugfix in update_mmap causing crashes with delta_x > 1 * Removed unnecessary includes of stdio.h * Added debug_checkrows 2008-10-22 Carlo Baldassi <carlobaldassi@gmail.com> * Moved classes definitions to private headers 2008-10-21 Carlo Baldassi <carlobaldassi@gmail.com> * Removed 2-fold scale-up limit, added enl_step setting 2008-10-12 Carlo Baldassi <carlobaldassi@gmail.com> * Added 32 bit and 64 bit floating point support * Added get_col_depth * Turned all internal floating point maps from gdouble to gfloat * Collapsed all the nonstandard constructors and span functions to a single version (*_ext) 2008-09-04 Carlo Baldassi <carlobaldassi@gmail.com> * Added set_no_dump_vmaps 2008-09-04 Carlo Baldassi <carlobaldassi@gmail.com> * Hid private symbols 2008-07-30 Carlo Baldassi <carlobaldassi@gmail.com> * Optimized vsmap memory management * Bugfixes 2008-04-06 Carlo Baldassi <carlobaldassi@gmail.com> * Added 16 bit support 2008-02-25 Carlo Baldassi <carlobaldassi@gmail.com> * Added left-right switches 2008-02-20 Carlo Baldassi <carlobaldassi@gmail.com> * Added rigidity mask 2007-12-07 Carlo Baldassi <carlobaldassi@yahoo.it> * initial revision. PK �Yj\|�wfK� K� doc/alt-liblqr-1/COPYINGnu �[��� GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007 Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/> Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Preamble The GNU General Public License is a free, copyleft license for software and other kinds of works. The licenses for most software and other practical works are designed to take away your freedom to share and change the works. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change all versions of a program--to make sure it remains free software for all its users. We, the Free Software Foundation, use the GNU General Public License for most of our software; it applies also to any other work released this way by its authors. You can apply it to your programs, too. When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you can do these things. To protect your rights, we need to prevent others from denying you these rights or asking you to surrender the rights. Therefore, you have certain responsibilities if you distribute copies of the software, or if you modify it: responsibilities to respect the freedom of others. For example, if you distribute copies of such a program, whether gratis or for a fee, you must pass on to the recipients the same freedoms that you received. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights. Developers that use the GNU GPL protect your rights with two steps: (1) assert copyright on the software, and (2) offer you this License giving you legal permission to copy, distribute and/or modify it. For the developers' and authors' protection, the GPL clearly explains that there is no warranty for this free software. For both users' and authors' sake, the GPL requires that modified versions be marked as changed, so that their problems will not be attributed erroneously to authors of previous versions. Some devices are designed to deny users access to install or run modified versions of the software inside them, although the manufacturer can do so. This is fundamentally incompatible with the aim of protecting users' freedom to change the software. The systematic pattern of such abuse occurs in the area of products for individuals to use, which is precisely where it is most unacceptable. Therefore, we have designed this version of the GPL to prohibit the practice for those products. If such problems arise substantially in other domains, we stand ready to extend this provision to those domains in future versions of the GPL, as needed to protect the freedom of users. Finally, every program is threatened constantly by software patents. States should not allow patents to restrict development and use of software on general-purpose computers, but in those that do, we wish to avoid the special danger that patents applied to a free program could make it effectively proprietary. To prevent this, the GPL assures that patents cannot be used to render the program non-free. The precise terms and conditions for copying, distribution and modification follow. TERMS AND CONDITIONS 0. Definitions. "This License" refers to version 3 of the GNU General Public License. "Copyright" also means copyright-like laws that apply to other kinds of works, such as semiconductor masks. "The Program" refers to any copyrightable work licensed under this License. Each licensee is addressed as "you". "Licensees" and "recipients" may be individuals or organizations. To "modify" a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy. The resulting work is called a "modified version" of the earlier work or a work "based on" the earlier work. A "covered work" means either the unmodified Program or a work based on the Program. To "propagate" a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying, distribution (with or without modification), making available to the public, and in some countries other activities as well. To "convey" a work means any kind of propagation that enables other parties to make or receive copies. Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying. An interactive user interface displays "Appropriate Legal Notices" to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License. If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion. 1. Source Code. The "source code" for a work means the preferred form of the work for making modifications to it. "Object code" means any non-source form of a work. A "Standard Interface" means an interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language. The "System Libraries" of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for which an implementation is available to the public in source code form. A "Major Component", in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it. The "Corresponding Source" for a work in object code form means all the source code needed to generate, install, and (for an executable work) run the object code and to modify the work, including scripts to control those activities. However, it does not include the work's System Libraries, or general-purpose tools or generally available free programs which are used unmodified in performing those activities but which are not part of the work. For example, Corresponding Source includes interface definition files associated with source files for the work, and the source code for shared libraries and dynamically linked subprograms that the work is specifically designed to require, such as by intimate data communication or control flow between those subprograms and other parts of the work. The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source. The Corresponding Source for a work in source code form is that same work. 2. Basic Permissions. All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law. You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for which you do not control copyright. Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you. Conveying under any other circumstances is permitted solely under the conditions stated below. Sublicensing is not allowed; section 10 makes it unnecessary. 3. Protecting Users' Legal Rights From Anti-Circumvention Law. No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures. When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work's users, your or third parties' legal rights to forbid circumvention of technological measures. 4. Conveying Verbatim Copies. You may convey verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program. You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee. 5. Conveying Modified Source Versions. You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions: a) The work must carry prominent notices stating that you modified it, and giving a relevant date. b) The work must carry prominent notices stating that it is released under this License and any conditions added under section 7. This requirement modifies the requirement in section 4 to "keep intact all notices". c) You must license the entire work, as a whole, under this License to anyone who comes into possession of a copy. This License will therefore apply, along with any applicable section 7 additional terms, to the whole of the work, and all its parts, regardless of how they are packaged. This License gives no permission to license the work in any other way, but it does not invalidate such permission if you have separately received it. d) If the work has interactive user interfaces, each must display Appropriate Legal Notices; however, if the Program has interactive interfaces that do not display Appropriate Legal Notices, your work need not make them do so. A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an "aggregate" if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation's users beyond what the individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate. 6. Conveying Non-Source Forms. You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways: a) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by the Corresponding Source fixed on a durable physical medium customarily used for software interchange. b) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by a written offer, valid for at least three years and valid for as long as you offer spare parts or customer support for that product model, to give anyone who possesses the object code either (1) a copy of the Corresponding Source for all the software in the product that is covered by this License, on a durable physical medium customarily used for software interchange, for a price no more than your reasonable cost of physically performing this conveying of source, or (2) access to copy the Corresponding Source from a network server at no charge. c) Convey individual copies of the object code with a copy of the written offer to provide the Corresponding Source. This alternative is allowed only occasionally and noncommercially, and only if you received the object code with such an offer, in accord with subsection 6b. d) Convey the object code by offering access from a designated place (gratis or for a charge), and offer equivalent access to the Corresponding Source in the same way through the same place at no further charge. You need not require recipients to copy the Corresponding Source along with the object code. If the place to copy the object code is a network server, the Corresponding Source may be on a different server (operated by you or a third party) that supports equivalent copying facilities, provided you maintain clear directions next to the object code saying where to find the Corresponding Source. Regardless of what server hosts the Corresponding Source, you remain obligated to ensure that it is available for as long as needed to satisfy these requirements. e) Convey the object code using peer-to-peer transmission, provided you inform other peers where the object code and Corresponding Source of the work are being offered to the general public at no charge under subsection 6d. A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code work. A "User Product" is either (1) a "consumer product", which means any tangible personal property which is normally used for personal, family, or household purposes, or (2) anything designed or sold for incorporation into a dwelling. In determining whether a product is a consumer product, doubtful cases shall be resolved in favor of coverage. For a particular product received by a particular user, "normally used" refers to a typical or common use of that class of product, regardless of the status of the particular user or of the way in which the particular user actually uses, or expects or is expected to use, the product. A product is a consumer product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless such uses represent the only significant mode of use of the product. "Installation Information" for a User Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding Source. The information must suffice to ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made. If you convey an object code work under this section in, or with, or specifically for use in, a User Product, and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is characterized), the Corresponding Source conveyed under this section must be accompanied by the Installation Information. But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product (for example, the work has been installed in ROM). The requirement to provide Installation Information does not include a requirement to continue to provide support service, warranty, or updates for a work that has been modified or installed by the recipient, or for the User Product in which it has been modified or installed. Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network. Corresponding Source conveyed, and Installation Information provided, in accord with this section must be in a format that is publicly documented (and with an implementation available to the public in source code form), and must require no special password or key for unpacking, reading or copying. 7. Additional Terms. "Additional permissions" are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as though they were included in this License, to the extent that they are valid under applicable law. If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire Program remains governed by this License without regard to the additional permissions. When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it. (Additional permissions may be written to require their own removal in certain cases when you modify the work.) You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission. Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms: a) Disclaiming warranty or limiting liability differently from the terms of sections 15 and 16 of this License; or b) Requiring preservation of specified reasonable legal notices or author attributions in that material or in the Appropriate Legal Notices displayed by works containing it; or c) Prohibiting misrepresentation of the origin of that material, or requiring that modified versions of such material be marked in reasonable ways as different from the original version; or d) Limiting the use for publicity purposes of names of licensors or authors of the material; or e) Declining to grant rights under trademark law for use of some trade names, trademarks, or service marks; or f) Requiring indemnification of licensors and authors of that material by anyone who conveys the material (or modified versions of it) with contractual assumptions of liability to the recipient, for any liability that these contractual assumptions directly impose on those licensors and authors. All other non-permissive additional terms are considered "further restrictions" within the meaning of section 10. If the Program as you received it, or any part of it, contains a notice stating that it is governed by this License along with a term that is a further restriction, you may remove that term. If a license document contains a further restriction but permits relicensing or conveying under this License, you may add to a covered work material governed by the terms of that license document, provided that the further restriction does not survive such relicensing or conveying. If you add terms to a covered work in accord with this section, you must place, in the relevant source files, a statement of the additional terms that apply to those files, or a notice indicating where to find the applicable terms. Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or stated as exceptions; the above requirements apply either way. 8. Termination. You may not propagate or modify a covered work except as expressly provided under this License. Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11). However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation. Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice. Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, you do not qualify to receive new licenses for the same material under section 10. 9. Acceptance Not Required for Having Copies. You are not required to accept this License in order to receive or run a copy of the Program. Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise does not require acceptance. However, nothing other than this License grants you permission to propagate or modify any covered work. These actions infringe copyright if you do not accept this License. Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so. 10. Automatic Licensing of Downstream Recipients. Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that work, subject to this License. You are not responsible for enforcing compliance by third parties with this License. An "entity transaction" is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations. If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party's predecessor in interest had or could give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts. You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it. 11. Patents. A "contributor" is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based. The work thus licensed is called the contributor's "contributor version". A contributor's "essential patent claims" are all patent claims owned or controlled by the contributor, whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the contributor version. For purposes of this definition, "control" includes the right to grant patent sublicenses in a manner consistent with the requirements of this License. Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor's essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version. In the following three paragraphs, a "patent license" is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to sue for patent infringement). To "grant" such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party. If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work is not available for anyone to copy, free of charge and under the terms of this License, through a publicly available network server or other readily accessible means, then you must either (1) cause the Corresponding Source to be so available, or (2) arrange to deprive yourself of the benefit of the patent license for this particular work, or (3) arrange, in a manner consistent with the requirements of this License, to extend the patent license to downstream recipients. "Knowingly relying" means you have actual knowledge that, but for the patent license, your conveying the covered work in a country, or your recipient's use of the covered work in a country, would infringe one or more identifiable patents in that country that you have reason to believe are valid. If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then the patent license you grant is automatically extended to all recipients of the covered work and works based on it. A patent license is "discriminatory" if it does not include within the scope of its coverage, prohibits the exercise of, or is conditioned on the non-exercise of one or more of the rights that are specifically granted under this License. You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software, under which you make payment to the third party based on the extent of your activity of conveying the work, and under which the third party grants, to any of the parties who would receive the covered work from you, a discriminatory patent license (a) in connection with copies of the covered work conveyed by you (or copies made from those copies), or (b) primarily for and in connection with specific products or compilations that contain the covered work, unless you entered into that arrangement, or that patent license was granted, prior to 28 March 2007. Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law. 12. No Surrender of Others' Freedom. If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program. 13. Use with the GNU Affero General Public License. Notwithstanding any other provision of this License, you have permission to link or combine any covered work with a work licensed under version 3 of the GNU Affero General Public License into a single combined work, and to convey the resulting work. The terms of this License will continue to apply to the part which is the covered work, but the special requirements of the GNU Affero General Public License, section 13, concerning interaction through a network will apply to the combination as such. 14. Revised Versions of this License. The Free Software Foundation may publish revised and/or new versions of the GNU General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Program specifies that a certain numbered version of the GNU General Public License "or any later version" applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the GNU General Public License, you may choose any version ever published by the Free Software Foundation. If the Program specifies that a proxy can decide which future versions of the GNU General Public License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Program. Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version. 15. Disclaimer of Warranty. THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 16. Limitation of Liability. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 17. Interpretation of Sections 15 and 16. If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee. END OF TERMS AND CONDITIONS How to Apply These Terms to Your New Programs If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms. To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively state the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found. <one line to give the program's name and a brief idea of what it does.> Copyright (C) <year> <name of author> This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>. Also add information on how to contact you by electronic and paper mail. If the program does terminal interaction, make it output a short notice like this when it starts in an interactive mode: <program> Copyright (C) <year> <name of author> This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details. The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, your program's commands might be different; for a GUI interface, you would use an "about box". You should also get your employer (if you work as a programmer) or school, if any, to sign a "copyright disclaimer" for the program, if necessary. For more information on this, and how to apply and follow the GNU GPL, see <http://www.gnu.org/licenses/>. The GNU General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. But first, please read <http://www.gnu.org/philosophy/why-not-lgpl.html>. PK �Yj\;bx6, , doc/alt-liblqr-1/READMEnu �[��� LiquidRescale library 0.4.0 =========================== Table of contents ----------------- * Introduction + Library features * Installation + Requirements + Normal setup * Using the library * References * Copyright + Introduction -------------- The LiquidRescale (lqr) library provides a C/C++ API for performing non-uniform resizing of images by the seam-carving technique. ++ Library features The library takes images in plain array format as input and converts them to a multi-size representation. Following is a list of features: * Easy to use and fully documented API * Currently supports 8 bit to 64 bit per channel images * Support for different color models: grayscale, RGB, CMY and their variants, and even custom ones * Areas in the image can be marked for preservation or discard, or for additional seam rigidity * Once the image has been fully processed, the scaling can be done in real-time. In fact, the information can be saved and read out later without any further processing * The resizing is done with a single function which automatically performs all the necessary operations; it can also work in successive steps without wasting computational time * Possibility to tune the carving operation by letting the seams be less connected, or more rigid, or both (the rigidity can be also be modulated through a mask, to get a differnet behaviour in different areas of the image) * Can export and import the visibility map (the seams) * Other images can be attached and undergo the same carving process as the parent image * The automatic feature detection algorithm can be tuned by selecting among different energy gradient functions, and easily defining custom ones * Reports progress through a customisable interface * A signalling system permits to cleanly handle errors * Portable to all major OS's + Installation -------------- ++ Dependencies The lqr library depends on the glib-2.0 libraries ++ Normal setup The build package uses autotools and libtool, so the installation commands on Unix systems are simply ./configure && make && sudo make install The last step requires administrative privileges. (Note: the default installation path is /usr since version 0.4) If you want to also install the man pages for the library functions, add the option `--enable-install-man' in the call to ./configure. If you want to disable legacy macro names which do not begin with LQR_ then add the option `--diable-legacy-macros' See the INSTALL file for a full description. + Using the library for development ------------------------------------- In order to use the library functions and structures from a C or C++ program, you have to add this include line in your program: #include <lqr.h> At compile time, you can take advantage of pkg-config to set the proper flags. In the `examples' directory you can find a basic example program, `liquidrescale-basic', and a full-featured demo program, `liquidrescale', together with a simple Makefile. Both programs are fully commented. The "basic" version demonstrates how to use the strictly-needed library functions, while the full version uses almost all of the API methods provided. The Makefile shows how to set the compilation flags. See the README file in that directory for more information. The complete manual and reference for the library, together with some additional notes, can be found in the `docs' directory in docbook format. The reference is also provided in man page format. The makefile in that directory (hopefully) generates the manual in html format, using xsltproc; then you'll find the index named after `liblqr_manual_index.html'. See the README file in that directory for further information. + References ------------ The library implements the algorithm described in the paper "Seam Carving for Content-Aware Image Resizing" by Shai Avidan and Ariel Shamir, which can be found at http://www.faculty.idc.ac.il/arik/imret.pdf + Copyright ----------- Copyright (C) 2007-2009 Carlo Baldassi <carlobaldassi@gmail.com> PK Ɠc\ m�&$ $ man/man3/ld_errno.3nu �[��� PK Ɠc\�շY� � g man/man3/ber_bvfree.3nu �[��� PK Ǔc\�4�� � 24 man/man3/ldap_modify_s.3nu �[��� PK Ǔc\��1ܽ � CF man/man3/ldap_control_create.3nu �[��� PK ȓc\���0 0 NR man/man3/ldap_memfree.3nu �[��� PK ȓc\���0 0 �X man/man3/ldap_memcalloc.3nu �[��� PK ɓc\� �q q >_ man/man3/ldap_explode_dn.3nu �[��� PK ɓc\�շY� � �y man/man3/ber_bvecadd.3nu �[��� PK ʓc\}�q � � œ man/man3/ldap_add.3nu �[��� PK ʓc\� �q q �� man/man3/ldap_dn2dcedn.3nu �[��� PK ˓c\���0 0 [� man/man3/ldap_memrealloc.3nu �[��� PK ˓c\�5^#v1 v1 տ man/man3/ber_get_stringa.3nu �[��� PK ̓c\��n� � �� man/man3/ldap_init_fd.3nu �[��� PK ̓c\�5^#v1 v1 � man/man3/ber_get_next.3nu �[��� PK ͓c\ V�H- - p; man/man3/ldap_abandon_ext.3nu �[��� PK ͓c\�� �. �. �D man/man3/ldap_unbind_s.3nu �[��� PK Γc\'�t!� � .t man/man3/ldap_start_tls.3nu �[��� PK Γc\� �q q { man/man3/ldap_str2dn.3nu �[��� PK ϓc\g�d"# "# ͕ man/man3/ldap_str2objectclass.3nu �[��� PK ϓc\�5^#v1 v1 >� man/man3/ber_peek_tag.3nu �[��� PK Гc\�5^#v1 v1 �� man/man3/ber_get_boolean.3nu �[��� PK ѓc\����� � � man/man3/ldap_get_values.3nu �[��� PK ғc\��A �' man/man3/ldap_modrdn2_s.3nu �[��� PK ғc\]�Ib� � F1 man/man3/ldap_delete_ext_s.3nu �[��� PK ӓc\��n� � �; man/man3/ldap_initialize.3nu �[��� PK ԓc\ ��� � & �S man/man3/ldap_parse_sasl_bind_result.3nu �[��� PK Փc\�C�B� � �c man/man3/ldap_compare_ext.3nu �[��� PK Փc\S/�6 6 �n man/man3/ldap_next_attribute.3nu �[��� PK ֓c\ ݴ� vx man/man3/ldap_free_urldesc.3nu �[��� PK דc\��MK$ K$ ۄ man/man3/ber_put_int.3nu �[��� PK דc\ ȵ�� � l� man/man3/ldap_sort_entries.3nu �[��� PK ؓc\a��j j �� man/man3/ldap_count_entries.3nu �[��� PK ٓc\%�&}. . W� man/man3/ldap_dup.3nu �[��� PK ړc\�T �� man/man3/lber-memory.3nu �[��� PK ړc\��1ܽ � *� man/man3/ldap_controls_dup.3nu �[��� PK ۓc\�� �. �. 3� man/man3/ldap_unbind_ext_s.3nu �[��� PK ܓc\�� �. �. } man/man3/ldap_simple_bind_s.3nu �[��� PK ݓc\ ݴ� �7 man/man3/ldap_url_parse.3nu �[��� PK ݓc\�^�E/ / *D man/man3/ldap_parse_reference.3nu �[��� PK �c\�շY� � �M man/man3/ber_dupbv.3nu �[��� PK �c\��MK$ K$ rg man/man3/ber_put_enum.3nu �[��� PK �c\ ȵ�� � � man/man3/ldap_sort_values.3nu �[��� PK �c\� �q q 7� man/man3/ldap_dnfree.3nu �[��� PK �c\a��j j � man/man3/ldap_next_entry.3nu �[��� PK �c\g�d"# "# �� man/man3/ldap_syntax2str.3nu �[��� PK �c\����� � � man/man3/ldap_count_values_len.3nu �[��� PK �c\��A F� man/man3/ldap_modrdn.3nu �[��� PK �c\g�d"# "# �� man/man3/ldap_syntax2name.3nu �[��� PK �c\��MK$ K$ man/man3/ber_put_string.3nu �[��� PK �c\�շY� � �5 man/man3/ber_bvarray_add.3nu �[��� PK �c\'�t!� � mO man/man3/ldap_tls.3nu �[��� PK �c\M7��R# R# OV man/man3/ldap.3nu �[��� PK �c\OPh�� � �y man/man3/ldap_rename_s.3nu �[��� PK �c\g�d"# "# �� man/man3/ldap_objectclass2str.3nu �[��� PK �c\g�d"# "# " "� man/man3/ldap_attributetype2name.3nu �[��� PK �c\�� �. �. �� man/man3/ldap_unbind_ext.3nu �[��� PK �c\����� � � man/man3/ldap_count_values.3nu �[��� PK �c\��MK$ K$ man/man3/ber_flush.3nu �[��� PK �c\���0 0 �* man/man3/ldap_memory.3nu �[��� PK �c\a��j j 1 man/man3/ldap_first_entry.3nu �[��� PK �c\J�s* * ! �: man/man3/ldap_parse_vlv_control.3nu �[��� PK �c\�C�B� � GD man/man3/ldap_compare_s.3nu �[��� PK �c\�c%u u sO man/man3/ldap_search_st.3nu �[��� PK �c\}�q � � 1d man/man3/ldap_add_ext_s.3nu �[��� PK �c\Y��X<L <L o man/man3/ldap_get_option.3nu �[��� PK �c\�5^#v1 v1 �� man/man3/ber_next_element.3nu �[��� PK �c\g�d"# "# [� man/man3/ldap_str2matchingrule.3nu �[��� PK �c\�5^#v1 v1 � man/man3/ber_get_bitstring.3nu �[��� PK �c\� �q q �B man/man3/ldap_dn2ufn.3nu �[��� PK �c\��MK$ K$ F] man/man3/ber_put_null.3nu �[��� PK �c\}�q � � man/man3/ldap_add_s.3nu �[��� PK �c\��� � $ �� man/man3/ldap_extended_operation_s.3nu �[��� PK �c\��1ܽ � � man/man3/ldap_control_dup.3nu �[��� PK �c\��1ܽ � �� man/man3/ldap_controls.3nu �[��� PK �c\g�d"# "# �� man/man3/ldap_schema.3nu �[��� PK �c\���0 0 f� man/man3/ldap_strdup.3nu �[��� PK �c\�շY� � �� man/man3/ber_bvdup.3nu �[��� PK �c\�Q�} & & �� man/man3/ldap_sync.3nu �[��� PK �c\'�t!� � � man/man3/ldap_install_tls.3nu �[��� PK �c\�c%u u � man/man3/ldap_search_ext_s.3nu �[��� PK �c\ ݴ� �4 man/man3/ldap_url.3nu �[��� PK �c\�� �. �. �@ man/man3/ldap_sasl_bind.3nu �[��� PK �c\�w;+- - Bp man/man3/ldap_count_references.3nu �[��� PK �c\��� � " �y man/man3/ldap_extended_operation.3nu �[��� PK �c\�4�� � �� man/man3/ldap_modify_ext_s.3nu �[��� PK �c\� �q q � man/man3/ldap_dn2ad_canonical.3nu �[��� PK �c\g�d"# "# ̰ man/man3/ldap_scherr2str.3nu �[��� PK �c\�4�� � 8� man/man3/ldap_modify.3nu �[��� PK �c\ V�H- - G� man/man3/ldap_abandon.3nu �[��� PK �c\Y��X<L <L �� man/man3/ldap_set_option.3nu �[��� PK �c\ ȵ�� � A< man/man3/ldap_sort_strcasecmp.3nu �[��� PK �c\�5^#v1 v1 xA man/man3/ber_get_null.3nu �[��� PK �c\]�Ib� � 5s man/man3/ldap_delete_s.3nu �[��� PK �c\��MK$ K$ t} man/man3/ber_put_seq.3nu �[��� PK �c\t5d�� � � man/man3/lber-sockbuf.3nu �[��� PK �c\�E͡ � *� man/man3/ldap_result.3nu �[��� PK �c\ NO O � man/man3/ldap_first_message.3nu �[��� PK �c\���0 0 �� man/man3/ldap_memalloc.3nu �[��� PK �c\�� �. �. %� man/man3/ldap_simple_bind.3nu �[��� PK �c\��A n man/man3/ldap_modrdn_s.3nu �[��� PK �c\�շY� � � man/man3/ber_free.3nu �[��� PK ��c\�w;+- - �. man/man3/ldap_next_reference.3nu �[��� PK ��c\�c%u u 8 man/man3/ldap_search_s.3nu �[��� PK ��c\�c%u u �L man/man3/ldap_search_ext.3nu �[��� PK ��c\�C�B� � �a man/man3/ldap_compare.3nu �[��� PK ��c\�շY� � �l man/man3/ber_bvarray_free.3nu �[��� PK ��c\g�d"# "# �� man/man3/ldap_objectclass2name.3nu �[��� PK ��c\�շY� � � man/man3/ber_str2bv.3nu �[��� PK ��c\ ȵ�� � �� man/man3/ldap_sort.3nu �[��� PK ��c\�4�� � �� man/man3/ldap_modify_ext.3nu �[��� PK ��c\����� � �� man/man3/ldap_get_values_len.3nu �[��� PK ��c\�E͡ � 3� man/man3/ldap_msgfree.3nu �[��� PK ��c\g�d"# "# ! � man/man3/ldap_str2attributetype.3nu �[��� PK ��c\ NO O � man/man3/ldap_count_messages.3nu �[��� PK ��c\��1ܽ � +& man/man3/ldap_controls_free.3nu �[��� PK ��c\�5^#v1 v1 52 man/man3/ber_scanf.3nu �[��� PK ��c\g�d"# "# �c man/man3/ldap_matchingrule2str.3nu �[��� PK ��c\g�d"# "# a� man/man3/ldap_objectclass_free.3nu �[��� PK ��c\��MK$ K$ Ӫ man/man3/ber_put_ostring.3nu �[��� PK ��c\OPh�� � h� man/man3/ldap_rename.3nu �[��� PK ��c\g�d"# "# " 7� man/man3/ldap_attributetype_free.3nu �[��� PK ��c\�� �. �. �� man/man3/ldap_set_rebind_proc.3nu �[��� PK ��c\����� � �, man/man3/ldap_value_free_len.3nu �[��� PK ��c\��MK$ K$ .8 man/man3/ber_printf.3nu �[��� PK ��c\� �q q �\ man/man3/ldap_dn2str.3nu �[��� PK ��c\g�d"# "# ! uw man/man3/ldap_matchingrule_free.3nu �[��� PK ��c\�� �. �. � man/man3/ldap_sasl_bind_s.3nu �[��� PK ��c\��n� � 1� man/man3/ldap_open.3nu �[��� PK �c\�c%u u L� man/man3/ldap_search.3nu �[��� PK �c\�5^#v1 v1 � man/man3/ber_get_stringb.3nu �[��� PK �c\��n� � �( man/man3/ldap_set_urllist_proc.3nu �[��� PK �c\ m�&$ $ �@ man/man3/ldap_perror.3nu �[��� PK �c\'�t!� � X[ man/man3/ldap_start_tls_s.3nu �[��� PK �c\ m�&$ $ Bb man/man3/ldap_error.3nu �[��� PK �c\����� � �| man/man3/ldap_value_free.3nu �[��� PK �c\�շY� � ݇ man/man3/ber_bvecfree.3nu �[��� PK �c\]�Ib� � �� man/man3/ldap_delete_ext.3nu �[��� PK �c\�� �. �. � man/man3/ldap_bind_s.3nu �[��� PK �c\�E͡ � /� man/man3/ldap_msgtype.3nu �[��� PK �c\�C�B� � � man/man3/ldap_compare_ext_s.3nu �[��� PK �c\S/�6 6 G� man/man3/ldap_first_attribute.3nu �[��� PK �c\��MK$ K$ � man/man3/ber_put_set.3nu �[��� PK �c\�4�� � ]& man/man3/ldap_mods_free.3nu �[��� PK �c\��MK$ K$ o8 man/man3/ber_start_set.3nu �[��� PK �c\g�d"# "# ] man/man3/ldap_str2syntax.3nu �[��� PK �c\ m�&$ $ n� man/man3/ldap_result2error.3nu �[��� PK �c\�E͡ � ޚ man/man3/ldap_msgid.3nu �[��� PK �c\%�&}. . Ĭ man/man3/ldap_destroy.3nu �[��� PK �c\� �q q 9� man/man3/ldap_get_dn.3nu �[��� PK �c\�� �. �. �� man/man3/ldap_unbind.3nu �[��� PK �c\��n� � 4 man/man3/ldap_init.3nu �[��� PK �c\ NO O O man/man3/ldap_next_message.3nu �[��� PK �c\�w;+- - �' man/man3/ldap_first_reference.3nu �[��� PK �c\}�q � � f1 man/man3/ldap_add_ext.3nu �[��� PK �c\ m�&$ $ G< man/man3/ldap_err2string.3nu �[��� PK �c\g�d"# "# ! �V man/man3/ldap_attributetype2str.3nu �[��� PK �c\g�d"# "# ! (z man/man3/ldap_matchingrule2name.3nu �[��� PK �c\�6+� � " �� man/man3/ldap_parse_sort_control.3nu �[��� PK �c\�5^#v1 v1 �� man/man3/ber_get_int.3nu �[��� PK �c\ ݴ� <� man/man3/ldap_is_ldap_url.3nu �[��� PK �c\ ��� � % �� man/man3/ldap_parse_extended_result.3nu �[��� PK �c\�5^#v1 v1 �� man/man3/lber-decode.3nu �[��� PK �c\�5^#v1 v1 u$ man/man3/ber_get_enum.3nu �[��� PK �c\��1ܽ � 2V man/man3/ldap_control_free.3nu �[��� PK �c\�շY� � ;b man/man3/ber_bvstr.3nu �[��� PK �c\]�Ib� � | man/man3/ldap_delete.3nu �[��� PK �c\�շY� � B� man/man3/ber_bvstrdup.3nu �[��� PK �c\� �q q � man/man3/ldap_dcedn2dn.3nu �[��� PK �c\'�t!� � Ⱥ man/man3/ldap_tls_inplace.3nu �[��� PK �c\���0 0 �� man/man3/ldap_memvfree.3nu �[��� PK �c\g�d"# "# *� man/man3/ldap_syntax_free.3nu �[��� PK �c\��A �� man/man3/ldap_modrdn2.3nu �[��� PK �c\��MK$ K$ �� man/man3/ber_alloc_t.3nu �[��� PK �c\�� �. �. man/man3/ldap_bind.3nu �[��� PK �c\ ��� � �H man/man3/ldap_parse_result.3nu �[��� PK �c\�5^#v1 v1 �X man/man3/ber_first_element.3nu �[��� PK �c\��MK$ K$ �� man/man3/lber-encode.3nu �[��� PK �c\� �q q $� man/man3/ldap_explode_rdn.3nu �[��� PK �c\��1ܽ � �� man/man3/ldap_control_find.3nu �[��� PK �c\�5^#v1 v1 �� man/man3/ber_skip_tag.3nu �[��� PK �c\�շY� � � man/man3/lber-types.3nu �[��� PK �c\ m�&$ $ q! man/man3/ldap_errlist.3nu �[��� PK �c\�"l��B �B �; man/man5/ldap.conf.5nu �[��� PK �c\��lN N �~ man/man5/ldif.5nu �[��� PK �c\T?Ц � �� licenses/alt-openldap11/LICENSEnu �[��� PK �c\`)��) ) ! y� licenses/alt-openldap11/COPYRIGHTnu �[��� PK "�c\C���k �k � doc/alt-openldap11/CHANGESnu �[��� PK "�c\�ѥ� � : doc/alt-openldap11/ANNOUNCEMENTnu �[��� PK "�c\�1�L� � �' doc/alt-openldap11/READMEnu �[��� PK #�c\!��+V +V ( t5 doc/alt-openldap11-devel/rfc/rfc2294.txtnu �[��� PK $�c\ֽ�� � ( �� doc/alt-openldap11-devel/rfc/rfc4523.txtnu �[��� PK $�c\I!�y{0 {0 ( 87 doc/alt-openldap11-devel/rfc/rfc2247.txtnu �[��� PK %�c\�x͡e �e ( h doc/alt-openldap11-devel/rfc/rfc2849.txtnu �[��� PK %�c\��֓' ' ( � doc/alt-openldap11-devel/rfc/rfc3673.txtnu �[��� PK &�c\5���� � ( o� doc/alt-openldap11-devel/rfc/rfc3663.txtnu �[��� PK &�c\�K�`�^ �^ ( ۚ doc/alt-openldap11-devel/rfc/rfc3876.txtnu �[��� PK &�c\1�y6�� �� ( � doc/alt-openldap11-devel/rfc/rfc2798.txtnu �[��� PK '�c\bP+�? �? ( �z doc/alt-openldap11-devel/rfc/rfc4522.txtnu �[��� PK '�c\�H�dJ dJ ( �� doc/alt-openldap11-devel/rfc/rfc4511.txtnu �[��� PK '�c\��� �. �. ( } doc/alt-openldap11-devel/rfc/rfc3829.txtnu �[��� PK '�c\�R˸W; W; ( �4 doc/alt-openldap11-devel/rfc/rfc4530.txtnu �[��� PK '�c\(��E� � " Vp doc/alt-openldap11-devel/rfc/INDEXnu �[��� PK (�c\� � E� E� ( �} doc/alt-openldap11-devel/rfc/rfc2926.txtnu �[��� PK (�c\?l� �! �! ( !V doc/alt-openldap11-devel/rfc/rfc5020.txtnu �[��� PK (�c\�A�\ { { ( x doc/alt-openldap11-devel/rfc/rfc3866.txtnu �[��� PK (�c\��PB0 B0 ( }� doc/alt-openldap11-devel/rfc/rfc4510.txtnu �[��� PK (�c\\��7�: �: ( $ doc/alt-openldap11-devel/rfc/rfc4513.txtnu �[��� PK (�c\��x�m� m� ( _ doc/alt-openldap11-devel/rfc/rfc4517.txtnu �[��� PK (�c\��/�s> s> ( � doc/alt-openldap11-devel/rfc/rfc4527.txtnu �[��� PK (�c\ iӑ . . ( �\ doc/alt-openldap11-devel/rfc/rfc3062.txtnu �[��� PK (�c\�7�i i ( � doc/alt-openldap11-devel/rfc/rfc3727.txtnu �[��� PK )�c\��2� x x ( ٫ doc/alt-openldap11-devel/rfc/rfc3687.txtnu �[��� PK )�c\|�YL L ( 1$ doc/alt-openldap11-devel/rfc/rfc3088.txtnu �[��� PK )�c\S���h �h ( �p doc/alt-openldap11-devel/rfc/rfc2589.txtnu �[��� PK )�c\�Œtsy sy ( �� doc/alt-openldap11-devel/rfc/rfc4373.txtnu �[��� PK )�c\!Z�+� � ( �S! doc/alt-openldap11-devel/rfc/rfc4524.txtnu �[��� PK )�c\��[� � ( " doc/alt-openldap11-devel/rfc/rfc3928.txtnu �[��� PK )�c\�?I�0 �0 ( +/# doc/alt-openldap11-devel/rfc/rfc4528.txtnu �[��� PK )�c\_��+ �+ ( ~`# doc/alt-openldap11-devel/rfc/rfc4525.txtnu �[��� PK )�c\4�5" 5" ( Ɍ# doc/alt-openldap11-devel/rfc/rfc2079.txtnu �[��� PK )�c\{��3M] M] ( V�# doc/alt-openldap11-devel/rfc/rfc4515.txtnu �[��� PK *�c\�䗚�O �O ( � $ doc/alt-openldap11-devel/rfc/rfc2649.txtnu �[��� PK *�c\fb@�u9 u9 ( I]$ doc/alt-openldap11-devel/rfc/rfc2714.txtnu �[��� PK *�c\�s| s| ( �$ doc/alt-openldap11-devel/rfc/rfc4514.txtnu �[��� PK *�c\��%�) �) ( �% doc/alt-openldap11-devel/rfc/rfc4370.txtnu �[��� PK *�c\d��q' q' ( �=% doc/alt-openldap11-devel/rfc/rfc4526.txtnu �[��� PK *�c\�z*��2 �2 ( �e% doc/alt-openldap11-devel/rfc/rfc4013.txtnu �[��� PK *�c\]}SL�E �E ( % doc/alt-openldap11-devel/rfc/rfc3671.txtnu �[��� PK *�c\�p o4 o4 ( %�% doc/alt-openldap11-devel/rfc/rfc3909.txtnu �[��� PK *�c\����T �T ( �& doc/alt-openldap11-devel/rfc/rfc5805.txtnu �[��� PK *�c\s Z �- �- ( i& doc/alt-openldap11-devel/rfc/rfc4529.txtnu �[��� PK *�c\�N �bw bw ( S�& doc/alt-openldap11-devel/rfc/rfc4516.txtnu �[��� PK *�c\p=�� �� ( ' doc/alt-openldap11-devel/rfc/rfc2377.txtnu �[��� PK *�c\��AI) ) ( �' doc/alt-openldap11-devel/rfc/rfc3045.txtnu �[��� PK +�c\��*�� �� ( U�' doc/alt-openldap11-devel/rfc/rfc2307.txtnu �[��� PK +�c\ѓ�j�� �� ( ap( doc/alt-openldap11-devel/rfc/rfc4520.txtnu �[��� PK +�c\ ��� � ( ��( doc/alt-openldap11-devel/rfc/rfc4533.txtnu �[��� PK +�c\��ќ�. �. ( �* doc/alt-openldap11-devel/rfc/rfc3703.txtnu �[��� PK +�c\��W��B �B ( �F, doc/alt-openldap11-devel/rfc/rfc3112.txtnu �[��� PK +�c\�[81Y� Y� ( ʼn, doc/alt-openldap11-devel/rfc/rfc4512.txtnu �[��� PK +�c\��}.�7 �7 ( v1. doc/alt-openldap11-devel/rfc/rfc4532.txtnu �[��� PK +�c\ϩ�� 2 2 ( ui. doc/alt-openldap11-devel/rfc/rfc2696.txtnu �[��� PK +�c\���]� ]� ( ֛. doc/alt-openldap11-devel/rfc/rfc3712.txtnu �[��� PK ,�c\R��d�3 �3 ( ��/ doc/alt-openldap11-devel/rfc/rfc4403.txtnu �[��� PK ,�c\Ɇ���j �j ( ~�0 doc/alt-openldap11-devel/rfc/rfc3296.txtnu �[��� PK -�c\]&�0 �0 ( �.1 doc/alt-openldap11-devel/rfc/rfc2293.txtnu �[��� PK .�c\�� � ( &`1 doc/alt-openldap11-devel/rfc/rfc4519.txtnu �[��� PK .�c\�h _ _ ( b^2 doc/alt-openldap11-devel/rfc/rfc3672.txtnu �[��� PK .�c\\r��)� )� ( 9�2 doc/alt-openldap11-devel/rfc/rfc2713.txtnu �[��� PK .�c\��� � ( �]3 doc/alt-openldap11-devel/rfc/rfc4521.txtnu �[��� PK .�c\h� ��D �D ( +�3 doc/alt-openldap11-devel/rfc/rfc3698.txtnu �[��� PK .�c\��W��= �= ( *4 doc/alt-openldap11-devel/rfc/rfc2891.txtnu �[��� PK .�c\V��Dn n ( Nh4 doc/alt-openldap11-devel/rfc/rfc4518.txtnu �[��� PK .�c\�&�*J *J ( ��4 doc/alt-openldap11-devel/rfc/rfc4531.txtnu �[��� PK .�c\���� �� > .!5 doc/alt-openldap11-devel/drafts/draft-howard-rfc2307bis-xx.txtnu �[��� PK /�c\[���j �j L m�5 doc/alt-openldap11-devel/drafts/draft-zeilenga-ldap-c-api-concurrency-xx.txtnu �[��� PK /�c\�-M�= �= F �Z6 doc/alt-openldap11-devel/drafts/draft-sermersheim-ldap-chaining-xx.txtnu �[��� PK /�c\�=���I �I C �6 doc/alt-openldap11-devel/drafts/draft-ietf-ldapext-acl-model-xx.txtnu �[��� PK /�c\�7�yL yL G *�7 doc/alt-openldap11-devel/drafts/draft-ietf-ldapext-ldapv3-dupent-xx.txtnu �[��� PK /�c\�Ӑ ( ( F 08 doc/alt-openldap11-devel/drafts/draft-zeilenga-ldap-dontusecopy-xx.txtnu �[��� PK /�c\��f�1� 1� > �X8 doc/alt-openldap11-devel/drafts/draft-wahl-ldap-session-xx.txtnu �[��� PK /�c\2��u] ] ? O�8 doc/alt-openldap11-devel/drafts/draft-legg-ldap-transfer-xx.txtnu �[��� PK /�c\����R+ R+ O �?9 doc/alt-openldap11-devel/drafts/draft-sermersheim-ldap-subordinate-scope-xx.txtnu �[��� PK /�c\U�x��N �N H �k9 doc/alt-openldap11-devel/drafts/draft-behera-ldap-password-policy-xx.txtnu �[��� PK /�c\J� I I F ��: doc/alt-openldap11-devel/drafts/draft-sermersheim-ldap-distproc-xx.txtnu �[��� PK /�c\�H��� � > @< doc/alt-openldap11-devel/drafts/draft-legg-ldap-acm-bac-xx.txtnu �[��� PK /�c\)��N� N� D ń= doc/alt-openldap11-devel/drafts/draft-ietf-ldapext-ldap-c-api-xx.txtnu �[��� PK 0�c\��aw�- �- ? �P@ doc/alt-openldap11-devel/drafts/draft-zeilenga-ldap-noop-xx.txtnu �[��� PK 0�c\�_���Y �Y = �~@ doc/alt-openldap11-devel/drafts/draft-zeilenga-ldap-relax.txtnu �[��� PK 0�c\?ᕕ\2 \2 E ��@ doc/alt-openldap11-devel/drafts/draft-masarati-ldap-whatfailed-xx.txtnu �[��� PK 0�c\B<u|?6 ?6 9 � A doc/alt-openldap11-devel/drafts/draft-chu-ldap-csn-xx.txtnu �[��� PK 0�c\А{�ˉ ˉ D bBA doc/alt-openldap11-devel/drafts/draft-ietf-ldapext-ldapv3-vlv-xx.txtnu �[��� PK 0�c\l�ۜ�8 �8 @ ��A doc/alt-openldap11-devel/drafts/draft-ietf-ldapext-locate-xx.txtnu �[��� PK 0�c\`Q�< �< ; �B doc/alt-openldap11-devel/drafts/draft-chu-ldap-ldapi-xx.txtnu �[��� PK 0�c\��ت; �; < �BB doc/alt-openldap11-devel/drafts/draft-legg-ldap-admin-xx.txtnu �[��� PK 0�c\4ߓ�� �� A �~B doc/alt-openldap11-devel/drafts/draft-joslin-config-schema-xx.txtnu �[��� PK 0�c\�� ?V ?V A �}C doc/alt-openldap11-devel/drafts/draft-sermersheim-ldap-csn-xx.txtnu �[��� PK 0�c\�Z�(� (� C ��C doc/alt-openldap11-devel/drafts/draft-haripriya-dynamicgroup-xx.txtnu �[��� PK 1�c\g��R5F 5F @ EeD doc/alt-openldap11-devel/drafts/draft-legg-ldap-acm-admin-xx.txtnu �[��� PK 1�c\� h�� � & �D doc/alt-openldap11-devel/drafts/READMEnu �[��� PK 1�c\�"��yw yw L �D doc/alt-openldap11-devel/drafts/draft-lachman-laser-ldap-mail-routing-xx.txtnu �[��� PK 1�c\n,ʥ5S 5S > 'E doc/alt-openldap11-devel/drafts/draft-chu-ldap-xordered-xx.txtnu �[��� PK 1�c\r��JE< E< @ �zE doc/alt-openldap11-devel/drafts/draft-masarati-ldap-deref-xx.txtnu �[��� PK KWi\�h�W�" �" [�E doc/pycurl/RELEASE-NOTES.rstnu �[��� PK KWi\�W�z�/ �/ Y�E doc/pycurl/INSTALL.rstnu �[��� PK KWi\1-��p� p� Q F doc/pycurl/ChangeLognu �[��� PK KWi\>X"V�g �g G doc/pycurl/COPYING-LGPLnu �[��� PK KWi\FX� U U �kG doc/pycurl/examples/linksys.pynu �[��� PK KWi\>�! ? G�G doc/pycurl/examples/__pycache__/retriever-multi.cpython-312.pycnu �[��� PK KWi\)i=� 7 ��G doc/pycurl/examples/__pycache__/sfquery.cpython-312.pycnu �[��� PK KWi\����� � C E�G doc/pycurl/examples/__pycache__/opensocketexception.cpython-312.pycnu �[��� PK KWi\��u� � ? s�G doc/pycurl/examples/__pycache__/ssh_keyfunction.cpython-312.pycnu �[��� PK KWi\��τ�� �� 7 ��G doc/pycurl/examples/__pycache__/linksys.cpython-312.pycnu �[��� PK KWi\�^ d� � 9 �xH doc/pycurl/examples/__pycache__/retriever.cpython-312.pycnu �[��� PK KWi\��� � ; �H doc/pycurl/examples/__pycache__/file_upload.cpython-312.pycnu �[��� PK KWi\X �� � 4 ?�H doc/pycurl/examples/__pycache__/smtp.cpython-312.pycnu �[��� PK KWi\F��m� � ; R�H doc/pycurl/examples/__pycache__/xmlrpc_curl.cpython-312.pycnu �[��� PK KWi\I?(� � J e�H doc/pycurl/examples/__pycache__/multi-socket_action-select.cpython-312.pycnu �[��� PK LWi\m��F : ��H doc/pycurl/examples/__pycache__/basicfirst.cpython-312.pycnu �[��� PK LWi\�8�� � " ��H doc/pycurl/examples/xmlrpc_curl.pynu �[��� PK LWi\ѹ�+� � " ��H doc/pycurl/examples/file_upload.pynu �[��� PK LWi\�!#�i i ��H doc/pycurl/examples/retriever.pynu �[��� PK LWi\O�X_] ] * z�H doc/pycurl/examples/opensocketexception.pynu �[��� PK LWi\%�ק & 1�H doc/pycurl/examples/retriever-multi.pynu �[��� PK LWi\� � � ��H doc/pycurl/examples/sfquery.pynu �[��� PK LWi\�p�K K ��H doc/pycurl/examples/smtp.pynu �[��� PK LWi\�О� � 3 #�H doc/pycurl/examples/quickstart/get_python3_https.pynu �[��� PK LWi\� b,� � - L�H doc/pycurl/examples/quickstart/get_python2.pynu �[��� PK LWi\�ԃ+, , * h I doc/pycurl/examples/quickstart/put_file.pynu �[��� PK LWi\)ى٭ � L �I doc/pycurl/examples/quickstart/__pycache__/get_python3_https.cpython-312.pycnu �[��� PK LWi\���_) ) D I doc/pycurl/examples/quickstart/__pycache__/form_post.cpython-312.pycnu �[��� PK LWi\\��]| | > � I doc/pycurl/examples/quickstart/__pycache__/get.cpython-312.pycnu �[��� PK LWi\��G�� � E � I doc/pycurl/examples/quickstart/__pycache__/put_buffer.cpython-312.pycnu �[��� PK LWi\y �0� � F �I doc/pycurl/examples/quickstart/__pycache__/get_python2.cpython-312.pycnu �[��� PK LWi\R�fzp p L I doc/pycurl/examples/quickstart/__pycache__/get_python2_https.cpython-312.pycnu �[��� PK LWi\t��� � H �I doc/pycurl/examples/quickstart/__pycache__/response_info.cpython-312.pycnu �[��� PK LWi\~ǞM M J Y I doc/pycurl/examples/quickstart/__pycache__/follow_redirect.cpython-312.pycnu �[��� PK LWi\g,� F I doc/pycurl/examples/quickstart/__pycache__/get_python3.cpython-312.pycnu �[��� PK LWi\e%2� � K �#I doc/pycurl/examples/quickstart/__pycache__/file_upload_real.cpython-312.pycnu �[��� PK LWi\���ɴ � E �&I doc/pycurl/examples/quickstart/__pycache__/write_file.cpython-312.pycnu �[��� PK LWi\�� � � K �)I doc/pycurl/examples/quickstart/__pycache__/response_headers.cpython-312.pycnu �[��� PK LWi\ #A$4 4 Q 2I doc/pycurl/examples/quickstart/__pycache__/file_upload_real_fancy.cpython-312.pycnu �[��� PK LWi\��Ő� � M �5I doc/pycurl/examples/quickstart/__pycache__/file_upload_buffer.cpython-312.pycnu �[��� PK LWi\5�os� � C A9I doc/pycurl/examples/quickstart/__pycache__/put_file.cpython-312.pycnu �[��� PK LWi\[�7 7 4 �<I doc/pycurl/examples/quickstart/file_upload_buffer.pynu �[��� PK LWi\�YQ1 1 2 <>I doc/pycurl/examples/quickstart/response_headers.pynu �[��� PK LWi\i%�� � / �FI doc/pycurl/examples/quickstart/response_info.pynu �[��� PK LWi\�%� � � 3 II doc/pycurl/examples/quickstart/get_python2_https.pynu �[��� PK LWi\�� �G G % uKI doc/pycurl/examples/quickstart/get.pynu �[��� PK LWi\WJ�A4 4 + NI doc/pycurl/examples/quickstart/form_post.pynu �[��� PK LWi\��� � - �PI doc/pycurl/examples/quickstart/get_python3.pynu �[��� PK LWi\p$�� � , �RI doc/pycurl/examples/quickstart/put_buffer.pynu �[��� PK LWi\h�PW� � 8 �TI doc/pycurl/examples/quickstart/file_upload_real_fancy.pynu �[��� PK LWi\���e e , WI doc/pycurl/examples/quickstart/write_file.pynu �[��� PK LWi\��~,� � 1 �XI doc/pycurl/examples/quickstart/follow_redirect.pynu �[��� PK LWi\�~(�# # 2 +ZI doc/pycurl/examples/quickstart/file_upload_real.pynu �[��� PK LWi\3���? ? 1 �[I doc/pycurl/examples/multi-socket_action-select.pynu �[��� PK LWi\^�7�. . & P{I doc/pycurl/examples/ssh_keyfunction.pynu �[��� PK LWi\8� ! ! ! �|I doc/pycurl/examples/basicfirst.pynu �[��� PK LWi\]��a� � FI doc/pycurl/AUTHORSnu �[��� PK LWi\H�wf f z�I doc/pycurl/README.rstnu �[��� PK LWi\�0l�� � %�I doc/pycurl/COPYING-MITnu �[��� PK �Yj\���Va a �I doc/alt-liblqr-1/ChangeLognu �[��� PK �Yj\|�wfK� K� ��I doc/alt-liblqr-1/COPYINGnu �[��� PK �Yj\;bx6, , LHJ doc/alt-liblqr-1/READMEnu �[��� PK YY�� �XJ