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
required

The ids parameter from the ExternalPublicKeyRing object as obtained from the GetExternalPublicKeys request.

string

Query

session
required

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
required

The ids parameter from the ExternalPublicKeyRing object as obtained from the GetExternalPublicKeys request.

string

Query

inline
required

True, to mark the key ring as "inline", False to mark it as "not inline".

boolean

Query

session
required

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
required

A session ID previously obtained from the Appsuite HTTP login module.

string

FormData

email
required

The email part of "name <email>".

string

FormData

keyId
required

The master key ID of the key ring which should be changed.

integer(int64)

FormData

name
required

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
required

A session ID previously obtained from the Appsuite HTTP login module.

string

FormData

name
required

The user’s name which will be part of the key identity.

string

FormData

password
required

The new password which will be set to protect the private key.

string

Responses
HTTP Code Description Schema

200

The new created key ring.

CreateResponse

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
required

The master key ID of the key ring which should be deleted.

string

Query

session
required

A session ID previously obtained from the Appsuite HTTP login module.

string

FormData

password
required

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
optional

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
optional

Specifies if the public and/or the private key of the key ring should be fetched.

enum (public, private, public_private)

"public_private"

Query

session
required

A session ID previously obtained from the Appsuite HTTP login module.

string

FormData

password
optional

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.

GetExternalPublicKeysResponse

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
optional

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
optional

Specifies if the public and/or the private key of the key ring should be fetched.

enum (public, private, public_private)

"public_private"

Query

session
required

A session ID previously obtained from the Appsuite HTTP login module.

string

FormData

password
optional

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.

GetKeyResponse

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
required

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.

GetKeysResponse

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
required

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.

HasKeyResponse

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
required

Specifies the ID of the master key to revoke.

integer(int64)

Query

session
required

A session ID previously obtained from the Appsuite HTTP login module.

string

FormData

password
required

The password of the private key.

string

FormData

reason
optional

Specifies the reason why the key is being revoked.

enum (no_reason, key_superseded, key_compromised, key_retired, user_no_longer_valid)

"no_reason"

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
required

The master key ID of the key ring which should be marked as "current".

integer(int64)

Query

session
required

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
required

The ids parameter from the ExternalPublicKeyRing object as obtained from the GetExternalPublicKeys request.

string

Query

session
required

A session ID previously obtained from the Appsuite HTTP login module.

string

Query

shared
required

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
required

A session ID previously obtained from the Appsuite HTTP login module.

string

FormData

key
required

The ASCII armored data of the key ring.

string

FormData

keyPassword
optional

The password of the private key. Can be omitted if the uploaded key ring does only contain public keys.

string

FormData

newPassword
optional

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
optional

Either a single (String) or list (Array) of upper-case category identifiers to which the error belongs.

string

category
optional

Maintained for legacy reasons: The numeric representation of the first category.

integer

code
optional

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
optional

KeyRing

error
optional

The translated error message. Present in case of errors.

string

error_desc
optional

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
optional

Unique error identifier to help finding this error instance in the server logs.

string

error_params
optional

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
optional

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
optional

The Identifier of the external key ring.

string

inline
optional

True, if the key is marked as inline, False otherwise.

boolean

publicRing
optional

PublicKeyRing

shareLevel
optional

The share level. A key is considered to be shared if the share level is greater than 0.

integer

shared
optional

True, if the key ring is shared, False otherwise

boolean

ExternalPublicKeyRingCollection

Name Description Schema

externalPublicKeyRings
optional

An array of PGP key rings belonging to external recipients.

< ExternalPublicKeyRing > array

GetExternalPublicKeysResponse

Name Description Schema

categories
optional

Either a single (String) or list (Array) of upper-case category identifiers to which the error belongs.

string

category
optional

Maintained for legacy reasons: The numeric representation of the first category.

integer

code
optional

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
optional

ExternalPublicKeyRingCollection

error
optional

The translated error message. Present in case of errors.

string

error_desc
optional

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
optional

Unique error identifier to help finding this error instance in the server logs.

string

error_params
optional

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
optional

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
optional

Either a single (String) or list (Array) of upper-case category identifiers to which the error belongs.

string

category
optional

Maintained for legacy reasons: The numeric representation of the first category.

integer

code
optional

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
optional

KeyRing

error
optional

The translated error message. Present in case of errors.

string

error_desc
optional

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
optional

Unique error identifier to help finding this error instance in the server logs.

string

error_params
optional

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
optional

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
optional

Either a single (String) or list (Array) of upper-case category identifiers to which the error belongs.

string

category
optional

Maintained for legacy reasons: The numeric representation of the first category.

integer

code
optional

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
optional

KeyRingCollection

error
optional

The translated error message. Present in case of errors.

string

error_desc
optional

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
optional

Unique error identifier to help finding this error instance in the server logs.

string

error_params
optional

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
optional

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
optional

Either a single (String) or list (Array) of upper-case category identifiers to which the error belongs.

string

category
optional

Maintained for legacy reasons: The numeric representation of the first category.

integer

code
optional

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
optional

HasKeyResult

error
optional

The translated error message. Present in case of errors.

string

error_desc
optional

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
optional

Unique error identifier to help finding this error instance in the server logs.

string

error_params
optional

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
optional

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
optional

True, if the user has at least one private PGP key, False otherwise

boolean

hasPublicKey
optional

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
optional

The context ID of the user

integer

current
optional

Whether the key ring is marked as "current" or not

boolean

privateRing
optional

PrivateKeyRing

publicRing
optional

PublicKeyRing

userId
optional

The user ID

integer

KeyRingCollection

Name Description Schema

keyRings
optional

An array of PGP key rings containing public and/or private PGP keys.

< KeyRing > array

PrivateKey

Private key meta data

Name Description Schema

expired
optional

True, if the key is marked as expired, False otherwise.

boolean

id
optional

The PGP key ID.

integer(int64)

masterKey
optional

True, if the key is the "master" key, false otherwise.

boolean

userIds
optional

An array containing all user identifiers.

< string > array

PrivateKeyRing

Name Description Schema

keys
optional

An array of private keys

< PrivateKey > array

ring
optional

The ASCII armored key material of the private key ring.

string

PublicKey

Public key meta data

Name Description Schema

creationTime
optional

The time stamp of creation (milliseconds since January 1, 1970, 00:00:00 GMT).

integer(int64)

encryptionKey
optional

True, if the key can be used for encryption, false otherwise.

boolean

expired
optional

True, if the key is marked as expired, False otherwise.

boolean

fingerPrint
optional

The hexadecimal representation of the key ID.

string

hasPrivateKey
optional

True, if the public key has a known corresponding private key.

boolean

id
optional

The PGP key ID.

integer(int64)

masterKey
optional

True, if the key is the "master" key, false otherwise.

boolean

revoked
optional

True, if the key has been revoked, false otherwise.

boolean

userIds
optional

An array containing all user identifiers.

< string > array

validSeconds
optional

The amount of seconds that the key is valid.

integer(int64)

PublicKeyRing

Name Description Schema

keys
optional

An array of public keys

< PublicKey > array

ring
optional

The ASCII armored key material of the public key ring.

string