Support for sk-ecdsa-sha2-nistp256 and sk-ssh-ed25519 keys, FIDO (lib…

…ssh2#698)

Notes:
Add support for [email protected] and [email protected] key exchange for FIDO auth using the OpenSSL backend. Stub API for other backends.

Credit:
Michael Buckley

docs/libssh2_sign_sk.3

@@ -0,0 +1,85 @@
+.TH libssh2_sign_sk 3 "1 Jun 2022" "libssh2 1.10.0" "libssh2 manual"
+.SH NAME
+libssh2_sign_sk - Create a signature from a FIDO2 authenticator.
+.SH SYNOPSIS
+#include <libssh2.h>
+.nf
+int libssh2_sign_sk(LIBSSH2_SESSION *session,
+                    unsigned char **sig,
+                    size_t *sig_len,
+                    const unsigned char *data,
+                    size_t data_len,
+                    void **abstract);
+
+typedef struct _LIBSSH2_PRIVKEY_SK {
+    int algorithm;
+    uint8_t flags;
+    const char *application;
+    const unsigned char *key_handle;
+    size_t handle_len;
+    LIBSSH2_USERAUTH_SK_SIGN_FUNC((*sign_callback));
+    void **orig_abstract;
+} LIBSSH2_PRIVKEY_SK;
+
+.SH DESCRIPTION
+\fIsession\fP - Session instance as returned by 
+.BR libssh2_session_init_ex(3)
+
+\fIsig\fP - A pointer to a buffer in which to place the signature. The caller 
+is responsible for freeing the signature with LIBSSH2_FREE.
+
+\fIsig_len\fP - A pointer to the length of the sig parameter.
+
+\fIdata\fP - The data to sign.
+
+\fIdata_len\fP - The length of the data parameter.
+
+\fIabstract\fP - A pointer to a pointer to a LIBSSH2_PRIVKEY_SK. See 
+description below.
+
+Create a signature from a FIDO2 authenticator, using either the 
+[email protected] or [email protected] key 
+exchange algorithms.
+
+The abstract parameter is a pointer to a pointer due to the internal workings 
+of libssh2. The LIBSSH2_PRIVKEY_SK must be completely filled out, and the 
+caller is responsible for all memory management of its fields.
+
+\fIalgorithm\fP - The signing algorithm to use. Possible values are 
+LIBSSH2_HOSTKEY_TYPE_ED25519 and LIBSSH2_HOSTKEY_TYPE_ECDSA_256.
+
+\fIflags\fP - A bitmask specifying options for the authenticator. When 
+LIBSSH2_SK_PRESENCE_REQUIRED is set, the authenticator requires a touch. When
+LIBSSH2_SK_VERIFICATION_REQUIRED is set, the authenticator requires a PIN. 
+Many servers and authenticators do not work properly when 
+LIBSSH2_SK_PRESENCE_REQUIRED is not set.
+
+\fIapplication\fP - A user-defined string to use as the RP name for the 
+authenticator. Usually "ssh:".
+
+\fIkey_handle\fP - The key handle to use for the authenticator's allow list.
+
+\fIhandle_len\fP - The length of the key_handle parameter.
+
+\fIabstract\fP - User-defined data. When a PIN is required, use this to pass in 
+the PIN, or a function pointer to retrieve the PIN.
+
+\fIkey_handle\fP The decoded key handle from the private key file.
+
+\fIhandle_len\fP The length of the key_handle parameter.
+
+\fIsign_callback\fP - Responsible for communicating with the hardware 
+authenticator to generate a signature. On success, the signature information
+must be placed in the `\fIsig_info\fP sig_info parameter and the callback must 
+return 0. On failure, it should return a negative number. See
+.BR libssh2_userauth_publickey_sk(3)
+ for more information.
+
+\fIorig_abstract\fP - User-defined data. When a PIN is required, use this to 
+pass in the PIN, or a function pointer to retrieve the PIN.
+
+.SH RETURN VALUE
+Return 0 on success or negative on failure.
+
+.SH SEE ALSO
+.BR libssh2_userauth_publickey_sk(3)

docs/libssh2_userauth_publickey_sk.3

@@ -0,0 +1,133 @@
+.TH libssh2_userauth_publickey_sk 3 "1 Jun 2022" "libssh2 1.10.0" "libssh2 manual"
+.SH NAME
+libssh2_userauth_publickey_sk - authenticate a session with a FIDO2 authenticator
+.SH SYNOPSIS
+#include <libssh2.h>
+.nf
+int libssh2_userauth_publickey_sk(LIBSSH2_SESSION *session,
+                                  const char *username,
+                                  size_t username_len,
+                                  const char *privatekeydata,
+                                  size_t privatekeydata_len,
+                                  const char *passphrase,
+                                  LIBSSH2_USERAUTH_SK_SIGN_FUNC
+                                  ((*sign_callback)),
+                                  void **abstract);
+
+.SH CALLBACK
+.nf
+#define LIBSSH2_SK_PRESENCE_REQUIRED     0x01
+#define LIBSSH2_SK_VERIFICATION_REQUIRED 0x04
+
+typedef struct _LIBSSH2_SK_SIG_INFO {
+    uint8_t flags;
+    uint32_t counter;
+    unsigned char *sig_r;
+    size_t sig_r_len;
+    unsigned char *sig_s;
+    size_t sig_s_len;
+} LIBSSH2_SK_SIG_INFO;
+
+int name(LIBSSH2_SESSION *session, LIBSSH2_SK_SIG_INFO *sig_info, 
+         const unsigned char *data, size_t data_len, int algorithm,
+         uint8_t flags, const char *application,
+         const unsigned char *key_handle, size_t handle_len, 
+         void **abstract);
+.fi
+
+.SH DESCRIPTION
+\fIsession\fP - Session instance as returned by 
+.BR libssh2_session_init_ex(3)
+
+\fIusername\fP - Name of user to attempt authentication for.
+
+\fIusername_len\fP - Length of username parameter.
+
+\fIprivatekeydata\fP - Buffer containing the contents of a private key file.
+
+\fIprivatekeydata_len\fP - Length of private key data.
+
+\fIpassphrase\fP - Passphrase to use when decoding private key file.
+
+\fIsign_callback\fP - Callback to communicate with FIDO2 authenticator.
+
+\fIabstract\fP - User-provided data to pass to callback.
+
+Attempt FIDO2 authentication. using either the [email protected] or 
+[email protected] key exchange algorithms.
+
+This function is only supported when libssh2 is backed by OpenSSL.
+
+.SH CALLBACK DESCRIPTION
+\fIsession\fP - Session instance as returned by 
+.BR libssh2_session_init_ex(3)
+
+\fIsig_info\fP - Filled in by the callback with the signature and accompanying 
+information from the authenticator.
+
+\fIdata\fP - The data to sign.
+
+\fIdata_len\fP - The length of the data parameter.
+
+\fIalgorithm\fP - The signing algorithm to use. Possible values are 
+LIBSSH2_HOSTKEY_TYPE_ED25519 and LIBSSH2_HOSTKEY_TYPE_ECDSA_256.
+
+\fIflags\fP - A bitmask specifying options for the authenticator. When 
+LIBSSH2_SK_PRESENCE_REQUIRED is set, the authenticator requires a touch. When
+LIBSSH2_SK_VERIFICATION_REQUIRED is set, the authenticator requires a PIN. 
+Many servers and authenticators do not work properly when 
+LIBSSH2_SK_PRESENCE_REQUIRED is not set.
+
+\fIapplication\fP - A user-defined string to use as the RP name for the 
+authenticator. Usually "ssh:".
+
+\fIkey_handle\fP - The key handle to use for the authenticator's allow list.
+
+\fIhandle_len\fP - The length of the key_handle parameter.
+
+\fIabstract\fP - User-defined data. When a PIN is required, use this to pass in 
+the PIN, or a function pointer to retrieve the PIN.
+
+The \fIsign_callback\fP is responsible for communicating with the hardware 
+authenticator to generate a signature. On success, the signature information
+must be placed in the `\fIsig_info\fP sig_info parameter and the callback must 
+return 0. On failure, it should return a negative number.
+
+The fields of the LIBSSH2_SK_SIG_INFO are as follows.
+
+\fIflags\fP - A bitmask specifying options for the authenticator. This should 
+be read from the authenticator and not merely copied from the flags parameter
+to the callback.
+
+\fIcounter\fP - A value returned from the authenticator.
+
+\fIsig_r\fP - For Ed25519 signatures, this contains the entire signature, as
+returned directly from the authenticator. For ECDSA signatures, this contains
+the r component of the signature in a big-endian binary representation. For 
+both algorithms, use LIBSSH2_ALLOC to allocate memory. It will be freed by the
+caller.
+
+\fIsig_r_len\fP - The length of the sig_r parameter.
+
+\fIsig_s\fP - For ECDSA signatures, this contains the s component of the 
+signature in a big-endian binary representation. Use LIBSSH2_ALLOC to allocate 
+memory. It will be freed by the caller. For Ed25519 signatures, set this to 
+NULL.
+
+\fIsig_s_len\fP - The length of the sig_s parameter.
+
+.SH RETURN VALUE
+Return 0 on success or negative on failure. It returns
+LIBSSH2_ERROR_EAGAIN when it would otherwise block. While
+LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se.
+
+.SH ERRORS
+Some of the errors this function may return include:
+
+\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed.
+
+\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket.
+
+\fILIBSSH2_ERROR_AUTHENTICATION_FAILED\fP - failed, invalid username/key.
+.SH SEE ALSO
+.BR libssh2_session_init_ex(3)

include/libssh2.h

@@ -283,6 +283,15 @@ typedef struct _LIBSSH2_USERAUTH_KBDINT_RESPONSE
     unsigned int length;
 } LIBSSH2_USERAUTH_KBDINT_RESPONSE;
 
+typedef struct _LIBSSH2_SK_SIG_INFO {
+    uint8_t flags;
+    uint32_t counter;
+    unsigned char *sig_r;
+    size_t sig_r_len;
+    unsigned char *sig_s;
+    size_t sig_s_len;
+} LIBSSH2_SK_SIG_INFO;
+
 /* 'publickey' authentication callback */
 #define LIBSSH2_USERAUTH_PUBLICKEY_SIGN_FUNC(name) \
   int name(LIBSSH2_SESSION *session, unsigned char **sig, size_t *sig_len, \
@@ -295,6 +304,17 @@ typedef struct _LIBSSH2_USERAUTH_KBDINT_RESPONSE
             const LIBSSH2_USERAUTH_KBDINT_PROMPT *prompts,              \
             LIBSSH2_USERAUTH_KBDINT_RESPONSE *responses, void **abstract)
 
+/* SK authentication callback */
+#define LIBSSH2_USERAUTH_SK_SIGN_FUNC(name) \
+int name(LIBSSH2_SESSION *session, LIBSSH2_SK_SIG_INFO *sig_info, \
+const unsigned char *data, size_t data_len, int algorithm, uint8_t flags, \
+const char *application, const unsigned char *key_handle, size_t handle_len, \
+void **abstract)
+
+/* Flags for SK authentication */
+#define LIBSSH2_SK_PRESENCE_REQUIRED     0x01
+#define LIBSSH2_SK_VERIFICATION_REQUIRED 0x04
+
 /* Callbacks for special SSH packets */
 #define LIBSSH2_IGNORE_FUNC(name) \
  void name(LIBSSH2_SESSION *session, const char *message, int message_len, \
@@ -368,6 +388,25 @@ typedef struct _LIBSSH2_LISTENER                    LIBSSH2_LISTENER;
 typedef struct _LIBSSH2_KNOWNHOSTS                  LIBSSH2_KNOWNHOSTS;
 typedef struct _LIBSSH2_AGENT                       LIBSSH2_AGENT;
 
+/* SK signature callback */
+typedef struct _LIBSSH2_PRIVKEY_SK {
+    int algorithm;
+    uint8_t flags;
+    const char *application;
+    const unsigned char *key_handle;
+    size_t handle_len;
+    LIBSSH2_USERAUTH_SK_SIGN_FUNC((*sign_callback));
+    void **orig_abstract;
+} LIBSSH2_PRIVKEY_SK;
+
+int
+libssh2_sign_sk(LIBSSH2_SESSION *session,
+                unsigned char **sig,
+                size_t *sig_len,
+                const unsigned char *data,
+                size_t data_len,
+                void **abstract);
+
 typedef struct _LIBSSH2_POLLFD {
     unsigned char type; /* LIBSSH2_POLLFD_* below */
 
@@ -711,6 +750,17 @@ libssh2_userauth_keyboard_interactive_ex(LIBSSH2_SESSION* session,
                                              (unsigned int)strlen(username), \
                                              (response_callback))
 
+LIBSSH2_API int
+libssh2_userauth_publickey_sk(LIBSSH2_SESSION *session,
+                              const char *username,
+                              size_t username_len,
+                              const char *privatekeydata,
+                              size_t privatekeydata_len,
+                              const char *passphrase,
+                              LIBSSH2_USERAUTH_SK_SIGN_FUNC
+                              ((*sign_callback)),
+                              void **abstract);
+
 LIBSSH2_API int libssh2_poll(LIBSSH2_POLLFD *fds, unsigned int nfds,
                              long timeout);
 

src/crypto.h

@@ -147,12 +147,23 @@ _libssh2_ecdsa_curve_name_with_octal_new(libssh2_ecdsa_ctx ** ecdsactx,
                                          const unsigned char *k,
                                          size_t k_len,
                                          libssh2_curve_type type);
+
 int
 _libssh2_ecdsa_new_private(libssh2_ecdsa_ctx ** ec_ctx,
                            LIBSSH2_SESSION * session,
                            const char *filename,
                            unsigned const char *passphrase);
 
+int
+_libssh2_ecdsa_new_private_sk(libssh2_ecdsa_ctx ** ec_ctx,
+                              unsigned char *flags,
+                              const char **application,
+                              const unsigned char **key_handle,
+                              size_t *handle_len,
+                              LIBSSH2_SESSION * session,
+                              const char *filename,
+                              unsigned const char *passphrase);
+
 int
 _libssh2_ecdsa_verify(libssh2_ecdsa_ctx * ctx,
                       const unsigned char *r, size_t r_len,
@@ -182,6 +193,16 @@ int _libssh2_ecdsa_new_private_frommemory(libssh2_ecdsa_ctx ** ec_ctx,
                                           size_t filedata_len,
                                           unsigned const char *passphrase);
 
+int _libssh2_ecdsa_new_private_frommemory_sk(libssh2_ecdsa_ctx ** ec_ctx,
+                                             unsigned char *flags,
+                                             const char **application,
+                                             const unsigned char **key_handle,
+                                             size_t *handle_len,
+                                             LIBSSH2_SESSION * session,
+                                             const char *filedata,
+                                             size_t filedata_len,
+                                             unsigned const char *passphrase);
+
 libssh2_curve_type
 _libssh2_ecdsa_get_curve_type(libssh2_ecdsa_ctx *ec_ctx);
 
@@ -211,6 +232,16 @@ _libssh2_ed25519_new_private(libssh2_ed25519_ctx **ed_ctx,
                             LIBSSH2_SESSION *session,
                             const char *filename, const uint8_t *passphrase);
 
+int
+_libssh2_ed25519_new_private_sk(libssh2_ed25519_ctx **ed_ctx,
+                                unsigned char *flags,
+                                const char **application,
+                                const unsigned char **key_handle,
+                                size_t *handle_len,
+                                LIBSSH2_SESSION *session,
+                                const char *filename,
+                                const uint8_t *passphrase);
+
 int
 _libssh2_ed25519_new_public(libssh2_ed25519_ctx **ed_ctx,
                             LIBSSH2_SESSION *session,
@@ -229,6 +260,17 @@ _libssh2_ed25519_new_private_frommemory(libssh2_ed25519_ctx **ed_ctx,
                                         size_t filedata_len,
                                         unsigned const char *passphrase);
 
+int
+_libssh2_ed25519_new_private_frommemory_sk(libssh2_ed25519_ctx **ed_ctx,
+                                           unsigned char *flags,
+                                           const char **application,
+                                           const unsigned char **key_handle,
+                                           size_t *handle_len,
+                                           LIBSSH2_SESSION *session,
+                                           const char *filedata,
+                                           size_t filedata_len,
+                                           unsigned const char *passphrase);
+
 #endif /* LIBSSH2_ED25519 */
 
 
@@ -259,6 +301,20 @@ int _libssh2_pub_priv_keyfilememory(LIBSSH2_SESSION *session,
                                     const char *passphrase);
 
 
+int _libssh2_sk_pub_keyfilememory(LIBSSH2_SESSION *session,
+                                  unsigned char **method,
+                                  size_t *method_len,
+                                  unsigned char **pubkeydata,
+                                  size_t *pubkeydata_len,
+                                  int *algorithm,
+                                  unsigned char *flags,
+                                  const char **application,
+                                  const unsigned char **key_handle,
+                                  size_t *handle_len,
+                                  const char *privatekeydata,
+                                  size_t privatekeydata_len,
+                                  const char *passphrase);
+
 /**
  * @function _libssh2_supported_key_sign_algorithms
  * @abstract Returns supported algorithms used for upgrading public