The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
HTTP-Promise-v0.1.5
River stage one • 1 direct dependent • 2 total dependents
1 ++
/ HTTP::Promise::Headers::ContentSecurityPolicy

NAME

HTTP::Promise::Headers::ContentSecurityPolicy - Content-Security-Policy Header Field

SYNOPSIS

    use HTTP::Promise::Headers::ContentSecurityPolicy;
    my $csp = HTTP::Promise::Headers::ContentSecurityPolicy->new || 
        die( HTTP::Promise::Headers::ContentSecurityPolicy->error, "\n" );

VERSION

    v0.1.0

DESCRIPTION

The following description is taken from Mozilla documentation.

The HTTP Content-Security-Policy response header allows web site administrators to control resources the user agent is allowed to load for a given page. With a few exceptions, policies mostly involve specifying server origins and script endpoints. This helps guard against cross-site scripting attacks (Cross-site_scripting).

    Content-Security-Policy: default-src 'self'
    Content-Security-Policy: default-src 'self' trusted.com *.trusted.com
    Content-Security-Policy: default-src 'self'; img-src *; media-src media1.com media2.com; script-src userscripts.example.com
    Content-Security-Policy: default-src https://onlinebanking.example.com
    Content-Security-Policy: default-src 'self'; report-uri http://reportcollector.example.com/collector.cgi

METHODS

All the methods below follow the same usage. You can pass a value to set it, whatever it is. It is up to you to proceed and set a value according to standards. The value will be added in order. To completely remove a property, simply pass undef as a value. If nothing is provided, the current value is returned, or an empty string, but not undef, if nothing is set yet.

If you want to modify a value, you probably want to first fetch it, and set it back, unless you already what it should contain.

    $h->default_src( "'self'" ); # now: default-src 'self'
    $h->default_src( "'self' trusted.com *.trusted.com ); # now: default-src 'self' trusted.com *.trusted.com
    my $value = $h->default_src;
    # Remove it
    $h->default_src( undef );

You can get all the properties set by calling "params", which returns an array object

as_string

Returns a string representation of this header field value.

base_uri

Restricts the URLs which can be used in a document's <base> element.

Example:

    Content-Security-Policy: base-uri https://example.com/
    Content-Security-Policy: base-uri https://example.com/ https://dev.example.com/

block_all_mixed_content

You can still use this, but know its use is deprecated.

Prevents loading any assets using HTTP when the page is loaded using HTTPS.

Example:

    Content-Security-Policy: block-all-mixed-content;

child_src

Defines the valid sources for web workers and nested browsing contexts loaded using elements such as <frame> and <iframe>.

Example:

    Content-Security-Policy: child-src https://example.com/
    Content-Security-Policy: child-src https://example.com/ https://dev.example.com/

connect_src

Restricts the URLs which can be loaded using script interfaces.

Example:

    Content-Security-Policy: connect-src https://example.com/

default_src

Serves as a fallback for the other fetch directives.

Example:

    Content-Security-Policy: default-src 'self'

font_src

Specifies valid sources for fonts loaded using @font-face.

Example:

    Content-Security-Policy: font-src https://example.com/

form_action

Restricts the URLs which can be used as the target of a form submissions from a given context.

Example:

    Content-Security-Policy: form-action https://example.com/;
    Content-Security-Policy: form-action https://example.com/ https://dev.example.com/;

frame_ancestors

Specifies valid parents that may embed a page using frame, iframe, object, embed, or applet.

Example:

    Content-Security-Policy: frame-ancestors https://example.com/;
    Content-Security-Policy: frame-ancestors https://example.com/ https://dev.example.com/;

frame_src

Specifies valid sources for nested browsing contexts loading using elements such as <frame> and <iframe>.

Example:

    Content-Security-Policy: frame-src https://example.com/

img_src

Specifies valid sources of images and favicons.

Example:

    Content-Security-Policy: img-src https://example.com/
    Content-Security-Policy: img-src 'self' img.example.com;

manifest_src

Specifies valid sources of application manifest files.

Example:

    Content-Security-Policy: manifest-src https://example.com/

media_src

Specifies valid sources for loading media using the audio , video and track elements.

Example:

    Content-Security-Policy: media-src https://example.com/

Restricts the URLs to which a document can initiate navigation by any means, including <form> (if form-action is not specified), <a>, window.location, window.open, etc.

Example:

    Content-Security-Policy: navigate-to https://example.com/;
    Content-Security-Policy: navigate-to https://example.com/ https://dev.example.com/;

object_src

Specifies valid sources for the object, embed, and applet elements.

Example:

    Content-Security-Policy: object-src https://example.com/

params

Returns the array object used by this header field object containing all the properties set.

plugin_types

You can still use this, but know its use is deprecated.

Restricts the set of plugins that can be embedded into a document by limiting the types of resources which can be loaded.

Example:

    Content-Security-Policy: plugin-types application/x-shockwave-flash

prefetch_src

Specifies valid sources to be prefetched or prerendered.

Example:

    Content-Security-Policy: prefetch-src https://example.com/

properties

Sets or gets an hash or hash reference ot property-value pairs.

referrer

You can still use this, but know its use is deprecated and it is non-standard.

Used to specify information in the Referer (sic) header for links away from a page. Use the Referrer-Policy header instead.

Example:

    Content-Security-Policy: referrer "none";

You can set whatever value you want, but know that, according to rfc, the standard possible values are:

no-referrer

The Referer header will be omitted entirely. No referrer information is sent along with requests.

none-when-downgrade

This is the user agent's default behavior if no policy is specified. The origin is sent as referrer to a-priori as-much-secure destination (HTTPS->HTTPS), but is not sent to a less secure destination (HTTPS->HTTP).

origin

Only send the origin of the document as the referrer in all cases. The document https://example.com/page.html will send the referrer https://example.com/.

origin-when-cross-origin / origin-when-crossorigin

Send a full URL when performing a same-origin request, but only send the origin of the document for other cases.

unsafe-url

Send a full URL (stripped from parameters) when performing a same-origin or cross-origin request. This policy will leak origins and paths from TLS-protected resources to insecure origins. Carefully consider the impact of this setting.

report_to

Fires a SecurityPolicyViolationEvent.

Example:

    Report-To: { "group": "csp-endpoint",
                  "max_age": 10886400,
                  "endpoints": [
                    { "url": "https://example.com/csp-reports" }
                  ] },
                { "group": "hpkp-endpoint",
                  "max_age": 10886400,
                  "endpoints": [
                    { "url": "https://example.com/hpkp-reports" }
                  ] }
    Content-Security-Policy: ...; report-to csp-endpoint

report_uri

Instructs the user agent to report attempts to violate the Content Security Policy. These violation reports consist of JSON documents sent via an HTTP POST request to the specified URI.

Example:

    Content-Security-Policy: default-src https:; report-uri /csp-violation-report-endpoint/
    Content-Security-Policy: default-src https:; report-uri /csp-violation-report-endpoint/ https://dev.example.com/report;

require_sri_for

Requires the use of SRI for scripts or styles on the page.

Example:

    Content-Security-Policy: require-sri-for script;
    Content-Security-Policy: require-sri-for style;
    Content-Security-Policy: require-sri-for script style;

require_trusted_types_for

Enforces Trusted Types at the DOM XSS injection sinks.

Example:

    Content-Security-Policy: require-trusted-types-for 'script';

sandbox

Enables a sandbox for the requested resource similar to the iframe sandbox attribute.

This can be set as a boolean or with a string value:

    # This will add 'sandbox' (without surrounding quotes) as a property
    $h->sandbox(1);
    # Returns true.
    my $rv = $h->sandbox;
    $h->sandbox(0);
    # Returns false.
    my $rv = $h->sandbox;
    # Removes it
    $h->sandbox( undef );
    # Will set sandbox to 'allow-downloads' (without surrounding quotes)
    $h->sandbox( 'allow-downloads' );

It takes an optional value, such as:

allow-downloads

Allows for downloads after the user clicks a button or link.

allow-downloads-without-user-activation

This is reportedly an experimental value.

Allows for downloads to occur without a gesture from the user.

allow-forms

Allows the page to submit forms. If this keyword is not used, this operation is not allowed.

allow-modals

Allows the page to open modal windows.

allow-orientation-lock

Allows the page to disable the ability to lock the screen orientation.

allow-pointer-lock

Allows the page to use the Pointer Lock API.

allow-popups

Allows popups (like from window.open, target="_blank", showModalDialog). If this keyword is not used, that functionality will silently fail.

allow-popups-to-escape-sandbox

Allows a sandboxed document to open new windows without forcing the sandboxing flags upon them. This will allow, for example, a third-party advertisement to be safely sandboxed without forcing the same restrictions upon the page the ad links to.

allow-presentation

Allows embedders to have control over whether an iframe can start a presentation session.

allow-same-origin

Allows the content to be treated as being from its normal origin. If this keyword is not used, the embedded content is treated as being from a unique origin.

allow-scripts

Allows the page to run scripts (but not create pop-up windows). If this keyword is not used, this operation is not allowed.

allow-storage-access-by-user-activation

This is reportedly an experimental value.

Lets the resource request access to the parent's storage capabilities with the Storage Access API.

allow-top-navigation

Allows the page to navigate (load) content to the top-level browsing context. If this keyword is not used, this operation is not allowed.

allow-top-navigation-by-user-activation

Lets the resource navigate the top-level browsing context, but only if initiated by a user gesture.

Example:

    Content-Security-Policy: sandbox;
    Content-Security-Policy: sandbox allow-scripts;

script_src

Specifies valid sources for JavaScript.

Example:

    Content-Security-Policy: script-src https://example.com/
    Content-Security-Policy: script-src 'self' js.example.com;

script_src_elem

Specifies valid sources for JavaScript <script> elements.

Example:

    Content-Security-Policy: script-src-elem https://example.com/
    Content-Security-Policy: script-src-elem https://example.com/ https://dev.example.com/

script_src_attr

Specifies valid sources for JavaScript inline event handlers.

Example:

    Content-Security-Policy: script-src-attr https://example.com/
    Content-Security-Policy: script-src-attr https://example.com/ https://dev.example.com/

style_src

Specifies valid sources for stylesheets.

Example:

    Content-Security-Policy: style-src https://example.com/
    Content-Security-Policy: style-src https://example.com/ https://dev.example.com/
    Content-Security-Policy: style-src 'self' css.example.com;

style_src_attr

Specifies valid sources for inline styles applied to individual DOM elements.

Example:

    Content-Security-Policy: style-src-attr https://example.com/
    Content-Security-Policy: style-src-attr https://example.com/ https://dev.example.com/

style_src_elem

Specifies valid sources for stylesheets <style> elements and <link> elements with rel="stylesheet".

Example:

    Content-Security-Policy: script-src-elem https://example.com/
    Content-Security-Policy: script-src-elem https://example.com/ https://dev.example.com/

trusted_types

Used to specify an allow-list of Trusted Types policies. Trusted Types allows applications to lock down DOM XSS injection sinks to only accept non-spoofable, typed values in place of strings.

Just like "sandbox", this can be set as a boolean or with a string value.

Example:

    # Set it as a boolean value
    $h->trusted_types(1);
    Content-Security-Policy: trusted-types;
    # Set it as a string value
    # You need to set the surrounding single quotes yourself
    $h->trusted_types( "'none'" );
    Content-Security-Policy: trusted-types 'none';
    # Set it to foo
    $h->trusted_types( 'foo' );
    Content-Security-Policy: trusted-types foo;
    Content-Security-Policy: trusted-types foo bar 'allow-duplicates';

upgrade_insecure_requests

Instructs user agents to treat all of a site's insecure URLs (those served over HTTP) as though they have been replaced with secure URLs (those served over HTTPS). This directive is intended for web sites with large numbers of insecure legacy URLs that need to be rewritten.

Example:

    Content-Security-Policy: upgrade-insecure-requests;

worker_src

Specifies valid sources for Worker, SharedWorker, or ServiceWorker scripts.

Example:

    Content-Security-Policy: worker-src https://example.com/
    Content-Security-Policy: worker-src https://example.com/ https://dev.example.com/

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

Mozilla documentation and Mozilla on CSP

https://content-security-policy.com/

HTTP::Promise, HTTP::Promise::Request, HTTP::Promise::Response, HTTP::Promise::Message, HTTP::Promise::Entity, HTTP::Promise::Headers, HTTP::Promise::Body, HTTP::Promise::Body::Form, HTTP::Promise::Body::Form::Data, HTTP::Promise::Body::Form::Field, HTTP::Promise::Status, HTTP::Promise::MIME, HTTP::Promise::Parser, HTTP::Promise::IO, HTTP::Promise::Stream, HTTP::Promise::Exception

COPYRIGHT & LICENSE

Copyright(c) 2022 DEGUEST Pte. Ltd.

All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.