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

DESCRIPTION

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

FUNCTIONS

25       ·   Functions converting between string or file and certificates and
26           keys.  They croak if the operation cannot be completed.
27
28           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
39           CERT_free(cert)
40           KEY_free(key)
41       ·   KEY_create_rsa(bits) -> key
42
43           Creates an RSA key pair, bits defaults to 2048.
44
45       ·   KEY_create_ec(curve) -> key
46
47           Creates an EC key, curve defaults to "prime256v1".
48
49       ·   CERT_asHash(cert,[digest_algo]) -> hash
50
51           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
55           subject Hash with the parts of the subject, e.g. commonName,
56                   countryName, organizationName, stateOrProvinceName,
57                   localityName.
58
59           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
64           issuer  Hash with the parts of the issuer, e.g. commonName,
65                   countryName, organizationName, stateOrProvinceName,
66                   localityName.
67
68           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
72           serial  The serial number
73
74           crl_uri List of URIs for CRL distribution.
75
76           ocsp_uri
77                   List of URIs for revocation checking using OCSP.
78
79           keyusage
80                   List of keyUsage information in the certificate.
81
82           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
87           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
92           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
97           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
104           signature_alg
105                   Algorithm used to sign certificate, e.g.
106                   "sha256WithRSAEncryption".
107
108           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
112           version Certificate version, usually 2 (x509v3)
113
114       ·   CERT_create(hash) -> (cert,key)
115
116           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
120           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
124           not_before
125                   A time_t value when the certificate starts to be valid.
126                   Defaults to current time.
127
128           not_after
129                   A time_t value when the certificate ends to be valid.
130                   Defaults to current time plus one 365 days.
131
132           serial  The serial number. If not given a random number will be
133                   used.
134
135           version The version of the certificate, default 2 (x509v3).
136
137           CA true|false
138                   If true declare certificate as CA, defaults to false.
139
140           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
148                   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
154                   Purpose affects basicConstraints, keyUsage, extKeyUsage and
155                   netscapeCertType.  The following purposes are defined (case
156                   is not important):
157
158                       client
159                       server
160                       email
161                       objsign
162
163                       CA
164                       sslCA
165                       emailCA
166                       objCA
167
168                       emailProtection
169                       codeSigning
170                       timeStamping
171
172                       digitalSignature
173                       nonRepudiation
174                       keyEncipherment
175                       dataEncipherment
176                       keyAgreement
177                       keyCertSign
178                       cRLSign
179                       encipherOnly
180                       decipherOnly
181
182                   Examples:
183
184                        # root-CA for SSL certificates
185                        purpose => 'sslCA'   # or CA => 1
186
187                        # server certificate and CA (typically self-signed)
188                        purpose => 'sslCA,server'
189
190                        # client certificate
191                        purpose => 'client',
192
193           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
201           key key use given key as key for certificate, otherwise a new one
202                   will be generated and returned
203
204           issuer_cert cert
205                   set issuer for new certificate
206
207           issuer_key key
208                   sign new certificate with given key
209
210           issuer [ cert, key ]
211                   Instead of giving issuer_key and issuer_cert as separate
212                   arguments they can be given both together.
213
214           digest algorithm
215                   specify the algorithm used to sign the certificate, default
216                   SHA-256.
217

AUTHOR

219       Steffen Ullrich
220
221
222
223perl v5.30.1                      2019-11-25         IO::Socket::SSL::Utils(3)
Impressum