diff --git a/.github/spellcheck.ignore b/.github/spellcheck.ignore new file mode 100644 index 00000000..47e4d2b9 --- /dev/null +++ b/.github/spellcheck.ignore @@ -0,0 +1,98 @@ +AllOf +AnyOf +Auth +CLI's +Changelog +ConditionGroup +CoolTool +Decrypt +ERS +FQNs +Hostname +JSON +JWT +KASes +KASs +LDAP +MacOS +NPM +Namespace +Nano +OIDC +OpenTDF +PDP +PKCE +README +RadService +SCS +SDK +ShinyThing +TDF +TDF'd +TDFd +TDFs +TLS +TODO +TUI +URI +Unassign +acmeco +args +attr +auth +cli +clientId +clientSecret +config +data-centric +decrypt +decryptable +decrypted +dev +encodings +enum +https +idP +jq +json +jwt +kas +kas-url-path +kasg +kasr +keychain +keycloak +keyring +localhost +namespace +namespaces +nano +ns +otdfctl +performant +poc +pubkey +quickstart +resm +resolvers +scs +sm +stdin +stdout +stdout +subcommand +subcs +subm +submap +tdf +tdf-type +tls +tls-no-verify +txt +unassign +unassignment +upsert +uri +with-client-creds +with-client-creds-file +yaml \ No newline at end of file diff --git a/.github/workflows/spellcheck.yaml b/.github/workflows/spellcheck.yaml new file mode 100644 index 00000000..f5cb1054 --- /dev/null +++ b/.github/workflows/spellcheck.yaml @@ -0,0 +1,22 @@ +name: 'spellcheck' + +on: + pull_request: + branches: + - main + paths-ignore: + - LICENSE + - CODEOWNERS + - '.gitignore' + - '**/*.go' + +jobs: + spellcheck: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: matheus23/md-spellcheck-action@v4.2.2 + with: + files-to-check: '**/*.md' + files-to-exclude: 'CHANGELOG.md' + words-to-ignore-file: './.github/spellcheck.ignore' diff --git a/docs/man/policy/_index.md b/docs/man/policy/_index.md index 4b4d3faf..bbe65c09 100644 --- a/docs/man/policy/_index.md +++ b/docs/man/policy/_index.md @@ -14,7 +14,7 @@ command: Manage policies within the platform. -Policy is a set of rules that are enforced by the platform. Specific to the the data centric +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 of attributes are namespaces, values, subject-mappings, resource-mappings, key-access-server grants, and other key elements. diff --git a/docs/man/policy/kas-grants/_index.md b/docs/man/policy/kas-grants/_index.md index 5ec389f9..8f46b0ce 100644 --- a/docs/man/policy/kas-grants/_index.md +++ b/docs/man/policy/kas-grants/_index.md @@ -15,7 +15,14 @@ they can be assigned grants to various attribute objects (namespaces, definition > See `kas-registry` command within `policy` to manage the KASs known to the platform. -Grants are utilized by the platform at two important points when engaging with a TDF. +Key Access Grants are associations between a registered KAS (see KAS Registry docs) and an Attribute. + +An attribute can be assigned a KAS Grant on its namespace, its definition, or any one of its values. + +Grants enable key split behaviors on TDFs with attributes, which can be useful for various collaboration scenarios around shared policy. + +> [!WARNING] +> KAS Grants are considered experimental, as grants to namespaces are not fully utilized within encrypt/decrypt flows at present. ## Utilization @@ -26,7 +33,7 @@ is found to be permissible): 1. look up the attributes on the TDF within the platform 2. find any associated grants for those attributes' values, definitions, namespaces 3. retrieve the public key of each KAS granted to those attribute objects -4. determine based on the specificity matrix below which keys to utilize +4. determine based on the specificity matrix below which keys to utilize in splits ## Specificity @@ -47,3 +54,69 @@ Grants to Attribute Objects: > Note: > A namespace grant may soon be required with deprecation of a default KAS/platform key. + +## Split Scenarios + +### AnyOf Split + +`Bob` and `Alice` want to share data equally, but maintain their ability to decrypt the data without sharing each other’s private keys. + +With KAS Grants, they can define a key split where the shared data is wrapped with both of their public keys and AnyOf logic, meaning that each partner could decrypt the data with just one of those keys. + +If `Bob` assigns a grant between Bob's running/registered KAS to a known attribute value, and `Alice` defines a grant of Alice's running/registered KAS to the same attribute value, +any data encrypted in a TDF will be decryptable with a key released by _either_ of their Key Access Servers. + +Attribute A: `https://conglomerate.com/attr/organization/value/acmeco` + +Attribute B: `https://conglomerate.com/attr/organization/value/example_inc` + +| Attribute | Namespace | Definition | Value | +| --------- | ---------------- | ------------ | ----------- | +| A | conglomerate.com | organization | acmeco | +| B | conglomerate.com | organization | example_inc | + +**Attribute KAS Grant Scenarios** + +1. Bob & Alice represent individual KAS Grants to attributes on TDF'd data +2. Note that the attributes A and B are of _the same definition and namespace_ + +| Definition: organization | Value: acmeco | Value: example_inc | Split | +| ------------------------ | ------------- | ------------------ | ----- | +| Bob, Alice | - | - | OR | +| - | Bob, Alice | - | OR | +| - | - | Bob, Alice | OR | +| - | Bob | Alice | OR | + +### AllOf Split + +Unlike the `AnyOf` split above, this time `Bob` and `Alice` want to make sure _both_ of their keys must be granted for data in a TDF +to be decrypted. With KAS Grants, they can define a key split where the shared data is wrapped with both of their public keys and +AllOf logic, meaning that neither partner can decrypt the data with just one of those keys. + +To accomplish this, they each define KAS Grants between their KASes and policy attributes, and TDF data with at least two attributes - +one assigned a KAS Grant to Bob's KAS and another assigned a KAS Grant to Alice's KAS. + +Both KASes will need to permit access and release payload keys for the data TDF'd with multiple attributes assigned KAS Grants to be accessible and decrypted. + +Attribute A: `https://conglomerate.com/attr/organization/value/acmeco` + +Attribute B: `https://conglomerate.com/attr/department/value/sales` + +| Attribute | Namespace | Definition | Value | +| --------- | ---------------- | ------------ | --------- | +| A | conglomerate.com | organization | acmeco | +| A | conglomerate.com | department | marketing | + +**Attribute KAS Grant Scenarios** + +1. Bob & Alice represent individual KAS Grants to attributes on TDF'd data +2. Note that the attributes A and B are of _the same namespace but different definitions_ + +| Definition: A | Value: A | Definition: B | Value: B | Split | +| ------------- | -------- | ------------- | -------- | ----- | +| Bob | - | Alice | - | AND | +| Bob | - | - | Alice | AND | +| - | Bob | - | Alice | AND | + +> [!NOTE] +> Any KAS Grants to attributes of different definitions or namespaces will be `AND` splits. diff --git a/docs/man/policy/kas-registry/create.md b/docs/man/policy/kas-registry/create.md index 8f4f59b5..828d6db3 100644 --- a/docs/man/policy/kas-registry/create.md +++ b/docs/man/policy/kas-registry/create.md @@ -44,7 +44,7 @@ can be retrieved for the registered KAS under the `remote` key, such as `https:/ "pem": "", // key identifier "kid": "", - // algorithm (either: 1 for rsa:2048, 2 for ec:secp256r1) + // key algorithm (see table below) "alg": 1 } ] @@ -54,7 +54,16 @@ can be retrieved for the registered KAS under the `remote` key, such as `https:/ The JSON value passed to the `--public-keys` flag stores the set of public keys for the KAS. -The PEM value should contain everything `-----BEGIN CERTIFICATE-----\nMIIB...5Q=\n-----END CERTIFICATE-----\n`. +1. The `"pem"` value should contain the entire certificate `-----BEGIN CERTIFICATE-----\nMIIB...5Q=\n-----END CERTIFICATE-----\n`. + +2. The `"kid"` value is a named key identifier, which is useful for key rotations. + +3. The `"alg"` specifies the key algorithm: + +| Key Algorithm | `alg` Value | +| -------------- | ----------- | +| `rsa:2048` | 1 | +| `ec:secp256r1` | 5 | ### Local diff --git a/docs/man/policy/subject-mappings/create.md b/docs/man/policy/subject-mappings/create.md index 909ad92e..3c5bf36a 100644 --- a/docs/man/policy/subject-mappings/create.md +++ b/docs/man/policy/subject-mappings/create.md @@ -1,5 +1,5 @@ --- -title: Create a new subject mapping +title: Create a new subject mapping command: name: create aliases: @@ -11,7 +11,7 @@ command: description: The ID of the attribute value to map to a subject set shorthand: a required: true - default: "" + default: '' - name: action-standard description: The standard action to map to a subject set enum: @@ -19,22 +19,22 @@ command: - TRANSMIT shorthand: s required: true - default: "" + default: '' - name: action-custom description: The custom action to map to a subject set shorthand: c required: false - default: "" + default: '' - name: subject-condition-set-id - description: Known pre-existing Subject Condition Set Id + description: Known preexisting Subject Condition Set Id required: true - default: "" + default: '' - name: subject-condition-set-new description: JSON array of Subject Sets to create a new Subject Condition Set associated with the created Subject Mapping required: false - default: "" + default: '' - name: label description: "Optional metadata 'labels' in the format: key=value" shorthand: l - default: "" ---- \ No newline at end of file + default: '' +--- diff --git a/docs/man/policy/subject-mappings/update.md b/docs/man/policy/subject-mappings/update.md index ee4fe065..d42b51b1 100644 --- a/docs/man/policy/subject-mappings/update.md +++ b/docs/man/policy/subject-mappings/update.md @@ -1,5 +1,5 @@ --- -title: Update a subject mapping +title: Update a subject mapping command: name: update aliases: @@ -16,20 +16,20 @@ command: - TRANSMIT shorthand: s required: true - default: "" + default: '' - name: action-custom description: The custom action to map to a subject set shorthand: c required: false - default: "" + default: '' - name: subject-condition-set-id - description: Known pre-existing Subject Condition Set Id + description: Known preexisting Subject Condition Set Id required: true - default: "" + default: '' - 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