[Openvas-commits] r411 - in trunk/openvas-libnasl: . doc

scm-commit@wald.intevation.org scm-commit at wald.intevation.org
Fri Oct 5 20:50:42 CEST 2007


Author: bh
Date: 2007-10-05 20:50:42 +0200 (Fri, 05 Oct 2007)
New Revision: 411

Added:
   trunk/openvas-libnasl/doc/signatures-howto.txt
Modified:
   trunk/openvas-libnasl/ChangeLog
Log:
* doc/signatures-howto.txt: Add some documentation about signature
handling in OpenVAS NASL


Modified: trunk/openvas-libnasl/ChangeLog
===================================================================
--- trunk/openvas-libnasl/ChangeLog	2007-10-05 15:26:37 UTC (rev 410)
+++ trunk/openvas-libnasl/ChangeLog	2007-10-05 18:50:42 UTC (rev 411)
@@ -1,5 +1,10 @@
 2007-10-05  Bernhard Herzog  <bh at intevation.de>
 
+	* doc/signatures-howto.txt: Add some documentation about signature
+	handling in OpenVAS NASL
+
+2007-10-05  Bernhard Herzog  <bh at intevation.de>
+
 	Extend the test suite to test signature verification
 
 	* test/signed.nasl, test/signed.nasl.asc: New. Signed NASL script

Added: trunk/openvas-libnasl/doc/signatures-howto.txt
===================================================================
--- trunk/openvas-libnasl/doc/signatures-howto.txt	2007-10-05 15:26:37 UTC (rev 410)
+++ trunk/openvas-libnasl/doc/signatures-howto.txt	2007-10-05 18:50:42 UTC (rev 411)
@@ -0,0 +1,135 @@
+NASL-Signatures in OpenVAS
+==========================
+
+This file summarizes what users of OpenVAS and developers of NASL
+scripts should know about signed NASL files in OpenVAS.
+
+Some general familiarity with OpenPGP and GnuPG in particular is
+assumed.
+
+
+Signature Format
+----------------
+
+The signatures for NASL-Files in OpenVAS are standard ASCII-armored
+detached OpenPGP signatures.  This format was chosen because it fits
+these criteria:
+
+ - there can be multiple signer keys
+
+ - site administrators can decide which keys to trust
+
+ - Signatures can be created and verified with standard tools like GnuPG
+
+ - Signatures do not require changes to the signed file
+
+
+The name of the signature file is the name of the signed file with the
+added extension ".asc".  That is, the name of the signature file for a
+file "myscript.nasl" is "myscript.nasl.asc".
+
+The keyring used by GnuPG when run by OpenVAS to verify signatures is
+located in $sysconfdir/openvas/gnupg.  The vale of sysconfdir is set by
+the configure script and defaults to $prefix/etc.
+
+
+Running GnuPG
+-------------
+
+Use the GNUPGHOME environment variable or the --homedir command line
+option of gpg to tell it where OpenVAS stores its keyrings.  E. g. if
+the keyring is in $sysconfdir/openvas/gnupg you can either
+
+    export GNUPGHOME=$sysconfdir/openvas/gnupg
+
+before calling gpg, or
+
+    gpg --homedir=$sysconfdir/openvas/gnupg
+
+followed by the rest of the command line arguments.
+
+In the following, all command examples assume that the home directory is
+specified in one of these ways.
+
+
+Signature Verification
+----------------------
+
+When OpenVAS verifies a NASL signature it checks all signatures
+contained in the signature file and all signatures must be fully valid.
+This means that all of the following criteria must be fulfilled for all
+signatures:
+
+  1. The public key must be present in the keyring
+  2. The key must be fully valid
+  3. The signature must be valid.
+
+If any of the signatures does not meet all of these criteria, the file
+is considered untrustworthy and will not be exectuded at all.  If all
+signatures meet the criteria, the script is trusted fully and may
+execute restricted functions like fwrite.  If no signature file exists,
+the script is executed but may not execute restricted functions.
+
+To verify signatures on the command line, you can either run GnuPG:
+
+    gpg --verify script.nasl.asc script.nasl
+
+Or you can use the standalone nasl interpreter:
+
+    openvas-nasl -p script.nasl
+
+The -p Option means that the script is only parsed and not executed.
+
+To debug the signature verification done by the nasl interpreter, use
+the -T Option to enable the trace mode.  The signature verification will
+leave some detailed information about the verification and the
+signatures found in the trace file.
+
+
+Creating a Signing Key
+----------------------
+
+To sign nasl scripts yourself and to sign other signing keys (see
+"Validating a Key" below) you need a signing key.  You can use an
+existing key you already have, or you can generate a new one:
+
+    gpg --gen-key
+
+Generating a new one for your OpenVAS installation is recommended.
+
+
+Signing a NASL File
+-------------------
+
+    gpg --detach-sign -a myscript.nasl
+
+This will create the signature file myscript.nasl.asc.  If the file
+myscript.nasl.asc already exists it will be overwritten.
+
+To add a signature to an existing signature you can do
+
+    gpg --detach-sign -a -o myscript.nasl.asc2 myscript.nasl
+    cat myscript.nasl.asc2 >> myscript.nasl.asc
+
+
+Adding keys to the keyring
+--------------------------
+
+To add a key to the keyring, import it with gpg:
+
+    gpg --import keyfile.asc
+
+
+Validating a Key
+----------------
+
+For OpenVAS to trust a signature, the key used to create the signature
+has to be valid.  A key that was just imported has unknown validity and
+thus is not valid.  To make a key valid, you have to sign it.  The
+preferred way is to use local signatures which will not be exported from
+the keyring.  To sign the key with a known key id (use gpg --list-keys
+to determine the ID), use
+
+    gpg --lsign-key KEY_ID
+
+Check the fingerprint carefully before signing a key!


Property changes on: trunk/openvas-libnasl/doc/signatures-howto.txt
___________________________________________________________________
Name: svn:keywords
   + Author Date Id Revision
Name: svn:eol-style
   + native



More information about the Openvas-commits mailing list