Class: HTTPClient::SSLConfig

Inherits:
Object
  • Object
show all
Includes:
OpenSSL
Defined in:
lib/httpclient/ssl_config.rb

Overview

Represents SSL configuration for HTTPClient instance. The implementation depends on OpenSSL.

Trust Anchor Control

SSLConfig loads ‘httpclient/cacert.p7s’ as a trust anchor (trusted certificate(s)) with add_trust_ca in initialization time. This means that HTTPClient instance trusts some CA certificates by default, like Web browsers. ‘httpclient/cacert.p7s’ is created by the author and included in released package.

‘cacert.p7s’ is automatically generated from JDK 1.6.

You may want to change trust anchor by yourself. Call clear_cert_store then add_trust_ca for that purpose.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client) ⇒ SSLConfig

Creates a SSLConfig.



73
74
75
76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/httpclient/ssl_config.rb', line 73

def initialize(client)
  return unless SSLEnabled
  @client = client
  @cert_store = X509::Store.new
  @client_cert = @client_key = @client_ca = nil
  @verify_mode = SSL::VERIFY_PEER | SSL::VERIFY_FAIL_IF_NO_PEER_CERT
  @verify_depth = nil
  @verify_callback = nil
  @dest = nil
  @timeout = nil
  @options = defined?(SSL::OP_ALL) ? SSL::OP_ALL | SSL::OP_NO_SSLv2 : nil
  @ciphers = "ALL:!ADH:!LOW:!EXP:!MD5:+SSLv2:@STRENGTH"
  @cacerts_loaded = false
end

Instance Attribute Details

#cert_store ⇒ Object

OpenSSL::X509::X509::Store used for verification. You can reset the store with clear_cert_store and set the new store with cert_store=.



67
68
69
 
# File 'lib/httpclient/ssl_config.rb', line 67

def cert_store
  @cert_store
end

#ciphers ⇒ Object

A String of OpenSSL’s cipher configuration. Default value is ALL:!ADH:!LOW:!EXP:!MD5:+SSLv2:@STRENGTH See ciphers(1) man in OpenSSL for more detail.



63
64
65
 
# File 'lib/httpclient/ssl_config.rb', line 63

def ciphers
  @ciphers
end

#client_ca ⇒ Object

For server side configuration. Ignore this.



70
71
72
 
# File 'lib/httpclient/ssl_config.rb', line 70

def client_ca
  @client_ca
end

#client_cert ⇒ Object

OpenSSL::X509::Certificate

certificate for SSL client authenticateion.

nil by default. (no client authenticateion)



38
39
40
 
# File 'lib/httpclient/ssl_config.rb', line 38

def client_cert
  @client_cert
end

#client_key ⇒ Object

OpenSSL::PKey::PKey

private key for SSL client authentication.

nil by default. (no client authenticateion)



41
42
43
 
# File 'lib/httpclient/ssl_config.rb', line 41

def client_key
  @client_key
end

#options ⇒ Object

A number of OpenSSL’s SSL options. Default value is OpenSSL::SSL::OP_ALL | OpenSSL::SSL::OP_NO_SSLv2



59
60
61
 
# File 'lib/httpclient/ssl_config.rb', line 59

def options
  @options
end

#timeout ⇒ Object

SSL timeout in sec. nil by default.



56
57
58
 
# File 'lib/httpclient/ssl_config.rb', line 56

def timeout
  @timeout
end

#verify_callback ⇒ Object

A callback handler for custom certificate verification. nil by default. If the handler is set, handler.call is invoked just after general OpenSSL’s verification. handler.call is invoked with 2 arguments, ok and ctx; ok is a result of general OpenSSL’s verification. ctx is a OpenSSL::X509::StoreContext.



54
55
56
 
# File 'lib/httpclient/ssl_config.rb', line 54

def verify_callback
  @verify_callback
end

#verify_depth ⇒ Object

A number of verify depth. Certification path which length is longer than this depth is not allowed.



48
49
50
 
# File 'lib/httpclient/ssl_config.rb', line 48

def verify_depth
  @verify_depth
end

#verify_mode ⇒ Object

A number which represents OpenSSL’s verify mode. Default value is OpenSSL::SSL::VERIFY_PEER | OpenSSL::SSL::VERIFY_FAIL_IF_NO_PEER_CERT.



45
46
47
 
# File 'lib/httpclient/ssl_config.rb', line 45

def verify_mode
  @verify_mode
end

Instance Method Details

#add_crl(crl) ⇒ Object Also known as: set_crl

Adds CRL for verification.

crl

a OpenSSL::X509::CRL or a filename of a PEM/DER formatted OpenSSL::X509::CRL.

Calling this method resets all existing sessions.



170
171
172
173
174
175
176
177
 
# File 'lib/httpclient/ssl_config.rb', line 170

def add_crl(crl)
  unless crl.is_a?(X509::CRL)
    crl = X509::CRL.new(File.open(crl) { |f| f.read })
  end
  @cert_store.add_crl(crl)
  @cert_store.flags = X509::V_FLAG_CRL_CHECK | X509::V_FLAG_CRL_CHECK_ALL
  change_notify
end

#add_trust_ca(trust_ca_file_or_hashed_dir) ⇒ Object Also known as: set_trust_ca

Sets trust anchor certificate(s) for verification.

trust_ca_file_or_hashed_dir

a filename of a PEM/DER formatted OpenSSL::X509::Certificate or a ‘c-rehash’eddirectory name which stores trusted certificate files.

Calling this method resets all existing sessions.



147
148
149
150
151
152
153
154
155
 
# File 'lib/httpclient/ssl_config.rb', line 147

def add_trust_ca(trust_ca_file_or_hashed_dir)
  @cacerts_loaded = true # avoid lazy override
  if FileTest.directory?(trust_ca_file_or_hashed_dir)
    @cert_store.add_path(trust_ca_file_or_hashed_dir)
  else
    @cert_store.add_file(trust_ca_file_or_hashed_dir)
  end
  change_notify
end

#clear_cert_store ⇒ Object

Drops current certificate store (OpenSSL::X509::Store) for SSL and create new one for the next session.

Calling this method resets all existing sessions.



124
125
126
127
128
 
# File 'lib/httpclient/ssl_config.rb', line 124

def clear_cert_store
  @cacerts_loaded = true # avoid lazy override
  @cert_store = X509::Store.new
  change_notify
end

#default_verify_callback(is_ok, ctx) ⇒ Object

Default callback for verification: only dumps error.



284
285
286
287
288
289
290
291
292
293
294
295
 
# File 'lib/httpclient/ssl_config.rb', line 284

def default_verify_callback(is_ok, ctx)
  if $DEBUG
    puts "#{ is_ok ? 'ok' : 'ng' }: #{ctx.current_cert.subject}"
  end
  if !is_ok
    depth = ctx.error_depth
    code = ctx.error
    msg = ctx.error_string
    STDERR.puts "at depth #{depth} - #{code}: #{msg}"
  end
  is_ok
end

#load_trust_ca ⇒ Object

Loads default trust anchors. Calling this method resets all existing sessions.



160
161
162
163
 
# File 'lib/httpclient/ssl_config.rb', line 160

def load_trust_ca
  load_cacerts
  change_notify
end

#post_connection_check(peer_cert, hostname) ⇒ Object

post connection check proc for ruby < 1.8.5. this definition must match with the one in ext/openssl/lib/openssl/ssl.rb

Raises:

  • (SSL::SSLError) 


256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
 
# File 'lib/httpclient/ssl_config.rb', line 256

def post_connection_check(peer_cert, hostname) # :nodoc:
  check_common_name = true
  cert = peer_cert
  cert.extensions.each{|ext|
    next if ext.oid != "subjectAltName"
    ext.value.split(/,\s+/).each{|general_name|
      if /\ADNS:(.*)/ =~ general_name
        check_common_name = false
        reg = Regexp.escape($1).gsub(/\\\*/, "[^.]+")
        return true if /\A#{reg}\z/i =~ hostname
      elsif /\AIP Address:(.*)/ =~ general_name
        check_common_name = false
        return true if $1 == hostname
      end
    }
  }
  if check_common_name
    cert.subject.to_a.each{|oid, value|
      if oid == "CN"
        reg = Regexp.escape(value).gsub(/\\\*/, "[^.]+")
        return true if /\A#{reg}\z/i =~ hostname
      end
    }
  end
  raise SSL::SSLError, "hostname was not match with the server certificate"
end

#sample_verify_callback(is_ok, ctx) ⇒ Object

Sample callback method: CAUTION: does not check CRL/ARL.



298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
 
# File 'lib/httpclient/ssl_config.rb', line 298

def sample_verify_callback(is_ok, ctx)
  unless is_ok
    depth = ctx.error_depth
    code = ctx.error
    msg = ctx.error_string
    STDERR.puts "at depth #{depth} - #{code}: #{msg}" if $DEBUG
    return false
  end

  cert = ctx.current_cert
  self_signed = false
  ca = false
  pathlen = nil
  server_auth = true
  self_signed = (cert.subject.cmp(cert.issuer) == 0)

  # Check extensions whatever its criticality is. (sample)
  cert.extensions.each do |ex|
    case ex.oid
    when 'basicConstraints'
      /CA:(TRUE|FALSE), pathlen:(\d+)/ =~ ex.value
      ca = ($1 == 'TRUE')
      pathlen = $2.to_i
    when 'keyUsage'
      usage = ex.value.split(/\s*,\s*/)
      ca = usage.include?('Certificate Sign')
      server_auth = usage.include?('Key Encipherment')
    when 'extendedKeyUsage'
      usage = ex.value.split(/\s*,\s*/)
      server_auth = usage.include?('Netscape Server Gated Crypto')
    when 'nsCertType'
      usage = ex.value.split(/\s*,\s*/)
      ca = usage.include?('SSL CA')
      server_auth = usage.include?('SSL Server')
    end
  end

  if self_signed
    STDERR.puts 'self signing CA' if $DEBUG
    return true
  elsif ca
    STDERR.puts 'middle level CA' if $DEBUG
    return true
  elsif server_auth
    STDERR.puts 'for server authentication' if $DEBUG
    return true
  end

  return false
end

#set_client_cert_file(cert_file, key_file) ⇒ Object

Sets certificate and private key for SSL client authentication.

cert_file

must be a filename of PEM/DER formatted file.

key_file

must be a filename of PEM/DER formatted file. Key must be an RSA key. If you want to use other PKey algorithm, use client_key=.

Calling this method resets all existing sessions.



114
115
116
117
118
 
# File 'lib/httpclient/ssl_config.rb', line 114

def set_client_cert_file(cert_file, key_file)
  @client_cert = X509::Certificate.new(File.open(cert_file) { |f| f.read })
  @client_key = PKey::RSA.new(File.open(key_file) { |f| f.read })
  change_notify
end

#set_context(ctx) ⇒ Object

interfaces for SSLSocketWrap.



237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
 
# File 'lib/httpclient/ssl_config.rb', line 237

def set_context(ctx) # :nodoc:
  load_trust_ca unless @cacerts_loaded
  @cacerts_loaded = true
  # Verification: Use Store#verify_callback instead of SSLContext#verify*?
  ctx.cert_store = @cert_store
  ctx.verify_mode = @verify_mode
  ctx.verify_depth = @verify_depth if @verify_depth
  ctx.verify_callback = @verify_callback || method(:default_verify_callback)
  # SSL config
  ctx.cert = @client_cert
  ctx.key = @client_key
  ctx.client_ca = @client_ca
  ctx.timeout = @timeout
  ctx.options = @options
  ctx.ciphers = @ciphers
end