| Security

## Using Arbitrary SASL Mechanisms

> > Note: The descriptions and examples presented here are based on a preview of a proposed Java SASL API standard (version 5). Although these examples work with version 1.2.3 of the LDAP provider, the APIs are still subject to change, depending on the evolution of the Java SASL API.

> The LDAP provider has built-in support for several SASL mechanisms. To use other SASL mechanisms, you must make the classes for the mechanisms available to your program (for example by adding them to your classpath) and inform the SASL framework of their availability. You can achieve the latter in one of three ways.
> 1. Set the `"javax.security.sasl.client.pkgs"` environment property to the package name of the factory class that creates implementations for SASL mechanisms.
> 2. Set the `"javax.security.sasl.client.pkgs"` system property to the package name of the factory class that creates implementations for SASL mechanisms.
> 3. Put the fully qualified name of the factory class in the file `META-INF/services/com.sun.security.sasl.preview.SaslClientFactory`.
> The third option is the most transparent and preferred way.

> Here is an example that uses a package (`examples`) that contains a custom SASL mechanism.

> >     // Specify the package name for SASL to search for the mechanism factories
> >     env.put("javax.security.sasl.client.pkgs", "examples");

> >     // Use the bogus SASL mechanism name
> >     env.put(Context.SECURITY_AUTHENTICATION, "SAMPLE");

> The program first adds the package `examples` to the list of packages to search for SASL mechanisms (actually, mechanism factories). It then requests a SASL mechanism (`"SAMPLE"`) from that package.

> Alternatively, instead of setting the `"javax.security.sasl.client.pkgs"` environment property, you can place the fully qualified name of the factory class (`examples.ClientFactory`) in the file `META-INF/services/com.sun.security.sasl.preview.SaslClientFactory` as follows.

> >     examples.ClientFactory

> When you run the program, the `"SAMPLE"` SASL mechanism implementation class (`SampleMech`) prints a debug message to indicate that it has been invoked. When the program communicates with the LDAP server, the server will return an `AuthenticationNotSupportedException` because `"SAMPLE"` is a bogus mechanism.

> You can use a similar technique to access a SASL mechanism that the LDAP server does support. Do this by using an appropriate value for the SASL mechanism name and the package name of the mechanism implementation. SASL mechanism implementations are typically provided by vendors and must follow the interfaces and guidelines outlined in the Java SASL API.

| Security