HTTPClient::SSLConfig

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 set_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 set_trust_ca for that purpose.

Attributes

client_cert[R]

OpenSSL::X509::Certificate

certificate for SSL client authenticateion.

nil by default. (no client authenticateion)

client_key[R]

OpenSSL::PKey::PKey

private key for SSL client authentication.

nil by default. (no client authenticateion)

verify_mode[R]

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

verify_depth[R]

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

verify_callback[R]

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.

timeout[R]

SSL timeout in sec. nil by default.

options[R]

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

ciphers[R]

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.

cert_store[R]

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

Public Class Methods

new(client) click to toggle source

Creates a SSLConfig.

    # File lib/httpclient/ssl_config.rb, line 73
73:     def initialize(client)
74:       return unless SSLEnabled
75:       @client = client
76:       @cert_store = X509::Store.new
77:       @client_cert = @client_key = @client_ca = nil
78:       @verify_mode = SSL::VERIFY_PEER | SSL::VERIFY_FAIL_IF_NO_PEER_CERT
79:       @verify_depth = nil
80:       @verify_callback = nil
81:       @dest = nil
82:       @timeout = nil
83:       @options = defined?(SSL::OP_ALL) ? SSL::OP_ALL | SSL::OP_NO_SSLv2 : nil
84:       @ciphers = "ALL:!ADH:!LOW:!EXP:!MD5:+SSLv2:@STRENGTH"
85:       load_cacerts
86:     end

Public Instance Methods

cert_store=(cert_store) click to toggle source

Sets new certificate store (OpenSSL::X509::Store). don’t use if you don’t know what it is.

Calling this method resets all existing sessions.

     # File lib/httpclient/ssl_config.rb, line 133
133:     def cert_store=(cert_store)
134:       @cert_store = cert_store
135:       change_notify
136:     end

ciphers=(ciphers) click to toggle source

Sets cipher configuration. New value must be a String.

Calling this method resets all existing sessions.

     # File lib/httpclient/ssl_config.rb, line 214
214:     def ciphers=(ciphers)
215:       @ciphers = ciphers
216:       change_notify
217:     end

clear_cert_store() click to toggle source

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

Calling this method resets all existing sessions.

     # File lib/httpclient/ssl_config.rb, line 124
124:     def clear_cert_store
125:       @cert_store = X509::Store.new
126:       change_notify
127:     end

client_cert=(client_cert) click to toggle source

Sets certificate (OpenSSL::X509::Certificate) for SSL client authentication. client_key and client_cert must be a pair.

Calling this method resets all existing sessions.

    # File lib/httpclient/ssl_config.rb, line 93
93:     def client_cert=(client_cert)
94:       @client_cert = client_cert
95:       change_notify
96:     end

client_key=(client_key) click to toggle source

Sets private key (OpenSSL::PKey::PKey) for SSL client authentication. client_key and client_cert must be a pair.

Calling this method resets all existing sessions.

     # File lib/httpclient/ssl_config.rb, line 102
102:     def client_key=(client_key)
103:       @client_key = client_key
104:       change_notify
105:     end

default_verify_callback(is_ok, ctx) click to toggle source

Default callback for verification: only dumps error.

     # File lib/httpclient/ssl_config.rb, line 270
270:     def default_verify_callback(is_ok, ctx)
271:       if $DEBUG
272:         puts "#{ is_ok ? 'ok' : 'ng' }: #{ctx.current_cert.subject}"
273:       end
274:       if !is_ok
275:         depth = ctx.error_depth
276:         code = ctx.error
277:         msg = ctx.error_string
278:         STDERR.puts "at depth #{depth} - #{code}: #{msg}"
279:       end
280:       is_ok
281:     end

options=(options) click to toggle source

Sets SSL options. New value must be a combination of # constants OpenSSL::SSL::OP_*

Calling this method resets all existing sessions.

     # File lib/httpclient/ssl_config.rb, line 206
206:     def options=(options)
207:       @options = options
208:       change_notify
209:     end

sample_verify_callback(is_ok, ctx) click to toggle source

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

     # File lib/httpclient/ssl_config.rb, line 284
284:     def sample_verify_callback(is_ok, ctx)
285:       unless is_ok
286:         depth = ctx.error_depth
287:         code = ctx.error
288:         msg = ctx.error_string
289:         STDERR.puts "at depth #{depth} - #{code}: #{msg}" if $DEBUG
290:         return false
291:       end
292: 
293:       cert = ctx.current_cert
294:       self_signed = false
295:       ca = false
296:       pathlen = nil
297:       server_auth = true
298:       self_signed = (cert.subject.cmp(cert.issuer) == 0)
299: 
300:       # Check extensions whatever its criticality is. (sample)
301:       cert.extensions.each do |ex|
302:         case ex.oid
303:         when 'basicConstraints'
304:           /CA:(TRUE|FALSE), pathlen:(\d+)/ =~ ex.value
305:           ca = ($1 == 'TRUE')
306:           pathlen = $2.to_i
307:         when 'keyUsage'
308:           usage = ex.value.split(/\s*,\s*/)
309:           ca = usage.include?('Certificate Sign')
310:           server_auth = usage.include?('Key Encipherment')
311:         when 'extendedKeyUsage'
312:           usage = ex.value.split(/\s*,\s*/)
313:           server_auth = usage.include?('Netscape Server Gated Crypto')
314:         when 'nsCertType'
315:           usage = ex.value.split(/\s*,\s*/)
316:           ca = usage.include?('SSL CA')
317:           server_auth = usage.include?('SSL Server')
318:         end
319:       end
320: 
321:       if self_signed
322:         STDERR.puts 'self signing CA' if $DEBUG
323:         return true
324:       elsif ca
325:         STDERR.puts 'middle level CA' if $DEBUG
326:         return true
327:       elsif server_auth
328:         STDERR.puts 'for server authentication' if $DEBUG
329:         return true
330:       end
331: 
332:       return false
333:     end

set_client_cert_file(cert_file, key_file) click to toggle source

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.

     # File lib/httpclient/ssl_config.rb, line 114
114:     def set_client_cert_file(cert_file, key_file)
115:       @client_cert = X509::Certificate.new(File.open(cert_file).read)
116:       @client_key = PKey::RSA.new(File.open(key_file).read)
117:       change_notify
118:     end

set_crl(crl) click to toggle source

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.

     # File lib/httpclient/ssl_config.rb, line 159
159:     def set_crl(crl)
160:       unless crl.is_a?(X509::CRL)
161:         crl = X509::CRL.new(File.open(crl).read)
162:       end
163:       @cert_store.add_crl(crl)
164:       @cert_store.flags = X509::V_FLAG_CRL_CHECK | X509::V_FLAG_CRL_CHECK_ALL
165:       change_notify
166:     end

set_trust_ca(trust_ca_file_or_hashed_dir) click to toggle source

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.

     # File lib/httpclient/ssl_config.rb, line 145
145:     def set_trust_ca(trust_ca_file_or_hashed_dir)
146:       if FileTest.directory?(trust_ca_file_or_hashed_dir)
147:         @cert_store.add_path(trust_ca_file_or_hashed_dir)
148:       else
149:         @cert_store.add_file(trust_ca_file_or_hashed_dir)
150:       end
151:       change_notify
152:     end

timeout=(timeout) click to toggle source

Sets SSL timeout in sec.

Calling this method resets all existing sessions.

     # File lib/httpclient/ssl_config.rb, line 197
197:     def timeout=(timeout)
198:       @timeout = timeout
199:       change_notify
200:     end

verify_callback=(verify_callback) click to toggle source

Sets callback handler for custom certificate verification. See verify_callback.

Calling this method resets all existing sessions.

     # File lib/httpclient/ssl_config.rb, line 189
189:     def verify_callback=(verify_callback)
190:       @verify_callback = verify_callback
191:       change_notify
192:     end

verify_depth=(verify_depth) click to toggle source

Sets verify depth. New value must be a number.

Calling this method resets all existing sessions.

     # File lib/httpclient/ssl_config.rb, line 180
180:     def verify_depth=(verify_depth)
181:       @verify_depth = verify_depth
182:       change_notify
183:     end

verify_mode=(verify_mode) click to toggle source

Sets verify mode of OpenSSL. New value must be a combination of constants OpenSSL::SSL::VERIFY_*

Calling this method resets all existing sessions.

     # File lib/httpclient/ssl_config.rb, line 172
172:     def verify_mode=(verify_mode)
173:       @verify_mode = verify_mode
174:       change_notify
175:     end

Private Instance Methods

change_notify() click to toggle source

     # File lib/httpclient/ssl_config.rb, line 337
337:     def change_notify
338:       @client.reset_all
339:     end

load_cacerts() click to toggle source

     # File lib/httpclient/ssl_config.rb, line 341
341:     def load_cacerts
342:       [
343:         [DIST_CERT, 'cacert.p7s'],
344:         [DIST_CERT_SHA1, 'cacert_sha1.p7s']
345:       ].each do |cert_str, ca_file|
346:         file = File.join(File.dirname(__FILE__), ca_file)
347:         if File.exist?(file)
348:           p7 = PKCS7.read_smime(File.open(file) { |f| f.read })
349:           selfcert = X509::Certificate.new(cert_str)
350:           store = X509::Store.new
351:           store.add_cert(selfcert)
352:           if (p7.verify(nil, store, p7.data, 0))
353:             set_trust_ca(file)
354:             return
355:           end
356:         end
357:       end
358:       STDERR.puts("cacerts loading failed")
359:     end

Home Classes Methods

In Files

Parent

Methods

Included Modules

Files

Class Index

HTTPClient::SSLConfig

Trust Anchor Control

Constants

Attributes

Public Class Methods

Public Instance Methods

Private Instance Methods