1 : // Copyright 2012 Google Inc. All Rights Reserved.
2 : //
3 : // Licensed under the Apache License, Version 2.0 (the "License");
4 : // you may not use this file except in compliance with the License.
5 : // You may obtain a copy of the License at
6 : //
7 : // http://www.apache.org/licenses/LICENSE-2.0
8 : //
9 : // Unless required by applicable law or agreed to in writing, software
10 : // distributed under the License is distributed on an "AS IS" BASIS,
11 : // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 : // See the License for the specific language governing permissions and
13 : // limitations under the License.
14 : //
15 : // Declares PERelinker. Relinking can be seen as decomposing an input image,
16 : // applying a sequence of block-graph transforms (some applied implicitly, and
17 : // others provided by the user), followed by a sequence of orderers (again, some
18 : // implicit, some provided by the user), laying-out, finalizing and finally
19 : // writing a new image. After writing the image a similar transformation
20 : // workflow is applied to the corresponding PDB file, consisting of applying
21 : // any user defined PDB mutations, followed by 2-3 (depending on PeRelinker
22 : // configuration) internal mutations (updating the GUID/age, adding the history
23 : // stream and adding the serialized block-graph stream). PERelinker encapsulates
24 : // this workflow.
25 : //
26 : // It is intended to be used as follows:
27 : //
28 : // PERelinker relinker;
29 : // relinker.set_input_path(...); // Required.
30 : // relinker.set_output_path(...); // Required.
31 : // relinker.set_input_pdb_path(...); // Optional.
32 : // relinker.set_output_pdb_path(...); // Optional.
33 : // relinker.Init(); // Check the return value!
34 : //
35 : // // At this point, the following accessors are valid:
36 : // relinker.input_pe_file();
37 : // relinker.input_image_layout();
38 : // relinker.block_graph();
39 : // relinker.dos_header_block();
40 : // relinker.output_guid();
41 : //
42 : // relinker.AppendTransform(...); // May be called repeatedly.
43 : // relinker.AppendOrderer(...); // May be called repeatedly.
44 : // relinker.AppendPdbMutator(...); // May be called repeatedly.
45 : //
46 : // relinker.Relink(); // Check the return value!
47 : //
48 : // NOTE: This split workflow is only necessary as a workaround to deal with
49 : // transforms and orderers built around legacy code. Intermediate
50 : // representations of serialized data-structures should be stored in such
51 : // a way so as not to explicitly require access to the untransformed image.
52 : // Additionally, for checking validity a transform or orderer should require
53 : // no more than the PESignature associated with the original module, and/or
54 : // the toolchain metadata present in the module, if there was any.
55 : //
56 : // TODO(chrisha): Resimplify this API once Reorderer has been reworked to move
57 : // away from Block pointers.
58 :
59 : #ifndef SYZYGY_PE_PE_RELINKER_H_
60 : #define SYZYGY_PE_PE_RELINKER_H_
61 :
62 : #include <vector>
63 :
64 : #include "base/files/file_path.h"
65 : #include "syzygy/block_graph/orderer.h"
66 : #include "syzygy/block_graph/transform.h"
67 : #include "syzygy/pdb/pdb_mutator.h"
68 : #include "syzygy/pe/image_layout.h"
69 : #include "syzygy/pe/pe_coff_relinker.h"
70 : #include "syzygy/pe/pe_file.h"
71 : #include "syzygy/pe/pe_transform_policy.h"
72 :
73 : namespace pe {
74 :
75 : // Embodies a transformation on a PE image, from decomposing an original image
76 : // to applying some transform(s) to it, to generating the layout and finally
77 : // writing the image and accompanying PDB to disk.
78 : //
79 : // Creating a PERelinker and not changing its default configuration yields
80 : // an identity relinker that will produce an identical (nearly, except for
81 : // cosmetic differences in some headers) image to the input. If no orderers
82 : // are specified the default original orderer will be applied. If, in
83 : // addition, no transforms have been added this effectively makes the entire
84 : // relinker an identity relinker.
85 : //
86 : // The workflow is as follows:
87 : //
88 : // 1. Relinker created with an input image. The PDB file is found automatically
89 : // and the image is decomposed. Optionally the PDB may be directly specified.
90 : // 2. The image is transformed:
91 : // a) Transforms provided by the user are applied.
92 : // b) AddMetadataTransform is conditionally applied.
93 : // c) AddPdbInfoTransform is applied.
94 : // d) PrepareHeadersTransform is applied.
95 : // 3. The image is ordered:
96 : // a) Orderers provided by the user are applied.
97 : // b) PEOrderer is applied.
98 : // 4. PEImageLayoutBuilder is used to convert the OrderedBlockGraph to an
99 : // ImageLayout.
100 : // 5. Image and accompanying PDB file are written. (Filenames are inferred from
101 : // input filenames or directly specified.)
102 : class PERelinker : public PECoffRelinker {
103 : public:
104 : // Constructor.
105 : // @param pe_transform_policy The policy that dictates how to apply
106 : // transforms.
107 : explicit PERelinker(const PETransformPolicy* pe_transform_policy);
108 :
109 : // @see RelinkerInterface::image_format()
110 i : virtual ImageFormat image_format() const OVERRIDE { return PE_IMAGE; }
111 :
112 : // @name Accessors.
113 : // @{
114 E : const base::FilePath& input_pdb_path() const { return input_pdb_path_; }
115 E : const base::FilePath& output_pdb_path() const { return output_pdb_path_; }
116 E : bool add_metadata() const { return add_metadata_; }
117 E : bool augment_pdb() const { return augment_pdb_; }
118 E : bool compress_pdb() const { return compress_pdb_; }
119 E : bool strip_strings() const { return strip_strings_; }
120 E : bool use_old_decomposer() const { return use_old_decomposer_; }
121 E : size_t padding() const { return padding_; }
122 E : size_t code_alignment() const { return code_alignment_; }
123 : // @}
124 :
125 : // @name Mutators for controlling relinker behaviour.
126 : // @{
127 E : void set_input_pdb_path(const base::FilePath& input_pdb_path) {
128 E : input_pdb_path_ = input_pdb_path;
129 E : }
130 E : void set_output_pdb_path(const base::FilePath& output_pdb_path) {
131 E : output_pdb_path_ = output_pdb_path;
132 E : }
133 E : void set_add_metadata(bool add_metadata) {
134 E : add_metadata_ = add_metadata;
135 E : }
136 E : void set_augment_pdb(bool augment_pdb) {
137 E : augment_pdb_ = augment_pdb;
138 E : }
139 E : void set_compress_pdb(bool compress_pdb) {
140 E : compress_pdb_ = compress_pdb;
141 E : }
142 E : void set_strip_strings(bool strip_strings) {
143 E : strip_strings_ = strip_strings;
144 E : }
145 E : void set_use_old_decomposer(bool use_old_decomposer) {
146 E : use_old_decomposer_ = use_old_decomposer;
147 E : }
148 E : void set_padding(size_t padding) {
149 E : padding_ = padding;
150 E : }
151 E : void set_code_alignment(size_t alignment) {
152 E : code_alignment_ = alignment;
153 E : }
154 : // @}
155 :
156 : // @see RelinkerInterface::AppendPdbMutator()
157 : virtual bool AppendPdbMutator(pdb::PdbMutatorInterface* pdb_mutator) OVERRIDE;
158 :
159 : // @see RelinkerInterface::AppendPdbMutators()
160 : virtual bool AppendPdbMutators(
161 : const std::vector<pdb::PdbMutatorInterface*>& pdb_mutators) OVERRIDE;
162 :
163 : // Runs the initialization phase of the relinker. This consists of decomposing
164 : // the input image, after which the intermediate data accessors declared below
165 : // become valid. This should typically be followed by a call to Relink.
166 : //
167 : // @returns true on success, false otherwise.
168 : // @pre input_path and output_path must be set prior to calling this.
169 : // input_pdb_path and output_pdb_path may optionally have been set prior
170 : // to calling this.
171 : // @post input_pe_file and input_image_layout may be called after this.
172 : // @note This entrypoint is virtual for unittest/mocking purposes.
173 : virtual bool Init() OVERRIDE;
174 :
175 : // Runs the relinker, generating an output image and PDB.
176 : //
177 : // @returns true on success, false otherwise.
178 : // @pre Init must have been called successfully.
179 : // @note This entrypoint is virtual for unittest/mocking purposes.
180 : virtual bool Relink() OVERRIDE;
181 :
182 : // @name Intermediate data accessors.
183 : // @{
184 : // These accessors only return meaningful data after Init has been called. By
185 : // the time any transforms or orderers are being called, these will contain
186 : // valid data.
187 : //
188 : // TODO(chrisha): Clean these up as part of the API simplification after
189 : // all legacy code has been refactored.
190 : //
191 : // @pre Init has been successfully called.
192 E : const PEFile& input_pe_file() const { return input_pe_file_; }
193 : const GUID& output_guid() const { return output_guid_; }
194 : // @}
195 :
196 : protected:
197 : // The transform policy used by this relinker.
198 : const PETransformPolicy* pe_transform_policy_;
199 :
200 : base::FilePath input_pdb_path_;
201 : base::FilePath output_pdb_path_;
202 :
203 : // If true, metadata will be added to the output image. Defaults to true.
204 : bool add_metadata_;
205 : // If true, the PDB will be augmented with a serialized block-graph and
206 : // image layout. Defaults to true.
207 : bool augment_pdb_;
208 : // If true, then the augmented PDB stream will be compressed as it is written.
209 : // Defaults to false.
210 : bool compress_pdb_;
211 : // If true, strings associated with a block-graph will not be serialized into
212 : // the PDB. Defaults to false.
213 : bool strip_strings_;
214 : // If true we will use the old decomposer. Defaults to false.
215 : bool use_old_decomposer_;
216 : // Indicates the amount of padding to be added between blocks. Zero is the
217 : // default value and indicates no padding will be added.
218 : size_t padding_;
219 : // Minimal code block alignment.
220 : size_t code_alignment_;
221 :
222 : // The vectors of user supplied transforms, orderers and mutators to be
223 : // applied.
224 : std::vector<pdb::PdbMutatorInterface*> pdb_mutators_;
225 :
226 : // Intermediate variables that are initialized and used by Relink. They are
227 : // made externally accessible so that transforms and orderers may make use
228 : // of them if necessary.
229 :
230 : // These refer to the original image, and don't change after init.
231 : PEFile input_pe_file_;
232 :
233 : // These are for the new image that will be produced at the end of Relink.
234 : GUID output_guid_;
235 : };
236 :
237 : } // namespace pe
238 :
239 : #endif // SYZYGY_PE_PE_RELINKER_H_
|