Branch data Line data Source code
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 : 0 : 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 ::rtl::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 ::rtl::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 ::rtl::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 ::rtl::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 ::rtl::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 ::rtl::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 ::rtl::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 ::rtl::OUString& rMediaPassword,
286 : : const ::com::sun::star::uno::Reference<
287 : : ::com::sun::star::task::XInteractionHandler >& rxInteractHandler,
288 : : const ::rtl::OUString& rDocumentName,
289 : : DocPasswordRequestType eRequestType,
290 : : const ::std::vector< ::rtl::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< ::rtl::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: */
|
