# Quick Start with OpenSC

If you haven't already, please first take a look at our OverView page, the OperatingSystems page and the CompilingInstalling page. For the rest of this document we assume you have installed OpenSC. We will show you how you can test if it works, and what you can do with it.

Please note that OpenSC 0.10 does not include the pam module and the openssl engine any more. We suggest you install libp11 and engine_pkcs11 and if you want to login with your smart card or crypto token, you might want to install either pam_p11 (a simple authentication module) or pam_pkcs11 (a full featured authentication module).

Before we start a word of warning: these experiments can destroy your card (e.g. if we have a bug. there is _NO WARRANTY_ on opensc of any kind). Also be sure to make notes of everything you do, for example the pin and puk and so-pin and so-puk you set, as it is for example not possible to erase some cards.

But lets start. First test if OpenSC works: check if your smart card reader is found:

    $ 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, those slots can be filled later by additional readers you plugin via usb.

Next test is to see if your card is found. Every card has a so called ATR ("Answer to reset"), a hex string used for identifying the card type.

    $ opensc-tool --reader 0 --atr
    3b:e2:00:ff:c1:10:31:fe:55:c8:02:9c

Lets see if that card is supported by OpenSC. If so, we should know the name of the card:

    $ opensc-tool --reader 0 --name
    Cryptoflex 32K e-gate

OpenSC has a small low level tool for exploring your smart card. This is useful if you have a new card and want to look at it, or check some details.

    $ opensc-explorer

However opensc-explorer only works with known cards and even then: some cards don't have then required functionality, for example no "ls" command.

# Quick start guide to initializing a blank card

The best way to use all features of OpenSC is to start with a blank card and initialize it with OpenSC. Make sure your vendor sold you a real blank card, many vendors also have pre-initialized cards, and those only work with the vendors software, but not or only limited with OpenSC.

Warning: before writing any data on the token please read the smartcard os specific wiki pages as some smartcards cannot be deleted once initialized.

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.

First you need to create the basic structure. At this step you are asked to enter a "security office" pin. Only with this pin you can alter the card, but that pin is not needed to use the keys.

    $ 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:

Next step is to create a user and a pin. That pin is needed for using the keys we will create later.

    $ 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:

Now create a key. Both pins are needed for this.

    $ pkcs15-init --generate-key rsa/1024 --auth-id 01
    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:

If engine_pkcs11 is installed we can use openssl to create a self signed certificate.

    $ openssl
    OpenSSL> engine dynamic -pre SO_PATH:/usr/lib/opensc/engine_pkcs11.so \
    	-pre ID:pkcs11 -pre LIST_ADD:1 -pre LOAD \
            -pre MODULE_PATH:opensc-pkcs11.so
    (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
    SmartCard 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.

For more details on the openssl engine, please see the engine pkcs11 documentation.

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.