feat: add support for SUCI in NAI format

[DomenicoVerde]

Summary

3GPP TS 24 501 defines four different SUPI Formats to be sent as SUCI in the NAS 5GS Mobile Identity IE [1]: IMSI (International Mobile Subscriber Identity), NSI (Network Specific Identifier), GCI (Global Cable Identifier), and GLI (Global Line Identifier). If the SUPI format is set to NSI, the SUCI is encoded as an NAI constructed as specified in Section 28.7.3 of 3GPP TS 23.003 [2]. This pull request updates the free5gc/nas module to include the support of SUCI in NAI format.

Motivation

Actually, Free5GC supports only the IMSI format for the SUPI. When the SUCI is encoded in NSI format, the naiToString() function only adds the prefix "nai-1-" and appends the SUCI NAI field. With this pull request, the SuciToStringWithError() function is updated to detect the SUPI format. If the SUPI format is of type NSI, the naiToString() function is called to parse the SUCI NAI field and construct the SUCI UTF-8 string to be sent to the UDM API (via the supiOrSuci parameter) as specified in TS 29 503 Annex C [3]. As a result, UEs can also authenticate using the SUCI in NAI format in the 5G NAS Registration Request.

Changes

• Added SupiFormatGCI and SupiFormatGLI types in NAS_CommInfoIE.go.
• Updated SuciToStringWithError() function to distinguish between SUPI formats: IMSI, NAI, GCI, and GLI.
• Updated naiToString() function to parse SUCI in NAI format.
• Added some tests taken directly from the 3GPP TS [2,3] in MobileIdentity5GS_test.go.

Validation

Validation is performed through: (1) the test cases provided in MobileIdentity5GS_test.go, and (2) Free5GC (commit 69ba98ff8eba69a8092c56abb80a01fcd483e7b3). More specifically, registration_test.go has been extended with a new test case in which a UE completes the registration procedure using a SUCI in NAI format. If this is of interest, I can open a pull request in the free5gc/free5gc module to share the additional test.

Notes

• The Decorated NAI used in roaming scenarios is still not supported (Ref. 3GPP TS 123 003 Section 28.7.9.1).
• With a bit of further effort it is also possible to add the support of SUPI formats: CGI, and GLI (as specified in 3GPP TS 123 003 Sections 28.15 and 28.16).

References

1. 3GPP TS 124 501 Section 9.11.3.4 (5GS Mobile Identity IE).
2. 3GPP TS 123 003 Sections 28.7.3 (NAI format for SUCI), 28.7.6 (NAI used for 5G registration via trusted non-3GPP access), 28.7.7 (NAI used by N5CW devices via trusted non-3GPP access), 28.7.12 (NAI used for 5G NSWO).
3. 3GPP TS 129 503 Annex C (SUCI encoding).

[Copilot]

Pull request overview

Adds proper parsing/formatting support for SUCI encoded in NAI format (NSI/NAI-based SUCI) so the module can produce the correct supiOrSuci string for UDM APIs per 3GPP specs.

Changes:

• Add SUPI format constants for GCI/GLI alongside IMSI/NAI.
• Update SuciToStringWithError() to branch on SUPI format and parse NAI-formatted SUCI into the UDM suci-... string form.
• Replace the previous “nai-1-” behavior with a structured NAI parser and add multiple spec-derived unit tests.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

File	Description
nasMessage/NAS_CommInfoIE.go	Adds missing SUPI format constants (GCI/GLI) used for format discrimination.
nasConvert/MobileIdentity5GS.go	Implements NAI username@realm parsing to construct UDM-facing suci-... strings and returns PLMN when derivable.
nasConvert/MobileIdentity5GS_test.go	Replaces legacy NAI-hex test with multiple 3GPP-derived NAI SUCI examples and negative cases.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.