include/comphelper/docpasswordhelper.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef INCLUDED_COMPHELPER_DOCPASSWORDHELPER_HXX
  21 #define INCLUDED_COMPHELPER_DOCPASSWORDHELPER_HXX
  22
  23 #include <comphelper/comphelperdllapi.h>
  24 #include <string_view>
  25 #include <vector>
  26 #include <comphelper/docpasswordrequest.hxx>
  27 #include <comphelper/hash.hxx>
  28
  29 namespace com::sun::star::task { class XInteractionHandler; }
  30 namespace com::sun::star::beans { struct PropertyValue; }
  31 namespace com::sun::star::beans { struct NamedValue; }
  32
  33 namespace comphelper {
  34
  35 enum class DocPasswordVerifierResult
  36 {
  37     OK,
  38     WrongPassword,
  39     Abort
  40 };
  41
  42
  43 /** Base class for a password verifier used by the DocPasswordHelper class
  44     below.
  45
  46     Users have to implement the virtual functions and pass an instance of the
  47     verifier to one of the password request functions.
  48  */
  49 class COMPHELPER_DLLPUBLIC IDocPasswordVerifier
  50 {
  51 public:
  52     virtual             ~IDocPasswordVerifier();
  53
  54     /** Will be called every time a password needs to be verified.
  55
  56         @param rPassword
  57             The password to be verified
  58
  59         @param o_rEncryptionData
  60             Output parameter, that is filled with the EncryptionData generated
  61             from the password. The data is filled only if the validation was
  62             successful.
  63
  64         @return  The result of the verification.
  65             - DocPasswordVerifierResult_OK, if and only if the passed password
  66               is valid and can be used to process the related document.
  67             - DocPasswordVerifierResult_WRONG_PASSWORD, if the password is
  68               wrong. The user may be asked again for a new password.
  69             - DocPasswordVerifierResult_ABORT, if an unrecoverable error
  70               occurred while password verification. The password request loop
  71               will be aborted.
  72      */
  73     virtual DocPasswordVerifierResult verifyPassword( const OUString& rPassword, css::uno::Sequence< css::beans::NamedValue >& o_rEncryptionData ) = 0;
  74
  75     /** Will be called every time an encryption data needs to be verified.
  76
  77         @param rEncryptionData
  78             The data will be validated
  79
  80         @return  The result of the verification.
  81             - DocPasswordVerifierResult_OK, if and only if the passed encryption data
  82               is valid and can be used to process the related document.
  83             - DocPasswordVerifierResult_WRONG_PASSWORD, if the encryption data is
  84               wrong.
  85             - DocPasswordVerifierResult_ABORT, if an unrecoverable error
  86               occurred while data verification. The password request loop
  87               will be aborted.
  88      */
  89     virtual DocPasswordVerifierResult verifyEncryptionData( const css::uno::Sequence< css::beans::NamedValue >& o_rEncryptionData ) = 0;
  90
  91 };
  92
  93
  94 /** Helper that asks for a document password and checks its validity.
  95  */
  96 class COMPHELPER_DLLPUBLIC DocPasswordHelper
  97 {
  98 public:
  99
 100
 101     /** This helper function generates the information related
 102         to "Password to modify" provided by user. The result
 103         sequence contains the hash and the algorithm-related
 104         info.
 105
 106         @param aString
 107             The string for which the info should be generated
 108
 109         @return
 110             The sequence containing the hash and the algorithm-related info
 111       */
 112
 113     static css::uno::Sequence< css::beans::PropertyValue >
 114         GenerateNewModifyPasswordInfo( std::u16string_view aPassword );
 115
 116     static css::uno::Sequence<css::beans::PropertyValue>
 117     GenerateNewModifyPasswordInfoOOXML(std::u16string_view aPassword);
 118
 119     /** This helper function allows to check whether
 120         the "Password to modify" provided by user is the correct one.
 121
 122         @param aString
 123             The string containing the provided password
 124
 125         @param aInfo
 126             The sequence containing the hash and the algorithm-info
 127
 128         @return
 129             <TRUE/> if the password is correct one
 130             <FALSE/> otherwise
 131       */
 132
 133     static bool IsModifyPasswordCorrect(
 134                 std::u16string_view aPassword,
 135                 const css::uno::Sequence< css::beans::PropertyValue >& aInfo );
 136
 137
 138     /** This helper function generates the hash code based on the algorithm
 139         specified by MS for "Password to modify" feature of Word.
 140
 141         @param aString
 142             The string for which the hash should be calculated
 143
 144         @return
 145             The hash represented by sal_uInt32
 146       */
 147
 148     static sal_uInt32 GetWordHashAsUINT32(
 149                 const OUString& aString );
 150
 151
 152     /** This helper function generates the hash code based on the algorithm
 153         specified by MS for "Password to modify" and passwords related to
 154         table protection of Excel.
 155
 156         @param aString
 157             The string for which the hash should be calculated
 158
 159         @param nEnc
 160             The encoding that should be used to generate the 8-bit string
 161             before the hash is generated
 162
 163         @return
 164             The hash represented by sal_uInt16
 165       */
 166
 167     static sal_uInt16 GetXLHashAsUINT16(
 168                 std::u16string_view aString,
 169                 rtl_TextEncoding nEnc = RTL_TEXTENCODING_UTF8 );
 170
 171
 172     /** This helper function generates the hash code based on the algorithm
 173         specified by MS for "Password to modify" and passwords related to
 174         table protection.
 175
 176         @param aString
 177             The string for which the hash should be calculated
 178
 179         @return
 180             The hash represented by sequence of bytes in BigEndian form
 181       */
 182
 183     static css::uno::Sequence< sal_Int8 > GetXLHashAsSequence(
 184                 std::u16string_view aString );
 185
 186
 187     /** Convenience function to calculate a salted hash with iterations as
 188         specified in https://msdn.microsoft.com/en-us/library/dd920692 for the
 189         OOXML sheetProtection and fileSharing elements, or
 190         https://msdn.microsoft.com/en-us/library/dd924776 and
 191         https://msdn.microsoft.com/en-us/library/dd925430 for Standard and
 192         Agile Encryption.
 193
 194         @param  rPassword
 195                 UTF-16 encoded string without leading BOM character
 196
 197         @param  rSaltValue
 198                 Base64 encoded salt that will be decoded and prepended to password
 199                 data.
 200
 201         @param  nSpinCount
 202                 If >0 the number of repeated iterations.
 203
 204         @param  eIterCount
 205                 If Hash::IterCount::APPEND, append iteration count as per
 206                 https://msdn.microsoft.com/en-us/library/dd920692
 207                 If Hash::IterCount::PREPEND, prepend iteration count as per
 208                 https://msdn.microsoft.com/en-us/library/dd924776 and
 209                 https://msdn.microsoft.com/en-us/library/dd925430
 210                 If Hash::IterCount::NONE, do not add the iteration count to hash
 211                 iterations.
 212
 213         @param  rAlgorithmName
 214                 One of "SHA-512", "SHA-256", ... as listed for AlgorithmName in
 215                 https://msdn.microsoft.com/en-us/library/dd920692
 216                 or "SHA512", "SHA256", ... as listed for HashAlgorithm in
 217                 https://msdn.microsoft.com/en-us/library/dd925810
 218                 that have a valid match in comphelper::HashType. If not, an
 219                 empty sequence is returned. Not all algorithm names are
 220                 supported.
 221
 222         @return the raw hash value as sal_Int8 sequence.
 223      */
 224     static css::uno::Sequence<sal_Int8> GetOoxHashAsSequence(
 225             const OUString& rPassword,
 226             const OUString& rSaltValue,
 227             sal_uInt32 nSpinCount,
 228             comphelper::Hash::IterCount eIterCount,
 229              std::u16string_view rAlgorithmName);
 230
 231
 232     /** Convenience function to calculate a salted hash with iterations as
 233         specified in https://msdn.microsoft.com/en-us/library/dd920692 for the
 234         OOXML sheetProtection and fileSharing elements, or
 235         https://msdn.microsoft.com/en-us/library/dd924776 and
 236         https://msdn.microsoft.com/en-us/library/dd925430 for Standard and
 237         Agile Encryption.
 238
 239         @param  rPassword
 240                 UTF-16 encoded string without leading BOM character
 241
 242         @param  rSaltValue
 243                 Base64 encoded salt that will be decoded and prepended to password
 244                 data.
 245
 246         @param  nSpinCount
 247                 If >0 the number of repeated iterations.
 248
 249         @param  eIterCount
 250                 If Hash::IterCount::APPEND, append iteration count as per
 251                 https://msdn.microsoft.com/en-us/library/dd920692
 252                 If Hash::IterCount::PREPEND, prepend iteration count as per
 253                 https://msdn.microsoft.com/en-us/library/dd924776 and
 254                 https://msdn.microsoft.com/en-us/library/dd925430
 255                 If Hash::IterCount::NONE, do not add the iteration count to hash
 256                 iterations.
 257
 258         @param  rAlgorithmName
 259                 One of "SHA-512", "SHA-256", ... as listed for AlgorithmName in
 260                 https://msdn.microsoft.com/en-us/library/dd920692
 261                 or "SHA512", "SHA256", ... as listed for HashAlgorithm in
 262                 https://msdn.microsoft.com/en-us/library/dd925810
 263                 that have a valid match in comphelper::HashType. If not, an
 264                 empty sequence is returned. Not all algorithm names are
 265                 supported.
 266
 267         @return the base64 encoded string of the hash value, that can be
 268                 compared against a stored base64 encoded hash value.
 269      */
 270     static OUString GetOoxHashAsBase64(
 271             const OUString& rPassword,
 272             const OUString& rSaltValue,
 273             sal_uInt32 nSpinCount,
 274             comphelper::Hash::IterCount eIterCount,
 275             std::u16string_view rAlgorithmName);
 276
 277
 278     /** Convenience function to calculate a salted hash with iterations as
 279         specified in https://msdn.microsoft.com/en-us/library/dd920692 for the
 280         OOXML sheetProtection and fileSharing elements, or
 281         https://msdn.microsoft.com/en-us/library/dd924776 and
 282         https://msdn.microsoft.com/en-us/library/dd925430 for Standard and
 283         Agile Encryption.
 284
 285         @param  rPassword
 286                 UTF-16 encoded string without leading BOM character
 287
 288         @param  rSaltValue
 289                 A raw salt that will be prepended to password data.
 290
 291         @param  nSpinCount
 292                 If >0 the number of repeated iterations.
 293
 294         @param  eIterCount
 295                 If Hash::IterCount::APPEND, append iteration count as per
 296                 https://msdn.microsoft.com/en-us/library/dd920692
 297                 If Hash::IterCount::PREPEND, prepend iteration count as per
 298                 https://msdn.microsoft.com/en-us/library/dd924776 and
 299                 https://msdn.microsoft.com/en-us/library/dd925430
 300                 If Hash::IterCount::NONE, do not add the iteration count to hash
 301                 iterations.
 302
 303         @param  rAlgorithmName
 304                 One of "SHA-512", "SHA-256", ... as listed for AlgorithmName in
 305                 https://msdn.microsoft.com/en-us/library/dd920692
 306                 or "SHA512", "SHA256", ... as listed for HashAlgorithm in
 307                 https://msdn.microsoft.com/en-us/library/dd925810
 308                 that have a valid match in comphelper::HashType. If not, an
 309                 empty sequence is returned. Not all algorithm names are
 310                 supported.
 311
 312         @return the raw the hash value.
 313      */
 314     static std::vector<unsigned char> GetOoxHashAsVector(
 315             const OUString& rPassword,
 316             const std::vector<unsigned char>& rSaltValue,
 317             sal_uInt32 nSpinCount,
 318             comphelper::Hash::IterCount eIterCount,
 319             std::u16string_view rAlgorithmName);
 320
 321
 322     /** This helper function generates a random sequence of bytes of
 323         requested length.
 324       */
 325
 326     static css::uno::Sequence< sal_Int8 > GenerateRandomByteSequence(
 327                 sal_Int32 nLength );
 328
 329
 330     /** This helper function generates a byte sequence representing the
 331         key digest value used by MSCodec_Std97 codec.
 332       */
 333
 334     static css::uno::Sequence< sal_Int8 > GenerateStd97Key(
 335                 const OUString& aPassword,
 336                 const css::uno::Sequence< sal_Int8 >& aDocId );
 337
 338
 339     /** This helper function generates a byte sequence representing the
 340         key digest value used by MSCodec_Std97 codec.
 341       */
 342
 343     static css::uno::Sequence< sal_Int8 > GenerateStd97Key(
 344                 const sal_uInt16 pPassData[16],
 345                 const css::uno::Sequence< sal_Int8 >& aDocId );
 346
 347     /** This helper function generates a byte sequence representing the
 348         key digest value used by MSCodec_Std97 codec.
 349       */
 350
 351     static css::uno::Sequence< sal_Int8 > GenerateStd97Key(
 352                 const sal_uInt16 pPassData[16],
 353                 const sal_uInt8 pDocId[16] );
 354
 355
 356     /** This helper function tries to request and verify a password to load a
 357         protected document.
 358
 359         First, the list of default passwords will be tried if provided. This is
 360         needed by import filters for external file formats that have to check a
 361         predefined password in some cases without asking the user for a
 362         password. Every password is checked using the passed password verifier.
 363
 364         If not successful, the passed password of a medium is tried, that has
 365         been set e.g. by an API call to load a document. If existing, the
 366         password is checked using the passed password verifier.
 367
 368         If still not successful, the passed interaction handler is used to
 369         request a password from the user. This will be repeated until the
 370         passed password verifier validates the entered password, or if the user
 371         chooses to cancel password input.
 372
 373         @param rVerifier
 374             The password verifier used to check every processed password.
 375
 376         @param rMediaPassword
 377             If not empty, will be passed to the password validator before
 378             requesting a password from the user. This password usually should
 379             be querried from a media descriptor.
 380
 381         @param rxInteractHandler
 382             The interaction handler that will be used to request a password
 383             from the user, e.g. by showing a password input dialog.
 384
 385         @param rDocumentUrl
 386             The URL of the related document that will be shown in the password
 387             input dialog.
 388
 389         @param eRequestType
 390             The password request type that will be passed to the
 391             DocPasswordRequest object created internally. See
 392             docpasswordrequest.hxx for more details.
 393
 394         @param pDefaultPasswords
 395             If not null, contains default passwords that will be tried before a
 396             password will be requested from the media descriptor or the user.
 397
 398         @param pbIsDefaultPassword
 399             (output parameter) If not null, the type of the found password will
 400             be returned. True means the password has been found in the passed
 401             list of default passwords. False means the password has been taken
 402             from the rMediaPassword parameter or has been entered by the user.
 403
 404         @return
 405             If not empty, contains the password that has been validated by the
 406             passed password verifier. If empty, no valid password has been
 407             found, or the user has chosen to cancel password input.
 408      */
 409     static css::uno::Sequence< css::beans::NamedValue > requestAndVerifyDocPassword(
 410                             IDocPasswordVerifier& rVerifier,
 411                             const css::uno::Sequence< css::beans::NamedValue >& rMediaEncData,
 412                             const OUString& rMediaPassword,
 413                             const css::uno::Reference< css::task::XInteractionHandler >& rxInteractHandler,
 414                             const OUString& rDocumentUrl,
 415                             DocPasswordRequestType eRequestType,
 416                             const ::std::vector< OUString >* pDefaultPasswords = nullptr,
 417                             bool* pbIsDefaultPassword = nullptr );
 418
 419     static css::uno::Sequence< css::beans::NamedValue > decryptGpgSession(
 420         const css::uno::Sequence< css::uno::Sequence< css::beans::NamedValue > >& rGpgProperties);
 421
 422 private:
 423                         ~DocPasswordHelper();
 424 };
 425
 426
 427 } // namespace comphelper
 428
 429 #endif
 430
 431 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */