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.
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 ”.
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”.
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. |