Let's EncryptでＳＳＬ証明書の新規作成と自動更新（http-01編）
Lets' EncryptによるＳＳＬ証明書の自動取得・自動更新に関するメモを残す。
- Let's Encrypt とその周辺ツールはどんどん変わっていて、今後の改善によっては本記述が間に合わないことがある。
- 実際、certbot、dehydrated だけでなく、様々な環境・言語等で、たくさんのクライアントが誕生している。
- Let's Encrypt 公式ツールであるところの certbot については特に記載しない。使わなくなってしばらく経過していることと、どんどん変わっていて、誤解を生む可能性があるからである。。
- 本記述に関して何か差違があると感じた場合は、本家のドキュメントを確認して欲しい。
- また運用環境が極端に違うことから、ＦｒｅｅＢＳＤ環境での解説のみとし、ＣｅｎｔＯＳ環境での解説は行わない。
- 将来もう少し、環境差違が無くなってからＣｅｎｔＯＳ環境での解説を行うつもりである。
対象環境
- 対象ＯＳはＦｒｅｅＢＳＤとする。
- その他のＯＳでは以下の点に相違がある。
- インストール方法
- インストールされるディレクトリ
- 自動更新のための手続きとその設定
- 逆に以下の点は参考にできる。
- 設定パラメータとその意味
- 運用事例
certbot と dehydrated
certbot と dehydrated の違いについては特に解説しない。
- Let's Encrypt からのＳＳＬ証明書発行するためのツールとして「dehydrated」を採用する。
- これは以下の点を考慮して dehydrated の方がマシだと考えたからである。
- dehydrated は bash/zsh 依存スクリプトであるため、特別な言語環境（Python）を必要としない。
- certbot の場合、Python に依存するくらいならまだ良いが、依存する Python モジュールが大量にある。
dehydrated はまだ依存が少ない（cURL のせいで増えてるが）。
- dehydrated の場合、わけわかんなくなっても、シェルなのでソースコード読んで理解できる。また長いコードではない。
- dehydrated はＷｅｂサーバーを内蔵していないため、Ｗｅｂサーバー（Apache 等）との組み合わせに考慮しなくてよい。
目次
インストール
- ports ないしは packages から、以下の ports をインストールする。
この時 ports/security/py-certbot のインストールは不要である。あって動かなくなることは無いが、あっても使われない。
- また、定期実行が設定ファイルに１行記述するだけで制御できるレベルで簡単である。
- ただ、この事情は ports メンテナの功績によるものなので:-)、他の（ＯＳ）環境でそうであるかは不明である。
準備
- いくつかのディレクトリの作成および設置ルールを決める。
証明書の設置場所
- ports/security/dehydrated では /usr/local/etc/dehydrated/certs/コモンネーム/ 以下のファイルが設置される。
- /usr/local/etc/dehydrated/certs/コモンネーム/cert-ＵＮＩＸタイムスタンプ.csr
- /usr/local/etc/dehydrated/certs/コモンネーム/cert-ＵＮＩＸタイムスタンプ.pem
- /usr/local/etc/dehydrated/certs/コモンネーム/chain-ＵＮＩＸタイムスタンプ.pem
- /usr/local/etc/dehydrated/certs/コモンネーム/fullchain-ＵＮＩＸタイムスタンプ.pem
- /usr/local/etc/dehydrated/certs/コモンネーム/privkey-ＵＮＩＸタイムスタンプ.pem
- 設置場所についてはプログラム中に直接記載されているため、変更は不可能である。
- その代わり、シンボリックリンクで誘導することは可能。
- また、最新（現在）の証明書に対してシンボリックリンクが張られる。
# cd /usr/local/etc/dehydrated/certs/コモンネーム # ls -alF total 122 -rw------- 1 root wheel 436 May 29 06:02 cert-1464469337.csr -rw------- 1 root wheel 1533 May 29 06:02 cert-1464469337.pem lrwx------ 1 root wheel 19 May 29 06:02 cert.csr@ -> cert-1464469337.csr lrwx------ 1 root wheel 19 May 29 06:02 cert.pem@ -> cert-1464469337.pem -rw------- 1 root wheel 1647 May 29 06:02 chain-1464469337.pem lrwx------ 1 root wheel 20 May 29 06:02 chain.pem@ -> chain-1464469337.pem -rw------- 1 root wheel 3180 May 29 06:02 fullchain-1464469337.pem lrwx------ 1 root wheel 24 May 29 06:02 fullchain.pem@ -> fullchain-1464469337.pem -rw------- 1 root wheel 302 May 29 06:02 privkey-1464469337.pem lrwx------ 1 root wheel 22 May 29 06:02 privkey.pem@ -> privkey-1464469337.pem
- 例えば Apache（2.4.8以上）では以下のように指定することになる。
SSLCertificateFile /usr/local/etc/dehydrated/certs/コモンネーム/fullchain.pem SSLCertificateKeyFile /usr/local/etc/dehydrated/certs/コモンネーム/privkey.pem
- 古い Apache（2.4.8未満）だと以下のパターンで指定する。
SSLCertificateFile /usr/local/etc/dehydrated/certs/コモンネーム/cert.pem SSLCertificateChainFile /usr/local/etc/dehydrated/certs/コモンネーム/chain.pem SSLCertificateKeyFile /usr/local/etc/dehydrated/certs/コモンネーム/privkey.pem
- cert.pem（署名済みＳＳＬ証明書公開鍵）＋chain.pem（中間証明書）＝fullchain.pem（両者を足したモノ） の使い分けは利用するサーバープログラムの仕様に従うこと。
- なお、Let's Encrypt の中間証明書（chain.pem）を世間一般のブラウザが持っていることは「現在」期待しない方がよい。限定的には持っているブラウザもあるが、広く世間で使おうと思ったら、持っていない前提で運用すべき。
ドメイン所有者確認トークンディレクトリの指定
- ドメイン所有者確認トークンの設置場所（ディレクトリ）を決める。
- 「ドメイン所有者確認トークン」はドメインの所有者であること確認するための「トークン」（一時発行キー）である。
- これはＷｅｂサーバー側の設定とも連動する話なので、その前提で決定する。
- 以下はアクセスログ（例）である。
66.133.109.36 - - [29/May/2016:06:02:21 +0900] "GET /.well-known/acme-challenge/チャレンジトークン HTTP/1.1" 200 87 "-" "Mozilla/5.0 (compatible; Let's Encrypt validation server; +https://www.letsencrypt.org)"
- デフォルトで /usr/local/etc/dehydrated/.acme-challenges となっている。
- またこの設定は「WELLKNOWN」変数で変更可能である。
- このディレクトリはインストール時に設定されるので、例えば Apache（2.4）の場合、以下のように設定する。
Alias /.well-known/acme-challenge/ /usr/local/etc/dehydrated/.acme-challenges/ <Directory /usr/local/etc/dehydrated/.acme-challenges> Options None AllowOverride None Require all granted Header add Content-Type text/plain </Directory>
アカウントキーの保存ディレクトリの指定
- アカウントキーと呼ばれるＪＳＯＮとＲＳＡ秘密鍵の保存ディレクトリを指定する。
- デフォルトで /usr/local/etc/dehydrated/private_key.{json,pem} となる。
- これら設定は「ACCOUNT_KEY_JSON」（.json）と「ACCOUNT_KEY」（.pem）設定で指定が可能である。
設定ファイル
- 上記準備と合わせて、設定ファイルに記載する。いわゆるシェルスクリプトなので、その記法はそれに準じる。
- 設定ファイルは /usr/local/etc/dehydrated/config である（シェル文法で記述）。
- ports の場合、config.example が同じディレクトリにインストールされるので、合わせて参照して欲しいところ。
- 色々と設定する項目はあるが、下記の設定のみ使用する。
- WELLKNOWN
- ACCOUNT_KEY
- ACCOUNT_KEY_JSON
- RENEW_DAYS
- PRIVATE_KEY_RENEW
- KEY_ALGO / KEYSIZE
- CONTACT_EMAIL
- WELLKNOWN, ACCOUNT_KEY, ACCOUNT_KEY_JSONについてはすでに解説済みなので、残りについて説明する。
- RENEW_DAYS
- 有効期限残日数を指定する。今日を基準に有効期限が指定日数（秒換算）未満になったら更新を行う。
- なお FreeBSD では、更新そのものは毎週行われる（periodic の weekly 指定、つまり７日単位に丸められる）。
- PRIVATE_KEY_RENEW
- 更新する毎に秘密鍵を作り直すか否かを指定する。
- デフォルトで「yes」である（毎回作り直す）。
- 指定可能な値は「yes」か「それ以外」かしか無いので、「Yes」と書いてもNoと解釈される。
- また「作り直さない」選択にメリットも無ければ推奨でもないので、ごく極めて例外的な何かが無ければ「yes」を選択すること。
- KEY_ALGO / KEYSIZE
- ＳＳＬ証明書の鍵アルゴリズム（KEY_ALGO）と鍵サイズ（KEYSIZE）を指定する。
- KEY_ALGO での選択可能な識別子は「rsa」「prime256v1」「secp384r1」。
- KEY_ALGO が「rsa」の時に限って KEYSIZE を指定する（2048, 3072, 4096）。
- CONTACT_EMAIL
- Let's Encrypt では連絡用メールアドレスの指定が必要となるので、メールアドレスを指定する。
設定ファイル例
コモンネームファイル
- 発行するＳＳＬ証明書のコモンネームを列挙したファイルを作成する。
- このファイル名は /usr/local/etc/dehydrated/domains.txt で指定される。
- １行１証明書で、１カラム目はコモンネームとなり、２カラム目以降は SANs（Subject Alternative Names）を指定する。
- 以下のサンプルでは example.org, example.com の２枚の証明書を作成／更新する。
example.org www.example.org example.com www.example.com wiki.example.com
- また、「example.org」のSANとして「www.example.org」が、「example.com」のSANとして「www.example.com」と「wiki.example.com」が合わせて設定される。
- 他にも、以下のルールで処理される。
- 大文字は小文字に変換される。
- 複数の空白類（スペース、タブなど）で区切り、１個の空白として処理される。
- 行頭が # や空行は無視。
初回実行ないしは手動更新の仕方
- 以上の設定が完了したら、コマンドを root で実行する。
-c オプションは --cron と同じ意味である（だからどうした！:-）。
dehydrated --register --accept-terms dehydrated -c
- とりあえずプログラムを読んだ限りでは環境変数汚染依存はなさそう。
- 正直、LANG、LC_* くらいはケアして欲しいところだけど。
自動更新
ports/security/dehydrated では定期実行に periodic(8) を採用している。
- よって定期実行は /etc/periodic.conf ないしは /etc/periodic.conf.local ファイルにて設定を行う。
weekly_dehydrated_enable="YES" weekly_dehydrated_deployscript="/usr/local/etc/dehydrated/deploy.sh"
単純に更新するだけなら、weekly_dehydrated_enable="YES" と設定するだけで良い。
- 全ての更新が完了した後、サーバーへの反映を行うスクリプトを weekly_dehydrated_deployscript で指定できる。
- 指定されたファイルは、実行権限（chmod +x）も必要。
- ただし、証明書の更新が無くても実行されるので、厳密には証明書が更新されたか確認した方がいい。
- とは言え、現地時間で毎週土曜日０４時０５分（/etc/crontab の periodic weekly 行参照のこと）に実行されるので、そのあたりはテキトーでもいいかもしれない。
dehydrated -gc は古い証明書の削除（クリーンナップ）を行う。
- わざと残しておくのであれば実行は不要である。
/usr/local/etc/dehydrated/deploy.sh 例
#/bin/sh /usr/sbin/service apache24 restart && /usr/local/bin/dehydrated -gc
よくある質問とその答え
Q. ＥＣＤＳＡ対応は必須？
A. 提供必須というほど、対応しているブラウザは普及してないですね。ごく最新の有名どころブラウザはともかく、四方山ブラウザを考慮するとまだまだ。 サーバー側でＲＳＡとＥＣＤＳＡの両方を提案してブラウザが受け入れられる方を…という解決策も無くもないですが（使えるか知らないし興味ない）、結局ＲＳＡの鍵も作らないと行けないことには変わりないので、当面、ＲＳＡ２０４８で行くのが正解かと。
Q. ports/security/dehydrated と ports/security/py-certbot とどっちがいいですか？
A. 目標が違うのでどっちとも言えない。 certbot は Let' Encrypt 推奨ＡＣＭＥクライアントで、 証明書の失効（revoke）までできるので、 フルスペックの機能使うなら…というところでしょうね。
ＡＣＭＥクライアントは、certbot、dehydrated だけでなく、他にもあるので、チェックしてみるといいかもしれない。
あと、certbot はＷｅｂサーバー内蔵で http（TCP ポート 80）開いてるかぎり使える点がうれしいかも。 ただ、既にＷｅｂサーバーが稼働済みの場合、certbot よりも、Ｗｅｂサーバーを内蔵してない dehydrated の方が都合がよい。
Q. 下記のように所有者確認アクセスに失敗、証明書が更新されません！
66.133.109.36 - - [29/May/2016:04:45:29 +0900] "GET /.well-known/acme-challenge/チャレンジトークン HTTP/1.1" 404 268 "-" "Mozilla/5.0 (compatible; Let's Encrypt validation server; +https://www.letsencrypt.org)"
A. Ｗｅｂサーバーの設定ミスの可能性があります！ 自分は Alias /.well-known/acme-challenge/ /usr/local/etc/dehydrated/.acme-challengesと最後に「/」を入れ忘れていました！ このケースでは Alias の第一、第二引数ともに最後に「/」を含める必要がある。
他にも良くありそうなのが、設定した後にサーバー再起動（ないしは再読み込み）を忘れていたなどが考えられる。
あとリカバリとして、更新に失敗して残ってるＣＳＲや秘密鍵を削除するのに dehydrated -gc を実施すること。
Q. Ｗｅｂサービス立ち上げてないサーバーでＳＳＬ証明書使いたいです！
A. そんなあなたにＤＮＳ認証（dns-01）。続きはＷｅｂで。
【付録】 dehydrated v0.40 での変更
v0.40 で、ライセンス受諾の確認が必須になりました。 それまでは暗黙の受諾として、dehydrated が勝手に受諾していましたが、 別途手動で、dehydrated --register --accept-terms を実行する必要があります。
ステージング用のライセンス受諾ともまた別の話となりますので、 CA だけでなく、CA_TERMS も合わせて設定する必要があります。
この振る舞いは /usr/local/etc/dehydrated/accounts/ハッシュキー/account_key.pem の有り無しがトリガーとなりますので、 既にこのファイルがある環境では影響有りません。
初回実行に手動で実行していれば気がつくレベルとなります（エラーメッセージ等「読まない」人についてはノーコメント）。
【付録】 letsencrypt.sh から dehydrated への移行
商標上の理由で、letsencrypt.sh から dehydrated へ名前変更が実施された。 合わせてディレクトリから設定まで色々変更になったので対応についてメモっておく。
ディレクトリ名の変更
/usr/local/etc/letsencrypt.sh から /usr/local/etc/dehydrated へ変更になったわけであるが、更新後は新しいディレクトリが作成されていることもあり、こまめに手を入れる必要がある。
/usr/local/etc/letsencrypt.sh/config.sh
mv /usr/local/etc/letsencrypt.sh/config.sh /usr/local/etc/dehydrated/config
※config.sh から config に変更になったので合わせて変更を実施する。
/usr/local/etc/letsencrypt.sh/deploy.sh
mv /usr/local/etc/letsencrypt.sh/deploy.sh /usr/local/etc/dehydrated/
/usr/local/etc/letsencrypt.sh/domains.txt
mv /usr/local/etc/letsencrypt.sh/domains.txt /usr/local/etc/dehydrated/
/usr/local/etc/letsencrypt.sh/hook.sh
mv /usr/local/etc/letsencrypt.sh/hook.sh /usr/local/etc/dehydrated/
/usr/local/etc/letsencrypt.sh/certs/
mv /usr/local/etc/letsencrypt.sh/certs /usr/local/etc/dehydrated/
- certs ディレクトリはインストール時には作成されない。
- ＳＳＬ証明書取得時にコモンネームと合わせて作成される。
- 既に /usr/local/etc/dehydrated/certs ディレクトリが作成されている場合は、子ディレクトリ（コモンネーム）を個別にリネーム（移動）すること。
/usr/local/etc/letsencrypt.sh/archive/
mv /usr/local/etc/letsencrypt.sh/archive /usr/local/etc/dehydrated/
- archive ディレクトリはインストール時には作成されない。
- ＳＳＬ証明書クリーンナップ（-gc オプション指定）時にコモンネームと合わせて作成される。
- 既に /usr/local/etc/dehydrated/archive ディレクトリが作成されている場合は、子ディレクトリ（コモンネーム）を個別にリネーム（移動）すること。
後始末
rmdir /usr/local/etc/letsencrypt.sh
※全ての移動が完了すれば、ディレクトリもファイルも残ってないはずなので削除する。
設定ファイルの変更
リネームによる影響で変更になるファイルは以下の３ファイルである。 ディレクトリ名およびコマンド名に letsencrypt.sh というキーワードが無いか確認し、dehydrated に置き換えること。
- /usr/local/etc/dehydrated/config
- /usr/local/etc/dehydrated/deploy.sh
- /usr/local/etc/dehydrated/hook.sh
ＳＳＬ証明書利用アプリケーションの設定変更
本例では Apache（2.4）を例に説明した。 当該箇所のディレクトリ名変更を新しいディレクトリ名に変更する。
ＳＳＬ証明書の旧指定例
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>
起動設定（periodic）の変更
/etc/periodic.conf あるいは /etc/periodic.conf.local のどちらかの設定で定期更新を実施しているわけだが、変数名が変更になっている。
本例では以下のような設定を実施しているが、
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"
単純に letsencrypt や letsencrypt.sh を dehydrated に置き換えるだけである。
参考文献
Rate Limits（ＳＳＬ証明書取得数制限）
Staging Environment（ステージング環境）
ACME Client Implementations（ＡＣＭＥクライアント実装）