feat(pki): implement PKI context API

A new generic struct is introduced which contains the various configuration options that can be used by pki operations.
API functions have been provided to configure all the options.

Signed-off-by: Praneeth Sarode <praneethsarode@gmail.com>
Reviewed-by: Jakub Jelen <jjelen@redhat.com>
Reviewed-by: Eshan Kelkar <eshankelkar@galorithm.com>

include/libssh/libssh.h

@@ -107,6 +107,7 @@ typedef struct ssh_session_struct* ssh_session;
 typedef struct ssh_string_struct* ssh_string;
 typedef struct ssh_event_struct* ssh_event;
 typedef struct ssh_connector_struct * ssh_connector;
+typedef struct ssh_pki_ctx_struct *ssh_pki_ctx;
 typedef void* ssh_gssapi_creds;
 
 /* Socket type */
@@ -911,6 +912,53 @@ LIBSSH_API int sshsig_verify(const void *data,
                              const char *sig_namespace,
                              ssh_key *sign_key);
 
+/* PKI context API */
+
+enum ssh_pki_options_e {
+    SSH_PKI_OPTION_RSA_KEY_SIZE,
+
+    /* Security Key options */
+    SSH_PKI_OPTION_SK_APPLICATION,
+    SSH_PKI_OPTION_SK_FLAGS,
+    SSH_PKI_OPTION_SK_USER_ID,
+    SSH_PKI_OPTION_SK_CHALLENGE,
+    SSH_PKI_OPTION_SK_CALLBACKS,
+};
+
+LIBSSH_API ssh_pki_ctx ssh_pki_ctx_new(void);
+
+LIBSSH_API int ssh_pki_ctx_options_set(ssh_pki_ctx context,
+                                       enum ssh_pki_options_e option,
+                                       const void *value);
+
+LIBSSH_API int ssh_pki_ctx_set_sk_pin_callback(ssh_pki_ctx context,
+                                               ssh_auth_callback pin_callback,
+                                               void *userdata);
+
+#define SSH_SK_OPTION_NAME_DEVICE_PATH "device"
+#define SSH_SK_OPTION_NAME_USER_ID     "user"
+
+LIBSSH_API int ssh_pki_ctx_sk_callbacks_option_set(ssh_pki_ctx context,
+                                                   const char *name,
+                                                   const char *value,
+                                                   bool required);
+
+LIBSSH_API int ssh_pki_ctx_sk_callbacks_options_clear(ssh_pki_ctx context);
+
+LIBSSH_API int
+ssh_pki_ctx_get_sk_attestation_buffer(const struct ssh_pki_ctx_struct *context,
+                                      ssh_buffer *attestation_buffer);
+
+LIBSSH_API void ssh_pki_ctx_free(ssh_pki_ctx context);
+
+#define SSH_PKI_CTX_FREE(x)      \
+    do {                         \
+        if ((x) != NULL) {       \
+            ssh_pki_ctx_free(x); \
+            x = NULL;            \
+        }                        \
+    } while (0)
+
 #ifndef LIBSSH_LEGACY_0_4
 #include "libssh/legacy.h"
 #endif

include/libssh/pki_context.h

@@ -0,0 +1,103 @@
+/*
+ * This file is part of the SSH Library
+ *
+ * Copyright (c) 2025 Praneeth Sarode <praneethsarode@gmail.com>
+ *
+ * The SSH Library is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, version 2.1 of the License.
+ *
+ * The SSH Library is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
+ * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
+ * License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with the SSH Library; see the file COPYING.  If not, write to
+ * the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
+ * MA 02111-1307, USA.
+ */
+
+#ifndef PKI_CONTEXT_H
+#define PKI_CONTEXT_H
+
+#include "libssh/callbacks.h"
+#include "libssh/libssh.h"
+
+/**
+ * @brief Security key context structure
+ *
+ * Context structure containing all parameters and callbacks
+ * needed for FIDO2/U2F security key operations.
+ */
+struct ssh_pki_ctx_struct {
+    /** @brief Desired RSA modulus size in bits
+     *
+     * Specified size of RSA keys to generate. If set to 0, defaults to 3072
+     * bits. Must be greater than or equal to 1024, as anything below is
+     * considered insecure.
+     */
+    int rsa_key_size;
+
+    /** @brief Security key callbacks
+     *
+     * Provides enroll/sign/load_resident_keys operations.
+     */
+    const struct ssh_sk_callbacks_struct *sk_callbacks;
+
+    /** @brief Application identifier string for the security key credential
+     *
+     * FIDO2 relying party identifier, typically "ssh:user@hostname" format.
+     * This is required for all security key operations.
+     */
+    char *sk_application;
+
+    /** @brief FIDO2 operation flags
+     *
+     * Bitfield controlling authenticator behavior. Combine with bitwise OR:
+     * - SSH_SK_USER_PRESENCE_REQD (0x01): Require user touch
+     * - SSH_SK_USER_VERIFICATION_REQD (0x04): Require PIN/biometric
+     * - SSH_SK_FORCE_OPERATION (0x10): Override duplicate detection
+     * - SSH_SK_RESIDENT_KEY (0x20): Create discoverable credential
+     */
+    uint8_t sk_flags;
+
+    /** @brief PIN callback for authenticator user verification (optional)
+     *
+     * Callback invoked to obtain a PIN or perform user verification when
+     * SSH_SK_USER_VERIFICATION_REQD is set or the authenticator requires it.
+     * If NULL, no interactive PIN retrieval is performed.
+     */
+    ssh_auth_callback sk_pin_callback;
+
+    /** @brief User supplied pointer passed to callbacks (optional)
+     *
+     * Generic pointer set by the application and forwarded to
+     * interactive callbacks (e.g. PIN callback) to allow applications to
+     * carry state context.
+     */
+    void *sk_userdata;
+
+    /** @brief Custom challenge data for enrollment (optional)
+     *
+     * Buffer containing challenge data signed by the authenticator.
+     * If NULL, a random 32-byte challenge is automatically generated.
+     */
+    ssh_buffer sk_challenge_buffer;
+
+    /** @brief Options to be passed to the sk_callbacks (optional)
+     *
+     * NULL-terminated array of sk_option pointers owned by this context.
+     */
+    struct sk_option **sk_callbacks_options;
+
+    /** @brief The buffer used to store attestation information returned in a
+     * key enrollment operation
+     */
+    ssh_buffer sk_attestation_buffer;
+};
+
+/* Internal PKI context functions */
+ssh_pki_ctx ssh_pki_ctx_dup(const ssh_pki_ctx context);
+
+#endif /* PKI_CONTEXT_H */