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 $pkey = $pem->read(
24 Filename => $keyfile,
25 Password => $pwd
26 );
27 $pem->write(
29 Content => $pkey,
30 Password => $pwd,
31 Filename => $keyfile
32 );
33
35 Convert::PEM reads and writes PEM files containing ASN.1-encoded
36 objects. The files can optionally be encrypted using a symmetric cipher
37 algorithm, such as 3DES. An unencrypted PEM file might look something
38 like this:
39 -----BEGIN DH PARAMETERS-----
41 MB4CGQDUoLoCULb9LsYm5+/WN992xxbiLQlEuIsCAQM=
42 -----END DH PARAMETERS-----
43 The string beginning "MB4C..." is the Base64-encoded, ASN.1-encoded
45 "object."
46 An encrypted file would have headers describing the type of encryption
48 used, and the initialization vector:
49 -----BEGIN DH PARAMETERS-----
51 Proc-Type: 4,ENCRYPTED
52 DEK-Info: DES-EDE3-CBC,C814158661DC1449
53 AFAZFbnQNrGjZJ/ZemdVSoZa3HWujxZuvBHzHNoesxeyqqidFvnydA==
55 -----END DH PARAMETERS-----
56 The two headers ("Proc-Type" and "DEK-Info") indicate information about
58 the type of encryption used, and the string starting with "AFAZ..." is
59 the Base64-encoded, encrypted, ASN.1-encoded contents of this "object."
60 The initialization vector ("C814158661DC1449") is chosen randomly.
62
64 $pem = Convert::PEM->new( %arg )
65 Constructs a new Convert::PEM object designed to read/write an object
67 of a specific type (given in %arg, see below). Returns the new object
68 on success, "undef" on failure (see ERROR HANDLING for details).
69 %arg can contain:
71 * Name
73 The name of the object; when decoding a PEM-encoded stream, the
74 name in the encoding will be checked against the value of Name.
75 Similarly, when encoding an object, the value of Name will be used
76 as the name of the object in the PEM-encoded content. For example,
77 given the string "FOO BAR", the output from encode will start with
78 a header like:
79 -----BEGIN FOO BAR-----
81 Name is a required argument.
83 * ASN
85 An ASN.1 description of the content to be either encoded or
86 decoded.
87 ASN is a required argument.
89 * Macro
91 If your ASN.1 description (in the ASN parameter) includes more than
92 one ASN.1 macro definition, you will want to use the Macro parame‐
93 ter to specify which definition to use when encoding/decoding
94 objects. For example, if your ASN.1 description looks like this:
95 Foo ::= SEQUENCE {
97 x INTEGER,
98 bar Bar
99 }
100 Bar ::= INTEGER
102 If you want to encode/decode a "Foo" object, you will need to tell
104 Convert::PEM to use the "Foo" macro definition by using the Macro
105 parameter and setting the value to "Foo".
106 Macro is an optional argument.
108 $obj = $pem->decode(%args)
110 Decodes, and, optionally, decrypts a PEM file, returning the object as
112 decoded by Convert::ASN1. The difference between this method and read
113 is that read reads the contents of a PEM file on disk; this method
114 expects you to pass the PEM contents as an argument.
115 If an error occurs while reading the file or decrypting/decoding the
117 contents, the function returns undef, and you should check the error
118 message using the errstr method (below).
119 %args can contain:
121 * Content
123 The PEM contents.
124 * Password
126 The password with which the file contents were encrypted.
127 If the file is encrypted, this is a mandatory argument (well, it's
129 not strictly mandatory, but decryption isn't going to work without
130 it). Otherwise it's not necessary.
131 $blob = $pem->encode(%args)
133 Constructs the contents for the PEM file from an object: ASN.1-encodes
135 the object, optionally encrypts those contents.
136 Returns undef on failure (encryption failure, file-writing failure,
138 etc.); in this case you should check the error message using the errstr
139 method (below). On success returns the constructed PEM string.
140 %args can contain:
142 * Content
144 A hash reference that will be passed to Convert::ASN1::encode, and
145 which should correspond to the ASN.1 description you gave to the
146 new method. The hash reference should have the exact same format as
147 that returned from the read method.
148 This argument is mandatory.
150 * Password
152 A password used to encrypt the contents of the PEM file. This is an
153 optional argument; if not provided the contents will be unen‐
154 crypted.
155 $obj = $pem->read(%args)
157 Reads, decodes, and, optionally, decrypts a PEM file, returning the
159 object as decoded by Convert::ASN1. This is implemented as a wrapper
160 around decode, with the bonus of reading the PEM file from disk for
161 you.
162 If an error occurs while reading the file or decrypting/decoding the
164 contents, the function returns undef, and you should check the error
165 message using the errstr method (below).
166 In addition to the arguments that can be passed to the decode method
168 (minus the Content method), %args can contain:
169 * Filename
171 The location of the PEM file that you wish to read.
172 $pem->write(%args)
174 Constructs the contents for the PEM file from an object: ASN.1-encodes
176 the object, optionally encrypts those contents; then writes the file to
177 disk. This is implemented as a wrapper around encode, with the bonus of
178 writing the file to disk for you.
179 Returns undef on failure (encryption failure, file-writing failure,
181 etc.); in this case you should check the error message using the errstr
182 method (below). On success returns the constructed PEM string.
183 In addition to the arguments for encode, %args can contain:
185 * Filename
187 The location on disk where you'd like the PEM file written.
188 $pem->errstr
190 Returns the value of the last error that occurred. This should only be
192 considered meaningful when you've received undef from one of the func‐
193 tions above; in all other cases its relevance is undefined.
194 $pem->asn
196 Returns the Convert::ASN1 object used internally to decode and encode
198 ASN.1 representations. This is useful when you wish to interact
199 directly with that object; for example, if you need to call configure
200 on that object to set the type of big-integer class to be used when
201 decoding/encoding big integers:
202 $pem->asn->configure( decode => { bigint => 'Math::Pari' },
204 encode => { bigint => 'Math::Pari' } );
205
207 If an error occurs in any of the above methods, the method will return
208 "undef". You should then call the method errstr to determine the source
209 of the error:
210 $pem->errstr
212 In the case that you do not yet have a Convert::PEM object (that is, if
214 an error occurs while creating a Convert::PEM object), the error can be
215 obtained as a class method:
216 Convert::PEM->errstr
218 For example, if you try to decode an encrypted object, and you do not
220 give a passphrase to decrypt the object:
221 my $obj = $pem->read( Filename => "encrypted.pem" )
223 or die "Decryption failed: ", $pem->errstr;
224
226 Benjamin Trott, ben@rhumba.pair.com
227 Except where otherwise noted, Convert::PEM is Copyright 2001 Benjamin
229 Trott. All rights reserved. Convert::PEM is free software; you may
230 redistribute it and/or modify it under the same terms as Perl itself.
231perl v5.8.8 2005-05-25 Convert::PEM(3)