vault 0.10.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 7e5fd83ffdf4937b80770ad21d25b1bab18b036b
-  data.tar.gz: 7d82f65b6e31bd4f8f4887bdc2224040159fc402
+SHA256:
+  metadata.gz: 46c570463a1aba190e789e5b2516b4140d48961611ff058235d3b9744e6a6b24
+  data.tar.gz: c84a96cf71d9f405281f56629e0fb68a6ce051740ea46da60e35cabf37d8b44e
 SHA512:
-  metadata.gz: bad1f9d3302041a5532145af4c1cd07d3f7fe289c5a81d3edd0cd410b0f0130d59f09a8ceea82955cf28b4f36dbefb6fa73cb1145d5e117a01dff537b9a3ab3b
-  data.tar.gz: 4c0b02bf433aa26c3573f8d6b9728662efc2a0d7fd8138cb486e4c4c044ba6d728c4405b910582f7c34feb3c0788aeb89874ea6999027379502821782e86b018
+  metadata.gz: 98a20e963ec212e2269d1c28b581c24b356495789b4b37b20ebcb829c17904b518fc32f9cd2dadfcd59b957361410e7aa61f88e7ad419d72533d0ac1bd0ec68d
+  data.tar.gz: 35f0126a7e7ba6173662222a9006cd02bc2f78d6d674533546b68ad87420f99b1e26f1f160058b2a051c36a5faac219921ab24191f9165212ddc8f15c440e0a6

data/CHANGELOG.md

@@ -1,5 +1,73 @@
 # Vault Ruby Changelog
 
+## v0.16.0 (??? ??, 2021)
+
+IMPROVEMENTS
+
+- The timeout used to get a connection from the connection pool that talks with vault is now configurable. Using `Vault.pool_timeout` or the env var `VAULT_POOL_TIMEOUT`.
+
+## v0.15.0 (July 29, 2020)
+
+IMPROVEMENTS
+
+- Added support for Resource Quotas
+
+## v0.14.0 (May 28, 2020)
+
+IMPROVEMENTS
+
+- Added support for the Transform Secrets Engine
+
+## v0.13.2 (May 7, 2020)
+
+BUG FIXES
+
+- Fixed the ability to use namespace as an option for each request. Previously, that option was ignored.
+- aws-sigv4 gem was unlocked after a bug in 1.1.2 broke CI
+
+## v0.13.1 (April 28, 2020)
+
+IMPROVEMENTS
+
+- Added support for defining a namespace when initializing the client, as well as options for changing the namespace via method.
+- Added support for sys/namespaces API. Ability to Get, Create, Delete, and List namespaces has been provided.
+
+## v0.13.0 (October 1, 2019)
+
+IMPROVEMENTS
+
+- Add support for versioned KV secrets in the client
+
+## v0.12.0 (August 14, 2018)
+
+IMPROVEMENTS
+
+- Expose the github login path as an optional argument
+- Support HTTP basic auth [GH-181]
+- Expose the AWS IAM path to use [GH-180]
+- Add GCP Auth [GH-173]
+- Add shutdown functionality to close persistent connections [GH-175]
+
+BUG FIXES
+
+- Specifing the hostname for SNI didn't work. The functionality has been disabled for now.
+
+## v0.11.0 (March 19, 2018)
+
+IMPROVEMENTS
+
+- Access to health has been added.
+- Added ability to handle a Base64 encoded PEM (useful for certs in environment variables)
+- Added IAM EC2 authentication support
+- Add custom mount path support to TLS authentication
+
+## v0.10.1 (May 8, 2017)
+
+IMPROVEMENTS
+
+- `vault-ruby` is licensed under Mozilla Public License 2.0, and has been for over 2 years. This patch release updates the gemspec to use the correct SPDX ID string for reporting this license, but **no change to the licensing of this gem has occurred**.
+
+
 ## v0.10.0 (April 19, 2017)
 
 IMPROVEMENTS

data/README.md

@@ -1,15 +1,17 @@
-Vault Ruby Client [![Build Status](https://secure.travis-ci.org/hashicorp/vault-ruby.svg)](http://travis-ci.org/hashicorp/vault-ruby)
+Vault Ruby Client [![Build Status](https://circleci.com/gh/hashicorp/vault-ruby.svg?style=shield)](https://circleci.com/gh/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.**
+**If you're viewing this README from GitHub on the `master` branch, know that 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.
+> 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:
 
@@ -18,7 +20,7 @@ Install via Rubygems:
 or add it to your Gemfile if you're using Bundler:
 
 ```ruby
-gem "vault", "~> 0.1"
+gem "vault"
 ```
 
 and then run the `bundle` command to install.
@@ -28,6 +30,8 @@ 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"> }
 ```
@@ -43,6 +47,8 @@ Vault.configure do |config|
 
   # 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  = "..."
@@ -53,6 +59,10 @@ Vault.configure do |config|
   # 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
 
@@ -75,6 +85,17 @@ 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.
 
@@ -103,7 +124,9 @@ For advanced users, the first argument of the block is the attempt number and th
 
 ```ruby
 Vault.with_retries(Vault::HTTPConnectionError, Vault::HTTPError) do |attempt, e|
-  log "Received exception #{e} from Vault - attempt #{attempt}"
+  if e
+    log "Received exception #{e} from Vault - attempt #{attempt}"
+  end
   Vault.logical.read("secret/bacon")
 end
 ```
@@ -192,7 +215,8 @@ Development
 
 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.
+- **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.rb

@@ -5,8 +5,10 @@ module Vault
     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"
+    require_relative "api/transform"
   end
 end

data/lib/vault/api/auth.rb

@@ -155,9 +155,9 @@ module Vault
     # @param [String] github_token
     #
     # @return [Secret]
-    def github(github_token)
+    def github(github_token, path="/v1/auth/github/login")
       payload = {token: github_token}
-      json = client.post("/v1/auth/github/login", JSON.fast_generate(payload))
+      json = client.post(path, JSON.fast_generate(payload))
       secret = Secret.decode(json)
       client.token = secret.auth.client_token
       return secret
@@ -173,12 +173,95 @@ module Vault
     # @param [String] role
     # @param [String] pkcs7
     #   pkcs7 returned by the instance identity document (with line breaks removed)
-    # @param [String] nonce
+    # @param [String] nonce optional
+    # @param [String] route optional
     #
     # @return [Secret]
-    def aws_ec2(role, pkcs7, nonce)
-      payload = { role: role, pkcs7: pkcs7, nonce: nonce }
-      json = client.post('/v1/auth/aws-ec2/login', JSON.fast_generate(payload))
+    def aws_ec2(role, pkcs7, nonce = nil, route = nil)
+      route ||= '/v1/auth/aws-ec2/login'
+      payload = { role: role, pkcs7: pkcs7 }
+      # Set a custom nonce if client is providing one
+      payload[:nonce] = nonce if nonce
+      json = client.post(route, JSON.fast_generate(payload))
+      secret = Secret.decode(json)
+      client.token = secret.auth.client_token
+      return secret
+    end
+
+    # Authenticate via AWS IAM auth method by providing a AWS CredentialProvider (either ECS, AssumeRole, etc.)
+    # If authentication is successful, the resulting token will be stored on the client and used
+    # for future requests.
+    #
+    # @example
+    #   Vault.auth.aws_iam("dev-role-iam", Aws::InstanceProfileCredentials.new, "vault.example.com", "https://sts.us-east-2.amazonaws.com") #=> #<Vault::Secret lease_id="">
+    #
+    # @param [String] role
+    # @param [CredentialProvider] credentials_provider
+    #   https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/CredentialProvider.html
+    # @param [String] iam_auth_header_value optional
+    #   As of Jan 2018, Vault will accept ANY or NO header if none is configured by the Vault server admin
+    # @param [String] sts_endpoint optional
+    #   https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html
+    # @param [String] route optional
+    # @return [Secret]
+    def aws_iam(role, credentials_provider, iam_auth_header_value = nil, sts_endpoint = 'https://sts.amazonaws.com', route = nil)
+      require "aws-sigv4"
+      require "base64"
+
+      request_body   = 'Action=GetCallerIdentity&Version=2011-06-15'
+      request_method = 'POST'
+
+      route ||= '/v1/auth/aws/login'
+
+      vault_headers = {
+        'User-Agent' => Vault::Client::USER_AGENT,
+        'Content-Type' => 'application/x-www-form-urlencoded; charset=utf-8'
+      }
+
+      vault_headers['X-Vault-AWS-IAM-Server-ID'] = iam_auth_header_value if iam_auth_header_value
+
+      sig4_headers = Aws::Sigv4::Signer.new(
+        service: 'sts',
+        region: region_from_sts_endpoint(sts_endpoint),
+        credentials_provider: credentials_provider
+      ).sign_request(
+        http_method: request_method,
+        url: sts_endpoint,
+        headers: vault_headers,
+        body: request_body
+      ).headers
+
+      payload = {
+        role: role,
+        iam_http_request_method: request_method,
+        iam_request_url: Base64.strict_encode64(sts_endpoint),
+        iam_request_headers: Base64.strict_encode64(vault_headers.merge(sig4_headers).to_json),
+        iam_request_body: Base64.strict_encode64(request_body)
+      }
+
+      json = client.post(route, JSON.fast_generate(payload))
+      secret = Secret.decode(json)
+      client.token = secret.auth.client_token
+      return secret
+    end
+
+    # Authenticate via the GCP authentication method. If authentication is
+    # successful, the resulting token will be stored on the client and used
+    # for future requests.
+    #
+    # @example
+    #   Vault.auth.gcp("read-only", "jwt", "gcp") #=> #<Vault::Secret lease_id="">
+    #
+    # @param [String] role
+    # @param [String] jwt
+    #   jwt returned by the instance identity metadata, or iam api
+    # @param [String] path optional
+    #   the path were the gcp auth backend is mounted
+    #
+    # @return [Secret]
+    def gcp(role, jwt, path = 'gcp')
+      payload = { role: role, jwt: jwt }
+      json = client.post("/v1/auth/#{CGI.escape(path)}/login", JSON.fast_generate(payload))
       secret = Secret.decode(json)
       client.token = secret.auth.client_token
       return secret
@@ -194,18 +277,40 @@ module Vault
     # @example Reading a pem from disk
     #   Vault.auth.tls(File.read("/path/to/my/certificate.pem")) #=> #<Vault::Secret lease_id="">
     #
+    # @example Sending to a cert authentication backend mounted at a custom location
+    #   Vault.auth.tls(pem_contents, 'custom/location') #=> #<Vault::Secret lease_id="">
+    #
     # @param [String] pem (default: the configured SSL pem file or contents)
     #   The raw pem contents to use for the login procedure.
     #
+    # @param [String] path (default: 'cert')
+    #   The path to the auth backend to use for the login procedure.
+    #
     # @return [Secret]
-    def tls(pem = nil)
+    def tls(pem = nil, path = 'cert')
       new_client = client.dup
       new_client.ssl_pem_contents = pem if !pem.nil?
 
-      json = new_client.post("/v1/auth/cert/login")
+      json = new_client.post("/v1/auth/#{CGI.escape(path)}/login")
       secret = Secret.decode(json)
       client.token = secret.auth.client_token
       return secret
     end
+
+    private
+
+    # Parse an AWS region from a STS endpoint
+    # STS in the China (Beijing) region (cn-north-1) is sts.cn-north-1.amazonaws.com.cn
+    # Take care changing below regex with that edge case in mind
+    #
+    # @param [String] sts_endpoint
+    #   https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html
+    #
+    # @return [String] aws region
+    def region_from_sts_endpoint(sts_endpoint)
+      valid_sts_endpoint = %r{https:\/\/sts\.?(.*).amazonaws.com}.match(sts_endpoint)
+      raise "Unable to parse STS endpoint #{sts_endpoint}" unless valid_sts_endpoint
+      valid_sts_endpoint[1].empty? ? 'us-east-1' : valid_sts_endpoint[1]
+    end
   end
 end

data/lib/vault/api/auth_token.rb

@@ -102,7 +102,7 @@ module Vault
     # Lookup information about the current token.
     #
     # @example
-    #   Vault.auth_token.lookup_self("abcd-...") #=> #<Vault::Secret lease_id="">
+    #   Vault.auth_token.lookup("abcd-...") #=> #<Vault::Secret lease_id="">
     #
     # @param [String] token
     # @param [Hash] options
@@ -215,7 +215,7 @@ module Vault
     # @return [true]
     def revoke_accessor(accessor, options = {})
       headers = extract_headers!(options)
-      client.put("/v1/auth/accessor/revoke-accessor", JSON.fast_generate(
+      client.put("/v1/auth/token/revoke-accessor", JSON.fast_generate(
         accessor: accessor,
       ), headers)
       return true

data/lib/vault/api/kv.rb

@@ -0,0 +1,207 @@
+require_relative "secret"
+require_relative "../client"
+require_relative "../request"
+require_relative "../response"
+
+module Vault
+  class Client
+    # A proxy to the {KV} methods.
+    # @return [KV]
+    def kv(mount)
+      KV.new(self, mount)
+    end
+  end
+
+  class KV < Request
+    attr_reader :mount
+
+    def initialize(client, mount)
+      super client
+
+      @mount = mount
+    end
+
+    # List the names of secrets at the given path, if the path supports
+    # listing. If the the path does not exist, an empty array will be returned.
+    #
+    # @example
+    #   Vault.kv("secret").list("foo") #=> ["bar", "baz"]
+    #
+    # @param [String] path
+    #   the path to list
+    #
+    # @return [Array<String>]
+    def list(path = "", options = {})
+      headers = extract_headers!(options)
+      json = client.list("/v1/#{mount}/metadata/#{encode_path(path)}", {}, headers)
+      json[:data][:keys] || []
+    rescue HTTPError => e
+      return [] if e.code == 404
+      raise
+    end
+
+    # Read the secret at the given path. If the secret does not exist, +nil+
+    # will be returned. The latest version is returned by default, but you
+    # can request a specific version.
+    #
+    # @example
+    #   Vault.kv("secret").read("password") #=> #<Vault::Secret lease_id="">
+    #
+    # @param [String] path
+    #   the path to read
+    # @param [Integer] version
+    #   the version of the secret
+    #
+    # @return [Secret, nil]
+    def read(path, version = nil, options = {})
+      headers = extract_headers!(options)
+      params  = {}
+      params[:version] = version unless version.nil?
+
+      json = client.get("/v1/#{mount}/data/#{encode_path(path)}", params, headers)
+      return Secret.decode(json[:data])
+    rescue HTTPError => e
+      return nil if e.code == 404
+      raise
+    end
+
+    # Read the metadata of a secret at the given path. If the secret does not
+    # exist, nil will be returned.
+    #
+    # @example
+    #    Vault.kv("secret").read_metadata("password") => {...}
+    #
+    # @param [String] path
+    #   the path to read
+    #
+    # @return [Hash, nil]
+    def read_metadata(path)
+      client.get("/v1/#{mount}/metadata/#{encode_path(path)}")[:data]
+    rescue HTTPError => e
+      return nil if e.code == 404
+      raise
+    end
+
+    # Write the secret at the given path with the given data. Note that the
+    # data must be a {Hash}!
+    #
+    # @example
+    #   Vault.logical.write("secret/password", value: "secret") #=> #<Vault::Secret lease_id="">
+    #
+    # @param [String] path
+    #   the path to write
+    # @param [Hash] data
+    #   the data to write
+    #
+    # @return [Secret]
+    def write(path, data = {}, options = {})
+      headers = extract_headers!(options)
+      json = client.post("/v1/#{mount}/data/#{encode_path(path)}", JSON.fast_generate(:data => data), headers)
+      if json.nil?
+        return true
+      else
+        return Secret.decode(json)
+      end
+    end
+
+    # Write the metadata of a secret at the given path. Note that the data must
+    # be a {Hash}.
+    #
+    # @example
+    #    Vault.kv("secret").write_metadata("password", max_versions => 3)
+    #
+    # @param [String] path
+    #   the path to write
+    # @param [Hash] metadata
+    #    the metadata to write
+    #
+    # @return [true]
+    def write_metadata(path, metadata = {})
+      client.post("/v1/#{mount}/metadata/#{encode_path(path)}", JSON.fast_generate(metadata))
+
+      true
+    end
+
+    # Delete the secret at the given path. If the secret does not exist, vault
+    # will still return true.
+    #
+    # @example
+    #   Vault.logical.delete("secret/password") #=> true
+    #
+    # @param [String] path
+    #   the path to delete
+    #
+    # @return [true]
+    def delete(path)
+      client.delete("/v1/#{mount}/data/#{encode_path(path)}")
+
+      true
+    end
+
+    # Mark specific versions of a secret as deleted.
+    #
+    # @example
+    #   Vault.kv("secret").delete_versions("password", [1, 2])
+    #
+    # @param [String] path
+    #   the path to remove versions from
+    # @param [Array<Integer>] versions
+    #   an array of versions to remove
+    #
+    # @return [true]
+    def delete_versions(path, versions)
+      client.post("/v1/#{mount}/delete/#{encode_path(path)}", JSON.fast_generate(versions: versions))
+
+      true
+    end
+
+    # Mark specific versions of a secret as active.
+    #
+    # @example
+    #   Vault.kv("secret").undelete_versions("password", [1, 2])
+    #
+    # @param [String] path
+    #   the path to enable versions for
+    # @param [Array<Integer>] versions
+    #   an array of versions to mark as undeleted
+    #
+    # @return [true]
+    def undelete_versions(path, versions)
+      client.post("/v1/#{mount}/undelete/#{encode_path(path)}", JSON.fast_generate(versions: versions))
+
+      true
+    end
+
+    # Completely remove a secret and its metadata.
+    #
+    # @example
+    #   Vault.kv("secret").destroy("password")
+    #
+    # @param [String] path
+    #   the path to remove
+    #
+    # @return [true]
+    def destroy(path)
+      client.delete("/v1/#{mount}/metadata/#{encode_path(path)}")
+
+      true
+    end
+
+    # Completely remove specific versions of a secret.
+    #
+    # @example
+    #   Vault.kv("secret").destroy_versions("password", [1, 2])
+    #
+    # @param [String] path
+    #   the path to remove versions from
+    # @param [Array<Integer>] versions
+    #   an array of versions to destroy
+    #
+    # @return [true]
+    def destroy_versions(path, versions)
+      client.post("/v1/#{mount}/destroy/#{encode_path(path)}", JSON.fast_generate(versions: versions))
+
+      true
+    end
+  end
+end