document the encryption cipher

1 files changed, 10 insertions, 2 deletions

diff --git a/doc/internals.mdwn b/doc/internals.mdwn
index 3136993f0..8ca035510 100644
--- a/doc/internals.mdwn
+++ b/doc/internals.mdwn
@@ -51,15 +51,23 @@ space and then the description, followed by a timestamp. Example:
 If there are multiple lines for the same uuid, the one with the most recent
 timestamp wins. git-annex union merges this and other files.
 
-## `remotes.log`
+## `remote.log`
 
 Holds persistent configuration settings for [[special_remotes]] such as
 Amazon S3.
 
 The file format is one line per remote, starting with the uuid of the
-remote, followed by a space, and then a series of key=value pairs,
+remote, followed by a space, and then a series of var=value pairs,
 each separated by whitespace, and finally a timestamp.
 
+Encrypted special remotes store their encryption key here,
+in the "cipher" value. It is base64 encoded, and unless shared [[encryption]]
+is used, is encrypted to one or more gpg keys. The first 256 bytes of
+the cipher is used as the HMAC SHA1 encryption key, to encrypt filenames
+stored on the special remote. The remainder of the cipher is used as a gpg
+symmetric encryption key, to encrypt the content of files stored on the special
+remote.
+
 ## `trust.log`
 
 Records the [[trust]] information for repositories. Does not exist unless