1 files changed, 59 insertions, 1 deletions
diff --git a/apps/files_encryption/appinfo/spec.txt b/apps/files_encryption/appinfo/spec.txt
index 2d22dffe08d..ddd3983a9eb 100644
--- a/apps/files_encryption/appinfo/spec.txt
+++ b/apps/files_encryption/appinfo/spec.txt
@@ -9,6 +9,57 @@ Encrypted files
 
   [encrypted data string][delimiter][IV][padding]
   [anhAAjAmcGXqj1X9g==][00iv00][MSHU5N5gECP7aAg7][xx] (square braces added)
+  
+- Directory structure:
+  - Encrypted user data (catfiles) are stored in the usual /data/user/files dir
+  - Keyfiles are stored in /data/user/files_encryption/keyfiles
+  - Sharekey are stored in /data/user/files_encryption/share-files
+  
+- File extensions:
+  - Catfiles have to keep the file extension of the original file, pre-encryption
+  - Keyfiles use .keyfile
+  - Sharekeys have .shareKey
+  
+Shared files
+------------
+
+Shared files have a centrally stored catfile and keyfile, and one sharekey for 
+each user that shares it.
+
+When sharing is used, a different encryption method is used to encrypt the 
+keyfile (openssl_seal). Although shared files have a keyfile, its contents
+use a different format therefore.
+
+Each time a shared file is edited or deleted, all sharekeys for users sharing
+that file must have their sharekeys changed also. The keyfile and catfile 
+however need only changing in the owners files, as there is only one copy of
+these.
+
+Publicly shared files (public links)
+------------------------------------
+
+Files shared via public links use a separate system user account called 'ownCloud'. All public files are shared to that user's public key, and the private key is used to access the files when the public link is used in browser.
+
+This means that files shared via public links are accessible only to users who know the shared URL, or to admins who know the 'ownCloud' user password.
+
+Lost password recovery
+----------------------
+
+In order to enable users to read their encrypted files in the event of a password loss/reset scenario, administrators can choose to enable a 'recoveryAdmin' account. This is a user that all user files will automatically be shared to of the option is enabled. This allows the recoveryAdmin user to generate new keyfiles for the user. By default the UID of the recoveryAdmin is 'recoveryAdmin'.
+
+OC_FilesystemView
+-----------------
+
+files_encryption deals extensively with paths and the filesystem. In order to minimise bugs, it makes calls to filesystem methods in a consistent way: OC_FilesystemView{} objects always use '/' as their root, and specify paths each time particular methods are called. e.g. do this:
+
+$view->file_exists( 'path/to/file' );
+
+Not:
+
+$view->chroot( 'path/to' );
+$view->file_exists( 'file' );
+
+Using this convention means that $view objects are more predictable and less likely to break. Problems with paths are the #1 cause of bugs in this app, and consistent $view handling is an important way to prevent them.
 
 Notes
 -----
@@ -16,4 +67,11 @@ Notes
 - The user passphrase is required in order to set up or upgrade the app. New 
   keypair generation, and the re-encryption of legacy encrypted files requires
   it. Therefore an appinfo/update.php script cannot be used, and upgrade logic
-  is handled in the login hook listener.
-\ No newline at end of file
+  is handled in the login hook listener. Therefore each time the user logs in 
+  their files are scanned to detect unencrypted and legacy encrypted files, and 
+  they are (re)encrypted as necessary. This may present a performance issue; we
+  need to monitor this.
+- When files are saved to ownCloud via WebDAV, a .part file extension is used so
+  that the file isn't cached before the upload has been completed. .part files 
+  are not compatible with files_encrytion's key management system however, so 
+  we have to always sanitise such paths manually before using them.
+\ No newline at end of file