Using the pkiprereg utility

Purpose

The pkiprereg program creates Simple Certificate Enrollment Protocol (SCEP) preregistration records in batch.

Path setup

Update your PATH, LIBPATH, and NLSPATH environment variables with the appropriate pkiserv directory before you run pkiprereg. (Note that you are updating the environment variables for the user running the utility, not updating values in the PKI Services environment variables file, pkiserv.envars.) Once you have updated these variables, you can run pkiprereg from the UNIX command line.
Variable name You must add …
PATH /install-dir/pkiserv/bin
LIBPATH /install-dir/pkiserv/lib
NLSPATH /install-dir/pkiserv/lib/nls/msg/%L/%N
The default directory for install-dir is /usr/lpp.

Format

pkiprereg {-m mode [-t tmpl-file] -s SCEP-file [-o out-file] [-d domain] 
          | [-h | -?]}

Parameters

You can display usage information about the pkiprereg command format and parameters when you execute the pkiprereg utility command with the -h or -? option or when you enter an incorrect parameter.

-m mode
Indicates one of the following modes of operation for this pkiprereg utility execution.
Mode name Function
verify Checks the data file for format errors but does not load the records into PKI Services.
generate Generates a random 8-character passphrase whenever it finds a passphrase placeholder (the * character) in the file. It does not load the records into PKI Services.
load Calls PKI Services to load the preregistration records.
remove Calls PKI Services to remove the preregistration records.
You can specify the mode value as the mode name or any number of initial characters of the mode name. Example: You can specify verify mode using any of the following options:
  • -m verify
  • -m ve
  • -m v
-t tmpl-file
When used in verify or load mode, specifies the path name of the PKI Services certificate templates file (pkiserv.tmpl if you are implementing the web application using REXX CGI scripts, or pkixgen.tmpl if you are implementing the web application using Java™Server pages), which is used as input. When used in other modes, the -t option is ignored.
-s SCEP-file
Specifies the path name of the file containing the preregistration data that is input for all modes.
-o out-file
When used in generate mode, specifies the path name of the output file for the preregistration data. When used in other modes, the -o option is ignored.
-d domain
When used in load or remove mode, specifies the PKI Services CA domain name where this utility command is directed.
Notes:
  1. When used in other modes, the -d option is ignored.
  2. The -d option is required only if PKI Services is running in multiple-CA mode.
  3. The domain value can be entered using uppercase or lowercase letters.
-h or -?
Displays the syntax of the pkiprereg command.

Input

The input for the pkiprereg utility is a data file (SCEP-file) containing preregistration records. The rules regarding format of the preregistration records are as follows:
Rules:
  • Each preregistration record consists of multiple consecutive name=value pairs, terminated by a blank line or an end-of-file indicator.
  • Each line consists of single field name and its value, separated by a = character, forming one name=value pair per line.
  • Each name=value pair (except the Template name=value pair) represents data that the client must supply at enrollment time for authentication purposes.
  • In pkiprereg verify and load modes, the Template and ClientName name=value pairs are required. All other name=value pairs are optional.
  • In pkiprereg remove mode, only the ClientName name=value pair is required.
  • Any line beginning with a # character is considered a comment.
  • All characters before the = character, except any leading and trailing white space, are considered the name.
  • All characters after the = character, except any leading and trailing white space, are considered the value.
  • The field name supplied as a name is case-sensitive and must match one of the field names listed in Table 1.
  • Line length is limited to 300 characters. After 300 characters, any additional characters are truncated.
The following field names are supported in the preregistration record.
Table 1. List of valid field names for use in the preregistration record as input to the pkiprereg utility
Field name Maximum length Description
Template 8 characters The nickname of the preregistration template to be used.
ClientName 64 characters The name of the person or device being preregistered. The first 32 characters are case-insensitive and must be unique for each user preregistered in PKI Services.
PassPhrase 32 characters The password to be communicated to the requestor. The * value can be used as a placeholder when running in generate mode.
SerialNumber 64 characters Serial number of the subject device.
UnstructAddr 64 characters Unstructured address of the subject device.
EmailAddr 64 characters Email address for the EMAIL= attribute for subject distinguished name.
Mail 64 characters Email address for the MAIL= attribute for subject distinguished name.
DNQualifier 64 characters Specifies information to add to the subject's distinguished name to make it unambiguous.
Uid 64 characters The system login name associated with the subject.
Title 64 characters Title for subject distinguished name.
DomainName 64 characters One component of a domain name. For example, domain name www.ibm.com is represented by 3 components: www, ibm, and com.
OrgUnit 64 characters Organizational unit for subject distinguished name.
Org 64 characters Organization for subject distinguished name.
Street 64 characters Street for subject distinguished name.
Locality 64 characters Locality for subject distinguished name.
StateProv 64 characters State or province for subject distinguished name.
PostalCode 64 characters Postal code for subject distinguished name.
Country 2 characters Country abbreviation for subject distinguished name.
AltIPAddr 45 characters The IP address for the subject alternate name extension. PKI Services supports IP version 4 and IP version 6 addresses.
  • For IP version 4, the IP address is in dotted decimal format; for example, 9.67.97.103.
  • For IP version 6, the IP address is divided into eight 16-bit hexadecimal blocks separated by colons. Leading zeros in each 16-bit field are optional, and successive fields of zeros can be represented by double colons, but only once; for example 1:2::3:4 is equivalent to 0001:0002:0000:0000:0000:0000:0003:0004.
  • In a mixed IP version 4 and IP version 6 environment, the IP address can be expressed in the format x:x:x:x:x:x:d.d.d.d, where the x values are the hexadecimal values of the six high-order 16-bit pieces of the address, and the d values are the decimal values of the four low-order 8-bit pieces of the address in standard IP version 4 representation; for example, 0:0:0:0:0:ABCD:1.2.3.4, or the equivalent value ::ABCD:1.2.3.4
AltURI 255 characters URI for subject alternate name extension.
AltEmail 100 characters Email address for subject alternate name extension.
AltDomain 100 characters Domain name for subject alternate name extension.
AltOther 255 characters Other Name for subject alternate name extension.
The following field names are supported as input to the pkiprereg utility, but they are not intended for use with SCEP certificates.
Table 2. List of valid field names for use in the preregistration record as input to the pkiprereg utility but not intended for use with SCEP certificates
Field name Maximum length Description
BusinessCat 64 characters Business category for subject distinguished name.
JurCountry 2 bytes Jurisdiction country for subject distinguished name.
JurStateProv 64 characters Jurisdiction state/province for subject distinguished name.
JurLocality 64 characters Jurisdiction locality for subject distinguished name.

For information about the format required for these values, see the R_PKIServ (IRRSPX00) section of z/OS Security Server RACF Callable Services.

Examples

The following example shows two preregistration records in the /etc/scep.txt file.
Template=5YSCEPP 
ClientName=www.ibm.com 
PassPhrase=gumby 
Org=IBM
Template=5YSCEPP 
ClientName=scep.company.com 
PassPhrase=*

The following command examples produce the actions listed:

Example 1: 
pkiprereg -m v -t /etc/pkiserv/pkiserv.tmpl -s /etc/scep.txt
Action: Verifies the /etc/scep.txt file, indicating that one PassPhrase has an incorrect value, the placeholder (*).
Example 2: 
pkiprereg -m g -s /etc/scep.txt -o /etc/scepfinal.txt
Action: Generates a passphrase for the placeholder and saves the records in the /etc/scepfinal.txt output file.
Example 3:
pkiprereg -m l -t /etc/pkiserv/pkiserv.tmpl -s /etc/scepfinal.txt
Action: Loads the preregistration records into PKI Services. If the template identified by the nickname 5YSCEPP contains any subject or alternate name information in the <CONSTANT> section, that information overrides any matching information specified in the /etc/scepfinal.txt file.
Parent topic: Using PKI Services utilities