---
name: "peks-keys"
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-keys"
---

# peks-keys(3)

key and file manipulation functions

## 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)](/gethostbyname/3.md), [**peks-keyfile**(5)](/peks-keyfile/5.md), **tagsresolve**(3),  [**errno**(3)](/errno/3.md), [**peks-errnum**(3)](/peks-errnum/3.md),

## AUTHOR

*The* **peks** *package where these* *functions belong to was written by Jordan* *Hrycaj \<jordan@teddy-net.com\>, originally* *to support the* **nessus** *security scanner.*