@gtkx/ffi 0.1.45 → 0.1.46

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

@@ -2,10 +2,29 @@ import { call } from "@gtkx/native";
 import { NativeError, getObject } from "@gtkx/ffi";
 import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * A certificate used for TLS authentication and encryption.
+ * This can represent either a certificate only (eg, the certificate
+ * received by a client from a server), or the combination of
+ * a certificate and a private key (which is needed when acting as a
+ * [iface@Gio.TlsServerConnection]).
+ */
 export class TlsCertificate extends GObject.GObject {
     constructor(...args) {
         super(...args);
     }
+    /**
+     * Creates a #GTlsCertificate from the data in @file.
+     *
+     * If `file` cannot be read or parsed, the function will return %NULL and
+     * set @error.
+     *
+     * Any unknown file types will error with %G_IO_ERROR_NOT_SUPPORTED.
+     * Currently only `.p12` and `.pfx` files are supported.
+     * See g_tls_certificate_new_from_pkcs12() for more details.
+     * @param file - file containing a certificate to import
+     * @param password - password for PKCS #12 files
+     */
     static certificateNewFromFileWithPassword(file, password) {
         const ptr = call("libgio-2.0.so.0", "g_tls_certificate_new_from_file_with_password", [
             {
@@ -19,6 +38,23 @@ export class TlsCertificate extends GObject.GObject {
         ], { type: "gobject", borrowed: false });
         return getObject(ptr, TlsCertificate);
     }
+    /**
+     * Creates a #GTlsCertificate from the PEM-encoded data in `cert_file` and @key_file. The returned certificate will be the first certificate
+     * found in @cert_file. As of GLib 2.44, if `cert_file` contains more
+     * certificates it will try to load a certificate chain. All
+     * certificates will be verified in the order found (top-level
+     * certificate should be the last one in the file) and the
+     * #GTlsCertificate:issuer property of each certificate will be set
+     * accordingly if the verification succeeds. If any certificate in the
+     * chain cannot be verified, the first certificate in the file will
+     * still be returned.
+     *
+     * If either file cannot be read or parsed, the function will return
+     * %NULL and set @error. Otherwise, this behaves like
+     * g_tls_certificate_new_from_pem().
+     * @param certFile - file containing one or more PEM-encoded
+     * @param keyFile - file containing a PEM-encoded private key
+     */
     static certificateNewFromFiles(certFile, keyFile) {
         const ptr = call("libgio-2.0.so.0", "g_tls_certificate_new_from_files", [
             {
@@ -32,6 +68,24 @@ export class TlsCertificate extends GObject.GObject {
         ], { type: "gobject", borrowed: false });
         return getObject(ptr, TlsCertificate);
     }
+    /**
+     * Creates a #GTlsCertificate from the PEM-encoded data in @data. If
+     * `data` includes both a certificate and a private key, then the
+     * returned certificate will include the private key data as well. (See
+     * the #GTlsCertificate:private-key-pem property for information about
+     * supported formats.)
+     *
+     * The returned certificate will be the first certificate found in
+     * @data. As of GLib 2.44, if `data` contains more certificates it will
+     * try to load a certificate chain. All certificates will be verified in
+     * the order found (top-level certificate should be the last one in the
+     * file) and the #GTlsCertificate:issuer property of each certificate
+     * will be set accordingly if the verification succeeds. If any
+     * certificate in the chain cannot be verified, the first certificate in
+     * the file will still be returned.
+     * @param data - PEM-encoded certificate data
+     * @param length - the length of @data, or -1 if it's 0-terminated.
+     */
     static certificateNewFromPem(data, length) {
         const ptr = call("libgio-2.0.so.0", "g_tls_certificate_new_from_pem", [
             {
@@ -45,6 +99,34 @@ export class TlsCertificate extends GObject.GObject {
         ], { type: "gobject", borrowed: false });
         return getObject(ptr, TlsCertificate);
     }
+    /**
+     * Creates a #GTlsCertificate from a
+     * PKCS \#11 URI.
+     *
+     * An example `pkcs11_uri` would be `pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01`
+     *
+     * Where the token’s layout is:
+     *
+     * |[
+     * Object 0:
+     * URL: pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01;object=private%20key;type=private
+     * Type: Private key (RSA-2048)
+     * ID: 01
+     *
+     * Object 1:
+     * URL: pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01;object=Certificate%20for%20Authentication;type=cert
+     * Type: X.509 Certificate (RSA-2048)
+     * ID: 01
+     * ]|
+     *
+     * In this case the certificate and private key would both be detected and used as expected.
+     * `pkcs_uri` may also just reference an X.509 certificate object and then optionally
+     * `private_key_pkcs11_uri` allows using a private key exposed under a different URI.
+     *
+     * Note that the private key is not accessed until usage and may fail or require a PIN later.
+     * @param pkcs11Uri - A PKCS \#11 URI
+     * @param privateKeyPkcs11Uri - A PKCS \#11 URI
+     */
     static certificateNewFromPkcs11Uris(pkcs11Uri, privateKeyPkcs11Uri) {
         const ptr = call("libgio-2.0.so.0", "g_tls_certificate_new_from_pkcs11_uris", [
             {
@@ -59,6 +141,28 @@ export class TlsCertificate extends GObject.GObject {
         ], { type: "gobject", borrowed: false });
         return getObject(ptr, TlsCertificate);
     }
+    /**
+     * Creates a #GTlsCertificate from the data in @data. It must contain
+     * a certificate and matching private key.
+     *
+     * If extra certificates are included they will be verified as a chain
+     * and the #GTlsCertificate:issuer property will be set.
+     * All other data will be ignored.
+     *
+     * You can pass as single password for all of the data which will be
+     * used both for the PKCS #12 container as well as encrypted
+     * private keys. If decryption fails it will error with
+     * %G_TLS_ERROR_BAD_CERTIFICATE_PASSWORD.
+     *
+     * This constructor requires support in the current #GTlsBackend.
+     * If support is missing it will error with
+     * %G_IO_ERROR_NOT_SUPPORTED.
+     *
+     * Other parsing failures will error with %G_TLS_ERROR_BAD_CERTIFICATE.
+     * @param data - DER-encoded PKCS #12 format certificate data
+     * @param length - the length of @data
+     * @param password - optional password for encrypted certificate data
+     */
     static certificateNewFromPkcs12(data, length, password) {
         const ptr = call("libgio-2.0.so.0", "g_tls_certificate_new_from_pkcs12", [
             {
@@ -89,6 +193,14 @@ export class TlsCertificate extends GObject.GObject {
             },
         ], { type: "gobject", borrowed: false });
     }
+    /**
+     * Creates one or more #GTlsCertificates from the PEM-encoded
+     * data in @file. If `file` cannot be read or parsed, the function will
+     * return %NULL and set @error. If `file` does not contain any
+     * PEM-encoded certificates, this will return an empty list and not
+     * set @error.
+     * @param file - file containing PEM-encoded certificates to import
+     */
     static listNewFromFile(file) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_tls_certificate_list_new_from_file", [
@@ -118,6 +230,9 @@ export class TlsCertificate extends GObject.GObject {
         }
         return result;
     }
+    /**
+     * Gets the value of #GTlsCertificate:dns-names.
+     */
     getDnsNames() {
         const ptr = call("libgio-2.0.so.0", "g_tls_certificate_get_dns_names", [
             {
@@ -134,6 +249,9 @@ export class TlsCertificate extends GObject.GObject {
             return null;
         return getObject(ptr, GLib.PtrArray);
     }
+    /**
+     * Gets the value of #GTlsCertificate:ip-addresses.
+     */
     getIpAddresses() {
         const ptr = call("libgio-2.0.so.0", "g_tls_certificate_get_ip_addresses", [
             {
@@ -150,6 +268,9 @@ export class TlsCertificate extends GObject.GObject {
             return null;
         return getObject(ptr, GLib.PtrArray);
     }
+    /**
+     * Gets the #GTlsCertificate representing @cert's issuer, if known
+     */
     getIssuer() {
         const ptr = call("libgio-2.0.so.0", "g_tls_certificate_get_issuer", [
             {
@@ -161,6 +282,9 @@ export class TlsCertificate extends GObject.GObject {
             return null;
         return getObject(ptr, TlsCertificate);
     }
+    /**
+     * Returns the issuer name from the certificate.
+     */
     getIssuerName() {
         return call("libgio-2.0.so.0", "g_tls_certificate_get_issuer_name", [
             {
@@ -169,6 +293,9 @@ export class TlsCertificate extends GObject.GObject {
             },
         ], { type: "string" });
     }
+    /**
+     * Returns the time at which the certificate became or will become invalid.
+     */
     getNotValidAfter() {
         const ptr = call("libgio-2.0.so.0", "g_tls_certificate_get_not_valid_after", [
             {
@@ -185,6 +312,9 @@ export class TlsCertificate extends GObject.GObject {
             return null;
         return getObject(ptr, GLib.DateTime);
     }
+    /**
+     * Returns the time at which the certificate became or will become valid.
+     */
     getNotValidBefore() {
         const ptr = call("libgio-2.0.so.0", "g_tls_certificate_get_not_valid_before", [
             {
@@ -201,6 +331,9 @@ export class TlsCertificate extends GObject.GObject {
             return null;
         return getObject(ptr, GLib.DateTime);
     }
+    /**
+     * Returns the subject name from the certificate.
+     */
     getSubjectName() {
         return call("libgio-2.0.so.0", "g_tls_certificate_get_subject_name", [
             {
@@ -209,6 +342,14 @@ export class TlsCertificate extends GObject.GObject {
             },
         ], { type: "string" });
     }
+    /**
+     * Check if two #GTlsCertificate objects represent the same certificate.
+     * The raw DER byte data of the two certificates are checked for equality.
+     * This has the effect that two certificates may compare equal even if
+     * their #GTlsCertificate:issuer, #GTlsCertificate:private-key, or
+     * #GTlsCertificate:private-key-pem properties differ.
+     * @param certTwo - second certificate to compare
+     */
     isSame(certTwo) {
         return call("libgio-2.0.so.0", "g_tls_certificate_is_same", [
             {
@@ -221,6 +362,43 @@ export class TlsCertificate extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * This verifies `cert` and returns a set of #GTlsCertificateFlags
+     * indicating any problems found with it. This can be used to verify a
+     * certificate outside the context of making a connection, or to
+     * check a certificate against a CA that is not part of the system
+     * CA database.
+     *
+     * If `cert` is valid, %G_TLS_CERTIFICATE_NO_FLAGS is returned.
+     *
+     * If `identity` is not %NULL, @cert's name(s) will be compared against
+     * it, and %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the return
+     * value if it does not match. If `identity` is %NULL, that bit will
+     * never be set in the return value.
+     *
+     * If `trusted_ca` is not %NULL, then `cert` (or one of the certificates
+     * in its chain) must be signed by it, or else
+     * %G_TLS_CERTIFICATE_UNKNOWN_CA will be set in the return value. If
+     * `trusted_ca` is %NULL, that bit will never be set in the return
+     * value.
+     *
+     * 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.
+     *
+     * Because TLS session context is not used, #GTlsCertificate 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.
+     * @param identity - the expected peer identity
+     * @param trustedCa - the certificate of a trusted authority
+     */
     verify(identity, trustedCa) {
         return call("libgio-2.0.so.0", "g_tls_certificate_verify", [
             {

package/dist/generated/gio/tls-client-connection.d.ts

@@ -1,16 +1,104 @@
 import { TlsCertificateFlags } from "./enums.js";
 import { SocketConnectable } from "./socket-connectable.js";
 import * as GLib from "../glib/index.js";
+/**
+ * `GTlsClientConnection` is the client-side subclass of
+ * [class@Gio.TlsConnection], representing a client-side TLS connection.
+ */
 export declare class TlsClientConnection {
     ptr: unknown;
     protected constructor(ptr: unknown);
     static fromPtr(ptr: unknown): TlsClientConnection;
+    /**
+     * Possibly copies session state from one connection to another, for use
+     * in TLS session resumption. This is not normally needed, but may be
+     * used when the same session needs to be used between different
+     * endpoints, as is required by some protocols, such as FTP over TLS.
+     * `source` should have already completed a handshake and, since TLS 1.3,
+     * it should have been used to read data at least once. `conn` should not
+     * have completed a handshake.
+     *
+     * It is not possible to know whether a call to this function will
+     * actually do anything. Because session resumption is normally used
+     * only for performance benefit, the TLS backend might not implement
+     * this function. Even if implemented, it may not actually succeed in
+     * allowing `conn` to resume @source's TLS session, because the server
+     * may not have sent a session resumption token to @source, or it may
+     * refuse to accept the token from @conn. There is no way to know
+     * whether a call to this function is actually successful.
+     *
+     * Using this function is not required to benefit from session
+     * resumption. If the TLS backend supports session resumption, the
+     * session will be resumed automatically if it is possible to do so
+     * without weakening the privacy guarantees normally provided by TLS,
+     * without need to call this function. For example, with TLS 1.3,
+     * a session ticket will be automatically copied from any
+     * #GTlsClientConnection that has previously received session tickets
+     * from the server, provided a ticket is available that has not
+     * previously been used for session resumption, since session ticket
+     * reuse would be a privacy weakness. Using this function causes the
+     * ticket to be copied without regard for privacy considerations.
+     * @param source - a #GTlsClientConnection
+     */
     copySessionState(source: TlsClientConnection): void;
+    /**
+     * Gets the list of distinguished names of the Certificate Authorities
+     * that the server will accept certificates from. This will be set
+     * during the TLS handshake if the server requests a certificate.
+     * Otherwise, it will be %NULL.
+     *
+     * Each item in the list is a #GByteArray which contains the complete
+     * subject DN of the certificate authority.
+     */
     getAcceptedCas(): GLib.ByteArray[];
+    /**
+     * Gets @conn's expected server identity
+     */
     getServerIdentity(): SocketConnectable | null;
+    /**
+     * SSL 3.0 is no longer supported. See
+     * g_tls_client_connection_set_use_ssl3() for details.
+     */
     getUseSsl3(): boolean;
+    /**
+     * Gets @conn's validation flags
+     *
+     * This function does not work as originally designed and is impossible
+     * to use correctly. See #GTlsClientConnection:validation-flags for more
+     * information.
+     */
     getValidationFlags(): TlsCertificateFlags;
+    /**
+     * Sets @conn's expected server identity, which is used both to tell
+     * servers on virtual hosts which certificate to present, and also
+     * to let `conn` know what name to look for in the certificate when
+     * performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled.
+     * @param identity - a #GSocketConnectable describing the expected server identity
+     */
     setServerIdentity(identity: SocketConnectable): void;
+    /**
+     * Since GLib 2.42.1, SSL 3.0 is no longer supported.
+     *
+     * From GLib 2.42.1 through GLib 2.62, this function could be used to
+     * force use of TLS 1.0, the lowest-supported TLS protocol version at
+     * the time. In the past, this was needed to connect to broken TLS
+     * servers that exhibited protocol version intolerance. Such servers
+     * are no longer common, and using TLS 1.0 is no longer considered
+     * acceptable.
+     *
+     * Since GLib 2.64, this function does nothing.
+     * @param useSsl3 - a #gboolean, ignored
+     */
     setUseSsl3(useSsl3: boolean): void;
+    /**
+     * Sets @conn's validation flags, to override the default set of
+     * checks performed when validating a server certificate. By default,
+     * %G_TLS_CERTIFICATE_VALIDATE_ALL is used.
+     *
+     * This function does not work as originally designed and is impossible
+     * to use correctly. See #GTlsClientConnection:validation-flags for more
+     * information.
+     * @param flags - the #GTlsCertificateFlags to use
+     */
     setValidationFlags(flags: TlsCertificateFlags): void;
 }

package/dist/generated/gio/tls-client-connection.js

@@ -1,6 +1,10 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { SocketConnectable } from "./socket-connectable.js";
+/**
+ * `GTlsClientConnection` is the client-side subclass of
+ * [class@Gio.TlsConnection], representing a client-side TLS connection.
+ */
 export class TlsClientConnection {
     ptr;
     constructor(ptr) {
@@ -9,6 +13,37 @@ export class TlsClientConnection {
     static fromPtr(ptr) {
         return new TlsClientConnection(ptr);
     }
+    /**
+     * Possibly copies session state from one connection to another, for use
+     * in TLS session resumption. This is not normally needed, but may be
+     * used when the same session needs to be used between different
+     * endpoints, as is required by some protocols, such as FTP over TLS.
+     * `source` should have already completed a handshake and, since TLS 1.3,
+     * it should have been used to read data at least once. `conn` should not
+     * have completed a handshake.
+     *
+     * It is not possible to know whether a call to this function will
+     * actually do anything. Because session resumption is normally used
+     * only for performance benefit, the TLS backend might not implement
+     * this function. Even if implemented, it may not actually succeed in
+     * allowing `conn` to resume @source's TLS session, because the server
+     * may not have sent a session resumption token to @source, or it may
+     * refuse to accept the token from @conn. There is no way to know
+     * whether a call to this function is actually successful.
+     *
+     * Using this function is not required to benefit from session
+     * resumption. If the TLS backend supports session resumption, the
+     * session will be resumed automatically if it is possible to do so
+     * without weakening the privacy guarantees normally provided by TLS,
+     * without need to call this function. For example, with TLS 1.3,
+     * a session ticket will be automatically copied from any
+     * #GTlsClientConnection that has previously received session tickets
+     * from the server, provided a ticket is available that has not
+     * previously been used for session resumption, since session ticket
+     * reuse would be a privacy weakness. Using this function causes the
+     * ticket to be copied without regard for privacy considerations.
+     * @param source - a #GTlsClientConnection
+     */
     copySessionState(source) {
         call("libgio-2.0.so.0", "g_tls_client_connection_copy_session_state", [
             {
@@ -21,6 +56,15 @@ export class TlsClientConnection {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Gets the list of distinguished names of the Certificate Authorities
+     * that the server will accept certificates from. This will be set
+     * during the TLS handshake if the server requests a certificate.
+     * Otherwise, it will be %NULL.
+     *
+     * Each item in the list is a #GByteArray which contains the complete
+     * subject DN of the certificate authority.
+     */
     getAcceptedCas() {
         return call("libgio-2.0.so.0", "g_tls_client_connection_get_accepted_cas", [
             {
@@ -38,6 +82,9 @@ export class TlsClientConnection {
             borrowed: true,
         });
     }
+    /**
+     * Gets @conn's expected server identity
+     */
     getServerIdentity() {
         const ptr = call("libgio-2.0.so.0", "g_tls_client_connection_get_server_identity", [
             {
@@ -49,6 +96,10 @@ export class TlsClientConnection {
             return null;
         return getObject(ptr, SocketConnectable);
     }
+    /**
+     * SSL 3.0 is no longer supported. See
+     * g_tls_client_connection_set_use_ssl3() for details.
+     */
     getUseSsl3() {
         return call("libgio-2.0.so.0", "g_tls_client_connection_get_use_ssl3", [
             {
@@ -57,6 +108,13 @@ export class TlsClientConnection {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Gets @conn's validation flags
+     *
+     * This function does not work as originally designed and is impossible
+     * to use correctly. See #GTlsClientConnection:validation-flags for more
+     * information.
+     */
     getValidationFlags() {
         return call("libgio-2.0.so.0", "g_tls_client_connection_get_validation_flags", [
             {
@@ -65,6 +123,13 @@ export class TlsClientConnection {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Sets @conn's expected server identity, which is used both to tell
+     * servers on virtual hosts which certificate to present, and also
+     * to let `conn` know what name to look for in the certificate when
+     * performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled.
+     * @param identity - a #GSocketConnectable describing the expected server identity
+     */
     setServerIdentity(identity) {
         call("libgio-2.0.so.0", "g_tls_client_connection_set_server_identity", [
             {
@@ -77,6 +142,19 @@ export class TlsClientConnection {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Since GLib 2.42.1, SSL 3.0 is no longer supported.
+     *
+     * From GLib 2.42.1 through GLib 2.62, this function could be used to
+     * force use of TLS 1.0, the lowest-supported TLS protocol version at
+     * the time. In the past, this was needed to connect to broken TLS
+     * servers that exhibited protocol version intolerance. Such servers
+     * are no longer common, and using TLS 1.0 is no longer considered
+     * acceptable.
+     *
+     * Since GLib 2.64, this function does nothing.
+     * @param useSsl3 - a #gboolean, ignored
+     */
     setUseSsl3(useSsl3) {
         call("libgio-2.0.so.0", "g_tls_client_connection_set_use_ssl3", [
             {
@@ -89,6 +167,16 @@ export class TlsClientConnection {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Sets @conn's validation flags, to override the default set of
+     * checks performed when validating a server certificate. By default,
+     * %G_TLS_CERTIFICATE_VALIDATE_ALL is used.
+     *
+     * This function does not work as originally designed and is impossible
+     * to use correctly. See #GTlsClientConnection:validation-flags for more
+     * information.
+     * @param flags - the #GTlsCertificateFlags to use
+     */
     setValidationFlags(flags) {
         call("libgio-2.0.so.0", "g_tls_client_connection_set_validation_flags", [
             {