Tesla Signaling/Hermes Protocol to send vehicle commands

[lotharbach]

Related to #763 I began looking into how the Tesla App now sends signed commands to the vehicle. I would like to share what I have found by intercepting the App network traffic, which is very easy to do with a rooted phone as there is no certificate pinning, and hope for more research to happen. I hope we will someday be able to properly document what I would call the "Tesla Signaling/Hermes Protocol" as part of this project.

First of all, the owner API is still heavily used by the app. There is no reason to suspect the owner API in its entirety will go away anytime soon, as I have read so many times. It will "just" loose all "api/1/vehicle/../command/.." REST endpoints, as vehicles require end-to-end signed commands which is a thousand times more secure and to the benefit of all vehicle owners! The wake_up and vehicle_data endpoint is used by the app every few seconds, and pure data loggers will continue to work just fine!

The Tesla App can not send commands without also being registered as a phone key. For the phone key function it generates a private key on the phone and likely transfer that public key to the vehicle via Bluetooth. Details about generating and transfering such a key is also found in teslas vehicle-sdk. The SDK also contains all there we kneed to know about generating signed commands and can send them via the Fleet API or via Bluetooth. Since we likely won't have access to the Fleet API as vehicle owners, I was interested how the App continues to function.

The App performs a POST on HERMES_AUTHORIZATION endpoint,
https://owner-api.teslamotors.com/api/1/users/jwt/hermes

Payload {"uuid": "<some uuid>"}
Response {  "token": "<jwt to talk to hermes>" }

There is also a second POST on HERMES_VEHICLE_AUTHORIZATION endpoint,
https://owner-api.teslamotors.com/api/1/vehicles/:vehicle-id/jwt/hermes

Payload {"uuid": "<some uuid>"}
Response {  "token": "<jwt found in some protobuf messages>" }

With the first token, a WebSocket connection is opened on HERMES_URI wss://signaling.vn.teslamotors.com/v1/mobile with
Header "X-Jwt: <jwt to talk to hermes>

And they now exchange some sort of protobuf based binary packets. A command in the App very clearly generates a new exchange on that WebSocket channel and nothing else on the network. Decoding the protobuf shows strings like vehicle_device.<my VIN>.cmds and what I guess is a wrapped message in the same signed command protobuf layout that the vehicle-sdk is generating to send via BLE or to the Fleet-API's signed_command endpoint.

This is the end of my knowledge so far. More revesing of the protobuf message description is required to generated what I guess is first some "handshake" and then the command messsages. I unfortunately can't/won't share my full binary capture as it contains private information and credentials.

This is how one can talk to hermes on the command line:

websocat -t --insecure -H="X-Jwt: $(cat hermestoken)" --ws-c-uri=wss://signaling.vn.teslamotors.com:443/v1/mobile ws-c:log:ssl:tcp:signaling.vn.teslamotors.com:443 -
[WARN  websocat::ssl_peer] Connected to TLS without proper verification of certificate. Use --tls-domain option.
WRITE 596 "GET /v1/mobile HTTP/1.1\r\nX-Jwt: redacted\r\nHost: signaling.vn.teslamotors.com\r\nConnection: Upgrade\r\nUpgrade: websocket\r\nSec-WebSocket-Version: 13\r\nSec-WebSocket-Key: 9rN06emPdZj1rpY+/2rNCA==\r\n\r\n"
READ 534 "HTTP/1.1 101 Switching Protocols\r\nDate: Sun, 26 Nov 2023 13:18:00 GMT\r\nConnection: upgrade\r\nUpgrade: websocket\r\nSec-WebSocket-Accept: ihuyLme774eaL2dZutRzHiTIz80=\r\nX-Server-Canonical-Url: wss://hermes-eu-west-prd.vn.tesla.services:443/v1/mobile\r\nStrict-Transport-Security: max-age=15724800; includeSubDomains\r\nContent-Security-Policy: default-src \'none\'\r\nCache-Control: no-cache, no-store, private, s-max-age=0\r\nStrict-Transport-Security: max-age=31536000; includeSubDomains\r\nX-Content-Type-Options: nosniff\r\nX-Frame-Options: DENY\r\n\r\n"
READ 563 "\x82~\x02/\n\xac\x04\n$f673c134-46d8-4e17-af06-f4b01727cb6f\x12\x08internal\x1a\x0c\x08\x88\x8b\x8d\xab\x06\x10\x84\x84\x8f\x9f\x01\"\x0cHermesServer(\xa0\x08J\x0b\x08\x80\x92\xb8\xc3\x98\xfe\xff\xff\xff\x01R\xcb\x03{\"expiration\":1701008280,\"connection_timeout\":180000,\"ping_frequency\":60000,\"autopark\":{\"heartbeat_frequency\":100,\"autopark_pause_timeout\":2000,\"autopark_stop_timeout\":10000},\"ice_servers\":[{\"urls\":[\"stun:46.137.45.143:3478\",\"stun:63.35.119.211:3478\"]},{\"urls\":[\"turn:54.78.132.75:3478\",\"turn:54.228.219.44:3478\",\"turn:turn6.euw1.vn.cloud.tesla.com:3478\"],\"username\":\"redacted:redacted\",\"credential\":\"redacted=\"}]}Z\x00"
 � $f673c134-46d8-4e17-af06-f4b01727cb6internal
                                              ��������"
                                                       HermesServer(J
                                                                    �������R�{"expiration":1701008280,"connection_timeout":180000,"ping_frequency":60000,"autopark":{"heartbeat_frequency":100,"autopark_pause_timeout":2000,"autopark_stop_timeout":10000},"ice_servers":[{"urls":["stun:46.137.45.143:3478","stun:63.35.119.211:3478"]},{"urls":["turn:54.78.132.75:3478","turn:54.228.219.44:3478","turn:turn6.euw1.vn.cloud.tesla.com:3478"],"username":"1redacted","credential":"redacted"}]}Z
READ 563 "\x82~\x02/\n\xac\x04\n$13043831-42b5-4b30-a11f-2fb6217d7db1\x12\x08internal\x1a\x0c\x08\x8d\x8b\x8d\xab\x06\x10\xbd\xc7\xb2\x9f\x01\"\x0cHermesServer(\xa0\x08J\x0b\x08\x80\x92\xb8\xc3\x98\xfe\xff\xff\xff\x01R\xcb\x03{\"expiration\":1701008285,\"connection_timeout\":180000,\"ping_frequency\":60000,\"autopark\":{\"heartbeat_frequency\":100,\"autopark_pause_timeout\":2000,\"autopark_stop_timeout\":10000},\"ice_servers\":[{\"urls\":[\"stun:54.228.219.44:3478\",\"stun:46.137.45.143:3478\"]},{\"urls\":[\"turn:54.78.132.75:3478\",\"turn:63.35.119.211:3478\",\"turn:turn6.euw1.vn.cloud.tesla.com:3478\"],\"username\":\"redacted\",\"credential\":\"redacted\"}]}Z\x00"
 � $13043831-42b5-4b30-a11f-2fb6217d7dbinternal
                                              �����Dz�"
                                                      HermesServer(J
                                                                   �������R�{"expiration":1701008285,"connection_timeout":180000,"ping_frequency":60000,"autopark":{"heartbeat_frequency":100,"autopark_pause_timeout":2000,"autopark_stop_timeout":10000},"ice_servers":[{"urls":["stun:54.228.219.44:3478","stun:46.137.45.143:3478"]},{"urls":["turn:54.78.132.75:3478","turn:63.35.119.211:3478","turn:turn6.euw1.vn.cloud.tesla.com:3478"],"username":"1redacted","credential":"1redacted"}]}Z
READ 561 "\x82~\x02-\n\xaa\x04\n$7c3a3ed4-33d1-4a64-a4db-9d788b2ce3fa\x12\x08internal\x1a\x0c\x08\x92\x8b\x8d\xab\x06\x10\xc3\xc9\xc8\x9f\x01\"\x0cHermesServer(\xa0\x08J\x0b\x08\x80\x92\xb8\xc3\x98\xfe\xff\xff\xff\x01R\xc9\x03{\"expiration\":1701008290,\"connection_timeout\":180000,\"ping_frequency\":60000,\"autopark\":{\"heartbeat_frequency\":100,\"autopark_pause_timeout\":2000,\"autopark_stop_timeout\":10000},\"ice_servers\":[{\"urls\":[\"stun:54.78.132.75:3478\",\"stun:63.35.119.211:3478\"]},{\"urls\":[\"turn:54.78.132.75:3478\",\"turn:52.18.36.139:3478\",\"turn:turn6.euw1.vn.cloud.tesla.com:3478\"],\"username\":\"1redacted\",\"credential\":\"1redacted\"}]}Z\x00"
 � $7c3a3ed4-33d1-4a64-a4db-9d788b2ce3finternal
                                              ������ȟ"
                                                      HermesServer(J
                                                                   �������R�{"expiration":1701008290,"connection_timeout":180000,"ping_frequency":60000,"autopark":{"heartbeat_frequency":100,"autopark_pause_timeout":2000,"autopark_stop_timeout":10000},"ice_servers":[{"urls":["stun:54.78.132.75:3478","stun:63.35.119.211:3478"]},{"urls":["turn:54.78.132.75:3478","turn:52.18.36.139:3478","turn:turn6.euw1.vn.cloud.tesla.com:3478"],"username":"11redacted","credential":"1redacted"}]}Z
^C

Without a valid token there is a "authorization denied" message.

[Urkman]

I also tried a lot here and I managed to register my public key in my tesla using the Tesla App.
And I can successfully access the vehicle data using the new API.

But when I try to send a command using the cli I get this error:
Error: {"error":"Account xxx must be registered please see https://developer.tesla.com/docs/fleet-api#register"}

But the Account is registered I can access the vehicle data.

Any ideas on this?

[lotharbach]

What I'm doing here is mainly motivated by trying to avoid the Fleet API as the App does not use it and random vehicle owners won't get approved to use the Fleet API. Questions and answers about how to use the Fleet API is really not the direction we should take in this discussion. Thanks!

[lotharbach]

Yesterday I was able to begin writing a .proto file to make some first sense of the captured network traffic. I'm able to manually find the field types and descriptors in the decompiled android app, so I think this protocol is completely feasible to re-implement.

10.0.0.1:54684 -> WebSocket binary message -> 52.208.90.105:443/v1/mobile
[22:16:28.325] Client sent a message:
[22:16:28.325] commandMessage {
  txid: "9A2CD9ABD1239B704F1720B3C8414690"
  topic: "vehicle_device.<redacted vin>.cmds"
  createdAt {
  }
  expiry {
    seconds: 10
  }
  payload: "<redacted what I hope is a signed command>"
  options {
    token: "<redacted vehicle jwt token>"
  }
}

10.0.0.1:54684 -> WebSocket binary message -> 52.208.90.105:443/v1/mobile
[22:16:28.326] Server sent a message:
[22:16:28.326] commandMessage {
  txid: "e0e139ec-a9e4-4880-941f-b78f5f7f3c61"
  topic: "vehicle_device.<redacted vin>.cmds"
  createdAt {
    seconds: 1701037685
    nanos: 652986515
  }
  senderId: "HermesServer"
  commandType: 1047
  requestTxid: "9A2CD9ABD1239B704F1720B3C8414690"
  statusCode: 1202
  expiry {
    seconds: -62135596800
  }
  options {
  }
}

[lotharbach]

I send my first command successfully with just owner API access and the Hermes protocol! I will write up the details and provide the code (golang as im leveraging the vehicle SDK) as time allows.

[lotharbach]

I can send commands to the vehicle via hermes by reusing the official golang vehicle-sdk. Here is a go package and example:

https://github.com/lotharbach/tesla-hermes-signaling

All of the encryption details, session setup and command message encoding is done in vehicle-sdk, and I can only give a high level explaination right now.

You need a private key that is authorized in the vehicle, which I have done with the tesla-command tool from the vehicle-sdk via Bluetooth.

As described above, two tokens are fetched from the owner API, and a websocket channel is established with the users hermes token. Binary messages are send and received, in the following format

syntax = "proto3";

message HermesMessage {
  CommandMessage commandMessage = 1;
  // ProtoSubscribeMessage subscribeMessage = 2;
  // ProtoUnsubscribeMessage unsubscribeMessage = 3;
}

message CommandMessage {
  bytes txid = 1;
  bytes topic = 2;
  Timestamp createdAt = 3;
  bytes senderId = 4;
  CommandType commandType = 5;
  bytes requestTxid = 6;
  StatusCode statusCode = 7;
  bytes responseTopic = 8;
  Timestamp expiry = 9;
  bytes payload = 10;
  FlatbuffersMessageOptions options = 11;
  bytes messageId = 12;
}

message Timestamp {
  int64 seconds = 1;
  int32 nanos = 2;
}

message FlatbuffersMessageOptions {
  uint32 responseSubscribed = 1;
  uint32 qos = 2;
  bytes token = 3;
  bytes signature = 4;
}

enum StatusCode {
  STATUS_CODE_OK = 0;
  STATUS_CODE_INVALID_MESSAGE = 1;
  STATUS_CODE_INVALID_TOKEN = 2;
  STATUS_CODE_PUBLISH_FAILED = 3;
  STATUS_CODE_PERMISSION_DENIED_NO_TOKEN = 4;
  STATUS_CODE_PERMISSION_DENIED_EXPIRED_TOKEN = 5;
  STATUS_CODE_PUBLISH_FAILED_NOT_CONNECTED = 6;
  STATUS_CODE_SERVER_ACK = 1202;
  STATUS_CODE_TOO_MANY_REQUESTS = 1429;
  STATUS_CODE_CLIENT_ACK = 2202;
  STATUS_CODE_INTERNAL_ERROR = 2500;
  STATUS_CODE_APPLICATION_OK = 3200;
  STATUS_CODE_APPLICATION_ACK = 3202;
  STATUS_CODE_APPLICATION_ERROR = 3500;
}

enum CommandType {
  COMMAND_TYPE_OK = 0;
  COMMAND_TYPE_ERROR_RESPONSE = 1031;
  COMMAND_TYPE_DEVICE_CONNECTED = 1044;
  COMMAND_TYPE_DEVICE_DISCONNECTED = 1046;
  COMMAND_TYPE_SIGNED_COMMAND = 1047;
  COMMAND_TYPE_SIGNED_COMMAND_RESPONSE = 1048;
  COMMAND_TYPE_SIGNED_COMMAND_ERROR = 1049;
  COMMAND_TYPE_STREAMING_CONFIG = 1056;
  COMMAND_TYPE_GET_VAULT = 1059;
  COMMAND_TYPE_SAVE_VAULT = 1060;
}

(I have not yet seen subscribeMessage/unsubscribeMessage being used in the App so far)

You need send a CLIENT_ACK for every message you receive, requestTxid set to the txid of the incoming message, and the same topic.

	requestTxid := input.GetCommandMessage().GetTxid()
	topic := input.GetCommandMessage().GetTopic()
	uuid := uuid.New()
	output := &protos.HermesMessage{
		CommandMessage: &protos.CommandMessage{
			Txid:        []byte(uuid.String()),
			Topic:       topic,
			RequestTxid: requestTxid,
			StatusCode:  *protos.StatusCode_STATUS_CODE_CLIENT_ACK.Enum(),
		},
	}

Messages to the car need to be send to the topic "vehicle_device..cmds", and need to have a valid hermes vehicle token (as described above). The payload is a binary RoutableMessage protobuf.

	topic := "vehicle_device." + c.vin + ".cmds"
	uuid := uuid.New()
	output := &protos.HermesMessage{
		CommandMessage: &protos.CommandMessage{
			Txid:    []byte(uuid.String()),
			Topic:   []byte(topic),
			Expiry:  &protos.Timestamp{Seconds: 10},
			Payload: buffer,
			Options: &protos.FlatbuffersMessageOptions{
				Token: []byte(c.vehicleToken),
			},
		},
	}

You need to first setup a session, for each domain you want to send commands, by sending your public key.

	request := universal.RoutableMessage{
		ToDestination: &universal.Destination{
			SubDestination: &universal.Destination_Domain{
				Domain: domain,
			},
		},
		Payload: &universal.RoutableMessage_SessionInfoRequest{
			SessionInfoRequest: &universal.SessionInfoRequest{
				PublicKey: publicBytes,
			},
		},
	}

The vehicle will then send back a message with its own public key and session info, basically an encrypted message channel. I did not dive deeper into this, but again the vehicle-sdk contains all the details to either reuse or reverse in another language.

Now command messages can be send, the payload is an encrypted/signed VehicleAction or RKEAction. The vehicle responds with a COMMAND_TYPE_SIGNED_COMMAND_RESPONSE.

[eiannone]

@lotharbach thank you for your work! I think this is the right direction to go, considering the heavy limitations of the Fleet API.

[lotharbach]

@eiannone I had noticed your great work in reimplementing the Command Protocol in NodeJS! Seeing how little code it actually takes (with the help of a few good libraries of course) gave me great hope for more Command Protocol implementations in other languages, and maybe somebody might sprinkle in this hermes client stuff as well. I will support you in every possible way if you want to add a hermes client to your codebase.

I myself would love to have the combination of hermes client + command protocol in python for home assistant and will work on this but am very time restricted.

The other idea I want to pursue (as time allows) is a hermes-command-proxy in go based directly on Teslas command proxy code. And a ble-command-proxy (Bluetooth Low Energy), but thats offtopic for this discussion.

[eiannone]

Thank you! Indeed I would like to implement the Hermes protocol in Javascript language, using the knowledge acquired for my library and your precious work.
I have a question regarding how to enroll your public key into the car. It's the same procedure as for the third party apps? I had to publish it on a specific url associated with a domain (https://domain.name/.well-known/appspecific/com.tesla.3p.public-key.pem), and then open the url https://tesla.com/_ak/domain.name with a mobile browser, which in turn opens the Tesla app and pushes the key into the car.

[lotharbach]

I only ever did that locally via BLE with https://github.com/teslamotors/vehicle-command/tree/main/cmd/tesla-control

go run ./cmd/tesla-control -ble add-key-request public_key.pem owner cloud_key

That does require physical presence and a key card, but no developer account, partner registration, public domains etc

[lotharbach]

I have a proof of concept patch to tesla-http-proxy that sends commands via hermes, and proxies other API requests to the owner api:

https://github.com/lotharbach/tesla-command-proxy/tree/owner-proxy

Run the modified proxy:

# go run ./cmd/tesla-http-proxy -tls-key key.pem -cert cert.pem -port 4443 -key-file private-key.pem -mode owner -verbose

Get vehicle_data and send command:

# curl -k --header "Authorization: Bearer $OWNER_AUTH_TOKEN" "https://localhost:4443/api/1/vehicles/$VIN/vehicle_data" | jq .response.charge_state.charge_limit_soc
86

# curl -k --header 'Content-Type: application/json' --header "Authorization: Bearer $OWNER_AUTH_TOKEN" "https://localhost:4443/api/1/vehicles/$VIN/command/set_charge_limit" --data '{"percent": 87}'
{"response":{"result":true,"reason":""}}

# curl -k --header "Authorization: Bearer $OWNER_AUTH_TOKEN" "https://localhost:4443/api/1/vehicles/$VIN/vehicle_data" | jq .response.charge_state.charge_limit_soc
87

[themonomers]

Holy cow it works. You are the man @lotharbach! I'm going to see if I can send commands to it from my existing Python scripts.

[themonomers]

After a few days of testing, here are my initial observations:

1. The fork of @lotharbach tesla-http-proxy is quite stable. No crashes running on a Raspberry Pi 4 and it doesn't seem to require BLE after initial setup to get/register keys.
2. Model 3's can no longer use the existing Owner API without this proxy. Pre-2021 Model X and S still need to use the existing Owner API, except for the wake_up endpoint for some reason.
3. The HTTP Proxy URL's are different in that they take VIN instead of id_s and some of the payloads are slightly different. So far I've only found this to the case with the remote_seat_heater_request endpoint using seat_position instead of heater.

I hope this can stay working long term!

I also fooled around with the Command SDK via BLE and it does work for things like honk horn, however trying to get vehicle data throws an error saying you have to use the Fleet API for that. So it seems the HTTP Proxy is really the way to go.

[llamafilm]

I just came across this project and looks interesting, thanks for sharing your research.

I just wanted to share that I’ve built a Home Assistant addon which implements the keygen, http proxy, and oauth flow. My goal was to make it as easy as possible for users. https://github.com/llamafilm/tesla-http-proxy-addon

[lotharbach]

Thanks for your work! I'm following it closely from the beginning!

My own vehicle (M3 from 2022) has not yet been hard locked to signed commands, so I'm actually still using the home assistant tesla integration without proxy/fleet api day to day and have not spend any more time on the proxy fork.

I will benefit from the work you've done to implement "proxy support" to the integration and python library once I have to switch over to my own "owner mode" proxy fork completely.

Still hoping for native python code to generate the signed commands, which could then work with both fleet api and hermes without any proxy required. And even more, I hope for tesla to make "vehicle owner" access to the fleet api much much easier, to keep it free and with usable API limits, because right now the majority of users probably can not get that setup and keep it running, and switch to paid third party integrations.

[Whirlwind]

@lotharbach Thanks for your work.

I have a question: How to get the OWNER_AUTH_TOKEN? From the auth.tesla.com?

In the fleet api document, we query the token from the auth.tesla.com. But I use the access_token to request the hermes token, I receive the 401: invalid bearer token.

[lotharbach]

This might be a situation of the "if you need to ask, it's not meant for you" kind, but im going to be helpful and recommend https://tesla-info.com/tesla-token.php

But please understand that I am not interested in turning this into a user support group but rather look for other people to share their unique and new findings about deeper details of this protocol.

[themonomers]

@Whirlwind I personally know of 2 ways to get the access token:

1. Python: This repository has methods to interact with a web browser for you to get the token. Then you can just use the refresh API and existing tokens to generate a new access token before it expires (in about 8 hours) in a headless manner.
2. iOS App: Similar to the Python method of interacting with a web browser. I'm pretty certain Android has a similar app that does this.

[Whirlwind]

Thanks everyone.

My example project works!

But today, I find there is not any response from hermes server.

I can connect the signaling, and I get the first message with the COMMAND_TYPE_STREAMING_CONFIG type, then I send client ack for it.

Then I send my routable message for get the session info, the server response STATUS_CODE_SERVER_ACK with COMMAND_TYPE_SIGNED_COMMAND type, I response the client ack for the server ack. There is nothing response from the vehicle. I am sure the vehicle is online(awake).

Is there same case for you?