Package com.chilkatsoft.chilkat2

Class XmlDSig

java.lang.Object
com.chilkatsoft.chilkat2.ChilkatObject
com.chilkatsoft.chilkat2.XmlDSig
All Implemented Interfaces:
AutoCloseable
public class XmlDSig extends ChilkatObject
<section class="xmldsig-summary">

Load, inspect, canonicalize, and verify XML Digital Signatures.

Chilkat.XmlDSig loads and verifies XML Digital Signatures. It can inspect signed XML, select among multiple signatures in one document, verify the overall SignatureValue, verify individual Reference digests, handle external references, extract KeyInfo, retrieve embedded certificates or public keys, canonicalize XML, and add an EncapsulatedTimeStamp to an existing signature.

Load signed XML

Load an XML document containing one or more digital signatures and inspect the signature structure before verification.

Select a signature

Work with documents that contain multiple signatures by selecting the specific signature to inspect or verify.

Verify SignatureValue

Verify the cryptographic signature over the canonicalized SignedInfo block.

Verify Reference digests

Check individual Reference digest values to confirm that each signed item still matches what was originally signed.

Certificates and keys

Extract KeyInfo, embedded signing certificates, or public keys used to validate the signature.

Canonicalization and timestamps

Canonicalize XML for signature analysis and add an EncapsulatedTimeStamp when timestamping an existing signature.

Common pattern: Load the signed XML, select the desired signature if more than one is present, inspect the signing certificate or public key information, verify the SignatureValue, then verify the individual reference digests. Use XmlDSig for verification and inspection; use Chilkat.XmlDSigGen when creating new XML Digital Signatures.

For an extended overview, see XmlDSig Class Overview.

</section>

Instances hold a native Chilkat object: close them with ChilkatObject.close() (try-with-resources) when done; an unclosed instance is freed when it becomes unreachable.

See Also:
Online reference

  • Constructor Details

    • XmlDSig

      public XmlDSig()
      Creates a new XmlDSig object.

  • Method Details

    • getExternalRefDirs

      public String getExternalRefDirs()
      May contain a set of directory paths specifying where referenced external files are located. Directory paths should be separated using a semicolon character. The default value of this property is the empty string which means no directories are automatically searched.

      This property can be used if the external file referenced in the XML signature has the same filename as the file in the local filesystem.

      Returns:
      the value of the ExternalRefDirs property

    • setExternalRefDirs

      public void setExternalRefDirs​(String value)
      Sets the ExternalRefDirs property; see getExternalRefDirs().
      Parameters:
      value - the new value (not null)

    • getIgnoreExternalRefs

      public boolean getIgnoreExternalRefs()
      If true, then ignore failures caused by external references not being available. This allows for the XML signature to be at least partially validated if the external referenced files are not available. The default value of this property is false.
      Returns:
      the value of the IgnoreExternalRefs property

    • setIgnoreExternalRefs

      public void setIgnoreExternalRefs​(boolean value)
      Sets the IgnoreExternalRefs property; see getIgnoreExternalRefs().
      Parameters:
      value - the new value

    • getNumReferences

      public int getNumReferences()
      The number of data objects referenced in the XML digital signature. A data object may be self-contained within the loaded XML signature, or it may be an external URI reference. An application can check each reference to see if it's external by calling IsReferenceExternal, and can get each reference URI by calling ReferenceUri.
      Returns:
      the value of the NumReferences property (read-only)

    • getNumSignatures

      public int getNumSignatures()
      The number of digital signatures found within the loaded XML. Each digital signature is composed of XML having the following structure: 
        _LT_Signature ID?_GT_ 
      _LT_SignedInfo_GT_
        _LT_CanonicalizationMethod/_GT_
        _LT_SignatureMethod/_GT_
        (_LT_Reference URI? _GT_
          (_LT_Transforms_GT_)?
          _LT_DigestMethod_GT_
          _LT_DigestValue_GT_
        _LT_/Reference_GT_)+
      _LT_/SignedInfo_GT_
      _LT_SignatureValue_GT_ 
     (_LT_KeyInfo_GT_)?
     (_LT_Object ID?_GT_)*
  _LT_/Signature_GT_

      Note: The Signature and other XML tags may be namespace prefixed.

      The Selector property is used to select which XML signature is in effect when validating or calling other methods or properties.

      Returns:
      the value of the NumSignatures property (read-only)

    • getRefFailReason

      public int getRefFailReason()
      Indicates the failure reason for the last call to VerifyReferenceDigest. Possible values are:
      • 0: No failure, the reference digest was valid.
      • 1: The computed digest differs from the digest stored in the XML.
      • 2: An external file is referenced, but it is unavailable for computing the digest.
      • 3: The index argument passed to VerifyReferenceDigest was out of range.
      • 4: Unable to find the Signature.
      • 5: A transformation specified some sort of XML canonicalization that is not supported.
      • 99: Unknown. (Should never get this value.)

      Returns:
      the value of the RefFailReason property (read-only)

    • getSelector

      public int getSelector()
      If the loaded XML contains multiple signatures, this property can be set to specify which signature is in effect when calling other methods or properties. In most cases, the loaded XML contains a single signature and this property will remain at the default value of 0.
      Returns:
      the value of the Selector property

    • setSelector

      public void setSelector​(int value)
      Sets the Selector property; see getSelector().
      Parameters:
      value - the new value

    • getUncommonOptions

      public String getUncommonOptions()
      This is a catch-all property to be used for uncommon needs. This property defaults to the empty string, and should typically remain empty.
      Returns:
      the value of the UncommonOptions property

    • setUncommonOptions

      public void setUncommonOptions​(String value)
      Sets the UncommonOptions property; see getUncommonOptions().
      Parameters:
      value - the new value (not null)

    • addEncapsulatedTimeStamp

      public void addEncapsulatedTimeStamp​(JsonObject json, StringBuilder sbOut)
      Adds an EncapsulatedTimeStamp to the signature indicated by the Selector property. The updated signed XML with the added EncapsulatedTimeStamp is returned in sbOut. See the example below for details.
      Parameters:
      json - the json argument (not null)
      sbOut - the sbOut argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • canonicalizeFragment

      public String canonicalizeFragment​(String xml, String fragmentId, String version, String prefixList, boolean withComments)
      Applies XML canonicalization to a fragment of the passed-in XML, and returns the canonicalized XML string. The fragmentId identifies the XML element where output begins. It is the XML element having an id attribute equal to fragmentId. The version may be one of the following:
      • C14N -- for Inclusive Canonical XML
      • EXCL_C14N -- for Exclusive Canonical XML

      The prefixList only applies when the version is set to EXCL_C14N. The prefixList may be an empty string, or a SPACE separated list of namespace prefixes. It is the InclusiveNamespaces PrefixList, which is the list of namespaces that are propagated from ancestor elements for canonicalization purposes.

      If withComments is true, then XML comments are included in the output. If withComments is false, then XML comments are excluded from the output.

      Parameters:
      xml - the xml argument (not null)
      fragmentId - the fragmentId argument (not null)
      version - the version argument (not null)
      prefixList - the prefixList argument (not null)
      withComments - the withComments argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • canonicalizeXml

      public String canonicalizeXml​(String xml, String version, boolean withComments)
      Applies XML canonicalization to the passed-in XML, and returns the canonicalized XML string. The version may be one of the following:
      • C14N -- for Inclusive Canonical XML
      • EXCL_C14N -- for Exclusive Canonical XML

      If withComments is true, then XML comments are included in the output. If withComments is false, then XML comments are excluded from the output.

      Parameters:
      xml - the xml argument (not null)
      version - the version argument (not null)
      withComments - the withComments argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getCerts

      public void getCerts​(StringArray sa)
      Returns the certificates found in the signature indicated by the Selector property. The base64 representation of each certificate is returned.
      Parameters:
      sa - the sa argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getKeyInfo

      public Xml getKeyInfo()
      Returns the KeyInfo XML for the signature indicated by the Selector property. Returns null if no KeyInfo exists.
      Returns:
      a new Xml owned by the caller (never null); close it when done
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getPublicKey

      public PublicKey getPublicKey()
      Returns the public key from the KeyInfo XML for the signature indicated by the Selector property. Returns null if no KeyInfo exists, or if no public key is actually contained in the KeyInfo.
      Returns:
      a new PublicKey owned by the caller (never null); close it when done
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • hasEncapsulatedTimeStamp

      public boolean hasEncapsulatedTimeStamp()
      Returns true if the signature indicated by the Selector property contains an EncapsulatedTimeStamp. Otherwise returns false.
      Returns:
      the result; this method never throws ChilkatException

    • isReferenceExternal

      public boolean isReferenceExternal​(int index)
      Returns true if the reference at index is external. Each external reference would first need to be provided by the application prior to validating the signature.
      Parameters:
      index - the index argument
      Returns:
      the result; this method never throws ChilkatException

    • loadSignature

      public void loadSignature​(String xmlSig)
      Loads an XML document containing 1 or more XML digital signatures. An application would first load XML containing digital signature(s), then validate. After loading, it is also possible to use various methods and properties to get information about the signature, such as the key info, references, etc. If external data is referenced by the signature, it may be necessary to provide the referenced data prior to validating.

      Note: When loading an XML document, the Selector property is automatically reset to 0, and the NumSignatures property is set to the number of XML digital signatures found.

      Parameters:
      xmlSig - the xmlSig argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadSignatureBd

      public void loadSignatureBd​(BinData binData)
      Loads an XML document containing one or more XML digital signatures from the contents of a BinData object. An application would first load the XML, then validate. After loading, it is also possible to use various methods and properties to get information about the signature, such as the key info, references, etc. If external data is referenced by the signature, it may be necessary to provide the referenced data prior to validating.

      Note: When loading an XML document, the Selector property is automatically reset to 0, and the NumSignatures property is set to the number of XML digital signatures found.

      Parameters:
      binData - the binData argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loadSignatureSb

      public void loadSignatureSb​(StringBuilder sbXmlSig)
      Loads an XML document containing one or more XML digital signatures from the contents of a StringBuilder object. An application would first load the XML, then validate. After loading, it is also possible to use various methods and properties to get information about the signature, such as the key info, references, etc. If external data is referenced by the signature, it may be necessary to provide the referenced data prior to validating.

      Note: When loading an XML document, the Selector property is automatically reset to 0, and the NumSignatures property is set to the number of XML digital signatures found.

      Parameters:
      sbXmlSig - the sbXmlSig argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • referenceUri

      public String referenceUri​(int index)
      Returns the URI of the Nth reference specified by index. (The 1st reference is at index 0.) URI's beginning with a pound sign ('#') are internal references.
      Parameters:
      index - the index argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setHmacKey

      public void setHmacKey​(String key, String encoding)
      Sets the HMAC key to be used if the Signature used an HMAC signing algorithm. The encoding specifies the encoding of key, and can be hex, base64, ascii, or any of the binary encodings supported by Chilkat in the link below.
      Parameters:
      key - the key argument (not null)
      encoding - the encoding argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setHttpObj

      public void setHttpObj​(Http http)
      Sets the HTTP object to be used to communicate with OCSP responders, CRL distribution points, or timestamp authority (TSA) servers if needed. The http is used to send the requests, and it allows for connection related settings and timeouts to be set. For example, if HTTP or SOCKS proxies are required, these features can be specified on the http.
      Parameters:
      http - the http argument (not null)

    • setPublicKey

      public void setPublicKey​(PublicKey pubKey)
      Sets the public key to be used for verifying the signature indicated by the Selector property. A public key only needs to be explicitly provided by the application for those XML signatures where the public key is not already available within the KeyInfo of the Signature. In some cases, the KeyInfo within the Signature contains information about what public key was used for signing. The application can use this information to retrieve the matching public key and provide it via this method.
      Parameters:
      pubKey - the pubKey argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setRefDataBd

      public void setRefDataBd​(int index, BinData binData)
      Provides the binary data for the external reference at index.
      Parameters:
      index - the index argument
      binData - the binData argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setRefDataFile

      public void setRefDataFile​(int index, String path)
      Provides the data for the external reference at index. When validating the signature, the data contained in path will be streamed to compute the digest for validation.
      Parameters:
      index - the index argument
      path - the path argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setRefDataSb

      public void setRefDataSb​(int index, StringBuilder sb, String charset)
      Provides the text data for the external reference at index. The charset specifies the byte representation of the text, such as utf-8, utf-16, windows-1252, etc. (If in doubt, try utf-8 first.)
      Parameters:
      index - the index argument
      sb - the sb argument (not null)
      charset - the charset argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • useCertVault

      public void useCertVault​(XmlCertVault certVault)
      Adds an XML certificate vault to the object's internal list of sources to be searched for certificates having public keys when verifying an XML signature. A single XML certificate vault may be used. If UseCertVault is called multiple times, only the last certificate vault will be used, as each call to UseCertVault will replace the certificate vault provided in previous calls.
      Parameters:
      certVault - the certVault argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • verifyReferenceDigest

      public boolean verifyReferenceDigest​(int index)
      This method allows for an application to verify the digest for each reference separately. This can be helpful if the full XMLDSIG validation fails, then one can test each referenced data's digest to see which, if any, fail to match.
      Parameters:
      index - the index argument
      Returns:
      the result; this method never throws ChilkatException

    • verifySignature

      public void verifySignature​(boolean verifyReferenceDigests)
      Verifies the signature indicated by the Selector property. If verifyReferenceDigests is true, then the digest of each Reference within the signature's SignedInfo is also validated.
      Parameters:
      verifyReferenceDigests - the verifyReferenceDigests argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why