| 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 |
|