@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gio/tls-database.d.ts

@@ -6,21 +6,244 @@ import { TlsCertificate } from "./tls-certificate.js";
 import { TlsInteraction } from "./tls-interaction.js";
 import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * `GTlsDatabase` is used to look up certificates and other information
+ * from a certificate or key store. It is an abstract base class which
+ * TLS library specific subtypes override.
+ *
+ * A `GTlsDatabase` may be accessed from multiple threads by the TLS backend.
+ * All implementations are required to be fully thread-safe.
+ *
+ * Most common client applications will not directly interact with
+ * `GTlsDatabase`. It is used internally by [class@Gio.TlsConnection].
+ */
 export declare class TlsDatabase extends GObject.GObject {
     constructor(...args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Create a handle string for the certificate. The database will only be able
+     * to create a handle for certificates that originate from the database. In
+     * cases where the database cannot create a handle for a certificate, %NULL
+     * will be returned.
+     *
+     * This handle should be stable across various instances of the application,
+     * and between applications. If a certificate is modified in the database,
+     * then it is not guaranteed that this handle will continue to point to it.
+     * @param certificate - certificate for which to create a handle.
+     */
     createCertificateHandle(certificate: TlsCertificate): string | null;
+    /**
+     * Look up a certificate by its handle.
+     *
+     * The handle should have been created by calling
+     * g_tls_database_create_certificate_handle() on a #GTlsDatabase object of
+     * the same TLS backend. The handle is designed to remain valid across
+     * instantiations of the database.
+     *
+     * If the handle is no longer valid, or does not point to a certificate in
+     * this database, then %NULL will be returned.
+     *
+     * This function can block, use g_tls_database_lookup_certificate_for_handle_async() to perform
+     * the lookup operation asynchronously.
+     * @param handle - a certificate handle
+     * @param interaction - used to interact with the user if necessary
+     * @param flags - Flags which affect the lookup.
+     * @param cancellable - a #GCancellable, or %NULL
+     */
     lookupCertificateForHandle(handle: string, flags: TlsDatabaseLookupFlags, interaction?: TlsInteraction | null, cancellable?: Cancellable | null): TlsCertificate | null;
+    /**
+     * Asynchronously look up a certificate by its handle in the database. See
+     * g_tls_database_lookup_certificate_for_handle() for more information.
+     * @param handle - a certificate handle
+     * @param interaction - used to interact with the user if necessary
+     * @param flags - Flags which affect the lookup.
+     * @param cancellable - a #GCancellable, or %NULL
+     * @param callback - callback to call when the operation completes
+     * @param userData - the data to pass to the callback function
+     */
     lookupCertificateForHandleAsync(handle: string, flags: TlsDatabaseLookupFlags, interaction?: TlsInteraction | null, cancellable?: Cancellable | null, callback?: (...args: unknown[]) => unknown | null, userData?: number | null): void;
+    /**
+     * Finish an asynchronous lookup of a certificate by its handle. See
+     * g_tls_database_lookup_certificate_for_handle() for more information.
+     *
+     * If the handle is no longer valid, or does not point to a certificate in
+     * this database, then %NULL will be returned.
+     * @param result - a #GAsyncResult.
+     */
     lookupCertificateForHandleFinish(result: AsyncResult): TlsCertificate;
+    /**
+     * Look up the issuer of `certificate` in the database. The
+     * #GTlsCertificate:issuer property of `certificate` is not modified, and
+     * the two certificates are not hooked into a chain.
+     *
+     * This function can block. Use g_tls_database_lookup_certificate_issuer_async()
+     * to perform the lookup operation asynchronously.
+     *
+     * Beware this function cannot be used to build certification paths. The
+     * issuer certificate returned by this function may not be the same as
+     * the certificate that would actually be used to construct a valid
+     * certification path during certificate verification.
+     * [RFC 4158](https://datatracker.ietf.org/doc/html/rfc4158) explains
+     * why an issuer certificate cannot be naively assumed to be part of the
+     * the certification path (though GLib's TLS backends may not follow the
+     * path building strategies outlined in this RFC). Due to the complexity
+     * of certification path building, GLib does not provide any way to know
+     * which certification path will actually be used when verifying a TLS
+     * certificate. Accordingly, this function cannot be used to make
+     * security-related decisions. Only GLib itself should make security
+     * decisions about TLS certificates.
+     * @param certificate - a #GTlsCertificate
+     * @param interaction - used to interact with the user if necessary
+     * @param flags - flags which affect the lookup operation
+     * @param cancellable - a #GCancellable, or %NULL
+     */
     lookupCertificateIssuer(certificate: TlsCertificate, flags: TlsDatabaseLookupFlags, interaction?: TlsInteraction | null, cancellable?: Cancellable | null): TlsCertificate;
+    /**
+     * Asynchronously look up the issuer of `certificate` in the database. See
+     * g_tls_database_lookup_certificate_issuer() for more information.
+     * @param certificate - a #GTlsCertificate
+     * @param interaction - used to interact with the user if necessary
+     * @param flags - flags which affect the lookup operation
+     * @param cancellable - a #GCancellable, or %NULL
+     * @param callback - callback to call when the operation completes
+     * @param userData - the data to pass to the callback function
+     */
     lookupCertificateIssuerAsync(certificate: TlsCertificate, flags: TlsDatabaseLookupFlags, interaction?: TlsInteraction | null, cancellable?: Cancellable | null, callback?: (...args: unknown[]) => unknown | null, userData?: number | null): void;
+    /**
+     * Finish an asynchronous lookup issuer operation. See
+     * g_tls_database_lookup_certificate_issuer() for more information.
+     * @param result - a #GAsyncResult.
+     */
     lookupCertificateIssuerFinish(result: AsyncResult): TlsCertificate;
+    /**
+     * Look up certificates issued by this issuer in the database.
+     *
+     * This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform
+     * the lookup operation asynchronously.
+     * @param issuerRawDn - a #GByteArray which holds the DER encoded issuer DN.
+     * @param interaction - used to interact with the user if necessary
+     * @param flags - Flags which affect the lookup operation.
+     * @param cancellable - a #GCancellable, or %NULL
+     */
     lookupCertificatesIssuedBy(issuerRawDn: GLib.ByteArray, flags: TlsDatabaseLookupFlags, interaction?: TlsInteraction | null, cancellable?: Cancellable | null): TlsCertificate[];
+    /**
+     * Asynchronously look up certificates issued by this issuer in the database. See
+     * g_tls_database_lookup_certificates_issued_by() for more information.
+     *
+     * The database may choose to hold a reference to the issuer byte array for the duration
+     * of this asynchronous operation. The byte array should not be modified during
+     * this time.
+     * @param issuerRawDn - a #GByteArray which holds the DER encoded issuer DN.
+     * @param interaction - used to interact with the user if necessary
+     * @param flags - Flags which affect the lookup operation.
+     * @param cancellable - a #GCancellable, or %NULL
+     * @param callback - callback to call when the operation completes
+     * @param userData - the data to pass to the callback function
+     */
     lookupCertificatesIssuedByAsync(issuerRawDn: GLib.ByteArray, flags: TlsDatabaseLookupFlags, interaction?: TlsInteraction | null, cancellable?: Cancellable | null, callback?: (...args: unknown[]) => unknown | null, userData?: number | null): void;
+    /**
+     * Finish an asynchronous lookup of certificates. See
+     * g_tls_database_lookup_certificates_issued_by() for more information.
+     * @param result - a #GAsyncResult.
+     */
     lookupCertificatesIssuedByFinish(result: AsyncResult): TlsCertificate[];
+    /**
+     * Determines the validity of a certificate chain, outside the context
+     * of a TLS session.
+     *
+     * `chain` is a chain of #GTlsCertificate objects each pointing to the next
+     * certificate in the chain by its #GTlsCertificate:issuer property.
+     *
+     * `purpose` describes the purpose (or usage) for which the certificate
+     * is being used. Typically `purpose` will be set to %G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER
+     * which means that the certificate is being used to authenticate a server
+     * (and we are acting as the client).
+     *
+     * The `identity` is used to ensure the server certificate is valid for
+     * the expected peer identity. If the identity does not match the
+     * certificate, %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the
+     * return value. If `identity` is %NULL, that bit will never be set in
+     * the return value. The peer identity may also be used to check for
+     * pinned certificates (trust exceptions) in the database. These may
+     * override the normal verification process on a host-by-host basis.
+     *
+     * Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be
+     * used.
+     *
+     * If `chain` is found to be valid, then the return value will be 0. If
+     * `chain` is found to be invalid, then the return value will indicate at
+     * least one problem found. If the function is unable to determine
+     * whether `chain` is valid (for example, because `cancellable` is
+     * triggered before it completes) then the return value will be
+     * %G_TLS_CERTIFICATE_GENERIC_ERROR and `error` will be set accordingly.
+     * `error` is not set when `chain` is successfully analyzed but found to
+     * be invalid.
+     *
+     * GLib guarantees that if certificate verification fails, at least one
+     * error will be set in the return value, but it does not guarantee
+     * that all possible errors will be set. Accordingly, you may not safely
+     * decide to ignore any particular type of error. For example, it would
+     * be incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow
+     * expired certificates, because this could potentially be the only
+     * error flag set even if other problems exist with the certificate.
+     *
+     * Prior to GLib 2.48, GLib's default TLS backend modified `chain` to
+     * represent the certification path built by #GTlsDatabase during
+     * certificate verification by adjusting the #GTlsCertificate:issuer
+     * property of each certificate in @chain. Since GLib 2.48, this no
+     * longer occurs, so you cannot rely on #GTlsCertificate:issuer to
+     * represent the actual certification path used during certificate
+     * verification.
+     *
+     * Because TLS session context is not used, #GTlsDatabase may not
+     * perform as many checks on the certificates as #GTlsConnection would.
+     * For example, certificate constraints may not be honored, and
+     * revocation checks may not be performed. The best way to verify TLS
+     * certificates used by a TLS connection is to let #GTlsConnection
+     * handle the verification.
+     *
+     * The TLS backend may attempt to look up and add missing certificates
+     * to the chain. This may involve HTTP requests to download missing
+     * certificates.
+     *
+     * This function can block. Use g_tls_database_verify_chain_async() to
+     * perform the verification operation asynchronously.
+     * @param chain - a #GTlsCertificate chain
+     * @param purpose - the purpose that this certificate chain will be used for.
+     * @param identity - the expected peer identity
+     * @param interaction - used to interact with the user if necessary
+     * @param flags - additional verify flags
+     * @param cancellable - a #GCancellable, or %NULL
+     */
     verifyChain(chain: TlsCertificate, purpose: string, flags: TlsDatabaseVerifyFlags, identity?: SocketConnectable | null, interaction?: TlsInteraction | null, cancellable?: Cancellable | null): TlsCertificateFlags;
+    /**
+     * Asynchronously determines the validity of a certificate chain after
+     * looking up and adding any missing certificates to the chain. See
+     * g_tls_database_verify_chain() for more information.
+     * @param chain - a #GTlsCertificate chain
+     * @param purpose - the purpose that this certificate chain will be used for.
+     * @param identity - the expected peer identity
+     * @param interaction - used to interact with the user if necessary
+     * @param flags - additional verify flags
+     * @param cancellable - a #GCancellable, or %NULL
+     * @param callback - callback to call when the operation completes
+     * @param userData - the data to pass to the callback function
+     */
     verifyChainAsync(chain: TlsCertificate, purpose: string, flags: TlsDatabaseVerifyFlags, identity?: SocketConnectable | null, interaction?: TlsInteraction | null, cancellable?: Cancellable | null, callback?: (...args: unknown[]) => unknown | null, userData?: number | null): void;
+    /**
+     * Finish an asynchronous verify chain operation. See
+     * g_tls_database_verify_chain() for more information.
+     *
+     * If `chain` is found to be valid, then the return value will be 0. If
+     * `chain` is found to be invalid, then the return value will indicate
+     * the problems found. If the function is unable to determine whether
+     * `chain` is valid or not (eg, because `cancellable` is triggered
+     * before it completes) then the return value will be
+     * %G_TLS_CERTIFICATE_GENERIC_ERROR and `error` will be set
+     * accordingly. `error` is not set when `chain` is successfully analyzed
+     * but found to be invalid.
+     * @param result - a #GAsyncResult.
+     */
     verifyChainFinish(result: AsyncResult): TlsCertificateFlags;
     connect(signal: "notify", handler: (self: TlsDatabase, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

package/dist/generated/gio/tls-database.js

@@ -2,6 +2,17 @@ import { call } from "@gtkx/native";
 import { NativeError, getObject } from "@gtkx/ffi";
 import { TlsCertificate } from "./tls-certificate.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * `GTlsDatabase` is used to look up certificates and other information
+ * from a certificate or key store. It is an abstract base class which
+ * TLS library specific subtypes override.
+ *
+ * A `GTlsDatabase` may be accessed from multiple threads by the TLS backend.
+ * All implementations are required to be fully thread-safe.
+ *
+ * Most common client applications will not directly interact with
+ * `GTlsDatabase`. It is used internally by [class@Gio.TlsConnection].
+ */
 export class TlsDatabase extends GObject.GObject {
     constructor(...args) {
         super(...args);
@@ -17,6 +28,17 @@ export class TlsDatabase extends GObject.GObject {
             { type: { type: "gobject" }, value: null },
         ], { type: "gobject", borrowed: true });
     }
+    /**
+     * Create a handle string for the certificate. The database will only be able
+     * to create a handle for certificates that originate from the database. In
+     * cases where the database cannot create a handle for a certificate, %NULL
+     * will be returned.
+     *
+     * This handle should be stable across various instances of the application,
+     * and between applications. If a certificate is modified in the database,
+     * then it is not guaranteed that this handle will continue to point to it.
+     * @param certificate - certificate for which to create a handle.
+     */
     createCertificateHandle(certificate) {
         return call("libgio-2.0.so.0", "g_tls_database_create_certificate_handle", [
             {
@@ -29,6 +51,24 @@ export class TlsDatabase extends GObject.GObject {
             },
         ], { type: "string" });
     }
+    /**
+     * Look up a certificate by its handle.
+     *
+     * The handle should have been created by calling
+     * g_tls_database_create_certificate_handle() on a #GTlsDatabase object of
+     * the same TLS backend. The handle is designed to remain valid across
+     * instantiations of the database.
+     *
+     * If the handle is no longer valid, or does not point to a certificate in
+     * this database, then %NULL will be returned.
+     *
+     * This function can block, use g_tls_database_lookup_certificate_for_handle_async() to perform
+     * the lookup operation asynchronously.
+     * @param handle - a certificate handle
+     * @param interaction - used to interact with the user if necessary
+     * @param flags - Flags which affect the lookup.
+     * @param cancellable - a #GCancellable, or %NULL
+     */
     lookupCertificateForHandle(handle, flags, interaction, cancellable) {
         const error = { value: null };
         const ptr = call("libgio-2.0.so.0", "g_tls_database_lookup_certificate_for_handle", [
@@ -73,6 +113,16 @@ export class TlsDatabase extends GObject.GObject {
             return null;
         return getObject(ptr, TlsCertificate);
     }
+    /**
+     * Asynchronously look up a certificate by its handle in the database. See
+     * g_tls_database_lookup_certificate_for_handle() for more information.
+     * @param handle - a certificate handle
+     * @param interaction - used to interact with the user if necessary
+     * @param flags - Flags which affect the lookup.
+     * @param cancellable - a #GCancellable, or %NULL
+     * @param callback - callback to call when the operation completes
+     * @param userData - the data to pass to the callback function
+     */
     lookupCertificateForHandleAsync(handle, flags, interaction, cancellable, callback, userData) {
         call("libgio-2.0.so.0", "g_tls_database_lookup_certificate_for_handle_async", [
             {
@@ -109,6 +159,14 @@ export class TlsDatabase extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Finish an asynchronous lookup of a certificate by its handle. See
+     * g_tls_database_lookup_certificate_for_handle() for more information.
+     *
+     * If the handle is no longer valid, or does not point to a certificate in
+     * this database, then %NULL will be returned.
+     * @param result - a #GAsyncResult.
+     */
     lookupCertificateForHandleFinish(result) {
         const error = { value: null };
         const ptr = call("libgio-2.0.so.0", "g_tls_database_lookup_certificate_for_handle_finish", [
@@ -137,6 +195,32 @@ export class TlsDatabase extends GObject.GObject {
         }
         return getObject(ptr, TlsCertificate);
     }
+    /**
+     * Look up the issuer of `certificate` in the database. The
+     * #GTlsCertificate:issuer property of `certificate` is not modified, and
+     * the two certificates are not hooked into a chain.
+     *
+     * This function can block. Use g_tls_database_lookup_certificate_issuer_async()
+     * to perform the lookup operation asynchronously.
+     *
+     * Beware this function cannot be used to build certification paths. The
+     * issuer certificate returned by this function may not be the same as
+     * the certificate that would actually be used to construct a valid
+     * certification path during certificate verification.
+     * [RFC 4158](https://datatracker.ietf.org/doc/html/rfc4158) explains
+     * why an issuer certificate cannot be naively assumed to be part of the
+     * the certification path (though GLib's TLS backends may not follow the
+     * path building strategies outlined in this RFC). Due to the complexity
+     * of certification path building, GLib does not provide any way to know
+     * which certification path will actually be used when verifying a TLS
+     * certificate. Accordingly, this function cannot be used to make
+     * security-related decisions. Only GLib itself should make security
+     * decisions about TLS certificates.
+     * @param certificate - a #GTlsCertificate
+     * @param interaction - used to interact with the user if necessary
+     * @param flags - flags which affect the lookup operation
+     * @param cancellable - a #GCancellable, or %NULL
+     */
     lookupCertificateIssuer(certificate, flags, interaction, cancellable) {
         const error = { value: null };
         const ptr = call("libgio-2.0.so.0", "g_tls_database_lookup_certificate_issuer", [
@@ -179,6 +263,16 @@ export class TlsDatabase extends GObject.GObject {
         }
         return getObject(ptr, TlsCertificate);
     }
+    /**
+     * Asynchronously look up the issuer of `certificate` in the database. See
+     * g_tls_database_lookup_certificate_issuer() for more information.
+     * @param certificate - a #GTlsCertificate
+     * @param interaction - used to interact with the user if necessary
+     * @param flags - flags which affect the lookup operation
+     * @param cancellable - a #GCancellable, or %NULL
+     * @param callback - callback to call when the operation completes
+     * @param userData - the data to pass to the callback function
+     */
     lookupCertificateIssuerAsync(certificate, flags, interaction, cancellable, callback, userData) {
         call("libgio-2.0.so.0", "g_tls_database_lookup_certificate_issuer_async", [
             {
@@ -215,6 +309,11 @@ export class TlsDatabase extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Finish an asynchronous lookup issuer operation. See
+     * g_tls_database_lookup_certificate_issuer() for more information.
+     * @param result - a #GAsyncResult.
+     */
     lookupCertificateIssuerFinish(result) {
         const error = { value: null };
         const ptr = call("libgio-2.0.so.0", "g_tls_database_lookup_certificate_issuer_finish", [
@@ -243,6 +342,16 @@ export class TlsDatabase extends GObject.GObject {
         }
         return getObject(ptr, TlsCertificate);
     }
+    /**
+     * Look up certificates issued by this issuer in the database.
+     *
+     * This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform
+     * the lookup operation asynchronously.
+     * @param issuerRawDn - a #GByteArray which holds the DER encoded issuer DN.
+     * @param interaction - used to interact with the user if necessary
+     * @param flags - Flags which affect the lookup operation.
+     * @param cancellable - a #GCancellable, or %NULL
+     */
     lookupCertificatesIssuedBy(issuerRawDn, flags, interaction, cancellable) {
         const error = { value: null };
         const ptrs = call("libgio-2.0.so.0", "g_tls_database_lookup_certificates_issued_by", [
@@ -295,6 +404,20 @@ export class TlsDatabase extends GObject.GObject {
         }
         return ptrs.map((ptr) => getObject(ptr, TlsCertificate));
     }
+    /**
+     * Asynchronously look up certificates issued by this issuer in the database. See
+     * g_tls_database_lookup_certificates_issued_by() for more information.
+     *
+     * The database may choose to hold a reference to the issuer byte array for the duration
+     * of this asynchronous operation. The byte array should not be modified during
+     * this time.
+     * @param issuerRawDn - a #GByteArray which holds the DER encoded issuer DN.
+     * @param interaction - used to interact with the user if necessary
+     * @param flags - Flags which affect the lookup operation.
+     * @param cancellable - a #GCancellable, or %NULL
+     * @param callback - callback to call when the operation completes
+     * @param userData - the data to pass to the callback function
+     */
     lookupCertificatesIssuedByAsync(issuerRawDn, flags, interaction, cancellable, callback, userData) {
         call("libgio-2.0.so.0", "g_tls_database_lookup_certificates_issued_by_async", [
             {
@@ -336,6 +459,11 @@ export class TlsDatabase extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Finish an asynchronous lookup of certificates. See
+     * g_tls_database_lookup_certificates_issued_by() for more information.
+     * @param result - a #GAsyncResult.
+     */
     lookupCertificatesIssuedByFinish(result) {
         const error = { value: null };
         const ptrs = call("libgio-2.0.so.0", "g_tls_database_lookup_certificates_issued_by_finish", [
@@ -369,6 +497,74 @@ export class TlsDatabase extends GObject.GObject {
         }
         return ptrs.map((ptr) => getObject(ptr, TlsCertificate));
     }
+    /**
+     * Determines the validity of a certificate chain, outside the context
+     * of a TLS session.
+     *
+     * `chain` is a chain of #GTlsCertificate objects each pointing to the next
+     * certificate in the chain by its #GTlsCertificate:issuer property.
+     *
+     * `purpose` describes the purpose (or usage) for which the certificate
+     * is being used. Typically `purpose` will be set to %G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER
+     * which means that the certificate is being used to authenticate a server
+     * (and we are acting as the client).
+     *
+     * The `identity` is used to ensure the server certificate is valid for
+     * the expected peer identity. If the identity does not match the
+     * certificate, %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the
+     * return value. If `identity` is %NULL, that bit will never be set in
+     * the return value. The peer identity may also be used to check for
+     * pinned certificates (trust exceptions) in the database. These may
+     * override the normal verification process on a host-by-host basis.
+     *
+     * Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be
+     * used.
+     *
+     * If `chain` is found to be valid, then the return value will be 0. If
+     * `chain` is found to be invalid, then the return value will indicate at
+     * least one problem found. If the function is unable to determine
+     * whether `chain` is valid (for example, because `cancellable` is
+     * triggered before it completes) then the return value will be
+     * %G_TLS_CERTIFICATE_GENERIC_ERROR and `error` will be set accordingly.
+     * `error` is not set when `chain` is successfully analyzed but found to
+     * be invalid.
+     *
+     * GLib guarantees that if certificate verification fails, at least one
+     * error will be set in the return value, but it does not guarantee
+     * that all possible errors will be set. Accordingly, you may not safely
+     * decide to ignore any particular type of error. For example, it would
+     * be incorrect to mask %G_TLS_CERTIFICATE_EXPIRED if you want to allow
+     * expired certificates, because this could potentially be the only
+     * error flag set even if other problems exist with the certificate.
+     *
+     * Prior to GLib 2.48, GLib's default TLS backend modified `chain` to
+     * represent the certification path built by #GTlsDatabase during
+     * certificate verification by adjusting the #GTlsCertificate:issuer
+     * property of each certificate in @chain. Since GLib 2.48, this no
+     * longer occurs, so you cannot rely on #GTlsCertificate:issuer to
+     * represent the actual certification path used during certificate
+     * verification.
+     *
+     * Because TLS session context is not used, #GTlsDatabase may not
+     * perform as many checks on the certificates as #GTlsConnection would.
+     * For example, certificate constraints may not be honored, and
+     * revocation checks may not be performed. The best way to verify TLS
+     * certificates used by a TLS connection is to let #GTlsConnection
+     * handle the verification.
+     *
+     * The TLS backend may attempt to look up and add missing certificates
+     * to the chain. This may involve HTTP requests to download missing
+     * certificates.
+     *
+     * This function can block. Use g_tls_database_verify_chain_async() to
+     * perform the verification operation asynchronously.
+     * @param chain - a #GTlsCertificate chain
+     * @param purpose - the purpose that this certificate chain will be used for.
+     * @param identity - the expected peer identity
+     * @param interaction - used to interact with the user if necessary
+     * @param flags - additional verify flags
+     * @param cancellable - a #GCancellable, or %NULL
+     */
     verifyChain(chain, purpose, flags, identity, interaction, cancellable) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_tls_database_verify_chain", [
@@ -420,6 +616,19 @@ export class TlsDatabase extends GObject.GObject {
         }
         return result;
     }
+    /**
+     * Asynchronously determines the validity of a certificate chain after
+     * looking up and adding any missing certificates to the chain. See
+     * g_tls_database_verify_chain() for more information.
+     * @param chain - a #GTlsCertificate chain
+     * @param purpose - the purpose that this certificate chain will be used for.
+     * @param identity - the expected peer identity
+     * @param interaction - used to interact with the user if necessary
+     * @param flags - additional verify flags
+     * @param cancellable - a #GCancellable, or %NULL
+     * @param callback - callback to call when the operation completes
+     * @param userData - the data to pass to the callback function
+     */
     verifyChainAsync(chain, purpose, flags, identity, interaction, cancellable, callback, userData) {
         call("libgio-2.0.so.0", "g_tls_database_verify_chain_async", [
             {
@@ -465,6 +674,20 @@ export class TlsDatabase extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Finish an asynchronous verify chain operation. See
+     * g_tls_database_verify_chain() for more information.
+     *
+     * If `chain` is found to be valid, then the return value will be 0. If
+     * `chain` is found to be invalid, then the return value will indicate
+     * the problems found. If the function is unable to determine whether
+     * `chain` is valid or not (eg, because `cancellable` is triggered
+     * before it completes) then the return value will be
+     * %G_TLS_CERTIFICATE_GENERIC_ERROR and `error` will be set
+     * accordingly. `error` is not set when `chain` is successfully analyzed
+     * but found to be invalid.
+     * @param result - a #GAsyncResult.
+     */
     verifyChainFinish(result) {
         const error = { value: null };
         const _result = call("libgio-2.0.so.0", "g_tls_database_verify_chain_finish", [

package/dist/generated/gio/tls-file-database.d.ts

@@ -1,3 +1,8 @@
+/**
+ * `GTlsFileDatabase` is implemented by [class@Gio.TlsDatabase] objects which
+ * load their certificate information from a file. It is an interface which
+ * TLS library specific subtypes implement.
+ */
 export declare class TlsFileDatabase {
     ptr: unknown;
     protected constructor(ptr: unknown);

package/dist/generated/gio/tls-file-database.js

@@ -1,3 +1,8 @@
+/**
+ * `GTlsFileDatabase` is implemented by [class@Gio.TlsDatabase] objects which
+ * load their certificate information from a file. It is an interface which
+ * TLS library specific subtypes implement.
+ */
 export class TlsFileDatabase {
     ptr;
     constructor(ptr) {