Document age usage.

README.rst

@@ -2,7 +2,7 @@ SOPS: Secrets OPerationS
 ========================
 
 **sops** is an editor of encrypted files that supports YAML, JSON, ENV, INI and BINARY
-formats and encrypts with AWS KMS, GCP KMS, Azure Key Vault and PGP.
+formats and encrypts with AWS KMS, GCP KMS, Azure Key Vault, age, and PGP.
 (`demo <https://www.youtube.com/watch?v=YTEVyLXFiq0>`_)
 
 .. image:: https://i.imgur.com/X0TM5NI.gif
@@ -164,6 +164,32 @@ Given that, the only command a ``sops`` user needs is:
 encrypted if modified, and saved back to its original location. All of these
 steps, apart from the actual editing, are transparent to the user.
 
+Encrypting using age
+~~~~~~~~~~~~~~~~~~~~
+
+`age<https://age-encryption.org/>`_ is a simple, modern, and secure tool for
+encrypting files. It's recommended to use age over PGP, if possible.
+
+You can encrypt a file for one or more age recipients (comma separated) using
+the ``--age`` option or the **SOPS_AGE_RECIPIENTS** environment variable:
+
+.. code:: bash
+
+   $ sops --age age1yt3tfqlfrwdwx0z0ynwplcr6qxcxfaqycuprpmy89nr83ltx74tqdpszlw test.yaml > test.enc.yaml
+
+When decrypting a file with the corresponding identity, sops will look for a
+text file name ``keys.txt`` located in a ``sops`` subdirectory of your user
+configuration directory. On Linux, this would be ``$XDG_CONFIG_HOME/sops/keys.txt``.
+On macOS, this would be ``$HOME/Library/Application Support/sops/keys.txt``. On
+Windows, this would be ``%AppData%\sops\keys.txt``. You can specify the location
+of this file manually by setting the environment variable **SOPS_AGE_KEY_FILE**.
+
+The contents of this key file should be a list of age X25519 identities, one
+per line. Lines beginning with ``#`` are considered comments and ignored. Each
+identity will be tried in sequence until one is able to decrypt the data.
+
+Encrypting with SSH keys via age is not yet supported by sops.
+
 Test with the dev PGP key
 ~~~~~~~~~~~~~~~~~~~~~~~~~