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 <com/sun/star/beans/NamedValue.hpp>
  24 #include <comphelper/comphelperdllapi.h>
  25 #include <vector>
  26 #include <comphelper/docpasswordrequest.hxx>
  27
  28 namespace com { namespace sun { namespace star { namespace task { class XInteractionHandler; } } } }
  29 namespace com { namespace sun { namespace star { namespace beans { struct PropertyValue; } } } }
  30
  31 namespace comphelper {
  32
  33 enum class DocPasswordVerifierResult
  34 {
  35     OK,
  36     WrongPassword,
  37     Abort
  38 };
  39
  40
  41 /** Base class for a password verifier used by the DocPasswordHelper class
  42     below.
  43
  44     Users have to implement the virtual functions and pass an instance of the
  45     verifier to one of the password request functions.
  46  */
  47 class COMPHELPER_DLLPUBLIC IDocPasswordVerifier
  48 {
  49 public:
  50     virtual             ~IDocPasswordVerifier();
  51
  52     /** Will be called every time a password needs to be verified.
  53
  54         @param rPassword
  55             The password to be verified
  56
  57         @param o_rEncryptionData
  58             Output parameter, that is filled with the EncryptionData generated
  59             from the password. The data is filled only if the validation was
  60             successful.
  61
  62         @return  The result of the verification.
  63             - DocPasswordVerifierResult_OK, if and only if the passed password
  64               is valid and can be used to process the related document.
  65             - DocPasswordVerifierResult_WRONG_PASSWORD, if the password is
  66               wrong. The user may be asked again for a new password.
  67             - DocPasswordVerifierResult_ABORT, if an unrecoverable error
  68               occurred while password verification. The password request loop
  69               will be aborted.
  70      */
  71     virtual DocPasswordVerifierResult verifyPassword( const OUString& rPassword, css::uno::Sequence< css::beans::NamedValue >& o_rEncryptionData ) = 0;
  72
  73     /** Will be called every time an encryption data needs to be verified.
  74
  75         @param rEncryptionData
  76             The data will be validated
  77
  78         @return  The result of the verification.
  79             - DocPasswordVerifierResult_OK, if and only if the passed encryption data
  80               is valid and can be used to process the related document.
  81             - DocPasswordVerifierResult_WRONG_PASSWORD, if the encryption data is
  82               wrong.
  83             - DocPasswordVerifierResult_ABORT, if an unrecoverable error
  84               occurred while data verification. The password request loop
  85               will be aborted.
  86      */
  87     virtual DocPasswordVerifierResult verifyEncryptionData( const css::uno::Sequence< css::beans::NamedValue >& o_rEncryptionData ) = 0;
  88
  89 };
  90
  91
  92 /** Helper that asks for a document password and checks its validity.
  93  */
  94 class COMPHELPER_DLLPUBLIC DocPasswordHelper
  95 {
  96 public:
  97
  98
  99     /** This helper function generates the information related
 100         to "Password to modify" provided by user. The result
 101         sequence contains the hash and the algorithm-related
 102         info.
 103
 104         @param aString
 105             The string for which the info should be generated
 106
 107         @return
 108             The sequence containing the hash and the algorithm-related info
 109       */
 110
 111     static css::uno::Sequence< css::beans::PropertyValue >
 112         GenerateNewModifyPasswordInfo( const OUString& aPassword );
 113
 114
 115     /** This helper function allows to check whether
 116         the "Password to modify" provided by user is the correct one.
 117
 118         @param aString
 119             The string containing the provided password
 120
 121         @param aInfo
 122             The sequence containing the hash and the algorithm-info
 123
 124         @return
 125             <TRUE/> if the password is correct one
 126             <FALSE/> otherwise
 127       */
 128
 129     static bool IsModifyPasswordCorrect(
 130                 const OUString& aPassword,
 131                 const css::uno::Sequence< css::beans::PropertyValue >& aInfo );
 132
 133
 134     /** This helper function generates the hash code based on the algorithm
 135         specified by MS for "Password to modify" feature of Word.
 136
 137         @param aString
 138             The string for which the hash should be calculated
 139
 140         @return
 141             The hash represented by sal_uInt32
 142       */
 143
 144     static sal_uInt32 GetWordHashAsUINT32(
 145                 const OUString& aString );
 146
 147
 148     /** This helper function generates the hash code based on the algorithm
 149         specified by MS for "Password to modify" and passwords related to
 150         table protection of Excel.
 151
 152         @param aString
 153             The string for which the hash should be calculated
 154
 155         @param nEnc
 156             The encoding that should be used to generate the 8-bit string
 157             before the hash is generated
 158
 159         @return
 160             The hash represented by sal_uInt16
 161       */
 162
 163     static sal_uInt16 GetXLHashAsUINT16(
 164                 const OUString& aString,
 165                 rtl_TextEncoding nEnc = RTL_TEXTENCODING_UTF8 );
 166
 167
 168     /** This helper function generates the hash code based on the algorithm
 169         specified by MS for "Password to modify" and passwords related to
 170         table protection.
 171
 172         @param aString
 173             The string for which the hash should be calculated
 174
 175         @return
 176             The hash represented by sequence of bytes in BigEndian form
 177       */
 178
 179     static css::uno::Sequence< sal_Int8 > GetXLHashAsSequence(
 180                 const OUString& aString );
 181
 182
 183     /** This helper function generates a random sequence of bytes of
 184         requested length.
 185       */
 186
 187     static css::uno::Sequence< sal_Int8 > GenerateRandomByteSequence(
 188                 sal_Int32 nLength );
 189
 190
 191     /** This helper function generates a byte sequence representing the
 192         key digest value used by MSCodec_Std97 codec.
 193       */
 194
 195     static css::uno::Sequence< sal_Int8 > GenerateStd97Key(
 196                 const OUString& aPassword,
 197                 const css::uno::Sequence< sal_Int8 >& aDocId );
 198
 199
 200     /** This helper function generates a byte sequence representing the
 201         key digest value used by MSCodec_Std97 codec.
 202       */
 203
 204     static css::uno::Sequence< sal_Int8 > GenerateStd97Key(
 205                 const sal_uInt16 pPassData[16],
 206                 const css::uno::Sequence< sal_Int8 >& aDocId );
 207
 208     /** This helper function generates a byte sequence representing the
 209         key digest value used by MSCodec_Std97 codec.
 210       */
 211
 212     static css::uno::Sequence< sal_Int8 > GenerateStd97Key(
 213                 const sal_uInt16 pPassData[16],
 214                 const sal_uInt8 pDocId[16] );
 215
 216
 217     /** This helper function tries to request and verify a password to load a
 218         protected document.
 219
 220         First, the list of default passwords will be tried if provided. This is
 221         needed by import filters for external file formats that have to check a
 222         predefined password in some cases without asking the user for a
 223         password. Every password is checked using the passed password verifier.
 224
 225         If not successful, the passed password of a medium is tried, that has
 226         been set e.g. by an API call to load a document. If existing, the
 227         password is checked using the passed password verifier.
 228
 229         If still not successful, the passed interaction handler is used to
 230         request a password from the user. This will be repeated until the
 231         passed password verifier validates the entered password, or if the user
 232         chooses to cancel password input.
 233
 234         @param rVerifier
 235             The password verifier used to check every processed password.
 236
 237         @param rMediaPassword
 238             If not empty, will be passed to the password validator before
 239             requesting a password from the user. This password usually should
 240             be querried from a media descriptor.
 241
 242         @param rxInteractHandler
 243             The interaction handler that will be used to request a password
 244             from the user, e.g. by showing a password input dialog.
 245
 246         @param rDocumentUrl
 247             The URL of the related document that will be shown in the password
 248             input dialog.
 249
 250         @param eRequestType
 251             The password request type that will be passed to the
 252             DocPasswordRequest object created internally. See
 253             docpasswordrequest.hxx for more details.
 254
 255         @param pDefaultPasswords
 256             If not null, contains default passwords that will be tried before a
 257             password will be requested from the media descriptor or the user.
 258
 259         @param pbIsDefaultPassword
 260             (output parameter) If not null, the type of the found password will
 261             be returned. True means the password has been found in the passed
 262             list of default passwords. False means the password has been taken
 263             from the rMediaPassword parameter or has been entered by the user.
 264
 265         @return
 266             If not empty, contains the password that has been validated by the
 267             passed password verifier. If empty, no valid password has been
 268             found, or the user has chosen to cancel password input.
 269      */
 270     static css::uno::Sequence< css::beans::NamedValue > requestAndVerifyDocPassword(
 271                             IDocPasswordVerifier& rVerifier,
 272                             const css::uno::Sequence< css::beans::NamedValue >& rMediaEncData,
 273                             const OUString& rMediaPassword,
 274                             const css::uno::Reference< css::task::XInteractionHandler >& rxInteractHandler,
 275                             const OUString& rDocumentUrl,
 276                             DocPasswordRequestType eRequestType,
 277                             const ::std::vector< OUString >* pDefaultPasswords = nullptr,
 278                             bool* pbIsDefaultPassword = nullptr );
 279
 280 private:
 281                         ~DocPasswordHelper();
 282 };
 283
 284
 285 } // namespace comphelper
 286
 287 #endif
 288
 289 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */