Add server-side rpc_gss_*() APIs

Introduce new RPCSEC API functions that match the same libtirpc API
in FreeBSD and Solaris.  This includes rpc_gss_getcred(3t),
rpc_gss_svc_max_data_length(3t), rpc_gss_set_svc_name(3t),
rpc_gss_set_callback(3t), and rpc_gss_get_principal_name(3t).

The man pages, written by Doug Rabson, come from FreeBSD, with
some adjustments by me.

The new code was written from scratch based on FreeBSD's
implementation, but adapted to invoke the existing legacy U-M APIs
in our implementation.  We will maintain the legacy APIs until
consumers are switched to the new ones.  FreeBSD never had the
legacy U-M API.

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

6 files changed, 421 insertions, 1 deletions

diff --git a/man/Makefile.am b/man/Makefile.am
index 366c650..cf510e7 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -12,7 +12,9 @@ RPCSEC_MANS		= rpcsec_gss.3t rpc_gss_get_error.3t \
 			  rpc_gss_get_versions.3t rpc_gss_is_installed.3t \
 			  rpc_gss_mech_to_oid.3t rpc_gss_qop_to_num.3t \
 			  rpc_gss_max_data_length.3t rpc_gss_seccreate.3t \
-			  rpc_gss_set_defaults.3t
+			  rpc_gss_set_defaults.3t rpc_gss_getcred.3t \
+			  rpc_gss_get_principal_name.3t rpc_gss_set_callback.3t \
+			  rpc_gss_set_svc_name.3t rpc_gss_svc_max_data_length.3t
 
 dist_man5_MANS		= netconfig.5
 dist_man3_MANS		= $(LOOKUP_MANS) $(NETCONFIG_MANS) \
diff --git a/man/rpc_gss_get_principal_name.3t b/man/rpc_gss_get_principal_name.3t
new file mode 100644
index 0000000..ba04239
--- /dev/null
+++ b/man/rpc_gss_get_principal_name.3t
@@ -0,0 +1,79 @@
+.\" 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_GET_PRINCIPAL_NAME 3
+.Os
+.Sh NAME
+.Nm rpc_gss_get_principal_name
+.Nd "Get a principal name"
+.Sh SYNOPSIS
+.In rpc/rpcsec_gss.h
+.Ft bool_t
+.Fo rpc_gss_get_principal_name
+.Fa "rpc_gss_principal_t *principal"
+.Fa "const char *mech"
+.Fa "const char *name"
+.Fa "const char *node"
+.Fa "const char *domain"
+.Fc
+.Sh DESCRIPTION
+This function can be used to generate a client principal name from
+various strings.
+.Sh PARAMETERS
+.Bl -tag -width ".It principal"
+.It principal
+If the principal is created successfully,
+.Fa *principal
+will be set to point at the new principal in GSS-API exported name form
+.It mech
+The name of the mechanism for this principal
+.It name
+The name part of the principal
+.It node
+If non-null, the hostname or instance part of the principal
+.It domain
+If non-null, the domain or realm part of the principal
+.El
+.Sh RETURN VALUES
+Returns
+.Dv TRUE
+if the principal was created or
+.Dv FALSE
+otherwise
+.Sh AVAILABILITY
+The
+.Fn rpc_gss_get_principal_name
+function is part of libtirpc.
+.Sh SEE ALSO
+.Xr rpc 3 ,
+.Xr gssapi 3 ,
+.Xr gss_export_name 3 ,
+.Xr rpcsec_gss 3
+.Sh AUTHORS
+This
+manual page was written by
+.An Doug Rabson Aq dfr@FreeBSD.org .
diff --git a/man/rpc_gss_getcred.3t b/man/rpc_gss_getcred.3t
new file mode 100644
index 0000000..8589f08
--- /dev/null
+++ b/man/rpc_gss_getcred.3t
@@ -0,0 +1,82 @@
+.\" 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_GETCRED 3
+.Os
+.Sh NAME
+.Nm rpc_gss_getcred
+.Nd "Get authorization information for an RPC request"
+.Sh SYNOPSIS
+.In rpc/rpcsec_gss.h
+.Ft AUTH *
+.Fo rpc_gss_getcred
+.Fa "struct svc_req *req"
+.Fa "rpc_gss_rawcred_t **rcred"
+.Fa "rpc_gss_ucred_t **ucred"
+.Fa "void **cookie"
+.Fc
+.Sh DESCRIPTION
+This function returns the RPCSEC_GSS authenticated credentials
+associated with an RPC request.
+.Sh PARAMETERS
+.Bl -tag -width ".It cookie"
+.It req
+The RPC request to query
+.It rcred
+If non-null,
+.Fa *rcred
+is set to point at the raw credentials for this request
+.It ucred
+.It rcred
+If non-null,
+.Fa *ucred
+is set to point at the corresponding unix credentials
+.It cookie
+If non-null,
+.Fa *cookie
+is set to the cookie value returned by a callback function registered with
+.Fn rpc_gss_set_callback
+.El
+.Sh RETURN VALUES
+Returns
+.Dv TRUE
+if successful,
+.Dv FALSE
+otherwise.
+.Sh AVAILABILITY
+The
+.Fn rpc_gss_getcred
+function is part of libtirpc.
+.Sh SEE ALSO
+.Xr rpc 3 ,
+.Xr gssapi 3 ,
+.Xr rpc_gss_set_callback 3 ,
+.Xr rpcsec_gss 3
+.Sh AUTHORS
+This
+manual page was written by
+.An Doug Rabson Aq dfr@FreeBSD.org .
diff --git a/man/rpc_gss_set_callback.3t b/man/rpc_gss_set_callback.3t
new file mode 100644
index 0000000..ee4ebdf
--- /dev/null
+++ b/man/rpc_gss_set_callback.3t
@@ -0,0 +1,112 @@
+.\" 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_SET_CALLBACK 3
+.Os
+.Sh NAME
+.Nm rpc_gss_set_callback
+.Nd "Register a security context creation callback"
+.Sh SYNOPSIS
+.In rpc/rpcsec_gss.h
+.Ft bool_t
+.Fo (*callback)
+.Fa "struct svc_req *req"
+.Fa "gss_cred_id_t deleg"
+.Fa "gss_ctx_id_t gss_context"
+.Fa "rpc_gss_lock_t *lock"
+.Fa "void **cookie"
+.Fc
+.Ft bool_t
+.Fn rpc_gss_set_callback "rpc_gss_callback_t *cb"
+.Sh DESCRIPTION
+Register a function which will be called when new security contexts
+are created on a server.
+This function will be called on the first RPC request which uses that
+context and has the opportunity of rejecting the request (for instance
+after matching the request credentials to an access control list).
+To accept the new security context, the callback should return
+.Dv TRUE ,
+otherwise
+.Dv FALSE .
+If the callback accepts a context, it becomes responsible for the
+lifetime of the delegated client credentials (if any).
+.Pp
+It is also possible to 'lock' the values of service and quality of
+protection used by the context.
+If a context is locked, any subsequent requests which use different
+values for service and quality of protection will be rejected.
+.Sh PARAMETERS
+.Bl -tag -width ".It gss_context"
+.It cb
+A structure containing the RPC program and version for this callback
+and a function which will be called when new contexts are created for
+the given RPC program and version
+.It req
+The RPC request using the new context
+.It deleg
+GSS-API delegated credentials (if any)
+.It gss_context
+The GSS-API context
+.It lock
+A structure used to enforce a particular QOP and service. Set
+.Fa lock->locked
+to
+.Dv TRUE
+to lock the service and QOP values
+.It cookie
+The callback function may set
+.Fa *cookie
+to any pointer sized value.
+This value can be accessed during the lifetime of the context via
+.Fn rpc_gss_getcred .
+.El
+.Sh RETURN VALUES
+Returns
+.Dv TRUE
+if the callback was registered successfully or
+.Dv FALSE
+otherwise
+.Sh AVAILABILITY
+The
+.Fn rpc_gss_set_callback
+function is part of libtirpc.
+.Sh SEE ALSO
+.Xr rpc 3 ,
+.Xr gssapi 3 ,
+.Xr rpc_gss_getcred 3
+.Xr rpcsec_gss 3
+.Sh AUTHORS
+This
+manual page was written by
+.An Doug Rabson Aq dfr@FreeBSD.org .
+.Sh BUGS
+There is no mechanism for informing a server when a security context
+has been deleted.
+This makes it difficult to allocate resources (e.g. to return via the
+callback's
+.Fa cookie
+argument).
diff --git a/man/rpc_gss_set_svc_name.3t b/man/rpc_gss_set_svc_name.3t
new file mode 100644
index 0000000..b895920
--- /dev/null
+++ b/man/rpc_gss_set_svc_name.3t
@@ -0,0 +1,84 @@
+.\" 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_SET_SVC_NAME 3
+.Os
+.Sh NAME
+.Nm rpc_gss_set_svc_name
+.Nd "Associate a GSS-API service principal with an RPC service"
+.Sh SYNOPSIS
+.In rpc/rpcsec_gss.h
+.Ft bool_t
+.Fo rpc_gss_set_svc_name
+.Fa "const char *principal"
+.Fa "const char *mechanism"
+.Fa "u_int req_time"
+.Fa "u_int program"
+.Fa "u_int version"
+.Fc
+.Sh DESCRIPTION
+This function registers a service principal which will be used to
+authenticate RPCSEC_GSS security contexts for a given RPC program and
+version.
+.Sh PARAMETERS
+.Bl -tag -width ".It mechanism"
+.It principal
+A string representing the service principal in the form
+.Qq service@hostname
+.It mechanism
+The name of the security mechanism
+.It req_time
+The time in seconds that the service credentials should remain
+valid.
+See
+.Xr gss_acquire_cred 3
+for more details.
+principal.
+.It program
+RPC program number for this service
+.It version
+RPC program version for this service
+.El
+.Sh RETURN VALUES
+Returns
+.Dv TRUE
+if the service principal was registered or
+.Dv FALSE
+otherwise.
+.Sh AVAILABILITY
+The
+.Fn rpc_gss_set_svc_name
+function is part of libtirpc.
+.Sh SEE ALSO
+.Xr rpc 3 ,
+.Xr gssapi 3 ,
+.Xr gss_acquire_cred 3 ,
+.Xr rpcsec_gss 3
+.Sh AUTHORS
+This
+manual page was written by
+.An Doug Rabson Aq dfr@FreeBSD.org .
diff --git a/man/rpc_gss_svc_max_data_length.3t b/man/rpc_gss_svc_max_data_length.3t
new file mode 100644
index 0000000..4b89716
--- /dev/null
+++ b/man/rpc_gss_svc_max_data_length.3t
@@ -0,0 +1,61 @@
+.\" 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_SVC_MAX_DATA_LENGTH 3
+.Os
+.Sh NAME
+.Nm rpc_gss_svc_max_data_length
+.Nd "calculate maximum data size"
+.Sh SYNOPSIS
+.In rpc/rpcsec_gss.h
+.Ft int
+.Fn rpc_gss_svc_max_data_length "struct svc_req *req" "int max_tp_unit_len"
+.Sh DESCRIPTION
+Calculate the maximum message size that will fit into a packet of size
+.Fa max_tp_unit_len ,
+given the current service and QoP setting.
+.Sh PARAMETERS
+.Bl -tag -width ".It max_tp_unit_len"
+.It req
+An RPC request
+.It max_tp_unit_len
+Maximum packet size of the underlying transport protocol
+.El
+.Sh RETURN VALUES
+The maximum message size that can be encoded
+.Sh AVAILABILITY
+The
+.Fn rpc_gss_svc_max_data_length
+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 .