getkey(3N)

getkey -- retrieve an authentication key

Synopsis

cc [options] file -lnsl

#include <cr1.h>

int getkey(char *scheme, char *local_principal, char *remote_principal);

Description

getkey is a library function that retrieves authentication keys from a key management daemon. The parameters are:

scheme: points to the name of the authentication scheme for which the keys should be obtained (such as cr1)
local_principal: points to the name of the local entity for which the corresponding authentication key should be obtained
remote_principal: points to the name of the remote entity for which the corresponding authentication key should be obtained

A principal name can have either of the following forms:

name@system
system!name

where name is the logname of the principal for which the key should be obtained, and system is the name of the system on which the logname resides.

Users may use getkey to obtain their own keys for use in authentication. In addition, a privileged user may obtain keys for any user. A privileged user is the owner of the keys file.

If local_principal is a NULL pointer, the principal name corresponding to the effective UID of the application is used. The ``@system'' or ``system!'' portion of the principal name is optional for local_principal, and the ``name@'' or ``!name'' portion is optional for remote_principal.

Also, the name for local_principal is equivalent to ``name@'' and ``name@local_system''. The system for remote_principal is equivalent to the remote privileged user indicated by ``@system'', but not to ``root@system''.

Files

/etc/iaf/cr1/keys: cr1 key database

Return values

getkey returns NULL if the daemon cannot be contacted or if the daemon rejects the request; otherwise, it returns a pointer to the key. The pointer references static storage, which is overwritten on subsequent calls. For multi-threaded applications, information is maintained on a per thread basis.

References

cr1(1Mbnu), cryptkey(1bnu), keymaster(1Mbnu)