path: root/gss.x

/*
 * 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_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_ctx_info   sec_ctx_info;
    default:
        octet_string    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) */