Method: Create Key

Description

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

The named key is wrapped (encrypted) by the vaults key.
The un-wrapped (plaintext) key material of the named key is not obtainable by any endpoints, unless:
1. The named key is marked as exportable (allow_export) upon creation of the key.
2. The named key is marked as backupable (allow_backup) upon creation of the key.
3. The user calling the /export endpoint has Admin permission in the vault where the named key resides.
4. The user calling the /backup endpoint has Admin permission in the vault where the named key resides.

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

See the overview on how transparent encryption in StoredSafe can help solve key distribution problems.

Note

Creating a key requires the Write permission in the affected vault.

URL Syntax

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

HTTP Method

POST

Successful HTTP Response

201

Parameters

Parameter name	Description	Parameter type	Type	Default	Mandatory	Comment
X-Http-Token	StoredSafe token	HTTP Header	String		¹⁾	Preferred method
token	StoredSafe token	JSON-encoded	String		¹⁾	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

¹⁾ One of the methods is required.

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 ¹⁾	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 ²⁾	Object
ERRORS	Error code and text ²⁾	Array

Note

¹⁾ Token to be used in subsequent calls

²) 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 annotated example for a full example on how to use transparent encryption.