Documentation
Everything you need to build interactive cryptographic protocol exercises with Decrypted.
Introduction
Decrypted is an educational framework for building interactive cryptographic protocol exercises. Exercise creators write exercises once using a simple text-based DSL, and Decrypted renders it into a fully interactive exercise, complete with drag-and-drop expression building, multiple choice, matching, and more.
Teaching cryptographic protocols is hard. Textbooks show static diagrams; students passively read. Decrypted closes that gap by turning protocol definitions into exercises students can actually work through, making concepts like Diffie-Hellman or RSA tangible rather than abstract.
If you're an educator, start with the Quick Start guide. If you want to jump straight into writing exercises, head to the DSL Reference.
Quick Start
To get started building exercises, follow this quick start guide, as it will teach you the basics of the framework. The framework provides a set amount of exercises, but it brings an infinite amount of possibilities, because they allow much different behavior.
Understanding the structure
Exercises have to be individually inside a step. A step covers what the user will see on a single page. This means that multiple steps, e.g. 4 steps, will cover four separate pages. Once the user has completed all 4 steps, the user will be able to submit their answers, and see the final summarization page of how they did.
Getting Started
Title
To get started building exercises, you have to put in a title for the exercise. This is purely a display name and DOES NOT affect the exercises. You put the title at the start of the code.
Define
The define block is where you declare the roles students assign symbols to before the exercises begin. It is a really powerful tool and it is important you understand and use this system.
See the Define Block section for full details.
Step
Example
title: Diffie-Hellman Key Exchange
define:
type: select
generator \elem { g, x, a, b }
prime \elem { p, q, r, s }
step:
description: Alice computes her public key.
exercise:
type: select
prompt: What does Alice send to Bob?
answer: g^a mod p
options: { g^a mod p, g^b mod p, g^ab mod p }Each step is rendered with the description at the top of the page and, if an exercise is defined, it will appear below it. Each step takes up an entire page. This means that if the exercise is omitted from the step, the page will only contain a description, which is useful for information between exercises. See the exercise types section for the fields each type accepts.
Installation
If you wish to install and run this project locally, then you have to navigate to the GitHub repository, then run:
Terminal
npm install
npm run devSyntax Overview
A Decrypted exercise is made up of four top-level blocks that must appear in this order: title, define, custom, and step. Only title and at least one step are required - the others are optional. Fields inside a block are indented with two spaces.
The title is a display name for the exercise. It has no effect on the exercises themselves, but it will be visible to you and anyone you share it with.
The define block declares the roles that students assign symbols to before the exercises begin. There are two variants: select (students pick from a fixed set) and construct (students build their own symbol via drag-and-drop). See the Define Block section for full details.
The custom block lets you define your own operators if the built-in set does not cover what you need. See Custom Operators for a full guide.
One or more step blocks define the actual exercises. Each step occupies its own page and contains a description and an optional exercise.
Role references are written as {role_name} and can appear in descriptions, prompts, and expressions. When a student has assigned a symbol to a role, every occurrence of that reference is automatically replaced with their chosen symbol. This only works if a define block is present. See Roles & Symbols for more detail.
Skeleton
title: Diffie-Hellman Key Exchange
define:
type: select
generator \elem {g, h, k}
prime \elem {p, q, r}
custom:
operator:
name: myop
type: BINARY
precedence: 5
step:
description: Alice uses {generator} as the base for her calculation.
exercise:
type: select
prompt: What is the base used with {prime}?
options:
- {generator}
- {prime}
answer: {generator}Define Block
The define block is where you declare the named roles that students assign symbols to before the exercises begin. Once a student has made their choices, you can reference any role throughout the protocol using {role}, in descriptions, prompts, and expressions alike. This lets a single exercise definition feel personal to each student, since every occurrence of {role} is automatically replaced with the symbol they picked.
Variants
Multiple ChoiceWith the multiple choice variant, each role is paired with a fixed set of symbols the student can choose from. This is the simpler of the two variants and is a good default, keeping the student focused without overwhelming them with options.
- requiredtypeAlways "select" for this define type.
- requiredrole \elem { ... }Declares a role and the set of symbols the student can pick from. Add one line per role.
Example - Multiple Choice
type: select
generator \elem {g, h, k}
prime \elem {p, n, m, q}
alice_secret \elem {a, s, x}
bob_secret \elem {b, t, y}With the drag and drop variant, students build their own symbol for each role using a palette of tokens, without being limited to a predefined set. This gives more flexibility, but also more room for error, so consider whether that freedom is appropriate for your exercise before choosing this variant over multiple choice.
- requiredtypeAlways "construct" for this define type.
- requiredvariablesA comma-separated list of role names the student will assign symbols to via drag and drop.
Example - Drag And Drop
type: construct
variables: generator, prime, alice_secret, bob_secretThe define block must appear before any step blocks, or the protocol will fail to compile.
Each symbol must belong to exactly one role. A symbol that appears in two different role definitions will cause a compile error. For example, if generator already contains g, no other role may also list g as a possible value. This applies to both the select and construct variants - in construct exercises, students will be prevented from assigning a symbol that is already assigned to another role.
Step Block
Each exercise is split into step code blocks. One step is one exercise. It is required for any step to always have a description, but each exercise type has a set of required and optional fields that needs to be included for the step to compile.
- requireddescriptionThe text shown at the top of the step page. Required for every step.
- optionalexerciseThe exercise block for this step. If omitted, the step renders as a description-only page.
Example
step:
description: Lorem ipsum description text.
exercise:
type: construct
prompt: Build the expression.
answer: a oplus bExpressions
An expression is any valid combination of values, variables, and operators, for example g ^ a mod p or A \xor B. Expressions are used in the answer, options, pairs, and prefill fields. Role references (e.g. {generator}) are also valid inside expressions and are substituted with the student's chosen symbol at runtime. See Roles & Symbols for details.
Built-in Operators
Operators that are standard keyboard characters are written directly. Operators that require a special symbol are written with a backslash prefix followed by their name (e.g. \xor renders as ⊕). All built-in operators are grouped by category below. If you need an operator that is not listed, you can define your own - see Custom Operators.
Operator Precedence
When an expression contains multiple operators, higher-precedence operators bind more tightly. The precedence order from highest to lowest is:
| Precedence | Operators |
|---|---|
| Highest (5) | ^ |
| 4 | *, /, mod |
| 3 | +, - |
| 2 | <, >, =, and all \backslash symbols |
| Lowest (1) | and, or |
For example, g ^ a mod p is parsed as (g ^ a) mod p because ^ has higher precedence than mod. Use parentheses to override the default order when needed.
Commutativity
When checking a student's answer, Decrypted treats the following operators as commutative: +, *, and, or, and =. This means that if the correct answer is a + b, a student who writes b + a will still be marked correct. You do not need to do anything to enable this - it is applied automatically for those operators.
The type field must always be the first field inside an exercise block. The parser uses it to validate other fields, so declaring prompt or any other field before type will throw an error.
Multiple Choice
The student is presented with a prompt and must pick the correct answer from a list of options.
- requiredtypeAlways "select" for this exercise type.
- requiredpromptThe question shown to the student.
- requiredanswerThe correct answer expression.
- requiredoptionsA list of expressions the student can choose from.
- optionalhintA hint revealed when the student requests it.
Example
exercise:
type: select
prompt: Choose Alice's secret exponent {alice_secret}
hint: Choose a random integer in the range [2, {prime}-2]
options:
- 1
- 7
- {prime}-1
- {prime}-2
answer: 7A select exercise supports a maximum of 6 options. The parser will throw an error if more than 6 options are provided.
Drag And Drop
The student builds an expression by dragging tokens from a palette onto a canvas.
- requiredtypeAlways "construct" for this exercise type.
- requiredpromptThe question shown to the student.
- requiredanswerThe correct expression the student must construct.
- optionalpaletteA default operator category shown in the palette. Students can still search for any operator.
- optionalprefillTokens pre-loaded onto the canvas that the student cannot remove. Prefill tokens must appear in the answer, and in the same left-to-right order as they do in the answer expression.
- optionalhintA hint revealed when the student requests it.
Example
exercise:
type: construct
prompt: Construct the expression for Alice to calculate her public key A
hint: Bob uses the same expression to calculate B
palette: ARITHMETIC_OPERATORS, CRYPTOGRAPHIC_SYMBOLS
prefill: mod {prime}
answer: {generator} ^ {alice_secret} mod {prime}Match
The student matches items on the left to their corresponding items on the right.
- requiredtypeAlways "match" for this exercise type.
- requiredpromptThe question shown to the student.
- requiredpairsA set of key-value pairs the student must match together.
- optionalhintA hint revealed when the student requests it.
Example
exercise:
type: match
prompt: Match each step in the Diffie-Hellman protocol with the right formula
hint: Remember, Alice doesn't know {bob_secret} and Bob doesn't know {alice_secret}
pairs:
- {generator}^{alice_secret} mod {prime} -> Alice's public key
- {generator}^{bob_secret} mod {prime} -> Bob's public key
- B^{alice_secret} mod {prime} -> Alice's shared secret
- A^{bob_secret} mod {prime} -> Bob's shared secretCalculate
The student is given an expression to evaluate and must type in the correct result.
- requiredtypeAlways "calculate" for this exercise type.
- requiredpromptThe question shown to the student.
- requiredanswerThe correct numeric or symbolic result.
- optionalhintA hint revealed when the student requests it.
Example
exercise:
type: calculate
prompt: Compute the shared key when alice_secret = 4, prime = 23, generator = 5
answer: 12Custom Operators
If the built-in operator set does not cover what your protocol needs, you can define your own. Custom operators are declared in a custom: block and can be used anywhere an expression is valid: answers, options, and prefill.
- requirednameThe identifier used in expressions. Written exactly as-is - for example, name: HASH means you write HASH x in an expression. Must not conflict with any built-in operator name (checked case-insensitively).
- requiredtypeEither "BINARY" (two operands) or "UNARY" (one operand). Controls how the operator is parsed and how many operands it takes.
- requiredprecedenceA non-negative integer controlling how tightly the operator binds. Higher numbers bind more tightly. Uses the same scale as built-in operators - click to expand.
- optionalcommutativeWhether a OP b and b OP a are treated as equal when checking answers. Defaults to false. Set to "true" to enable - the operator will then behave like + or * when evaluating student answers.
Example
custom:
operator:
name: HASH
type: UNARY
precedence: 6
operator:
name: SET
type: BINARY
commutative: true
precedence: 3Once defined, custom operators are written directly by name in expressions. Binary operators are infix (a SET b), and unary operators are prefix (HASH x). They are also automatically added to the palette in construct exercises, so students can drag them in without any extra configuration.
Custom operator names tokenize as plain identifiers, not backslash symbols. This means a name like HASH is written as HASH x in the DSL, not \HASH x. The name must be unique and must not match any built-in operator (e.g. mod, xor, forall).
Roles & Symbols
A role reference is written as {role_name} and acts as a placeholder that is replaced with the student's chosen symbol at runtime. Role references can appear anywhere in the code.
Once a student has assigned a symbol to a role in the define step, every {role_name} occurrence throughout the exercise is replaced with that symbol. This means a single exercise definition can feel personalized to each student, since their chosen symbols appear consistently everywhere.
Example
step:
description: Alice chooses her secret {alice_secret} and computes her public key.
exercise:
type: construct
prompt: Build the formula Alice uses with {generator} and {prime}
hint: The exponent is {alice_secret}
answer: {generator} ^ {alice_secret} mod {prime}Every role reference used anywhere in the exercise must be declared in the define: block. Using a role name that has not been defined - in a prompt, hint, or expression - will cause a parse error.
Examples
The following are complete, copy-paste-ready exercises for two foundational cryptographic protocols. Each example uses multiple exercise types across several steps to guide students through the full protocol from key generation to the final computation.
Diffie-Hellman Key Exchange
A five-step exercise that walks students through the Diffie-Hellman key exchange protocol: agreeing on public parameters, computing public keys, exchanging them, and deriving the shared secret. The final step uses concrete numbers to verify understanding.
Full Example
title: Diffie-Hellman
custom:
operator:
name: SET
type: BINARY
commutative: true
precedence: 4
define:
type: select
generator \elem {g, h, k}
prime \elem {p, n, m, q}
alice_secret \elem {a, s, x}
bob_secret \elem {b, t, y}
step:
description: Alice chooses secret {alice_secret}
exercise:
type: select
prompt: Choose a valid secret exponent for Alice's secret {alice_secret}
hint: Choose a random integer in the range [2, {prime}-2]
options:
- 1
- 7
- {prime}-1
- {prime}-2
answer: 7
step:
description: Alice computes her public key A
exercise:
type: construct
prompt: Construct the expression for Alice to calculate her public key A
hint: Bob uses the same expression to calculate B
palette: ARITHMETIC_OPERATORS
prefill: mod {prime}
answer: {generator} ^ {alice_secret} mod {prime}
step:
description: Alice sends A to Bob
step:
description: Bob chooses secret {bob_secret}
exercise:
type: match
prompt: Match each step in the Diffie-Hellman protocol with the right formula
hint: Remember, Alice doesn't know {bob_secret} and Bob doesn't know {alice_secret}
pairs:
- {generator}^{alice_secret} mod {prime} -> Alice's public key
- {generator}^{bob_secret} mod {prime} -> Bob's public key
- B^{alice_secret} mod {prime} -> Alice's shared secret
- A^{bob_secret} mod {prime} -> Bob's shared secret
step:
description: Bob computes his public key B
exercise:
type: select
prompt: Which expression does Bob use to calculate his public key B
hint: Alice uses the same expression to calculate A
options:
- {bob_secret}^{generator} mod {prime}
- {prime}^{bob_secret} mod {generator}
- {generator}^{bob_secret} mod {prime}
answer: {generator}^{bob_secret} mod {prime}
step:
description: Bob sends B to Alice
step:
description: Alice computes shared key
exercise:
type: calculate
prompt: Compute the shared key for Alice and Bob, when {alice_secret} = 4, {bob_secret} = 5, {prime} = 23, {generator} = 5
hint: The formula is A ^ {bob_secret} mod {prime} and B ^ {alice_secret} mod {prime}
answer: 12El-Gamal Encryption
A five-step exercise covering the El-Gamal encryption scheme: key generation, computing both ciphertext components during encryption, recovering the shared secret during decryption, and finally recovering the plaintext.
Full Example
title: El-Gamal Encryption
define:
type: select
generator \elem {g, h, j}
prime \elem {p, q, n}
private_key \elem {x, a, b}
ephemeral \elem {k, r, t}
step:
description: The recipient generates a key pair. They choose a prime {prime}, a generator {generator}, and a private key {private_key}.
exercise:
type: construct
prompt: Build the recipient's public key h
palette: ARITHMETIC_OPERATORS
answer: {generator} ^ {private_key} mod {prime}
step:
description: To encrypt a message m, the sender picks a random ephemeral value {ephemeral} and computes the first ciphertext component.
exercise:
type: construct
prompt: Build the first ciphertext component c1
palette: ARITHMETIC_OPERATORS
answer: {generator} ^ {ephemeral} mod {prime}
step:
description: The sender uses the recipient's public key h to mask the message m.
exercise:
type: construct
prompt: Build the second ciphertext component c2
palette: ARITHMETIC_OPERATORS
answer: m * h ^ {ephemeral} mod {prime}
step:
description: To decrypt, the recipient first recovers the shared secret from c1 using their private key {private_key}.
exercise:
type: construct
prompt: Compute the shared secret s from c1
palette: ARITHMETIC_OPERATORS
answer: c1 ^ {private_key} mod {prime}
step:
description: The recipient now uses the shared secret s to recover the original message from c2.
exercise:
type: select
prompt: How does the recipient recover message m?
hint: s masks the message, so you need to invert it
options:
- c2 * s^(-1) mod {prime}
- c2 + s mod {prime}
- c2 \xor s
- c2 - s mod {prime}
answer: c2 * s^(-1) mod {prime}TLS Handshake (Key Exchange)
A five-step exercise walking students through the ECDH-based key exchange at the heart of TLS: computing each party's public key share, deriving the pre-master secret independently on both sides, and verifying the result with concrete numbers.
Full Example
title: TLS Handshake (Key Exchange)
define:
type: select
generator \elem {g, h, k}
prime \elem {p, q, n}
client_priv \elem {c, a, x}
server_priv \elem {s, b, y}
step:
description: The TLS handshake begins. The client sends a ClientHello with a random nonce and an DH key share derived from its private value {client_priv}.
step:
description: The client computes its DH key share to include in the ClientHello.
exercise:
type: construct
prompt: Build the client's DH public key share C
palette: ARITHMETIC_OPERATORS
answer: {generator} ^ {client_priv} mod {prime}
step:
description: The server responds with a ServerHello and its own DH key share S, computed from its private value {server_priv}.
exercise:
type: construct
prompt: Build the server's DH public key share S
palette: ARITHMETIC_OPERATORS
answer: {generator} ^ {server_priv} mod {prime}
step:
description: Each party can now independently compute the pre-master secret using the other party's public key share.
exercise:
type: match
prompt: Match each party to the pre-master secret they compute
hint: Both computations must yield the same result for the handshake to succeed
pairs:
- S ^ {client_priv} mod {prime} -> Client's pre-master secret
- C ^ {server_priv} mod {prime} -> Server's pre-master secret
step:
description: Verify the key exchange with concrete values. Use generator = 2, prime = 11, client_priv = 3, server_priv = 5.
exercise:
type: calculate
prompt: What is the pre-master secret?
hint: Compute C = 2^3 mod 11 = 8, then raise it to server_priv mod prime
answer: 10