home / skills / stuartf303 / sorcha / cryptography

cryptography skill

safe

This skill enables multi-algorithm cryptography with signing, verification, encryption, and HD wallet derivation to secure data and identities.

npx playbooks add skill stuartf303/sorcha --skill cryptography

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

3.4 KB

---
name: cryptography
description: |
  Applies multi-algorithm cryptography (ED25519, P-256, RSA-4096) using Sorcha.Cryptography.
  Use when: implementing signing, verification, encryption, key generation, HD wallets, or address encoding.
allowed-tools: Read, Edit, Write, Glob, Grep, Bash, mcp__context7__resolve-library-id, mcp__context7__query-docs
---

# Cryptography Skill

Sorcha.Cryptography provides multi-algorithm support (ED25519, P-256, RSA-4096), symmetric encryption (AES, ChaCha20), and BIP39/44 HD wallet derivation. All operations return `CryptoResult<T>` for explicit error handling—no exceptions for crypto failures.

## Quick Start

### Key Generation

```csharp
// Inject ICryptoModule
var keySetResult = await _cryptoModule.GenerateKeySetAsync(WalletNetworks.ED25519);
if (!keySetResult.IsSuccess)
    throw new InvalidOperationException($"Key generation failed: {keySetResult.Status}");

var keySet = keySetResult.Value!;
// keySet.PrivateKey.Key = 64 bytes (ED25519)
// keySet.PublicKey.Key = 32 bytes (ED25519)
```

### Signing & Verification

```csharp
// Hash then sign
byte[] hash = SHA256.HashData(transactionData);
var signResult = await _cryptoModule.SignAsync(
    hash,
    (byte)WalletNetworks.ED25519,
    keySet.PrivateKey.Key!);

// Verify
var status = await _cryptoModule.VerifyAsync(
    signResult.Value!,
    hash,
    (byte)WalletNetworks.ED25519,
    keySet.PublicKey.Key!);
bool isValid = status == CryptoStatus.Success;
```

### HD Wallet Creation

```csharp
var keyRing = await _keyManager.CreateMasterKeyRingAsync(WalletNetworks.ED25519, password: null);
// keyRing.Mnemonic = "word1 word2 ... word12" — user must backup
// keyRing.MasterKeySet contains derived keys
```

## Key Concepts

| Concept | Usage | Example |
|---------|-------|---------|
| `WalletNetworks` | Algorithm selection | `ED25519`, `NISTP256`, `RSA4096` |
| `CryptoResult<T>` | Error handling | `.IsSuccess`, `.Status`, `.Value` |
| `KeySet` | Public/private pair | `.PrivateKey.Key`, `.PublicKey.Key` |
| `KeyRing` | Full wallet with mnemonic | `.Mnemonic`, `.MasterKeySet` |
| `.Zeroize()` | Secure memory clearing | Call when done with keys |

## Common Patterns

### Platform-Specific Key Storage

```csharp
// Encryption provider abstraction handles platform differences
var encrypted = await _encryptionProvider.EncryptAsync(privateKey, "wallet-key-id");
// Windows: DPAPI, Linux: Secret Service, Dev: AES-GCM
```

### Address Generation

```csharp
var address = _walletUtilities.PublicKeyToWallet(publicKey, (byte)WalletNetworks.ED25519);
// Returns: "ws1q8tuvvdykly8n0fy5jkuu8cjw0fu0p6jl5rp9g..."
```

## See Also

- [patterns](references/patterns.md) - Algorithm selection, signing workflows, key management
- [workflows](references/workflows.md) - Wallet creation, transaction signing, encryption

## Related Skills

- See the **nbitcoin** skill for HD wallet derivation paths (BIP32/39/44)
- See the **postgresql** skill for encrypted key storage patterns
- See the **xunit** and **fluent-assertions** skills for testing crypto code

## Documentation Resources

> Fetch latest cryptography documentation with Context7.

**How to use Context7:**
1. Use `mcp__context7__resolve-library-id` to search for "libsodium" or "System.Security.Cryptography"
2. Query with `mcp__context7__query-docs` using the resolved library ID

**Recommended Queries:**
- "ED25519 signing verification"
- "AES-GCM authenticated encryption"
- "BIP39 mnemonic seed derivation"

Overview

This skill implements multi-algorithm cryptography using Sorcha.Cryptography, covering ED25519, P-256 (NIST P-256), and RSA-4096. It provides signing, verification, asymmetric key generation, symmetric encryption (AES, ChaCha20), and BIP39/44 HD wallet derivation. All operations return CryptoResult<T> for explicit, non-exception error handling.

How this skill works

The module exposes async operations for key generation, signing, verification, encryption, decryption, and HD wallet management. Calls return CryptoResult<T> objects that include IsSuccess, Status, and Value for explicit error control. Platform-aware providers handle secure key storage and encryption differences (DPAPI on Windows, Secret Service on Linux, AES-GCM for dev). Utility functions convert public keys to wallet addresses and derive keys from mnemonics using BIP39/44.

When to use it

Generate algorithm-specific key pairs (ED25519, P-256, RSA-4096) for signing or key exchange.
Sign and verify payloads with explicit, non-exception error handling in production workflows.
Create and manage HD wallets and mnemonics using BIP39/44 for deterministic key derivation.
Encrypt and decrypt private material using platform-appropriate secure storage or symmetric ciphers.
Derive wallet addresses from public keys and integrate with transaction signing flows.

Best practices

Always check CryptoResult.IsSuccess and handle CryptoResult.Status rather than relying on exceptions.
Call .Zeroize() on sensitive key material when finished to clear memory securely.
Prefer platform encryption providers for storing private keys; fall back to AES-GCM only for development.
Hash data (e.g., SHA-256) before signing to ensure consistent input length and algorithm compatibility.
Backup mnemonic phrases securely; treat KeyRing.Mnemonic as sensitive material.

Example use cases

Generate an ED25519 KeySet, sign a transaction hash, and verify the signature before broadcast.
Create a master KeyRing with a 12-word mnemonic, derive child keys by BIP44 paths, and export public addresses.
Encrypt a private key with the platform encryption provider, store the ciphertext, and decrypt at runtime for signing.
Use RSA-4096 for legacy compatibility when large-key asymmetric encryption is required.
Convert a public key to a wallet address for display and address validation prior to sending funds.

FAQ

How are errors reported?

All APIs return CryptoResult<T>; inspect IsSuccess and Status and only use Value when IsSuccess is true.

Which algorithms are available?

ED25519, NIST P-256 (P-256), RSA-4096 for asymmetric; AES and ChaCha20 for symmetric; BIP39/44 for HD wallets.