6.2. How setpin Works

The PIN Generator generates PINs for user entries in an LDAP directory and updates the directory with these PINs. To run the setpin command, the following five options are required:
  • The host name (host) and port number (port) of the LDAP server
  • The bind DN (binddn) and password (bindpw)
  • An LDAP filter (filter) for filtering out the user entries that require PINs
The setpin command looks like the following:
setpin host=csldap port=19000 binddn="CN=Directory Manager" bindpw=secret filter="(ou=employees)" basedn="dc=example,dc=com"
This example queries the directory for all the entries in the employees organizational unit (ou). For each entry matching the filter, information is printed out to standard error and to the standard output.

Note

Because the PIN Generator makes a lot of changes to the directory, it is important to use the correct filter, or the wrong entries are modified. Using the write option is a safeguard because no changes are made to the directory unless that option is used. This allows the PINs to be verified before any entries are modified.
The information can be written to a different output file by using the output option; see Section 6.2.2, “Output File” for more information. The entries returned by the LDAP search filter can be further restricted by using an ASCII input file which lists the entry DNs; only entries matching those in the file are updated. The input file is set with the input option. The input file is not a substitute for the LDAP directory entries; the filter attribute must still be provided. For more information about the input file, refer to Section 6.2.1, “Input File”. Figure 6.1, “Using an Input and Output File When Generating PINs” shows how the input and output files work with the setpin tool.
Using an Input and Output File When Generating PINs

Figure 6.1. Using an Input and Output File When Generating PINs

The output file contains the entry and PIN information from running setpin, as shown in the following example:
Processing: cn=QA Managers,ou=employees,dc=example,dc=com
Adding new pin/password
dn:cn=QA Managers,ou=employees,dc=example,dc=com
pin:lDWynV
status:notwritten

Processing: cn=PD Managers,ou=employees,dc=example,dc=com
Adding new pin/password
dn:cn=PD Managers,ou=employees,dc=example,dc=com
pin:G69uV7
status:notwritten
The output also contains the status of each entry in the directory. The status values are listed in Table 6.1, “PIN Generator Status ”.

Table 6.1. PIN Generator Status

Exit Code Description
notwritten The PINs were not written to the directory because the write option was not used.
writefailed The tool tried to modify the directory, but the write operation was unsuccessful.
added The tool added the new PIN to the directory successfully.
replaced The tool replaced an old PIN with a new one; this means the clobber option was used.
notreplaced The tool did not replace the old PIN with a new one; this means the clobber option was not used.
If a PIN already exists for a user, it is not changed if the setpin command is run a second time. This allows new PINs to be created for new users without overwriting PINs for users who have already received a PIN. To overwrite a PIN, use the clobber option.
After making sure that the filter is matching the right users, run the setpin command again with the write option and with output set to the name of the file to capture the unhoused PINs. For details about the output file, refer to Section 6.2.2, “Output File”.

6.2.1. Input File

The PIN Generator can receive a list of DNs to modify in a text file specified by the input argument. If an input file is specified, then the tool compares the DNs returned by the filtered to the ones in the input file and updates only those DNs that match in the input file.
The input enables the user to provide the PIN Generator with an exact list of DNs to modify; it is also possible to provide the PIN Generator with PINs in plain text for all DNs or for specific DNs.
There are two common situations when using an input file is useful:
  • If PINs have been set for all entries in the user directory, and new users join the organization. For the new users to get certificates, the directory must contain PINs. PINs should be generated for only those two entries without changing any of the other user entries. Instead of constructing a complex LDAP filter, using an input file allows using a general filter, and the modified entries are restricted to the DNs of the two users listed in the input file.
  • If a particular values, such as Social Security numbers, should be used as PINs, then the Social Security numbers can be put in the input file and provide those numbers as PINs to the PIN Generator. These are then stored as hashed values in the directory.
The format of the input file is the same as that of the output file (refer to Section 6.2.2, “Output File”) except for the status line. In the input file, PINs can be set for all the DNs in the file, for specific DNs, or for none of the DNs. If the PIN attribute is missing for a DN, the tool automatically generates a random PIN.
An input file looks like the following example:
dn:cn=user1, dc=example,dc=com

dn:cn=user2, dc=example,dc=com

...
dn:cn=user3, dc=example,dc=com
PINs can also be provided for the DNs in plain-text format; these PINs are hashed according to the command-line arguments.
dn:cn=user1, dc=example,dc=com
pin:pl229Ab

dn:cn=user2, dc=example,dc=com
pin:9j65dSf

...
dn:cn=user3, dc=example,dc=com
pin:3knAg60

Note

Hashed PINs cannot be provided to the tool.

6.2.2. Output File

The PIN Generator can capture the output to a text file specified by the output option.
The output contains a sequence of records in the following format:
dn: user_dn1
pin: generated_pin1
status: status1

dn: user_dn2
pin: generated_pin2
status: status2

...
dn: user_dn#
pin: generated_pin#
status: status#
where user_dn is a distinguished name matching the DN filter or listed in the input file. By default, the delimiter is a semi-colon (;) or the character defined on the command line. generated_pin is a string of characters of fixed or variable length, depending on the length parameters used. status is one of the values listed Table 6.1, “PIN Generator Status ”.
The first line in each record is always the DN. The subsequent lines for pin and status are optional. The record ends with a blank line, using the Unix end of line sequence (\n).

6.2.3. How PINs Are Stored in the Directory

Each PIN is concatenated with the corresponding LDAP attribute named in the saltattribute argument (which defaults to the entry DN, the recommended value). If this argument is not specified, the DN is used.
That string is hashed with the routine specified in the hash argument; the default algorithm is SHA-1, but this should be set to none so that it works with Directory Servers which restrict the use of incoming hashed passwords.
One byte is prepended to indicate the hash type used. The PIN is stored as follows:
byte[0] = X
The value of X depends on the hash algorithm chosen during the PIN generation process.
X Hash Algorithm
0 SHA-1
1 MD5
45 none
The PIN is stored in the directory as a binary value, not as a base-64 encoded value.

6.2.4. Exit Codes

When the PIN Generator is finished running, it returns a result code showing how it ended. These result codes are listed in Table 6.2, “Result Codes Returned by the PIN Generator”.

Table 6.2. Result Codes Returned by the PIN Generator

Result Code Description
0 The PIN generation was successful; PINs were set for all the DNs in the specified directory.
4 The tool could not bind to the directory as the user specified in the binddn parameter.
5 The tool could not open the output file specified in the output parameter.
7 There was an error parsing command-line arguments.
8 The tool could not open the input file specified in the input parameter.
9 The tool encountered an internal error.
10 The tool found a duplicate entry in the input file.
11 The tool did not find the salt attribute specified in the saltattribute parameter in the directory.