home *** CD-ROM | disk | FTP | other *** search
/ Tools / WinSN5.0Ver.iso / NETSCAP.50 / WIN1998.ZIP / ns / cmd / winfe / daintf.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-04-08  |  14.0 KB  |  408 lines
  1. /* ****************************************************************************
  2.  *  
  3.  *  Copyright (c) 1995-1996 by CompuServe Incorporated, Columbus, Ohio
  4.  *  All Rights Reserved
  5.  *
  6.  *  Facility:   CompuServe Distributed Authentication(DA) Facility
  7.  *
  8.  *  Abstract
  9.  *      This facility provides a means for authentication of users and services 
  10.  *      without compromising passphrases between them across the wire.
  11.  *
  12.  *  Module
  13.  *      This module defines the interfaces necessary for the DA process.
  14.  *
  15.  *  Author
  16.  *      Chris Fortier
  17.  *
  18.  *  Notes
  19.  *      DA is implemented as an in-process OLE server.  To access the DA 
  20.  *      OLE server, the IDAProcess interface on an instance of the CLSID_DA 
  21.  *      object must be used.  Using IDAProcess requires the client to implement 
  22.  *      the IDAPacket and optionally the IDAPassword interfaces.  These 
  23.  *      interfaces are described below.  
  24.  *
  25.  *      The DA OLE server is self-registering, so be sure to (un)register the 
  26.  *      DA OLE server by using REGSVR32.EXE, or by accessing the exported 
  27.  *      (DllUnregisterServer)DllRegisterServer functions.
  28.  *
  29.  */
  30.  
  31.  
  32. #if !defined(__DAINTF_H__)
  33. #define __DAINTF_H__
  34.  
  35.  
  36. /* ****************************************************************************
  37.  *  
  38.  *  Name
  39.  *      IDAPacket
  40.  *
  41.  *  Purpose
  42.  *      This interface must be implemented by clients who wish to access DA 
  43.  *      services.  The interface is used to encapsulate a request or response 
  44.  *      during the DA process.
  45.  *
  46.  *  Notes
  47.  *      The implemented form of a packet could be an HTTP header.  As the 
  48.  *      header representation varies (buffer, tree, etc.), an encapsulation is 
  49.  *      necessary.  Terminology is as follows:
  50.  *
  51.  *          Term                    Example
  52.  *
  53.  *          Name                    Authorization:
  54.  *          Value                   Remote-Passphrase
  55.  *          SubName="SubValue"      Realm="foo"
  56.  *
  57.  */
  58. #undef  INTERFACE
  59. #define INTERFACE   IDAPacket
  60.  
  61. DECLARE_INTERFACE_(IDAPacket, IUnknown)
  62. {
  63.     /* ************************************************************************
  64.      *
  65.      *  HRESULT IDAPacket::AddNameValue
  66.      *  (
  67.      *      [IN]    const TCHAR *pszName,
  68.      *      [IN]    const TCHAR *pszValue
  69.      *  )
  70.      *
  71.      *  This method adds a new name and value to the DA packet.
  72.      *
  73.      *  Parameters
  74.      *      pszName     - Name to add.
  75.      *      pszValue    - Value to add.
  76.      *
  77.      *  Return
  78.      *      NOERROR     - The name and value were added.
  79.      *      E_FAIL      - The name and value could not be added.
  80.      *
  81.      */
  82.     STDMETHOD(AddNameValue)(THIS_
  83.                             const TCHAR *pszName, 
  84.                             const TCHAR *pszValue)          PURE;
  85.  
  86.     /* ************************************************************************
  87.      *
  88.      *  HRESULT IDAPacket::FindValue
  89.      *  (
  90.      *      [IN]            const TCHAR *pszName,
  91.      *      [IN]            const TCHAR *pszSubName,
  92.      *      [OUT OPTIONAL]  const TCHAR *pszSubValue,
  93.      *      [IN]            DWORD        cbSubValue
  94.      *  )
  95.      *
  96.      *  This method finds a value or subvalue given a packet header name and 
  97.      *  subname.
  98.      *
  99.      *  Parameters
  100.      *      pszName     - Name of the header within which to search
  101.      *      pszSubName  - Subname to search for.
  102.      *      pszValue    - Points to a buffer for the returned (sub)value.
  103.      *      cbSubValue  - Size of the the return (sub)value buffer.
  104.      *
  105.      *  Return
  106.      *      NOERROR     - The (sub)name was found.
  107.      *      E_FAIL      - The (sub)name could not be found.
  108.      *
  109.      */
  110.     STDMETHOD(FindValue)(THIS_ 
  111.                          const TCHAR *pszName,
  112.                          const TCHAR *pszSubName,
  113.                          TCHAR *      pszValue,
  114.                          DWORD        cbValue)          const   PURE;
  115.  
  116.     /* ************************************************************************
  117.      *
  118.      *  HRESULT IDAPacket::ReplaceNameValue
  119.      *  (
  120.      *      [IN]    const TCHAR *pszName,
  121.      *      [IN]    const TCHAR *pszValue
  122.      *  )
  123.      *
  124.      *  This method replaces an existing name and value in a DA packet.
  125.      *
  126.      *  Parameters
  127.      *      pszName     - Name to append.
  128.      *      pszValue    - Value to append.
  129.      *
  130.      *  Return
  131.      *      NOERROR     - The name and value were updated.
  132.      *      E_FAIL      - The name and value could not be updated.
  133.      *
  134.      *  Notes
  135.      *      The pszValue string may itself be composed of many subnames and 
  136.      *      subvalues.
  137.      *
  138.      */
  139.     STDMETHOD(ReplaceNameValue)(THIS_
  140.                                 const TCHAR *pszName, 
  141.                                 const TCHAR *pszValue)          PURE;
  142. };
  143.  
  144.  
  145. /* ****************************************************************************
  146.  *  
  147.  *  Name
  148.  *      IDAPassword
  149.  *
  150.  *  Purpose
  151.  *      This interface might be implemented by clients who wish to access DA 
  152.  *      services.  The interface is used to perform transformations of passwords 
  153.  *      from text to 128 bit values.
  154.  *
  155.  *  Notes
  156.  *      It is an optional interface.  Not implementing the interface causes 
  157.  *      authentications to fail if a user chooses a service with any password 
  158.  *      transformation parameters.
  159.  *
  160.  */
  161. #undef  INTERFACE
  162. #define INTERFACE   IDAPassword
  163.  
  164. DECLARE_INTERFACE_(IDAPassword, IUnknown)
  165. {
  166.     /* ************************************************************************
  167.      *
  168.      *  HRESULT IDAProcess::Transform
  169.      *  (
  170.      *      [IN]    const TCHAR *   pszPassword,
  171.      *      [IN]    const TCHAR *   pszCharSet, 
  172.      *      [IN]    const TCHAR *   pszConvCase,
  173.      *      [IN]    const TCHAR *   pszHashFunc,
  174.      *      [OUT]   BYTE *          pbPasswordXfrm
  175.      *  )
  176.      *
  177.      *  This method transforms a password from text to a 128 bit value.
  178.      *
  179.      *  Parameters
  180.      *      pszPassword     - Password as entered by the user.
  181.      *      pszCharSet      - Service transformation character set.
  182.      *      pszConvCase     - Service transformation case conversion.
  183.      *      pszHashFunc     - Service transformation hash function.
  184.      *      pbPasswordXfrm  - Pointer to 128 bits for the password 
  185.      *                        transformation.
  186.      *
  187.      *  Return
  188.      *      NOERROR - Password was successfully transformed to a 128 bit value.
  189.      *      E_FAIL  - Unable to transform the password.
  190.      *
  191.      *  Notes
  192.      *      If pszCharSet is "none", pszConvCase and pszHashFunc will be empty 
  193.      *      strings.
  194.      *
  195.      */
  196.     STDMETHOD(Transform)(const TCHAR *  pszPassword,
  197.                          const TCHAR *  pszCharSet, 
  198.                          const TCHAR *  pszConvCase,
  199.                          const TCHAR *  pszHashFunc,
  200.                          BYTE *         pbPasswdXfrm)   const   PURE;
  201. };
  202.  
  203.  
  204. /* ****************************************************************************
  205.  *
  206.  *  Name
  207.  *      SDAAuthData
  208.  *
  209.  *  Purpose
  210.  *      Used to package the needed parameters for IDAProcess::OnAuthorize.
  211.  *
  212.  */
  213. struct  SDAAuthData
  214. {
  215.     const IDAPacket *   pIDAPacketIn;   // [IN]             Server response DA packet.
  216.     const TCHAR *       pszHost;        // [IN]             Host for the outgoing DA packet.
  217.     const TCHAR *       pszURI;         // [IN]             URI for the outgoing DA packet.
  218.     const TCHAR *       pszMethod;      // [IN]             Method for the outgoing DA packet.
  219.     IDAPacket *         pIDAPacketOut;  // [IN OUT]         New request DA packet.
  220.     BOOL                bShowDialog;    // [IN]             Display authentication dialog?
  221.     HWND                hParent;        // [IN OPTIONAL]    Parent for authentication dialog.
  222.     TCHAR *             pszUsername;    // [IN OUT]         User name.
  223.     WORD                wMaxUsername;   // [IN]             Maximum user name length.
  224.     TCHAR *             pszRealmname;   // [IN OUT]         Realm name.
  225.     TCHAR *             pszPassword;    // [IN OUT]         Password.
  226.     WORD                wMaxPassword;   // [IN]             Maximum password length.
  227.     const IDAPassword * pIDAPassword;   // [IN OPTIONAL]    Password transformation interface.
  228. };
  229.  
  230.  
  231. #define DA_MAXFIELD 64  // Maximum string parameter length.
  232.  
  233.  
  234. /* ****************************************************************************
  235.  *
  236.  *  Name
  237.  *      IDAProcess
  238.  *
  239.  *  Purpose
  240.  *      This interface is implemented by the DA engine.  It is the interface 
  241.  *      clients use to access DA services.
  242.  *
  243.  */
  244. #undef  INTERFACE
  245. #define INTERFACE   IDAProcess
  246.  
  247. DECLARE_INTERFACE_(IDAProcess, IUnknown)
  248. {
  249.     /* ************************************************************************
  250.      *
  251.      *  HRESULT IDAProcess::Cheat
  252.      *  (
  253.      *      [IN]        const TCHAR *   pszHost,
  254.      *      [IN]        const TCHAR *   pszURI,
  255.      *      [IN]        const TCHAR *   pszMethod,
  256.      *      [IN OUT]    IDAPacket *     pIDAPacket
  257.      *  )
  258.      *
  259.      *  This method performs DA cheating.
  260.      *
  261.      *  Parameters
  262.      *      pszHost     - Name of the host to receive the outgoing request.
  263.      *      pszURI      - URI of the outgoing request.
  264.      *      pszMethod   - Method type of the outgoing request.
  265.      *      pIDAPacket  - DA packet representing an outgoing request.
  266.      *
  267.      *  Return
  268.      *      NOERROR         - An Authorization header was added to the 
  269.      *                        outgoing request DA packet.
  270.      *      S_FALSE         - Cheating failed, there is no DA cache 
  271.      *                        information for the host.
  272.      *      E_FAIL          - Outgoing request DA packet could not be 
  273.      *                        updated.
  274.      *      E_INVALIDARG    - A bad function parameter was passed, or the 
  275.      *                        DA packet is not in the correct format, or IP
  276.      *                        information could not be obtained for the 
  277.      *                        hostname.
  278.      *      E_UNEXPECTED    - Internal DA error.
  279.      *
  280.      */
  281.     STDMETHOD(Cheat)(THIS_ 
  282.                      const TCHAR *  pszHost, 
  283.                      const TCHAR *  pszURI,
  284.                      const TCHAR *  pszMethod,
  285.                      IDAPacket *    pIDAPacket)                 const   PURE;
  286.     
  287.     /* ************************************************************************
  288.      *
  289.      *  HRESULT IDAProcess::On401Authenticate
  290.      *  (
  291.      *      [IN OUT]    SDAAuthData *pDAAuthData
  292.      *  )
  293.      *
  294.      *  This method processes 401 WWW-Authenticate server response.
  295.      *
  296.      *  Parameters
  297.      *      pDAAuthData - Authorization parameters.
  298.      *
  299.      *  Return
  300.      *      NOERROR         - Successfully added an Authorization header to 
  301.      *                        the outgoing request DA packet.
  302.      *      E_FAIL          - The outgoing request DA packet could not be 
  303.      *                        updated or IP information could not be obtained 
  304.      *                        for the hostname.
  305.      *      E_INVALIDARG    - A bad function parameter was passed, or the 
  306.      *                        DA packet is not in the correct format, or IP
  307.      *                        information could not be obtained for the 
  308.      *                        hostname.
  309.      *      E_UNEXPECTED    - Internal DA error.
  310.      *
  311.      */
  312.     STDMETHOD(On401Authenticate)(THIS_
  313.                                  SDAAuthData *pDAAuthData)      const   PURE;
  314.  
  315.     /* ************************************************************************
  316.      *
  317.      *  HRESULT IDAProcess::OnAuthenticate
  318.      *  (
  319.      *      [IN]    const TCHAR *       pszHost,
  320.      *      [IN]    const IDAPacket *   pIDAPacket
  321.      *  )
  322.      *
  323.      *  This method processes 200 WWW-Authenticate server response.
  324.      *
  325.      *  Parameters
  326.      *      pszHost     - Name of the host to receive the outgoing request.
  327.      *      pIDAPacket  - DA packet representing a server response.
  328.      *
  329.      *  Return
  330.      *      NOERROR         - Successfully verified authentication.
  331.      *      E_FAIL          - Authentication verification failed.
  332.      *      E_INVALIDARG    - Bad function parameter was passed, or the DA
  333.      *                        packet is not in the correct format, or IP
  334.      *                        information could not be obtained for the 
  335.      *                        hostname.
  336.      *      E_UNEXPECTED    - Internal DA error.
  337.      *
  338.      */
  339.     STDMETHOD(On200Authenticate)(THIS_
  340.                                  const TCHAR *      pszHost, 
  341.                                  const IDAPacket *  pIDAPacket) const   PURE;
  342. };
  343.  
  344.  
  345. #endif  // __DAINTF_H__
  346.  
  347.  
  348. /* ****************************************************************************
  349.  *
  350.  *  GUIDs
  351.  *
  352.  */
  353. // CLSID for the DA object {BCBD97D1-5F68-11CF-8370-000000000000}.
  354. DEFINE_GUID(CLSID_DA, 
  355.             0xBCBD97D1, 
  356.             0x5F68, 
  357.             0x11CF, 
  358.             0x83, 
  359.             0x70, 
  360.             0x0, 
  361.             0x0, 
  362.             0x0, 
  363.             0x0, 
  364.             0x0, 
  365.             0x0);
  366.  
  367. // IID for the IDAPacket interface {BCBD97D2-5F68-11CF-8370-000000000000}.
  368. DEFINE_GUID(IID_IDAPacket, 
  369.             0xBCBD97D2, 
  370.             0x5F68, 
  371.             0x11CF, 
  372.             0x83, 
  373.             0x70, 
  374.             0x0, 
  375.             0x0, 
  376.             0x0, 
  377.             0x0, 
  378.             0x0, 
  379.             0x0);
  380.  
  381. // IID for the IDAPassword interface {BCBD97D3-5F68-11CF-8370-000000000000}.
  382. DEFINE_GUID(IID_IDAPassword,
  383.             0xBCBD97D3, 
  384.             0x5F68, 
  385.             0x11CF, 
  386.             0x83, 
  387.             0x70, 
  388.             0x0, 
  389.             0x0, 
  390.             0x0, 
  391.             0x0, 
  392.             0x0, 
  393.             0x0);
  394.  
  395. // IID for the IDAProcess interface {BCBD97D4-5F68-11CF-8370-000000000000}.
  396. DEFINE_GUID(IID_IDAProcess, 
  397.             0xBCBD97D4, 
  398.             0x5F68, 
  399.             0x11CF, 
  400.             0x83, 
  401.             0x70, 
  402.             0x0, 
  403.             0x0, 
  404.             0x0, 
  405.             0x0, 
  406.             0x0, 
  407.             0x0);
  408.