linux-system-roles.certificate
証明書システムロール
TLS/SSL証明書の発行と更新を管理するためのロール
Linuxシステムロールは、SSL証明書を発行および更新します。
基本的な使用法：
---
- hosts: webserver
vars:
certificate_requests:
- name: mycert
dns: www.example.com
ca: self-sign
roles:
- linux-system-roles.certificate
RPMベースのシステムでは、証明書は /etc/pki/tls/certs/mycert.crt に配置され、鍵は /etc/pki/tls/private/mycert.key に配置されます。
要件
以下を参照してください
コレクション要件
ロールは、rpm-ostree ノードの管理にのみ外部コレクションを必要とします。rpm-ostree ノードを管理する必要がある場合、以下のコマンドを実行してインストールしてください：
ansible-galaxy collection install -vv -r meta/collection-requirements.yml
変数
| パラメータ | 説明 | 型 | 必須 | デフォルト |
|---|---|---|---|---|
| certificate_wait | 証明書が発行されるまでタスクが待機するかどうか。 | bool | いいえ | yes |
| certificate_requests | 発行される各証明書を表す辞書のリスト。 certificate_requestsを参照してください。 | list | いいえ | - |
certificate_requests
注: common_name, country, state, locality, organization, organizational_unit, email, key_usage, extended_key_usage などのフィールドは、証明書リクエストに含まれることがあります。これらはRFC 5280によって定義されています。
注: CAは要求されたすべてのフィールドを尊重しない場合があります。例えば、リクエストにcountry: USが含まれていても、CAはcountryを持たない証明書を発行するかもしれません。
注: dns, emailとipは、サブジェクト代替名(SAN)を定義するために使用されます。
| パラメータ | 説明 | 型 | 必須 | デフォルト |
|---|---|---|---|---|
| name | 証明書の名前。ファイルが保存されるディレクトリを選択するためにフルパスを使用できます。 | str | はい | - |
| ca | 証明書を発行するCA。 CAsとプロバイダーを参照してください。 | str | はい | - |
| dns | 証明書に含まれるドメイン（またはドメインのリスト）。 common_nameのデフォルト値を提供することもできます。 | strまたはlist | いいえ | - |
| 証明書に含まれるメール（またはメールのリスト）。 | strまたはlist | いいえ | - | |
| ip | 証明書に含まれるIPまたはIPのリスト。IPはIPv4、IPv6のいずれか、または両方を含めることができます。 common_nameのデフォルト値を提供することもできます。 | strまたはlist | いいえ | - |
| auto_renew | 証明書が有効期限の前に自動的に更新されるべきかどうかを示します。 | bool | いいえ | yes |
| owner | 証明書と鍵ファイルのユーザー名（またはユーザーID）。 | str | いいえ | Ansibleを実行しているユーザー |
| group | 証明書と鍵ファイルのグループ名（またはグループID）。 | str | いいえ | Ansibleを実行しているグループ |
| mode | 証明書と鍵ファイルのファイルシステムの権限。 | raw | いいえ | - |
| key_size | 特定のビット数のキーサイズを持つキーを生成します。 | int | いいえ | 2048 - key_sizeを参照 |
| common_name | 証明書のサブジェクトに要求されるコモン名。 | str | いいえ | common_nameを参照 |
| country | 証明書のサブジェクトに要求される国コード。 | str | いいえ | - |
| state | 証明書のサブジェクトに要求される州。 | str | いいえ | - |
| locality | 証明書のサブジェクトに要求される地域（通常は都市）。 | str | いいえ | - |
| organization | 証明書のサブジェクトに要求される組織。 | str | いいえ | - |
| organizational_unit | 証明書のサブジェクトに要求される組織単位。 | str | いいえ | - |
| contact_email | 証明書のサブジェクトに要求される連絡先メール。 | str | いいえ | - |
| key_usage | 証明書のための許可されたキーの使用。 有効な値については、 key_usageをご覧ください。 | list | いいえ | key_usageを参照 |
| extended_key_usage | 証明書リクエストに含めるべき拡張キー使用属性。 | list | いいえ | extended_key_usageを参照 |
| run_before | 証明書を保存する前に実行するコマンド。 run hooksを参照してください。 | str | いいえ | - |
| run_after | 証明書を保存した後に実行するコマンド。 run hooksを参照してください。 | str | いいえ | - |
| principal | Kerberosプリンシパル。 | str | いいえ | - |
| provider | 証明書をリクエストし、管理するために使用される基本的な方法。 | str | いいえ | CAによって異なる |
common_name
common_nameが設定されていない場合、ロールは最初のdnsまたはipの値をデフォルトとして使用しようとします。 dnsとipも設定されていない場合、common_nameは証明書に含まれません。
key_size
証明書のキーサイズの推奨最小値は、異なる組織によって時間とともに異なります。安全設定を提供するために、key_sizeのデフォルト最小値は時間とともに増加します。
証明書が更新される際に常に同じkey_sizeを保持したい場合は、この変数を所望の値に設定してください。
key_usage
key_usageの有効値は：
- digitalSignature
- nonRepudiation
- keyEncipherment
- dataEncipherment
- keyAgreement
- keyCertSign
- cRLSign
- encipherOnly
- decipherOnly
key_usageのデフォルト値は：
- digitalSignature
- keyEncipherment
extended_key_usage
有効なOIDは1つ以上のextended_key_usageを設定するために使用できます。また、ロールによって認識される既知のエイリアスのリストもあります：
- id-kp-serverAuth
- id-kp-clientAuth
- id-kp-codeSigning
- id-kp-emailProtection
- id-kp-timeStamping
- id-kp-OCSPSigning
- id-kp-ipsecEndSystem
- id-kp-ipsecTunnel
- id-kp-ipsecUser
extended_key_usageが設定されていない場合、ロールはデフォルトで：
- id-kp-serverAuth
- id-kp-clientAuth
run hooks
時々、証明書が更新される前にコマンドを実行し、その後に別のコマンドを実行する必要があります。そのためには、run_beforeとrun_afterを使用します。
run_beforeおよびrun_afterに提供された値は、後でプロバイダーによって実行されるシェルスクリプトファイルにラップされ、保存されます。
CAおよびプロバイダー
| CA | プロバイダー | CAの説明 | 要件 |
|---|---|---|---|
| self-sign | certmonger* | ローカルCAから自己署名の証明書を発行します。 | |
| ipa | certmonger* | FreeIPA CAを使用して証明書を発行します。 | ホストはFreeIPAサーバーに登録されている必要があります。 |
* デフォルトプロバイダー。
CAは、要求された証明書の発行と署名に使用されるCA証明書を表します。プロバイダーは、CAに証明書リクエストを送信し、署名された証明書を取得するために使用される方法を表します。
ユーザーがCAをself-sign、プロバイダーをcertmongerとして選択し、後でプロバイダーをopensslに変更することを選択した場合、両方のケースで使用されるCA証明書は同じである必要があります。 注意：opensslはまだサポートされていないプロバイダーであり、ここでは例としてのみ言及されています。
CertmongerとSELinux
SELinuxが強制されている場合、certmongerサービスは、cert_tコンテキストが存在するディレクトリ内のファイルを書き込むか、編集することができます。
さらに、run_beforeおよびrun_afterパラメーターによって実行されるスクリプトがファイルを書くまたは編集する必要がある場合、それらのスクリプトもロール実行前にcert_tコンテキストの存在が必要です。
SELinuxコンテキストを管理するには、selinux システムロールを使用できます。
certmongerとSELinuxの要件に関する詳細については、certmonger_selinux(8)マニュアルをご覧ください。
例
自己署名証明書の発行
*.example.comの証明書を発行し、配布用の標準ディレクトリに配置します。
---
- hosts: webserver
vars:
certificate_requests:
- name: mycert
dns: *.example.com
ca: self-sign
roles:
- linux-system-roles.certificate
各ディストリビューションのディレクトリは、以下の場所にあります：
Debian/Ubuntu:
- 証明書:
/etc/ssl/localcerts/certs/ - 鍵:
/etc/ssl/localcerts/private/
- 証明書:
RHEL/CentOS/Fedora:
- 証明書:
/etc/pki/tls/certs/ - 鍵:
/etc/pki/tls/private/
- 証明書:
証明書の配置場所を選択する
証明書と鍵を発行し、指定された場所に配置します。以下の例では、/another/path/mycert.crtに証明書ファイルが作成され、/another/path/mycert.keyに鍵ファイルが作成されます。
---
- hosts: webserver
vars:
certificate_requests:
- name: /another/path/mycert
dns: *.example.com
ca: self-sign
roles:
- linux-system-roles.certificate
複数のDNS、IP、およびメールを持つ証明書の発行
---
- hosts: webserver
vars:
certificate_requests:
- name: mycert
dns:
- www.example.com
- sub1.example.com
- sub2.example.com
- sub3.example.com
ip:
- 192.0.2.12
- 198.51.100.65
- 2001:db8::2:1
email:
- [email protected]
- [email protected]
ca: self-sign
roles:
- linux-system-roles.certificate
共通のサブジェクトオプションの設定
---
- hosts: webserver
vars:
certificate_requests:
- name: mycert
dns: www.example.com
common_name: www.example.com
ca: self-sign
country: US
state: NY
locality: New York
organization: Red Hat
organizational_unit: platform
email: [email protected]
roles:
- linux-system-roles.certificate
証明書キーサイズの設定
---
- hosts: webserver
vars:
certificate_requests:
- name: mycert
dns: www.example.com
ca: self-sign
key_size: 4096
roles:
- linux-system-roles.certificate
"キー使用"と"拡張キー使用" (EKU) の設定
---
- hosts: webserver
vars:
certificate_requests:
- name: mycert
dns: www.example.com
ca: self-sign
key_usage:
- digitalSignature
- nonRepudiation
- keyEncipherment
extended_key_usage:
- id-kp-clientAuth
- id-kp-serverAuth
roles:
- linux-system-roles.certificate
証明書が発行されるのを待たない
証明書の発行にはCAによって数分かかることがあります。そのため、証明書をリクエストするが、実際には待たないという設定も可能です。
この設定はすべての証明書に影響します。certificate_waitがnoに設定されている場合、ロールは証明書の発行を待ちません。
---
- hosts: webserver
vars:
certificate_wait: false
certificate_requests:
- name: mycert
dns: www.example.com
ca: self-sign
roles:
- linux-system-roles.certificate
プリンシパルの設定
---
- hosts: webserver
vars:
certificate_requests:
- name: mycert
dns: www.example.com
ca: self-sign
principal: HTTP/[email protected]
roles:
- linux-system-roles.certificate
自動更新を無効にする選択肢
デフォルトでは、このロールによって生成された証明書は自動更新の設定になっています。その動作を無効にするには、auto_renew: noを設定します。
---
- hosts: webserver
vars:
certificate_requests:
- name: mycert
dns: www.example.com
ca: self-sign
auto_renew: no
roles:
- linux-system-roles.certificate
FreeIPAを使用して証明書を発行
ホストがFreeIPAサーバーに登録されている場合、そのCAを使用して証明書を発行するオプションもあります。それを行うには、ca: ipaを設定します。
---
- hosts: webserver
vars:
certificate_requests:
- name: mycert
dns: www.example.com
principal: HTTP/[email protected]
ca: ipa
roles:
- linux-system-roles.certificate
証明書が発行される前または後にコマンドを実行する
時々、証明書が更新される前にコマンドを実行し、その後に別のコマンドを実行する必要があります。そのためには、run_beforeとrun_afterを使用します。
---
- hosts: webserver
vars:
certificate_requests:
- name: mycert
dns: www.example.com
ca: self-sign
run_before: systemctl stop webserver.service
run_after: systemctl start webserver.service
roles:
- linux-system-roles.certificate
証明書のオーナーとグループの設定
サービス用の証明書を使用する場合（例：httpd）、証明書を所有するオーナーとグループを設定する必要があります。以下の例では、オーナーとグループの両方がhttpdに設定されています。
---
- hosts: webserver
vars:
certificate_requests:
- name: mycert
dns: www.example.com
ca: self-sign
owner: httpd
group: httpd
roles:
- linux-system-roles.certificate
ユーザー名やグループ名の代わりにUIDやGIDを使用することもできます。
対応状況
現在、CentOS 7以上、RHEL 7以上、Fedoraをサポートしています。Debian 10でテストされています。
rpm-ostree
README-ostree.mdを参照してください。
ライセンス
MIT
著者情報
Sergio Oliveira Campos (@seocam)