From ba34510f94cc02c7c15f984a2995dfb357a2cf82 Mon Sep 17 00:00:00 2001
From: Markus Quaritsch <markus.quaritsch@tugraz.at>
Date: Thu, 28 Sep 2017 16:51:15 +0200
Subject: [PATCH] more work on user manual
---
Documentation/VectoHashingTool/Manual.md | 135 ++++++++++++++++++++++-
1 file changed, 134 insertions(+), 1 deletion(-)
diff --git a/Documentation/VectoHashingTool/Manual.md b/Documentation/VectoHashingTool/Manual.md
index 92f07388d5..00d67c85c3 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
--
GitLab