1IO::Socket::SSL::Utils(U3s)er Contributed Perl DocumentatIiOo:n:Socket::SSL::Utils(3)
2
3
4

NAME

6       IO::Socket::SSL::Utils -- loading, storing, creating certificates and
7       keys
8

SYNOPSIS

10           use IO::Socket::SSL::Utils;
11
12           $cert = PEM_file2cert('cert.pem');     # load certificate from file
13           my $hash = CERT_asHash($cert);         # get details from certificate
14           PEM_cert2file($cert,'cert.pem');       # write certificate to file
15           CERT_free($cert);                      # free memory within OpenSSL
16
17           @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
21           my $cert = PEM_string2cert($pem);      # load certificate from PEM string
22           $pem = PEM_cert2string($cert);         # convert certificate to PEM string
23
24           $key = KEY_create_rsa(2048);           # create new 2048-bit RSA key
25           PEM_key2file($key,"key.pem");          # and write it to file
26           KEY_free($key);                        # free memory within OpenSSL
27

DESCRIPTION

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

FUNCTIONS

34       •   Functions converting between string or file and certificates and
35           keys.  They croak if the operation cannot be completed.
36
37           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
50           CERT_free(@certs)
51           KEY_free(@keys)
52       •   KEY_create_rsa(bits) -> key
53
54           Creates an RSA key pair, bits defaults to 2048.
55
56       •   KEY_create_ec(curve) -> key
57
58           Creates an EC key, curve defaults to "prime256v1".
59
60       •   CERT_asHash(cert,[digest_algo]) -> hash
61
62           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
66           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
72           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
77           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
83           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
87           serial  The serial number
88
89           crl_uri List of URIs for CRL distribution.
90
91           ocsp_uri
92                   List of URIs for revocation checking using OCSP.
93
94           keyusage
95                   List of keyUsage information in the certificate.
96
97           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
102           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
107           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
112           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
119           signature_alg
120                   Algorithm used to sign certificate, e.g.
121                   "sha256WithRSAEncryption".
122
123           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
127           version Certificate version, usually 2 (x509v3)
128
129       •   CERT_create(hash) -> (cert,key)
130
131           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
135           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
139           not_before
140                   A time_t value when the certificate starts to be valid.
141                   Defaults to current time.
142
143           not_after
144                   A time_t value when the certificate ends to be valid.
145                   Defaults to current time plus one 365 days.
146
147           serial  The serial number. If not given a random number will be
148                   used.
149
150           version The version of the certificate, default 2 (x509v3).
151
152           CA true|false
153                   If true declare certificate as CA, defaults to false.
154
155           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
163                   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
169                   Purpose affects basicConstraints, keyUsage, extKeyUsage and
170                   netscapeCertType.  The following purposes are defined (case
171                   is not important):
172
173                       client
174                       server
175                       email
176                       objsign
177
178                       CA
179                       sslCA
180                       emailCA
181                       objCA
182
183                       emailProtection
184                       codeSigning
185                       timeStamping
186
187                       digitalSignature
188                       nonRepudiation
189                       keyEncipherment
190                       dataEncipherment
191                       keyAgreement
192                       keyCertSign
193                       cRLSign
194                       encipherOnly
195                       decipherOnly
196
197                   Examples:
198
199                        # root-CA for SSL certificates
200                        purpose => 'sslCA'   # or CA => 1
201
202                        # server certificate and CA (typically self-signed)
203                        purpose => 'sslCA,server'
204
205                        # client certificate
206                        purpose => 'client',
207
208           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
216           key key use given key as key for certificate, otherwise a new one
217                   will be generated and returned
218
219           issuer_cert cert
220                   set issuer for new certificate
221
222           issuer_key key
223                   sign new certificate with given key
224
225           issuer [ cert, key ]
226                   Instead of giving issuer_key and issuer_cert as separate
227                   arguments they can be given both together.
228
229           digest algorithm
230                   specify the algorithm used to sign the certificate, default
231                   SHA-256.
232

AUTHOR

234       Steffen Ullrich
235
236
237
238perl v5.36.0                      2023-01-25         IO::Socket::SSL::Utils(3)
Impressum