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  xml:id="foo1">
    ...
  </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.

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.

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

1. choose a random symmetric key,

2. encrypt your data with this key,

3. encrypt this random symmetric key with your asymmetric key, and

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

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

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.

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.

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.

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.

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());

To create a detached signature like this:

<myDoc>
  <importantInfo  xml:id="foo1">
    ...
  </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());

The following topics explain it further:

• Including Multiple References

• Using an Enveloped Signature

• Using an XPath Expression

• Using a Certificate Hint

• Signing with an HMAC Key

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.

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));

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.

// 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
}

The last step is to actually verify the signature. The call protocol depends on whether callbacks are set up.

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);

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
);

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);

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);

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);

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);