Smartcard linux

== Scientific Linux 7 ==
These instructions should work on Scientific Linux 7 and all compatible
releases.

Initial configuration requires +root+ access and may require a reboot
of the system for hardware detection.

=== Initial Client Configuration ===
Before your SmartCard will work, the system must be configured to recognize it.

NOTE: You should apply all pending updates to your system.

These steps need to be performed *only once*, and they must be performed within a terminal.

TIP: Your system may already have some or all of these packages installed.

--------------------------------------
sudo yum install pcsc-lite openssh-clients opensc ;
sudo systemctl enable pcscd ;
sudo systemctl restart pcscd ;
--------------------------------------

=== Verify Reader is Supported ===
To make sure you SmartCard reader is known to your system please run the
following command:

TIP: You should unplug your reader and plug it back in at this time
     if it does not appear in the list.

--------------------------------------
opensc-tool --list-readers ;
--------------------------------------

TIP: You may need to restart your computer if your reader does
     not appear in the list.

=== Extract Your Public Key ===
Before the first time you connect you must provide the system admin
with your public key.

To perform these steps you must:

* open a terminal
* insert your PIV-II SmartCard
* enter your PIN when prompted

Enter the following commands into the terminal:

--------------------------------------
pkcs15-tool --read-ssh-key 01 -o $(whoami).pub ;
--------------------------------------

Please provide the output file (+$(whoami).pub+) file to the system admin of
the remote server.


=== Using The Configuration ===
There are two ways to configure SSH to use your SmartCard:

* Single Usage
* Default Usage

==== Single Usage ====
Configuring SSH for Single Usage means you must run a specific command
every time you wish SSH to use your SmartCard.

--------------------------------------
ssh -I /usr/lib64/pkcs11/opensc-pkcs11.so user@host ;
--------------------------------------

==== Default Usage ====
Configuring SSH for Default Usage means SSH will look for your SmartCard
and prompt you automatically.  When your SmartCard is not present you
will see a warning message +'no slots'+ and SSH will continue as normal.
This does not alter the behavior of non-PIV authenticated connections.

===== Configuration =====
You only need to perform this step once

--------------------------------------
mkdir -p ~/.ssh ;
echo 'PKCS11Provider /usr/lib64/pkcs11/opensc-pkcs11.so' >> ~/.ssh/config ;
chmod 700 ~/.ssh ;
chmod 600 ~/.ssh/config ;
--------------------------------------

TIP: You can restrict the +PKCS11Provider+ to be considered only on
     specific hosts following the +ssh_config+ Match syntax. +
     The manual for +ssh_config+ has more details on how this can be
     accomplished.

===== Usage =====
Once you've configured SSH for Default Usage of your SmartCard,
you can just execute SSH as normal.

--------------------------------------
ssh user@host ;
--------------------------------------

=== Additional Diagnostic Commands ===
To gain additional information about your SmartCard you can run the following
commands:

--------------------------------------
pkcs15-tool -c ;
pkcs15-tool -D ;
--------------------------------------