RasSetCredentialsA function (ras.h)

Article
02/09/2023

The RasSetCredentials function sets the user credentials associated with a specified RAS phone-book entry.

Syntax

DWORD RasSetCredentialsA(
  [in] LPCSTR            unnamedParam1,
  [in] LPCSTR            unnamedParam2,
  [in] LPRASCREDENTIALSA unnamedParam3,
  [in] BOOL              unnamedParam4
);

Parameters

[in] unnamedParam1

A pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.

[in] unnamedParam2

A pointer to a null-terminated string that specifies the name of a phone-book entry.

[in] unnamedParam3

A pointer to a RASCREDENTIALS structure that specifies the user credentials to set for the specified phone-book entry. Before calling RasSetCredentials, set the dwSize member of the structure to sizeof(RASCREDENTIALS) and set the dwMask member to indicate the credential information to be set.

[in] unnamedParam4

A value that specifies whether RasSetCredentials clears existing credentials by setting them to the empty string, "". If this flag is TRUE, the dwMask member of the RASCREDENTIALS structure indicates which credentials that the function sets to the empty string. If this flag is FALSE, the function sets the indicated credentials according to the contents of their corresponding RASCREDENTIALS members.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is one of the following error codes or a value from Routing and Remote Access Error Codes or WinError.h.

Value	Meaning
ERROR_CANNOT_OPEN_PHONEBOOK	The specified phone book cannot be found.
ERROR_INVALID_PARAMETER	The lpCredentials parameter was NULL, or the specified entry does not exist in the phone book.
ERROR_ACCESS_DENIED	One of the following conditions occurred: The calling application attempted to set default credentials for a per-user connection. Default credentials can be set only for an all-user connection. The user does not have the correct privileges to set pre-shared keys or credentials for all users in case of all-user connectoids. Only administrators can complete these tasks.

Remarks

The RasSetCredentials function sets the user credentials associated with a specified RAS phone-book entry. The credentials stored with a phone-book entry are the credentials of the last user to successfully connect by using the specified phone-book entry, or the credentials subsequently specified in a call to the RasSetCredentials or RasSetEntryDialParams function for the phone-book entry.

The RasSetCredentials function is the preferred way of securely storing credentials with a phone-book entry. RasSetCredentials supersedes the RasSetEntryDialParams function, which may not be supported in future releases of the Windows operating system.

A password handle is "****************" (16 asterisks). If you call RasGetCredentials and receive 16 *s back in the password field, you have a stored password and, for security reasons, it will not be given back to you in plain text. If the szPassword member of the RASCREDENTIALS structure contains the password handle (16 *s) returned by RasGetCredentials or RasGetEntryDialParams, the next call to RasSetCredentials will not change the saved password.

To set the default credentials for an all-user connection, set the RASCM_DefaultCreds flag in the dwMask member of the RASCREDENTIALS structure pointed to by the lpCredentials parameter. If you attempt to set default credentials for a per-user connection, RasSetCredentials returns ERROR_ACCESS_DENIED.

When setting credentials for an all-users connection, if the calling application specifies a non-NULL value for the phone-book parameter, lpszPhonebook, the phone-book file must be located in the phone-book directory beneath the all-users application data path. To obtain the correct location for the phone-book file, first call SHGetFolderPath with a CSIDL value of CSIDL_COMMON_APPDATA. SHGetFolderPath returns the all-users application data path. Append the following string to this path:

Microsoft\Network\Connections\Pbk

The combined path is the correct location for the phone-book file.

Note Specifying a non-NULL value for the lpszPhonebook parameter may not be supported in later versions of the Windows operating system.

To set a pre-shared key, use the RASCM_PreSharedKey flag in the RASCREDENTIALS.dwMask field.

Note

The ras.h header defines RasSetCredentials as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

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	ras.h
Library	Rasapi32.lib
DLL	Rasapi32.dll