Skip to content
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Securely manage privileged account credentials via Shamir secret sharing

What is the problem credmgr is trying to solve?

  • Root access is problematic for many reasons - if that requires further explanation this tool is probably not for you.
  • There are times when it may be absolutely necessary to have that root password, for example, in a disaster-recovery scenario.

How does credmgr work?

  • It generates a random password in memory (of configurable length and complexity).
  • It generates hashes (salted, of course!) from that cleartext password (still in memory) in any hash format passlib supports.
  • It shards the cleartext using Shamir sharing so that the cleartext is recoverable by joining back together a minimal subset of the shards.
  • It emails these shards to their respective shard-holders (encrypted to the shard-holder's individual GPG pubkey) along with contact details for the other shard holders and instructions for how to reassemble the cleartext.
  • It outputs all the requested password hash formats for deployment.

What kind of systems can credmgr create hashes for?

  • Short answer: a ton. Have a look at the passlib docs for a full listing.
  • BCrypt, PBKDF2, and SHA-512 are probably the most interesting.
    • Various Windows, DBMS, and other application-specific and/or archaic formats are also supported.

Recommended Deployment Strategy

  • Validate
    • Make sure you validate this in a test environment before you reset your root passwords in production!!!
      • Generate test password hash(es).
      • Create a test account(s) on all your target platform(s) and manually insert the credmgr-generated hash for the test account in /etc/shadow (or platform equivalent).
      • Verify that you can recover the cleartext password by reassembling the shards (using ssss-combine) and successfully gain access to the test account via su (or platform equivalent).
  • Prepare
    • You'll want to already have a good sudoers (or equivalent) setup in place so your system / network admins can continue to do their jobs.
      • Also test this, if you're moving away from a 'sudo su -' (or platform equivalent) workflow.
    • Establish and communicate a clear policy for under what circumstances the root password(s) can be recovered, workflows, management approval process, etc to put some accountability around this.
      • Decide who within your organization will hold shards for which systems and which privileged accounts (depends on your environment and the classification / sensitivity of your various systems).
    • Document and test the recovery procedure and integrate it with your site security procedures.
  • Deploy
    • Generate credmgr hash(es) for your target systems / platforms.
    • Deploy the password hashes across your whole environment, preferably via a configuration management system, cf.
  • Monitor
    • If you're using a log management tool that supports alerts or script execution based on log events, consider configuring it to watch for successful root logins and automatically generates a ticket for incident response and/or to regenerate and reset the affected root password.

How to get credmgr up and running:

  • Satisfy general platform dependencies

    • For the moment, credmgr will only run on a native posix system (or cygwin) because it makes a couple of fuggly-ass subshell calls.
    • It has only been tested on Debian and CentOS.
    • The crypto operations depend on lots of system entropy - if you're planning to run in a virtualized environment consider installing rng-tools or you may spend a lot of time waiting.
    • For the moment credmgr smtp is totally simplistic so you'll need to make sure that mails sent from localhost will get properly delivered.
  • Satisfy Python version dependencies

    • This has only been tested on python 2.7.
      • It may work under 2.6.
      • It probably won't run under 3.x.
  • Satisfy external binary dependencies:

    • You'll need to have gnupg up-and-running.
    • You'll need to have ssss installed
    • If you're running linux, there should be packages for both gnupg and ssss available in your native package manager.
      • If not, you'll have to build / package from source.
  • Satisfy Python module dependencies:

    • These are listed in requirements.txt.
    • Install these from pip or from your native package manager.
    • Note: I still haven't tested all of the passlib hashing algorithms; some of these will have their own external dependencies.
  • Initial configuration:

    • You'll need to have all the public keys for your shard-holders imported to your GPG keyring.
      • Consider creating a separate credmgr user and putting a dedicated, standalone GPG setup in its home directory so as not to create dependencies on your personal GPG keyring.
    • Checkout credmgr from github
    • cd credmgr/
    • cp example_config/* config/
      • Hint: you can have multiple config dirs
    • Put all your shard-holders' info into config/contacts.yaml
    • Put all your site-wide defaults into config/defaults.yaml
    • Use config/example_cred.yaml as a template for your credential-specific config(s)
      • Hint: settings in defaults.yaml and your credential-specific yaml are merged at runtime.
      • In case of conflict, settings in your credential-specific yaml take precedence over defaults.yaml.
      • You have to specifically list shard-holders (using the shard_holders array) in your defaults.yaml and/or your credential-specific yaml, ie, credmgr doesn't automatically include everyone listed in contacts.yaml and you can specify different sets of shard-holders for different credentials.
    • Take her for a spin!
      • --configdir path_to_config_dir --cred-yaml path_to_credential-specific_yaml
      • If everything's setup correctly:
        • You should see password hashes (in all your requested formats) on stdout.
        • You'll wait (up to a couple of minutes) for the shamir key-sharding operation, depending on your hardware and the availability of system entropy.
        • The configured shard-holders should receive individual emails, encrypted to their public-keys, providing their shard material, some explanation about what it's for, instructions for how to reassemble the cleartext, and a contact list for all the other shard-holders.

Planned for 0.2 release

  • refactor to use VIFF or python-shamir instead of ssss
  • refactor to use python-gnupg instead of calling gpg in a subshell
  • once these subshell calls are eliminated, credmgr should be portable to any platform that supports python
  • put a sqlite backend behind it to support more complex trust management scenarios and reporting capability, ie
    • show me all the active sets of credentials in my environment
    • regenerate all the credentials using $deprecated_hashing_scheme
    • operations around hiring / firing (or promote / demote trust, depending on your use case)
  • add cli flags to remove dependencies on yaml config
    • lets the thing be further automated via scripting
  • use gpg + web of trust in a more nuanced, less slap-happy way
    • use gpg keyring for whatever you can and move whatever can be shifted from contacts.yaml to it
    • enable (optional) use of master shards for credential management (keyring passphrase, signing of shard mails, encryption of sqlite db)
  • find ways to better protect the cleartext while it's held in memory
    • warn the user if the system is swapping to an unencrypted swap partition?
  • write a puppet class for better integration
  • provide an abstraction (perhaps a hash of a hash?) for nodes to indicate (via puppet reports) which root password they have set so as to provide a root password auditing capability
  • clean up code
    • write unit tests
    • add docstrings

Todo - future

  • create a receipt-confirmation system for shard-holders (something like mailman subscription system) so you can ensure there were no delivery problems prior to changing production password hashes
  • create a sort of state machine, trap kill signals, and try to ensure that there is no execution path that lands you in an indeterminate state
  • document (and add to requirements.txt) external dependencies for all the passlig hashing algorithms
  • i've got lots of other ideas but...i only have so much free time :-/


  • tl;dr: Use at your own risk!
  • You are free to use credmgr in any way you see fit, so long as you respect the terms of the license.
    • Apache License, Version 2.0 - cf. the project LICENSE file for further details.
  • There may be security problems with my implementation (remember, this is 0.1 code, my friend!)
    • I've asked a number of people within the infosec and sysadmin communities to review this; so far, no-one has pointed out any implementation flaws.
  • This is some rather ugly code; it couldn't be much farther from PEP8 compliance (Python styleguide).
  • credmgr presently lacks unit tests and docstrings.
  • This is a minimally-viable implementation intended to validate the concepts; refinements will follow.
  • There may be undisclosed vulnerabilities in the underlying dependencies (external binaries and python modules.)
    • This is also true for every other open-source project with external dependencies (which is basically all of them.)


Securely manage privileged account credentials via Shamir secret sharing




No releases published


No packages published


You can’t perform that action at this time.