@chilkat/react-native 11.6.1

package/src/specs/EdDSA.nitro.ts

@@ -0,0 +1,273 @@
+// Generated by ReactNativeNs.RnGenerator -- do not edit.
+import type { HybridObject } from 'react-native-nitro-modules'
+import type { BinData } from './BinData.nitro'
+import type { PrivateKey } from './PrivateKey.nitro'
+import type { Prng } from './Prng.nitro'
+import type { PublicKey } from './PublicKey.nitro'
+
+/**
+ * Generate Ed25519 keys, sign data, verify signatures, and compute shared secrets.
+ *
+ * `EdDSA` is the Chilkat class for Ed25519-based EdDSA
+ * operations. It can generate Ed25519 private keys, sign data contained in
+ * `BinData`, verify encoded signatures with public keys, and compute
+ * encoded shared secrets from compatible private/public key pairs. It supports
+ * the Ed25519, Ed25519ph, and Ed25519ctx variants, with optional context bytes
+ * supplied as a hex string when the selected variant requires them.
+ *
+ * **Generate Ed25519 keys**
+ *
+ * Create Ed25519 private keys for signing, verification, and compatible
+ * key-agreement workflows.
+ *
+ * **Sign BinData**
+ *
+ * Sign binary data directly from a `Chilkat.BinData` object
+ * using an Ed25519 private key.
+ *
+ * **Verify signatures**
+ *
+ * Verify encoded EdDSA signatures using the corresponding public key and
+ * the original message data.
+ *
+ * **Ed25519 variants**
+ *
+ * Use Ed25519, Ed25519ph, or Ed25519ctx depending on the protocol or
+ * interoperability requirements.
+ *
+ * **Context support**
+ *
+ * Supply optional context bytes as a hex string for workflows that use the
+ * Ed25519ctx or related context-aware signing modes.
+ *
+ * **Shared-secret output**
+ *
+ * Compute encoded shared secrets from compatible private and public key
+ * pairs for protocols that require this operation.
+ *
+ * **Common pattern:**
+ * Generate or load an Ed25519 key, choose the required EdDSA variant, provide
+ * context bytes when needed, then sign or verify the `BinData`
+ * content. For shared-secret workflows, compute the encoded secret and pass it
+ * through the key derivation or formatting step required by the protocol.
+ *
+ * For an extended overview, see
+ * [EdDSA Class Overview](https://www.chilkatsoft.com/eddsa_class_overview.asp).
+ *
+ * Each `EdDSA` 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 EdDSA()`.
+ */
+export interface EdDSA 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
+
+  /**
+   * Selects the Ed25519 signature variant used by {@link EdDSA.signBdENC} and {@link
+   * EdDSA.verifyBdENC}. The default is `Ed25519`.
+   *
+   * ValueBehaviorContext
+   *
+   * | `Ed25519` | | The standard pure Ed25519 signature scheme. The complete message is signed
+   * directly by the Ed25519 algorithm. | | A context is not part of this variant and should be
+   * empty. |
+   *
+   * | `Ed25519ctx` | | Pure Ed25519 with domain separation supplied by a context string. | | The
+   * context should normally be nonempty and must match exactly during verification. |
+   *
+   * | `Ed25519ph` | | Prehash Ed25519. Chilkat first hashes the message with SHA-512 as defined for
+   * this variant. | | May be empty or contain up to 255 context bytes; it must match exactly during
+   * verification. |
+   *
+   * **Interoperability requirement:** The signer and verifier must select the same variant. An
+   * Ed25519ph signature cannot be verified as ordinary Ed25519, even if the same key and message
+   * are used.
+   *
+   * **Scope:** This property selects a signing variant; it does not change the type of key
+   * generated by {@link EdDSA.genEd25519Key} and does not affect {@link EdDSA.sharedSecretENC}.
+   */
+  algorithm: string
+
+  /**
+   * Gets or sets the context bytes used by the Ed25519ctx and Ed25519ph signature variants. Supply
+   * the bytes as a hexadecimal string. The default is an empty string.
+   *
+   * A context may contain at most 255 bytes, which corresponds to at most 510 hexadecimal
+   * characters. The same context bytes must be supplied byte-for-byte when verifying the signature.
+   * An invalid hexadecimal value or an oversized context causes the signing or verification
+   * operation to fail.
+   *
+   * **Domain separation:** A context is a public protocol label that separates signatures created
+   * for different purposes, applications, or message types. It is not a password, secret key, salt,
+   * or part of the message payload.
+   *
+   * **Algorithm interaction:** Use this property only when {@link EdDSA.algorithm} is `Ed25519ctx`
+   * or `Ed25519ph`. Standard `Ed25519` does not include a context.
+   */
+  context: string
+
+  // ---- Methods ----
+
+  /**
+   * Generates a new Ed25519 key pair using `prng` as the source of cryptographically secure random
+   * bytes. On success, the generated private key and its corresponding public key are stored in the
+   * existing `PrivateKey` object passed in `privKey`.
+   *
+   * Returns `_TRUE_` on success and `_FALSE_` on failure. If the method fails, inspect
+   * `LastErrorText` for details.
+   *
+   * **Ed25519 key size:** Ed25519 key generation begins with a 32-byte private-key seed from which
+   * the public key is derived. Exported PEM, DER, JWK, or other key formats may contain additional
+   * structure and metadata, so their serialized size is not necessarily 32 bytes.
+   *
+   * **Protect the private key:** The generated private key can create signatures on behalf of its
+   * owner. Store it securely and disclose only the corresponding public key.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link EdDSA.lastErrorText}.
+   */
+  genEd25519Key(prng: Prng, privKey: PrivateKey): void
+
+  /**
+   * Creates an EdDSA signature over the exact byte sequence contained in `bd`, using the Ed25519
+   * private key in `privkey`. The 64-byte signature is returned as text using the binary encoding
+   * named by `encoding`, such as `hex`, `hexlower`, or `base64`.
+   *
+   * The selected {@link EdDSA.algorithm} and {@link EdDSA.context} properties determine whether the
+   * operation uses Ed25519, Ed25519ctx, or Ed25519ph. For Ed25519ph, pass the original message
+   * bytes in `bd`; Chilkat performs the required SHA-512 prehash as part of the Ed25519ph
+   * operation.
+   *
+   * **Deterministic signatures:** Ed25519 signatures do not require a caller-supplied per-message
+   * random number. With the same private key, message, algorithm variant, and context, the
+   * signature is deterministic.
+   *
+   * **Ed25519ph is a distinct variant:** It is not equivalent to hashing the message yourself and
+   * then signing that digest with ordinary Ed25519. Ed25519ph includes variant-specific domain
+   * separation.
+   *
+   * This is a string-returning method. Check `LastMethodSuccess` before using the returned value;
+   * on failure, inspect `LastErrorText`.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link EdDSA.lastErrorText}.
+   */
+  signBdENC(bd: BinData, encoding: string, privkey: PrivateKey): string
+
+  /**
+   * Verifies the encoded EdDSA signature in `encodedSig` against the exact byte sequence contained
+   * in `bd`, using the Ed25519 public key in `pubkey`. `enocding` names the binary encoding of
+   * `encodedSig`, such as `hex`, `hexlower`, or `base64`.
+   *
+   * The verifier must use the same {@link EdDSA.algorithm} and {@link EdDSA.context} values that
+   * were used to create the signature. Any change to the message, signature, public key, algorithm
+   * variant, or context causes verification to fail.
+   *
+   * Returns `_TRUE_` only when the signature is valid. Returns `_FALSE_` for an invalid signature
+   * or an operational error, such as malformed encoded input, an unsupported encoding, or an
+   * unsuitable key. Inspect `LastErrorText` for diagnostic information.
+   *
+   * **Trust remains an application decision:** A valid signature proves that the message matches
+   * the supplied public key. The application must still establish that the public key belongs to
+   * the expected signer.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link EdDSA.lastErrorText}.
+   */
+  verifyBdENC(bd: BinData, encodedSig: string, enocding: string, pubkey: PublicKey): void
+
+  /**
+   * Computes a 32-byte X25519 shared secret from the private key in `privkey` and the peer's public
+   * key in `pubkey`. The resulting bytes are returned as text using the binary encoding named by
+   * `encoding`, such as `hex`, `hexlower`, or `base64`.
+   *
+   * Each participant supplies its own private key and the other participant's public key. When
+   * Alice computes the secret from Alice's private key and Bob's public key, and Bob computes it
+   * from Bob's private key and Alice's public key, both obtain the same result.
+   *
+   * **X25519, not an EdDSA signature operation:** This method performs Curve25519 Diffie-Hellman
+   * key agreement. It is separate from the Ed25519, Ed25519ctx, and Ed25519ph signature variants,
+   * so the {@link EdDSA.algorithm} and {@link EdDSA.context} properties do not apply.
+   *
+   * **Do not normally use the raw secret directly:** A protocol should pass the shared secret
+   * through its specified key-derivation function and should authenticate the participants' public
+   * keys. Key agreement by itself does not establish the peer's identity.
+   *
+   * This is a string-returning method. Check `LastMethodSuccess` before using the returned value;
+   * on failure, inspect `LastErrorText`.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link EdDSA.lastErrorText}.
+   */
+  sharedSecretENC(privkey: PrivateKey, pubkey: PublicKey, encoding: string): string
+}