|
| 1 | +# What is a Realm Instance? A Developer's Guide |
| 2 | + |
| 3 | +> **Note:** This guide focuses specifically on Realm Instances in the context of Arm's Confidential Computing Architecture (CCA). |
| 4 | +
|
| 5 | +## The Basics |
| 6 | + |
| 7 | +Let's break down what a Realm Instance really is in everyday terms. Think of a Realm Instance like a secured VM for your application - it's a special, isolated space where your code runs safely in a virtualized environment backed by security guarantees provided by Arm's Confidential Computing Architecture (CCA). |
| 8 | + |
| 9 | +## Key Concepts: Building Blocks of a Realm Instance |
| 10 | + |
| 11 | +### The Birth Certificate: Realm Initial Measurements (RIM) |
| 12 | + |
| 13 | +Think of RIM as your Realm's birth certificate - it's the first and most fundamental piece of identity: |
| 14 | +- It's basically a hash (digest) of the code and optionally configuration of the Realm instance when it first starts up |
| 15 | +- Works like a fingerprint - unique to your initial code setup |
| 16 | +- Helps others verify "Yes, this is exactly the code we expect to be running" |
| 17 | +- Every Realm Instance needs this - it's not optional |
| 18 | + |
| 19 | +### The Name Tag: Realm Personalization Value (RPV) |
| 20 | + |
| 21 | +Think of RPV like a name tag for your Realm - it's optional, but super useful when you need it: |
| 22 | +- Often includes a footprint of instance-specific data supplied to the realm |
| 23 | +- It's like giving unique names to twins - same base code and configuration, however different identities |
| 24 | +- Without it? Your Realm is one-of-a-kind (like a custom-built tool) |
| 25 | +- With it? You can run multiple copies of the same code and configuration (like spinning up multiple web servers) |
| 26 | +- Perfect for when you need to scale up identical services but keep them separate |
| 27 | + |
| 28 | +### The Journey Tracker: Realm Extensible Measurements (REM) |
| 29 | + |
| 30 | +REMs are like measurements recorded during a car journey or path choices made when following a map: |
| 31 | +- Works like a car's odometer and navigation system with 4 different measurement points (rem0 through rem3) |
| 32 | +- These are passive measurements rather than active policy enforcement - they record what happened, not control what happens |
| 33 | +- Like recording different routes taken or fuel consumption during a journey, REMs capture execution differences that a workload may have made in response to configuration it received |
| 34 | +- These measurements can affect the workload identity and help identify state received from users |
| 35 | + |
| 36 | +**Real-world usage examples:** |
| 37 | +- **Configuration Response Tracking**: REMs record how a workload behaves differently based on the configuration it receives (like taking different code paths) |
| 38 | +- **User State Identification**: REMs can capture and identify some state or data received from users during runtime |
| 39 | +- **Execution Path Monitoring**: Like a GPS tracking different routes taken, REMs monitor the different execution paths your code follows |
| 40 | +- **Runtime Behavior Fingerprinting**: REMs create unique signatures based on how your code actually runs, not just how it starts |
| 41 | + |
| 42 | +## Real-World Examples |
| 43 | + |
| 44 | +### The Custom Workshop: One RIM per Tool (No RPV needed) |
| 45 | + |
| 46 | +Imagine you're running a workshop where each machine does something different: |
| 47 | +- Each tool (Realm) is unique - a lathe, a drill press, a saw |
| 48 | +- You know each tool by its shape and purpose (RIM) |
| 49 | +- No need for extra labels because each tool is obviously different |
| 50 | +- Real example: A microservices architecture where each service (authentication, database, API) runs in its own Realm |
| 51 | + |
| 52 | +### The Assembly Line: Multiple Instances of the Same Tool (Using RPV) |
| 53 | + |
| 54 | +Now picture an assembly line with multiple workers using identical tools: |
| 55 | +- All workers use the same type of tool (same RIM) |
| 56 | +- Each worker's tool has a unique number (RPV) |
| 57 | +- They can all work at the same time without confusion |
| 58 | +- **Real example**: A workload needs to do identical job in a batch [parallel processing], so on a Server, Identical N Workloads are instantiated with the same RIM. Each instance gets a unique RPV to distinguish them, allowing: |
| 59 | + - Parallel processing of different data sets |
| 60 | + - Independent scaling of each instance |
| 61 | + - Separate monitoring and debugging of each worker |
| 62 | + - Load distribution across multiple identical services |
| 63 | + |
| 64 | +## Under the Hood: How It All Works |
| 65 | + |
| 66 | +### The ID Card: How We Track Each Realm |
| 67 | +```json |
| 68 | +{ |
| 69 | + "scheme": "ARM_CCA", |
| 70 | + "type": "REFERENCE_VALUE", |
| 71 | + "subType": "realm.reference-value", |
| 72 | + "attributes": { |
| 73 | + "vendor": "Example Vendor", // Who made it |
| 74 | + "class-id": "<UUID>", // The model number |
| 75 | + "realm-initial-measurement": "...", // The fingerprint |
| 76 | + "hash-alg-id": "sha-384", // How we took the fingerprint |
| 77 | + "realm-personalization-value": "...", // The serial number (if needed) |
| 78 | + "rem0": "...", // Current state check #1 |
| 79 | + "rem1": "..." // Current state check #2 |
| 80 | + } |
| 81 | +} |
| 82 | +``` |
| 83 | + |
| 84 | +### Trust Levels: How We Know It's Safe |
| 85 | + |
| 86 | +Just like airport security, we have different levels of verification: |
| 87 | +1. "Are you who you say you are?" - Checking the Realm's identity |
| 88 | +2. "Is your code safe to run?" - Checking what's actually running inside |
| 89 | + - "All Clear": Everything matches and is running properly |
| 90 | + - "Startup Verified": Initial state is good, but still checking runtime |
| 91 | + - "Unknown": We don't recognize this code |
| 92 | + |
| 93 | +### Source of Truth: Where Reference Values Come From |
| 94 | + |
| 95 | +Just like a birth certificate is trusted because it comes from a government department, RIM reference values need to come from trusted sources where the Realm's initial code had a registration event: |
| 96 | +- **Software Release Events**: When code is officially released and signed |
| 97 | +- **Build System Attestations**: Automated systems that verify and record code builds |
| 98 | +- **Developer Registrations**: Trusted registration of code fingerprints during development |
| 99 | +- **Certificate Authorities**: Third-party validation of code authenticity |
| 100 | + |
| 101 | +Think of it like a chain of custody - each step in your code's journey from development to deployment needs to be documented and verifiable. |
| 102 | + |
| 103 | +## Tips from the Trenches |
| 104 | + |
| 105 | +### Keeping Your RIMs in Order |
| 106 | +Think of this like maintaining tools in your workshop: |
| 107 | +- Label different tools clearly (keep RIMs distinct for different apps) |
| 108 | +- Track when you sharpen or replace tools (version control your RIMs) |
| 109 | +- Keep a logbook of which tool is for what job (document your RIM mappings) |
| 110 | + |
| 111 | +### Smart RPV Management |
| 112 | +When running multiple instances: |
| 113 | +- Use RPVs when you need multiple copies of the same service |
| 114 | +- Generate strong, unique RPVs (like having a robust serial number system) |
| 115 | +- Keep track of which instance is which (maintain an RPV registry) |
| 116 | + |
| 117 | +### Watching Your REMs |
| 118 | +These are more like tripwire alarms than cameras: |
| 119 | +- They can tell you when something went wrong, but not what (for that, you need event logs) |
| 120 | +- Know what "normal" looks like (establish baseline measurements) |
| 121 | +- Watch for anything unusual (monitor for unexpected changes) |
| 122 | +- Set up automatic alerts (include REM checks in your security policies) |
| 123 | + |
| 124 | +Remember: A well-organized workshop is a productive workshop. The same goes for your Realm Instances! |
0 commit comments