A quick installation guide to opensc ==================================== To install opensc, please do as user, $ wget http://www.opensc.org/files/opensc-x.y.z.tar.gz $ tar xfvz opensc-x.y.z.tar.gz $ cd opensc-x.y.z nothing special so far. $ ./configure --prefix=/usr --sysconfdir=/etc This will install opensc in /usr with the config file in /etc. If you installed openct at some special place opensc might not find it. Please add "--with-openct=/path/to/openct" to make sure it is found. At the end of the configure script, opensc will print a summary page, too. It should look like this: OpenSC has been configured with the following options User binaries: /usr/bin Configuration files: /etc Host: i686-pc-linux-gnu Compiler: gcc Compiler flags: -Wall -fno-strict-aliasing -g -O2 Preprocessor flags: -I${top_builddir}/src/include Linker flags: -L/usr -L/usr/lib -L/usr/lib Libraries: -lpthread Random number collection: device (/dev/urandom) OpenSSL support: yes with engine: yes PC/SC support: yes OpenCT support: yes Assuan support: no LDAP support: yes PAM support: yes OpenSSL support is very important, some cards cannot work without. I strongly suggest to use a recent version. Best is 0.9.7d or later, as the OpenSSL project improved one issue very important to opensc. But older versions will work fine, too. If you want to use openssl version 0.9.6, be aware that it is available in two flavors: the normal version and an "engine" version. Only with the "engine" version OpenSC can provide full OpenSSL support, including two engines for OpenSSL. With OpenSSL 0.9.7 you don't need to worry, the engine support is always enabled. OpenSC is about smart cards. You need some software that knows smart card readers to access the cards in them. OpenSC supports three flavors: - CT-API is a very simple interface, and there are many drivers for it, mostly binary only. This support is always build into OpenSC. But it is recommended to use this only for testing, or in environments with a single user and a single application using smart cards. - PC/SC is a standard used in the Windows world. But the pcsc-lite software implements this standard for Unix and Mac OS X, too, and many drivers are available for it. Some are open source, many are binary only. - OpenCT is an open source software implementing smart card drivers for many smart card readers and usb tokens. OpenCT does not follow any standard, but instead it is small, lean, and still has everything needed to do the job. OpenCT is only available on Linux and Unix-like operating systems, but not on Windows. If OpenCT supports your reader, it is the recommended choice to use. Otherwise if there is a driver for pcsc-lite, that is your best alternative. Note: it is possible to use OpenCT both directly with OpenSC, but you can also create a chain OpenCT -> PC/SC-Lite -> OpenSC. Such a chain is only recommended, if applications other than OpenSC need to access the same readers and smart cards, too. Otherwise it adds an overhead and is not tested very much. Note also that OpenSC can use both, OpenCT and PC/SC-Lite at the same time. So if both are turned on, that is fine. To use OpenSC with GnuPG, first compile the assuan library, then compile OpenSC with support for Assuan, and then compile GnuPG with OpenSC. This only works with development versions of GnuPG (1.9.*) and has not been well tested. Feedback is very welcome. Other than to use OpenSC with GnuPG, the Assuan support is not needed. PAM support allowes you to use a smart card and the opensc PAM module to log into your system. If enabled, the pam module has two flavors: it can compare a key on a smart card to a certificate stored locally, or it can communicate with an LDAP server to check the key and certificate stored on a smart card. The former mode requires only PAM support, the later is only available, if OpenSC is compiled with LDAP and PAM support enabled. Now if your configuration is similar, you can compile the software. $ make $ su root and install the software as root # make install usually opensc is fine without any config file, still you can install it: # cp etc/opensc.conf /etc/opensc.conf # cp etc/scldap.conf /etc/scldap.conf If you have some reason to edit the config file, feel free to do so. But most users are fine without. OpenSC is now fully installed. Have fun. Some usual commands include: $ opensc-tool --list-readers Readers known about: Nr. Driver Name 0 openct Towitoko Chipdrive Micro 1 openct Aladdin eToken PRO 2 openct OpenCT reader (detached) 3 openct OpenCT reader (detached) 4 openct OpenCT reader (detached) You can see, openct claims five slots, but only two are used. This is done to support hotplugging. If you are using OpenCT and PC/SC-Lite, please use this test often to make sure you are using some openct driver directly, and not indirectly via openct. In theory both should work fine, but if you have some problems, please test this. $ opensc-tool --reader 1 --atr 3b:e2:00:ff:c1:10:31:fe:55:c8:02:9c OpenCT can give you the ATR as well. $ opensc-explorer Is a tool to explore the smart card - list directories, change directories, look at files, and so on. If this doesn't work, do not panic. Many cards simply do not support this, they have no "ls" command. Many other tools will still work. Quick start guide to initializing a card ======================================== If opensc and openct are both installed and can see the reader and the card, you might want to start formatting it, creating an pkcs#15 structure, adding a user name and pin, generate a key, create a certificate and use it everywhere. Here is the quick guide. You can add "-v" to all of these commands, to get a more verbose output. Adding "-v" more than once will enable debugging or increase the debugging level. $ pkcs15-init --create-pkcs15 New Security Officer PIN (Optional - press return for no PIN). Please enter Security Officer PIN: Please type again to verify: Unblock Code for New User PIN (Optional - press return for no PIN). Please enter User unblocking PIN (PUK): Please type again to verify: This created an empty pkcs15 structure. You can't do much without it. Also I entered a pin for the security officer, and an unblocking pin. As a general rule, the SO pin is required every time you change the card, but only the user pin is required to use it. $ pkcs15-init --store-pin --auth-id 01 --label "Andreas Jellinghaus" New User PIN. Please enter User PIN: Please type again to verify: Unblock Code for New User PIN (Optional - press return for no PIN). Please enter User unblocking PIN (PUK): Please type again to verify: Security officer PIN required. Please enter Security officer PIN: I created a user with my name on it, so it is easier to see who uses this card. The security officer pin is required as this changes the card. However later to use it, the security officer pin will never work, there is no way for the security officer to get to my key. Also I need to remember my unblocking pin, as only I can reset it, the security officer cannot. $ pkcs15-init --generate-key rsa/1024 --auth-id 01 --key-usage sign,decrypt Security officer PIN required. Please enter Security officer PIN: User PIN required. Please enter User PIN: Security officer PIN required. Please enter Security officer PIN: This created an RSA key that I as User can use. Lets create a new self-signed certificate with it. To do this, we use openssl. $ openssl OpenSSL> engine dynamic -pre SO_PATH:/usr/lib/opensc/engine_pkcs11.so \ -pre ID:pkcs11 -pre LIST_ADD:1 -pre LOAD (dynamic) Dynamic engine loading support [Success]: SO_PATH:/home/aj/opentest/lib/opensc/engine_pkcs11.so [Success]: ID:pkcs11 [Success]: LIST_ADD:1 [Success]: LOAD Loaded: (pkcs11) pkcs11 engine OpenSSL> It is important to enter the whole long command in one single command line. I usually copy&paste the command, to make sure I don't mistype anything. This command loads the opensc engine, so openssl can delegate some work from your computers cpu to the smart card. OpenSSL> req -engine pkcs11 -new -key id_45 -keyform engine -out req.pem -text -x509 Smart card PIN: You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- Country Name (2 letter code) [AU]:. State or Province Name (full name) [Some-State]:. Locality Name (eg, city) []:. Organization Name (eg, company) [Internet Widgits Pty Ltd]:. Organizational Unit Name (eg, section) []:. Common Name (eg, YOUR name) []:Andreas Jellinghaus Email Address []:aj@dungeon.inka.de Please enter the following 'extra' attributes to be sent with your certificate request A challenge password []: An optional company name []: OpenSSL> So now I have a signed certificate. Remove the final "-x509" if you want a certificate signing request only. In that case, send the request to the CA, wait till you get it back, signed, and proceed as normal. Now store the certificate side by side with the key. It is important to save the certificate under the same ID as the key. You can get a list of all keys and their details (including the ID) with: $ pkcs15-tool --list-keys Private RSA Key [Private Key] Com. Flags : 3 Usage : [0x4], sign Access Flags: [0x1D], sensitive, alwaysSensitive, neverExtract, local ModLength : 1024 Key ref : 16 Native : yes Path : 3F005015 Auth ID : 01 ID : 45 So lets store the key: $ pkcs15-init --store-certificate req.pem --auth-id 01 --id 45 --format pem Security officer PIN required. Please enter Security officer PIN: Now we are ready to go. If you want to add more certificates (e.g. the root certificate of the CA that signed your key, or some intermediate certificates in the chain to the root CA) simply put those into pem files, and add them to id 46, 47 and so on.