1. Overview

The Crypto Keys API allows you to import, create and work with symmetric and asymmetric keys and certificates to sign/verify digest values, encrypt/decrypt input, or hash and sign input values. The benefit is that you don’t have to store secret keys in your application.
The API has an integration with Azure KeyVault, allowing you to store keys, secrets and certificates in FIPS 140-2 Level 2 validated Hardware Security Modules (HSM). The key will never leave the HSM, making it really secure, especially if you combine it with IP whitelisting

Interactive testing: A web based test console is available in the <a href="https://store.sphereon.com">Sphereon API Store</a>

1.1. Version information

Version : 0.9

1.2. Contact information

Contact : Sphereon DevOps Team
Contact Email : dev@sphereon.com

1.3. License information

License : Apache License Version 2.0
License URL : http://www.apache.org/licenses/LICENSE-2.0
Terms of service : https://sphereon.com

1.4. URI scheme

Host : gw.api.cloud.sphereon.com
BasePath : /crypto/keys/0.9
Schemes : HTTPS

1.5. Tags

  • Cert : Certificate Management APIs

  • Config : Configuration APIs

  • Content : Content APIs

  • Key : Key Management APIs

2. Introduction

The Crypto Keys API helps to safely store cryptographic keys and secrets used by applications and services.
You can encrypt keys and secrets (eg. account keys, authentication keys, encryption keys, .PFX files, and passwords) using keys optionally protected by Hardware Security Modules (HSMs).
Currently the API can store high value keys/secrets in Microsoft Azure HSMs that are FIPS 140-2 Level 2 validated (hardware and firmware).

It allows you to maintain control of keys that access and encrypt your data outside of your application.
You can block access to the API based on IP whitelisting for instance. This means your application has no access to keys directly and when placed in a HSM nobody has access to the key. Combined with IP based protection this means your’s encryption/signing needs are really secure.

2.1. Keys, Secret and Certificates

This API enables you to store and use cryptographic keys. Multiple key types and algorithms are supported.
Besides this, it allows you to remotely and securely store secrets. Certificates are built on top of keys and secrets. It is the combination of public and private keys with a secret.

2.1.1. Secret

A secret is a

2.1.2. Keys

Keys conform to JSON Web Keys (JWK).

Currently we support RSA keys only. We plan on supporting other key types (symmetric and elliptic curve).

  • RSA: A 2048-bit RSA key. When no HSM is choosen this is a "soft" key, which is processed in software but it is stored encrypted using a system key that is in an HSM. When HSM is choosen the key is stored in the HSM and will never leave if to perform operations. You can import an existing RSA key yourself or generate one.

RSA algorithms

The following algorithm identifiers are supported with RSA keys in Azure Key Vault.

Sign, Verify and Hash content operations

  • RS256 - RSASSA-PKCS-v1_5 using SHA-256. The supplied digest must be a valid 32 bytes SHA-256 hash

  • RS384 - RSASSA-PKCS-v1_5 using SHA-384. The supplied digest must be a valid 48 bytes SHA-384 hash

  • RS512 - RSASSA-PKCS-v1_5 using SHA-512. The supplied digest must be a valid 64 bytes SHA-512 hash

Encrypt and Decrypt content operations

  • RSA1_5 - * DEPRECATED * RSAES-PKCS1-V1_5 [RFC3447] key encryption

  • RSA-OAEP - * DEPRECATED * RSAES using Optimal Asymmetric Encryption Padding (OAEP) [RFC3447], with the default parameters specified by RFC 3447 in Section A.2.1 meaning a a hash function using SHA-1 and a mask generation function using MGF1 with SHA-1.

  • RSA-OAEP-256 - RSAES using Optimal Asymmetric Encryption Padding (OAEP) [RFC3447], with the default parameters specified by RFC 3447 in Section A.2.1, meaning a hash function using SHA-256 and a mask generation function using MGF1 with SHA-256.

The following cryptographic operations may be performed using a key:

  • Sign and Verify hash - You should hash the data to be signed locally and then request that we sign the hash. Verification of signed hashes is supported, but we recommend for best performance that you, verify locally, unless you don’t have access to the public key from your application.

  • Key Wrapping - A key stored in the API may be used to protect another key, typically a symmetric content encryption key (CEK). When the key is asymmetric, key encryption is used, for example RSA-OAEP-256 and the WRAPKEY/UNWRAPKEY operations are in this case equivalent to ENCRYPT/DECRYPT. When the key is however symmetric, key wrapping is used; for example AES-KW. It is recommended that you perform WRAPKEY operations locally.

  • Encrypt and Decrypt - Encrypt or decrypt a single block of data, the size of which is determined by the key type and encryption algorithm. For best performance it is recommended that you encrypt data locally, unless you don’t have access to the public key from your application.

The Wrapkey and Unwrapkey operations using asymmetric keys may seem superfluous since it is equivalent to Ecrypt and Decrypt, the use of distinct operations is considered important to provide semantic separation and consistency of these operations when other key types are supported by the service (for instance symmetric keys).

We do not support any Export operations. Meaning once a key is provisioned in the system it cannot be extracted or its key material modified

You can restrict cryptographic operations supported on a per-key basis using the key_ops property of the JWK object. Meaning it is possible to restrict a key only to sign/verify (default) or encrypt/decrypt for instance.

2.2. Integration with other API’s

This API can be used with our Storage API to hash or encrypt/decrypt files directly. Furthermore the Easy Blockchain and Blockchain Proof API’s are related to this API. The Blockchain Proof API has direct integration to sign document hashes. This API can be used with the Easy Blockchain API to sign entries in the blockchain.
== SDKs

Our API’s are based on the OpenAPI specification (formerly known as Swagger specification). This means you can pickup our REST API definition file and generate classes for your favorite programming language.

2.3. Provided SDKs and generated SDKs

2.3.1. Provided SDKs

For some popular programming languages we provide you with an SDK implementation.
This implementation can be found at https://github.com/Sphereon-SDK/crypto-keys-sdk

2.3.2. Generate your own SDK

Please feel free to generate an SDK for your own programming language using our Swagger file. Please note that we do not officially support your SDK, but unofficially we are here to help of course.
You can use Swagger codegen for this (https://swagger.io/swagger-codegen). Swagger codegen support almost 100 programming languages.

Please use version 2.X of swagger codegen with our current API’s

2.4. Version compatibility between SDK and API

Al of our REST API’s follow the versioning scheme below

XX.YY

When the major number (XX) changes this means we completely redesign an API.
Minor number (YY) changes means smaller backwards comptible breaks within the API. An API can be changed forward compatible within the same minor number.

Our SDK follow the below versioning scheme

XX.YY.ZZ

The major (XX) and minor (YY) number always map directly to the accompanying REST API version.
The micro number (ZZ) is used if we add forward compatible changes to our REST API, or when bugs are encountered in a specific SDK.

3. Privacy and file storage

This micro service uses the Sphereon Storage API to store or retrieve files.
Both input- and output files can be stored or retrieved using our Storage API.
Our Storage API provides integration with Amazon S3 ®, Google Cloud Storage ®, Xillio Engine or our Sphereon Storage.
Therefore you have the flexibility to store your files at a place you want.
More information about the Storage API: https://docs.sphereon.com/api/storage/0.8/html

4. Resources

4.1. Cert

Certificate Management APIs

4.1.1. List certificates metadata information

GET /{config}/certs
Description

Gets a list of all certiciate metadata

Parameters
Type Name Description Schema

Path

config
required

config

string

Responses
HTTP Code Description Schema

200

Certificate metadata retrieved.

CertificateMetadataListResponse

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
GET /crypto/keys/0.9/example-config/certs HTTP/1.1
Authorization: Bearer c11b88cc-280d-303f-a864-bd0af62db0bb
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 2146

{
  "certificateMetadata" : {
    "example-config/certs/test/latest" : {
      "attributes" : {
        "creationTime" : "2018-03-07T23:54:31Z",
        "expirationTime" : "2019-03-07T23:54:30Z",
        "notBeforeTime" : "2018-03-07T23:44:30Z",
        "updatedTime" : "2018-03-07T23:54:31Z",
        "enabled" : true
      },
      "applicationMetadata" : { },
      "cid" : "example-config/certs/test/latest",
      "url" : "https://gw.api.cloud.sphereon.com/crypto/keys/0.9/example-config/certs/test/latest",
      "x509Thumbprint" : "WwMvLWAw8z76Z54lyr/sZ6xIz0Q=",
      "backendMetadata" : {
        "azure:id" : "https://sphereontestkv.vault.azure.net/certificates/test"
      }
    },
    "example-config/certs/testall/latest" : {
      "attributes" : {
        "creationTime" : "2018-03-08T22:08:25Z",
        "expirationTime" : "2019-03-08T22:08:20Z",
        "notBeforeTime" : "2018-03-08T21:58:20Z",
        "updatedTime" : "2018-03-08T22:45:42Z",
        "enabled" : true
      },
      "applicationMetadata" : {
        "sphereon" : "test"
      },
      "cid" : "example-config/certs/testall/latest",
      "url" : "https://gw.api.cloud.sphereon.com/crypto/keys/0.9/example-config/certs/testall/latest",
      "x509Thumbprint" : "4j46wjwAeLkzeGG/PCwhE552sBM=",
      "backendMetadata" : {
        "azure:id" : "https://sphereontestkv.vault.azure.net/certificates/testall"
      }
    },
    "example-config/certs/testimport/latest" : {
      "attributes" : {
        "creationTime" : "2018-08-09T01:10:14Z",
        "expirationTime" : "2021-11-04T00:00:00Z",
        "notBeforeTime" : "2016-11-04T22:24:45Z",
        "updatedTime" : "2018-08-09T01:10:14Z",
        "enabled" : true
      },
      "applicationMetadata" : { },
      "cid" : "example-config/certs/testimport/latest",
      "url" : "https://gw.api.cloud.sphereon.com/crypto/keys/0.9/example-config/certs/testimport/latest",
      "x509Thumbprint" : "/g17sM85nRmfjkZc81he2Ys9mJk=",
      "backendMetadata" : {
        "azure:id" : "https://sphereontestkv.vault.azure.net/certificates/testimport"
      }
    }
  }
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/crypto/keys/0.9/example-config/certs' -i -H 'Authorization: Bearer c11b88cc-280d-303f-a864-bd0af62db0bb'

4.1.2. Create certificate

POST /{config}/certs/create
Description

Creates a new certificate.

Parameters
Type Name Description Schema

Path

config
required

config

string

Body

certificateRequest
required

The create certificate request

CreateCertificateRequest

Responses
HTTP Code Description Schema

201

Created

CreateCertificateResponse

202

Certificate creation started

CreateCertificateResponse

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

4.1.3. Import certificate

POST /{config}/certs/import
Description

Imports an existing valid certificate, containing a private key, into Azure Key Vault. The certificate to be imported can be in either PFX or PEM format. If the certificate is in PEM format the PEM file must contain the key as well as x509 certificates.

Parameters
Type Name Description Schema

Path

config
required

config

string

Body

request
required

The import certificate request

ImportCertificateRequest

Responses
HTTP Code Description Schema

200

Imported certificate successfully.

CreateCertificateResponse

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

4.1.4. Delete certificate

DELETE /{config}/certs/{name}
Description

Deletes a certificate

Parameters
Type Name Description Schema

Path

config
required

config

string

Path

name
required

name

string

Responses
HTTP Code Description Schema

200

Certificate deletion requested

DeletedCertificateBundleResponse

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

4.1.5. Get certificate info

GET /{config}/certs/{name}/{version}
Description

Gets information about a certificate

Parameters
Type Name Description Schema

Path

config
required

config

string

Path

name
required

name

string

Path

version
required

version

string

Responses
HTTP Code Description Schema

200

Certificate information retrieved.

CertificateBundleResponse

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
GET /crypto/keys/0.9/example-config/certs/testimport/latest HTTP/1.1
Authorization: Bearer c11b88cc-280d-303f-a864-bd0af62db0bb
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 3205

{
  "name" : "testimport",
  "version" : "462925f49be04c13a931f6e22bd09907",
  "certificateBundle" : {
    "attributes" : {
      "creationTime" : "2018-08-09T01:10:14Z",
      "expirationTime" : "2021-11-04T00:00:00Z",
      "notBeforeTime" : "2016-11-04T22:24:45Z",
      "updatedTime" : "2018-08-09T01:10:14Z",
      "enabled" : true
    },
    "applicationMetadata" : { },
    "cid" : "example-config/certs/testimport/462925f49be04c13a931f6e22bd09907",
    "url" : "https://gw.api.cloud.sphereon.com/crypto/keys/0.9/example-config/certs/testimport/462925f49be04c13a931f6e22bd09907",
    "x509Thumbprint" : "/g17sM85nRmfjkZc81he2Ys9mJk=",
    "backendMetadata" : {
      "azure:id" : "https://sphereontestkv.vault.azure.net/certificates/testimport/462925f49be04c13a931f6e22bd09907",
      "azure:kid" : "https://sphereontestkv.vault.azure.net/keys/testimport/462925f49be04c13a931f6e22bd09907",
      "azure:sid" : "https://sphereontestkv.vault.azure.net/secrets/testimport/462925f49be04c13a931f6e22bd09907"
    },
    "cer" : "MIIC1jCCAb6gAwIBAgIQPYQVEWOQ7aVN6/skCp9zoTANBgkqhkiG9w0BAQsFADAUMRIwEAYDVQQDEwlsb2NhbGhvc3QwHhcNMTYxMTA0MjIyNDQ1WhcNMjExMTA0MDAwMDAwWjAUMRIwEAYDVQQDEwlsb2NhbGhvc3QwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCwclpLkUiPalZ4gHQdQ3uIO0czSZOfipIeoXmHU36Upuu9q+8Z7spjeSrmB+8gcQjac2K3O0kpDZeGCKFhDVqcNaGdPaR2WTsO3yAqpZGd8DGlP7L/UjVGt8pu3ZBEPmcDBFlXumradZbSvvYEXJeE3416yxsrO02975HzvweQIzQuB0vTch32a497tptDYuu8+oDfBXg2IWEuhBvY5TSfbBWzaVTXTM0J5ZSzEbviPeU0S1ZVwpiyJeAOxjESzo1lJLE6P97gE28OyPiLaKbCvhi6bzsVniJ3FOugub/6nRQIIx8w/WRY9V5BZDEMofXhMnGuRyVuLzBH1+1PtIqVAgMBAAGjJDAiMAsGA1UdDwQEAwIEsDATBgNVHSUEDDAKBggrBgEFBQcDATANBgkqhkiG9w0BAQsFAAOCAQEAk9l+4O/tmR63z9WCbftBzJfTk42CfYwRGk5uDamaM7Zioe2d6wBNrbvmABdOXE8S6H0eJvWtOoxYrmZJKx3pXN3dA+rtZzX2UdKG7LW2zZsSy3ekFVtHYp0qq4hSAhqeYr71A5DFdIZ34aiBr7rlmjlUlyWYyKGf0ZAaP36qvyglcgAYW56EyTfLvEce7wlh0pox1rO332Zvdvk9zL5TLa3FbkXlgXzL8QxLDMZC335wCMLtMxYbWrdVRGtDtCJyDjrw8rvyewQN0D+msO1Hppu6aqKWkz+8OzSkFIkyhJXdsMAqfSktjYEsSQEFNJzL8fbKxUq2BA9t1RFn7DTMtQ==",
    "kid" : "example-config/keys/testimport/462925f49be04c13a931f6e22bd09907",
    "sid" : "example-config/secrets/testimport/462925f49be04c13a931f6e22bd09907",
    "policy" : {
      "id" : "https://sphereontestkv.vault.azure.net/certificates/testimport/policy",
      "attributes" : {
        "creationTime" : "2018-08-09T01:10:14Z",
        "updatedTime" : "2018-08-09T01:10:14Z",
        "enabled" : true
      },
      "issuer" : {
        "name" : "Unknown"
      },
      "keyProperties" : {
        "exportable" : true,
        "keySize" : 2048,
        "kty" : "RSA",
        "reuseOnRenewal" : false
      },
      "secretProperties" : {
        "mediaType" : "application/x-pkcs12"
      },
      "x509Properties" : {
        "enhancedKeyUsage" : [ "1.3.6.1.5.5.7.3.1" ],
        "keyUsage" : [ "DATA_ENCIPHERMENT", "DIGITAL_SIGNATURE", "KEY_ENCIPHERMENT" ],
        "subject" : "CN=localhost",
        "validityMonths" : 60
      },
      "lifetimeActions" : [ {
        "action" : {
          "actionType" : "EMAIL_CONTACTS"
        },
        "trigger" : {
          "lifetimePercentage" : 80
        }
      } ]
    }
  }
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/crypto/keys/0.9/example-config/certs/testimport/latest' -i -H 'Authorization: Bearer c11b88cc-280d-303f-a864-bd0af62db0bb'

4.2. Config

Configuration APIs

4.2.1. Create a new Configuration

POST /manage/configs
Description

Create a new crypto key configuration

Parameters
Type Name Description Schema

Body

request
required

The configuration request

Create configuration request

Responses
HTTP Code Description Schema

200

Configuration created

ConfigurationResponse

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
POST /crypto/keys/0.9/manage/configs HTTP/1.1
Content-Type: application/json
Authorization: Bearer c11b88cc-280d-303f-a864-bd0af62db0bb
Host: gw.api.cloud.sphereon.com
Content-Length: 583

{
  "configuration" : {
    "name" : "example-config",
    "azureKeyVaultSettings" : {
      "tenant" : "example.com",
      "clientId" : "52aa3be5-c25f-280a-22ac-2210ac3a666a",
      "clientSecret" : "a7qaG3jA0q47srzVK9SaL7i11y6GdI6570ka14CAa2a=",
      "resourceGroup" : "example-azure-resource-group-name",
      "keyVaultName" : "example-keyvault-name",
      "keyVaultURL" : "https://example-keyvault-name.vault.azure.net/",
      "environment" : "AZURE",
      "region" : "EUROPE_WEST",
      "subscriptionId" : "a52165ad-ba8a-38a0-5e70-5fe57204264b"
    }
  }
}
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 635

{
  "configuration" : {
    "name" : "example-config",
    "id" : "18f25b01-dedf-4fdf-9d3e-35bef8f32fa7",
    "azureKeyVaultSettings" : {
      "tenant" : "example.com",
      "clientId" : "52aa3be5-c25f-280a-22ac-2210ac3a666a",
      "clientSecret" : "a7qaG3jA0q47srzVK9SaL7i11y6GdI6570ka14CAa2a=",
      "resourceGroup" : "example-azure-resource-group-name",
      "keyVaultName" : "example-keyvault-name",
      "keyVaultURL" : "https://example-keyvault-name.vault.azure.net/",
      "environment" : "AZURE",
      "region" : "EUROPE_WEST",
      "subscriptionId" : "a52165ad-ba8a-38a0-5e70-5fe57204264b"
    }
  }
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/crypto/keys/0.9/manage/configs' -i -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer c11b88cc-280d-303f-a864-bd0af62db0bb' -d '{
  "configuration" : {
    "name" : "example-config",
    "azureKeyVaultSettings" : {
      "tenant" : "example.com",
      "clientId" : "52aa3be5-c25f-280a-22ac-2210ac3a666a",
      "clientSecret" : "a7qaG3jA0q47srzVK9SaL7i11y6GdI6570ka14CAa2a=",
      "resourceGroup" : "example-azure-resource-group-name",
      "keyVaultName" : "example-keyvault-name",
      "keyVaultURL" : "https://example-keyvault-name.vault.azure.net/",
      "environment" : "AZURE",
      "region" : "EUROPE_WEST",
      "subscriptionId" : "a52165ad-ba8a-38a0-5e70-5fe57204264b"
    }
  }
}'

4.2.2. Get Configuration

GET /manage/configs/{config}
Description

Get existing configuration

Parameters
Type Name Description Schema

Path

config
required

config name

string

Responses
HTTP Code Description Schema

200

Configuration

ConfigurationResponse

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
GET /crypto/keys/0.9/manage/configs/example-config HTTP/1.1
Content-Type: application/json
Authorization: Bearer c11b88cc-280d-303f-a864-bd0af62db0bb
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 635

{
  "configuration" : {
    "name" : "example-config",
    "id" : "18f25b01-dedf-4fdf-9d3e-35bef8f32fa7",
    "azureKeyVaultSettings" : {
      "tenant" : "example.com",
      "clientId" : "52aa3be5-c25f-280a-22ac-2210ac3a666a",
      "clientSecret" : "a7qaG3jA0q47srzVK9SaL7i11y6GdI6570ka14CAa2a=",
      "resourceGroup" : "example-azure-resource-group-name",
      "keyVaultName" : "example-keyvault-name",
      "keyVaultURL" : "https://example-keyvault-name.vault.azure.net/",
      "environment" : "AZURE",
      "region" : "EUROPE_WEST",
      "subscriptionId" : "a52165ad-ba8a-38a0-5e70-5fe57204264b"
    }
  }
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/crypto/keys/0.9/manage/configs/example-config' -i -H 'Content-Type: application/json' -H 'Authorization: Bearer c11b88cc-280d-303f-a864-bd0af62db0bb'

4.2.3. Update Configuration

PUT /manage/configs/{config}
Description

Update an existing configuration

Parameters
Type Name Description Schema

Path

config
required

config

string

Body

request
required

The updated configuration request

UpdateConfigurationRequest

Responses
HTTP Code Description Schema

200

Configuration updated

ConfigurationResponse

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
PUT /crypto/keys/0.9/manage/configs/18f25b01-dedf-4fdf-9d3e-35bef8f32fa7 HTTP/1.1
Content-Type: application/json
Authorization: Bearer c11b88cc-280d-303f-a864-bd0af62db0bb
Host: gw.api.cloud.sphereon.com
Content-Length: 591

{
  "configuration" : {
    "name" : "updated-example-config",
    "azureKeyVaultSettings" : {
      "tenant" : "example.com",
      "clientId" : "52aa3be5-c25f-280a-22ac-2210ac3a666a",
      "clientSecret" : "a7qaG3jA0q47srzVK9SaL7i11y6GdI6570ka14CAa2a=",
      "resourceGroup" : "example-azure-resource-group-name",
      "keyVaultName" : "example-keyvault-name",
      "keyVaultURL" : "https://example-keyvault-name.vault.azure.net/",
      "environment" : "AZURE",
      "region" : "EUROPE_WEST",
      "subscriptionId" : "a52165ad-ba8a-38a0-5e70-5fe57204264b"
    }
  }
}
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 643

{
  "configuration" : {
    "name" : "updated-example-config",
    "id" : "18f25b01-dedf-4fdf-9d3e-35bef8f32fa7",
    "azureKeyVaultSettings" : {
      "tenant" : "example.com",
      "clientId" : "52aa3be5-c25f-280a-22ac-2210ac3a666a",
      "clientSecret" : "a7qaG3jA0q47srzVK9SaL7i11y6GdI6570ka14CAa2a=",
      "resourceGroup" : "example-azure-resource-group-name",
      "keyVaultName" : "example-keyvault-name",
      "keyVaultURL" : "https://example-keyvault-name.vault.azure.net/",
      "environment" : "AZURE",
      "region" : "EUROPE_WEST",
      "subscriptionId" : "a52165ad-ba8a-38a0-5e70-5fe57204264b"
    }
  }
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/crypto/keys/0.9/manage/configs/18f25b01-dedf-4fdf-9d3e-35bef8f32fa7' -i -X PUT -H 'Content-Type: application/json' -H 'Authorization: Bearer c11b88cc-280d-303f-a864-bd0af62db0bb' -d '{
  "configuration" : {
    "name" : "updated-example-config",
    "azureKeyVaultSettings" : {
      "tenant" : "example.com",
      "clientId" : "52aa3be5-c25f-280a-22ac-2210ac3a666a",
      "clientSecret" : "a7qaG3jA0q47srzVK9SaL7i11y6GdI6570ka14CAa2a=",
      "resourceGroup" : "example-azure-resource-group-name",
      "keyVaultName" : "example-keyvault-name",
      "keyVaultURL" : "https://example-keyvault-name.vault.azure.net/",
      "environment" : "AZURE",
      "region" : "EUROPE_WEST",
      "subscriptionId" : "a52165ad-ba8a-38a0-5e70-5fe57204264b"
    }
  }
}'

4.2.4. Delete Configuration

DELETE /manage/configs/{config}
Description

Delete an existing configuration. As a protection this can only be done using the configuration Id and this not the name

Parameters
Type Name Description Schema

Path

config
required

config id

string

Responses
HTTP Code Description Schema

200

Configuration deleted

ConfigurationResponse

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
DELETE /crypto/keys/0.9/manage/configs/18f25b01-dedf-4fdf-9d3e-35bef8f32fa7 HTTP/1.1
Content-Type: application/json
Authorization: Bearer c11b88cc-280d-303f-a864-bd0af62db0bb
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 643

{
  "configuration" : {
    "name" : "updated-example-config",
    "id" : "18f25b01-dedf-4fdf-9d3e-35bef8f32fa7",
    "azureKeyVaultSettings" : {
      "tenant" : "example.com",
      "clientId" : "52aa3be5-c25f-280a-22ac-2210ac3a666a",
      "clientSecret" : "a7qaG3jA0q47srzVK9SaL7i11y6GdI6570ka14CAa2a=",
      "resourceGroup" : "example-azure-resource-group-name",
      "keyVaultName" : "example-keyvault-name",
      "keyVaultURL" : "https://example-keyvault-name.vault.azure.net/",
      "environment" : "AZURE",
      "region" : "EUROPE_WEST",
      "subscriptionId" : "a52165ad-ba8a-38a0-5e70-5fe57204264b"
    }
  }
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/crypto/keys/0.9/manage/configs/18f25b01-dedf-4fdf-9d3e-35bef8f32fa7' -i -X DELETE -H 'Content-Type: application/json' -H 'Authorization: Bearer c11b88cc-280d-303f-a864-bd0af62db0bb'

4.3. Content

Content APIs

4.3.1. Decrypt value

POST /{config}/keys/{name}/{version}/decrypt
Description

Decrypts a well-formed block of ciphertext using the target encryption key and specified algorithm. This operation is the reverse of the encrypt operation. This operation applies to asymmetric and symmetric keys since it uses the private portion of the key.

Parameters
Type Name Description Schema

Path

config
required

config

string

Path

name
required

name

string

Path

version
required

version

string

Body

request
required

The decrypt request

KeyDecryptRequest

Responses
HTTP Code Description Schema

200

Input decrypted

KeyDecryptResponse

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
POST /crypto/keys/0.9/example-config/keys/testimport/462925f49be04c13a931f6e22bd09907/decrypt HTTP/1.1
Content-Type: application/json
Authorization: Bearer c11b88cc-280d-303f-a864-bd0af62db0bb
Host: gw.api.cloud.sphereon.com
Content-Length: 391

{
  "alg" : "RSA_OAEP",
  "encrypted" : "MHeF+ua5lcxbeWckQkUjq5jqdHnOqngIMTyX3EvessGwfdhFY4KY2FvX6Jo2XhCj/z2pQf5lLYNSEMZjrHS3H0Lo8BYbmG/iif8F8IQlXPEB5XO5ig6XiVNLsNdeSyQUqTSBmxz4qVeDMWa+pqmeHCYQaWrfNj9+ByJh0NXPwRhTyxD49lWgxTetUtAz8fiJa9uAsZ6YfdbDLvxO9chdG1XhWV2OHYlsOMyj2wtIEWSvxGW3n3YBhpUnwIQ6YHPz7RHkV5FumLPZSAov94WEGVb5/qqtMJ9j+KCK8GS4g+qui+Xz2UOMtPsBLjmjqC0Jp2aJef090rlQQKVbmpfOfw=="
}
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 154

{
  "kid" : "example-config/keys/testimport/462925f49be04c13a931f6e22bd09907",
  "decrypted" : "RXhhbXBsZSBkb2N1bWVudGF0aW9uIHVuZW5jcnlwdGVkIHRleHQ="
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/crypto/keys/0.9/example-config/keys/testimport/462925f49be04c13a931f6e22bd09907/decrypt' -i -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer c11b88cc-280d-303f-a864-bd0af62db0bb' -d '{
  "alg" : "RSA_OAEP",
  "encrypted" : "MHeF+ua5lcxbeWckQkUjq5jqdHnOqngIMTyX3EvessGwfdhFY4KY2FvX6Jo2XhCj/z2pQf5lLYNSEMZjrHS3H0Lo8BYbmG/iif8F8IQlXPEB5XO5ig6XiVNLsNdeSyQUqTSBmxz4qVeDMWa+pqmeHCYQaWrfNj9+ByJh0NXPwRhTyxD49lWgxTetUtAz8fiJa9uAsZ6YfdbDLvxO9chdG1XhWV2OHYlsOMyj2wtIEWSvxGW3n3YBhpUnwIQ6YHPz7RHkV5FumLPZSAov94WEGVb5/qqtMJ9j+KCK8GS4g+qui+Xz2UOMtPsBLjmjqC0Jp2aJef090rlQQKVbmpfOfw=="
}'

4.3.2. Encrypt value

POST /{config}/keys/{name}/{version}/encrypt
Description

Encrypts a sequence of bytes using an encryption key. This operation is only strictly necessary for symmetric keys since encryption with an asymmetric key can be performed using the public portion of the key. This operation is supported for asymmetric keys as a convenience for callers that have a key-reference but do not have access to the public key material.

Parameters
Type Name Description Schema

Path

config
required

config

string

Path

name
required

name

string

Path

version
required

version

string

Body

request
required

The encrypt request

KeyEncryptRequest

Responses
HTTP Code Description Schema

200

Input encrypted

KeyEncryptResponse

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
POST /crypto/keys/0.9/example-config/keys/testimport/462925f49be04c13a931f6e22bd09907/encrypt HTTP/1.1
Content-Type: application/json
Authorization: Bearer c11b88cc-280d-303f-a864-bd0af62db0bb
Host: gw.api.cloud.sphereon.com
Content-Length: 95

{
  "alg" : "RSA_OAEP",
  "input" : "RXhhbXBsZSBkb2N1bWVudGF0aW9uIHVuZW5jcnlwdGVkIHRleHQ="
}
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 446

{
  "kid" : "example-config/keys/testimport/462925f49be04c13a931f6e22bd09907",
  "encrypted" : "MHeF+ua5lcxbeWckQkUjq5jqdHnOqngIMTyX3EvessGwfdhFY4KY2FvX6Jo2XhCj/z2pQf5lLYNSEMZjrHS3H0Lo8BYbmG/iif8F8IQlXPEB5XO5ig6XiVNLsNdeSyQUqTSBmxz4qVeDMWa+pqmeHCYQaWrfNj9+ByJh0NXPwRhTyxD49lWgxTetUtAz8fiJa9uAsZ6YfdbDLvxO9chdG1XhWV2OHYlsOMyj2wtIEWSvxGW3n3YBhpUnwIQ6YHPz7RHkV5FumLPZSAov94WEGVb5/qqtMJ9j+KCK8GS4g+qui+Xz2UOMtPsBLjmjqC0Jp2aJef090rlQQKVbmpfOfw=="
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/crypto/keys/0.9/example-config/keys/testimport/462925f49be04c13a931f6e22bd09907/encrypt' -i -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer c11b88cc-280d-303f-a864-bd0af62db0bb' -d '{
  "alg" : "RSA_OAEP",
  "input" : "RXhhbXBsZSBkb2N1bWVudGF0aW9uIHVuZW5jcnlwdGVkIHRleHQ="
}'

4.3.3. Create signature

POST /{config}/keys/{name}/{version}/sign
Description

Creates a signature from a digest using a key. This operation is applicable to asymmetric and symmetric keys, since this operation uses the private portion of the key. Please note that the input needs to be a hash using a hash algorithm that fits the JsonWebKeySignatureAlgorithm, meaning SHA-256, SHA-384 or SHA-512

Parameters
Type Name Description Schema

Path

config
required

config

string

Path

name
required

name

string

Path

version
required

version

string

Body

request
required

The sign request

KeySignRequest

Responses
HTTP Code Description Schema

200

Digest signed

KeySignResponse

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
POST /crypto/keys/0.9/example-config/keys/testimport/462925f49be04c13a931f6e22bd09907/sign HTTP/1.1
Content-Type: application/json
Authorization: Bearer c11b88cc-280d-303f-a864-bd0af62db0bb
Host: gw.api.cloud.sphereon.com
Content-Length: 85

{
  "alg" : "RS256",
  "digest" : "hoCtw6aGCaNtaHi99eRTHhZjDWf+tdws8+n6m4eLe9I="
}
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1014

{
  "kid" : "example-config/keys/testimport/462925f49be04c13a931f6e22bd09907",
  "base64Signature" : "Va4kCTjEvfNTWi+dmMgnFcInOMWyFdb002txK7XGU4xteRsRuqw6QJP2dP2Fex/+FQJQDlx84OfyLjWFq4MBNue/NKqcEnlG2wzhBADxSs/mD6O3MevLC7DmX629UamifKCEb3vbcn8vJ1bev4M05x3c2wAQbO/H1pQFgqTNmoLvCKQCsI/u6TQQCcIGa1ZMGxqVksko9HF7aBfgU509s+/fFGbd3SMtVUgkyFyJFWWJyTcg7njuV1vEiXb/SumhDSWZjo3bQ1/NKU3B4scfmFFGTvW/4G8v269YkWyy4wzc2JYeOL67X0OF0kklkWMSMmnulnFM/VvK7MztSfA1KA==",
  "hexSignature" : "55ae240938c4bdf3535a2f9d98c82715c22738c5b215d6f4d36b712bb5c6538c6d791b11baac3a4093f674fd857b1ffe1502500e5c7ce0e7f22e3585ab830136e7bf34aa9c127946db0ce10400f14acfe60fa3b731ebcb0bb0e65fadbd51a9a27ca0846f7bdb727f2f2756debf8334e71ddcdb00106cefc7d6940582a4cd9a82ef08a402b08feee9341009c2066b564c1b1a9592c928f4717b6817e0539d3db3efdf1466dddd232d554824c85c89156589c93720ee78ee575bc48976ff4ae9a10d25998e8ddb435fcd294dc1e2c71f9851464ef5bfe06f2fdbaf58916cb2e30cdcd8961e38bebb5f4385d249259163123269ee96714cfd5bcaeccced49f03528",
  "algorithm" : "RS256"
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/crypto/keys/0.9/example-config/keys/testimport/462925f49be04c13a931f6e22bd09907/sign' -i -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer c11b88cc-280d-303f-a864-bd0af62db0bb' -d '{
  "alg" : "RS256",
  "digest" : "hoCtw6aGCaNtaHi99eRTHhZjDWf+tdws8+n6m4eLe9I="
}'

4.3.4. Verify signature

POST /{config}/keys/{name}/{version}/verify
Description

Verifies a signature using a key. This operation is applicable to assymetric and symmetric keys. It is not strictly necessary for asymmetric keys, since signature verification can be performed using the public portion of the key but this operation is supported as a convenience for callers that only have a key-reference and not the public portion of the key.

Parameters
Type Name Description Schema

Path

config
required

config

string

Path

name
required

name

string

Path

version
required

version

string

Body

request
required

The verify request

KeyVerifyRequest

Responses
HTTP Code Description Schema

200

Digest signature verified.

KeyVerifyResponse

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
POST /crypto/keys/0.9/example-config/keys/testimport/latest/verify HTTP/1.1
Content-Type: application/json
Authorization: Bearer c11b88cc-280d-303f-a864-bd0af62db0bb
Host: gw.api.cloud.sphereon.com
Content-Length: 456

{
  "alg" : "RS256",
  "digest" : "hoCtw6aGCaNtaHi99eRTHhZjDWf+tdws8+n6m4eLe9I=",
  "base64Signature" : "Va4kCTjEvfNTWi+dmMgnFcInOMWyFdb002txK7XGU4xteRsRuqw6QJP2dP2Fex/+FQJQDlx84OfyLjWFq4MBNue/NKqcEnlG2wzhBADxSs/mD6O3MevLC7DmX629UamifKCEb3vbcn8vJ1bev4M05x3c2wAQbO/H1pQFgqTNmoLvCKQCsI/u6TQQCcIGa1ZMGxqVksko9HF7aBfgU509s+/fFGbd3SMtVUgkyFyJFWWJyTcg7njuV1vEiXb/SumhDSWZjo3bQ1/NKU3B4scfmFFGTvW/4G8v269YkWyy4wzc2JYeOL67X0OF0kklkWMSMmnulnFM/VvK7MztSfA1KA=="
}
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1010

{
  "kid" : "example-config/keys/testimport/latest",
  "verified" : true,
  "base64Signature" : "Va4kCTjEvfNTWi+dmMgnFcInOMWyFdb002txK7XGU4xteRsRuqw6QJP2dP2Fex/+FQJQDlx84OfyLjWFq4MBNue/NKqcEnlG2wzhBADxSs/mD6O3MevLC7DmX629UamifKCEb3vbcn8vJ1bev4M05x3c2wAQbO/H1pQFgqTNmoLvCKQCsI/u6TQQCcIGa1ZMGxqVksko9HF7aBfgU509s+/fFGbd3SMtVUgkyFyJFWWJyTcg7njuV1vEiXb/SumhDSWZjo3bQ1/NKU3B4scfmFFGTvW/4G8v269YkWyy4wzc2JYeOL67X0OF0kklkWMSMmnulnFM/VvK7MztSfA1KA==",
  "hexSignature" : "55ae240938c4bdf3535a2f9d98c82715c22738c5b215d6f4d36b712bb5c6538c6d791b11baac3a4093f674fd857b1ffe1502500e5c7ce0e7f22e3585ab830136e7bf34aa9c127946db0ce10400f14acfe60fa3b731ebcb0bb0e65fadbd51a9a27ca0846f7bdb727f2f2756debf8334e71ddcdb00106cefc7d6940582a4cd9a82ef08a402b08feee9341009c2066b564c1b1a9592c928f4717b6817e0539d3db3efdf1466dddd232d554824c85c89156589c93720ee78ee575bc48976ff4ae9a10d25998e8ddb435fcd294dc1e2c71f9851464ef5bfe06f2fdbaf58916cb2e30cdcd8961e38bebb5f4385d249259163123269ee96714cfd5bcaeccced49f03528",
  "algorithm" : "RS256"
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/crypto/keys/0.9/example-config/keys/testimport/latest/verify' -i -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer c11b88cc-280d-303f-a864-bd0af62db0bb' -d '{
  "alg" : "RS256",
  "digest" : "hoCtw6aGCaNtaHi99eRTHhZjDWf+tdws8+n6m4eLe9I=",
  "base64Signature" : "Va4kCTjEvfNTWi+dmMgnFcInOMWyFdb002txK7XGU4xteRsRuqw6QJP2dP2Fex/+FQJQDlx84OfyLjWFq4MBNue/NKqcEnlG2wzhBADxSs/mD6O3MevLC7DmX629UamifKCEb3vbcn8vJ1bev4M05x3c2wAQbO/H1pQFgqTNmoLvCKQCsI/u6TQQCcIGa1ZMGxqVksko9HF7aBfgU509s+/fFGbd3SMtVUgkyFyJFWWJyTcg7njuV1vEiXb/SumhDSWZjo3bQ1/NKU3B4scfmFFGTvW/4G8v269YkWyy4wzc2JYeOL67X0OF0kklkWMSMmnulnFM/VvK7MztSfA1KA=="
}'

4.4. Key

Key Management APIs

4.4.1. List keys metadata information

GET /{config}/keys
Description

Gets a list of all key metadata

Parameters
Type Name Description Schema

Path

config
required

config

string

Responses
HTTP Code Description Schema

200

Key metadata retrieved.

KeyMetadataListResponse

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
GET /crypto/keys/0.9/example-config/keys HTTP/1.1
Authorization: Bearer c11b88cc-280d-303f-a864-bd0af62db0bb
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 2555

{
  "keyMetadata" : {
    "example-config/keys/test/latest" : {
      "attributes" : {
        "creationTime" : "2018-03-07T23:54:31Z",
        "expirationTime" : "2019-03-07T23:54:30Z",
        "notBeforeTime" : "2018-03-07T23:44:30Z",
        "updatedTime" : "2018-03-07T23:54:31Z",
        "enabled" : true
      },
      "applicationMetadata" : { },
      "kid" : "example-config/keys/test/latest",
      "managed" : true,
      "url" : "https://gw.api.cloud.sphereon.com/crypto/keys/0.9/example-config/keys/test/latest",
      "backendMetadata" : {
        "azure:kid" : "https://sphereontestkv.vault.azure.net/keys/test"
      }
    },
    "example-config/keys/testall/latest" : {
      "attributes" : {
        "creationTime" : "2018-03-08T22:08:25Z",
        "expirationTime" : "2019-03-08T22:08:20Z",
        "notBeforeTime" : "2018-03-08T21:58:20Z",
        "updatedTime" : "2018-03-08T22:45:42Z",
        "enabled" : true
      },
      "applicationMetadata" : {
        "sphereon" : "test"
      },
      "kid" : "example-config/keys/testall/latest",
      "managed" : true,
      "url" : "https://gw.api.cloud.sphereon.com/crypto/keys/0.9/example-config/keys/testall/latest",
      "backendMetadata" : {
        "azure:kid" : "https://sphereontestkv.vault.azure.net/keys/testall"
      }
    },
    "example-config/keys/testimport/latest" : {
      "attributes" : {
        "creationTime" : "2018-08-09T01:10:14Z",
        "expirationTime" : "2021-11-04T00:00:00Z",
        "notBeforeTime" : "2016-11-04T22:24:45Z",
        "updatedTime" : "2018-08-09T01:10:14Z",
        "enabled" : true
      },
      "applicationMetadata" : { },
      "kid" : "example-config/keys/testimport/latest",
      "managed" : true,
      "url" : "https://gw.api.cloud.sphereon.com/crypto/keys/0.9/example-config/keys/testimport/latest",
      "backendMetadata" : {
        "azure:kid" : "https://sphereontestkv.vault.azure.net/keys/testimport"
      }
    },
    "example-config/keys/testkey/latest" : {
      "attributes" : {
        "creationTime" : "2018-03-09T02:55:57Z",
        "updatedTime" : "2018-03-09T02:55:57Z",
        "enabled" : true
      },
      "applicationMetadata" : { },
      "kid" : "example-config/keys/testkey/latest",
      "managed" : false,
      "url" : "https://gw.api.cloud.sphereon.com/crypto/keys/0.9/example-config/keys/testkey/latest",
      "backendMetadata" : {
        "azure:kid" : "https://sphereontestkv.vault.azure.net/keys/testkey"
      }
    }
  }
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/crypto/keys/0.9/example-config/keys' -i -H 'Authorization: Bearer c11b88cc-280d-303f-a864-bd0af62db0bb'

4.4.2. Create key

POST /{config}/keys/create
Description

Creates a new key

Parameters
Type Name Description Schema

Path

config
required

config

string

Body

request
required

The create key request

CreateKeyRequest

Responses
HTTP Code Description Schema

200

Key created

KeyBundle

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

4.4.3. Import key

POST /{config}/keys/import
Description

Imports a new key

Parameters
Type Name Description Schema

Path

config
required

config

string

Body

request
required

The import key request

ImportKeyRequest

Responses
HTTP Code Description Schema

200

Imported key successfully.

KeyBundle

Consumes
  • application/json;charset=UTF-8

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

4.4.4. Delete key

DELETE /{config}/keys/{name}
Description

Deletes a key

Parameters
Type Name Description Schema

Path

config
required

config

string

Path

name
required

name

string

Responses
HTTP Code Description Schema

200

Key deletion requested

DeletedKeyBundleResponse

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

4.4.5. Get key information

GET /{config}/keys/{name}/{version}
Description

Gets information about a key

Parameters
Type Name Description Schema

Path

config
required

config

string

Path

name
required

name

string

Path

version
required

version

string

Responses
HTTP Code Description Schema

200

Key information retrieved.

KeyBundleResponse

Produces
  • application/json;charset=UTF-8

Security
Type Name Scopes

oauth2

oauth2schema

global

Example HTTP request
GET /crypto/keys/0.9/example-config/keys/testall/latest HTTP/1.1
Authorization: Bearer c11b88cc-280d-303f-a864-bd0af62db0bb
Host: gw.api.cloud.sphereon.com
Example HTTP response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1767

{
  "name" : "testall",
  "version" : "71bba689a8f842979869479d42aa1b54",
  "keyBundle" : {
    "attributes" : {
      "creationTime" : "2018-03-08T22:08:25Z",
      "expirationTime" : "2019-03-08T22:08:20Z",
      "notBeforeTime" : "2018-03-08T21:58:20Z",
      "updatedTime" : "2018-03-08T22:45:42Z",
      "enabled" : true
    },
    "applicationMetadata" : {
      "sphereon" : "test"
    },
    "kid" : "example-config/keys/testall/71bba689a8f842979869479d42aa1b54",
    "managed" : true,
    "url" : "https://gw.api.cloud.sphereon.com/crypto/keys/0.9/example-config/keys/testall/71bba689a8f842979869479d42aa1b54",
    "backendMetadata" : {
      "azure:kid" : "https://sphereontestkv.vault.azure.net/keys/testall/71bba689a8f842979869479d42aa1b54"
    },
    "key" : {
      "kid" : "https://sphereontestkv.vault.azure.net/keys/testall/71bba689a8f842979869479d42aa1b54",
      "kty" : "RSA",
      "n" : "keNNCK0JAL0P9xVQ9B8FSZCDhnl6-lmR-oOx6aewVUosry8WyaDxp7Luqff32-U157JYReVnBM2zxiy-dI3VbwX2k9VftP1LGX1aS8EfyFe7AeV8fomg3DeVWrpW7KPScZlTaZ396vQF11W7gVXOFKYx1wwX8JafKjZ3VfVwqRAHj7hdSQBCI-nfZx-VI1sVv64aAFKrU--ehxc6IbKG00ikdVBhEps7m38IE-vkV2hVEJTQ7DzsJSlZYRMPVT3t82v-x1UN1QPHzNWR4jw1LajY_PkXKIABI4KSxyWnmYm-Gl7gNnK0W3ZZ2G5i1gDKsFjziAk1AdQu78DS4KfGC4Q2Wyl_cvyliqSywZ1FwZdesDU9Qk3mIs7pS8m0EhhGcSEffRpLc22C1Z9393uahJfAbk2ibbg7XELMv84yKfRsGvEHmgkO5jHaHOj-x4S5Z24A7HhglXGfF4DYOQJ0Vdfh681oKcEfp_1lhPDQystb02EL74lBruvjng4-zwjb5S1x5D2RT0YilWu9H7UCWdxx7QQ4pVjcg5j3dkdgIdgHAyBKEsU-9k5uEh6nyvT74--pKXxG45xcvwuzZBh1RYBFhUq6421_LjhOABMYoQkUALz4EwvMLsuELfsGuKqd-1X1HRRyICDjQuAtSnobCW15Pyr3i60MKDPziScNSDc",
      "e" : "AQAB",
      "key_ops" : [ "SIGN", "VERIFY", "ENCRYPT", "DECRYPT", "WRAP_KEY", "UNWRAP_KEY" ]
    },
    "hsmType" : "NONE"
  }
}
Example Curl request
$ curl 'https://gw.api.cloud.sphereon.com/crypto/keys/0.9/example-config/keys/testall/latest' -i -H 'Authorization: Bearer c11b88cc-280d-303f-a864-bd0af62db0bb'

5. Security

5.1. oauth2schema

Type : oauth2
Flow : application
Token URL : https://gw.api.cloud.sphereon.com/token

Name Description

global

accessEverything

6. Definitions

6.1. Action

An action to perform (email, renew)

Name Description Schema

actionType
required

The action type

enum (EMAIL_CONTACTS, AUTO_RENEW)

6.2. Attributes

Attributes associated with a key or certificate

Name Description Schema

creationTime
optional

The creation time

string (date-time)

enabled
optional

Enabled
Example : false

boolean

expirationTime
optional

The expiration time

string (date-time)

notBeforeTime
optional

Do not use before time

string (date-time)

updatedTime
optional

Last update time

string (date-time)

6.3. AzureKeyVaultSettings

Name Schema

clientId
optional

string

clientSecret
optional

string

environment
optional

enum (AZURE, AZURE_CHINA, AZURE_GERMANY, AZURE_US_GOVERNMENT)

hsmUsage
optional

enum (DISALLOW, OPTIONAL, PREFER, REQUIRE)

keyVaultName
optional

string

keyVaultURL
optional

string

region
optional

enum (US_WEST, US_WEST2, US_CENTRAL, US_EAST, US_EAST2, US_NORTH_CENTRAL, US_SOUTH_CENTRAL, US_WEST_CENTRAL, CANADA_CENTRAL, CANADA_EAST, BRAZIL_SOUTH, EUROPE_NORTH, EUROPE_WEST, UK_SOUTH, UK_WEST, ASIA_EAST, ASIA_SOUTHEAST, JAPAN_EAST, JAPAN_WEST, AUSTRALIA_EAST, AUSTRALIA_SOUTHEAST, INDIA_CENTRAL, INDIA_SOUTH, INDIA_WEST, KOREA_CENTRAL, KOREA_SOUTH, CHINA_NORTH, CHINA_EAST, GERMANY_CENTRAL, GERMANY_NORTHEAST, GOV_US_VIRGINIA, GOV_US_IOWA)

resourceGroup
optional

string

subscriptionId
optional

string

tenant
optional

string

6.4. CertificateBundle

Name Description Schema

applicationMetadata
optional

Application metadata. This is the place where you can store your own tags

< string, string > map

attributes
optional

The attributes

Attributes

backendMetadata
optional

StorageType metadata. This is the place where additional metadata return from the backend is stored

< string, string > map

cer
required
read-only

Certificate x509 CER contents

string (byte)

cid
required
read-only

Certificate Id

string

kid
optional
read-only

Key Id

string

mediaType
optional
read-only

Media type of the certificate

string

policy
optional

Certificate management policy

CertificatePolicy

sid
optional
read-only

Secret Id

string

url
required
read-only

Certificate URL

string

x509Thumbprint
optional
read-only

Certificate X509 thumbprint

string (byte)

6.5. CertificateBundleResponse

Certificate bundle response

Name Description Schema

certificateBundle
required

Certificate bundle

CertificateBundle

name
required
read-only

The name/id of the certificate

string

version
required
read-only

The version of the bundle

string

6.6. CertificateMetadata

Certificate metadata

Name Description Schema

applicationMetadata
optional

Application metadata. This is the place where you can store your own tags

< string, string > map

attributes
optional

The attributes

Attributes

backendMetadata
optional

StorageType metadata. This is the place where additional metadata return from the backend is stored

< string, string > map

cid
required
read-only

Certificate Id

string

url
required
read-only

Certificate URL

string

x509Thumbprint
optional
read-only

Certificate X509 thumbprint

string (byte)

6.7. CertificateMetadataListResponse

Certificate Metadata list response

Name Description Schema

certificateMetadata
required

The certificate metadata keyed by certificate id

< string, CertificateMetadata > map

6.8. CertificateParameters

Name Schema

certificateId
optional

string

csr
optional

string

issuerParameters
optional

IssuerParameters

requestId
optional

string

status
optional

string

statusDetails
optional

string

target
optional

string

6.9. CertificatePolicy

The certificate policy

Name Schema

attributes
optional

Attributes

id
optional

string

issuer
optional

IssuerParameters

keyProperties
optional

KeyProperties

lifetimeActions
optional

< LifetimeAction > array

secretProperties
optional

SecretProperties

x509Properties
optional

X509Properties

6.10. Configuration

Configuration

Name Description Schema

azureKeyVaultSettings
optional

AzureKeyVaultSettings

id
optional
read-only

The id of the configuration

string

implementationType
optional

enum (AZURE_KEYVAULT_MANAGED, AZURE_KEYVAULT_DEDICATED, KEYSTORE_FILE)

localStorageSettings
optional

LocalStorageSettings

name
required

The name as it appears in the urls. Allowed values hexadecimal characters and -

string

storageTypeType
optional

enum (AZURE_KEYVAULT, LOCAL_STORAGE)

6.11. ConfigurationResponse

Configuration response

Name Description Schema

configuration
required

Configuration

Configuration

6.12. Create configuration request

Name Schema

configuration
required

Configuration

6.13. CreateCertificateRequest

Create certificate request

Name Description Schema

applicationMetadata
optional

Application metadata. This is the place where you can store your own tags

< string, string > map

attributes
optional

The attributes

Attributes

name
required

The name for the certificate

string

policy
required

The policy

CertificatePolicy

6.14. CreateCertificateResponse

Certificate response

Name Description Schema

certificateParameters
required

Certificate parameters

CertificateParameters

6.15. CreateKeyRequest

Name Schema

applicationMetadata
optional

< string, string > map

attributes
optional

Attributes

crv
optional

enum (P_256, P_384, P_521, SECP256K1)

key_ops
optional

< enum (ENCRYPT, DECRYPT, SIGN, VERIFY, WRAP_KEY, UNWRAP_KEY) > array

key_size
optional

integer (int32)

kty
optional

enum (EC, RSA, OCT)

name
optional

string

6.16. DeletedCertificateBundle

Name Description Schema

applicationMetadata
optional

Application metadata. This is the place where you can store your own tags

< string, string > map

attributes
optional

The attributes

Attributes

backendMetadata
optional

StorageType metadata. This is the place where additional metadata return from the backend is stored

< string, string > map

cer
required
read-only

Certificate x509 CER contents

string (byte)

cid
required
read-only

Certificate Id

string

deletedTime
optional

string (date-time)

kid
optional
read-only

Key Id

string

mediaType
optional
read-only

Media type of the certificate

string

policy
optional

Certificate management policy

CertificatePolicy

recoveryId
optional

string

scheduledPurgeTime
optional

string (date-time)

sid
optional
read-only

Secret Id

string

url
required
read-only

Certificate URL

string

x509Thumbprint
optional
read-only

Certificate X509 thumbprint

string (byte)

6.17. DeletedCertificateBundleResponse

Certificate bundle response

Name Description Schema

deletedCertificateBundle
required

Deleted certificate bundle

DeletedCertificateBundle

name
required
read-only

The name/id of the certificate

string

version
required
read-only

The version of the bundle

string

6.18. DeletedKeyBundle

Key Metadata

Name Description Schema

applicationMetadata
optional

Application metadata. This is the place where you can store your own tags

< string, string > map

attributes
optional

The attributes

Attributes

backendMetadata
optional

StorageType metadata. This is the place where additional metadata return from the backend is stored

< string, string > map

deletedTime
optional

string (date-time)

hsmType
required
read-only

The HSM Type if any

enum (NONE, AZURE_KEYVAULT_HSM)

key
required

The Json Web Key

JsonWebKey

kid
required
read-only

Key Id

string

managed
optional

True if the key is backing a certificate
Example : false

boolean

recoveryId
optional

string

scheduledPurgeTime
optional

string (date-time)

url
required
read-only

Key URL

string

6.19. DeletedKeyBundleResponse

Key bundle response

Name Description Schema

keyBundle
required

Key bundle

DeletedKeyBundle

name
required
read-only

The name/id of the key

string

version
required
read-only

The version of the bundle

string

6.20. ImportCertificateRequest

Imports an existing valid certificate, containing a private key. The certificate can be supplied in PFX and PEM format. When using PEM format, it must contain the key as well as x509 certificate(s).

Name Description Schema

applicationMetadata
optional

Application specific metadata

< string, string > map

attributes
optional

Certificate attributes

Attributes

certificate
required

Base64 encoded representation of the certificate to import. It needs to contain the private key

string

name
required

Certificate name

string

password
optional

If the private key has a password it needs to be supplied here

string

policy
required

Certificate policy

CertificatePolicy

6.21. ImportKeyRequest

Name Schema

applicationMetadata
optional

< string, string > map

attributes
optional

Attributes

key
optional

JsonWebKey

name
optional

string

6.22. IssuerParameters

Issuer params of the X509 component of a certificate

Name Description Schema

cty
required

Type of certificate

string

name
required

Name of the referenced issuer object or reserved names; for example, 'Self' or 'Unknown'.

string

6.23. JsonWebKey

Name Description Schema

crv
optional

Elliptic curve name. see JsonWebKeyCurveName

enum (P_256, P_384, P_521, SECP256K1)

d
optional

RSA private exponent

string (byte)

dp
optional

RSA Private Key Parameter

string (byte)

dq
optional

RSA Private Key Parameter

string (byte)

e
optional

RSA public exponent

string (byte)

k
optional

Symmetric key

string (byte)

key_ops
optional

Supported operations

< enum (ENCRYPT, DECRYPT, SIGN, VERIFY, WRAP_KEY, UNWRAP_KEY) > array

kid
optional

Key id

string

kty
optional

Key type

enum (EC, RSA, OCT)

n
optional

RSA modulus

string (byte)

p
optional

RSA secret prime

string (byte)

q
optional

RSA secret prime, with p <

string (byte)

qi
optional

RSA Private Key Parameter

string (byte)

t
optional

HSM Token, used with Bring Your Own Key

string (byte)

x
optional

X component of an EC public key

string (byte)

y
optional

Y component of an EC public key.

string (byte)

6.24. KeyBundle

Key Metadata

Name Description Schema

applicationMetadata
optional

Application metadata. This is the place where you can store your own tags

< string, string > map

attributes
optional

The attributes

Attributes

backendMetadata
optional

StorageType metadata. This is the place where additional metadata return from the backend is stored

< string, string > map

hsmType
required
read-only

The HSM Type if any

enum (NONE, AZURE_KEYVAULT_HSM)

key
required

The Json Web Key

JsonWebKey

kid
required
read-only

Key Id

string

managed
optional

True if the key is backing a certificate
Example : false

boolean

url
required
read-only

Key URL

string

6.25. KeyBundleResponse

Key bundle response

Name Description Schema

keyBundle
required

Key bundle

DeletedKeyBundle

name
required
read-only

The name/id of the key

string

version
required
read-only

The version of the bundle

string

6.26. KeyDecryptRequest

Name Schema

alg
optional

enum (RSA_OAEP_256, RSA_OAEP, RSA1_5)

encrypted
optional

string (byte)

6.27. KeyDecryptResponse

Name Description Schema

decrypted
required
read-only

The decrypted value in base64url format

string (byte)

kid
required
read-only

The Key Id

string

6.28. KeyEncryptRequest

Name Schema

alg
optional

enum (RSA_OAEP_256, RSA_OAEP, RSA1_5)

input
optional

string (byte)

6.29. KeyEncryptResponse

Name Description Schema

encrypted
required
read-only

The encrypted value in base64 value

string (byte)

kid
required
read-only

The Key Id

string

6.30. KeyMetadata

Key Metadata

Name Description Schema

applicationMetadata
optional

Application metadata. This is the place where you can store your own tags

< string, string > map

attributes
optional

The attributes

Attributes

backendMetadata
optional

StorageType metadata. This is the place where additional metadata return from the backend is stored

< string, string > map

kid
required
read-only

Key Id

string

managed
optional

True if the key is backing a certificate
Example : false

boolean

url
required
read-only

Key URL

string

6.31. KeyMetadataListResponse

Key metadata list response

Name Description Schema

keyMetadata
required

Key metadata list, keyed with Key Id

< string, KeyMetadata > map

6.32. KeyProperties

Properties of the key pair backing the certificate

Name Description Schema

exportable
optional

Whether the private key is exportable
Example : false

boolean

keySize
optional

The key size in bytes. eg 1024, 2048 or 4096

integer (int32)

kty
optional

Key type

string

reuseOnRenewal
optional

Indicates if the same key pair will be used on certificate renewal
Example : false

boolean

6.33. KeySignRequest

The sign request (using a key)

Name Description Schema

alg
required

The algorithm to use for signing the diget

enum (PS256, PS384, PS512, RS256, RS384, RS512, RSNULL, ES256, ES384, ES512, ECDSA256)

digest
required

The digest value. This must be a hash that conforms to the algorithm choosen

string (byte)

6.34. KeySignResponse

The response of the sign request

Name Description Schema

algorithm
required
read-only

The signature algorithm used in the request

enum (PS256, PS384, PS512, RS256, RS384, RS512, RSNULL, ES256, ES384, ES512, ECDSA256)

base64Signature
required
read-only

The signature of the sign request in base 64 form

string (byte)

hexSignature
required
read-only

The signature of the sign request in hex form

string

kid
required
read-only

The Key Id

string

6.35. KeyVerifyRequest

The verify request (using the digest and signature). Please note that for assymetric encryption we encourage you to do the verification clientside for best performance

Name Description Schema

alg
required

The algorithm to use for signing the diget

enum (PS256, PS384, PS512, RS256, RS384, RS512, RSNULL, ES256, ES384, ES512, ECDSA256)

base64Signature
optional

The signature in base 64 form. Please note that the base 64 xor the HEX signature is mandatory.

string (byte)

digest
required

The digest value. This must be a hash that conforms to the algorithm choosen

string (byte)

hexSignature
optional

The signature in HEX form. Please note that the base 64 xor the HEX signature is mandatory.

string

6.36. KeyVerifyResponse

The response of the sign request

Name Description Schema

algorithm
required
read-only

The signature algorithm used in the request

enum (PS256, PS384, PS512, RS256, RS384, RS512, RSNULL, ES256, ES384, ES512, ECDSA256)

base64Signature
required
read-only

The signature of the sign request in base 64 form

string (byte)

hexSignature
required
read-only

The signature of the sign request in hex form

string

kid
required
read-only

The Key Id

string

verified
required
read-only

Whether the supplied signature matched the regenerated signature
Example : false

boolean

6.37. LifetimeAction

Lifetime action and trigger for certificate

Name Description Schema

action
required

The action that will be performed

Action

trigger
required

The trigger condition for the action

Trigger

6.39. SecretProperties

Properties of the key backing the certificate

Name Description Schema

mediaType
optional

The media type (MIME type)

string

6.40. SubjectAlternativeNames

Subject Alternative Names

Name Description Schema

dnsNames
optional

Domain names

< string > array

emailAddresses
optional

Email adresses

< string > array

userPrincipalNames
optional

User principal names

< string > array

6.41. Trigger

The trigger for an action

Name Description Schema

daysBeforeExpiry
optional

The amount of days before the certificate expires

integer (int32)

lifetimePercentage
optional

The percentage of the lifetime of the certificate at which to execute the action. eg 90

integer (int32)

6.42. UpdateConfigurationRequest

Update configuration request

Name Schema

configuration
required

Configuration

6.43. X509Properties

Name Description Schema

enhancedKeyUsage
optional

Enhanced key usage

< string > array

keyUsage
required

List of key usages

< enum (DIGITAL_SIGNATURE, NON_REPUDIATION, KEY_ENCIPHERMENT, DATA_ENCIPHERMENT, KEY_AGREEMENT, KEY_CERT_SIGN, CRL_SIGN, ENCIPHER_ONLY, DECIPHER_ONLY) > array

sans
optional

Subject alternative name

SubjectAlternativeNames

subject
required

Subject name. Should be a valid X509 Distinguished Name

string

validityMonths
required

Certificate validity in months

integer (int32)