This section demonstrates how to write a plug-in that encodes passwords. The plug-in also allows Directory Server to compare stored passwords with passwords provided by a client application.
The examples in this chapter do not constitute a secure password storage scheme.
The source for the example plug-in referenced in this chapter is install-path/examples/testpwdstore.c. For encoding and comparing, the plug-in performs an exclusive or with 42 on each character of the 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 the example encode function, xorenc(), is as follows:
static char * xorenc(char * pwd);
Allocate space for the encoded password with slapi_ch_malloc() rather than regular malloc(). Directory Server can then terminate with an “out of memory” message if allocation fails memory with slapi_ch_free().
By convention, you prefix the encoded password with the name of the password storage scheme, enclosed in braces, { and }. In other words, the example plug-in is called XOR.
The name is declared in the example:
static char * name = "XOR"; /* Storage scheme name */
You return encoded strings prefixed with {XOR}. You also register the name with Directory Server.
#include "slapi-plugin.h" static char * name ="XOR"; /* Storage scheme name */ #define PREFIX_START '{' #define PREFIX_END '}' static char * xorenc(char * pwd) { char * tmp = NULL; /* Used for encoding */ char * head = NULL; /* Encoded password */ char * cipher = NULL; /* Prefix, then pwd */ int i, len; /* Allocate space to build the encoded password */ len = strlen(pwd); tmp = slapi_ch_malloc(len + 1); if (tmp == NULL) return NULL; memset(tmp, '\0', len + 1); head = tmp; /* Encode. This example is not secure by any means. */ for (i = 0; i < len; i++, pwd++, tmp++) *tmp = *pwd ^ 42; /* Add the prefix to the cipher */ if (tmp != NULL) { cipher = slapi_ch_malloc(3 + strlen(name) + strlen(head)); if (cipher != NULL) { sprintf(cipher,"%c%s%c%s",PREFIX_START,name,PREFIX_END,head); } } slapi_ch_free((void **) &head); return (cipher); /* Server frees cipher */ }
Notice that you 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(), see Chapter 16, Function Reference, Part I.
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 zero, 0, if the input password matches the password from the directory. The function returns 1 otherwise. The prototype for the example compare function, xorcmp(), is therefore as follows:
static int xorcmp(char * userpwd, char * dbpwd);
Here, userpwd is the input password. 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.
#include "slapi-plugin.h" static int xorcmp(char * userpwd, char * dbpwd) { /* Check the correspondence of the two char by char */ int i, len = strlen(userpwd); for (i = 0; i < len; i++) { if ((userpwd[i] ^ 42) != dbpwd[i]) return 1; /* Different passwords */ } return 0; /* Identical passwords */ }
Notice that Directory Server strips the prefix from the password before passing the value to the compare function. In other words, you need not account for {XOR} in this case.
Not all encoding algorithms have such a trivial compare function.
You must register four password storage scheme specific items with Directory Server:
The storage scheme name that is used for the prefix
The encode function
The compare function
The decode function
Notice that you provide no decoding function. In this case, Directory Server does not decode user passwords after they are stored.
#include "slapi-plugin.h" static char * name ="XOR"; /* Storage scheme name */ static Slapi_PluginDesc desc = { "xor-password-storage-scheme", /* Plug-in identifier */ "Sun Microsystems, Inc.", /* Vendor name */ "6.0", /* Revision number */ "Exclusive-or example (XOR)" /* Plug-in description */ }; #ifdef _WIN32 __declspec(dllexport) #endif int xor_init(Slapi_PBlock * pb) { int rc = 0; /* 0 means success */ rc |= slapi_pblock_set( /* Plug-in API version */ pb, SLAPI_PLUGIN_VERSION, (void *) SLAPI_PLUGIN_CURRENT_VERSION ); rc |= slapi_pblock_set( /* Plug-in description */ pb, SLAPI_PLUGIN_DESCRIPTION, (void *) &desc ); rc |= slapi_pblock_set( /* Storage scheme name */ pb, SLAPI_PLUGIN_PWD_STORAGE_SCHEME_NAME, (void *) name ); rc |= slapi_pblock_set( /* Encode password */ pb, SLAPI_PLUGIN_PWD_STORAGE_SCHEME_ENC_FN, (void *) xorenc ); rc |= slapi_pblock_set( /* Compare password */ pb, SLAPI_PLUGIN_PWD_STORAGE_SCHEME_CMP_FN, (void *) xorcmp ); rc |= slapi_pblock_set( /* Never decode pwd */ pb, SLAPI_PLUGIN_PWD_STORAGE_SCHEME_DEC_FN, NULL ); return rc; }
Set up a directory instance ad build the plug-in if you have not done so already.
If you have not already done so, build the example plug-in library and activate both plug-in informational logging and the example plug-in.
Build the plug-in.
Hint Use install-path/examples/Makefile or install-path/examples/Makefile64.
Configure Directory Server to log plug-in informational messages and load the plug-in.
Hint Use the commands specified in the comments at the outset of the plug-in source file.
Restart Directory Server.
$ dsadm restart instance-path |
If you have not done so already, set up a directory instance with a suffix, dc=example,dc=com, containing data loaded from a sample LDIF file, install-path/ds6/ldif/Example.ldif.
Create a new Directory Server instance.
For example:
$ dsadm create /local/ds Choose the Directory Manager password: Confirm the Directory Manager password: $ |
Start the new Directory Server instance.
For example:
$ dsadm start /local/ds Server started: pid=4705 $ |
Create a suffix called dc=example,dc=com.
For example, with long lines folded for the printed page:
$ dsconf create-suffix -h localhost -p 1389 dc=example,dc=com Enter "cn=directory manager" password: Certificate "CN=defaultCert, CN=hostname:1636" presented by the server is not trusted. Type "Y" to accept, "y" to accept just once, "n" to refuse, "d" for more details: Y $ |
Load the sample LDIF.
For example, with long lines folded for the printed page:
$ dsconf import -h localhost -p 1389 \ /opt/SUNWdsee/ds6/ldif/Example.ldif dc=example,dc=com Enter "cn=directory manager" password: New data will override existing data of the suffix "dc=example,dc=com". Initialization will have to be performed on replicated suffixes. Do you want to continue [y/n] ? y ## Index buffering enabled with bucket size 16 ## Beginning import job... ## Processing file "/opt/SUNWdsee/ds6/ldif/Example.ldif" ## Finished scanning file "/opt/SUNWdsee/ds6/ldif/Example.ldif" (160 entries) ## Workers finished; cleaning up... ## Workers cleaned up. ## Cleaning up producer thread... ## Indexing complete. ## Starting numsubordinates attribute generation. This may take a while, please wait for further activity reports. ## Numsubordinates attribute generation complete. Flushing caches... ## Closing files... ## Import complete. Processed 160 entries in 5 seconds. (32.00 entries/sec) Task completed (slapd exit code: 0). $ |
You can use Directory Service Control Center to perform this task. For more information, see the Directory Service Control Center online help.
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.
Before you do anything else, quickly check that Directory Server calls the plug-in encode function as expected. To perform this quick test, use the pwdhash tool. The pwdhash tool has Directory Server encode a password, then display the result.
$ pwdhash -D /local/ds -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, you can fix the plug-in library. Then try pwdhash without doing anything to Directory Server. If this quick test does not work, fix the example.
Here, you use the XOR scheme to encode a new password for Barbara Jensen.
Change the password storage scheme for the suffix to XOR.
$ dsconf set-server-prop -h localhost -p 1389 pwd-storage-scheme:XOR |
Change Barbara’s password to password.
View Barbara’s newly encoded password.
$ ldapsearch -h localhost -p 1389 -b dc=example,dc=com uid=bjensen version: 1 dn: uid=bjensen, ou=People, dc=example,dc=com cn: Barbara Jensen cn: Babs Jensen sn: Jensen givenName: Barbara objectClass: top objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson ou: Product Development ou: People l: Cupertino uid: bjensen mail: bjensen@example.com telephoneNumber: +1 408 555 1862 facsimileTelephoneNumber: +1 408 555 1992 roomNumber: 0209 userPassword: {XOR}ZKYY]EXN |
Notice that Barbara’s password is XOR-encoded.
Barbara has the right to search other entries under dc=example,dc=com. Here, you search for Kirsten Vaughan's entry as bjensen.
$ ldapsearch -h localhost -p 1389 -b dc=example,dc=com -D uid=bjensen,ou=People,dc=example,dc=com -w password uid=kvaughan version: 1 dn: uid=kvaughan, ou=People, dc=example,dc=com cn: Kirsten Vaughan sn: Vaughan givenName: Kirsten objectClass: top objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson ou: Human Resources ou: People l: Sunnyvale uid: kvaughan mail: kvaughan@example.com telephoneNumber: +1 408 555 5625 facsimileTelephoneNumber: +1 408 555 3372 roomNumber: 2871 |
You know that Directory Server uses a plug-in to check Barbara’s password during the bind. Thus, Directory Server must have used the XOR plug-in because you saw that Barbara’s password was XOR-encoded. If the whole process appears to work, you can conclude that the compare function works, too.