peks-auth(3) · carta

NAME

peks_server_auth_pubkey,
peks_server_auth_accept, peks_server_auth_reject,
peks_client_authenticate - public key authentication

SYNOPSIS

#include <peks.h>

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).

Clienthost: is the name of the IP address of the client host, used for key or password lookup, see peks-keyfile(5).

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 "~/<filename>", 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).

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_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).

CAVEAT

Any non-NULL return value will have been allocated using the XMALLOC() macro (which is usually a replacement for calloc(3)) 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 "~/<filename>".

AUTHOR

The peks package where these functions belong to was written by Jordan Hrycaj <[email protected]>, originally to support the nessus security scanner.