Using RLM with HTTPS

Beginning in RLM v14.0, your RLM-enabled application can communicate with an RLM Cloud license server using HTTPS, rather than the native RLM socket protocol. Beginning in RLM v14.1, Activation Pro supports the HTTPS protocol as well.

You will need to ensure that you can handle the new RLM_EH_WEBS_NOSUPP and or RLM_EH_NOHTTPSSUPPORT status returns, which will be returned on certain RLM API functions that are not supported with web services. See the last section in this chapter for more information.

If your company does not use RLM Cloud servers or Activation Pro, you can ignore this chapter.

How to use HTTPS with RLM Cloud or Activation Pro

First of all, HTTPS transport is only supported in the Linux, Mac and Windows versions of RLM. Any other platform will return RLM_EH_WS_NOSUPP when web services is specified in the license file, or RLM_EH_NOHTTPSSUPPORT if you specify an HTTPS URL to Activation Pro (or your URL redirects to an HTTPS URL).

For RLM Cloud, to include HTTPS support in your application, follow these instructions:

  • Be sure to set the appropriate value in the rlm_isv_cfg_set_promise() call contained in rlm_isv_config.c. By default, this is 10 minutes, which means you need to call rlm_get_attr_health() every 5-7 minutes.

  • Call rlm_isv_cfg_set_isv_handshake() in rlm_isv_config.c with an appropriate set of P1 and P2 parameters (please do not use the defaults values in rlm_isv_config.c).

For both RLM Cloud and Activation Pro, follow these (additional) instructions:

For Linux and Mac:

  • Link your RLM application with the web services http module rlm_msgs_http.o. Place this object file before the rlm library in your link line. Consult the build rules for rlmclient_http in the makefile for an example.

  • You must ensure that every system where your application runs has the CURL libraries installed. (These libraries are always installed in our experience on Mac). If the libraries are not installed, you will get a message similar to this when you run your application on Linux:

your-program-name: error while loading shared libraries: libcurl.so.4: cannot open
shared object file: No such file or directory

On Ubuntu Linux, this is solved with the following command:

% sudo apt-get install libcurl-openssl-dev

For Windows:

  • Link your RLM application with the web services http module rlm_msgs_http.obj. There are 4 different variants of rlm_msgs_http.obj for Windows, corresponding to the 4 different object formats (//MD, //MT, //MDd, and //MTd). They are rlm_msgs_http_md.obj, etc. When building your application, select the appropriate one for the style of build you’re doing and place it on your LINK command line before the RLM library. See the build rule for exampleclient_http.exe in the makefile for an example.

    • If using a DLL, link the appropriate rlm_msgs_http.obj with the DLL and then link only the include library with your application. see the DLL and exampleclientd_http_md.exe rules in the makefile for an example

  • Unlike on Linux, using the HTTPS capability in RLM does not require any external library dependencies. All the low-level CURL/HTTPS support is in the RLM client library. Of course, it is linked into your application only if you use rlm_msgs_http_*.obj.

Once your application is built with the correct support, and the CURL libraries are installed on the target system, using HTTPS is simply a matter of:

For RLM Cloud:

Change the normal RLM Cloud CUSTOMER line to use the HTTPS port. So, for a normal RLM Cloud license file, there would be a CUSTOMER line like the following:

CUSTOMER customer-name isv=isvname server=lsN.rlmcloud.com port=5053 password=XXX

To use the HTTPS transport, simply change the port number from 5053 to 443:

CUSTOMER customer-name isv=isvname server=lsN.rlmcloud.com port=443 password=XXX

For Activation Pro:

Specify an https:// URL rather than http://

That’s all there is to it. Everything else remains the same; the RLM client library switches to use HTTPS transport when appropriate.

What if I I use RLM Cloud and don’t build in web services support

If you use RLM Cloud and don’t build in web services support, you must be prepared to receive the RLM_EH_WS_NOSUPP error from various RLM functions (or RLM_EH_NOHTTPSSUPPORT for the rlm_activate() family of functions). If your customer changes the RLM CUSTOMER line to use port 443, any requests you make thru the RLM client library will return RLM_EH_WS_NOSUPP.

If you use web services, you might get a RLM_EL_BADHANDSHAKE error if a checkout succeeds and the handshake is bad. In this case, you should be sure to check the license back in, otherwise it will remain checked out on the server until the promise interval expires.

Note

Calling rlm_checkin() after a failed checkout is always a fine thing to do.

Some notes on MacOS

Earlier versions of MacOS have a bug in the CURL libraries and HTTPS will not work. What we know for sure at this point is that 10.5.8 (Leopard) and earlier do not work, and that 10.12 (Sierra) and presumably later do work.

Unsupported RLM API functions with web services

When using the HTTPS transport, there are RLM API functions which are not supported, and if you call any of these, your code should be prepared to receive an RLM_EH_WEBS_NOSUPP error, or the function may simply be ineffective These functions continue to work for local license files, and license files which specify a server that does not use web services, they just don’t work on any license file in your path that specifies web services access to the server. These functions are:

  • Licenses cannot be roamed when using web services.

  • You cannot queue for licenses with web services – RLM_QUEUE is ignored.

  • rlm_auth_check() - used to detect a hacked server, which is not an issue for RLM Cloud.

  • rlm_set_attr_logging() is ignored.

  • Dynamic reservations can only be created/reclaimed for the same ISV name. This means that if you want a job scheduler to create dynamic reservations for you, you will have to write a small utility program to create the reservation and use non-HTTPS transport.

  • Client timezone= and platforms= license keywords are unused – the timezone will always appear to be the servers timezone, and the platform will always be x64_l.

  • The “disallow_generic” server setting and the “isv string invisible” settings are ignored.

  • The following client environment parameters are not passed to the server: RLM_PROJECT, client computing environment, client os version, client’s argv[0]

  • Client authentication with rlmadduser is not supported with HTTPS.

Using RLM/HTTP with proxy servers

RLM uses CURL for https transport. If you have a proxy server, you will need to set the CURL environment variable http_proxy to the address of your proxy server. See the CURL documentation.

RLM Cloud Performance Metrics

We have run tests on both native and web services based versions of RLM, from various locations (always to an RLM Cloud license server in the Dallas datacenter). The test performs 100 rlm_init()/rlm_checkout()/rlm_checkin()/rlm_close() calls and takes the average time (all in milliseconds). The “location” column indicates where the client software is running. The results are summarized in this table:

Client Location

Checkout time, native

Checkout time, web services

Dallas (same as server)

10-20 msec

280 msec

San Francisco

570 msec

610 msec

New York

280 msec

460 msec

And using a loop of 100 checkout/check-ins (without rlm_init()/rlm_close()):

Client Location

Checkout time, native

Checkout time, web services

Dallas (same as server)

< 10 msec

270 msec

San Francisco

330 msec

600 msec

New York

190 msec

Performance Comparison

If you want to understand why web services for RLM Cloud is so much slower, this section will give you an idea. With the native comm package, the following happens when you check out a license:

  1. Send a message to RLM on the server host, get the address of the ISV server (this is done once per customer name on a particular client machine, and the result is cached).

  2. Send a “hello” message to the ISV server and read the response.

  3. Send a “checkout” message to the ISV server and read the response.

  4. Send a heartbeat message to the ISV server and read the response later.

With web services, it is a lot more complicated:

  1. Your program makes an HTTPS request to the license server on the server host.

  2. The Apache web server on that host starts a php program to process the request.

  3. The php program starts a helper program – (which is a lot like your program would have been if you used the normal comm package) - via another http request to the web server, which then:

    • Sends a hello message to the ISV server, reads the response.

    • Sends a “checkout” message to the ISV server, reads the response.

    • Sends a heartbeat message to the ISV server, it will read the response later.

    • Formats the response back to the php program that started it.

  4. Now, the php program re-formats that data in json and returns it, via the Apache web server, to the web services client (i.e., your program)

  5. Your program parses the json and returns the status to you.

  6. Next, when you call rlm_get_attr_health(), you repeat steps 1-5 again, rather than just reading a response that was already waiting on a socket that was already open.

This brings up another important point. In the normal RLM comm package, heartbeats are “primed” and the response is not checked until later, so the application never waits for a round-trip to the server for a heartbeat. In web services, the heartbeat is always synchronous, so the whole round-trip overhead is incurred on each heartbeat. So don’t do them too often.