PHP RFC: New Curl URL API

• Version: 0.9
• Date: 2022-06-21
• Author: Pierrick Charron pierrick@php.net
• Status: Under discussion
• First Published at: https://wiki.php.net/rfc/curl-url-api

Since its version 7.62.0 [1], libcurl features a brand new URL API [2] that can be used to parse and generate URLs, using libcurl’s own parser. One of the goal of this API is to tighten a problematic vulnerable area for applications where the URL parser library would believe one thing and libcurl another. This could and has sometimes led to security problems [3].

The current RFC propose the addition of 2 new classes CurlUrl and CurlUrlException. Those two classes will only exists if the version of libcurl installed on the system is greater or equal to 7.62. If the version is older those 2 classes will not exists.

/* libcurl >= 7.62.0 */
final class CurlUrl implements Stringable
{
    public const APPEND_QUERY = UNKNOWN;
    public const DEFAULT_PORT = UNKNOWN;
    public const DEFAULT_SCHEME = UNKNOWN;
    public const DISALLOW_USER = UNKNOWN;
    public const GUESS_SCHEME = UNKNOWN;
    public const NO_DEFAULT_PORT = UNKNOWN;
    public const ALLOW_UNSUPPORTED_SCHEME = UNKNOWN;
    public const PATH_AS_IS = UNKNOWN;
    public const URL_DECODE = UNKNOWN;
    public const URL_ENCODE = UNKNOWN;
 
    /* libcurl >= 7.67.0 */
    public const NO_AUTHORITY = UNKNOWN;
 
    /* libcurl >= 7.78.0 */
    public const ALLOW_SPACE = UNKNOWN;
 
    public function __construct(?string $url = null, int $flags = 0) {}
    public function get(int $flags = 0): string {}
    public function set(?string $url, int $flags = 0): CurlUrl {}
    public function getHost(): ?string {}
    public function setHost(?string $host): CurlUrl {}
    public function getScheme(): ?string {}
    public function setScheme(?string $scheme, int $flags = 0): CurlUrl {}
    public function getPort(int $flags = 0): ?int {}
    public function setPort(?int $port): CurlUrl {}
    public function getPath(int $flags = 0): string {}
    public function setPath(?string $scheme, int $flags = 0): CurlUrl {}
    public function getQuery(int $flags = 0): ?string {}
    public function setQuery(?string $query, int $flags = 0): CurlUrl {}
    public function getFragment(int $flags = 0): ?string {}
    public function setFragment(?string $fragment, int $flags = 0): CurlUrl {}
    public function getUser(int $flags = 0): ?string {}
    public function setUser(?string $user, int $flags = 0): CurlUrl {}
    public function getPassword(int $flags = 0): ?string {}
    public function setPassword(?string $password, int $flags = 0): CurlUrl {}
    public function getOptions(int $flags = 0): ?string {}
    public function setOptions(?string $options, int $flags = 0): CurlUrl {}
    public function __toString(): string {}
 
    /* libcurl >= 7.65.0 */
    public function getZoneId(int $flags = 0): ?string {}
    public function setZoneId(?string $zoneid, int $flags = 0): CurlUrl {}
}

Create a new CurlUrl object. Implementation is similar to :

public function __construct(?string $url = null, int $flags = 0) {
    $this->set($url, $flags);
}

Return the full, normalized, and possibly cleaned up URL version of what was previously parsed.

Set the full URL of the CurlUrl instance. If the object is already populated with a URL, the new URL can be relative to the previous. Setting $url to NULL will set all parts of the object to null.

Get the Host part of the URL.

Set the host part of the URL. If it is IDNA the string must then be encoded as your locale says or UTF-8. If it is a bracketed IPv6 numeric address it may contain a zone id (or you can use CurlUrl::setZoneid()).

Get the scheme part of the URL.

Set the scheme part of the URL. Libcurl only accepts setting schemes up to 40 bytes long.

Get the port part of the URL.

Set the port part of the URL. The given port number must be between 1 and 65535. Anything else will throw an exception.

Get the path part of the URL.

Set the path part of the URL. If a path is set in the URL without a leading slash, a slash will be inserted automatically when this URL is read from the handle.

Get the query part of the URL.

Set the query part of the URL. The question mark in the URL is not part of the actual query contents.

Get the fragment part of the URL. The hash sign in the URL is not part of the actual fragment contents.

Set the fragement part of the URL.

Get the user part of the URL.

Set the user part of the URL.

Get the password part of the URL.

Set the password part of the URL.

Get the options part of the URL.

Set the options part of the URL.

Get the zone id part of the URL.

Set the zone id part of the URL.

Same as calling CurlUrl::get()

The CurlUrlException class represents an error raised by libcurl. The constants exposed in this class are all the code that CurlUrlException::getCode() could return. Those code are internally mapped to CURLUE_* error codes that libcurl could raise. Those constants may vary depending on the version of libcurl ext/curl was compiled with.

If ext/curl was compiled with libcurl > 7.80 then CurlUrlException::getMessage() will return a user friendly message that will discriber the problem. (Exemple: Malformed input to a URL function).

/* libcurl >= 7.62.0 */
final class CurlUrlException extends Exception
{
    public const BAD_PORT_NUMBER = UNKNOWN;
    public const MALFORMED_INPUT = UNKNOWN;
    public const OUT_OF_MEMORY = UNKNOWN;
    public const UNSUPPORTED_SCHEME = UNKNOWN;
    public const URL_DECODING_FAILED = UNKNOWN;
    public const USER_NOT_ALLOWED = UNKNOWN;
 
    /* libcurl >= 7.81.0 */
    public const BAD_FILE_URL = UNKNOWN;
    public const BAD_FRAGMENT = UNKNOWN;
    public const BAD_HOSTNAME = UNKNOWN;
    public const BAD_IPV6 = UNKNOWN;
    public const BAD_LOGIN = UNKNOWN;
    public const BAD_PASSWORD = UNKNOWN;
    public const BAD_PATH = UNKNOWN;
    public const BAD_QUERY = UNKNOWN;
    public const BAD_SCHEME = UNKNOWN;
    public const BAD_SLASHES = UNKNOWN;
    public const BAD_USER = UNKNOWN;
}

None, except that the class names CurlUrl, CurlException will be declared by PHP and conflict with applications declaring one of the same class name in the global namespace.

8.2

The current implementation of the CurlUrl class is mutable. We might want to add a new ImmutableCurlUrl class.

As per the voting RFC a yes/no vote with a 2/3 majority is needed for this proposal to be accepted.

https://github.com/php/php-src/pull/8770

N/A

1. https://daniel.haxx.se/blog/2018/10/31/curl-7-62-0-moar-stuff/
2. https://daniel.haxx.se/blog/2018/09/09/libcurl-gets-a-url-api/
3. https://www.blackhat.com/docs/us-17/thursday/us-17-Tsai-A-New-Era-Of-SSRF-Exploiting-URL-Parser-In-Trending-Programming-Languages.pdf