View source for PKCS11 token usage with opensc

== Summary == 

Basic command line usage of a PKCS#11 token

== Requirements ==

* Operating system: Ubuntu 18.04 bionic amd64
* Packages: opensc >= 0.18 opensc-pkcs11

== Description ==

The documentation uses the [[Feitian ePass 2003 FIPS 140-2 Level 2]] tokens which can be used with the open source project [https://github.com/OpenSC/OpenSC OpenSC].

The default configuration of the tokens, according to the manufacturer, is as follows:

* Default User PIN: 12345678
* Default SO PIN: entersafe

=== Install opensc-0.18 ===

To install opensc-0.18 on Ubuntu 18.04 download the three source package files from https://packages.ubuntu.com/cosmic/opensc and store them in a build folder. Then run

 $ dpkg-source -x opensc_0.18.0-3ubuntu2.dsc                                                                                                                                                             
 gpgv: Signature made Tue 10 Jul 2018 14:45:55 CEST
 gpgv:                using RSA key 92978A6E195E4921825F7FF0F34F09744E9F5DD9
 gpgv: Can't check signature: No public key
 dpkg-source: warning: failed to verify signature on ./opensc_0.18.0-3ubuntu2.dsc
 dpkg-source: info: extracting opensc in opensc-0.18.0
 dpkg-source: info: unpacking opensc_0.18.0.orig.tar.gz
 dpkg-source: info: unpacking opensc_0.18.0-3ubuntu2.debian.tar.xz
 dpkg-source: info: applying ppc64el-fix.patch
                                                                                                                                                                                                           
 $ cd opensc-0.18.0
 
 $ dpkg-buildpackage                                                                                                                                                                                     
 dpkg-buildpackage: info: source package opensc
 dpkg-buildpackage: info: source version 0.18.0-3ubuntu2
 [...]
 dpkg-deb: building package 'opensc-pkcs11' in '../opensc-pkcs11_0.18.0-3ubuntu2_amd64.deb'.
 dpkg-deb: building package 'opensc' in '../opensc_0.18.0-3ubuntu2_amd64.deb'.
 dpkg-deb: building package 'opensc-dbgsym' in 'debian/.debhelper/scratch-space/build-opensc/opensc-dbgsym_0.18.0-3ubuntu2_amd64.deb'.
 dpkg-deb: building package 'opensc-pkcs11-dbgsym' in 'debian/.debhelper/scratch-space/build-opensc-pkcs11/opensc-pkcs11-dbgsym_0.18.0-3ubuntu2_amd64.deb'.
       Renaming opensc-dbgsym_0.18.0-3ubuntu2_amd64.deb to opensc-dbgsym_0.18.0-3ubuntu2_amd64.ddeb
       Renaming opensc-pkcs11-dbgsym_0.18.0-3ubuntu2_amd64.deb to opensc-pkcs11-dbgsym_0.18.0-3ubuntu2_amd64.ddeb
  dpkg-genbuildinfo
  dpkg-genchanges  >../opensc_0.18.0-3ubuntu2_amd64.changes
 dpkg-genchanges: info: not including original source code in upload
 dpkg-source --after-build opensc-0.18.0
 dpkg-buildpackage: info: binary and diff upload (original source NOT included)
 signfile opensc_0.18.0-3ubuntu2.dsc
 gpg: skipped "Gianfranco Costamagna <locutusofborg@debian.org>": No secret key
 gpg: dpkg-sign.HSiUXvK2/opensc_0.18.0-3ubuntu2.dsc: clear-sign failed: No secret key
 
 dpkg-buildpackage: error: failed to sign .dsc file
  
 $ sudo dpkg --install ../opensc_0.18.0-3ubuntu2_amd64.deb ../opensc-pkcs11_0.18.0-3ubuntu2_amd64.deb
 (Reading database ... 526489 files and directories currently installed.)
 Preparing to unpack .../opensc_0.18.0-3ubuntu2_amd64.deb ...
 [...]

=== First steps ===

We are going to get some basic informations using the command line tool [https://linux.die.net/man/1/pkcs11-tool pkcs11-tool]

List the number of available tokens:

 $ pkcs11-tool --module /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so -L
 Available slots:
 Slot 0 (0x0): Feitian ePass2003 00 00
 C_GetTokenInfo() failed: rv = CKR_TOKEN_NOT_PRESENT
 Slot 1 (0x4): Alcor Micro AU9560 01 00
   (empty)

Initialise the token for usage with opensc:

 $ pkcs15-init --erase-card --reader "Feitian ePass2003 00 00" 
 
 $ pkcs15-init --create-pkcs15 --profile pkcs15+onepin --label "myToken" --pin 123456 --puk 12345678 --reader "Feitian ePass2003 00 00"
 
 $ pkcs15-tool --dump  --reader "Feitian ePass2003 00 00"
 
 PKCS#15 Card [myToken]:
        Version        : 0
        Serial number  : 213C3C500003003D
        Manufacturer ID: EnterSafe
        Last update    : 20190415150218Z
        Flags          : EID compliant
 PIN [User PIN]
        Object Flags   : [0x3], private, modifiable
        ID             : 01
        Flags          : [0x32], local, initialized, needs-padding
        Length         : min_len:4, max_len:16, stored_len:16
        Pad char       : 0x00
        Reference      : 1 (0x01)
        Type           : ascii-numeric
        Path           : 3f005015
 
 $ pkcs11-tool --module /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so -L 
 Available slots:
 Slot 0 (0x0): Feitian ePass2003 00 00
  token label        : User PIN (myToken)
  token manufacturer : EnterSafe
  token model        : PKCS#15
  token flags        : login required, rng, token initialized, PIN initialized
  hardware version   : 0.0
  firmware version   : 0.0
  serial num         : 213C3C500003003D
  pin min/max        : 4/16

Erase the token:

 $ pkcs15-init --erase-card --reader "Feitian ePass2003 00 00"

=== Key Generation ===

  $ pkcs11-tool --module /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so --slot 0 --list-mechanisms
 Supported mechanisms:
  SHA-1, digest
  SHA256, digest
  SHA384, digest
  SHA512, digest
  MD5, digest
  RIPEMD160, digest
  GOSTR3411, digest
  ECDSA, keySize={256,256}, hw, sign
  ECDSA-SHA1, keySize={256,256}, hw, sign
  ECDSA-KEY-PAIR-GEN, keySize={256,256}, hw, generate_key_pair
  RSA-X-509, keySize={512,2048}, hw, decrypt, sign, verify
  RSA-PKCS, keySize={512,2048}, hw, decrypt, sign, verify
  SHA1-RSA-PKCS, keySize={512,2048}, sign, verify
  SHA256-RSA-PKCS, keySize={512,2048}, sign, verify
  SHA384-RSA-PKCS, keySize={512,2048}, sign, verify
  SHA512-RSA-PKCS, keySize={512,2048}, sign, verify
  MD5-RSA-PKCS, keySize={512,2048}, sign, verify
  RIPEMD160-RSA-PKCS, keySize={512,2048}, sign, verify
  RSA-PKCS-KEY-PAIR-GEN, keySize={512,2048}, generate_key_pair
 
 $ pkcs11-tool --module /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so --slot 0 --keypairgen --key-type rsa:2048 --label "my RSA key" --id 42 --login
 Logging in to "User PIN (myToken)".
 Please enter User PIN: 
 Key pair generated:
 Private Key Object; RSA 
   label:      my RSA key
   ID:         42
   Usage:      decrypt, sign, unwrap
 Public Key Object; RSA 2048 bits
   label:      my RSA key
   ID:         42
   Usage:      encrypt, verify, wrap

=== Sign Data ===

First we export the public key

 $ pkcs11-tool --module /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so --slot 0 --read-object --id 42 --type pubkey --output-file pubkey.der

Sign a file:

 $ pkcs11-tool --module /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so --slot 0 --sign --id 42 --mechanism SHA256-RSA-PKCS --input-file test.dat --output-file test.dat.sig --login                                                     
 Logging in to "User PIN (myToken)".
 Please enter User PIN: 
 Using signature algorithm SHA256-RSA-PKCS

And verify the signature:

 $ openssl pkeyutl -pubin -inkey pubkey.der -keyform der -verifyrecover -in test.dat.sig -pkeyopt rsa_padding_mode:pkcs1 -pkeyopt digest:SHA256|xxd                                                                                 
 00000000: b5bb 9d80 14a0 f9b1 d61e 21e7 96d7 8dcc  ..........!.....
 00000010: df13 52f2 3cd3 2812 f485 0b87 8ae4 944c  ..R.<.(........L
 
 $ sha256sum test.dat                                                                                                                                                                                                               
 b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c  test.dat


== Used Hardware ==

[[Feitian ePass 2003 FIPS 140-2 Level 2]]

== Courses ==

None yet

== References ==

* https://github.com/OpenSC/OpenSC
* https://github.com/OpenSC/OpenSC/wiki/Feitian-ePass2003
* https://linux.die.net/man/1/pkcs11-tool
* https://www.ftsafe.com/Products/PKI/Standard/Specification
[[Category:Documentation]]