# Quick-start guide to programming with Cryptix 3.0

Cryptix contains several classes which allow you to protect your application's data without needing to understand cryptography in depth. The class interfaces are easy to use, but the crypto code behind them is based on extensively reviewed algorithms and is itself well-tested. If you use Cryptix properly, your data will be very difficult to break - even by organisations with enormous resources and great determination to throw at the problem.

Just make sure you follow any points which are labelled as Security Essential.

### Securing your data

Storing data securely in a file is as easy as writing the data. Create an instance of `java.security.CipherOutputStream`, as follows:

>     import java.io.*;
>     import java.security.*;
>     import cryptix.provider.key.RawSecretKey;

>     ...

>     String yourfilename = "test.idea";
>     String passphrase = "Test passphrase";

>     // First, create a FileOutputStream to the file you want to write to
>     FileOutputStream outputStream = new FileOutputStream(yourfilename);

>     // Now, initialise a cipher which will do the actual encryption
>     // In this example we will use IDEA, the cipher used by PGP 2.x
>     Cipher cipher = Cipher.getInstance("IDEA/CBC/PKCS#5", "Cryptix");
>     // (is getBytes() right? Is it portable? --IB)
>     RawSecretKey aKey = new RawSecretKey("IDEA", passphrase.getBytes());
>     cipher.initEncrypt(aKey);

>     // Finally, create a secure output stream with these two parameters
>     CipherOutputStream out = new CipherOutputStream(outputStream, cipher)

You can now simply call `out.write(byte[])` with your data, which will be encrypted and written to the file opened in `outputStream`.

Initialising the cipher is the critical line in the above code sample. `IDEA` is a cipher object which implements the International Data Encryption Algorithm designed by Ascom-Tech. You can, however, use any class which extends `java.security.cipher`. Cryptix provides several such ciphers, including `SPEED` and `DES`.

Security Essential See the Cryptix FAQ for information on these different ciphers and their relative strengths.

Cipher objects need to be initialised with a piece of secret information (a key). Only someone who knows this information will be able to decrypt the data. The key needed depends on the cipher you use. IDEA requires a 16-byte array. See the documentation of the other ciphers for their requirements.

Security Essential Remember to advise your application's users that passphrases must be reasonably complex to provide proper protection. Single words, names of themselves or friends/relatives, or well-known phrases from songs, poems, etc. can be easily guessed by automatic passphrase-guessing programs (many of which exist!). Refer them to http://skuz.wanweb.net/passfaq.html for more advice.

To read the secured data back in, you need an inputstream connected to the file it is stored in, and a Cipher object as above.

>     FileInputStream inputStream = new FileInputStream(encryptedfile);

>     // Initialise a cipher to do the decryption
>     Cipher cipher = Cipher.getInstance("IDEA/CBC/PKCS#5", "Cryptix");
>     RawSecretKey aKey = new RawSecretKey("IDEA", passphrase.getBytes());
>     cipher.initDecrypt(aKey);

>     CipherInputStream in = new CipherInputStream(inputStream, cipher)

### Securing communications

You can secure a communications channel in exactly the same way you secure a file output stream above. Once you have connected a stream, pass it to a new `CipherOutputStream` as you did before. The user at the other end does the same with a `CipherInputStream`.

>     Socket serverSocket = new Socket(serverName, serverPort);
>     DataOutStream outputStream = serverSocket.getOutputStream();
>     CipherOutputStream secureOut = new CipherOutputStream(outputStream, cipher);

Obviously, the user you are communicating with needs to know the passphrase as well. This is OK if the two communicating parties can swap this passphrase by other means - such as a personal meeting - but if they cannot you need to use public-key cryptography, which is more difficult. When you're ready to progress to that, good luck!

A book that everyone interested in security should read is Bruce Schneier, Applied Cryptography 2nd Ed, 1996, John Wiley & Sons. If you have any crypto questions, this is where you should look first. Available on-line is the excellent afterword by Matt Blaze which demonstrates that secure systems require far more than just crypto. Remember that Cryptix is not a panacea!