Message Encryption/Decryption Mechanism

1. Web service invocation 
2. Retrieve client's X.509 certificate and private key 
3. Digitally sign message (e.g SOAP body) using private key 
4. Include client application's X.509 certificate in SOAP header as binary security token. 
5. Encrypt message with symmetrical algorithm using a shared key. 
6. Retrieve public key of the service provider's X.509 certificate 
7. Encrypt shared key with asymmetric algorithm using service provider's public key. 
8. Include encrypted shared key in SOAP header 
9. Include reference to Service Provider's certificate in SOAP header.

1. SP SOAP runtime recieves request
2. Identify Service Provider's X.509 certification from reference in SOAP header
3. Retrieve Service Provider's X.509 certificate and keys
4. Decrypt shared key with asymmetric algorithms using private key of certificate
5. Decrypt message with sysmmetric algorithm using shared key
6. Retrieve sender's X.509 public key from binary security token in SOAP header
7. Validate digital signature of message that also authenticate sender
8. Call web service implmentation
9. Process request

Digital Signature Overview

RFC 2828 defines a digital signature as "a value computed with a cryptographic algorithm and appended to a data object in such a way that any recipient of the data can use the signature to verify the data's origin and integrity."

Within the XML document, if a signature is the parent element, then it is an enveloping signature. If it is the child element, it is an enveloped signature. If it is neither of both, then it is called detached signature.

We will use the following XML document as subject for XML digital signing:

<?xml version="1.0" ?>
<account>
 <number>9876543210</number>
 <type>savings</type>
 <branch>main</branch>
 <name>First M Last</name>
</account>

The resulting signed XML document, which the signature is enveloped, is as follow.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<account>
 <number>9876543210</number>
 <type>savings</type>
 <branch>main</branch>
 <name>First M Last</name>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
 <SignedInfo><CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments"/><SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#dsa-sha1"/><Reference URI=""><Transforms><Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/></Transforms><DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/><DigestValue>pc92d1PtOWfWuYcv8KKzI1VomhM=</DigestValue></Reference></SignedInfo>
 <SignatureValue>gQLJpLXZYyay4z3P5so0291bU8hhjlTaKpzOKfKrS87VtuuXwTnATg==</SignatureValue>
 <KeyInfo>
  <KeyValue>
   <DSAKeyValue>
    <P>/KaCzo4Syrom78z3EQ5SbbB4sF7ey80etKII864WF64B81uRpH5t9jQTxeEu0ImbzRMqzVDZkVG9
     xD7nN1kuFw==</P>
    <Q>li7dzDacuo67Jg7mtqEm2TRuOMU=</Q>
    <G>Z4Rxsnqc9E7pGknFFH2xqaryRPBaQ01khpMdLRQnG541Awtx/XPaF5Bpsy4pNWMOHCBiNU0Nogps
     QW5QvnlMpA==</G>
    <Y>x68Jz5Eb/pO6MuNDwhWmSWrgyNN5mvIAYOrvIqf4JzgCll0HvIOXK8Tf1SxrqiYHqPawsqXE0S53
     5LW709Dzcw==</Y>
   </DSAKeyValue>
  </KeyValue>
 </KeyInfo>
</Signature></account>

Java code for signing XML document
Step1: instantiate the document to be signed

  DocumentBuilderFactory dbf = 
   DocumentBuilderFactory.newInstance();
  dbf.setNamespaceAware(true);
  DocumentBuilder builder = dbf.newDocumentBuilder();
  Document doc = builder.parse(inputStream);

Step2: generate public-private key pair

  KeyPairGenerator kpg = KeyPairGenerator.getInstance("DSA");
  kpg.initialize(512);
  KeyPair kp = kpg.generateKeyPair();

Step3: create signing context

  DOMSignContext dsc = new DOMSignContext(kp.getPrivate(),
    doc.getDocumentElement());

Step4: assemble XML signature

  XMLSignatureFactory fac = 
   XMLSignatureFactory.getInstance("DOM");
  // Step4a: create reference
  Reference ref = fac.newReference("", fac.newDigestMethod(
    DigestMethod.SHA1, null), 
    Collections.singletonList(
     fac.newTransform(Transform.ENVELOPED,
     (TransformParameterSpec) null)), null, null);
  // Step4b: create signed info
  SignedInfo si = fac
   .newSignedInfo(fac.newCanonicalizationMethod(
    CanonicalizationMethod.INCLUSIVE_WITH_COMMENTS,
     (C14NMethodParameterSpec) null), fac
     .newSignatureMethod(SignatureMethod.DSA_SHA1, null),
     Collections.singletonList(ref));
  // Step4c: create optional KeyInfo
  // - contains information that enables the recipient
  // to find the key needed to validate the signature
  KeyInfoFactory kif = fac.getKeyInfoFactory();
  KeyValue kv = kif.newKeyValue(kp.getPublic());
  KeyInfo ki = kif.newKeyInfo(Collections.singletonList(kv));
  // Step4d: create XML signature
  XMLSignature signature = fac.newXMLSignature(si, ki);

Step5: generate XML signature

  signature.sign(dsc); // DOM structure will be updated.

Step6: print signed document

  TransformerFactory tf = TransformerFactory.newInstance();
  Transformer trans = tf.newTransformer();
  trans.transform(new DOMSource(doc), new StreamResult(outputStream));

Validating signed document
Step1: instantiate document that contains signature

  DocumentBuilderFactory dbf = 
   DocumentBuilderFactory.newInstance();
  dbf.setNamespaceAware(true);
  DocumentBuilder builder = dbf.newDocumentBuilder();
  Document doc = builder.parse(inputStream);

Step2: Specify the document to be validated

  NodeList nl = doc.getElementsByTagNameNS(XMLSignature.XMLNS, "Signature");
  if (nl.getLength() == 0) {
   throw new IllegalArgumentException
    ("Signature element not found");
  }

Step3: create validation context

  DOMValidateContext valContext = new DOMValidateContext(
    new KeyValueKeySelector(), nl.item(0));

Step4: Unmarshal XML signature

  XMLSignatureFactory factory = 
   XMLSignatureFactory.getInstance("DOM");
  XMLSignature signature = 
   factory.unmarshalXMLSignature(valContext);

Step5: Validate

  return signature.validate(valContext);

Index: KeySelector class definition

 private static class KeyValueKeySelector 
  extends KeySelector {
  public KeySelectorResult select(KeyInfo keyInfo,
    KeySelector.Purpose purpose, 
    AlgorithmMethod method,
    XMLCryptoContext context) 
  throws KeySelectorException {
   if (keyInfo == null) {
    throw new KeySelectorException("Null KeyInfo object!");
   }
   SignatureMethod sm = (SignatureMethod) method;
   List list = keyInfo.getContent();

   for (int i = 0; i < list.size(); i++) {
    XMLStructure xmlStructure = (XMLStructure) list.get(i);
    if (xmlStructure instanceof KeyValue) {
     PublicKey pk = null;
     try {
      pk = ((KeyValue) xmlStructure).getPublicKey();
     } catch (KeyException ke) {
      throw new KeySelectorException(ke);
     }

     // make sure algorithm is compatible with method
     if (algEquals(sm.getAlgorithm(), pk.getAlgorithm())) {
      return new SimpleKeySelectorResult(pk);
     }
    }
   }
   throw 
    new KeySelectorException("No KeyValue element found!");
  }

  // this should also work for key types other than DSA/RSA
  static boolean algEquals(String algURI, String algName) {
   if (algName.equalsIgnoreCase("DSA")
     && algURI.equalsIgnoreCase(SignatureMethod.DSA_SHA1)) {
    return true;
   } else if (algName.equalsIgnoreCase("RSA")
     && algURI.equalsIgnoreCase(SignatureMethod.RSA_SHA1)) {
    return true;
   } else {
    return false;
   }
  }
 }

 private static class SimpleKeySelectorResult 
      implements KeySelectorResult {
  private PublicKey pk;

  SimpleKeySelectorResult(PublicKey pk) {
   this.pk = pk;
  }

  public Key getKey() {
   return pk;
  }
 }

References:

• http://docs.oracle.com/javase/6/docs/technotes/guides/security/xmldsig/XMLDigitalSignature.html
• http://www.xinotes.org/notes/note/753/
• http://docs.oracle.com/javase/6/docs/technotes/guides/security/xmldsig/XMLDigitalSignature.html