diff --git a/Documentation/VectoHashingTool/Manual.md b/Documentation/VectoHashingTool/Manual.md index 92f07388d5a9af55b6d9eb2ac4c292a4c83d0e96..00d67c85c3561dd80f977b6b31ab387b872805a2 100644 --- a/Documentation/VectoHashingTool/Manual.md +++ b/Documentation/VectoHashingTool/Manual.md @@ -248,4 +248,137 @@ The selected file is a valid VECTO XML file and has the correct contents. This dialog shows more details about errors during loading a VECTO XML file and validating its contents. The error messages can be copied to the clipboard using the 'Copy Errors' button. -## Using the Hashing Library \ No newline at end of file +## Using the Hashing Library + +The basic functionality of computing and verifying the digest value of component data, job data, reports, etc. as well as adding the digest value to a component are available as C# library in VectoHashing.dll. + +How to use the hashing libarary in your own application is described in the following. The class VectoHash provides factory methods to load the XML data from a file, from a stream or an XmlDocument. + +~~~ +var h = VectoHash.Load(xml); +~~~ + +The factory method returns an object providing the IVectoHash interface. The interface definition along with the method documentation is provided below. + +~~~ +var componentHash = h.ReadHash(); +var compoentDataValid = h.ValidateHash(); +~~~ + +The supported canonicalization methods and digest methods as well as the current default methods can be obtained from the VectoHash class: + +~~~ +VectoHash.SupportedDigestMehods() +VectoHash.DefaultDigestMethod() + +VectoHash.SupportedCanonicalizationMethods() +VectoHash.DefaultCanonicalizationMethod() +~~~ + +Description of the available VectoHash methods + +~~~ +public interface IVectoHash + { + /** + * Get a list of all vecto components contained in the XML file. If a certain + * component appears multiple times (e.g. tires) it is provided multiple times + * in the returned list. + * to get a list with unique entries (and the number of occurences) use e.g. + * GetContainigComponents().GroupBy(s => s).Select(g => new { Entry = g.Key, Count = g.Count() }) + */ + IList<VectoComponents> GetContainigComponents(); + + /** + * Get the digest method used to compute the digest value of the top-level Signature element + * if there is no top-level Signature element, the default digest method is returned (see XMLHashProvider.DefaultDigestMethod) + * @return identifier (urn) of the digest method + */ + string GetDigestMethod(); + + /** + * Get the digest method of the Signature element for the given component. If a component exists + * multiple times (e.g., tires), the index specifies for which component the digest method is returned + * @param component + * @param index + * @return identifier (urn) of the digest method + */ + string GetDigestMethod(VectoComponents component, int index = 0); + + /** + * Get the list of canonicalization methods used to compute the digest value of the top-level Signature element + * If there is no top-level Signature element, the default digest method is returned (see XMLHashProvider.DefaulCanonicalizationMethod) + * @return returns a list of identifiers (urns) of the canonicalization methods + */ + IEnumerable<string> GetCanonicalizationMethods(); + + /** + * Get the list of canonicalization methods used to compute the digest value of the Signature element + * for the given component. If a component exists multiple times (e.g., tires) the indes specifies for which + * component the canonicalization method is returned + * If there is no top-level Signature element, the default digest method is returned (see XMLHashProvider.DefaulCanonicalizationMethod) + * @return returns a list of identifiers (urns) of the canonicalization methods + */ + IEnumerable<string> GetCanonicalizationMethods(VectoComponents component, int index = 0); + + /** + * Reads the hash-value of the top-level Signature element + * @return base64 encoded hash value + */ + string ReadHash(); + + /** + * Reads the hash-value of the Signature element for the given component. If a component can exist + * multiple times (i.e., tires), the index specifies for which component the hash is computed + * @return base64 encoded hash value + */ + string ReadHash(VectoComponents component, int index = 0); + + + /** + * Computes the hash-value of the top-level Data element (or vehicle) + * If the canoonicalizationMethods is null the canonicalizationMethods from + * the signature element are read if available or the default canonicalization is applied + * If the digestMethod is null the digestMethod from the signature element is read if + * available or the default digestMethod is used + * Note: the top-level Data element is required to have an id attribute! + * @return base64 encoded hash value + */ + string ComputeHash(IEnumerable<string> canonicalizationMethods = null, string digestMethod = null); + + /** + * Computes the hash-value for the given component. If a component can exist multiple times + * (i.e., Tyres) the index specifies for which component the hash is computed + * If the canoonicalizationMethods is null the canonicalizationMethods from + * the signature element are read if available or the default canonicalization is applied + * If the digestMethod is null the digestMethod from the signature element is read if + * available or the default digestMethod is used + * Note: the Data element is required to have an id attribute! + * @return base64 encoded hash value + */ + + string ComputeHash(VectoComponents component, int index = 0, IEnumerable<string> canonicalizationMethods = null, + string digestMethod = null); + + /** + * Validates the hash of the top-level component (or vehicle) + */ + bool ValidateHash(); + + /** + * Validates the hash for the given component. + */ + bool ValidateHash(VectoComponents component, int index = 0); + + /** + * Computes the hash-value of the outer Data element and adds the according Signature element + * after the Data element. + * The default CaonocalizationMethods and DigestMethod are used. + * Note: the id attribute is added to the Data element automatically. if an id attribute is already + * present its value is overwritten. + * @return returns the document including the Signature element with the hash of the Data block + */ + XDocument AddHash(); + } + +~~~~ \ No newline at end of file