Skip to content

pki_mapfile Map File Reference

Reflection 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.

The default map filename and location is:

  • UNIX

    /opt/microfocus/pkid/``config/pki_mapfile

  • Windows:

    ProgramData\Micro Focus\ReflectionPKI\config\pki_mapfile

    Note

    On Windows systems, you can modify the map file from the Reflection PKI Services Manager console using the Identity Mapper pane.

File Format

The map file consists of keyword settings and rules. Each rule is a single line and is independent of other rules. The format of a rule is:

{Allowed-Identity} [Conditional Expression]

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.

Within the map file, you can use the RuleType keyword to apply different mapping criteria based on whether a user or host presents the certificate. Note: 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.

Allowed Identity Set

The allowed identity set is a required component of a rule. Allowed identities can be specified using a combination of constant values and values extracted from the certificate. The set of allowed identities can take multiple constant values, extracted values, or a combination of both. The identity mapping requirements for PKI Services Manager clients vary. For example: The Reflection for Secure IT UNIX Client and Server server supports multiple formats for specifying domain user names in map rules. The Reflection for Secure IT UNIX Client and Server 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 UNIX Client and Server in your product documentation.

Using constant values to define allowed identities

Constant values are literal strings. Use white space to delimit separate values. (If an allowed name includes spaces, enclose it in quotes.) For example, the following rule uses literal strings to allow root, joe, and fred smith to authenticate with any valid certificate:

{ root joe "fred smith" }

Note

After PKI Services Manager determines that a certificate meets the condition defined in a rule, rule processing stops. In the example above, no conditions are defined. This means the rule will be applied to any valid certificate and no subsequent rules will be processed. To create a similar rule, you would need to include all allowed identities within the same rule.

Two asterisks used alone { ** } act as a wildcard for defining the allowed identity set. This option may be useful for testing, but should otherwise be used only with extreme caution. If you use this wildcard in a user rule, any user presenting a valid certificate is allowed to authenticate to any user account on the server. This creates a major security risk by allowing access to accounts with root, administrator, or power user privileges without requiring a password. If you use this wildcard in a host rule, any server with a valid certificate is accepted by the client. If you do choose to use the wildcard, consider limiting access using other options:

  • Use the wildcard only with certificates signed by Certification Authorities that you control.

  • Use the wildcard only in rules that have very restrictive conditions.

  • Use the wildcard only in server-specific user rules (those whose RuleType is user-address).

  • Limit user account access on the server side. For example, on a Secure Shell server, you might define sftp chroot jails and allow no command shell or remote command access.

Using values extracted from the certificate

Use extracted values to construct the allowed identity set based on the contents of the certificate presented for authentication. Extracted values must be preceded and followed by "%". For example, to allow authentication by the host specified in the Host portion of the UPN field:

{ %UPN.Host% }

You can also combine literal strings with extracted identities. (You can prepend a literal string to an extracted identity, and/or append a literal string, but you cannot combine more than one extracted value to form a single identity.) The following example adds a Windows domain name to an extracted user identity:

{ windomain\%UPN.User% }

Note

If the extracted identity evaluates to an empty result, the entire concatenated string is deemed to be empty and is not included in the set of allowed identities. If the entire set of allowed identities is empty,the rule is deemed to have failed and processing continues to the next rule.

Supported certificate fields are:

  • Subject

    The Subject field defined in the certificate. The comparison is done following X.500 rules (not as a string comparison). For a successful match, the format must follow standards described in RFC 2253. To be compliant with this standard, Subject and Issuer fields start with the Common Name (for example, "CN = Secure CA, O = Secure Corporation, C = US").

    On UNIX systems, you can use the ssh-certview utility to obtain the Subject value in this format.

    On Windows systems, copy the Subject contents from the Details tab of the certificate viewer, paste to an editor, and then replace new line characters with commas.

  • Subject.CN

    The Common Name portion of the Subject field, if present.

  • Subject.Email

    The email attribute part of the Subject, if present.

  • DNS

    The DNS part of a SubjectAltName, if present.

  • IPAddress

    The IP Address part of a SubjectAltName, if present. (PKI Services Manager version 1.2 and later.)

  • UPN

    The "otherName" representation of the SubjectAltName field, with the OID of 1.3.6.1.4.1.311.20.2.3 (UPN OID), if present.

  • UPN.User

    The userID portion of the UPN field.

  • UPN.Host

    The host portion of the UPN field.

  • Email

    The representation of SubjecAltName as defined in RFC 822.

  • Email.User

    The userID portion of Email.

  • Email.Host

    The host portion of Email.

  • SerialAndIssuer

    The certificate serial number (hex encoded) and value of the certificate's Issuer field in this format:

  • serial_number Issuer**

    Use white space to separate the serial number from the issuer. For example:

    461D07A8 CN = Secure CA, O = Secure Corporation, C = US

  • Cert

    This indicates the entire certificate. The Operation must be Equals and the argument must be a file path to a certificate.

    Note

    The Mapper does not use the certificate store defined by Reflection PKI Services Manager.

  • subst

    This option is available when the conditional expression within a rule uses either Regex or Extern.

    With Regex, use subst in combination with any regular expression that has a capturing group, which has been identified using round brackets (). If the regular expression includes an exact match to a specified certificate field, the value of the first capturing group in the expression replaces %subst% in the allowed identity set.

    With Extern, use subst as a placeholder for the value returned by the external application.

Conditional Expression

When a conditional expression follows the {Allowed-Identity}, the allowed identities can authenticate only if the conditional expression is true. The use of a conditional expression is optional, but in most cases is recommended. If no conditional expression is included, the allowed identities can authenticate with any valid certificate.

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.

The syntax for a conditional expression is:

Field Operation Argument

For Field, specify any of these supported certificate fields (described above): Subject, Subject.CN, Subject.Email, DNS, IPAddress, UPN, UPN.User, UPN.Host, Email, Email.Host, SerialAndIssuer, Cert, or subst.

For Argument, specify a string value.

For Operation, use one of the following:

  • Equals

    Checks for absolute equality between the Field value and the Argument string. For DNS, UPN and Email options, the comparison is case-insensitive.

  • Contains

    Checks if the Field value is contained anywhere within the Argument string. For DNS, UPN and Email options, the comparison is case-insensitive.

  • Regex

    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. If the set of allowed identities contains the string %subst%, the first capturing group (if defined) of the Regex match is inserted.

  • Extern

    Uses an external application to test the condition. Use Argument to point to the application. Use %subst% in the allowed identity set as a placeholder for the value returned by the external application. PKI Services Manager sends the Field value you specify 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 the Field value you specify is Cert, 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.

Sample rules with conditional expressions:

{ %UPN.Email% } Subject.CN Equals acme.com

{ joep } Subject Contains "Joe Plumber"

Rule Type Stanzas

Rule types apply different mapping criteria based on whether the validated certificate is a user certificate or a host certificate. Use the RuleType keyword to create a new stanza for each supported type. A stanza ends at the next RuleType keyword or the end of the file. The format is:

RuleType type

Valid rule types are:

  • none

    The rule applies to both hosts and user certificates.

  • host

    The rule applies to host certificates only.

  • user

    The rule applies to user certificates only.

  • user-address= server

    The rule applies only to user certificates authenticating to the specified server. Note: When PKI Services Manager evaluates a user-address 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 user-address 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.

    For example, to create rules that apply only to users connecting to the server acme:

    RuleType user-address=acme

    Note

    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.

Keywords

  • DynamicFile

    Specifies whether PKI Services Manager reloads the map file every time it checks for allowed identities. The allowed values are 'yes' and 'no'. The default is 'no'.

  • ExternTimeout

    Sets the timeout for rules that use the Extern option. The default is 0 (zero), which sets no time out.

  • RuleType

    Marks the beginning of a rule type stanza, which can be used to apply different mapping criteria based on whether a user or host presents the certificate. The allowed values are 'user', 'host', 'none', and 'user-address = server'. The default is 'none'.