@chilkat/react-native 11.6.1

package/src/specs/Csr.nitro.ts

@@ -0,0 +1,461 @@
+// 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 { PublicKey } from './PublicKey.nitro'
+import type { StringTable } from './StringTable.nitro'
+import type { Xml } from './Xml.nitro'
+
+/**
+ * Create, load, inspect, and verify Certificate Signing Requests.
+ *
+ * `Csr` is the Chilkat class for working with Certificate
+ * Signing Requests. It can create CSRs from RSA or ECDSA private keys, set
+ * common certificate subject fields, add custom subject fields by OID, include
+ * Subject Alternative Names, request certificate extensions, export CSRs in
+ * PEM or DER format, load existing CSRs, extract the public key, inspect SAN
+ * values, and verify the CSR signature.
+ *
+ * **Create CSRs**
+ *
+ * Generate certificate signing requests using RSA or ECDSA private keys
+ * and the subject fields required by the certificate authority.
+ *
+ * **Subject fields**
+ *
+ * Set common X.509 subject fields such as common name, organization,
+ * organizational unit, locality, state, country, and email address.
+ *
+ * **Custom OID fields**
+ *
+ * Add custom subject attributes by object identifier when a certificate
+ * authority or application profile requires nonstandard fields.
+ *
+ * **Subject Alternative Names**
+ *
+ * Include DNS names, IP addresses, email addresses, URIs, or other SAN
+ * entries needed for modern TLS and identity certificates.
+ *
+ * **Extension requests**
+ *
+ * Request certificate extensions that the issuing CA may include in the
+ * final certificate.
+ *
+ * **Inspect and verify**
+ *
+ * Load an existing CSR, extract its public key, inspect requested names and
+ * fields, and verify that the CSR signature is valid.
+ *
+ * **Common pattern:**
+ * Create or load a private key, populate the subject and SAN values required
+ * by the certificate authority, generate the CSR in PEM or DER format, submit
+ * it to the CA, and keep the private key secure because it will be needed when
+ * using the issued certificate.
+ *
+ * For an extended overview, see
+ * [Csr Class Overview](https://www.chilkatsoft.com/csr_class_overview.asp).
+ *
+ * Each `Csr` 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 Csr()`.
+ */
+export interface Csr 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
+
+  /**
+   * Gets or sets the subject common name (`CN`), OID `2.5.4.3`, for the CSR. For a TLS server
+   * request this has traditionally been a DNS hostname; for other certificate profiles it may
+   * identify a person, device, service, or organization.
+   *
+   * Chilkat requires this property when generating a CSR. The exact value and validation rules are
+   * determined by the certificate authority and certificate profile.
+   *
+   * **Do not use CN as a substitute for SAN:** For modern TLS certificates, add every DNS hostname
+   * or IP address through {@link Csr.addSan}. Current TLS identity verification uses Subject
+   * Alternative Name entries, and the common name is retained primarily for compatibility and
+   * display.
+   */
+  commonName: string
+
+  /**
+   * Gets or sets the subject country name (`C`), OID `2.5.4.6`. The value is normally a two-letter
+   * uppercase ISO 3166-1 country code, such as `US`, `CA`, or `DE`.
+   *
+   * This property is optional unless required by the certificate authority's enrollment profile.
+   *
+   * **X.520 encoding:** The country-name attribute is defined as a two-character `PrintableString`.
+   * Do not place a full country name such as `United States` in this field.
+   */
+  country: string
+
+  /**
+   * Gets or sets the subject state or province name (`ST`, sometimes displayed as `S`), OID
+   * `2.5.4.8`.
+   *
+   * This property is optional unless required by the certificate authority. Use the full
+   * jurisdiction name expected by the CA, such as `Illinois`, rather than assuming an abbreviation
+   * is accepted.
+   */
+  state: string
+
+  /**
+   * Gets or sets the subject locality name (`L`), OID `2.5.4.7`. This usually identifies a city,
+   * town, or other local jurisdiction.
+   *
+   * This property is optional unless required by the certificate authority's enrollment profile.
+   */
+  locality: string
+
+  /**
+   * Gets or sets the subject organization name (`O`), OID `2.5.4.10`. For organization-validated
+   * certificate profiles, this is typically the legal or verified organization name.
+   *
+   * This property is optional at the PKCS #10 level, but a certificate authority may require it or
+   * replace it with a value established during identity validation.
+   */
+  company: string
+
+  /**
+   * Gets or sets the subject organizational unit name (`OU`), OID `2.5.4.11`. It may identify a
+   * department, division, team, or other unit within the organization.
+   *
+   * This property is optional. Some public certificate profiles restrict or omit
+   * organizational-unit values, so follow the requirements of the receiving CA.
+   */
+  companyDivision: string
+
+  /**
+   * Gets or sets the legacy PKCS #9 `emailAddress` subject attribute, OID `1.2.840.113549.1.9.1`.
+   * This property is optional.
+   *
+   * **Prefer an email SAN for email identity:** The subject-DN `emailAddress` attribute is
+   * permitted for legacy compatibility but is deprecated in the Internet X.509 profile. When the
+   * certificate must identify an email address, also use {@link Csr.addSan} with `rfc822Name`, as
+   * required by the target certificate profile.
+   */
+  emailAddress: string
+
+  /**
+   * Gets or sets the message-digest algorithm used when signing a generated CSR. Supported values
+   * are `sha1`, `sha256`, `sha384`, and `sha512`. The default is `sha256`.
+   *
+   * This property selects the digest for the CSR's proof-of-possession signature. It does not
+   * select the signature algorithm that the certificate authority will use on the issued
+   * certificate.
+   *
+   * **Avoid SHA-1 for new requests:** Use `sha256` or stronger unless a legacy enrollment system
+   * explicitly requires SHA-1. The digest must also be compatible with the supplied key type and
+   * the receiving CA.
+   */
+  hashAlgorithm: string
+
+  /**
+   * Controls the RSA signature scheme used when generating a CSR with an RSA private key. When
+   * `true`, Chilkat signs using RSASSA-PSS. When `false`, the RSA signature uses the traditional
+   * RSASSA-PKCS1-v1_5 scheme. This property has no effect for elliptic-curve keys.
+   *
+   * **Related settings:** {@link Csr.hashAlgorithm} selects the digest of the certification-request
+   * information. When PSS is enabled, {@link Csr.mgfHashAlg} selects the digest used by MGF1.
+   *
+   * **Interoperability:** RSASSA-PSS is a modern RSA signature scheme, but the receiving CA or
+   * enrollment protocol must support PSS algorithm parameters in PKCS #10 requests.
+   */
+  pssPadding: boolean
+
+  /**
+   * Gets or sets the hash algorithm used by MGF1 in an RSASSA-PSS CSR signature. This property
+   * applies only when the private key is RSA and {@link Csr.pssPadding} is `true`.
+   *
+   * Supported values are `sha256`, `sha384`, and `sha512`. The default is `sha256`.
+   *
+   * **Common choice:** For straightforward interoperability, set this to the same digest selected
+   * by {@link Csr.hashAlgorithm} unless the receiving profile explicitly specifies different
+   * RSASSA-PSS parameters.
+   */
+  mgfHashAlg: string
+
+  // ---- Methods ----
+
+  /**
+   * Generates a PKCS #10 Certificate Signing Request using the supplied `PrivateKey` and the
+   * subject fields, Subject Alternative Names, extension request, and signature settings currently
+   * configured on this object. The private key may be RSA or elliptic-curve (ECDSA).
+   *
+   * On success, returns the CSR in PEM form, normally enclosed by `-----BEGIN CERTIFICATE
+   * REQUEST-----` and `-----END CERTIFICATE REQUEST-----` lines. The Base64 body is the DER-encoded
+   * PKCS #10 request.
+   *
+   * **What a CSR contains:** A CSR contains the subject name, the public key derived from
+   * `privKey`, optional attributes such as requested extensions, and a signature made with the
+   * corresponding private key. The private key itself is never included.
+   *
+   * **Signature settings:** {@link Csr.hashAlgorithm} selects the digest. For RSA keys, {@link
+   * Csr.pssPadding} and {@link Csr.mgfHashAlg} control whether RSASSA-PSS is used and which MGF1
+   * digest is encoded in its parameters.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Csr.lastErrorText}.
+   */
+  genCsrPem(privKey: PrivateKey): string
+
+  /**
+   * Generates a PKCS #10 Certificate Signing Request using the supplied RSA or elliptic-curve
+   * private key and writes the binary DER representation to `csrData`.
+   *
+   * The generated request uses the subject fields, Subject Alternative Names, extension request,
+   * and signature settings currently configured on this object. The DER bytes are the same request
+   * data that would appear as the Base64 body returned by {@link Csr.genCsrPem}.
+   *
+   * **DER versus PEM:** DER is the binary ASN.1 encoding of the CSR. PEM is that DER data encoded
+   * as Base64 with certificate-request header and footer lines. Use DER for binary protocols such
+   * as EST when required by the receiving system.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Csr.lastErrorText}.
+   */
+  genCsrBd(privKey: PrivateKey, csrData: BinData): void
+
+  /**
+   * Sets a subject distinguished-name attribute identified by `oid`. For example, OID `2.5.4.9`
+   * identifies \*streetAddress\*. Use the dedicated properties such as {@link Csr.commonName},
+   * {@link Csr.company}, and {@link Csr.country} for the commonly used subject attributes.
+   *
+   * `asnType` specifies the ASN.1 string type used to encode the value and may be `UTF8String`,
+   * `IA5String`, or `PrintableString`. Use `UTF8String` unless the attribute definition or
+   * certificate-authority profile requires another type.
+   *
+   * ASN.1 typeTypical use
+   *
+   * | `UTF8String` | | General Unicode text and the preferred default for most modern directory
+   * attributes. |
+   *
+   * | `IA5String` | | ASCII-based attributes whose schema specifically requires IA5String, such as
+   * the legacy PKCS #9 `emailAddress` attribute. |
+   *
+   * | `PrintableString` | | Attributes constrained to the limited PrintableString character set,
+   * such as the X.520 country name. |
+   *
+   * **Schema matters:** The OID determines the attribute's meaning and permitted syntax. A value
+   * can be valid text yet still be rejected by a CA if the selected ASN.1 type, length, or format
+   * does not match that attribute's schema or the CA's enrollment policy.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Csr.lastErrorText}.
+   */
+  setSubjectField(oid: string, value: string, asnType: string): void
+
+  /**
+   * Loads a PEM-encoded PKCS #10 Certificate Signing Request. On success, the subject properties
+   * and retrieval methods on this object reflect the values contained in the loaded request,
+   * including its public key, Subject Alternative Names, and extension-request attribute when
+   * present.
+   *
+   * **Loading is not verification:** Parsing a CSR does not prove that its signature is valid. Call
+   * {@link Csr.verifyCsr} to verify that the request was signed by the private key corresponding to
+   * the public key carried in the CSR.
+   *
+   * **No private key is loaded:** A PKCS #10 request contains only the public key and signature.
+   * The applicant must retain the original private key separately for use with the certificate
+   * issued by the CA.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Csr.lastErrorText}.
+   */
+  loadCsrPem(csrPemStr: string): void
+
+  /**
+   * Returns the value of a subject distinguished-name attribute from the currently loaded or
+   * configured CSR, identified by its object identifier. For example, OID `2.5.4.9` identifies
+   * \*streetAddress\*.
+   *
+   * **OID-based lookup:** The short names commonly displayed in certificate tools, such as `CN`,
+   * `O`, `OU`, and `C`, are labels for specific OIDs. This method uses the numeric OID so uncommon
+   * or application-specific attributes can also be retrieved.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Csr.lastErrorText}.
+   */
+  getSubjectField(oid: string): string
+
+  /**
+   * Copies the public key contained in the currently loaded CSR into `pubkey`. The resulting
+   * `PublicKey` object is independent of the CSR and contains no private-key material.
+   *
+   * **Proof of possession:** A PKCS #10 request is signed with the private key corresponding to
+   * this public key. Use {@link Csr.verifyCsr} to check that relationship; merely extracting the
+   * public key does not verify the CSR signature.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Csr.lastErrorText}.
+   */
+  getPublicKey(pubkey: PublicKey): void
+
+  /**
+   * Verifies the digital signature on the currently loaded CSR using the public key embedded in
+   * that request. Returns `true` when the signature is cryptographically valid; otherwise returns
+   * `false`.
+   *
+   * **What this proves:** Successful verification shows that the request was signed using the
+   * private key corresponding to the included public key and that the signed request data has not
+   * been altered.
+   *
+   * **What this does not prove:** Signature verification does not validate the applicant's
+   * identity, confirm control of a DNS name or email address, approve requested extensions,
+   * establish trust, or issue a certificate. Those checks and policy decisions belong to the
+   * certificate authority.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Csr.lastErrorText}.
+   */
+  verifyCsr(): void
+
+  /**
+   * Adds one Subject Alternative Name to the CSR that will be generated. Call this method once for
+   * each name to request. The SAN values are carried as requested certificate extensions; the
+   * issuing certificate authority decides whether to validate and include them in the final
+   * certificate.
+   *
+   * `sanType`Meaning and example
+   *
+   * | `dnsName` | | A DNS hostname, such as `www.example.com` or an allowed wildcard such as
+   * `*.example.com`. |
+   *
+   * | `IPAddress` |  | An IPv4 or IPv6 address, such as `192.0.2.10` or `2001:db8::10`. |
+   *
+   * | `rfc822Name` |  | An Internet email address, such as `user@example.com`. |
+   *
+   * | `uniformResourceIndicator` | | A URI. This is Chilkat's accepted keyword; the X.509
+   * `GeneralName` field is formally named `uniformResourceIdentifier`. |
+   *
+   * | `directoryName` |  | An X.500 distinguished name. |
+   *
+   * | `registeredID` |  | A registered object identifier. |
+   *
+   * | `otherName`, `x400Address`, `ediPartyName` | | Less common X.509 `GeneralName` forms used by
+   * specialized profiles. |
+   *
+   * **TLS server certificates:** Put every DNS name and IP address that clients must validate in
+   * the SAN extension. Modern TLS identity checking uses `dNSName` and `iPAddress` SAN entries
+   * rather than relying on the subject common name.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Csr.lastErrorText}.
+   */
+  addSan(sanType: string, sanValue: string): void
+
+  /**
+   * Retrieves the Subject Alternative Names requested by the currently loaded CSR and writes them
+   * to the supplied `StringTable`.
+   *
+   * **Requested, not issued:** These values are taken from the CSR's extension-request data. They
+   * describe what the applicant asked the CA to place in the certificate, not what a CA has
+   * validated or will necessarily issue.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Csr.lastErrorText}.
+   */
+  getSans(sans: StringTable): void
+
+  /**
+   * Sets the PKCS #9 `extensionRequest` attribute, OID `1.2.840.113549.1.9.14`, for the CSR to be
+   * generated. `extensionReqXml` supplies the requested X.509 extensions as ASN.1 represented in
+   * Chilkat XML form.
+   *
+   * **Purpose of extensionRequest:** PKCS #10 has no certificate-extension field of its own.
+   * Requested X.509 extensions, such as Subject Alternative Name, key usage, or extended key usage,
+   * are commonly carried in this signed attribute.
+   *
+   * **A request is not a command:** The certificate authority may ignore, modify, reject, or
+   * independently validate any requested extension according to its enrollment profile and security
+   * policy.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Csr.lastErrorText}.
+   */
+  setExtensionRequest(extensionReqXml: Xml): void
+
+  /**
+   * Retrieves the PKCS #9 `extensionRequest` attribute, OID `1.2.840.113549.1.9.14`, from the
+   * currently loaded CSR. When present, the requested extensions are loaded into `extensionReqXml`
+   * as Chilkat ASN.1 XML.
+   *
+   * **CSR contents only:** The returned XML describes extensions requested by the applicant. It
+   * does not show which extensions a certificate authority ultimately accepted or placed in an
+   * issued certificate.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link Csr.lastErrorText}.
+   */
+  getExtensionRequest(extensionReqXml: Xml): void
+}