1088 lines
33 KiB
ReStructuredText
1088 lines
33 KiB
ReStructuredText
..
|
|
Copyright 2017 Cedric Mesnil <cslashm@gmail.com>, Ledger SAS
|
|
Licensed under the Apache License, Version 2.0 (the "License");
|
|
you may not use this file except in compliance with the License.
|
|
You may obtain a copy of the License at
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
|
|
..
|
|
------------------------------------------------------------------------
|
|
LaTex substitution Definition
|
|
------------------------------------------------------------------------
|
|
|
|
|
|
|
|
License
|
|
=======
|
|
|
|
Author: Cedric Mesnil <cedric@ledger.fr>
|
|
|
|
License:
|
|
|
|
| Copyright 2017 Cedric Mesnil <cedric@ledger.fr>, Ledger SAS
|
|
|
|
|
| Licensed under the Apache License, Version 2.0 (the "License");
|
|
| you may not use this file except in compliance with the License.
|
|
| You may obtain a copy of the License at
|
|
|
|
|
| http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
|
| Unless required by applicable law or agreed to in writing, software
|
|
| distributed under the License is distributed on an "AS IS" BASIS,
|
|
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
| See the License for the specific language governing permissions and
|
|
| limitations under the License.
|
|
|
|
|
|
|
|
|
|
Introduction
|
|
============
|
|
|
|
GnuPG application for Ledger Blue and Nano S
|
|
|
|
This application implements "The OpenPGP card" specification revision 3.0. This specification is available in doc directory and at https://g10code.com/p-card.html .
|
|
|
|
The application supports:
|
|
|
|
- RSA with key up to 4096 bits
|
|
- ECDSA with secp256k1, secp256r1, brainpool 256r1 and brainpool 256t1 curves
|
|
- EDDSA with Ed25519 curve
|
|
- ECDH with secp256k1, secp256r1, brainpool 256r1, brainpool 256t1 and
|
|
curve25519 curves
|
|
|
|
This release has known missing parts (see also [GPGADD]) :
|
|
|
|
- Ledger Blue support
|
|
- Seed mode ON/OFF via apdu
|
|
|
|
|
|
|
|
How to install GPG Application
|
|
==============================
|
|
|
|
Nano S / Blue
|
|
-------------
|
|
|
|
For both, source and binary installation, use the most recent tag.
|
|
|
|
From Binary
|
|
~~~~~~~~~~~~~
|
|
|
|
Use the "Ledger Manager" Chrome App. See https://www.ledgerwallet.com/apps/manager for details.
|
|
|
|
As the "OpenPGP card" application is not fully compliant with UI and documentation guidelines, the application is in developer section: click on "Show delevopers items" on the bottom right corner to see it.
|
|
|
|
- Launch the Ledger Manager. See `Ledger Manager <https://www.ledgerwallet.com/apps/manager>`_
|
|
and ` <https://ledger.groovehq.com/knowledge_base/topics/ledger-manager>`_
|
|
for details about installing and using the manager;
|
|
- Connect your Nano S or your Blue, enter your PIN, and stay on the
|
|
dashboard;
|
|
- Click on *show developer items* on the bottom right corner;
|
|
- Click on the green bottom arrow icon near the Ledger *Open PGP* logo;
|
|
- Confirm the installation when required on your device by pressing the
|
|
right button above the checkmark;
|
|
- Quit the Ledger Manager
|
|
|
|
|
|
The application is ready to use!
|
|
|
|
|
|
From source
|
|
~~~~~~~~~~~~~
|
|
|
|
Building from sources requires the the Nano S SDK 1.3.1.4 on firmware 1.3.1. See https://github.com/LedgerHQ/nanos-secure-sdk
|
|
|
|
The SDK must be slightly modified:
|
|
|
|
- replace lib_stusb/STM32_USB_Device_Library/Class/CCID/src/usbd_ccid_if.c
|
|
and lib_stusb/STM32_USB_Device_Library/Class/CCID/inc/usbd_ccid_if.h by the
|
|
one provided in sdk/ directory
|
|
- edit script.ld and modify the stack size : STACK_SIZE = 832;
|
|
|
|
|
|
Refer to the SDK documentation for the compiling/loading...
|
|
|
|
System Configuration
|
|
--------------------
|
|
|
|
For Linux and MAC, until version 1.4.27, Ledger CCID interface is not supported
|
|
by default by pcscd and must be manually added
|
|
|
|
For windows....
|
|
|
|
Linux
|
|
~~~~~
|
|
|
|
You have to have to add the NanoS to /etc/libccid_Info.plist
|
|
|
|
In <key>ifdVendorID</key> add the entry <string>0x2C97</string>
|
|
In <key>ifdProductID</key> add the entry <string>0x0001</string>
|
|
In <key>ifdFriendlyName</key> add the entry <string>Ledger Token</string>
|
|
|
|
These 3 entries must be added at the end of each list.
|
|
|
|
MAC
|
|
~~~
|
|
|
|
1. First it is necessary to [disable SIP](https://developer.apple.com/library/mac/documentation/Security/Conceptual/System_Integrity_Protection_Guide/ConfiguringSystemIntegrityProtection/ConfiguringSystemIntegrityProtection.html) That doesn't allow the editing of files in /usr/.
|
|
|
|
2. You have to add the Nano S to /usr/libexec/SmartCardServices/drivers/ifd-ccid.bundle/Contents/Info.plist
|
|
|
|
|
|
In <key>ifdVendorID</key> add the entry <string>0x2C97</string>
|
|
In <key>ifdProductID</key> add the entry <string>0x0001</string>
|
|
In <key>ifdFriendlyName</key> add the entry <string>Ledger Token</string>
|
|
|
|
This 3 entries must be added at the end of each list.
|
|
|
|
3. [Enable SIP](https://developer.apple.com/library/content/documentation/Security/Conceptual/System_Integrity_Protection_Guide/ConfiguringSystemIntegrityProtection/ConfiguringSystemIntegrityProtection.html)
|
|
|
|
Windows
|
|
~~~~~~~
|
|
|
|
TODO
|
|
|
|
|
|
|
|
Nano S OpenPGP Card application explained
|
|
=========================================
|
|
|
|
Menu Overview
|
|
-------------
|
|
|
|
The full menu layout is :
|
|
|
|
|
|
| \ *Device Info*
|
|
| Select Slot
|
|
| \ *Choose:*
|
|
| Slot 1 #+
|
|
| Slot 2
|
|
| Slot 3
|
|
| Set Default
|
|
| Settings
|
|
| Key Template
|
|
| Choose Key...
|
|
| Signature
|
|
| Decryption
|
|
| Authentication
|
|
| Choose Type...
|
|
| RSA 2048
|
|
| RSA 3072
|
|
| RSA 4096
|
|
| NIST P256
|
|
| Brainpool 256R1
|
|
| ED25519
|
|
| Set Template
|
|
| Seed mode
|
|
| \ *<ON|OFF>*
|
|
| Set on
|
|
| Set off
|
|
| PIN mode
|
|
| \ *Choose:*
|
|
| Host
|
|
| On Screen
|
|
| Confirm only #+
|
|
| Trust
|
|
| Reset
|
|
| About
|
|
| \ *OpenPGP Card*
|
|
| \ *(c) Ledger SAS*
|
|
| \ *Spec 3.0*
|
|
| \ *App 1.0.1*
|
|
|
|
| Emphasis entries are not selectable and just provide information.
|
|
| A "**#**" after the entry label means default value on reset.
|
|
| A "**+**" after the entry label means current value.
|
|
|
|
|
|
Device Info
|
|
-------------
|
|
|
|
The *Device Info* provides current user and slot information. The format is:
|
|
|
|
| <User: **name**/ Slot: **n** / Serial: **s** >
|
|
|
|
with:
|
|
|
|
* **name** is the one provided to ``gpg --card-edit``. See [GPGSC].
|
|
* **n** is the current slot, see below.
|
|
* **s** is the 32 bits card serial number. Note that the last three bits always
|
|
encode the current slot value.
|
|
|
|
|
|
Select Slot
|
|
-------------
|
|
|
|
A Slot is a set of
|
|
three key pairs *Signature, Decryption, Authentication* as defined by gnupg
|
|
specification.
|
|
|
|
Usually a GPG card application only manages a single set. Ledger version enhances
|
|
this and allows you to manage three key sets.
|
|
|
|
The *Select Slot* menu allows you to select the slot you want to play with, and
|
|
to set the default slot when the application start.
|
|
|
|
To change the current slot, display the slot you want and select it
|
|
|
|
To change the default slot, first select it, and then select the *Set Default*
|
|
entry.
|
|
|
|
|
|
Settings
|
|
--------
|
|
|
|
Key Template
|
|
~~~~~~~~~~~~
|
|
|
|
A key template is defined by the OpenGPG card application specification. It
|
|
describes the key to be generated with the ``generate`` command in
|
|
``gpg --card-edit``
|
|
|
|
The problem is there is no way with the ``gpg`` command line to easily set
|
|
up the desired template. The menu fixes that.
|
|
|
|
First under *Choose Key* menu, select the one of three keys for which you want to modify
|
|
the template. Then under "Choose Type", select the desired key template.
|
|
Finally select "Set Template" entry to set it.
|
|
|
|
To show the current template use the ``gpg --card-status`` command.
|
|
|
|
|
|
Seed mode
|
|
~~~~~~~~~
|
|
|
|
When generating new keys on NanoS, those keys can be generated randomly
|
|
or in a deterministic way. The deterministic way is specified in [GPGADD].
|
|
The current mode is displayed in the first sub menu. To activate the seeded
|
|
mode select *ON*, to deactivate the seeded mode select *OFF*.
|
|
|
|
When the application starts, the seeded mode is always set to *OFF*
|
|
|
|
|
|
PIN mode
|
|
~~~~~~~~
|
|
|
|
Some operations require the user to enter his PIN code.
|
|
The default PIN values are:
|
|
|
|
- user: ``123456``
|
|
- admin: ``12345678``
|
|
|
|
The PIN entry can be done using four methods, named
|
|
"*Host*", "*On Screen*", "*Confirm only*", "*Trust*".
|
|
|
|
After each mode a *+* or *#* symbol may appear to tell which mode is the current one
|
|
and which one is the default when the application starts.
|
|
The default mode can be changed by first selecting the desired mode and then
|
|
selecting the *Set default" menu. Note that *Trust* can not be set as default mode.
|
|
|
|
|
|
Note that *On Screen*", "*Confirm only*" and "*Trust*" may not work if the
|
|
client application does not support it. In that case the "*Host*" should be
|
|
automatically used by the client in a transparent way.
|
|
|
|
**Host**
|
|
|
|
The PIN is entered on the external computer.
|
|
|
|
|
|
**On Screen**
|
|
|
|
The PIN is entered on the Nano S or Blue screen. For entering the PIN choose the
|
|
next digit by using the left or right button. When the digit you expect is displayed
|
|
select it by pressing both buttons ar the same time
|
|
|
|
.. image:: pin_entry.png
|
|
:align: middle
|
|
|
|
|
|
Once all digits are selected, validate the PIN by selecting the **'V'** (Validate)
|
|
letter
|
|
|
|
.. image:: pin_validate.png
|
|
:align: middle
|
|
|
|
|
|
If you want to change the previous digit select the **'C'** (Cancel) letter.
|
|
|
|
.. image:: pin_cancel.png
|
|
:align: middle
|
|
|
|
|
|
Finnaly if you want to abort the PIN entry, select the **'A'** (Abort) letter.
|
|
|
|
.. image:: pin_abort.png
|
|
:align: middle
|
|
|
|
|
|
**Confirm only**
|
|
|
|
The user is requested, on the NanoS or Blue screen, to confirm
|
|
the PIN validation. The PIN value is not required, the user just has
|
|
to push the *REJECT* or *OK* button on the device.
|
|
|
|
This is the default mode after application installation.
|
|
|
|
.. image:: pin_confirm.png
|
|
:align: middle
|
|
|
|
|
|
**Trust**
|
|
|
|
Act as if the PIN is always validated. This is a dangerous mode which should only be
|
|
used in a highly secure environment.
|
|
|
|
Reset
|
|
~~~~~
|
|
|
|
Selecting the menu will erase all OpenPGP Card Application data and will
|
|
reset the application in its '*just installed*' state.
|
|
|
|
|
|
|
|
Nano S OpenPGP Card application usage
|
|
=====================================
|
|
|
|
|
|
GPG
|
|
---
|
|
|
|
The OpenGPG Card application need at least version 2.1.19 for full support.
|
|
A version prior to 2.1.19 will fail when using ECC.
|
|
|
|
You should test with a test key and make a backup of your
|
|
keyring before starting, except if your are sure about what you do.
|
|
|
|
|
|
Configuration
|
|
~~~~~~~~~~~~~
|
|
|
|
In order to use a Ledger device with gpg it is needed to explicitly setup
|
|
the reader and the delegated PIN support.
|
|
Edit the file ~/.gnupg/scdaemon.conf and add the following lines:
|
|
|
|
| ``reader-port "Ledger Token [Nano S] (0001) 01 00"``
|
|
| ``enable-pinpad-varlen``
|
|
|
|
|
|
If you do not set the ``enable-pinpad-varlen`` option, even if Nano S is
|
|
configured in *On Screen* mode, gpg will keep requesting the PIN on the host.
|
|
|
|
You can check ``the reader-port`` value by running the command line ``pcsc_scan``:
|
|
|
|
| ``$ pcsc_scan ``
|
|
| ``PC/SC device scanner``
|
|
| ``V 1.4.27 (c) 2001-2011, Ludovic Rousseau <ludovic.rousseau@free.fr>``
|
|
| ``Compiled with PC/SC lite version: 1.8.14``
|
|
| ``Using reader plug'n play mechanism``
|
|
| ``Scanning present readers...``
|
|
| ``0: Alcor Micro AU9560 00 00``
|
|
| ``1: Ledger Token [Nano S] (0001) 01 00``
|
|
| ``Reader 0: Alcor Micro AU9560 00 00``
|
|
| ``Card state: Card removed, ``
|
|
| ``Reader 1: Ledger Token [Nano S] (0001) 01 00``
|
|
| ``Card state: Card inserted, ``
|
|
| ``ATR: 3B 00``
|
|
| ``+ TS = 3B --> Direct Convention``
|
|
| ``+ T0 = 00, Y(1): 0000, K: 0 (historical bytes)``
|
|
|
|
|
|
|
|
Get/Set basic information
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The ``gpg --card-status`` command provides default card information. Just after
|
|
installation it should look like this:
|
|
|
|
| ``$ gpg --card-status``
|
|
| ``Reader ...........: Ledger Token [Nano S] (0001) 01 00``
|
|
| ``Application ID ...: D2760001240103002C97AFB114290000``
|
|
| ``Version ..........: 3.0``
|
|
| ``Manufacturer .....: unknown``
|
|
| ``Serial number ....: AFB11429``
|
|
| ``Name of cardholder: [not set]``
|
|
| ``Language prefs ...: [not set]``
|
|
| ``Sex ..............: unspecified``
|
|
| ``URL of public key : [not set]``
|
|
| ``Login data .......: [not set]``
|
|
| ``Signature PIN ....: not forced``
|
|
| ``Key attributes ...: rsa2048 rsa2048 rsa2048``
|
|
| ``Max. PIN lengths .: 12 12 12``
|
|
| ``PIN retry counter : 3 0 3``
|
|
| ``Signature counter : 0``
|
|
| ``Signature key ....: [none]``
|
|
| ``Encryption key....: [none]``
|
|
| ``Authentication key: [none]``
|
|
| ``General key info..: [none]``
|
|
|
|
You can set the user information with the ``gpg --card-edit`` command and
|
|
``name``, ``url``, ``login``, ``lang``, ``sex`` subcommands. For example if you
|
|
want to set up your name:
|
|
|
|
| ``$ gpg --card-edit``
|
|
| ``gpg/card> admin``
|
|
| ``Admin commands are allowed``
|
|
| ````
|
|
| ``gpg/card> name``
|
|
| ``Cardholder's surname: Mesnil``
|
|
| ``Cardholder's given name: Cedric``
|
|
| ````
|
|
| ``gpg/card> sex``
|
|
| ``Sex ((M)ale, (F)emale or space): M``
|
|
| ````
|
|
| ``gpg/card> list``
|
|
| ````
|
|
| ``Reader ...........: Ledger Token [Nano S] (0001) 01 00``
|
|
| ``Application ID ...: D2760001240103002C97AFB114290000``
|
|
| ``Version ..........: 3.0``
|
|
| ``Manufacturer .....: unknown``
|
|
| ``Serial number ....: AFB11429``
|
|
| ``Name of cardholder: Cedric Mesnil``
|
|
| ``Language prefs ...: [not set]``
|
|
| ``Sex ..............: unspecified``
|
|
| ``URL of public key : [not set]``
|
|
| ``Login data .......: [not set]``
|
|
| ``Signature PIN ....: not forced``
|
|
| ``Key attributes ...: rsa2048 rsa2048 rsa2048``
|
|
| ``Max. PIN lengths .: 12 12 12``
|
|
| ``PIN retry counter : 3 0 3``
|
|
| ``Signature counter : 0``
|
|
| ``Signature key ....: [none]``
|
|
| ``Encryption key....: [none]``
|
|
| ``Authentication key: [none]``
|
|
| ``General key info..: [none]``
|
|
|
|
|
|
Notes:
|
|
|
|
* Modifying the user information will prompt you to enter ``User PIN``.
|
|
* Setting user information is not required for using gpg client.
|
|
|
|
|
|
Generate new key pair
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
For generating a new key pair follow those steps:
|
|
|
|
- Select the desired NanoS OpenPGP Card application slot
|
|
- Setup the desired key template for this slot
|
|
- Generate the new key set
|
|
|
|
|
|
**Step 1**
|
|
|
|
Starting from main menu:
|
|
|
|
- Select *Select slot* menu
|
|
- Scroll to desired slot
|
|
- Select it
|
|
- Optionally set it as default by selecting *Set Default* menu
|
|
- Select *Back* to return to main menu.
|
|
|
|
|
|
**Step 2**
|
|
|
|
The default template for each three keys (*signature*, *decryption*,
|
|
*authentication*) is ``RSA 2048``. If you want another kind of key
|
|
you have to set the template before generating keys.
|
|
|
|
!WARNING!: changing the current template of a key automatically erases
|
|
the associated key.
|
|
|
|
Starting from main menu:
|
|
|
|
- Select *Settings* menu
|
|
- Select *Key template* menu
|
|
- Select *Choose Key...* menu (a)
|
|
- Scroll and select which key you want to set the new template for
|
|
- Select *Choose type...* menu
|
|
- Scroll and select among the supported key types and sizes
|
|
- Select *Set template*
|
|
- Repeat this process from (a) if you want to modify another key
|
|
template
|
|
- Select *Back* to return to main menu.
|
|
|
|
|
|
**Step 3**
|
|
|
|
Once the template has been set, it's possible to generate new key pairs
|
|
with ``gpg``.
|
|
|
|
!WARNING!: gpg will generate the three key pairs and
|
|
will overwrite any key already present in the selected slot.
|
|
|
|
Here after is a detailed log of key generation of ECC keys, assuming
|
|
the three key templates are ``NIST P256``.
|
|
|
|
**Edit Card**
|
|
|
|
|
|
| ``$ gpg2 --edit-card``
|
|
| ``Reader ...........: Ledger Token [Nano S] (0001) 01 00``
|
|
| ``Application ID ...: D2760001240103002C97AFB1142B0000``
|
|
| ``Version ..........: 3.0``
|
|
| ``Manufacturer .....: unknown``
|
|
| ``Serial number ....: AFB1142B``
|
|
| ``Name of cardholder: Cedric Mesnil``
|
|
| ``Language prefs ...: [not set]``
|
|
| ``Sex ..............: male``
|
|
| ``URL of public key : [not set]``
|
|
| ``Login data .......: [not set]``
|
|
| ``Signature PIN ....: not forced``
|
|
| ``Key attributes ...: nistp256 nistp256 nistp256``
|
|
| ``Max. PIN lengths .: 12 12 12``
|
|
| ``PIN retry counter : 3 0 3``
|
|
| ``Signature counter : 0``
|
|
| ``Signature key ....: [none]``
|
|
| ``Encryption key....: [none]``
|
|
| ``Authentication key: [none]``
|
|
| ``General key info..: [none]``
|
|
|
|
**Switch to admin mode:**
|
|
|
|
| ``gpg/card>`` *admin*
|
|
| ``Admin commands are allowed``
|
|
|
|
**Request new key generation without backup**
|
|
|
|
| ``gpg/card>`` *generate*
|
|
| ``Make off-card backup of encryption key? (Y/n)`` **n**
|
|
|
|
**Unlock user level ``81``**
|
|
|
|
| ``Please unlock the card``
|
|
| ````
|
|
| ``Number: 2C97 AFB1142B``
|
|
| ``Holder: Cedric Mesnil``
|
|
| ````
|
|
| ``Use the reader's pinpad for input.``
|
|
| `` OK``
|
|
| ``Press any key to continue. ``
|
|
|
|
**Set key validity**
|
|
|
|
| ``Please specify how long the key should be valid.``
|
|
| `` 0 = key does not expire``
|
|
| `` <n> = key expires in n days``
|
|
| `` <n>w = key expires in n weeks``
|
|
| `` <n>m = key expires in n months``
|
|
| `` <n>y = key expires in n years``
|
|
| ``Key is valid for? (0)`` *0*
|
|
| ``Key does not expire at all``
|
|
| ``Is this correct? (y/N)``*y*
|
|
|
|
**Set user ID**
|
|
|
|
| ``GnuPG needs to construct a user ID to identify your key.``
|
|
| ````
|
|
| ``Real name: Cedric Mesnil``
|
|
| ``Email address: cedric@ledger.fr``
|
|
| ``Comment: ``
|
|
| ``You selected this USER-ID:``
|
|
| `` "Cedric Mesnil <cedric@ledger.fr>"``
|
|
| ````
|
|
| ``Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit?`` *O*
|
|
| ````
|
|
| ``You selected this USER-ID:``
|
|
| `` "Cedric Mesnil <cedric@ledger.fr>"``
|
|
|
|
**Unlock admin level ``83``**
|
|
|
|
| ``Please enter the Admin PIN ``
|
|
| ````
|
|
| ``Number: 2C97 AFB1142B``
|
|
| ``Holder: Cedric Mesnil``
|
|
| ````
|
|
| ``Use the reader's pinpad for input.``
|
|
| `` OK``
|
|
| ``Press any key to continue.``
|
|
|
|
**Unlock user level ``82``**
|
|
|
|
| ``Please unlock the card``
|
|
| ````
|
|
| ``Number: 2C97 AFB1142B``
|
|
| ``Holder: Cedric Mesnil``
|
|
| ``Counter: 8``
|
|
| ````
|
|
| ``Use the reader's pinpad for input.``
|
|
| `` OK``
|
|
| ``Press any key to continue.``
|
|
|
|
**Final confirmation**
|
|
|
|
| ``Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit?`` *O*
|
|
| ``gpg: key DF3FA4A33EF00E47 marked as ultimately trusted``
|
|
| ``gpg: revocation certificate stored as '/home/gnuk/.gnupg/openpgp-revocs.d/89F772243C9A3E583CB59AB5DF3FA4A33EF00E47.rev'``
|
|
| ``public and secret key created and signed.``
|
|
|
|
**Get information after key generation**
|
|
|
|
| ``gpg/card> list``
|
|
| ````
|
|
| ``Reader ...........: Ledger Token [Nano S] (0001) 01 00``
|
|
| ``Application ID ...: D2760001240103002C97AFB1142B0000``
|
|
| ``Version ..........: 3.0``
|
|
| ``Manufacturer .....: unknown``
|
|
| ``Serial number ....: AFB1142B``
|
|
| ``Name of cardholder: Cedric Mesnil``
|
|
| ``Language prefs ...: [not set]``
|
|
| ``Sex ..............: male``
|
|
| ``URL of public key : [not set]``
|
|
| ``Login data .......: [not set]``
|
|
| ``Signature PIN ....: not forced``
|
|
| ``Key attributes ...: nistp256 nistp256 nistp256``
|
|
| ``Max. PIN lengths .: 12 12 12``
|
|
| ``PIN retry counter : 3 0 3``
|
|
| ``Signature counter : 12``
|
|
| ``Signature key ....: F844 38BB CA87 F9A7 6830 F002 F8A4 A353 3CBF CAA5``
|
|
| `` created ....: 2017-08-22 15:59:36``
|
|
| ``Encryption key....: B1D3 C9F2 C3C5 87CA 36A7 F02E E137 28E9 13B8 77E1``
|
|
| `` created ....: 2017-08-22 15:59:36``
|
|
| ``Authentication key: F87D EF02 9C38 C43D 41F0 6872 2345 A677 CE9D 8223``
|
|
| `` created ....: 2017-08-22 15:59:36``
|
|
| ``General key info..: pub nistp256/F8A4A3533CBFCAA5 2017-08-22 cedric mesnilCedric Mesnil <cedric@ledger>``
|
|
| ``sec> nistp256/F8A4A3533CBFCAA5 created: 2017-08-22 expires: never ``
|
|
| `` card-no: 2C97 AFB1142B``
|
|
| ``ssb> nistp256/2345A677CE9D8223 created: 2017-08-22 expires: never ``
|
|
| `` card-no: 2C97 AFB1142B``
|
|
| ``ssb> nistp256/E13728E913B877E1 created: 2017-08-22 expires: never ``
|
|
| `` card-no: 2C97 AFB1142B``
|
|
|
|
**Say goodbye
|
|
|
|
| ``gpg/card> quit``**
|
|
|
|
|
|
|
|
At this point it's possible to check that the key has been generated on card with the following command:
|
|
|
|
| ``$ gpg2 --list-secret-keys cedric@ledger``
|
|
| ``gpg: checking the trustdb``
|
|
| ````
|
|
| ``sec> nistp256 2017-08-22 [SC]``
|
|
| `` F84438BBCA87F9A76830F002F8A4A3533CBFCAA5``
|
|
| `` Card serial no. = 2C97 AFB1142B``
|
|
| ``uid [ultimate] cedric mesnilCedric Mesnil <cedric@ledger>``
|
|
| ``ssb> nistp256 2017-08-22 [A]``
|
|
| ``ssb> nistp256 2017-08-22 [E]``
|
|
|
|
|
|
|
|
Moving existing key pair
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
This section shows how to move an existing key onto the Ledger device.
|
|
|
|
The key to transfer here is a RSA 4096 bits key:
|
|
|
|
| ``$ gpg2 --list-secret-keys "RSA 4096"``
|
|
| ``sec rsa4096 2017-04-26 [SC]``
|
|
| `` FB6C6C75FB016635872ED3E49B93CB47F954FB53``
|
|
| ``uid [ultimate] RSA 4096``
|
|
| ``ssb rsa4096 2017-04-26 [E]``
|
|
|
|
|
|
In case of transfer it is not necessary to previously set the template.
|
|
It will be automatically changed.
|
|
When generating a new key, the three keys (*signature*, *decryption*,
|
|
*authentication*)) are automatically generated.
|
|
When transferring existing ones, it is possible to choose which one will be
|
|
moved.
|
|
|
|
**Edit Key**
|
|
|
|
| ``$ gpg2 --edit-key "RSA 4096"``
|
|
| ``gpg (GnuPG) 2.1.19; Copyright (C) 2017 Free Software Foundation, Inc.``
|
|
| ``This is free software: you are free to change and redistribute it.``
|
|
| ``There is NO WARRANTY, to the extent permitted by law.``
|
|
| ````
|
|
| ``Secret key is available.``
|
|
| ````
|
|
| ``sec rsa4096/9B93CB47F954FB53``
|
|
| `` created: 2017-04-26 expires: never usage: SC ``
|
|
| `` trust: ultimate validity: ultimate``
|
|
| ``ssb rsa4096/49EE12B0F5CBDF26``
|
|
| `` created: 2017-04-26 expires: never usage: E ``
|
|
| ``[ultimate] (1). RSA 4096``
|
|
|
|
**Select the key to move, here the *encryption* one.**
|
|
|
|
| ``gpg> `` *key 1*
|
|
| `` ``
|
|
| ``sec rsa4096/9B93CB47F954FB53``
|
|
| `` created: 2017-04-26 expires: never usage: SC ``
|
|
| `` trust: ultimate validity: ultimate``
|
|
| ``ssb* rsa4096/49EE12B0F5CBDF26``
|
|
| `` created: 2017-04-26 expires: never usage: E ``
|
|
| ``[ultimate] (1). RSA 4096``
|
|
|
|
**Move**
|
|
|
|
| ``gpg> `` **keytocard**
|
|
| ``Please select where to store the key:``
|
|
| `` (2) Encryption key``
|
|
| ``Your selection?`` *2*
|
|
|
|
**Unlock admin level ``83``**
|
|
|
|
| ``Please enter the Admin PIN``
|
|
| ````
|
|
| ``Number: 2C97 1D49B409``
|
|
| ``Holder: ``
|
|
| ````
|
|
| ``Use the reader's pinpad for input.``
|
|
| `` OK``
|
|
| ``Press any key to continue.``
|
|
|
|
**Unlock admin level ``83`` (maybe twice....)**
|
|
|
|
| ``Please enter the Admin PIN``
|
|
| ````
|
|
| ``Number: 2C97 1D49B409``
|
|
| ``Holder: ``
|
|
| ````
|
|
| ``Use the reader's pinpad for input.``
|
|
| `` OK``
|
|
| ``Press any key to continue.``
|
|
|
|
| ``sec rsa4096/9B93CB47F954FB53``
|
|
| `` created: 2017-04-26 expires: never usage: SC ``
|
|
| `` trust: ultimate validity: ultimate``
|
|
| ``ssb* rsa4096/49EE12B0F5CBDF26``
|
|
| `` created: 2017-04-26 expires: never usage: E ``
|
|
| ``[ultimate] (1). RSA 4096``
|
|
|
|
**Say goobye with saving!**
|
|
|
|
| ``gpg> `` *save*
|
|
|
|
**check**
|
|
|
|
| ``$ gpg2 --edit-keys cedric``
|
|
| ``gpg: error reading key: No public key``
|
|
| ``gnuk@Lulu:~$ /opt/gnupg2.1.19/bin/gpg2 --edit-key "RSA 4096"``
|
|
| ``gpg (GnuPG) 2.1.19; Copyright (C) 2017 Free Software Foundation, Inc.``
|
|
| ``This is free software: you are free to change and redistribute it.``
|
|
| ``There is NO WARRANTY, to the extent permitted by law.``
|
|
| ````
|
|
| ``Secret key is available.``
|
|
| ````
|
|
| ``sec rsa4096/9B93CB47F954FB53``
|
|
| `` created: 2017-04-26 expires: never usage: SC ``
|
|
| `` trust: ultimate validity: ultimate``
|
|
| ``ssb rsa4096/49EE12B0F5CBDF26``
|
|
| `` created: 2017-04-26 expires: never usage: E ``
|
|
| `` card-no: 2C97 7BB895B9``
|
|
| ``[ultimate] (1). RSA 4096``
|
|
| ````
|
|
| ``gpg> `` *quit*
|
|
|
|
|
|
The encryption key is now associated with a card.
|
|
|
|
Decrypting and Signing
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
Decrypting and Signing will act exactly the same way as if keys were not on
|
|
the card. The only difference is ``gpg`` will request the PIN code instead
|
|
of the passphrase.
|
|
|
|
|
|
SSH
|
|
---
|
|
|
|
|
|
Overview
|
|
~~~~~~~~
|
|
|
|
In order to use gpg for SSH authentication, an "authentication" is needed.
|
|
There are two solutions for that, either generate one on the device
|
|
or add an authentication sub-key to your existing master gpg key.
|
|
|
|
Once done, it is necessary to configure ssh to point to the right key and
|
|
delegate the authentication to *gpg-ssg-agent* instead of *ssh-agent*.
|
|
|
|
|
|
Generate new key on device
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The important thing to keep in mind here is there is no way to tell gpg to
|
|
only generate the authentication key. So generating this key will also
|
|
generate the two other under a new identity and will erase existing keys
|
|
on the current slot on the device.
|
|
|
|
Nevertheless, if you want to use a different identity for ssh login, you can use
|
|
another slot on the device. See `Nano S OpenPGP Card application explained`_
|
|
and `Generate new key pair`_.
|
|
|
|
|
|
Add sub-key
|
|
~~~~~~~~~~~
|
|
|
|
**Edit pgp key set**
|
|
|
|
| ``$ gpg --expert --edit-key cedric``
|
|
| ``gpg (GnuPG) 2.1.15; Copyright (C) 2016 Free Software Foundation, Inc.``
|
|
| ``This is free software: you are free to change and redistribute it.``
|
|
| ``There is NO WARRANTY, to the extent permitted by law.``
|
|
|
|
| ``Secret key is available.``
|
|
|
|
| ``sec rsa2048/831415DA94A9A15C``
|
|
| `` created: 2017-08-25 expires: never usage: SC ``
|
|
| `` trust: ultimate validity: ultimate``
|
|
| ``ssb rsa2048/8E95F2999EEC38C4``
|
|
| `` created: 2017-08-25 expires: never usage: E ``
|
|
| ``[ultimate] (1). cedric``
|
|
|
|
**Add sub key**
|
|
|
|
| ``gpg> *addkey*``
|
|
|
|
| ``Please select what kind of key you want:``
|
|
| `` (3) DSA (sign only)``
|
|
| `` (4) RSA (sign only)``
|
|
| `` (5) Elgamal (encrypt only)``
|
|
| `` (6) RSA (encrypt only)``
|
|
| `` (7) DSA (set your own capabilities)``
|
|
| `` (8) RSA (set your own capabilities)``
|
|
| `` (10) ECC (sign only)``
|
|
| `` (11) ECC (set your own capabilities)``
|
|
| `` (12) ECC (encrypt only)``
|
|
| `` (13) Existing key``
|
|
| ``Your selection? 8``
|
|
|
|
**Toggle sign/encrypt OFF, Toggle authentication ON**
|
|
|
|
| ``Possible actions for a RSA key: Sign Encrypt Authenticate ``
|
|
| ``Current allowed actions: Sign Encrypt ``
|
|
|
|
| `` (S) Toggle the sign capability``
|
|
| `` (E) Toggle the encrypt capability``
|
|
| `` (A) Toggle the authenticate capability``
|
|
| `` (Q) Finished``
|
|
|
|
| ``Your selection?`` *S*
|
|
|
|
| ``Possible actions for a RSA key: Sign Encrypt Authenticate ``
|
|
| ``Current allowed actions: Encrypt ``
|
|
|
|
| `` (S) Toggle the sign capability``
|
|
| `` (E) Toggle the encrypt capability``
|
|
| `` (A) Toggle the authenticate capability``
|
|
| `` (Q) Finished``
|
|
|
|
| ``Your selection?`` *E*
|
|
|
|
| ``Possible actions for a RSA key: Sign Encrypt Authenticate ``
|
|
| ``Current allowed actions: ``
|
|
|
|
| `` (S) Toggle the sign capability``
|
|
| `` (E) Toggle the encrypt capability``
|
|
| `` (A) Toggle the authenticate capability``
|
|
| `` (Q) Finished``
|
|
|
|
| ``Your selection?`` *A*
|
|
|
|
| ``Possible actions for a RSA key: Sign Encrypt Authenticate ``
|
|
| ``Current allowed actions: Authenticate ``
|
|
|
|
| `` (S) Toggle the sign capability``
|
|
| `` (E) Toggle the encrypt capability``
|
|
| `` (A) Toggle the authenticate capability``
|
|
| `` (Q) Finished``
|
|
|
|
| ``Your selection? Q``
|
|
|
|
**Set key options**
|
|
|
|
| ``RSA keys may be between 1024 and 4096 bits long.``
|
|
| ``What keysize do you want? (2048)`` *2048*
|
|
| ``Requested keysize is 2048 bits``
|
|
| ``Please specify how long the key should be valid.``
|
|
| `` 0 = key does not expire``
|
|
| `` <n> = key expires in n days``
|
|
| `` <n>w = key expires in n weeks``
|
|
| `` <n>m = key expires in n months``
|
|
| `` <n>y = key expires in n years``
|
|
| ``Key is valid for? (0)`` *0*
|
|
| ``Key does not expire at all``
|
|
| ``Is this correct? (y/N)`` *y*
|
|
| ``Really create? (y/N)`` *y*
|
|
| ``We need to generate a lot of random bytes. It is a good idea to perform``
|
|
| ``some other action (type on the keyboard, move the mouse, utilize the``
|
|
| ``disks) during the prime generation; this gives the random number``
|
|
| ``generator a better chance to gain enough entropy.``
|
|
|
|
| ``sec rsa2048/831415DA94A9A15C``
|
|
| `` created: 2017-08-25 expires: never usage: SC ``
|
|
| `` trust: ultimate validity: ultimate``
|
|
| ``ssb rsa2048/8E95F2999EEC38C4``
|
|
| `` created: 2017-08-25 expires: never usage: E ``
|
|
| ``ssb rsa2048/C20B90E12F68F035``
|
|
| `` created: 2017-08-28 expires: never usage: A ``
|
|
| ``[ultimate] (1). cedric``
|
|
|
|
**Select the key and move it**
|
|
|
|
| ``gpg> key`` *2*
|
|
| ````
|
|
| ``sec rsa2048/831415DA94A9A15C``
|
|
| `` created: 2017-08-25 expires: never usage: SC ``
|
|
| `` trust: ultimate validity: ultimate``
|
|
| ``ssb rsa2048/8E95F2999EEC38C4``
|
|
| `` created: 2017-08-25 expires: never usage: E ``
|
|
| ``ssb* rsa2048/C20B90E12F68F035``
|
|
| `` created: 2017-08-28 expires: never usage: A ``
|
|
| ``[ultimate] (1). cedric``
|
|
| ````
|
|
| ``gpg>`` *keytocard*
|
|
| ``Please select where to store the key:``
|
|
| `` (3) Authentication key``
|
|
| ``Your selection?`` *3*
|
|
| `` ``
|
|
| ``sec rsa2048/831415DA94A9A15C``
|
|
| `` created: 2017-08-25 expires: never usage: SC ``
|
|
| `` trust: ultimate validity: ultimate``
|
|
| ``ssb rsa2048/8E95F2999EEC38C4``
|
|
| `` created: 2017-08-25 expires: never usage: E ``
|
|
| ``ssb* rsa2048/C20B90E12F68F035``
|
|
| `` created: 2017-08-28 expires: never usage: A ``
|
|
| ``[ultimate] (1). cedric``
|
|
|
|
|
|
**Save and Quit**
|
|
|
|
| ``gpg>`` save
|
|
| ``$ ``
|
|
|
|
|
|
|
|
|
|
Configure SSH and GPG
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
First, tell gpg-agent to enable ssh-auth feature by adding the following line
|
|
to your .gpg-agent.conf:
|
|
|
|
``enable-ssh-support``
|
|
|
|
Starting with gpg2 it necessary to add some configuration options to make the *pinentry*
|
|
work properly. Add the following line to ~/.bashrc file:
|
|
|
|
| ``export SSH_AUTH_SOCK=`gpgconf --list-dirs agent-ssh-socket` ``
|
|
| ``export GPG_TTY=`tty` ``
|
|
| ``gpgconf --launch gpg-agent ``
|
|
|
|
|
|
It may be also necessary to setup the loopback pinentry options.
|
|
|
|
Add the following line to your ~/.gnupg/gpg-agent.conf:
|
|
|
|
``allow-loopback-pinentry``
|
|
|
|
And add the following line to your ~/.gnupg/gpg.conf:
|
|
|
|
``pinentry-mode loopback``
|
|
|
|
|
|
Then export your authentication public key. First execute the
|
|
``gpg -k --with-subkey-fingerprint --with-keygrip cedric`` command.
|
|
|
|
|
|
| ``pub rsa2048 2017-08-25 [SC]``
|
|
| `` 7886147C4C2E5CE2A4B1546C831415DA94A9A15C``
|
|
| `` Keygrip = DE2B63C13AB92EBD2D05C1021A9DAA2D40ECB564``
|
|
| ``uid [ultimate] cedric``
|
|
| ``sub rsa2048 2017-08-25 [E]``
|
|
| `` 789E56872A0D9A5AC8AF9C2F8E95F2999EEC38C4``
|
|
| `` Keygrip = 9D7C2EF8D84E3B31371A09DFD9A4B3EF72AB4ACE``
|
|
| ``sub rsa2048 2017-08-28 [A]``
|
|
| `` 2D0E4FFFAA448AA2770C7F02C20B90E12F68F035``
|
|
| `` Keygrip = 6D60CB58D9D66EE09804E7FE460E865A91F5E41A``
|
|
|
|
Add the keygrip of the authentication key, the one identified by ``[A]``,
|
|
to .gnupg/sshcontrol file:
|
|
|
|
| ``$ echo 6D60CB58D9D66EE09804E7FE460E865A91F5E41A > .gnupg/sshcontrol``
|
|
|
|
Export your authentication key, identifier by its fingerprint, in a SSH compliant format.
|
|
|
|
| ``$ gpg --export-ssh-key 2D0E4FFFAA448AA2770C7F02C20B90E12F68F035``
|
|
| ``ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDCIARKh0IZTHld+I6oA8nwrgnCUQE8f``
|
|
| ``7X3pmI4ZwryT52fKhpcsQJsd3krodXrM//LiK8+m2ZRMneJ9iGlqqE7SCyZkNBj1GUm9s``
|
|
| ``rK3Q5eoR6nU0s+sq17b/FAtQWHBJTqqaOtyA33hFj5twUtWZ6rokX9cNZrD1ne8kRVHDe``
|
|
| ``3uEBsaY5PR1Tuko/GwywLyZu0SwfEobl/RPjL7P8rUSc7DTHpQMw8fjJFb4BNvIHAlaVC``
|
|
| ``5FwZwkuogygaJdN/44MayHFmOZmzx9CAgYgLpTzen35+CcyhlqCqi+HjNlnHL2DDWd4iR``
|
|
| ``d3Y6pY8LjS3xQkECc3Bhedptp17D+H9AVJt openpgp:0x2F68F035``
|
|
|
|
Finaly copy the above export (``ssh-rsa AAAAB...Jt openpgp:0x2F68F035``) into the
|
|
~/.ssh/authorized_keys file on your remote server.
|
|
|
|
|
|
Now, if everything is correctly setup and running, an ``ssh-add -l`` should show your key:
|
|
|
|
| ``$ ssh-add -l``
|
|
| ``2048 SHA256:sLCzsoi5GAG2kJkG6hSp8gTLPxSvo/zNtsks2kQ7vTU cardno:2C979421A9E1 (RSA)``
|
|
| ``2048 SHA256:sLCzsoi5GAG2kJkG6hSp8gTLPxSvo/zNtsks2kQ7vTU (none) (RSA)``
|
|
|
|
And you should be able to ssh to your remote server with your gpg key!
|
|
|
|
|
|
Trouble/FAQ
|
|
-----------
|
|
|
|
**Q:** pinentry failed with a strange canceled message:
|
|
|
|
**R:** there is some problem with gpg2 and pinentry-gnome3. You may update your system
|
|
to use pinentry-gtk-2. Under Ubuntu-like OS, use ``update-alternatives --config pinentry``
|
|
|
|
| ````
|
|
|
|
**Q:** gpg-connection agent failed
|
|
|
|
**R:** check that you don't have multiple running agents. After setting-up all SSH stuff, try to fully
|
|
logout/login
|
|
|
|
| ````
|
|
|
|
**Q:** It does not work at all, HELP ME!!!
|
|
|
|
**R** Please keep calm and do not cry.
|
|
Add the following option to ~/.gnupg/gpg-agent.conf
|
|
|
|
| ``debug-level guru``
|
|
| ``log-file /tmp/gpgagent.log``
|
|
|
|
Add the follwing option to ~/.gnupg/scdaemon.conf
|
|
|
|
| ``log-file /tmp/scd.log``
|
|
| ``debug-level guru``
|
|
| ``debug-all``
|
|
|
|
Make a nice issue report under github providing log and and command line you run.
|
|
**!*WARNING*!** : this may reveal confidential information such as key values. Do your log with a test key.
|
|
|
|
|
|
Annexes
|
|
=======
|
|
|
|
References
|
|
----------
|
|
|
|
* [GPG] *The GNU Privacy Guard*, https://gnupg.org/
|
|
* [GPGSC] *The GnuPG Smartcard HOWTO*, https://gnupg.org/howtos/card-howto/en/smartcard-howto.html
|
|
* [G10CODE] *The OpenPGP card application*, https://g10code.com/p-card.html
|
|
* [GPGADD] *The OpenPGP card application add-on*, https://github.com/LedgerHQ/blue-app-openpgp-card/blob/master/doc/gpgcard3.0-addon.rst
|