@chilkat/react-native 11.6.1

package/src/specs/CertStore.nitro.ts

@@ -0,0 +1,430 @@
+// Generated by ReactNativeNs.RnGenerator -- do not edit.
+import type { HybridObject } from 'react-native-nitro-modules'
+import type { BinData } from './BinData.nitro'
+import type { Cert } from './Cert.nitro'
+import type { JsonObject } from './JsonObject.nitro'
+
+/**
+ * Open, search, manage, and use certificate collections from many sources.
+ *
+ * `CertStore` is the Chilkat class for working with
+ * collections of X.509 certificates. It can open and manage certificates from
+ * system stores, Apple Keychain, Windows registry or file stores, memory
+ * stores, PEM files, PFX/P12 files, and smart card or USB token devices. It
+ * supports loading, searching, iterating, adding, removing, and closing
+ * certificate stores, with platform-specific behavior for Windows and Apple
+ * Keychain.
+ *
+ * **Open certificate stores**
+ *
+ * Access certificates from Windows certificate stores, Apple Keychain,
+ * files, memory stores, PEM bundles, PFX/P12 files, and hardware tokens.
+ *
+ * **Search and retrieve certs**
+ *
+ * Find certificates by subject, issuer, serial number, thumbprint, email,
+ * private-key availability, or other identifying information.
+ *
+ * **Iterate collections**
+ *
+ * Enumerate certificates in a store and retrieve each certificate as a
+ * `Chilkat.Cert` object for inspection or use.
+ *
+ * **Add and remove certificates**
+ *
+ * Add certificates to writable stores, remove certificates where supported,
+ * and manage store contents from application code.
+ *
+ * **Private-key backed certs**
+ *
+ * Work with certificates that have associated private keys from PFX/P12,
+ * operating-system stores, smart cards, USB tokens, or other providers.
+ *
+ * **Use across Chilkat**
+ *
+ * Pass retrieved certificates to other Chilkat classes for TLS client
+ * authentication, S/MIME, signing, encryption, decryption, and verification.
+ *
+ * **Common pattern:**
+ * Open the appropriate certificate store, search or iterate to find the needed
+ * certificate, retrieve it as a `Chilkat.Cert`, and then pass that
+ * certificate to the Chilkat class that needs it. Use certificate stores when
+ * the application should select from existing system, file-based, keychain, or
+ * hardware-backed certificates.
+ *
+ * For an extended overview, see
+ * [CertStore Class Overview](https://www.chilkatsoft.com/certstore_class_overview.asp).
+ *
+ * Each `CertStore` 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 CertStore()`.
+ */
+export interface CertStore 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
+
+  /**
+   * Applies only when running on a Microsoft Windows operating system. If `true`, then any method
+   * that returns a certificate will not try to also access the associated private key, assuming one
+   * exists. This is useful if the certificate was installed with high-security such that a private
+   * key access would trigger the Windows OS to display a security warning dialog. The default value
+   * of this property is `false`.
+   */
+  avoidWindowsPkAccess: boolean
+
+  /**
+   * The number of certificates held in the certificate store.
+   *
+   * This property is read-only.
+   */
+  readonly numCertificates: number
+
+  /**
+   * Can be set to the PIN value for a certificate / private key stored on a smart card.
+   */
+  smartCardPin: 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 ----
+
+  /**
+   * On Windows, this updates or adds `cert` to the open Windows certificate store. Note: This
+   * imports the certificate without the private key. The `Chilkat.Pfx.ImportToWindows` method must
+   * be called to import a certificate with a private key.
+   *
+   * Beginning with Chilkat v10.0.0, on macOS and iOS, this adds the certificate, **including any
+   * private keys** and intermediate CA certificates, to the Apple Keychain.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link CertStore.lastErrorText}.
+   */
+  addCertificate(cert: Cert): void
+
+  /**
+   * This method, **available only on Microsoft Windows**, creates a new file-based certificate
+   * store. You can save certificates to this store by using the AddCertificate function.
+   *
+   * Internally, the Microsoft function CertOpenStore is called with the provider type
+   * CERT_STORE_PROV_FILE and the flag CERT_STORE_CREATE_NEW_FLAG, to create a new, empty
+   * certificate store that is backed by a file.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link CertStore.lastErrorText}.
+   */
+  createFileStore(filename: string): void
+
+  /**
+   * This method, **available only on Microsoft Windows**, creates an in-memory certificate store.
+   * Certificates may be added by calling AddCertificate.
+   *
+   * Internally, the Microsoft function CertOpenStore is called with the provider type
+   * CERT_STORE_PROV_MEMORY to create a new in-memory certificate store. This store acts as a
+   * temporary container for managing certificates during runtime. The store exists only in memory
+   * and is not backed by a file or persistent storage. Certificates can be added, retrieved, or
+   * removed, but the store is lost when the application ends unless explicitly saved elsewhere.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link CertStore.lastErrorText}.
+   */
+  createMemoryStore(): void
+
+  /**
+   * This method, **available only on Microsoft Windows**, creates a new registry-based certificate
+   * store. You can save certificates to this store by using the AddCertificate function.
+   *
+   * Internally, the Microsoft function CertOpenStore is called with the provider type
+   * CERT_STORE_PROV_REG and a registry key to create a new, empty certificate store in the Windows
+   * registry.
+   *
+   * `regRoot` can be the string `CurrentUser` or `LocalMachine`. `regPath` is a registry key path
+   * such as `Software/MyApplication/Certificates`.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link CertStore.lastErrorText}.
+   */
+  createRegistryStore(regRoot: string, regPath: string): void
+
+  /**
+   * Loads the certificates contained within a PEM formatted file.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link CertStore.lastErrorText}.
+   */
+  loadPemFile(pemPath: string): void
+
+  /**
+   * Loads the certificates contained within an in-memory PEM formatted string.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link CertStore.lastErrorText}.
+   */
+  loadPemStr(pemString: string): void
+
+  /**
+   * Loads a PFX file. Once loaded, the certificates within the PFX may be searched via the Find\*
+   * methods. It is also possible to iterate from 0 to NumCertficates-1, calling GetCertificate for
+   * each index, to retrieve each certificate within the PFX.
+   *
+   * **Note:** This method does not import certificates into the Windows certificate stores. The
+   * purpose of this method is to load a .pfx/.p12 into this object so that other API methods can be
+   * called to explore or search the contents of the PFX. The Chilkat Pfx class also provides
+   * similar functionality.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link CertStore.lastErrorText}.
+   */
+  loadPfxFile(pfxFilename: string, password: string): void
+
+  /**
+   * On Windows, this method opens the **Current-User\\Personal** certificate store in the registry.
+   * Set `bReadOnly` to `true` to open the store in read-only mode, which allows you to fetch
+   * certificates without adding or removing them. This prevents `permission denied` errors that
+   * require read-write access.
+   *
+   * Starting in version 10.0.0, this method opens the **Apple Keychain** on MacOS and iOS systems.
+   * The `bReadOnly` is ignored.
+   *
+   * After opening the store, you can search for certificates using the Find\* methods.
+   * Alternatively, you can iterate through the certificates by indexing from 0 to
+   * NumCertificates-1, using GetCertificate to access each one.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link CertStore.lastErrorText}.
+   */
+  openCurrentUserStore(bReadOnly: boolean): void
+
+  /**
+   * (This method only available on Microsoft Windows operating systems.)
+   *
+   * Opens a file-based certificate store.
+   *
+   * Once loaded, the certificates within the store may be searched via the Find\* methods. An
+   * application may also iterate from 0 to NumCertficates-1 and call GetCertificate to access each
+   * certificate by index.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link CertStore.lastErrorText}.
+   */
+  openFileStore(filename: string, bReadOnly: boolean): void
+
+  /**
+   * (This method is only available on Microsoft Windows operating systems.)
+   *
+   * Opens the registry-based Local-Computer\\Personal certificate store. Set `bReadOnly` = `true`
+   * if only fetching certificates and not updating the certificate store (i.e. certificates will
+   * not be added or removed). Setting `bReadOnly` = `true` causes the certificate store to be
+   * opened read-only, and will prevent `permission denied` errors caused by the need for read-write
+   * permission.
+   *
+   * Once loaded, the certificates within the store may be searched via the Find\* methods. An
+   * application may also iterate from 0 to NumCertficates-1 and call GetCertificate to access each
+   * certificate by index.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link CertStore.lastErrorText}.
+   */
+  openLocalSystemStore(bReadOnly: boolean): void
+
+  /**
+   * (This method only available on Microsoft Windows operating systems.)
+   *
+   * Opens an arbitrary registry-based certificate store. `regRoot` must be `CurrentUser` or
+   * `LocalMachine`. `regPath` is a registry path such as `Software/MyApplication/Certificates`.
+   *
+   * Setting `bReadOnly` = `true` causes the certificate store to be opened read-only, and will
+   * prevent `permission denied` errors caused by the need for read-write permission.
+   *
+   * Once loaded, the certificates within the store may be searched via the Find\* methods. An
+   * application may also iterate from 0 to NumCertficates-1 and call GetCertificate to access each
+   * certificate by index.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link CertStore.lastErrorText}.
+   */
+  openRegistryStore(regRoot: string, regPath: string, bReadOnly: boolean): void
+
+  /**
+   * (This method only available on Microsoft Windows operating systems.)
+   *
+   * Opens a Microsoft Windows certificate store. `storeLocation` must be `CurrentUser` or
+   * `LocalMachine`. `storeName` is the name of the certificate store to open. It may be any of the
+   * following:
+   *
+   * -
+   * AddressBook: Certificate store for other users.
+   *
+   * -
+   * AuthRoot: Certificate store for third-party certification authorities (CAs).
+   *
+   * -
+   * CertificationAuthority: Certificate store for intermediate certification authorities (CAs).
+   *
+   * -
+   * Disallowed: Certificate store for revoked certificates.
+   *
+   * -
+   * My: Certificate store for personal certificates.
+   *
+   * -
+   * Root: Certificate store for trusted root certification authorities (CAs).
+   *
+   * -
+   * TrustedPeople: Certificate store for directly trusted people and resources.
+   *
+   * -
+   * TrustedPublisher: Certificate store for directly trusted publishers.
+   *
+   * Setting `bReadOnly` = `true` causes the certificate store to be opened read-only, and will
+   * prevent `permission denied` errors caused by the need for read-write permission.
+   *
+   * Once loaded, the certificates within the store may be searched via the Find\* methods. An
+   * application may also iterate from 0 to NumCertficates-1 and call GetCertificate to access each
+   * certificate by index.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link CertStore.lastErrorText}.
+   */
+  openWindowsStore(storeLocation: string, storeName: string, bReadOnly: boolean): void
+
+  /**
+   * (This method only available on Microsoft Windows operating systems.)
+   *
+   * Removes the passed certificate from the store. The certificate object passed as the argument
+   * can no longer be used once removed.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link CertStore.lastErrorText}.
+   */
+  removeCertificate(cert: Cert): void
+
+  /**
+   * This function identifies connected HSM devices such as smart cards and USB tokens, and loads
+   * the certificates from each device. It has been significantly enhanced in Chilkat v10.1.2 and is
+   * compatible with Windows, MacOS, iOS, and Linux. (Android is not yet supported.)
+   *
+   * Note: The `csp` is no longer used and is ignored.  Applications should pass an empty string.
+   *
+   * Note: If multiple HSM devices are connected, avoid setting the SmartCardPin property unless all
+   * devices share the same PIN. Otherwise, Chilkat will attempt to use that PIN for each device,
+   * which could cause issues.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link CertStore.lastErrorText}.
+   */
+  openSmartcard(csp: string): void
+
+  /**
+   * This method closes any open certificate stores, removes all certificates from the object, and
+   * sets the NumCertificates property back to 0.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link CertStore.lastErrorText}.
+   */
+  closeCertStore(): void
+
+  /**
+   * Searches for a certificate using criteria from `json` and stores the result in `cert`. If
+   * multiple criteria are provided, it searches each one sequentially and returns the first match.
+   *
+   * Preference is given to non-expired certificates, so if both expired and non-expired
+   * certificates match, the non-expired one is selected.
+   *
+   * See the examples below for details.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link CertStore.lastErrorText}.
+   */
+  findCert(json: JsonObject, cert: Cert): void
+
+  /**
+   * Loads the PFX/P12 bytes contained in `bd`.  `password` is the password to the PFX.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link CertStore.lastErrorText}.
+   */
+  loadPfxBd(bd: BinData, password: string): void
+
+  /**
+   * Loads the Nth certificate into `cert`. The first certificate is at index 0.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link CertStore.lastErrorText}.
+   */
+  getCert(index: number, cert: Cert): void
+}