include/realmedia/rmaauth.h

   1 /****************************************************************************
   2  *
   3  *  $Id: rmaauth.h 7 2003-05-30 02:18:02Z gabest $
   4  *
   5  *  Copyright (C) 1995-1999 RealNetworks, Inc. All rights reserved.
   6  *
   7  *  http://www.real.com/devzone
   8  *
   9  *  This program contains proprietary
  10  *  information of Progressive Networks, Inc, and is licensed
  11  *  subject to restrictions on use and distribution.
  12  *
  13  *  Authentication and password interfaces.
  14  *
  15  */
  16
  17 #ifndef _RMAAUTH_H_
  18 #define _RMAAUTH_H_
  19
  20 /*
  21  * Forward declarations of some interfaces defined or used here-in.
  22  */
  23 typedef _INTERFACE  IRMAAuthenticator               IRMAAuthenticator;
  24 typedef _INTERFACE  IRMAAuthenticatorResponse       IRMAAuthenticatorResponse;
  25 typedef _INTERFACE  IRMAAuthenticatorRequest        IRMAAuthenticatorRequest;
  26 typedef _INTERFACE  IRMAPassword                    IRMAPassword;
  27 typedef _INTERFACE  IRMAAuthenticationManagerResponse IRMAAuthenticationManagerResponse;
  28 typedef _INTERFACE  IRMAValues                      IRMAValues;
  29 typedef _INTERFACE  IRMABuffer                      IRMABuffer;
  30
  31 /****************************************************************************
  32  *
  33  *  Interface:
  34  *
  35  *      IRMAAuthenticator
  36  *
  37  *  Purpose:
  38  *
  39  *      Provide a means of authenticating users.
  40  *
  41  *  IID_IRMAAuthenticator:
  42  *
  43  *      {00001800-0901-11d1-8B06-00A024406D59}
  44  *
  45  */
  46
  47 DEFINE_GUID(IID_IRMAAuthenticator, 0x00001800, 0x901, 0x11d1, 0x8b, 0x6, 0x0,
  48                         0xa0, 0x24, 0x40, 0x6d, 0x59);
  49
  50 #define CLSID_IRMAAuthenticator IID_IRMAAuthenticator
  51
  52 #undef  INTERFACE
  53 #define INTERFACE IRMAAuthenticator
  54
  55 DECLARE_INTERFACE_(IRMAAuthenticator, IUnknown)
  56 {
  57     STDMETHOD(QueryInterface)           (THIS_
  58                                         REFIID riid,
  59                                         void** ppvObj) PURE;
  60
  61     STDMETHOD_(ULONG,AddRef)          (THIS) PURE;
  62
  63     STDMETHOD_(ULONG,Release)         (THIS) PURE;
  64
  65     /*
  66      * InitAuthenticator is called by the creator of the Authenticator
  67      * object in order to pass it an IRMAAuthenticatorRequest object,
  68      * usually implemented by the creator itself.
  69      */
  70     STDMETHOD(InitAuthenticator) (THIS_
  71                                   IRMAAuthenticatorRequest* pRequest) PURE;
  72     /*
  73      * Authenticate is called by a file object (and others??)
  74      * when it wants to ask the creator, presumably an FS Manager,
  75      * for authorization to open it's file.
  76      *
  77      * Authenticate will call IRMAAuthenticateResponse::AuthenticateDone
  78      * when done with PNR_OK or an error.
  79      *
  80      * File objects will presumably perform the Authenticate response as
  81      * part of their Init() call, and not call InitDone until they receive
  82      * a response one way or the other.
  83      */
  84     STDMETHOD(Authenticate) (THIS_
  85                              IRMAValues* pValues,
  86                              IRMAAuthenticatorResponse* pResponse) PURE;
  87
  88     /* GenerateAuthRequest is called by the creator of this object
  89      * when they want to send an authentication request to someone.
  90      */
  91     STDMETHOD(GenerateAuthRequest) (THIS_
  92                                     UINT32 authType,
  93                                     REF(IRMAValues*) pValues) PURE;
  94     /*
  95      * AuthValuesReady is called by IRMAAuthenticatorRequest when it
  96      * is ready to respond to a GetAuthValues request.
  97      */
  98     STDMETHOD(AuthValuesReady) (THIS_
  99                                 PN_RESULT result,
 100                                 IRMAValues* pValues) PURE;
 101 };
 102
 103
 104 /****************************************************************************
 105  *
 106  *  Interface:
 107  *
 108  *      IRMAAuthenticatorResponse
 109  *
 110  *  Purpose:
 111  *
 112  *      Response object for the Authenticator class.
 113  *
 114  *  IID_IRMAAuthenticatorResponse:
 115  *
 116  *      {00001801-0901-11d1-8B06-00A024406D59}
 117  *
 118  */
 119
 120 DEFINE_GUID(IID_IRMAAuthenticatorResponse, 0x00001801, 0x901, 0x11d1, 0x8b, 0x6, 0x0,
 121                         0xa0, 0x24, 0x40, 0x6d, 0x59);
 122
 123 #undef  INTERFACE
 124 #define INTERFACE IRMAAuthenticatorResponse
 125
 126 DECLARE_INTERFACE_(IRMAAuthenticatorResponse, IUnknown)
 127 {
 128     STDMETHOD(QueryInterface)           (THIS_
 129                                         REFIID riid,
 130                                         void** ppvObj) PURE;
 131
 132     STDMETHOD_(ULONG,AddRef)          (THIS) PURE;
 133
 134     STDMETHOD_(ULONG,Release)         (THIS) PURE;
 135
 136     /* AuthenticateDone is called by an IRMAAuthenticator when it has
 137      * finished it's authorization steps.  If the result is PNR_OK,
 138      * then the values contain authorization information as generated by
 139      * IRMAPassword.
 140      */
 141     STDMETHOD(AuthenticateDone) (THIS_ PN_RESULT result,
 142                                 IRMAValues* pAuthResponseValues) PURE;
 143 };
 144
 145
 146 /****************************************************************************
 147  *
 148  *  Interface:
 149  *
 150  *      IRMAAuthenticatorRequest
 151  *
 152  *  Purpose:
 153  *
 154  *      Request object for the Authenticator class.
 155  *
 156  *  IID_IRMAAuthenticatorRequest:
 157  *
 158  *      {00001802-0901-11d1-8B06-00A024406D59}
 159  *
 160  */
 161
 162 DEFINE_GUID(IID_IRMAAuthenticatorRequest, 0x00001802, 0x901, 0x11d1, 0x8b, 0x6, 0x0,
 163                         0xa0, 0x24, 0x40, 0x6d, 0x59);
 164
 165 #undef  INTERFACE
 166 #define INTERFACE IRMAAuthenticatorRequest
 167
 168 DECLARE_INTERFACE_(IRMAAuthenticatorRequest, IUnknown)
 169 {
 170     STDMETHOD(QueryInterface)           (THIS_
 171                                         REFIID riid,
 172                                         void** ppvObj) PURE;
 173
 174     STDMETHOD_(ULONG,AddRef)          (THIS) PURE;
 175
 176     STDMETHOD_(ULONG,Release)         (THIS) PURE;
 177
 178     /* GetAuthValues is called by the Authenticator object when it
 179      * needs to know the authorization info for this transaction.
 180      *
 181      * This object should call AuthValuesReady when ready.
 182      */
 183     STDMETHOD(GetAuthValues) (THIS_ IRMAValues* pOrigValues) PURE;
 184 };
 185
 186
 187 /****************************************************************************
 188  *
 189  *  Interface:
 190  *
 191  *      IRMAPassword
 192  *
 193  *  Purpose:
 194  *
 195  *      Provides a general password facility for storing of passwords in
 196  *      an encrypted form and a facility for verifying passwords securely
 197  *      over the network.
 198  *
 199  *  IID_IRMAPassword:
 200  *
 201  *      {00001700-0901-11d1-8B06-00A024406D59}
 202  *
 203  */
 204
 205 #define PN_AUTH_BASIC   1
 206 #define PN_AUTH_DIGEST  2
 207 #define PN_AUTH_RN5     3
 208 #define PN_AUTH_NTLM    4
 209
 210 DEFINE_GUID(IID_IRMAPassword, 0x00001700, 0x901, 0x11d1, 0x8b, 0x6, 0x0,
 211                         0xa0, 0x24, 0x40, 0x6d, 0x59);
 212
 213 #undef  INTERFACE
 214 #define INTERFACE IRMAPassword
 215
 216 DECLARE_INTERFACE_(IRMAPassword, IUnknown)
 217 {
 218     /*
 219      *  IUnknown methods
 220      */
 221     STDMETHOD(QueryInterface)           (THIS_
 222                                         REFIID riid,
 223                                         void** ppvObj) PURE;
 224
 225     STDMETHOD_(ULONG,AddRef)          (THIS) PURE;
 226
 227     STDMETHOD_(ULONG,Release)         (THIS) PURE;
 228
 229     /*
 230      *  IRMAPassword methods
 231      */
 232
 233     STDMETHOD(Crypt) (THIS_ IRMAValues* pAuthentication) PURE;
 234     STDMETHOD(Verify) (THIS_ IRMAValues* pAuth1, IRMAValues* pAuth2) PURE;
 235
 236     STDMETHOD(AsString) (THIS_ IRMAValues* pAuth, REF(IRMABuffer*) pBuffer) PURE;
 237     STDMETHOD(AsValues) (THIS_ const char* str, IRMAValues* pValues) PURE;
 238
 239     /*
 240      * CreateBuffer is provided for the convenince of external users,
 241      * who would otherwise have to get a context and common class factory
 242      * just to create IRMABuffers.  This method can be used instead, but
 243      * is not advisable if other means are available.
 244      */
 245     STDMETHOD(CreateBuffer) (THIS_ REF(IRMABuffer*) pBuffer) PURE;
 246
 247     /*
 248      * Ditto for CreateValues
 249      */
 250     STDMETHOD(CreateValues) (THIS_ REF(IRMAValues*) pValues) PURE;
 251 };
 252
 253
 254 /****************************************************************************
 255  *
 256  *  Interface:
 257  *
 258  *      IRMAAuthenticationManager
 259  *
 260  *  Purpose:
 261  *
 262  *      Provide a means of authenticating users.
 263  *
 264  *  IID_IRMAAuthenticator:
 265  *
 266  *      {00001a00-0901-11d1-8B06-00A024406D59}
 267  *
 268  */
 269
 270 DEFINE_GUID(IID_IRMAAuthenticationManager, 0x00001a00, 0x901, 0x11d1,
 271             0x8b, 0x6, 0x0, 0xa0, 0x24, 0x40, 0x6d, 0x59);
 272
 273 #undef  INTERFACE
 274 #define INTERFACE IRMAAuthenticationManager
 275
 276 DECLARE_INTERFACE_(IRMAAuthenticationManager, IUnknown)
 277 {
 278     STDMETHOD(QueryInterface)           (THIS_
 279                                         REFIID riid,
 280                                         void** ppvObj) PURE;
 281     STDMETHOD_(ULONG,AddRef)          (THIS) PURE;
 282     STDMETHOD_(ULONG,Release)         (THIS) PURE;
 283
 284     /* HandleAuthenticationRequest is called when the core wants us to get
 285      * a username and password.
 286      */
 287     STDMETHOD(HandleAuthenticationRequest) (
 288         THIS_ IRMAAuthenticationManagerResponse* pResponse) PURE;
 289 };
 290
 291
 292 /****************************************************************************
 293  *
 294  *  Interface:
 295  *
 296  *      IRMAAuthenticationManagerResponse
 297  *
 298  *  Purpose:
 299  *
 300  *      Response object for IRMAAuthenticationManager.
 301  *
 302  *  IID_IRMAAuthenticator:
 303  *
 304  *      {00001a01-0901-11d1-8B06-00A024406D59}
 305  *
 306  */
 307
 308 DEFINE_GUID(IID_IRMAAuthenticationManagerResponse, 0x00001a01, 0x901, 0x11d1,
 309             0x8b, 0x6, 0x0, 0xa0, 0x24, 0x40, 0x6d, 0x59);
 310
 311
 312 #undef  INTERFACE
 313 #define INTERFACE IRMAAuthenticationManagerResponse
 314
 315 DECLARE_INTERFACE_(IRMAAuthenticationManagerResponse, IUnknown)
 316 {
 317     STDMETHOD(QueryInterface)           (THIS_
 318                                         REFIID riid,
 319                                         void** ppvObj) PURE;
 320     STDMETHOD_(ULONG,AddRef)          (THIS) PURE;
 321     STDMETHOD_(ULONG,Release)         (THIS) PURE;
 322
 323     /* HandleAuthenticationRequest is called when the core wants us to get
 324      * a username and password.
 325      */
 326     STDMETHOD(AuthenticationRequestDone) (THIS_
 327                                           PN_RESULT result,
 328                                           const char* pUserName,
 329                                           const char* pPassword) PURE;
 330 };
 331
 332 #ifdef _MACINTOSH
 333 #pragma export on
 334 #endif
 335
 336 STDAPI CreatePassword(IUnknown** /* OUT */ ppIUnknown);
 337
 338 #ifdef _MACINTOSH
 339 #pragma export off
 340 #endif
 341
 342 #endif /* _RMAAUTH_H_ */