diff --git a/website/content/docs/commands/token/capabilities.mdx b/website/content/docs/commands/token/capabilities.mdx index 265f4707ab1b..c58756c215e8 100644 --- a/website/content/docs/commands/token/capabilities.mdx +++ b/website/content/docs/commands/token/capabilities.mdx @@ -8,43 +8,77 @@ description: |- # token capabilities -The `token capabilities` command fetches the capabilities of a token for a given -path. +List the capabilities of a token. -If you pass a token value as an argument, this command uses the -`/sys/capabilities` endpoint and permission. In the absence of an explicit token -value, this command uses the `/sys/capabilities-self` endpoint and permission -with the locally authenticated token. + + +```shell-session +$ vault token capabilities [flags] + +$ vault token capabilities [-help | -h] +``` + + + +## Description + +`token capabilities` lists the capabilities of a token for a given path. + +If you provide a token value as an argument, this command uses the +`/sys/capabilities` endpoint and permission. + +If you do not provide an explicit token value, this command uses the +`/sys/capabilities-self` endpoint and permission with the locally authenticated +token. + + + + - QueryTokenCapabilities - [`POST:/sys/capabilities`](/vault/api-docs/system/capabilities) + - QueryTokenCapabilitiesSelf - [`POST:/sys/capabilities-self`](/vault/api-docs/system/capabilities-self) + - QueryTokenCapabilitiesAccessor - [`POST:/sys/capabilities-accessor`](/vault/api-docs/system/capabilities-accessor) + + + +## Command arguments + +
+ +@include 'cli/token/args/token.mdx' + +


+ +@include 'cli/token/args/path.mdx' + +## Command options + +None. + +## Command flags + +None. + +## Global flags + +
+ + +@include 'cli/standard-settings/all-standard-flags.mdx' ## Examples -List capabilities for the local token on the `secret/foo` path: +List capabilities for the local token on the `secret/foo` path. The output shows +the local token has read permission on the `secret/foo` path. ```shell-session $ vault token capabilities secret/foo read ``` -The output shows the local token has read permission on the `secret/foo` path. - List capabilities for a token (`hvs.CAESI...WtiSW5mWUY`) on the `cubbyhole/foo` -path: +path. The output shows the token (`hvs.CAESI...WtiSW5mWUY`) has no permission to +operate on the `cubbyhole/foo` path. ```shell-session $ vault token capabilities hvs.CAESI...WtiSW5mWUY database/creds/readonly deny ``` - -The output shows the token (`hvs.CAESI...WtiSW5mWUY`) has no permission to -operate on the `cubbyhole/foo` path. - -## Usage - -The following flags are available in addition to the [standard set of -flags](/vault/docs/commands) included on all commands. - -### Output options - -- `-format` `(string: "table")` - Print the output in the given format. Valid - formats are "table", "json", or "yaml". This can also be specified via the - `VAULT_FORMAT` environment variable. diff --git a/website/content/docs/commands/token/create.mdx b/website/content/docs/commands/token/create.mdx index 5914f6f5170b..e3a00ea1c6ec 100644 --- a/website/content/docs/commands/token/create.mdx +++ b/website/content/docs/commands/token/create.mdx @@ -11,23 +11,130 @@ description: |- # token create -The `token create` command creates a new token that can be used for -authentication. This token will be created as a child of the currently -authenticated token. The generated token will inherit all policies and -permissions of the currently authenticated token unless you explicitly define a -subset list policies to assign to the token. +Creates a new token that you can use to authenticate to Vault. -A ttl can also be associated with the token. If a ttl is not associated with the -token, then it cannot be renewed. If a ttl is associated with the token, it will -expire after that amount of time unless it is renewed. + -Metadata associated with the token (specified with `-metadata`) is written to -the audit log when the token is used. +```shell-session +$ vault token create [flags] + +$ vault token create [-help | -h] +``` + + + +## Description + +`token create` creates a new token that you can use to authenticate to Vault. +Vault will create this token as a child of the currently authenticated token. +The generated token will inherit all policies and permissions of the currently +authenticated token unless you explicitly define a subset list policies to +assign to the token. + +You can also associate a TTL with the token. If you do specify a TTL, the token +will expire after that amount of time unless it is renewed. Otherwise, if you +do not specify a TTL, the token cannot be renewed. + +Vault writes metadata associated with the token (specified with `-metadata`) +to the audit log when the token is used. If a role is specified, the role may override parameters specified here. + + + - CreateToken - [`POST:/auth/token/create`](/vault/api-docs/auth/token#create-token) + - CreateTokenOrphan - [`POST:/auth/token/create-orphan`](/vault/api-docs/auth/token#create-token) + - CreateTokenWithRole - [`POST:/auth/token/create/:role_name`](/vault/api-docs/auth/token#create-token) + + + + +## Command arguments + +None. + +## Command options + +None. + +## Command flags + +@include 'cli/token/flags/display-name.mdx' + +


+ +@include 'cli/token/flags/entity-alias.mdx' + +


+ +@include 'cli/token/flags/explicit-max-ttl.mdx' + +


+ +@include 'cli/shared/flags/field.mdx' + +


+ +@include 'cli/token/flags/id.mdx' + +


+ +@include 'cli/token/flags/metadata.mdx' + +


+ +@include 'cli/token/flags/no-default-policy.mdx' + +


+ +@include 'cli/token/flags/orphan.mdx' + +


+ +@include 'cli/token/flags/period.mdx' + +


+ +@include 'cli/token/flags/policy.mdx' + +


+ +@include 'cli/token/flags/renewable.mdx' + +


+ +@include 'cli/token/flags/role.mdx' + +


+ +@include 'cli/token/flags/ttl.mdx' + +


+ +@include 'cli/token/flags/type.mdx' + +


+ +@include 'cli/token/flags/use-limit.mdx' + +


+ +@include 'cli/token/flags/wrap-ttl.mdx' + +## Global flags + +
+ +@include 'cli/standard-settings/all-standard-flags.mdx' + ## Examples +Create a new token: + +```shell-session +$ vault token create +``` + Create a token attached to specific policies: ```shell-session @@ -52,78 +159,4 @@ token_accessor 4cd9177c-034b-a004-c62d-54bc56c0e9bd token_duration 30m token_renewable true token_policies [my-policy] -``` - -## Usage - -The following flags are available in addition to the [standard set of -flags](/vault/docs/commands) included on all commands. - -### Output options - -- `-field` `(string: "")` - Print only the field with the given name. Specifying - this option will take precedence over other formatting directives. The result - will not have a trailing newline making it ideal for piping to other processes. - -- `-format` `(string: "table")` - Print the output in the given format. Valid - formats are "table", "json", or "yaml". This can also be specified via the - `VAULT_FORMAT` environment variable. - -### Command options - -- `-display-name` `(string: "")` - Name to associate with this token. This is a - non-sensitive value that can be used to help identify created secrets (e.g. - prefixes). - -- `-entity-alias` `(string: "")` - Name of the entity alias to associate with - during token creation. Only works in combination with -role argument and used - entity alias must be listed in allowed_entity_aliases. If this has been - specified, the entity will not be inherited from the parent. - -- `-explicit-max-ttl` `(duration: "")` - Explicit maximum lifetime for the - token. Unlike normal TTLs, the maximum TTL is a hard limit and cannot be - exceeded. Uses [duration format strings](/vault/docs/concepts/duration-format). - -- `-id` `(string: "")` - Value for the token. By default, this is an - auto-generated value. Specifying this value requires sudo permissions. - -- `-metadata` `(k=v: "")` - Arbitrary key=value metadata to associate with the - token. This metadata will show in the audit log when the token is used. This - can be specified multiple times to add multiple pieces of metadata. - -- `-no-default-policy` `(bool: false)` - Detach the "default" policy from the - policy set for this token. - -- `-orphan` `(bool: false)` - Create the token with no parent. This prevents the - token from being revoked when the token which created it expires. Setting this - value requires sudo permissions. - -- `-period` `(duration: "")` - If specified, every renewal will use the given - period. Periodic tokens do not expire as long as they are actively being - renewed (unless `-explicit-max-ttl` is also provided). Setting this value - requires sudo permissions. Uses [duration format strings](/vault/docs/concepts/duration-format). - -- `-policy` `(string: "")` - Name of a policy to associate with this token. This - can be specified multiple times to attach multiple policies. - -- `-renewable` `(bool: true)` - Allow the token to be renewed up to it's maximum - TTL. - -- `-role` `(string: "")` - Name of the role to create the token against. - Specifying -role may override other arguments. The locally authenticated Vault - token must have permission for `auth/token/create/`. - -- `-ttl` `(duration: "")` - Initial TTL to associate with the token. Token - renewals may be able to extend beyond this value, depending on the configured - maximumTTLs. Uses [duration format strings](/vault/docs/concepts/duration-format). - -- `-type` `(string: "service")` - The type of token to create. Can be "service" or "batch". - -- `-use-limit` `(int: 0)` - Number of times this token can be used. After the - last use, the token is automatically revoked. By default, tokens can be used - an unlimited number of times until their expiration. - -- `-wrap-ttl` `(duration: "")` - Wraps the response in a cubbyhole token with the - requested TTL. The response is available via the "vault unwrap" command. The TTL - is specified as a numeric string with suffix like "30s" or "5m". This can also be - specified via the `VAULT_WRAP_TTL` environment variable. +``` \ No newline at end of file diff --git a/website/content/docs/commands/token/index.mdx b/website/content/docs/commands/token/index.mdx deleted file mode 100644 index d4a4645c922e..000000000000 --- a/website/content/docs/commands/token/index.mdx +++ /dev/null @@ -1,53 +0,0 @@ ---- -layout: docs -page_title: token - Command -description: |- - The "token" command groups subcommands for interacting with tokens. Users can - create, lookup, renew, and revoke tokens. ---- - -# token - -The `token` command groups subcommands for interacting with tokens. Users can -create, lookup, renew, and revoke tokens. - -For more information on tokens, please see the [token concepts -page](/vault/docs/concepts/tokens). - -## Examples - -Create a new token: - -```shell-session -$ vault token create -``` - -Revoke a token: - -```shell-session -$ vault token revoke 96ddf4bc-d217-f3ba-f9bd-017055595017 -``` - -Renew a token: - -```shell-session -$ vault token renew 96ddf4bc-d217-f3ba-f9bd-017055595017 -``` - -## Usage - -```text -Usage: vault token [options] [args] - - # ... - -Subcommands: - capabilities Print capabilities of a token on a path - create Create a new token - lookup Display information about a token - renew Renew a token lease - revoke Revoke a token and its children -``` - -For more information, examples, and usage about a subcommand, click on the name -of the subcommand in the sidebar. diff --git a/website/content/docs/commands/token/lookup.mdx b/website/content/docs/commands/token/lookup.mdx index a96a5bcd967f..868dc1ee5a23 100644 --- a/website/content/docs/commands/token/lookup.mdx +++ b/website/content/docs/commands/token/lookup.mdx @@ -8,8 +8,52 @@ description: |- # token lookup -The `token lookup` displays information about a token or accessor. If a TOKEN is -not provided, the locally authenticated token is used. +Displays information about a token or accessor. + + + +```shell-session +$ vault token lookup [flags] + +$ vault token lookup [-help | -h] +``` + + + +## Description + +`token lookup` displays information about a token or accessor. If you do not +provide a token, Vault will use your locally authenticated token. + + + + - LookupToken - [`POST:/auth/token/lookup`](/vault/api-docs/auth/token#lookup-a-token) + - LookupTokenSelf - [`GET:/auth/token/lookup-self`](/vault/api-docs/auth/token#lookup-a-token-self) + - LookupTokenAccessor - [`POST:/auth/token/lookup-accessor`](/vault/api-docs/auth/token#lookup-a-token-accessor) + + + +## Command arguments + +
+ +@include 'cli/token/args/token.mdx' + +## Command options + +None. + +## Command flags + +
+ +@include 'cli/token/flags/accessor.mdx' + +## Global flags + +
+ +@include 'cli/standard-settings/all-standard-flags.mdx' ## Examples @@ -31,20 +75,4 @@ Get information about a token via its accessor: ```shell-session $ vault token lookup -accessor 9793c9b3-e04a-46f3-e7b8-748d7da248da -``` - -## Usage - -The following flags are available in addition to the [standard set of -flags](/vault/docs/commands) included on all commands. - -### Output options - -- `-format` `(default: "table")` - Print the output in the given format. Valid - formats are "table", "json", or "yaml". This can also be specified via the - `VAULT_FORMAT` environment variable. - -### Command options - -- `-accessor` `(bool: false)` - Treat the argument as an accessor instead of a - token. When this option is selected, the output will NOT include the token. +``` \ No newline at end of file diff --git a/website/content/docs/commands/token/renew.mdx b/website/content/docs/commands/token/renew.mdx index c957db9f1b43..dac9263179e9 100644 --- a/website/content/docs/commands/token/renew.mdx +++ b/website/content/docs/commands/token/renew.mdx @@ -10,10 +10,57 @@ description: |- # token renew -The `token renew` renews a token's lease, extending the amount of time it can be -used. If a TOKEN is not provided, the locally authenticated token is used. Lease -renewal will fail if the token is not renewable, the token has already been -revoked, or if the token has already reached its maximum TTL. +Renews a token's lease. + + + +```shell-session +$ vault token renew [flags] + +$ vault token renew [-help | -h] +``` + + + +## Description + +`token renew` extends the lease duration of a token. You can specify which token +to renew, or Vault will use your locally authenticated token if you do not +provide one. The renewal will fail if: + +- The token is not renewable +- Someone has already revoked the token +- The token has reached its maximum TTL + + + + - RenewToken - [`POST:/auth/token/renew`](/vault/api-docs/auth/token#renew-a-token) + - RenewTokenSelf - [`POST:/auth/token/renew-self`](/vault/api-docs/auth/token#renew-a-token-self) + - RenewTokenAccessor - [`POST:/auth/token/renew-accessor`](/vault/api-docs/auth/token#renew-a-token-accessor) + + + +## Command arguments + +
+ +@include 'cli/token/args/token.mdx' + +## Command options + +None. + +## Command flags + +
+ +@include 'cli/token/flags/increment.mdx' + +## Global flags + +
+ +@include 'cli/standard-settings/all-standard-flags.mdx' ## Examples @@ -35,21 +82,3 @@ Renew a token requesting a specific increment value: ```shell-session $ vault token renew -increment=30m 96ddf4bc-d217-f3ba-f9bd-017055595017 ``` - -## Usage - -The following flags are available in addition to the [standard set of -flags](/vault/docs/commands) included on all commands. - -### Output options - -- `-format` `(default: "table")` - Print the output in the given format. Valid - formats are "table", "json", or "yaml". This can also be specified via the - `VAULT_FORMAT` environment variable. - -### Command options - -- `-increment` `(duration: "")` - Request a specific increment for renewal. - Vault will not honor this request for periodic tokens. If not supplied, Vault will use - the default TTL. This is specified as a numeric string with suffix like "30s" - or "5m". This is aliased as "-i". diff --git a/website/content/docs/commands/token/revoke.mdx b/website/content/docs/commands/token/revoke.mdx index a281d4607a58..fe670ce756ce 100644 --- a/website/content/docs/commands/token/revoke.mdx +++ b/website/content/docs/commands/token/revoke.mdx @@ -8,9 +8,62 @@ description: |- # token revoke -The `token revoke` revokes authentication tokens and their children. If a TOKEN -is not provided, the locally authenticated token is used. The `-mode` flag can -be used to control the behavior of the revocation. +Revokes authentication tokens and their children. + + + +```shell-session +$ vault token revoke [flags] + +$ vault token revoke [-help | -h] +``` + + + +## Description + +`token revoke` revokes authentication tokens and their children. If you do not +provide a token, Vault will use the locally authenticated token. You can use the +`-mode` flag to control the revocation behavior. + + + + - RevokeToken - [`POST:/auth/token/revoke`](/vault/api-docs/auth/token#revoke-a-token) + - RevokeTokenSelf - [`POST:/auth/token/revoke-self`](/vault/api-docs/auth/token#revoke-a-token-self) + - RevokeTokenAccessor - [`POST:/auth/token/revoke-accessor`](/vault/api-docs/auth/token#revoke-a-token-accessor) + - RevokeTokenOrphanChildren - [`POST:/auth/token/revoke-orphan`](/vault/api-docs/auth/token#revoke-token-and-orphan-children) + + + +## Command arguments + +
+ +@include 'cli/token/args/token.mdx' + +## Command options + +None. + +## Command flags + +
+ +@include 'cli/token/flags/accessor.mdx' + +


+ +@include 'cli/token/flags/mode.mdx' + +


+ +@include 'cli/token/flags/self.mdx' + +## Global flags + +
+ +@include 'cli/standard-settings/all-standard-flags.mdx' ## Examples @@ -33,20 +86,4 @@ Revoke a token by accessor: ```shell-session $ vault token revoke -accessor 9793c9b3-e04a-46f3-e7b8-748d7da248da Success! Revoked token (if it existed) -``` - -## Usage - -The following flags are available in addition to the [standard set of -flags](/vault/docs/commands) included on all commands. - -- `-accessor` `(bool: false)` - Treat the argument as an accessor instead of a - token. - -- `-mode` `(string: "")` - Type of revocation to perform. If unspecified, Vault - will revoke the token and all of the token's children. If "orphan", Vault will - revoke only the token, leaving the children as orphans. If "path", tokens - created from the given authentication path prefix are deleted along with their - children. - -- `-self` - Perform the revocation on the currently authenticated token. +``` \ No newline at end of file diff --git a/website/content/docs/commands/transform/import-version.mdx b/website/content/docs/commands/transform/import-version.mdx new file mode 100644 index 000000000000..3f4c6f7cf51f --- /dev/null +++ b/website/content/docs/commands/transform/import-version.mdx @@ -0,0 +1,79 @@ +--- +layout: docs +page_title: transform import-version - Command +description: |- + The "transform import-version" command imports new key material into an + existing transform-managed encryption key via the Transform BYOK mechanism. +--- + +# transform import-version + +Imports new key material into an existing transform-managed encryption key. + + + +```shell-session +$ vault transform import-version [flags] [options] + +$ vault transform import-version [-help | -h] +``` + + + +## Description + +`transform import-version` imports new key material into an existing +transform-managed encryption key via the [Transform BYOK mechanism](/vault/docs/secrets/transform#bring-your-own-key-byok). +To import a completely new key, use the `transform import` command instead. + +To use this command, you need: + +- Read access to the transform mount's wrapping key at `transform/wrapping_key` +- Write access to the import endpoints at `transform/keys/:name/import` + + + + ImportKeyVersionTransform - [`POST:/transform/transformations/tokenization/:name/import_version`](/vault/api-docs/secret/transform#import-key-version-for-tokenization-transformation) + + + +## Command arguments + +
+ +@include 'cli/transform/args/path.mdx' + +
+ +@include 'cli/transform/args/key.mdx' + +## Command options + +After the required `key` argument, you can specify additional options in +`key=value` format to pass these options directly to the Create/Update FPE +Transformation or Create/Update Tokenization Transformation API endpoints. + +Examples: `type=rsa-2048`, `allowed_roles=legacy-system` + +## Command flags + +None. + +## Global flags + +
+ +@include 'cli/standard-settings/all-standard-flags-but-format.mdx' + +## Examples + +Imports a new version of an existing key: + +```shell-session +$ vault transform import-version transform/keys/test-key @test-key-updated +Retrieving transform wrapping key. +Wrapping source key with ephemeral key. +Encrypting ephemeral key with transform wrapping key. +Submitting wrapped key to Vault transform. +Success! +``` \ No newline at end of file diff --git a/website/content/docs/commands/transform/import.mdx b/website/content/docs/commands/transform/import.mdx index eb9e848fd8e7..8685976d79da 100644 --- a/website/content/docs/commands/transform/import.mdx +++ b/website/content/docs/commands/transform/import.mdx @@ -1,62 +1,81 @@ --- layout: docs -page_title: transform import and transform import-version - Command +page_title: transform import - Command description: |- - The "transform import" and "transform import-version" commands import the - specified key into Transform, via the Transform BYOK mechanism. + The "transform import" command imports key material into a new transform-managed + encryption key via the Transform BYOK mechanism. --- -# transform import and transform import-version +# transform import -The `transform import` and `transform import-version` commands import the -specified key into Transform, via the [Transform BYOK -mechanism](/vault/docs/secrets/transform#bring-your-own-key-byok). The former -imports this key as a new key, failing if it already exists, whereas the -latter will only update an existing key in Transform to a new version of the -key material. +Imports key material into a new transform-managed encryption key. -This needs access to read the transform mount's wrapping key (at -`transform/wrapping_key`) and the ability to write to either import -endpoints (either `transform/keys/:name/import` or -`transform/keys/:name/import_version`). + + +```shell-session +$ vault transform import [flags] [options] + +$ vault transform import [-help | -h] +``` + + + +## Description + +`transform import` imports key material into a new transform-managed encryption +key via the [Transform BYOK mechanism](/vault/docs/secrets/transform#bring-your-own-key-byok). +This command will fail if the key already exists. To import key material into +an existing key, use the `transform import-version` command instead. + +To use this command, you need: + +- Read access to the transform mount's wrapping key at `transform/wrapping_key` +- Write access to the import endpoints at `transform/keys/:name/import` + + + + - ImportKeyFPETransform - [`POST:/transform/transformations/fpe/:name/import`](/vault/api-docs/secret/transform#import-key-for-fpe-transformation) + - ImportKeyTokenTransform - [`POST:/transform/transformations/tokenization/:name/import`](/vault/api-docs/secret/transform#import-key-for-tokenization-transformation) + + + +## Command arguments + +
+ +@include 'cli/transform/args/path.mdx' + +
+ +@include 'cli/transform/args/key.mdx' + +## Command options + +After the required `key` argument, you can specify additional options in +`key=value` format to pass these options directly to the Create/Update FPE +Transformation or Create/Update Tokenization Transformation API endpoints. + +Examples: `type=rsa-2048`, `allowed_roles=legacy-system` + +## Command flags + +None. + +## Global flags + +
+ +@include 'cli/standard-settings/all-standard-flags-but-format.mdx' ## Examples Imports a 2048-bit RSA key as a new key: -``` +```shell-session $ vault transform import transform/keys/test-key @test-key type=rsa-2048 Retrieving transform wrapping key. Wrapping source key with ephemeral key. Encrypting ephemeral key with transform wrapping key. Submitting wrapped key to Vault transform. Success! -``` - -Imports a new version of an existing key: - -``` -$ vault transform import-version transform/keys/test-key @test-key-updated -Retrieving transform wrapping key. -Wrapping source key with ephemeral key. -Encrypting ephemeral key with transform wrapping key. -Submitting wrapped key to Vault transform. -Success! -``` - -## Usage - -This command does not have any unique flags and respects core Vault CLI -commands. See `vault transform import -help` for more information. - -This command requires two positional arguments: - - 1. `PATH`, the path to the transform key to import in the format of - `/keys/`, where `` is the path to the mount - (using `-namespace=` to specify any namespaces), and `` - is the desired name of the key. - 2. `KEY`, the key material to import in Standard Base64 encoding (either - of a raw key in the case of symmetric keys such as AES, or of the DER - encoded format for asymmetric keys such as RSA). If the value for `KEY` - begins with an `@`, the CLI argument is assumed to be a path to a file - on disk to be read. +``` \ No newline at end of file diff --git a/website/content/docs/commands/transform/index.mdx b/website/content/docs/commands/transform/index.mdx deleted file mode 100644 index f4a39af409e8..000000000000 --- a/website/content/docs/commands/transform/index.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -layout: docs -page_title: transform - Command -description: |- - The "transform" command groups subcommands for interacting with Vault's Transform - secrets engine. ---- - -# transform - -The `transform` command groups subcommands for interacting with Vault's -[Transform Secrets Engine](/vault/docs/secrets/transform). - -## Syntax - -Option flags for a given subcommand are provided after the subcommand, but before the arguments. - -## Examples - -To [import](/vault/docs/commands/transform/import) keys into a mount via the -[Transform BYOK](/vault/docs/secrets/transform#bring-your-own-key-byok) -mechanism, use the `vault transform import ` or -`vault transform import-version ` commands: - -``` -$ vault transform import transform/transformations/fpe/example @test-key type=rsa-2048 -Retrieving transform wrapping key. -Wrapping source key with ephemeral key. -Encrypting ephemeral key with transform wrapping key. -Submitting wrapped key. -Success! -``` diff --git a/website/content/docs/commands/transit/import-version.mdx b/website/content/docs/commands/transit/import-version.mdx new file mode 100644 index 000000000000..cd4f707e8e07 --- /dev/null +++ b/website/content/docs/commands/transit/import-version.mdx @@ -0,0 +1,82 @@ +--- +layout: docs +page_title: transit import-version - Command +description: |- + The "transit import-version" command imports new key material into an existing transit-managed encryption key via the Transit BYOK mechanism. +--- + +# transit import-version + +Imports new key material into an existing transit-managed encryption key. + + + +```shell-session +$ vault transit import-version [flags] [options] + +$ vault transit import-version [-help | -h] +``` + + + +## Description + +`transit import-version` imports new key material into an existing transit-managed +encryption key via the [Transit BYOK mechanism](/vault/docs/secrets/transit#bring-your-own-key-byok). +To import a completely new key, use the `transit import` command instead. + +If your system or device natively supports the RSA AES key wrap mechanism +(such as the PKCS#11 mechanism `CKM_RSA_AES_KEY_WRAP`), you should use it +directly rather than this command. + +To use this command, you need: + +- Read access to the transit mount's wrapping key at `transit/wrapping_key` +- Write access to the import endpoints at `transit/keys/:name/import_version` + + + + ImportKeyVersion - [`POST:/transit/keys/:name/import_version`](/vault/api-docs/secret/transit#import-key-version) + + + +## Command arguments + +
+ +@include 'cli/transit/args/path.mdx' + +
+ +@include 'cli/transit/args/key.mdx' + +## Command options + +After the required `key` argument, you can specify additional options in +`key=value` format to pass these options directly to the Transit key create +endpoint. + +Examples: `type=rsa-2048`, `allowed_roles=legacy-system` + +## Command flags + +None. + +## Global flags + +
+ +@include 'cli/standard-settings/all-standard-flags-but-format.mdx' + +## Examples + +Imports a new version of an existing key: + +```shell-session +$ vault transit import-version transit/keys/test-key @test-key-updated +Retrieving transit wrapping key. +Wrapping source key with ephemeral key. +Encrypting ephemeral key with transit wrapping key. +Submitting wrapped key to Vault transit. +Success! +``` \ No newline at end of file diff --git a/website/content/docs/commands/transit/import.mdx b/website/content/docs/commands/transit/import.mdx index 2a8c72055602..145ab5591cf1 100644 --- a/website/content/docs/commands/transit/import.mdx +++ b/website/content/docs/commands/transit/import.mdx @@ -1,62 +1,84 @@ --- layout: docs -page_title: transit import and transit import-version - Command +page_title: transit import - Command description: |- - The "transit import" and "transit import-version" commands import the - specified key into Transit, via the Transit BYOK mechanism. + The "transit import" command imports key material into a new transit-managed + encryption key via the Transit BYOK mechanism. --- -# transit import and transit import-version +# transit import -The `transit import` and `transit import-version` commands import the -specified key into Transit, via the [Transit BYOK -mechanism](/vault/docs/secrets/transit#bring-your-own-key-byok). The former -imports this key as a new key, failing if it already exists, whereas the -latter will only update an existing key in Transit to a new version of the -key material. +Imports key material into a new transit-managed encryption key. -This needs access to read the transit mount's wrapping key (at -`transit/wrapping_key`) and the ability to write to either import -endpoints (either `transit/keys/:name/import` or -`transit/keys/:name/import_version`). + + +```shell-session +$ vault transit import [flags] [options] + +$ vault transit import [-help | -h] +``` + + + +## Description + +`transit import` imports key material into a new transit-managed encryption key +via the [Transit BYOK mechanism](/vault/docs/secrets/transit#bring-your-own-key-byok). +This command will fail if the key already exists. To import key material into +an existing key, use the `transit import-version` command instead. + +If your system or device natively supports the RSA AES key wrap mechanism +(such as the PKCS#11 mechanism `CKM_RSA_AES_KEY_WRAP`), you should use it +directly rather than this command. + +To use this command, you need: + +- Read access to the transit mount's wrapping key at `transit/wrapping_key` +- Write access to the import endpoints at `transit/keys/:name/import` + + + + ImportKey - [`POST:/transit/keys/:name/import`](/vault/api-docs/secret/transit#import-key) + + + +## Command arguments + +
+ +@include 'cli/transit/args/path.mdx' + +
+ +@include 'cli/transit/args/key.mdx' + +## Command options + +After the required `key` argument, you can specify additional options in +`key=value` format to pass these options directly to the Transit key create +endpoint. + +Examples: `type=rsa-2048`, `allowed_roles=legacy-system` + +## Command flags + +None. + +## Global flags + +
+ +@include 'cli/standard-settings/all-standard-flags-but-format.mdx' ## Examples Imports a 2048-bit RSA key as a new key: -``` +```shell-session $ vault transit import transit/keys/test-key @test-key type=rsa-2048 Retrieving transit wrapping key. Wrapping source key with ephemeral key. Encrypting ephemeral key with transit wrapping key. Submitting wrapped key to Vault transit. Success! -``` - -Imports a new version of an existing key: - -``` -$ vault transit import-version transit/keys/test-key @test-key-updated -Retrieving transit wrapping key. -Wrapping source key with ephemeral key. -Encrypting ephemeral key with transit wrapping key. -Submitting wrapped key to Vault transit. -Success! -``` - -## Usage - -This command does not have any unique flags and respects core Vault CLI -commands. See `vault transit import -help` for more information. - -This command requires two positional arguments: - - 1. `PATH`, the path to the transit key to import in the format of - `/keys/`, where `` is the path to the mount - (using `-namespace=` to specify any namespaces), and `` - is the desired name of the key. - 2. `KEY`, the key material to import in Standard Base64 encoding (either - of a raw key in the case of symmetric keys such as AES, or of the DER - encoded format for asymmetric keys such as RSA). If the value for `KEY` - begins with an `@`, the CLI argument is assumed to be a path to a file - on disk to be read. +``` \ No newline at end of file diff --git a/website/content/docs/commands/transit/index.mdx b/website/content/docs/commands/transit/index.mdx deleted file mode 100644 index 60b511968c57..000000000000 --- a/website/content/docs/commands/transit/index.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -layout: docs -page_title: transit - Command -description: |- - The "transit" command groups subcommands for interacting with Vault's Transit - secrets engine. ---- - -# transit - -The `transit` command groups subcommands for interacting with Vault's -[Transit Secrets Engine](/vault/docs/secrets/transit). - -## Syntax - -Option flags for a given subcommand are provided after the subcommand, but before the arguments. - -## Examples - -To [import](/vault/docs/commands/transit/import) keys into a mount via the -[Transit BYOK](/vault/docs/secrets/transit#bring-your-own-key-byok) -mechanism, use the `vault transit import ` or -`vault transit import-version ` commands: - -``` -$ vault transit import transit/keys/test-key @test-key type=rsa-2048 -Retrieving transit wrapping key. -Wrapping source key with ephemeral key. -Encrypting ephemeral key with transit wrapping key. -Submitting wrapped key. -Success! -``` diff --git a/website/content/partials/cli/shared/flags/field.mdx b/website/content/partials/cli/shared/flags/field.mdx new file mode 100644 index 000000000000..51f47679ab91 --- /dev/null +++ b/website/content/partials/cli/shared/flags/field.mdx @@ -0,0 +1,9 @@ + + +**`-field (string : "")`** + +Print only the field with the given name. Specifying this option will take +precedence over other formatting directives. The result will not have a +trailing newline making it ideal for piping to other processes. + +**Example**: `-field "id"` \ No newline at end of file diff --git a/website/content/partials/cli/token/args/path.mdx b/website/content/partials/cli/token/args/path.mdx new file mode 100644 index 000000000000..0ea16e6df012 --- /dev/null +++ b/website/content/partials/cli/token/args/path.mdx @@ -0,0 +1,7 @@ + + +**`path (string : "")`** + +The path to test the token's capabilities against. + +**Example**: `secret/foo` \ No newline at end of file diff --git a/website/content/partials/cli/token/args/token.mdx b/website/content/partials/cli/token/args/token.mdx new file mode 100644 index 000000000000..7fa0f0a4db27 --- /dev/null +++ b/website/content/partials/cli/token/args/token.mdx @@ -0,0 +1,8 @@ + + +**`token (string : "")`** + +The authentication token to use. If not provided, the command will use the +locally authenticated token. + +**Example**: `96ddf4bc-d217-f3ba-f9bd-017055595017` \ No newline at end of file diff --git a/website/content/partials/cli/token/flags/accessor.mdx b/website/content/partials/cli/token/flags/accessor.mdx new file mode 100644 index 000000000000..dce0d76002da --- /dev/null +++ b/website/content/partials/cli/token/flags/accessor.mdx @@ -0,0 +1,8 @@ + + +**`-accessor (bool : false)`** + +Treat the argument as an accessor instead of a token. When you select this +option, the output will not include the token. + +**Example**: `-accessor` \ No newline at end of file diff --git a/website/content/partials/cli/token/flags/display-name.mdx b/website/content/partials/cli/token/flags/display-name.mdx new file mode 100644 index 000000000000..3c65388bb11a --- /dev/null +++ b/website/content/partials/cli/token/flags/display-name.mdx @@ -0,0 +1,8 @@ + + +**`-display-name (string : "")`** + +Name to associate with this token. This is a non-sensitive value that you can +use to help identify created secrets (e.g. prefixes). + +**Example**: `-display-name "dev"` \ No newline at end of file diff --git a/website/content/partials/cli/token/flags/entity-alias.mdx b/website/content/partials/cli/token/flags/entity-alias.mdx new file mode 100644 index 000000000000..1732458e9122 --- /dev/null +++ b/website/content/partials/cli/token/flags/entity-alias.mdx @@ -0,0 +1,10 @@ + + +**`-entity-alias (string : "")`** + +Name of the entity alias to associate with during token creation. This flag only +works in combination with the `-role` argument. You must list the entity alias in +`allowed_entity_aliases` for the role. If you specify the entity alias, it will +not be inherited from the parent token. + +**Example**: `-entity-alias "dev"` \ No newline at end of file diff --git a/website/content/partials/cli/token/flags/explicit-max-ttl.mdx b/website/content/partials/cli/token/flags/explicit-max-ttl.mdx new file mode 100644 index 000000000000..9ff5d0d5cc9d --- /dev/null +++ b/website/content/partials/cli/token/flags/explicit-max-ttl.mdx @@ -0,0 +1,8 @@ + + +**`-explicit-max-ttl (duration : "")`** + +Explicit maximum lifetime for the token. Unlike normal TTLs, the maximum TTL is +a hard limit and cannot be exceeded. Uses [duration format strings](/vault/docs/concepts/duration-format). + +**Example**: `-explicit-max-ttl "1h"` \ No newline at end of file diff --git a/website/content/partials/cli/token/flags/id.mdx b/website/content/partials/cli/token/flags/id.mdx new file mode 100644 index 000000000000..fd136fd6ad9f --- /dev/null +++ b/website/content/partials/cli/token/flags/id.mdx @@ -0,0 +1,8 @@ + + +**`-id (string : "")`** + +Value for the token. By default, this is an auto-generated value. Specifying +this value requires sudo permissions. + +**Example**: `-id "dev"` \ No newline at end of file diff --git a/website/content/partials/cli/token/flags/increment.mdx b/website/content/partials/cli/token/flags/increment.mdx new file mode 100644 index 000000000000..9afc8019d9b6 --- /dev/null +++ b/website/content/partials/cli/token/flags/increment.mdx @@ -0,0 +1,10 @@ + + +**`-increment (duration : "")`** + +Request a specific increment for renewal. Vault will not honor this request for +periodic tokens. If not supplied, Vault will use the default TTL. This is +specified as a numeric string with suffix like "30s" or "5m". This flag is +aliased as `-i`. + +**Example**: `-increment "5m"` diff --git a/website/content/partials/cli/token/flags/metadata.mdx b/website/content/partials/cli/token/flags/metadata.mdx new file mode 100644 index 000000000000..f8b5d578d68f --- /dev/null +++ b/website/content/partials/cli/token/flags/metadata.mdx @@ -0,0 +1,9 @@ + + +`-metadata (string : "")`** + +Custom metadata associated with the token in `"key=value"` format. The metadata shows up +in the audit log when the token is used. You can specify this flag multiple times +to add multiple pieces of metadata. + +**Example**: `-metadata "environment=sandbox"` \ No newline at end of file diff --git a/website/content/partials/cli/token/flags/mode.mdx b/website/content/partials/cli/token/flags/mode.mdx new file mode 100644 index 000000000000..b09312b774df --- /dev/null +++ b/website/content/partials/cli/token/flags/mode.mdx @@ -0,0 +1,10 @@ + + +**`-mode (string : "")`** + +Type of revocation to perform. If unspecified, Vault will revoke the token and +all of the token's children. If `"orphan"`, Vault will revoke only the token, +leaving the children as orphans. If `"path"`, Vault deletes tokens created from +the given authentication path prefix along with their children. + +**Example**: `-mode "orphan"` \ No newline at end of file diff --git a/website/content/partials/cli/token/flags/no-default-policy.mdx b/website/content/partials/cli/token/flags/no-default-policy.mdx new file mode 100644 index 000000000000..6c2f3566ecd1 --- /dev/null +++ b/website/content/partials/cli/token/flags/no-default-policy.mdx @@ -0,0 +1,7 @@ + + +**`-no-default-policy (bool : false)`** + +Detach the "default" policy from the policy set for this token. + +**Example**: `-no-default-policy` \ No newline at end of file diff --git a/website/content/partials/cli/token/flags/orphan.mdx b/website/content/partials/cli/token/flags/orphan.mdx new file mode 100644 index 000000000000..b6133b4a8191 --- /dev/null +++ b/website/content/partials/cli/token/flags/orphan.mdx @@ -0,0 +1,8 @@ + + +**`-orphan (bool : false)`** + +Create the token with no parent. This prevents the token from being revoked when +the token which created it expires. This flag requires sudo permissions. + +**Example**: `-orphan` \ No newline at end of file diff --git a/website/content/partials/cli/token/flags/period.mdx b/website/content/partials/cli/token/flags/period.mdx new file mode 100644 index 000000000000..2a69f3156ead --- /dev/null +++ b/website/content/partials/cli/token/flags/period.mdx @@ -0,0 +1,10 @@ + + +**`-period (duration : "")`** + +If specified, every renewal will use the given period. Periodic tokens do not +expire as long as they are actively being renewed (unless `-explicit-max-ttl` is +also provided). This flag requires sudo permissions. Uses +[duration format strings](/vault/docs/concepts/duration-format). + +**Example**: `-period "1h"` \ No newline at end of file diff --git a/website/content/partials/cli/token/flags/policy.mdx b/website/content/partials/cli/token/flags/policy.mdx new file mode 100644 index 000000000000..cec100cd3bbf --- /dev/null +++ b/website/content/partials/cli/token/flags/policy.mdx @@ -0,0 +1,8 @@ + + +**`-policy (string : "")`** + +Name of a policy to associate with this token. Specify the `policy` flag multiple +times to attach multiple policies. + +**Example**: `-policy "admin"` \ No newline at end of file diff --git a/website/content/partials/cli/token/flags/renewable.mdx b/website/content/partials/cli/token/flags/renewable.mdx new file mode 100644 index 000000000000..ab1ddf60c824 --- /dev/null +++ b/website/content/partials/cli/token/flags/renewable.mdx @@ -0,0 +1,7 @@ + + +**`-renewable (bool : true)`** + +Allow the token to be renewed up to its maximum TTL. + +**Example**: `-renewable` \ No newline at end of file diff --git a/website/content/partials/cli/token/flags/role.mdx b/website/content/partials/cli/token/flags/role.mdx new file mode 100644 index 000000000000..ba75e441db96 --- /dev/null +++ b/website/content/partials/cli/token/flags/role.mdx @@ -0,0 +1,8 @@ + + +**`-role (string : "")`** + +Name of the role to create the token against. Specifying this value may override +other arguments. + +**Example**: `-role "admin"` \ No newline at end of file diff --git a/website/content/partials/cli/token/flags/self.mdx b/website/content/partials/cli/token/flags/self.mdx new file mode 100644 index 000000000000..d3ae88833b47 --- /dev/null +++ b/website/content/partials/cli/token/flags/self.mdx @@ -0,0 +1,7 @@ + + +**`-self` (bool : false)** + +Perform the revocation on the currently authenticated token. + +**Example**: `-self` \ No newline at end of file diff --git a/website/content/partials/cli/token/flags/ttl.mdx b/website/content/partials/cli/token/flags/ttl.mdx new file mode 100644 index 000000000000..fa6b5cb9e19f --- /dev/null +++ b/website/content/partials/cli/token/flags/ttl.mdx @@ -0,0 +1,9 @@ + + +**`-ttl (string : "")`** + +Initial TTL to associate with the token. You can renew the token beyond this +value, depending on the configured maximum TTLs. Uses +[duration format strings](/vault/docs/concepts/duration-format). + +**Example**: `-ttl "1h"` \ No newline at end of file diff --git a/website/content/partials/cli/token/flags/type.mdx b/website/content/partials/cli/token/flags/type.mdx new file mode 100644 index 000000000000..d63989bd27cd --- /dev/null +++ b/website/content/partials/cli/token/flags/type.mdx @@ -0,0 +1,7 @@ + + +**`-type (string : "service")`** + +The type of token to create. Can be "service" or "batch". + +**Example**: `-type "batch"` diff --git a/website/content/partials/cli/token/flags/use-limit.mdx b/website/content/partials/cli/token/flags/use-limit.mdx new file mode 100644 index 000000000000..d946b6b399b6 --- /dev/null +++ b/website/content/partials/cli/token/flags/use-limit.mdx @@ -0,0 +1,9 @@ + + +**`-use-limit (int : 0)`** + +Number of times this token can be used. After the last use, the token is +automatically revoked. By default, you can use tokens an unlimited number of +times until their expiration. + +**Example**: `-use-limit 10` diff --git a/website/content/partials/cli/token/flags/wrap-ttl.mdx b/website/content/partials/cli/token/flags/wrap-ttl.mdx new file mode 100644 index 000000000000..90bf5d055570 --- /dev/null +++ b/website/content/partials/cli/token/flags/wrap-ttl.mdx @@ -0,0 +1,10 @@ + + +**`-wrap-ttl (string : "")`** + +Wraps the response in a cubbyhole token with the requested TTL. The response is +available via the `vault unwrap` command. The TTL is specified as a numeric +string with suffix like "30s" or "5m". You can also specify this via the +`VAULT_WRAP_TTL` environment variable. + +**Example**: `-wrap-ttl "1h"` diff --git a/website/content/partials/cli/transform/args/key.mdx b/website/content/partials/cli/transform/args/key.mdx new file mode 100644 index 000000000000..b47c6542d90e --- /dev/null +++ b/website/content/partials/cli/transform/args/key.mdx @@ -0,0 +1,10 @@ + + +**`key (string : )`** + +The key material to import, encoded in base64 format. For symmetric keys like +AES, this is the raw key material. For asymmetric keys like RSA, this is the +DER-encoded format. If the value starts with `@`, it is treated as a path to a +file containing the key material. + +**Example**: `@/path/to/key` \ No newline at end of file diff --git a/website/content/partials/cli/transform/args/path.mdx b/website/content/partials/cli/transform/args/path.mdx new file mode 100644 index 000000000000..b6da2a3d9ae2 --- /dev/null +++ b/website/content/partials/cli/transform/args/path.mdx @@ -0,0 +1,10 @@ + + +**`path (string : )`** + +The path to the transform key to import, formatted as `/keys/`. +This path consists of two parts: ``, which is the path to the mount, and +``, which is the desired name of the key. You can optionally specify a +namespace in the `` path using the `-namespace=` flag. + +**Example**: `transform/keys/my-key` \ No newline at end of file diff --git a/website/content/partials/cli/transit/args/key.mdx b/website/content/partials/cli/transit/args/key.mdx new file mode 100644 index 000000000000..b47c6542d90e --- /dev/null +++ b/website/content/partials/cli/transit/args/key.mdx @@ -0,0 +1,10 @@ + + +**`key (string : )`** + +The key material to import, encoded in base64 format. For symmetric keys like +AES, this is the raw key material. For asymmetric keys like RSA, this is the +DER-encoded format. If the value starts with `@`, it is treated as a path to a +file containing the key material. + +**Example**: `@/path/to/key` \ No newline at end of file diff --git a/website/content/partials/cli/transit/args/path.mdx b/website/content/partials/cli/transit/args/path.mdx new file mode 100644 index 000000000000..b6da2a3d9ae2 --- /dev/null +++ b/website/content/partials/cli/transit/args/path.mdx @@ -0,0 +1,10 @@ + + +**`path (string : )`** + +The path to the transform key to import, formatted as `/keys/`. +This path consists of two parts: ``, which is the path to the mount, and +``, which is the desired name of the key. You can optionally specify a +namespace in the `` path using the `-namespace=` flag. + +**Example**: `transform/keys/my-key` \ No newline at end of file diff --git a/website/content/partials/global-settings/both/format.mdx b/website/content/partials/global-settings/both/format.mdx index c0d437e482ec..d4f5ff54d792 100644 --- a/website/content/partials/global-settings/both/format.mdx +++ b/website/content/partials/global-settings/both/format.mdx @@ -1,8 +1,9 @@ -**`[-format | VAULT_FORMAT] (enum: json)`** +**`[-format | VAULT_FORMAT] (enum: table)`** -Set the CLI output format. +Set the CLI output format. You can also define this via the `VAULT_FORMAT` +environment variable. Value | Description ------- | ----------- @@ -13,6 +14,5 @@ Value | Description **Examples**: -- CLI flag: `-format table` -- Environment variable: `export VAULT_FORMAT=table` - +- CLI flag: `-format json` +- Environment variable: `export VAULT_FORMAT=json` \ No newline at end of file diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 546597d77229..e2a243bfecbf 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -1096,10 +1096,6 @@ { "title": "token", "routes": [ - { - "title": "Overview", - "path": "commands/token" - }, { "title": "capabilities", "path": "commands/token/capabilities" @@ -1123,28 +1119,28 @@ ] }, { - "title": "transit", + "title": "transform", "routes": [ { - "title": "Overview", - "path": "commands/transit" + "title": "import", + "path": "commands/transform/import" }, { - "title": "import and import-version", - "path": "commands/transit/import" + "title": "import-version", + "path": "commands/transform/import-version" } ] }, { - "title": "transform", + "title": "transit", "routes": [ { - "title": "Overview", - "path": "commands/transform" + "title": "import", + "path": "commands/transit/import" }, { - "title": "import and import-version", - "path": "commands/transform/import" + "title": "import-version", + "path": "commands/transit/import-version" } ] }, diff --git a/website/redirects.js b/website/redirects.js index de0477a91213..6e533041b15b 100644 --- a/website/redirects.js +++ b/website/redirects.js @@ -134,5 +134,20 @@ module.exports = [ source: '/vault/docs/command/web', destination: '/vault/docs/ui/web-cli', permanent: true, - } + }, + { + source: '/vault/docs/commands/token', + destination: '/vault/docs/commands/token/create', + permanent: true, + }, + { + source: '/vault/docs/commands/transform', + destination: '/vault/docs/commands/transform/import', + permanent: true, + }, + { + source: '/vault/docs/commands/transit', + destination: '/vault/docs/commands/transit/import', + permanent: true, + }, ]