Loker is a self-hosted AWS secrets manager compatible server. With the main purpose of being used for Integration and End-to-end testing use cases without requiring alternative secret backends.

Data is stored in an encrypted SQLite database using SQLCipher. Server supports using HTTPS and enforces AWS SigV4 signing on requests.

Quick Start (Docker)

HTTP

The command below will start a simple docker container for Loker mounting the database to the ./data folder.

docker run -d \
  --name loker \
  -p 8080:8080 \
  -e SM_ENCRYPTION_KEY="your-encryption-key" \
  -e SM_ACCESS_KEY_ID="your-access-key-id" \
  -e SM_ACCESS_KEY_SECRET="your-access-key-secret" \
  -v ./data:/data \
  jacobtread/loker:latest

HTTPS

The command below will start a simple docker container for Loker with HTTPS enabled. For HTTPS you must provide your own certificate and private key.

The following command will mount the certificates from ./certs ensure that folder contains the certificate (sm.cert.pem) and private key (sm.key.pem) in PEM format.

docker run -d \
  --name loker \
  -p 8443:8443 \
  -e SM_ENCRYPTION_KEY="your-encryption-key" \
  -e SM_ACCESS_KEY_ID="your-access-key-id" \
  -e SM_ACCESS_KEY_SECRET="your-access-key-secret" \
  -e SM_USE_HTTPS="true" \
  -e SM_HTTPS_CERTIFICATE_PATH="/certs/sm.cert.pem" \
  -e SM_HTTPS_PRIVATE_KEY_PATH="/certs/sm.key.pem" \
  -v ./certs:/certs \
  -v ./data:/data \
  jacobtread/loker:latest

Quick Start (Docker Compose)

services:
    loker:
        image: jacobtread/loker:latest
        container_name: loker
        restart: unless-stopped
        environment:
            SM_ENCRYPTION_KEY: "your-encryption-key"
            SM_ACCESS_KEY_ID: "your-access-key-id"
            SM_ACCESS_KEY_SECRET: "your-access-key-secret"
            # Uncomment the lines below if you want to enable HTTPS
            # SM_USE_HTTPS: "true"
            # SM_HTTPS_CERTIFICATE_PATH: "/certs/sm.cert.pem"
            # SM_HTTPS_PRIVATE_KEY_PATH: "/certs/sm.key.pem"
        ports:
            # For HTTP mode
            - "8080:8080"
            # For HTTPS mode (uncomment when using HTTPS)
            # - "8443:8443"
        volumes:
            # Persistent data storage
            - ./data:/data
            # Mount certs only if using HTTPS
            # - ./certs:/certs

AWS SDK

To use with the AWS Secrets Manager SDK configure your SDK config like the following

Rust

The following snippet is an example for using Loker with the aws-sdk-secretsmanager crate:

use aws_config::{BehaviorVersion, Region, SdkConfig};
use aws_sdk_secretsmanager::config::{Credentials, SharedCredentialsProvider};

// Update credentials to match your environment variables
let credentials = Credentials::new(
    "ACCESS_KEY_ID",
    "ACCESS_KEY_SECRET",
    None,
    None,
    "sm-credentials",
);

// Adjust endpoint to match your Loker server
let endpoint_url = "http://localhost:8008";
let sdk_config = SdkConfig::builder()
    .behavior_version(BehaviorVersion::latest())
    .region(Region::from_static("us-east-1"))
    .endpoint_url(endpoint_url)
    .credentials_provider(SharedCredentialsProvider::new(credentials))
    .build()

// Construct the client
let client = aws_sdk_secretsmanager::Client::new(&sdk_config);

// ...Use the client as normal

JavaScript / TypeScript

The following snippet is an example for using Loker with the @aws-sdk/client-secrets-manager npm package:

import { SecretsManagerClient } from "@aws-sdk/client-secrets-manager";

// Update credentials to match your environment variables
const credentials = {
    accessKeyId: "ACCESS_KEY_ID",
    secretAccessKey: "ACCESS_KEY_SECRET",
};

// Adjust endpoint to match your Loker server
const endpoint = "http://localhost:8080";

// Construct the client
const client = new SecretsManagerClient({
    region: "us-east-1",
    endpoint,
    credentials,
});

// ...Use the client as normal

Environment Variables

Name	Required	Description
SM_ENCRYPTION_KEY	Yes	Encryption key to encrypt the database with
SM_DATABASE_PATH	No (Default: secrets.db)	Path to the file where the database should be stored
SM_ACCESS_KEY_ID	Yes	Access key ID to use the server for AWS SigV4
SM_ACCESS_KEY_SECRET	Yes	Access key secret to use the server for AWS SigV4
SM_SERVER_ADDRESS	No (Default: HTTP=0.0.0.0:8080 HTTPS=0.0.0.0:8443)	Socket address to bind the server to
SM_USE_HTTPS	No (Default: false)	Whether to use HTTPS instead of HTTP
SM_HTTPS_CERTIFICATE_PATH	No (Default: sm.cert.pem)	Path to the certificate in PEM format to use for HTTPS
SM_HTTPS_PRIVATE_KEY_PATH	No (Default: sm.key.pem)	Path to the private key in PEM format to use for HTTPS

Implementations:

• BatchGetSecretValue
• CreateSecret
• DeleteSecret
• DescribeSecret
• GetRandomPassword
• GetSecretValue
• ListSecrets
• ListSecretVersionIds
• PutSecretValue
• RestoreSecret
• TagResource
• UntagResource
• UpdateSecret
• UpdateSecretVersionStage

Not Planned:

• CancelRotateSecret
• DeleteResourcePolicy
• GetResourcePolicy
• PutResourcePolicy
• RemoveRegionsFromReplication
• ReplicateSecretToRegions
• RotateSecret
• StopReplicationToReplica
• ValidateResourcePolicy

Windows Build Notes

If you are building on Windows ensure you download the required prerequisites from https://wiki.openssl.org/index.php/Compilation_and_Installation#Windows Loker depends on OpenSSL for the vendored SQLCipher dependency

Disclaimer

This project is not affiliated with or endorsed by Amazon AWS.