NAME

       Net::DNS::RR::SIG - DNS SIG resource record

SYNOPSIS

       "use Net::DNS::RR;"

DESCRIPTION

       IMPORTANT: For any other use than SIG0 signatures the SIG RR has been deprecated (RFC3755). Use the
       DNSSIG instead.

       All functionality currently remains present although a warning will be printed at first usage of the
       verify and create methods.

       Class for DNS Address (SIG) resource records. In addition to the regular methods in the Net::DNS::RR the
       Class contains a method to sign RRsets using private keys (create). And a class for verifying signatures
       over RRsets (verify).

       The SIG RR is an implementation of RFC 2931.

SIG0 Support

       When Net::DNS::RR::SIG.pm is available the Net::DNS::Packet module will have the abilityh for sig0
       support. See Net::DNS::Packet for details.

           my $keypathrsa="Ktest.example.+001+11567.private";
           my $update1 = Net::DNS::Update->new("test.example");

           $update1->push("update", Net::DNS::rr_add("foo.test.example 3600 IN A 10.0.0.1"));
           $update1->sign_sig0($keypathrsa);

METHODS

   create
       create is an alternative constructor for a SIG RR object.

       You are advised to create a packet object and then use the sign_sig0 method to create a sig0 signature.

       To create a signature over a packet (SIG0) you can use the following alternative recipe.

           my $keypath=
                   "/home/olaf/keys/Kbla.foo.+001+60114.private";

           $sig0 = Net::DNS::RR::SIG->create('', $keypath);
           $packet->push('additional', $sig0) if $sig0;
           $packet->data;  # When the data method on a packet is called
                           # the actual sig0 calculation is done.

       The first argument to the create method should be an empty string in order for the SIG0 magic to work.

       The second argument is a string containing the path to a file containing the the private key as generated
       with dnssec-keygen, a program that commes with the bind distribution.

       The third argument is an anonymous hash containing the following possible arguments:

           ( ttl => 3600,                        # TTL
             sigin =>   20010501010101,          # signature inception
             sigex =>   20010501010101,          # signature expiration
             sigval => 1.5                       # signature validity
             )

       The default for the ttl is 3600 seconds. sigin and sigex need to be specified in the following format
       'yyyymmddhhmmss'. The default for sigin is the time of signing.

       sigval is the validity of the signature in minutes. If sigval is specified then sigex is ignored. The
       default for sigval is 5 minutes.

       Note that for SIG0 signatures the default sigin is calculated at the moment the object is created, not at
       the moment that the packet is put on the wire.

       Notes:

       - Do not change the name of the file generated by dnssec-keygen, the
         create method uses the filename as generated by dnssec-keygen to determine
         the keyowner, algorithm and the keyid (keytag).

       - Only RSA signatures (algorithm 1 and 5) and DSA signatures
         (algorithm 3) have been implemented.

   typecovered
           print "typecovered =", $rr->typecovered, "\n"

       Returns the type covered by the sig (should be TYPE000 with common SIG0 usage)

   algorithm
           print "algorithm =", $rr->algorithm, "\n"

       Returns the algorithm number used for the signature

   sigexpiration
           print "sigexpiration =", $rr->sigexpiration, "\n"

       Returns the expiration date of the signature

   siginception
           print "siginception =", $rr->siginception, "\n"

       Returns the date the signature was incepted.

   keytag
           print "keytag =", $rr->keytag, "\n"

       Returns the the keytag (key id) of the key the sig was made with.  Read "KeyID Bug in bind." below.

   signame
           print "signame =", $rr->signame, "\n"

       Returns the name of the public KEY RRs  this sig was made with.  (Note: the name does not contain a
       trailing dot.)

   sig
           print "sig =", $rr->sig, "\n"

       Returns the base64 representation of the signature.

   verify and vrfyerrstr
           my $sigrr=$update1->pop("additional");
           $sigrr->verify($packet, $keyrr) || croak $sigrr->vrfyerrstr;

       If the first argument is a Net::DNS::Packet object and if $sig->type equals zero a a sig0 verification is
       performed. Note that the signature needs to be 'popped' from the packet before verifying.

       Returns 0 on error and sets $sig->vrfyerrstr

   Example
          my $sigrr=$packet->pop("additional");
          print $sigrr->vrfyerrstr unless $sigrr1->verify($update1, $keyrr1);

Remarks

       - The code is not optimized for speed whatsoever. It is probably not
         suitable to be used for signing large zones.

TODO

       - Clean up the code, it still contains some cruft left from the times that
         the SIG RR was used for signing packets and RR sets.

       - If this code is still around by 2030 you have a few years to check
         the proper handling of times...

ACKNOWLEDGMENTS

       Andy Vaskys (Network Associates Laboratories) supplied the code for handling RSA with SHA1 (Algorithm 5).

       Chris Reinardt for maintianing Net::DNS.

       T.J. Mather, <tjmather@tjmather.com>, the Crypt::OpenSSL::DSA maintainer, for his quick responses to bug
       report and feature requests.

COPYRIGHT

       Copyright (c) 2001-2005  RIPE NCC.  Author Olaf M. Kolkman <olaf@net-dns.org>

       All Rights Reserved

       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, written prior permission.

       THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF
       MERCHANTABILITY AND FITNESS; IN NO EVENT SHALL AUTHOR BE LIABLE FOR ANY SPECIAL, INDIRECT OR
       CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
       AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE
       OR PERFORMANCE OF THIS SOFTWARE.

       Based on, and contains, code by Copyright (c) 1997 Michael Fuhr.

       This code uses Crypt::OpenSSL which uses the openssl library

SEE ALSO

       http://www.net-dns.org/ <http://www.net-dns.org/>

       perl(1), Net::DNS, Net::DNS::Resolver, Net::DNS::Packet, Net::DNS::Header, Net::DNS::Question,
       Net::DNS::RR,Crypt::OpenSSL::RSA,Crypt::OpenSSL::DSA, RFC 2931.