Added initial XDR file for GSS proxy RPC protocol

1 files changed, 522 insertions, 0 deletions

diff --git a/gss.x b/gss.x
new file mode 100644
index 0000000..9d21d4c
--- /dev/null
+++ b/gss.x
@@ -0,0 +1,522 @@
+/*
+ * Copyright (c) 2011, Secure Endpoints Inc.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * - Redistributions of source code must retain the above copyright
+ *   notice, this list of conditions and the following disclaimer.
+ *
+ * - 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 COPYRIGHT HOLDERS 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
+ * COPYRIGHT HOLDER 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.
+ *
+ */
+
+/*
+ * This is an initial attempt at creating an XDR representation of the
+ * GSS-API for the implementation of a GSS proxy client/server protocol,
+ * both over local IPC (for NFS and various other applications) and
+ * remote (for ssh-agent-like functionality).
+ *
+ * This is a work-in-progress.  However, rpcgen(1) on Ubuntu does
+ * compile this file.
+ *
+ * Because the GSS-API is based on "functions" and XDR is the basis for
+ * ONC RPC (which is based on "procedures") we use "_arg_" and "_res_"
+ * affixes to name structures, and we use those structures to encode
+ * function arguments and results, respectively.
+ *
+ * Naming functions are unified into one RPC for now.  Clients are
+ * expected to not call the proxy for GSS_Import_name() calls unless the
+ * name type is GSS_C_NT_EXPORTED_NAME.  Calls to GSS_Import/
+ * Canonicalize/Display_name() can done in one RPC.
+ *
+ * Credentials functions are also unified.  The idea is to not have to
+ * do multiple round-trips to acquire credentials then inquire them.
+ *
+ * GSS_Init/Accept_sec_context() similarly return all the information
+ * about a context that the app could want, including an exported
+ * security context token (so the app can import it).
+ *
+ * We support stateful and stateless proxy server implementations both.
+ *
+ * We use gssx_ as a prefix to avoid colliding with the C bindings.
+ *
+ * We use the XDR '*' operator to denote "optional" fields in structs.
+ * But for optional gss_OID and gss_OID_set arguments, and only those
+ * types of arguments,  we use empty OID/OID set to denote "not present"
+ * (presently no GSS functions have any special semantics for empty
+ * OIDs/OID sets; we can use '*' in the future if any new functions are
+ * added with such semantics).
+ */
+
+/* Generic base types */
+typedef opaque		utf8string<>;
+typedef opaque		octet_string<>;
+
+/* GSS base types */
+typedef unsigned hyper		gssx_uint64;	/* 64-bit for future proofing */
+typedef unsigned hyper		gssx_qop;
+typedef octet_string		gssx_buffer;	/* empty -> empty, !missing */
+typedef octet_string		gssx_OID;	/* empty -> GSS_C_NO_OID */
+typedef gssx_OID		gssx_OID_set<>;	/* empty -> GSS_C_NO_OID_SET */
+enum gssx_cred_usage {GSSX_C_INITIATE = 1, GSSX_C_ACCEPT = 2, GSSX_C_BOTH = 3};
+typedef unsigned hyper		gssx_time;	/* seconds since Unix epoch */
+
+/* Extensions */
+struct gssx_typed_hole {
+	/*
+	 * Negative values of ext_type will be for private use; positive
+	 * values will require registration.
+	 */
+	int		ext_type;
+	octet_string	ext_data;
+};
+
+/* Avoid round-trips for GSS_Display_status() */
+struct gssx_status {
+	gssx_uint64	major_status;
+	gssx_OID	mech;		/* to interpret minor_status by */
+	gssx_uint64	minor_status;
+	utf8string	major_status_string; /* localized; see below */
+	utf8string	minor_status_string; /* localized; see below */
+};
+
+/*
+ * Caller context.  This is needed to help the proxy server find user
+ * credentials, for example.  It could be used in the future for other
+ * extensions.  It could be used for gss_set_context_option() for some
+ * context options.
+ *
+ * A credential store is always implied in the GSS-API, but for a proxy
+ * GSS protocol we need an option to make the credential store explicit.
+ * The cred_store field is used to identify a credential store.
+ *
+ * For some implementations and/or use contexts cred_store may be an
+ * empty octet string.  Others might encode such things as environment
+ * variables in it.
+ */
+struct gssx_call_ctx {
+	utf8string		locale;	/* for status display string L10N */
+	gssx_typed_hole		cred_store;
+	gssx_typed_hole		extensions<>;
+};
+
+/* Example/possible structs to encode and use as cred_store */
+struct gssx__unix_kernel_cred_store {
+	/*
+	 * A unix kernel proxy client will want to tell the proxy server
+	 * most/every relevant details about the client process/thread
+	 * on behalf of which the kernel is doing this call.  Unless the
+	 * kernel can do this through an IPC-specific mechanism (e.g.,
+	 * door_ucred(3DOOR) in Solaris).
+	 *
+	 * The proxy server needs this information for either or both of
+	 * these two purposes: a) credential store identification, b)
+	 * authorization.  Some implementations might not need this for
+	 * (b) (e.g., where there's a per-user or per-session proxy
+	 * server, in which case access to the IPC endpoint might be
+	 * authorization enough).
+	 */
+	gss_uint64		pid; /* process ID */
+	gss_uint64		tid; /* thread ID */
+	gss_uint64		euid;/* effective UID */
+	gss_uint64		pag; /* PAG; 0 -> no PAG */
+	/*
+	 * Lots of other things could be relevant here, such as keyring
+	 * IDs, labels, ...
+	 *
+	 * A lot of this might be obviated by SCM_CREDENTIALS or
+	 * door_ucred(3DOOR) type interfaces, so for some OSes this
+	 * structure might well be empty.
+	 */
+};
+struct gssx__unix_user_cred_store {
+	utf8string		environment<>;	/* for non-kernel clients */
+	/* The proxy server has to apply some form of authorization, of course */
+};
+
+/*
+ * For NAME we don't use a plain opaque handle representation.  Our aim
+ * is to be able to implement GSS_Import_name() and GSS_Display_name()
+ * without talking to the proxy server (e.g., when the name type is not
+ * an exported name type), and to unify those and GSS_Canonicalize_name()
+ * and GSS_Get/Set_name_attribute() into one RPC.
+ */
+struct gssx_name {
+	/* Non-MNs MUST have these; MNs MAY have these */
+	gssx_buffer	*display_name;
+	gssx_OID	name_type;
+	/* MNs MUST have at least one exported name */
+	gssx_buffer	*exported_name;
+	gssx_buffer	*exported_composite_name;
+	/* Name attributes */
+	gssx_typed_hole	desired_name_attributes<>;
+	gssx_typed_hole	actual_name_attributes<>;
+	gssx_typed_hole	extensions<>;
+};
+
+/*
+ * CREDENTIAL and CONTEXT handles
+ */
+struct gssx_cred_info {
+	/* GSS_Inquire_cred_by_mech() outputs */
+	gssx_name	MN;
+	gssx_OID	mech;
+	gssx_cred_usage	cred_usage;
+	gssx_time	initiator_time_rec;
+	gssx_time	acceptor_time_rec;
+	gssx_typed_hole	cred_options<>;
+	gssx_typed_hole	extensions<>;
+};
+struct gssx_sec_ctx_info {
+	/* GSS_Inquire_context() outputs */
+	gssx_OID	mech;
+	gssx_name	src_name;
+	gssx_name	targ_name;
+	gssx_time	lifetime;
+	gssx_uint64	ctx_flags;
+	bool		locally_initiated;
+	bool		open;
+	gssx_typed_hole	context_options<>;
+	gssx_typed_hole	extensions<>;
+};
+enum gssx_handle_type { GSSX_C_HANDLE_SEC_CTX = 0, GSSX_C_HANDLE_CRED = 1 };
+union gssx_handle_info switch (gssx_handle_type handle_type) {
+	case GSSX_C_HANDLE_CRED:
+		gssx_cred_info		cred_info<>; /* One per cred element */
+	case GSSX_C_HANDLE_SEC_CTX:
+		gssx_sec_ctx_info	sec_ctx_info;
+	default:
+		gssx_typed_hole		extensions<>; /* Future handle types */
+};
+struct gssx_handle {
+	gssx_handle_info	handle_info;	    /* Has handle type */
+	octet_string		*handle;	    /* Server-specific bits */
+	octet_string		*exported_handle;   /* Local standard form */
+	bool			needs_release;	    /* For stateful proxies */
+};
+typedef gssx_handle		gssx_ctx;
+typedef gssx_handle		gssx_cred;
+
+/*
+ * We should probably come up with a standard RFC4121 context export
+ * token structure here.  We only need, basically, the session keys and
+ * initial token sequence numbers (plus, for clients that want to proxy
+ * per-msg token functions to stateless servers, we'd need a sequence
+ * number window structure).  Things like authz-data can be placed in
+ * the gssx_name's exported_composite_name or extensions fields, in the
+ * handle_info.
+ */
+
+/* Channel bindings */
+struct gssx_cb {
+	/*
+	 * Address type CB is deprecated; use only application_data.
+	 * See RFCs 5056 and 5554.
+	 */
+	gssx_uint64		initiator_addrtype; /* deprecated */
+	gssx_buffer		initiator_address;  /* deprecated */
+	gssx_uint64		acceptor_addrtype;  /* deprecated */
+	gssx_buffer		acceptor_address;   /* deprecated */
+	gssx_buffer		application_data;
+	/*
+	 * There's no extensibility here, and there must not be.  All CB
+	 * extensibility in the GSS-API now is a matter of
+	 * application_data formatting conventions.
+	 */
+};
+typedef	struct gssx_cb gssx_cb;
+
+/* One RPC for all handle release functions */
+struct gssx_arg_release_handle {
+	gssx_call_ctx	call_ctx;
+	gssx_handle	cred_handle;
+};
+struct gssx_res_release_handle {
+	gssx_status	status;
+};
+
+/* We unify GSS_Import/Canonicalize_name() */
+struct gssx_arg_import_and_canon_name {
+	gssx_call_ctx	call_ctx;
+	gssx_name	input_name;
+	gssx_OID	mech;
+	gssx_typed_hole	extensions<>;
+};
+struct gssx_res_import_and_canon_name {
+	gssx_status	status;
+	gssx_name	*output_name;
+	gssx_typed_hole	extensions<>;
+};
+
+struct gssx_arg_get_call_context {
+	gssx_call_ctx	call_ctx;
+};
+struct gssx_res_get_call_context {
+	gssx_status	status;
+	gssx_call_ctx	call_ctx;
+};
+
+/*
+ * We unify GSS_Acquire/Add_cred() here.
+ *
+ * GSS_Add_cred() is only meaningful here for stateful proxy server
+ * implementations.  Stateless ones will always output a new handle;
+ * stateful ones will modify the given input handle if desired, but we
+ * still include a handle in the result for the handle_info.
+ */
+struct gssx_arg_acquire_cred {
+	gssx_call_ctx	call_ctx;
+	gssx_cred	*input_cred_handle;
+	bool		add_cred_to_input_handle;
+	gssx_name	*desired_name; /* absent -> GSS_C_NO_NAME */
+	gssx_time	time_req;
+	gssx_OID_set	desired_mechs; /* no need to dist. empty vs. absent */
+	gssx_cred_usage	cred_usage;
+	gssx_time	initiator_time_req;
+	gssx_time	acceptor_time_req;
+	gssx_typed_hole	extensions<>;
+};
+struct gssx_res_acquire_cred {
+	gssx_status	status;
+	gssx_cred	*output_cred_handle; /* includes info */
+	gssx_typed_hole	extensions<>;
+};
+
+struct gssx_arg_store_cred {
+	gssx_call_ctx	call_ctx;
+	gssx_cred	input_cred_handle;
+	gssx_cred_usage	cred_usage;
+	gssx_OID	desired_mech;
+	bool		overwrite_cred;
+	bool		default_cred;
+};
+struct gssx_res_store_cred {
+	gssx_status	status;
+	gssx_OID_set	elements_stored;
+	gssx_cred_usage	cred_usage_stored;
+};
+
+/*
+ * Security context functions
+ *
+ * We don't need GSS_Inquire_context(), nor GSS_Import/
+ * Export_sec_context().  These are all subsumed into
+ * GSS_Init/Accept_sec_context() in this protocol.
+ */
+struct gssx_arg_init_sec_context {
+	gssx_call_ctx	call_ctx;
+	gssx_ctx	*context_handle;
+	gssx_cred	*cred_handle; /* absent -> GSS_C_NO_CREDENTIAL */
+	gssx_name	*target_name; /* absent -> GSS_C_NO_NAME */
+	gssx_OID	mech_type;
+	gssx_uint64	req_flags;
+	gssx_time	time_req;
+	gssx_cb		*input_chan_bindings;
+	gssx_buffer	*input_token;
+	gssx_typed_hole	extensions<>;
+};
+struct gssx_res_init_sec_context {
+	gssx_status	status;
+	gssx_ctx	*context_handle; /* includes info outputs */
+	gssx_buffer	*output_token;	
+	gssx_typed_hole	extensions<>;
+};
+
+struct gssx_arg_accept_sec_context {
+	gssx_call_ctx	call_ctx;
+	gssx_ctx	*context_handle;
+	gssx_cred	*cred_handle; /* absent -> GSS_C_NO_CREDENTIAL */
+	gssx_buffer	input_token;
+	gssx_cb		*input_chan_bindings;
+	gssx_typed_hole	extensions<>;
+};
+struct gssx_res_accept_sec_context {
+	gssx_status	status;
+	gssx_ctx	*context_handle; /* includes info outputs */
+	gssx_buffer	*output_token;
+	gssx_cred	*delegated_cred_handle;
+	gssx_typed_hole	extensions<>;
+};
+
+/*
+ * We provide per-message token functions for testing and bootstrap
+ * purposes: a client might not have a provider for a given mechanism,
+ * in which case the proxy can provide per-message token functions to
+ * the client.  This is primarily useful for testing that the
+ * client-side provider and the server-side provider have interoperable
+ * per-message token functions, which can be especially important for
+ * kernel-mode client use cases.
+ *
+ * The results of these functions have an optional context_handle output
+ * so that stateless servers can store sequence number windows and such
+ * things in the returned handle.
+ *
+ * Server support for this is optional.  Clients should really not need
+ * this.
+ */
+struct gssx_arg_get_mic {
+	gssx_call_ctx	call_ctx;
+	gssx_ctx	context_handle;
+	gssx_qop	qop_req;
+	gssx_buffer	message_buffer;
+};
+struct gssx_res_get_mic {
+	gssx_status	status;
+	gssx_ctx	*context_handle;
+	gssx_buffer	token_buffer; /* empty on error */
+	gssx_qop	*qop_state;
+};
+
+struct gssx_arg_verify_mic {
+	gssx_call_ctx	call_ctx;
+	gssx_ctx	context_handle;
+	gssx_buffer	message_buffer;
+	gssx_buffer	token_buffer;
+};
+struct gssx_res_verify_mic {
+	gssx_status	status;
+	gssx_ctx	*context_handle;
+	gssx_qop	*qop_state;
+};
+
+/*
+ * We use gssx_buffer<> to make implementation of iov variants slightly
+ * easier.
+ */
+struct gssx_arg_wrap {
+	gssx_call_ctx	call_ctx;
+	gssx_ctx	context_handle;
+	bool		conf_req;
+	gssx_buffer	message_buffer<>;
+	gssx_qop	qop_state;
+};
+struct gssx_res_wrap {
+	gssx_status	status;
+	gssx_ctx	*context_handle;
+	gssx_buffer	token_buffer<>;
+	bool		*conf_state;
+	gssx_qop	*qop_state;
+};
+
+struct gssx_arg_unwrap {
+	gssx_call_ctx	call_ctx;
+	gssx_ctx	context_handle;
+	gssx_buffer	token_buffer<>;
+	gssx_qop	qop_state;
+};
+struct gssx_res_unwrap {
+	gssx_status	status;
+	gssx_ctx	*context_handle;
+	gssx_buffer	message_buffer<>;
+	bool		*conf_state;
+	gssx_qop	*qop_state;
+};
+
+struct gssx_arg_wrap_size_limit {
+	gssx_call_ctx	call_ctx;
+	gssx_ctx	context_handle;
+	bool		conf_req;
+	gssx_qop	qop_state;
+	gssx_uint64	req_output_size;
+};
+struct gssx_res_wrap_size_limit {
+	gssx_status	status;
+	gssx_uint64	max_input_size;
+};
+
+/* Various inquiry functions */
+struct gssx_arg_indicate_mechs {
+	gssx_call_ctx	call_ctx;
+};
+struct gssx_res_indicate_mechs {
+	gssx_status	status;
+	gssx_OID_set	mech_set;
+};
+
+struct gssx_arg_indicate_mechs_by_attr {
+	gssx_call_ctx	call_ctx;
+	gssx_OID_set	desired_mech_attrs;
+	gssx_OID_set	except_mech_attrs;
+	gssx_OID_set	critical_mech_attrs;
+};
+struct gssx_res_indicate_mechs_by_attr {
+	gssx_status	status;
+	gssx_OID_set	mech_set;
+};
+
+struct gssx_arg_inquire_attrs_for_mech {
+	gssx_call_ctx	call_ctx;
+	gssx_OID	mech;
+};
+struct gssx_res_inquire_attrs_for_mech {
+	gssx_status	status;
+	gssx_OID_set	mech_attrs;
+	gssx_OID_set	known_mech_attrs;
+};
+
+struct gssx_arg_display_mech_attr {
+	gssx_call_ctx	call_ctx;
+	gssx_OID	mech_attr;
+};
+struct gssx_res_display_mech_attr {
+	gssx_status	status;
+	gssx_buffer	name;
+	gssx_buffer	short_desc;
+	gssx_buffer	long_desc;
+};
+
+program GSSPROXY {
+    version GSSPROXYVERS {
+	gssx_res_indicate_mechs
+	    GSSX_INDICATE_MECHS(gssx_arg_indicate_mechs) = 1;
+	gssx_res_indicate_mechs_by_attr
+	    GSSX_INDICATE_MECHS_BY_ATTR(gssx_arg_indicate_mechs_by_attr) = 2;
+	gssx_res_inquire_attrs_for_mech
+	    GSSX_INQUIRE_ATTRS_FOR_MECH(gssx_arg_inquire_attrs_for_mech) = 3;
+	gssx_res_display_mech_attr
+	    GSSX_DISPLAY_MECH_ATTR(gssx_arg_display_mech_attr) = 4;
+	gssx_res_get_call_context
+	    GSSX_GET_CALL_CONTEXT(gssx_arg_get_call_context) = 5;
+	gssx_res_import_and_canon_name
+	    GSSX_IMPORT_AND_CANON_NAME(gssx_arg_import_and_canon_name) = 6;
+	gssx_res_acquire_cred
+	    GSSX_ACQUIRE_CRED(gssx_arg_acquire_cred) = 7;
+	gssx_res_store_cred
+	    GSSX_STORE_CRED(gssx_arg_store_cred) = 8;
+	gssx_res_init_sec_context
+	    GSSX_INIT_SEC_CONTEXT(gssx_arg_init_sec_context) = 9;
+	gssx_res_accept_sec_context
+	    GSSX_ACCEPT_SEC_CONTEXT(gssx_arg_accept_sec_context) = 10;
+	gssx_res_release_handle
+	    GSSX_RELEASE_HANDLE(gssx_arg_release_handle) = 11;
+	gssx_res_get_mic
+	    GSSX_GET_MIC(gssx_arg_get_mic) = 12;
+	gssx_res_verify_mic
+	    GSSX_VERIFY(gssx_arg_verify_mic) = 13;
+	gssx_res_wrap
+	    GSSX_WRAP(gssx_arg_wrap) = 14;
+	gssx_res_unwrap
+	    GSSX_UNWRAP(gssx_arg_unwrap) = 15;
+	gssx_res_wrap_size_limit
+	    GSSX_WRAP_SIZE_LIMIT(gssx_arg_wrap_size_limit) = 16;
+    } = 1;
+} = 412345; /* XXX obtain from Oracle (Bill Baker, I think) */