WorkbookProtection Class
Workbook Protection.When the object is serialized out as xml, its qualified name is x:workbookProtection.
Inheritance Hierarchy
System.Object
DocumentFormat.OpenXml.OpenXmlElement
DocumentFormat.OpenXml.OpenXmlLeafElement
DocumentFormat.OpenXml.Spreadsheet.WorkbookProtection
Namespace: DocumentFormat.OpenXml.Spreadsheet
Assembly: DocumentFormat.OpenXml (in DocumentFormat.OpenXml.dll)
Syntax
'Declaration
Public Class WorkbookProtection _
Inherits OpenXmlLeafElement
'Usage
Dim instance As WorkbookProtection
public class WorkbookProtection : OpenXmlLeafElement
Remarks
[ISO/IEC 29500-1 1st Edition]
18.2.29 workbookProtection (Workbook Protection)
This element specifies options for protecting data in the workbook. Applications might use workbook protection to prevent anyone from accidentally changing, moving, or deleting important data. This protection can be ignored by applications which choose not to support this optional protection mechanism.
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.
[Note: Worksheet or workbook element protection should not be confused with file security. It is not meant to make your workbook safe from unintentional modification, and cannot protect it from malicious modification. end note]
Parent Elements |
|---|
workbook (§18.2.27) |
Attributes |
Description |
|---|---|
lockRevision (Lock Revisions) |
Specifies a boolean value that indicates whether the workbook is locked for revisions. The possible values for this attribute are defined by the W3C XML Schema boolean datatype. |
lockStructure (Lock Structure) |
Specifies a boolean value that indicates whether structure of workbook is locked. A value of 1 or true indicates the structure of the workbook is locked. Worksheets in the workbook can't be moved, deleted, hidden, unhidden, or renamed, and new worksheets can't be inserted. A value of 0 or false indicates the structure of the workbook is not locked. The default value for this attribute is false. The possible values for this attribute are defined by the W3C XML Schema boolean datatype. |
lockWindows (Lock Windows) |
Specifies a boolean value that indicates whether the windows that comprise the workbook are locked. A value of 1 or true indicates the workbook windows are locked. Windows are the same size and position each time the workbook is opened. A value of 0 or false indicates the workbook windows are not locked. The default value for this attribute is false. The possible values for this attribute are defined by the W3C XML Schema boolean datatype. |
revisionsAlgorithmName (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 for the revisionsHashValue attribute. The following values are reserved: Value Algorithm MD2 Specifies that the MD2 algorithm, as defined by RFC 1319, shall be used. [Note: It is recommended that applications should avoid using this algorithm to store new hash values, due to publically known breaks. end note] MD4 Specifies that the MD4 algorithm, as defined by RFC 1320, shall be used. [Note: It is recommended that applications should avoid using this algorithm to store new hash values, due to publically known breaks. end note] MD5 Specifies that the MD5 algorithm, as defined by RFC 1321, shall be used. [Note: It is recommended that applications should avoid using this algorithm to store new hash values, due to publically known breaks. end note] RIPEMD-128 Specifies that the RIPEMD-128 algorithm, as defined by ISO/IEC 10118-3:2004 shall be used. [Note: It is recommended that applications should avoid using this algorithm to store new hash values, due to publically known breaks. end note] RIPEMD-160 Specifies that the RIPEMD-160 algorithm, as defined by ISO/IEC 10118-3:2004 shall be used. SHA-1 Specifies that the SHA-1 algorithm, as defined by ISO/IEC 10118-3:2004 shall be used. SHA-256 Specifies that the SHA-256 algorithm, as defined by ISO/IEC 10118-3:2004 shall be used. SHA-384 Specifies that the SHA-384 algorithm, as defined by ISO/IEC 10118-3:2004 shall be used. SHA-512 Specifies that the SHA-512 algorithm, as defined by ISO/IEC 10118-3:2004 shall be used. WHIRLPOOL Specifies that the WHIRLPOOL algorithm, as defined by ISO/IEC 10118-3:2004 shall be used. [Example: Consider an Office Open XML document with the following information stored in one of its protection elements: < … revisionsAlgorithmName="SHA-1" revisionsHashValue="9oN7nWkCAyEZib1RomSJTjmPpCY=" /> The revisionsAlgorithmName attribute value of “SHA-1” specifies that the SHA-1 hashing algorithm shall be used to generate a hash from the user-defined password. end example] The possible values for this attribute are defined by the ST_Xstring simple type (§22.9.2.19). |
revisionsHashValue (Password Hash Value) |
Specifies the hash value for the password stored for unlocking revisions in this workbook. 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 a SpreadsheetML document with the following information stored in one of its protection elements: <… revisionsAlgorithmName="SHA-1" revisionsHashValue="9oN7nWkCAyEZib1RomSJTjmPpCY=" /> The revisionsHashValue 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 revisionsAlgorithmName attribute value of SHA-1) and that the resulting has value must be 9oN7nWkCAyEZib1RomSJTjmPpCY= for the protection to be disabled. end example] The possible values for this attribute are defined by the W3C XML Schema base64Binary datatype. |
revisionsSaltValue (Salt Value for Password Verifier) |
Specifies the salt that was prepended to the user-supplied password before it was hashed using the hashing algorithm defined by the preceding attribute values to generate the revisionsHashValue attribute, and that 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: <… revisionsSaltValue="ZUdHa+D8F/OAKP3I7ssUnQ==" revisionsHashValue="9oN7nWkCAyEZib1RomSJTjmPpCY=" /> The revisionsSaltValue 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. |
revisionsSpinCount (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 revisionsHashValue 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: <… revisionsSpinCount="100000" revisionHashValue="9oN7nWkCAyEZib1RomSJTjmPpCY=" /> The revisionsSpinCount 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 revisionsHashValue attribute. end example] The possible values for this attribute are defined by the W3C XML Schema unsignedInt datatype. |
workbookAlgorithmName (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 for the workbookHashValue attribute. The following values are reserved: Value Algorithm MD2 Specifies that the MD2 algorithm, as defined by RFC 1319, shall be used. [Note: It is recommended that applications should avoid using this algorithm to store new hash values, due to publically known breaks. end note] MD4 Specifies that the MD4 algorithm, as defined by RFC 1320, shall be used. [Note: It is recommended that applications should avoid using this algorithm to store new hash values, due to publically known breaks. end note] MD5 Specifies that the MD5 algorithm, as defined by RFC 1321, shall be used. [Note: It is recommended that applications should avoid using this algorithm to store new hash values, due to publically known breaks. end note] RIPEMD-128 Specifies that the RIPEMD-128 algorithm, as defined by ISO/IEC 10118-3:2004 shall be used. [Note: It is recommended that applications should avoid using this algorithm to store new hash values, due to publically known breaks. end note] RIPEMD-160 Specifies that the RIPEMD-160 algorithm, as defined by ISO/IEC 10118-3:2004 shall be used. SHA-1 Specifies that the SHA-1 algorithm, as defined by ISO/IEC 10118-3:2004 shall be used. SHA-256 Specifies that the SHA-256 algorithm, as defined by ISO/IEC 10118-3:2004 shall be used. SHA-384 Specifies that the SHA-384 algorithm, as defined by ISO/IEC 10118-3:2004 shall be used. SHA-512 Specifies that the SHA-512 algorithm, as defined by ISO/IEC 10118-3:2004 shall be used. WHIRLPOOL Specifies that the WHIRLPOOL algorithm, as defined by ISO/IEC 10118-3:2004 shall be used. [Example: Consider an Office Open XML document with the following information stored in one of its protection elements: < … workbookAlgorithmName="SHA-1" workbookHashValue="9oN7nWkCAyEZib1RomSJTjmPpCY=" /> The workbookAlgorithmName attribute value of “SHA-1” specifies that the SHA-1 hashing algorithm must be used to generate a hash from the user-defined password. end example] The possible values for this attribute are defined by the ST_Xstring simple type (§22.9.2.19). |
workbookHashValue (Password Hash Value) |
Specifies the hash value for the password stored for unlocking this workbook. 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 a SpreadsheetML document with the following information stored in one of its protection elements: <… workbookAlgorithmName="SHA-1" workbookHashValue="9oN7nWkCAyEZib1RomSJTjmPpCY=" /> The workbookHashValue 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 workbookAlgorithmName attribute value of SHA-1) and that the resulting has value must be 9oN7nWkCAyEZib1RomSJTjmPpCY= for the protection to be disabled. end example] The possible values for this attribute are defined by the W3C XML Schema base64Binary datatype. |
workbookSaltValue (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 workbookHashValue 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: <… workbookSaltValue="ZUdHa+D8F/OAKP3I7ssUnQ==" workbookHashValue="9oN7nWkCAyEZib1RomSJTjmPpCY=" /> The workbookSaltValue 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. |
workbookSpinCount (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 workbookHashValue 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: <… workbookSpinCount="100000" revisionHashValue="9oN7nWkCAyEZib1RomSJTjmPpCY=" /> The workbookSpinCount 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 workbookHashValue attribute. end example] The possible values for this attribute are defined by the W3C XML Schema unsignedInt datatype. |
[Note: The W3C XML Schema definition of this element’s content model (CT_WorkbookProtection) is located in §A.2. end note]
© ISO/IEC29500: 2008.
Thread Safety
Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.