Awesome
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:
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 forOrder
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
andPassword
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 beactive
,inactive
, ordisabled
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
andPassword
are the authentication fields for this request* (required)Uses
is the number of times the delegated credentials can be used fordecryption
or otherwise and must be >= 1 (required)Time
is a duration the delegation is active and must parse with Go'stime.ParseDuration()
(required)Slot
is a string that can be used to allow multiple delegations. This value is passed to thekeycache.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 forssh-sign-with
and another user fordecrypt
, then they should submit different values forSlot
during each/delegate
request. (optional)Users
is a list of users that can use this delegation. Values must match theName
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 sameUser
andPassword
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 differentSlot
values, either could be used assuming:Uses
has not reached0
Time
has not expiredUsers
contains the user attempting to utilize the delegation
Labels
is for theOrder
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
andPassword
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","Password":"Lewis"}'
{"Status":"ok"}
Password
Password allows a user to change their password. This password change does not require the previously encrypted files to be re-encrypted.
Requires Authentication | Requires Admin |
---|---|
Yes | No |
Request:
{
"Name": "User1",
"Password": "User1Password!",
"NewPassword": "User1Password!NEW",
"HipchatName": ""
}
Name
andPassword
are used to authenticate the request (required)NewPassword
will replace the current password and must be at least 1 character long (required)HipchatName
is used for the internal HipChat ordering system (optional)
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/password \
-d '{"Name":"Bill","Password":"Lizard", "NewPassword": "theLizard"}'
{"Status":"ok"}
Encrypt
Encrypt allows a user to encrypt a piece of data. A list of valid users is provided and a minimum number of delegated users required to decrypt. The returned data can be decrypted as long as "Minimum" number users from the set of "Owners" have delegated their keys to the server.
Requires Authentication | Requires Admin |
---|---|
Yes | No |
Request:
{
"Name": "User1",
"Password": "User1Password",
"Minimum": 2,
"Owners": ["User4", "User3", "Users2"],
"LeftOwners": ["", ""],
"RightOwners": ["", ""],
"Predicate": "",
"Data": "V2h5IGlzIGEgcmF2ZW4gbGlrZSBhIHdyaXRpbmcgZGVzaz8K",
"Labels": ["", ""],
"Usages": ["", ""]
}
Name
andPassword
authenticate the request (required)Minimum
is the number of delegations required to decrypt. Should only be 1 or 2 unless usingLeftOwners
andRightOwners
or aPredicate
string. (optional)Owners
is a list of users that if delegated allows decryption of the secret. Need at leastMinimum
users. (required<sup>1</sup>)LeftOwners
andRightOwners
are list of users that require delegation of at least one left and one right (required<sup>1</sup>)Predicate
is a string that maps to an arbitrary monotone access structure. Please see MSP Package (required<sup>1</sup>)Data
is the base64 encoded data to be encrypted (required)Labels
are strings that will mark if a decryption can occure based on matching labels in the delegation. IfLabels
is not empty, then at least one value ofLabels
in the/delegate
request must match at least one value in this request'sLabels
. (optional)Usages
are strings that define how the secret can be used. Such as if it can be returned by/decrypt
["decrypt
"] or used to with/ssh-sign-with
["ssh-sign-with"
] (optional)
<sup>1</sup> Either Owners
, LeftOwners
and RightOwners
, or Predicate
is required. If one of the three is used, the other two should not be provided in the request.
Response:
{
"Status": "ok",
"Response": "nWY13Rx8d7Tov0AFGu...Hok3DlNnDs8FcrU5/PrxuExq"
}
Status
will be"ok"
if successful or an error string if not.Response
is the base64 encoded JSON object
If you base64 decode Response
, you will get:
{
"Version": -1,
"Data": "c5UHBZ5KYk9K4WIf94Os/n6gtm...hu2aM1+yQO0iwhLC",
"Signature": "Hsd88NiDaA9Ech2uHzDjLA=="
}
Version
is always -1 as it is used when HMAC-ing the encrypted dataData
is a base64 encoded JSON objectSignature
is the HMAC signature ofData
If you base64 decode Data
, you will get:
{
"Version": 1,
"VaultId": 12905318,
"Labels": ["", ""],
"Usages": ["", ""],
"Predicate": "",
"KeySet": [
{
"Name": ["User1", "User2"],
"Key": "OnfKLlXjk0swCtdc3/GPcQ=="
},
{
"Name": ["User2", "User3"],
"Key": "BRJ1ZtL0IS1g6fuPAgKkGA=="
},
...
],
"KeySetRSA": [
"User1": {
"Key": "ZTXz2KehhQ+02umuhSK9pmv3q155FW6BtqDUctz1k0NOI9e9WrL+vg=="
},
"User2": {
"Key": "R87vNqb7GhxZ8Bl+hd2osnQWVmgs68KmQ8LqoXg/3M3dvfyPBxyujw=="
},
"User3": {
"Key": "uocoMcwt00sbMM2aqUhKnDdwcyWfj8AxZjUGib8pDSBYl2XfU4gM/A=="
},
...
],
"ShareSet": [
"User1": ["5tJHlh2P+x9pNwOrjQsqxJMuTN9PdRqiFJ...OFYw/0="],
"User2": ["Hg06yJnUUAjerytV6/iHr/7...bxUB/M8U7FpYDzw="],
...
],
"IV": "xyjda++X7+8wQ0VH6Dnt/w==",
"Data": "k9kezvCRTe6x/Fl8pVBxb...Wup5ESrQw553IxIRbY=",
"Signature": "uUXOkuCAbGUSO4u81/ampQ=="
}
Version
is the version number of theEncryptedData
structureVaultId
will be a random 32 bit, non-negative integer identifying the vaultLabels
are the same as the requestLabels
Usages
are the same as the requestUsages
Predicate
are the same as the requestPredicate
KeySet
is an array of objects with aName
andKey
attribute. Each object in the array is a encrypted value using intermediary keys from two users. All validate two user key delegations are stored in this array to allow decryption.Name
is an array of two users that were used to encrypt theData
encryption keyKey
is a base64 encoded byte array that represents a doubly encrypted key, that was used to encryptData
KeySetRSA
is an map where the key is a user and the value is an object with one attributeKey
.Key
is the base64 encoded byte array that represents the intermediary key encrypted with a users RSA or ECC public key. Once decrypted, the intermediary key for two users can be used to decrypt theData
encryption key stored in theKeySet
map.
ShareSet
is a map of base64 encoded byte strings representing the distributed shares generated from the requestedPredicate
- The map key is the user and the value is that users portion of the share
IV
is the AES initial vector usedSignature
is the internal HMAC signature of this whole structure
Assumptions:
KeySet
andKeySetRSA
will always be populatedShareSet
will only be populated when usingPredicate
Example query:
$ echo "Why is a raven like a writing desk?" | openssl base64
V2h5IGlzIGEgcmF2ZW4gbGlrZSBhIHdyaXRpbmcgZGVzaz8K
$ curl --cacert cert/server.crt https://localhost:8080/encrypt \
-d '{"Name":"Alice","Password":"Lewis","Minimum":2, "Owners":["Alice","Bill","Cat","Dodo"],"Data":"V2h5IGlzIGEgcmF2ZW4gbGlrZSBhIHdyaXRpbmcgZGVzaz8K"}'
{"Status":"ok","Response":"eyJWZXJzaW9uIj...NSSllzPSJ9"}
Example query with a predicate:
$ curl --cacert cert/server.crt https://localhost:8080/encrypt \
-d '{"Name":"Alice","Password":"Lewis","Predicate":"Alice & (Bob | Carl)",
Data":"V2h5IGlzIGEgcmF2ZW4gbGlrZSBhIHdyaXRpbmcgZGVzaz8K"}'
{"Status":"ok","Response":"eyJWZXJzaW9uIj...NSSllzPSJ9"}
The data expansion is not tied to the size of the input.
Re-Encrypt
Re-encrypt allows for modification of encrypted data, without having to call Decrypt and then Encrypt, thus exposing the
secret to the caller. Enough delegation to Decrypt are required for this call to run. A call is very similar to except
instead of base64 encoded data in the Data
field, provide the Response
value from a previous /encrypt
call.
Requires Authentication | Requires Admin |
---|---|
Yes | No |
Request:
{
"Name": "User1",
"Password": "User1Password",
"Minimum": 2,
"Owners": ["User4", "User3", "Users2", "User5"],
"LeftOwners": ["", ""],
"RightOwners": ["", ""],
"Predicate": "",
"Data": "nWY13Rx8d7Tov.../PrxuExq",
"Labels": ["", ""],
"Usages": ["", ""],
}
Name
andPassword
authenticate the request (required)Data
is the base64 encoded response from/encrypt
(required)- All other fields work similar to a
/encrypt
call and will replace the original calls values
Response:
{
"Status": "ok",
"Response": "QIsDoh/jp3sky...JfOTePLRAMp7k="
}
Status
will be"ok"
if successful or an error string if not.Response
is the base64 encoded JSON object- The internal structure of
Response
is identical to the response of an/encrypt
call
Assumptions:
- Necessary delegations to decrypt the provided encrypted value should already be delegated.
Example query:
$ echo "Why is a raven like a writing desk?" | openssl base64
V2h5IGlzIGEgcmF2ZW4gbGlrZSBhIHdyaXRpbmcgZGVzaz8K
$ curl --cacert cert/server.crt https://localhost:8080/re-encrypt \
-d '{"Name":"Alice","Password":"Lewis","Minimum":2, "Owners":["Alice","Bill","Cat","Dodo","Greg"],"Data":"eyJWZXJzaW9uIj...NSSllzPSJ9"}'
{"Status":"ok","Response":"J6rv0zlJ7l8stG6Oz...lQu8gXKSoIR6U="}
Example query with a predicate:
$ curl --cacert cert/server.crt https://localhost:8080/re-encrypt \
-d '{"Name":"Alice","Password":"Lewis","Predicate":"Alice & (Bob | Carl | Dodo)",
Data":"eyJWZXJzaW9uIj...NSSllzPSJ9"}'
{"Status":"ok","Response":"J6rv0zlJ7l8stG6Oz...lQu8gXKSoIR6U="}
The data expansion is not tied to the size of the input.
Decrypt
Decrypt allows a user to decrypt a piece of data. As long as "Minimum" number users from the set of "Owners" have delegated their keys to the server, a base64 encoded object with the clear data and the set of "Owners" whose private keys were used is returned.
Requires Authentication | Requires Admin |
---|---|
Yes | No |
Request:
{
"Name": "User1",
"Password": "User1Password",
"Data": "nWY13Rx8.../PrxuExq",
}
Name
andPassword
are used to authenticate the request (required)Data
is the encrypted secret returned be a call to/encrypt
(required)
Response:
{
"Data": "V2h5IGlzIGEgcmF2ZW4gbGlrZSBhIHdyaXRpbmcgZGVzaz8K",
"Secure": true,
"Delegates": ["User2", "User3"]
}
Data
is the response from an encrypt call to be decryptedSecure
this is a flag that states if the payload was properly HMAC protectedDelegates
notes which user's delegated keys were used to decrypt this blob
Assumptions:
- None
Example query:
$ curl --cacert cert/server.crt https://localhost:8080/decrypt \
-d '{"Name":"Alice","Password":"Lewis","Data":"eyJWZXJzaW9uIj...NSSllzPSJ9"}'
{"Status":"ok","Response":"eyJEYXRhI...FuMiJdfQ=="}
If there aren't enough keys delegated you'll see:
{"Status":"need more delegated keys"}
SSH Sign With
SSHSignWith signs a message with an SSH key previously encrypted with Red October and with a "Usages" containing ssh-sign-with
Requires Authentication | Requires Admin |
---|---|
Yes | No |
Request:
{
"Name": "User1",
"Password": "User1Password!",
"Data": "W2Y4QfAd5pf+sqFkvEzEm...p8/Zbo21YWzCNuStzyXfUcBk=",
"TBSData": "fjELOIwcZsloJY...PPIutXm7fBLJHOJwQ8ht+8Mo="
}
Name
andPassword
are used to authenticate the request (required)Data
is the encrypted SSH private key (required)TBSData
is the SSH message to be signed by the SSH private key (required)
Response:
{
"Status": "ok",
"Response": "rePs8L+l7xtRY50uuuFZ4As4UQZWgzfLd...q808VFaHZNJ9AIfK0vZ9c="
}
Status
will be"ok"
if successful or an error string if not.
If you base64 decode the Response, you will get:
{
"SignatureFormat": "ssh-rsa-cert-v01@openssh.com",
"Signature": "M02dHSCbE/35H8RrxZmHAA==",
"Secure": true, # boolean
"Delegates": ["User1", "User2"]
}
SignatureFormat
is the SSH signature typeSignature
is a base64 encoded byte array, which is the signature of the SSH signing operationSecure
whether the HMAC validated or notDelegates
are the user keys used to temporary decrypt the SSH key for signing
Assumptions:
- If a
Usages
value ofssh-sign-with
was not provided, this function will not work - If a
Usages
value ofdecrypt
is not provided withssh-sign-with
, then the SSH key cannot be decrypted via a/decrypt
call- Note that while not providing
decrypt
avoids/decrypt
returning the unencrypted SSH private key,/re-encrypt
could be used to change that with the necessary delegation.
- Note that while not providing
Example query:
$ curl --cacert cert/server.crt https://localhost:8080/ssh-sign-with \
-d '{"Name":"Alice","Password":"Lewis","Data":"eyJWZXJzaW9uIj...NSSllzPSJ9","TBSData":"eyJEYXRhI...FuMiJdfQ=="}'
{"Status":"ok","Response":"rePs8L+l7xtRY50uuuFZ4As4UQZWg...FaHZNJ9AIfK0vZ9c="}
Owners
Owners allows users to determine which delegations are needed to decrypt a piece of data.
Requires Authentication | Requires Admin |
---|---|
No | No |
Request:
{
"Data": "V2h5IGlzIGEgcmF2ZW4gbGlrZSB...hIHdyaXRpbmcgZGVzaz8K=="
}
Data
is the response from an encrypt call to be decrypted (required)
Response:
{
"Status": "ok",
"Owners": ["User1", "User2", "User3"],
"Labels": ["", ""],
"Predicate": ""
}
Status
will be"ok"
if successful or an error string if not.Owners
will be all the users that were noted inOwners
,LeftOwners
,RightOwners
, or within thePredicate
Labels
will match any that were provided in the/encrypt
call or not be present if emptyPredicate
will be the value provied to/encrypt
or not present if not used in the encryption
Assumptions:
- Anyone with access to an encrypted secret can look this data up in the JSON structure anyway, so it is not an authenticated request
Example query:
$ curl --cacert cert/server.crt https://localhost:8080/owners \
-d '{"Data":"eyJWZXJzaW9uIj...NSSllzPSJ9"}'
{"Status":"ok","Owners":["Alice","Bill","Cat","Dodo"]}
Modify
Modify allows an admin user to change information about a given user. There are 3 commands:
revoke
: revokes the admin status of a useradmin
: grants admin status to a userdelete
: removes the account of a user
Requires Authentication | Requires Admin |
---|---|
Yes | Yes |
Request:
{
"Name": "User1",
"Password": "User1Password!",
"ToModify": "User2",
"Command": "admin"
}
Name
andPassword
are used to authenticate the request (required)ToModify
username to apply theCommand
against (required)Command
can berevoke
,admin
,delete
(required)
Response:
{
"Status": "ok"
}
Status
will be"ok"
if successful or an error string if not.
Assumptions:
- If a user is deleted, their key can never be delegated again because the key is deleted. If you recreate the user, delegation will still fail as the keys will be different.
Example input JSON format:
$ curl --cacert cert/server.crt https://localhost:8080/modify \
-d '{"Name":"Alice","Password":"Lewis","ToModify":"Bill","Command":"admin"}'
{"Status":"ok"}
Export
Export Red October's internal password vault, which contains users' hashed passwords, salts, encrypted private keys and their public keys.
Requires Authentication | Requires Admin |
---|---|
Yes | Yes |
Request:
{
"Name": "User1",
"Password": "User1Password!"
}
Name
andPassword
are used to authenticate the request (required)
Response:
{
"Status": "ok",
"Response": "ewogICAgIlZlcnNpb24iOiAxLCAjIG51bWJlcgogI...ICAgIH0KfQo="
}
Status
will be"ok"
if successful or an error string if not.Response
is a base64 encoded JSON object
If you were to base64 decode Response
, you would get:
{
"Version": 1,
"VaultId": 12905318,
"HmacKey": "JaEu/PQTkpFjp2rML8QUbQ==",
"Passwords": {
"User1": {
"Type": "",
"PasswordSalt": "rFQLnQj+5+I6/YPOteDSNw==",
"HashedPassword": "1WCgv8d9uXC9CcPQBQv9qw==",
"KeySalt": "gVDCnhwOMP3obXgv0avBlQ==",
"RSAKey": {
"RSAExp": "jfqESm+...+nMgQM3x34wQmGswfF62MhDk2sTw==",
"RSAExpIV": "gA0/0sS...iKNXVxXGCKXFyBlyGo4g==",
"RSAPrimeP": "xZnZ32YvEhhOV+...boElV9EA9OJvxsyODjQ==",
"RSAPrimePIV": "LneAiwSzMGbym7e7...nL12tcOy/LN4l8uAV8Khw==",
"RSAPrimeQ": "s/cnhyihrUS...sfnyLuxRIb1eL3aYB18dzjn0D0g==",
"RSAPrimeQIV": "S+8+9Q51Ig6/8in31J9y...4GD2BSig==",
"RSAPublic": {"N":707958947...4076221507,"E":65537}
},
"ECKey": {
"ECPriv":"vzrbL2pj8wxldTb6vYws7cAjIzGdh39TxepIb71GcB0=",
"ECPrivIV": "LPXav82KMgI3pdg30VPvI2cBsk4BQLaylg45NCYR0Bc=",
"ECPublic":{
"Curve":{
"P":11579208921035...308867097853951,
"N":11579208925624...259061068512369,
"B":41058363725114...725554835251291,
"Gx":4843956129391...807170824035286,
"Gy":3613425095677...253568414405109,
"BitSize":256,
"Name":"P-256"
},
"X":1288875298858438030...5394564151993378,
"Y":3728055919617037354...6025371017809918
},
"AltNames": {
"": "",
...
},
"Admin": true
},
"User2": {
...
},
...
}
}
Assumptions:
- Only RSAKey or ECKey would be populated in an actual response
- While the user passwords are hashed and and the various internal values of the ECKey and RSAKey are encrypted with the user's cleartext password, these values are still sensitive and should be handled as such.
Example query:
$ curl --cacert cert/server.crt https://localhost:8080/export \
-d '{"Name":"Alice","Password":"Lewis"}'
{"Status":"ok","Response":"ewogICAgIlZlcn...ICAgIH0KfQo="}
Order
Order creates a new order and lets other users know delegations are needed.
Requires Authentication | Requires Admin |
---|---|
Yes | No |
Request:
{
"Name": "User1",
"Password": "User1Password!",
"Duration": "1h10m5s",
"Uses": 2,
"Users": ["User2", "User3"],
"EncryptedData": "nWY13Rx8d7Tov0AFGuf3IINzdHIFD.../PrxuExq",
"Labels": ["", ""]
}
Name
andPassword
are used to authenticate the request (required)Duration
must be parsable by Go'stime.ParseDuration()
and is the amount of time thisOrder
is valid for (required)Uses
is the number ofUses
required of each user delegation (required)Users
lists the specific user delegations being requested (required)EncryptedData
is the secret that the user delegations will be used against (required)Labels
are specific label requirements for the delegation requests, likely required for/decrypt
of this specific secret (optional)
Response:
{
"Status": "ok",
"Response": "ewogICJDcmVhdG9yIjogIlVz...gICAgIiIKICBdCn0K"
}
Status
will be"ok"
if successful or an error string if not.Response
will be a base64 encoded JSON object
If you base64 decode Response
, you will get:
{
"Creator": "User1",
"Users": ["User2", "User3"],
"Num": "2ab99e07ff0405961f5e0d10",
"TimeRequested": "2009-11-10T23:00:00Z",
"DurationRequested": 4205000000000,
"Delegated": 1,
"OwnersDelegated": ["User3"],
"Owners": ["User4", "User3", "Users2"],
"Labels": ["", ""]
}
Creator
is the user that created theOrder
Users
are the list of users in theOrder
requestNum
is a hex encoded random 12 byte value, which is hteOrderId
TimeRequested
is the time theOrder
was createdDurationRequested
is the parsed value ofDuration
in 64 bit number formDelegated
is the number of user key delegations that already exist from those requested in the original requestOwnersDelegated
is the users that were found already delegated (this array length will be the same asDelegated
)Owners
are the users listed asOwners
in theEncryptedData
provided in the original requestLabels
are the labels included in the original request
Assumptions:
- Orders work with the Hipchat components of Red October, so those should be configured and user details for Hipchat registered
Example input JSON format:
$ curl --cacert server/server.crt https://localhost:8080/order \
-d '{"Name":"Alice","Password":"Lewis","Labels": ["Blue","Red"],\
"Duration":"1h","Uses":5,"EncryptedData":"ABCDE=="}'
{"Status": "ok","Response": "ewogICJDcmVhdG9yIjogIlVzZXIxIiwKICAiVXNlcnMiOiBbCiAgICAiVXNlcjIiLAogICAgIlVzZXIzIgogIF0sCiAgIk51bSI6ICIyYWI5OWUwN2ZmMDQwNTk2MWY1ZTBkMTAiLAogICJUaW1lUmVxdWVzdGVkIjogIjIwMDktMTEtMTBUMjM6MDA6MDBaIiwKICAiRHVyYXRpb25SZXF1ZXN0ZWQiOiA0MjA1MDAwMDAwMDAwLAogICJEZWxlZ2F0ZWQiOiAxLAogICJPd25lcnNEZWxlZ2F0ZWQiOiBbCiAgICAiVXNlcjMiCiAgXSwKICAiT3duZXJzIjogWwogICAgIlVzZXI0IiwKICAgICJVc2VyMyIsCiAgICAiVXNlcnMyIgogIF0sCiAgIkxhYmVscyI6IFsKICAgICIiLAogICAgIiIKICBdCn0K"}
Orders Outstanding
Orders Outstanding will return a list of current order numbers
Requires Authentication | Requires Admin |
---|---|
Yes | No |
Request:
{
"Name": "User1",
"Password": "User1Password!"
}
Name
andPassword
are used to authenticate the request (required)
Response:
{
"Status": "ok",
"Response": "ewogICIyYWI5OWUwN2Z...AgIF0KICB9Cn0K"
}
Status
will be"ok"
if successful or an error string if not.Response
will be a base64 encoded JSON object
If you base64 decode Response
, you will get:
{
"2ab99e07ff0405961f5e0d10": {
"Creator": "User1",
"Users": ["User2", "User3"],
"Num": "2ab99e07ff0405961f5e0d10",
"TimeRequested": "2009-11-10T23:00:00Z",
"DurationRequested": 4205000000000,
"Delegated": 1,
"OwnersDelegated": ["User3"],
"Owners": ["User4", "User3", "Users2"],
"Labels": ["", ""]
},
...
}
- The object is a map where the
key
is eachOrder
'sNum
(a.k.a.OrderNum
) and thevalue
is the serializedOrder
objectCreator
is the user that created theOrder
Users
are the list of users in theOrder
requestNum
is a hex encoded random 12 byte value, which is hteOrderId
TimeRequested
is the time theOrder
was createdDurationRequested
is the parsed value ofDuration
in 64 bit number formDelegated
is the number of user key delegations that already exist from those requested in the original requestOwnersDelegated
is the users that were found already delegated (this array length will be the same asDelegated
)Owners
are the users listed asOwners
in theEncryptedData
provided in the original requestLabels
are the labels included in the original request
Assumptions:
- None
Example input JSON format:
$ curl --cacert server/server.crt https://localhost:8080/orderout
-d '{"Name":"Alice","Password":"Lewis"}'
{"Status": "ok","Response": "ewogICI3N2RhMWNmZDg5NjJmYjk2ODVjMTVjODQiOiB7CiAgICAiTmFtZSI6ICJBbGljZSIsCiAgICAiVXNlcnMiOiBbCiAgICAgICJCb2IiLAogICAgICAiRXZlIgogICAgXSwKICAgICJOdW0iOiAiNzdkYTFjZmQ4OTYyZmI5Njg1YzE1Yzg0IiwKICAgICJUaW1lUmVxdWVzdGVkIjogIjIwMTYtMDEtMjVUMTU6NTg6NDEuOTYxOTA2Njc5LTA4OjAwIiwKICAgICJEdXJhdGlvblJlcXVlc3RlZCI6IDM2MDAwMDAwMDAwMDAsCiAgICAiRGVsZWdhdGVkIjogMCwKICAgICJPd25lcnNEZWxlZ2F0ZWQiOiBbXSwKICAgICJPd25lcnMiOiBbCiAgICAgICJCb2IiLAogICAgICAiRXZlIgogICAgXSwKICAgICJMYWJlbHMiOiBbCiAgICAgICJCbHVlIiwKICAgICAgIlJlZCIKICAgIF0KICB9Cn0K"}
Order Information
Returns the order information for a specific Order number.
Requires Authentication | Requires Admin |
---|---|
Yes | No |
Request:
{
"Name": "User1",
"Password": "User1Password!",
"OrderNum": "2ab99e07ff0405961f5e0d10"
}
Name
andPassword
are used to authenticate the request (required)OrderNum
is the same value returned asNum
under andOrder
object (required)
Response:
{
"Status": "ok",
"Response": "ewogICJDcmVhdG9yIjogIlVzZXIxIiwKICAiV...AogICAgIiIKICBdCn0K"
}
Status
will be"ok"
if successful or an error string if not.Response
will be a base64 encoded JSON object
If you base64 decode Response
, you will get:
{
"Creator": "User1",
"Users": ["User2", "User3"],
"Num": "2ab99e07ff0405961f5e0d10",
"TimeRequested": "2009-11-10T23:00:00Z",
"DurationRequested": 4205000000000,
"Delegated": 1,
"OwnersDelegated": ["User3"],
"Owners": ["User4", "User3", "Users2"],
"Labels": ["", ""]
}
Creator
is the user that created theOrder
Users
are the list of users in theOrder
requestNum
is a hex encoded random 12 byte value, which is hteOrderId
TimeRequested
is the time theOrder
was createdDurationRequested
is the parsed value ofDuration
in 64 bit number formDelegated
is the number of user key delegations that already exist from those requested in the original requestOwnersDelegated
is the users that were found already delegated (this array length will be the same asDelegated
)Owners
are the users listed asOwners
in theEncryptedData
provided in the original requestLabels
are the labels included in the original request
Assumptions:
- None
Example input JSON format:
$ curl --cacert server/server.crt https://localhost:8080/orderinfo
-d '{"Name":"Alice","Password":"Lewis", \
"OrderNum":"77da1cfd8962fb9685c15c84"}'
{"Status": "ok","Response": "ewogICJDcmVhdG9yIjogIlVzZXIxIiwKICAiVXNlcnMiOiBbCiAgICAiVXNlcjIiLAogICAgIlVzZXIzIgogIF0sCiAgIk51bSI6ICIyYWI5OWUwN2ZmMDQwNTk2MWY1ZTBkMTAiLAogICJUaW1lUmVxdWVzdGVkIjogIjIwMDktMTEtMTBUMjM6MDA6MDBaIiwKICAiRHVyYXRpb25SZXF1ZXN0ZWQiOiA0MjA1MDAwMDAwMDAwLAogICJEZWxlZ2F0ZWQiOiAxLAogICJPd25lcnNEZWxlZ2F0ZWQiOiBbCiAgICAiVXNlcjMiCiAgXSwKICAiT3duZXJzIjogWwogICAgIlVzZXI0IiwKICAgICJVc2VyMyIsCiAgICAiVXNlcnMyIgogIF0sCiAgIkxhYmVscyI6IFsKICAgICIiLAogICAgIiIKICBdCn0K"}
Order Cancel
Removes a given order from Red October's Orderer.
Requires Authentication | Requires Admin |
---|---|
Yes | No |
Request:
{
"Name": "User1",
"Password": "User1Password!",
"OrderNum": "2ab99e07ff0405961f5e0d10"
}
Name
andPassword
are used to authenticate the request (required)OrderNum
is the same value returned asNum
under andOrder
object (required)
Response:
{
"Status": "ok",
"Response": "U3VjY2Vzc2Z1bGx5IHJlbW92ZWQgb3JkZXIK"
}
Status
will be"ok"
if successful or an error string if not.Response
will be the base64 encoded string"Successfully removed order"
if successful
Assumptions:
- None
Example input JSON format:
$ curl --cacert server/server.crt https://localhost:8080/orderinfo
-d '{"Name":"Alice","Password":"Lewis", \
"OrderNum":"77da1cfd8962fb9685c15c84"}'
{"Status":"ok","Response": "U3VjY2Vzc2Z1bGx5IHJlbW92ZWQgb3JkZXIK"}
Restore
Restore is functionally almost identical to Delegate, but for restoring the persisted delegation cache. Once enough calls to restore are completed to meet the delegation requirements of the persistence configuration, the current delegation cache will be overwritten with the persisted one.
Requires Authentication | Requires Admin |
---|---|
Yes | No |
Request:
{
"Name": "User1",
"Password": "User1Password",
"Time": "",
}
Name
andPassword
are the authentication fields for this request* (required)Time
is a duration the delegation is active and must parse with Go'stime.ParseDuration()
(required)
Response:
{
"Status": "ok",
"Response": "e1N0YXR1czogYWN0aXZlfQo="
}
Status
will be"ok"
if successful or an error string if not.Response
will be a base64 encoded JSON object if not empty
If you base64 decode Response
, you will get:
{
"Status": "active"
}
Status
could beactive
,inactive
, ordisabled
Assumptions:
- This function only does something if the persist module has been configured.
Example query:
On succesful restore
$ curl --cacert cert/server.crt https://localhost:8080/restore \
-d '{"Name":"Alice","Password":"Lewis","Time":"1h10m"}'
{"Status":"ok","Response":"e1N0YXR1czogYWN0aXZlfQo="}
Need more calls to restore to delegate more credentials
$ curl --cacert cert/server.crt https://localhost:8080/restore \
-d '{"Name":"Alice","Password":"Lewis","Time":"1h10m"}'
{"Status":"need more delegated keys","Response":""}
Reset-Persisted
Reset-Persisted will clear the persisted delegation data if configured.
Requires Authentication | Requires Admin |
---|---|
Yes | Yes |
Request:
{
"Name": "User1",
"Password": "User1Password!"
}
Name
andPassword
are used to authenticate the request (required)
Response:
{
"Status": "ok",
"Response": "e1N0YXR1czogYWN0aXZlfQo="
}
Status
will be"ok"
if successful or an error string if not.Response
will be a base64 encoded JSON object if not empty
If you base64 decode Response
, you will get:
{
"Status": "active"
}
Status
could beactive
,inactive
, ordisabled
Assumptions:
- None
Example query:
$ curl --cacert cert/server.crt https://localhost:8080/reset-persisted \
-d '{"Name":"Alice","Password":"Lewis"}'
{"Status":"ok","Response":"e1N0YXR1czogYWN0aXZlfQo="}
Status
Status returns the current delegation persistence state.
Requires Authentication | Requires Admin |
---|---|
Yes | No |
Request:
{
"Name": "User1",
"Password": "User1Password!"
}
Name
andPassword
are used to authenticate the request (required)
Response:
{
"Status": "ok",
"Response": "e1N0YXR1czogYWN0aXZlfQo="
}
Status
will be"ok"
if successful or an error string if not.Response
will be a base64 encoded JSON object if not empty
If you base64 decode Response
, you will get:
{
"Status": "active"
}
Status
could beactive
,inactive
, ordisabled
Assumptions:
- None
Example query:
$ curl --cacert cert/server.crt https://localhost:8080/status \
-d '{"Name":"Alice","Password":"Lewis"}'
{"Status":"ok","Response":"e1N0YXR1czogYWN0aXZlfQo="}
Web interface
You can build a web interface to manage the Red October service using
the -static
flag and providing a path to the HTML file you want to
serve.
The index.html file in this repo provides a basic example for using
all of the service's features, including encrypting and decrypting
data. Data sent to the server needs to be base64 encoded. The
example uses JavaScript's btoa
and atob
functions for string
conversion. For dealing with files directly, using the
HTML5 File API
would be a good option.
SSH Signing Oracle
Red October can encrypt an SSH private key with a restriction that the key can be used to sign messages, but that it should not be returned as the result of a decrypt call. The ro client can use this feature to mimic an ssh-agent server which authenticates a user to a remote SSH server without ever handling the unencrypted private key directly.
Generate an ssh key without passphrase:
$ ssh-keygen -f id_ed25519 -N ""
Consign the Key to the RO Server
Encrypt with the "ssh-sign-with" usage only:
$ ro -server localhost:443 -ca server.crt \
-minUsers 2 -owners alice,bob -usages ssh-sign-with \
-in id_ed25519 -out id_ed25519.encrypted encrypt
Start the RO SSH Agent
Initiate a SSH agent with connection to the remote RO server:
$ ro -server localhost:443 -ca server.crt ssh-agent
2018/02/05 05:21:13 Starting Red October Secret Shell Agent
export SSH_AUTH_SOCK=/tmp/ro_ssh_267631424/roagent.sock
Connect to SSH via RO SSH Agent
On a separate terminal, run:
$ export SSH_AUTH_SOCK=/tmp/ro_ssh_267631424/roagent.sock
$ ro -in ssh_key.encrypted -pubkey ssh_key.pub ssh-add
$ ssh-add -L # list of all public keys available through ro-ssh-agent
Now, all commands that utilize ssh-agents, such as scp, git, etc., will authenticate through the red october server:
$ ssh user@hostname
$ git -T git@github.com
$ ...
SSH Agent Forwarding
Moreover, since ro-ssh-agent is compatible with the ssh-agent protocol, you can forward the ro-ssh-agent:
localhost $ ssh -A user@middle # calls local ro-ssh-agent to ask RO server for a signature
middle $ ssh -A user@far # calls local ssh-agent for a signature, which forwards the
# request packet to the ro-ssh-agent
far $ echo Profit!