TrinityD API (0.1.0)

Download OpenAPI specification:Download

P3KI GmbH: support@p3ki.com URL: https://p3ki.com License: MIT

HTTP API for Trinity

Handshaking

Trust handshaking related API requests.

Create Challenge

post /identity/{identity}/handshake/challenge

Base path for a local deployment of trinityd.

https://localhost/api/v1/identity/{identity}/handshake/challenge

Initialize a handshake challenge message.

path Parameters
identity
required
string[a-z][-_a-z0-9]*

The alias of an identity.

Each alias represents a single cryptographic key pair, the actual identity.

Request Body schema: application/json
language
required
string <trinity-policy> (language)

Serialized string representation of a trinity policy language.

min_policy
required
string <trinity-policy> (policy)

Serialized string representation of a trinity policy.

Attention: The expected schema of a such serialized policy depends on the policy language defined by the actual application.

max_policy
string <trinity-policy> (policy)

Serialized string representation of a trinity policy.

Attention: The expected schema of a such serialized policy depends on the policy language defined by the actual application.

Responses

500

Bad Request. Wrong formatted input.

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "language": "action:tdns(atomic)",
  • "min_policy": "action:{foo.bar}",
  • "max_policy": "action:{foo.bar}"
}

Create Response

post /identity/{identity}/handshake/response

Base path for a local deployment of trinityd.

https://localhost/api/v1/identity/{identity}/handshake/response

Create a handshake response message.

path Parameters
identity
required
string[a-z][-_a-z0-9]*

The alias of an identity.

Each alias represents a single cryptographic key pair, the actual identity.

Request Body schema: application/json
challenge
required
string <byte>

Url-safe base64 encoded trust handshake challenge.

certificates
required
Array of strings <byte> (certificate)

List of url-safe base64 encoded trust certificates.

The signed information contained in these certificates will serve as trust anchors while the validation process checks for the widest available trust relationship between the

Responses

500

Bad Request. Wrong formatted input.

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "challenge": "string",
  • "certificates":
    [
    ]
}

Response verification

post /verify/handshake

Base path for a local deployment of trinityd.

https://localhost/api/v1/verify/handshake

Verify the response to a trust challenge.

Ensures that a given response matches a specific challenge and checks that the response contains enough information to proof the existence of the expected trust relationship.

Request Body schema: application/json
challenge
required
string <byte>

Url-safe base64 encoded trust handshake challenge.

response
required
string <byte>

Url-safe base64 encoded trust handshake response.

Responses

200

Verification successful.

400

Error. Wrong formatted input.

422

Error. Wrong response or missing trust.

500

Error. Internal Server Error.

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "challenge": "string",
  • "response": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "success": true,
  • "policy": "action:{foo.bar}",
  • "error": ""
}

Identity Management

Identity lifecycle related API requests.

Lists identities

get /identity

Base path for a local deployment of trinityd.

https://localhost/api/v1/identity

Lists all available identities.

Responses

200

A list of available identities.

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "public":
    [
    ]
}

Get key of identity

get /identity/{identity}

Base path for a local deployment of trinityd.

https://localhost/api/v1/identity/{identity}

Request the actual cryptographic public key of the identity.

path Parameters
identity
required
string[a-z][-_a-z0-9]*

The alias of an identity.

Each alias represents a single cryptographic key pair, the actual identity.

Responses

200

Success.

500

Error. Identity not found.

Response samples

Content type
application/json
Copy
Expand all Collapse all
"AAABP8wtjqWMjkv2lk8-i16c5Syp0FFAMWfm7rFrckfBqik"

Create identity

post /identity/{identity}

Base path for a local deployment of trinityd.

https://localhost/api/v1/identity/{identity}

Creates a new identity.

path Parameters
identity
required
string[a-z][-_a-z0-9]*

The alias of an identity.

Each alias represents a single cryptographic key pair, the actual identity.

query Parameters
reinitialize
boolean
Default: false

Reinitialize the given identity with a new key pair.

This will preserve all of the identity's relationships but requires an active reexport afterwards. This is necessary as we need a signature using the new key pair to make the relationships public available again.

Attention: Existing relationships of other identities managed by the same daemon are not effected by this call. They will still mention the old public key as their target and must be changed independently.

Responses

200

Success. The creation or re-initialization of the identity was successful. The new public key of the identity is contained inside the response.

500

Error.

If the reinitialization query parameter is not present or explicitly set to false and error occurs if an identity with this alias already exists. In any other case the identity couldn't be detected.

Response samples

Content type
application/json
Copy
Expand all Collapse all
"AAABP8wtjqWMjkv2lk8-i16c5Syp0FFAMWfm7rFrckfBqik"

Monitoring

Monitoring related API requests.

Ping

get /ping

Base path for a local deployment of trinityd.

https://localhost/api/v1/ping

Trigger a simple "Pong" response to verify the reachability and latency of the instance.

Responses

200

A simple "Pong" response.

Response samples

Content type
application/json
Copy
Expand all Collapse all
"Pong"

Policy

Policy language related API requests.

Meet policies

post /policy/meet

Base path for a local deployment of trinityd.

https://localhost/api/v1/policy/meet

Calculate the greatest lower bound.

This operation takes a list of string formatted trust policies and tries to calculate the greatest lower bound for all given policies.

The resulting policy will also be returned as json string formatted trust policy.

Attention: If the given policies do not belong to the same policy language the result will always be the bottom element (represented as "_").

Request Body schema: application/json
language
required
string <trinity-policy> (language)

Serialized string representation of a trinity policy language.

policies
required
Array of strings <trinity-policy> (policy)

List of all policies to meet.

Responses

200

Success. Calculated policy.

500

Bad Request. Wrong formatted input.

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "language": "action:tdns(atomic)",
  • "policies":
    [
    ]
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
"action:{foo.bar}"

Join policies

post /policy/join

Base path for a local deployment of trinityd.

https://localhost/api/v1/policy/join

Calculate the smallest upper bound.

This operation takes a list of string formatted trust policies and tries to calculate the smallest upper bound for all given policies.

The resulting policy will also be returned as string formatted trust policy.

Attention: If the given policies do not belong to the same policy language the result will always be the bottom element (represented as "_").

Request Body schema: application/json
language
required
string <trinity-policy> (language)

Serialized string representation of a trinity policy language.

policies
required
Array of strings <trinity-policy> (policy)

List of all policies to meet.

Responses

200

Success. Calculated policy.

500

Bad Request. Wrong formatted input.

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "language": "action:tdns(atomic)",
  • "policies":
    [
    ]
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
"action:{foo.bar}"

Trust Management

Trust relationship lifecycle related API requests.

List relationships.

get /identity/{identity}/trust

Base path for a local deployment of trinityd.

https://localhost/api/v1/identity/{identity}/trust

List all trust relationships of the identity stored in the specified scopes.

This can be used to get an overview of all existing relationionships and their current validity dates, e.g. to determine if the identity contains expired relationships or relationships which require an updated of the target key.

path Parameters
identity
required
string[a-z][-_a-z0-9]*

The alias of an identity.

Each alias represents a single cryptographic key pair, the actual identity.

query Parameters
scopes
Array of strings (scope)
Items Enum: "public" "private"
Example: scopes=public,private

Set containing a list of unique trust scopes.

Responses

200

A list of the identity's relationships.

500

Error. Identity not found.

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Export signed trust certificate.

get /identity/{identity}/trust/export

Base path for a local deployment of trinityd.

https://localhost/api/v1/identity/{identity}/trust/export

Export a signed trinity certificate.

The certificate contains a list of all requested relationships but is also signed the by the identity's private key. This can be used to export the public relationships of the identity or to create a custom short living proof of the relationship existence containing private relationship information.

path Parameters
identity
required
string[a-z][-_a-z0-9]*

The alias of an identity.

Each alias represents a single cryptographic key pair, the actual identity.

query Parameters
scopes
Array of strings (scope)
Items Enum: "public" "private"
Example: scopes=public,private

Set containing a list of unique trust scopes.

Responses

200

A trust certificate containing a signed list of relationships. These relationships represent the trust information of the given identity.

500

Error. Identity not found.

Response samples

Content type
application/json
Copy
Expand all Collapse all
"ZDI6aHRkNjpTSEEyNTZkZWU1OnJvb3RzZDMyOhwj85tmpUhrVeUrYVSl1oPBAr8 CPAtU+I/iTzLrheNwbGQ1OmlubmVyZDE6Y2kxNTM2MjQ1NzM0OTAwZTE6cmRlZT EwOnB1YmxpY19rZXkzMjocI/ObZqVIa1XlK2FUpdaDwQK/AjwLVPiP4k8y64Xjc Dk6c2lnbmF0dXJlbGkxMTBlaTM2ZWkxODNlaTI0ZWkyMDBlaTkyZWk4OWVpMTMz ZWk0NmVpNTZlaTIzOGVpNTBlaTEzMGVpMTczZWkxMzVlaTE4MWVpMjAzZWk3ZWk xNjZlaTc3ZWkxMDVlaTUzZWkxNzZlaTIxMWVpMjA1ZWkyNGVpMTc2ZWkxNTVlaT E1ZWk0MWVpNTVlaTIyMGVpMTMwZWk5N2VpMjI2ZWkyMjhlaTU0ZWkyNmVpMjExZ WkyMTFlaTI1ZWkxNTFlaTg5ZWkxNTBlaTQzZWk3MGVpMTQ0ZWkzMWVpMjI3ZWky MzBlaTI0NGVpMTg4ZWkyMDllaTI0MWVpMzNlaTIxOGVpMTI5ZWk5MWVpODhlaTE 4NmVpMjI5ZWk5NmVpMjdlaThlaTEwMGVpNDllaTU4ZWk5OWVpMTA1ZWk0OWVpNT NlaTUxZWk1NGVpNTBlaTUyZWk1M2VpNTVlaTUxZWk1MmVpNTdlaTQ4ZWk0OGVpM TAxZWk0OWVpNThlaTExNGVpMTAwZWkxMDFlaTEwMWVlZWVlZQ=="

Get relationship.

get /identity/{identity}/trust/{key}

Base path for a local deployment of trinityd.

https://localhost/api/v1/identity/{identity}/trust/{key}

Returns the trust relationship from the identity to the given public-key.

Hint: If no relationship exist this will return the a default one representing no trust at all without any custom validity dates.

path Parameters
identity
required
string[a-z][-_a-z0-9]*

The alias of an identity.

Each alias represents a single cryptographic key pair, the actual identity.

key
required
string <byte>

A cryptographic key formatted as url-safe base64 encoded byte string.

query Parameters
scopes
Array of strings (scope)
Items Enum: "public" "private"
Example: scopes=public,private

Set containing a list of unique trust scopes.

Responses

200

Success

500

Error. Identity not found.

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Set relationship.

post /identity/{identity}/trust/{key}

Base path for a local deployment of trinityd.

https://localhost/api/v1/identity/{identity}/trust/{key}

Create, replace or update a trust relationship from the identity to the given public-key.

Hint: If its required to delete an existing valid start or end date it is expected to pass null for the specific value.

Attention: This doesn't contain a target parameter as this is already defined through the request path.

path Parameters
identity
required
string[a-z][-_a-z0-9]*

The alias of an identity.

Each alias represents a single cryptographic key pair, the actual identity.

key
required
string <byte>

A cryptographic key formatted as url-safe base64 encoded byte string.

query Parameters
scopes
Array of strings (scope)
Items Enum: "public" "private"
Example: scopes=public,private

Set containing a list of unique trust scopes.

Request Body schema: application/json
policy
required
string <trinity-policy> (policy)

Serialized string representation of a trinity policy.

Attention: The expected schema of a such serialized policy depends on the policy language defined by the actual application.

valid_from
unix_date_nullable (integer) or iso_date_nullable (string)
valid_until
unix_date_nullable (integer) or iso_date_nullable (string)

Responses

200

Sucess. Relationship stored.

500

Error. Invalid input.

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "policy": "action:{foo.bar}",
  • "valid_from": 1536662725,
  • "valid_until": 1536662725
}

Delete relationship.

delete /identity/{identity}/trust/{key}

Base path for a local deployment of trinityd.

https://localhost/api/v1/identity/{identity}/trust/{key}

Removes the trust relationship from the given identity.

path Parameters
identity
required
string[a-z][-_a-z0-9]*

The alias of an identity.

Each alias represents a single cryptographic key pair, the actual identity.

key
required
string <byte>

A cryptographic key formatted as url-safe base64 encoded byte string.

query Parameters
scopes
Array of strings (scope)
Items Enum: "public" "private"
Example: scopes=public,private

Set containing a list of unique trust scopes.

Responses

200

Success. Relationship deleted.

500

Error. Identity or relationship not found.

Verify trust.

post /verify/trust

Base path for a local deployment of trinityd.

https://localhost/api/v1/verify/trust

Verifiy the existance of a trust relationship.

The verification depends on the trust stored in trust certificates which must be provided by the caller. If additional certificates are providedd the verification process is going to validate the contained signed data and will only use sucessful validated trust relationships.

Hint: There is a list of additional verification settings which can be used to specify extended verification behaviour.

Request Body schema: application/json
source
required
object

The alias of an identity.

Each alias represents a single cryptographic key pair, the actual identity.

target
required
object

A cryptographic key formatted as url-safe base64 encoded byte string.

language
required
string <trinity-policy> (language)

Serialized string representation of a trinity policy language.

policy
required
string <trinity-policy> (policy)

Serialized string representation of a trinity policy.

Attention: The expected schema of a such serialized policy depends on the policy language defined by the actual application.

certificates
required
Array of strings <byte> (certificate)

List of url-safe base64 encoded trust certificates.

The signed information contained in these certificates will serve as trust anchors while the validation process checks for the widest available trust relationship between the

at_time
iso_date (string) or unix_date (integer)
options
object

A set of additional verification settings.

Attention: None of these are available on Whitesands.

Responses

200

Verification processed all available data.

Contains the widest verified trust policy that could be verified based on the given trust certificates.

500

Bad Request. Wrong formatted parameter.

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "source": { },
  • "target": { },
  • "language": "action:tdns(atomic)",
  • "policy": "action:{foo.bar}",
  • "at_time": "2018-09-17T14:53:16+00:00",
  • "certificates":
    [
    ],
  • "options":
    {
    }
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
"action:{foo.bar}"