.. _create_key:

Method: Create Key
------------------

Description
~~~~~~~~~~~

This endpoint creates a new named encryption key in the specified vault.

.. _protected_key:

1. The named key is wrapped (encrypted) by the vaults key.
2. The un-wrapped (plaintext) key material of the named key is **not** obtainable by any endpoints, unless:

   a) The named key is marked as exportable (:ref:`allow_export<allow_export>`) upon creation of the key.
   b) The named key is marked as backupable (:ref:`allow_backup<allow_backup>`) upon creation of the key.
   c) The user calling the :ref:`/export<export_key>` endpoint has :ref:`Admin<bits>` permission in the vault where the named key resides.
   d) The user calling the :ref:`/backup<backup_key>` endpoint has :ref:`Admin<bits>` permission in the vault where the named key resides.

The newly created named key can be used by a user with at least :ref:`Read<bits>` permission in the vault,
to encrypt data using the :ref:`/encrypt<encrypt>` endpoint, or to decrypt data using the
:ref:`/decrypt<decrypt>` endpoint without having any access, or knowledge, about the key material.

See the :ref:`overview<explain_transparent>` on how transparent encryption in StoredSafe can help solve key distribution problems.

.. note:: Creating a key requires the :ref:`Write<bits>` permission in the affected vault.

URL Syntax
~~~~~~~~~~

/api/{version}/transparent/:vaultid/keys/:name

HTTP Method
~~~~~~~~~~~

POST

Successful HTTP Response
~~~~~~~~~~~~~~~~~~~~~~~~

201

Parameters
~~~~~~~~~~

.. _allow_backup:
.. _allow_export:
.. _allow_delete:

+----------------+------------------------------------------+----------------+---------+--------------+-----------+-------------------------------------+
| Parameter name |               Description                | Parameter type |  Type   |   Default    | Mandatory |               Comment               |
+================+==========================================+================+=========+==============+===========+=====================================+
| X-Http-Token   | StoredSafe token                         | HTTP Header    | String  |              | :sup:`1)` | Preferred method                    |
+----------------+------------------------------------------+----------------+---------+--------------+-----------+-------------------------------------+
| token          | StoredSafe token                         | JSON-encoded   | String  |              | :sup:`1)` | Legacy method                       |
+----------------+------------------------------------------+----------------+---------+--------------+-----------+-------------------------------------+
| vaultid        | Vault-ID                                 | URL-encoded    | String  |              | Yes       |                                     |
+----------------+------------------------------------------+----------------+---------+--------------+-----------+-------------------------------------+
| name           | Key name                                 | URL-encoded    | String  |              | Yes       |                                     |
+----------------+------------------------------------------+----------------+---------+--------------+-----------+-------------------------------------+
| type           | Type of key                              | JSON-encoded   | String  | aes128-gcm96 |           | See table below for supported types |
+----------------+------------------------------------------+----------------+---------+--------------+-----------+-------------------------------------+
| allow_export   | Enables key to be exported               | JSON-encoded   | Boolean | True         |           |                                     |
+----------------+------------------------------------------+----------------+---------+--------------+-----------+-------------------------------------+
| allow_backup   | Enables key to be backed up in plaintext | JSON-encoded   | Boolean | True         |           |                                     |
+----------------+------------------------------------------+----------------+---------+--------------+-----------+-------------------------------------+
| allow_delete   | Enable deletion of key                   | JSON-encoded   | Boolean | True         |           |                                     |
+----------------+------------------------------------------+----------------+---------+--------------+-----------+-------------------------------------+
| info           | Key information                          | JSON-encoded   | String  |              |           |                                     |
+----------------+------------------------------------------+----------------+---------+--------------+-----------+-------------------------------------+

.. note:: :sup:`1)` One of the methods is required.

.. _type_of_key:

+-------------------+--------------------------------------------------+------------+---------+
|       Name        |                   Description                    |    Type    | Signing |
+===================+==================================================+============+=========+
| aes128-ofb        | AES-128 in OFB mode                              | Symmetric  |         |
+-------------------+--------------------------------------------------+------------+---------+
| aes256-ofb        | AES-256 in OFB mode                              | Symmetric  |         |
+-------------------+--------------------------------------------------+------------+---------+
| aes128-gcm96      | AES-128 in GCM mode using 96 bit nonce size AEAD | Symmetric  |         |
+-------------------+--------------------------------------------------+------------+---------+
| aes256-gcm96      | AES-256 in GCM mode using 96 bit nonce size AEAD | Symmetric  |         |
+-------------------+--------------------------------------------------+------------+---------+
| chacha20-poly1305 | ChaCha20-Poly1305 AEAD                           | Symmetric  |         |
+-------------------+--------------------------------------------------+------------+---------+
| RSA-4096          | RSA-4096                                         | Asymmetric | Yes     |
+-------------------+--------------------------------------------------+------------+---------+
| ED25519           | ED25519                                          | Asymmetric | Yes     |
+-------------------+--------------------------------------------------+------------+---------+

Response Attributes
~~~~~~~~~~~~~~~~~~~

+---------------------+------------------------------------+---------+
|      Attribute      |            Description             |  Type   |
+=====================+====================================+=========+
| CALLINFO.errorcodes | Number of errors                   | Integer |
+---------------------+------------------------------------+---------+
| CALLINFO.errors     | Number of errors                   | Integer |
+---------------------+------------------------------------+---------+
| CALLINFO.general    | Information                        | Array   |
+---------------------+------------------------------------+---------+
| CALLINFO.handler    | Handler used                       | String  |
+---------------------+------------------------------------+---------+
| CALLINFO.status     | SUCCESS or FAIL                    | String  |
+---------------------+------------------------------------+---------+
| CALLINFO.token      | Rotated StoredSafe token :sup:`1)` | String  |
+---------------------+------------------------------------+---------+
| CALLINFO.version    | Key version                        | String  |
+---------------------+------------------------------------+---------+
| CALLINFO.objectid   | Object-ID                          | String  |
+---------------------+------------------------------------+---------+
| DATA                | Supplied data in prior API-call    | String  |
+---------------------+------------------------------------+---------+
| HEADERS.(headers)   | HTTP Headers                       | String  |
+---------------------+------------------------------------+---------+
| PARAMS              | Route parameters (empty)           | Array   |
+---------------------+------------------------------------+---------+
| ERRORCODES          | Error code and text :sup:`2)`      | Object  |
+---------------------+------------------------------------+---------+
| ERRORS              | Error code and text :sup:`2)`      | Array   |
+---------------------+------------------------------------+---------+

.. note:: | :sup:`1)` Token to be used in subsequent calls
   | :sup:`2`) Only present if errors

Examples
~~~~~~~~

Create a new named key (``my-new-key``) in the vault (vault-id) 179.

**Request**

::

   POST /api/1.0/transparent/179/keys/my-new-key
   x-http-token: your_storedsafe_token
   {
       "type": "aes256-gcm96",
       "info": "my new key"
   }

**Response**

::

   HTTP/2 201
   Content-type: application/json; charset=UTF-8
   {
       "CALLINFO": {
           "errorcodes": 0,
           "errors": 0,
           "general": [],
           "handler": "EncryptionHandler",
           "status": "SUCCESS",
           "token": "rotated_storedsafe_token",
           "name": "my-new-key",
           "objectid": "8743"
       },
       "DATA": {
           "name": "my-new-key",
           "vaultid": "179",
           "type": "aes256-gcm96",
           "info": "my new key",
           "token": "your_storedsafe_token",
       },
       "HEADERS": {
           "Accept": "*/*",
           "Content-Length": "169",
           "Content-Type": "application/json",
           "Host": "safe.domain.cc",
           "User-Agent": "curl/7.64.1",
           "X-Http-Token": "your_storedsafe_token"
       },
       "PARAMS": []
   }

See the :ref:`annotated example<annotated_example_encrypt>` for a full example on how to use transparent encryption.