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