Download the PHP package yohgaki/validate-php-scr without Composer

"Validate" for PHP - An INPUT data validation framework

"Validate" is "input data validation framework" that is developed to be useful for "CERT Secure Coding" and "Design by Contract"(DbC). "Validate" is designed to develop OWASP TOP 10 A10:2017 vulnerability compliant application. "Validate" is planned to be implemented as C module for PHP.

CERT Top 10 Secure Coding Practices.

1. Validate input. Validate input from all untrusted data sources. Proper input validation can eliminate the vast majority of software vulnerabilities. Be suspicious of most external data sources, including command line arguments, network interfaces, environmental variables, and user controlled files [Seacord 05].

Validate for PHP is designed to help "Standard Input Validation".

Use a standard input validation mechanism to validate all input for:

• length
• type of input
• syntax
• missing or extra inputs
• consistency across related fields
• business rules

Basic Design

• Framework - "Validate" is a framework, not an out-of-the-box library by itself. Provides easy, yet flexible input data validations.
• Secure - No insecure defaults. Everything has to be specified explicitly. i.e. White list.
• Fast & Simple - Define data validation rules and use them. No code execution for building validation rules.
• Easy to use - Simple PHP array rule specification. Plain PHP code for complex inputs.
• Native type - Returns natively typed data by default. Eliminates type conversions and helps faster PHP code execution with type hints.

"Validate" is very flexible and able to perform any data validations, including HTTP header/Query parameter validations with multi stage validations, HTML form validations, JSON data validations, etc. Although "Validate" is designed to validate all inputs at once, you may validate values one by one also.

"Strings" are the most important for input validations and "Validate" is strict for string validations. Many apps miss to validate "char encodings" and "length". "Validate" forces them to be validated always by default. "Validate" does not allow Unicode control characters which cause problems by default.

Requirements

• PHP 8.0 and up.
• BCMath module.

Recommended

• PHP 7.2 and up - Newer mbstring provides better performance.
• mbstring module - mb_ord() improves performance, more supported encodings and better encoding checks.
• GMP module - "Validate" supports GMP integer also.

Basic Behaviors

• validate() does not allow anything unless explicitly specified. i.e. Strictly white listing.
• validate() converts input values to native types when it is possible. e.g. '123' to int. 'yes'/'no' to bool.
• validate() processes input values and validation specs recursively. i.e. Any input values (scalar/array/object) are accepted.
• validate() checks validation spec format by default. i.e. Disable spec format check for production.
• validate() stores validation statuses to context. e.g. $ctx in examples below.
• validate() throws InvalidArgumentException by default.

Tip:

• For application business logic data validations, disable exception and set 'error_message' option.
• Define your own 'filter' for normalization.
• Define your own 'key_callback' for custom array key validations.
• Use VALIDATE_CALLBACK and 'callback' for complex validations.

Example #1: Single value validation with exception

src/examples/91-example.php

Validation error results in Exception. Application input data validation errors should be handled by exception without user interaction.

NOTE: Valid inputs are any inputs that the application is supposed to handle. i.e. Input mistakes are valid inputs for an application.

Example #2: Single value validation without exception

src/examples/92-example.php

Validation errors are stored in $ctx. Application business logic data validation errors should be handled without error/exception for interactive error handling.

Example #3: Multiple value validations at once.

src/examples/93-example.php

"Validate" removes validated elements from $inputs. You can validate remaining elements by next validation.

A little more realistic working example is here:

• https://sample.ohgaki.net/validate-php/validate-php-scr/src/examples/99-web.php

Example #4: Validation that validates all HTTP headers

src/examples/94-example.php

OWASP TOP 10 A10:2017 requires to validate all inputs. Although you are better to do stricter validations against headers, this validation is OWASP TOP 10 A10:2017 compliant HTTP request header validation.

Example #5: Validate all HTTP inputs ($_GET / $_POST / $_COOKIE / $_FILES) at once

A realistic user-registration form receives data from multiple superglobals: a CSRF token in $_GET, the form fields in $_POST, a session identifier in $_COOKIE, and an avatar upload in $_FILES. All of them are untrusted and must be validated. "Validate" can verify the entire request in a single validate() call by nesting per-source specs under one VALIDATE_ARRAY spec.

Key points:

• One call per request. Nesting VALIDATE_ARRAY specs lets you validate every HTTP source in a single validate() call, so no input bypasses the trust boundary.
• min/max reject extra and missing keys. Unknown $_POST fields or extra cookies become validation errors instead of being silently passed through.
• $_FILES is just a nested array. Each upload's 5 keys (name, type, tmp_name, error, size) are validated like any other parameter; whitelist type against allowed MIME types and bound size explicitly. Do not trust type for security decisions — always re-check the uploaded file's content with finfo_file() before storing or serving it.
• Use validate_get_user_errors($ctx) for the form, and let the application reject "impossible" inputs (wrong types, oversized strings) fast with no user-facing message, per the "FAIL FAST" principle.

"APPLICATION INPUT" and "BUSINESS LOGIC" Data Validation Basics

APPLICATION INPUT data validation and BUSINESS LOGIC data validation are 2 different validations.

APPLICATION INPUT Data Validation

IMPORTANT: User mistakes are valid inputs.

APPLICATION INPUT data should be validated as fast as it can to minimize misbehavior/vulnerability. Application INPUT data validation must validate all inputs are valid for the application. i.e. If ID is number between 1000 and INT_MAX, then you must only accepts number 1000 from INT_MAX. If a string is for names, then the string should never exceed 512 bytes unless attacker is tampering your application. If your application restricts name length to 100 by client side JavaScript, then you should never accept strings longer than 100. Do not forget to check too few/many parameters as this is one of a "standard input validation" requirement.

All of application input data must be validated and validations should be done at Application Trust Boundary. Application INPUT data validation assures "Values have correct forms". e.g. length, range, encoding, used chars, specific formats such as date, phone, zip. Both Correct and "Input mistake" values are valid input data.

Application INPUT data validation failure MUST NOT require user interactions. INPUT data validation failure means "A user sent Invalid values.(= values clients cannot/should not send. unacceptable values. e.g. Too large, broken char encoding, malformed format/char, etc). These invalid inputs MUST simply be rejected and handled according to "FAIL FAST" principle. i.e. Reject invalid inputs like WAF(Web Application Firewall) does. All inputs, including HTTP headers/query parameters, must be validated always.

Input data format correctness must be validated by server always AND the validation must be done as fast as it can. Input data validation should not require user interaction, should not provide meaningful error message (to attackers).

BUSINESS LOGIC Data Validation

IMPORTANT: Detecting broken/totally wrong/invalid inputs at business logic code is too late. It is good for "fail safe", but "fail safe" is not an ideal security measure.

BUSINESS LOGIC data validation is for input mistake detection that users allowed to, not for totally broken inputs sent from crackers. Business logic (e.g. Model in MVC) should not supposed to handle totally wrong input value (e.g. number is expected, but string is supplied) because totally wrong values should be handled by APPLICATION INPUT validation already.

Application BUSINESS LOGIC data validation validates values against business logic. e.g. Reservation date is future date, min value is less than max value, has valid CSRF token, etc. BUSINESS LOGIC data validations are responsible for logical correctness mainly.

Unlike Application INPUT data validations, many BUSINESS LOGIC data validations require user interactions to correct input mistakes.

Logical data correctness must be validated by server always. Business logic validation usually requires user interaction and/or should provide meaningful error message what went wrong.

References

• Input and business logic validations are 2 different validations. OWASP Code Review Guide - Section 7.6 Input Validation, for details.
• INPUT validation failure must not simply ignored. 2017 OWASP TOP 10 - "A10 Insufficient Logging & Monitoring".
• Input data validation is the most powerful security measure. CWE/SANS Top 25 - Monster mitigations.
• Input data validation is the first Secure Coding principle. CERT TOP 10 Secure Coding Practices

Documents

Reference.

• REFERENCE.md

Examples.

• Examples and Tests

Codes.

• validate() and other function definitions are in validate_func.php
• Validator behavior is defined in Validate.php
• Validator flags is defined in validate_defs.php

Status

• Pre Alpha
• Please test drive and report bugs.

TODO

• Add Unicode validations. e.g. RFC 3454, .NET like UnicodeCategory (RFC 3454 C check is implemented. Whitelist may be implemented in C module from Unicode standard char definition XML. RFC 3454 C check makes string validation 6 times slower already.)
• More tests. (Most features are tested.)
• Back port this to C module - When API is fixed. (TODO: Cleanup, Optimize, Reorganize PHP code for C implementation.)
• Spec builder app(?).
• Learning and automatic spec builder tool(?).

Input Data Security Tip

Strings are the most risky inputs and web apps are made by string inputs. i.e. Almost all inputs to web apps are strings. Invalid strings must not be processed by web apps' code at all.

While most web apps do not validate input string character encoding, web developers must validate character encodings. If you don't validate character encoding, your application became vulnerable to DoS easily. i.e. htmlspecialchars() return empty string, modern browsers refuse to render badly broken encoding, system has both binary safe and encoding aware APIs/storages. These facts create very hard to find DoS vulnerabilities.

In order to programs to work correctly, valid data is absolute mandatory requirement. Invalid data for program results in invalid state always.

Some apps/libraries sanitize input data and make "invalid data" into "valid data" because "valid data" is mandatory. However sanitization ignores and hides attacks from cyber criminals. Ignoring and hiding attacks is insecure practice should be avoided. Developers must not rely on sanitizer in general.

Extending

Since "Validate" is designed as framework, it is easy to extend. It can work with other validators such as Respect.

"src/tools" directory contains tools that request logging, creating validation spec rules from log and validation script.

"Validate" C extension module

This PHP script is based on validate C module for PHP 7. Features are planned to be ported to C module which can perform validations a lot faster.

https://github.com/yohgaki/validate-php (Do not use this. Use PHP script version for now.)

Comments & Issues

Comments, Bug reports and PRs are welcomed! Please remember "Validate" is not optimized for OO nor PHP scripts, but C module. This script is planned to be implemented as a C module in the future.