For Netscape Certificate Management System (CMS) to use the plug-in module for directory-based authentication with PINs, 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.
The setpin Command
How the Tool Works
Generating PINs
Delivering PINs to End Entities
<server_root> is the directory where the CMS binaries are kept. You first specified this directory during installation.
Use the following command in a Unix or DOS command shell:
The setpin command takes the following arguments and options:
[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]
<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]]
<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.
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 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 access 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.
Use this argument to specify the object class, if any, the tool should add to the authentication directory. [attribute=<attribute_name_for_pins>]
Use this argument to specify the object class, if any, the tool should add to the authentication directory.
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; see "Step 2. Update the Directory Schema". ["filter=<LDAP_search_filter>"]
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; see "Step 2. Update the Directory Schema".
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 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
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 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.
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 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.
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 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).
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 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.
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 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.
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 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.
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 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.
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 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".
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 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".
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.
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=airius.com in the directory tree. The tool overwrites the existing PINs, if any, with the new ones.
The bind DN (binddn) and password (bindpw)
An LDAP filter (filter) for filtering out the user entries that require PINs
Figure 10.1 Using an input and output file for the PIN-generation process
Table 10.1 PIN Generator status
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.
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.
dn:cn=user1, o=netscape
<blank line>
dn:cn=user2, o=netscape
...
dn:cn=user3, o=netscape
pin:pl229Ab
pin:9j65dSf
pin:3knAg60
Output File
The PIN Generator can capture the output to a text file specified by the output=<file_name> argument.
dn: <user_dn>1
pin: <generated_pin>1
status: <status>1
dn: <user_dn>2
pin: <generated_pin>2
status: <status>2
dn: <user_dn>n
pin: <generated_pin>n
status: <status>n
<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 10.1.
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).
The value of X depends on the hash algorithm chosen during the PIN generation process:
The PIN Generator returns exit codes to the shell window; for a list of codes, see Table 10.2. If you plan on automating the PIN-generation process, exit codes are useful in programming shell scripts.
Table 10.2 Exit codes returned by the PIN Generator
Step 2. Update the Directory Schema
Step 3. Prepare the Input File
Step 4. Run the Command Without the Write Option
Step 5. Check the Output File
Step 6. Run the Command Again with the Write Option
Before you run the PIN Generator, make sure that the directory you intend to use for generating PINs has been populated with all end-entity entries that require PINs. It is also a good idea to confirm with that directory's administrator that all pending directory requests have been processed before the PIN Generator starts its operation.
By default, the PIN Generator modifies the pin attribute in the directory's user entry (see "Arguments"). Because this attribute is not part of the standard organizationalPerson, you need to add it--that is, create a new object class in your authentication directory's schema.
superior organizationalPerson
allows
When the PIN Generator adds the PIN to the user entry, it also adds the appropriate object class. By default, the object class name is pinPerson, and the name of the attribute is pin, but you can override this with the object class and attribute options.
If you are using Netscape Directory Server version 3.x as your authentication directory, you can follow the instruction below to update the schema:
Enter the URL to the Directory Server instance that you want to use for storing end-entity PINs.
Click Schema.
In the left frame, click the "Edit or View Attributes" link.
The Manage Attributes form appears. In the Add New Attribute section, enter the information for the new attribute:
The Manage Attributes form appears.
Attribute Name. Type pin in this field. Attribute OID (optional). Entering information in this field is optional. So, you can leave it blank. Syntax. Choose binary from the drop-down list. Click Add New Attribute.
In the left frame, click the Create Objectclass link.
The Create Objectclass form appears; this form allows you to create a new object class to hold the new attribute you added. Enter information as appropriate:
The Create Objectclass form appears; this form allows you to create a new object class to hold the new attribute you added.
ObjectClass Name. Type pinPerson in this field. Parent Objectclass. Choose organizationalPerson from the drop-down list. ObjectClass OID (optional). Entering information in this field is optional. So, you can leave it blank. In the Available Attributes list, select pin and then click the Add button shown to the left of the Allowed Attributes list.
This action moves the pin attribute to the Allowed Attributes list. Click Create New ObjectClass.
This action moves the pin attribute to the Allowed Attributes list.
The server informs you that the object class has been added to the schema. Restart the server, if prompted to do so.
The server informs you that the object class has been added to the schema.
If you are using Netscape Directory Server version 4.x as your authentication directory, you can follow the instruction below to update the schema:
Select the directory that you want to use for storing end-entity PINs, and click Open to open the administration interface for Directory Server.
Click the Configuration tab.
In the navigation tree, expand the Database object.
Click Schema, and then in the right pane, click the Attributes tab.
Click Create.
The Create Attribute window appears. Enter information as appropriate:
The Create Attribute window appears.
Attribute name. Type pin in this field. Attribute OID (optional). Entering information in this field is optional. So, you can leave it blank. Syntax. Choose binary from the drop-down list. Click OK.
You are returned to the Attributes tab. Click the Object Classes tab.
You are returned to the Attributes tab.
The Create Object Class window appears. Enter information as appropriate:
The Create Object Class window appears.
Name. Type pinPerson in this field. Parent. Choose organizationalperson from the drop-down list. In the Available Attributes list, select pin and then click the Add button shown to the left of the Allowed Attributes list.
This action moves the pin attribute to the Allowed Attributes list. Click OK.
This step is optional.
Run the setpin command without the write option. Be sure to include the output option. For details, see "The setpin Command".
Go to <server_root>/bin/cert/tools
<server_root> is the directory where the CMS binaries are kept. You first specified this directory during installation. Run the setpin command with the appropriate arguments.
Check the output file to be sure it contains PINs for your users; the output should look similar to the one specified in "Output File".
When you are sure about the results, run the command again (with exactly the same arguments) with the write option and the output option. The tool stores the hashed PINs in the directory. For information on how PINs are stored in the directory, see "How PINs Are Stored in the Directory".
Mail--you can mail PINs to users, for example along with their pay slips.
Personal delivery--you can arrange a secure means of delivering the password to the user, or ask the user to collect it from you in person.
Previous
