Nexus' software components have new names:

Nexus PRIME -> Smart ID Identity Manager
Nexus Certificate Manager -> Smart ID Certificate Manager
Nexus Hybrid Access Gateway -> Smart ID Digital Access component
Nexus Personal -> Smart ID clients

Go to Nexus homepage for overviews of Nexus' solutions, customer cases, news and more.


An encoding description contains the information for the electronic personalization of a card. You import the encoding description from a file. This can be used in Smart ID Identity Manager.

This article includes information about the T-Systems TCOS middleware and cards as supported by Identity Manager and describes how you create descriptions for them.


Expand/Collapse All

About TCOS DLLs

TCOS P11 Dynamic Link Libraries (DLLs) come in three different flavors:

  • NetKey version (basic P11 library for NKS application)
  • SigG version (for qualified digital signatures, if the card in question supports it via an additional SigG application - not officially supported by Identity Manager)
  • ELSTER version (for the German tax reporting system - not officially supported by Identity Manager)

The DLL you load gives you a view of a specific subset of the card. For example, with the SigG DLL you would only see the PINs/keys/certs of the SigG application. Thus make sure you always load the DLL of the appropriate type.

Make sure that you use the latest version of the P11 middleware. The documents and software available at https://www.telesec.de/de/tcos/support/downloadbereich may sometimes be outdated, especially the P11 DLLs (for those check the file versions, not the publishing date!).

Also note that the filename of the 32-bit version varies slightly between versions (newer releases added the suffix "32").

  • Middleware version 1.8.3.1 or 1.8.3.2 is required (1.8.3.2 recommended)

PIN/PUK/CR-Key

The following are always present:

  • Pin 1 (mapped to USER pin in P11, uninitialized by default, 6-24 chars)
  • Pin 2 (mapped to SO pin aka PUK in P11, blocked by default, 8-24 chars)

This one is present on some cards:

  • Challenge/Response key (3DES key, not yet implemented in IDM for TCOS)

Unblocking can be done via the following (not fully supported in Identity Manager):

  • Pin 1 can unblock Pin 2 and vice-versa
  • CR-Key can unblock Pin 1 (not yet implemented in IDM)

Supported cards

Refer to the lists of public key and certificate labels for each card when needed in the encoding description.

  • NKS application has 3 ECC keypairs with 2 certificate slots each.
    • Public key labels (use for searching the existing key)
      • Public Authentication Key ECC
      • Public Encryption Key ECC
      • Public Signature Key ECC
    • User Cert labels
      • ECC Authentication Certificate (pre-loaded cert exists initially)
      • ECC Reserve Authentication Certificate (missing initially)
      • ECC Encryption Certificate (pre-loaded cert exists initially)
      • ECC Reserve Encryption Certificate (missing initially)
      • ECC Signature Certificate (pre-loaded cert exists initially)
      • ECC Reserve Signature Certificate (missing initially)
  • CA Cert Labels
    • EF.C.CSP.SCA1 (pre-loaded intermediate CA cert exists initially)
    • EF.C.CSP.RCA1 (pre-loaded root CA cert exists initially)
  • SigG application has 1 ECC key (not officially supported by Identity Manager)
  • 6 fixed, pre-existing RSA keypairs with one certificate slot each
    • Public key labels (use for searching the existing key)
      • MSCP Public Encryption Key 1
      • ...
      • MSCP Public Encryption Key 6
    • Certificate labels (use for deleting existing certificates)
      • MSCP Encryption Certificate 1
      • ...
      • MSCP Encryption Certificate 6
  • 10 slots for RSA key/certificate import
    • Certificate labels (use for deleting existing certificates and associated keys)
      • Ext. Certificate 1
      • ...
      • Ext. Certificate 10

Feature support

(tick) - supported by Identity Manager

(error) - not supported by Identity Manager, card/P11 feature might be present or planned

n/a - not available on card/P11 lib and not possible or planned

FeatureSignature Card V2.0 (ECC)IDKey 1.0 (RSA)
P10 request for pre-loaded RSA keysn/a(tick)
P10 request for pre-loaded ECC sig/auth keys(tick) The CA connector needs to support ECC.n/a
P10 request for pre-loaded ECC enc key

(tick) The connector needs to support ECC.

  • Will not work with CAs that verify the proof-of-possession on the P10 request.
  • Requires SignP10WithDummyKey=true in the application.
n/a
Plain request (including key archival)(error) Key import is not supported.
(tick) Up to 10 keypairs with associated certificate can be imported.
Generate key on card(error) Not tested, can just redirect to matching pre-loaded key.(error) see Signature Card V2.0
Init PIN and PUK via InitToken(tick)(tick)
Delete existing certs by label

(tick)

(tick)
Profile init via InitTokenn/an/a
Profile reset(error) Not supported via P11 or the Telesec CardManager.(error) see Signature Card V2.0
Change PIN/PUK with old one(tick)(tick)
Unblock PIN with PUK(tick)(tick)
Unblock PUK with PIN(error) Not implemented for consistency with other cards.(error) see Signature Card V2.0
Unblock PIN with CardManagerKeyn/a(error) not implemented
Change CardManagerKey with old onen/a(error) not implemented
Store cert chain or other arbitrary CA certs

(error)/(tick) Cert chain writing within P10 request is not supported, thus StoreUserCertOnly=true is mandatory.

However, up to two CA certificates (root+intermediate) may be written separately.

(error) StoreUserCertOnly=true is mandatory.
Change attributes on existing keys/certsn/a as C_SetAttributeValue just returns CKR_OK without making any changes.n/a see Signature Card V2.0
Support NetKey P11 library(tick)(tick)
Support SigG P11 library (for qualified signatures)(error) Not tested except for PIN/PUK handling.(error) see Signature Card V2.0
Support ELSTER P11 library (DE tax reporting)(error) Not tested(error) see Signature Card V2.0

Encoding description settings

For NetKey middleware on Windows, you can use the following (assuming installation in C:\Windows\System32 and C:\Windows\SysWOW64, respectively):

  1. Define like this in the encoding description:

    ...
    [Description]
    PKCS11LibraryWindows64=P11TCOS3NetKey64.dll
    PKCS11LibraryWindows32=P11TCOS3NetKey32.dll
    ...

The cards are pre-initialized, and the initToken=true flag is used to trigger initialization of Pin 1 (PIN) and subsequent unblocking of Pin 2 (PUK). Note that both PIN and InitialPUK have to be set.

  1. Define like this in the encoding description:

    ...
    [Fields]
    PIN=
    PUK=
    ...
     
    [Description]
    InitToken=true
    PIN=PIN
    InitialPUK=PUK
    ...

Any certificates on the card which you want to replace have to be deleted first. You can also discard any superfluous certificates this way.

For certificates created for a pre-loaded key you have to set DeleteCertsOnly=true, as the keypair itself cannot be deleted for such a certificate.
When deleting certificates that belong to an imported keypair, you have to set DeleteCertsOnly=false (default), to make sure the associated keys are also removed.

For performance reasons it is recommended to use a single application for all certificates to be deleted.

  1. Define like this in the encoding description:

    ...
    
    [Application_X]
    # deleting only certs for pre-loaded keys
    DeleteCertKeyObjects=true
    DeleteCertsOnly=true
    DeleteCertKeyObjectsCriteria=Label(MSCP Encryption Certificate 1,MSCP Encryption Certificate 2,MSCP Encryption Certificate 3)
    
    [Application_Y]
    # deleting also the keys for imported ones
    DeleteCertKeyObjects=true
    DeleteCertsOnly=false
    DeleteCertKeyObjectsCriteria=Label(Ext Certificate 1,Ext Certificate 2)
    ...

This feature is available on Signature Card V2.0 only!

Any certificates on the card which you want to replace have to be deleted first. See Delete certificates above.

Write new CA certificates

You can write up to two CA certificates by specifying the target label.

The label parameter depends on whether the certificate to be written is a root or intermediate certificate.

  1. Define like this in the encoding description:

    ...
    [Application_X]
    WriteCertificate=true
    Certificate=INTERMEDIATE_CA_CERT_FIELD
    LabelTemplateCertIntermediate=fixtext=EF.C.CSP.SCA1
    ...
    [Application_Y]
    WriteCertificate=true
    Certificate=ROOT_CA_CERT_FIELD
    LabelTemplateCertRoot=fixtext=EF.C.CSP.RCA1
    ...


Any certificates on the card which you want to replace have to be deleted first. See Delete certificates above.

General Notes

Certificate chain writing not supported

You have to specify this in your certificate application, as writing a certificate chain supplied in the CA response is not supported (for Signature Card V2.0 see Write CA certificates above for an alternative).

  1. Define like this in the encoding description:

    ...
    [Application_X]
    StoreUserCertOnly=true
    ...

TeleSec Signature Card V2.0

ECC P10 signing

The only supported signing algorithm for Signature Card V2.0 is ECDSA with SHA1.

Even though keys are not generated - existing ones are used - you must specify the KeySize to indicate ECC is to be used. Different variants of the cards use, for example, brainpoolp256r1 or prime256v1 curves.

Identity Manager uses BC curve names.

As a minimum requirement, you have to specify a curve which has the same size (for example, 256 bits) as whatever the card is using, which is required for request validation to work. To future-proof your encodings it is recommended to specify the exact curve.

For cards with different key sizes you need separate applications.

  1. Define like this in the encoding description:

    ...
    [Application_X]
    Pkcs10SigningAlgorithm=SHA1_ECDSA
    KeySize=ECC/prime256v1
    ...

Dummy P10 signing for ECC encryption keys

Unlike ECC sig/auth keys, the ECC encryption keys on a Signature Card V2.0 cannot be used for signing. This is a restriction of the key permissions on the card and cannot be solved by a middleware update. If the CA does not need to verify the P10 signature (for example, CM, DTrust and others where the connector parses the P10), P10 signing can be enabled with a dummy key.

  1. Define like this in the encoding description:

    ...
    [Application_X]
    SignP10WithDummyKey=true
    ...

Select user certificate slot

On a TeleSec Signature Card V2.0 each keypair can have multiple certificate slots, so you need to explicitly define which slot to use by specifying the correct certificate label (unlike above, not key label).

Merely deleting existing certificates for a keypair does not guarantee that the resulting certificate will end up in the main slot.

Note that the Telesec CardManager does not display the correct labels. You have to use a P11 admin tool like https://www.pkcs11admin.net/ to view them.

  1. Define like this in the encoding description:

    ...
    [Application_X]
    LabelTemplate=fixtext=The Certificate Label Goes Here
    ...

IDKey 1.0 Card

Skip Label

When using pre-loaded keypairs it is recommended to skip setting the label attribute via LabelTemplate=skip instead of specifying the actual label via fixtext as shown above, as it is easier to configure and less error-prone.

When importing a keypair and certificate setting the label attribute is not allowed by the middleware, so it is mandatory to skip it.

  1. Define like this in the encoding description:

    ...
    [Application_X]
    LabelTemplate=skip
    ...