1Convert::PEM(3) User Contributed Perl Documentation Convert::PEM(3)
2
6 Convert::PEM - Read/write encrypted ASN.1 PEM files
7
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 my $keyfile = 'private-key.pem';
24 my $pwd = 'foobar';
25 my $pkey = $pem->read(
27 Filename => $keyfile,
28 Password => $pwd
29 );
30 $pem->write(
32 Content => $pkey,
33 Password => $pwd,
34 Filename => $keyfile
35 );
36
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 -----BEGIN DH PARAMETERS-----
44 MB4CGQDUoLoCULb9LsYm5+/WN992xxbiLQlEuIsCAQM=
45 -----END DH PARAMETERS-----
46 The string beginning "MB4C..." is the Base64-encoded, ASN.1-encoded
48 "object."
49 An encrypted file would have headers describing the type of encryption
51 used, and the initialization vector:
52 -----BEGIN DH PARAMETERS-----
54 Proc-Type: 4,ENCRYPTED
55 DEK-Info: DES-EDE3-CBC,C814158661DC1449
56 AFAZFbnQNrGjZJ/ZemdVSoZa3HWujxZuvBHzHNoesxeyqqidFvnydA==
58 -----END DH PARAMETERS-----
59 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 The initialization vector ("C814158661DC1449") is chosen randomly.
65
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 %arg can contain:
73 • Name
75 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 -----BEGIN FOO BAR-----
84 Name is a required argument.
86 • ASN
88 An ASN.1 description of the content to be either encoded or
90 decoded.
91 ASN is a required argument.
93 • Macro
95 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 Foo ::= SEQUENCE {
102 x INTEGER,
103 bar Bar
104 }
105 Bar ::= INTEGER
107 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 Macro is an optional argument.
113 $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 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 %args can contain:
125 • Content
127 The PEM contents.
129 • Password
131 The password with which the file contents were encrypted.
133 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 $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 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 %args can contain:
147 • Content
149 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 This argument is mandatory.
156 • Password
158 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 $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 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 In addition to the arguments that can be passed to the decode method
174 (minus the Content method), %args can contain:
175 • Filename
177 The location of the PEM file that you wish to read.
179 $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 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 In addition to the arguments for encode, %args can contain:
191 • Filename
193 The location on disk where you'd like the PEM file written.
195 $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 $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 $pem->asn->configure( decode => { bigint => 'Math::Pari' },
209 encode => { bigint => 'Math::Pari' } );
210
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 $pem->errstr
217 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 Convert::PEM->errstr
223 For example, if you try to decode an encrypted object, and you do not
225 give a passphrase to decrypt the object:
226 my $obj = $pem->read( Filename => "encrypted.pem" )
228 or die "Decryption failed: ", $pem->errstr;
229
231 Convert::PEM is free software; you may redistribute it and/or modify it
232 under the same terms as Perl itself.
233
235 Except where otherwise noted, Convert::PEM is Copyright Benjamin Trott,
236 cpan@stupidfool.org. All rights reserved.
237perl v5.36.0 2023-01-20 Convert::PEM(3)