Encoding using T-Systems TCOS middleware in Identity Manager

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

• 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 can only see the PINs/keys/certs of the SigG application. Make sure you always load the DLL of the appropriate type.

Make sure that you use a recommended 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, make sure to verify the file versions and not the publishing date.

Different versions of the middleware may use different DLL filenames.

Use the following middleware versions:

• 1.13.5.0 (supports TCOS4 and TCOS3 cards), requires IDM 22.10 or later
• 1.12.4.0 (supports TCOS4 and TCOS3 cards), requires IDM 22.10 or later
• 1.8.3.2 (supports TCOS3 cards only)

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 (IDKey 1.0, TCOS4):

• Challenge/Response key (3DES key)

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

• 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
  • Public key labels (use for selecting a specific public key target slot)
    • Ext. Public Encryption Key 1
    • ...
    • Ext. Public Encryption Key 10
  • Private key labels (use for selecting a specific private key target slot)
    • Ext. Private Encryption Key 1
    • ...
    • Ext. Private Encryption Key 10
  • Certificate labels (use for selecting a specific certificate target slot / for deleting existing certificates and associated keys)
    • Ext. Certificate 1
    • ...
    • Ext. Certificate 10

Preloaded keys:

• 2x 2048 bit RSA
• 2x 3072 bit RSA
• 6x ECC NIST 256

Import slots:

• 10x 2048 bit RSA
• 6x 3702 bit RSA
• 16x ECC

Label names for on-card keys:

• PuK.ICC.TCn.RSA or PuK.ICC.TCn.ECC
• PrK.ICC.TCn.RSA or PrK.ICC.TCn.ECC
• EF.C.ICC.TCn.RSA or EF.C.ICC.TCn.ECC

(with n of 1-2 being RSA 2048, n of 3-4 being RSA 3072 and 5-10 being ECC)

Label names for imported keys/certs:

• PuK.ICC.EXn.RSA or PuK.ICC.EXn.ECC
• PrK.ICC.EXn.RSA or PrK.ICC.EXn.ECC
• EF.C.ICC.EXn.RSA or EF.C.ICC.EXn.ECC

(with n of 1-10 being RSA 2048, n of 11-16 being RSA 3072 and 17-32 being ECC)

 - supported by Identity Manager

 - 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

Feature	Signature Card V2.0 (ECC)	IDKey 1.0 (RSA)
P10 request for pre-loaded RSA keys	n/a
P10 request for pre-loaded ECC sig/auth keys	The CA connector needs to support ECC.	n/a
P10 request for pre-loaded ECC enc key	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)	Key import is not supported.	Up to 10 keypairs with associated certificate can be imported.
Generate key on card	Not tested, can just redirect to matching pre-loaded key.	see Signature Card V2.0
Init PIN and PUK via InitToken
Delete existing certs by label
Profile init via InitToken	n/a	n/a
Profile reset	Not supported via P11 or the Telesec CardManager.	see Signature Card V2.0
Change PIN/PUK with old one
Unblock PIN with PUK
Unblock PUK with PIN	Not implemented for consistency with other cards.	see Signature Card V2.0
Unblock PIN with CardManagerKey	n/a	(Identity Manager 22.04.3 and later only, uses TCOS P11 extension, which is not challenge/response-based)
Change CardManagerKey with old one	n/a	(Identity Manager 22.04.3 and later only, uses TCOS P11 extension, which is not challenge/response-based)
Store cert chain or other arbitrary CA certs	/ 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.	StoreUserCertOnly=true is mandatory.
Change attributes on existing keys/certs	n/a as C_SetAttributeValue just returns CKR_OK without making any changes.	n/a see Signature Card V2.0
Support NetKey P11 library
Support SigG P11 library (for qualified signatures)	Not tested except for PIN/PUK handling.	see Signature Card V2.0
Support ELSTER P11 library (DE tax reporting)	Not tested	see Signature Card V2.0
Importing to a specific slot via label	n/a	Middleware supports it only starting with version 1.12.4.0

 - supported by Identity Manager

 - 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

Feature	TCOS 4.0 NetKey
P10 request for pre-loaded RSA keys
P10 request for pre-loaded ECC sig/auth keys	The CA connector needs to support ECC.
P10 request for pre-loaded ECC enc key	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)	Up to 10  RSA 2048 keypairs + 6 RSA 3072 keypairs + 16 ECC keypairs with associated certificate can be imported.
Generate key on card	Not tested, can just redirect to matching pre-loaded key.
Init PIN and PUK via InitToken
Delete existing certs by label
Profile init via InitToken	n/a
Profile reset	Not supported
Change PIN/PUK with old one
Unblock PIN with PUK
Unblock PUK with PIN	Not implemented for consistency with other cards.
Unblock PIN with CardManagerKey	(Identity Manager 22.10 and later only, uses TCOS P11 extension, which is not challenge/response-based)
Change CardManagerKey with old one	(Identity Manager 22.10 and later only, uses TCOS P11 extension, which is not challenge/response-based)
Store cert chain or other arbitrary CA certs	StoreUserCertOnly=true is mandatory.
Change attributes on existing keys/certs	n/a
Support NetKey P11 library
Support SigG P11 library (for qualified signatures)	Not tested
Support ELSTER P11 library (DE tax reporting)	Not tested
Importing to a specific slot via label	Middleware supports it only starting with version 1.12.4.0

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

• Define like this in the encoding description:

  CODE

  ...
  [Description]
  for version 1.8.x.x use these
  PKCS11LibraryWindows64=P11TCOS3NetKey64.dll
  PKCS11LibraryWindows32=P11TCOS3NetKey32.dll
   
  for version 1.10.x.x thru 1.12.x.x use these instead
  PKCS11LibraryWindows64=P11TCOSNetKey64.dll
  PKCS11LibraryWindows32=P11TCOSNetKey32.dll
  
  for version 1.13.x.x use these instead
  PKCS11LibraryWindows64=P11TCOSNetkey_x64.dll
  PKCS11LibraryWindows32=P11TCOSNetkey_x86.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).

Both PIN and InitialPUK have to be set.

• Define like this in the encoding description:
  

  CODE

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

Applies to:

• IDKey 1.0 (IDM 22.04.3 and later)
  
• TCOS 4.0 NetKey (IDM 22.10 and later)

Change CardManagerKey

• Define like this in the encoding description:

  CODE

  ...
  [Fields]
  CARD_MANAGER_KEY=
  NEW_CARD_MANAGER_KEY=
  ...
  [Description]
  SetPin=true
  CardManagerKey=CARD_MANAGER_KEY
  NewCardManagerKey=NEW_CARD_MANAGER_KEY
  ...

Unblock PIN Via CardManagerKey

• Define like this in the encoding description:

  CODE

  ...
  [Fields]
  CARD_MANAGER_KEY=
  NEW_PIN=
  ...
  [Description]
  SetPin=true
  CardManagerKey=CARD_MANAGER_KEY
  PIN=NEW_PIN
  ...

Any certificates on the card which you want to replace must 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, use a single application for all certificates to be deleted.

• Define like this in the encoding description:
  

  CODE

  ...
  
  [Application_X]
  # deleting only certs for some pre-loaded keys (example key labels for IDKey 1.0 cards)
  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 some imported ones (example key labels for IDKey 1.0 cards)
  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.

• Define like this in the encoding description:
  

  CODE

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

Certificate chain writing not supported

Applies to:

• IDKey 1.0
• Signature Card V2.0
• TCOS 4.0 NetKey

You must 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).

• Define like this in the encoding description:
  

  CODE

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

ECC KeySize

Applies to:

• Signature Card V2.0
• TCOS 4.0 NetKey

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 must specify a curve which has the same size (for example, 256 bits) as 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.

• Define like this in the encoding description:
  

  CODE

  ...
  [Application_X]
  # NOTE: some cards use ECC/brainpool256r1
  KeySize=ECC/prime256v1
  ...

ECC P10 Signing Algorithms

Applies to:

• Signature Card V2.0
• TCOS 4.0 NetKey

The only supported signing algorithm for Signature Card V2.0 is ECDSA with SHA1. On TCOS 4.0 NetKey cards you may use ECDSA with SHA256 as well.

• Define like this in the encoding description:
  

  CODE

  ...
  [Application_X]
  # use this for Signature Card V2.0 cards:
  Pkcs10SigningAlgorithm=SHA1_ECDSA
  
  # for TCOS 4.0 NetKey cards you can use this instead:
  Pkcs10SigningAlgorithm=SHA256_ECDSA
  ...

Dummy P10 signing for ECC encryption keys

Applies to:

• Signature Card V2.0

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.

• Define like this in the encoding description:
  

  CODE

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

Select user certificate slot

Applies to:

• Signature Card V2.0

On a Signature Card V2.0, each keypair can have multiple certificate slots. You must explicitly define which slot to use by specifying the correct certificate label (unlike above, not key label). Deleting existing certificates for a keypair does not guarantee that the resulting certificate will end up in the main slot.

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

• Define like this in the encoding description:

  CODE

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

Skip label or select target slot via labels

Applies to:

• IDKey 1.0
• TCOS 4.0 NetKey

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 in versions before 1.12.4.0, so it is mandatory to skip it. On TCOS 1.12.4.0 this restriction was removed Now it's possible to address to slot to put the certificate and keypair.

 Before writing, make sure the target slot is free by deleting the certificate and keys, or the middleware might report an error.

• Define like this in the encoding description:

  CODE

  ...
  [Application_X]
  # next free spot is taken automatically (mandatory before TCOS 1.12.4.0)
  LabelTemplate=skip
  ...
  [Application_Y]
  # TCOS 1.12.4.0 and up only, make sure the slot you specify here is free!
  # you have to specify the labels for private- and public key separately
  # from the certificate label, as they differ but share the same index
  LabelTemplate=fixtext=...
  PrivateKeyLabelTemplate=fixtext=...
  PublicKeyLabelTemplate=fixtext=...
  ...