Configuring a Credential Provider

This section describes the process for configuring a Credential Provider and provides the following:

  • A sample configuration template/profile template XML schema

  • A sample credential profile template data dictionary XML schema

ConfigurationTemplate and ProfileTemplate XML Schemas

The syntax attribute of a ConfigurationTemplate or ProfileTemplate contains an XML schema that ActivID CMS uses to validate operator responses.

In this schema, an attribute definition is provided for each entry in the ConfigurationTemplate. The entry’s key attribute is used to look up the schema attribute definition. Example 1: Sample ConfigurationTemplate illustrates an example of a ConfigurationTemplate.

Example 1: Sample ConfigurationTemplate

Copy 
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault= "unqualified"><xsd:attribute name="userDN" type="string"/>
<xsd:attribute name="retryCount" type="integer"/>
<xsd:attribute name="startDate" type="date"/>
<xsd:attribute name="credDescription">
<xsd:annotation>
<xsd:documentation>
This is a free form description of the credential
</xsd:documentation>
</xsd:annotation>
<xsd:simpleType>
<xsd:restriction base="string">
<xsd:pattern value="[a-zA-Z0-9]*"/>
<xsd:minLength value="1"/>
<xsd:maxLength value="40"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="credentialType">
<xsd:annotation>
<xsd:documentation>
The type of certificate to produce: key encryption, signing or identification
</xsd:documentation>
</xsd:annotation>
<xsd:simpleType>
<xsd:restriction base="string">
<xsd:enumeration value="ENC">
<xsd:annotation>
<xsd:documentation>
Key encryption certificate
</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
<xsd:enumeration value="SIGN">
<xsd:annotation>
<xsd:documentation>
E-Mail signing certificate
</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
<xsd:enumeration value="ID">
<xsd:annotation>
<xsd:documentation> Identification certificate
</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>
<xsd:attribute name="credentialGroups">
<xsd:simpleType>
<xsd:list>
<xsd:simpleType>
<xsd:restriction base="string">
<xsd:minLength value="1"/>
<xsd:maxLength value="10"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:list>
</xsd:simpleType>
</xsd:attribute>
</xsd:schema>

All schema definitions must be <attribute> definitions, as the element structure is not needed for validating simple data, for example:

Copy 
<xsd:attribute name=”...”>
...
</xsd:attribute>

An <attribute name=”...”> entry must appear for every EntryTemplate in the ConfigurationTemplate or CredentialProfileTemplate.

The description of this attribute appears in an <annotation> tag as the first child element of the <attribute>. In enumerated items, the same <annotation> structure appears as the child of each <enumeration>. This is shown in the bold sections of the following sample (Example 2) where these bold sections highlight <annotation> structures in <enumerations>.

Example 2: Sample <attribute> Definition

Copy 
<xsd:attribute name="credentialType"><xsd:annotation>
<xsd:documentation>
The type of certificate to produce: key encryption, signing or identification
</xsd:documentation>
</xsd:annotation>
<xsd:simpleType>
<xsd:restriction base="string">
<xsd:enumeration value="ENC">
<xsd:annotation>
<xsd:documentation>Key encryption certificate</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
<xsd:enumeration value="SIGN">
<xsd:annotation>
<xsd:documentation>E-Mail signing certificate</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
<xsd:enumeration value="ID">
<xsd:annotation>
<xsd:documentation>Identification certificate</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
</xsd:restriction>
</xsd:simpleType>
</xsd:attribute>

The following <simpleType> data types are supported (as per the http:// www.w3.org/2001/XMLSchema namespace):

  • string

  • float

  • double

  • integer

  • long

  • short

  • boolean

  • date

  • base64Binary

In addition to these native XML types, the following HID Global-enhanced type is supported:

  • dnString

HID Global types can be in the following namespace, for example:

http://www.hidglobal.com/provider/credential/types

If used in a configuration or profile syntax, the following attribute must be included in the root element: For example:

Copy 
xmlns:ai="http://www.hidglobal.com/provider/credential/types"

where the syntax schema would use the following type:

Copy 
<attribute name="myDN" type="ai:dnString"/>

ActivID CMS recognizes this type as valid only for Credential Profile dynamic entries. As a dynamic entry, the ActivID CMS GUI allows the ActivID CMS attribute alias to be specified as a customized DN pattern that is validated after the configuring operator has specified it.

The pattern is a string literal with ActivID CMS attributes embedded where each of the attribute names are delimited by the % (percent) character, as in the following example:

Copy 
CN=%DIR.CN%, OU=%DN.OU%, DC=com

ActivID CMS is responsible for validating the syntax of the pattern and the validity of the attributes. Also, per the http://www.w3.org/ 2001/XMLSchema, the following XML schema definition forms of an <attribute> are supported:

  • Type definitions with no restrictions:

    Copy 
    <attribute name="enter_name_here" type="enter_type_here"/>

  • Type definitions with restrictions or an enumerated list where only one value can be selected:

    Copy 
    <attribute name="enter_name_here">
    <xsd:simpleType>
    <xsd:restriction base="enter_type_here">
    <xsd:theRestriction .../>
    ...
    <xsd:theRestriction .../>
    </xsd:restriction>
    </xsd:simpleType>
    </xsd:attribute>

  • Type definitions with restrictions and an enumerated or free form list where multiple values can be selected:

    Copy 
    <attribute name="enter_name_here"><xsd:simpleType>
    <xsd:list>
    <xsd:simpleType>
    <xsd:restriction base="enter_type_here">
    <xsd:theRestriction .../>
    ...
    <xsd:theRestriction .../>
    </xsd:restriction>
    </xsd:simpleType>
    </xsd:list>
    </xsd:simpleType>
    </xsd:attribute>

where theRestriction ... may be one of the following restriction types:

  • minLength—minimum length (suitable for string and base64Binary)

  • maxLength—minimum length (suitable for string and base64Binary)

  • minInclusive—minimum value (suitable for float, double, integer, and long)

  • pattern—a regular expression pattern (suitable for all types)

  • enumeration—a list of possible values (suitable for all types)

Conditional Entries

ConfigurationTemplate and ProfileTemplate objects contain a flat list of entries. These entries can be mandatory or conditional depending on whether the entry has one or more criteria for use. If it contains criteria, these criteria describe a value requirement for another entry; for example:

Copy 
if xyz = abc then this entry is required

If multiple criteria exist within the entry, an attribute specifies whether to logically AND or OR the criteria together in order to reach a binary result of true or false. Each criterion consists of the following:

  • An ID indicating which other entry to examine

  • A value to compare against

  • A comparison type to use when evaluating the criterion (such as equals, greater than, or less than)

CredentialProfiles

The behavior of a CredentialProfile resembles that of a CredentialProviderConfiguration, in that the template entries are populated with concrete values. One additional requirement of the CredentialProfile class is the ability to support dynamic entries.

These special entries are identical to the normal entries in a CredentialProfileTemplate or ConfigurationTemplate, except that they are intended to be populated at configuration time with aliases that are references to external data. These can be context-sensitive per-user or time-sensitive values such as directory attributes or attributes that are output from previous workflow steps.

A dynamic entry is a piece of data that may be different in each credential generated by a Credential Provider. For example, in the case of a PKI Credential Provider, the certificate attributes would be dynamic entries. The operator could specify that the actual value be read from a directory source using ActivID CMS aliases.

It is the responsibility of ActivID CMS to determine whether an entry is dynamic or not. The isDynamic attribute of the Entry class is set by ActivID CMS at configuration time. This is read by ActivID CMS at the credential-provisioning/management-time. Credential Providers have no need to know whether an entry is dynamic or not.

At the credential-provisioning/management-time, the aliases are transformed (outside of the Credential Provider in the ActivID CMS Infrastructure) into concrete values before being passed into the createCredential entry point as entries in the CredentialProfile.

Information Attributes

ActivID CMS uses information attributes to pass mandatory data elements to credential providers. These information attributes may be present in both Configurations and CredentialProfiles.

There is no need for a Credential Provider to request these attributes using templates as they are always provided by ActivID CMS. The Credential Provider is not required to use these information attributes; whether or not it does generally depends on the functionality that is implemented by the credential provider.

ActivID CMS supports the following information attributes:

  • com.activcard.provider.transport.certificate

The encryption certificate used to transport sensitive information from the Credential Provider back to ActivID CMS is always provided in each CredentialProviderConfiguration. The transport encryption certificate is provided by ActivID CMS as an X.509 certificate represented as a base64-encoded string.

  • com.activcard.provider.cmsuser.DN

The distinguished name of the ActivID CMS user in the ActivID CMS LDAP directory is always provided in each CredentialProfile. The cmsuser.DN is provided by ActivID CMS as a fully distinguished name of type DNString.

CredentialProfileTemplate Data Dictionary XML Schema

To make it possible for ActivID CMS to filter Credential Profiles based on different criteria, it is necessary for each Credential Provider to return the complete data dictionary of all possible EntryTemplates that may appear in any of the CredentialProfileTemplates returned by the Credential Provider.

This is accomplished by using thegetDataDictionary() method of the CredentialProvider interface, where the data dictionary is returned as a limited-scope XML schema describing the CredentialProfileTemplate syntax for all possible EntryTemplate keys.

The format of the XML schema data dictionary is identical to the format of the XML schema of ConfigurationTemplates and ProfileTemplates, with the exception that the list of attributes defined is the exhaustive superset of the attributes relevant to all templates. Only the attributes relevant to a specific template are included in the ConfigurationTemplates and ProfileTemplates.

Provider Lifecycle Processes and Actions

CredentialProviderContexts and individual Credentials are able to support different lifecycle processes and actions. The set of processes and actions supported by each Credential associated with a given CredentialProfile is a subset of the processes and actions supported by the corresponding CredentialProviderContext.

CredentialProfiles are used to create Credentials and they specify the set of processes and actions supported for Credentials created with a particular CredentialProfile. The processes and actions reported as the capabilities of the Credential Provider are the processes and actions that can be used in the CredentialProviderContext’s performProcess and updateCredential methods for all Credentials created using that CredentialProfile.

For example, for a given PKI provider a CredentialProfile supporting PKI encryption would support the recover action, whereas a PKI signature CredentialProfile would not support that same action since signature keys are not usually archived.

The set of processes supported by a given Credential can be obtainable using the getProcessTypes() method. The set of actions supported by a given Credential is obtainable using the getActionTypes() method.

External Processing

Various credential management tasks may require multiple steps to achieve one high-level credential task. Between these steps, it is sometimes necessary for an entity or component external to the provider to provide some additional information resulting from an external operation in order for the Credential Provider to complete its processing. For example, these might include using one of the following:

  • Signing a certificate request with an on-card private key for Proof of Possession (POP)

  • Generating an on-card RSA key pair

  • Injecting private keys or certificates onto a security module

This mechanism is provided using the concept of External Operations, and realized in the ExternalOperation class. All external operations that are returned by a Credential Provider must use the concrete ExternalOperation class itself, not an ExternalOperation sub-class.

A Credential Provider is not allowed to store contextual information associated with transactions in the external operation object itself. Contextual information associated with transactions must be maintained internally by the Credential Provider and linked to returned TransactionIds.

This release of ActivID CMS supports a set of documented HID Global plug-ins that have been tailored to support PKI Credential Providers.

The type of each of the following external operations is securitymodule. The type of external operation determines the logical component or entity that interprets this operation and triggers its execution.

The securitymodule type implies that the external operations are to be serviced by the security module and the components that interface with the security module. The supported securitymodule external operations are:

  • generateKeyPair: Generates a key pair in the security module and returns the public key

  • injectData: Injects private keys and certificates into the security module

  • signData: Performs signing of data for use in POP signatures

External processing may be required by various credential management operations as determined by the Credential Provider’s internal workflow.

External Operations may be generated and require external processing as a result of the following:

  • Credential creation

  • Credential update

  • Credential deletion

  • Credential lifecycle processes

An External Operation is essentially a collection of data that requests specific functionality be performed, external to the Credential Provider, which contain:

  • A set of name/value parameters to be used as inputs to these external processes.

  • A script type indicating what type of script is requested for execution. The script type must always be a lowercase, hierarchical, and dot-notated list. The type hierarchy is used to select the interpreter of the script.

  • A credential profile identifier indicating the credential for which the external operation is to be executed.

  • A set of name/value ResponseParameters resulting from these external processes.

Each parameter has the following additional attributes to aid in the use of the data:

  • The parameter’s type attribute is optional and if not supported defaults to a type of string.

  • The parameter’s encoding attribute is optional and if not supported defaults to None.