Whitesands Proving Ground

This is the online testing platform for the P3KI Core decentralized and offline-capable authorization and delegation framework.

Get started »

Roadmap

Whitesands is under active development. The roadmap for demo features is as follows:

  1. Improve documentation on TPLs
  2. Add a full scenario example with interaction between multiple nodes
  3. Release trinity-cli command line utility to interact with Whitesands (alternative to curl)
  4. Add examples in Python and Rust
  5. Enable storage backend support for Whitesands demo environment

Current version

rev5 (2020-11-10)

rev5 (2020-11-10)
  • Feature: Whitesands uses API v2 now
  • Feature: WHitesands performance increased significantly. Requests should now be sub-second affairs.
  • Feature: /api/v2/reset now resets all instances in a single go
  • Deprecated: /api/v1/instance/{i}/reset is deprecated
rev4 (2019-12-11)
  • Feature: Whitesands now offering a /reset endpoint for instances.
rev3 (2019-12-05)
  • Doc: added handshake examples.
rev2 (2019-12-04)
  • Fix: Some requests to backends were dropped in the frontend due to connection pool exhaustion.
rev1 (2019-11-28)
  • Initial release

Get access

Whitesands is currently in closed beta status. To apply for access, please send an informal email to contact@p3ki.com or use the contact form linked below. Please make sure to include the following information:

  • Your name, contact info and affiliation.
  • What project/use-case you're planning on using P3KI Core with.
  • The number of test instances you'd like to have and whether you want them to have specific names or not.

We'll get back to you as soon as possible.

Contact form »


Whitesands Proving Ground Structure

Whitesands is a multi-user / multi-instance environment for test-driving P3KI Core. Its goal is to give you a feeling for how to interact with multiple P3KI Core identities, how delegations work, and how to verify trust between identities.

Due to the nature of the setup, certain features are difficult to demonstrate. Key among them is P3KI Core's offline capability. The full feature set including offline capability is available if you use local deployments of our RESTful service (as demonstrated here) or our native library which is also suitable for many embedded targets including ARM (iPhone, Android, Raspberry Pi, ...) and Extensa (ESP32).

Whitesands is definitely not suitable to be used in actual deployments or production environments. If you want to use P3KI Core in production, please get in touch with us.

Whitesands Frontend

Whitesands offers a simple frontend to access multiple P3KI Core instances.

It can be accessed via a RESTful API. Support for REST APIs is common and wide-spread across all modern programming languages.

P3KI Core Backend

Every instance accessible via the Whitesands frontend is a fully contained P3KI Core Node.

A P3KI Core Node is able to manage multiple identities, so strictly speaking, multiple instances are not necessary to demonstrate P3KI Core's features but we thought it a nice touch.


API Description

Whitesands Frontend

Endpoints are relative to https://whitesands.p3ki.net/api/v2.

Method Endpoint Input Output Description
GET /ping none application/json
String
"Pong"
Check availability of frontend
POST /reset none application/json
String
"Instance reset executed"
Reset the storage of all your instances. This will destroy any identities and trust kept at that instance so you can do a fresh start.
GET /instance none application/json
Array of String
["instance_id_1","instance_id_2"]
Get list of all instances available to you
GET /instance/{id} none application/json
String
"Up 2 hours"
Status of instance {id}
various /instance/{id}/trinity/{tail} various various application/json
Proxy all requests given as {tail} to the P3KI Core backend instance identified by {id}. For detailed documentation, see P3KI Core Backend documentation below. This is analogue to directly calling the REST interface of a specific instance with just "/{tail}".

P3KI Core Backend

Endpoints are relative to https://whitesands.p3ki.net/api/v2/instance/{id}/trinity.

Go to P3KI Core (TrinityD) API Documentation »


TPL Primer

More detailed documentation on TPL will be released shortly.

TPL is short for Trust Policy Language. It's a mathematically provable language to express any desired permission, role, and capability with arbitrary precision. A single P3KI Core instance can "speak" multiple TPLs, though this is usually only needed for instances that operate across multiple scenarios (like a personal identity that might be used at work and at home). The vast majority of instances will only ever speak a single language.

A given TPL can contain multiple aspects which can be interpreted as dimensions. One aspect could express operations (open, close), another might define a geo-location, identifier, object, address, value or value range, etc. The key takeaway is that at time of evaluation, all aspects of a given expression are evaluated together, never individually.

Some aspects are also (arbitrarily) sub-dividable, meaning identities can delegate with fine precision. For example if you received a delegation with access to a whole building, you can then further delegate access to individual floors or doors to others.

Whether or not something that was delegated can be further delegated by the receiver of this delegation can also be controlled in several ways. However, the version of P3KI Core available via Whitesands leaves these options open to the user and does not limit delegations by default.

If you think the TPL available via Whitesands instances does not fit your need or is too constrained, please talk to us! Our TPL concept far more powerful than what we could practically fit into a simple demo like Whitesands.


Limitations

This being an online demo instance, certain limitations apply that are not present for production deployments!

Data Storage

Whitesand instances of P3KI Core only support local storage (local to the instance, aka on whitesands.p3ki.net) and are not equipped with a shared storage backend (like a shared database or peer-to-peer network, also see Transport below). We've taken this simplification step because the nature of the storage required is somewhat scenario specific. This results in the following limitations only affecting this demo platform:

  • No automatic fetching of updated delegations of peer instances.
  • No automatic global view of trust relationships.
  • No selective queries to ensure presented trust delegation proofs contain the most up to date information possible.
  • Proofs have to be provided in full, no support for partial or empty proofs as would be possible in actual deployments.
  • No blind trust searches between arbitrary identity, since this would require a shared storage medium.

Identity Storage

Whitesands instances of P3KI core store private key material on media rated low security. This should come at no surprise, since Whitesands instances are fully managed and users should be under no illusion of what it means to let someone else handle your private key material (in short: don't & never).

For production deployments we offer a flexible interface to integrate Hardware Security Modules (HSM) and comparable solutions to handle secret key material properly. Remember: do not use Whitesands demo instances in any production scenario!

Transport

Demo instances are limited to exchanging data via TCP/IP-based HTTPS connections using the P3KI Core RESTful interface.

In reality P3KI Core is fully transport agnostic and you can use any communication means available to you including but not limited to NFC, Bluetooth, peer-to-peer networks, central databases, flat-files, store-and-forward networks, printed QR codes or similar, etc.

This makes P3KI Core especially suitable to integrate into already existing protocols or as a solid foundation for developing new protocols.

Trust Policy Language

The Trust Policy Language (TPL) supported by Whitesands instances is very limited (as outlined in the TPL Primer section above). For production deployments we'll design a scenario specific TPL that can be orders of magnitude more powerful and expressive to perfectly address your specific requirements.

Privacy

Any interaction with Whitesands-based P3KI Core instances may be logged and analyzed. If this is not acceptable to you, please get in touch with us so we can arrange a suitable demo environment for you.


Support

Simply drop us an email at support@p3ki.com and one of our engineers will get in touch with you.


Example: Frontend ping

Request
curl \
-u user:pass \
https://whitesands.p3ki.net/api/v2/ping
Response
"Pong"

Example: Enumerating Instances

While instance IDs should be fairly stable, they are not guaranteed to be permanent. If we deploy updates to the Whitesands platform, your IDs may change (though the number of instances available to you will stay the same). Remember, Whitesands is just a demo sandbox.

Request
curl \
-u user:pass \
https://whitesands.p3ki.net/api/v2/instance
Response
["i1","i2","i3"]


Example: Resetting an instance

This will destroy all identities held by an instance as well as destroy all data and delegations it keeps.

Request
curl \
-u user:pass \
-X POST -H 'Content-Type: application/json' \
https://whitesands.p3ki.net/api/v2/instance/i1/reset
Response
"Instance reset executed"

Example: Instance environment status (uptime)

This checks the uptime of a given instance's environment.

Technically, this alone does not mean the instance is actually available. To determine this, perform an instance ping.

Request
curl \
-u user:pass \
https://whitesands.p3ki.net/api/v2/instance/i1
Response
"Up 3 hours"

Example: Instance ping

This queries the actual P3KI Core instance running in the backend directly.

Request
curl \
-u user:pass \
https://whitesands.p3ki.net/api/v2/instance/i1/trinity/api/v1/ping
Response
Pong

Example: Creating identities

This will create an identity named "identity1" and upon success return this identity's public key.

Request
curl \
-u user:pass \
-X POST \
https://whitesands.p3ki.net/api/v2/instance/i1/trinity/api/v1/identity/identity1
Response
"AAAB2j...tf6KII"
Request
Response
Request
Response

Example: Delegating trust

This will delegate the policy "action:{foo.bar[baz]}" from instance i1's identity "identity1" to another identity denoted by public key AAABXurDnRtZLiv3F80vPbYeRfuwrqsHHgn-8iEqkLfORrI.

This will not yet publish the delegation. At this point this delegation is only known to "identity1"

Take note of the --header option used to set the requests content type. If you forget this, the operation will fail.

Request
curl \
--header "Content-Type: application/json" \
-X POST \
-u user:pass \
--data '{"policy":"action:{foo.bar[baz]}"}' \
https://whitesands.p3ki.net/api/v2/instance/i1/trinity/api/v1/identity/identity1/trust/AAABXu...LfORrI
Response
"Success"
Request
Response
Request
Response

Example: Exporting delegations

This will generate a signed export of all delegations issued by "identity1" of instance "i1".

Other nodes can quote this or even multiple exports like this to assemble a proof that a certain delegation chain exists.

Request
curl \
-u user:pass \
https://whitesands.p3ki.net/api/v2/instance/i1/trinity/api/v1/identity/identity1/trust/export
Response
"ZDI6aH...WVlZWU"
Request
Response
Request
Response

Example: Performing identity verification handshakes

We'll create two identities (identity1, identity2).

Then identity1 will challenge identity2 to a handshake.

The handshake outlined here will only verify identity ownership, not the existence of any trust path between the two parties

Request
curl -u user:pass \
  -X POST -H 'Content-Type: application/json' \
  https://whitesands.p3ki.net/api/v2/instance/i1/trinity/api/v1/identity/identity1
Response
"AAABul...HERPKo"
Request
curl -u user:pass \
  -X POST -H 'Content-Type: application/json' \
  https://whitesands.p3ki.net/api/v2/instance/i1/trinity/api/v1/identity/identity2
Response
"AAABqF...Ljdn9o"
Request

Here we're asking for min_policy=_, this will always succeed, effectively disabling verification of policies between the parties and only verifying identity ownership.
To verify delegations such a delegation would need to exist and be available to identity2 to form a proof for its response.
Handshake v2 (to be released soon) will allow the use of partial/complementary proofs where identity2 needs to only provide proof in the form of a delegation between a third party and itself if it knows, eg. that identity1 already trusts the third party.

curl -u user:pass \
-X POST -H 'Content-Type: application/json' \
--data '{"language":"action:tdns(atomic)", "min_policy":"_", "max_policy":"action:{foo.bar}"}' \
https://whitesands.p3ki.net/api/v2/instance/i1/trinity/api/v1/identity/identity1/handshake/challenge 
Response
"ZDE6JD...ETyqZQ"
Request

If we were to prove a certain trust policy is fulfilled between identity1 and identity2 via arbitrary third parties, we could provide this information via the certificate field.

curl -u user:pass \
-X POST -H 'Content-Type: application/json' \
--data '{"challenge":"ZDE6JD...ETyqZQ", "certificate": []}' \
https://whitesands.p3ki.net/api/v2/instance/i1/trinity/api/v1/identity/identity2/handshake/response
Response
"ZDEwOn...PKplZQ"
Request

As you can see here, whether a given challenge/response pair is valid can be verified by anyone. This operation is no longer tied to a specific identity.

curl -u user:pass \
-X POST -H 'Content-Type: application/json' \
--data '{"challenge":"ZDE6JD...ETyqZQ", "response":"ZDEwOn...PKplZQ"}' \
https://whitesands.p3ki.net/api/v2/instance/i1/trinity/api/v1/verify/handshake
Response
{"success":true,"policy":"_"}
Request
Response
Request
Response

Example: Performing identity and trust verification handshakes

We'll create three identities (identity1, identity2, identity3).

Then identity1 will delegate action:{foo.bar} to identity2 which will further delegate the same to identity3. Both will publish this fact.

identity1 will then perform an identity and trust verifying handshake with identity3 which it does not directly trust.

With the upcoming v2 handshake it will be possible to provide partial trust as proof. This would allow identity1 to not have to publish its delegation to identity2 and identity3 providing only the delegation between identity2 and itself as a proof. identity1 will then be able to combine its local knowledge (it trusting identity2) with what it was told (identity2 trust identity3) to transitively trust identity3 despite not knowing it directly.

Request
curl -u user:pass \
  -X POST -H 'Content-Type: application/json' \
  https://whitesands.p3ki.net/api/v2/instance/i1/trinity/api/v1/identity/identity1
Response
"AAABul...HERPKo"
Request
curl -u user:pass \
  -X POST -H 'Content-Type: application/json' \
  https://whitesands.p3ki.net/api/v2/instance/i1/trinity/api/v1/identity/identity2
Response
"AAABqF...Ljdn9o"
Request
curl -u user:pass \
  -X POST -H 'Content-Type: application/json' \
  https://whitesands.p3ki.net/api/v2/instance/i1/trinity/api/v1/identity/identity3
Response
"AAABwo...R-C97o"
Request

identity1 trusts identity2 with action:{foo.bar}.

curl -u user:pass \
-X POST -H 'Content-Type: application/json' \
--data '{"policy":"action:{foo.bar}"}' \
https://whitesands.p3ki.net/api/v2/instance/i1/trinity/api/v1/identity/identity1/trust/AAABqf...Ljdn9o
Response
"Success"
Request

identity2 trusts identity3 with action:{foo.bar}.

curl -u user:pass \
-X POST -H 'Content-Type: application/json' \
--data '{"policy":"action:{foo.bar}"}' \
https://whitesands.p3ki.net/api/v2/instance/i1/trinity/api/v1/identity/identity2/trust/AAABwo4J0UEkAPo-cRcQjEsOLBS8-O7-c_BfYAX2AR-C97o
Response
"Success"
Request

Exporting/publishing identity1's delegations.

curl -u user:pass \
https://whitesands.p3ki.net/api/v2/instance/i1/trinity/api/v1/identity/identity1/trust/export          
Response
"ZDI6aH...Vi-zl5...VlZWVl"
Request

Exporting/publishing identity2's delegations.

curl -u user:pass \
https://whitesands.p3ki.net/api/v2/instance/i1/trinity/api/v1/identity/identity2/trust/export
Response
"ZDI6aH...Bn7nYs...VlZWVl"
Request

identity1 issues a challenge. You can see that min_policy is set to the required policy that needs to be proven.

curl -u user:pass \
-X POST -H 'Content-Type: application/json' \
--data '{"language":"action:tdns(atomic)", "min_policy":"action:{foo.bar}"}' \
https://whitesands.p3ki.net/api/v2/instance/i1/trinity/api/v1/identity/identity1/handshake/challenge
Response
"ZDE6JD...ETyqZQ"
Request

identity3 responds, providing the two delegations published earlier to form its proof.

curl -u user:pass \
-X POST -H 'Content-Type: application/json' \
--data '{"challenge":"ZDE6JD...ETyqZQ", "certificate": ["ZDI6aH...Vi-zl5...VlZWVl", "ZDI6aH...Bn7nYs...VlZWVl"]}' \
https://whitesands.p3ki.net/api/v2/instance/i1/trinity/api/v1/identity/identity3/handshake/response
Response
"ZDEwOn...E8qmVl"
Request

The handshake was successful and established trust over action:{foo.bar} between identity1 and identity3.

curl -u user:pass \
-X POST -H 'Content-Type: application/json' \
--data '{"challenge":"ZDE6JD...ETyqZQ", "response":"ZDEwOn...E8qmVl"}' \
https://whitesands.p3ki.net/api/v2/instance/i1/trinity/api/v1/verify/handshake
Response
{"success":true,"policy":"action:{foo.bar}"}
Request
Response
Request
Response