| This page provides links to review drafts of new and changed documentation for the Security Guide as listed in the GlassFishV3.1SecurityDocPlan. Mandatory reviewers for each item are listed in each section. Changes to existing documentation since the last release are indicated. No changes are marked in new documentation. Please provide your feedback by adding a comment to this page. To simplify the processing of your comments, please add your comments in the format in the sample comment. Review existing comments to see known issues and avoid duplicates.
Changes to Books Security Guide Changes
| Section |
Documentation Impact |
Reviewers |
Administering System Security
Changed Sections:
JSR 196 Server Authentication Modules (New)
Working With the server.policy Policy File (New)
Custom Authentication of Client Certificate in SSL Mutual
Authentication (New)
Changes in Master Password (TBD) |
Moderate |
Kumar Jayanti
Tom Mueller
Bill Shannon
Martin Matula
Tim Quinn
Sonia Liu |
Administering User Security
Changed Sections:
Added PAM Realm to Overview of Authentication Realms |
Minor |
Kumar Jayanti
Tom Mueller
Bill Shannon
Martin Matula
Tim Quinn
Sonia Liu |
Administering Message Security
Changed Sections:
Administering JACC Providers (New) |
Minor |
Kumar Jayanti
Bill Shannon
Martin Matula
Tim Quinn
Sonia Liu |
| Administering Security in Cluster Mode |
New |
Kumar Jayanti
Tom Mueller
Bill Shannon
Martin Matula
Tim Quinn
Sonia Liu |
Managing Administrative Security
Added only comments from previous review |
New |
Kumar Jayanti
Tom Mueller
Bill Shannon
Martin Matula
Tim Quinn
Sonia Liu |
| Running in a Secure Environment |
New |
Kumar Jayanti
Tom Mueller
Bill Shannon
Martin Matula
Tim Quinn
Sonia Liu |
Changes to Online Help TBD Changes to Man Pages TBD
| Comment ID |
Location |
Comment |
| KM-001 |
Runtime Security Chapter |
Sample comment. Should provide a proposed fix and correct content if applicable. |
 Posted by kevinmcd at Jan 11, 2011 09:55
|
| Comment ID |
Location |
Comment |
| TJQ-001 |
p 11, just before the last line |
Insert something like: "When you install GlassFish Server or create a new domain, secure admin is disabled by default. GlassFish Server will not encrypt administrative communication among the GlassFish Server system components and will not accept administrative connections from remote hosts." |
| TJQ-002 |
p 12, 1st bullet |
Currently reads "The enable-secure-admin subcommand creates or modifies the
secure-admin element under the domain element in the domain.xml for the domain." Users won't care as much about the domain.xml change as they will the outward behavior of the system. I suggest: "The enable-secure-admin subcommand turns on secure admin. GlassFish Server will use SSL encryption to protect subsequent administrative traffic and will accept remote administrative connections." |
| TJQ-003 |
p 12, 2nd bullet |
For similar reasons, it should read "The disable-secure-admin subcommand turns off secure admin. GlassFish Server will no longer encrypt administrative messages and will no longer accept remote admin connections." |
| TJQ-004 |
p 12, 2nd bullet |
Change the last line to read "If secure admin is not enabled, this command has no effect." |
| TJQ-005 |
p 12, remove last outer bullet and its two inner bullets |
The keystore and truststore are loaded with the required keys and certs during the build and during domain creation. |
| TJQ-006 |
p 13, 4th sub-bullet under "Adjusts..." bullet |
Change "alias \$aliasName" to "the correct alias" I might have used that property-style notation in the one-pager but it's not appropriate for the doc. Also change the 2nd paragraph in that subbullet to be "The Grizzly configuration on the DAS and each instance is identical, with the exception that the DAS uses the s1as alias for SSL/TLS
authentication and the instances use the glassfish-instance alias." |
| TJQ-007 |
p 13, paragraph just before the "Which Admin Account..." section header |
Replace the paragraph (including numbered list) with "The restart also synchronizes the restarted instances. When you start the instances, the DAS delivers the updated config (in domain.xml) to the instances." The DAS will in fact deliver the keystore and truststore if needed but they will not change as a result of enable/disable-secure-admin. |
| TJQ-008 |
p 13, mid-page heading |
change heading to "Default Admin Account" The default admin account is related to but not dependent on secure admin. |
| TJQ-009 |
p 15, first sentence |
Add ", and a separate private key and self-signed certificate for remote instances." |
| TJQ-010 |
p 15, 1st bullet |
Remove this point. The keys and certs will always be in the keystore and truststore. |
| TJQ-011 |
p 15, last bullet |
Remove the second sentence starting "If the...". |
| TJQ-012 |
p 15, numbered list |
Replace numbered list and its introducing sentence with: "Here is what happens when the DAS sends an admin message to an instance:
1. When the DAS connects to the instance, SSL on the instance asks the DAS to provide an SSL/TLS certificate.
2. The DAS sends the certificate with the alias you specified using the --adminalias option when you ran the enable-secure-admin command.
3. SSL on the instance makes sure the certificate is valid and GlassFish Server makes sure that the security Principal associated with the incoming request (provided automatically by Grizzly and the SSL/TLS Java implementation) matches the Principal associated with the adminalias from the instance's truststore. |
| TJQ-013 |
p 15, 2nd paragraph under "What Certs are Used" section |
Change "instance-alias" to --instancealias and "admin-alias" to --adminalias because we're talking about the option name, not the domain.xml attribute. |
| TJQ-014 |
p 15, last sentence |
Remove this sentence ("Whether you use..."). The original design had the principals in the admin realm but we are not doing that now. |
| TJQ-015 |
p 19, last bullet ("Remote client-to-instance") |
Change first sentence from "Remote clients..." to "Remote asadmin clients..." because other types of clients - browsers using the REST interface retrieve monitoring data, for example - are allowed to connect directly to instances. The locally-provisioned password is used only by asadmin clients.
Also, remove the sentence starting "In addition" because there is in fact an admin realm on the instances. It is not used directly by secure admin but is by other parts of security. |
| TJQ-016 |
p 20, item #6 |
change "...when you create the domain." to "...when you create the domain or install GlassFish Server." |
Posted by timq at Jan 13, 2011 15:49
|
| Thanks for the detailed comments, I really appreciate them! I've made all the changes except TJQ-008. I'm not sure what you want for this one.
Posted by kevinmcd at Jan 14, 2011 13:22
|
| About TJQ-008... GlassFish uses the same approach to the default admin account whether secure admin is enabled or not. I thought that renaming the heading would remove some possible confusion, given that the original heading is "Which Admin Account is Used for Secure Admin?" Enabling secure admin allows the default admin account – and all other admin accounts – to access the DAS remotely. But it does not affect how the default admin account is handled or whether there is one.
Posted by timq at Jan 14, 2011 14:40
|
| What if I change the head to "Which Admin Account is Used"? That describes the content of the section, and removes any notion that the admin account is somehow different for secure admin.
Posted by kevinmcd at Jan 14, 2011 14:59
|
| That sounds good.
Posted by timq at Jan 14, 2011 15:14
|
| OK, I'll make that change.
Posted by kevinmcd at Jan 14, 2011 15:16
|
| Comments on "Administering Administrative Security"
| Comment ID |
Location |
Comment |
| trm-001 |
p11 |
add "administrative" to "secure all communication" in the first pp under Secure Administration Overview. Other communication such as for GMS is not secured by this feature. |
| trm-002 |
p12, last bullet |
extra "," at the end of the phrase |
| trm-003 |
general |
there are many uses of words such as "admin" and "config" that should probably be spelled out. For example, "config" in "delivers the updated config" on p13 and "admin" in the 2nd bullet on p13. |
| trm-004 |
p15 |
"When the DAS sends an admin message to an instance:" and "When the DAS connects to the instance" seem to be redundant. |
| trm-005 |
p15 |
When describing the use of keytool to look at the keystore contents, it would be good to mention how one knows what the password for the keystore is. This is the "master password" that has a default value of "changeit" unless it has been changed by the change-master-password subcommand. |
| trm-006 |
p18 |
Section "Using your own certificates" - is it really necessary to use different alias names? Or is it possible to just install your own certificates using the s1as and glassfish-instance aliases? |
| trm-007 |
p18, 2nd bullet |
"truststores" should be "truststore" |
| trm-008 |
p19, 1st bullet |
Given what "foobar" stands for, I would recommend not using these as example host names in formal documentation. |
| trm-009 |
p19, table 5-2 |
The last entry does not seem to get across the point that it is possible to setup a DAS with instances on remote servers as long as SSH is being used (with the create-instance, start-instance, start-cluster, etc. commands working), even though create-local-instance, start-local-instance on the remote host will not work. In that case, the start-instance, start-cluster, etc. commands are run on the same host as the DAS, but through the use of SSH, a hidden start-local-instance is actually run on a remote host and it works, even though running start-local-instance manually on the remote host will not work. Maybe the problem is the term "*-ssh command" since it is more than that that actually works in this situation. |
| trm-010 |
p20 |
typo "GlassFish Serverwith"
|
| trm-011 |
p20, #2 |
AFAIK, it is possible to run enable-secure-admin even if there are no instances created. |
| trm-012 |
p21 |
Under "Additional Considerations...", it is not clear what "xxx-instance-ssh" refers to.
|
Posted by trmueller at Jan 18, 2011 08:35
|
| Great comments, thanks! For trm-009 would it be clearer if I were to change "*-ssh commands" to "Commands that require SSH. For example, create-instance."?
Posted by kevinmcd at Jan 18, 2011 11:40
|
| Yes, but I would suggest phrasing it "Command that use SSH" rather than "require SSH", since it is possible to use commands such as create-instance even with SSH is not being used.
Posted by trmueller at Jan 22, 2011 12:59
|
| I'll make this change. (Which I meant to do before now!)
Posted by kevinmcd at Jan 30, 2011 18:59
|
| Comment ID |
Location |
Comment |
| TJQ-017 |
Administering System Security, p. 13, Administration Password section |
This implies there is a single administration password. In fact, the user can authenticate as an administrator using any username/password pair that is defined in the admin realm and also marked as a member of the admin group. As a result of installation (or domain creation) there is a single default admin account, so maybe this section could be clarified to refer to that? |
| TJQ-018 |
same chapter, p. 31-32, Changing the Administration Password |
Again, the header implies there is a single admin password. Also, the example confuses the --user option which authenticates the person running asadmin to the DAS with the --username option which identifies for which admin account you want to change the password. Given that the example shows multi-mode, normally the user would specify --user on the asadmin invocation and not on the subcommand. Changing the example to change-admin-password --username anonymous would be better. |
| TJQ-019 |
Cluster Security chapter, p. 11, Dynamic Reconfig section, first paragraph |
Change last sentence in the paragraph from "... the DAS and the instances make the same changes to the domain's configuration" to "... the DAS and the instances make the same changes to their respective copies of the domain's configuration." |
| TJQ-020 |
same chapter, p. 12, first bullet list |
There should be some typographical difference between "server" in the first bullet item - which is the actual text the user would enter - and the values in the other bullet items - which are placeholders for actual values. |
| TJQ-021 |
same chapter, Enabling Dynamic Reconfig section, 2nd paragraph |
Remove this paragraph. The user no longer needs to disable dynamic reconfig to perform rolling application upgrades. In fact dyn. reconfig should be left on. The new application versioning support simplifies rolling upgrade, and removing the need for disabling and then re-enabling dyn. reconfig. is one such simplification. |
| TJQ-022 |
Administering Runtime Security chapter |
Should we rename this chapter to Managing Administrative Security (or something similar) instead of referring to runtime security? As Tom and I have pointed out, enable-/disable-secure-admin affects admin security only - not other communication such as IIOP, normal web traffic, MQ, etc. |
| TJQ-023 |
same ch., p. 12, 2nd sentence |
Prefix the sentence with "In this state," or "With secure admin disabled." I know the context should imply that we're talking about the case with secure admin disabled, but this would help emphasize it. |
| TJQ-024 |
same ch., p. 14, 4th bullet |
4th sentence (starting "messages") should be capitalized. |
| TJQ-025 |
same ch., p. 20, item #2 |
It's not required to have remote instances installed to use secure admin. If any remote instances exists, they should not be running. So maybe change this item to "No remote instances are running." |
| TJQ-026 |
same ch., p. 21, in the "Example" section |
Please add the following: You can use the following command to see the current state of secure admin in a domain:
asadmin get secure-admin.enabled
secure-admin.enabled=false
Command get executed successfully. |
| TJQ-027 |
various places |
With secure admin disabled, GlassFish server rejects remote access using asadmin or IDEs. But GlassFish Server does allow remote monitoring (read-only) access via the REST interface with secure admin disabled. We should mention this in the places where we talk about what GlassFish Server allows or prohibits with secure admin disabled. This applies to each of the chapters. |
| TJQ-028 |
Cluster-mode chapter |
Possible additional topic to discuss (actually, this applies to any installation with remote instances, whether those instances are cluster members or not):
Realize that the remote instances will synchronize with the DAS. This means files will be copied over the network from the DAS to the instances. Enable secure admin so GlassFish server will transfer these files securely. |
Posted by timq at Jan 31, 2011 08:48
|
| I updated the PDF files to fix a bad-link problem.
Posted by kevinmcd at Feb 01, 2011 19:34
|
| I don't know why I don't see your latest comments here, Kevin. But anyway... I don't see a way to get to the previous version of the .pdf, so I can't compare the recent edits to the earlier version. But re: TJQ-017 (on p. 15, Administration Password section...) I realize this overall section talks about passwords and their importance. I still think it's useful to reinforce that an admin password is always paired with an admin username. So how about changing the second sentence in the Administration Password section: "As with the default admin username, the default admin password is usually set during installation but it can be changed." Re: TJQ-018 (p. 34). Changes look good. Is it obvious that the new password and the confirmation will not be echoed on the user's display, or should we indicate that in the doc somehow?
Posted by timq at Feb 03, 2011 15:30
|
| Tim, I had posted my comments for TJQ-017 and TJQ-018, but then looked again at the changes and thought I might not have done enough. So, I backed out my comment. But I forgot about email notification! I had removed the prior version because of a link problem I needed to fix. I'll keep the next versions in place.
Posted by kevinmcd at Feb 03, 2011 15:41
|
| Changes made as indicated, marked with change bars. Previous version of PDF file retained and is available from attachments page.
Posted by kevinmcd at Feb 03, 2011 19:48
|
| Comments on "Administering System Security"
| Comment ID |
Location |
Comment |
| trm-001 |
p17, 2nd pp and p29, p38 |
Replace J2SE with Java SE |
| trm-002 |
p28 |
The example runs off the right hand side of the page. |
| trm-003 |
p13 and p30 |
The statement about the master password being the most sensitive piece of data in the system is most likely not true. |
| trm-004 |
p30 |
When changing the master password, it has to be changed on all nodes as well as on the DAS. The master password on nodes is only stored once in the node, for all instances that are on that node. |
| trm-005 |
p31 |
remove the " again" from the first prompt at the top of the page. The old master password is only requested once, so there is no "again" in that prompt. |
| trm-006 |
p31 |
The set command in the middle of the page doesn't seem to make sense, i.e., I don't see why that example is there. The jms-service admin passwords is unrelated to GlassFish's admin password. |
| trm-007 |
p32 |
typo: "In This example" |
| trm-008 |
p36 |
typo: "update-password-allias" - also, I don't know why that "password.txt" argument is there. The update-password-alias command only takes one operand, the name of the alias. |
| trm-009 |
p36 |
In the create audit module intro, there isn't much information here on why one would want to create an Audit module, what interface the specified class has to implement, or where the JAR file containing that class has to go. Maybe there should be a reference here to some development guide for this. |
Comments on "Running in a Secure Environment"
| Comment ID |
Location |
Comment |
| trm-010 |
p97 |
typo: "preventDAS-to-DAS" |
| trm-011 |
p100 |
there is a reference to "3.0.1" on this page that should be 3.1 |
| trm-012 |
p103 |
first table item refers to "-password" which should be "-passwordfile" |
| trm-013 |
p104 |
typo: "Serverprovides" |
| trm-014 |
p106 |
typo: "Serverenvironment" |
Comments on "Administering Security in Cluster Mode"
| Comment ID |
Location |
Comment |
| trm-015 |
p12 |
in the list of command in the middle of the page, add "create-file-user" |
| trm-016 |
p12 |
the list-jacc-providers command doesn't actually take the --target option, it takes a target operand. |
Posted by trmueller at Feb 07, 2011 15:31
|
| Does the following text adequately/correctly address trm-006? (I updated the PDF with this text, but I suspect the ASCII will be easier to work with.) "It is also possible to use s1as and glassfish-instance as the alias names for your own certificates. A benefit of doing so is that you would not have to specify alias names with the enable-secure-admin subcommand. In addition, your own certificate identified by the s1as alias would be used in all other cases within the domain where the s1as alias is used (by default), such as in the SSL configuration of the IIOP and http-listener-2 listeners, and as the encryption.key.alias and
signature.key.alias used for provider configuration in the SOAP authentication layer for Message Security configuration. You may find the wide-reaching effect of using the s1as alias with your own certificate to be either a useful feature or an unintended consequence. Therefore, you should understand the implications of using the s1as alias before doing so. If you decide to use the s1as and glassfish-instance aliases with your own certificates, you will first need to disable secure admin (if enabled) and then change or delete the exiting s1as alias from both the keystore.jks keystore and cacerts.jks truststore for the DAS. You can use the --changealias or --delete option of keytool to accomplish this. Then, import your own certificates. When you enable secure admin, the DAS and the instances then have copies of the same keystore and truststore."
Posted by kevinmcd at Feb 08, 2011 14:35
|
| Yes.
Posted by trmueller at Feb 09, 2011 08:32
|
|
