The Pin Generator allows you to generate PINs for user entries in an LDAP-compliant directory and update the directory with these PINs. To run the setpin command, you need at a minimum to specify the following:
For example:
setpin host=laiking port=19000 "binddn=CN=Directory Manager" bindpw=netscape "filter=(ou=employees)" basedn=o=siroe.com
This command, if run, will query the directory for all the entries that match the filter criteria, which in this case is all users belonging to an organizational unit (ou) called employees. For each entry matching the filter, information is printed out to standard error. Additionally, to the standard output or the file named in output; see "Output File".
You can also provide the tool with an input argument using the input option. The argument must be in the form of an ASCII file of pre-prepared DNs and PINs (see Figure 11.1). Note that the input file isn't a substitute for the LDAP directory entries; the filter attribute must still be provided. If an input file is provided, the tool updates only those filtered attributes that match the ones in the input file. For more information about the input file, see "Input File"
Figure 11.1 Using an input and output file for the PIN-generation process
Examples of output follow:
Processing: cn=QA Managers,ou=employees,o=airius.com
Adding new pin/password
dn:cn=QA Managers,ou=employees,o=airius.com
pin:lDWynV
status:notwritten
Processing: cn=PD Managers,ou=employees,o=airius.com
Adding new pin/password
dn:cn=PD Managers,ou=employees,o=airius.com
pin:G69uV7
status:notwritten
Because the PIN Generator makes a lot of changes to your directory, it is important that you specify the correct filter; otherwise, you may change the wrong entries. As a safeguard, a write option is provided that you use to enable writing to the directory after you verify the output; the tool doesn't make any changes to the directory until you specify the write option on the command line.
The output also contains the status of each entry in the directory. It can be one of the values specified in Table 11.1.
If a PIN already exists for a user, it will by default not be changed if you run the setpin command a second time. This is so that you can generate PINs for new users without overwriting PINs for users who have previously been notified of their PINs. If you want to overwrite a PIN, you should use the clobber option.
Once you are sure that the filter is matching the right users, you should run the setpin command again with the write option, and with output set to the name of the file to capture the unhashed PINs. This output file is in the same format as the input file. For details about the output file, see "Output File".
Input File
The PIN Generator can receive a list of DNs to modify in a text file specified by the input=<file_name> argument. If you specify an input file, the tool compares the DNs it filtered from the LDAP directory with the ones in the input file, and updates only those DNs that matched the ones in the input file.
The purpose of the input file is multifold. It enables you to provide the Pin Generator with an exact list of DNs to modify. Via the input file, you can also provide the PIN Generator with PINs (in plain text format) for all DNs or for specific DNs.
The following examples explain why you might want to use the input file:
The format of the input file is the same as that of the output file (see "Output File"), with the omission of the status line. In the input file, you can choose to specify PINs 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.
For example, you can set up your input file to look like this:
You can also provide PINs, in plain-text format, for the DNs in the input file, which is then hashed according to the command-line arguments. For example, you can set up your input file to look like this:
Note
You cannot provide hashed PINs to the tool.
Output File
The PIN Generator can capture the output to a text file specified by the output=<file_name> argument.
The captured output will contain a sequence of records and will be in the following format:
where
The first line in each record will always be the distinguished name. The subsequent lines, for pin and status, are optional. The record ends with a blank line. The end of line (EOL) sequence is as follows:
Windows NT
\r\n
Unix
\n
How PINs Are Stored in the Directory
Each PIN is concatenated with the corresponding user's LDAP attribute named in the saltattribute argument. If this argument is not specified, the DN of the user is used. Then, this string is hashed with the hash routine specified in the hash argument (the default selection is SHA-1).
Then, one byte is prepended to indicate the hash type used. Here's how the PIN gets stored:
byte[0] = X
The value of X depends on the hash algorithm chosen during the PIN
generation process:
X=0 if the hash algorithm chosen is SHA-1.
X=1 if the hash algorithm chosen is MD5.
X=45 if the hash algorithm chosen is none.
byte[1...] = hash("DN"+"pin")
The PIN is stored in the directory as a binary value, not as a base-64 encoded value.
Exit Codes
The PIN Generator returns exit codes to the shell window; for a list of codes, see Table 11.2. If you plan on automating the PIN-generation process, exit codes are useful in programming shell scripts.
|