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.