QDtls Class

メンバー関数ドキュメント

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

QDtls オブジェクトを作成します。parent はQObject コンストラクタに渡されます。mode は、サーバー側 DTLS 接続の場合はQSslSocket::SslServerMode となり、クライアントの場合はQSslSocket::SslClientMode となります。

sslMode() およびQSslSocket::SslModeも参照 。

[virtual noexcept] QDtls::~QDtls()

QDtls オブジェクトを破棄する。

bool QDtls::abortHandshake(QUdpSocket *socket)

進行中のハンドシェイクを中止する。socket で進行中だった場合はtrueを返し、そうでない場合は適切なエラーを設定してfalseを返す。

doHandshake() およびresumeHandshake()も参照 。

QDtls::GeneratorParameters QDtls::cookieGeneratorParameters() const

現在のハッシュアルゴリズムとシークレットを返す。デフォルトのものか、あるいはsetCookieGeneratorParameters() のコールによって設定されたものである。

デフォルトのハッシュアルゴリズムは、Qt がそれをサポートするように設定されている場合はQCryptographicHash::Sha256 で、そうでない場合はQCryptographicHash::Sha1 です。デフォルトの秘密は、バックエンド固有の暗号化された強力な擬似乱数生成器から取得されます。

setCookieGeneratorParameters()、QDtlsClientVerifier 、および cookieGeneratorParameters()も参照してください 。

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

dgram を復号化し、その内容をプレーンテキストとして返す。データグラムを復号化する前に、ハンドシェイクを完了しなければならない。TLSメッセージのタイプによって、接続はsocket に書き込むかもしれない。 は有効なポインタでなければならない。

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

DTLS ハンドシェイクを開始または継続する。socket は有効なポインタでなければならない。サーバー側のDTLSハンドシェイクを開始する場合、dgram には、QUdpSocket から読み込まれた最初の ClientHelloメッセージが含まれていなければならない。 この関数は、エラーが見つからなかった場合、true を返す。ハンドシェイクの状態はhandshakeState()を使用してテストできる。false returnは何らかのエラーが発生したことを意味する。より詳細な情報はdtlsError()を使用する。

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

handshakeState()、dtlsError()、ignoreVerificationErrors()、resumeHandshake()、abortHandshake()も参照 。

QSslConfiguration QDtls::dtlsConfiguration() const

デフォルトのDTLS構成、またはそれ以前にsetDtlsConfiguration() をコールして設定した構成のいずれかを返す。

setDtlsConfiguration() およびQSslConfiguration::defaultDtlsConfiguration()も参照 。

QDtlsError QDtls::dtlsError() const

接続で最後に発生したエラーまたはQDtlsError::NoError を返す。

dtlsErrorString() およびQDtlsError も参照 。

QString QDtls::dtlsErrorString() const

接続で最後に発生したエラーの説明をテキストで返すか、空の文字列を返します。

dtlsError()も参照 。

bool QDtls::handleTimeout(QUdpSocket *socket)

ハンドシェイク中にタイムアウトが発生すると、handshakeTimeout() シグナルが発行される。アプリケーションは、ハンドシェイク・メッセージを再送するために handleTimeout() を呼び出す必要がある。handleTimeout() は、タイムアウトが発生した場合はtrue を返し、そうでない場合は false を返す。socket は有効なポインタでなければならない。

handshakeTimeout()も参照のこと 。

QDtls::HandshakeState QDtls::handshakeState() const

このQDtls の現在のハンドシェーク状態を返す。

doHandshake() およびQDtls::HandshakeState も参照のこと 。

[signal] void QDtls::handshakeTimeout()

パケットロスは、ハンドシェーク・フェーズのタイムアウトにつながる可能性がある。この場合、QDtls は handshakeTimeout() シグナルを発する。handleTimeout() を呼び出して、ハンドシェーク・メッセージを再送する：

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

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

handleTimeout()も参照 。

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

このメソッドは、errorsToIgnore で指定されたエラーのみを無視するようにQDtls に指示する。

例えば、自己署名証明書を使用するサーバに接続したい場合、以下のスニペットを考 慮してほしい：

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

この関数は、doHandshake （ ）がQDtlsError::PeerVerificationError エラーに遭遇した後に呼び出すこともでき、その場合はresumeHandshake （ ）を呼び出してハンドシェイクを再開する。

この関数を後で呼び出すと、前の呼び出しで渡されたエラーのリストが置き換えられる。この関数を空のリストで呼び出すと、無視したいエラーのリストを消去できる。

doHandshake()、resumeHandshake()、QSslErrorも参照のこと 。

bool QDtls::isConnectionEncrypted() const

DTLSハンドシェイクが正常に完了した場合、true を返す。

doHandshake() およびhandshakeState() も参照 。

quint16 QDtls::mtuHint() const

setMtuHint() で設定した値を返す。デフォルト値は 0 である。

setMtuHint()も参照 。

QHostAddress QDtls::peerAddress() const

setPeer() で設定した相手のアドレス、またはQHostAddress::Null を返す。

setPeer()も参照 。

quint16 QDtls::peerPort() const

setPeer() で設定されたピアのポート番号、または 0 を返します。

setPeer()も参照 。

QList<QSslError> QDtls::peerVerificationErrors() const

相手の ID を確立する際に見つかったエラーを返します。

エラーが発生したにもかかわらず接続を続行する場合は、ignoreVerificationErrors() を呼び出す必要があります。

QString QDtls::peerVerificationName() const

setPeer() またはsetPeerVerificationName() で設定されたホスト名を返します。デフォルト値は空文字列である。

setPeerVerificationName() およびsetPeer()も参照 。

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

QDtls は、PSK 暗号スイートをネゴシエートする際にこのシグナルを発行する。

PSKを使用する場合、TLSハンドシェイクを継続するために、クライアントは有効なIDと有効な事前共有鍵をサーバーに送信しなければならない。アプリケーションは、このシグナルに接続されたスロットに、渡されたauthenticator オブジェクトを必要に応じて入力することで、この情報を提供することができる。

QSslPreSharedKeyAuthenticatorも参照のこと 。

bool QDtls::resumeHandshake(QUdpSocket *socket)

ハンドシェーク中にピア検証エラーが無視された場合、resumeHandshake() はハンドシェークを再開して完了し、true を返す。socket は有効なポインタでなければならない。ハンドシェークを再開できなかった場合はfalse を返す。

doHandshake()、abortHandshake()、peerVerificationErrors()、ignoreVerificationErrors()も参照のこと 。

QSslCipher QDtls::sessionCipher() const

この接続で使用されている暗号cipher を返すか、接続が暗号化されていない場合は NULL 暗号を返す。セッションの暗号はハンドシェーク時に選択される。暗号はデータの暗号化と復号に使用されます。

QSslConfiguration には、ハンドシェークフェーズで最終的にセッション暗号を選択する暗号の順序リストを設定する関数が用意されています。この順序付きリストは、ハンドシェークフェーズの開始前に設定されている必要がある。

QSslConfiguration 、setDtlsConfiguration()、dtlsConfiguration()も参照のこと 。

QSsl::SslProtocol QDtls::sessionProtocol() const

この接続で使用されている DTLS プロトコルのバージョン、あるいは接続がまだ暗号化されていない場合は UnknownProtocol を返す。接続のプロトコルはハンドシェーク時に選択されます。

setDtlsConfiguration() は、ハンドシェークが始まる前に優先バージョンを設定することができます。

setDtlsConfiguration()、QSslConfiguration 、QSslConfiguration::defaultDtlsConfiguration()、QSslConfiguration::setProtocol()も参照 。

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

暗号化ハッシュアルゴリズムとシークレットをparams から設定する。 この関数は、サーバー側のQDtls 接続にのみ必要である。成功するとtrue を返す。

cookieGeneratorParameters()、doHandshake()、QDtlsClientVerifier 、およびQDtlsClientVerifier::cookieGeneratorParameters()も参照 。

bool QDtls::setDtlsConfiguration(const QSslConfiguration &configuration)

接続のTLS構成をconfiguration から設定し、成功すればtrue を返す。

dtlsConfiguration() およびdoHandshake()も参照のこと 。

void QDtls::setMtuHint(quint16 mtuHint)

mtuHint は最大伝送単位（MTU）であり、アプリケーションによって発見されるか、推測される。アプリケーションはこの値を設定する必要はない。

mtuHint() およびQAbstractSocket::PathMtuSocketOption も参照 。

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

ピアのアドレス、port 、およびホスト名を設定し、成功するとtrue を返す。address は、NULL、マルチキャスト、またはブロードキャストであってはならない。verificationName は、証明書の検証に使用されるホスト名である。

peerAddress()、peerPort()、およびpeerVerificationName()も参照 。

bool QDtls::setPeerVerificationName(const QString &name)

証明書の検証に使用するホストname を設定し、成功した場合はtrue を返す。

peerVerificationName() およびsetPeer()も参照のこと 。

bool QDtls::shutdown(QUdpSocket *socket)

暗号化されたシャットダウン警告メッセージを送信し、DTLS接続を閉じる。ハンドシェーク状態はQDtls::HandshakeNotStarted に変化する。socket は有効なポインタでなければならない。この関数は成功するとtrue を返す。

doHandshake()も参照のこと 。

QSslSocket::SslMode QDtls::sslMode() const

サーバー側接続の場合はQSslSocket::SslServerMode を、クライアントの場合はQSslSocket::SslClientMode を返す。

QDtls() およびQSslSocket::SslMode も参照のこと 。

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

dgram を暗号化し、暗号化されたデータをsocket に書き込む。書き込まれたバイト数、またはエラーの場合は -1 を返す。暗号化されたデータを書き込む前に、ハンドシェイクが完了していなければならない。socket は有効なポインタでなければならない。

doHandshake()、handshakeState()、isConnectionEncrypted()、dtlsError()も参照のこと 。