Importing keys (trusted dealer)

TKeeper supports importing externally generated key material using a trusted dealer flow. This capability exists for controlled operational scenarios such as migrations or key recovery from an external custody system.

When to use import

Use import only when:

• Migrating existing keys from another system into TKeeper.
• Rehydrating keys from an external secure source under strict operational controls.
• You have an established process for handling raw key material safely.

Do not use import when:

• You can generate keys inside TKeeper (preferred). Import changes the trust model and increases exposure risk.
• You want “normal” threshold custody guarantees from the very beginning of key lifecycle.

Security model and risk

Import is a trusted dealer operation:

• The private key material exists in full outside the threshold system during import time.
• Operational controls around key handling, transport, and storage become critical.

Treat import as a migration tool, not a default workflow.

API endpoint

• POST /v1/keeper/storage/store
• Permission: tkeeper.storage.write

This endpoint stores key material under the provided keyId (logical id).

Request model

Schema (Store):

{
  "keyId": "custody-key",
  "curve": "SECP256K1",
  "value64": "base64(key-material-bytes)",
  "policy": {
    "allowHistoricalProcess": true,
    "apply": { "unit": "SECONDS", "notAfter": 1735689600 },
    "process": { "unit": "SECONDS", "notAfter": 1735689600 }
  }
}

Fields:

Field	Type	Required	Meaning
keyId	string	yes	Logical key id used across the API.
curve	enum	yes	SECP256K1 or ED25519.
value64	string	yes	Base64-encoded private key material for the selected curve.
policy	object	no	Optional KeySetPolicy applied to the imported key.

Response:

• 200 OK with an empty body on success.

Curve-specific requirements

ED25519 import format (seed, not clamped)

For curve = "ED25519":

• value64 must contain a 32-byte Ed25519 seed.
• Do NOT provide a clamped private scalar, TKeeper performs clamping internally as part of key derivation.

This is important for correctness and interoperability.

SECP256K1 import format

For curve = "SECP256K1":

• value64 must contain the raw private key material for secp256k1 (32 bytes).
• The value must be a valid secret scalar for the curve.

Key policy on imported keys

The optional policy field attaches a KeySetPolicy to the stored key. This is the same policy model used by other lifecycle operations.

KeySetPolicy fields:

• apply: optional “not after” constraint for applying operations
• process: optional “not after” constraint for processing operations
• allowHistoricalProcess: whether operations may be processed against historical generations (default: true)

Note

If you do not need policy restrictions at import time, omit the policy field. More details on key policies can be found in the key lifecycle documentation.

Recommendation

Use import only for migration and controlled recovery scenarios. For normal operation, generate keys using DKG and manage them through the key lifecycle APIs.