Soracom Arc

Managing Virtual SIM Credentials

In order establish a secure connection between your device and Soracom, your device's WireGuard client must be configured with a unique private and public key, and the public key must be attached to the Virtual SIM. When your device attempts to connect to Soracom, Arc will then authenticate the device using the attached public key.

Crucially, the private key should not be distributed, as anyone with this private key may be able to impersonate the real device.

When creating a new Virtual SIM, Arc will automatically generate a unique set of private and public keys for your device. Since the User Console and Soracom API/CLI are secured using modern encryption protocols, these keys remain safe when Arc transmits them to your browser or as an API/CLI response.

Although the private key is temporarily visible on your computer so that you can copy it to your device, there is typically minimal security risk with this process.

When using the Soratun command line tool to bootstrap a device, the generated private and public keys are sent directly to the device.

However, for an additional layer of protection, you can generate your own set of private and public keys directly on your device, and then attach the public key to your Virtual SIM. While this process requires a few additional steps, it also ensures that the private key never leaves your device.

If you simply want to use a new set of private and public keys without generating it on the device, you can also generate it on the User Console or through the Soracom API/CLI. Arc will automatically attach the new public key to your Virtual SIM.

When attaching a custom public key or generating a new set of private and public keys, Arc will overwrite the previous public key attached to your Virtual SIM. As a result, your device will no longer be able to communicate with Soracom until your device's Arc configuration is updated with the new client private and public keys.

Attaching a Custom Public Key

The following instructions apply for both Standalone Virtual SIMs and Subscription Container Virtual SIMs.

  1. Login to the User Console. From the Menu, open the SIM Management screen.

  2. From the list of subscribers, click the for the SIM you want to manage, then click the Details button.

  3. From the SIM Details dialog, click the Virtual SIM tab, then click the Credentials section.

  4. From the Update credentials panel, enter the Public Key that you want to attach to the Virtual SIM. Then click Save Public Key.

Once your device's WireGuard configuration is updated with the new set of private and public keys, it will be able to connect to Soracom.

Generating New Credentials

The following instructions apply for both Standalone Virtual SIMs and Subscription Container Virtual SIMs.

  1. Login to the User Console. From the Menu, open the SIM Management screen.

  2. From the list of subscribers, click the for the SIM you want to manage, then click the Details button.

  3. From the SIM Details dialog, click the Virtual SIM tab, then click the Credentials section.

  4. From the Update credentials panel, click Generate credentials.

  5. Once Arc has generated the credentials, the private and public key will be displayed. Update the Arc configuration on your device and reconnect.

    The private key will be displayed only once, and you must make sure to copy the private key to your device.

    Your device will not be able to communicate with the Soracom platform using the Virtual SIM until the configuration has been updated.

    The steps for updating and reconnecting depend on your connection method:

    Connection Method How to update the Arc configuration and reconnect
    Connecting using Soratun Update the Soratun configuration file (e.g. /path/to/arc.json) or perform bootstrapping again, then reconnect using Soratun
    Other WireGuard client Update the WireGuard configuration file (e.g. /etc/wireguard/wg0.conf), then reconnect using your WireGuard client

    If you bootstrapped with Soratun, you can also update the Arc configuration and reconnect with the same bootstrap procedure as before. Refer to the following for further information.

Programmatic Usage

In addition to attaching a custom public key to or generating new credentials for Virtual SIMs from the User Console, you can also perform the same actions programmatically using the Soracom API or CLI.

Soracom API

To access the Soracom API, first use the auth API to obtain an API Key and Token. Refer to the API Reference Guide for instructions on how to use the API Key and Token in API requests.

Then, use the renewArcSimCredentials API to register a custom public key to the Virtual SIM:

curl -X PUT \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  -H 'Content-Type: application/json' \
>  -d '{
>        "arcClientPeerPublicKey": "<PUBLIC-KEY>",
>      }' \
>  https://g.api.soracom.io/v1/sims/<SIM-ID>/credentials/arc

If you want Arc to generate a new set of private and public keys for your Virtual SIM, use the same renewArcSimCredentials API and simply pass in an empty object:

curl -X PUT \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  -H 'Content-Type: application/json' \
>  -d '{}' \
>  https://g.api.soracom.io/v1/sims/<SIM-ID>/credentials/arc

Arc will return a response containing the generated private and public keys.

Soracom CLI

To use the Soracom CLI, you must first configure it to authenticate with your account information, authorization key, or SAM user credentials.

Then, run the following command to register a custom public key to the Virtual SIM:

soracom sims renew-arc-credentials --sim-id "<SIM-ID>" --arc-client-peer-public-key "<PUBLIC-KEY>" --coverage-type g

If you want Arc to generate a new set of private and public keys for your Virtual SIM, use the same renew-arc-credentials command and simply omit the --arc-client-peer-public-key parameter:

soracom sims renew-arc-credentials --sim-id "<SIM-ID>" --coverage-type g

Arc will return a response containing the generated private and public keys.