File Coverage

blib/lib/Net/DNS/SEC/Keyset.pm

Criterion	Covered	Total	%
statement	112	112	100.0
branch	28	28	100.0
condition	7	7	100.0
subroutine	19	19	100.0
pod	9	9	100.0
total	175	175	100.0

package Net::DNS::SEC::Keyset;

use strict;
use warnings;

our $VERSION = (qw$Id: Keyset.pm 1868 2022-08-31 20:13:35Z willem $)[2];


=head1 NAME

Net::DNS::SEC::Keyset - DNSSEC Keyset object class


=head1 SYNOPSIS

    use Net::DNS::SEC::Keyset;


=head1 DESCRIPTION

A keyset is an "administrative" unit used for DNSSEC maintenance.

This class provides interfaces for creating, reading and writing keysets.

Object methods are provided to extract DNSKEY, RRSIG and DS records.

Note that this class is still being developed.
Attributes and methods are subject to change.

=cut


use Carp;
use File::Spec;
use IO::File;

use Net::DNS::ZoneFile;

our $keyset_err;


sub new {
	my ( $class, $arg1, $arg2 ) = @_;

	my $ref1 = ref($arg1);
	return &_new_from_file unless $ref1;

	return &_new_from_packet if $ref1 eq 'Net::DNS::Packet';

	return &_new_from_keys unless ref($arg2);

	return &_new_from_keys_sigs;
}


=head2 new (from file)

    $keyset = Net::DNS::SEC::Keyset->new( $filename );
    $keyset = Net::DNS::SEC::Keyset->new( $filename, $directory );
    die Net::DNS::SEC::Keyset->keyset_err unless $keyset;

Constructor method which reads the specified keyset file and returns a
keyset object.

The optional second argument specifies the filename base directory.

Sets keyset_err and returns undef on failure.

=cut

sub _new_from_file {
	my ( $class, $name, @path ) = @_;

	my $file = File::Spec->catfile( @path, $name );

	my @rr = Net::DNS::ZoneFile->new($file)->read;

	return $class->_new_from_keys_sigs( \@rr, \@rr );
}


=head2 new (by signing keys)

    $keyset = Net::DNS::SEC::Keyset->new( [@keyrr], $privatekeypath );
    die Net::DNS::SEC::Keyset->keyset_err unless $keyset;

Creates a keyset object from the keys provided through the reference to an
array of Net::DNS::RR::DNSKEY objects.

The method will create and self-sign the whole keyset. The private keys as
generated by the BIND dnssec-keygen tool are assumed to be in the current
directory or, if specified, the directory indicated by $privatekeypath.

Sets keyset_err and returns undef on failure.

=cut

sub _new_from_keys {
	my ( $class, $keylist, @keypath ) = @_;

	my @sigrr;
	foreach my $key ( grep { $_->type eq 'DNSKEY' } @$keylist ) {
		my $keyname = $key->privatekeyname;
		my $keyfile = File::Spec->catfile( @keypath, $keyname );
		my @rrsig   = Net::DNS::RR::RRSIG->create( $keylist, $keyfile );
		push @sigrr, grep {defined} @rrsig;
	}

	return $class->_new_from_keys_sigs( $keylist, \@sigrr );
}


=head2 new (from key and sig RRsets)

    $keyset = Net::DNS::Keyset->new( [@keyrr], [@sigrr] );
    die Net::DNS::SEC::Keyset->keyset_err unless $keyset;

Creates a keyset object from the keys provided through the references
to arrays of Net::DNS::RR::DNSKEY and Net::DNS::RR::RRSIG objects.

Sets keyset_err and returns undef on failure.

=cut

sub _new_from_keys_sigs {
	my ( $class, $key_ref, $sig_ref ) = @_;

	my @keyrr = grep { $_->type eq 'DNSKEY' } @$key_ref;
	my @sigrr = grep { $_->type eq 'RRSIG' } @$sig_ref;

	my $keyset = bless {keys => \@keyrr, sigs => \@sigrr}, $class;

	return scalar( $keyset->verify ) ? $keyset : undef;
}


=head2 new (from Packet)

    $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;

Creates a keyset object from a Net::DNS::Packet that contains the answer
to a query for key records at the zone apex.

This is the method you should use for automatically fetching keys.

Sets keyset_err and returns undef on failure.

=cut

sub _new_from_packet {
	my ( $class, $packet ) = @_;
	my @rrset = $packet->answer;
	return $class->_new_from_keys_sigs( \@rrset, \@rrset );
}


=head2 keys

    @keyrr = $keyset->keys;

Returns an array of Net::DNS::RR::DNSKEY objects.

=cut

sub keys {
	my $self = shift;
	my @keys = @{$self->{keys}};
	return @keys;
}


=head2 sigs

    @sigrr = $keyset->sigs;

Returns an array of Net::DNS::RR::RRSIG objects.

=cut

sub sigs {
	my $self = shift;
	my @sigs = @{$self->{sigs}};
	return @sigs;
}


=head2 extract_ds

    @ds = $keyset->extract_ds();	# default SHA-1
    @ds = $keyset->extract_ds( digtype => 'SHA-256' );
    die Net::DNS::SEC::Keyset->keyset_err unless @ds;

Extracts DS records from the keyset. Note that the keyset will be verified
during extraction. All keys will need to have a valid self-signature.

The method sets keyset_err if verification fails.

=cut

sub extract_ds {
	my ( $self, @arg ) = @_;
	my @ds;
	@ds = map { Net::DNS::RR::DS->create( $_, @arg ) } $self->keys if $self->verify;
	return @ds;
}


=head2 verify

    @keytags = $keyset->verify();
    die Net::DNS::SEC::Keyset->keyset_err unless @keytags;

    $keyset->verify( $keytag ) || die $keyset->keyset_err;

If no arguments are given:

=over 2

=item

Verifies if all signatures present verify the keyset.

=item

Verifies if there are DNSKEYs with the SEP flag set, there is at
least one RRSIG made using that key.

=item

Verifies that if there are no DNSKEYs with the SEP flag set there
is at least one RRSIG made with one of the keys from the keyset.

=back

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 RRSIG.

The method returns a list of keytags of verified keys in the keyset.

The method sets keyset_err and returns empty list if verification fails.

=cut

sub verify {
	my ( $self, $keyid ) = @_;

	my @keys = $self->keys;

	my %keysbytag;
	push( @{$keysbytag{$_->keytag}}, $_ ) foreach @keys;

	my @sigs = $self->sigs;

	my @keyset_err;
	my %names = map { ( $_->name => $_ ) } @keys, @sigs;
	my @names = CORE::keys %names;
	push @keyset_err, "Multiple names in keyset: @names" if scalar(@names) > 1;


	if ($keyid) {
		@sigs = grep { $_->keytag == $keyid } @sigs;
		push @keyset_err, "No signature made with key $keyid" unless @sigs;
	} elsif ( my @sepkeys = grep { $_->sep } @keys ) {
		my %sepkey = map { ( $_->keytag => $_ ) } @sepkeys;
		push @keyset_err, 'No signature found for key with SEP flag'
				unless grep { $sepkey{$_->keytag} } @sigs;
	}

	foreach my $sig (@sigs) {
		my $keytag = $sig->keytag;
		next if $sig->verify( \@keys, $keysbytag{$keytag} || [] );
		my $vrfyerr = $sig->vrfyerrstr;
		push @keyset_err, "$vrfyerr for keyset @names";
	}

	$keyset_err = join "\n", @keyset_err;

	my @tags_verified;
	@tags_verified = map { $_->keytag } @sigs unless $keyset_err;
	return @tags_verified;
}


=head2 keyset_err

    $keyset_err = Net::DNS::SEC::Keyset->keyset_err;

Returns the keyset error string.

=cut

sub keyset_err {
	return $keyset_err;
}


=head2 string

    $string = $keyset->string;

Returns a string representation of the keyset.

=cut

sub string {
	my $self = shift;
	return join "\n", map { $_->string } ( $self->keys, $self->sigs );
}


=head2 print

    $keyset->print;		# similar to print( $keyset->string )

Prints the keyset.

=cut

sub print {
	my $self = shift;
	foreach ( $self->keys, $self->sigs ) { $_->print }
	return;
}


=head2 writekeyset

    $keyset->writekeyset;
    $keyset->writekeyset( $path );
    $keyset->writekeyset( $prefix );
    $keyset->writekeyset( $prefix, $path );

Writes the keyset to a file named "keyset-." in the current
working directory or directory defined by the optional $path argument.

The optional $prefix argument specifies the prefix that will be
prepended to the domain name to form the keyset filename.

=cut

sub writekeyset {
	my ( $self, $arg1, @path ) = @_;
	shift;
	@path = shift() if $arg1 && File::Spec->file_name_is_absolute($arg1);
	my $prefix = shift || 'keyset-';

	my @keysetrr   = ( $self->keys, $self->sigs );
	my $domainname = $keysetrr[0]->name;
	my $keysetname = "$prefix$domainname.";
	my $filename   = File::Spec->catfile( @path, $keysetname );
	$filename =~ s/[.]+/\./;	## avoid antisocial consequences of $path with ..
	my $handle = IO::File->new( $filename, '>' ) or croak qq("$filename": $!);
	select( ( select($handle), $self->print )[0] );
	close($handle);
	return $filename;
}


1;

__END__