From ab59ef0d79ece2b441782a3be8e647a54c894dee Mon Sep 17 00:00:00 2001 From: frank honza Date: Mon, 26 Oct 2020 13:18:06 +0100 Subject: [PATCH] ikev1: add documentation for ikev1 --- doc/userguide/output/eve/eve-json-format.rst | 109 +++++++++++++ doc/userguide/rules/ike-keywords.rst | 155 +++++++++++++++++++ doc/userguide/rules/index.rst | 1 + doc/userguide/upgrade.rst | 5 + 4 files changed, 270 insertions(+) create mode 100644 doc/userguide/rules/ike-keywords.rst diff --git a/doc/userguide/output/eve/eve-json-format.rst b/doc/userguide/output/eve/eve-json-format.rst index 8901998408..88545f7deb 100644 --- a/doc/userguide/output/eve/eve-json-format.rst +++ b/doc/userguide/output/eve/eve-json-format.rst @@ -1811,3 +1811,112 @@ Example of HTTP2 logging, of a request and response: ] } } + +Event type: IKE +--------------- + +The parser implementations for IKEv1 and IKEv2 have a slightly different feature +set. They can be distinguished using the "version_major" field (which equals +either 1 or 2). +The unique properties are contained within a separate "ikev1" and "ikev2" sub-object. + +Fields +~~~~~~ + +* "init_spi", "resp_spi": The Security Parameter Index (SPI) of the initiator and responder. +* "version_major": Major version of the ISAKMP header. +* "version_minor": Minor version of the ISAKMP header. +* "payload": List of payload types in the current packet. +* "exchange_type": Type of the exchange, as numeric values. +* "exchange_type_verbose": Type of the exchange, in human-readable form. Needs ``extended: yes`` set in the ``ike`` EVE output option. +* "alg_enc", "alg_hash", "alg_auth", "alg_dh", "alg_esn": Properties of the chosen security association by the server. +* "ikev1.encrypted_payloads": Set to ``true`` if the payloads in the packet are encrypted. +* "ikev1.doi": Value of the domain of interpretation (DOI). +* "ikev1.server.key_exchange_payload", "ikev1.client.key_exchange_payload": Public key exchange payloads of the server and client. +* "ikev1.server.key_exchange_payload_length", "ikev1.client.key_exchange_payload_length": Length of the public key exchange payload. +* "ikev1.server.nonce_payload", "ikev1.client.nonce_payload": Nonce payload of the server and client. +* "ikev1.server.nonce_payload_length", "ikev1.client.nonce_payload_length": Length of the nonce payload. +* "ikev1.client.client_proposals": List of the security associations proposed to the server. +* "ikev1.vendor_ids": List of the vendor IDs observed in the communication. + + + +Examples +~~~~~~~~ + +Example of IKE logging: + +:: + + "ike": { + "version_major": 1, + "version_minor": 0, + "init_spi": "8511617bfea2f172", + "resp_spi": "c0fc6bae013de0f5", + "message_id": 0, + "exchange_type": 2, + "exchange_type_verbose": "Identity Protection", + "sa_life_type": "LifeTypeSeconds", + "sa_life_type_raw": 1, + "sa_life_duration": "Unknown", + "sa_life_duration_raw": 900, + "alg_enc": "EncAesCbc", + "alg_enc_raw": 7, + "alg_hash": "HashSha2_256", + "alg_hash_raw": 4, + "alg_auth": "AuthPreSharedKey", + "alg_auth_raw": 1, + "alg_dh": "GroupModp2048Bit", + "alg_dh_raw": 14, + "sa_key_length": "Unknown", + "sa_key_length_raw": 256, + "alg_esn": "NoESN", + "payload": [ + "VendorID", + "Transform", + "Proposal", + "SecurityAssociation" + ], + "ikev1": { + "doi": 1, + "encrypted_payloads": false, + "client": { + "key_exchange_payload": "0bf7907681a656aabed38fb1ba8918b10d707a8e635a...", + "key_exchange_payload_length": 256, + "nonce_payload": "1427d158fc1ed6bbbc1bd81e6b74960809c87d18af5f0abef14d5274ac232904", + "nonce_payload_length": 32, + "proposals": [ + { + "sa_life_type": "LifeTypeSeconds", + "sa_life_type_raw": 1, + "sa_life_duration": "Unknown", + "sa_life_duration_raw": 900, + "alg_enc": "EncAesCbc", + "alg_enc_raw": 7, + "alg_hash": "HashSha2_256", + "alg_hash_raw": 4, + "alg_auth": "AuthPreSharedKey", + "alg_auth_raw": 1, + "alg_dh": "GroupModp2048Bit", + "alg_dh_raw": 14, + "sa_key_length": "Unknown", + "sa_key_length_raw": 256 + } + ] + }, + "server": { + "key_exchange_payload": "1e43be52b088ec840ff81865074b6d459b5ca7813b46...", + "key_exchange_payload_length": 256, + "nonce_payload": "04d78293ead007bc1a0f0c6c821a3515286a935af12ca50e08905b15d6c8fcd4", + "nonce_payload_length": 32 + }, + "vendor_ids": [ + "4048b7d56ebce88525e7de7f00d6c2d3", + "4a131c81070358455c5728f20e95452f", + "afcad71368a1f1c96b8696fc77570100", + "7d9419a65310ca6f2c179d9215529d56", + "cd60464335df21f87cfdb2fc68b6a448", + "90cb80913ebb696e086381b5ec427b1f" + ] + }, + } diff --git a/doc/userguide/rules/ike-keywords.rst b/doc/userguide/rules/ike-keywords.rst new file mode 100644 index 0000000000..b8ee70277e --- /dev/null +++ b/doc/userguide/rules/ike-keywords.rst @@ -0,0 +1,155 @@ +IKE Keywords +============ + +The keywords + +* ``ike.init_spi`` +* ``ike.resp_spi`` +* ``ike.chosen_sa_attribute`` +* ``ike.exchtype`` +* ``ike.vendor`` +* ``ike.key_exchange_payload`` +* ``ike.key_exchange_payload_length`` +* ``ike.nonce_payload`` +* ``ike.nonce_payload_length`` + +can be used for matching on various properties of IKE connections. + + +ike.init_spi, ike.resp_spi +-------------------------- + +Match on an exact value of the Security Parameter Index (SPI) for the Initiator or Responder. + +Examples:: + + ike.init_spi; content:"18fe9b731f9f8034"; + ike.resp_spi; content:"a00b8ef0902bb8ec"; + +``ike.init_spi`` and ``ike.resp_spi`` are 'sticky buffer'. + +``ike.init_spi`` and ``ike.resp_spi`` can be used as ``fast_pattern``. + + +ike.chosen_sa_attribute +----------------------- + +Match on an attribute value of the chosen Security Association (SA) by the Responder. Supported for IKEv1 are: +``alg_enc``, +``alg_hash``, +``alg_auth``, +``alg_dh``, +``alg_prf``, +``sa_group_type``, +``sa_life_type``, +``sa_life_duration``, +``sa_key_length`` and +``sa_field_size``. +IKEv2 supports ``alg_enc``, ``alg_auth``, ``alg_prf`` and ``alg_dh``. + + +Examples:: + + ike.chosen_sa_attribute:alg_hash=2; + ike.chosen_sa_attribute:sa_key_length=128; + + +ike.exchtype +------------ + +Match on the value of the Exchange Type. + +This keyword takes a numeric argument after a colon and supports additional qualifiers, such as: + +* ``>`` (greater than) +* ``<`` (less than) +* ``>=`` (greater than or equal) +* ``<=`` (less than or equal) +* ``arg1-arg2`` (range) + +Examples:: + + ike.exchtype:5; + ike.exchtype:>=2; + + +ike.vendor +---------- + +Match a vendor ID against the list of collected vendor IDs. + +Examples:: + + ike.vendor:4a131c81070358455c5728f20e95452f; + + +ike.key_exchange_payload +------------------------ + +Match against the public key exchange payload (e.g. Diffie-Hellman) of the server or client. + +Examples:: + + ike.key_exchange_payload; content:"|6d026d5616c45be05e5b898411e9|" + +``ike.key_exchange_payload`` is a 'sticky buffer'. + +``ike.key_exchange_payload`` can be used as ``fast_pattern``. + + +ike.key_exchange_payload_length +------------------------------- + +Match against the length of the public key exchange payload (e.g. Diffie-Hellman) of the server or client. + +This keyword takes a numeric argument after a colon and supports additional qualifiers, such as: + +* ``>`` (greater than) +* ``<`` (less than) +* ``>=`` (greater than or equal) +* ``<=`` (less than or equal) +* ``arg1-arg2`` (range) + +Examples:: + + ike.key_exchange_payload_length:>132 + + +ike.nonce_payload +----------------- + +Match against the nonce of the server or client. + +Examples:: + + ike.nonce_payload; content:"|6d026d5616c45be05e5b898411e9|" + +``ike.nonce_payload`` is a 'sticky buffer'. + +``ike.nonce_payload`` can be used as ``fast_pattern``. + + +ike.nonce_payload_length +------------------------ + +Match against the length of the nonce of the server or client. + +This keyword takes a numeric argument after a colon and supports additional qualifiers, such as: + +* ``>`` (greater than) +* ``<`` (less than) +* ``>=`` (greater than or equal) +* ``<=`` (less than or equal) +* ``arg1-arg2`` (range) + +Examples:: + + ike.nonce_payload_length:132 + ike.nonce_payload_length:>132 + + +Additional information +---------------------- + +More information on the protocol and the data contained in it can be found here: +``_ diff --git a/doc/userguide/rules/index.rst b/doc/userguide/rules/index.rst index 651763a64a..2e7dd00c96 100644 --- a/doc/userguide/rules/index.rst +++ b/doc/userguide/rules/index.rst @@ -27,6 +27,7 @@ Suricata Rules sip-keywords rfb-keywords mqtt-keywords + ike-keywords http2-keywords app-layer xbits diff --git a/doc/userguide/upgrade.rst b/doc/userguide/upgrade.rst index e4eedb051d..fd05fdd52e 100644 --- a/doc/userguide/upgrade.rst +++ b/doc/userguide/upgrade.rst @@ -54,6 +54,11 @@ Removals if this behavior is still required. See :ref:`multiple-eve-instances`. - Unified2 has been removed. See :ref:`unified2-removed`. +Logging changes +~~~~~~~~~~~~~~~ +- IKEv2 Eve logging changed, the event_type has become ``ike``. The fields ``errors`` and ``notify`` have moved to + ``ike.ikev2.errors`` and ``ike.ikev2.notify``. + Upgrading 4.1 to 5.0 --------------------