xrpl-dev-portal/docs/tutorials/best-practices/key-management/assign-a-regular-key-pair.md

seo, labels

seo	labels
description Authorize a regular key pair to sign transactions from your account. This key pair can be changed or removed later.	Security Accounts

Assign a Regular Key Pair

This tutorial shows how to authorize a secondary key pair, called a regular key pair, to sign future transactions. Unlike the master key pair, which is mathematically linked to the account's address, you can remove or replace the regular key pair, which is better for security.

You can use these steps to assign a regular key pair for the first time or to replace an existing regular key pair with a new one. You can use this same process for key rotation as a proactive security measure.

Goals

By following this tutorial, you should learn how to:

• Securely generate a regular key pair and attach it to your account.
• Submit transactions using a regular key pair.
• Check a transaction to see if the key that was used to sign it matches a known key pair.

Prerequisites

To complete this tutorial, you should:

• Have a basic understanding of the XRP Ledger.
• Have an XRP Ledger client library, such as xrpl.js, installed.
• Have a basic understanding of Cryptographic Keys.

Source Code

You can find the complete source code for this tutorial's examples in the {% repo-link path="_code-samples/assign-regular-key/" %}code samples section of this website's repository{% /repo-link %}.

Steps

1. Install dependencies

{% tabs %} {% tab label="JavaScript" %} From the code sample folder, use npm to install dependencies:

npm i

{% /tab %}

{% tab label="Python" %} From the code sample folder, set up a virtual environment and use pip to install dependencies:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

{% /tab %} {% /tabs %}

2. Connect and get account(s)

To get started, import the client library and instantiate an API client. For this tutorial, you need one account, which the sample code funds using the Testnet faucet; you could also use an existing account.

{% tabs %} {% tab label="JavaScript" %} {% code-snippet file="/_code-samples/assign-regular-key/js/assign-regular-key.js" language="js" before="// Generate a new key pair" /%} {% /tab %}

{% tab label="Python" %} {% code-snippet file="/_code-samples/assign-regular-key/py/assign-regular-key.py" language="py" before="# Generate a new key pair" /%} {% /tab %} {% /tabs %}

3. Generate a key pair

Next, generate a key pair to use as the regular key pair. This is the same data type as a master key pair, so you can generate it the same way.

{% admonition type="danger" name="Warning" %} It's important to generate and store the key pair securely; otherwise, it may be possible for malicious actors to gain access to your account and take your money. Common errors include:

• Getting your secret key from a remote machine, or otherwise sending your secret key in plain text over the internet.
• Generating a key pair using a compromised software library.
• Generating a key pair from a passphrase or other secret value that does not have enough entropy. {% /admonition %}

{% tabs %} {% tab label="JavaScript" %} Use the Wallet.generate() class method to generate a key pair locally on your machine. {% code-snippet file="/_code-samples/assign-regular-key/js/assign-regular-key.js" language="js" from="// Generate a new key pair" before="// Send SetRegularKey transaction" /%} {% /tab %}

{% tab label="Python" %} Use the Wallet.create() class method to generate a key pair locally on your machine. {% code-snippet file="/_code-samples/assign-regular-key/py/assign-regular-key.py" language="py" from="# Generate a new key pair" before="# Send SetRegularKey transaction" /%} {% /tab %} {% /tabs %}

4. Send a SetRegularKey transaction

Use a [SetRegularKey transaction][] to assign the new key pair to your account as a regular key pair.

{% admonition type="success" name="Tip: Rotating a Regular Key" %}This example signs the transaction using the master key pair, but you could also use an existing regular key pair, or a multi-signing list if your account has multi-signing set up.{% /admonition %}

{% tabs %} {% tab label="JavaScript" %} {% code-snippet file="/_code-samples/assign-regular-key/js/assign-regular-key.js" language="js" from="// Send SetRegularKey transaction" before="// Send a test transaction" /%} {% /tab %}

{% tab label="Python" %} {% code-snippet file="/_code-samples/assign-regular-key/py/assign-regular-key.py" language="py" from="# Send SetRegularKey transaction" before="# Send a test transaction" /%} {% /tab %} {% /tabs %}

5. Send a test transaction using the regular key

After the SetRegularKey transaction succeeds, the regular key pair is assigned to your account and you should be able to send transactions using the regular key pair. To avoid losing control of your account, it is important that you test your regular key before you take any additional steps such as disabling the master key pair. If you make a mistake and lose access to your account, no one can restore it for you.

To test the key, send any type of transaction, signing it using the regular key pair. The sample code sends an [AccountSet transaction][] with no parameters, which is a "no-op" that does nothing besides use a sequence number and burn the transaction cost.

{% tabs %} {% tab label="JavaScript" %} {% code-snippet file="/_code-samples/assign-regular-key/js/assign-regular-key.js" language="js" from="// Send a test transaction" before="// Check result of the test" /%} {% /tab %}

{% tab label="Python" %} {% code-snippet file="/_code-samples/assign-regular-key/py/assign-regular-key.py" language="py" from="# Send a test transaction" before="# Check result of the test" /%} {% /tab %} {% /tabs %}

6. Confirm that the test transaction succeeded as expected

If the test transaction succeeds, your regular key pair works as expected. For further confirmation, you can look at the SigningPubKey field which is automatically added to a transaction during signing; this field contains the public key of the key pair that was used to sign the transaction, and is what the network uses to validate the transaction signature. When you use your regular key pair to sign a transaction, the SigningPubKey field contains the public key from your regular key pair.

{% tabs %} {% tab label="JavaScript" %} {% code-snippet file="/_code-samples/assign-regular-key/js/assign-regular-key.js" language="js" from="// Check result of the test" /%} {% /tab %}

{% tab label="Python" %} {% code-snippet file="/_code-samples/assign-regular-key/py/assign-regular-key.py" language="py" from="# Check result of the test" /%} {% /tab %} {% /tabs %}

If the transaction fails with the following result codes, here are some things to check:

• tefBAD_AUTH: The regular key you signed your test transaction with doesn't match the regular key you set in the previous step. Check that the secret and address for your regular key pair match and double-check which values you used in each step.
• tefBAD_AUTH_MASTER or temBAD_AUTH_MASTER: Your account doesn't have a regular key assigned. Check that the SetRegularKey transaction executed successfully. You can also use the [account_info method][] to confirm that your regular key is set in the RegularKey field as expected.

For possible causes of other result codes, see Transaction Results.

See Also

Now that you're familiar with the benefits of assigning a regular key pair to an account, consider taking a look at these related topics and tutorials:

• Concepts:
  • Cryptographic Keys
  • Multi-Signing
  • Issuing and Operational Addresses
• Tutorials:
  • Remove a Regular Key Pair
  • Set Up Multi-Signing
  • List XRP as an Exchange
• References:
  • [wallet_propose method][]
  • [sign method][]
  • [SetRegularKey transaction][]
  • AccountRoot object where the regular key is stored in the field RegularKey

{% raw-partial file="/docs/_snippets/common-links.md" /%}