Certificates requested using card production or operation tasks

This article contains information about the state and object relations of the certificates issued during card production and operation tasks and how to access these certificates in the process. When a card production or operation task requests a certificate from a Certificate Authority (CA), the certificate is persisted in Identity Manager and an object relation may be created to a card. The new certificates can appear in the process variables. This can be configured to accommodate various use cases.

A requested certificate is persisted as soon as it is received from a CA, even before it is written on the card. At this point, it will be in the state Issued. The exception to this rule is recovered certificates: These were already persisted in Identity Manager the time they were initially issued and they will not be persisted again, nor will their state be changed. They can however be related to the cards they are written to during a recovery, as described below.

When the card production or operation task has successfully finished, the certificates' state will be set from Issued to their start state as defined in the state graph.

certificateHold

You can temporarily revoke a certificate upon issuing it using the keyword revokeOnIssue. This will instruct the CA to revoke the certificate using the revocation state certificateHold. However, in Identity Manager, the certificate will still be in its start state. If the certificate's start state is not certificateHold, you must add a Change State task to the process to set the certificate's state accordingly.

Should the task end in an error instead, they will remain in the Issued state.

Issued state

Issued is an internal state for certificates. It is set on just issued certificates, before they are later set to their start state. This state makes it possible to search for certificates that were issued during failed card operations. These certificates were issued by a CA to an end entity, but were probably not successfully written on a card. To avoid having unused valid certificates, it is recommended that these certificates are revoked. Per default there is no further handling of these certificates. You need to find a way to handle them that suits your needs.

Since all certificates are initially stored in the state Issued and later moved to their start state, this transition needs to be defined in the certificate's state graph definition.

Looking for certificates in the Issued state is a way of finding certificates that were requested but were probably not written on a card and should therefore be processed, for example, revoked. There is no default handling of issued certificates, but it is recommended to do one of the following:

search for them and implement a process that handles any that are found
handle them directly in the process when an encoding fails, using the generated certificate's CoreObjectDescriptors, as described below.

A difference between a card production (Identity Manager Operator only) and a card operation (Smart ID Self-Service and Identity Manager Operator) is that a card production task generates a card object, while a card operation task does not. A card operation task is usually (but not necessarily) executed on an existing card object.

In case of a Card Production task, relations can be created between the produced card and the requested certificates.
In case of a Card Operation task, relations can be created if there is a card in the process variables at the time the task is executed.

After the task has finished, CoreObjectDescriptors for the generated certificates can be set in the process map, to facilitate working with the new certificates. For example, they can be revoked if the task ended in an error, indicating a problem during the card encoding.

You can change the state in which issued but not yet written certificates are persisted from Issued to a different value.

WAR file deployment

For WAR file deployment, this is set in WEB-INF\classes\system.properties:

stateGraphDefinitionManager.certificateInternalIssuedState=MyCustomState

Docker deployment

For docker deployment, this is set in compose\identitymanager\operator\docker-compose.yml.

services:
  smartid-idm-operator:
    ...etc...
    environment:
      ...etc...
      - 'SYSTEM_PROPERTIES={
          "stateGraphDefinitionManager.certificateInternalIssuedState": "MyCustomState",
          ...etc...

The following requirements apply to the custom Issued state you configure:

All configured certificate state-graphs MUST contain this state and have a transition from it to the respective start state.
State MUST be configured in every certificate template.
State MUST NOT be used for any other purpose.

CreateObjectRelation: Configures the creation of object relations between the card and the requested certificates.
- always: Always creates an object relation between the card and the certificate. In case of a Card Operation, if there is no card in the process map, an exception will be thrown during the encoding, as a relation can not be created.
- success (default): Creates an object relation only if the complete task ends in success. In case of a Card Operation, if there is no card in the process map, no relation will be created.
- never: Do not create any object relations.
ObjectRelationType: This can optionally be used to specify the type of the object relation between a card and a certificate.
CertCoreObjectDescriptorReturnField: If present, the CoreObjectDescriptor of the generated certificate will we set in the specified field. The field must be specified in the encoding's fields and mapped to a process variable. Thus the CoreObjectDescriptor of the issued certificate will be put in the process map. This has no effect in case of a certificate recovery.

Example

This is an example of encoding using the above keywords.

Sample encoding description

[Encoding]
Type=1024,Chip
Devices=8711
 
[Fields]
PIN=
# Declaration of the field to which Application_A will set the CoreObjectDescriptor of the generated certificate (see line 24).
# In the Encoding Fields, the name of a process variable must be set as a value for this field, e.g. "${theGeneratedCertificate}"
# This would result in a process variable "theGeneratedCertificate" being created that would hold the CoreObjectDescriptor.
GeneratedCertApp_A=
 
[Description]
PKCS11Library=...
PIN=PIN
Applicationlist=AB

[Application_A]
CertTempl=AuthCertificate
# Create an object relation even if the card encoding fails
CreateObjectRelation=always
# Instead of the default object relation, create one of type "HAS_A"
ObjectRelationType=HAS_A
# Set the CoreObjectDescriptor of the generated certificate on the field "GeneratedCertApp_A", see also the fields above.
CertCoreObjectDescriptorReturnField=GeneratedCertApp_A

[Application_B]
CertTempl=EncCertificate
# No further configuration. 
# * The object relation will only be generated if the entire encoding ends successfully.
# * The object relation will be of the default type.
# * The CoreObjectDescriptor of the issued certificate will not be put into the process map.