-
-
Notifications
You must be signed in to change notification settings - Fork 189
Protocol V2 draft
| Command | Description |
|---|---|
associate |
Request for associating a new client with KeePassXC. |
change-public-keys |
Request for passing public keys from client to server and back. |
create-credentials |
Request for adding or updating credentials to the database. |
create-new-group |
Request for creating a new group to the database. |
delete-entry |
Request for deleting an entry from the database. |
generate-password |
Request for generating a password. KeePassXC's settings are used. |
get-credentials |
Request for retrieving credentials from all connected databases. |
get-database-entries |
Request for retrieving all credentials in the database. |
get-database-groups |
Request for receiving a list of all groups in the database. |
get-database-statuses |
Request for receiving statuses of all databases in KeePassXC. |
get-totp |
Request for receiving TOTP's. |
lock-database |
Request for locking the database from client. |
request-autotype |
Request for triggering Global Auto-Type in KeePassXC. |
Signals are sent by KeePassXC on certain actions. The two signals below happens when database is closed, opened, or database tab is switched and its status is passed to KeePassXC.
| Signal | Description |
|---|---|
database-locked |
Current active database is locked. |
database-unlocked |
Current active database is unlocked. |
All encrypted requests are formed as following:
{
"message": "<encrypted message>",
"nonce": "tZvLrBzkQ9GxXq9PvKJj4iAnfPT0VZ3Q",
"clientID": "<clientID>"
"requestID": "<requestID>",
"triggerUnlock": <optional boolean>
}
If the reply has an error, encrypted/decrypted message contains:
"error": <string>
"errorCode": <int>
If all connection keys ([Connection Keys]) are required for the request, it contains:
"keys": [
{
"id": "<saved database identifier received from associate>",
"key": "<saved identification public key>"
},
...
]
If only [Current Connection Key] is required, the array holds id and key only for the active database.
Connects the client to the current database active on KeePassXC. A new Identification Key is generated for the association. Response includes the connection name given in KeePassXC. Only applies to active database.
Request:
{
"action": <string>,
"idKey": <string, a new identification public key>,
"publicKey": <string, client public key>
}
Response:
{
"id": <string>,
"hash": <string>,
"version": <string>
}
Example request:
{
"action": "associate",
"idKey": "p4hA2P9wNLjYWwinEoqK43unr8xjnl8V7lCs2d6Rd3o=",
"publicKey": "awWQ40iK0nvfZ8R9zA1g30UcGIhGrHveQP6+YZjObkY="
}
Example response:
{
"id": "testclient",
"hash": "5bba70348a79595a0fa90d0b844e25560174da41c24af02913b0b523d4162ae6",
"version": "2.8.0"
}
Changes the connection keys with KeePassXC for further communication. KeePassXC side's public key is returned to the client.
Request:
{
"action": "change-public-keys",
"clientID": "<clientID>"
"nonce": "tZvLrBzkQ9GxXq9PvKJj4iAnfPT0VZ3Q",
"publicKey": "<client public key>",
}
Response:
{
"action": "change-public-keys",
"protocolVersion": 2,
"publicKey": "<host public key>",
"version": "2.8.0"
}
Creates or updates new credentials. If no specific group is given, default group "KeePassXC-Browser Passwords" is used. Only applies to active database.
downloadFavicon is not supported when updating credentials.
Request:
{
"action": "create-credentials",
"downloadFavicon": <optional boolean>,
"group": "<optional string: group name>",
"groupUuid": "<optional string: group UUID>",
"keys": [Current Connection Key],
"login": "user1",
"password": "passwd1",
"submitUrl": "<snip>",
"url": "<snip>",
"uuid": "<optional string: entry UUID>",
}
Response:
{
"result": <boolean>
}
Creates a new group. Returns the name and a new generated UUID for it. Only applies to active database.
Request:
{
"action": "create-new-group",
"groupName": "<group name or path>",
"keys": [Current Connection Key]
}
Response:
{
"name": "<group name>",
"uuid": "<group UUID>"
}
Deletes an entry based on entry UUID. Only applies to active database.
Request:
{
"keys": [Current Connection Key]
"uuid": "<UUID>"
}
Response:
{
"result": <boolean>
}
Sends a request to KeePassXC for showing a password generator popup. Accepted password is returned.
Request:
{
"action": "generate-password"
}
Response:
{
"password": "newPassword",
}
Returns credentials for requested URL. If autoLockRequested is true, database will lock immediately after credential fill.
Request:
{
"action": "get-credentials",
"httpAuth": <optional boolean>,
"keys": [Connection Keys],
"submitUrl": "<optional string>",
"url": "<snip>"
}
Response:
{
"entries" : [
{
"login": "user1",
"name": "user1",
"password": "passwd1"
},
{
"login": "user2",
"name": "user2",
"password": "passwd2",
"expired": true
}
],
autoLockRequested: <optional boolean>
}
Returns all entries from the selected database. Not allowed by default. This requires enabling an extra security setting in KeePassXC. No passwords are returned. Only applies to active database.
Request:
{
"action": "get-database-entries",
"keys": [Current Connection Key]
}
Response:
{
"entries": [
{
"title": "<Entry Title>,
"url": ""<Entry URL>,
"uuid": "<Entry UUID>"
},
...
]
}
Returns all groups from the selected database. Only applies to active database.
Request:
{
"action": "get-database-groups",
"keys": [Current Connection Key]
}
Response:
{
"defaultGroup": "<default group name>",
"defaultGroupAlwaysAllow": false,
"groups": [
{
"name": "Root",
"uuid": "<group UUID>",
"children": [
{
"name": "KeePassXC-Browser Passwords",
"uuid": "<group UUID>",
"children": []
},
{
"name": "SecondRoot",
"uuid": "<group UUID>",
"children": [
{
"name": "Child",
"uuid": "<group UUID>",
"children": [
{
"name": "GrandChild",
"uuid": "<group UUID>",
"children": []
}
]
}
]
},
{
"name": "ThirdRoot",
"uuid": "<group UUID>",
"children": [
{
"name": "Child2",
"uuid": "<group UUID>",
"children": []
}
]
},
{
"name": "Child2",
"uuid": "<group UUID>",
"children": []
}
]
}
]
}
Retrieves statuses of all databases in KeePassXC. This function is mainly used for checking if a database is associated with the client.
Request:
{
"action": "get-database-statuses"
"keys": [Connection Keys]
}
Response:
{
"hash": "<hash of active database>"
"statuses": [
{
"associated": false,
"hash": "<database hash>",
"locked": true
},
...
]
}
Returns all TOTP's based on the entry UUID's from connected databases.
Request:
{
"action": "get-totp",
"keys": [Connection Keys],
"uuids": [
"<entry 1 UUID>",
"<entry 2 UUID>",
...
]
}
Response:
{
"totpList": [
{
"totp": "<entry UUID>",
"uuid": "<TOTP>"
},
{
"totp": "<entry UUID>",
"uuid": "<TOTP>"
},
...
]
}
Locks databases. Setting lockSingle to true only locks the current active database. Returns always true if response is sent.
Request:
{
"action": "lock-database"
"lockSingle": <optional boolean>
}
Response:
{
"result": true
}
Sends a Global Auto-Type request to KeePassXC and performs an automatic search for the selected URL.
Request:
{
"action": "request-autotype",
"search": "<base domain of URL>"
}
Response:
{
"result": <boolean>
}