Class: Vault::Client

Inherits:
Object
  • Object
show all
Includes:
Configurable
Defined in:
lib/vault/client.rb,
lib/vault/api/sys.rb,
lib/vault/api/auth.rb,
lib/vault/api/help.rb,
lib/vault/api/approle.rb,
lib/vault/api/logical.rb,
lib/vault/api/auth_tls.rb,
lib/vault/api/auth_token.rb

Defined Under Namespace

Classes: SecurityError

Constant Summary collapse

USER_AGENT =

The user agent for this client.

"VaultRuby/#{Vault::VERSION} (+github.com/hashicorp/vault-ruby)".freeze
TOKEN_HEADER =

The name of the header used to hold the Vault token.

"X-Vault-Token".freeze
WRAP_TTL_HEADER =

The name of the header used to hold the wrapped request ttl.

"X-Vault-Wrap-TTL".freeze
LOCATION_HEADER =

The name of the header used for redirection.

"location".freeze
DEFAULT_HEADERS =

The default headers that are sent with every request.

{
  "Content-Type" => "application/json",
  "Accept"       => "application/json",
  "User-Agent"   => USER_AGENT,
}.freeze
JSON_PARSE_OPTIONS =

The default list of options to use when parsing JSON.

{
  max_nesting:      false,
  create_additions: false,
  symbolize_names:  true,
}.freeze
RESCUED_EXCEPTIONS = 
[].tap do |a|
  # Failure to even open the socket (usually permissions)
  a << SocketError

  # Failed to reach the server (aka bad URL)
  a << Errno::ECONNREFUSED

  # Failed to read body or no response body given
  a << EOFError

  # Timeout (Ruby 1.9-)
  a << Timeout::Error

  # Timeout (Ruby 1.9+) - Ruby 1.9 does not define these constants so we
  # only add them if they are defiend
  a << Net::ReadTimeout if defined?(Net::ReadTimeout)
  a << Net::OpenTimeout if defined?(Net::OpenTimeout)

  a << PersistentHTTP::Error
end.freeze

Instance Method Summary collapse

Methods included from Configurable

#configure, keys, #options

Constructor Details

#initialize(options = {}) ⇒ Vault::Client

Create a new Client with the given options. Any options given take precedence over the default options.



71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
 
# File 'lib/vault/client.rb', line 71

def initialize(options = {})
  # Use any options given, but fall back to the defaults set on the module
  Vault::Configurable.keys.each do |key|
    value = options.key?(key) ? options[key] : Defaults.public_send(key)
    instance_variable_set(:"@#{key}", value)
  end

  @nhp = PersistentHTTP.new(name: "vault-ruby")

  if proxy_address
    proxy_uri = URI.parse "http://#{proxy_address}"

    proxy_uri.port = proxy_port if proxy_port

    if proxy_username
      proxy_uri.user = proxy_username
      proxy_uri.password = proxy_password
    end

    @nhp.proxy = proxy_uri
  end

  # Use a custom open timeout
  if open_timeout || timeout
    @nhp.open_timeout = (open_timeout || timeout).to_i
  end

  # Use a custom read timeout
  if read_timeout || timeout
    @nhp.read_timeout = (read_timeout || timeout).to_i
  end

  @nhp.verify_mode = OpenSSL::SSL::VERIFY_PEER

  # Vault requires TLS1.2
  @nhp.ssl_version = "TLSv1_2"

  # Only use secure ciphers
  @nhp.ciphers = ssl_ciphers

  # Custom pem files, no problem!
  pem = ssl_pem_contents || (ssl_pem_file ? File.read(ssl_pem_file) : nil)
  if pem
    @nhp.cert = OpenSSL::X509::Certificate.new(pem)
    @nhp.key = OpenSSL::PKey::RSA.new(pem, ssl_pem_passphrase)
  end

  # Use custom CA cert for verification
  if ssl_ca_cert
    @nhp.ca_file = ssl_ca_cert
  end

  # Use custom CA path that contains CA certs
  if ssl_ca_path
    @nhp.ca_path = ssl_ca_path
  end

  if ssl_cert_store
    @nhp.cert_store = ssl_cert_store
  end

  # Naughty, naughty, naughty! Don't blame me when someone hops in
  # and executes a MITM attack!
  if !ssl_verify
    @nhp.verify_mode = OpenSSL::SSL::VERIFY_NONE
  end

  # Use custom timeout for connecting and verifying via SSL
  if ssl_timeout || timeout
    @nhp.ssl_timeout = (ssl_timeout || timeout).to_i
  end
end

Instance Method Details

#approle ⇒ AppRole

A proxy to the AppRole methods.

Returns:



12
13
14
 
# File 'lib/vault/api/approle.rb', line 12

def approle
  @approle ||= AppRole.new(self)
end

#auth ⇒ Auth

A proxy to the Auth methods.

Returns:



10
11
12
 
# File 'lib/vault/api/auth.rb', line 10

def auth
  @auth ||= Authenticate.new(self)
end

#auth_tls ⇒ AuthTLS

A proxy to the AuthTLS methods.

Returns:



12
13
14
 
# File 'lib/vault/api/auth_tls.rb', line 12

def auth_tls
  @auth_tls ||= AuthTLS.new(self)
end

#auth_token ⇒ AuthToken

A proxy to the AuthToken methods.

Returns:



12
13
14
 
# File 'lib/vault/api/auth_token.rb', line 12

def auth_token
  @auth_token ||= AuthToken.new(self)
end

#build_uri(verb, path, params = {}) ⇒ URI

Construct a URL from the given verb and path. If the request is a GET or DELETE request, the params are assumed to be query params are are converted as such using #to_query_string.

If the path is relative, it is merged with the Defaults.address attribute. If the path is absolute, it is converted to a URI object and returned.

Parameters:

  • verb (Symbol) —

    the lowercase HTTP verb (e.g. :get)

  • path (String) —

    the absolute or relative HTTP path (url) to get

  • params (Hash) (defaults to: {}) —

    the list of params to build the URI with (for GET and DELETE requests)

Returns:

  • (URI) 


292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
 
# File 'lib/vault/client.rb', line 292

def build_uri(verb, path, params = {})
  # Add any query string parameters
  if [:delete, :get].include?(verb)
    path = [path, to_query_string(params)].compact.join("?")
  end

  # Parse the URI
  uri = URI.parse(path)

  # Don't merge absolute URLs
  uri = URI.parse(File.join(address, path)) unless uri.absolute?

  # Return the URI object
  uri
end

#class_for_request(verb) ⇒ Class

Helper method to get the corresponding Net::HTTP class from the given HTTP verb.

Parameters:

  • verb (#to_s) —

    the HTTP verb to create a class from

Returns:

  • (Class) 


315
316
317
 
# File 'lib/vault/client.rb', line 315

def class_for_request(verb)
  Net::HTTP.const_get(verb.to_s.capitalize)
end

#delete(path, params = {}, headers = {}) ⇒ Object

Perform a DELETE request.

See Also:



195
196
197
 
# File 'lib/vault/client.rb', line 195

def delete(path, params = {}, headers = {})
  request(:delete, path, params, headers)
end

#error(response) ⇒ Object

Raise a response error, extracting as much information from the server’s response as possible.

Parameters:

  • response (HTTP::Message) —

    the response object from the request

Raises:



357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
 
# File 'lib/vault/client.rb', line 357

def error(response)
  if response.body && response.body.match("missing client token")
    raise MissingTokenError
  end

  # Use the correct exception class
  case response
  when Net::HTTPClientError
    klass = HTTPClientError
  when Net::HTTPServerError
    klass = HTTPServerError
  else
    klass = HTTPError
  end

  if (response.content_type || '').include?("json")
    # Attempt to parse the error as JSON
    begin
      json = JSON.parse(response.body, JSON_PARSE_OPTIONS)

      if json[:errors]
        raise klass.new(address, response, json[:errors])
      end
    rescue JSON::ParserError; end
  end

  raise klass.new(address, response, [response.body])
end

#get(path, params = {}, headers = {}) ⇒ Object

Perform a GET request.

See Also:



164
165
166
 
# File 'lib/vault/client.rb', line 164

def get(path, params = {}, headers = {})
  request(:get, path, params, headers)
end

#help(path) ⇒ Help

Gets help for the given path.

Examples:

Vault.help("secret") #=> #<Vault::Help help="..." see_also="...">

Parameters:

  • path (String) —

    the path to get help for

Returns:



28
29
30
31
 
# File 'lib/vault/api/help.rb', line 28

def help(path)
  json = self.get("/v1/#{EncodePath.encode_path(path)}", help: 1)
  return Help.decode(json)
end

#list(path, params = {}, headers = {}) ⇒ Object

Perform a LIST request.

See Also:



170
171
172
173
 
# File 'lib/vault/client.rb', line 170

def list(path, params = {}, headers = {})
  params = params.merge(list: true)
  request(:get, path, params, headers)
end

#logical ⇒ Logical

A proxy to the Logical methods.

Returns:



10
11
12
 
# File 'lib/vault/api/logical.rb', line 10

def logical
  @logical ||= Logical.new(self)
end

#patch(path, data, headers = {}) ⇒ Object

Perform a PATCH request.

See Also:



189
190
191
 
# File 'lib/vault/client.rb', line 189

def patch(path, data, headers = {})
  request(:patch, path, data, headers)
end

#post(path, data = {}, headers = {}) ⇒ Object

Perform a POST request.

See Also:



177
178
179
 
# File 'lib/vault/client.rb', line 177

def post(path, data = {}, headers = {})
  request(:post, path, data, headers)
end

#put(path, data, headers = {}) ⇒ Object

Perform a PUT request.

See Also:



183
184
185
 
# File 'lib/vault/client.rb', line 183

def put(path, data, headers = {})
  request(:put, path, data, headers)
end

#request(verb, path, data = {}, headers = {}) ⇒ String, Hash

Make an HTTP request with the given verb, data, params, and headers. If the response has a return type of JSON, the JSON is automatically parsed and returned as a hash; otherwise it is returned as a string.

Parameters:

  • verb (Symbol) —

    the lowercase symbol of the HTTP verb (e.g. :get, :delete)

  • path (String) —

    the absolute or relative path from Defaults.address to make the request against

  • data (#read, Hash, nil) (defaults to: {}) —

    the data to use (varies based on the verb)

  • headers (Hash) (defaults to: {}) —

    the list of headers to use

Returns:

  • (String, Hash) —

    the response body

Raises:

  • (HTTPError) —

    if the request is not an HTTP 200 OK



218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
 
# File 'lib/vault/client.rb', line 218

def request(verb, path, data = {}, headers = {})
  # Build the URI and request object from the given information
  uri = build_uri(verb, path, data)
  request = class_for_request(verb).new(uri.request_uri)

  if proxy_address and uri.scheme.downcase == "https"
    raise SecurityError, "no direct https connection to vault"
  end

  # Get a list of headers
  headers = DEFAULT_HEADERS.merge(headers)

  # Add the Vault token header - users could still override this on a
  # per-request basis
  if !token.nil?
    headers[TOKEN_HEADER] ||= token
  end

  # Add headers
  headers.each do |key, value|
    request.add_field(key, value)
  end

  # Setup PATCH/POST/PUT
  if [:patch, :post, :put].include?(verb)
    if data.respond_to?(:read)
      request.content_length = data.size
      request.body_stream = data
    elsif data.is_a?(Hash)
      request.form_data = data
    else
      request.body = data
    end
  end

  begin
    # Create a connection using the block form, which will ensure the socket
    # is properly closed in the event of an error.
    response = @nhp.request(uri, request)

    case response
    when Net::HTTPRedirection
      # On a redirect of a GET or HEAD request, the URL already contains
      # the data as query string parameters.
      if [:head, :get].include?(verb)
        data = {}
      end
      request(verb, response[LOCATION_HEADER], data, headers)
    when Net::HTTPSuccess
      success(response)
    else
      error(response)
    end
  rescue *RESCUED_EXCEPTIONS => e
    raise HTTPConnectionError.new(address, e)
  end
end

#same_options?(opts) ⇒ true, false

Determine if the given options are the same as ours.

Returns:

  • (true, false) 


158
159
160
 
# File 'lib/vault/client.rb', line 158

def same_options?(opts)
  options.hash == opts.hash
end

#success(response) ⇒ String, Hash

Parse the response object and manipulate the result based on the given Content-Type header. For now, this method only parses JSON, but it could be expanded in the future to accept other content types.

Parameters:

  • response (HTTP::Message) —

    the response object from the request

Returns:

  • (String, Hash) —

    the parsed response, as an object



342
343
344
345
346
347
348
 
# File 'lib/vault/client.rb', line 342

def success(response)
  if response.body && (response.content_type || '').include?("json")
    JSON.parse(response.body, JSON_PARSE_OPTIONS)
  else
    response.body
  end
end

#sys ⇒ Sys

A proxy to the Sys methods.

Returns:



9
10
11
 
# File 'lib/vault/api/sys.rb', line 9

def sys
  @sys ||= Sys.new(self)
end

#to_query_string(hash) ⇒ String?

Convert the given hash to a list of query string parameters. Each key and value in the hash is URI-escaped for safety.

Parameters:

  • hash (Hash) —

    the hash to create the query string from

Returns:

  • (String, nil) —

    the query string as a string, or nil if there are no params



327
328
329
330
331
 
# File 'lib/vault/client.rb', line 327

def to_query_string(hash)
  hash.map do |key, value|
    "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}"
  end.join('&')[/.+/]
end

#with_retries(*rescued, &block) ⇒ Object

Execute the given block with retries and exponential backoff.

Parameters:

  • rescued (Array<Exception>) —

    the list of exceptions to rescue



390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
 
# File 'lib/vault/client.rb', line 390

def with_retries(*rescued, &block)
  options      = rescued.last.is_a?(Hash) ? rescued.pop : {}
  exception    = nil
  retries      = 0

  max_attempts = options[:attempts] || Defaults::RETRY_ATTEMPTS
  backoff_base = options[:base]     || Defaults::RETRY_BASE
  backoff_max  = options[:max_wait] || Defaults::RETRY_MAX_WAIT

  begin
    return yield retries, exception
  rescue *rescued => e
    exception = e

    retries += 1
    raise if retries > max_attempts

    # Calculate the exponential backoff combined with an element of
    # randomness.
    backoff = [backoff_base * (2 ** (retries - 1)), backoff_max].min
    backoff = backoff * (0.5 * (1 + Kernel.rand))

    # Ensure we are sleeping at least the minimum interval.
    backoff = [backoff_base, backoff].max

    # Exponential backoff.
    Kernel.sleep(backoff)

    # Now retry
    retry
  end
end

#with_token(token) {|Vault::Client| ... } ⇒ Object

Creates and yields a new client object with the given token. This may be used safely in a threadsafe manner because the original client remains unchanged. The value of the block is returned.

Yields:



149
150
151
152
153
154
 
# File 'lib/vault/client.rb', line 149

def with_token(token)
  client = self.dup
  client.token = token
  return yield client if block_given?
  return nil
end