view release on metacpan or  search on metacpan

lib/HTTP/Promise/Headers/ContentSecurityPolicy.pm  view on Meta::CPAN

sub object_src { return( shift->_set_get_property_value( 'object-src', @_ ) ); }

sub plugin_types { return( shift->_set_get_property_value( 'plugin-types', @_ ) ); }

sub prefetch_src { return( shift->_set_get_property_value( 'prefetch-src', @_ ) ); }

sub referrer { return( shift->_set_get_property_value( 'referrer', @_ ) ); }

sub report_to { return( shift->_set_get_property_value( 'report-to', @_ ) ); }

sub report_uri { return( shift->_set_get_property_value( 'report-uri', @_ ) ); }

sub require_sri_for { return( shift->_set_get_property_value( 'require-sri-for', @_ ) ); }

sub require_trusted_types_for { return( shift->_set_get_property_value( 'require-trusted-types-for', @_ ) ); }

sub sandbox { return( shift->_set_get_property_value( 'sandbox', @_, { maybe_boolean => 1 } ) ); }

sub script_src { return( shift->_set_get_property_value( 'script-src', @_ ) ); }

sub script_src_elem { return( shift->_set_get_property_value( 'script-src-elem', @_ ) ); }

sub script_src_attr { return( shift->_set_get_property_value( 'script-src-attr', @_ ) ); }

sub style_src { return( shift->_set_get_property_value( 'style-src', @_ ) ); }

sub style_src_attr { return( shift->_set_get_property_value( 'style-src-attr', @_ ) ); }

sub style_src_elem { return( shift->_set_get_property_value( 'style-src-elem', @_ ) ); }

sub trusted_types { return( shift->_set_get_property_value( 'trusted-types', @_, { maybe_boolean => 1 } ) ); }

sub upgrade_insecure_requests { return( shift->_set_get_property_boolean( 'upgrade-insecure-requests', @_ ) ); }

sub worker_src { return( shift->_set_get_property_value( 'worker-src', @_ ) ); }

1;
# NOTE: POD
__END__

=encoding utf-8

=head1 NAME

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

=head1 SYNOPSIS

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

=head1 VERSION

    v0.1.0

=head1 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. Th...

    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

=head1 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 C<undef> as...

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 L</params>, which returns an L<array object|Module::Generic::Array>

=head2 as_string

Returns a string representation of this header field value.

=head2 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/

=head2 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;

=head2 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/

=head2 connect_src

Restricts the URLs which can be loaded using script interfaces.

Example:

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

lib/HTTP/Promise/Headers/ContentSecurityPolicy.pm  view on Meta::CPAN

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

=head2 prefetch_src

Specifies valid sources to be prefetched or prerendered.

Example:

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

=head2 properties

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

=head2 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 C<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:

=over 4

=item C<no-referrer>

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

=item C<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).

=item C<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/.

=item C<origin-when-cross-origin> / C<origin-when-crossorigin>

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

=item C<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.

=back

=head2 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

=head2 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;

=head2 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;

=head2 require_trusted_types_for

Enforces Trusted Types at the DOM XSS injection sinks.

Example:

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

=head2 sandbox

Enables a sandbox for the requested resource similar to the C<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:

=over 4

=item C<allow-downloads>

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

=item C<allow-downloads-without-user-activation>

This is reportedly an experimental value.

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

=item C<allow-forms>

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

=item C<allow-modals>

Allows the page to open modal windows.

=item C<allow-orientation-lock>