redoctober

[!WARNING] This project is no longer actively developed.

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 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 fields for this request* (required)
• Uses is the number of times the delegated credentials can be used for decryption or otherwise and must be >= 1 (required)
• Time is a duration the delegation is active and must parse with Go's time.ParseDuration() (required)
• Slot is a string that can be used to allow multiple delegations. This value is passed to the keycache.Cache, which stores delegated user credentails, when a user delegates their credentials. If a user wanted to delegate multiple times with different restrictions, such as allowing one user delegated credentials for ssh-sign-with and another user for decrypt, then they should submit different values for Slot during each /delegate request. (optional)
• Users is a list of users that can use this delegation. Values must match the Name field used at creation of the user. (optional)
• Labels are strings used to match the delegation to whether a encrypted secret can be decrypted. If labels were used in the encryption then at least one label must match in the delegation from both users. (optional)

*See the first assumption for this API call

Response:

{
    "Status": "ok"
}

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

Assumptions:

• This API call will create a user if no user matching the User field is found. In that case, the same User and Password validations as /create and /create-user are followed.
• Slot allows for multiple delegations, but is not a validation of purpose. If two delegations are identical, but with different Slot values, either could be used assuming:
  • Uses has not reached 0
  • Time has not expired
  • Users contains the user attempting to utilize the delegation
• Labels is for the Order component of RO only and is not checked when attempting to utilize a delegation

Example query:

$ curl --cacert cert/server.crt https://localhost:8080/delegate \
       -d '{"Name":"Bill","Password":"Lizard","Time":"2h34m","Uses":3}'
{"Status":"ok"}
$ curl --cacert cert/server.crt https://localhost:8080/delegate \
       -d '{"Name":"Cat","Password":"Cheshire","Time":"2h34m","Uses":3}'
{"Status":"ok"}
$ curl --cacert cert/server.crt https://localhost:8080/delegate \
       -d '{"Name":"Dodo","Password":"Dodgson","Time":"2h34m","Uses":3}'
{"Status":"ok"}

Purge

Purge deletes all delegated keys in Red October.

Requires Authentication Requires Admin Yes Yes

Request:

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

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

Response:

{
    "Status": "ok"
}

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

Assumptions:

• None

Example input JSON format:

$ curl --cacert cert/server.crt https://localhost:8080/purge \
       -d '{"Name":"Alice",