|
| Sun ONE Directory Server 5.2 Plug-In API Programming Guide |
Chapter 11 Writing Password Storage Scheme Plug-Ins
This chapter covers how to write plug-ins that let you modify how Directory Server stores password attribute values.
This chapter includes the following sections:
Calling Password Storage Scheme Plug-Ins
This section describes the circumstances in which Directory Server calls password storage scheme plug-ins and how password values are expected to be handled by the plug-ins.
Two Types
Two types of password storage scheme plug-ins work with Directory Server, pwdstoragescheme and reverpwdstoragescheme. The former is one-way, in that once the server encodes and stores a password, the password is not decoded. The pwdstoragescheme type therefore includes plug-in functions only for encoding passwords to be stored and for comparing incoming passwords with encoded, stored passwords. The latter is reversible, in that the plug-in allows Directory Server both to encode and to decode passwords. The reverpwdstoragescheme type therefore includes encode, compare, and decode plug-in functions.
Note This chapter covers the one-way type pwdstoragescheme plug-ins.
Pre-Installed Schemes
Existing schemes delivered with Directory Server are provided as password storage scheme plug-ins. Search cn=config for entries whose DN contains cn=Password Storage Schemes. The default password storage scheme uses the Salted Secure Hashing Algorithm (SSHA).
You can change the password storage scheme used to encode user passwords. Refer to the Sun ONE Directory Server Administration Guide for instructions.
Affects Password Attribute Values
Password storage scheme plug-in functions act on password (userPassword) attribute values. Directory Server registers password storage scheme plug-ins at startup. After startup, any registered, enabled password storage scheme plug-in can then be used to encode password values, and to compare incoming passwords to the encoded values. Which plug-in Directory Server invokes depends on the password storage scheme used for the entry in question.
Invoked for Add and Modify Requests
Add and modify requests can imply that Directory Server encode an input password, and then store it in the directory. First, Directory Server determines the storage scheme for the password value. Next, it invokes the plug-in encode function for the appropriate scheme. The encode function returns the encoded password to Directory Server.
Invoked for Bind Requests
Bind requests imply that Directory Server compares an input password value to a stored password value. As for add and modify requests, Directory Server determines the storage scheme for the password value. Next, it invokes the plug-in compare function for the appropriate scheme. The compare scheme returns an int that communicates to Directory Server whether the two passwords match as described in "Comparing a Password".
Part of a Password Policy
Password storage scheme plug-ins typically do no more than encode passwords and compare input passwords with stored, encoded passwords. In other words, they represent only a part of a comprehensive password policy. Refer to the Sun ONE Directory Server Deployment Guide for suggestions on designing secure directory services.
Writing a Password Storage Scheme Plug-In
This section demonstrates how to write a plug-in that encodes passwords and allows Directory Server to compare stored passwords with passwords provided by a client application.
Caution
The example does not constitute a secure password storage scheme.
The source for the example plug-in referenced in this section is ServerRoot/plugins/slapd/slapi/examples/testpwdstore.c. For encoding and comparing, the plug-in performs an exclusive or with 42 on each character of the password.
Encoding a Password
When Directory Server calls a password storage scheme plug-in encode function, it passes that function an input password char * and expects an encoded password char * in return. The prototype for our example encode function, xorenc(), is:
static char * xorenc(char * pwd);
Allocate space for the encoded password using slapi_ch_malloc() rather than regular malloc(). Directory Server can then terminate with an "out of memory" message if allocation fails. Free memory using slapi_ch_free().
By convention, we prefix the encoded password with the common name, of the password storage scheme, enclosed in braces, { and }. In other words, our example plug-in has cn: XOR.
Our name is declared in the example:
static char * name = "XOR"; /* Storage scheme name */
We return encoded strings prefixed with {XOR}, and register that name with Directory Server.
Notice we free only memory allocated for temporary use. Directory Server frees memory for the char * returned, not the plug-in. For details on slapi_ch_malloc() and slapi_ch_free(), refer to the Sun ONE Directory Server Plug-In API Reference.
Comparing a Password
When Directory Server calls a password storage scheme plug-in compare function, it passes that function an input password char * and a stored, encoded password char * from the directory. The compare function returns 0 if the input password matches the password from the directory. It returns 1 otherwise. The prototype for our example compare function, xorcmp(), is therefore:
static int xorcmp(char * userpwd, char * dbpwd);
Here, userpwd is the input password and dbpwd is the password from the directory. The compare function must encode the input password to compare the result to the password from the directory.
Notice Directory Server strips the prefix from the password before passing it to the compare function. In other words, we need not account for {XOR} in this case.
Not all encoding algorithms have such a trivial compare function.
Registering the Plug-In
You must register four password storage scheme specific items with Directory Server: the storage scheme name (used for the prefix), the encode function, the compare function, and the decode function.
Notice we provide no decoding function. In this case, Directory Server never decodes user passwords once they are stored.
Creating a Configuration Entry
Build the plug-in if you have not done so already.
The configuration entry for the plug-in resembles other entries under cn=config whose DN contains cn=Password Storage Schemes. Create an LDIF file similar to that of Code Example 11-4.
Notice nsslapd-pluginEnabled must be set to on. Otherwise, no one can use the password storage scheme. Setting nsslapd-pluginEnabled to on does not suffice, however, for the plug-in to be used. In addition to enabling the plug-in, you must configure Directory Server to use the password storage scheme it provides.
Add the entry to the directory configuration. For example:
$ ldapmodify -a -p port -D "cn=Directory Manager" -w password -f file.ldif
Here, file.ldif contains the plug-in configuration entry.
Restart Directory Server so it loads the plug-in at startup:
$ ServerRoot/slapd-serverID/restart-slapd
At this point, the XOR password storage scheme plug-in should be enabled for Directory Server, and visible in the server configuration.
Trying It Out
This section demonstrates the example plug-in for this chapter. Plug the XOR password storage scheme into Directory Server if you have not done so already.
Perform a Quick Test
Before we do anything involved, quickly check that Directory Server manages to call the plug-in encode function as expected. To perform this quick test, we use the pwdhash tool. The pwdhash tool can be used to have Directory Server encode a password, then display the result.
Code Example 11-5 Testing the Password Storage Scheme
$ cd ServerRoot/bin/slapd/server
$ ./pwdhash -D ServerRoot/slapd-serverID -s XOR password
{XOR}ZKYY]EXN
Do not be concerned with the exact value of the resulting encoded password. The output should, however, start with {XOR}.
As Directory Server calls the encode function dynamically, we can fix the plug-in library, then try pwdhash again without touching Directory Server. That is, if this quick test does not work for you, now is a good time to fix the example.
Add Example Users with Clear Text Passwords
In order to experiment with user passwords, we need some users with passwords. Here, we create a directory suffix, dc=example,dc=com, whose users we load from an LDIF file, ServerRoot/slapd-serverID/ldif/Example-Plugin.ldif. The example user passwords appear in clear text in Example-Plugin.ldif.
Perform the following steps to load the example into the directory.
- Open the Directory Server Console.
- Use the console to create a new root suffix, dc=example,dc=com.
Hint Configuration tab page. Select Data node. Object > New Root Suffix.
- Set the password storage scheme to No encryption (CLEAR).
Hint Use the Password encryption drop-down list.
- Log in as cn=Directory Manager.
Hint Console > Log in as New User...
- Import entries from ServerRoot/slapd-serverID/ldif/Example-Plugin.ldif.
Hint Console > Import Databases...
Once the Example-Plugin.ldif entries have been imported, check that the user passwords appear in clear text. The console does not show passwords in clear text, so we use ldapsearch on the command line.
Notice that Yolanda Yorgensons's password is yyorgens.
Encode a Password with the XOR Scheme
Here we use the XOR scheme to encode a new password for Yolanda Yorgenson.
- As Directory Manager, set the password storage scheme for the suffix to Exclusive-or example (XOR).
Hint Use the Password encryption drop-down list.
- Change Yolanda's password to foobar12.
Hint Directory tab page. Select example/People. Double-click yyorgens.
- View Yolanda's newly encoded password.
Notice that Yolanda Yorgenson's password is XOR encoded.
Compare an XOR-Encoded Password
Yolanda has the right to search other entries under dc=example,dc=com. Here we search for Bartholomew Cubbins's entry as yyorgens.
We know Directory Server uses a plug-in to check Yolanda's password during the bind. In this case, Directory Server must have used the XOR plug-in, because we saw that Yolanda's password was XOR encoded. If the whole process appears to work, we can conclude that our compare function works, too.