1[ 2 { 3 "name": "text", 4 "expr": "doc.Text.String", 5 "expect": "\n\nThe OpenOffice.org XML Security Framework\n\nVersion 1.2.1, March 2005\n\nMichael Mi\n\nTable of Contents\n1. Component Overview\t4\n1.1 SAXWriter\t4\n1.2 SAXParser\t4\n1.3 XMLDocumentWrapper\t4\n1.4 XMLExporter\t4\n1.5 XMLImporter\t5\n1.6 SignatureCreator\t5\n1.7 SignatureVerifier\t5\n1.8 Encryptor\t5\n1.9 Decryptor\t5\n1.10 SAXEventKeeper\t5\n1.11 XMLSignature\t6\n1.12 XMLEncryption\t6\n2. Use Cases\t7\n2.1 Generate A Signature (signature before the signed data)\t7\n2.2 Generate A Signature (signature after the signed data)\t7\n2.3 Generate A Signature (sign detached content)\t8\n2.4 Generate An Encryption\t9\n2.5 Verify A Signature (signature before the signed data)\t9\n2.6 Verify A Signature (signature after the signed data)\t9\n2.7 Verify A Signature (verify detached signature)\t10\n2.8 Do a decryption\t10\n3. Unsupported Features\t12\n4. Work Flow\t14\n4.1 Export a Document\t14\n4.1.1 Preparation\t14\n4.1.2 Export non-security related content\t14\n4.1.3 Export security related content\t14\n4.1.4 Export a new signature\t14\n4.1.5 Export a new encryption\t15\n4.1.6 Export a referenced element\t15\n4.1.7 Buffer SAX events\t15\n4.1.8 Convert SAX events into DOM\t16\n4.1.9 Generate signature\t16\n4.1.10 Generate encryption\t16\n4.1.11 Status feedback\t16\n4.1.12 Clear up\t17\n4.2 Import a Document\t18\n4.2.1 Preparation\t18\n4.2.2 Import non-security related content\t18\n4.2.3 Import security related content\t18\n4.2.4 Import a new signature\t18\n4.2.5 Import a new encryption\t19\n4.2.6 Import a referenced element\t19\n4.2.7 Buffer SAX events\t19\n4.2.8 Verify signature\t19\n4.2.9 Decryption\t19\n4.2.10 Status feedback\t19\n4.2.11 Clear up\t19\n5. Interfaces\t20\n5.1 Existing Interfaces\t20\n5.1.1 XDocumentHandler\t20\n5.1.2 XExporter\t20\n5.1.3 XFilter\t20\n5.1.4 XImporter\t20\n5.1.5 XInitialization\t20\n5.1.6 XParser\t20\n5.2 New Interfaces\t20\n5.2.1 XReferenceResolvedListener\t20\n5.2.2 XReferenceResolvedBroadcaster\t21\n5.2.3 XKeyCollector\t21\n5.2.4 XBlockerMonitor\t21\n5.2.5 XSignatureCollector\t21\n5.2.6 XXMLElementWrapperWrapper\t21\n5.2.7 XXMLDocumentWrapper\t22\n5.2.8 XCompressedDocumentHandler\t23\n5.2.9 XSAXEventKeeper\t23\n5.2.10 XSecuritySAXEventKeeper\t24\n5.2.11 XSignatureCreationResultListener\t24\n5.2.12 XSignatureCreationResultBroadcaster\t25\n5.2.13 XSignatureVerifyResultListener\t25\n5.2.14 XSignatureVerifyResultBroadcaster\t25\n5.2.15 XEncryptionResultListener\t25\n5.2.16 XEncryptionResultBroadcaster\t25\n5.2.17 XDecryptionResultListener\t26\n5.2.18 XDecryptionResultBroadcaster\t26\n5.2.19 XSAXEventKeeperStatusChangeListener\t26\n5.2.20 XSAXEventKeeperStatusChangeBroadcaster\t26\n5.2.21 XMissionTaker\t27\n6. Components\t28\n6.1 XMLDocumentWrapper\t28\n6.2 XMLExporter\t28\n6.3 XMLImporter\t28\n6.4 SAXEventKeeper\t29\n6.5 SignatureCreator\t29\n6.6 SignatureVerifier\t30\n6.7 Encryptor\t30\n6.8 Decryptor\t30\n6.9 XMLSignature\t30\n6.10 XMLEncryption\t31\n7. Solutions\t32\n7.1 Notify Sequence\t32\n7.2 Transfer DOM data\t32\n8. Helper Components\t33\n8.1 SAXHelper\t33\n9. Prototype\t34\n9.1 Program overview\t34\n9.2 File format\t35\n\nComponent Overview\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\nSAXWriter\nThe SAXWriter receives SAX events and writes them into an XML file.\nSAXParser\nThe SAXParser reads an XML file and convert it into SAX events.\nXMLDocumentWrapper\nThe XMLDocumentWrapper is mainly used to buffer SAX events into one of implementation related DOM formats. These resulting buffers will be used to generate/verify signatures and to encrypt/decrypt.\nCurrently, the XMLDocumentWrapper has two implementations: one is based on XMLSec library, its internal DOM data format is XMLDocPtr. The other implementation is based on JSR105, the internal DOM data format is w3c.dom.DOM. More implementations can be added when necessary.\nThe XMLDocumentWrapper's primary controller is the SAXEventKeeper. The SAXEventKeeper can decide whether a SAX event should be buffered, whether a buffer should be released, etc..\nXMLExporter\nThe XMLExporter creates a SAXWriter and converts the document into SAX events.\nWhen there is no security related content, the XMLExporter exports the SAX events directly to the SAXWriter. There are two components on the SAX chain, the XMLExporter, followed by the SAXWriter.\nWhen some security related content (signature or encryption) needs to be generated, the XMLExporter reads the configuration file, and finds out what security library the user currently is using. \nThe XMLExporter creates XMLSec based or JSR105 based an XMLDocumentWrapper component, an XMLSignature component and an XMLEncryption component.\n(Annotation MT 2005/04: There is no configuration file or JSR105 implementation anymore...)\nThen the XMLExporter creates a SAXEventKeeper and inserts the SAXEventKeeper into the middle of the SAX chain. Now, all SAX events generated by the XMLExporter will be transferred to the SAXEventKeeper first. \nWhen a signature needs to be generated, the XMLExporter creates a SignatureCreator and informs the SAXEventKeeper to collect all data, including signed elements, the signature template and the key materials. When an encryption need to be generated, the XMLExporter creates an Encryptor and informs the SAXEventKeeper to collect all data which will be encrypted.\nWhen all security related content is generated, the XMLExporter removes the SAXEventKeeper from the SAX chain.\nXMLImporter\nThe XMLImporter creates a SAXParser to parse a XML file into SAX events, then the XMLImporter converts those SAX events into a document.\nWhen there is no security related content, the XMLImporter directly receives SAX events generated by the SAXParser. There are two components on the SAX chain, the SAXParser, followed by the XMLImporter.\nWhen some security related content (signature or encryption) needs to be handled, the XMLImporter creates a XMLDocumentWrapper component, an XMLSignature component, an XMLEncryption component and a SAXEventKeeper component as the XMLExporter does.\nNow, all SAX events parsed out by the SAXParser will be transferred to the SAXEventKeeper first, then to the XMLImporter. \nWhen a signature needs to be verified, the XMLImporter creates a SignatureVerifier and informs the SAXEventKeeper to collect all related data. When an encryption need to decrypt, the XMLImporter creates an Decryptor and informs the SAXEventKeeper to collect all related data.\nWhen all security related contents are solved, the XMLImporter removes the SAXEventKeeper from the SAX chain.\nSignatureCreator\nThe SignatureCreator monitors the collecting processes for the signed elements, the signature template and the key material. When the collection is done, it invokes a XMLSignature to generate the signature element.\nSignatureVerifier\nThe SignatureVerifier monitors the collecting processes for the signed elements, the signature template and the key material. When finished, it invokes a XMLSignature to verify the signature element.\nEncryptor\nThe Encryptor monitors the collecting processes for both the encryption template and the key material. When finished, it invokes a XMLEncryption to generate the encryption.\nDecryptor\nThe Decryptor monitors the collecting processes for both the encryption template and its key material. When finished, it invokes a XMLEncryption to do the decryption.\nSAXEventKeeper\nThe SAXEventKeeper is a component located in the SAX chain. It receives SAX events from the previous component and forwards them to the next component in the SAX chain. \nMeanwhile, the SAXEventKeeper is also in charge of controlling the XMLDocumentWrapper to buffer/release XML data. For example, to generate a new signature, the SAXEventKeeper will transfer SAX events of the signature template, all signed elements, and the key material element to the XMLDocumentWrapper, and asks the XMLDocumentWrapper to buffer them. When the signature is generated, the SAXEventKeeper asks the XMLDocumentWrapper to release all these buffers.\nWhen some element is not in the final shape, such as a signature template before generated, the SAXEventKeeper will stop forwarding any SAX events starting from that element to the next component in the SAX chain, instead, all these SAX events are transferred to the XMLDocumentWrapper to be buffered temporarily. When this element enters its final shape, all buffered SAX events are forwarded out again.\nXMLSignature\nThe XMLSignature component manipulates the buffered data in XMLDocumentWrapper to do signature calculation and verification.\nThe XMLSignature component accesses the buffered data by using native DOM methods provided by another component. \nThese methods are not UNO based, so this needs the XMLSignature can access the class reference of a particular UNO interface. This problem can be solved through using XUNOTunnel interface. Native calling can save a lot of time, especially when thinking of the Java/C++ UNO bridge.\nThe XMLSignature has two implementations: One is based on XMLSec library, the other is based on JSR105.\nThe XMLSec based implementation is a C implementation, which can directly manipulate the data buffer inside of the XMLSec based XMLDocumentWrapper component.\nThe JSR105 based implementation is a Java one, it can directly manipulate the data buffer in the JSR105 based XMLDocumentWrapper component.\nXMLEncryption\nThe XMLEncryption component is similar to the XMLSignature component, which its functionality is to encrypt and decrypt instead of manipulating signature.\nThe XMLEncryption component accesses the buffered data by using native DOM methods too.\nThe XMLEncryption also has two implementation: One is based on XMLSec library, the other is based on JSR106.\nUse Cases\nGenerate A Signature (signature before the signed data)\nThe XMLExporter transfers SAX events locating before the signature directly to the SAXWriter. There are two components in the SAX chain: the XMLExporter and the SAXWriter.\nWhen the XMLExporter needs to export the Signature element,it creates a SAXEventKeeper, and insert it between the XMLExporter and the SAXWriter as a filter. Now, there are three components in the SAX chain: the XMLExporter, the SAXEvenetKeeper and the SAXWriter.\nThe XMLExporter constructs the signature template. This template is almost a Signature element, but with empty DigestValue elements and empty SignatureValue element.\nThe XMLExporter creates a SignatureCreator for this Signature template. Then it ask the SAXEventKeeper to buffer the following element. Moreover, the XMLExporter asks the SAXEventKeeper to create a blocker on the same element, which prevents the SAXEventKeeper from forwarding the following SAX events to the SAXWriter. \nThe XMLExporter transfers the signature template to the SAXEventKeeper as SAX events.\nThe SAXEventKeeper stop forwarding any SAX event to the SAXWriter.\nThe SAXEventKeeper transfers these SAX events to the XMLDocumentWrapper and asks the XMLDocumentWrapper to buffer this signature template.\nWhen the signature template element is buffered completely, the SAXEventKeeper notifies the collection end to the SignatureCreator.\nSAX events after the signature element are still transferred to the SAXEventKeeper to be buffered.\nBefore the XMLExporter transfers the signed element, it ask the SAXEventKeeper to buffer the following element. Then the XMLExporter transfers this element to the SAXEventKeeper.\nThe SAXEventKeeper transfers these SAX events to the XMLDocumentWrapper and asks the XMLDocumentWrapper to buffer this element. If multiple buffered elements include same data, the SAXEventKeeper will make sure the event is kept in memory once only.\nWhen this element is buffered completely, the SAXEventKeeper notifies the collection end to the SignatureCreator. There might be several notifications for a single signature if the signature contains more than one reference.\nAt the time the SignatureCreator knows both the signed elements and the signature template are collected, it invokes the XMLSignature to do the signature generation.\nInside of the XMLSignature, the DOM tree in the XMLDocumentWrapper is read, and the signature is calculated out. Then the template is filled in with DigestValue content and SignatureValue content.\nThe SignatureCreator asks the SAXEventKeeper to release all buffer data, and also removes the blocker.\nBecause the blocker is removed, the SAXEventKeeper asks the XMLDocumentWrapper to forward all SAX events starting from the signature template to the SAXWriter.\nThe XMLExporter removes the SAXEventKeeper from the SAX chain, and destroy the SAXEventKeeper. Now the SAX events generated by the XMLExporter are transferred directly to the SAXWriter again.\nGenerate A Signature (signature after the signed data)\nThe XMLExporter transfers SAX events locating before the signed element directly to the SAXWriter. There are two components in the SAX chain: the XMLExporter and the SAXWriter.\nBefore the XMLExporter transfers the signed element, it creates a SAXEventKeeper, and insert it between the XMLExporter and the SAXWriter as a filter. Now, there are three components in the SAX chain: the XMLExporter, the SAXEvenetKeeper and the SAXWriter.\nit ask the SAXEventKeeper to buffer the following element. Then the XMLExporter transfers the signed element to the SAXEventKeeper.\nThe SAXEventKeeper tramsfers these SAX events to the XMLDocumentWrapper and asks the XMLDocumentWrapper to buffer this element.\nWhen this element is buffered completely, the SAXEventKeeper hold the collection end notification, because by now, there is no notification listener yet.\nThe XMLExporter removes the SAXEventKeeper from the SAX chain, so SAX events after the signed element are transferred directly to the SAXWriter.\nWhen need to export the Signature element, the XMLExporter connect the SAXEventKeeper to the SAX chain again. \nThe XMLExporter constructs a signature template and creates a SignatureCreator for this Signature template. Then it asks the SAXEventKeeper to buffer the following element, and to create a blocker as well, which prevents the SAXEventKeeper from forwarding the following SAX events to the SAXWriter. \nThe SAXEventKeeper notifies the signed element's collection end to the SignatureCreator.\nThe XMLExporter transfers the signature template to the SAXEventKeeper as SAX events.\nThe SAXEventKeeper stops forwarding any SAX event to the SAXWriter.\nThe SAXEventKeeper transfers SAX events to the XMLDocumentWrapper and asks the XMLDocumentWrapper to buffer this signature template.\nWhen the signature template element is buffered completely, the SAXEventKeeper notifies the collection end to the SignatureCreator.\nAt the time the SignatureCreator knows both the signed elements and the signature template are collected, it invokes the XMLSignature to do the signature generation.\nInside of the XMLSignature, the DOM tree in the XMLDocumentWrapper is read, and the signature is calculated out. Then the template is filled in with DigestValue content and SignatureValue content.\nThe SignatureCreator asks the SAXEventKeeper to release all buffer data, and also removes the blocker.\nBecause the blocker is removed, the SAXEventKeeper asks the XMLDocumentWrapper to forward all SAX events starting from the signature template to the SAXWriter.\nThe XMLExporter removes the SAXEventKeeper from the SAX chain, and destroy the SAXEventKeeper. Now the SAX events generated by the XMLExporter are transferred directly to the SAXWriter again.\nGenerate A Signature (sign detached content)\nThe XMLExporter transfers SAX events locating before the signature directly to the SAXWriter. There are two components in the SAX chain: the XMLExporter and the SAXWriter.\nWhen the XMLExporter needs to export the Signature element,it creates a SAXEventKeeper, and insert it between the XMLExporter and the SAXWriter as a filter. Now, there are three components in the SAX chain: the XMLExporter, the SAXEvenetKeeper and the SAXWriter.\nThe XMLExporter constructs the signature template. This template is almost a Signature element, but with empty DigestValue elements and empty SignatureValue element.\nThe XMLExporter creates a SignatureCreator for this Signature template. Then it ask the SAXEventKeeper to buffer the following element. Moreover, the XMLExporter asks the SAXEventKeeper to create a blocker on the same element, which prevents the SAXEventKeeper from forwarding the following SAX events to the SAXWriter. \nThe XMLExporter transfers the signature template to the SAXEventKeeper as SAX events.\nThe SAXEventKeeper stop forwarding any SAX event to the SAXWriter.\nThe SAXEventKeeper transfers these SAX events to the XMLDocumentWrapper and asks the XMLDocumentWrapper to buffer this signature template.\nWhen the signature template element is buffered completely, the SAXEventKeeper notifies the collection end to the SignatureCreator.\nNow the SignatureCreator invokes the XMLSignature to do the signature generation.\nInside of the XMLSignature, all detached contents are retrieved according their URI attributes, the DOM tree in the XMLDocumentWrapper is also read, and the signature is calculated out. Then the template is filled in with DigestValue content and SignatureValue content.\nThe SignatureCreator asks the SAXEventKeeper to release the buffer data, and also removes the blocker.\nBecause the blocker is removed, the SAXEventKeeper asks the XMLDocumentWrapper to forward all SAX events of the signature template to the SAXWriter.\nThe XMLExporter removes the SAXEventKeeper from the SAX chain, and destroy the SAXEventKeeper. Now the SAX events generated by the XMLExporter are transferred directly to the SAXWriter again.\nGenerate An Encryption\n\u201cGenerating an encryption\u201d has the same procedure with \u201cgenerating a signature\u201d, except that:\nthe signature template is replaced by a encryption template;an encryption template is similar with an EncryptedData element, but the content in the CipherValue element is the plain XML data need to be encrypted, instead of cipher data.\nthe SignatureCreator is replaced by Encryptor.\nA blocker is created at the start tag of the EncryptedData element, instead of on the signature template.\nVerify A Signature (signature before the signed data)\nThe XMLImporter gets SAX events locating before the signature directly from the SAXParser. There are two components in the SAX chain: the SAXParser and the XMLImporter.\nWhen the XMLImporter meets a start tag of a Signature element, it creates a SAXEventKeeper, and insert it between the SAXParser and the XMLImporter as a filter. Now, there are three components in the SAX chain: the SAXParser, the SAXEvenetKeeper and the XMLImporter.\nThe XMLImporter creates a SignatureVerifier. Then it informs the SAXEventKeeper to buffer this signature element starting with current SAX event, which in turn will be used as a signature template.\nDuring receiving the signature element from the SAXParser, the SAXEventKeeper transfers these SAX events to the XMLDocumentWrapper, and asks it to buffer them. Meanwhile, the SAXEvenetKeeper forwards this signature element to the XMLImporter.\nDuring analyzing the Signature element, the XMLImporter gets all references' URIs. \nThe XMLImporter tells the SignatureVerifier how many references inside of that signature.\nWhen the signature template element is buffered completely, the SAXEventKeeper notifies the collection end to the SignatureVerifier.\nThe XMLImporter removes the SAXEventKeeper from the SAX chain, so SAX events after the signature element are transferred from the SAXParser directly to the XMLImporter.\nThe XMLImporter detects the signed element in the SAX events stream according to the reference's URI.\nWhen find the start tag of the signed element, the XMLExporter connect the SAXEventKeeper to the SAX chain again. \nThe XMLImporter asks the SAXEventKeeper to buffer the element starting with the current SAX event. \nDuring receiving the signed element from the SAXParser, the SAXEventKeeper transfers these SAX events to the XMLDocumentWrapper, and asks it to buffer them. Meanwhile, the SAXEvenetKeeper forwards these SAX events to the XMLImporter.\nWhen this element is buffered completely, the SAXEventKeeper notifies the collection end to the SignatureVerifier.\nAt the time the SignatureVerifier knows both the signed elements and the signature template are collected, it invokes the XMLSignature to do the signature verification.\nInside of the XMLSignature, the DOM tree in the XMLDocumentWrapper is read, and the signature is verified.\nThe SignatureVerifier gives the verify result to the XMLImporter, then asks the SAXEventKeeper to release all buffer data.\nThe XMLImporter removes the SAXEventKeeper from the SAX chain, and destroy the SAXEventKeeper. Now the SAX events are transferred from the SAXParser to the XMLImporter directly again.\nVerify A Signature (signature after the signed data)\nThe XMLImporter gets SAX events locating before the signed element directly from the SAXParser. There are two components in the SAX chain: the SAXParser and the XMLImporter.\nWhen the XMLImporter meets a start tag of a signed element, it creates a SAXEventKeeper, and insert it between the SAXParser and the XMLImporter as a filter. Now, there are three components in the SAX chain: the SAXParser, the SAXEvenetKeeper and the XMLImporter.\nThe XMLImporter asks the SAXEventKeeper to buffer the element starting with the current SAX event. \nDuring receiving the signed element from the SAXParser, the SAXEventKeeper transfers these SAX events to the XMLDocumentWrapper, and asks it to buffer them. Meanwhile, the SAXEvenetKeeper forwards these SAX events to the XMLImporter.\nWhen this element is buffered completely, the SAXEventKeeper hold the collection end notification, because by now, there is no notification listener yet.\nThe XMLImporter removes the SAXEventKeeper from the SAX chain, so SAX events after the signed element are transferred from the SAXParser directly to the XMLImporter.\nWhen find the start tag of the signature element, the XMLExporter connect the SAXEventKeeper to the SAX chain again. \nThe XMLImporter creates a SignatureVerifier. Then it informs the SAXEventKeeper to buffer this signature element starting with this SAX event.\nDuring receiving the signature element from the SAXParser, the SAXEventKeeper transfers these SAX events to the XMLDocumentWrapper, and asks it to buffer them. Meanwhile, the SAXEvenetKeeper forwards this signature element to the XMLImporter.\nDuring analyzing the Signature element, the XMLImporter gets all references' URIs. And the XMLImporter make the SignatureVerifier as the signed element' collection end listener. The SAXEventKeeper notifies the signed element's collection end to the SignatureVerifier.\nThe XMLImporter tells the SignatureVerifier how many references inside of that signature.\nWhen the signature element is buffered completely, the SAXEventKeeper notifies the collection end to the SignatureVerifier.\nAt the time the SignatureVerifier knows both the signed elements and the signature template are collected, it invokes the XMLSignature to do the signature verification.\nInside of the XMLSignature, the DOM tree in the XMLDocumentWrapper is read, and the signature is verified.\nThe SignatureVerifier gives the verify result to the XMLImporter, then asks the SAXEventKeeper to release all buffer data.\nThe XMLImporter removes the SAXEventKeeper from the SAX chain, and destroy the SAXEventKeeper. Now the SAX events are transferred from the SAXParser to the XMLImporter directly again.\nVerify A Signature (verify detached signature)\nThe XMLImporter gets SAX events locating before the signature directly from the SAXParser. There are two components in the SAX chain: the SAXParser and the XMLImporter.\nWhen the XMLImporter meets a start tag of a Signature element, it creates a SAXEventKeeper, and insert it between the SAXParser and the XMLImporter as a filter. Now, there are three components in the SAX chain: the SAXParser, the SAXEvenetKeeper and the XMLImporter.\nThe XMLImporter creates a SignatureVerifier. Then it informs the SAXEventKeeper to buffer this signature element starting with current SAX event, which in turn will be used as a signature template.\nDuring receiving the signature element from the SAXParser, the SAXEventKeeper transfers these SAX events to the XMLDocumentWrapper, and asks it to buffer them. Meanwhile, the SAXEvenetKeeper forwards this signature element to the XMLImporter.\nDuring analyzing the Signature element, the XMLImporter gets all references' URIs. Then the XMLImporter notifies the SignatureVerfier that all references are detached contents, instead of same-document elements.\nWhen the signature template element is buffered completely, the SAXEventKeeper notifies the collection end to the SignatureVerifier.\nNow the SignatureVerifier invokes the XMLSignature to do the signature verification.\nInside of the XMLSignature, all detached contents are retrieved according their URI attributes, the DOM tree in the XMLDocumentWrapper is also read, and the signature is verified.\nThe SignatureVerifier gives the verify result to the XMLImporter, then asks the SAXEventKeeper to release all buffer data.\nThe XMLImporter removes the SAXEventKeeper from the SAX chain, and destroy the SAXEventKeeper. Now the SAX events are transferred from the SAXParser to the XMLImporter directly again.\nDo a decryption\n\u201cDoing a decryption\u201d has the same procedure with \u201cverifying a signature\u201d, except that:\nthe signature template is replaced by a encryption template;\nthe SignatureVerifier is replaced by Decryptor\na blocker is created at the EncryptedData element, which is used to prevent the SAXEventKeeper from forwarding the EncryptedData element to the XMLImporter; After the decryption, the EncryptedData element is replaced by the encrypted data, then the blocker is released, all new SAX events can be forwarded.\nwhen the Decryptor releases the buffered data, it also needs to remove the blocker.\nUnsupported Features\nWhen importing, the SAXEventKeeper is between the SAXParser and the XMLImporter in the SAX chain, so logically, any SAX event first reaches the SAXEventKeeper, then the XMLImporter. So when the SAXEventKeeper is blocked, the XMLImporter can't get any SAX event behind the blocking point until the block is released. \nSo the SAXEventKeeper has to know enough information before the blocking's happening to finish the work without the XMLImporter's assisstant. Otherwise, a deadlock status will be reached. For example\n...\n<EncryptedData>\n <KeyInfo RetrieveMethod=\"#key1\"/>\n <CipherData>\n </CipherValue>\n ABV$%AZXS2345RS\n </CipherValue>\n </CipherData>\n</EncryptedData>\n...\n<EncryptedKey>\n <KeyValue>abcd</KeyValue>\n <CipherData>\n </CipherValue>\n @3XXSFSFS\n </CipherValue>\n </CipherData>\n</EncryptedKey>\n...\n\nWhen importing this document, the SAXEventKeeper blocks at the EncryptedData element. The Decryptor waits for the XMLImporter to tell it the key element to decrypt, then the blocking can be released. On the other hand, the XMLImporter will never receive the EncryptedKey element, because the SAX event stream is blocked at the start point of the EncryptoedData element, so the XMLImporter has also no idea about the key.\nBecause of that trouble blocker, the above example can't be supported by current design.\nWhen importing, all unsupported features caused by a trouble blocker include:\nAn encryption with external key material, and the encryption locates before the key material in the XML file.\nThis feature is illustrated by above example.\nAn encryption is signed by a signature, and the encryption locates before the signature in the XML file.\nIn following example, the SAX event stream will be blocked at the CipherData element, because that element needs to be decrypted before forwarded to the XMLImporter. While, the decryption can't be preformed, because this EncryptedData element also signed by the signature, and the signature verification has to be done before any change happens inside the signed element. And the signature verification will never start because the XMLImporter will not create the SignatureVerifier if it can't receive the SAX events of the signature element.\n...\n<EncryptedData id=\u201dsigned\u201d>\n <KeyValue>abcd</KeyValue>\n <CipherData>\n </CipherValue>\n ABV$%AZXS2345RS\n </CipherValue>\n </CipherData>\n</EncryptedData>\n...\n<Signature>\n ...\n <Refrence URI=\u201d#signed\u201d/>\n ...\n</Signature>\n...\n\nAn signature signs on multiple elements, an encryption is included in one signed elements and will be read before at least one signed element.\nIn following example, the signature signs on element A and element B. There is an encryption inside the element A, so the SAX events stream will be blocked at the CipherData element, because that element needs to be decrypted before forwarded to the XMLImporter. But the decryption can't be preformed, because this EncryptedData element is inside a signed element, that signature should be verified first. While that signature will never be verified because the XMLImporter can't collect the last signed element.\n...\n\n<Signature>\n ...\n <Refrence URI=\u201d#signed1\u201d/>\n <Refrence URI=\u201d#signed2\u201d/>\n ...\n</Signature>\n...\n<A id=\u201dsigned1\u201d>\n <EncryptedData id=\u201dsigned\u201d>\n <KeyValue>abcd</KeyValue>\n <CipherData>\n ...\n </CipherData>\n </EncryptedData>\n</A>\n...\n<B id=\u201dsigned2\u201d>\n ...\n</B>\n\n...\n\nWhen any above situation happens, the SAXEventKeeper will buffer all SAX events from the trouble blocker to the end of the document. The trouble blocker will be released when the XMLImporter performs the clearing up function. In this case, no promise can be made for other security related content to be handled correctly.\nWork Flow\nExport a Document\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\nPreparation\nBefore export a document, the XMLExporter create a SAXWriter, which is used to write SAX events in to an XML file.\nExport non-security related content\nFor the non-security related content, the XMLExporter generates SAX events and transfers them directly to the SAXWriter. The current SAX chain includes two components, the XMLExporter and the SAXWriter.\nSecurity related contents include\nnew signature,\nnew encryption,\nreferenced elements, including the signed element for new signature, and the key material element for new signature or new encryption.\nExport security related content\nWhen security related content met, the XMLExporter creates a SAXEventKeeper and inserts it before the SAXWriter. Now the SAX chain includes three components, the XMLExporter, the SAXEventKeeper and the SAXWriter.\nExport a new signature\nFor a new signature, the XMLExporter constructs a signature template. This template is similar with a signature element, but it's DigestValue sub-elements and SignatureValue sub-element are dummy, or with no value inside.\nThe Reference sub-elements of the template include all signed element' Ids. If the signature uses an external key, then the KeyInfo sub-element includes the key material element's Id.\nBefore export the template to the SAXEvenetKeeper, the XMLExporter creates a SignatureCreator.\nThen the XMLExporter asks the SAXEventKeeper to collect following element in the SAX events, or to create a Element Collector (EC). (we call the collected element as the EC's working element.) The EC's owner is set to the SignatureCreator. Here the owner represents the component which the SAXEventKeeper sends collection end notification to.\nBecause the digest values and the signature value are missed in the signature template, the XMLExporter also asks the SAXEventKeeper to stop forwarding following SAX events to the SAXWriter, that is, the XMLExporter creates a blocker in the SAXEventKeeper. (we call the first blocked element, the signature template element in this case, as the blocker's working element.) The blocker's owner is also set to the SignatureCreator. That is to say, the SignatureCreator is responsible for remove the blocker after the new signature generated, then all blocked SAX events are forwarded.\nThen the XMLExporter transfers the signature template to the SAXEventKeeper.\nThe XMLExporter knows exactly whether this signature template takes its key material with itself, or has an external key material. If the key material is inside the template, the XMLExporter informs the SignatureCreator that the key material is included internally. Otherwise, it will create a new EC when exporting that key material, the EC's owner is also set to the SignatureCreator.\nThe XMLExporter is aware on every signed element of this signature. Before exporting these elements, it needs to make additional EC for the SignatureCreator. Moreover, the XMLExporter is responsible to tell the SignatureCreator how many references it will have.\nExport a new encryption\nFor a new encryption, the XMLExporter constructs a encryption template. This template is similar with a EncryptedData element, but the content in the CipherValue element is the plain XML data need to be encrypted, instead of cipher data.\nIf the encryption uses an external key, then the KeyInfo sub-element includes the key material element's Id.\nSimilar with transferring a signature template, before exporting the template, the XMLExporter creates an Encryptor, and an EC for the Encryptor as well.\nThe XMLExporter needs also inform the Encryptor its key material information as to the SignatureCreator.\nA blocker is created right before the EncryptedData element. The content in the CipherData element are the plain XML data which need to be encrypted. This blocker will be released when the encryption is generated.\nExport a referenced element\nFor a referenced element, before exporting them, the XMLExporter creates an EC for every already created SignatureCreator or Encryptor, which has reference on this element.\nIf the XMLExporter thinks there will be some further SignatureCreator/Encryptor, which has reference on this element, in the future SAX events, the XMLExporter will create a EC owned by itself. When that SignatureCreator/Encryptor is met, the XMLExporter will clone its own EC for that SignatureCreator/Encryptor. The reason why doing this is very simple, to ask the SAXEventKeeper to buffer some element, an EC must be created before that element is transferred to the SAXEventKeeper, or else, it will be late. The XMLExporter will release its own EC whenever it thinks there is no further SignatureCreator/Encryptor will reference on that element.\nNext, the XMLExporter transfers the referenced element to the SAXEvenetKeeper.\nBuffer SAX events\nThe SAXEventKeeper Receives SAX events from the XMLExporter. Meanwhile, the SAXEventKeeper will do following actions based on the instructions from the XMLExporter and the current status:\nIf the current received element is asked to be buffered by the XMLExporter, the SAXEventKeeper transfers the SAX events to the XMLDocumentWrapper to buffer them.\nIf the current SAX event stream is blocked, the SAXEventKeeper transfers the SAX events to the XMLDocumentWrapper to buffer them.\nIf neither the stream is blocked nor inside any element's collection, the SAXEventKeeper transfers the SAX events to the next component on the SAX chain without buffering them.\nThere are four kinds of instructions from the XMLExporter, they are:\nadd a element collector (EC):\nwhen the SAXEventKeeper receives this instruction, it will ask the XMLDocumentWrapper buffer all SAX events of following element.\nWhen the element is buffered, the SAXEventKeeper will notify the collection end to the EC's owner.\nremove a element collector:\nwhen the SAXEventKeeper receives this instruction, that means a previous buffered element is not useful any longer, so the SAXEventKeeper informs the XMLDocumentWrapper to release that data. \nAdd a blocker:\nwhen the SAXEventKeeper receives this instruction, it knows that the following element in the SAX events stream can't be forwarded to the next component in the SAX chain. So all SAX events starting from this element need to be blocked in buffer.\nRemove a blocker:\nwhen the SAXEventKeeper receives this instruction, that means a blocker is removed. All buffered SAX events for that blocker can be forwarded to the next component in the SAX chain now.\nWhen several instructions need to buffer the same part of data, the SAXEventKeeper can promise only one copy of data existing in memory.\nConvert SAX events into DOM\nWhen an element needs to be bufferred, the SAXEventKeeper transfer this element to the XMLDocumentWrapper as SAX events. The XMLDocumentWrapper is responsible for converting these SAX events into a DOM tree.\nWhen the XMLDocumentWrapper is initialized, it creates an empty DOM tree, and the root element is the \u201ccurrent element\u201d.\nWhen a startElement event received, the XMLDocumentWrapper creates a new element, and this element becomes the \u201ccurrent element\u201d, all following SAX events should be under this element.\nWhen a endElement event received, the \u201ccurrent element\u201d changes to its parent element.\nWhen other events received, new nodes will be created under the \u201ccurrent element\u201d.\nSo, the XMLDocumentWrapper will always hold a \u201ccomplete\u201d DOM tree no matter what segment of SAX events have been received.\nGenerate signature\nWhen the SignatureCreator gets all signed elements, key material and signature template are buffered, it invokes the XMLSignature component to generate the signature.\nThe XMLSignature directly access the DOM tree inside of the XMLDocumentWrapper component, and fills in the DigestValue elements and the SignatureValue element in the signature.\nAfter that, the SignatureCreator asks the SAXEventKeeper to release all EC and blocker.\nGenerate encryption\nWhen the Encryptor gets both the encryption template and the key material bufferred, it invokes the XMLEncryption component to generate the encryption.\nThe XMLEncryption directly access the DOM tree inside of the XMLDocumentWrapper component, and encrypt the plain XML data in the CipherData element into cipher data.\nAfter that, the Encryptor asks the SAXEventKeeper to release all EC and blocker.\nStatus feedback\nThe SAXEventKeeper will give the XMLExporter its current status, based on the status, the XMLExporter can adopt different actions.\nThe feedback status includes:\nEnter element collection. It tells the XMLExporter that the SAXEventKeeper just began to collect an element, so following SAX events are required by the SAXEventKeeper for this element's collection.\nLeave element collection. It tells the XMLExporter that the SAXEventKeeper just left any element collection, following SAX events don't belong to any element need to be collected.\nEnter blocking. It tells the XMLExporter that a blocker is just created, so all SAX events starting from that blocker's working element can't be forwarded and have to be buffered temporarily. That blocker's working element is also called the blocking element.\nLeave blocking. It tells the XMLExporter that the last blocker is just removed, and all temporarily buffered SAX events have been forwarded.\nBuffer empty. It tells the XMLExporter that all buffered data are released in the SAXEventKeeper, that is to say, the SAXEventKeeper is meaningless for existing.\n\nWhen receiving above notification, the XMLExporter will adopt different actions.\nWhen the XMLExporter receives the buffer empty notification, it removes the SAXEventKeeper from the SAX chain and destroys it. Following SAX events will be transferred to the SAXWriter. Everything looks like before no security related contents happened.\nIf neither in blocking status nor in element collection status, the XMLExporter will transfer following SAX events to the SAXWriter, otherwise, to the SAXEventKeeper.\nAfter change transfer to the SAXWriter, when the XMLExporter finds any security related content again, it has to change its transfer back to the SAXEventKeeper again.\nClear up\nAlthough it is rarely to happen, the SAX events exported by the XMLExporter may include error. For instance, the signed element doesn't exist in the SAX events. The direct result from this kind of error is that the SAXEventKeeper can still buffer or block something after all SAX events are passed. So in this situation, there must be some mechanism to promise the SAXEventKeeper can reach empty status in the end.\nWhen the XMLExporter finished transferring all SAX events, it asks every SignatrueCreator and Encryptor to do clear-up function.\nWhen a SignatureCreator or Encryptor receives the clear-up message, it will release all unreleased ECs or blocker if there is any. \nThe XMLExporter will also release all ECs owned by itself.\nIn this way, the SAXEventKeeper will reach the buffer empty status finally.\nImport a Document\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\nPreparation\nBefore importing a document, the XMLImporter creates a SAXParser, which is used to parse an XML file into SAX events.\nImport non-security related content\nFor the non-security related content, the XMLImporter receives SAX events directly from the SAXParser. The current SAX chain includes two components, the SAXParser and the XMLImporter.\nSecurity related contents include\nsignature, i.e., the Signature element,\nencryption, i.e., the EncryptedData element,\nreferenced elements, including the signed element for any signature, and the key material element for signature and encryption.\nImport security related content\nWhen security related content met, the XMLImporter creates a SAXEventKeeper and inserts it behind the SAXParser. Now the SAX chain includes three components, the SAXParser, the SAXEvenetKeeper and the XMLImporter.\nImport a new signature\nWhen the XMLImporter receives the start tag of a Signature element, it create a SignatureVerifier. Then the XMLImporter asks the SAXEventKeeper to create an EC for the current element, the EC's owner is set to the SignatureVerifier.\nThe XMLImporter analyzes the signature during receiving its SAX events. Through which, it can figure out the reference number, every reference's URI, and ,if there is, the external key material's URI. \nThe XMLImporter tells the SignatureVerifier how many references it will have and the key material's information.\nAfter the XMLImporter gets all reference's URI and the key's URI, it will detect them in the SAX event stream.\nImport a new encryption\nWhen the XMLImporter receives the start tag of a EncryptedData element, it create a Decryptor. Then the XMLImporter asks the SAXEventKeeper to create an EC for the current element, the EC's owner is set to the Decryptor.\nThe XMLImporter asks the SAXEventKeeper to create a blocker before the EncryptedData element. The content in the CipherData sub-element are the cipher data which need to be decrypted. This blocker will be removed when the cipher data is decrypted.\nThe XMLImporter analyzes the encryption during receiving it. Through which, it can figure out the key material the encryption uses. The XMLImporter tells the Decryptor the key material's information, and moreover, if this encryption uses an external key material, the XMLImporter will detect it in the SAX event stream by its URI. \nImport a referenced element\nWhen the XMLImporter receives the start tag of any element, it will first evaluate whether this element is referenced or not.\nIf this element is already referenced by some received signature or encryption, or if this element, the XMLImporter thinks, will be referenced by any further signature or encryption, ECs will be created.\nFor each received signature or encryption, an EC is created for it. If the XMLImporter thinks this element will be further referenced, the XMLImporter will create an EC owned by itself. When any further SignatureCreator/Encryptor referencing on this element is found, the XMLImporter will clone its own EC for that SignatureCreator/Encryptor.\nThe XMLImporter will release its own EC whenever it thinks there will be no further reference on it.\nBuffer SAX events\nThe SAXEventKeeper receives SAX events from the SAXParser. It will manipulate EC and blocker as in the exporting case. The XMLImporter will give the SAXEventKeeper instructions.\nVerify signature\nWhen the SignatureVerifier knows all the Signature element, signed elements and its key material are buffered, it invokes the XMLSignature to verify the signature.\nThe XMLSignature directly accesses the DOM tree inside of the XMLDocumentWrapper and verifies the signature.\nAfter that, the SignatureVerifier asks the SAXEventKeeper to release all ECs.\nThen, the SignatureVerifier informs the XMLImporter about the verify result.\nDecryption\nWhen the Decryptor knows both the EncryptedData element and its key material are buffered, it invokes the XMLEncryption to decrypt the encryption.\nThe XMLEncryption directly accesses the DOM tree inside of the XMLDocumentWrapper and replaces the whole EncryptedData element with the plain decrypted data.\nAfter that, the Decryptor asks the SAXEventKeeper to destroy all EC and blocker.\nThen, the Decryptor informs the XMLImporter about the decryption result.\nStatus feedback\nSame with exporting case, the SAXEventKeeper will give the XMLImporter its current status, and based on the status, the XMLImporter adopts corresponding actions.\nClear up\nWhen it knows the SAXParser has transferred all SAX events, the XMLImporter asks every SignatrueVerifier and Decryptor to do clear-up function.\nEvery SignatureVerifier and Decryptor will release its unreleased ECs or blocker if there is any. \nThe XMLImporter will also release all ECs owned by itself.\nInterfaces\nExisting Interfaces\nXDocumentHandler\nvoid startDocument()\nvoid endDocument()\nvoid startElement( string aName, XAttributeList xAttribs )\nvoid endElement( string aName )\nvoid characters( string aChars )\nvoid ignorableWhitespace( string aWhitespaces )\nvoid processingInstruction( string aTarget, string aData )\nvoid setDocumentLocator( XLocator xLocator )\nXExporter\nvoid setSourceDocument(XComponent xDoc)\nXFilter\nboolean filter(sequence<PorpertyValue> aDescriptor)\nvoid cancel()\nXImporter\nvoid setTargetDocument(XComponent xDoc)\nXInitialization\nvoid initialize(any[] aArguments)\nXParser\nvoid parseStream(InputSource strucInputSource )\nvoid setDocumentHandler(XDocumentHandler xHandler )\nvoid setErrorHandler(XErrorHandler xHandler )\nvoid setDTDHandler(XDTDHandler xHandler )\nvoid setEntityResolver(XEntityResolver xResolver )\nvoid setLocale(Locale locale )\n\nNew Interfaces\nXReferenceResolvedListener\nThe XReferenceResolvedListener interface is supported by the SignatureCreator component, the SignatureVerifier component, the Encryptor component and the Decryptor component. It is used to get notification when a particular element is collected.\nThe referenceResolved method is used to notify an element's collection end.\nMethod list:\nvoid referenceResolved(long id)\nthe id parameter is id of the EC working on the collected element.\nXReferenceResolvedBroadcaster\nThe XReferenceResolvedBroadcaster interface is supported by the SAXEventKeeper component, which is used to add/remove reference resolved listener on particular element collector.\nThe addReferenceResolvedListener method adds a reference resolved listener on an EC.\nThe removeReferenceResolvedListener method remove a reference resolved listener from an EC.\nBy now, one EC can has only one reference resolved listener on it.\nMethod list:\nvoid addReferenceResolvedListener(long referenceId, XReferenceResolvedListener listener)\nvoid removeReferenceResolvedListener(long referenceId, XReferenceResolvedListener listener)\nXKeyCollector\nThe XKeyCollector interface is supported by the SignatureCreator component, the SignatureVerifier component, the Encryptor component and the Decryptor component. It is used to tell the interface provider whether or not there is an independent key element's EC for it.\nMethod list:\nvoid setKeyId(long id)\nThe setKeyId method is used to tell the key element EC's id, if the id parameter is set to 0, it represents there is no independent key for the interface provider, and the key information has been already involved in the Signature or EncryptedData element, otherwise, the id parameter is the key element EC's id.\nXBlockerMonitor\nThe XBlockerMonitor interface is supported by the SignatureCreator component, the Encryptor component and the Decryptor component. It is used to tell the interface provider which blocker is helping to block the SAX event stream, and in turn, the interface provider will be responsible for remove this blocker.\nThe setBlockerId method is used to configure the id of the blocker.\nMethod list:\nvoid setBlockerId(long id)\nXSignatureCollector\nThe XSignatureCollector interface is supported by the SignatureCreator component and the SignatureVerifier component, which is used to receive information about the signature element.\nThe setReferenceNumber method is used to tell the interface provider the reference number in this signature element. \nThe setReferenceId method is used to tell the interface provider every reference EC's id. \nMethod list:\nvoid setReferenceCount(long count)\nvoid setReferenceId(long id)\nXXMLElementWrapperWrapper\nThe XXMLElementWrapperWrapper interface is supported by the XMLElementWrapper component, which is used to encapsulate an native element data, such as w3c.dom.DOM, or xmlNodePtr.\nThere is no method in this interface, the component supporting this interface can only be used as an object after conversion from interface to class instance.\nXXMLDocumentWrapper\nThe XXMLDocumentWrapper interface is supported by the XMLDocumentWrapper component, which is used to manipulate the buffered SAX events.\nSome methods are used to convert a SAX event into a DOM format, including all inherited methods from the XDocumentHandler interface.\nSome methods are used to get particular information from the XML tree. \nThe getCurrentElement return the current element node.\nThe setCurrentElement method is used to set the current element if it is changed outside the interface provider.\nThe removeCurrentElement method is used to remove the current element, and set the current element to its parent element.\nThe isCurrent method judges whether a particular node is the current element node.\nThe isCurrentElementEmpty method judges whether the current element has no children.\nThe getNodeName method returns name of the particular element.\nA few methods can perform more complex functions, which in fact is only meaningful for the SAXEvenetKeeper component to operate the buffered data. These methods include:\nthe clearUselessData method: this method remove all content inside a particular element, except reserving some assigned children along with their ancestor path. Moreover, a stop point can be specified to stop the removal.\nthe collapse method: this method delete a particular element, if this node has no content inside, after that, that node's parent node will be processed in the same way until an non-empty element is met.\nthe getTree method: this method export the whole dom tree through an assigned XdocumentHandler interface. This methods is only for debug purpose.\nThe generateSAXEvent method is used to convert part of the XML tree into SAX events stream.\nMethod list:\nXXMLElementWrapperWrapper getCurrentElement()\nvoid setCurrentElement(XXMLElementWrapperWrapper element)\nvoid removeCurrentElement()\nboolean isCurrent(XXMLElementWrapperWrapper node)\nboolean isCurrentElementEmpty();\nString getNodeName(XXMLElementWrapperWrapper node);\nvoid clearUselessData(XXMLElementWrapperWrapper node, sequence<XXMLElementWrapperWrapper> reservedDescendants, XXMLElementWrapperWrapper stopAtNode)\nThe node parameter is the element to be cleared.\nThe stopAt parameter is the node before whose path information will be deleted the removal should stop. \nThe reservedDescendants parameter is all nodes sorted in tree order which need to reserved along with their ancestor path.\nWhen the stopAt parameter is null, then the removal will spread all through the element.\nA typical example is after some EC/blocker is removed, this method is called with the node is set to that EC/blocker's working element, and the stopAt is set to the current blocker's working element, and the reservedDescendants includes all working element inside the node. After this call, all useless buffer data generated by the EC/blocker's removal are deleted from the buffer tree.\nvoid collapse(XXMLElementWrapperWrapper node)\t\t\nvoid generateSAXEvents(XDocumentHandler handler, XSAXEventKeeper saxEventKeeper, XXMLElementWrapperWrapper startNode, XXMLElementWrapperWrapper endNode)\nthe handler parameter is the document handler to receive SAX events.\nThe startNode and the endNode parameters are the two boundary nodes along tree order, between which SAX events need to be generated on.\nThe saxEventKeeper is the SAXEventKeeper who calls this method. Some SAXEventKeeper's methods need to be called during generating SAX events.\nvoid getTree(XDocumentHandler handler)\n\nXCompressedDocumentHandler\nThe XCompressedDocumentHandler interface is supported by XMLDocumentWrapper component, which is used to receive SAX events in a relativly efficient way.\nActually, this interface has the same functionality with the XDocumentHandler interface, the only difference is that there is less data transfer when using this interface instead of the standard XDocumentHandler. This is very pratical when considering Java/C++ calling.\nvoid _startDocument()\nvoid _endDocument() \nvoid _startElement( String aName, sequence< XMLAttribute > aAttributes)\nthe parameters name is the same with startElement method in XDocumentHandler method, while the aAttributes parameter is an attribute array instead of an interface. \nWhen this method is called, a new element is created under the current element node, then the new element become the new current element node.\nvoid _endElement(String localName)\nthe parameters are the same with endElement method in XDocumentHandler method.\nWhen this method is called, the current element's parent become the new current element.\nvoid _characters(String aChars)\nthe parameters are the same with startElement method in XDocumentHandler method.\nWhen this method is called, a new text node is created under the current element node.\nvoid _processingInstruction(String target, String data)\nthe parameters are the same with startElement method in XDocumentHandler method.\nWhen this method is called, a new PI node is created under the current element node.\nvoid _ignorableWhitespace(String aWhitespaces ) \nthe parameters are the same with startElement method in XDocumentHandler method.\nWhen this method is called, the aWhitespaces is processed as standard characters.\nvoid _setDocumentLocator( long columnNumber, long lineNumber, string publicId, string systemId)\nfour parameters are used to replace the Xlocator interface parameter in the original setDocumentLocator method of the XdocumentHandler interface.\nXSAXEventKeeper\nThe XSAXEventKeeper interface is supported by SAXEventKeeper component, which is used to implement element collection and blocking.\nThere are two method categories.\nOne category is for EC, including:\nthe addElementCollector method is used to create a EC on the current element.\nThe removeElementCollector method is used to remove an EC.\nThe getElement method is used to get the buffered element.\nThe setElement method is used to update an element if that element is modified outside of the interface provider's control.\nA tapical example is that when an decryption is finished, the EncryptedData element has already been removed, and a new decrypted element is added to the original position. Then this method is called to synchornize all pointer pointing to the EncryptedData element to the new element.\n\nThe other category is for blocker, including:\nthe addBlocker method is used to create a blocker on the current element. This blocker will prevent the SAXEventKeeper from forwarding following SAX events to the downstream component.\nThe removeBlocker method is used to remove a blocker. Now all blocked SAX events by this blocker can be forwarded again.\nThe isBlocking method returns whether or not the SAXEventKeeper is blocked currently.\nThe getCurrentBlockingNode method returns the node which it is currently blocking at.\n\nThe setNextHandler method is used to configure the next component in the SAX chain, all following SAX events will be forwarded to the new configured handler.\nThe printBufferNodeTree method is used to convert internal data into a string. This method is only for debug purpose.\nMethod list:\nlong addElementCollector()\nThe return value is the EC's id, which can be used in following functions.\nremoveElementCollector(long id)\nthe id parameter is the id of the EC to be destroyed.\nAny getElement(long id)\nvoid setElement(long id, XXMLElementWrapperWrapper aElement)\nlong addBlocker()\nvoid removeBlocker(long id)\nboolean isBlocking()\nXXMLElementWrapperWrapper getCurrentBlockingNode()\nXDocumentHandler setNextHandler(XDocumentHandler nextHandler)\nthe return value is the old handler.\nString printBufferNodeTree()\nXSecuritySAXEventKeeper\nThe XSecuritySAXEventKeeper interface is derived from the XSAXEventKeeper interface, and more security related methods are added.\nThe XSecuritySAXEventKeeper interface is supported by the SAXEventKeeper component.\nThe addElementCollector method is used to add a EC with specified priority and the suppressInternalNotification flag. \nThe cloneElementCollector method is used to clone a already created EC.\nThe setSecurityId method is used to configure the security id to a EC or blocker. The security id is used to detect whether different EC/blocker belongs to the same signature or encryption. (this is specially useful when check enveloped signature.)\nMethod list:\nlong addElementCollector(long priority, boolean suppressInternalNotification)\nthe priority parameter represents this EC's priority. When more than one EC working on the same element, it needs a priority to arrange the notify sequence. For example, when exporting, if an EncryptedData element is also signed by a signature, then the EC for the encryption template must be first notified, the EC for the signed element can only be notified after the encryption template is released (which means the encryption is generated).\nThe \u201csuppressInternalNotification\u201d flag represents whether this EC \u201csuppresses Internal EC's notification\u201d. For example, when exporting, a key material's EC should has this flag with true, because some key material's EC includes another key string inside as another encryption template EC, so the outer key material's EC must be notified first before the internal key string is ciphered.\nlong cloneElementCollector(long referenceId, long priority, boolean suppressInternalNotification)\nthe referenceId parameter is the id of an already created EC, the return value is the id of a new cloned EC.\nThe priority and suppresInternalNotification parameters are the same with the addElementCollector method.\nvoid setSecurityId(long id, long securityId)\nthe id parameter is the id of the EC to be configured.\nXSignatureCreationResultListener\nThe XSignatureCreationResultListener interface is supported by the XMLExporter component, which is used to get the result of signature creation.\nThe signatureCreated method give the creation result for a particular signature.\nMethod list:\nvoid signatureCreated(long signatureId, SecurityOperationStatus creationResult)\nthe signatureId parameter is the security id, and the creationResult parameter is the creation result.\nXSignatureCreationResultBroadcaster\nThe XSignatureCreationResultBroadcaster interface is supported by the SignatureCreator component, which is used to add/remove signature creation result listener.\nThe addSignatureCreationResultListener method adds a signature creation result listener.\nThe removeSignatureCreationResultListener method remove a signature creation result listener.\nBy now, one SignatureCreator can has only one signature verify result listener.\nMethod list:\nvoid addSignatureCreationResultListener(XSignatureCreationResultListener listener)\nvoid removeSignatureCreationResultListener(XSignatureCreationResultListener listener)\nXSignatureVerifyResultListener\nThe XSignatureVerifyResultListener interface is supported by the XMLImporter component, which is used to get signature verify result.\nThe signatureVerified method give the verify result for a particular signature.\nMethod list:\nvoid signatureVerified(long signatureId, SecurityOperationStatus verifyResult)\nthe signatureId parameter is the security id, and the verifyResult parameter is the verify result.\nXSignatureVerifyResultBroadcaster\nThe XSignatureVerifyResultBroadcaster interface is supported by the SignatureVerifier component, which is used to add/remove signature verify result listener.\nThe addSignatureVerifyResultListener method adds a signature verify result listener.\nThe removeSignatureVerifyResultListener method remove a signature verify result listener.\nBy now, one SignatureVerifier can has only one signature verify result listener.\nMethod list:\nvoid addSignatureVerifyResultListener(XSignatureVerifyResultListener listener)\nvoid removeSignatureVerifyResultListener(XSignatureVerifyResultListener listener)\nXEncryptionResultListener\nThe XEncryptionResultListener interface is supported by the XMLExporter component, which is used to get decryption result.\nThe encrypted method give the encryption result for a particular encryption.\nMethod list:\nvoid encrypted(long securityId, SecurityOperationStatus encryptionResult)\nthe securityId parameter is the security id, and the encryptionResult parameter is the encryption result.\nXEncryptionResultBroadcaster\nThe XEncryptionResultBroadcaster interface is supported by the Encryptor component, which is used to add/remove encryption result listener.\nThe addEncryptionResultListener method adds a encryption result listener.\nThe removeEncryptionResultListener method remove a encryption result listener.\nBy now, one Encryptor can has only one encryption result listener.\nMethod list:\nvoid addEncryptionResultListener(XEncryptionResultListener listener)\nvoid removeEncryptionResultListener(XEncryptionResultListener listener)\nXDecryptionResultListener\nThe XDecryptionResultListener interface is supported by the XMLImporter component, which is used to get decryption result.\nThe decrypted method give the decryption result for a particular encryption.\nMethod list:\nvoid decrypted(long securityId, SecurityOperationStatus decryptionResult)\nthe securityId parameter is the security id, and the decryptionResult parameter is the verify result.\nXDecryptionResultBroadcaster\nThe XDecryptionResultBroadcaster interface is supported by the Decryptor component, which is used to add/remove decryption result listener.\nThe addDecryptionResultListener method adds a decryption result listener.\nThe removeSignatureVerifyResultListener method remove a decryption result listener.\nBy now, one Decryptor can has only one decryption result listener.\nMethod list:\nvoid addDecryptionResultListener(XDecryptionResultListener listener)\nvoid removeDecryptionResultListener(XDecryptionResultListener listener)\nXSAXEventKeeperStatusChangeListener\nThe XSAXEventKeeperStatusChangeListener interface is supported by the XMLExporter and the XMLImporter component, which is used to notify the SAXEventKeeper's status.\nThe blockingStatusChanged method informs the switch of the blocking status.\nThe collectionStatusChanged method informs the switch of the collection status.\nThe bufferStatusChanged method informs whether or not the current SAXEventKeeper's buffer is empty.\nMethod list:\nvoid blockingStatusChanged(boolean isBlocking)\nif the isBlocking parameter is true, that represents the SAXEventKeeper just became blocking; otherwise, the SAXEvenetKeeper just leave blocking.\nvoid collectionStatusChanged(boolean isInsideCollectedElement)\nif the isInsideCollectedElement is true, that represents the SAXEvenetKeeper just entered element collection;otherwise, the SAXEventKeeper just left element collection.\nvoid bufferStatusChanged(boolean isBufferEmpty)\nif the isBufferEmpty is true, that represents the SAXEventKeeper just delete its last buffer data, now the SAXEventKeeper includes nothing.\nXSAXEventKeeperStatusChangeBroadcaster\nThe XSAXEventKeeperStatusChangeBroadcaster interface is supported by the SAXEventKeeper component, which is used to add/remove SAXEventKeeper status change listener.\nThe addXSAXEventKeeperStatusChangeListener method adds a SAXEventKeeper status change listener.\nThe removeXSAXEventKeeperStatusChangeListener method remove a SAXEventKeeper status change listener.\nBy now, one SAXEventKeeper can has only one status change listener.\nMethod list:\nvoid addXSAXEventKeeperStatusChangeListener(XSAXEventKeeperStatusChangeListener listener)\nvoid removeXSAXEventKeeperStatusChangeListener(XSAXEventKeeperStatusChangeListener listener)\nXMissionTaker\nThe XMissionTaker interface is supported by the SignatureCreator component, the SignatureVerifier component, the Encryptor component and the Decryptor component. It is used to force to end a mission.\nThe endMission method is used to force the interface provider to end its mission. Because there is possibility that a Signature element can't be verified, or a encryption data can't be decrypted, so this method is used to stop current mission and release all related resources, including EC and blocker.\nMethod list:\nboolean endMission()\nthe return value represents whether or not the mission is accomplished successfully.\nComponents\nXMLDocumentWrapper\nFunctions\nConvert SAX events into DOM format.\nManipulate buffered data according to SAXEventKeeper's instruction.\nConvert DOM format back to SAX events on demand.\nInterfaces\nXXMLDocumentWrapper\nXMLExporter\nFunctions\nCreate a XMLDocumentWrapper according to configuration.\nCreate a XMLSignature according to configuration.\nCreate a XMLEncryption according to configuration.\nReceive the status change of the SAXEventKeeper\nAdjust the SAX chain to include or exclude the SAXEventKeeper as a output filter.\nConvert an internal document into SAX event stream.\nCreate a SignatureCreator for new Signature elements to be created.\nCreate a Encryptor for new EncryptedData elements to be created.\nAsk the SAXEventKeeper to create ECs.\nAsk the SAXEventKeeper to create blocker.\nAssign owner for EC.\nAssign owner for blocker.\nReserve signature creation results.\nReserve encryption result.\nInterfaces\nXInitialization\nXExporter\nXFilter\nXSAXEventKeeperStatusChangeListener\nXSignatureCreationResultListener\nXEncryptionResultListener\nXMLImporter\nFunctions\nCreate a XMLDocumentWrapper according to configuration.\nCreate a XMLSignature according to configuration.\nCreate a XMLEncryption according to configuration.\nReceive the status change of the SAXEventKeeper\nAdjust the SAX chain to include or exclude the SAXEventKeeper as a output filter.\nConvert SAX event stream into an internal document.\nJudge whether an element should be signed somewhere or not.\nJudge whether an element should be key material for other stuff.\nCreate SignatureVerifier objects to verify Signature element.\nCreate Decryptor objects to do decryption.\nAsk the SAXEventKeeper to create ECs.\nAsk the SAXEventKeeper to create blocker.\nAssign owner for EC.\nAssign owner for blocker.\nReserve verify results.\nReserve decryption result.\nInterfaces\nXImporter\nXDocumentHandler\nXSignatureVerifyResultListener\nXDecryptionResultListener\nXSAXEventKeeperStatusChangeListener\nSAXEventKeeper\nFunctions\nControl the XMLDocumentWrapper to manipulate the buffer data.\nManipulate ECs.\nManipulate blockers.\nNotify EC's collection end.\nBroadcast SAXEvenetKeeper's status change.\nInterfaces\nXDocumentHandler\nXSAXEventKeeper\nXSecuritySAXEventKeeper\nXReferenceResolvedBroadcaster \nXSAXEventKeeperStatusChangeBroadcaster\nSignatureCreator\nFunctions\nMonitor the collection of signed elements, key material and signature template.\nInvoke signature generation.\nClear up involved EC and blocker.\nInterfaces\nXReferenceResolvedListener\nXSignatureCollector\nXBlockerMonitor\nXKeyCollector\nXMissionTaker\nSignatureVerifier\nFunctions\nMonitor the collection of signed elements, key material and signature template.\nInvoke signature verification.\nClear up involved EC.\nBroadcast verify result.\nInterfaces\nXReferenceResolvedListener\nXSignatureCollector\nXKeyCollector\nXMissionTaker\nXSignatureVerifyResultBroadcaster\nEncryptor\nFunctions\nMonitor the collection of key material and encryption template.\nInvoke encryption.\nClear up involved EC and blocker.\nInterfaces\nXReferenceResolvedListener\nXBlockerMonitor\nXKeyCollector\nXMissionTaker\nDecryptor\nFunctions\nMonitor the collection of key material and encryption template.\nInvoke decryption.\nClear up involved EC and blocker.\nBroadcast decryption result.\nInterfaces\nXReferenceResolvedListener\nXBlockerMonitor\nXKeyCollector\nXMissionTaker\nXDecryptionResultBroadcaster\nXMLSignature\nFunctions\nGenerate signature.\nVerify signature.\nInterfaces\nSee XMLSignature design document.\n\nXMLEncryption\nFunctions\nEncrypt.\nDecrypt.\nInterfaces\nSee XMLEncryption design document.\n\nSolutions\nNotify Sequence\nAn element can be buffered for more than one purpose, each purpose needs one independent EC. When this element is completely buffered, in what sequence these ECs are notified collection end? If a blocker is working inside the element of the EC, should the EC be notified before or after the blocker is released?\nThe following paragraph will describe the notify sequence issue.\nWhen exporting, a EC can be used for a signed element, a signature template, an encryption template, a key material. When different type of ECs working on the same element, the notify sequence should be:\nkey material's EC\nencryption template's EC\nsignature template's EC\nsigned element's EC\nThe key material's EC should be notified before any encryption is performed, because any internal encryption may cause the key value become invisible.\nThe signed element's EC must be notified in the end. Because the message digest's calculation need the signed element's final shape as input, that is to say, all internal changes have been finished before that calculation.\nMoreover, inside a signed element's EC, if there is any blocker with different security id, this EC can't be notified until all this kind of blocker is removed.\nWhen importing, the notify sequence should be:\nsigned element's EC\nsignature template's EC\nencryption template's EC\nkey material's EC\nthe sequence is reversed from the one for exporting, the reason is so obvious. \nTransfer DOM data\nThe JSR105 based XMLDocumentWrapper implementation (XMLDocumentWrapper_Impl_JSR105) will have a native method as following (Java code):\n\nDocument getDocument();\n\nwhich will return the whole buffered data as a Document interface. While, the XMLSecurity based XMLDocumentWrapper (XMLDocumentWrapper_Impl_XMLSec) will have following native method (c++ code):\n\nXMLDocPtr * getDocument();\n\nthis method will return a XMLDocPtr pointer which represents the whole buffered document.\nBoth of these two methods don't belong to any UNO interface, mostly because their return type.\nWhen creating/verifying signatures, the XMLSignature component will get buffered SAX events as native data format from the XMLDocumentWrapper component through above methods, i.e., the JSR105 based XMLSignature (XMLSignature_Impl_JSR105) should get a DOM representing data by calling getDocument method (Java), and the XMLSecurity based XMLSignature (XMLSignature_Impl_XMLSec)will get a XMLDocPtr by calling getDocument method (c++).\nTo achieve this point, we will use the XUNOTunnel interface.\nThe two XMLSignature components will use the XUNOTunnel interface to get the native class instance (non-UNO instance) of XMLDocumentWrapper implementation. \n\n\nHelper Components\nSAXHelper\nThis class can translate UNO based SAX events into SAX events in the libxml2 format.\nPrototype\nThe chapter will describe how to use the prototype Java program.\nProgram overview\nThe prototype program is used to demonstrate the functionality of the XML Security Framework Components. its UI looks like following:\n\n\nThis is the original document which needs to be exported or imported. This document actually is a xml file. You can use command line \u201cJava TestTool xxx.xml\u201d to open a file directly, or use the \u201cOpen...\u201d button to open a file interactively.\nBecause no DTD to assist analyzing, any signature template and encryption template need to be directly included in this xml file. When export, a signature template should have empty DigestValue elements and empty SignatureValue element, a encryption template should include a CipherData element with plain XML data to be encrypted. When import, both a signature template and a encryption template should have complete data.\nThis text field shows the SAX event which is just sent out by the first component in the SAX chain. The first component is the XMLExporter in exporting, or the SAXParser in importing.\nThis table area shows the ECs owned by the application, which simulates the XMLImporter or XMLExporter holding ECs which will have further reference on.\nTo make it simple, this application use a RefNum attribute to estimate the referencing number on a EC.\nThere are three columns, the first column is the element's Id attribute, the second column is the leftover reference number, the third column is the EC's id.\nThis is the DOM tree inside of the XMLDocumentWrapper. A star mark represents the current blocking element.\nThis is the information of EC and blocker in the SAXEventKeeper.\nAll EC and blocker are organized in a tree, which represents the relationship between their working elements.\nEach item starts with an element name, followed by name of its parent element in a square bracket pair.\nThe string following \u201cEC=\u201d is EC's information:\n[EC's id] \u2013 [priority] ([security id])\nthe security id equals to -1 means no signature id assignment yet.\nThe stirng number following \u201cBR=\u201d is a blocker's information:\n[blocker's id]([security id])\nThis is the current SAX chain representative.\nThis is the result tree. When export, this is what received by the SAXWriter; when import, this is what received by the XMLImporter.\nThese are all function button.\nThe \u201cOpen...\u201d button is used to open an xml file as the original document.\nThe \u201cStart\u201d button is used to start the export/import.\nWhen \u201cStart\u201d button is pressed, the \u201cGo\u201d button and the \u201cStep\u201d button are enabled.\nThe \u201cGo\u201d button is used to export/import the original document continuously. While the \u201cStep\u201d button is used to export/import event by event.\nThe \u201cexport, not import\u201d check box indicates whether exporting or importing is in progress, when checked, it means exporting.\nThe \u201cjava, not c++\u201d check box indicates whether using the java based components or c++ based components. when checked, it means java.\nThe \u201cSave...\u201d button is used to save the result tree to an xml file.\nFile format\nWhen a xml file is read, it needs some particular format for the application to recognize.\nBecause there is no DTD for the xml file, so all blank text will be ignored for briefness.\nWhen an element is signed, it should has an \u201cid\u201d attribute. Meanwhile, it needs an additional attribute named \u201crefNum\u201d which represents how many times this element is referenced by signature element. If the \u201crefNum\u201d attribute is ignored, the default value is 999, that is to say, this element will be kept in buffer till the end of the exporting/importing process.\nThe following is an example of a signed element.\n<Data_C id=\"C\" refNum=\"3\">\n This is Data_C\n</Data_C>\n\nthe signature template format is similar with w3c's definition, some untouched fields are ignored for briefness, as following.\n<Signature>\n <KeyInfo>\n <RetrievalMethod URI=\"...\">\n </RetrievalMethod>\n <KeyValue>...</KeyValue>\n </KeyInfo> \n <SignedInfo>\n <Reference URI=\"C\">\n <DigestValue>\n d.i.g.e.s.t.V.a.l.u.e\n </DigestValue>\n </Reference>\n ...\n </SignedInfo>\n <SignatureValue>\n s.i.g.n.a.t.u.r.e.v.l.a.u.e\n </SignatureValue>\n <Object>\n ...\n </Object>\n</Signature>\n\nThe KeyInfo can include either KeyValue or RetrievalMethod, not both. When the KeyValue included, this signature has its key material by its own, otherwise, the URI attribute points to the external key material element.\nThere can be several Reference elements under the signedInfo element. The URI attribute in the Reference element can be either an Id, which refer a same-document element, or an external URI, which refer a detached content. When using external URI, there must be some mechanism to retrieve the content of the URI.\nWhen export, the content inside digestvalue and signaturevalue needs to be empty.\nThe Object element is optional, it can be used to store some additonal information about the signature, for instance, we can use the Object element to reserve the time of the signature, as the following:\n<Object>\n <SignatureProperties>\n <SignatureProperty Id=\"ID_XXXX\" Target=\"#ID_XXX\">\n <dc:date xmlns:dc=\"http://purl.org/dc/elements/1.1/\">\n ...\n </dc:date>\n </SignatureProperty>\n </SignatureProperties>\n</Object>\n\nBecause the SignatureProperty element has an Id attribute, so it is possible to sign the date by adding into the signature a new reference whose URI attribute points to this SignatureProperty element.\nThe encryption template format is similar with w3c's definition, some untouched fields are ignored for briefness, as following.\n<EncryptedData|Encryptedkey>\n <KeyInfo>\n <RetrievalMethod URI=\"...\">\n </RetrievalMethod>\n <KeyValue>...</KeyValue>\n </KeyInfo> \n <CipherData>\n <CipherValue>\n ...\n </CipherValue>\n </CipherData>\n</EncryptedData|Encryptedkey>\n\nThe KeyInfo is the same with the signature template.\nWhen import, the content inside CipherValue is the cipher data; when export, the CipherValue element is replaced with plain XML data to be encrypted." 6 }, 7 { 8 "name": "paras", 9 "expr": "len(doc.Text.String.split('\\r'))", 10 "expect": 1 11 } 12]