# Introduction

We’re going to deploy OpenDNSSEC to enabled automated DNSSEC management of your zone.

## Notes

- Commands preceded with “$” imply that you should execute the command as a general user - not as root.
- Commands preceded with “#” imply that you should be working as root.
- Commands with more specific command lines (e.g. “rtrX>” or “mysql>”) imply that you are executing commands on remote equipment, or within another program.

# On your authoritative server (SOA)

## Initialize the Software “Hardware Security Module” (SoftHSM)

Start by becoming root for this session (or use sudo when required)

    # mkdir /var/lib/softhsm/tokens
    # softhsm2-util --init-token --slot 0 --label OpenDNSSEC

Use `1234` as a pin for both the SO (Security Office) and the User PIN:

    === SO PIN (4-255 characters) ===
    Please enter SO PIN: ****
    Please reenter SO PIN: ****

    === User PIN (4-255 characters) ===
    Please enter user PIN: ****
    Please reenter user PIN: ****

You should see:

    The token has been initialized.

Check that the token is now configured:

    # softhsm2-util --show-slots

## Set up OpenDNSSEC

### Modify OpenDNSSEC configuration to use SoftHSM

Edit `/etc/opendnssec/conf.xml`, and find the section

    <!--
              <Repository name="SoftHSM">
                            <Module>/usr/lib/softhsm/libsofthsm.so</Module>
                            <TokenLabel>OpenDNSSEC</TokenLabel>
                            <PIN>1234</PIN>
                            <SkipPublicKey/>
                            <!--
                            <AllowExtraction/>
                            -->
                    </Repository>
    -->

Remove the comments (`< !--` and `-- >`) before and after, but leave the ones around `<AllowExtraction/>`

Also, set the correct path for the libsofthsm.so in the `conf.xml` file.

Change:

    <Module>/usr/lib/softhsm/libsofthsm.so</Module>

to

    <Module>/usr/lib/softhsm/libsofthsm2.so</Module>

In the end you should have:

              <Repository name="SoftHSM">
                            <Module>/usr/lib/softhsm/libsofthsm2.so</Module>
                            <TokenLabel>OpenDNSSEC</TokenLabel>
                            <PIN>1234</PIN>
                            <SkipPublicKey/>
                            <!--
                            <AllowExtraction/>
                            -->
                    </Repository>

### Shorten key generation period

To make the key generation period shorter for this lab, find:

            <AutomaticKeyGenerationPeriod>P1Y</AutomaticKeyGenerationPeriod>

And change it to:

            <AutomaticKeyGenerationPeriod>P7D</AutomaticKeyGenerationPeriod>

Save the file, and exit.

### Change the default Policy to be the `Lab` one

Now we’ll be editing `/etc/opendnssec/kasp.xml`. In the file, find the line:

        <Policy name="default">

… and replace default with production so it becomes:

        <Policy name="production">

Then further down, find the line:

        <Policy name="lab">

… and replace ‘lab’ with default so it becomes:

        <Policy name="default">

### Change the lifetime of the KSK

We’re also going to be reducing the lifetime of the KSK to be more useful in a Lab environment:

Still in `/etc/opendnssec/kasp.xml`, change the lifetime of the KSK to be 1 week:

    <KSK>
            <Algorithm length="2048">8</Algorithm>
            <Lifetime>P1Y</Lifetime>
            <Repository>SoftHSM</Repository>
    </KSK>

change to

    <KSK>
            <Algorithm length="2048">8</Algorithm>
            <Lifetime>P7D</Lifetime>
            <Repository>SoftHSM</Repository>
    </KSK>

Save & exit.

### Initialise the database

We’re now ready to initialize the database. By default, OpenDNSSEC uses `sqlite`, an embedded, single user database engine. This is fine for testing and for small deployments, but for real world installations or if you have thousands of zones to manage, you’d probably be using MySQL.

Run the command:

    # ods-enforcer-db-setup

You will be told:

    *WARNING* This will erase all data in the database; are you sure? [y/N]

Answer `y`, and you will see:

    Database setup successfully.

Some directory permissions need to be modified for OpenDNSSEC to work properly:

    # chown -R opendnssec:opendnssec /var/lib/opendnssec
    # chmod -R 755 /var/lib/opendnssec

Finally, restart the enforcer:

    # service opendnssec-enforcer restart

### Import the default policies

We’ll be importing the key management and signing policy configuration we modified earlier (from `/etc/opendnssec/conf.xml`). To do this:

    # ods-enforcer policy import

You will see:

    Created policy production successfully
    Created policy default successfully

## Add the zone to OpenDNSSEC

### Install a copy of the unsigned zone for OpenDNSSEC to sign

We will make a copy of your DNS zone, and place it where OpenDNSSEC expects to find unsigned zones:

    # cd /etc/bind/zones/mytld
    # cp mytld /var/lib/opendnssec/unsigned/mytld

### Add the zone to OpenDNSSEC’s database:

    # ods-enforcer zone add --zone mytld

(Do remember to replace `mytld` with the name of your zone!)

    input is set to /var/lib/opendnssec/unsigned/mytld.
    output is set to /var/lib/opendnssec/signed/mytld.
    Zone mytld added successfully

### Sign the zone

Restart the signer process, it should figure out that you’ve added a zone, keys need to be generated, and the zone needs to be signed.

    # service opendnssec-signer restart

### Check that the zone is signed

To verify that the zone is signed:

    # ls -l /var/lib/opendnssec/signed/

You should see something similar to this:

    -rw-r--r--  1 root  wheel  2621 Feb 19 09:10 mytld

Take a look at the contents of the zone - note the key ids for the `KSK` and `ZSK`.

If for some reason, you don’t see a file in this directory (`/var/lib/opendnssec/signed/`), then explicitly tell the signer to sign:

    # ods-signer sign mytld

## OpenDNSSEC and key management

Now the zone should be signed with OpenDNSSEC - do notice that the zone was signed, but you didn’t issue any commands to generate keys.

### List the keys currently managed by OpenDNSSEC:

    # ods-enforcer key list

    Keys:
    Zone:                           Keytype:      State:    Date of next transition:
    mytld                           KSK           publish   2018-03-28 09:44:29
    mytld                           ZSK           active    2018-03-28 09:44:29

Note: the ZSK might be in a ‘ready’ state for 10-15 minutes.

Notice that two keys have just been created by OpenDNSSEC, “on the fly”.

Also notice the key state (`publish`, `active`) and the “Date of next transition”.

Note: the time is `UTC`, not the local timezone of your server.

## Make BIND load the zone signed by OpenDNSSEC

BIND is still loading the zone that was signed earlier (either manually or using the inline signer).

We need to modify the zone definition in the `/etc/bind/named.conf.local` file, and point to the zone signed by OpenDNSSEC instead.

Modify `/etc/bind/named.conf.local`, and change the zone definition for `mytld` so it looks like this (REMOVE auto-dnssec, etc…):

    zone "mytld" {
        file "/var/lib/opendnssec/signed/mytld";  // <--- Change path
        type master;
    };

If you have additional statements like:

        key-directory "/etc/bind/keys";
        auto-dnssec maintain;
        inline-signing yes;

… please remove them, as those were only being used when BIND was doing the signing. Now, BIND is back to being a “passive” nameserver that doesn’t sign the zone - it just serves the zone signed by OpenDNSSEC.

## Tell OpenDNSSEC to notify BIND when the signed zone is updated

You can have OpenDNSSEC tell BIND to reload the zone when it has been signed - like this, no need to manually reload.

To do this, modify `/etc/opendnssec/conf.xml`, and find the lines:

    <!--
                    <NotifyCommand>/usr/sbin/rndc reload %zone</NotifyCommand>
    -->

… remove the comments (the lines `< !--` and `-- >`) before and after, so you now only have:

                    <NotifyCommand>/usr/sbin/rndc reload %zone</NotifyCommand>

Save the file, and restart OpenDNSSEC:

    # ods-control stop

Wait a few seconds, then:

    # ods-control start

## Moment of reflection

A few questions:

1. Which KSK is currently being used ?

2. And which DS record is published in the parent zone ?

3. Would the resolvers be able to verify the signatures on the zone signed with OpenDNSSEC ? Why not ? What would you have to do for it to work (there are several possible answers)

If you don’t care about breaking your zone for a little while, then you can proceed with the rest of this lab.

## Make BIND use the new configuration

We still haven’t told BIND about the changes we made to the configuration. To do so:

    # rndc reconfig
    # rndc reload mytld

Check the logs in `/etc/bind/log/general` to make sure that the zone is loading correctly.

Now, validation will probably fail for those trying to look up data in your zone. Wait a few minutes, and try to lookup a record in your zone:

    # dig @10.0.0.252 mytld SOA +dnssec

What do you notice ?

You may well see a “SERVFAIL” error! Try again with the Checking Disabled flag set:

    # dig @10.0.0.252 mytld SOA +dnssec +cd

Do you see an answer now?

Why did you get SERVFAIL when DNSSEC checking was enabled? Think about the questions earlier - we generated new keys, but which DS is in the root?

If your zone is signed, but data fails DNSSEC valiation, it has gone “bogus”. We need to fix this.

## Export the DS from your KSK

Verify the state of the KSK at this stage:

    # ods-enforcer key list

Note the state that the KSK is in.

If it is still in publish state (see https://wiki.opendnssec.org/display/DOCS/Key+States#KeyStates-Publish for reference), then the key is, from OpenDNSSEC’s point of view, not ready to be used, as it hasn’t had time to propagate.

As a result, if you try to export the DS at this point:

    # ods-enforcer key export --zone mytld --ds --keytype KSK --keystate publish

… you will see nothing, precisely because OpenDNSSEC’s policy says the key isn’t ready to be published in the parent zone.

At this point, it would be wise to wait a few minutes until the key is in the `ready` state.

Once it is, you may export the DS to a file, so we can upload it to the root:

    # ods-enforcer key export --zone mytld --ds >/tmp/dsset-mytld.

If you’re impatient, and want to force an export, you can do it in the following way:

    # ods-enforcer key export --zone mytld --ds --keytype KSK --keystate publish --keytype KSK

Either way, make sure the file `/tmp/dsset-mytld.` isn’t empty!

## Upload the DS to the root server

Use `scp` to copy the file to the root server:

    # scp /tmp/dsset-mytld. sysadm@10.0.0.237:

Notify the administrator that you have uploaded the NEW DS, and ask them to it to the root zone. See how long it takes before validation starts working again for your zone.

## What’s with the keystate ?

About the keystate in the previous step…

Is it still in the Publish state, or in the Ready statue ?

Was it a good idea to upload the DS already ?

If you wait long enough, and show the key list:

    # ods-enforcer key list

    Zone:                           Keytype: State:    Date of next transition:
    mytld                           KSK      ready     waiting for ds-seen
    mytld                           ZSK      active    2018-03-28 13:34:29

Once you see “Ready”, you can proceed to the next step - not before!

## Tell OpenDNSSEC that the DS is seen in the parent zone

Once you have seen the DS in the parent zone (reminder: 1. export DS, 2. copy to root and notify administrator, 3. verify with `dig @10.0.0.237 DS mytld`), AND the KSK is in the “ready” state, THEN you can tell OpenDNSSEC about it:

    # ods-enforcer key list -v

    Zone:                           Keytype: State:    Date of next transition: Size: Algorithm: CKA_ID:                          Repository: KeyTag:
    mytld                            KSK      ready     waiting for ds-seen      2048  8          ed239c01cd4358cd1ff717e19e86775f SoftHSM     45409
    mytld                            ZSK      active    2018-03-28 13:34:29      1024  8          06d06ad8415b8df60d2506cd0b19b4ad SoftHSM     24681

Using the `-v` option gives you the key ids, which you will need for the next step.

Note the keyid of the KSK, which is in `ready` state.

Now, do:

    # ods-enforcer key ds-seen --zone mytld --keytag 45409

… where 45409 is the keyid of the KSK in the example above - replace with the keyd of your key!

In our class, you will see:

    1 KSK matches found.
    1 KSKs changed.

… which means that 1 key in the “ready” state was found.

Look at the key list again:

    # ods-enforcer key list

You should see something like this:

    Zone:                           Keytype: State:    Date of next transition:
    mytld                           KSK      active    2018-03-28 13:34:29
    mytld                           ZSK      active    2018-03-28 13:34:29

You can now proceeed and attempt a ZSK rollover!