Skip to content

Test vectors

Jump to bottom Edit New page
rweather edited this page Sep 28, 2016 · 25 revisions

Format

{
"vectors": [
{
"name": "arbitrary string",
"pattern": "NN|KN|NK|KK|NX|KX|XN|IN|XK|IK|XX|IX|N|K|X",
"dh": "25519|448",
"hybrid": "25519|448|NewHope"
"cipher": "AESGCM|ChaChaPoly",
"hash": "SHA256|SHA512|BLAKE2s|BLAKE2b",
"fail": false|true,
"fallback": false|true,
"fallback_pattern": "XXfallback|XXfallback+hfs"
"init_prologue": "hex string",
"init_psk": "hex string",
"init_ssk": "hex string",
"init_static": "hex string",
"init_semiephemeral": "hex string",
"init_ephemeral": "hex string",
"init_remote_static": "hex string",
"init_remote_semiephemeral": "hex string",
"resp_prologue": "hex string",
"resp_psk": "hex string",
"resp_ssk": "hex string",
"resp_static": "hex string",
"resp_semiephemeral": "hex string",
"resp_ephemeral": "hex string",
"resp_remote_static": "hex string",
"resp_remote_semiephemeral": "hex string",
"handshake_hash": "hex string",
"messages": [
{
"payload": "hex string",
"ciphertext": "hex string"
}, ...
]
}, ...
]
}

The following keys are optional:

  • init_* and resp_* (except the prologues)
  • handshake_hash
  • fallback (used for testing Noise Pipes, described below, defaults to false)
  • fallback_pattern
  • hybrid

Optional keys may be null or omitted entirely. The fail key, if omitted, defaults to false. All other keys are mandatory.

The handshake_hash key specifies the expected handshake hash value for both parties at the end of a successful handshake. If fail is true and the failure occurs on a handshake packet, then the handshake_hash key should be ignored.

The messages array describes a conversation alternating between the initiator and responder, starting with the initiator. No distinction is made between when the handshake begins and when it is complete. E.g., if a handshake pattern has three messages in it, the responder will send the first non-handshake Noise message. For one-way patterns the messages simply flow from the initiator to the responder.

Noise Pipes

There are three main scenarios to test for Noise Pipes: XX for a "full handshake", IK with a successful response for an "abbreviated handshake", and IK followed by XXfallback for a "fallback handshake".

The "full handshake" and successful "abbreviated handshake" cases are tested in the same way as before because they are normal XX and IK handshake patterns.

The "fallback handshake" case requires some special handling by the test runner to deal with the transition from IK to XXfallback. This special handling is indicated in the test case by setting fallback to true. The pattern for the test case must be set to IK and init_remote_static must be a different public key than the one corresponding to resp_static, to trigger the fallback (they would normally correspond for a successful IK handshake).

The first message in the messages array is the initial IK handshake message from initiator to responder. The responder fails on this message and triggers fallback. The roles are reversed and the handshake restarts with the pattern set to XXfallback. The init_remote_static value is ignored when the handshake restarts and the init_* and resp_* fields are reversed in meaning.

The initiator's semi-ephemeral public key is carried across from IK to XXfallback. This value does not explicitly appear in the test case as an init_* or resp_* field. It is assumed that the implementation will extract the value from the first IK handshake message and pass it to the XXfallback session.

The second message in the messages array is the initial XXfallback handshake message from the former responder (now the initiator) back to the former initiator (now the responder).

The remaining messages proceed as per a normal handshake followed by data transfer.

If the fallback pattern name is not XXfallback, then the fallback_pattern key can be provided to specify an alternative pattern:

"fallback": true
"fallback_pattern": "XXfallback+hfs"

Hybrid Forward Secrecy

The hybrid key specifies the name of the algorithm to use for Hybrid Forward Secrecy.

Examples

https://github.com/noiseprotocol/noise_wiki.wiki.git

Clone this wiki locally