@chilkat/react-native 11.6.1

package/src/specs/Rsa.nitro.ts

@@ -0,0 +1,453 @@
+// 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 { PrivateKey } from './PrivateKey.nitro'
+import type { PublicKey } from './PublicKey.nitro'
+
+/**
+ * Encrypt, decrypt, sign, verify, and generate RSA keys.
+ *
+ * Use `Rsa` when an application needs direct RSA
+ * cryptographic operations. It can encrypt data with a public key, decrypt with
+ * a private key, create RSA signatures, verify signatures, sign precomputed
+ * hashes, verify signed hashes, and generate RSA key pairs. It also works with
+ * keys supplied directly as `PrivateKey` or `PublicKey`
+ * objects, or indirectly through certificates.
+ *
+ * **RSA encryption**
+ *
+ * Encrypt data with a public key for workflows where only the matching
+ * private key should be able to decrypt the result.
+ *
+ * **RSA decryption**
+ *
+ * Decrypt RSA-encrypted data using a private key, including keys loaded
+ * directly or accessed through a certificate.
+ *
+ * **Sign and verify data**
+ *
+ * Create and verify RSA signatures over data using the hash algorithm and
+ * padding mode required by the application or protocol.
+ *
+ * **Sign precomputed hashes**
+ *
+ * Sign or verify already-computed message digests when the hashing step is
+ * performed separately or by another component.
+ *
+ * **Generate RSA keys**
+ *
+ * Generate RSA key pairs for applications that need new public/private key
+ * material.
+ *
+ * **Certificate-backed keys**
+ *
+ * Use RSA keys associated with certificates, including non-exportable
+ * private keys in smart cards, USB tokens, Windows stores, or Apple
+ * Keychain.
+ *
+ * **Common pattern:**
+ * Load or generate the RSA key material, configure the padding, hash, charset,
+ * and encoding options needed by the protocol, then call the method matching
+ * the operation: encrypt, decrypt, sign, verify, sign-hash, or verify-hash.
+ * Use `Rsa` for direct RSA operations; use higher-level
+ * classes such as `Crypt2`, `Jws`, `Jwt`, or
+ * `Mime` when the RSA operation is part of a larger format or
+ * protocol.
+ *
+ * For an extended overview, see
+ * [Rsa Class Overview](https://www.chilkatsoft.com/rsa_class_overview.asp).
+ *
+ * Each `Rsa` 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 Rsa()`.
+ */
+export interface Rsa 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
+
+  /**
+   * This property specifies the character encoding used to represent text as bytes for encryption,
+   * decryption, signing, and signature validation. By default, it uses the computer's `ANSI`
+   * charset, such as Windows-1252 for locales like the United States, United Kingdom, Western
+   * Europe, Australia, and New Zealand.
+   *
+   * Most applications are advised to set this property to `UTF-8`. Chilkat plans to change its
+   * default to UTF-8 in a future major version to align with current standards. The current default
+   * of ANSI stems from a time when UTF-8 was not widely adopted.
+   */
+  charset: string
+
+  /**
+   * This property defines the encoding for methods ending in `ENC`, such as EncryptStringENC. Valid
+   * modes include `base64`, `hex`, `hex_lower`, and more. The encoding mode applies to signatures,
+   * encrypted data, and hashes used in or returned by a method.
+   */
+  encodingMode: string
+
+  /**
+   * When creating RSA signatures, this property determines the endianness: set it to `true` for
+   * little-endian signatures and `false` for big-endian signatures.
+   */
+  littleEndian: boolean
+
+  /**
+   * If `true`, skips unpadding when decrypting. The default is `false`. This property value is
+   * typically left unchanged.
+   */
+  noUnpad: boolean
+
+  /**
+   * The bit length, such as 2048, of the imported or generated RSA key.
+   *
+   * This property is read-only.
+   */
+  readonly numBits: number
+
+  /**
+   * Selects the hash algorithm for use within OAEP padding for encryption. The valid choices are
+   * `sha256`, `sha384`, `sha512`, or `sha1`.
+   *
+   * The default is SHA1. You'll likely want to change this to to SHA256. The next major version of
+   * Chilkat (11.0.0) will change the default to SHA256.
+   */
+  oaepHash: string
+
+  /**
+   * Selects the MGF (mask generation) hash algorithm for use within OAEP padding for encryption.
+   * The valid choices are `sha256`, `sha384`, `sha512`, or `sha1`.
+   *
+   * Note: This property should typically be set to the same value as the OaepHash property. Many
+   * software implementations are not able to handle cases where the MGF hash is different than the
+   * OAEP hash.
+   *
+   * The default is SHA1. You'll likely want to change this to to SHA256. The next major version of
+   * Chilkat (11.0.0) will change the default to SHA256.
+   */
+  oaepMgfHash: string
+
+  /**
+   * When using RSASSA-PSS padding for signatures, you can choose the PSS salt length. By default,
+   * the salt length is set to -1, which uses the length of the hash function. For instance, with
+   * the SHA256 hash function, the salt length will be 32 bytes. You can specify a different salt
+   * length, like 20 bytes, if needed, but it's generally recommended to keep the default setting.
+   */
+  pssSaltLen: number
+
+  /**
+   * The optional RSA encryption OAEP label is a hex representation of the label bytes used for
+   * encrypting with OAEP padding. Typically, this is left empty (0 bytes) unless there's a specific
+   * requirement to set it.
+   */
+  oaepLabel: 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
+
+  /**
+   * This property controls padding for both signing and encryption. The default value is true,
+   * which is to use PKCS#1 v1.5 padding. If set to false, then PSS padding is used for signatures
+   * and OAEP padding is used for encryption.
+   *
+   * This property replaces the deprecated `OaepPadding` property. Until the OaepPadding property is
+   * removed, setting this property will automatically set OaepPadding to the opposite, and
+   * vice-versa. This is to maintain backward compatibility until applications can switch to using
+   * this new property.
+   */
+  pkcsPadding: boolean
+
+  // ---- Methods ----
+
+  /**
+   * Decrypts `str` with the RSA algorithm. `str` is the encoded form of the encrypted binary data.
+   * The EncodingMode property defines `str`'s encoding. The Charset property specifies the byte
+   * representation for interpreting the decrypted text. Set `usePrivateKey` to `true` to use the
+   * private key for decryption; otherwise, set `usePrivateKey` to `false` to use the public key
+   * (used rarely). Returns the decrypted string.
+   *
+   * **Important:** If trying to match OpenSSL results, set the LittleEndian property = `false`.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Rsa.lastErrorText}.
+   */
+  decryptStringENC(str: string, usePrivateKey: boolean): string
+
+  /**
+   * Encrypts `str` with the RSA algorithm. The Charset property specifies the byte representation
+   * of the string that is encrypted. Set `bUsePrivateKey` to `false` to use the public key for
+   * encrypting; otherwise, set it to `true` to use the private key (in rare cases). The encrypted
+   * data is returned in the format specified by the EncodingMode property.
+   *
+   * **Important:** If trying to match OpenSSL results, set the LittleEndian property = `false`.
+   *
+   * **Note:** The public key's role is to make encryption accessible to anyone while ensuring that
+   * only the private key holder can decrypt the messages. The public key is designed to be widely
+   * distributed so anyone can use it to encrypt messages intended for the owner of the private key.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Rsa.lastErrorText}.
+   */
+  encryptStringENC(str: string, bUsePrivateKey: boolean): string
+
+  /**
+   * This function creates an RSA digital signature for the hash provided in `encodedHash`, which
+   * should be encoded according to the EncodingMode setting (e.g., base64 if EncodingMode =
+   * `base64`). `hashAlg` specifies the hash algorithm and can be `sha256`, `sha384`, `sha512`, or
+   * `sha1`. The function returns the signature encoded as specified by EncodingMode.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Rsa.lastErrorText}.
+   */
+  signHashENC(encodedHash: string, hashAlg: string): string
+
+  /**
+   * Generates an RSA digital signature by first hashing `strToBeHashed` with the hash algorithm
+   * specified by `hashAlgorithm`, which can be `sha256`, `sha384`, `sha512`, or `sha1`. Returns the
+   * signature encoded based on the EncodingMode property.
+   *
+   * **
+   *
+   * Note:** It is important to be aware of endianness. Make sure the LittleEndian property is set
+   * according to your specific needs.
+   *
+   * **Note:** It is recommended to set the Charset property equal to `utf-8` before signing
+   * strings.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Rsa.lastErrorText}.
+   */
+  signStringENC(strToBeHashed: string, hashAlgorithm: string): string
+
+  /**
+   * Imports a .snk file to an XML document that can be imported via the ImportPrivateKey method.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Rsa.lastErrorText}.
+   */
+  snkToXml(filename: string): string
+
+  /**
+   * Validates an RSA signature provided in `encodedSig` against the hash of the original data in
+   * `encodedHash`. Returns `true` if validation is successful, otherwise returns `false`. `hashAlg`
+   * specifies the hash algorithm used for `encodedHash`, such as `sha256`, `sha384`, `sha512`, or
+   * `sha1`. Ensure the hash's size (e.g., 32 bytes for sha256, 48 bytes for sha384, 64 bytes for
+   * sha512, 20 bytes for sha1) matches that of `encodedHash`.
+   *
+   * Both `encodedHash` and `encodedSig` should be encoded according to the EncodingMode property
+   * (e.g., base64 if EncodingMode = `base64`)
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Rsa.lastErrorText}.
+   */
+  verifyHashENC(encodedHash: string, hashAlg: string, encodedSig: string): void
+
+  /**
+   * Verifies the encoded RSA signature passed in `encodedSig` against the original data passed in
+   * `originalString`. The original data passed in `originalString` is hashed using the hash
+   * algorithm passed in `hashAlgorithm` (such as `sha256`, `sha384`, `sha512`, or `sha1`). Returns
+   * `true` if the signature is validated, and `false` if not.
+   *
+   * The signature passed in `encodedSig` should be encoded according to the EncodingMode property
+   * (e.g., base64 if EncodingMode = `base64`)
+   *
+   * Note: Knowing the exact hash algorithm used to create the signature is not required. If the
+   * signature is not validated using the hash algorithm specified in `hashAlgorithm`, Chilkat will
+   * automatically try validating using the other supported algorithms and return success if any
+   * validate.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Rsa.lastErrorText}.
+   */
+  verifyStringENC(originalString: string, hashAlgorithm: string, encodedSig: string): void
+
+  /**
+   * Provides the private or public key indirectly through a certificate. This method is used when
+   * the private key is inaccessible, such as when stored on a smart card, USB token, in the Windows
+   * registry (marked as non-exportable), or in the Apple Keychain.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Rsa.lastErrorText}.
+   */
+  setX509Cert(cert: Cert, usePrivateKey: boolean): void
+
+  /**
+   * RSA decrypts the contents of `bd`. `usePrivateKey` should be set to `true` if the private key
+   * is to be used for decrypting. Otherwise it should be set to `false` if (in rare cases) the
+   * public key is to be used for decrypting.
+   *
+   * **Important:** If trying to match OpenSSL results, set the LittleEndian property = `false`.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Rsa.lastErrorText}.
+   */
+  decryptBd(bd: BinData, usePrivateKey: boolean): void
+
+  /**
+   * RSA encrypts the contents of `bd`. Set `usePrivateKey` to `false` to use the public key for
+   * encrypting; otherwise, set it to `true` to use the private key (in rare cases).
+   *
+   * **Important:** If trying to match OpenSSL results, set the LittleEndian property = `false`.
+   *
+   * **Note:** The public key's role is to make encryption accessible to anyone while ensuring that
+   * only the private key holder can decrypt the messages. The public key is designed to be widely
+   * distributed so anyone can use it to encrypt messages intended for the owner of the private key.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Rsa.lastErrorText}.
+   */
+  encryptBd(bd: BinData, usePrivateKey: boolean): void
+
+  /**
+   * Generates an RSA digital signature by first hashing the contents of `bdData` with the hash
+   * algorithm specified by `hashAlgorithm`, which can be `sha256`, `sha384`, `sha512`, or `sha1`.
+   * The resulting signature is written to `bdSig`.
+   *
+   * Note: It is important to be aware of endianness. Make sure the LittleEndian property is set
+   * according to your specific needs.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Rsa.lastErrorText}.
+   */
+  signBd(bdData: BinData, hashAlgorithm: string, bdSig: BinData): void
+
+  /**
+   * Verifies the RSA signature passed in `bdSig` against the original data passed in `bdData`. The
+   * original data passed in `bdData` is hashed using the hash algorithm passed in `hashAlgorithm`
+   * (such as `sha256`, `sha384`, `sha512`, or `sha1`). Returns `true` if the signature is
+   * validated, and `false` if not.
+   *
+   * Note: Knowing the exact hash algorithm used to create the signature is not required. If the
+   * signature is not validated using the hash algorithm specified in `hashAlgorithm`, Chilkat will
+   * automatically try validating using the other supported algorithms and return success if any
+   * validate.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Rsa.lastErrorText}.
+   */
+  verifyBd(bdData: BinData, hashAlgorithm: string, bdSig: BinData): void
+
+  /**
+   * Generates a new RSA key and stores it in `privKey`. `numBits` specifies the key length, which
+   * can range from 512 to 8192 bits. Common key lengths are 1024, 2048, or 4096 bits.
+   *
+   * Note: Generating an 8192-bit key may take a significant amount of time. The method does not
+   * support event callbacks or progress monitoring and will block the thread until completion.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Rsa.lastErrorText}.
+   */
+  genKey(numBits: number, privKey: PrivateKey): void
+
+  /**
+   * Imports a private key from `privKey` to use for signing or decrypting.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Rsa.lastErrorText}.
+   */
+  usePrivateKey(privKey: PrivateKey): void
+
+  /**
+   * Imports a public key from `pubKey` to use for encrypting or signature verification.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Rsa.lastErrorText}.
+   */
+  usePublicKey(pubKey: PublicKey): void
+
+  /**
+   * This is legacy low-level raw RSA that duplicates the (now deprecated) `OpenSSL` `rsautl`
+   * utility. It directly signs raw data rather than signing a hash of the data. PKCS#1 v1.5 padding
+   * is always used. The data to be signed is passed in `bd`, and on return the content of `bd` is
+   * replaced with the RSA signed data.
+   *
+   * Note: It is possible to validate and recover the original data by calling `VerifyRawBd`.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Rsa.lastErrorText}.
+   */
+  signRawBd(bd: BinData): void
+
+  /**
+   * This is legacy low-level raw RSA that duplicates the (now deprecated) `OpenSSL` `rsautl`
+   * utility. It validates signed raw data and recovers the original data. The RSA signature to be
+   * verified is passed in `bd`, and on return the content of `bd` is replaced with the original
+   * data.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Rsa.lastErrorText}.
+   */
+  verifyRawBd(bd: BinData): void
+}