Skip to content

Commit b820df6

Browse files
boriskatinboriskatin
committed
Merge branch 'staging'
2 parents 77cca1f + 4876758 commit b820df6

1 file changed

Lines changed: 139 additions & 20 deletions

File tree

‎net/developer-guide/advanced-usage/loading/skip-external-resources.md‎

Lines changed: 139 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -9,19 +9,45 @@ productName: GroupDocs.Conversion for .NET
99
hideChildren: False
1010
toc: True
1111
---
12+
1213
## What are external resources?
14+
1315
*External resources* refer to various types of content or files that are not directly embedded within the document but are instead referenced and loaded from external locations. These resources enhance the functionality, appearance, and interactivity of the document. Common external resources include images, audio, video, fonts, CSS, scripts, frameworks, and so on. **GroupDocs.Conversion** considers external any resource that a document is trying to load from an external URL.
1416

1517
Utilizing external resources optimizes the performance, maintainability, and scalability of web pages and other documents. These resources are typically cached by browsers, which can reduce the load time of subsequent visits to a website. However, relying too heavily on external resources can also introduce dependencies and potential points of failure if the external sources become unavailable.
1618

17-
## Restricting all external resources
18-
While loading [web]({{< ref "conversion/net/developer-guide/advanced-usage/loading/load-options-for-different-document-types/load-markup-document-with-options.md" >}}), [presentations]({{< ref "conversion/net/developer-guide/advanced-usage/loading/load-options-for-different-document-types/load-presentation-document-with-options.md" >}}) and [word-processing]({{< ref "conversion/net/developer-guide/advanced-usage/loading/load-options-for-different-document-types/load-wordprocessing-document-with-options.md" >}}) documents, the [**GroupDocs.Conversion**](https://products.groupdocs.com/conversion/net) allows skipping of loading the external resources.
19+
## Security considerations
20+
21+
Loading external resources from untrusted documents can pose security risks:
22+
23+
* **Server-Side Request Forgery (SSRF)**: A malicious document could contain references to internal network resources, potentially allowing attackers to probe or access internal services.
24+
* **NTLM credential leaks**: Documents with UNC paths (e.g., `\\server\share`) could trigger automatic NTLM authentication, potentially leaking credentials.
25+
* **Data exfiltration**: External resources could be used to track document access or exfiltrate data.
26+
27+
To mitigate these risks, [**GroupDocs.Conversion**](https://products.groupdocs.com/conversion/net) implements a **secure by default** approach - the `SkipExternalResources` property is set to `true` by default in all supporting load options classes.
28+
29+
## Supported document types
1930

20-
To restrict the loading of external resources during the conversion, use the `SkipExternalResources` boolean property of the respective [WebLoadOptions](https://reference.groupdocs.com/conversion/net/groupdocs.conversion.options.load/webloadoptions), [PresentationLoadOptions](https://reference.groupdocs.com/conversion/net/groupdocs.conversion.options.load/presentationloadoptions), or [WordProcessingLoadOptions](https://reference.groupdocs.com/conversion/net/groupdocs.conversion.options.load/wordprocessingloadoptions) class.
31+
The external resource loading control is available for the following document types:
2132

22-
The following code snippet shows how to skip loading of external resources while loading an HTML document:
33+
| Document Type | LoadOptions Class |
34+
|---------------|-------------------|
35+
| Web/HTML | [WebLoadOptions](https://reference.groupdocs.com/conversion/net/groupdocs.conversion.options.load/webloadoptions) |
36+
| Word Processing | [WordProcessingLoadOptions](https://reference.groupdocs.com/conversion/net/groupdocs.conversion.options.load/wordprocessingloadoptions) |
37+
| Presentations | [PresentationLoadOptions](https://reference.groupdocs.com/conversion/net/groupdocs.conversion.options.load/presentationloadoptions) |
38+
| Spreadsheets | [SpreadsheetLoadOptions](https://reference.groupdocs.com/conversion/net/groupdocs.conversion.options.load/spreadsheetloadoptions) |
39+
| Email | [EmailLoadOptions](https://reference.groupdocs.com/conversion/net/groupdocs.conversion.options.load/emailloadoptions) |
40+
| SVG | [SvgLoadOptions](https://reference.groupdocs.com/conversion/net/groupdocs.conversion.options.load/svgloadoptions) |
2341

24-
With v24.10 and later:
42+
All these classes implement the [IResourceLoadingOptions](https://reference.groupdocs.com/conversion/net/groupdocs.conversion.options.load/iresourceloadingoptions) interface, which defines the `SkipExternalResources` and `WhitelistedResources` properties.
43+
44+
## Restricting external resources
45+
46+
By default, `SkipExternalResources` is set to `true`, which means external resources are already blocked. If you have previously enabled external resource loading and want to restrict it again, set the `SkipExternalResources` property to `true`.
47+
48+
The following code snippets show how to skip loading of external resources for different document types:
49+
50+
### Web/HTML documents
2551

2652
```csharp
2753
using GroupDocs.Conversion;
@@ -39,32 +65,103 @@ using (var converter = new Converter("sample.html", (LoadContext loadContext) =>
3965
}
4066
```
4167

68+
### Word processing documents
69+
70+
```csharp
71+
using GroupDocs.Conversion;
72+
using GroupDocs.Conversion.Options.Convert;
73+
using GroupDocs.Conversion.Options.Load;
74+
75+
var loadOptions = new WordProcessingLoadOptions
76+
{
77+
SkipExternalResources = true
78+
};
79+
using (var converter = new Converter("sample.docx", (LoadContext loadContext) => loadOptions))
80+
{
81+
var options = new PdfConvertOptions();
82+
converter.Convert("converted.pdf", options);
83+
}
84+
```
85+
86+
### Presentation documents
87+
88+
```csharp
89+
using GroupDocs.Conversion;
90+
using GroupDocs.Conversion.Options.Convert;
91+
using GroupDocs.Conversion.Options.Load;
92+
93+
var loadOptions = new PresentationLoadOptions
94+
{
95+
SkipExternalResources = true
96+
};
97+
using (var converter = new Converter("sample.pptx", (LoadContext loadContext) => loadOptions))
98+
{
99+
var options = new PdfConvertOptions();
100+
converter.Convert("converted.pdf", options);
101+
}
102+
```
42103

43-
Before v24.10:
104+
### Spreadsheet documents
44105

45106
```csharp
46107
using GroupDocs.Conversion;
47108
using GroupDocs.Conversion.Options.Convert;
48109
using GroupDocs.Conversion.Options.Load;
49110

50-
var loadOptions = new WebLoadOptions
111+
var loadOptions = new SpreadsheetLoadOptions
112+
{
113+
SkipExternalResources = true
114+
};
115+
using (var converter = new Converter("sample.xlsx", (LoadContext loadContext) => loadOptions))
116+
{
117+
var options = new PdfConvertOptions();
118+
converter.Convert("converted.pdf", options);
119+
}
120+
```
121+
122+
### Email documents
123+
124+
```csharp
125+
using GroupDocs.Conversion;
126+
using GroupDocs.Conversion.Options.Convert;
127+
using GroupDocs.Conversion.Options.Load;
128+
129+
var loadOptions = new EmailLoadOptions
130+
{
131+
SkipExternalResources = true
132+
};
133+
using (var converter = new Converter("sample.eml", (LoadContext loadContext) => loadOptions))
134+
{
135+
var options = new PdfConvertOptions();
136+
converter.Convert("converted.pdf", options);
137+
}
138+
```
139+
140+
### SVG documents
141+
142+
```csharp
143+
using GroupDocs.Conversion;
144+
using GroupDocs.Conversion.Options.Convert;
145+
using GroupDocs.Conversion.Options.Load;
146+
147+
var loadOptions = new SvgLoadOptions
51148
{
52149
SkipExternalResources = true
53150
};
54-
using (var converter = new Converter("sample.html", () => loadOptions))
151+
using (var converter = new Converter("sample.svg", (LoadContext loadContext) => loadOptions))
55152
{
56153
var options = new PdfConvertOptions();
57154
converter.Convert("converted.pdf", options);
58155
}
59156
```
60157

61-
## Allowlisting some of the external resources
62-
Sometimes you may want to skip loading most of the external resources, but still load some particular resources.
63-
To allow-list specific resources during the conversion, use the `WhitelistedResources` property of the respective [WebLoadOptions](https://reference.groupdocs.com/conversion/net/groupdocs.conversion.options.load/webloadoptions), [PresentationLoadOptions](https://reference.groupdocs.com/conversion/net/groupdocs.conversion.options.load/presentationloadoptions), or [WordProcessingLoadOptions](https://reference.groupdocs.com/conversion/net/groupdocs.conversion.options.load/wordprocessingloadoptions) class. The property is effective when the `SkipExternalResources` property is enabled. The `WhitelistedResources` property accepts the string list containing the portions of URLs to be loaded while restricting the loading of other external resources.
158+
## Allowlisting specific external resources
159+
160+
Sometimes you may want to skip loading most of the external resources, but still load some particular resources from trusted sources.
64161

65-
The following code snippet shows how to load the JPG and JPEG images and any resources from the `example.com` domain while restricting any other external resources:
162+
To allow-list specific resources during the conversion, use the `WhitelistedResources` property. This property accepts a list of strings containing portions of URLs to be allowed. The `WhitelistedResources` property is effective only when the `SkipExternalResources` property is set to `true`.
66163

67-
With v24.10 and later:
164+
The following code snippet shows how to load JPG and JPEG images and any resources from the `example.com` domain while restricting all other external resources:
68165

69166
```csharp
70167
using GroupDocs.Conversion;
@@ -73,8 +170,8 @@ using GroupDocs.Conversion.Options.Load;
73170

74171
var loadOptions = new WebLoadOptions
75172
{
76-
SkipExternalResources = true,
77-
WhitelistedResources = new List<string>() { "jpg", "jpeg", "example.com" }
173+
SkipExternalResources = true,
174+
WhitelistedResources = new List<string> { "jpg", "jpeg", "example.com" }
78175
};
79176
using (var converter = new Converter("sample.html", (LoadContext loadContext) => loadOptions))
80177
{
@@ -83,7 +180,30 @@ using (var converter = new Converter("sample.html", (LoadContext loadContext) =>
83180
}
84181
```
85182

86-
Before v24.10:
183+
The same approach works for all supported document types. For example, to allow specific resources when converting an email document:
184+
185+
```csharp
186+
using GroupDocs.Conversion;
187+
using GroupDocs.Conversion.Options.Convert;
188+
using GroupDocs.Conversion.Options.Load;
189+
190+
var loadOptions = new EmailLoadOptions
191+
{
192+
SkipExternalResources = true,
193+
WhitelistedResources = new List<string> { "trusted-domain.com", ".png", ".jpeg" }
194+
};
195+
using (var converter = new Converter("newsletter.eml", (LoadContext loadContext) => loadOptions))
196+
{
197+
var options = new PdfConvertOptions();
198+
converter.Convert("converted.pdf", options);
199+
}
200+
```
201+
202+
Resources matching any entry in the whitelist will be loaded normally, while all other external resources will be skipped.
203+
204+
## Enabling external resources loading
205+
206+
If you need to load all external resources (not recommended for untrusted documents), set `SkipExternalResources` to `false`:
87207

88208
```csharp
89209
using GroupDocs.Conversion;
@@ -92,12 +212,11 @@ using GroupDocs.Conversion.Options.Load;
92212

93213
var loadOptions = new WebLoadOptions
94214
{
95-
SkipExternalResources = true,
96-
WhitelistedResources = new List<string>() { "jpg", "jpeg", "example.com" }
215+
SkipExternalResources = false
97216
};
98-
using (var converter = new Converter("sample.html", () => loadOptions))
217+
using (var converter = new Converter("trusted-document.html", (LoadContext loadContext) => loadOptions))
99218
{
100219
var options = new PdfConvertOptions();
101220
converter.Convert("converted.pdf", options);
102221
}
103-
```
222+
```

0 commit comments

Comments
 (0)