NAME
    HTTP::PublicKeyPins - Generate RFC 7469 HTTP Public Key Pin (HPKP)
    header values

VERSION
    Version 0.07

SYNOPSIS
    Make it more difficult for the bad guys to Man-In-The-Middle your users
    TLS sessions

        use HTTP::Headers();
        use HTTP::PublicKeyPins qw( pin_sha256 );

        ...
        my $h = HTTP::Headers->new();
        $h->header( 'Public-Key-Pins-Report-Only',
                'pin-sha256="'
              . pin_sha256('/etc/pki/tls/certs/example.pem')
              . '"; pin-sha256="'
              . pin_sha256('/etc/pki/tls/certs/backup.pem')
              . '"; report-uri="https://example.com/pkp-report.pl' );

DESCRIPTION
    This module allows the calculation of RFC 7469 HTTP Public Key Pin
    header values. This can be used to verify your TLS session to a remote
    server has not been hit by a Man-In-The-Middle attack OR to instruct
    your users to ignore any TLS sessions to your web service that does not
    use your Public Key

EXPORT
  pin_sha256
    This function accepts the path to a X.509 Certificate
    <https://en.wikipedia.org/wiki/X.509>. It will load the public key from
    the certificate and prepare the appropriate value for the pin_sha256
    parameter of the Public-Key-Pins value. This function will also make an
    attempt to read public keys (in PEM format). Patches for other formats
    are encouraged.

SUBROUTINES/METHODS
    None. This module only has the one exported function.

DIAGNOSTICS
    "Failed to open %s for reading"
        Failed to open the supplied X.509 Certificate file

    "Failed to read from %s"
        Failed to read from the supplied X.509 Certificate file

    "%s is not an X.509 Certificate"
        The supplied input file does not look like X.509 Certificate File.
        The X.509 Certificate file may be encoded in PEM or DER format. A
        PEM encoded X.509 Certificate file has the following header

          -----BEGIN CERTIFICATE-----

CONFIGURATION AND ENVIRONMENT
    HTTP::PublicKeyPins requires no configuration files or environment
    variables.

DEPENDENCIES
    HTTP::PublicKeyPins requires the following non-core modules

      Crypt::OpenSSL::X509;
      Crypt::OpenSSL::RSA;
      Digest

INCOMPATIBILITIES
    None known.

SEE ALSO
    RFC 7469 - Public Key Pinning Extension for HTTP
    <http://tools.ietf.org/html/rfc7469>
    X.509 Certificate <https://en.wikipedia.org/wiki/X.509>

AUTHOR
    David Dick, "<ddick at cpan.org>"

BUGS AND LIMITATIONS
    Please report any bugs or feature requests to "bug-http-publickeypins at
    rt.cpan.org", or through the web interface at
    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=HTTP-PublicKeyPins>. I
    will be notified, and then you'll automatically be notified of progress
    on your bug as I make changes.

SUPPORT
    You can find documentation for this module with the perldoc command.

        perldoc HTTP::PublicKeyPins

    You can also look for information at:

    *   RT: CPAN's request tracker (report bugs here)

        <http://rt.cpan.org/NoAuth/Bugs.html?Dist=HTTP-PublicKeyPins>

    *   AnnoCPAN: Annotated CPAN documentation

        <http://annocpan.org/dist/HTTP-PublicKeyPins>

    *   CPAN Ratings

        <http://cpanratings.perl.org/d/HTTP-PublicKeyPins>

    *   Search CPAN

        <http://search.cpan.org/dist/HTTP-PublicKeyPins/>

LICENSE AND COPYRIGHT
    Copyright 2015 David Dick.

    This module is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself. This program is distributed in the
    hope that it will be useful, but WITHOUT ANY WARRANTY; without even the
    implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.