From: jason taylor Date: Wed, 22 May 2024 01:04:09 +0000 (-0400) Subject: doc: add source verification docs X-Git-Tag: suricata-8.0.0-beta1~1272 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=47d6c3a3ab632dca72e60b753afa60521f0ea079;p=thirdparty%2Fsuricata.git doc: add source verification docs Ticket: #6908 Signed-off-by: jason taylor --- diff --git a/doc/userguide/Makefile.am b/doc/userguide/Makefile.am index 8ffede5974..53f4907eb7 100644 --- a/doc/userguide/Makefile.am +++ b/doc/userguide/Makefile.am @@ -31,7 +31,8 @@ EXTRA_DIST = \ setting-up-ipsinline-for-windows.rst \ support-status.rst \ unix-socket.rst \ - what-is-suricata.rst + what-is-suricata.rst \ + verifying-source-files.rst if HAVE_SURICATA_MAN dist_man1_MANS = suricata.1 suricatasc.1 suricatactl.1 suricatactl-filestore.1 diff --git a/doc/userguide/index.rst b/doc/userguide/index.rst index e30de788fe..1440fa8280 100644 --- a/doc/userguide/index.rst +++ b/doc/userguide/index.rst @@ -34,3 +34,4 @@ This is the documentation for Suricata |version|. acknowledgements licenses/index.rst devguide/index.rst + verifying-source-files \ No newline at end of file diff --git a/doc/userguide/install.rst b/doc/userguide/install.rst index cfb3c1bbbd..ef9efdbb54 100644 --- a/doc/userguide/install.rst +++ b/doc/userguide/install.rst @@ -16,6 +16,9 @@ Source Installing from the source distribution files gives the most control over the Suricata installation. +The Suricata source distribution files should be verified before building +the source, see :doc:`verifying-source-files`. + Basic steps:: tar xzvf suricata-6.0.0.tar.gz diff --git a/doc/userguide/verifying-source-files.rst b/doc/userguide/verifying-source-files.rst new file mode 100644 index 0000000000..52204b20d1 --- /dev/null +++ b/doc/userguide/verifying-source-files.rst @@ -0,0 +1,86 @@ +Verifying Suricata Source Distribution Files +============================================ + +Once the Suricata release distribution file has been downloaded, the PGP +signature should be verified. This can be done using the GPG application and +is usually available on Linux/BSD systems without having to manually install +any additional packages. For Mac or Windows systems installation packages can +be found at ``_. + +Verification Steps +------------------ + +These verification steps are for general guidance, the exact process and +commands may vary between operating systems. + +Downloading the Signature File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The signature file needs to be downloaded as well as the distribution file. +Both files can be found at ``_. + +Importing the OISF Signing Key +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Once both the signature file and Suricata distribution files are obtained, the +OISF signing key should be imported to the local gpg keyring. This can be done +by running the following command:: + + $ gpg --receive-keys 2BA9C98CCDF1E93A + +The above command should produce output similar to the following:: + + gpg: key 2BA9C98CCDF1E93A: public key "Open Information Security Foundation + (OISF) " imported + gpg: Total number processed: 1 + gpg: imported: 1 + +Verifying the Suricata Distribution File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To verify the contents of the Suricata distribution file the following command +could be ran on the Suricata 7.0.5 distribution file:: + + $ gpg --verify suricata-7.0.5.tar.gz.sig suricata-7.0.5.tar.gz + +Depending on the trust level assigned to the OISF signing keys, something +similar to the following output should be seen:: + + $ gpg --verify suricata-7.0.5.tar.gz.sig suricata-7.0.5.tar.gz + gpg: Signature made Tue 23 Apr 2024 11:58:56 AM UTC + gpg: using RSA key B36FDAF2607E10E8FFA89E5E2BA9C98CCDF1E93A + gpg: checking the trustdb + gpg: marginals needed: 3 completes needed: 1 trust model: pgp + gpg: depth: 0 valid: 1 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 1u + gpg: next trustdb check due at 2025-08-06 + gpg: Good signature from "Open Information Security Foundation (OISF) + " [ultimate] + +This indicates a valid signature and that the signing key is trusted. + +.. note:: If output from the `--verify` command is similar to the following:: + + gpg: Signature made Tue 23 Apr 2024 11:58:56 AM UTC + gpg: using RSA key B36FDAF2607E10E8FFA89E5E2BA9C98CCDF1E93A + gpg: Can't check signature: No public key + + This indicates that the OISF signing key was not imported to the local GPG + keyring. + +.. note:: If output from the `--verify` command is similar to the following:: + + gpg: Signature made Tue 23 Apr 2024 11:58:56 AM UTC + gpg: using RSA key B36FDAF2607E10E8FFA89E5E2BA9C98CCDF1E93A + gpg: Good signature from "Open Information Security Foundation (OISF) + " [unknown] + gpg: WARNING: This key is not certified with a trusted signature! + gpg: There is no indication that the signature belongs to the owner. + Primary key fingerprint: B36F DAF2 607E 10E8 FFA8 9E5E 2BA9 C98C CDF1 E93A + + This indicates that the OISF signing key was imported and the signatures are + valid, but either the keys have not been marked as trusted OR the keys are + possibly a forgery. + + If there are questions regarding the validity of the downloaded file, the + OISF team can be reached at `security @ oisf.net` (remove the spaces between + the `@` before sending). \ No newline at end of file