Guide: Managing GP Keys
=======================

Most of today's smartcards follow the GlobalPlatform Card Specification and the included Security Domain model.
UICCs and eUCCCs are no exception here.

The Security Domain acts as an on-card representative of a card authority or administrator. It is used to perform tasks
like the installation of applications or the provisioning and rotation of secure channel keys. It also acts as a secure
key storage and offers all kinds of cryptographic services to applications that are installed under a specific
Security Domain (see also GlobalPlatform Card Specification, section 7).

In this tutorial, we will show how to work with the key material (keysets) stored inside a Security Domain and how to
rotate (replace) existing keys. We will also show how to provision new keys.

.. warning:: Making changes to keysets requires extreme caution as misconfigured keysets may lock you out permanently.
	     It's also strongly recommended to maintain at least one backup keyset that you can use as fallback in case
	     the primary keyset becomes unusable for some reason.


Selecting a Security Domain
~~~~~~~~~~~~~~~~~~~~~~~~~~~

A typical smartcard, such as an UICC will have one primary Security Domain, called the Issuer Security Domain (ISD).
When working with those cards, the ISD will show up in the UICC filesystem tree as `ADF.ISD` and can be selected like
any other file.

::

   pySIM-shell (00:MF)> select ADF.ISD
   {
      "application_id": "a000000003000000",
      "proprietary_data": {
         "maximum_length_of_data_field_in_command_message": 255
      }
   }

When working with eUICCs, multiple Security Domains are involved. The model is fundamentally different from the classic
model with one primary Security Domain (ISD). In the case of eUICCs, an ISD-R (Issuer Security Domain - Root) and an
ISD-P (Issuer Security Domain - Profile) exist (see also: GSMA SGP.02, section 2.2.1).

The ISD-P is established by the ISD-R during the profile installation and serves as a secure container for an eSIM
profile. Within the ISD-P the eSIM profile establishes a dedicated Security Domain called `MNO-SD` (see also GSMA
SGP.02, section 2.2.4). This `MNO-SD` is comparable to the Issuer Security Domain (ISD) we find on UICCs. The AID of
`MNO-SD` is either the default AID for the Issuer Security Domain (see also GlobalPlatform, section H.1.3) or a
different value specified by the provider of the eSIM profile.

Since the AID of the `MNO-SD` is not a fixed value, it is not known by `pySim-shell`. This means there will be no
`ADF.ISD` file shown in the file system, but we can simply select the `ADF.ISD-R` first and then select the `MNO-SD`
using a raw APDU. In the following example we assume that the default AID (``a000000151000000``) is used  The APDU
would look like this: ``00a4040408`` + ``a000000151000000`` + ``00``

::

   pySIM-shell (00:MF)> select ADF.ISD-R
   {
       "application_id": "a0000005591010ffffffff8900000100",
       "proprietary_data": {
           "maximum_length_of_data_field_in_command_message": 255
       },
       "isdr_proprietary_application_template": {
           "supported_version_number": "020300"
       }
   }
   pySIM-shell (00:MF/ADF.ISD-R)> apdu 00a4040408a00000015100000000
   SW: 9000, RESP: 6f108408a000000151000000a5049f6501ff

After that, the prompt will still show the `ADF.ISD-R`, but we are actually in `ADF.ISD` and the standard GlobalPlatform
operations like `establish_scpXX`, `get_data`, and `put_key` should work. By doing this, we simply have tricked
`pySim-shell` into making the GlobalPlatform related commands available for some other Security Domain we are not
interested in. With the raw APDU we then have swapped out the Security Domain under the hood. The same workaround can
be applied to any Security Domain, provided that the AID is known to the user.


Establishing a secure channel
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Before we can make changes to the keysets in the currently selected Security Domain we must first establish a secure
channel with that Security Domain. In the following examples we will use `SCP02` (see also GlobalPlatform Card
Specification, section E.1.1) and `SCP03` (see also GlobalPlatform Card Specification – Amendment D) to establish the
secure channel. `SCP02` is slightly older than `SCP03`. The main difference between the two is that `SCP02` uses 3DES
while `SCP03` is based on AES.

.. warning:: Secure channel protocols like `SCP02` and `SCP03` may manage an error counter to count failed login
	     attempts. This means attempting to establish a secure channel with a wrong keyset multiple times may lock
	     you out permanently. Double check the applied keyset before attempting to establish a secure channel.

.. warning:: The key values used in the following examples are random key values used for illustration purposes only.
	     Each UICC or eSIM profile is shipped with individual keys, which means that the keys used below will not
	     work with your UICC or eSIM profile. You must replace the key values with the values you have received
	     from your UICC vendor or eSIM profile provider.


Example: `SCP02`
----------------

In the following example, we assume that we want to establish a secure channel with the ISD of a `sysmoUSIM-SJA5` UICC.
Along with the card we have received the following keyset:

+---------+----------------------------------+
| Keyname | Keyvalue                         |
+=========+==================================+
| ENC/KIC | F09C43EE1A0391665CC9F05AF4E0BD10 |
+---------+----------------------------------+
| MAC/KID | 01981F4A20999F62AF99988007BAF6CA |
+---------+----------------------------------+
| DEK/KIK | 8F8AEE5CDCC5D361368BC45673D99195 |
+---------+----------------------------------+

This keyset is tied to the key version number KVN 122 and is configured as a DES keyset. We can use this keyset to
establish a secure channel using the SCP02 Secure Channel Protocol.

::

    pySIM-shell (00:MF/ADF.ISD)> establish_scp02 --key-enc F09C43EE1A0391665CC9F05AF4E0BD10 --key-mac 01981F4A20999F62AF99988007BAF6CA --key-dek 8F8AEE5CDCC5D361368BC45673D99195  --key-ver 112 --security-level 3
    Successfully established a SCP02[03] secure channel


Example: `SCP03`
----------------

The establishment of a secure channel via SCP03 works just the same. In the following example we will establish a
secure channel to the `MNO-SD` of an eSIM profile. The SCP03 keyset we use is tied to KVN 48 and looks like this:

+---------+------------------------------------------------------------------+
| Keyname | Keyvalue                                                         |
+=========+==================================================================+
| ENC/KIC | 63af517c29ad6ac6fcadfe6ac8a3c8a041d8141c7eb845ef1cba6112a325e430 |
+---------+------------------------------------------------------------------+
| MAC/KID | 54b9ad6713ae922f54014ed762132e7b59bdcd2a2a6beba98fb9afe6b4df27e1 |
+---------+------------------------------------------------------------------+
| DEK/KIK | cbb933ba2389da93c86c112739cd96389139f16c6f80f7d16bf3593e407ca893 |
+---------+------------------------------------------------------------------+

We assume that the `MNO-SD` is already selected (see above). We may now establish the SCP03 secure channel:

::

   pySIM-shell (00:MF/ADF.ISD-R)> establish_scp03 --key-enc 63af517c29ad6ac6fcadfe6ac8a3c8a041d8141c7eb845ef1cba6112a325e430 --key-mac 54b9ad6713ae922f54014ed762132e7b59bdcd2a2a6beba98fb9afe6b4df27e1 --key-dek cbb933ba2389da93c86c112739cd96389139f16c6f80f7d16bf3593e407ca893 --key-ver 48 --security-level 3
   Successfully established a SCP03[03] secure channel



Understanding Keysets
~~~~~~~~~~~~~~~~~~~~~

Before making any changes to keysets, it is recommended to check the status of the currently installed keysets. To do
so, we use the `get_data` command to retrieve the `key_information`. This command does not require the establishment of
a secure channel. We also cannot read back the key values themselves, but we get a summary of the installed keys
together with their KVN numbers, IDs, algorithm and key length values.

Example: `key_information` from a `sysmoISIM-SJA5`:

::

    pySIM-shell (SCP02[03]:00:MF/ADF.ISD)> get_data key_information
    {
        "key_information": [
            {
                "key_information_data": {
                    "key_identifier": 1,
                    "key_version_number": 112,
                    "key_types": [
                        {
                            "type": "des",
                            "length": 16
                        }
                    ]
                }
            },
            {
                "key_information_data": {
                    "key_identifier": 2,
                    "key_version_number": 112,
                    "key_types": [
                        {
                            "type": "des",
                            "length": 16
                        }
                    ]
                }
            },
            {
                "key_information_data": {
                    "key_identifier": 3,
                    "key_version_number": 112,
                    "key_types": [
                        {
                            "type": "des",
                            "length": 16
                        }
                    ]
                }
            },
            {
                "key_information_data": {
                    "key_identifier": 1,
                    "key_version_number": 1,
                    "key_types": [
                        {
                            "type": "des",
                            "length": 16
                        }
                    ]
                }
            },
            {
                "key_information_data": {
                    "key_identifier": 2,
                    "key_version_number": 1,
                    "key_types": [
                        {
                            "type": "des",
                            "length": 16
                        }
                    ]
                }
            },
            {
                "key_information_data": {
                    "key_identifier": 3,
                    "key_version_number": 1,
                    "key_types": [
                        {
                            "type": "des",
                            "length": 16
                        }
                    ]
                }
            },
            {
                "key_information_data": {
                    "key_identifier": 1,
                    "key_version_number": 2,
                    "key_types": [
                        {
                            "type": "des",
                            "length": 16
                        }
                    ]
                }
            },
            {
                "key_information_data": {
                    "key_identifier": 2,
                    "key_version_number": 2,
                    "key_types": [
                        {
                            "type": "des",
                            "length": 16
                        }
                    ]
                }
            },
            {
                "key_information_data": {
                    "key_identifier": 3,
                    "key_version_number": 2,
                    "key_types": [
                        {
                            "type": "des",
                            "length": 16
                        }
                    ]
                }
            },
            {
                "key_information_data": {
                    "key_identifier": 1,
                    "key_version_number": 47,
                    "key_types": [
                        {
                            "type": "des",
                            "length": 16
                        }
                    ]
                }
            },
            {
                "key_information_data": {
                    "key_identifier": 2,
                    "key_version_number": 47,
                    "key_types": [
                        {
                            "type": "des",
                            "length": 16
                        }
                    ]
                }
            },
            {
                "key_information_data": {
                    "key_identifier": 3,
                    "key_version_number": 47,
                    "key_types": [
                        {
                            "type": "des",
                            "length": 16
                        }
                    ]
                }
            }
        ]
    }

Example: `key_information` from a `sysmoEUICC1-C2T`:

::

    pySIM-shell (SCP03[03]:00:MF/ADF.ISD-R)> get_data key_information
    {
        "key_information": [
            {
                "key_information_data": {
                    "key_identifier": 3,
                    "key_version_number": 50,
                    "key_types": [
                        {
                            "type": "aes",
                            "length": 32
                        }
                    ]
                }
            },
            {
                "key_information_data": {
                    "key_identifier": 2,
                    "key_version_number": 50,
                    "key_types": [
                        {
                            "type": "aes",
                            "length": 32
                        }
                    ]
                }
            },
            {
                "key_information_data": {
                    "key_identifier": 1,
                    "key_version_number": 50,
                    "key_types": [
                        {
                            "type": "aes",
                            "length": 32
                        }
                    ]
                }
            },
            {
                "key_information_data": {
                    "key_identifier": 2,
                    "key_version_number": 64,
                    "key_types": [
                        {
                            "type": "aes",
                            "length": 16
                        }
                    ]
                }
            },
            {
                "key_information_data": {
                    "key_identifier": 1,
                    "key_version_number": 64,
                    "key_types": [
                        {
                            "type": "tls_psk",
                            "length": 16
                        }
                    ]
                }
            }
        ]
    }

The output from those two examples above may seem lengthy, but in order to move on and to provision own keys
successfully, it is important to understand each aspect of it.

Key Version Number (KVN)
------------------------

Each key is associated with a Key Version Number (KVN). Multiple keys that share the same KVN belong to the same
keyset. In the first example above we can see that four keysets with KVN numbers 112, 1, 2 and 47 are provisioned.
In the second example we see two keysets. One with KVN 50 and one with KVN 64.

The term "Key Version Number" is misleading as this number is not really a version number. It's actually a unique
identifier for a specific keyset that also defines with which Secure Channel Protocol a key can be used. This means
that the KVN is not just an arbitrary number. The following (incomplete) table gives a hint which KVN numbers may be
used with which Secure Channel Protocol.

+-----------+-------------------------------------------------------+
| KVN range | Secure Channel Protocol                               |
+===========+=======================================================+
| 1-15      | reserved for `SCP80` (OTA SMS)                        |
+-----------+-------------------------------------------------------+
| 17        | reserved for DAP specified in ETSI TS 102 226         |
+-----------+-------------------------------------------------------+
| 32-47     | reserved for `SCP02`                                  |
+-----------+-------------------------------------------------------+
| 48-63     | reserved for `SCP03`                                  |
+-----------+-------------------------------------------------------+
| 64-79     | reserved for `SCP81` (GSMA SGP.02, section 2.2.5.1)   |
+-----------+-------------------------------------------------------+
| 112       | Token key (RSA public or DES, also used with `SCP02`) |
+-----------+-------------------------------------------------------+
| 113       | Receipt key (DES)                                     |
+-----------+-------------------------------------------------------+
| 115       | DAP verification key (RS public or DES)               |
+-----------+-------------------------------------------------------+
| 116       | reserved for CASD                                     |
+-----------+-------------------------------------------------------+
| 117       | 16-byte DES key for Ciphered Load File Data Block     |
+-----------+-------------------------------------------------------+
| 255       | reserved for ISD with SCP02 without SCP80 support     |
+-----------+-------------------------------------------------------+

With that we can now understand that in the first example, the first and the last keyset is intended to be used with
`SCP02` and that the second and the third keyset is intended to be used with `SCP80` (OTA SMS). In the second example we
can see that the first keyset is intended to be used with `SCP03`, wheres the second should be usable with `SCP81`.


Key Identifier
--------------

Each keyset consists of a number of keys, where each key has a different Key Identifier. The Key Identifier is usually
an incrementing number that starts counting at 1. The Key Identifier is used to distinguish the keys within the keyset.
The exact number of keys and their attributes depends on the secure channel protocol for which the keyset is intended
for. Each secure channel protocol may have its specific requirements on how many keys of which which type, length or
Key Identifier have to be present.

However, almost all of the classic secure channel protocols (including  `SCP02`, `SCP03` and `SCP81`) make use of the
following three-key scheme:

+----------------+---------+---------------------------------------+
| Key Identifier | Keyname | Purpose                               |
+================+=========+=======================================+
| 1              | ENC/KIC | encryption/decryption                 |
+----------------+---------+---------------------------------------+
| 2              | MAC/KID | cryptographic checksumming/signing    |
+----------------+---------+---------------------------------------+
| 3              | DEK/KIK | encryption/decryption of key material |
+----------------+---------+---------------------------------------+

In this case, all three keys share the same length and are used with the same algorithm. The key length is often used
to implicitly select sub-types of an algorithm. (e.g. a 16 byte key of type `aes` is associated with `AES128`, where a 32
byte key would be associated with `AES256`).

The second example shows that different schemes are possible. The `SCP80` keyset from the second example uses a scheme
that works with two keys:

+----------------+---------+---------------------------------------+
| Key Identifier | Keyname | Purpose                               |
+================+=========+=======================================+
| 1              | TLS-PSK | pre-shared key used for TLS           |
+----------------+---------+---------------------------------------+
| 2              | DEK/KIK | encryption/decryption of key material |
+----------------+---------+---------------------------------------+

It should also be noted that the order in which keysets and keys appear is an implementation detail of the UICC/eUICC
O/S. The order has no influence on how a keyset is interpreted. Only the Key Version Number (KVN) and the Key Identifier
matter.


Rotating a keyset
~~~~~~~~~~~~~~~~~

Rotating keys is one of the most basic tasks one might want to perform on an UICC/eUICC before using it productively. In
the following example we will illustrate how key rotation can be done. When rotating keys, only the key itself may
change. For example it is not possible to change the key length or the algorithm used (see also GlobalPlatform Card
Specification, section 11.8.2.3.3). Any key of the current Security Domain can be rotated, this also includes the key
that was used to establish the secure channel.

In the following example we assume that the Security Domain is selected and a secure channel is already established. We
intend to rotate the keyset with KVN 112. Since this keyset uses triple DES keys with a key length of 16, we must
replace it with a keyset with keys of the same nature.

The new keyset shall look like this:

+----------------+---------+----------------------------------+
| Key Identifier | Keyname | Keyvalue                         |
+================+=========+==================================+
| 1              | ENC/KIC | 542C37A6043679F2F9F71116418B1CD5 |
+----------------+---------+----------------------------------+
| 2              | MAC/KID | 34F11BAC8E5390B57F4E601372339E3C |
+----------------+---------+----------------------------------+
| 3              | DEK/KIK | 5524F4BECFE96FB63FC29D6BAAC6058B |
+----------------+---------+----------------------------------+

When passing the keys to the `put_key` commandline, we set the Key Identifier of the first key using the `--key-id`
parameter. This Key Identifier will be valid for the first key (KIC) we pass. For all consecutive keys, the Key
Identifier will be incremented automatically (see also GlobalPlatform Card Specification, section 11.8.2.2). To Ensure
that the new KIC, KID and KIK keys get the correct Key Identifiers, it is crucial to maintain order when passing the
keys in the `--key-data` arguments. It is also important that each `--key-data` argument is preceded by a `--key-type`
argument that sets the algorithm correctly (`des` in this case).

Finally we have to target the keyset we want to rotate by its KVN. The `--old-key-version-nr` argument is set to 112
as this identifies the keyset we want to rotate. The `--key-version-nr` is also set to 112 as we do not want
KVN to be changed in this example. Changing the KVN while rotating a keyset is possible. In case the KVN has to change
for some reason, the new KVN must be selected carefully to keep the key usable with the associated Secure Channel
Protocol.

The commandline that matches the keyset we had laid out above looks like this:
::

   pySIM-shell (SCP02[03]:00:MF/ADF.ISD)> put_key --key-id 1 --key-type des --key-data 542C37A6043679F2F9F71116418B1CD5 --key-type des --key-data 34F11BAC8E5390B57F4E601372339E3C --key-type des --key-data 5524F4BECFE96FB63FC29D6BAAC6058B --old-key-version-nr 112 --key-version-nr 112

After executing this put_key commandline, the keyset identified by KVN 122 is equipped with new keys. We can use
`get_data key_information` to inspect the currently installed keysets. The output should appear unchanged as
we only swapped out the keys. All other parameters, identifiers etc. should remain constant.

.. warning:: It is technically possible to rotate a keyset in a `non atomic` way using one `put_key` commandline for
	     each key. However, in case the targeted keyset is the one used to establish the current secure channel,
	     this method should not be used since, depending on the UICC/eUICC model, half-written key material may
	     interrupt the current secure channel.


Removing a keyset
~~~~~~~~~~~~~~~~~

In some cases it is necessary to remove a keyset entirely. This can be done with the `delete_key` command. Here it is
important to understand that `delete_key` only removes one specific key from a specific keyset. This means that you
need to run a separate `delete_key` command for each key inside a keyset.

In the following example we assume that the Security Domain is selected and a secure channel is already established. We
intend to remove the keyset with KVN 112. This keyset consists of three keys.

::

   pySIM-shell (SCP02[03]:00:MF/ADF.ISD)> delete_key --key-ver 112 --key-id 1
   pySIM-shell (SCP02[03]:00:MF/ADF.ISD)> delete_key --key-ver 112 --key-id 2
   pySIM-shell (SCP02[03]:00:MF/ADF.ISD)> delete_key --key-ver 112 --key-id 3

To verify that the keyset has been deleted properly, we can use the `get_data key_information` command to inspect the
current status of the installed keysets. We should see that the key with KVN 112 is no longer present.


Adding a keyset
~~~~~~~~~~~~~~~

In the following we will discuss how to add an entirely new keyset. The procedure is almost identical with the key
rotation procedure we have already discussed and it is assumed that all details about the key rotation are understood.
In this section we will go into more detail and illustrate how to provision new 3DES, `AES128` and `AES256` keysets.

It is important to keep in mind that storage space on smartcard is a precious resource. In many cases the amount of
keysets that a Security Domain can store is limited. In some situations you may be forced to sacrifice one of your
existing keysets in favor of a new keyset.

The main difference between key rotation and the adding of new keys is that we do not simply replace an existing key.
Instead an entirely new key is programmed into the Security Domain. Therefore the `put_key` commandline will have no
`--old-key-version-nr` parameter. From the commandline perspective, this is already the only visible difference from a
commandline that simply rotates a keyset. Since we are writing an entirely new keyset, we are free to chose the
algorithm and the key length within the parameter range permitted by the targeted secure channel protocol. Otherwise
the same rules apply.

For reference, it should be mentioned that it is also possible to add or rotate keyset using multiple `put_key`
commandlines. In this case one `put_key` commandline for each key is used. Each commandline will specify `--key-id` and
`--key-version-nr` and one `--key-type` and `--key-data` tuple. However, when rotating or adding a keyset step-by-step,
the whole process happens in a `non-atomic` way, which is less reliable. Therefore we will favor the `atomic method`

In the following examples we assume that the Security Domain is selected and a secure channel is already established.


Example: `3DES` key for `SCP02`
-------------------------------

Let's assume we want to provision a new 3DES keyset that we can use for SCP02. The keyset shall look like this:

+----------------+---------+----------------------------------+
| Key Identifier | Keyname | Keyvalue                         |
+================+=========+==================================+
| 1              | ENC/KIC | 542C37A6043679F2F9F71116418B1CD5 |
+----------------+---------+----------------------------------+
| 2              | MAC/KID | 34F11BAC8E5390B57F4E601372339E3C |
+----------------+---------+----------------------------------+
| 3              | DEK/KIK | 5524F4BECFE96FB63FC29D6BAAC6058B |
+----------------+---------+----------------------------------+

The keyset shall be a associated with the KVN 46. We have made sure before that KVN 46 is still unused and that this
KVN number is actually suitable for SCP02 keys. As we are using 3DES, it is obvious that we have to pass 3 keys with 16
byte length.

To program the key, we may use the following commandline. As we can see, this commandline is almost the exact same as
the one from the key rotation example where we were rotating a 3DES key. The only difference is that we didn't specify
an old KVN number and that we have chosen a different KVN.

::

   pySIM-shell (SCP02[03]:00:MF/ADF.ISD)> put_key --key-id 1 --key-type des --key-data 542C37A6043679F2F9F71116418B1CD5 --key-type des --key-data 34F11BAC8E5390B57F4E601372339E3C --key-type des --key-data 5524F4BECFE96FB63FC29D6BAAC6058B --key-version-nr 46

In case of success, the keyset should appear in the `key_information` among the other keysets that are already present.

::

    pySIM-shell (SCP02[03]:00:MF/ADF.ISD)> get_data key_information
    {
        "key_information": [
            {
                "key_information_data": {
                    "key_identifier": 1,
                    "key_version_number": 46,
                    "key_types": [
                        {
                            "type": "des",
                            "length": 16
                        }
                    ]
                }
            },
            {
                "key_information_data": {
                    "key_identifier": 2,
                    "key_version_number": 46,
                    "key_types": [
                        {
                            "type": "des",
                            "length": 16
                        }
                    ]
                }
            },
            {
                "key_information_data": {
                    "key_identifier": 3,
                    "key_version_number": 46,
                    "key_types": [
                        {
                            "type": "des",
                            "length": 16
                        }
                    ]
                }
            },
            ...
        ]
    }


Example: `AES128` key for `SCP80`
---------------------------------

In this example we intend to provision a new `AES128` keyset that we can use with SCP80 (OTA SMS). The keyset shall look
like this:

+----------------+---------+----------------------------------+
| Key Identifier | Keyname | Keyvalue                         |
+================+=========+==================================+
| 1              | ENC/KIC | 542C37A6043679F2F9F71116418B1CD5 |
+----------------+---------+----------------------------------+
| 2              | MAC/KID | 34F11BAC8E5390B57F4E601372339E3C |
+----------------+---------+----------------------------------+
| 3              | DEK/KIK | 5524F4BECFE96FB63FC29D6BAAC6058B |
+----------------+---------+----------------------------------+

In addition to that, we want to associate this key with KVN 3. We have inspected the currently installed keysets before
and made sure that KVN 3 is still unused. We are also aware that for SCP80 we may only use KVN values from 1 to 15.

For `AES128`, we specify the algorithm using the `--key-type aes` parameter. The selection between `AES128` and `AES256` is
done implicitly using the key length. Since we want to use `AES128` in this case, all three keys have a length of 16 byte.

::

   pySIM-shell (SCP02[03]:00:MF/ADF.ISD)> put_key --key-id 1 --key-type aes --key-data 542C37A6043679F2F9F71116418B1CD5 --key-type aes --key-data 34F11BAC8E5390B57F4E601372339E3C --key-type aes --key-data 5524F4BECFE96FB63FC29D6BAAC6058B --key-version-nr 3

In case of success, the keyset should appear in the `key_information` among the other keysets that are already present.

::

    pySIM-shell (SCP02[03]:00:MF/ADF.ISD)> get_data key_information
    {
        "key_information": [
            {
                "key_information_data": {
                    "key_identifier": 1,
                    "key_version_number": 3,
                    "key_types": [
                        {
                            "type": "aes",
                            "length": 16
                        }
                    ]
                }
            },
            {
                "key_information_data": {
                    "key_identifier": 2,
                    "key_version_number": 3,
                    "key_types": [
                        {
                            "type": "aes",
                            "length": 16
                        }
                    ]
                }
            },
            {
                "key_information_data": {
                    "key_identifier": 3,
                    "key_version_number": 3,
                    "key_types": [
                        {
                            "type": "aes",
                            "length": 16
                        }
                    ]
                }
            },
            ...
        ]
    }


Example: `AES256` key for `SCP03`
---------------------------------

Let's assume we want to provision a new `AES256` keyset that we can use for SCP03. The keyset shall look like this:

+----------------+---------+------------------------------------------------------------------+
| Key Identifier | Keyname | Keyvalue                                                         |
+================+=========+==================================================================+
| 1              | ENC/KIC | 542C37A6043679F2F9F71116418B1CD5542C37A6043679F2F9F71116418B1CD5 |
+----------------+---------+------------------------------------------------------------------+
| 2              | MAC/KID | 34F11BAC8E5390B57F4E601372339E3C34F11BAC8E5390B57F4E601372339E3C |
+----------------+---------+------------------------------------------------------------------+
| 3              | DEK/KIK | 5524F4BECFE96FB63FC29D6BAAC6058B5524F4BECFE96FB63FC29D6BAAC6058B |
+----------------+---------+------------------------------------------------------------------+

In addition to that, we assume that we want to associate this key with KVN 51. This KVN number falls in the range of
48 - 63 and is therefore suitable for a key that shall be usable with SCP03. We also made sure before that KVN 51 is
still unused.

With that we can go ahead and make up the following commandline:
::

   pySIM-shell (SCP02[03]:00:MF/ADF.ISD)> put_key --key-id 1 --key-type aes --key-data 542C37A6043679F2F9F71116418B1CD5542C37A6043679F2F9F71116418B1CD5 --key-type aes --key-data 34F11BAC8E5390B57F4E601372339E3C34F11BAC8E5390B57F4E601372339E3C --key-type aes --key-data 5524F4BECFE96FB63FC29D6BAAC6058B5524F4BECFE96FB63FC29D6BAAC6058B --key-version-nr 51

In case of success, we should see the keyset in the `key_information`

::

    pySIM-shell (SCP02[03]:00:MF/ADF.ISD)> get_data key_information
    {
        "key_information": [
            {
                "key_information_data": {
                    "key_identifier": 1,
                    "key_version_number": 51,
                    "key_types": [
                        {
                            "type": "aes",
                            "length": 32
                        }
                    ]
                }
            },
            {
                "key_information_data": {
                    "key_identifier": 2,
                    "key_version_number": 51,
                    "key_types": [
                        {
                            "type": "aes",
                            "length": 32
                        }
                    ]
                }
            },
            {
                "key_information_data": {
                    "key_identifier": 3,
                    "key_version_number": 51,
                    "key_types": [
                        {
                            "type": "aes",
                            "length": 32
                        }
                    ]
                }
            },
            ...
        ]
    }


Example: `AES128` key for `SCP81`
---------------------------------

In this example we will show how to provision a new `AES128` keyset for `SCP81`. We will provision this keyset under
KVN 64. The keyset we intend to apply shall look like this:

+----------------+---------+----------------------------------+
| Key Identifier | Keyname | Keyvalue                         |
+================+=========+==================================+
| 1              | TLS-PSK | 000102030405060708090a0b0c0d0e0f |
+----------------+---------+----------------------------------+
| 2              | DEK/KIK | 000102030405060708090a0b0c0d0e0f |
+----------------+---------+----------------------------------+

With that we can put together the following command line:

::

    put_key --key-id 1 --key-type tls_psk --key-data 000102030405060708090a0b0c0d0e0f --key-type aes --key-data 000102030405060708090a0b0c0d0e0f --key-version-nr 64

In case of success, the keyset should appear in the `key_information` as follows:

::

    pySIM-shell (SCP03[03]:00:MF/ADF.ISD-R)> get_data key_information
    {
        "key_information": [
            ...,
            {
                "key_information_data": {
                    "key_identifier": 2,
                    "key_version_number": 64,
                    "key_types": [
                        {
                            "type": "aes",
                            "length": 16
                        }
                    ]
                }
            },
            {
                "key_information_data": {
                    "key_identifier": 1,
                    "key_version_number": 64,
                    "key_types": [
                        {
                            "type": "tls_psk",
                            "length": 16
                        }
                    ]
                }
            }
        ]
    }
