You are browsing a read-only backup copy of Wikitech. The live site can be found at wikitech.wikimedia.org

Yubikey-SSH: Difference between revisions

From Wikitech-static
Jump to navigation Jump to search
imported>Muehlenhoff
(Initial documentation for Yubikey NEO/PIV/SSH)
 
imported>Ori.livneh
Line 1: Line 1:
Configuring the Yubikey NEO for SSH authentication in the prod cluster:
Configuring the YubiKey NEO for SSH authentication in the prod cluster:


= Installation =
= Installation =
Line 13: Line 13:
= Enabling CCID smartcard mode =
= Enabling CCID smartcard mode =


The smartcard/CCID feature on the Yubikey NEO is disabled by default. You can change that with the following command:
The smartcard/CCID feature on the YubiKey NEO is disabled by default. You can change that with the following command:


  ykpersonalize -m86
  ykpersonalize -m86


(See https://www.yubico.com/2012/12/yubikey-neo-composite-device/ for some more information on the parameter)
A message will be printed to the console, confirming the action. Proceed by removing and re-inserting your YubiKey.


= Securing physical access to the Yubikey =
= Securing physical access to the YubiKey =


When accessing the NEO you need to enter a PIN to prevent access for someone who e.g. stole your Yubikey. If that PIN is entered incorrectly thrice, the Yubikey needs to be unlocked with a PUK.  
When accessing the NEO you need to enter a PIN to prevent access for someone who e.g. stole your YubiKey. If that PIN is entered incorrectly thrice, the YubiKey needs to be unlocked with a PUK.  
If that PUK is also entered incorrectly three time your Yubikey is toast, so make sure to store these in your password manager.
If that PUK is also entered incorrectly three time your YubiKey is toast, so make sure to store these in your password manager.


In addition the NEO uses a management key: It secures access when updating the feature applets running on the Yubikey and protects you from someone backdooring your NEO.
In addition the NEO uses a management key: It secures access when updating the feature applets running on the YubiKey and protects you from someone backdooring your NEO.


The Yubikey uses default values for PIN, PUK and management key, so we need to change all of them:
The YubiKey uses default values for PIN, PUK and management key, so we need to change all of them:


* First the management key (24 chars hexadecimal):
* First the management key (24 chars hexadecimal):


  key=`dd if=/dev/random bs=1 count=24 2>/dev/null | hexdump -v -e '/1 "%02X"'`
  key=`dd if=/dev/random bs=1 count=24 2>/dev/null | hexdump -v -e '/1 "%02X"'`
  yubico-piv-tool -a set-mgm-key -n $key
  yubico-piv-tool -a set-mgm-key -n $key


* Now the PIN (6 digits, 123456 is the shipped default PIN):
* Now the PIN (6 digits, 123456 is the shipped default PIN):


  pin=`dd if=/dev/random bs=1 count=6 2>/dev/null | hexdump -v -e '/1 "%u"'|cut -c1-6`
  pin=`dd if=/dev/random bs=1 count=6 2>/dev/null | hexdump -v -e '/1 "%u"'| cut -c1-6`
  yubico-piv-tool -a change-pin -P 123456 -N $pin
  yubico-piv-tool -a change-pin -P 123456 -N $pin


Line 42: Line 42:
  puk=`dd if=/dev/random bs=1 count=6 2>/dev/null | hexdump -v -e '/1 "%u"'|cut -c1-8`
  puk=`dd if=/dev/random bs=1 count=6 2>/dev/null | hexdump -v -e '/1 "%u"'|cut -c1-8`
  yubico-piv-tool -a change-puk -P 12345678 -N $puk
  yubico-piv-tool -a change-puk -P 12345678 -N $puk
* Finally don't forget to keep the content of $key, $pin and $puk in your password manager.


= Key/certificate creation =
= Key/certificate creation =


First of all generate a new prvate key: (9a is a slot number, for others see the introduction of https://www.yubico.com/wp-content/uploads/2015/04/Yubico-PIV-Management-Tools_v1.0.pdf )
First of all generate a new private key: (9a is a slot number, for others see the introduction of https://www.yubico.com/wp-content/uploads/2015/04/Yubico-PIV-Management-Tools_v1.0.pdf )


   yubico-piv-tool -s 9a -a generate -o public.pem
   yubico-piv-tool -k $key -s 9a -a generate -o public.pem


Generate a self-signed certificate:
Generate a self-signed certificate:
Line 78: Line 80:
  ssh-add -s $OPENSC
  ssh-add -s $OPENSC


to enter the key to the agent.
to enter the key to the agent.
 
= Troubleshooting =
 
If you get the error message that "ssh-add -s" couldn't access the agent, try starting an additional ssh-agent on a terminal. It will use a random new socket and print it on the command line:
 
ssh-agent
export SSH_AUTH_SOCK=what was printed above
ssh-add -S $OPENSC
If it works fine that way, try figuring out what ssh-add uses by default. Maybe gnome-keyring gets in the way.

Revision as of 22:32, 17 November 2015

Configuring the YubiKey NEO for SSH authentication in the prod cluster:

Installation

On Debian / Ubuntu:

apt-get install yubikey-personalization  yubico-piv-tool opensc

On MacOS:

brew install opensc ykpers yubico-piv-tool

Enabling CCID smartcard mode

The smartcard/CCID feature on the YubiKey NEO is disabled by default. You can change that with the following command:

ykpersonalize -m86

A message will be printed to the console, confirming the action. Proceed by removing and re-inserting your YubiKey.

Securing physical access to the YubiKey

When accessing the NEO you need to enter a PIN to prevent access for someone who e.g. stole your YubiKey. If that PIN is entered incorrectly thrice, the YubiKey needs to be unlocked with a PUK. If that PUK is also entered incorrectly three time your YubiKey is toast, so make sure to store these in your password manager.

In addition the NEO uses a management key: It secures access when updating the feature applets running on the YubiKey and protects you from someone backdooring your NEO.

The YubiKey uses default values for PIN, PUK and management key, so we need to change all of them:

  • First the management key (24 chars hexadecimal):
key=`dd if=/dev/random bs=1 count=24 2>/dev/null | hexdump -v -e '/1 "%02X"'`
yubico-piv-tool -a set-mgm-key -n $key
  • Now the PIN (6 digits, 123456 is the shipped default PIN):
pin=`dd if=/dev/random bs=1 count=6 2>/dev/null | hexdump -v -e '/1 "%u"'| cut -c1-6`
yubico-piv-tool -a change-pin -P 123456 -N $pin
  • Finally the PUK (8 digits, with the default 12345678)
puk=`dd if=/dev/random bs=1 count=6 2>/dev/null | hexdump -v -e '/1 "%u"'|cut -c1-8`
yubico-piv-tool -a change-puk -P 12345678 -N $puk
  • Finally don't forget to keep the content of $key, $pin and $puk in your password manager.

Key/certificate creation

First of all generate a new private key: (9a is a slot number, for others see the introduction of https://www.yubico.com/wp-content/uploads/2015/04/Yubico-PIV-Management-Tools_v1.0.pdf )

 yubico-piv-tool -k $key -s 9a -a generate -o public.pem

Generate a self-signed certificate:

 yubico-piv-tool -a verify-pin -P YOUR_PIN -a selfsign-certificate -s 9a -S "/CN=SSH key/" -i public.pem -o cert.pem

Import the certificate:

 yubico-piv-tool -a import-certificate -s 9a -i cert.pem

Generate an SSH pubkey

On Debian/Ubuntu and amd64:

export OPENSC="/usr/lib/x86_64-linux-gnu/pkcs11/opensc-pkcs11.so"
ssh-keygen -D $OPENSC -e

On MacOS X / Brew:

export OPENSC="/usr/local/Cellar/opensc/0.15.0/lib/opensc-pkcs11.so"
ssh-keygen -D $OPENSC -e

Accessing the key

The key is accessed via the PKCS11 interface (which OpenSSH supports):

ssh -I $OPENSC $HOST
Enter PIN for 'PIV_II (PIV Card Holder pin)':

Of course you don't need to enter the PIN all the time, ssh-agent supports PKCS11 as well. Simply run

ssh-add -s $OPENSC

to enter the key to the agent.

Troubleshooting

If you get the error message that "ssh-add -s" couldn't access the agent, try starting an additional ssh-agent on a terminal. It will use a random new socket and print it on the command line:

ssh-agent
export SSH_AUTH_SOCK=what was printed above
ssh-add -S $OPENSC

If it works fine that way, try figuring out what ssh-add uses by default. Maybe gnome-keyring gets in the way.