RasSecurityDialogBegin function (rasshost.h)

Article
10/13/2021

The RasSecurityDialogBegin function is a third-party RAS security DLL entry point that the RAS server calls when a remote user tries to connect. This enables the security DLL to begin its authentication of the remote user.

Note Windows Server 2008, Windows Server 2003, Windows 2000 Server, and Windows NT Server 4.0 currently provide RAS security host support for serial devices only. Other types of connections, such as Integrated Services Digital Network (ISDN) or virtual private network (VPN) connections, are not supported.

Syntax

DWORD RasSecurityDialogBegin(
  [in] HPORT                        hPort,
  [in] PBYTE                        pSendBuf,
  [in] DWORD                        SendBufSize,
  [in] PBYTE                        pRecvBuf,
  [in] DWORD                        RecvBufSize,
       VOID(* )(SECURITY_MESSAGE *) RasSecurityDialogComplete
);

Parameters

[in] hPort

Specifies a RAS port handle. The security DLL uses this handle in other RAS security functions, such as RasSecurityDialogSend and RasSecurityDialogReceive, to identify this authentication transaction.

Note that this handle is valid only in RAS security functions; do not use it in other I/O functions.

[in] pSendBuf

Pointer to a buffer allocated by the RAS server. The security DLL uses this buffer with the RasSecurityDialogSend function to send text that is displayed in the RAS terminal window on the remote computer.

[in] SendBufSize

Specifies the size, in bytes, of the pSendBuf buffer.

[in] pRecvBuf

Pointer to a buffer allocated by the RAS server. The security DLL uses this buffer with the RasSecurityDialogReceive function to receive the response from the remote user.

[in] RecvBufSize

Specifies the size, in bytes, of the pRecvBuf buffer.

RasSecurityDialogComplete

Return value

If the security DLL successfully starts the authentication operation, RasSecurityDialogBegin should return NO_ERROR. In this case, the security DLL must later terminate the authentication transaction by calling the function pointed to by the RasSecurityDialogComplete parameter.

If an error occurs, RasSecurityDialogBegin should return a nonzero error code. In this case, the RAS server hangs up the call and records the error in the event log. Returning a nonzero error code terminates the authentication transaction, so the security DLL does not need to call the RasSecurityDialogComplete function.

Remarks

When a RAS server receives a call from a remote computer, it calls the RasSecurityDialogBegin function exported by the registered RAS security DLL, if there is one. When the RAS server calls this function, it passes the following information to the security DLL:

A port handle to identify the connection
Pointers to buffers to use when communicating with the remote user
A pointer to the RasSecurityDialogComplete function to call when the authentication has been completed

The port handle and buffer pointers are valid until RasSecurityDialogComplete is called to terminate the authentication transaction.

The RasSecurityDialogBegin implementation must return as soon as possible, because the RAS server is blocked and cannot accept any other calls until RasSecurityDialogBegin returns. The RasSecurityDialogBegin function should copy the input parameters and create a thread to communicate with and authenticate the remote user.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	rasshost.h