Whole document tree

Please send feedback to jndi@java.sun.com

Table of Contents

 

1. Introduction

2. Conformance

3. Environment Properties

4. Names

5. Attributes

6. URLs

7. Java Objects

8. Schema

9. Exceptions

10. API Mapping

11. Federation

12. SASL

13. Extensions and Controls

14. Event Notification

15. SSL

1. Introduction

Not all of the features described in this document must be supported by an LDAP service provider. However, if a feature is supported, it should be supported in the way described by this document.

2. Conformance

•  RFC 2251 and related specifications.

•  RFC 1777  and related specifications.

3. Environment Properties

There are four types of environment properties that affect LDAP service providers:

• Standard JNDI environment properties
• LDAP-specific environment properties
• Provider-specific environment properties
• Feature-specific environment properties

3.1 Overview

3.1.1 Initialization

In particular, if any of the following properties is not supplied in the environment properties then it is sought from the system properties, applet parameters, and both provider and application resource files (in that order):

• java.naming.factory.control
• java.naming.factory.initial
• java.naming.factory.object
• java.naming.factory.state
• java.naming.provider.url

A context's environment properties can be examined using the Context.getEnvironment method.

3.1.2 Modification

3.1.3 Scope

3.1.4 Timeliness

3.1.5 Defaults

When a property is removed from the environment properties of a context, the context assumes the default behavior specified for that property. This does not necessarily mean that the default value must be recorded as the property's value. The removal may also be indicated by the absence of the property from the context's environment properties.

3.1.6 Acceptable Values

3.2 JNDI Properties

The value of this property is a string of decimal digits that specifies the batch size of search results returned by the server.

This property affects the blocking behaviour of the Context.list, Context.listBindings, and DirContext.search methods and the NamingEnumeration objects that they return. It does not affect how many items are returned in the enumeration; it only affects how the items are batched or read at the LDAP protocol level.

A setting of zero means that the provider should block until all results have been received. A setting of an integer n greater than zero means that the provider should block until n results have been received from the server or until the enumeration terminates, whichever produces the fewer number of results. After the application has read n results (using NamingEnumeration.next or NamingEnumeration.nextElement), the provider should read n more results from the server or until the enumeration terminates, whichever produces the fewer number of results.

If this property is not set then its default value is implementation-specific.

For example,

env.put(Context.BATCHSIZE, "24");

specifies that the provider should block until 24 entries have been read from the server or until the enumeration terminates, whichever produces the fewer number of results.

The value of this property is a colon-separated list of fully qualified class names of control factory classes.

The factories are responsible for narrowing the class of response controls. They create specific response controls from the generic response controls generated by the provider.

No default value is defined for this property.

For example,

env.put(LdapContext.CONTROL_FACTORIES,
        "com.sun.jndi.ldap.ctl.ResponseControlFactory");

sets the ResponseControlFactory class as the control factory to try.

The value of this property is the fully qualified class name of the factory class which creates the initial context for the LDAP service provider.

It is used to select a particular LDAP service provider; it's not actually used by the provider itself. This property need not be set when the name argument to initial context methods is a URL.

No default value is defined for this property.

For example,

env.put(Context.INITIAL_CONTEXT_FACTORY,
        "com.sun.jndi.ldap.LdapCtxFactory");

selects Sun's LDAP provider.

The value of this property is a colon-separated list of fully qualified class names of object factory classes.

The factories are responsible for creating specific objects from the LDAP entries returned by the provider. For example, a Person object factory might generate a Person object from an LDAP entry of object class person. Object factories behave in the opposite way to state factories in that they generate objects from LDAP attributes.

No default value is defined for this property.

For example,

env.put(Context.OBJECT_FACTORIES,
        "com.sun.jndi.ldap.obj.PersonFromLDAP");

sets the PersonFromLDAP class as the object factory to try.

The value of this property is a colon-separated list of fully qualified class names of state factory classes.

The factories are responsible for creating an object's state (for storing) from the object itself. For example, a Person state factory might generate an LDAP entry of object class person from a Person object. State factories behave in the opposite way to object factories in that they generate LDAP attributes from objects.

No default value is defined for this property.

For example,

env.put(Context.STATE_FACTORIES,
        "com.sun.jndi.ldap.obj.PersonToLDAP");

sets the PersonToLDAP class as the state factory to try.

The value of this property is a string language tag according to RFC 1766.

This property indicates a preference for a particular natural language. A provider may adjust its LDAP requests and responses according to the value of this property.

The affect of this property is implementation-specific. No default value is defined.

For example:

env.put(Context.LANGUAGE, "ja-JP");

indicates a preference for Japanese.

The value of this property is a URL string that specifies the hostname and port number of the LDAP server, and the root distinguished name of the naming context to use.

See LDAP URL for information on how to treat other information found in the URL.

The default hostname is localhost; the default port is 389. The default root distinguished name is the empty string. If this property is not set, or if either the hostname or port number is omitted, then the default values are used in place of the missing information.

For example:

env.put(Context.PROVIDER_URL, "ldap://secserver:636");

specifies that the LDAP server is running on a host named secserver at port 636.

NOTE: Changing this property using the Context.addToEnvironment or Context.removeFromEnvironment methods does not affect the context. It is only used by the initial context constructors.

The value of this property is a string that specifies how referrals shall be handled by the provider. The following values are defined for this property:

follow

automatically follow any referrals.

throw

throw a ReferralException for each referral.

ignore

ignore referrals if they appear in results. A PartialResultException is thrown to indicate an incomplete result. In addition, for LDAPv3 servers, the provider shall request that referrals be treated as ordinary attributes when they appear in entries. This is achieved by sending a non-critical ManageDsaIT (draft-ietf-ldapext-namedref-00.txt) LDAP control with each LDAP request. LDAP servers which do not support this LDAP control will simply ignore it and process the request as normal.

See LDAP URL for information on how to treat multiple URLs found in a single referral entry.

If this property is not set then its default value is ignore.

For example:

env.put(Context.REFERRAL, "throw");

specifies that referrals encountered during an LDAP operation should throw a ReferralException to the application.

The value of this property is a string that specifies the authentication mechanism(s) for the provider to use. The following values are defined for this property:

none

use no authentication (anonymous bind).

simple

use simple authentication (a cleartext password).

A space-separated list of one or more SASL mechanism names:

use the first available SASL mechanism in the list that conforms to the specified policy requirements

See the SASL section for information on how this property is used for SASL authentication. See  RFC 2829  for information on LDAP authentication mechanisms.

If this property is not set then its default value is none, unless the java.naming.security.credentials property is set, in which case the default value is simple. If this property is set to a value that the provider does not recognize or support, it should throw AuthenticationNotSupportedException.

For example:

env.put(Context.SECURITY_AUTHENTICATION, "simple");

specifies that simple authentication be used to authenticate to the LDAP server. Or,

env.put(Context.SECURITY_AUTHENTICATION, "DIGEST-MD5 CRAM-MD5");

specifies that DIGEST-MD5 authentication be used and, if that SASL mechanism is unavailable, that CRAM-MD5 authentication be used. If neither is available then throw AuthenticationNotSupportedException.

The value of this property is an object that specifies the credentials of the principal to be authenticated. Its format and handling depends on the value of the  java.naming.security.authentication property.

For anonymous binds, this property is ignored - an empty string is always used for the credentials. For simple authentication and SASL authentication that requires a password, the value of this property may be supplied as a java.lang.String, a char[] or a byte[]. If it is a String or a char[] then it is encoded into a byte array using UTF-8 in the case of LDAPv3 and encoded using ISO-Latin-1 in the case of LDAPv2. If it is a byte[] then it is used as is.

See the SASL section for information on how this property is used for SASL authentication.

No default value is defined for this property.

For example:

env.put(Context.SECURITY_CREDENTIALS, "secret");

sets the credentials to be the string "secret".

The value of this property is a string that specifies the identity of the principal to be authenticated. Its format depends on the authentication type; see RFC 2829  for more information. The value is used as the name component in an LDAP ASN.1 BindRequest for non-SASL authentication. For SASL authentication, the value of this property is used as the authentication ID for SASL mechanisms that need an authentication ID.

The provider is not required to verify the validity of the principal name. It may, for example, just pass the string to be verified by the server. If the principal identified is not a valid principal then the provider shall throw an AuthenticationException.

No default value is defined for this property.

For example:

env.put(Context.SECURITY_PRINCIPAL, "cn=admin,o=sun,c=us");

sets the principal name to be the distinguished name "cn=admin, o=sun, c=us".

The value of this property is a string that specifies the security protocol for the provider to use. The following value is defined for this property:
 

ssl

use Secure Sockets Layer version 3.0.

If this property is set to ssl, the provider must use SSL sockets, or throw ConfigurationException if it is unable to do so. In addition to the value listed above, a provider may support other security protocols. However, such provider-specific protocols might not be supported by all providers. If this property is set to a security protocol that the provider does not recognize or support, it should throw ConfigurationException.

If the  java.naming.ldap.factory.socket  property is set, then the socket factory identified by that property must create sockets that are appropriate for this protocol setting. For example, if the security protocol is set to ssl, then the socket factory must create SSL-compliant sockets.

If this property is not set then the default is to use no security protocol.

As a developer of the LDAP provider, you should be aware that using SSL to connect to a server on a port that is not listening for SSL connections causes the socket to hang. Similarly, using a plain socket to connect to a server that is listening for SSL connections also leads to hanging. This is a characteristic of the protocol that some implementations may choose to correct but is not otherwise required to do so. The provider's documentation, however, should describe this behavior to its users. See SSL for information on how to use SSL.

For example:

env.put(Context.SECURITY_PROTOCOL, "ssl");

specifies that SSL-compliant sockets be used to communicate with the server.

3.3 LDAP-specific Properties

The value of this property is a string of space-separated attribute names. It specifies attributes which have non-string syntax. It extends the provider's built-in list of non-string attributes (below). The value of an attribute that has non-string syntax is returned as a byte array (byte[]) instead of a String.

No default is defined. If this property is not set then only the following attributes are considered to have non-string syntax:

Attribute ID	OID	Reference
Any attribute ID with the ";binary" option.
photo	0.9.2342.19200300.100.1.7	RFC 1274
personalSignature	0.9.2342.19200300.100.1.53	RFC 1274
audio	0.9.2342.19200300.100.1.55	RFC 1274
jpegPhoto	0.9.2342.19200300.100.1.60	RFC 2798
javaSerializedData	1.3.6.1.4.1.42.2.27.4.1.7	RFC 2713
thumbnailPhoto	2.16.128.113533.1.1400.1	NAC LIP Schema
thumbnailLogo	2.16.128.113533.1.1400.2	NAC LIP Schema
userPassword	2.5.4.35	RFC 2256
userCertificate	2.5.4.36	RFC 2256
cACertificate	2.5.4.37	RFC 2256
authorityRevocationList	2.5.4.38	RFC 2256
certificateRevocationList	2.5.4.39	RFC 2256
crossCertificatePair	2.5.4.40	RFC 2256
x500UniqueIdentifier	2.5.4.45	RFC 2256

For example:

env.put("java.naming.ldap.attributes.binary",
        "mpegVideo myspecialkey");

informs the provider to return values of the mpegVideo and myspecialkey attributes as byte[].

java.naming.ldap.control.connect

The value of this property is a Control[] object.  It sets the connection request controls that are active on a connection. See LdapContext.

No default value is defined for this property.

For example:

env.put("java.naming.ldap.control.connect",
        new Control[]{ new ManageReferralControl(true) });

sets a critical ManageDsaIT LDAP control as the connection request control.

java.naming.ldap.deleteRDN

The value of this property is a string that specifies whether the old RDN is removed by the Context.rename method. The following values are defined for this property:
 

true

delete the old RDN from the entry during the rename operation.

false

retain the old RDN as an attribute value of the entry.

 

If this property is not set then its default value is true.

For example:

env.put("java.naming.ldap.deleteRDN", "false");

causes the old RDN to be retained as an attribute of the renamed entry.

The value of this property is a string that specifies how aliases are dereferenced during search operations. The following values are defined for this property:

always

always dereference aliases.

never

never dereference aliases.

finding

dereference aliases only during name resolution (that is, while locating the target entry).

searching

dereference aliases once name resolution has completed (that is, after locating the target entry).

If this property is not set then its default value is always.

For example:

env.put("java.naming.ldap.derefAliases", "searching");

causes the provider to dereference aliases only once the target entry has been located.

NOTE: this property is unrelated to the dereference-links flag in the SearchControls object.

The value of this property is a string identifying the class name of a socket factory.

This property is used to override the default socket factory. The class specified in this property must implement the javax.net.SocketFactory interface. See http://java.sun.com/products/jsse/doc/guide/API_users_guide.html for more information. See SSL for information on how to use SSL.

In addition, if the  java.naming.security.protocol  property is set, then the socket factory identified by this property must create sockets which are appropriate for that protocol setting. For example, if the security protocol is set to ssl then the socket factory must create SSL-compliant sockets.

No default is defined for this property.

For example:

env.put("java.naming.ldap.factory.socket",
        "javax.net.ssl.SSLSocketFactory");

sets the socket factory of the provider to be javax.net.ssl.SSLSocketFactory.

The value of this property is a string containing the character to use when encoding a RefAddr object in the javaReferenceAddress attribute (see Java Objects).

This property is used to avoid a conflict in the case where the default separator character appears in the components of a RefAddr object.

If this property is not set then its default value is '#' (the hash character).

For example:

env.put("java.naming.ldap.ref.separator", ":");

specifies that the separator ':' (the colon character) be used when storing RefAddr instances.

The value of this property is a string of decimal digits specifying the maximum number of referrals to follow in a chain of referrals. A setting of zero indicates that there is no limit.

If this property is not set then the default value is 10.

For example:

env.put("java.naming.ldap.referral.limit", "5");

specifies that the referral limit is 5.

The value of this property is a string that specifies whether only attribute IDs are returned in results - attribute values are omitted. Affects the SearchResult.getAttributes and DirContext.getAttributes methods. The following values are defined for this property:
 

true

return only attribute IDs.

false

return both attribute IDs and attribute values.

If this property is not set then its default value is false.

For example:

env.put("java.naming.ldap.typesOnly", "true");

causes the server to return attribute IDs but not attribute values.

The value of this property is a string that specifies the protocol version for the provider. The following values are defined for this property:
 

2

selects LDAP version 2 (LDAPv2).

3

selects LDAP version 3 (LDAPv3).

If this property is not set then the provider first attempts to bind using LDAP v3 and fails over to using LDAP v2 if a protocol error is received from the server. This failover mechanism is only used when the java.naming.security.authentication property indicates anonymous bind or simple authentication.

For example:

env.put("java.naming.ldap.version", "2");

requests the LDAP provider to communicate with the server using LDAPv2.

3.4 Feature-specific Properties

3.4.1 SASL Properties

java.naming.security.sasl.authorizationId

The value of this property is a string that specifies the authorization ID for the SASL mechanisms.

If this property is not set, then the authorization ID passed to the SASL mechanisms is the empty string. According to SASL (RFC 2222), using an authorization ID of the empty string directs the server to derive an authorization ID from the client's authentication credentials.

For example:

env.put("java.naming.security.sasl.authorizationId",
        "dn:cn=administrators,ou=groups,o=sun,c=us");

specifies the identity to use for authorization (access control) upon successful authentication.

java.naming.security.sasl.realm

The value of this property is a string that specifies the realm information required by some SASL mechanisms such as DIGEST-MD5.

If this property is not set, then a mechanism-specific default such as that negotiated between the client and server during the authentication exchange is used.

For example:

env.put("java.naming.security.sasl.realm", "webusers");

specifies that the client wants to use the "webusers" realm for authentication.

java.naming.security.sasl.callback

The value of this property is an instance of javax.security.auth.callback.CallbackHandler. When the provider uses a SASL mechanism that requires callbacks, the SASL mechanism uses the object supplied in the property. The callback handler should satisfy a NameCallback by supplying the authentication ID.

If this property is not set, then the provider should use a default callback handler that satisfies the NameCallback using the value of the java.naming.security.principal property, satisfies the PasswordCallback using the value of the java.naming.security.credentials property, and satisfies the RealmCallback and RealmChoiceCallback (described in the Java SASL API) using the value of the java.naming.security.sasl.realm property.

For example:

env.put("java.naming.security.sasl.callback",
        new MyCallbackHandler());

supplies an instance of the callback handler for SASL mechanisms to use.

The value of this property is a '|'-separated list of package names used to locate factories that produce SASL mechanism drivers.

The value of this property is a ','-separated list of quality-of-protection (qop) values used to specify the client's qop preference. A qop value is one of

• "auth" - authentication only
• "auth-int" - authentication plus integrity protection
• "auth-conf" - authentication plus integrity and confidentiality protection

The order of the list specifies the preference order. If this property is absent, the default qop is "auth".

The value of this property is a ','-separated list of cipher strength values used to specify the client's preference. A strength value is one of

• "low"
• "medium"
• "high"

The order of the list specifies the preference order. If this property is absent, the default strength is "high,medium,low".

For privacy in DIGEST-MD5, "high" maps to "3des", "medium" to "rc4" or "des", and "low" to "rc4-56" or "rc4-40".

The value of this property is the string representation of an integer that specifies the maximum size of the receive buffer in bytes that the client is willing to receive. If this property is absent, the default size is defined by the SASL mechanism.

The value of this property is either "true" or "false", specifying whether the server must authenticate to the client or not, respectively. If this property is absent, the default is "false".

The value of this property is either "true" or "false", specifying whether the selected SASL mechanism must support forward secrecy between sessions or not, respectively. If this property is absent, the default is "false".

The value of this property is either "true" or "false", specifying whether the selected SASL mechanism must require client credentials or not, respectively. If this property is absent, the default is "false".

The value of this property is either "true" or "false", specifying whether the selected SASL mechanism must not be susceptible to simple plain passive attacks or not, respectively. If this property is absent, the default is "false".

The value of this property is either "true" or "false", specifying whether the selected SASL mechanism must not be susceptible to active (non-dictionary) attacks or not, respectively. If this property is absent, the default is "false".

The value of this property is either "true" or "false", specifying whether the selected SASL mechanism must not be susceptible to dictionary attacks or not, respectively. If this property is absent, the default is "false".

The value of this property is either "true" or "false", specifying whether the selected SASL mechanism must not accept anonymous logins or not, respectively. If this property is absent, the default is "false".

3.5 Provider-specific Properties

4. Names

1. String names supplied as parameters to the context methods are in the composite name syntax.
The first component of the composite name is an LDAP distinguished name while the rest of the components are used for federation.
2. If a Name argument is a CompositeName object then its first component is assumed to be an LDAP distinguished name and the remaining components (if any) are used for federation.
3. If a Name argument is not a CompositeName object then all of its components are assumed to be the parsed form of an LDAP distinguished name. That is, each Name component is an LDAP relative distinguished name (RDN).
4. Names are parsed using the name parser returned by the Context.getNameParser method. The parser accepts LDAP distinguished names as String objects and produces LDAP distinguished names as Name objects.
5. Names returned by context operations are string composite names or string URLs.

CN=Steve Kille, O=Isode Limited, C=GB

OU=Sales+CN=J. Smith, O=Widget Inc., C=US

CN=L. Eagle, O=Sue\, Grabbit and Runn, C=GB

        Attributes attrs = lctx.getAttributes("cn=John Smith");

Similarly, when a context is enumerated using any of the enumeration methods (Context.list, Context.listBindings, DirContext.search), the names returned are relative to the target context--the context being enumerated.  When referrals are invoked, instead of a relative name, an LDAP URL string, containing the fully qualified name, is returned. The format of LDAP URLs is defined in RFC 2255.

LDAP URLs that follow RFC 2255 may be supplied to any of the context methods. The hostname and port number are extracted from the URL and used to contact the LDAP server; the java.naming.factory.initial and java.naming.provider.url properties are ignored. For example,

    DirContext ictx = new InitialDirContext();
    Attributes attrs = ictx.getAttributes(
        "ldap://wserver:389/cn=John Smith,dc=widget,dc=com");

This code fragment contacts the LDAP server at machine wserver at port 389.

5. Attributes

The LDAP provider expects as input and returns as output all attribute values as either String or byte[] objects.  See the java.naming.ldap.attributes.binary environment property for which ones are treated as byte[] and how to extend the list.

6. URLs

ldap://host:port/dn?attributes?scope?filter?extensions

URLs play a role in several places in JNDI:

1. Configuration of service providers.

To configure an LDAP service provider, you typically supply an LDAP URL in the java.naming.provider.url property. This is used by the LDAP service provider to configure its connection to the directory server. Only the host, port, and dn parts of the URL are relevant in this setting. Supplying other parts of the URL results in a ConfigurationException.
 
2. Argument to initial context methods.

If a URL string (with syntax scheme_id:rest_of_name) is passed to the methods in InitialContext, either as a String argument or as the first component of Name, the URL's scheme id is used to locate the context factory for handling that scheme. If none is found, the URL string is treated as an ordinary name and passed to the initial context specified by the java.naming.factory.initial property is used. See the java.naming.spi.NamingManager.getURLContext method for details on how URL context factories are located. Note that this support for LDAP URLs as names is only available in the initial context.

With the exception of the search methods, when an LDAP URL is passed as a name to the initial context, the URL should not contain any query ('?') components. Otherwise, an InvalidNameException is thrown by the service provider. For the search methods, the query components of the URL override any corresponding components supplied as arguments. For example, if an LDAP URL containing a scope component is supplied, then that scope overrides any scope setting that may be passed in a SearchControls argument.
 

3. Referrals.

An LDAP referral contains a list of one or more URLs. To process an LDAP referral (either explicitly or implicitly by setting the java.naming.referral property), the service provider needs to use the information in the these URLs to create connections to LDAP servers to which they refer. When multiple LDAP URLs are present in a single referral they are treated as alternatives and each is followed until one succeeds. The complete URL (that is, including any query components) are used.
 
4. Returned as a name in list and search enumerations.

When the name of the entry being returned has a name that is not relative to the target context (i.e., the starting context for the list or search), the name is returned as a URL. See the NameClassPair.isRelative method for details.
 
5. Argument to the getObjectInstance method of NamingManager or DirectoryManager.

When an LDAP namespace is federated underneath another namespace (for example, such as DNS), the information that is stored in the superior namespace might be an LDAP URL. In such a scenario, a lookup/list/search operation in the superior namespace would return a Reference containing an LDAP URL for the LDAP namespace. The service provider for the superior namespace would pass the Reference to the getObjectInstance method to create an instance of an LDAP context.

7. Java Objects

7.1 Storing

• Context.bind()
• Context.rebind()
• DirContext.bind()
• DirContext.rebind()

1. Instances of Reference
2. Objects that implement the Referenceable interface
3. Objects that implement the Serializable interface
4. Objects that implement the DirContext interface

References, referenceable and serializable objects should be stored according to RFC 2713. DirContext objects should be stored by storing their attributes.

When storing a reference's list of RefAddr into the javaReferenceAddress attribute, the separator to use for delimiting the address's position, type and content are controlled using the environment property java.naming.ldap.ref.separator. If this environment property is not specified, the hash character '#' should be used as the separator.

The provider uses the DirectoryManager.getStateToBind method when storing objects in the directory. This allows objects of any type to be transformed into one of the four categories listed above so that they can be stored into the directory.

7.2 Reading

• Context.lookup()
• Context.lookupLink()
• Binding.getObject()

8.0 Schema

• AttributeDefinition
• ClassDefinition
• SyntaxDefinition

Permission to modify the contents of the schema tree is determined by the directory administrator. When the schema tree is modified, the changes are made to schema stored on the directory server.

8.1 Schema Tree Structure

• MatchingRule
• ExtensionDefinition
• ControlDefinition
• SASLDefinition

 

Any or all of these bindings may be absent if the underlying directory does not publish such schema information, or the service provider does not support retrieving them. If these names are present in the root schema context, however, they must have the binding specified in the above table.

The attribute names and values of these entries' attributes are case-insensitive.

8.2 Attribute Definitions

Each object in the "AttributeDefinition" context has the following mandatory and optional attributes:
 

These attributes have a 1-to-1 correspondence with the names defined in RFC 2252 for "AttributeTypeDescription." All the attribute values are represented by the java.lang.String class.

You can, for example, obtain the object representing the "cn" attribute using the following code:

DirContext schema = ctx.getSchema(""); // get schema tree
DirContext cnSchema = schema.lookup("AttributeDefinition/cn");

NUMERICOID      2.5.4.3
NAME            cn
SYNTAX          1.3.6.1.4.1.1466.115.121.1.15
DESC            Standard Attribute, alias for commonName

Attributes attrs = ctx.getAttributes("cn=John", new String[]{"cn"});
Attribute cnAttr = attrs.get("cn");
DirContext cnSchema = cnAttr.getAttributeDefinition();

8.3 Object Class Definitions

Each object in the "ClassDefinition" context has the following mandatory and optional attributes:
 

These attributes have a 1-to-1 correspondence with the names defined in RFC 2252 for "ObjectClassDescription." All the attribute values are represented by the java.lang.String class.

You can, for example, obtain the object representing the "country" object class using the following code:

DirContext schema = ctx.getSchema(""); // get schema tree
DirContext countrySchema = schema.lookup("ClassDefinition/country");

NUMERICOID      2.5.6.2
NAME            country
MAY             aci, searchguide, description
MUST            objectclass, c
DESC            Standard ObjectClass
SUP             top

// Read object from directory
DirContext countryObj = (DirContext)ctx.lookup("c=us", new String[]{"country"});

// Get all of object's object class definitions
DirContext objClasses = countryAttr.getSchemaClassDefinition();

// Pick out "country" object class in particular
DirContext countryClass = (DirContext)objClasses.lookup("country");

8.4 Syntax Definitions

Each object in "SyntaxDefinition" context has the following mandatory and optional attributes:
 

These attributes have a 1-to-1 correspondence with the names defined in RFC 2252 for "SyntaxDescription." All the attribute values are represented by the java.lang.String class.

You can, for example, obtain the object representing the "1.3.6.1.4.1.1466.115.121.1.15" syntax using the following code:

DirContext schema = ctx.getSchema(""); // get schema tree
DirContext dirStringSchema = 
    schema.lookup("SyntaxDefinition/1.3.6.1.4.1.1466.115.121.1.15");

NUMERICOID      1.3.6.1.4.1.1466.115.121.1.15
DESC            Directory String

Attributes attrs = ctx.getAttributes("c=us", new String[]{"country"});
Attribute countryAttr = attrs.get("country");
DirContext dirStringSchema = countryAttr.getSyntaxAttributeDefinition();

8.5 Matching Rules

When a matching rule is an extensible matching rule, it must also contain an "APPLIES" attribute listing the attributes to which this extensible matching rule can be applied.

Each object in "MatchingRule" context has the following mandatory and optional attributes:
 

These attributes have a 1-to-1 correspondence with the names defined in RFC 2252 for "MatchingRuleDescription" and "MatchingRuleUseDescription." All the attribute values are represented by the java.lang.String class.

You can, for example, obtain the object representing the "soundAlikeMatch" syntax using the following code:

DirContext schema = ctx.getSchema(""); // get schema tree
DirContext soundMatchSchema = 
    schema.lookup("MatchingRule/soundAlikeMatch");

NUMERICOID      1.2.3.4.5
NAME            soundAlikeMatch
SYNTAX          1.3.6.1.4.1.1466.115.121.1.15 (for directory string)
APPLIES         2.5.4.41, 2.5.4.15
DESC            Home-grown Phonetic match

8.6 Extension Definitions

Each object in "ExtensionDefinition" context has the following mandatory and optional attributes:
 

All the attribute values are represented by the java.lang.String class.

You can, for example, obtain the object representing the Start TLS extension ("1.3.6.1.4.1.1466.20037") using the following code:

DirContext schema = ctx.getSchema(""); // get schema tree
DirContext startTLSSchema = 
    schema.lookup("ExtensionDefinition/1.3.6.1.4.1.1466.20037");

NUMERICOID      1.3.6.1.4.1.1466.20037
DESC            Start TLS (see RFC 2830)

8.7 Control Definitions

Each object in "ControlDefinition" context has the following mandatory and optional attributes:
 

All the attribute values are represented by the java.lang.String class.

You can, for example, obtain the object representing the server-side sorting control ("1.2.840.113556.1.4.473") using the following code:

DirContext schema = ctx.getSchema(""); // get schema tree
DirContext svrSortSchema = 
    schema.lookup("ControlDefinition/1.2.840.113556.1.4.473");

NUMERICOID      1.2.840.113556.1.4.473
DESC            server-side sorting of search results

8.8 SASL Mechanisms

Each object in "SASLMechanism" context has the following mandatory and optional attributes:
 

All the attribute values are represented by the java.lang.String class.

You can, for example, obtain the object representing the EXTERNAL SASL mechanism using the following code:

DirContext schema = ctx.getSchema(""); // get schema tree
DirContext saslExternalSchema = 
    schema.lookup("SASLMechanism/EXTERNAL");

NAME      EXTERNAL
DESC      EXTERNAL SASL mechanism (RFC 2222)

9. Exceptions

10. API Mapping

Register a listener for receiving naming events that take place in the specified subtree of LDAP entries. LDAP servers notify clients of events by means of LDAP controls attached to LDAP operation responses or by means of an LDAP unsolicited notifications. Such responses are then processed by the LDAP provider and indicated to the application in the form of NamingEvent or UnsolicitedNotificationEvent.

Update context's environment properties. If multiple contexts share the same set of environment properties, the provider should take care to only modify the intended context's environment. Changing an environment property might require changes to the existing connection the context is using.

Supplying null for the property value has the same effect as removing the property.

For all environment properties, the new property is recorded even if it does not affect the context. See the Environment Properties section.

Perform an LDAP add operation to create a new entry in the directory. The DirContext.bind method can accept null as the object to bind if it is also supplied a non-null set of attributes. Otherwise, if the method is given insufficient information (i.e., no object or attributes), no entry can be added. If an object is provided in the arguments, then it is converted into attributes and stored in the entry along with any supplied attributes, as described in the Java Objects section. The provider should use the DirectoryManager.getStateToBind method to transform the input object into a form that it can store.

If the provider does not support binding any objects in the directory then it should throw OperationNotSupportedException. Otherwise, if it does support binding objects but does not support the supplied object then it should throw IllegalArgumentException.

Release resources associated with context. For example, if the connection being used by this context is not shared with another context, the provider may abandon any outstanding requests and close the network connection to the server. Precisely which resources are released is implementation-dependent.

Context.composeName

If the parent context is from the same LDAP namespace, then concatenate the names according to the LDAP name syntax described in Context.getNameParser(). Otherwise, concatenate the names as composite names.

Perform an LDAP add operation to create the named entry and its associated attributes. If no attributes are supplied then the objectClass attribute is generated with the values top and javaContainer (javaContainer is a structural class that is necessary to avoid a schema violation error).

Perform an LDAP delete operation to remove the named entry and its associated attributes. The named entry must be a leaf entry; subtrees are not removed. If the leaf entry does not exist (but its parent exists), the operation still succeeds.

Perform an LDAP extended operation.

Perform an LDAP base-object search operation to retrieve the LDAP entry's attributes. Use "(objectclass=*)" as the filter.

If the list of requested attributes is null or contains the special attribute identifier '*' then all the user attributes at the LDAP entry are returned. If operational attributes are required then those attribute identifiers must be present in the list of requested attributes.

Retrieve the connection request controls in effect for LDAP bind operations invoked on this context.

Return the environment properties recorded at the context.

Context.getNameInNamespace

Return the LDAP distinguished name of the context.

Context.getNameParser

Return a name parser that parses LDAP names according to RFC 2253.

Retrieve the request controls in effect for LDAP operations subsequently invoked on this context.

Retrieve the response controls returned by the last LDAP operation invoked on this context.

See the Schema Section.

See the Schema Section.

Perform an LDAP one-level search operation of the named entry using the filter "(objectclass=*)" to retrieve the names of the entries immediately below the named entry.

Ask for, at a minimum, the javaClassName attributes so that the class name of each entry can be determined. If the class name cannot be determined, return javax.naming.directory.DirContext as the class name.

The names which are returned are either relative to the named context or they are LDAP URLs.

Perform an LDAP one-level search operation of the named entry using the filter "(objectclass=*)" to retrieve the attributes representing objects (or object references). Request the attributes for reconstructing the Java object and possibly other attributes as well. See Java Objects on how to reconstruct the object. If the object cannot be reconstructed according to RFC 2713 then return a DirContext object representing the LDAP entry. The provider should use the DirectoryManager.getObjectInstance method to satisfy calls to the Binding.getObject method.

The names which are returned are either relative to the named context or they are LDAP URLs.

Perform an LDAP base-object search operation of the named entry using the filter "(objectclass=*)". Request (possibly all) the attributes for reconstructing the Java object. See Java Objects on how to reconstruct the object. The provider should use the DirectoryManager.getObjectInstance method to satisfy calls to the Binding.getObject method.

Perform an LDAP modify operation at the named entry using the supplied modifications. For the overloaded method that accepts an Attributes, first convert the Attributes argument into an ordered list of modifications by enumerating its contents using Attributes.getAll() and reusing the modification operation argument (mod_op).

Initialize an new instance of this context with the specified request controls.

Context.rebind

DirContext.rebind

This method may involve several different LDAP operations. First get the existing entry's attributes. If the existing entry does not exist, this method behaves the same as bind(). Otherwise, if no attributes have been supplied and the object being bound is DirContext, invoke DirContext.getAttributes() and use the result as the attributes argument (attrs). If there are still no attributes, use the original entry's attributes as attrs. Remove the existing entry using the LDAP delete operation. Convert the object provided in the arguments into attributes (as described in the Java Objects section) and store in the entry along with attrs using the LDAP add operation. The provider should use the DirectoryManager.getStateToBind method to transform the input object into a form that it can store.

LdapContext.reconnect

Reconnect to the LDAP server using the supplied connection request controls and the current environment properties.

Context.removeFromEnvironment

Remove context's environment properties. If multiple contexts share the same set of environment properties, the provider should take care to only modify the intended context's environment. Changing an environment property might require changes to the existing connection the context is using.

For all environment properties, the new property is recorded even if it does not affect the context. Removing a property should cause the context to assume the property's default.

EventContext.removeNamingListener

Deregister a naming event listener so that subsequent events destined for that listener are not delivered.

Perform an LDAP modify DN operation to rename the entry. If LDAPv2 is being used then the new name and the old name must share the same immediate parent name. If the parents are not equal then throw InvalidNameException.

Note the effect of the  java.naming.ldap.deleteRDN  property on the behavior of this method.

Perform an LDAP search operation according to the specified search controls.

If the list of requested attributes is null or contains the special attribute identifier '*' then all the user attributes at the LDAP entry are returned. If operational attributes are required then those attribute identifiers must be present in the list of requested attributes.

If objects are requested to be returned, then the Java object-related attributes (RFC 2713) are requested in addition to any requested by the API user. If these attributes are present then they are used to assemble the original objects (see Java Objects). If the object cannot be reconstructed according to RFC 2713 then return a DirContext object representing the LDAP entry. The provider should use the DirectoryManager.getObjectInstance method to satisfy calls to the Binding.getObject method.

The names which are returned are either relative to the named context or they are LDAP URLs.

The provider may use an LDAP compare operation instead of an LDAP search when the search filter supplied is suitably constrained:
 

The filter must be of the form "(<attributeID>=<value>)"

The scope must be object scope

Zero attributes must be requested (empty returning-attributes list)

In the forms of search that accept a string filter as argument, the syntax of the filter follows RFC 2254 with the exception that Unicode characters are also allowed. The use of Unicode characters is preferable to the use of encoded UTF-8 octets. The service provider is responsible for translating the Unicode characters into their corresponding UTF-8 representation for transmission to the server. For example, the Greek letter alpha can be specified in the string filter either as "\u03B1" or as "\\CE\\B1".

In the form search(Name, Attributes) and related methods, the Attributes argument is converted into a string filter by creating a conjunctive expression out of its elements. Each attribute value is treated as a literal; therefore '*' and other special characters defined in RFC 2254 that appear in the values of an attribute should be escaped according to the rules in RFC 2254. For example, an attribute value of '*' should be encoded as the string "\\2a".

In the form search(Name, String filterExpr, Object[] filterArgs) and its String overloaded method, "{num}" expansion is done in the filter by putting in values from filterArgs. Each "{num}" component may appear in the place of "attr" or "value" in Section 4 from RFC 2254.

The objects in filterArgs should be encoded in the following way:
 

byte arrays (byte[]) are encoded by encoding each byte as a string according to RFC 2254. For example, the array {0, 1, 10, 100} is encoded as the string "\\00\\01\\0a\\64".

Strings are treated as literals. In other words, '*' and other special characters defined in RFC 2254 that appear in the string are escaped according to the rules in RFC 2254. For example, a string of "*" is encoded as the string "\\2a".

Objects that are neither String nor byte[] are converted to their string form using Object.toString() and then the rules for String applied.

Set the request controls for LDAP operations subsequently invoked on this context.

Determine whether a listener can register interest in an LDAP entry that doesn't exist.

Perform an LDAP delete operation to remove the named entry. The named entry must be a leaf entry; subtrees are not removed. If the leaf entry does not exist (but its parents exist), the operation still succeeds.

11. Federation

12. SASL

The Java SASL API depends on the Java Authentication and Authorization Service (JAAS), which provides callback support for SASL mechanisms that need to obtain or supply user/application information directly.

12.1 SASL Configuration

Some SASL mechanisms require the identity of the entity being authenticated. This is known as the authentication ID. Some SASL mechanisms, like DIGEST-MD5, require the use of a password and/or a realm. By default, the provider supplies the value of java.naming.security.principal property as the authentication ID to any SASL mechanism that requires the authentication ID, the value of the java.naming.security.credentials property as the password, and the value of the java.naming.security.sasl.realm property as the realm. To override these defaults, use the java.naming.security.sasl.callback property.

SASL mechanisms support the notion of authorization identity or authorization ID, which is the entity to which the server should grant access if the authentication succeeds.  If the java.naming.security.sasl.authorizationId property has been set, then its value is used as the authorization ID. Otherwise, the empty string is used as the authorization ID, which directs the server to derive an authorization ID from the client's authentication credentials.

See SASL properties for a description of the properties used by an LDAP service provider for supporting SASL.

In addition to these properties, there might be properties required for specific SASL mechanisms. For example, a SASL mechanism that supports privacy and integrity needs to know the quality of protection that the client requires. Properties such as these are passed to the SASL mechanism via the environment properties. See the JNDI documentation for how to set environment properties.

For example, if the application needs privacy, it can do so by using a call such as:

     env.put("javax.security.sasl.qop", "auth-conf");

before passing env to the initial context constructor. See the Java SASL API for details about these properties.

12.2 SASL Mechanism Drivers

13. Extensions and Controls

Several LDAP extensions and controls are defined by the IETF LDAPEXT working group.

14. Event Notification

A JNDI application can register for events that occur in the directory, such as the addition or removal of an entry, or the modification of an entry. Applications can also register for unsolicited notifications.

15. SSL

env.put(Context.SECURITY_PROTOCOL, "ssl");

If, in addition, LDAP authentication is also required then the java.naming.security.authentication, java.naming.security.principal, and java.naming.security.credentials environment properties should be set, as appropriate. If LDAP authentication is required and the SSL credentials should be reused for LDAP authentication then set the java.naming.security.authentication environment property to select the SASL EXTERNAL mechanism, as follows:

        env.put(Context.SECURITY_AUTHENTICATION, "EXTERNAL");