[Crypto: age] From Password to Ciphertext

age is a program that encrypts files. Encryption converts readable data into data that you cannot read without the correct secret. Decryption converts the encrypted data back into the initial data.

I keep some files that must stay private if I lose this laptop. I use age for these files. A passphrase is the secret that I enter to encrypt or decrypt a file.

This is the first of six posts. The example starts with a small text file. Later posts show the file format, the encryption process, and the time necessary to try passphrases.

Encrypt a small file

These commands use a terminal on macOS. A terminal lets you enter commands as text. The examples use age version 1.3.1.

1. If Homebrew is installed, install age with this command:

   bash

   brew install age
   

2. Show the installed version:

   bash

   age --version
   

   The example version is:

   text

   v1.3.1
   

3. Make a new directory for the examples:

   bash

   mkdir age-demo
   

4. Change to that directory:

   bash

   cd age-demo
   

5. Make the example file:

   bash

   printf '%s\n' 'Meet me at the docks at 9. Bring the second key. Do not write this down.' > secret.txt
   

6. Encrypt the file:

   bash

   age -p -o secret.txt.age secret.txt
   

7. Enter a passphrase at the prompt.

8. Enter the same passphrase at the confirmation prompt.

The -p option selects passphrase encryption. The -o option specifies the output file. The last name, secret.txt, specifies the input file.

The terminal does not show the passphrase as you enter it. age also lets you leave the first prompt empty to generate a random passphrase. Keep that generated passphrase in a password manager if you use this option.

The command makes secret.txt.age. It also leaves secret.txt in the directory. Anyone who can read the initial file can still read its contents. Encryption does not remove the initial file.

The output option can replace an existing file. Use the new example directory to keep these commands separate from your other files. The age manual gives the options and prompts.

What the encrypted file contains

Plaintext is the readable input. Ciphertext is the encrypted content. A byte is a unit of data. Each letter, space, and punctuation mark in this example uses one byte.

The input file has 73 bytes, including the final newline. With age 1.3.1 and the passphrase options above, the encrypted file has 255 bytes.

The additional bytes contain information necessary for decryption. They include a header, a random value for payload encryption, and authentication data. Authentication data lets age detect an incorrect key or a change to encrypted data.

An age file has two primary parts:

The header is readable, but it does not contain the passphrase. It contains an encrypted key, not a key that anyone can use directly. The header post gives the meaning of each field.

Decrypt the file

1. Decrypt the example into a new file:

   bash

   age -d -o out.txt secret.txt.age
   

2. Enter the same passphrase that you used for encryption.

3. Show the result:

   bash

   cat out.txt
   

The -d option selects decryption. The output is:

Meet me at the docks at 9. Bring the second key. Do not write this down.

The file out.txt now contains readable plaintext. Keep it private, as with secret.txt.

What an incorrect passphrase does

To try an incorrect passphrase, run this command:

age -d secret.txt.age

Enter a different passphrase at the prompt. age reports an error that includes:

incorrect passphrase

age first tries to decrypt the encrypted file key. An incorrect passphrase makes an incorrect wrapping key. The authentication check fails, so age stops before it decrypts the payload.

This error differs from a damaged payload. The cipher post shows that later failure with a small example.

The rest of the series

Each post shows one part of the process:

The next post uses the same secret.txt.age file. Keep the example files and the passphrase to continue.