.. _scpublickey_authentication:

Using Smart Card Public Key Authentication
------------------------------------------

Introduction
~~~~~~~~~~~~

Smart card public key authentication is an advanced version of the
method described in :ref:`publickey_authentication`. It uses the same
basic principle but stores the private key on a smart card, where it can
never be extracted. This section will describe how to configure ThinLinc
to use it.

General Requirements
~~~~~~~~~~~~~~~~~~~~

-  Smart cards with an appropriate PKCS#11 library. The library included
   with ThinLinc requires PKCS#15 compliant smart cards and PC/SC
   libraries on the client system.

Key Generation
~~~~~~~~~~~~~~

The keys on the smart card are generated when the smart card is issued.
How this is done is not covered by this guide.

Server Configuration
~~~~~~~~~~~~~~~~~~~~

To use a smart card with ThinLinc, the public key must be extracted off
the card and associated with a user on the ThinLinc server. The method
for doing this depends on your smart card and your SSH server.

On Linux, with the OpenSSH server and an PKCS#15 compliant smart card,
the tool :command:`pkcs15-tool` (part of the OpenSC suite) is able to
extract the public key.

The first step is identifying the certificate on the card:

.. code:: console

   $ pkcs15-tool --list-certificates
   X.509 Certificate [identification]
           Flags    : 0
           Authority: no
           Path     : 3f0050154331
           ID       : 45

The second step is to extract the key, based on the ID number:

.. code:: console

   $ pkcs15-tool --read-ssh-key 45
   1024 65537 918282501237151981353694684191630174855276113858858644490084487922635
   27407657612671471887563630990149686313179737831148878256058532261207121307761545
   37226554073750496652425001832055579758510787971892507619849564722087378266977930
   9875752082163453335538210518946058646748977963861144645730357512544251473818679
   ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQCCxIx/xtVoDR2qwY4Pym7F6yKmdJsB26MUbbTiGT7o
   6M6G4A2l5Go1kdQRNjOWDJE9HZWToaApSkVprNeiQLeOkbELz2yND2Te/Oyl3u44YeIUImT1v4t7q9jC
   MTpfZ+TpxLf0sd3DAk2So8EBAtUkhib/ugKqfTCqB7WNoHf0Nw==

The second line, starting with ``ssh-rsa``, is the one needed for SSH
version 2 authentication. For instructions on how to associate this key
with a user, see :ref:`publickey_authentication`.

Client Configuration
~~~~~~~~~~~~~~~~~~~~

The ThinLinc client requires no special configuration to use the smart
card.

.. _smartcard_auto:

Automatic Connection
~~~~~~~~~~~~~~~~~~~~

The client is able to automatically connect to the server when a smart
card is inserted (see :ref:`client_security_tab`). It does, however,
require that the user is able to log in using the subject name on the
card. As that is rarely a valid user name, ThinLinc ships with a special
NSS module, called **nss-passwdaliases**, that enables alternate names
for users.

The module is configured by editing the file :file:`/etc/passwdaliases`.
The file is a colon-delimited table of alternate names and their
corresponding user ids. Example::

   givenname=John,sn=Doe,c=us:572

To activate the nss-passwdaliases module, it must be added to the list
of NSS modules for the **passwd** database. This is specified in the
file :file:`/etc/nsswitch.conf`. For example, replace the following
line::

   passwd: files ldap

with this line::

   passwd: files ldap passwdaliases

.. _certalias:

LDAP Automatic Update (tl-ldap-certalias)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

ThinLinc includes the tool :program:`tl-ldap-certalias` that can
automatically update the local databases needed for smart card public
key authentication, provided the system uses the OpenSSH server (or any
SSH server that uses a compatible format and location for authorized
public keys) and standards compliant LDAP servers where users and
certificates are stored.

The :program:`tl-ldap-certalias` command can also perform validation of
certificates it finds in LDAP databases. Read more about this in
:ref:`certalias_validation`.

-  On invocation, a list of all users and matching certificates is
   gathered. How is determined by the |certificate_user_match|
   configuration variable. If |allow_invalid_certificates| is no, only
   matching valid certificates will be gathered.

   .. |certificate_user_match| replace::
      :servconf:`certificate_user_match
      </utils/tl-ldap-certalias/certificate_user_match>`
   .. |allow_invalid_certificates| replace::
      :servconf:`allow_invalid_certificates
      </utils/tl-ldap-certalias/allow_invalid_certificates>`

-  The user's home directory, as well as the :file:`~/.ssh` directory,
   are created if they are required and do not already exist.
   :program:`tl-ldap-certalias` reuses the
   :servconf:`/vsmagent/make_homedir_mode` configuration variable from
   vsmagent for determining the default permissions of newly created
   home directories.

-  Any old public keys added by :program:`tl-ldap-certalias` are removed
   from the :file:`~/.ssh/authorized_keys` file and the keys from the
   current set of certificates are added.

-  The file :file:`/etc/passwdaliases` is updated with a list of subject
   names and user id:s, to allow for login without usernames. See
   :ref:`smartcard_auto` for more information.

.. note::

   It should be noted that any custom entries in
   :file:`~/.ssh/authorized_keys` will be retained, but custom changes
   to :file:`/etc/passwdaliases` will be overwritten each time
   :program:`tl-ldap-certalias` is run.

After deployment, :program:`tl-ldap-certalias` is meant to be run from
cron at regular intervals, for example every 15 minutes. This makes sure
that the ThinLinc system automatically keeps all user certificates
updated. However, please note that if you're using certificate
validation, downloading and parsing certificate revocation lists may
take a long time (up to 5 minutes each). This is mitigated by caching
the data from the CRL:s, but the first run and whenever the CRL needs to
be updated may take a long time. Thus, if you have certificates from a
lot of different certificate authorities, don't run
:program:`tl-ldap-certalias` too often.

Since the default use of this tool is to be run from cron, the default
behaviour is to produces no output other than error messages. If you
want more output from :program:`tl-ldap-certalias`, see options in
:ref:`certalias_cli`.

.. note::

   The root user must able to write to the users' home directories for
   :program:`tl-ldap-certalias` to be able to update the
   :file:`~/.ssh/authorized_keys` files.

.. _certalias_cli:

Command line options
^^^^^^^^^^^^^^^^^^^^

:program:`tl-ldap-certalias` accepts a number of different command line
options that affects how the program interacts with its environment.

.. option:: -v, --verbose

   Turn on program status output to standard output. This is off by
   default.

.. option:: -d, --debug

   Turn on extra debugging putput to standard output. This is off by
   default.

.. option:: -s, --simulate

   Dry run mode. Specifying this option tells
   :program:`tl-ldap-certalias` to avoid writing any changes to disk.
   This is off by default.

.. option:: -h, --help

   Show usage information and exit.

.. _certalias_config:

Configuration
^^^^^^^^^^^^^

:program:`tl-ldap-certalias` uses the
:servconf:`/utils/tl-ldap-certalias` hiveconf folder for configuration
purposes. On a standard ThinLinc installation, it's located in
:file:`/opt/thinlinc/etc/conf.d/tl-ldap-certalias.hconf`. See
:ref:`configuration_tl_ldap_certalias` for details about the available
parameters.

.. _certalias_validation:

Certificate validation
^^^^^^^^^^^^^^^^^^^^^^

:program:`tl-ldap-certalias` can perform validation of certificates
found in LDAP databases by the following methods if
|allow_invalid_certificates| is set to ``yes``:

Certificate validity and expiry dates
   :program:`tl-ldap-certalias` now checks the certificate validity and
   expiry dates and rejects certificates that are not valid yet or have
   expired.

Matching certificate to certificate issuers
   Place the CA certificates you wish to trust certificates from in
   :file:`/opt/thinlinc/etc/ca/`. The CA certificates must be in DER
   form. If :program:`tl-ldap-certalias` finds a certificate with an
   issuer that does not match any of the certificates in
   :file:`/opt/thinlinc/etc/ca/`, the certificate will be considered
   invalid and ignored.

Certificate revocation lists
   :program:`tl-ldap-certalias` searches the certificates it encounter
   for certificate revocation lists (CRL), to make sure that the
   certificate has not been revoked by its issuer. Once downloaded, the
   CRL will be cached until the time for the next scheduled update found
   in the CRL list has passed.

   .. note::

      :program:`tl-ldap-certalias` can only handle CRL lists distributed
      with HTTP.

Validation of certificate signatures.
   :program:`tl-ldap-certalias` can verify that the certificate
   signature is valid and thus assures that the certificate has not been
   tampered with.
