SIP2 over https

Laatst bijgewerkt op
Als PDF opslaan

SIP2-automaten in OCLC Wise kunnen gebruik maken van communicatie over HTTPS. Voordeel van https is dat er geen configuratie nodig is in de routeringen en in vestigingen als scholen of kleine bibliotheken. Daarnaast is het ook niet afluisterbaar omdat de communicatie versleuteld wordt. SIP2 over https werkt gewoon out of the box zonder aanpassing aan het lokale netwerk.

Het wachtwoord moet minimaal 16 posities lang zijn en een zeer sterk wachtwoord zijn (zo random mogelijk). Er zit geen filtering op IP-nummer voor de SIP2 https requests wat betekent dat vanaf het gehele internet SIP2-requests kunnen worden uitgevoerd. Om deze reden is het belangrijk dat zorgvuldig wordt omgegaan met inloggegevens, inclusief de url waarmee wordt verbonden.

Het wachtwoord moet worden ingesteld via de Manager > systeemWise > Toegangscodes en bevoegdheden > Bevoegdheden > Tabblad Gebruikers.

Door te zoeken op ‘naam (met rol)’ is de 'Wise gebruiker' van de SIP2 poort te vinden (zet ‘Automaat-‘ of ‘actor-‘ als prefix voor de toegangscode van de poort, bijv. actor-PAY1234).
De juiste poort gevonden? Klik aan, dan is in het deel erboven het wachtwoord in te stellen bij ‘Inlogcode Manager + https-client’.
De url waarmee gecommuniceerd moet worden: https://[WISE-URL]/SIP2https/services.

Open de url in een browser om te testen of de juiste url in gebruik is. Als de melding {"error":"Method not allowed"} verschijnt, is de juiste url in gebruik.

JSON request en response

De SIP2https-tool biedt een manier om clear-text SIP2-commando's en -antwoorden te tunnelen via beveiligde HTTPS. Elk SIP2-commando wordt verpakt in een JSON-object en vergezeld van een token. Dit token dient om de authenticiteit van het verzoek te identificeren.

Hieronder staat een voorbeeld van een request- en response. Let op: het token zal aanvankelijk leeg zal zijn (verzonden door de client samen met een 93-request). De server zal na een succesvolle login een token verstrekken. Vanaf dat moment moet de client bij elk volgend verzoek het laatst ontvangen token meesturen.

JSON Request voorbeeld:

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

JSON Response voorbeeld:

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

Aantekeningen voor bij (client side) implementatie

De SIP2https-service heeft een basis-URL in het volgende formaat:
https://<hostname>/SIP2https/services en accepteert alleen POST-requests.

Ge-POST-e gegevens moeten de Content-Type application/json hebben. De codering is UTF-8.
Om veiligheidsredenen vereist de SIP-service een wachtwoord (CO-subveld van commando 93) met een minimale lengte van 16 tekens. Dit wachtwoord mag niet hetzelfde zijn als de gebruikersnaam (CN-subveld).
Volgens REST-stijl maakt de service gebruik van HTTP-statuscodes en foutmeldingen voor foutafhandeling:
- Status 200 geeft een geslaagd commando aan.
- Statuscodes in de 4XX-reeks worden gebruikt voor verschillende foutmeldingen.

Authenticatiefouten en IP-blokkering

Bij een authenticatiefout verhoogt de service een counter voor failures per (client) IP-adres.

Wanneer deze counter een vooraf gedefinieerde limiet bereikt (meestal 10 pogingen), wordt het IP-adres geblokkeerd voor een bepaalde periode (meestal 1 uur) om misbruik te voorkomen.
Een succesvolle login reset de counter.

Token-verloop en herauthenticatie

Het token dat wordt verstrekt na een succesvolle login verloopt na een bepaalde inactieve periode (meestal 2 uur).

Als de client een verlopen token gebruikt, zal de server reageren met 401 Unauthorized.
Een serverreset kan ook leiden tot het verlopen van een token.
Implementors moeten in dergelijke gevallen automatisch opnieuw inloggen (93-commando).

Installatie

SIP2https is een CGI-script dat wordt uitgevoerd onder Apache met mod_perl. Het wordt gedeployed vanuit het OCLC Wise-bxmcgi-pakket. Er zijn specifieke ScriptAlias- en Allow-regels nodig om het correct te laten functioneren binnen de Apache-omgeving.

Om SIP2https in te schakelen, moet de volgende configuratie worden opgenomen in de Apache-configuratie die is gekoppeld aan de SSL (HTTPS)-configuratie:

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>

Let op: het is de verantwoordelijkheid van de host om ervoor te zorgen dat dit script alleen via HTTPS bereikbaar is en niet via standaard HTTP.

Het script zelf dwingt dit niet af (en heeft ook geen mechanisme om dit te doen).
De SSL-verbinding moet worden afgehandeld door Apache of een ander netwerkcomponent (zoals een firewall) aan de hostzijde.
SIP2https fungeert alleen als doorgeefluik voor commando’s.

Dit script maakt gebruik van de cache die beschikbaar is op de OCLC Wiseweb-server. Standaard wordt een bestandssysteemgebaseerde cache gebruikt:
/tmp/FileCache/SIP2https

Er kan ook een hazelcast of een ander memcached-protocol-compatibel objectopslagmechanisme worden gebruikt. Het script slaat de volgende gegevens op in de cache:

Failure counters
Blokkade-informatie
Sommige sessiestatusgegevens

Configuratie

Het wordt aangeraden om sterke wachtwoorden aan de SIP2-clients toe te wijzen. De minimale lengte is 16 tekens. Het wordt aanbevolen om een random string generator te gebruiken om deze wachtwoorden te genereren.

Scriptconfiguratie

De configuratie van het script vindt plaats in:
/etc/bng.d/SIP2https.conf

Een minimale configuratie bevat:

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

1;

DEBUG level 4 is de aanbevolen minimuminstelling, aangezien dit nog steeds waarschuwingen en statistieken doorgeeft.

Instellingen voor "failure counter" gedrag

De volgende opties bestaan voor het aanpassen van het "failure counter" gedrag:

$cfg->{'CONN'}{'MAX_TRIES_PER_IP'} met een default van 10
$cfg->{'CONN'}{'BLOCK_TIME'} met een default van '60m' (60 minuten)

Bijlage:

Voorbeeld dialogen:

CMD	Betekenis	Dialoog
93	login	93<0><0>\|CN<inlog>\|CO<ww>\|AY0
99	Sc status	99<0><080><2.00>\|AY1
23	Patron status request	23<001><transactiedatum>\|AO<>\|AA<lenernr>\|AY1
63	Patron information	63<001><transactiedatum><YYYYYYYYYY>\|AO<>\|AA<klantnr>\|BP<000>\|BQ<999>\|AY1
09	checkin	09<N><uitleendatum><inleverdatum>\|AP<>\|AO<>\|AB<exemnr>\|AY1
11	checkout	11<Y><N><uitleendatum:18><inleverdatum:18>\|AA<klantnr>\|AB<exemnr>\|BO<N>\|BI<N>}AY1
29	Renew	29<N><N><transactiedatum><inleverdatum>\|AA<klantnr>\|AB<exemnr>\|BO<Y>\|AY2
17	Item information	17<YYYYMMDDzzzzHHMMSS>\|AB<exemnr>\|AY1
35	End patron session	35<transactiedatum>\|AA<klantnr>\|AY1