Setting up the HTTP Server for CMP

You can pass information about CMP requests through HTTP Server environment variables.
  • For IBM® HTTP Server - Powered by Apache, the environment variables are specified using the SetEnv directive in the virtual host file for SSL requests with client authentication, which by default is vhost1443.conf.
For information about IBM HTTP Server - Powered by Apache environment variables, see the WebSphere Application Server Knowledge Center. The variables that you can set are described in Table 1, Table 2, and Table 3.
Table 1. HTTP Server environment variables used to determine the CA
Environment variable name Description
_PKISERV_CMP_DOMAIN_ISSUERx CA’s subject distinguished name with comma-separated RDNs
Example:
SetEnv _PKISERV_CMP_DOMAIN_ISSUER1 "CN=Issuer CA,OU=Lab,O=IBM,C=AU"
_PKISERV_CMP_DOMAIN_NAMEx_y Issuer's PKI CA domain name. The domain name variable is limited to 8 characters beginning with an alphabetic character or an underscore “_” and no embedded spaces. For an unnamed domain, this variable must be set to <NONE>. A rollover of an unnamed domain requires the new domain to be named.
Example: If there are, or have been, 3 domains of certificates for the same issuer, there would be 3 entries in the environment variables file:
SetEnv _PKISERV_CMP_DOMAIN_NAME1_1 CardCA1
SetEnv _PKISERV_CMP_DOMAIN_NAME1_2 CardCA2
SetEnv _PKISERV_CMP_DOMAIN_NAME1_3 CardCA3
Example: The domain is unnamed.
SetEnv _PKISERV_CMP_DOMAIN_NAME1_1 <NONE>
_PKISERV_CMP_DOMAIN_FSTSNx_y Starting serial number, in decimal, for the first certificate that is issued by _PKISERV_CMP_DOMAIN_NAMEx_y.
Example:
SetEnv _PKISERV_CMP_DOMAIN_FSTSN1_2 1001
Notes:
  1. x represents any of the available certificate issuers from 1 to the maximum number of issuers. If there are 2 issuers of certificates, there would be 2 entries in the configuration file. The values of x are consecutive integers starting with 1.
  2. y represents any of the available CA domains that issue or have issued certificates on behalf of _PKISERV_CMP_DOMAIN_ISSUERx. The values of y are consecutive integers starting with 1.
  3. Environment variable values must be enclosed in quotations if they include white space.
  4. Any comma in a relative distinguished name (RDN) value must be escaped by placing a backslash immediately before the comma in the _PKISERV_CMP_DOMAIN_ISSUERx variable. For example, if your Organization RDN value is Widgets, Inc., the RDN must be specified as O=Widgets\, Inc.. The commas that separate the RDNs must not be escaped.
    Example:
    CN=Issuer CA,OU=Lab,O=Widgets\, Inc.,C=AU
Table 2. HTTP Server environment variables used to control the content of the certificate within a CA
Environment variable name Description
_PKISERV_CMP_KEYTYPE_domain Specifies the key type or encryption algorithm to be used to generate the key pair. PKI Services supports RSA, NISTECC and BPECC.
Examples:
SetEnv _PKISERV_CMP_KEYTYPE_CardCA1 RSA
SetEnv _PKISERV_CMP_KEYTYPE BPECC
_PKISERV_CMP_KEYSIZE_domain A three- or four-digit number that specifies the length of the key.
  • For RSA, minimum size is 512 (1024 if _PKISERV_CMP_SECUREKEY is set), maximum size is 4096, and the default is 1024. The value must be a multiple of two (256, if _PKISERV_CMP_SECUREKEY is set).
  • For NISTECC, valid sizes are 192, 224, 256, 384 and 521, and the default is 192.
  • For BPECC, valid sizes are 160, 192, 224, 256, 320, 384, 512, and the default is 192.
Examples:
SetEnv _PKISERV_CMP_KEYSIZE_CardCA1 2048
SetEnv _PKISERV_CMP_KEYSIZE 512
_PKISERV_CMP_SECUREKEY_domain Specifies whether to generate secure keys in the TKDS. The value 1 specifies that secure keys are to be generated. The value 0 specifies that clear keys are to be generated.
If this variable is not set, the profile protecting the CLEARKEY resource in the CRYPTOZ class determines whether the key generated is a secure key or a clear key. If the profile allows clear key generation, the generated key is a clear key. If the profile restricts clear key generation, the generated key is a secure key. For example, the following command creates a profile that prevents the generation of clear keys from any of the CMP clients:
RDEF CRYPTOZ CLEARKEY.SYSTOK-SESSION-ONLY UACC(NONE)
In this case, AES256 is used to envelop the private key.
_PKISERV_CMP_SECUREKEY_KEYENCALG_domain Specifies the algorithm to envelop the private key. Valid values are AES256, AES128, and TDES. If not set, it defaults to AES256. This variable is ignored if _PKISERV_CMP_SECUREKEY_domain is not set.
_PKISERV_CMP_HONOR_CLIENT_DATES_domain Specifies whether to honor client-specified certificate validity dates. Valid values are 0 and 1.

The value 1 specifies that PKI Services uses start and end dates that are specified in the validity field of the certificate request. If validity dates are not specified, PKI Services uses the values in the environment variables _PKISERV_CMP_NOTBEFORE_domain and _PKISERV_CMP_NOTAFTER_domain. If either the start date or the end date is specified and the other is not specified, PKI Services uses the value set by the corresponding environment variable for the unspecified value.

The value 0, or the absence of this variable, indicates that PKI Services is to use the values in the environment variables _PKISERV_CMP_NOTBEFORE_domain and _PKISERV_CMP_NOTAFTER_domain. If the client specifies either a start or end date in the validity field of a cr message when the value of this variable is 0 or absent, PKI Services rejects the request.

Examples:
SetEnv _PKISERV_CMP_HONOR_CLIENT_DATES_CardCA1 1
SetEnv _PKISERV_CMP_HONOR_CLIENT_DATES 0
_PKISERV_CMP_NOTBEFORE_domain Specifies the number of days from day of issue to when the certificate becomes valid. Valid values are 0 - 30 days. The default is 0, specifying that the certificate is valid from the start of the current day.
Examples:
SetEnv _PKISERV_CMP_NOTBEFORE_CardCA1 7
SetEnv _PKISERV_CMP_NOTBEFORE 5
_PKISERV_CMP_NOTAFTER_domain Specifies the number of days from today’s date to when the certificate expires. Valid values are 1 - 9999. The default is 365. The value 1 specifies that the certificate is valid until the end of the current day.
Examples:
SetEnv _PKISERV_CMP_NOTAFTER_CardCA1 1825
SetEnv _PKISERV_CMP_NOTAFTER 1580
_PKISERV_CMP_HONOR_CLIENT_EXTS_domain Specifies whether to honor the client-specified extensions Subject Alternate Name, Keyusage and Extended keyusage. Valid values are 0 and 1.

The value 1 specifies that PKI Services uses the extensions Subject Alternate Name, Keyusage and Extended keyusage from the request.

The value 0, or the absence of this variable, specifies that PKI Services is to use the extensions Keyusage and Extended keyusage from the environment variables _PKISERV_CMP_KEYUSAGE_domain and _PKISERV_CMP_EXTKEYUSAGE_domain. If the client specifies the extensions field of a cr message or the attributes field of a p10cr message when the value of this variable is 0 or absent, PKI Services rejects the request.

Examples:
SetEnv _PKISERV_CMP_HONOR_CLIENT_EXTS_CardCA1 1
SetEnv _PKISERV_CMP_HONOR_CLIENT_EXTS 0
_PKISERV_CMP_KEYUSAGE_domain Blank-separated character strings defining the key usage to be added to requested certificates. Valid values are: handshake, dataencrypt, certsign, docsign, digitalsignature, digitalsig, nonrepudiation, keyencipherment, keyenciph, keyencrypt, dataencipherment, dataenciph, keyagreement, keyagree, keycertsign, crlsign, Start of changecmcaa, cmcra, cmcas, pkinitkdc, and pkinitclientauthEnd of change. The values are not case-sensitive. No default value.
Examples:
SetEnv _PKISERV_CMP_KEYUSAGE_CardCA1
        "digitalsig keyencrypt"
SetEnv _PKISERV_CMP_KEYUSAGE handshake
_PKISERV_CMP_EXTKEYUSAGE_domain Blank-separated character strings defining the extended key usage to be added to requested certificates. Valid values are: serverauth, clientauth, codesigning, emailprotection, timestamping, ocspsigning, mssmartcardlogon, Start of changecmcaa, cmcra, cmcas, pkinitkdc, and pkinitclientauthEnd of change. The values are not case-sensitive. No default value.
Examples:
SetEnv _PKISERV_CMP_EXTKEYUSAGE_CardCA1 clientauth
SetEnv _PKISERV_CMP_EXTKEYUSAGE serverauth
_PKISERV_CMP_AUTHINFOACC_domain Deprecated. Use _PKISERV_CMP_AUTHINFOACCn_domain instead. Ignored if you specify _PKISERV_CMP_AUTHINFOACCn_domain.

A comma-separated two-part string specifying information that is used to create the AuthorityInfoAccess extension. The two-part string identifies the accessMethod and accessLocation. The accessMethod is either OCSP or IdentrusOCSP (case-insensitive). The accessLocation is a URI in the form URI=access-url or URL=access-url. The access-url must be an HTTP protocol. No default value.

Examples:
SetEnv _PKISERV_CMP_AUTHINFOACC_CardCA1 OCSP,
   URL=http://www.widgets.com/CardCA1/public-cgi/caocsp
SetEnv _PKISERV_CMP_AUTHINFOACC OCSP,
   URI=http://www.widgets.com/PKIServ/public-cgi/caocsp
_PKISERV_CMP_AUTHINFOACCn_domain Specifies one or more AuthorityInfoAccess extensions in the form of a comma-separated two-part string. The two-part string identifies the accessMethod and accessLocation. The accessMethod is either OCSP or IdentrusOCSP (case-insensitive). The accessLocation is a URI in the form URI=access-url or URL=access-url. The access-url must be an HTTP protocol. No default value. There can be multiple entries, where n is 1 for the first AuthorityInfoAccess extension and increases sequentially for additional entries.
Examples:
SetEnv _PKISERV_CMP_AUTHINFOACC1_CardCA1 OCSP,
   URL=http://www.widgets.com/CardCA1/public-cgi/caocsp
SetEnv _PKISERV_CMP_AUTHINFOACC2_CardCA1 OCSP,
   URI=http://www.widgets.com/PKIServ/public-cgi/caocsp
_PKISERV_CMP_CERTPOLICIES_domain Specifies the certificate policies that are to be included in the issued certificates. The value is a set of numbers, which are separated by blanks, each representing one of the PolicyName values specified in the CertPolicy section of the PKI Services configuration file. Valid values are 1 - 99. No default value.
Examples:
SetEnv _PKISERV_CMP_CERTPOLICIES_CardCA1 "1 2 3"
SetEnv _PKISERV_CMP_CERTPOLICIES "1 4"
_PKISERV_CMP_CUSTOMEXTn_domain Specifies one or more custom extensions in the form of a comma-separated four-part string as indicated in the CustomExt field in the GENCERT CertPlist. There can be multiple entries, where n is 1 for the first custom extension and increases sequentially for additional entries.
Example:
SetEnv _PKISERV_CMP_CUSTOMEXT1_CardCA1 
   1.3.6.1.4.1.311.20.2, N,BMP,myDomainController
Notes:
  1. _domain represents the domain name that is contained in the variable _PKISERV_CMP_DOMAIN_NAMEx_y. For an unnamed domain, omit _domain.
  2. Environment variable values must be enclosed in quotations if they include white space.
Table 3. HTTP Server environment variables used to configure the certificate recipients
Environment variable name Description
_PKISERV_CMP_HONOR_CLIENT_CERTS_domain Specifies the maximum number of extra input recipient certificates that can be supplied in the input message, by using the extraCerts construct in the PKIMessage structure. Valid values are 0 - 5. If omitted or set to a value of 0, certificate requests that contain extraCerts are rejected.
Example:
SetEnv _PKISERV_CMP_HONOR_CLIENT_CERTS_CardCA1 3

For more information, see Determining the source of certificates used to encrypt the returned private key.
_PKISERV_CMP_KEYRING_domain Specifies the RACF® user ID and the name of the key ring that is associated with that user ID that contains the certificates that are to be used to encrypt the private key for certificate request messages.
Example:
SetEnv _PKISERV_CMP_KEYRING_CardCA1 CMPCLNT/CardKeyRing

For more information, see Determining the source of certificates used to encrypt the returned private key.

Table 4. HTTP Server environment variables used to control tracing
Environment variable name Description
_PKISERV_CMP_TRACE Specifies a bit mask enabling CMP trace options. No trace option is enabled if the bit mask is 0 and all trace options are enabled if the bit mask is 0xff. The bit mask can be specified as a decimal (nnn), octal (0nnnn) or hexadecimal (0xhh) value. These trace options are available:
0x01
CMP error messages
0x02
CMP informational messages
0x04
R_PKIServ callable service parameter list traces on entry and exit
0x08
Elapse time messages of events within the CMP program
0x10
CMP program function entry and exit trace messages
0x20
DER buffer display messages
0x40
Displays environment variables that are set at CMP program startup
Example:
SetEnv _PKISERV_CMP_TRACE 0xff
_PKISERV_CMP_TRACE_FILE Specifies the name of the trace file. Defaults to /tmp/pkicmp.%.trc. The trace file is not used if the _PKISERV_CMP_TRACE environment variable is not defined or is set to 0. The current process identifier is included as part of the trace file name when the name contains a percent sign (%). For example, if _PKISERV_CMP_TRACE_FILE is set to /tmp/pkicmp.%.trc and the current process identifier is 247, the trace file name is /tmp/pkicmp.247.trc.

Guideline: Because multiple copies of the CMP CGI program can run concurrently for multiple CMP clients, the value of _PKISERV_CMP_TRACE_FILE should include the percent sign (%) to prevent multiple copies of the CMP CGI program from writing to the same file.

Example:
SetEnv _PKISERV_CMP_TRACE_FILE /tmp/pkicmp.%.trc
Table 5. HTTP Server environment variable used to control the FIPS level
Environment variable name Description
_PKISERV_CMP_FIPS_LEVEL Specify the FIPS level the CMP program runs.
0
non FIPS mode (default)
1
FIPS 140-2
2
SP800-131-A with exception
3
SP800-131-A without exception
The value applies to all the domains. Make sure that the specified value agrees with the key size that is specified in the _PKISERV_CMP_KEYSIZE_ domain keyword. The value of 0 or, the absence of this variable, indicates that CMP is not running in FIPS mode.
Example:
SetEnv _PKISERV_CMP_FIPS_LEVEL 1