Coral client attestation/f parameter

[samuelthomas2774]

Tracking issue for anything related to the f parameter required to authenticate to the Coral API and web services...

If you can help reverse engineering this, leave a comment here or send a message on Discord (#12).

---

Related:

• f token generation in NSO app v1.4.1 frozenpandaman/splatnet2statink#62
• Request to use your api in my application. frozenpandaman/splatnet2statink#117
• Error from the flapg API: Error 404 (offline or incorrect headers). frozenpandaman/splatnet2statink#138
• https://twitter.com/NexusMine/status/1051500912584273920
• https://twitter.com/JoneWang/status/1426257245113749507
• https://github.com/clovervidia/nsotokengen - Python implementation of my server
• https://twitter.com/JoneWang/status/1555556979963154433 - imink Android device setup

---

Currently nxapi, splatnet2statink, ikaWidget2, imink and anything else that uses the Coral (Nintendo Switch Online app) API or any web services rely on either the flapg or imink API to generate some data necessary for two (actually three) authentication-related API calls, which requires sending them some authentication data (!). The data doesn't seem to have any useful purpose other than to (somewhat unsuccessfully) prove the client is actually Nintendo's app.

• The flapg API runs Nintendo's app on an emulated Android device to generate this data.
  • The flapg API has it's own client authentication system, which is what the splatnet2statink API is required for. As splatnet2statink is now using the imink API and has deprecated it's own API for use with flapg, anyone using the flapg API with the splatnet2statink API will now need to move to another service, or ask NexusMine for assistance using flapg directly.
• I took the same sort of approach as the flapg API here, specifically, using Frida to hook into the app (but I don't have the resources to actually run this, and so far haven't managed to get Nintendo's app launching in an emulated Android device at all). (This is probably less efficient and reliable than flapg though lol, but it works.)
• The imink API uses a physical Android device (previously a virtual device) running Nintendo's app with a custom agent written in Go (https://twitter.com/JoneWang/status/1555556979963154433).

Ideally this would just be done locally so we don't have to send any data anywhere...

---

From #9 (comment):

I'm thinking it would be great to have a WebAssembly binary that (somehow?) calls the function, then we're not really sharing how it works and could still tie it to an API to stop Nintendo complaining, and prevent sending invalid tokens.

No idea how that would actually work (either reimplementing or somehow embedding gen_audio_h/gen_audio_h2), but (if possible) it should be usable in anything that can compile WebAssembly modules (e.g. for Python pywasm or wasmer), then we could create a simple API that would be required by the module to prevent clients sending too many/any invalid requests to Nintendo.

---

From https://www.reddit.com/r/NintendoSwitch/comments/tpzabb/comment/i2kk9ny/, re. possibly running Nintendo's app locally as flapg/my service do now (w/ added line breaks):

Running Nintendo's app locally also isn't very practical as users will have to install an Android emulator and the app manually, and have it constantly running in the background just in case we need to renew any tokens.

What could maybe help here is Windows Subsystem for Android (I haven't looked into this too much as I don't regularly use Windows, but I assume it would then be possible to enter the Android environment via adb and run Frida just as my server does now).

For macOS it would be super helpful of Nintendo if they just released their current iOS app for Mac - then it should be possible to just hook into it using Frida as an unprivileged but unsandboxed macOS app (but the actual Frida script would be very different to how it works on Android).

It is possible to run Coral on a Mac with an ARM/M1 processor but you need a jailbroken iOS device to dump a decrypted copy of the app. I can't get past the login screen though (where it should launch a Safari web view with the Nintendo Account login page it just doesn't do anything, I think it shows a message with the Safari icon but then immediately closes it). Attaching to the app with Frida (as root) works, and you can read the app's memory and Objective-C classes, but even just attempting to call anything causes the app to segfault. (Possibly due to SIP?)

It should be possible to inject a dylib when launching Coral (assuming it's signature has already been removed to get it to run at all). Then that could provide some API that could be used to call genAudioH/2, without dynamic instrumentation.

---

Is it possible to isolate the gen_audio_h/2 functions, and any other functions they call, and remove everything else + any Android (/iOS?) specific dependencies from the binary? That would at least mean it would be possible to just call it on any Linux OS…

So far I’ve managed to compile a binary that (would) call gen_audio_h, but it doesn’t work because it tries to load Android stuff.

Or, would it be possible to just create stubs of anything libvoip imports but doesn’t actually need to call gen_audio_h?

If this works it could be run in a WebAssembly binary, using a minimal Linux environment with v86. (If this can restore a snapshot of graphical OS almost instantly it’s definitely fast enough to run a single function from a Linux binary. Possibly this could also run a custom minimal Android environment as well.)

[samuelthomas2774]

Since 23/08/2022 Nintendo is validating the parameters used to generate the f parameter are generated strictly as they would be in Nintendo's official app:

• The token/id_token/naIdToken parameter is the Nintendo Account id_token from https://accounts.nintendo.com/connect/1.0.0/api/token for Coral authentication (Account/Login/Account/GetToken), and the Coral access token from Account/Login/Account/GetToken for web service authentication (Game/GetWebServiceToken).
• The timestamp parameter is the current timestamp. On iOS this is in seconds, and on Android this is in milliseconds.
  • The timestamp parameter in the request body should be a JSON number, not a string (on both platforms), although the API will currently accept either.
• The request_id/requestId parameter is a random (v4) UUID. On iOS this is uppercase hex, and on Android this is lowercase hex, although Nintendo don't appear to be checking this currently.

What changed on 23/08/2022 is that Nintendo appears to be somehow checking the timestamp property does actually match the time that the f parameter was generated (with only ~1s difference allowed). This means the get_audio_h/2 functions must get the system time itself and encode it in the returned f parameter somehow. If this doesn't match a 9599 Unexpected error. message will be returned (not 9403 Invalid token.?).

Just changing the client to get the timestamp in milliseconds before sending it to imink/flapg will allow authentication attempts to succeed, but only if the client's time (plus request latency) exactly matches the time on the Android device. So, the proper solution is to not send the timestamp to the API and instead have the API use and return the timestamp on the Android device with the resulting f parameter.

• The imink API has been updated to make the timestamp parameter optional.

  Documentation: https://github.com/JoneWang/imink/wiki/imink-API-Documentation

  samuel nxapi % curl -i --header 'Content-Type: application/json' \
  > --data '{"hash_method": "1", "token": "test"}' \
  > 'https://api.imink.app/f'
  
  HTTP/2 200 
  server: nginx
  date: Wed, 24 Aug 2022 22:30:45 GMT
  content-type: application/json; charset=utf-8
  content-length: 180
  strict-transport-security: max-age=15724800; includeSubdomains
  
  {
    "f": "0576fc5f46c933c80455df0bce790dcdc78b0fa698bd12ec2dcab684336c38dfd22d1db1d76f9130369e917e85cb1c",
    "timestamp": 1661380244671,
    "request_id": "f3c12c1e-0f76-40ec-b153-37375e0bbe7d"
  }
  

• nxapi's custom server using Frida has already been updated to make the timestamp parameter optional. You can run this by building nxapi from source.

  Documentation: https://github.com/samuelthomas2774/nxapi/blob/main/docs/cli.md#znca-api-server

  samuel nxapi % curl -i --header 'Content-Type: application/json' \
  > --data '{"hash_method": "1", "token": "test", "request_id": "test"}' \
  > 'http://[::1]:8080/api/znca/f'
  
  HTTP/1.1 200 OK
  X-Powered-By: Express
  Server: nxapi 1.3.0-223faab (main) android-znca-api-frida
  X-Android-Build-Type: user
  X-Android-Release: 8.0.0
  X-Android-Platform-Version: 26
  X-znca-Platform: Android
  X-znca-Version: 2.2.0
  X-znca-Build: 2832
  Content-Type: application/json
  Date: Wed, 24 Aug 2022 09:42:49 GMT
  Connection: keep-alive
  Keep-Alive: timeout=5
  Content-Length: 124
  
  {
    "f": "8b1d192127bf357a008046eddb4d0bbd0fe6c3c9381e8fb84d2ee7f8a445c0086547e13144ce8814bb6180bfd0",
    "timestamp": 1661334167921
  }
  

• The flapg API has also been updated and is now compatible with the imink API. The API is now available at https://flapg.com/ika/api/login-main. Client authentication is no longer required.

  https://twitter.com/NexusMine/status/1563728086322929665

  samuel nxapi % curl -i --header 'Content-Type: application/json' \
  > --data '{"hash_method": "1", "token": "test"}' \
  > 'https://flapg.com/ika/api/login-main'
  
  HTTP/2 200 
  server: nginx/1.19.2
  date: Thu, 01 Sep 2022 12:27:06 GMT
  content-type: application/json; charset=utf-8
  content-length: 179
  strict-transport-security: max-age=31536000;
  
  {
    "f": "a343c9e95bf87ffea3225a941f0acc0b3941d58b7b501000c2a47a13d20a201c30040155409bd7e6300241d4",
    "timestamp": 1662035226888,
    "request_id": "1a61446a-ba0f-4f37-a305-984971e2fadf"
  }
  

imink and nxapi both have fully compatible APIs when used as documented, however nxapi's server will only return parameters that were not included in the request and were generated by the server, while imink will always return the timestamp and request_id. If the timestamp is submitted to imink it must be a numeric string, while nxapi will accept either a string (not required to be numeric) or a number. nsotokengen has also been updated and is fully compatible with the imink API.

[frozenpandaman]

Never knew the iOS version of the app used an uppercase UUID. Hah, fun facts, the more you know!

Re: the error code from Nintendo that we've been seeing, though – I was wondering that too. Why 9599 Unexpected error now and not 9403 Invalid token like has always been returned before?! Interesting…

[frozenpandaman]

I would recommend just waiting for an update for now.

Jone's "minus 1000 ms" method mentioned in the updated imink docs here & in the Discord actually seems to be a really good workaround! But I agree, waiting for an update (probably quite soon) is the better solution instead of just patching in the workaround only to have to change it later (like I had to do in s2s due to the number of users unable to generate tokens) is cleaner, haha.

[samuelthomas2774]

Never knew the iOS version of the app used an uppercase UUID. Hah, fun facts, the more you know!

Yeah they just use exactly what the platform's API returns, that's why the timestamp is different as well. The parental controls app uses client-generated UUIDs (and must just store them as a string) for each smart device, so it's the same there as well.

Re: the error code from Nintendo that we've been seeing, though – I was wondering that too. Why 9599 Unexpected error now and not 9403 Invalid token like has always been returned before?! Interesting…

My theory is that f is the result of encrypting something (possibly the system time), using the token, timestamp and request ID, and possibly the platform and some static data (that they don't change between releases?) as a key. That would explain how they can verify the system time. So 9403 would be that decryption of f failed and therefore the parameters used to generate it must be wrong, and 9599 means it was decrypted/unwrapped/whatever successfully but validation of the data failed.

Jone's "minus 1000 ms" method mentioned in the updated imink docs here & in the Discord actually seems to be a really good workaround!

The issue with that is the client's time still has to match the imink API's time, just now off by 1s. My time does match imink's time exactly so this would be less likely to work for me, as it seems to work fine without this:

samuel ~ % curl -I https://api.imink.app ; date
HTTP/2 404 
server: nginx
date: Wed, 24 Aug 2022 11:16:38 GMT
content-type: application/json; charset=utf-8
content-length: 35
strict-transport-security: max-age=15724800; includeSubdomains

Wed 24 Aug 2022 12:16:38 BST

[frozenpandaman]

possibly the platform and some static data (that they don't change between releases?) as a key

Have some info here from previous versions of the app (back when f was a simple HMAC generated using a static key) in case it's helpful that I'll send in the Discord.

[samuelthomas2774]

In v2.4.0 the format of f parameters was changed:

• f generation is currently down (9403 error: Invalid token) frozenpandaman/s3s#96

Example of f generated by Nintendo: 9aee4e7dbf18b41a006a70fed8437e1d5fed17828a053157b9a0b9ab5dae8002bb6d78ad49cc645c42e97dd7d445527c34ba302c1772ced73099e0afff00e533b5311b6ff7████ (142–144 characters)

Example of f generated by imink API + s3s: e3eb429ef99d4b0be3b8dc7667bbcf422a3ba22383392292b2cc8fd94cd74b53b6704fe2cee3e8b0c401517e02████ (94 characters)

This broke most projects using the Coral API as it was still accepting f tokens in the old format, including from clients claiming to be running 2.4.0, until ~2:00 am today when Nintendo stopped accepting requests from clients claiming to be running 2.3.1... and f tokens generated by 2.3.1 (and older).

---

If you are using the Nintendo Switch Online app API: you do not need to do anything if you are using the imink API (or my nxapi-znca-api test server) to generate f tokens, as these have now been updated to use 2.4.0.

If you are using a custom imink API server you need to update the server to v1.0.3.

If you are using another API to generate f tokens for the Nintendo Switch Online app API or are running an API to generate f tokens, it needs to be updated use 2.4.0 (or at least, libvoip from 2.4.0 :)).

---

...

[samuelthomas2774]

f-generation changes 24/05/2023

(These changes were actually introduced in 2.4.0, but Nintendo wasn't validating clients were setting them properly when generating f until now.)

• Step2 F-token generation appears to be broken with 2.5.1 imink-app/f-API#3
• Automatic token generation is broken (9403: Invalid token.) frozenpandaman/s3s#125
• Error: No idToken2 found spacemeowx2/s3si.ts#69
• Unhandled Exception in Script (FIXED) MCMi460/NSO-RPC#74

---

Since 2.4.0 the native gen_audio_h/2 functions make calls in the Java VM to retrieve data used to generate f, however Nintendo continued to accept tokens generated with these functions not returning the correct data. (libvoip did not change in 2.5.1, but did in 2.5.0.)

It is also possible that libvoip is able to detect code injection. Calling init while Frida is loaded now appears to cause generated tokens to be rejected, even when they are only generated by using the app normally.

The following methods need to be modified to return the correct data: (This is not a complete list of the methods called by libvoip when generating f tokens.)

Coral authentication (gen_audio_h/hash method 1)

• com.nintendo.coral.core.entity.NAUser/c returns the user's Nintendo Account ID
• com.nintendo.nx.nasdk.m/d returns the Nintendo Account id_token (the same token passed to gen_audio_h as the first argument)

Web service authentication (gen_audio_h2/hash method 2)

• com.nintendo.coral.core.network.e/b returns the Coral token (the same token passed to gen_audio_h2 as the first argument)
• za.h/v returns an instance of com.nintendo.coral.core.entity.CoralUser, with the a field set to the Coral user ID (other fields are not used)
• com.nintendo.coral.core.entity.NAUser/c returns the user's Nintendo Account ID

(Example of patching these using Frida: https://github.com/samuelthomas2774/nxapi-znca-api/blob/09adae38e3ae0425ae7d7478ecb62840f9b802c4/src/android-frida-server/frida-script.cts#L157.)

---

I think I've got f generation working properly, but:

• For coral tokens (hash method 1) the f-generation server now needs the Nintendo Account ID. This can be extracted from the id_token that's already sent, so clients won't need to be updated.
• For web services tokens (hash method 2) the f-generation server needs the Nintendo Account ID and Coral user ID. The Coral user ID can also just be read from the id_token, but the Nintendo Account ID can't and clients will need to be updated to send it.

Nintendo isn't validating the Nintendo Account ID (yet?) so all current clients can still get web service tokens without being updated, but Nintendo might be able to just update the server to check it is set properly.

I'm updating my API to accept na_id (hash method 1/2) and coral_user_id (only 2) values being sent separately for both methods. (I would recommend clients are updated to send these values so they don't have to rely on the server reading them from the JWT/Nintendo not checking one of them.)

[samuelthomas2774]

nxapi-znca-api.fancy.org.uk has now been updated. No changes to clients are necessary immediately, however clients should be updated to send the na_id and coral_user_id fields. The updated API documentation is available at https://github.com/samuelthomas2774/nxapi-znca-api/blob/main/docs/api.md.

nxapi users: I've updated nxapi's remote configuration data. You will need to restart the app (or any long running processes).

https://github.com/samuelthomas2774/nxapi-znca-api/releases/tag/v1.3.0

[samuelthomas2774]

(Updated to add more information about the Java methods used by libvoip.)

[samuelthomas2774]

Coral 2.7.0 changes the obfuscated names of some of the classes and methods that are called by the token generation functions in the native library.

No additional data is used and no changes to clients are required.

Coral authentication (gen_audio_h/hash method 1)

Previous method	New method	Description/purpose
com.nintendo.coral.core.entity.NAUser/c	com.nintendo.coral.core.entity.NAUser/a	Returns the user's Nintendo Account ID
com.nintendo.nx.nasdk.m/d	pb.k/c	Returns the Nintendo Account id_token (the same token passed to gen_audio_h as the first argument)

Web service authentication (gen_audio_h2/hash method 2)

Previous method	New method	Description/purpose
com.nintendo.coral.core.network.e/b	c9.l/b	Returns the Coral token (the same token passed to gen_audio_h2 as the first argument)
za.h/v	ea.a/h	Returns an instance of com.nintendo.coral.core.entity.CoralUser (not renamed), with the a field (not renamed) set to the Coral user ID (other fields are not used) (com.nintendo.coral.models.AccountModel)
com.nintendo.coral.core.entity.NAUser/c	com.nintendo.coral.core.entity.NAUser/a	Returns the user's Nintendo Account ID

(Example of patching these using Frida: https://github.com/samuelthomas2774/nxapi-znca-api/blob/8cf62e95e705b64249321a965bb950281c923c5f/src/android-frida-server/frida-script.cts#L162)

[samuelthomas2774]

Coral 2.8.0 changes the obfuscated names of some of the classes and methods that are called by the token generation functions in the native library.

No additional data is used and no changes to clients are required.

Coral authentication (gen_audio_h/hash method 1)

Previous method	New method	Description/purpose
com.nintendo.coral.core.entity.NAUser/a	com.nintendo.coral.core.entity.NAUser/h	Returns the user's Nintendo Account ID
pb.k/c	bw.j/c	Returns the Nintendo Account id_token (the same token passed to gen_audio_h as the first argument)

Web service authentication (gen_audio_h2/hash method 2)

Previous method	New method	Description/purpose
c9.l/b	s4.l/b	Returns the Coral token (the same token passed to gen_audio_h2 as the first argument)
ea.a/h	ty.a/i	Returns an instance of com.nintendo.coral.core.entity.CoralUser (not renamed), with the p field (renamed from a) set to the Coral user ID (other fields are not used) (com.nintendo.coral.models.AccountModel)
com.nintendo.coral.core.entity.NAUser/a	com.nintendo.coral.core.entity.NAUser/h	Returns the user's Nintendo Account ID

[jellejurre]

I have looked into this more, these are my findings:

the JNI function Java_com_nintendo_coral_core_services_voip_LibvoipJni_genAudioH takes 5 arguments:

• the JNIEnv struct that gets passed through the JNI ABI,
• the object struct (which is ignored since it's a static method)
• and the three jstrings, which get turned into char arrays using JNIEnv_::GetStringUTFChars (in my example called FUN_007babf4),

these char arrays are directly passed into the gen_audio_h native function, like so:

void Java_com_nintendo_coral_core_services_voip_LibvoipJni_genAudioH
        (undefined8 param_1,undefined8 param_2,undefined8 param_3,undefined8 param_4,
            undefined8 param_5)

        {
            long lVar1 = FUN_007babf4(param_1,param_3,0);
            long lVar2 = FUN_007babf4(param_1,param_4,0);
            long lVar3 = FUN_007babf4(param_1,param_5,0);
            if ((((lVar1 != 0)) && (lVar2 != 0)) && (lVar3 != 0)) 
            {
                gen_audio_h(lVar1,lVar2,lVar3,param_1);
                FUN_0077e04c(param_1);
                if (lVar3 != 0) {
                    FUN_0076c984(param_1,param_5,lVar3);
                }
                if (lVar2 != 0) {
                    FUN_0076c984(param_1,param_4,lVar2);
                }
                if (lVar1 != 0) {
                    FUN_0076c984(param_1,param_3,lVar1);
                }
                FUN_007d7ffc(param_1);
                return;
            }
            else
            {
                FUN_0077e04c(param_1,"");
                if (lVar3 != 0) {
                    FUN_0076c984(param_1,param_5,lVar3);
                }
                if (lVar2 != 0) {
                    FUN_0076c984(param_1,param_4,lVar2);
                }
                if (lVar1 != 0) {
                    FUN_0076c984(param_1,param_3,lVar1);
                }
                FUN_007d7ffc(param_1);
                return;
            }
        }

The issue with this is that gen_audio_h is 500k instructions long, and does multiple syscalls to fopen, fclose, and gettimeofday.
I am unsure what these calls are for, but I think that these calls are either verifying that it's running on android or that they depend on android infrastructure, as I have managed to embed the x86 library into my own program (both directly in a c++ program, and in a java program using the JNI), and it hits an infinite loop after calling gettimeofday a few times.

So I think unless someone is able to find out what this giant gen_audio_h function does in the .so file, running it the way we currently do is probably the best we're gonna get.

Note: There is a possibility that the x86 library and the arm64-v8a/armeabi-v7a libraries do something else, but that is hard to find out as I am not as good at debugging on android and tools like ghidra/binaryninja seem to handle those libraries worse, though the general gist of the JNI function seems to be the same.