Whenever your are asked to enter a PIN make sure you know which PIN is meant. There are two PINs for the card - the PIN and the AdminPIN. Please make sure you do not mix them up.

This phenomenom occurs when the card reader has been in use for quite some time. It might help to re-plug the reader.

During the writing of this HowTo it seemed that every once in a while GnuPG did not want to talk with the card reader. We were quite sure we have not changed anything in the configuration but for some reason it just did not work. Werner knows this problem and it will hopefully soon be fixed. Note that we never encountered this problem with Linux kernels 2.4.x - only with most 2.6 kernels.

This primary user ID is shown if the corresponding public OpenPGP key is available.

This key is not used by gpg at all. Other tools like PAM modules or ssh use this key for authentication services.

This key is commonly used as an encryption subkey.

This key is commonly used as the primary OpenPGP key.

This number keeps track of the signatures performed with the stored key. It is only reset if a new signature key is created on or imported to the card.

This field saves how many tries still are left to enter the right PIN. They are decremented whenever a wrong PIN is entered. They are reset whenever a correct AdminPIN is entered. The first and second PIN are for the standard PIN. gpg makes sure that the two numbers are synchronized. The second PIN is only required due to peculiarities of the ISO-7816 standard; gpg tries to keep this PIN in sync with the first PIN. The third PIN represents the retry counter for the AdminPIN.

This field is unchangeable. The values are put on the card right after personalisation - this is the moment after the chip has been glued on the card.

When set to "forced", gpg requests the entry of a PIN for each signature operation. When set to "non forced", gpg may cache the PIN as long as the card has not been removed from the reader.

This field may be used to store the account name of the card holder. It may be used for login purposes. gpg does not enforce any match of this name with a name used in the key. See the source (app-openpgp.c) for some special features of the login-name field.

Used by the fetch command of gpg --edit-card . It may contain an URL to be used to retrieve the public key.

The holder of this card. Only plain ASCII characters are Allowed here. gpg does not use this field.

The manufacture's ID. This includes the type of the card, the implemented version of the specification, the manufacturer and the serial number. This is a unique identifier for any card.

The information displayed is the standard output for the Fellowship smartcard we are using. Cards from other manufacturers might produce a different output.

To check if your card (and installation) is working please put your OpenPGP card in the reader and run gpg --card-status . For an empty card the output should look like this:

Changing the AdminPIN is the same procedure as changing the PIN. Enter the current AdminPIN. Then enter a new AdminPIN and re-enter it. The normal PIN is not affected by these changes.

Please note that an AdminPIN cannot be unblocked.

First you are asked for the AdminPIN and then to enter and re-enter a new PIN. The AdminPIN is not affected by this procedure.

The PIN has been successfully changed. The AdminPIN is not affected by these changes.

You are first asked to enter the current PIN. Afterwards you are asked to enter the new PIN. Then you are asked to re-enter the new PIN. The cursor will not move forward to indicate your typing.

To access the PIN operations enter gpg --change-pin . Different options for PIN management will be displayed. To select a command enter the number displayed in front of the command.

It is also important to know that entering a wrong AdminPIN three times in a row destroys(!) the card. There is no way to unblock the card when a wrong AdminPIN has been entered three times.

If a wrong PIN has been entered three times in a row the card will be blocked. It can be unblocked with the AdminPIN.

You might have received a card with a few data fields already personalized (e.g. the FSFE Fellowship card). Please check the documentation which comes with this card to see whether the default PINs are really to be used or from where to get the actual PINs. Often the AdminPIN is send by separate mail.

A new card has the following default PINs stored. The AdminPIN's value is 12345678. The normal PIN is 123456. Please note that the second PIN is two digits shorter.

3.3. Initialising the card

To follow the instructions in this chapter make sure that the card reader works and the card can be accessed (Chapter 3, Administrating the Card, command gpg --card-status ).

To initialise a card enter gpg --card-edit . Basic information about the card is shown. The output is the same as gpg --card-status . The difference is that the output is now followed by a command prompt.

To get a list of all commands available enter help .

Command> help quit quit this menu admin show admin commands help show this help list list all available data fetch fetch the key specified in the card URL passwd menu to change or unblock the PIN

These commands are not very useful because data stored on the card cannot be changed.

For a list of useful commands enter admin and then help .

Command> admin Admin commands are allowed Command> help quit quit this menu admin show admin commands help show this help list list all available data name change card holder's name url change URL to retrieve key fetch fetch the key specified in the card URL login change the login name lang change the language preferences sex change card holder's sex cafpr change a CA fingerprint forcesig toggle the signature force PIN flag generate generate new keys passwd menu to change or unblock the PIN

3.3.1. Personalising the card Save the name of the card owner on the card. Technically this is not required but it will prove useful if more than one card is around. Enter name and follow the prompts. You are seperately asked for sur- and given name. After entering the data you are asked for the AdminPIN. Note The name is stored in an ISO format. This format distinguishes between the different name parts and is also used for machine readable passports. In general the AdminPin is cached through a session. So if you do not remove the card you will not be asked again to enter it. As always there are exceptions to this rule. If you like you can also enter the language you prefer ( lang ) and the sex ( sex ). gpg does not use this information so you might want to omit it.

3.3.2. Generating keys To generate a key on the card enter generate . You will be asked if you would like to make an off-card copy of the encryption key. It is useful to say yes here. Note Without a backup you will not be able to access any data you encrypted with the card if it gets lost or damaged. Command> generate Make off-card backup of encryption key? (Y/n) If a key exists on the card a security question has to be answered to avoid accidental overwriting. gpg: NOTE: keys are already stored on the card! Replace existing keys? (y/N) The whole process of key generation looks like this. Note You might be asked for the PINs at different times. Command> generate Make off-card backup of encryption key? (Y/n) Y gpg: 3 Admin PIN attempts remaining before card is permanently locked Admin PIN PIN Please specify how long the key should be valid. 0 = key does not expire <n> = key expires in n days <n>w = key expires in n weeks <n>m = key expires in n months <n>y = key expires in n years Key is valid for? (0) 0 Key does not expire at all Is this correct? (y/N) y You need a user ID to identify your key; the software constructs the user ID from the Real Name, Comment and Email Address in this form: "Heinrich Heine (Der Dichter) <heinrichh@duesseldorf.de>" Real name: Archibald Goodwin Email address: archi@foobar.example Comment: tester You selected this USER-ID: "Archibald Goodwin (tester) <archi@foobar.example>" Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O gpg: generating new key gpg: please wait while key is being generated ... gpg: key generation completed (45 seconds) gpg: signatures created so far: 0 gpg: signatures created so far: 0 You need a Passphrase to protect your secret key. +++++ ..+++++ gpg: NOTE: backup of card key saved to `/home/archi/.gnupg/sk_26D728A8F09033F1.gpg' gpg: signatures created so far: 2 gpg: signatures created so far: 2 gpg: generating new key gpg: please wait while key is being generated ... gpg: key generation completed (25 seconds) gpg: signatures created so far: 4 gpg: signatures created so far: 4 gpg: key FF19F200 marked as ultimately trusted public and secret key created and signed. gpg: checking the trustdb gpg: 3 marginal(s) needed, 1 complete(s) needed, classic trust model gpg: depth: 0 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 1u pub 1024R/FF19F200 2005-03-05 Key fingerprint = 884B 9142 F645 1A72 4B92 EB94 DF80 CCEF FF19 F200 uid Archibald Goodwin (The Tester) <archi@foobar.example> sub 1024R/F09033F1 2005-03-05 sub 1024R/3239D981 2005-03-05 Six signing operations are done during the creation of the public and secret key (one self-signature to bind the name to the key and two key-binding signatures for each key). Future versions of gpg might just need three signing operations. Command> list Application ID ...: D2760001240101010001000000490000 Version ..........: 1.1 Manufacturer .....: PPC Card Systems Serial number ....: 00000049 Name of cardholder: Archibald Goodwin Language prefs ...: de Sex ..............: unspecified URL of public key : [not set] Login data .......: [not set] Signature PIN ....: not forced Max. PIN lengths .: 254 254 254 PIN retry counter : 3 3 3 Signature counter : 6 Signature key ....: 884B 9142 F645 1A72 4B92 EB94 DF80 CCEF FF19 F200 created ....: Sat Mar 5 19:56:42 2005 CET Encryption key....: 31C1 2190 FCF1 A684 5AF9 D719 26D7 28A8 F090 33F1 created ....: Sat Mar 5 19:56:43 2005 CET Authentication key: 811F C45F 911A C15A F6DC 5BD6 58BA B8D1 3239 D981 created ....: Sat Mar 5 19:57:19 2005 CET General key info..: pub 1024R/FF19F200 2005-03-05 Archibald Goodwin (The Tester) <archi@foobar.example>

The card is now ready for use.