View mode

KMS Authorizing users with access objects¶

When authentication is enabled, each KMS object requires explicit authorization from its owner to be accessed or used by others. The KMS CLI then allows to manage the access rights of users to cryptographic objects stored in the KMS.

Granting an access right¶

An owner of an object grants an access right to a specific user for a given operation on a given object. The supported KMIP operations are: get, export, encrypt, decrypt, import, revoke, destroy.

cosmianREST

➜ ckms access grant --help
Grant another user an access right to an object.

This command can only be called by the owner of the object.

The right is granted for one of the supported KMIP operations: create, get, encrypt, decrypt, import, revoke, locate, rekey, destroy

Usage: ckms access grant <USER> <OBJECT_UID> <OPERATION>

Arguments:
<USER>
         The user identifier to allow

<OBJECT_UID>
         The object unique identifier stored in the KMS

<OPERATION>
         The KMIP operation to allow

Options:
-h, --help
         Print help (see a summary with '-h')

POST to the /access/grant endpoint with the JSON object:

{
   "unique_identifier": "1ae2...25df",  // the object unique identifier
   "user_id": "[email protected]", // the user identifier to allow
   "operation_type": "get" // the KMIP operation to allow
}

The response is a JSON object:

{
"success": "a success message"
}

Revoking an access right¶

An owner of an object can revoke an access right to a specific user for a given operation on a given object at any time.

cosmianREST

➜ ckms access revoke --help
Revoke another user access right to an object.

This command can only be called by the owner of the object.

Usage: ckms access revoke <USER> <OBJECT_UID> <OPERATION>

Arguments:
<USER>
         The user to revoke access to

<OBJECT_UID>
         The object unique identifier stored in the KMS

<OPERATION>
         The operation to revoke (create, get, encrypt, decrypt, import, revoke, locate, rekey, destroy)

Options:
-h, --help
         Print help (see a summary with '-h')

POST to the /access/revoke endpoint with the JSON object:

{
   "unique_identifier": "1ae2...25df",  // the object unique identifier
   "user_id": "[email protected]", // the user identifier to allow
   "operation_type": "get" // the KMIP operation to allow
}

The response is a JSON object:

{
"success": "a success message"
}

Listing an object access rights¶

The owner of an object can list all the access rights that have been granted to another object.

cosmianREST

➜ ckms access list --help
List the access rights granted on an object to other users.

This command can only be called by the owner of the object. Returns a list of users and the operations they have been granted access to.

Usage: ckms access list <OBJECT_UID>

Arguments:
<OBJECT_UID>
         The object unique identifier

Options:
-h, --help
         Print help (see a summary with '-h')

GET to the /access/list/{object_unique_id} endpoint:

The response is a JSON array:

[
   {
      "user_id": "the user identifier the access rights are granted to",
      "operations": [ <operation type> ]
   }
]

where <operation type> is one of the following: export, get, encrypt, decrypt, import, revoke, destroy.

Listing the objects owned by a user¶

A user can list all the objects it owns (i.e. the objects it created using either the Create, CreateKeyPair, or Import KMIP operations).

cosmianREST

➜ ckms access owned --help
List the objects owned by the calling user.

Owners of objects can perform any operation on these objects and can grant access rights on any of these operations to any other user.

Usage: ckms access owned

Options:
-h, --help
         Print help (see a summary with '-h')

GET to the /access/owned endpoint:

The response is a JSON array:

[
   {
      "object_id": "the object unique identifier",
      "state": "<state>",
      "attributes": "<attributes>",
      "is_wrapped": "<wrapped_state>"
   }
]

where:

<state> is one of the following KMIP states: PreActive, Active, Deactivated, Compromised, Destroyed_Compromised,
<attributes> is the KMIP Attributes structure (see the KMIP documentation)
<wrapped_state>: is a boolean indicating whether the object is wrapped or not (see key wrapping).

Listing the access rights obtained by a user¶

A user can list all the access rights that have been granted to it by object owners.

cosmianREST

➜ ckms access obtained --help
List the access rights obtained by the calling user

Returns a list of objects, their state, their owner and the accesses rights granted on the object

Usage: ckms access obtained

Options:
-h, --help
      Print help (see a summary with '-h')

GET to the /access/obtained endpoint:

The response is a JSON array:

[
      {
      "object_id": "the object unique identifier",
      "owner_id": "the user identifier of the owner of the object",
      "state": "<state>",
      "operations": [ <operation type> ]
      "attributes": "<attributes>",
      "is_wrapped": "<wrapped_state>"
      }
]

where:

<state> is one of the following KMIP states: PreActive, Active, Deactivated, Compromised, Destroyed_Compromised,
<operation type> is one of the following: export, get, encrypt, decrypt, import, revoke, destroy,
<wrapped_state>: is a boolean indicating whether the object is wrapped or not (see key wrapping).