diff options
-rw-r--r-- | docs/api.md | 157 |
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` + + |