/**
* A string equality function that compares strings in a way that isn't suceptible to timing
* attacks. An attacker can figure out the length of the string, but not the string's value.
*
* Use this when comparing two strings where:
* - one string could be influenced by an attacker
* - the other string contains data an attacker shouldn't know
*
* @param string $a
* @param string $b
* @return bool
*/
static function stringEquals($a, $b)
{
// Be strict with arguments. PHP's liberal types could get us pwned.
if (func_num_args() !== 2) {
throw \InvalidArgumentException("Expecting 2 args, got " . func_num_args() . ".");
}
Checker::argString("a", $a);
Checker::argString("b", $b);
if (strlen($a) !== strlen($b)) {
return false;
}
$result = 0;
for ($i = 0; $i < strlen($a); $i++) {
$result |= ord($a[$i]) ^ ord($b[$i]);
}
return $result === 0;
}
/**
* Perform an OAuth-2-authorized POST request to the Dropbox API. Will automatically
* fill in "User-Agent" and "locale" as well.
*
* @param string $host
* Either the "API" or "API content" hostname from {@link getHost()}.
* @param string $path
* The "path" part of the URL. For example, "/commit_chunked_upload".
* @param array|null $params
* POST parameters.
* @return HttpResponse
*
* @throws Exception
*/
function doPost($host, $path, $params = null)
{
Checker::argString("host", $host);
Checker::argString("path", $path);
return RequestUtil::doPost($this->clientIdentifier, $this->accessToken, $this->userLocale, $host, $path, $params);
}
/**
* Return the last component of a path (the file or folder name).
*
* <code>
* Path::getName("/Misc/Notes.txt") // "Notes.txt"
* Path::getName("/Misc") // "Misc"
* Path::getName("/") // null
* </code>
*
* @param string $path
* The full path you want to get the last component of.
*
* @return null|string
* The last component of `$path` or `null` if the given
* `$path` was `"/"`.
*/
static function getName($path)
{
Checker::argString("path", $path);
if (\substr_compare($path, "/", 0, 1) !== 0) {
throw new \InvalidArgumentException("'path' must start with \"/\"");
}
$l = strlen($path);
if ($l === 1) {
return null;
}
if ($path[$l - 1] === "/") {
throw new \InvalidArgumentException("'path' must not end with \"/\"");
}
$lastSlash = strrpos($path, "/");
return substr($path, $lastSlash + 1);
}
/**
* Call this after the user has visited the authorize URL ({@link start()}), approved your app,
* and was redirected to your redirect URI.
*
* See <a href="https://www.dropbox.com/developers/core/docs#oa2-token">/oauth2/token</a>.
*
* @param array $queryParams
* The query parameters on the GET request to your redirect URI.
*
* @return array
* A <code>list(string $accessToken, string $userId, string $urlState)</code>, where
* <code>$accessToken</code> can be used to construct a {@link Client}, <code>$userId</code>
* is the user ID of the user's Dropbox account, and <code>$urlState</code> is the
* value you originally passed in to {@link start()}.
*
* @throws Exception
* Thrown if there's an error getting the access token from Dropbox.
* @throws WebAuthException_BadRequest
* @throws WebAuthException_BadState
* @throws WebAuthException_Csrf
* @throws WebAuthException_NotApproved
* @throws WebAuthException_Provider
*/
function finish($queryParams)
{
Checker::argArray("queryParams", $queryParams);
$csrfTokenFromSession = $this->csrfTokenStore->get();
Checker::argStringOrNull("this->csrfTokenStore->get()", $csrfTokenFromSession);
// Check well-formedness of request.
if (!isset($queryParams['state'])) {
throw new WebAuthException_BadRequest("Missing query parameter 'state'.");
}
$state = $queryParams['state'];
Checker::argString("queryParams['state']", $state);
$error = null;
$errorDescription = null;
if (isset($queryParams['error'])) {
$error = $queryParams['error'];
Checker::argString("queryParams['error']", $error);
if (isset($queryParams['error_description'])) {
$errorDescription = $queryParams['error_description'];
Checker::argString("queryParams['error_description']", $errorDescription);
}
}
$code = null;
if (isset($queryParams['code'])) {
$code = $queryParams['code'];
Checker::argString("queryParams['code']", $code);
}
if ($code !== null && $error !== null) {
throw new WebAuthException_BadRequest("Query parameters 'code' and 'error' are both set;" . " only one must be set.");
}
if ($code === null && $error === null) {
throw new WebAuthException_BadRequest("Neither query parameter 'code' or 'error' is set.");
}
// Check CSRF token
if ($csrfTokenFromSession === null) {
throw new WebAuthException_BadState();
}
$splitPos = strpos($state, "|");
if ($splitPos === false) {
$givenCsrfToken = $state;
$urlState = null;
} else {
$givenCsrfToken = substr($state, 0, $splitPos);
$urlState = substr($state, $splitPos + 1);
}
if (!Security::stringEquals($csrfTokenFromSession, $givenCsrfToken)) {
throw new WebAuthException_Csrf("Expected " . Util::q($csrfTokenFromSession) . ", got " . Util::q($givenCsrfToken) . ".");
}
$this->csrfTokenStore->clear();
// Check for error identifier
if ($error !== null) {
if ($error === 'access_denied') {
// When the user clicks "Deny".
if ($errorDescription === null) {
throw new WebAuthException_NotApproved("No additional description from Dropbox.");
} else {
throw new WebAuthException_NotApproved("Additional description from Dropbox: {$errorDescription}");
}
} else {
// All other errors.
$fullMessage = $error;
if ($errorDescription !== null) {
$fullMessage .= ": ";
$fullMessage .= $errorDescription;
}
throw new WebAuthException_Provider($fullMessage);
}
}
// If everything went ok, make the network call to get an access token.
list($accessToken, $userId) = $this->_finish($code, $this->redirectUri);
return array($accessToken, $userId, $urlState);
}