From ccc1a047abfd367c2a906cee1733b998b115d6a3 Mon Sep 17 00:00:00 2001
From: Neels Hofmeyr <nhofmeyr@sysmocom.de>
Date: Sat, 1 Mar 2025 03:58:31 +0100
Subject: [PATCH] personalization: set example input values

For all ConfigurableParameter subclasses, provide an example_input.

This may be useful for downstream projects' user interaction, to suggest
a value or prefill an input field, as appropriate.

Related: SYS#6768
Change-Id: I2672fedcbc32cb7a6cb0c233a4a22112bd9aae03
---
 pySim/esim/saip/personalization.py | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/pySim/esim/saip/personalization.py b/pySim/esim/saip/personalization.py
index 943784f6..54aaa435 100644
--- a/pySim/esim/saip/personalization.py
+++ b/pySim/esim/saip/personalization.py
@@ -115,6 +115,7 @@ class ConfigurableParameter(abc.ABC, metaclass=ClassVarMeta):
     min_len = None
     max_len = None
     allow_len = None # a list of specific lengths
+    example_input = None
 
     def __init__(self, input_value=None):
         self.input_value = input_value # the raw input value as given by caller
@@ -306,6 +307,7 @@ class Iccid(DecimalParam):
     name = 'ICCID'
     min_len = 18
     max_len = 20
+    example_input = '998877665544332211'
 
     @classmethod
     def validate_val(cls, val):
@@ -326,6 +328,7 @@ class Imsi(DecimalParam):
     name = 'IMSI'
     min_len = 6
     max_len = 15
+    example_input = '00101' + ('0' * 10)
 
     @classmethod
     def apply_val(cls, pes: ProfileElementSequence, val):
@@ -497,6 +500,7 @@ class Puk(DecimalHexParam):
     allow_len = 8
     rpad = 16
     keyReference = None
+    example_input = '0' * allow_len
 
     @classmethod
     def apply_val(cls, pes: ProfileElementSequence, val):
@@ -523,6 +527,7 @@ class Pin(DecimalHexParam):
     rpad = 16
     min_len = 4
     max_len = 8
+    example_input = '0' * max_len
     keyReference = None
 
     @staticmethod
@@ -546,9 +551,10 @@ class Pin(DecimalHexParam):
 
 class Pin1(Pin):
     name = 'PIN1'
+    example_input = '0' * 4  # PIN are usually 4 digits
     keyReference = 0x01
 
-class Pin2(Pin):
+class Pin2(Pin1):
     name = 'PIN2'
     keyReference = 0x81
 
@@ -568,7 +574,7 @@ class Adm1(Pin):
     name = 'ADM1'
     keyReference = 0x0A
 
-class Adm2(Pin):
+class Adm2(Adm1):
     name = 'ADM2'
     keyReference = 0x0B
 
@@ -591,6 +597,7 @@ class AlgoConfig(ConfigurableParameter):
 class AlgorithmID(DecimalParam, AlgoConfig):
     algo_config_key = 'algorithmID'
     allow_len = 1
+    example_input = 1  # Milenage
 
     @classmethod
     def validate_val(cls, val):
@@ -606,6 +613,7 @@ class K(BinaryParam, AlgoConfig):
     name = 'K'
     algo_config_key = 'key'
     allow_len = (128 // 8, 256 // 8) # length in bytes (from BinaryParam); TUAK also allows 256 bit
+    example_input = '00' * allow_len[0]
 
 class Opc(K):
     name = 'OPc'
@@ -618,6 +626,7 @@ class MilenageRotationConstants(BinaryParam, AlgoConfig):
     name = 'MilenageRotation'
     algo_config_key = 'rotationConstants'
     allow_len = 5 # length in bytes (from BinaryParam)
+    example_input = '0a 0b 0c 0d 0e'
 
     @classmethod
     def validate_val(cls, val):
@@ -641,6 +650,11 @@ class MilenageXoringConstants(BinaryParam, AlgoConfig):
     name = 'MilenageXOR'
     algo_config_key = 'xoringConstants'
     allow_len = 80 # length in bytes (from BinaryParam)
+    example_input = ('00000000000000000000000000000000'
+                     ' 00000000000000000000000000000001'
+                     ' 00000000000000000000000000000002'
+                     ' 00000000000000000000000000000004'
+                     ' 00000000000000000000000000000008')
 
 class TuakNumberOfKeccak(IntegerParam, AlgoConfig):
     """Number of iterations of Keccak-f[1600] permutation as recomended by Section 7.2 of 3GPP TS 35.231"""
@@ -648,3 +662,4 @@ class TuakNumberOfKeccak(IntegerParam, AlgoConfig):
     algo_config_key = 'numberOfKeccak'
     min_val = 1
     max_val = 255
+    example_input = '1'