.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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::DSA::Key 3pm"
.TH Crypt::DSA::Key 3pm "2022-06-12" "perl v5.34.0" "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::DSA::Key \- DSA key
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    use Crypt::DSA::Key;
\&    my $key = Crypt::DSA::Key\->new;
\&
\&    $key\->p($p);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fICrypt::DSA::Key\fR contains a \s-1DSA\s0 key, both the public and
private portions. Subclasses of \fICrypt::DSA::Key\fR implement
\&\fIread\fR and \fIwrite\fR methods, such that you can store \s-1DSA\s0
keys on disk, and read them back into your application.
.SH "USAGE"
.IX Header "USAGE"
Any of the key attributes can be accessed through combination
get/set methods. The key attributes are: \fIp\fR, \fIq\fR, \fIg\fR,
\&\fIpriv_key\fR, and \fIpub_key\fR. For example:
.PP
.Vb 2
\&    $key\->p($p);
\&    my $p2 = $key\->p;
.Ve
.ie n .SS "$key = Crypt::DSA::Key\->new(%arg)"
.el .SS "\f(CW$key\fP = Crypt::DSA::Key\->new(%arg)"
.IX Subsection "$key = Crypt::DSA::Key->new(%arg)"
Creates a new (empty) key object. All of the attributes are
initialized to 0.
.PP
Alternately, if you provide the \fIFilename\fR parameter (see
below), the key will be read in from disk. If you provide
the \fIType\fR parameter (mandatory if \fIFilename\fR is provided),
be aware that your key will actually be blessed into a subclass
of \fICrypt::DSA::Key\fR. Specifically, it will be the class
implementing the specific read functionality for that type,
eg. \fICrypt::DSA::Key::PEM\fR.
.PP
Returns the key on success, \f(CW\*(C`undef\*(C'\fR otherwise. (See \fIPassword\fR
for one reason why \fInew\fR might return \f(CW\*(C`undef\*(C'\fR).
.PP
\&\fI\f(CI%arg\fI\fR can contain:
.IP "\(bu" 4
Type
.Sp
The type of file where the key is stored. Currently the only
option is \fI\s-1PEM\s0\fR, which indicates a \s-1PEM\s0 file (optionally
encrypted, \s-1ASN\s0.1\-encoded object). Support for reading/writing
\&\s-1PEM\s0 files comes from \fIConvert::PEM\fR; if you don't have this
module installed, the \fInew\fR method will die.
.Sp
This argument is mandatory, \fIif\fR you're either reading the file from
disk (ie. you provide a \fIFilename\fR argument) or you've specified the
\&\fIContent\fR argument.
.IP "\(bu" 4
Filename
.Sp
The location of the file from which you'd like to read the key.
Requires a \fIType\fR argument so the decoder knows what type of file it
is.  You can't specify \fIContent\fR and \fIFilename\fR at the same time.
.IP "\(bu" 4
Content
.Sp
The serialized version of the key.  Requires a \fIType\fR argument so the
decoder knows how to decode it.  You can't specify \fIContent\fR and
\&\fIFilename\fR at the same time.
.IP "\(bu" 4
Password
.Sp
If your key file is encrypted, you'll need to supply a
passphrase to decrypt it. You can do that here.
.Sp
If your passphrase is incorrect, \fInew\fR will return \f(CW\*(C`undef\*(C'\fR.
.ie n .SS "$key\->write(%arg)"
.el .SS "\f(CW$key\fP\->write(%arg)"
.IX Subsection "$key->write(%arg)"
Writes a key (optionally) to disk, using a format that you
define with the \fIType\fR parameter.
.PP
If your \fI\f(CI$key\fI\fR object has a defined \fIpriv_key\fR (private key portion),
the key will be written as a \s-1DSA\s0 private key object; otherwise, it will
be written out as a public key. Note that not all serialization mechanisms
can produce public keys in this version\*(--currently, only \s-1PEM\s0 public keys
are supported.
.PP
\&\fI\f(CI%arg\fI\fR can include:
.IP "\(bu" 4
Type
.Sp
The type of file format that you wish to write. \fI\s-1PEM\s0\fR is one
example (in fact, currently, it's the only example).
.Sp
This argument is mandatory, \fIunless\fR your \fI\f(CI$key\fI\fR object is
already blessed into a subclass (eg. \fICrypt::DSA::Key::PEM\fR),
and you wish to write the file using the same subclass.
.IP "\(bu" 4
Filename
.Sp
The location of the file on disk where you want the key file
to be written.
.IP "\(bu" 4
Password
.Sp
If you want the key file to be encrypted, provide this
argument, and the \s-1ASN\s0.1\-encoded string will be encrypted using
the passphrase as a key.
.ie n .SS "$key\->size"
.el .SS "\f(CW$key\fP\->size"
.IX Subsection "$key->size"
Returns the size of the key, in bits. This is actually the
number of bits in the large prime \fIp\fR.
.SH "AUTHOR & COPYRIGHTS"
.IX Header "AUTHOR & COPYRIGHTS"
Please see the Crypt::DSA manpage for author, copyright,
and license information.