netwerk/base/nsIAuthModule.idl

   1 /* vim:set ts=4 sw=4 et cindent: */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7 [uuid(6e35dbc0-49ef-4e2c-b1ea-b72ec64450a2)]
   8 interface nsIAuthModule : nsISupports
   9 {
  10     /**
  11      * Default behavior.
  12      */
  13     const unsigned long REQ_DEFAULT = 0;
  14
  15     /**
  16      * Client and server will be authenticated.
  17      */
  18     const unsigned long REQ_MUTUAL_AUTH = (1 << 0);
  19
  20     /**
  21      * The server is allowed to impersonate the client.  The REQ_MUTUAL_AUTH
  22      * flag may also need to be specified in order for this flag to take
  23      * effect.
  24      */
  25     const unsigned long REQ_DELEGATE = (1 << 1);
  26
  27     /**
  28      * The authentication is required for a proxy connection.
  29      */
  30     const unsigned long REQ_PROXY_AUTH = (1 << 2);
  31
  32     /**
  33      * Flags used for telemetry.
  34      */
  35     const unsigned long NTLM_MODULE_SAMBA_AUTH_PROXY = 0;
  36     const unsigned long NTLM_MODULE_SAMBA_AUTH_DIRECT = 1;
  37     const unsigned long NTLM_MODULE_WIN_API_PROXY = 2;
  38     const unsigned long NTLM_MODULE_WIN_API_DIRECT = 3;
  39     const unsigned long NTLM_MODULE_GENERIC_PROXY = 4;
  40     const unsigned long NTLM_MODULE_GENERIC_DIRECT = 5;
  41     const unsigned long NTLM_MODULE_KERBEROS_PROXY = 6;
  42     const unsigned long NTLM_MODULE_KERBEROS_DIRECT = 7;
  43
  44     /** Other flags may be defined in the future */
  45
  46     /**
  47      * Called to initialize an auth module.  The other methods cannot be called
  48      * unless this method succeeds.
  49      *
  50      * @param aServiceName
  51      *        the service name, which may be null if not applicable (e.g., for
  52      *        NTLM, this parameter should be null).
  53      * @param aServiceFlags
  54      *        a bitwise-or of the REQ_ flags defined above (pass REQ_DEFAULT
  55      *        for default behavior).
  56      * @param aDomain
  57      *        the authentication domain, which may be null if not applicable.
  58      * @param aUsername
  59      *        the user's login name
  60      * @param aPassword
  61      *        the user's password
  62      */
  63     void init(in ACString        aServiceName,
  64               in unsigned long aServiceFlags,
  65               in AString       aDomain,
  66               in AString       aUsername,
  67               in AString       aPassword);
  68
  69     /**
  70      * Called to get the next token in a sequence of authentication steps.
  71      *
  72      * @param aInToken
  73      *        A buffer containing the input token (e.g., a challenge from a
  74      *        server).  This may be null.
  75      * @param aInTokenLength
  76      *        The length of the input token.
  77      * @param aOutToken
  78      *        If getNextToken succeeds, then aOutToken will point to a buffer
  79      *        to be sent in response to the server challenge.  The length of
  80      *        this buffer is given by aOutTokenLength.  The buffer at aOutToken
  81      *        must be recycled with a call to free.
  82      * @param aOutTokenLength
  83      *        If getNextToken succeeds, then aOutTokenLength contains the
  84      *        length of the buffer (number of bytes) pointed to by aOutToken.
  85      */
  86     void getNextToken([const] in voidPtr  aInToken,
  87                       in unsigned long    aInTokenLength,
  88                       out voidPtr         aOutToken,
  89                       out unsigned long   aOutTokenLength);
  90     /**
  91      * Once a security context has been established through calls to GetNextToken()
  92      * it may be used to protect data exchanged between client and server. Calls
  93      * to Wrap() are used to protect items of data to be sent to the server.
  94      *
  95      * @param aInToken
  96      *        A buffer containing the data to be sent to the server
  97      * @param aInTokenLength
  98      *        The length of the input token
  99      * @param confidential
 100      *        If set to true, Wrap() will encrypt the data, otherwise data will
 101      *        just be integrity protected (checksummed)
 102      * @param aOutToken
 103      *        A buffer containing the resulting data to be sent to the server
 104      * @param aOutTokenLength
 105      *        The length of the output token buffer
 106      *
 107      * Wrap() may return NS_ERROR_NOT_IMPLEMENTED, if the underlying authentication
 108      * mechanism does not support security layers.
 109      */
 110     void wrap([const] in voidPtr aInToken,
 111               in unsigned long   aInTokenLength,
 112               in boolean         confidential,
 113               out voidPtr        aOutToken,
 114               out unsigned long  aOutTokenLength);
 115
 116     /**
 117      * Unwrap() is used to unpack, decrypt, and verify the checksums on data
 118      * returned by a server when security layers are in use.
 119      *
 120      * @param aInToken
 121      *        A buffer containing the data received from the server
 122      * @param aInTokenLength
 123      *        The length of the input token
 124      * @param aOutToken
 125      *        A buffer containing the plaintext data from the server
 126      * @param aOutTokenLength
 127      *        The length of the output token buffer
 128      *
 129      * Unwrap() may return NS_ERROR_NOT_IMPLEMENTED, if the underlying
 130      * authentication mechanism does not support security layers.
 131      */
 132     void unwrap([const] in voidPtr aInToken,
 133                 in unsigned long   aInTokenLength,
 134                 out voidPtr        aOutToken,
 135                 out unsigned long  aOutTokenLength);
 136
 137 %{C++
 138     /**
 139      * Create a new instance of an auth module.
 140      *
 141      * @param aType
 142      *        The type of the auth module to be constructed.
 143      */
 144     static already_AddRefed<nsIAuthModule> CreateInstance(const char* aType);
 145 %}
 146 };