Calling Entry Store and Entry Fetch Plug-Ins

This section describes when entry store and entry fetch plug-ins are called. This section also describes how entries are expected to be handled by the plug-in.

The server calls entry store plug-in functions before writing data to a directory database. It calls entry fetch plug-in functions after reading data from the directory database. Entry store and entry fetch plug-ins may therefore typically be used to encrypt and decrypt directory entries, or to perform auditing work.

Using LDIF String Parameters

Unlike other types of plug-ins, entry store and entry fetch plug-in functions do not take a parameter block as an argument. Instead, the functions take two parameters, the LDIF string representation of an entry and the length of the string. Directory Server uses the modified LDIF string after the plug-in returns successfully. An example prototype for an entry store plug-in function is as follows:

int my_entrystore_fn(char ** entry, unsigned int * length);

Plug-in functions can manipulate the string as necessary. Entry store and entry fetch plug-ins return zero, 0, on success. When the function returns, Directory Server expects entry and length to contain the modified versions of the parameters.

Locating the Entry Store and Entry Fetch Examples

The plug-in function examples in this chapter can be found in install-path/examples/testentry.c.

The following example shows the entry store scrambling function used in this chapter. This function is called by Directory Server before writing an entry to the database.

Example 8-1 Entry Fetch Scrambler (testentry.c)

#include "slapi-plugin.h"

#ifdef _WIN32
typedef unsigned int uint;
__declspec(dllexport)
#endif
int
testentry_scramble(unsigned char ** entry, uint * len)
{
    uint i;

    (*len)++;
    *entry = slapi_ch_realloc(*entry, *len);
    /* Scramble using bitwise exclusive-or on each character.     */
    for (i = *len - 1; i > 0; i--) {
         (*entry)[i] = (*entry)[i - 1] ^ 0xaa;
    }
    (*entry)[0] = 0xaa;

    slapi_log_info_ex(
        SLAPI_LOG_INFO_AREA_PLUGIN,
        SLAPI_LOG_INFO_LEVEL_DEFAULT,
        SLAPI_LOG_NO_MSGID,
        SLAPI_LOG_NO_CONNID,
        SLAPI_LOG_NO_OPID,
        "testentry_scramble in test-entry plug-in",
        "Entry data scrambled.\n"
    );

    return 0;
}

The following example shows the entry fetch unscrambling function used in this chapter. The function is called by the server after reading an entry from the database.

Example 8-2 Entry Fetch UnScrambler (testentry.c)

#include "slapi-plugin.h"

#ifdef _WIN32
typedef unsigned int uint;
__declspec(dllexport)
#endif
int
testentry_unscramble(unsigned char ** entry, uint * len)
{
    uint i;

    /* Return now if the entry is not scrambled.                  */
    if (**entry != 0xaa) { return 0; }

    /* Unscramble using bitwise exclusive-or on each character.   */
    (*len)--;
    for (i = 0; i < *len; i++) {
        (*entry)[i] = (*entry)[i + 1] ^ 0xaa;
    }

    slapi_log_info_ex(
        SLAPI_LOG_INFO_AREA_PLUGIN,
        SLAPI_LOG_INFO_LEVEL_DEFAULT,
        SLAPI_LOG_NO_MSGID,
        SLAPI_LOG_NO_CONNID,
        SLAPI_LOG_NO_OPID,
        "testentry_unscramble in test-entry plug-in",
        "Entry data unscrambled.\n"
    );

    return 0;
}

Notice the symmetry between the two functions. The scrambling mask, 0xaa or 10101010 in binary, makes the transformation simple to understand but not secure. A secure encryption mechanism can be significantly more complicated.