#ifndef AEESSL_H
#define AEESSL_H
/*======================================================

FILE:  AEESSL.h

SERVICES:
        ISSL, SSLRootCerts

GENERAL DESCRIPTION:
        Implements the SSL protocol engine over/under the ISocket 
        interface using IX509Chain for certificate chaining
        

  
=====================================================

      Copyright © 2002 QUALCOMM Incorporated 
              All Rights Reserved.
           QUALCOMM Proprietary/GTDR

=====================================================*/
#include "AEE.h"
#include "AEESource.h"
#include "AEEError.h"
#include "AEEWebOpts.h"
#include "AEENet.h"
#include "AEEX509Chain.h"

//********************************************************************************************************************************
//
// SSL Type declarations
//
//********************************************************************************************************************************


// SSL protocol versions
#define SSL_VERSION_30         0x0300
#define SSL_VERSION_TLS10      0x0301
#define SSL_VERSION_UNKNOWN    0xffff


// Constants representing diffrent key exchange protocols
#define SSL_KEYPROT_NONE          (0)   // No key exchange       
#define SSL_KEYPROT_DH_ANONYMOUS  (1)   // anonymous Diffie-Hellman
#define SSL_KEYPROT_DH_EPHEMERAL  (2)   // ephemeral Diffie-Hellman   
#define SSL_KEYPROT_DH_DSS_SIGN   (3)   // Diffie-Hellman w/ DSS signature
#define SSL_KEYPROT_DH_RSA_SIGN   (4)   // Diffie-Hellman w/ RSA signature
#define SSL_KEYPROT_DH_DSS_CERT   (5)   // Diffie-Hellman w/ DSS certificate
#define SSL_KEYPROT_DH_RSA_CERT   (6)   // Diffie-Hellman w/ RSA certificate
#define SSL_KEYPROT_RSA           (7)   // Standard RSA with certs
#define SSL_KEYPROT_UNKNOWN       (100) // Don't know what the exchange was

// Represent different encryption algorithms 
#define SSL_CRYPT_NONE            (0)   // No encryption
#define SSL_CRYPT_RC4             (1)   // ARC4 algorithm
#define SSL_CRYPT_DES             (2)   // DES algorithm
#define SSL_CRYPT_3DES            (3)   // 3DES algorithm
#define SSL_CRYPT_SEED            (4)   // SEED algorithm
#define SSL_CRYPT_UNKNOWN         (100) // Don't know what was used 

// The hash or mac algorithm used 
#define SSL_HASH_NONE             (0)   // No hash function 
#define SSL_HASH_SHA              (1)   // SHA-1 hash function 
#define SSL_HASH_MD5              (2)   // MD5 hash function 
#define SSL_HASH_UNKNOWN          (100) // Don't know what was used 

// Cipher suites
#define SSL_CSUITE_RSA_WITH_RC4_128_MD5      (0x0004)
#define SSL_CSUITE_RSA_WITH_RC4_128_SHA      (0x0005)
#define SSL_CSUITE_RSA_WITH_DES_CBC_SHA      (0x0009)
#define SSL_CSUITE_RSA_WITH_3DES_EDE_CBC_SHA (0x000A)
#define SSL_CSUITE_RSA_WITH_SEED_CBC_SHA     (0x0109)
#define SSL_CSUITE_UNKNOWN                   (0xffff) 


// Data structure holding security level info, about 6 bytes
typedef struct {
   uint16  uProtoVersion; // One of SSL_VERSION_*
   uint8   uKeyExchange;  // One of SSL_KEYPROT_*
   uint8   uCryptAlgo;    // One of SSL_CRYPT_*
   uint8   uHashAlgo;     // One of SSL_HASH_*
   uint16  uCipherSuite;  // One of SSL_CSUITE_*  SSL_CSUITE_UNKNOWN returning this is unsupported
} SSLSecurityInfo;


typedef struct SSLInfo
{
   int             nResult;      // Status of the SSL connection. One of SSL_RESULT_*
   SSLSecurityInfo SecInfo;      // The security level negotiated. Valid on SSL_RESULT_SECURED
   X509TrustResult TrustResult;  // Trust results; see AEEX509Chain.h
   ISocket        *pSSLSocket;   // Open socket representing secured stream

} SSLInfo;





//********************************************************************************************************************************
//
// SSL Options
//
//********************************************************************************************************************************

// Options and parameters in ISSL are handled with WebOpts. Some are
// options you set that control the protocol engine. Some are  values
// you retrieve to find out what the engine has done. Any value you set
// you can also get. 

// ISSL uses IX509Chain for all the certificate chaining. You can and
// should set some IX509Chain options for the negotiation. You can 
// AddOpt them to instance of ISSL, or you can pass them to negotiate.
// They will be passed on to IX509Chain. These options include
// the root certs and the host name you're trying to get to.
//
// By default these options are *not* copied. You have to be sure the 
// storage for the value you set persists. You can set the options to be copied 
// by adding  a copy opts parameter. 
//
// You can add WebOpt defaults (other IWebOpts objects) to the option list
// for negotiation or to ISSL to chain sets of options however you see fit.
// For example you could have one IWebOpt that has all the options that are
// common to one of several ISSL connections you have going, or as a base
// set of options.


// claim our chunk of the option ID space. This is private stuff actually part of the
// implementation that you don't need to reference to use ISSL
#define WEBOPT_SSL_SZ               0x00012000
#define WEBOPT_SSL_SZ_LAST          0x000121ff //that's 511 possible options
#define WEBOPT_SSL_32BIT            0x00022000
#define WEBOPT_SSL_32BIT_LAST       0x000221ff
#define WEBOPT_SSL_VARIABLE         0x10010000
#define WEBOPT_SSL_VARIABLE_LAST    0x1001f000
#define WEBOPT_SSL_INTERFACE        0x00032000
#define WEBOPT_SSL_INTERFACE_LAST   0x000321ff


#define WEBOPT_SSL_SEC_INFO               (WEBOPT_SSL_VARIABLE+sizeof(SSLInfo))
#define WEBOPT_SSL_TRUST_MODE             (WEBOPT_SSL_32BIT+1) 
#define    SSL_TRUST_MODE_FAIL   (0L)
#define    SSL_TRUST_MODE_CHECK  (1L)
#define    SSL_TRUST_MODE_IGNORE (2L)
#define    SSL_TRUST_MODE_ALWAYS (3L)
#define WEBOPT_SSL_ALLOWED_CIPHER_SUITES  (WEBOPT_SSL_32BIT+2)                    
#define WEBOPT_SSL_ALLOWED_VERSIONS       (WEBOPT_SSL_32BIT+3)  
#define WEBOPT_SSL_WANT_X509_CHAIN        (WEBOPT_SSL_32BIT+4)  
#define WEBOPT_SSL_X509_CHAIN             (WEBOPT_SSL_INTERFACE+1)
#define WEBOPT_SSL_SESSIONDB              (WEBOPT_SSL_INTERFACE + 2)


//Reserved
#define ISSL_SOCKET_IOCTL_RESERVED1 0x5555feed




//********************************************************************************************************************************
//
// SSL Interface
//
//********************************************************************************************************************************

typedef struct ISSL ISSL;
AEEINTERFACE(ISSL) {
   INHERIT_IWebOpts(ISSL);

   void  (*SetSocket)    (ISSL *po, ISocket *pSock);                     
   void  (*Negotiate)    (ISSL *po, SSLInfo *pInfo, IX509Chain **pCerts, AEECallback *pcb, ...);   
   void  (*NegotiateV)   (ISSL *po, SSLInfo *pInfo, IX509Chain **pCerts, AEECallback *pcb, const WebOpt *awozList);   
   void  (*Renegotiate)  (ISSL *po, SSLInfo *pInfo, IX509Chain **pCerts, AEECallback *pcb, ...);   
   void  (*RenegotiateV) (ISSL *po, SSLInfo *pInfo, IX509Chain **pCerts, AEECallback *pcb, const WebOpt *awozList);   
   void  (*Close)        (ISSL *po, SSLInfo *pInfo, AEECallback *pcb);
};

#define ISSL_AddRef(p)                  AEEGETPVTBL((p),ISSL)->AddRef((p))
#define ISSL_Release(p)                 AEEGETPVTBL((p),ISSL)->Release((p))  

#define ISSL_QueryInterface(p,clsid,pp) AEEGETPVTBL((p),ISSL)->QueryInterface((p),(clsid),(pp))
#define ISSL_AddOpt(p,o)                AEEGETPVTBL((p),ISSL)->AddOpt((p),(o))
#define ISSL_RemoveOpt(p,i,n)           AEEGETPVTBL((p),ISSL)->RemoveOpt((p),(i),(n))
#define ISSL_GetOpt(p,i,n,o)            AEEGETPVTBL((p),ISSL)->GetOpt((p),(i),(n),(o))

#define ISSL_SetSocket(p,s)             AEEGETPVTBL((p),ISSL)->SetSocket((p),(s))
#define ISSL_Negotiate(p,args)          AEEGETPVTBL((p),ISSL)->Negotiate args
#define ISSL_NegotiateV(p,s, x, cb,ol)  AEEGETPVTBL((p),ISSL)->NegotiateV((p),(s), (x), (cb),(ol))
#define ISSL_Renegotiate(p,args)        AEEGETPVTBL((p),ISSL)->Renegotiate args
#define ISSL_RenegotiateV(p,s,x, cb,ol) AEEGETPVTBL((p),ISSL)->RenegotiateV((p),(s), (x), (cb),(ol))
#define ISSL_Close(p,s,cb)              AEEGETPVTBL((p),ISSL)->Close((p),(s),(cb))






/*=====================================================================
  DATA STRUCTURE DOCUMENTATION
=======================================================================

=======================================================================
SSLSecurityInfo

Description:
   This data type is a negotiated SSL security level including cipher suite.

Definition:
   typedef struct {
      uint16  uProtoVersion; 
      uint8   uKeyExchange;
      uint8   uCryptAlgo;
      uint8   uHashAlgo;
      uint16  uCipherSuite;
   } SSLSecurityInfo;;

Members:
===pre>
   uProtoVersion        SSL protocol version negotiated. One of SSL_VERSION_*
   uKeyExchagne         The key exchange algorithm. One of SSL_KEYPROT_*
   uCryptAlgo           Symmetric algorithm negotiated. One of SSL_CRYPT_*
   uHashAlgo            Hash function negotiated. One of SSL_HASH_*
   uCipherSuite         Cipher suite negotiated. One of SSL_CSUITE_*  
===/pre>

Comments:
   When the security level negotiated for the currrent session
   is reported it is in the SSLSecurityInfo data structure.
   
   The following constants define the protocol version. SSL version2
   is not supported.
===pre>
      SSL_VERSION_30            SSL version 3.0
      SSL_VERSION_TLS10         TLS version 1.0
      SSL_VERSION_UNKNOWN       Protocol unknown
===/pre>

   The following constants define the key exchange / agreement / protection
   scheme or algorithm. Note that all of these algorithms may not be
   available with a particular version of Brew or on a particular handset. 
===pre>
      SSL_KEYPROT_NONE          No key exchange       
      SSL_KEYPROT_DH_ANONYMOUS  Anonymous Diffie-Hellman
      SSL_KEYPROT_DH_EPHEMERAL  Ephemeral Diffie-Hellman   
      SSL_KEYPROT_DH_DSS_SIGN   Diffie-Hellman w/ DSS signature
      SSL_KEYPROT_DH_RSA_SIGN   Diffie-Hellman w/ RSA signature
      SSL_KEYPROT_DH_DSS_CERT   Diffie-Hellman w/ DSS certificate
      SSL_KEYPROT_DH_RSA_CERT   Diffie-Hellman w/ RSA certificate
      SSL_KEYPROT_RSA           Standard RSA with certs
      SSL_KEYPROT_UNKNOWN       Don't know what the exchange was
===/pre>

   The following constants define the symmetric cipher used. Note
   that just because a constant is defined here doesn't mean that
   a particular version of Brew or handset supports it. ARC4 is
   generally always available and performs well. This is the
   same algorithm in the cipher suite separated out for convenience.
===pre>
      SSL_CRYPT_NONE            No encryption
      SSL_CRYPT_RC4             ARC4 algorithm
      SSL_CRYPT_DES             DES algorithm
      SSL_CRYPT_3DES            3DES algorithm
      SSL_CRYPT_SEED            SEED algorithm
      SSL_CRYPT_UNKNOWN         Don't know what was used 
===/pre>

   The following constants define the hash function used. They are
   usually available with any Brew version or handsets. 
===pre>
      SSL_HASH_NONE             No hash function 
      SSL_HASH_SHA              SHA-1 hash function 
      SSL_HASH_MD5              MD5 hash function 
      SSL_HASH_UNKNOWN          Don't know what was used 
===/pre>

   The following constants indicate the cipher suite used. This is some
   what redundant with the above set of constants, but included for
   convenience. Not all cipher suites are supported on a given version
   of Brew or a given handset. They correspond to the standard cipher
   suites for SSL and TLS.
===pre>
      SSL_CSUITE_RSA_WITH_RC4_128_MD5  
      SSL_CSUITE_RSA_WITH_RC4_128_SHA  
      SSL_CSUITE_RSA_WITH_DES_CBC_SHA   
      SSL_CSUITE_RSA_WITH_3DES_EDE_CBC_SHA  
      SSL_CSUITE_UNKNOWN  
===/pre>  
   The above constants are also used to request a particular set of protocol
   versions and cipher suites before a negotiation.

See Also:
    ISSL_Negotiate(),
    ISSL_NegotiatV(),
    ISSL_Renegotiate(),
    ISSL_RenegotiateV()

=======================================================================
SSLInfo

Description:
   This data type is the result of the SSL negotiation including the secured ISocket.

Definition:
   typedef struct SSLInfo
   {
      int             nResult;
      SSLSecurityInfo SecInfo;
      X509TrustResult TrustResult;
      ISocket        *pSSLSocket;
   } SSLInfo;

Members:
===pre>
   nResult           General result of an SSL negotiation. One of SSL_RESULT_*
   SecInfo           The security level negotiated. Valid on SSL_RESULT_SECURED
   TrustResult       Trust results; see AEEX509Chain.h
   pSSLSocket        Open socket representing secured stream
===/pre>
Comments:
   This returns the result of a negotiation. The results has two parts, the
   protocol negotiation result, and the trust result from the X509 chain. 
   verification.  
   
   Trust result is filled in only if nResult is either SSL_RESULT_TRUST_ERR or
   SSL_RESULT_SECURED. If the result is a secured connection there will be no
   trust errors, and only the chain length is of any use in the structure. If the
   error is SSL_RESULT_TRUST_ERR then the details of the error are reported in 
   TrustResult structure. Note that nResult in the TrustResult structure does not
   show the details, rather the array and summary further down show it. nResult
   in the TrustResult structure will generally be 0. Errors such as running out
   of memory or a very corrupt certificate are reported as nResult in the SSLInfo
   structure.

   Trust errors can be overridden and the negotiation continued on. Other errors
   cannot be overriden.  
   
   pSSLSocket is the most important part of the result as it is the secured
   stream.

See Also:
   ISSL_Negotiate(), 
   SSLSecurityInfo, 
   IX509CHAIN_Verify(),
   X509TrustResult

=======================================================================*/


/*=======================================================================
  INTERFACES   DOCUMENTATION
 ========================================================================

ISSL Interface

This interface provides SSL/TLS security for a network connection. This interface
inherits from IWebOpts. It uses ISocket in the interface. Note that this functionality
is available combined with HTTP to form HTTPS in the IWeb interface. The web opts
described here and in IX509Chain do apply to https.

The WebOpts are passed all the way down through IWeb to the ISSL or IX509Chain used for 
the https transaction. Also, the web opts that give the results of an SSL negotiation 
performed as part of an HTTPS connection are available. These are available as options 
in the IWebResp object returned when the web transaction completes. For example you can 
get the security level. You can also request the whole IX509Chain object be returned if 
you wish to examine the cert chain. 

Generally to use https, you should create an IWeb, add an opt or opts for root certs, 
add an opt for the hostname, and give a URL with scheme "https". 

A set of root certs commonly used with SSL is available via the ISSLRootCerts interface. 
This can just be passed to IWeb or ISSL as a web opt of type WEBOPT_DEFAULTS.

The following header file is required:

AEESSL.h

=============================================================================

ISSL_AddRef()

Description:
    This function is inherited from IBASE_AddRef(). 

See Also:

    ISSL_Release()

=============================================================================

ISSL_Release()

Description:
    This function releases references to ISSL. 

Prototype:
    void ISSL_Release(ISSL *pISSL);

Parameters:
    pISSL :  The Interface pointer

Return Value:
    none

Comments:
   If the reference count goes to zero all memory held is freed and all callbacks
   are cancelled. Callbacks should be cancelled explicitly rather than relying on ISSL_Release.

Version:
   Introduced BREW Client 2.0

See Also:

    ISSL_AddRef()

=============================================================================

ISSL_QueryInterface()

Description:
    This function is inherited from IQI_QueryInterface().


=============================================================================

ISSL_AddOpt()

Description:
    This function is inherited from IWEBOPTS_AddOpt().

See Also:

    WebOpt
    IWebOpts Interface
    ISSL_RemoveOpt()
    ISSL_GetOpt()
    
=============================================================================

ISSL_RemoveOpt()

Description:
    This function is inherited from IWEBOPTS_GetOpt(). 

See Also:
    IWebOpts Interface
    ISSL_AddOpt()
    
=============================================================================

ISSL_GetOpt()

Description:
    This function is inherited from IWEBOPTS_GetOpt(). 

See Also:
    WebOpt
    IWebOpts Interface
    ISSL_AddOpt()
    ISSL_RemoveOpt()

=============================================================================

ISSL_SetSocket()

Description:
    This function must be called to supply the socket open and connected to the
SSL server.

Prototype:
    void ISSL_SetSocket(ISSL *pISSL, ISocket *pISocket)

Parameters:
    pISSL :  The Interface pointer
    pISocket :  Pointer to open socket

Return Value:
    none

Comments:
   The ISocket passed in must be open and connected to a server that is ready to
   start an SSL negotiation. Note that the ISocket passed is an object with a vtable.
   It doesn't have to be a standard Brew ISocket, but can instead be an object that
   implements ISocket. By this mechanism ISSL can be used on top of any data stream
   object. 

Version:
   Introduced BREW Client 2.0

See Also:
    None
==============================================================================
ISSL_NegotiatV()

This function is described with ISSL_Negotiate()
==============================================================================
ISSL_Renegotiate()

This function is described with ISSL_Negotiate()
==============================================================================
ISSL_RenegotiateV()

This function is described with ISSL_Negotiate()
==============================================================================
ISSL_Negotiate()

Description:
   The functions ISSL_Negotiate(), ISSL_NegotiatV(), ISSL_Renegotiate(), and ISSL_RenegotiateV(), causes SSL handshaking to progress. If a handshake has not started
   it starts it. If one is in progress it continues it. If one has been established
   it reports the state of it in relation to what was requested.
 
   Renegotiate is exactly the same except it will redo the negotiation if a connection
   is established. Renegotiate is currently NOT supported. 

Definition:


void ISSL_Negotiate
    (
    ISSL *pISSL, 
    SSLInfo *pinfo, 
    IX509Chain **pCerts, 
    AEECallback *pcb, ...
    )

void ISSL_NegotiateV
    (
    ISSL *pISSL, 
    SSLInfo *pinfo, 
    IX509Chain **pCerts,
    AEECallback *pcb,
    WebOpts *pOpts
    )

void ISSL_Renegotiate
    (
    ISSL *pISSL, 
    SSLInfo *pinfo, 
    IX509Chain *pCerts, 
    AEECallback *pcb, ...
    )

void ISSL_RenegotiateV
    (
    ISSL *pISSL, 
    SSLInfo *pinfo, 
    IX509Chain **pCerts,
    AEECallback *pcb,
    WebOpts *pOpts
    )


Parameters:
    pISSL :  The Interface pointer
    pinfo :  Place to put the response structure
    pCerts :  Place for ISSL to return cert chain. 
    pcb :  Place to call back when SSL, suceeds, fails or needs help
    pOpts or ...  :  The set of options against which negotiation is performed.

Return Value:
    None

Comments:  
   In the simplest case this call negotiates until completion or failure. It uses the options
   passed on the command line and any options stored in the instance as parameters for the
   negotiation. The negotiation also does the cert chain verification internally using an 
   instance of IX509Chain. On completion or failure the pinfo is filled in and the
   call back is called.

   When evaluating parameters for the negotiation, the options passed as arguments
   to Negotiate are considered first. Note that these may include a default IWebOpts that
   contains a whole tree of options. The ones stored in ISSL are considered next. 
   These options are used for the SSL negotiation to determine cipher suite, protocol,
   version and other. They are also passed to the IX509Chain instance internally
   as options for the cert chain verification. That is you can and should add/pass IX509Chain
   options here. In particular you should pass the root certs set and the hostname.

   If you want the IX509Chain instance created returned so you can examine the
   certs in the chain or store them then you can either pass a non-NULL parameter for
   pCerts or set the web opt that causes the interface to be put in a web opt.

   The negotiation has different behaviors depending on the state of the connection, 
   WEBOPT_SSL_TRUST_MODE, and whether negotiation or renegotiate is called. The three
   connections states are unsecured, suspended negotiation and secured. 

   In the unsecured state the description of WEBOPT_SSL_TRUST_MODE above applies to
   a call to negotiation or renegotiate.  Normally on a trust error ISSL will close the 
   connection to the server and cannot be overridden. This is the case if
   WEBOPT_SSL_TRUST_MODE is not set or it is set to SSL_TRUST_MODE_FAIL. If 
   WEBOPT_SSL_TRUST_MODE is set to SSL_TRUST_MODE_CHECK the connection will not be closed.
   ISSL_Negotiate can then be called again, most likely with some TrustOverrides to
   continue with the SSL session despite the trust error. If it is set to 
   SSL_TRUST_MODE_IGNORE, then all trust errors will be ignored at substantial risk to
   the connection security. If the mode is SSL_TRUST_MODE_ALWAYS the call back will always
   fire after the trust check is complete. This allows you to examine the trust chain and
   reject it even if the chaining engine is  able to successfully validate it.

   A possible mode of operation is to use SSL_TRUST_MODE_CHECK on the first call to
   negotiate, and after checking the trust errors to use SSL_TRUST_MODE_IGNORE on the
   second call to neogiate. IF YOU SET SSL_TRUST_IGNORE ON THE FIRST CALL TO NEGOTIATE YOU
   ARE DEFEATING MOST OF SSL'S SECURITY!! The following are the possible trust modes.
===pre>
      SSL_TRUST_MODE_FAIL      Default, fail on trust errors
      SSL_TRUST_MODE_CHECK     Suspend on trust error so they can be checked and ignored
      SSL_TRUST_MODE_IGNORE    Ignore all trust errors
      SSL_TRUST_MODE_ALWAYS    Always suspend so trust can always be checked.
===/pre>     
   Once in the suspended state any call to negotiate or renegotiate will continue
   the negotiation to success or failure. 

   Calls in the secured state are where it gets, unusual and interesting. If
   renegotiate where supported and is called in the secured state, then a new 
   negotiation will take place. 
 
   If you call negotiate in the secured state the security level of the connection
   will be evaluated against the security level implied by the various options, 
   in particular the cipher suites and root certs. If it matches then success will
   be returned, otherwise failure. On either success or failure the connection it
   self will not be disturbed. The purpose of this is to evaluate a kept-alive
   session for reuse. Though this is not commonly done it is used by the internal
   https implementation. 

   If the WEBOPT_SSL_SESSIONDB option is set to an instantiated IRecordStore interface
   this will be used to store and fetch session resumption data. When a negotiation is
   successful, a record will be stored in the database/cache provided by
   this interface via an add call. Before a negotiation is attempted Lookup
   calls to this database/cache will be performed to find any previously stored
   sessions. The sessions may be stored for the life of the app or for longer. 
   If they are stored longer care should be taken as the records contain the
   master secret from the session.

   When the negotiation completes, examine the pinfo structure to get details, and
   most importantly an instance of an ISocket that is secured. This ISocket can
   be used like any other ISocket. Any IOCTLs that are not handled by ISSL 
   are passed on to the ISocket passed in to ISSL_SetSocket(). Calling ISOCKET_Release()
   is equivalent to calling ISSL_Release().

   The following summarizes WebOpts that affect negotiation. Note that all the
   WebOpts that affect IX509CHAIN_Verify() also affect negotiation.
===pre>
      WEBOPT_SSL_SEC_INFO               An alternate way to get the SSLInfo result
                                        of a negotiation. This is useful with IWeb
                                        and HTTPS.

      WEBOPT_SSL_TRUST_MODE             Specify general behavior on trust errors.

      WEBOPT_SSL_ALLOWED_CIPHER_SUITES  Multiple options to give an ordered list of
                                        cipher suites to be allowed for the
                                        negotiation. Must be one of SSL_CSUITE_*.
              
      WEBOPT_SSL_ALLOWED_VERSIONS       Multiple options to give an order list of
                                        protocol versions to be allowed for the
                                        negotation. Must be one of SSL_VERSION_*.

      WEBOPT_SSL_WANT_X509_CHAIN        Set ths option to get the X509Chain created
                                        internally back in the web opt below. This
                                        allows you to examine the cert chain,
                                        display it or save it. If you set the chain
                                        which uses memory to store all the certs
                                        will persist until this interface is 
                                        destroyed, or the option deleted.

      WEBOPT_SSL_X509_CHAIN             The option in which a reference to the
                                        IX509Chain object used internally will be
                                        returned. This is a single value and should
                                        not be set.

      WEBOPT_SSL_SESSIONDB              The instantiated interface for session
                                        resumption. This must be an interface to an,
                                        IRecordStore, such a IRamCache. If this is 
                                        not set or set to NULL then there will be 
                                        no session resumption.
===/pre>
Side Effects: 
   None  
 
See Also:
   IX509CHAIN_Verify()
   SSLInfo


===============================================================================

ISSL_Close()

Description:
    This function closes and SSL session.

Prototype:
    void ISSL_Close(ISSL *pISSL, SSLInfo *pinfo, AEECallback *pcb);

Parameters:
    pISSL :  The Interface pointer
    pinfo :  Place to put the response structure
    pcb :  Place to call back when SSL, suceeds, fails or needs help

Return Value:
    nReturn in SSLInfo indicates the sucess of the closure 

Comments:
   ISSL_Close makes one attempt to send the close notify alert to the
   server. 

   Closure in SSL tends to differ in practice from the documented
   standard. The standard requires a complete exchange of close
   alerts. In practice the secure closure is acheived by the 
   exchange of protocol messages that are part of the protocol
   secured, not SSL. This is true of HTTP. Basically it is not
   that important for complete closure, thus the implementation
   here simply attempts to send the close notify and not the
   full close handshake.

Side Effects: 
   None     

See Also:
   SSLInfo
   SSLSecurityInfo
   X509TrustResult 

  
==============================================================================*/





/*========================================================================
  INTERFACES   DOCUMENTATION
=======================================================================

SSLRootCerts Interface

This interface provides access to an embeded set of common root certificates. It
is a bit unusual in that it isn't really a new inteface of its own. It's interface
is exactly that of the IWebOpts Interface. The difference is a set of options are
preset which contain common root certificates. They have WebOpt.nID set to 
WEBOPT_X509_ROOT_CERTS and there are usually five or ten of them.

When you call ISHELL_CreateInstance(), pass AEECLSID_SSLROOTCERTS as the class ID. You'll
get back an IWebOpts *. You can uses this as a full instance of IWebOpts and store
other things if you wish.

The root certificates avaialble are usually the common VeriSign roots. They are
provided as a convenience and to save space on the handset and have only one copy
of them, rather than a copy per application that uses SSL. Only a small set of common
ones is included to avoid using up a lot of space on the handset.

Typically this will be instantiated and passed to IX509CHAIN_Verify(), ISSL_Negotiate(),
ISSL_NegotiatV(), ISSL_Renegotiate(), ISSL_RenegotiateV(), or IWEB_GetResponse()
as an option of type WEBOPT_DEFAULTS.


The following header file is required:
AEESSL.h
=============================================================================*/

#endif /*  AEESSL_H */      

   
