1. No category

Krediidipanga Internetipangas realiseeritud “Pangalingi” päringute
tehniline kirjeldus.
Dokument viimati
muudetud:
16.10.2014
Krediidipanga internetipangas (https://i-pank.krediidipank.ee/) on hetkel realiseeritud
järgmised nn. “Pangalingi” päringud.
1. Autentimine: Portaal → Pank → Portaal
a. Ajapitserist sõltumatu lahendus (4012->3013)
Portaal
Kasutaja
Pank
1: portaali sisenemine
2: Autentimismeetodi valik
3: Valik: Autentimine panga kaudu
4: 4012 genereerimine (sh. nons)
5: 4012 signeerimine
6: Signeeritud 4012 kasutajale
7: Signeeritud 4012 kasutajalt panka läbi turvakanali (HTTPS)
8: 4012 signatuuri kontroll
9: Isiku tuvastamise päring
10: Kasutaja vastus päringule
11: Kasutaja ja 4012 põhjal vastus 3013
12: Vastuse 3013 signeerimine
13: Signeeritud 3013 kasutajale
14: HTTPS kaudu 3013 portaali
15: 3013 Signatuuri kontroll
16: 3013 Nonsi kontroll
17: 3013 Isikukoodi kontroll
18: Sessiooni loomine
19: Autenditud kasutaja sessioon
Joonis 1. Autentimise mudel: Portaal → Pank → Portaal: ajapitserist sõltumatu lahendus
b. Ajapitserist sõltuv lahendus (4011->3012)
Portaal
Kasutaja
Pank
1: portaali sisenemine
2: Autentimismeetodi valik
3: Valik: Autentimine panga kaudu
4: 4011 genereerimine
5: 4011 signeerimine
6: Signeeritud 4011 kasutajale
7: Signeeritud 4011 kasutajalt panka läbi turvakanali (HTTPS)
8: 4011 signatuuri kontroll
+ Ajapitseri kontroll
9: Isiku tuvastamise päring
10: Kasutaja vastus päringule
11: Kasutaja ja 4011 põhjal vastus 3012
12: Vastuse 3012 signeerimine
13: Signeeritud 3012 kasutajale
14: HTTPS kaudu 3012 portaali
15: 3012 Signatuuri kontroll
16: 3012 Ajapitseri kontroll
17: 3012 Isikukoodi kontroll
18: Sessiooni loomine
19: Autenditud kasutaja sessioon
Joonis 2. Autentimise mudel: Portaal → Pank → Portaal: ajapitserist sõltuv lahendus
Autentimispäringu 4011 väljad:
URL: https://i-pank.krediidipank.ee/auth
Jrk.
1
2
3
4
5
6
7
-
Välja nimi
VK_SERVICE
VK_VERSION
VK_SND_ID
VK_REPLY
VK_RETURN
VK_DATETIME
VK_RID
VK_MAC
VK_ENCODING
VK_LANG
Pikkus
4
3
15
4
255
24
30
700
12
3
Kirjeldus
Teenuse number (4011)
Kasutatav krüptoalgoritm (008)
Sõnumi koostaja (partneri) ID
Oodatava vastuspaketi kood (3012)
Kaupmehe URL, kuhu vastatakse
Sõnumi genereerimise aeg DATETIME formaadis
Sessiooniga seotud identifikaator
Kontrollkood e. allkiri
Sõnumi kodeering. ISO-8859-1 või UTF-8 või WINDOWS-1257
Soovitav suhtluskeel (EST, ENG või RUS)
Autentimispäringu 4012 väljad:
URL: https://i-pank.krediidipank.ee/auth
Jrk.
1
2
3
4
5
6
7
8
-
Välja nimi
VK_SERVICE
VK_VERSION
VK_SND_ID
VK_REC_ID
VK_NONCE
VK_RETURN
VK_DATETIME
VK_RID
VK_MAC
VK_ENCODING
VK_LANG
Pikkus
4
3
15
15
50
255
24
30
700
12
3
Kirjeldus
Teenuse number (4012)
Kasutatav krüptoalgoritm (008)
Sõnumi koostaja (partneri) ID
Sõnumi saaja (panga) ID
Päringu koostaja poolt genereeritud juhuslik nonss
Kaupmehe URL, kuhu vastatakse
Sõnumi genereerimise aeg DATETIME formaadis
Sessiooniga seotud identifikaator
Kontrollkood e. allkiri
Sõnumi kodeering. ISO-8859-1 või UTF-8 või WINDOWS-1257
Soovitav suhtluskeel (EST, ENG või RUS)
Autentimisvastuse 3012 väljad:
Jrk.
1
2
3
4
5
6
7
8
9
10
11
Välja nimi
VK_SERVICE
VK_VERSION
VK_USER
VK_DATETIME
VK_SND_ID
VK_REC_ID
VK_USER_NAME
VK_USER_ID
VK_COUNTRY
VK_OTHER
VK_TOKEN
Pikkus
4
3
16
24
15
15
140
20
2
150
2
12
-
VK_RID
VK_MAC
VK_ENCODING
VK_LANG
30
700
12
3
Kirjeldus
Teenuse number (3012)
Kasutatav krüptoalgoritm (008)
Kokkuleppeline kasutaja identifikaator
Sõnumi genereerimise aeg DATETIME formaadis
Sõnumi koostaja ID (Panga ID)
Sõnumi saaja (partneri) ID
Kasutaja nimi
Kasutaja isikukood
Isikukoodi riik (kahetäheline ISO 3166-1)
Muu info kasutaja kohta
Autentimisvahendi identifikaatori kood:
1- ID-kaart; 2- Mobiil-ID; 5- ühekordsed koodid (v.a. PINkalkulaator); 6- PIN-kalkulaator; 7- korduvkasutusega kaart
Sessiooniga seotud identifikaator
Kontrollkood e. allkiri
Sõnumi kodeering. ISO-8859-1 või UTF-8 või WINDOWS-1257
Soovitav suhtluskeel (EST, ENG või RUS)
Autentimisvastuse 3013 väljad:
Jrk.
1
2
3
4
5
6
7
8
9
10
11
Välja nimi
VK_SERVICE
VK_VERSION
VK_DATETIME
VK_SND_ID
VK_REC_ID
VK_NONCE
VK_USER_NAME
VK_USER_ID
VK_COUNTRY
VK_OTHER
VK_TOKEN
Pikkus
4
3
24
15
15
50
140
20
2
150
2
12
-
VK_RID
VK_MAC
VK_ENCODING
VK_LANG
30
700
12
3
Kirjeldus
Teenuse number (3013)
Kasutatav krüptoalgoritm (008)
Sõnumi genereerimise aeg DATETIME formaadis
Sõnumi koostaja ID (Panga ID)
Sõnumi saaja (partneri) ID
Päringus olnud nonssi koopia
Kasutaja nimi
Kasutaja isikukood
Isikukoodi riik (kahetäheline ISO 3166-1)
Muu info kasutaja kohta
Autentimisvahendi identifikaatori kood:
1- ID-kaart; 2- Mobiil-ID; 5- ühekordsed koodid (v.a. PINkalkulaator); 6- PIN-kalkulaator; 7- korduvkasutusega kaart
Sessiooniga seotud identifikaator
Kontrollkood e. allkiri
Sõnumi kodeering. ISO-8859-1 või UTF-8 või WINDOWS-1257
Soovitav suhtluskeel (EST, ENG või RUS)
** Juhul kui VK_ENCODING väli puudub, siis teisendatakse kõikides vastuse
tekstiväljades ISO-8859-1 kooditabelis kõrgemal kui kood 128 olevad
sümbolid järgnevalt: eesti keele täpitähed vastavateks täppideta analoogiks (nt
Ä->A ja Š->S) ja muud eemaldatakse.
Portaal genereerib kasutaja poolt valitud panga jaoks sõnumi 4012 (4) ja signeerib
selle (5). Samaaegselt salvestatakse genereeritud sõnum ka vahetabelisse.
Genereeritud ja signeeritud sõnum 4012 saadetakse ootavale kasutajale (6), kus
kuvatakse nupp Autendime mispeale suunatakse kasutaja edasi internetipanka (7).
Asjakohane näide on ära toodud lisas 3 – HTTP(S) kanali kasutamine.
Pank, pärast signatuuri kontrolli (8) palub kasutajal ennast sisse logida (9). Kui
kasutaja on edukalt panka sisenenud (10), siis koostab pank vastussõnumi: 3013 (11).
Sarnaselt sõnumile 4012 see signeeritakse (12) ning edastatakse kasutajale (13),
misjärel viimane suunatakse tagasi Portaali (14).
Portaal kontrollib edastatud sõnumi signatuuri (15). Kui signatuur on tõene, siis
kontrollitakse, kas vastus 3013 on saabunud eelnevalt saadetud sõnumile (4012)
etteantud ajaliimid piires (16) ja seejärel vaadatakse, kas antud kasutaja isikukood on
kasutusel (17). Portaal kasutab klientide identifikaatorina isikukoodi.
2. Autenditud sisenemine: Pank → Portaal
Kasutaja
Portaal
Pank
1: internetipanka sisenemine
2: Isiku tuvastamise päring läbi turvalise sidekanali HTTPS.
3: Kasutaja vastus päringule (HTTPS)
4: Teenuse valik (HTTPS)
5: Valik: Soovin siseneda Portaali (HTTPS)
6: Kasutaja info põhjal sõnum 3012
7: Vastuse 3012 signeerimine
8: Signeeritud 3012 kasutajale (HTTPS)
9: HTTPS kaudu 3012 portaali
10: 3012 Signatuuri kontroll
11: 3012 Ajapitseri kontroll
12: 3012 Isikukoodii kontroll
13: Sessiooni loomine
14: Autenditud kasutaja sessioon
Joonis 3. Autentinditud sisenemise mudel: Pank → Portaal
Autentimissõnumi 3012 väljad:
Jrk.
1
2
3
4
5
6
7
8
9
10
11
Välja nimi
VK_SERVICE
VK_VERSION
VK_USER
VK_DATETIME
VK_SND_ID
VK_REC_ID
VK_USER_NAME
VK_USER_ID
VK_COUNTRY
VK_OTHER
VK_TOKEN
Pikkus
4
3
16
24
15
15
140
20
2
150
2
12
-
VK_RID
VK_MAC
VK_ENCODING
VK_LANG
30
700
12
3
Kirjeldus
Teenuse number (3012)
Kasutatav krüptoalgoritm (008)
Kokkuleppeline kasutaja identifikaator
Sõnumi genereerimise aeg DATETIME formaadis
Sõnumi koostaja ID (Panga ID)
Sõnumi saaja (partneri) ID
Kasutaja nimi
Kasutaja isikukood
Isikukoodi riik (kahetäheline ISO 3166-1)
Muu info kasutaja kohta
Autentimisvahendi identifikaatori kood:
1- ID-kaart; 2- Mobiil-ID; 5- ühekordsed koodid (v.a. PINkalkulaator); 6- PIN-kalkulaator; 7- korduvkasutusega kaart
Sessiooniga seotud identifikaator
Kontrollkood e. allkiri
Sõnumi kodeering. ISO-8859-1 või UTF-8 või WINDOWS-1257
Soovitav suhtluskeel (EST, ENG või RUS)
Kasutaja pöördub panka (1). Pank palub kasutajal ennast identifitseerida (2). Pärast
positiivset kasutajatunnuste sisestamist (3) pakutakse kasutajale võimalust kasutada
erinevaid pangateenuseid (4), millest üks on sisenemine Portaali (5).
Pärast seda, kui kasutaja on teavitanud panka, et ta soovib kasutada Portaali teenuseid,
produtseerib pank sõnumi 3012 (6), mis signeeritakse (7) ja saadetakse kasutaja
brauseri päise kaudu (8) edasi Portaali (9). Seejärel jätkub tegevus juba sarnaselt
meetodis 1 kirjeldatud teed pidi.
Peab siiski märkima, et Ajapitseri kontrollimine käib selles meetodis mõnevõrra
teistmoodi: erinevalt eelmisest meetodist, ei saadeta kontrollaega päringuga 4012,
vaid selle genereerib pank. Kui panga ja Portaali serverikellaaegade erinevus läheb
piisavalt suureks, siis võib tekkida olukord, et tühistatakse kõik sisenemised, mis on
saabunud sellest ettevõttest. Et seda vältida, valivad Portaal ja Pank aja
sünkroniseerimiseks ühe Internetis ajastandardi teenust pakkuvatest institutsioonidest,
kelle tuumakella loetakse sõnumi ajapitseri (VK_TIME ja VK_DATE) koostamisel
kohustuslikuks.
3. Makse teostamine: Portaal → Pank → Portaal.
Portaal
Kasutaja
Pank
1: portaali sisenemine
2: Maksemeetodi valik
3: Valik: Maksame panga kaudu
4: 1012 (või 1011) genereerimine
5: 1012 (või 1011) signeerimine
6: Signeeritud 1012 (või 1011) kasutajale
7: Signeeritud 1012 (või 1011) kasutajalt panka läbi turvakanali (HTTPS)
8: 1012 (või 1011) signatuuri kontroll
9: Isiku tuvastamise päring
10: Kasutaja vastus päringule
11. Makse kuvamine kasutajale ja selle
teostaminevõi teostamisest loobumine
12: Makse teostamisele vastavalt vastus 1111 või 1911
13: Vastuse signeerimine
14: Signeeritud maksevastus kasutajale
15: Vastus HTTPS kaudu
Portaalile
16: Vastuse Signatuuri kontroll
17: Vastuskoodi kontroll
18: Eduka makse korral kauba või
teenuse väljastamine
Joonis 4. Makse teostamise mudel internetipanga kaudu: Portaal → Pank → Portaal
Makse algatamise päringu 1012 väljad:
URL: https://i-pank.krediidipank.ee/pay
Jrk.
1
2
3
4
5
6
7
8
9
10
11
-
Välja nimi
VK_SERVICE
VK_VERSION
VK_SND_ID
VK_STAMP
VK_AMOUNT
VK_CURR
VK_REF
VK_MSG
VK_RETURN
VK_CANCEL
VK_DATETIME
VK_MAC
VK_ENCODING
Pikkus
4
3
15
20
12
3
35
95
255
255
24
700
12
Kirjeldus
Teenuse number (1012)
Kasutatav krüptoalgoritm (008)
Päringu koostaja ID (Kaupluse ID)
Päringu ID
Maksmisele kuuluv summa
Valuuta nimi: EUR
Maksekorralduse viitenumber
Maksekorralduse selgitus
URL, kuhu vastatakse edukal tehingu sooritamisel
URL, kuhu vastatakse ebaõnnestunud tehingu puhul
Päringu algatamise kuupäev ja kellaaeg DATETIME formaadis
Kontrollkood e. allkiri
Sõnumi kodeering. ISO-8859-1 või UTF-8 või WINDOWS-1257
-
VK_LANG
3
Soovitav suhtluskeel (EST, ENG või RUS)
Makse algatamise päringu 1011 väljad:
URL: https://i-pank.krediidipank.ee/pay
Jrk.
1
2
3
4
5
6
7
8
9
10
11
12
13
-
Välja nimi
VK_SERVICE
VK_VERSION
VK_SND_ID
VK_STAMP
VK_AMOUNT
VK_CURR
VK_ACC
VK_NAME
VK_REF
VK_MSG
VK_RETURN
VK_CANCEL
VK_DATETIME
VK_MAC
VK_ENCODING
VK_LANG
Pikkus
4
3
15
20
12
3
34
70
35
95
255
255
24
700
12
3
Kirjeldus
Teenuse number (1011)
Kasutatav krüptoalgoritm (008)
Päringu koostaja ID (Kaupluse ID)
Päringu ID
Maksmisele kuuluv summa
Valuuta nimi: EUR
Saaja konto number
Saaja nimi
Maksekorralduse viitenumber
Maksekorralduse selgitus
URL, kuhu vastatakse edukal tehingu sooritamisel
URL, kuhu vastatakse ebaõnnestunud tehingu puhul
Päringu algatamise kuupäev ja kellaaeg DATETIME formaadis
Kontrollkood e. allkiri
Sõnumi kodeering. ISO-8859-1 või UTF-8 või WINDOWS-1257
Soovitav suhtluskeel (EST, ENG või RUS)
Makse eduka teostamise vastuse 1111 väljad:
Jrk.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
-
Välja nimi
VK_SERVICE
VK_VERSION
VK_SND_ID
VK_REC_ID
VK_STAMP
VK_T_NO
VK_AMOUNT
VK_CURR
VK_REC_ACC
VK_REC_NAME
VK_SND_ACC
VK_SND_NAME
VK_REF
VK_MSG
VK_T_DATETIME
VK_MAC
VK_ENCODING
VK_LANG
VK_AUTO
Pikkus
4
3
15
15
20
20
12
3
34
70
34
70
35
95
24
700
12
3
1
Kirjeldus
Teenuse number (1111)
Kasutatav krüptoalgoritm 008
Päringu koostaja ID (Panga ID)
Päringu vastuvõtja ID (Kaupluse ID)
Päringu ID
Maksekorralduse number
Makstud summa
Valuuta nimi: EUR
Saaja konto number
Saaja nimi
Maksja konto number
Maksja nimi
Maksekorralduse viitenumber
Maksekorralduse selgitus
Maksekorralduse kuupäev ja kellaaeg DATETIME formaadis
Kontrollkood e. allkiri
Sõnumi kodeering. ISO-8859-1 või UTF-8 või WINDOWS-1257
Soovitav suhtluskeel (EST, ENG või RUS)
Y = panga poolt automaatselt saadetud vastus.
N = vastus kliendi liikumisega kaupmehe lehele
Makse ebaõnnestunud teostamise vastuse 1911 väljad:
Jrk.
1
2
3
4
5
6
7
-
Välja nimi
VK_SERVICE
VK_VERSION
VK_SND_ID
VK_REC_ID
VK_STAMP
VK_REF
VK_MSG
VK_MAC
VK_ENCODING
Pikkus
4
3
15
15
20
35
95
700
12
Kirjeldus
Teenuse number (1911)
Kasutatav krüptoalgoritm (008)
Päringu koostaja ID (Panga ID)
Päringu vastuvõtja ID (Kaupluse ID)
Päringu ID
Maksekorralduse viitenumber
Maksekorralduse selgitus
Kontrollkood e. allkiri
Sõnumi kodeering. ISO-8859-1 või UTF-8 või WINDOWS-1257
-
VK_LANG
VK_AUTO
3
1
Soovitav suhtluskeel (EST, ENG või RUS)
Y = panga poolt automaatselt saadetud vastus.
N = vastus kliendi liikumisega kaupmehe lehele
* Juhul kui VK_ENCODING väli puudub, siis teisendatakse kõikides vastuse
tekstiväljades ISO-8859-1 kooditabelis kõrgemal kui kood 128 olevad
sümbolid järgnevalt: eesti keele täpitähed vastavateks täppideta analoogiks (nt
Ä->A ja Š->S) ja muud eemaldatakse.
Kaupmees saadab (7) kliendi päringuga panka allkirjastatud maksekorralduse
andmed, mida klient internetipangas muuta ei saa. Makse saaja nimi ja konto number
võtab pank panga ja kaupmehe vahelisest lepingust.
Peale edukat makset koostatakse kaupmehele päring "1111" (12), ebaõnnestunud
makse puhul pakett "1911". Internetipanga server püüab alati oma serverist saata ka
vastuse rezhiimiga VK_AUTO=’Y’, seda juhtudeks kui kliendi seanss katkeb või
klient ei liigu korrektselt tagasi kaupmehe veebileheküljele.
Lisa 1. Päringuväljade spetsifikatsioon
 Kõiki lisades 1 ja 2 toodud väljanimesid tuleb võtta kui HTTP GET või POST
muutujaid.
 Päringutes esitatud summades on komakohad ja sendid eristatud punktiga "."
Tuhandete eraldajat ei kasutata.
 Kuupäevad ja kellaajad esitatakse DATETIME formaadis sekundi täpsusega
nt 2013-03-13T07:21:14+0200 Päringu saaja on kohustatud kontrollima
DATETIME väljal olevat väärtust, kusjuures välja väärtus tohib erineda
kontrollimise hetkel kehtivast kellaajast maksimaalselt ± 5 minutit.
 Välja väärtuse pikkus ei tohi ületada spetsifikatsioonis ettenähtut. Välja
väärtuse maksimumpikkused on sümbolites. Välja väärtus võib olla lühem kui
maksimaalne pikkus lubab.
 Spetsifikatsioonile mittevastavatele päringutele vastatakse veateatega.
 Väljal VK_RETURN ei ole lubatud kasutada pangalingi päringutes
kasutatavaid välja nimesid (VK_...)
Lisa 2. Kontrollkoodi VK_MAC leidmine
Päringutes kasutatava elektroonse allkirja, vk_mac, kontroll toimub kokkuleppelise
algoritmi, vk_version, alusel. Praegu on kasutusel versioon 008. Ei kasutata enam
versioone 001, 002 ja 007. Koos uute meetodite leiutamisega maailmas võib ka
allkirjastamise algoritm tulevikus muutuda.
VK_MAC esitatakse päringu parameetri väärtusena BASE64 kodeeringus.
Kodeerimine VK_VERSION=008 puhul:
VK_MAC arvutatakse vastavalt RSA algoritmile ning viiakse seejärel üle BASE64
kodeeringusse.
VK_MAC väärtus arvutatakse kasutades avaliku võtme algoritmi RSA. Arvestatakse
ka tühjade väljade pikkusi – “000”. Ei signeerita päringute järjekorrastamata
lisaväljasid.
MAC(x1,x2,…,xn) := RSA( SHA-1(p(x1 )|| x1|| p(x2 )|| x2 || … ||p( xn )||xn),d,n)
kus:
|| on stringi liitmise tehe
x1, x2, …, xn on päringu parameetrid
p on funktsioon parameetri pikkusest. Pikkus on number kolmekohalise stringi kujul
d on RSA salajane eksponent
n on RSA modulus
Lisa 3. HTTP(S) kanali kasutamise näide.
Kuna nii päringu, kui vastuse saamine/saatmine on ideoloogiliselt identsed, siis
peatume näitena pikemalt vaid meetodi 4012 saatmisel ja vastuvõtmisel:
HTMLi algus
Järgnevas reas on näha, et pärast nupuvajutust suunatakse kasutaja
koos hidden väljadesse talletatud informatsiooniga aadressil
https://i-pank.krediidipank.ee/ asuvale leheküljele/programmile
nimega /auth
<form method=”get”
action=”https://i-pank.krediidipank.ee/auth”>
<input type=”hidden” name=”VK_SERVICE” value=”4012”>
<input type=”hidden” name=”VK_VERSION” value=”008”>
<input type=”hidden” name=”VK_SND_ID” value=”PORTAAL”>
. . .
<input type=”submit” value=”Autendi internetipangas”>
</form>
Ülejäänud HTML
Krediidipanga server võtab hidden väljade kaudu Portaalist saadetud andmed vastu,
ning alustab nende töötlemist. Vastus saadetakse pangast identse meetodiga.