netwerk/base/public/nsIAuthModule.idl

   1 /* vim:set ts=4 sw=4 et cindent: */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is Mozilla.
  16  *
  17  * The Initial Developer of the Original Code is IBM Corporation.
  18  * Portions created by IBM Corporation are Copyright (C) 2003
  19  * IBM Corporation. All Rights Reserved.
  20  *
  21  * Contributor(s):
  22  *   Darin Fisher <darin@meer.net>
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #include "nsISupports.idl"
  39 [uuid(6e35dbc0-49ef-4e2c-b1ea-b72ec64450a2)]
  40 interface nsIAuthModule : nsISupports
  41 {
  42     /**
  43      * Default behavior.
  44      */
  45     const unsigned long REQ_DEFAULT = 0;
  46
  47     /**
  48      * Client and server will be authenticated.
  49      */
  50     const unsigned long REQ_MUTUAL_AUTH = (1 << 0);
  51
  52     /**
  53      * The server is allowed to impersonate the client.  The REQ_MUTUAL_AUTH
  54      * flag may also need to be specified in order for this flag to take
  55      * effect.
  56      */
  57     const unsigned long REQ_DELEGATE = (1 << 1);
  58
  59     /** Other flags may be defined in the future */
  60
  61     /**
  62      * Called to initialize an auth module.  The other methods cannot be called
  63      * unless this method succeeds.
  64      *
  65      * @param aServiceName
  66      *        the service name, which may be null if not applicable (e.g., for
  67      *        NTLM, this parameter should be null).
  68      * @param aServiceFlags
  69      *        a bitwise-or of the REQ_ flags defined above (pass REQ_DEFAULT
  70      *        for default behavior).
  71      * @param aDomain
  72      *        the authentication domain, which may be null if not applicable.
  73      * @param aUsername
  74      *        the user's login name
  75      * @param aPassword
  76      *        the user's password
  77      */
  78     void init(in string        aServiceName,
  79               in unsigned long aServiceFlags,
  80               in wstring       aDomain,
  81               in wstring       aUsername,
  82               in wstring       aPassword);
  83
  84     /**
  85      * Called to get the next token in a sequence of authentication steps.
  86      *
  87      * @param aInToken
  88      *        A buffer containing the input token (e.g., a challenge from a
  89      *        server).  This may be null.
  90      * @param aInTokenLength
  91      *        The length of the input token.
  92      * @param aOutToken
  93      *        If getNextToken succeeds, then aOutToken will point to a buffer
  94      *        to be sent in response to the server challenge.  The length of
  95      *        this buffer is given by aOutTokenLength.  The buffer at aOutToken
  96      *        must be recycled with a call to nsMemory::Free.
  97      * @param aOutTokenLength
  98      *        If getNextToken succeeds, then aOutTokenLength contains the
  99      *        length of the buffer (number of bytes) pointed to by aOutToken.
 100      */
 101     void getNextToken([const] in voidPtr  aInToken,
 102                       in unsigned long    aInTokenLength,
 103                       out voidPtr         aOutToken,
 104                       out unsigned long   aOutTokenLength);
 105     /**
 106      * Once a security context has been established through calls to GetNextToken()
 107      * it may be used to protect data exchanged between client and server. Calls
 108      * to Wrap() are used to protect items of data to be sent to the server.
 109      *
 110      * @param aInToken
 111      *        A buffer containing the data to be sent to the server
 112      * @param aInTokenLength
 113      *        The length of the input token
 114      * @param confidential
 115      *        If set to true, Wrap() will encrypt the data, otherwise data will
 116      *        just be integrity protected (checksummed)
 117      * @param aOutToken
 118      *        A buffer containing the resulting data to be sent to the server
 119      * @param aOutTokenLength
 120      *        The length of the output token buffer
 121      *
 122      * Wrap() may return NS_ERROR_NOT_IMPLEMENTED, if the underlying authentication
 123      * mechanism does not support security layers.
 124      */
 125     void wrap([const] in voidPtr aInToken,
 126               in unsigned long   aInTokenLength,
 127               in boolean         confidential,
 128               out voidPtr        aOutToken,
 129               out unsigned long  aOutTokenLength);
 130
 131     /**
 132      * Unwrap() is used to unpack, decrypt, and verify the checksums on data
 133      * returned by a server when security layers are in use.
 134      *
 135      * @param aInToken
 136      *        A buffer containing the data received from the server
 137      * @param aInTokenLength
 138      *        The length of the input token
 139      * @param aOutToken
 140      *        A buffer containing the plaintext data from the server
 141      * @param aOutTokenLength
 142      *        The length of the output token buffer
 143      *
 144      * Unwrap() may return NS_ERROR_NOT_IMPLEMENTED, if the underlying
 145      * authentication mechanism does not support security layers.
 146      */
 147     void unwrap([const] in voidPtr aInToken,
 148                 in unsigned long   aInTokenLength,
 149                 out voidPtr        aOutToken,
 150                 out unsigned long  aOutTokenLength);
 151 };
 152
 153 %{C++
 154 /**
 155  * nsIAuthModule implementations are registered under the following contract
 156  * ID prefix:
 157  */
 158 #define NS_AUTH_MODULE_CONTRACTID_PREFIX \
 159     "@mozilla.org/network/auth-module;1?name="
 160
 161 /**
 162  * This success code may be returned by nsIAuthModule::getNextToken to
 163  * indicate that the authentication is finished and thus there's no need
 164  * to call getNextToken again.
 165  */
 166 #define NS_SUCCESS_AUTH_FINISHED \
 167     NS_ERROR_GENERATE_SUCCESS(NS_ERROR_MODULE_NETWORK, 40)
 168 %}