Bug#719262: [src:openssl] Please review package descriptions
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 lib
Bug#719262: [Pkg-openssl-devel] Bug#719262: [src:openssl] Please review package descriptions
Dear Kurt,
thank you for your prompt response.
>> 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.
>> .
>> - 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.
> I'm not sure mentioning those package is useful, since it gets
> installed as dependency. It doesn't explain what it does. But
> I really have nothing really useful to say about such things.
I just wanted to introduce a unified description, add common boilerplate
and be as minimally invasive as an NMU. But IMHO you are very right. It's a
shared library's nature to be used by several programs. Without explaining
their purpose it is just namedropping.
>> @@ -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
> Maybe it should mention both SSL and TLS.
> Maybe it should make a reference to https?
> Do you think it's useful to also mention things like RSA
> in the description of the shared libraries?
I'm not a computer scientist by education. I don't know anything about
cryptographic protocols. From my Jon Doe POV there is no benefit in
mentioning TLS and HTTPS - at least without shortly explaining them.
Martin
PS: There was a typo in my patch.
--- control.orig 2013-08-08 00:20:03.0 +0200
+++ control 2013-08-09 23:45:13.0 +0200
@@ -13,12 +13,16 @@
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.
+OpenSSL's Secure Sockets Layer implementation - xxx
+ This package is part of the OpenSSL project's implementation of the SSL
+ cryptographic protocol for communication security over the internet.
+Description: Secure Sockets Layer implementation - binary and related cryptographic tools
+ This package is part of the OpenSSL project's implementation of the SSL
+ cryptographic protocol for communication security over the internet.
.
- It is part of the OpenSSL implementation of SSL.
+ It contains the openssl binary and related tools.
.
- You need it to perform certain cryptographic actions like:
+ You need it to perform cryptographic operations such as:
- Creation of RSA, DH and DSA key parameters;
- Creation of X.509 certificates, CSRs and CRLs;
- Calculation of message digests;
@@ -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
+ cryptographic protocol for communication security over the internet.
.
- 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.
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
+ cryptographic 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.
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
Bug#719262: [Pkg-openssl-devel] Bug#719262: [src:openssl] Please review package descriptions
On Fri, Aug 09, 2013 at 09:54:16PM +0200, Martin Eberhard Schauer wrote:
> 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.
> .
> - 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.
I'm not sure mentioning those package is useful, since it gets
installed as dependency. It doesn't explain what it does. But
I really have nothing really useful to say about such things.
> @@ -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.
Maybe it should mention both SSL and TLS.
Maybe it should make a reference to https?
Do you think it's useful to also mention things like RSA
in the description of the shared libraries?
Kurt
--
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org
Bug#719262: [src:openssl] Please review package descriptions
Package: src:openssl
Version: 1.0.1e-3
Severity: wishlist
X-Debbugs-CC: debian-l10n-engl...@lists.debian.org
Dear Debian OpenSSL Team,
as libssl has a high popcon I suggest a bit of rewording to adhere better to
(1). I would like to see some boilerplate explaining (Open)SSL, unified
short
descriptions and "complete" sentences. For your convenience I prepared a
debian/control with rewritten descriptions, using information from Wikipedia
(2) and the OpenSSL project homepage (3) to be used as a starting point.
Kind regards
Martin
1:
http://www.debian.org/doc/manuals/developers-reference/best-pkging-practices.html#bpp-debian-control
2: http://en.wikipedia.org/wiki/Transport_Layer_Security
Transport Layer Security (TLS) and its predecessor, Secure Sockets Layer
(SSL), are cryptographic protocols that provide communication
security over
the Internet.[1]
3: http://www.openssl.org/
Welcome to the OpenSSL Project
The OpenSSL Project is a collaborative effort to develop a robust,
commercial-grade, full-featured, and Open Source toolkit
implementing the
Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS v1)
protocols as well as a full-strength general purpose cryptography
library.
…
--- control.orig 2013-08-08 00:20:03.0 +0200
+++ control 2013-08-08 01:04:17.0 +0200
@@ -13,12 +13,16 @@
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.
+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.
+Description: Secure Sockets Layer implementation - binary and related cryptographic tools
+ 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 the openssl binary and related tools.
.
- You need it to perform certain cryptographic actions like:
+ You need it to perform cryptographic operations such as:
- Creation of RSA, DH and DSA key parameters;
- Creation of X.509 certificates, CSRs and CRLs;
- Calculation of message digests;
@@ -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.
.
- 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.
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.
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.
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
+ 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.
Package: libssl1.0.0-dbg
Section: debug
