For this spherical, I’m masking the Aventra MyEID PKI Card. I purchased a SIM-sized model to suit into an ACS ACR38T-IBS-R smartcard reader (it’s apparently now not made, and the ACT38T-D1 is supposed to interchange it). Why such specificity you might ask? As a result of you must make certain that your smartcard will work along with your reader, and that your reader can have a working driver for you system, and that your smartcard can have a working PKCS#11 driver in order that software program can speak to the smartcard. Fortunately there may be the OpenSC undertaking to cowl the PKCS#11 half, it implements the PKCS#11 communications commonplace for a lot of smartcards. On my Ubuntu/exact system, I needed to set up an additional driver, libacr38u, to get the ACR38T reader to indicate up on my system.
"safety

ACS ACR38-T-IBS
So let’s begin there and get this factor to indicate up! First we’d like some packages. The OpenSC packages are out-of-date in quite a lot of releases, you want model 0.13.0-Four or newer, so you must add our PPA (Private Package deal Archive) to get present variations, which embody a selected repair for the Aventra MyEID: (fingerprint: F50E ADDD 2234 F563):

sudo add-apt-repository ppa:guardianproject/ppa
sudo apt-get replace
sudo apt-get set up opensc libacr38u libacsccid1 pcsc-tools usbutils

Very first thing, I take advantage of lsusb within the terminal to see what USB units the Linux kernel sees, and fortunately it sees my reader:

$ lsusb
Bus 005 Machine 013: ID 072f:9000 Superior Card Methods, Ltd ACR38 AC1038-based Sensible Card Reader

Subsequent, its time to strive pcsc_scan to see if the system can see the smartcard put in within the reader. If every thing is put in and so as, then pcsc_scan will report this:

`

$ pcsc_scan
PC/SC system scanner
V 1.4.18 © 2001-2011, Ludovic Rousseau <[email protected]>
Compiled with PC/SC lite model: 1.7.4
Utilizing reader plug’n play mechanism
Scanning current readers…
0: ACS ACR38U 00 00

Thu Mar 27 14:38:36 2014
Reader 0: ACS ACR38U 00 00
Card state: Card inserted,
ATR: 3B F5 18 00 00 81 31 FE 45 4D 79 45 49 44 9A
[snip]

`

If pcsc_scan can not see the cardboard, then issues won’t work. Strive re-seating the smardcard within the reader, be sure to have all the correct packages put in, and if you happen to can see the reader in lsusb. In case your smartcard or reader can’t be learn, then pcsc_scan will report one thing like this:

$ pcsc_scan 
PC/SC system scanner
V 1.4.18 (c) 2001-2011, Ludovic Rousseau <[email protected]>
Compiled with PC/SC lite model: 1.7.4
Utilizing reader plug'n play mechanism
Scanning current readers...
Ready for the primary reader...

Shifting proper alongside… now pcscd can see the smartcard, so we will begin enjoying with utilizing the OpenSC instruments. These are wanted to setup the cardboard, put PINs on it for entry management, and add keys and certificates to it. The final annoying little preparation duties are discovering the place opensc-pkcs11.so is put in and the “slot” for the signing key within the card. These will go right into a config file which keytool and jarsigner want. To get this data on Debian/Ubuntu/and many others, run these:

$ dpkg -S opensc-pkcs11.so
opensc: /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so
$ pkcs11-tool --module /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so 
>     --list-slots
Accessible slots:
Slot 0 (0xffffffffffffffff): Digital hotplug slot
  (empty)
Slot 1 (0x1): ACS ACR38U 00 00
  token label        : MyEID (signing)
  token producer : Aventra Ltd.
  token mannequin        : PKCS#15
  token flags        : rng, login required, PIN initialized, token initialized
  {hardware} model   : 0.0
  firmware model   : 0.0
  serial num         : 0106004065952228

That is the information wanted to place right into a opensc-java.cfg, which keytool and jarsigner want with the intention to speak to the Aventra HSM. The title, library, and slot fields are important, and the outline is useful. Right here is how the opensc-java.cfg utilizing the above info appears:

title = OpenSC
description = SunPKCS11 w/ OpenSC Sensible card Framework
library = /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so
slot = 1

Now every thing ought to be prepared for initializing the HSM, producing a brand new key, and importing that key to the HSM. This course of generates the important thing and certificates, places them into information, then uploads them to the HSM. Meaning it is best to solely run this course of on a trusted machine, definitely with some form of disk encryption, and ideally on a machine that’s not related to a community, operating an OS that has by no means been related to the web. A reside CD is one good instance, I like to recommend Tails on a USB thumb drive operating with the safe persistent retailer on it (we’ve got been working right here and there on making a TAILS-based distro particularly for managing keys, we name it CleanRoom).

HSM plugged into a laptopHSM plugged right into a laptop computer

First off, the HSM must be initialized, then arrange with a signing PIN and a “Security Officer” PIN (which suggests principally an “admin” or “root” PIN). The signing PIN is the one you’ll use for signing APKs, the “Security Officer PIN” (SO-PIN) is used for modifying the HSM setup, like importing new keys, and many others. As a result of there are such a lot of steps within the course of, I’ve written up scripts to run via the entire steps. If you wish to see the small print, learn the scripts. The following step is to generate the important thing utilizing openssl and add it to the HSM. Then the HSM must be “finalized”, which suggests the PINs are activated, and keys can’t be uploaded. Don’t fear, so long as you have got the SO-PIN, you may erase the HSM and re-initialize it. However watch out! Many HSMs will completely self-destruct if you happen to enter within the fallacious PIN too many occasions, some will do this after solely three fallacious PINs! So long as you haven’t finalized the HSM, any PIN will work, so mess around quite a bit with it earlier than finalizing it. Run the init and key add process a couple of occasions, strive signing an APK, and many others. Take observe: the script will generate a random password for the key information, then echo that password when it completes, so make certain nobody can see your display while you generate the true key. Alright, right here goes!

code $ git clone https://github.com/guardianproject/smartcard-apk-signing
code $ cd smartcard-apk-signing/Aventra_MyEID_Setup
Aventra_MyEID_Setup $ ./setup.sh 
Edit pkcs15-init-options-file-pins to place within the PINs you wish to set:
Aventra_MyEID_Setup $ emacs pkcs15-init-options-file-pins
Aventra_MyEID_Setup $ ./setup.sh 
Utilizing reader with a card: ACS ACR38U 00 00
Connecting to card in reader ACS ACR38U 00 00...
Utilizing card driver MyEID playing cards with PKCS#15 applet.
About to erase card.
PIN [Security Officer PIN] required.
Please enter PIN [Security Officer PIN]: 
Utilizing reader with a card: ACS ACR38U 00 00
Connecting to card in reader ACS ACR38U 00 00...
Utilizing card driver MyEID playing cards with PKCS#15 applet.
About to create PKCS #15 meta construction.
Utilizing reader with a card: ACS ACR38U 00 00
Connecting to card in reader ACS ACR38U 00 00...
Utilizing card driver MyEID playing cards with PKCS#15 applet.
Discovered MyEID
About to generate key.
Utilizing reader with a card: ACS ACR38U 00 00
Connecting to card in reader ACS ACR38U 00 00...
Utilizing card driver MyEID playing cards with PKCS#15 applet.
Discovered MyEID
About to generate key.
subsequent generate a key with ./gen.sh then ./finalize.sh
Aventra_MyEID_Setup $ cd ../openssl-gen/
openssl-gen $ ./gen.sh 
Utilization: ./gen.sh "CertDName" [4096]
  for instance:
  "/C=US/ST=New York/O=Guardian Challenge Check/CN=take a look at.guardianproject.data/emailAddress=take a look [email protected]"
openssl-gen $ ./gen.sh "/C=US/ST=New York/O=Guardian Challenge Check/CN=take a look at.guardianproject.data/emailAddress=take a look [email protected]"
Producing key, be affected person...
2048 semi-random bytes loaded
Producing RSA personal key, 2048 bit lengthy modulus
.......................................+++
..................................................+++
e is 65537 (0x10001)
Signature okay
topic=/C=US/ST=New York/O=Guardian Challenge Check/CN=take a look at.guardianproject.data/emailAddress=take a look [email protected]
Getting Personal key
writing RSA key
Your HSM will immediate you for 'Safety Officer' aka admin PIN, watch for it!
Enter vacation spot keystore password:  
Entry for alias 1 efficiently imported.
Import command accomplished:  1 entries efficiently imported, Zero entries failed or cancelled
[Storing keystore]
Key fingerprints for reference:
MD5 Fingerprint=90:24:68:F3:F3:22:7D:13:8C:81:11:C3:A4:B6:9A:2F
SHA1 Fingerprint=3D:9D:01:C9:28:BD:1F:F4:10:80:FC:02:95:51:39:F4:7D:E7:A9:B1
SHA256 Fingerprint=C6:3A:ED:1A:C7:9D:37:C7:B0:47:44:72:AC:6E:FA:6C:3A:B2:B1:1A:76:7A:4F:42:CF:36:0F:A5:49:6E:3C:50
The general public information are: certificates.pem publickey.pem request.pem
The key information are: secretkey.pem certificates.p12 certificates.jkr
The passphrase for the key information is: fTQ*he-[:y+69RS+W&+!*0O5ipercentn
openssl-gen $ cd ../Aventra_MyEID_Setup/
Aventra_MyEID_Setup $ ./finalize.sh 
Utilizing reader with a card: ACS ACR38U 00 00
Connecting to card in reader ACS ACR38U 00 00...
Utilizing card driver MyEID playing cards with PKCS#15 applet.
Discovered MyEID
About to delete object(s).
Your HSM is prepared to be used! Put the key key information someplace encrypted and secure!

Now your HSM ought to be prepared to be used for signing. You possibly can strive it out with keytool to see what’s on it, utilizing the signing PIN not the Safety Officer PIN:

`

smartcard-apk-signing $ /usr/bin/keytool -v
> -providerClass solar.safety.pkcs11.SunPKCS11
> -providerArg opensc-java.cfg
> -providerName SunPKCS11-OpenSC -keystore NONE -storetype PKCS11
> -list
Enter keystore password:

Keystore kind: PKCS11
Keystore supplier: SunPKCS11-OpenSC

Your keystore incorporates 1 entry

Alias title: 1
Entry kind: PrivateKeyEntry
Certificates chain size: 1
Certificates” width=”219″ peak=”119″ class=”alignleft size-full wp-image-12311″ />:
Proprietor: EMAILADDRESS=take a look [email protected], CN=take a look at.guardianproject.data, O=Guardian Challenge Check, ST=New York, C=US
Issuer: EMAILADDRESS=take a look [email protected], CN=take a look at.guardianproject.data, O=Guardian Challenge Check, ST=New York, C=US
Serial quantity: aa6887be1ec84bde
Legitimate from: Fri Mar 28 16:41:26 EDT 2014 till: Mon Aug 12 16:41:26 EDT 2041
Certificates fingerprints:
MD5: 90:24:68:F3:F3:22:7D:13:8C:81:11:C3:A4:B6:9A:2F
SHA1: 3D:9D:01:C9:28:BD:1F:F4:10:80:FC:02:95:51:39:F4:7D:E7:A9:B1
SHA256: C6:3A:ED:1A:C7:9D:37:C7:B0:47:44:72:AC:6E:FA:6C:3A:B2:B1:1A:76:7A:4F:42:CF:36:0F:A5:49:6E:3C:50
Signature algorithm title: SHA1withRSA
Model: 1



`

And let’s strive signing an precise APK utilizing the arguments that Google recommends, once more, utilizing the signing PIN:

smartcard-apk-signing $ /usr/bin/jarsigner -verbose 
>     -providerClass solar.safety.pkcs11.SunPKCS11 
>     -providerArg opensc-java.cfg -providerName SunPKCS11-OpenSC 
>     -keystore NONE -storetype PKCS11 
>     -sigalg SHA1withRSA -digestalg SHA1 
>     bin/LilDebi-release-unsigned.apk 1
Enter Passphrase for keystore: 
   including: META-INF/1.SF
   including: META-INF/1.RSA
  signing: property/busybox
  signing: property/complete-debian-setup.sh
  signing: property/configure-downloaded-image.sh
  signing: property/create-debian-setup.sh
  signing: property/debian-archive-keyring.gpg
  signing: property/debootstrap.tar.bz2
  signing: property/e2fsck.static
  signing: property/gpgv
  signing: property/lildebi-common
[snip]

Now we’ve got a working, however elaborate, course of for establishing a {Hardware} Safety Module for signing APKs. As soon as the HSM is setup, utilizing it ought to be fairly simple. Subsequent steps are to work out as many kinks on this course of as attainable so this would be the default strategy to signal APKs. Meaning issues like determining how Java could be pre-configured to make use of OpenSC within the Debian package deal, in addition to together with all related fixes within the pcscd and opensc packages. Then the last word is so as to add assist for utilizing HSMs in Android’s generated construct information just like the construct.xml for ant that’s generated by android replace undertaking. Then folks might simply plug within the HSM and run ant launch and have a signed APK!