Skip to content

Latest commit

 

History

History
124 lines (86 loc) · 4.39 KB

control_plane.md

File metadata and controls

124 lines (86 loc) · 4.39 KB

Keyhouse Control Plane

Purpose

The Keyhouse Data Plane serves administrator/operator traffic.

Endpoints

GET /info

Takes no arguments. Currently it serves as an authentication check, responding hello .

GET /keyrings

Gets information on all authorized keyrings.

Takes no arguments.

Returns a JSON body consisting of an array of Keyrings that the currently authenticated user is authorized to see.

POST /keyrings

Creates a new keyring.

Must have header content-type: application/json. Takes the following input format:

{
    "alias": String,
    "description": String,
    "level": "L2" | "L3" | "L4" // Corresponds to security level
}

For example:

{
    "alias": "test key",
    "description": "used for testing",
    "level": "L3"
}

Returns a JSON body consisting of a single created Keyring that has been sucessfully created. If the alias is already in use, a 403 Forbidden error is returned. The only authorized owner of the new keyring will be the currently authenticated user.

GET /keyrings/:keyring_alias

Gets information on a single keyring.

Takes 'keyring_alias' as a string based path argument.

Returns a JSON body consisting of a single Keyring that the currently authenticated user is authorized to see.

GET /keyrings/:keyring_alias/customer_key

Lists all Customer Key information under a keyring the user is authorized to see.

Takes 'keyring_alias' as a string based path argument.

Returns a JSON body consisting of an array of Customer Keys that the currently authenticated user is authorized to see.

POST /keyrings/:keyring_alias/customer_key

Creates a new Customer Key under a keyring that the currently authenticated user is authorized to see.

Must have header content-type: application/json.

Takes the following input format:

{
    "alias": String,
    "description": String,
    "purpose": "EncodeDecode" | "SignVerify" | "Secret",
    "acls": AccessControlLists
}

Returns a JSON body consisting of a single created Customer Key that has been successfully created. If the alias is already in use, a 403 Forbidden error is returned.

GET /keyrings/:keyring_alias/customer_key/:key_alias

Gets information on a single Customer Key.

Takes 'keyring_alias' and 'key_alias' as string based path arguments.

Returns a JSON body consisting of a single Customer Key that the currently authenticated user is authorized to see.

PATCH /keyrings/:keyring_alias/customer_key/:key_alias

Performs a partial update on a single customer key.

Takes 'keyring_alias' and 'key_alias' as string based path arguments.

Must have header content-type: application/json.

Takes the following input format:

Note here that a suffixing ? denotes an optional/nullable field, if not present, the field is not updated in the underlying customer key

{
    "description": String?,
    "acls": AccessControlLists?,
    "status": ("Enabled" | "Disabled")? // can only change from enabled -> disabled
}

Returns a JSON body consisting of a single, post-mutation, Customer Key that the currently authenticated user is authorized to see.

GET /keyrings/:keyring_alias/customer_key/:key_alias/secret

Lists all Secrets under a customer key the user is authorized to see.

Takes 'keyring_alias' and 'key_alias' as string based path arguments.

Returns a JSON body consisting of an array of Secrets contained within the given customer key.

POST /keyrings/:keyring_alias/customer_key/:key_alias/secret/:secret_alias

Creates or updates a new/existing Secret under a customer key.

Must have header content-type: application/json.

Takes the following input format:

{
    "secret": String?, // the new value the secret should have, doesn't change if not present. DOES CHANGE IF EMPTY
    "description": String?, // the new value of description, doesn't change if not present. DOES CHANGE IF EMPTY
}

Returns a JSON body consisting of the updated Secret that has been successfully created. Aliases for secrets are namespaced to their parent customer key.

DELETE /keyrings/:keyring_alias/customer_key/:key_alias/secret/:secret_alias

Deletes existing Secret under a customer key.