17.15.1.29 documentProtection
This element specifies the set of document protection restrictions which have been applied to the contents of a WordprocessingML document. These restrictions should be enforced by applications editing this document when the enforcement attribute is turned on, and ignored (but persisted) otherwise. Document protection is a set of restrictions used to prevent unintentional changes to all or part of a WordprocessingML document. [Note: This protection does not encrypt the document, and malicious applications might circumvent its use. This protection is not intended as a security feature. end note]
If this element is omitted, then no protection shall be applied to this document. When a password is to be hashed and stored in this element, it shall be hashed as defined below, starting from a UTF-16LE encoded string value. If there is a leading BOM character (U+FEFF) in the encoded password it is removed before hash calculation.
Attributes
algorithmName (Cryptographic Algorithm Name)
Specifies the specific cryptographic hashing algorithm which shall be used along with the salt attribute and input password in order to compute the hash value.
The following values are reserved:
Algorithm
Specifies that the MD2 algorithm, as defined by RFC 1319, shall be used.
Attributes
formatting (Only Allow Formatting With Unlocked Styles)
Specifies if formatting restrictions are in effect for a given WordprocessingML document. This enables the document to restrict the types of styles that can exist in a given WordprocessingML document. Specifically, by setting this attribute’s value equal to true, every style whose locked element (17.7.4.7) has a value of true (or latent styles
(17.7.4.5) whose locked attribute is true) shall not be available for use in the application, nor should any direct formatting. Only styles with a locked value of false can be used.
If this attribute is omitted, then no formatting restrictions shall be applied, even when document protection is enforced.
[Example: Consider a WordprocessingML document that must apply formatting protection. This requirement would be specified using the following WordprocessingML in the document settings:
<w:documentProtection w:formatting="true" w:enforcement="true"
/>If the following definition for a style was also present in the document:
<w:style w:type="paragraph" w:styleId="Heading1">
<w:name w:val="Heading 1" />
<w:locked w:val="1" />
…
</w:style>The formatting attribute has a value of true specifying that the applications must not allow the style above to be added to the WordprocessingML document. This does not preclude previous uses of that style (which must not be removed), but does prevent new uses of this style from being added. end example]
The possible values for this attribute are defined by the ST_OnOff simple type (22.9.2.7).
enforcement (Enforce Document Protection Settings)
Specifies if the document protection settings shall be enforced for a given WordprocessingML document. If the value of this element is off, 0, or false, all the WordprocessingML pertaining to document protection is still preserved in the document, but is not enforced. If the value of this element is on, 1, or true, the document protection is enforced.
If this attribute is omitted, then document protection settings shall not be enforced by applications.
[Example: Consider a WordprocessingML document that contains the following WordprocessingML specifying that hosting applications must apply read-only protection for a given document:
<w:documentProtection w:edit="readOnly" w:enforcement="1" />The enforcement attribute has a value of 1, specifying that the document protection specified must be enforced on the given document. end example]
The possible values for this attribute are defined by the ST_OnOff simple type (22.9.2.7).
edit (Document Editing Restrictions)
Specifies the set of editing restrictions which shall be enforced on a given WordprocessingML document, as defined by the simple type referenced below
If this attribute is omitted, the consumer shall behave as though there are no editing restrictions applied to this document; equivalent to an attribute value of none.
[Example: Consider a WordprocessingML document that contains the following WordprocessingML specifying that hosting applications must enforce read-only protection for a given document:
<w:documentProtection w:edit="readOnly" w:enforcement="1" />The edit attribute has a value of readOnly and a enforcement attribute with a value of 1, specifying that read-only document protection must be enforced on the given document. end example]
The possible values for this attribute are defined by the ST_DocProtect simple type (17.18.18).
hashValue (Password Hash Value)
Specifies the hash value for the password stored with this document. This value shall be compared with the resulting hash value after hashing the user-supplied password using the algorithm specified by the preceding attributes and parent XML element, and if the two values match, the protection shall no longer be enforced.
If this value is omitted, then the reservationPassword attribute shall contain the password hash for the workbook.
[Example: Consider an Office Open XML document with the following information stored in one of its protection elements:
<… AlgorithmName="SHA-1"
hashValue="9oN7nWkCAyEZib1RomSJTjmPpCY=" />The hashValue attribute value of 9oN7nWkCAyEZib1RomSJTjmPpCY= specifies that the user-supplied password must be hashed using the pre-processing defined by the parent element (if any) followed by the SHA-1 algorithm (specified via the algorithmName attribute value of SHA-1) and that the resulting has value must be
The possible values for this attribute are defined by the W3C XML Schema base64Binary datatype.
spinCount (Iterations to Run Hashing Algorithm)
Specifies the number of times the hashing function shall be iteratively run (runs using each iteration’s result plus a 4 byte value (0-based, little endian) containing the number of the iteration as the input for the next iteration) when attempting to compare a user- supplied password with the value stored in the hashValue attribute.
[Rationale: Running the algorithm many times increases the cost of exhaustive search attacks correspondingly. Storing this value allows for the number of iterations to be increased over time to accommodate faster hardware (and hence the ability to run more iterations in less time). end rationale]
[Example: Consider an Office Open XML document with the following information stored in one of its protection elements:
<… spinCount="100000"
hashValue="9oN7nWkCAyEZib1RomSJTjmPpCY=" />The spinCount attribute value of 100000 specifies that the hashing function must be run one hundred thousand times to generate a hash value for comparison with the
hashValue attribute. end example]
The possible values for this attribute are defined by the ST_DecimalNumber simple type (17.18.10).
saltValue (Salt Value for Password Verifier)
Specifies the salt which was prepended to the user-supplied password before it was hashed using the hashing algorithm defined by the preceding attribute values to generate the hashValue attribute, and which shall also be prepended to the user-supplied password before attempting to generate a hash value for comparison. A salt is a random string which is added to a user-supplied password before it is hashed in order to prevent a malicious party from pre-calculating all possible password/hash combinations and simply using those pre-calculated values (often referred to as a “dictionary attack”).
If this attribute is omitted, then no salt shall be prepended to the user-supplied password before it is hashed for comparison with the stored hash value.
[Example: Consider an Office Open XML document with the following information stored in one of its protection elements:
<… saltValue="ZUdHa+D8F/OAKP3I7ssUnQ=="
hashValue="9oN7nWkCAyEZib1RomSJTjmPpCY=" />The saltValue attribute value of ZUdHa+D8F/OAKP3I7ssUnQ== specifies that the user- supplied password must have this value prepended before it is run through the specified hashing algorithm to generate a resulting hash value for comparison. end example]
The possible values for this attribute are defined by the W3C XML Schema base64Binary datatype.
[Note: The W3C XML Schema definition of this element’s content model (CT_DocProtect) is located in A.1. end note]