The json_gssapi layer provides an interface to calling the GSSAPI using JSON to communicate its data. The messages are passed to the layer to initiate a call into GSSAPI, and results are returned. The calling messages into the layer are expected to run one per line. The calls have a general structure of: { "method": "gss_api_call_name", "nonce": 0000, /* 32-bit integer */ "arguments": { "argument_1": "string value", "argument_2": 0000, /* Number */ "argument_3": ["array","of","values"] } } Returns have a general structure of: { "method": "gss_api_call_name", "return_values": { "major_status": 0, "minor_status": 0, "return_1": "return value", "errors": { "major_status_message": "...", "minor_status_message": "None" } } } Background: data types ---------------------------------------------------------------------------- GSS defines several data types, including names, security contexts, credentials, and OIDs. The json_gssapi layer consumes and emits these as javascript strings, but each type expects its strings to conform to a specific format. Data Type Format ------------ -------------------------------------------------------- Context A Base64 encoded string. json_gssapi users should never generate these. Instead, users should use the value returned from the gss_init_sec_context method whenever a context is needed. Credential A Base64 encoded string. json_gssapi users should never generate these. Instead, users should use the value returned from the gss_acquire_cred method whenever a credential is needed. Name A Base64 encoded string. json_gssapi users should never generate these. Instead, users should use the value returned from the gss_import_name function whenever a name is needed. OID A character string representing an OID (http://en.wikipedia.org/wiki/Object_identifier). These will be either in the format of "{ # # ## # }" or in the format of "#.#.##.#" GSS Import Name ------------------------------------------------------------------------ The gss_import_name call is used to convert a text string name into an internal representation that other GSS functions will use. The call takes two arguments: input_name The textual name to be imported input_name_type The OID that specifies how input_name is interpreted. The call returns three values: major_status Major status return code; 0 on success. minor_status Minor status return code; 0 on success. gss_name The Base64 encoded string representing the GSSAPI name object. (Note that this is a hash table lookup key for the object, not the object itself) The input_name string will have different formats, depending on the input_name_type specified. Some popular combinations are: input_name_type expected input_name formatting ---------------------- --------------------------------------------- 1.2.840.113554.1.2.1.1 username@realm postmaster@example.com 1.2.840.113554.1.2.1.4 service@hostname HTTP@www.example.com Example message: w{"method":"gss_import_name","arguments":{"input_name":"HTTP@localhost","input_name_type":"{1 2 840 113554 1 2 1 4 }"}} GSS Initialize Security Context ------------------------------------------------------------------------------ The gss_init_sec_context call is used to initialize a security context. This is a two-party process. The originating party will call gss_init_sec_context to generate (1) a GSS context return, and (2) a token to send to the other party. The token is then communicated to the other party, which uses that as input to generate its own token in return. The originating party then calls gss_init_sec_context again, including as parameters the token generated by the other side and the context generated by the first call to gss_init_sec_context. Perhaps an illustration will be easier: Initiating party Accepting party ----------------------------------- ----------------------------------- Call gss_init_sec_context Receive back Token_I1 Receive back context_I1 Send Token_I1 to acceptor Receive Token_A1 Call gss_accept_sec_context Receive back Token_A2 Receive back Context_A2 Send Token_A2 to initiator Call gss_init_sec_context Receive back Token_I3 Receive back Context_I3 Send Token_I3 to acceptor ... The back-and-forth communication negotiates a session, called a security context, between the two parties. It continues while the gss_init_sec_context command returns a major_status value of 1, "GSS_CONTINUE_NEEDED". Success is indicated by a major_status value of 0. The call takes arguments: target_name The Base64 handle to the GSS name generated by gss_import_name. This name needs to match the name that the acceptor calls itself. context_handle The Base64 handle to the GSS context generated by the previous call to gss_init_sec_context. If this is the first call, do not specify this argument. input_token The token received back from the acceptor. Omit this parameter for the first call to gss_init_sec_context. mech_type An OID of the security mechanism desired. Omit this to use the default mechanism, gss-eap-aes128. Another good option is "1.3.6.1.5.5.15.1.1.18", which is gss-eap-aes256. Anything not matching the prefix 1.3.6.1.5.5.15.1.1, with a single final segment, will be rejected. time_req The number of seconds this security context (session) should remain valid. Omitting or setting a value of 0 results in the default of two hours. req_flags An integer of a bitmask of flags representing requested GSS services. Omit unless you have reason to include it. Example messages: First invocation: {"method":"gss_init_sec_context","arguments":{"target_name":""}} Subsequent invocation: {"method":"gss_init_sec_context","arguments":{"target_name":"","context_handle":"","input_token":""}} ... where the target name comes from gss_import_name, the context handle comes from previous calls to gss_init_sec_contest, and the input token comes from the acceptor. GSS Acquire Cred ------------------------------------------------------------------------ Arguments: desired_name The Base64 handle to a GSS name generated by gss_import_name. This name represents the name to be used in the credential. cred_usage One of three values: GSS_C_ACCEPT - used to accept security contexts GSS_C_INITIATE - Used to initiate security contexts GSS_C_BOTH - Used for both. time_req The number of seconds this credential should remain valid. Omitting or setting a value of 0 results in the default of two hours. desired_mechs An array of OIDs for the desired security mechanisms for use with this credential. Omitting will use the default set of mechanisms, which is what most uses will want. Include only if you know that you need it. This call returns values: major_status Major status return code; 0 on success. minor_status Minor status return code; 0 on success. cred_handle The Base64 encoded string representing the GSSAPI credential object. (Note that this is a hash table lookup key for the object, not the object itself) actual_mechs An array of strings representing the OIDs for which the credential is valid. time_rec The number of seconds for which this credential will remain valid. Example message: {"method":"gss_acquire_cred","arguments":{"cred_usage":"GSS_C_INITIATE","desired_name":""}}