home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Windows Gam…ming Gurus (2nd Edition) / Disc2.iso / vc98 / include / raseapif.h < prev    next >
C/C++ Source or Header  |  1998-04-25  |  14KB  |  409 lines
  1. /********************************************************************/
  2. /**               Copyright(c) 1989 Microsoft Corporation.           **/
  3. /********************************************************************/
  4.  
  5. //***
  6. //
  7. // Filename:    raseapif.h
  8. //
  9. // Description: Defines interface between a third party authentication module
  10. //              and the Remote Access Service PPP engine.
  11. //
  12.  
  13. #ifndef _RASEAPIF_
  14. #define _RASEAPIF_
  15.  
  16. #include <lmcons.h>     // For UNLEN definition
  17.  
  18. //
  19. // Defines used for installtion of EAP DLL
  20. //
  21. // Custom EAP DLL (ex. Name=Sample.dll, Type=40) regsitry installation
  22. //
  23. // HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Rasman\PPP\EAP\40)
  24. //      Path                (REG_EXPAND_SZ) %SystemRoot%\system32\sample.dll  
  25. //      FriendlyName        (REG_SZ) Sample EAP Protocol
  26. //      ConfigUIPath        (REG_EXPAND_SZ) %SystemRoot%\system32\sample.dll  
  27. //      InteractiveUIPath   (REG_EXPAND_SZ) %SystemRoot%\system32\sample.dll  
  28. //      RequireConfigUI     (REG_DWORD) 1
  29. //
  30. //
  31.  
  32. #define RAS_EAP_REGISTRY_LOCATION   \
  33.     TEXT("System\\CurrentControlSet\\Services\\Rasman\\PPP\\EAP")
  34.  
  35. #define RAS_EAP_VALUENAME_PATH              TEXT("Path")   
  36. #define RAS_EAP_VALUENAME_CONFIGUI          TEXT("ConfigUIPath")
  37. #define RAS_EAP_VALUENAME_INTERACTIVEUI     TEXT("InteractiveUIPath")
  38. #define RAS_EAP_VALUENAME_FRIENDLY_NAME     TEXT("FriendlyName")
  39. #define RAS_EAP_VALUENAME_DEFAULT_DATA      TEXT("ConfigData")
  40. #define RAS_EAP_VALUENAME_DEFAULT_IDENTITY  TEXT("Identity")
  41. #define RAS_EAP_VALUENAME_REQUIRE_CONFIGUI  TEXT("RequireConfigUI")
  42. #define RAS_EAP_VALUENAME_INVOKE_STDUI   TEXT("InvokeStandardCredentialsDialog")
  43.  
  44. //
  45. // EAP packet codes from EAP spec.
  46. //
  47.  
  48. #define EAPCODE_Request         1
  49. #define EAPCODE_Response        2
  50. #define EAPCODE_Success         3
  51. #define EAPCODE_Failure         4
  52.  
  53. #define MAXEAPCODE              4
  54.  
  55. typedef struct _PPP_EAP_PACKET
  56. {
  57.     BYTE    Code;       // 1-Request, 2-Response, 3-Success, 4-Failure
  58.  
  59.     BYTE    Id;         // Id of this packet
  60.  
  61.     BYTE    Length[2];  // Length of this packet
  62.  
  63.     BYTE    Data[1];    // Data - First byte is Type for Request/Response
  64.  
  65. }PPP_EAP_PACKET, *PPPP_EAP_PACKET;
  66.  
  67. #define PPP_EAP_PACKET_HDR_LEN  ( sizeof( PPP_EAP_PACKET ) - 1 )
  68.  
  69. //
  70. // Interface structure between the engine and APs. This is passed to the
  71. // AP's via the RasCpBegin call. 
  72. //
  73.  
  74. typedef struct _PPP_EAP_INPUT
  75. {
  76.     //
  77.     // Size of this structure
  78.     //
  79.  
  80.     DWORD       dwSizeInBytes;  
  81.  
  82.     //
  83.     // The follwing four fields are valid only in RasEapBegin call
  84.     //
  85.  
  86.     HANDLE      hPort;          // Used to pass to back-end authenticator
  87.  
  88.     BOOL         fAuthenticator;    // Act as authenticator or authenticatee
  89.  
  90.     CHAR *      pszIdentity;    // Users's identity
  91.  
  92.     CHAR *      pszPassword;    // Client's account password.
  93.  
  94.     //
  95.     // Set of attributes for the currently dialed in user, set only on
  96.     // RasEapBegin call for the authenticator side. 
  97.     // Identifies the port used, NAS IP Address etc. May be used to send to
  98.     // the authentication provider, if this protocol is using one.
  99.     //
  100.  
  101.     RAS_AUTH_ATTRIBUTE * pUserAttributes;
  102.  
  103.     //
  104.     // The following fields are used only if the EAP DLL is using the 
  105.     // currently configured authentication provider ex: RADIUS or Windows NT 
  106.     // domain authentication, and the fAuthenticator field above is set to 
  107.     // TRUE.
  108.     //
  109.  
  110.     //
  111.     // This call should be used to make use of the installed back-end
  112.     // authenticator. It is upto the EAP DLL to free the pInAttributes
  113.     // memory. The pInAttributes structure may be freed soon after the
  114.     // call since a copy of this is made.
  115.     //
  116.  
  117.     DWORD  (APIENTRY *RasAuthenticateClient)(
  118.                                 IN  HANDLE                  hPort,
  119.                                 IN  RAS_AUTH_ATTRIBUTE *    pInAttributes );
  120.  
  121.     //
  122.     // Indicates that the authenticator has completed the previous call to
  123.     // RasAuthenticateClient. Ignore this field if an authentication provider
  124.     // is not being used.
  125.     //
  126.  
  127.     BOOL                fAuthenticationComplete;    
  128.  
  129.     //
  130.     // Used to indicate an error that did not allow the authentication process
  131.     // to complete successfully. NO_ERROR means the dwAuthResultCode field 
  132.     // below is valid. This field is valid only when the field above is TRUE.
  133.     //
  134.  
  135.     DWORD               dwAuthError;
  136.  
  137.     //
  138.     // Result of the authentication process by the authentication provider. 
  139.     // NO_ERROR indicates success, 
  140.     // otherwise is a value from winerror.h, raserror.h or mprerror.h 
  141.     // indicating failure reason. Valid only when the field above is NO_ERROR.
  142.     //
  143.  
  144.     DWORD               dwAuthResultCode;  
  145.  
  146.     //
  147.     // When the fAuthenticationComplete flag is TRUE this will point to 
  148.     // attributes returned by the authentication provider, if the 
  149.     // authentication was successful. ie. dwAuthResultCode and dwAuthError are 
  150.     // both NO_ERROR. This memory is not owned by the EAP DLL and it should 
  151.     // only used for read.
  152.     //
  153.  
  154.     OPTIONAL RAS_AUTH_ATTRIBUTE * pAttributesFromAuthenticator;
  155.  
  156.     //
  157.     // Valid only on the authenticatee side. This may be used on the 
  158.     // authenticatee side to impersonate the user being authenticated.
  159.     //
  160.  
  161.     HANDLE              hTokenImpersonateUser;
  162.  
  163.     //
  164.     // This variable should be examined only by the authenticatee side.
  165.     // The EAP specification states that the success packet may be lost and 
  166.     // since it is a non-acknowledged packet, reception of an NCP packet should
  167.     // be interpreted as a success packet. This varable is set to TRUE in this
  168.     // case only on the authenticatee side
  169.     //
  170.  
  171.     DWORD               fSuccessPacketReceived;
  172.  
  173.     //
  174.     // Will be set to TRUE only when the user dismissed the interactive
  175.     // UI that was invoked by the EAP dll
  176.     //
  177.  
  178.     DWORD               fDataReceivedFromInteractiveUI;
  179.  
  180.     //
  181.     // Data received from the Interactive UI. Will be set to non-NULL when
  182.     // fDataFromInteractiveUI is set to TRUE and the RasEapInvokeInteractiveUI
  183.     // returned non-NULL data. This buffer will be freed by the PPP engine
  184.     // on return from the RasEapMakeMessage call. A copy of this data should
  185.     // be made in the EAP Dll's memory space.
  186.     //
  187.  
  188.     OPTIONAL PBYTE      pDataFromInteractiveUI;
  189.  
  190.     //
  191.     // Size in bytes of data pointed to by pDataFromInteractiveUI. This may
  192.     // be 0 if there was no data passed back by the RasEapInvokeInteractiveUI
  193.     // call.
  194.     //
  195.  
  196.     DWORD               dwSizeOfDataFromInteractiveUI;
  197.  
  198.     //
  199.     // Data received from the Config UI. Will be set to non-NULL when
  200.     // fDataFromConfigUI is set to TRUE and the RasEapInvokeConfigUI
  201.     // returned non-NULL data. This buffer will be freed by the PPP engine
  202.     // on return from the RasEapMakeMessage call. A copy of this data should
  203.     // be made in the EAP Dll's memory space.
  204.     //
  205.  
  206.     OPTIONAL PBYTE      pDataFromConfigUI;
  207.  
  208.     //
  209.     // Size in bytes of data pointed to by pDataFromConfigUI. This may
  210.     // be 0 if there was no data passed back by the RasEapInvokeConfigUI
  211.     // call.
  212.     //
  213.  
  214.     DWORD               dwSizeOfDataFromConfigUI;
  215.  
  216. }PPP_EAP_INPUT, *PPPP_EAP_INPUT;
  217.  
  218. typedef enum _PPP_EAP_ACTION
  219. {
  220.     //
  221.     // These actions are provided by the EAP DLL as output from the
  222.     // RasEapMakeMessage API.  They tell the PPP engine what action (if any) to
  223.     // take on the EAP DLL's behalf, and eventually inform the engine that the 
  224.     // EAP DLL has finished authentication.
  225.     //
  226.  
  227.     EAPACTION_NoAction,     // Be passive, i.e. listen without timeout (default)
  228.     EAPACTION_Done,         // End auth session, dwAuthResultCode is set 
  229.     EAPACTION_SendAndDone,  // As above but send message without timeout first
  230.     EAPACTION_Send,         // Send message, don't timeout waiting for reply
  231.     EAPACTION_SendWithTimeout, // Send message, timeout if reply not received
  232.     EAPACTION_SendWithTimeoutInteractive // As above, but don't increment 
  233.                                          // retry count
  234.  
  235. }PPP_EAP_ACTION;
  236.  
  237. typedef struct _PPP_EAP_OUTPUT
  238. {
  239.     //
  240.     // Size of this structure
  241.     //
  242.  
  243.     DWORD                   dwSizeInBytes;  
  244.  
  245.     //
  246.     // Action that the PPP engine should take
  247.     //
  248.  
  249.     PPP_EAP_ACTION          Action;
  250.  
  251.     //
  252.     // MUST be set only if Action is EAPCTION_SendWithTimeout or
  253.     // EAPACTION_SendWithTimeoutInteractive. This value indicates to PPP engine
  254.     // to drop any responses with IDs that do not match this one.
  255.     //
  256.  
  257.     DWORD                   dwIdExpected;
  258.  
  259.     //
  260.     // dwAuthResultCode is valid only with an Action code of Done or 
  261.     // SendAndDone. Zero value indicates succesful authentication.  
  262.     // Non-zero indicates unsuccessful authentication with the value 
  263.     // indicating the reason for authentication failure.
  264.     // Non-zero return codes should be only from winerror.h, raserror.h and 
  265.     // mprerror.h
  266.     //
  267.  
  268.     DWORD                    dwAuthResultCode;
  269.  
  270.     //
  271.     // Must be set on the Authenticator side when Action is EAPACTION_Done or
  272.     // EAPACTION_SendAndDone. 
  273.     //
  274.  
  275.     CHAR                    szIdentity[UNLEN+1];
  276.  
  277.     //
  278.     // Non-NULL if there are any user attributes for this user. This is 
  279.     // allocated by the EAP DLL only if it is not using the currently configured
  280.     // authentication provider. It is upto the EAP DLL to free this memory in
  281.     // RasEapEnd call. Should only be set on the Authenticator side when 
  282.     // Action is EAPACTION_Done or EAPACTION_SendAndDone and if 
  283.     // dwAuthResultCode is 0. 
  284.     //
  285.  
  286.     OPTIONAL RAS_AUTH_ATTRIBUTE * pAuthenticatedUserAttributes;   
  287.  
  288.     //
  289.     // Flag set to true will cause the RasEapInvokeInteractiveUI call to be
  290.     // made.
  291.     //
  292.  
  293.     BOOL                    fInvokeInteractiveUI;
  294.  
  295.     //
  296.     // Pointer to context data, if any, to be sent to the UI. The EAP dll
  297.     // is responsible for freeing this buffer in the RasEapEnd call or when
  298.     // a response from the user for this invocation is obtained. 
  299.     //
  300.  
  301.     OPTIONAL PBYTE          pUIContextData;
  302.  
  303.     //
  304.     // Size in bytes of the data pointed to by pUIContextData. Ignored if 
  305.     // pUIContextData is NULL
  306.     //
  307.  
  308.     DWORD                   dwSizeOfUIContextData;
  309.     
  310.  
  311. }PPP_EAP_OUTPUT, *PPPP_EAP_OUTPUT;
  312.  
  313. typedef struct _PPP_EAP_INFO
  314. {
  315.     //
  316.     // Size of this structure
  317.     //
  318.  
  319.     DWORD   dwSizeInBytes;  
  320.  
  321.     DWORD   dwEapTypeId;
  322.  
  323.     //
  324.     // Called to get a context buffer for this EAP session and pass 
  325.     // initialization  information. This will be called before any other 
  326.     // call is made. Must return errorcodes only from winerror.h, raserror.h or
  327.     // mprerror.h
  328.     //
  329.  
  330.     DWORD   (APIENTRY *RasEapBegin)( OUT VOID **             ppWorkBuffer,
  331.                                      IN  PPP_EAP_INPUT *     pPppEapInput );
  332.  
  333.     //
  334.     // Called to free the context buffer for this EAP session. 
  335.     // Called after this session is completed successfully or not.
  336.     // Must return errorcodes only from winerror.h, raserror.h or mprerror.h
  337.     //
  338.  
  339.     DWORD   (APIENTRY *RasEapEnd)(   IN  VOID *     pWorkBuffer );
  340.  
  341.     //
  342.     // Called to process an incomming packet and/or send a packet.
  343.     // cbSendPacket is the size in bytes of the buffer pointed to by 
  344.     // pSendPacket. Must return errorcodes only from winerror.h, raserror.h or
  345.     // mprerror.h. Error return code indicates an error occurance during the
  346.     // authentication process.
  347.     //
  348.  
  349.     DWORD   (APIENTRY *RasEapMakeMessage)(
  350.                             IN  VOID*               pWorkBuf,
  351.                             IN  PPP_EAP_PACKET*     pReceivePacket,
  352.                             OUT PPP_EAP_PACKET*     pSendPacket,
  353.                             IN  DWORD               cbSendPacket,
  354.                             OUT PPP_EAP_OUTPUT*     pEapOutput,
  355.                             IN  PPP_EAP_INPUT*      pEapInput );
  356.  
  357. }PPP_EAP_INFO, *PPPP_EAP_INFO;
  358.  
  359. //
  360. // RasEapGetInfo should be exported by the 3rd party EAP dll installed in the
  361. // registry via the Path value.
  362. //
  363.  
  364. DWORD APIENTRY
  365. RasEapGetInfo(
  366.     IN  DWORD           dwEapTypeId,
  367.     OUT PPP_EAP_INFO*   pEapInfo
  368. );
  369.  
  370. //
  371. // RasEapInvokeInteractiveUI and RasEapFreeUserData should be exported by the 
  372. // 3rd party EAP dll installed in the registry via the InterfactiveUI value.
  373. //
  374.  
  375. DWORD APIENTRY 
  376. RasEapInvokeInteractiveUI(
  377.     IN  HWND            hwndParent,
  378.     IN  PBYTE           pUIContextData,
  379.     IN  DWORD           dwSizeofUIContextData,
  380.     OUT PBYTE *         ppUserData              OPTIONAL,
  381.     OUT DWORD *         lpdwSizeOfUserData
  382. );
  383.  
  384. DWORD APIENTRY 
  385. RasEapFreeUserData(
  386.     IN  PBYTE           pUserData
  387. );
  388.  
  389. //
  390. // RasEapInvokeConfigUI and RasEapFreeConfigData should be exported by the 
  391. // 3rd party EAP dll installed in the registry via the ConfigUI value.
  392. //
  393.  
  394. DWORD APIENTRY 
  395. RasEapInvokeConfigUI(
  396.     IN  HWND            hwndParent,
  397.     OUT BYTE *          pConfigData,
  398.     OUT DWORD *         lpdwSizeOfConfigData,
  399.     OUT BOOL  *         fInvokeStandardCredentialsDialog,
  400.     OUT LPSTR           szIdentity              OPTIONAL    
  401. );
  402.  
  403. DWORD APIENTRY 
  404. RasEapFreeConfigData(
  405.     IN  PBYTE           pConfigData
  406. );
  407.  
  408. #endif
  409.