pkid_config Configuration File Reference

The PKI Services Manager console saves settings to the configuration file. You can also view and edit this file manually. The default file location is:

• Unix

  /opt/microfocus/pkid/config/pki_config

• Windows

  \ProgramData\Micro Focus\ReflectionPKI\config\pki_config

File Format

The configuration file consists of keywords followed by values. The value can be separated from the keyword by tabs, spaces, or spaces and one '='. Any line starting with a pound sign (#) is a comment. Any empty line is ignored. Some keywords can appear multiple times, and these settings are applied cumulatively. Changes to settings do not take effect until you reload the settings or restart the service. (If a restart is required, that information is given in the keyword description.)

The file includes a global section that contains settings that apply to all validation queries. You can also create stanzas that configure certificate-specific settings. The TrustAnchor keyword marks the beginning of each trust anchor stanza. Settings beneath the TrustAnchor keyword apply only to that trust anchor. The stanza ends at the next TrustAnchor keyword.

Some settings must be configured outside any trust anchor stanzas. These settings apply to all validation queries. Where a setting is supported both globally and within a stanza, the value within the trust anchor stanza overrides the global value.

Keywords

AllowClientStats

Specifies whether PKI Services Manager allows clients to request PKI Services Manager runtime statistics. Configure this keyword once, outside any stanza. The allowed values are 'yes' and 'no'. The default is 'yes'.

AllowVers1

Specifies whether PKI Services Manager allows version 1 certificates for a trust anchor. Note: Intermediate certificates must be version 3 regardless of the value of this setting. Configure this keyword once, outside any stanza. The allowed values are 'yes' and 'no'. The default is 'no'.

AllowWhoAmI

Specifies whether PKI Services Manager allows a client to query for the mapped identity (using -w or --whoAmI) when using PKI Services Manager to validate certificates. Configure this keyword once, outside any stanza. The allowed values are 'yes' and 'no'. The default is 'yes'.

CertSearchOrder

A comma-separated list that specifies where PKI Services Manager searches for intermediate certificates required to validate a certificate. Listed locations are searched in order. The options are 'local', 'certserver', 'aia', and 'windows'. The default is 'local, certserver.' (Note: If you select 'windows', PKI Services Manager uses only those certificates that are installed for use by the local computer, not certificates installed for the current user. To view and manage the local computer certificates, use the Microsoft Management Console. Add the Certificates Snap-in and configure it to manage certificates for the computer account.) Configure this keyword once, outside any stanza.

CertServers

Specifies a server from which PKI Services Manager can retrieve intermediate certificates when 'certserver' is included in the CertSearchOrder list. You can specify either an HTTP or an LDAP server. (For example: ldap://certserver:10389 or http://certserver:1080) This keyword can be configured multiple times outside any stanza. The values are cumulative.

CRLServers

Specifies a server from which PKI Services Manager can retrieve Certificate Revocation Lists (CRLs) when 'crlserver' is included in the RevocationCheckOrder list. You can specify either an HTTP or an LDAP server. (For example: ldap://crlserver:10389 or http://crlserver:1080.) This keyword can be configured multiple times outside of any stanza and multiple times per stanza. The values are cumulative.

ClientDebugging

Specifies whether the application that is requesting certificate validation can request and receive debug messages from PKI Services Manager. Configure this keyword once, outside any stanza. The allowed values are 'yes' and 'no'. The default is 'no'. Note: To view these messages you also need to set a sufficiently detailed debug level in the calling application. For the Reflection for Secure IT Server for Windows, specify "Protocol details" or higher. For the Reflection for Secure IT Client and Server for UNIX, specify debug level 3 or higher.

EnforceDODPKI

Determines whether PKI Services Manager enforces settings that meet US Department of Defense PKI requirements. The allowed values are 'yes' and 'no'. The default is 'no'. When this setting is 'yes', the service will not start unless the following conditions are met: FipsMode = yes; AllowVers1 = no; CertSearchOrder does not include 'windows'; and RevocationCheckOrder has at least one option specified and does not include 'none'.

ExplicitPolicy

Determines whether PKI Services Manager enforces application policies. This keyword can be configured once outside of any stanza and once per stanza. The allowed values are 'yes' and 'no'. The default is 'no'. If the value is 'yes' you must specify one or more application policies to be enforced using the PolicyOID keyword. Each application policy is specified with a Policy Identifier (OID). (Note: Policies may also be required by the certificate being presented or by a certificate within the chain of trust.)

FipsMode

Enforces security protocols and algorithms that meet FIPS 140-2 standards. The allowed values are 'yes' and 'no'. The default is 'yes'. Configure this keyword once, outside any stanza. You need to restart the service if you modify this setting.

KeyFilePath

Specifies the path to the private key used to identify PKI Services Manager. When no path is specified, the path or file name is relative to the PKI Services Manager configuration directory. Configure this keyword once, outside any stanza. This setting is required. If KeyFilePath is not specified, or no key is present, the PKI Services Manager service will not start. The default is 'pki_key'. You need to restart the service if you modify this setting. PKI Services Manager creates a key pair when it initializes the settings, but you can also use a key pair created by ssh-keygen (or another tool). Only RSA keys are allowed.

ListenAddress

Specifies the port on which PKI Services Manager listens for validation requests. The syntax is host:port. You can specify the host name using either an IP address or a host name. IP addresses can be in either IPv4 or IPv6 format. IPv6 addresses must be enclosed in square brackets, for example [::D155:AB63]:18081.The default is 0.0.0.0:18081, which configures the server to listen on port 18081 using all available network adapters. This setting is required. You need to restart the service if you modify this setting.

LocalStore

The local store is used to hold items that are required for certificate validation. Depending on your configuration, this may include trusted root certificates, intermediate certificates, and/or Certificate Revocation Lists (CRLs). You can specify directories or files. When a directory is specified, all files in the specified directory and any subdirectories are included in the store. Files must be binary or base 64 encoded X.509 certificates or CRLs. This keyword can be configured multiple times outside any stanza. The values are cumulative. This setting is required.

LogFacility Specifies the output location for log messages. Allowed values are 'file' and 'none'. The default is 'file'. Log files are created daily and saved to a directory called logs located in the PKI Services Manager data directory. Configure this keyword once, outside any stanza. You need to restart the service if you modify this setting.

LogLevel

Specifies the amount of information sent to the log. Allowed values are: 'error', 'warn', 'info', 'debug', and 'trace'. The log can contain both auditing messages (labeled "[audit]"), and debug messages (labeled "[debug]"). Auditing messages provide information about both successful and unsuccessful validation attempts. Debug messages are designed to help in troubleshooting. The default log level is 'error'. At this level, auditing messages are sent to the log, but debug messages are sent only if a PKI Services Manager error occurs, generally because PKI Services Manager is not correctly configured. The other options include audit messages plus increasing levels of detail in the debug messages. Configure this keyword once, outside any stanza.

MapFile

Specifies the location of the PKI Services Manager map file. Use the map file to configure which users or computers are allowed to authenticate with a valid certificate. When no path is specified, the path or file name is relative to the PKI Services Manager configuration directory. This setting is required. This keyword can be configured once outside of any stanza and once per stanza.

MaxLogFiles

Specifies the maximum number of log files to create. A new log file is automatically created daily. When the maximum is reached, the oldest log is removed. The default is 10. Configure this keyword once, outside any stanza. You need to restart the service if you modify this setting.

NetworkTimeout

Specifies the timeout for any network download: LDAP, HTTP, or OCSP. Units are milliseconds. The default is 20000. Configure this keyword once, outside any stanza. Configure this keyword once, outside any stanza.

OCSPCertificate

Specifies a certificate that can be used to verify the signature of the OCSP response. This is needed only if the OCSP response does not include the signer's certificate. The value can be either a certificate file or the Subject value of the certificate (for example OcspCertificate = "CN = Secure CA, O = Secure Corporation, C = US"). If you use the Subject value, the certificate must be in the local store. This keyword can be configured multiple times outside of any stanza and multiple times per stanza. The values are cumulative.

OCSPResponders

Specifies the address of an OCSP responder to use for checking certificate revocation when 'ocsp' is included in the RevocationCheckOrder list. Use an HTTP address to identify the responder. (For example: http://ocsp.myhost.com:1080.) This keyword can be configured multiple times outside of any stanza and multiple times per stanza. The values are cumulative.

PolicyOID

Specifies an allowed Policy Identifier (OID) to use when application policies are in force, either because ExplicitPolicy is 'yes' or because policies are required by the certificate being presented or by a certificate within the chain of trust. When ExplicitPolicy is 'yes', the specified OID must match at least one of the OIDs in the final policy set of the certificate chain. The value 2.5.29.32.0 allows use of any Policy Identifier. (Note: The default value is 'no-policy'. When ExplicitPolicy is set to 'yes', you must change PolicyOID to indicate which policy or policies are allowed; if ExplicitPolicy is set to 'yes' and PolicyOID is set to 'no-policy', no certificate can pass validation.) This keyword can be configured multiple times both outside any stanza and within a stanza. Configured values are cumulative.

RevocationCheckOrder

A comma-separated list that specifies which sources are used to check for certificate revocation and the order in which these checks occur. The options are 'ocsp', 'cdp', 'crlserver', 'local', and 'none'. The default is 'local'. Note: If you specify just 'none', no revocation checking occurs. If you specify 'none' with other options, PKI Services Manager attempts to determine the revocation status using the specified options until it reaches 'none'. If the certificate revocation status is still unknown at this point, authentication is allowed. This keyword can be configured once outside of any stanza and once per stanza.

StrictMode

Specifies whether strict checking rules (as defined in RFC 3280) are used when validating certificates. Many certificates cannot pass strict checks. The allowed values are 'yes' and 'no'. The default is 'no'. This keyword can be configured once outside of any stanza and once per stanza.

TrustAnchor

Specifies a certificate to use as the final trust point in a certificate chain of trust that Reflection for Secure IT validates. This can be an intermediate CA certificate, a root CA certificate, or a self-signed certificate (which can only validate itself). It can not be a user certificate or host certificate. The value can be either a certificate filename or the contents of the Subject field defined in the certificate (for example TrustAnchor = "CN = Secure CA, O = Secure Corporation, C = US"). If you specify a certificate filename and include full path information, the trust anchor is used regardless of how you configure the CertSearchOrder keyword. If you specify a certificate filename without including full path information, CertSearchOrder must include 'local'; and PKI Services Manager looks for the certificate in your local store. If you specify the contents of the certificate's Subject field, CertSearchOrder must include 'local' and/or 'windows'; and PKI Services Manager looks for the certificate in your local store and/or Windows certificate store. This setting is required. To configure multiple trust anchors, add additional TrustAnchor lines.

Any keywords under a TrustAnchor setting create a stanza. The values you configure within a trust anchor stanza are specific to that trust anchor.