1Convert::PEM(3)       User Contributed Perl Documentation      Convert::PEM(3)
2
3
4

NAME

6       Convert::PEM - Read/write encrypted ASN.1 PEM files
7

SYNOPSIS

9           use Convert::PEM;
10           my $pem = Convert::PEM->new(
11                          Name => "DSA PRIVATE KEY",
12                          ASN => qq(
13                              DSAPrivateKey SEQUENCE {
14                                  version INTEGER,
15                                  p INTEGER,
16                                  q INTEGER,
17                                  g INTEGER,
18                                  pub_key INTEGER,
19                                  priv_key INTEGER
20                              }
21                         ));
22
23           my $keyfile = 'private-key.pem';
24           my $pwd = 'foobar';
25
26           my $pkey = $pem->read(
27                          Filename => $keyfile,
28                          Password => $pwd
29                    );
30
31           $pem->write(
32                          Content  => $pkey,
33                          Password => $pwd,
34                          Filename => $keyfile
35                    );
36

DESCRIPTION

38       Convert::PEM reads and writes PEM files containing ASN.1-encoded
39       objects. The files can optionally be encrypted using a symmetric cipher
40       algorithm, such as 3DES. An unencrypted PEM file might look something
41       like this:
42
43           -----BEGIN DH PARAMETERS-----
44           MB4CGQDUoLoCULb9LsYm5+/WN992xxbiLQlEuIsCAQM=
45           -----END DH PARAMETERS-----
46
47       The string beginning "MB4C..." is the Base64-encoded, ASN.1-encoded
48       "object."
49
50       An encrypted file would have headers describing the type of encryption
51       used, and the initialization vector:
52
53           -----BEGIN DH PARAMETERS-----
54           Proc-Type: 4,ENCRYPTED
55           DEK-Info: DES-EDE3-CBC,C814158661DC1449
56
57           AFAZFbnQNrGjZJ/ZemdVSoZa3HWujxZuvBHzHNoesxeyqqidFvnydA==
58           -----END DH PARAMETERS-----
59
60       The two headers ("Proc-Type" and "DEK-Info") indicate information about
61       the type of encryption used, and the string starting with "AFAZ..." is
62       the Base64-encoded, encrypted, ASN.1-encoded contents of this "object."
63
64       The initialization vector ("C814158661DC1449") is chosen randomly.
65

USAGE

67   $pem = Convert::PEM->new( %arg )
68       Constructs a new Convert::PEM object designed to read/write an object
69       of a specific type (given in %arg, see below). Returns the new object
70       on success, "undef" on failure (see ERROR HANDLING for details).
71
72       %arg can contain:
73
74       •   Name
75
76           The name of the object; when decoding a PEM-encoded stream, the
77           name in the encoding will be checked against the value of Name.
78           Similarly, when encoding an object, the value of Name will be used
79           as the name of the object in the PEM-encoded content. For example,
80           given the string "FOO BAR", the output from encode will start with
81           a header like:
82
83               -----BEGIN FOO BAR-----
84
85           Name is a required argument.
86
87       •   ASN
88
89           An ASN.1 description of the content to be either encoded or
90           decoded.
91
92           ASN is a required argument.
93
94       •   Macro
95
96           If your ASN.1 description (in the ASN parameter) includes more than
97           one ASN.1 macro definition, you will want to use the Macro
98           parameter to specify which definition to use when encoding/decoding
99           objects.  For example, if your ASN.1 description looks like this:
100
101               Foo ::= SEQUENCE {
102                   x INTEGER,
103                   bar Bar
104               }
105
106               Bar ::= INTEGER
107
108           If you want to encode/decode a "Foo" object, you will need to tell
109           Convert::PEM to use the "Foo" macro definition by using the Macro
110           parameter and setting the value to "Foo".
111
112           Macro is an optional argument.
113
114   $obj = $pem->decode(%args)
115       Decodes, and, optionally, decrypts a PEM file, returning the object as
116       decoded by Convert::ASN1. The difference between this method and read
117       is that read reads the contents of a PEM file on disk; this method
118       expects you to pass the PEM contents as an argument.
119
120       If an error occurs while reading the file or decrypting/decoding the
121       contents, the function returns undef, and you should check the error
122       message using the errstr method (below).
123
124       %args can contain:
125
126       •   Content
127
128           The PEM contents.
129
130       •   Password
131
132           The password with which the file contents were encrypted.
133
134           If the file is encrypted, this is a mandatory argument (well, it's
135           not strictly mandatory, but decryption isn't going to work without
136           it). Otherwise it's not necessary.
137
138   $blob = $pem->encode(%args)
139       Constructs the contents for the PEM file from an object: ASN.1-encodes
140       the object, optionally encrypts those contents.
141
142       Returns undef on failure (encryption failure, file-writing failure,
143       etc.); in this case you should check the error message using the errstr
144       method (below). On success returns the constructed PEM string.
145
146       %args can contain:
147
148       •   Content
149
150           A hash reference that will be passed to Convert::ASN1::encode, and
151           which should correspond to the ASN.1 description you gave to the
152           new method. The hash reference should have the exact same format as
153           that returned from the read method.
154
155           This argument is mandatory.
156
157       •   Password
158
159           A password used to encrypt the contents of the PEM file. This is an
160           optional argument; if not provided the contents will be
161           unencrypted.
162
163   $obj = $pem->read(%args)
164       Reads, decodes, and, optionally, decrypts a PEM file, returning the
165       object as decoded by Convert::ASN1. This is implemented as a wrapper
166       around decode, with the bonus of reading the PEM file from disk for
167       you.
168
169       If an error occurs while reading the file or decrypting/decoding the
170       contents, the function returns undef, and you should check the error
171       message using the errstr method (below).
172
173       In addition to the arguments that can be passed to the decode method
174       (minus the Content method), %args can contain:
175
176       •   Filename
177
178           The location of the PEM file that you wish to read.
179
180   $pem->write(%args)
181       Constructs the contents for the PEM file from an object: ASN.1-encodes
182       the object, optionally encrypts those contents; then writes the file to
183       disk. This is implemented as a wrapper around encode, with the bonus of
184       writing the file to disk for you.
185
186       Returns undef on failure (encryption failure, file-writing failure,
187       etc.); in this case you should check the error message using the errstr
188       method (below). On success returns the constructed PEM string.
189
190       In addition to the arguments for encode, %args can contain:
191
192       •   Filename
193
194           The location on disk where you'd like the PEM file written.
195
196   $pem->errstr
197       Returns the value of the last error that occurred. This should only be
198       considered meaningful when you've received undef from one of the
199       functions above; in all other cases its relevance is undefined.
200
201   $pem->asn
202       Returns the Convert::ASN1 object used internally to decode and encode
203       ASN.1 representations. This is useful when you wish to interact
204       directly with that object; for example, if you need to call configure
205       on that object to set the type of big-integer class to be used when
206       decoding/encoding big integers:
207
208           $pem->asn->configure( decode => { bigint => 'Math::Pari' },
209                                 encode => { bigint => 'Math::Pari' } );
210

ERROR HANDLING

212       If an error occurs in any of the above methods, the method will return
213       "undef". You should then call the method errstr to determine the source
214       of the error:
215
216           $pem->errstr
217
218       In the case that you do not yet have a Convert::PEM object (that is, if
219       an error occurs while creating a Convert::PEM object), the error can be
220       obtained as a class method:
221
222           Convert::PEM->errstr
223
224       For example, if you try to decode an encrypted object, and you do not
225       give a passphrase to decrypt the object:
226
227           my $obj = $pem->read( Filename => "encrypted.pem" )
228               or die "Decryption failed: ", $pem->errstr;
229

LICENSE

231       Convert::PEM is free software; you may redistribute it and/or modify it
232       under the same terms as Perl itself.
233

AUTHOR & COPYRIGHTS

235       Except where otherwise noted, Convert::PEM is Copyright Benjamin Trott,
236       cpan@stupidfool.org. All rights reserved.
237
238
239
240perl v5.32.1                      2021-01-27                   Convert::PEM(3)
Impressum