Key Infrastructure and PIN Code Management

Private Key Management

Venly creates a private and public keypair whenever a Wallet is created through the Wallet-API. The public key is the wallet address (e.g. 0x123123123) that is openly shareable, allowing anyone to send funds to it.

The private key acts as the "password" to access and control the wallet's funds. It should be kept secure and not shared with anyone to prevent unauthorized access to the wallet and its funds.

Knowing the private key will give you access to all digital assets linked to this wallet. The private key is encrypted with a passphrase and securely stored in our system. The following diagram explains the steps.

The private key is first encrypted with a random passphrase. The passphrase is then split into two different shares, using the Shamir Secret Sharing algorithm.

The two shares are explained below.

User-Owned Share

This share refers to the ownership exclusively held by the user. To further enhance security, this share undergoes an extra layer of encryption using a secret chosen by the user (such as the PIN code provided during wallet creation). Following this, the encrypted user-owned share is stored securely in a Key-Vault.

Because of the extra encryption, only the user can access this share. By providing the correct PIN code (or other signing method), the user can decrypt and use the user-owned share and application share, to access the private key.

As a result, the security measures ensure that only the rightful user can decrypt and access the private key, safeguarding the wallet and its funds.

Application Share

A share owned by Venly and securely stored in a Key-Vault. You, as a customer, receive this share along with a Client ID and Client Secret.

Accessing the Private Key

To access the private key, ownership has to be proven of the 2 shares. (User-owned and application share)

The user-owned share (decrypted using the user's PIN code) and the application share are utilized to reconstruct the passphrase and decrypt the private key.

Hereafter the private key can be used to execute the requested functions (e.g. performing a crypto transfer, signing transactions, etc.)

All shares are encrypted and securely stored in a "Vault" (Key Management system).

📘
You can always export the private key of a created wallet if you like (e.g., provide it to the user).

PIN Code

When using the Wallet-API to create a wallet, including a PIN code is mandatory. This PIN code is critical in enabling the user to carry out functions on their wallets.

PIN code uses:

Firstly, the PIN code grants your users access to their wallets.
Secondly, if a user forgets any of their signingmethods (emergency_code, biometrics), the PIN code serves as a recovery mechanism.
The PIN code also allows your users to sign signature requests and authorize transactions.
As described earlier, the PIN code plays a role in encrypting the user-owned share.

📘
In addition to the PIN code, your users can also perform all the mentioned functions using other signing methods, such as the emergency code and biometrics.

PIN Code Management

The PIN code's significance lies in being the gateway for your users to access and interact with their wallets, making its secure management imperative.

Proper handling and safeguarding of the PIN code are essential to ensure the security and confidentiality of the user's wallet and assets.

Based on different use cases, we will discuss some recommendations for managing the PIN code.

Use cases involving interaction from user side

The initial three use cases will involve scenarios where user interaction is necessary to interact with the wallets.

1) User creates PIN code (when major user interaction is needed)

Use case scenario:

In this scenario, the PIN code functionality is accessible to the user. Upon wallet creation, the user is required to input their PIN code, which is then utilized to generate their wallets.

Once the user provides their PIN code, it is securely passed through the Wallet-API to create their wallets. This ensures that the PIN code is not stored in plain text and remains confidential throughout the wallet creation procedure.

Provide clear guidelines on creating a strong and unique PIN which should be 6 digits long. Encourage them to avoid using easily guessable combinations like birthdates or repetitive sequences.

Wallet Creation Flow:

The user enters their PIN code at the time of wallet creation
You create a wallet with the user’s PIN code
You never store the PIN code

User Interaction with Wallet Flow:

The user needs to provide the PIN code, whenever they want to interact with their wallet
You use the PIN code to call the necessary Venly-endpoints

2) User creates another secret: password (used for a good user experience)

Use case scenario:

When aiming to maintain a high level of security without exposing the PIN code functionality to the user, a viable solution is to employ encryption while utilizing a user-known secret, such as a password.

To enhance user experience, a seamless approach involves allowing users to set a password during the signup process with your app. This way, the same password they use to access your app can be utilized as the user-known secret to encrypt and decrypt their PIN code.

This implementation simplifies the authentication process for users, as they only need to remember one password to access your application and their wallets.

🚧
It will be your responsibility to validate and ensure the password's strength. Additionally, you will need to handle the encryption and decryption of the user's PIN code using their chosen password.

It is essential to employ strong encryption algorithms and follow industry best practices for data protection. Utilizing hashing algorithms, salting techniques, and encryption standards helps ensure that both the password and the encrypted PIN code remain highly secure.

Wallet Creation Flow:

Your app generates a random PIN code
You create the wallet with the generated PIN code
You encrypt the generated PIN code with a user-known secret (a password they provide)
You store the encrypted PIN code

User Interaction with Wallet Flow:

User enters their user-known secret (password)
You decrypt the stored encrypted PIN code with the provided user-secret (password)
Use the decrypted PIN code to call the necessary Venly-endpoints

3) User creates another secret: biometric (used for mobile devices)

Use case scenario:

In the context of a mobile app, you can utilize the biometric capabilities inherent in the user's mobile phone to establish and safeguard wallets.

By integrating biometric features such as fingerprint recognition or facial authentication, you can offer a secure and convenient method for your users to create and access their wallets, enhancing the overall user experience.

Wallet Creation Flow:

Create user's wallet with a random PIN code
Request biometric authentication from the user
Link the biometric to the wallet using the biometric ID
Store the biometric ID

User Interaction with Wallet Flow:

Request biometric authentication from the user
Use the biometric ID to call the necessary Venly-endpoints

Use cases involving minimal or no interaction from user side

The following three use cases will involve scenarios where minimal or no user interaction is required to interact with the wallets.

4) Create a Master PIN for all wallets (when you want to interact with wallets without user interaction)

Use case scenario:

Another viable option is to employ a master PIN for each wallet created on behalf of your users. Unlike the previous method, where users were involved in choosing their PIN codes, this approach eliminates their direct input.

This enables you to interact with the wallets without user involvement. This approach grants you greater control over the wallets' functionality.

Example Use Case:

By adopting this approach, you can implement a feature for periodic payments. An automated transfer is initiated on the user's wallet at defined intervals, facilitating seamless recurring transactions.
Furthermore, this method let's you to distribute NFTs (Non-Fungible Tokens) directly to your users' wallets. This capability allows for efficient and secure distribution of unique digital assets without user involvement.

This method is suggested primarily for cases where direct interaction with wallets is necessary, and user involvement is not required.

Employing a master PIN for each created wallet introduces potential security risks. Caution should be exercised when using this approach, and thorough security measures should be implemented to mitigate any vulnerabilities.

Wallet Creation Flow:

You create a master PIN
You use the same master PIN to create wallets

5) Sending emergency code to user (when minimal user interaction is needed)

Use case scenario:

Another viable alternative to consider is the implementation of Venly's emergency code mechanism. Venly offers users the ability to generate an emergency code, either through manual input or automatic generation.

The emergency code needs to be 25 characters long to ensure high entropy.

This emergency code serves as a valuable tool to reset a forgotten PIN code or facilitate transaction signing when required.

The emergency code can only be created with a known PIN, so it should be generated during wallet creation. Your users can rest assured that they have a reliable backup option to regain access to their wallet or execute transactions securely if required.

Wallet Creation Flow:

Your app generates a random PIN code
You create the wallet with the generated PIN code
You request the emergency code with the generated PIN code
You send the emergency code to the user (e.g. via email)
You forget / never store the PIN code

User Interaction with Wallet Flow:

The user retrieves the emergency code from their email
The user enters the emergency code in your app
Your user can perform a PIN reset with a user-chosen PIN or perform any function with the emergency code (perform transfer, sign transaction, etc.)

6) Throwaway PIN and lock Wallet (when no interaction is needed at all)

Use case scenario:

Consider implementing a random PIN code system, where a unique PIN is generated during wallet creation but is promptly erased from the system afterward.

This process guarantees that the PIN code remains entirely confidential, as neither the user nor you can access the PIN code at any stage.

In this scenario, the wallet's transaction capability is restricted. Due to the secrecy of the PIN code (unknown to the user, you, or Venly), the wallet is effectively "locked," allowing assets to be added but not withdrawn or transferred out.

Reading the content of the wallet still remains possible.

📘
You can also save the PIN codes somewhere safe, if you want to access the wallets in the future.

Example Scenario:

The created wallets are used to drop permanent NFTs for loyal customers

Wallet Creation Flow:

Your app generates a random PIN code
You create the wallet with the generated PIN code
You forget/never store the PIN code
The created wallet is used to drop an NFT