@chilkat/react-native 11.6.1

package/src/specs/CertChain.nitro.ts

@@ -0,0 +1,312 @@
+// Generated by ReactNativeNs.RnGenerator -- do not edit.
+import type { HybridObject } from 'react-native-nitro-modules'
+import type { Cert } from './Cert.nitro'
+import type { JsonObject } from './JsonObject.nitro'
+import type { TrustedRoots } from './TrustedRoots.nitro'
+
+/**
+ * Inspect, verify, export, and work with X.509 certificate chains.
+ *
+ * `CertChain` is a compact helper class for representing
+ * and working with X.509 certificate chains. It lets applications inspect the
+ * ordered certificates in a chain, retrieve individual certificates, determine
+ * whether the chain reaches a root, check for expired certificates, verify
+ * chain signatures, test whether the root is trusted, load certificate chains
+ * from JWK `x5c` data, and export the chain as
+ * `X509PKIPathv1`.
+ *
+ * **Chain inspection**
+ *
+ * Examine the certificates in chain order and retrieve individual
+ * certificates with `CertAt`.
+ *
+ * **Root and trust checks**
+ *
+ * Determine whether the chain reaches a root certificate and whether that
+ * root is trusted.
+ *
+ * **Signature verification**
+ *
+ * Verify that each certificate in the chain is signed by the next
+ * certificate in the chain.
+ *
+ * **Expiration checks**
+ *
+ * Detect whether one or more certificates in the chain are expired.
+ *
+ * **JWK x5c support**
+ *
+ * Load certificate chains from JWK `x5c` arrays used by JWT,
+ * JWS, and other security-token workflows.
+ *
+ * **Chain export**
+ *
+ * Export the certificate chain in `X509PKIPathv1` format when
+ * that representation is required.
+ *
+ * **Common pattern:**
+ * Use `CertChain` to reason about the chain as a whole. For
+ * certificate-level details such as subject, issuer, SAN values, key usage,
+ * validity dates, fingerprints, serial numbers, and extensions, retrieve each
+ * certificate with `CertAt` and inspect it using
+ * `Chilkat.Cert`.
+ *
+ * For an extended overview, see
+ * [CertChain Class Overview](https://www.chilkatsoft.com/certchain_class_overview.asp).
+ *
+ * Each `CertChain` 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 CertChain()`.
+ */
+export interface CertChain 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 certificates currently contained in the chain.
+   *
+   * Index
+   * Meaning
+   *
+   * | `0` |
+   * | The target or end-entity certificate—the certificate farthest from the root end of the chain
+   * |
+   *
+   * | `1 ... NumCerts - 2` |
+   * | Intermediate CA certificates, when present |
+   *
+   * | `NumCerts - 1` |
+   * | The highest certificate available in the chain |
+   *
+   * **Do not assume the final certificate is trusted:** If `ReachesRoot` is `_FALSE_`, the final
+   * certificate may only be the highest intermediate that was available. Even when the chain ends
+   * in a self-signed root, trust must be established separately.
+   *
+   * This property is read-only.
+   */
+  readonly numCerts: number
+
+  /**
+   * The number of certificates in the chain whose validity period has expired.
+   *
+   * **Expiration is only one validation check:** A value of `0` does not mean the chain is valid or
+   * trusted. It does not by itself establish that certificates are already valid, correctly signed,
+   * unrevoked, issued by an accepted trust anchor, or suitable for the intended identity and key
+   * usage.
+   *
+   * Retrieve individual certificates with `CertAt` when the application needs to inspect exact
+   * validity dates or identify which certificates are expired.
+   *
+   * This property is read-only.
+   */
+  readonly numExpiredCerts: number
+
+  /**
+   * `_TRUE_` if the chain extends to a terminal root certificate rather than stopping at an
+   * intermediate certificate. When this property is `_TRUE_`, the certificate at index `NumCerts -
+   * 1` is the root-end certificate of the chain.
+   *
+   * **Root presence is not root trust:** An included root is commonly self-signed, but its presence
+   * does not make it a trusted anchor. Use `IsRootTrusted` with the application's approved
+   * `TrustedRoots` collection to test trust-anchor membership.
+   *
+   * A value of `_FALSE_` means the chain is incomplete at the root end; the final certificate may
+   * be an intermediate CA for which no issuer certificate was available.
+   *
+   * This property is read-only.
+   */
+  readonly reachesRoot: boolean
+
+  /**
+   * Specifies uncommon behavior as a comma-separated list of keywords. The default is the empty
+   * string, which enables the standard behavior.
+   *
+   * Keyword
+   * Effect
+   *
+   * | `PkiPathV1.ExcludeRoot` |
+   * | Omits the root certificate from the value returned by `X509PKIPathv1`. This option affects
+   * that method only. |
+   *
+   * **Interoperability note:** Some protocols transport the trust anchor with the path, while
+   * others expect the recipient to obtain or trust it independently. Use this option according to
+   * the format required by the receiving system.
+   */
+  uncommonOptions: string
+
+  // ---- Methods ----
+
+  /**
+   * Tests whether the certificate at the root end of this chain is present in the `TrustedRoots`
+   * collection passed in `ARG1`. Returns `_TRUE_` when a matching trusted-root certificate is
+   * found; otherwise returns `_FALSE_`.
+   *
+   * **Trust is a local policy decision:** A self-signed certificate is not trusted merely because
+   * it appears at the end of a chain. This method checks membership in the supplied trust
+   * collection; it does not, by itself, establish that the entire chain is valid for a particular
+   * application or identity.
+   *
+   * A complete certificate-validation decision may also require checking signature linkage,
+   * certificate validity periods, revocation status, basic constraints, key usage, policies, name
+   * constraints, and application-specific identity requirements.
+   */
+  isRootTrusted(trustedRoots: TrustedRoots): boolean
+
+  /**
+   * Verifies the cryptographic signature linkage of the certificates in this chain. Starting with
+   * the target certificate at index `0`, each certificate's signature is checked using the public
+   * key of the next issuer certificate in the chain. Returns `_TRUE_` when the certificate
+   * signatures are valid through the root end of the chain; otherwise returns `_FALSE_`.
+   *
+   * **Signature verification is not full path validation:** A `_TRUE_` result confirms the
+   * issuer-signature relationships represented by the chain. It does not by itself prove that the
+   * root is trusted, that certificates are within their validity periods, that none are revoked,
+   * that CA constraints and policies are acceptable, or that the target certificate is valid for a
+   * particular hostname or usage.
+   */
+  verifyCertSignatures(): boolean
+
+  /**
+   * Loads the certificate chain from the `x5c` member of the JWK contained in `ARG1`. Returns
+   * `_TRUE_` if the chain is loaded successfully; otherwise returns `_FALSE_`.
+   *
+   * As defined by RFC 7517, `x5c` is a JSON array of DER-encoded X.509 certificates represented
+   * using standard Base64—not Base64URL. The first certificate contains the key associated with the
+   * JWK. Each following certificate should certify the certificate immediately before it, so the
+   * array order is target certificate first and rootward certificates afterward.
+   *
+   * **Security note:** Loading an `x5c` array does not make its certificates trusted. Treat the
+   * chain as untrusted input until the required signature, validity, trust-anchor, revocation, and
+   * application-policy checks have been completed.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link CertChain.lastErrorText}.
+   */
+  loadX5C(jwk: JsonObject): void
+
+  /**
+   * Returns the Base64 representation of a DER-encoded ASN.1 `PkiPath` containing the certificates
+   * in this chain. This representation is commonly identified as the `X509PKIPathv1` token type in
+   * WS-Security and may also be encountered in XML-signature workflows.
+   *
+   * A `PkiPath` is a `SEQUENCE OF Certificate` ordered from the root or most-trusted end toward the
+   * target certificate. This is the reverse of the indexing used by `CertAt`, where index `0` is
+   * the target certificate.
+   *
+   * Representation
+   * Certificate order
+   *
+   * | `CertChain` indexing |
+   * | Target/leaf → intermediates → root |
+   *
+   * | `X509PKIPathv1` |
+   * | Root → intermediates → target/leaf |
+   *
+   * By default, the root certificate is included when it is present in the chain. Set
+   * `UncommonOptions` to `PkiPathV1.ExcludeRoot` when the receiving protocol expects the trust
+   * anchor to be supplied separately.
+   *
+   * **Return-value note:** This is a string-returning method. Check `LastMethodSuccess` before
+   * using the returned text, and inspect `LastErrorText` if the operation fails.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link CertChain.lastErrorText}.
+   */
+  x509PKIPathv1(): string
+
+  /**
+   * Populates `ARG2` with the certificate at the specified zero-based `index`. Valid indices range
+   * from `0` through `NumCerts - 1`.
+   *
+   * Index
+   * Position in the chain
+   *
+   * | `0` |
+   * | Target or end-entity certificate |
+   *
+   * | `1 ... NumCerts - 2` |
+   * | Intermediate CA certificates, when present |
+   *
+   * | `NumCerts - 1` |
+   * | Highest certificate available in the chain; a root certificate only when `ReachesRoot` is
+   * `_TRUE_` |
+   *
+   * Returns `_TRUE_` on success. Returns `_FALSE_` if the index is invalid or the certificate
+   * cannot be returned; in that case, do not use the contents of `ARG2` as a successful result.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link CertChain.lastErrorText}.
+   */
+  certAt(index: number, cert: Cert): void
+}