Documentation should give examples for using the different security mechanisms

• Key: DERBY-2361
• Type: Improvement
• Status: Resolved
• Resolution: Fixed
• Priority: Major
• Assignee: Kim Haase
• Reporter: Andrew McIntyre
• Component/s: Documentation
• Affects Version/s: 10.2.2.0
• Fix Version/s: 10.3.1.4

Description

The Derby Server and Administration guide talks about the different security mechanisms, but does not give examples of how these can be used via connection URLs, it only mentions the client DataSource field names.

http://db.apache.org/derby/docs/10.2/adminguide/cadminapps49914.html

The documentation should give examples of how to use the different security mechanisms via connection URLs, and perhaps an example of how the client field names would be used programmatically.

Comments

[Laura Stewart]

Can someone provide these examples?

[Kim Haase]

I think I might be able to figure this out; I assume the examples could be variants on the one in http://db.apache.org/derby/docs/dev/adminguide/radminnsdatasourcexmp.html, but using the ClientDataSource.setSecurityMechanism method?

I could take this on, since it involves Java examples.

[Andrew McIntyre]

The Strong Substitute Password is securityMechanism number 8, so:

jdbc:derby://localhost/mydb;user=myuser;password=mypassword;securityMechanism=8

for the encrypted username and password, the number is 9, so:

jdbc:derby://localhost/mydb;user=myuser;password=mypassword;securityMechanism=9

I believe that you can also set a default security mechanism for a server by setting the property derby.drda.securityMechanism to one of those values to ensure that clients can only connect if they are using a specific security mechanism, and that also needs documentation, see DERBY-928. That could be separated out to a separate issue if desired, though.

[Kim Haase]

Thanks, Andrew. I think I get it now -- this does not involve Java examples, but instead improving the cadminapps49914 topic to add information on setting this client attribute through the connection URL.

Are 8 and 9 the only values that are relevant? I assume the numeric equivalent of CLEAR_TEXT_PASSWORD_SECURITY doesn't need to be documented, since it's the default. What about USER_ONLY_SECURITY? Would this be automatically set if you omitted the password attribute from the connection URL?

I think the property derby.drda.securityMechanism is actually pretty well documented in http://db.apache.org/derby/docs/dev/adminguide/radmindrdasecmechanism.html. It would probably be helpful to add to cadminapps49914 a cross-reference to the radmindrdasecmechanism topic and to explain that if the securityMechanism property is set for the server, client connections are restricted to the specified mechanism.

[Andrew McIntyre]

Looking in ClientBaseDataSource, if password is not supplied, USER_ONLY_SECURITY is the default. If a password is supplied, then CLEAR_TEXT_PASSWORD is used. It appears from reading the code that the security mechanism is automatically upgraded to ENCRYPTED_USER_AND_PASSWORD on supported JVMs, at the moment that is only IBM VMs.

[Kim Haase]

Thanks for clarifying that, Andrew.

I realized I'll also need to create a new topic in the Reference Manual for the securityMechanism attribute, under "Setting attributes for the database connection URL". I think the details on the attribute, along with an example, can go there, with a cross-reference to it from cadminapps49914.

Also, on a slightly different subject, one of the topics under cadminapps49914 is "Enabling the encrypted user ID and password security mechanism". It says that in order to use this mechanism you need "IBM JCE (Java Cryptography Extension) 1.2.1 or later", but it doesn't say how to get this if you don't already have it. Should this be a separate JIRA issue?

[Andrew McIntyre]

I believe that IBM JCE 1.2.1 is only available with an IBM JDK 1.4.2 or newer, and IBM JDKs/JREs are only available as part of other IBM product downloads. I don't think Derby should necessarily be promoting IBM products, however, resourceful users will be able to find the IBM JDKs if they look hard enough for them.

[John H. Embretsen]

My 2 cents:

I would say document all possible security mechanisms (with examples), even the defaults - it won't hurt. Just mark the defaults as defaults in certain scenarios. The defaults may change in the future, and having all options documented will save us some work when that happens.

Also, I think the following page needs to be updated to also mention the STRONG_PASSWORD_SUBSTITUTE_SECURITY mechanism (but perhaps that is something for another Jira):
http://db.apache.org/derby/docs/dev/adminguide/cadminapps811631.html

[Kim Haase]

Good catch, John -- I think we missed cadminapps811631.html when fixing DERBY-1747. I think there is no harm in adding that to this issue. It is the topic that immediately follows cadminapps49914.html.

If we want to document the numeric values for the other two securityMechanism settings (USER_ONLY_SECURITY and CLEAR_TEXT_PASSWORD), then I'll need to know what they are (6 and 7?). Andrew, can you help with this?

And Andrew, thanks for the answer on IBM JCE. It's fine with me to keep that information out of the docs.

[Sunitha Kambhampati]

Numeric values for
USER_ONLY_SECURITY is 4
CLEAR_TEXT_PASSWORD_SECURITY is 3

[Kim Haase]

Thanks, Sunitha, for the information about the attribute values.

I'm attaching DERBY-2361.diff and DERBY-2361.zip, along with the new source file ref/rrefattribsecmech.dita to document the connection URL attribute. The diffs include changes to adminguide/cadminapps49914.dita and cadminapps811631.dita. Some of the cadminapps49914 changes are formatting corrections; I hope that's all right. The diffs also add the new rrefattribsecmech.dita file to the map file for the Reference Manual. I have done an svn add for this file.

Please let me know what additional changes are needed.

[John H. Embretsen]

Thank you, Kim, for working on this! I have looked through the html-output from your patch, and it looks good to me. Nevertheless, here are a couple of nits in case you want/need to submit another version:

- In rrefattribsecmech.html, user=userName and password=userPassword are links in the description of value 3, but not in the description of value 4.
- cadminapps49914.html says that you need to specify both user and password when using CLEAR_TEXT_PASSWORD_SECURITY, and user only when using USER_ONLY_SECURITY, but does not say anything about what is required when the remaining two secMecs are used. Perhaps this is obvious to most readers (or specified elsewhere in the manuals)?
- Perhaps it would be useful to link at least one of the topics to cadminappsclientsecurity.html ("Network client security")?


Finally, a general comment about documentation of security features...

This may have been discussed before, but in general, I think the security topics in the server&admin guide are quite poorly organized. For example:
  - there is the "Network client security" topic (http://db.apache.org/derby/docs/dev/adminguide/cadminappsclientsecurity.html) under "Accessing the Network Server by using the network client driver".
  - there are the "Network Server user authentication..." topics and the "Enabling the encrypted user ID and password security mechanism" topic under "Differences between running Derby in embedded mode and using the Network Server" -> "User authentication differences"
  - there is the "Network Server security" topic (http://db.apache.org/derby/docs/dev/adminguide/cadminnetservsecurity.html) under "Derby Network Server advanced topics", mentioning the host property/option only.
  - there is the "Running the Network Server under the security manager" topic in the same section as the one above.

In addition there are several topics at various places in other manuals. I'm not surprised that users are unable to find what they are looking for with respect to Derby Security.

I think there should at least be one master topic for Derby security, linking to all other sections/topics as appropriate. One idea could be to start off with a wiki page describing the different security features of Derby (authentication, authorization, Security Manager, etc.), linking to the relevant manual pages, and continue from there...

[Kim Haase]

Thanks for these great comments, John. You're right that these topics need a thorough reworking -- there's a lot of duplication. Since the primary focus of the next Derby release is security, this is a good time to do that. It probably makes sense to file a separate issue for that; I can do it. A wiki page would be helpful for now, but it's no substitute for good organization.

As for your comments on this particular issue,

- In rrefattribsecmech.html, user=userName and password=userPassword are links in the description of value 3, but not in the description of value 4.

Good point. I was applying the principle of linking only to the first occurrence of each attribute, but that makes the two descriptions inconsistent. There's another occurrence of user=userName later, too (along with all the related-topic links at the bottom). I'll think about this.

- cadminapps49914.html says that you need to specify both user and password when using CLEAR_TEXT_PASSWORD_SECURITY, and user only when using USER_ONLY_SECURITY, but does not say anything about what is required when the remaining two secMecs are used. Perhaps this is obvious to most readers (or specified elsewhere in the manuals)?

You're right, it's unclear. I think it will help if I say in the description of USER_ONLY_SECURITY that all other mechanisms require both username and password.

- Perhaps it would be useful to link at least one of the topics to cadminappsclientsecurity.html ("Network client security")?

Probably, although there's almost complete duplication between cadminapps49914 and this one (another instance of the organizational problems of the admin guide).

I'll revise the patch tomorrow. In the meantime, further suggestions are welcome. Thanks again.

[John H. Embretsen]

Kim, your comments make sense to me. I leave it to your own judgment to decide how to proceed with the nits I listed.

Regarding general cleanup of the security topics, I think there is already an issue covering client/server aspects, although the description and comments are slightly outdated at the moment: DERBY-474 ("Improve Network Server security documentation").

Also, I agree that a wiki page won't be a substitute for whatever is or should be in the manuals, but it could be a useful starting point if, for example, developers want to work on this documentation task but are reluctant to do it because of the overhead (or learning curve?) associated with working with Dita source, etc.

[Kim Haase]

Thanks very much, John.

I'm attaching a second patch, DERBY-2361-2.diff and DERBY-2361-2.zip.

I decided to include the additional xrefs in rrefattribsecmech.dita, for consistency with other topics in this group (the few that refer more than once to other attributes use the xref each time). (New file is rrefattribsecmech.dita-2.)

I added a link from cadminapps49914 to cadminappsclientsecurity, since the latter provides a little more information about how to set the property.

I'm glad to hear there is already a JIRA issue for improving the Network Server security documentation. And I think you've made a good case for a wiki page; are you thinking of providing it?

[Laura Stewart]

Is this patch ready to commit?

[Kim Haase]

Actually, I had better revise the patch to reflect the addition of the new file as well as the recent changes to the refderby.ditamap file.

svn stat src/ref
A src/ref/rrefattribsecmech.dita
M src/ref/refderby.ditamap

svn stat src/adminguide
M src/adminguide/cadminapps811631.dita
M src/adminguide/cadminapps49914.dita

It would be helpful to get feedback from John Embretsen and/or Andrew McIntyre.

[Kim Haase]

Latest patch is DERBY-2361-3.diff. Zip file does not change (DERBY-2361-2.zip).

[Laura Stewart]

Hi Kim -

I was getting ready to commit this patch, and I noticed the this title:

        Network Server user authentication when user authentication is on in Derby

It just doesn't seem solid to me with the repeat of "user authentication" and "is on in".
I know that there is another topic about "off in Derby".

Maybe "Security mechanism options when user authentication is enabled on a Derby Network Server " and "Security mechanism options when user authentication is disabled on a Derby Network Server"

I was trying to pull the content from the actual text... it's still too long for my tastes, but seems more accurate and less redundant (and easier to translate).

What do you think?

[Laura Stewart]

Also, on this file
       rrefattribsecmech.html
Is there a reason why the valid values are not in numerical order?
I am wondering if there is another way to display this besides a bulleted list. It's just that the numbers at the beginning throw me off.
I don't think a definition list is a better choice... maybe if the numbers in the beginning of the bulleted list were bold?

[Kim Haase]

Those are excellent suggestions for retitling those two topics -- thanks. I will implement them and attach a new patch if the technical folks don't disagree.

The reason the values aren't in numerical order is that the first two are the ones that users are likely to specify. The other two are there solely for completeness: ordinarily users don't specify them, because they are the defaults (depending on the user/password settings). Maybe I should create two separate lists to make this clear? I'll try that.

I agree about the problem of the numbers at the beginning and discarded the definition list probably for the same reason you do. I'll try bold and see if that helps. Thanks for the great feedback.

[Laura Stewart]

Kim - don't worry about breaking up the list, I don't think that is necessary. Sometimes it is important to have the list in the most frequently used order. Could you add a dita comment that says the reason they are not in numerical order (along with your name and date) so that in the future I don't ask the same question :-)

I used this one in a file recently:
 <!--(Laura - March 2007) The topics in this section are intentionally not listed alphabetical order. They are listed by group of information. For example, the COMPRESS and INPLACE_COMPRESS topics are listed together; the IMPORT and EXPORT topics are listed together.-->

[Kim Haase]

Thanks, Laura, that's a good suggestion. See what you think of this latest patch (DERBY-2361-4.diff, DERBY-2361-4.zip), which I hope includes all your comments. (I gave the two files matching numbers; hope that doesn't confuse anyone.)

The other changes to the security mechanisms topic included the bold font you suggested; mentioning explicitly that the values are numeric; and changing the description from "Specifies a non-default security mechanism" to just "Specifies a security mechanism", since we are including the defaults.

[Kim Haase]

Oops, and here's the stat file.

[Laura Stewart]

Looks good Kim.

Committed revision 521448.