Add companion whitepaper: Operator Token Acquisition for Number Verification on Android (TS.43/OpenID4VP)

[albertoramosmonagas]

What type of PR is this?

Add one of the following kinds:

• documentation

What this PR does / why we need it:

Adds a technical whitepaper describing the end-to-end Operator Token acquisition flow for Number Verification on Android, including TS.43, OpenID4VP, Digital Credentials API and JWT Bearer usage.

The document is intended as complementary implementation guidance and does not modify the CAMARA Number Verification API specification. It is informative, not normative, and fills the gap left by NV 2.1 regarding how an operatorToken is obtained and exchanged prior to calling the API.

Which issue(s) this PR fixes:

Fixes #237

Special notes for reviewers:

This document is informative/companion material, not a change to the NV API definition or YAML. Placement in this repository reflects where the work originated; there is an open discussion about eventually hosting this and similar cross-spec companion material in a dedicated whitepaper/reference repository rather than inside individual API Sub Project repos. Reviewers from Commonalities and ICM are encouraged to confirm alignment with the JWT Bearer flow as currently documented.

Changelog input

release-note
Added companion whitepaper: Operator Token Acquisition for Number Verification on Android (TS.43 / OpenID4VP / Digital Credentials API / JWT Bearer). Informative only; does not modify the NV API specification.

Additional documentation

This section can be blank.

docs

[AxelNennker]

The language could be clearer, I think, what is a "specification" and what is a recommendation.
The description of the PR writes "informative" but the language of the whitepater says "this specification".

[albertoramosmonagas]

The language could be clearer, I think, what is a "specification" and what is a recommendation.
The description of the PR writes "informative" but the language of the whitepater says "this specification.

Thanks for the feedback, Axel. Are you referring to a specific part of the document, or is this a general comment based on what you've seen throughout the document?

[bigludo7]

Hello @albertoramosmonagas
We will take a deep look with the team - this is great work. Thanks !
I have a comment probably close to Axel one about the document objective: is it a specification (that must be enforced) or a guide to help ? I tend to think that it should be initially a guide but as such we should state it explicitly. As you use standardises word for example in your text you're probably see it as a specification.

I have one first comment/question on the detail: Do you have rational to perform the phoneNumber retrieval from the tempToken in step 3 of your flow and not in the 4? I do not have a clear response on that. We have implement this way in some of our countries but I'm struggling to answer when IT architects told that is a Resource Server job and not AS one...

[bigludo7]

Another one (checked with @chatelgu) - in step (3) POST /token (from Application to the Aggregator) it is confusing to use operatortoken as sub type while 1/it is not an operator token (this is a openidv4 token) and 2/ the 'real' operator token is used in the next flow between the aggregator and the CSP auth server. Should defined here another name like vp_token? the assertion will be: assertion = JWT{sub=vp_token:SD-JWT}

Another option is to have in the assertion a dedicated vp_token claim.

[diegotid]

Hi @bigludo7

Once aligned internally at TEF, we thumb up to using vp_token as a prefix to the sub claim

Regarding the previous comment, our rational is as follows:

• We want the flow to be the same for both verify and retrieve, specifically regarding obtaining the access token.
• For verify, we don't want to/can't provide an access token without having identified the line. Therefore, in step 3, we absolutely have to query the entitlement server to find out which line it is (and thus the MSISDN).
• Since we've already done this in that step, we avoid doing it in step 4 (service API).
• So, it makes sense to do the same in retrieve, even though intuitively the data isn't returned until step 4. The access token still needs to have three legs (and therefore the MSISDN must be obtained in step 3).

What are your thoughts, guys?

[albertoramosmonagas]

Hi @bigludo7, @AxelNennker. Thanks for the feedback — pushed a revision addressing it:

• Informative guide, not a specification: status stated explicitly, RFC 2119 softened, "standardises" → "describes".
• Step-3 sub prefix → vp_token: App → Aggregator now uses vp_token:<SD-JWT>; Aggregator → CSP keeps operatortoken:<temp_token>.
• §5.4 rationale: the CAMARA access token is three-legged, so the MSISDN is resolved at step 3; same flow for verify and device-phone-number. Marked provisional.
• Aggregator → CSP hop now references the CAMARA JWT Bearer Flow with Operator Token as the source of the interface.

[kwokonn-looi]

Hi @albertoramosmonagas

Is there a typo in the end-to-end flows in Step 4? It's stated the Application calls the NV API directly but it's the Host: < aggregator-host > that's shown.

Our understanding would be that following Step 3, after the MNO access_token is obtained by the Aggregator, the Aggregator may correspondingly return the aggregator_access_token to the Application. Then in Step 4, the Application calls the Aggregator's API endpoint with the aggregator_access_token, and subsequently the Aggregator maps this to the MNO access_token to call the MNO's API endpoint (as per the standard CAMARA flows with an aggregator).

In this way,

• the Application is still integrated with the Aggregator and calls the Aggregator's API endpoints. The Application does not need to track the MNO's API endpoints per market (especially for global brands).
• the API consumption can be charged correctly by the MNO in relation to the Aggregator, and correspondingly between the Aggregator and the Application. Otherwise, the MNO and the Application may not have the processes properly established for the API consumption.
• the standard onboarding processes between the Aggregator and MNO, and between the Application and the Aggregator are already in place.

I'm not sure if the above is your intention for these flows.

[diegotid]

Hi @kwokonn-looi

You’re absolutely right with your arguments. That’s precisely why Step 4 instructs the application to make its service API request to the aggregator host, rather than the MNOs.

My guess on where the confusion might come from imho, is that many aggregators are not exposing raw CAMARA APIs and thus the understanding of "calling /number-verification/v2/device-phone-number directly" for them is that such call is expected to be performed on the MNOs host.

The white paper though, in the Step 4 description, refers to calling the NV API directly on the aggregator host with the aggregator's provided access_token. Maybe "directly" may result confusing here since it is not grammatically needed, or access_token could be referred to as aggregator_access_token, or it is actually the aggregator exposing raw CAMARA NV API what is confusing.

What's your thoughts on what could be reworded for better understanding?

[kwokonn-looi]

Hi @diegotid

Thanks for your understanding.

If possible, I'd propose to start with the end-to-end flow diagrams since the Application and the Aggregator are present and separated (unlike in the ICM docs). The Step 4 flows (e.g. GET /device-phone-number) may then be split from Application -> Aggregator, and then Aggregator -> CSP NV API, along with the respective API responses per leg.

In the Step 4 text section, you may then opt to describe each of these legs. This should then bring clarity to the Step 4 flows.

[albertoramosmonagas]

Hi @kwokonn-looi,

Thanks, this is a fair point and we appreciate the suggestion. Our sense is that the split you describe is already reflected in the sequence diagrams: both the §3 overview and the detailed Appendix A diagram model the Application and the Aggregator as separate participants (Appendix A even splits App Frontend / App Backend / Aggregator / CSP), so each hop already appears as its own arrow with its own response.

For Step 4 specifically, we have reworded the text so it is explicit that the Application calls the Aggregator's NV endpoint, and the Aggregator then maps the request to the MNO/CSP NV API internally — the same aggregator pattern used in Step 3. With that wording change, we think the per-leg behaviour is clear without adding separate diagrams that would duplicate what the participant columns already distinguish.

So we would propose to keep the current representation as is. If any specific leg still reads ambiguously to you, point us at it and we will refine that spot.

CC: @diegotid

[albertoramosmonagas]

Hi @bigludo7, any points from your side? can we proceed with merge this PR?

[ToshiWakayama-KDDI]

Hi @alberto, @ludovic, @axel,

My sincere apologies for the late comment.

From KDDI's perspective, our development team has identified a few security concerns regarding the TS.43 Temporary Token.

If everyone agrees, we believe it would be highly valuable to add the following points to the whitepaper to address these concerns written in the form of a proposal:

Subject: Proposed Revision on the Security Considerations and Trust Model: Addressing Temp Token Injection Attacks via Compromised OS and the Associated MNO/Aggregator Responsibility

We propose adding explicit descriptions regarding the risk of "Temp Token Injection Attacks" leveraging compromised Android OS (e.g., rooted devices) and the subsequent responsibilities of Mobile Network Operators (MNOs) to mitigate this threat.

1. Mechanism of the Temp Token Injection Attack

To fully understand the systemic risk, it is necessary to outline the mechanics of this attack vector. The attack exploits a compromised OS to bypass the JWE (JSON Web Encryption) protection intended for inter-aggregator security:

(1) Token Acquisition: An attacker operates or colludes with a malicious "Aggregator A", which holds a legitimate contract with the MNO. Aggregator A requests and obtains a valid temp_token for a victim's MSISDN from the MNO.

(2) Execution on Compromised OS: The attacker uses a compromised device (e.g., a rooted Android device). On this device, a legitimate Service Provider's app (which utilizes a trustworthy "Aggregator B") initiates the Number Verification flow.

(3) OS-Level Injection & Forged Encryption: The compromised OS intercepts the underlying credential generation process. Instead of requesting a new token from the MNO for Aggregator B, the OS injects the valid temp_token previously acquired by Aggregator A. The compromised OS then encrypts this injected token using Aggregator B's public key.

(4) Authentication Bypass: The legitimate app receives the forged Operator Token and sends it to Aggregator B. Aggregator B successfully decrypts the JWE, finds a valid temp_token, and forwards it to the MNO. The MNO validates the token, resulting in a successful, fraudulent authentication against the legitimate Service Provider.

2. Divergence of the Trust Model: SMS-OTP vs. Number Verification (NV2.0)

In the traditional SMS-OTP authentication flow, Service Providers (SPs) select and contract their own SMS delivery aggregators. Consequently, if an aggregator commits fraud or is compromised, the SP bears a certain degree of responsibility for their choice of partner, and SPs retain the ability to defend themselves by selecting trustworthy aggregators.

However, in the context of NV2.0, the "Temp Token Injection Attack" detailed above completely invalidates this self-defense assumption. In this scenario, even if the victimized SP has acted with due diligence and selected a highly trustworthy partner (Aggregator B), they cannot prevent the fraud. The SP is entirely defenseless against attacks originating from other compromised or malicious aggregators (Aggregator A) within the broader MNO ecosystem.

3. Definition of MNO Responsibility and Contractual Enforcement

Since the root cause of this attack vector relies on the precondition that "an MNO has an active contract with a malicious or inadequately audited aggregator (Aggregator A)," the ultimate responsibility for ensuring the integrity of the ecosystem lies with the MNOs. SPs cannot self-defend against this risk.
Therefore, we highly recommend that this Whitepaper explicitly mandate the following requirements in the Trust Model:

• MNO Due Diligence: MNOs must assume full responsibility for conducting rigorous, ongoing vetting, due diligence, and security auditing of all contracted aggregators.
• Enforceable Trust Anchor Framework: MNOs must establish a legally and systemically binding framework to manage a whitelist of trusted aggregators. This framework must enable the immediate revocation of API access and contract termination upon detecting any malicious activity or policy violations.
• Mandatory Device Attestation: Along with enforcing strict aggregator management, the whitepaper should advocate for the mandatory verification of device integrity (e.g., via Play Integrity API or equivalent hardware-backed Device Attestation) at the aggregator level.

4. Exploring Transition to Alternative Secure Protocols such as TS.43 ap2015

Finally, to fundamentally eliminate the risk of OS-level token injection, we recommend that the industry consider transitioning to, or offering, a more secure protocol architecture—such as the one defined in GSMA TS.43 ap2015—as a viable long-term option.

The current protocol's reliance on the device OS as a critical part of the trust chain creates an inherent vulnerability to client-side attacks. In contrast, the TS.43 ap2015 flow structurally mitigates this risk by shifting the critical token exchange away from the device. In that model, a pre-authorized app token is exchanged for an operator token via a direct, secure backend channel between the aggregator and the MNO.
By adopting an architecture that does not depend on the integrity of the client-side environment for its core security, the systemic risks associated with token spoofing on compromised devices can be definitively addressed.

Apologies for the long sentences.
Please let me know your thoughts on this.

Best regards,
Toshi

[pendula95]

Hi @alberto, @ludovic, @axel,

My sincere apologies for the late comment.

From KDDI's perspective, our development team has identified a few security concerns regarding the TS.43 Temporary Token.

If everyone agrees, we believe it would be highly valuable to add the following points to the whitepaper to address these concerns written in the form of a proposal:

Subject: Proposed Revision on the Security Considerations and Trust Model: Addressing Temp Token Injection Attacks via Compromised OS and the Associated MNO/Aggregator Responsibility

We propose adding explicit descriptions regarding the risk of "Temp Token Injection Attacks" leveraging compromised Android OS (e.g., rooted devices) and the subsequent responsibilities of Mobile Network Operators (MNOs) to mitigate this threat.

1. Mechanism of the Temp Token Injection Attack

To fully understand the systemic risk, it is necessary to outline the mechanics of this attack vector. The attack exploits a compromised OS to bypass the JWE (JSON Web Encryption) protection intended for inter-aggregator security:

(1) Token Acquisition: An attacker operates or colludes with a malicious "Aggregator A", which holds a legitimate contract with the MNO. Aggregator A requests and obtains a valid temp_token for a victim's MSISDN from the MNO.

(2) Execution on Compromised OS: The attacker uses a compromised device (e.g., a rooted Android device). On this device, a legitimate Service Provider's app (which utilizes a trustworthy "Aggregator B") initiates the Number Verification flow.

(3) OS-Level Injection & Forged Encryption: The compromised OS intercepts the underlying credential generation process. Instead of requesting a new token from the MNO for Aggregator B, the OS injects the valid temp_token previously acquired by Aggregator A. The compromised OS then encrypts this injected token using Aggregator B's public key.

(4) Authentication Bypass: The legitimate app receives the forged Operator Token and sends it to Aggregator B. Aggregator B successfully decrypts the JWE, finds a valid temp_token, and forwards it to the MNO. The MNO validates the token, resulting in a successful, fraudulent authentication against the legitimate Service Provider.

2. Divergence of the Trust Model: SMS-OTP vs. Number Verification (NV2.0)

In the traditional SMS-OTP authentication flow, Service Providers (SPs) select and contract their own SMS delivery aggregators. Consequently, if an aggregator commits fraud or is compromised, the SP bears a certain degree of responsibility for their choice of partner, and SPs retain the ability to defend themselves by selecting trustworthy aggregators.

However, in the context of NV2.0, the "Temp Token Injection Attack" detailed above completely invalidates this self-defense assumption. In this scenario, even if the victimized SP has acted with due diligence and selected a highly trustworthy partner (Aggregator B), they cannot prevent the fraud. The SP is entirely defenseless against attacks originating from other compromised or malicious aggregators (Aggregator A) within the broader MNO ecosystem.

3. Definition of MNO Responsibility and Contractual Enforcement

Since the root cause of this attack vector relies on the precondition that "an MNO has an active contract with a malicious or inadequately audited aggregator (Aggregator A)," the ultimate responsibility for ensuring the integrity of the ecosystem lies with the MNOs. SPs cannot self-defend against this risk. Therefore, we highly recommend that this Whitepaper explicitly mandate the following requirements in the Trust Model:

* **MNO Due Diligence**: MNOs must assume full responsibility for conducting rigorous, ongoing vetting, due diligence, and security auditing of all contracted aggregators.

* **Enforceable Trust Anchor Framework**: MNOs must establish a legally and systemically binding framework to manage a whitelist of trusted aggregators. This framework must enable the immediate revocation of API access and contract termination upon detecting any malicious activity or policy violations.

* **Mandatory Device Attestation**: Along with enforcing strict aggregator management, the whitepaper should advocate for the mandatory verification of device integrity (e.g., via Play Integrity API or equivalent hardware-backed Device Attestation) at the aggregator level.

4. Exploring Transition to Alternative Secure Protocols such as TS.43 ap2015

Finally, to fundamentally eliminate the risk of OS-level token injection, we recommend that the industry consider transitioning to, or offering, a more secure protocol architecture—such as the one defined in GSMA TS.43 ap2015—as a viable long-term option.

The current protocol's reliance on the device OS as a critical part of the trust chain creates an inherent vulnerability to client-side attacks. In contrast, the TS.43 ap2015 flow structurally mitigates this risk by shifting the critical token exchange away from the device. In that model, a pre-authorized app token is exchanged for an operator token via a direct, secure backend channel between the aggregator and the MNO. By adopting an architecture that does not depend on the integrity of the client-side environment for its core security, the systemic risks associated with token spoofing on compromised devices can be definitively addressed.

Apologies for the long sentences. Please let me know your thoughts on this.

Best regards, Toshi

There are some facts that you are not taking in to account.
Output of the Android API Verify phone numbers with digital credentials is not temporary/operator token. It is vp_token. vp_token is a SD-JWT. Any tempering of this token would be detected by legit aggregator B in the verification process. Even if this is done on a rooted device. Only assumption that needs to be stated is the aggregators ALWAYS receive vp_token via sub claim of assertion.

[ToshiWakayama-KDDI]

Hi @pendula95 ,

Thank you for the clarification. I have discussed it internally with our development team.

We think we are discussing two different security properties.

We fully agree that tampering of an issued SD-JWT / vp_token is detectable, since the Aggregator validates the Issuer JWT signature, Binding JWT signature, nonce, aud and sd_hash.

Our concern is different: context binding of the temp_token itself.

In the current flow, the Aggregator decrypts the JWE and obtains a valid TS.43 temp_token. However, there is no mechanism that allows Aggregator B to verify that this temp_token was originally obtained for:

• Aggregator B,
• the corresponding credential_authorization_jwt,
• or the current verification transaction.

Therefore, even if all SD-JWT-level validation succeeds, we do not see how Aggregator B can determine whether the decrypted temp_token was originally obtained in the same Aggregator, authorization, and transaction context.

That is the specific residual risk we are referring to.

Hope the above makes sense to you.

Best Regards,

[jgarciahospital]

Hi @ToshiWakayama-KDDI,

Thank you for the detailed analysis. Let us provide some feedback on the points you raised, to complement the great explanation of @pendula95 .

First, we based all the process in the fact that the aggregator is a trusted partner, therefore this aggregator is included in the OS allowlist for the temporary_token generation, and also this aggregator receives CAMARA credentials for the temporary_token usage in a CAMARA API.

Without those two stages jointly enabled, any aggregator or other partner cannot make any action:

• Neither generate a temporary_token,as the allowlist blocks it.
• Nor use an already generated temporary_token, as credentials for CAMARA API will not be enabled.

Going over the original points:

1. Mechanism of the Temp Token Injection Attack

If all contracted aggregators implement the specification correctly, the injection is blocked by four independent bindings:

• VP-token is bound to the aggregator in the OS generation process, ensuring that only that aggregator is able to decrypt it and ensuring that the valid aggregator (that aggregator who has a trusted relationship with the telco.
• Credential cannot be forged on-device. The Issuer JWT is signed by Android Telephony using a TEE/StrongBox-resident key provisioned by the carrier. The Binding JWT is signed by a device-bound attested key referenced in cnf. A rooted OS does not hold those keys — this is the same hardware boundary that protects hardware-backed passkeys and Google Wallet credentials — and cannot assemble a credential that passes §5.1 verification. GMS additionally applies its own pre-execution integrity check before initiating any TS.43 acquisition.
• aud binds the credential to the calling application. The Aggregator verifies that the aud — set by Telephony to the APK signing certificate hash of the application that invoked CredentialManager — matches the registered origin. A credential cannot be replayed into a different application's flow.
• nonce and consent_data_hash bind it to the specific request and to consent actually shown. The nonce must match the one issued for that session; the consent hash proves the permission dialog was displayed to the user before the token was issued.

It's, of course, a matter of the aggregator to properly protect the temporary_token once it's decripted from the vp_token package.

---

2. Divergence of the Trust Model

Considering previous point, a Service Provider can make sure that as long as the Channel Partner is a trusted one, as per relationship with MNOs, the service is also protected properly from malicious Channel Partners and as well from malicious ASP, as both app binding and CP binding protects the token.

---

3. MNO Responsibility and Contractual Enforcement

We agree the document should make MNO governance obligations explicit. We will add to §8 and Appendix B.1: explicit requirements for ongoing Aggregator auditing and for revocation capability at both the GMS whitelist layer and the CAMARA Auth Server layer — either of which is independently sufficient to block a compromised Aggregator. We will also add a recommendation that Aggregators implement Play Integrity API verification as a defense-in-depth measure at Step 1 or Step 3.

---

4. TS.43 ap2015 as an alternative

This is a endless discussion about two alternatives that depends on MNO decision. Whether ap2014 (just generate a temporaryToken that can be exchanged for MSISDN info) or ap2015 (generate a temporaryToken that, after eligibility, is translated into a Operator Token that finally gives access to the info) is right now just a matter of MNO decision, as currently OS not support full ap2015 flow (eligibility and app binding in OS-ECS token generation). What is clear is that both current models, if used together with CAMARA, are safe enough as CAMARA authentication protects the access to the API info, so fully eligibility for the information exchange is still imposed.

As a future evolution, integrating the full ap2015 flow — including eligibility signalling from the OS layer — could provide end-to-end token traceability that complements the current design. That said, the current TS.43 flow combined with CAMARA already addresses the core concern. The protection therefore exists by design, provided two conditions hold: the Aggregator validates that binding when decrypting the encrypted_credential JWE, and the temp_token is not exposed in plaintext to other aggregators. Any other Aggregator that did obtain a temp_token would still need valid credentials registered at the CAMARA Auth Server to redeem it — meaning the CAMARA layer acts as the final containment boundary regardless.