diff --git a/docs/hafas-mgate-api.md b/docs/hafas-mgate-api.md index 21afc1de..5c5f641f 100644 --- a/docs/hafas-mgate-api.md +++ b/docs/hafas-mgate-api.md @@ -60,6 +60,30 @@ In many aspects, the API looks and feels like [RPCs](https://en.wikipedia.org/wi For working code, check out [`request()`](lib/request.js). +## Authentication + +There are three known types of authentication used among `mgate.exe` endpoints. + +For working code, check out [`hafas-client`'s `request()`](lib/request.js), [`public-transport-enabler`'s Java implementation](https://github.com/schildbach/public-transport-enabler/blob/69614c87af627e2feafc576882f2ccccdbf4b7e6/src/de/schildbach/pte/AbstractHafasClientInterfaceProvider.java#L845-L860), [`TripKit`'s Swift implementation](https://github.com/alexander-albers/tripkit/blob/724b6cd8c258c9c61e7443c81e914618b79393cb/TripKit/AbstractHafasClientInterfaceProvider.swift#L1473-L1495) or [`marudor.de`'s TypeScript implementation](https://github.com/marudor/BahnhofsAbfahrten/blob/cf64d53c6902981ec529d3952253b2c83bff9221/src/server/HAFAS/profiles.ts#L30-L54). + +### unprotected endpoints + +You can just query these, as long as you send a formally correct request. + +### endpoints using the `checksum` query parameter + +`checksum` is a [message authentication code](https://en.wikipedia.org/wiki/Message_authentication_code): You can compute it by [hashing](https://en.wikipedia.org/wiki/Hash_function) the request body and a secret *salt*. + +This secret can be read from the config file inside the accompanying client app. There is no guide for this yet, so please [open an issue](https://github.com/public-transport/hafas-client/issues/new). + +### endpoints using the `mic` & `mac` query parameters + +`mic` is a [message integrity code](https://en.wikipedia.org/wiki/Message_authentication_code), the [hash](https://en.wikipedia.org/wiki/Hash_function) of the request body. + +`mac` is a [message authentication code](https://en.wikipedia.org/wiki/Message_authentication_code), the hash of `mic` and a secret *salt*. + +This secret can be read from the config file inside the accompanying client app. There is no guide for this yet, so please [open an issue](https://github.com/public-transport/hafas-client/issues/new). + ## API responses A minimal valid response looks like this: diff --git a/docs/writing-a-profile.md b/docs/writing-a-profile.md index 80eff168..cd06fac2 100644 --- a/docs/writing-a-profile.md +++ b/docs/writing-a-profile.md @@ -80,7 +80,7 @@ You may want to start with the [profile boilerplate](profile-boilerplate.js). - **Copy the authentication** and other meta fields, namely `ver`, `ext`, `client` and `lang`. - You can find these fields in the root of each request JSON. Check [a VBB request](https://gist.github.com/derhuerst/5fa86ed5aec63645e5ae37e23e555886#file-1-http-L13-L22) and [the corresponding VBB profile](https://github.com/public-transport/hafas-client/blob/6e61097687a37b60d53e767f2711466b80c5142c/p/vbb/index.js#L22-L29) for an example. - Add a function `transformReqBody(body)` to your profile, which assigns them to `body`. - - Some profiles have a `checksum` parameter (like [here](https://gist.github.com/derhuerst/2a735268bd82a0a6779633f15dceba33#file-journey-details-1-http-L1)) or two `mic` & `mac` parameters (like [here](https://gist.github.com/derhuerst/5fa86ed5aec63645e5ae37e23e555886#file-1-http-L1)). If you see one of them in your requests, jump to [*Appendix A: checksum, mic, mac*](#appendix-a-checksum-mic-mac). Unfortunately, this is necessary to get the profile working. + - Some profiles have a `checksum` parameter (like [here](https://gist.github.com/derhuerst/2a735268bd82a0a6779633f15dceba33#file-journey-details-1-http-L1)) or two `mic` & `mac` parameters (like [here](https://gist.github.com/derhuerst/5fa86ed5aec63645e5ae37e23e555886#file-1-http-L1)). If you see one of them in your requests, jump to the [*Authentication* section of the `mgate.exe` docs](hafas-mgate-api.md#authentication). Unfortunately, this is necessary to get the profile working. ## 3. Products @@ -149,23 +149,3 @@ We consider these improvements to be *optional*: - `Berlin Jungfernheide Bhf` -> `Berlin Jungfernheide`. With local context, it's obvious that *Jungfernheide* is a train station. - **Check if the endpoint has non-obvious limitations** and let use know about these. Examples: - Some endpoints have a time limit, after which they won't return more departures, but silently discard them. - ---- - -## Appendix A: `checksum`, `mic`, `mac` - -As far as we know, there are three different types of authentication used among HAFAS deployments. - -### unprotected endpoints - -You can just query these, as long as you send a formally correct request. - -### endpoints using the `checksum` query parameter - -`checksum` is a [message authentication code](https://en.wikipedia.org/wiki/Message_authentication_code): `hafas-client` will compute it by [hashing](https://en.wikipedia.org/wiki/Hash_function) the request body and a secret *salt*. **This secret can be read from the config file inside the app bundle.** There is no guide for this yet, so please [open an issue](https://github.com/public-transport/hafas-client/issues/new) instead. - -### endpoints using the `mic` & `mac` query parameters - -`mic` is a [message integrity code](https://en.wikipedia.org/wiki/Message_authentication_code), the [hash](https://en.wikipedia.org/wiki/Hash_function) of the request body. - -`mac` is a [message authentication code](https://en.wikipedia.org/wiki/Message_authentication_code), the hash of `mic` and a secret *salt*. **This secret can be read from the config file inside the app bundle.** There is no guide for this yet, so please [open an issue](https://github.com/public-transport/hafas-client/issues/new) instead.