coelner/gnuk
1
0
Fork 0
mirror of https://salsa.debian.org/gnuk-team/gnuk/gnuk.git synced 2024-09-19 18:30:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation for Gnuk 2.

Browse Source 
Signed-off-by: NIIBE Yutaka <gniibe@fsij.org>
This commit is contained in:
NIIBE Yutaka 2024-09-04 10:49:49 +09:00
parent de9652726b
commit 628aabd991
No known key found for this signature in database
GPG Key ID: 640114AF89DE6054
11 changed files with 223 additions and 575 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
doc/development.rst
View File

@ -31,9 +31,6 @@ GNU Toolchain
You need GNU toolchain and newlib for 'arm-none-eabi' target.
In Debian, we can just apt-get packages of: gcc-arm-none-eabi, binutils-arm-none-eabi, gdb-arm-none-eabi and libnewlib-arm-none-eabi.
For other distributiions, there is "gcc-arm-embedded" project. See:
https://launchpad.net/gcc-arm-embedded/
We are using "-O3 -Os" for compiler option.

462
doc/generating-key.rst
View File

@ -1,337 +1,26 @@
====================
Generating key pairs
====================
In this section, we describe how to generate 2048-bit RSA keys.
You would like to use newer ECC keys instead of RSA keys. It is also described.
Key length of RSA
=================
In 2005, NIST (National Institute of Standards and Technology, USA)
issued the first revision of NIST Special Publication 800-57,
"Recommendation for Key Management".
In 800-57, NIST advises that 1024-bit RSA keys will no longer be
viable after 2010 and advises moving to 2048-bit RSA keys. NIST
advises that 2048-bit keys should be viable until 2030.
As of 2016, GnuPG's default for generating RSA key is 2048-bit.
Some people have preference on RSA 4096-bit keys, considering "longer is better".
However, "longer is better" is not always true. When it's long, it
requires more computational resource, memory, and storage. Further,
it consumes more power for nomal usages. These days, many people has
enough computational resource, that would be true, but less is better
for power consumption, isn't it?
For security, the key length is just a single factor. We had and will have
algorithm issues, too. It is true that it's difficult to update
our public keys, but this problem wouldn't be solved by just having
longer keys.
We deliberately recommend use of RSA 2048-bit keys for Gnuk,
considering device computation power and host software constraints.
Thus, the key size is 2048-bit in the examples below.
When/If your environment allows use of newer ECC keys, newer ECC keys are recommended.
Generating RSA keys on host PC
==============================
Here is the example session to generate main key and a subkey for encryption.
I invoke GnuPG with ``--quick-gen-key`` option. ::
$ gpg --quick-gen-key "Niibe Yutaka <gniibe@fsij.org>"
About to create a key for:
"Niibe Yutaka <gniibe@fsij.org>"
Continue? (Y/n) y
It askes passphrase for this **key on host PC**.
Note that this is a passphrase for the key on host PC.
It is different thing to the passphrase of Gnuk Token.
We enter two same inputs two times
(once for passphrase input, and another for confirmation),
<PASSWORD-KEY-ON-PC>.
Then, GnuPG generate keys. It takes some time. ::
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.
gpg: key 76A9392B02CD15D1 marked as ultimately trusted
gpg: revocation certificate stored as '/home/gniibe.gnupg/openpgp-revocs.d/36CE0B8408CFE5CD07F94ACF76A9392B02CD15D1.rev'
public and secret key created and signed.
gpg: checking the trustdb
gpg: marginals needed: 3 completes needed: 1 trust model: pgp
gpg: depth: 0 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 1u
pub rsa2048 2016-06-20 [S]
36CE0B8408CFE5CD07F94ACF76A9392B02CD15D1
uid [ultimate] Niibe Yutaka <gniibe@fsij.org>
sub rsa2048 2016-06-20 []
Done.
Then, we create authentication subkey.
Authentication subkey is not that common,
but very useful (for SSH authentication).
As it is not that common, we need ``--expert`` option for GnuPG. ::
gpg (GnuPG) 2.1.13; 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/76A9392B02CD15D1
created: 2016-06-20 expires: never usage: SC
trust: ultimate validity: ultimate
ssb rsa2048/4BD1EB26F0E607E6
created: 2016-06-20 expires: never usage: E
[ultimate] (1). Niibe Yutaka <gniibe@fsij.org>
gpg>
Here, it displays that there are main key and a subkey.
It prompts sub-command with ``gpg>`` .
Here, we enter ``addkey`` sub-command.
gpg> addkey
GnuPG asks kind of key. We select ``RSA (set your own capabilities)``. ::
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
And select ``Authenticate`` for the capabilities for this key.
Initially, it's ``Sign`` and ``Encrypt``.
I need to deselect ``Sign`` and ``Encrypt``, and select ``Authenticate``.
To do that, I enter ``s``, ``e``, and ``a``. ::
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
OK, we set the capability of ``Authenticate``.
We enter ``q`` to finish setting capabilities. ::
Your selection? q
GnuPG asks bitsize and expiration, we enter 2048 for bitsize and no expiration.
Then, we confirm that we really create the key. ::
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (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
Then, it askes the passphrase, it is the passphrase of **key on host PC**.
It's the one we entered above as <PASSWORD-KEY-ON-PC>.
Then, GnuPG generate the key. ::
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/76A9392B02CD15D1
created: 2016-06-20 expires: never usage: SC
trust: ultimate validity: ultimate
ssb rsa2048/4BD1EB26F0E607E6
created: 2016-06-20 expires: never usage: E
ssb rsa2048/F3BA52C64012198D
created: 2016-06-20 expires: never usage: A
[ultimate] (1). Niibe Yutaka <gniibe@fsij.org>
gpg>
We save the key (to the storage of the host PC). ::
gpg> save
$
Now, we have three keys (one primary key for signature and certification,
subkey for encryption, and another subkey for authentication).
Publishing public key
=====================
We make a file for the public key by ``--export`` option of GnuPG. ::
$ gpg --armor --output <YOUR-KEY>.asc --export <YOUR-KEY-ID>
We can publish the file by web server. Or we can publish the key
to a keyserver, by invoking GnuPG with ``--send-keys`` option. ::
$ gpg --keyserver pool.sks-keyservers.net --send-keys <YOUR-KEY-ID>
Here, pool.sks-keyservers.net is a keyserver, which is widely used.
Backup the private key
======================
There are some ways to back up private key, such that backup .gnupg
directory entirely, or use of paperkey, etc.
Here, we describe backup by ASCII file.
ASCII file is good, because it has less risk on transfer.
Binary file has a risk to be modified on transfer.
Note that the key on host PC is protected by passphrase (which
is <PASSWORD-KEY-ON-PC> in the example above). Using the key
from the backup needs this passphrase. It is common that
people will forget passphrase for backup. Never forget it.
You have been warned.
To make ASCII backup for private key,
invokde GnuPG with ``--armor`` option and ``--export-secret-keys``
specifying the key identifier. ::
$ gpg --armor --output <YOUR-SECRET>.asc --export-secret-keys <YOUR-KEY-ID>
From the backup,
we can recover privet key by invoking GnuPG with ``--import`` option. ::
$ gpg --import <YOUR-SECRET>.asc
===============================
Generating keys on your host PC
===============================
In this section, we describe how to generate ECC keys.
Generating ECC keys on host PC
==============================
Here is an example session log to create newer ECC keys. You need
libgcrypt 1.7 or newer and GnuPG 2.1.8 or newer.
Here is an example session log to create newer ECC keys.
Next, we invoke gpg frontend with ``--expert`` and ``--full-gen-key`` option. ::
Firstly, we invoke gpg frontend with ``--quick-gen-key`` option, specifying a user ID. ::
$ gpg --expert --full-gen-key
gpg (GnuPG) 2.1.13; 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.
$ gpg --quick-gen-key "Kunisada Chuji <chuji@gniibe.org>" default
Then, we input ``9`` to select ECC primary key and ECC encryption subkey. ::
Please select what kind of key you want:
(1) RSA and RSA (default)
(2) DSA and Elgamal
(3) DSA (sign only)
(4) RSA (sign only)
(7) DSA (set your own capabilities)
(8) RSA (set your own capabilities)
(9) ECC and ECC
(10) ECC (sign only)
(11) ECC (set your own capabilities)
Your selection? 9
It askes passphrase for this **key on host PC** (usually, by pop-up
window). Note that this is a passphrase for the key on host PC. It
is different thing to the passphrase of Gnuk Token. We enter two same
inputs two times (once for passphrase input, and another for
confirmation), <PASSWORD-KEY-ON-PC>.
Next is the important selection. We input ``1`` to select "Curve25519". ::
Please select which elliptic curve you want:
(1) Curve 25519
(2) NIST P-256
(3) NIST P-384
(4) NIST P-521
(5) Brainpool P-256
(6) Brainpool P-384
(7) Brainpool P-512
(8) secp256k1
Your selection? 1
You may see WARNING (it depends on version of GnuPG) and may been asked. Since it is what you want, please answer with 'y'. ::
gpg: WARNING: Curve25519 is not yet part of the OpenPGP standard.
Use this curve anyway? (y/N) y
It asks about expiration of key. ::
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)
Key does not expire at all
Is this correct? (y/N) y
Then, it asks about a user ID. ::
GnuPG needs to construct a user ID to identify your key.
Real name: Kunisada Chuji
Email address: chuji@gniibe.org
Comment:
You selected this USER-ID:
"Kunisada Chuji <chuji@gniibe.org>"
Lastly, it asks confirmation. ::
Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o
Then, it goes like this. ::
Then, GnuPG generates keys (one primary key and a subkey). It emits
message about random bytes, but it soon finishes. ::
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
@ -341,46 +30,36 @@ Then, it goes like this. ::
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.
It asks the passphrase for keys by pop-up window, and then, finishes. ::
gpg: key 17174C1A7C406DB5 marked as ultimately trusted
gpg: revocation certificate stored as '/home/gniibe.gnupg/openpgp-revocs.d/1719874a4fe5a1d8c465277d5a1bb27e3000f4ff.rev'
gpg: revocation certificate stored as '/tmp/tmp.riPmBwzyyp/openpgp-revocs.d/7AE3BF51B0CBF2F67E98C82038AC1343DBBEA961.rev'
public and secret key created and signed.
gpg: checking the trustdb
gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
gpg: depth: 0 valid: 6 signed: 67 trust: 0-, 0q, 0n, 0m, 0f, 6u
gpg: depth: 1 valid: 67 signed: 40 trust: 67-, 0q, 0n, 0m, 0f, 0u
gpg: next trustdb check due at 2016-10-05
pub ed25519 2016-07-08
F478770235B60A230BE78005006A236C292C31D7
uid [ultimate] Kunisada Chuji <chuji@gniibe.org>
sub cv25519 2016-07-08
$
pub ed25519 2024-09-03 [SC] [expires: 2027-09-03]
7AE3BF51B0CBF2F67E98C82038AC1343DBBEA961
uid Kunisada Chuji <chuji@gniibe.org>
sub cv25519 2024-09-03 [E]
We have the primary key with ed25519, and encryption subkey with cv25519.
Next, we add an authentication subkey which can be used with OpenSSH.
As the use case is not that common, we need ``--expert`` option for GnuPG. ::
We invoke gpg frontend with ``--edit-key``, specifying the key ID. ::
Next, we add authentication subkey which can be used with OpenSSH.
We invoke gpg frontend with ``--edit-key`` and the key ID. ::
$ gpg2 --expert --edit-key 17174C1A7C406DB5
gpg (GnuPG) 2.1.13; Copyright (C) 2016 Free Software Foundation, Inc.
$ gpg --expert --edit-key 7AE3BF51B0CBF2F67E98C82038AC1343DBBEA961
gpg (GnuPG) 2.4.5; Copyright (C) 2024 g10 Code GmbH
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 ed25519/17174C1A7C406DB5
created: 2016-07-08 expires: never usage: SC
trust: ultimate validity: ultimate
ssb cv25519/37A03183DF7B31B1
created: 2016-07-08 expires: never usage: E
[ultimate] (1). Kunisada Chuji <chuji@gniibe.org>
We invoke ``addkey`` subcommand. ::
Secret key is available.
sec ed25519/38AC1343DBBEA961
created: 2024-09-03 expires: 2027-09-03 usage: SC
trust: ultimate validity: ultimate
ssb cv25519/52CBE6AC87EAD054
created: 2024-09-03 expires: never usage: E
[ultimate] (1). Kunisada Chuji <chuji@gniibe.org>
Here, it displays that there are main key and a subkey.
It prompts sub-command with ``gpg>``. We invoke ``addkey`` subcommand. ::
gpg> addkey
@ -401,7 +80,7 @@ It asks a kind of key, we input ``11`` to select ECC for authentication. ::
and then, we specify "Authenticate" capability. ::
Possible actions for a ECDSA/EdDSA key: Sign Authenticate
Possible actions for a ECC key: Sign Authenticate
Current allowed actions: Sign
(S) Toggle the sign capability
@ -410,7 +89,7 @@ and then, we specify "Authenticate" capability. ::
Your selection? a
Possible actions for a ECDSA/EdDSA key: Sign Authenticate
Possible actions for a ECC key: Sign Authenticate
Current allowed actions: Sign Authenticate
(S) Toggle the sign capability
@ -419,7 +98,7 @@ and then, we specify "Authenticate" capability. ::
Your selection? s
Possible actions for a ECDSA/EdDSA key: Sign Authenticate
Possible actions for a ECC key: Sign Authenticate
Current allowed actions: Authenticate
(S) Toggle the sign capability
@ -432,20 +111,16 @@ Then, it asks which curve. We input ``1`` for "Curve25519". ::
Please select which elliptic curve you want:
(1) Curve 25519
(2) NIST P-256
(3) NIST P-384
(4) NIST P-521
(5) Brainpool P-256
(6) Brainpool P-384
(7) Brainpool P-512
(8) secp256k1
(2) Curve 448
(3) NIST P-256
(4) NIST P-384
(5) NIST P-521
(6) Brainpool P-256
(7) Brainpool P-384
(8) Brainpool P-512
(9) secp256k1
Your selection? 1
It may ask confirmation with WARNING (depends on version). We say ``y``. ::
gpg: WARNING: Curve25519 is not yet part of the OpenPGP standard.
Use this curve anyway? (y/N) y
It asks expiration of the key. ::
Please specify how long the key should be valid.
@ -469,19 +144,48 @@ It goes. ::
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
It asks the passphrase. And done. ::
Then, it asks the passphrase, it is the passphrase of **key on host PC**.
It's the one we entered above as <PASSWORD-KEY-ON-PC>. And the subkey
is added. ::
sec ed25519/17174C1A7C406DB5
created: 2016-09-08 expires: never usage: SC
sec ed25519/38AC1343DBBEA961
created: 2024-09-03 expires: 2027-09-03 usage: SC
trust: ultimate validity: ultimate
ssb cv25519/37A03183DF7B31B1
created: 2016-09-08 expires: never usage: E
ssb ed25519/4AD7D2428679DF5F
created: 2016-09-08 expires: never usage: A
ssb cv25519/52CBE6AC87EAD054
created: 2024-09-03 expires: never usage: E
ssb ed25519/AC87B245DFC7AEAC
created: 2024-09-03 expires: never usage: A
[ultimate] (1). Kunisada Chuji <chuji@gniibe.org>
We type ``save`` to exit form gpg. ::
gpg> save
$
Backup the private key
======================
There are some ways to back up private key, such that backup .gnupg
directory entirely, or use of paperkey, etc. Here, we describe backup
by ASCII file. ASCII file is good, because it has less risk on
transfer. Binary file has a risk to be modified on transfer.
Note that the key on host PC is protected by a passphrase (which
is <PASSWORD-KEY-ON-PC> in the example above). Using the key
from the backup needs this passphrase. It is common that
people will forget passphrase for backup. Never forget it.
You have been warned.
To make ASCII backup for private key,
invokde GnuPG with ``--armor`` option and ``--export-secret-keys``
specifying the key identifier. ::
$ gpg --armor --output <YOUR-SECRET>.asc --export-secret-keys <YOUR-KEY-ID>
From the backup,
we can recover privet key by invoking GnuPG with ``--import`` option. ::
$ gpg --import <YOUR-SECRET>.asc
Note that both command invocations ask you the passphrase.

16
doc/gnuk-keytocard.rst
View File

@ -20,14 +20,14 @@ See `another document`_ to import keys to the Token from copied directory.
.. _another document: gnuk-keytocard-noremoval
After personalization, I put my keys into the Token.
After initial configuration, I put my keys into the Token.
Here is the session log.
I invoke GnuPG with my key (249CB3771750745D5CDD323CE267B052364F028D). ::
$ gpg --edit-key 249CB3771750745D5CDD323CE267B052364F028D
gpg (GnuPG) 2.1.13; Copyright (C) 2016 Free Software Foundation, Inc.
gpg (GnuPG) 2.4.5; Copyright (C) 2024 g10 Code GmbH
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
@ -61,8 +61,7 @@ and type ``1`` to say it's signature key. ::
Then, GnuPG asks two kinds of passphrases. One is the passphrase of **keys on PC**
and another is the passphrase of **Gnuk Token**. Note that the passphrase of
the token and the passphrase of the keys on PC are different things,
although they can be same.
the token and the passphrase of the keys on PC are different things.
Here, I assume that Gnuk Token's admin passphrase of factory setting (12345678).
@ -83,6 +82,9 @@ I enter these passphrases. ::
created: 2015-08-12 expires: never usage: A
[ultimate] (1). NIIBE Yutaka <gniibe@fsij.org>
[ultimate] (2) NIIBE Yutaka <gniibe@debian.org>
Note: the local copy of the secret key will only be deleted with "save".
gpg>
Secondly, I import my subkey of encryption. I select key number '1'. ::
@ -121,6 +123,9 @@ Then, GnuPG asks the passphrase of **keys on PC** again. I enter. ::
created: 2015-08-12 expires: never usage: A
[ultimate] (1). NIIBE Yutaka <gniibe@fsij.org>
[ultimate] (2) NIIBE Yutaka <gniibe@debian.org>
Note: the local copy of the secret key will only be deleted with "save".
gpg>
The sub key is now on the Token.
@ -175,6 +180,9 @@ Then, GnuPG asks the passphrase of **keys on PC** again. I enter. ::
created: 2015-08-12 expires: never usage: A
[ultimate] (1). NIIBE Yutaka <gniibe@fsij.org>
[ultimate] (2) NIIBE Yutaka <gniibe@debian.org>
Note: the local copy of the secret key will only be deleted with "save".
gpg>
The sub key is now on the Token.

72
doc/gnuk-passphrase-setting.rst
View File

@ -8,7 +8,6 @@ Terminology
In the OpenPGPcard specification, there are two passwords: one is
user-password and another is admin-password. In the specification,
user-password is refered as PW1, and admin-password is refered as PW3.
Besides, there is reset code, which enable a user to reset PW1.
Note that people sometimes use different words than "password" to
refer same thing, in GnuPG and its applications. For example, the
@ -32,16 +31,18 @@ Invoke GnuPG with the option ``--card-edit``. ::
Version ..........: 2.0
Manufacturer .....: unmanaged S/N range
Serial number ....: 87193059
Name of cardholder: Yutaka Niibe
Language prefs ...: ja
Sex ..............: male
URL of public key : http://www.gniibe.org/gniibe-20150813.asc
Name of cardholder: [not set]
Language prefs ...: [not set]
Salutation .......:
URL of public key : [not set]
Login data .......: gniibe
Signature PIN ....: not forced
Key attributes ...: ed25519 cv25519 ed25519
Max. PIN lengths .: 127 127 127
PIN retry counter : 3 3 3
Signature counter : 0
KDF setting ......: single
UIF setting ......: Sign=off Decrypt=off Auth=off
Signature key ....: 249C B377 1750 745D 5CDD 323C E267 B052 364F 028D
created ....: 2015-08-12 07:10:48
Encryption key....: E228 AB42 0F73 3B1D 712D E50C 850A F040 D619 F240
@ -63,7 +64,8 @@ It shows the status of the card (as same as the output of ``gpg --card-status``)
Then, GnuPG enters its own command interaction mode. The prompt is ``gpg/card>``.
Firstly, I change PIN of card user from factory setting (of "123456").
Note that, by only changing user's PIN, it enables "admin less mode" of Gnuk.
Note that, by only changing user's PIN as initial setup,
it enables "admin less mode" of Gnuk.
"Admin less mode" means that admin password will become same one of user's.
That is, PW1 = PW3.
Note that *the length of PIN should be more than (or equals to) 8* for
@ -82,65 +84,15 @@ Note that *the length of PIN should be more than (or equals to) 8* for
Repeat this PIN: <PASSWORD-OF-GNUK>
PIN changed.
The "admin less mode" is Gnuk only feature, not defined in the
OpenPGPcard specification. By using "admin less mode", it will be
only a sigle password for user to memorize, and it will be easier if a token
The "admin less mode" is Gnuk only feature, not defined in the OpenPGP
card specification. By using "admin less mode", it will be only a
sigle password for user to memorize, and it will be easier if a token
is used by an individual.
(If you want normal way ("admin full mode" in Gnuk's term),
that is, user-password *and* admin-password independently,
please change admin-password at first.
Then, the token works as same as OpenPGPcard specification
Then, the token works as same as OpenPGP card specification
with regards to PW1 and PW3.)
Set up of reset code (optional)
===============================
Lastly, we can setup reset code, entering admin mode.
Having reset code, we can unblock the token when the token will be blocked
(by wrong attempts to entering passphrase). Note that this is optional step.
When reset code is known to someone, that person can try to guess your passphrase of PW1 more times by unblocking the token. So, I don't use this feature by myself.
If we do, here is the interaction. ::
gpg/card> admin
Admin commands are allowed
gpg/card> passwd
gpg: OpenPGP card no. D276000124010200FFFE871930590000 detected
1 - change PIN
2 - unblock PIN
3 - change Admin PIN
4 - set the Reset Code
Q - quit
Your selection? 4
gpg: 3 Admin PIN attempts remaining before card is permanently locked
Please enter the Admin PIN
Enter Admin PIN: <PASSWORD-OF-GNUK>
New Reset Code
Enter New PIN: <RESETCODE-OF-GNUK>
New Reset Code
Repeat this PIN: <RESETCODE-OF-GNUK>
Reset Code set.
1 - change PIN
2 - unblock PIN
3 - change Admin PIN
4 - set the Reset Code
Q - quit
Your selection? q
Then, I quit. ::
gpg/card> quit
That's all in this step.

103
doc/gnuk-personalization.rst
View File

@ -1,30 +1,29 @@
=============================
Personalization of Gnuk Token
=============================
===================================
Initial configuration of Gnuk Token
===================================
Personalize your Gnuk Token
===========================
Invoke GnuPG with the option ``--card-edit``. ::
Invoke GnuPG with the option ``--card-edit`` with your new Gnuk Token. ::
$ gpg --card-edit
Reader ...........: 234B:0000:FSIJ-1.2.0-87193059:0
Application ID ...: D276000124010200FFFE871930590000
Reader ...........: 234B:0000:FSIJ-2.2-F1420A7A:0
Application ID ...: D276000124010200FFFEF1420A7A0000
Application type .: OpenPGP
Version ..........: 2.0
Manufacturer .....: unmanaged S/N range
Serial number ....: 87193059
Serial number ....: F1420A7A
Name of cardholder: [not set]
Language prefs ...: [not set]
Sex ..............: unspecified
Salutation .......:
URL of public key : [not set]
Login data .......: [not set]
Signature PIN ....: forced
Key attributes ...: rsa2048 rsa2048 rsa2048
Key attributes ...: ed25519 cv25519 ed25519
Max. PIN lengths .: 127 127 127
PIN retry counter : 3 3 3
Signature counter : 0
KDF setting ......: off
UIF setting ......: Sign=off Decrypt=off Auth=off
Signature key ....: [none]
Encryption key....: [none]
Authentication key: [none]
@ -36,40 +35,74 @@ It shows the status of the card (as same as the output of ``gpg --card-status``)
Then, GnuPG enters its own command interaction mode. The prompt is ``gpg/card>``.
First, enabling admin command, I put name of mine.
Note that I input admin PIN of factory setting (12345678) here. ::
Gnuk specific things
====================
Gnuk doesn't allow setting passphrase before importing your private
keys. Only **after** importing your private keys from your host PC,
it's possible to change the passphrase. Thus, the oder of setup
procedure is: initial config, importing private keys, and setup
passphrase.
Gnuk supports "admin less mode" for your passphrase setting. It's the
smartcard culture to have two passphrases (one for admin, another for
user). Gnuk supports the use case where admin==user.
Note that Gnuk requires enabling KDF-DO at initial configuration.
Let's do that first.
KDF-DO initial configuration
============================
Firstly, enabling admin command, I setup KDF-DO. (KDF-DO is a feature
of OpenPGP card to allow computation of key derivation function on
host side. This is mandatory for Gnuk 2.2. With KDF-DO, your private
keys on MCU's flash ROM can be encrypted securely with help on host
side.) ::
gpg/card> admin
Admin commands are allowed
gpg/card> name
Cardholder's surname: Niibe
Cardholder's given name: Yutaka
gpg: 3 Admin PIN attempts remaining before card is permanently locked
Please enter the Admin PIN
Enter Admin PIN: 12345678
gpg/card> kdf-setup single
Secondly, I put some other informations, such as language, sex,
login, and URL. URL specifies the place where I put my public keys. ::
Here, "kdf-setup" is the sub-command and "single" is to specify the
use case of single PIN (adminless). If you prefer traditional two
PINs use case (of Admin PIN and User PIN), don't supply "single"
argument, but just type "kdf-setup" sub-command.
It asks factory setting Admin PIN (usually with pop-up window), which
is 12345678.
Personalize your Gnuk Token
===========================
Optionally, you can put your name, language (by lang sub-command),
salutation, url and login. I only put login of mine. ::
gpg/card> lang
Language preferences: ja
gpg/card> sex
Sex ((M)ale, (F)emale or space): m
gpg/card> url
URL to retrieve public key: http://www.gniibe.org/gniibe-20150813.asc
gpg/card> login
Login data (account name): gniibe
Since I don't force PIN input everytime,
toggle it to non-force-pin-for-signature. ::
PIN input is needed (or not) everytime for signing
==================================================
Since I don't want to force PIN input everytime when signing, toggle
it to non-force-pin-for-signature. ::
gpg/card> forcesig
Instead of forcing PIN input everytime when signing by Gnuk Token, I
have a configuration of private key file under gpg-agent with a line
of "Confirm: yes", so that I can acknowledge/authorize use of key
everytime on my desktop.
Quit from the interactive session
=================================
Then, I quit. ::
gpg/card> quit

14
doc/gpg-settings.rst
View File

@ -11,17 +11,9 @@ Here is my GnuPG settings.
I create ``.gnupg/gpg.conf`` file with the following content. ::
use-agent
default-key 0xE267B052364F028D
In addition to the ``use-agent`` option, I specify my default key.
The ``use-agent`` option is for GnuPG 1.4.x and it means using gpg-agent if available.
If no option, GnuPG 1.4.x directly connects to Gnuk Token by itself, instead of through scdaemon. When GnuPG 1.4.x tries to access Gnuk Token and scdaemon is running, there are conflicts.
We recommend to specify the ``use-agent`` option for GnuPG 1.4.x to access Gnuk Token through gpg-agent and scdaemon.
For GnuPG 2.0 and 2.1, gpg-agent is always used, so, there is no need to specify the ``use-agent`` option, but having this option is no harm, anyway.
I specify my default key (since I had old RSA key too).
Let gpg-agent manage SSH key
@ -51,5 +43,5 @@ References
* `Creating a new GPG key`_
* `Use OpenPGP Keys for OpenSSH, how to use gpg with ssh`_
.. _Creating a new GPG key: http://keyring.debian.org/creating-key.html
.. _Use OpenPGP Keys for OpenSSH, how to use gpg with ssh: http://www.programmierecke.net/howto/gpg-ssh.html
.. _Creating a new GPG key: https://keyring.debian.org/creating-key.html
.. _Use OpenPGP Keys for OpenSSH, how to use gpg with ssh: https://www.programmierecke.net/howto/gpg-ssh.html

5
doc/index.rst
View File

@ -2,8 +2,8 @@
sphinx-quickstart on Wed Jul 4 15:29:05 2012.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Copyright (C) 2012, 2013, 2016 NIIBE Yutaka
Copyright (C) 2012, 2013, 2016 Free Software Initiative of Japan
Copyright (C) 2012, 2013, 2016, 2024 NIIBE Yutaka
Copyright (C) 2012, 2013, 2016, 2024 Free Software Initiative of Japan
This document is licensed under a CC-BY-SA 3.0 Unported License
Gnuk Documentation
@ -18,7 +18,6 @@ Contents:
gpg-settings.rst
stop-scdaemon.rst
udev-rules.rst
gnuk-token-initial-configuration.rst
gnuk-personalization.rst
generating-key.rst
gnuk-keytocard.rst

14
doc/intro.rst
View File

@ -7,9 +7,9 @@ What's Gnuk?
Gnuk is an implementation of USB cryptographic token for GNU Privacy
Guard. Gnuk supports OpenPGP card protocol version 2, and it runs on
STM32F103 processor.
an MCU (currently STM32F103 and GD32F103 are supported) .
This document explains about Gnuk 1.2, which comes with ECC algorithm.
This document explains about Gnuk 2.2, which comes with ECC support.
Cryptographic token and feature of Gnuk
@ -18,7 +18,7 @@ Cryptographic token and feature of Gnuk
Cryptographic token is a store of private keys and it computes cryptographic
functions on the device.
The idea is to separate important secrets to independent device,
The idea is to separate important secrets to an independent device,
from where nobody can extract them.
@ -32,17 +32,15 @@ Gnuk is developed on the environment where there are only Free Software.
Target boards for running Gnuk
------------------------------
Hardware requirement for Gnuk is the micro controller STM32F103.
In version 1.2, Gnuk supports following boards.
Hardware requirement for Gnuk is the micro controller STM32F103 or GD32F103.
In version 2.2, Gnuk supports following boards.
* FST-01 (Flying Stone Tiny ZERO-ONE)
* FST-01 (Flying Stone Tiny ZERO-ONE), FST-01G, and FST-01SZ
* Olimex STM32-H103
* ST Nucleo F103
* Nitrokey Start
Host prerequisites for using Gnuk Token
---------------------------------------

2
doc/stop-scdaemon.rst
View File

@ -30,7 +30,7 @@ command.
Or, you can use ``gpgconf`` command. Type::
$ gpgconf --reload scdaemon
$ gpgconf --kill scdaemon
will do the same thing.

48
doc/udev-rules.rst
View File

@ -10,34 +10,20 @@ PC/SC Lite, as it has its own device configuration.
udev rules for Gnuk Token
=========================
In case of Debian, there is a file /lib/udev/rules.d/60-gnupg.rules
(or /lib/udev/rules.d/60-scdamon.rules for newer version),
when you install "gnupg" package (or "scdaemon" package).
This is the place we need to
change, if your installation is older than jessie. Newer "gnupg"
package (1.4.15-1 or later) or "scdaemon" package has already
supported Gnuk Token.
In case of Debian, there is a file /lib/udev/rules.d/60-scdamon.rules,
when you install "scdaemon" package, and no need of another
configuration.
If needed, please add lines for Gnuk Token to give a desktop user the
permission to use the device. We specify USB ID of Gnuk Token (by
FSIJ)::
If it's not the case, please have a configuration file of udev for
Gnuk Token to give a desktop user the permission to use the device.
It's like in the file /etc/udev/rules.d/60-gnuk.rules. ::
--- /lib/udev/rules.d/60-gnupg.rules.orig 2012-06-24 21:51:26.000000000 +0900
+++ /lib/udev/rules.d/60-gnupg.rules 2012-07-13 17:18:55.149587687 +0900
@@ -10,4 +10,7 @@
ATTR{idVendor}=="04e6", ATTR{idProduct}=="5115", ENV{ID_SMARTCARD_READER}="1", ENV{ID_SMARTCARD_READER_DRIVER}="gnupg"
ATTR{idVendor}=="20a0", ATTR{idProduct}=="4107", ENV{ID_SMARTCARD_READER}="1", ENV{ID_SMARTCARD_READER_DRIVER}="gnupg"
+# Gnuk
+ATTR{idVendor}=="234b", ATTR{idProduct}=="0000", ENV{ID_SMARTCARD_READER}="1", ENV{ID_SMARTCARD_READER_DRIVER}="gnupg"
+
LABEL="gnupg_rules_end"
When we only install "gnupg2" package for 2.0 (with no "gnupg" package),
there will be no udev rules (there is a bug report #543217 for this issue).
In this case, we need something like this in /etc/udev/rules.d/60-gnuk.rules::
SUBSYSTEMS=="usb", ATTR{idVendor}=="234b", ATTR{idProduct}=="0000", \
## Gnuk Token
SUBSYSTEM=="usb", ATTR{product}=="Gnuk Token", ENV{ID_SMARTCARD_READER}="1", \
ENV{ID_SMARTCARD_READER_DRIVER}="gnupg"
SUBSYSTEM=="usb", ATTR{idVendor}=="234b", ATTR{idProduct}=="0000", \
ENV{ID_SMARTCARD_READER}="1", ENV{ID_SMARTCARD_READER_DRIVER}="gnupg"
SUBSYSTEM=="usb", ATTR{idVendor}=="1209", ATTR{idProduct}=="2440", \
ENV{ID_SMARTCARD_READER}="1", ENV{ID_SMARTCARD_READER_DRIVER}="gnupg"
Usually, udev daemon automatically handles for the changes of configuration
@ -46,14 +32,16 @@ files. If not, please let the daemon reload rules::
# udevadm control --reload-rules
udev rules for ST-Link/V2
=========================
For development of Gnuk, we use ST-Link/V2 as JTAG/SWD debugger.
We need to have a udev rule for ST-Link/V2. It's like::
ACTION=="add", SUBSYSTEM=="usb", ATTR{idVendor}=="0483", ATTR{idProduct}=="3748", GROUP="tape", MODE="664", SYMLINK+="stlink"
ACTION=="add", SUBSYSTEM=="usb", ATTR{idVendor}=="0483", \
ATTR{idProduct}=="3748", GROUP="tape", MODE="664", SYMLINK+="stlink"
I have this in the file /etc/udev/rules.d/10-stlink.rules.
I had this in the file /etc/udev/rules.d/10-stlink.rules.
In case of Debian, /usr/lib/udev/rules.d/60-openocd.rules has the
configuration for ST-Link/V2.

59
doc/using-gnuk-token-with-another-computer.rst
View File

@ -15,23 +15,25 @@ Fetch the public key and connect it to the Token
In order to use the Token, we need to put the public key and the secret
key references (to the token) under ``.gnupg`` directory.
To do that, invoke GnuPG with ``--card-edit`` option. ::
When I invoke GnuPG with ``--card-status`` option. ::
Reader ...........: 234B:0000:FSIJ-1.2.0-87193059:0
Application ID ...: D276000124010200FFFE871930590000
Version ..........: 2.0
Manufacturer .....: unmanaged S/N range
Serial number ....: 87193059
Name of cardholder: Yutaka Niibe
Language prefs ...: ja
Sex ..............: male
URL of public key : http://www.gniibe.org/gniibe-20150813.asc
Name of cardholder: [not set]
Language prefs ...: [not set]
Salutation .......:
URL of public key : [not set]
Login data .......: gniibe
Signature PIN ....: not forced
Key attributes ...: ed25519 cv25519 ed25519
Max. PIN lengths .: 127 127 127
PIN retry counter : 3 3 3
Signature counter : 0
KDF setting ......: off
UIF setting ......: Sign=off Decrypt=off Auth=off
Signature key ....: 249C B377 1750 745D 5CDD 323C E267 B052 364F 028D
created ....: 2015-08-12 07:10:48
Encryption key....: E228 AB42 0F73 3B1D 712D E50C 850A F040 D619 F240
@ -40,49 +42,27 @@ To do that, invoke GnuPG with ``--card-edit`` option. ::
created ....: 2015-08-12 07:16:14
General key info..: [none]
gpg/card>
Here, the secret key references (to the token) are created under ``.gnupg/private-keys-v1.d`` directory. It can be also created when I do ``--card-status`` by GnuPG.
Still, it says that there is no key info related to this token on my PC (``[none]`` for General key info), because I don't have the public key on this PC yet.
So, I fetch the public key from URL specified in the Token. ::
Because I have WKD setup for my email of FSIJ, I fetch the public key
by WKD using `gpg --locate-key` command. ::
gpg/card> fetch
gpg: requesting key E267B052364F028D from http server www.gniibe.org
$ gpg --locate-key gniibe@fsij.org
gpg: key E267B052364F028D: public key "NIIBE Yutaka <gniibe@fsij.org>" imported
gpg: Total number processed: 1
gpg: imported: 1
gpg: marginals needed: 3 completes needed: 1 trust model: pgp
gpg: depth: 0 valid: 6 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 6u
gpg/card>
pub ed25519 2015-08-12 [SC]
249CB3771750745D5CDD323CE267B052364F028D
uid [ unknown] NIIBE Yutaka <gniibe@fsij.org>
sub cv25519 2015-08-12 [E]
sub ed25519 2015-08-12 [A]
Good. The public key is now under ``.gnupg`` directory. We can examine by ``gpg --list-keys``.
When I type return at the ``gpg/card>`` prompt, now, I can see: ::
When I do ``gpg --card-status``, now, I can see: ::
Reader ...........: 234B:0000:FSIJ-1.2.0-87193059:0
Application ID ...: D276000124010200FFFE871930590000
Version ..........: 2.0
Manufacturer .....: unmanaged S/N range
Serial number ....: 87193059
Name of cardholder: Yutaka Niibe
Language prefs ...: ja
Sex ..............: male
URL of public key : http://www.gniibe.org/gniibe-20150813.asc
Login data .......: gniibe
Signature PIN ....: not forced
Key attributes ...: ed25519 cv25519 ed25519
Max. PIN lengths .: 127 127 127
PIN retry counter : 3 3 3
Signature counter : 0
Signature key ....: 249C B377 1750 745D 5CDD 323C E267 B052 364F 028D
created ....: 2015-08-12 07:10:48
Encryption key....: E228 AB42 0F73 3B1D 712D E50C 850A F040 D619 F240
created ....: 2015-08-12 07:10:48
Authentication key: E63F 31E6 F203 20B5 D796 D266 5F91 0521 FAA8 05B1
created ....: 2015-08-12 07:16:14
General key info..: pub ed25519/E267B052364F028D 2015-08-12 NIIBE Yutaka <gniibe@fsij.org>
sec> ed25519/E267B052364F028D created: 2015-08-12 expires: never
card-no: FFFE 87193059
@ -91,9 +71,6 @@ When I type return at the ``gpg/card>`` prompt, now, I can see: ::
ssb> ed25519/5F910521FAA805B1 created: 2015-08-12 expires: never
card-no: FFFE 87193059
gpg/card>
Note that, it displays the information about "General key info".
OK, now I can use the Token on this computer.
@ -108,7 +85,7 @@ key references to the card. More, I need to update the trustdb.
To do that, I do: ::
$ ./gpg --edit-key E267B052364F028D
gpg (GnuPG) 2.1.13; Copyright (C) 2016 Free Software Foundation, Inc.
gpg (GnuPG) 2.4.5; Copyright (C) 2024 g10 Code GmbH
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
@ -176,7 +153,7 @@ See, the key is ``unknown`` state. Add trust for that, because it's the key und
And I quit from gpg. Then, when I invoke GnuPG, it will be ``ultimate`` key. Let's see: ::
$ ./gpg --edit-key E267B052364F028D
gpg (GnuPG) 2.1.13; Copyright (C) 2016 Free Software Foundation, Inc.
gpg (GnuPG) 2.4.5; Copyright (C) 2024 g10 Code GmbH
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.