1IO::Socket::SSL::Utils(U3s)er Contributed Perl DocumentatIiOo:n:Socket::SSL::Utils(3)
2
6 IO::Socket::SSL::Utils -- loading, storing, creating certificates and
7 keys
8
10 use IO::Socket::SSL::Utils;
11 my $cert = PEM_file2cert('cert.pem'); # load certificate from file
12 my $string = PEM_cert2string($cert); # convert certificate to PEM string
13 CERT_free($cert); # free memory within OpenSSL
14 my $key = KEY_create_rsa(2048); # create new 2048-bit RSA key
16 PEM_string2file($key,"key.pem"); # and write it to file
17 KEY_free($key); # free memory within OpenSSL
18
20 This module provides various utility functions to work with
21 certificates and private keys, shielding some of the complexity of the
22 underlying Net::SSLeay and OpenSSL.
23
25 • Functions converting between string or file and certificates and
26 keys. They croak if the operation cannot be completed.
27 PEM_file2cert(file) -> cert
29 PEM_cert2file(cert,file)
30 PEM_string2cert(string) -> cert
31 PEM_cert2string(cert) -> string
32 PEM_file2key(file) -> key
33 PEM_key2file(key,file)
34 PEM_string2key(string) -> key
35 PEM_key2string(key) -> string
36 • Functions for cleaning up. Each loaded or created cert and key
37 must be freed to not leak memory.
38 CERT_free(cert)
40 KEY_free(key)
41 • KEY_create_rsa(bits) -> key
42 Creates an RSA key pair, bits defaults to 2048.
44 • KEY_create_ec(curve) -> key
46 Creates an EC key, curve defaults to "prime256v1".
48 • CERT_asHash(cert,[digest_algo]) -> hash
50 Extracts the information from the certificate into a hash and uses
52 the given digest_algo (default: SHA-256) to determine digest of
53 pubkey and cert. The resulting hash contains:
54 subject Hash with the parts of the subject, e.g. commonName,
56 countryName, organizationName, stateOrProvinceName,
57 localityName. If there are multiple values for any of these
58 parts the hash value will be an array ref with the values
59 in order instead of just a scalar.
60 subjectAltNames
62 Array with list of alternative names. Each entry in the
63 list is of "[type,value]", where "type" can be OTHERNAME,
64 EMAIL, DNS, X400, DIRNAME, EDIPARTY, URI, IP or RID.
65 issuer Hash with the parts of the issuer, e.g. commonName,
67 countryName, organizationName, stateOrProvinceName,
68 localityName. If there are multiple values for any of these
69 parts the hash value will be an array ref with the values
70 in order instead of just a scalar.
71 not_before, not_after
73 The time frame, where the certificate is valid, as time_t,
74 e.g. can be converted with localtime or similar functions.
75 serial The serial number
77 crl_uri List of URIs for CRL distribution.
79 ocsp_uri
81 List of URIs for revocation checking using OCSP.
82 keyusage
84 List of keyUsage information in the certificate.
85 extkeyusage
87 List of extended key usage information from the
88 certificate. Each entry in this list consists of a hash
89 with oid, nid, ln and sn.
90 pubkey_digest_xxx
92 Binary digest of the pubkey using the given digest
93 algorithm, e.g. pubkey_digest_sha256 if (the default)
94 SHA-256 was used.
95 x509_digest_xxx
97 Binary digest of the X.509 certificate using the given
98 digest algorithm, e.g. x509_digest_sha256 if (the default)
99 SHA-256 was used.
100 fingerprint_xxx
102 Fingerprint of the certificate using the given digest
103 algorithm, e.g. fingerprint_sha256 if (the default)
104 SHA-256 was used. Contrary to digest_* this is an ASCII
105 string with a list if hexadecimal numbers, e.g.
106 "73:59:75:5C:6D...".
107 signature_alg
109 Algorithm used to sign certificate, e.g.
110 "sha256WithRSAEncryption".
111 ext List of extensions. Each entry in the list is a hash with
113 oid, nid, sn, critical flag (boolean) and data (string
114 representation given by X509V3_EXT_print).
115 version Certificate version, usually 2 (x509v3)
117 • CERT_create(hash) -> (cert,key)
119 Creates a certificate based on the given hash. If the issuer is
121 not specified the certificate will be self-signed. The following
122 keys can be given:
123 subject Hash with the parts of the subject, e.g. commonName,
125 countryName, ... as described in "CERT_asHash". Default
126 points to IO::Socket::SSL.
127 not_before
129 A time_t value when the certificate starts to be valid.
130 Defaults to current time.
131 not_after
133 A time_t value when the certificate ends to be valid.
134 Defaults to current time plus one 365 days.
135 serial The serial number. If not given a random number will be
137 used.
138 version The version of the certificate, default 2 (x509v3).
140 CA true|false
142 If true declare certificate as CA, defaults to false.
143 purpose string|array|hash
145 Set the purpose of the certificate. The different purposes
146 can be given as a string separated by non-word character,
147 as array or hash. With string or array each purpose can be
148 prefixed with '+' (enable) or '-' (disable) and same can be
149 done with the value when given as a hash. By default
150 enabling the purpose is assumed.
151 If the CA option is given and true the defaults
153 "ca,sslca,emailca,objca" are assumed, but can be overridden
154 with explicit purpose. If the CA option is given and false
155 the defaults "server,client" are assumed. If no CA option
156 and no purpose is given it defaults to "server,client".
157 Purpose affects basicConstraints, keyUsage, extKeyUsage and
159 netscapeCertType. The following purposes are defined (case
160 is not important):
161 client
163 server
164 email
165 objsign
166 CA
168 sslCA
169 emailCA
170 objCA
171 emailProtection
173 codeSigning
174 timeStamping
175 digitalSignature
177 nonRepudiation
178 keyEncipherment
179 dataEncipherment
180 keyAgreement
181 keyCertSign
182 cRLSign
183 encipherOnly
184 decipherOnly
185 Examples:
187 # root-CA for SSL certificates
189 purpose => 'sslCA' # or CA => 1
190 # server certificate and CA (typically self-signed)
192 purpose => 'sslCA,server'
193 # client certificate
195 purpose => 'client',
196 ext [{ sn => .., data => ... }, ... ]
198 List of extensions. The type of the extension can be
199 specified as name with "sn" or as NID with "nid" and the
200 data with "data". These data must be in the same syntax as
201 expected within openssl.cnf, e.g. something like
202 "OCSP;URI=http://...". Additionally the critical flag can
203 be set with "critical =" 1>.
204 key key use given key as key for certificate, otherwise a new one
206 will be generated and returned
207 issuer_cert cert
209 set issuer for new certificate
210 issuer_key key
212 sign new certificate with given key
213 issuer [ cert, key ]
215 Instead of giving issuer_key and issuer_cert as separate
216 arguments they can be given both together.
217 digest algorithm
219 specify the algorithm used to sign the certificate, default
220 SHA-256.
221
223 Steffen Ullrich
224perl v5.32.1 2021-03-19 IO::Socket::SSL::Utils(3)