'\" te .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved .\" Copyright 1989 AT&T .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] .TH SECURE_RPC 3NSL "April 9, 2016" .SH NAME secure_rpc, authdes_getucred, authdes_seccreate, getnetname, host2netname, key_decryptsession, key_encryptsession, key_gendes, key_setsecret, key_secretkey_is_set, netname2host, netname2user, user2netname \- library routines for secure remote procedure calls .SH SYNOPSIS .LP .nf \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lnsl\fR [ \fIlibrary\fR...] #include #include \fBint\fR \fBauthdes_getucred\fR(\fBconst struct authdes_cred *\fR\fIadc\fR, \fBuid_t *\fR\fIuidp\fR, \fBgid_t *\fR\fIgidp\fR, \fBshort *\fR\fIgidlenp\fR, \fBgid_t *\fR\fIgidlist\fR); .fi .LP .nf \fBAUTH *\fR\fBauthdes_seccreate\fR(\fBconst char *\fR\fIname\fR, \fBconst uint_t\fR \fIwindow\fR, \fBconst char *\fR\fItimehost\fR, \fIckey\fR); .fi .LP .nf \fBint\fR \fBgetnetname\fR(\fBchar\fR \fIname\fR \fB[MAXNETNAMELEN+1]\fR); .fi .LP .nf \fBint\fR \fBhost2netname\fR(\fBchar\fR \fIname\fR \fB[MAXNETNAMELEN+1]\fR, \fBconst char *\fR\fIhost\fR, \fBconst char *\fR\fIdomain\fR); .fi .LP .nf \fBint\fR \fBkey_decryptsession\fR(\fBconst char *\fR\fIremotename\fR, \fBdes_block *\fR\fIdeskey\fR); .fi .LP .nf \fBint\fR \fBkey_encryptsession\fR(\fBconst char *\fR\fIremotename\fR, \fBdes_block *\fR\fIdeskey\fR); .fi .LP .nf \fBint\fR \fBkey_gendes\fR(\fBdes_block *\fR\fIdeskey\fR); .fi .LP .nf \fBint\fR \fBkey_setsecret\fR(\fBconst char *\fR\fIkey\fR); .fi .LP .nf \fBint\fR \fBkey_secretkey_is_set\fR(void) .fi .LP .nf \fBint\fR \fBnetname2host\fR(\fBconst char *\fR\fIname\fR, \fBchar *\fR\fIhost\fR, \fBconst int\fR \fIhostlen\fR); .fi .LP .nf \fBint\fR \fBnetname2user\fR(\fBconst char *\fR\fIname\fR, \fBuid_t *\fR\fIuidp\fR, \fBgid_t *\fR\fIgidp\fR, \fBint *\fR\fIgidlenp\fR, \fBgid_t *\fR\fIgidlist\fR \fB[NGRPS]\fR); .fi .LP .nf \fBint\fR \fBuser2netname\fR(\fBchar\fR \fIname\fR \fB[MAXNETNAMELEN+1]\fR, \fBconst uid_t\fR \fIuid\fR, \fBconst char *\fR\fIdomain\fR); .fi .SH DESCRIPTION .LP The \fBRPC\fR library functions allow C programs to make procedure calls on other machines across the network. .sp .LP \fBRPC\fR supports various authentication flavors. Among them are: .sp .ne 2 .na \fB\fBAUTH_NONE\fR\fR .ad .RS 13n No authentication (none). .RE .sp .ne 2 .na \fB\fBAUTH_SYS\fR\fR .ad .RS 13n Traditional \fBUNIX-style\fR authentication. .RE .sp .ne 2 .na \fB\fBAUTH_DES\fR\fR .ad .RS 13n \fBDES\fR encryption-based authentication. .RE .sp .LP The \fBauthdes_getucred()\fR and \fBauthdes_seccreate()\fR functions implement the \fBAUTH_DES\fR authentication style. The keyserver daemon \fBkeyserv\fR(1M) must be running for the \fBAUTH_DES\fR authentication system to work and \fBkeylogin\fR(1) must have been run. The \fBAUTH_DES\fR style of authentication is discussed here. For information about the \fBAUTH_NONE\fR and \fBAUTH_SYS\fR flavors of authentication, refer to \fBrpc_clnt_auth\fR(3NSL). See \fBrpc\fR(3NSL) for the definition of the \fBAUTH\fR data structure. .sp .LP The following functions documented on this page are MT-Safe. For the MT-levels of other authentication styles, see relevant man pages. .sp .ne 2 .na \fB\fBauthdes_getucred()\fR\fR .ad .RS 26n This is the first of two functions that interface to the \fBRPC\fR secure authentication system \fBAUTH_DES\fR. The second is the \fBauthdes_seccreate()\fR function. The \fBauthdes_getucred()\fR function is used on the server side to convert an \fBAUTH_DES\fR credential, which is operating system independent, to an \fBAUTH_SYS\fR credential. The \fBauthdes_getucred()\fR function returns \fB1\fR if it succeeds, \fB0\fR if it fails. .sp The \fB*\fR\fIuidp\fR parameter is set to the user's numerical \fBID\fR associated with \fIadc\fR. The \fB*\fR\fIgidp\fR parameter is set to the numerical \fBID\fR of the user's group. The \fB*\fR\fIgidlist\fR parameter contains the numerical \fBIDs\fR of the other groups to which the user belongs. The \fB*\fR\fIgidlenp\fR parameter is set to the number of valid group ID entries specified by the \fB*\fR\fIgidlist\fR parameter. .sp The \fBauthdes_getucred()\fR function fails if the \fBauthdes_cred\fR structure was created with the netname of a host. In such a case, \fBnetname2host()\fR should be used to get the host name from the host netname in the \fBauthdes_cred\fR structure. .RE .sp .ne 2 .na \fB\fBauthdes_seccreate()\fR\fR .ad .RS 26n The second of two \fBAUTH_DES\fR authentication functions, the \fBauthdes_seccreate()\fR function is used on the client side to return an authentication handle that enables the use of the secure authentication system. The first field, \fIname\fR, specifies the network name \fInetname\fR of the owner of the server process. The field usually represents a hostname derived from the \fBhost2netname()\fR utility, but the field might also represent a user name converted with the \fBuser2netname()\fR utility. .sp The second field, \fIwindow\fR, specifies the validity of the client credential in seconds. If the difference in time between the client's clock and the server's clock exceeds \fIwindow\fR, the server rejects the client's credentials and the clock will have to be resynchronized. A small window is more secure than a large one, but choosing too small a window increases the frequency of resynchronization due to clock drift. .sp The third parameter, \fItimehost\fR, is the host's name and is optional. If \fItimehost\fR is \fINULL\fR, the authentication system assumes that the local clock is always in sync with the \fItimehost\fR clock and does not attempt resynchronization. If a timehost is supplied, the system consults the remote time service whenever resynchronization is required. The \fItimehost\fR parameter is usually the name of the host on which the server is running. .sp The final parameter, \fIckey\fR, is also optional. If \fIckey\fR is \fINULL,\fR the authentication system generates a random \fBDES\fR key to be used for the encryption of credentials. If \fIckey\fR is supplied, it is used for encryption. .sp If \fBauthdes_seccreate()\fR fails, it returns \fINULL.\fR .RE .sp .ne 2 .na \fB\fBgetnetname()\fR\fR .ad .RS 26n This function returns the unique, operating system independent netname of the caller in the fixed-length array \fIname\fR. The function returns \fB1\fR if it succeeds and \fB0\fR if it fails. .RE .sp .ne 2 .na \fB\fBhost2netname()\fR\fR .ad .RS 26n This function converts a domain-specific hostname \fIhost\fR to an operating system independent netname. The function returns \fB1\fR if it succeeds and \fB0\fR if it fails. The \fBhost2netname()\fR function is the inverse of the \fBnetname2host()\fR function. If the \fIdomain\fR is \fINULL\fR, \fBhost2netname()\fR uses the default domain name of the machine. If \fIhost\fR is \fINULL\fR, it defaults to that machine itself. If \fIdomain\fR is \fINULL\fR and \fIhost\fR is an NIS name such as \fBmyhost.sun.example.com\fR, the \fBhost2netname()\fR function uses the domain \fBsun.example.com\fR rather than the default domain name of the machine. .RE .sp .ne 2 .na \fB\fBkey_decryptsession()\fR\fR .ad .RS 26n This function is an interface to the keyserver daemon, which is associated with \fBRPC's\fR secure authentication system (\fBAUTH_DES\fR authentication). User programs rarely need to call \fBkey_decryptsession()\fR or the associated functions \fBkey_encryptsession()\fR, \fBkey_gendes()\fR, and \fBkey_setsecret()\fR. .sp The \fBkey_decryptsession()\fR function takes a server netname \fIremotename\fR and a \fBDES\fR key \fIdeskey\fR, and decrypts the key by using the public key of the server and the secret key associated with the effective \fBUID\fR of the calling process. The \fBkey_decryptsession()\fR function is the inverse of \fBkey_encryptsession()\fR function. .RE .sp .ne 2 .na \fB\fBkey_encryptsession()\fR\fR .ad .RS 26n This function is a keyserver interface that takes a server netname \fIremotename\fR and a \fBDES\fR key \fIdeskey\fR, and encrypts the key using the public key of the server and the secret key associated with the effective \fBUID\fR of the calling process. If the keyserver does not have a key registered for the UID, it falls back to using the secret key for the netname \fBnobody\fR unless this feature has been disabled. See \fBkeyserv\fR(1M). The \fBkey_encryptsession()\fR function is the inverse of \fBkey_decryptsession()\fR function. The \fBkey_encryptsession()\fR function returns \fB0\fR if it succeeds, \fB\(mi1\fR if it fails. .RE .sp .ne 2 .na \fB\fBkey_gendes()\fR\fR .ad .RS 26n This is a keyserver interface function used to ask the keyserver for a secure conversation key. Selecting a conversion key at random is generally not secure because the common ways of choosing random numbers are too easy to guess. The \fBkey_gendes()\fR function returns \fB0\fR if it succeeds, \fB\(mi1\fR if it fails. .RE .sp .ne 2 .na \fB\fBkey_setsecret()\fR\fR .ad .RS 26n This is a keyserver interface function used to set the key for the effective \fBUID\fR of the calling process. This function returns \fB0\fR if it succeeds, \fB\(mi1\fR if it fails. .RE .sp .ne 2 .na \fB\fBkey_secretkey_is_set()\fR\fR .ad .RS 26n This is a keyserver interface function used to determine if a key has been set for the effective \fBUID\fR of the calling process. If the keyserver has a key stored for the effective \fBUID\fR of the calling process, the \fBkey_secretkey_is_set()\fR function returns \fB1\fR. Otherwise it returns \fB0\fR. .RE .sp .ne 2 .na \fB\fBnetname2host()\fR\fR .ad .RS 26n This function converts an operating system independent netname \fIname\fR to a domain-specific hostname \fIhost\fR. The \fIhostlen\fR parameter is the maximum size of \fIhost\fR. The \fBnetname2host()\fR function returns \fB1\fR if it succeeds and \fB0\fR if it fails. The function is the inverse of the \fBhost2netname()\fR function. .RE .sp .ne 2 .na \fB\fBnetname2user()\fR\fR .ad .RS 26n This function converts an operating system independent netname to a domain-specific user \fBID\fR. The \fBnetname2user()\fR function returns \fB1\fR if it succeeds and \fB0\fR if it fails.The function is the inverse of the \fBuser2netname()\fR function. .sp The \fB*\fR\fIuidp\fR parameter is set to the user's numerical \fBID\fR associated with \fIname\fR. The \fB*\fR\fIgidp\fR parameter is set to the numerical \fBID\fR of the user's group. The \fIgidlist\fR parameter contains the numerical \fBIDs\fR of the other groups to which the user belongs. The \fB*\fR\fIgidlenp\fR parameter is set to the number of valid group \fBID\fR entries specified by the \fIgidlist\fR parameter. .RE .sp .ne 2 .na \fB\fBuser2netname()\fR\fR .ad .RS 26n This function converts a domain-specific username to an operating system independent netname. The \fBuser2netname()\fR function returns \fB1\fR if it succeeds and \fB0\fR if it fails. The function is the inverse of \fBnetname2user()\fR function. .RE .SH ATTRIBUTES .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS box; c | c l | l . ATTRIBUTE TYPE ATTRIBUTE VALUE _ MT-Level MT-Safe .TE .SH SEE ALSO .LP \fBchkey\fR(1), \fBkeylogin\fR(1), \fBkeyserv\fR(1M), \fBnewkey\fR(1M), \fBrpc\fR(3NSL), \fBrpc_clnt_auth\fR(3NSL), \fBattributes\fR(5)