This is an article in the category of dumping my internal wiki to this blog.

Encrypted Passwords in Bash Scripts with EncPass

encpass.sh provides a lightweight library to use encrypted passwords in shell scripts. Passwords or other secrets can be encrypted at runtime and then used, decrypted, within scripts.

The default OpenSSL implementation generated an AES 256 bit symmetric key for each script or user-defined bucket that stores secrets. This key will obviously be used to encrypt all secrets for that script or bucket.

Subsequent calls to retrieve a secret will not prompt for a key to be entered as the file with the encrypted value already exists.

Note: By default, EncPass sets up a .encpass directory under the user's home directory where keys and secrets will be stored. This contains the following subdirectories:

• keys: holds the private key for each script or user-defined bucket
• secrets: contains the secrets stored for each script or user-defined bucket
• exports: contains any export files created by the export command

Installation

Download the EncPass script, place it in a directory on the path and make it executable:

sudo curl https://raw.githubusercontent.com/ahnick/encpass.sh/master/encpass.sh -o /usr/local/bin/encpass.sh
sudo chmod a+x /user/local/bin/encpass.sh

A light version, which can only read and write secrets, can be created as follows:

sudo encpass.sh lite > encpass-lite.sh
sudo mv encpass-lite.sh /usr/local/bin/encpass-lite.sh
sudo chmod a+x /usr/local/bin/encpass-lite.sh

Note: Move the files to the /bin directory, if EncPass is used in cronjobs that will be run as root.

Command Line Management

EncPass provides a command line interface to perform various management functions, such as:

• Add secrets/buckets
• Remove secrets/buckets
• List secrets/buckets
• Show secrets/buckets
• Lock/Unlock all keys for buckets
• Import/Export secrets/buckets

Creating Secrets

To add a secret to a bucket, the add command can be used:

encpass.sh add [f] bucket secret

Would create the secret secret for bucket bucket. If the bucket does not yet exist, the bucket will be created. If the secret already exists in the bucket, the user will be prompted whether the secret should be overriden or not. If the -f option is specified, a forceful overwrite of the secret will happen automatically.

Updating Secrets

In a similar way, the update command can be used to update secrets. This command is similar to using an add -f" command, but it has a safety check to only proceed if the specified secret exists.

encpass.sh update bucket secret

Removing Secrets

To remove a secret from a bucket, the remove command can be used. If only a bucket is specified then the entire bucket will be deleted. By default the user is asked to confirm the removal of the secret or the bucket. This prompt can be automated by passing the -f option.

encpass.sh remove bucket secret

List Secrets

To list all secrets in a bucket, simply use the list command:

encpass.sh list bucket

Note: If no bucket is specified, then the names of all existing buckets will be displayed.

Revealing Secrets

To show the unencrypted value of a secret from a specified bucket, the show command can be used:

encpass.sh show bucket secret

If no secret is specified then all secrets for the bucket are displayed. If no bucket is specified then all secrets for all buckets are displayed.

Importing and Exporting Buckets

Buckets can be imported and exported using the import and export commands:

encpass.sh export -k -p bucket secret

Check the man page for further information.

Man Page

To view the man page for EncPass, call

encpass.sh ?

Using in Scripts

There are three ways to get secrets.

When no arguments are passed to the get_secret function, then the bucket name is set to the name of the script and the secret name is set to password.

#!/bin/sh
. encpass.sh

password=$(get_secret)

- bucket name = <script name>
- secret name = "password"

When only a secret name is specfied, the bucket still defaults to the name of the script.

#!/bin/sh
. encpass.sh

password=$(get_secret user)

- bucket name = <script name>
- secret name = "user"

If both the secret and bucket are specified, no default values are used:

#!/bin/sh
. encpass.sh

password=$(get_secret personal user)

- bucket name = "personal"
- secret name = "user"

Note: For most scripts it will be enough to use the encpass-lite version.

Security Warning

Although EncPass encrypts every secret on disk within the user's home directory, once the password is decrypted within a script, the script author must take care not to inadvertently expose the password. For example, if a script invokes another process that is using the decrypted password and, then the password would be visible to ps:

#!/bin/sh
. encpass.sh
password=$(get_secret)
watch whatever.sh --pass=$password &

ps -A
97349 ??         9:56.30 watch whatever.sh --pass=P@$$w0rd

References

EncPass