Organization Secret Registration

Organization Secret Registration is a critical step in setting up your organization's security posture on Planbok's MPC system. This guide explains how to register your secret, the technical implementation of the encryption process, and the fundamental differences between Trustless MPC and Standard MPC security models.

What is an Organization Secret?

The Organization Secret is a 32-byte (256-bit) high-entropy string generated and managed entirely by your organization. It acts as a primary entropy source for the Distributed Key Generation (DKG) and signing processes.

In the Planbok MPC ecosystem, shards of your master key are distributed across multiple nodes. By providing a secret, you ensure that the nodes can only reconstruct the necessary data for signing when you authorize it with your encrypted secret.

Trustless vs. Standard MPC

When registering your organization, you must choose between two security models. This choice is permanent for the organization's lifecycle.

1. Trustless MPC (Recommended)

This is the highest level of security. Planbok nodes never store your organization's entropy.

• How it works: You must provide an encryptedOrganizationSecret with every significant request (creating wallet sets, creating wallets, and signing transactions).
• Security Advantage: Even if the Planbok platform were fully compromised, an attacker cannot sign any transactions without your secret, which never touches our databases in an unencrypted state.
• The "Export" Advantage: Only in Trustless MPC can the organization owner export the private keys of all wallets. This is crucial for disaster recovery or migrating to a different platform, providing ultimate "sovereignty" over your assets.

2. Standard MPC

This model balances security with convenience.

• How it works: You register the secret once during the organization setup. The nodes store the necessary information to perform signing operations without requiring the secret in subsequent API calls.
• Security Advantage: Uses the same 2-of-2 MPC math, ensuring no single point of failure.
• Convenience Advantage: You do not need to manage secret encryption logic for every transaction call.
• Constraint: You cannot "export" wallets (retrieve private keys) in this mode.

Quickstart: Registering Your Secret

Step 1: Generate & Encrypt the Secret

You must never send your secret in plain text. It must be encrypted using the RSA Public Key specific to your organization which can be found in your organization's dashboard or via the API.

1.1 Get your Public Key

Call the following endpoint to retrieve your PEM-formatted RSA Public Key: GET /config/organization/public-key

1.2 Use the Encryption Script

We provide a reference script to handle the RSA-OAEP encryption logic. You can find this in the planbok-v2-beta-docs repository.

Code
# Clone the repository
git clone https://github.com/nerdjango/planbok-v2-beta-docs.git
cd planbok-v2-beta-docs

# Generate an encrypted payload for registration (context: dkg)
node generate-encrypted-organization-secret.js dkg

Implementation Details (generate-encrypted-organization-secret.js): The script performs the following:

1. Generates a random 32-byte hex string (if not provided).
2. Sets a context (e.g., dkg for registration, sign for wallets creation and transactions, verify for exports).
3. Adds a high-resolution timestamp (secrets expire after 5 minutes for replay protection).
4. Encrypts the JSON payload with RSA-OAEP (SHA-256).

Code
// Internal payload structure before encryption:
{
  "secret": "79f733a81c566da48f20828b2443c708fffbd7...",
  "timestamp": 1709412345678,
  "context": "dkg"
}

Step 2: Register via the Dashboard

Once you have the encryptedOrganizationSecret (a Base64 string), you must register it through the Planbok Dashboard to finalize your organization's security setup.

1. Log in to the Planbok Dashboard.
2. Click on Register Organization Secret.
3. Select your preferred mode: Trustless MPC. For Standard MPC, you wouldn't need encryptedOrganizationSecret.
4. Paste the encryptedOrganizationSecret into the registration field.
5. Click Finalize Registration.

[!IMPORTANT] The choice between Trustless and Standard is permanent. Ensure you have read the advantages of each model before finalizing.

[!IMPORTANT] The mode selection determines your export capabilities. In Trustless MPC, you retain the ability to export your private keys for full sovereignty, but must provide the secret encrypted with your RSA Public Key for every transaction. In Standard MPC, signing is simplified to just the use of your organization API key, but exports are disabled.

Security Best Practices

1. Hardware Security: Store your 32-byte organizationSecret in a secure environment (e.g., AWS KMS, or a physical HSM).
2. Key Rotation: While the RSA Public Key is static, your encryptedOrganizationSecret uses a timestamp-based nonce. Never reuse the same encrypted ciphertext.

Advantages Summary