@ -63,17 +63,17 @@ TODO: Building a plugin example. compiling one, and encoding one.
```sh
$ readpass --prompt "Please enter password" \ # Initial user prompt
--restrict size 10..50 \ # Restrict on a Rust-format size range:`10..50` >=10 &&<50,`10..`>=10, `..` unrestricted, `..=50`<=50 (no lower bound, can be zero chars here) Or a specific exact size (e.g: `10` == 10)
--restrict regex '(?!.*\2)(?:(?1){4})+^ \ # Restrict based on regex match (this one requires at least 4 unique characters in a row.
--restrict regex '(?!.*\2)(?:(?1){4})+$' \ # Restrict based on regex match (this one requires at least 4 unique characters in a row at the end of the password.
The salt can be one of the following: `raw:salt_string` (use the literal "salt_string". "hex:<valuehex-string-encodeddata>" Where the post-colon text is decoded into bytes as a hexadecimal string, e.g: "hex:cafebeef1004" is decoded to the hex-dump literal `0xcafebeef1004`. "base64:<base64string>" Where the post-colon text is a valid base64 string, the salt used is the basae64 decoded data. "file:<filename>[/{[{=,-}],..}<bytes>]" use the data of a file as the salt, optionally only up to "<bytes>" number read, omit the `..` to read only exactly `<bytes>` number from the file, or if the range has a lower bound, the most possible number of bytes within that range; the `=` is entirely optional, but explicitly says to read the *most* bytes, if the character `-` is used instead of the `=` before the range specifier, then it will read the *least* bytes instead. "fd:<fd>[{{=,-},..}<bytes>]" specify a currently open file-descriptor to read the salt from (will be read to the end if not lstat()/mmap()able). The optional sizing restriction rules are the same as with `file:`, but the `=` is not optional and must be provided if a `-` is not (see "file:" sizing behaviour.). Essentially the same as`file:/dev/<fd>[/sizing-rules...]. ) \
Or a bare string literal, which defaults to assuming the prefix is "raw:". \
(note: a "did you mean" warning _may_ be omitted if the data string starts with a prefix "<kw>:", and the levelshtein distance between <kw> and a valid keyword is very low, so explicit "raw:" is advised over letting the implicit default behaviour potentially emit these kinds of warnings.) \
Valid options for `sha256` are: ( Salt required: `sha256`, `sha512`, `sha1`, `blake2`. \
The hashes will be attempted to be read as such from the wordlist: optionally (since hashes are of fixed size) whitespace-delimited hex strings decoded, optionally whitespace-delimited base64 strings, raw binary datawith no delimiter. A warning *may* be omitted if it is thought the file was *intended* to be read as a line/whitespace-based format when it is instead being read as a binary one. To avoid any potential program confusion, the format may be specified explicitly by prefixing `wordlist` with any of: ("hex[=]:[:]", "base64[=]:[:]", "raw[=]:[:]", specifying the format. The `=` character additionally specifies that the file is *not delimited*, i.e. the fixed-sized hash list is to be read one fixed-size encoding at a time; for "raw:", this prevents auto-decompression of detected-compressed files, and the postfix extra `:` redundantly has the same behaviour.) \
The file may be compressed with: `zstd`, `brotli`, or `gz` algorithms; if the header of the file indicates that is compressed with that format, it will first be decompressed. If the file seems compressed, but still can be validly interpreted in the specified (or inferred) format without decompression, a warning *will* be outputted. To prevent this, post-fix the ":" with another `:` on the explicit format specifier to disable automatic attempted decompression (for "raw=:", the second ":" is redundant, but either/or can still be specified.) \
Some hashes may require size constraints on the salt, if the ":" of a specifier is prefixed with the character `~` (e.g. `raw~:`, `file~:`), then if the size of the read salt is lower than what is required, a correctly-sized nonce will *instead* be generated from the read salt using as many rounds of the `blake2` hash (/*XXX: is this still secure? should we choose an embedded salt for this at compile-time, or blake2 the `salt` specifier list and use that result instead? It cannot be random, since the hashes much match*/ unsalted) on the input needed to generate a nonce of the required size (usually, only one round will be applied to generate enough data to use, when reading a specific size, if the input is too large, the rest will just be discarded, the extra hashing round is only for inputs that are too small.) \
Salt not required: `raw` (i.e, deny raw password strings delimited by newlines inside the wordlist.txt), `null`, same as raw, but delimited by the NUL character instead of newlines.
\# The salt can be one of the following: `raw:salt_string` (use the literal "salt_string". "hex:<valuehex-string-encodeddata>" Where the post-colon text is decoded into bytes as a hexadecimal string, e.g: "hex:cafebeef1004" is decoded to the hex-dump literal `0xcafebeef1004`. "base64:<base64string>" Where the post-colon text is a valid base64 string, the salt used is the basae64 decoded data. "file:<filename>[/{[{=,-}],..}<bytes>]" use the data of a file as the salt, optionally only up to "<bytes>" number read, omit the `..` to read only exactly `<bytes>` number from the file, or if the range has a lower bound, the most possible number of bytes within that range; the `=` is entirely optional, but explicitly says to read the *most* bytes, if the character `-` is used instead of the `=` before the range specifier, then it will read the *least* bytes instead. "fd:<fd>[{{=,-},..}<bytes>]" specify a currently open file-descriptor to read the salt from (will be read to the end if not lstat()/mmap()able). The optional sizing restriction rules are the same as with `file:`, but the `=` is not optional and must be provided if a `-` is not (see "file:" sizing behaviour.). Essentially the same as`file:/dev/<fd>[/sizing-rules...]. )
\# Or a bare string literal, which defaults to assuming the prefix is "raw:".
\ # (NOTE: a "did you mean" warning _may_ be omitted if the data string starts with a prefix "<kw>:", and the levelshtein distance between <kw> and a valid keyword is very low, so explicit "raw:" is advised over letting the implicit default behaviour potentially emit these kinds of warnings.)
\# Valid options for `sha256` are: ( Salt required: `sha256`, `sha512`, `sha1`, `blake2`.
\# The hashes will be attempted to be read as such from the wordlist: optionally (since hashes are of fixed size) whitespace-delimited hex strings decoded, optionally whitespace-delimited base64 strings, raw binary datawith no delimiter. A warning *may* be omitted if it is thought the file was *intended* to be read as a line/whitespace-based format when it is instead being read as a binary one. To avoid any potential program confusion, the format may be specified explicitly by prefixing `wordlist` with any of: ("hex[=]:[:]", "base64[=]:[:]", "raw[=]:[:]", specifying the format. The `=` character additionally specifies that the file is *not delimited*, i.e. the fixed-sized hash list is to be read one fixed-size encoding at a time; for "raw:", this prevents auto-decompression of detected-compressed files, and the postfix extra `:` redundantly has the same behaviour.)
\# The file may be compressed with: `zstd`, `brotli`, or `gz` algorithms; if the header of the file indicates that is compressed with that format, it will first be decompressed. If the file seems compressed, but still can be validly interpreted in the specified (or inferred) format without decompression, a warning *will* be outputted. To prevent this, post-fix the ":" with another `:` on the explicit format specifier to disable automatic attempted decompression (for "raw=:", the second ":" is redundant, but either/or can still be specified.)
\# Some hashes may require size constraints on the salt, if the ":" of a specifier is prefixed with the character `~` (e.g. `raw~:`, `file~:`), then if the size of the read salt is lower than what is required, a correctly-sized nonce will *instead* be generated from the read salt using as many rounds of the `blake2` hash (/*XXX: is this still secure? should we choose an embedded salt for this at compile-time, or blake2 the `salt` specifier list and use that result instead? It cannot be random, since the hashes much match*/ unsalted) on the input needed to generate a nonce of the required size (usually, only one round will be applied to generate enough data to use, when reading a specific size, if the input is too large, the rest will just be discarded, the extra hashing round is only for inputs that are too small.)
\# Salt not required: `raw` (i.e, deny raw password strings delimited by newlines inside the wordlist.txt), `null`, same as raw, but delimited by the NUL character instead of newlines.
--restrict deny sha256 word salt \ # The same as above, but a single value specified on the command-line instead of a file containing a list of them, the same formatting rules for `deny-list` can be applied to "word" as can be "wordlist", and are interpreted the same, without the compression support or the `=` and `::` modofiers. The default for hashes (like `sha256`) is "hex:", and auto-detection is applied to validly encoded inputs. The default for `raw` is "raw:", since it is a raw string match and a password is likely not to contain encoded binary data, the explicit modifier can still be used for `raw` though, but by default it is interperted verbatim.
--restrict allow-list ... \ # See `deny-list`. This has the same arguments, and whitelists overrides restrictions on passwords denied by *previous*`deny[-...]``--restrict` directives, but not subsequent ones.
--restrict allow ... \ # See `deny`. This has the same arguments. Behaves the same as `allow-list` but for a single value.
@ -82,4 +82,15 @@ $ readpass --prompt "Please enter password" \ # Initial user prompt
--restrict whitelist ... \ # The same as `--restrict deny-all --restrict allow-list ...` (See restriction directive ordering rules for `allow/deny[-...]` directives. (TODO: explain them on completeness in another section of the README.md file.)
--restrict whitelist-single ... \ # The same as `--restrict deny-all --restrict allow ...`
--restrict plugin:<loaded-plugin-name> ... \ # Add a restriction rule from an externally loaded plugin (TODO: see Plugins section of README.md file)
--process <algo> [salt] [...[;]] \ # Postprocess the password *before* encrypting it with the `<output-public-key>`, applying a supported algo (or available loaded "plugin:[<plugin-ident>:]<algo>".) Supported algos are: Compression: `zstd`, `gz`, plugin-based, etc. Derivation (requires size argument after `salt`): `pbkdf2`, `argon2[i][d]`, `blake2`, plugin based etc. Hashing: All available hashing algorithms specified above in `deny-list` (which also includes plugin-based ones). Encryption: `[x]chacha20`, `[x]salsa`. Signing: `sign-<hash-algo>`, the signing key must be provided after `salt`. The signature will be appended to the data in the process chain.
\ # As well as format specifier changes ("hex", "base64", plugin-specific etc.). Salt specifying rules are the same as described by `deny-list` as well if a salt or nonce is required; or can be explicitly `none:`, the format-spec that just means "0 bytes of nothing, regardless of what is after the `:`".
\ # `--process` directives are applied in the order specified, so `--process zstd 11 \; --process argon2id hex:... [size=]255 lanes=4 \; --process sha256 none:` will: Compress the password with zstd compression level 11, then run the compressed data through argon2id with 4 lanes for 255 derived bytes with the specified nonce in hex format, then hash those 255 bytes with a saltless sha256, and *that* hash will be passed to the asymmetric encryption with `<output-public-key>`.
--preprocess <algo> [salt] [...[;]] \ # Same behaviour and rules as `--process`, except the process happens *after* the asymmetric encryption.
--raw-input \ # Do not treat terminal key-combinations such as U^ as they should be, but insert the keystroke in to the input directly
--show-length[=<char>] \ # Instead of printing nothing to the screen as the user is typing, the prompt should show the user the length of the string by outputting `<char>` for each new character read (and removing them when removed.) The default `<char>` is '*'.
hex:... > encrypted-password.socket # Specify `<output-public-key>` as hex-encoded, and write the output to a UNIX socket, which another process that created the socket and has the private key safely stored in its own memory can then read from and decrypt to get the user's provided password
# Rules may take fixed, variable, positional, and named arguments, the same as processes may take, (though they use variable ones far less often in general.) If the argument list is not fixed or contextually fixed, then the ';' will be required, if it is only contextually fixed, then the ';' isn't *required*, but might clarify your intentions to the program a bit better.
