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 WebSphere Application Server Library.The variables that you can set are described in Table 1, Table 2, and Table 3. End of change

Table 1. HTTP Server environment variables used to determine the CA
Environment variable name	Description
_PKISERV_CMP_DOMAIN_ISSUER`x`	CA’s subject distinguished name with comma-separated RDNs Example: `_PKISERV_CMP_DOMAIN_ISSUER1=CN=Issuer CA,OU=Lab,O=IBM,C=AU`
_PKISERV_CMP_DOMAIN_NAME`x`_`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 roll over 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: `_PKISERV_CMP_DOMAIN_NAME1_1=CardCA1 _PKISERV_CMP_DOMAIN_NAME1_2=CardCA2 _PKISERV_CMP_DOMAIN_NAME1_3=CardCA3` Example: The domain is unnamed. `PKISERV_CMP_DOMAIN_NAME1_1=<NONE>`
_PKISERV_CMP_DOMAIN_FSTSN`x`_`y`	Starting serial number, in decimal, for the first certificate that is issued by _PKISERV_CMP_DOMAIN_NAME`x`_`y`. Example: `PKISERV_CMP_DOMAIN_FSTSN1_2=1001`

Notes:

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.
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.
Environment variable values must not be enclosed in quotations even if they include white space.
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: `_PKISERV_CMP_KEYTYPE_CardCA1=RSA _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: `_PKISERV_CMP_KEYSIZE_CardCA1=2048 _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_`dom`	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_`dom`	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 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: `_PKISERV_CMP_HONOR_CLIENT_DATES_CardCA1=1 _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: `_PKISERV_CMP_NOTBEFORE_CardCA1=7 _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: `_PKISERV_CMP_NOTAFTER_CardCA1=1825 _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: `_PKISERV_CMP_HONOR_CLIENT_EXTS_CardCA1=1 _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`, and `crlsign`. The values are not case-sensitive. No default value. Examples: `_PKISERV_CMP_KEYUSAGE_CardCA1=digitalsig keyencrypt _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`, and `mssmartcardlogon`. The values are not case-sensitive. No default value. Examples: `_PKISERV_CMP_EXTKEYUSAGE_CardCA1=clientauth _PKISERV_CMP_EXTKEYUSAGE=serverauth`
_PKISERV_CMP_AUTHINFOACC_`domain`	Deprecated. Use _PKISERV_CMP_AUTHINFOACC`n`_`domain` instead. Ignored if you specify _PKISERV_CMP_AUTHINFOACC`n`_`domain`. A comma-separated two-part string specifying information 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: `_PKISERV_CMP_AUTHINFOACC_CardCA1=OCSP, URL=http://www.widgets.com/CardCA1/public-cgi/caocsp _PKISERV_CMP_AUTHINFOACC=OCSP, URI=http://www.widgets.com/PKIServ/public-cgi/caocsp`
_PKISERV_CMP_AUTHINFOACC`n`_`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: `_PKISERV_CMP_AUTHINFOACC1_CardCA1=OCSP, URL=http://www.widgets.com/CardCA1/public-cgi/caocsp _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: `_PKISERV_CMP_CERTPOLICIES_CardCA1=1 2 3 _PKISERV_CMP_CERTPOLICIES=1 4`
_PKISERV_CMP_CUSTOMEXT`n`_`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: `_PKISERV_CMP_CUSTOMEXT1_CardCA1=1.3.6.1.4.1.311.20.2, N,BMP,myDomainController`

Notes:

_domain or _dom represents the domain name that is contained in the variable _PKISERV_CMP_DOMAIN_NAMEx_y. For an unnamed domain, omit _domain or _dom.
Environment variable values must not be enclosed in quotations even 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: `_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: `_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 (0`nnnn`) or hexadecimal (0x`hh`) 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
_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.