diff --git a/docs/man/policy/obligations/_index.md b/docs/man/policy/obligations/_index.md new file mode 100644 index 00000000..b3caf0d1 --- /dev/null +++ b/docs/man/policy/obligations/_index.md @@ -0,0 +1,71 @@ +--- +title: Manage obligations +command: + name: obligations +--- + +Commands to manage obligations within the platform. + +Obligations are requirements that should be fulfilled by a Subject or Environment requesting access to Resource data. Obligations +are distinct from Entitlements because they are a post-entitlement decision. + +For example, if a Subject user is entitled through a Subject Mapping to access data that is considered confidential intellectual +property, an obligation can be utilized to ensure the access path is through a PEP or flow that supports watermarking to enhance +security of the data post-decryption. It is a precondition of an obligation that a Subject requesting access must already be entitled. + +Obligations are represented as platform attributes. They can be either added to TDFs directly, or derived via mapping. + +**Example:** + +As a platform admin, Alice already has the hierarchical attribute `https://namespace.io/attr/card_suits` with high-to-low values `ace, king, queen, jack` +that are successfully entitled to various Subject users at each intended level of access. + +Alice wants to ensure data of the hierarchical attribute `https://namespace.io/attr/card_suits/value/queen` +is accessible to Subjects that are entitled to Queen or King data, but Alice wants an additional protection of `watermarking` when +the TDF'd data is decrypted. + +To add a `watermarking` assurance when a PEP handles decrypted TDF data a `digital rights management` , she can utilize obligations. + +**Option 1: Derived obligations** + +To dynamically tie all TDF data of that attribute value to this new obligation to watermark, she will create an obligation +mapped in platform policy to the `https://namespace.io/attr/card_suits/value/queen` attribute value: + +`policy obligations create --name drm --value watermarking` + +From this point forward, any time an access request is made on a TDF containing the `/attr/card_suits/value/queen` attribute value, the obligation +will be derived and considered in the decision. + +The same obligation can also be assigned multiple attribute values when derived, so `--attr` can take multiple attribute value IDs, and the +`assign` and `remove` subcommands exist on `obligations` as well to assign attribute values to already-created obligations. + +**Option 2: TDF-only obligations** + +To add this obligation to any TDF data without permanently associating every TDF containing an attribute value to the obligation (see derived above), +Alice can create the obligation without associating it to an attribute value: + +`policy obligations create --name drm --value watermarking` + +Without the derived assocation, the obligation can be added on TDF encrypt as any other attribute FQN. There is nothing stopping a PEP or admin from utilizing obligations in both manners in tandem as appropriate. + +**Evaluation: Fulfillment Conditions** + +In either scenario above, resolution of obligation satisfaction is similar to an `anyOf` rule on an attribute definition. If the obligation for `drm` contains +several values, and only one of them is `watermark`, a PEP or environmental entity that successfully meets the admin-defined obligation fulfillment conditions +for specifically that obligation or any of the other child values of the `drm` obligation parent for the data (derived via attributes or on the TDF) +would result in a permitted access decision. + +The fulfillment conditions of an obligation can be thought of as loosely similar to Condition Sets within Subject Mappings that drive entitlements. + +To allow access to data with obligations (derived by assignment to attribute values or directly added to a TDF), an admin must define the conditions +an entity must meet as provided by the Entity Resolution Service (ERS) or OIDC token claims if running the platform without an ERS. + +For example, if `drm:watermark` is a required obligation contextualizing a TDF access decision, a user must first be entitled to the data attributes via subject mappings, +but they must also meet the conditions that they're attempting to access through `Some_Cool_PEP`, which is known to the admin to support watermarking +as a feature and respect it as an obligation on decrypt. The admin should define through the `fulfillments` subcommand the conditions where the obligation +is fulfilled. In plain English, that would be: `if a user's access token indicates they are accessing through Some_Cool_PEP, the obligation has been fulfilled`. + +TODO: fulfillment conditions instruction here that comes from protos + +As you can see in the example above, the user's entity chain indicated they came through `Some_Cool_PEP` and therefore they were granted access alongside the obligation +for `Some_Cool_PEP` to receive in response and drive the watermarking behavior. diff --git a/docs/man/policy/obligations/create.md b/docs/man/policy/obligations/create.md new file mode 100644 index 00000000..3dd52ab7 --- /dev/null +++ b/docs/man/policy/obligations/create.md @@ -0,0 +1,23 @@ +--- +title: Create an obligation +command: + name: create + flags: + - name: name + shorthand: n + description: Name of the obligation (i.e. 'drm' for Digital Rights Management) + required: true + - name: value + shorthand: v + description: Values of the obligation (i.e. 'watermark') + required: false + - name: label + description: "Optional metadata 'labels' in the format: key=value" + shorthand: l + default: '' +--- + +An obligation, like an attribute definition, is a parent that can contain one or more values. + +For more information about the significance of obligations and how they are utilized for derived obligations on attribute values +or when added directly to a TDF, view the parent command documentation with `--help`. \ No newline at end of file diff --git a/docs/man/policy/obligations/delete.md b/docs/man/policy/obligations/delete.md new file mode 100644 index 00000000..283d180d --- /dev/null +++ b/docs/man/policy/obligations/delete.md @@ -0,0 +1,16 @@ +--- +title: Delete an obligation +command: + name: delete + flags: + - name: id + shorthand: i + description: ID of the obligation + required: true +--- + +Because obligations are a post-entitlement decision, they are safe to delete. Upon deletion, any derived obligations as a result of +mappings to platform policy attribute values will be removed, and any TDFs containing obligations within will remain accessible, just +without obligations returned along with an access request to drive PEP behavior. + +Upon deletion, all child values and the entity conditions to satisfy an obligation are cascadingly deleted. diff --git a/docs/man/policy/obligations/fulfillments/_index.md b/docs/man/policy/obligations/fulfillments/_index.md new file mode 100644 index 00000000..138c7ef3 --- /dev/null +++ b/docs/man/policy/obligations/fulfillments/_index.md @@ -0,0 +1,10 @@ +--- +title: Manage obligation fulfillments +command: + name: fulfillments +--- + +Commands to manage the conditions under which obligations on attributes are fulfilled by subject and environment entities. + +For more information about the significance of obligations and how they are utilized for derived obligations on attribute values +or when added directly to a TDF, view the parent command documentation with `--help`. diff --git a/docs/man/policy/obligations/fulfillments/create.md b/docs/man/policy/obligations/fulfillments/create.md new file mode 100644 index 00000000..a7eb3912 --- /dev/null +++ b/docs/man/policy/obligations/fulfillments/create.md @@ -0,0 +1,23 @@ +--- +title: Create an obligation fulfillment +command: + name: create + flags: + - name: conditions-json + description: TODO - Conditions as defined by the protos as JSON + required: false + - name: conditions-json-file + description: TODO - Conditions as defined by the protos from a JSON file + required: false + - name: obligation-scope + shorthand: s + description: Scope of the obligation as subject or environment [ SUBJECT, ENV ] + required: true + - name: label + description: "Optional metadata 'labels' in the format: key=value" + shorthand: l + default: '' +--- + +For more information about the significance of obligations and how they are utilized for derived obligations on attribute values +or when added directly to a TDF, see the parent command above. diff --git a/docs/man/policy/obligations/fulfillments/delete.md b/docs/man/policy/obligations/fulfillments/delete.md new file mode 100644 index 00000000..70258e89 --- /dev/null +++ b/docs/man/policy/obligations/fulfillments/delete.md @@ -0,0 +1,14 @@ +--- +title: Delete an obligation value +command: + name: delete + flags: + - name: id + shorthand: i + description: ID of the obligation value + required: true +--- + +Because obligations are a post-entitlement decision, they are safe to delete. Upon deletion, any derived obligations as a result of +mappings to platform policy attribute values will be removed, and any TDFs containing obligations within will remain accessible, just +without obligations returned along with an access request to drive PEP behavior. \ No newline at end of file diff --git a/docs/man/policy/obligations/fulfillments/get.md b/docs/man/policy/obligations/fulfillments/get.md new file mode 100644 index 00000000..4dc3d6c3 --- /dev/null +++ b/docs/man/policy/obligations/fulfillments/get.md @@ -0,0 +1,18 @@ +--- +title: Get an obligation value +command: + name: get + flags: + - name: id + shorthand: i + description: ID of the obligation value +--- + +Retrieves the obligation value, comprised of: + +- ID +- value +- parent obligation (name and ID) +- FQN +- any assigned attribute value FQNs and IDs for derived obligations +- condition sets for mappings to entities that satisfy the obligation diff --git a/docs/man/policy/obligations/fulfillments/list.md b/docs/man/policy/obligations/fulfillments/list.md new file mode 100644 index 00000000..af41ea24 --- /dev/null +++ b/docs/man/policy/obligations/fulfillments/list.md @@ -0,0 +1,19 @@ +--- +title: List obligation values +command: + name: list + flags: + - name: obligation-id + shorthand: o + description: The ID of the obligation to list values for + - name: state + shorthand: s + description: Filter by state + enum: + - active + - inactive + - any + default: active +--- + +Retrieves all obligation valuess stored in platform policy. diff --git a/docs/man/policy/obligations/fulfillments/update.md b/docs/man/policy/obligations/fulfillments/update.md new file mode 100644 index 00000000..f89d08c8 --- /dev/null +++ b/docs/man/policy/obligations/fulfillments/update.md @@ -0,0 +1,17 @@ +--- +title: Update an obligation value +command: + name: update + flags: + - name: id + shorthand: i + description: ID of the obligation value + required: true + - name: label + description: "Optional metadata 'labels' in the format: key=value" + shorthand: l + default: "" + - name: force-replace-labels + description: Destructively replace entire set of existing metadata 'labels' with any provided to this command + default: false +--- diff --git a/docs/man/policy/obligations/get.md b/docs/man/policy/obligations/get.md new file mode 100644 index 00000000..9304765f --- /dev/null +++ b/docs/man/policy/obligations/get.md @@ -0,0 +1,16 @@ +--- +title: Get an obligation +command: + name: get + flags: + - name: id + shorthand: i + description: ID of the obligation +--- + +Retrieves the obligation, comprised of: + +- ID +- name +- child values (values and IDs) +- FQN diff --git a/docs/man/policy/obligations/list.md b/docs/man/policy/obligations/list.md new file mode 100644 index 00000000..dc9f7a11 --- /dev/null +++ b/docs/man/policy/obligations/list.md @@ -0,0 +1,7 @@ +--- +title: List obligations +command: + name: list +--- + +Retrieves all obligations stored in platform policy. diff --git a/docs/man/policy/obligations/update.md b/docs/man/policy/obligations/update.md new file mode 100644 index 00000000..1b8ccfe3 --- /dev/null +++ b/docs/man/policy/obligations/update.md @@ -0,0 +1,17 @@ +--- +title: Update an attribute +command: + name: update + flags: + - name: id + shorthand: i + description: ID of the attribute + required: true + - name: label + description: "Optional metadata 'labels' in the format: key=value" + shorthand: l + default: "" + - name: force-replace-labels + description: Destructively replace entire set of existing metadata 'labels' with any provided to this command + default: false +--- diff --git a/docs/man/policy/obligations/values/_index.md b/docs/man/policy/obligations/values/_index.md new file mode 100644 index 00000000..0dca7187 --- /dev/null +++ b/docs/man/policy/obligations/values/_index.md @@ -0,0 +1,10 @@ +--- +title: Manage obligation values +command: + name: values +--- + +Commands to manage obligation values within an existing obligation. + +For more information about the significance of obligations and how they are utilized for derived obligations on attribute values +or when added directly to a TDF, view the parent command documentation with `--help`. diff --git a/docs/man/policy/obligations/values/assign.md b/docs/man/policy/obligations/values/assign.md new file mode 100644 index 00000000..e5b06c17 --- /dev/null +++ b/docs/man/policy/obligations/values/assign.md @@ -0,0 +1,18 @@ +--- +title: Assign an obligation value to an attribute value +command: + name: assign + flags: + - name: id + shorthand: i + description: ID of the obligation value + required: true + - name: attr-val + description: ID of the attribute value(s) being assigned for derived obligations + required: true +--- + +Assigns an existing obligation value to one or more attribute values for derived obligations in an access decision. + +For more information about the significance of obligations and how they are utilized for derived obligations on attribute values, +see the parent command. diff --git a/docs/man/policy/obligations/values/create.md b/docs/man/policy/obligations/values/create.md new file mode 100644 index 00000000..170c692d --- /dev/null +++ b/docs/man/policy/obligations/values/create.md @@ -0,0 +1,25 @@ +--- +title: Create an obligation value +command: + name: create + flags: + - name: value + shorthand: v + description: Value being added to the existing obligation (i.e. 'watermark') + required: true + - name: obligation + shorthand: o + description: ID of the parent obligation + required: true + - name: attr-val + shorthand: a + description: ID of assigned attribute value(s) for derived obligations + required: false + - name: label + description: "Optional metadata 'labels' in the format: key=value" + shorthand: l + default: '' +--- + +For more information about the significance of obligations and how they are utilized for derived obligations on attribute values +or when added directly to a TDF, see the parent command above. diff --git a/docs/man/policy/obligations/values/delete.md b/docs/man/policy/obligations/values/delete.md new file mode 100644 index 00000000..70258e89 --- /dev/null +++ b/docs/man/policy/obligations/values/delete.md @@ -0,0 +1,14 @@ +--- +title: Delete an obligation value +command: + name: delete + flags: + - name: id + shorthand: i + description: ID of the obligation value + required: true +--- + +Because obligations are a post-entitlement decision, they are safe to delete. Upon deletion, any derived obligations as a result of +mappings to platform policy attribute values will be removed, and any TDFs containing obligations within will remain accessible, just +without obligations returned along with an access request to drive PEP behavior. \ No newline at end of file diff --git a/docs/man/policy/obligations/values/get.md b/docs/man/policy/obligations/values/get.md new file mode 100644 index 00000000..4dc3d6c3 --- /dev/null +++ b/docs/man/policy/obligations/values/get.md @@ -0,0 +1,18 @@ +--- +title: Get an obligation value +command: + name: get + flags: + - name: id + shorthand: i + description: ID of the obligation value +--- + +Retrieves the obligation value, comprised of: + +- ID +- value +- parent obligation (name and ID) +- FQN +- any assigned attribute value FQNs and IDs for derived obligations +- condition sets for mappings to entities that satisfy the obligation diff --git a/docs/man/policy/obligations/values/list.md b/docs/man/policy/obligations/values/list.md new file mode 100644 index 00000000..af41ea24 --- /dev/null +++ b/docs/man/policy/obligations/values/list.md @@ -0,0 +1,19 @@ +--- +title: List obligation values +command: + name: list + flags: + - name: obligation-id + shorthand: o + description: The ID of the obligation to list values for + - name: state + shorthand: s + description: Filter by state + enum: + - active + - inactive + - any + default: active +--- + +Retrieves all obligation valuess stored in platform policy. diff --git a/docs/man/policy/obligations/values/unassign.md b/docs/man/policy/obligations/values/unassign.md new file mode 100644 index 00000000..7da11c4a --- /dev/null +++ b/docs/man/policy/obligations/values/unassign.md @@ -0,0 +1,19 @@ +--- +title: Unassign an obligation value from an attribute value +command: + name: unassign + flags: + - name: id + shorthand: i + description: ID of the obligation value + required: true + - name: attr-val + description: ID of the attribute value being removed for derived obligation assignment + required: true +--- + +Unassigns an obligation value from an attribute value so that the obligation is no longer considered a derived obligation in an +access decision. + +For more information about the significance of obligations and how they are utilized for derived obligations on attribute values, +see the parent command. diff --git a/docs/man/policy/obligations/values/update.md b/docs/man/policy/obligations/values/update.md new file mode 100644 index 00000000..f89d08c8 --- /dev/null +++ b/docs/man/policy/obligations/values/update.md @@ -0,0 +1,17 @@ +--- +title: Update an obligation value +command: + name: update + flags: + - name: id + shorthand: i + description: ID of the obligation value + required: true + - name: label + description: "Optional metadata 'labels' in the format: key=value" + shorthand: l + default: "" + - name: force-replace-labels + description: Destructively replace entire set of existing metadata 'labels' with any provided to this command + default: false +--- diff --git a/docs/man/policy/subject-condition-sets/create.md b/docs/man/policy/subject-condition-sets/create.md index 6ca47bf4..1362acb0 100644 --- a/docs/man/policy/subject-condition-sets/create.md +++ b/docs/man/policy/subject-condition-sets/create.md @@ -18,7 +18,4 @@ command: description: "Optional metadata 'labels' in the format: key=value" shorthand: l default: '' - - name: force-replace-labels - description: Destructively replace entire set of existing metadata 'labels' with any provided to this command - default: false ---