You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
1.) Update documentation around key management. Removing the idea that a
root key is needed with keys of mode **remote**.
---------
Co-authored-by: Jp Ayyappan <108297634+jp-ayyappan@users.noreply.github.com>
Copy file name to clipboardExpand all lines: docs/components/policy/keymanagement/quickstart.md
+13-13Lines changed: 13 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -29,7 +29,7 @@ be helpful for migrations.
29
29
30
30
## Key management is activated for KAS
31
31
32
-
- 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).
32
+
- 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).
33
33
- You will also need to set a root key to be used with the basic manager. The root key should be 32 bytes long.
34
34
- In addition, the root key should be hex encoded.
35
35
@@ -39,15 +39,15 @@ be helpful for migrations.
39
39
You can also perform all key commands with the [OpenTDF CLI](https://github.com/opentdf/otdfctl)
40
40
:::
41
41
42
-
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).
43
-
2. Once you have a **Key Access Server** registered you will then want to create a key for that registered KAS.
42
+
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).
43
+
2. Once you have a **Key Access Server** registered you should then create a key for that registered KAS.
44
44
45
-
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).
45
+
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).
46
46
47
47
Let's look at a valid request and dissect it:
48
48
49
49
:::note
50
-
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
50
+
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
|`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.|
87
87
|`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.|
88
-
|`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`.|
88
+
|`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. |
89
89
|`KEY_MODE_PUBLIC_KEY_ONLY`| 4 | No private key information is stored. This is used when importing another org's policy information.|
90
90
91
91
- The **public_key_ctx** holds the public key for the asymmetric key pair. (Required)
92
-
- The **private_key_ctx** holds the encrypted private key and a **key_id** specific to the symmetric key that is wrapping that key.
92
+
- 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)
93
93
94
94
:::important
95
95
Wrapped_Key is only required for KEY_MODE_CONFIG_ROOT_KEY and KEY_MODE_PROVIDER_ROOT_KEY.
@@ -100,7 +100,7 @@ Key_Id is required for all key modes except KEY_MODE_PUBLIC_KEY_ONLY
100
100
You can also specify metadata for the key via a common metadata structure, but that is not covered here.
101
101
:::
102
102
103
-
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.
103
+
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.
104
104
105
105
```json5
106
106
{
@@ -112,15 +112,15 @@ The above JSON request covers registering a key where the asymmetric key pair wi
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:
121
+
The above is a valid request for registering a key with the platform where the private keyis stored externally from the platform. The difference between the two requests is:
122
122
123
-
- 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.
123
+
- 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.
124
124
125
125
## Assigning Key Mappings (Optional, but recommended)
126
126
@@ -133,4 +133,4 @@ Follow the [base key setup](./base_key.md) guide for setting a base key.
133
133
## Important additional comments
134
134
135
135
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.
136
-
2. When creating a key of mode **KEY_MODE_CONFIG_ROOT_KE** the **wrapped_key** is expected to be base64 encoded.
136
+
2. When creating a key of mode **KEY_MODE_CONFIG_ROOT_KEY** the **wrapped_key** is expected to be base64 encoded.
0 commit comments