Smart Card Parameters in Management and Security Server

Host Access Management and Security Server supports smart card authentication on Windows platforms. This technical note provides details about configuring smart card parameters.

About Smart Cards and Digital Certificates

Smart cards store digital certificates that can be used to validate (authenticate) a user’s identity to the network.

Digital certificates are used in X.509 systems, and are part of an organization’s public key infrastructure (PKI). The certificates must be issued by a trusted third party, such as a certification authority (CA) set up within a company’s private network.

Each certificate contains:

• the user’s identification information.
• the user’s public and private key pair.
• the issuing entity’s digital signature, which verifies that the certificate was issued by a valid certification authority (CA).
• an expiration date or a time period for which the certificate is valid.

Smart Card Parameters in Management and Security Server

Only one certificate from a user’s smart card is used for authentication. In Management and Security Server, the Smart card parameters setting filters out the unusable certificates to identify and select a valid certificate. This Identity certificate can then be used for login or client authentication.

This document refers to Management and Security Server's default smart card parameter to identify the logic of the filters and how they can be changed to work in your environment.

Locate the default smart card parameter:

1. In Management and Security Server, open Administrative WebStation > Security Setup > Security tab.
2. Scroll to Smart card parameters, and note the default entry.

View Full Size

The default parameter is this continuous line:

The Parts of the Parameter

The parameter begins with the smart card provider followed by a series of filters.

Smart Card Provider

The first part of the parameter identifies the software provider that Management and Security Server should use to access the smart card certificate reader on the client machine. In the default parameter, sunpkcs11 is the intended software provider.

Valid provider values:

• sunpkcs11: By default, Management and Security Server uses PKCS#11 (Public-Key Cryptography Standard) mechanisms to access smart cards.

• mscapi: Management and Security Server works with the native Windows MS-CAPI/CNG (Microsoft Crypto API/Next Generation) to access valid smart card certificates.

• baltimore: This legacy code, which uses ActivClient, can be used to access some smart cards but may not support newer certificate formats.

Using Multiple Providers

If some clients in the organization use sunpkcs11 and some use mscapi, both providers can be specified by separating them with a space (" "). List the preferred provider first because Management and Security Server uses them in sequence (from left to right) until a certificate with that provider is found.

A sample entry for multiple providers looks like this:

Note: A colon (":") is required after the provider name when one or more filters are used.

You may need to consider Multiple Smart Cards for One User.

Filters

The next part of the default parameter is made up of two filters, separated by a semi-colon (";").

Each filter consists of Object-ID (OID) masks that specify certificate attributes.

Object-ID (OID) Masks

After Management and Security Server locates all of the potential certificates on the client machine, then the OID masks are applied. The masks specify certificate attributes and locate the certificates that qualify for login or client authentication.

If the results identify a single certificate, then that one is used for the login or client authentication. If the results identify several certificates, then the user will be shown a certificate “Chooser” dialog to select one of the qualified certificates.

Note: In the default parameter, the first filter is for Personal Identity Verification (PIV) smartcards, and the second filter is for Common Access Cards (CACs). During the scan, if the first filter fails to identify a single certificate, the remaining filters are attempted in sequence until a single certificate is obtained. If no filters succeed, then the Chooser dialog displays all potential certificates.

Using Multiple Masks

Organizations that support different smart cards (such as PIV and CAC) may need to use more than one mask. Sometimes one mask works for two similar cards, such as two PIV cards.

When using multiple masks to identify a single certificate for each smart card, specify the most complex masks before the masks with a smaller set of qualifying attributes. Test the sequence of the masks on a machine that holds each of the organization’s supported smart cards to verify that at most a single certificate is identified from each smart card. Adjust the order of the masks to fine-tune the results.

You may need to consider Multiple Smart Cards for One User.

Certificate Attributes

The masks specify which certificate attributes (encoded tokens) MUST (+) or MUST NOT (-) be on the Identity certificate before it can be used for login or client authentication. The distinction is used to disqualify certificates that are not preferred.

Each certificate attribute specification must be valid (does or does not exist) for a certificate to be a valid choice for login or client authentication.

The attributes of a mask are separated by commas (",").The default parameter includes five certificate attributes in the first filter:

The second filter includes three attributes:

The Logic of Certificate Attributes

Each attribute begins with either KU (Key Usage) or EKU (Extended Key Usage). KU and EKU are followed by values that either MUST (+) or MUST NOT (-) be on the smart card certificate.

Key Usage. (KU) indicates the purpose of the public key. The key usage extensions can be used to restrict the public key to as few or as many operations as needed. Nine standard types of uses are intended for digital (X.509) certificates.

The six-character KU values either MUST (+) or MUST NOT (-) be present on the certificate. Valid Key Usage OIDs include:

Extended Key Usage. (EKU) further refines key usage extensions and enables the user to choose a certificate based on whether the certificate can be used for the intended purpose.

The seven-character EKU values either MUST (+) or MUST NOT (-) be present on the certificate. Variations can be added to this list of valid Extended Key Usage OIDs:

Other attributes. In addition to KU and EKU, other attributes can be used with the OID masks. For example:

• SAN+UPN: indicates that there MUST be a User Principal Name (UPN) field within the Subject Alternative Names (SAN) structure on the smart card
• SAN-UPN: indicates that there MUST NOT be a User Principal Name (UPN) field within the Subject Alternative Names (SAN) structure on the smart card.

The Logic in the Default Parameter

The filters in the default parameter use a logic that all OID masks must be TRUE for the certificate to be valid for authentication. If one mask is FALSE, the certificate is disqualified for that filter. If all of the potential certificates are disqualified by one or more tokens of a mask, then the filtering is tried again with the next mask.

Looking at the default parameter, the first filter uses the following logic for each attribute to be TRUE:

• KU+DIGSIG: Key Usage of Digital Signature OID MUST be present in the certificate.
• KU-NONREP: Key Usage of Nonrepudiation OID MUST NOT be present in the certificate.
• EKU+CLIAUTH: Extended Key Usage of Client Authentication OID MUST be present in the certificate.
• EKU+SCLOGIN: Extended Key Usage of Smart Card Login OID MUST be present in the certificate.
• EKU-EMLPROT: Extended Key Usage of Email Protection (called Secure Email) OID MUST NOT be present in the certificate.

• KU+DIGSIG: Key Usage of Digital Signature OID MUST be present in the certificate.
• KU+NONREP: Key Usage of Nonrepudiation OID MUST be present in the certificate.
• EKU-NONE: Extended Key Usage MUST NOT be present in the certificate.

Multiple Smart Cards for One User

Some users may have more than one smart card. When two or more smart cards are in the smart card readers attached to a user's machine, it is possible that one provider (such as sunpkcs11) is able to read one of the cards, and that a different provider (such as mscapi) would work for another smart card.

When two or more smart cards are read, the Chooser will contain two or more Identity certificates. The user must select the proper certificate based on something unique about the Subject names of the Identity certificates. For example, the user must be able to recognize the name on the certificate that is used to authenticate to MSS, as opposed to a certificate used to authenticate to a host.

To select the proper certificate, the client will typically recognize the name in the “Name” column of the Chooser.

Smart Card Libraries

Management and Security Server provides a field to designate smart card libraries. The libraries are required when using sunpkcs11 to access smart cards.

In the library examples provided in Management and Security Server, you could use acpkcs211 instead of acpkcs, and acpkcs211.dll instead of acpkcs201.dll. Separate the library names by commas.

Designate smart card libraries.

View Full Size

Notes:

• Many libraries can be listed. Management and Security Server needs to find only one that matches the software on a given user's machine.
• If clients logging on to Management and Security Server use either Java 7 or ActivClient 7.0.x, then use the Windows 8.3 representation of “Program Files” in the full path.

• To cover the likelihood that both 32-bit and 64-bit clients will access Management and Security Server and may be using both Java 7 and ActivClient 7.x.x, include both paths to a given dll.

• If the clients logging on to Management and Security Server use Java 8 or higher, then the 8.3 notation is not required.

Determining Whether a Certificate Meets a Smart Card Parameter's Requirements

Now you can apply your knowledge of the smart card parameters and the logic of certificate filters.

Examine two sample certificates from a user's smart card (CAC), and determine whether the certificate meets the requirements in Management and Security Server's default parameter, thereby enabling the user to authenticate.

Note: All of the OID masks must be TRUE for the certificate to be used for authentication.

Sample #1: Apply the first filter to this certificate on a CAC.

Start with the first filter. If the parameter requirements are met, the certificate would be valid. For reference, here is the first filter of the default parameter:

Does this certificate meet the first filter's requirements?

Compare the first filter's requirements with the values on the certificate:

Result: Because the KU-NONREP mask is FALSE, that certificate is not valid for this mask. However, another certificate in the list of potential certificates may be valid for this mask. But if all the certificates in the list are not valid for this mask, the Management and Security Server would proceed sequentially to examining the list with the next filter.

Sample #2: Apply the second filter to the same certificate on the same CAC.

Since the first filter failed, try the second filter. For reference, here is the second filter of the default parameter:

Does this certificate meet the second filter's requirements?

Compare the second filter's requirements with the values on the certificate:

Result: Because all of the values are TRUE (there is no Extended Key Usage), the certificate can be used for authentication.

Sample #3: Apply the first filter to a different certificate on the same CAC.

As another test, compare a different certificate with the default parameter's first filter. For reference, here is the first filter:

Does this certificate meet the first filter's requirements?

Note: The images highlight the Key Usage and Extended Key Usage lines in one certificate.

Compare the first filter's requirements with the values on this certificate:

Result: Because the KU-NONREP mask is FALSE, the certificate is not valid. The latter values do not affect the decision when an earlier value is FALSE.

References

Host Access Management and Security Server – Technical Resources:

https://support.microfocus.com/product/?prod=MSS

Legacy KB ID