X.509 토큰으로 웹 서비스 보호

Liberty는 OASIS 웹 서비스 보안 X.509 인증서 토큰 프로파일 1.1을 지원합니다. X.509 토큰은 메시지 서명 및 암호화로 메시지 무결성 및 기밀성을 제공하는 데 사용됩니다.

WS-Security 정책

XML 메시지를 X.509 토큰으로 보호하려면 WSDL(Web Services Description Language)로 지정된 계약을 먼저 작성해야 합니다. 웹 서비스에는 WSDL 파일에 포함된 WS-Security 정책이 들어 있어야 합니다. WS-Security 정책에는 AsymmetricBinding 또는 SymmetricBinding 어설션이 포함될 수 있습니다.

X.509 토큰의 요구사항은 WS-Security 정책에 X509Token 어설션 유형으로 표시되어 있습니다. 다음 예제는 샘플 X509Token 어설션을 보여줍니다.
<sp:X509Token sp:IncludeToken=
  "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
  <wsp:Policy>
    <sp:WssX509V3Token10 />
  </wsp:Policy></sp:X509Token>
AsymmetricBinding 어설션에서는 다음과 같습니다.
  • 개시자 X509Token은 요청자에서 제공자로의 메시지 서명과 제공자에서 요청자로의 메시지 암호화에 사용됩니다.
  • 수신인 X509Token은 제공자에서 요청자로의 메시지 서명과 요청자에서 제공자로의 메시지 암호화에 사용됩니다.
다음 표는 개시인 및 수신인 토큰이 요청/응답 체인의 각 파트에 사용되는 방법을 보여줍니다.
표 1. 요청/응답 체인의 각 파트에 사용되는 개시인 및 수신인 토큰
* 개시인 토큰 수신인 토큰
request out(요청자) sign encrypt
request in(제공자) verify signature decrypt
response out(제공자) encrypt sign
response in(요청자) decrypt verify signature
개인 키는 메시지를 서명하고 복호화하는데 사용됩니다. 공용 인증서는 메시지를 암호화하고 서명을 확인하는 데 사용됩니다. 개인 키는 키의 사용자(서명자 또는 복호화자)에 속합니다.

SymmetricBinding 어설션에서 X509Token에 대해 보호되는 비밀 키 또는 일시적 키는 개시자 및 수신인 모두가 공유합니다. 이 키는 암호화 및 복호화 모두에 사용됩니다.

다음 예제는 AsymmetricBinding 어설션에서 X.509 토큰을 사용하는 샘플 WS-Security 정책을 보여줍니다. 이 정책은 시간소인이 있는 요청 및 응답 모두의 본문에 서명하고 암호화할 수 있게 합니다.
<wsp:Policy wsu:Id="SampleAsymmetricX509TokensPolicy">
  <wsp:ExactlyOne>
    <wsp:All>
      <sp:AsymmetricBinding>
        <wsp:Policy>
          <sp:InitiatorToken>
            <wsp:Policy>
              <sp:X509Token sp:IncludeToken=
                "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
                <wsp:Policy>
                  <sp:WssX509V3Token10 />
                </wsp:Policy>              </sp:X509Token>
            </wsp:Policy>          </sp:InitiatorToken>
          <sp:RecipientToken>
            <wsp:Policy>
              <sp:X509Token sp:IncludeToken=
                "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/Never">
                <wsp:Policy>
                  <sp:WssX509V3Token10 />
                </wsp:Policy>              </sp:X509Token>
            </wsp:Policy>          </sp:RecipientToken>
          <sp:AlgorithmSuite>
            <wsp:Policy>
              <sp:Basic128 />
            </wsp:Policy>          </sp:AlgorithmSuite>
          <sp:Layout>
            <wsp:Policy>
              <sp:Strict />
            </wsp:Policy>          </sp:Layout>
          <sp:IncludeTimestamp />
          <sp:ProtectTokens />
          <sp:OnlySignEntireHeadersAndBody />
        </wsp:Policy>      </sp:AsymmetricBinding>
      <sp:SignedParts>
        <sp:Body />
      </sp:SignedParts>
      <sp:EncryptedParts>
        <sp:Body />
      </sp:EncryptedParts>
      <sp:Wss10>
        <wsp:Policy>
          <sp:MustSupportRefKeyIdentifier />
        </wsp:Policy>      </sp:Wss10>
    </wsp:All>
  </wsp:ExactlyOne>
</wsp:Policy>
다음 예제는 SymmetricBinding 어설션에서 X.509 토큰을 사용하는 샘플 WS-Security 정책을 보여줍니다. 이 정책은 시간소인이 있는 요청 및 응답 둘 다에 대한 본문에 서명할 수 있게 합니다.
<wsp:Policy wsu:Id="SampleSymmetricX509TokensPolicy">
  <wsp:ExactlyOne>
    <wsp:All>
      <sp:SymmetricBinding>
        <wsp:Policy>
          <sp:ProtectionToken>
            <wsp:Policy>
              <sp:X509Token sp:IncludeToken=
                "http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/Never">
                <wsp:Policy>
                  <sp:WssX509V3Token11 />
                  <sp:RequireThumbprintReference />
                </wsp:Policy>              </sp:X509Token>
            </wsp:Policy>          </sp:ProtectionToken>
          <sp:Layout>
            <wsp:Policy>
              <sp:Lax />
            </wsp:Policy>          </sp:Layout>
          <sp:IncludeTimestamp />
          <sp:OnlySignEntireHeadersAndBody />
          <sp:SignBeforeEncrypting />
          <sp:AlgorithmSuite>
            <wsp:Policy>
              <sp:Basic128 />
            </wsp:Policy>          </sp:AlgorithmSuite>
        </wsp:Policy>      </sp:SymmetricBinding>
      <sp:EncryptedParts>
        <sp:Body />
      </sp:EncryptedParts>
      <sp:SignedParts>
        <sp:Body />
      </sp:SignedParts>
    </wsp:All>
  </wsp:ExactlyOne>
</wsp:Policy>

토큰 참조 및 토큰 포함

토큰 어설션은 메시지에 토큰을 포함해야 sp:IncludeToken 속성을 전달할 수 있습니다. 몇몇 토큰 어설션은 직접 참조 외에 토큰 참조 메커니즘을 지원합니다. 토큰 어설션에 여러 참조 어설션이 있는 경우, 해당 토큰에 대한 참조에는 지정된 모든 참조 유형이 포함되어야 합니다. 예를 들어, 토큰 어설션이 ../Always 값의 sp:IncludeToken 속성을 전달하는 경우, 토큰 어설션 또한 중첩된 sp:RequireIssuerSerialReference 어설션을 포함하고 있으면 토큰은 메시지에 두 번 포함되어야 합니다. 이와 같은 조합이 오류는 아니지만 효율성을 위해 피하는 것이 최상입니다.

IncludeToken 어설션은 Liberty에서는 강제 실행되지만, WebSphere Application Server Traditional의 WS-Security 런타임 환경에서는 무시됩니다.

WS-Security 정책은 다음과 같은 토큰 참조 메커니즘을 지원합니다.
  • KeyIdentifier: <sp:RequireKeyIdentifierReference... />
  • IssuerSerial: <sp:RequireIssuerSerialReference ... />
  • Thumbprint: <sp:RequireThumbprintReference ... />

이 참조는 클라이언트/생성기 측에서 X.509 토큰을 생성할 때 사용되고 서버/이용자 측에서 적용되지 않습니다.

런타임 구성

Liberty의 WS-Security 기능 런타임은 WS-Security 정책에서 다루는 것보다 X.509 토큰의 메시지 보호에 대한 구성 옵션을 추가로 제공합니다. 런타임 구성은 server.xml 파일에 정의되어 있습니다. 런타임 구성에는 signaturePropertiesencryptionProperties 키와 키 저장소 같은 암호용 특성이 포함됩니다.

다음 예제는 X509Token 어설션에 대한 클라이언트 구성을 보여줍니다.
<wsSecurityClient id="default"
                  ws-security.callback-handler="com.ibm.ws.wssecurity.example.cbh.KeyPasswordCallbackHandler">
  <signatureProperties org.apache.ws.security.crypto.merlin.keystore.type="jks"
                       org.apache.ws.security.crypto.merlin.keystore.password="LibertyX509Client"
                       org.apache.ws.security.crypto.merlin.keystore.alias="x509ClientDefault"
                       org.apache.ws.security.crypto.merlin.file="${server.config.dir}/x509ClientDefault.jks" />
  <encryptionProperties org.apache.ws.security.crypto.merlin.keystore.type="jks"
                        org.apache.ws.security.crypto.merlin.keystore.password="LibertyXClient"
                        org.apache.ws.security.crypto.merlin.keystore.alias="x509DefaultCert"
                        org.apache.ws.security.crypto.merlin.file="${server.config.dir}/x509ClientDefault.jks" />
</wsSecurityClient>
다음 예제는 X509Token 어설션에 대한 서버 구성을 보여줍니다.
<wsSecurityProvider id="default"
                    ws-security.callback-handler="com.ibm.ws.wssecurity.example.cbh.KeyPasswordCallbackHandler">
  <signatureProperties org.apache.ws.security.crypto.merlin.keystore.type="jks"
                       org.apache.ws.security.crypto.merlin.keystore.password="LibertyX509Server"
                       org.apache.ws.security.crypto.merlin.keystore.alias="x509ServerDefault"
                       org.apache.ws.security.crypto.merlin.file="${server.config.dir}/x509ServerDefault.jks"/>
  <encryptionProperties org.apache.ws.security.crypto.merlin.keystore.type="jks"
                        org.apache.ws.security.crypto.merlin.keystore.password="LibertyX509Server"
                        org.apache.ws.security.crypto.merlin.keystore.alias="x509ServerDefault"
                        org.apache.ws.security.crypto.merlin.file="${server.config.dir}/x509ServerDefault.jks"/>
</wsSecurityProvider>

런타임 구성에서, signaturePropertiesencryptionProperties 특성은 WSS4J 구성의 암호화 특성에 해당됩니다. 자세한 정보는 WSS4J 구성을 참조하십시오. 많은 암호화 특성에 올바른 기본값이 있으므로 기본값을 지정하지 않아도 됩니다. 그러나 키 저장소와 같은 다른 특성과 키 관련 특성을 지정해야 합니다.

이 특성에 대한 자세한 정보는 웹 서비스 보안 기본 구성을 참조하십시오.

키저장소 파일, 키 및 인증서

메시지 서명 및 암호화에는 공용 인증서 및 개인 키를 사용해야 합니다. 이 공용 인증서 및 개인 키는 키 저장소 파일에 저장됩니다. X509Token 어설션을 사용할 때 키 저장소 파일이 필요합니다. 클라이언트 측 키 저장소 파일에는 클라이언트의 개인 키와 서버의 공개 키에 해당하는 인증서 체인이 있습니다. 서버 측 키 저장소 파일에는 서버의 개인 키와 클라이언트의 공개 키에 해당하는 인증서 체인이 있습니다.

SOAP 메시지에 서명하고 암호화하는 경우, signaturePropertiesencryptionProperties 특성은 다음과 같이 WS-Security 런타임 환경에 의해 해석됩니다.
  • AsymmetricBinding 어설션

    signatureProperties 특성에 의해 지정된 키는 아웃바운드 메시지 서명을 위한 개인 키로 사용되고 인바운드 메시지의 복호화에도 사용됩니다.

    encryptionProperties 특성에 의해 지정된 키는 아웃바운드 메시지 암호화를 위한 공개 키로 사용되고 인바운드 메시지에서의 서명 확인에도 사용됩니다.

  • SymmetricBinding 어설션

    encryptionProperties 특성에 의해 지정된 키가 사용되는 반면에 signatureProperties 특성이 무시됩니다.

개인 키 비밀번호 CallbackHandler

키 저장소에서 개인 키에 액세스하려면 두 개의 다른 비밀번호를 알아야 합니다. 한 비밀번호는 개인 키가 저장되는 키 저장소의 비밀번호입니다. 다른 비밀번호는 개인 키 자체에 대한 비밀번호입니다. 키 저장소에 대한 비밀번호가 암호화 특성 중 하나에 지정되는 반면(signatureProperties 또는 encryptionProperties), CallbackHandler 클래스는 보통 키 저장소의 개인 키에 액세스하기 위해 WS-Security에서 사용됩니다. Liberty에서 이 CallbackHandler 클래스는 Liberty 기능 및 security.xml에서 ws-security.callback-handler 사용자 정의 특성의 값으로 지정된 해당 클래스 이름으로서 패키징되어야 합니다.

CallbackHandler 클래스는 키 저장소의 개인 키에 액세스하기 위해 WS-Security에서 필요합니다.

비밀번호 CallbackHandler 클래스에 대한 자세한 정보는 WS-Security에 대한 비밀번호 콜백 핸들러 개발을 참조하십시오.

CallbackHandler 클래스가 개인 키 비밀번호를 제공하지 않는 경우 ws-security 런타임이 먼저 CallbackHandler를 시도하므로 제공되어야 하며 그런 다음 암호화 특성에 지정된 비밀번호가 개인 키의 기본 비밀번호로 사용됩니다. 이 특성은 org.apache.ws.security.crypto.merlin.keystore.private.password로 구성됩니다.

security.xml 파일의 각 wsSecurityClientwsSecurityProvider 섹션에는 지원되는 단 하나의 ws-security.callback-handler 사용자 정의 특성이 있으므로 단일 비밀번호 콜백 핸들러가 애플리케이션 유형(클라이언트 또는 서버)마다 기본값을 사용하는 모든 필수 비밀번호를 지원해야 합니다. 모든 제공자 애플리케이션은 기본 비밀번호 콜백 핸들러를 사용해야 합니다. 클라이언트 애플리케이션은 클라이언트의 웹 서비스 호출에 대한 요청 컨텍스트에 ws-security.callback-handler 사용자 정의 특성을 지정하여 기본 콜백 핸들러를 대체할 수 있습니다.

단일 웹 서비스 호출에 X.509 개인 키 및 UsernameToken에 대한 비밀번호를 제공해야 하는 경우, 사용마다 별도의 콜백 핸들러를 제공할 수 없습니다. 이러한 경우, 두 종류의 비밀번호 모두를 처리하는 단일 콜백 핸들러를 구현해야 합니다. 이전 예제에 설명된 것처럼, 리턴되는 비밀번호의 종류를 판별하기 위해 WSPasswordCallback.getUsage() 메소드를 사용해야 합니다. 지원되는 사용 코드에 대해서는 WSPasswordCallback API 문서를 참조하십시오(http://ws.apache.org/wss4j/apidocs/org/apache/wss4j/common/ext/WSPasswordCallback.html).

인증서 폐기 목록

인증서 폐기 목록(CRL)은 폐기된 인증서의 일련 번호 목록입니다. CRL은 독립형 파일이거나 PKCS#7 랩퍼에서 패키징될 수 있습니다. 서비스에 대한 액세스를 제어하기 위해 신뢰 저장소와 함께 CRL을 사용할 수 있습니다.

CRL 파일에서 폐기 확인을 수행하도록 Liberty의 WS-Security 기능을 구성하기 위해 두 단계가 필요합니다. CRL 파일로 인증서 폐기 확인을 사용하려면 server.xml 파일에서 WS-Security 런타임 구성을 수정해야 합니다.
  1. wsSecurityProvider 또는 wsSecurityClient 요소 내에서 다음 특성을 추가하십시오.
    ws-security.enableRevocation="true"
  2. signatureProperties 요소 내에서 다음 특성을 추가하고 값을 CRL 파일에 설정하십시오.
    org.apache.ws.security.crypto.merlin.x509crl.file
다음 예제는 CRL 파일로 인증서 폐기 확인을 사용하는 샘플 WS-Security 제공자 구성을 보여줍니다.
<wsSecurityProvider id="default"
    ws-security.callback-handler="com.acme.example.cbh.CommonPasswordCallback" 
    ws-security.signature.username="x509ServerDefault"
    ws-security.enableRevocation="true">
  <signatureProperties 
      org.apache.ws.security.crypto.merlin.keystore.type="jks"
      org.apache.ws.security.crypto.merlin.keystore.password="LibertyX509Server"
      org.apache.ws.security.crypto.merlin.keystore.alias="x509ServerDefault"
      org.apache.ws.security.crypto.merlin.file="${server.config.dir}/x509ServerDefault.ks"
      org.apache.ws.security.crypto.merlin.truststore.password="LibertyX509Server"
      org.apache.ws.security.crypto.merlin.truststore.file="${server.config.dir}/x509DefaultServer.ks"
      org.apache.ws.security.crypto.merlin.x509crl.file="${server.config.dir}/revokedCerts.crl"/>
</wsSecurityProvider>

주제의 유형을 표시하는 아이콘 개념 주제

파일 이름: cwlp_wssec_x509.html