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 어설션이 포함될 수 있습니다.
<sp:X509Token sp:IncludeToken=
"http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702/IncludeToken/AlwaysToRecipient">
<wsp:Policy>
<sp:WssX509V3Token10 />
</wsp:Policy>
</sp:X509Token>
- 개시자 X509Token은 요청자에서 제공자로의 메시지 서명과 제공자에서 요청자로의 메시지 암호화에 사용됩니다.
- 수신인 X509Token은 제공자에서 요청자로의 메시지 서명과 요청자에서 제공자로의 메시지 암호화에 사용됩니다.
* | 개시인 토큰 | 수신인 토큰 |
---|---|---|
request out(요청자) | sign | encrypt |
request in(제공자) | verify signature | decrypt |
response out(제공자) | encrypt | sign |
response in(요청자) | decrypt | verify signature |
SymmetricBinding 어설션에서 X509Token에 대해 보호되는 비밀 키 또는 일시적 키는 개시자 및 수신인 모두가 공유합니다. 이 키는 암호화 및 복호화 모두에 사용됩니다.
<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>
<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 런타임 환경에서는 무시됩니다.
- KeyIdentifier: <sp:RequireKeyIdentifierReference... />
- IssuerSerial: <sp:RequireIssuerSerialReference ... />
- Thumbprint: <sp:RequireThumbprintReference ... />
이 참조는 클라이언트/생성기 측에서 X.509 토큰을 생성할 때 사용되고 서버/이용자 측에서 적용되지 않습니다.
런타임 구성
Liberty의 WS-Security 기능 런타임은 WS-Security 정책에서 다루는 것보다 많은 구성 옵션(X.509 토큰을 사용하는 메시지 보호에 대한)을 제공합니다. 런타임 구성은 server.xml 파일에 정의되어 있습니다. 런타임 구성에는 signatureProperties 및 encryptionProperties 키와 키 저장소 같은 암호용 특성이 포함됩니다.
<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>
<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>
런타임 구성에서, signatureProperties와 encryptionProperties 특성은 WSS4J 구성의 암호화 특성에 해당됩니다. 자세한 정보는 WSS4J 구성을 참조하십시오. 많은 암호화 특성에 올바른 기본값이 있으므로 기본값을 지정하지 않아도 됩니다. 그러나 키 저장소와 같은 다른 특성과 키 관련 특성을 지정해야 합니다.
이 특성에 대한 자세한 정보는 웹 서비스 보안 기본 구성을 참조하십시오.
키저장소 파일, 키 및 인증서
메시지 서명 및 암호화에는 공용 인증서 및 개인 키를 사용해야 합니다. 이 공용 인증서 및 개인 키는 키 저장소 파일에 저장됩니다. X509Token 어설션을 사용할 때 키 저장소 파일이 필요합니다. 클라이언트 측 키 저장소 파일에는 클라이언트의 개인 키와 서버의 공개 키에 해당하는 인증서 체인이 있습니다. 서버 측 키 저장소 파일에는 서버의 개인 키와 클라이언트의 공개 키에 해당하는 인증서 체인이 있습니다.
- AsymmetricBinding 어설션
signatureProperties 특성에 의해 지정된 키는 아웃바운드 메시지 서명을 위한 개인 키로 사용되고 인바운드 메시지의 복호화에도 사용됩니다.
encryptionProperties 특성에 의해 지정된 키는 아웃바운드 메시지 암호화를 위한 공개 키로 사용되고 인바운드 메시지에서의 서명 확인에도 사용됩니다.
- SymmetricBinding 어설션
encryptionProperties 특성에 의해 지정된 키가 사용되는 반면에 signatureProperties 특성이 무시됩니다.
개인 키 비밀번호 CallbackHandler
키 저장소에서 개인 키에 액세스하려면 두 개의 다른 비밀번호를 알아야 합니다. 한 비밀번호는 개인 키가 저장되는 키 저장소의 비밀번호입니다. 다른 비밀번호는 개인 키 자체에 대한 비밀번호입니다. 키 저장소에 대한 비밀번호가 암호화 특성 중 하나에 지정되는 반면(signatureProperties 또는 encryptionProperties), CallbackHandler 클래스는 보통 키 저장소의 개인 키에 액세스하기 위해 WS-Security에서 사용됩니다. Liberty에서 이 CallbackHandler 클래스는 security.xml의 ws-security.callback-handler 사용자 정의 특성 값으로 지정된 Liberty 기능 및 해당 클래스 이름으로 패키징되어야 합니다.
이 CallbackHandler 클래스는 키 저장소의 개인 키에 액세스하기 위해 WS-Security에서 필요합니다.
비밀번호 CallbackHandler 클래스에 대한 자세한 정보는 WS-Security에 대한 비밀번호 콜백 핸들러 개발을 참조하십시오.CallbackHandler 클래스가 개인 키 비밀번호를 제공하지 않는 경우 ws-security 런타임이 먼저 CallbackHandler를 시도하므로 제공되어야 하며 그런 다음 암호화 특성에 지정된 비밀번호가 개인 키의 기본 비밀번호로 사용됩니다. 이 특성은 org.apache.ws.security.crypto.merlin.keystore.private.password로 구성됩니다.
security.xml 파일의 각 wsSecurityClient 및 wsSecurityProvider 섹션에는 지원되는 단 하나의 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을 사용할 수 있습니다.
- wsSecurityProvider 또는 wsSecurityClient 요소 내에서
다음 특성을 추가하십시오.
ws-security.enableRevocation="true"
- signatureProperties 요소 내에서
다음 특성을 추가하고 값을 CRL 파일에 설정하십시오.
org.apache.ws.security.crypto.merlin.x509crl.file
<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>