8 Oracle XML Security

8.1.1 Supported Algorithms

Oracle Security Developer Tools provide a complete implementation of the XML Signature and XML Encryption specifications, and support these algorithms:

Signature Algorithms

• DSA with SHA1

• RSA with SHA1

• HMAC-SHA1

Digest Algorithms

• MD5

• SHA1

• SHA256

• SHA512

Transforms

• Canonicalization – Canonical XML 1.0, Canonical XML 1.1, exclusive Canonical XML 1.0, (all forms are supported with and without comments)

• XSLT

• XPath Filter

• XPath Filter 2.0

• Base64 Decode

• Enveloped Signature

• Decrypt Transform

Data Encryption Algorithms

• AES-128 in CBC mode

• AES-192 in CBC mode

• AES-256 in CBC mode

• DES EDE in CBC mode

Key Encryption and Key Wrapping Algorithms

• RSAES-OAEP-ENCRYPT with MGF1

• RSAES-PKCS1-v1_5

• AES-128 Key Wrap

• AES-192 Key Wrap

• AES-256 Key Wrap

• DES-EDE Key Wrap

Links to these standards are available in Appendix A, "References".

8.1.2 Oracle XML Security API

This section describes the Oracle XML Security API.

About the Examples in this Chapter

This chapter contains several sections with instructions and examples of API usage.

• Section 8.3, "How Data is Signed"

• Section 8.4, "How Data is Verified"

• Section 8.5, "How Data is Encrypted"

• Section 8.6, "How Data is Decrypted"

The following sections are specific to the Oracle XML Security API:

• Section 8.7, "About Element Wrappers in the Oracle Security Developer Tools XML APIs"

• Section 8.8, "How to Sign Data with the Oracle XML Security API"

• Section 8.9, "How to Verify Signatures with the Oracle XML Security API"

• Section 8.10, "How to Encrypt Data with the Oracle XML Security API"

• Section 8.11, "How to Decrypt Data with the Oracle XML Security API"

8.3.1 Identify What to Sign

The first step is to identify the data that you need to sign and where your signature will be placed.

The most common case of signing is when you are signing a part of a document, and the signature is also placed in the same document. For this you need to decide how you refer to that part. The simplest way is to use an ID, for example:

<myDoc>
  <importantInfo>
    ...
  </importantInfo>
  <dsig:Signature>
    ...
      <dsig:Reference URI="#foo1">
    ...
  </dsig:Signature>
</myDoc>

In this example myDoc is the entire document, of which you only want to sign the <importantInfo> element, and the signature is placed right after the <importantInfo> element. The <importantInfo> has an xml:id attribute, which the Signature uses to refer to it.

xml:id is a generic identifying mechanism.

If your schema does not allow you to add this attribute to your <importantInfo> element, you can instead use an Xpath to refer to it.

<myDoc>
  <importantInfo>
    ...
    <dsig:Signature>
      ...
      <dsig:Reference URI="#foo1">
         ...
         <Transform Algorithm="...enveloped-signature">
         ...
      </dsig:Reference>
      ...
    </dsig:Signature>
    ...
  </importantInfo>
</myDoc>

<myDoc>
  <importantBinaryData>
    XJELGHKLasNDE12KL=
  </importantBinaryData>
  <dsig:Signature>
    ...
      <dsig:Reference URI="#foo1">
         ...
         <Transform Algorithm="...base64">
         ...
      </dsig:Reference>
      ...
  </dsig:Signature>
</myDoc>

8.3.2 Decide on a Signing Key

Once you have decided what to sign, and how to reference it, you need to decide on a signing key. Options include:

• Use a X509Certificate.

  This is the most common mechanism. You sign with the private key, and anybody who has your public key can verify with it.

• Use a raw asymmetric signing key, like a DSA, RSA, or DH key.

  When you are signing with an X509certificate, you are in fact signing with the DSA/RSA/DH signing key that is associated with the certificate. You can also sign with DSA/RSA/DH signing key that is not associated with any certificate, although there is no good reason for doing so.

• Use a symmetric key.

  You can also do HMAC signing with a symmetric key. This is useful when you and the verifier already share a symmetric key; it could be a key derived from a password, or it could be from a kerberos system which uses symmetric keys. The Oracle Security Developer Tools WS Security APIs provide explicit APIs for password-based keys and kerberos keys.

8.5.1 Identify what to Encrypt

The most common encryption scenario is to encrypt and replace. When you are encrypting a part of the document, replacing the document with the encrypted bytes.

For example:

<myDoc>
  <importantInfo>
    ...
  </importantInfo>
</myDoc>

If you encrypt the importantInfo element, it will look like this:

<myDoc>
  <xenc:EncryptedData>
    ...
  </xenc:EncryptedData>
</myDoc>

Here the entire <importantInfo> and all its contents are replaced by an EncryptedData element which essentially contains a large base64 string, which is the base64 encoding of the encrypted <importantInfo> element.

In this mode the <importantInfo> element is completely hidden, and the receiver has no way of knowing the contents until it is decrypted.

<myDoc>
  <importantInfo>
    <xenc:EncryptedData>
      ...
    </xenc:EncryptedData>
  </importantInfo>
</myDoc>

8.5.2 Decide on the Encryption Key

This is very similar to the task of deciding the signing key (see section Section 8.3.2, "Decide on a Signing Key") except that you never directly encrypt with an asymmetric key. Instead, you usually:

• choose a random symmetric key,

• encrypt your data with this key,

• encrypt this random symmetric key with your asymmetric key, and

• send both the encrypted data and encrypted key to the receiver.

Even with a symmetric key, you can still choose to:

• generate a random symmetric key,

• encrypt this random symmetric key with your symmetric key and

• send both the encrypted data key and the encrypted key to the receiver

To use this encrypted key mechanism, you need to decide where to place the xenc:EncryptedKey in your document.

• If you only have one encryptedData element, place the EncryptedKey in the KeyInfo of the EncryptedData.

• Otherwise, place them separately and have one refer to the other.

Use the <dsig:KeyInfo> inside the EncryptedKey to refer to the certificate, asymmetric key, or key name that can be used to decrypt the EncryptedKey.

8.7.1 Construct the Wrapper Object

To construct a wrapper object from the DOM element, simply invoke the constructor.

For example:

Element sigElem =  
   (Element)doc.getElementsByTagNameNS(XMLURI.ns_dsig, "Signature").item(0);
XSSignature sig = new XSSignature(sigElem);

To construct a Wrapper object when the DOM element does not exist, you can either:

• create a DOM element, and use the above method, or

• use a newInstance method

XSSignature sig = XSSignature.newInstance(doc, null);

This internally achieves the same ends, that is, it creates a <dsig:Signature> DOM element, without appending it anywhere, then creates a wrapper object on top of the element. You will need to append this element somewhere in your document.

For some wrapper classes, there is no newInstance method and you need to call a constructor that takes the document object.

XSSignedInfo sigInfo =  new XSSignedInfo(doc, null);

Another way to create the wrapper object from the element is to call the XMLUtils.getInstance method:

XSSignature sig = (XSSignature)XMLUtils.getInstance(sigElem);

The Oracle Security Developer Tools APIs internally maintain a table associating element names to wrapper class names. The XMLUtils.getInstance uses this table to invoke the appropriate constructor and return an instance of that wrapper class.

8.7.2 Obtain the DOM Element from the Wrapper Object

The underlying DOM element is readily available. All wrapper classes extend from XMLElement which provides a method, XMLElement.getElement(), to get the underlying DOM element.

8.7.3 Parse Complex Elements

Whenever there are complex elements containing a hierarchy of subelements, there will also be an equivalent hierarchy of wrapper objects. For example, suppose you have an incoming document containing a signature:

<dsig:Signature>
  <dsig:SignedInfo>
    <dsig:CanonicalizationMethod ... />
     ...
  <dsig:SignedInfo>
  <dsig:SignatureValue>..</dsig:SignatureValue>
  ...  
</dsig:Signature>

Most of these elements have a corresponding wrapper class, such as dsig:Signature -> XSSignature, dsig:SignedInfo -> XSSignedInfo, dsig:SignatureValue -> XSSignatureValue and so on.

But when you construct the XSSignedInfo object from the dsig:Signature DOM element, it does not construct any of the child objects, in fact it does not even look at any of the child elements. The new XSSignature(sigElem) is a quick call which simply creates an object with the data member pointing to the sigElem. The child objects are created every time. So when you call XSSignature.getSignedInfo() it searches the child elements of dsig:Signature to find the dsig:SignedInfo element, constructs a wrapper object on that element, and returns it.

This wrapper object is not stored anywhere. So if you invoke XSSignature.getSignedInfo() again, it does the same thing, returning a different instance of the SignedInfo object; however both these objects point to the same DOM element, so they behave exactly the same way even though they are different instances.

8.7.4 Construct Complex Elements

Consider the same example as before, but now instead of the signature present in an incoming document, you want to create a document containing a signature and send this document to someone.

<dsig:Signature>
  <dsig:SignedInfo>
     ...
  <dsig:SignedInfo>
  ...  
</dsig:Signature>

To construct this complex element, you need to create individual wrapper objects and assemble them using set methods.

For example:

XSSignature sig = XSSignature.newInstance(doc, null);
XSSignedInfo sigInfo = new XSSignedInfo(doc, null);
sig.setSignedInfo(sigInfo);

Remember that the DOM is always the source of truth; the set methods do not store or copy the passed-in wrapper object, they just modify the underlying DOM.

So in this case the setSignedInfo gets the dsig:SignedInfo element, and makes that a child of the dsig:Signature element. So after invoking setSignedInfo(sigInfo), if you do sigInfo = null, it will not affect anything.

Finally you need to insert the top-level object somewhere into your DOM:

elem.appendChild(sig.getElement());

8.8.1 Basic Procedure to Create a Detached Signature

To create a detached signature like this:

<myDoc>
  <importantInfo>
    ...
  </importantInfo>
  <dsig:Signature>
    ...
      <dsig:Reference URI="#foo1">
    ...
  </dsig:Signature>
</myDoc>

You need to do this:

// assume you have your data set up in doc
Document doc = ...
Element impElem = ...
 
// Now put an ID on the importantInfo element
impElem.setAttributeNS(XMLURI.ns_xml, "xml:id", "foo1");
 
// Then get the signing key and certificate from 
// somewhere – e.g. you can load them from a keystore
PrivateKey signKey = ...
X509Certificate signCert = ...
 
// Create the Signature object
XSSignature sig = XSSignature.newInstance(doc, null);
 
// Create the SignedInfo object
// Normally you should use exclusive canonicalization
//    alg_exclusiveC14N
// Depending on the type of your private key DSA or RSA
//    use dsaWithSHA1 or rsaWithSHA1
XSSignedInfo sigInfo = sig.createSignedInfo(
  XMLURI.alg_exclusiveC14N, XMLURI.alg_rsaWithSHA1, null)
sig.setSignedInfo(sigInfo);
 
 
// Create a Reference object to the importantInfo element
// You need to specify the id which you set up earlier, 
//  and also a digestMethod
XSReference ref = sig.createReference(null, "#foo1", null, 
   XMLURI.alg_sha1);
sigInfo.addReference(ref);
// Create an exclusive c14n Transform object
// If you do not add this transform object, it will use 
// inclusive by default
XSAlgorithmIdentifier transform = 
  new XSAlgorithmIdentifier(doc, "Transform", 
  XMLURI.alg_exclusiveC14n);
ref.addTransform(transform);
 
 
// Create a KeyInfo object
XSKeyInfo keyInfo = sig.createKeyInfo();
sig.setKeyInfo(keyInfo);
 
// Create an X509Data element for your signingCert, inside
//  this keyingo
X509Data x509 = keyInfo.createX509Data(signingCert);
keyInfo.addKeyInfoData(x509);
 
// Everything is setup, now do the actual signing
// This will actually do all the canonicalization, 
// digesting, signing etc
sig.sign(signKey, null);
 
// Finally insert the signature somewhere in your document
doc.getDocumentElement().appendChild(sig.getElement());

8.8.2 Variations on the Basic Signing Procedure

Variations on the basic signing procedure include multiple references, enveloped signatures, XPath expressions, certificate hints, and HMAC key signing.

XSAlgorithmIdentifier transform1 = 
  new XSAlgorithmIdentifier(doc, "Transform", 
  XMLURI.alg_envelopedSignature);
ref.addTransform(transform1);

String xpathExpr = "ancestor-or-self:importantInfo";
Element xpathElem = doc.createElementNS(XMLURI.ns_dsig, 
 "dsig:XPath");
xpathElem.appendChild(doc.createTextNode(xpathExpr);
XSAlgorithmIdentifier transform2 = 
  new XSAlgorithmIdentifier(doc, "Transform", 
  XMLURI.alg_xpath);
transform2.addParameter(xpathElem);
ref.addTransform(transform2);

8.9.1 Basic Procedure to Check What is Signed

To verify a signature, first locate the <dsig:Signature> element in your document, then use it to construct the XSSignature wrapper object.

Element sigElem = …
XSSignature sig = new XSSignature(sigElem);

Next, fetch the KeyInfo of the signature and examine the key to determine if you trust the signer. There are different ways to deal with the KeyInfo:

• For very simple cases, you may already know the verification key in advance, and you do not need to look at the KeyInfo at all.

• In most cases, however, you should look at the KeyInfo. One way is to set up callbacks, so when you call XSSignature.verify() you call it with no verification key. Internally, the Oracle Security Developer Tools look at the KeyInfo to see if it invokes a callback to fetch the key.

• The other option is to proactively look into the KeyInfo and determine the key yourself.

8.9.2 Set Up Callbacks

If the KeyInfo Contains the Signing Certificate

If you expect the KeyInfo to contain the signing certificate, and you do not already have this certificate, but you have set up the trust points, you just need to set a certificate validator callback.

// Create your certificate validator
CertificateValidator myValidator 
  = new CertificateValidator() {
  public void validateCert(CertPath cp) {
     // Code to validate the certificate
  }
};
KeyRetriever.setCertificateValidator(myValidator);

The Oracle Security Developer Tools API retrieves the certificate from the KeyInfo and invokes your callback; if the callback returns true, it will verify with that certificate.

If the KeyInfo Contains a Hint

If you expect the KeyInfo to contain only a hint to the signing certificate, that is, the subjectDN or Issuer Serial or subject key identifier, write a KeyRetriever to fetch a certificate from a certificate store given this hint.

If your certificate store is a keystore, a PKCS12 wallet, or a PKCS8 file, you can use one of the built-in retrievers for these types. These retrievers iterate through all the certificates in the keystore or Oracle wallet and find the one which matches the given subjectDN/issuerSerial or SubjectKey.

// Load your keystore
KeyStore ks = 
// Set up a callback against this KeyStore
KeyRetriever.addKeyRetriever(
  new KeyStoreKeyRetriever(ks, passwd));

8.9.3 Write a Custom Key Retriever

If these built in retrievers are not suitable, you can write a custom KeyRetriever by deriving from the KeyRetriever class; for example you could do this when you expect the KeyInfo to contain a subjectDN, and you will look up an LDAP directory to find the certificate for that DN.

KeyRetriever myRetriever = new KeyRetriever() {
   X509Certificate retrieveCertificate (KeyInfoData keyInfo) {
       // write code to fetch the certificate from 
       // the certificate store based on keyInfo
   }
 
   PublicKey retrieveCertificate (KeyInfoData keyInfo) {
       // write code to fetch the PublicKey from 
       // the certificate store based on keyInfo
   }
};
KeyRetriever.addKeyRetriever(myRetriever);

If the signature used the symmetric key, and the KeyInfo has the keyname of that key, write a custom key retriever which can fetch the symmetric key based on this key name.

8.9.4 Check What is Signed

The next step is to check if this signature really signs what you were expecting it to sign. The Oracle Security Developer Tools provide an API to return this information:

// XSSignature has be created as mentioned before
XSSignature sig = ...
 
// at first locate the element that are expecting 
// to be signed
Element impElem = ...
 
// Now check if the signature really signs this
List signedObjects = XMLUtils.resolveReferences(sig);
if (signedObjects.size() != 1 ||
   signedObjects.get(0) != impElem {
   // something is wrong – impElem is not signed by
   // this signature
}

8.9.5 Verify the Signature

The last step is to actually verify the signature.

boolean result = sig.verify();

8.10.1 Encrypt with a Shared Symmetric Key

To encrypt and replace the following <importantInfo> element:

<myDoc>
  <importantInfo>
    ...
  </importantInfo>
</myDoc>

you will need to take the following steps:

// Assuming there is a shared symmetric key
SecretKey dataEncKey = ...
 
// Create a new XEEncryptedData instance 
// use either obj_Element or obj_Content depending
// on whether you want to encrypt the whole element
// or content only
XEEncryptedData ed = XEEncryptedData
    .newInstance(doc, null, XMLURI.obj_Element);
 
// Specify the data encryption method
XEEncryptionMethod em =   
   ed.createEncryptionMethod(XMLURI.alg_aes128_CBC);
ed.setEncryptionMethod(em);
 
// Create a Keyinfo with a hint to the symmetric key
XEKeyInfo ki= ed.createKeyInfo();
ki.addKeyInfoData(ki.createKeyName("MyKey"));
ed.setKeyInfo(ki);
 
// Locate the importantInfo element
Element impElem = ...
 
// Encrypt the importantInfo element and replace
// it with the EncryptedData element
XEEncrytedData.encryptAndReplace(impElem, dataEncKey, 
   null, ed);

A Utility Method for Encryption

There is a utility method which performs all these steps:

XEncUtils.encryptElement(
  impElem,  // element to be encrypted
  false,    // true = contentOnly, false = entire element
  XMLURI.alg_aes128_CBC, // data encryption alg
  "MyKey" // hint to data key
);

8.10.2 Encrypt with a Random Symmetric Key

In Section 8.10.1, "Encrypt with a Shared Symmetric Key", the example made a simplifying assumption that there was a shared symmetric key. In practice, you usually generate a random symmetric key and encrypt with that key, and then encrypt this random symmetric key with the receiver's public key. Here is how you would do that:

// Load up the encryption certificate of the reciever
X509Certificate encCert = ...
 
// Get the reciever's public key from the cert
PublicKey keyEncKey = encCert.getPublicKey();
 
// Then generate a random symmetric key
KeyGenerator keyGen = KeyGenerator.getInstance("AES");
keyGen.init(128);
SecretKey dataEncKey = keyGen.generateKey();
 
// Now create an EncryptedKey object
XEEncryptedKey = new XEEncryptedKey(doc);
 
// set up the key encryption algorithm
XEEncryptionMethod em =   
  ek.createEncryptionMethod(XMLURI.alg_rsaOAEP_MGF1);
em.setDigestMethod(XMLURI.alg_sha1);
ek.setEncryptionMethod(em);
 
// encrypt the random symmetric key with public key
byte[] cipherValue = ek.encrypt(dataEncKey, keyEncKey);
 
// store this cipherValue into ek
XECipherData cd = ek.createCipherData();
cd.setCipherValue(cipherValue);
ek.setCipherData(cd);
 
 
// decide on how you would let the receiver know the
// the key encryption key. We are putting in the 
// entire reciever's certificate
XEKeyInfo kki = ek.createKeyInfo();
kki.addKeyInfoData(kki.createX509Data(encCert);
 
// Now the encrypted key has been set up, let us
// do the data encryption as before
XEncUtils.encryptElement(
  impElem,  // element to be encrypted
  false,    // true = contentOnly, false = entire element
  XMLURI.alg_aes128_CBC, // data encryption alg
  null // No hint to data key
);
 
// Finally we need to put the EncryptedKey inside the
// KeyInfo of the EncryptedData
ed.addKeyInfoData(ek);

A Utility Method for Encryption

There is a utility method which performs all these steps:

XEncUtils.encryptElement (
  impElem,  // element to be encrypted
  false,    // true = contentOnly, false = entire element
  XMLURI.alg_aes128_CBC, // data encryption alg
  dataEncKey, // the random symmetric key that we generated
  XMLURI.alg_rsaOAEP_MGF1, // key encryption alg
  KeyEncKey, // public key that we got from cert
  "RecieverCert" // A hint to the certificate
);

Notice that this utility method puts KeyName in the EncryptedKey's KeyInfo; if you want to pass X509Data instead, pass null for keyEncKeyName and then add the X509Data yourself:

// use utility method to create EncrytedData
XEEncryptedData ed = XEncUtils...
 
// no extract EncryptedKey from it
XEEncryptedKey ek = (XEEncryptedKey)ed.getKeyInfo()
 .getEncryptedKeys().elementAt(0);
 
// Set the keyInfo of the ek
XEKeyInfo kki = ek.createKeyInfo();
kki.addKeyInfoData(kki.createX509Data(encCert);

8.11.1 Decrypt with a Shared Symmetric Key

If you have a shared symmetric key, do the following:

// search for the EncryptedData element
Element edElem = ...
 
// decrypt the data
SecretKey dataDecKey = ...
XEEncrytedData.decryptAndReplace(dataDecKey, edElem, true);

8.11.2 Decrypt with a Random Symmetric Key

If you expect to use a random symmetric key:

// search for the EncryptedData element
Element edElem = ...
 
// decrypt the data
PrivateKey keyDecKey = ...
XEEncUtils.decryptElement(edElem, keyDecKey);

8.12.1 The oracle.security.xmlsec.util.XMLURI Interface

This interface defines URI string constants for algorithms, namespaces, and objects. It uses the following naming convention:

• Algorithm URIs begin with "alg_".

• Namespace URIs begin with "ns_".

• Object type URIs begin with "obj_".

8.12.2 The oracle.security.xmlsec.util.XMLUtils class

This class contains static utility methods for XML and XML-DSIG. Methods frequently used in applications include the createDocBuilder(), createDocument(), toBytesXML(), and toStringXML() methods.