db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Kim Haase (JIRA)" <j...@apache.org>
Subject [jira] Commented: (DERBY-2272) SSL Documentation
Date Fri, 25 May 2007 16:14:16 GMT

    [ https://issues.apache.org/jira/browse/DERBY-2272?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12499135
] 

Kim Haase commented on DERBY-2272:
----------------------------------

Excellent work, Bernt! I have just a few tech-writer corrections -- others can do better with
the technical review.


cadminssl.html (SSL/TLS):

It would be helpful to indicate what the abbreviations SSL and TLS stand for, the first time
they are used here. (You can just put the meanings in parentheses after "SSL/TLS" in the first
paragraph.)

Typo: "sever" for "server"


cadminsslkeys.html (Key and certificate handling):

Second sentence is a bit awkward -- how about this?

To generate the key pair using keytool, use a command like the following. In this example,
the key pair and corresponding certificate are valid for 7 days:

Does the keyalg have to be RSA? If so, maybe that should be stated.

First sentence of "Install server certificate on the client (optional)" lacks a period.

Replace "like this" with "as follows" (2 occurrences).

There's a lack of parallel structure between "Install server certificate on the client (optional)"
and "The client certificate (optional)". Should they be as follows?

Installing the server certificate on the client (optional)
Installing the client certificate on the server (optional)

Change "At the client with" to 

On the client, generate and export the certificate as follows:

Change "At the server" to

On the server, import the certificate as follows:


cadminsslserver.html (Starting the server) is fine.


cadminsslclient.html (Running the client):

Change "If also the server is in peer authentication mode" to "If the server is also in peer
authentication mode".


cadminssladmin.html (Other server commands):

Change 

are implemented as clients and behave that way with regards to SSL. So e.g.

to something like

are implemented as clients, and they behave as clients with regard to SSL. For example, the
command

And change 

will shutdown an SSL-enabled server. Similarly, if you have peerAuthentication on both sides,
it will be

to 

shuts down an SSL-enabled server. Similarly, if you have peerAuthentication on both sides,
use the following command:


radmindrdasslmode.html (derby.drda.sslMode property):

The first sentence is not a complete sentence -- and for a little consistency with descriptions
of other properties, I think it needs to be something like

Indicates whether the client connection is encrypted or not, and whether certificate based
peer authentication is enabled.

Or else "Use the derby.drda.sslMode property to indicate ..."

I would also recommend adding an example and description of the peerAuthentication setting,
just to be complete.


The devguide fix is fine.


rrefattribssl.html (ssl=sslMode attribute):

I think for consistency with other attribute descriptions the first sentence needs to be in
a "Function" section. And should it not be "Specifies the SSL mode"? It would also be helpful
to state the valid values. And there is an extra period at the end. So it could be changed
to

Function

Specifies the SSL mode of the client. The <i>sslMode<i> can be <codeph>basic</codeph>,
<codeph>peerAuthentication</codeph>, or <codeph>off</codeph> (the
default). See "SSL/TLS" in Derby Server and Administration Guide for details.

I see the other examples in the Ref Manual are extremely inconsistent, but this one could
be improved if the introductory sentence were

Connect to mydb with basic SSL encryption:


> SSL Documentation
> -----------------
>
>                 Key: DERBY-2272
>                 URL: https://issues.apache.org/jira/browse/DERBY-2272
>             Project: Derby
>          Issue Type: Sub-task
>          Components: Documentation
>            Reporter: Bernt M. Johnsen
>         Assigned To: Bernt M. Johnsen
>             Fix For: 10.3.0.0
>
>         Attachments: DERBY-2272.diff, DERBY-2272.stat, DERBY-2272.tar.gz
>
>
> Provide documentation for SSL in Derby

-- 
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.


Mime
View raw message