REST API

REST API

notes:

• all communication is assumed TLS encrypted.
• additional encryption to mitigate single point-of-failure from a compromised TLS is sparingly applied where most required, with an eye on keeping the processing load on the server as lightweight as possible.
• as defined by couchDB documentation, _rev values
  • start with a positive integer N,
  • followed by a dash -, and
  • end with a MD5 binary hash of the document
• throughout this document --_rev denotes the _rev value from the previous document, i.e. the '_rev' value that was included in the document when posting it to the database.
• SDBK denotes the encrypted private (secret) DB key.
  • SDBK(doc) denotes a doc encrypted with the SDBK.
  • SDBK[doc] denotes the signature of doc created with the SDBK.
• PBKDF2(password) denotes the PBKDF2 hash of password
• scrolling horizontally might be required to view complete lines of the table. this table can also be found in the cryptobox specification spreadsheet

endpoint	database/document	content	method	request/response	description
/api/cryptobox/:version	/_user		GET		retrieve signed server certificate for additionally encrypting messages to the server (in addition to TLS)
				200-OK { signed server certificate }	the server certificate is signed with an offline private certification key, the public counterpart of which is embedded in the client code running on the user agent. the user agent can verify the authenticity of the server certificate with the embedded public key.
			POST	-d { public DB key, signed identification string }	new account creation request. the identification string is used to uniquely identify the requesting user-agent during the verification process. this request triggers identity verification, e.g. email verification with the given identification string.
				202-ACCEPTED { path of pending user account endpoint (e.g. /api/cryptobox/:version/:uuid), path of couchDB host (e.g. /db/cryptobox) }	account creation is successfully initiated, but can only proceed further after successful verification. the user account status is now 'pending' verification. 'pending' status is valid 30min.
				400-BAD REQUEST	identification string is not authentic, i.e. is not signed with given public DB key
				401-UNAUTHORIZED	there is already a user account with one of the following status for the given email: a 'verified' status that has not yet expired, or a 'created' status, or an authenticated 'authorized' status
/api/cryptobox/:version/:uuid	/_user/org.couchdb.user:uuid	{ _id: org.couchdb.user:uuid, _rev: N-MD5, name: uuid, password: PBKDF2(account password), secret: PDBK(account password), roles: [], pdbkey: public DB key, status: { id: 'pending/verified/created/authorized', date: unix time stamp (, token: string) }, signature: SDBK[{ _id, --_rev, PBKDF2(password), roles, pdbkey, status }]	GET		get the public DB key of user UUID. needed for sharing, i.e. encrypting for another user.
				200-OK { public DB key }	important note: there is no guarantee that the returned key is authentic. authenticity must be verified independently., e.g. by authenticating the signature created with the private DB key of a secret known only to both parties, as is done with the secret modhex string for registering a new user agent.
				404-NOT FOUND	no authentic 'authorized' user account exists for the UUID from the url
			POST	-d { encrypted signed account password }	set the account password of a verified account, and complete account creation.
				201-CREATED { path of user document in '_user' database, path of 'agents' database for the new account }	successful creation of the user account for the UUID from the url. the requesting user agent can now access its user document and the 'agent' database for the new account directly from the couchDB endpoint with the uuid and given password. the user account status is now 'created'
				400-BAD REQUEST	cannot decrypt message
				401-UNAUTHORIZED	invalid password signature. only passwords signed with the private DB key, counterpart to the public DB key supplied in the account creation request, are accepted
				404-NOT FOUND	there is no user account with a non-expired 'verified' status for the UUID from the url. the 'verified' status expires at most 24h after successful verification, or when account creation is successfully completed within that time.
			DELETE	-H If-Match: SDBK[{ committed_update_seq, data_size, db_name, doc_count, doc_del_count, instance_start_time, purge_seq, update_seq }]	delete the UUID account. a signature created from a subset of the 'agent' database information must be supplied in the request header as 'If-Match' parameter. it avoids unintentional deletions and authenticates the request. retrieve the 'agent' database information from couchDB as follows: GET /:uuid/agent
				200-OK	UUID account successfully deleted. the corresponding user account document from the '_user' database and all corresponding databases owned by the UUID user, including the 'agent' database were successfully deleted.
				401-UNAUTHORIZED	signature not authentic or 'agent' database information mismatch
				404-NOT FOUND	UUID account does not exist
/api/cryptobox/:version/:uuid/agent	/:uuid/agent		POST	-d { public UA key, signed identification string, SUAK[{ public UA key, identification string, secret modhex string }] }	new user-agent registration request. this request triggers identity verification from another user-agent, registered for the UUID account. the identification string is used to help the user uniquely identify the requesting user-agent during the verification process. the user will also be required by the verifying user agent to enter the secret modhex string to authenticate the signature. the secret modhex string used in the signature must hence be known only to the user (e.g. displayed on the requesting user-agent). it should not be stored, transmitted or shared in any way.
				202-ACCEPTED { path of pending user agent endpoint (e.g. /api/cryptobox/:version/:uuid/agent/:key-fingerprint), token }	user-agent registration is successfully initiated, but can only proceed further after successful verification. the user-agent registration status is now 'pending' verification. verification can be processed from any registered user-agent, which will set the registration status to 'verified' upon success.
				400-BAD REQUEST	the UUID from the public UA key does not match that from the url
				404-NOT FOUND	no authentic “authorized” user account exists for the UUID from the url
/api/cryptobox/:version/:uuid/agent/:fingerprint	/:uuid/agent/:fingerprint	{ _id: UA key fingerprint, _rev: N-MD5,identifier: identification string, puakey: public UA key, sdbkey: PUAK(SDBK) secret DB key encrypted with the public UA key, status: { id: 'pending/verified/authorized', unix time stamp (, token, SUAK[{ puakey, identifier, secret modhex string }]) }, signature: SDBK[{ _id, --_rev, puakey, sdbkey, identifier, status }] }	POST	-d { signed token }	complete user-agent registration: retrieve private DB key and account password
				201-CREATED { path of user document in '_user' database, path of 'agents' database for the new account, PUAK(SDBK) encrypted passphrase-protected private DB key, PDBK(password) encrypted account password }	the status of the registration remains unchanged at 'verified'. if for some reason the received data is corrupt, the request can be repeated during the validity period of the “verified” status. the returned encrypted credentials enable the requesting user agent to complete the registration without any further server interaction: the requesting user agent must update its status to 'authorized'.
				401-UNAUTHORIZED	the token is not valid, or its signature is not authentic (not signed with private UA key)
				404-NOT FOUND	no authentic 'authorized' user account exists for the UUID from the url, or the user agent for key-fingerprint from the url is not authentically 'verified', or its 'verified' status has expired (max. 24h)
/api/cryptobox/:version/:uuid/:dbpath	/:uuid/:dbpath		PUT	-d { SDBK[/:uuid/:dbpath] }	create a database. the signature of the request path authenticates the request. note that replay attacks are not mitigated because not security critical.
				201-CREATED { admins: { names: [ uuid ], roles: [] }, members: { names: [ uuid ], roles: [] } }	database successfully created. a '_security' document was added to the created database restricting access to the new database to the requesting UUID, as described by the returned entries from the '_security' document.
				400-BAD REQUEST	invalid database name: dbpath must comply with ^[a-z][a-z0-9_$()+/-]*$ as mandated by couchDB
				401-UNAUTHORIZED	invalid signature. verification with public DB key failed.
				412-PRECONDITION FAILED	database already exists
			DELETE	-H If-Match: SDBK[{ committed_update_seq, data_size, db_name, doc_count, doc_del_count, instance_start_time, purge_seq, update_seq }]	delete the database at /:uuid/:dbpath. a signature created from a subset of the target database information must be supplied in the request header as 'If-Match' parameter. it avoids unintentional deletions, authenticates the request and helps mitigate replay attacks. retrieve the current database information from couchDB as follows: GET /:uuid/:dbpath
				200-OK	database successfully deleted
				400-BAD REQUEST	invalid database name: name must comply with ^[a-z][a-z0-9_$()+/-]*$ as mandated by couchDB
				401-UNAUTHORIZED	signature not authentic, target database information mismatch, or attempted to delete the 'agent' database, which is not allowed.
				404-NOT FOUND	database does not exist