Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/Nitrokey/nitrokey-start-firmware

A mirror of Gnuk's 1.0.x and 1.2.x branches.
https://github.com/Nitrokey/nitrokey-start-firmware

Last synced: 13 days ago
JSON representation

A mirror of Gnuk's 1.0.x and 1.2.x branches.

Awesome Lists containing this project

README 

        
Gnuk - An Implementation of USB Cryptographic Token for GnuPG



							 Version 1.2.19

							     2021-10-12

							   Niibe Yutaka

				      Free Software Initiative of Japan



Release Notes

=============



This is the release of Gnuk, version 1.2.19, which has major

incompatible changes to Gnuk 1.0.x.  Specifically, it now 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 documentation for Gnuk Token, so

that the instruction of importing keys won't cause any confusion.



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.  Please note that this is

experimental.  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.



With FST-01SZ and GNU/Linux emulation, experimental ack button support

is available for test.



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).



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.



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.



Build system and Host system

============================



Makefile is written for GNU make.  You need Bash 4.x for configure.



If your bash is not installed as /bin/bash, you need to run configure

script prepending 'bash' before './configure'.



Some tools are written in Python.  If your Python is not installed as

/usr/bin/python, please prepend 'python' or 'python3' for your command

invocation.  I use Python 3.8 and PyUSB 1.0.2.



Source code

===========



Gnuk source code is under src/ directory.



Note that SHA-2 hash function implementation, src/sha256.c, is based

on the original implementation by Dr. Brian Gladman.  See:



  http://brg.a2hosted.com//oldsite/cryptography_technology/sha/index.php

(was at:

 http://gladman.plushost.co.uk/oldsite/cryptography_technology/sha/index.php)



License

=======



It is distributed under GNU General Public Licence version 3 or later

(GPLv3+).  Please see src/COPYING.



Please note that it is distributed with external source code too.

Please read relevant licenses for external source code as well.



The author(s) of Gnuk expect users of Gnuk will be able to access the

source code of Gnuk, so that users can study the code and can modify

if needed.  This doesn't mean person who has a Gnuk Token should be

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.20



  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)

============================================



When you have a vendor ID and assign a product ID for Gnuk, edit the

file GNUK_USB_DEVICE_ID and add an entry for yours.  In this case,

please contact Niibe, so that it is listed to the file in the official

release of the source code.



When you are modifing Gnuk and installing the binary to device, you

should replace the vendor string and serial number to yours (in the

file GNUK_USB_DEVICE_ID and SERIALNO of the script of src/configure),

so that users can see it's not by original vendor, and it is modified

version.



FSIJ allows you to use USB device ID of FSIJ (234b:0000) for devices

with Gnuk under one of following conditions:



  * For everyone for experimental purpose:



    - You must not distribute a binary with FSIJ's USB device ID, but

      must use the binary by yourself only for your experiment.  Note

      that "Distributing binary" includes distributing a device which

      holds the binary.



  * For general individuals:



    - You must use your Gnuk device with a card serial number which is

      *not* by FSIJ.  Easy one would be a card serial number generated

      by chip unique ID.



  * For individuals with explicit permission from FSIJ.



    - You should have an assigned card serial number by FSIJ,

      please use that number for your device.

      (There a file 'GNUK_SERIAL_NUMBER' in the official release.)



FSIJ could give companies or business entities "second source

manufacturer" license to use USB device ID of FSIJ for devices with

unmodified version of Gnuk, provided they support Free Software and

respect users' freedom for computing.  Please ask FSIJ for the

license.



Otherwise, companies which want to distribute Gnuk devices, please use

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

==============



You need GNU toolchain and newlib for 'arm-none-eabi' target.



On Debian we can install the packages of gcc-arm-none-eabi

and its friends.  I'm using:



	binutils-arm-none-eabi	2.35.2-2+14+b2

	gcc-arm-none-eabi 	15:8-2019-q3-1+b1

	libnewlib-arm-none-eabi	3.3.0-1

	gdb-multiarch 		10.1-2



Or else, see https://launchpad.net/gcc-arm-embedded for preparation of

GNU Toolchain for 'arm-none-eabi' target.



Change directory to `src':



  $ cd gnuk-VERSION/src



Then, run `configure':



  $ ./configure --vidpid=



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.



Then, type:



  $ make



Then, we will have "gnuk.elf" under src/build directory.



If you are not the authorized vendor, please never distribute this

file of "gnuk.elf", which includes VID:PID in the image.  If you would

like to distribute the image (for example, to check if it's

reproducible or not), the file "gnuk-no-vidpid.elf" is the one with no

VID:PID.



How to install

==============



Olimex STM32-H103 board

-----------------------



If you are using Olimex JTAG-Tiny, type following to invoke OpenOCD

and write "gnuk.elf" to Flash ROM:



  $ openocd -f interface/ftdi/olimex-jtag-tiny.cfg \

            -f board/olimex_stm32_h103.cfg \

            -c "program build/gnuk.elf verify reset exit"



Command invocation is assumed in src/ directory.



Flying Stone Tiny 01

--------------------



If you are using Flying Stone Tiny 01, you need a SWD writer.



OpenOCD 0.9.0 now supports ST-Link/V2.  We can use it like:



  $ openocd -f interface/stlink-v2.cfg -f target/stm32f1x.cfg \

            -c "program build/gnuk.elf verify reset exit"



STBee

-----



Note that this is only for your experiment; Your private key materials

on the board can be accessed by DfuSe.



Reset the board with "USER" switch pushed.  Type following to write

to flash:



  # cd ../tool

  # ./dfuse.py ../src/build/gnuk.hex



Then, reset the board.



How to protect flash ROM

========================



To protect, invoke OpenOCD like (for FST-01):



  $ openocd -f interface/stlink-v2.cfg -f target/stm32f1x.cfg \

            -c init -c "reset halt" -c "stm32f1x lock 0" -c reset -c exit



After power-off / power-on sequence, the contents of flash ROM cannot

be accessible from JTAG debugger.



Unprotecting is:



  $ openocd -f interface/stlink-v2.cfg -f target/stm32f1x.cfg \

            -c init -c "reset halt" -c "stm32f1x unlock 0" -c reset -c exit



Upon unprotection, flash is erased.



Note that it would be still possible for some implementation of DfuSe

to access the contents, even if it's protected.  If you really want to

protect, killing DfuSe and accessing by JTAG debugger is recommended.



(Optional) Configure serial number and X.509 certificate

========================================================



This is completely optional.



For this procedure, you need python and pyscard (python-pyscard

package in Debian) or PyUSB (python-usb package in Debian).



(1) [pyscard] Stop scdaemon

    [PyUSB] Stop the pcsc daemon.



If scdaemon is running, please kill it, or you will get "Smartcard

Exception" by "Sharing violation".



  $ gpg-connect-agent "SCD KILLSCD" "SCD BYE" /bye



In case of PyUSB tool, you need to stop pcscd.



  # systemctl stop pcscd



(2) [Optional] Write fixed serial number



If you use fixed serial number in the file 'GNUK_SERIAL_NUMBER', you can do:



  $ EMAIL= ../tool/gnuk_put_binary_usb.py -s ../GNUK_SERIAL_NUMBER

  Writing serial number

  ...



(3) [Optional] Write card holder certificate



If you have card holder certificate binary file, you can do:



  $ ../tool/gnuk_put_binary_usb.py ../../.bin

  ../../.bin: 

  Updating card holder certificate

  ...



How to run

==========



Debug enabled

-------------



If you compiled with --enable-debug option, Gnuk has two interfaces

(one is CCID/ICCD device and another is virtual COM port).  Open

virtual COM port by:



  $ cu -l /dev/ttyACM0



and you will see debug output of Gnuk.



Testing Gnuk

------------



Type following command to see Gnuk runs:



  $ gpg --card-status



Besides, there is a functionality test under tests/ directory.  See

tests/README.



Personalize the Token, import keys, and change the password

-----------------------------------------------------------



You can personalize the token, putting your information like: Name,

Login name, Sex, Languages, URL.  To do so, GnuPG command is:



  $ gpg --card-edit



Note that the factory setting of user password is "123456" and admin

password is "12345678" as the specification.



It is recommended to create your keys on your computer, and import

them to Gnuk Token.  After you create your keys (they must be 2048-bit

RSA), you can import them.



Gnuk supports key generation, but this feature is young and should be

considered experimental.



For detail, please see documentation under doc/.  You can see the HTML

version at: https://www.fsij.org/doc-gnuk/



How to debug

============



We can use GDB.



  $ arm-none-eabi-gdb gnuk.elf



Inside GDB, we can connect OpenOCD by:



  (gdb) target remote localhost:3333



or



  (gdb) target extended-remote localhost:3333



You can see the output of PCSCD:



  # /etc/init.d/pcscd stop

  # LIBCCID_ifdLogLevel=7 /usr/sbin/pcscd --debug --foreground



You can observe the traffic of USB using "usbmon".  See the file:

linux/Documentation/usb/usbmon.txt



Firmware update

===============



See doc/note/firmware-update.



Git Repositories

================



Please use: https://salsa.debian.org/gnuk-team/gnuk/



You can get it by:

 

    $ git clone https://salsa.debian.org/gnuk-team/gnuk/gnuk.git



It's also available at: www.gniibe.org

You can browse at: https://git.gniibe.org/cgit/gnuk/gnuk.git/



I put Chopstx as a submodule of Git.  Please do this:



    $ git submodule update --init



Information on the Web

======================



For more information, please visit: https://www.fsij.org/gnuk/



Please see the FST-01 support pages:



    https://www.gniibe.org/category/fst-01.html



Please consider to join Gnuk-users mailing list:



    https://lists.gnupg.org/mailman/listinfo/gnuk-users



Your Contributions

==================



FSIJ welcomes your contributions.  Please assign your copyright

to FSIJ (if possible), as I do.



Foot note

==========



* NUK(R) is a registered trademark owend by MAPA GmbH, Germany.

--