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.
58 subjectAltNames
60 Array with list of alternative names. Each entry in the
61 list is of "[type,value]", where "type" can be OTHERNAME,
62 EMAIL, DNS, X400, DIRNAME, EDIPARTY, URI, IP or RID.
63 issuer Hash with the parts of the issuer, e.g. commonName,
65 countryName, organizationName, stateOrProvinceName,
66 localityName.
67 not_before, not_after
69 The time frame, where the certificate is valid, as time_t,
70 e.g. can be converted with localtime or similar functions.
71 serial The serial number
73 crl_uri List of URIs for CRL distribution.
75 ocsp_uri
77 List of URIs for revocation checking using OCSP.
78 keyusage
80 List of keyUsage information in the certificate.
81 extkeyusage
83 List of extended key usage information from the
84 certificate. Each entry in this list consists of a hash
85 with oid, nid, ln and sn.
86 pubkey_digest_xxx
88 Binary digest of the pubkey using the given digest
89 algorithm, e.g. pubkey_digest_sha256 if (the default)
90 SHA-256 was used.
91 x509_digest_xxx
93 Binary digest of the X.509 certificate using the given
94 digest algorithm, e.g. x509_digest_sha256 if (the default)
95 SHA-256 was used.
96 fingerprint_xxx
98 Fingerprint of the certificate using the given digest
99 algorithm, e.g. fingerprint_sha256 if (the default)
100 SHA-256 was used. Contrary to digest_* this is an ASCII
101 string with a list if hexadecimal numbers, e.g.
102 "73:59:75:5C:6D...".
103 signature_alg
105 Algorithm used to sign certificate, e.g.
106 "sha256WithRSAEncryption".
107 ext List of extensions. Each entry in the list is a hash with
109 oid, nid, sn, critical flag (boolean) and data (string
110 representation given by X509V3_EXT_print).
111 version Certificate version, usually 2 (x509v3)
113 · CERT_create(hash) -> (cert,key)
115 Creates a certificate based on the given hash. If the issuer is
117 not specified the certificate will be self-signed. The following
118 keys can be given:
119 subject Hash with the parts of the subject, e.g. commonName,
121 countryName, ... as described in "CERT_asHash". Default
122 points to IO::Socket::SSL.
123 not_before
125 A time_t value when the certificate starts to be valid.
126 Defaults to current time.
127 not_after
129 A time_t value when the certificate ends to be valid.
130 Defaults to current time plus one 365 days.
131 serial The serial number. If not given a random number will be
133 used.
134 version The version of the certificate, default 2 (x509v3).
136 CA true|false
138 If true declare certificate as CA, defaults to false.
139 purpose string|array|hash
141 Set the purpose of the certificate. The different purposes
142 can be given as a string separated by non-word character,
143 as array or hash. With string or array each purpose can be
144 prefixed with '+' (enable) or '-' (disable) and same can be
145 done with the value when given as a hash. By default
146 enabling the purpose is assumed.
147 If the CA option is given and true the defaults
149 "ca,sslca,emailca,objca" are assumed, but can be overridden
150 with explicit purpose. If the CA option is given and false
151 the defaults "server,client" are assumed. If no CA option
152 and no purpose is given it defaults to "server,client".
153 Purpose affects basicConstraints, keyUsage, extKeyUsage and
155 netscapeCertType. The following purposes are defined (case
156 is not important):
157 client
159 server
160 email
161 objsign
162 CA
164 sslCA
165 emailCA
166 objCA
167 emailProtection
169 codeSigning
170 timeStamping
171 digitalSignature
173 nonRepudiation
174 keyEncipherment
175 dataEncipherment
176 keyAgreement
177 keyCertSign
178 cRLSign
179 encipherOnly
180 decipherOnly
181 Examples:
183 # root-CA for SSL certificates
185 purpose => 'sslCA' # or CA => 1
186 # server certificate and CA (typically self-signed)
188 purpose => 'sslCA,server'
189 # client certificate
191 purpose => 'client',
192 ext [{ sn => .., data => ... }, ... ]
194 List of extensions. The type of the extension can be
195 specified as name with "sn" or as NID with "nid" and the
196 data with "data". These data must be in the same syntax as
197 expected within openssl.cnf, e.g. something like
198 "OCSP;URI=http://...". Additionally the critical flag can
199 be set with "critical =" 1>.
200 key key use given key as key for certificate, otherwise a new one
202 will be generated and returned
203 issuer_cert cert
205 set issuer for new certificate
206 issuer_key key
208 sign new certificate with given key
209 issuer [ cert, key ]
211 Instead of giving issuer_key and issuer_cert as separate
212 arguments they can be given both together.
213 digest algorithm
215 specify the algorithm used to sign the certificate, default
216 SHA-256.
217
219 Steffen Ullrich
220perl v5.28.1 2019-02-21 IO::Socket::SSL::Utils(3)