ドキュメント
プロジェクト

tls

サイトのTLSを設定します。

CaddyのデフォルトのTLS設定は安全です。十分な理由があり、影響を理解している場合にのみ、これらの設定を変更してください。このディレクティブの最も一般的な用途は、ACMEアカウントのメールアドレスの指定、ACME CAエンドポイントの変更、または独自の証明書の提供です。

互換性に関する注意：セキュリティプロトコルとしての性質上、TLSのデフォルトへの意図的な調整は、新しいマイナーまたはパッチリリースで行われる場合があります。古いまたは破損したTLSバージョン、暗号、機能などはいつでも削除される可能性があります。デプロイが変更に非常に敏感である場合は、常に一定に保つ必要のある値を明示的に指定し、アップグレードに注意する必要があります。ほとんどすべての場合、デフォルト設定を使用することをお勧めします。

構文

tls [internal|<email>] | [<cert_file> <key_file>] {
	protocols <min> [<max>]
	ciphers   <cipher_suites...>
	curves    <curves...>
	alpn      <values...>
	load      <paths...>
	ca        <ca_dir_url>
	ca_root   <pem_file>
	key_type  ed25519|p256|p384|rsa2048|rsa4096
	dns       <provider_name> [<params...>]
	propagation_timeout <duration>
	propagation_delay   <duration>
	dns_ttl             <duration>
	dns_challenge_override_domain <domain>
	resolvers <dns_servers...>
	eab       <key_id> <mac_key>
	on_demand
	client_auth {
		mode                   [request|require|verify_if_given|require_and_verify]
		trusted_ca_cert        <base64_der>
		trusted_ca_cert_file   <filename>
		trusted_leaf_cert      <base64_der>
		trusted_leaf_cert_file <filename>
	}
	issuer          <issuer_name>  [<params...>]
	get_certificate <manager_name> [<params...>]
	insecure_secrets_log <log_file>
}

  • internal は、Caddyの内部でローカルに信頼されたCAを使用して、このサイトの証明書を生成することを意味します。 internal 発行者をさらに構成するには、 issuer サブディレクティブを使用します。

  • <email> は、サイトの証明書を管理するACMEアカウントに使用するメールアドレスです。代わりに、 email グローバルオプションを使用して、すべてのサイトに対してこれを一度に構成することをお勧めします。

  • <cert_file> と <key_file> は、証明書と秘密鍵のPEMファイルへのパスです。片方だけを指定するのは無効です。

  • protocols 最小および最大プロトコルバージョンを指定します。何をしているかを理解していない限り、これらを変更しないでください。Caddyは常に最新のデフォルトを使用するため、これを構成する必要はほとんどありません。

    デフォルトの最小値：tls1.2、デフォルトの最大値：tls1.3

  • ciphers 優先順位の高い順に暗号スイート名のリストを指定します。何をしているかを理解していない限り、これらを変更しないでください。TLS 1.3では暗号スイートをカスタマイズできず、TLS 1.2暗号の一部はデフォルトで有効になっていないことに注意してください。サポートされている名前は（Go stdlibによる優先順位順）：

    • TLS_AES_128_GCM_SHA256
    • TLS_CHACHA20_POLY1305_SHA256
    • TLS_AES_256_GCM_SHA384
    • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
    • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
    • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
    • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
    • TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
    • TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
    • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
    • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
    • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
    • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
    • TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA

  • curves サポートするEC曲線の一覧を指定します。これらを変更しないことをお勧めします。サポートされている値は次のとおりです。

    • x25519
    • secp256r1
    • secp384r1
    • secp521r1

  • alpn TLSハンドシェイクのALPN拡張機能でアドバタイズする値のリストです。

  • load 証明書と鍵のバンドルであるPEMファイルをロードするフォルダのリストを指定します。

  • ca ACME CAエンドポイントを変更します。これは、テスト時にLet's Encryptのステージングエンドポイントまたは内部ACMEサーバーを設定するためによく使用されます。（Caddyfile全体でこの値を変更するには、代わりに acme_ca グローバルオプションを使用してください。）

  • ca_root システム信頼ストアにない場合、ACME CAエンドポイントの信頼できるルート証明書を含むPEMファイルを指定します。

  • key_type CSRの生成時に使用する鍵のタイプです。特定の要件がある場合にのみ、これを設定してください。

  • dns 指定されたプロバイダープラグインを使用してDNSチャレンジを有効にします。これは、caddy-dns リポジトリのいずれかからプラグインされている必要があります。各プロバイダープラグインには、名前の後に独自の構文がある場合があります。詳細については、ドキュメントを参照してください。各DNSプロバイダーのサポートを維持することはコミュニティの努力です。WikiでプロバイダーのDNSチャレンジを有効にする方法を学びましょう。

  • propagation_timeout 期間値であり、DNSチャレンジを使用するときにDNS TXTレコードが表示されるのを待つ最大時間を設定します。伝播チェックを無効にするには、-1に設定します。デフォルトは2分です。

  • propagation_delay 期間値であり、DNSチャレンジを使用するときにDNS TXTレコードの伝播チェックを開始する前に待機する時間を設定します。デフォルトは0（待機なし）です。

  • dns_ttl 期間値であり、DNSチャレンジに使用されるTXTレコードのTTLを設定します。ほとんど必要ありません。

  • dns_challenge_override_domain DNSチャレンジに使用するドメインをオーバーライドします。これは、チャレンジを別のドメインに委任するためのものです。

    プライマリドメインのDNSプロバイダーに、利用可能なDNSプラグイン がない場合にこれを使用する必要がある場合があります。代わりに、_acme-challengeサブドメインを使用して、プラグインがあるセカンダリドメインを指すCNAMEレコードを追加できます。このオプションは、プラグインからの特別なサポートを必要としません。

    ACME発行者がプライマリドメインのDNSチャレンジを解決しようとすると、CNAMEに従ってセカンダリドメインを探し、TXTレコードを見つけます。

    注：ここで値としてCNAMEレコードからの完全な正規名を使用してください - _acme-challenge サブドメインは自動的に先頭に追加されません。

  • resolvers DNSチャレンジを実行するときに使用されるDNSリゾルバーをカスタマイズします。これらは、システムリゾルバーまたはデフォルトのリゾルバーよりも優先されます。ここで設定すると、リゾルバーは構成されたすべての証明書発行者に伝播されます。

    これは通常、IPアドレスのリストです。たとえば、Google Public DNS を使用するには、

    resolvers 8.8.8.8 8.8.4.4

  • eab CAから提供されたキーIDとMACキーを使用して、このサイトのACME外部アカウントバインディング（EAB）を構成します。

  • on_demand サイトブロックのアドレスに指定されたホスト名のオンデマンドTLSを有効にします。セキュリティ警告：本番環境でこれを行う場合は、乱用を軽減するためにon_demand_tls グローバルオプションも構成しない限り、安全ではありません。

  • client_auth TLSクライアント認証を有効にして構成します。

    • mode クライアントを認証するためのモードです。許可される値は次のとおりです。

      モード 説明
      request クライアントに証明書を要求しますが、証明書がなくても許可します。検証はしません
      require クライアントに証明書の提示を要求しますが、検証はしません
      verify_if_given クライアントに証明書を要求します。なくても許可しますが、あれば検証します
      require_and_verify 検証済みの有効な証明書をクライアントに提示することを要求します

      デフォルト：trusted_ca_certまたはtrusted_leaf_certが提供されている場合はrequire_and_verify。それ以外の場合はrequire。

    • trusted_ca_cert クライアント証明書を検証するためのbase64 DERエンコードされたCA証明書です。

    • trusted_ca_cert_file クライアント証明書を検証するためのPEM CA証明書ファイルへのパスです。

    • trusted_leaf_cert 受信するbase64 DERエンコードされたクライアントリーフ証明書です。

    • trusted_leaf_cert_file クライアント証明書を検証するためのPEM CA証明書ファイルへのパスです。

      複数のtrusted_*ディレクティブを使用して、複数のCAまたはリーフ証明書を指定できます。リーフ証明書の1つとしてリストされていない、または指定されたCAのいずれかによって署名されていないクライアント証明書は、モードに従って拒否されます。

  • issuer カスタムの証明書発行者、または証明書を取得するソースを構成します。

    どの発行者が使用されるか、このセグメントに続くオプションは、利用可能な発行者モジュールによって異なります。caやdnsなどの他のサブディレクティブは、実際にはacme発行者を構成するためのショートカット（およびこのサブディレクティブは後で追加されました）であるため、このディレクティブとその他のいくつかのディレクティブを指定することは混乱を招き、禁止されています。

    このサブディレクティブは複数回指定して、複数の冗長な発行者を構成できます。1つが証明書の発行に失敗した場合、次のものが試行されます。

  • get_certificate ハンドシェイク時にマネージャーモジュールから証明書を取得できるようにします。

  • insecure_secrets_log TLSシークレットのファイルへのロギングを有効にします。これはSSLKEYLOGFILEとも呼ばれます。Wiresharkなどのツールで解析できるNSSキーログ形式を使用します。⚠️ セキュリティ警告：他のプログラムやツールがTLS接続を復号化できるため、これは安全ではなく、したがってセキュリティを完全に侵害します。ただし、この機能はデバッグとトラブルシューティングに役立つ場合があります。

発行者

これらの発行者は、tlsディレクティブに標準で付属しています。

acme

ACMEプロトコルを使用して証明書を取得します。acmeはデフォルトの発行者（Let's Encryptを使用）であるため、明示的に設定する必要は通常ありません。

... acme [<directory_url>] {
	dir      <directory_url>
	test_dir <test_directory_url>
	email    <email>
	timeout  <duration>
	disable_http_challenge
	disable_tlsalpn_challenge
	alt_http_port    <port>
	alt_tlsalpn_port <port>
	eab <key_id> <mac_key>
	trusted_roots <pem_files...>
	dns <provider_name> [<options>]
	propagation_timeout <duration>
	propagation_delay   <duration>
	dns_ttl             <duration>
	dns_challenge_override_domain <domain>
	resolvers <dns_servers...>
	preferred_chains [smallest] {
		root_common_name <common_names...>
		any_common_name  <common_names...>
	}
}

  • dir は、ACME CAのディレクトリへのURLです。

    デフォルト: https://acme-v02.api.letsencrypt.org/directory

  • test_dir は、チャレンジを再試行する際に使用するオプションのフォールバックディレクトリです。すべてのチャレンジが失敗した場合、再試行中にこのエンドポイントが使用されます。CAが本番エンドポイントでのレート制限を回避したいステージングエンドポイントを持っている場合に便利です。

    デフォルト: https://acme-staging-v02.api.letsencrypt.org/directory

  • email は、ACMEアカウントの連絡先メールアドレスです。

  • timeout は、ACME操作がタイムアウトするまでの待機時間を設定するduration値です。

  • disable_http_challenge は、HTTPチャレンジを無効にします。

  • disable_tlsalpn_challenge は、TLS-ALPNチャレンジを無効にします。

  • alt_http_port は、HTTPチャレンジを処理する代替ポートです。ポート80で発生する必要があるため、パケットをこの代替ポートに転送する必要があります。

  • alt_tlsalpn_port は、TLS-ALPNチャレンジを処理する代替ポートです。ポート443で発生する必要があるため、パケットをこの代替ポートに転送する必要があります。

  • eab は、一部のACME CAで必要となる可能性がある外部アカウントバインディングを指定します。

  • trusted_roots は、ACME CAサーバーに接続するときに信頼する1つ以上のルート証明書（PEMファイル名として）です。

  • dns は、DNSチャレンジを設定します。

  • propagation_timeout 期間値であり、DNSチャレンジを使用するときにDNS TXTレコードが表示されるのを待つ最大時間を設定します。伝播チェックを無効にするには、-1に設定します。デフォルトは2分です。

  • propagation_delay は、DNSチャレンジを使用するときにDNS TXTレコードの伝播チェックを開始するまでの待機時間を設定するduration値です。デフォルトは0（待機なし）です。

  • dns_ttl 期間値であり、DNSチャレンジに使用されるTXTレコードのTTLを設定します。ほとんど必要ありません。

  • dns_challenge_override_domain DNSチャレンジに使用するドメインをオーバーライドします。これは、チャレンジを別のドメインに委任するためのものです。

    プライマリドメインのDNSプロバイダーに、利用可能なDNSプラグイン がない場合にこれを使用する必要がある場合があります。代わりに、_acme-challengeサブドメインを使用して、プラグインがあるセカンダリドメインを指すCNAMEレコードを追加できます。このオプションは、プラグインからの特別なサポートを必要としません。

    ACME発行者がプライマリドメインのDNSチャレンジを解決しようとすると、CNAMEに従ってセカンダリドメインを探し、TXTレコードを見つけます。

    注：ここで値としてCNAMEレコードからの完全な正規名を使用してください - _acme-challenge サブドメインは自動的に先頭に追加されません。

  • resolvers DNSチャレンジを実行するときに使用されるDNSリゾルバーをカスタマイズします。これらは、システムリゾルバーまたはデフォルトのリゾルバーよりも優先されます。ここで設定すると、リゾルバーは構成されたすべての証明書発行者に伝播されます。

    これは通常、IPアドレスのリストです。たとえば、Google Public DNS を使用するには、

    resolvers 8.8.8.8 8.8.4.4

  • preferred_chains は、Caddyが優先する証明書チェーンを指定します。CAが複数のチェーンを提供する場合に便利です。次のいずれかのオプションを使用します。

    • smallest は、Caddyに最小バイト数のチェーンを優先するように指示します。

    • root_common_name は、1つ以上のコモンネームのリストです。Caddyは、指定されたコモンネームの少なくとも1つと一致するルートを持つ最初のチェーンを選択します。

    • any_common_name は、1つ以上のコモンネームのリストです。Caddyは、指定されたコモンネームの少なくとも1つと一致する発行者を持つ最初のチェーンを選択します。

zerossl

ACMEプロトコルを使用して、特にZeroSSLを使用して証明書を取得します。zerosslはデフォルトの発行者であるため、明示的に設定する必要は通常ありません。

... zerossl [<api_key>] {
	...
}

zerosslの構文は、acmeとまったく同じですが、名前がzerosslであり、オプションでZeroSSL APIキーを取得できる点が異なります。

その機能も同じですが、デフォルトでZeroSSLのディレクトリを使用し、EAB資格情報を自動的にネゴシエートできます（一方、acme発行者では、EAB資格情報を手動で提供し、ディレクトリエンドポイントを設定する必要があります）。

zerosslを明示的に設定する場合、証明書がZeroSSLダッシュボードに表示されるようにemailを設定する必要があります。

internal

内部認証局から証明書を取得します。

... internal {
	ca       <name>
	lifetime <duration>
	sign_with_root
}

  • ca は、使用する内部CAの名前です。デフォルト: local。local CAを設定したり、代替CAを作成したりするには、PKIアプリのグローバルオプションを参照してください。

    デフォルトでは、ルートCA証明書の有効期間は3600d（10年）であり、中間証明書の有効期間は7d（7日）です。

    Caddyは、システムトラストストアにルートCA証明書をインストールしようとしますが、Caddyが特権のないユーザーとして実行されている場合、またはDockerコンテナ内で実行されている場合は失敗する可能性があります。その場合、caddy trustコマンドを使用するか、コンテナからコピーすることにより、ルートCA証明書を手動でインストールする必要があります。

  • lifetime は、内部で発行されたリーフ証明書の有効期間を設定するduration値です。デフォルト: 12h。絶対に必要でない限り、これを変更することはお勧めしません。中間証明書の有効期間よりも短くする必要があります。

  • sign_with_root は、中間証明書の代わりにルートを発行者として強制します。これはお勧めできません。デバイス/クライアントが証明書チェーンを適切に検証しない場合にのみ使用する必要があります（非常にまれです）。

証明書マネージャー

証明書マネージャーモジュールは、マネージャーモジュールの使用は外部ツールまたはサービスが証明書の更新を維持していることを意味する点で発行者モジュールとは異なります。一方、発行者モジュールはCaddy自体が証明書を管理していることを意味します。（発行者モジュールは証明書署名要求（CSR）を入力として受け取りますが、証明書マネージャーモジュールはTLS ClientHelloを入力として受け取ります。）

これらのマネージャーモジュールは、tlsディレクティブに標準で付属しています。

tailscale

ローカルで実行されているTailscale インスタンスから証明書を取得します。TailscaleアカウントでHTTPSを有効にする必要があります（または、オープンソースのHeadscaleサーバー ）；そして、Caddyプロセスはルートとして実行されているか、またはtailscaledを構成してCaddyユーザーに証明書をフェッチする許可を与える必要があります。

注: これは通常不要です！ Caddyは、追加の設定なしに、すべての*.ts.netドメインに対してTailscaleを自動的に使用します。

get_certificate tailscale  # often unnecessary!

http

HTTP(S)リクエストを行うことで証明書を取得します。応答は200ステータスコードを持っている必要があり、本文には完全な証明書（中間証明書を含む）と秘密鍵を含むPEMチェーンが含まれている必要があります。

get_certificate http <url>

  • url は、リクエストを行う完全修飾URLです。パフォーマンス上の理由から、これがローカルエンドポイントであることを強くお勧めします。URLは、次のクエリ文字列パラメーターで拡張されます。

    • server_name: SNI値
    • signature_schemes: 署名アルゴリズムの16進数IDのコンマ区切りリスト
    • cipher_suites: 暗号スイートの16進数IDのコンマ区切りリスト

例

カスタム証明書とキーを使用します。証明書には、サイトのアドレスと一致するSANが必要です。

example.com {
	tls cert.pem key.pem
}

ACME / Let's Encryptによるパブリック証明書ではなく、現在のサイトブロック上のすべてのホストに対してローカルで信頼された証明書を使用します（開発環境で役立ちます）。

example.com {
	tls internal
}

ローカルで信頼された証明書を使用しますが、バックグラウンドではなくオンデマンドで管理します。これにより、任意のドメインをCaddyインスタンスに向け、自動的に証明書をプロビジョニングできます。Caddyインスタンスがパブリックにアクセス可能な場合、攻撃者がサーバーのリソースを使い果たすために使用する可能性があるため、これは使用しないでください。

https:// {
	tls internal {
		on_demand
	}
}

内部CAのカスタムオプションを使用します（tls internalショートカットは使用できません）。

example.com {
	tls {
		issuer internal {
			ca foo
		}
	}
}

ACMEアカウントのメールアドレスを指定します（ただし、すべてのサイトに1つのメールのみを使用する場合は、代わりにemail グローバルオプションをお勧めします）。

example.com {
	tls your@email.com
}

環境変数にアカウント資格情報を持つCloudflareで管理されるドメインのDNSチャレンジを有効にします。これにより、DNS検証が必要なワイルドカード証明書のサポートが有効になります。

*.example.com {
	tls {
		dns cloudflare {env.CLOUDFLARE_API_TOKEN}
	}
}

Caddyに管理させる代わりに、HTTP経由で証明書チェーンを取得します。 get_certificateは、ACME発行をトリガーするのではなくモジュールを使用して証明書をフェッチするon_demandが有効になっていることを意味することに注意してください。

https:// {
	tls {
		get_certificate http http://localhost:9007/certs
	}
}

TLSクライアント認証を有効にし、trusted_ca_cert_file経由で提供されたすべてのCAに対して検証された有効な証明書をクライアントが提示することを要求します。

example.com {
	tls {
		client_auth {
			mode                 require_and_verify
			trusted_ca_cert_file ../caddy.ca.cer
			trusted_ca_cert_file ../root.ca.cer
		}
	}
}