Node.js is an asynchronous event driven JavaScript runtime, designed to build scalable network applications. This tutorial will demonstrate how to use IBM SDK for Node.js – z/OS® to create and serve HTTPS web services, and how to create HTTPS clients with help from the Request npm module.

Serving HTTPS web services

This section will demonstrate how to create and serve HTTPS web services.

Step 1: Download and Install IBM SDK for Node.js – z/OS®

Download IBM SDK for Node.js – z/OS here: Download IBM SDK for Node.js – z/OS®

Follow the Knowledge Center Documentation installation instructions to install Node.js and required prerequisites.

Step 2: Start a New Project

Create your project directory and change your current working directory to it. For this tutorial, we will name our sample project my-server.

mkdir my-server
cd my-server

Create a Node.js Package using npm as follows:

npm init --yes

This command will create a package.json file which describes your package and its dependencies. The file will contain the following content:

{
  "name": "my-server",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

The main source file for our project will be named index.js by default.

Step 3: Generate SSL Key and Certificate

You will need to generate a private SSL key and a self-signed certificate to use HTTPS.

This step requires the OpenSSL client. If the OpenSSL client is not installed on your system, you may download it from the Rocket Software website. The download link is given in the Knowledge Center Documentation installation instructions.

Generate the private key privatekey.pem using the following command:

openssl genrsa -out privatekey.pem 1024

Generate a certificate signing request named certrequest.csr. You may be prompted for information that will be incorporated into your certificate request. Enter the information when prompted. Use the following command to begin the process of generating the request:

openssl req -new -key privatekey.pem -out certrequest.csr

Generate a self-signed certificate certificate.pem using the following command:

openssl x509 -req -in certrequest.csr -signkey privatekey.pem -out certificate.pem

Verify that the generated files privatekey.pem and certificate.pem are tagged correctly:

ls -T privatekey.pem

If the command prints out:

t ISO8859-1   T=on  privatekey.pem

Then the file is already tagged correctly. The prefix t ISO8859-1   T=on indicates that the file is tagged as ISO8859-1, and there is nothing you need to do.

If a different message appears, then the file still needs to be tagged. Determine the file’s current encoding:

file -W filecodeset=ISO8859-1 privatekey.pem

If the command prints out:

privatekey.pem: text

Then the file needs to be tagged as ISO8859-1. Run this command:

chtag -tc 819 privatekey.pem

Otherwise, if the command instead prints out:

privatekey.pem:  binary data

Then the file needs to be tagged as IBM-1047. Run this command instead:

chtag -tc 1047 privatekey.pem

Repeat the verification for certificate.pem (replace all instances of privatekey.pem with certificate.pem for each command.)

Step 4: Writing the HTTPS web service

Manually create a new file index.js, and then open it in a text editor of your choosing.

Write the following code to the file:

// Load modules that we'll use.
const https = require('https'); // HTTPS web server.
const fs = require('fs'); // Read files.


// Configuration for the HTTPS web server.
const options = {
  key: fs.readFileSync('privatekey.pem'), // Read privatekey.pem file.
  cert: fs.readFileSync('certificate.pem'), // Read certificate.pem file.
};


// Create the https server and begin listening for requests.
https.createServer(options, (req, res) => {
  // This callback function will be called when someone makes a request to the https server.
  // req will contain the request data, while res will allow a response to be sent back.
  res.writeHead(200); // Set the HTTP response status codes to 200 OK.
  res.end('hello world\n'); // Write the string 'hello world\n' to the body, and send the response back.
}).listen(3000); // Listen for requests on port 3000.

Step 5: Run the HTTPS web service

Run the index.js code we wrote using the following command:

node index.js

For this demonstration, our service listens on port 3000. If this port is already in use by another service, then replace it with a different port that’s not in use.

Next, test that the service is running correctly. Direct your web browser to your server on the appropriate port:

https://your.server.ip.address:3000

You may receive a warning message informing you that your connection is not private, or that the certificate authority is invalid. This is to be expected, because the certificate we generated in Step 3 is self-signed. Ignore the warning message and tell your browser to proceed to the website anyway.

Your connection is not private
You may see this message.

If everything is working correctly, your web browser should now display the “hello world” message.

"hello world" message in the web browser
“hello world” message in the web browser.

Creating HTTPS clients with Request npm module

This section will demonstrate how to create HTTPS clients with help from the Request npm module.

For the purposes of this demonstration, it is recommended that you first complete the previous section, and keep the HTTPS web server running. The following instructions will assume you are working in a new session.

Step 1: Download and Install IBM SDK for Node.js – z/OS®

If you already downloaded and installed IBM SDK for Node.js – z/OS® in the previous section, skip this step.

Download IBM SDK for Node.js – z/OS® here: Download IBM SDK for Node.js – z/OS®

Follow the Knowledge Centre Documentation installation instructions to install Node.js and required prerequisites.

Step 2: Start a New Project

Create your project directory and change your current working directory to it. For this tutorial, we will name our sample project my-client.

mkdir my-client
cd my-client

Create a Node.js Package using npm as follows:

npm init --yes

This command will create a package.json file which describes your package and its dependencies. The file will contain the following content:

{
  "name": "my-client",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

The main source file for our project will be named index.js by default.

Step 3: Install Project Dependencies

The Request npm module needs to be installed as a dependency using:

npm install --save request

This will generate a new file package-lock.json, and modify package.json to add Request as a project dependency. The Request npm module and all of its dependencies will be downloaded and installed under a newly created node_modules directory.

Step 4: Writing the HTTPS Client

Manually create a new file index.js, and then open it in a text editor of your choosing.

Write the following code to the file:

// Load modules that we'll use.
const request = require('request'); // HTTPS Client.


// Configuration for the HTTPS request that we're about to make.
const options = {
    // If you changed the port of the web service in the previous section to something other 
    // than 3000, modify the url accordingly as well.
    url : 'https://your.server.ip.address:3000', // The url of the server we're making the request to.
    rejectUnauthorized: false, // Ignore self-signed certificate warnings.
};


// Make a GET request.
request.get(options, function (err, res, body) {
  // This callback function will be called when someone makes a request to the https server.
  console.log('error:', err); // Print the error if any occurred.
  console.log('statusCode:', res && res.statusCode); // Print the response status code if a response was received.
  console.log('body:', body); // Print the body of the page.
});

Step 5: Run the HTTPS Client

Run the index.js code we wrote using the following command:

node index.js

Assuming that the HTTPS web server from the previous section is still running, you should now see the following printed to the console:

error: null
statusCode: 200
body: hello world

Since the HTTPS web server that we wrote returns status code 200 with “hello world” as the body, this indicates that both our HTTPS web service as well as the HTTPS client are working correctly.

If a different message appears, then either the HTTPS server from the previous section is no longer running, or you entered the IP address/hostname of a different web server.

Join The Discussion

Your email address will not be published. Required fields are marked *