Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

SSL_Context.h

Go to the documentation of this file.
00001 // -*- C++ -*-
00002 
00003 //=============================================================================
00004 /**
00005  *  @file    SSL_Context.h
00006  *
00007  *  $Id: SSL_Context.h,v 1.1.1.2 2003/02/21 18:36:32 chad Exp $
00008  *
00009  *  @author Carlos O'Ryan <coryan@ece.uci.edu>
00010  */
00011 //=============================================================================
00012 
00013 
00014 #ifndef ACE_SSL_CONTEXT_H
00015 #define ACE_SSL_CONTEXT_H
00016 
00017 #include "ace/pre.h"
00018 
00019 #include "SSL_Export.h"
00020 
00021 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00022 # pragma once
00023 #endif /* ACE_LACKS_PRAGMA_ONCE */
00024 
00025 #include "ace/SString.h"
00026 #include "ace/Singleton.h"
00027 #include "ace/Synch.h"
00028 
00029 #include <openssl/ssl.h>
00030 
00031 #ifdef ACE_HAS_THREADS
00032 extern "C"
00033 {
00034 
00035   /// Mutex locking/unlocking callback for OpenSSL multithread
00036   /// support.
00037   void ACE_SSL_locking_callback (int mode,
00038                                  int type,
00039                                  const char * file,
00040                                  int line);
00041 
00042   /// Return the current thread ID.  OpenSSL uses this on platforms
00043   /// that need it.
00044   unsigned long ACE_SSL_thread_id (void);
00045 }
00046 #endif  /* ACE_HAS_THREADS */
00047 
00048 
00049 class ACE_SSL_Export ACE_SSL_Data_File
00050 {
00051 public:
00052 
00053   /// Default constructor
00054   ACE_SSL_Data_File (void);
00055 
00056   /// Contructor from a file name and the file type.
00057   ACE_SSL_Data_File (const char *file_name,
00058                      int type = SSL_FILETYPE_PEM);
00059 
00060   /// The file name
00061   const char *file_name (void) const;
00062 
00063   /// The type
00064   int type (void) const;
00065 
00066 private:
00067 
00068   /// The file name
00069   ACE_CString file_name_;
00070 
00071   /// The type, used by the SSL library to parse the file contents.
00072   int type_;
00073 };
00074 
00075 // ****************************************************************
00076 
00077 
00078 /**
00079  * @class ACE_SSL_Context
00080  *
00081  * @brief A wrapper for the OpenSSL SSL_CTX related functions.
00082  *
00083  * This class provides a wrapper for the SSL_CTX data structure.
00084  * Since most applications have a single SSL_CTX structure, this class
00085  * can be used as a singleton.
00086  */
00087 class ACE_SSL_Export ACE_SSL_Context
00088 {
00089   friend void ACE_SSL_locking_callback (int, int, const char *, int);
00090 
00091 public:
00092 
00093   enum {
00094     INVALID_METHOD = -1,
00095     SSLv2_client = 1,
00096     SSLv2_server,
00097     SSLv2,
00098     SSLv3_client,
00099     SSLv3_server,
00100     SSLv3,
00101     SSLv23_client,
00102     SSLv23_server,
00103     SSLv23,
00104     TLSv1_client,
00105     TLSv1_server,
00106     TLSv1
00107   };
00108 
00109   /// Constructor
00110   ACE_SSL_Context (void);
00111 
00112   /// Destructor
00113   ~ACE_SSL_Context (void);
00114 
00115   /// The Singleton context, the SSL components use the singleton if
00116   /// nothing else is available.
00117   static ACE_SSL_Context *instance (void);
00118 
00119   /**
00120    * Set the CTX mode.  The mode can be set only once, afterwards the
00121    * function has no effect and returns -1.
00122    * Once the mode is set the underlying SSL_CTX is initialized and
00123    * the class can be used.
00124    * If the mode is not set, then the class automatically initializes
00125    * itself to the default mode.
00126    */
00127   int set_mode (int mode = ACE_SSL_Context::SSLv23);
00128 
00129   int get_mode (void) const;
00130 
00131   /// Get the SSL context
00132   SSL_CTX *context (void);
00133 
00134   /// Get the file name and file format used for the private key
00135   int private_key_type (void) const;
00136   const char *private_key_file_name (void) const;
00137 
00138   /// Set the private key file.
00139   /**
00140    * @note This method should only be called after a certificate has
00141    *       been set since key verification is performed against the
00142    *       certificate, among other things.
00143    */
00144   int private_key (const char *file_name,
00145                    int type = SSL_FILETYPE_PEM);
00146 
00147   /// Verify that the private key is valid.
00148   /**
00149    * @note This method should only be called after a certificate has
00150    *       been set since key verification is performed against the
00151    *       certificate, among other things.
00152    */
00153   int verify_private_key (void);
00154 
00155   /// Get the file name and file format used for the certificate file
00156   int certificate_type (void) const;
00157   const char *certificate_file_name (void) const;
00158 
00159   /// Set the certificate file.
00160   int certificate (const char *file_name,
00161                    int type = SSL_FILETYPE_PEM);
00162 
00163 
00164   /**
00165    *  Load the location of the trusted certification authority
00166    *  certificates.  Note that CA certificates are stored in PEM format
00167    *  as a sequence of certificates in <ca_file> or as a set of
00168    *  individual certificates in <ca_dir> (or both).
00169    *
00170    *  Note this method is called by set_mode() to load the default
00171    *  environment settings for <ca_file> and <ca_dir>, if any. This
00172    *  allows for automatic service configuration (and backward
00173    *  compatibility with previous versions.
00174    *
00175    *  Note that the underlying SSL function will add valid file and
00176    *  directory names to the load location lists maintained as part of
00177    *  the SSL_CTX table.  (... It therefore dosn't make sense to keep a
00178    *  copy of the file and path name of the most recently added
00179    *  <ca_file> or <ca_path>.
00180    *
00181    *  @return 0 for success or -1 on error.
00182    *
00183    *  @see OpenSSL manual SSL_CTX_load_verify_locations(3) for a
00184    *  detailed description of the CA file and directory requirements
00185    *  and processing.
00186   */
00187   int load_trusted_ca(const char* ca_file = 0, const char* ca_dir = 0);
00188 
00189   /**
00190      Test whether any CA locations have been successfully loaded and
00191      return the number of successful attempts.
00192 
00193      @return  >0 This value indicates the number of successful CA load
00194                  attempts .
00195      @return  0  If all CA load attempts have failed.
00196   */
00197   int have_trusted_ca(void) const;
00198 
00199 
00200   /**
00201    *  @todo Complete this documentation where elipses(...) are used
00202    *
00203    *  @doc Use this method when certificate chain verification is
00204    *  required.  The default server behaviour is SSL_VERIFY_NONE
00205    *  i.e. client certicates are requested for verified. This method
00206    *  can be used to configure server to request client certificates
00207    *  and perform the certificate verification. If <strict> is set
00208    *  true the client connection is rejected when certificate
00209    *  verification fails.  Otherwise the session is accepted with a
00210    *  warning, which is the default behaviour.  If <once> is set true
00211    *  (default), certificates are requested only once per session.
00212    *  The last parameter <depth> can be used to set the verification
00213    *  depth.
00214    *
00215    *  Note for verification to work correctly there should be a valid
00216    *  CA name list set using load_trusted_ca().
00217    *
00218    *  @see OpenSSL documentation of SSL_CTX_set_verify(3) for details of
00219    *  the verification process.
00220    *
00221    *  @see OpenSSL documentation ... set_verify_depth(3) ...
00222    *
00223    *  Note that this method overrides the use of the
00224    *  default_verify_mode() method.
00225    */
00226   void set_verify_peer (int strict = 0,
00227                         int once = 1,
00228                         int depth = 0);
00229 
00230 
00231   /// TODO: a implementation that will lookup the CTX table for the list
00232   /// of files and paths etc.
00233   /// Query the location of trusted certification authority
00234   /// certificates.
00235   // const char* ca_file_name(void) const;
00236   // const char* ca_dir_name(void) const;
00237 
00238 
00239 
00240   /**
00241    * Set and query the default verify mode for this context, it is
00242    * inherited by all the ACE_SSL objects created using the context.
00243    * It can be overriden on a per-ACE_SSL object.
00244    */
00245   void default_verify_mode (int mode);
00246   int default_verify_mode (void) const;
00247 
00248   /**
00249    * @name OpenSSL Random Number Generator Seed Related Methods
00250    *
00251    * These are methods that can be used to seed OpenSSL's
00252    * pseudo-random number generator.  These methods can be called more
00253    * than once.
00254    */
00255   //@{
00256   /// Seed the underlying random number generator.  This value should
00257   /// have at least 128 bits of entropy.
00258   int random_seed (const char * seed);
00259 
00260   /// Set the Entropy Gathering Daemon (EGD) UNIX domain socket file to
00261   /// read random seed values from.
00262   int egd_file (const char * socket_file);
00263 
00264   /**
00265    * Set the file that contains the random seed value state, and the
00266    * amount of bytes to read.  "-1" bytes causes the entire file to be
00267    * read.
00268    */
00269   int seed_file (const char * seed_file, long bytes = -1);
00270   //@}
00271 
00272   /// Print SSL error corresponding to the given error code.
00273   static void report_error (unsigned long error_code);
00274 
00275   /// Print the last SSL error for the current thread.
00276   static void report_error (void);
00277 
00278   /**
00279    * @name Diffie-Hellman (DH) Parameters
00280    *
00281    * When using DSS-based certificates, Diffie-Hellman keys need to be
00282    * exchanged.  These must be provided in the form of DH key
00283    * generation parameters loaded in, or as fixed keys hardcoded into
00284    * the code itself.  ACE_SSL supports loaded parameters.
00285    * 
00286    */
00287   //@{
00288   /**
00289    * Load Diffie-Hellman parameters from file_name.  The specified file can be
00290    * a standalone file containing only DH parameters (e.g., as created
00291    * by <code>openssl dhparam</code>), or it can be a certificate which has
00292    * a PEM-encoded set of DH params concatenated on to i.
00293    */
00294   int dh_params (const char *file_name, int type = SSL_FILETYPE_PEM);
00295   const char *dh_params_file_name () const;
00296   int dh_params_file_type () const;
00297   //@}
00298 
00299 private:
00300 
00301   /// Verify if the context has been initialized or not.
00302   void check_context (void);
00303 
00304   /// @@ More to document
00305   void ssl_library_init ();
00306   void ssl_library_fini ();
00307 
00308   // = Prevent assignment and initialization.
00309   //@{
00310   ACE_UNIMPLEMENTED_FUNC (void operator= (const ACE_SSL_Context &))
00311   ACE_UNIMPLEMENTED_FUNC (ACE_SSL_Context (const ACE_SSL_Context &))
00312   //@}
00313 
00314 private:
00315   // @@ Carlos, I protected this variable with an ACE_GUARD, just like
00316   //    what we do for the orb_init_count_ variable in
00317   //    tao/ORB.cpp.   The code isn't pretty but it should suffice
00318   //    until the SSL context is stored in a Singleton.
00319   //       -Ossama
00320 
00321   /// The SSL_CTX structure
00322   SSL_CTX *context_;
00323 
00324   /// Cache the mode so we can answer fast
00325   int mode_;
00326 
00327   /// The private key, certificate, and Diffie-Hellman paramters files
00328   ACE_SSL_Data_File private_key_;
00329   ACE_SSL_Data_File certificate_;
00330   ACE_SSL_Data_File dh_params_;
00331 
00332   /// The default verify mode.
00333   int default_verify_mode_;
00334 
00335   /// count of successful CA load attempts
00336   int have_ca_;
00337 
00338   /// Reference count of the number of times the ACE_SSL_Context was
00339   /// initialized.
00340   static int library_init_count_;
00341 
00342   // @@ This should also be done with a singleton, otherwise it is not
00343   //    thread safe and/or portable to some weird platforms...
00344 
00345 #ifdef ACE_HAS_THREADS
00346   /// Array of mutexes used internally by OpenSSL when the SSL
00347   /// application is multithreaded.
00348   static ACE_mutex_t * lock_;
00349 
00350   // @@ This should also be managed by a singleton.
00351 #endif
00352 
00353 };
00354 
00355 #if defined(__ACE_INLINE__)
00356 #include "SSL_Context.inl"
00357 #endif /* __ACE_INLINE__ */
00358 
00359 #include "ace/post.h"
00360 
00361 #endif  /* ACE_SSL_CONTEXT_H */

Generated on Mon Jun 16 13:15:55 2003 for ACE_SSL by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002