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

VERSION
    Version 0.11

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.req')
              . '"; 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
    <http://tools.ietf.org/html/rfc5280>. 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 (SubjectPublicKeyInfo
    <http://tools.ietf.org/html/rfc5280#section-4.1.2.7> or PKCS#1
    <https://tools.ietf.org/html/rfc2437>) or DER format) and PKCS#10
    Certificate Requests <https://tools.ietf.org/html/rfc2986> in PEM or DER
    format.

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, PKCS10 Certificate
        Request or Public Key file

    "Failed to read from %s"
        Failed to read from the X.509 Certificate, PKCS10 Certificate
        Request or Public Key file

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

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

        A PEM encoded PKCS#10 Certificate Request has the following header

          -----BEGIN CERTIFICATE REQUEST-----

        A PEM encoded PKCS#1 Public Key has the following header

          -----BEGIN RSA PUBLIC KEY-----

        A PEM encoded SubjectPublicKeyInfo Public Key has the following
        header

          -----BEGIN PUBLIC KEY-----

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

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

      Convert::ASN1
      Crypt::OpenSSL::PKCS10
      Crypt::OpenSSL::RSA
      Crypt::OpenSSL::X509
      Digest

INCOMPATIBILITIES
    None known.

SEE ALSO
    RFC 7469 - Public Key Pinning Extension for HTTP
    <http://tools.ietf.org/html/rfc7469>
    X.509 Certificate <http://tools.ietf.org/html/rfc5280>
    PKCS#1 <https://tools.ietf.org/html/rfc2437>
    PKCS#10 <https://tools.ietf.org/html/rfc2986>

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.

