Skip to content

fix(policy): Update key management docs. #141

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
c-r33d merged 11 commits into from
Aug 12, 2025
Merged

fix(policy): Update key management docs. #141

Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
056c4d6
fix(policy): Update key management docs.
c-r33d Aug 11, 2025
24e8ed4
update.
c-r33d Aug 11, 2025
6f31a1f
update.
c-r33d Aug 11, 2025
11a339c
update.
c-r33d Aug 11, 2025
bd6c116
update.
c-r33d Aug 11, 2025
150b429
Update docs/components/policy/keymanagement/quickstart.md
c-r33d Aug 11, 2025
926fa67
Update docs/components/policy/keymanagement/quickstart.md
c-r33d Aug 11, 2025
c532952
Update docs/components/policy/keymanagement/quickstart.md
c-r33d Aug 11, 2025
f82541a
update with static links.
c-r33d Aug 12, 2025
b13f7e8
Merge branch 'dspx-1565-km-doc-updates' of github.com:opentdf/docs in…
c-r33d Aug 12, 2025
606b8f9
Merge branch 'main' into dspx-1565-km-doc-updates
c-r33d Aug 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 13 additions & 13 deletions docs/components/policy/keymanagement/quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@

## Key management is activated for KAS

- To activate key management for KAS you will need to modify the **key_management** field within the opentdf.yaml file to be true. [opentdf-dev.yaml](https://github.com/opentdf/platform/blob/main/opentdf-dev.yaml#L24).
- To activate key management for KAS you will need to modify the **key_management** field within the opentdf.yaml file to be true. [opentdf-dev.yaml](https://github.com/opentdf/platform/blob/6203fbaebcdd57b5b3437679465149f8ff395484/opentdf-dev.yaml#L25).

Check failure on line 32 in docs/components/policy/keymanagement/quickstart.md

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'key_management'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'key_management'?", "location": {"path": "docs/components/policy/keymanagement/quickstart.md", "range": {"start": {"line": 32, "column": 68}}}, "severity": "ERROR"}
- You will also need to set a root key to be used with the basic manager. The root key should be 32 bytes long.
- In addition, the root key should be hex encoded.

Expand All @@ -39,15 +39,15 @@
You can also perform all key commands with the [OpenTDF CLI](https://github.com/opentdf/otdfctl)
:::

1. You will want to have already created and registered a **Key Access Server** with the platform via the [Create Key Access Server Endpoint](https://github.com/opentdf/platform/blob/main/service/policy/kasregistry/key_access_server_registry.proto#L630).
2. Once you have a **Key Access Server** registered you will then want to create a key for that registered KAS.
1. You should already have created and registered a **Key Access Server** with the platform via the [Create Key Access Server Endpoint](https://github.com/opentdf/platform/blob/6203fbaebcdd57b5b3437679465149f8ff395484/service/policy/kasregistry/key_access_server_registry.proto#L59).
2. Once you have a **Key Access Server** registered you should then create a key for that registered KAS.

The definition for creating a key can be found in the key_access_registry [proto](https://github.com/opentdf/platform/blob/main/service/policy/kasregistry/key_access_server_registry.proto#L399-L421).
The definition for creating a key can be found in the key_access_registry [proto](https://github.com/opentdf/platform/blob/6203fbaebcdd57b5b3437679465149f8ff395484/service/policy/kasregistry/key_access_server_registry.proto#L379).

Check failure on line 45 in docs/components/policy/keymanagement/quickstart.md

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use 'Podman' instead of 'proto'.

Raw Output:
{"message": "[Vale.Terms] Use 'Podman' instead of 'proto'.", "location": {"path": "docs/components/policy/keymanagement/quickstart.md", "range": {"start": {"line": 45, "column": 76}}}, "severity": "ERROR"}

Check failure on line 45 in docs/components/policy/keymanagement/quickstart.md

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'key_access_registry'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'key_access_registry'?", "location": {"path": "docs/components/policy/keymanagement/quickstart.md", "range": {"start": {"line": 45, "column": 55}}}, "severity": "ERROR"}

Let's look at a valid request and dissect it:

:::note
These keys can be found within the [policy_fixtures.yaml](https://github.com/opentdf/platform/blob/main/service/internal/fixtures/policy_fixtures.yaml#L541) file located
These keys can be found within the [policy_fixtures.yaml](https://github.com/opentdf/platform/blob/6203fbaebcdd57b5b3437679465149f8ff395484/service/internal/fixtures/policy_fixtures.yaml#L528) file located
in opentdf.
:::

Expand All @@ -62,7 +62,7 @@
},
"private_key_ctx": {
"key_id": "config",
"wrapped_key": "eyAid3JhcHBlZEtleSI6ICJsY2JxNjgyR3NpaStqRWtRNjJzV0lYa1dXVkpqZ1dQdXZobUJ0OUtpWUZKL28zWENseVJkNGMwS0RGdHVvaGRCdzJqdlZHd2VGZnNwaTllV0dNSXpFbDZiY0VSYzUycTVIdmlINWtjVDlSY25KaFV2M2lONjM1UndIek52akdFVktLVU5CdjRwZkVOMzB3N29wSFBpZ3owS1ExVkJNSk5PM1lEOUZWQTdVb0h4MGVKY0Y3WlFKSkdYeHdwUVYwTXR3bHFtUnBxNFEyVTl2cFlyajY3ODdRSEdmOWhlZ0lYTkErcjByM1RDTHB3YzVZM0E5aEhreWp3N1FnWEU4dWVKSUx1TW04N0NlckpweVpPQ3NySDN2QWppWUFWdjcvZEVKcWpYMUFnYUI4NFQ3aHhERmVqOUpLaEl5OWVLWk5yTndNWW1Bc0hwYkEzamc1R0VIQjdFM2ZYRXFoaTFTTllhR1ZpZHRvSnVTLzNrVm5JTEtOWTZpZnRvNllMTEJBdWlQQVJjNTZVblVTS0hZQ1dtTko3QkM4Y0hhN2FIdDllUW1lVVRicVZmMGg3aDQ2M3FZQ2F6RDhYT0FMUTBuQ3lPQ3I5dUxkV1o1QThLbHFmMytqKzcyOGtaYUJFN2tKZ1I1UFh0dDFMTHlYcThmSEhPRXNOWXMzT3RSOGN3akV1ZGpvVVRJMTd1YkJOYjhYZU01emFaL1dmdWZDcWp2UGVjREt6cHJVbzdlanBrZjZKOEJ0RStZSFZRSjdNMWJWb1ZlQ0tFTWUvK3p5Y2Zpc3BzbmZsQ1ZtNkJNdFlMdmtVLzIzRWRiOWNNN1BRR3lFTEZOeDMyQXRwUXpMRUUrNWVaWWFhUU5Za3hEaWF0c3ZkMkQyNEVSTVhmWGp1YWg4MTBOSVpUZTE4cStGMitZMEtuTU9LZHpqV3AyUXdvNHVIb3JidndRRkwzOXZrVHJmZTIzelhVY2Q2N1pCTmpJUUNGc0prOW5sRk9ORjhrc25XVzQ5aHdxSjk1dXJtaG5zSGRSZlBrbVc2SHZ0UnVTclN3L2VmOGZ0MUZmMlZGMUNKUXArSnc2YnpKWmRQSzdsTmxmN1F3N2trREtqSGxnTTVnanZlZVJXZjE5Q3FqaTdHM1FhSS9Oa3FDdEplWllLZmZGU1RtbStIY3o0bXpMQkpzc3hNdGgvUkRaQzVTaVVJODJhZ0h0QkJ5VC9DK3A2NEE3cjZGeFNvdmRNTi9mTU5ZSUx3NGRQV3VxdDZwNmVnTUlyMFNVYXBpUHJpTjBiRjNaN2d5R1QxQXZyMHVnaU9qQUI3L3pybDJHaWFlajFUV01YS08zd2J4L0VzUVdpMDNWcmxWanBIdjl2Y2hlWjdGTzliREJUUkxKZHI0QkU4RWs0YkZCaytxRkZOQXZXcC9GZDFiNnFiKytEdU5Iajg1V2R3WE1PaW9nNUlSSzdjZUlNT0xQY214TnE3YXh5WnkrTm0yQ2VocjN5Qk9OQzFQRml4U2NMSGJZUEJlTU9EaGJHWXo5NEVaYkxHOWJpL1B5RkJiNERYSGlLemxrNEtTZ3BYZ1FLUHBSRWx6aUNiYVB3WlowZVljUEhoaktVNHQ3a2k3TlR2MlFYVU1nK3V2dVZWajJtcGpSMTJ5bmJiS2xJNDJoUEcxYW1FV0JlM1JjNmZ4cW5uQnVScnlMWjdEYW5wa252V0t5UXE3S1pHSHJGemlaMEE3Q1VSejFnT2R4d2xDQXEvRnAxZ2oxMGpNMFpJK3lod1RGcnhCUDJXdHF1S1dBREhGMHBGblNWdUpKUnlzUFR2aXNSYVM1N3d2aVZZQnRCcnRGYmZhTHBGcytwQ2ViYk81K0dRZ29wWlZaSDM5c0lnY0dIY3B4RU1zdDBCd3JuUGZIM0RRbGJqVmdrWlFmNkJiZUpDNWFBL2tEVTVSZFNiUTI1NjNCcGRMRUREQ3dvaVU5NW5LcE1tOE8zVTIxMEdRMHgveFdFYUMxdDJkOVM2RlVFbFRVSlJYWVZNZVB2Z3JaMnZGajl5YTZvNm5LVWt4RXAyaUlkS2d1ckR4MEVNSHZ2NU90TEZYTnVXWVdIU0o3czNET3JWNjZxUXRYaHF6VUlsRjRHWERVYUpmZ3NtUTk0MU03eUFqL3RibjBHUGFkMENsRXZWd25ucGpnNEpoZ2Y1dlpCaC9TcG5Na2hia1RIQis0ajhrT1dFTHdWc2ZDU3RTa0ZGdHAxY1VtRVI5RWhqSzhjSmJ3L2FKVTU5ZkZmZDJXR0N6VUxIZkEyMURLcld6SWwzODhray94cXdUN1E5aU92Y1NSN1pzdE10R1RRWG54Q1gvV3A4VG9qNjRIM2RsR2p6TGhGeDZ1Qk53WFQxMTRSeGw4ZWZLdW9VZzd0ZHcxcVdtOUplUC92TVF6VTlLd2Z5SExLNmdDQUlmWkpneVkrcnVyN0YrZVNPRUlEeWlkRnJLM1NWTFE3T1lHRmVXaFRNS01HdzdaV2VuTC9xWDdBUFErdkdoMmpQNTJVN2VsT0t4L1RsTkZ5UHJHL2FZUDN0MDRTdWVZUkd2RXAremZkVU0xbmYvN3YvRHhzc1VSS29zQUdHa1JwbzBLQ3NUU0I4UzhxdTlNKzA3YjBSREVXai9QdHVrZWdvRUR1KzZ4azN0WmRqclpWTTIxZURDaDhxME9HbS9KeDBITWVlUHFIY28zeEdTMUpYMW90QVp3UEhaaUkyaWNjWksrV21KTExaSXJYSzRsSG8vd1lpQitOeUlwZDJWd2dTdXZua3hhTlF5dmxtdWtSaTJCTzM1ZEdDNVFaY1V5d2lCZlRoSzdzRC9CMjJHNDZlUVNHeTdqeTlJSmJaMXhNKzVHcXVxOTdPOCtWOVIreEcydW1ZN0grWG90NlBaRjVPT0hERmI2cEVUSThsNDJDdDV2bElJMmRmWXFqZWR6WHAvb1drdXFub2FQejNnUU4wS2JGaDlsazZvVXVJMWlMaHBDMWxIR283em8xV3E0NDFlUW9nS3dhWFNDcGxQNDE0UW44dFE0elcvRTdjZ2hLbnpWMTg1K2lHdXBxTnNoWTBlS1VtSzB2Rkx3dkcrdnc9PSIsICJrZXlfaWQiOiAiY29uZmlnIiB9"
"wrapped_key": "lcbq682Gsii+jEkQ62sWIXkWWVJjgWPuvhmBt9KiYFJ/o3XClyRd4c0KDFtuohdBw2jvVGweFfspi9eWGMIzEl6bcERc52q5HviH5kcT9RcnJhUv3iN635RwHzNvjGEVKKUNBv4pfEN30w7opHPigz0KQ1VBMJNO3YD9FVA7UoHx0eJcF7ZQJJGXxwpQV0MtwlqmRpq4Q2U9vpYrj6787QHGf9hegIXNA+r0r3TCLpwc5Y3A9hHkyjw7QgXE8ueJILuMm87CerJpyZOCsrH3vAjiYAVv7/dEJqjX1AgaB84T7hxDFej9JKhIy9eKZNrNwMYmAsHpbA3jg5GEHB7E3fXEqhi1SNYaGVidtoJuS/3kVnILKNY6ifto6YLLBAuiPARc56UnUSKHYCWmNJ7BC8cHa7aHt9eQmeUTbqVf0h7h463qYCazD8XOALQ0nCyOCr9uLdWZ5A8Klqf3+j+728kZaBE7kJgR5PXtt1LLyXq8fHHOEsNYs3OtR8cwjEudjoUTI17ubBNb8XeM5zaZ/WfufCqjvPecDKzprUo7ejpkf6J8BtE+YHVQJ7M1bVoVeCKEMe/+zycfispsnflCVm6BMtYLvkU/23Edb9cM7PQGyELFNx32AtpQzLEE+5eZYaaQNYkxDiatsvd2D24ERMXfXjuah810NIZTe18q+F2+Y0KnMOKdzjWp2Qwo4uHorbvwQFL39vkTrfe23zXUcd67ZBNjIQCFsJk9nlFONF8ksnWW49hwqJ95urmhnsHdRfPkmW6HvtRuSrSw/ef8ft1Ff2VF1CJQp+Jw6bzJZdPK7lNlf7Qw7kkDKjHlgM5gjveeRWf19Cqji7G3QaI/NkqCtJeZYKffFSTmm+Hcz4mzLBJssxMth/RDZC5SiUI82agHtBByT/C+p64A7r6FxSovdMN/fMNYILw4dPWuqt6p6egMIr0SUapiPriN0bF3Z7gyGT1Avr0ugiOjAB7/zrl2Giaej1TWMXKO3wbx/EsQWi03VrlVjpHv9vcheZ7FO9bDBTRLJdr4BE8Ek4bFBk+qFFNAvWp/Fd1b6qb++DuNHj85WdwXMOiog5IRK7ceIMOLPcmxNq7axyZy+Nm2Cehr3yBONC1PFixScLHbYPBeMODhbGYz94EZbLG9bi/PyFBb4DXHiKzlk4KSgpXgQKPpRElziCbaPwZZ0eYcPHhjKU4t7ki7NTv2QXUMg+uvuVVj2mpjR12ynbbKlI42hPG1amEWBe3Rc6fxqnnBuRryLZ7DanpknvWKyQq7KZGHrFziZ0A7CURz1gOdxwlCAq/Fp1gj10jM0ZI+yhwTFrxBP2WtquKWADHF0pFnSVuJJRysPTvisRaS57wviVYBtBrtFbfaLpFs+pCebbO5+GQgopZVZH39sIgcGHcpxEMst0BwrnPfH3DQlbjVgkZQf6BbeJC5aA/kDU5RdSbQ2563BpdLEDDCwoiU95nKpMm8O3U210GQ0x/xWEaC1t2d9S6FUElTUJRXYVMePvgrZ2vFj9ya6o6nKUkxEp2iIdKgurDx0EMHvv5OtLFXNuWYWHSJ7s3DOrV66qQtXhqzUIlF4GXDUaJfgsmQ941M7yAj/tbn0GPad0ClEvVwnnpjg4Jhgf5vZBh/SpnMkhbkTHB+4j8kOWELwVsfCStSkFFtp1cUmER9EhjK8cJbw/aJU59fFfd2WGCzULHfA21DKrWzIl388kk/xqwT7Q9iOvcSR7ZstMtGTQXnxCX/Wp8Toj64H3dlGjzLhFx6uBNwXT114Rxl8efKuoUg7tdw1qWm9JeP/vMQzU9KwfyHLK6gCAIfZJgyY+rur7F+eSOEIDyidFrK3SVLQ7OYGFeWhTMKMGw7ZWenL/qX7APQ+vGh2jP52U7elOKx/TlNFyPrG/aYP3t04SueYRGvEp+zfdUM1nf/7v/DxssURKosAGGkRpo0KCsTSB8S8qu9M+07b0RDEWj/PtukegoEDu+6xk3tZdjrZVM21eDCh8q0OGm/Jx0HMeePqHco3xGS1JX1otAZwPHZiI2iccZK+WmJLLZIrXK4lHo/wYiB+NyIpd2VwgSuvnkxaNQyvlmukRi2BO35dGC5QZcUywiBfThK7sD/B22G46eQSGy7jy9IJbZ1xM+5Gquq97O8+V9R+xG2umY7H+Xot6PZF5OOHDFb6pETI8l42Ct5vlII2dfYqjedzXp/oWkuqnoaPz3gQN0KbFh9lk6oUuI1iLhpC1lHGo7zo1Wq441eQogKwaXSCplP414Qn8tQ4zW/E7cghKnzV185+iGupqNshY0eKUmK0vFLwvG+vw=="
},
}
```
Expand All @@ -85,11 +85,11 @@
| ---------------------------- | ------------ | ------------------------------------------------------------------------------------------------------- |
| `KEY_MODE_CONFIG_ROOT_KEY` | 1 | The symmetric wrapping (root) key is stored with the platform configuration and the wrapped KAS key is stored in the platform database.|
| `KEY_MODE_PROVIDER_ROOT_KEY` | 2 | The symmetric wrapping (root) key is stored external to the platform using a KMS or HSM interface. The wrapped KAS key is stored in the platform's database.|
| `KEY_MODE_REMOTE` | 3 | Both the symmetric wrapping (root) key and the wrapped KAS key are stored external to the platform using a KMS or HSM interface. This is also referred to as `STRICT_MODE`.|
| `KEY_MODE_REMOTE` | 3 | The private portion of the asymmetric key is stored external to the platform using a KMS or HSM interface. This is also referred to as `STRICT_MODE`. No symmetric (root) key is required here since the platform is not storing any sensitive key material. |
| `KEY_MODE_PUBLIC_KEY_ONLY` | 4 | No private key information is stored. This is used when importing another org's policy information.|

- The **public_key_ctx** holds the public key for the asymmetric key pair. (Required)
- The **private_key_ctx** holds the encrypted private key and a **key_id** specific to the symmetric key that is wrapping that key.
- The **private_key_ctx** holds the encrypted private key and a **key_id** specific to the symmetric key that is wrapping the private key. For keys of mode **KEY_MODE_REMOTE**, the **key_id** within private_key_ctx is used for identifying the remote private key. Our [key managers](./key_managers.md) use the **key_id** field present within the private_key_ctx when making requests to your external KMS/HSM instead of the **key_id** field at the root of the object. We do this to allow for larger key identifiers, which might be necessary for external providers. (Ex: arns with AWS)

Check failure on line 92 in docs/components/policy/keymanagement/quickstart.md

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'private_key_ctx'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'private_key_ctx'?", "location": {"path": "docs/components/policy/keymanagement/quickstart.md", "range": {"start": {"line": 92, "column": 346}}}, "severity": "ERROR"}

Check failure on line 92 in docs/components/policy/keymanagement/quickstart.md

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'key_id'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'key_id'?", "location": {"path": "docs/components/policy/keymanagement/quickstart.md", "range": {"start": {"line": 92, "column": 312}}}, "severity": "ERROR"}

Check failure on line 92 in docs/components/policy/keymanagement/quickstart.md

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'private_key_ctx'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'private_key_ctx'?", "location": {"path": "docs/components/policy/keymanagement/quickstart.md", "range": {"start": {"line": 92, "column": 200}}}, "severity": "ERROR"}

Check failure on line 92 in docs/components/policy/keymanagement/quickstart.md

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'key_id'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'key_id'?", "location": {"path": "docs/components/policy/keymanagement/quickstart.md", "range": {"start": {"line": 92, "column": 184}}}, "severity": "ERROR"}

Check failure on line 92 in docs/components/policy/keymanagement/quickstart.md

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'key_id'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'key_id'?", "location": {"path": "docs/components/policy/keymanagement/quickstart.md", "range": {"start": {"line": 92, "column": 67}}}, "severity": "ERROR"}

Check failure on line 92 in docs/components/policy/keymanagement/quickstart.md

View workflow job for this annotation

GitHub Actions / Vale 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'private_key_ctx'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'private_key_ctx'?", "location": {"path": "docs/components/policy/keymanagement/quickstart.md", "range": {"start": {"line": 92, "column": 9}}}, "severity": "ERROR"}

:::important
Wrapped_Key is only required for KEY_MODE_CONFIG_ROOT_KEY and KEY_MODE_PROVIDER_ROOT_KEY.
Expand All @@ -100,7 +100,7 @@
You can also specify metadata for the key via a common metadata structure, but that is not covered here.
:::

The above JSON request covers registering a key where the asymmetric key pair will be stored within the platform's database, and the expected symmetric key that decrypts the private key will be stored within KAS. What if you want to only store a reference to a key and have that reference point to a key elsewhere? Say for a KMS, for example. That's where the key mode **KEY_MODE_REMOTE** is handy.
The above JSON request covers registering a key where the asymmetric key pair will be stored within the platform's database, and the expected symmetric key that decrypts the private key will be stored within KAS. What if you want to only store a reference to a key and have that reference point to a key elsewhere? Say for a KMS, for example. That's where **KEY_MODE_REMOTE** is handy.

```json5
{
Expand All @@ -112,15 +112,15 @@
"pem": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUMvVENDQWVXZ0F3SUJBZ0lVRjA5QWpIallJOENSekVGSmpjVEREY2lkZEgwd0RRWUpLb1pJaHZjTkFRRUwKQlFBd0RqRU1NQW9HQTFVRUF3d0RhMkZ6TUI0WERUSTBNRFV3TmpFeU1UQXhNbG9YRFRJMU1EVXdOakV5TVRBeApNbG93RGpFTU1Bb0dBMVVFQXd3RGEyRnpNSUlCSWpBTkJna3Foa2lHOXcwQkFRRUZBQU9DQVE4QU1JSUJDZ0tDCkFRRUFsVEI5eks3dzF1MG1mOWI5bmg4U3p0K0t5ZFdvbjUyUDVNY2k4Z1YremFQWjlmM0picllHVWZWWG16RmEKbVErTjBmTjZRaDhVOWlzbzFPZ3VHWDB1eTRwV1k3em1XTXFtRjVpSk9INENBdTVnV2Vuc3I5R2FXM1lmeEtWRgpWUnpKcUx0U3pBT3lvQ0lhNVErSTJUdmdNeEZjSFYwSGN4OXU5ekdYdDdKNUdlV1pTM3I2OUg4MGRGUjdGc0lRCk1hTDZRUHhmUWNWOVJidW9weUFwOE43TktiU3p4OEZUZEJYUWE4QnVxTXNvNlZyK0crZC9oeVp6YlpVc1pEUzQKZ3RtNnJCQlUraE8zMEN6WnBaZHBETVNPdjljNGNZUXlpdElwRjBrbVdQcE02YitKUzRyN2hGUU5kY1BWVXBWeAovVGowRUFNaWsrcHpZQUxyalRLZjlHcmJkd0lEQVFBQm8xTXdVVEFkQmdOVkhRNEVGZ1FVa2RTM0JuWHNnZUtSCnVNL0hCNW9sM3lacVRvMHdId1lEVlIwakJCZ3dGb0FVa2RTM0JuWHNnZUtSdU0vSEI1b2wzeVpxVG8wd0R3WUQKVlIwVEFRSC9CQVV3QXdFQi96QU5CZ2txaGtpRzl3MEJBUXNGQUFPQ0FRRUFTZXoxQVZhNVhHVXBrNUg4THpySQp4U0VzUnRHUitSV2NJdGxMZVVLc3NPTTNzY01mUEZ6SnQyTldwd0NwSTRiY2FGQVgzeFlLR1lxVnZzVmpxbTFVCnRKYmh6dzFhUVBUT2ZvNDZlOXNGK2lxZGJpbEplRUlQZllDb0w2VXR0Rm96TC9LZ2k1eWFlSXBScTFiaHFwVjcKTVRmSm1CbHVIckZhdWNFaEFMTDJoK0tsQ1R6amJsQnBZN1hpVFZHc3JZc0V2MmF3NEh2b1pZVkZVV3IxQ1JXYgppcDB4dFZ1SXE5RFhha0ZJYWVQWlZnMHRCczVBejBzUGlpNUdUVjUzVXdmcjY4VjhBYXFRSE9yVGRQL2ZadkN3CmRXTWdKSnltc21VUis1cTJCTnJvZHlTWDd4RzZxenE0Mm5BV1ZwSlNvb0g5ZWdSYXZuZ0Q5UXRreWU5KzBuRW0KVGc9PQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg=="
},
"private_key_ctx": {
"key_id": "aws-wrapping-key-1",
"key_id": "arn:aws:kms:REGION:ACCOUNT-ID:key/KEY-ID",
},
"provider_config_id": "948e8167-6f32-4eee-89b7-f0cd42ce70ea"
}
```

The above is a valid request for registering a key with platform where the private key, and symmetric key that wraps the private key, is stored outside of the platform. The difference between the two requests is:
The above is a valid request for registering a key with the platform where the private key is stored externally from the platform. The difference between the two requests is:

- The **wrapped_key** should not be within the **private_key_ctx**, in addition a provider configuration has been registered with the system. See details on [provider configuration](./key_managers.md#provider-configurations). In small detail, adding a provider configuration reference to a key tells KAS what [manager](./key_managers.md) should be used to complete a rewrap operation.
- The **wrapped_key** should not be within the **private_key_ctx**, in addition a provider configuration has been registered with the system. See details on [provider configuration](./key_managers.md#provider-configurations). In small detail, adding a provider configuration reference to a key tells KAS what [key manager](./key_managers.md) should be used to complete a rewrap operation.

## Assigning Key Mappings (Optional, but recommended)

Expand All @@ -133,4 +133,4 @@
## Important additional comments

1. As of version 0.7.0 of the OpenTDF platform, there is no way to delete a key. If you would like to deactivate a key, use the **RotateKey** rpc.
2. When creating a key of mode **KEY_MODE_CONFIG_ROOT_KE** the **wrapped_key** is expected to be base64 encoded.
2. When creating a key of mode **KEY_MODE_CONFIG_ROOT_KEY** the **wrapped_key** is expected to be base64 encoded.
Comment thread
c-r33d marked this conversation as resolved.
Loading