Thursday, December 2, 2010

Accessing the Australian Taxation Office's Business Portal using the AUSkey system on Ubuntu Maverick v10.10

Background: Australian businesses interacting over the Internet with the ATO have always required public key infrastructure for secure communication and identification. Back in 2002 they posted out 3.5" floppy disks with the keys. In 2005 they upgraded to the Common-use Signing Interface (CSI) and posted out passwords. Now with their new AUSkey system they allow you to register and download your key all online. This article describes the new AUSkey system.

The ATO's support for end-users running Linux has been patchy. I've been using their CSI system on Ubuntu since 2008 thanks to threads like this. If you still have a valid CSI key, it should work fine on Maverick. Refer to this post for an easy install script for CSI.

The new AUSkey system has software for Win/Mac OS, but not Linux. In July 2010 they announced that they would officially support Ubuntu Linux by the end of the year. In this article they are quoted saying Nov 12th. And again they said it would be before Christmas. Unfortunately my BAS couldn't wait that long, and I sure-as-hell wasn't using my new SSO key+password in a Windows virtual machine (I'll refrain from ranting about using SSO for multiple government service on potentially malware-infected Windows PC's).

The AUSkey system follows the same bad design as the CSI: a Java applet wrapped in an OS-specific binary browser plug-in. It is relatively easy to pull the Java JAR files out and install them into Ubuntu. Similar to the approach used to get CSI working this may need to be reinstalled each time Java is updated on your PC.

Disclaimer: follow these instructions at your own risk. I am not responsible for your actions, including but not limited to you destroying your computer, its operating system or Java environment, or if your actions contradict any of the ATO's terms and conditions. According to the Terms & Conditions you accept when installing the AUSkey software, you're not allowed to disassemble or reverse engineer it. This solution involves neither disassembly nor reverse engineering, it simply copies the appropriate Java JAR libraries from an existing installation into the correct location in your Ubuntu Linux system.

Installation: Rather than describing the process in detail, I have written a small bash script that installs the AUSkey into Ubuntu. Download this bash script file and run it at the command line:
sudo bash
It uses Wine to install the AUSkey software and then copies the JAR files. Just click through the AUSkey installer accepting the Terms & Conditions and default settings. Refer to the disclaimer above, more details on the script are below.

Testing: Confirm the AUSkey software is working correctly by attempting to either login or register. If the software is not installed correctly, it will prompt you do to download the installer. Let me know in the comments if it does/doesn't work for you. It works perfectly for me on Ubuntu Linux "Maverick" v10.10, 64-bit using Firefox v3.6.12 (Maverick's default browser).

Keys: You can register for a new AUSkey online (without waiting for the postman) and this setup should work fine for downloading your initial key. However given it is experimental: you may want to make sure you don't mess-up the initial key download (you'd be stuck) by registering/downloading on a Win/Mac PC first. Once you're logged in you can register for additional keys using "Get Additional AUSkey". An email will be sent that allows the additional key to be downloaded into Ubuntu in the same way. Keys are stored in ~/AUSkey/keystore.xml. You can probably copy that file between PC's.

Script Details: The bash script needs to runs as root to install software and set the default Java plugin. The script is commented - read over it if you're worried. It shouldn't break your system but may affect other Java applications. Briefly it:
  • Purges any existing Sun Java v1.6 install files.
  • Installs Sun Java v1.6 browser plugin and Wine.
  • Sets "java-6-sun" as the default Java VM. 
  • Downloads the Windows AUSkey software from here.
  • Uses Wine to install the AUSkey software into a temporary Wine profile.
  • Copies the appropriate JAR files into: /usr/lib/jvm/java-6-sun/jre/lib/ext and lib/security
  • Cleans up.
Enjoy, let me know in the comments if this has helped!


  1. Well, this is interesting.

    I am doing this manually on a gentoo system, sun jre I installed the Windows Auskey on a Windows vm, then copied over the ext folder contents to my linux desktop.

    I left behind the security folder contents, because the files are already present for csi, although they are different versions.

    If I try it this way, when I go to install the auskey cert, it gets to the point where the applet loads, and you are prompted for a password. After this I get "An internal error occured, no error message is available". You can see the applet doing its thing briefly.

    So then I copy the security folder contents over, and start over, and in this case I get a message saying the applet cannot be loaded. So it almost works with the "wrong" security applets, but doesn't load at all with the new security applets.

    Do you think the jre 1.5 dependency is right? If you have any other tips, I'd appreciate any suggestions.

  2. In my original attempts I had similar behaviour after progressing through the cert install: hit install after entering the password then "no error message available" the same as Paul. If someone were to look at the ajax requests using Firebug at the point of clicking install they might see the javascript trying to establish a secure connection via an applet call and then dying. Hence my reason for copying the security folder: it worked perfectly after that.

    That said unfortunately it doesn't work today. The same Firebug investigations might have shown some user/OS detection javascript code that didnt seem to be doing anything at the time. Perhaps they've fixed that. I tried spoofing the user agent string to Win/Mac with no luck.

    The Windows installer drops the binaries for Sun Java(TM) SE Runtime Environment v1.6.0_17-b04.
    I had it working under linux with v1.6.0_22-b04. The Mac installer uses the OS's Java install: any ideas what java version that is? Cheers.

  3. Hi Rob, Thanks for posting this! I had a couple of issues which I was able to overcome.

    1. JAVA_HOME variable was not set for me by default, so I had to set that before running your script.

    2. One of the copied files in lib/security is called and it has a line:

    I had to comment this out as sunmscapi is Windows only and prevents the applet from starting. Maybe this file shouldn't be copied across in the first place.

    It would be nice if your script used "cp -i" to warn of any files that it might overwrite. But anyway, thanks again - you saved me a lot of time!

  4. Hi Tom, thanks for your reply, along with another PAYG form I was prompted to investigate again. I can confirm it is working fine again now!

    I have modified my script to be a little more discriminating: originally i just wanted it to work without caring about messing up Java. This time i used "diff" to check what i was overwriting.

    1) JAVA_HOME is already set at the top of the script - it is not needed by the browser plugin.
    2) I ran diff on lib/security/ The Ubuntu version is pretty much the same, without the line. I'm only taking cacerts and localsecurity.jar from AUSkey now.
    3) the script now purges and deletes any existing Sun Java lib folders first: if you don't want this to happen, you may want to edit the script before running it.
    4) the cp commands now skip overwriting existing files in lib/ext and save a backup of the two files in lib/security.

    Cheers, Rob.

  5. You're right about JAVA_HOME - I missed it when I copied the lines one-by-one.

    I had one more issue on a different machine. The sun-java6-* packages weren't found, so I had to add the "partner" repository first:
    $ sudo add-apt-repository "deb maverick partner"
    $ sudo apt-get update


  6. Rob,

    I've tried the new script under Ubuntu 10.04 64bit (first copying my lib backup to lib). I still had no joy.

    I restarted my firefox 3.6.12. I tried the new 3.6.13 just incase.

    I've remarked out the in my line as suggested. This did help the looping problem, but still no AUSkey.

    I copied the keystore.xml and preferences.xml to ~/AUSkey and still no luck.

    What else should I try?

    Michael (map7)

  7. Hi Michael, have a look in the script, there's some commented lines for purging and reinstalling Java to get a clean start. Run those commented lines and then run the script again and see how it goes.

    The SunMSCAPI line isn't in the default Ubuntu config: if yours was still there then you didn't have a clean Java install.

    What 'java -version' do you get in Lucid/10.04? It could be a different version to Maverick.

    How far does your browser get installing your key? The keystore.xml file is created after you download your first key.

  8. Ignore my last comment. It has started working now. Thank you so much Rob, now I can turn off this old Windows XP box I have laying around for AUSkey.

  9. Great work guys, I am logged in.

  10. AUSkey wasn't working for me tonight - the AUSkey software detection is broken for Linux browsers with the dreaded: "Software download required".

    So I did a bit of debugging and found that the isABRBrowserPluginInstalled() function in ABR_BrowserEnabler.js doesn't actually check for the Java plugin unless running on a Mac!

    As a workaround I simply added "Mac" to the user agent string in Firefox and I'm now able to log in again.

  11. Thanks Tom. For a brief few days in Dec 2010 i noticed the same thing using. And then after the 'official' release, it worked without the useragent mod. Sounds like a regression somewhere. I just tried it on Natty beta, and FF locked up. Something to investigate next BAS ;) cheers.