vault_ruby_client 0.18.2

data/README.md

@@ -0,0 +1,223 @@
+# Vault Ruby Client
+
+[![Gem Version](https://img.shields.io/gem/v/vault_ruby_client.svg?style=flat)](https://rubygems.org/gems/vault_ruby_client)
+[![Build Status](https://github.com/khiav223577/vault_ruby_client/workflows/Ruby/badge.svg)](https://github.com/khiav223577/vault_ruby_client/actions)
+[![RubyGems](http://img.shields.io/gem/dt/vault_ruby_client.svg?style=flat)](https://rubygems.org/gems/vault_ruby_client)
+[![Code Climate](https://codeclimate.com/github/khiav223577/vault_ruby_client/badges/gpa.svg)](https://codeclimate.com/github/khiav223577/vault_ruby_client)
+[![Test Coverage](https://codeclimate.com/github/khiav223577/vault_ruby_client/badges/coverage.svg)](https://codeclimate.com/github/khiav223577/vault_ruby_client/coverage)
+
+Vault is the official Ruby client for interacting with [Vault](https://vaultproject.io) by HashiCorp.
+
+Quick Start
+-----------
+Install Ruby 2.0+: [Guide](https://www.ruby-lang.org/en/documentation/installation/).
+
+> Please note that as of Vault Ruby version 0.14.0 versions of Ruby prior to 2.0 are no longer supported.
+
+Install via Rubygems:
+
+    $ gem install vault_ruby_client
+
+or add it to your Gemfile if you're using Bundler:
+
+```ruby
+gem "vault_ruby_client"
+```
+
+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"]
+# Optional - if using the Namespace enterprise feature
+# Vault.namespace   = "my-namespace" # Also reads from ENV["VAULT_NAMESPACE"]
+
+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"
+  # Optional - if using the Namespace enterprise feature
+  # config.namespace   = "my-namespace" # Also reads from ENV["VAULT_NAMESPACE"]
+
+  # 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`
+    iam_role = `curl http://169.254.169.254/latest/meta-data/iam/security-credentials/`
+    vault_token = Vault.auth.aws_ec2(iam_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|
+  if e
+    log "Received exception #{e} from Vault - attempt #{attempt}"
+  end
+  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 integration tests as well.
+- **The tests must 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.
+   - **In order to be considered an integration test:** The test MUST use the `vault_test_client` or `vault_redirect_test_client` as the client. This spawns a process, or uses an already existing process from another test, to run against.

data/lib/vault/api/approle.rb

@@ -0,0 +1,221 @@
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: MPL-2.0
+
+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