1.5. 为应用程序配置单向和双向 SSL/TLS

1.5.1. 面向应用程序的自动自签名证书创建

使用传统安全域时,JBoss EAP 提供了自动生成自签名证书以用于开发目的。

示例:服务器日志显示自签名证书创建

15:26:09,031 WARN  [org.jboss.as.domain.management.security] (MSC service thread 1-7) WFLYDM0111: Keystore /path/to/jboss/standalone/configuration/application.keystore not found, it will be auto generated on first use with a self signed certificate for host localhost
...
15:26:10,076 WARN  [org.jboss.as.domain.management.security] (MSC service thread 1-2) WFLYDM0113: Generated self signed certificate at /path/to/jboss/configuration/application.keystore. Please note that self signed certificates are not secure, and should only be used for testing purposes. Do not use this self signed certificate in production.
SHA-1 fingerprint of the generated key is 00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33
SHA-256 fingerprint of the generated key is 00:11:22:33:44:55:66:77:88:99:00:aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee
...

此证书是为测试目的创建的,被分配给应用程序使用的 HTTPS 接口。如果文件在首次访问 HTTPS 接口时不存在,将生成包含证书的密钥存储。

示例:使用自签名证书的默认 ApplicationRealm

<security-realm name="ApplicationRealm">
  <server-identities>
    <ssl>
      <keystore path="application.keystore" relative-to="jboss.server.config.dir" keystore-password="password" alias="server" key-password="password" generate-self-signed-certificate-host="localhost"/>
    </ssl>
  </server-identities>
  ...
</security-realm>

示例:默认 HTTPS 接口配置

<subsystem xmlns="urn:jboss:domain:undertow:10.0">
    ...
    <server name="default-server">
        ...
        <https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
        <host name="default-host" alias="localhost">
        ...

注意

如果要禁用自签名证书创建,则需要从服务器密钥存储配置中移除 generate-self-signed-certificate-host="localhost"。generate-self-signed-certificate-host 属性保存应生成自签名证书的主机名。

警告

此自签名证书仅用于测试目的,不应在生产环境中使用。有关使用 Elytronon 为应用程序配置 SSL/TLS 的更多信息,请参阅使用 Elytron subsystem 为应用程序 启用双向 SSL/TLS 以及 为使用 Elytron 子系统 的应用启用双向 SSL/TLS。有关使用传统安全性为应用程序配置 SSL/TLS 的更多信息,请参阅 为应用程序 启用单向 SSL/TLS,以及使用传统安全性 Realms 为应用程序 启用双向 SSL/TLS,以及使用 Legacy Security Realms 的应用程序启用双向 SSL/TLS 部分。

1.5.2. 使用 Elytron

1.5.2.1. 使用 Elytron subsystem 为应用程序启用单向 SSL/TLS

在 JBoss EAP 中,您可以使用 JBoss EAP 管理 CLI 或管理控制台为已部署的应用程序启用单向 SSL/TLS。

在管理 CLI 中,可以通过两种方式启用单向 SSL/TLS:

使用安全命令

security enable-ssl-http-server 命令可用于为已部署的应用程序启用单向 SSL/TLS。

示例:向导使用

security enable-ssl-http-server --interactive

Please provide required pieces of information to enable SSL:
Key-store file name (default default-server.keystore): keystore.jks
Password (blank generated): secret
What is your first and last name? [Unknown]: localhost
What is the name of your organizational unit? [Unknown]:
What is the name of your organization? [Unknown]:
What is the name of your City or Locality? [Unknown]:
What is the name of your State or Province? [Unknown]:
What is the two-letter country code for this unit? [Unknown]:
Is CN=Unknown, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown correct y/n [y]?
Validity (in days, blank default): 365
Alias (blank generated): localhost
Enable SSL Mutual Authentication y/n (blank n): n

SSL options:
key store file: keystore.jks
distinguished name: CN=localhost, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown
password: secret
validity: 365
alias: localhost
Server keystore file keystore.jks, certificate file keystore.pem and keystore.csr file
will be generated in server configuration directory.
Do you confirm y/n: y

注意

执行命令后,管理 CLI 将重新加载服务器。

现在应用程序启用了单向 SSL/TLS。

使用 Elytron 子系统命令

在 JBoss EAP 中,您可以使用 elytron 子系统和 undertow 子系统来为已部署的应用程序启用单向 SSL/TLS。

  1. JBoss EAP 中配置密钥存储。

    /subsystem=elytron/key-store=httpsKS:add(path=/path/to/keystore.jks, credential-reference={clear-text=secret}, type=JKS)

    如果密钥存储文件尚不存在,则可以使用下列命令来生成示例密钥对:

    /subsystem=elytron/key-store=httpsKS:generate-key-pair(alias=localhost,algorithm=RSA,key-size=1024,validity=365,credential-reference={clear-text=secret},distinguished-name="CN=localhost")
    
    /subsystem=elytron/key-store=httpsKS:store()
  2. 配置一个 key-manager,它引用您的 key-store

    /subsystem=elytron/key-manager=httpsKM:add(key-store=httpsKS,credential-reference={clear-text=secret})
    重要

    红帽没有指定上一命令中的 algorithm 属性,因为 Elytron 子系统使用 KeyManagerFactory.getDefaultAlgorithm() 来确定算法。但是,您可以指定 algorithm 属性。要指定 algorithm 属性,您需要知道您使用的 JDK 提供了哪些关键管理器算法。例如,使用 SunJSSE 的 JDK 提供了 PKIXSunX509 算法。

    在上一命令中,您可以指定 SunX509 作为密钥管理器算法属性。

  3. 配置引用您的 key-managerserver-ssl-context

    /subsystem=elytron/server-ssl-context=httpsSSC:add(key-manager=httpsKM, protocols=["TLSv1.2"])
    重要

    您需要确定您要支持的 SSL/TLS 协议。上面的示例命令使用 TLSv1.2。您可以使用 cipher-suite-filter 参数指定允许哪些密码套件,使用-cipher-suites-order 参数来遵循服务器密码套件顺序。use-cipher-suites-order 属性默认设置为 true。这与旧的 security 子系统行为不同,它默认为遵循客户端密码套件顺序。

    警告

    红帽建议显式禁用 SSLv2、SSLv3 和 TLSv1.0,以便在所有受影响的软件包中明确禁用 TLSv1.1 或 TLSv1.2。

  4. 检查并查看 https-listener 是否已配置为使用旧安全域进行 SSL 配置。

    /subsystem=undertow/server=default-server/https-listener=https:read-attribute(name=security-realm)
    {
        "outcome" => "success",
        "result" => "ApplicationRealm"
    }

    以上命令显示 https-listener 被配置为将 ApplicationRealm 传统安全 realm 用于其 SSL 配置。Undertow 无法同时引用传统的安全域和 Elytron 中的 ssl-context,因此您必须删除对旧安全域的引用。

    注意

    如果结果 未定义,则不需要在下一步中删除对安全域的引用。

  5. 删除对旧安全域的引用,并更新 https-listener 以使用 Elytron 中的 ssl-context

    注意

    https-listener 需要始终配置了 security-realmssl-context。在两个配置之间更改时,命令必须作为一个批处理来执行,如下所示。

    batch
    /subsystem=undertow/server=default-server/https-listener=https:undefine-attribute(name=security-realm)
    /subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=ssl-context, value=httpsSSC)
    run-batch
  6. 重新加载服务器。

    reload

    现在应用程序启用了单向 SSL/TLS。

注意

您可以使用 disable-ssl-http-server 命令为已部署的应用程序禁用单向 SSL/TLS。

security disable-ssl-http-server

此命令不会删除 Elytron 资源。它将系统配置为使用 ApplicationRealm legacy security realm 进行其 SSL 配置。

使用管理控制台

您可以使用管理控制台中的 SSL 向导配置 undertow 子系统,为应用启用 SSL。

访问向导:

  1. 访问管理控制台。有关更多信息,请参阅 JBoss EAP 配置指南中的管理控制台部分。
  2. 导航到 ConfigurationSubsystemsWeb(Undertow)Server
  3. 单击要配置的服务器的名称。
  4. View
  5. 导航到 ListenerHTTPS Listener
  6. 选择要启用 SSL 的监听程序,然后点启用 SSL 以启动向导。

    向导可以帮助您在以下场景中启用 SSL:

    • 您需要创建证书存储并生成自签名证书。
    • 您需要从 Let 的加密证书颁发机构获取证书。
    • 您已将证书存储在文件系统中,但没有密钥存储配置。
    • 您已经拥有使用有效证书存储的密钥存储配置。

使用向导,您可以选择性地为 mutual 验证创建信任存储。

1.5.2.2. 使用 Elytron subsystem 为应用程序启用双向 SSL/TLS

  1. 获取或生成您的客户端密钥存储:

    $ keytool -genkeypair -alias client -keyalg RSA -keysize 1024 -validity 365 -keystore client.keystore.jks -dname "CN=client" -keypass secret -storepass secret
  2. 导出客户端证书:

    keytool -exportcert  -keystore client.keystore.jks -alias client -keypass secret -storepass secret -file /path/to/client.cer
  3. 为已部署的应用程序启用双向 SSL/TLS。

    在 JBoss EAP 中,可以使用安全命令或使用 elytron 子系统命令启用部署应用程序的双向 SSL/TLS。

    1. 使用安全命令.

      security enable-ssl-http-server 命令可用于为已部署的应用程序启用双向 SSL/TLS。

      注意

      以下示例没有信任链的验证证书。如果您使用可信证书,则在没有问题的情况下可以验证客户端证书。

      示例:向导使用

      security enable-ssl-http-server --interactive
      
      Please provide required pieces of information to enable SSL:
      Key-store file name (default default-server.keystore): server.keystore.jks
      Password (blank generated): secret
      What is your first and last name? [Unknown]: localhost
      What is the name of your organizational unit? [Unknown]:
      What is the name of your organization? [Unknown]:
      What is the name of your City or Locality? [Unknown]:
      What is the name of your State or Province? [Unknown]:
      What is the two-letter country code for this unit? [Unknown]:
      Is CN=Unknown, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown correct y/n [y]?
      Validity (in days, blank default): 365
      Alias (blank generated): localhost
      Enable SSL Mutual Authentication y/n (blank n): y
      Client certificate (path to pem file): /path/to/client.cer
      Validate certificate y/n (blank y): n
      Trust-store file name (management.truststore): server.truststore.jks
      Password (blank generated): secret
      
      SSL options:
      key store file: server.keystore.jks
      distinguished name: CN=localhost, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown
      password: secret
      validity: 365
      alias: localhost
      client certificate: /path/to/client.cer
      trust store file: server.trustore.jks
      trust store password: secret
      Server keystore file server.keystore.jks, certificate file server.pem and server.csr file will be generated in server configuration directory.
      Server truststore file server.trustore.jks will be generated in server configuration directory.
      Do you confirm y/n: y

      注意

      执行命令后,管理 CLI 将重新加载服务器。

      要完成双向 SSL/TLS 身份验证,您需要将服务器证书导入到客户端信任存储中,并将您的客户端配置为显示客户端证书。

    2. 使用 elytron 子系统命令.

      在 JBoss EAP 中,您还可以使用 elytron 子系统和 undertow 子系统,为已部署的应用启用双向 SSL/TLS。

      1. 获取或生成密钥存储。

        在 JBoss EAP 中启用双向 SSL/TLS 之前,您必须获取或生成您计划使用的密钥存储、信任存储和证书。

        1. 创建服务器密钥存储:

          /subsystem=elytron/key-store=twoWayKS:add(path=/PATH/TO/server.keystore.jks,credential-reference={clear-text=secret},type=JKS)
          
          /subsystem=elytron/key-store=twoWayKS:generate-key-pair(alias=localhost,algorithm=RSA,key-size=1024,validity=365,credential-reference={clear-text=secret},distinguished-name="CN=localhost")
          
          /subsystem=elytron/key-store=twoWayKS:store()
          注意

          以上命令使用了到密钥存储的绝对路径。或者,您可以使用 relative-to 属性来指定基础目录变量,以及 path 指定相对路径。

          /subsystem=elytron/key-store=twoWayKS:add(path=server.keystore.jks,relative-to=jboss.server.config.dir,credential-reference={clear-text=secret},type=JKS)
        2. 导出服务器证书:

          /subsystem=elytron/key-store=twoWayKS:export-certificate(alias=localhost,path=/path/to/server.cer,pem=true)
      2. 为服务器信任存储创建密钥存储,并将客户端证书导入到服务器信任存储中。

        注意

        以下示例没有信任链的验证证书。如果您使用可信证书,则在没有问题的情况下可以验证客户端证书。

        /subsystem=elytron/key-store=twoWayTS:add(path=/path/to/server.truststore.jks,credential-reference={clear-text=secret},type=JKS)
        
        /subsystem=elytron/key-store=twoWayTS:import-certificate(alias=client,path=/path/to/client.cer,credential-reference={clear-text=secret},trust-cacerts=true,validate=false)
        
        /subsystem=elytron/key-store=twoWayTS:store()
      3. 配置 key-manager,它引用您的密钥存储 key-store

        /subsystem=elytron/key-manager=twoWayKM:add(key-store=twoWayKS, credential-reference={clear-text=secret})
        重要

        红帽没有指定上一命令中的 algorithm 属性,因为 Elytron 子系统使用 KeyManagerFactory.getDefaultAlgorithm() 来确定算法。但是,您可以指定 algorithm 属性。要指定 algorithm 属性,您需要知道您使用的 JDK 提供了哪些关键管理器算法。

        例如,使用 SunJSSE 的 JDK 提供了 PKIXSunX509 算法。

        在上一命令中,您可以指定 SunX509 作为密钥管理器算法属性。

      4. 配置一个 trust-manager,它引用您的信任存储 key-store

        /subsystem=elytron/trust-manager=twoWayTM:add(key-store=twoWayTS)
        重要

        红帽没有在上一个命令中指定 algorithm 属性,因为 Elytron 子系统使用 TrustManagerFactory.getDefaultAlgorithm() 来确定算法。但是,您可以指定 algorithm 属性。要指定 algorithm 属性,您需要知道您使用的 JDK 提供了哪些信任管理器算法。例如,使用 SunJSSE 的 JDK 提供了 PKIXSunX509 算法。

        在上一命令中,您可以指定 PKIX 作为信任管理器算法属性。

      5. 配置一个 server-ssl-context,它引用您的 key-managertrust-manager 并启用客户端身份验证:

        /subsystem=elytron/server-ssl-context=twoWaySSC:add(key-manager=twoWayKM, protocols=["TLSv1.2"], trust-manager=twoWayTM, need-client-auth=true)
        重要

        您需要确定您要支持的 SSL/TLS 协议。上面的示例命令使用 TLSv1.2。您可以使用 cipher-suite-filter 参数指定允许哪些密码套件,使用-cipher-suites-order 参数来遵循服务器密码套件顺序。use-cipher-suites-order 属性默认设置为 true。这与旧的 security 子系统行为不同,它默认为遵循客户端密码套件顺序。

        警告

        红帽建议显式禁用 SSLv2、SSLv3 和 TLSv1.0,以便在所有受影响的软件包中明确禁用 TLSv1.1 或 TLSv1.2。

      6. 检查并查看 https-listener 是否已配置为使用旧安全域进行 SSL 配置。

        /subsystem=undertow/server=default-server/https-listener=https:read-attribute(name=security-realm)
        {
            "outcome" => "success",
            "result" => "ApplicationRealm"
        }

        以上命令显示 https-listener 被配置为将 ApplicationRealm 传统安全 realm 用于其 SSL 配置。Undertow 无法同时引用 elytron 子系统中的传统安全域和 ssl-context。因此,您必须移除对旧安全域的引用。

        注意

        如果结果 未定义,则不需要在下一步中删除对安全域的引用。

      7. 删除对旧安全域的引用,并更新 https-listener 以使用 Elytron 中的 ssl-context

        注意

        https-listener 需要始终配置了 security-realmssl-context。在两个配置之间更改时,命令必须作为一个批处理来执行,如下所示。

        batch
        /subsystem=undertow/server=default-server/https-listener=https:undefine-attribute(name=security-realm)
        /subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=ssl-context, value=twoWaySSC)
        run-batch
      8. 重新加载服务器。

        reload
        注意

        要完成双向 SSL/TLS 身份验证,您需要将服务器证书导入到客户端信任存储中,并将您的客户端配置为显示客户端证书。

        $ keytool -importcert -keystore client.truststore.jks -storepass secret -alias localhost -trustcacerts -file /path/to/server.cer
      9. 将您的客户端配置为使用客户端证书。

        您需要将客户端配置为向服务器提供可信客户端证书,以完成双向 SSL/TLS 身份验证。例如,如果使用浏览器,您需要将可信证书导入到浏览器的信任存储中。

        此流程强制双向 SSL/TLS,但不更改应用程序的原始验证方法。

        如果要更改原始身份验证方法,请参阅 JBoss EAP 的 How to Configure Identity Management 中的 Configure Authentication with Certificates 部分。

现在应用程序启用了双向 SSL/TLS。

注意

您可以使用 disable-ssl-http-server 命令为已部署的应用程序禁用双向 SSL/TLS。

security disable-ssl-http-server

此命令不会删除 Elytron 资源。它将系统配置为使用 ApplicationRealm legacy security realm 进行其 SSL 配置。

1.5.3. 在 Elytron 中使用 CRL 配置证书撤销

配置用于启用双向 SSL/TLS 的信任管理器,以将证书撤销列表(CRL)用于 Elytron 中的证书撤销。

先决条件

  • 信任管理器被配置为使用双向 SSL/TLS。
  • 信任管理器包含用于检查的证书链来撤销。

流程

  1. 配置信任管理器,以使用从证书中引用的发布点中获取的 CRL。

    /subsystem=elytron/trust-manager=twoWayTM:write-attribute(name=certificate-revocation-list,value={})
  2. 覆盖从证书中引用的发布点中获取的 CRL。

    /subsystem=elytron/trust-manager=twoWayTM:write-attribute(name=certificate-revocation-list.path, value=intermediate.crl.pem)
  3. 配置 trust-manager,以使用 CRL 进行证书撤销。

    • 如果同时也为证书撤销配置了 OCSP 响应器,在信任管理器中添加值为 true 的属性 ocsp.prefer-crls,以针对证书撤销使用 CRL:

      /subsystem=elytron/trust-manager=twoWayTM:write-attribute(name=ocsp.prefer-crls,value="true")
    • 如果没有为证书撤销配置 OCSP 响应程序,则配置完成。

其它信息

1.5.4. 在 Elytron 中配置使用 OCSP 的认证撤销

配置用于启用双向 SSL/TLS 的信任管理器,以使用在线证书状态协议(OCSP)响应程序进行证书撤销。OCSP 在 RFC6960 中定义。

当为证书撤销配置 OCSP 响应程序和 CRL 时,则默认调用 OCSP 响应程序。

先决条件

  • 信任管理器被配置为使用双向 SSL/TLS。

流程

  1. 将信任管理器配置为使用证书中定义的 OCSP 响应程序进行证书撤销。

    /subsystem=elytron/trust-manager=twoWayTM:write-attribute(name=ocsp,value={})
  2. 覆盖证书中定义的 OCSP 响应程序。

    /subsystem=elytron/trust-manager=twoWayTM:write-attribute(name=ocsp.responder,value="http://example.com/ocsp-responder")

其它信息

1.5.5. 使用旧的安全性 Realms

重要

作为先决条件,应创建 SSL/TLS 加密密钥和证书并将其放置在可访问的目录中。此外,也应可以访问密钥存储别名和密码等相关信息,以及所需的密码套件。有关生成 SSL/TLS 密钥和证书的示例,请参考为管理接口 设置双向 SSL/TLS 中的前两个步骤。有关 HTTPS 侦听器(包括密码套件)的更多信息,请参阅 HTTPS Listener Reference 部分。

1.5.5.1. 为使用旧安全 Realms 的应用启用单向 SSL/TLS

本例假定密钥存储 identity.jks 已复制到服务器配置目录中,并且配置了给定的属性。管理员应该用自己的示例值替换它们。

注意

显示的管理 CLI 命令假定您正在运行 JBoss EAP 单机服务器。有关为 JBoss EAP 受管域使用管理 CLI 的详情,请查看 JBoss EAP 管理 CLI 指南

  1. 首先添加和配置 HTTPS 安全域。配置 HTTPS 安全域后,在引用安全域的 undertow 子系统中配置 https-listener

    batch
    
    /core-service=management/security-realm=HTTPSRealm:add
    
    /core-service=management/security-realm=HTTPSRealm/server-identity=ssl:add(keystore-path=identity.jks, keystore-relative-to=jboss.server.config.dir, keystore-password=password1, alias=appserver)
    
    /subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=security-realm, value=HTTPSRealm)
    
    run-batch
    警告

    红帽建议显式禁用 SSLv2、SSLv3 和 TLSv1.0,以便在所有受影响的软件包中明确禁用 TLSv1.1 或 TLSv1.2。

  2. 重启 JBoss EAP 实例以使更改生效。

1.5.5.2. 为使用旧安全 Realms 的应用启用双向 SSL/TLS

为应用程序设置双向 SSL/TLS 遵循为 管理接口 设置双向 SSL/TLS 中的许多 相同步骤。要为应用程序设置双向 SSL/TLS,您需要执行以下操作:

  1. 为客户端和服务器生成存储
  2. 导出客户端和服务器的证书
  3. 将证书导入到而非信任存储中
  4. 在使用服务器的密钥存储和信任存储的服务器上定义安全域,如 CertificateRealm
  5. 更新 undertow 子系统,以使用安全域并要求客户端验证

为管理接口设置双向 SSL/TLS 中介绍了前四个步骤。

重要

如果服务器尚未重新加载,因为添加了新的安全域,您必须重新加载服务器,然后执行下一步。

更新 Undertow 子系统

创建了密钥存储、证书、信任存储和安全域后,您需要将 HTTPS 侦听器添加到 undertow 子系统,使用您创建的安全域并需要客户端验证:

/subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=security-realm, value=CertificateRealm)

/subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=verify-client, value=REQUIRED)
重要

您必须重新加载服务器,以便这些更改生效。

重要

任何为应用启用了双向 SSL/TLS 的客户端连接到 JBoss EAP 实例都必须有权访问客户端证书或密钥存储,而该证书包含在服务器信任存储中的客户端密钥存储中。如果客户端使用浏览器连接 JBoss EAP 实例,您需要将该证书或密钥存储导入到浏览器的证书管理器中。

注意

除了使用双向 SSL/TLS 和应用的双向 SSL/TLS 一起,请参阅 JBoss EAP 如何 配置安全域以使用基于证书的身份验证一节中的更多有关在应用中使用基于证书的身份验证 的详细信息。