Red October

Red October is a software-based two-man rule style encryption and decryption server.

Building

Note: GODEBUG=x509ignoreCN=0 must be set during runtime (#204)

This project requires Go 1.16 or later to compile.

Running

Red October is a TLS server. It requires a local file to hold the key vault, an internet address, and a certificate keypair.

First you need to acquire a TLS certificate. The simplest (and least secure) way is to skip the Certificate Authority verification and generate a self-signed TLS certificate. Read this detailed guide or, alternatively, follow these insecure commands:

$ mkdir cert
$ chmod 700 cert
## Generate private key with password "password"
$ openssl genrsa -aes128 -passout pass:password -out cert/server.pem 2048
## Remove password from private key
$ openssl rsa -passin pass:password -in cert/server.pem -out cert/server.pem
## Generate CSR (make sure the common name CN field matches your server
## address. It's set to "localhost" here.)
$ openssl req -new -key cert/server.pem -out cert/server.csr -subj '/C=US/ST=California/L=Everywhere/CN=localhost'
## Sign the CSR and create certificate
$ openssl x509 -req -days 365 -in cert/server.csr -signkey cert/server.pem -out cert/server.crt
## Clean up
$ rm cert/server.csr
$ chmod 600 cert/*

You're ready to run the server:

$ ./bin/redoctober -addr=localhost:8080 \
                   -vaultpath=diskrecord.json \
                   -certs=cert/server.crt \
                   -keys=cert/server.pem

Quick start: example webapp

At this point Red October should be serving an example webapp. Access it using your browser:

• https://localhost:8080/

Using the API

The server exposes several JSON API endpoints. JSON of the prescribed format is POSTed and JSON is returned.

| Path | Summary | | ---- | ------- | | /create | Create the first admin account | | /create-user | Create a user | | /summary | Display summary of the delegated keys and Red October users | | /delegate | Delegate a key to Red October | | /purge | Delete all delegated keys | | /password | Change password for the authenticating user | | /encrypt | Encrypt provided data with specified owners and predicates | | /re-encrypt | Change encryption parameters of already encrypted data (delegation requirements must be met) | | /decrypt | Decrypt provided data assuming necesary delegation requirements have been met | | /ssh-sign-with | Sign data as an SSH oracle without disclosing the SSH private key (delegation requirements must be met) | | /owners | List owners (those who can delegate to allow decryption) of a provided encrypted secret | | /modify | Modify an existing user (delete, set admin flag, revoke admin flag) | | /export | Exports the internal vault contained encrypted user private keys, hashed passwords, public keys and other RO internal data | | /order | Adds an Order request to delegate credentials with specific parameters requested | | /orderout | Returns a list of Order structures for all outstanding orders | | /orderinfo | Returns the Order structure for a specified OrderNum | | /ordercancel | Cancel the Order with the specified OrderNum | | /restore | Restore delegations from a persisted state (if configured). Operates like a /delegate call | | /reset-persisted | Deletes all delegations from the persisted state (if configured) | | /status | Returns the status of the persistent store of delegated keys (if configured) | | /index | Optionally, the server can host a static HTML file |

Create

Create is the necessary first call to a new vault. It creates an admin account.

| Requires Authentication | Requires Admin | | ----------------------- | -------------- | | No | No |

Request:

{
    "Name": "User1",
    "Password": "User1Password"
}

• Name must start with an alphnumeric character and then can contain any alphanumeric character, '-', or '_' after the first character (required)
• Password must be at least one character long (required)

Response:

{
    "Status": "ok"
}

• Status will be "ok" if successful or an error string if not.

Assumptions:

• This API call can only be called on an uninitialized vault and will fail on any call after the first user is created.
• The user created with this call is an Admin account.
• This user will use the passvault.DefaultRecordType, which is RSA.

Example query:

$ curl --cacert cert/server.crt https://localhost:8080/create \
        -d '{"Name":"Alice","Password":"Lewis"}'
{"Status":"ok"}

Create User

Create User creates a new user account.

| Requires Authentication | Requires Admin | | ----------------------- | -------------- | | No | No |

Request:

{
    "Name": "User1", 
    "Password": "User1Password!", 
    "UserType": "ECC", 
    "HipchatName": ""
}

• Name must be unique within the RedOctober vault (required)
• Password must be at least one character long (required)
• UserType can be "RSA" or "ECC" (optional, will default to "RSA")
• HipchatName specifies the HipChat username for Order notifications if configured (optional)

Response:

{
    "Status": "ok",
}

• Status will be "ok" if successful or an error string if not.

Assumptions:

• Anyone who can access the API, can register a user with this API call.

Example query:

$ curl --cacert cert/server.crt https://localhost:8080/create-user \
       -d '{"Name":"Bill","Password":"Lizard","UserType":"ECC"}'
{"Status":"ok"}

Summary

Summary provides a list of the users with keys on the system, and a list of users who have currently delegated their key to the server.

| Requires Authentication | Requires Admin | | ----------------------- | -------------- | | Yes | No |

Request:

{
    "Name": "User1",
    "Password": "User1Password!"
}

• Name and Password are used to authenticate the request (required)

Response:

{
    "Status": "ok", 
    "State": "",
    "Live": {
        "User1": {
            "Uses": 1,
            "Labels": ["", ""],
            "Users": ["", ""],
            "Expiry": "",
            "AltNames": {
                "key1": "value1",
                "key2": "value2"
            },
            "Admin": true,
            "Type": "RSA"
        },
        "User1-slot1": {
            "Uses": 1,
            "Labels": ["", ""],
            "Users": ["", ""],
            "Expiry": "",
            "AltNames": {
                "key1": "value1",
                "key2": "value2"
            },
            "Admin": true,
            "Type": "ECC"
        },
    },
    "All": {
        "User1": {
            "Admin": true,
            "Type": "RSA"
        }
    }
}

• Status will be "ok" if successful or an error string if not.
• State could be active, inactive, or disabled and is the status of the persisted keycache (delegated credentials)
• Live is a map of active delegations
  • The key is a combination of the username and a slot string (if provided on delegation)
  • The value is an object with details about the user and the specific delegation
• All is a map of users with keys in Red October
  • The key of the map is the username
  • The value is a object that says if the user is an Admin and if a "RSA or "ECC" key is used (Type)

Assumptions:

• None

Example query:

$ curl --cacert cert/server.crt https://localhost:8080/summary  \
        -d '{"Name":"Alice","Password":"Lewis"}'
{"Status":"ok",
 "Live":{
  "Bill":{"Admin":false,
          "Type":"RSA",
          "Expiry":"2013-11-26T08:42:29.65501032-08:00",
          "Uses":3},
  "Cat":{"Admin":false,
         "Type":"RSA",
         "Expiry":"2013-11-26T08:42:42.016311595-08:00",
         "Uses":3},
  "Dodo":{"Admin":false,
          "Type":"RSA",
          "Expiry":"2013-11-26T08:43:06.651429104-08:00",
          "Uses":3}
 },
 "All":{
  "Alice":{"Admin":true, "Type":"RSA"},
  "Bill":{"Admin":false, "Type":"RSA"},
  "Cat":{"Admin":false, "Type":"RSA"},
  "Dodo":{"Admin":false, "Type":"RSA"}
 }
}

Delegate

Delegate allows a user to delegate their decryption password to the server for a fixed period of time and for a fixed number of decryptions. If the user's account is not created, it creates it. Any new delegation overrides the previous delegation.

| Requires Authentication | Requires Admin | | ----------------------- | -------------- | | Yes* | No |

*See the first assumption for this API call

Request:

{
    "Name": "User1",
    "Password": "User1Password!",
    "Uses": 1,
    "Time": "1h10m5s",
    "Slot": "",
    "Users": ["User2", "User3"],
    "Labels": ["", ""]
}

• Name and Password are the authentication fi