480 lines
13 KiB
Markdown
480 lines
13 KiB
Markdown
# Request Body Analysis - ADIF API
|
|
|
|
> Reverse engineering of package `com.adif.elcanomovil.serviceNetworking`
|
|
> Date: 2025-12-04
|
|
|
|
## Table of Contents
|
|
- [1. Authentication Headers](#1-authentication-headers)
|
|
- [2. Request Bodies](#2-request-bodies)
|
|
- [3. Endpoints and Base URLs](#3-endpoints-and-base-urls)
|
|
- [4. Network Configuration](#4-network-configuration)
|
|
- [5. Authentication System](#5-authentication-system)
|
|
- [6. Code References](#6-code-references)
|
|
|
|
---
|
|
|
|
## 1. Authentication Headers
|
|
|
|
### 1.1 Static Headers
|
|
|
|
**File:** `ServicePaths.java:67-76`
|
|
|
|
#### Circulations
|
|
```
|
|
User-key: f4ce9fbfa9d721e39b8984805901b5df
|
|
Content-Type: application/json;charset=utf-8
|
|
```
|
|
|
|
#### Stations
|
|
```
|
|
User-key: 0d021447a2fd2ac64553674d5a0c1a6f
|
|
Content-Type: application/json;charset=utf-8
|
|
```
|
|
|
|
#### AVISA (Login/Refresh)
|
|
```
|
|
Authorization: Basic YXZpc3RhX2NsaWVudF9hbmRyb2lkOjh5WzZKNyFmSjwhXypmYXE1NyNnOSohNElwa2MjWC1BTg==
|
|
```
|
|
|
|
**Decoded (Base64):**
|
|
```
|
|
avista_client_android:8y[6J7!fJ<_*faq57#g9*!4Ipkc#X-AN
|
|
```
|
|
|
|
### 1.2 Dynamic Headers (Generated by ElcanoAuth)
|
|
|
|
**File:** `serviceNetworking/interceptors/auth/ElcanoAuth.java`
|
|
|
|
The interceptor adds the X-Elcano headers produced by the HMAC calculation:
|
|
|
|
```
|
|
X-Elcano-Host: <host>
|
|
X-Elcano-Client: AndroidElcanoApp
|
|
X-Elcano-Date: <timestamp>
|
|
X-Elcano-UserId: <uuid>
|
|
Authorization: HMAC-SHA256 Credential=... SignedHeaders=... Signature=...
|
|
```
|
|
|
|
**Generation algorithm (summary):**
|
|
- Canonical headers (order matters): `content-type`, `x-elcano-host`, `x-elcano-client`, `x-elcano-date`, `x-elcano-userid`
|
|
- Canonical request: method + path + query + canonical headers + SHA256(payload)
|
|
- String to sign: `HMAC-SHA256\n<timestamp>\n<date>/<client>/<userId>/elcano_request\n<hash>`
|
|
- Signature key: HMAC(secretKey, date) → HMAC(result, client) → HMAC(result, "elcano_request")
|
|
|
|
---
|
|
|
|
## 2. Request Bodies
|
|
|
|
### 2.1 Circulations - Departures/Arrivals/Between Stations
|
|
|
|
**Endpoints:**
|
|
- `/portroyalmanager/secure/circulationpaths/departures/traffictype/`
|
|
- `/portroyalmanager/secure/circulationpaths/arrivals/traffictype/`
|
|
- `/portroyalmanager/secure/circulationpaths/betweenstations/traffictype/`
|
|
|
|
**Model:** `TrafficCirculationPathRequest`
|
|
**File:** `circulations/model/request/TrafficCirculationPathRequest.java:10-212`
|
|
|
|
```json
|
|
{
|
|
"commercialService": "YES|NOT|BOTH",
|
|
"commercialStopType": "YES|NOT|BOTH",
|
|
"destinationStationCode": "string or null",
|
|
"originStationCode": "string or null",
|
|
"page": {
|
|
"pageNumber": 0
|
|
},
|
|
"stationCode": "string or null",
|
|
"trafficType": "CERCANIAS|AVLDMD|OTHERS|TRAVELERS|GOODS|ALL"
|
|
}
|
|
```
|
|
|
|
#### Real Example
|
|
```json
|
|
{
|
|
"commercialService": "BOTH",
|
|
"commercialStopType": "BOTH",
|
|
"page": {
|
|
"pageNumber": 0
|
|
},
|
|
"stationCode": "60000",
|
|
"trafficType": "ALL"
|
|
}
|
|
```
|
|
|
|
#### Allowed Values
|
|
|
|
**commercialService / commercialStopType** (`CirculationPathRequest.java:65-67`):
|
|
- `YES` - Only commercial services/stops
|
|
- `NOT` - Without commercial services/stops
|
|
- `BOTH` - All types
|
|
|
|
**trafficType** (`TrafficType.java:16-21`):
|
|
- `CERCANIAS` - Commuter trains
|
|
- `AVLDMD` - High speed long/medium distance
|
|
- `OTHERS` - Other types
|
|
- `TRAVELERS` - Passengers
|
|
- `GOODS` - Freight
|
|
- `ALL` - All types
|
|
|
|
---
|
|
|
|
### 2.2 Circulations - Specific Routes
|
|
|
|
**Endpoints:**
|
|
- `/portroyalmanager/secure/circulationpathdetails/onepaths/`
|
|
- `/portroyalmanager/secure/circulationpathdetails/severalpaths/`
|
|
|
|
**Model:** `OneOrSeveralPathsRequest`
|
|
**File:** `circulations/model/request/OneOrSeveralPathsRequest.java:11-140`
|
|
|
|
```json
|
|
{
|
|
"allControlPoints": true/false/null,
|
|
"commercialNumber": "string or null",
|
|
"destinationStationCode": "string or null",
|
|
"launchingDate": 1733356800000,
|
|
"originStationCode": "string or null"
|
|
}
|
|
```
|
|
|
|
#### Real Example
|
|
```json
|
|
{
|
|
"allControlPoints": true,
|
|
"commercialNumber": "04138",
|
|
"destinationStationCode": "60000",
|
|
"launchingDate": 1733356800000,
|
|
"originStationCode": "71801"
|
|
}
|
|
```
|
|
|
|
**Important notes:**
|
|
- `launchingDate` is a **millisecond** timestamp (Long in Java)
|
|
- `allControlPoints` indicates whether to include every control point in the route
|
|
- Optional fields should be omitted rather than set to `null`
|
|
|
|
---
|
|
|
|
### 2.3 Train Compositions
|
|
|
|
**Endpoint:** `/portroyalmanager/secure/circulationpaths/compositions/path/`
|
|
|
|
**Model:** `OneOrSeveralPathsRequest` (same as routes)
|
|
**File:** `compositions/CompositionsService.java:14-18`
|
|
|
|
```json
|
|
{
|
|
"allControlPoints": true/false/null,
|
|
"commercialNumber": "string or null",
|
|
"destinationStationCode": "string or null",
|
|
"launchingDate": 1733356800000,
|
|
"originStationCode": "string or null"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 2.4 Stations - Single Station Details
|
|
|
|
**Endpoint:** `/portroyalmanager/secure/stations/onestation/`
|
|
|
|
**Model:** `OneStationRequest`
|
|
**File:** `stations/model/OneStationRequest.java:9-93`
|
|
|
|
```json
|
|
{
|
|
"detailedInfo": {
|
|
"extendedStationInfo": true,
|
|
"stationActivities": true,
|
|
"stationBanner": true,
|
|
"stationCommercialServices": true,
|
|
"stationInfo": true,
|
|
"stationServices": true,
|
|
"stationTransportServices": true
|
|
},
|
|
"stationCode": "60000",
|
|
"token": "string"
|
|
}
|
|
```
|
|
|
|
**Important notes:**
|
|
- The `detailedInfo` object controls what is returned
|
|
- All boolean fields default to `true` (see `DetailedInfoDTO.java:149`)
|
|
- `token` is required
|
|
|
|
#### DetailedInfo fields
|
|
|
|
**File:** `stations/model/DetailedInfoDTO.java:10-151`
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| `extendedStationInfo` | boolean | Extended station information |
|
|
| `stationActivities` | boolean | Station activities |
|
|
| `stationBanner` | boolean | Banner/announcements |
|
|
| `stationCommercialServices` | boolean | Commercial services |
|
|
| `stationInfo` | boolean | Basic station information |
|
|
| `stationServices` | boolean | Available services |
|
|
| `stationTransportServices` | boolean | Transport services |
|
|
|
|
---
|
|
|
|
### 2.5 Station Observations
|
|
|
|
**Endpoint:** `/portroyalmanager/secure/stationsobservations/`
|
|
|
|
**Model:** `StationObservationsRequest`
|
|
**File:** `stationObservations/model/StationObservationsRequest.java:10-53`
|
|
|
|
```json
|
|
{
|
|
"stationCodes": ["60000", "71801"]
|
|
}
|
|
```
|
|
|
|
#### Real Example
|
|
```json
|
|
{
|
|
"stationCodes": ["60000", "71801", "79600"]
|
|
}
|
|
```
|
|
|
|
**Notes:**
|
|
- Array of station codes (strings)
|
|
- Required field
|
|
- Can contain multiple codes
|
|
|
|
---
|
|
|
|
## 3. Endpoints and Base URLs
|
|
|
|
### 3.1 Base URLs
|
|
|
|
**File:** `di/NetworkModule.java:73-159`
|
|
|
|
| Service | Base URL | Authentication |
|
|
|---------|----------|----------------|
|
|
| **Circulations** | `https://circulacion.api.adif.es` | Secured (with AuthHeaderInterceptor) |
|
|
| **Stations** | `https://estaciones.api.adif.es` | Secured (with AuthHeaderInterceptor) |
|
|
| **AVISA** | `https://avisa.adif.es` | Basic (without AuthHeaderInterceptor) |
|
|
| **Elcano Web** | `https://elcanoweb.adif.es/api/` | - |
|
|
|
|
### 3.2 Full Paths - Stations
|
|
|
|
**File:** `ServicePaths.java:106-112`
|
|
|
|
```
|
|
GET /portroyalmanager/secure/stations/allstations/reducedinfo/{token}/
|
|
POST /portroyalmanager/secure/stations/onestation/
|
|
POST /portroyalmanager/secure/stationsobservations/
|
|
```
|
|
|
|
### 3.3 Full Paths - Circulations
|
|
|
|
**File:** `ServicePaths.java:41-51`
|
|
|
|
```
|
|
POST /portroyalmanager/secure/circulationpaths/departures/traffictype/
|
|
POST /portroyalmanager/secure/circulationpaths/arrivals/traffictype/
|
|
POST /portroyalmanager/secure/circulationpaths/betweenstations/traffictype/
|
|
POST /portroyalmanager/secure/circulationpathdetails/onepaths/
|
|
POST /portroyalmanager/secure/circulationpathdetails/severalpaths/
|
|
```
|
|
|
|
### 3.4 Full Paths - Compositions
|
|
|
|
**File:** `ServicePaths.java:55-61`
|
|
|
|
```
|
|
POST /portroyalmanager/secure/circulationpaths/compositions/path/
|
|
```
|
|
|
|
### 3.5 Full Paths - AVISA
|
|
|
|
**Files:** `ServicePaths.java:82-92` and `ServicePaths.java:29-37`
|
|
|
|
```
|
|
POST /avisa-ws/api/token (login)
|
|
POST /avisa-ws/api/token (refresh)
|
|
POST /avisa-ws/api/v1/client (register)
|
|
GET /avisa-ws/api/v1/station (stations)
|
|
GET /avisa-ws/api/v1/category (categories)
|
|
GET /avisa-ws/api/v1/incidence (incidences list)
|
|
GET /avisa-ws/api/v1/incidence/{id} (incidence details)
|
|
POST /avisa-ws/api/v1/incidence (create incidence)
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Network Configuration
|
|
|
|
### 4.1 OkHttpClient Configuration
|
|
|
|
**File:** `di/NetworkModule.java:100-132`
|
|
|
|
#### Basic client
|
|
```kotlin
|
|
OkHttpClient.Builder()
|
|
.certificatePinner(certificatePinner)
|
|
.connectTimeout(60, TimeUnit.SECONDS)
|
|
.readTimeout(60, TimeUnit.SECONDS)
|
|
.build()
|
|
```
|
|
|
|
#### Secured client (with authentication)
|
|
```kotlin
|
|
OkHttpClient.Builder()
|
|
.addInterceptor(AuthHeaderInterceptor(userId))
|
|
.certificatePinner(certificatePinner)
|
|
.connectTimeout(60, TimeUnit.SECONDS)
|
|
.readTimeout(60, TimeUnit.SECONDS)
|
|
.build()
|
|
```
|
|
|
|
**Timeouts:**
|
|
- Connect timeout: 60 seconds
|
|
- Read timeout: 60 seconds
|
|
|
|
### 4.2 Services using the secured client
|
|
|
|
**File:** `di/NetworkModule.java`
|
|
|
|
- `CirculationService` (line 73)
|
|
- `StationsService` (line 142)
|
|
- `StationObservationsService` (line 135)
|
|
- `CompositionsService` (line 156)
|
|
|
|
### 4.3 Services using the basic client
|
|
|
|
- `AvisaLoginService` (line 50)
|
|
- `AvisaStationsService` (line 57)
|
|
- `IncidenceService` (line 80)
|
|
- `SubscriptionsService` (line 149)
|
|
|
|
---
|
|
|
|
## 5. Authentication System
|
|
|
|
### 5.1 AuthHeaderInterceptor
|
|
|
|
**File:** `interceptors/AuthHeaderInterceptor.java:27-84`
|
|
|
|
This interceptor runs on **every** request for secured services.
|
|
|
|
#### Authentication process
|
|
|
|
1. **Generate persistent User ID**
|
|
- Uses `GeneratePersistentUserIdUseCase`
|
|
- The ID is stored and reused between sessions
|
|
|
|
2. **Build the token**
|
|
```java
|
|
ElcanoClientAuth.Builder()
|
|
.host(request.url().host())
|
|
.contentType("application/json;charset=utf-8")
|
|
.path(request.url().encodedPath())
|
|
.params(request.url().encodedQuery())
|
|
.xElcanoClient("AndroidElcanoApp")
|
|
.xElcanoUserId(userId)
|
|
.httpMethodName(request.method())
|
|
.payload(bodyJsonWithoutSpaces)
|
|
.build()
|
|
```
|
|
|
|
3. **Generate headers**
|
|
- The `ElcanoClientAuth` object generates authentication headers
|
|
- They are added automatically to the request
|
|
|
|
#### Generated headers
|
|
|
|
```
|
|
X-CanalMovil-Authentication: <calculated_token>
|
|
X-CanalMovil-deviceID: <device_id>
|
|
X-CanalMovil-pushID: <push_id>
|
|
```
|
|
|
|
### 5.2 GetKeysHelper class
|
|
|
|
**File:** `AuthHeaderInterceptor.java:44`
|
|
|
|
Provides keys for authentication:
|
|
- `getKeysHelper.a()` - First key
|
|
- `getKeysHelper.b()` - Second key
|
|
|
|
These keys are used by the signing/authentication algorithm.
|
|
|
|
### 5.3 Certificate Pinning
|
|
|
|
**File:** `di/NetworkModule.java:64-70`
|
|
|
|
The app uses **Certificate Pinning** to prevent MITM attacks:
|
|
- Expected SSL certificates are in `PinningRepository`
|
|
- Loaded asynchronously at startup
|
|
- All requests validate the server certificate
|
|
|
|
---
|
|
|
|
## 6. Code References
|
|
|
|
### 6.1 Key Files
|
|
|
|
| File | Location | Description |
|
|
|------|----------|-------------|
|
|
| `ServicePaths.java` | `serviceNetworking/` | Paths and static headers |
|
|
| `AuthHeaderInterceptor.java` | `serviceNetworking/interceptors/` | Auth header generation |
|
|
| `NetworkModule.java` | `serviceNetworking/di/` | Retrofit/OkHttp configuration |
|
|
| `CirculationService.java` | `serviceNetworking/circulations/` | Circulation API |
|
|
| `StationsService.java` | `serviceNetworking/stations/` | Stations API |
|
|
| `StationObservationsService.java` | `serviceNetworking/stationObservations/` | Observations API |
|
|
| `CompositionsService.java` | `serviceNetworking/compositions/` | Compositions API |
|
|
|
|
### 6.2 Request Models
|
|
|
|
| Model | File | Usage |
|
|
|-------|------|-------|
|
|
| `TrafficCirculationPathRequest` | `circulations/model/request/` | Departures, Arrivals, BetweenStations |
|
|
| `OneOrSeveralPathsRequest` | `circulations/model/request/` | OnePaths, SeveralPaths, Compositions |
|
|
| `OneStationRequest` | `stations/model/` | Station details |
|
|
| `DetailedInfoDTO` | `stations/model/` | Detailed info configuration |
|
|
| `StationObservationsRequest` | `stationObservations/model/` | Station observations |
|
|
|
|
### 6.3 Important Code Lines
|
|
|
|
- Static headers: `ServicePaths.java:67-76`
|
|
- Circulations user-key: `ServicePaths.java:67`
|
|
- Stations user-key: `ServicePaths.java:68`
|
|
- AVISA login token: `ServicePaths.java:70`
|
|
- Auth interceptor: `AuthHeaderInterceptor.java:38-83`
|
|
- Circulations base URL: `NetworkModule.java:76`
|
|
- Stations base URL: `NetworkModule.java:145`
|
|
- Enum TrafficType: `TrafficType.java:16-21`
|
|
- Enum State: `CirculationPathRequest.java:65-67`
|
|
|
|
---
|
|
|
|
## 7. Additional Notes
|
|
|
|
### 7.1 JSON Serialization
|
|
|
|
- **Library used:** Moshi (configured in `NetworkModule.java:87-96`)
|
|
- **Format:** JSON field names match Java property names exactly
|
|
- **Null handling:** Optional fields are **omitted** by the client; sending explicit `null` values leads to 401 responses
|
|
- **Date format:** Millisecond timestamps (Long)
|
|
|
|
### 7.2 Security Considerations
|
|
|
|
1. **Hardcoded user-keys:** API keys are in the code (easy to extract)
|
|
2. **Certificate Pinning:** Makes proxy interception harder
|
|
3. **Dynamic authentication:** X-Elcano headers require the HMAC algorithm to be reproduced
|
|
4. **AVISA token:** Base64 credentials in code (decodable)
|
|
|
|
### 7.3 Testing
|
|
|
|
Use the Python client (`adif_client.py`) or the signed test scripts in `/tests` to validate each endpoint. All endpoints are currently reproducible with the shipped keys and HMAC implementation.
|
|
|
|
---
|
|
|
|
**Last update:** 2025-12-05
|
|
**Source:** Decompiled ADIF El Cano Movil APK
|
|
**Tools:** JADX, Ghidra, manual Java code analysis
|