~ubuntu-branches/ubuntu/wily/qca2/wily-proposed : revision 5

41

/**

42

Specify the lower-bound for acceptable TLS/SASL security layers

43

44

For TLS, the intepretation of these levels is:

44

For TLS, the interpretation of these levels is:

45

- Any cipher suite that provides non-authenticated communications

46

(usually anonymous Diffie-Hellman) is SL_Integrity.

47

- Any cipher suite that is limited to 40 bits (export-version

97

activities (which require network traffic to agree a

98

configuration to use) and other overheads associated with

99

the secure link.

100

101

\ingroup UserAPI

100

102

*/

101

103

class QCA_EXPORT SecureLayer : public QObject

102

104

{

140

142

This method writes unencrypted (plain) data to

141

143

the SecureLayer implementation. You normally

142

144

call this function on the application side.

145

146

\param a the source of the application-side data

143

147

*/

144

148

virtual void write(const QByteArray &a) = 0;

145

149

157

161

data read from the network socket (e.g. using

158

162

QTcpSocket::readAll()) after receiving a signal that

159

163

indicates that the socket has data to read.

164

165

\param a the ByteArray to take network-side data from

160

166

*/

161

167

virtual void writeIncoming(const QByteArray &a) = 0;

162

168

166

172

to write out to the network socket (e.g. using

167

173

QTcpSocket::write()) after receiving the

168

174

readyReadOutgoing() signal.

175

176

\param plainBytes the number of bytes that were read.

169

177

*/

170

178

virtual QByteArray readOutgoing(int *plainBytes = 0) = 0;

171

179

180

188

181

189

/**

182

190

Convert encrypted bytes written to plain text bytes written

191

192

\param encryptedBytes the number of bytes to convert

183

193

*/

184

194

virtual int convertBytesWritten(qint64 encryptedBytes) = 0;

185

195

217

227

};

218

228

219

229

/**

230

\class TLSSession qca_securelayer.h QtCrypto

231

220

232

Session token, used for TLS resuming

233

234

\ingroup UserAPI

235

221

236

*/

222

237

class QCA_EXPORT TLSSession : public Algorithm

223

238

{

224

239

public:

225

240

TLSSession();

241

242

/**

243

Copy constructor

244

245

\param from the session token to copy from

246

*/

226

247

TLSSession(const TLSSession &from);

248

227

249

~TLSSession();

250

251

/**

252

Assignment operator

253

254

\param from the session token to assign from

255

*/

228

256

TLSSession & operator=(const TLSSession &from);

229

257

258

/**

259

Test if the session token is valid

260

*/

230

261

bool isNull() const;

231

262

};

232

263

249

280

Socket Layer (SSL version 2 and SSL version 3). New

250

281

applications should use at least TLS 1.0, and SSL version 2

251

282

should be avoided due to known security problems.

283

284

\ingroup UserAPI

252

285

*/

253

286

class QCA_EXPORT TLS : public SecureLayer, public Algorithm

254

287

{

312

345

explicit TLS(QObject *parent = 0, const QString &provider = QString());

313

346

314

347

/**

315

Constructor for Transport Layer Security connection

348

Constructor for Transport Layer Security connection.

349

350

This constructor can be used for both normal %TLS (set mode to TLS::Stream)

351

or DTLS (set mode to TLS::Datagram).

316

352

317

353

\param mode the connection Mode

318

354

\param parent the parent object for this object

366

402

\overload

367

403

368

404

Allows setting a certificate from a KeyBundle.

405

406

\param kb key bundle containing the local certificate

407

and associated private key.

369

408

*/

370

409

void setCertificate(const KeyBundle &kb);

371

410

443

482

/**

444

483

Sets the issuer list to present to the client. For

445

484

use with servers only. Only DN types are allowed.

485

486

\param issuers the list of valid issuers to be used.

446

487

*/

447

488

void setIssuerList(const QList<CertificateInfoOrdered> &issuers);

448

489

449

490

/**

450

Resume a TLS session using the given session object

491

Resume a %TLS session using the given session object

492

493

\param session the session state to use for resumption.

451

494

*/

452

495

void setSession(const TLSSession &session);

453

496

490

533

QString hostName() const;

491

534

492

535

/**

493

Start the TLS/SSL connection as a client

536

Start the %TLS/SSL connection as a client

494

537

495

538

Typically, you'll want to perform RFC 2818 validation on the

496

539

server's certificate, based on the hostname you're intending

511

554

void startClient(const QString &host = QString());

512

555

513

556

/**

514

Start the TLS/SSL connection as a server.

557

Start the %TLS/SSL connection as a server.

515

558

*/

516

559

void startServer();

517

560

518

561

/**

519

Resumes TLS processing.

562

Resumes %TLS processing.

520

563

521

Call this function after hostNameReceived(),

522

certificateRequested() or handshaken() is emitted. By requiring

523

this function to be called in order to proceed, applications are

524

given a chance to perform user interaction between steps in the

525

TLS process.

564

Call this function after hostNameReceived(), certificateRequested()

565

peerCertificateAvailable() or handshaken() is emitted. By

566

requiring this function to be called in order to proceed,

567

applications are given a chance to perform user interaction between

568

steps in the %TLS process.

526

569

*/

527

570

void continueAfterStep();

528

571

575

618

int cipherMaxBits() const;

576

619

577

620

/**

578

The session object of the TLS connection, which can be used

621

The session object of the %TLS connection, which can be used

579

622

for resuming.

580

623

*/

581

624

TLSSession session() const;

588

631

Error errorCode() const;

589

632

590

633

/**

591

After the SSL/TLS handshake is complete, this

634

After the SSL/%TLS handshake is complete, this

592

635

method allows you to determine if the other end

593

636

of the connection (if the application is a client,

594

637

this is the server; if the application is a server,

595

638

this is the client) has a valid identity.

596

639

597

Note that the security of TLS/SSL depends on

640

Note that the security of %TLS/SSL depends on

598

641

checking this. It is not enough to check that the

599

642

certificate is valid - you must check that the

600

643

certificate is valid for the entity that you are

607

650

IdentityResult peerIdentityResult() const;

608

651

609

652

/**

610

After the SSL/TLS handshake is valid, this method

653

After the SSL/%TLS handshake is valid, this method

611

654

allows you to check if the received certificate

612

655

from the other end is valid. As noted in

613

656

peerIdentityResult(), you also need to check that

683

726

Emitted if a host name is set by the client. At

684

727

this time, the server can inspect the hostName().

685

728

686

You must call continueAfterStep() in order for TLS

729

You must call continueAfterStep() in order for %TLS

687

730

processing to resume after this signal is emitted.

688

731

689

732

This signal is only emitted in server mode.

696

739

Emitted when the server requests a certificate. At

697

740

this time, the client can inspect the issuerList().

698

741

699

You must call continueAfterStep() in order for TLS

742

You must call continueAfterStep() in order for %TLS

700

743

processing to resume after this signal is emitted.

701

744

702

745

This signal is only emitted in client mode.

706

749

void certificateRequested();

707

750

708

751

/**

752

Emitted when a certificate is received from the peer.

753

At this time, you may inspect peerIdentityResult(),

754

peerCertificateValidity(), and peerCertificateChain().

755

756

You must call continueAfterStep() in order for %TLS

757

processing to resume after this signal is emitted.

758

759

\sa continueAfterStep

760

*/

761

void peerCertificateAvailable();

762

763

/**

709

764

Emitted when the protocol handshake is complete. At

710

this time, all available information about the TLS

765

this time, all available information about the %TLS

711

766

session can be inspected.

712

767

713

You must call continueAfterStep() in order for TLS

768

You must call continueAfterStep() in order for %TLS

714

769

processing to resume after this signal is emitted.

715

770

716

771

\sa continueAfterStep

719

774

void handshaken();

720

775

721

776

protected:

777

/**

778

Called when a connection is made to a particular signal

779

780

\param signal the name of the signal that has been

781

connected to.

782

*/

722

783

void connectNotify(const char *signal);

784

785

/**

786

Called when a connection is removed from a particular signal

787

788

\param signal the name of the signal that has been

789

disconnected from.

790

*/

723

791

void disconnectNotify(const char *signal);

724

792

725

793

private:

753

821

"protocol aware". That means that %SASL does not understand how the client

754

822

connects to the server, and %SASL does not understand the actual

755

823

application protocol.

824

825

\ingroup UserAPI

826

756

827

*/

757

828

class QCA_EXPORT SASL : public SecureLayer, public Algorithm

758

829

{

759

830

Q_OBJECT

760

831

public:

761

832

/**

762

Possible errors that may occur when using SASL

833

Possible errors that may occur when using %SASL

763

834

*/

764

835

enum Error

765

836

{

766

ErrorInit, ///< problem starting up SASL

837

ErrorInit, ///< problem starting up %SASL

767

838

ErrorHandshake, ///< problem during the authentication process

768

839

ErrorCrypt ///< problem at anytime after

769

840

};

822

893

/**

823

894

\class Params qca_securelayer.h QtCrypto

824

895

825

Parameter flags for the SASL authentication

896

Parameter flags for the %SASL authentication

826

897

827

This is used to indicate which parameters are needed by SASL

898

This is used to indicate which parameters are needed by %SASL

828

899

in order to complete the authentication process.

900

901

\ingroup UserAPI

829

902

*/

830

903

class QCA_EXPORT Params

831

904

{

888

961

/**

889

962

Standard constructor

890

963

891

\param parent the parent object for this SASL connection

964

\param parent the parent object for this %SASL connection

892

965

\param provider if specified, the provider to use. If not

893

966

specified, or specified as empty, then any provider is

894

967

acceptable.

895

968

*/

896

SASL(QObject *parent = 0, const QString &provider = QString());

969

explicit SASL(QObject *parent = 0, const QString &provider = QString());

970

897

971

~SASL();

898

972

899

973

/**

900

Reset the SASL mechanism

974

Reset the %SASL mechanism

901

975

*/

902

976

void reset();

903

977

904

978

/**

905

979

Specify connection constraints

906

980

907

SASL supports a range of authentication requirements, and

981

%SASL supports a range of authentication requirements, and

908

982

a range of security levels. This method allows you to

909

983

specify the requirements for your connection.

910

984

995

1069

Call this with the mechanism selected by the client. If there

996

1070

is initial client data, call the other version of this function

997

1071

instead.

1072

1073

\param mech the mechanism to be used.

998

1074

*/

999

1075

void putServerFirstStep(const QString &mech);

1000

1076

1004

1080

Call this with the mechanism selected by the client, and initial

1005

1081

client data. If there is no initial client data, call the other

1006

1082

version of this function instead.

1083

1084

\param mech the mechanism to be used

1085

\param clientInit the initial data provided by the client side

1007

1086

*/

1008

1087

void putServerFirstStep(const QString &mech, const QByteArray &clientInit);

1009

1088

1013

1092

Call this with authentication data received from the network.

1014

1093

The only exception is the first step in server mode, in which

1015

1094

case putServerFirstStep must be called.

1095

1096

\param stepData the authentication data from the network

1016

1097

*/

1017

1098

void putStep(const QByteArray &stepData);

1018

1099

1095

1176

1096

1177

Q_SIGNALS:

1097

1178

/**

1098

This signal is emitted when the client has been

1099

successfully started

1179

This signal is emitted when the client has been successfully

1180

started

1181

1182

\param clientInit true if the client should send an initial

1183

response to the server

1184

\param clientInitData the initial response to send to the server.

1185

Do note that there is a difference in SASL between an empty initial

1186

response and no initial response, and so even if clientInitData is

1187

an empty array, you still need to send an initial response if

1188

clientInit is true.

1100

1189

*/

1101

1190

void clientStarted(bool clientInit, const QByteArray &clientInitData);

1102

1191

1119

1208

This signal is emitted when the client needs

1120

1209

additional parameters

1121

1210

1122

Set parameter values as necessary and then call

1211

After receiving this signal, the application should set

1212

the required parameter values appropriately and then call

1123

1213

continueAfterParams().

1214

1215

\param params the parameters that are required by the client

1124

1216

*/

1125

1217

void needParams(const QCA::SASL::Params &params);

1126

1218

1129

1221

perform the authentication check

1130

1222

1131

1223

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

1224

1225

\param user the user identification name

1226

\param authzid the user authorization name

1132

1227

*/

1133

1228

void authCheck(const QString &user, const QString &authzid);

1134

1229