![[Index]](../../../../a_stock/images/btn_index.gif)
![[Previous]](../../../../a_stock/images/btn_prev_top.gif)
![[Next]](../../../../a_stock/images/btn_next_top.gif)
|
|
|
|
|
|
||
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:
static MSecureSocket* NewL( RSocket& aSocket, const TDesC& aProtocol );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
Defined in MSecureSocket:
AvailableCipherSuites(TDes8 &)Gets the list of cipher suites that are available to use. The list of cipher sui...CancelAll()Cancels all outstanding operations. This method will cancel all outstanding oper...CancelHandshake()Cancels an outstanding handshake operation. This method is used to cancel the St...CancelRecv()Cancels any outstanding read operation. See individual implementation notes for ...CancelSend()Cancels any outstanding send operation. See individual implementation notes for ...ClientCert()Gets the current client certificate.ClientCertMode()Returns the current client certificate mode. The client certificate mode is used...Close()Closes the secure connection. Implementations should terminate the secure connec...CurrentCipherSuite(TDes8 &)Gets the current cipher suite in use. The current cipher suite is returned in th...DialogMode()Gets the current dialog mode. FlushSessionCache()Flushes the session cache.GetOpt(TUint,TUint,TDes8 &)Gets an option.GetOpt(TUint,TUint,TInt &)Gets an option.Protocol(TDes &)Get the protocol in use.Recv(TDes8 &,TRequestStatus &)Receives data from the socket.RecvOneOrMore(TDes8 &,TRequestStatus &,TSockXfrLength &)Receives data from the socket.RenegotiateHandshake(TRequestStatus &)Initiates a renegotiation of the secure connection.Send(const TDesC8 &,TRequestStatus &)Send data over the socket.Send(const TDesC8 &,TRequestStatus &,TSockXfrLength &)Send data over the socket.ServerCert()Gets the current server certificate.SetAvailableCipherSuites(const TDesC8 &)Sets a list of cipher suites that are available to use.SetClientCert(const CX509Certificate &)Sets the client certificate to use.SetClientCertMode(const TClientCertMode)Set the client certificate mode.SetDialogMode(const TDialogMode)Set the untrusted certificate dialog mode.SetOpt(TUint,TUint,TInt)Sets an option.SetOpt(TUint,TUint,const TDesC8 &)Sets a socket option.SetProtocol(const TDesC &)Set a specific protocol/version to use.SetServerCert(const CX509Certificate &)Set the server certificate.StartClientHandshake(TRequestStatus &)Start acting as a client and initiate a handshake with the remote server.StartServerHandshake(TRequestStatus &)Start acting as a server and listen for a handshake from the remote client.~MSecureSocket()Standard destructor. |
|
virtual TInt AvailableCipherSuites(TDes8 &aCiphers)=0;
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.
|
|
virtual void CancelAll()=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 CancelHandshake()=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 CancelRecv()=0;
Cancels any outstanding read operation. See individual implementation notes for behaviour after canceling.
virtual void CancelSend()=0;
Cancels any outstanding send operation. See individual implementation notes for behaviour after canceling.
virtual const CX509Certificate* ClientCert()=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.
|
virtual TClientCertMode ClientCertMode()=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.
|
![[Top]](../../../../a_stock/images/arrow_up_2.gif){kind=icon}
TClientCertModeServer client certificate mode. Specifies if client certificates will be asked f...virtual void Close()=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 TInt CurrentCipherSuite(TDes8 &aCipherSuite)=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.
|
|
virtual TDialogMode DialogMode()=0;
Gets the current dialog mode.
|
TDialogModeUntrusted certificate dialog mode. When an untrusted certificate is received, th...virtual void FlushSessionCache()=0;
Flushes the session cache.
If protocols implement a session cache, this method will cause that cache to be flushed.
virtual TInt GetOpt(TUint aOptionName, TUint aOptionLevel, TDes8 &aOption)=0;
Gets an option.
SecureSocket implementations may provide options that can be read with this method. See individual implementation notes for details.
|
|
virtual TInt GetOpt(TUint aOptionName, TUint aOptionLevel, TInt &aOption)=0;
Gets an option.
Secure socket implementations may provide options that can be read with this method. See individual implementation notes for details.
|
|
virtual TInt Protocol(TDes &aProtocol)=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.
|
|
virtual void Recv(TDes8 &aDesc, TRequestStatus &aStatus)=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.
|
virtual void RecvOneOrMore(TDes8 &aDesc, TRequestStatus &aStatus, TSockXfrLength &aLen)=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.
|
virtual void RenegotiateHandshake(TRequestStatus &aStatus)=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.
|
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.
|
virtual void Send(const TDesC8 &aDesc, TRequestStatus &aStatus, TSockXfrLength &aLen)=0;
Send data over the socket.
This is an asynchronous call. Only one Send operation can be outstanding at any time.
|
virtual const CX509Certificate* ServerCert()=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.
|
virtual TInt SetAvailableCipherSuites(const TDesC8 &aCiphers)=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.
|
|
virtual TInt SetClientCert(const CX509Certificate &aCert)=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.
|
|
virtual TInt SetClientCertMode(const TClientCertMode aClientCertMode)=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.
|
|
TClientCertModeServer client certificate mode. Specifies if client certificates will be asked f...virtual TInt SetDialogMode(const TDialogMode aDialogMode)=0;
Set the untrusted certificate dialog mode.
Determines if a dialog is displayed when an untrusted certificate is received.
|
|
TDialogModeUntrusted certificate dialog mode. When an untrusted certificate is received, th...virtual TInt SetOpt(TUint aOptionName, TUint aOptionLevel, const TDesC8 &aOption=KNullDesC8())=0;
Sets a socket option.
Secure socket implementations may provide options that can be set with this method. See individual implementation notes for details.
|
|
virtual TInt SetOpt(TUint aOptionName, TUint aOptionLevel, TInt anOption)=0;
Sets an option.
SecureSocket implementations may provide options that can be set with this method. See individual implementation notes for details.
|
|
virtual TInt SetProtocol(const TDesC &aProtocol)=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.
|
|
virtual TInt SetServerCert(const CX509Certificate &aCert)=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.
|
|
virtual void StartClientHandshake(TRequestStatus &aStatus)=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.
|
virtual void StartServerHandshake(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.
|
|
Copyright © 2005-2008 Symbian Software Ltd. |
|
![[Previous]](../../../../a_stock/images/btn_prev.gif)
![[Top]](../../../../a_stock/images/btn_top.gif)
![[Next]](../../../../a_stock/images/btn_next.gif)