QDtls Class

Documentation des fonctions membres

[explicit] QDtls::QDtls(QSslSocket::SslMode mode, QObject *parent = nullptr)

Crée un objet QDtls, parent est passé au constructeur QObject. mode est QSslSocket::SslServerMode pour une connexion DTLS côté serveur ou QSslSocket::SslClientMode pour un client.

Voir également sslMode() et QSslSocket::SslMode.

[virtual noexcept] QDtls::~QDtls()

Détruit l'objet QDtls.

bool QDtls::abortHandshake(QUdpSocket *socket)

Abandonne la poignée de main en cours. Retourne vrai si une poignée de main était en cours sur socket; sinon, met en place une erreur appropriée et retourne faux.

Voir aussi doHandshake() et resumeHandshake().

QDtls::GeneratorParameters QDtls::cookieGeneratorParameters() const

Renvoie l'algorithme de hachage et le secret actuels, soit ceux par défaut, soit ceux précédemment définis par un appel à setCookieGeneratorParameters().

L'algorithme de hachage par défaut est QCryptographicHash::Sha256 si Qt XML a été configuré pour le supporter, QCryptographicHash::Sha1 sinon. Le secret par défaut est obtenu à partir du générateur de nombres pseudo-aléatoires cryptographiquement fort spécifique au backend.

Voir aussi QDtlsClientVerifier et setCookieGeneratorParameters().

QByteArray QDtls::decryptDatagram(QUdpSocket *socket, const QByteArray &dgram)

Décrypte dgram et renvoie son contenu en texte clair. La poignée de main doit être terminée avant que les datagrammes puissent être décryptés. Selon le type de message TLS, la connexion peut écrire dans socket, qui doit être un pointeur valide.

bool QDtls::doHandshake(QUdpSocket *socket, const QByteArray &dgram = {})

Démarre ou poursuit une poignée de main DTLS. socket doit être un pointeur valide. Lors du démarrage d'une poignée de main DTLS côté serveur, dgram doit contenir le message ClientHello initial lu à partir de QUdpSocket. Cette fonction renvoie true si aucune erreur n'a été trouvée. L'état de la poignée de main peut être testé à l'aide de handshakeState(). Le retour de false signifie qu'une erreur s'est produite, utilisez dtlsError() pour obtenir des informations plus détaillées.

if (!dtls.doHandshake(&socket, dgram)) {
    if (dtls.dtlsError() == QDtlsError::PeerVerificationError)
        dtls.abortAfterError(&socket);
}

Voir aussi handshakeState(), dtlsError(), ignoreVerificationErrors(), resumeHandshake() et abortHandshake().

QSslConfiguration QDtls::dtlsConfiguration() const

Renvoie soit la configuration DTLS par défaut, soit la configuration définie par un appel antérieur à setDtlsConfiguration().

Voir aussi setDtlsConfiguration() et QSslConfiguration::defaultDtlsConfiguration().

QDtlsError QDtls::dtlsError() const

Renvoie la dernière erreur rencontrée par la connexion ou QDtlsError::NoError.

Voir aussi dtlsErrorString() et QDtlsError.

QString QDtls::dtlsErrorString() const

Renvoie une description textuelle de la dernière erreur rencontrée par la connexion ou une chaîne vide.

Voir aussi dtlsError().

bool QDtls::handleTimeout(QUdpSocket *socket)

Si un dépassement de délai se produit au cours de la poignée de main, le signal handshakeTimeout() est émis. L'application doit appeler handleTimeout() pour retransmettre les messages de la poignée de main ; handleTimeout() renvoie true si un dépassement de délai s'est produit, false dans le cas contraire. socket doit être un pointeur valide.

Voir également handshakeTimeout().

QDtls::HandshakeState QDtls::handshakeState() const

Renvoie l'état actuel de la poignée de main pour cette QDtls.

Voir aussi doHandshake() et QDtls::HandshakeState.

[signal] void QDtls::handshakeTimeout()

La perte de paquets peut entraîner des dépassements de délai pendant la phase d'échange. Dans ce cas, QDtls émet un signal handshakeTimeout(). Appelez handleTimeout() pour retransmettre les messages de prise de contact :

DtlsClient::DtlsClient()
{
    // Some initialization code here ...
    connect(&clientDtls, &QDtls::handshakeTimeout, this, &DtlsClient::handleTimeout);
}

void DtlsClient::handleTimeout()
{
    clientDtls.handleTimeout(&clientSocket);
}

Voir aussi handleTimeout().

void QDtls::ignoreVerificationErrors(const QList<QSslError> &errorsToIgnore)

Cette méthode indique à QDtls d'ignorer uniquement les erreurs indiquées dans errorsToIgnore.

Si, par exemple, vous souhaitez vous connecter à un serveur qui utilise un certificat auto-signé, examinez l'extrait suivant :

QList<QSslCertificate> cert = QSslCertificate::fromPath("server-certificate.pem"_L1);
QSslError error(QSslError::SelfSignedCertificate, cert.at(0));
QList<QSslError> expectedSslErrors;
expectedSslErrors.append(error);

QDtls dtls;
dtls.ignoreVerificationErrors(expectedSslErrors);
dtls.doHandshake(udpSocket);

Vous pouvez également appeler cette fonction après que doHandshake() a rencontré l'erreur QDtlsError::PeerVerificationError, puis reprendre la poignée de main en appelant resumeHandshake().

Les appels ultérieurs à cette fonction remplaceront la liste des erreurs transmises lors des appels précédents. Vous pouvez effacer la liste des erreurs que vous souhaitez ignorer en appelant cette fonction avec une liste vide.

Voir aussi doHandshake(), resumeHandshake() et QSslError.

bool QDtls::isConnectionEncrypted() const

Renvoie true si la poignée de main DTLS s'est terminée avec succès.

Voir aussi doHandshake() et handshakeState().

quint16 QDtls::mtuHint() const

Renvoie la valeur précédemment définie par setMtuHint(). La valeur par défaut est 0.

Voir aussi setMtuHint().

QHostAddress QDtls::peerAddress() const

Renvoie l'adresse de l'homologue, définie par setPeer(), ou QHostAddress::Null.

Voir aussi setPeer().

quint16 QDtls::peerPort() const

Renvoie le numéro de port de l'homologue, défini par setPeer(), ou 0.

Voir aussi setPeer().

QList<QSslError> QDtls::peerVerificationErrors() const

Renvoie les erreurs trouvées lors de l'établissement de l'identité de l'homologue.

Si vous voulez continuer à vous connecter malgré les erreurs qui se sont produites, vous devez appeler ignoreVerificationErrors().

QString QDtls::peerVerificationName() const

Renvoie le nom d'hôte défini par setPeer() ou setPeerVerificationName(). La valeur par défaut est une chaîne vide.

Voir aussi setPeerVerificationName() et setPeer().

[signal] void QDtls::pskRequired(QSslPreSharedKeyAuthenticator *authenticator)

QDtls émet ce signal lorsqu'il négocie une suite de chiffrement PSK, et une authentification PSK est donc nécessaire.

Lors de l'utilisation de la PSK, le client doit envoyer au serveur une identité valide et une clé prépartagée valide, afin que la poignée de main TLS puisse se poursuivre. Les applications peuvent fournir ces informations dans un slot connecté à ce signal, en remplissant l'objet authenticator en fonction de leurs besoins.

Voir aussi QSslPreSharedKeyAuthenticator.

bool QDtls::resumeHandshake(QUdpSocket *socket)

Si les erreurs de vérification de l'homologue ont été ignorées pendant la poignée de main, resumeHandshake() reprend et termine la poignée de main et renvoie true. socket doit être un pointeur valide. Retourne false si la poignée de main n'a pas pu être reprise.

Voir aussi doHandshake(), abortHandshake(), peerVerificationErrors() et ignoreVerificationErrors().

QSslCipher QDtls::sessionCipher() const

Renvoie le code cryptographique cipher utilisé par cette connexion, ou un code nul si la connexion n'est pas cryptée. Le système de chiffrement de la session est sélectionné lors de la phase d'échange de données. Il est utilisé pour chiffrer et déchiffrer les données.

QSslConfiguration fournit des fonctions permettant de définir la liste ordonnée de chiffrements à partir de laquelle la phase de poignée de main sélectionnera finalement le chiffrement de la session. Cette liste ordonnée doit être en place avant le début de la phase de poignée de main.

Voir aussi QSslConfiguration, setDtlsConfiguration(), et dtlsConfiguration().

QSsl::SslProtocol QDtls::sessionProtocol() const

Renvoie la version du protocole DTLS utilisée par cette connexion, ou UnknownProtocol si la connexion n'est pas encore cryptée. Le protocole de la connexion est sélectionné lors de la phase d'échange.

setDtlsConfiguration() peut définir la version préférée avant le début de la poignée de main.

Voir aussi setDtlsConfiguration(), QSslConfiguration, QSslConfiguration::defaultDtlsConfiguration(), et QSslConfiguration::setProtocol().

bool QDtls::setCookieGeneratorParameters(const QDtls::GeneratorParameters &params)

Définit l'algorithme de hachage cryptographique et le secret à partir de params. Cette fonction n'est nécessaire que pour une connexion côté serveur QDtls. Retourne true en cas de succès.

Voir aussi cookieGeneratorParameters(), doHandshake(), QDtlsClientVerifier, et QDtlsClientVerifier::cookieGeneratorParameters().

bool QDtls::setDtlsConfiguration(const QSslConfiguration &configuration)

Définit la configuration TLS de la connexion à partir de configuration et renvoie true en cas de succès.

Voir aussi dtlsConfiguration() et doHandshake().

void QDtls::setMtuHint(quint16 mtuHint)

mtuHint est l'unité de transmission maximale (MTU), découverte ou devinée par l'application. L'application n'est pas tenue de définir cette valeur.

Voir également mtuHint() et QAbstractSocket::PathMtuSocketOption.

bool QDtls::setPeer(const QHostAddress &address, quint16 port, const QString &verificationName = {})

Définit l'adresse de l'homologue, port, et le nom d'hôte et renvoie true en cas de succès. address ne doit pas être null, multicast ou broadcast. verificationName est le nom d'hôte utilisé pour la validation du certificat.

Voir aussi peerAddress(), peerPort() et peerVerificationName().

bool QDtls::setPeerVerificationName(const QString &name)

Définit l'hôte name qui sera utilisé pour la validation du certificat et renvoie true en cas de succès.

Voir aussi peerVerificationName() et setPeer().

bool QDtls::shutdown(QUdpSocket *socket)

Envoie un message d'alerte d'arrêt crypté et ferme la connexion DTLS. L'état de la poignée de main passe à QDtls::HandshakeNotStarted. socket doit être un pointeur valide. Cette fonction renvoie true en cas de succès.

Voir aussi doHandshake().

QSslSocket::SslMode QDtls::sslMode() const

Retourne QSslSocket::SslServerMode pour une connexion côté serveur et QSslSocket::SslClientMode pour un client.

Voir aussi QDtls() et QSslSocket::SslMode.

qint64 QDtls::writeDatagramEncrypted(QUdpSocket *socket, const QByteArray &dgram)

Chiffre dgram et écrit les données chiffrées dans socket. Retourne le nombre d'octets écrits, ou -1 en cas d'erreur. La poignée de main doit être terminée avant d'écrire des données cryptées. socket doit être un pointeur valide.

Voir également doHandshake(), handshakeState(), isConnectionEncrypted() et dtlsError().