Add docs about requesting vaults / credentials

1 files changed, 157 insertions, 0 deletions

diff --git a/docs/api.md b/docs/api.md
new file mode 100644
index 00000000..4fd9dea0
--- /dev/null
+++ b/docs/api.md
@@ -0,0 +1,157 @@
+Passman offers a api for extensions.
+
+
+##Table of Contents
+- [Authentication](#authentication)
+- [Get vaults](#get-vaults-get)
+- [Get vault](#get-vault-get)
+- [Create new credential](#create-new-credential-post)
+- [Update credential](#update-credential-patch)
+- [Decrypting Credentials / challenge password ](#decrypting-credentials--challenge-password)
+
+##Authentication 
+All apps must authenticate.   
+For example in JS it would be:   
+```
+ var encodedLogin ="MyUsername:MyPassword";
+ var request = new XMLHttpRequest({"mozAnon": true});
+ request.setRequestHeader("Authorization", "Basic " + encodedLogin);
+ request.setRequestHeader("Content-Type", "application/json");
+```
+An other option is logging in via HTTP Basic auth.   
+In this case an example would be:
+`https://MyUsername:Mypassword@nextcloudinstance.com`
+
+Connectivity via http is possible, but you *MUST* warn that their login credentials are send in plaintext.   
+The credentials from passman are still send encrypted if http is used.
+       
+      
+###Get vaults [GET]
+`/apps/passman/api/v2/vaults`   
+This will return a list of vaults.   
+A vault consists of the following properties:
+```
+{  
+   "vault_id":17,
+   "guid":"64DDADA1-54A6-4BE6-AA2F-BCB2EC8E8455",
+   "name":"test",
+   "created":1484175865,
+   "public_sharing_key":"-----BEGIN PUBLIC KEY-----\r\nMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC1h6j+vLcvJDUgOi6VkjzDKTT0\r\nLXluie7+VH2DjnzeXO2QalHI1qAzd\/G51r2NArgwzKMm9g\/kGN1V+mcX3j2WZu\/E\r\n8o5jk83LaSlgcG9GIbOyXUXJlflvctnhPa8Em3GoM\/ZfO2EkkDYANTKvyiyRXroa\r\ny6m2C+aJVzxmhj5tvQIDAQAB\r\n-----END PUBLIC KEY-----\r\n",
+   "last_access":1484216598,
+   "challenge_password":"eyJpdiI6IkFEWExocDFsRWFZSEZhc0cxY2NzUnciLCJ2IjoxLCJpdGVyIjoxMDAwLCJrcyI6MjU2LCJ0cyI6NjQsIm1vZGUiOiJjY20iLCJhZGF0YSI6IiIsImNpcGhlciI6ImFlcyIsInNhbHQiOiJFVmdZLzIxNmI0USIsImN0IjoiU3d5QUkzdVFqenh1cStwaCJ9"
+}
+```
+Short description of the fields:
+- `vault_id` -Id of the vault, only used within queries
+- `vault_guid` - The guid of the vault, use this when making requests
+- `name` - The name of the vault
+- `created` - Timestamp when the vault was created
+- `public_sharing_key` - The public sharing key 
+- `last_access` - Timestamp when the vault was last accessed
+- `challenge_password` - Encrypted challenge password, you can use this to check if the user provided a correct password.
+
+
+###Get vault [GET]
+`/apps/passman/api/v2/vaults/{vault_guid}`   
+To request the credentials.   
+This will return the requested vault and it's credentials
+```$xslt
+created:1484175865
+credentials: [{}, {}, ....]
+guid:"64DDADA1-54A6-4BE6-AA2F-BCB2EC8E8455"
+last_access:1484217620
+name: "test"
+private_sharing_key ''
+public_sharing_key: ''
+sharing_keys_generated:1484175865
+vault_id:17
+vault_settings:null
+```   
+To see how a credential is build up (which fields), see [create new credential](#Create new credential).
+
+###Create new credential [POST]
+`/api/v2/credentials`   
+Fields:
+```$xslt
+var credential = {
+				'vault_id': int,
+				'label': string,
+				'description': string,
+				'created':  null (Will be set server side),
+				'changed': null (Will be set server side),
+				'tags': [{text: string}],
+				'email': string,
+				'username': string,
+				'password': string (encrypted),
+				'url': string (encrypted),
+				'favicon': string,
+				'renew_interval': int,
+				'expire_time': timestamp,
+				'delete_time': timestamp,
+				'files': [
+				{
+                                    filename:  string,
+                                    size: int (size in bytes),
+                                    mimetype: string,
+                                    guid: string (generated server side)
+                                }
+				],
+				'custom_fields': [
+				{
+                                    label: string,
+                                    value: string,
+                                    secret: bool,
+                                    field_type: 'text'
+                }
+				],
+				'otp': {},
+				'hidden': false
+			};
+```
+There are a few special fields here.
+- `custom_fields`
+   - Those fields are added by the user `secret` indicates if the value should be hidden
+
+When posting to the endpoint the following fields are required:
+- `label`
+- `vault_id`
+
+###Update credential [PATCH]
+`/api/v2/credentials/{credential_guid}`   
+See [create new credential](#Create new credential).
+
+
+
+###Decrypting Credentials / challenge password 
+For the client side encryption we use [sjcl](https://github.com/bitwiseshiftleft/sjcl)   
+To decrypt (and test if a valid key is given):
+```$xslt
+var encryption_config = {
+				adata: "",
+				iter: 1000,
+				ks: 256,
+				mode: 'ccm',
+				ts: 64
+};
+var ciphertext = window.atob(encryptedString);
+var rp = {};
+try {
+    return sjcl.decrypt(_key, ciphertext, encryption_config, rp);
+} catch (e) {
+    throw e; // Invalid key
+}
+```
+
+For decrypting the credentials you can use above code.   
+The following fields are encrypted:   
+- `description`
+- `username`
+- `password`
+- `files`
+- `custom_fields`
+- `otp`
+- `email`
+- `tags`
+- `url`
+
+