Cryptographic Operations

Key management, encryption, signatures, and zero-knowledge proofs — most apps never call this directly, but the API is here when you need it.

Key management, encryption, signatures, and zero-knowledge proofs. YF handles these under the hood for any operation that needs them — most apps never call the crypto API directly. The endpoints below are exposed for flows that need explicit control: bring-your-own-key flows, application- level encryption, custom signing flows that bypass the wallet UI.

What's available

  • Zero-knowledge privacy — confidential transactions via Groth16 circuits. Amounts, parties, and obligations are encrypted; the chain verifies the proof without revealing the substance.
  • Key management — generate and manage signing keys for users and groups. Hardware-security-module-friendly.
  • Digital signatures — sign arbitrary data; verify externally produced signatures.
  • Application-level encryption — encrypt/decrypt data using public/private key pairs.

Key management

Generate a user keypair

curl -X POST $YF_AUTH/keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "'$USER_ID'",
    "key_name": "Primary signing key",
    "key_type": "Signing",
    "provider_type": "OpenSSL"
  }'

Generate a group keypair

For group operations, mint a delegation JWT first and use it as the bearer token.

curl -X POST $YF_AUTH/auth/groups/$GROUP_ID/keypairs \
  -H "Authorization: Bearer $DELEGATION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key_name": "Group signing key",
    "key_type": "Signing",
    "provider_type": "OpenSSL"
  }'

List keypairs

curl $YF_AUTH/keys/users/$USER_ID/keys \
  -H "Authorization: Bearer $TOKEN"

For wallet-led signups that need a server-custodied key provisioned for a contact, use the unified crypto route:

curl -X POST $YF_AUTH/api/v1/generate-keypair \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "contact_id": "'$USER_ID'", "provider_type": "OpenSSL" }'

Encryption

Encrypt data

Encrypt sensitive data using a public key. Useful for application-level encryption of payloads that need to be readable only by a specific recipient.

curl -X POST $YF_AUTH/api/v1/encrypt \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key_id": "'$KEY_ID'",
    "data": "Confidential business data",
    "data_format": "utf8"
  }'

Decrypt data

curl -X POST $YF_AUTH/api/v1/decrypt \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key_id": "'$KEY_ID'",
    "encrypted_data": "'$CIPHERTEXT'",
    "encrypted_data_format": "base64"
  }'

Digital signatures

Sign data

curl -X POST $YF_AUTH/api/v1/sign \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key_id": "'$KEY_ID'",
    "data": "Contract terms to sign",
    "entity_type": "user",
    "entity_id": "'$USER_ID'",
    "data_format": "utf8"
  }'

Verify a signature

curl -X POST $YF_AUTH/api/v1/verify \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key_id": "'$KEY_ID'",
    "data": "Contract terms to sign",
    "signature": "3045022100a1b2c3d4...",
    "signature_format": "der",
    "data_format": "utf8"
  }'

Zero-knowledge proofs

YF uses zero-knowledge proofs (Groth16 circuits) under the hood for confidential transactions. Apps don't construct proofs directly — the platform builds them when you submit operations like instant or createSwap. The categories of proof in use:

Proof
Balance proof
What it proves
The sender has sufficient balance, without revealing the amount.
Proof
Range proof
What it proves
A value lies within a permitted range, without revealing the value.
Proof
Equality proof
What it proves
Two values are equal, without revealing them.
Proof
Membership proof
What it proves
A value is a member of a set, without revealing which.

Privacy features that result:

  • Transaction amounts hidden from public view.
  • Account balances private; queries return values only to authorised holders.
  • Payment flows encrypted end-to-end on-chain.
  • Verifications anonymous — third parties can verify validity without learning the substance.

Security guidance

Key management

  • Rotate keys on a regular schedule.
  • Use hardware security modules where available (the platform supports HSM-backed keystores).
  • Limit key access to the entities that actually need it.
  • Log all cryptographic operations (auth audit is on by default).

Encryption

  • Generate keys with sufficient entropy (the platform's /keys and /api/v1/generate-keypair endpoints already do this).
  • Use secure key exchange protocols when keys cross trust boundaries.
  • Encrypt sensitive payloads at rest, not just in transit.
  • Keep your client-side crypto libraries current.

Signatures

  • Use unique nonces for each signature (the platform handles nonce generation for its own operations).
  • Include timestamps in signed payloads to prevent replay.
  • Always verify public keys before trusting them — bind keys to identity via the auth service.
  • Verify all signatures before processing.

See also

  • Authentication & signing — JWT lifecycle and delegation are how the platform authorises crypto operations.
  • Building with YieldFabric — for most apps, the wallet SDK + signature drawer is the right way to invoke signing; calling the crypto API directly is the advanced path.
YieldFabric docs(317)