json_gssapi/json_protocol.txt

   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.
   5
   6 The calls have a general structure of:
   7 {
   8   "method": "gss_api_call_name",
   9   "nonce": 0000, /* 32-bit integer */
  10   "arguments":
  11   {
  12     "argument_1": "string value",
  13     "argument_2": 0000, /* Number */
  14     "argument_3": ["array","of","values"]
  15   }
  16 }
  17
  18 Returns have a general structure of:
  19 {
  20   "method": "gss_api_call_name",
  21   "return_values":
  22   {
  23     "major_status": 0,
  24     "minor_status": 0,
  25     "return_1": "return value",
  26     "errors":
  27     {
  28       "major_status_message": "...",
  29       "minor_status_message": "None"
  30     }
  31   }
  32 }
  33
  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
  39 specific format.
  40
  41 Data Type    Format
  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
  46              a context is needed.
  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
  50              credential is needed.
  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
  54              name is needed.
  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
  58              format of "#.#.##.#"
  59
  60
  61 GSS Import Name
  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
  65 takes two arguments:
  66     input_name        The textual name to be imported
  67     input_name_type   The OID that specifies how input_name is
  68                       interpreted.
  69
  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)
  76
  77 The input_name string will have different formats, depending on the
  78 input_name_type specified.  Some popular combinations are:
  79
  80   input_name_type          expected input_name formatting
  81   ----------------------   ---------------------------------------------
  82   1.2.840.113554.1.2.1.1   username@realm
  83                            postmaster@example.com
  84
  85   1.2.840.113554.1.2.1.4   service@hostname
  86                            HTTP@www.example.com
  87
  88 Example message:
  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 }"}}
  90
  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.
 101
 102 Perhaps an illustration will be easier:
 103
 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
 110                                      Receive Token_A1
 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
 119                             ...
 120
 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
 125 0.
 126
 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-eap-aes128.
 138                    Another good option is "1.3.6.1.5.5.15.1.1.18", which
 139                    is gss-eap-aes256.  Anything not matching the prefix
 140                    1.3.6.1.5.5.15.1.1, with a single final segment,
 141                    will be rejected.
 142   time_req         The number of seconds this security context (session)
 143                    should remain valid.  Omitting or setting a value of
 144                    0 results in the default of two hours.
 145   req_flags        An integer of a bitmask of flags representing
 146                    requested GSS services.  Omit unless you have reason
 147                    to include it.
 148
 149 Example messages:
 150   First invocation:
 151     {"method":"gss_init_sec_context","arguments":{"target_name":""}}
 152   Subsequent invocation:
 153     {"method":"gss_init_sec_context","arguments":{"target_name":"","context_handle":"","input_token":""}}
 154   ... where the target name comes from gss_import_name, the context
 155   handle comes from previous calls to gss_init_sec_contest, and the
 156   input token comes from the acceptor.
 157
 158
 159
 160 GSS Acquire Cred
 161 ------------------------------------------------------------------------
 162
 163 Arguments:
 164     desired_name     The Base64 handle to a GSS name generated by
 165                      gss_import_name.  This name represents the name to
 166                      be used in the credential.
 167     cred_usage       One of three values:
 168                      GSS_C_ACCEPT - used to accept security contexts
 169                      GSS_C_INITIATE - Used to initiate security contexts
 170                      GSS_C_BOTH - Used for both.
 171     time_req         The number of seconds this credential should remain
 172                      valid.  Omitting or setting a value of 0 results in
 173                      the default of two hours.
 174     desired_mechs    An array of OIDs for the desired security mechanisms
 175                      for use with this credential.  Omitting will use the
 176                      default set of mechanisms, which is what most uses
 177                      will want.  Include only if you know that you need
 178                      it.
 179
 180 This call returns values:
 181     major_status      Major status return code; 0 on success.
 182     minor_status      Minor status return code; 0 on success.
 183     cred_handle       The Base64 encoded string representing the GSSAPI
 184                       credential object.  (Note that this is a hash
 185                       table lookup key for the object, not the object
 186                       itself)
 187     actual_mechs      An array of strings representing the OIDs for
 188                       which the credential is valid.
 189     time_rec          The number of seconds for which this credential
 190                       will remain valid.
 191
 192 Example message:
 193   {"method":"gss_acquire_cred","arguments":{"cred_usage":"GSS_C_INITIATE","desired_name":""}}