vault-kv 0.12.0

data/README.md

@@ -0,0 +1,212 @@
+Vault Ruby Client [![Build Status](https://secure.travis-ci.org/hashicorp/vault-ruby.svg)](http://travis-ci.org/hashicorp/vault-ruby)
+=================
+
+Vault is the official Ruby client for interacting with [Vault](https://vaultproject.io) by HashiCorp.
+
+**The documentation in this README corresponds to the master branch of the Vault Ruby client. It may contain unreleased features or different APIs than the most recently released version. Please see the Git tag that corresponds to your version of the Vault Ruby client for the proper documentation.**
+
+Quick Start
+-----------
+Install Ruby 2.0+: [Guide](https://www.ruby-lang.org/en/documentation/installation/).
+
+> Please note that Vault Ruby may work on older Ruby installations like Ruby 1.9, but you **should not** use these versions of Ruby when communicating with a Vault server. Ruby 1.9 has [reached EOL](https://www.ruby-lang.org/en/news/2014/01/10/ruby-1-9-3-will-end-on-2015/) and will no longer receive important security patches or maintenance updates. There _are known security vulnerabilities_ specifically around SSL ciphers, which this library uses to communicate with a Vault server. While many distros still ship with Ruby 1.9 as the default, you are **highly discouraged** from using this library on any version of Ruby lower than Ruby 2.0.
+
+Install via Rubygems:
+
+    $ gem install vault
+
+or add it to your Gemfile if you're using Bundler:
+
+```ruby
+gem "vault", "~> 0.1"
+```
+
+and then run the `bundle` command to install.
+
+Start a Vault client:
+
+```ruby
+Vault.address = "http://127.0.0.1:8200" # Also reads from ENV["VAULT_ADDR"]
+Vault.token   = "abcd-1234" # Also reads from ENV["VAULT_TOKEN"]
+
+Vault.sys.mounts #=> { :secret => #<struct Vault::Mount type="generic", description="generic secret storage"> }
+```
+
+Usage
+-----
+The following configuration options are available:
+
+```ruby
+Vault.configure do |config|
+  # The address of the Vault server, also read as ENV["VAULT_ADDR"]
+  config.address = "https://127.0.0.1:8200"
+
+  # The token to authenticate with Vault, also read as ENV["VAULT_TOKEN"]
+  config.token = "abcd-1234"
+
+  # Proxy connection information, also read as ENV["VAULT_PROXY_(thing)"]
+  config.proxy_address  = "..."
+  config.proxy_port     = "..."
+  config.proxy_username = "..."
+  config.proxy_password = "..."
+
+  # Custom SSL PEM, also read as ENV["VAULT_SSL_CERT"]
+  config.ssl_pem_file = "/path/on/disk.pem"
+
+  # As an alternative to a pem file, you can provide the raw PEM string, also read in the following order of preference:
+  # ENV["VAULT_SSL_PEM_CONTENTS_BASE64"] then ENV["VAULT_SSL_PEM_CONTENTS"]
+  config.ssl_pem_contents = "-----BEGIN ENCRYPTED..."
+
+  # Use SSL verification, also read as ENV["VAULT_SSL_VERIFY"]
+  config.ssl_verify = false
+
+  # Timeout the connection after a certain amount of time (seconds), also read
+  # as ENV["VAULT_TIMEOUT"]
+  config.timeout = 30
+
+  # It is also possible to have finer-grained controls over the timeouts, these
+  # may also be read as environment variables
+  config.ssl_timeout  = 5
+  config.open_timeout = 5
+  config.read_timeout = 30
+end
+```
+
+If you do not want the Vault singleton, or if you need to communicate with multiple Vault servers at once, you can create independent client objects:
+
+```ruby
+client_1 = Vault::Client.new(address: "https://vault.mycompany.com")
+client_2 = Vault::Client.new(address: "https://other-vault.mycompany.com")
+```
+
+And if you want to authenticate with a `AWS EC2` :
+
+```ruby
+    # Export VAULT_ADDR to ENV then
+    # Get the pkcs7 value from AWS
+    signature = `curl http://169.254.169.254/latest/dynamic/instance-identity/pkcs7`
+    vault_token = Vault.auth.aws_ec2(ENV['EC2_ROLE'], signature, nil)
+    vault_client = Vault::Client.new(address: ENV["VAULT_ADDR"], token: vault_token.auth.client_token)
+```
+
+### Making requests
+All of the methods and API calls are heavily documented with examples inline using YARD. In order to keep the examples versioned with the code, the README only lists a few examples for using the Vault gem. Please see the inline documentation for the full API documentation. The tests in the 'spec' directory are an additional source of examples.
+
+Idempotent requests can be wrapped with a `with_retries` clause to automatically retry on certain connection errors. For example, to retry on socket/network-level issues, you can do the following:
+
+```ruby
+Vault.with_retries(Vault::HTTPConnectionError) do
+  Vault.logical.read("secret/on_bad_network")
+end
+```
+
+To rescue particular HTTP exceptions:
+
+```ruby
+# Rescue 4xx errors
+Vault.with_retries(Vault::HTTPClientError) {}
+
+# Rescue 5xx errors
+Vault.with_retries(Vault::HTTPServerError) {}
+
+# Rescue all HTTP errors
+Vault.with_retries(Vault::HTTPError) {}
+```
+
+For advanced users, the first argument of the block is the attempt number and the second argument is the exception itself:
+
+```ruby
+Vault.with_retries(Vault::HTTPConnectionError, Vault::HTTPError) do |attempt, e|
+  log "Received exception #{e} from Vault - attempt #{attempt}"
+  Vault.logical.read("secret/bacon")
+end
+```
+
+The following options are available:
+
+```ruby
+# :attempts - The number of retries when communicating with the Vault server.
+#   The default value is 2.
+#
+# :base - The base interval for retry exponential backoff. The default value is
+#   0.05s.
+#
+# :max_wait - The maximum amount of time for a single exponential backoff to
+#   sleep. The default value is 2.0s.
+
+Vault.with_retries(Vault::HTTPError, attempts: 5) do
+  # ...
+end
+```
+
+After the number of retries have been exhausted, the original exception is raised.
+
+```ruby
+Vault.with_retries(Exception) do
+  raise Exception
+end #=> #<Exception>
+```
+
+#### Seal Status
+```ruby
+Vault.sys.seal_status
+#=> #<Vault::SealStatus sealed=false, t=1, n=1, progress=0>
+```
+
+#### Create a Secret
+```ruby
+Vault.logical.write("secret/bacon", delicious: true, cooktime: "11")
+#=> #<Vault::Secret lease_id="">
+```
+
+#### Retrieve a Secret
+```ruby
+Vault.logical.read("secret/bacon")
+#=> #<Vault::Secret lease_id="">
+```
+
+#### Retrieve the Contents of a Secret
+```ruby
+secret = Vault.logical.read("secret/bacon")
+secret.data #=> { :cooktime = >"11", :delicious => true }
+```
+
+### Response wrapping
+
+```ruby
+# Request new access token as wrapped response where the TTL of the temporary
+# token is "5s".
+wrapped = Vault.auth_token.create(wrap_ttl: "5s")
+
+# Unwrap the wrapped response to get the final token using the initial temporary
+# token from the first request.
+unwrapped = Vault.logical.unwrap(wrapped.wrap_info.token)
+
+# Extract the final token from the response.
+token = unwrapped.data.auth.client_token
+```
+
+A helper function is also provided when unwrapping a token directly:
+
+```ruby
+# Request new access token as wrapped response where the TTL of the temporary
+# token is "5s".
+wrapped = Vault.auth_token.create(wrap_ttl: "5s")
+
+# Unwrap wrapped response for final token using the initial temporary token.
+token = Vault.logical.unwrap_token(wrapped)
+```
+
+
+Development
+-----------
+1. Clone the project on GitHub
+2. Create a feature branch
+3. Submit a Pull Request
+
+Important Notes:
+
+- **All new features must include test coverage.** At a bare minimum, Unit tests are required. It is preferred if you include acceptance tests as well.
+- **The tests must be be idempotent.** The HTTP calls made during a test should be able to be run over and over.
+- **Tests are order independent.** The default RSpec configuration randomizes the test order, so this should not be a problem.
+- **Integration tests require Vault**  Vault must be available in the path for the integration tests to pass.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/vault.rb

@@ -0,0 +1,49 @@
+module Vault
+  require_relative "vault/errors"
+  require_relative "vault/client"
+  require_relative "vault/configurable"
+  require_relative "vault/defaults"
+  require_relative "vault/response"
+  require_relative "vault/version"
+
+  require_relative "vault/api"
+
+  class << self
+    # API client object based off the configured options in {Configurable}.
+    #
+    # @return [Vault::Client]
+    attr_reader :client
+
+    def setup!
+      @client = Vault::Client.new
+
+      # Set secure SSL options
+      OpenSSL::SSL::SSLContext::DEFAULT_PARAMS[:options].tap do |opts|
+        opts &= ~OpenSSL::SSL::OP_DONT_INSERT_EMPTY_FRAGMENTS if defined?(OpenSSL::SSL::OP_DONT_INSERT_EMPTY_FRAGMENTS)
+        opts |= OpenSSL::SSL::OP_NO_COMPRESSION if defined?(OpenSSL::SSL::OP_NO_COMPRESSION)
+        opts |= OpenSSL::SSL::OP_NO_SSLv2 if defined?(OpenSSL::SSL::OP_NO_SSLv2)
+        opts |= OpenSSL::SSL::OP_NO_SSLv3 if defined?(OpenSSL::SSL::OP_NO_SSLv3)
+      end
+
+      self
+    end
+
+    # Delegate all methods to the client object, essentially making the module
+    # object behave like a {Client}.
+    def method_missing(m, *args, &block)
+      if @client.respond_to?(m)
+        @client.send(m, *args, &block)
+      else
+        super
+      end
+    end
+
+    # Delegating +respond_to+ to the {Client}.
+    def respond_to_missing?(m, include_private = false)
+      @client.respond_to?(m, include_private) || super
+    end
+  end
+end
+
+# Load the initial default values
+Vault.setup!

data/lib/vault/api.rb

@@ -0,0 +1,13 @@
+module Vault
+  module API
+    require_relative "api/approle"
+    require_relative "api/auth_token"
+    require_relative "api/auth_tls"
+    require_relative "api/auth"
+    require_relative "api/help"
+    require_relative "api/kv"
+    require_relative "api/logical"
+    require_relative "api/secret"
+    require_relative "api/sys"
+  end
+end

data/lib/vault/api/approle.rb

@@ -0,0 +1,218 @@
+require "json"
+
+require_relative "secret"
+require_relative "../client"
+require_relative "../request"
+require_relative "../response"
+
+module Vault
+  class Client
+    # A proxy to the {AppRole} methods.
+    # @return [AppRole]
+    def approle
+      @approle ||= AppRole.new(self)
+    end
+  end
+
+  class AppRole < Request
+    # Creates a new AppRole or update an existing AppRole with the given name
+    # and attributes.
+    #
+    # @example
+    #   Vault.approle.set_role("testrole", {
+    #     secret_id_ttl: "10m",
+    #     token_ttl:     "20m",
+    #     policies:      "default",
+    #     period:        3600,
+    #   }) #=> true
+    #
+    # @param [String] name
+    #   The name of the AppRole
+    # @param [Hash] options
+    # @option options [Boolean] :bind_secret_id
+    #   Require secret_id to be presented when logging in using this AppRole.
+    # @option options [String] :bound_cidr_list
+    #   Comma-separated list of CIDR blocks. Specifies blocks of IP addresses
+    #   which can perform the login operation.
+    # @option options [String] :policies
+    #   Comma-separated list of policies set on tokens issued via this AppRole.
+    # @option options [String] :secret_id_num_uses
+    #   Number of times any particular SecretID can be used to fetch a token
+    #   from this AppRole, after which the SecretID will expire.
+    # @option options [Fixnum, String] :secret_id_ttl
+    #   The number of seconds or a golang-formatted timestamp like "60m" after
+    #   which any SecretID expires.
+    # @option options [Fixnum, String] :token_ttl
+    #   The number of seconds or a golang-formatted timestamp like "60m" to set
+    #   as the TTL for issued tokens and at renewal time.
+    # @option options [Fixnum, String] :token_max_ttl
+    #   The number of seconds or a golang-formatted timestamp like "60m" after
+    #   which the issued token can no longer be renewed.
+    # @option options [Fixnum, String] :period
+    #   The number of seconds or a golang-formatted timestamp like "60m".
+    #   If set, the token generated using this AppRole is a periodic token.
+    #   So long as it is renewed it never expires, but the TTL set on the token
+    #   at each renewal is fixed to the value specified here. If this value is
+    #   modified, the token will pick up the new value at its next renewal.
+    #
+    # @return [true]
+    def set_role(name, options = {})
+      headers = extract_headers!(options)
+      client.post("/v1/auth/approle/role/#{encode_path(name)}", JSON.fast_generate(options), headers)
+      return true
+    end
+
+    # Gets the AppRole by the given name. If an AppRole does not exist by that
+    # name, +nil+ is returned.
+    #
+    # @example
+    #   Vault.approle.role("testrole") #=> #<Vault::Secret lease_id="...">
+    #
+    # @return [Secret, nil]
+    def role(name)
+      json = client.get("/v1/auth/approle/role/#{encode_path(name)}")
+      return Secret.decode(json)
+    rescue HTTPError => e
+      return nil if e.code == 404
+      raise
+    end
+
+    # Gets the list of AppRoles in vault auth backend.
+    #
+    # @example
+    #   Vault.approle.roles #=> ["testrole"]
+    #
+    # @return [Array<String>]
+    def roles(options = {})
+      headers = extract_headers!(options)
+      json = client.list("/v1/auth/approle/role", options, headers)
+      return Secret.decode(json).data[:keys] || []
+    rescue HTTPError => e
+      return [] if e.code == 404
+      raise
+    end
+
+    # Reads the RoleID of an existing AppRole. If an AppRole does not exist by
+    # that name, +nil+ is returned.
+    #
+    # @example
+    #   Vault.approle.role_id("testrole") #=> #<Vault::Secret lease_id="...">
+    #
+    # @return [Secret, nil]
+    def role_id(name)
+      json = client.get("/v1/auth/approle/role/#{encode_path(name)}/role-id")
+      return Secret.decode(json).data[:role_id]
+    rescue HTTPError => e
+      return nil if e.code == 404
+      raise
+    end
+
+    # Updates the RoleID of an existing AppRole to a custom value.
+    #
+    # @example
+    #   Vault.approle.set_role_id("testrole") #=> true
+    #
+    # @return [true]
+    def set_role_id(name, role_id)
+      options = { role_id: role_id }
+      client.post("/v1/auth/approle/role/#{encode_path(name)}/role-id", JSON.fast_generate(options))
+      return true
+    end
+
+    # Deletes the AppRole with the given name. If an AppRole does not exist,
+    # vault will not return an error.
+    #
+    # @example
+    #   Vault.approle.delete_role("testrole") #=> true
+    #
+    # @param [String] name
+    #   the name of the certificate
+    def delete_role(name)
+      client.delete("/v1/auth/approle/role/#{encode_path(name)}")
+      return true
+    end
+
+    # Generates and issues a new SecretID on an existing AppRole.
+    #
+    # @example Generate a new SecretID
+    #   result = Vault.approle.create_secret_id("testrole") #=> #<Vault::Secret lease_id="...">
+    #   result.data[:secret_id] #=> "841771dc-11c9-bbc7-bcac-6a3945a69cd9"
+    #
+    # @example Assign a custom SecretID
+    #   result = Vault.approle.create_secret_id("testrole", {
+    #     secret_id: "testsecretid"
+    #   }) #=> #<Vault::Secret lease_id="...">
+    #   result.data[:secret_id] #=> "testsecretid"
+    #
+    # @param [String] role_name
+    #   The name of the AppRole
+    # @param [Hash] options
+    # @option options [String] :secret_id
+    #   SecretID to be attached to the Role. If not set, then the new SecretID
+    #   will be generated
+    # @option options [Hash<String, String>] :metadata
+    #   Metadata to be tied to the SecretID. This should be a JSON-formatted
+    #   string containing the metadata in key-value pairs. It will be set on
+    #   tokens issued with this SecretID, and is logged in audit logs in
+    #   plaintext.
+    #
+    # @return [true]
+    def create_secret_id(role_name, options = {})
+      headers = extract_headers!(options)
+      if options[:secret_id]
+        json = client.post("/v1/auth/approle/role/#{encode_path(role_name)}/custom-secret-id", JSON.fast_generate(options), headers)
+      else
+        json = client.post("/v1/auth/approle/role/#{encode_path(role_name)}/secret-id", JSON.fast_generate(options), headers)
+      end
+      return Secret.decode(json)
+    end
+
+    # Reads out the properties of a SecretID assigned to an AppRole.
+    # If the specified SecretID don't exist, +nil+ is returned.
+    #
+    # @example
+    #   Vault.approle.role("testrole", "841771dc-11c9-...") #=> #<Vault::Secret lease_id="...">
+    #
+    # @param [String] role_name
+    #   The name of the AppRole
+    # @param [String] secret_id
+    #   SecretID belonging to AppRole
+    #
+    # @return [Secret, nil]
+    def secret_id(role_name, secret_id)
+      opts = { secret_id: secret_id }
+      json = client.post("/v1/auth/approle/role/#{encode_path(role_name)}/secret-id/lookup", JSON.fast_generate(opts), {})
+      return nil unless json
+      return Secret.decode(json)
+    rescue HTTPError => e
+      if e.code == 404 || e.code == 405
+        begin
+          json = client.get("/v1/auth/approle/role/#{encode_path(role_name)}/secret-id/#{encode_path(secret_id)}")
+          return Secret.decode(json)
+        rescue HTTPError => e
+          return nil if e.code == 404
+          raise e
+        end
+      end
+
+      raise
+    end
+
+    # Lists the accessors of all the SecretIDs issued against the AppRole.
+    # This includes the accessors for "custom" SecretIDs as well. If there are
+    # no SecretIDs against this role, an empty array will be returned.
+    #
+    # @example
+    #   Vault.approle.secret_ids("testrole") #=> ["ce102d2a-...", "a1c8dee4-..."]
+    #
+    # @return [Array<String>]
+    def secret_id_accessors(role_name, options = {})
+      headers = extract_headers!(options)
+      json = client.list("/v1/auth/approle/role/#{encode_path(role_name)}/secret-id", options, headers)
+      return Secret.decode(json).data[:keys] || []
+    rescue HTTPError => e
+      return [] if e.code == 404
+      raise
+    end
+  end
+end