1 The json_gssapi layer provides an interface to calling the GSSAPI using JSON
2 to communicate its data. The messages are passed to the layer to initiate
3 a call into GSSAPI, and results are returned. The calling messages into the
4 layer are expected to run one per line.
6 The calls have a general structure of:
8 "method": "gss_api_call_name",
9 "nonce": 0000, /* 32-bit integer */
12 "argument_1": "string value",
13 "argument_2": 0000, /* Number */
14 "argument_3": ["array","of","values"]
18 Returns have a general structure of:
20 "method": "gss_api_call_name",
25 "return_1": "return value",
28 "major_status_message": "...",
29 "minor_status_message": "None"
34 Background: data types
35 ----------------------------------------------------------------------------
36 GSS defines several data types, including names, security contexts,
37 credentials, and OIDs. The json_gssapi layer consumes and emits these as
38 javascript strings, but each type expects its strings to conform to a
42 ------------ --------------------------------------------------------
43 Context A Base64 encoded string. json_gssapi users should never
44 generate these. Instead, users should use the value
45 returned from the gss_init_sec_context method whenever
47 Credential A Base64 encoded string. json_gssapi users should never
48 generate these. Instead, users should use the value
49 returned from the gss_acquire_cred method whenever a
51 Name A Base64 encoded string. json_gssapi users should never
52 generate these. Instead, users should use the value
53 returned from the gss_import_name function whenever a
55 OID A character string representing an OID
56 (http://en.wikipedia.org/wiki/Object_identifier). These
57 will be either in the format of "{ # # ## # }" or in the
62 ------------------------------------------------------------------------
63 The gss_import_name call is used to convert a text string name into an
64 internal representation that other GSS functions will use. The call
66 input_name The textual name to be imported
67 input_name_type The OID that specifies how input_name is
70 The call returns three values:
71 major_status Major status return code; 0 on success.
72 minor_status Minor status return code; 0 on success.
73 gss_name The Base64 encoded string representing the GSSAPI
74 name object. (Note that this is a hash table
75 lookup key for the object, not the object itself)
77 The input_name string will have different formats, depending on the
78 input_name_type specified. Some popular combinations are:
80 input_name_type expected input_name formatting
81 ---------------------- ---------------------------------------------
82 1.2.840.113554.1.2.1.1 username@realm
83 postmaster@example.com
85 1.2.840.113554.1.2.1.4 service@hostname
89 w
\0\0\0{"method":"gss_import_name","arguments":{"input_name":"HTTP@localhost","input_name_type":"{1 2 840 113554 1 2 1 4 }"}}
91 GSS Initialize Security Context
92 ------------------------------------------------------------------------------
93 The gss_init_sec_context call is used to initialize a security context. This
94 is a two-party process. The originating party will call gss_init_sec_context
95 to generate (1) a GSS context return, and (2) a token to send to the other
96 party. The token is then communicated to the other party, which uses that as
97 input to generate its own token in return. The originating party then calls
98 gss_init_sec_context again, including as parameters the token generated by
99 the other side and the context generated by the first call to
100 gss_init_sec_context.
102 Perhaps an illustration will be easier:
104 Initiating party Accepting party
105 ----------------------------------- -----------------------------------
106 Call gss_init_sec_context
107 Receive back Token_I1
108 Receive back context_I1
109 Send Token_I1 to acceptor
111 Call gss_accept_sec_context
112 Receive back Token_A2
113 Receive back Context_A2
114 Send Token_A2 to initiator
115 Call gss_init_sec_context
116 Receive back Token_I3
117 Receive back Context_I3
118 Send Token_I3 to acceptor
121 The back-and-forth communication negotiates a session, called a security
122 context, between the two parties. It continues while the
123 gss_init_sec_context command returns a major_status value of 1,
124 "GSS_CONTINUE_NEEDED". Success is indicated by a major_status value of
127 The call takes arguments:
128 target_name The Base64 handle to the GSS name generated by
129 gss_import_name. This name needs to match the name
130 that the acceptor calls itself.
131 context_handle The Base64 handle to the GSS context generated by the
132 previous call to gss_init_sec_context. If this is
133 the first call, do not specify this argument.
134 input_token The token received back from the acceptor. Omit this
135 parameter for the first call to gss_init_sec_context.
136 mech_type An OID of the security mechanism desired. Omit this
137 to use the default mechanism. (GSS_C_NO_OID)
138 time_req The number of seconds this security context (session)
139 should remain valid. Omitting or setting a value of
140 0 results in the default of two hours.
141 req_flags An integer of a bitmask of flags representing
142 requested GSS services. Omit unless you have reason
147 {"method":"gss_create_sec_context","arguments":{"target_name":""}}
148 Subsequent invocation:
149 {"method":"gss_create_sec_context","arguments":{"target_name":"","context_handle":"","input_token":""}}
150 ... where the target name comes from gss_import_name, the context
151 handle comes from previous calls to gss_init_sec_contest, and the
152 input token comes from the acceptor.
157 ------------------------------------------------------------------------
160 desired_name The Base64 handle to a GSS name generated by
161 gss_import_name. This name represents the name to
162 be used in the credential.
163 cred_usage One of three values:
164 GSS_C_ACCEPT - used to accept security contexts
165 GSS_C_INITIATE - Used to initiate security contexts
166 GSS_C_BOTH - Used for both.
167 time_req The number of seconds this credential should remain
168 valid. Omitting or setting a value of 0 results in
169 the default of two hours.
170 desired_mechs An array of OIDs for the desired security mechanisms
171 for use with this credential. Omitting will use the
172 default set of mechanisms, which is what most uses
173 will want. Include only if you know that you need
176 This call returns values:
177 major_status Major status return code; 0 on success.
178 minor_status Minor status return code; 0 on success.
179 cred_handle The Base64 encoded string representing the GSSAPI
180 credential object. (Note that this is a hash
181 table lookup key for the object, not the object
183 actual_mechs An array of strings representing the OIDs for
184 which the credential is valid.
185 time_rec The number of seconds for which this credential
189 {"method":"gss_acquire_cred","arguments":{"cred_usage":"GSS_C_INITIATE","desired_name":""}}