123456789_123456789_123456789_123456789_123456789_

Class: OpenSSL::SSL::SSLContext

Relationships & Source Files
Inherits: Object
Defined in: ext/openssl/ossl_ssl.c,
ext/openssl/lib/openssl/ssl.rb

Overview

An SSLContext is used to set various options regarding certificates, algorithms, verification, session caching, etc. The SSLContext is used to create an SSLSocket.

All attributes must be set before creating an SSLSocket as the SSLContext will be frozen afterward.

The following attributes are available but don't show up in rdoc:

  • ssl_version, cert, key, client_ca, ca_file, ca_path, timeout,

  • verify_mode, verify_depth client_cert_cb, tmp_dh_callback,

  • session_id_context, session_add_cb, session_new_cb, session_remove_cb

Constant Summary

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new ⇒ ctx .new(:TLSv1) ⇒ ctx .new("SSLv23_client") ⇒ ctx

You can get a list of valid methods with METHODS

[ GitHub ] 

  


# File 'ext/openssl/lib/openssl/ssl.rb', line 108



def initialize(version = nil)
  INIT_VARS.each { |v| instance_variable_set v, nil }
  self.options = self.options | OpenSSL::SSL::OP_ALL
  return unless version
  self.ssl_version = version
end


  







Instance Attribute Details



  

    #alpn_protocols   (rw)
  



  

    

An Enumerable of Strings. Each String represents a protocol to be advertised as the list of supported protocols for Application-Layer Protocol Negotiation. Supported in ::OpenSSL 1.0.1 and higher. Has no effect on the client side. If not set explicitly, the NPN extension will not be sent by the server in the handshake.



Example



ctx.alpn_protocols = ["http/1.1", "spdy/2", "h2"]


  









  

    #alpn_select_cb   (rw)
  



  

    

A callback invoked on the server side when the server needs to select a protocol from the list sent by the client. Supported in ::OpenSSL 1.0.2 and higher. The server MUST select a protocol of those advertised by the client. If none is acceptable, raising an error in the callback will cause the handshake to fail. Not setting this callback explicitly means not supporting the ALPN extension on the client - any protocols advertised by the server will be ignored.



Example



ctx.alpn_select_cb = lambda do |protocols|
  #inspect the protocols and select one
  protocols.first
end


  









  

    #ca_file   (rw)
  



  

    

The path to a file containing a PEM-format CA certificate


  









  

    #ca_path   (rw)
  



  

    

The path to a directory containing CA certificates in PEM format.



Files are looked up by subject's ::OpenSSL::X509 name's hash value.


  









  

    #cert   (rw)
  



  

    

Context certificate


  









  

    #cert_store   (rw)
  



  

    

An ::OpenSSL::X509::Store used for certificate verification


  









  

    #ciphers  ⇒ Array, ...  (rw)  



  

    

The list of ciphers configured for this context.


  









  

    

      #ciphers=("cipher1:cipher2:...")   (rw)
      #ciphers=([name, ...])  
      #ciphers=([[name, version, bits, alg_bits], ...])  
    

  



  

    

Sets the list of available ciphers for this context.  Note in a server context some ciphers require the appropriate certificates.  For example, an RSA cipher can only be chosen when an RSA certificate is available.



See also ::OpenSSL::Cipher and Cipher.ciphers


  





  








  

    #client_ca   (rw)
  



  

    

A certificate or Array of certificates that will be sent to the client.


  









  

    #client_cert_cb   (rw)
  



  

    

A callback invoked when a client certificate is requested by a server and no certificate has been set.



The callback is invoked with a Session and must return an Array containing an ::OpenSSL::X509::Certificate and an ::OpenSSL::PKey.  If any other value is returned the handshake is suspended.


  









  

    #extra_chain_cert   (rw)
  



  

    

An Array of extra ::OpenSSL::X509 certificates to be added to the certificate chain.


  









  

    #key   (rw)
  



  

    

Context private key


  









  

    #npn_protocols   (rw)
  



  

    

An Enumerable of Strings. Each String represents a protocol to be advertised as the list of supported protocols for Next Protocol Negotiation. Supported in ::OpenSSL 1.0.1 and higher. Has no effect on the client side. If not set explicitly, the NPN extension will not be sent by the server in the handshake.



Example



ctx.npn_protocols = ["http/1.1", "spdy/2"]


  









  

    #npn_select_cb   (rw)
  



  

    

A callback invoked on the client side when the client needs to select a protocol from the list sent by the server. Supported in ::OpenSSL 1.0.1 and higher. The client MUST select a protocol of those advertised by the server. If none is acceptable, raising an error in the callback will cause the handshake to fail. Not setting this callback explicitly means not supporting the NPN extension on the client - any protocols advertised by the server will be ignored.



Example



ctx.npn_select_cb = lambda do |protocols|
  #inspect the protocols and select one
  protocols.first
end


  









  

    #options   (rw)
  



  

    

Gets various ::OpenSSL options.


  









  

    #options=(options)   (rw)
  



  

    

Sets various ::OpenSSL options.


  









  

    #renegotiation_cb   (rw)
  



  

    

A callback invoked whenever a new handshake is initiated. May be used to disable renegotiation entirely.



The callback is invoked with the active SSLSocket. The callback's return value is irrelevant, normal return indicates “approval” of the renegotiation and will continue the process. To forbid renegotiation and to cancel the process, an Error may be raised within the callback.



Disable client renegotiation



When running a server, it is often desirable to disable client renegotiation entirely. You may use a callback as follows to implement this feature:



num_handshakes = 0
ctx.renegotiation_cb = lambda do |ssl|
  num_handshakes += 1
  raise RuntimeError.new("Client renegotiation disabled") if num_handshakes > 1
end


  









  

    #servername_cb   (rw)
  



  

    

A callback invoked at connect time to distinguish between multiple server names.



The callback is invoked with an SSLSocket and a server name.  The callback must return an SSLContext for the server name or nil.


  



  [ GitHub ]


  

  


# File 'ext/openssl/lib/openssl/ssl.rb', line 99



attr_accessor :servername_cb


  








  

    #session_cache_mode  ⇒ Integer  (rw)  



  

    

The current session cache mode.


  









  

    #session_cache_mode=(integer)  ⇒ Integer  (rw)  



  

    

Sets the ::OpenSSL::SSL session cache mode.  Bitwise-or together the desired SESSION_CACHE_* constants to set.  See SSL_CTX_set_session_cache_mode(3) for details.


  









  

    #session_cache_size  ⇒ Integer  (rw)  



  

    

Returns the current session cache size.  Zero is used to represent an unlimited cache size.


  









  

    #session_cache_size=(integer)  ⇒ Integer  (rw)  



  

    

Sets the session cache size.  Returns the previously valid session cache size.  Zero is used to represent an unlimited session cache size.


  









  

    #session_get_cb   (rw)
  



  

    

A callback invoked on a server when a session is proposed by the client but the session could not be found in the server's internal cache.



The callback is invoked with the SSLSocket and session id.  The callback may return a Session from an external cache.


  









  

    #session_id_context   (rw)
  



  

    

Sets the context in which a session can be reused.  This allows sessions for multiple applications to be distinguished, for example, by name.


  









  

    #session_new_cb   (rw)
  



  

    

A callback invoked when a new session was negotiated.



The callback is invoked with an SSLSocket.  If false is returned the session will be removed from the internal cache.


  









  

    #session_remove_cb   (rw)
  



  

    

A callback invoked when a session is removed from the internal cache.



The callback is invoked with an SSLContext and a Session.


  









  

    #ssl_timeout   (rw)
  



  

    

Alias for #timeout.


  









  

    

      #ssl_version=(:TLSv1)   (writeonly)
      #ssl_version=("SSLv23_client")  
    

  



  

    

You can get a list of valid versions with METHODS


  





  








  

    #timeout   (rw)
    Also known as: #ssl_timeout
  



  

    

Maximum session lifetime.


  









  

    #tmp_dh_callback   (rw)
  



  

    

A callback invoked when DH parameters are required.



The callback is invoked with the Session for the key exchange, an flag indicating the use of an export cipher and the keylength required.



The callback must return an ::OpenSSL::PKey::DH instance of the correct key length.


  



  [ GitHub ]


  

  


# File 'ext/openssl/lib/openssl/ssl.rb', line 91



attr_accessor :tmp_dh_callback


  








  

    #tmp_ecdh_callback   (rw)
  



  

    

A callback invoked when ECDH parameters are required.



The callback is invoked with the Session for the key exchange, an flag indicating the use of an export cipher and the keylength required.



The callback must return an ::OpenSSL::PKey::EC instance of the correct key length.


  









  

    #verify_callback   (rw)
  



  

    

A callback for additional certificate verification.  The callback is invoked for each certificate in the chain.



The callback is invoked with two values.  preverify_ok indicates indicates if the verification was passed (true) or not (false). store_context is an ::OpenSSL::X509::StoreContext containing the context used for certificate verification.



If the callback returns false verification is stopped.


  









  

    #verify_depth   (rw)
  



  

    

Number of CA certificates to walk when verifying a certificate chain.


  









  

    #verify_mode   (rw)
  



  

    

Session verification mode.



Valid modes are VERIFY_NONE, VERIFY_PEER, VERIFY_CLIENT_ONCE, VERIFY_FAIL_IF_NO_PEER_CERT and defined on ::OpenSSL::SSL


  








Instance Method Details



  

    #flush_sessions(time | nil)  ⇒ self   



  

    

Removes sessions in the internal cache that have expired at time.


  









  

    #session_add(session)  ⇒ Boolean   



  

    

Adds session to the session cache


  









  

    #session_cache_stats  ⇒ Hash   



  

    

Returns a Hash containing the following keys:


:accept



Number of started SSL/TLS handshakes in server mode


:accept_good



Number of established SSL/TLS sessions in server mode


:accept_renegotiate



Number of start renegotiations in server mode


:cache_full



Number of sessions that were removed due to cache overflow


:cache_hits



Number of successfully reused connections


:cache_misses



Number of sessions proposed by clients that were not found in the cache


:cache_num



Number of sessions in the internal session cache


:cb_hits



Number of sessions retrieved from the external cache in server mode


:connect



Number of started SSL/TLS handshakes in client mode


:connect_good



Number of established SSL/TLS sessions in client mode


:connect_renegotiate



Number of start renegotiations in client mode


:timeouts



Number of sessions proposed by clients that were found in the cache but had expired due to timeouts




  









  

    #session_remove(session)  ⇒ Boolean   



  

    

Removes session from the session cache


  









  

    #set_params(params = {})  
  



  

    

Sets the parameters for this ::OpenSSL::SSL context to the values in params. The keys in params must be assignment methods on SSLContext.



If the verify_mode is not VERIFY_NONE and ca_file, ca_path and cert_store are not set then the system default certificate store is used.


  



  [ GitHub ]


  

  


# File 'ext/openssl/lib/openssl/ssl.rb', line 123



def set_params(params={})
  params = DEFAULT_PARAMS.merge(params)
  params.each{|name, value| self.__send__("#{name}=", value) }
  if self.verify_mode != OpenSSL::SSL::VERIFY_NONE
    unless self.ca_file or self.ca_path or self.cert_store
      self.cert_store = DEFAULT_CERT_STORE
    end
  end
  return params
end


  








  

    

      #setup  ⇒ Qtrue #firstt time 
      #setup  ⇒ nil #thereafterr 
    

  



  

    

This method is called automatically when a new SSLSocket is created. However, it is not thread-safe and must be called before creating SSLSocket objects in a multi-threaded program.