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

update doc (partially)

Browse Source
This commit is contained in:
NIIBE Yutaka
2012-12-26 11:11:18 +09:00
parent ad9a901e1b
commit 90a11859dc
4 changed files with 124 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
doc/development.rst
View File

@@ -5,10 +5,9 @@ Development Environment
Hardware
--------
For development, it is highly recommended to have JTAG debugger or SWD
debugger.
For development, it is highly recommended to have JTAG/SWD debugger.
For boards with DFU (Device Firmware Upgrade) feature, such as DfuSe,
For boards with DFU (Device Firmware Upgrade) feature (such as DfuSe),
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
@@ -17,17 +16,16 @@ that your secret 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
the tool of tool/stlinkv2.py.
tool/stlinkv2.py.
OpenOCD
-------
For JTAG debugger or SWD debugger, we can use OpenOCD.
For JTAG/SWD debugger, we can use OpenOCD.
Note that ST-Link/V2 is *not* supported by OpenOCD 0.5.0. It will be
supported by version 0.6 or later, as current development version
supports it.
Note that ST-Link/V2 is *not* supported by OpenOCD 0.5.0. It is
supported by version 0.6 or later.
GNU Toolchain
@@ -35,9 +33,11 @@ GNU Toolchain
You need GNU toolchain and newlib for 'arm-none-eabi' target.
See http://github.com/esden/summon-arm-toolchain/ (which includes fix
of binutils-2.21.1) for preparation of GNU Toolchain for
'arm-none-eabi' target. This is for GCC 4.5.
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:
@@ -45,20 +45,9 @@ 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 is needed for the configuration of
-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.
In ChibiOS_2.0.8/os/ports/GCC/ARM/rules.mk, it specifies
-mno-thumb-interwork option. This means that you should not link C
library which contains ARM (not Thumb) code.
Recently, there is "gcc-arm-embedded" project. See:
https://launchpad.net/gcc-arm-embedded/
It is based on GCC 4.6. For version 4.6-2012-q2-update, you'd
need "-O3 -Os" instead of "-O2" and it will be slightly better.
Building Gnuk
-------------
@@ -72,8 +61,8 @@ Then, run ``configure``:
$ ./configure --vidpid=<VID:PID>
Here, you need to specify USB vendor ID and product ID. For FSIJ's,
it's: --vidpid=234b:0000 . Please read section 'USB vendor ID and
product ID' above.
it's: --vidpid=234b:0000 . Please read the section 'USB vendor ID and
product ID' in README.
Type:

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

@@ -2,11 +2,45 @@
Generating 2048-bit RSA keys
============================
This document describes how I generate 2048-bit RSA keys.
In this section, we describe how to generate 2048-bit RSA keys.
.. BREAK
Here is the log to generate signature key and encryption subkey.
Key length of RSA
=================
In 2005, NIST (National Institute of Standards and Technology, USA)
has 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 2010, 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, and 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.
For security, the key length is 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.
We deliberately support only 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.
Generating keys on host PC
==========================
Here is the example session to generate main key and a subkey for encryption.
I invoke GnuPG with ``--gen-key`` option. ::
@@ -25,7 +59,7 @@ and GnuPG asks kind of key. Select ``RSA and RSA``. ::
Your selection? 1
RSA keys may be between 1024 and 4096 bits long.
and select 2048-bit (as Gnuk Token only suppurt this). ::
and select 2048-bit (as Gnuk Token only supports this). ::
What keysize do you want? (2048)
Requested keysize is 2048 bits
@@ -59,7 +93,12 @@ Then enter user ID. ::
Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o
and enter passphrase for this **key on PC**. ::
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.
We enter two same inputs two times
(once for passphrase input, and another for confirmation). ::
You need a Passphrase to protect your secret key.
<PASSWORD-KEY-ON-PC>
@@ -86,43 +125,47 @@ Then, GnuPG generate keys. It takes some time. ::
gpg: checking the trustdb
gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
gpg: depth: 0 valid: 2 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 2u
pub 2048R/28C0CD7C 2011-05-24
Key fingerprint = 0B4D C763 D57B ADBB 1870 A978 BDEE 4A35 28C0 CD7C
pub 2048R/4CA7BABE 2010-10-15
Key fingerprint = 1241 24BD 3B48 62AF 7A0A 42F1 00B4 5EBD 4CA7 BABE
uid Niibe Yutaka <gniibe@fsij.org>
sub 2048R/F01E19B7 2011-05-24
sub 2048R/084239CF 2010-10-15
$
Done.
Then, I create authentication subkey. Authentication subkey is not that common, but very useful (say, for SSH authentication). As it is not that common, we need ``--expert`` option for GnuPG. ::
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 --expert --edit-key 28C0CD7C
$ gpg --expert --edit-key 4CA7BABE
gpg (GnuPG) 1.4.11; Copyright (C) 2010 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.
pub 2048R/28C0CD7C created: 2011-05-24 expires: never usage: SC
pub 2048R/4CA7BABE created: 2010-10-15 expires: never usage: SC
trust: ultimate validity: ultimate
sub 2048R/F01E19B7 created: 2011-05-24 expires: never usage: E
sub 2048R/084239CF created: 2010-10-15 expires: never usage: E
[ultimate] (1). Niibe Yutaka <gniibe@fsij.org>
gpg>
Here, I enter ``addkey`` command. Then, I enter the passphrase of **key on PC**, I specified above. ::
Here, it displays that there are main key and a subkey.
It prompts sub-command with ``gpg>`` .
Here, we enter ``addkey`` sub-command.
Then, we enter the passphrase of **key on host PC**.
It's the one we entered above as <PASSWORD-KEY-ON-PC>. ::
gpg> addkey
Key is protected.
You need a passphrase to unlock the secret key for
user: "Niibe Yutaka <gniibe@fsij.org>"
2048-bit RSA key, ID 28C0CD7C, created 2011-05-24
2048-bit RSA key, ID 4CA7BABE, created 2010-10-15
<PASSWORD-KEY-ON-PC>
gpg: gpg-agent is not available in this session
GnuPG askes kind of key. I select ``RSA (set your own capabilities)``. ::
GnuPG asks kind of key. We select ``RSA (set your own capabilities)``. ::
Please select what kind of key you want:
(3) DSA (sign only)
@@ -133,7 +176,7 @@ GnuPG askes kind of key. I select ``RSA (set your own capabilities)``. ::
(8) RSA (set your own capabilities)
Your selection? 8
And select ``Authenticate`` for the capabilities for this key. Initially, it's ``Sign`` and ``Encrypt``. I need to deselect ``Sign`` and ``Encryp``, and select ``Authenticate``. To do that, I enter ``s``, ``a``, and ``e``. ::
And select ``Authenticate`` for the capabilities for this key. Initially, it's ``Sign`` and ``Encrypt``. I need to deselect ``Sign`` and ``Encryp``, 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
@@ -153,31 +196,33 @@ And select ``Authenticate`` for the capabilities for this key. Initially, it's
(A) Toggle the authenticate capability
(Q) Finished
Your selection? a
Possible actions for a RSA key: Sign Encrypt Authenticate
Current allowed actions: Encrypt Authenticate
(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: 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, I set the capability of ``Authenticate``. I enter ``q`` to finish setting capabilities. ::
OK, we set the capability of ``Authenticate``.
We enter ``q`` to finish setting capabilities. ::
Your selection? q
GnuPG asks bitsize and expiration, I enter 2048 for bitsize and no expiration. Then, I confirm that I really create the key. ::
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)
@@ -202,15 +247,15 @@ Then, GnuPG generate the key. ::
.......+++++
+++++
pub 2048R/28C0CD7C created: 2011-05-24 expires: never usage: SC
pub 2048R/4CA7BABE created: 2010-10-15 expires: never usage: SC
trust: ultimate validity: ultimate
sub 2048R/F01E19B7 created: 2011-05-24 expires: never usage: E
sub 2048R/B8929606 created: 2011-05-24 expires: never usage: A
sub 2048R/084239CF created: 2010-10-15 expires: never usage: E
sub 2048R/5BB065DC created: 2010-10-22 expires: never usage: A
[ultimate] (1). Niibe Yutaka <gniibe@fsij.org>
gpg>
I save the key. ::
We save the key (to the storage of the host PC. ::
gpg> save
$
@@ -221,8 +266,13 @@ Now, we have three keys (one primary key for signature and certification, subkey
Publishing public key
=====================
I make a file for my public key by ``--export`` option of GnuPG. ::
We make a file for the public key by ``--export`` option of GnuPG. ::
$ gpg --armor --output gniibe.asc --export 4CA7BABE
$ gpg --armor --output <YOUR-KEY>.asc --export <YOUR-KEY-ID>
and put it at: http://www.gniibe.org/gniibe.asc
We can publish the file by web server. Or we can publish it
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, widely used.

4
doc/stop-scdaemon.rst
View File

@@ -6,8 +6,8 @@ There is a daemon named ``scdaemon`` behind gpg-agent, which handles
communication to smartcard/token.
Ideally, we don't need to care about ``scdaemon``, and it should
everything automatically. But, there are some cases (because of
bugs), where we need to talk to the daemon directly, in practice.
handle everything automatically. But, there are some cases (because
of bugs), where we need to talk to the daemon directly, in practice.
How to communicate SCDAEMON

39
doc/udev-rules.rst
View File

@@ -7,11 +7,13 @@ needed for permissions. Note that this is not needed for the case of
PC/SC Lite, as it has its own device configuration.
Patching 60-gnupg.rules
=======================
udev rules for Gnuk Token
=========================
In case of Debian, there is a file /lib/udev/rules.d/60-gnupg.rules.
This would be the place we need to change::
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)::
--- /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
@@ -24,25 +26,26 @@ This would be the place we need to change::
+
LABEL="gnupg_rules_end"
When we install "gnupg2" package only (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", ATTRS{idVendor}=="234b", ATTRS{idProduct}=="0000", \
ENV{ID_SMARTCARD_READER}="1", ENV{ID_SMARTCARD_READER_DRIVER}="gnupg"
Usually, udev daemon automatically handles for the changes of configuration
files. If not, please let the daemon reload rules::
# udevadm control --reload-rules
Have a another configuration for reGNUal
========================================
For reGNUal (upgrade feature of Gnuk),
I also have a file /etc/udev/rules.d/92-gnuk.rules::
# For updating firmware, permission settings are needed.
SUBSYSTEMS=="usb", ATTRS{idVendor}=="234b", ATTRS{idProduct}=="0000", \
ENV{ID_USB_INTERFACES}=="*:ff0000:*", GROUP="pcscd"
Configuration for ST-Link/V2
============================
udev rules for ST-Link/V2
=========================
This is for development, but I also have a file
/etc/udev/rules.d/10-stlink.rules::
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"
I have this in the file /etc/udev/rules.d/10-stlink.rules.