Let's EncryptでＳＳＬ証明書の新規作成と自動更新（dns-01編）

Let's Encrypt とは

dns-01 とは

• ドメイン所有者を証明するための「チャレンジ・レスポンス」のやりとりをＨＴＴＰ経由（http-01）ではなく、ＤＮＳ経由（dns-01）で行う方法である。
• 以下のような環境では、この方法しか採れないケースもある。
  • ワイルドカード証明書を取得する場合。
  • イントラネット内のサーバーでインターネットに公開してない場合。
  • アプライアンス機器等で、ＨＴＴＰの直接ランディングが不可能である場合。
  • 特定プロトコル（メールサーバー等）ユースでＨＴＴＰでのランディングができない／したくない場合など。
• もちろんデメリットもある。
  • http-01 との比較で手順が複雑化する（ＤＮＳコンテンツサーバーへの更新が標準化されていないため）。
  • RFC2136（Dynamic Updates in the Domain Name System）で更新手順が標準化されてるじゃないか！

  • というあなたは 現実 を見た方がいい。

  • ＤＮＳコンテンツサーバーとの連携が必須でそちらをなんとかしないとどうしようもない。
• とは言え、一度この味を知ってしまうと http-01 手順には戻れなくなること請け合いである:-)。
• どれくらい戻れないかというと、Ｗｅｂサーバーに対しても dns-01 手順を適用したくなってしまうくらい中毒性がある:-)。

目次

検証環境

• 以下のソフトウェアの利用を前提に検証を実施した。いずれも最新のリリースということで確認しているが、ある程度古い環境でも問題無いと思われる。
  • ＯＳ： FreeBSD 11.1-R
  • ＡＣＭＥクライアント： dehydrated 0.4.0
  • ＤＮＳダイナミックアップデートクライアント： BIND 9.11.2（nsupdate コマンド）
  • ＤＮＳコンテンツサーバー： BIND 9.11.2
  • ＳＳＬ証明書利用サーバーの利用詳細についてはここでは言及しない。
• 上記以外の環境では、以下の点に相違が発生する。必要に応じて読み替えたし。
  • インストール方法
  • インストールされるディレクトリ
  • 自動更新のための手続きとその設定
• 逆に以下の点は参考にできる。
  • 設定パラメータとその意味
  • 運用事例

検証作業内容

• 本例では、www.example.jp というサイトに対して証明書を発行するものとする。
• チャレンジ・レスポンスコードをＤＮＳダイナミックアップデートするため、example.jp ゾーンに対するＤＮＳコンテンツサーバーへの更新権限があるものとする。
• ＢＩＮＤの場合「ＤＮＳダイナミックアップデート」を許可する（allow-update）だけでは、許可したアクセス元からの「ゾーン」に対するあらゆるレコードの変更ができてしまうので注意。
• その辺りは update-policy 機能（allow-update 機能とは排他）により、ある程度制限することができる。
• しかし update-policy ではアクセス元制限ができないという罠もあり多少の妥協は致し方ないところ。

想定サーバー・ドメイン

• ＤＮＳコンテンツサーバーは ns.example.jp とする。
  • 実際には複数のＤＮＳコンテンツサーバー（いわゆるセカンダリサーバー）で運用されていると思う。
  • それらサーバーへの反映は ns.example.jp からの notify yes; およびＩＸＦＲ（Incremental Zone Transfer）により、全てのサーバーへ、即時に遅滞なく通達されるものとする。
  • それら運用上の詳細については既に設定されているものとして、ここでは取り扱わない。
• ＳＳＬサーバーは www.example.jp とする。
• 上記サーバー（ＤＮＳコンテンツサーバー・ＳＳＬサーバー）は同一でもかまわないし、別々でもかまわない。

ＤＮＳコンテンツサーバー側

• ＤＮＳサーバーは ports/dns/bind911 をインストールする。

ＳＳＬサーバー側

• ＤＮＳダイナミックアップデートクライアントは ports/dns/bind-tools をインストールする。

• なお既にＢＩＮＤ（ports/dns/bind911）がインストールされている環境では不要。

• 古いＦｒｅｅＢＳＤ標準（９．ｘ等）の nsupdate コマンドはＴＳＩＧは取り扱えないため、やはりインストールする必要がある。

• ＡＣＭＥクライアントは ports/security/dehydrated をインストールしておく。

インストール

• いずれも ports/security/dehydrated、ports/dns/bind911 または ports/dns/bind-utils よりインストールする。
• オプションの選択によって手順が変わる点は無いため、ここでは明示しない。

ＤＮＳコンテンツサーバー側の設定

• Let's EncryptでＳＳＬ証明書の新規取得と自動更新（http-01編）で実施した「ドメイン所有者確認トークンディレクトリの指定」の代わりの作業となる。

• よってディレクトリ作成作業は不要である。
• しかし設定ファイル（named.conf）やゾーンファイル（example.jp.db）の設置場所等に工夫が必要になる。

/usr/local/etc/namedb/named.conf（一部）

include "/usr/local/etc/namedb/ns-www.key";

zone "example.jp" {
    type master;
    file "/usr/local/etc/namedb/dynamic/example.jp.db";
    update-policy {
        grant ns-www. name _acme-challenge.www.example.jp. TXT;
    };
};

• 「ＤＮＳコンテンツサーバー」と「ＳＳＬサーバー」とで、ＴＳＩＧ（Transaction SIGnature）キーを共有する。
• ＴＳＩＧキーファイルはキー名と秘密鍵で構成された、named.conf の書式に準拠したテキストファイルである。
• このＴＳＩＧキーを「/usr/local/etc/namedb/ns-www.key」という名前で保存しておく（所有者は bind:wheel、パーミッションは 0400 で）。
• また、ＴＳＩＧキー名に対して、更新許可設定を与える（update-policy および grant）。
• また変更できるレコード名およびリソースレコードを限定する（name _acme-challenge.www.example.jp. TXT）。
• 残念なことに update-policy ではアクセス元制限ができないので、キーファイル（secret）の取り扱いについては注意すること。
• なお allow-update は update-policy とは排他であるため、両方設定することはできない。

/usr/local/etc/namedb/dynamic/example.jp.db（example.jp ゾーンファイル）

$TTL               300

@                       IN SOA ns.example.jp. domain.example.jp. (
                               2017032201 ; serial
                               7200       ; refresh (2 hours)
                               900        ; retry (15 minutes)
                               2419200    ; expire (4 weeks)
                               86400      ; minimum (1 day)
                               )
                        IN NS ns
ns                      IN A  192.0.2.1

• 本ファイルの設置場所、命名規則はそれぞれのポリシーに従う（本例では ゾーン名.db とした）。
• ＤＮＳダイナミックアップデート対象となるゾーンは /usr/local/etc/namedb/dynamic/ ディレクトリ以下に設置されるものとしている。

/usr/local/etc/namedb/ns-www.key（ＴＳＩＧキーファイル）

key "ns-www." {
    algorithm hmac-sha256;
    secret "PfzeGvXiOqtPOwQJY/iNFrvlD3/eKAHRZ0TbyK5GYII=";
};

上記ファイルは以下の手順にて生成することができる。

tsig-keygen -a hmac-sha256 ns-www. > /usr/local/etc/namedb/ns-www.key
chown bind:wheel /usr/local/etc/namedb/ns-www.key
chmod 0400       /usr/local/etc/namedb/ns-www.key

• もちろん secret の部分は毎回【【ランダム】】に発行される（違うキーで同じシークレットを使ってはいけません）。
• このファイルは named.conf でも、（後で説明する）nsupdate コマンド（-k オプションで）でもそのまま解釈してくれる。
• 本ファイルの設置場所、命名規則については一概に言えることが無く、「ポリシーで」で逃げるには無責任すぎるので、以下に例を出してみる。

本例における具体的設定例

• ＢＩＮＤ側に設置する場合は、/usr/local/etc/namedb/ ディレクトリに設置することとする。
  • /usr/local/etc/namedb/ns-www.key（owner:group=bind:wheel, mode=0400）
• ｄｅｈｙｄｒａｔｅｄ側に設置する場合は、/usr/local/etc/dehydrated/ ディレクトリに設置することとする。
  • /usr/local/etc/dehydrated/ns-www.key（owner:group=root:wheel, mode=0400）
• ファイル名についてだが、「キー名.key」とするのが違和感なくていいと思う。

• 肝心のキー名だが、ＢＩＮＤ９．１１のマニュアル（ＴＳＩＧ）によれば「ホスト名１-ホスト名２.」という例がある。

• 本気かどうかわからないが、「ＤＮＳコンテンツサーバー-ダイナミックアップデートするサーバー.」というニュアンスになる。
• 本件の場合、ns.example.jp と www.example.jp であることから「ns-www.」とするのが妥当（ほんと？）。
• まぁなんでもいいけど、わかりやすいようにね。

ＳＳＬサーバー側の設定

• ほとんどLet's EncryptでＳＳＬ証明書の新規取得と自動更新（http-01編）で実施した作業と同じになる。

• 明確に違う点は、先のページでは解説してない「HOOK」設定となる。
• ここでは一通り作業の意味がわかってる前提で、一通り設定を紹介する。

/etc/periodic.conf

weekly_dehydrated_enable="YES"

自動更新設定（YES＝自動更新する）。 periodic(8)にある通り、毎週土曜日３時に実行される。

なお今回、weekly_dehydrated_deployscript は指定しない（後述の HOOK 設定参照のこと）。

/usr/local/etc/dehydrated/ns-www.key（ＴＳＩＧキーファイル）

これは先に tsig-keygen コマンドで作成されたファイルである。 ＤＮＳコンテンツサーバーと同一になるようコピーするなどして設定すること。 その際のオーナー・グループ・パーミッションは以下の通りである。

chown root:wheel /usr/local/etc/dehydrated/ns-www.key
chmod 0400       /usr/local/etc/dehydrated/ns-www.key

/usr/local/etc/dehydrated/config

alias openssl="/usr/bin/openssl"

CHALLENGETYPE="dns-01"
HOOK="${BASEDIR}/hook.sh"
RENEW_DAYS="30"
KEY_ALGO="rsa" KEYSIZE="2048"
#KEY_ALGO="prime256v1"
CONTACT_EMAIL="メールアドレス"
#テスト発行したい場合、以下の２行を有効にすること。
#CA="https://acme-staging.api.letsencrypt.org/directory"
#CA_TERMS="https://acme-staging.api.letsencrypt.org/terms"

• http-01 との時との大きな違いは CHALLENGETYPE と HOOK 設定にある。
• HOOK 設定（によって指定されるファイル）については後述する。
• CHALLENGETYPE には dns-01 を指定する。
• CHALLENGETYPE は現在 http-01 か dns-01 の２つしか選択肢は無い。

/usr/local/etc/dehydrated/domains.txt

www.example.jp

本ファイルの設定については コモンネームの設定に準拠するものとする（例）。

ワイルドカード証明書

v0.6.0 以降でワイルドカード証明書を取得したい場合の domains.txt の書き方は下記の通りです。

*.example.jp > star_example_jp

• 味噌は「 > 」で上記例では star_example_jp というエイリアス設定（サブディレクトリ名として使用）してやる必要があります。

• エイリアス設定しない場合、エイリアス設定でも「*.」で始まる場合、エラーとなります（途中に * が入ってても問題無い！？）。
• まぁシェルスクリプトで、パス名に * が含まれる場合の取り扱いは面倒なので、このような仕組みになってるのだと思います。
• このエイリアスの指定は今までの指定方法でも使用できますが、わざわざ設定する必要はないでしょう。

• 複数の「>」の指定はエラーです（エイリアスは一行に一個だけ）。

• なお二行以上の設定（違うコモンネーム）に対して同一エイリアスを設定した場合の振る舞いについては未調査です:-)。

またベストプラクティクス的にははＳＡＮｓによる設定がスマートかと思われます（example.jp をコモンネームとする）。

example.jp *.example.jp

/usr/local/etc/dehydrated/hook.sh

TTL="300"
DNSSERVER="ns.example.jp"
alias nsupdate="/usr/local/bin/nsupdate -k ${BASEDIR}/ns-www.key"

deploy_challenge {
    local DOMAIN="${1}" TOKEN_FILENAME="${2}" TOKEN_VALUE="${3}"
    printf 'server %s\nupdate add _acme-challenge.%s. %d TXT "%s"\nsend\n' "${DNSSERVER}" "${DOMAIN}" "${TTL}" "${TOKEN_VALUE}" | nsupdate
}

clean_challenge {
    local DOMAIN="${1}" TOKEN_FILENAME="${2}" TOKEN_VALUE="${3}"
    printf 'server %s\nupdate delete _acme-challenge.%s. TXT\nsend\n' "${DNSSERVER}" "${DOMAIN}" | nsupdate
}

deploy_cert {
    /usr/sbin/service apache24 restart && /usr/local/bin/dehydrated -gc
}

HANDLER="$1"; shift
if [[ "${HANDLER}" =~ ^(deploy_challenge|clean_challenge|deploy_cert)$ ]]; then
  "$HANDLER" "$@"
fi

• フック（HOOK）ファイルのひな形としては /usr/local/etc/dehydrated/hook.sh.example を参照すること。
• またほとんどのフックは「何もしない」ので、バージョンアップによる拡張の影響を考慮して、使用しているフック以外は無視するようプログラムしましょう。

/usr/local/etc/dehydrated/deploy.sh

• 本ケースでは deploy.sh を取り扱わない（無くてもいい）。
• これは HOOK で指定するシェルスクリプトの deploy_cert シェル関数で代替するからである。
• HOOK（/usr/local/etc/dehydrated/config）と weekly_dehydrated_deployscript（/etc/periodic.conf）の違いは以下の通りである。
  • 証明書取得する単位毎に実行されるのが HOOK、全て取得終って実行されるのが weekly_dehydrated_deployscript。
  • 証明書取得に成功した・失敗した（または更新なし）がわかるのが HOOK、わからないのが weekly_dehydrated_deployscript。
• よって、１枚の証明書を相手にする時はそう違いは無いが、複数枚を取得して分散デプロイしたいなら HOOK しかない。
• ファインチューニング（更新ない時は何もしないなど）したいなら HOOK 一択。
• 逆に HOOK はデプロイだけしたいユースケースにおいて若干ながら大味（ダミーの関数を置く必要がある）である。
• この HOOK はバージョンによって拡張されるので、未知の呼び出しに対してはエラーにならないよう、ケアする必要がある。

【付録】ゾーン分割によるダイナミックアップデートの制限

• 以下のケースのどれか（and/or）が該当するなら、一工夫必要になる。
  • ＤＮＳコンテンツサーバーへの更新権限が無い／得られない場合。
  • 本例レベルの「ゾーン」に対して更新を許可するには広すぎる（セキュリティ的・ポリシー的）ので狭くしたい場合。
• なお実現のためには「委任」が必須なので、そこは調整すること。
• 今回、_acme-challenge.www.example.jp ゾーン（に分けて／委任してもらって）に、更新が新しいゾーン内に閉じるよう制限してみた。
• ここでは敢えて「example.jp」ゾーンから「_acme-challenge.www.example.jp」を自分自身（ＤＮＳコンテンツサーバー）へ委任するものとし、外部のＤＮＳコンテンツサーバーへは向けないものとする。
• ここまでお膳立てが整えられていれば例えば、サービスゾーンのＤＮＳコンテンツサーバーへの更新権限は得られなくても、自前のＤＮＳコンテンツサーバーに委任してもらって、更新できるようにするのは難しくないと思う。

/usr/local/etc/namedb/named.conf（一部）

include "/usr/local/etc/namedb/ns-www.key";

zone "example.jp" {
    type master;
    file "/usr/local/etc/namedb/master/example.jp.db";
};

zone "_acme-challenge.www.example.jp" {
    type master;
    file "/usr/local/etc/namedb/dynamic/_acme-challenge.www.example.jp.db";
    update-policy {
        grant ns-www. name _acme-challenge.www.example.jp. TXT;
    };
};

/usr/local/etc/namedb/master/example.jp.db（example.jp ゾーンファイル）

$TTL               300

@                       IN SOA ns.example.jp. domain.example.jp. (
                               2017032201 ; serial
                               7200       ; refresh (2 hours)
                               900        ; retry (15 minutes)
                               2419200    ; expire (4 weeks)
                               86400      ; minimum (1 day)
                               )
                        IN NS ns
_acme-challenge.www     IN NS ns
ns                      IN A  192.0.2.1

/usr/local/etc/namedb/dynamic/_acme-challenge.www.example.jp.db（_acme-challenge.www.example.jp ゾーンファイル）

$TTL               300

@                       IN SOA ns.example.jp. domain.example.jp. (
                               2017032201 ; serial
                               7200       ; refresh (2 hours)
                               900        ; retry (15 minutes)
                               2419200    ; expire (4 weeks)
                               86400      ; minimum (1 day)
                               )
                        IN NS ns.example.jp.

/usr/local/etc/dehydrated/hook.sh

  :
DNSSERVER="ns.example.jp"
  :

場合によっては DNSSERVER 設定を変更する（今回の前提では必要ない）。

相違点

• 以下の３ファイルに対する変更以外に相違点は無い。
• 委任先のＤＮＳサーバーが元と違う場合は nsupdate コマンドで指定するサーバーを変更する必要がある。

/usr/local/etc/namedb/named.conf

• example.jp ゾーンでのＤＮＳダイナミックアップデートの許可をしない。
• よって設置先ディレクトリも変わる。
• _acme-challenge.www.example.jp ゾーンを定義し、そちらでＤＮＳダイナミックアップデートの設定を行う。

/usr/local/etc/namedb/master/example.jp.db

• _acme-challenge.www レコードにて委任の設定を追加する。
• もちろんＤＮＳサーバーが複数ある場合は複数記入すること。

/usr/local/etc/namedb/dynamic/_acme-challenge.www.example.jp.db

• 新規作成する。
• 中身はほぼ空になるが、ＳＯＡとＮＳレコードの設定は必須である。
• 設置先ディレクトリには注意すること（/usr/local/etc/namedb/dynamic ディレクトリ以下に設置）。

参考文献

• BIND 9 Administrator Reference Manual

• Chapter 4. Advanced DNS Features - Dynamic Update

• Chapter 4. Advanced DNS Features - TSIG

• Chapter 6. BIND 9 Configuration Reference - Dynamic Update Policies

• Chapter 7. BIND 9 Security Considerations

参考文献について一言

• ＢＩＮＤに関する情報を検索しても、オリジナルドキュメントが上位に来ないのは問題だと思う。
• 検索して出てきたサイトの情報を精査してみると、微妙な問題が散見しており、オリジナル文書読むと間違いであることに気がつく。
• 特にダイナミックアップデートについては tsig-keygen コマンドがあるのに dnssec-keygen コマンドで説明しているサイトがあるなど、涙無しには調査できない。

mv /usr/local/etc/letsencrypt.sh/config.sh /usr/local/etc/dehydrated/config

mv /usr/local/etc/letsencrypt.sh/deploy.sh /usr/local/etc/dehydrated/

mv /usr/local/etc/letsencrypt.sh/domains.txt /usr/local/etc/dehydrated/

mv /usr/local/etc/letsencrypt.sh/hook.sh /usr/local/etc/dehydrated/

mv /usr/local/etc/letsencrypt.sh/certs /usr/local/etc/dehydrated/

mv /usr/local/etc/letsencrypt.sh/archive /usr/local/etc/dehydrated/

rmdir /usr/local/etc/letsencrypt.sh

  SSLCertificateFile    /usr/local/etc/letsencrypt.sh/certs/コモンネーム/fullchain.pem
  SSLCertificateKeyFile /usr/local/etc/letsencrypt.sh/certs/コモンネーム/privkey.pem

Alias /.well-known/acme-challenge/ /usr/local/etc/letsencrypt.sh/.acme-challenges/

<Directory /usr/local/etc/letsencrypt.sh/.acme-challenges>
  Options       None
  AllowOverride None
  Require       all granted
  Header        add Content-Type text/plain
</Directory>

weekly_letsencrypt_enable="YES"
weekly_letsencrypt_deployscript="/usr/local/etc/letsencrypt.sh/deploy.sh"

weekly_dehydrated_enable="YES"
weekly_dehydrated_deployscript="/usr/local/etc/dehydrated/deploy.sh"