--- name: "peks-auth" section: "3" platform: "linux" package: "libnessus-dev" version: "1.0.10-2" release: "Debian 3.0 (Woody)" platforms: ["linux"] url: "https://new.carta.tech/peks-auth" --- # peks-auth(3) public key authentication ## NAME peks\_server\_auth\_pubkey, \ peks\_server\_auth\_accept, peks\_server\_auth\_reject,\ peks\_client\_authenticate - public key authentication ## SYNOPSIS ``` #include char *peks_server_auth_pubkey (int socket, const char *client_host, peks_key *pwd_key, unsigned keylen, unsigned max_fail, const char *key_file); void peks_server_auth_accept (peks_key *pwd_key); void peks_server_auth_reject (peks_key *pwd_key, char *why); int peks_client_authenticate (unsigned digst_meth, int socket, const char *user, peks_key *key, char *(*get_pwd)(int)); extern int peks_recv_passwd_timeout ; extern int peks_recv_timeout; ``` ## DESCRIPTION **Peks\_server\_auth\_pubkey()** lets a user client authenticate on the server by having her signed a challenge. If the user client is unknown, yet she gets a chance sending a password digest. If the password is ok, the passowd line is replaced by the public key sent by the client serving fur further logins. If the client is rejected, she will be informed immediately and the function returnes NULL. Otherwise, the function returns the user name but does not have sent the final acceptance notice to the client, yet. The arguments needed for **peks\_server\_auth\_pubkey()** are: - *Socket* is the socket id to read from, this function uses **io\_send()** and **io\_recv()** rather than **send()** and **recv()**, see [**iostream**(3)](/iostream/3.md). - *Clienthost* is the name of the IP address of the client host, used for key or password lookup, see [**peks-keyfile**(5)](/peks-keyfile/5.md). - *Pwd\_key* is the private key, the password is (assymetrically) encrypted with. The structure is also used to hold the current protocol state. - *Keylen* is the minimal bit length of a user's public key. Keys received with less bits than this length are rejected. - *Max\_fail* is the maximal number of failures using a password when there is no public key, available. If that limit is exeeded, the password line will be deleted automatically from the password data base. - *Key\_file* is the name of the file that coontains the password and user key data base. If the file name begins with a tilde as in "~/\", the tilde is replaced by the actual value of the environment variable **HOME**. The function **peks\_server\_auth\_pubkey()** must always be followed by either **peks\_server\_auth\_accept()**, or **peks\_server\_auth\_reject()** if the return value was non NULL. Otherwise, **peks\_server\_auth\_reject()** has been called already, implicitely but there is no harm to call these functions, anyway. Example: ``` #include "peks.h" if ((user = peks_server_auth_pubkey (socket, /* socket number */ from, /* client host name */ key, /* server prv key */ peks_keylen, /* client min key len */ MAXPWDFAIL, /* max failures allowed */ usrkeys_file)) == 0) /* client key data base */ return 0; /* do some more checks for that user */ ... if (user == 0) { peks_server_auth_reject (key, "user not configured") ; return 0; } peks_server_auth_accept (key) ; return user; ``` **Peks\_server\_auth\_accept()** sends a final acceptance message to the authenticated client after a successful authentication accomplished by **peks\_server\_auth\_pubkey()**. It cleans up the internal state information in the *pwd\_key* argument structure. **Peks\_server\_auth\_reject()** sends a final rejection message to the client and cleans up the state information in the *pwd\_key* argument structure. If the second argument *why* is non-NULL, this string is sent with the rejection notice to the client as an explanation why the server decided to reject the client (currently, this explanation is discarded on the authentication client.) **Peks\_client\_authenticate()** lets a client authenticate on the server by having her signed a challenge granted by the server. The client must choose some authentication method *digst\_meth* (currently 1 or 3.) This decides upon some mathematical method to sign a key, either one is similar to the other (see README.PUB-KEY-ALGO in the source distribution for details.) The other arguments, **Peks\_client\_authenticate()** needs are: - *Socket* is the socket id to read from, this function uses **io\_send()** and **io\_recv()** rather than **send()** and **recv()**, see [**iostream**(3)](/iostream/3.md). - *User* is the name the user who wants to be authenticated. - *Key* is the private key needed in order to sign the server challenge. - *Get\_pwd* is a call back function pointer. If it is non-NULL, the function called with argument 0 as **get\_pwd(0)** is expected to return a password (or NULL when there is none, and (char\*)-1 upon error) used to authenticate the user after the public key method failed. If a password is returned, the password will be cleared to 0 after usage. So the function **get\_pwd()** must never return static memory. By setting the global variable *peks\_recv\_timeout* to some positive value *n*, a timeout is imposed on waiting for an answer while the handshake is active. This is done by temporarily changing the receive timeout value using **io\_recv\_tmo()**, a similar procedure applies to *peks\_recv\_passwd\_timeout*, which is the waiting time when a passwd is asked, for. The default values are 20 seconds for *peks\_recv\_timeout*, and 90 seconds for\ *peks\_recv\_passwd\_timeout*. ## RETURN VALUE **Peks\_server\_auth\_pubkey()** returns the login name of the client user when the authentication was successful, and NULL otherwise. In the latter case you could check the global variable **errno** to get an explanation where the authentication failed, see also [**peks\_strerr**(3)](/peks_strerr/3.md). **Peks\_client\_authenticate** returns 0 if the server has accepted the user, and 1 if the server rejected the user. Upon error, -1 is returned while the variable errno is set, accordingly. In that case you could check the global variable **errno** to get an explanation why the authentication failed, see also [**peks-errnum**(3)](/peks-errnum/3.md). ## CAVEAT Any non-NULL return value will have been allocated using the **XMALLOC()** macro (which is usually a replacement for [**calloc**(3)](/calloc/3.md)) as configured in the **common-stuff.h** header file upon compilation of the package. ## ENVIRONMENT VARIABLES - **HOME** Used for the key file name expansion when there is a leading tilde-slash as in "~/\". ## SEE ALSO **socket**(3), [**calloc**(3)](/calloc/3.md), [**io\_push**(3)](/io_push/3.md), [**iostream**(3)](/iostream/3.md), [**io\_recv\_tmo**(3)](/io_recv_tmo/3.md), [**errno**(3)](/errno/3.md), [**peks-errnum**(3)](/peks-errnum/3.md), [**peks-keyfile**(5)](/peks-keyfile/5.md), ## AUTHOR The **peks** package where these functions belong to was written by Jordan Hrycaj \, originally to support the **nessus** security scanner.