Implementing XML Signatures in WSS4J

In the first column of this series, I introduced the WSS4J API. In the second column, I demonstrated the use of XSS4J for XML encryption. In the third column, I implemented the encryption features of WSS4J using the concepts discussed in the second column. And the fourth column of this series demonstrated the use of XSS4J to author XML digital signatures.

In this column, I'll use the concepts discussed in the previous columns to implement XML signature support in our WSS4J API.

As you know from previous columns, the WSS4J API implements the Token interface separately for different types of security tokens in WSS. In this column, I'll discuss six types of WSS signature tokens:

1. X509 binary security token
2. Username password text token
3. Username password digest token
4. X509 key name token
5. X509 pointer token
6. X509 key identifier token

Let's start our discussion by considering a WSS message before and after XML signatures.

A WSS Message Before and After XML Signature

In this section I'll present an input message (i.e. a SOAP message containing data to be signed) that we will use to demonstrate our WSS4J API for signing. Then I'll discuss the output after signing of the input message with six different tokens supported by the WSS specifications.

Listing 1 shows the SOAP input message that we will use as input for the XML signature process. Listings 2, 3, 4, 5, 6, and 7 show the output after signing the input SOAP message with different tokens.

You can see from Listings 2, 3, 4, 5, 6, and 7 that they are not very different from each other. Therefore, we will first explain Listing 2 and then outline the differences between Listing 2 and other tokens.

Listing 2 shows the result after signing the input SOAP message using the wsse:BinarySecurityToken element. I covered the details of using the wsse:BinarySecurityToken element in our web services security series (especially in Part 2). Notice the following points from Listing 2:

1. You can see in Listing 2 that the wsse:BinarySecurityToken element is included inside the wsse:Security element in the SOAP Header.
2. This wsse:BinarySecurityToken element is actually a security token and in order to act as a security token, the wsse:BinarySecurityToken element has to wrap authentication data.
3. The wsse:BinarySecurityToken can wrap different types of authentication data in binary format (e.g. X509 certificates and Kerberos tickets, etc.).
4. You can see in Listing 2 that the wsse:BinarySecurityToken element contains three attributes, namely ValueType, EncodeType, and wsu:Id.
5. The ValueType attribute of the wsse:BinarySecurityToken element in Listing 2 is used to specify the type of the security token wrapped inside this wsse:BinarySecurityToken element. Here the ValueType attribute contains "X509v3", which means this binary security token wraps an X509 version 3 certificate.
6. The wsu:Id attribute is used to specify an identifier for the token. Here we specified its value as "BinarySecurityTokenWithReference." Whenever we need this token for signing a message, we will refer to the token using its wsu:Id.
7. The EncodeType attribute is used to specify the encoding type of the token. In Listing 2 the value of the EncodeType attribute is wsse:Base64Binary. The binary data in raw form cannot be wrapped inside XML markup as such; it may produce problems while XML parsing. Therefore we encode it into base-64 before wrapping inside XML markup. The result of base-64 encoding does not contain any byte that conflicts with XML processing.
8. Now look at the ds:Signature element in wsse:Security element. We discussed the details of the ds:Signature format in the second article of the Web Services Security series.
9. How will we specify the token that a particular signature element uses for signature? Look at the ds:KeyInfo element inside the ds:Signature element in Listing 2. It contains a wsse:SecurityTokenReference element. This wsse:SecurityTokenReference element is used to specify the token that we have used to produce the signature. In Listing 2 we have included a ds:Reference element inside the wsse:SecurityTokenReference element. The URI attribute of the ds:Reference element specifies the ID of the token we want to sign our message. For example in Listing 2 the value of the URI attribute is "#BinarySecurityTokenWithReference". This attribute value points to the token whose wsu:Id is "BinarySecurityTokenWithReference."

We will call the wsse:BinarySecurityToken element that wraps an X509 certificate as X509 binary security token.

Now look at Listing 3, the output in Listing 3 is generated after signing the SOAP message with another type of token named UsernameToken, which is also defined by the WSS Specification. The only difference between Listings 2 and 3 is that the wsse:BinarySecurityToken element in Listing 3 is replaced with wsse:UsernameToken element. The following points explain the wsse:UsernameToken security token:

1. You can see in Listing 3 that a wsse:UsernameToken element contains a username in the wsse:Username element and a password wrapped in the wsse:Password element.
2. The UsernameToken signs the SOAP message with the password specified in the wsse:Password element.
3. The wsse:Password element contains a Type attribute, which specifies the form in which the password is wrapped inside the wsse:Password element. Here in Listing 3 its value is "PasswordText", which tells that the password is in plain-text form. Some users might not like to send their password in plain-text form. They can use another type of security token named Username password digest token, which I will explain shortly.

We will call the username token with password in text form (Listing 3) as Username password text token.

Now look at Listing 4, which is a very slightly modified form of Listing 3. In Listing 4 the Type attribute of wsse:Password element is specified as "PasswordDigest." Moreover, two elements named wsse:Nonce and wsse:Created are included in the wsse:UsernameToken element. In this case the password (which is a secret key), wsse:Nonce (which wraps a random number), and wsse:Created (which is a timestamp) will be combined to form the digest value corresponding to the password.

We have already covered the details of password digests as well as wsse:Nonce and wsse:Created elements while discussing the wsse:UsernameToken element in Listing 1 of the fourth article of the Web Services Security series.

We will call the username token of type "PasswordDigest" (Listing 4) as Username password digest token.

Listing 5 shows the output after signing the message with the key name token. You can see in Listing 5 that it contains a ds:KeyName element as child of the wsse:SecurityTokenReference element. This ds:KeyName element contains the alias of the X509 certificate used to sign the WSS message.

Notice that unlike Listings 2, 3, and 4, Listing 5 does not contain any token. This is because, in Listing 5 a reference to the token is directly included in the wsse:SecurityTokenReference child of the ds:KeyInfo element. In this case we are assuming that the application that receives this WSS message can itself find the certificate using the alias. Therefore, we do not need to send the certificate along with the message.

We will call the key name token (Listing 5) as X509 key name token.

Now have a look at Listing 6, which is a slightly modified form of Listing 5. In Listing 6 the ds:KeyName element inside the wsse:SecurityTokenReference is replaced with the ds:X509Data element structure. The following points explain the ds:X509Data element:

1. The ds:X509Data element wraps an element named X509IssureSerial.
2. The X509IssureSerial element contains two child elements named X509IssuerName and X509SerialNumber. These two elements uniquely identify an X509 certificate used for signing.

Also notice that in the case of Listing 6, we are assuming that the recipient can find the certificate with the information provided in the ds:X509Data element. Therefore, we do not need to send the certificate along with the message.

We will refer to the token with the X509 issuer serial (Listing 6) as X509 pointer token.

Listing 7 shows the output after signing the message with the key identifier token. You can see that Listing 7 is a slightly modified form of Listing 5. In Listing 7 the ds:KeyName element is replaced with the wsse:KeyIdentifier element as the child of the wsse:SecurityTokenReference element. The wsse:KeyIdentifier wraps an identifier of a key.

The following points explain the wsse:KeyIdentifier element:

1. You can see in Listing 7 that the wsse:KeyIdentifier element contains two attributes, namely EncodeType and ValueType.
2. The ValueType attribute of the wsse:KeyIdentifier element in Listing 7 is used to specify the type of the identifier wrapped inside this wsse:KeyIdentifier element. Here the value of the ValueType attribute is wsse:X509SubjectKeyIdentifier, which means this key identifier identifies the signer's X509 certificate.
3. The EncodeType attribute is used to specify the encoding type of the token. In our case we are using base-64 encoding.

Also notice that in case of Listing 7, we are assuming that the recipient can find the certificate with the information provided in the wsse:KeyIdentifier element. Therefore, we do not need to send the certificate along with the message.

We will refer to the key identifier token (Listing 7) as X509 key identifier token.

Pages: 1, 2

Next Page