doc/specification/draft-josefsson-sasl-api-export.txt

   1 Index: draft-newman-sasl-c-api-00.txt
   2 ===================================================================
   3 RCS file: /home/public-cvs/libgsasl/doc/specification/draft-newman-sasl-c-api-00.txt,v
   4 retrieving revision 1.1
   5 diff -u -p -u -w -r1.1 draft-newman-sasl-c-api-00.txt
   6 --- draft-newman-sasl-c-api-00.txt      7 Nov 2002 02:42:57 -0000       1.1
   7 +++ draft-newman-sasl-c-api-00.txt      5 Dec 2002 00:47:16 -0000
   8 @@ -1362,6 +1362,67 @@ Results:
   9        or calloc or resized by realloc.  The contents of the memory may
  10        be altered by this call.
  11
  12 + 5.2.   Exporting and importing security layer state
  13 +
  14 +      Some application environments wishes to separate the initial and
  15 +      short authentication step from the potentially long lived
  16 +      application step, where the application uses sasl_encode() and
  17 +      sasl_decode() to transfer application data.  This separation may
  18 +      be between processes (separation across hosts is more
  19 +      complicated, as the security layer state is often dependent on
  20 +      the host address, but still conceivable).  The reason for such
  21 +      separation may be to guarantee that long-term secrets (e.g.,
  22 +      passwords) cannot be recovered by compromising the application
  23 +      that handles existing session.
  24 +
  25 +      The functions defined in this section allows the application to
  26 +      export the security layer state associated with a session as an
  27 +      opaque character string, and later import the opaque character
  28 +      string.  The opaque state typically contains an encryption key,
  29 +      initialization vectors, what encryption algorithm to use, packet
  30 +      number etc.
  31 +
  32 +  5.2.1. sasl_export_security_layer_state function
  33 +
  34 +Arguments:
  35 +            sasl_conn_t *conn,
  36 +            const char **state,
  37 +            unsigned int *statelen
  38 +
  39 +Results:
  40 +            SASL_OK        -- Success
  41 +            SASL_NOTDONE   -- Security layer negotiation not finished
  42 +
  43 +      This function exports the security layer state required to
  44 +      implement the sasl_encode() and sasl_decode() functions after
  45 +      the state has been imported.  The security layer state is an
  46 +      opaque data string.  The state and statelen are filled in with
  47 +      the opaque state data and its length respectively. If the
  48 +      security layer negotiation has not finished, SASL_NOTDONE is
  49 +      returned.  After calling this function, the application should
  50 +      treat the SASL session as concluded and call sasl_dispose().  In
  51 +      particular, the application MUST NOT call sasl_encode() or
  52 +      sasl_decode() [XXX those functions should simply return a error
  53 +      code when it happens].  The state data is only valid until a
  54 +      call to sasl_dispose(), and should be copied before calling
  55 +      sasl_dipose() if necessary.
  56 +
  57 +  5.2.2. sasl_import_security_layer_state function
  58 +
  59 +
  60 +Arguments:
  61 +            const char *state,
  62 +            unsigned int statelen
  63 +            sasl_conn_t **conn,
  64 +
  65 +Results:
  66 +            SASL_OK        -- Success
  67 +
  68 +      This function create a SASL session, for use with sasl_encode(),
  69 +      sasl_decode() and sasl_dispose() only, from the given security
  70 +      layer state.  The security layer state is an opaque data string,
  71 +      as returned from sasl_export_security_layer_state().
  72 +
  73  6.     Additional Properties
  74
  75        <<To be completed>>