Debian Codegraph @

README

raw
1 NAME
2 Crypt::OpenSSL::PKCS10 - Perl extension to OpenSSL's PKCS10 API.
3
4 SYNOPSIS
5 use Crypt::OpenSSL::PKCS10 qw( :const );
6
7 my $req = Crypt::OpenSSL::PKCS10->new;
8 $req->set_subject("/C=RO/O=UTI/OU=ssi");
9 $req->add_ext(Crypt::OpenSSL::PKCS10::NID_key_usage,"critical,digitalSignature,keyEncipherment");
10 $req->add_ext(Crypt::OpenSSL::PKCS10::NID_ext_key_usage,"serverAuth, nsSGC, msSGC, 1.3.4");
11 $req->add_ext(Crypt::OpenSSL::PKCS10::NID_subject_alt_name,"email:[email protected]");
12 $req->add_custom_ext('1.2.3.3',"My new extension");
13 $req->add_ext_final();
14 $req->sign();
15 $req->write_pem_req('request.pem');
16 $req->write_pem_pk('pk.pem');
17 print $req->get_pem_pubkey();
18 print $req->pubkey_type();
19 print $req->get_pem_req();
20
21 Crypt::OpenSSL::PKCS10->new() # Defaults to a 1024-bit RSA private key
22
23 Crypt::OpenSSL::PKCS10->new(2048) # Specify a 2048-bit RSA private key
24
25 # With 2 arguements the keysize must be first
26 Crypt::OpenSSL::PKCS10->new(
27 2048, # 2048-bit RSA keysize
28 {
29 type => 'rsa', # Private key type ('rsa' or 'ec')
30 hash => 'SHA256', # Hash Algorithm name
31 });
32
33 Crypt::OpenSSL::PKCS10->new(
34 {
35 type => 'ec', # Private key type ('rsa' or 'ec')
36 curve => 'secp384r1', # Eliptic Curve type (secp384r1 default)
37 hash => 'SHA256', # Hash Algorithm name
38 });
39
40 ABSTRACT
41 Crypt::OpenSSL::PKCS10 - Perl extension to OpenSSL's PKCS10 API.
42
43 DESCRIPTION
44 Crypt::OpenSSL::PKCS10 provides the ability to create PKCS10 certificate
45 requests using RSA key pairs.
46
47 Class Methods
48 new Create a new Crypt::OpenSSL::PKCS10 object by generating a new key
49 pair. There are two optional arguments, the key size which defaults
50 to 1024, and a hash of options which can be used to customize
51 options.
52
53 Crypt::OpenSSL::PKCS10->new() # Defaults to a 1024-bit RSA private key
54
55 Crypt::OpenSSL::PKCS10->new(2048) # Specify a 2048-bit RSA private key
56
57 # With 2 arguements the keysize must be first
58 Crypt::OpenSSL::PKCS10->new(
59 2048, # 2048-bit RSA keysize
60 {
61 type => 'rsa', # Private key type ('rsa' or 'ec')
62 hash => 'SHA256', # Hash Algorithm name
63 });
64
65 Crypt::OpenSSL::PKCS10->new(
66 {
67 type => 'ec', # Private key type ('rsa' or 'ec')
68 curve => 'secp384r1', # Eliptic Curve type (secp384r1 default)
69 hash => 'SHA256', # Hash Algorithm name
70 });
71
72 new_from_rsa( $rsa_object )
73 Create a new Crypt::OpenSSL::PKCS10 object by using key information
74 from a Crypt::OpenSSL::RSA object. Here is an example:
75
76 my $rsa = Crypt::OpenSSL::RSA->generate_key(512);
77 my $req = Crypt::OpenSSL::PKCS10->new_from_rsa($rsa);
78
79 my $rsa = Crypt::OpenSSL::RSA->generate_key(1024);
80 my $req = Crypt::OpenSSL::PKCS10->new_from_rsa($rsa, {type => 'rsa', hash => 'SHA384'});
81
82 OpenSSL 3.0 has deprecated the RSA object which Crypt::OpenSSL::RSA
83 creates. new_from_rsa() is now a perl sub which obtains the private
84 key as a string that is also passed to the _new_from_rsa() XS
85 function.
86
87 new_from_file( $filename )
88 Create a new Crypt::OpenSSL::PKCS10 object by reading the request
89 and key information from a PEM formatted file. Here is an example:
90
91 my $req = Crypt::OpenSSL::PKCS10->new_from_file("CSR.csr");
92
93 You can also specify the format of the PKCS10 file, either DER or
94 PEM format. Here are some examples:
95
96 my $req = Crypt::OpenSSL::PKCS10->new_from_file("CSR.csr", Crypt::OpenSSL::PKCS10::FORMAT_PEM());
97
98 my $req = Crypt::OpenSSL::PKCS10->new_from_file("CSR.der", Crypt::OpenSSL::PKCS10::FORMAT_ASN1());
99
100 Instance Methods
101 set_subject($subject, [ $utf8 ])
102 Sets the subject DN of the request. Note: $subject is expected to be
103 in the format /type0=value0/type1=value1/type2=... where characters
104 may be escaped by \. If $utf8 is non-zero integer, $subject is
105 interpreted as UTF-8 string.
106
107 add_ext($nid, $extension)
108 Adds a new extension to the request. The first argument $nid is one of
109 the exported constants (see below). The second one $extension is a
110 string (for more info read openssl(3)).
111
112 $req->add_ext(Crypt::OpenSSL::PKCS10::NID_key_usage,"critical,digitalSignature,keyEncipherment");
113 $req->add_ext(Crypt::OpenSSL::PKCS10::NID_ext_key_usage,"serverAuth, nsSGC, msSGC, 1.3.4");
114 $req->add_ext(Crypt::OpenSSL::PKCS10::NID_subject_alt_name,"email:[email protected]");
115
116 add_custom_ext($oid, $desc)
117 Adds a new custom extension to the request. The value is added as a
118 text string, using ASN.1 encoding rules inherited from the Netscape
119 Comment OID.
120
121 $req->add_custom_ext('1.2.3.3',"My new extension");
122
123 add_custom_ext_raw($oid, $bytes)
124 Adds a new custom extension to the request. The value is added as a
125 raw DER octet string. Use this if you are packing your own ASN.1
126 structures and need to set the extension value directly.
127
128 $req->add_custom_ext_raw($oid, pack('H*','1E06006100620063')) # BMPString 'abc'
129
130 add_ext_final()
131 This must be called after all extensions has been added. It actually
132 copies the extension stack to request structure.
133
134 $req->add_ext(Crypt::OpenSSL::PKCS10::NID_subject_alt_name,"email:[email protected]");
135 $req->add_ext_final();
136
137 sign()
138 This adds the signature to the PKCS10 request.
139
140 $req->sign();
141
142 $req->sign("SHA256"); # Set the hash to use for the signature
143
144 pubkey_type()
145 Returns the type of the PKCS10 public key - one of (rsa|dsa|ec).
146
147 $req->pubkey_type();
148
149 get_pubkey()
150 Returns the PEM encoding of the PKCS10 public key.
151
152 $req->get_pubkey();
153
154 get_pem_req()
155 Returns the PEM encoding of the PKCS10 request.
156
157 $req->get_pem_req();
158
159 write_pem_req($filename)
160 Writes the PEM encoding of the PKCS10 request to a given file.
161
162 $req->write_pem_req('request.pem');
163
164 get_pem_pk()
165 Returns the PEM encoding of the private key.
166
167 $req->get_pem_pk();
168
169 write_pem_pk($filename)
170 Writes the PEM encoding of the private key to a given file.
171
172 $req->write_pem_pk('request.pem');
173
174 subject()
175 returns the subject of the PKCS10 request
176
177 $subject = $req->subject();
178
179 keyinfo()
180 returns the human readable info about the key of the PKCS10 request
181
182 $keyinfo = $req->keyinfo();
183
184 EXPORT
185 None by default.
186
187 On request:
188
189 NID_key_usage NID_subject_alt_name NID_netscape_cert_type NID_netscape_comment
190 NID_ext_key_usage
191
192 BUGS
193 If you destroy $req object that is linked to a Crypt::OpenSSL::RSA
194 object, the RSA private key is also freed, thus you can't use latter
195 object anymore. Avoid this:
196
197 my $rsa = Crypt::OpenSSL::RSA->generate_key(512);
198 my $req = Crypt::OpenSSL::PKCS10->new_from_rsa($rsa);
199 undef $req;
200 print $rsa->get_private_key_string();
201
202 SEE ALSO
203 "Crypt::OpenSSL::RSA", "Crypt::OpenSSL::X509".
204
205 AUTHOR
206 JoNO, <[email protected]>
207
208 COPYRIGHT AND LICENSE
209 Copyright (C) 2006 by JoNO
210
211 This library is free software; you can redistribute it and/or modify it
212 under the same terms as Perl itself, either Perl version 5.8.2 or, at
213 your option, any later version of Perl 5 you may have available.
214