libssh2_userauth_publickey_sk(3)

1libssh2_userauth_publickey_sk(3)    libssh2   libssh2_userauth_publickey_sk(3)
2
3
4

NAME

6       libssh2_userauth_publickey_sk - authenticate a session with a FIDO2 au‐
7       thenticator
8

SYNOPSIS

10       #include <libssh2.h>
11
12       int
13       libssh2_userauth_publickey_sk(LIBSSH2_SESSION *session,
14                                     const char *username,
15                                     size_t username_len,
16                                     const unsigned char *publickeydata,
17                                     size_t publickeydata_len,
18                                     const char *privatekeydata,
19                                     size_t privatekeydata_len,
20                                     const char *passphrase,
21                                     LIBSSH2_USERAUTH_SK_SIGN_FUNC((*sign_callback)),
22                                     void **abstract);
23

CALLBACK

25       #define LIBSSH2_SK_PRESENCE_REQUIRED     0x01
26       #define LIBSSH2_SK_VERIFICATION_REQUIRED 0x04
27
28       typedef struct _LIBSSH2_SK_SIG_INFO {
29           uint8_t flags;
30           uint32_t counter;
31           unsigned char *sig_r;
32           size_t sig_r_len;
33           unsigned char *sig_s;
34           size_t sig_s_len;
35       } LIBSSH2_SK_SIG_INFO;
36
37       int name(LIBSSH2_SESSION *session, LIBSSH2_SK_SIG_INFO *sig_info,
38                const unsigned char *data, size_t data_len, int algorithm,
39                uint8_t flags, const char *application,
40                const unsigned char *key_handle, size_t handle_len,
41                void **abstract);
42

DESCRIPTION

44       session - Session instance as returned by libssh2_session_init_ex(3)
45
46       username - Name of user to attempt authentication for.
47
48       username_len - Length of username parameter.
49
50       publickeydata - Buffer containing the contents of a public key file. If
51       NULL,  the  public  key will be extracted from the privatekeydata. When
52       using certificate authentication, this buffer should contain the public
53       certificate data.
54
55       publickeydata_len - Length of public key data.
56
57       privatekeydata - Buffer containing the contents of a private key file.
58
59       privatekeydata_len - Length of private key data.
60
61       passphrase - Passphrase to use when decoding private key file.
62
63       sign_callback - Callback to communicate with FIDO2 authenticator.
64
65       abstract - User-provided data to pass to callback.
66
67       Attempt    FIDO2    authentication.    using    either    the   sk-ssh-
68       ed25519@openssh.com or sk-ecdsa-sha2-nistp256@openssh.com key  exchange
69       algorithms.
70
71       This function is only supported when libssh2 is backed by OpenSSL.
72
73

CALLBACK DESCRIPTION

75       session - Session instance as returned by libssh2_session_init_ex(3)
76
77       sig_info  - Filled in by the callback with the signature and accompany‐
78       ing information from the authenticator.
79
80       data - The data to sign.
81
82       data_len - The length of the data parameter.
83
84       algorithm - The signing algorithm to  use.  Possible  values  are  LIB‐
85       SSH2_HOSTKEY_TYPE_ED25519 and LIBSSH2_HOSTKEY_TYPE_ECDSA_256.
86
87       flags  -  A bitmask specifying options for the authenticator. When LIB‐
88       SSH2_SK_PRESENCE_REQUIRED is set, the authenticator requires  a  touch.
89       When  LIBSSH2_SK_VERIFICATION_REQUIRED  is  set,  the authenticator re‐
90       quires a PIN.  Many servers and authenticators  do  not  work  properly
91       when LIBSSH2_SK_PRESENCE_REQUIRED is not set.
92
93       application  -  A user-defined string to use as the RP name for the au‐
94       thenticator. Usually "ssh:".
95
96       key_handle - The key handle to use for the authenticator's allow list.
97
98       handle_len - The length of the key_handle parameter.
99
100       abstract - User-defined data. When a PIN is required, use this to  pass
101       in the PIN, or a function pointer to retrieve the PIN.
102
103       The  sign_callback  is  responsible for communicating with the hardware
104       authenticator to generate a signature. On success, the signature infor‐
105       mation must be placed in the `sig_info sig_info parameter and the call‐
106       back must return 0. On failure, it should return a negative number.
107
108       The fields of the LIBSSH2_SK_SIG_INFO are as follows.
109
110       flags - A bitmask specifying options for the authenticator. This should
111       be read from the authenticator and not merely copied from the flags pa‐
112       rameter to the callback.
113
114       counter - A value returned from the authenticator.
115
116       sig_r - For Ed25519 signatures, this contains the entire signature,  as
117       returned  directly  from  the authenticator. For ECDSA signatures, this
118       contains the r component of the signature in a big-endian binary repre‐
119       sentation.  For  both algorithms, use LIBSSH2_ALLOC to allocate memory.
120       It will be freed by the caller.
121
122       sig_r_len - The length of the sig_r parameter.
123
124       sig_s - For ECDSA signatures, this contains the s component of the sig‐
125       nature  in a big-endian binary representation. Use LIBSSH2_ALLOC to al‐
126       locate memory. It will be freed by the caller. For Ed25519  signatures,
127       set this to NULL.
128
129       sig_s_len - The length of the sig_s parameter.
130

RETURN VALUE

132       Return  0  on  success  or  negative on failure. It returns LIBSSH2_ER‐
133       ROR_EAGAIN when it would otherwise block. While LIBSSH2_ERROR_EAGAIN is
134       a negative number, it is not really a failure per se.
135

ERRORS

137       Some of the errors this function may return include:
138
139       LIBSSH2_ERROR_ALLOC - An internal memory allocation call failed.
140
141       LIBSSH2_ERROR_SOCKET_SEND - Unable to send data on socket.
142
143       LIBSSH2_ERROR_AUTHENTICATION_FAILED - failed, invalid username/key.
144

AVAILABILITY

146       Added in libssh2 1.10.0
147