Keyknox Service

Virgil Keyknox Service helps to safeguard cryptographic keys and secrets of your users in your software. With Vigil Keyknox your users can securely store keys as well as sync and share them between their devices.

Virgil Keyknox is designed so that only your users can have access to their keys. All keys are stored in encrypted format and only the user is able to decrypt them on their own authorized devices.

Virgil Keyknox service can be accessed by using the Virgil Keyknox SDK or Virgil Keyknox API.

Virgil Keyknox Service address:

https://api.virgilsecurity.com/keyknox/v1

All API calls require authentication with Virgil JWT. So all requests go through Virgil API Gateway which bypasses the request with preset HTTP headers: X-Application-Id, X-Virgil-Identity.

The Virgil Keyknox REST API supports the following operations for keyknox object:

Creates a new record, stores it, then returns keyknox value and meta data to the client. If a keyknox record already exists, service creates a new version of the keyknox record. It requires the keyknox/create permissions.

Request info

HTTP Request method    PUT
Request URL            https://api.virgilsecurity.com/keyknox/v1 HTTP/1.1
Headers                X-Virgil-Identity: {UserIDString}
                       X-Account-Id: {AccountID}
                       X-Application-Id: {ApplicationID}
                       Virgil-Keyknox-Previous-Hash: {KeyknoxPreviousHash}

Request

{
    "meta": "BASE64_STRING",
    "value": "BASE64_STRING"
}

Response info

HTTP/1.1 200 OK
Content-Type: application/json
Virgil-Keyknox-Hash: kcY8QLKqFu1gScis3fvKXVBtN1Yghm1L7gARqH3iafgYSU0dGxIUWZ1RITaJshiWyOEOT62FUfQzmVUafum7kA==

Response

{
	"meta": "BASE64_STRING",
	"value": "BASE64_STRING",
	"version": "1.0"
}

The get operation returns keyknox record for a current user specified in a JWT. This operation requires the keyknox/get permission.

Request info

HTTP Request method    GET
Request URL            https://api.virgilsecurity.com/keyknox/v1 HTTP/1.1
Headers                X-Virgil-Identity: {UserIDString}
                       X-Account-Id: {AccountID}
                       X-Application-Id: {ApplicationID}

Response info

HTTP/1.1 200 OK
Content-Type:         application/json
Virgil-Keyknox-Hash:  kcY8QLKqFu1gScis3fvKXVBtN1Yghm1L7gARqH3iafgYSU0dGxIUWZ1RITaJshiWyOEOT62FUfQzmVUafum7kA==

Response

{
	"meta":  "BASE64_STRING",
	"value": "BASE64_STRING",
	"version": "1.0"
}

The reset operation changes only meta data of a stored keyknox record. In order to perform this operation, the keyknox record must be already set in the Service. Note that the keyknox value itself cannot be changed. This operation requires the keyknox/reset permission.

Request info

HTTP Request method    POST
Request URL            https://api.virgilsecurity.com/keyknox/v1/reset HTTP/1.1
Headers                X-Virgil-Identity: {UserIDString}
                       X-Account-Id: {AccountID}
                       X-Application-Id: {ApplicationID}

Response info

HTTP/1.1 200 OK
Content-Type:          application/json
Virgil-Keyknox-Hash:   kcY8QLKqFu1gScis3fvKXVBtN1Yghm1L7gARqH3iafgYSU0dGxIUWZ1RITaJshiWyOEOT62FUfQzmVUafum7kA==

Response

{
    "meta":  "",
    "value": "",
    "version": "1.0"
}

• meta and value properties set to initial state - empty state.
• version property, major part increment by 1, minor reset to initial state - 0.

The Application uses standard HTTP response codes:

This status is returned in extremely rare cases of internal application errors

1. When Keyknox record created at the first time, version parameter is set to initial state: 1.0, where the major part of the version belongs to the Keyknox meta part and the minor part of the version belongs to the Keyknox value part.

2. When Keyknox record already exists and the reset action is performed, then Keyknox version updates by next rules:

• if only meta part was changed then performs increment minor part of the version by one.
• if meta + value parts were changed, then performs reset to 0 of the minor part of the version and increment by one the major part of the version.

Virgil Security provides SDKs which allow you to communicate with the Virgil Keyknox Service to upload, download, and synchronize encrypted sensitive data (private keys) between user's devices:

• Javascript SDK
• Swift
• Java (Kotlin)

For best practice take a look at our use cases which use Virgil Keyknox Service for sharing users' private keys between their devices:

• Add end-to-end encryption to your application using Virgil SDK and Firebase
• Add end-to-end encryption to your application using Virgil SDK and your custom platform
• Add end-to-end encryption to your application using Virgil SDK and Twilio