What do I need to know in order to encrypt elsewhere for Conceal to decrypt?

[huttarl]

This is somewhat related to issue #49.
I realize it's not the use case for which Conceal was intended. But it is a useful one.

Suppose I want to store a bunch of encrypted files on SD cards, distribute those SD cards, and have an app that can decrypt the data later. I can't use Conceal to encrypt the files because it's written for Android, but the task of encrypting all those files would be too slow to do on Android.

What does my encryption process need to know in order to encrypt files on a server in a way that Conceal could later decrypt? (I'm planning to implement a custom keychain to return the right key in my Android app.) I know the encryption process should use AES-GCM and the same key as my custom keychain returns. Is that enough to ensure that the encrypted files will be decryptable by Conceal?

[huttarl]

I think maybe I found the answer at #95, where the reverse process is asked about: Encrypting with Conceal and decrypting with another tool.

I understand that the IV is a random, non-secret value, that gets included in the encrypted file; and the Entity is also a known value (perhaps based on the filename). However I'm not real clear on how to determine the value of the Entity, or how to use it in creating the integrity check TAG. I guess I can read the source code for that, though it would be nice to have a documented API we can rely on to not change in the future.

[mandrachek]

The first byte is the format.
The second bit is the cipher id, which tells you if you have a 128bit (1) or 256bit (2) key.
The next 12 bytes is the IV (same for both 128 and 256bit, but could change with future versions).
Then the encrypted content.
Then a 16 byte authentication tag.

This authentication tag is basically there to make sure the data in the file hasn't been tampered with. You may have seen this referred to as a MAC, or HMAC, a message authentication code.

I believe the pure java code for decrypting this would look something like this:

function decrypt(SecretKey key, File file, OutputStream outputStream) throws Exception {
   BufferedInputStream bis = new BufferedInputStream(new FileInputStream(file));

   // read the format
   byte[] format = new byte[1];
   bis.read(format);

   // read the cipher
   byte[] cipherId = new byte[1];
   bis.read(cipherId);

   // read the IV
   byte[] iv = new byte[12];
   bis.read(iv); // reads the iv
   int tagLength = 16;

   // initialize the cipher for decryption, using the iv and tagLength
   Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding")
   // the GCMParamterSpec wants a tagLength as one of it's parameters, but as bits, not bytes
   cipher.initialize(Cipher.DECRYPT_MODE, key, new GCMParamterSpec(tagLength*8, iv);

   // decrypt picking up right after the IV. Don't worry about the tag, that should be handled
   // by GCM natively ... I think... as long as conceal didn't role their own.
   CipherInputStream cis = new CipherInputStream(bis,cipher);

   // read in encrypted content, write out decrypted content
   byte[] buffer = new byte[128];
   int readBytes;
   while ((readBytes = cis.read(buffer)) != 0) {
      outputStream.write(buffer,0,readBytes);
   }
   outputStream.flush();
   outputStream.close();
   cis.close();

}

[strat1892]

Be sure to update the additional authentication data prior to encryption/decryption.
cipher.updateAAD(format);
cipher.updateAAD(cipherId);
cipher.updateAAD(entity);

Also, if dealing with the deprecated 128bit, use the old UTF-16 encoding for the entity.