view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    $ENV{PERL_HTTP_TINY_SSL_INSECURE_BY_DEFAULT} to 1.

    Verification is done by checking that that the TLS/SSL connection has a
    valid certificate corresponding to the host name of the connection and
    that the certificate has been verified by a CA. Assuming you trust the
    CA, this will protect against machine-in-the-middle attacks
    <http://en.wikipedia.org/wiki/Machine-in-the-middle_attack>.

    Certificate verification requires a file or directory containing trusted
    CA certificates.

    IO::Socket::SSL::default_ca() is called to detect the default location
    of your CA certificates. This also supports the environment variables
    "SSL_CERT_FILE" and "SSL_CERT_DIR", and will fail over to Mozilla::CA if
    no certs are found.

    If IO::Socket::SSL::default_ca() is not able to find usable CA
    certificates, HTTP::Tiny will search several well-known system-specific
    default locations for a CA certificate file as a last resort:

    *   /etc/ssl/certs/ca-certificates.crt

    *   /etc/pki/tls/certs/ca-bundle.crt

    *   /etc/ssl/ca-bundle.pem

    *   /etc/openssl/certs/ca-certificates.crt

    *   /etc/ssl/cert.pem

    *   /usr/local/share/certs/ca-root-nss.crt

    *   /etc/pki/tls/cacert.pem

    *   /etc/certs/ca-certificates.crt

    An error will be occur if "verify_SSL" is true and no CA certificate
    file is available.

    If you desire complete control over TLS/SSL connections, the
    "SSL_options" attribute lets you provide a hash reference that will be
    passed through to IO::Socket::SSL::start_SSL(), overriding any options
    set by HTTP::Tiny. For example, to provide your own trusted CA file:

        SSL_options => {
            SSL_ca_file => $file_path,
        }

    The "SSL_options" attribute could also be used for such things as
    providing a client certificate for authentication to a server or
    controlling the choice of cipher used for the TLS/SSL connection. See
    IO::Socket::SSL documentation for details.

PROXY SUPPORT
    HTTP::Tiny can proxy both "http" and "https" requests. Only Basic proxy
    authorization is supported and it must be provided as part of the proxy
    URL: "http://user:pass@proxy.example.com/".

    HTTP::Tiny supports the following proxy environment variables:

    *   http_proxy or HTTP_PROXY

    *   https_proxy or HTTPS_PROXY

    *   all_proxy or ALL_PROXY

    If the "REQUEST_METHOD" environment variable is set, then this might be
    a CGI process and "HTTP_PROXY" would be set from the "Proxy:" header,
    which is a security risk. If "REQUEST_METHOD" is set, "HTTP_PROXY" (the
    upper case variant only) is ignored, but "CGI_HTTP_PROXY" is considered
    instead.

    Tunnelling "https" over an "http" proxy using the CONNECT method is
    supported. If your proxy uses "https" itself, you can not tunnel "https"
    over it.

    Be warned that proxying an "https" connection opens you to the risk of a
    man-in-the-middle attack by the proxy server.

    The "no_proxy" environment variable is supported in the format of a
    comma-separated list of domain extensions proxy should not be used for.

    Proxy arguments passed to "new" will override their corresponding
    environment variables.

LIMITATIONS
    HTTP::Tiny is *conditionally compliant* with the HTTP/1.1 specifications
    <http://www.w3.org/Protocols/>:

    *   "Message Syntax and Routing" [RFC7230]

    *   "Semantics and Content" [RFC7231]

    *   "Conditional Requests" [RFC7232]

    *   "Range Requests" [RFC7233]

    *   "Caching" [RFC7234]

    *   "Authentication" [RFC7235]

    It attempts to meet all "MUST" requirements of the specification, but
    does not implement all "SHOULD" requirements. (Note: it was developed
    against the earlier RFC 2616 specification and may not yet meet the
    revised RFC 7230-7235 spec.) Additionally, HTTP::Tiny supports the
    "PATCH" method of RFC 5789.

    Some particular limitations of note include:

    *   HTTP::Tiny focuses on correct transport. Users are responsible for
        ensuring that user-defined headers and content are compliant with
        the HTTP/1.1 specification.

    *   Users must ensure that URLs are properly escaped for unsafe
        characters and that international domain names are properly encoded
        to ASCII. See URI::Escape, URI::_punycode and Net::IDN::Encode.

    *   Redirection is very strict against the specification. Redirection is
        only automatic for response codes 301, 302, 307 and 308 if the
        request method is 'GET' or 'HEAD'. Response code 303 is always
        converted into a 'GET' redirection, as mandated by the
        specification. There is no automatic support for status 305 ("Use
        proxy") redirections.

    *   There is no provision for delaying a request body using an "Expect"
        header. Unexpected "1XX" responses are silently ignored as per the
        specification.

    *   Only 'chunked' "Transfer-Encoding" is supported.