Key(3)

NAME
Net::DNS::SEC::Maint::Key - Class used for implementing a DNSSEC Key Database

DESCRIPTION
This class implements an interface to a database of private keys used during DNSSEC administration. The class implements the Key object.

A Key object has two 'incarnations' when an instance is first created it is a generic object that knows all about the database in which the keys are stored;

Once the 'fetch' method (see below) is called the attributes that are specific to one key in the database are loaded and can be accessed with number of methods documented below.

Generic database methods.

  new ($responsible_person, $session_id)
    my $keydb=Net::DNS::SEC::Maint::Key->new;

Initializes a key object that can be used to create access, modify and delete DNSSEC keypairs. The arguments are used for logging purposes.

  get_keyset
   $keyset=$keydb->get_keyset($domain);
   $keyset=$keydb->get_keyset($domain,$ttl);

Unless specified by the second argument the TTL on the keys in the keyset is set to 3600,

The method returns a string with a string representation of the key RRs that are used for signing i.e. the keys that are set as ACTIVE.

  get_all Get all keys.
   @keyobjects=$keydb->get_all();
   @keyobjects=$keydb->get_all($domainlist);

Returns an array of 'fetched' keyobjects.

  get_active
    @keys=$keydb->get_active($domain,$algorithm);
    @keys=$keydb->get_active_zone ($domain,$algorithm);
    @keys=$keydb->get_active_key ($domain,$algorithm);

Returns an array of key objects with the set of all active keys, the active zone signing keys or the active keysigning keys for the specified domain respectively.

The return value is an array containing strings specifiying the paths to the private keys of the active keys.

The 'algorithm' must be the algorithm in string representation.

An optional 3rd argument (boolean) determines if the not-active keys are returned as well.

  get_inactive
    @keys=$keydb->get_inactive($domain,$algorithm);
    @keys=$keydb->get_inactive_zone ($domain,$algorithm);
    @keys=$keydb->get_inactive_key ($domain,$algorithm);

Same as get_active but then for in_active keys.

  get_published
    @keys=$keydb->get_published($domain,$algorithm);
    @keys=$keydb->get_published ($domain,$algorithm);
    @keys=$keydb->get_published ($domain,$algorithm);

Same as get_active but then for published keys.

  purge
  $keydb->purge;

Delete private keys are actually not deleted but stored elsewhere in the database, inaccesible to the user. The purge command will remove these "backup" keys as well as all the data about keys that used to exist (possibly shorten the list of domains that is returned with the get_available_domain method)

As this is a somewhat radical method advice not to use this command as it will prohibit manual rollback in case the database gets corrupted.

Rollover Commands
The system implements rudmentary rollover methods. Only the more simple rollover methods as discribed in [Document with distribution] is implemented.

The automatic rollover commands may fail to work if you have tried to mannually add or remove keys. For more details see the rollover_zone and rollover_key methods.

  set_rollover, unset_rollover, is_rollover
These methods set, unset and determine the state of the rollover attribute. These methods should not be used directly, they may lead to database inconsistencies. Use rollover_zone and rollover_key methods instead. Be careful if you use these methods anyway (use in combination with the checkconsistency method)

  get_rollover, get_rollover_key, get_rollover_zone
    @keys=$key->get_rollover($domain,$algorithm);

    @keys=$key->get_rollover_key($domain,$algorithm);
    @keys=$key->get_rollover_zone($domain,$algorithm);

Returns an array of key objects with the set of all keys for the specified domain that have the rollover attribute set.

The return value is an array containing strings specifiying the paths to the private keys of the active keys.

If the 2nd optional paramater is specified then only the keys that have the rollover attribute set for the specified domain AND algorithm are returned.

  rollover_zone
    $key->rollover_zone($domain,"RSASHA1")

The rollover_zone command takes care of rolling a zone signing key. This method implies that a very specific key maintenance scheme is used; At any given time not more than two zone-signing keys (per algorithm) are published in the keyset.

The first argument specifies for which domain the rollover is to take place, the second specifies for which algorithm (by name) there is a zone signing key rollover. If there are only keys from one algorithm then this argument is optional.

The method returns 0 on success or a string with an error condition.

The rollover precondition is that one of the keys (key 1) is active and another key (key 2) is published (see set_published method). When the rollover_zone method first is issued key 1 is set to published and marked as "rollover" (see is_rollover method), the key 2 is then set to active.

When the rollover_zone method is called a second time the system first determines if a zone signing key rollover is in progress. If so key 1, the key that has the rollover attribute set, will be deleted from the system and a new key, key 3, will be created so that it can be used in the future.

Users of the rollover method should be carefull issueing the rollover commands to fast. The data signed with the different keys and the different keysets, as published in the DNS, will need time to propagate. One should not underestimate the time needed for DNS data to propagate.

  rollover_key
    $key->rollover_key($domain,"RSASHA1")

The rollover_key command takes care of rolling a key signing key. This method implies that a very specific key maintenance scheme is used; At any given time not more than two zone-signing keys (per algorithm) are published in the keyset.

The first argument specifies for which domain the rollover is to take place, the second specifies for which algorithm (by name) there is a zone signing key rollover. If there are only keys from one algorithm then this argument is optional.

The method returns 0 on success or a string with an error condition.

The rollover precondition is that there is one that there are one ore more active key signing key. When the rollover_zone method first is issued the oldest key is marked as "rollover" (see is_rollover method), a new key is created and both keys and set to active. The key second key should be exchanged with the parent.

When the rollover_key method is called a second time the system first determines if a key signing key rollover is in progress. If so the key marked as "rollover" will be deleted from the system.

Users of the rollover method should be carefull issueing the rollover commands to fast. The data signed with the different keys and the different keysets, as published in the DNS, will need time to propagate. One should not underestimate the time needed for DNS data to propagate.

  get_rollover
  @rolloverkeys=$key->get_rollover($domain);

Returns an array of 'fetched' keys for wich the rollover attribute is set.

  get_available_domains
Returns array with domains for which there are, or have been, keys in the database.

If a non-zero argument is provided then only the domains for which there currently are private keys are returned.

  get_algo_id_pairs
  $key->get_algo_id_pairs($domain);

Returns array with algo_idpairs in "algo+keyid" notation. Returns empty array on error.

  get_available_keyids
  @keyids=$self->get_available_keyid("RSASHA1",$domains);

Returns an array of keyIDs for the specified algorithm from specfied domains.

Methods to operate on specific keys

  create
   $key->create($domainname,$algorithm,$keysize,
                $functionality,$setactive)

Adds a new key to the database. Returns the new key. The functinality is either ZSK or KSK, setactive is a boolean, if true the key is set to active no matter what.

  fetch
  $key->fetch($domain,$algorithm,$keyid);
  $key->fetch($fullpath);

Sets the $key attributes to reflect domain, algorithm (by name or number) and keyid. Once the key is fetched one can use the deletekey, bla and foo methods on it.

Alternatively one can specify the full path to the private key. This may be handy because an array containing those paths is returned by other methods.

Returns 0 if the key is uniquely identified. Ruturns a string with error conditition if the key could not be uniquely identified or could not otherwise be fetched.

  deletekey
    $key->deletekey;

Delete the "fetched" key.

  state
  $state=$key->state;
  die "state change failed" if "ACTIVE" ne $key->state("active");

Read or set the state attribute of a key. A key can be

  ACTIVE      : Used for signing and published in a keyset.
  PUBLISHED   : Published in a keyset but not used for signing.
  INACTIVE    : Not published in a keyset nor used for signing.

On success the method returns the state (in upper case) othewise the method rerurns an error mesage.

The argument has to be one of the states mentioned above. The input is case insensitive.

  get_state_change
Returns the time of the last state change (in seconds since epoch).

  is_active, is_published, is_inactive
These are wrappers around the "state" method.

Returns true if the state of a key is ACTIVE, PUBLISHED or INACTIVE respectively.

  set_active, set_published, set_inactive
These are wrappers around the "state" method.

Set the state of a fetched key to ACTIVE, PUBLISHED or INACTIVE respectively.

  is_zsk, is_ksk
    print "Key is Keysigning Key" if $key->is_zsk;

Returns true if the key is a zone signing or a key signing key respectivly

Note that the fact that a key is a zone or key singing key is determined at key creation time. Hence there are no equivalent set methods.

  is_algortithm();
  print "Is an RSASHA1 KEY" if $key->is_algorithm("rsasha1");
  print "Is an RSASHA1 KEY" if $key->is_algorithm(5);

Tests if the algorithm of the key stored in $key is the one that has been provided in the argument.

  get_algortithm, get_keyid, get_keypath
After applying the fetch method these method will return non-empty strings.

   $key->fetch("dacht.net","RSASHA1","21827");
   print $key->get_keypath;

get_keypath the path to the private key. Returns empty string if the path is not set. Only useful after the fetch method that uniqely identifies a key.

get_keypath

   $key->fetch("dacht.net","RSASHA1","21827");
   print $key->get_keypath;

Returns the path to the private key. Returns empty string if the path is not set. Only useful after the fetch method that uniqely identifies a key.

  keysize
Returns a string the size of the key.

    print $key->keysize();

  description
    print $key->description."\n"

Returns a string with a consice description of the key.

  keyrrstring
    print $key->keyrrstring;
    print $key->keyrrstring(3600);

Prints a multiline representation of the key RR string. By default the TTL of the key RR is set to 0. An optional argument will overwrite this.

Some helper methods
These are methods used by other methods to access some esoteric attributes. They may proof handy for other tools.

  get_SessionID
  print $key->get_SessionID

Each session is associated with a sessionID that consists of a string with the date in yyyymmddhhmm and a random number. The SessionID is used for logging purposes.

  add_log_message
  $key->add_log_message("Add some LOG message to the key");

Adds a log message to the key.

Use only on 'fetch'ed keys

  checkconsistency
    $key->fetch($fullpath);
    $key->checkconsistency;

Checks the consistency of the different attributes that may be set for a given key.

The method should only be used on 'fetched' keys. Will return an error message if there is an inconsistency. The message generated will be something like:

 "Database inconistency: ...."

returns 0 if there are no problems.

  algorithms
Returns the avialble algorithms. The list of algorithms is hardcoded and should be consistent to the list as offered by dnssec-keygen.

(TODO: make this a configuration option?)

  valid_algorithm
Returns true if the argument is a valid algotithm i.e. if it is one of the algorithms returned by the algorithm method.

  getconf
When a key object is created using 'new' there it contains an embedded Net::DNS::SEC::Maint::Config object.

This is the interface method that accesses the embedded Net::DNS::SEC::Maint::Key::Config object see Net::DNS::SEC::Config and Net::DNS::SEC::Maint::Key::Config for details.

Functions

oldest_key
Helper function. The input is an array of keys. The function returns the key that had the first state_change

If there are multiple keys that had the state change at exactly the same moment the key with the lowest keyid is returned.

typical use case is $oldest_key_active_key=oldest_key($keydb->get_active("bla.foo","RSAHA1")); returns the oldest_key key or undefined on failure...

Logging
The class uses log4perl for logging.

If not yet initialized the code will use /usr/local/etc/log4perl.conf, /etc/log4perl.conf or use the default:

    log4perl.appender.Logfile          = Log::Log4perl::Appender::File
    log4perl.appender.Logfile.filename = test.log
    log4perl.appender.Logfile.layout   = Log::Log4perl::Layout::PatternLayout
    log4perl.appender.Logfile.layout.ConversionPattern = [%r] %F %L %m%n

    log4perl.appender.Screen         = Log::Log4perl::Appender::Screen
    log4perl.appender.Screen.stderr  = 0
    log4perl.appender.Screen.layout = Log::Log4perl::Layout::SimpleLayout

REFERENCES
[1] SEP KEY

TODO, BUGS and FEATURS
Whenever a database inconsistency is encountered the module will call "die()".

COPYRIGHT
Copyright (c) 2004 RIPE NCC. Author Olaf M. Kolkman <net-dns-sec@ripe.net>

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.

SEE ALSO