Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Smart ID 23.10.5: Added a section about how to delete orphaned keys from a card using encoding label filters.
Info

This article includes updates for Smart ID 23.10.5 

An encoding description contains the information for the electronic personalization of a card. You import the encoding description from a file. This article describes how you create descriptions on how to handle certificates and keys. This can be used in Smart ID Identity Manager.

See also Structure of an encoding description in Identity Manager.

Read and write certificates

Write a certificate

Define like this in the encoding description:

Code Block
[Fields]
CERT_FIELD=
...
 
[Application_A]
WriteCertificate=true
Certificate=CERT_FIELD

Description of the elements:

Element

Description

WriteCertificate=true

Triggers to write a certificate.

Certificate=...

Specifies from which defined field the certificate is taken. The field's value has to be a base64 encoded X.509 certificate.

Write a Certificate-Key-List

Use this application command to write a structure of base64 encoded certificate and base64 encoded keypair to the smartcard. It can be used as a surrogate to writing a PKCS#12 container directly to the smartcard (even with root and intermediate certificates, that have no private key attached).

Define like this in the encoding description:

Code Block
[Fields]
ENCR_CERT_KEY_LIST=
ENCR_CERT_KEY_LIST_RETURN=
...
 
[Application_C]
WriteCertKeyList=true
CertKeyList=ENCR_CERT_KEY_LIST
CertKeyListReturnField=ENCR_CERT_KEY_LIST_RETURN
CertKeyListMode=WRITE_ANY_BUT_MANDATORILY_THE_FIRST

Description of the elements:

Element

Description

WriteCertKeyList=true

Triggers to write a certificate-key-list.

CertKeyList=... 

The description key for the input string. (Corresponds to the structure: "<1. cert>,<1. private key>;<2. cert>,<2. private key>;..." without the square brackets, see examples below. You can pass one or multiple certificate-key like that, each base64 encoded.)

The base64 encoded certificate is left-handed to the comma separator and the base64 encoded private key (if any, otherwise empty) is right-handed to the comma separator and each pair of certificate-privatekey is terminated by a semicolon. The certificate and private key are both in DER encoded format and then each base64 encoded.

CertKeyListReturnField=...

The description key where to set the field definition that later gets the list of written certificates.

CertKeyListMode=...

Sets the mode for reacting on errors when writing the certificate-key-list to the smartcard. Options are:

  • WRITE_ALL (default) - All certificates and keypairs have to be successfully written, otherwise the application was not successful.

  • WRITE_ANY - This is the "don't care" case.

  • WRITE_ANY_BUT_MANDATORILY_THE_FIRST - In this mode the first certificate-key has to be mandatorily written successfully (the others may be not written) in order to have this application be successful.

The certificates are sorted chronologically (newer certificates first), that is, if the card is full (and you did not set "WRITE_ALL"), only some older certificates may be unwritten.

Note: StoreUserCertsOnly is ignored for the WriteCertKeyList use-case and all certs from the list are written.

Delete certificates and other objects

Delete certificates

To delete certificates (and optionally their associated keys) on a token, it can be necessary to select special certificates by a selection criteria.

Define like this in the encoding description:

Code Block
[Fields]
DEL_CRITERIA=

[Application_A]
DeleteCertKeyObjects=true
DeleteCertKeyObjectsCriteria=DEL_CRITERIA

[Application_B]
DeleteCertKeyObjects=true
DeleteCertsOnly=true
DeleteCertKeyObjectsCriteria=Key_Usage(keyEncipherment,dataEncipherment)

Description of the elements:

Element

Description

DeleteCertKeyObjects=true

Enables deletion of certificates and their associated keys according to given criteria. The parameter name is historic and retained for compatibility.

DeleteCertsOnly=true

Overrides the default behavior of deleting certificates and keys and instead deletes certificates only.

DeleteCertKeyObjectsCriteria=... 

Defines the selection criteria to be used to find the certificates. This option can have one of these values:

  • SOME_FIELD_NAME
    The name of a mapped field, containing one of the deletion criteria shown below:

  • KeyUsage (fixed, comma-separated strings) 
    or
    Key_Usage (fixed, comma-separated strings)
    Pass at least one string, which can be mapped to an implementation of type ICertificateSelectionStrategy. Only certificates (with their keys) matching exactly these specified KeyUsage(s) will be deleted. Possible values are decipherOnly, encipherOnly, cRLSign, keyCertSign, keyAgreement, dataEncipherment, keyEncipherment, nonRepudiation, digitalSignature

  • Label (fixed string)
    The label of the certificate and keypair to be deleted. Only one value can be set here. To delete more than one certificate by label, add multiple applications.

  • CertSerial (fixed, comma-separated strings)
    or
    Cert_Serial (fixed, comma-separated strings)
    Pass at least one certificate serial number in hex-format.

It is not possible to leave the parentheses empty.

If you use a mapped field, you can link it to a process variable created e.g. via a Groovy script like this:

Code Block
languagegroovy
binding.variables["MY_DELETION_CRITERA"] = 'CertSerial(' + binding.variables["MyCertDataPool_CertSerial"] + ')'

Delete orphan keys

Orphan keys are private and/or public keys that have no matching certificate on the card. This can happen for example when a keypair is created but the certification request fails because the CA is unreachable. Typically this leads to a useless keypair on the card.

You can delete such orphan keys. The keys can be selected by their label or you can delete all orphan keys of a card. If a key does have a matching certificate, it will not be deleted without raising any error.

Define like this in the encoding description:

Code Block
[Application_A]
DeleteOrphanKeys=Label(Jane Doe Auth, Jane Doe Enc)
[Application_B]
DeleteOrphanKeys=Label()

Description of the elements:

Element

Description

DeleteOrphanKeys=Label(…)

This will trigger deletion of all orphan private and/or public keys with the labels specified. Several labels can be separated using comma. If the label is empty, like in the second example, all orphan public and private keys will be deleted.

Delete all objects from smartcard

This use case clears all objects (actually just public- and private keys and certificates) from the smartcard, instead of re-initializing the smartcard. This is done by searching all objects on the smartcard and executing a delete operation on each returned object handle. (You just need to login with PIN, to be able to also search for private keys and delete them. No PUK or SO-PIN needed.)

Define like this in the encoding description:

Code Block
[Application_A]
DeleteAllObjects=true

Description of the elements:

Element

Description

DeleteAllObjects=true

Triggers the use case.

Save certificate with specific object relation type

Save certificate with specific object relation type

You can specify the relation type between card and certificates. Otherwise the default is used (see Object Relation section in Identity Manager Admin):

Define like this in the encoding description:

Code Block
[Application_A]
ObjectRelationType=MyRelationType

Description of the elements:

Element

Description

ObjectRelationType=

Provides the possibility to save the card and certificate to a specified object relation type. If this is not provided in the encoding description, Identity Manager uses default relationship. 

PKCS#10 requests

Generates a key pair on the smartcard and then invokes a PKCS#10 request (Certificate Signing Request) to a CA (defined by a certificate template name). After receiving the response from the CA with the signed certificate (and optional CA certificates), the user certificate will be written to the beforehand generated key pair. Available CA certificates will also be written to the smartcard to form the chain of trust (can optionally be disabled, see heading "Skip Writing CA Certificates"). Afterwards the CKA_ID and labels of the keys will be modified to match the ones of the written user certificate.

Define like this in the encoding description:

Code Block
[Fields]
SIGN_PUBKEY=    ## optional
AuthCertificate.CN=  ## Only needed prior to sprint 166
AuthCertificate.C=   ## Only needed prior to sprint 166
...
 
[Application_A]
CertTempl=AuthCertificate
PubKeyReturnField=SIGN_PUBKEY    ## optional

Description of the elements:

Element

Description

CertTempl=... 

Defines the certificate template name to be used, which is configured to reference the CA and the token procedure on the CA.

PubKeyReturnField=...  (optional)

Set this to get the PublicKey back into the mapped fields, that is, into the task.

Temporary revoke a certificate right after P10-request

When requesting a certificate by CSR (P10-Request), it is very useful to also revoke that certificate right after it has been requested (inside jpki_encoder), that is, on client-side before communicating back to the server. This helps in cases where an error occurs and the server could, for example, not fulfil further steps with this certificate. It also benefits from better security when the certificates remains temporary revoked on the CA as long as the user, for example, retracts the temporary revocation on his certificate(s). This triggers a new communication to the CA right after the P10-Request.

On each application which requests a certificate, you could add a flag to indicate temporary revocation:

Define like this in the encoding description:

Code Block
[Application_A]
CertTempl=MyCertificateTemplateName
RevokeOnIssue=true
RevocationReason=certificateHold

Description of the elements:

Element

Description

RevokeOnIssue=true

Triggers the temporary revocation directly in InvokeCaApplicationCommand right after the P10-Request.

RevocationReason=certificateHold

Sets the revocation reason to "certificateHold". This is also the default if no RevocationReason is set.

Create external card serial number and reuse value (CM)

Return card serial number from CM

Nexus Certificate Manager (CM) supports the token procedure type Smart Card. This token procedure type is used to describe various certificates on one type of smart card. When such a card is personalized, CM creates a unique card serial number. 

Define like this in the encoding description to let CM create the CM card serial number and return the value:

Code Block
[Fields]
CM_CARD_NUMBER=
...
[Application_A]
CertTempl=AuthCertificate
CardSerialNumberReturnField=CM_CARD_NUMBER

Description of the elements:

Element

Description

CardSerialNumberReturnField=...

Point it to a field.

Map the field in CardSerialNumberReturnField to the ${carddatapool_cardnumber} (or to generally any other process variable) and activate the 'read' option. In the example above the cardnumber value would be read from CM_CARD_NUMBER_RETURN_FIELD.

Specify card serial number

When requesting a certificate for an existing card, for example, in a second, third... application, you use the CardSerialNumberField and point it to a field containing the card serial number. In the following example, Application_A generates the card serial number and reuses the value in the second application to make sure, that the certificate is created on the same card as the previous certificate from Application_A.

Define like this in the encoding description:

Code Block
[Fields]
CM_CARD_NUMBER=
...
[Application_A]
CertTempl=AuthCertificate
CardSerialNumberReturnField=CM_CARD_NUMBER
 
[Application_B]
CertTempl=NonRepCertificate
CardSerialNumberField=CM_CARD_NUMBER

Description of the elements:

Elements

Description

CardSerialNumberReturnField=...

Point it to a field.

CardSerialNumberField=...

Point it to a field.

Add KeyUsage to specify the corresponding certificate

As a smartcard token procedure contains multiple certificates, we eventually need to specify the Key usage of the according certificate. This is done using the KeyUsage key in the description file. It corresponds to the key usage value(s) in the CM definition.

Define like this in the encoding description:

Code Block
[Application_A]
CertTempl=AuthenticationCertificateSC
CardSerialNumberReturnField=CM_CARD_NUMBER
KeyUsage=DigitalSignature,KeyEncipherment
...
 
[Application_B]
CertTempl=NonRepudiationCertificateSC
CardSerialNumberField=CM_CARD_NUMBER
KeyUsage=NonRepudiation
...

Note: KeyUsage attribute is ignored in the key archiving process.

Required configuration in Identity Manager Admin

The card serial number encoding field (named CM_CARD_NUMBER in the examples above) acts as output and input field for Identity Manager's encoding component.

It is required:

  • to map this field in the encoding mappings of the encoding description configuration to a Identity Manager variable or database field using an appropriate JUEL expression and

  • to set the Read flag for this field mapping.

Plain-text request

Plain-text requests are relevant, when:

  • Personal Desktop Client is used and

  • the used card profile does not allow to access the private key to sign the request.

Usually, the JPKI-Encoder creates a PKCS10 request that is sent to the server. But in special cases, a plain text request is required. Such profiles are used when customer's processes define, that the certificate/keypair is only activated in the field (by a separate mechanism). Note that the plain text request also requires a CM Token Procedure of type "Smart card". You cannot use the type "PKCS10" and "PKCS12" for this request. To turn on the plain text request, SendPlainTextRequest must be set to true. Regarding the data which is technically sent, see also the actual REST call content behind.

Note

Key archiving does not make sense if there is no private key. The default (and only reasonable) option for KeyArchivalRequest in a plain-text request is false. Keep in mind to use the plain-text requests only if the PKCS10 can not be created. And it's only implemented for Nexus Certificate Manager

Define like this in the encoding description:
In the following example, all the certificate related fields (subject/distinguished name fields and subject alternative nameskeysizekeyusage, the existing publickey and if keyarchival is requested), will be sent as parameters to the server.

Code Block
[Application_A]
UseExistingKeyPair=1
ObjectCriteria=CKO_PUBLIC_KEY,CKA_LABEL,string,"Non Repudiation"
KeySize=2048
KeyUsage=NonRepudiation
SendPlainTextRequest=true
...

Description of the elements:

Element

Description

SendPlainTextRequest=true

Triggers the use case.

For certain cards that contain pre-generated keys with CKA_ID, it may be required to set this as well, to read the existing ID instead of trying to generate it from the public key's modulus:

Code Block
ReadExistingPublicKeyId=true

Key archival

Certificate and key pair are generated on the server and the card is written on the client. When using CardOS middleware, Secure Key Injection (SKI) is supported to transport the private key from the server to the smart card.

Key archival without Secure Key Injection

In the non SKI case, normal PKCS#12 file data is transferred from server to client instead of encrypted key pair.

Define like this in the encoding description:

Code Block
[Fields]
P12PASSWORD_A=
P12PASSWORD_B=
P12CERTIFICATE_A=
P12CERTIFICATE_B=
...

Encoding Description details:

Code Block
[Description]
...
Applicationlist=AB
ClearFields= P12PASSWORD_A,P12Certificate_A,P12PASSWORD_B,P12Certificate_B, ...
 
[Application_A]
KeyArchivalRequest=true
WriteP12Data=true
Certificate=P12Certificate_A
P12PASSWORD=P12PASSWORD_A
CertTempl=PFXEncryptionCert
 
[Application_B]
KeyArchivalRequest=true
WriteP12Data=true
Certificate=P12Certificate_B
P12PASSWORD=P12PASSWORD_B
CertTempl=PFXEncryptionCert

Description of the elements:

Element

Description

KeyArchivalRequest=true

Triggers the KeyArchivalRequestPreProcessor which executes the KeyArchival request at the CA.

WriteP12Data=true

Triggers the WriteP12KeyStoreApplicationCommand which writes P12 certificates to a token/smartcard.

Note: This flag is ignored for integrated CA connectors (they get their P12 data via a different mechanism: the client requests the application by ID from the integrated CA connector and receives the P12 data or SKI-encrypted key-pair in the response).

Certificate=P12Certificate_A

Mapping for the KeyArchival certificate returned by the server side KeyArchival request at the CA. This is ignored for integrated CA connectors (see above).

P12PASSWORD=P12PASSWORD_A

The P12 password used for the KeyArchival request. It is mandatory to set a P12PASSWORD for the KeyArchivalRequest.

CertTempl=...

Defines a certificate template name for the KeyArchival request at the CA.

ClearFields=...

Remember to set ClearFields=... otherwise the P12 container and the P12 password will be written into the database, or might be written to log file (which is often not wished!) when returning the fields after the encoding is done.

The Result of a P12 request will be stored as base64 encoded value for the requesting application like:

Code Block
P12CERTIFICATE_A=MIIDLjCCAhYCAQAwEDEOMAwGA1UEAwwFbmV4dXMwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCvVjkiOMMjeWH/yBlwsuyo6N2mHzFk5ebegtY95meGCjET...

Key archival with Secure Key Injection

Encrypted key pair is transferred from server to client. Secure Key Injection (SKI) will only be supported by CardOS 5.4W14 or later middleware with MiniDriver and CardOS card should be 5.3 or higher.

Prerequisites

  • The CardOS middleware must be installed on the Identity Manager server

  • Set EnableSKI=true in the encoding description to activate SKI.

Define like this in the encoding description (in addition to the definition for nonSKI):

Code Block
[Fields]
.....
Thumbprint=
...
 
[Application_A]
EnableSKI=true
 

Additional description fields:

Code Block
[Description]
...
CardOSSkiThumbprintField=Thumbprint
...
 
[Application_A]
......
ForceSKI=true

Description of the elements:

Element

Description

EnableSKI=true

Enable SKI process execution. SKI is disabled by default.

CardOSSkiThumbprintField=Thumbprint

Thumbprint will be supplied from Card which was stored earlier. Set the "Read"-attribute in the "Encoding Fields" tab to get the value into your data-Map.

ForceSKI=true

If set to true, Identity Manager will perform SKI key archival forcefully, meaning if middleware/card do not support it, the CA connector endpoints will refuse a non-SKI request. This field is optional. SKI card support is checked at client side via smart card driver api.

The ForceSKI flag has priority over the EnableSKI flag. The ForceSKI flag enables forcefully execution of SKI use cases even though the EnableSKI flag is not provided. Here are some use cases:

ForceSKI

EnableSKI

Selected process

true

false

SKI

true

true

SKI

false

true

SKI

false

false

Non SKI

Repackage PKCS#12 file right after KeyArchival request

To support renaming of the friendly name according to a configurable pattern (also with case-sensitivity) and for renaming friendly names of the CA certificates (intermediates and the root) according to the same pattern, inject this PKCS#12 Repackager mechanism into the KeyArchivalRequestPreProcessor:

Code Block
<bean id="keyArchivalRequestPreProcessor" class="de.vps.act.action.softtoken.KeyArchivalRequestPreProcessor">
    ...
    <property name="pkcs12Repackager" ref="keyStoreRepackager"/>
</bean>
 
<bean id="keyStoreRepackager" class="de.vps.act.action.softtoken.PKCS12Repackager">
    <property name="friendlyNameNamingStrategy" ref="genericNamingStrategy" />
</bean>
 
<bean id="genericNamingStrategy" class="de.vps.act.action.softtoken.GenericNamingStrategy">
    <property name="juelExpressionResolver" ref="juelExpressionResolver" />
    <!-- use _!CERT_SERIAL_NUM to configure the naming with the certificate serial number in place -->
    <property name="naming" value="§{CN} - _!CERT_SERIAL_NUM" />
    <property name="certSerialInHex" value="true" />
    <property name="prefix"><null/></property>
    <property name="suffix"><null/></property>
</bean>

Note the value of "naming" - here "§{CN} - _!CERT_SERIAL_NUM", where you can mix Juel-like expressions (here with "§" (paragraph) which is resolved out of the certificates' DN), free text and a special identifier _!CERT_SERIAL_NUM (that is replaced by the real certificate serial number of the certificate).

With the property "certSerialInHex" as boolean flag, you can change the usage of the certificate serial number in the friendly name by applying it in hexadecimal (true) or decimal (false) notation. Prefix and suffix are free text options to be attached in front of the resolved naming or behind, however, there is no resolving inside the pre- and suffix, just in the "naming" string sequence.

Key recovery

Certificates and corresponding private keys are fetched from from the certificate authority (CA). The requested certificates can be provided either as a list of Core Object IDs or CoreObjectDescriptors via the RecoveryCertificateData attribute of encoding description. Thus the certificates to be recovered can either be looked up via Cert: Load Key History List or Processes: Execute Search Task or any other way that can provide either format. 

Key recovery without Secure Key Injection

Define like this in the encoding description:

Code Block
[Fields]
P12CERTIFICATE_A=
P12PASSWORD_A=
RecoveryCertificateData_A= ...
 
[Application_A]
CertTempl=Recovery
RecoveryTemplate=Recovery
KeyRecoveryRequest=true
Certificate=P12CERTIFICATE_A
P12PASSWORD=P12PASSWORD_A
WriteP12Data=true
RecoveryCertificateData=RecoveryCertificateData_A

Description of the elements:

Element

Description

RecoveryCertificateData

The field holding the certificates to be recovered, either as a list of CoreObjectDescriptors or as a list of Core Object IDs. 

Note

The name of the field must be RecoveryCertificateData_<ApplicationId> as shown in the example.

Info

It is possible - but not recommended - to not map any value to RecoveryCertificateData_<ApplicationId>. In this case, the certificates to be recovered will be taken from the process variable configured in the bean property keyArchivalRequestPreProcessor.coreObjectIDKey (defaults to "Certificate_CoreObjects" but is often overwritten).

Key recovery with Secure Key Injection

This use case is only supported with CardOS 5.4 middleware or later with MiniDriver and CardOS 5.3 cards.

Define like this in the encoding description:

Code Block
[Fields]
P12CERTIFICATE_A=
P12PASSWORD_A=
Thumbprint=
RecoveryCertificateData_A=
 ...
 
[Application_A]
CertTempl=Recovery
RecoveryTemplate=Recovery
KeyRecoveryRequest=true
Certificate=P12CERTIFICATE_A
P12PASSWORD=P12PASSWORD_A
WriteP12Data=true
EnableSKI=true
CardOSSkiThumbPrintField=Thumbprint
RecoveryCertificateData=RecoveryCertificateData_A

Description of the elements:

Element

Description

RecoveryCertificateData

The field holding the certificates to be recovered, either as a list of CoreObjectDescriptors or as a list of Core Object IDs. 

Note

The name of the field must be RecoveryCertificateData_<ApplicationId> as shown in the example.

Info

It is possible - but not recommended - to not map any value to RecoveryCertificateData_<ApplicationId>. In this case, the certificates to be recovered will be taken from the process variable configured in the bean property keyArchivalRequestPreProcessor.coreObjectIDKey (defaults to "Certificate_CoreObjects" but is often overwritten).

CardOSSkiThumbprintField=Thumbprint

Used to read the Card thumbprint value and hold into this field. The card must be initialized and thumbprint value should be available into the card. 

Enforce Secure Key Injection for PKCS#12 requests

Enforce Secure Key Injection for PKCS#12 requests

For applications that require a CA-supplied key-pair to be written to the card, key-pair transfer can be enforced via Secure Key Injection (SKI) to prevent eavesdropping by a malicious client. For SKI to work, the CardOS middleware must also be installed on the Identity Manager server. By default, when SKI is not supported, the client may fall back to a less secure non-SKI request.

Define like this in the encoding description:

Code Block
...
 
[Application_A]
ForceSKI=true
...

If the ForceSKI flag is set, then non-SKI PKCS#12 endpoints of the integrated CA connector will refuse to process the application requested by the client and the CA request will be blocked.

Note

  • integrated CA connectors are required for SKI

  • the client does not supply the ForceSKI flag to the server for this check (the server already knows it), so it cannot be manipulated by a malicious client attempting a downgrade attack

  • this flag of course only makes sense in an SKI-enabled setup with integrated CA connector, the proper cards, middleware (currently only CardOS 5.4+), etc.

Key pair generation and discovery

Generate key pair

To explicitly generate a key pair, trigger it in an application part of the encoding description.

Define like this in the encoding description:

Code Block
[Fields]
SIGN_PUBKEY=
...
 
[Application_A]
GenerateKeyPair=true
PubKeyReturnField=SIGN_PUBKEY
...

Description of the elements:

Element

Description

GenerateKeyPair=true

Triggers the key pair generation.

PubKeyReturnField=...

Defines the field in which to store the generated public key. You must also define the field in the Fields section.

Discover generated key pair

When you re-use already generated key pairs on the smartcard, you can search such a key pair to place a certificate to it. This is especially done for signature- and authentication certificates in the context of Nexus Personal Desktop, which creates 2 such key pairs on initialization of the smartcard with a special card profile. A key pair can be searched by an object criteria specifying the following 4 parameters:

  • The constant of objects type to be found, for example, CKO_PUBLIC_KEY

  • The constant of attribute type to be found, for example, CKA_LABEL

  • The type of attribute to be found, for example, string

  • The value of the attribute to be found, for example, a label name

Define like this in the encoding description:

Code Block
[Fields]
SIGN_PUBKEY=
...
 
[Application_A]
UseExistingKeyPair=1
ObjectCriteria=CKO_PUBLIC_KEY,CKA_LABEL,string,'My Sig Key'
PubKeyReturnField=SIGN_PUBKEY

Description of the elements:

Element

Description

UseExistingKeyPair=1

Triggers the key pair discovery.

PubKeyReturnField=...

Defines the field in which to store the discovered public key. You must also define the field in the Fields section.

ObjectCriteria=...

See the description above concerning the 4 parameters. Note! Use single quotes (not double quotes) to enclose the value of the attribute.

Skip writing CA certificates

If you would like to just write user certificates without intermediate certificates and without a root certificate to the smartcard, you can add an encoding property to your certificte application:

Define like this in the encoding description:

Code Block
[Application_A]
StoreUserCertOnly=true
...

Description of the elements:

Element

Description

StoreUserCertOnly=true

Triggers writing only user certificates without intermediate certificates and without a root certificate.

Note

The StoreUserCertOnly option may be used only inside an application that writes a certificate (e.g. defining CertTempl=xyz).

Object labels

The label (CKA_LABEL value) for certificates, public and private keys using the default template, is generated using the CN from the DN followed by a white space and a two digit counter that starts by 01. The CN is limited to 36 characters. Doing so, the complete value is never longer than 39 characters. The reason for that is that CSPs in Windows have issues with longer values.

For example: Max Mustermann 01

Applying these values, each certificate and key pair bundle carries a unique name. However, the generation of the label can be configured using the keys Description/labelCounter and Application_X/LabelTemplate.

LabelCounter is the start value for the global counter.

LabelTemplate is the template that instructs the generation of the label. It has following syntax: LabelTemplate=[<labelAttr>=<value>],[<labelAttr>=<value>],…

Note

The LabelTemplate option may be used only inside an application that writes a certificate (e.g. defining CertTempl=xyz).

Valid values for labelAttr:

Element

Description

name

The CN from the certificate’s DN. A value is not used. If the CN is empty, it uses the DN’s email, or if that is empty, it uses the OU.

limitedName=<n characters>

The same description as name, but limited to the length of n characters.

snr

The SERIALNUMBER from the certificate’s DN.

cert_snr

The serialnumber from the certificate itself

blank=<n>

Inserts n white spaces

certcounter=<start value>

Defines a two digit global counter value that is incremented with each certificate. Default value is 10. However, the value is not used directly. When an encoding process is started, the count of possible available certificates on the card is retrieved. Then, this counter value is added.

keyUsageDigSig=<text>

Defines the value that is used when the certificate’s key usage digital signature is set.

keyUsageNotDataEnc=<text>

Defines the value that is used when the certificate’s key usage data encipherment is not set.

keyUsageDataEnc=<text>

Defines the value that is used when the certificate’s key usage data encipherment is set

fixtext=<text>

Defines a fix string

complete-dn

Defines the encoding of the complete DN

notbefore

Defines the valid from date in ISO format (2019-01-15)

notafter

Defines the valid to date in ISO format (2019-12-30)

applicationCertCounter=<start value>

Defines a counter value that is incremented with each main certificate that is handled within a single application section of the encoding description.

Example: During a recovery of several certificates the counter will be incremented for every recovered certificate, but not for any certificate in the respective chain. 

Note

You can also specify LabelTemplate=skip which will instruct IDM not to set any label attribute. This is required e.g. for certain TCOS cards.

Corresponding to this definition, the default label template is

labeltemplate=limitedname=36,blank=1,certcounter

The content of the every type of LabelTemplate can also be concatenated using the fields in the Fields section of the encoding description, using an expression language based on the exclamation mark. See https://docs.spring.io/spring-framework/reference/core/expressions.html for details. Examples:

Code Block
// Just provide the whole via a field:
LabelTemplate=!{FIELD_NAME} 
// Or concatenate different parts:
LabelTemplate=fixtext=!{FIELD_NAME}
// The language has a sophisticated syntax and tuff like this also work:
LabelTemplate=fix!{'text=Bla,snr'} // -> fixtext=Bla,snr -> Bla123B4
// Or really complex stuff:
LabelTemplate=fixtext=!{MODEL.contains('4') ? 'EF.C.ICC.EX' + CERT_INDEX + '.RSA : 'Ex. Certificate ' + CERT_INDEX}

Define like this in the encoding description:

Code Block
[Application_X]
LabelTemplate=<A template as described above. This is for the actual user certificate>
LabelTemplateCertRoot=<The template string for root certificates. This applies for all  certificates being written by the corresponding application>
LabelTemplateCertIntermediate=<The template string for intermediate certificates. This applies for all certificates being written by the corresponding application>
PrivateKeyLabelTemplate=<The template string for private keys. This applies for all private being written by the corresponding application if supported. See below.> 
PublicKeyLabelTemplate=<The template string for public keys. This applies for all public being written by the corresponding application if supported. See below.>
Note

PrivateKeyLabelTemplate is not supported for the Idopte middleware with secure channel support. 

Note

PublicKeyLabelTemplate is not supported for middlewares, that don't manage an explicit public key object. This includes CryptoVision, Personal Desktop Classic, Atos CardAPI, Idopte middle.

Define the attribute set (PKCS#11 template)

Template

When an object (certificate, public or private key) on the card is stored or created, it contains a set of attributes as defined by the PKCS#11 standard. The PKCS#11 standard typically names this set as template. For our use cases, templates are used for:

  • storing a certificate (using a certificate template),

  • storing a private key (using a private key template),

  • creating a key pair (using a private key and public key template).

The set of attributes are basically "hard coded" by the JPKIEncoder. However, the attribute sets can be varied by the corresponding description file entry. Using such an entry,

  • may change the value of the corresponding attribute,

  • may extend the default list of attributes inclusive defining their values.

Template for storing a certificate

Attribute

Value

CKA_TOKEN

CK_TRUE

CKA_CERTIFICATE_TYPE

CKC_X_509

CKA_CLASS

CKO_CERTIFICATE

CKA_VALUE

DER encoded certificate

CKA_ISSUER

DER encoded issuer from the certificate

CKA_SERIAL_NUMBER

DER encoded serial from the certificate

CKA_SUBJECT

DER encoded subject from the certificate

CKA_ID

See "Notes for CKA_ID" below

CKA_LABEL


Template for storing a private key

Attribute

Value

CKA_CLASS

CKO_PRIVATE_KEY

CKA_TOKEN

CK_TRUE

CKA_ID

See "Notes for CKA_ID" below

CKA_MODULUS

CKA_PRIVATE_EXPONENT

CKA_PRIVATE

CK_TRUE

CKA_LABEL

CKA_MODIFIABLE

CK_TRUE

CKA_KEY_TYPE

CKK_RSA

CKA_PUBLIC_EXPONENT

CKA_PRIME_1

CKA_PRIME_2

CKA_EXPONENT_1

CKA_EXPONENT_2

CKA_COEFFICIENT

CKA_SUBJECT

DER encoded subject from the certificate

CKA_DERIVE

CK_FALSE

CKA_DECRYPT

CK_TRUE

CKA_SIGN

CK_TRUE

CKA_UNWRAP

CK_TRUE

Template for generating a private key

Attribute

Value

CKA_CLASS

CKO_CERTIFICATE

CKA_TOKEN

CK_TRUE

CKA_ID

See "Notes for CKA_ID" below

CKA_SUBJECT

DER encoded subject from the certificate

CKA_ISSUER

DER encoded issuer from the certificate

CKA_SERIAL_NUMBER

DER encoded serial from the certificate

CKA_LABEL

CKA_VALUE

DER encoded certificate

CKA_CERTIFICATE_TYPE

CKC_X_509


Template for generating a public key

Attribute

Value

CKA_CLASS

CKO_PRIVATE_KEY

CKA_TOKEN

CK_TRUE

CKA_ID

See "Notes for CKA_ID" below

CKA_MODULUS

CKA_PRIVATE_EXPONENT

CKA_PRIVATE

CK_TRUE

CKA_LABEL

CKA_MODIFIABLE

CK_TRUE

CKA_KEY_TYPE

CKK_RSA

CKA_PUBLIC_EXPONENT

CKA_PRIME_1

CKA_PRIME_2

CKA_EXPONENT_1

CKA_EXPONENT_2

CKA_COEFFICIENT

CKA_SUBJECT

DER encoded subject from the certificate

CKA_DERIVE

CK_FALSE

CKA_DECRYPT

CK_TRUE

CKA_SIGN

CK_TRUE

CKA_UNWRAP

CK_TRUE

Notes for CKA_ID

The CKA_ID establishes the link between certificate, private and public key.

Variant 1: It is stored as twenty bytes long value, generated from the public key’s modulus using the SHA-1 hash algorithm.

Variant 2: Alternatively, the SubjectKeyIdentifier of the object bundle is used, when this field is contained in the corresponding certificate of the object bunch. The SubjectKeyIdentifier is then stored in its DER encoded form.

Example for variant 2:

A certificates' SubjectKeyIdentifier is defined in the x509 extensions section, as seen in this image:

...

  • This SubjectKeyIdentifier is then taken for CKA_ID generation with the following generation rules:

    1. Byte is an encoding identifier. Generally DER encoding is preferred, represented by the byte sequence 04h.

    2. Byte is the length of the SubjectKeyIdentifier (here 6 bytes, therefore 06h).

    3. The following Bytes are the SubjectKeyIdentifier bytes.

  • The resulting CKA_ID (8 bytes length) then is: 0406014B2ADD5F66 (=example)

Apply extra attributes
To change the default sets used by the JPKIEncoder, define like this in the encoding description:

Code Block
[Application_A]
WiteCertificate=TRUE
AttributesCert=CKA_PRIVATE=FALSE,CKA_MODIFIABLE=TRUE,...
 
[Application_B]
CreateKeyPair=TRUE
AttributesPubKey=CKA_MODIFIABLE=TRUE,CKA_DERIVE=FALSE,...
AttributesPrvKey=CKA_MODIFIABLE=TRUE,CKA_DERIVE=FALSE,...
 
[Application_C]
WriteP12Data=true
AttributesCert=CKA_PRIVATE=FALSE,CKA_MODIFIABLE=TRUE,...
AttributesPubKey=CKA_MODIFIABLE=TRUE,CKA_DERIVE=FALSE,...
AttributesPrvKey=CKA_MODIFIABLE=TRUE,CKA_DERIVE=FALSE,...

Description of the elements:

Element

Description

AttributesCert=...

Contains comma separated lists of [Attribute]=[Value] pairs which are used when the object is written or created. When specified using one of these three attributes, it may either overwrite the above named default value or add this value to the template.

AttributesPubKey=...

~

AttributesPrvKey=...

~

These attributes are supported to be overwritten or added to the JPKIEncoder’s default templates:

Attribute

Data type

Value (as appearing in the dsc file

CKA_DERIVE

CK_BBOOL

TRUE | FALSE

CKA_LOCAL

CK_BBOOL

TRUE | FALSE

CKA_MODIFIABLE

CK_BBOOL

TRUE | FALSE

CKA_ENCRYPT

CK_BBOOL

TRUE | FALSE

CKA_VERIFY

CK_BBOOL

TRUE | FALSE

CKA_VERIFY_RECOVER

CK_BBOOL

TRUE | FALSE

CKA_WRAP

CK_BBOOL

TRUE | FALSE

CKA_TRUSTED

CK_BBOOL

TRUE | FALSE

CKA_SENSITIVE

CK_BBOOL

TRUE | FALSE

CKA_DECRYPT

CK_BBOOL

TRUE | FALSE

CKA_SIGN

CK_BBOOL

TRUE | FALSE

CKA_SIGN_RECOVER

CK_BBOOL

TRUE | FALSE

CKA_UNWRAP

CK_BBOOL

TRUE | FALSE

CKA_EXTRACTABLE

CK_BBOOL

TRUE | FALSE

CKA_ALWAYS_SENSITIVE

CK_BBOOL

TRUE | FALSE

CKA_NEVER_EXTRACTABLE

CK_BBOOL

TRUE | FALSE

CKA_PRIVATE

CK_BBOOL

TRUE | FALSE

Optional attributes

Similar to the definition of extra attributes, the encoding description allows the definition of optional attributes (which is, however, a JPKIEncoder internal name for the way to consider these attributes). The general meaning of this feature is also minor, see the remarks below.

The mechanism to apply optional attributes, works like this:

  • A Smartcard object (certificate, public key, private key) is created on the card. It then owns some attributes as described above in the section for standard and default attributes.

  • When optional attributes are defined in the description file, the JPKIEncoder checks if such an attribute exists and if it has a different value from the requested one. If so, it updates the existing value.

The mechanism basically exists to support various middleware with various support of such attributes - without having knowledge how far a middleware uses such attributes.

Define the optional attributes like this in the encoding description:

Code Block
[Description]
AttributesCertRootOpt=CKA_START_DATE,CKA_END_DATE...
AttributesCertIntermediateOpt=CKA_START_DATE,CKA_END_DATE...
 
[Application_A]
WiteCertificate=TRUE
AttributesCertOpt=CKA_START_DATE,CKA_END_DATE,...
 
[Application_B]
CreateKeyPair=TRUE
AttributesCertOpt=CKA_START_DATE,CKA_END_DATE,...
AttributesPubKeyOpt=CKA_TRUSTED=FALSE,...
AttributesPrvKeyOpt=CKA_WRAP_WITH_TRUSTED=FALSE,...
 
[Application_C]
WriteP12Data=TRUE
AttributesCertOpt=CKA_START_DATE,CKA_END_DATE,...
AttributesPubKeyOpt=CKA_TRUSTED=FALSE,...
AttributesPrvKeyOpt=CKA_WRAP_WITH_TRUSTED=FALSE,...

Description of the elements

The examples above demonstrate the usage of optional attributes for allowed use cases. Please note the specialty of the separate and global attribute definition for root and intermediate certificates. Attributes for user certificates are always taken from the corresponding Application_X section, but if an Application_X defined use case provides root or intermediate certificates, their definition is taken from the global Description section. The table describes all allowed attributes that may be used as optional attributes. The actual usage of an attribute depends on the corresponding object and use case.

Attributes of type CK_BBOOL and CK_ULONG require a corresponding value in the encoding description. CK_DATE and Byte array values are implicitly generated from the related certificate and do not require a value. That means, the different kind of attributes are defined like this:

AttributesCertOpt=CKA_ALWAYS_AUTHENTICATE=TRUE,CKA_CERTIFICATE_CATEGORY=1,CKA_START_DATE,CKA_HASH_OF_SUBJECT_PUBLIC_KEY

 

Attribute

Data type

Value (as appearing in the dsc file)

CKA_DERIVE

CK_BBOOL

TRUE | FALSE

CKA_LOCAL

CK_BBOOL

TRUE | FALSE

CKA_MODIFIABLE

CK_BBOOL

TRUE | FALSE

CKA_ENCRYPT

CK_BBOOL

TRUE | FALSE

CKA_VERIFY

CK_BBOOL

TRUE | FALSE

CKA_VERIFY_RECOVER

CK_BBOOL

TRUE | FALSE

CKA_WRAP

CK_BBOOL

TRUE | FALSE

CKA_TRUSTED

CK_BBOOL

TRUE | FALSE

CKA_SENSITIVE

CK_BBOOL

TRUE | FALSE

CKA_DECRYPT

CK_BBOOL

TRUE | FALSE

CKA_SIGN

CK_BBOOL

TRUE | FALSE

CKA_SIGN_RECOVER

CK_BBOOL

TRUE | FALSE

CKA_UNWRAP

CK_BBOOL

TRUE | FALSE

CKA_EXTRACTABLE

CK_BBOOL

TRUE | FALSE

CKA_ALWAYS_SENSITIVE

CK_BBOOL

TRUE | FALSE

CKA_NEVER_EXTRACTABLE

CK_BBOOL

TRUE | FALSE

CKA_PRIVATE

CK_BBOOL

TRUE | FALSE

CKA_TRUSTED

CK_BBOOL

TRUE | FALSE

CKA_WRAP_WITH_TRUSTED

CK_BBOOL

TRUE | FALSE

CKA_ALWAYS_AUTHENTICATE

CK_BBOOL

TRUE | FALSE

CKA_CERTIFICATE_CATEGORY

CK_ULONG

Categorization of the

certificate: 0 = unspecified (default

value), 1 = token user, 2 =

authority, 3 = other entity

CKA_START_DATE

CK_DATE

Implicit. Start date for the certificate, taken from the certificate that was encoded.

CKA_END_DATE

CK_DATE

Implicit. End date for the certificate, taken from the certificate that was encoded.

CKA_HASH_OF_SUBJECT_PUBLIC_KEY

Byte array

Implicit. SHA-1 hash of the subject public key, automatically calculated from the certificate that was encoded.

CKA_HASH_OF_ISSUER_PUBLIC_KEY

Byte array

Implicit. SHA-1 hash of the issuer public key, automatically calculated from the certificate that was encoded.

CKA_CHECK_VALUE

Byte array

Implicit. First  three  bytes  of  the  SHA-1  hash  of  the  certificate’s attribute CKA_VALUE, automatically calculated from the certificate that was encoded

Transport certificates

Example of transport certificate

Transport certificates (TC) are a Nexus Personal Desktop feature for cards that are pre-personalized with keypairs. The purpose of a transport certificate is to guarantee the originator of the pre-personalized card, to avoid that other cards, with non-secret private keys, are used when issuing certificates. The public keys on a pre-personalized smart card produced in the Key Generation System (KGS) are normally not signed and therefore not protected against tampering during the transport from the KGS to the Registration Authority (RA) where the cards are personalized. To improve the security of the issuing system, the public key can be embedded in a transport certificate signed by a dedicated "transport CA". When the personalization takes place in the RA, a special token procedure must be selected by the officer. The token procedure must include a special modifier that checks the signature and validity of the transport certificate.

Generally, a certificate requested using a TC will replace the TC on the card. When - in the future - the requested certificate is renewed, the requested certificate will in turn act as a TC.

Identity Manager supports transport certificates. Nexus CM must be used as a CA. If pre-personalized cards with generated keypairs are being used, any transport certificates matching the generated keys will automatically be used. The requested certificate will automatically replace the TC. No further configuration is needed in Identity Manager. The JPKIEncoder Log will indicate whether a transport certificate was found or not.

This is an example of an encoding description:

Code Block
# This encoding can also be used for transport certificates (TC). For this, the card must be prepersonalized with a TC
# and the certificate templates referenced with CertTempl must be configured on the CM to use TC
[Encoding]
Type = 1024,Chip
Devices = 8710
[Fields]
PublicKeyPlain=
PublicKeyP10=
PIN=
[Description]
PKCS11Library = personal.dll
Applicationlist = A
PIN=PIN
 
# Plain request
[Application_A]
CertTempl = EncHardCodedValues
# Currently (190410) UseExistingKeyPair isn't needed
#UseExistingKeyPair=1
ObjectCriteria=CKO_PRIVATE_KEY,CKA_LABEL,string,"Non Repudiation"
KeyUsage=NonRepudiation
SendPlainTextRequest=true
ReadExistingPublicKeyId=true
# Will hold the discovered public key
PubKeyReturnField = PublicKeyPlain
labeltemplate=fixtext=Non Repudiation
 
# PKCS#10 request
[Application_B]
CertTempl = EncHardCodedValuesP10
# Currently (190410) UseExistingKeyPair isn't needed
#UseExistingKeyPair=1
ObjectCriteria=CKO_PRIVATE_KEY,CKA_LABEL,string,"Digital Signature"
KeyUsage=DigitalSignature
ReadExistingPublicKeyId=true
# Will hold the discovered public key
PubKeyReturnField = PublicKeyP10
labeltemplate=fixtext=Digital Signature

Generate card with transport certificate

  1.  Install current version of CM Key Generation System

  2. Install Personal Desktop Client, see Install Personal Desktop Client.

  3. In C:\Program Files (x86)\Nexus\Certificate Manager\Key Generation System\Cardprofiles you can find some CPFs. The ones that end with "Transport" are relevant. Choose one fitting the card you want to use, for example, RaP15Siemens50_2FCa1P_2048_OKG_KAR_Transport.cpf for a CardOS 5.0 ("50" stands for the CardOS version) token, and copy it to some directory. Uncomment the following lines in your copy:

    .cpf

    Code Block
    MakeCardEraseable()
    SEC_OP = '3333333333333333'
    SEC_PUK1 = '123456789012'
    SEC_PIN1 = '11111111'

    and comment out the previous values for SEC_*. Note that the profile for 5.0 cards specifies PIN minlength = 8. Initializing with "132435" will seem to work but you won't be able to log in or change PIN. To be sure, search for "minlength" in the cpf you use.

  4. Some certificates are needed. Example certificates can be found in C:\Program Files (x86)\Nexus\Certificate Manager\Key Generation System\Certificates. Open the Personal GUI > View > Preferences > Electronic Identity Token Search > Browse > open the aforementioned folder > Add.
    You should now see tcsigner in your Nexus Personal GUI, its PIN is 1234 . This will be the the CA for signing the transport certificates.

  5. Edit C:\Program Files (x86)\Nexus\Certificate Manager\Key Generation System\ppa.cfg or %APPDATA%\Nexus\Certificate Manager\Key Generation System\ppa.cf (the latter wins, if it exists), and make the following adjustments:

    ppa.cfg

    Code Block
    [Script]
    File=c:\path\to\your\copy\of\yourEditedTransport.cpf
     
    [PIN Encryption]
    File=C:\Program Files (x86)\Nexus\Certificate Manager\Key Generation System\Certificates\pin.crt
     
    [Transport CA]
    dll-transportca=TransportCa.dll
    dll-pkcs11=C:\Program Files (x86)\Personal\bin\personal.dll
    name=tcsigner
    ; setting cacert=... is optional, but if you do specify it, it has to match the signer specified above
    cacert="C:\Program Files (x86)\Nexus\Certificate Manager\Key Generation System\Certificates\tcsigner.cer"
    pin=1234
    validity=365
     
    [Trace]
    directory=C:\tmp\Personal_Log
  6. Start KGS.

  7. Select Target card reader.

  8. Insert an erased card with the OS that fits your CPF.

  9. Click Start.

  10. In case of errors, consult the logfile specified in the [Trace] section.

Configure CM for transport certificates

  1. Copy config\certformats\rfc5280.conf to config\certformats\rfc5280-tc.conf

  2. Edit rfc5280-tc.conf and add transport certificate module after ID2Legacy:

    Code Block
    TransportCertificate = 6
  3. Edit config\tcconfig.conf as you see fit.

  4. Restart CM.

  5. Clone an existing certificate procedure using rfc5280 certificate format and edit it

    • Rename appropriately

    • Set Certificate Format to rfc5280-tc (the one you just created)

  6. Clone a token procedure that uses the certificate procedure you just cloned and edit it

    • Rename appropriatelly

    • Set Certificate Procedure to the one you just created

    • Set Storage Profile to PKCS10

  7. Further information can be found here:

Use elliptic curves cryptography

The type of the created keys is coded into the KeySize property. The value is 'ECC/' plus a curve name. Supported curves are limited by Bouncy Castle, the PKCS#11 middleware and the certificate authority. For details, refer to the respective documentation. The PKCS10SigningAlgorithm needs to be specified when using elliptic curves cryptography.

  • PRIME 3.9: Elliptic curves is only supported for Cryptovision and Nexus Certificate Manager. Other middlewares are guaranteed to NOT work, while other CA connectors are not tested.

  • PRIME 3.10: Support is added for TCOS cards with ECC. Note that those only support SHA1_ECDSA as PKCS10SigningAlgorithm, SHA2-variants do not work.

  • PRIME 3.11: Support is added for EJBCA.

Define like this in the encoding description:

Code Block
[Application_A]
CertTempl=SigCert
KeySize=ECC/prime256v1
PKCS10SigningAlgorithm=SHA256_ECDSA
 
[Application_B]
CertTempl=AuthCert
KeySize=ECC/brainpoolP256r1
PKCS10SigningAlgorithm=SHA256_ECDSA