QCA::SASL Class Reference
[QCA user API]

Simple Authentication and Security Layer protocol implementation. More...

#include <QtCrypto>

Inheritance diagram for QCA::SASL:

QCA::SecureLayer QCA::Algorithm QObject
Collaboration diagram for QCA::SASL:

Collaboration graph
[legend]

List of all members.

Public Types

enum  AuthCondition {
  AuthFail, NoMechanism, BadProtocol, BadServer,
  BadAuth, NoAuthzid, TooWeak, NeedEncrypt,
  Expired, Disabled, NoUser, RemoteUnavailable
}
enum  AuthFlags {
  AuthFlagsNone = 0x00, AllowPlain = 0x01, AllowAnonymous = 0x02, RequireForwardSecrecy = 0x04,
  RequirePassCredentials = 0x08, RequireMutualAuth = 0x10, RequireAuthzidSupport = 0x20
}
enum  ClientSendMode { AllowClientSendFirst, DisableClientSendFirst }
enum  Error { ErrorInit, ErrorHandshake, ErrorCrypt }
enum  ServerSendMode { AllowServerSendLast, DisableServerSendLast }

Signals

void authCheck (const QString &user, const QString &authzid)
void authenticated ()
void clientStarted (bool clientInit, const QByteArray &clientInitData)
void needParams (const QCA::SASL::Params &params)
void nextStep (const QByteArray &stepData)
void serverStarted ()

Public Member Functions

AuthCondition authCondition () const
virtual int bytesAvailable () const
virtual int bytesOutgoingAvailable () const
void continueAfterAuthCheck ()
void continueAfterParams ()
virtual int convertBytesWritten (qint64 encryptedBytes)
Error errorCode () const
QString mechanism () const
QStringList mechanismList () const
void putServerFirstStep (const QString &mech, const QByteArray &clientInit)
void putServerFirstStep (const QString &mech)
void putStep (const QByteArray &stepData)
virtual QByteArray read ()
virtual QByteArray readOutgoing (int *plainBytes=0)
QStringList realmList () const
void reset ()
 SASL (QObject *parent=0, const QString &provider=QString())
void setAuthzid (const QString &auth)
void setConstraints (AuthFlags f, int minSSF, int maxSSF)
void setConstraints (AuthFlags f, SecurityLevel s=SL_None)
void setExternalAuthId (const QString &authid)
void setExternalSSF (int strength)
void setLocalAddress (const QString &addr, quint16 port)
void setPassword (const SecureArray &pass)
void setRealm (const QString &realm)
void setRemoteAddress (const QString &addr, quint16 port)
void setUsername (const QString &user)
int ssf () const
void startClient (const QString &service, const QString &host, const QStringList &mechlist, ClientSendMode mode=AllowClientSendFirst)
void startServer (const QString &service, const QString &host, const QString &realm, ServerSendMode mode=DisableServerSendLast)
virtual void write (const QByteArray &a)
virtual void writeIncoming (const QByteArray &a)

Friends

class Private

Classes

class  Params
 Parameter flags for the SASL authentication. More...


Detailed Description

Simple Authentication and Security Layer protocol implementation.

This class implements the Simple Authenication and Security Layer protocol, which is described in RFC2222 - see http://www.ietf.org/rfc/rfc2222.txt.

As the name suggests, SASL provides authentication (eg, a "login" of some form), for a connection oriented protocol, and can also provide protection for the subsequent connection.

The SASL protocol is designed to be extensible, through a range of "mechanisms", where a mechanism is the actual authentication method. Example mechanisms include Anonymous, LOGIN, Kerberos V4, and GSSAPI. Mechanisms can be added (potentially without restarting the server application) by the system administrator.

It is important to understand that SASL is neither "network aware" nor "protocol aware". That means that SASL does not understand how the client connects to the server, and SASL does not understand the actual application protocol.

Examples:

saslclient.cpp, and saslserver.cpp.


Member Enumeration Documentation

Possible authentication error states.

Enumerator:
AuthFail  Generic authentication failure.
NoMechanism  No compatible/appropriate authentication mechanism.
BadProtocol  Bad protocol or cancelled.
BadServer  Server failed mutual authentication (client side only).
BadAuth  Authentication failure (server side only).
NoAuthzid  Authorization failure (server side only).
TooWeak  Mechanism too weak for this user (server side only).
NeedEncrypt  Encryption is needed in order to use mechanism (server side only).
Expired  Passphrase expired, has to be reset (server side only).
Disabled  Account is disabled (server side only).
NoUser  User not found (server side only).
RemoteUnavailable  Remote service needed for auth is gone (server side only).

Authentication requirement flag values.

Mode options for client side sending.

Possible errors that may occur when using SASL.

Enumerator:
ErrorInit  problem starting up SASL
ErrorHandshake  problem during the authentication process
ErrorCrypt  problem at anytime after

Mode options for server side sending.


Constructor & Destructor Documentation

QCA::SASL::SASL ( QObject parent = 0,
const QString provider = QString() 
) [explicit]

Standard constructor.

Parameters:
parent the parent object for this SASL connection
provider if specified, the provider to use. If not specified, or specified as empty, then any provider is acceptable.


Member Function Documentation

void QCA::SASL::authCheck ( const QString user,
const QString authzid 
) [signal]

This signal is emitted when the server needs to perform the authentication check.

If the user and authzid are valid, call continueAfterAuthCheck().

Parameters:
user the user identification name
authzid the user authorization name

AuthCondition QCA::SASL::authCondition (  )  const

Return the reason for authentication failure.

void QCA::SASL::authenticated (  )  [signal]

This signal is emitted when authentication is complete.

virtual int QCA::SASL::bytesAvailable (  )  const [virtual]

Returns the number of bytes available to be read() on the application side.

Implements QCA::SecureLayer.

virtual int QCA::SASL::bytesOutgoingAvailable (  )  const [virtual]

Returns the number of bytes available to be readOutgoing() on the network side.

Implements QCA::SecureLayer.

void QCA::SASL::clientStarted ( bool  clientInit,
const QByteArray clientInitData 
) [signal]

This signal is emitted when the client has been successfully started.

Parameters:
clientInit true if the client should send an initial response to the server
clientInitData the initial response to send to the server. Do note that there is a difference in SASL between an empty initial response and no initial response, and so even if clientInitData is an empty array, you still need to send an initial response if clientInit is true.

void QCA::SASL::continueAfterAuthCheck (  ) 

Continue negotiation after auth ids have been checked (server).

void QCA::SASL::continueAfterParams (  ) 

Continue negotiation after parameters have been set (client).

virtual int QCA::SASL::convertBytesWritten ( qint64  encryptedBytes  )  [virtual]

Convert encrypted bytes written to plain text bytes written.

Parameters:
encryptedBytes the number of bytes to convert

Implements QCA::SecureLayer.

Error QCA::SASL::errorCode (  )  const

Return the error code.

QString QCA::SASL::mechanism (  )  const

Return the mechanism selected (client).

QStringList QCA::SASL::mechanismList (  )  const

Return the mechanism list (server).

void QCA::SASL::needParams ( const QCA::SASL::Params params  )  [signal]

This signal is emitted when the client needs additional parameters.

After receiving this signal, the application should set the required parameter values appropriately and then call continueAfterParams().

Parameters:
params the parameters that are required by the client

void QCA::SASL::nextStep ( const QByteArray stepData  )  [signal]

This signal is emitted when there is data required to be sent over the network to complete the next step in the authentication process.

Parameters:
stepData the data to send over the network

void QCA::SASL::putServerFirstStep ( const QString mech,
const QByteArray clientInit 
)

Process the first step in server mode (server).

Call this with the mechanism selected by the client, and initial client data. If there is no initial client data, call the other version of this function instead.

Parameters:
mech the mechanism to be used
clientInit the initial data provided by the client side

void QCA::SASL::putServerFirstStep ( const QString mech  ) 

Process the first step in server mode (server).

Call this with the mechanism selected by the client. If there is initial client data, call the other version of this function instead.

Parameters:
mech the mechanism to be used.

void QCA::SASL::putStep ( const QByteArray stepData  ) 

Process an authentication step.

Call this with authentication data received from the network. The only exception is the first step in server mode, in which case putServerFirstStep must be called.

Parameters:
stepData the authentication data from the network

virtual QByteArray QCA::SASL::read (  )  [virtual]

This method reads decrypted (plain) data from the SecureLayer implementation.

You normally call this function on the application side after receiving the readyRead() signal.

Implements QCA::SecureLayer.

virtual QByteArray QCA::SASL::readOutgoing ( int *  plainBytes = 0  )  [virtual]

This method provides encoded (typically encrypted) data.

You normally call this function to get data to write out to the network socket (e.g. using QTcpSocket::write()) after receiving the readyReadOutgoing() signal.

Parameters:
plainBytes the number of bytes that were read.

Implements QCA::SecureLayer.

QStringList QCA::SASL::realmList (  )  const

Return the realm list, if available (client).

void QCA::SASL::reset (  ) 

Reset the SASL mechanism.

void QCA::SASL::serverStarted (  )  [signal]

This signal is emitted after the server has been successfully started.

void QCA::SASL::setAuthzid ( const QString auth  ) 

Specify the authorization identity to use in authentication.

Parameters:
auth the authorization identity to use

void QCA::SASL::setConstraints ( AuthFlags  f,
int  minSSF,
int  maxSSF 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Unless you have a specific reason for directly specifying a strength factor, you probably should use the method above.

Parameters:
f the authentication requirements, which you typically build using a binary OR function (eg AllowPlain | AllowAnonymous)
minSSF the minimum security strength factor that is required
maxSSF the maximum security strength factor that is required
Note:
Security strength factors are a rough approximation to key length in the encryption function (eg if you are securing with plain DES, the security strength factor would be 56).

void QCA::SASL::setConstraints ( AuthFlags  f,
SecurityLevel  s = SL_None 
)

Specify connection constraints.

SASL supports a range of authentication requirements, and a range of security levels. This method allows you to specify the requirements for your connection.

Parameters:
f the authentication requirements, which you typically build using a binary OR function (eg AllowPlain | AllowAnonymous)
s the security level of the encryption, if used. See SecurityLevel for details of what each level provides.

void QCA::SASL::setExternalAuthId ( const QString authid  ) 

Specify the id of the externally secured connection.

Parameters:
authid the id of the connection

void QCA::SASL::setExternalSSF ( int  strength  ) 

Specify a security strength factor for an externally secured connection.

Parameters:
strength the security strength factor of the connection

void QCA::SASL::setLocalAddress ( const QString addr,
quint16  port 
)

Specify the local address.

Parameters:
addr the address of the local part of the connection
port the port number of the local part of the connection

void QCA::SASL::setPassword ( const SecureArray pass  ) 

Specify the password to use in authentication.

Parameters:
pass the password to use

void QCA::SASL::setRealm ( const QString realm  ) 

Specify the realm to use in authentication.

Parameters:
realm the realm to use

void QCA::SASL::setRemoteAddress ( const QString addr,
quint16  port 
)

Specify the peer address.

Parameters:
addr the address of the peer side of the connection
port the port number of the peer side of the connection

void QCA::SASL::setUsername ( const QString user  ) 

Specify the username to use in authentication.

Parameters:
user the username to use

int QCA::SASL::ssf (  )  const

Return the security strength factor of the connection.

void QCA::SASL::startClient ( const QString service,
const QString host,
const QStringList mechlist,
ClientSendMode  mode = AllowClientSendFirst 
)

Initialise the client side of the connection.

startClient must be called on the client side of the connection. clientStarted will be emitted when the operation is completed.

Parameters:
service the name of the service
host the client side host name
mechlist the list of mechanisms which can be used
mode the mode to use on the client side

void QCA::SASL::startServer ( const QString service,
const QString host,
const QString realm,
ServerSendMode  mode = DisableServerSendLast 
)

Initialise the server side of the connection.

startServer must be called on the server side of the connection. serverStarted will be emitted when the operation is completed.

Parameters:
service the name of the service
host the server side host name
realm the realm to use
mode which mode to use on the server side

virtual void QCA::SASL::write ( const QByteArray a  )  [virtual]

This method writes unencrypted (plain) data to the SecureLayer implementation.

You normally call this function on the application side.

Parameters:
a the source of the application-side data

Implements QCA::SecureLayer.

virtual void QCA::SASL::writeIncoming ( const QByteArray a  )  [virtual]

This method accepts encoded (typically encrypted) data for processing.

You normally call this function using data read from the network socket (e.g. using QTcpSocket::readAll()) after receiving a signal that indicates that the socket has data to read.

Parameters:
a the ByteArray to take network-side data from

Implements QCA::SecureLayer.


The documentation for this class was generated from the following file:

Generated on Wed Apr 29 15:16:09 2009 for Qt Cryptographic Architecture by  doxygen 1.5.5