.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Crypt::Perl::PKCS10 3"
.TH Crypt::Perl::PKCS10 3 "2020-09-27" "perl v5.30.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Crypt::Perl::PKCS10 \- Certificate Signing Request (CSR) creation
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    my $pkcs10 = Crypt::Perl::PKCS10\->new(
\&
\&        key => $private_key_obj,
\&
\&        subject => [
\&            commonName => \*(Aqfoo.com\*(Aq,
\&            localityName => \*(Aqsomewhere\*(Aq,
\&            #...
\&        ],
\&        attributes => [
\&            [ \*(AqextensionRequest\*(Aq,
\&                [ \*(AqsubjectAltName\*(Aq,
\&                    [ dNSName => \*(Aqfoo.com\*(Aq ],
\&                    [ dNSName => \*(Aqbar.com\*(Aq ],
\&                ],
\&            ],
\&        ],
\&    );
\&
\&    my $der = $pkcs10\->to_der();
\&    my $pem = $pkcs10\->to_pem();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is for creation of (\s-1PKCS\s0 #10) certificate signing requests (CSRs).
Right now it supports only a
subset of what OpenSSL <http://openssl.org> can create; however, it’s
useful enough for use with many certificate authorities, including
\&\s-1ACME\s0 <https://ietf-wg-acme.github.io/acme/> services like
Let’s Encrypt <http://letsencrypt.org>.
.PP
It’s also a good deal easier to use!
.PP
I believe this is the only \s-1CPAN\s0 <http://search.cpan.org> module that
can create CSRs for \s-1RSA, ECDSA,\s0 and Ed25519 keys. Other encryption schemes
would not be difficult to integrate—but do any CAs accept them?
.SH "ECDSA KEY FORMAT"
.IX Header "ECDSA KEY FORMAT"
After a brief flirtation (cf. v0.13) with producing ECDSA-signed CSRs using
explicit curve parameters, this module produces CSRs using \fBnamed\fR curves.
Certificate authorities seem to prefer this format—which makes sense since
they only allow certain curves in the first place.
.SH "SIGNATURE DIGEST ALGORITHMS"
.IX Header "SIGNATURE DIGEST ALGORITHMS"
The signature digest algorithm is
determined based on the passed-in key: for \s-1RSA\s0 it’s always \s-1SHA\-512,\s0 and for
\&\s-1ECDSA\s0 it’s the strongest \s-1SHA\s0 digest algorithm that the key allows
(e.g., \s-1SHA\-224\s0 for a 239\-bit key, etc.)
.PP
If you need additional flexibility, let me know.
.PP
(Note that Ed25519 signs an entire document rather than a digest.)
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
.SS "new( \s-1NAME\s0 => \s-1VALUE, ...\s0 );"
.IX Subsection "new( NAME => VALUE, ... );"
Create an instance of this class. Parameters are:
.IP "\(bu" 4
\&\f(CW\*(C`key\*(C'\fR \- An instance of \f(CW\*(C`Crypt::Perl::RSA::PrivateKey\*(C'\fR,
\&\f(CW\*(C`Crypt::Perl::ECDSA::PrivateKey\*(C'\fR, or \f(CW\*(C`Crypt::Perl::Ed25519::PrivateKey\*(C'\fR.
If you’ve got a \s-1DER\-\s0 or PEM-encoded key string, use Crypt::Perl::PK
(included in this distribution) to create an appropriate object.
.IP "\(bu" 4
\&\f(CW\*(C`subject\*(C'\fR \- An array reference of arguments into
Crypt::Perl::X509::Name’s constructor.
.IP "\(bu" 4
\&\f(CW\*(C`attributes\*(C'\fR \- An array reference of arguments into
Crypt::Perl::PKCS10::Attributes’s constructor.
.SH "TODO"
.IX Header "TODO"
Let me know what features you would find useful, ideally with
a representative sample \s-1CSR\s0 that demonstrates the requested feature.
(Or, better yet, send me a pull request!)
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
Crypt::PKCS10 \- Parse CSRs, in pure Perl.
.IP "\(bu" 4
Crypt::OpenSSL::PKCS10 \- Create CSRs using OpenSSL via \s-1XS.\s0
Currently this only seems to support \s-1RSA.\s0