Netscape Certificate Management System Command-Line Tools Guide: Chapter 5PIN Generator Tool

Command-Line Tools Guide
Netscape Certificate Management System

Chapter 5 PIN Generator Tool

For Netscape 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 "Setting Up Pin Based Enrollment" in Chapter 9 "Authentication" of CMS Administrator's Guide.

Command-Line Syntax

To set up directory for pin usage, modify setpin.conf, then run:

./setpin optfile=/bin/cert/tools/setpin.conf

Usage: ./setpin option=value ... option=value
Table 5-1
host LDAP host [required] port LDAP port (default 389) binddn DN to bind to directory as [required] bindpw Password associated with above DN filter Ldap search filter e.g. filter=(uid=*) [required] basedn Base DN used for LDAP search length Length of generated pins (default 6) minlength Minimum length of generated pins (not to be used with 'length') maxlength Maximum length of generated pins (not to be used with 'length') gen Permitted chars for pin. Type 'setpin gen' for more info case Restrict case of pins 'case=upperonly' objectclass Objectclass of LDAP entry to operate on (default pinPerson) attribute Which LDAP attribute to write to (default pin) hash Hash algorithm used to store pin: 'none', 'md5' or 'sha1' (default) saltattribute Which attribute to use for salt (default: dn) input File to use for restricting DN's, or providing your own pins output Redirect stdout to a file write Turn on writing to directory (otherwise, pins will not get written) clobber Overwrite old pins in the directory testpingen Test pin generation mode. testpingen=count debug Turn on debugging, or use debug=attrs for even more optfile Read in options (one per line) from specified file setup Switch to setup mode pinmanager Pin Manager user to create in setup mode pinmanagerpwd password of pin manager user in setup mode schemachange make schema changes in setup mode

A description for each argument follows:

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

<host_name> specifies the LDAP directory to connect to. This argument is required.

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

["binddn=<user_id>" bindpw=<bind_password>]

<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. This argument is required.

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

["filter=<LDAP_search_filter>" [basedn=<LDAP_base_DN>]]

<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. This argument is required.

<LDAP_base_DN> specifies the base DN to be utilized by the LDAP search filter. If this argument is not specified, the filter will begin searching from the root.

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

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

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

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

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

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

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

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

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

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

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

[setup pinmanager=<pinmanager_user> pinmanagerpwd=<pinmanager_password>]

When placed in the 'setup' mode, this executable allows schema modifications to be performed to add things to the directory schema.

<pinmanager_userd> used in conjunction with setup to specify the pin manager user that has permission to remove the PIN for the basedn specified.

<pinmanager_password> specifies the password for the pin manager user.

[setup schemachange=<schema_change>"]

When placed in the 'setup' mode, this executable allows schema modifications to be performed to add things to the directory schema.

<schema_change> used in conjunction with setup to specify a schema change on the 'pin' attribute as specified by the 'attribute' argument (default 'pin'), and/or the 'pinPerson' objectclass as specified by the 'objectclass argument (default: pinperson).

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=example.com in the directory tree. The tool overwrites the existing PINs, if any, with the new ones.

setpin host=lailing port=19000 "binddn=CN=directory manager" bindpw=password "filter=(cn=*)" basedn=o=example.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=example.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 5-1). Note that the input file is not 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 5-1    Using an input and output file for the PIN-generation process

Examples of output follow:

Processing: cn=QA Managers,ou=employees,o=example.com
Adding new pin/password
dn:cn=QA Managers,ou=employees,o=example.com pin:lDWynV status:notwritten

Processing: cn=PD Managers,ou=employees,o=example.com
Adding new pin/password
dn:cn=PD Managers,ou=employees,o=example.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 5-2.

Table 5-2    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 unhoused 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 multi fold. 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=example.com <blank line>
dn:cn=user2, o=example.com <blank line>
...
dn:cn=user3, o=example.com
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=example.com pin:pl229Ab <blank line>
dn:cn=user2, o=example.com pin:9j65dSf <blank line>
...
dn:cn=user3, o=example.com 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 5-2 on page 57.

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 Unix: \n

On Windows NT: \r\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 5-3. If you plan on automating the PIN-generation process, exit codes are useful in programming shell scripts.

Table 5-3    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.


host	LDAP host [required]
port	LDAP port (default 389)
binddn	DN to bind to directory as [required]
bindpw	Password associated with above DN
filter	Ldap search filter e.g. filter=(uid=*) [required]
basedn	Base DN used for LDAP search
length	Length of generated pins (default 6)
minlength	Minimum length of generated pins (not to be used with 'length')
maxlength	Maximum length of generated pins (not to be used with 'length')
gen	Permitted chars for pin. Type 'setpin gen' for more info
case	Restrict case of pins 'case=upperonly'
objectclass	Objectclass of LDAP entry to operate on (default pinPerson)
attribute	Which LDAP attribute to write to (default pin)
hash	Hash algorithm used to store pin: 'none', 'md5' or 'sha1' (default)
saltattribute	Which attribute to use for salt (default: dn)
input	File to use for restricting DN's, or providing your own pins
output	Redirect stdout to a file
write	Turn on writing to directory (otherwise, pins will not get written)
clobber	Overwrite old pins in the directory
testpingen	Test pin generation mode. testpingen=count
debug	Turn on debugging, or use debug=attrs for even more
optfile	Read in options (one per line) from specified file
setup	Switch to setup mode
pinmanager	Pin Manager user to create in setup mode
pinmanagerpwd	password of pin manager user in setup mode
schemachange	make schema changes in setup mode

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

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.

Last Updated November 23, 2004