// Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).
// All rights reserved.
// This component and the accompanying materials are made available
// under the terms of "Eclipse Public License v1.0"
// which accompanies this distribution, and is available
// at the URL "http://www.eclipse.org/legal/epl-v10.html".
//
// Initial Contributors:
// Nokia Corporation - initial contribution.
//
// Contributors:
//
// Description:
//


#ifndef __SECURESOCKETINTERFACE_H__
#define __SECURESOCKETINTERFACE_H__

#include <e32base.h>
#include <sslerr.h>
#include <x509cert.h>
#include <es_sock.h>

// File description
/** 
 * @file SecureSocketInterface.h
 * Definition of the MSecureSocket class.
 *
 * @publishedAll
 * @released
 */

/** 
 * Server client certificate mode.
 * Specifies if client certificates will be asked for when in server mode, and also if they are optional
 * or must be provided to complete the handshake successfully.
 *
 * @since v7.0
 */
enum TClientCertMode
	{
	/** Client certificates won't be asked for during handshake negotiation. */
	EClientCertModeIgnore,
	/** Client certificates will be requested, but are not compulsory, 
	  * and the handshake will continue if the client doesn't supply one. */
	EClientCertModeOptional,
	/** Client certificates must be supplied, and the handshake will fail if 
	  * the client does not provide a one. */
	EClientCertModeRequired
	};

/**
 * Untrusted certificate dialog mode.
 * When an untrusted certificate is received, the dialog mode determines if the handshake 
 * fails automatically, or if a dialog is displayed allowing the user the option of continuing
 * anyway. 
 *
 * @since v7.0
 */
enum TDialogMode
	{
	/** All untrusted certificates result in a user dialog. */
	EDialogModeAttended,
	/** Untrusted certificates are canceled without user confirmation. */
	EDialogModeUnattended
	};


class MSecureSocket
/**
 * Abstract interface API for secure socket implementations.
 *
 * MSecureSocket is the interface that secure socket implementations must adhere to.
 * The API supports both client and server operation, see individual implementations'
 * documentation for details of client/server operation that they may support.
 * 
 * Secure socket implementations will be used to secure an already open and connected socket. 
 * The class must be passed a reference to an already open and connected socket when a new 
 * secure socket is created. New secure sockets are created through the CSecureSocket class, 
 * which hides the MSecureSocket class and the underlying plug-in nature of implementations 
 * from applications. Secure socket implementations MUST provide a NewL function that 
 * matches the following:
 *
 * @code
 * static MSecureSocket* NewL( RSocket& aSocket, const TDesC& aProtocol );
 * @endcode
 *
 * aSocket A reference to an already opened and connected socket.
 *
 * aProtocol A descriptor containing the name of a protocol, i.e. SSL3.0, TLS1.0, that the 
 * application must specify when it creates the secure socket. The maximum length that can 
 * be specified for a protocol name is 32 characters.
 *
 * For error code definitions see SSLErr.h
 *
 * @since 6.2
 */
	{

public:

	 /** 
	 * Gets the list of cipher suites that are available to use. 
	 * The list of cipher suites that will be used by default will be returned in the descriptor.
	 * They are returned in the order that they will be used during a handshake, and are assumed to
	 * be in the format as per the SSL/TLS RFCs, i.e. [0x??][0x??] for each suite. 
	 * See individual implementation notes for any differences.
	 *
	 * @param aCiphers	A reference to a descriptor, should be at least 64 bytes long. 
	 * @return			Any one of the system error codes, or KErrNone on success. */
	virtual TInt AvailableCipherSuites( TDes8& aCiphers ) = 0;

	 /**
	 * Cancels all outstanding operations. 
	 * This method will cancel all outstanding operations with the exception of Shutdown, 
	 * which cannot be canceled once started. 
	 * See individual implementation notes for behaviour after canceling. */
	virtual void CancelAll() = 0;

	 /**
	 * Cancels an outstanding handshake operation. 
	 * This method is used to cancel the StartClientHandshake, StartServerHandshake and 
	 * RenegociateHandshake operations. 
	 * See individual implementation notes for behaviour after canceling.*/
	virtual void CancelHandshake() = 0;

	 /** 
	 * Cancels any outstanding read operation.
	 * See individual implementation notes for behaviour after canceling. */
	virtual void CancelRecv() = 0;

	 /** 
	 * Cancels any outstanding send operation. 
	 * See individual implementation notes for behaviour after canceling. */
	virtual void CancelSend() = 0;

	 /**
	 * Gets the current client certificate.
	 *
	 * When a secure socket is acting in server mode, the returned certificate will be the certificate that the remote
	 * client provided. 
	 * When acting in client mode, the certificate returned will be the one that the client will send to the 
	 * remote server if requested. 
	 * 
 	 * Note that if there is no client certificate defined, either in server or client mode, 
	 * this method will return NULL.
	 *
	 * @return A pointer to the client certificate, or NULL if none exists.*/
	virtual const CX509Certificate* ClientCert() = 0;

	 /** 
	 * Returns the current client certificate mode.
	 * The client certificate mode is used when the socket is acting as a server, and determines if a 
	 * client certificate is requested.
	 * @see TClientCertMode for details of each mode.
	 * @return TClientCertMode The current mode that is set. */
	virtual TClientCertMode ClientCertMode() = 0; 

	 /** 
	 * Closes the secure connection.
	 * Implementations should terminate the secure connection gracefully as appropriate to their protocol. 
	 * It is assumed that they also close the socket when finished unless explicitly stated. They MUST NOT 
	 * destroy the RSocket object, this is left to the client application.
	 */
	virtual void Close() = 0;

	 /**
	 * Gets the current cipher suite in use.
	 * The current cipher suite is returned in the referenced buffer.
	 * 
	 * Note that it is assumed that implementations return cipher suites in two byte format 
	 * as is the case with the TLS/SSL protocols, i.e. [0x??][0x??]. 
	 * Implementations should specify if they differ.
	 *
	 * @param aCipherSuite		A reference to a descriptor at least 2 bytes long, 
								implementations that differ from the [0x??][0x??] format may 
								require larger descriptors. See individual implementations 
								notes for details. 
	 * @return					Any one of the system error codes, or KErrNone on success. */
	virtual TInt CurrentCipherSuite( TDes8& aCipherSuite ) = 0;

	 /**
	 * Gets the current dialog mode.
	 * @see		TDialogMode for description of valid modes.
	 * @return	TDialogMode The current dialog mode. */
	virtual TDialogMode	DialogMode() = 0; 

	 /** 
	 * Flushes the session cache.
	 *
	 * If protocols implement a session cache, this method will cause that cache to be flushed. */
	virtual void FlushSessionCache() = 0;

	 /**
	 * Gets an option.
	 *
	 * SecureSocket implementations may provide options that can be read with this method.
	 * See individual implementation notes for details.
	 *
	 * @param aOptionName	An integer constant which identifies an option.	 
	 * @param aOptionLevel	An integer constant which identifies level of an option.	 
	 * @param aOption		Option value packaged in a descriptor.
	 * @return				KErrNone if successful, otherwise another of the system-wide error codes. */
	virtual TInt GetOpt(TUint aOptionName,TUint aOptionLevel,TDes8& aOption) = 0;

	 /**
	 * Gets an option.
	 *
	 * Secure socket implementations may provide options that can be read with this method.
	 * See individual implementation notes for details.
	 *
	 * @param aOptionName	An integer constant which identifies an option.
	 * @param aOptionLevel	An integer constant which identifies level of an option.	 
	 * @param aOption		Option value as an integer.
	 * @return				KErrNone if successful, otherwise another of the system-wide error codes. */
	virtual TInt GetOpt(TUint aOptionName,TUint aOptionLevel,TInt& aOption) = 0;

	 /**
	 * Get the protocol in use.
	 *
	 * This method can be used to return the particular protocol/version that is being 
	 * used by implementations that support different protocols/versions.
	 * See individual implementation notes for details.
	 *
	 * @param aProtocol		A descriptor containing the protocol name/version that is being 
							used. Protocol names can be upto 32 characters long, and so a 
							descriptor of at least that size is required.
	 * @return			KErrNone if successful; otherwise, another of the system-wide error codes. */
	virtual TInt Protocol(TDes& aProtocol) = 0;

	 /**
	 * Receives data from the socket.
	 *
	 * This is an asynchronous method, and will complete when the descriptor has been filled. 
	 * Only one Recv or RecvOneOrMore operation can be outstanding at any time.
	 *
	 * @param aDesc		A descriptor where data read will be placed.
	 * @param aStatus	On completion, will contain an error code: see the system-wide error 
						codes. Note that KErrEof indicates that a remote connection is 
						closed, and that no more data is available for reading. */
	virtual void Recv(TDes8& aDesc, TRequestStatus & aStatus) = 0;

	 /** 
	 * Receives data from the socket. 
	 *
	 * This is an asynchronous call, and will complete when at least one byte has been read.
	 * Only one Recv or RecvOneOrMore operation can be outstanding at any time.
	 *
	 * @param aDesc		A descriptor where data read will be placed.
	 * @param aStatus	On completion, will contain an error code: see the system-wide error 
	 *					codes. Note that KErrEof indicates that a remote connection is closed,
     *					and that no more data is available for reading.
	 * @param aLen		On return, a length which indicates how much data was read. 
	 *					This is the same as the length of the returned aDesc. */
	virtual void RecvOneOrMore(TDes8& aDesc, TRequestStatus& aStatus, TSockXfrLength& aLen) = 0;

	 /**
	 * Initiates a renegotiation of the secure connection.
	 *
	 * This is an asynchronous method that completes when renegotiation is complete. 
	 * It is valid for both client and server operation. 
	 * There can only be one outstanding RenegotiateHandshake operation at a time.
	 *
	 * @param aStatus	On completion, will contain an error code: see the system-wide error 
						codes. */
	virtual void RenegotiateHandshake(TRequestStatus& aStatus) = 0;

	 /** 
	 * Send data over the socket. 
	 *
	 * This is an asynchronous call. Only one Send operation can be outstanding at any time. 
	 * @param aDesc		A constant descriptor containing the data to be sent.
	 * @param aStatus	On completion, will contain an error code: see the system-wide error 
						codes. */
	virtual void Send(const TDesC8& aDesc, TRequestStatus& aStatus) = 0;

	 /** 
	 * Send data over the socket.
	 *
	 * This is an asynchronous call. Only one Send operation can be outstanding at any time.
	 *
	 * @param aDesc		A constant descriptor.
	 * @param aStatus	On completion, will contain an error code: see the system-wide error 
	 *					codes. 
	 * @param aLen		Filled in with amount of data sent before completion */
	virtual void Send(const TDesC8& aDesc, TRequestStatus& aStatus, TSockXfrLength& aLen) = 0;

	 /**
	 * Gets the current server certificate.
	 *
	 * When a secure socket is acting in client mode, the returned certificate will be the 
	 * certificate for the remote server.
	 * When acting in server mode, the certificate returned will be the one that is being 
	 * used as the server certificate.
	 *
	 * @return CX509Certificate A pointer to the certificate. */ 
	virtual const CX509Certificate* ServerCert() = 0;

	 /** 
	 * Sets a list of cipher suites that are available to use. 
	 *
	 * It is assumed that implementations require a list of cipher suites supplied in a descriptor in two
	 * byte format as is the case with the TLS/SSL protocols, i.e. [0x??][0x??]. 
	 * It is also assumed that the order of suites is important, and so they should be listed
	 * with the preferred suites first. 
	 * Implementations should specify if they differ.
	 *
	 * @param aCiphers	A descriptor containing the list or ciphers suites to use. 
	 * @return			Any one of the system error codes, or KErrNone on success. */
	virtual TInt SetAvailableCipherSuites(const TDesC8& aCiphers) = 0;

	 /**
	 * Sets the client certificate to use.
	 *
	 * When a secure socket is acting in client mode, this method will set the certificate 
	 * that will be used if a server requests one.
	 * When acting in server mode, this method will perform no action, but will return KErrNotSupported.
	 * @param aCert		A reference to the certificate to use.
	 * @return			Any one of the system error codes, or KErrNone on success. */
	virtual TInt SetClientCert(const CX509Certificate& aCert) = 0;

	 /** 
	 * Set the client certificate mode. 
	 *
	 * When a secure socket is acting in server mode, the client certificate mode determines
	 * if clients will be requested to provide a certificate.
	 * When acting in client mode, this method will perform no action, but will return KErrNotSupported.
	 *
	 * @see TClientCertMode for details of each available mode.
	 * @param aClientCertMode	The client certificate mode to use.
	 * @return					Any one of the system error codes, or KErrNone on success. */
	virtual TInt SetClientCertMode(const TClientCertMode aClientCertMode) = 0;

	 /**
	 * Set the untrusted certificate dialog mode.
	 *
	 * Determines if a dialog is displayed when an untrusted certificate is received.
	 *
	 * @see TDialogMode for details of each available mode.
	 * @param aDialogMode	The dialog mode to use.
	 * @return				Any one of the system error codes, or KErrNone on success. */
	virtual TInt SetDialogMode(const TDialogMode aDialogMode) = 0;

	 /** 
	 * Sets a socket option. 
	 *
	 * Secure socket implementations may provide options that can be set with this method.
	 * See individual implementation notes for details.
	 *
	 * @param aOptionName	An integer constant which identifies an option.
	 * @param aOptionLevel	An integer constant which identifies level of an option: 
	 *						i.e. an option level groups related options together.
	 * @param aOption		Option value packaged in a descriptor
	 * @return				Any one of the system error codes, or KErrNone on success. */
	virtual TInt SetOpt(TUint aOptionName,TUint aOptionLevel, const TDesC8& aOption=KNullDesC8()) = 0;
																					   
	 /** 
	 * Sets an option.
	 *
	 * SecureSocket implementations may provide options that can be set with this method.
	 * See individual implementation notes for details.
	 *
	 * @param aOptionName	An integer constant which identifies an option.
	 * @param aOptionLevel	An integer constant which identifies level of an option: 
	 *						i.e. an option level groups related options together.
	 * @param aOption		Option value as an integer
	 * @return				Any one of the system error codes, or KErrNone on success. */
	virtual TInt SetOpt(TUint aOptionName,TUint aOptionLevel,TInt anOption) = 0;

	 /**
	 * Set a specific protocol/version to use.
	 *
	 * This method can be used to select a particular protocol version to use in 
	 * implementations that support different protocols/versions.
	 * See individual implementation notes for details.
	 *
	 * @param aProtocol A reference to a descriptor containing the protocol name/version to use.
	 * @return			KErrNone if successful, a system-wide error code if not. */
	virtual TInt SetProtocol(const TDesC& aProtocol) = 0;

	 /**
	 * Set the server certificate.
	 *
	 * When acting in server mode, this method will set the certificate that is to be used 
	 * as the server certificate.
	 * When acting in client mode, this method will perform no action, but will return KErrNotSupported.
	 *
	 * @param aCert The certificate to use.
	 * @return		Any one of the system error codes, or KErrNone on success. */
	virtual TInt SetServerCert(const CX509Certificate& aCert) = 0;

	 /**
	 * Start acting as a client and initiate a handshake with the remote server.
	 *
	 * This is an asynchronous call, and will only complete when the handshake completes 
	 * and the secure connection is established, or it fails.
	 *
	 * @param aStatus On completion, any one of the system error codes, or KErrNone on success. */
	virtual void StartClientHandshake(TRequestStatus& aStatus) = 0;

	 /**
	 * Start acting as a server and listen for a handshake from the remote client.
	 *
	 * This is an asynchronous call, and will only complete when a client completes the 
	 * handshake, or if it fails. Normally, the socket passed in will usually have been 
	 * previously used in a call to Accept() on a listening socket, but this is not required. 
	 *
	 * @param aStatus On completion, any one of the system error codes, or KErrNone on success. */
	virtual void StartServerHandshake(TRequestStatus& aStatus) = 0;

	/** Standard destructor. */
	virtual ~MSecureSocket() {};

	};

#endif // __SECURESOCKETINTERFACE_H__