Skip to content

docs: Clarify nesting of context events #285

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ueno wants to merge 3 commits into
base: main
Choose a base branch
from
+40 −24
Open

docs: Clarify nesting of context events #285

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
81d846c
docs: Clarify nesting of context events
ueno Jul 16, 2026
15e5462
docs: Add pk::rsa_padding in public-key cryptography registry
ueno Jul 16, 2026
8ffb6a6
docs: Add tls::verify_cert_chain in TLS registry
ueno Jul 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 40 additions & 24 deletions docs/registry.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,9 @@ points as well as protocol-specific probe points for TLS and SSH.

## Presentation language

A protocol is typically defined with a context hierarchy, which can be
defined using the following presentation syntax.
Tracing information for most protocols can be represented in a
hierarchical structure of contexts and events. This document
defines the presentation syntax for this tree.

### Miscellaneous

Expand All @@ -19,7 +20,12 @@ A scope groups multiple related events within a namespace. It is
defined using `scope <name> { ... }`, where `<name>` is the scope name.
The body of this block may contain context events or data events.

### Data events
### Events

There are two kinds of events: data events and context events. All
events defined in this document are optional.

#### Data events

A data event is defined using `<name>: <type>;`, where `<name>` is the
name of the data event and `<type>` is its data type. For example:
Expand All @@ -44,7 +50,7 @@ Available types are defined as follows:
| int32 | word | 32-bit signed integer |
| int64 | word | 64-bit signed integer |

### Context events
#### Context events

A context event is defined using a `context <name> { ... }` block,
where `<name>` is the name of the context event. The body of this block
Expand All @@ -68,9 +74,11 @@ The hierarchy of context events must be preserved within the same scope.
In the example above, `c2` cannot appear at the top level, and `c3`
cannot be placed directly under `c1`.

However, context events from different scopes can be nested together.
For example, `pk::derive` (defined below) may appear within
`tls::key_exchange`.
However, context events defined at top-level can be nested. For
example, `pk::derive` may appear within `tls::key_exchange`, as well
as `pk::decapsulate` may be placed under another `pk::decapsulate` if
the algorithm is defined using a hybrid construction, such as
X25519MLKEM768.

## Generic data events

Expand All @@ -93,25 +101,29 @@ scope pk {
curve: string;
bits: uint16;
hash: string;
rsa_padding: string;
}

context verify {
algorithm: string;
curve: string;
bits: uint16;
hash: string;
rsa_padding: string;
}

context encrypt {
algorithm: string;
bits: uint16;
hash: string;
rsa_padding: string;
}

context decrypt {
algorithm: string;
bits: uint16;
hash: string;
rsa_padding: string;
}

context encapsulate {
Expand Down Expand Up @@ -151,14 +163,15 @@ scope pk {

### Public key cryptography data events

| key | value type | description |
|-----------------|------------|----------------------------------------------------------------------------------------------------------------------------|
| `pk::algorithm` | string | Used algorithm name |
| `pk::curve` | string | Elliptic curve name |
| `pk::group` | string | FFDH group name |
| `pk::bits` | uint16 | Key strength in bits |
| `pk::hash` | string | Hash algorithm used for signing or encryption (for prehashed or parametrized schemes such as ECDSA, RSA-PSS, and RSA-OAEP) |
| `pk::static` | bool | Whether `pk::derive` takes place with reused keys |
| key | value type | description |
|-------------------|------------|----------------------------------------------------------------------------------------------------------------------------|
| `pk::algorithm` | string | Used algorithm name |
| `pk::curve` | string | Elliptic curve name |
| `pk::group` | string | FFDH group name |

@neverpanic neverpanic Jul 22, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The examples above don't use group. Should the derive event use group instead of curve?

| `pk::bits` | uint16 | Key strength in bits |
| `pk::hash` | string | Hash algorithm used for signing or encryption (for prehashed or parametrized schemes such as ECDSA, RSA-PSS, and RSA-OAEP) |
| `pk::rsa_padding` | string | Padding mode used for signing or encryption in RSA. While this can be an arbitrary string, the following values are pre-defined: "pss" for RSA-PSS, "oaep" for RSA-OAEP, and "pkcs1-v1.5" for PKCS#1 v1.5 |
| `pk::static` | bool | Whether `pk::derive` takes place with reused keys |

## TLS

Expand All @@ -172,6 +185,10 @@ scope tls {
protocol_version: uint16;
ciphersuite: uint16;

context key_exchange {
group: uint16;
}

context sign {
signature_algorithm: uint16;
}
Expand All @@ -180,9 +197,7 @@ scope tls {
signature_algorithm: uint16;
}

context key_exchange {
group: uint16;
}
context verify_cert_chain {}

extended_master_secret: bool;
}
Expand All @@ -191,12 +206,13 @@ scope tls {

### TLS context events

| name | description |
|---------------------|------------------------------------------------------------------|
| `tls::handshake` | TLS handshake |
| `tls::sign` | Digital signature is created using certificate in TLS handshake |
| `tls::verify` | Digital signature is verified using certificate in TLS handshake |
| `tls::key_exchange` | Shared secret derivation in TLS handshake |
| name | description |
|--------------------------|-----------------------------------------------------------------------------------------|
| `tls::handshake` | A TLS handshake is in progress |
| `tls::key_exchange` | A shared secret is derived in TLS handshake |
| `tls::sign` | A TLS handshake message (e.g., CertificateVerify in TLS 1.3) is digitally signed |
| `tls::verify` | A signature on a TLS handshake message (e.g., CertificateVerify in TLS 1.3) is verified |
| `tls::verify_cert_chain` | A certificate chain presented during a TLS handshake is verified |

### TLS data events

Expand Down