SIP2 over https

Introduction

The SIP2https tool offers a means to tunnel clear-text SIP2 commands and replies through secured HTTPS. Each SIP2 command is wrapped in an JSON object and accompanied by a token. This token serves to identify the authenticity of the request.

Below is an example request- and response-pair. Note that initially the token (sent by the client together with a 93 request) will be empty. The server will supply a token after successful login. From that point on the client must issue the last received token on each subsequent request.

JSON Request example:

{
    "SIP2request":"6300020071001AO|AA21234002896242|ACxyzzy|AD1234|AY3AZEF37",
    "token":"rqYtfjBBMOqK+fK7yW0Z1TSyCJ8"
}


JSON Response example:

{
    "SIP2response":"64Y83838383838AOWisecity|AA21234002896242|AE|BLN|CQY|BHEur|BV0.00|FB0.00|FC0.00|AY3AZBFDE"
    "token":"rqYtfjBBMOqK+fK7yW0Z1TSyCJ8"
}

Notes for the (client side) implementation

The SIP2https service has a base URL of the format:
https://<hostname>/SIP2https/services and accepts only POST requests.

POST-ed data should be op Content-type application/json. Encoding is UTF-8.

For security reasons the SIP service requires a password (CO subfield of command 93) with a length of at least 16 characters. This password must be different from the username (CN subfield).

In a REST-like fashion, the service makes use of HTTP-status codes and error messages for error situations. Status 200 indicates a successful command, status codes in the 4XX series are used for different errors.

In case of Authentication failures, the service increments a failure counter per (client) IP address. When the failure counter reaches a certain predefined limit (typically 10) the IP address will be blocked from accessing the service for a certain predetermined period (typically 1 hour) to defend against abuse. A successful login resets the counter.

The token that is provided after a successful login will expire after a certain amount of idle time (typically 2 hours). If the client makes use of an expired token the server will respond with 401 Unauthorized. A reset of the server may also trigger timeout of a token. Implementors should automatically re-login (93) in such cases.

Installation notes

SIP2https is a CGI script that runs in the same environment as the OCLC Wisecat+, i.e. under Apache with mod_perl, and is deployed from the OCLC Wise-bxmcgi package. Since it is deployed in a different directory (SIP2https and not cgi-bin) there are specific ScriptAlias and Allow rules needed to allow functioning within the Apache environment. To enable, the following config should be included with the Apache config associated with the SSL (HTTPS) config:

ScriptAlias /SIP2https/services /home/bng/SIP2https/SIP2https.pl
<Directory /home/bng/SIP2https>
    SetHandler perl-script
    PerlHandler ModPerl::Registry
    Options +ExecCGI
    PerlOptions +ParseHeaders
    Require all granted
</Directory>

Note that it is the responsibility of the host to ensure that this script is only reachable via HTTPS and not via standard HTTP. The script itself does not enforce this (nor has the means to do that). The SSL connection is supposed to be handled by Apache or some other network component (e.g. a firewall) at the hosing side and this is out of scope for the SIP2https script. (This script merely relays commands.)

This script makes use of the cache that is available on the OCLC Wiseweb server. By default this is a File-system based cache in tmp/FileCache/SIP2https. Like with the CGI OCLC Wisecat+, a hazelcast or other memcached protocol capable object store can be used as well. The script stores the failure counters, blocking information and some session state there.

Configuration notes

It is advised to hand out hard passwords to the SIP2 clients. The minimal length is 16 characters. The advise is to make us of some random string generator for this. Such funcionality will eventually be provided in the Manager.

Configuration of the script takes place in /etc/bng.d/SIP2https.conf. Minimal contents are (*):

$cfg = {
    'CONN' => {
    'WISEURL' => 'http://wiseas/bxmas',
    },
    'DEBUG' => 3,
};

1;
DEBUG level 4 is the minimum that is advised, as this still gives warnings and some statistics.

The following options exist for modifying "failure counter" behavior:
$cfg->{'CONN'}{'MAX_TRIES_PER_IP'} with a default of 10
$cfg->{'CONN'}{'BLOCK_TIME'} with a default of '60m' (60 minutes)

(*) without a config file these defaults will be used

Bijlage:

Voorbeeld dialogen: