Overview
Documentation of the Open-Xchange OX Guard HTTP API
Version information
Version : 2.6.0
Contact information
Contact : Open-Xchange GmbH
Contact Email : info@open-xchange.com
URI scheme
Host : example.com
BasePath : /appsuite/api/oxguard
Schemes : HTTPS
Tags
-
login : The login module is used to obtain a Guard authentication token which can be used to decrypt encrypted data without providing the user’s password. To understands the details, please see article (TODO).
-
keys : The keys module provides functionality to create, receive and manage PGP key pairs.
Consumes
-
application/x-www-form-urlencoded
Produces
-
application/json
Resources
Keys
The keys module provides functionality to create, receive and manage PGP key pairs.
Deletes an uploaded external recipient key.
DELETE /keys?action=DeleteExternalPublicKey
Parameters
Type | Name | Description | Schema | Default |
---|---|---|---|---|
Query |
ids |
The ids parameter from the ExternalPublicKeyRing object as obtained from the GetExternalPublicKeys request. |
string |
|
Query |
session |
A session ID previously obtained from the Appsuite HTTP login module. |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
An empty response in case the key was deleted. |
No Content |
Marks an uploaded external recipient key as "inline".
PUT /keys?action=InlineExternalPublicKey
Description
An external public key which is marked as "inline" produces PGP/INLNE email encryption by default.
Parameters
Type | Name | Description | Schema | Default |
---|---|---|---|---|
Query |
ids |
The ids parameter from the ExternalPublicKeyRing object as obtained from the GetExternalPublicKeys request. |
string |
|
Query |
inline |
True, to mark the key ring as "inline", False to mark it as "not inline". |
boolean |
|
Query |
session |
A session ID previously obtained from the Appsuite HTTP login module. |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
An empty response in case the key was marked as inline. |
No Content |
Adds a new user ID "name <email>" to the given key ring.
PUT /keys?action=addUserId
Parameters
Type | Name | Description | Schema | Default |
---|---|---|---|---|
Query |
session |
A session ID previously obtained from the Appsuite HTTP login module. |
string |
|
FormData |
email |
The email part of "name <email>". |
string |
|
FormData |
keyId |
The master key ID of the key ring which should be changed. |
integer(int64) |
|
FormData |
name |
The name part of "name <email>". |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
An empty response in case the key was successfully marked as current. |
No Content |
Creates a new PGP key ring for the user
POST /keys?action=create
Description
Creates a new PGP key ring for the user and marks the new key ring as "current".
Parameters
Type | Name | Description | Schema | Default |
---|---|---|---|---|
Query |
session |
A session ID previously obtained from the Appsuite HTTP login module. |
string |
|
FormData |
name |
The user’s name which will be part of the key identity. |
string |
|
FormData |
password |
The new password which will be set to protect the private key. |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
The new created key ring. |
Delete a user’s PGP key ring
POST /keys?action=delete
Description
Delete a specific PGP key ring
Parameters
Type | Name | Description | Schema | Default |
---|---|---|---|---|
Query |
keyid |
The master key ID of the key ring which should be deleted. |
string |
|
Query |
session |
A session ID previously obtained from the Appsuite HTTP login module. |
string |
|
FormData |
password |
The password of the private key. |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
An empty response in case the key has been deleted. |
No Content |
Downloads the ASCII armored representation of a specific PGP key ring owned by the user containing public and/or private PGP keys.
POST /keys?action=downloadKey
Description
This request fetches the raw ASCII armored PGP key ring data.
Parameters
Type | Name | Description | Schema | Default |
---|---|---|---|---|
Query |
keyId |
Specifies the ID of the key to fetch. If this parameter is omitted the key marked as "current" is returned instead. |
integer(int64) |
|
Query |
keyType |
Specifies if the public and/or the private key of the key ring should be fetched. |
enum (public, private, public_private) |
|
Query |
session |
A session ID previously obtained from the Appsuite HTTP login module. |
string |
|
FormData |
password |
The password of the private key (if keyType is set to 'private' or 'public_private') |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
The public and/or private part of the specified key ring as raw ASCII armored data. |
string(binary) |
Produces
-
application/pgp-keys
Gets a list of upload public keys for external recipients.
GET /keys?action=getExternalPublicKeys
Description
A user can upload public key rings for other external communication partners. This requests gets the uploaded public key rings for externals including useful meta information.
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
The collection of uploaded external key rings. |
Gets a specific PGP key ring owned by the user containing public and/or private PGP keys.
POST /keys?action=getKey
Description
This request fetches detailed information about a specific PGP key ring.
Parameters
Type | Name | Description | Schema | Default |
---|---|---|---|---|
Query |
keyId |
Specifies the ID of the key to fetch. If this parameter is missing the key marked as "current" is returned instead. |
integer(int64) |
|
Query |
keyType |
Specifies if the public and/or the private key of the key ring should be fetched. |
enum (public, private, public_private) |
|
Query |
session |
A session ID previously obtained from the Appsuite HTTP login module. |
string |
|
FormData |
password |
The password of the private key (if keyType is set to 'private' or 'public_private') |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
The public and/or private part of the specified key ring. |
Gets the the user’s collection of public PGP key rings.
GET /keys?action=getKeys
Description
A user can have multiple PGP key rings. This requests returns all public keys in a single collection.
Parameters
Type | Name | Description | Schema | Default |
---|---|---|---|---|
Query |
session |
A session ID previously obtained from the Appsuite HTTP login module. |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
A collection of the user’s public key rings. |
Checks if the user has at least one public and/or private PGP key available.
GET /keys?action=hasKey
Parameters
Type | Name | Description | Schema | Default |
---|---|---|---|---|
Query |
session |
A session ID previously obtained from the Appsuite HTTP login module. |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
A JSON object which contains if the user has a private and/or public key setup. |
Revokes a user’s PGP key ring.
POST /keys?action=revoke
Description
Reovkes a PGP key ring.
Parameters
Type | Name | Description | Schema | Default |
---|---|---|---|---|
Query |
keyId |
Specifies the ID of the master key to revoke. |
integer(int64) |
|
Query |
session |
A session ID previously obtained from the Appsuite HTTP login module. |
string |
|
FormData |
password |
The password of the private key. |
string |
|
FormData |
reason |
Specifies the reason why the key is being revoked. |
enum (no_reason, key_superseded, key_compromised, key_retired, user_no_longer_valid) |
|
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
An empty response in case the key was revoked. |
No Content |
Marks a Guard PGP key ring as "current".
PUT /keys?action=setCurrentKey
Parameters
Type | Name | Description | Schema | Default |
---|---|---|---|---|
Query |
keyId |
The master key ID of the key ring which should be marked as "current". |
integer(int64) |
|
Query |
session |
A session ID previously obtained from the Appsuite HTTP login module. |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
An empty response in case the key was successfully marked as current. |
No Content |
Marks an uploaded external recipient key as shared or as not shared.
PUT /keys?action=shareExternalPublicKey
Description
An external public key which is marked as shared can be accessed from other OX Guard users in the same context.
Parameters
Type | Name | Description | Schema | Default |
---|---|---|---|---|
Query |
ids |
The ids parameter from the ExternalPublicKeyRing object as obtained from the GetExternalPublicKeys request. |
string |
|
Query |
session |
A session ID previously obtained from the Appsuite HTTP login module. |
string |
|
Query |
shared |
True, to mark the key ring as "shared", False to mark it as "not shared". |
boolean |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
An empty response in case the key was marked as shared. |
No Content |
Uploads a new key ring to OX Guard.
POST /keys?action=upload
Description
Uploads a new ASCII armored key ring to OX Guard. The key ring can contain public and/or private keys.
Parameters
Type | Name | Description | Schema | Default |
---|---|---|---|---|
Query |
session |
A session ID previously obtained from the Appsuite HTTP login module. |
string |
|
FormData |
key |
The ASCII armored data of the key ring. |
string |
|
FormData |
keyPassword |
The password of the private key. Can be omitted if the uploaded key ring does only contain public keys. |
string |
|
FormData |
newPassword |
The new password to set for the imported private keys. Can be omitted if the uploaded key ring does only contain public keys. |
string |
Responses
HTTP Code | Description | Schema |
---|---|---|
200 |
An empty response in case the key rings have been imported. |
No Content |
Definitions
CreateResponse
Name | Description | Schema |
---|---|---|
categories |
Either a single (String) or list (Array) of upper-case category identifiers to which the error belongs. |
string |
category |
Maintained for legacy reasons: The numeric representation of the first category. |
integer |
code |
Error code consisting of an upper-case module identifier and a four-digit message number, separated by a dash; e.g. "MSG-0012" |
string |
data |
||
error |
The translated error message. Present in case of errors. |
string |
error_desc |
The technical error message (always English) useful for debugging the problem. Might be the same as error message if there is no more information available. |
string |
error_id |
Unique error identifier to help finding this error instance in the server logs. |
string |
error_params |
As of 7.4.2: Empty JSON array. Before that: Parameters for the error message that would need to be replaced in the error string (in a printf-format style). |
< string > array |
error_stack |
If configured (see "com.openexchange.ajax.response.includeStackTraceOnError" in "server.properties") this field provides the stack trace of associated Java exception represented as a JSON array. |
< string > array |
ExternalPublicKeyRing
Name | Description | Schema |
---|---|---|
ids |
The Identifier of the external key ring. |
string |
inline |
True, if the key is marked as inline, False otherwise. |
boolean |
publicRing |
||
shareLevel |
The share level. A key is considered to be shared if the share level is greater than 0. |
integer |
shared |
True, if the key ring is shared, False otherwise |
boolean |
ExternalPublicKeyRingCollection
Name | Description | Schema |
---|---|---|
externalPublicKeyRings |
An array of PGP key rings belonging to external recipients. |
< ExternalPublicKeyRing > array |
GetExternalPublicKeysResponse
Name | Description | Schema |
---|---|---|
categories |
Either a single (String) or list (Array) of upper-case category identifiers to which the error belongs. |
string |
category |
Maintained for legacy reasons: The numeric representation of the first category. |
integer |
code |
Error code consisting of an upper-case module identifier and a four-digit message number, separated by a dash; e.g. "MSG-0012" |
string |
data |
||
error |
The translated error message. Present in case of errors. |
string |
error_desc |
The technical error message (always English) useful for debugging the problem. Might be the same as error message if there is no more information available. |
string |
error_id |
Unique error identifier to help finding this error instance in the server logs. |
string |
error_params |
As of 7.4.2: Empty JSON array. Before that: Parameters for the error message that would need to be replaced in the error string (in a printf-format style). |
< string > array |
error_stack |
If configured (see "com.openexchange.ajax.response.includeStackTraceOnError" in "server.properties") this field provides the stack trace of associated Java exception represented as a JSON array. |
< string > array |
GetKeyResponse
Name | Description | Schema |
---|---|---|
categories |
Either a single (String) or list (Array) of upper-case category identifiers to which the error belongs. |
string |
category |
Maintained for legacy reasons: The numeric representation of the first category. |
integer |
code |
Error code consisting of an upper-case module identifier and a four-digit message number, separated by a dash; e.g. "MSG-0012" |
string |
data |
||
error |
The translated error message. Present in case of errors. |
string |
error_desc |
The technical error message (always English) useful for debugging the problem. Might be the same as error message if there is no more information available. |
string |
error_id |
Unique error identifier to help finding this error instance in the server logs. |
string |
error_params |
As of 7.4.2: Empty JSON array. Before that: Parameters for the error message that would need to be replaced in the error string (in a printf-format style). |
< string > array |
error_stack |
If configured (see "com.openexchange.ajax.response.includeStackTraceOnError" in "server.properties") this field provides the stack trace of associated Java exception represented as a JSON array. |
< string > array |
GetKeysResponse
Name | Description | Schema |
---|---|---|
categories |
Either a single (String) or list (Array) of upper-case category identifiers to which the error belongs. |
string |
category |
Maintained for legacy reasons: The numeric representation of the first category. |
integer |
code |
Error code consisting of an upper-case module identifier and a four-digit message number, separated by a dash; e.g. "MSG-0012" |
string |
data |
||
error |
The translated error message. Present in case of errors. |
string |
error_desc |
The technical error message (always English) useful for debugging the problem. Might be the same as error message if there is no more information available. |
string |
error_id |
Unique error identifier to help finding this error instance in the server logs. |
string |
error_params |
As of 7.4.2: Empty JSON array. Before that: Parameters for the error message that would need to be replaced in the error string (in a printf-format style). |
< string > array |
error_stack |
If configured (see "com.openexchange.ajax.response.includeStackTraceOnError" in "server.properties") this field provides the stack trace of associated Java exception represented as a JSON array. |
< string > array |
HasKeyResponse
Name | Description | Schema |
---|---|---|
categories |
Either a single (String) or list (Array) of upper-case category identifiers to which the error belongs. |
string |
category |
Maintained for legacy reasons: The numeric representation of the first category. |
integer |
code |
Error code consisting of an upper-case module identifier and a four-digit message number, separated by a dash; e.g. "MSG-0012" |
string |
data |
||
error |
The translated error message. Present in case of errors. |
string |
error_desc |
The technical error message (always English) useful for debugging the problem. Might be the same as error message if there is no more information available. |
string |
error_id |
Unique error identifier to help finding this error instance in the server logs. |
string |
error_params |
As of 7.4.2: Empty JSON array. Before that: Parameters for the error message that would need to be replaced in the error string (in a printf-format style). |
< string > array |
error_stack |
If configured (see "com.openexchange.ajax.response.includeStackTraceOnError" in "server.properties") this field provides the stack trace of associated Java exception represented as a JSON array. |
< string > array |
HasKeyResult
An result object which describes if the user has a key pair available or not.
Name | Description | Schema |
---|---|---|
hasPrivateKey |
True, if the user has at least one private PGP key, False otherwise |
boolean |
hasPublicKey |
True, if the user has at least one public PGP key, False otherwise |
boolean |
KeyRing
The key ring of the response.
Name | Description | Schema |
---|---|---|
contextId |
The context ID of the user |
integer |
current |
Whether the key ring is marked as "current" or not |
boolean |
privateRing |
||
publicRing |
||
userId |
The user ID |
integer |
KeyRingCollection
Name | Description | Schema |
---|---|---|
keyRings |
An array of PGP key rings containing public and/or private PGP keys. |
< KeyRing > array |
PrivateKey
Private key meta data
Name | Description | Schema |
---|---|---|
expired |
True, if the key is marked as expired, False otherwise. |
boolean |
id |
The PGP key ID. |
integer(int64) |
masterKey |
True, if the key is the "master" key, false otherwise. |
boolean |
userIds |
An array containing all user identifiers. |
< string > array |
PrivateKeyRing
Name | Description | Schema |
---|---|---|
keys |
An array of private keys |
< PrivateKey > array |
ring |
The ASCII armored key material of the private key ring. |
string |
PublicKey
Public key meta data
Name | Description | Schema |
---|---|---|
creationTime |
The time stamp of creation (milliseconds since January 1, 1970, 00:00:00 GMT). |
integer(int64) |
encryptionKey |
True, if the key can be used for encryption, false otherwise. |
boolean |
expired |
True, if the key is marked as expired, False otherwise. |
boolean |
fingerPrint |
The hexadecimal representation of the key ID. |
string |
hasPrivateKey |
True, if the public key has a known corresponding private key. |
boolean |
id |
The PGP key ID. |
integer(int64) |
masterKey |
True, if the key is the "master" key, false otherwise. |
boolean |
revoked |
True, if the key has been revoked, false otherwise. |
boolean |
userIds |
An array containing all user identifiers. |
< string > array |
validSeconds |
The amount of seconds that the key is valid. |
integer(int64) |
PublicKeyRing
Name | Description | Schema |
---|---|---|
keys |
An array of public keys |
< PublicKey > array |
ring |
The ASCII armored key material of the public key ring. |
string |