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

Update readme

Browse Source
This commit is contained in:
Deon Spengler
2022-07-16 23:28:47 +02:00
parent b8ada80163
commit d6c040400a
1 changed files with 6 additions and 262 deletions
Download Patch File Download Diff File Expand all files Collapse all files

268
README → README.md
View File

@@ -1,201 +1,17 @@
Gnuk - An Implementation of USB Cryptographic Token for GnuPG
Version 1.2.20
2021-04-22
Niibe Yutaka
Free Software Initiative of Japan
Release Notes
=============
This is the release of Gnuk, version 1.2.20.
It has supports of Ed25519 and X25519 (ECDH on Curve25519). It also
has experimental support of ECDSA (on NIST P256 and secp256k1) and
ECDH (on NIST P256 and secp256k1).
It also supports RSA-4096, but users should know that it takes more
than 8 seconds to sign/decrypt. Key generation of RSA-4096 just fails,
because the device doesn't have enough memory.
It supports new KDF-DO feature. To use the feature, you need to use
newer GnuPG (2.2.6 or later). You need to prepare the KDF-DO on your
token by the card-edit/kdf-setup command of GnuPG.
With FST-01SZ and GNU/Linux emulation, experimental ack button support
is available for test.
Please note that version 1.2 implementation has major incompatible
changes to Gnuk 1.0.x. Specifically, it supports overriding key
import, but importing keys (or generating keys) results password
reset. Also, you need to import private keys before changing your
password. Please update your old documentation for Gnuk Token, so
that the instruction of importing keys won't cause any confusion.
***Note:*** *This fork of Gnuk fixes some compiling bugs and focuses on using the ST-Link v2 clone hardware.*
Here is the link to the original project: <https://alsa.debian.org/gnuk-team/gnuk/gnuk>
What's Gnuk?
============
Gnuk is an implementation of USB cryptographic token for GNU Privacy
Guard. Gnuk supports OpenPGP card protocol version 3, and it runs on
STM32F103 processor (and its compatible).
Gnuk is an implementation of USB cryptographic token for GNU Privacy Guard. Gnuk supports OpenPGP card protocol version 3, and it runs on STM32F103 processor (and its compatible). Gnuk allows one to converting a Cheap $2 ST-Link v2 clone into a Hardware GPG Key.
I wish that Gnuk will be a developer's soother who uses GnuPG. I have
been nervous of storing secret key(s) on usual secondary storage.
There is a solution with OpenPGP card, but it is not the choice for
me, as card reader is not common device. With Gnuk, this issue will
be solved by a USB token.
It has supports of Ed25519 and X25519 (ECDH on Curve25519). It also has experimental support of ECDSA (on NIST P256 and secp256k1) and ECDH (on NIST P256 and secp256k1).
Please look at the graphics of "gnuk.svg" for the software name. My
son used to be with his NUK(R), always, everywhere. Now, I am with a
USB Cryptographic Token by "Gnuk", always, everywhere.
FAQ
===
Q0: How Gnuk USB Token is superior than other solutions (OpenPGP
card 2.0/3.3/3.4, YubiKey, etc.) ?
https://www.g10code.de/p-card.html
https://www.yubico.com/
A0: Good points of Gnuk are:
* If you have skill of electronics and like DIY, you can build
Gnuk Token cheaper (see Q8-A8).
* You can study Gnuk to modify and to enhance. For example, you
can implement your own authentication method with some sensor
such as an acceleration sensor.
* It is "of Free Software"; Gnuk is distributed under GPLv3+,
"by Free Software"; Gnuk development requires only Free Software
(GNU Toolchain, Python, etc.),
"for Free Software"; Gnuk supports GnuPG.
Q1: What kind of key algorithm is supported?
A1: Gnuk version 1.0 only supports RSA-2048.
Gnuk version 1.2.x supports 255-bit EdDSA, as well as RSA-4096.
(Note that it takes long time to sign with RSA-4096.)
Q2: How long does it take for digital signing?
A2: It takes a second and a half or so for RSA-2048.
It takes more than 8 seconds for RSA-4096.
Q3: What's your recommendation for target board?
A3: Orthodox choice is Olimex STM32-H103.
FST-01SZ (Flying Stone Tiny 01 SZ) is available for sale, and it
is a kind of the best choice, hopefully. If you have a skill of
electronics, STM32 Nucleo F103 is the best choice for experiment.
Q4: What's version of GnuPG are you using?
A4: In Debian GNU/Linux system, I use GnuPG modern 2.2.23.
Q5: What's version of pcscd and libccid are you using?
A5: I don't use them, pcscd and libccid are optional, you can use Gnuk
Token without them.
I tested pcscd 1.5.5-4 and libccid 1.3.11-2 which were in Debian
squeeze.
Q6: What kinds of hardware is required for development?
A6: You need a target board plus a JTAG/SWD debugger. If you just
want to test Gnuk for target boards with DfuSe, JTAG debugger is
not the requirement. Note that for real use, you need JTAG/SWD
debugger to enable flash ROM protection.
Q7: How much does it cost?
A7: Olimex STM32-H103 plus ARM-USB-TINY-H cost 70 Euro or so.
Q8: How much does it cost for DIY version?
A8: STM32 Nucleo F103 costs about $10 USD.
Q9: I got an error like "gpg: selecting openpgp failed: ec=6.108", what's up?
A9: Older GnuPG's SCDaemon has problems for handling insertion/removal of
card/reader. When your newly inserted token is not found by
GnuPG, try killing scdaemon and let it to be invoked again. I do:
$ gpg-connect-agent "SCD KILLSCD" "SCD BYE" /bye
and confirm scdaemon doesn't exist, then,
$ gpg-connect-agent learn /bye
Qa: With GNOME 2, I can't use Gnuk Token for SSH. How can we use it for SSH?
Aa: You need to deactivate seahorse-agent and gnome-keyring, but use
gpg-agant for the role of ssh-agent. For gnome-keyring please do:
$ gconftool-2 --type bool --set /apps/gnome-keyring/daemon-components/ssh false
Qb: With GNOME 3.0, I can't use Gnuk Token at all. Why?
Ab: That's because gnome-keyring-daemon interferes GnuPG. Type:
$ gnome-session-properties
and at the tab of "Startup Programs", disable check buttons for
"GPG Password Agent" and "SSH Key Agent".
Qc: With GNOME 3.x (x >= 8?), I can't use Gnuk Token at all. Why?
Ac: That's because gnome-keyring-daemon interferes GnuPG. Please
disable the invocation of gnome-keyring-daemon. In Debian
wheezy, it's in the files /etc/xdg/autostart/gnome-keyring-ssh.desktop
and /etc/xdg/autostart/gnome-keyring-gpg.desktop.
We have a line something like:
OnlyShowIn=GNOME;Unity;MATE;
Please edit this line to:
OnlyShowIn=
Qd: Do you know a good SWD debugger to connect FST-01 or something?
Ad: ST-Link/V2 is cheap one. We have a tool/stlinkv2.py as flash ROM
writer program. STM32 Nucleo F103 comes with the valiant of
ST-Link/V2. Note that the firmware of ST-Link/V2 is proprietary.
So, in case of transparency matters, ST-Link/V2 would not be your
choice.
I care transparency for our process of manufacturing FST-01SZ (and
better control by Free Software, in general), thus, I develop
BBG-SWD, SWD debugger by BeagleBone Green.
I use ST-Link/V2 for daily development. For serious task like
flashing product, I use BBG-SWD.
Tested features
===============
Gnuk is tested by test suite. Please see the "tests" directory.
* Personalization of the card
* Changing Login name, URL, Name, Sex, Language, etc.
* Password handling (PW1, RC, PW3)
* Key import for three types:
* key for digital signing
* key for decryption
* key for authentication
* PSO: Digital Signature
* PSO: Decipher
* INTERNAL AUTHENTICATE
* Changing value of password status bytes (0x00C4): forcesig
* Verify with pin pad
* Modify with pin pad
* Card holder certificate (read)
* Removal of keys
* Key generation on device side for RSA-2048
* Overriding key import
Original features of Gnuk, tested manually lightly:
* OpenPGP card serial number setup
* Card holder certificate (write by UPDATE BINARY)
* Upgrading with "EXTERNAL AUTHENTICATE" by reGNUal
Targets
=======
We use Olimex STM32-H103 board and Flying Stone Tiny 01 (FST-01).
With DfuSe support, STBee is also our targets. But this target with
DfuSe is for experiment only, because it is impossible for DfuSe to
disable read from flash. For real use, please consider killing DfuSe
and enabling read protection using JTAG debugger.
It also supports RSA-4096, but users should know that it takes more than 8 seconds to sign/decrypt. Key generation of RSA-4096 just fails, because the device doesn't have enough memory.
Gnuk supports the Key Derived Function (KDF) functionality. With the KDF function enabled, the PIN is stored as a hash on the Gnuk. To use the feature, you need to use GnuPG (2.2.6 or later). The KDF setting needs to be enabled before any keys is put on the Gnuk. Once a key has been placed on the Gnuk and changes to the KDF settings will be prevented until the Gnuk has been reset. Your Gnuk token can be configured with the card-edit/kdf-setup command of GnuPG.
Build system and Host system
============================
@@ -239,69 +55,6 @@ able to access everything on the Token, regardless of its protections.
Private keys, and other information should be protected properly.
External source code
====================
Gnuk is distributed with external source code.
* chopstx/ -- Chopstx 1.21
We use Chopstx as the kernel for Gnuk.
Chopstx is distributed under GPLv3+ (with a special exception).
* polarssl/ -- based on PolarSSL 1.2.10 (now mbedTLS)
Souce code taken from: http://polarssl.org/
We use PolarSSL for RSA computation, and AES encryption/decryption.
PolarSSL is distributed under GPLv2+. We use PolarSSL under GPLv3
as our options.
The file include/polarssl/bn_mul.h is heavily modified for ARM
Cortex-M3.
The function rsa_private in polarssl/library/rsa.c is modified so
that it doesn't check T against N. The function rsa_pkcs1_sign is
modified to avoid warnings in case of !POLARSSL_PKCS1_V21.
The functions rsa_pkcs1_verify and rsa_rsassa_pkcs1_v15_verify in
include/polarssl/rsa.h and polarssl/library/rsa.c are modified
(fixed) for last argument SIG, as the memory at SIG aren't modified
by those routines.
The constant POLARSSL_MPI_MAX_SIZE in include/polarssl/bignum.h is
modified for 2048-bit keys only Gnuk.
The function mpi_mul_hlp in library/bignum.c is modified for more
optimization for ARM Cortex-M3. Functions mpi_montred, mpi_sub_hlp,
mpi_sub_abs, mpi_mul_mpi, mpi_montmul, and mpi_exp_mod are modified
to avoid side channel attacks. Note that we don't use RSA-blinding
technique for Gnuk. Function mpi_gen_prime and mpi_is_prime are
modified to use Fouque-Tibouchi method. Function mpi_exp_mod is
modified to use new function mpi_montsqr for speed up.
The file library/aes.c is modified so that some constants can
go to .sys section.
The file include/polarssl/config.h are modified not to define
POLARSSL_HAVE_LONGLONG to avoid linking libgcc, to define
POLARSSL_AES_ROM_TABLES to have AES tables, not to define
POLARSSL_CIPHER_MODE_CTR, POLARSSL_FS_IO, POLARSSL_PKCS1_V21,
POLARSSL_SELF_TEST, and POLARSSL_PADLOCK_C, and only define
POLARSSL_GENPRIME when defined KEYGEN_SUPPORT.
And polarssl/library/bignum.c is modified to work on 64-bit machine.
Aurelien Jarno also modified:
polarssl/include/polarssl/bn_mul.h
polarssl/library/bignum.c
See ChangeLog (and/or history of git) for detail.
USB vendor ID and product ID (USB device ID)
============================================
@@ -350,14 +103,6 @@ your own USB vendor ID and product ID. Please replace vendor string
and possibly product string to yours, when you modify Gnuk.
Host Requirements
=================
For GNU/Linux, PC/SC service is an option, you can use GnuPG's
internal CCID driver instead. If you chose using PC/SC service,
libccid version >= 1.3.11 is recommended for GNU/Linux.
How to compile
==============
@@ -629,4 +374,3 @@ Foot note
==========
* NUK(R) is a registered trademark owend by MAPA GmbH, Germany.
--