[
https://issues.apache.org/jira/browse/DERBY-2520?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12499909
]
Dag H. Wanvik commented on DERBY-2520:
--------------------------------------
Hi Kim,
wow, thanks for the quick response! I'll get on to it tomorrow :)
Dag
Kim>
Kim> [
https://issues.apache.org/jira/browse/DERBY-2520?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12499890
]
Kim>
Kim> Kim Haase commented on DERBY-2520:
Kim> ----------------------------------
Kim>
Kim> I started working on this on Friday -- I hope there's not too much overlap
between these and what Laura finds (two eyes are probably better than one).
Kim>
Kim> adminguide/cadminappsclient.dita: Fine
Kim>
Kim>
Kim> devguide/cdevcsecureDbOwner.html (Database owner):
Kim>
Kim> This one's new, right? It's very good. Only a few nits --
Kim>
Kim> I would suggest getting rid of the Latin -- change "e.g" to "for example"
(if that is what is meant), and change "i.e." to "that is". The "cf." is in a
bit of a run-on sentence; you might want to make a separate sentence saying,
Kim>
Kim> See "SET SCHEMA statement" in <ph
conref="../conrefs.dita#pub/citref"></ph>.
Kim>
Kim> Also, in the sentence beginning "When authentication is enabled...", make
"shut down" two words, and change the "and" to "or" ("or to perform a full
upgrade").
Kim>
Kim> I would suggest changing the CAVEAT paragraph to a <note type="attention">
or <note type="important">.
Kim>
Kim>
Kim> devguide/cdevcsecure36127.html (Enabling user authentication):
Kim>
Kim> The sentence after the second note seems like another way of stating the
information in the first note. Would it be possible to combine the information
so it's all in one note?
Kim>
Kim> "If you start a Derby system without defining at least one user, and you
enable user authentication either at startup time or later, problems will
occur. When user authentication is enabled without a user being defined, the
default database owner will become "APP", and unless this is a valid user name,
you will not be able to shut down the database, encrypt or reencrypt the
database, or perform a full upgrade of it. You will need to alter shutdown
scripts accordingly."
Kim>
Kim> Something like that? And how would you alter the shutdown scripts to
recover from this?
Kim>
Kim>
Kim> devguide/tdevdvlp40464.html (Shutting down Derby or an individual
database):
Kim>
Kim> The text "database owner" occurs twice, once inside the xref and once
outside.
Kim>
Kim> In the new example, a semicolon is needed at the end of the statement.
Kim>
Kim>
Kim> devguide/cdevcsecuregrantrevokeaccess.html: Fine
Kim> devguide/tdevcsecurenewkeyoverview.html: Fine
Kim> devguide/cdevcsecure36595.html: Fine
Kim> devguide/tdevcsecureunencrypteddb.html: Fine
Kim> devguide/tdevcsecurenewextkey.html: Fine
Kim>
Kim>
Kim> devguide/tdevcsecurenewbootpw.html: Fine, though there was an existing
error in the last sentence: "new the boot password" instead of "the new boot
password" -- that it would be nice to fix.
Kim>
Kim>
Kim> devguide/rdevcsecure13713.html (User authentication example in a
single-user, embedded environment):
Kim>
Kim> The note here is a bit confusing --
Kim>
Kim> The user name "enduser" must be supplied ...
Kim>
Kim> The way to set the username and password is not quite clear here, since
it's described in another topic ("Built-in Derby users"). Also the last phrase
turns the sentence into a run-on. So I would suggest something like this:
Kim>
Kim> The user name (the value specified by the
<codeph>derby.user.<i>username</i></codeph> property) must be supplied when the
database is created, even if authentication is not yet enabled. Otherwise the
database owner will have the default name "APP" (see <xref
href="cdevcsecureDbOwner.dita#cdevcsecureDbOwner"></xref> for details).
Kim>
Kim> In the next sentence, it is not clear what "those" refers to any more,
because of the inserted note. How about this?
Kim>
Kim> The following example shows how to provide these properties in a
connection URL, although ...
Kim>
Kim>
Kim> devguide/rdevdvlp22102.html: Fine
Kim>
Kim>
Kim> ref/rrefattrib15290.html (dataEncryption=true attribute):
Kim>
Kim> I am not quite sure what the phrase "cf. the property
derby.connection.requireAuthentication" means here. Usually "cf." (confere)
means "refer to" or "see", but there's no xref to another topic. I see that
because the description is in another book you can't create an xref. So you
need to do something like
Kim>
Kim> For an existing, unencrypted database for which authentication is enabled,
only the <xref href="rrefattrib26867.dita#rrefattrib26867">database
owner</xref> can perform encryption. See "Enabling user authentication" in the
<ph conref="../conrefs.dita#pub/citdevelop"></ph> for more information.
Kim>
Kim> Similar suggestions -- with appropriate variations in wording -- for
Kim>
Kim> ref/rrefattrib88843.html (encryptionProvider=providerName attribute)
Kim> ref/rrefattrib42100.html (bootPassword=key attribute)
Kim> ref/rrefattribencryptkey.html (encryptionKey=key attribute)
Kim> ref/rrefattribnewencryptkey.html (newEncryptionKey=key attribute)
Kim> ref/rrefattribnewbootpw.html (newBootPassword=newPassword attribute)
Kim> ref/rrefattrib60346.html (encryptionAlgorithm=algorithm attribute)
Kim> ref/rrefattrib16471.html (shutdown=true attribute)
Kim>
Kim>
Kim> ref/rrefattrib26867.html (create=true attribute):
Kim>
Kim> Same suggestion as above, for that sentence. I would also suggest
rephrasing the other two "cf." phrases. So the whole paragraph would look
something like this:
Kim>
Kim> When the database is created, the current authorization identifier becomes
the database owner (see the <i><xref
href="rrefattrib10035.dita#rrefattrib10035"></xref></i>). If authentication is
enabled (see "Enabling user authentication" in the <ph
conref="../conrefs.dita#pub/citdevelop"></ph>), only the database owner can
<xref href="rrefattrib16471.dita#rrefattrib16471">shut down</xref> the
database, <xref href="rrefattrib15290.dita#rrefattrib15290">encrypt</xref> it,
reencrypt it with a new <xref
href="rrefattribnewbootpw.dita#rrefattribnewbootpw">boot password</xref> or new
<xref href="rrefattribnewencryptkey.dita#rrefattribnewencryptkey">encryption
key</xref>, or perform a full upgrade. If authentication is not enabled, and no
user is supplied, the database owner defaults to "APP", which is also the name
of the default schema (see <xref
href="rrefsqlj32268.dita#rrefsqlj32268"></xref>).
Kim>
Kim>
Kim> ref/rrefsqlj24513.html: Fine
Kim> ref/rrefsqljrevoke.html: Fine
Kim> ref/rrefsqljrenametablestatement.html: Fine
Kim> ref/rrefsqlj15446.html: Fine
Kim> ref/rrefcreateprocedurestatement.html: Fine
Kim> ref/rrefsqlj40506.html: Fine
Kim> ref/rrefcreatefunctionstatement.html: Fine
Kim> ref/rrefexcept71493.html: Fine
Kim> ref/rrefsqlj43125.html: Fine
Kim>
Kim> > Document new restrictions of database shutdown, encryption and hard
upgrade powers
Kim> >
----------------------------------------------------------------------------------
Kim> >
Kim> > Key: DERBY-2520
Kim> > URL: https://issues.apache.org/jira/browse/DERBY-2520
Kim> > Project: Derby
Kim> > Issue Type: Improvement
Kim> > Components: Documentation
Kim> > Reporter: Dag H. Wanvik
Kim> > Assignee: Dag H. Wanvik
Kim> > Fix For: 10.3.0.0
Kim> >
Kim> > Attachments: DERBY-2520.diff, DERBY-2520.stat,
DERBY-2520.tar.gz, DERBY-2520.zip
Kim> >
Kim> >
Kim> > Add documentation for the new functionality introduced with DERBY-2264.
Kim>
Kim> --
Kim> This message is automatically generated by JIRA.
Kim> -
Kim> You can reply to this email to add a comment to the issue online.
Kim>
--
Dag H. Wanvik
Sun Microsystems, Database Technology Group (DBTG)
Haakon VII gt. 7b, N-7485 Trondheim, Norway
Tel: x43496/+47 73842196, Fax: +47 73842101
> Document new restrictions of database shutdown, encryption and hard upgrade
> powers
> ----------------------------------------------------------------------------------
>
> Key: DERBY-2520
> URL: https://issues.apache.org/jira/browse/DERBY-2520
> Project: Derby
> Issue Type: Improvement
> Components: Documentation
> Reporter: Dag H. Wanvik
> Assignee: Dag H. Wanvik
> Fix For: 10.3.0.0
>
> Attachments: DERBY-2520.diff, DERBY-2520.stat, DERBY-2520.tar.gz,
> DERBY-2520.zip
>
>
> Add documentation for the new functionality introduced with DERBY-2264.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
