Add utility rpc_gss_*() APIs

These are utility functions used by both client and server consumers
of RPCSEC GSS. The man pages, written by Doug Rabson, come from
FreeBSD, with some adjustments by me. The following functions are
added:

rpc_gss_get_error(3t), rpc_gss_get_mechanisms(3t),
rpc_gss_get_mech_info(3t), rpc_gss_get_versions(3t)
rpc_gss_is_installed(3t), rpc_gss_mech_to_oid(3t), and
rpc_gss_qop_to_num(3t)

This is a relatively simple patch, but there are a couple of
important design points to call out.

1.  Don't add a new DLL

Solaris and FreeBSD keep a dynamic library separate from libtirpc
for RPCSEC_GSS support, called librpcsec_gss. Our existing
RPCSEC_GSS support, though unfinished, is already built into our
fork of the libtirpc library. This patch continues with that
approach by adding these new functions in libtirpc instead of
introducing another library.

2.  Don't bother with /etc/gss/{mech,qop}

The Solaris gssapi implementation uses the files
/etc/gss/{mech,qop} to define supported GSS mechanisms. The
rpc_gss_*() API provides the utility functions added in this patch
so that RPC consumers can easily discover what GSS mechanisms are
available.

FreeBSD and Linux use the MIT gssapi implementation, which does not
use /etc/gss/{mech,qop} .

The FreeBSD implementation of the rpc_gss_*() API emulates support
for these configuration files, rather than invoking gssapi functions
that don't exist in the MIT gssapi library.

For Linux, I don't see a need for the extra config files:

  o  Our fork of libtirpc will support only the Kerberos GSS
     mechanism for the foreseeable future.
  o  It's easy to add another GSS mechanism in the static data
     structures, and that should be done only after thorough
     testing.
  o  It should be a simple change to add support for /etc/gss/* if
     we find we need it.
  o  Consumers of the rpc_gss_*() API ported from FreeBSD or
     Solaris should see exactly the same result when calling the
     new utility functions.

Signed-off-by: Chuck Lever <chuck.lever@oracle.com>
Signed-off-by: Steve Dickson <steved@redhat.com>

1 files changed, 67 insertions, 0 deletions

diff --git a/man/rpc_gss_qop_to_num.3t b/man/rpc_gss_qop_to_num.3t
new file mode 100644
index 0000000..3968216
--- /dev/null
+++ b/man/rpc_gss_qop_to_num.3t
@@ -0,0 +1,67 @@
+.\" Copyright (c) 2008 Isilon Inc http://www.isilon.com/
+.\" Authors: Doug Rabson <dfr@rabson.org>
+.\" Developed with Red Inc: Alfred Perlstein <alfred@FreeBSD.org>
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.Dd January 26, 2010
+.Dt RPC_GSS_QOP_TO_NUM 3
+.Os
+.Sh NAME
+.Nm rpc_gss_qop_to_num
+.Nd "Convert a quality of protection name to number"
+.Sh SYNOPSIS
+.In rpc/rpcsec_gss.h
+.Ft bool_t
+.Fn rpc_gss_qop_to_num "const char *qop" "const char *mech" "u_int *num_ret"
+.Sh DESCRIPTION
+This function looks up a quality of protection by name by reading the file
+/etc/gss/qop.
+.Sh PARAMETERS
+.Bl -tag -width ".It number_ret"
+.It qop
+The quality of protection to search for
+.It mech
+The mechanism name to search for
+.It number_ret
+If the quality of protection is found, the corresponding number is
+returned in
+.Fa *num_ret
+.El
+.Sh RETURN VALUES
+If the value is found,
+.Dv TRUE
+is returned, otherwise
+.Dv FALSE .
+.Sh AVAILABILITY
+The
+.Fn rpc_gss_qop_to_num
+function is part of libtirpc.
+.Sh SEE ALSO
+.Xr rpc 3 ,
+.Xr gssapi 3 ,
+.Xr rpcsec_gss 3
+.Sh AUTHORS
+This
+manual page was written by
+.An Doug Rabson Aq dfr@FreeBSD.org .