view release on metacpan or  search on metacpan

lib/Crypt/SecretBuffer/PEM.pm  view on Meta::CPAN

=head2 parse_all

  my @pem_blocks= Crypt::SecretBuffer::PEM->parse_all($span, %options);

A file can contain more than one PEM block (such as a SSL certificate chain, and its key)
This just calls L</parse> in a loop until no more PEM blocks are found.

=head2 new

  my $pem= Crypt::SecretBuffer::PEM->new(%attributes);

You can construct a PEM object from attributes, in case you want to serialize your own data.

=head1 ATTRIBUTES

=head2 label

The text from the PEM begin-marker:

   -----BEGIN SOME LABEL-----
   ...
   -----END SOME LABEL-----

In this case the attribute would hold C<< 'SOME LABEL' >>.

=head2 buffer

A L<Crypt::SecretBuffer> holding the complete PEM text from BEGIN marker to END marker, inclusive.

=head2 header_kv

PEM format has optional header C<< 'NAME: VALUE' >> pairs that can appear right after the
BEGIN marker.  When parsed, leading and trailing whitespace are removed from keys and values.
When written, keys and values may not contain leading or trailing whitespace, or any control
characters.  This attribute presents them in their original order as an arrayref of
C<< [ $key0, $value0, $key1, $value1, ... ] >>.

Note that the values can be L<Span|Crypt::SecretBuffer::Span> objects if you used the
C<secret_headers> option.

=head2 headers

  my $values_arrayref= $pem->headers->get_values('example');
  my $value_maybe_arrayref= $pem->headers->{example};
  $pem->headers->{example}= $value;
  $pem->headers->append('example', $value);

For convenience, you can access the headers by name using this attribute, which masquerades as
L<both a hashref and an object with methods|Crypt::SecretBuffer::PEM::Headers>.
This object/hashref only provides a view of the L<header_kv> array, and is not particularly
efficient at reading or writing it.  (but, it's very convenient)

If there are multiple header keys with the same name, the value returned for that name is an
arrayref of all the values.

=head2 content

A L<Span|Crypt::SecretBuffer::Span> or SecretBuffer that contains the bytes of the PEM payload.
This span created by L</parse> has C<< encoding => BASE64 >> set, which affects the
character-based methods like C<parse>, but has not actually been Base64-decoded, which matters
for methods like C<length> or C<memcmp>.

=head1 METHODS

=head2 serialize

  $buffer= $pem->serialize;

This writes a PEM block into a SecretBuffer object.  The headers (if any) come from L</header_kv>,
falling back to the L</headers> hashref.

=head1 VERSION

version 0.024

=head1 AUTHOR

Michael Conrad <mike@nrdvana.net>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Michael Conrad.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut