Ptolemy v0.2.0 Ptolemy View Source
Ptolemy
provides client side functions calls to fetch, sets and update secrets and environment variables within a remote backend.
Configurating the remote backend
Before using the Ptolemy
module, ensure you have the :vaults
configuration block configured.
Each key within the :vaults
block configures one remote vault server backend.
You can chose to name this key what ever you wish. The key's value is of type map.
Within the actual server configuration block, the top level keys follows a specific schema:
:vault_url
(Required) - A string representing the url of the remote vault server.:engines
- The engines list configuration, all your engines configuration needs be store in here. (See Configuring the:engines
block for more detail):auth
(Required) - A Map containing the necessary information to authenticate against a remote vault server. (See Configuring the:auth
block for more detail)
Configuring the :engines
block
The :engines
block is a keyword list containing engine specific configuration data, which allows for a more friendlier
interface with Ptolemy's APIs.
- The keys in the list can be arbitrarily named.
Values associated with the keys must be of type map with the following keys:
:engine_type
(Required) the engine type must be one of:GCP
,:KV
or:PKI
(as of v0.2):engine_path
(Required) the engine path string, the value will need to always needs to end with a/
.:secrets
(Required only for:KV
) a map of the secrets contained in the engine, this should only be specified if a:KV
engine is specified.:roles
(Required only for:PKI
) a map of the roles contained in the enigne, this should only be specified if a:PKI
engine is specified.
Configuring the :auth
block
The :auth
key found within the server configuration block instructs and provide the necessary information
for a successful authentication against a remote vault server.
The :method
key
(Required) - Specifies the type of auth method ptolemy will try to auth with. One of either (as of version 0.2 and above):
:GCP
:Approle
The :credentials
key
(Required) - A map containing all necessary information concerning auth. Depending on the
authentication method the :credentials
map will have a different keys.
If
:Approle
auth method is specified the:crendentials
map's schema will need to contain the following keys::role_id
- String representation of the role id.:secret_id
- String representation of the secret id.
If
:GCP
auth method is specified the:crendentials
map's schema will need to contain the following keys::gcp_acc_svc
- The base64 string represention of ther GCP service account.:vault_role
- String representation of the vault role associated with the login.:exp
- The integer representation of the validity period for the JWT that will be summited to the remote vault server. Google's maximum validity perriod is 3600 seconds.
The :auto_renew
key
(Required) A boolean indicating if you want the X-Vault-Token
to be auto-renewed when expiry
is near. The Vault token will always be renewed 5 seconds prior to expiry.
The :opts
key
(Required) A keyword list with additional options. As of version 0.2 the only options currently available are for the configuration to authenticate against Google's Cloud Identity Aware Proxy. The following keys are required if you desire to use such options:
:iap_svc_acc
has 2 valid associated values: specifying the:reuse
atom will tell ptolemy to reuse the:gcp_svc_acc
specified in the credentials block (that service account will need the correct IAM permissions for IAP). If:reuse
is not specified a base64 string representation of the service account that has the valid IAM permissions will need to be provided.:client_id
The string representation of the client_id of the OAuth client protecting the resource. Can be found in Security -> Identity-Aware-Proxy -> Select the IAP resource -> Edit OAuth client.:exp
The integer representation of the validity period for the JWT that will be summited to Google. Google's maximum validity perriod is 3600 seconds.
Configuration Examples:
Example configuration can be seen in config/test.exs
or even in examples/simple/config/config.exs
.
Link to this section Summary
Functions
Create a secret in Vault
Delete a secret
Read a secret's key and value from a defined location
Start a process and store all necessary state for a connection to a remote vault server
Updates a secret
Link to this section Functions
create(pid, engine_name, opts \\ []) View Source
Create a secret in Vault.
opts requirements, ARGUMENTS MUST BE AN ORDERED LIST as follow
KV Engine
- secret (Required)
- payload (Required)
- cas (Optional, default: nil)
Example
iex(1)> Ptolemy.create(server, :kv_engine1, [:test_secret, %{test: "foo"}])
{:ok, "KV secret created"}
GCP Engine
- roleset name (Required)
- roleset configuration payload(Required)
Example
iex(1)> Ptolemy.create(server, :gcp_engine1, ["roleset_name", %{
bindings: "bindings",
project: "project-name",
secret_type: "service_account_key"
}])
{:ok, "Roleset implemented"}
PKI Engine
- role name (Required)
- role specifications (Optional)
Example
iex(1)> Ptolemy.create(server, :pki_engine1, [:test_role1, %{allow_any_name: true}])
{:ok, "PKI role created"}
delete(pid, engine_name, opts \\ []) View Source
Delete a secret
opts requirements, ARGUMENTS MUST BE AN ORDERED LIST as follow
KV Engine
- secret (Required)
- vers (Required)
- destroy (Optional, default: false), destroy will leave no trace of the secret
Example
iex(4)> Ptolemy.delete(server, :kv_engine1, [:ptolemy, [1]])
:ok
GCP Engine
- gcp secret type (Required)
- roleset name (Required)
See Ptolemy.Engines.GCP documentation for more information regarding deleting GCP secrets
Example
iex(4)> Ptolemy.delete(server, :gcp_engine1, [:access_token, "roleset_name"])
{:ok, "Rotated"}
PKI Engine
- delete type (Required) :role/:certificate
- arg1 (Required) a. :role -> role name b. :certificate -> serial number
Example
iex(4)> Ptolemy.delete(server, :pki_engine1, [:certificate, "17:84:7f:5b:bd:90:da:21:16"])
{:ok, "PKI certificate revoked"}
iex(5)> Ptolemy.delete(server, :pki_engine1, [:role, :test_tole1])
{:ok, "PKI role revoked"}
read(pid, engine_name, opts \\ []) View Source
Read a secret's key and value from a defined location.
opts requirements, ARGUMENTS MUST BE AN ORDERED LIST as follow
KV Engine
- secret (Required)
- silent (Optional, default: false), use silent option if you want the data ONLY
- version (Optional, default: 0)
Example
iex(2)> Ptolemy.read(server, :kv_engine1, [:ptolemy, true])
{:ok, %{"test" => "foo"}}
GCP Engine
- gcp secret type (Required)
- roleset name (Required)
Example
iex(2)> Ptolemy.read(server, :gcp_engine1, [:service_account_key, "roleset_name"])
{:ok, %{
token: "shhh...",
expires_at_seconds: 1537400046,
token_ttl: 3599
}}
PKI Engine
- role name (Required)
- common name (Required) See vault docs for more details
certificate specs (optional)
## Example
iex(2)> Ptolemy.read(server, :pki_engine1, [:test_role1, "www.example.com"])
{:ok, %{
"data" => %{
"certificate" => "Certificate itself",
"serial_number" => "5b:65:31:58"
},
"lease_duration" => 0}
start(name, config) View Source
Start a process and store all necessary state for a connection to a remote vault server.
Example
iex(2)> {:ok, server} = Ptolemy.start(:production, :server1)
{:ok, #PID<0.228.0>}
update(pid, engine_name, opts \\ []) View Source
Updates a secret
opts requirements, ARGUMENTS MUST BE AN ORDERED LIST as follow
KV Engine
- secret (Required)
- payload (Required)
- cas (Optional, default: nil)
Example
iex(3)> Ptolemy.update(server, :kv_engine1, [:ptolemy, %{test: "bar"}])
:ok
GCP Engine
- roleset name (Required)
- roleset configuration payload (Required)
See Ptolemy.Engines.GCP documentation for restrictions on updating rolesets
Example
iex(3)> Ptolemy.update(server, :gcp_engine1, ["roleset_name", %{
bindings: "bindings",
project: "project-name",
secret_type: "service_account_key"
}])
{:ok, "Roleset implemented"}
PKI Engine
- role name (Required)
- new specifications (Optional) overwrite previous entirely
See Ptolemy.Engines.GCP documentation for restrictions on updating rolesets
Example
iex(3)> Ptolemy.update(server, :pki_engine1, [:test_role1, %{allow_any_name: true}])
{:ok, "PKI role updated"}