view release on metacpan or  search on metacpan

PKCS12.pm  view on Meta::CPAN

package Crypt::OpenSSL::PKCS12;

use warnings;
use strict;
use Exporter;

our $VERSION = '1.99';
our @ISA = qw(Exporter);

our @EXPORT_OK = qw(NOKEYS NOCERTS INFO CLCERTS CACERTS);

use XSLoader;

XSLoader::load 'Crypt::OpenSSL::PKCS12', $VERSION;

END {
  __PACKAGE__->__PKCS12_cleanup();
}

1;

__END__

=pod

=encoding UTF-8

=head1 NAME

Crypt::OpenSSL::PKCS12 - Perl extension to OpenSSL's PKCS12 API.

=head1 SYNOPSIS

  use Crypt::OpenSSL::PKCS12;

  my $pass   = "your password";
  my $pkcs12 = Crypt::OpenSSL::PKCS12->new_from_file('cert.p12');

  print $pkcs12->certificate($pass);
  print $pkcs12->private_key($pass);

  if ($pkcs12->mac_ok($pass)) {
    # MAC verification passed
  }

  # Creating a file
  $pkcs12->create('test-cert.pem', 'test-key.pem', $pass, 'out.p12', 'friendly name');


  # Creating a string
  my $pkcs12_data = $pkcs12->create_as_string('test-cert.pem', 'test-key.pem', $pass, 'friendly name');

  # Reproducing OpenSSL's info
  my $info = $pkcs12->info($pass);

  # Accessing OpenSSL's info as a hash
  my $info_hash = $pkcs12->info_as_hash($pass);

=head1 VERSION

This documentation describes version 1.99 of Crypt::OpenSSL::PKCS12

=head1 DESCRIPTION

PKCS12 is a file format for storing cryptography objects as a single file or string. PKCS12 is commonly used to bundle a private key with its X.509 certificate or to bundle all the members of a chain of trust.

This distribution implements a subset of OpenSSL's PKCS12 API.

=head1 SUBROUTINES/METHODS

=over 4

=item * new( )

Create an empty Crypt::OpenSSL::PKCS12 object. Use C<new_from_string()> or
C<new_from_file()> to load an existing PKCS12 structure.

=item * legacy_support ( )

Returns true if the legacy provider has been successfully loaded by a prior
constructor call (C<new_from_string()> or C<new_from_file()>). Always returns
true on OpenSSL 1.x (where the legacy provider concept does not apply). On
OpenSSL 3.x, returns true only if the legacy provider was loaded during the
most recent constructor call; calling C<legacy_support()> before constructing
an object may return false even if the provider is loadable.

=item * new_from_string( C<$string> )

=item * new_from_file( C<$filename> )

Create a new Crypt::OpenSSL::PKCS12 instance from a binary PKCS12 string or
from a file path respectively. Both forms croak on error (invalid format,
unreadable file, OpenSSL parse failure). The binary string passed to
C<new_from_string()> must not carry Perl's UTF-8 flag; use
C<Encode::encode('octets', $str)> if needed.

=item * certificate( [C<$pass>] )

Returns the end-entity certificate as a PEM-encoded string (Base64 with
C<-----BEGIN CERTIFICATE-----> / C<-----END CERTIFICATE-----> headers).
C<$pass> is required when the PKCS12 file is password-protected. Returns an
empty string if the password is wrong or no client certificate is present.

=item * ca_certificate( [C<$pass>] )

Returns any CA certificates in the chain as a concatenated PEM string.
Returns an empty string if no CA certificates are present. C<$pass> is
required when the PKCS12 file is password-protected.

=item * private_key( [C<$pass>] )

Returns the private key as a PEM-encoded string. C<$pass> is required when
the PKCS12 file is password-protected. Returns an empty string if no private
key is present or if decryption fails (wrong password).

=item * as_string( )

Returns the PKCS12 structure as a raw binary DER string. Useful for writing
to a file or transmitting over a network without touching the filesystem.
The in-memory structure is serialized as-is; no password is needed or accepted.

=item * mac_ok( [C<$pass>] )

Verifies the Message Authentication Code (MAC) of the PKCS12 structure using
C<$pass>. Returns true if the MAC is valid. Croaks on failure (wrong
password, corrupted file, or OpenSSL error).

=item * changepass( C<$old>, C<$new> )

Re-encrypts the PKCS12 structure with a new password. C<$old> is the current
password; C<$new> is the replacement. Returns false on failure.

B<Note:> Changing the PKCS12 password is not supported on OpenSSL 3.x or
4.x for PBES2-encrypted files (the default OpenSSL uses for newly created
PKCS12 files) — C<changepass()> will return false. This is a known
upstream OpenSSL limitation
(L<openssl/openssl#19092|https://github.com/openssl/openssl/issues/19092>),
not specific to this module; only OpenSSL 1.x is confirmed to work. See
L<https://github.com/dsully/perl-crypt-openssl-pkcs12/issues/62> for
details. Consider re-creating the PKCS12 structure with C<create()>
instead.

=item * create( C<$cert>, C<$key>, C<$pass>, C<$output_file>, C<$friendly_name> )

Creates a new PKCS12 file at C<$output_file>. C<$cert> and C<$key> may each be
either a PEM string (detected by a C<"-----"> prefix) or a filesystem path.
C<$pass> is used to encrypt the private key. C<$friendly_name> is optional and
sets the C<friendlyName> bag attribute. Croaks on any OpenSSL error.

=item * create_as_string( C<$cert>, C<$key>, C<$pass>, C<$friendly_name> )

Same as C<create()> but returns the PKCS12 structure as a raw binary DER string
instead of writing to a file. C<$cert> and C<$key> may each be a PEM string or
a filesystem path. C<$friendly_name> is optional. Croaks on any OpenSSL error.

=item * info( C<$pass> )

Returns a string containing the output of information about the pkcs12 file in
the same format as produced by the openssl command:

    openssl pkcs12 -in certs/test_le_1.1.p12 -info -nodes

=item * info_as_hash( C<$pass> )

Places the information about the pkcs12 file, the certificates and keys
in a hash.

The format of the hash is complex to represent the data in the PKCS12 file:

Essentially, the hash follows the format of the -info output.