Libguestfs - Oct 2019 - [libnbd PATCH] docs: Add libnbd-security(1) man page

Copies heavily after a similar addition recently made in nbdkit.
---

I'm not sure if .1 or .3 fits better for the man page.  With nbdkit,
.1 made sense because 'nbdkit' is a standalone program; but with
libnbd, our only standalone is nbdsh, yet naming it nbdsh-security
seems off.

 docs/Makefile.am         |  7 +++++++
 docs/libnbd-security.pod | 32 ++++++++++++++++++++++++++++++++
 docs/libnbd.pod          |  1 +
 Makefile.am              |  1 +
 .gitignore               |  3 ++-
 SECURITY                 | 14 ++++++++++++++
 6 files changed, 57 insertions(+), 1 deletion(-)
 create mode 100644 docs/libnbd-security.pod
 create mode 100644 SECURITY

diff --git a/docs/Makefile.am b/docs/Makefile.am
index df58586..4c99b5d 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -38,6 +38,7 @@ generator_built = \
 EXTRA_DIST = \
 	$(generator_built) \
 	libnbd.pod \
+	libnbd-security.pod \
 	nbd_create.pod \
 	nbd_close.3 \
 	nbd_get_error.3 \
@@ -48,6 +49,7 @@ if HAVE_POD

 man_MANS = \
 	libnbd.3 \
+	libnbd-security.1 \
 	nbd_create.3 \
 	nbd_close.3 \
 	nbd_get_error.3 \
@@ -73,4 +75,9 @@ libnbd.3: libnbd.pod $(top_builddir)/podwrapper.pl \
 	    --html $(top_builddir)/html/$@.html \
 	    $<

+libnbd-security.1: libnbd-security.pod
+	$(PODWRAPPER) --section=1 --man $@ \
+	    --html $(top_builddir)/html/$@.html \
+	    $<
+
 endif HAVE_POD
diff --git a/docs/libnbd-security.pod b/docs/libnbd-security.pod
new file mode 100644
index 0000000..5fe0926
--- /dev/null
+++ b/docs/libnbd-security.pod
@@ -0,0 +1,32 @@
+=head1 NAME
+
+libnbd-security - information about past security issues in libnbd
+
+=head1 DESCRIPTION
+
+This page details past security issues found in libnbd.
+
+For how to report new security issues, see the C<SECURITY> file in the
+top level source directory, also available online here:
+L<https://github.com/libguestfs/libnbd/blob/master/SECURITY>
+
+=head2 CVE-2019-14842
+protocol downgrade attack when using LIBNBD_TLS_REQUIRE
+
+See the full announcement and links to mitigation, tests and fixes
+here:
+https://www.redhat.com/archives/libguestfs/2019-September/msg00128.html
+
+=head1 SEE ALSO
+
+L<libnbd(1)>.
+
+=head1 AUTHORS
+
+Eric Blake
+
+Richard W.M. Jones
+
+=head1 COPYRIGHT
+
+Copyright (C) 2019 Red Hat Inc.
diff --git a/docs/libnbd.pod b/docs/libnbd.pod
index 7bd59f5..e4810f6 100644
--- a/docs/libnbd.pod
+++ b/docs/libnbd.pod
@@ -830,6 +830,7 @@
L<https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md>.

 =head2 Other

+L<libnbd-security(1),
 L<qemu(1)>.

 =head1 AUTHORS
diff --git a/Makefile.am b/Makefile.am
index 59918b9..019936f 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -24,6 +24,7 @@ EXTRA_DIST = \
 	.gitignore \
 	html/pod.css \
 	scripts/git.orderfile \
+	SECURITY \
 	$(NULL)

 SUBDIRS = \
diff --git a/.gitignore b/.gitignore
index 9254d1a..ae3e04f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -37,10 +37,11 @@ Makefile.in
 /config.sub
 /configure
 /depcomp
-/docs/*.3
+/docs/*.[13]
 /docs/*.pod
 /docs/Makefile.inc
 !/docs/libnbd.pod
+!/docs/libnbd-security.pod
 !/docs/nbd_close.3
 !/docs/nbd_create.pod
 !/docs/nbd_get_err??.3
diff --git a/SECURITY b/SECURITY
new file mode 100644
index 0000000..d9a32d6
--- /dev/null
+++ b/SECURITY
@@ -0,0 +1,14 @@
+If you think you've found a serious or potential security bug that you
+don't want to report on a public mailing list, then send email to both
+<rjones@redhat.com> and <eblake@redhat.com>.
+
+Make it clear in the email Subject line that it's a serious or
+security-related bug in libnbd.
+
+You can also sign and/or encrypt messages using our GPG public keys
+available on the usual keyservers.
+
+For information about past security issues, see
+docs/libnbd-security.pod, or the libnbd-security(1) man page if you
+have installed libnbd, also available online here:
+http://libguestfs.org/libnbd-security.1.html
-- 
2.21.0

On Tue, Oct 01, 2019 at 02:28:39PM -0500, Eric Blake
wrote:
> Copies heavily after a similar addition recently made in nbdkit.
> ---
> 
> I'm not sure if .1 or .3 fits better for the man page.  With nbdkit,
> .1 made sense because 'nbdkit' is a standalone program; but with
> libnbd, our only standalone is nbdsh, yet naming it nbdsh-security
> seems off.
So the patch is fine, thanks for adding it.  I don't think I have a
strong opinion about whether the new page should be in section 1 or 3.
I would lean towards section 3 because that's where our other man
pages have gone, and as you say it's not a command line tool.  But
it's not a strong preference, so you can decide.

Rich.
>  docs/Makefile.am         |  7 +++++++
>  docs/libnbd-security.pod | 32 ++++++++++++++++++++++++++++++++
>  docs/libnbd.pod          |  1 +
>  Makefile.am              |  1 +
>  .gitignore               |  3 ++-
>  SECURITY                 | 14 ++++++++++++++
>  6 files changed, 57 insertions(+), 1 deletion(-)
>  create mode 100644 docs/libnbd-security.pod
>  create mode 100644 SECURITY
> 
> diff --git a/docs/Makefile.am b/docs/Makefile.am
> index df58586..4c99b5d 100644
> --- a/docs/Makefile.am
> +++ b/docs/Makefile.am
> @@ -38,6 +38,7 @@ generator_built = \
>  EXTRA_DIST = \
>  	$(generator_built) \
>  	libnbd.pod \
> +	libnbd-security.pod \
>  	nbd_create.pod \
>  	nbd_close.3 \
>  	nbd_get_error.3 \
> @@ -48,6 +49,7 @@ if HAVE_POD
> 
>  man_MANS = \
>  	libnbd.3 \
> +	libnbd-security.1 \
>  	nbd_create.3 \
>  	nbd_close.3 \
>  	nbd_get_error.3 \
> @@ -73,4 +75,9 @@ libnbd.3: libnbd.pod $(top_builddir)/podwrapper.pl \
>  	    --html $(top_builddir)/html/$@.html \
>  	    $<
> 
> +libnbd-security.1: libnbd-security.pod
> +	$(PODWRAPPER) --section=1 --man $@ \
> +	    --html $(top_builddir)/html/$@.html \
> +	    $<
> +
>  endif HAVE_POD
> diff --git a/docs/libnbd-security.pod b/docs/libnbd-security.pod
> new file mode 100644
> index 0000000..5fe0926
> --- /dev/null
> +++ b/docs/libnbd-security.pod
> @@ -0,0 +1,32 @@
> +=head1 NAME
> +
> +libnbd-security - information about past security issues in libnbd
> +
> +=head1 DESCRIPTION
> +
> +This page details past security issues found in libnbd.
> +
> +For how to report new security issues, see the C<SECURITY> file in
the
> +top level source directory, also available online here:
> +L<https://github.com/libguestfs/libnbd/blob/master/SECURITY>
> +
> +=head2 CVE-2019-14842
> +protocol downgrade attack when using LIBNBD_TLS_REQUIRE
> +
> +See the full announcement and links to mitigation, tests and fixes
> +here:
> +https://www.redhat.com/archives/libguestfs/2019-September/msg00128.html
> +
> +=head1 SEE ALSO
> +
> +L<libnbd(1)>.
> +
> +=head1 AUTHORS
> +
> +Eric Blake
> +
> +Richard W.M. Jones
> +
> +=head1 COPYRIGHT
> +
> +Copyright (C) 2019 Red Hat Inc.
> diff --git a/docs/libnbd.pod b/docs/libnbd.pod
> index 7bd59f5..e4810f6 100644
> --- a/docs/libnbd.pod
> +++ b/docs/libnbd.pod
> @@ -830,6 +830,7 @@
L<https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md>.
> 
>  =head2 Other
> 
> +L<libnbd-security(1),
>  L<qemu(1)>.
> 
>  =head1 AUTHORS
> diff --git a/Makefile.am b/Makefile.am
> index 59918b9..019936f 100644
> --- a/Makefile.am
> +++ b/Makefile.am
> @@ -24,6 +24,7 @@ EXTRA_DIST = \
>  	.gitignore \
>  	html/pod.css \
>  	scripts/git.orderfile \
> +	SECURITY \
>  	$(NULL)
> 
>  SUBDIRS = \
> diff --git a/.gitignore b/.gitignore
> index 9254d1a..ae3e04f 100644
> --- a/.gitignore
> +++ b/.gitignore
> @@ -37,10 +37,11 @@ Makefile.in
>  /config.sub
>  /configure
>  /depcomp
> -/docs/*.3
> +/docs/*.[13]
>  /docs/*.pod
>  /docs/Makefile.inc
>  !/docs/libnbd.pod
> +!/docs/libnbd-security.pod
>  !/docs/nbd_close.3
>  !/docs/nbd_create.pod
>  !/docs/nbd_get_err??.3
> diff --git a/SECURITY b/SECURITY
> new file mode 100644
> index 0000000..d9a32d6
> --- /dev/null
> +++ b/SECURITY
> @@ -0,0 +1,14 @@
> +If you think you've found a serious or potential security bug that you
> +don't want to report on a public mailing list, then send email to both
> +<rjones@redhat.com> and <eblake@redhat.com>.
> +
> +Make it clear in the email Subject line that it's a serious or
> +security-related bug in libnbd.
> +
> +You can also sign and/or encrypt messages using our GPG public keys
> +available on the usual keyservers.
> +
> +For information about past security issues, see
> +docs/libnbd-security.pod, or the libnbd-security(1) man page if you
> +have installed libnbd, also available online here:
> +http://libguestfs.org/libnbd-security.1.html
> -- 
> 2.21.0
> 
> _______________________________________________
> Libguestfs mailing list
> Libguestfs@redhat.com
> https://www.redhat.com/mailman/listinfo/libguestfs
-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
virt-builder quickly builds VMs from scratch
http://libguestfs.org/virt-builder.1.html