R-ABE Keyserver

Welcome to the R-ABE Keyserver API! This REST API wraps the attribute based encryption (ABE) schemes of the R-ABE library and can be used to set up an ABE key server. Currently, the keyserver API supports only the “BSW” scheme, as described in [1], but we plan to add support for all six schemes implemented by R-ABE.

Note that the API is still under development and must not be used in production. We rather provide it as an easy way to get started with R-ABE, without writing your own standalone program in Rust or C.

To get started with the R-ABE keyserver, refer to the example python client.

[1] John Bethencourt, Amit Sahai, and Brent Waters. Ciphertext-policy attribute-based encryption. in IEEE Symposium on Security and Privacy, pages 321–334, 2007.

Scheme Setup

An ABE scheme must be initialized before it can be used. During initialization, the key material for the keyserver is created and a session ID is issued that is required in further requests within this scheme.

Call the setup endpoint to create a new instance of a scheme and define the attribute universe. Some schemes do not require an upfront definition of the attribute universe. In this case, the attributes field must be given nevertheless, but its value will have no effect.

  • Endpoint: /setup
  • Type: POST
  • Data { "scheme": SCHEME, "attributes": [ "attribute_1", "...", "attribute_n", ], }
  • Result: session_id: a session ID that refers to the newly set up scheme

User Key/Attribute Generation

After setting up the scheme, the keyserver is in possession of master keys for the scheme, but there are no user keys yet. To create a user key, the add_user endpoint is used. Keys are typically only assigned to attributes, i.e. you will not create the keys for a user but for a set of attributes.

  • Endpoint: /add_user
  • Type: POST
  • Data
{
 "username": <username>,
 "password": <password>,
 "random_session_id": <session_id>,
 "attributes":  [
 					"attribute_1",
 					"...",
 					"attribute_n",
 				],
}
  • Result: HTTP 200 in case of success, HTTP 500 BadRequest otherwise.

Encryption

In ciphertext-policy schemes (CP-ABE), data is encrypted for a policy over attributes. How a policy looks like depends on the scheme, but in most cases it will be a boolean expression of attributes for which keys have been created in the previous phase.

To encrypt, you will need to provide the session ID, the plaintext data, and the desired policy.

  • Endpoint: /encrypt
  • Type: POST
  • Data
{
 "plaintext": <plaintext to encrypt>,
 "policy": <scheme-specific policy>,
 "session_id": <session_id>,
}

For ciphertext-policy schemes, the is a JSON structure determining the attribute access rights. For the BSW, for instance, a valid policy looks as follows:

  { "OR": [
  	{ "ATT": "attribute_1"}, 
  	{"ATT": "attribute_2"}
  	]
  }
  • Result: A not further specified JSON structure that can be treated as an opaque Blob by the client. This structure contains the encrypted ciphertext and some scheme-specific parameters. The Blob will be used for decryption. It shall not be modified, but it can be freely moved around in the public.

Decryption

In contrast to classical public key cryptography, decryption is not restricted to the owner of a single private key, but rather any private key for attributes matching the encryption policy will be able to decrypt data.

To use the decrypt endpoint, you will need to provide the session ID, the username, and the ciphertext structure. The keyserver will automatically use the attributes assigned to the user in the session and attempt to decrypt the ciphertext.

  • Endpoint: /decrypt
  • Type: POST
  • Data
{
 "ct": <Ciphertext blob, received from /encrypt endpoint>,
 "session_id":  <session_id>
}
  • Result: The plaintext as a string