Chapter 6. setpin (Generating Unique PINs for Entities)

For the Certificate System to use the UidPwdPinDirAuth authentication plug-in module, the authentication directory must contain unique PINs for each end entity which will be issued a certificate. The Certificate System provides a tool, the PIN Generator, which generates unique PINs for end-entity entries in an LDAP directory. The tool stores these PINs as hashed values in the same directory against the corresponding user entries. It also copies the PINs to a text file so that the PINs can be sent to the end entities.

6.1. The setpin Command

This chapter describes the syntax and arguments of the setpin tool and the expected responses.

6.1.1. Editing the setpin.conf Configuration File

The setpin tool can use a configuration file, setpin.conf, to store some of its required options. Before running setpin, modify this file to reflect the directory information, and set the setpin tool to use this file by doing the following:
  1. Open the setpin.conf file.
    cd /usr/lib/pki/native-tools
    vi setpin.conf
  2. Edit the directory parameters in the file to match the directory installation information.
    #------- Enter the hostname of the LDAP server
    host=localhost
    
    #------- Enter the port number of the LDAP server
    port=389
    
    #------- Enter the DN of the Directory Manager user
    binddn=CN=Directory Manager
    
    #------- Enter the password for the Directory manager user
    bindpw=
    
    #    Enter the DN and password for the new pin manager user
    pinmanager=cn=pinmanager,dc=example,dc=com
    pinmanagerpwd=
    
    #    Enter the base over which this user has the power
    #    to remove pins
    basedn=ou=people,dc=example,dc=com
    
    ## This line switches setpin into setup mode.
    ## Please do not change it.
    setup=yes
  3. Run setpin, and set the option file to setpin.conf.
    setpin optfile=/usr/lib/pki/native-tools/setpin.conf

6.1.2. Syntax

The setpin has the following syntax:

setpin host=host_name [ port=port_number ] binddn=user_id [ bindpw=bind_password ] filter="LDAP_search_filter" [ basedn=LDAP_base_DN ] [[ length=PIN_length ] | [ minlength=minimum_PIN_length ] | [ maxlength=maximum_PIN_length ]] [ gen=character_type ] [ case=upperonly ] [ hash=algorithm ] [ saltattribute=LDAP_attribute_to_use_for_salt_creation ] [ input=file_name ] [ output=file_name ] [ write ] [ clobber ] [ testpingen=count ] [ debug ] [ optfile=file_name ] [ setup [ pinmanager=pinmanager_user ] [ pinmanagerpwd=pinmanager_password ] ]

Option Description
host Required. Specifies the LDAP directory to which to connect. Depending on how DNS and the network are configured, this can be a machine name, fully-qualified domain name, or IPv4 or IPv6 address.
port Specifies the LDAP directory port to which to bind. The default port number is the default LDAP port, 389.
binddn Required. Specifies the user as whom the PIN Generator binds to the LDAP directory. This user account must have read/write access to the directory.
bindpw Gives the password for the user ID set in the binddn option. If the bind password is not given at the command line, the tool prompts for it.
filter Required. Sets the search filter for those DNs in the directory for which the tool should generate PINs.
basedn Specifies the base DN under which to search for DNs. If this argument is not specified, the filter searches from the root.
length Specifies the exact number a PIN must contain; the default is 6. Do not use with minlength or maxlength.
minlength Sets the minimum length of the generated PINs. If used with maxlength, this sets the lower end of the range of the PIN length. Do not use with length.
maxlength Sets the maximum length of the generated PINs. If used with minlength, this sets the upper end of the range of the PIN length. Do not use with length.
gen Specifies the character type 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 Restricts the character cases to uppercase only; otherwise, the case is mixed. Restricting alphabetic characters to uppercase reduces the overall combinations for the password space significantly. Use case with gen.
hash
Specifies the message digest algorithm with which to hash the PINs before storing them in the authentication directory.

Note

This should be set to none (which does not hash PINs) because the Directory Server may have restrictions on incoming hashed passwords.
The default is sha1, which produces a 160-bit message digest. md5 produces a 128-bit message digest. none does not hash the PINs.
saltattribute Specifies the LDAP attribute to use for salt creation. This must be set to dn. If an attribute is set, the tool integrates the value of the attribute with each PIN and hashes the resulting string with the hash routine. For details, refer to Section 6.2.3, “How PINs Are Stored in the Directory”.
This attribute is ignored if the hash value is set to none, which is the recommended setting.
input Specifies the file that contains the list of DNs to process. If this is used, the tool compares the filtered DNs to the ones in the input file and generates PINs for only those DNs .
output Specifies the absolute path to the file to write the PINs as setpin generates them. If a file is not set, then the output is written to the standard output. Regardless of whether an output file is set, all error messages are directed to the standard error.
write Sets whether the tool should write PINs to the directory. If specified, the PINs are written to the directory as they are generated. Otherwise, the tool does not make any changes to the directory. Do not write PINs to the directory if the PINs are to be checked. The PINs can be viewed in the output file to make sure that they are being assigned to the correct users and that they conform to the length and character restrictions. For more information, see Section 6.2.2, “Output File”.
clobber Overwrites pre-existing PINs, if any, associated with a DN. If this option is not used, any existing PINs are left in the directory.
testpingen Tests the PIN-generation mode. count sets the total number of PINs to generate for testing.
debug Writes debugging information to the standard error. If debug=attrs is specified, the tool writes more detailed information about each entry in the directory.
optfile Sets the tool to read options, one per line, from a file. This allows all arguments to be put in a file, instead of typing them at the command line. One configuration file, setpin.conf, is located in the /usr/lib/pki/native-tools directory.
setup Switches to setup mode, which allows the tool to add to the directory schema.
pinmanager Specifies the PIN manager user that has permission to remove the PIN for the basedn specified. Used with the setup option.
pinmanagerpwd Gives the password for the PIN manager user. Used with the setup option.

6.1.3. Usage

First, run the setpin command with its optfile option pointing to the setpin.conf file.
setpin optfile=/usr/lib/pki/native-tools/setpin.conf
The tool modifies the schema with a new attribute (by default, pin) and a new object class (by default, pinPerson), creates a pinmanager user, and sets the ACI to allow only the pinmanager user to modify the pin attribute.
Then, disable setup mode for the setpin command. Either comment out the setup line or change the value to no.
vim /usr/lib/pki/native-tools/setpin.conf

setup=no
After the setup is complete, then setpin can be used to generate PINs.
The following command generates PINs for all entries that have the CN attribute in their distinguished name in an LDAP directory named csldap listening on port 389. The PIN Generator binds to the directory as Directory Manager and starts searching the directory from the base DN dn=dc=example,dc=com in the directory tree. Any existing PINs are overwritten with the new ones.
setpin host=csldap port=389 binddn="CN=directory manager" bindpw=password filter="(cn=*)" basedn="dc=example,dc=com" clobber write hash=none