IBM Support

WebSphere WS-Security XML Digital Signature: Learning more about Web Services Security for WebSphere Application Server

Troubleshooting


Problem

Learning more about Web Services Security (WS-Security) is the first step in the troubleshooting process. This document provides you with educational information that can help you learn more about this topic.

Resolving The Problem


Topics:


Overview
 
Digital signature is a method for providing data integrity for a SOAP message (ensuring it was not modified in transit). It can also be used to evaluate trust on a sender since a message is 'signed' using a private key. When a digital signature is validated using the corresponding public key, you have verified that the signer is the authentic holder of the private key.

When using X.509 asymmetric digital signature, public key/private keys are used. A private key is used to sign the data and the matching public key is used to verify the signature.
 

Elements in the WS-Security header

There are several parts to an XML Digital Signature, which is self-describing. In the WS-Security header, there would be the following elements:

  • One or more Signature elements (one for each Signed part configured), containing:
  • A SignatureValue
  • A KeyInfo element
  • A SignedInfo element, containing:
  • One or more Reference elements (one for each Element configured within the Signed part), containing:
  • A DigestValue
  • A DigestMethod
  • A Transform

The KeyInfo element describes how to obtain the key that should be used to validate the signature. There are various methods, including Security token reference (Reference), Key identifier (KeyIdentifier), Embedded token (BinarySecurityToken), and X509 issuer (X509IssuerSerial).

Calculating a signature value is expensive, so it is done only one time for the signature element over a small portion of the message (the SignedInfo element). Compared to calculating a signature, calculating a digest value is 'cheap'. The XSS4J engine canonicalizes an element using the transform specified, then calculates the digest value using the digest method specified. A digest value is calculated for each configured element in the signed part.

Once a digest value is calculated for each of the elements (References) configured within the signed part, XSS4J updates the SignedInfo element that had been initialized by the WS-Security runtime. The SignatureValue is calculated across the final canonicalized SignedInfo element.
<soapenv:Body xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
 

Signature calculation trace snip

Here is an example of a trace from a section of the JAX-WS SignatureGenerator where the signature is calculated for a timestamp and body:

SignatureGene 3 Signing started.
IdUtil > resolveID(Document doc[org.apache.axiom.om.impl.llom.OMDocumentImpl],String id[wssecurity_signature_id_32]) Entry
IdUtil < resolveID(Document doc,String id) returns Element[org.apache.axiom.soap.impl.llom.soap11.SOAP11BodyImpl --- {http://schemas.xmlsoap.org/soap/envelope/}Body] Exit
ReferenceProc 3 no context
SignatureGene 3 ResourceShower logs sign-#wssecurity_signature_id_32:<soapenv:Body xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="wssecurity_signature_id_32"><ns2:sayHello xmlns:ns2="http://samples"><name>c</name></ns2:sayHello></soapenv:Body>
IdUtil > resolveID(Document doc[org.apache.axiom.om.impl.llom.OMDocumentImpl],String id[wssecurity_signature_id_33]) Entry
IdUtil < resolveID(Document doc,String id) returns Element[org.apache.axiom.om.impl.llom.OMElementImpl --- {http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd}Timestamp] Exit
ReferenceProc 3 no context
SignatureGene 3 ResourceShower logs sign-#wssecurity_signature_id_33: <wsu:Timestamp xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"wsu:Id="wssecurity_signature_id_33"><wsu:Created>2009-08-27T19:26:05.343Z</wsu:Created></wsu:Timestamp>
SignatureGene 3 ResourceShower logs sign-SignedInfo: <ds:SignedInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:CanonicalizationMethod><ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"></ds:SignatureMethod><ds:Reference URI="#wssecurity_signature_id_32"><ds:Transforms><ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:Transform></ds:Transforms><ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"></ds:DigestMethod><ds:DigestValue>gr0aIrcNjIMGUkKOJiWpkJevmDY=</ds:DigestValue></ds:Reference><ds:Reference URI="#wssecurity_signature_id_33"><ds:Transforms><ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:Transform></ds:Transforms><ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"></ds:DigestMethod><ds:DigestValue>/fBwdIUvIErwJ4wJ4b5l1aBop6Y=</ds:DigestValue></ds:Reference></ds:SignedInfo>
SignatureGene 3 Signing done.
 
  • The first ResourceShower output is the canonicalized form of the Body.
  • The second ResourceShower output is the canonicalized form of the TimeStamp.
  • The third ResourceShower output is the final canonicalized SignedInfo element containing the digest values for both the Timestamp and Body.
 

Signature validation trace snip

Here is an example of a trace from a section of the JAX-WS SignatureConsumer where the signature shown above is verified:

SignatureCons 3 ResourceShower logs verify-#wssecurity_signature_id_32: <soapenv:Body xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="wssecurity_signature_id_32"><ns2:sayHello xmlns:ns2="http://samples"><name>c</name></ns2:sayHello></soapenv:Body>
IdUtil > resolveID(Document doc[org.apache.axiom.soap.impl.llom.SOAPMessageImpl],String id[wssecurity_signature_id_33]) Entry
IdUtil < resolveID(Document doc,String id) returns Element[org.apache.axiom.om.impl.llom.OMElementImpl --- {http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd}Timestamp] Exit
ReferenceProc 3 not in golden path
SignatureCons 3 ResourceShower logs verify-#wssecurity_signature_id_33: <wsu:Timestamp xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="wssecurity_signature_id_33"><wsu:Created>2009-08-27T19:26:05.343Z</wsu:Created></wsu:Timestamp>
SignatureCons 3 ResourceShower logs verify-SignedInfo: <ds:SignedInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:CanonicalizationMethod><ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"></ds:SignatureMethod><ds:Reference URI="#wssecurity_signature_id_32"><ds:Transforms><ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:Transform></ds:Transforms><ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"></ds:DigestMethod><ds:DigestValue>gr0aIrcNjIMGUkKOJiWpkJevmDY=</ds:DigestValue></ds:Reference><ds:Reference URI="#wssecurity_signature_id_33"><ds:Transforms><ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:Transform></ds:Transforms><ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"></ds:DigestMethod><ds:DigestValue>/fBwdIUvIErwJ4wJ4b5l1aBop6Y=</ds:DigestValue></ds:Reference></ds:SignedInfo>
SignatureCons 3 Core validity=true Signed info validity=true Signed info message='null' Ref[java.util.HashMap$KeyIterator@20562056](validity=true message='Ok.' uri='#wssecurity_signature_id_32' type='null') Ref[java.util.HashMap$KeyIterator@20562056](validity=true message='Ok.' uri='#wssecurity_signature_id_33' type='null')
SignatureCons < verify(Element signature,Key key,WSSConsumerConfig gconfig,SignatureConsumerConfig config,IDResolver idResolver,Document document,VerificationResult vresult,Map selectors,Map context) Exit


 

KeyInfo Types

In the JAX-WS runtime, there are five KeyInfo types:

  • Security token reference
  • Embedded
  • Key Identifier
  • Thumbprint
  • X509 Issuer/Serial Number

In JAX-RPC there is an additional KeyInfo type of Key Name.

By default, the WS-Security runtime is configured to use Security token reference.

The client must be configured to send out the desired KeyInfo type. In JAX-RPC, the receiver must be configured for each KeyInfo type that it will accept; it can accept more than one. In JAX-WS, the receiver will accept any type that is received. In the receiver, Security token reference and Embedded do not require additional configuration because the BinarySecurityToken representing the sender's public certificate is passed in the message. The other three types require additional configuration.

When the Key Identifier, Thumbprint, or X509 Issuer/Serial Number KeyInfo types are used, the BinarySecurityToken representing the sender's public certificate is not passed in the message. The receiver uses the information provided in the KeyInfo element to obtain the key. In order to consume a message with one of these three KeyInfo types, the receiver of the message must have a keystore configured on the X.509 token consumer that contains the key that is being referenced by the key in the KeyInfo. There can only be one of these configured on a token consumer, so client1 can not send one keyid and client2 a different one. The key that we would be looking for is the one that had signed the message. So, for instance, if you signed with dsig-sender.ks/soaprequester, that same key would have to be configured on the receiver. Please note that, although it must be the same certificate (either keyEntry or trustedCertEntry), it does not have to be the same alias.


 

WS-Security headers for each KeyInfo type

The following SOAP Security headers are produced with each KeyInfo type:

Security Token reference
 
<wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<wsu:Timestamp wsu:Id="wssecurity_signature_id_18" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsu:Created>2009-08-26T16:36:40.171Z</wsu:Created>
</wsu:Timestamp>
<wsse:BinarySecurityToken wsu:Id="x509bst_20" EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary" ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">...really_long_BST_goes_here...</wsse:BinarySecurityToken>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:SignedInfo>
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:CanonicalizationMethod>
<ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"></ds:SignatureMethod>
<ds:Reference URI="#wssecurity_signature_id_18">
<ds:Transforms>
<ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:Transform>
</ds:Transforms>
<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"></ds:DigestMethod>
<ds:DigestValue>9g+PSSUH8LvENS19nC2H4X8dTDM=</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>...signature_value...</ds:SignatureValue>
<ds:KeyInfo>
<wsse:SecurityTokenReference>
<wsse:Reference URI="#x509bst_20" ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"></wsse:Reference>
</wsse:SecurityTokenReference>
</ds:KeyInfo>
</ds:Signature>
<wsse:UsernameToken wsu:Id="user2" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsse:Username>user2</wsse:Username>
</wsse:UsernameToken>
</wsse:Security>

Embedded
 
<wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<wsu:Timestamp wsu:Id="wssecurity_signature_id_21" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsu:Created>2009-08-27T19:17:05.687Z</wsu:Created>
</wsu:Timestamp>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:SignedInfo>
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:CanonicalizationMethod>
<ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"></ds:SignatureMethod>
<ds:Reference URI="#wssecurity_signature_id_21">
<ds:Transforms>
<ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:Transform>
</ds:Transforms>
<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"></ds:DigestMethod>
<ds:DigestValue>QE7NyQFVQvYtIZqpWVRiGnrH7Xg=</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>...signature_value...</ds:SignatureValue>
<ds:KeyInfo>
<wsse:SecurityTokenReference>
<wsse:Embedded wsu:Id="x509bst_23" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsse:BinarySecurityToken EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary" ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3">...really_long_BST_goes_here...</wsse:BinarySecurityToken>
</wsse:Embedded>
</wsse:SecurityTokenReference>
</ds:KeyInfo>
</ds:Signature>
<wsse:UsernameToken wsu:Id="user2" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsse:Username>user2</wsse:Username>
</wsse:UsernameToken>
</wsse:Security>

Key Identifier
 
<wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<wsu:Timestamp wsu:Id="wssecurity_signature_id_30" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsu:Created>2009-08-27T19:23:14.484Z</wsu:Created>
</wsu:Timestamp>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:SignedInfo>
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:CanonicalizationMethod>
<ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"></ds:SignatureMethod>
<ds:Reference URI="#wssecurity_signature_id_30">
<ds:Transforms>
<ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:Transform>
</ds:Transforms>
<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"></ds:DigestMethod>
<ds:DigestValue>l5hacS7tofYqs4OQmp1WK67l8Eo=</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>...signature_value...</ds:SignatureValue>
<ds:KeyInfo>
<wsse:SecurityTokenReference>
<wsse:KeyIdentifier
EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary"
ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509SubjectKeyIdentifier">
hbcUPVxeJ7iPjPDWACnhy44BniU=</wsse:KeyIdentifier>
</wsse:SecurityTokenReference>
</ds:KeyInfo>
</ds:Signature>
<wsse:UsernameToken wsu:Id="user2" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsse:Username>user2</wsse:Username>
</wsse:UsernameToken>
</wsse:Security>

Thumbprint
<wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<wsu:Timestamp wsu:Id="wssecurity_signature_id_29" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsu:Created>2009-08-27T19:21:36.890Z</wsu:Created>
</wsu:Timestamp>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:SignedInfo>
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:CanonicalizationMethod>
<ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"></ds:SignatureMethod>
<ds:Reference URI="#wssecurity_signature_id_28">
<ds:Transforms>
<ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:Transform>
</ds:Transforms>
<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"></ds:DigestMethod>
<ds:DigestValue>sqDFjpt/Vew1aMUryV2JiBdKuEs=</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>...signature_value...</ds:SignatureValue>
<ds:KeyInfo>
<wsse:SecurityTokenReference>
<wsse:KeyIdentifier
EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary"
ValueType="http://docs.oasis-open.org/wss/oasis-wss-soap-message-security-1.1#ThumbprintSHA1">
B5o2elsan6IhbxxYgZ62pPFnUIc=</wsse:KeyIdentifier>
</wsse:SecurityTokenReference>
</ds:KeyInfo>
</ds:Signature>
</wsse:Security>

X509 Issuer/Serial Number
 
<wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
<wsu:Timestamp wsu:Id="wssecurity_signature_id_33" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsu:Created>2009-08-27T19:26:05.343Z</wsu:Created>
</wsu:Timestamp>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:SignedInfo>
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:CanonicalizationMethod>
<ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"></ds:SignatureMethod>
<ds:Reference URI="#wssecurity_signature_id_32">
<ds:Transforms>
<ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"></ds:Transform>
</ds:Transforms>
<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"></ds:DigestMethod>
<ds:DigestValue>gr0aIrcNjIMGUkKOJiWpkJevmDY=</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>...signature_value...</ds:SignatureValue>
<ds:KeyInfo>
<wsse:SecurityTokenReference>
<ds:X509Data>
<ds:X509IssuerSerial>
<ds:X509IssuerName>CN=Int CA2,OU=TRL,O=IBM,ST=Kanagawa,C=JP</ds:X509IssuerName>
<ds:X509SerialNumber>260</ds:X509SerialNumber>
</ds:X509IssuerSerial>
</ds:X509Data>
</wsse:SecurityTokenReference>
</ds:KeyInfo>
</ds:Signature>
<wsse:UsernameToken wsu:Id="user2" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<wsse:Username>user2</wsse:Username>
</wsse:UsernameToken>
</wsse:Security>


 

Key Identifier vs Thumbprint

Key Identifier and Thumbprint look very similar. Here are a Key Identifier and Thumbprint generated from the soaprequester alias in dsig-sender.ks:



Key Identifier:
 
<wsse:KeyIdentifier EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary"
ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509SubjectKeyIdentifier">
hbcUPVxeJ7iPjPDWACnhy44BniU=</wsse:KeyIdentifier>

Thumbprint:
 
<wsse:KeyIdentifier EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary"
ValueType="http://docs.oasis-open.org/wss/oasis-wss-soap-message-security-1.1#ThumbprintSHA1">B5o2elsan6IhbxxYgZ62pPFnUIc=</wsse:KeyIdentifier>

Notice that they both are a KeyIdentifier element, but the valueType for the Key Identifier type is {}#X509SubjectKeyIdentifier and the valueType for Thumbprint is {}#ThumbprintSHA1.


 

Token types for certificates

The key used to generate or validate the XML Digital Signature originates from the certificate obtained by one of the methods outlined previously in KeyInfo types. When a certificate is passed in the message as a BinarySecurityToken element, there are three value types with which the certificate can be represented:

  •  X.509
  • An X.509 certificate capable of signature-verification at a minimum.
  • Value types:
    http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509
    http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3
  • X.509 PKIPath
  • An ordered list of X.509 certificates packaged in a PKIPath. The X509PKIPathv1 token type may be used to represent a certificate path.
  • Value type:
    http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509PKIPathv1
  • PKCS#7
  • A list of X.509 certificates and (optionally) CRLs packaged in a PKCS#7 wrapper. The PKCS7 token may be used to represent a certificate path. It is recommended that applications use the PKIPath object for this purpose instead. The order of the certificates in a PKCS#7 data structure is not significant. If an ordered certificate path is converted to PKCS#7 encoded bytes and then converted back, the order of the certificates may not be preserved. Processors shall not assume any significance to the order of the certificates in the data structure.
  • Value type:
    http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#PKCS7
 

Certificate Paths (CertPaths)

Following are three explanations of CertPaths from three different sources:

  • http://www-01.ibm.com/support/knowledgecenter/SSFKSJ_8.0.0/com.ibm.mq.sec.doc/q009880_.htm
    "When you receive the certificate for another entity, you might need to use a certificate chain to obtain the root CA certificate. The certificate chain, also known as the certification path, is a list of certificates used to authenticate an entity. The chain, or path, begins with the certificate of that entity, and each certificate in the chain is signed by the entity identified by the next certificate in the chain. The chain terminates with a root CA certificate. The root CA certificate is always signed by the CA itself. The signatures of all certificates in the chain must be verified until the root CA certificate is reached. Figure 1 illustrates a certification path from the certificate owner to the root CA, where the chain of trust begins. "
  • https://books.google.com/books?id=IRfmJf1bFaIC&printsec=frontcover#v=onepage&q&f=false
    "Class CertPath encapsulates a collection of certificates. It represents a certification path, the first element of the path being the target certificate followed by the certificate of its issuer and so on, terminating at the certificate of the root CA. Quite like a Certificate object, a CertPath object can be instantiated by reading a suitably encoded stream of bytes using CertificateFactory engine class. A certification path follows the structure defined by PKCS#7 standard or is an ASN.1 sequence of X.509 certificates. The former is identified by type "PKCS7" and the later by type "PkiPath". "
  • https://docs.oracle.com/javase/7/docs/api/java/security/cert/CertPath.html
    "By convention, X.509 CertPaths (consisting of X509Certificates), are ordered starting with the target certificate and ending with a certificate issued by the trust anchor. That is, the issuer of one certificate is the subject of the following one. The certificate representing the TrustAnchor should not be included in the certification path. Unvalidated X.509 CertPaths may not follow these conventions. PKIX CertPathValidators will detect any departure from these conventions that cause the certification path to be invalid and throw a CertPathValidatorException. "

Following is the annotated contents of a WS-Security sample keystore and intermediate ca that is shipped with WebSphere. They are located in the (profileRoot)/etc/ws-security/samples directory. This is the view that you'll see with keytool. Keytool ships in the bin directory of WebSphere.
keytool -list -v -keystore dsig-receiver.ks -storepass server
keytool -printcert -v -file intca2.cer
certPath.jpg
 

Evaluation of Trust

Trying to figure out how trust should be evaluated when 'Trust Any' is not configured is not so straight forward. If you cruise around on the internet, you'll find many different ways of explaining the process, most of which are quite confusing. Various articles are included in the section above.

  •  References
    The following document provides a good overview of the Public Key Infrastructure for the evaluation of trust. PKI is what WebSphere WS-Security implements when 'Trust Any' is unchecked in the X.509 token consumer, and truststores, certstores, and/or CRLs are configured. TTP is what we implement when 'Trust Any' is checked.

    http://en.wikipedia.org/wiki/Public_key_infrastructure
     
  • WebSphere's WS-Security implementation
    The WebSphere WS-Security implementation does the following process to validate trust:
     
    • X.509
    • Build the CertPath, then validate the built CertPath
    • PKIPath and PKCS#7
    • Validate the CertPath, then build the validated CertPath

    The ultimate evaluation of trust is almost exclusively done in the Java's CertPathBuilder.build method. This is the method that takes the configured truststores, certstores, and CRLs in a PKIXBuilderParams object and evaluates them against the target certificate. If the certificate is not trusted according to the criteria, an exception will be emitted.

    The Java's CertPath.validate method only ensures that the CertPath itself is 'proper'. In other words, that it follows the CertPath chaining as outlined in the articles listed in the section above.

    The WS-Security runtime is only responsible for populating the PKIXBuilderParams object based on configuration data in the bindings. Other than that, the WS-Security runtime plays no role in doing any part of the CertPath validation.

[{"Product":{"code":"SSEQTP","label":"WebSphere Application Server"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":"Web Services Security","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF012","label":"IBM i"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"},{"code":"PF035","label":"z\/OS"},{"code":"PF013","label":"Inspur K-UX"}],"Version":"9.0;8.5.5;8.5;8.0;7.0","Edition":"Advanced;Base;Developer;Enterprise;Express;Network Deployment;Single Server;WebSphere Business Integration Server Foundation","Line of Business":{"code":"LOB45","label":"Automation"}}]

Document Information

Modified date:
13 November 2019

UID

swg21972066

Page Feedback