This article explains how to ensure information about the RadAsyncUpload configuration is secure and non-readable. Its transmission between the client and the server must be encrypted and impossible to decode, so the data cannot be used by a malicious entity in an attack against the server.
Configuration information includes temporary and target folder on the server, allowed file extensions and the type of the file metadata object (by default, a class from the Telerik.Web.UI.dll assembly).
This article contains the following sections:
- Recommended Settings
- Configuration Keys Details
There are three
appSettings keys you should add to your
web.config to ensure information security with file uploads:
Set a custom
Set a custom
Telerik.Upload.AllowedCustomMetaDataTypeskey. Check the Metadata Type Whitelisting section to avoid any breaking changes.
<appSettings> <add key="Telerik.AsyncUpload.ConfigurationEncryptionKey" value="YOUR-FIRST-UNIQUE-STRONG-RANDOM-VALUE-UNIQUE-TO-YOUR-APP&" /> <add key="Telerik.Upload.ConfigurationHashKey" value="YOUR-SECOND-UNIQUE-STRONG-RANDOM-VALUE-UNIQUE-TO-YOUR-APP&" /> <add key="Telerik.Upload.AllowedCustomMetaDataTypes" value="Telerik.Web.UI.AsyncUploadConfiguration" /> </appSettings>
In case you do not use RadAsyncUpload, you can disable file uploads for your application via the Telerik.Web.DisableAsyncUploadHandler key web.config switch. This feature is available as of R2 2017 SP2.
The information below provides more details on the available keys and their usage.
If you do not set custom encryption and hashing keys, default (hardcoded) values are used to encrypt/decrypt the information for versions prior to R2 2017 SP1. If you are using such an old version, we recommend upgrading to the latest.
As of R2 2017 SP1, hardcoded keys are not used anymore. Instead, standard .NET methods are used for encryption. Nevertheless, you should still set your own unique custom keys.
Other cryptographic operations in the UI for ASP.NET AJAX suite may also use these two keys. Telerik avoids adding more keys in order to improve backwards compatibility of your applications and to reduce the number of properties you have to set.
To provide secure encryption of the control configuration, we strongly advise that you set a custom encryption key for
<appSettings> <add key="Telerik.AsyncUpload.ConfigurationEncryptionKey" value="YOUR-FIRST-UNIQUE-STRONG-RANDOM-VALUE-UNIQUE-TO-YOUR-APP&" /> </appSettings>
Telerik.AsyncUpload.ConfigurationEncryptionKey is available as of Q3 2012 SP1 (version 2012.3.1205).
As of R1 2017, the Encrypt-then-MAC approach is implemented, in order to improve the integrity of the encrypted temporary and target folders.
Telerik.Upload.ConfigurationHashKey key is used to hash the encrypted text. The value returned from the client is checked in the upload handler for integrity. If the hashing attempt is incorrect, a
new CryptographicException("The hash is not valid!"); exception will be thrown.
<appSettings> <add key="Telerik.Upload.ConfigurationHashKey" value="YOUR-SECOND-UNIQUE-STRONG-RANDOM-VALUE-UNIQUE-TO-YOUR-APP&" /> </appSettings>
As of R3 2019 SP1, the metadata classes (upload configurations) can be whitelisted. That allows the application to use only the metadata classes from a whitelisted collection of configurations.
As of R1 2020 this feature is enabled by default to improve the application security, and allows the built-in Telerik type only. In R3 2019 SP1 the feature is opt-in. If you add any types, you must add all types that you use, otherwise those that are not whitelisted will throw a The cryptographic operation has failed! error when uploading.
There are several situations when you may be using a custom metadata class, you can read more on the most common cases in the following resources. This can help you determine whether you have such code in your application for any purpose. If you do, read the information after this list to see how to apply whitelisting for them.
- Sending custom information to and from a custom handler
- Capturing file upload errors from a custom handler
- Preserving upload configuration across postbacks
To whitelist your custom types, add the
Telerik.Upload.AllowedCustomMetaDataTypes key in the
appSettings section of the
web.config. As a value for the key, provide the metadata class full name, including the namespace, in a list delimited by a semicolon (
;). The built-in type that we use out-of-the-box is always whitelisted. For an easy way to obtain the fully qualified name of the configuration class you need to add, check the example in the following KB article:
<appSettings> <add key="Telerik.Upload.AllowedCustomMetaDataTypes" value="SomeNameSpace.SampleAsyncUploadConfiguration;SomeOtherNameSpace.OtherAsyncUploadConfiguration" /> </appSettings>
This is an additional security measure and it does not replace setting the main custom encryption keys.
Failure to deserialize a custom metadata type will also throw a
CryptographicException on the server and the handler request will fail, resulting in a
The cryptographic operation has failed! error on the client.
Custom handlers are affected by this feature.
You can disable file uploads through RadAsyncUpload's built-in configuration altogether. This feature is available as of R2 2017 SP2 (2017.2.711).
Telerik.Web.DisableAsyncUploadHandler key to
true disables the built-in RadAsyncUpload handler that is used for storing files in the temporary folder before they are moved to the target folder.
When you set this key to
true, no files can be uploaded to the default handler (
Custom handlers are not affected by this feature and you can still use them to upload and save files with the desired level of security.
<appSettings> <add key="Telerik.Web.DisableAsyncUploadHandler" value="true"/> </appSettings>
Even when disabling file uploads, we recommend setting the main custom encryption keys, especially for versions prior to R3 2019 SP1.