/ 
HTTP-PublicKeyPins-0.16
River stage zero No dependents
++
 / HTTP::PublicKeyPins

NAME

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

VERSION

Version 0.16

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. 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 or PKCS#1) or DER format), private keys (in PEM PKCS#1 or DER format) and PKCS#10 Certificate Requests 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, Private or Public Key file

Failed to read from %s

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

%s is not an X.509 Certificate, PKCS10 Certificate Request, Private or Public Key

The supplied input file does not look like X.509 Certificate File, PKCS10 Certificate Request, Private 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 PKCS#1 Private Key has the following header

  -----BEGIN RSA PRIVATE 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::PKCS10
  Crypt::OpenSSL::RSA
  Crypt::OpenSSL::X509
  Digest

INCOMPATIBILITIES

None known.

SEE ALSO

RFC 7469 - Public Key Pinning Extension for HTTP
X.509 Certificate
PKCS#1
PKCS#10

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:

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.