USAGE_SEC
			Secure DNS (TIS/DNSSEC)
			   September 1996

This is the usage documentation for TIS' Secure DNS (TIS/DNSSEC) version
BETA-1.3.  This looks like a standard named distribution, with
the following exceptions

	this version is coded against BIND-4.9.4-P1

	there are three new directories in this distribution
		dnssec_lib
		signer
		rsaref
		

	rsaref/ is place holder directory for RSAREF distribution.
	You must get RSAREF on your own. 

	signer/  contains two applications needed by DNSSEC: 
		signer:  tool to sign zones
		key_gen: tool to generate keys
	dnssec_lib/ contains common library routines that are used by
		named, key_gen and signer. 
		This is where most of the DNSSEC work is done. 

Before compiling you need to do your standard configurations for named
and the edits explained in INSTALL_SEC.  This version has been tested
on SUNOS4.1.3. This version includes portability fixes from previous
beta releases for Linux, Solaris-2.4, HPUX-9 and FreeBSD.

CHANGES TO BIND

res/

	There are minor changes to the files in the res directory.  Most of
	the changes have to do with displaying NXT
	records. There are also some changes related to translating
	domain names into uncompressed lower case names upon request.

tools/
	Minor changes to recognize NXT records and display them.

named/
	Added code to read and write new record types. 
	Added code to do signature validation on read. 
	Added code to return appropriate SIG records.
	Added security flags to databuf and zoneinfo structures. 
	Names can now have CNAME record and security RR's. 
	Records are stored and transmitted in DNS SEC sort order.

conf/

	Turned off ROUND_ROBIN option and installed new sorting required
	for signature verification. 

signer/
	NXT record generation.
	Key generation
	Signing of zones
	Converting data records to format required for signatures.

dnssec_lib/
	Interfacing with Crypto library.
	Verifying signatures, 
	preparing data for signing and verification

The role of <zone>.PARENT files:

DNSSEC specification requires change who is authorative for certain
resource records. In order to support certification hierarchy each
zone KEY RR must be signed by parent zone. The parent signed KEY RR
must be distributed by the zone itself as it is the most authorative
for its own records. 

To facilitate this TIS/DNSSEC signer program creates a <name>.PARENT
file for every name in a zone that has a NS record. This file contains
the KEY records stored under this name and 
NXT record and corresponding SIG records. If no KEY record is found
for a name with a NS record a NULL-KEY record is generated to indicate
that the child is INSECURE. 

Each <zone>.PARENT file must be sent via an out of band mechanism to
the appropriate primary for the zone, for inclusion.  signer program
adds an $INCLUDE <zone>.PARENT command at the end of each zone file,
if no file exists an warning message is printed.

Potential PROBLEM: It is likely that the parent and child are on a
different signing schedule. If new <zone>.PARENT file is put on the
primary, due to the fact that the zone data changed but the SOA did
not, it may take a long time for new records to propagate to the
secondaries.  This is only a problem if zone has added/deleted a KEY
or if the the signatures will expire in the near future. To overcome
this problem, resign your zone when any of above conditions is true.
DNS NOTIFY and/or DNS DYNUPDATE may fix this problem in the future.

TIS/DNSSEC SOA serial numbers. To facilitate prompt distribution of
zone data to secondaries, signer takes over the management of SOA
serial numbers. Each time signer signs a zone it sets the serial
number to a value reflecting the time the zone was signed, in standard
Unix time seconds since 1970/1/1 0:0:0 GMT.

How to configure a secure zone. 
	Create a directory <zone> to contain your zone files.
	Create a output directory <outdir> for the signer output.
	Put in <zone> a boot file that includes the files from that zone.
	Create a KEY for the zone by running key_gen, Name the key <domain>.

	Run signer on your zone writing to the output directory <outdir>. 
	Signer will rewrite the boot file to include new directive 
		"pubkey" of the key used to sign the file. If there where
		any pubkey declarations in the input boot file they will be
		deleted. 
	Signer generates files that correspond to the load files specified.

	In case of load file that $INCLUDEs another load file, signer will 
		merge them to the output file. 
	You will notice that the output files are significantly larger. 
	The output files will be in a different order than the input files,
		all records are sorted into DNSSEC sort order. 
	NXT and SIG records have been added. 

	If there are any NS records for a name other than the zone name of
		each input file you will see messages that NULL KEY records 
		have been created, if this is not correct behavior, add 
		the correct KEY RRs.
	For each domain name that has a NS record but is not a zone name 
		of load file you will see a file named  <name>.PARENT, 
		this file contains the KEY record for that name and an 
		NXT record + 2 SIG records. 
	This file needs to be sent to the nameserver that is primary for that
		zone. There are two reasons for this: 
		1. To support Certification Hierarchy, each zone key is 
	        signed by the parent zone key. 
		2. Zone is the most trustworthy source for itself unless 
		these records are loaded into the primary server for
		the zone, the records may not get propagated.

how to run SEC_NAMED:

Included in the distribution there is a small test setup:

# run signer 
./signer boot-f simple_test/test.boot [out-dir /tmp] 
# or 
make test
# This takes few minutes to run depending on your machine and the size
# of the key selected 
# all output files will be stored in /tmp unless out-dir is specified

# 
# Now we are ready to run named 
cd ../named
./named -p 12345 -b /tmp/test.boot.save [-d x] 

# 
# you can now check for data in the data base
# using the new dig. 
#
cd ../tools
./dig @yourhost snore.foo.bar. any in -p 12345 

#
# Output from new dig will be something like this
#
; <<>> DiG 2.1 <<>> @dnssrv snore.foo.bar. any in -p 
; (1 server found)
;; res options: init recurs defnam dnsrch
;; got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 10
;; flags: qr rd ra; Ques: 1, Ans: 11, Auth: 0, Addit: 1
;; QUESTIONS:
;;      snore.foo.bar, type = ANY, class = IN

;; ANSWERS:
snore.foo.bar.  259200  A       10.17.3.20
snore.foo.bar.  259200  SIG     A (
                 1 3; alg labels
        259200  ; TTL
        19950506200636  ; Signature expiration
        19950406200659  ; time signed 
        47437   ; Key foot print
        foo.bar.        ; Signers name  
                FsqeW3hstM8Q6v8PMCGPsVMfO6dEpHjFgKm2dJRaofFtCQ/CT9O6Vo7J5zgkV+5ciWQwuZwvzW071jnZ1i27Ip/8vqdKGHC63tjWkCHSZV0=
        ) ; END Signature
snore.foo.bar.  259200  MX      96 who.foo.bar.
snore.foo.bar.  259200  MX      100 foo.bar.
snore.foo.bar.  259200  MX      120 xxx.foo.bar.
snore.foo.bar.  259200  MX      130 maGellan.foo.bar.
snore.foo.bar.  259200  MX      140 bozo.foo.bar.
snore.foo.bar.  259200  SIG     MX (
                 1 3; alg labels
        259200  ; TTL
        19950506200636  ; Signature expiration
        19950406200659  ; time signed 
        47437   ; Key foot print
        foo.bar.        ; Signers name
                EV0cJqF3pUOgktggTrFf55YGwQFbUqPJAMTnAkHK3+Z/Ya6GgwwNOGRzq/FYm5P4E+yIj6WUYFh9Ex5eX5TwiIsjM/hy173lSa3qm/ljDk8=
        ) ; END Signature
snore.foo.bar.  259200  NXT     xxx.foo.bar.
snore.foo.bar.  259200  SIG     NXT (
                 1 3; alg labels
        259200  ; TTL
        19950506200636  ; Signature expiration
        19950406200659  ; time signed 
        47437   ; Key foot print
        foo.bar.        ; Signers name
                eJUHVm5Q5qYQYFVOW0L5Of67HQvQ9+7T7sQqHv7ayTT2sMnXudxviYv43vALMMwBcJFXFEhLhwYwN7pUDssD/w5si/6JJQTi1o30S8si3zE=
        ) ; END Signature

;; Total query time: 195 msec
;; FROM: dnssrv to SERVER: dnssrv  10.17.3.1
;; WHEN: Thu Apr  6 16:20:32 1995
;; MSG SIZE  sent: 31  rcvd: 662