diff --git a/.github/spellcheck.ignore b/.github/spellcheck.ignore index 47e4d2b9..a059f799 100644 --- a/.github/spellcheck.ignore +++ b/.github/spellcheck.ignore @@ -8,6 +8,8 @@ CoolTool Decrypt ERS FQNs +FQN +FQN'd Hostname JSON JWT @@ -15,16 +17,22 @@ KASes KASs LDAP MacOS +mapping's NPM Namespace +namespace's Nano OIDC OpenTDF +OpenID PDP PKCE +plaintext +pluggability README RadService SCS +SCSs SDK ShinyThing TDF diff --git a/docs/man/inspect/_index.md b/docs/man/inspect/_index.md index 319dc83d..d9c36313 100644 --- a/docs/man/inspect/_index.md +++ b/docs/man/inspect/_index.md @@ -4,3 +4,9 @@ command: name: inspect [file] flags: --- + +# Inspect a TDF file + +Prints the `manifest.json` of the specified TDF for inspection. + +This is useful for development and administration. diff --git a/docs/man/policy/_index.md b/docs/man/policy/_index.md index bbe65c09..ba6b0377 100644 --- a/docs/man/policy/_index.md +++ b/docs/man/policy/_index.md @@ -12,7 +12,7 @@ command: default: 'false' --- -Manage policies within the platform. +# Manage platform policy Policy is a set of rules that are enforced by the platform. Specific to the the data-centric security, policy revolves around data attributes (referred to as attributes). Within the context diff --git a/docs/man/policy/attributes/_index.md b/docs/man/policy/attributes/_index.md index 600ee798..838ebc13 100644 --- a/docs/man/policy/attributes/_index.md +++ b/docs/man/policy/attributes/_index.md @@ -7,6 +7,8 @@ command: - attribute --- +# Manage attributes + Commands to manage attributes within the platform. Attributes are used to to define the properties of a piece of data. These attributes will then be diff --git a/docs/man/policy/attributes/create.md b/docs/man/policy/attributes/create.md index bf3d73fa..32f3a1ca 100644 --- a/docs/man/policy/attributes/create.md +++ b/docs/man/policy/attributes/create.md @@ -32,3 +32,26 @@ command: shorthand: l default: '' --- + +# Create an attribute definition + +Under a namespace, create an attribute with a rule. + +### Rules + +#### ANY_OF + +If an Attribute is defined with logical rule `ANY_OF`, an Entity who is mapped to `any` of the associated Values of the Attribute +on TDF'd Resource Data will be Entitled. + +#### ALL_OF + +If an Attribute is defined with logical rule `ALL_OF`, an Entity must be mapped to `all` of the associated Values of the Attribute +on TDF'd Resource Data to be Entitled. + +### HIERARCHY + +If an Attribute is defined with logical rule `HIERARCHY`, an Entity must be mapped to the same level Value or a level above in hierarchy +compared to a given Value on TDF'd Resource Data. Hierarchical values are considered highest at index 0 and lowest at the last index. + +For more general information about attributes, see the `attributes` subcommand. diff --git a/docs/man/policy/attributes/deactivate.md b/docs/man/policy/attributes/deactivate.md index 0872f066..df8ac65e 100644 --- a/docs/man/policy/attributes/deactivate.md +++ b/docs/man/policy/attributes/deactivate.md @@ -8,3 +8,14 @@ command: description: ID of the attribute required: true --- + +# Deactivate an attribute definition + +Deactivation preserves uniqueness of the attribute and values underneath within policy and all existing relations, +essentially reserving them. + +However, a deactivation of an attribute means its associated values cannot be entitled in an access decision. + +For information about reactivation, see the `unsafe reactivate` subcommand. + +For more general information about attributes, see the `attributes` subcommand. diff --git a/docs/man/policy/attributes/get.md b/docs/man/policy/attributes/get.md index 3c4691b6..b9e92045 100644 --- a/docs/man/policy/attributes/get.md +++ b/docs/man/policy/attributes/get.md @@ -9,3 +9,9 @@ command: shorthand: i description: ID of the attribute --- + +# Get an attribute + +Retrieve an attribute along with its metadata, rule, and values. + +For more general information about attributes, see the `attributes` subcommand. diff --git a/docs/man/policy/attributes/list.md b/docs/man/policy/attributes/list.md index 3fe2bd0e..4843849e 100644 --- a/docs/man/policy/attributes/list.md +++ b/docs/man/policy/attributes/list.md @@ -14,3 +14,9 @@ command: - any default: active --- + +# List the known attributes + +By default, the list will only provide `active` attributes if unspecified, but the filter can be controlled with the `--state` flag. + +For more general information about attributes, see the `attributes` subcommand. diff --git a/docs/man/policy/attributes/namespaces/_index.md b/docs/man/policy/attributes/namespaces/_index.md index 31225b00..af378294 100644 --- a/docs/man/policy/attributes/namespaces/_index.md +++ b/docs/man/policy/attributes/namespaces/_index.md @@ -1,6 +1,6 @@ --- title: Manage attribute namespaces -command: +command: name: namespaces aliases: - ns @@ -8,3 +8,13 @@ command: --- # Manage attribute namespaces + +A namespace is the root (parent) of a set of platform policy. Like an owner or an authority, it fully qualifies attributes and their values, +resource mapping groups, etc. As the various mappings of a platform are to attributes or values, a namespace effectively "owns" the +mappings as well (transitively if not directly). + +In an attribute or other FQN (Fully Qualified Name), the namespace is found after the scheme: `https://` + +Namespaces, like other FQN'd objects, are normalized to lower case both on create and in a decision request lookup. + +As the Namespace is the parent of policy, a namespace's existence is required to create attributes or resource mapping groups beneath. diff --git a/docs/man/policy/attributes/namespaces/create.md b/docs/man/policy/attributes/namespaces/create.md index 0be7f0a0..3e10845e 100644 --- a/docs/man/policy/attributes/namespaces/create.md +++ b/docs/man/policy/attributes/namespaces/create.md @@ -14,5 +14,11 @@ command: - name: label description: "Optional metadata 'labels' in the format: key=value" shorthand: l - default: "" + default: '' --- + +# Create an attribute namespace + +Creation of a `namespace` is required to add attributes or any other policy objects beneath. + +For more information, see the `namespaces` subcommand. diff --git a/docs/man/policy/attributes/namespaces/deactivate.md b/docs/man/policy/attributes/namespaces/deactivate.md index decdd0b1..b6237395 100644 --- a/docs/man/policy/attributes/namespaces/deactivate.md +++ b/docs/man/policy/attributes/namespaces/deactivate.md @@ -11,6 +11,8 @@ command: description: Force deletion without interactive confirmation (dangerous) --- +# Deactivate an attribute namespace + Deactivating an Attribute Namespace will make the namespace name inactive as well as any attribute definitions and values beneath. Deactivation of a Namespace renders any existing TDFs of those attributes inaccessible. @@ -18,4 +20,6 @@ Deactivation of a Namespace renders any existing TDFs of those attributes inacce Deactivation will permanently reserve the Namespace name within a platform. Reactivation and deletion are both considered "unsafe" behaviors. +For information about reactivation, see the `unsafe reactivate` subcommand. + For reactivation, see the `unsafe` command. diff --git a/docs/man/policy/attributes/namespaces/get.md b/docs/man/policy/attributes/namespaces/get.md index ea0ad568..39a577b0 100644 --- a/docs/man/policy/attributes/namespaces/get.md +++ b/docs/man/policy/attributes/namespaces/get.md @@ -11,3 +11,4 @@ command: --- # Get an attribute namespace + diff --git a/docs/man/policy/attributes/namespaces/list.md b/docs/man/policy/attributes/namespaces/list.md index cdf78d87..a40250cf 100644 --- a/docs/man/policy/attributes/namespaces/list.md +++ b/docs/man/policy/attributes/namespaces/list.md @@ -12,3 +12,5 @@ command: --- # List attribute namespaces + +For more general information, see the `namespaces` subcommand. diff --git a/docs/man/policy/attributes/namespaces/unsafe/_index.md b/docs/man/policy/attributes/namespaces/unsafe/_index.md index 5061a05c..f6b887ea 100644 --- a/docs/man/policy/attributes/namespaces/unsafe/_index.md +++ b/docs/man/policy/attributes/namespaces/unsafe/_index.md @@ -17,3 +17,5 @@ Depending on the unsafe change introduced and already existing TDFs, TDFs might accessible or vice versa. Make sure you know what you are doing. + +For more general information, see the `namespaces` subcommand. diff --git a/docs/man/policy/attributes/namespaces/unsafe/delete.md b/docs/man/policy/attributes/namespaces/unsafe/delete.md index 488082de..6a27deab 100644 --- a/docs/man/policy/attributes/namespaces/unsafe/delete.md +++ b/docs/man/policy/attributes/namespaces/unsafe/delete.md @@ -16,3 +16,5 @@ Deleting a Namespace cascades deletion of any Attribute Definitions, Values, and Any existing TDFs containing attributes under this namespace will be rendered inaccessible until it has been recreated. Make sure you know what you are doing. + +For more general information, see the `namespaces` subcommand. diff --git a/docs/man/policy/attributes/namespaces/unsafe/reactivate.md b/docs/man/policy/attributes/namespaces/unsafe/reactivate.md index ad28e8b6..f5ae353e 100644 --- a/docs/man/policy/attributes/namespaces/unsafe/reactivate.md +++ b/docs/man/policy/attributes/namespaces/unsafe/reactivate.md @@ -16,3 +16,5 @@ Reactivating a Namespace can potentially open up an access path to any existing The Active/Inactive state of any Attribute Definitions or Values under this Namespace will NOT be changed. Make sure you know what you are doing. + +For more general information, see the `namespaces` subcommand. diff --git a/docs/man/policy/attributes/namespaces/unsafe/update.md b/docs/man/policy/attributes/namespaces/unsafe/update.md index fe37c6ff..35da7611 100644 --- a/docs/man/policy/attributes/namespaces/unsafe/update.md +++ b/docs/man/policy/attributes/namespaces/unsafe/update.md @@ -21,3 +21,5 @@ Any existing TDFs containing attributes under the old namespace will be rendered and already created may now become accessible. Make sure you know what you are doing. + +For more general information, see the `namespaces` subcommand. diff --git a/docs/man/policy/attributes/namespaces/update.md b/docs/man/policy/attributes/namespaces/update.md index a57a705b..2bfdbf01 100644 --- a/docs/man/policy/attributes/namespaces/update.md +++ b/docs/man/policy/attributes/namespaces/update.md @@ -12,7 +12,7 @@ command: - name: label description: "Optional metadata 'labels' in the format: key=value" shorthand: l - default: "" + default: '' - name: force-replace-labels description: Destructively replace entire set of existing metadata 'labels' with any provided to this command default: false @@ -20,6 +20,6 @@ command: # Update an Attribute Namespace -Attribute Namespace changes can be dangerous, so this command is for updates considered "safe." +Attribute Namespace changes can be dangerous, so this command is for updates considered "safe" (currently just mutations to metadata `labels`). -For unsafe updates, see the dedicated `update` command. \ No newline at end of file +For unsafe updates, see the dedicated `unsafe update` command. For more general information, see the `namespaces` subcommand. diff --git a/docs/man/policy/attributes/unsafe/_index.md b/docs/man/policy/attributes/unsafe/_index.md index bbe63683..4ffad81a 100644 --- a/docs/man/policy/attributes/unsafe/_index.md +++ b/docs/man/policy/attributes/unsafe/_index.md @@ -17,3 +17,5 @@ Depending on the unsafe change introduced and already existing TDFs, TDFs might accessible or vice versa. Make sure you know what you are doing. + +For more general information about attributes, see the `attributes` subcommand. diff --git a/docs/man/policy/attributes/unsafe/delete.md b/docs/man/policy/attributes/unsafe/delete.md index c2ecf37a..4e2e4e4c 100644 --- a/docs/man/policy/attributes/unsafe/delete.md +++ b/docs/man/policy/attributes/unsafe/delete.md @@ -16,3 +16,5 @@ Deleting an Attribute Definition cascades deletion of any Attribute Values and a Any existing TDFs containing the deleted attribute of this name will be rendered inaccessible until it has been recreated. Make sure you know what you are doing. + +For more general information about attributes, see the `attributes` subcommand. diff --git a/docs/man/policy/attributes/unsafe/reactivate.md b/docs/man/policy/attributes/unsafe/reactivate.md index e1f69a8b..8a944f71 100644 --- a/docs/man/policy/attributes/unsafe/reactivate.md +++ b/docs/man/policy/attributes/unsafe/reactivate.md @@ -16,3 +16,5 @@ Reactivating an Attribute Definition can potentially open up an access path to a The Active/Inactive state of any Attribute Values under this Definition will NOT be changed. Make sure you know what you are doing. + +For more general information about attributes, see the `attributes` subcommand. diff --git a/docs/man/policy/attributes/unsafe/update.md b/docs/man/policy/attributes/unsafe/update.md index 10090ccd..17099c45 100644 --- a/docs/man/policy/attributes/unsafe/update.md +++ b/docs/man/policy/attributes/unsafe/update.md @@ -46,3 +46,5 @@ To remove Values from an Attribute Definition, delete them separately via the `v `values create` commands. Make sure you know what you are doing. + +For more general information about attributes, see the `attributes` subcommand. diff --git a/docs/man/policy/attributes/update.md b/docs/man/policy/attributes/update.md index 7dd5e407..e77b564a 100644 --- a/docs/man/policy/attributes/update.md +++ b/docs/man/policy/attributes/update.md @@ -17,3 +17,11 @@ command: description: Destructively replace entire set of existing metadata 'labels' with any provided to this command default: false --- + +# Update an attribute + +Attribute Definition changes can be dangerous, so this command is for updates considered "safe" (currently just mutations to metadata `labels`). + +For unsafe updates, see the dedicated `unsafe update` command. For more general information, see the `attributes` subcommand. + +For more general information about attributes, see the `attributes` subcommand. diff --git a/docs/man/policy/attributes/values/_index.md b/docs/man/policy/attributes/values/_index.md index b008a034..319b66d0 100644 --- a/docs/man/policy/attributes/values/_index.md +++ b/docs/man/policy/attributes/values/_index.md @@ -7,4 +7,25 @@ command: - value --- -This command allows you to manage the values of an attribute. +# Manage attribute values + +Attribute values are the individual units tagged on TDFs containing Resource Data. + +They are mapped to entitle person and non-person entities through Subject Mappings, to varied terms for tagging providers +through Resource Mappings, to individual keys and Key Access Servers through KAS Grants, and more. + +They are fully-qualified through the FQN structure `https:///attr//value/`, and the presence +of one or more values on a piece of Resource Data (a TDF) determines an entity's access to the data through a combination +of entitlements and the attribute definition rule evaluation. + +In other words, Attribute Values are the atomic units that drive access control relation of Data -> Entities and vice versa. + +Values are contextualized by Attribute Definitions within Namespaces, and only have logical meaning as part of a Definition. + +Giving data multiple Attribute Values across the same or multiple Definitions/Namespaces will require all of the definition rules to be satisfied +by an Entity's mapped Entitlements to result in key release, decryption, and resulting access to TDF'd data. + +For more information on: +- values, see the `attributes values` subcommand +- attribute definitions, see the `attributes` subcommand +- namespaces, see the `attributes namespaces` subcommand \ No newline at end of file diff --git a/docs/man/policy/attributes/values/create.md b/docs/man/policy/attributes/values/create.md index 9f4c5f84..22aea852 100644 --- a/docs/man/policy/attributes/values/create.md +++ b/docs/man/policy/attributes/values/create.md @@ -16,7 +16,13 @@ command: - name: label description: "Optional metadata 'labels' in the format: key=value" shorthand: l - default: "" + default: '' --- -This command allows you to manage the values of an attribute. +# Create an attribute value + +Add a single new value underneath an existing attribute. + +For a hierarchical attribute, a new value is added in lowest hierarchy (last). + +For more information on attribute values, see the `values` subcommand. diff --git a/docs/man/policy/attributes/values/deactivate.md b/docs/man/policy/attributes/values/deactivate.md index c29136f1..cf4a0589 100644 --- a/docs/man/policy/attributes/values/deactivate.md +++ b/docs/man/policy/attributes/values/deactivate.md @@ -7,3 +7,13 @@ command: shorthand: i description: The ID of the attribute value to deactivate --- + +# Deactivate an attribute value + +Deactivation preserves uniqueness of the attribute value within policy and all existing relations, essentially reserving it. + +However, a deactivation of an attribute value means it cannot be entitled in an access decision. + +For information about reactivation, see the `unsafe reactivate` subcommand. + +For more information on attribute values, see the `values` subcommand. diff --git a/docs/man/policy/attributes/values/get.md b/docs/man/policy/attributes/values/get.md index 04632231..13653637 100644 --- a/docs/man/policy/attributes/values/get.md +++ b/docs/man/policy/attributes/values/get.md @@ -9,3 +9,9 @@ command: shorthand: i description: The ID of the attribute value to get --- + +# Get an attribute value + +Retrieve an attribute value along with its metadata. + +For more general information about attribute values, see the `values` subcommand. \ No newline at end of file diff --git a/docs/man/policy/attributes/values/list.md b/docs/man/policy/attributes/values/list.md index 803209d6..bf015b96 100644 --- a/docs/man/policy/attributes/values/list.md +++ b/docs/man/policy/attributes/values/list.md @@ -20,3 +20,7 @@ command: --- # List attribute values + +By default, the list will only provide `active` values if unspecified, but the filter can be controlled with the `--state` flag. + +For more general information about attribute values, see the `values` subcommand. diff --git a/docs/man/policy/attributes/values/unsafe/_index.md b/docs/man/policy/attributes/values/unsafe/_index.md index 524b5988..4da0a452 100644 --- a/docs/man/policy/attributes/values/unsafe/_index.md +++ b/docs/man/policy/attributes/values/unsafe/_index.md @@ -17,3 +17,5 @@ Depending on the unsafe change introduced and already existing TDFs, TDFs might accessible or vice versa. Make sure you know what you are doing. + +For more information on attribute values, see the `values` subcommand. diff --git a/docs/man/policy/attributes/values/unsafe/delete.md b/docs/man/policy/attributes/values/unsafe/delete.md index 8093072d..28572b62 100644 --- a/docs/man/policy/attributes/values/unsafe/delete.md +++ b/docs/man/policy/attributes/values/unsafe/delete.md @@ -16,3 +16,5 @@ Deleting an Attribute Value cascades deletion of any associated mappings underne Any existing TDFs containing the deleted attribute of this value will be rendered inaccessible until it has been recreated. Make sure you know what you are doing. + +For more information on attribute values, see the `values` subcommand. diff --git a/docs/man/policy/attributes/values/unsafe/reactivate.md b/docs/man/policy/attributes/values/unsafe/reactivate.md index cbc7caeb..67868726 100644 --- a/docs/man/policy/attributes/values/unsafe/reactivate.md +++ b/docs/man/policy/attributes/values/unsafe/reactivate.md @@ -16,3 +16,5 @@ Reactivating an Attribute Value can potentially open up an access path to any ex The Active/Inactive state of the Attribute Definition and Namespace above this Value will NOT be changed. Make sure you know what you are doing. + +For more information on attribute values, see the `values` subcommand. diff --git a/docs/man/policy/attributes/values/unsafe/update.md b/docs/man/policy/attributes/values/unsafe/update.md index 8eef51ba..4157a9c8 100644 --- a/docs/man/policy/attributes/values/unsafe/update.md +++ b/docs/man/policy/attributes/values/unsafe/update.md @@ -22,3 +22,5 @@ Any existing TDFs containing attributes under the old value will be rendered ina and already created may now become accessible. Make sure you know what you are doing. + +For more information on attribute values, see the `values` subcommand. diff --git a/docs/man/policy/attributes/values/update.md b/docs/man/policy/attributes/values/update.md index 8d7266b9..0ef6a621 100644 --- a/docs/man/policy/attributes/values/update.md +++ b/docs/man/policy/attributes/values/update.md @@ -9,9 +9,6 @@ command: - name: id shorthand: i description: The ID of the attribute value to update - - name: value - shorthand: v - description: The new value - name: label description: "Optional metadata 'labels' in the format: key=value" shorthand: l @@ -21,4 +18,10 @@ command: default: false --- -This command allows you to manage the values of an attribute. +# Update an attribute value + +Attribute Value changes can be dangerous, so this command is for updates considered "safe" (currently just mutations to metadata `labels`). + +For unsafe updates, see the dedicated `unsafe update` command. For more general information, see the `values` subcommand. + +For more general information about attributes, see the `attributes` subcommand. diff --git a/docs/man/policy/kas-grants/_index.md b/docs/man/policy/kas-grants/_index.md index ddceb10e..fa25e88f 100644 --- a/docs/man/policy/kas-grants/_index.md +++ b/docs/man/policy/kas-grants/_index.md @@ -52,7 +52,7 @@ Grants to Attribute Objects: | no | no | yes | value | | no | no | no | default KAS/platform key | -> Note: +> [!NOTE] > A namespace grant may soon be required with deprecation of a default KAS/platform key. ## Split Scenarios @@ -119,4 +119,4 @@ Attribute B: `https://conglomerate.com/attr/department/value/marketing` | - | Bob | - | Alice | AND | > [!NOTE] -> Any KAS Grants to attributes of different definitions or namespaces will be `AND` splits. +> Any KAS Grants to attributes across different definitions or namespaces will be `AND` splits. diff --git a/docs/man/policy/kas-grants/assign.md b/docs/man/policy/kas-grants/assign.md index 318ad36d..ba96d902 100644 --- a/docs/man/policy/kas-grants/assign.md +++ b/docs/man/policy/kas-grants/assign.md @@ -36,6 +36,8 @@ command: default: false --- +# Assign a grant to a KAS + Assign a registered Key Access Server (KAS) to an attribute namespace, definition, or value. For more information, see `kas-registry` and `kas-grants` manuals. \ No newline at end of file diff --git a/docs/man/policy/kas-grants/unassign.md b/docs/man/policy/kas-grants/unassign.md index 3af55453..ff3d388a 100644 --- a/docs/man/policy/kas-grants/unassign.md +++ b/docs/man/policy/kas-grants/unassign.md @@ -27,6 +27,8 @@ command: description: Force the unassignment with no confirmation --- -Unassign a registered Key Access Server (KAS) to an attribute definition or value. +# Unassign a grant to a KAS + +Unassign a registered Key Access Server (KAS) to an attribute namespace, definition, or value. For more information, see `kas-registry` and `kas-grants` manuals. diff --git a/docs/man/policy/kas-registry/_index.md b/docs/man/policy/kas-registry/_index.md index 170169a5..33aa4191 100644 --- a/docs/man/policy/kas-registry/_index.md +++ b/docs/man/policy/kas-registry/_index.md @@ -7,11 +7,14 @@ command: - kas-registries --- -The Key Access Server (KAS) registry is a record of KASs safeguarding access and maintaining public keys. +# Manage Key Access Servers registered to the platform + +The Key Access Server (KAS) registry is a record of KASes safeguarding access and maintaining public keys. + The registry contains critical information like each server's uri, its public key (which can be -either cached or at a remote uri), and any metadata about the server. Key Access Servers grant keys -for specified Namespaces, Attributes, and their Values via Attribute Key Access Grants and Attribute Value Key -Access Grants. +either cached or at a remote uri), and any metadata about the server. + +Registered Key Access Servers may grant keys for specified Namespaces, Attributes, and their Values via KAS Grants. For more information about grants and how KASs are utilized once registered, see the manual for the `kas-grants` command. diff --git a/docs/man/policy/kas-registry/create.md b/docs/man/policy/kas-registry/create.md index 828d6db3..e86257db 100644 --- a/docs/man/policy/kas-registry/create.md +++ b/docs/man/policy/kas-registry/create.md @@ -23,7 +23,7 @@ command: default: '' --- -For more information about registration of Key Access Servers, see the manual for `kas-registry`. +# Create a KAS registration Public keys can be stored as either `remote` or `cached` under the following JSON structure. @@ -68,3 +68,5 @@ The JSON value passed to the `--public-keys` flag stores the set of public keys ### Local Deprecated. + +For more information about registration of Key Access Servers, see the manual for `kas-registry`. diff --git a/docs/man/policy/kas-registry/delete.md b/docs/man/policy/kas-registry/delete.md index 27b2d836..81fc9bd8 100644 --- a/docs/man/policy/kas-registry/delete.md +++ b/docs/man/policy/kas-registry/delete.md @@ -10,3 +10,15 @@ command: - name: force description: Force deletion without interactive confirmation (dangerous) --- + +# Delete a registered KAS + +Removes knowledge of a KAS (registration) from a platform's policy. + +If resource data has been TDFd utilizing key splits from the registered KAS, deletion from +the registry (and therefore any associated grants) may prevent decryption depending on the +type of grants and relevant key splits. + +Make sure you know what you are doing. + +For more information about registration of Key Access Servers, see the manual for `kas-registry`. diff --git a/docs/man/policy/kas-registry/get.md b/docs/man/policy/kas-registry/get.md index c93ac795..6b99b291 100644 --- a/docs/man/policy/kas-registry/get.md +++ b/docs/man/policy/kas-registry/get.md @@ -1,5 +1,5 @@ --- -title: Get a Key Access Server registration +title: Get a registered Key Access Server command: name: get aliases: @@ -10,3 +10,7 @@ command: description: ID of the Key Access Server registration required: true --- + +# Get a registered Key Access Server + +For more information about registration of Key Access Servers, see the manual for `kas-registry`. diff --git a/docs/man/policy/kas-registry/list.md b/docs/man/policy/kas-registry/list.md index 9b76992c..70f11723 100644 --- a/docs/man/policy/kas-registry/list.md +++ b/docs/man/policy/kas-registry/list.md @@ -5,3 +5,7 @@ command: aliases: - l --- + +# List KASes registered within a platform + +For more information about registration of Key Access Servers, see the manual for `kas-registry`. diff --git a/docs/man/policy/kas-registry/update.md b/docs/man/policy/kas-registry/update.md index 3770879c..c3fd3956 100644 --- a/docs/man/policy/kas-registry/update.md +++ b/docs/man/policy/kas-registry/update.md @@ -26,3 +26,15 @@ command: description: Destructively replace entire set of existing metadata 'labels' with any provided to this command default: false --- + +# Update a registered KAS + +Update the `uri`, `metadata`, or key material (remote/cached) for a KAS registered to the platform. + +If resource data has been TDFd utilizing key splits from the registered KAS, deletion from +the registry (and therefore any associated grants) may prevent decryption depending on the +type of grants and relevant key splits. + +Make sure you know what you are doing. + +For more information about registration of Key Access Servers, see the manual for `kas-registry`. diff --git a/docs/man/policy/resource-mappings/create.md b/docs/man/policy/resource-mappings/create.md index 40e9f5f8..f56ee210 100644 --- a/docs/man/policy/resource-mappings/create.md +++ b/docs/man/policy/resource-mappings/create.md @@ -18,3 +18,9 @@ command: shorthand: l default: "" --- + +# Create a resource mapping + +Associate an attribute value with a set of plaintext string terms. + +For more information about resource mappings, see the `resource-mappings` subcommand. \ No newline at end of file diff --git a/docs/man/policy/resource-mappings/delete.md b/docs/man/policy/resource-mappings/delete.md index c094f792..f27b1c38 100644 --- a/docs/man/policy/resource-mappings/delete.md +++ b/docs/man/policy/resource-mappings/delete.md @@ -5,5 +5,9 @@ command: flags: - name: id description: The ID of the resource mapping to delete. - default: "" + default: '' --- + +# Delete a resource mapping + +For more information about resource mappings, see the `resource-mappings` subcommand. diff --git a/docs/man/policy/resource-mappings/get.md b/docs/man/policy/resource-mappings/get.md index 4bbbc771..d2afa3a1 100644 --- a/docs/man/policy/resource-mappings/get.md +++ b/docs/man/policy/resource-mappings/get.md @@ -9,3 +9,7 @@ command: description: The ID of the resource mapping to get. default: "" --- + +# Get a resource mapping + +For more information about resource mappings, see the `resource-mappings` subcommand. \ No newline at end of file diff --git a/docs/man/policy/resource-mappings/list.md b/docs/man/policy/resource-mappings/list.md index af56c972..3c90081f 100644 --- a/docs/man/policy/resource-mappings/list.md +++ b/docs/man/policy/resource-mappings/list.md @@ -5,3 +5,7 @@ command: aliases: - l --- + +# List resource mappings + +For more information about resource mappings, see the `resource-mappings` subcommand. diff --git a/docs/man/policy/resource-mappings/update.md b/docs/man/policy/resource-mappings/update.md index 76474a94..fb1e1f8d 100644 --- a/docs/man/policy/resource-mappings/update.md +++ b/docs/man/policy/resource-mappings/update.md @@ -22,3 +22,9 @@ command: description: Destructively replace entire set of existing metadata 'labels' with any provided to this command default: false --- + +# Update a resource mapping + +Alter the attribute value associated with a resource mapping's terms, or fully replace the terms in a given resource mapping. + +For more information about resource mappings, see the `resource-mappings` subcommand. \ No newline at end of file diff --git a/docs/man/policy/subject-condition-sets/_index.md b/docs/man/policy/subject-condition-sets/_index.md index ea354384..fd9d56bb 100644 --- a/docs/man/policy/subject-condition-sets/_index.md +++ b/docs/man/policy/subject-condition-sets/_index.md @@ -8,7 +8,9 @@ command: - subject-condition-set --- -Subject Condition Sets are the logical resolvers of entitlement to attributes. +# Manage subject condition sets + +Subject Condition Sets (SCSs) are the logical resolvers of entitlement to attributes. An SCS contains AND/OR groups of conditions with IN/NOT_IN/CONTAINS logic to be applied against a Subject Entity Representation as either their OIDC Access Token claims or the platform's Entity diff --git a/docs/man/policy/subject-condition-sets/create.md b/docs/man/policy/subject-condition-sets/create.md index 410a32b9..814ec270 100644 --- a/docs/man/policy/subject-condition-sets/create.md +++ b/docs/man/policy/subject-condition-sets/create.md @@ -27,6 +27,8 @@ command: default: false --- +# Create a Subject Condition Set + ### Example Subject Condition Sets `--subject-sets` example input: @@ -92,3 +94,5 @@ This structure if their team name was "CoolTool" and they were entitled might lo If any condition in the group is not met (such as if `.org.name` were `marketing` instead), the condition set would not resolve to true, and the Subject would not be found to be entitled to the Attribute Value applicable to this Subject Condition Set via Subject Mapping between. + +For more information about subject condition sets, see the `subject-condition-sets` subcommand. \ No newline at end of file diff --git a/docs/man/policy/subject-condition-sets/delete.md b/docs/man/policy/subject-condition-sets/delete.md index 55e34417..d5a9f1e1 100644 --- a/docs/man/policy/subject-condition-sets/delete.md +++ b/docs/man/policy/subject-condition-sets/delete.md @@ -9,3 +9,7 @@ command: shorthand: i required: true --- + +# Delete a subject condition set + +For more information about subject condition sets, see the `subject-condition-sets` subcommand. \ No newline at end of file diff --git a/docs/man/policy/subject-condition-sets/get.md b/docs/man/policy/subject-condition-sets/get.md index 91c9e89a..5e510bf5 100644 --- a/docs/man/policy/subject-condition-sets/get.md +++ b/docs/man/policy/subject-condition-sets/get.md @@ -11,3 +11,7 @@ command: shorthand: i required: true --- + +# Get a subject condition set + +For more information about subject condition sets, see the `subject-condition-sets` subcommand. \ No newline at end of file diff --git a/docs/man/policy/subject-condition-sets/list.md b/docs/man/policy/subject-condition-sets/list.md index 1c366e36..99e19d58 100644 --- a/docs/man/policy/subject-condition-sets/list.md +++ b/docs/man/policy/subject-condition-sets/list.md @@ -6,3 +6,7 @@ command: aliases: - l --- + +# List subject condition sets + +For more information about subject condition sets, see the `subject-condition-sets` subcommand. \ No newline at end of file diff --git a/docs/man/policy/subject-condition-sets/update.md b/docs/man/policy/subject-condition-sets/update.md index 30e5d7c8..2bce68dc 100644 --- a/docs/man/policy/subject-condition-sets/update.md +++ b/docs/man/policy/subject-condition-sets/update.md @@ -13,7 +13,7 @@ command: - name: subject-sets description: A JSON array of subject sets, containing a list of condition groups, each with one or more conditions shorthand: s - default: "" + default: '' - name: subject-sets-file-json description: A JSON file with path from the current working directory containing an array of subject sets shorthand: j @@ -22,8 +22,14 @@ command: - name: label description: "Optional metadata 'labels' in the format: key=value" shorthand: l - default: "" + default: '' - name: force-replace-labels description: Destructively replace entire set of existing metadata 'labels' with any provided to this command default: false --- + +# Update a subject condition set + +Replace the existing conditional logic within an SCS with new conditional logic, passing either JSON directly or a JSON file. + +For more information about subject condition sets, see the `subject-condition-sets` subcommand. diff --git a/docs/man/policy/subject-mappings/_index.md b/docs/man/policy/subject-mappings/_index.md index 3ae092dc..fda40ffc 100644 --- a/docs/man/policy/subject-mappings/_index.md +++ b/docs/man/policy/subject-mappings/_index.md @@ -9,5 +9,13 @@ command: - subject-mapping --- +# Manage subject mappings + +As data is bound to fully qualified Attribute Values when encrypted within a TDF, Entities are entitled to Attribute Values through a mechanism called Subject Mappings. + A Subject Mapping (SM) is the relation of a Subject Condition Set (SCS, see `subject-condition-sets` command) -to an Attribute Value to determine a Subject's Entitlement. +to an Attribute Value to determine a Subject's Entitlement to an Attribute Value. + +Entities (Subjects, Users, Machines, etc.) are defined by a representation (Entity Representation) of their identity from an identity provider (idP). +The OpenTDF Platform is not itself an idP, and it utilizes the OpenID Connect (OIDC) protocol as well as idP pluggability to rely upon an Entity store +of truth outside the platform to represent Entity identities. diff --git a/docs/man/policy/subject-mappings/create.md b/docs/man/policy/subject-mappings/create.md index 3c5bf36a..656e81ac 100644 --- a/docs/man/policy/subject-mappings/create.md +++ b/docs/man/policy/subject-mappings/create.md @@ -38,3 +38,11 @@ command: shorthand: l default: '' --- + +# Create a subject mapping + +Create a Subject Mapping to entitle an entity (via existing or new Subject Condition Set) to an Attribute Value. + +For more information about subject mappings, see the `subject-mappings` subcommand. + +For more information about subject condition sets, see the `subject-condition-sets` subcommand. diff --git a/docs/man/policy/subject-mappings/delete.md b/docs/man/policy/subject-mappings/delete.md index 081075b2..21252bd9 100644 --- a/docs/man/policy/subject-mappings/delete.md +++ b/docs/man/policy/subject-mappings/delete.md @@ -7,5 +7,13 @@ command: description: The ID of the subject mapping to delete shorthand: i required: true - default: "" ---- \ No newline at end of file + default: '' +--- + +# Delete a subject mapping + +Delete a Subject Mapping to remove entitlement of an entity (via Subject Condition Set) to an Attribute Value. + +For more information about subject mappings, see the `subject-mappings` subcommand. + +For more information about subject condition sets, see the `subject-condition-sets` subcommand. \ No newline at end of file diff --git a/docs/man/policy/subject-mappings/get.md b/docs/man/policy/subject-mappings/get.md index eedb8c1e..5271bab8 100644 --- a/docs/man/policy/subject-mappings/get.md +++ b/docs/man/policy/subject-mappings/get.md @@ -10,4 +10,10 @@ command: shorthand: i required: true default: "" ---- \ No newline at end of file +--- + +# Get a subject mapping + +Retrieve the specifics of a Subject Mapping. + +For more information about subject mappings, see the `subject-mappings` subcommand. \ No newline at end of file diff --git a/docs/man/policy/subject-mappings/list.md b/docs/man/policy/subject-mappings/list.md index 60117991..da2436de 100644 --- a/docs/man/policy/subject-mappings/list.md +++ b/docs/man/policy/subject-mappings/list.md @@ -4,4 +4,8 @@ command: name: list aliases: - l ---- \ No newline at end of file +--- + +# List subject mappings + +For more information about subject mappings, see the `subject-mappings` subcommand. diff --git a/docs/man/policy/subject-mappings/update.md b/docs/man/policy/subject-mappings/update.md index d42b51b1..4bb324b1 100644 --- a/docs/man/policy/subject-mappings/update.md +++ b/docs/man/policy/subject-mappings/update.md @@ -35,4 +35,14 @@ command: default: false --- -'Actions' are updated in place, destructively replacing the current set. If you want to add or remove actions, you must provide the full set of actions on update. +# Update a subject mapping + +Update a Subject Mapping to alter entitlement of an entity to an Attribute Value. + +`Actions` are updated in place, destructively replacing the current set. If you want to add or remove actions, you must provide the full set of actions on update. + +At this time, creation of a new SCS during update of a subject mapping is not supported. + +For more information about subject mappings, see the `subject-mappings` subcommand. + +For more information about subject condition sets, see the `subject-condition-sets` subcommand.