vaultpass/docs

VaultPass User Manual

Table of Contents

• Preface
  • What is Vault?
  • What is Pass?
  • What is VaultPass?
• Configuration
  • Example Configuration
  • Auth
    • AppRole
      • Example Snippet
    • LDAP
      • Example Snippet
    • Token
      • Example Snippet
    • User/Password
      • Example Snippet
  • GPG-Encrypted Elements
    • *Gpg elements
    • GPG-Encrypted Elements Example
    • ASCII-Armored
      • Encrypted
      • Decrypted
    • Binary
      • Encrypted
      • Decrypted

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. It’s 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.

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. It’s 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.^[2] This element is a container for connection and management of the Vault server. This consists of:

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

      2. An unseal directive, which can be used to (attempt to) automatically unseal the server if it is sealed. This isn’t 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.

Let’s 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:8000/</uri>
        <unseal>YOUR_UNSEAL_SHARD</unseal>
    </server>
    <auth>
        <token/>
    </auth>

</vaultpass>

In the above, we can see that it would use the vault server at http://localhost:8000/ 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).

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 AppRole’s RoleID, and

   2. secret, the AppRole’s 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 element — but 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 doesn’t 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.

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

Vault’s userpass authentication method must be configured beforehand, but it’s 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 -->

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 didn’t 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.

Note that while this does increase security, it breaks compatibility with other XML parsers - they won’t 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 some optional attributes as well:

Table 2. *Gpg element attributes

Attribute	Content
keyFPR [2]	The GPG key to use to decrypt the file. It accepts multiple key ID formats, but it’s highly recommended to use the full 40-character (without spaces) key fingerprint. If not specified, VaultPass will use the first private key it finds in the keyring.
gpgHome [2]	The GPG home directory. If not specified, VaultPass will first check the GNUPGHOME environment variable. If that’s empty, we’ll default to ~/.gnupg/.

The contents of the encrypted file should match the unencrypted XML content it’s replacing.

Caution

Note that if you use namespaces in your vaultpass.xml config file, you MUST use matching declarations in your encrypted file.

Let’s look at an example of GPG-encrypted elements.

GPG-Encrypted Elements Example

~/.config/vaultpass.xml snippet:

<?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:8000/</uri>
        <unsealGpg keyFPR="D34DB33FD34DB33FD34DB33FD34DB33FD34DB33F"
                   gpgHome="~/.gnupg">~/.private/vaultpass/unseal.asc</unsealGpg>
    </server>
    <authGpg keyFPR="D34DB33FD34DB33FD34DB33FD34DB33FD34DB33F"
               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>

---

1. These aren’t strictly necessary, but will make cross-parsing and validation MUCH easier. It’s highly recommended to use them.

2. This element/attribute/text content is optional. See the item’s description for how default values/behaviour are determined.