[skip ci][doc] start security module

docs/index.rst

@@ -15,6 +15,7 @@ Ubiquity User guide
 
 .. sidebar:: New in documentation
 
+   - :ref:`Security<security>`
    - :ref:`Async platforms<async>`
    - :ref:`Commands module<commands>`
    - :ref:`Composer module<composer>`
@@ -104,6 +105,14 @@ Ubiquity User guide
    contents/transformers
    translation/index
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Security
+
+   security/index
+   security/module
+   security/acl
+
 .. toctree::
    :maxdepth: 1
    :caption: Rest

docs/model/db.rst

@@ -43,11 +43,11 @@ In some cases, however, it may be useful to make an explicit connection to the d
     use Ubiquity\controllers\Startup;
     ...
     try{
-    	$config=\Ubiquity\controllers\Startup::getConfig();
-    	DAO::startDatabase($config);
-    	$users=DAO::getAll(User::class,'');
+        $config=\Ubiquity\controllers\Startup::getConfig();
+        DAO::startDatabase($config);
+        $users=DAO::getAll(User::class,'');
     }catch(Exception $e){
-    	echo $e->getMessage();
+        echo $e->getMessage();
     }
 
 
@@ -72,7 +72,7 @@ Define the connection configuration parameters:
    :class: bordered
 
 Generate models for the new connection:|br|
-The generated models include the ``@database`` annotation mentioning their link to the connection.
+The generated models include the ``@database`` annotation or the ``Database`` attribute mentioning their link to the connection.
 
 
 .. tabs::
@@ -83,10 +83,11 @@ The generated models include the ``@database`` annotation mentioning their link
 
         <?php
         namespace models\tests;
-        /**
-         * @database('tests')
-         * @table('groupe')
-         */
+        use Ubiquity\attributes\items\Database;
+        use Ubiquity\attributes\items\Table;
+
+        #[Database('tests')]
+        #[Table('groupe')]
         class Groupe{
             ...
         }
@@ -97,11 +98,10 @@ The generated models include the ``@database`` annotation mentioning their link
 
         <?php
         namespace models\tests;
-        use Ubiquity\attributes\items\Database;
-        use Ubiquity\attributes\items\Table;
-
-        #[Database('tests')]
-        #[Table('groupe')]
+        /**
+         * @database('tests')
+         * @table('groupe')
+         */
         class Groupe{
             ...
         }

docs/security/acl.rst

@@ -0,0 +1,6 @@
+ACL management
+**************
+
+.. |br| raw:: html
+
+   <br />

docs/security/index.rst

@@ -0,0 +1,145 @@
+.. _security:
+Security
+********
+
+.. |br| raw:: html
+
+   <br />
+
+Guiding principles
+==================
+Forms validation
+----------------
+Client-side validation
+^^^^^^^^^^^^^^^^^^^^^^
+It is preferable to perform an initial client-side validation to avoid submitting invalid data to the server.
+
+Example of the creation of a form in the action of a controller (this part could be located in a dedicated service for a better separation of layers):
+.. code-block:: php
+   :linenos:
+   :caption: app/controllers/UsersManagement.php
+    public function index(){
+        $frm=$this->jquery->semantic()->dataForm('frm-user',new User());
+        $frm->setFields(['login','password','connection']);
+        $frm->fieldAsInput('login',
+            ['rules'=>'empty']
+        );
+        $frm->fieldAsInput('password',
+            [
+                'inputType'=>'password',
+                'rules'=>['empty','minLength[6]']
+            ]
+        );
+        $frm->setValidationParams(['on'=>'blur','inline'=>true]);
+        $frm->fieldAsSubmit('connection','fluid green','/submit','#response');
+        $this->jquery->renderDefaultView();
+    }
+
+The Associated View:
+.. code-block:: html+twig
+   :caption: app/views/UsersManagement/index.html
+    {{ q['frm-user'] | raw }}
+    {{ script_foot | raw }}
+    <div id="response"></div>
+
+.. image:: /_static/images/security/bases/frm-user.png
+   :class: bordered
+
+.. tip:: The CRUD controllers automatically integrate this client-side validation using the Validators attached to the members of the models.
+
+.. code-block:: php
+
+   #[Column(name: "password",nullable: true,dbType: "varchar(255)")]
+   #[Validator(type: "length",constraints: ["max"=>20,"min"=>6])]
+   #[Transformer(name: "password")]
+   private $password;
+
+Server-side validation
+^^^^^^^^^^^^^^^^^^^^^^
+It is preferable to restrict the URLs allowed to modify data.
+Beforehand, by specifying the Http method in the routes, and by testing the request :
+
+.. code-block:: php
+
+   #[Post(path: "/submit")]
+   public function submitUser(){
+      if(!URequest::isCrossSite() && URequest::isAjax()){
+         $datas=URequest::getPost();//post with htmlEntities
+         //Do something with $datas
+      }
+   }
+
+.. tips:: The **Ubiquity-security** module offers additional control to avoid cross-site requests.
+
+After modifying an object, it is possible to check its validity, given the validators attached to the members of the associated Model:
+
+.. code-block:: php
+
+   #[Post(path: "/submit")]
+   public function submitUser(){
+      if(!URequest::isCrossSite() && URequest::isAjax()){
+         $datas=URequest::getPost();//post with htmlEntities
+         $user=new User();
+         URequest::setValuesToObject($user,$datas);
+         $violations=ValidatorsManager::validate($user);
+         if(\count($violations)==0){
+            //do something with this valid user
+         } else {
+            //Display violations...
+         }
+      }
+   }
+
+
+DAO operations
+--------------
+It is always recommended to use parameterized queries, regardless of the operations performed on the data.
+- To avoid SQL injections.
+- To allow the use of prepared queries, speeding up processing.
+
+.. code-block:: php
+
+   $googleUsers=DAO::getAll(User::class,'email like ?',false,['%@gmail.com']);
+
+.. code-block:: php
+
+   $countActiveUsers=DAO::count(User::class,'active= ?',[true]);
+
+.. tips:: DAO operations that take objects as parameters use this mechanism by default.
+
+.. code-block:: php
+
+   DAO::save($user);
+
+.. tips:: It is possible to apply the transformers defined on a model before modification in the database.
+
+Passwords management
+--------------------
+
+The `Password` Transformer allows a field to be of the password type when displayed in an automatically generated CRUD form.
+
+.. code-block:: php
+
+   #[Transformer(name: "password")]
+   private $password;
+
+After submission from a form, it is possible to encrypt a password from the URequest class:
+
+.. code-block:: php
+
+   $encryptedPassword=URequest::password_hash('password');
+   $user->setPassword($encryptedPassword);
+   DAO::save($user);
+
+The algorithm used in this case is defined by the php `PASSWORD_DEFAULT`.
+
+It is also possible to check a password entered by a user in the same way, to compare it to a hash:
+
+.. code-block:: php
+
+   if(URequest::password_verify('password', $existingPasswordHash)){
+      //password is ok
+   }
+
+
+.. important:: Set up Https to avoid sending passwords in clear text.

docs/security/module.rst

@@ -0,0 +1,91 @@
+.. _securityModule:
+Security module
+***************
+
+.. |br| raw:: html
+
+   <br />
+
+Installation
+============
+
+Install the Ubiquity-security module from the command prompt or from the **Webtools** (Composer part).
+
+.. code-block:: bash
+
+    composer require phpmv/ubiquity-security
+
+Then activate the display of the Security part in the **Webtools**:
+
+.. image:: /_static/images/security/display-security.png
+   :class: bordered
+Session CSRF
+============
+
+The installation of the Security module enables by default the CSRF protection of the session:
+
+.. image:: /_static/images/security/security-part.png
+   :class: bordered
+
+Encryption manager
+==================
+The **EncryptionManager** service can be started directly from the **webtools** interface.
+
+- In this case, a key is generated in the configuration file `app/config/config.php`.
+
+- The service is started in the `services.php` file.
+
+.. code-block:: php
+   :caption: app/config/services.php
+
+    \Ubiquity\security\data\EncryptionManager::start($config);
+
+.. tips:: By default, encryption is performed in ``AES-256``.
+
+.. image:: /_static/images/security/encryption-manager-started.png
+   :class: bordered
+
+Cookie encryption
+-----------------
+Cookies can be encrypted by default, by adding this in `services.php`:
+
+.. code-block:: php
+   :caption: app/config/services.php
+
+    use Ubiquity\utils\http\UCookie;
+    use Ubiquity\contents\transformation\transformers\Crypt;
+
+    UCookie::setTransformer(new Crypt());
+
+.. image:: /_static/images/security/cookie-crypt.png
+   :class: bordered
+
+Model data encryption
+---------------------
+The ``Crypt`` transformer can also be used on the members of a model:
+
+.. code-block:: php
+   :caption: app/models/User.php
+
+    class Foo{
+        #[Transformer(name: "crypt")]
+        private $secret;
+        ...
+    }
+
+
+Generic Data encryption
+-----------------------
+It is possible to encrypt any type of data:
+
+.. code-block:: php
+
+    $encryptedUser=EncryptionManager::encrypt($user);
+
+To then decrypt it, with possible serialisation/deserialisation if it is an object:
+
+.. code-block:: php
+
+    $user=EncryptionManager::encrypt($encryptedUser);
+
+