1// Copyright (C) 2016 The Qt Company Ltd.
2// Copyright (C) 2014 BlackBerry Limited. All rights reserved.
3// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
4
5#include "qssl_p.h"
6#include "qsslconfiguration.h"
7#include "qsslconfiguration_p.h"
8#include "qsslsocket.h"
9#include "qsslsocket_p.h"
10#include "qmutex.h"
11#include "qdebug.h"
12
13QT_BEGIN_NAMESPACE
14
15QT_IMPL_METATYPE_EXTERN(QSslConfiguration)
16
17const QSsl::SslOptions QSslConfigurationPrivate::defaultSslOptions = QSsl::SslOptionDisableEmptyFragments
18 |QSsl::SslOptionDisableLegacyRenegotiation
19 |QSsl::SslOptionDisableCompression
20 |QSsl::SslOptionDisableSessionPersistence;
21
22const char QSslConfiguration::ALPNProtocolHTTP2[] = "h2";
23const char QSslConfiguration::NextProtocolHttp1_1[] = "http/1.1";
24
25/*!
26 \class QSslConfiguration
27 \brief The QSslConfiguration class holds the configuration and state of an SSL connection.
28 \since 4.4
29
30 \reentrant
31 \inmodule QtNetwork
32 \ingroup network
33 \ingroup ssl
34 \ingroup shared
35
36 QSslConfiguration is used by Qt networking classes to relay
37 information about an open SSL connection and to allow the
38 application to control certain features of that connection.
39
40 The settings that QSslConfiguration currently supports are:
41
42 \list
43 \li The SSL/TLS protocol to be used
44 \li The certificate to be presented to the peer during connection
45 and its associated private key
46 \li The ciphers allowed to be used for encrypting the connection
47 \li The list of Certificate Authorities certificates that are
48 used to validate the peer's certificate
49 \endlist
50
51 These settings are applied only during the connection
52 handshake. Setting them after the connection has been established
53 has no effect.
54
55 The state that QSslConfiguration supports are:
56 \list
57 \li The certificate the peer presented during handshake, along
58 with the chain leading to a CA certificate
59 \li The cipher used to encrypt this session
60 \endlist
61
62 The state can only be obtained once the SSL connection starts, but
63 not necessarily before it's done. Some settings may change during
64 the course of the SSL connection without need to restart it (for
65 instance, the cipher can be changed over time).
66
67 State in QSslConfiguration objects cannot be changed.
68
69 QSslConfiguration can be used with QSslSocket and the Network
70 Access API.
71
72 Note that changing settings in QSslConfiguration is not enough to
73 change the settings in the related SSL connection. You must call
74 setSslConfiguration on a modified QSslConfiguration object to
75 achieve that. The following example illustrates how to change the
76 protocol to TLSv1_2 in a QSslSocket object:
77
78 \snippet code/src_network_ssl_qsslconfiguration.cpp 0
79
80 \sa QSsl::SslProtocol, QSslCertificate, QSslCipher, QSslKey,
81 QSslSocket, QNetworkAccessManager,
82 QSslSocket::sslConfiguration(), QSslSocket::setSslConfiguration()
83*/
84
85/*!
86 \enum QSslConfiguration::NextProtocolNegotiationStatus
87
88 Describes the status of the Next Protocol Negotiation (NPN) or
89 Application-Layer Protocol Negotiation (ALPN).
90
91 \value NextProtocolNegotiationNone No application protocol
92 has been negotiated (yet).
93
94 \value NextProtocolNegotiationNegotiated A next protocol
95 has been negotiated (see nextNegotiatedProtocol()).
96
97 \value NextProtocolNegotiationUnsupported The client and
98 server could not agree on a common next application protocol.
99*/
100
101/*!
102 \variable QSslConfiguration::NextProtocolHttp1_1
103 \brief The value used for negotiating HTTP 1.1 during the Next
104 Protocol Negotiation.
105*/
106
107/*!
108 \variable QSslConfiguration::ALPNProtocolHTTP2
109 \brief The value used for negotiating HTTP 2 during the Application-Layer
110 Protocol Negotiation.
111*/
112
113/*!
114 Constructs an empty SSL configuration. This configuration contains
115 no valid settings and the state will be empty. isNull() will
116 return true after this constructor is called.
117
118 Once any setter methods are called, isNull() will return false.
119*/
120QSslConfiguration::QSslConfiguration()
121 : d(new QSslConfigurationPrivate)
122{
123}
124
125/*!
126 Copies the configuration and state of \a other. If \a other is
127 null, this object will be null too.
128*/
129QSslConfiguration::QSslConfiguration(const QSslConfiguration &other)
130 : d(other.d)
131{
132}
133
134/*!
135 Releases any resources held by QSslConfiguration.
136*/
137QSslConfiguration::~QSslConfiguration()
138{
139 // QSharedDataPointer deletes d for us if necessary
140}
141
142/*!
143 Copies the configuration and state of \a other. If \a other is
144 null, this object will be null too.
145*/
146QSslConfiguration &QSslConfiguration::operator=(const QSslConfiguration &other)
147{
148 d = other.d;
149 return *this;
150}
151
152/*!
153 \fn void QSslConfiguration::swap(QSslConfiguration &other)
154 \since 5.0
155
156 Swaps this SSL configuration instance with \a other. This function
157 is very fast and never fails.
158*/
159
160/*!
161 Returns \c true if this QSslConfiguration object is equal to \a
162 other.
163
164 Two QSslConfiguration objects are considered equal if they have
165 the exact same settings and state.
166
167 \sa operator!=()
168*/
169bool QSslConfiguration::operator==(const QSslConfiguration &other) const
170{
171 if (d == other.d)
172 return true;
173 return d->peerCertificate == other.d->peerCertificate &&
174 d->peerCertificateChain == other.d->peerCertificateChain &&
175 d->localCertificateChain == other.d->localCertificateChain &&
176 d->privateKey == other.d->privateKey &&
177 d->sessionCipher == other.d->sessionCipher &&
178 d->sessionProtocol == other.d->sessionProtocol &&
179 d->preSharedKeyIdentityHint == other.d->preSharedKeyIdentityHint &&
180 d->ciphers == other.d->ciphers &&
181 d->ellipticCurves == other.d->ellipticCurves &&
182 d->ephemeralServerKey == other.d->ephemeralServerKey &&
183 d->dhParams == other.d->dhParams &&
184 d->caCertificates == other.d->caCertificates &&
185 d->protocol == other.d->protocol &&
186 d->peerVerifyMode == other.d->peerVerifyMode &&
187 d->peerVerifyDepth == other.d->peerVerifyDepth &&
188 d->allowRootCertOnDemandLoading == other.d->allowRootCertOnDemandLoading &&
189 d->backendConfig == other.d->backendConfig &&
190 d->sslOptions == other.d->sslOptions &&
191 d->sslSession == other.d->sslSession &&
192 d->sslSessionTicketLifeTimeHint == other.d->sslSessionTicketLifeTimeHint &&
193 d->nextAllowedProtocols == other.d->nextAllowedProtocols &&
194 d->nextNegotiatedProtocol == other.d->nextNegotiatedProtocol &&
195 d->nextProtocolNegotiationStatus == other.d->nextProtocolNegotiationStatus &&
196 d->dtlsCookieEnabled == other.d->dtlsCookieEnabled &&
197 d->ocspStaplingEnabled == other.d->ocspStaplingEnabled &&
198 d->reportFromCallback == other.d->reportFromCallback &&
199 d->missingCertIsFatal == other.d->missingCertIsFatal;
200}
201
202/*!
203 \fn QSslConfiguration::operator!=(const QSslConfiguration &other) const
204
205 Returns \c true if this QSslConfiguration differs from \a other. Two
206 QSslConfiguration objects are considered different if any state or
207 setting is different.
208
209 \sa operator==()
210*/
211
212/*!
213 Returns \c true if this is a null QSslConfiguration object.
214
215 A QSslConfiguration object is null if it has been
216 default-constructed and no setter methods have been called.
217
218 \sa setProtocol(), setLocalCertificate(), setPrivateKey(),
219 setCiphers(), setCaCertificates()
220*/
221bool QSslConfiguration::isNull() const
222{
223 return (d->protocol == QSsl::SecureProtocols &&
224 d->peerVerifyMode == QSslSocket::AutoVerifyPeer &&
225 d->peerVerifyDepth == 0 &&
226 d->allowRootCertOnDemandLoading == true &&
227 d->caCertificates.size() == 0 &&
228 d->ciphers.size() == 0 &&
229 d->ellipticCurves.isEmpty() &&
230 d->ephemeralServerKey.isNull() &&
231 d->dhParams == QSslDiffieHellmanParameters::defaultParameters() &&
232 d->localCertificateChain.isEmpty() &&
233 d->privateKey.isNull() &&
234 d->peerCertificate.isNull() &&
235 d->peerCertificateChain.size() == 0 &&
236 d->backendConfig.isEmpty() &&
237 d->sslOptions == QSslConfigurationPrivate::defaultSslOptions &&
238 d->sslSession.isNull() &&
239 d->sslSessionTicketLifeTimeHint == -1 &&
240 d->preSharedKeyIdentityHint.isNull() &&
241 d->nextAllowedProtocols.isEmpty() &&
242 d->nextNegotiatedProtocol.isNull() &&
243 d->nextProtocolNegotiationStatus == QSslConfiguration::NextProtocolNegotiationNone &&
244 d->ocspStaplingEnabled == false &&
245 d->reportFromCallback == false &&
246 d->missingCertIsFatal == false);
247}
248
249/*!
250 Returns the protocol setting for this SSL configuration.
251
252 \sa setProtocol()
253*/
254QSsl::SslProtocol QSslConfiguration::protocol() const
255{
256 return d->protocol;
257}
258
259/*!
260 Sets the protocol setting for this configuration to be \a
261 protocol.
262
263 Setting the protocol once the connection has already been
264 established has no effect.
265
266 \sa protocol()
267*/
268void QSslConfiguration::setProtocol(QSsl::SslProtocol protocol)
269{
270 d->protocol = protocol;
271}
272
273/*!
274 Returns the verify mode. This mode decides whether QSslSocket should
275 request a certificate from the peer (i.e., the client requests a
276 certificate from the server, or a server requesting a certificate from the
277 client), and whether it should require that this certificate is valid.
278
279 The default mode is AutoVerifyPeer, which tells QSslSocket to use
280 VerifyPeer for clients, QueryPeer for servers.
281
282 \sa setPeerVerifyMode()
283*/
284QSslSocket::PeerVerifyMode QSslConfiguration::peerVerifyMode() const
285{
286 return d->peerVerifyMode;
287}
288
289/*!
290 Sets the verify mode to \a mode. This mode decides whether QSslSocket
291 should request a certificate from the peer (i.e., the client requests a
292 certificate from the server, or a server requesting a certificate from the
293 client), and whether it should require that this certificate is valid.
294
295 The default mode is AutoVerifyPeer, which tells QSslSocket to use
296 VerifyPeer for clients, QueryPeer for servers.
297
298 \sa peerVerifyMode()
299*/
300void QSslConfiguration::setPeerVerifyMode(QSslSocket::PeerVerifyMode mode)
301{
302 d->peerVerifyMode = mode;
303}
304
305
306/*!
307 Returns the maximum number of certificates in the peer's certificate chain
308 to be checked during the SSL handshake phase, or 0 (the default) if no
309 maximum depth has been set, indicating that the whole certificate chain
310 should be checked.
311
312 The certificates are checked in issuing order, starting with the peer's
313 own certificate, then its issuer's certificate, and so on.
314
315 \sa setPeerVerifyDepth(), peerVerifyMode()
316*/
317int QSslConfiguration::peerVerifyDepth() const
318{
319 return d->peerVerifyDepth;
320}
321
322/*!
323 Sets the maximum number of certificates in the peer's certificate chain to
324 be checked during the SSL handshake phase, to \a depth. Setting a depth of
325 0 means that no maximum depth is set, indicating that the whole
326 certificate chain should be checked.
327
328 The certificates are checked in issuing order, starting with the peer's
329 own certificate, then its issuer's certificate, and so on.
330
331 \sa peerVerifyDepth(), setPeerVerifyMode()
332*/
333void QSslConfiguration::setPeerVerifyDepth(int depth)
334{
335 if (depth < 0) {
336 qCWarning(lcSsl,
337 "QSslConfiguration::setPeerVerifyDepth: cannot set negative depth of %d", depth);
338 return;
339 }
340 d->peerVerifyDepth = depth;
341}
342
343/*!
344 Returns the certificate chain to be presented to the peer during
345 the SSL handshake process.
346
347 \sa localCertificate()
348 \since 5.1
349*/
350QList<QSslCertificate> QSslConfiguration::localCertificateChain() const
351{
352 return d->localCertificateChain;
353}
354
355/*!
356 Sets the certificate chain to be presented to the peer during the
357 SSL handshake to be \a localChain.
358
359 Setting the certificate chain once the connection has been
360 established has no effect.
361
362 A certificate is the means of identification used in the SSL
363 process. The local certificate is used by the remote end to verify
364 the local user's identity against its list of Certification
365 Authorities. In most cases, such as in HTTP web browsing, only
366 servers identify to the clients, so the client does not send a
367 certificate.
368
369 Unlike QSslConfiguration::setLocalCertificate() this method allows
370 you to specify any intermediate certificates required in order to
371 validate your certificate. The first item in the list must be the
372 leaf certificate.
373
374 \sa localCertificateChain()
375 \since 5.1
376 */
377void QSslConfiguration::setLocalCertificateChain(const QList<QSslCertificate> &localChain)
378{
379 d->localCertificateChain = localChain;
380}
381
382/*!
383 Returns the certificate to be presented to the peer during the SSL
384 handshake process.
385
386 \sa setLocalCertificate()
387*/
388QSslCertificate QSslConfiguration::localCertificate() const
389{
390 if (d->localCertificateChain.isEmpty())
391 return QSslCertificate();
392 return d->localCertificateChain[0];
393}
394
395/*!
396 Sets the certificate to be presented to the peer during SSL
397 handshake to be \a certificate.
398
399 Setting the certificate once the connection has been established
400 has no effect.
401
402 A certificate is the means of identification used in the SSL
403 process. The local certificate is used by the remote end to verify
404 the local user's identity against its list of Certification
405 Authorities. In most cases, such as in HTTP web browsing, only
406 servers identify to the clients, so the client does not send a
407 certificate.
408
409 \sa localCertificate()
410*/
411void QSslConfiguration::setLocalCertificate(const QSslCertificate &certificate)
412{
413 d->localCertificateChain = QList<QSslCertificate>();
414 d->localCertificateChain += certificate;
415}
416
417/*!
418 Returns the peer's digital certificate (i.e., the immediate
419 certificate of the host you are connected to), or a null
420 certificate, if the peer has not assigned a certificate.
421
422 The peer certificate is checked automatically during the
423 handshake phase, so this function is normally used to fetch
424 the certificate for display or for connection diagnostic
425 purposes. It contains information about the peer, including
426 its host name, the certificate issuer, and the peer's public
427 key.
428
429 Because the peer certificate is set during the handshake phase, it
430 is safe to access the peer certificate from a slot connected to
431 the QSslSocket::sslErrors() signal, QNetworkReply::sslErrors()
432 signal, or the QSslSocket::encrypted() signal.
433
434 If a null certificate is returned, it can mean the SSL handshake
435 failed, or it can mean the host you are connected to doesn't have
436 a certificate, or it can mean there is no connection.
437
438 If you want to check the peer's complete chain of certificates,
439 use peerCertificateChain() to get them all at once.
440
441 \sa peerCertificateChain(),
442 QSslSocket::sslErrors(), QSslSocket::ignoreSslErrors(),
443 QNetworkReply::sslErrors(), QNetworkReply::ignoreSslErrors()
444*/
445QSslCertificate QSslConfiguration::peerCertificate() const
446{
447 return d->peerCertificate;
448}
449
450/*!
451 Returns the peer's chain of digital certificates, starting with
452 the peer's immediate certificate and ending with the CA's
453 certificate.
454
455 Peer certificates are checked automatically during the handshake
456 phase. This function is normally used to fetch certificates for
457 display, or for performing connection diagnostics. Certificates
458 contain information about the peer and the certificate issuers,
459 including host name, issuer names, and issuer public keys.
460
461 Because the peer certificate is set during the handshake phase, it
462 is safe to access the peer certificate from a slot connected to
463 the QSslSocket::sslErrors() signal, QNetworkReply::sslErrors()
464 signal, or the QSslSocket::encrypted() signal.
465
466 If an empty list is returned, it can mean the SSL handshake
467 failed, or it can mean the host you are connected to doesn't have
468 a certificate, or it can mean there is no connection.
469
470 If you want to get only the peer's immediate certificate, use
471 peerCertificate().
472
473 \sa peerCertificate(),
474 QSslSocket::sslErrors(), QSslSocket::ignoreSslErrors(),
475 QNetworkReply::sslErrors(), QNetworkReply::ignoreSslErrors()
476*/
477QList<QSslCertificate> QSslConfiguration::peerCertificateChain() const
478{
479 return d->peerCertificateChain;
480}
481
482/*!
483 Returns the socket's cryptographic \l {QSslCipher} {cipher}, or a
484 null cipher if the connection isn't encrypted. The socket's cipher
485 for the session is set during the handshake phase. The cipher is
486 used to encrypt and decrypt data transmitted through the socket.
487
488 The SSL infrastructure also provides functions for setting the
489 ordered list of ciphers from which the handshake phase will
490 eventually select the session cipher. This ordered list must be in
491 place before the handshake phase begins.
492
493 \sa ciphers(), setCiphers(), supportedCiphers()
494*/
495QSslCipher QSslConfiguration::sessionCipher() const
496{
497 return d->sessionCipher;
498}
499
500/*!
501 Returns the socket's SSL/TLS protocol or UnknownProtocol if the
502 connection isn't encrypted. The socket's protocol for the session
503 is set during the handshake phase.
504
505 \sa protocol(), setProtocol()
506 \since 5.4
507*/
508QSsl::SslProtocol QSslConfiguration::sessionProtocol() const
509{
510 return d->sessionProtocol;
511}
512
513/*!
514 Returns the \l {QSslKey} {SSL key} assigned to this connection or
515 a null key if none has been assigned yet.
516
517 \sa setPrivateKey(), localCertificate()
518*/
519QSslKey QSslConfiguration::privateKey() const
520{
521 return d->privateKey;
522}
523
524/*!
525 Sets the connection's private \l {QSslKey} {key} to \a key. The
526 private key and the local \l {QSslCertificate} {certificate} are
527 used by clients and servers that must prove their identity to
528 SSL peers.
529
530 Both the key and the local certificate are required if you are
531 creating an SSL server socket. If you are creating an SSL client
532 socket, the key and local certificate are required if your client
533 must identify itself to an SSL server.
534
535 \sa privateKey(), setLocalCertificate()
536*/
537void QSslConfiguration::setPrivateKey(const QSslKey &key)
538{
539 d->privateKey = key;
540}
541
542/*!
543 Returns this connection's current cryptographic cipher suite. This
544 list is used during the handshake phase for choosing a
545 session cipher. The returned list of ciphers is ordered by
546 descending preference. (i.e., the first cipher in the list is the
547 most preferred cipher). The session cipher will be the first one
548 in the list that is also supported by the peer.
549
550 By default, the handshake phase can choose any of the ciphers
551 supported by this system's SSL libraries, which may vary from
552 system to system. The list of ciphers supported by this system's
553 SSL libraries is returned by supportedCiphers(). You can restrict
554 the list of ciphers used for choosing the session cipher for this
555 socket by calling setCiphers() with a subset of the supported
556 ciphers. You can revert to using the entire set by calling
557 setCiphers() with the list returned by supportedCiphers().
558
559 \sa setCiphers(), supportedCiphers()
560*/
561QList<QSslCipher> QSslConfiguration::ciphers() const
562{
563 return d->ciphers;
564}
565
566/*!
567 Sets the cryptographic cipher suite for this socket to \a ciphers,
568 which must contain a subset of the ciphers in the list returned by
569 supportedCiphers().
570
571 Restricting the cipher suite must be done before the handshake
572 phase, where the session cipher is chosen.
573
574 \sa ciphers(), supportedCiphers()
575*/
576void QSslConfiguration::setCiphers(const QList<QSslCipher> &ciphers)
577{
578 d->ciphers = ciphers;
579}
580
581/*!
582 \since 6.0
583
584 Sets the cryptographic cipher suite for this configuration to \a ciphers,
585 which is a colon-separated list of cipher suite names. The ciphers are listed
586 in order of preference, starting with the most preferred cipher.
587 Each cipher name in \a ciphers must be the name of a cipher in the
588 list returned by supportedCiphers(). Restricting the cipher suite
589 must be done before the handshake phase, where the session cipher
590 is chosen.
591
592 \note With the Schannel backend the order of the ciphers is ignored and Schannel
593 picks the most secure one during the handshake.
594
595 \sa ciphers()
596*/
597void QSslConfiguration::setCiphers(const QString &ciphers)
598{
599 auto *p = d.data();
600 p->ciphers.clear();
601 const auto cipherNames = ciphers.split(sep: u':', behavior: Qt::SkipEmptyParts);
602 for (const QString &cipherName : cipherNames) {
603 QSslCipher cipher(cipherName);
604 if (!cipher.isNull())
605 p->ciphers << cipher;
606 }
607}
608
609/*!
610 \since 5.5
611
612 Returns the list of cryptographic ciphers supported by this
613 system. This list is set by the system's SSL libraries and may
614 vary from system to system.
615
616 \sa ciphers(), setCiphers()
617*/
618QList<QSslCipher> QSslConfiguration::supportedCiphers()
619{
620 return QSslSocketPrivate::supportedCiphers();
621}
622
623/*!
624 Returns this connection's CA certificate database. The CA certificate
625 database is used by the socket during the handshake phase to
626 validate the peer's certificate. It can be modified prior to the
627 handshake with setCaCertificates(), or with addCaCertificate() and
628 addCaCertificates().
629
630 \sa setCaCertificates(), addCaCertificate(), addCaCertificates()
631*/
632QList<QSslCertificate> QSslConfiguration::caCertificates() const
633{
634 return d->caCertificates;
635}
636
637/*!
638 Sets this socket's CA certificate database to be \a certificates.
639 The certificate database must be set prior to the SSL handshake.
640 The CA certificate database is used by the socket during the
641 handshake phase to validate the peer's certificate.
642
643 \note The default configuration uses the system CA certificate database. If
644 that is not available (as is commonly the case on iOS), the default database
645 is empty.
646
647 \sa caCertificates(), addCaCertificates(), addCaCertificate()
648*/
649void QSslConfiguration::setCaCertificates(const QList<QSslCertificate> &certificates)
650{
651 d->caCertificates = certificates;
652 d->allowRootCertOnDemandLoading = false;
653}
654
655/*!
656 \since 5.15
657
658 Searches all files in the \a path for certificates encoded in the
659 specified \a format and adds them to this socket's CA certificate
660 database. \a path must be a file or a pattern matching one or more
661 files, as specified by \a syntax. Returns \c true if one or more
662 certificates are added to the socket's CA certificate database;
663 otherwise returns \c false.
664
665 The CA certificate database is used by the socket during the
666 handshake phase to validate the peer's certificate.
667
668 For more precise control, use addCaCertificate().
669
670 \sa addCaCertificate(), QSslCertificate::fromPath()
671*/
672bool QSslConfiguration::addCaCertificates(const QString &path, QSsl::EncodingFormat format,
673 QSslCertificate::PatternSyntax syntax)
674{
675 QList<QSslCertificate> certs = QSslCertificate::fromPath(path, format, syntax);
676 if (certs.isEmpty())
677 return false;
678
679 d->caCertificates += certs;
680 return true;
681}
682
683/*!
684 \since 5.15
685
686 Adds \a certificate to this configuration's CA certificate database.
687 The certificate database must be set prior to the SSL handshake.
688 The CA certificate database is used by the socket during the
689 handshake phase to validate the peer's certificate.
690
691 \note The default configuration uses the system CA certificate database. If
692 that is not available (as is commonly the case on iOS), the default database
693 is empty.
694
695 \sa caCertificates(), setCaCertificates(), addCaCertificates()
696*/
697void QSslConfiguration::addCaCertificate(const QSslCertificate &certificate)
698{
699 d->caCertificates += certificate;
700 d->allowRootCertOnDemandLoading = false;
701}
702
703/*!
704 \since 5.15
705
706 Adds \a certificates to this configuration's CA certificate database.
707 The certificate database must be set prior to the SSL handshake.
708 The CA certificate database is used by the socket during the
709 handshake phase to validate the peer's certificate.
710
711 \note The default configuration uses the system CA certificate database. If
712 that is not available (as is commonly the case on iOS), the default database
713 is empty.
714
715 \sa caCertificates(), setCaCertificates(), addCaCertificate()
716*/
717void QSslConfiguration::addCaCertificates(const QList<QSslCertificate> &certificates)
718{
719 d->caCertificates += certificates;
720 d->allowRootCertOnDemandLoading = false;
721}
722
723/*!
724 \since 5.5
725
726 This function provides the CA certificate database
727 provided by the operating system. The CA certificate database
728 returned by this function is used to initialize the database
729 returned by caCertificates() on the default QSslConfiguration.
730
731 \sa caCertificates(), setCaCertificates(), defaultConfiguration(),
732 addCaCertificate(), addCaCertificates()
733*/
734QList<QSslCertificate> QSslConfiguration::systemCaCertificates()
735{
736 // we are calling ensureInitialized() in the method below
737 return QSslSocketPrivate::systemCaCertificates();
738}
739
740/*!
741 Enables or disables an SSL compatibility \a option. If \a on
742 is true, the \a option is enabled. If \a on is false, the
743 \a option is disabled.
744
745 \sa testSslOption()
746*/
747void QSslConfiguration::setSslOption(QSsl::SslOption option, bool on)
748{
749 d->sslOptions.setFlag(flag: option, on);
750}
751
752/*!
753 \since 4.8
754
755 Returns \c true if the specified SSL compatibility \a option is enabled.
756
757 \sa setSslOption()
758*/
759bool QSslConfiguration::testSslOption(QSsl::SslOption option) const
760{
761 return d->sslOptions & option;
762}
763
764/*!
765 \since 5.2
766
767 If QSsl::SslOptionDisableSessionPersistence was turned off, this
768 function returns the session ticket used in the SSL handshake in ASN.1
769 format, suitable to e.g. be persisted to disk. If no session ticket was
770 used or QSsl::SslOptionDisableSessionPersistence was not turned off,
771 this function returns an empty QByteArray.
772
773 \note When persisting the session ticket to disk or similar, be
774 careful not to expose the session to a potential attacker, as
775 knowledge of the session allows for eavesdropping on data
776 encrypted with the session parameters.
777
778 \sa setSessionTicket(), QSsl::SslOptionDisableSessionPersistence, setSslOption(), QSslSocket::newSessionTicketReceived()
779 */
780QByteArray QSslConfiguration::sessionTicket() const
781{
782 return d->sslSession;
783}
784
785/*!
786 \since 5.2
787
788 Sets the session ticket to be used in an SSL handshake.
789 QSsl::SslOptionDisableSessionPersistence must be turned off
790 for this to work, and \a sessionTicket must be in ASN.1 format
791 as returned by sessionTicket().
792
793 \sa sessionTicket(), QSsl::SslOptionDisableSessionPersistence, setSslOption(), QSslSocket::newSessionTicketReceived()
794 */
795void QSslConfiguration::setSessionTicket(const QByteArray &sessionTicket)
796{
797 d->sslSession = sessionTicket;
798}
799
800/*!
801 \since 5.2
802
803 If QSsl::SslOptionDisableSessionPersistence was turned off, this
804 function returns the session ticket life time hint sent by the
805 server (which might be 0).
806 If the server did not send a session ticket (e.g. when
807 resuming a session or when the server does not support it) or
808 QSsl::SslOptionDisableSessionPersistence was not turned off,
809 this function returns -1.
810
811 \sa sessionTicket(), QSsl::SslOptionDisableSessionPersistence, setSslOption(), QSslSocket::newSessionTicketReceived()
812 */
813int QSslConfiguration::sessionTicketLifeTimeHint() const
814{
815 return d->sslSessionTicketLifeTimeHint;
816}
817
818/*!
819 \since 5.7
820
821 Returns the ephemeral server key used for cipher algorithms
822 with forward secrecy, e.g. DHE-RSA-AES128-SHA.
823
824 The ephemeral key is only available when running in client mode, i.e.
825 QSslSocket::SslClientMode. When running in server mode or using a
826 cipher algorithm without forward secrecy a null key is returned.
827 The ephemeral server key will be set before emitting the encrypted()
828 signal.
829 */
830QSslKey QSslConfiguration::ephemeralServerKey() const
831{
832 return d->ephemeralServerKey;
833}
834
835/*!
836 \since 5.5
837
838 Returns this connection's current list of elliptic curves. This
839 list is used during the handshake phase for choosing an
840 elliptic curve (when using an elliptic curve cipher).
841 The returned list of curves is ordered by descending preference
842 (i.e., the first curve in the list is the most preferred one).
843
844 By default, the handshake phase can choose any of the curves
845 supported by this system's SSL libraries, which may vary from
846 system to system. The list of curves supported by this system's
847 SSL libraries is returned by QSslSocket::supportedEllipticCurves().
848
849 You can restrict the list of curves used for choosing the session cipher
850 for this socket by calling setEllipticCurves() with a subset of the
851 supported ciphers. You can revert to using the entire set by calling
852 setEllipticCurves() with the list returned by
853 QSslSocket::supportedEllipticCurves().
854
855 \sa setEllipticCurves
856 */
857QList<QSslEllipticCurve> QSslConfiguration::ellipticCurves() const
858{
859 return d->ellipticCurves;
860}
861
862/*!
863 \since 5.5
864
865 Sets the list of elliptic curves to be used by this socket to \a curves,
866 which must contain a subset of the curves in the list returned by
867 supportedEllipticCurves().
868
869 Restricting the elliptic curves must be done before the handshake
870 phase, where the session cipher is chosen.
871
872 \sa ellipticCurves
873 */
874void QSslConfiguration::setEllipticCurves(const QList<QSslEllipticCurve> &curves)
875{
876 d->ellipticCurves = curves;
877}
878
879/*!
880 \since 5.5
881
882 Returns the list of elliptic curves supported by this
883 system. This list is set by the system's SSL libraries and may
884 vary from system to system.
885
886 \sa ellipticCurves(), setEllipticCurves()
887*/
888QList<QSslEllipticCurve> QSslConfiguration::supportedEllipticCurves()
889{
890 return QSslSocketPrivate::supportedEllipticCurves();
891}
892
893/*!
894 \since 5.8
895
896 Returns the identity hint.
897
898 \sa setPreSharedKeyIdentityHint()
899*/
900QByteArray QSslConfiguration::preSharedKeyIdentityHint() const
901{
902 return d->preSharedKeyIdentityHint;
903}
904
905/*!
906 \since 5.8
907
908 Sets the identity hint for a preshared key authentication to \a hint. This will
909 affect the next initiated handshake; calling this function on an already-encrypted
910 socket will not affect the socket's identity hint.
911
912 The identity hint is used in QSslSocket::SslServerMode only!
913*/
914void QSslConfiguration::setPreSharedKeyIdentityHint(const QByteArray &hint)
915{
916 d->preSharedKeyIdentityHint = hint;
917}
918
919/*!
920 \since 5.8
921
922 Retrieves the current set of Diffie-Hellman parameters.
923
924 If no Diffie-Hellman parameters have been set, the QSslConfiguration object
925 defaults to using the 2048-bit MODP group from RFC 3526.
926
927 \note The default parameters may change in future Qt versions.
928 Please check the documentation of the \e{exact Qt version} that you
929 are using in order to know what defaults that version uses.
930 */
931QSslDiffieHellmanParameters QSslConfiguration::diffieHellmanParameters() const
932{
933 return d->dhParams;
934}
935
936/*!
937 \since 5.8
938
939 Sets a custom set of Diffie-Hellman parameters to be used by this socket when functioning as
940 a server to \a dhparams.
941
942 If no Diffie-Hellman parameters have been set, the QSslConfiguration object
943 defaults to using the 2048-bit MODP group from RFC 3526.
944
945 Since 6.7 you can provide an empty Diffie-Hellman parameter to use auto selection
946 (see SSL_CTX_set_dh_auto of openssl) if the tls backend supports it.
947
948 \note The default parameters may change in future Qt versions.
949 Please check the documentation of the \e{exact Qt version} that you
950 are using in order to know what defaults that version uses.
951 */
952void QSslConfiguration::setDiffieHellmanParameters(const QSslDiffieHellmanParameters &dhparams)
953{
954 d->dhParams = dhparams;
955}
956
957/*!
958 \since 5.11
959
960 Returns the backend-specific configuration.
961
962 Only options set by setBackendConfigurationOption() or setBackendConfiguration() will be
963 returned. The internal standard configuration of the backend is not reported.
964
965 \sa setBackendConfigurationOption(), setBackendConfiguration()
966 */
967QMap<QByteArray, QVariant> QSslConfiguration::backendConfiguration() const
968{
969 return d->backendConfig;
970}
971
972/*!
973 \since 5.11
974
975 Sets the option \a name in the backend-specific configuration to \a value.
976
977 Options supported by the OpenSSL (>= 1.0.2) backend are available in the \l
978 {https://www.openssl.org/docs/manmaster/man3/SSL_CONF_cmd.html#SUPPORTED-CONFIGURATION-FILE-COMMANDS}
979 {supported configuration file commands} documentation. The expected type for
980 the \a value parameter is a QByteArray for all options. The \l
981 {https://www.openssl.org/docs/manmaster/man3/SSL_CONF_cmd.html#EXAMPLES}{examples}
982 show how to use some of the options.
983
984 \note The backend-specific configuration will be applied after the general
985 configuration. Using the backend-specific configuration to set a general
986 configuration option again will overwrite the general configuration option.
987
988 \sa backendConfiguration(), setBackendConfiguration()
989 */
990void QSslConfiguration::setBackendConfigurationOption(const QByteArray &name, const QVariant &value)
991{
992 d->backendConfig[name] = value;
993}
994
995/*!
996 \since 5.11
997
998 Sets or clears the backend-specific configuration.
999
1000 Without a \a backendConfiguration parameter this function will clear the
1001 backend-specific configuration. More information about the supported
1002 options is available in the documentation of setBackendConfigurationOption().
1003
1004 \sa backendConfiguration(), setBackendConfigurationOption()
1005 */
1006void QSslConfiguration::setBackendConfiguration(const QMap<QByteArray, QVariant> &backendConfiguration)
1007{
1008 d->backendConfig = backendConfiguration;
1009}
1010
1011/*!
1012 \since 5.3
1013
1014 This function returns the protocol negotiated with the server
1015 if the Next Protocol Negotiation (NPN) or Application-Layer Protocol
1016 Negotiation (ALPN) TLS extension was enabled.
1017 In order for the NPN/ALPN extension to be enabled, setAllowedNextProtocols()
1018 needs to be called explicitly before connecting to the server.
1019
1020 If no protocol could be negotiated or the extension was not enabled,
1021 this function returns a QByteArray which is null.
1022
1023 \sa setAllowedNextProtocols(), nextProtocolNegotiationStatus()
1024 */
1025QByteArray QSslConfiguration::nextNegotiatedProtocol() const
1026{
1027 return d->nextNegotiatedProtocol;
1028}
1029
1030/*!
1031 \since 5.3
1032
1033 This function sets the allowed \a protocols to be negotiated with the
1034 server through the Next Protocol Negotiation (NPN) or Application-Layer
1035 Protocol Negotiation (ALPN) TLS extension; each
1036 element in \a protocols must define one allowed protocol.
1037 The function must be called explicitly before connecting to send the NPN/ALPN
1038 extension in the SSL handshake.
1039 Whether or not the negotiation succeeded can be queried through
1040 nextProtocolNegotiationStatus().
1041
1042 \sa nextNegotiatedProtocol(), nextProtocolNegotiationStatus(), allowedNextProtocols(), QSslConfiguration::NextProtocolHttp1_1
1043 */
1044void QSslConfiguration::setAllowedNextProtocols(const QList<QByteArray> &protocols)
1045{
1046 d->nextAllowedProtocols = protocols;
1047}
1048
1049/*!
1050 \since 5.3
1051
1052 This function returns the allowed protocols to be negotiated with the
1053 server through the Next Protocol Negotiation (NPN) or Application-Layer
1054 Protocol Negotiation (ALPN) TLS extension, as set by setAllowedNextProtocols().
1055
1056 \sa nextNegotiatedProtocol(), nextProtocolNegotiationStatus(), setAllowedNextProtocols(), QSslConfiguration::NextProtocolHttp1_1
1057 */
1058QList<QByteArray> QSslConfiguration::allowedNextProtocols() const
1059{
1060 return d->nextAllowedProtocols;
1061}
1062
1063/*!
1064 \since 5.3
1065
1066 This function returns the status of the Next Protocol Negotiation (NPN)
1067 or Application-Layer Protocol Negotiation (ALPN).
1068 If the feature has not been enabled through setAllowedNextProtocols(),
1069 this function returns NextProtocolNegotiationNone.
1070 The status will be set before emitting the encrypted() signal.
1071
1072 \sa setAllowedNextProtocols(), allowedNextProtocols(), nextNegotiatedProtocol(), QSslConfiguration::NextProtocolNegotiationStatus
1073 */
1074QSslConfiguration::NextProtocolNegotiationStatus QSslConfiguration::nextProtocolNegotiationStatus() const
1075{
1076 return d->nextProtocolNegotiationStatus;
1077}
1078
1079/*!
1080 Returns the default SSL configuration to be used in new SSL
1081 connections.
1082
1083 The default SSL configuration consists of:
1084
1085 \list
1086 \li no local certificate and no private key
1087 \li protocol \l{QSsl::SecureProtocols}{SecureProtocols}
1088 \li the system's default CA certificate list
1089 \li the cipher list equal to the list of the SSL libraries'
1090 supported SSL ciphers that are 128 bits or more
1091 \endlist
1092
1093 \sa supportedCiphers(), setDefaultConfiguration()
1094*/
1095QSslConfiguration QSslConfiguration::defaultConfiguration()
1096{
1097 return QSslConfigurationPrivate::defaultConfiguration();
1098}
1099
1100/*!
1101 Sets the default SSL configuration to be used in new SSL
1102 connections to be \a configuration. Existing connections are not
1103 affected by this call.
1104
1105 \sa supportedCiphers(), defaultConfiguration()
1106*/
1107void QSslConfiguration::setDefaultConfiguration(const QSslConfiguration &configuration)
1108{
1109 QSslConfigurationPrivate::setDefaultConfiguration(configuration);
1110}
1111
1112#if QT_CONFIG(dtls) || defined(Q_QDOC)
1113
1114/*!
1115 This function returns true if DTLS cookie verification was enabled on a
1116 server-side socket.
1117
1118 \sa setDtlsCookieVerificationEnabled()
1119 */
1120bool QSslConfiguration::dtlsCookieVerificationEnabled() const
1121{
1122 return d->dtlsCookieEnabled;
1123}
1124
1125/*!
1126 This function enables DTLS cookie verification when \a enable is true.
1127
1128 \sa dtlsCookieVerificationEnabled()
1129 */
1130void QSslConfiguration::setDtlsCookieVerificationEnabled(bool enable)
1131{
1132 d->dtlsCookieEnabled = enable;
1133}
1134
1135/*!
1136 Returns the default DTLS configuration to be used in new DTLS
1137 connections.
1138
1139 The default DTLS configuration consists of:
1140
1141 \list
1142 \li no local certificate and no private key
1143 \li protocol DtlsV1_2OrLater
1144 \li the system's default CA certificate list
1145 \li the cipher list equal to the list of the SSL libraries'
1146 supported TLS 1.2 ciphers that use 128 or more secret bits
1147 for the cipher.
1148 \endlist
1149
1150 \sa setDefaultDtlsConfiguration()
1151*/
1152QSslConfiguration QSslConfiguration::defaultDtlsConfiguration()
1153{
1154 return QSslConfigurationPrivate::defaultDtlsConfiguration();
1155}
1156
1157/*!
1158 Sets the default DTLS configuration to be used in new DTLS
1159 connections to be \a configuration. Existing connections are not
1160 affected by this call.
1161
1162 \sa defaultDtlsConfiguration()
1163*/
1164void QSslConfiguration::setDefaultDtlsConfiguration(const QSslConfiguration &configuration)
1165{
1166 QSslConfigurationPrivate::setDefaultDtlsConfiguration(configuration);
1167}
1168
1169#endif // dtls
1170
1171/*!
1172 \since 5.13
1173 If \a enabled is true, client QSslSocket will send a certificate status request
1174 to its peer when initiating a handshake. During the handshake QSslSocket will
1175 verify the server's response. This value must be set before the handshake
1176 starts.
1177
1178 \sa ocspStaplingEnabled()
1179*/
1180void QSslConfiguration::setOcspStaplingEnabled(bool enabled)
1181{
1182#if QT_CONFIG(ocsp)
1183 d->ocspStaplingEnabled = enabled;
1184#else
1185 if (enabled)
1186 qCWarning(lcSsl, "Enabling OCSP-stapling requires the feature 'ocsp'");
1187#endif // ocsp
1188}
1189
1190/*!
1191 \since 5.13
1192 Returns true if OCSP stapling was enabled by setOCSPStaplingEnabled(),
1193 otherwise false (which is the default value).
1194
1195 \sa setOcspStaplingEnabled()
1196*/
1197bool QSslConfiguration::ocspStaplingEnabled() const
1198{
1199 return d->ocspStaplingEnabled;
1200}
1201
1202/*!
1203 \since 6.0
1204
1205 Returns true if a verification callback will emit QSslSocket::handshakeInterruptedOnError()
1206 early, before concluding the handshake.
1207
1208 \note This function always returns false for all backends but OpenSSL.
1209
1210 \sa setHandshakeMustInterruptOnError(), QSslSocket::handshakeInterruptedOnError(), QSslSocket::continueInterruptedHandshake()
1211*/
1212bool QSslConfiguration::handshakeMustInterruptOnError() const
1213{
1214 return d->reportFromCallback;
1215}
1216
1217/*!
1218 \since 6.0
1219
1220 If \a interrupt is true and the underlying backend supports this option,
1221 errors found during certificate verification are reported immediately
1222 by emitting QSslSocket::handshakeInterruptedOnError(). This allows
1223 to stop the unfinished handshake and send a proper alert message to
1224 a peer. No special action is required from the application in this case.
1225 QSslSocket will close the connection after sending the alert message.
1226 If the application after inspecting the error wants to continue the
1227 handshake, it must call QSslSocket::continueInterruptedHandshake()
1228 from its slot function. The signal-slot connection must be direct.
1229
1230 \note When interrupting handshake is enabled, errors that would otherwise
1231 be reported by QSslSocket::peerVerifyError() are instead only reported by
1232 QSslSocket::handshakeInterruptedOnError().
1233 \note Even if the handshake was continued, these errors will be
1234 reported when emitting QSslSocket::sslErrors() signal (and thus must
1235 be ignored in the corresponding function slot).
1236
1237 \sa handshakeMustInterruptOnError(), QSslSocket::handshakeInterruptedOnError(), QSslSocket::continueInterruptedHandshake()
1238*/
1239void QSslConfiguration::setHandshakeMustInterruptOnError(bool interrupt)
1240{
1241#if QT_CONFIG(openssl)
1242 d->reportFromCallback = interrupt;
1243#else
1244 Q_UNUSED(interrupt);
1245 qCWarning(lcSsl, "This operation requires OpenSSL as TLS backend");
1246#endif
1247}
1248
1249/*!
1250 \since 6.0
1251
1252 Returns true if errors with code QSslError::NoPeerCertificate
1253 cannot be ignored.
1254
1255 \note Always returns false for all TLS backends but OpenSSL.
1256
1257 \sa QSslSocket::ignoreSslErrors(), setMissingCertificateIsFatal()
1258*/
1259bool QSslConfiguration::missingCertificateIsFatal() const
1260{
1261 return d->missingCertIsFatal;
1262}
1263
1264/*!
1265 \since 6.0
1266
1267 If \a cannotRecover is true, and verification mode in use is
1268 QSslSocket::VerifyPeer or QSslSocket::AutoVerifyPeer (for a
1269 client-side socket), the missing peer's certificate would be
1270 treated as an unrecoverable error that cannot be ignored. A proper
1271 alert message will be sent to the peer before closing the connection.
1272
1273 \note Only available if Qt was configured and built with OpenSSL backend.
1274
1275 \sa QSslSocket::ignoreSslErrors(), QSslSocket::PeerVerifyMode, missingCertificateIsFatal()
1276*/
1277void QSslConfiguration::setMissingCertificateIsFatal(bool cannotRecover)
1278{
1279#if QT_CONFIG(openssl)
1280 d->missingCertIsFatal = cannotRecover;
1281#else
1282 Q_UNUSED(cannotRecover);
1283 qCWarning(lcSsl, "Handling a missing certificate as a fatal error requires an OpenSSL backend");
1284#endif // openssl
1285}
1286
1287/*! \internal
1288*/
1289bool QSslConfigurationPrivate::peerSessionWasShared(const QSslConfiguration &configuration) {
1290 return configuration.d->peerSessionShared;
1291 }
1292
1293QT_END_NAMESPACE
1294

Provided by KDAB

Privacy Policy
Learn Advanced QML with KDAB
Find out more

source code of qtbase/src/network/ssl/qsslconfiguration.cpp