Document the checksums addition in 10.0

This commit documents the new checksums addition in 10.0, specifically
in the desktop client. This fixes owncloud/documentation/issues/2964.

3 files changed, 133 insertions, 13 deletions

diff --git a/doc/architecture.rst b/doc/architecture.rst
index d8e6319af..58ff1d17d 100644
--- a/doc/architecture.rst
+++ b/doc/architecture.rst
@@ -143,16 +143,135 @@ the remote file will be downloaded and saved as message.txt.
 
 Conflict files are always created on the client and never on the server.
 
+Checksum Algorithm Negotiation
+------------------------------
+
+In ownCloud 10.0 we implemented a checksum feature which checks the file integrity on upload and download by computing a checksum after the file transfer finishes.
+The client queries the server capabilities after login to decide which checksum algorithm to use.
+Currently, SHA1 is hard-coded in the official server release and can't be changed by the end-user. 
+Note that the server additionally also supports MD5 and Adler-32, but the desktop client will always use the checksum algorithm announced in the capabilities:
+
+::
+
+  GET http://localhost:8000/ocs/v1.php/cloud/capabilities?format=json
+
+::
+
+  json
+  {
+     "ocs":{
+        "meta":{
+           "status":"ok",
+           "statuscode":100,
+           "message":"OK",
+           "totalitems":"",
+           "itemsperpage":""
+        },
+        "data":{
+           "version":{
+              "major":10,
+              "minor":0,
+              "micro":0,
+              "string":"10.0.0 beta",
+              "edition":"Community"
+           },
+           "capabilities":{
+              "core":{
+                 "pollinterval":60,
+                 "webdav-root":"remote.php/webdav"
+              },
+              "dav":{
+                 "chunking":"1.0"
+              },
+              "files_sharing":{
+                 "api_enabled":true,
+                 "public":{
+                    "enabled":true,
+                    "password":{
+                       "enforced":false
+                    },
+                    "expire_date":{
+                       "enabled":false
+                    },
+                    "send_mail":false,
+                    "upload":true
+                 },
+                 "user":{
+                    "send_mail":false
+                 },
+                 "resharing":true,
+                 "group_sharing":true,
+                 "federation":{
+                    "outgoing":true,
+                    "incoming":true
+                 }
+              },
+              "checksums":{
+                 "supportedTypes":[
+                    "SHA1"
+                 ],
+                 "preferredUploadType":"SHA1"
+              },
+              "files":{
+                 "bigfilechunking":true,
+                 "blacklisted_files":[
+                    ".htaccess"
+                 ],
+                 "undelete":true,
+                 "versioning":true
+              }
+           }
+        }
+     }
+  }
+
+Upload
+~~~~~~
+
+A checksum is calculated with the previously negotiated algorithm by the client and sent along with the file in an HTTP Header. 
+```OC-Checksum: [algorithm]:[checksum]```
+
+.. image:: ./images/checksums/client-activity.png
+
+During file upload, the server computes SHA1, MD5, and Adler-32 checksums and compares one of them to the checksum supplied by the client. 
+
+On mismatch, the server returns HTTP Status code 400 (Bad Request) thus signaling the client that the upload failed. 
+The server then discards the upload, and the client blacklists the file:
+
+.. image:: ./images/checksums/testing-checksums.png
+
+::
+
+  <?xml version='1.0' encoding='utf-8'?>
+  <d:error xmlns:d="DAV:" xmlns:s="http://sabredav.org/ns">
+    <s:exception>Sabre\DAV\Exception\BadRequest</s:exception>
+    <s:message>The computed checksum does not match the one received from the
+  client.</s:message>
+  </d:error>
+
+The client retries the upload using exponential back-off. 
+On success (matching checksum) the computed checksums are stored by the server in ``oc_filecache`` alongside the file.
+
+Chunked Upload
+~~~~~~~~~~~~~~
+
+Mostly same as above. 
+The checksum of the full file is sent with every chunk, but the server compares the checksum of the last chunk.
+
+Download
+~~~~~~~~
+
+The server sends the checksum in an HTTP header with the file. (same format as above).
+If no checksum is found in ``oc_filecache`` (freshly mounted external storage) it is computed and stored in ``oc_filecache`` on the first download. 
+The checksum is then provided on all subsequent downloads but not on the first. 
 
 .. _ignored-files-label:
 
 Ignored Files
 -------------
 
-The ownCloud Client supports the ability to exclude or ignore certain files
-from the synchronization process. Some system wide file patterns that are used
-to exclude or ignore files are included with the client by default and the
-ownCloud Client provides the ability to add custom patterns.
+The ownCloud Client supports the ability to exclude or ignore certain files from the synchronization process. 
+Some system wide file patterns that are used to exclude or ignore files are included with the client by default and the ownCloud Client provides the ability to add custom patterns.
 
 By default, the ownCloud Client ignores the following files:
 
@@ -163,18 +282,19 @@ By default, the ownCloud Client ignores the following files:
 If a pattern selected using a checkbox in the `ignoredFilesEditor-label` (or if
 a line in the exclude file starts with the character ``]`` directly followed by
 the file pattern), files matching the pattern are considered *fleeting meta
-data*. These files are ignored and *removed* by the client if found in the
-synchronized folder. This is suitable for meta files created by some
-applications that have no sustainable meaning.
+data*. 
 
-If a pattern ends with the forward slash (``/``) character, only directories are
-matched. The pattern is only applied for directory components of filenames
-selected using the checkbox.
+These files are ignored and *removed* by the client if found in the
+synchronized folder. 
+This is suitable for meta files created by some applications that have no sustainable meaning.
+
+If a pattern ends with the forward slash (``/``) character, only directories are matched. 
+The pattern is only applied for directory components of filenames selected using the checkbox.
 
 To match filenames against the exclude patterns, the UNIX standard C library
-function ``fnmatch`` is used. This process checks the filename against the
-specified pattern using standard shell wildcard pattern matching. For more
-information, please refer to `The opengroup website
+function ``fnmatch`` is used. 
+This process checks the filename against the specified pattern using standard shell wildcard pattern matching. 
+For more information, please refer to `The opengroup website
 <http://pubs.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#tag_02_13_01>`_.
 
 The path that is checked is the relative path under the sync root directory.
diff --git a/doc/images/checksums/client-activity.png b/doc/images/checksums/client-activity.png
new file mode 100644
index 000000000..c82c0634a
--- /dev/null
+++ b/doc/images/checksums/client-activity.png
diff --git a/doc/images/checksums/testing-checksums.png b/doc/images/checksums/testing-checksums.png
new file mode 100644
index 000000000..612a74c6f
--- /dev/null
+++ b/doc/images/checksums/testing-checksums.png