bluemix-secure-gateway

bluemix-secure-gateway

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

Usage

To be used in conjunction with the Secure Gateway for Bluemix 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 . This defaults to "https://sgmanager.ng.bluemix.net", the basepath of the Secure Gateway Service in the us-south region. The basepath for the REST API in the UK region is "https://sgmanager.eu-gb.bluemix.net". The basepath for the REST API in the AU region is "https://sgmanager.au-syd.bluemix.net".
• orgID - The Bluemix Organization ID for the Secure Gateway Service being accessed. This is only required if creating or listing gateways.
• spaceID - The Bluemix Space ID for the Secure Gateway Service being accessed. This is only required if creating, describing, or listing gateways.
• username - A Bluemix username which is in the Org and Space provided. This is only needed if creating, describing, or listing gateways.
• password - The Bluemix password associated with the Bluemix username provided.
• token - An authentication token retrieved from Bluemix SSO. This can be used in place of the username and password and must be associated with the Org and Space provided.

var env = sdk.defaults ({
    'username': <Bluemix user name>,
    'password': <Bluemix password>
})

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.

Describe 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 - 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.
• enable_client_tls - Enable TLS for the final outbound connection to the destination. Expected to be a Boolean. Defaults to false.
• client_tls - Either mutualauth or none. Is only compatible with enable_client_tls true. Defaults to none.
• 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.

Updating a Destination

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

Options:

• id - (Required) ID if 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.
• 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.

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

Describe A Destination

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

Options:

• id - ID of the destination to be retrieved

Delete a Destination

gateway.deleteDestination(options, function(error))

Options:

• id - ID of the destination to be deleted

Upload 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

Download 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

Download 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

Delete 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 Generate 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.

Add 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

Remove 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.

Managing Clients

Get Connected Clients

gateway.getClientList(function(err, client_id_array))

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

Get Client status

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

Returns Connected or Disconnected for the specified client ID.

Disconnect Clients

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

gateway.disconnectClients(client_id_array, function(err))

Client Installer Information

Get Client Installer Information

env.getInstallerList(function(err, array_of_descriptions))

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