Derby
  1. Derby
  2. DERBY-2109 System privileges
  3. DERBY-3585

Document user authentication support for network server shutdown

    Details

    • Type: Sub-task Sub-task
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 10.4.1.3
    • Component/s: Documentation
    • Labels:
      None
    • Issue & fix info:
      Patch Available, Release Note Needed

      Description

      As part of the System Privileges work in DERBY-2109, the support of user authentication for network server shutdown was discussed, implemented, and committed (revision 632502).

      In order to address a security issue (missing user authentication for shutdown), this feature introduces a few incompatibilities with the usage of NetworkServerControl, which need to be documented.

      This JIRA is to provide for the user documentation and the release notes describing the usage changes and incompatibilities.

      1. releaseNote.html
        7 kB
        Martin Zaun
      2. releaseNote.html
        7 kB
        Martin Zaun
      3. releaseNote.html
        8 kB
        Martin Zaun
      4. releaseNote.html
        8 kB
        Rick Hillegas
      5. DERBY-3585-0.stat
        0.3 kB
        Martin Zaun
      6. DERBY-3585-0.diff
        13 kB
        Martin Zaun
      7. DERBY-3585-0.zip
        193 kB
        Martin Zaun

        Activity

        Hide
        Kim Haase added a comment -

        I just wanted to add that you did a terrific job with the DITA, Martin, considering how hard it is to work with (as you say). The documentation changes are really excellent.

        The codeblock lines could be shortened, but since they wrap in the PDF and are fully visible, this is not urgent.

        Were you thinking of filing a JIRA issue on the error in devguide/tdevdvlp20349.dita about garbage collection? That should be corrected.

        Show
        Kim Haase added a comment - I just wanted to add that you did a terrific job with the DITA, Martin, considering how hard it is to work with (as you say). The documentation changes are really excellent. The codeblock lines could be shortened, but since they wrap in the PDF and are fully visible, this is not urgent. Were you thinking of filing a JIRA issue on the error in devguide/tdevdvlp20349.dita about garbage collection? That should be corrected.
        Hide
        Rick Hillegas added a comment -

        Closing this issue. This will hopefully make the attached release note appear in the 10.4 release notes.

        Show
        Rick Hillegas added a comment - Closing this issue. This will hopefully make the attached release note appear in the 10.4 release notes.
        Hide
        Rick Hillegas added a comment -

        Port 644555 from trunk docs to 10.4 docs branch.

        Show
        Rick Hillegas added a comment - Port 644555 from trunk docs to 10.4 docs branch.
        Hide
        Rick Hillegas added a comment -

        Thanks, Martin. I made some minor wording changes and committed the Admin Guide patch at subversion revision 644555.

        Show
        Rick Hillegas added a comment - Thanks, Martin. I made some minor wording changes and committed the Admin Guide patch at subversion revision 644555.
        Hide
        Martin Zaun added a comment -

        Admin Guide patch available for review/comments/edits.

        Show
        Martin Zaun added a comment - Admin Guide patch available for review/comments/edits.
        Hide
        Martin Zaun added a comment -

        Please find attached for review and comments the documentation update
        (dita diffs and html) for the network server shutdown authentication.

        Having looked into the documentation source for the first time, the
        formatting, the usage of the dita-tags in the individual sections, and
        the applied level of detail appeared at times somewhat incoherent to me
        (in the admin guide, for instance, comparing the network server start with
        the shutdown section).

        I tried to fit my additions into the existing structure, language, and
        formatting, but most certainly there's plenty of chance for improvement by
        a native speaker and a dita expert. For instance, I'm not sure if the
        codeblock lines have gotten too long with the newly appended "... [-user
        username] [-password password]" options.

        Summary of changes:

        1) adminguide/tadminconfigshuttingdownthenetworkserver.dita

        • removed obsolete statements that user must explicitely shut down open
          databases before shutting down the server when user authentication is
          enabled
          + added that server can be shutdown by invoking script, jar, or class
          + added new user/password command-line options

        2) adminguide/tadminconfig815333.dita
        + added jar file invokation usage for server shutdown
        + added username/password command-line options

        3) tadminconfig815357.dita
        + added username/password constructor arguments

        4) adminguide/derbyadmin.ditamap
        adminguide/tadminnetservusrauth.dita
        + added a new section/toc entry "Running the Network Server with User
        Authentication" under "Derby Network Server advanced topics"; this
        adds a cross-reference to "Working with user authentication" in the
        Derby Developer's Guide, which I strongly felt missing. Without this
        section (or task?), there's only scattered information in the admin
        guide on how to enable user authentication. For instance, there's a
        note burried in "Basic Network Server security policy"; however,
        enabling user authentication is independent from running with a
        security manager. Also, having "user authentication" show up under
        the generated links "Related concepts/tasks" might be very helpful
        (even if the user will only find a cross-reference to the devguide
        there).

        5) adminguide/tadminconfig813694.dita
        + added new constructors with user/password arguments

        6) adminguide/radminappsclientxmp.dita
        + added cross-reference to devguide's section on "user authentication"
        neccessary to understand the examples and context

        7) adminguide/tadminconfig814963.dita

        • decided not to add new constructor examples here, since they're
          described in their own section

        8) adminguide/cadminssl.dita

        • decided not to address any potential confusion about Derby's user
          authentication and authentication with SSL/TLS, which are separate;
          we've already identified this as a topic for future refinement and
          changes (single login with certificate-based identity).

        9) devguide/cdevcsecure36127.dita

        • ok, no changes needed

        10) devguide/tdevdvlp20349.dita

        • found a flatly wrong statement but did NOT correct here since
          unrelated to server shutdown authentication:
          "You cannot explicitly request that the JVM unload a class, but you
          can ensure that the EmbeddedDriver class is unloaded by using a
          System.gc() to force it to garbage collect classes that are no longer
          needed. Running with -nogc or -noclassgc definitely prevents the class
          from being unloaded and makes you unable to restart Derby in the same
          JVM."

        System.gc() is only a suggestion to the Runtime to garbage-collect, it
        cannot be enforced, and there's no guarantee whatsoever that GC has
        run and any classes been unloaded. Likewise it's most probably not
        guarantueed that -nogc or -noclassgc definitely prevent a class
        from being unloaded (a JVM may ignore these options...)

        11) refderby, getstartderby, tuningderby, derbytools

        • ok, no changes needed
        Show
        Martin Zaun added a comment - Please find attached for review and comments the documentation update (dita diffs and html) for the network server shutdown authentication. Having looked into the documentation source for the first time, the formatting, the usage of the dita-tags in the individual sections, and the applied level of detail appeared at times somewhat incoherent to me (in the admin guide, for instance, comparing the network server start with the shutdown section). I tried to fit my additions into the existing structure, language, and formatting, but most certainly there's plenty of chance for improvement by a native speaker and a dita expert. For instance, I'm not sure if the codeblock lines have gotten too long with the newly appended "... [-user username] [-password password] " options. Summary of changes: 1) adminguide/tadminconfigshuttingdownthenetworkserver.dita removed obsolete statements that user must explicitely shut down open databases before shutting down the server when user authentication is enabled + added that server can be shutdown by invoking script, jar, or class + added new user/password command-line options 2) adminguide/tadminconfig815333.dita + added jar file invokation usage for server shutdown + added username/password command-line options 3) tadminconfig815357.dita + added username/password constructor arguments 4) adminguide/derbyadmin.ditamap adminguide/tadminnetservusrauth.dita + added a new section/toc entry "Running the Network Server with User Authentication" under "Derby Network Server advanced topics"; this adds a cross-reference to "Working with user authentication" in the Derby Developer's Guide, which I strongly felt missing. Without this section (or task?), there's only scattered information in the admin guide on how to enable user authentication. For instance, there's a note burried in "Basic Network Server security policy"; however, enabling user authentication is independent from running with a security manager. Also, having "user authentication" show up under the generated links "Related concepts/tasks" might be very helpful (even if the user will only find a cross-reference to the devguide there). 5) adminguide/tadminconfig813694.dita + added new constructors with user/password arguments 6) adminguide/radminappsclientxmp.dita + added cross-reference to devguide's section on "user authentication" neccessary to understand the examples and context 7) adminguide/tadminconfig814963.dita decided not to add new constructor examples here, since they're described in their own section 8) adminguide/cadminssl.dita decided not to address any potential confusion about Derby's user authentication and authentication with SSL/TLS, which are separate; we've already identified this as a topic for future refinement and changes (single login with certificate-based identity). 9) devguide/cdevcsecure36127.dita ok, no changes needed 10) devguide/tdevdvlp20349.dita found a flatly wrong statement but did NOT correct here since unrelated to server shutdown authentication: "You cannot explicitly request that the JVM unload a class, but you can ensure that the EmbeddedDriver class is unloaded by using a System.gc() to force it to garbage collect classes that are no longer needed. Running with -nogc or -noclassgc definitely prevents the class from being unloaded and makes you unable to restart Derby in the same JVM." System.gc() is only a suggestion to the Runtime to garbage-collect, it cannot be enforced, and there's no guarantee whatsoever that GC has run and any classes been unloaded. Likewise it's most probably not guarantueed that -nogc or -noclassgc definitely prevent a class from being unloaded (a JVM may ignore these options...) 11) refderby, getstartderby, tuningderby, derbytools ok, no changes needed
        Hide
        Rick Hillegas added a comment -

        Thanks for the release note, Martin. I have made a couple small edits to clarify it a bit more.

        Show
        Rick Hillegas added a comment - Thanks for the release note, Martin. I have made a couple small edits to clarify it a bit more.
        Hide
        Martin Zaun added a comment -

        Attached a new Release Note version with added clarifications:

        • "Any client could shut down the server by calling NetworkServerControl with a shutdown command-line argument or by invoking the shutdown() method (provided the shutdown was initiated on the host running the server)."
        • "Note that additionally checking for a user's shutdown authorization has not been provided yet."
        • "The previous behavior represented a security issue, because any client could shut down a
          network server running with user authentication from the same host without needing to provide user credentials."

        Hope this makes it clearer. Further comments welcome (especially from native speakers).

        Show
        Martin Zaun added a comment - Attached a new Release Note version with added clarifications: "Any client could shut down the server by calling NetworkServerControl with a shutdown command-line argument or by invoking the shutdown() method (provided the shutdown was initiated on the host running the server)." "Note that additionally checking for a user's shutdown authorization has not been provided yet." "The previous behavior represented a security issue, because any client could shut down a network server running with user authentication from the same host without needing to provide user credentials." Hope this makes it clearer. Further comments welcome (especially from native speakers).
        Hide
        John H. Embretsen added a comment -

        I'm wondering if the release note's description of the previous state may lead to impressions that the security issue was more severe than it actually was. Specifically, the release note says:

        "Any user could shut down the server..."

        and

        "The previous behavior represented a security issue, because any client, without providing user credentials, could shut down a network server running with user authentication."

        Should we mention the fact that only local users/clients (users/clients on the same host as the host running the server) could shut down the server? (Which as far as I know is still true).

        Show
        John H. Embretsen added a comment - I'm wondering if the release note's description of the previous state may lead to impressions that the security issue was more severe than it actually was. Specifically, the release note says: "Any user could shut down the server..." and "The previous behavior represented a security issue, because any client, without providing user credentials, could shut down a network server running with user authentication." Should we mention the fact that only local users/clients (users/clients on the same host as the host running the server) could shut down the server? (Which as far as I know is still true).
        Hide
        Martin Zaun added a comment -

        > I found with some experimenting that it also worked to use the user/password constructor for start. e.g.
        >
        > NetworkServerControl nscauth = new NetworkServerControl(user, password);
        > nscauth.start();
        > ...
        > nscauth.shutdown();
        >
        > Is that an acceptable workaround?

        Definitely, and I meant this to be covered by list item #2. But since this is a major use case, I made it explicit and updated the releaseNote.html.

        Hope this makes it clearer.

        > Are there plans for the future to add authentication checks to start?

        That makes sense to me, though it would introduce a few more (minor) usage incompatibilities.

        In any case we should address the asymmetry of requiring user credentials to shutdown a server but not to start one.

        While we could relax the credentials requirement for shutdown, it appears easiest to me to have but one rule: when running with user authentication, users need to provide credentials to be able to do any server administration action.

        Note that there is another post 10.4 brainstorming item of how to reconcile certificate-based authentication scheme (JMX) with user/password requirements (dual or single logins).

        Show
        Martin Zaun added a comment - > I found with some experimenting that it also worked to use the user/password constructor for start. e.g. > > NetworkServerControl nscauth = new NetworkServerControl(user, password); > nscauth.start(); > ... > nscauth.shutdown(); > > Is that an acceptable workaround? Definitely, and I meant this to be covered by list item #2. But since this is a major use case, I made it explicit and updated the releaseNote.html. Hope this makes it clearer. > Are there plans for the future to add authentication checks to start? That makes sense to me, though it would introduce a few more (minor) usage incompatibilities. In any case we should address the asymmetry of requiring user credentials to shutdown a server but not to start one. While we could relax the credentials requirement for shutdown, it appears easiest to me to have but one rule: when running with user authentication, users need to provide credentials to be able to do any server administration action. Note that there is another post 10.4 brainstorming item of how to reconcile certificate-based authentication scheme (JMX) with user/password requirements (dual or single logins).
        Hide
        Kathey Marsden added a comment -

        Thanks Martin for the release note. I have a question on the edge case:
        Note that there is an edge case

        NetworkServerControl nsc = new NetworkServerControl();
        nsc.start(console);
        ...
        nsc.shutdown();

        which currently fails with above's SQLException.

        An quick workaround, however, is to create another NetworkServerControl instance with user credential arguments:

        NetworkServerControl nsc = new NetworkServerControl();
        nsc.start(console);
        ...
        NetworkServerControl nscauth = new NetworkServerControl(user, password);
        nscauth.shutdown();

        I found with some experimenting that it also worked to use the user/password constructor for start. e.g.

        NetworkServerControl nscauth = new NetworkServerControl(user, password);
        nscauth.start();
        ...
        nscauth.shutdown();

        Is that an acceptable workaround? Are there plans for the future to add authentication checks to start?

        Show
        Kathey Marsden added a comment - Thanks Martin for the release note. I have a question on the edge case: Note that there is an edge case NetworkServerControl nsc = new NetworkServerControl(); nsc.start(console); ... nsc.shutdown(); which currently fails with above's SQLException. An quick workaround, however, is to create another NetworkServerControl instance with user credential arguments: NetworkServerControl nsc = new NetworkServerControl(); nsc.start(console); ... NetworkServerControl nscauth = new NetworkServerControl(user, password); nscauth.shutdown(); I found with some experimenting that it also worked to use the user/password constructor for start. e.g. NetworkServerControl nscauth = new NetworkServerControl(user, password); nscauth.start(); ... nscauth.shutdown(); Is that an acceptable workaround? Are there plans for the future to add authentication checks to start?
        Hide
        Martin Zaun added a comment -

        Attached is the releaseNote.html describing the usage changes and incompatibilities with networ server shutdown authentication. The file passes the release note generator.

        A bundle with the documentation updates will follow shortly.

        Show
        Martin Zaun added a comment - Attached is the releaseNote.html describing the usage changes and incompatibilities with networ server shutdown authentication. The file passes the release note generator. A bundle with the documentation updates will follow shortly.

          People

          • Assignee:
            Martin Zaun
            Reporter:
            Martin Zaun
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development