Oracle Vault

Oracle Vault is a service that allows you to store and manage sensitive information such as keys, passwords, and certificates. It provides a secure and centralized location to store and manage sensitive information, and it provides access controls to ensure that only authorized users and applications can access the information.

The walt.id Wallet API provides an interface to interact with Oracle Vault to store and manage keys .

Oracle vault Configuration

On the Oracle Cloud Infrastructure (OCI) console, you can create a vault and manage the keys in the vault.

Create a Vault

To create a vault, you can follow the steps below:

  1. Go to the OCI console and navigate to the Vault service.
  2. Click on the Create Vault button.
  3. Enter the details for the vault, such as the compartment and name.
  4. Click on the Create button to create the vault.
  5. Once the vault is created, you can manage the keys in the vault.

Create Vault

Get Vault Details

To get the details of the vault, you can follow the steps below:

  1. Go to the OCI console and navigate to the Vault service.
  2. Click on the vault to view the details of the vault.
  3. You can view the details of the vault, such as the OCID, management endpoint, and crypto endpoint.
  4. You can use this information to configure the wallet to use Oracle Vault.

Vault Details

Get tenancy OCID

To get the tenancy OCID, you can follow the steps below:

  1. Go to the OCI console and click on the user profile.
  2. Click on the Tenancy:{name-of-tenancy} to view the details of the tenancy.
  3. You can view the details of the tenancy, such as the OCID.
  4. You can use this OCID to configure the wallet to use Oracle Vault.

Tenancy OCID

Get user OCID

To get the user OCID, you can follow the steps below:

  1. Go to the OCI console and click on the user profile -> My profile.
  2. You can view the details of the user, such as the OCID.
  3. You can use this OCID to configure the wallet to use Oracle Vault.

User OCID

Add Vault user

To use the vault api you need to add a user and provide him with the necessary permissions to access the vault. Once added you can generate a private key for the user and use it to authenticate the wallet to the vault.

You can find more information on how to add a user and generate a fingerprint + private key here

Instance Principal Authentication

To use oci sdk method you need to configure the vault for instance principal authentication. This is done by adding the instance principal to the vault and providing the necessary permissions.

You can find more information on how to configure instance principal authentication here

Key Creation

Below you find an example call to create a key in OCI Vault and associate it with a wallet managed by the Wallet API.

The only thing that is important to note for the creation, that our system is only compatible with the following Key types offered by the OCI Vault:

  • RSA & ECDSA

Oracle KMS key types full list.

OCI SDK
OCI REST API

**Endpoint: ** /onboard/issuer | API Reference

Example Request

curl -X 'POST' \
  'https://wallet.walt.id/wallet-api/wallet/f01f8f55-d098-4c53-b47b-c97552829b39/keys/generate' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
  "backend": "oci",
  "config": {
     "vaultId": "ocid1.vault.oc1.eu-frankfurt-1.entbf645aabf2.abtheljshkb6dsuldqf324kitneb63vkz3dfd74dtqvkd5j2l2cxwyvmefeq",
     "compartmentId": "ocid1.compartment.oc1..aaaaaaaawirugoz35riiybcxsvf7bmelqsxo3sajaav5w3i2vqowcwqrllxa"
  },
  "keyType": "secp256r1"
}'

Body

{
  "backend": "oci",
  "config": {
    "vaultId": "ocid1.vault.oc1.eu-frankfurt-1.entbf645aabf2.abtheljshkb6dsuldqf324kitneb63vkz3dfd74dtqvkd5j2l2cxwyvmefeq",
    "compartmentId": "ocid1.compartment.oc1..aaaaaaaawirugoz35riiybcxsvf7bmelqsxo3sajaav5w3i2vqowcwqrllxa"
  },
  "keyType": "secp256r1"
}

Body Parameters

  • backend: String - The location where the key is stored. In our case oci as we want to store it in oracle's vault.
  • config
    • vaultId: String - the OCID of the vault where the key should be stored.
    • compartmentId: String - the OCID of the compartment where the key should be stored.
  • keyType: String - the algorithm used to generate the key. For Vault only RSA and secp256r1 is possible.

Example Response

The API will respond with the ID of the key. This ID is the internal reference and can be used in operations such as DID create or key delete.

Kki22j4lUwo1gtDfdvdCgOE0hhKcNHgIZSzSxU0CugE

Creation via Issuer API

OCI SDK
OCI REST API

**Endpoint: ** /onboard/issuer | API Reference

Example Request

curl -X 'POST' \
  'https://issuer.portal.walt-test.cloud/onboard/issuer' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": {
    "backend": "oci",
    "keyType": "secp256r1",
    "config": {
      "tenancyOcid": "ocid1.tenancy.oc1..aaaaaaaaiijfupfvsqwqwgupzdy5yclfzcccmie4ktp2wlgslftv5j7xpk6q",
      "compartmentOcid": "ocid1.tenancy.oc1..aaaaaaaaiijfupfvsqwqwgupzdy5yclfzcccmie4ktp2wlgslftv5j7xpk6q",
      "userOcid": "ocid1.user.oc1..aaaaaaaaxjkkfjqxdqk7ldfjrxjmacmbi7sci73rbfiwpioehikavpbtqx5q",
      "fingerprint": "bb:d4:4b:0c:c8:3a:49:15:7f:87:55:d5:2b:7e:dd:bc",
      "managementEndpoint": "entaftlvaaemy-management.kms.eu-frankfurt-1.oraclecloud.com",
      "cryptoEndpoint": "entaftlvaaemy-crypto.kms.eu-frankfurt-1.oraclecloud.com",
      "signingKeyPem": "-----BEGIN PRIVATE KEY-----\n\n-----END PRIVATE KEY-----\n"
    }
  },
  "did": {
    "method": "jwk"
  }
}'

Body

{
  "key": {
    "backend": "oci",
    "keyType": "secp256r1",
    "config": {
      "tenancyOcid": "ocid1.tenancy.oc1..aaaaaaaaiijfupfvsqwqwgupzdy5yclfzcccmie4ktp2wlgslftv5j7xpk6q",
      "compartmentOcid": "ocid1.tenancy.oc1..aaaaaaaaiijfupfvsqwqwgupzdy5yclfzcccmie4ktp2wlgslftv5j7xpk6q",
      "userOcid": "ocid1.user.oc1..aaaaaaaaxjkkfjqxdqk7ldfjrxjmacmbi7sci73rbfiwpioehikavpbtqx5q",
      "fingerprint": "bb:d4:4b:0c:c8:3a:49:15:7f:87:55:d5:2b:7e:dd:bc",
      "managementEndpoint": "entaftlvaaemy-management.kms.eu-frankfurt-1.oraclecloud.com",
      "cryptoEndpoint": "entaftlvaaemy-crypto.kms.eu-frankfurt-1.oraclecloud.com",
      "signingKeyPem": "-----BEGIN PRIVATE KEY-----\n\n-----END PRIVATE KEY-----\n"
    }
  },
  "did": {
    "method": "jwk"
  }
}

Body Parameters

  • key
    • backend: String - Specifies the storage type of key. It can be jwk (manged by you), TSE (managed by Hashicorp) or oci (managed by Oracle)
    • keyType: String - the algorithm used to generate the key. For Vault only secp256r1 is possible.
  • did:
    • method: String - Specifies the DID method. It can be key, jwk, web, cheqd.

Example Response

The onboard/issuer endpoint will return an object containing both the generated key in JWK format and the related DID.

{
  "issuerKey": {
    "type": "oci",
    "config": {
      "vaultId": "ocid1.vault.oc1.eu-frankfurt-1.entbf645aabf2.abtheljshkb6dsuldqf324kitneb63vkz3dfd74dtqvkd5j2l2cxwyvmefeq",
      "compartmentId": "ocid1.compartment.oc1..aaaaaaaawirugoz35riiybcxsvf7bmelqsxo3sajaav5w3i2vqowcwqrllxa"
    },
    "id": "ocid1.key.oc1.eu-frankfurt-1.enta2fneaadmk.abtheljrlj5snthwkx7ycdmknuftght527dkyjsoz72dcogklixrsdyolo5a",
    "_publicKey": "{\"kty\":\"EC\",\"crv\":\"P-256\",\"x\":\"tT1DAZdtp7vUPphTxoilmr6dfZPKcPfwL8G_Ri3K0_E\",\"y\":\"JabPubkHQPK0G7O8eL3bKg75hX4Wkojb_AOepX8xdAs\"}",
    "_keyType": "secp256r1"
  },
  "issuerDid": "did:jwk:eyJrdHkiOiJFQyIsImNydiI6IlAtMjU2IiwieCI6InRUMURBWmR0cDd2VVBwaFR4b2lsbXI2ZGZaUEtjUGZ3TDhHX1JpM0swX0UiLCJ5IjoiSmFiUHVia0hRUEswRzdPOGVMM2JLZzc1aFg0V2tvamJfQU9lcFg4eGRBcyJ9"
}

Properties

  • type: String - the type of key can be either "oci" when using OCI Vault or "jwk" when providing the key in full as JWK.
  • config: Object - the configuration object containing the necessary information to access the OCI Vault.
  • id: String - the ID of the key in the OCI Vault.
  • _publicKey (optional): Array - The public key can be fetched by the issuer API or directly provided, saving resources and reducing network requests.
  • _keyType (optional): String - The key type can be fetched by the issuer API or directly provided, saving resources and reducing network requests.

Key Usage

Once you have successfully created a key that is one of the supported types listed above, you can use it in sign and issue operations offered by the issuer API.

If you've already had a look at our /sign, /issue, /batchIssue endpoints, you have seen that they all follow a similar request body structure, where the key that should be used for signing credentials is provided via the issuerKey property. Now instead of providing the key as JWK, we provide a reference to a key stored in Vault with the required parameters and access credentials.

Below you can see an example of issuerKey object referencing a key stored in Vault.

Example IssuerKey Object

{
  "type": "oci-rest-api",
  "config": {
    "tenancyOcid": "ocid1.tenancy.oc1..aaaaaaaaxxxxxx",
    "compartmentOcid": "ocid1.tenancy.oc1..aaaaaaaaxxxxxx",
    "userOcid": "ocid1.user.oc1..aaaaaaaaxxxxxx",
    "fingerprint": "d4:4b:0c:c8:3a:49:15:7f:87",
    "managementEndpoint": "vault-management.region.oraclecloud.com",
    "cryptoEndpoint": "vault-crypto.region.oraclecloud.com",
    "signingKeyPem": "-----BEGIN PRIVATE KEY-----"
  },
  "id": "ocid1.key.oc1.eu-frankfurt-1.entaftlvaaemy.abtheljtkwxupytaepjrgvgbhoufoonh2kbevc3cenjetbpeabhgcxyzcmwq",
  "_publicKey": "{\"kty\":\"EC\",\"crv\":\"P-256\",\"x\":\"r1FURkMEYWiYL_IKi1bG0Ar-N36Z5bvocBcEKtkGF_s\",\"y\":\"0QP3QWwVXfpZf_i-T9qOaSMfd3_or7t6JtbJr9YkvPY\"}",
  "_keyType": "secp256r1"
}

Properties

  • type: String - the type of key can be either "oci" when using OCI Vault or "jwk" when providing the key in full as JWK.
  • config: Object - the configuration object containing the necessary information to access the OCI Vault.
  • id: String - the ID of the key in the OCI Vault.
  • _publicKey (optional): Array - The public key can be fetched by the issuer API or directly provided, saving resources and reducing network requests.
  • _keyType (optional): String - The key type can be fetched by the issuer API or directly provided, saving resources and reducing network requests.

Example Issuance Request

Below you can see example issuance request to jwt/issue using a key created in the Vault Transit Secret Engine to sign the credential.

OCI SDK
OCI REST API

Api Reference

curl -X 'POST' \
  'https://issuer.portal.walt.id/openid4vc/jwt/issue' \
  -H 'accept: text/plain' \
  -H 'Content-Type: application/json' \
  -d '{
  "issuerKey": {
    "type": "oci",
    "config": {
       "vaultId": "ocid1.vault.oc1.eu-frankfurt-1.entbf645aabf2.abtheljshkb6dsuldqf324kitneb63vkz3dfd74dtqvkd5j2l2cxwyvmefeq",
       "compartmentId": "ocid1.compartment.oc1..aaaaaaaawirugoz35riiybcxsvf7bmelqsxo3sajaav5w3i2vqowcwqrllxa"
    },
    "id": "ocid1.key.oc1.eu-frankfurt-1.entaftlvaaemy.abtheljtkwxupytaepjrgvgbhoufoonh2kbevc3cenjetbpeabhgcxyzcmwq",
    "_publicKey": "{\"kty\":\"EC\",\"crv\":\"P-256\",\"x\":\"r1FURkMEYWiYL_IKi1bG0Ar-N36Z5bvocBcEKtkGF_s\",\"y\":\"0QP3QWwVXfpZf_i-T9qOaSMfd3_or7t6JtbJr9YkvPY\"}",
    "_keyType": "secp256r1"
  },
  "issuerDid": "did:key:z6MkjoRhq1jSNJdLiruSXrFFxagqrztZaXHqHGUTKJbcNywp",
  "credentialData": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://purl.imsglobal.org/spec/ob/v3p0/context.json"
    ],
    "id": "urn:uuid:THIS WILL BE REPLACED WITH DYNAMIC DATA FUNCTION (see below)",
    "type": [
      "VerifiableCredential",
      "OpenBadgeCredential"
    ],
    "name": "JFF x vc-edu PlugFest 3 Interoperability",
    ... 
  },
  "mapping": {
    "id": "<uuid>",
     ... 
  }
}'

Body

As you can see for the property issuanceKey we only provided the required parameters of the OCI Key Reference Object described above and left out _publicKey and _keyType

{
  "issuanceKey": {
    "type": "oci",
    "config": {
      "vaultId": "ocid1.vault.oc1.eu-frankfurt-1.entbf645aabf2.abtheljshkb6dsuldqf324kitneb63vkz3dfd74dtqvkd5j2l2cxwyvmefeq",
      "compartmentId": "ocid1.compartment.oc1..aaaaaaaawirugoz35riiybcxsvf7bmelqsxo3sajaav5w3i2vqowcwqrllxa"
    },
    "id": "ocid1.key.oc1.eu-frankfurt-1.entaftlvaaemy.abtheljtkwxupytaepjrgvgbhoufoonh2kbevc3cenjetbpeabhgcxyzcmwq",
    "_publicKey": "{\"kty\":\"EC\",\"crv\":\"P-256\",\"x\":\"r1FURkMEYWiYL_IKi1bG0Ar-N36Z5bvocBcEKtkGF_s\",\"y\":\"0QP3QWwVXfpZf_i-T9qOaSMfd3_or7t6JtbJr9YkvPY\"}",
    "_keyType": "secp256r1"
  },
  "issuerDid": "did:key:z6MkjoRhq1jSNJdLiruSXrFFxagqrztZaXHqHGUTKJbcNywp",
  "credentialData": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://purl.imsglobal.org/spec/ob/v3p0/context.json"
    ],
    "id": "urn:uuid:THIS WILL BE REPLACED WITH DYNAMIC DATA FUNCTION (see below)",
    "type": [
      "VerifiableCredential",
      "OpenBadgeCredential"
    ],
    "name": "JFF x vc-edu PlugFest 3 Interoperability",
    ...
  },
  "mapping": {
    "id": "<uuid>",
    ...
  }
}
Hashicorp VaultAWS KMS