nextcloud/passman
1
1
Fork 0
mirror of https://github.com/nextcloud/passman.git synced 2024-09-20 06:46:20 +08:00
Code Issues Packages Projects Releases Wiki Activity

Fix markdown syntax / reformatting of api.md

Browse source 
Signed-off-by: Samuel Barabas <samuel@owee.de>
This commit is contained in:
Samuel Barabas 2019-10-25 23:32:10 +02:00
parent 9aa31e8819
commit 330545dc51
1 changed files with 109 additions and 89 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

198
docs/api.md
View file

@ -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`