@chilkat/react-native 11.6.1

package/src/specs/XmlDSig.nitro.ts

@@ -0,0 +1,464 @@
+// Generated by ReactNativeNs.RnGenerator -- do not edit.
+import type { HybridObject } from 'react-native-nitro-modules'
+import type { BinData } from './BinData.nitro'
+import type { Http } from './Http.nitro'
+import type { JsonObject } from './JsonObject.nitro'
+import type { PublicKey } from './PublicKey.nitro'
+import type { StringArray } from './StringArray.nitro'
+import type { StringBuilder } from './StringBuilder.nitro'
+import type { Xml } from './Xml.nitro'
+import type { XmlCertVault } from './XmlCertVault.nitro'
+
+/**
+ * Load, inspect, canonicalize, and verify XML Digital Signatures.
+ *
+ * `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
+ * `XmlDSigGen` when creating new XML Digital Signatures.
+ *
+ * For an extended overview, see
+ * [XmlDSig Class Overview](https://www.chilkatsoft.com/xmldsig_class_overview.asp).
+ *
+ * Each `XmlDSig` instance owns a native Chilkat object. It is released when the JavaScript object
+ * is
+ * garbage collected, or immediately by `dispose()`; any use after `dispose()` throws.
+ * Create one with `new XmlDSig()`.
+ */
+export interface XmlDSig extends HybridObject<{ ios: 'c++', android: 'c++' }> {
+  // ---- Properties ----
+
+  /**
+   * Provides HTML-formatted information about the last called method or property. If a method call
+   * fails or behaves unexpectedly, check this property for details. Note that information is
+   * available regardless of the method call's success.
+   *
+   * This property is read-only.
+   */
+  readonly lastErrorHtml: string
+
+  /**
+   * Provides plain text information about the last called method or property. If a method call
+   * fails or behaves unexpectedly, check this property for details. Note that information is
+   * available regardless of the method call's success.
+   *
+   * This property is read-only.
+   */
+  readonly lastErrorText: string
+
+  /**
+   * Provides XML-formatted information about the last called method or property. If a method call
+   * fails or behaves unexpectedly, check this property for details. Note that information is
+   * available regardless of the method call's success.
+   *
+   * This property is read-only.
+   */
+  readonly lastErrorXml: string
+
+  /**
+   * Version of the component/library, such as "10.1.0"
+   *
+   * This property is read-only.
+   */
+  readonly version: string
+
+  /**
+   * If set to a file path, this property logs the LastErrorText of each Chilkat method or property
+   * call to the specified file. This logging helps identify the context and history of Chilkat
+   * calls leading up to any crash or hang, aiding in debugging.
+   *
+   * Enabling the VerboseLogging property provides more detailed information.
+   *
+   * This property is mainly used for debugging rare instances where a Chilkat method call causes a
+   * hang or crash, which should generally not happen.
+   *
+   * Possible causes of hangs include:
+   *
+   * - A timeout property set to 0, indicating an infinite timeout.
+   *
+   * - A hang occurring within an event callback in the application code.
+   *
+   * - An internal bug in the Chilkat code causing the hang.
+   */
+  debugLogFilePath: string
+
+  /**
+   * If set to `true`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may
+   * contain more verbose information. The default value is `false`. Verbose logging should only be
+   * used for debugging. The potentially large quantity of logged information may adversely affect
+   * peformance.
+   */
+  verboseLogging: boolean
+
+  /**
+   * Indicates the success or failure of the most recent method call: `true` means success, `false`
+   * means failure. This property remains unchanged by property setters or getters. This method is
+   * present to address challenges in checking for null or Nothing returns in certain programming
+   * languages. Note: This property does not apply to methods that return integer values or to
+   * boolean-returning methods where the boolean does not indicate success or failure.
+   */
+  lastMethodSuccess: boolean
+
+  /**
+   * 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.
+   *
+   * This property is read-only.
+   */
+  readonly numReferences: number
+
+  /**
+   * 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.
+   *
+   * This property is read-only.
+   */
+  readonly numSignatures: number
+
+  /**
+   * 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.
+   */
+  selector: number
+
+  /**
+   * 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`.
+   */
+  ignoreExternalRefs: boolean
+
+  /**
+   * 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.)
+   *
+   * This property is read-only.
+   */
+  readonly refFailReason: number
+
+  /**
+   * 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.
+   */
+  externalRefDirs: string
+
+  /**
+   * This is a catch-all property to be used for uncommon needs. This property defaults to the empty
+   * string, and should typically remain empty.
+   */
+  uncommonOptions: string
+
+  // ---- Methods ----
+
+  /**
+   * 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link XmlDSig.lastErrorText}.
+   */
+  canonicalizeXml(xml: string, version: string, withComments: boolean): string
+
+  /**
+   * 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link XmlDSig.lastErrorText}.
+   */
+  loadSignature(xmlSig: string): void
+
+  /**
+   * 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link XmlDSig.lastErrorText}.
+   */
+  loadSignatureSb(sbXmlSig: StringBuilder): void
+
+  /**
+   * 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.
+   */
+  isReferenceExternal(index: number): boolean
+
+  /**
+   * 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link XmlDSig.lastErrorText}.
+   */
+  referenceUri(index: number): string
+
+  /**
+   * 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.)
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link XmlDSig.lastErrorText}.
+   */
+  setRefDataSb(index: number, sb: StringBuilder, charset: string): void
+
+  /**
+   * Provides the binary data for the external reference at `index`.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link XmlDSig.lastErrorText}.
+   */
+  setRefDataBd(index: number, binData: BinData): void
+
+  /**
+   * 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link XmlDSig.lastErrorText}.
+   */
+  setRefDataFile(index: number, path: string): void
+
+  /**
+   * 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.
+   */
+  verifyReferenceDigest(index: number): boolean
+
+  /**
+   * 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link XmlDSig.lastErrorText}.
+   */
+  canonicalizeFragment(xml: string, fragmentId: string, version: string, prefixList: string, withComments: boolean): string
+
+  /**
+   * 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link XmlDSig.lastErrorText}.
+   */
+  loadSignatureBd(binData: BinData): void
+
+  /**
+   * 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link XmlDSig.lastErrorText}.
+   */
+  verifySignature(verifyReferenceDigests: boolean): void
+
+  /**
+   * Returns the KeyInfo XML for the signature indicated by the Selector property. Returns _NULL_ if
+   * no KeyInfo exists.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link XmlDSig.lastErrorText}.
+   */
+  getKeyInfo(): Xml
+
+  /**
+   * 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link XmlDSig.lastErrorText}.
+   */
+  getPublicKey(): PublicKey
+
+  /**
+   * 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link XmlDSig.lastErrorText}.
+   */
+  useCertVault(certVault: XmlCertVault): void
+
+  /**
+   * 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link XmlDSig.lastErrorText}.
+   */
+  setHmacKey(key: string, encoding: string): void
+
+  /**
+   * 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link XmlDSig.lastErrorText}.
+   */
+  setPublicKey(pubKey: PublicKey): void
+
+  /**
+   * Returns the certificates found in the signature indicated by the Selector property. The base64
+   * representation of each certificate is returned.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link XmlDSig.lastErrorText}.
+   */
+  getCerts(sa: StringArray): void
+
+  /**
+   * Returns `true` if the signature indicated by the Selector property contains an
+   * EncapsulatedTimeStamp. Otherwise returns `false`.
+   */
+  hasEncapsulatedTimeStamp(): boolean
+
+  /**
+   * 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.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link XmlDSig.lastErrorText}.
+   */
+  addEncapsulatedTimeStamp(json: JsonObject, sbOut: StringBuilder): void
+
+  /**
+   * 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`.
+   */
+  setHttpObj(http: Http): void
+}