KSC Open API  13.1
Kaspersky Security Center API description
Creating gateway connections

Gateway connection is a way to communicate between nodes which don't have possibility to create direct connection. Gateway connection is created with help of gateway nodes, each of those has two connections and redirect all data between them. For example it is possible to create gateway connection from OpenAPI client to Network Agent through KSC Server as a gateway node; in such case OpenAPI client may make OpenAPI calls to Network Agent. With help of gateway connections OpenAPI client may connect to the secondary Administration Servers, Network Agents and components on them. Multi-node gateway connections are also supported, so gateway connections such as "OpenAPIClient -> the primary Administration Server -> the secondary Administration Server -> Network Agent" are possible.

Gateway connections may be created using GatewayConnection interface. The general scheme to create a gateway connection is following:

  1. Obtain gateway node locations and build locations list. Gateway node location as an opaque KLPAR::Params container retrieved using helper interfaces, such as CgwHelper.
  2. Call GatewayConnection.PrepareGatewayConnection method to create gateway connection, and receive one-time authentication key.
  3. Create new OpenAPI connection or session to same KSC server using KSCGW authentication scheme with provided one-time authentication key.


If 'login' method was used for authentication, then after successful authentication current connection may be used to make OpenAPI calls to target.
If Session.StartSession was called for authentication, then all calls within created session will be routed to target host.

  • To connect to Network Agent obtain its location using CgwHelper.GetNagentLocation method, and build location list as an array of one element containing received location.
  • To connect to the secondary Administration Server obtain its location using CgwHelper.GetSlaveServerLocation method, and build location list as an array of one element containing received location.
  • To connect to the secondary Administration Server or Network Agent lower in server hierarchy, build locations list as an ordered array of the secondary Administration Servers and Network Agent.



Example1: if you want to connect to Network Agent 1, which is managed by the primary Administration Server 1:

  1. Get Network Agent 1 location using CgwHelper.GetNagentLocation call to the primary Administration Server 1
  2. Build locations list as an array of one element, containing Network Agent 1 location
  3. Create gateway connection by calling GatewayConnection.PrepareGatewayConnection on the primary Administration Server 1 and get authentication key.
  4. Create new session using Session.CreateSession method using KSCGW authentication scheme with provided one-time authentication key.
  5. All calls within created session on any OpenAPI connection to the primary Administration Server 1 will be routed to Network Agent 1.

After successful authentication this connection may be used to communicate with Network Agent 1, for example, by calling methods of NagHstCtl, NagRdu, NagGuiCalls, NagRemoteScreen (or NagCgwHelper to recursively create a deeper gateway connection).



Example2: if you want to connect to Network Agent 2, which is managed by the secondary Administration Server 1, and you connected to the primary Administration Server 1, where the primary Administration Server 1 is a direct primary Server for the secondary Administration Server 1:

  1. Get the secondary Administration Server location using CgwHelper.GetSlaveServerLocation call to the primary Administration Server 1
  2. Get Network Agent 2 location using CgwHelper.GetNagentLocation call to the secondary Administration Server 1
  3. Build locations list as an array of two elements: first is the secondary Administration Server 1 location, second is Network Agent 2 location.
  4. Create gateway connection by calling GatewayConnection.PrepareGatewayConnection on the primary Administration Server 1 and get authentication key.
  5. Create new connection to the primary Administration Server 1 using KSCGW authentication scheme with provided one-time authentication key.

After successful authentication this connection may be used to communicate with Network Agent 2, for example, by calling methods of NagHstCtl, NagRdu, NagGuiCalls, NagRemoteScreen (or NagCgwHelper to recursively create a deeper gateway connection).

With KlAkOAPI Python package the secondary Administration Server can be connected as follows: 

        # connect to main server with basic authentication to get gateway token
        server_main = KlAkOAPI.AdmServer.KlAkAdmServer.Create('https://ksc-main.example.com', 'username', 'password', verify = False)        
        # step 1: get the secondary Administration Server location
        cgwHelper = KlAkOAPI.CgwHelper.KlAkCgwHelper(server_main)
        slaveServerLocation = cgwHelper.GetSlaveServerLocation(nChildServerId).RetVal()   
        # step 2: build locations list
        arrLocation = [KlAkOAPI.Params.paramParams(slaveServerLocation)]
        # step 3: prepare gateway connection to main server with locations array built on previous step
        gatewayConnection = KlAkOAPI.GatewayConnection.KlAkGatewayConnection(server_main)
        token_on_slave = gatewayConnection.PrepareGatewayConnection(arrLocation).OutPar('wstrAuthKey')
        server_main.Disconnect()        
        # connect the secondary Administration Server
        server = KlAkOAPI.AdmServer.KlAkAdmServer.CreateGateway('https://ksc-main.example.com', token_on_slave, verify = False)

Network Agent can be connected as follows: 

        # connect to main server with basic authentication to get gateway token
        server_main = KlAkOAPI.AdmServer.KlAkAdmServer.Create('https://ksc-main.example.com', 'username', 'password', verify = False)        
        # step 1: get the Network Agent location
        cgwHelper = KlAkOAPI.CgwHelper.KlAkCgwHelper(server_main)
        nagentLocation = cgwHelper.GetNagentLocation(wsHostName).RetVal()    
        # step 2: build locations list
        arrLocation = [KlAkOAPI.Params.paramParams(nagentLocation)]
        # step 3: prepare gateway connection to main server with locations array built on previous step
        gatewayConnection = KlAkOAPI.GatewayConnection.KlAkGatewayConnection(server_main)
        token_on_nagent = gatewayConnection.PrepareGatewayConnection(arrLocation).OutPar('wstrAuthKey')
        server_main.Disconnect()      
        # connect Network Agent        
        server = KlAkOAPI.AdmServer.KlAkAdmServer.CreateGateway('https://ksc-main.example.com', token_on_slave, verify = False)
See also: