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