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認証が必要になる。

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()も参照のこと 。