From 330545dc513b0b7fa161475ca4669fe4e5c777ee Mon Sep 17 00:00:00 2001 From: Samuel Barabas Date: Fri, 25 Oct 2019 23:32:10 +0200 Subject: Fix markdown syntax / reformatting of api.md Signed-off-by: Samuel Barabas --- docs/api.md | 198 +++++++++++++++++++++++++++++++++--------------------------- 1 file changed, 109 insertions(+), 89 deletions(-) (limited to 'docs') diff --git a/docs/api.md b/docs/api.md index 4fd9dea0..322c2ba0 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,7 +1,7 @@ Passman offers a api for extensions. -##Table of Contents +## Table of Contents - [Authentication](#authentication) - [Get vaults](#get-vaults-get) - [Get vault](#get-vault-get) @@ -9,129 +9,150 @@ Passman offers a api for extensions. - [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: + +## 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"); +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. + +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. +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" +{ + "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 +- `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 +### 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 +created: 1484175865 credentials: [{}, {}, ....] -guid:"64DDADA1-54A6-4BE6-AA2F-BCB2EC8E8455" -last_access:1484217620 +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 -``` +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` + +### 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 - }; + '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 + - 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}` + +### Update credential [PATCH] + +`/api/v2/credentials/{credential_guid}` See [create new credential](#Create new credential). +### Decrypting Credentials / challenge password -###Decrypting Credentials / challenge password -For the client side encryption we use [sjcl](https://github.com/bitwiseshiftleft/sjcl) +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 + adata: "", + iter: 1000, + ks: 256, + mode: 'ccm', + ts: 64 }; var ciphertext = window.atob(encryptedString); var rp = {}; @@ -142,8 +163,8 @@ try { } ``` -For decrypting the credentials you can use above code. -The following fields are encrypted: +For decrypting the credentials you can use above code. +The following fields are encrypted: - `description` - `username` - `password` @@ -154,4 +175,3 @@ The following fields are encrypted: - `tags` - `url` - -- cgit v1.2.3