bluemix-secure-gateway

The Secure Gateway SDK for IBM Cloud contains a set of javascript wrapper APIs for Secure Gateway REST calls to the IBM Cloud Secure Gateway service.

Usage

To be used in conjunction with the Secure Gateway for IBM Cloud accounts and other services.

Developing

You can develop javascript applications with this SDK, nodejs is required.

Initialization

The SDK can be initialized with the following command:

var sdk = require('bluemix-secure-gateway');

Once the SDK has been initialized, we can set the defaults for an environment. Default options that can be set include:

• basepath - The basepath of the Secure Gateway Service REST API.

| Region | basepath | | -- | -- | | US South (Default) | sgmanager.us-south.securegateway.cloud.ibm.com | | US East | sgmanager.us-east.securegateway.cloud.ibm.com | | United Kingdom | sgmanager.eu-gb.securegateway.cloud.ibm.com | | Germany | sgmanager.eu-de.securegateway.cloud.ibm.com | | Sydney | sgmanager.au-syd.securegateway.cloud.ibm.com |

• rscGrp - The IBM Cloud Resource Group ID for the Secure Gateway Service being accessed.
• apiKey - The IBM Cloud apikey of user who has Secure Gateway instance manage permission. Customer can get apiKey via IBM Cloud UI by signing in to IBM Cloud and select Manage>Access (IAM)>API Keys
• iamEndpoint - The IBM IAM Endpoint of the environment you are working with. Default value is https://iam.cloud.ibm.com

var env = sdk.defaults ({
    'basepath': <basepath of the Secure Gateway Service>,
    'rscGrp': <IBM Cloud Resource Group ID>,
    'apiKey': <IBM Cloud  API Key>,
})

Deprecation Notice: If you did not migrate your instances from Cloud Foundry org/space to Resource Group yet, please use different set of default value as below:

• basepath - The basepath of the Secure Gateway Service REST API. (refer to above table for the base path inforamtion)
• orgID - The IBM Cloud Organization ID for the Secure Gateway Service being accessed. This is only required if creating or listing gateways.
• spaceID - The IBM Cloud Space ID for the Secure Gateway Service being accessed. This is only required if creating, describing, or listing gateways.
• username - A IBM Cloud username which is in the Org and Space provided. This is only needed if creating, describing, or listing gateways.
• password - The IBM Cloud password associated with the IBM Cloud username provided.
• token - An authentication token retrieved from IBM Cloud SSO. This can be used in place of the username and password and must be associated with the Org and Space provided.

Creating and Managing Gateways

Creating a Gateway

env.createGateway(options, function(error, gateway))

Options:

• desc - (Required) A description of this gateway. Must be a String.
• enf_tok_sec - Whether to require the security token when connecting the client. Must be a boolean. Defaults to true.
• token_exp - Number of days until the associated security token expires. Defaults to 90 (enter 0 for never expiring).

On success, a gateway object is returned. Use the destination functions on this gateway to manage the destinations under this gateway.

Describing a Gateway

env.getGateway(options, function(error, gateway))

Options:

• id - The Gateway ID, this is accessible from the Secure Gateway UI or the list call
• securityToken - The Gateway Security Token

Returns a gateway object on success.

Listing Gateways

env.listGateways (options, function(error, array))

Options:

• type - (optional) Either enabled or disabled.

Returns an array of all gateways associated with the org and space on success.

Regenerating Gateway Authorization

gateway.regenAuthorization(function(error, gateway))

Returns the updated gateway object.

Updating a Gateway

gateway.updateGateway(options, function(error, gateway))

Options:

• desc - Updated description of the gateway
• enabled - Enable or disable the gateway. Should be a Boolean
• enf_tok_sec - Whether to require the security token when connecting the client. Must be a boolean.
• regen_token - Whether to regenerate the associated security token. Defaults to false. Must be a boolean.
• token_exp - Number of days until the associated security token expires. Defaults to 90. Ignored if regen_token is false or not provided.

Deleting a Gateway

gateway.deleteGateway(function(error))    

Deletes the gateway and returns an error if one occurred.

Creating and Managing Destinations

Creating and managing destinations is done by calling the functions below on the gateway object returned from the gateway functions.

Creating a Destination

gateway.createDestination(options, function(error, destination))

Options:

• desc - (Required) A description of the destination. This must a be a String.
• ip - (Required) The hostname or ip of the destination.
• port - (Required) The port of the destination
• clientPort - This will be a cloud destination. This is the port the client will listen on for an incoming connection.
• protocol - (Required) The protocol of the destination, one of TCP, UDP, TLS, HTTP, or HTTPS.
• TLS - (Required) One of serverside, mutualauth, or none. Defaults to none. Is only compatible with the TLS protocol.
• sni - Server name for the SNI (Server Name Indication) TLS extensions.
• enable_client_tls - (Required) Enable TLS for the final outbound connection to the destination. Expected to be a Boolean.
• client_tls - (Required) Either mutualauth or none. Is only compatible with enable_client_tls true.
• private - Whether iptable rules will be enforced on the cloud host:port connection point. Not supported for cloud destinations. Must be a boolean. Defaults to false.
• compressData - Whether the compression of the request data is enabled or not. Must be a boolean. Defaults to true.
• timeout - Connection timeout in seconds. To enable the timeout, define a non-zero integer (minimum 1, maximum 180). 0 means disable the timeout.
• rejectUnauth - whether the client reject any connection to the destination which is not authorized with the list of supplied CAs. Must be a boolean. Defaults to true.

Deprecation Notice:

As of version 4.3.0 the fields are now required: TLS, enable_client_tls, client_tls. Secure endpoint stand foremost as Secure Gateway's mission and we felt that defaulting to insecure protocols put our API users at risk. The choice is up to you as the user now to decide which protocol you want to leverage when creating your destination.

That being said the Secure Gateway Team would like to see users securing their entry points in the cloud with TLS Mutual auth in order to ensure that only the traffic you expect should enter your Secure Gateway tunnel and then your network.

As an example one can create a Cloud to Onprem destination that secures the Cloud entry point with Mutual TLS with the following configuration:

{
  "desc": "Mutual Auth Secured Entrypoint to Onprem",
  "ip": "my.onprem.destination",
  "port": 9000,
  "protocol": "TLS",
  "TLS": "mutualauth",
  "enable_client_tls": false,
  "client_tls": "none"
}

Note, this only secures the cloud entry point, and in order to secure the final path from the Secure Gateway client to the final destination one would need to set enable_client_tls to true, and client_tls to "mutualauth".

Updating a Destination

gateway.updateDestination(options, function(error, destination))

Options:

• id - (Required) ID of the destination to update
• desc - A description of the destination. This must a be a String.
• enabled - Enable or disable the destination. Should be a Boolean.
• ip - The hostname or ip of the destination.
• port - The port of the destination.
• clientPort - The port the client will listen on for an incoming connection for cloud destinations. If sent to an on-premises destination, an error will be returned.
• protocol - The protocol of the destination, one of TCP, UDP, TLS, HTTP, or HTTPS. The default is TCP.
• TLS - One of serverside, mutualauth, or none. Defaults to none. Is only compatible with the TLS protocol.
• sni - Server name for the SNI (Server Name Indication) TLS extensions.
• enable_client_tls - Enable TLS between the client and the final destination. Expected to be a Boolean.
• client_tls - Either mutualauth or none. Is only compatible with enable_client_tls true.
• private - Whether iptable rules will be enforced on the cloud host:port connection point. Not supported for cloud destinations.
• compressData - Whether the compression of the request data is enabled or not. Must be a boolean. Defaults to true.
• timeout - Connection timeout in seconds. To enable the timeout, define a non-zero integer (minimum 1, maximum 180). 0 means disable the timeout.
• rejectUnauth - whether the client reject any connection to the destination which is not authorized with the list of supplied CAs. Must be a boolean. Defaults to true.

Listing Destinations

gateway.listDestinations(options, function(error, array_of_destinations))

Options:

• enabled - Whether to only include enabled or disabled destinations. Should be a Boolean. If not specified all destinations will be returned.

Returns all destinations associated with the gateway

Describing A Destination

gateway.getDestination(options, function(error, destination))

Options:

• id - ID of the destination to be retrieved

Deleting a Destination

gateway.deleteDestination(options, function(error))

Options:

• id - ID of the destination to be deleted

Uploading Destination Certificates

gateway.uploadDestinationCert(options, function(err, destination))

Options:

• id - ID of the destination these certificates belong to.
• server_cert_filepath - Filepath of the server cert to be uploaded
• client_cert_filepath - Single filepath or an array of up to 6 filepaths of the client certs to be uploaded
• dest_cert_filepath - Filepath of the certificate the client should use to identify itself for TLS purposes
• dest_key_filepath - Filepath of the key the client should use to identify itself for TLS purposes

Downloading Destination Certs and Keys

gateway.downloadDestinationCerts(options, function(err[, array_of_objects]))

Options:

• id - ID of the destination whose certs are to be downloaded
• filepath - Filepath where the zip file should be saved. If none provided, response will be an array of objects {name, contents} instead of a zip

Downloading Specific Destination Certificates

gateway.downloadCertsByName(options, function(err[, array_of_objects]))

Options:

• id - ID of the destination these certificates belong to.
• filenames - String of filenames separated by spaces or an array of filenames
• filepath - Filepath where the zip file should be saved. If none provided, response will be an array of objects {name, contents} instead of a zip

Deleting Destination Certificates

gateway.deleteDestinationCerts(options, function(err, destination))

Options:

• id - ID of the destination these certificates belong to.
• filenames - String of filenames separated by spaces or an array of filenames

Auto Generating Destination Certificate/Private Key

gateway.generateDestinationCerts(options, function(err))

Options:

• id - ID of the destination to generate cert and key for
• client - Whether the generated cert and key are for destination-side TLS Mutual Auth (determined by destination properties enable_client_tls and client_tls) or for server side TLS Mutual Auth (determined by destination properties protocol and TLS). False will generate for server side TLS Mutual Auth, true will generate for destination-side TLS Mutual Auth. Should be a boolean. Default to false.

This generates a cert and key for a TLS: Mutual Auth destination on either destination side or server side.

Adding an IP Table Rule

gateway.addIPTableRule(destination_id, options, function(err))

Destination must be set to private in order to add and enforce iptable rules. If you want to set multiple rules at once, you can send an array of options.

Options:

• src - IP to allow to connect. If no src or src_range provided, all IPs will be allowed for this rule.
• src_range - Range of IPs (using the form 1.1.1.1-2.2.2.2) to allow (src and src_range cannot be sent in the same object).
• spt - Port or range of ports to allow (using the form 5000:5005 for a range). If none provided, all ports will be allowed for this rule.
• app - Desired ID to associate with the rule. If used, any other rule given the same ID will overwrite this one

Removing an IP Table Rule

gateway.removeIPTableRule(destination_id, options, function(err))

Destination must be set to private in order to add and enforce iptable rules. Rules may be removed all at once or one at a time (via individual calls). If removing individually, these values should match exactly what was provided when adding them. Options:

• src - IP to match for removal.
• src_range - Range of IPs (using the form 1.1.1.1-2.2.2.2) to allow match for removal (src and src_range cannot be sent in the same object).
• spt - Port or range of ports to match for removal (using the form 5000:5005 for a range).
• all - Must be a boolean. If true, will remove all iptable rules associed with the destination. Defaults to false.

Importing and Exporting

Exporting a Service

env.exportService([filepath,] function(error[, gateways]))

Exports the gateways and their destinations as a JSON object. If a filepath is provided, a <filepath>/service.config file will be written containing the response (NOTE: this will overwrite any existing file with the same name). Otherwise, the response will be returned as the second argument of the callback. The downloaded file can be used with the env.importService function to recreate the gateways and destinations.

Importing a Service

env.importService(filepath, function(error, array))

Filepath is the path to the service.config file from an exported service. This imports the gateways and their destinations into the org/space specified in the defaults. On success, an array of gateway objects will be returned.

Exporting a Gateway

gateway.exportGateway([filepath,] function(error[, gateway]))

Exports the gateway and its destinations as a JSON object. If a filepath is provided, a <filepath>/<gateway_id>.gateway file will be written containing the response (NOTE: this will overwrite any existing file with the same name). Otherwise, the response will be returned as the second argument of the callback. The downloaded file can be used with the env.importGateway function to recreate the gateway and destinations.

Importing a Gateway

env.importGateway(filepath, function(error, gateway))

Filepath is the path to the *.gateway file from an exported gateway. This imports the gateway and its destinations into the org/space specified in the defaults. On success, a gateway object will be returned.

Exporting a Destination

gateway.exportDestination(options, function(error[, destination]))

Exports the destination as a JSON object. If a filepath is provided, a <filepath>/<destiantion_id>.destination file will be written containing the response (NOTE: this will overwrite any existing file with the same name). Otherwise, the response will be returned as the second argument of the callback. The downloaded file can be used with the gateway.importDestination function to recreate the destination.

Options:

• id - (Required) ID of the destination to export.
• filepath - Location to write the <id>.destination file.

Importing a Destination

gateway.importDestination(filepath, function(error, destination))

Filepath is the path to the *.destination file from an exported destination. This imports the destination into the gateway. On success, the imported destination will be returned as a JSON object.

Managing Clients

Getting Connected Clients

gateway.getClientList(function(err, client_id_array))

Returns an array of objects {id, version} that are currently connected to the gateway.

Getting Client status

gateway.getClientStatus(client_id, function(err, status))

Returns Connected or Disconnected for the specified client ID.

Disconnecting Clients

Note: This is only supported for clients >= v1.4.2

gateway.disconnectClients(client_id_array, function(err))

Getting Recently Disconnected Clients

gateway.getDisconnectedClients(function(err, client_id_array))

Returns an array of objects {id, disconnectedAt} containing up to the last 10 clients that disconnected from the gateway.

Getting Client Logs

gateway.getClientLogs([options,] function(err, logs))

Returns an object keyed by the clientID that contains a warnings object and an errors object. Each of these objects contain log messages keyed by timestamp (e.g., {warnings: {<timestamp>:<message>}})

Options:

• clientID - Specific client ID to return the logs for
• type - Either warn or error, only that type of log will be returned

Client Installer Information

Getting Client Installer Information

env.getInstallerList(function(err, array_of_descriptions))

Returns an array of objects {description, url} for each installer we currently offer.