SIP2 over HTTPS
SIP2 over HTTPS
SIP2 machines can communicate over HTTPS. The advantage of HTTPs is that it does not require any configuration in the HostedWise routing or in branches like schools or small libraries. Furthermore, the communication is encrypted. SIP2 over HTTPS is plug-and-play, so no additional configuration to the network is needed.
The password should be 16 to 20 characters, consisting of letters, numbers and/or @$%^&+=-". There is no filter on IP address for SIP2 HTTPS requests, which means SIP2 is available from any public internet connection, which means that it is important that user/login/url information is handled carefully.
The password can be set up in the Wise Manager > systemWise > Access codes and authorizations > Access authorizations > Users. By searching for “name (with role)”, the Wise user of the SIP2 port can be found (put 'machine' or 'actor' as a prefix for the access code of the port; for example 'actor-PAY1234'). Find the right port in the search results and select it. In the section above, the password can be set at 'Manager login code + https client'.
The url that is used to communicate is:
https://[WISE-URL]/sip2https/services .
To check whether the URL is correct, you can open the URL in the browser of your computer; if you see the following text, the URL is correct:
{"error":"Method not allowed"}
JSON request and response
The sip2https tool offers a means to tunnel clear-text SIP2 commands and replies through secured HTTPS. Each SIP2 command is wrapped in a 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 time out of a token.
Implementers should automatically re-login (93) in such cases.
Installation notes
sip2https is a CGI script that runs in the same environment as the Wise portal, i.e. under Apache with mod_perl, and is deployed from the 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 does it have 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 Wise web server. By default, this is a File-system based cache in tmp/FileCache/sip2https. Like with the CGI Wise portal, 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 information there.