========= API v1.0 ========= .. warning:: This api is in development. Changes can and will be made without notice. The base url is: https://sgauth.intemo.com/ .. |HOST| replace:: https://sandgrain.intemo.com Routing table ============= :ref:`routingtable` Authentication API ================== The authentication api can be invoked by client to verify if credentials are ok. This is typically invoked by mosquitto (mosquitto-go-auth plugin). mosquitto --------- This api implements the http interface of `mosquitto-go-auth `_ See table below for configuration items =========================== ================================ config item value =========================== ================================ auth_opt_backends `http` auth_opt_http_host `sgauth.intemo.com` auth_opt_http_port `443` auth_opt_http_getuser_uri `/api/1.0/auth/mqtt/getuser` auth_opt_http_aclcheck_uri `/api/1.0/auth/mqtt/aclcheck` auth_opt_http_superuser_uri `/api/1.0/auth/mqtt/superuser` auth_opt_http_with_tls `true` auth_opt_http_response_mode `status` auth_opt_http_params_mode `json` auth_opt_http_timeout `2` =========================== ================================ getuser ------- .. http:post:: /api/1.0/auth/mqtt/getuser :synopsis: Authenticate user This is the `auth_opt_http_getuser_uri` url that mosquitto-go-auth invokes. **Example request**: .. sourcecode:: http POST /api/1.0/auth/mqtt/getuser HTTP/1.1 Host: sgauth.intemo.com Content-Type: application/json { "clientid": "auto-E0CC51DE-815E-3502-0BF4-7796C60893BB", "password": "test", "username": "test" } **Example response**: .. sourcecode:: http HTTP/1.1 201 CREATED **Example response**: .. sourcecode:: http HTTP/1.1 401 Unauthorized : t: SPI: Read identification\n(mode 1) t -> d: pccid d -> api: POST ek-init\n{pccid} api -> cb: POST ekRequestCW cb -> api: tid, cw api -> d: tid, cw d -> t: SPI: cw (mode 7) t-> d: ek, rw d->api: POST ek-fin\n{pccid, cw, rw, tid}\n{meta: username, client-id, ...} api -> cb: POST ekReplyRW cb -> api: tid api -> cb: GET ekCheckAuthStatus cb -> api: ek api -> db: store username\nclient-id api -> db: Store ek\nhashed api -> d: HTTP/1.1 201 d->d: store ek Setting up an mqtt connection is shown in the sequence diagrom below. Note that establishing an mqtt connection does not involve the sandgrain token (on the device), nor the cyberrock api. It uses the shared secret (ek) stored in the device, and stored hashed in sgauth. .. uml:: :align: center title setup mqtt connection participant "IOT device" as d participant "MQTT server" as m participant sgauth as api database "sgauth db" as db d -> d: read ek as password d -> d: read username, clientid d -> m: connect\nusername, clientid, password m->api: POST getuser\nusername,clientid, password api -> db: validate username, clientid, password api->m: HTTP 201 note right: 20X means allowed m-> d: connection established d-> m: subscribe topic m-> api: POST aclcheck\nusername,clientid, topic api->db: Check acl rules api->m: HTTP 201 m->d: subscribed Initiate EK ----------- .. http:post:: /api/1.0/iot/ek-init :synopsis: Start EK exchange Initiate an ephemeral key exchange Nodes, Schedules all belong to an organization. **Example request**: .. sourcecode:: http POST /api/1.0/iot/ek-init HTTP/1.1 Host: sgauth.intemo.com Content-Type: application/json Authentication: Basic dXNlcjpzZWNyZXQ= { "sg": { "pccid": "800000000000000000000000000000188d7aa5f9036480c8aa62f400023f2faa" } } **Example response**: .. sourcecode:: http HTTP/1.1 201 OK Content-Type: application/json; charset=utf-8 { "sg": { "cw": "93ceada15860e236d36a90398596e18879c785aa06aa03aab1db27a6da6939fd", "tid": "411fbdb2-b2df-4ef9-a953-4a823ef471a1" } } **Example response**: .. sourcecode:: http HTTP/1.1 503 Service Unavailable :query pretty: bool: if true, json will we returned pretty formatted :json str cw: sandgrain challenge word, 32 bytes, hex encoded :>json str tid: sandgrain transaction id, must be sent in next ek-fin api call :status 201: OK :status 401: Login or credentials required (http basic auth failed) :status 403: Authorization error (sandgrain error, or internal api error) :status 503: Upstream server (sandgrain cyberrock) is down/not responding .. _finalize_ek: Finalize EK ----------- .. http:post:: /api/1.0/iot/ek-fin :synopsis: Finalize EK exchange Finalize an ephemeral key exchange. And optionally store meta data (if authentication succeeded). After this call, both the api caller (device), and the api (agauth) know a shared secret (ephemeral key). The device should store this in non volatile memory. sgauth will store this secret hashed, so that it can do password validations on it. **Example request**: .. sourcecode:: http POST /api/1.0/iot/ek-fin HTTP/1.1 Host: sgauth.intemo.com Content-Type: application/json Authentication: Basic dXNlcjpzZWNyZXQ= { "sg": { "pccid": "800000000000000000000000000000188d7aa5f9036480c8aa62f400023f2faa", "cw": "93ceada15860e236d36a90398596e18879c785aa06aa03aab1db27a6da6939fd", "tid": "411fbdb2-b2df-4ef9-a953-4a823ef471a1", "rw": "410eeed408ae7c482128f1b279f79f46", }, "meta": { "username": "8d7aa5f9036480c8aa62f400023f2faa", "client-id": "0004A30B01668119", "product": "cityzenz-connect", "serial": "20251200123", "board": "CZ-STM32-17A", "revision": "2A03", "firmware": "1.2.3-1-ga807e57", "location": {"latitude": 51.23, "longitude": 5.17} } } **Example response**: .. sourcecode:: http HTTP/1.1 201 CREATED { "status":"ok" } **Example response**: .. sourcecode:: http HTTP/1.1 403 FORBIDDEN { "status": "fail", "details": "sandgrain auth error" } :json str cw: sandgrain challenge word, received from matching ik-init api call : :synopsis: Update metadata Update or create metadata. **Example request**: .. sourcecode:: http POST /api/1.0/iot/meta/8d7aa5f9036480c8aa62f400023f2faa HTTP/1.1 Host: sgauth.intemo.com Content-Type: application/json Authentication: Basic dXNlcjpzZWNyZXQ=, Bearer { "meta": { "client-id": "0004A30B01668119", "product": "cityzenz-connect", "serial": "20251200123", "board": "CZ-STM32-17A", "revision": "2A03", "firmware": "1.2.3-1-ga807e57", "location": {"latitude": 51.23, "longitude": 5.17} } } **Example response**: .. sourcecode:: http HTTP/1.1 201 CREATED :reqheader Authorization: Bearer + shared secret as exchanged in :ref:`finalize_ek`) :param id: sandgrain id (right 16 bytes of pccid) :query pretty: bool: if true, json will we returned pretty formatted :