Qt Cryptographic Architecture: QCA::SASL Class Reference

Qt Cryptographic Architecture

Classes | Public Types | Signals | Public Member Functions | Friends | List of all members
QCA::SASL Class Reference
QCA user API

`#include <QtCrypto>`

Collaboration diagram for QCA::SASL:
[legend]

## Classes
class | Params

## 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 ()
Signals inherited from QCA::SecureLayer
void | closed ()
void | error ()
void | readyRead ()
void | readyReadOutgoing ()

## 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)
void | putServerFirstStep (const QString &mech, const QByteArray &clientInit)
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, SecurityLevel s=SL_None)
void | setConstraints (AuthFlags f, int minSSF, int maxSSF)
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)
Public Member Functions inherited from QCA::SecureLayer
virtual void | close ()
virtual bool | isClosable () const
virtual QByteArray | readUnprocessed ()
| SecureLayer (QObject *parent=0)
Public Member Functions inherited from QCA::Algorithm
| Algorithm (const Algorithm &from)
void | change (Provider::Context *c)
void | change (const QString &type, const QString &provider)
Provider::Context * | context ()
const Provider::Context * | context () const
Algorithm & | operator= (const Algorithm &from)
Provider * | provider () const
Provider::Context * | takeContext ()
QString | type () const

## Friends
class | Private

## Additional Inherited Members
Protected Member Functions inherited from QCA::Algorithm
| Algorithm ()
| Algorithm (const QString &type, const QString &provider)

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

## ◆ Error

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

## ◆ AuthCondition

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)

## ◆ AuthFlags

enum QCA::SASL::AuthFlags

Authentication requirement flag values.

## ◆ ClientSendMode

enum QCA::SASL::ClientSendMode

Mode options for client side sending.

## ◆ ServerSendMode

enum QCA::SASL::ServerSendMode

Mode options for server side sending.

## Constructor & Destructor Documentation

## ◆ SASL()

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

## ◆ reset()

void QCA::SASL::reset | ( |  | ) |

Reset the SASL mechanism.

## ◆ setConstraints() [1/2]

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.

Examples:
  saslclient.cpp, and saslserver.cpp.

## ◆ setConstraints() [2/2]

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

## ◆ setLocalAddress()

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

## ◆ setRemoteAddress()

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

## ◆ setExternalAuthId()

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

Specify the id of the externally secured connection.

Parameters

  authid | the id of the connection

## ◆ setExternalSSF()

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

## ◆ startClient()

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

Examples:
  saslclient.cpp.

## ◆ startServer()

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

Examples:
  saslserver.cpp.

## ◆ putServerFirstStep() [1/2]

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.

Examples:
  saslserver.cpp.

## ◆ putServerFirstStep() [2/2]

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

## ◆ putStep()

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

Examples:
  saslclient.cpp, and saslserver.cpp.

## ◆ mechanism()

QString QCA::SASL::mechanism | ( |  | ) | const

Return the mechanism selected (client)

Examples:
  saslclient.cpp.

## ◆ mechanismList()

QStringList QCA::SASL::mechanismList | ( |  | ) | const

Return the mechanism list (server)

Examples:
  saslserver.cpp.

## ◆ realmList()

QStringList QCA::SASL::realmList | ( |  | ) | const

Return the realm list, if available (client)

Examples:
  saslclient.cpp.

## ◆ ssf()

int QCA::SASL::ssf | ( |  | ) | const

Return the security strength factor of the connection.

Examples:
  saslclient.cpp, and saslserver.cpp.

## ◆ errorCode()

Error QCA::SASL::errorCode | ( |  | ) | const

Return the error code.

Examples:
  saslclient.cpp, and saslserver.cpp.

## ◆ authCondition()

AuthCondition QCA::SASL::authCondition | ( |  | ) | const

Return the reason for authentication failure.

Examples:
  saslclient.cpp, and saslserver.cpp.

## ◆ setUsername()

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

Specify the username to use in authentication.

Parameters

  user | the username to use

Examples:
  saslclient.cpp.

## ◆ setAuthzid()

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

Specify the authorization identity to use in authentication.

Parameters

  auth | the authorization identity to use

Examples:
  saslclient.cpp.

## ◆ setPassword()

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

Specify the password to use in authentication.

Parameters

  pass | the password to use

Examples:
  saslclient.cpp.

## ◆ setRealm()

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

Specify the realm to use in authentication.

Parameters

  realm | the realm to use

Examples:
  saslclient.cpp.

## ◆ continueAfterParams()

void QCA::SASL::continueAfterParams | ( |  | ) |

Continue negotiation after parameters have been set (client)

Examples:
  saslclient.cpp.

## ◆ continueAfterAuthCheck()

void QCA::SASL::continueAfterAuthCheck | ( |  | ) |

Continue negotiation after auth ids have been checked (server)

Examples:
  saslserver.cpp.

## ◆ bytesAvailable()

virtual int QCA::SASL::bytesAvailable | ( |  | ) | const
| virtual

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

Implements QCA::SecureLayer.

## ◆ bytesOutgoingAvailable()

virtual int QCA::SASL::bytesOutgoingAvailable | ( |  | ) | const
| virtual

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

Implements QCA::SecureLayer.

## ◆ write()

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.

Examples:
  saslclient.cpp, and saslserver.cpp.

## ◆ read()

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.

Examples:
  saslclient.cpp, and saslserver.cpp.

## ◆ writeIncoming()

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.

Examples:
  saslclient.cpp.

## ◆ readOutgoing()

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.

Examples:
  saslclient.cpp, and saslserver.cpp.

## ◆ convertBytesWritten()

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.

Examples:
  saslserver.cpp.

## ◆ clientStarted

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.

## ◆ serverStarted

void QCA::SASL::serverStarted | ( |  | ) |
| signal

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

## ◆ nextStep

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

## ◆ needParams

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

## ◆ authCheck

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

## ◆ authenticated

void QCA::SASL::authenticated | ( |  | ) |
| signal

This signal is emitted when authentication is complete.

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

- qca_securelayer.h