Merge 5.10 into 5.10.0v5.10.0-rc3v5.10.0-rc2v5.10.0-rc1v5.10.0

Change-Id: Ia395f65e4e6cb7b7efbebab71e8653d87d028af4

1 files changed, 147 insertions, 0 deletions

diff --git a/src/oauth/qoauth1signature.cpp b/src/oauth/qoauth1signature.cpp
index 722d7f6..6ad38b2 100644
--- a/src/oauth/qoauth1signature.cpp
+++ b/src/oauth/qoauth1signature.cpp
@@ -43,6 +43,45 @@ QT_BEGIN_NAMESPACE
 
 Q_LOGGING_CATEGORY(loggingCategory, "qt.networkauth.oauth1.signature")
 
+/*!
+    \class QOAuth1Signature
+    \inmodule QtNetworkAuth
+    \ingroup oauth
+    \brief Implements OAuth 1 signature methods
+    \since 5.8
+
+    OAuth-authenticated requests can have two sets of credentials:
+    those passed via the "oauth_consumer_key" parameter and those in
+    the "oauth_token" parameter.  In order for the server to verify
+    the authenticity of the request and prevent unauthorized access,
+    the client needs to prove that it is the rightful owner of the
+    credentials.  This is accomplished using the shared-secret (or
+    RSA key) part of each set of credentials.
+
+    OAuth specifies three methods for the client to establish its
+    rightful ownership of the credentials: "HMAC-SHA1", "RSA-SHA1",
+    and "PLAINTEXT".  Each generates a "signature" with which the
+    request is "signed"; the first two use a digest of the data
+    signed in generating this, though the last does not.  The
+    "RSA-SHA1" method is not supported here; it would use an RSA key
+    rather than the shared-secret associated with the client
+    credentials.
+*/
+
+/*!
+    \enum QOAuth1Signature::HttpRequestMethod
+
+    Indicates the HTTP request method.
+
+    \value Head     HEAD method.
+    \value Get      GET method.
+    \value Put      PUT method.
+    \value Post     POST method.
+    \value Delete   DELETE method.
+    \value Custom   Identifies a custom method.
+    \value Unknown  Method not set.
+*/
+
 static_assert(static_cast<int>(QOAuth1Signature::HttpRequestMethod::Head) ==
               static_cast<int>(QNetworkAccessManager::HeadOperation) &&
               static_cast<int>(QOAuth1Signature::HttpRequestMethod::Get) ==
@@ -136,58 +175,111 @@ QByteArray QOAuth1SignaturePrivate::encodeHeaders(const QVariantMap &headers)
     return QUrl::toPercentEncoding(QString::fromLatin1(parameterString(headers)));
 }
 
+/*!
+    Creates a QOAuth1Signature using
+    \list
+        \li \a url as the target address
+        \li \a method as the HTTP method used to send the request
+        \li and the given user \a parameters to augment the request.
+    \endlist
+*/
 QOAuth1Signature::QOAuth1Signature(const QUrl &url, QOAuth1Signature::HttpRequestMethod method,
                                    const QVariantMap &parameters) :
     d(new QOAuth1SignaturePrivate(url, method, parameters))
 {}
 
+/*!
+    Creates a QOAuth1Signature using
+    \list
+        \li \a url as the target address
+        \li \a clientSharedKey as the user token used to verify the
+        signature
+        \li \a tokenSecret as the negotiated token used to verify
+        the signature
+        \li \a method as the HTTP method used to send the request
+        \li and the given user \a parameters to augment the request.
+    \endlist
+*/
 QOAuth1Signature::QOAuth1Signature(const QUrl &url, const QString &clientSharedKey,
                                    const QString &tokenSecret, HttpRequestMethod method,
                                    const QVariantMap &parameters) :
     d(new QOAuth1SignaturePrivate(url, method, parameters, clientSharedKey, tokenSecret))
 {}
 
+/*!
+    Creates a copy of \a other.
+*/
 QOAuth1Signature::QOAuth1Signature(const QOAuth1Signature &other) : d(other.d)
 {}
 
+/*!
+    Move-constructs a QOAuth1Signature instance, taking over the
+    private data \a other was using.
+*/
 QOAuth1Signature::QOAuth1Signature(QOAuth1Signature &&other) : d(other.d)
 {
     other.d = &QOAuth1SignaturePrivate::shared_null;
 }
 
+/*!
+    Destroys the QOAuth1Signature.
+*/
 QOAuth1Signature::~QOAuth1Signature()
 {}
 
+/*!
+    Returns the request method.
+*/
 QOAuth1Signature::HttpRequestMethod QOAuth1Signature::httpRequestMethod() const
 {
     return d->method;
 }
 
+/*!
+    Sets the request \a method.
+*/
 void QOAuth1Signature::setHttpRequestMethod(QOAuth1Signature::HttpRequestMethod method)
 {
     d->method = method;
 }
 
+/*!
+    Returns the URL.
+*/
 QUrl QOAuth1Signature::url() const
 {
     return d->url;
 }
 
+/*!
+    Sets the URL to \a url.
+*/
 void QOAuth1Signature::setUrl(const QUrl &url)
 {
     d->url = url;
 }
 
+/*!
+    Returns the parameters.
+*/
 QVariantMap QOAuth1Signature::parameters() const
 {
     return d->parameters;
 }
 
+/*!
+    Sets the \a parameters.
+*/
 void QOAuth1Signature::setParameters(const QVariantMap &parameters)
 {
     d->parameters = parameters;
 }
 
+/*!
+    Adds the request \a body to the signature. When a POST request
+    body contains arguments they should be included in the signed
+    data.
+*/
 void QOAuth1Signature::addRequestBody(const QUrlQuery &body)
 {
     const auto list = body.queryItems();
@@ -195,46 +287,79 @@ void QOAuth1Signature::addRequestBody(const QUrlQuery &body)
         d->parameters.insert(it->first, it->second);
 }
 
+/*!
+    Inserts a new pair \a key, \a value into the signature. When a
+    POST request body contains arguments they should be included in
+    the signed data.
+*/
 void QOAuth1Signature::insert(const QString &key, const QVariant &value)
 {
     d->parameters.insert(key, value);
 }
 
+/*!
+    Retrieves the list of keys of parameters included in the signed
+    data.
+*/
 QList<QString> QOAuth1Signature::keys() const
 {
     return d->parameters.uniqueKeys();
 }
 
+/*!
+    Removes \a key and any associated value from the signed data.
+*/
 QVariant QOAuth1Signature::take(const QString &key)
 {
     return d->parameters.take(key);
 }
 
+/*!
+    Returns the value associated with \a key, if present in the
+    signed data, otherwise \a defaultValue.
+*/
 QVariant QOAuth1Signature::value(const QString &key, const QVariant &defaultValue) const
 {
     return d->parameters.value(key, defaultValue);
 }
 
+/*!
+    Returns the user secret used to generate the signature.
+*/
 QString QOAuth1Signature::clientSharedKey() const
 {
     return d->clientSharedKey;
 }
 
+/*!
+    Sets \a secret as the user secret used to generate the signature.
+*/
 void QOAuth1Signature::setClientSharedKey(const QString &secret)
 {
     d->clientSharedKey = secret;
 }
 
+/*!
+    Returns the negotiated secret used to generate the signature.
+*/
 QString QOAuth1Signature::tokenSecret() const
 {
     return d->tokenSecret;
 }
 
+/*!
+    Sets \a secret as the negotiated secret used to generate the
+    signature.
+*/
 void QOAuth1Signature::setTokenSecret(const QString &secret)
 {
     d->tokenSecret = secret;
 }
 
+/*!
+    Generates the HMAC-SHA1 signature using the client shared secret
+    and, where available, token secret.
+*/
 QByteArray QOAuth1Signature::hmacSha1() const
 {
     QMessageAuthenticationCode code(QCryptographicHash::Sha1);
@@ -243,17 +368,29 @@ QByteArray QOAuth1Signature::hmacSha1() const
     return code.result();
 }
 
+/*!
+    Generates the RSA-SHA1 signature.
+
+    \note Currently this method is not supported.
+*/
 QByteArray QOAuth1Signature::rsaSha1() const
 {
     qCCritical(loggingCategory, "RSA-SHA1 signing method not supported");
     return QByteArray();
 }
 
+/*!
+    Generates the PLAINTEXT signature.
+*/
 QByteArray QOAuth1Signature::plainText() const
 {
     return plainText(d->clientSharedKey, d->tokenSecret);
 }
 
+/*!
+    Generates a PLAINTEXT signature from the client secret
+    \a clientSharedKey and the token secret \a tokenSecret.
+*/
 QByteArray QOAuth1Signature::plainText(const QString &clientSharedKey,
                                        const QString &tokenSecret)
 {
@@ -262,11 +399,18 @@ QByteArray QOAuth1Signature::plainText(const QString &clientSharedKey,
     return ret;
 }
 
+/*!
+    Swaps signature \a other with this signature. This operation is
+    very fast and never fails.
+*/
 void QOAuth1Signature::swap(QOAuth1Signature &other)
 {
     qSwap(d, other.d);
 }
 
+/*!
+    Copy-assignment operator.
+*/
 QOAuth1Signature &QOAuth1Signature::operator=(const QOAuth1Signature &other)
 {
     if (d != other.d) {
@@ -276,6 +420,9 @@ QOAuth1Signature &QOAuth1Signature::operator=(const QOAuth1Signature &other)
     return *this;
 }
 
+/*!
+    Move-assignment operator.
+*/
 QOAuth1Signature &QOAuth1Signature::operator=(QOAuth1Signature &&other)
 {
     QOAuth1Signature moved(std::move(other));