HTC G1 Cellphone
Add an X.509 Certificate Authority Root

A number of Android users, myself included, have posted forum complaints that they cannot read or send mail, or do other internet activities such as XMPP/Jabber, that involve SSL/TLS to a server whose X.509 host certificate is signed by a trust vendor or other origin of trust that is not in Android's certificate storage area. Here is the procedure to add your preferred X.509 root certificate, or to delete a certificate which you object to on political grounds.

If a reader has gotten to this page he/she probably is fully aware of the issues, but they should be repeated: you should only believe in a root certificate if you have obtained it from a trusted source, e.g. from the hand of a trusted system administrator or over an internal LAN on which the enemy is not likely to be operating, and if you trust the person who can wield its secret key to only certify hosts or persons whose hat color matches yours.

These instructions are for Android 1.5 Cupcake, but are likely to be fairly stable on back or future versions.

To add (or delete) a root certificate:

• R00t your phone.

• Make sure that the Java package on your development machine includes keytool; look for /usr/bin/keytool. My distro (OpenSuSE 11.1) provides java-1_6_0-sun-1.6.0.u13 which provides this program symlinked through /etc/alternatives/keytool).

• Make sure OpenSSL is installed. Look for the command /usr/bin/openssl.

• Obtain and install the Android SDK (software development kit). It is not necessary to have a functioning Eclipse setup for this, but you will be using adb.

• Check out a copy of the sources. See the Get Source page for how to do this. For these examples full path names in the source code are shown beginning with ~/android; modify to match where you put the sources. In many cases files and directories can be adjusted and may possibly change in future versions of Android.

• Change directory to ~/android/dalvik/libcore/security/src/main/files

• Download the BouncyCastle provider JAR file from http://www.bouncycastle.org/latest_releases.html. This JAR file is not included with Android, though the contents are in the distro; nonetheless I was not able to make the procedure work using the unpacked native source code. I planted the JAR file in the current directory, purely for convenience.

• In this directory is a subdirectory called cacerts, which contains authority root certificates. You need to add your own root certificate to the directory, or delete the politically poisonous one. The certificates are in PEM format: view the file and look for -----BEGIN CERTIFICATE-----, a lot of base64 encoded stuff, down to -----END CERTIFICATE-----. A text description may come before or after the boundary lines; it will be ignored. The certificate files are named after their subject hashes. The naming is unimportant, but you should import only one copy of each certificate; the typical subject hash links used in OpenSSL will confuse the script and would have to be excluded one way or another, if present.

  To display a certificate:

  openssl x509 -in cacerts/e4a7f639.0 -noout -text

  To determine the subject hash (append .0 in the likely case of no duplicates):

  openssl x509 -in example-com.pem -noout -subject_hash

• You will find ./cacerts.bks which is the pre-built certificate store. It will end up as /system/etc/security/cacerts.bks and is bit-for-bit identical to this file (before hacking). The scripts assume that this file may be removed at the start, being created anew by keytool.

• You will also find ./certimport.sh which is a wrapper that calls keytool. However, the needed JAR file is not present and some of the other pathnames and options do not seem to be functional. Likely this is the script that one of the real developers used, at some time in the past, to create ./cacerts.bks. We're going to need to update this script.

• The attached file certimportJ is the updated script. It wants on the command line the names of the keystore file and of the certificates to put in it; if a directory is found all the files in it are added. For the Android source situation call it like this (assuming the script and the JAR file were deposited in the current directory):

  ./certimportJ cacerts.bks cacerts

• The key item in this script is that it calls keytool with the following parameters for each certificate. Bash syntax is used to pipe the output of openssl into keytool. Each parameter is shown on a separate line to make it more readable. In the filenames I am assuming that the script is executed in the files directory.

  COUNTER=0
  keytool \
  -importcert \
  -v \
  -noprompt \
  -trustcacerts \
  -alias cert$((COUNTER++)) \
  -file <(openssl x509 -in $cert -outform DER) \
  -keystore ./cacerts.bks \
  -storetype BKS \
  -storepass SillyNoKeysHere \
  -provider org.bouncycastle.jce.provider.BouncyCastleProvider \
  -providerpath $PWD/bcprov-jdk16-143.jar

  Notes on the parameters:

  • COUNTER=0 : The script iterates over all the scripts and this variable is used to make a unique alias for each one. If the alias were a short form of the issuer's name it would be more useful.
  • keytool
  • -importcert : There are a lot of possible operations; use -help to show them all. Options have only one hyphen, unlike GNU long options.
  • -v : It will report that it successfully added the certificate.
  • -noprompt : If used interactively, keytool will ask for confirmation to add the certificate. We don't want that.
  • -trustcacerts : I'm not sure what happens if you omit this, but it can't be good. I exepct that the keystore has separate sections for user certificates and root certificates, and this option selects the latter.
  • -alias cert$((COUNTER++)) : A unique alias is needed. In Android it is never shown to the user, but other software can report which root certificate is involved in authentication using this alias.
  • -file <(openssl x509 -in $cert -outform DER) : This is the certificate to be added, in DER (binary) format. A bash syntax is used to pipe it in from an openssl command line. $cert represents the filename of the PEM format certificate.
  • -keystore ./cacerts.bks : This is the output file, which will be created when keytool is run the first time.
  • -storetype BKS : There are several format possibilities; BKS is what Android uses. I didn't investigate all the possibilities for the format.
  • -storepass SillyNoKeysHere : If private (secret) keys were included in the keystore a master password would be important, but that is not the situation here. In any case a password must be provided even if irrelevant.
  • -provider org.bouncycastle.jce.provider.BouncyCastleProvider : Keytool's Java will call methods of this class.
  • -providerpath $PWD/bcprov.jar : This is the JAR file containing an implementation of the provider class. You will need to edit the script or rename the file so keytool refers to the actual JAR file. I don't know if a full path name is required, probably not, but I decided not to tempt fate.

• Now you have a keystore file that includes your root certificate. Here is how to get it onto your phone.

  • Connect the USB cable.
  • Execute: adb push ./cacerts.bks /sdcard/cacerts.bks
  • Execute: adb shell
  • Execute (in the phone's shell): su root
  • Remount the /system partition in read-write mode. It should be sufficient to do (on the host system) adb remount, but I'm getting a permission problem, so here is how to do it by hand.
    • Execute: cat /proc/mounts ; look for /dev/block/mtdblock3 /system yaffs2 ro 0 0 (in the unlikely event of future alterations to the partitioning, adjust the following mount command to match what's actually in /proc/mounts).
    • Execute: mount -o remount,rw -t yaffs2 /dev/block/mtdblock3 /system
    • Execute cat /proc/mounts again and make sure /system now has the rw option.
  • Execute: cd /system/etc/security
  • Execute: ls -l ; you should see cacerts.bks, mode 644, owner root:root. If you're not too familiar with UNIX, the mode code will be shown as -rw-r--r--.
  • Execute: mv cacerts.bks cacerts.bks.orig ; you're saving the original keystore in case of problems. Of course, skip this step if you've already saved the original version.
  • Have you installed busybox and made a symbolic link for the cp (copy) command? Use whichever of these command lines is going to work for you, to bring in the new keystore from where you left it on the SD card. Note the dot representing the current directory, as the destination of cp.

    cp /sdcard/cacerts.bks .
dd if=/sdcard/cacerts.bks of=./cacerts.bks

  • Execute: chmod 644 cacerts.bks ; the file's mode comes out wrong, most likely because the shell's umask is not set, and you need to fix it. Afterward do ls -l and compare to the result seen previously.
  • If you're anally retentive, remount /system read-only by repeating the above remount steps interchanging ro and rw, but you're just going to reboot your phone, so don't bother.
  • Exit from the phone's shell (type exit twice) and disconnect the USB cable.
  • The Dalvik virtual machine apparently caches the keystore -- the old one. So restart Dalvik. How do you do that? Reboot. (Unlock the screen, then hold down the red button until you get the dialog box for turning off power.)

Now you should be able to connect to your SSL/TLS servers without being hassled about certificates issued by an untrusted origin of trust.

This issue has been posted on Android's bug system as issue 3237. It has been merged into an earlier similar thread, Android bug 1016.