NAME
peks_list_keyfile, peks_private_key, new_peks_key,
peks_save_private_key, peks_private_access,
peks_delete_userkey - key and file manipulation functions
SYNOPSIS
#include <peks.h>
peks_key *new_peks_key (unsigned size);
unsigned peks_keylen (const peks_key *key);
int peks_list_keyfile
(void (*print) (const char*), const char *key_file);
peks_key *peks_private_key
(const char *usr_at_host,
const char *key_file, char *(*get_pwd)(int),
unsigned keylen);
int peks_save_private_key
(const char *usr_at_host, peks_key *key,
const char *key_file, char *(*get_pwd)(int));
int peks_save_public_key
(const char *usr_at_host, peks_key *key,
const char *key_file);
int peks_delete_userkey
(const char *usr_at_host, const char *key_file,
char *(*get_pwd)(int);
int peks_delete_hostkey
(const char *hostname, const char *key_file,
char *(*get_pwd)(int);
int peks_private_access
(const char *filename, int strictly);
unsigned long peks_admin_equiv
(unsigneduid, unsignedgid);
void peks_set_keep_alive_notice
(void (*print_string)(const char*));
DESCRIPTION
New_peks_key() creates a new private key of at least size bits.
peks_keylen() returnes the bit length of the peks key given as argument.
Peks_list_keyfile() reads the file key_file given as argument and prints all the key tags from that file. Each tag is printad on a separate line followed by some comment.
If the first function argument print is NULL, the data are printed to the stdout, otherwise the argument function print is called once for each line to be printed.
peks_private_key() reads a user key from the file given as argument and returns a pointer to it as the function return value. Assuming the argument usr_at_host is given as "usr@host" or "usr", the function looks for a key tagged "usr@host:" first (in case of "usr@host",) and if that failes for a key tagged "usr@", next.
If there was a key found, the function checks whether that key has at least keylen (given as last argument) bits. If it has less bits, an error is returned.
If the key needs a pass phrase, the function given as argument get_pwd is consulted and the return value is evaluated (see the paragraph PASS PHRASE, below.)
Otherwise the key is activted and returned.
If there was no key and/or no file, a new private key of at least keylen bits will be generated and stored in the file key_file given as second argument. A pointer to that key is returned as function value.
The tag for the key just created is the string usr_at_host.
Notice:
In the key data base, there is no other way to distinguish a private key from a public key else but by the tag. Be aware that this tag may habe been edited. By convention, a user key (the tag contains the letter '@') is private and a host key is public.
peks_save_private_key() saves the private key given as second argument key tagged according to the first argument usr_at_fost in the file key_file. If a key instance for the tag applied is found, already this key will be replaced in the key_file.
If the argument get_pwd is non NULL, the function given as argument get_pwd is consulted and the return value is evaluated (see the paragraph PASS PHRASE, below.)
peks_save_public_key() saves the public key derived from the second argument key onto the key file key_file given as last argument. The first argument usr_at_fost corresponds to a key tag used for key lookup. If a public key with a corresponding tag is not found, the public key with the tag is added to the file. Otherwise, if the key tags match but the public keys differ, an error is detected.
peks_delete_userkey() selects a key from the file given as argument the same way as described for peks_private_key (), above. Once a key tag matches, the whole key is deleted from the file.
peks_delete_hostkey() works similar as the function peks_delete_userkey() but for host keys.
If the key needs a pass phrase, the function given as argument get_pwd is consulted and the return value is evaluated (see the paragraph PASS PHRASE, below.)
The function peks_private_access() is a cute little function that checks the access rights of the file filename as used for private data such as keys and the like. With the second parameter strictly, the function is informed about the level of privacy.
The file filename must be a proper file and cannot be a symlink and cannot have extra hardlinks. If the second argument strictly is zero, the file filename may be group and world readable but not writable. If strictly is non-zero but smaller than 2, the file must not even be world- but may be group readable. If strictly is 2 or greater, no world or group read or write permission is allowed.
The function peks_admin_equiv() installs the maximal user and group id for any admin account to check, for. When checking files with peks_private_access(), all path segments with a user and group id smaller or equal than these values are considerd secure and tamperproof.
Passing the second argument gid as -1, the path check is disabled when the first argument uid is non-zero. In this case only file checking applies without owner check (!). Otherwise, when the second argument gid is -1 and the first argument uid is 0 and patch checking is turned on, again.
RETURN VALUE
New_peks_key() returns a pointer to a new key, and NULL upon error while the global variable errno will be set to indicate some explanation. peks_keylen() returns number of bits used for that key, and 0 if the argument was the NULL pointer.
Peks_list_keyfile() and peks_delete_userkey() return 0, on success and -1, otherwise. In the latter case while the global variable errno will be set to indicate some error explanation (see peks-errnum(3) and errno(3) for details).
peks_private_key() returns a pointer to a key structure of type peks_key on success, an NULL otherwise while the global variable errno will be set.
peks_save_public_key() returns 0, if there was no key in the data base and a new key had been added. If the key existed, already in the data base and was the same as the one to be added, 0 is returned otherwise if tags match but not the keys -1 is returned.
Peks_private_access() returns 0 on success. In this case the file exists and meets the privacy settings as specified. Otherwise -1 is returned. In that case the global variable errno will be set to indicate some error explanation (see peks-errnum(3) and errno(3) for details).
If the second argument gid of peks_admin_equiv_uid is not -1, it returns the values that were previously effective. The values are retured as a pair of 16 bit values as in (uid<<16)|(gid&0xffff).
If the second argument gid of peks_admin_equiv_uid is -1, the previous state of the patc ckeck mode is returned: 0 if path check were enabled, and -1, otherwise.
peks_set_keep_alive_notice lets you define a call back function print_string printing some dots while a key is generated. By default, this funtion looks similar to puts function printing to the stdout (see puts(3) for details.) Passing a NULL argument to print_string resets to the default.
PASS PHRASE
The pass phrase for a private key is always read by some call back function. In this documentation, the function argument pointer get_pwd refers to a pass phrase returning function.
The pass phrase function will be called as get_pwd(0) if the private key is to be activated, only and as get_pwd(1) if the key is to be ireencoded with a new pass phrase. If the function is called from peks_private_key() after a newly generated key, it is called as get_pwd(2).
This function get_pwd() returns a character string which comprises the pass phrase. The value NULL or the empty string "" is returned if there is no such pass phrase which has the same effect as if the argument get_pwd were passed as NULL pointer from the beginning.
If a password is returned, the password will be cleared to 0 after usage. So the function get_pwd() must never return constant, or read-only memory.
An error condition can be returned as (char*)-1 which will be handled, accordingly. Such a pass phrase function could look like
#include <pwd.h>
#include <string.h>
const char*
get_pwd
(int mode)
{
char *s, *t ;
if (mode == 0) /* read private key */
return getpass ("Pass phrase: ");
/* change pass phrase for the private key */
if ((s = getpass ("New pass phrase: ")) == 0)
return (char*)-1;
s = strdup (s);
if ((t = getpass ("Repeat : ")) == 0) {
free (s);
return (char*)-1;
}
if (strcmp (s, t) != 0)
t = 0 ;
free (s);
if (t == 0)
return (char*)-1;
return t ;
}
ENVIRONMENT VARIABLES
- HOME
-
Used for the key file name expansion when there is a leading tilde-slash as in "~/<key_file>".
SEE ALSO
gethostbyname(3), peks-keyfile(5), tagsresolve(3), errno(3), peks-errnum(3),
AUTHOR
The peks package where these functions belong to was written by Jordan Hrycaj <[email protected]>, originally to support the nessus security scanner.