[Pkg-openssl-devel] Bug#719262: [src:openssl] Please review package descriptions

[Justin B Rye]

Martin Eberhard Schauer wrote:
> -Description: Secure Socket Layer (SSL) binary and related cryptographic tools
> - This package contains the openssl binary and related tools.
> +OpenSSL's Secure Sockets Layer implementation - xxx
> + This package is part of the OpenSSL project's implementation of the SSL
> + cryptograpfic protocol for communication security over the internet.

What's going on here?

> +Description: Secure Sockets Layer implementation - binary and related cryptographic tools

Nobody seems to be able to decide whether it's "Socket" or
"Sockets"... oh, fair enough, RFC 6101 had plural.

Too long.  I suppose we could demote the expansion of OpenSSL to the
long description, but I'd rather get rid of the word "implementation",
which is rather a waste of space given that all software is
necessarily an implementation of something.  Yes, this general
approach gives us a suite-wide standard format for synopses, but how
about calling it a "toolkit"?  Upstream seem fond of the word.

What "related cryptographic tools" does openssl contain, though?  I
have to assume it's talking about the trivial shellscripts in
/usr/lib/ssl/misc, but how do those rate as "tools"?  Is there some
way of calling them other than via /usr/bin/openssl subcommands, and
some reason why I would care that these particular functions aren't
carried out directly by way of libssl/libcrypto?

Or then again are the "related cryptographic tools" a confused
reference to the subcommands like "openssl md5"?

Either way it seems pointless to mention them.  I would suggest:

   Description: Secure Sockets Layer toolkit - cryptographic utility

> + This package is part of the OpenSSL project's implementation of the SSL
> + cryptograpfic protocol for communication security over the internet.
              ^                                                ^
Typo: cryptographic.

"The Internet", capital I.

"For communication security" is a bit clumsy when we could just say
"for secure communication".

Cobwebby: shouldn't this mention TLS?

>   .
> - It is part of the OpenSSL implementation of SSL.
> + It contains the openssl binary and related tools.

Again, what related tools?  I wish I could find a good concise way of
expressing the idea that it's a "wrapper binary" with myriad
subcommands; maybe:

    This package is part of the OpenSSL project's implementation of the SSL
    and TLS cryptographic protocols for secure communication over the
    Internet.
    .
    It contains the general-purpose command line binary /usr/bin/openssl.

>   .
> - You need it to perform certain cryptographic actions like:
> + You need it to perform cryptographic operations such as:

While we're making it less informal English, avoiding the second
person pronoun would actually make it simpler:

    It is needed for cryptographic operations such as:

But that's a lie!  I can carry out (e.g.) "encryption and decryption
with ciphers" without using openssl.  How about, running this sentence
together with the last:

    It contains the general-purpose command line binary /usr/bin/openssl,
    useful for cryptographic operations such as:

>    -  Creation of RSA, DH and DSA key parameters;
>    -  Creation of X.509 certificates, CSRs and CRLs;
>    -  Calculation of message digests;

(The d-l-e house style would use singlespaced asterisks rather than
those doublespaced hyphens, and extra commas in those lists.  And I
would suggest "s/Creation of/creating/" etc. throughout.)

> @@ -33,11 +37,12 @@
>  Multi-Arch: same
>  Pre-Depends: ${misc:Pre-Depends}
>  Depends: ${shlibs:Depends}, ${misc:Depends}
> -Description: SSL shared libraries
> - libssl and libcrypto shared libraries needed by programs like
> - apache-ssl, telnet-ssl and openssh.
> +Description: Secure Sockets Layer implementation - shared libraries
> + This package is part of the OpenSSL project's implementation of the SSL
> + cryptograpfic protocol for communication security over the internet.

As above.

>   .
> - It is part of the OpenSSL implementation of SSL.
> + The libssl and libcrypto shared libraries are needed by programs like
> + apache-ssl, telnet-ssl and openssh.

These are cobwebby.  These days it's not just long-vanished nineties
programs like apache-ssl that depend on libssl1.0.0, it's everything
from bibtexconv to python3.2, and listing them is pointless when
anybody who cares can ask apt-cache rdepends.

   It provides the libssl and libcrypto shared libraries.
  
>  Package: libcrypto1.0.0-udeb
>  XC-Package-Type: udeb
> @@ -45,10 +50,12 @@
>  Priority: optional
>  Architecture: any
>  Depends: ${shlibs:Depends}, ${misc:Depends}
> -Description: crypto shared library - udeb
> - libcrypto shared library.
> +Description: Secure Sockets Layer implementation - libcrypto udeb
> + This package is part of the OpenSSL project's implementation of the SSL
> + cryptograpfic protocol for communication security over the internet.
>   .
> - Do not install it on a normal system.
> + It contains the libcrypto shared library. Do not install it on a normal
> + system.

This makes it sound as if containing libcrypto is what makes it
unsuitable for installation.

    It contains a version of the libcrypto shared library for use with the
    Debian Installer. Do not install it on a normal system.
  
>  Package: libssl-dev
>  Section: libdevel
> @@ -57,11 +64,12 @@
>  Multi-Arch: same
>  Recommends: libssl-doc
>  Depends: libssl1.0.0 (= ${binary:Version}), zlib1g-dev, ${misc:Depends}
> -Description: SSL development libraries, header files and documentation
> - libssl and libcrypto development libraries, header files and manpages.
> +Description: Secure Sockets Layer implementation - development files
> + This package is part of the OpenSSL project's implementation of the SSL
> + cryptograpfic protocol for communication security over the internet.
>   .
> - It is part of the OpenSSL implementation of SSL.
> -
> + It contains development libraries, header files and manpages for the libssl
> + and libcrypto libraries.

(Another opportunity for d-l-e's "Harvard comma".  Drop the second
"libraries".)
 
>  Package: libssl-doc
>  Section: doc
> @@ -70,10 +78,11 @@
>  Replaces: libssl-dev (<< 1.0.0)
>  Breaks: libssl-dev (<< 1.0.0)
>  Depends: ${shlibs:Depends}, ${perl:Depends}, ${misc:Depends}
> -Description: SSL development documentation documentation
> - libssl and libcrypto manpages and demo files.
> +Description: Secure Sockets Layer implementation - documentation

Keep the word "development"; it's not a user manual.

> + This package is part of the OpenSSL project's implementation of the SSL
> + cryptograpfic protocol for communication security over the internet.
>   .
> - It is part of the OpenSSL implementation of SSL.
> + It contains libssl and libcrypto manpages and demo files.

Say "manpages and demo files for libssl and libcrypto", to keep it in
line with the others.
  
>  Package: libssl1.0.0-dbg
>  Section: debug
> @@ -81,5 +90,8 @@
>  Architecture: any
>  Multi-Arch: same
>  Depends: libssl1.0.0 (= ${binary:Version}), ${misc:Depends}
> -Description: Symbol tables for libssl and libcrypto
> - This package is part of the OpenSSL implementation of SSL.
> +Description: Secure Sockets Layer implementation - debug information
> + This package is part of the OpenSSL project's implementation of the SSL
> + cryptograpfic protocol for communication security over the internet.
> + .
> + It contains symbol tables for libssl and libcrypto.

That's a remarkably unclear way of saying what it's good for... the
more standard and microscopically clearer phrasing is:

    It contains debugging symbols for libssl and libcrypto.

-- 
JBR	with qualifications in linguistics, experience as a Debian
	sysadmin, and probably no clue about this particular package
-------------- next part --------------
diff -ru -u openssl-1.0.1e.pristine/debian/control openssl-1.0.1e/debian/control
--- openssl-1.0.1e.pristine/debian/control	2013-05-20 15:31:36.000000000 +0100
+++ openssl-1.0.1e/debian/control	2013-08-09 23:20:51.090037181 +0100
@@ -13,18 +13,19 @@
 Architecture: any
 Depends: ${shlibs:Depends}, ${perl:Depends}, ${misc:Depends}
 Suggests: ca-certificates
-Description: Secure Socket Layer (SSL) binary and related cryptographic tools
- This package contains the openssl binary and related tools.
- .
- It is part of the OpenSSL implementation of SSL.
- .
- You need it to perform certain cryptographic actions like:
-  -  Creation of RSA, DH and DSA key parameters;
-  -  Creation of X.509 certificates, CSRs and CRLs;
-  -  Calculation of message digests;
-  -  Encryption and decryption with ciphers;
-  -  SSL/TLS client and server tests;
-  -  Handling of S/MIME signed or encrypted mail.
+Description: Secure Sockets Layer toolkit - cryptographic utility
+ This package is part of the OpenSSL project's implementation of the SSL
+ and TLS cryptographic protocols for secure communication over the
+ Internet.
+ .
+ It contains the general-purpose command line binary /usr/bin/openssl,
+ useful for cryptographic operations such as:
+  * creating RSA, DH, and DSA key parameters;
+  * creating X.509 certificates, CSRs, and CRLs;
+  * calculating message digests;
+  * encrypting and decrypting with ciphers;
+  * testing SSL/TLS clients and servers;
+  * handling S/MIME signed or encrypted mail.
 
 Package: libssl1.0.0
 Section: libs
@@ -33,11 +34,12 @@
 Multi-Arch: same
 Pre-Depends: ${misc:Pre-Depends}
 Depends: ${shlibs:Depends}, ${misc:Depends}
-Description: SSL shared libraries
- libssl and libcrypto shared libraries needed by programs like
- apache-ssl, telnet-ssl and openssh.
+Description: Secure Sockets Layer toolkit - shared libraries
+ This package is part of the OpenSSL project's implementation of the SSL
+ and TLS cryptographic protocols for secure communication over the
+ Internet.
  .
- It is part of the OpenSSL implementation of SSL.
+ It provides the libssl and libcrypto shared libraries.
 
 Package: libcrypto1.0.0-udeb
 XC-Package-Type: udeb
@@ -45,10 +47,13 @@
 Priority: optional
 Architecture: any
 Depends: ${shlibs:Depends}, ${misc:Depends}
-Description: crypto shared library - udeb
- libcrypto shared library.
+Description: Secure Sockets Layer toolkit - libcrypto udeb
+ This package is part of the OpenSSL project's implementation of the SSL
+ and TLS cryptographic protocols for secure communication over the
+ Internet.
  .
- Do not install it on a normal system.
+ It contains a version of the libcrypto shared library for use with the
+ Debian Installer. Do not install it on a normal system.
 
 Package: libssl-dev
 Section: libdevel
@@ -57,11 +62,13 @@
 Multi-Arch: same
 Recommends: libssl-doc
 Depends: libssl1.0.0 (= ${binary:Version}), zlib1g-dev, ${misc:Depends}
-Description: SSL development libraries, header files and documentation
- libssl and libcrypto development libraries, header files and manpages.
+Description: Secure Sockets Layer toolkit - development files
+ This package is part of the OpenSSL project's implementation of the SSL
+ and TLS cryptographic protocols for secure communication over the
+ Internet.
  .
- It is part of the OpenSSL implementation of SSL.
-
+ It contains development libraries, header files, and manpages for libssl
+ and libcrypto.
 
 Package: libssl-doc
 Section: doc
@@ -70,10 +77,12 @@
 Replaces: libssl-dev (<< 1.0.0)
 Breaks: libssl-dev (<< 1.0.0)
 Depends: ${shlibs:Depends}, ${perl:Depends}, ${misc:Depends}
-Description: SSL development documentation documentation
- libssl and libcrypto manpages and demo files.
+Description: Secure Sockets Layer toolkit - development documentation
+ This package is part of the OpenSSL project's implementation of the SSL
+ and TLS cryptographic protocols for secure communication over the
+ Internet.
  .
- It is part of the OpenSSL implementation of SSL.
+ It contains manpages and demo files for libssl and libcrypto.
 
 Package: libssl1.0.0-dbg
 Section: debug
@@ -81,5 +90,9 @@
 Architecture: any
 Multi-Arch: same
 Depends: libssl1.0.0 (= ${binary:Version}), ${misc:Depends}
-Description: Symbol tables for libssl and libcrypto
- This package is part of the OpenSSL implementation of SSL.
+Description: Secure Sockets Layer toolkit - debug information
+ This package is part of the OpenSSL project's implementation of the SSL
+ and TLS cryptographic protocols for secure communication over the
+ Internet.
+ .
+ It contains debugging symbols for libssl and libcrypto.
-------------- next part --------------
Source: openssl
Build-Depends: debhelper (>= 8.1.3), zlib1g-dev, m4, bc, dpkg-dev (>= 1.15.7)
Section: utils
Priority: optional
Maintainer: Debian OpenSSL Team <pkg-openssl-devel at lists.alioth.debian.org>
Uploaders: Christoph Martin <christoph.martin at uni-mainz.de>, Kurt Roeckx <kurt at roeckx.be>
Standards-Version: 3.8.0
Vcs-Browser: http://svn.debian.org/wsvn/pkg-openssl/openssl
Vcs-Svn: svn://svn.debian.org/pkg-openssl/openssl/

Package: openssl
Priority: optional
Architecture: any
Depends: ${shlibs:Depends}, ${perl:Depends}, ${misc:Depends}
Suggests: ca-certificates
Description: Secure Sockets Layer toolkit - cryptographic utility
 This package is part of the OpenSSL project's implementation of the SSL
 and TLS cryptographic protocols for secure communication over the
 Internet.
 .
 It contains the general-purpose command line binary /usr/bin/openssl,
 useful for cryptographic operations such as:
  * creating RSA, DH, and DSA key parameters;
  * creating X.509 certificates, CSRs, and CRLs;
  * calculating message digests;
  * encrypting and decrypting with ciphers;
  * testing SSL/TLS clients and servers;
  * handling S/MIME signed or encrypted mail.

Package: libssl1.0.0
Section: libs
Priority: important
Architecture: any
Multi-Arch: same
Pre-Depends: ${misc:Pre-Depends}
Depends: ${shlibs:Depends}, ${misc:Depends}
Description: Secure Sockets Layer toolkit - shared libraries
 This package is part of the OpenSSL project's implementation of the SSL
 and TLS cryptographic protocols for secure communication over the
 Internet.
 .
 It provides the libssl and libcrypto shared libraries.

Package: libcrypto1.0.0-udeb
XC-Package-Type: udeb
Section: debian-installer
Priority: optional
Architecture: any
Depends: ${shlibs:Depends}, ${misc:Depends}
Description: Secure Sockets Layer toolkit - libcrypto udeb
 This package is part of the OpenSSL project's implementation of the SSL
 and TLS cryptographic protocols for secure communication over the
 Internet.
 .
 It contains a version of the libcrypto shared library for use with the
 Debian Installer. Do not install it on a normal system.

Package: libssl-dev
Section: libdevel
Priority: optional
Architecture: any
Multi-Arch: same
Recommends: libssl-doc
Depends: libssl1.0.0 (= ${binary:Version}), zlib1g-dev, ${misc:Depends}
Description: Secure Sockets Layer toolkit - development files
 This package is part of the OpenSSL project's implementation of the SSL
 and TLS cryptographic protocols for secure communication over the
 Internet.
 .
 It contains development libraries, header files, and manpages for libssl
 and libcrypto.

Package: libssl-doc
Section: doc
Priority: optional
Architecture: all
Replaces: libssl-dev (<< 1.0.0)
Breaks: libssl-dev (<< 1.0.0)
Depends: ${shlibs:Depends}, ${perl:Depends}, ${misc:Depends}
Description: Secure Sockets Layer toolkit - development documentation
 This package is part of the OpenSSL project's implementation of the SSL
 and TLS cryptographic protocols for secure communication over the
 Internet.
 .
 It contains manpages and demo files for libssl and libcrypto.

Package: libssl1.0.0-dbg
Section: debug
Priority: extra
Architecture: any
Multi-Arch: same
Depends: libssl1.0.0 (= ${binary:Version}), ${misc:Depends}
Description: Secure Sockets Layer toolkit - debug information
 This package is part of the OpenSSL project's implementation of the SSL
 and TLS cryptographic protocols for secure communication over the
 Internet.
 .
 It contains debugging symbols for libssl and libcrypto.