deon/gnuk
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

update doc for new passphrase process

Browse Source
This commit is contained in:
NIIBE Yutaka
2013-10-24 16:02:50 +09:00
parent 9b6e2bd160
commit 1b1cf7f0e3
12 changed files with 178 additions and 124 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
doc/development.rst
View File

@@ -12,7 +12,7 @@ it is possible to develop with that. But it should be considered
*experimental* environment, and it should not be used for usual
purpose. That's because it is basically impossible for DfuSe
implementations to disable reading-out from flash ROM. It means
that your secret will be readily extracted by DfuSe.
that your secrets will be readily extracted by DfuSe.
For JTAG debugger, Olimex JTAG-Tiny is good and supported well. For
SWD debugger, ST-Link/V2 would be good, and it is supported by
@@ -22,10 +22,12 @@ tool/stlinkv2.py.
OpenOCD
-------
For JTAG/SWD debugger, we can use OpenOCD.
For JTAG/SWD debugger, we can use OpenOCD somehow.
Note that ST-Link/V2 is *not* supported by OpenOCD 0.5.0. It is
supported by version 0.6 or later.
Note that ST-Link/V2 was *not* supported by OpenOCD 0.5.0.
It is supported by version 0.6 or later somehow, but still, you can't
enable protection of flash ROM with OpenOCD using ST-Link/V2.
GNU Toolchain
@@ -36,17 +38,8 @@ You need GNU toolchain and newlib for 'arm-none-eabi' target.
There is "gcc-arm-embedded" project. See:
https://launchpad.net/gcc-arm-embedded/
It is based on GCC 4.6. You'd need "-O3 -Os" instead of "-O2" and it
will be slightly better.
Note that we need to link correct C library (for string functions).
For this purpose, our src/Makefile.in contains following line:
MCFLAGS= -mcpu=$(MCU) -mfix-cortex-m3-ldrd
This should not be needed (as -mcpu=cortex-m3 means
-mfix-cortex-m3-ldrd), but it was needed for the configuration of
patch-gcc-config-arm-t-arm-elf.diff in summon-arm-toolchain in practice.
It is based on GCC 4.7 (as of October, 2013). We are using "-O3 -Os"
for compiler option.
Building Gnuk
@@ -68,4 +61,4 @@ Type:
$ make
Then, we will have "gnuk.elf".
Then, we will have "gnuk.elf" under src/build directory.

10
doc/generating-2048-RSA-key.rst
View File

@@ -27,7 +27,7 @@ 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.
For security, the key length is a single factor. We had and will have
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 have
longer keys.
@@ -37,6 +37,7 @@ device computation power and host software constraints.
Thus, the key size is 2048-bit in the examples below.
Generating keys on host PC
==========================
@@ -95,7 +96,7 @@ Then enter user ID. ::
and enter 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 password of Gnuk Token.
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). ::
@@ -289,8 +290,9 @@ Backup the private key
======================
There are some ways to back up private key, such that backup .gnupg
directory entirely, use of paperkey. Here we describe backup by ASCII
file. ASCII file is good, because it has less risk on transfer.
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

5
doc/gnuk-keytocard-noremoval.rst
View File

@@ -59,6 +59,8 @@ and another is the password of **Gnuk Token**. Note that the password of
the token and the password of the keys on PC are different things,
although they can be same.
Here, I assume that Gnuk Token's admin password of factory setting (12345678).
I enter these passwords. ::
You need a passphrase to unlock the secret key for
@@ -69,7 +71,7 @@ I enter these passwords. ::
gpg: 3 Admin PIN attempts remaining before card is permanently locked
Please enter the Admin PIN
Enter Admin PIN: <PASSWORD-GNUK>
Enter Admin PIN: 12345678
sec 2048R/4CA7BABE created: 2010-10-15 expires: never
card-no: F517 00000001
@@ -181,3 +183,4 @@ Lastly, I quit GnuPG. Note that I **don't** save changes. ::
$
All keys are imported to Gnuk Token now.
Still, secret keys are available on PC.

14
doc/gnuk-keytocard.rst
View File

@@ -3,9 +3,9 @@ Key import from PC to Gnuk Token
================================
This document describes how I put my **keys on PC** to the Token,
and remove keys from PC.
and remove secret keys from PC.
Note that there is **no ways** to export keys from the Token,
Note that there is **no ways** to export keys from the Gnuk Token,
so please be careful.
@@ -71,6 +71,8 @@ and another is the password of **Gnuk Token**. Note that the password of
the token and the password of the keys on PC are different things,
although they can be same.
Here, I assume that Gnuk Token's admin password of factory setting (12345678).
I enter these passwords. ::
You need a passphrase to unlock the secret key for
@@ -81,7 +83,7 @@ I enter these passwords. ::
gpg: 3 Admin PIN attempts remaining before card is permanently locked
Please enter the Admin PIN
Enter Admin PIN: <PASSWORD-GNUK>
Enter Admin PIN: 12345678
sec 2048R/4CA7BABE created: 2010-10-15 expires: never
card-no: F517 00000001
@@ -89,7 +91,8 @@ I enter these passwords. ::
ssb 2048R/5BB065DC created: 2010-10-22 expires: never
(1) NIIBE Yutaka <gniibe@fsij.org>
The primary key is now on the Token and GnuPG says its card-no (F517 00000001) , where F517 is the vendor ID of FSIJ.
The primary key is now on the Token and GnuPG says its card-no (F517 00000001),
where F517 is the vendor ID of FSIJ.
Secondly, I import my subkey of encryption. I select key number '1'. ::
@@ -190,4 +193,5 @@ Lastly, I save changes of **keys on PC** and quit GnuPG. ::
$
All secret keys are imported to Gnuk Token now.
On PC, only references (card-no) to the Token remain.
On PC, only references (card-no) to the Token remain
and secrets have been removed.

122
doc/gnuk-passphrase-setting.rst Normal file
View File

@@ -0,0 +1,122 @@
==========================================
Set up your passphrase for your Gnuk Token
==========================================
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
output explained above includes the word "PIN" (Personal
Identification Number), and the helper program for input is named
"pinentry". Note that it is OK (and recommended) to include
characters other than digits for the case of OpenPGPcard.
Besides, some people sometimes prefer the word "passphrase" to
"password", as it can encourage to have longer string, but it means
same thing and it just refer user-password or admin-password.
Set up PW1, PW3 and reset code
==============================
Invoke GnuPG with the option ``--card-edit``. ::
$ gpg --card-edit
gpg: detected reader `FSIJ Gnuk (0.12-34006E06) 00 00'
Application ID ...: D276000124010200F517000000010000
Version ..........: 2.0
Manufacturer .....: FSIJ
Serial number ....: 00000001
Name of cardholder: [not set]
Language prefs ...: [not set]
Sex ..............: unspecified
URL of public key : [not set]
Login data .......: [not set]
Signature PIN ....: forced
Key attributes ...: 2048R 2048R 2048R
Max. PIN lengths .: 127 127 127
PIN retry counter : 3 3 3
Signature counter : 0
Signature key ....: [none]
Encryption key....: [none]
Authentication key: [none]
General key info..: [none]
It shows the status of the card (as same as the output of ``gpg --card-status``). It shows token's name and its USB serial string (0.12-34006E06) from PC/SC-lite.
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.
"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
"admin less mode". ::
gpg/card> passwd
gpg: OpenPGP card no. D276000124010200F517000000010000 detected
Please enter the PIN
Enter PIN: 123456
New PIN
Enter New PIN: <PASSWORD-OF-GNUK>
New PIN
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
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
with regards to PW1 and PW3.)
Lastly, I setup reset code. This is optional. ::
gpg/card> passwd
gpg: OpenPGP card no. D276000124010200F517000000010000 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.

87
doc/gnuk-personalization.rst
View File

@@ -33,55 +33,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>``.
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.
Note that people sometimes use different words than "password" to
refer same thing, in GnuPG and its applications. For example, the
output explained above includes the word "PIN" (Personal
Identification Number), and the helper program for input is named
"pinentry". Note that it is OK (and recommended) to include
characters other than digits for the case of OpenPGPcard.
Besides, some people sometimes prefer the word "passphrase" to
"password", as it can encourage to have longer string, but it means
same thing and it just refer user-password or admin-password.
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.
"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
"admin less mode". ::
gpg/card> passwd
gpg: OpenPGP card no. D276000124010200F517000000010000 detected
Please enter the PIN
Enter PIN: 123456
New PIN
Enter New PIN: <PASSWORD-OF-GNUK>
New PIN
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
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
with regards to PW1 and PW3.)
Secondly, enabling admin command, I put name of mine.
Note that I input user's PIN (which I set above) here,
because it is "admin less mode". ::
First, enabling admin command, I put name of mine.
Note that I input admin PIN of factory setting (12345678) here. ::
gpg/card> admin
Admin commands are allowed
@@ -92,9 +45,9 @@ because it is "admin less mode". ::
gpg: 3 Admin PIN attempts remaining before card is permanently locked
Please enter the Admin PIN
Enter Admin PIN: <PASSWORD-OF-GNUK>
Enter Admin PIN: 12345678
Thirdly, I put some other informations, such as language, sex,
Secondly, I put some other informations, such as language, sex,
login, and URL. URL specifies the place where I put my public keys. ::
gpg/card> lang
@@ -114,38 +67,6 @@ toggle it to non-force-pin-for-signature. ::
gpg/card> forcesig
Lastly, I setup reset code. This is optional. ::
gpg/card> passwd
gpg: OpenPGP card no. D276000124010200F517000000010000 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

4
doc/gnuk-token-initial-configuration.rst
View File

@@ -2,7 +2,9 @@
Initial Configuration of Gnuk Token
===================================
This is optional. You don't need to setup the serial number of Gnuk Token,
This is optional step.
You don't need to setup the serial number of Gnuk Token,
as it comes with its default serial number based on MCU's chip ID.
You can setup the serial number of Gnuk Token only once.

4
doc/gpg-settings.rst
View File

@@ -14,8 +14,8 @@ I create ``.gnupg/gpg.conf`` file with the following content. ::
use-agent
personal-digest-preferences SHA256
cert-digest-algo SHA256
default-preference-list SHA512 SHA384 SHA256 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed
default-key 0x4ca7babe

7
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 NIIBE Yutaka
Copyright (C) 2012 Free Software Initiative of Japan
Copyright (C) 2012, 2013 NIIBE Yutaka
Copyright (C) 2012, 2013 Free Software Initiative of Japan
This document is licensed under a CC-BY-SA 3.0 Unported License
Gnuk Documentation
@@ -15,7 +15,6 @@ Contents:
:maxdepth: 2
intro.rst
development.rst
stop-scdaemon.rst
udev-rules.rst
gnuk-token-initial-configuration.rst
@@ -23,9 +22,11 @@ Contents:
generating-2048-RSA-key.rst
gnuk-keytocard.rst
gnuk-keytocard-noremoval.rst
gnuk-passphrase-setting.rst
using-gnuk-token-with-another-computer.rst
gpg-settings.rst
gnome3-gpg-settings.rst
development.rst
Indices and tables

12
doc/intro.rst
View File

@@ -31,20 +31,22 @@ Target boards for running Gnuk
------------------------------
Hardware requirement for Gnuk is the micro controller STM32F103.
In version 1.0, Gnuk supports following boards.
In version 1.1.x, Gnuk supports following boards.
* FST-01 (Flying Stone Tiny ZERO-ONE)
* Olimex STM32-H103
* STM32 part of STM8S Discovery Kit
Not supported yet.
* CQ STARM
* STBee
* STBee Mini
* STM32 part of STM8S Discovery Kit
Host prerequisites for using Gnuk Token
---------------------------------------
@@ -65,5 +67,5 @@ Usages
* Sign with GnuPG
* Decrypt with GnuPG
* Use with OpenSSH
* Use with Firefox for X.509 client certificate authentication
* Use with OpenSSH through gpg-agent (as ssh-agent)
* Use with Firefox through Scute for X.509 client certificate authentication

2
doc/stop-scdaemon.rst
View File

@@ -32,6 +32,6 @@ command.
Let GPG-AGENT/SCDAEMON learn
============================
To let gpg-agent/scdaemon learn, type::
To let gpg-agent/scdaemon learn from Gnuk Token, type::
$ gpg-connect-agent learn /bye

10
doc/udev-rules.rst
View File

@@ -11,9 +11,13 @@ udev rules for Gnuk Token
=========================
In case of Debian, there is a file /lib/udev/rules.d/60-gnupg.rules,
when you install "gnupg" package. This is the place we need to change.
We 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)::
when you install "gnupg" 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) has already supported Gnuk Token.
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)::
--- /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