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 store only the encrypted, wrapped material derived from your organization's entropy, not the secret in usable form.

• 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 is not stored in our databases or anywhere else in an unencrypted state.
• The "Export" Advantage: In Trustless MPC, the organization owner can export the private keys of the organization-custody wallets. This supports disaster recovery or migration to a different platform.

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 uses only your organization API key, and wallets have no export path.

Security Best Practices

1. Secret Storage: Store your 32-byte organizationSecret in a secure environment that only your authorized systems can reach.
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