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.