docs/src/encryption.md

Sun, 01 Apr 2018 12:40:48 +0200

author
Olaf Wintermann <olaf.wintermann@gmail.com>
date
Sun, 01 Apr 2018 12:40:48 +0200
changeset 372
2e15ff88a0ab
parent 283
0e36bb75a732
permissions
-rw-r--r--

adds tag management commands to dav-sync

283
0e36bb75a732 adds dav-sync introduction and sync.xml documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 281
diff changeset
1 ---
0e36bb75a732 adds dav-sync introduction and sync.xml documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 281
diff changeset
2 title: 'Encryption'
0e36bb75a732 adds dav-sync introduction and sync.xml documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 281
diff changeset
3 ---
273
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
4
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
5 The davutils programs have an integrated client-side encryption feature, that allows you to encrypt and decrypt on the fly with AES256 or AES128. To use this feature, the server **must** support WebDAV dead properties.
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
6
281
ddb5e8f2a43d some more minor doc improvements
Mike Becker <universe@uap-core.de>
parents: 274
diff changeset
7 The tools support both, encryption of the resource content and encryption of the resource name. Each resource is encrypted separately. With activated name encryption, the actual resource name is disguised by a random name but the name used by the client is stored encrypted as a WebDAV property. This means, an attacker can see the directory structure and the file length, but can't guess the file names and in particular which files have the same name.
273
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
8
274
5577d3eae04c dav-sync command documentation complete
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 273
diff changeset
9 To enable encryption a key must be configured in `$HOME/.dav/config.xml`. A key must have a unique name. To access encrypted resources, all clients must configure the same key with the same name. Currently a key can only be loaded from a file and not generated from a password.
273
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
10
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
11 A configuration for a key looks like:
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
12
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
13 <key>
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
14 <name>mykey1</name>
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
15 <file>keys/mykey1</file>
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
16 </key>
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
17
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
18 The file path must be relative to `$HOME/.dav/`. In this example the file `$HOME/.dav/keys/mykey1` is loaded.
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
19
281
ddb5e8f2a43d some more minor doc improvements
Mike Becker <universe@uap-core.de>
parents: 274
diff changeset
20 To generate a key use **`dd`** on unix like systems. The following command generates a 256 bit (32 bytes) key for AES256 encryption.
273
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
21
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
22 dd if=/dev/random of=mykey1 bs=32 count=1
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
23
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
24 After a key is configured, you can enable encryption/decryption in two ways. You can use the dav option **`-c`** to enable encryption and specify your key with the **`-k`** option. The alternative is to enable encryption by default for a repository in the config.xml file.
281
ddb5e8f2a43d some more minor doc improvements
Mike Becker <universe@uap-core.de>
parents: 274
diff changeset
25 You may also choose to specify the default key only and use **`-c`** where you like to use encryption.
273
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
26
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
27 <repository>
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
28 <name>myrepo</name>
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
29 <url>http://example.com/webdav/</url>
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
30
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
31 <default-key>mykey1</default-key>
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
32 <full-encryption>true</full-encryption>
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
33 </repository>
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
34
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
35 See [Configuration][1] for details.
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
36
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
37 [1]: ./configuration.html
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
38
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
39 Internals
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
40 ---------
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
41
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
42 When a resource is encrypted, some crypto properties (namespace: http://davutils.org/) are set for the resource.
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
43
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
44 - crypto-key: Contains the name of the key used for encryption. The presence of this property indicates that the resource is encrypted
281
ddb5e8f2a43d some more minor doc improvements
Mike Becker <universe@uap-core.de>
parents: 274
diff changeset
45 - crypto-hash: A hash of the cleartext, encrypted and base64 encoded
273
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
46 - crypto-name: The name of the resource, encrypted and base64 encoded. This property is not used if name encryption is disabled.
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
47
c743721d566f more documentation
Olaf Wintermann <olaf.wintermann@gmail.com>
parents: 265
diff changeset
48

mercurial