Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
The OpenPGP card is an ISO/IEC 7816-4/-8 compatible smart card implementation that is integrated with many GnuPG functions.
Using this smart card, various cryptographic tasks (encryption, decryption, digital signing/verification, authentication etc.) can be performed.
The cards come in various form factors ranging from the standard size ID-1, over ID-1 with cut-outs for ID-000 (i.e. SIM card size), which together with an USB card reader allows to build a do-it-yourself crypto stick, the Nitrokey (former Crypto Stick).
Version 1.0 of the specification is mostly of theoretical interest, as most – if not all – cards adhere to version 1.1 or version 2.0.
All versions allow storing card holder details as well as generating and storing up to three RSA key pairs on the card.
While the 1.x version only supported 1024-bit RSA keys and no certificates, version 2.0 allows for RSA keys up to 4096 bits (requires GnuPG 2.0.18+) and optionally an X.509 card holder certificate for the AUT key on the card.
Other changes were:
- V1.1 brought 4 optional DOs for private use with different access conditions
- V2.0 brought optional support for
- card reset functionality (life cycle management)
- changeable algorithm attributes
- other algorithms than RSA (not specified)
- Removal of PW2 (“Encryption PIN”) present in v1.1. In v2.0 only “Admin PIN” and “User PIN” are specified. Furthermore, v2.0 spec defines “user consent” capabilities for signature key.
Where/How to get one?
OpenPGP cards / Nitrokeys can be obtained from vendors like e.g.
- Kernel concepts
- or by becoming a fellow in the Free Software Foundation Europe which uses the OpenPGP card specification on the Fellowship Smart Cards it hands out to its fellows.
State of OpenSC support
OpenPGP card v1.0 /1.1 is deprecated but should work since OpenSC 0.9.1. Starting with OpenSC 0.12.2, OpenSC supports reading the OpenPGP card v2.0 too. Since OpenSC, 0.13 full write support for OpenPGP card 2 is supported.
Gnuk, a variant of OpenPGP v.2 is supported since OpenSC 0.15.
Basically, usage between general OpenPGP card (Nitrokey for example) and Gnuk are the same, except some differences that will be noted below.
1. Display user info
2. Read and write data object (DO)
For example, you want to change card holder name:
2. Verify Admin PIN by this command
verify CHV3 3132333435363738
CHV3 means Admin PIN is to be verified (User PIN will be CHV1 or CHV2) and
3132333435363738 is ASCII-decoded hex string of PIN code “12345678”.
3. Put data to 005B DO, the DO containing card holder name:
do_put 005B "Quan"
4. Remove it afterwards:
do_put 005B ""
5. Or change user PIN to “654321”:
change CHV1 31:32:33:34:35:36 "654321"
31:32:33:34:35:36is hex string of ASCII-decoded old PIN “123456”.
Reading DO content is not as straightforward as writing, because the DOs are nested in each other. For example, to read 005B DO, you have to go through 0065 DO:
OpenSC [3F00]> cd 0065 OpenSC [3F00/0065]> cat 005B 00000000: 51 75 61 6E Quan
Note: We cannot delete DO content with
delete/rm command. Technical reason: The OpenSC framework doesn’t pass the full path of file to OpenPGP driver, so the driver cannot identify the DO to be deleted.
3. Generating keys
Key generation via
openpgp-tool --verify CHV3 --pin 12345678 --gen-key 3 openpgp-tool --verify CHV3 --pin 12345678 --gen-key 1 --key-len 1024
--genkey 3 means that we’re generating key with ID=3. The three keys in the have these IDs: Signing key: 1, Decryption key: 2, Authentication: 3.
--key-length 1024 means that the key is 1024-bit. We can specify bit length: 1024, 2048, 3072, 4096.
If this option is absent, default key length 2048-bit is used.
Gnuk only supports 2048-bit key, so don’t specify
--key-length option, you also have to delete old key before generating or import new one.
openpgp-tool --verify CHV3 --pin 12345678 --del-key 3
Note: The 4096-bit key is supported in development version of OpenSC, after v0.16.
Key generation via
pkcs15-init --delete-objects privkey,pubkey --id 3 --generate-key rsa/2048 --auth-id 3 --verify
There is limitation:
pkcs15-init requires new key length to be the same as existing key. To generate key with different key length,
openpgp-tool is recommended.
pkcs15-init also requires to explicitly remove existing key/object. That’s why we have
--delete-objects privkey,pubkey --id 3 in the command (though it has no effect to Nitrokey, which does not support deleting key, but support overwriting key).
Note: Generating key via PKCS#11 is not supported yet. Technical reason: The operation needs Admin PIN, but we find no way in OpenSC to popup a prompt dialog for PIN entry.
4. Delete key (Gnuk)
Deleting key is supported by Gnuk and Nitrokey Start only. Other Nitrokey models don’t.
Example to delete 3rd (authentication) key:
openpgp-tool --verify CHV3 --pin 12345678 --del-key 3
pkcs15-init --delete-objects privkey,pubkey --id 3
If you want to delete key from Nitrokey, the only option is to erase card (all things will be deleted).
5. Erase card (Nitrokey)
Erasing card is supported by Nitrokey (or general OpenPGP card v2). Gnuk and Nitrokey Start support this function from version 1.2.6 on.
6. Import key resp. certificate
pkcs15-init --store-certificate mycert.pem --id 3
In which the PEM file is extracted from p12 using OpenSSL (key is stripped out):
openssl pkcs12 -in myprivate.p12 -nokeys -out mycert.pem
Note that the OpenPGP Card v2 contains only 1 certificate, so the ID to store is always 3.
pkcs15-init --delete-objects privkey,pubkey --id 3 --store-private-key mykey.pem --auth-id 3 --verify-pin --id 3
In which the PEM file is extracted from a p12 file using OpenSSL
(certificate is stripped out):
openssl pkcs12 -in myprivate.p12 -nocerts -out mykey.pem
Pairs of key & certificate from P12 file:
pkcs15-init --delete-objects privkey,pubkey --id 3 --store-private-key myprivate.p12 --format pkcs12 --auth-id 3 --verify-pin
- In current version,
pkcs15-inittool is pretty silent, so you may not recognize if the operation is successful or not. You should run
pkcs15-initin debug mode (set environment variable
- In p12 file, the
pkcs15-initdetect X.509 certificates in hierarchy, in which only the first found certificate need to be imported. But
pkcs15-initthen try to do with all, so the later imports will fail. You can see some error messages due to this failure, but it is OK because the main certificate has been imported successfully.
- The certificate can be used to encrypt email. But to make decryption work, the corresponding private key need to be import to “Decryption Key” (ID=2) as well (normally, it is imported to “Authentication Key”, which has the same ID=3 as certificate).
pkcs15-init --delete-objects privkey,pubkey --id 2 --store-private-key mykey.pem --auth-id 3 --verify-pin --id 2
7. Delete certificate
pkcs15-init --delete-objects cert --id 3
OpenSC driver details
OpenPGP cards only implement a small subset of the ISO/IEC 7816-4/-8 standard. Most importantly, they do not use a file system to store the application specific data. Instead the data stored for the application is accessible via Data Objects (DO) only.
These DOs come in two variants:
- simple DOs that do not have a meaningful internal structure
- complex DOs that have a well-known internal structure which is encoded according to ASN.1 BER rules
In order to make OpenPGP cards accessible for OpenSC’s PKCS15 functions, the OpenPGP card driver in OpenSC simulates a file system.
It does so by reading the well-known DOs on the card and converting them according to this logic:
- simple DOs are treated as wEFs
- complex DOs are treated as DFs with their elements as children.
As complex DOs can also contain complex DOs as elements, this conversion is done recursively, leading to a multi-level hierarchy.
This file-system is currently read-only, hence any operation writing to the card, i.e. personalization and key generation, needs to be done via GnuPG.
Here’s an example of a card as seen via GnuPG:
$ gpg --card-edit Application ID ...: D2760001240101010001000004D50000 Version ..........: 1.1 Manufacturer .....: PPC Card Systems Serial number ....: 000004D5 Name of cardholder: John Doe Language prefs ...: en Sex ..............: male URL of public key : [not set] Login data .......: johndoe Private DO 1 .....: [not set] Private DO 2 .....: [not set] Signature PIN ....: forced Key attributes ...: 1024R 1024R 1024R Max. PIN lengths .: 254 254 254 PIN retry counter : 0 0 0 Signature counter : 5 Signature key ....: 6B71 349B 27F0 370A A964 9BD4 967C B116 BDFA 3CDD created ....: 2010-03-07 09:17:36 Encryption key....: 3A2F 8637 C325 AAEE 18DD 88F1 AC40 47D4 2764 F212 created ....: 2010-03-07 09:18:25 Authentication key: F49C 7334 2AEC B098 60C9 04C7 9BFC 9789 DF31 19A9 created ....: 2010-03-07 09:18:25 General key info..: pub 1024R/BDFA3CDD 2010-03-07 John Doe <email@example.com> sec> 1024R/BDFA3CDD created: 2010-03-07 expires: never card-no: 0001 000004D5 ssb> 1024R/DF3119A9 created: 2010-03-07 expires: never card-no: 0001 000004D5 ssb> 1024R/2764F212 created: 2010-03-07 expires: never card-no: 0001 000004D5
opensc-explorer the very same card looks like
$ opensc-explorer OpenSC Explorer version 0.12.1-svn Using reader with a card: SCM SCR 335 [CCID Interface] (60600adc) 00 00 OpenSC [3F00]> ls FileID Type Size 004F wEF 16 [005E] DF 8  DF 20 [006E] DF 202  DF 157 [007A] DF 5 5F50 wEF 0 [B600] DF 141 [B800] DF 141 [A400] DF 141 B601 wEF 142 B801 wEF 141 A401 wEF 142 OpenSC [3F00]> cd 0065 OpenSC [3F00/0065]> ls FileID Type Size 005B wEF 9 5F2D wEF 2 5F35 wEF 1 OpenSC [3F00/0065]> cat 005B 00000000: 44 6F 65 3C 3C 4A 6F 68 Doe<<John OpenSC [3F00/0065]>
- Minimum PIN length is 6 (you get a generic “Bad PIN” error if trying to use a shorter one) and Admin PIN must be at least 8 digits.
- OpenPGP v2.0 card can be erased with the following command (ATTENTION! ONLY USE IT ON A V2 CARD LIKE NITROKEY! WILL BRICK OTHERS!)
$ opensc-tool -s 00:20:00:81:08:40:40:40:40:40:40:40:40 \ -s 00:20:00:81:08:40:40:40:40:40:40:40:40 \ -s 00:20:00:81:08:40:40:40:40:40:40:40:40 \ -s 00:20:00:81:08:40:40:40:40:40:40:40:40 \ -s 00:20:00:83:08:40:40:40:40:40:40:40:40 \ -s 00:20:00:83:08:40:40:40:40:40:40:40:40 \ -s 00:20:00:83:08:40:40:40:40:40:40:40:40 \ -s 00:20:00:83:08:40:40:40:40:40:40:40:40 \ -s 00:e6:00:00 \ -s 00:44:00:00
- In order to import 4096 bit RSA keys, the Nitrokey may need to be initialized with a 4096 bit RSA key beforehand (e.g. via GnuPG). Otherwise, you may experience an “Invalid key size” error.
Mac OS X
- Use http://www.gpgtools.org/ to get GnuPG2 for Mac OS X
- Remove OpenSC.tokend from !/System/Library/Security/tokend when personalizing your token. scdaemon requires exclusive access which can not be shared with OpenSC.tokend, which is started when OpenPGP card/token is inserted.
- kill scdaemon and re-insert your reader if you still see this:
gpg: selecting openpgp failed: Card error gpg: OpenPGP card not available: Card error
Linux (and Gnome)
gnome-keyring sets up
$ env | grep GPG_AGENT GPG_AGENT_INFO=/tmp/keyring-cKD5KN/gpg:0:1
This agent is not capable of talking to smart cards (
$ gpg2 --card-status gpg: selecting openpgp failed: Unsupported certificate gpg: OpenPGP card not available: Unsupported certificate
gpg2from a console or unset
GPG_AGENT_INFOto use smart card related functions:
$ GPG_AGENT_INFO= gpg2 --card-status scdaemon: enabled debug flags: command cardio Application ID ...: D2760001240102000005000005460000 Version ..........: 2.0 Manufacturer .....: ZeitControl ...
Or permanently disable the
And then uncheck GPG Password Agent, log out and log back in.
If there is no GPG Password Agent entry in
gnome-session-properties, you can put this line to ~/.bashrc file:
SSH agent failure
When using OpenSSH with support of a pkcs11 module, you may fail:
$ ssh-add -s /usr/lib/opensc-pkcs11.so Enter passphrase for PKCS#11: SSH_AGENT_FAILURE Could not add card: /usr/lib/opensc-pkcs11.so
gpg2 and multiple readers
gpg2 only works if the OpenPGP compatible card is in the first listed reader:
$ opensc-tool -l # Detected readers (pcsc) Nr. Card Features Name 0 No Sitecom USB simcard reader MD-010 00 00 1 Yes German Privacy Foundation Crypto Stick v1.2 01 00 $ GPG_AGENT_INFO= gpg2 --card-status scdaemon: enabled debug flags: command cardio gpg: selecting openpgp failed: Card not present gpg: OpenPGP card not available: Card not present
$ opensc-tool -l # Detected readers (pcsc) Nr. Card Features Name 0 Yes German Privacy Foundation Crypto Stick v1.2 00 00 1 No Sitecom USB simcard reader MD-010 01 00 $ GPG_AGENT_INFO= gpg2 --card-status scdaemon: enabled debug flags: command cardio Application ID ...: D2760001240102000005000005460000 Version ..........: 2.0 Manufacturer .....: ZeitControl ...
Solution: remove other smart card readers. If all readers are USB, killing pcscd and inserting readers in the “right order” (Nitrokey first) helps. If this is not possible (for example, a reader integrated into the keyboard) editing the CCID driver Info.plist file and removing entries related to the “other” smart card readers can help.
Alternatively look up the name of the reader you are using and add it to ~/.gnupg/scdaemon.conf (or
--reader-port command line option if using GnuPG 1.X):
reader-port "German Privacy Foundation Crypto Stick v1.2 01 00"
After this a reader other than the first reader can be used. Be sure to change the configuration file if your reader setup changes (like more readers are added before the right one) as the numbering at the end of the name changes.
No readers error
If there are no readers connected,
gpg2 gives a “generic” error message:
$ opensc-tool -l No smart card readers found. $ GPG_AGENT_INFO= gpg2 --card-status scdaemon: enabled debug flags: command cardio gpg: selecting openpgp failed: Card error gpg: OpenPGP card not available: Card error
This is just for your information.