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