[
https://issues.apache.org/jira/browse/DERBY-2520?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#action_12499890
]
Kim Haase commented on DERBY-2520:
----------------------------------
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).
adminguide/cadminappsclient.dita: Fine
devguide/cdevcsecureDbOwner.html (Database owner):
This one's new, right? It's very good. Only a few nits --
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,
See "SET SCHEMA statement" in <ph conref="../conrefs.dita#pub/citref"></ph>.
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").
I would suggest changing the CAVEAT paragraph to a <note type="attention"> or
<note type="important">.
devguide/cdevcsecure36127.html (Enabling user authentication):
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?
"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."
Something like that? And how would you alter the shutdown scripts to recover
from this?
devguide/tdevdvlp40464.html (Shutting down Derby or an individual database):
The text "database owner" occurs twice, once inside the xref and once outside.
In the new example, a semicolon is needed at the end of the statement.
devguide/cdevcsecuregrantrevokeaccess.html: Fine
devguide/tdevcsecurenewkeyoverview.html: Fine
devguide/cdevcsecure36595.html: Fine
devguide/tdevcsecureunencrypteddb.html: Fine
devguide/tdevcsecurenewextkey.html: Fine
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.
devguide/rdevcsecure13713.html (User authentication example in a single-user,
embedded environment):
The note here is a bit confusing --
The user name "enduser" must be supplied ...
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:
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).
In the next sentence, it is not clear what "those" refers to any more, because
of the inserted note. How about this?
The following example shows how to provide these properties in a connection
URL, although ...
devguide/rdevdvlp22102.html: Fine
ref/rrefattrib15290.html (dataEncryption=true attribute):
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
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.
Similar suggestions -- with appropriate variations in wording -- for
ref/rrefattrib88843.html (encryptionProvider=providerName attribute)
ref/rrefattrib42100.html (bootPassword=key attribute)
ref/rrefattribencryptkey.html (encryptionKey=key attribute)
ref/rrefattribnewencryptkey.html (newEncryptionKey=key attribute)
ref/rrefattribnewbootpw.html (newBootPassword=newPassword attribute)
ref/rrefattrib60346.html (encryptionAlgorithm=algorithm attribute)
ref/rrefattrib16471.html (shutdown=true attribute)
ref/rrefattrib26867.html (create=true attribute):
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:
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>).
ref/rrefsqlj24513.html: Fine
ref/rrefsqljrevoke.html: Fine
ref/rrefsqljrenametablestatement.html: Fine
ref/rrefsqlj15446.html: Fine
ref/rrefcreateprocedurestatement.html: Fine
ref/rrefsqlj40506.html: Fine
ref/rrefcreatefunctionstatement.html: Fine
ref/rrefexcept71493.html: Fine
ref/rrefsqlj43125.html: Fine
> 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.
