Skip to content

Console Dialog Box Options

Set Data Folder

If you are running PKI Services Manager on Windows, you can change the data directory.

You can choose to use the default data folder or use a custom folder.

To use a custom folder:

  • Click Browse to specify the new data folder location. The folder must already exist, and must be on the computer running PKI Services Manager; network locations are not supported. If no configuration file is present in the new location, you will be given the choice of copying the contents of your existing base directory to the new location, or creating a new, default configuration.

    When Use default is selected, the Data folder option is not available and any path displayed is ignored.

Enable fail-over cluster support

This option configures PKI Services Manager to run in a Microsoft cluster environment. When this option is selected, the value you specify for Data folder should be a local directory on the shared physical disk you have set up as part of your cluster group. To configure a cluster, you must be running the server in a Microsoft cluster environment. The Microsoft cluster service is required to manage access to shared resources.

Test Certificate

Use this dialog box to test if a certificate is valid and to determine which identities can authenticate using a valid certificate.

Note

The certificate validation test applies only to end-entity certificates, not CA certificates. Valid CA-signed root and intermediate certificates will not pass the validation test.

Click Browse to select the user or server certificate you want to test. You can add a certificate from your local store or the Windows certificate store. You can also specify a certificate file that's not in any store.

Operation

  • Validate certificate and revocation

    Validates the specified certificate and checks its revocation status. To pass a validity test, the certificate's trust anchor must be listed on the Trusted Chain pane.

  • List matched mapper rule identities Lists the identities that can authenticate using the specified certificate base on your current Identity > Mapper settings.

  • Perform validate and mapper rule operations Performs both of the above tests.

Click Test to test the specified certificate and view the results.

Public Key Details

To confirm that you have correctly configured the connection between PKI Services Manager and applications that use its services, you can compare either of the public key fingerprints displayed here with values displayed for the PKI Services Manager key in those applications. The fingerprints should be identical.

  • SHA-256 fingerprint - Displays the SHA-256 hash for this key.
  • SHA1 fingerprint - Displays the SHA1 hash for this key (also called Bubble Babble format).
  • MDS fingerprint - Displays the MD5 hash for this key.

General Pane

You need to restart the server for some changes on this pane to take effect.

Option Description
Private key location The path to the private key used to verify the identify of PKI Services Manager. If this doesn't point to a valid key, the service won't start
PKI server address The address on which PKI Services Manager listens for validation requests. The default is 0.0.0.0, which configures the server to listen on all available network adapters. To specify a particular IP address, use the drop-down list. Available IPv4 addresses for your system are shown by default. Click "Show IPv6 addresses" to see available IPv6 addresses.
PKI server port The port on which PKI Services Manager listens for validation requests. The default is 18081.
Enforce DOD PKI settings Enforces settings that meet United States Department of Defense PKI requirements. When this option is selected, the service will not start unless the following conditions are met:
  • On the General pane: - FIPS mode is selected and - Allow version 1 certificates is not selected
  • On the Trusted Chain pane: - Search order to use when building path to trust anchor does not include "Windows certificate store"
  • On the Revocation pane: - Search order to use for revocation has at least one option selected and does not include "None".
    FIPS mode Enforces security protocols and algorithms that meet FIPS 140-2 standards.
    Allow version 1 certificates Allow X.509 version 1 certificates to be used as trust anchors. Intermediate certificates must be version 3 regardless of the value of this setting.
    Client debugging Specifies whether or not debug messages are sent to the application that is requesting certificate validation.
    Log output to file Log files are created daily and saved to a directory called logs located in the PKI Services Manager data directory.
    Maximum log files 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.
    Log level Specifies the amount of information sent to the log. 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. Select None to turn off logging.

    Note

    • Changes made on this pane are saved to the PKI Services Manager configuration file (pki_config).
    • Changes made on this pane do not take effect until you reload the settings (Server > Reload) or restart the server.
    • Changes to the following settings require a restart: Private key location, PKI server address, DOD PKI mode, FIPS mode, Maximum log files, or Log output to file.

    Local Store Pane

    Option Description
    Local store 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). The default local store is: `common application data folder\Micro Focus\ReflectionPKI\local-store` You can add folders or files. When you add a folder, all the contents of the folder, including subfolders, are included in your store. Files must be binary or base 64 encoded X.509 certificates or CRLs.
    Path details Shows certificates available in the selected item under Local Store. To view the contents of a certificate, select it and click View.

    Note

    • Changes made on this pane are saved to the PKI Services Manager configuration file (pki_config).
    • Changes made on this pane do not take effect until you reload the settings (Server > Reload) or restart the server.

    Trusted Chain Pane

    Use the Trusted Chain pane to determine which certificates PKI Services Manager uses to verify the authenticity of certificates presented by authenticating parties.

    Trust Anchors

    Option Description
    Trusted Anchor Lists your trust anchors. Click Add to add a certificate to the list. You can add a certificate from your local store or the Windows certificate store. You can also specify a certificate file that's not in any store.
    Edit Click Edit to configure certificate-specific settings for revocation or identity mapping. Certificate-specific settings override the global settings configured using the Revocation and Identity Mapper panes.
    Clone Use Clone if you have configured certificate-specific settings and you want to add a new certificate that will use all or most of these settings. Select the certificate and click Clone. This displays the Add Trust Anchor dialog box, which you can use to add the new certificate. From the Add Trust Anchor dialog box, click Properties to view or modify the cloned settings.

    Search order to use when building path to trust anchor

    The certificate search list specifies where PKI Services Manager searches for intermediate certificates. Selected locations are searched in order.

    Certificate servers

    Lists servers from which PKI Services Manager can retrieve intermediate certificates. To add a server to the list, select "Certificate servers" under Search order to use when building path to trust anchor, and click Add. You can specify either an HTTP or an LDAP server.

    Add Trust Anchor

    Use these options to select a trust anchor:

    Local store certificate Browse for a certificate in your local store.
    Windows certificate Browse for a certificate in the Windows local computer certificate store.
    Certificate file Browse for a certificate file anywhere on your system.

    Use the Properties button to modify settings for this trust anchor.

    • Properties - Click Properties to configure certificate-specific settings for revocation or identity mapping. Certificate-specific settings override the global settings configured using the Revocation and Identity Mapper panes.

    Local Store Browser

    1. From the PKI Services Manager console, click Trusted Chain.
    2. Under Trust Anchors, click Add.
    3. Select Local store certificate.
    4. Click Browse.

    Use the certificate list in the Local Store Browser to select a certificate from your local store.

    Windows Certificate Browser

    1. From the PKI Services Manager console, click Trusted Chain.
    2. Under Search order to use when building path to trust anchor, select Windows certificate store.
    3. Under Trust Anchors, click Add.
    4. Select Windows certificate.
    5. Click Browse.

    The Windows Certificate Browser is available if you are running on Windows and have selected "Windows certificate store" under Search order to use when building path to trust anchor on the Trusted Chain pane.

    Use the Windows Certificate Browser to select a certificate from the list of trusted root certification authorities in the Windows local computer certificate store.

    Note

    PKI Services Manager uses only those certificates that are installed for use by the local computer (not certificates installed for the current user) and are in either the trusted root certification authorities list or the trusted intermediate authorities list. 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.

    Edit Trust Anchor

    Use the Edit Trust Anchor dialog box to configure certificate-specific settings for revocation or identity mapping. Certificate-specific settings override global settings configured using the Revocation and Identity Mapper panes.

    • Distinguished name - If you are editing properties of an existing trust anchor, this displays the certificate's Subject value. If you are configuring a new trust anchor, this is blank.
    • Override - Clear Override to configure certificate-specific values for a setting. Select Override to restore settings to global values.

    Clone Trust Anchor

    Use the Clone Trust Anchor dialog box if you have configured certificate-specific settings and you want to apply all or most of these settings to a different certificate.

    1. From the PKI Services Manager console, click Trusted Chain.
    2. Select a certificate and then click Clone.

    To clone a certificate

    1. From the Trusted Chain pane, select a certificate and then click Clone.
    2. Use the Clone Trust Anchor dialog box to add the new certificate.
    3. Click Properties to view or modify the certificate-specific settings inherited from the original certificate.

    Specify URI for Intermediate Certificate

    1. From the PKI Services Manager console, click Trusted Chain.
    2. Under Search order to use when building path to trust anchor, select "Certificate servers".
    3. Under Certificate servers, click Add.

    Specify the Address value as a URI (Uniform Resource Identifier) using either LDAP or HTTP syntax.

    For example:

     - ldap://certserver:10389
 - http://certserver:1080

    Revocation Pane

    Option Description
    Search order to use for revocation Determines which sources are used to check for certificate revocation and the order in which these checks occur. If you select "None" and no other options are selected, no revocation checking occurs. If you select "None" along with other options, PKI Services Manager attempts to determine the revocation status using all selected options higher in the search order list. If the certificate revocation status is still unknown after these checks, authentication is allowed.
    CRL servers Lists servers from which PKI Services Manager can retrieve CRLs. To add a server to the list, select "CRL servers" under Search order to use for revocation, and click Add. You can specify either an HTTP or an LDAP server.
    OCSP responder URIs Lists OCSP responders to use for checking the certificate revocation status. To add a URI, select "OCSP responders" under Search order to use for revocation, and click Add. Specify the Address value as a URI (Uniform Resource Identifier) using HTTP syntax. For example: http://ocsp.myhost.com or http://ocsp.myhost.com:1080
    OCSP certificates Lists certificates that can be used to sign the OCSP response. This is needed only if the OCSP response does not include the signer's certificate in its response.
    Settings Opens the Revocation Settings dialog box, which you can use to configure policy OIDs and settings that affect how strictly revocation checking is enforced.

    Note

    • Changes made on this pane are saved to the PKI Services Manager configuration file (pki_config).
    • Changes made on this pane do not take effect until you reload the settings (Server > Reload) or restart the server.

    Revocation Settings

    Option Description
    Override This option is available only if you're configuring trust-specific settings. Clear Override to configure certificate-specific values for a setting. Select Override to restore settings to global values.
    Policy OIDs Enter one or more (comma-separated) OIDs to use when application policies are in force, either because Use explicit policy is selected or because policies are required by the certificate being presented or by a certificate within the chain of trust. Select "Any policy" to allow use of any Policy Identifier. The default value is "No policy". When you select Use explicit policy, you must change this value to indicate which policy or policies are allowed. If Use explicit policy is selected and Policy OID is set to "No policy", no certificate can pass validation.
    Use explicit policy Select this option to enforce application policies. Use Policy OIDs to specify which policy or policies are allowed.
    Strict validation Specifies whether strict checking rules (as defined in RFC 3280) are used when validating certificates. Many certificates cannot pass strict checks.

    Identity Mapper Pane

    PKI Services Manager mapping binds certificates to one or more allowed identities using mapping rules. Typically, allowed identities are users or hosts. For SSH connections, to authenticate a user correctly, you need to define a rule that links information in the validated certificate to an allowed user account. The mapper provides flexible options for mapping certificates to names. You can specify allowed names explicitly in your rules, or define rules that extract information, such as user or host name, from a certificate. By using these options, you can bind identities to certificates without having to create a separate rule for each certificate. Some PKI Services Manager client applications, including Reflection Security Gateway, use PKI Services Manager for certificate validation only, and do not require any identity mapping.

    Note

    • The identity mapping requirements for PKI Services Manager clients vary. For example: The Reflection for Secure IT server supports multiple formats for specifying domain user names in map rules. The Reflection for Secure IT User Manager requires that only one user be allowed for any valid certificate. For additional information refer to information about configuring validation using Reflection for Secure IT in your product documentation.
    • After a certificate is determined to be valid, rules are processed in order (based on rule type then sequence). If the certificate meets the requirements defined in the conditional expression (or if the rule has no condition), the allowed identities specified in that rule are allowed to authenticate. No additional rules are applied after the first match.
    • If no true condition is found, certificate validation fails and an appropriate error message is returned to the validating application.

    Rules for determining how to map a certificate to an identity

    Click Add to configure a new rule. This opens the Add Mapper Rule dialog box, which you can use to construct new rules. Use the arrows to control the order in which rules are processed within each group.

    To use an existing rule as a template for creating a new rule, click Duplicate, then select the copy and click Edit.

    Rules are saved to the map file, which can also be edited directly.

    Tip

    Rule type determines the order in which rules are processed. The order for processing user certificates is: user-address, user, none. The order for processing host certificates is: host, none. Within each rule type, rules are processed in order from top to bottom.

    Settings

    • Refresh rules from file before mapping operation

      When this option is selected PKI Services Manager reloads the map file every time it evaluates a certificate to determine which identities are allowed.

    • Timeout for 'Extern' operations

      Sets the timeout (in milliseconds) to use when you've configured an external application to handle mapping conditions. The default is 0 (zero), which sets no time out.

    Global mappings are saved to the default PKI Services Manager map file. Certificate-specific mappings are saved to a uniquely named map file that is created in the same location. Map files can be viewed and edited directly. For information about rule syntax, see PKI Services Manager Map File Reference.

    Add Mapper Rule

    • As you configure a rule, the constructed rule is displayed at the bottom of the dialog box. For additional information about the rule syntax see PKI Services Manager Map File Reference.
    • After PKI Services Manager determines that a certificate meets the condition defined in a rule, rule processing stops.
    • If the map file contains rules of multiple types, PKI Services Manager first tests user-address rules, then user rules, then the "none" rules (which apply to any certificate). PKI Services Manager stops processing rules with the first successful test.

    Select the type of certificate that is to be mapped

    • Select the type of certificate that is to be mapped

    Specifies whether the rule applies to user or host authentication. Select "Any certificate" to have the rule apply to all authentications.

    • Apply this rule only to this server

      This option is available when the rule type is set to "User Certificate". To apply a rule only to users authenticating to a specific server, enable this setting and then specify the server.

      When PKI Services Manager evaluates this rule, it uses the server name (not the DNS host name) of the server the user is connecting to. The server sends its name to PKI Services Manager when it requests validation of a user certificate, and PKI Services Manager uses that name when applying the rule. To determine the host name that is sent, you can enter the hostname command from a Windows DOS window or from a UNIX terminal session.

    Specify one or more identities for the mapped certificate

    Use the text box to specify which identities can authenticate with a valid certificate. Use spaces to separate multiple allowed identities. If an allowed name includes spaces, enclose it in quotes. For example, to allow users named root, joe, and fred smith to authenticate with a valid certificate, enter: root joe "fred smith"

    Choose certificate identity to insert

    Select an item from this drop-down list to construct the allowed identity set based on the contents of the certificate presented for authentication. In the resulting rule, the percent symbol (%) precedes and follows the item you select. For example, if you are configuring host authentication, you can select "UPN Host" to allow authentication by the host specified in the Host portion of the UPN field. The allowed identity set shows as: %UPN.Host%

    You can combine text strings with extracted information. The following example adds a Windows domain name to an extracted user identity: windomain\%UPN.User%

    You can precede a text string with an extracted identity, and/or add a text string after an extracted identity, but you cannot combine more than one extracted value to form a single identity.

    Specify how the contents of the certificate affects authentication

    • Accept claimed identity

    When this option is selected, no conditions are set on the identity being mapped.

    CAUTION: This option allows the listed identities to authenticate with any valid certificate and should therefore be used with caution.

    • Allow authentication if the following condition is met

    When this option is selected, the set of allowed identities can authenticate only if the condition you configure is true. For details, see "Defining Conditions in a Rule".

    Defining Conditions in a Rule

    A conditional expression takes the form:

    Field Operation Argument

    For Field, select one of the supported options from the first drop-down list. For Operation, select one of the following from the second drop-down list:

    Contains Checks if the Field value is contained anywhere within the Argument.
    Equals Checks for absolute equality between the Field value and the Argument value. (This is the only option available if you select Certificate or Serial/Issuer from the first drop-down list.) For DNS, UPN and Email options, the comparison is case-insensitive.
    External Uses an external application to test the condition. Use the Argument box to point to the external application. Set the identity value to "First match," which is a placeholder for the value returned by the external application. PKI Services Manager sends the value of the field you specify in the first drop-down list to the external application. If the test within the external application is successful, it should exit with status 0; a non-zero return means an unsuccessful match. If you select "Certificate" in the first drop-down list, PKI Services Manager passes two arguments to your external application. The first contains the contents of the certificate in PEM format (text). The second argument contains the path to a temporary file that contains a copy of the certificate in DER format (binary). PKI Services Manager deletes the temporary DER formatted certificate when the external application exits.
    Regular expression Applies the Argument as a regular expression to the Field. If the regular expression includes an exact match to the Field contents, the condition is true.

    For Argument, enter text in the last text box. The required text depends on the Field item you have selected. For example, if you select Serial/Issuer, enter the certificate Serial number followed by the Issuer.

    Fetch Certificate

    Use this dialog box to locate a certificate when you are setting up a rule condition based on both serial number and certificate issuer.

    1. From the PKI Services Manager console, click Identity Mapper.
    2. Click Add.
    3. Select Allow authentication if the following condition is met.
    4. From the field drop-down list, select either Subject or Issuer.
    5. From the condition drop-down list, select Equals.

    6. Click Browse.

    7. Local store certificate - Browse for a certificate in your local store.

    8. Windows certificate - Browse for a certificate in the Windows local computer certificate store.
    9. Certificate file - Browse for a certificate file anywhere on your system.