Details

    • Type: Sub-task Sub-task
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 10.3.1.4
    • Component/s: Documentation
    • Labels:
      None

      Description

      Provide documentation for SSL in Derby

      1. DERBY-2272.diff
        23 kB
        Bernt M. Johnsen
      2. DERBY-2272.stat
        0.4 kB
        Bernt M. Johnsen
      3. DERBY-2272.tar.gz
        6 kB
        Bernt M. Johnsen
      4. DERBY-2272-v2.diff
        23 kB
        Bernt M. Johnsen
      5. DERBY-2272-v2.stat
        0.4 kB
        Bernt M. Johnsen
      6. DERBY-2272-v2.zip
        16 kB
        Bernt M. Johnsen
      7. DERBY-2272-v2.diff
        23 kB
        Bernt M. Johnsen
      8. DERBY-2272-v2.stat
        0.4 kB
        Bernt M. Johnsen
      9. DERBY-2272-v2.zip
        16 kB
        Bernt M. Johnsen
      10. DERBY-2272-glitch.diff
        2 kB
        Bernt M. Johnsen
      11. DERBY-2272-glitch.stat
        0.2 kB
        Bernt M. Johnsen
      12. DERBY-2272-glitch.zip
        7 kB
        Bernt M. Johnsen
      13. DERBY-2272-ns-javadoc.diff
        4 kB
        Bernt M. Johnsen
      14. NetworkServerControl.html
        34 kB
        John H. Embretsen
      15. DERBY-2272-ns-javadoc-v2.diff
        4 kB
        Bernt M. Johnsen

        Activity

        Bernt M. Johnsen created issue -
        Bernt M. Johnsen made changes -
        Field Original Value New Value
        Assignee Bernt M. Johnsen [ bernt ]
        Bernt M. Johnsen made changes -
        Fix Version/s 10.3.0.0 [ 12310800 ]
        Hide
        Bernt M. Johnsen added a comment -

        tar fail contains html of changed files

        Show
        Bernt M. Johnsen added a comment - tar fail contains html of changed files
        Bernt M. Johnsen made changes -
        Attachment DERBY-2272.stat [ 12358238 ]
        Attachment DERBY-2272.diff [ 12358237 ]
        Attachment DERBY-2272.tar.gz [ 12358239 ]
        Bernt M. Johnsen made changes -
        Derby Info [Patch Available]
        Hide
        Kim Haase added a comment -

        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:

        Show
        Kim Haase added a comment - 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:
        Hide
        Bernt M. Johnsen added a comment -

        Thanks Kim for your comments! New version (V2) of the patch uploaded. HTML of changed files in the ZIP-file.

        Show
        Bernt M. Johnsen added a comment - Thanks Kim for your comments! New version (V2) of the patch uploaded. HTML of changed files in the ZIP-file.
        Bernt M. Johnsen made changes -
        Attachment DERBY-2272-v2.diff [ 12358433 ]
        Attachment DERBY-2272-v2.zip [ 12358435 ]
        Attachment DERBY-2272-v2.stat [ 12358434 ]
        Hide
        Bernt M. Johnsen added a comment -

        Forgot to check "Grant license"... sigh... done now.

        Show
        Bernt M. Johnsen added a comment - Forgot to check "Grant license"... sigh... done now.
        Bernt M. Johnsen made changes -
        Attachment DERBY-2272-v2.diff [ 12358436 ]
        Attachment DERBY-2272-v2.zip [ 12358438 ]
        Attachment DERBY-2272-v2.stat [ 12358437 ]
        Hide
        Bernt M. Johnsen added a comment -

        Committed revision 542796.

        Show
        Bernt M. Johnsen added a comment - Committed revision 542796.
        Bernt M. Johnsen made changes -
        Status Open [ 1 ] Resolved [ 5 ]
        Derby Info [Patch Available]
        Resolution Fixed [ 1 ]
        Hide
        Kim Haase added a comment -

        I'm really sorry I wasn't able to get to this yesterday. Most of the corrections are fine but there are still a few little glitches, some more serious than others. In approximate order of importance:

        cadminsslkeys.html (Key and certificate handling):

        The two subsections now both have the same title, "Install server certificate on the client (optional)". But I think the second one is supposed to be something like "Install client certificate on the server (optional)"?

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

        In the first sentence, "indicates" is misspelled.

        rrefattribssl.html (ssl=sslMode attribute):

        The sentence introducing the example is missing a "to" and a colon – it should be something like

        Connecting to mydb with basic SSL encryption:

        cadminssladmin.html (Other server commands):

        There's a colon missing at the end of "use the following command".

        Show
        Kim Haase added a comment - I'm really sorry I wasn't able to get to this yesterday. Most of the corrections are fine but there are still a few little glitches, some more serious than others. In approximate order of importance: cadminsslkeys.html (Key and certificate handling): The two subsections now both have the same title, "Install server certificate on the client (optional)". But I think the second one is supposed to be something like "Install client certificate on the server (optional)"? radmindrdasslmode.html (derby.drda.sslMode property): In the first sentence, "indicates" is misspelled. rrefattribssl.html (ssl=sslMode attribute): The sentence introducing the example is missing a "to" and a colon – it should be something like Connecting to mydb with basic SSL encryption: cadminssladmin.html (Other server commands): There's a colon missing at the end of "use the following command".
        Hide
        Bernt M. Johnsen added a comment -

        Has to fix some glitches.

        Show
        Bernt M. Johnsen added a comment - Has to fix some glitches.
        Bernt M. Johnsen made changes -
        Status Resolved [ 5 ] Reopened [ 4 ]
        Resolution Fixed [ 1 ]
        Hide
        Bernt M. Johnsen added a comment -

        Thanks Kim for catching these. It should be correct now (I think I was more throrough this time .

        Show
        Bernt M. Johnsen added a comment - Thanks Kim for catching these. It should be correct now (I think I was more throrough this time .
        Bernt M. Johnsen made changes -
        Attachment DERBY-2272-glitch.stat [ 12358600 ]
        Attachment DERBY-2272-glitch.zip [ 12358601 ]
        Attachment DERBY-2272-glitch.diff [ 12358599 ]
        Bernt M. Johnsen made changes -
        Derby Info [Patch Available]
        Hide
        Kim Haase added a comment -

        Thanks, Bernt! They look great now. +1 to commit.

        Show
        Kim Haase added a comment - Thanks, Bernt! They look great now. +1 to commit.
        Hide
        Bernt M. Johnsen added a comment -

        Committed revision 543144.

        Show
        Bernt M. Johnsen added a comment - Committed revision 543144.
        Bernt M. Johnsen made changes -
        Resolution Fixed [ 1 ]
        Status Reopened [ 4 ] Resolved [ 5 ]
        Derby Info [Patch Available]
        Hide
        John H. Embretsen added a comment -

        Shouldn't the new derby.drda.sslMode property also be documented in the class JavaDocs for org.apache.derby.drda.NetworkServerControl, where other server properties, arguments and options are listed? And the -ssl option be added to the description for the various server commands in the same place? (Sorry for not noticing earlier).

        See for example http://db.apache.org/derby/javadoc/publishedapi/jdbc4/org/apache/derby/drda/NetworkServerControl.html

        Show
        John H. Embretsen added a comment - Shouldn't the new derby.drda.sslMode property also be documented in the class JavaDocs for org.apache.derby.drda.NetworkServerControl, where other server properties, arguments and options are listed? And the -ssl option be added to the description for the various server commands in the same place? (Sorry for not noticing earlier). See for example http://db.apache.org/derby/javadoc/publishedapi/jdbc4/org/apache/derby/drda/NetworkServerControl.html
        Hide
        Bernt M. Johnsen added a comment -

        Thanks John! Attached javadoc fix for NetworkServerControl.

        Show
        Bernt M. Johnsen added a comment - Thanks John! Attached javadoc fix for NetworkServerControl.
        Bernt M. Johnsen made changes -
        Attachment DERBY-2272-ns-javadoc.diff [ 12359503 ]
        Hide
        John H. Embretsen added a comment -

        Looks good, except that you forgot to include the ssl option with the logconnections command.

        Attaching NetworkServerControl JavaDoc (NetworkServerControl.html) based on the latest patch in case others want to review as well.

        Show
        John H. Embretsen added a comment - Looks good, except that you forgot to include the ssl option with the logconnections command. Attaching NetworkServerControl JavaDoc (NetworkServerControl.html) based on the latest patch in case others want to review as well.
        John H. Embretsen made changes -
        Attachment NetworkServerControl.html [ 12359518 ]
        Hide
        Bernt M. Johnsen added a comment -

        Fix network server javadoc too!

        Show
        Bernt M. Johnsen added a comment - Fix network server javadoc too!
        Bernt M. Johnsen made changes -
        Status Resolved [ 5 ] Reopened [ 4 ]
        Resolution Fixed [ 1 ]
        Hide
        Bernt M. Johnsen added a comment -

        Thanks John. Now patch DERBY-2272-ns-javadoc-v2.diff attatched.

        Show
        Bernt M. Johnsen added a comment - Thanks John. Now patch DERBY-2272 -ns-javadoc-v2.diff attatched.
        Bernt M. Johnsen made changes -
        Attachment DERBY-2272-ns-javadoc-v2.diff [ 12359574 ]
        Hide
        Bernt M. Johnsen added a comment -

        Committed revision 546771.
        Added ssl to NetworkServerControl Javadoc.

        Show
        Bernt M. Johnsen added a comment - Committed revision 546771. Added ssl to NetworkServerControl Javadoc.
        Bernt M. Johnsen made changes -
        Resolution Fixed [ 1 ]
        Status Reopened [ 4 ] Resolved [ 5 ]
        Hide
        John H. Embretsen added a comment -

        Thanks, Javadoc looks up to date now.

        Show
        John H. Embretsen added a comment - Thanks, Javadoc looks up to date now.
        Bernt M. Johnsen made changes -
        Status Resolved [ 5 ] Closed [ 6 ]
        Gavin made changes -
        Workflow jira [ 12395110 ] Default workflow, editable Closed status [ 12798467 ]

          People

          • Assignee:
            Bernt M. Johnsen
            Reporter:
            Bernt M. Johnsen
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development