Internet Gateway Server

Design Specification
Revision 1.4
July 6, 2019

Microsoft Confidential 7/6/2019 7/6/20197/6/2019 1

1. OVERVIEW

2. INTERNET APIS

2.1 Locate Gateway Server

2.2 Internet Init APIs

2.2.1 OpenInternet
2.2.2 CloseInternet

3. GATEWAY SERVER

3.1 URL Caching

3.1.1 URL File Phase out
3.1.2 Cache Cleanup
3.1.3 Url Cache APIs
3.1.3.1 UrlCacheInit
3.1.3.2 CacheUrlFile
3.1.3.3 RetrieveUrlFile
3.1.3.4 UnlockUrlFile
3.1.3.5 CreateUrlFile
3.1.3.5 GetUrlInfo
3.1.3.5 SetUrlInfo
3.1.4 URL Files Cache Admin Management
3.1.5 URL Cache Management APIs

3.2 Gateway Service Management

3.2.1 User Access Control
3.2.1.1 GatewayAddUserAccess
3.2.1.2 GatewayDeleteUserAccess
3.2.1.3 GatewayEnumUserAccess
3.2.2 Server MIB
3.2.2.1 GatewayServerQueryMIBInfo
3.2.3 Server Audit Log
3.2.3.1 GatewaySetAuditLogConfigInfo
3.2.3.1 GatewayGetAuditLogConfigInfo
3.2.4 Server RPC Memory
3.2.4.1 GatewayFreeMemory

3.3 User Access Validation :

3.2.1 GatewayAccessValidate

4. REVISION HISTORY

Microsoft Confidential 7/6/2019 7/6/20197/6/2019 2

1. Overview
As the Internet usage becomes more popular, people expect to access the Internet information
from their desktop as easily as possible. Gateway server is aimed to easy this access in
corporate environment where the corporate network is isolated from Internet. Gateway server not
only provides the Internet information access, it also maintains a secure environment. As we all
know that we work in heterogeneous environment where we use different type of network
protocols for various reasons, but the Internet uses only TCP/IP protocol. In a way gateway
server acts as a transport protocol translator and provides access to Internet to desktop that
knows its native protocol such as IPX, NetBeui, etc.

Gateway server is a service that runs on Windows NT 3.5 server that has access to Internet and
to local “corporate” network. Clients requests and responses are transported across client
desktop and gateway server using RPC mechanism which provides transport transparency and
user level security. Gateway server processes the client requests by calling WIN32 Internet APIs.

In order to effectively use the available Internet resources and to enhance the client Internet
access performance, the gateway server caches the Internet information in its local storage so
that if any corporate client needs the information that is already in the cache, it will be fetched
from there and returned to client. This retrieval not only reduces the Internet traffic, also the
client gets back the information much quicker. Administrators have control over the cached
information such as disk usage, cached information Time-out and Refresh Interval.

Gateway server multiplexes the users requests and effectively uses the Internet resources, so
that a moderate sized corporation can provide Internet access to all its employees using few
gateway servers. These servers could be the same Internet servers (such as microsoft.com)
where the corporation places its public information for access to Internet users.

The layout of the Internet and Gateway service DLLs is given in the figure 1.

2. Internet APIs
WIN32 Internet APIs are set of APIs that provide ways for the Internet application writer to
access the Internet. These APIs are remotable to gateway servers or they can directly talk to
Internet. Also they encapsulate the protocol information to make the application writers life easy.
The application written using these APIs can talk to Internet either directly or through the
gateway server. APIs will determines the path automatically.

Microsoft Confidential 7/6/2019 7/6/20197/6/2019 3

Current plan is to include APIs to access Archie, FTP, Gopher, and WEB servers in
WININET.DLL

Wininet.dll

Thunk Layer

Worker
RPC Stub To Internet
Functions

Gateway Server

RPC STUB

Service Mangement APIs

Wininet.dll

Thunk Layer
Gateway Service
Admin Tool
Worker
RPC Stub Function
s

To Internet

Figure 1. Internet and Gateway DLLs layout.

2.1 Locate Gateway Server1

The client dll code locates the gateway server before it remotes the Internet APIs to the server. It
uses RPC locator service to find out the gateway server. When the gateway servers come up,
they register with the locator server with the machine name, the transports and the type Internet

1
This session will be modified soon.
Microsoft Confidential 7/6/2019 7/6/20197/6/2019 4
services they serve. When the client code decides to remote the Internet APIs, it talks to the
locator service to get the list of RPC gateway servers and selects the gateway server that
support the transport the client can talk to and the Internet services that the client wants.

2.2 Internet Init APIs

The application writers are given choice to pick the Internet APIs execution path, which means
that Internet APIs are executed on the local machine or remoted to the gateway server where the
Internet workers will be called. This path can also be pre-configured in the registry using network
control panel. When the application decides to select a path, it calls the Internet API
OpenInternet() with parameters that indicate local or gateway or pre-configured access and the
type of Internet services the application expects to use. This API returns an handle which can be
used later to open or access other Internet service APIs.

Data Definitions :

#define PRE_CONFIG_INTERNET_ACCESS 0x00000000

#define LOCAL_INTERNET_ACCESS 0x00000001
#define GATEWAY_INTERNET_ACCESS 0x00000002

#define INTERNET_SERVICE_READ 0x000000001

#define INTERNET_SERVICE_WRITE 0x000000002

typedef PVOID HINET;

2.2.1 OpenInternet
OpenInternet API opens the Internet dll and sets up the gateway session if the access is through
gateway server. It locates the gateway server with the required Internet services enabled. It
returns a handle which can be used to call other Internet service APIs. If the AccessMethod
specified is PER_CONFIG_INTERNET_ACCESS, the API reads registry for the default
configuration.

HINET
OpenInternet(
DWORD AccessMethod,
LPCTSTR GroupName
);

Parameters :

AccessMethod : Type of access method preferred. It should be one among the followings :
Microsoft Confidential 7/6/2019 7/6/20197/6/2019 5
 LOCAL_INTERNET_ACCESS
GATEWAY_INTERNET_ACCESS
PRE_CONFIG_INTERNET_ACCESS
GroupName : This is a reserved parameter. In future this parameter can be used to pick a
gateway server from selected group of servers.

Return Value :

If this function is successful, it returns a valid handle, otherwise it returns

INVALID_HANDLE_VALUE, in this case GetLastError() returns extended error
information.

Return Error Codes :

RPC_S_SERVER_UNAVAILABLE : If no matching RPC server is found.

2.2.2 CloseInternet
CloseInternet API call closes any pending RPC connection to Gateway server, frees up the
handle resources and invalidates the handle. The caller should not use the Internet handle after
this call returns.

BOOL
CloseInternet(
HINET InternetHandle,
);

Parameters :

InternetHandle : Handle value that is returned by the OpenInternet() call.

Return Value :

If this function is successful, it returns TRUE otherwise FALSE. GetLastError() function will
return extended error information.

Return Error Codes :

ERROR_INVALID_HANDLE : If the handle value passed in is invalid.

3. Gateway Server

Apart from serving the remote client calls, gateway server performs :

1. Caching of Internet URL files

Microsoft Confidential 7/6/2019 7/6/20197/6/2019 6

 2. User access control

3. Gateway MIB information gathering

4. Gateway Configuration

5. User Access Validation

3.1 URL Caching

Gateway server provides a set of APIs that can be called by the Internet API worker functions to
cache or retrieve URL (Uniform Resource Location) files. These APIs are packaged as DLL so
that other internet services can leverage the caching code. Gateway service initializes the URL
caching when it comes up and let the Internet APIs to cache URL files. Other internet
applications such as proxy server or a MSN service can also use URL caching, but they need to
initialize the URL caching before they start using it. All internet services should call the cache
clean up routine when they shut down.

The admin configures the cache storage, the storage can be spread at multiple locations either
on a same volume or across different volumes. The cache mangement system optimally uses
this store to cache different size of URLs. When the allocate storage becomes full, the system
will apply a complex score system to phase out previously cached files.

The cache mangement system updates the URL as required. The admin can configure cache
manager with URL update interval (ex. 24hrs) to control the freshness of the URLs. However
some WEB servers specify the expire date of the URL files, in such cases cache manger uses it.
Cache manager does not cache files that are changing frequently such as URL files with less
than 15mins freshness interval.

3.1.1 URL File Phase out

There are serveral factors that control the usage of the storage optimally. The cache manager
uses a score system to phase out URLs. The most impartant factors are

1. File Size of the URL

2. Last Access Time of the URL
3. Number of accesses since Last URL Update
4. Expire Time of the URL.

Each above factor is given a weighing, a score is computed for each of the above factors and all
scores are added to make phase out score. The URL with highest score will be phased out first.
An example of this score system is given in the following spread sheet.

Microsoft Confidential 7/6/2019 7/6/20197/6/2019 7

 Size Last Access Last Freshness Total
In MB AccessTime Freq. UpdateTime in Hrs Score1 Score2 Score3 Score4 Score

File1 20 4/1/95 20:00 3 4/7/95 11:50 24 4.00 20.00 6.00 20.00 50.00
File2 1 4/7/95 13:00 8 4/7/95 13:00 3 0.20 7.78 16.00 20.00 43.98
File3 100 4/4/95 17:00 2 4/1/95 10:00 4 20.00 20.00 4.00 20.00 64.00
File4 15 4/8/95 13:00 8 4/8/95 10:00 1 3.00 1.11 16.00 20.00 40.11
File5 0.5 4/8/95 1:00 5 4/8/95 1:00 24 0.10 4.44 10.00 13.33 27.88

CacheSize 200 in MB
Phaseout 3 in days
Frequency 10 times
TimeNow 4/8/95 17:00
Score1 Fac. 40 %
Score2 Fac. 20 %
Score3 Fac. 20 %
Score4 Fac. 20 %

3.1.2 Cache Cleanup

URL Cache manager cleans up the cache storage periodically to get rid of unused files and
makes room for the new URLs. Cache cleanup is also invoked whenever the cache storage is
full and cache space is required for the new URL. Admin can also flush the cache from admin
tool and also specify to flush the cache periodically or when the service is shut down.

3.1.3 Url Cache APIs

3.1.3.1 UrlCacheInit
URLCacheInit API initializes the cache manager and makes cache manager to accept other
APIs. Internet service that uses the URL caching should call this API during service startup.

DWORD
UrlCacheInit(
VOID
);

Parameters :

None.

Parameters :

Windows Error Codes.

Microsoft Confidential 7/6/2019 7/6/20197/6/2019 8

3.1.3.2 CacheUrlFile
CacheUrlFile API caches an specified URL in the gateway server cache storage. If the storage
is full then it invokes cache cleanup to make space for this new URL file. If the file size is bigger
than the cache size, the API returns ERROR_DISK_FULL. If the file is already in the cache, the
API overwrites it. URLCacheInit must have been called before calling this API, otherwise it will
return ERROR_SERVICE_NOT_ACTIVE.

DWORD
CacheUrlFile(
IN LPCSTR UrlName,
IN LPCWSTR LocalFileName,
LONGLONG ExpireTime
);

Parameters :

UrlName : Name of the file in URL format. This must be an unique name. The name string
should not contain any escape character.
LocalFileName : Name of the local file that is being cached. The file will be moved to the cache
storage if the stoage is in the same volume of the local file otherwise the file is copied to
the cache storage and then the local file is deleted.
Expire Time : Expire date and time (GMT) of the URL file that is being cached. If it is unknown
set it to zero.

Return Error Codes :

ERROR_FILE_NOT_FOUND : if the specified local file is not found.

ERROR_DISK_FULL : if the cache storage is full.
ERROR_SERVICE_NOT_ACTIVE : if this API is called without calling UrlCacheInit API.

3.1.3.3 RetrieveUrlFile
RetrieveUrlFile API retrieves an URL file from cache. If the file is not available in cache it
returns ERROR_FILE_NOT_FOUND, otherwise it returns the name of the local file. The caller is
given only read permission to the local file, so the caller should not attempt to write or delete the
file. The file is locked for the caller when it is retrieved, the caller should unlock the file after it
has been used up. Cache manager will automatically unlock the locked files after certain
interval. While the file is locked cache manager will not remove the file from cache.

DWORD
RetrieveUrlFile(

Microsoft Confidential 7/6/2019 7/6/20197/6/2019 9

 IN LPCSTR UrlName,
OUT LPWSTR LocalFileName
BOOL *IsExpired
);

Parameters:

UrlName : Name of the file in URL format. This must be an unique name.The name string should
not contain any escape characters.
LocalFileName : Pointer to a location where the name of the local file of the specified URL file is
returned.
IsExpired : pointer to a bool which will be set if the specified file is found and the file time has
expired. The caller can decide to retrieve this file from the internet server. Note: the file
is locked even if the time has expired, so the caller should unlock it before it updates the
file.

Return Error Codes :

ERROR_FILE_NOT_FOUND : if the specified URL is not found in the cache storage.

3.1.3.4 UnlockUrlFile

UnlockUrlFile API unlocks the cache file which was locked while the file was retrieved for use
from cache. The caller should not access the file after it calls this API. The cache manager is
now free to delete the file if it wants.

DWORD
UnlockUrlFile(
LPCSTR UrlName
);

Parameters:

UrlName : name of the Url File that is being unlocked.The name string should not contain any
escape characters.

Return Error Codes :

ERROR_FILE_NOT_FOUND : if the specified URL is not found in the cache storage.

Microsoft Confidential 7/6/2019 7/6/20197/6/2019 10

3.1.3.5 CreateUrlFile
CreateUrlFile API will allocate requested cache storage and make a local file name that will be
used to save the Url file. Internet services that use the URL cache should call this API to write
directly into the cache storage. The caller should indicate the expected size of the URL file, but it
is not guaranteed. Once the file is completely received, the caller should call CacheUrlFile to
commit the file in the cache.

DWORD
CreateUrlFile(
LPCSTR UrlName,
DWORD ExpectedFileSize,
LPWSTR FileName
);

Parameters:

UrlName : Name of the URL. The name string should not contain any escape character.
ExectedFileSize : Expected size of the URL. If the expected size is unknown then set this value
to zero.
FileName : Pointer to a file name buffer. The buffer should be large enough to store the file path
name of the create file.

Return Error Codes:

Windows Error Codes.

3.1.3.5 GetUrlInfo
GetUrlInfo API retrieves the information of the specified URL.

DWORD
GetUrlInfo(
LPCSTR UrlName,
LPURL_INFO UrlInfo
);

Data Definition:

typedef struct _URL_INFO {

LONGLONG LastModifiedTime;
LONGLONG ExpireTime;
Microsoft Confidential 7/6/2019 7/6/20197/6/2019 11
} URL_INFO, *LPURL_INFO;

Parameters:

UrlName : Name of the URL. The name string should not contain any escape character.
UrlInfo : Pointer to a URL_INFO structure.

Return Error Codes:

ERROR_FILE_NOT_FOUND : if the specified URL is not found in the cache.

3.1.3.5 SetUrlInfo
SetUrlInfo API retrieves the information of the specified URL.

DWORD
SetUrlInfo(
LPCSTR UrlName,
LPURL_INFO UrlInfo
);

Data Definition:

typedef struct _URL_INFO {

LONGLONG LastModifiedTime;
LONGLONG ExpireTime;
} URL_INFO, *LPURL_INFO;

Parameters:

UrlName : Name of the URL. The name string should not contain any escape character.
UrlInfo : Pointer to a URL_INFO structure.

Return Error Codes:

ERROR_FILE_NOT_FOUND : if the specified URL is not found in the cache.

3.1.4 URL Files Cache Admin Management

Internet URL files cache management APIs provide controls to administrator to manage the URL
files that are cached on the gateway server storage.

Data Definitions:

typedef struct _CACHE_PATH_ENTRY {

LPTSTR CachePath;
LARGE_INTEGER CacheSize;

Microsoft Confidential 7/6/2019 7/6/20197/6/2019 12

} CACHE_PATH_ENTRY, *LPCACHE_PATH_ENTRY;

typedef struct _CACHE_PATHS {

DWORD NumCachePaths;
LPCACHE_PATH_ENTRY CachePaths;
} CACHE_PATHS, *LPCACHE_PATHS;

typedef struct _CACHE_INFO {

DWORD FreshnessInterval; // time to wait before URL file update
DWORD CleanupInterval; // time inteval between the unused file cleanups.
DWORD CleanupFactor; // % of the cache storage freed up during cleanup.
DWORD TimetoCleanup; // schedule cleanup, 0 - mid-night, 1 - 1:00 AM and so on.
BOOL PersistentCache; // if set the cache is presistent across service restart.
BOOL ForceCleanup; // setting this field flushes the cache.
LPCACHE_PATHS CachePaths; // list of cache paths.
} CACHE_INFO, *LPCACHE_INFO;

3.1.5 URL Cache Management APIs2

3.2 Gateway Service Management

Gateway service provides a rich set of APIs that controls the service usage. These APIs are
categorized into the following classes :

1. User Access Control APIs

2. Server MIB API

3. Server Audit Log APIs

3.2.1 User Access Control

Gateway server selectively allows access to users to use Internet services. If a user is not
allowed to access certain Internet service or not allowed to do certain operation such as write
through the gateway server, it returns ERROR_ACCESS_DENIED when the user calls that
service specific API. The administrator will have control to specify such access to users. When

2
These APIs are defined as part of internet mangement APIs in some other doc.
Microsoft Confidential 7/6/2019 7/6/20197/6/2019 13
the service is installed all users (the world) will have all access to all services. The administrator
needs to setup appropriate access to users if the gateways server has to be secured.

Data Definitions :

#define GATEWAY_SERVICE_NO_ACCESS 0x00000000

#define GATEWAY_SERVICE_READ_ACCESS 0x00000001
#define GATEWAY_SERVICE_WRITE_ACCESS 0x000000023

typedef struct _ACCESS_ENTRY {

ACCESS_MASK AccessRights;
PSID UserID;
} ACCESS_ENTRY, *LPACCESS_ENTRY;

typedef struct _ACCESS_LIST {

DWORD NumEntries;
LPACCESS_ENTRY AccessEntries;
} ACCESS_LIST, *LPACCESS_LIST;

3.2.1.1 GatewayAddUserAccess
GatewayAddUserAccess API gives the specified access rights to the specified user or group to
access the specified service. The call will return ERROR_ACCESS_DENIED if the caller does
not have enough privilege to perform this operation. If the specified user or group has already
had an entry in the access control list of the specified service, it will replace the old access
rights. The order of access control entries in the list is also important, since a user can be
member of a group that does not have access to a service, will not receive access to that service
even if another entry in the access control list specified beyond the group entry that gives the
user access.

DWORD
GatewayAddUserAccess(
IN LPCWSTR ServerAddress,
IN LPCWSTR ServiceName,
IN LPACCESS_LIST AccessList
);

Parameters :
3
Currently only these access mask are defined here, in future new access types can be defined. The system allows us to
define upto 16 access types.
Microsoft Confidential 7/6/2019 7/6/20197/6/2019 14
ServerAddress : Address of the Gateway server.
ServiceName : Name of the Internet service that requires this access protection.
AccessList : Pointer to a list of aces to be added/modified in the service ACL.

Return Error Codes :

ERROR_ACCESS_DENIED : if the caller does not have enough access privilege to perform this
operation.
ERROR_INVALID_PARAMETER : if any of the specified parameter is invalid.

3.2.1.2 GatewayDeleteUserAccess
GatewayDeleteUserAccess deletes the specified user aces from the ACL of the specified
service. If the access list becomes empty, no one can access the service.

DWORD
GatewayDeleteUserAccess(
IN LPCWSTR ServerAddress,
IN LPCWSTR ServiceName,
IN LPACCESS_LIST AccessList
);

Parameters :

ServerAddress : Address of the Gateway server.

ServiceName : Name of the Internet service that requires this access protection.
AccessList : Pointer to a list of aces to be deleted from the service ACL.

Return Error Codes :

ERROR_NO_SUCH_USER : if the specified user is not found in the user control list of the
specified service.
ERROR_INVALID_PARAMETER : if any of the specified parameter is invalid.

3.2.1.3 GatewayEnumUserAccess
GatewayEnumUserAccess enumerates the list of users and their corresponding access rights.

DWORD
GatewayEnumUserAccess(
IN LPCWSTR ServerAddress,
IN LPCWSTR ServiceName,
OUT LPACCESS_LIST *AccessList
);

Microsoft Confidential 7/6/2019 7/6/20197/6/2019 15

Parameters :

ServerAddress : Address of the Gateway server.

ServiceName : Name of the Internet service whose user access list is queried.
AccessList : Pointer to a location where the pointer to an AccessList memory block is returned.
The caller should free up the memory after use by calling GatewayFreeMemory()
function.

Return Error Codes :

ERROR_INVALID_PARAMETER : if the service name is invalid.

ERROR_NOT_ENOUGH_MEMORY : if the system does not have enough memory to return
user access list.

3.2.2 Server MIB

Server MIB API provides gateway server statistic information such as number of users
connected to the server, number of users connected to different Internet services, number of files
that are transferred, etc.

Data Definitions :

typedef struct _INTERNET_SERVICE_MIB_ENTRY {

LPTSTR ServiceName;
DWORD NumUsers;
DWORD NumFiles;
} INTERNET_SERVICE_MIB_ENTRY, *LPINTERNET_SERVICE_MIB_ENTRY;

typedef struct SERVER_MIB_INFO {

SYSTEMTIME StartTime;
DWORD NumUsersConnected;
DWORD NumCacheFiles;
DWORD NumCacheQueries;
DWORD NumServices;
LPINTERNET_SERVICE_MIB_ENTRY ServiceMIBs;
} SERVER_MIB_INFO, *LPSERVER_MIB_INFO;

3.2.2.1 GatewayServerQueryMIBInfo
GatewayServerQueryMIBInfo returns the server statistic information.

Microsoft Confidential 7/6/2019 7/6/20197/6/2019 16

DWORD
GatewayServerQueryMIBInfo(
IN LPCWSTR ServerAddress,
OUT LPSERVER_MIB_INFO *ServerQueryMIBInfo
);

Parameters :

ServerAddress : Address of the Gateway server.

ServerQueryMIBInfo : Pointer to a location where the pointer to ServerQueryMIBInfo memory
block is returned. The caller should free up the memory after use by calling
GatewayFreeMemory() function.

Return Error Codes :

None.

3.2.3 Server Audit Log

Server Audit Log APIs allow you to configure the server audit logging.

Data Definitions :

typedef enum _GATEWAY_LOG_TYPE {

GatewayNoLog,
GatewayLogToFile,
GatewayLogToPeriodicFile,
GatewayLogToRemoteFile,
GatewayLogToSQLServer
} GATEWAY_LOG_TYPE, *LPGATEWAY_LOG_TYPE;

typedef enum _GATEWAY_LOG_PERIOD {

GatewayPeriodNone,
GatewayPeriodDaily,
GatewayPeriodWeekly,
GatewayPeriodMonthly,
GatewayPeriodYearly
} GATEWAY_LOG_PERIOD, *LPGATEWAY_LPG_PERIOD;

typedef struct _GATEWAY_CONFIG_FILE_INFO {

LPWSTR FileName;

Microsoft Confidential 7/6/2019 7/6/20197/6/2019 17

 DWORD FileSize;
} GATEWAY_CONFIG_FILE_INFO, *LPGATEWAY_CONFIG_FILE_INFO;

typedef _GATEWAY_CONFIG_PERIODIC_FILE_INFO {
LPWSTR FileName;
GATEWAY_LOG_PERIOD Period;
} GATEWAY_CONFIG_PERIODIC_FILE_INFO,
*LPGATEWAY_CONFIG_PERIODIC_FILE_INFO;

typedef struct _GATEWAY_CONFIG_REMOTE_FILE_INFO {

LPWSTR RemoteFileName; // UNC name.
LPWSTR UserName;
DWORD PasswordLength;
LPBYTE Password;
GATEWAY_REMOTE_LOG_TYPE LogType;
union {
DWORD FileSize;
GATEWAY_LOG_PERIOD Period;
} LogTypeInfo;
} GATEWAY_CONFIG_REMOTE_FILE_INFO, *LPGATEWAY_CONFIG_REMOTE_FILE_INFO;

typedef struct _GATEWAY_CONFIG_SQL_INFO {

LPWSTR ServerName;
LPWSTR DatabaseName;
LPWSTR TableName;
LPWSTR UserName;
DWORD PasswordLength;
LPBYTE Password;
} GATEWAY_CONFIG_SQL_INFO, *LPGATEWAY_CONFIG_SQL_INFO;

typedef struct _GATEWAY_LOG_CONFIG {

GATEWAY_LOG_TYPE LogType;
union {
GATEWAY_CONFIG_FILE_INFO FileInfo;
GATEWAY_CONFIG_PERIODIC_FILE_INFO PeriodicFileInfo;
GATEWAY_CONFIG_REMOTE_FILE_INFO RemoteFileInfo;
GATEWAY_CONFIG_SQL_INFO SqlServerInfo;
} LogInfo;
Microsoft Confidential 7/6/2019 7/6/20197/6/2019 18
 LPWSTR LogRecordFormat;
} GATEWAY_LOG_CONFIG, *LPGATEWAY_LOG_CONFIG;

3.2.3.1 GatewaySetAuditLogConfigInfo
GatewaySetAuditLogConfigInfo API allows administrators to set the gateway server audit log
configuration.

DWORD
GatewaySetAuditLogConfigInfo(
IN LPCWSTR ServerAddress,
IN GATEWAY_LOG_CONFIG *AuditLogConfig
);

Parameters :

ServerAddress : Address of the Gateway server.

AuditLogConfig : pointer to a GATEWAY_LOG_CONFIG structure used to set server audit log
configuration.

Return Error Codes :

ERROR_INVALID_PARAMETER : if the info any info specified in the AuditLogConfig structure is

invalid.

3.2.3.1 GatewayGetAuditLogConfigInfo
GatewayGetAuditLogConfigInfo API allows administrators to get the current gateway server
audit log configuration.

DWORD
GatewayGetAuditLogConfigInfo(
IN LPCWSTR ServerAddress,
IN LPGATEWAY_LOG_CONFIG *AuditLogConfig
);

Parameters :

ServerAddress : Address of the Gateway server.

AuditLogConfig : pointer to a location where the pointer to a GATEWAY_LOG_CONFIG structure
is returned. Caller should freeup the memory allocated for the returned structure after
use.

Return Error Codes :

Microsoft Confidential 7/6/2019 7/6/20197/6/2019 19

ERROR_INVALID_PARAMETER : if the info class specified is invalid.

3.2.4 Server RPC Memory

Whenever a RPC returns a block memory as return data, the caller should free up that memory
after the data is used or copied to another buffer, otherwise the system will lose its virtual
memory for that application.

3.2.4.1 GatewayFreeMemory
GatewayFreeMemory API call frees up the memory block that was returned as data block to
caller.

DWORD
GatewayFreeMemory(
IN LPCWSTR ServerAddress,
IN PVOID MemoryBlock
);

Parameters :

ServerAddress : Address of the Gateway server.

MemoryBlock : Pointer to a memory block that is freed up.

Return Error Codes :

None.

3.3 User Access Validation :

Gateway server performs access validation for internet API calls to check against the access
privilege required to execute an API. If an user is not granted the required access privilege, the
API will return ERROR_ACCESS_DENIED without doing any further service. This validation is
performed by impersonating the user identification and check against the access required with
the access privileges assigned to the user. After the access check is done the user impersonation
is reverted back. Gateway service provides an API to do this access check for external internet
services. New external internet services implementing the service APIs should use this access
check API to validate user access.

3.2.1 GatewayAccessValidate
GatewayAccessValidate checks user permission to perform specified access.
Microsoft Confidential 7/6/2019 7/6/20197/6/2019 20
DWORD
GatewayAccessValidate( 4
IN LPWSTR ServiceName,
IN ACCESS_MASK DesiredAccess
);

Parameters:

ServiceName : pointer to the name of the external service that is performing this access check.
DesiredAccess : desired access required to perform the required service.

Return Error Codes :

ERROR_INVALID_PAREMETER : if the service name specified is unknown.

ERROR_ACCESS_DENIED : if the caller does not have permission to perform desired access.

4
Local API
Microsoft Confidential 7/6/2019 7/6/20197/6/2019 21
4. Revision History

Version Date Author Description

1.0 11/8/94 madana New Document

1.1 12/5/94 madana Review comments incorporated.

1.2 01/31/95 madana Updated for match implementation and MSN requirements

1.3 02/06/95 madana Updated Server Audit Log APIs

1.4 04/10/95 madana URL cache extensions

Microsoft Confidential 7/6/2019 7/6/20197/6/2019 22