.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "SEC::Private 3pm"
.TH SEC::Private 3pm "2010-03-12" "perl v5.12.4" "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::Private \- DNS SIG Private key object
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
use Net::DNS::SEC::Private;
my \f(CW$private\fR=Net::DNS::SEC::Private\->new($keypath);
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Class containing a the private key as read from a dnssec-keygen
generate zonefile. The class is written to be used only in the context
of the Net::DNS::RR::SIG create method. This class is not designed to
interact with any other system.
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
\&\f(CW$private\fR\->new(\*(L"/home/foo/ Kexample.com.+001+11567.private\*(R")
.PP
Creator method. The argument is the full path to a private key
generated by the \s-1BIND\s0 dnssec-keygen tool. Note that the filename contains
information about the algorithm and keyid.
.SS "private"
.IX Subsection "private"
\&\f(CW$private\fR\->private
.PP
Returns the private key material. This is either a Crypt::OpenSSL::RSA
or Crypt::OpenSSL::DSA object. This is really only relevant to the
Net::DNS::RR::SIG class.
.SS "algorithm, keytag, signame"
.IX Subsection "algorithm, keytag, signame"
.Vb 3
\& $private\->algorithm
\& $private\->keytag
\& $private\->signame
.Ve
.PP
Returns components as determined from the filename and needed by
Net::DNS::RR::RRSIG.
.SH "RSASHA1 specific helper functions"
.IX Header "RSASHA1 specific helper functions"
These functions may be usefull to read and transfer \s-1BIND\s0 private keys to and
from X509 format.
.SS "new_rsa_private"
.IX Subsection "new_rsa_private"
Constructor method.
.PP
.Vb 1
\& my $private=Net::DNS::SEC::Private\->new_rsa_private($keyblob,$domain,$flag);
.Ve
.PP
Creates a Net::DNS::SEC::Private object from the supplied string.  For
the object to be useful you will have to provide the \*(L"domain\*(R" name for
which this key is to be used as the second argument and the flag
(either 256 or 257 for a non \s-1SEP\s0 and a \s-1SEP\s0 key respectivly).
.PP
The string should include the \-\-\-\-\-BEGIN...\-\-\-\-\- and \-\-\-\-\-END...\-\-\-\-\-
lines.  The padding is set to \s-1PKCS1_OAEP\s0, but can be changed with the
use_xxx_padding methods
.PP
It is the same
.SS "dump_rsa_priv"
.IX Subsection "dump_rsa_priv"
.Vb 1
\&  my $bind_keyfilecontent=$private\->dump_rsa_priv
.Ve
.PP
Returns the content of a \s-1BIND\s0 private keyfile (Private-key-format: v1.2).
.PP
An empty string will be returned if not all parameters are available (please
supply the author with example code if this ever happens).
.SS "dump_rsa_pub"
.IX Subsection "dump_rsa_pub"
.Vb 1
\&    my $bind_keyfilecontent=$private\->dump_rsa_pub
.Ve
.PP
Returns the publick key part of the \s-1DNSKEY\s0 \s-1RR\s0.
.PP
Returns an empty string on failure.
.SS "dump_rsa_keytag"
.IX Subsection "dump_rsa_keytag"
.Vb 2
\&    my $flags=257;   # SEP key.
\&    my $keytag=$private\->dump_rsa_keytag($flags);
.Ve
.PP
This function will calculate the keyt with the value of the \s-1DNSKEY\s0
flags as input.
.PP
The flags field may be needed in case it was not specified when the
key was created. If the object allready knows it's flags vallue the
input is ignored.
.PP
returns undefined on failure
.SS "dump_rsa_private_der"
.IX Subsection "dump_rsa_private_der"
.Vb 1
\&    my $keyblob=$private\->dump_rsa_privat_der
.Ve
.PP
Return the DER-encoded \s-1PKCS1\s0 representation of the private key. (Same format that
can be read with the read_rsa_private method.)
.SS "generate_rsa"
.IX Subsection "generate_rsa"
.Vb 3
\&    my $keypair=Net::DNS::SEC::Private\->generate_rsa("example.com",$flag,1024,$random);
\&prin $newkey\->dump_rsa_priv;
\&print $newkey\->dump_rsa_pub();
.Ve
.PP
Uses Crypt::OpenSSL::RSA generate_key to create a keypair.
.PP
First argument is the name of the key, the second argument is the flag
field (take a value of 257 for Keysigning keys and a value of 256 for
zone signing keys). The 3rd argument is the keysize.
.PP
If the 4th argument is defined it is passed to the
Crypt::OpenSSL::Random::random_seed method (see Crypt::OpenSSL::RSA
for details), not needed with a proper /dev/random.
.SH "Example"
.IX Header "Example"
This is a code sniplet from the test script. First a new keypair is
generated.  An Net::DNS::RR object is created by constructing
the resource record string \- using the \fIdump_rsa_pub()\fR method.
.PP
Then a self signature over the public key is created and verified.
.PP
.Vb 6
\&    my $newkey=Net::DNS::SEC::Private\->generate_rsa("example.com",257,1024);
\&    my $tstpubkeyrr= Net::DNS::RR\->new ($newkey\->signame .
\&                                    "  IN DNSKEY 257 3 5 ".
\&                                    $newkey\->dump_rsa_pub());
\&    # flags not needed as argument for dump_rsa_keytag
\&    $ since they where set by generate_rsa
\&
\&    is($tstpubkeyrr\->keytag,$newkey\->dump_rsa_keytag(),
\&                "Consistent keytag calculation");
\&
\&    my $sigrr= create Net::DNS::RR::RRSIG([$tstpubkeyrr],$newkey);
\&    is ($sigrr\->keytag,$tstpubkeyrr\->keytag,
\&            "Consisted keytag in the created signature");;
\&
\&    ok($sigrr\->verify([$tstpubkeyrr],$tstpubkeyrr), 
\&             "Self verification consistent.");
.Ve
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2002\-2005 \s-1RIPE\s0 \s-1NCC\s0.  Author Olaf M. Kolkman <olaf@net\-dns.org>
.PP
All Rights Reserved
.PP
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.
.PP
\&\s-1THE\s0 \s-1AUTHOR\s0 \s-1DISCLAIMS\s0 \s-1ALL\s0 \s-1WARRANTIES\s0 \s-1WITH\s0 \s-1REGARD\s0 \s-1TO\s0 \s-1THIS\s0 \s-1SOFTWARE\s0, \s-1INCLUDING\s0
\&\s-1ALL\s0 \s-1IMPLIED\s0 \s-1WARRANTIES\s0 \s-1OF\s0 \s-1MERCHANTABILITY\s0 \s-1AND\s0 \s-1FITNESS\s0; \s-1IN\s0 \s-1NO\s0 \s-1EVENT\s0 \s-1SHALL\s0
\&\s-1AUTHOR\s0 \s-1BE\s0 \s-1LIABLE\s0 \s-1FOR\s0 \s-1ANY\s0 \s-1SPECIAL\s0, \s-1INDIRECT\s0 \s-1OR\s0 \s-1CONSEQUENTIAL\s0 \s-1DAMAGES\s0 \s-1OR\s0 \s-1ANY\s0
\&\s-1DAMAGES\s0 \s-1WHATSOEVER\s0 \s-1RESULTING\s0 \s-1FROM\s0 \s-1LOSS\s0 \s-1OF\s0 \s-1USE\s0, \s-1DATA\s0 \s-1OR\s0 \s-1PROFITS\s0, \s-1WHETHER\s0 \s-1IN\s0
\&\s-1AN\s0 \s-1ACTION\s0 \s-1OF\s0 \s-1CONTRACT\s0, \s-1NEGLIGENCE\s0 \s-1OR\s0 \s-1OTHER\s0 \s-1TORTIOUS\s0 \s-1ACTION\s0, \s-1ARISING\s0 \s-1OUT\s0 \s-1OF\s0
\&\s-1OR\s0 \s-1IN\s0 \s-1CONNECTION\s0 \s-1WITH\s0 \s-1THE\s0 \s-1USE\s0 \s-1OR\s0 \s-1PERFORMANCE\s0 \s-1OF\s0 \s-1THIS\s0 \s-1SOFTWARE\s0.
.PP
This code uses Crypt::OpenSSL which uses the openssl library
.SH "SEE ALSO"
.IX Header "SEE ALSO"
http://www.net\-dns.org/ <http://www.net-dns.org/>
.PP
\&\fIperl\fR\|(1), Net::DNS, Net::DNS::RR::SIG, Crypt::OpenSSL::RSA,Crypt::OpenSSL::DSA, \s-1RFC\s0 2435 Section 4, \s-1RFC\s0 2931.