diff --git a/docs/registry.md b/docs/registry.md index 8e8b2e7..8142ac4 100644 --- a/docs/registry.md +++ b/docs/registry.md @@ -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 @@ -19,7 +20,12 @@ A scope groups multiple related events within a namespace. It is defined using `scope { ... }`, where `` 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 `: ;`, where `` is the name of the data event and `` is its data type. For example: @@ -44,7 +50,9 @@ Available types are defined as follows: | int32 | word | 32-bit signed integer | | int64 | word | 64-bit signed integer | -### Context events +All data events defined in this document are optional. + +#### Context events A context event is defined using a `context { ... }` block, where `` is the name of the context event. The body of this block @@ -68,9 +76,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 @@ -93,6 +103,7 @@ scope pk { curve: string; bits: uint16; hash: string; + rsa_padding: string; } context verify { @@ -100,18 +111,21 @@ scope pk { 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 { @@ -124,12 +138,15 @@ scope pk { context generate { algorithm: string; + curve: string; + group: string; bits: uint16; } context derive { algorithm: string; curve: string; + group: string; bits: uint16; static: bool; } @@ -151,14 +168,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 | +| `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 @@ -172,6 +190,10 @@ scope tls { protocol_version: uint16; ciphersuite: uint16; + context key_exchange { + group: uint16; + } + context sign { signature_algorithm: uint16; } @@ -180,9 +202,7 @@ scope tls { signature_algorithm: uint16; } - context key_exchange { - group: uint16; - } + context verify_cert_chain {} extended_master_secret: bool; } @@ -191,12 +211,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