1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
Workflow
--------
This section shows some possible workflows as an example
communication between your application and the |AppName|.
The JSON structure can be identified by parameter **cmd**
or parameter **msg** as described in section :doc:`commands`
and section :doc:`messages`.
- **cmd**: Commands are sent by your application.
- **msg**: Messages are sent by the |AppName|.
Minimal successful authentication
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following messages and commands are the minimal
iterations of a successful authentication.
We assume that the user already inserted a card
into the connected card reader.
.. code-block:: json
{"cmd": "RUN_AUTH", "tcTokenURL": "https://test.governikus-eid.de/AusweisAuskunft/WebServiceRequesterServlet"}
{"msg": "AUTH"}
{"msg": "ACCESS_RIGHTS", "chat": {"effective":["FamilyName","GivenNames","DocumentType"],"optional":["GivenNames"],"required":["FamilyName","DocumentType"]}}
{"cmd": "ACCEPT"}
{"msg": "ENTER_PIN", "reader": {"attached":true,"card":{"inoperative":false,"deactivated":false,"retryCounter":3},"keypad":false,"name":"NFC"}}
{"cmd": "SET_PIN", "value": "123456"}
{"msg": "AUTH","result": {"major":"http://www.bsi.bund.de/ecard/api/1.1/resultmajor#ok"},"url":"https://test.governikus-eid.de/DEMO/?refID=123456"}
Successful authentication with CAN
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following messages and commands show possible
iterations if the user enters an incorrect PIN and CAN twice
before entering the correct CAN and PIN.
We assume that the user did not insert a card
into the connected card reader.
.. code-block:: json
{"cmd": "RUN_AUTH", "tcTokenURL": "https://test.governikus-eid.de/DEMO"}
{"msg": "AUTH"}
{"msg": "ACCESS_RIGHTS", "chat": {"effective":["DocumentType"],"optional":[],"required":["DocumentType"]}}
{"cmd": "ACCEPT"}
{"msg": "INSERT_CARD"}
{"msg": "ENTER_PIN", "reader": {"attached":true,"card":{"inoperative":false,"deactivated":false,"retryCounter":3},"keypad":false,"name":"NFC"}}
{"cmd": "SET_PIN", "value": "000000"}
{"msg": "ENTER_PIN", "reader": {"attached":true,"card":{"inoperative":false,"deactivated":false,"retryCounter":2},"keypad":false,"name":"NFC"}}
{"cmd": "SET_PIN", "value": "000001"}
{"msg": "ENTER_CAN", "reader": {"attached":true,"card":{"inoperative":false,"deactivated":false,"retryCounter":1},"keypad":false,"name":"NFC"}}
{"cmd": "SET_CAN", "value": "000000"}
{"msg": "ENTER_CAN", "reader": {"attached":true,"card":{"inoperative":false,"deactivated":false,"retryCounter":1},"keypad":false,"name":"NFC"}}
{"cmd": "SET_CAN", "value": "654321"}
{"msg": "ENTER_PIN", "reader": {"attached":true,"card":{"inoperative":false,"deactivated":false,"retryCounter":1},"keypad":false,"name":"NFC"}}
{"cmd": "SET_PIN", "value": "123456"}
{"msg": "AUTH","result": {"major":"http://www.bsi.bund.de/ecard/api/1.1/resultmajor#ok"},"url":"https://test.governikus-eid.de/DEMO/?refID=123456"}
Cancelled authentication
^^^^^^^^^^^^^^^^^^^^^^^^
The following messages and commands show possible
iterations if the user cancels the authentication.
We assume that the user did not connect the card reader.
.. code-block:: json
{"cmd": "RUN_AUTH", "tcTokenURL": "https://test.governikus-eid.de/DEMO"}
{"msg": "AUTH"}
{"msg": "ACCESS_RIGHTS", "chat": {"effective":["DocumentType"],"optional":[],"required":["DocumentType"]}}
{"cmd": "CANCEL"}
{"msg": "AUTH", "result": {"description":"The process has been cancelled.","language":"en","major":"http://www.bsi.bund.de/ecard/api/1.1/resultmajor#error","message":"The process has been cancelled.","minor":"http://www.bsi.bund.de/ecard/api/1.1/resultminor/sal#cancellationByUser"},"url":"https://test.governikus-eid.de/DEMO/?errID=123456"}
Set some access rights
^^^^^^^^^^^^^^^^^^^^^^
The following messages and commands show possible
iterations if the user disables and enables an access right.
We assume that the user did not connect the card reader.
.. code-block:: json
{"cmd": "RUN_AUTH", "tcTokenURL": "https://test.governikus-eid.de/DEMO"}
{"msg": "AUTH"}
{"msg": "ACCESS_RIGHTS", "chat": {"effective":["FamilyName","GivenNames","DocumentType"],"optional":["GivenNames"],"required":["FamilyName","DocumentType"]}}
{"cmd": "SET_ACCESS_RIGHTS", "chat": []}
{"msg": "ACCESS_RIGHTS", "chat": {"effective":["FamilyName","DocumentType"],"optional":["GivenNames"],"required":["FamilyName","DocumentType"]}}
{"cmd": "SET_ACCESS_RIGHTS", "chat": ["GivenNames"]}
{"msg": "ACCESS_RIGHTS", "chat": {"effective":["FamilyName","GivenNames","DocumentType"],"optional":["GivenNames"],"required":["FamilyName","DocumentType"]}}
{"cmd": "CANCEL"}
{"msg": "AUTH", "result": {"description":"The process has been cancelled.","language":"en","major":"http://www.bsi.bund.de/ecard/api/1.1/resultmajor#error","message":"The process has been cancelled.","minor":"http://www.bsi.bund.de/ecard/api/1.1/resultminor/sal#cancellationByUser"},"url":"https://test.governikus-eid.de/DEMO/?errID=123456"}
Minimal successful PIN change
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following messages and commands are the minimal
iterations of a successful PIN change.
We assume that the user already inserted a card
into the connected card reader.
.. code-block:: json
{"cmd": "RUN_CHANGE_PIN"}
{"msg": "CHANGE_PIN"}
{"msg": "ENTER_PIN", "reader": {"attached":true,"card":{"inoperative":false,"deactivated":false,"retryCounter":3},"keypad":false,"name":"NFC"}}
{"cmd": "SET_PIN", "value": "123456"}
{"msg": "ENTER_NEW_PIN", "reader": {"attached":true,"card":{"inoperative":false,"deactivated":false,"retryCounter":3},"keypad":false,"name":"NFC"}}
{"cmd": "SET_NEW_PIN", "value": "123456"}
{"msg": "CHANGE_PIN", "success": true}
|
