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   "arguments":
  10   {
  11     "argument_1": "string value",
  12     "argument_2": 0000, /* Number */
  13     "argument_3": ["array","of","values"]
  14   }
  15 }
  16
  17 Returns have a genaral structure of:
  18 {
  19   "method": "gss_api_call_name",
  20   "return_values":
  21   {
  22     "major_status": 0,
  23     "minor_status": 0,
  24     "return_1": "return value"
  25   }
  26 }
  27
  28 Background: data types
  29 ----------------------------------------------------------------------------
  30 GSS defines several data types, including names, security contexts,
  31 credentials, and OIDs.  The json_gssapi layer consumes and emits these as
  32 javascript strings, but each type expects its strings to conform to a
  33 specific format.
  34
  35 Data Type    Format
  36 ------------ --------------------------------------------------------
  37 Context      A Base64 encoded string.  json_gssapi users should never
  38              generate these.  Instead, users should use the value
  39              returned from the gss_init_sec_context method whenever
  40              a context is needed.
  41 Credential   A Base64 encoded string.  json_gssapi users should never
  42              generate these.  Instead, users should use the value
  43              returned from the gss_acquire_cred method whenever a
  44              credential is needed.
  45 Name         A Base64 encoded string.  json_gssapi users should never
  46              generate these.  Instead, users should use the value
  47              returned from the gss_import_name function whenever a
  48              name is needed.
  49 OID          A character string representing an OID
  50              (http://en.wikipedia.org/wiki/Object_identifier).  These
  51              will be either in the format of "{ # # ## # }" or in the
  52              format of "#.#.##.#"
  53
  54
  55 GSS Import Name
  56 ------------------------------------------------------------------------
  57 The gss_import_name call is used to convert a text string name into an
  58 internal representation that other GSS functions will use.  The call
  59 takes two arguments:
  60     input_name        The textual name to be imported
  61     input_name_type   The OID that specifies how input_name is
  62                       interpreted.
  63
  64 The call returns three values:
  65     major_status      Major status return code; 0 on success.
  66     minor_status      Minor status return code; 0 on success.
  67     gss_name          The Base64 encoded string representing the GSSAPI
  68                       name object.  (Note that this is a hash table
  69                       lookup key for the object, not the object itself)
  70
  71 The input_name string will have different formats, depending on the
  72 input_name_type specified.  Some popular combinations are:
  73
  74   input_name_type          expected input_name formatting
  75   ----------------------   ---------------------------------------------
  76   1.2.840.113554.1.2.1.1   username@realm
  77                            postmaster@example.com
  78
  79   1.2.840.113554.1.2.1.4   service@hostname
  80                            HTTP@www.example.com
  81
  82 Example message:
  83   {"method":"gss_import_name","arguments":{"input_name":"HTTP@localhost","input_name_type":"{1 2 840 113554 1 2 1 4 }"}}
  84
  85 GSS Initialize Security Context
  86 ------------------------------------------------------------------------------
  87 The gss_init_sec_context call is used to initialize a security context.  This
  88 is a two-party process.  The originating party will call gss_init_sec_context
  89 to generate (1) a GSS context return, and (2) a token to send to the other
  90 party.  The token is then communicated to the other party, which uses that as
  91 input to generate its own token in return.  The originating party then calls
  92 gss_init_sec_context again, including as parameters the token generated by
  93 the other side and the context generated by the first call to
  94 gss_init_sec_context.
  95
  96 Perhaps an illustration will be easier:
  97
  98 Initiating party                    Accepting party
  99 ----------------------------------- -----------------------------------
 100 Call gss_init_sec_context
 101    Receive back Token_I1
 102    Receive back context_I1
 103 Send Token_I1 to acceptor
 104                                      Receive Token_A1
 105                                      Call gss_accept_sec_context
 106                                         Receive back Token_A2
 107                                         Receive back Context_A2
 108                                      Send Token_A2 to initiator
 109 Call gss_init_sec_context
 110    Receive back Token_I3
 111    Receive back Context_I3
 112 Send Token_I3 to acceptor
 113                             ...
 114
 115 The back-and-forth communication negotiates a session, called a security
 116 context, between the two parties.  It continues while the
 117 gss_init_sec_context command returns a major_status value of 1,
 118 "GSS_CONTINUE_NEEDED".  Success is indicated by a major_status value of
 119 0.
 120
 121 The call takes arguments:
 122   target_name      The Base64 handle to the GSS name generated by
 123                    gss_import_name.  This name needs to match the name
 124                    that the acceptor calls itself.
 125   context_handle   The Base64 handle to the GSS context generated by the
 126                    previous call to gss_init_sec_context.  If this is
 127                    the first call, do not specify this argument.
 128   input_token      The token received back from the acceptor.  Omit this
 129                    parameter for the first call to gss_init_sec_context.
 130   mech_type        An OID of the security mechanism desired.  Omit this
 131                    to use the default mechanism.  (GSS_C_NO_OID)
 132   time_req         The number of seconds this security context (session)
 133                    should remain valid.  Omitting or setting a value of
 134                    0 results in the default of two hours.
 135   req_flags        An integer of a bitmask of flags representing
 136                    requested GSS services.  Omit unless you have reason
 137                    to include it.
 138
 139 Example messages:
 140   First invocation:
 141     {"method":"gss_create_sec_context","arguments":{"target_name":""}}
 142   Subsequent invocation:
 143     {"method":"gss_create_sec_context","arguments":{"target_name":"","context_handle":"","input_token":""}}
 144   ... where the target name comes from gss_import_name, the context
 145   handle comes from previous calls to gss_init_sec_contest, and the
 146   input token comes from the acceptor.
 147
 148
 149
 150 GSS Acquire Cred
 151 ------------------------------------------------------------------------
 152
 153 Arguments:
 154     desired_name     The Base64 handle to a GSS name generated by
 155                      gss_import_name.  This name represents the name to
 156                      be used in the credential.
 157     cred_usage       One of three values:
 158                      GSS_C_ACCEPT - used to accept security contexts
 159                      GSS_C_INITIATE - Used to initiate security contexts
 160                      GSS_C_BOTH - Used for both.
 161     time_req         The number of seconds this credential should remain
 162                      valid.  Omitting or setting a value of 0 results in
 163                      the default of two hours.
 164     desired_mechs    An array of OIDs for the desired security mechanisms
 165                      for use with this credential.  Omitting will use the
 166                      default set of mechanisms, which is what most uses
 167                      will want.  Include only if you know that you need
 168                      it.
 169
 170 This call returns values:
 171     major_status      Major status return code; 0 on success.
 172     minor_status      Minor status return code; 0 on success.
 173     cred_handle       The Base64 encoded string representing the GSSAPI
 174                       credential object.  (Note that this is a hash
 175                       table lookup key for the object, not the object
 176                       itself)
 177     actual_mechs      An array of strings representing the OIDs for
 178                       which the credential is valid.
 179     time_rec          The number of seconds for which this credential
 180                       will remain valid.
 181
 182 Example message:
 183   {"method":"gss_acquire_cred","arguments":{"cred_usage":"GSS_C_INITIATE","desired_name":""}}