.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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 "Net::DNS::SEC::Keyset 3pm"
.TH Net::DNS::SEC::Keyset 3pm "2020-11-08" "perl v5.32.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"
Net::DNS::SEC::Keyset \- DNSSEC Keyset object class
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Net::DNS::SEC::Keyset;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A keyset is an \*(L"administrative\*(R" unit used for \s-1DNSSEC\s0 maintenance.
.PP
This class provides interfaces for creating, reading and writing keysets.
.PP
Object methods are provided to extract \s-1DNSKEY, RRSIG\s0 and \s-1DS\s0 records.
.PP
Note that this class is still being developed.
Attributes and methods are subject to change.
.SS "new (from file)"
.IX Subsection "new (from file)"
.Vb 3
\&    $keyset = Net::DNS::SEC::Keyset\->new( $filename );
\&    $keyset = Net::DNS::SEC::Keyset\->new( $filename, $directory );
\&    die Net::DNS::SEC::Keyset\->keyset_err unless $keyset;
.Ve
.PP
Constructor method which reads the specified keyset file and returns a
keyset object.
.PP
The optional second argument specifies the filename base directory.
.PP
Sets keyset_err and returns undef on failure.
.SS "new (by signing keys)"
.IX Subsection "new (by signing keys)"
.Vb 2
\&    $keyset = Net::DNS::SEC::Keyset\->new( [@keyrr], $privatekeypath );
\&    die Net::DNS::SEC::Keyset\->keyset_err unless $keyset;
.Ve
.PP
Creates a keyset object from the keys provided through the reference to an
array of Net::DNS::RR::DNSKEY objects.
.PP
The method will create and self-sign the whole keyset. The private keys as
generated by the \s-1BIND\s0 dnssec-keygen tool are assumed to be in the current
directory or, if specified, the directory indicated by \f(CW$privatekeypath\fR.
.PP
Sets keyset_err and returns undef on failure.
.SS "new (from key and sig RRsets)"
.IX Subsection "new (from key and sig RRsets)"
.Vb 2
\&    $keyset = Net::DNS::Keyset\->new( [@keyrr], [@sigrr] );
\&    die Net::DNS::SEC::Keyset\->keyset_err unless $keyset;
.Ve
.PP
Creates a keyset object from the keys provided through the references
to arrays of Net::DNS::RR::DNSKEY and Net::DNS::RR::RRSIG objects.
.PP
Sets keyset_err and returns undef on failure.
.SS "new (from Packet)"
.IX Subsection "new (from Packet)"
.Vb 2
\&    $resolver = Net::DNS::Resolver\->new;
\&    $resolver\->dnssec(1);
\&   
\&    $reply = $res\->send ( "example.com", "DNSKEY" );
\&
\&    $keyset = Net::DNS::SEC::Keyset\->new( $reply );
\&    die Net::DNS::SEC::Keyset\->keyset_err unless $keyset;
.Ve
.PP
Creates a keyset object from a Net::DNS::Packet that contains the answer
to a query for key records at the zone apex.
.PP
This is the method you should use for automatically fetching keys.
.PP
Sets keyset_err and returns undef on failure.
.SS "keys"
.IX Subsection "keys"
.Vb 1
\&    @keyrr = $keyset\->keys;
.Ve
.PP
Returns an array of Net::DNS::RR::DNSKEY objects.
.SS "sigs"
.IX Subsection "sigs"
.Vb 1
\&    @sigrr = $keyset\->sigs;
.Ve
.PP
Returns an array of Net::DNS::RR::RRSIG objects.
.SS "extract_ds"
.IX Subsection "extract_ds"
.Vb 2
\&    @ds = $keyset\->extract_ds;
\&    die Net::DNS::SEC::Keyset\->keyset_err unless @ds;
.Ve
.PP
Extracts \s-1DS\s0 records from the keyset. Note that the keyset will be verified
during extraction. All keys will need to have a valid self-signature.
.PP
The method sets keyset_err if verification fails.
.SS "verify"
.IX Subsection "verify"
.Vb 2
\&    @keytags = $keyset\->verify();
\&    die Net::DNS::SEC::Keyset\->keyset_err unless @keytags;
\&
\&    $keyset\->verify( $keytag ) || die $keyset\->keyset_err;
.Ve
.PP
If no arguments are given:
.IP "\(bu" 2
Verifies if all signatures present verify the keyset.
.IP "\(bu" 2
Verifies if there are DNSKEYs with the \s-1SEP\s0 flag set, there is at
least one \s-1RRSIG\s0 made using that key.
.IP "\(bu" 2
Verifies that if there are no DNSKEYs with the \s-1SEP\s0 flag set there
is at least one \s-1RRSIG\s0 made with one of the keys from the keyset.
.PP
If an argument is given, it is should be the numeric keytag of the key
in the keyset which will be verified using the corresponding \s-1RRSIG.\s0
.PP
The method returns a list of keytags of verified keys in the keyset.
.PP
The method sets keyset_err and returns empty list if verification fails.
.SS "keyset_err"
.IX Subsection "keyset_err"
.Vb 1
\&    $keyset_err = Net::DNS::SEC::Keyset\->keyset_err;
.Ve
.PP
Returns the keyset error string.
.SS "string"
.IX Subsection "string"
.Vb 1
\&    $string = $keyset\->string;
.Ve
.PP
Returns a string representation of the keyset.
.SS "print"
.IX Subsection "print"
.Vb 1
\&    $keyset\->print;             # similar to print( $keyset\->string )
.Ve
.PP
Prints the keyset.
.SS "writekeyset"
.IX Subsection "writekeyset"
.Vb 4
\&    $keyset\->writekeyset;
\&    $keyset\->writekeyset( $path );
\&    $keyset\->writekeyset( $prefix );
\&    $keyset\->writekeyset( $prefix, $path );
.Ve
.PP
Writes the keyset to a file named \*(L"keyset\-<domain>.\*(R" in the current
working directory or directory defined by the optional \f(CW$path\fR argument.
.PP
The optional \f(CW$prefix\fR argument specifies the prefix that will be
prepended to the domain name to form the keyset filename.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c)2002 \s-1RIPE NCC.\s0  Author Olaf M. Kolkman
.PP
Portions Copyright (c)2014 Dick Franks
.PP
All Rights Reserved
.SH "LICENSE"
.IX Header "LICENSE"
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted, provided
that the above copyright notice appear in all copies and that both that
copyright notice and this permission notice appear in supporting
documentation, and that the name of the author not be used in advertising
or publicity pertaining to distribution of the software without specific
prior written permission.
.PP
\&\s-1THE SOFTWARE IS PROVIDED \*(L"AS IS\*(R", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.\s0