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:
- Open the
setpin.conffile.cd /usr/lib/pki/native-tools vi setpin.conf
- 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
- Run
setpin, and set the option file tosetpin.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
