# TCOS based preformatted cards

Telesec (part of T-Systems), Deutsche Post, Kobil GmbH and DATEV are german companies that sell TCOS based preformatted cards, i.e NetKey E4 cards, SignTrust cards, Smartkey cards and DATEV-cards. All these cards have a TCOS 2.02 operationg system and an almost PKCS#15 compatible file-layout. OpenSC has read-only support for these kind of cards.

If OpenSC would fully support TCOS, one could erase the preformatted card and initialize the card with a PKCS#15 filesystem. This is not possible right now as OpenSC lacks support for initializing a PKCS#15 layout on an empty card with TCOS operation system.

The good news are: With the help of an emulation layer OpenSC can use cards that are almost PKCS#15 compatible. For the above mentioned cards such an emulation layer exists. The emulation cannot store certificates, keys or pins on the card, but you can use whatever is visible through the emulation layer.

If you know of other TCOS based cards and are willing to help, please post information on the mailing list. You might also send `opensc-tool -f` output to me, maybe I can extend the emulation such that it works with your card as well.

Since late 2006 TCOS 3.0 cards are available from Telesec and a test card plus excellent doku has reached me. Besides 2048bit keys TCOS 3.0 has some new features so it might be necessary to write a separate driver. Another option is to extend the current TCOS 2.0 driver. The new NetKey cards are TCOS 3.0 based. The signature key of this new card can be used only with secure messaging. Since OpenSC does not have support for secure messaging the signature key will not be supported soon.

If your are interested in TCOS 3.0 cards - please let me know. Unless at least someone is interested I will work on other things.

## NetKey E4 filesystem layout

NetKey E4 cards contain different applications. Two of them, namely application NKS in DF DF01 and application SigG in DF DF06, are made visible through the NetKey emulation layer. The NKS application contains 3 keypairs, 3 read only certificates, 6 empty certificate files, 2 PINs and one signature-counter. The SigG application contains one keypair that can be used according to german signature law, 1 certificate and 1 PIN.

      pkcs15-tool -c

will list all certificates. It will not list empty certificate files. Here's the output for a new NetKey E4 card:

    $ pkcs15-tool -c
    X.509 Certificate [Telesec Signatur Zertifikat]
            Flags    : 0
            Authority: no
            Path     : df01c000
            ID       : 45

    X.509 Certificate [Telesec Authentifizierungs Zertifikat]
            Flags    : 0
            Authority: no
            Path     : df01c100
            ID       : 46

    X.509 Certificate [Telesec Verschluesselungs Zertifikat]
            Flags    : 0
            Authority: no
            Path     : df01c200
            ID       : 47

    X.509 Certificate [SigG Zertifikat 1]
            Flags    : 2
            Authority: no
            Path     : df06c000
            ID       : 48

The public-keys are record-based transparent files and cannot be used for cryptographic operations. They are on the card for convenience only. OpenSC extracts the public keys from the certificates and does not use the public key files.

The Signature-Key can do signature-operations only. All other private keys can be used for decryption- and signature operations.

### How do I store additional certificates into the above mentioned empty certificate-files?

You (and OpenSC) dont see the empty certificate files through the emulation layer. One consequence is that you cannot store your own certificates into these files with pkcs11-tool or pkcs15-init.

You must use opensc-explorer and store the certificate directly into the right position or use netkey-tool, a small program, that I wrote exactly for that purpose. Since version 0.7 of SCB netkey-tool is contained in the Windows version too.

In general (and in particular with TCOS-cards) it's a lot more complicated to create a new file on a smartcard than updating an existing one. That's the reason why there are empty certificate files on a NetKey card. They contain 1536 0xFF-bytes and you can overwrite them with your own certificate (if your certificate has at most 1536 bytes).

There is one problem with many PKCS#11 or PKCS#15 smartcard-applications. They assume that the ID of a certificate uniquely identifies the certificate itself. This is wrong as the ID only identifies the private/public keypair that belongs to the certificate. So if you have more than one certificate for the same keypair all these certificates will share the same ID-value. OpenSC has this problem with NetKey cards too. Have a look at the -r option of pkcs15-tool. In order to select a certificate you can only specify its ID and pkcs15-tool will output the first certificate from the card that has such an ID-value.

OpenSwan? is another application, that selects a certificate by ID and therefore has problems to select the right one from NetKey cards.

If you have stored a certificate on your card, you most likely want to use this certificate (and not the readonly-one). Therefore the emulation will add the user-certificates first into its internal list.

### Some remarks about the pins of a Netkey card

There are two global pins on a NetKey?-card and some of the directories contain further pins. The NetKey emuation will list the two global pins (PIN and PUK) and the two local pins contained in directory DF01 (PIN0 and PIN1). The TCOS card operation system can protect a private key by more than one pin. OpenSC does NOT support this and will always ask for one specific pin. If a key is protected by both a global pin and a local pin OpenSC will always ask for the local one.

Now that you know that you MUST use local PIN0 or local PIN1 and cannot use your global PIN instead you probably want to know the initial value of those local pins. But these local pins were set to a random 6-digit number when TeleSec Gmbh produced your card. So you cannot know them until you changed them.

You can change local PIN0 only if you know either local PIN0 itself or your global PIN. And you cannot change a pin once it was blocked. So if your local PIN0 is blocked (for example because you provided you global PIN when OpenSC asked you for the local one and you did that for at least three times) then you must unblock it first.

Here's an example about how to unblock your local PIN0, how to change its value to 111111 with your global PIN and then change its value from 111111 to 222222. It assumes that your global PIN is 123456

    netkey-tool --pin 123456 unblock pin0
    netkey-tool --pin 123456 change pin0 111111
    netkey-tool --pin0 111111 change pin0 222222

One more hint: Your global PUK was set to an 8-digit random number at production time. This random number is stored on your card in a transparent file. This transparent file is read-protected by your global PIN. If you ever block your global PIN you will need your global PUK. But once your global PIN is blocked you cannot read the initial value of your global PUK anymore.

`netkey-tool --pin <your_global_pin>` will print out the initial PUK-value. If you changed your global PUK to some other value the transparent file on your card will still contain the initial value.

`netkey-tool` does not support the SigG application. If you want to change your SigG-PIN or read/write yout SigG-certificates with `netkey-tool` please let me know.

## SignTrust layout

SignTrust cards contain three applications (i.e. directories). Each of them contain one certificate, one private key and one pin.

The signature-key is restricted such that it can create signatures only, the other keys can be used for decryption- and signature operations. There are no empty certificate files on a SignTrust card (as with NetKey cards) so you cannot store your own certificates on a SignTrust card.

The certificate from the signature-application can ba used to create SigG (german signature law) conforming digital signatures. Neither the CA-certificate nor the Root-Certificate is stored on the card but you can download them here.

Here's some output that shows the SigG-certificate of my SignTrust card:

    $ pkcs15-tool -r 45 | openssl x509 -noout -text -certopt no_pubkey,no_sigdump
    Certificate:
        Data:
            Version: 3 (0x2)
            Serial Number: 32322 (0x7e42)
            Signature Algorithm: sha1WithRSAEncryption
            Issuer: C=DE, O=Deutsche Post Com GmbH, OU=Signtrust, CN=CA DP Com 5:PN
            Validity
                Not Before: Sep 21 10:19:04 2005 GMT
                Not After : Sep 21 10:19:04 2007 GMT
            Subject: CN=Peter Koch, SN=Koch, GN=Peter, C=DE/serialNumber=1
            X509v3 extensions:
                X509v3 Authority Key Identifier:
                    keyid:22:BB:26:65:07:57:15:DE:06:EB:10:1E:CC:77:82:A7:13:79:74:C6
                    DirName:/C=DE/O=Bundesnetzagentur/CN=10R-CA 1:PN
                    serial:AE
                X509v3 Key Usage: critical
                    Non Repudiation
                X509v3 Certificate Policies:
                    Policy: 1.3.36.8.1.1
                X509v3 CRL Distribution Points:
                    URI:ldap://dir.signtrust.de/o=Deutsche%20Post%20Com%20GmbH,c=de
                    CRLissuer:<UNSUPPORTED>
                Authority Information Access:
                    OCSP - URI:http://dir.signtrust.de/Signtrust/OCSP/servlet/httpGateway.PostHandler

The remaining certificates (from the authentication and encryption application) are signed by a selfsigned Root-certificate from Deutsche Post.

## Kobil Smartkey layout

There are two sorts of Kobil Smartkey cards. The first one are NetKey E4 cards with one additional directory where Kobil stores a Windows 2000 logon certificate. The emulation detects this kind of Smartkey cards as a NetKey card.

The second one has a Kobil specific undocumented layout. The emulation tries its best to support this kind of cards too. Two Smartkey-variants that already works are the student card of the Technical University of Darmstadt and the student card of the University of Giessen. These Smartkey variants both contain one application with one private key, one public key file and one certificate, protected by one global PIN and PUK.

Here' some output that shows the layout of the TUD-card:

    $ pkcs15-tool -D
    PKCS#15 Card [Smartkey Card TypB]:
            Version        : 0
            Serial number  : 8949017200003335855
            Manufacturer ID: Kobil GmbH
            Flags          :

    PIN [globale PIN]
            Com. Flags: 0x3
            ID        : 01
            Flags     : [0x51], case-sensitive, initialized, unblockingPin
            Length    : min_len:6, max_len:16, stored_len:16
            Pad char  : 0x00
            Reference : 0
            Type      : ascii-numeric
            Path      : 5000
            Tries left: 3

    PIN [globale PUK]
            Com. Flags: 0x3
            ID        : 02
            Flags     : [0xD1], case-sensitive, initialized, unblockingPin, soPin
            Length    : min_len:8, max_len:16, stored_len:16
            Pad char  : 0x00
            Reference : 1
            Type      : ascii-numeric
            Path      : 5008
            Tries left: 3

    Private RSA Key [Smartkey Schluessel 1]
            Com. Flags  : 1
            Usage       : [0x7], encrypt, decrypt, sign
            Access Flags: [0x1D], sensitive, alwaysSensitive, neverExtract, local
            ModLength   : 1024
            Key ref     : 131
            Native      : yes
            Path        : 41015103
            Auth ID     : 01
            ID          : 45

    X.509 Certificate [Smartkey Zertifikat 1]
            Flags    : 2
            Authority: no
            Path     : 41014352
            ID       : 45

If you are using a Smartkey card that OpenSC does not yet support please let me know.

## DATEV cards

DATEV offers different smart cards. Some are NetKey cards (those that can create signatures in accordance with the german signature law) and will be detected as such. One model is not (named DATEV Smartcard classic) and this card has a seperate emulation. It contains two application. One application has one certificate and one keypair while the other application contains two certificates and two keypairs. There's only one global PIN that protect all keys.

If you are using a DATEV card that OpenSC does not yet support please let me know.