diff options
Diffstat (limited to 'man/rpc_secure.3t')
| -rw-r--r-- | man/rpc_secure.3t | 295 |
1 files changed, 295 insertions, 0 deletions
diff --git a/man/rpc_secure.3t b/man/rpc_secure.3t new file mode 100644 index 0000000..404df0b --- /dev/null +++ b/man/rpc_secure.3t @@ -0,0 +1,295 @@ +.\" @(#)rpc_secure.3n 2.1 88/08/08 4.0 RPCSRC; from 1.19 88/06/24 SMI +.\" $FreeBSD: src/lib/libc/rpc/rpc_secure.3,v 1.14 2002/12/19 09:40:23 ru Exp $ +.\" +.Dd February 16, 1988 +.Dt RPC 3 +.Os +.Sh NAME +.Nm rpc_secure +.Nd library routines for secure remote procedure calls +.Sh SYNOPSIS +.In rpc/rpc.h +.Ft AUTH * +.Fo authdes_create +.Fa "char *name" +.Fa "unsigned window" +.Fa "struct sockaddr *addr" +.Fa "des_block *ckey" +.Fc +.Ft AUTH * +.Fo authdes_pk_create +.Fa "char *name" +.Fa "netobj *publickey" +.Fa "unsigned window" +.Fa "struct sockaddr *addr" +.Fa "des_block *ckey" +.Fc +.Ft int +.Fn authdes_getucred "struct authdes_cred *adc" "uid_t *uid" "gid_t *gid" "int *grouplen" "gid_t *groups" +.Ft int +.Fn getnetname "char *name" +.Ft int +.Fn host2netname "char *name" "const char *host" "const char *domain" +.Ft int +.Fn key_decryptsession "const char *remotename" "des_block *deskey" +.Ft int +.Fn key_encryptsession "const char *remotename" "des_block *deskey" +.Ft int +.Fn key_gendes "des_block *deskey" +.Ft int +.Fn key_setsecret "const char *key" +.Ft int +.Fn netname2host "char *name" "char *host" "int hostlen" +.Ft int +.Fn netname2user "char *name" "uid_t *uidp" "gid_t *gidp" "int *gidlenp" "gid_t *gidlist" +.Ft int +.Fn user2netname "char *name" "const uid_t uid" "const char *domain" +.Sh DESCRIPTION +These routines are part of the +.Tn RPC +library. They implement +.Tn DES +Authentication. See +.Xr rpc 3 +for further details about +.Tn RPC . +.Pp +The +.Fn authdes_create +is the first of two routines which interface to the +.Tn RPC +secure authentication system, known as +.Tn DES +authentication. +The second is +.Fn authdes_getucred , +below. +.Pp +Note: the keyserver daemon +.Xr keyserv 8 +must be running for the +.Tn DES +authentication system to work. +.Pp +The +.Fn authdes_create +function, +used on the client side, returns an authentication handle that +will enable the use of the secure authentication system. +The first argument +.Fa name +is the network name, or +.Fa netname , +of the owner of the server process. +This field usually +represents a +.Fa hostname +derived from the utility routine +.Fn host2netname , +but could also represent a user name using +.Fn user2netname . +The second field is window on the validity of +the client credential, given in seconds. A small +window is more secure than a large one, but choosing +too small of a window will increase the frequency of +resynchronizations because of clock drift. +The third +argument +.Fa addr +is optional. If it is +.Dv NULL , +then the authentication system will assume +that the local clock is always in sync with the server's +clock, and will not attempt resynchronizations. +If an address +is supplied, however, then the system will use the address +for consulting the remote time service whenever +resynchronization +is required. +This argument is usually the +address of the +.Tn RPC +server itself. +The final argument +.Fa ckey +is also optional. If it is +.Dv NULL , +then the authentication system will +generate a random +.Tn DES +key to be used for the encryption of credentials. +If it is supplied, however, then it will be used instead. +.Pp +The +.Fn authdes_pk_create +function is identical to +.Fn authdes_create , +except that the public key needs to be provided at calling time and +will not looked up by this function itself. +.Pp +The +.Fn authdes_getucred +function, +the second of the two +.Tn DES +authentication routines, +is used on the server side for converting a +.Tn DES +credential, which is +operating system independent, into a +.Ux +credential. +This routine differs from utility routine +.Fn netname2user +in that +.Fn authdes_getucred +pulls its information from a cache, and does not have to do a +Yellow Pages lookup every time it is called to get its information. +.Pp +The +.Fn getnetname +function +installs the unique, operating-system independent netname of +the +caller in the fixed-length array +.Fa name . +Returns +.Dv TRUE +if it succeeds and +.Dv FALSE +if it fails. +.Pp +The +.Fn host2netname +function +converts from a domain-specific hostname to an +operating-system independent netname. +Returns +.Dv TRUE +if it succeeds and +.Dv FALSE +if it fails. +Inverse of +.Fn netname2host . +.Pp +The +.Fn key_decryptsession +function +is an interface to the keyserver daemon, which is associated +with +.Tn RPC Ns 's +secure authentication system +.Tn ( DES +authentication). +User programs rarely need to call it, or its associated routines +.Fn key_encryptsession , +.Fn key_gendes +and +.Fn key_setsecret . +System commands such as +.Xr login 1 +and the +.Tn RPC +library are the main clients of these four routines. +.Pp +The +.Fn key_decryptsession +function +takes a server netname and a +.Tn DES +key, and decrypts the key by +using the public key of the server and the secret key +associated with the effective uid of the calling process. It +is the inverse of +.Fn key_encryptsession . +.Pp +The +.Fn key_encryptsession +function +is a keyserver interface routine. +It +takes a server netname and a des key, and encrypts +it using the public key of the server and the secret key +associated with the effective uid of the calling process. It +is the inverse of +.Fn key_decryptsession . +.Pp +The +.Fn key_gendes +function +is a keyserver interface routine. +It +is used to ask the keyserver for a secure conversation key. +Choosing one +.Qq random +is usually not good enough, +because +the common ways of choosing random numbers, such as using the +current time, are very easy to guess. +.Pp +The +.Fn key_setsecret +function +is a keyserver interface routine. +It is used to set the key for +the effective +.Fa uid +of the calling process. +.Pp +The +.Fn netname2host +function +converts from an operating-system independent netname to a +domain-specific hostname. +Returns +.Dv TRUE +if it succeeds and +.Dv FALSE +if it fails. Inverse of +.Fn host2netname . +.Pp +The +.Fn netname2user +function +converts from an operating-system independent netname to a +domain-specific user ID. +Returns +.Dv TRUE +if it succeeds and +.Dv FALSE +if it fails. +Inverse of +.Fn user2netname . +.Pp +The +.Fn user2netname +function +converts from a domain-specific username to an operating-system +independent netname. +Returns +.Dv TRUE +if it succeeds and +.Dv FALSE +if it fails. +Inverse of +.Fn netname2user . +.Sh AVAILABILITY +These functions are part of libtirpc. +.Sh SEE ALSO +.Xr rpc 3 , +.Xr xdr 3 +.Pp +The following manuals: +.Rs +.%B Remote Procedure Calls: Protocol Specification +.Re +.Rs +.%B Remote Procedure Call Programming Guide +.Re +.Rs +.%B Rpcgen Programming Guide +.Re +.Rs +.%B RPC: Remote Procedure Call Protocol Specification +.%O RFC1050, Sun Microsystems Inc., USC-ISI +.Re |