From 90f6dfe658da423dddd544bb232ed97d22b39518 Mon Sep 17 00:00:00 2001 From: Yolan Romailler Date: Mon, 30 May 2022 21:41:23 +0200 Subject: [PATCH] Adding doc around parsing and YAML RELEASE_NOTES=[DOCUMENTATION] Adding documentation about YAML entries and unsafe-keys Fixes #1940 Signed-off-by: Yolan Romailler --- docs/commands/show.md | 22 ++++++++++++++++++++-- docs/features.md | 27 ++++++++++++++++++++++----- 2 files changed, 42 insertions(+), 7 deletions(-) diff --git a/docs/commands/show.md b/docs/commands/show.md index 34b7099a45..674ec6735d 100644 --- a/docs/commands/show.md +++ b/docs/commands/show.md @@ -78,7 +78,6 @@ The secrets are split into 3 categories: will be parsed into (with `safecontent` enabled): ``` and: the keys are separated from their value by : - password: ****** where: the first line is the password @@ -103,11 +102,30 @@ The secrets are split into 3 categories: bill-to: map[family:Doe given:Bob] date: 2001-01-23 00:00:00 +0000 UTC invoice: 83 - password: ***** ship-to: map[family:Doe given:Bob] ``` Note how the `0123` is interpreted as octal for 83. If you want to store a string made of digits such as a numerical username, it should be enclosed in string delimiters: `username: "0123"` will always be parsed as the string `0123` and not as octal. +Both the key-value and the YAML format support so-called "unsafe-keys", which is a key-value that allows you to specify keys that should be hidden when using `gopass show` with `gopass config safecontent` set to true. +E.g: +``` +supersecret +--- +age: 27 +secret: The rabbit outran the tortoise +name: John Smith +unsafe-keys: age,secret +``` +will display (with safecontent enabled): +``` +age: ***** +name: John Smith +secret: ***** +unsafe-keys: age,secret + +``` +unless it is called with `gopass show -n` that would disable parsing of the body, but still hide the password, or `gopass show -f` that would show everything that was hidden, including the password. + Notice that if the option `parsing` is disabled in the config, then all secrets are handled as plain secrets. diff --git a/docs/features.md b/docs/features.md index dda6b88024..72276c2c76 100644 --- a/docs/features.md +++ b/docs/features.md @@ -168,7 +168,7 @@ secret1234 otpauth://totp/golang.org:gopher?secret=ABC123 ``` -Alternatively, you can use YAML (currently totp only): +Alternatively, you can use YAML (notice the usage of the YAML separator to indicate it is a YAML secret): ``` gopass show golang.org/gopher @@ -375,9 +375,7 @@ Commands that support the `--store` flag: ### Directly edit structured secrets aka. YAML support -Warning: YAML support is deprecated. - -gopass supports directly editing structured secrets (simple key-value maps or YAML). +gopass supports directly editing structured secrets (simple key-value maps): ```bash $ gopass generate -n foo/bar 12 @@ -393,11 +391,30 @@ $ gopass foo/bar baz: zab ``` +Or even YAML: +```bash +secret1234 +--- +multi: | + text + more text +octal: 0123 +date : 2001-01-23 +bill-to: &id001 + given : Bob + family : Doe +ship-to: *id001 +``` + +Note that YAML entries currently support only one YAML block and **must start with the separator** `---` after the password and body text, if any. We do not support comments directly after the separator. + Please note that gopass will try to leave your secret as is whenever possible, but as soon as you mutate the YAML content through gopass, i.e. `gopass insert secret key`, -it will employ an YAML marshaler that may alter the order and escaping of your +it will employ a YAML marshaler that may alter the order and escaping of your entries. +See also [gopass show doc entry](/docs/commands/show.md#parsing-and-secrets) for more information about parsing and how to disable it. + ### Edit the Config gopass allows editing the config from the command-line. This is similar to how git handles config changes through the command-line. Any change will be written to the configured gopass config file.