9 Oracle Web Services Security

For outgoing messages, you need to create a new <wsse:Security> header, add security tokens and then encrypt and/or sign parts of the document. Here is how to accomplish this task:

// Assuming we the outgoing message has already been constructed into 
// a SOAPMessage object (part of SAAJ API)
SOAPMessage msg = ...
 
// Now create a new <wsse:Security> Header 
// newInstance will internally use SOAPHeader.addHeaderElement
SOAPEnvelope env = msg.getSOAPPart().getEnvelope();
WSSecurity ws = WSSecurity.newInstance(env);
 
// Add required prefixes to this SOAP header
 
// Now add some security tokens (refer to the next section on 
// how to create security tokens)
UsernameToken ut = ...
ws.addUsernameToken(ut);
 
// Create some security token references to this token 
// (refer to following sections)
ws.createSTR...
 
// Now sign or encrypt some data (refer to following sections)
// These should use the above STRs
ws.sign(...);
ws.encryptWithEncKey(...);
ws.encryptNoEncKey(...);

For incoming messages, you need to look for a particular <wsse:Security> header, inspect its contents, and verify or decrypt parts of the document. To accomplish this task:

// Assuming we the incoming message has already been constructed into 
// a SOAPMessage object (part of SAAJ API)
SOAPMessage msg = ...

First, create a UsernameToken and place it inside your WSSecurity header. The only mandatory field in the UsernameToken is the username:

// create a Username token
WSSecurity ws = ...
UsernameToken ut = new UsernameToken(doc);
ut.setUserName("Zoe");
 
// remember to put this inside your WSSecurity header. 
// addUserNameToken puts it at the beginning, you can also
// use a regular DOM method appendChild or insertChild to put it in.
ws.addUsernameToken(ut); 
 
// optionally add an wsu:Id, so you can refer to it
ut.setWsuId("MyUser");

Next, decide how to put the password into this token. There are several choices:

// For options 1 and 2, use the setPassword method
ut.setPassword("IloveDogs");  
 
// With this mechanism, the reciever should simply call
// UsernameToken.getPassword to check if the password is as expected.
 
// For option 3, use the setPasswordDigest method, but before doing 
// thatfor that you have to  at first set a nonce and a created date.
SecureRandom random = SecureRandom.getInstance("SHA1PRNG");
byte nonce[] = new byte[20];
random.nextBytes(nonce); // compute a 20 byte random nonce
ut.setNonce(nonce);
ut.setCreatedDate(new Date()); // Set the date to now
ut.setPasswordDigest("IloveDogs"); // will compute the digest from 
                                   // this clear text password using 
                                   // nonce and createdDate
 
// For this mechanism, the reciever should use the following
byte nonce[] = ut.getNonce();
.. check against the used nonces, to make sure this is a new nonce
Date createdDate = ut.getCreated();
.. check that this createdDate is within an expected clock skew
boolean valid = ut.isValid(userName, passwd), 
// above call will recompute the digest from the passwd
// and the nonce and created date, and check if this digest matches 
// the digest in the username token
 
 
// For option 4, set the salt and iteration count
SecureRandom random = SecureRandom.getInstance("SHA1PRNG");
byte salt[] = new byte[15];
random.nextBytes(salt); // compute a 15 byte random salt
 
ut.setSalt(1, salt);
ut.setIteration(1000);
SecretKey key = ut.deriveKey("IloveDogs");

Now you can use this secret key to sign or encrypt data.

You can either use the X509BinarySecurityToken constructor followed by the setToken method, or use the equivalent helper method WSSecurity.createBST_X509:

WSSecurity ws = ...
X509Certificate cert = ...
X509BinarySecurityToken x509token = WSSecurity.createBST_X509(cert);
 
// remember to put this inside your WSSecurity header. 
// addX509CertificateToken puts it at the beginning, you can also
// use a regular DOM method appendChild or insertChild to put it in.
ws.addX509CertificateToken(x509Token);
 
// optionally add an wsu:Id, so you can refer to it
x509Token.setWsuId("MyCert");

You can also create an X509BinarySecurityToken from a CertPath object if you want to include an entire chain of certificates.

For encryption data with this certificate, you need the public key which you can obtain by using cert.getPublicKey(). For signing, however, you need the private key, which you should maintain in a keystore.

Kerberos tokens are used, as a rule, in conjunction with the Java GSS-API.

This example shows how to create a client-side token:

//Use JAAS Authentication with Kerberos Login Module
 
// Set up the config files and then call  login()
// to login using this module. This will cause the client to contact 
// the Kerberos Authentication-Service and get a ticket to talk to the 
// Kerberos Ticket-Granting-Service
LoginContext lc = new LoginContext(...);
lc.login();
 
//Use JAAS Authorization to set the subject into the thread context
Subject.doAs(lc.getSubject(), action)
 
// The rest of the code should be executed as a Privileged action
// Create a GSSContext to talk to a particular server.
 
GSSManager gssManager = GSSManager.getInstance();
GSSName serviceName = gssManager.createName(svcPrincipalName, null);
GSSContext gssContext = gssManager.createContext(serviceName, null, 
    null, GSSCredential.DEFAULT_LIFETIME);
 
// Then call initSecContext. this will cause the client to contact 
// the Ticket-Granting-Service to obtain a ticket for talking to that 
// particular server. The token that is returned by the initSecContext
// is a GSS wrapped AP_REQ packet.
byte[] token = new byte[1];
token = gssContext.initSecContext(token, 0, token.length);
 
// Create a Kerberos BST using this AP_REQ packet
WSSecurity ws = ...
KerberosBinarySecurityToken kbst = ws.createBST_Kerberos(token,   
      WSSURI.vt_GSSKerberosv5);
ws.addKerberosToken(kbst);
 
// Get the sessionKey that is present inside the AP_REQ packet, 
// this is the session that is generated by the TGT and returned
// to the client in the initSecContext class
//
// This getSessionKey call simply calls Subject.getPrivateCredentials
// to get a list of tickets associated with the subject, and then
// iterates through them to find the one to be used for
// for that particular server
SecretKey sessionKey = 
   KerberosUtils.getSessionKey(lc.getSubject(),svcPrincipalName);

Now you can use this secret key to sign or encrypt data.

Server Side

Server-side kerberos tokens require creation of the GSSContext and extraction of the session key.

This example shows how to create a server-side kerberos token:

// Use JAAS Authentication and Authorization as for the client 
// Create GSSContext will null credentials </b><br>
SSManager manager = GSSManager.getInstance();
GSSContext gssContext = manager.createContext((GSSCredential)null);
 
 
// Locate the KerberosBinarySecurityToken in the incoming WSSecurity 
// header. You can do this by doing a DOM search
WSSecurity = ...
KerberosBinarySecurityToken kbst = ...
 
 
// Now extract the AP_REQ from the BST and call acceptSecContext 
byte ap_req[] = kbst.getValue();
gssContext.acceptSecContext(ap_req);
 
// The context is now extablished. (Note Mutual authentication would 
// need one more round trip)
 
// Now extract the session key
// KerberosUtils.getSession is an overloaded method, and this 
// particular one is meant to be used by server. Internally
// it decrypts the ap_req packet using the server's key (or the 
// tgtSession key) and extracts the key from the decrypted ap_req
// packet
Subject srvrSubject = ...
SecretKey sessionKey = 
   KerberosUtils.getSessionKey(srvrSubject, ap_req);

Now you can decrypt or verify using this key.

Refer to Oracle XML Security for information on how to create Assertion objects. From the Assertion object you can create a SAML assertion token by simply invoking the SAMLAssertionToken(Assertion assertion) constructor.

STRs are created using a uniform procedure; the mechanism to pass in the STR depends on the type of token.

To create the STR:

Subsequent sections demonstrate how to pass in the STR for various tokens.

This example shows how to create a reference STR for a username token:

WSSecurity ws = ...
WSSecurityTokenReference str = 
   ws.createSTR_Username_ref("#MyUser");

This example shows how to create a reference STR for an X509 token:

WSSecurity ws = ...
WSSecurityTokenReference str =     
   ws.createSTR_X509_Ref("#MyCert");

This example shows how to create a reference STR for a kerberos token:

WSSecurity ws = ...
// use the appropriate value type
String valueType = WSSURI.vt_GSSKerberosv5;
WSSecurityTokenReference str =     
   ws.createSTR_KerberosKeyRef ( "#MyToken");

This example shows how to create a reference STR for a SAML assertion token:

WSSecurity ws = ...
WSSecurityTokenReference str =
   ws.createSTR_SAML_Assertion_Ref20("MySAMLAssertion")

This example shows how to create a reference STR for an encrypted key:

WSSecurity ws = ...
WSSecurityTokenReference str =
  ws.createSTR_EncKeyRef("MyEncKey")

Instead of using the createSTR methods you can also create the reference directly with the appropriate valueType and tokenType:

WSSecurity ws = ...
String uri = "#MyToken";
WSSReference ref = new WSSReference(doc, uri);
ref.setValueType(valueType); // set an optional valueType
WSSecurityTokenReference str = new WSSecurityTokenReference(doc);
str.setTokenType(tokenType); // set an optional tokenType
str.appendChild(ref);

A KeyIdentifier is another way to refer to a security token that uses some intrinsic property of the token; for example, an assertionID for a SAML Token or a Subject Key Identifier for an X509 token.

KeyIdentifers are often used when the token itself is not present in the document. For example, an incoming message can be encrypted with a X509Cert, but instead of having that X509Cert in the message, it can have only a hint to it, in the form of a SubjectKeyIdentifier.

There are three different ways to identify an X509 Token:

X509Certificate cert = ... 
WSSecurity ws = ...
WSSecurityTokenReference str = 
   ws.createSTR_X509_IssuerSerial(cert);
// alternatively use ws.createSTR_X509_SKI(cert) 
// or ws. createSTR_X509_ThumbprintSHA1(cert)

Kerberos tokens can be identified by the SHA1 of the AP_REQ packet or of the GSS wrapped AP_REQ packet.

byte ap_req[] = ...
WSSecurity ws = ...
String valueType = WSSURI.vt_GSSKerberosv5;
WSSecurityTokenReference str = 
   ws.createSTR_KerberosKeyIdSHA1(ap_req, valueType);

SAML assertions can be identified by the Assertion ID.

For local SAML 1.1 assertions use:

WSSecurity.createSTR_SAML_AssertionIdv11(byte assertionId[])

For remote SAML 1.1 assertions use:

createSTR_SAML_AssertionIdv11(
   byte assertionId[], AuthorityBinding authorityBinding)

For local SAML 2.0 assertions use:

createSTR_SAML_AssertionIdv20(byte assertionId[])

For remote SAML 2.0 assertions use a reference URI:

createSTR_SAML_Assertion_Ref20("MySAMLAssertion")

Remote encrypted keys can be identified by their SHA1 hash. Use this function to create the KeyIdentifier:

createSTR_EncKeySHA1(byte sha1[])

An STRTransform is a very useful transform that you add to your signatures. This transform causes a temporary replacement of the STRs wth the corresponding STs while calculating the signature.

For example, you might include an X509 SKI based STR in your reference. Without the STRTransform this will result in only the STR reference being included in the signature,that is, only the SKI value. But if you add an STRTransform, during the signing and verifiing process the STR will be replaced by the actual X509 Certificate, that is, the entire X509 certificate will be included in the message.

Take these steps to sign a SOAP message:

When verifying a signature you first need to locate the signature elements in the <wsse:Security> header; for this you can use the method

WSSecurity ws = ...
List<XSSignature>sigs = ws.getSignatures();

This method searches the DOM tree to find all immediate children of <wsse:Security> that are <dsig:Signature> and then creates XSSignature wrapper objects for each of those elements and returns them. (Note the namespace prefixes do not have to use wsse and dsig).

If you already have the verification key in hand, you can call the following method - either pass in an hmacKey for HMAC signatures or a signingKey for asymmetric key signatures. The SOAPMessage is only need when attachments are signed.

XSSignature sig = sigs[0];
 
byte [] hmacKey = ...
PublicKey signingKey = ... ; // Need either hmacKey of signingKey
 
SOAPMessage msg = null; // needed only for attachments
boolean res = WSSecurity.verify(sig, byte[] hmacKey, signingKey, msg);

However, if you do not have the verification key, you need to set up the following callbacks for resolving STR Key Identifiers. Recall that STR Key Identifiers are usually references to tokens outside the document, so Oracle Security Developer Tools cannot locate these tokens unless you explicitly set up these callbacks.

For tokens that use symmetric keys - UserName Token, Kerberos, and EncryptedKey - you need to set up a resolver, because the document does not have this symmetric key, and Oracle Security Developer Tools cannot verify (or decrypt) unless you set the resolvers.

For tokens that use asymmetric keys - SAML Assertions and X509 Tokens - you do not need to set up a resolver if it uses a direct URI reference STR or an embedded token, because in these cases Oracle Security Developer Tools can locate the certificate on its own. However you still need to set up the CertificateValidator callback because Oracle Security Developer Tools will not blindly use a certificate in the message unless you have validated the certificate in your callback.

After you have set up all the resolvers and the CertificateValidator, use the following method:

SOAPMessage msg = null; // needed only for attachments
boolean searchTokens = true; 
boolean res = WSSecurity.verify(sig, searchTokens, msg);

This method inspects the Signature's KeyInfo and either searches for the certificate, or calls the appropriate resolvers to get the signing key.

You can also use the WSSecurity.verifyAll method which searches for signatures and verifies them one by one.

You use the WSSignatureConfirmation wrapper class to contruct and process signature confirmation elements.

You can encrypt SOAP messages by means of EncryptedKey.

First decide on a key to use to encrypt this random session key, then create an STR with the information that the receiver will use to locate this decryption key:

Key keyEncKey = ... ; WSSecurityTokenReference str = ...

create a WSSEncryptionParams with this information:

// Choose a data encryption algorithm - say AES 128
String dataEncAlg = XMLURI.alg_aes128_CBC;
 
// Either generate a random session key yourself, or set this to 
// null to indicate that OSDT should generate it
SecretKey dataEncKey = null;
 
// Depending on the KeyEncryptionKey that you have chosen choose 
// either an RSA key wrap or a symmetric key wrap
String keyEncAlg = XMLURI.alg_rsaOAEP_MGF1;
 
// Now put all this information into a WSSEncryptionParams
WSSEncryptionParams eParam = new WSSEncryptionParams(
 dataEncAlg, dataEncKey, keyEncAlg, keyEncKey, str);

regular DOM element, SOAP headers, the SOAP Body or AttachmentParts:

Element elem1 = ... // one object to be encrypted
Element elem2 = … // another object to be encrypted
ArrayList objectList[] = new ArrayList();
objectList.add(elem1);
objectList.add(elem2);

Create two more arrays to indicate whether each object is to be encrypted content only, and what IDs will be assigned to the resulting EncryptedData objects:

// both these elements are not content only
boolean[] contentOnlys = { false, false };
 
// After encryption the EncryptedData elements will get these ids
String encDataIds[] = { "id1", "id2" };

Finally, call the encryptWithEncKey method:

WSSecurity ws = ...
XEEncryptedKey encKey = ws.encryptWithEncKey(objectList, contentOnlys, 
 encDataIds, eParam);

Use these steps if you do not wish to use an EncryptedKey:

Decide on a data encryption key; you can either use the same one for all the EncryptedData sections or a different one for each. Also create an STR with the information that the receiver will use to locate this decryption key, and put into a WSSEncryptionParams object:

SecretKey dataEncKey = ... ; // assuming 128 bit AES key
String dataEncAlg = XMLURI.alg_aes128_CBC;
WSSecurityTokenReference str = ...
 
// Now put all this information into a WSSEncryptionParams
WSSEncryptionParams eParam = new WSSEncryptionParams(
 dataEncAlg, dataEncKey, null, null, str);

Now create a list of elements to be encrypted as before, along with the associated contentOnly and encDataIds array:

Element elem1 = ... // one object to be encrypted
Element elem2 = … // another object to be encrypted
ArrayList objectList[] = new ArrayList();
objectList.add(elem1);
objectList.add(elem2);
 
// both these elements are not content only
boolean[] contentOnlys = { false, false };
 
// After encryption the EncryptedData elements will get these ids
String encDataIds[] = { "id1", "id2" };

Finally, call the encryptWithNoEncKey method:

WSSecurity ws = ...
XEEncryptedKey encKey = ws.encryptWithNoEncKey(objectList, 
 contentOnlys, encDataIds, new WSEncryptionParams[]{eParam, eParam});

In this example we used the same encryptionParams for both elements.

When you call the encrypt methods on the SOAP header block , with content only set to false, the entire SOAP header block is encrypted into an EncryptedData element; this element is placed inside an EncryptedHeader element, which replaces the original SOAP header block.

The mustUnderstand and actor attributes are copied over from the current wsse:Security header.

To decrypt SOAP messages with EncryptedKey, use:

WSSecurity.decrypt(XEEncryptedKey, PrivateKey, SOAPMessage)

which first decrypts the EncryptedKey with the given PrivateKey to obtain a symmetric key, then uses this symmetric key to decrypt all the references inside the EncrytedKey.

If you do not know the PrivateKey, call:

decrypt(XEEncryptedKey, SOAPMessage)

which looks into the KeyInfo of the EncryptedKey and calls the registered callbacks to obtain the private key.

If you already know the decrypted form of the EncryptedKey then use:

decrypt(XEEncryptedKey, SecretKey, SOAPMessage)

which uses the given symmetric key to decrypt all the references inside the EncryptedKey.

When you wish to decrypt all the elements (or attachments) mentioned in a top level ReferenceList, use:

decrypt(XEReferenceList, SecretKey, SOAPMessage)

which uses the given symmetric key to decrypt all the references inside the ReferenceList. This functions assumes that all the references are encrypted with the same key.

If you do not know the SecretKey, or if all the references are not encrypted with the same key, send in a null for the SecretKey; decrypt then looks into the KeyInfo of each of the EncrytedData and calls the registered callbacks to obtain the symmetric key.