This repository has been archived by the owner. It is now read-only.
A DEPRECATED file-system client for Keywhiz
Go Shell Makefile
Switch branches/tags
Nothing to show
Clone or download
Latest commit 0711e69 May 31, 2017
Permalink
Failed to load latest commit information.
fixtures Specify the server cert to use with the net/http/httptest server Sep 24, 2015
integration-tests Run integration tests in travis-ci Jun 30, 2016
log Non-blocking log wrapper, never block on syslog Aug 25, 2016
vendor Update go-fuse to latest version Aug 15, 2016
.gitignore Checked-in vendor/ directory Jun 29, 2016
.travis.yml
BUG-BOUNTY.md Includes this repo in our open source bug bounty program. May 11, 2015
CONTRIBUTING.md Initial open-source commit Mar 27, 2015
Dockerfile Checked-in vendor/ directory Jun 29, 2016
LICENSE.txt Initial open-source commit Mar 27, 2015
Makefile Run integration tests in travis-ci Jun 30, 2016
README.md Update README.md May 31, 2017
cache.go Avoid channel/goroutine leaks on timeouts Sep 26, 2016
cache_test.go Adds a test for the client.SecretList refreshing times on cached secr… Aug 8, 2016
client.go Use atomic pointers for holding on to http client Aug 25, 2016
client_test.go Adds metrics for failed communications with keywhiz server. Aug 4, 2016
docker.sh Build docker container on travis, update readme Jun 1, 2016
fs.go Avoid channel/goroutine leaks on timeouts Sep 26, 2016
fs_test.go Show .pprof dir, enable profile debug output Aug 16, 2016
glide.lock Update go-fuse to latest version Aug 15, 2016
glide.yaml Switch flag to kingpin. Apr 13, 2016
main.go Merge branch 'master' into stfinney/monitoring Aug 4, 2016
mount.kwfs Update mount.kwfs May 9, 2016
ownership.go More tests for ownership.go Mar 25, 2016
ownership_test.go More tests for ownership.go Mar 25, 2016
secret.go Flatten package structure and simplify build Mar 7, 2016
secret_test.go Flatten package structure and simplify build Mar 7, 2016
secretmap.go Fixes bug where cache does not refresh automatically Aug 8, 2016
secretmap_test.go Fixes bug where cache does not refresh automatically Aug 8, 2016
util_test.go Expose info via .json/status Mar 9, 2016

README.md

Status

We plan to deprecate keywhiz-fs shortly. While this approach has served us well, we've decided the advantages of using FUSE do not outweigh the operational difficulty. A mostly drop-in replacement is https://github.com/square/keysync

Overview

license build coverage

KeywhizFs is a client for Keywhiz which represents accessible secrets as a userland filesystem (using FUSE). This client will mount a directory which contains files for each secret that is accessible.

Exposing secrets as a filesystem has many benefits.

  1. Consumers of secrets require no special libraries or code.
  2. Unix user and group permissions restrict which processes can read a secret.

Transparently, authentication is performed with a Keywhiz server using mutually-authenticated TLS. A client certificate, trusted by Keywhiz, is required and used to authenticate KeywhizFs. Refer to the Keywhiz documentation for generating and managing client access.

Directory structure

KeywhizFs will display all secrets under the top level directory of the mountpoint. Secrets may not begin with the '.' character, which is reserved for special control "files".

Control files

  • .running
  • This "file" contains the PID of the owner process.
  • .clear_cache
  • Deleting this empty "file" will cause the internal cache of KeywhizFs to be cleared. This should seldom be necessary in practice but has been useful at times.
  • .json/
  • This sub-directory mimics the REST API of Keywhiz. Reading files will directly communicate with the backend server and display the unparsed JSON response.

Building

Run make keywhiz-fs to build a binary and make test to run tests.

We use glide to manage vendored dependencies.

Running

/etc/fuse.conf

In order to allow KeywhizFs to expose its filesystems to other users besides the owner of the process, fuse must be configured with the 'user_allow_other' option. Put the following snippet in /etc/fuse.conf.

# The following line was added for keywhiz-fs
user_allow_other

fusermount setuid permissions

The fusermount progam is used within the go-fuse library. Generally, it is installed setuid root, with group read/execute permissions for group 'fuse'. For KeywhizFs to work, the running user must be a member of the 'fuse' group.

mlockall / CAP_IPC_LOCK capability

To prevent secrets from ending up in swap, KeywhizFs will attempt to mlockall memory. This is not required, but is beneficial. To disable this behavior, pass --disable-mlock to keywhiz-fs on startup. Disabling mlockall means that secrets may end up in swap.

If you want to mlockall memory, you will need to make sure the KeywhizFs binary has the CAP_IPC_LOCK capability. On Linux, set the proper capability on the KeywhizFs binary so memory can be locked without running as root. Example assumes your binary is at /sbin/keywhiz-fs.

setcap 'cap_ipc_lock=+ep' /sbin/keywhiz-fs

Usage

usage: keywhiz-fs --key=FILE --ca=FILE [<flags>] <url> <mountpoint>

A FUSE based file-system client for Keywhiz.

Flags:
  --help                   Show context-sensitive help (also try --help-long and --help-man).
  --cert=FILE              PEM-encoded certificate file
  --key=FILE               PEM-encoded private key file
  --ca=FILE                PEM-encoded CA certificates file
  --asuser="keywhiz"       Default user to own files
  --group="keywhiz"        Default group to own files
  --debug                  Enable debugging output
  --timeout=20s            Timeout for communication with server
  --metrics-url=URL        Collect metrics and POST them periodically to the given URL (via HTTP/JSON).
  --metrics-prefix=PREFIX  Override the default metrics prefix used for reporting metrics.
  --syslog                 Send logs to syslog instead of stderr.
  --disable-mlock          Do not call mlockall on process memory.
  --version                Show application version.

Args:
  <url>         server url
  <mountpoint>  mountpoint

The --cert option may be omitted if the --key option contains both a PEM-encoded certificate and key.

Running in Docker

We have included a Dockerfile so you can easily build and run KeywhizFs with all of its dependencies. To build a kewhizfs Docker image run the following command:

docker build --rm -t square/keywhiz-fs .

After building, you can run the newly built image by running:

docker run --device /dev/fuse:/dev/fuse --cap-add MKNOD --cap-add IPC_LOCK --cap-add SYS_ADMIN --security-opt apparmor:unconfined square/keywhiz-fs --debug --ca=/go/src/github.com/square/keywhiz-fs/fixtures/cacert.crt --key=/go/src/github.com/square/keywhiz-fs/fixtures/client.pem https://localhost:443 /secrets/kwfs

Note that we have to pass --device /dev/fuse:/dev/fuse to mount the fuse device into the container, and give SYS_ADMIN capabilities to the container, so it can mount fuse-fs filesystems.

This build mounts the KeywhizFs filesystem at /secrets/kwfs/.

Contributing

Please contribute! And, please see CONTRIBUTING.md.