Chapter 4   PIN Generator Tool


For iPlanet Certificate Management System (CMS) to use the authentication plug-in module named UidPwdPinDirAuth your authentication directory must contain unique PINs for each end entity to whom you intend to issue a certificate. To aid you in generating PINs for end-entity entries in a directory, Certificate Management System provides a command-line tool called the PIN Generator. This tool allows you to generate unique PINs for entries in an LDAP-compliant user directory. The tool stores these PINs (as hashed values) in the same directory against the corresponding user entries, and it copies the PINs to a text file, from which you can deliver the PINs to end entities by an appropriate, secure means.

This chapter explains how to use the PIN Generator. The chapter has the following sections:

• Locating the PIN Generator Tool

• The setpin Command

• How the Tool Works

Locating the PIN Generator Tool

---

You can find the PIN Generator at this location:

<server_root>/bin/cert/tools/setpin.exe

The setpin Command

---

You run the PIN Generator by entering the setpin command and its arguments in a command shell and monitoring the output in the shell window. This section gives the syntax for the setpin command and its arguments. For instructions on generating PINs and storing them in your authentication directory, see section "Configuring Authentication for End-User Enrollment" in Chapter 15, "Setting Up End-User Authentication" of CMS Installation and Setup Guide.

Command-Line Syntax

Use the following command in a Unix or DOS command shell:

setpin [arguments]
setpin [optfile=filename] [param1] [param2]

Arguments

The setpin command takes the following arguments and options:

setpin

[host=<host_name> [port=<port_number>]]
[certdb=<path> nickname=<certificate_nickname> | "binddn=<user_id>"
   bindpw=<bind_password> [SSL=yes | no]]
[objectclass=<objectclass_to_add>]
[attribute=<attribute_name_for_pins>]
["filter=<LDAP_search_filter>"]
[input=<file_name>]
[length=<PIN_length> | minlength=<minimum_PIN_length>
   maxlength=<maximum_PIN_length>]
[gen=RNG-alpha | RNG-alphanum | RNG=printableascii]
[case=upperonly]
[hash=sha1 | md5 | none]
[output=<file_name>]
[clobber]
[write]
[saltattribute=<LDAP_attribute_to_use_for_salt_creation>]
[debug]

A description for each argument follows:

• [host=<host_name> [port=<port_number>]]

  <host_name> specifies the LDAP directory to connect to.

  <port_number> specifies the TCP/IP port to bind to; the default port number is the default LDAP port, 389.

• [certdb=<path> nickname=<certificate_nickname> | "binddn=<user_id>" bindpw=<bind_password> [SSL=yes | no]]

  Use this argument to specify how the tool should connect to the directory: whether to use basic authentication, SSL, or SSL with client authentication. By default, SSL is not used (SSL=no).

  • If you want the tool to use basic authentication, you must turn off SSL (SSL=no) and enter the bind DN and password information. Do not enter values for the remaining options.

  • If you want the tool to use SSL, you must turn on SSL (SSL=yes) and enter the bind DN and password information. Do not enter values for the remaining options.

  • If you want the tool to use SSL with client authentication, you must turn on SSL (SSL=yes) and enter the nickname of the certificate to use for SSL client authentication and the path to the certificate database that contains this certificate. You don't have to provide the bind DN and password.

  <path> specifies the path to the certificate database containing the client authentication certificate to use for SSL client authentication. If you provide the path to the certificate database (cert7.db in Netscape Directory Server), it is assumed that the LDAP directory has been set up for SSL-based access. You must also specify the certificate for SSL client authentication to the directory.

  <certificate_nickname> specifies the nickname of the certificate to use for SSL client authentication to the directory. The tool looks for this certificate in the database specified by the path parameter value. If you want the tool to use a client certificate residing on a token or smart card to access the directory, prefix the nickname with the word module (module:nickname); then a PKCS #11 module will be used.

  <user_id> specifies the user ID that has read and write permission to the LDAP directory; the PIN Generator binds to the directory as this user.

  <bind_password> specifies the password for the user ID that has read and write access to the LDAP directory.

  If the bind password is not given at the command line, the tool prompts for it.

• [objectclass=<objectclass_to_add>]

  Use this argument to specify the object class, if any, the tool should add to the authentication directory. By default it is pinPerson.

• [attribute=<attribute_name_for_pins>]

  Use this argument to specify the authentication directory attribute to which PINs should be published. If you don't specify an attribute, it defaults to pin, the new attribute added to the authentication directory schema.

• ["filter=<LDAP_search_filter>"]

  Use this argument to filter those DNs in the directory for which the tool should generate PINs. For information on how to specify filters, see the information available at this URL: http://developer.netscape.com/docs/manuals/
  dirsdk/capi/search.htm

• [input=<file_name>]

  Use this argument to specify the name of the file that contains the list of DNs to process. Using this argument is optional. If you do, the tool compares the filtered DNs to the ones specified by the input file and generates PINs for only those DNs that are also in the file.

• [length=<PIN_length> | minlength=<minimum_PIN_length> maxlength=<maximum_PIN_length>]

  Use this argument to specify the exact number or a range of characters that a PIN must contain. The PINs can be either a fixed length or generated to be between two values (x,y) inclusive (x,y>0).

  <PIN_length> specifies the exact length for the PINs. For example, if you want PIN length to be eight characters, enter 8. PIN length must be an integer greater than zero.

  <minimum_PIN_length> specifies the minimum length for the PINs. For example, if you want PIN length to be at least six characters, enter 6.

  <maximum_PIN_length> specifies the maximum length for the PINs. For example, if you want PIN length to be nine characters at the most, enter 9.

• [gen=RNG-alpha | RNG-alphanum | RNG-printableascii]

  Use this argument to specify the type of characters for PINs. The characters in the password can be constructed out of alphabetic characters (RNG-alpha), alphanumeric characters (RNG-alphanum), or any printable ASCII characters (printableascii).

• [case=upperonly]

  Use this argument with the gen parameter. If you do, the case for all alphabetic characters is fixed to uppercase only; otherwise, the case is mixed. Restricting alphabetic characters to uppercase reduces the overall combinations for the password space significantly.

• [hash=sha1 | md5 | none]

  Use this argument to specify the message digest algorithm the tool should use to hash the PINs before storing them in the authentication directory. If you want to store PINs as SHA-1 or MD5 hashed values in the directory, be sure to specify an output file for storing PINs in plain text. You will need the PINs in plain text for delivering them to end entities.

  sha1 produces a 160-bit message digest. This option is used by default.
  md5 produces a 128-bit message digest.
  none does not hash the PINs.

• [output=<file_name>]

  Use this argument to specify the absolute path to the file to which the tool should write the PINs as it generates them; this is the file to which the tool will capture the output.

  If you don't specify a filename, the tool will write the output to the standard output. In any case, all the error messages will be directed to the standard error.

• [clobber]

  Use this argument to specify whether the tool should overwrite preexisting PINs, if any, associated with a DN (user). If specified, the tool overwrites the existing PINs with the one it generates. Otherwise, it leaves the existing PINs as they are.

• [write]

  Use this argument to specify whether the tool should write PINs to the directory. If specified, the tool writes PINs (as it generates) to the directory. Otherwise, the tool does not make any changes to the directory.

  For example, if you want to check PINs—that the PINs are being given to the correct users and that they are conforming to the length and character-set restrictions—before updating the directory, do not specify this option. You can check the PINs before updating the directory by looking at the output file; for details, see "Output File".

• [saltattribute=<LDAP_attribute_to_use_for_salt_creation>]

  Use this argument to specify the LDAP attribute the tool should use for salt creation. If you specify an attribute, the tool integrates the corresponding value of the attribute with each PIN, and hashes the resulting string with the hash routine specified in the hash argument.

  If you don't specify this argument, the DN of the user is used. For details, see "How PINs Are Stored in the Directory".

• [debug]

  Use this argument to specify whether the tool should write debugging information (to the standard error). If debug=attrs is specified, the tool writes much more information about each entry in the directory.

• [testpingen=<count>]

  Use this argument to test the pin-generation mode.

  <count> specifies the total number (in decimal) of PINs to be generated for testing purposes.

• [optfile]

  Use this argument to specify that the tool should read in options (one per line) from specified file; this option enables you to put all the arguments in a file, instead of typing them on the command line.

Example

The following command generates PINs for all entries that have the CN attribute (in their distinguished name) defined in an LDAP directory named laiking that is listening at port 19000. The PIN Generator binds to the directory as user DirectoryManager and starts searching the directory from the node dn=o=siroe.com in the directory tree. The tool overwrites the existing PINs, if any, with the new ones.

setpin host=lailing port=19000 "binddn=CN=directoryManager"
bindpw=password "filter=(cn=*)" basedn=o=siroe.com clobber write

How the Tool Works

---

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:

• 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

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 4-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 4-1    Using an input and output file for the PIN-generation process

Examples of output follow:

Processing: cn=QA Managers,ou=employees,o=siroe.com

Adding new pin/password

dn:cn=QA Managers,ou=employees,o=siroe.com
pin:lDWynV
status:notwritten

Processing: cn=PD Managers,ou=employees,o=siroe.com

Adding new pin/password

dn:cn=PD Managers,ou=employees,o=siroe.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 4-1.

Table 4-1    PIN Generator status  

Exit code	Description
notwritten	Specifies that the PINs were not written to the directory, because the write option was not specified on the command line.
writefailed	Specifies that the tool made an attempt to modify the directory, but the write operation was unsuccessful.
added	Specifies that the tool added the new PIN to directory successfully.
replaced	Specifies that the tool replaced an old PIN with a new one (the clobber option was specified).
notreplaced	Specifies that the tool did not replace the old PIN with a new one (the clobber option was not specified).

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:

• Assume that you have set PINs for all entries in the user directory. Two new users joined your organization and you updated the directory with new users' information. For the new users to get certificates, the directory must contain PINs. And you want to set PINs for just those user entries without making changes to any of the other user entries. Instead of constructing a complex LDAP filter to filter out just these two entries, you can construct a general filter, put the two users' DNs in the input file, and run the PIN Generator.

• Assume that you want your users to use their social security numbers as PINs. You can enter users' social security numbers as PINs in the input file, and the PIN Generator will store them as hashed values in the directory.

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:

dn:cn=user1, o=siroe
<blank line>

dn:cn=user2, o=siroe
<blank line>

...

dn:cn=user3, o=siroe

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:

dn:cn=user1, o=siroe
pin:pl229Ab
<blank line>

dn:cn=user2, o=siroe
pin:9j65dSf
<blank line>

...

dn:cn=user3, o=siroe
pin:3knAg60
<blank line>

---

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:

dn: <user_dn>1
pin: <generated_pin>1
status: <status>1
<blank line>

dn: <user_dn>2
pin: <generated_pin>2
status: <status>2
<blank line>

...

dn: <user_dn>n
pin: <generated_pin>n
status: <status>n
<blank line>

where

<user_dn> is a distinguished name that matched the specified DN pattern (specified by the DN filter) or that was in the input file (the DN file). By default, the delimiter is ";" or the character defined on the command line.

<generated_pin> is a string of characters with either fixed or variable length, dependent on parameters passed into the command.

<status> is one of the values specified in Table 4-1.

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:

• On Windows NT: \r\n

• On 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 4-2. If you plan on automating the PIN-generation process, exit codes are useful in programming shell scripts.

Table 4-2    Exit codes returned by the PIN Generator  

Exit code	Description
0	Indicates that PIN generation was successful; that is, PINs are set for all the DNs in the specified directory.
2	Indicates that the tool could not open the certificate database specified by the certdb parameter.
3	Indicates that the tool could not locate the certificate specified by the nickname parameter in the specified certificate database.
4	Indicates that the tool could not bind to the directory as the user specified by the binddn parameter (over SSL).
5	Indicates that the tool could not open the output file specified by the output parameter.
7	Indicates an error parsing command-line arguments.
8	Indicates that the tool could not open the input file specified by the input parameter.
9	Indicates that the tool encountered an internal error.
10	Indicates that the tool found a duplicate entry in the input file specified by the input parameter.
11	Indicates that the tool didn't find the salt attribute, specified by the saltattribute parameter, in the directory.