This repository has been archived on 2022-01-23. You can view files and clone it, but cannot push or open issues or pull requests.
vaultpass/docs
brent s. 7502b6a23b
this is kind of broken so it's being rewritten. just pushing some local changes first
2021-03-28 12:45:01 -04:00
..
README.adoc this is kind of broken so it's being rewritten. just pushing some local changes first 2021-03-28 12:45:01 -04:00
gendocs.sh more argument parsing 2020-04-03 11:44:34 -04:00
vaultpass.1.adoc fleshing out the args and adding stub manpage 2020-04-02 21:22:57 -04:00

README.adoc

VaultPass User Manual

Preface

What is Vault?

Vault by HashiCorp is a "secrets manager" - it securely protects various secrets with a very robust system of authentication and authorization.

It also provides an X.509 PKI system for certificates generation and a token/OTP generator.

What is Pass?

Pass ("The standard Unix password manager") is a password manager written entirely in bash and backed by GPG. Its fairly barebones in terms of technology but does a decent enough job.

What is VaultPass?

VaultPass attempts to bridge the gap between the two. It aims to be a drop-in replacement for the pass CLI utility via subcommands and other operations, but obviously with Vault as a backend instead of GPG-encrypted flatfile hierarchy.

Obviously since the backends are vastly different, total parity is going to be impossible but I try to get it pretty close. Important deviations are documented below.

Configuration

Unlike Pass, PassVault requires a persistent configuration. At the very least, the authentication method needs to be specified.

The default location for the configuration file is ~/.config/vaultpass.xml. Its an XML document formatted with the following structure:

  1. The XML prolog, specifying the character encoding of the document and XML version.[1]

  2. The root element (vaultpass). This element contains attributes describing parsing/validation specifics as well, such as the namespace definitions and schema location.[1]

    1. The server element. This element is a container for connection and management of the Vault server and is required (even though it may not have any children). This consists of:

      1. A single uri element.[2] It should be the same as the base URL for your Vault server. If not specified, the default is to first check for a VAULT_ADDR environment variable and, if not found, to use http://localhost:8200/.

      2. An unseal element[2], which can be used to (attempt to) automatically unseal the server if it is sealed. This isnt required, but can assist in automatic operation. One of either:[2]

        1. unseal, the unseal key shard (a Base64 string), or

        2. unsealGpg, the unseal key shard encrypted with GPG. See the section on GPG-Encrypted Elements.

      3. A required authentication directive which specifies how we should authenticate to Vault. It should be comprised of one of either:

        1. auth (see Auth section below), or

        2. authGpg, an Auth config snippet encrypted with GPG. See the section on GPG-Encrypted Elements.

      4. An optional mounts container.[2] See the section on Mounts.

If you would like to initialize Vault with VaultPass, use a self-enclosed Token auth stanza. It will automatically be replaced once a root token is generated.

Lets look at an example configuration.

Example Configuration

~/.config/vaultpass.xml example:
<?xml version="1.0" encoding="UTF-8" ?>
<vaultpass xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xmlns="https://git.square-r00t.net/VaultPass/"
           xsi:schemaLocation="https://git.square-r00t.net/VaultPass/ http://schema.xml.r00t2.io/projects/vaultpass.xsd">

    <server>
        <uri>http://localhost:8200/</uri>
        <unseal>YOUR_UNSEAL_SHARD</unseal>
    </server>
    <auth>
        <token/>
    </auth>
    <mounts>
        <mount type="kv1">secret_legacy</mount>
        <mount type="kv2">secret</mount>
        <mount type="cubbyhole">cubbyhole</mount>
    </mounts>

</vaultpass>

In the above, we can see that it would use the Vault server at http://localhost:8200/ using whatever token is either in the VAULT_TOKEN environment variable or, if empty, the ~/.vault-token file. Because an unseal shard was provided, it will be able to attempt to automatically unseal the Vault (assuming its shard will complete the threshold needed). Because we specify mounts, we do not need permissions in Vault to list /sys/mounts (but if our token has access to do so per its policy, then any automatically discovered will be added).

Auth

Vault itself supports a large number of authentication methods. However, in the interest if maintainability, this project has limited support to only the most common authentication methods. More authentication methods may be added in the future upon request.

Note
All of these (except for Token) require configuration in Vault first. Configuration of those authentication methods is out of scope for this document and project. Please ensure that your authentication works as expected in the Vault CLI utility or via the Vault API first before submitting a bug report in VaultPass.

AppRole

AppRole takes two required children elements:

  1. appRole (the container element)

    1. role, the AppRoles RoleID, and

    2. secret, the AppRoles SecretID.

Example Snippet
<!-- SNIP -->
    <auth>
        <appRole>
            <role>my-role</role>
            <secret>37b74931-c4cd-d49a-9246-ccc62d682a25</secret>
        </appRole>
    </auth>
<!-- SNIP -->

LDAP

LDAP takes two required children elements and one optional child element:

  1. ldap (the container element)

    1. username, the username (as according to the userdn and userattr settings in the configuration)

    2. password, the password for the account object.

    3. mountPoint [2], the mount point for the LDAP authentication in Vault. The default, if not provided, is ldap.

Example Snippet
<!-- SNIP -->
    <auth>
        <ldap>
            <username>mitchellh</username>
            <password>MyPassword1</password>
            <mountPoint>ldap</mountPoint>
        </ldap>
    </auth>
<!-- SNIP -->

Token

Token auth is the most basic supported authentication in Vault and can be used without any further configuration.

It consists of, at its most basic (and "automagic") configuration, a single elementbut this can be configured more in-depth/explicitly.

  1. token (the container element)

    1. The token itself or content/source of the token.[2]

It has one optional attribute: source.[2]. It can be one of the following:

  • env:MY_TOKEN_VAR, in which environmental token MY_TOKEN_VAR will be sourced.

  • A filesystem path, in which the file is assumed to contain the token (and ONLY the token).

To determine the behaviour of how this behaves, please refer to the below table.

Table 1. Determining token behaviour
No. If… Then…

1

self-enclosed, no source

The VAULT_TOKEN environment variable is checked. If not defined, the file ~/.vault-token will be checked. If that file doesnt exist, a RuntimeError will be raised.

2

self-enclosed, source given

The source is assumed to be the only source and no automatic detection will occur.

3

token contained in tags, no source

The specified token will be used and no automatic detection will occur.

4

token contained in tags, source given

Same as 3; source is ignored.

If the Vault instance is not initialized and a vaultpass init is called, the configuration file will be updated to use token auth, populated with the new root token, and populated with the new unseal shard. (The previous configuration file will be backed up first!).

Example Snippet
<!-- SNIP -->
    <auth>
        <!-- "Automagic" (#1).
             First $VAULT_TOKEN environment variable is checked,
             then ~/.vault-token is checked. -->
        <token/>

        <!-- Source is considered the only place to fetch token from (#2). -->
            <!-- This would check the environment variable $SOMEVAR -->
        <!-- <token source="env:SOMEVAR"/> -->
            <!-- This would use the contents of ~/.vault-token.alt -->
        <!-- <token source="~/.vault-token.alt"/> -->

        <!-- Token explicitly given is the only one used. -->
        <!-- <token>s.Lp4ix1CKBtJOfA46Ks4b4cs6</token> -->

        <!-- Token explicitly given is the only one used; source attribute is ignored. -->
        <!-- <token source="env:THIS_IS_IGNORED">s.Lp4ix1CKBtJOfA46Ks4b4cs6</token> -->
    </auth>
<!-- SNIP -->

User/Password

Vaults userpass authentication method must be configured beforehand, but its a relatively simple configuration.

VaultPass user/password authentication takes two required children elements and one optional element.

  1. userpass (the container element)

    1. username, the username of the account.

    2. password, the password for the account.

    3. mountPoint [2], the mount point for the auth. If not specified, the default is userpass.

Example Snippet
<!-- SNIP -->
    <auth>
        <userpass>
            <username>mitchellh</username>
            <password>foo</password>
            <mountPoint>userpass</mountPoint>
        </userpass>
    </auth>
<!-- SNIP -->

Mounts

VaultPass has the ability to automatically detect (some) mounts and their paths.

So why, then, should you specify them in the configuration file? Simple: because you might not have permission to list them! Even if you can see the mounts in the web UI that you have permission to, that doesnt guarantee that theyre accessible/viewable via the API (which is how VaultPass, and even the upstream Vault binary client, operates). So by specifying them in the configuration file, youre able to "bootstrap" the process.

The optional mounts [2] container contains one or more mount child elements, with the name of the mountpoint as the content.

Each mount element has one optional attribute, type [2], which can be one of:

More mount types may be added upon popular demand and technical feasability.

GPG-Encrypted Elements

Understandably, in order to have a persistent configuration, that means storing on disk. That also means that they need to be able to be accessed with no or minimal user interruption. Pass used GPG natively, so it didnt have an issue with this; since gpg-agent is typically spawned on first use of a GPG homedir (usually ~/.gnupg/ by default) and keeps an authenticated session open for 10 minutes (by default).

To get around needing to store plaintext credentials on-disk in any form, VaultPass has unsealGpg and authGpg elements. These elements are of the same composition (described below) and allow you to use GPG to encrypt that sensitive information.

While this does increase security, it breaks compatibility with other XML parsers - they wont be able to decrypt and parse the encrypted snippet unless explicitly coded to do so.

*Gpg elements

*Gpg elements (authGpg, unsealGpg) have the same structure:

  1. unsealGpg/authGpg, the container element.

    1. The path to the encrypted file as the contained text.

It has one optional attribute, gpgHome [2]the GPG home directory to use. If not specified, VaultPass will first check the GNUPGHOME environment variable. If that isnt defined, well default to ~/.gnupg/ (or whatever the compiled-in default is).

The contents of the encrypted file should match the unencrypted XML content its replacing.

Caution
Note that if you use namespaces in your vaultpass.xml config file, you MUST use matching declarations in your encrypted file. You MAY exclude the xsi:schemaLocation specification, however, if its the same as your vaultpass.xml. It is highly recommended that you use the same xsi:shemaLocation, however (or leave it out entirely).

Lets look at an example of GPG-encrypted elements.

GPG-Encrypted Elements Example

~/.config/vaultpass.xml:
<?xml version="1.0" encoding="UTF-8" ?>
<vaultpass xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xmlns="https://git.square-r00t.net/VaultPass/"
           xsi:schemaLocation="https://git.square-r00t.net/VaultPass/ http://schema.xml.r00t2.io/projects/vaultpass.xsd">

    <server>
        <uri>http://localhost:8200/</uri>
        <unsealGpg gpgHome="~/.gnupg">~/.private/vaultpass/unseal.asc</unsealGpg>
    </server>
    <authGpg gpgHome="~/.gnupg">~/.private/vaultpass/auth.gpg</unsealGpg>
</vaultpass>

As shown, it supports both ASCII-Armored and Binary encryption formats.

ASCII-Armored

Encrypted
~/.private/vaultpass/unseal.asc contents:
-----BEGIN PGP MESSAGE-----

hQIMA7QuYg9nGdZdAQ//eHvEZ7vpLvygM2ofIiT2uW7cWYQaYm/09li7s0+0ZqTu
hNki7oIQ1Ip+k6ds45eEXPG6hXwZ7+mtIDG8VcYpo0PdwpvcJ9qqAgvnFAynvjgH
pRkeIw4VUfGxxhs8oZMvdrXuYtwzaXIhn0UuZv+cIS1Jj6IfG0xSpRvd+M0MW+Wk
IWSIyUcY6fkP7MFEiId7sQwm6htHXJDqiVAmwn4lqk2CnIhtsTd5HUyRzGg5gZs+
sFAssa7QjoBKJMkTDVH4EIC4GcgNtTB/rg7XBoX1k36CHZAwB/boZ5arMYswwkYp
VFv9At13vkkRMf23bb7siq7U0Vbvs0PGsFJS/1ivS1IyzFGFZGHaTz7ndk2q2iyY
tMjMe+z+i2VAGvtfdE7H4K4TrqrM9OZ81vyJkEjRBrkSfR9sWOgv5yBFDvoeVkZl
k1gRXLkrF/7eZn8vD17oOew/zr+um7s/rTtLp5GEknOsKzb1NOMBHP44dXdxNreT
HdRlNDLgOp2KffXgNSm/A026tMSA0nf0kpJmR1yLjucKPoy6wVrTMh+sLNubgxmZ
BCz64myu8dfWtHQfPSis1kjrs15mfQoOu9Cl9st8gTs50sKWTa+dGdajZEcz8rcX
OMBLwiTQodP/0uRHf8YofIFk86QXbYALd4WsC/KvDQBiaz8HRcfkccDQCHQvdLrS
wEkBuhCZj1OqUnTXg0qggMD0Hp2pO0CqD4uZ3RHvIt49W+7oUr22Y4VarRNeP06x
JhYC3Sr0RXv/Vi21DMiUUUAXYeYKP82HpP0zSZhCcwVZZje1dXwq85SH04u9pT+n
f2JqgATxmAaepQZCANxAluknfSluuCBi0hmhagYY2IsgKmJcSsksm0AWfGyzgoeV
ZypDlE3MuERVLJSDBjZtfnScy3CeTWWj5vw7Nfm5XEqOuIIbZaTV/qb6i6y4rc6k
Yx5xYKHeuXJGbrQdVJemcXyDIV5tDw5RtLpO57EwL+uEYgSbN9rO/N2B83QjB7D5
lCmbJtQcjxG/eJ/SrB2oS47YdEKRy+cH0Xx+
=scGv
-----END PGP MESSAGE-----
Decrypted
<unseal xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns="https://git.square-r00t.net/VaultPass/"
        xsi:schemaLocation="https://git.square-r00t.net/VaultPass/ http://schema.xml.r00t2.io/projects/vaultpass.xsd">1fs1tV46ebb6awF6edtuzsoEawZlBARFp5rSaED+EJI=</unseal>

Binary

Encrypted
~/.private/vaultpass/auth.gpg contents:
<BINARY DATA>
Decrypted
<auth xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns="https://git.square-r00t.net/VaultPass/"
        xsi:schemaLocation="https://git.square-r00t.net/VaultPass/ http://schema.xml.r00t2.io/projects/vaultpass.xsd">

    <token>s.Lp4ix1CKBtJOfA46Ks4b4cs6</token>

</auth>

Known Incompatibilities with Pass

PASSWORD_STORE_ENABLE_EXTENSIONS,.extensions/COMMAND.bash, and Default Subcommands

Issue Description

Per the Pass man page:

PASS(1)
If no COMMAND is specified, COMMAND defaults to either show or ls, depending on the type of specifier in ARGS. Alternatively, if PASSWORD_STORE_ENABLE_EXTENSIONS is set to "true", and the file .extensions/COMMAND.bash exists inside the password store and is executable, then it is sourced into the environment, passing any arguments and environment variables. Extensions existing in a system-wide directory, only installable by the administrator, are always enabled.

Due to this being Python, we lose some of this compatibility. It may be possible to add this functionality in the future, but its lower priority currently.

Similarly, we cannot set a default subcommand as of yet in Python via argparse (the library that VaultPass uses to parse command-line arguments).

Workaround(s)

You can set an alias in your ~/.bashrc that will:

  1. Execute show by default

  2. Provide a direct command for ls operations

  3. Specify default options for a command

Via the following:

~/.bashrc:
# ...

# 1
alias pass='vaultpass show'

# 2
alias lpass='vaultpass ls'

# 3
alias vaultpass='vaultpass -c ~/.config/alternate.vaultpass.xml'

To use the non-aliased command in Bash, you can either invoke the full path:

/usr/local/bin/vaultpass edit path/to/secret

Or, alternatively, prefix with a backslash:

\vaultpass edit path/to/secret

Finally, you can always use VaultPass by specifying the subcommand and disregard aliases entirely.

find/search Subcommand Searching

Issue Description

Pass used find(1) to search secret paths. Because we use Vault and not a filesystem hierarchy, this isnt applicable. As such, the normal find globbing language is not supported…

Workaround(s)

What is supported, however, is regular expressions' ("regex") match patterns.

If you havent used regexes before, here are some helpful starters/tools:

Regular expressions are MUCH more powerful than the find globbing language, but do have a slight learning curve. You will be thankful to learn their syntax, however, as they are very widely applicable.

Environment Variables

Issue Description

Pass (and to a slightly lesser extent, Vault) relies almost entirely/exclusively upon environment variables for configuration. VaultPass does not.

Workaround(s)

Relying entirely on environment variables for configuration is dumb, so I dont do on that. All persistent configuration can be either specified in the configuration file or can be overridden by flags/switches to subcommands. Some configuration directives/behaviour may be overridden by environment variables where supported by Vault/Pass upstream configuration.

Vault Paths Dont Match VaultPass' Paths

Issue Description

Pass and Vault have fundamentally different storage ideas. Pass secrets/passwords are, once decrypted, just plaintext blobs. Vault, on the other hand, uses a key/value type of storage. As a result, this means two things:

  • The last item in a path in VaultPass is the key name (e.g. the path foo/bar/baz in VaultPass would be a Vault path of foo/bar, which would then have a key named baz), and

  • The line-number sub-argument is completely irrelevant for things like copying to the clipboard and generating a QR code (e.g. as in pass show --clip=line-number).

Workaround(s)

None, aside from not using the line-number sub-argument since its no longer relevant. (Youll get an error if you do.)

Unable to specify line-number

See above (Vault Paths Dont Match VaultPass' Paths).

Deleting Secrets in KV2

Issue Description

In Pass, because it doesnt have versioning (unless youre using git with your Pass instance). Vaults kv2 engine, however, does have versioning. As a result, once a secret is "deleted", it can still be recovered via an undelete method. If you are deleting a secret for security reasons, you may want to destroy it instead. VaultPass' delete method uses a delete rather than a destroy.

Workaround(s)

VaultPass has a new subcommand, destroy, which will remove versioned secrets permanently. Use with caution, obviously. If called on a non-KV2 mounts path, it will be the same as the delete subcommand.


1. These arent strictly necessary, but will make cross-parsing and validation MUCH easier. Its highly recommended to use them.
2. This element/attribute/text content is optional. See the items description for how default values/behaviour are determined.