Qt Cryptographic Architecture: QCA::SASL Class Reference

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.

Member Enumeration Documentation

enum QCA::SASL::Error

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

enum QCA::SASL::AuthCondition

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).

enum QCA::SASL::AuthFlags

Authentication requirement flag values.

enum QCA::SASL::ClientSendMode

Mode options for client side sending.

enum QCA::SASL::ServerSendMode

Mode options for server side sending.

Constructor & Destructor Documentation

QCA::SASL::SASL	(	QObject *	parent = `0`,
		const QString &	provider = `QString()`
	)

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::reset ( )

Reset the SASL mechanism.

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::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::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::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::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::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

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.

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.

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.

QString QCA::SASL::mechanism ( ) const

Return the mechanism selected (client).

QStringList QCA::SASL::mechanismList ( ) const

Return the mechanism list (server).

QStringList QCA::SASL::realmList ( ) const

Return the realm list, if available (client).

int QCA::SASL::ssf ( ) const

Return the security strength factor of the connection.

Error QCA::SASL::errorCode ( ) const

Return the error code.

AuthCondition QCA::SASL::authCondition ( ) const

Return the reason for authentication failure.

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

Specify the username to use in authentication.

Parameters:

user

the username to use

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::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::continueAfterParams ( )

Continue negotiation after parameters have been set (client).

void QCA::SASL::continueAfterAuthCheck ( )

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

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.

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.

Implements QCA::SecureLayer.

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 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.

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.

Implements QCA::SecureLayer.

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

Convert encrypted bytes written to plain text bytes written.

Implements QCA::SecureLayer.

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

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

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

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

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::needParams ( const QCA::SASL::Params & params ) [signal]

This signal is emitted when the client needs additional parameters.

Set parameter values as necessary and then call continueAfterParams().

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().

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

This signal is emitted when authentication is complete.


Public Types
enum	Error { ErrorInit, ErrorHandshake, ErrorCrypt }
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	ServerSendMode { AllowServerSendLast, DisableServerSendLast }
Signals
void	clientStarted (bool clientInit, const QByteArray &clientInitData)
void	serverStarted ()
void	nextStep (const QByteArray &stepData)
void	needParams (const QCA::SASL::Params &params)
void	authCheck (const QString &user, const QString &authzid)
void	authenticated ()
Public Member Functions
	SASL (QObject *parent=0, const QString &provider=QString())
void	reset ()
void	setConstraints (AuthFlags f, SecurityLevel s=SL_None)
void	setConstraints (AuthFlags f, int minSSF, int maxSSF)
void	setLocalAddress (const QString &addr, quint16 port)
void	setRemoteAddress (const QString &addr, quint16 port)
void	setExternalAuthId (const QString &authid)
void	setExternalSSF (int strength)
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)
void	putServerFirstStep (const QString &mech)
void	putServerFirstStep (const QString &mech, const QByteArray &clientInit)
void	putStep (const QByteArray &stepData)
QString	mechanism () const
QStringList	mechanismList () const
QStringList	realmList () const
int	ssf () const
Error	errorCode () const
AuthCondition	authCondition () const
void	setUsername (const QString &user)
void	setAuthzid (const QString &auth)
void	setPassword (const SecureArray &pass)
void	setRealm (const QString &realm)
void	continueAfterParams ()
void	continueAfterAuthCheck ()
virtual int	bytesAvailable () const
virtual int	bytesOutgoingAvailable () const
virtual void	write (const QByteArray &a)
virtual QByteArray	read ()
virtual void	writeIncoming (const QByteArray &a)
virtual QByteArray	readOutgoing (int *plainBytes=0)
virtual int	convertBytesWritten (qint64 encryptedBytes)
Friends
class	Private
Classes
class	Params
	Parameter flags for the SASL authentication. More...

QCA::SASL Class Reference
[QCA user API]

Public Types

Signals

Public Member Functions

Friends

Classes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

QCA::SASL Class Reference [QCA user API]

Public Types

Signals

Public Member Functions

Friends

Classes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

QCA::SASL Class Reference
[QCA user API]