sysmocom eSIM Manager: User’s Manual

GnuPG supports various pinentry types to prompt for a secret passphrase. If you are using gpg on a remote or headless system, a graphical pinentry will not be useful. Instead, configure the gpg-agent to prompt on the current terminal.

For example, on a Debian system, you may install the pinentry-curses and/or pinentry-tty packages and append
export GPG_TTY=$(tty)
to your terminal shell profile (depending on the shell, this may be ~/.profile, ~/.bashrc, …).

For graphical pinentry, individual packages like pinentry-gnome3, pinentry-gtk2, pinentry-qt etc. match various window managers.

In a terminal window, the following GnuPG command creates a new key pair — make sure to adjust the name and email address! It will ask for a new passphrase using a pinentry dialog.

To make sure gpg outputs only one single public key, identify the correct key by its fingerprint. First list all your keys:

In the output, pick the fingerprint of the correct OpenPGP key — in the following example output, the correct (non-revoked) key has the fingerprint E729A93113DAFCFA74E1C9B07D6817D33ED675F9:

Protect your assets: the OpenPGP private key and your passphrase must not be lost.

To export your private key, use the fingerprint as in section [pgp_fingerprint]. If, for example, your fingerprint were E729A93113DAFCFA74E1C9B07D6817D33ED675F9, then the following commands export your GnuPG private key to the local filesystem — a pinentry dialog may pop up to request your GnuPG passphrase to confirm the export:

The resulting file gnupg_private_key.asc is highly confidential. Keep it safe from access by third parties — paired with your passphrase, it allows decrypting all of your OpenPGP guarded secrets.

You must never upload or enter this private key on any website.

Do not enter this private key on the sysmo-eSIM-manager encryption page. Instead, see section [pgp_pubkey].

After you identified your fingerprint in section [pgp_fingerprint], this command should output your public key:

A public key looks something like this:

The input.csv file’s column names can match eSIM parameter names, to assign them automatically. For matching CSV columns to eSIM parameters, we ignore all whitespace, punctuation and upper/lowercase differences. For example, a column name of "Pin: 1" will match with eSIM parameter PIN1.

Automatic matching is attempted at these times:

The CSV columns don’t have to match parameters. CSV column names may be chosen arbitrarily, and after upload, columns can be manually assigned to parameters, one by one:

Manual column assignments always override the automatic matching, so you may freely mix-and-match automatic and manual column assignments.

If you would like to clean out a parameter to make it available for automatic matching again, you may click the revert icon next to the parameter (small arrow in circle). It only shows when the parameter has been modified.

Choose constant to use the same value for each eSIM.

Algorithm example:

This means that each eSIM in this personalization job will be set to use value 1 for Algorithm, i.e. all eSIMs will use Milenage.

IMSI example: if you run an unusual lab setup where all of your eSIMs should have the same IMSI value:

This means that each eSIM in this personalization job will have the same IMSI, i.e. exactly 901700123456789.

Choose incrementing decimal digits to add +1 to this value for each next eSIM.

IMSI example:

This means that the first eSIM of this personalization job will use 001019999990001 as IMSI, the second will use 001019999990002, the third 001019999990003 and so on.

Choose random decimal digits for values that should be different for each eSIM, where the value is represented in digits 0-9. (For hexadecimal 0-f digits, see [paramsrc_random_hex] instead.)

Your input value usually sets only the count of digits, not the actual value. For example, a value of "0000" has four digits, so it would randomly assign four-digit values to each eSIM, like 9281, 0591, 4235, …
The chosen value for each eSIM is returned in the final output.csv file.

There is a shorthand notation for random decimal digits, so you don’t need to manually count digits in the web form:
you can append * and a number to repeat the entered digits as many times. For example, a value of 0*4 will expand to 0000 and result in random values that are four digits long.

It is possible to specify a range in which to choose random values, using two dots to separate the start and end value of the desired range. For example, 1000..9999 generates four-digit codes that never start with zero.

PIN1 example, long notation:

This means that PIN1 will be four digits long for all of the eSIMs, but will have an unpredictable, distinct value for each individual eSIM.

PUK1 example, shorthand notation:

This means that PUK1 will be eight digits long for all of the eSIMs, but will have an unpredictable, distinct value for each individual eSIM.

IMSI example, range notation:

This means that all IMSIs will start with 001010000009, each ending in hopefully distinct randomized digits 000 to 999.

Choose random hexadecimal digits for values that should be different for each eSIM, where the value is represented in digits 0-F. (For decimal 0-9 digits, see [paramsrc_random] instead.)

Your input value usually sets only the number of digits, not the actual value. For example, a value of "0000" would randomly assign four-digit values to each eSIM, like 9a8f, 0e91, 4235, …
The chosen value for each eSIM is returned in the final output.csv file.

There is a shorthand notation for random hexadecimal digits, so you don’t need to manually count digits in the web form:
you can append * and a number to repeat the entered digits as many times. For example, a value of 00*16 will repeat 00 a total of 16 times. So it expands to 00000000000000000000000000000000.
This will result in random values that are 32 hex digits or 128 bits long.

It is possible to specify a range in which to choose random values, using two dots to separate the start and end value of the desired range. For example, entering 1000..ffff generates four-digit codes that never start with zero.

OPc example, shorthand notation:

This means that OPc will be two times sixteen, i.e. 32 hex digits long for all of the eSIMs, but will have an unpredictable, distinct value for each individual eSIM.

Instead of generating values, you may feed pre-generated values per individual eSIM, by uploading an input CSV file.

The input.csv file format and how to match columns to parameters is described in section [input_csv].

The ICCID is assigned automatically and cannot be configured.

We assign ICCID to your eSIM profiles internally, drawing from the ICCID range officially assigned to sysmocom.

The IMSI, the International Mobile Subscriber Identity, identifies a subscriber on a mobile network.

A valid IMSI value consists of 6 to 15 decimal 0-9 digits, a contrived example:

001020000000003

Here,

Typically, each eSIM has a unique IMSI.

In production networks, IMSI ranges are officially assigned to countries and vendors. You should only use IMSI ranges that are assigned to you, and that are guaranteed to not be in use by anyone else. This is entirely your own responsibility.

In testing networks, you may choose IMSIs freely.

To use a specific IMSI range:

For example, to apply IMSIs 001019999990001 through 001019999990100 to 100 new eSIM profiles:

This means that:

PIN1 is the code that most users encounter when they switch on their mobile device, when PIN1 is required to unlock a SIM card for mobile operation.

It consists of four to eight decimal 0-9 digits, which should be random.

PIN1 is usually configured as random decimal digits, so that each eSIM gets its own random PIN1. You will merely indicate the number of digits in the personalization job form.

The chosen value for each eSIM is returned in the final output.csv file.

For example, if all eSIMs should have the same identical PIN1, recommended only for lab test eSIMs:

This means that all eSIMs will have the same PIN1 of literally 1234. This is not secure and must not be used in this way in a production network.

To configure each eSIM to have a distinct randomized four digit PIN1:

For example, to use six randomized digits:

PIN2 is used for mobile operator security features, such as limiting calls to specific numbers or call cost control.

PIN2 is configured exactly like PIN1, please see [PIN1].

ADM1 is the code that usually allows (depending on the eSIM template) write access to the files, usually not disclosed to consumers.

ADM1 consists of four to eight decimal 0-9 digits, which should be random.

It is configured exactly like PIN1, please see section [PIN1].

ADM2 is configured identically to ADM1 and PIN1, please see section [PIN1].

PUK1 is the main PIN unlocking code, which a user needs when the PIN1 has been entered incorrectly for too many times in a row.

It consists of exactly eight decimal 0-9 digits, which should be random.

Like PIN1, PUK1 is usually configured as random decimal digits, so that each eSIM gets its own random PUK1. For PUK1, you need to configure exactly eight decimal 0-9 digits.

The chosen value for each eSIM is returned in the final output.csv file.

To configure each eSIM to have a distinct randomized PUK1:

If all eSIMs should have an identical PUK1, recommended only for lab testing:

This means that all eSIMs will have a PUK1 of 12345678. This is not secure and must not be used in this way in a production network.

PUK2 is the PIN2 unlocking code.

PUK2 is configured identically to PUK1, please see section [PUK1].

Algorithm selects the authentication and key agreement (AKA) algorithm that the uSIM uses to authenticate and encrypt signalling on the mobile network.

These AKA algorithms are available, as specified by 3GPP:

See also [K], [OPc].

K (or Ki) is the subscriber’s personal key that is used for the algorithms described in [Algorithm].

It consists of 32 hexadecimal 0-f digits (16 octets), and should be random.

K is usually configured as random hexadecimal digits, so that each eSIM gets its own random key.

The chosen value for each eSIM is returned in the final output.csv file.

For example, to configure each eSIM to have a distinct value for K:

This will produce 32 hexadecimal 0-f digits (16 octets), randomly chosen for each individual eSIM.

If all eSIMs should have an identical K, recommended only for lab testing:

This means that all eSIMs will have an identical K of 0102030405060708090a0b0c0d0e0f10. This is not secure and must not be used in this way in a production network.

Like K, OPc is used by the algorithm chosen for parameter Algorithm.

OPc can be used as OP, or as OPC, which depends entirely on the mobile operator. Historically, OP was the "Operator Key" and was identical for all subscribers. OPC is a combination of the unique K and the common OP, to form an OPC that is again unique for each subscriber.

OPc is the same length as and configured exactly like K, please see section [K].

Security domain keys usually come in three components: ENC, MAC and DEK (indicated by the Key ID). Each of ENC, MAC, DEK is a key that is either 16, 24 or 32 octets long — that is, either 32, 48 or 64 hexadecimal 0-f digits, corresponding to 128, 192 and 256 bit key lengths, respectively. Each of these keys should be random and unique in a production environment.

Security domain keys are specific to a given Secure Channel Protocol (SCP) and a Key Version Number (KVN).

Each SCP type can have multiple instances, indicated by differing KVN. Each SCP-KVN pair in turn has its components identified by key-ids (usually indicating ENC, MAC and DEK).

Here is a list of some common SDKey configurations:

The personalization job form will display only those keys that are useful in the chosen eSIM template.

For each SDKey, there are as many eSIM parameters as there are key components. For example, for SCP80-KVN01-AES, you will find:

Make sure you configure all three of them.

For example, to set up an SCP80 KVN 0x01 key of AES type using the maximum supported key length:

This means that each eSIM will have its own distinct SCP80 KVN 0x01 key material, generated randomly and individually for each eSIM and each key component.

If all the eSIMs should have identical keys for SCP80 KVN 0x01, recommended only for lab tests:

This means that all eSIMs will have the same, identical key for all of SCP80 KVN 0x1 ENC, MAC and DEK, which will all be exactly 16 bytes of 00112233445566778899aabbccddeeff. This is not secure and must not be used in this way in a production network.

For real-world production use of your eSIM profiles, choose GSMA certified SM-DP+ (Invigo).

The usual eUICC in consumer devices require eSIM profiles to be signed by the GSMA certificate authority. This is why eSIM profiles intended for production use need to be published at a GSMA certified SM-DP+.

For lab testing environments, where privacy and authentication is not a concern, it is cheaper to use the Test SM-DP+ (sysmocom).

The Test SM-DP+ uses testing certificates as specified in GSMA SGP.26. It can be installed on eUICC We offer both a GSMA certified SM-DP+ upload for production use, as well as a lab testing SM-DP+ using SGP.26 Test Certificates.