401 lines
8.9 KiB
HTML
401 lines
8.9 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of IO::Socket::SSL::Utils</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>IO::Socket::SSL::Utils</H1>
|
|
Section: User Contributed Perl Documentation (3pm)<BR>Updated: 2020-02-14<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
IO::Socket::SSL::Utils -- loading, storing, creating certificates and keys
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
use IO::Socket::SSL::Utils;
|
|
my $cert = PEM_file2cert('cert.pem'); # load certificate from file
|
|
my $string = PEM_cert2string($cert); # convert certificate to PEM string
|
|
CERT_free($cert); # free memory within OpenSSL
|
|
|
|
my $key = KEY_create_rsa(2048); # create new 2048-bit RSA key
|
|
PEM_string2file($key,"key.pem"); # and write it to file
|
|
KEY_free($key); # free memory within OpenSSL
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
This module provides various utility functions to work with certificates and
|
|
private keys, shielding some of the complexity of the underlying Net::SSLeay and
|
|
OpenSSL.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>FUNCTIONS</H2>
|
|
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="1">•<DD>
|
|
Functions converting between string or file and certificates and keys.
|
|
They croak if the operation cannot be completed.
|
|
<DL COMPACT><DT id="2"><DD>
|
|
<DL COMPACT>
|
|
<DT id="3">PEM_file2cert(file) -> cert<DD>
|
|
|
|
|
|
|
|
<DT id="4">PEM_cert2file(cert,file)<DD>
|
|
|
|
|
|
<DT id="5">PEM_string2cert(string) -> cert<DD>
|
|
|
|
|
|
<DT id="6">PEM_cert2string(cert) -> string<DD>
|
|
|
|
|
|
<DT id="7">PEM_file2key(file) -> key<DD>
|
|
|
|
|
|
<DT id="8">PEM_key2file(key,file)<DD>
|
|
|
|
|
|
<DT id="9">PEM_string2key(string) -> key<DD>
|
|
|
|
|
|
<DT id="10">PEM_key2string(key) -> string<DD>
|
|
|
|
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="11"><DD>
|
|
</DL>
|
|
|
|
<DT id="12">•<DD>
|
|
|
|
Functions for cleaning up.
|
|
Each loaded or created cert and key must be freed to not leak memory.
|
|
<DL COMPACT><DT id="13"><DD>
|
|
<DL COMPACT>
|
|
<DT id="14">CERT_free(cert)<DD>
|
|
|
|
|
|
|
|
<DT id="15">KEY_free(key)<DD>
|
|
|
|
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="16"><DD>
|
|
</DL>
|
|
|
|
<DT id="17">•<DD>
|
|
|
|
KEY_create_rsa(bits) -> key
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Creates an <FONT SIZE="-1">RSA</FONT> key pair, bits defaults to 2048.
|
|
<DT id="18">•<DD>
|
|
KEY_create_ec(curve) -> key
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Creates an <FONT SIZE="-1">EC</FONT> key, curve defaults to <TT>"prime256v1"</TT>.
|
|
<DT id="19">•<DD>
|
|
CERT_asHash(cert,[digest_algo]) -> hash
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Extracts the information from the certificate into a hash and uses the given
|
|
digest_algo (default: <FONT SIZE="-1">SHA-256</FONT>) to determine digest of pubkey and cert.
|
|
The resulting hash contains:
|
|
<DL COMPACT><DT id="20"><DD>
|
|
<DL COMPACT>
|
|
<DT id="21">subject<DD>
|
|
|
|
|
|
Hash with the parts of the subject, e.g. commonName, countryName,
|
|
organizationName, stateOrProvinceName, localityName.
|
|
<DT id="22">subjectAltNames<DD>
|
|
|
|
|
|
Array with list of alternative names. Each entry in the list is of
|
|
<TT>"[type,value]"</TT>, where <TT>"type"</TT> can be <FONT SIZE="-1">OTHERNAME, EMAIL, DNS, X400, DIRNAME,
|
|
EDIPARTY, URI, IP</FONT> or <FONT SIZE="-1">RID.</FONT>
|
|
<DT id="23">issuer<DD>
|
|
|
|
|
|
Hash with the parts of the issuer, e.g. commonName, countryName,
|
|
organizationName, stateOrProvinceName, localityName.
|
|
<DT id="24">not_before, not_after<DD>
|
|
|
|
|
|
The time frame, where the certificate is valid, as time_t, e.g. can be converted
|
|
with localtime or similar functions.
|
|
<DT id="25">serial<DD>
|
|
|
|
|
|
The serial number
|
|
<DT id="26">crl_uri<DD>
|
|
|
|
|
|
List of URIs for <FONT SIZE="-1">CRL</FONT> distribution.
|
|
<DT id="27">ocsp_uri<DD>
|
|
|
|
|
|
List of URIs for revocation checking using <FONT SIZE="-1">OCSP.</FONT>
|
|
<DT id="28">keyusage<DD>
|
|
|
|
|
|
List of keyUsage information in the certificate.
|
|
<DT id="29">extkeyusage<DD>
|
|
|
|
|
|
List of extended key usage information from the certificate. Each entry in
|
|
this list consists of a hash with oid, nid, ln and sn.
|
|
<DT id="30">pubkey_digest_xxx<DD>
|
|
|
|
|
|
Binary digest of the pubkey using the given digest algorithm, e.g.
|
|
pubkey_digest_sha256 if (the default) <FONT SIZE="-1">SHA-256</FONT> was used.
|
|
<DT id="31">x509_digest_xxx<DD>
|
|
|
|
|
|
Binary digest of the X.509 certificate using the given digest algorithm, e.g.
|
|
x509_digest_sha256 if (the default) <FONT SIZE="-1">SHA-256</FONT> was used.
|
|
<DT id="32">fingerprint_xxx<DD>
|
|
|
|
|
|
Fingerprint of the certificate using the given digest algorithm, e.g.
|
|
fingerprint_sha256 if (the default) <FONT SIZE="-1">SHA-256</FONT> was used. Contrary to digest_* this
|
|
is an <FONT SIZE="-1">ASCII</FONT> string with a list if hexadecimal numbers, e.g.
|
|
``73:59:75:5C:6D...''.
|
|
<DT id="33">signature_alg<DD>
|
|
|
|
|
|
Algorithm used to sign certificate, e.g. <TT>"sha256WithRSAEncryption"</TT>.
|
|
<DT id="34">ext<DD>
|
|
|
|
|
|
List of extensions.
|
|
Each entry in the list is a hash with oid, nid, sn, critical flag (boolean) and
|
|
data (string representation given by X509V3_EXT_print).
|
|
<DT id="35">version<DD>
|
|
|
|
|
|
Certificate version, usually 2 (x509v3)
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="36"><DD>
|
|
</DL>
|
|
|
|
<DT id="37">•<DD>
|
|
CERT_create(hash) -> (cert,key)
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Creates a certificate based on the given hash.
|
|
If the issuer is not specified the certificate will be self-signed.
|
|
The following keys can be given:
|
|
<DL COMPACT><DT id="38"><DD>
|
|
<DL COMPACT>
|
|
<DT id="39">subject<DD>
|
|
|
|
|
|
Hash with the parts of the subject, e.g. commonName, countryName, ... as
|
|
described in <TT>"CERT_asHash"</TT>.
|
|
Default points to IO::Socket::SSL.
|
|
<DT id="40">not_before<DD>
|
|
|
|
|
|
A time_t value when the certificate starts to be valid. Defaults to current
|
|
time.
|
|
<DT id="41">not_after<DD>
|
|
|
|
|
|
A time_t value when the certificate ends to be valid. Defaults to current
|
|
time plus one 365 days.
|
|
<DT id="42">serial<DD>
|
|
|
|
|
|
The serial number. If not given a random number will be used.
|
|
<DT id="43">version<DD>
|
|
|
|
|
|
The version of the certificate, default 2 (x509v3).
|
|
<DT id="44"><FONT SIZE="-1">CA</FONT> true|false<DD>
|
|
|
|
|
|
If true declare certificate as <FONT SIZE="-1">CA,</FONT> defaults to false.
|
|
<DT id="45">purpose string|array|hash<DD>
|
|
|
|
|
|
Set the purpose of the certificate.
|
|
The different purposes can be given as a string separated by non-word character,
|
|
as array or hash. With string or array each purpose can be prefixed with '+'
|
|
(enable) or '-' (disable) and same can be done with the value when given as a
|
|
hash. By default enabling the purpose is assumed.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If the <FONT SIZE="-1">CA</FONT> option is given and true the defaults ``ca,sslca,emailca,objca'' are
|
|
assumed, but can be overridden with explicit purpose.
|
|
If the <FONT SIZE="-1">CA</FONT> option is given and false the defaults ``server,client'' are assumed.
|
|
If no <FONT SIZE="-1">CA</FONT> option and no purpose is given it defaults to ``server,client''.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Purpose affects basicConstraints, keyUsage, extKeyUsage and netscapeCertType.
|
|
The following purposes are defined (case is not important):
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
client
|
|
server
|
|
email
|
|
objsign
|
|
|
|
CA
|
|
sslCA
|
|
emailCA
|
|
objCA
|
|
|
|
emailProtection
|
|
codeSigning
|
|
timeStamping
|
|
|
|
digitalSignature
|
|
nonRepudiation
|
|
keyEncipherment
|
|
dataEncipherment
|
|
keyAgreement
|
|
keyCertSign
|
|
cRLSign
|
|
encipherOnly
|
|
decipherOnly
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Examples:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
# root-CA for SSL certificates
|
|
purpose => 'sslCA' # or CA => 1
|
|
|
|
# server certificate and CA (typically self-signed)
|
|
purpose => 'sslCA,server'
|
|
|
|
# client certificate
|
|
purpose => 'client',
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="46">ext [{ sn => .., data => ... }, ... ]<DD>
|
|
|
|
|
|
List of extensions. The type of the extension can be specified as name with
|
|
<TT>"sn"</TT> or as <FONT SIZE="-1">NID</FONT> with <TT>"nid"</TT> and the data with <TT>"data"</TT>. These data must be in the
|
|
same syntax as expected within openssl.cnf, e.g. something like
|
|
<TT>"OCSP;URI=<A HREF="http://...">http://...</A>"</TT>. Additionally the critical flag can be set with
|
|
<TT>"critical ="</TT> 1>.
|
|
<DT id="47">key key<DD>
|
|
|
|
|
|
use given key as key for certificate, otherwise a new one will be generated and
|
|
returned
|
|
<DT id="48">issuer_cert cert<DD>
|
|
|
|
|
|
set issuer for new certificate
|
|
<DT id="49">issuer_key key<DD>
|
|
|
|
|
|
sign new certificate with given key
|
|
<DT id="50">issuer [ cert, key ]<DD>
|
|
|
|
|
|
Instead of giving issuer_key and issuer_cert as separate arguments they can be
|
|
given both together.
|
|
<DT id="51">digest algorithm<DD>
|
|
|
|
|
|
specify the algorithm used to sign the certificate, default <FONT SIZE="-1">SHA-256.</FONT>
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="52"><DD>
|
|
</DL>
|
|
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
|
|
|
|
Steffen Ullrich
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="53"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="54"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="55"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="56"><A HREF="#lbAE">FUNCTIONS</A><DD>
|
|
<DT id="57"><A HREF="#lbAF">AUTHOR</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:46 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|