@chilkat/react-native 11.6.1

package/src/specs/Pkcs11.nitro.ts

@@ -0,0 +1,559 @@
+// 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 { PrivateKey } from './PrivateKey.nitro'
+import type { PublicKey } from './PublicKey.nitro'
+import type { SshKey } from './SshKey.nitro'
+
+/**
+ * Work directly with PKCS#11 smart cards, USB tokens, and HSMs.
+ *
+ * `Pkcs11` is the direct Chilkat interface for working with
+ * PKCS#11 devices such as smart cards, USB tokens, and hardware security
+ * modules. It manages the vendor PKCS#11 shared library, slot and token
+ * discovery, session opening, PIN login, certificate and key discovery, object
+ * attributes, key generation, key import, object creation and deletion,
+ * public-key export, and token administration.
+ *
+ * **Load vendor libraries**
+ *
+ * Initialize access to the PKCS#11 module supplied by the smart-card,
+ * token, or HSM vendor.
+ *
+ * **Discover slots and tokens**
+ *
+ * Enumerate available slots, detect inserted tokens, and inspect token or
+ * slot information before opening a session.
+ *
+ * **Open sessions and login**
+ *
+ * Open PKCS#11 sessions, login with a user PIN, perform private-key
+ * operations, then logout and close the session.
+ *
+ * **Find certs and keys**
+ *
+ * Search for certificates, public keys, private keys, and other token
+ * objects using labels, IDs, classes, attributes, or key relationships.
+ *
+ * **Create and manage objects**
+ *
+ * Generate keys, import keys, create token objects, inspect attributes, and
+ * delete objects when supported by the token policy.
+ *
+ * **Use with signing classes**
+ *
+ * Link a token-backed certificate or private key to other Chilkat classes
+ * so signing can occur without the private key leaving the device.
+ *
+ * **Common pattern:**
+ * Load the vendor PKCS#11 library, select the slot or token, open a session,
+ * login with the PIN, find the certificate that has the needed private key,
+ * link that certificate for use by another Chilkat signing class, then logout
+ * and close the session. Use `Pkcs11` when the application needs
+ * direct token control; use `Chilkat.Cert` once a token-backed
+ * certificate has been selected for signing or authentication.
+ *
+ * For an extended overview, see
+ * [Pkcs11 Class Overview](https://www.chilkatsoft.com/pkcs11_class_overview.asp).
+ *
+ * Each `Pkcs11` 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 Pkcs11()`.
+ */
+export interface Pkcs11 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
+
+  /**
+   * On Windows systems, then should be set to the name of the DLL file (if the DLL is located in
+   * C:\\Windows\\System32), or it can be the full path to the DLL.
+   *
+   * On Linux, MacOSX, or other non-Windows systems, this can also be either the full path to the
+   * .so or .dylib, or just the .so or .dylib filename. On these systems, Chilkat calls the dlopen
+   * system function to load the shared library. If just the filename is passed in, the directories
+   * searched are those indicated in the dlopen function description at
+   * [https://man7.org/linux/man-pages/man3/dlopen.3.html](https://man7.org/linux/man-pages/man3/dlopen.3.html)
+   */
+  sharedLibPath: string
+
+  /**
+   * The number of certificates contained on the smart card or USB token. This property is set when
+   * FindAllCerts is called.
+   *
+   * This property is read-only.
+   */
+  readonly numCerts: number
+
+  /**
+   * If the smart card or token requires a signature context login within the signing operation,
+   * then set this property to the context-specific signature PIN. Most smart cards do not need
+   * this. Don't set this property unless you know for sure your smart card needs it.
+   */
+  sigContextPin: string
+
+  /**
+   * This is a catch-all property to be used for uncommon needs. This property defaults to the empty
+   * string. It can be set to a list of one or more of the following comma separated keywords:
+   *
+   * - **Pkcs11DiscoverSkipTokenInfo** - Introduced in v9.5.0.99. Applies to the Discover method. If
+   *   this keyword is present, then Discover will only return the slot information and will not
+   *   make potentially time-consuming calls to get TokenInfo or information about supported
+   *   mechanisms.
+   *
+   * - **Pkcs11DiscoverSkipMechanisms** - Introduced in v9.5.0.99. Applies to the Discover method.
+   *   If this keyword is present, then Discover will get slot and token info, but will not make
+   *   potentially time-consuming calls to get information about supported mechanisms.
+   */
+  uncommonOptions: string
+
+  // ---- Methods ----
+
+  /**
+   * Initializes the PKCS#11 library. Should be called after specifying the SharedLibPath. The DLL
+   * (or .so/.dylib) is dynamically loaded and the PKCS#11 lib is initialized.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Pkcs11.lastErrorText}.
+   */
+  initialize(): void
+
+  /**
+   * Discovers the readers, smart cards, and USB tokens accessible via PKCS11 on the computer (using
+   * the DLL/shared lib specified by SharedLibPath). The `onlyTokensPresent` specifies if only slots
+   * (readers) with tokens (smart cards) present should be returned. The information is written to
+   * the `json`. (For details, see the example below.)
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Pkcs11.lastErrorText}.
+   */
+  discover(onlyTokensPresent: boolean, json: JsonObject): void
+
+  /**
+   * Opens a session on the token (i.e. smart card). The `slotId` is the ID of the slot (not the
+   * index). Set `slotId` equal to -1 to choose the first available non-empty slot. The `readWrite`
+   * indicates whether the session should be read-only or read-write.
+   *
+   * The PKCS11 terminology is confusing:
+   *
+   * - A `slot` corresponds to a connected smart card reader or USB hardware token, such as a
+   *   Feitian ePass3003Auto token.
+   *
+   * - A `token` corresponds to the smart card inserted into the reader. If we have a USB hardware
+   *   token, such as the epass3003Auto (or many others), then technically there is always a `smart
+   *   card` inserted, because the USB hardware token is effectively both the reader and smart card
+   *   wrapped in one inseparable device.
+   *
+   * - The PKCS11 DLL (or .so shared lib, or .dylib) is the vendor supplied PKCS11 implementation
+   *   (driver) that provides the low-level `C` PKCS11 functions (called by Chilkat internally).
+   *
+   * - Generally, the number of slots will equal the number of connected smart cards or tokens
+   *   belonging to the vendor of the DLL, or compatible with the DLL. In most cases you'll have
+   *   your single reader with a single smart card inserted, and therefore only one slot exists.
+   *
+   * - Some PKCS11 DLLs are provided by a 3rd party and support many smart cards.
+   *   For example, A.E.T. Europe B.V.'s `SafeSign Identity Client Standard Version 3.5` DLL is
+   *   `aetpkss1.dll`. It supports the following tokens:
+   *
+   * - Defensiepas
+   *
+   * - Defensiepas 2
+   *
+   * - G&D Convego Join 4.01 40k/80k
+   *
+   * - G&D SkySIM Hercules
+   *
+   * - G&D SkySIM Scorpius
+   *
+   * - G&D Sm@rtCafé Expert 3.2
+   *
+   * - G&D Sm@rtCafé Expert 4.0
+   *
+   * - G&D Sm@rtCafé Expert 5.0
+   *
+   * - G&D Sm@rtCafé Expert 6.0
+   *
+   * - G&D Sm@rtCafé Expert 7.0
+   *
+   * - G&D Sm@rtCafé Expert 64
+   *
+   * - Gemalto Desineo ICP D72 FXR1 Java
+   *
+   * - Gemalto IDCore 30
+   *
+   * - Gemalto MultiApp ID v2.1
+   *
+   * - Gemalto Optelio D72 FR1
+   *
+   * - Gemalto TOP DL v2
+   *
+   * - Infineon Oracle JCOS Ed.1
+   *
+   * - JCOP21 v2.3
+   *
+   * - Morpho IDealCitiz v2.1
+   *
+   * - Morpho JMV ProCL V3.0
+   *
+   * - NXP J2A080 / J2A081 (JCOP 2.4.1 R3)
+   *
+   * - NXP JD081 (JCOP 2.4.1 R3)
+   *
+   * - NXP J3A080 (JCOP 2.4.1 R3)
+   *
+   * - NXP JCOP 2.4.2 R3
+   *
+   * - NXP JCOP 3 SecID P60
+   *
+   * - Oberthur IDOne Cosmo v7.0
+   *
+   * - RDW ABR kaart
+   *
+   * - Rijkspas
+   *
+   * - Rijkspas 2
+   *
+   * - Sagem YpsID s2
+   *
+   * - Sagem YpsID s3
+   *
+   * - StarSign Crypto USB Token S
+   *
+   * - Swissbit PS-100u SE
+   *
+   * - UZI-pas
+   *
+   * - UZI-pas 2
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Pkcs11.lastErrorText}.
+   */
+  openSession(slotId: number, readWrite: boolean): void
+
+  /**
+   * Closes the session on the token (i.e. smart card).
+   *
+   * Note: Memory leaks can occur if the session is not properly closed.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Pkcs11.lastErrorText}.
+   */
+  closeSession(): void
+
+  /**
+   * Authenticates a session with a PIN.  The `userType` can be one of the following integer values:
+   *
+   * - Security Officer (0)
+   *
+   * - Normal User (1)
+   *
+   * - Context Specific (2)
+   *
+   * Except for special circumstances, you'll always login as the Normal User.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Pkcs11.lastErrorText}.
+   */
+  login(userType: number, pin: string): void
+
+  /**
+   * Logs out from a token (smart card).
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Pkcs11.lastErrorText}.
+   */
+  logout(): void
+
+  /**
+   * Finds all certificates contained on the smart card (or USB token). This sets the NumCerts
+   * property. Each certificate can be obtained by calling GetCert(index) where the 1st cert is at
+   * index 0.
+   *
+   * Important: Private keys will not be seen unless the PKCS11 session is authenticated. To
+   * authenticate, your application must call Login after calling OpenSession.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Pkcs11.lastErrorText}.
+   */
+  findAllCerts(): void
+
+  /**
+   * Loads `cert` with the Nth certificate indicated by `index`. The 1st certificate is at index 0.
+   * The FindAllCerts method must be called beforehand to load the certs from the smart card into
+   * this object. After calling FindAllCerts, the NumCerts property is set and each certificate can
+   * be retrieved by calling GetCert.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Pkcs11.lastErrorText}.
+   */
+  getCert(index: number, cert: Cert): void
+
+  /**
+   * Finds the certificate where the given `certPart` equals the `partValue`. Possible values for
+   * `certPart` are: `privateKey`, `subjectDN`, `subjectDN_withTags`, `subjectCN`, `serial`, or
+   * `serial:issuerCN`. If `certPart` equals `privateKey`, then pass an empty string in `partValue`.
+   * Specifying `privateKey` means to return the first certificate having a private key.
+   *
+   * The `cert` is loaded with the certificate if successful.
+   *
+   * Important: Private keys will not be seen unless the PKCS11 session is authenticated. To
+   * authenticate, your application must call Login after calling OpenSession.
+   *
+   * Note: If successful, the `cert` will be linked internally with this PKCS11 session such that
+   * certificate can be used for signing on the smart card when used in other Chilkat classes such
+   * as XmlDSigGen, Pdf, Crypt2, Mime, MailMan, etc.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Pkcs11.lastErrorText}.
+   */
+  findCert(certPart: string, partValue: string, cert: Cert): void
+
+  /**
+   * Modifies the PIN of the user that is currently logged in, or the Normal User PIN if the session
+   * is not logged in.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Pkcs11.lastErrorText}.
+   */
+  setPin(oldPin: string, newPin: string): void
+
+  /**
+   * Initializes the normal user's PIN. This must be called from the security officer's (SO)
+   * logged-in session.
+   *
+   * Note: To unblock a smart card, login to the SO (Security Officer) session using the PUK, and
+   * then call this with the new user PIN.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Pkcs11.lastErrorText}.
+   */
+  initPin(pin: string): void
+
+  /**
+   * Initializes a token.  `slotId` is the slot ID of the token's slot.
+   *
+   * If the token has not been initialized (i.e. new from the factory), then the pPin parameter
+   * becomes the initial value of the SO (Security Officer) PIN. If the token is being
+   * reinitialized, the `pin` parameter is checked against the existing SO PIN to authorize the
+   * initialization operation.
+   *
+   * When a token is initialized, all objects that can be destroyed are destroyed (i.e., all except
+   * for “indestructible” objects such as keys built into the token). Also, access by the normal
+   * user is disabled until the SO sets the normal user’s PIN. Depending on the token, some
+   * “default” objects may be created, and attributes of some objects may be set to default values.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Pkcs11.lastErrorText}.
+   */
+  initToken(slotId: number, pin: string, tokenLabel: string): void
+
+  /**
+   * Finds all keys contained on the smart card (or USB token). The `keyClass` indicates the kind of
+   * keys to return, and can be one of the following:
+   *
+   * - public
+   *
+   * - private
+   *
+   * - secret
+   *
+   * - otp
+   *
+   * Information about the keys is returned in `json`.
+   *
+   * Important: Private keys will not be seen unless the PKCS11 session is authenticated. To
+   * authenticate, your application must call Login after calling OpenSession.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Pkcs11.lastErrorText}.
+   */
+  findAllKeys(keyClass: string, json: JsonObject): void
+
+  /**
+   * Generates a symmetric encryption key. The `keyType` is the key type, which can be one of the
+   * following values:
+   *
+   * - AES
+   *
+   * - AES XTS
+   *
+   * - Blowfish
+   *
+   * - Twofish
+   *
+   * - ChaCha20
+   *
+   * The `jsonTemplate` is a template that specifies attributes about the key to be generated. See
+   * the example at the link below.
+   *
+   * The handle to the generated key is returned.  A value of 0 is returned on failure.
+   */
+  genSecretKey(keyType: string, jsonTemplate: JsonObject): number
+
+  /**
+   * Generate an RSA key pair suitable for signing data and verifying signatures. The private key is
+   * created on the HSM (smart card or token), and the public key is returned in `pubKey`. The
+   * `publicAttrs` and `privateAttrs` contain attributes for the public and private keys
+   * respectively. The PKCS11 public and private key handles are returned in `jsonOut`. Handles are
+   * used to reference a PKCS11 object, such as a public or private key, and are valid during the
+   * PKCS11 session. To use the key in future PKCS11 sessions, your application would need to find
+   * the object to get a new handle.
+   *
+   * See the example linked below for more details.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Pkcs11.lastErrorText}.
+   */
+  genRsaKey(publicAttrs: JsonObject, privateAttrs: JsonObject, jsonOut: JsonObject, pubKey: PublicKey): void
+
+  /**
+   * Generate an EC key pair suitable for signing data and verifying signatures. The private key is
+   * created on the HSM (smart card or token), and the public key is returned in `pubKey`. The
+   * `publicAttrs` and `privateAttrs` contain attributes for the public and private keys
+   * respectively. The PKCS11 public and private key handles are returned in `jsonOut`. Handles are
+   * used to reference a PKCS11 object, such as a public or private key, and are valid during the
+   * PKCS11 session. To use the key in future PKCS11 sessions, your application would need to find
+   * the object to get a new handle.
+   *
+   * See the example linked below for more details.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Pkcs11.lastErrorText}.
+   */
+  genEcKey(publicAttrs: JsonObject, privateAttrs: JsonObject, jsonOut: JsonObject, pubKey: PublicKey): void
+
+  /**
+   * Creates an object and returns the handle. The `attrs` specifies the attributes that define the
+   * object to be created. See the linked examples below for more information.
+   */
+  createPkcs11Object(attrs: JsonObject): number
+
+  /**
+   * Quickly establishes a session on the 1st unempty slot, with or without login. If the `pin` is
+   * the empty string, then no login will take place. The `userType` can be one of the following
+   * integer values:
+   *
+   * - Security Officer (0)
+   *
+   * - Normal User (1)
+   *
+   * - Context Specific (2)
+   *
+   * Except for special circumstances, you should always select Normal User. If `pin` is the empty
+   * string, then no login takes place and `userType` is ignored.
+   *
+   * Calling this method takes the place of making separate calls to Initialize, OpenSession, and
+   * Login.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Pkcs11.lastErrorText}.
+   */
+  quickSession(userType: number, pin: string): void
+
+  /**
+   * Imports a private key onto the HSM. Returns the handle of the unwrapped key, or 0 if failed.
+   * See the linked example below for more details.
+   */
+  importPrivateKey(privKey: PrivateKey, jsonTemplate: JsonObject): number
+
+  /**
+   * Destroys an object (deletes it from the HSM). `hObject` is the object's handle.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Pkcs11.lastErrorText}.
+   */
+  destroyObject(hObject: number): void
+
+  /**
+   * General function for finding an object such as a private key. Returns the handle of the first
+   * matching object, or 0 if not found.
+   */
+  findObject(jsonTemplate: JsonObject): number
+
+  /**
+   * Imports an SSH private key onto the HSM. Returns the handle of the unwrapped key, or 0 if
+   * failed.
+   */
+  importSshKey(sshKey: SshKey, jsonTemplate: JsonObject): number
+
+  /**
+   * Export a public key given a public or private key handle. The `pubKey` is loaded with the
+   * exported public key.
+   *
+   * See the example linked below for more details.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Pkcs11.lastErrorText}.
+   */
+  exportPublicKey(keyHandle: number, pubKey: PublicKey): void
+}