Using eID with existing applications old

Allikas: eid.eesti.ee

Using eID with existing applications

Desktop applications

The ID card base software offers a PKCS#11 interface for ID card and digital ID. Therefore, they can be used in all applications that are able to communicate through this interface. In some situations, all that is needed for adding ID card support to an application is to configure it to use the ID card module instead of or in addition to the existing crypto-device. An example is the sample application of a claims-processing service , where changing the locale of the PKCS#11 module in the DigiDoc library was enough to start using a crypto-stick instead of ID card.

For Windows, ID card base software is also offered by Cryptographic Application Programming Interface[1][2] or CryptoAPI or just a CAPI interface. As it is an interface created and supported by Microsoft itself, some things are smoother in it (like communication with the system certificate repository), so when developing a Windows-only application, using this may be the simplest way and offer more options. Here, we also see the situation that if the application is already talking to the CAPI provider then reconfiguring it is enough to start using the ID card.

As mentioned above, the SafeNet Authentication Client software offered by the crypto-stick manufacturer includes PKCS#11 and CAPI interfaces, which allow the crypto-stick to be used in exactly the same way.

Also, here is a requirement of necessity, i.e. when the desktop application does not support PKCS#11 or CAPI interfaces, using eID documents is most likely difficult and the application should be updated.

Note: It should be kept in mind here that the ID card and the crypto-stick themselves only sign hashes and decrypt data. Other functions, such as creating the container in DDOC format, are left to DigiDoc libraries or other software. In other words, these crypto-devices can be used to perform exactly the operations offered by the interfaces; for additional functionality, the desktop application needs to be updated.

Mail programs

Usage of PKCS#11 interface is very well demonstrated in mail clients offering the option to encrypt and sign messages. Using ID card in widespread mail programs (Outlook, Thunderbird) is a widely discussed topic on the Internet (and more related to end users than to developers); therefore, we will only provide links to configuring guidelines.

Virtual private networks

eID documents are also suitable for authentication into virtual private networks (VPN). As there are many VPN solutions and there are lots of guides for configuring them, we will again provide just some links to configuring guidelines.

Validity confirmation query

Several desktop applications support querying for validity confirmation for certificates read from eID documents. However, there are a few drawbacks related to AS Sertifitseerimiskeskus's OCSP responder:

  • If no separate contract has been made with SK about granting access to a certain IP, validity confirmation queries have to be signed with an access certificate issued by SK. However, if the desktop application does not support signing queries, they cannot be presented.
  • Including the OCSP responder's certificate in the response is optional and SK's responder does not do it. But several applications (like Apache httpd and Microsoft IIS web servers) do not support responses without certificates and therefore they cannot query for validity confirmation certificates.

If the desktop application supports both signing the queries and responses without certificates, validity confirmation queries for eID documents can be made with it.

There is a significant amount of information for the more technically-minded Linux user to be found on the webpage Using the Estonian ID card under Debian (in Estonian).

Logging into Windows with ID card

Logging into a domain

Logging into domains is supported in the ID card base software since version 3.5 and there is no need to install additional components to configure your domain. However, SK does offer system administrators a guide (in Estonian) and a script that enable simpler management of certificates in client computers running Windows Vista, Windows 7 or Windows Server 2008.

It is advisable to use domain logging with the validity certification service that gives out the validity information of authentication certificates; more information on this is on SK's OCSP authentication page.

As an alternative solution, the IDLogin component can be used, which is offered for a licence fee by JaJa Arendus (in Estonian).

Logging into a standalone computer

By default, logging into Windows with a smart card is only possible if the computer belongs to a domain; autonomous computers do not have that option. For adding this functionality to an autonomous computer, the EIDAuthenticate application should be used:

  1. Download installer package from http://www.mysmartlogon.com/products/eidauthenticate.html and run it;
  2. From the Windows Control Panel, choose the newly added option "Smart Card Logon"
    • You can also click "Check online database for known incompatibilities", to make sure the card works with the application. All Estonian ID cards should be compatible.
  3. Click "Use preconfigured card", as ID cards already have the necessary certificates.
  4. Of the two certificates offered, choose the first, personal authentication certificate. The right certificate has been chosen if the sections "Crypto" and "Encryption" are ok (when the signing certificate has been chosen accidentally, both will display an error message).
    • As the personal identification certificate does not have the Extended Key Usage components required by the application, the section "Trust" will display an error message. To bypass this, the respective check should be turned off by clicking "Don't check EKU".
    • If an error message is displayed saying that the certificate is not trusted, it has to be made sure that the certificates of the issuer of the ID card have been installed on the computer (this is especially true in the case of test cards, where the issuer's certificates are not installed with the base software).
  5. After moving to the next page, a user account password will be requested, which is necessary for logging the user in. It is advisable to choose "Launch a test after the completion of this wizard" to make sure the configuration is correct.
    • Although the application will work even when the user does not have a password, this does not make sense, as it is then also possible to log on without an ID card.
  6. After moving on to the next page, the user will be asked for the ID card's PIN1 for testing purposes. If everything goes successfully, configuration has been completed.

In the future, if an ID card that the application recognises is inserted, the additional option "Smart card credential" will appear, which will enable logging into the account associated with the card after PIN1 has been entered.

Attention: EIDAuthenticate only checks the validity of the certificate used for logging in by the start and end dates included in it, i.e. revocation lists and are not checked nor validity confirmation asked.

Logging into Linux with an ID card

Logging into Linux with an ID card can be done using the OpenSC project's PKCS#11 PAM authentication module.[3]

More information can be found from the official documentation, which is what the following is also based on.

Installing

For Debian based distributions, the necessary module can be found from the libpam-pkcs11 package. The module may be accessible through a package manager in other distributions as well. However, if a ready-made package cannot be found, the module has to be built from source code. The code can be found on the official homepage and building and installing is done "as usual":[4]

$ ./configure
$ make
$ make install

Configuration

Package configuration:[4][5]

  1. Create folder /etc/pam_pkcs11/ for configuration.
  2. Copy the sample configuration to that folder and name it pam_pkcs11.conf. In Debian-based distributions, the sample is located at /usr/share/doc/libpam-pkcs11/examples/pam_pkcs11.conf.example.gz (in this case, it definitely has to be unzipped first). In source code, it is located in the etc/ folder.
  3. Create folder /etc/pam_pkcs11/cacerts/ and load into it the certificate issuers' certificates used for logging in. In the case of Estonian ID cards, the issuer is SK and the certificates are available from their homepage.
  4. The package includes the utility pkcs11_make_hash_link (in source code, it is located in the folder tools/), which can be used for easily creating links to certificates using their hashes. This is necessary for finding the right certificate quickly by its hash but still preserving names in a human-readable form.
# pkcs11_make_hash_link /etc/pam_pkcs11/cacerts/
    • In the case of the two test certificates mentioned above, the links are 600c2b9f.0 and ecc5099c.0, respectively.
    • Attention: pkcs11_make_hash_link is faulty and does not put certificate file names into quotation marks. Therefore, the certificates included in the /etc/pam_pkcs11/cacerts/ folder should not contain empty spaces or other special characters.
  1. (Optional) If you wish to avoid requesting revocation lists from the Internet every time a user logs in, they can be downloaded into the computer. However, in this case, you are responsible for renewing them!
    • Create folder /etc/pam_pkcs11/crls/ and load certificate revocation lists into it. Again, the ones by SK are available from their home page.
    • Use the pkcs11_make_hash_link tool for creating the links. The file names of the revocation lists should also not contain empty spaces or other special characters.
  2. Configure /etc/pam_pkcs11/pam_pkcs11.conf. In general, it is well documented and therefore easy to modify. It is very advisable to set the PKCS#11 module's cert_policy value to "ca,signature,crl_auto". This will ensure that the certificate's issuer, PIN and revocation lists will be checked. If you do not want to download revocation lists from the Internet, the last value should be set to crl_offline.

Linking an ID card with a user account

As it is impossible to know from the information contained on the ID card which user of the information system it belongs to, cards have to be linked with user accounts. Several ways for such mapping exist, and it is also possible to create new ones.[6]

The packages and source code come with some sample configurations for finding a user on the basis of the owner of the certificate, its hash or the mail address on it.

In the example below, the user is identified on the basis of the owner of the certificate. This solution does not require renewal when the user's certificate (therefore also its hash) changes and it is better than using just the mail address. The module also has several other, more powerful mapping modules (the LDAP module may be of special interest) but, for the sake of simplicity, these will not be demonstrated here.

  1. Configure /etc/pam_pkcs11/pam_pkcs11.conf:
    1. Set use_mappers value to </tt>subject, null</tt>. Other modules can be added here, but for the example, this is the minimum value. The module null must always be last.
    2. Configure the mapper subject block. Default values should be ok, but they should still be checked.
    3. Configure the mapper null block. This module either always prohibits logging in or always succeeds and returns the default user (e.g. nobody). Again, the default values should be ok.
  2. Create the mapping:
    1. Insert the ID card used for logging in and deploy the pkcs11_inspect application that comes with the PAM module and displays the information necessary for mapping. Of course, this information can be determined independently but this way it is displayed in exactly the way needed for mapping.
    2. Create the mapfile referenced in the mapper subject block, e.g. /etc/pam_pkcs11/subject_mapping. To this, add a line in the form of ... -> <user>, where "..." the information given by pkcs11_inspect is contained and "<user>" card owner's username.
    • Attention: The empty spaces on both sides of "->" are required and should not be left out.
  3. Run the pklogin_finder application that comes with the PAM module. This will display the username corresponding to the inserted card and it helps make sure the mapping was successful.

For example, the subject_mapping would look like this with a test ID card:

# Mapping file for Certificate Subject
# format: Certificate Subject -> login
/C=EE/O=ESTEID/OU=authentication/CN=M\xC3\x84NNIK,MARI-LIIS,47101010033/SN=M\xC3\x84NNIK/GN=MARI-LIIS/serialNumber=47101010033 -> mariliis

Additional help for creating the map can be found in this guide.

PAM configuration

For the module to work, it has to be configured in PAM (Pluggable Authentication Module). Tools for simplifying this are offered by pam-auth-update.pam-auth-update.[7][8]

First, a new file has to be added to the folder /usr/share/pam-configs/ (the name is not important, it can be e.g. "pkcs11") with the following content:

Name: PKCS#11 authentication
Default: no
Priority: 800
Auth-Type: Primary
Auth: sufficient pam_pkcs11.so

Where:

  • Name - module name
  • Default - is the module used by default
  • Priority - used for prioritising modules
  • Auth-Type - module type
  • Auth - the line that will be added to the PAM authentication modules' configuration file

Attention: To avoid being locked out of the computer, you have to log in at another terminal as a root user before continuing. Should something go wrong, that terminal can be used for repairing the mistake or system recovery.

Next, you need to run the command pam-auth-update as a root user. Now a dialogue will be displayed where the PKCS#11 module can be activated (if it is not activated by default already). When "OK" is chosen, the changes will be applied and then it should be possible to log into the computer with an ID card. This can be tested right away with the commands su or sudo.

If something went wrong, the previously opened backup terminal should be used -- this will make it possible to run pam-auth-update again to disable the faulty module.

References

  1. http://msdn.microsoft.com/en-us/library/ms867086.aspx
  2. http://msdn.microsoft.com/en-us/library/windows/desktop/aa380255%28v=vs.85%29.aspx
  3. http://www.opensc-project.org/pam_pkcs11/
  4. 4,0 4,1 http://www.opensc-project.org/doc/pam_pkcs11/pam_pkcs11.html#install
  5. http://www.opensc-project.org/doc/pam_pkcs11/pam_pkcs11.html#HOWTO
  6. http://www.opensc-project.org/doc/pam_pkcs11/pam_pkcs11.html#mappers
  7. pam-auth-update(8) manpage hosted by Hurricane Electric. http://man.he.net/man8/pam-auth-update
  8. http://www.gooze.eu/howto/gnu-linux-smartcard-logon-using-pam-pkcs11/configuring-pam-pkcs11