Caroline's notes on OPC Clause 12 (Digital Signatures)

[caroline arms]

All,

Clause 12 has been exhausting to go through.  But this is what I have.

Many of my concerns relate to text from the original version.  I have NOT
been through the substantial deleted section on Modifications to the XML
Digital Signature Specification to see if equivalent text has been included
somewhere in the latest draft.

    Have fun in Prague.  Talk to you on Tuesday morning.

    Caroline

======================

General concerns.

We currently use the 2002 version of the W3C spec.  I had been checking
clause references in that document (assuming we needed to use the old spec
for some reason — but when I got to the DigestMethod element, I wondered
whether that assumption was incorrect.  The latest W3C spec is always at
https://www.w3.org/TR/xmldsig-core/
Currently that gets to a 2013 version
https://www.w3.org/TR/2013/REC-xmldsig-core1-20130411/
See notes on 12.4.9 below.

Clause 4 does not define "package" as conforming to the OPC specification.
However, I think Clause 12 does use the term to apply to OPC packages.  I
was particularly confused as to the meaning of "package-specific."  When I
read "package-specific" I could interpret it as being specific to a
particular package instance.  I think what is meant amounts to
OPC-specific.  I'm wondering if we can use that term (or something
equivalent) in this clause.  I have not suggested a change — but I find the
use of "package-specific" confusing in MANY cases.

"Relationships transform" is introduced and used again in 12.4.8 without
clearly indicating where it is defined/explained. I did not understand the
explanation — why is it needed.  What problem does it address?
[Eventually I figured it out, but only with difficulty.]

When I got to the example in 12.5, I realized that I didn't understand how
the elements relate to each other and the links to the W3C spec didn't
help.  In particular, I hadn't grasped that the Reference element not only
defined what was being signed, but included the digest value that is the
guts of the digital signature.  Of course, the schema definition in the W3C
spec lists DigestValue, but that subclause does a poor job of relating the
Reference element to the Signature process.  You have to read 2.1 in the
W3C spec to understand that:
 "Each Reference element includes the digest method and resulting digest
value calculated over the identified data object. It also may include
transformations that produced the input to the digest operation. A data
object is signed by computing its digest value and a signature over that
value. "

Could we include an equivalent statement either near the beginning of 12.4
or in 12.4.6?

12.1   General

In first sentence: It isn't the signatures "which identify …" but the
associated markup.

I think we should mention the date for the W3C spec here (not just in the
Normative References clause) because there are more recent versions.  We
currently have https://www.w3.org/TR/2002/REC-xmldsig-core-20020212/ in
Normative references.

=== Suggested rewording.

A derived format might allow a package to include digital signatures and
markup that identifies the parts of a package that have been signed and the
process for validating the signatures. This clause describes how the
digital signature framework for packages applies the W3C Recommendation
“XML-Signature Syntax and Processing” from 12 February 2002 (also referred
to here as the “XML Digital Signature specification”).  This clause
introduces further requirements on digital signatures when applied to a
package.
===

12.2

Last sentence of para 1
  "By signing a subset, other relationships can be added, removed, or
modified without invalidating the signature."
is grammatically awkward.  The relationships aren't doing the signing.

=== suggested replacement sentence
If only a subset of relationships are signed, other relationships can be
added, removed, or modified without invalidating the signature.

Para 2.  I agree that the paragraph has little value.  I might replace with
a Note, something like:

[Note; The definition for a derived format would benefit from an explicit
policy that specifies which portions of a package should not change in
order for the content to be considered intact. ]


12.3.1   I see two X.509 certificates in the diagram (Fig 12-1)  The figure
description mentions one.


12.3.3
In first sentence:   Does "digital signature markup" warrant a reference to
12.4?

 "One or more of these parts may exist in a package." is potentially
confusing.  A package does not need to have any XML Signature Parts.

What about replacing with:
"More than one of these parts may exist in a package."


12.3.4
Second sentence
"Alternatively, instead of using a Digital Signature Certificate part, the
certificate may exist as a separate part in the package, may be embedded
within the Digital Signature XML Signature part itself, or may be excluded
from the package if certificate data is known or can be obtained from a
local or remote certificate store. "

Reads awkwardly particularly wrt "excluded".  The original wording used
"not included."

====suggested rewording====
Instead of using a Digital Signature Certificate part, the certificate may
exist as a separate part in the package, or may be embedded within the
Digital Signature XML Signature part itself.  When certificate data is
known or can be obtained from a local or remote certificate store, the
certificate may be omitted from the package.
====

Last para.
"media types" should be singular.

12.4.1
First para is awkward.
"The markup described here includes additional requirements on some
elements and attributes from the XML Digital Signature specification and
some package-specific markup.   For each element having such additional
requirements, there is a subclause for it.  When an element does not have
any additional requirements, there are no subclause for it.  In other
words, if an element in XML- Signature Syntax and Processing is not
mentioned, it is allowed and there are no additional requirements.  For
example, an X509Certificate element in XML- Signature Syntax and Processing
is not mentioned, but it is allowed."

====suggested rewording====
The digital signature markup within a Digital Signature XML Signature part
is based on the XML Digital Signature specification, supplemented with some
package-specific markup.  As described here, additional requirements are
imposed on some elements and attributes from the XML Digital Signature
specification.  For each element having such additional requirements, there
is a subclause below.  For elements without additional requirements, there
is no subclause.  In other words, if an element in the XML Digital
Signature specification is not mentioned, it is allowed and there are no
additional requirements.  For example, an X509Certificate element is
allowed.


12.4.2  What does "local-data" mean?  I looked for it in the XML Digital
Signature spec, but don't see it.

The additional requirement(s) would be clearer if split.  Given that we are
dropping [Mx.xx] indicators, I see no disadvantage.

A Signature element shall contain exactly one local-data, package-specific
Object element.  A Signature element may contain application-defined Object
elements.

12.4.5

The 2012 version DOES IMPOSE an additional requirement .   The W3C spec
requires support for DSA but only RECOMMENDS support for RSA (both with
SHA1).  Pointer to 6.5 Canonicalization Algorithms in XML Digital Signature
specification might be useful.  Or to 6.5.1 for the particular
canonicalization algorithms.

I would have found it helpful here and in 12.4.8 to be told that the
algorithms are identified by URIs (or whichever term we have standardized
on now.)

12.4.6 See general concern at top.  It wasn't until I got to trying to
understand the example in 12.5 that I realized how inadequate this
subclause was.

12.4.6.1
The first two sentences seem to mean the same thing.  Perhaps only one is
necessary.

12.4.8  This subclause is confusing.  I don't have a single suggested
approach to rewording.  Below are some individual suggestions — probably
not compatible.

We have dropped a table for the Relationship Transform element from the
2012 OPC spec. that helped a lot.  Can we bring it back?  12.4.19 and
12.4.20 are incomprehensible without the content of the table.  In
particular 12.4.20 refers to this subclause implying it defines the
Relationships Transform element — which it no longer does.

Probably need a pointer to 6.6 Transform Algorithms in the XML Digital
Signature specification.

"Relationships transform" could benefit from brief contextualization or
pointer to 12.4.21 at first mention.  Could we use Relationships Transform
— with initial capital for Transform throughout?    It is used in
subclauses 12.4.19 and 12.4.20.
The sentence/paragraph added after the list of permitted transforms
interrupts the flow about Relationships Transform

As I read about filtering, I wanted to know: When does the filtering need
to happen?  What is the filtering intended to achieve.

Move the sentence
"Relationships transforms shall only be used when the Transform element is
a descendant element of a Manifest element and followed by a
canonicalization transform [M6.19]" to the end of the subclause.  Rewrite
to make sure what is meant by "followed by a canonical transform" actually
means. I think it means followed by a Transform element specifying a
canonicalization transform.  Provide pointer to Manifest element subclause.

12.4.9 is confusing (a) because the W3C spec document we are using as the
basis refers to SHA-1 algorithm (singular) not RSA-SHA1 algorithms and (b)
the sentence seems inverted.  I don't find a Normative Reference in our
document.  The W3C 2002 spec has a bad link to FIPS PUB 180-1. Secure Hash
Standard. U.S. Department of Commerce/National Institute of Standards and
Technology.  Good link is to
https://csrc.nist.gov/csrc/media/publications/fips/180/2/archive/2002-08-01/documents/fips180-2.pdf
— but standard has been superseded by FIPS 180-4.  Find at
https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf  or, perhaps
better, via DOI, at http://dx.doi.org/10.6028/NIST.FIPS.180-4

The current W3C spec cites FIPS 180-3 as a Normative Reference.

===suggested rewording (without decision as to how we refer to the digest
algorithm====
A DigestMethod element shall specify a RSA-SHA1 algorithm. [M6.17]
RSA-SHA1 algorithms shall be supported for validation.

12.4.10

Middle requirement sentence in 12.4.10.1 is not really a requirement on the
Object element.  If kept here, it should be in a separate paragraph from
the other added requirements.  The requirement is also stated in 12.4.2.

Last sentence of 12.4.10.2 reads oddly.  A "derived format" doesn't really
"apply restrictions."  I always stumble over "might not" used like this.

====suggested rewording===
Derived format specifications are not required to adopt the
package-specific restrictions regarding URIs and Transform elements to
application-defined Object elements.
====

12.4.12
It would be clearer if  "references" clearly meant Reference elements.

12.4.14
Not clear that the structure of the SignatureProperty element is defined in
the same clause in XML Dig Sig spec as SignatureProperties.  Can a
package-specific Object have more than one SignatureProperty element?  I
think so, but without the diagrams that isn't quite clear.  I think what we
need to say here is probably something like

What does "by" mean in 'shall specify "idSignatureTime" by the Id
attribute,'?

I think what we need to say here is probably something like
====suggest rewording====
A package-specific Object element shall contain a SignatureProperty element
with an Id attribute with the value "idSignatureTime".  The Target
attribute value of such a SignatureProperty element shall be either empty
or contain a fragment reference to the value of the Id attribute of the
root Signature element. This SignatureProperty element shall contain a
SignatureTime element and no other elements.

 12.4.19
=====suggested minor rewording for first sentence===
The RelationshipReference element specifies that the Relationship element
with a specified Id value is signed.

12.4.20
I would change "the specified value" to "a specified value".

"A derived format might allow individual relationships in a package or the
Relationships part as a whole to be signed. [O6.10] To sign or validate a
subset of relationships, the package-specific Relationships Transform shall
be used. [M6.25] To filter signed relationships based on their IDs, a
RelationshipReference element with the corresponding SourceID attribute is
added to the Relationships Transform element (§12.4.8). To filter signed
relationships based on their type, a RelationshipGroupReference element
with the corresponding SourceType attribute is added to the Relationships
Transform element. Only one relationship transform shall be specified for a
particular Relationships part. [M6.35]"

is (a) very dense and (b) seems to refer as much to 12.4.19 as to 12.4.20.
Teasing it apart:

"A derived format might allow individual relationships in a package or the
Relationships part as a whole to be signed. [O6.10]"

"To sign or validate a subset of relationships, the package-specific
Relationships Transform shall be used."
BUT IS an "individual relationship" a "subset"

"To filter signed relationships based on their IDs, a RelationshipReference
element with the corresponding SourceID attribute is added to the
Relationships Transform element (§12.4.8). "
RELATES TO 12.4.19 or the missing description of the Relationships
Transform Element.

"To filter signed relationships based on their type, a
RelationshipGroupReference element with the corresponding SourceType
attribute is added to the Relationships Transform element."

"Only one relationship transform shall be specified for a particular
Relationships part."
DOESN'T SEEM TO BE A REQUIREMENT ON the RelationshipGroupReference element.

12.4.21
=====suggested rewording for first sentence
A Relationships Transform takes the XML document of a Relationships part
and converts it to another XML document.

Can we add a brief explanation here that mentions the RelationshipReference
and RelationshipsGroupReference elements — which are the elements that have
the SourceType and SourceId values that are mentioned.


12.5 This example would benefit from a brief description, particularly to
say that it includes the structure for signing a package-specific digest
AND an application-defined digest — but omits the detail for the
application-defined "object."

12.6 and beyond
I RAN OUT OF ENERGY
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mailman.vse.cz/pipermail/sc34wg4/attachments/20180304/231b0cff/attachment-0001.html>
-------------- next part --------------


General concerns.  

We currently use the 2002 version of the W3C spec.  I had been checking clause references in that document (assuming we needed to use the old spec for some reason — but when I got to the DigestMethod element, I wondered whether that assumption was incorrect.  The latest W3C spec is always at https://www.w3.org/TR/xmldsig-core/
Currently that gets to a 2013 version  https://www.w3.org/TR/2013/REC-xmldsig-core1-20130411/

Clause 4 does not define "package" as conforming to the OPC specification.  However, I think Clause 12 does use the term to apply to OPC packages.  I was particularly confused as to the meaning of "package-specific."  When I read "package-specific" I could interpret it as being specific to a particular package instance.  I think what is meant amounts to OPC-specific.  I'm wondering if we can use that term (or something equivalent) in this clause.  I have not suggested a change — but I find the use of "package-specific" confusing in MANY cases.

"Relationships transform" is introduced and used again in 12.4.8 without clearly indicating where it is defined/explained. I did not understand the explanation — why is it needed.  What problem does it address?   [Eventually I figured it out, but only with difficulty.]  

When I got to the example in 12.5, I realized that I didn't understand how the elements relate to each other and the links to the W3C spec didn't help.  In particular, I hadn't grasped that the Reference element not only defined what was being signed, but included the digest value that is the guts of the digital signature.  Of course, the schema definition in the W3C spec lists DigestValue, but that subclause does a poor job of relating the Reference element to the Signature process.  You have to read 2.1 in the W3C spec to understand that:
 "Each Reference element includes the digest method and resulting digest value calculated over the identified data object. It also may include transformations that produced the input to the digest operation. A data object is signed by computing its digest value and a signature over that value. "

Could we include an equivalent statement either near the beginning of 12.4 or in 12.4.6?

12.1   General

In first sentence: It isn't the signatures "which identify …" but the associated markup.

I think we should mention the date for the W3C spec here (not just in the Normative References clause) because there are more recent versions.  We currently have https://www.w3.org/TR/2002/REC-xmldsig-core-20020212/ in Normative references.

=== Suggested rewording.  

A derived format might allow a package to include digital signatures and markup that identifies the parts of a package that have been signed and the process for validating the signatures. This clause describes how the digital signature framework for packages applies the W3C Recommendation “XML-Signature Syntax and Processing” from 12 February 2002 (also referred to here as the “XML Digital Signature specification”).  This clause introduces further requirements on digital signatures when applied to a package. 
===

12.2

Last sentence of para 1 
  "By signing a subset, other relationships can be added, removed, or modified without invalidating the signature."
is grammatically awkward.  The relationships aren't doing the signing.  

=== suggested replacement sentence
If only a subset of relationships are signed, other relationships can be added, removed, or modified without invalidating the signature.

Para 2.  I agree that the paragraph has little value.  I might replace with a Note, something like:

[Note; The definition for a derived format would benefit from an explicit policy that specifies which portions of a package should not change in order for the content to be considered intact. ]


12.3.1   I see two X.509 certificates in the diagram (Fig 12-1)  The figure description mentions one.


12.3.3   
In first sentence:   Does "digital signature markup" warrant a reference to 12.4?

 "One or more of these parts may exist in a package." is potentially confusing.  A package does not need to have any XML Signature Parts.

What about replacing with:
"More than one of these parts may exist in a package."


12.3.4  
Second sentence
"Alternatively, instead of using a Digital Signature Certificate part, the certificate may exist as a separate part in the package, may be embedded within the Digital Signature XML Signature part itself, or may be excluded from the package if certificate data is known or can be obtained from a local or remote certificate store. "

Reads awkwardly particularly wrt "excluded".  The original wording used "not included."

====suggested rewording====
Instead of using a Digital Signature Certificate part, the certificate may exist as a separate part in the package, or may be embedded within the Digital Signature XML Signature part itself.  When certificate data is known or can be obtained from a local or remote certificate store, the certificate may be omitted from the package.
====

Last para.
"media types" should be singular.

12.4.1
First para is awkward.
"The markup described here includes additional requirements on some elements and attributes from the XML Digital Signature specification and some package-specific markup.   For each element having such additional requirements, there is a subclause for it.  When an element does not have any additional requirements, there are no subclause for it.  In other words, if an element in XML- Signature Syntax and Processing is not mentioned, it is allowed and there are no additional requirements.  For example, an X509Certificate element in XML- Signature Syntax and Processing is not mentioned, but it is allowed."

====suggested rewording====
The digital signature markup within a Digital Signature XML Signature part is based on the XML Digital Signature specification, supplemented with some package-specific markup.  As described here, additional requirements are imposed on some elements and attributes from the XML Digital Signature specification.  For each element having such additional requirements, there is a subclause below.  For elements without additional requirements, there is no subclause.  In other words, if an element in the XML Digital Signature specification is not mentioned, it is allowed and there are no additional requirements.  For example, an X509Certificate element is allowed. 


12.4.2  What does "local-data" mean?  I looked for it in the XML Digital Signature spec, but don't see it.

The additional requirement(s) would be clearer if split.  Given that we are dropping [Mx.xx] indicators, I see no disadvantage.

A Signature element shall contain exactly one local-data, package-specific Object element.  A Signature element may contain application-defined Object elements. 

12.4.5

The 2012 version DOES IMPOSE an additional requirement .   The W3C spec requires support for DSA but only RECOMMENDS support for RSA (both with SHA1).  Pointer to 6.5 Canonicalization Algorithms in XML Digital Signature specification might be useful.  Or to 6.5.1 for the particular canonicalization algorithms.

I would have found it helpful here and in 12.4.8 to be told that the algorithms are identified by URIs (or whichever term we have standardized on now.)

12.4.6 See general concern at top.  It wasn't until I got to trying to understand the example in 12.5 that I realized how inadequate this subclause was.  

12.4.6.1
The first two sentences seem to mean the same thing.  Perhaps only one is necessary.  

12.4.8  This subclause is confusing.  I don't have a single suggested approach to rewording.  Below are some individual suggestions — probably not compatible.

We have dropped a table for the Relationship Transform element from the 2012 OPC spec. that helped a lot.  Can we bring it back?  12.4.19 and 12.4.20 are incomprehensible without the content of the table.  In particular 12.4.20 refers to this subclause implying it defines the Relationships Transform element — which it no longer does.

Probably need a pointer to 6.6 Transform Algorithms in the XML Digital Signature specification.

"Relationships transform" could benefit from brief contextualization or pointer to 12.4.21 at first mention.  Could we use Relationships Transform — with initial capital for Transform throughout?    It is used in subclauses 12.4.19 and 12.4.20.
The sentence/paragraph added after the list of permitted transforms interrupts the flow about Relationships Transform 

As I read about filtering, I wanted to know: When does the filtering need to happen?  What is the filtering intended to achieve.

Move the sentence
"Relationships transforms shall only be used when the Transform element is a descendant element of a Manifest element and followed by a canonicalization transform [M6.19]" to the end of the subclause.  Rewrite to make sure what is meant by "followed by a canonical transform" actually means. I think it means followed by a Transform element specifying a canonicalization transform.  Provide pointer to Manifest element subclause.

12.4.9 is confusing (a) because the W3C spec document we are using as the basis refers to SHA-1 algorithm (singular) not RSA-SHA1 algorithms and (b) the sentence seems inverted.  I don't find a Normative Reference in our document.  The W3C 2002 spec has a bad link to FIPS PUB 180-1. Secure Hash Standard. U.S. Department of Commerce/National Institute of Standards and Technology.  Good link is to https://csrc.nist.gov/csrc/media/publications/fips/180/2/archive/2002-08-01/documents/fips180-2.pdf — but standard has been superseded by FIPS 180-4.  Find at https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf  or, perhaps better, via DOI, at http://dx.doi.org/10.6028/NIST.FIPS.180-4

The current W3C spec cites FIPS 180-3 as a Normative Reference.

===suggested rewording (without decision as to how we refer to the digest algorithm====
A DigestMethod element shall specify a RSA-SHA1 algorithm. [M6.17]  RSA-SHA1 algorithms shall be supported for validation.

12.4.10

Middle requirement sentence in 12.4.10.1 is not really a requirement on the Object element.  If kept here, it should be in a separate paragraph from the other added requirements.  The requirement is also stated in 12.4.2.

Last sentence of 12.4.10.2 reads oddly.  A "derived format" doesn't really "apply restrictions."  I always stumble over "might not" used like this.

====suggested rewording===
Derived format specifications are not required to adopt the package-specific restrictions regarding URIs and Transform elements to application-defined Object elements. 
====

12.4.12
It would be clearer if  "references" clearly meant Reference elements.

12.4.14  
Not clear that the structure of the SignatureProperty element is defined in the same clause in XML Dig Sig spec as SignatureProperties.  Can a package-specific Object have more than one SignatureProperty element?  I think so, but without the diagrams that isn't quite clear.  I think what we need to say here is probably something like 

What does "by" mean in 'shall specify "idSignatureTime" by the Id attribute,'?  

I think what we need to say here is probably something like 
====suggest rewording====
A package-specific Object element shall contain a SignatureProperty element with an Id attribute with the value "idSignatureTime".  The Target attribute value of such a SignatureProperty element shall be either empty or contain a fragment reference to the value of the Id attribute of the root Signature element. This SignatureProperty element shall contain a SignatureTime element and no other elements.  

 12.4.19
=====suggested minor rewording for first sentence===
The RelationshipReference element specifies that the Relationship element with a specified Id value is signed.

12.4.20
I would change "the specified value" to "a specified value".  

"A derived format might allow individual relationships in a package or the Relationships part as a whole to be signed. [O6.10] To sign or validate a subset of relationships, the package-specific Relationships Transform shall be used. [M6.25] To filter signed relationships based on their IDs, a RelationshipReference element with the corresponding SourceID attribute is added to the Relationships Transform element (§12.4.8). To filter signed relationships based on their type, a RelationshipGroupReference element with the corresponding SourceType attribute is added to the Relationships Transform element. Only one relationship transform shall be specified for a particular Relationships part. [M6.35]"

is (a) very dense and (b) seems to refer as much to 12.4.19 as to 12.4.20. Teasing it apart:

"A derived format might allow individual relationships in a package or the Relationships part as a whole to be signed. [O6.10]" 

"To sign or validate a subset of relationships, the package-specific Relationships Transform shall be used."  
BUT IS an "individual relationship" a "subset" 

"To filter signed relationships based on their IDs, a RelationshipReference element with the corresponding SourceID attribute is added to the Relationships Transform element (§12.4.8). "
RELATES TO 12.4.19 or the missing description of the Relationships Transform Element.

"To filter signed relationships based on their type, a RelationshipGroupReference element with the corresponding SourceType attribute is added to the Relationships Transform element."

"Only one relationship transform shall be specified for a particular Relationships part."
DOESN'T SEEM TO BE A REQUIREMENT ON the RelationshipGroupReference element.

12.4.21
=====suggested rewording for first sentence
A Relationships Transform takes the XML document of a Relationships part and converts it to another XML document.

Can we add a brief explanation here that mentions the RelationshipReference and RelationshipsGroupReference elements — which are the elements that have the SourceType and SourceId values that are mentioned.


12.5 This example would benefit from a brief description, particularly to say that it includes the structure for signing a package-specific digest AND an application-defined digest — but omits the detail for the application-defined "object."  

12.6 and beyond  
I RAN OUT OF ENERGY