Configuration basics

Byteguard.FileValidator uses a simple configuration class to configure validation parameters, though with the possibility of using the fluent API configuration builder FileValidatorConfigurationBuilder.

Manuel instantiation

Manually instantiating the configuration class is as simple as simply instantiating it with the proper values.

var configuration = new FileValidatorConfiguration
{
    SupportedFileTypes = [FileExtensions.Pdf, FileExtensions.Jpg, FileExtensions.Jpeg, FileExtensions.Png],
    FileSizeLimit = ByteSize.MegaBytes(25),
    ThrowExceptionOnInvalidFile = false
};

Using the fluent API builder

The fluent configuration API builder is a simple helper class to instantiate the configuration instance.

var configuration = new FileValidatorConfigurationBuilder()
    .AllowFileTypes(FileExtensions.Pdf, FileExtensions.Jpg, FileExtensions.jpg, FileExtensions.Png)
    .SetFileSizeLimit(ByteSize.MegaBytes(25))
    .SetThrowExceptionOnInvalidFile(false)
    .Build();

Configuration options

The file validator can be configured to suit your needs with the following available configurations:

• Supported file types
• File size limit
• Exception vs. boolean return values

As this package is built with the principle "secure-by-default" in mind, none of the options has any default values. This might seem counter-intuitive, but this ensures that the file validator does not support file types you do not expect nor does it have a default file size limit, as that's completely up to you to decide.

Supported file types

SupportedFileTypes lets you define what extensions you are willing to accept in your application. Any file extensions received that does not match the supported file types will be considered invalid.

The following file types are currently supported:

• Images
  • Joint Photographic Experts Group (.jpeg, .jpg, jpe)
  • Portable Network Graphics (.png)
  • Bitmap (.bmp)
• Documents
  • Portable Document Format (.pdf)
  • Microsoft Word Document (.doc)
  • Microsoft Word Open XML Document (.docx)
  • OpenDocument Text (.odt)
  • Rich Text Format (.rtf)
• Spreadsheets
  • Microsoft Excel Spreadsheet (.xls)
  • Microsoft Excel Open XML Spreadsheet (.xlsx)
• Presentations
  • Microsoft PowerPoint Open XML Presentation (.pptx)
• Audio
  • MPEG-4 Audio (.m4a)
  • MP3 Audio (.mp3)
  • Waveform Audio File Format (.wav)
• Video
  • Apple QuickTime Movie (.mov)
  • Audio Video Interleave (.avi)
  • MPEG-4 Video (.mp4)

File signature validation

The file validator does not only verify that the extensions matches any of the supported, but also validates the file signature (also known as the magic-number or magic-bytes).

Whenever a file is validated, the file validator ensures that the file signature matches the expected file type. For example, if the file extension is a .jpg or .jpeg, the first 3 bytes is expected to be FF D8 FF (ASCII value: ÿØÿ).

The file signature check is not enough in terms of ZIP-based file formats such as .docx, .xlsx and .pptx. In these scenarios, the expected signature is the same as a ZIP-archive (first 4 bytes 50 4B 03 04, ASCII: PK␃␄), hence why these functions IsValidOpenXmlFormat() and IsValidOpenDocumentFormat() exists.

The file signature validation for PDF-files is different as well, as PDF files are simply expected to have the file signature 25 50 44 46 2D (ASCII: %PDF-) somewhere within the first 1024 bytes. This is supported by the file validator.

⚠️ WARNING: PDF files can include embedded files and/or JavaScript. If you do not want to support JavaScript, most PDF viewers today support disabling JavaScript from PDF-files.

File size limit

The file validator includes an options to set the max file size limit of files is receives to validate using FileSizeLimit. This value has no default and if not set, the file validator with throw an exception on instantiation. It is expected that you as a developer, decide on the limit value.

Exception vs. boolean return value

When validating files using the file validator, you have 2 options in terms of response type using the options ThrowExceptionOnInvalidFile:

• false: boolean return values
• true: throw exceptions when an invalid file has been encountered

By default, the file validator will throw an appropriate exception whenever an invalid file has been encountered, but this can be disabled by setting the option to false.

If true, any of the following exceptions may be thrown during validation:

Exception type	Scenario
EmptyFileException	Thrown when the file content is null or empty, indicating a file without any content.
UnsupportedFileException	Thrown when the file extension is not in the list of supported types.
InvalidFileSizeException	Thrown when the file size exceeds the configured file size limit.
InvalidSignatureException	Thrown when the file's signature does not match the expected signature for its type.
InvalidOpenXmlFormatException	Thrown when the internal structure of an Open XML file is invalid (.docx, .xlsx, .pptx, etc.).
InvalidOpenDocumentFormatException	Thrown when the specification conformance of an Open Document Format file is invalid (.odt, etc.).
MalwareDetectedException	Thrown when the configured antimalware scanner detected malware in the file from a scan result.