How To‎ > ‎

CSI under Linux - obsolete

As of March 2014 this document is no longer required. AUSkey now works natively under Linux. While the process described was correct at time of publication, this now contains out of date information retained for historical reference.

About this document

This document describes the process to make it possible to use the ATO Business Portal under Linux which is currently not a supported OS. In my opinion this is not likely to change in the near future, but that should not deter you. If you think that Linux should be supported I suggest that you contact your member of parliament or the ATO directly.

Of course this document is completely written without the official endorsement of the ATO, so don't blame them for anything in here.

$Revision: 1.19 $
$Date: 2007-09-09 05:47:17 $
$Author: onno $

Current version at: http://auskey.itmaze.com.au/auskey/how-to/

Credits

The Linux community does what it does and supports itself. This document is the result of that community. This document is written by Onno Benschop assisted and (in parts copied) from notes written by Bojan Smojver and published by Jim Watson. The Australian Taxation Office also assisted with able representation from Ty and Dean. Of course the countless members from the Perth Linux User Group pointed out my errors along the way and kept me busy with hints and assistance.

The aim of this exercise is to:

  1. Install Java
  2. Install CSI
  3. Import a certificate
  4. Login to the ATO Business Portal

Introduction

This whole thing started because I needed to lodge my Business Activity Statement and because I'm an Internet child, I refuse to do it on paper. The ATO supplied ECI software was written under Microsoft's idea of what Java is, so after spending some effort trying to make that work, I gave up. While the ATO initially announced a Linux client, I believe that this project was scuttled. The Macintosh OS X version gave me hope, but not enough to get excited.

One day the ATO announced that it was migrating to Sun Java and that started the process all over again. I called the ATO and found there was a Business Portal that used a web browser. I tried it and it didn't work, then spent countless months tracking people down and finally found a guy in a room who understood what I was talking about and while not in any official capacity, could assist and he allocated some resources. We spent some hours playing when he reported success. Apparently all he'd done is installed RedHat and it just worked after installing the CSI. Not that I could reproduce it in any way, but then that is what this document is all about.

Also note that I'm using Debian, so if you find any Debian specific things in here (in the non-Debian comments), let me know and I'll attempt to make it more generic. As a Debian user you should also know that using alien to make a .deb from the Sun supplied .rpm doesn't work, so unless you're the alien developer, don't bother :-)

Update: As of 2007, I am using Ubuntu. It came installed with gij, which I was unable to make work. The biggest issue was that I could not actually locate any documentation that told me where to install the csi.jar files. After several hours I gave up, found that sun-java was already installed and that the jre/lib/ directory was slightly different to Debian. This document has been updated to reflect that knowlege.

Finally, if you know of a way to make this work without Sun Java, please let me know and I'll include your notes as well. I've not yet worked out how to keep the CSI application separate from this install, to allow it to just continue to work even if you upgrade Java. (It does appear that Feisty has a ~/.java/deployment/ext/ directory, but I do not yet understood how it is supposed to work. For now, the Feisty install detailed here will be put in the shared jre/lib/ directory.)

The ATO now has a FAQ item about unsupported operating systems and unsupported browsers and you should read that before you continue here.

Requirements

To make this work you need a web-browser capable of running Java and you need a copy of Java. The current version of Java is 1.5.0_07 (as at Jun 12, 2006).

The minimum machine specifications are anything that Sun says will run Java.

It is assumed that you know how to get to a Linux command line and that you know how to become root on the machine where you want to install the software. If this is not the case, either contact the system administrator for your machine, or contact a local Linux User Group, I'd recommend my friends at the Perth Linux User Group. Having said that, this is not hard and if you know how to type you should not be able to get into too much trouble while installing this.

The ATO maintains an FAQ and Known Issues for the CSI which now has information that assists you in the installation and/or running of the CSI software.

Installing Sun Java

Today we're installing Sun j2re v1.5.0_07, if you're installing a different version, the names below will likely change. Sun updates its Java version regularly, so to stay sane, I suggest that if you're not using Debian that you create a directory called /usr/local/java.sun/, in that you store the versions of Java that are installed, and sym-link to the current one, so the plug-ins keep working and everything stays happy. Debian users will find their current version in /usr/lib/.

The process is to download the Sun Java installer, put it in the appropriate location, activate the plug-in, test the software.

For non-Debian users:
  1. Goto http://java.com/en/download/manual.jsp
  2. Download the Linux (self-extracting file)
  3. As root, type: sh ./j2re-1_5_0_07-linux-i586.bin
  4. Read the license to acknowledge that you've read it and agree and at the end type: yes
  5. The installer will now run and create a directory named j2re1.5.0_07
  6. As root, type: mv j2re1.5.0_07 /usr/local/java.sun/
  7. As root, type: cd /usr/local/java.sun/
  8. As root, type: ln -s j2re1.5.0_07 java.current
  9. If all is well, you should now be able to type ./java.current/bin/java -version and see: java version "1.5.0_07"
  10. To activate the plug-in, as root type: ln -s /usr/local/java.sun/java.current/plugin/i386/ns610-gcc32/libjavaplugin_oji.so /usr/lib/mozilla/plugins/
  11. Visit http://www.java.com/en/download/help/testvm.jsp and you should see that your Java plug-in works.
For Debian users:
  1. To get started you'll need to install the java package builder. This will create a Java package that you can install. Type: sudo apt-get install java-package build-essential
  2. Goto http://java.com/en/download/manual.jsp
  3. Download the Linux (self-extracting file)
  4. In the directory where you downloaded the file, type: fakeroot make-jpkg j2re-1_5_0_07-linux-i586.bin
  5. This will create a .dpkg file which you can install with: sudo dpkg -i sun-j2re1.5_1.5.0+update07_i386.deb
  6. Visit http://www.java.com/en/download/help/testvm.jsp and you should see that your Java plug-in works.
For Ubuntu Feisty users:
  1. Unlike Debian, you can just install Sun Java like this: sudo aptitude install sun-java5-bin
  2. To see if you actually have the Sun Java package active, type: java -version
  3. If all works as expected, the output should look like this:
    java version "1.5.0_11"
    Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_11-b03)
    Java HotSpot(TM) Client VM (build 1.5.0_11-b03, mixed mode, sharing)
  4. If you see any output that looks like this:
    java version "1.4.2"
    gij (GNU libgcj) version 4.1.2 (Ubuntu 4.1.2-0ubuntu5)
    Copyright (C) 2006 Free Software Foundation, Inc.
    This is free software; see the source for copying conditions. There is NO
    warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
    You will need to make the Sun version active like this: sudo update-java-alternatives --set java-1.5.0-sun

At this point you should have Java running and the Java plug-in running on your browser. If you cannot see the plug-in work, there is no point in continuing until you do, because the CSI will need to be accessed using the plug-in via your web-browser.

Updating Java should become as simple as downloading the new version, running the installer, moving the new version directory to /usr/local/java.sun/ and updating the java.current sym-link. (Debian users can just download the new Sun package, run the make-jpkg command and re-install with dpkg.)

Installing CSI

Now we install the CSI software which allows us to authenticate to the ATO server. We can use the CsiInstallForLinux.tar.gz archive as supplied by the ATO. It contains documentation, an icon file, a license and associated files..

The process is to download the file, extract it and then copy the three required files and run the CSI manager.

  1. You can make yourself a directory to store all this: mkdir ~/CSI ; cd ~/CSI ; wget http://csi.business.gov.au/CSI/CsiInstallForLinux.tar.gz
  2. If you cannot download http://www.csi.business.gov.au/CSI/CsiInstallForLinux.tar.gz (I'll attempt to keep this link current, but you can visit csi.business.gov.au and follow the links to the FAQ. Look for "unsupported" and click the link. I've been told that the ATO and CSI web-sites change without notice - you've been warned.)
  3. To access the files, type: cd ~/CSI ; tar -zxf CsiInstallForLinux.tar.gz
  4. Goto the current java version by typing: cd /usr/local/java.sun/java.current/lib/ext (for Debian users: cd /usr/lib/j2re1.5-sun/lib/ext) (for Feisty users: cd /usr/lib/jvm/java-1.5.0-sun/jre/lib/ext)
  5. Copy the CSI application, as root type: cp ~/CSI/CSILinux/csi.jar .
  6. Copy the local policy file, as root type: cp ~/CSI/CSILinux/local_policy.jar .
  7. Copy the export policy file, as root type: cp ~/CSI/CSILinux/US_export_policy.jar .

At this point you should have the CSI software installed and ready to go. To actually make it work, you'll need to install some certificates.

Notice: If you install a new version of Java, your current CSI install will break and you'll need to copy the csi.jar, local_policy.jar and US_export_policy.jar files back into your current installation.

Importing Certificates

Disclaimer: This section is likely incomplete. The ATO will need to supply you with a certificate if you don't already have one. You can use the certificate that came with the ECI software to make this work and that is where I got my certificate from. You can register for an ATO digital certificate on-line at: http://www.ato.gov.au/onlineservices/

Additional instructions can also be found in the README.txt file that comes with the ATO supplied Linux files, which if you've followed these instructions will be at ~/CSI/CSILinux/README.txt

To make this work, you need the file that ends in the extension .p12, in my case it's called after my name and came from the ECI folder on my Windows install of the ECI software.

As regular user (the one you use for your day-to-day work):

  1. Type: /usr/local/java.sun/java.current/bin/java au.gov.bafcsi.clapi.crypto.CsiManager (Debian and Feisty: java au.gov.bafcsi.clapi.crypto.CsiManager)
  2. Click OK to the hint.
  3. Go to "CSI Store" tab. Click on "Add" button.
  4. Pick the ECI certificate file.
  5. Enter the password, then when asked to set the new password, enter whichever one you want to set up as new, twice. This will be the password for this set of certificates from now on. The program will show two imported certificates. (For me the password didn't actually work as expected for my existing ECI certificate, instead it stayed the same as the original password.)
  6. Go to "Default Certificates" tab. Pick "Default Certificate" radio button.
  7. Click "Change" button on both the authentication and non-repudiation certificates.
  8. Pick the certificates, click "Select". Then click "Apply" and "Exit".

CSI stores all configuration as well as certificate store in ~/.csi directory. You can find logs - helpful for debugging - in the logs subdirectory of this directory as well.

NOTICE: Before your certificates expire, you can update your certificates using Linux, but the software may throw an error about backing up the old store. The work-around appears to be to restart the process. Note that for me when it failed, it actually did work, so I ended up with two sets of certificates. One needed to be deleted to make it work.

NOTICE: As of September 2007, the renewal process will warn you that you are using an unsupported browser, but for me it just worked without any issues. The address for renewal is: http://pki.ato.gov.au/atocertificate/Welcome.htm.

NOTICE: You need two certificates, one for "Authentication Signing" and "Non-Repudiation Signing" and another for "Encryption".

Login to Business Portal

Start you browser as the same user (i.e. the one used to import the certs).

  1. Go to http://bp.ato.gov.au/.
  2. Click "Continue". This will open a new window.
  3. Click "Login" in that new window.
  4. A Java window will pop up with the title "Signing terms and conditions".
  5. Click "Sign" button.
  6. Enter your certificate password in the box provided.

You should now be connected to and authenticated with the Business Portal. Remember to click "Logout" when you leave.

Comments