NAV Navbar
php

Introduction

Welcome!

Welcome to our documents and support! Even though Lockr is an easy-to-use service for WordPress or Drupal, occasionally users run into some challenges and we want to help you through it. Below are some resources to help guide you through the installation, registration, and use of Lockr.

When necessary, you can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

These docs are open to public editing, you can find them at our github page. Feel free to submit pull requests and help us make the docs better with your experiences.

Additional Support

If you'd like support outside these docs, we're here to help! You can find us on our slack channel

Lockr Automated Hosts

Lockr Integrated Authentication

Lockr partners with hosting providers and website platforms to provide integrations with Lockr which make registration and use simple and secure. Partners with integrated authentication allow for simple registration because the partner manages the secure authentication to Lockr. This means no extra steps, outside of connecting your site with a KeyRing, are necessary. This is the easiest way to use Lockr is with one of these providers, and we highly recommend using these platforms.

Lockr Automated Setup

In addition to hosts with integrated authentication, Lockr has also automated setup to handle the certificates for development and production once initial setup has occurred. Users on these hosts will only need to go through the initial setup with their Lockr account and KeyRing, at which point the automation will take care of the placement of the certificates for access. Currently Lockr does this for:

Lockr General Concepts

Lockr is a secrets management service, which integrates into any application to provide a secure way to store values such as API tokens, passwords, and encryption keys. Currently Lockr provides integrations with Drupal and WordPress which allow for registration, and storage without any extra code necessary.

Below are some general concepts to understand when using Lockr.

KeyRings

Lockr groups secrets together into KeyRings, which are the basis for billing. Each KeyRing will be attached to an independent subscription. This makes it possible to have different KeyRings with varying subscription levels and billing frequencies.

One of the main distinctions of KeyRings is they can be used by any number of applications. Previously, we grouped secrets by "sites" but this became difficult to translate into non-website applications. Also, we found many times in setting up the integrations, developers accidentally created multiple site subscriptions leading to billing issues. We hope to eliminate this not only through the new registration workflow but by making it more apparent when creating a new KeyRing the billing impact.

Client Certificates

What good is an API token to secure an API token? We asked ourselves the same question when coming up with Lockr, which is why we rely on x509 certificates for authentication. These client certificates aren't unlike the ones used to provide SSL on your website, and allow us to cryptographically prove the source of the value. It also allows us to quickly invalidate and re-issue new certificates should one get lost or compromised during an attack.

These certificates are at the heart of all that Lockr does. They provide us a secure way to validate the request, encrypt the transmission of the data to Lockr, and identify the site and environment the request is coming from. Because of this, it's important to keep these certificates in a safe location. If you're on a integrated authentication partner you're taken care of, it's all handled behind the scenes at the host. If you're not, we have automated partners where we set them into a safe location for you. If you're not on these partners have no fear, Lockr can still be used and we've put together a guide on how to make sure you put certs into a safe location.

With the addition of the KeyRing feature, there can now be any number of client certificates created to access a single KeyRing. This allows multiple development environments to all be issued individual client certificates, giving more in-depth access control. Production client certificates can also be issued to multiple environments/applications, but only by going through two-factor authentication first, this ensures production certificates are not issued without the account holder knowing.

How Lockr protects secrets

Lockr takes protecting secrets very seriously and appreciates the trust our customers put in us to keep them safe. To do this, we make sure each layer of our system is built to meet or exceed industry standards for security and availability.

Layers of Encryption

Lockr deploys multiple layers of encryption in order to protect secrets. The first and foremost layer of encryption happens before the value even leaves your site. The Lockr modules and plugins encrypt the value to be stored using AES 128 bit encryption with a SHA256 HMAC. If you know what this means, you know that's secure. If you don't, to put it in perspective, it will take 10 years, using all the energy output for the entire earth to compute a single value (assuming technology continues to double till the year 2040).

The process of encrypting secrets is called key wrapping, as it takes one value, and encrypts (wraps) it using a second key. Lockr takes the second key, usually termed the KEK (key encryption key) and stores it in the website in place of the original value. This KEK does not have any function outside securing the value stored in Lockr so it is safe to store on the site. Anyone gaining access to this key still does not have the original value, and since they are not related or a derivation of the value, it's useless to an attacker.

Lockr then takes the encrypted value to be stored, and sends it over a secure, encrypted connection to the Lockr servers. Once in Lockr, it is routed to and stored encrypted at rest inside a an HSM (Hardware Security Module), provided by Townsend Security.

This is what's termed "end to end encryption" as the value sent to Lockr is encrypted before being transmitted and only able to be decrypted where it started. Lockr cannot at anytime view, modify, or lose your value.

Separate Environments

One of the benefits of Lockr, besides storing your values in a secure encrypted HSM, is that values for development and production environments are isolated from each other. This is done for a number of reasons:

  1. If you are encrypting values with a key stored in Lockr, those values will not be able to be decrypted in development environments. This is important in regulated environments where you need to be able to control who has access to encrypted data.
  2. Admit it, we've all done it. You've accidentally sent an email from a development environment to a production service. Lockr helps keep your development environment isolated by keeping your production tokens and keys away from developers. (If you want horror stories of why this is important just ask us, we've seen some good ones)

This can cause some confusion for first time users, but once synchronized it becomes a background process that keeps data where it should be and developers safe from accidentally triggering production events.

Download and Installation

Downloads

Drupal Module

Drupal is where Lockr got its start, as a simple and secure way to store encryption keys and secrets via the key module. You can find Lockr for Drupal and download it from our module page.

Below we'll go through how to download, install, and register Lockr on both Drupal 7 and Drupal 8. Once you have the module installed, the UI for registration and key management between the two versions is very similar. Be sure to download the Key module along with Lockr as it's a dependency for it to function.

WordPress Plugin

You can download Lockr for WordPress from our plugin page.

PHP Library

We have our php library, which is used by both the Drupal and WordPress plugins, available on packagist here

Drupal 7 Installation

When installing a module on Drupal 7, you first need to get the module files into the right spot. Once you have the files where you need them, you likely will need to commit them to your version control (likely git) or SFTP them into the server. We highly recommend using git as a version control system as it is the most secure way to manage site files. If you do need to upload them directly to the server, be sure to use SFTP and not FTP.

Download the files

Upload the newest version of the Lockr and Key modules to the below file path. Once placed in that folder path, login and activate the plugin. Then jump to set up and registration.

/sites/all/modules/contrib

Command Line (Drush)

Using Drush to install Lockr is the easiest way, if you're comfortable in the command line. Once installed you can simply run drush dl lockr key to download the modules.

Enable the Module

Once you've got the modules into the site directory, you can then enable them by going to /admin/modules and checking the box next to Key and Lockr, then clicking the Save Configuration button at the bottom of the screen. The Ctools is required as well but you likely already have this enabled as it's standard requirement to a lot of Drupal modules.

Drupal 8 Installation

In Drupal 8, installation is done through composer as this is the best practice recommended. To download the module as well as the php library from your command line, inside the site folder run: composer require drupal/lockr

This will download not only Lockr but all the requirements and update the composer.json with these requirements.

Once you've got the module into the site, you can then enable them by going to /admin/modules and checking the box next to Key and Lockr, then clicking the Install button at the bottom of the screen.

WordPress Installation

When installing a plugin on WordPress, like any CMS, there are multiple ways to accomplish it. In essence you will need to download the plugin and make sure it is in the right directory /wp-contents/plugins. Once you have the files where you need them, you likely will need to commit them to your version control (likely git) or SFTP them into the server. We highly recommend using git as a version control system as it is the most secure way to manage site files. If you do need to upload them directly to the server, be sure to use SFTP and not FTP.

File Upload

Download the Lockr plugin and upload to the /wp-contents/plugins directory of your website. As mentioned above, this can be done either by downloading and checking it into your version control system (git) or via SFTP directly to the site/server. Once placed in that folder path, login to the admin dashboard and activate the plugin by clicking the activate link next to the plugin. (/wp-admin/plugins.php). Once activated, jump to setup and registration.

WP-CLI

WP-CLI is a command line interface to do many necessary and advanced functions for your WordPress site. More information on it can be found here and here.

With WP-CLI you simply need to run the following command: wp plugin install lockr - activate

WordPress Dashboard

If your server allows for it, you are able to install Lockr directly from your WP-Admin dashboard (/wp-admin on your website). Access the WordPress Plugins in the left admin panel. This will bring you to the list of currently installed plugins used with your site. Now locate the “Add new” button near the top of this new screen. Now search for Lockr in the search plugins data field. Find the Lockr plugin, install and activate it.

Once you’ve installed and activated the Lockr plugin you’ll notice your WordPress dashboard reloads and there is now a Lockr settings tab located in the left column near the bottom. You’ll be brought to a screen like this below and will need to register your site before using it.

Setup Lockr module in WordPress

Setup and Registration

Once you have the Lockr plugin or module installed and enabled, you will first need to connect the site with a KeyRing in the Lockr service before you are able to store any secrets. This process is simple and quick, no matter what environment you're in. During the setup process, we'll only need minimal information about your site to create the client certificates needed to authenticate.

If you're on a partner the server credentials are already in place, which means we simply need to associate the site with a KeyRing in the system, or create a new KeyRing subscription. To make setup as simple as possible, if you haven't already registered an account on the lockr website that's ok, the registration process will create a new account for you.

Drupal Registration

Whether you're using Drupal 7 or Drupal 8 the registration process is the same. Follow the steps below to register your site with Lockr to begin storing keys.

Ensure the private directory is setup

  1. Whether you've installed the Lockr module on a supporting hosting provider or not, the process is the same. The first step is to click on the button to register the site and another window will popup to take you the rest of the way. Register Lockr module in Drupal

  2. If you do not already have an account or are not currently logged into the Lockr Dashboard, you’ll be prompted to enter your email address. If your email is not associated with an account in Lockr, you'll be taken to an account creation confirmation page. Otherwise you'll be prompted to enter your account password. Login to your Lockr account

  3. Once you’ve logged in, you will be taken to the KeyRing setup form. The first step is to name the client (certificate) you would like to create. This should be descriptive like "local development" or "development server" so you can later track what client certificates are accessing the KeyRing. Next you can either create a new KeyRing ( NOTE: This creates a new subscription charge ): Create a new client or create a client certificate for an existing KeyRing already on your account: Create client for existing KeyRing Once you finish filling out the form and submit, the popup will close and take you back to the dashboard page.

  4. If the entire process was successful, you should now see the dashboard identify what environment your client has access to and the KeyRing you're now connected to. Successful registration of Lockr in Drupal

  5. You're now ready to start saving values in Lockr!

WordPress Registration

Registering your WordPress site can be done by following a few simple steps outlined below. You'll know the site is not yet registered when any of the Lockr admin screens only show prompts to register the site, like this: Registration needed in Lockr plugin in WordPress

  1. Whether you've installed the plugin module on a supporting hosting provider or not, the process is the same. The first step is to click on the button to register the site and another window will popup to take you the rest of the way. Valid certificate for Lockr plugin in WordPress

  2. If you do not already have an account or are not currently logged into the Lockr Dashboard, you’ll be prompted to enter your email address. If your email is not associated with an account in Lockr, you'll be taken to an account creation confirmation page. Otherwise you'll be prompted to enter your account password. Login to your Lockr account

  3. Once you’ve logged in, you will be taken to the KeyRing setup form. The first step is to name the client certificate you would like to create. This should be descriptive like "local development" or "development server" so you can later track what client certificates are accessing the KeyRing. Next you can either create a new KeyRing ( NOTE: This creates a new subscription charge ): Create a new client or create a client certificate for an existing KeyRing already on your account: Create client for existing KeyRing Once you finish filling out the form and submit, the popup will close and take you back to the dashboard page.

  4. If the entire process was successful, you should now see the dashboard identify what environment your client has access to and the KeyRing you're now connected to. Successful registration of Lockr in WordPress

  5. You're now ready to start saving values in Lockr!

Moving to Production

If you are using a custom Lockr certificate, you will need to move to production. In order to do this, you'll need to have 2 things:

  1. A credit card on file with the Lockr website
  2. A valid development certificate

When you move to production, Lockr will take you through a pop-up similar to registration to generate a production certificate. In order to move to production, we highly recommend setting up two-factor authentication via TOTP. If your account is setup with two-factor authentication, any production certificates will require the extra authentication to be issued. If successful, a production certificate will be returned and put in place of the development certificate. Protect this certificate as it is what gives any request to our service the ability to return production values

How To Use SRAS

Generating a SRAS token

There are two different options for generating a token. Note *First you will need to login to your lockr account on the dev environment for lockr accounts. do that here: https://accounts.lockr.io/user/login

Running SRAS in Drush

Before running these commands you must have the lockr module installed on your drupal site. You can install this module using this command: composer require 'drupal/lockr:4.x-dev@dev'

drush lockr:register-token {Token} --client_label={Client Label Here} --keyring_label={Keyring Label Here}

drush lockr:register-token {Token}

Advanced Settings

Lockr takes care of most of the setup for you, however there are a few advanced settings that you'll be able to change that will let you modify where Lockr finds the certificate.

Custom Certificate Location

If you've followed our recommendation to move your custom certificates outside the webroot into a more protected folder, kudos! You're doing it right. With that, Lockr will need to know where to look for the certs. Simply use this input in the advanced settings to point to the directory the certificate file is located. This directory will need to be readable to the webserver but doesn't need any global permissions. This input can be relative to the site root.

Lockr Region Selection

By default Lockr selects the closest region to you to store your secrets in. You are able to override the region to store your secrets in if you'd like.

Troubleshooting

If you are running into issues with Lockr, that's not fun for anyone. We want to make sure you get the support you need. We're always available at our slack channel if you want to chat with us or anyone else in the Lockr community.

In supporting customers, here are some common issues we find people running into and how to fix them. Many will rely on information that can be found on the Lockr configuration page from within the site. There we provide a status table to know the live status of your site and Lockr.

No Valid Certificate

The #1 thing we find people running into is Lockr either not having a valid certificate, or not knowing where to look for one. Without a valid certificate, Lockr plugins cannot do anything and all unsigned requests are immediately rejected by our services.

If you are on a supported hosting provider, and are seeing an invalid certificate on your site then we are having issues with the hosting provider and it needs to be elevated to Lockr and/or your hosting provider asap.

More often, we see this issue when someone is on a custom certificate. It is likely due to the certificate being in a location that Lockr doesn't know about. The advanced settings allow you to specify this location for the certificates. Once you know the location of the directory, enter it here and you should now be seeing green on the status table for a valid certificate.

Key value not found

Key values are not returned from Lockr because of one of 3 issues: The certificate was not valid, the value requested doesn't exist in the environment it's being requested, and (although rare) Lockr is having a server-side issue. You can reference a valid certificate not found above, but if you're seeing a valid certificate and no key values it's likely because Lockr separates development and production environments and the key you're trying to retrieve is not stored in the environment you're in. Without setting a value in each environment, Lockr may not find the value you're looking for.

If you are sure the key has been set in the environment you're in, and you have a valid certificate, please contact us via slack or email.

Values in different Environments

Lockr separates production and development environments. This can lead to issues where a key is being requested in an environment it doesn't exist. If you first setup Lockr in a development environment (which we recommend) the values you set will be in our development vaults. Because of this, when you move to production the values will not be present. You will need to re-enter the production value into the admin interface. Be sure to name the key the same you did in testing, so when you pull the production database back to development environments Lockr will seamlessly transition to using the development values instead of production.

FAQ

What types of secrets does Lockr manage?

Can Lockr be used by a non-CMS application?

Yes! Non-CMS applications can easily integrate with Lockr using our API. The API supports creating authentication certificates and saving/retrieving key values. We currently offer a php library on Packagist. If you have another language you’d like to see a library built in, contact support and we’d be happy to help.

How is Lockr different from other key management systems?

Lockr makes key management simple, secure, and carefree by taking on all the hard work and monitoring, leaving you to focus on your site / application. Lockr sets itself apart by encrypting the keys prior to leaving the site or application. This process, called key wrapping, encrypts the key while it is still in your website / application. Key wrapping prevents keys stored in Lockr from being viewed or compromised outside of your website / application (Lockr cannot see your key values - EVER) In addition to these steps, the wrapped keys are always transferred via secure HTTPS connections and stored in Townsend Security’s FIPS 140-2 compliant key manager, making them secured to the highest of industry standards.

Lockr also introduces the concept of managing keys on a “per environment" basis, which helps eliminate the potential of keys being shared from production to development environments. No longer will you have to worry about sending a test notification from development to production users, or having production data decrypted in development environments.

Is Lockr safe?

Yes! Lockr can be used to secure any API key, application secret, encryption keys and other types of credentials. Once enabled in the CMS, keys entered into Lockr are wrapped (encrypted) and then sent over an encrypted connection to the Lockr system. Many times the credentials used to access Lockr are provided by the site host or application platform to prevent hijacking and tampering. This prevents unauthorized access and also enables the separation of development and production environments. Using certificates, either by the hosting provider or ones issued by Lockr, allows for secure authentication without passwords or tokens. These certifications expire, can be revoked and are automatically renewed making managing access simple and secure. Using key wrapping (see above), keys are rendered useless from being used outside the website or application environment. Everyone, including Lockr, is unable to get the values of your key.

Will developers be able to access the secrets?

Only if you want them to. Lockr has isolated development and production environments and working with your hosting provider, or with custom certificates from Lockr, developers can be restricted to only access keys in the development environment.

If you're encrypting sensitive information in your production environment, that data should not be decrypted anywhere but in production. With Lockr, data encrypted in production with a production key is not retrievable outside that environment. This is because Lockr is aware of what environment a request is coming from and uses entirely different key storage environments for development and production keys. When cloned to development, the keys that development environment has access to cannot decrypt the data.

Who can access the secrets?

The only access to the encrypted keys stored in Lockr is given to a request signed by the certificate used to save that key. Using a proprietary method, Lockr routes and stores keys using a “fingerprint” based on the access certificate which prevents anyone with a valid certificate getting a key belonging to another account.

Since keys are encrypted with AES-256 before they are ever transmitted to Lockr there is no way for Lockr to access key values. We’d have to bend the rules of physics and math in order to do read a key value.

Where are the secrets stored?

Once transmitted to Lockr, encrypted key values are routed to a highly redundant cluster of cloud Hardware Security Modules (HSMs) for storage based on the environment and region desired for that key. Lockr runs isolated US and EU clouds to ensure storage meets regulatory standards and are positioned as close to your site / app for performance. Lockr is backed by Townsend Security Alliance Key Managers, which are FIPS 104-2 validated and NIST compliant, ensuring the highest level of industry standards.

What happens if my site / application is hacked?

If your site is hacked, usually the first thing a hacker does is make a copy of the environment they’re in. This means they grab a copy of your database if it is a SQL exploit or a copy of the server if it’s a server breach. Each of these environments do not alone have the ability to expose a key stored in Lockr. The database stores the secondary key, used in the key wrapping process, but by itself this key is useless. Likewise the server environment holds the connection certificate, but without the ability to unwrap (decrypt) the value given back from Lockr the value is rendered useless. Additionally, certificates can be revoked and re-issued. By revoking a certificate, a hacker will no longer be able to access the encrypted values stored in Lockr.

By isolating the various pieces necessary to get the true key value, it greatly reduces the chances a hacker will be able to access your keys.

What happens if Lockr gets hacked?

In the unfortunate situation where Lockr itself is hacked, we’ve taken the necessary steps to isolate systems to keep your keys safe. By going through the key wrapping within your site or application, by the time Lockr has the key it is not longer in a usable form. This means that even if a hacker gained access to Lockr’s HSMs they would be unable to get access to the true keys stored within. Additionally, by using our proprietary fingerprinting methodology even the name of a key is not decipherable.

Access to the Lockr database is worthless as all values within it are encrypted with keys we don’t have access to, or are obfuscated using data we don’t store.

Can Lockr access my keys?

Since keys are encrypted with AES-256 before they are ever transmitted to Lockr there is no way for Lockr to access key values. We’d have to bend the rules of physics and math in order to do read a key value.

What if I want to leave Lockr?

We hate to see you go! However, if you need to leave Lockr, we can either migrate you to another Townsend Alliance Key Manager or provide you with a way to export your keys and unwrap them in your application. Contact support for help in this process.

php