How to use a NetKey card

[Werner Koch]

Hi!

I managed to make the German Telesec NetKey Smartcards work with
Aegypten.  For now only signing is supported and card personalization
requires the use of OpenSSL.

You have to use the latest NewPG from the CVS and with a modified
OpenSC tarball at:

  ftp://ftp.gnupg.org/gcrypt/alpha/aegypten/newpg-0.6-1-wk-20020328.tar.gz

I am going to prepare patches for the upstream release but for now the
tarball should work.

IF YOU DON'T FOLLOW THESE RULES, IT MAY HAPPEN THAT YOU MAKE THE CARD
UNUSABLE - IT IS ALSO LIKELY THAT THIS HAPPENS DUE TO BUGS OR
INSTRALLATION PROBLEMS.  I have been lucky in that I have only one
file on one card which is not deletable anymore.

The blank TCOS cards don't work yet because we do not have a procedure
yet to install a SO password (global secret 0). 


1. Build OpenSC as usual and make sure that OpenSSL supported is
   included (the configure run displays this).

2. You must install an opensc.conf file in {prefix}/etc; an example is
   included in opensc/etc/.  I am using the pcsc framework.

3. Build newpg

4. Create a new test certificate and a key using OpenSSL.

5. Insert the Netkey card and fire up opensc-explorer.  Do this at the
   opensc-explorer command line (we assume that it is a fresh card
   with a 6 byte NullPIN):

     change CHV0 00:00:00:00:00:00  "admin0"
     get 2F00 saved-2F00
     del 2F00
     quit

   We need to delete the GDO file because the record length used is
   too short for our application.  Note the new SO (Security Officer)
   password ("admin0") somewhere.  

6. Initialize the card:

    $ pkcs15-init -C

   You are asked for 2 PINs and PUKs; use at least 6 characaters.
   The PUKs are not yet used, the SO password serves for this.
   
7. Write a certificate to the card:

    $ pkcs15-init -X /somewhere/my_cert.pem

8. Write a secret key to the card

    $ pkcs15-init -S /somewhere/my_private_key.pem

   You are asked for the PEM password which is used to protect the ket
   in the PEM file and for CHV2, where you enter the password/PIN set
   in step 2.
   
   Note, you will see an error message - don't care about this.

9. Check that everything is fine:

    $ pkcs-tool --list-pins

    After some garbage you should get:

       Card has 2 PIN code(s).
       
       PIN [Authentication PIN]
               Com. Flags: 0x13
               Auth ID   : 01
               Flags     : [0x03], case-sensitive, local
               Length    : 6..16
               Pad char  : 0x00
               Reference : 128
               Type      : 2
               Path      : 3F005015
       
       PIN [Non-repudiation PIN]
               Com. Flags: 0x13
               Auth ID   : 02
               Flags     : [0x03], case-sensitive, local
               Length    : 6..16
               Pad char  : 0x00
               Reference : 129
               Type      : 2
               Path      : 3F005015

    $ pkcs-tool -c

        Card has 1 certificate(s).
             
        X.509 Certificate [Authentication Certificate]
                 Flags    : 0
                 Authority: no
                 Path     : 3F0050159001
                 ID       : 45

    $ pkcs-tool -k

         Card has 1 private key(s).
         
         Private RSA Key [Authentication Key]
                 Com. Flags  : 0
                 Usage       : [0x4], sign
                 Access Flags: [0x1D], sensitive, alwaysSensitive, neverExtract, local
                 ModLength   : 1024
                 Key ref     : 0
                 Native      : no
                 Path        : 3F0050155001
                 Auth ID     : 01
                 ID          : 45


10.  Now register this card with gpgsm:

      $ gpgsm --learn-card

11.  Now you can use this card to create a signature

      $ gpgsm -sbvu 'user_id_of_new_cert' plain >plain.sig

     The PIN entry dialog should pop up and ask you for the
     Authentication PIN which is the one you entered as CHV0.

     There will also be a popup window to ask you to insert the card
     if you did remove it from the reader or you are using a different
     one.


That's it.  This is all alpha code of course and some security
things are not yet setup in the way they should.

You may want to erase the PKCS15 structure in case of (very likely)
problems; you can use this script:

   $ opensc-explorer <<EOF
cd 5015
del 9001
del 5002
del 5001
del 4404
del 4402
del 4401
del 5032
del 5031
del 0011
del 0001
cd ..
del 5015
EOF


If you want to play with the PIN files created under the 5015 DF, you
should now that you have to use CHV128 and CHV129 with the
opensc-explorer commands "ver" and "change".


Happy hacking,

  Werner