Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Minor

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 (PRIME).

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.


Expandall

About TCOS DLLs

Expand
titleTCOS P11 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").


Expand
titleKnown P11 middleware limitations
  • Middleware version 1.8.3.1 or later is required
  • Key import is not possible.

PIN/PUK/CR-Key

Expand
titlePIN/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 supported in Identity Manager 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

Supported cards

Expand
titleTeleSec Signature Card V2.0 (with pre-loaded ECC keys and certs)
  • NKS application has 3 ECC keys 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)

Feature support

Expand
titleFeature support matrix

(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)
P10 request for pre-loaded ECC sig/auth keys(tick) The CA connector needs to support ECC.
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.
Plain request (including key archival)(error) Key import is not yet supported by P11 lib.
Generate key on card(error)Not tested, can just redirect to matching pre-loaded key.
Init PIN and PUK via InitToken(tick)
Delete existing certs by label

(tick)

Profile init via InitTokenn/a
Profile reset(error)Not supported via P11 or the Telesec CardManager.
Change PIN/PUK with old one(tick)
Unblock PIN with PUK(tick)
Unblock PUK with PIN(error)Not implemented for consistency with other cards.
Unblock PIN with CardManagerKeyn/a
Change CardManagerKey with old onen/a
Store cert chain or other arbitrary 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.

Change attributes on existing keys/certsn/a as C_SetAttributeValue just returns CKR_OK without making any changes.
Support NetKey P11 library(tick)
Support SigG P11 library (for qualified signatures)(error) Not tested except for PIN/PUK handling.
Support ELSTER P11 library (DE tax reporting)(error) Not tested


Encoding description settings

Expand
titleSelect middleware

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:

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



Expand
titleInitialize PIN and PUK

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:

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



Expand
titleDelete certificates

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 performance reasons it is recommended to use a single application for all certificates to be deleted.

  1. Define like this in the encoding description:

    Code Block
    ...
    [Application_X]
    DeleteCertKeyObjects=true
    DeleteCertsOnly=true
    DeleteCertKeyObjectsCriteria=Label(First Cert Label Goes Here,Second Cert Label Goes Here,etc.)
    ...



Expand
titleWrite CA certificates


Note

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.

Note

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:

    Code Block
    ...
    [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
    ...



Expand
titleCertificate requests

Only P10 requests are currently possible.

Note

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


ECC P10 signing

The only supported signing algorithm for these cards 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:

    Code Block
    ...
    [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 TCOS cards 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:

    Code Block
    ...
    [Application_X]
    SignP10WithDummyKey=true
    ...


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 (see Write CA certificates above for an alternative).

  1. Define like this in the encoding description:

    Code Block
    ...
    [Application_X]
    StoreUserCertOnly=true
    ...


Select existing key and ID

Since you can only use the existing keys already on the card, you have to select the key by its 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.

Also note that you have to use the existing CKA_ID on the card instead of calculating it from the public key.

  1. Define like this in the encoding description:

    Code Block
    ...
    [Application_X]
    UseExistingKeyPair=true
    ObjectCriteria=CKO_PUBLIC_KEY,CKA_LABEL,string,"The Public Key Label Goes Here"
    ReadExistingPublicKeyID=true
    
    # the line below is for 
    LabelTemplate=fixtext=The Certificate Label Goes Here
    ...

    The middleware does support C_GenerateKey in a way that would return an existing, unused key that matches the parameters, if one exists. However, this approach was not used, as for an existing use-case with TCOS RSA cards, as explicit key selection was employed already.

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 (not key label unlike above).

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:

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