View on GitHub

Thoughts, opinions, and occasionally rantings of a passionate technologist.

Managed Secrets

Secrets management is an important job, but it sucks. There. I said it.

Everybody needs secrets. What’s so hard about them?

How you store secrets and how you access them is all the developers care about. It’s all most people think of. Just about any solution can provide for that use case.

Anyone who’s actually run/managed a secrets system of any size knows that storage and access, while critical, are just the tip of the iceberg.

There’s more. Quite a lot more. Ask any security pro or gasp, an auditor.

Functional Requirements of a Secrets System

As a MVP, that’s pretty much it. The rest is all gravy. Any backend system aught to be able to handle those tasks, but they all need to be automated.

If they’re manual, they won’t be done as often or as quickly as needed. That’s just human nature.

Nonfunctional Requirements of a Secrets System

Here’s a short list of the ‘other’ concerns behind a secrets system:

The problem with all the above tasks is, they’re necessary, and individually they’re not hard.

They are, however, time consuming, boring, and inglorious, so most of the time, they don’t get done.

What’s that you say? They don’t get done? Surely you jest. No conscientious engineer would allow that laundry list of things to languish in the bottom of the ticket backlog.

I’m dead serious- and don’t call me ‘Shirley’. When’s the last time your secrets were rotated? Ask somebody in your company. Bet the response is something like “Uh… Probably never?”.

Secret Storage Backends

There are a bazillion of them to choose from. Every one of them has some way of getting your secret to your application, and I’m here to tell you which one you use doesn’t friggin matter.

Yes, you heard that. What secret backend you choose really doesn’t matter. (Within reason anyway.)

How can I say that? Because any secret storage backend worth considering, specially one offered by a reputable cloud provider or serious Open Source software vendor probably has all it’s little duckies in a row.

Big cloud providers like Amazon and Google almost certainly have their solutions audited/reviewed/vetted/certified by people who break into systems for a living. Others like Hashicorp Vault are Open Source, and anyone can read, peruse, comment, and propose changes.

Odds are, unless you’re trying to use something some idiot whipped up on a cocktail napkin, the secret storage backend of your choice is probably pretty decent.

Security software that’s sufficiently paranoid to protect your secrets is actually not that hard to write. You know what’s hard? Dealing with Humans.

Humans are the Problem

Ask any Sysadmin. The biggest headache they have are the users. (Operators of computer systems of course spell it with a silent ‘l’ - luser.)

We humans like to do what we’re interested in doing, and we don’t like being distracted by details that get in our way.

Case in point? Every use a public WiFi access point? Hmm? You’d be hard pressed to find a more INsecure means of using a computer.

You’d never lick the seat of a public toilet, but we’ll all connect to a public WiFi without even thinking about it. (And yes, it’s more or less the same thing, electronically speaking. At least the toilet is cleaned on some schedule. The router at Starbucks? Odds are it hasn’t been touched since it was first plugged in.)

The worst four letter word in technology is - wait for it - ‘just’. As in, “I just want to do X.”, or “I’m just trying to do Y.”. We humans happily ignore anything that doesn’t interest us and gets in the way of something that does.

Humans are the weak point in any security system. If it’s boring, or tedious, or not directly and visibly part of our ‘job description’, we generally don’t do it.

That’s why secrets sit un-rotated - forever. Human Nature.

The key to a successful secrets system lies in Human Nature. In understanding it. In finding ways to make it work for you.

Nobody ever (or at least rarely) thinks “I think I’m going to cause a data breach that destroys my company today.”. No, they just want to get ‘their job’ done.

They’ll do just about anything to meet that goal. If you can make the ‘most secure’ way also the ‘easy way’, they’ll do anything you ask.

Laziness can be a powerful ally.

UX is the Key

User Experience is the single most important factor in any tool’s adoption or success. Face it, if it’s a pain to use, it will be ignored, replaced, or circumvented.

That laundry list of ‘nonfunctional requirements’ listed above will never get done if your users are required to do any of them. They don’t care. They just want their app to get it’s secrets.

You also can’t hire anyone worth anything to do all that stuff, cos face it, it’s a boring job that can be better done by a computer.

The trick is getting the computer to do all the shit work so we humans can do what we do best - work on things we find interesting.

The Case for Managed Secrets

The perfect secret system should:

The computer should make this all happen, freeing the humans to just do their jobs.

What is ‘Managed Secrets’

Managed Secrets is basically a system in which you define your secret’s metadata in yaml, and let the tools do the rest.

It’s essentially a yaml interface on your secret access and storage system.

Let’s say that again: Managed Secrets is a YAML Interface on your Secret System. The code takes care of translating what you have placed in your YAML file, and translates that into reality in your secret storage system.

That’s what makes this approach so cool. Everybody gets what they want. Developers can ‘just get secrets’. Security Engineers and Auditors can get the reports/alerts they want.

Secrets can be rotated on schedule or on demand as needed. Everybody wins.

TLS Certificates and Private Keys are Secrets

When you think about it, TLS Certificates and Private Keys are secrets just like any other. They have their own lifecycle (expiration), are usually provided by an entirely different entity than the application code that depends upon them, and the authors of your services don’t really care what’s in them, they just want them to work.

There are systems like certbot, which let your app servers request their own certificates. This works, but it’s a little scary in that the thing connected to the outside world - the app server has the power to create and refresh the trust and encryption mechanism for your systems. Better in my opinion to separate the concerns, and let your internal, protected systems create your TLS certs, and deliver them to the point of use. This way, a cert (or a secret) can be compromised and you can rotate/change it, but the attacker will never have the ability to create credentials. Call me paranoid.

By treating Certificates and Keys as ‘just another secret’, we can deliver them in the same fashion as any other secret, and benefit from the same access and audit mechanism. Why work harder than you need to? K.I.S.S. (Keep It Simple, Stupid).


I chose Hashicorp Vault as the backend for my reference implementation, but you could write backends for AWS Secrets Manager, or SSM Parameter Store, or any other system.

I wrote it in Golang, because go has the wonderful ability to compile everything down to single binaries without dependencies, and easily cross compile for OS’es other than the one I, the author, work in.

None of these choices mean jack. I could have written it in Ruby and backed it by AWS SSM Parameter Store. The backend and the language really, Really, REALLY don’t matter. It’s the UX that counts here.

Too many people get lost in ‘solutioning’ and can’t see the forest for the trees. You create tools for users. Users don’t care about what’s going on under the hood. They care that the car goes when they want to go, and stops when they want to stop.

Design your tools for your users- one of which is undoubtedly yourself. You want powerful, easy to use tools don’t you? I sure do.

Managed Secrets Components

There are 4 components to Managed Secrets. I originally wrote this code for Scribd, and they were kind enough to allow me to publish it under the MIT License.

To the best of my knowledge, while Scribd uses Managed Secrets, they have no interest in maintaining or extending the code behind the system, so it seems likely as of the time of this writing that my forks of these repos will become the primary source for Managed Secrets.

These repos conform to my idea of MVC-Ish. In short, it’s 2 binaries that exercise libraries in the other repos. It was my intention that the libraries be used by other systems (programs, services, Lambda’s, etc), but the CLI binaries would provide both a reference implementation and a default tool that anyone could use from the CLI or a bash script.

The CLI binaries are separate from the library code so that they can be easily forked and customized for internal usage. The real meat of the solution is in keymaster and vault-authenticator, but a company’s actual implementation is customizable in the CLI tools. That way you can leverage the audit/review of the Open Source world, yet keep your own internal architectural details private.

This code, combined with a YAML config file, takes all the sting out of managing secrets for you, and for your users. Again, I wrote the reference implementation with Vault as a backend, and Vault is the Cadillac of secret storage engines, but the idea was that I could swap out the backend at anytime and my users wouldn’t know or care.

Users don’t interact with the storage system. They just write YAML files. Like this one:

Config Example

This example defines a Team, which is any logical grouping of people in a company.

name: test-team1                        # The name of the Team
secrets:                                # Definitions of the Secrets in the Team
  - name: foo
      type: alpha                       # A 10 digit alphanumeric secert
      length: 10

  - name: bar
      type: hex                         # A 12 digit hexadecimal secret
      length: 12

  - name: baz
      type: uuid                        # A UUID secret

  - name: wip
      type: chbs
      words: 6                          # A 6 word 'correct-horse-battery-staple' secret.  6 random commonly used words joined by hyphens.

  - name: zoz
      type: rsa
      blocksize: 2048                   # A RSA keypair expressed as a secret (Not currently supported)
  - name: blort                         # I've clearly run out of standard throwaway names here.
      type: static                      # Static secrets have to be placed manually.  API keys are a good use case for Static Secrets.

  - name:
      type: tls                         # A TLS Certificate/ Private Key expressed as a secret.
      ca: service                       # This cert is created off of the 'service' CA
        -                # Allowed alternate names for this cert
      ip_sans:                          # IP SANS allow you to use TLS and target an IP directly
roles:                                  # Your Secret Roles  This is what you authenticate to in order to access the Secrets above.
  - name: app1                          # A role unimaginatively named 'app1'
      - type: k8s                       # legal types are 'k8s', 'tls', and 'iam'
          - some-k8s-cluster            # for k8s, this is the name of the cluster.  Has no meaning for other realms.
          - app1                        # for k8s, this is the namespace that's allowed to access the secret
        environment: production         # each role maps to a single environment.  Which one is this?

      - type: tls                       # 'tls' specifies authenticated by client certs (generally only applies to SL hosts)
          -          # for tls, this is the FQDN of the host
        environment: development        # when this host connects, it gets development secrets

      - type: iam                       # only works if you're running in AWS
          - "arn:aws:iam::888888888888:role/some-role20201234567890123456789012"
        environment: staging            # each principal auths to a role in a single environment.
      - name: foo                       # These Secrets are defined above.  No 'team' in the config means 'team from this file'
      - name: wip
      - name: baz
        team: test-team2                # This secret is owned by another Team.
environments:                           # Environments are just strings.  Use whatever you want.   Many people would like Scribd to use standardized Environment names.  That's a people problem, not a tech problem.  To the code, they're all just strings.
  - production
  - staging
  - development                         # The 'development' environment is special.  If you have one, anyone who can authenticate can access development secrets.  This is intended to ease/ speed development.

With the above file, all you need is a properly configured instance of Keymaster-CLI to configure the secrets backend.

Your systems can use Keymaster-CLI (or something like it) to authenticate and get their secrets.

Heck, if they really want to, they can interact directly with the secrets backend directly. The storage and access system of your backend is still there, and could be used. The libraries described here are just a control / management plane on the backend.

Why someone would want to connect directly to the backend is beyond me. Doing so makes whatever you’re using less portable, and makes it more likely you’ll have to go back and change your code when the secret storage system changes or upgrades.

Managed Secrets is, again, basically just a YAML interface to your secret storage system. Interfaces are like fences. Good fences make for good neighbors.

Managing a secrets system is like making sausage. The diner doesn’t care how the sausage gets made. They just get to take a bite and enjoy. yum


Users don’t interact with the secrets backend to provision secrets. They don’t interact with it to obtain secrets either.

Using the secrets example tool, you use secrets fetch to fetch whatever secrets you’re allowed to have, and secrets exec to exec a subprocess with the secrets exported as ENV vars in your subprocess.

You can run secrets checksum to obtain a checksum of all secrets available to you, which allows you to detect whether they’ve changed, and if so, take whatever action is appropriate.

The whole idea of Managed Secrets is to give the user - in this case the application developer the UX they’ve always wanted - they want secrets to ‘just be there’ when they’re needed. Likewise the administrator gets the UX they want - they can control what goes where, and report to auditors about who obtained what, and when the need inevitably arises, they can instantly respond and ‘rotate’ (i.e. change) the secrets. Everybody wins!