crypt: update docs

Mostly tense, clarity and point of view proposed changes.

There is still some duplication and benefits that would accrue from further examples.

docs/content/crypt.md

@@ -6,23 +6,26 @@ description: "Encryption overlay remote"
 {{< icon "fa fa-lock" >}}Crypt
 ----------------------------------------
 
-The `crypt` remote encrypts and decrypts another remote.
+Rclone `crypt` remotes encrypt and decrypt other remotes.
 
-To use it first set up the underlying remote following the config
+To use `crypt`, first set up the underlying remote. Follow the `rclone
-instructions for that remote.  You can also use a local pathname
+config` instructions for that remote.
-instead of a remote which will encrypt and decrypt from that directory
-which might be useful for encrypting onto a USB stick for example.
 
-First check your chosen remote is working - we'll call it
+`crypt` applied to a local pathname instead of a remote will
-`remote:path` in these docs.  Note that anything inside `remote:path`
+encrypt and decrypt that directory, and can be used to encrypt USB
-will be encrypted and anything outside won't.  This means that if you
+removable drives.
-are using a bucket based remote (eg S3, B2, swift) then you should
-probably put the bucket in the remote `s3:bucket`. If you just use
-`s3:` then rclone will make encrypted bucket names too (if using file
-name encryption) which may or may not be what you want.
 
-Now configure `crypt` using `rclone config`. We will call this one
+Before configuring the crypt remote, check the underlying remote is
-`secret` to differentiate it from the `remote`.
+working. In this example the underlying remote is called `remote:path`.
+Anything inside `remote:path` will be encrypted and anything outside
+will not. In the case of an S3 based underlying remote (eg Amazon S3,
+B2, Swift) it is generally advisable to define a crypt remote in the
+underlying remote `s3:bucket`. If `s3:` alone is specified alongside
+file name encryption, rclone will encrypt the bucket name.
+
+Configure `crypt` using `rclone config`. In this example the `crypt`
+remote is called `secret`, to differentiate it from the underlying
+`remote`.
 
 ```
 No remotes found - make a new one
@@ -96,49 +99,42 @@ d) Delete this remote
 y/e/d> y
 ```
 
-**Important** The password is stored in the config file is lightly
+**Important** The crypt password stored in `rclone.conf` is lightly
-obscured so it isn't immediately obvious what it is.  It is in no way
+obscured. That only protects it from cursory inspection. It is not
-secure unless you use config file encryption.
+secure unless encryption of `rclone.conf` is specified.
 
-A long passphrase is recommended, or you can use a random one.
+A long passphrase is recommended, or `rclone config` can generate a
+random one.
 
-The obscured password is created by using AES-CTR with a static key, with
+The obscured password is created using AES-CTR with a static key. The
-the salt stored verbatim at the beginning of the obscured password. This
+salt is stored verbatim at the beginning of the obscured password. This
-static key is shared by between all versions of rclone.
+static key is shared between all versions of rclone.
 
 If you reconfigure rclone with the same passwords/passphrases
 elsewhere it will be compatible, but the obscured version will be different
 due to the different salt.
 
-Note that rclone does not encrypt
+Rclone does not encrypt
 
   * file length - this can be calculated within 16 bytes
   * modification time - used for syncing
 
 ## Specifying the remote ##
 
-In normal use, make sure the remote has a `:` in. If you specify the
+In normal use, ensure the remote has a `:` in. If specified without,
-remote without a `:` then rclone will use a local directory of that
+rclone uses a local directory of that name.  For example if a remote
-name.  So if you use a remote of `/path/to/secret/files` then rclone
+`/path/to/secret/files` is specified, rclone encrypts content to that
-will encrypt stuff to that directory.  If you use a remote of `name`
+directory.  If a remote `name` is specified, rclone targets a directory
-then rclone will put files in a directory called `name` in the current
+`name` in the current directory.
-directory.
 
-If you specify the remote as `remote:path/to/dir` then rclone will
+If remote `remote:path/to/dir` is specified, rclone stores encrypted
-store encrypted files in `path/to/dir` on the remote. If you are using
+files in `path/to/dir` on the remote. With file name encryption, files
-file name encryption, then when you save files to
+saved to `secret:subdir/subfile` are stored in the unencrypted path
-`secret:subdir/subfile` this will store them in the unencrypted path
+`path/to/dir` but the `subdir/subpath` element is encrypted.
-`path/to/dir` but the `subdir/subpath` bit will be encrypted.
-
-Note that unless you want encrypted bucket names (which are difficult
-to manage because you won't know what directory they represent in web
-interfaces etc), you should probably specify a bucket, eg
-`remote:secretbucket` when using bucket based remotes such as S3,
-Swift, Hubic, B2, GCS.
 
 ## Example ##
 
-To test I made a little directory of files using "standard" file name
+Create the following file structure using "standard" file name
 encryption.
 
 ```
@@ -152,7 +148,7 @@ plaintext/
         └── file4.txt
 ```
 
-Copy these to the remote and list them back
+Copy these to the remote, and list them
 
 ```
 $ rclone -q copy plaintext secret:
@@ -164,7 +160,7 @@ $ rclone -q ls secret:
         9 subdir/file3.txt
 ```
 
-Now see what that looked like when encrypted
+The crypt remote looks like
 
 ```
 $ rclone -q ls remote:path
@@ -175,7 +171,7 @@ $ rclone -q ls remote:path
        56 86vhrsv86mpbtd3a0akjuqslj8/8njh1sk437gttmep3p70g81aps
 ```
 
-Note that this retains the directory structure which means you can do this
+The directory structure is preserved
 
 ```
 $ rclone -q ls secret:subdir
@@ -184,9 +180,9 @@ $ rclone -q ls secret:subdir
        10 subsubdir/file4.txt
 ```
 
-If don't use file name encryption then the remote will look like this
+Without file name encryption `.bin` extensions are added to underlying
-- note the `.bin` extensions added to prevent the cloud provider
+names. This prevents the cloud provider attempting to interpret file
-attempting to interpret the data.
+content.
 
 ```
 $ rclone -q ls remote:path
@@ -199,8 +195,6 @@ $ rclone -q ls remote:path
 
 ### File name encryption modes ###
 
-Here are some of the features of the file name encryption modes
-
 Off
 
   * doesn't hide file names or directory structure
@@ -219,17 +213,19 @@ Standard
 Obfuscation
 
 This is a simple "rotate" of the filename, with each file having a rot
-distance based on the filename. We store the distance at the beginning
+distance based on the filename. Rclone stores the distance at the
-of the filename. So a file called "hello" may become "53.jgnnq".
+beginning of the filename. A file called "hello" may become "53.jgnnq".
 
-This is not a strong encryption of filenames, but it may stop automated
+Obfuscation is not a strong encryption of filenames, but hinders
-scanning tools from picking up on filename patterns. As such it's an
+automated scanning tools picking up on filename patterns. It is an
-intermediate between "off" and "standard". The advantage is that it
+intermediate between "off" and "standard" which allows for longer path
-allows for longer path segment names.
+segment names.
 
 There is a possibility with some unicode based filenames that the
 obfuscation is weak and may map lower case characters to upper case
-equivalents.  You can not rely on this for strong protection.
+equivalents. 
+
+Obfuscation cannot be relied upon for strong protection.
 
   * file names very lightly obfuscated
   * file names can be longer than standard encryption
@@ -237,13 +233,14 @@ equivalents.  You can not rely on this for strong protection.
   * directory structure visible
   * identical files names will have identical uploaded names
 
-Cloud storage systems have various limits on file name length and
+Cloud storage systems have limits on file name length and
-total path length which you are more likely to hit using "Standard"
+total path length which rclone is more likely to breach using
-file name encryption.  If you keep your file names to below 156
+"Standard" file name encryption.  Where file names are less thn 156
-characters in length then you should be OK on all providers.
+characters in length issues should not be encountered, irrespective of
+cloud storage provider.
 
-There may be an even more secure file name encryption mode in the
+An alternative, future rclone file name encryption mode may tolerate
-future which will address the long file name problem.
+backend provider path length limits.
 
 ### Directory name encryption ###
 Crypt offers the option of encrypting dir names or leaving them intact.
@@ -269,10 +266,10 @@ Example:
 Crypt stores modification times using the underlying remote so support
 depends on that.
 
-Hashes are not stored for crypt.  However the data integrity is
+Hashes are not stored for crypt. However the data integrity is
 protected by an extremely strong crypto authenticator.
 
-Note that you should use the `rclone cryptcheck` command to check the
+Use the `rclone cryptcheck` command to check the
 integrity of a crypted remote instead of `rclone check` which can't
 check the checksums properly.