.. Reminder for header structure:
  Parts (H1)          : #################### with overline
  Chapters (H2)        : ******************** with overline
  Sections (H3)        : ====================
  Subsections (H4)    : --------------------
  Subsubsections (H5) : ^^^^^^^^^^^^^^^^^^^^
  Paragraphs (H6)      : """""""""""""""""""""

.. meta::
  :description: Presentation of the security principles in WAPT
  :keywords: Cybersecurity, WAPT, documentation

#######################################
Presentation of cryptographic processes
#######################################

.. list-table:: 
  :header-rows: 1
  :stub-columns: 1
  :widths: auto

  * - Date
    - |today|
  * - Written by
    - Hubert TOUVET, Vincent CARDON
  * - Applicable for WAPT
    -  ≥ 2.3.0.13180
  * - Version of the document
    - 2.3.0.0-0
  * - Git hash
    - |git_hash|


******************************************************************
WAPT solution components and cryptographic mechanism specification
******************************************************************

Cryptographic processes are involved in the following activities:

* Signature and verification of **files contained in a package**.

* Signature and verification of **package attributes**.

* Signature and verification of **immediate actions** on WAPT clients.

* Signature of inventories and **WAPT customer status**.

* Websockets connection authentication for WAPT clients on the WAPT Server.

* HTTPS communication between WAPT clients and the WAPT Server.

* HTTPS communications between the WAPT Console and the WAPT Server.

* HTTPS communications between WAPT clients and WAPT repositories.

Software component versions are specified in the "List of third-party components integrated into the product (COTS)" section of the Security Target.

WAPT Server cryptographic specifications
========================================

The WAPT Server runs on a PostgreSQL database.

*************
Nginx service
*************

The Nginx Server serves packages to client workstations and acts as a reverse proxy for the WAPT Server. It is configured in :abbr:`TLS (Transport Layer Security)` v1.3 with the EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH ciphers.

.. list-table:: Nginx service cryptographic specifications
  :header-rows: 1
  :widths: 20 20 20 20 20
  :align: center

  * - Crypto hardware used
    - Usage
    - Specifications
    - Location
    - Creation / renewal
  * - nginx https Server private key
    - Connections Console WAPT- Server
      
      Connections Agent WAPT - Server
    - RSA 2048 bits.
      
      Unencrypted :abbr:`PEM \(Privacy Enhanced Mail\)` format.
    - :file:`/opt/wapt/waptserver/ssl/key.pem`
    - Initial Server post-configuration
  * - nginx https Server certificate
    - Server authentication
      
      Encrypt https connections.
    - X509 certificate with RSA key
      
      :abbr:`PEM \(Privacy Enhanced Mail\)` format
      
      Duration 3 years
    - :file:`/opt/wapt/waptserver/ssl/cert.pem`
    - Initial Server post-configuration
      
      When renewing, it is necessary to distribute the new https Server certificate to the Agents with a WAPT package before the previous one expires.
  * - Diffie-Hellman key
    - Initial key exchange
    - 2048 bits
      
      :abbr:`PEM \(Privacy Enhanced Mail\)` format.
    - :file:`/etc/ssl/certs/dhparam.pem`
    - Initial Server post-configuration
  * - https client :abbr:`CA (Certificate Authority)`
    - Client certificate authentication for https connections to WAPT Agents and the WAPT Console.
    - An X509 format certificate Store containing copies of the :abbr:`CA (Certificate Authority)` :abbr:`PKI (Private Infrastucture Key)` WAPT Agents and :abbr:`CA (Certificate Authority)` :abbr:`PKI (Private Infrastucture Key)` WAPT Administrators
    - Defined in :file:`/opt/wapt/conf/waptserver.ini` by the key **ssl_client_certificates** in the [options] section.
    - Initial Server post-configuration and updated manually each time the :abbr:`CA (Certificate Authority)` :abbr:`PKI (Private Infrastucture Key)` WAPT Agents and :abbr:`CA (Certificate Authority)` :abbr:`PKI (Private Infrastucture Key)` WAPT Administrators
  * - Clients https :abbr:`CRL (Certificate Revocation List)`
    - Enables NGINX to check that client certificates have not been revoked.
    - A file in :abbr:`PEM \(Privacy Enhanced Mail\)` format containing copies of the :abbr:`PKI (Private Infrastucture Key)` Agents WAPT and :abbr:`CRL (Certificate Revocation List)` :abbr:`PKI (Private Infrastucture Key)` WAPT administrators
    - Defined in :file:`/opt/wapt/conf/waptserver.ini` by the key **ssl_client_crls** in the [options] section.
    - :abbr:`CRL (Certificate Revocation List)` Store updated every hour by a scheduled task on the WAPT Server.
    
      The **clients_signing_crl** :abbr:`CRL (Certificate Revocation List)` and the :mimetype:`*.crt` files in :abbr:`PEM \(Privacy Enhanced Mail\)` format in the directory defined by **ssl_additional_crls** are concatenated for use by NGINX.
  * - Keytab kerberos
    - Authentication of WAPT Console logins. 

      Authentication of WAPT Agent initial registrations.
    - SPN: HTTP/<fqdn of WAPT Server> @<REALM> 
    - :file:`/etc/nginx/http-krb5.keytab`
    - Keytab created and extracted from :abbr:`AD (Active Directory)` manually.

No automatic renewal.

*******************
WAPT Server service
*******************

For WAPT Agents, the WAPT Serveur service:

* Manages the authorization and initial registration of WAPT Agents and signs WAPT Agent :abbr:`CSR (Certificate Signing Request)` .

* Checks the authenticity and integrity of status information sent by WAPT Agents.

* Authorizes Websockets connections.

For the WAPT Console, the WAPT:

* Manages WAPT Administrator authentication and access authorizations to data returned by WAPT Agents.

.. list-table:: Cryptographic specifications for the WAPT service
  :header-rows: 1
  :widths: 20 20 20 20 20
  :align: center

  * - Crypto hardware used
    - Usage
    - Specifications
    - Location
    - Creation / renewal
  * - :abbr:`PKI (Private Infrastucture Key)` private key WAPT Agents.
    - Signs Agent :abbr:`CSR (Certificate Signing Request)` on initial registration and :abbr:`CSR (Certificate Signing Request)` for temporary client certificates for Console https access.
    - RSA 2048 bits.
      
      Unencrypted :abbr:`PEM \(Privacy Enhanced Mail\)` format.
    - Defined in :file:`/opt/wapt/conf/waptserver.ini` by the key **clients_signing_key** in the [options] section.

      Default: :file:`/opt/wapt/conf/ca-<servername>.pem`.
    - Initialized during WAPT Server installation (postconf).
  * - :abbr:`CA (Certificate Authority)` :abbr:`PKI (Private Infrastucture Key)` Agents WAPT.
    - Certificate with which Agent certificates can be verified.
      
      This certificate is used by nginx for Agent client certificate authentication.
    - Self-signed and pinned X509 certificatewith RSA key.
      
      :abbr:`PEM \(Privacy Enhanced Mail\)` format.
      
      Duration 3 years.
    - Defined in :file:`/opt/wapt/conf/waptserver.ini` by key **clients_signing_certificate** in the [options] section.

      Default: :file:`/opt/wapt/conf/ca-<servername>.crt`.
    - Initialized during WAPT Server installation (postconf).
  * - :abbr:`CA (Certificate Authority)` :abbr:`PKI (Private Infrastucture Key)` WAPT Administrators.
    - Certificates used to verify WAPT administrator certificates.

      This certificate is used by waptserver to authorize packages to be sent to the Server.
    - CertificatesX509 with RSA key.
  
      :abbr:`PEM \(Privacy Enhanced Mail\)` format.
  
      Organization-specific specifications.
    - Defined in :file:`/opt/wapt/conf/waptserver.ini` by key **trusted_signers_certificates_folder** in the [options] section.
    - Provided and managed by the organization.
  * - :abbr:`CRL (Certificate Revocation List)` :abbr:`PKI (Private Infrastucture Key)` WAPT Agents.
    - Stores serial numbers of banned WAPT Agent certificates.
    - :abbr:`PEM \(Privacy Enhanced Mail\)` format.
  
      Duration 10 days.
    - Defined in :file:`/opt/wapt/conf/waptserver.ini` by key **clients_signing_crl** in the [options] section.

      Default: :file:`/var/www/ssl/ca-<servername>.crt`.
    - Initialized at post-configuration.

      Fed and re-signed each time a WAPT Agent is deleted.

      Automatic task that periodically re-signs the :abbr:`CRL (Certificate Revocation List)`.
  * - Known certificates.
    - Enables WAPT Console and WAPT Agents to reconstitute certificate chains (in the case of intermediate :abbr:`CA (Certificate Authority)`).
    - 
    - Defined in :file:`/opt/wapt/conf/waptserver.ini` by key **known_certificates_folder** in the [options] section.

      Default: :file:`/var/www/html/wapt/ssl/*.crt`.
    - Certificates are automatically extracted from packages when they are sent to the Server.
  
      Certificates associated with administrators are also extracted when user accounts are registered.
  * - Secret admin account.
    - For initial authentication of the WAPT Console for the account designated **wapt_user**.
    - Minimum password length: 20 characters.
  
      Verified complexity.
  
      PBKDF2 password derivation with 29000 iterations, hmac-sha256.
    - Defined in :file:`/opt/wapt/conf/waptserver.ini` by key **wapt_password** in the [options] section.
    - Initialized during installation.
  
      Can be changed from the WAPT Console by a WAPT administrator authenticated with the same account.
  * - Secret session cookies.
    - Authenticates WAPT Server :abbr:`API (Application Programming Interface)` calls after correct login.
    - 64 ascii characters.
    - Defined in :file:`/opt/wapt/conf/waptserver.ini` by key **secret_key** in the [options] section.
    - Set to a random value on initial installation.

      Not automatically renewed.
  * - Token encryption secret.
    - Authenticates Agent Websockets connections (deprecated behavior, disabled in :abbr:`TOE (Target Of Evaluation)` configuration).

      Authenticates the login for the "Waptselfservice" application.

      Tokens are generated during Server login if the Server configuration authorizes the "token" method, or if the login call explicitly specifies that it wants a token instead of a session cookie.
    - 64 ascii characters.
    - Defined in :file:`/opt/wapt/conf/waptserver.ini` by key **token_secret_key** in the [options] section.
    - Set to a random value on initial installation.

      Not automatically renewed.
  * - WAPT Agent certificates.
    - Authentication and integrity checking of data sent by WAPT Agents.

      Authentication of websocket token requests by WAPT Agents (deprecated behavior, disabled in :abbr:`TOE (Target Of Evaluation)` configuration).
    - X509 certificate signed by :abbr:`CA (Certificate Authority)` :abbr:`PKI (Private Infrastucture Key)` WAPT Agents.
      
      :abbr:`PEM \(Privacy Enhanced Mail\)` format.
      
      Default duration 3 years.
      
      Extended Key Usage: :abbr:`TLS (Transport Layer Security)` Web Client Authentication.
      
      Key Usage: Digital Signature.
    - Field '**host_certificate**' Table 'Hosts' in the 'wapt' database.
    - 
  * - WAPT Administrator Certificates.
    - Lists directors' personal certificates.
    - X509 certificate signed by the :abbr:`CA (Certificate Authority)`.
  
      :abbr:`PEM \(Privacy Enhanced Mail\)` format.
  
      Default Duration 3 years.
  
      Extended Key Usage: :abbr:`TLS (Transport Layer Security)` Web Client Authentication.
  
      Key Usage: Digital Signature.
    - Field **user_certificate**, Table 'WaptUsers' from the 'wapt' database.
    - Created from the WAPT Console.
      
      Assigned to a WAPT Administrator accountWAPT Console's "WAPT user and rights management" function.
  * - Certificate fingerprints WAPT Administrator.
    - Authorization to access WAPT Server :abbr:`API (Application Programming Interface)` after successful authentication of client certificate by Nginx Server if "ssl" method enabled in Server configuration (not enabled in :abbr:`TOE (Target Of Evaluation)` configuration).
    - sha1 fingerprint of the administrator's certificate.

      (A sha1 is used here, as this is the information provided by nginx's SSL authentication module).
    - Field '**user_fingerprint**' Table 'WaptUsers' from the 'wapt' database.
    - Extracted from the administrator's certificate when assigning the certificate to the account in the WAPT Console.

.. _signing_actions_relayed_to_WAPT_agents:

Cryptographic specifications of the administrator workstation hosting the WAPT Console
======================================================================================

.. list-table:: Cryptographic specifications for the administrator workstation hosting the WAPT Console
  :header-rows: 1
  :widths: 20 20 20 20 20
  :align: center

  * - Crypto hardware used
    - Usage
    - Specifications
    - Location
    - Creation / renewal
  * - :abbr:`CA (Certificate Authority)` https Servers
    - Verification of WAPT Server https certificate.
  
      Verification WAPT repository https certificate
    - X509 Certificate Stores in :abbr:`PEM \(Privacy Enhanced Mail\)` format (:mimetype:`.crt` extension).

      Each :mimetype:`.crt` file can contain several approved https Server :abbr:`CAs (Certificate Authority)`.
    - The path to the trusted Store is specified by the **verify_cert** attribute in the WAPT Agent's :file:`wapt-get.ini` file.

      Stores are stored in the :file:`%LOCALAPPDATA%\waptconsole\ssl\server` directory.
    - The first time the WAPT Console is launched, Stores and Agent configuration are copied.
  * - :abbr:`CA (Certificate Authority)` system
    - Certificate verification for https connections if **verify_cert** attribute is equal to 1
    - X509 Certificate Store in :abbr:`PEM \(Privacy Enhanced Mail\)` format.
    - File :file:`%LOCALAPPDATA%\i\cacert.pem`
    - Automatic extraction from CERTSTORE's :abbr:`CA (Certificate Authority)` and ROOT Stores of the trusted :abbr:`CA (Certificate Authority)` system used to verify https certificates.
  
      1h cache
  * - Clients packages and shares
    - Authentication of imported or edited packages
    - One X509 Certificate Chain file in :abbr:`PEM \(Privacy Enhanced Mail\)` format per approved :abbr:`CA (Certificate Authority)`.

      The first certificate in each file is approved (Key Usage: Digital Signature), the others are any intermediate :abbr:`CAs (Certificate Authority)` (Basic constraint: CA, Key Usage: Certificate Sign).
    - Defined in the ini file :file:`%LOCALAPPDATA%\waptconsole\waptconsole.ini` Key [<repository name>] **public_certs_dir**

      Default: WAPT administrator certificate
    - WAPT administrator copies certificates for approval.
  * - WAPT administrator certificate
    - Package signature
  
      Signature of remote actions on WAPT Agents
  
      https authentication on Nginx Server
    - X509 Certificate Chain in :abbr:`PEM \(Privacy Enhanced Mail\)` format

      The first certificate is the administrator's certificate, the others are any intermediate :abbr:`CA (Certificate Authority)`.

      WAPT administrator certificate features:
  
      Key Usage: Digital Signature, Non Repudiation, Data Encipherment
  
      Extended Key Usage: :abbr:`TLS (Transport Layer Security)` Web Client Authentication

      If the administrator is authorized by the organization to sign packages with python code, the certificate must also have:
  
      Extended Key Usage: Code Signing
    - :file:`%USERPROFILE%\private\<keyname>.crt`
    - Created and renewed by the organization.

  * - WAPT administrator private key
    - Signing WAPT packages.
  
      Signature of actions to WAPT Agents
    - Signature by cRSA 2048 bits, PKCS#8 password-encrypted format. PBKDF2 password derivation with 800 iterations, hmac-sha256.AES-256-CBC encryption
  
      Share and package signature type: RSA-SHA256 without padding
    - :file:`%USERPROFILE%\private\<keyname>.pem`
    - Created by the organization.
  * - Ticket Kerberos Windows session WAPT administrator
    - Initial authentication (login) to the WAPT Server
    - 
    - Windows session
    - 
  * - Private key password
    - WAPT Administrator private key decryption to sign actions and packages
    - 
    - Kept encrypted in the WAPT Console's memory space by an ephemeral secret also in the WAPT Console's memory and by a random secret specific to the user's session and stored in the user's private directory.
    - 
  * - Password WAPT administrator account
    - Initial authentication (login) to the WAPT Server
    - 
    - idem
    - 
  * - TOTP authentication key WAPT console
    - Second initial authentication factor (login) with the WAPT server
    - RFC6238, 160-bit key derived from a secret of 32 uppercase ascii characters. 
      Sha1 derivation algorithm
      Duration of 30s
      6-digit temporary token
    - In the otp_key field of the WaptUsers table on the WAPT server.
      In the administrator's authentication device.
    - From the console, the authenticated user can add or reset the key. 
  * - WAPT Console certificate
    - Client https authentication to Nginx Server for Console session.
    - Temporary X509 certificate in :abbr:`PEM \(Privacy Enhanced Mail\)` format signed by :abbr:`CA (Certificate Authority)` :abbr:`PKI (Private Infrastucture Key)` Agents WAPT.
      Validity period equal to the duration of session cookies.
    - Temporary user directory
    - Signed by the :abbr:`CA (Certificate Authority)` :abbr:`PKI (Private Infrastucture Key)` WAPT Agents on the Server after successful Kerberos authentication of the Console.
  * - Private key WAPT Console
    - Client https authentication to Nginx Server for Console session.
    - Temporary encrypted 2048-bit RSA key. PKCS#8 format encrypted by 120-character random password encrypted in memory by session key. PBKDF2 password derivation with 800 iterations, hmac-sha256. AES-256-CBC encryption
    - Temporary user directory
    - Generated by the Console each time you log in.

Cryptographic specifications for client workstations equipped with the WAPT Agent
=================================================================================

**********
WAPT Agent
**********

.. list-table:: Cryptographic specifications for client workstations equipped with the WAPT Agent
  :header-rows: 1
  :widths: 20 20 20 20 20
  :align: center

  * - Crypto hardware used
    - Usage
    - Specifications
    - Location
    - Creation / renewal
  * - :abbr:`CA (Certificate Authority)` https Servers.
    - Verification of WAPT Server https certificate. Verification of WAPT repository https certificate.
    - X509 Certificate Stores in :abbr:`PEM \(Privacy Enhanced Mail\)` format (:mimetype:`.crt` extension).

      Each :mimetype:`.crt` file can contain several approved https Server :abbr:`CA (Certificate Authority)`.
    - The path to the trusted Store is specified by the **verify_cert** attribute in the Agent's wapt-get.ini file.

      Stores are stored in the directory :file:`C:\program files (x86)\wapt\ssl\server`.
    - Initially deployed when the WAPTagent is installed on the client workstation.
  
      Added or updated by WAPT packages dynamic configuration.
  
      Removed by a WAPT package.
  * - :abbr:`CA (Certificate Authority)` system.
    - Certificate verification for https connections if **verify_cert** attribute is equal to True.
    - X509 Certificate Store in :abbr:`PEM \(Privacy Enhanced Mail\)` format.
    - File :file:`%localappdata%\i\cacert.pem`.
    - Automatic extraction from CERTSTORE's :abbr:`CA (Certificate Authority)` and ROOT Stores of the trusted :abbr:`CA (Certificate Authority)` system used to verify https certificates.
  
      1h cache.
  * - Client packages and shares.
    - package authentication and authorization.
  
      Authentication and authorization of actions.
    - X509 certificate chain in :abbr:`PEM \(Privacy Enhanced Mail\)` format.
  
      The first certificate in each file is approved, the others are any intermediate :abbr:`CA (Certificate Authority)`.
  
      Type of signature for actions and packages: RSA-SHA256 algorithm without padding applied to the sha256 condensate of serialized data.
  
      The "Code signing" function of the certificate is used to authorize or not the execution of python code in the package.
    - :file:`C:\program files (x86)\wapt\ssl\*.crt`.
    - Initially deployed when the WAPT Agent is installed on the client workstation.

      Add or update with dynamically configured WAPT packages.

      Withdrawal via a WAPT package.
  * - WAPT Agent Certificate.
    - Client https authentication to Nginx Server.
      Signature of inventory data.
    - X509 certificate in :abbr:`PEM \(Privacy Enhanced Mail\)` format signed by :abbr:`CA (Certificate Authority)` :abbr:`PKI (Private Infrastucture Key)` WAPT Agents.
    - :file:`C:\program files (x86)\wapt\private\<agent UUID>.crt`.
    - Signed when a WAPT Agent is registered after successful Kerberos authentication of the Agent.
  * - Private key WAPT Agent.
    - Client https authentication to Nginx Server.
      Signature of inventory data.
    - Unencrypted 2048-bit RSA key.
    - :file:`C:\program files (x86)\wapt\private\<agent UUID>.pem`.
    - Generated by the WAPT Agent on installation or when the Agent :abbr:`UUID (Universally Unique IDentifier)` is changed.
  * - Secret Agent WAPT.
    - Encrypt authentication tokens for local applications.
    - 64-character random string.
    - :file:`C:\Program Files (x86)\wapt\private\secret_key`.
    - Randomly generated when the Agent is installed.

*******************************************************
Local client applications: waptexit, waptself, wapttray
*******************************************************

.. list-table:: Cryptographic specifications for client-side applications: waptexit, waptself, wapttray
  :header-rows: 1
  :widths: 20 20 20 20 20
  :align: center
  
  * - Crypto hardware used
    - Usage
    - Specifications
    - Location
    - Creation / renewal
  * - Token Local applications
    - Authentication of local actions on the WAPT Agent initiated from local applications (on the same machine as the WAPT Agent).
    - JWT token dated.
      Algorithm: HS512.
      Validity: 24 hours.
      Content: username and groups.
    - Local application memory.
    - After authenticating local applications to the WAPT Agent, the WAPT Agent generates a token to authenticate the following actions.
  * - Ticket Kerberos Windows session user.
    - 
    - 
    - Windows session.
    - 
  * - Local WAPT Agent https server certificate
    - Encryption and authentication of https connections from local wapt-get, waptexit, waptself, wapttray clients on the local wapt service 
    - X509 certificate with RSAFormat PEM key. Valid for 2 days
    - C:\Program Files (x86)\wapt\public\localservice.crt
    - When the local wapt (the local service is restarted every day)
  * - Secret token transmission
    - Ephemeral encryption of the "Local Applications Token" when it is temporarily stored on the file system during login to the local service, clients
    - aes-cbc encryption and pkcs#7 padding. Random string of 64 characters minimum passed in the login request. The encryption key is derived from the secret by pbkdf2 hmac sha256 (10000 iterations)
    - 
    - Generated by each /login or /localtoken request by local clients.

SF1. Secure communications
==========================

The WAPT Agent and WAPT Console use both interpreted Python code and Lazarus / FPC compiled code.

The Lazarus / FPC code uses the mORMot framework for https protocol management, Kerberos client management, X509 certificate operations, and cryptographic operations (Hash, RSA).

The mORMot framework is itself configured and linked to use the OpenSSL library for :abbr:`TLS (Transport Layer Security)` sockets, asymmetric RSA operations (key generation, encryption, decryption, signing, verification), and X509 certificate operations.

The Python code is linked to the same OpenSSL libraries and uses the following modules:

* python cryptography and pyOpenSSL modules linked to OpenSSL: used for all RSA cryptographic operations, X509 certificate generation and signature verification in the python WAPT Agent.

* winkerberos (Windows Agent) / Kerberos (Linux Agent) and requests-kerberos: used to authenticate the WAPT Agent when it first registers with the WAPT Server.

* Certifi: the authority certificate bundle used for certificate validation is the certificate Store of the operating system running the Agent, Console or Server (certstore Windows under Windows and /etc/ssl/certs/ under Redhat).

Communications between WAPT agents and the WAPT server use the https protocol. The Nginx server uses the :abbr:`TLS (Transport Layer Security)` layer of the system. The certificate used to encrypt the https connection is generated and configured by the organisation as part of its internal https :abbr:`PKI (Private Infrastucture Key)`.

Communications between local clients (wapt-get, waptself, waptexit, wapttray) use the https protocol. The WAPT agent's local https server uses the Openssl TLS layer installed with the agent.


SF2. Identification, authentication and access control
======================================================

*******************************
Initial WAPT Agent registration
*******************************

After installation, the WAPT Agent performs an initial registration on the WAPT Server. 
The initial registration corresponds to the creation of a client certificate, which will be used to authenticate the WAPT Agent:

Agent authentication on the WAPT Server (Kerberos or login/password).

The Agent creates a public/private key pair and sends a :abbr:`CSR (Certificate Signing Request)` to the WAPT Server.

The Server signs the :abbr:`CSR (Certificate Signing Request)` with the "machine" :abbr:`CA (Certificate Authority)`.

Server registration of the Agent's public certificate and its identifier (Bios :abbr:`UUID (Universally Unique IDentifier)` by default).

The WAPT Agents :abbr:`PKI (Private Infrastucture Key)` :abbr:`CA (Certificate Authority)` is an internal WAPT :abbr:`CA (Certificate Authority)` used only to sign :abbr:`CSR (Certificate Signing Request)` during workstation registration and to validate WAPT Agent authentication on the WAPT Server afterwards. 
It is generated when the WAPT Server is installed with a 2048-bit key. 
It is independent of the WAPT Administrators :abbr:`PKI (Private Infrastucture Key)` :abbr:`CA (Certificate Authority)` or the https client :abbr:`CA (Certificate Authority)`.

A :abbr:`CRL (Certificate Revocation List)` file is generated and populated when a machine is deleted from the WAPT inventory.

The :abbr:`PKI (Private Infrastucture Key)` Agents WAPT :abbr:`CA (Certificate Authority)` and :abbr:`PKI (Private Infrastucture Key)` Agents WAPT :abbr:`CRL (Certificate Revocation List)` are integrated into the Nginx service, which handles client certificate authentication.

This means that only machines that have been properly registered on the WAPT Server and not deleted can access the package repository.

The workstation's initial registration URL is not protected by Nginx client certificate authentication.

For initial authentication of the workstation during registration, the workstation uses the machine's Kerberos account to retrieve a service ticket for the WAPT service, which will then be used to authenticate the Agent for registration with the Server. 
Once the workstation has been registered and the client certificate signed, the WAPT Agent will no longer use Kerberos, but only certificate authentication on the WAPT Server.

**************************
Agent websocket connection
**************************

Agent websockets connections are made over the same https channel as other connections, with an upgrade after the first exchange.
The WAPT Agent uses its WAPT Agent Certificate to authenticate itself on the Nginx Server.
If authentication fails, the Agent will try to re-register (see previous paragraph).

As a reminder, no connection is initiated by the Server to the Agents.

**********************************
Agent login for inventory feedback
**********************************

Inventories are uploaded over the https connection. 
Authentication is performed with the WAPT Agent Certificate by the Nginx Server. 
If authentication fails, the workstation will attempt to re-register.

**************************************
Connecting Agents to download packages
**************************************

package index and packages are downloaded over the https connection.
Authentication is performed with the WAPT Agent Certificate by the Nginx Server.

*******************************
Server authentication by Agents
*******************************

The client authenticates the WAPT Server using the https Server :abbr:`CA (Certificate Authority)`.

**************************************
Authentication of deposit(s) by Agents
**************************************

The client workstation authenticates the WAPT repository using the https Server :abbr:`CA (Certificate Authority)`.

************************
Remote actions on Agents
************************

It is possible, from the WAPT Console, to send actions to WAPT Agents, such as "update the list of available updates", "launch installations of available updates", etc.
These various actions are initiated from the WAPT Console and relayed by the WAPT Server to the Agents via the existing websocket.

Communication between the Console and the WAPT Server is via the https channel. Communication between the WAPT Server and the WAPT Agent is via the websocket previously set up by the Agent.

************************************************
Administrator authentication on the WAPT Console
************************************************

Following installation of the WAPT Server, the first authentication is performed using the "admin" account and the password entered when running the postconf.
This account is used to finish configuration and define :abbr:`ACL (Access Control List)` for WAPT administration accounts defined in Active Directory.
Following this initial configuration, "admin" :abbr:`ACL (Access Control List)` can be assigned to named Active Directory accounts.

Authentication on the WAPT Server uses these domain accounts.

A second TOTP factor is then defined for each account and is requested during the authentication phase.

In addition, access to the WAPT Server and WAPT repository is protected on the Nginx Server by client certificate authentication based on the WAPT Agents :abbr:`PKI (Private Infrastucture Key)` :abbr:`CA (Certificate Authority)`.

SF3. Data protection
====================

The data protection functions do not use cryptographic procedures and are based entirely on the security of the file system.

SF4. Cryptographic functions: Authenticity and integrity
========================================================

************************************
Signature of control file attributes
************************************

When signing a WAPT package, the package's sensitive attributes are listed in the **signed_attributes** attribute.

The attributes listed in **signed_attributes** are signed with the Administrator's private key and the signature is stored in the signature attribute of the control file.

The certificate associated with this private key is stored in the :file:`<wapt>\certificate.crt` file inside the WAPT package.

On the WAPT Server, during the wapt-scanpackages operation (triggered by the addition or deletion of a package), the Packages index is regenerated.

The WAPT Server extracts the signer's certificate from each package and adds it to the Packages ZIP file, in the <wapt>/ssl directory.
Each certificate is named with its hexadecimal-encoded fingerprint.

When the WAPT Agent performs an update, it downloads the Packages index file, which contains both the signed attributes of all packages and the certificates of the signatories.
If the certificate of the signatory of a package's attributes is approved (meaning that the certificate is signed by a Certification Authority or that the certificate itself is trusted), AND the signatory's certificate can verify the signature of the attributes, the package is added to the index of available packages, otherwise it is ignored.

*********************
Signing WAPT packages
*********************

When an Administrator or a Package Developer builds a WAPT:

A :file:`<wapt>/manifest.sha256` file is created which lists the checksums of all the files in the package.

A :file:`signature.sha256` file encrypted with the private key is then created in the WAPT folder, containing the checksum of the :file:`<wapt>/manifest.sha256` file.

All files are archived in ZIP format with the  :mimetype:`.wapt` extension.

When a WAPT Agent downloads a WAPT package, the Agent checks that the :file:`signature.sha256` file has been signed with the private key that corresponds to the package's :file:`<wapt>/certificate.crt` certificate.

The WAPT Agent then verifies that the certificate (or certificate chain) :file:`certificate.crt` has been signed with a private key corresponding to one of the certificates in the :file:`<wapt>\ssl` folder.

The WAPT Agent then checksums all the files in the package (except the :file:`signature.sha256` and :file:`certificate.crt` files) and verifies that the checksum matches the :file:`<wapt>manifest.sha256` file contained in the package.

If one of these steps is not validated, this means that a file has been modified / added / deleted. In this case, execution of :program:`setup.py` is cancelled.

The faulty package is then deleted from the local cache; the event is reported in the Agent logs.

SF5. Tamper protection
======================

**************************************************************
Microsoft Authenticode" signature for binaries and installers.
**************************************************************

We use the standard mechanism integrated into Windows. Binaries are signed in the build chain with a "Code signing" Extended Validation certificate issued by an authority validated by Microsoft.

The timestamping Server used is :file:`http://timestamp.sectigo.com`.

*******************************************
Checking the installer hash with waptdeploy
*******************************************

The waptdeploy utility is responsible for silently launching the waptagent.exe installer with elevated rights.

To guarantee the authenticity of the installer, we check that the sha1 fingerprint of the installer's "Authenticode" signature certificate is one of those used by Tranquil IT.
This list is integrated into the :file:`waptdeploy.exe` binary when :file:`waptdeploy.exe` is compiled.
The integrity of this list is ensured by the signature of the :file:`waptdeploy.exe` binary.

The :file:`waptagent.exe` installer is the aggregation of a standard waptsetup.exe binary (signed by Tranquil IT) and a json variable part for organization-specific configuration (in particular WAPT Server and repository URLs, authorized package certificates, trusted https certificates).
To guarantee the integrity of the "Installer" + specific configuration set, a sha256 fingerprint is supplied as an argument to the waptdeploy utility.
After downloading :file:`waptagent.exe` and before running it in silent mode, waptdeploy checks that the :file:`waptagent.exe` fingerprint matches the one supplied as an argument.
The integrity of the --hash argument is ensured by the :abbr:`ACL (Access Control List)` on the :abbr:`GPO (Group Policy Objects)` in which this command line is specified.
It is the responsibility of the organization's administrator to ensure that the installer fingerprint in the :abbr:`GPO (Group Policy Objects)` is correct.

SF6. Logging
============

************************************
Signing requests sent to WAPT Agents
************************************

Commands are signed by the WAPT Console before being sent individually to each WAPT Agent.

All action request attributes are signed:

the :abbr:`UUID (Universally Unique IDentifier)` of the Agent concerned;

action (e.g. install);

arguments (e.g. tis-firefox);

request time stamping.

The certificate associated with the signature is also passed. 
When the WAPT Agent receives a request, it checks:

That the :abbr:`UUID (Universally Unique IDentifier)` mentioned in the action corresponds to its :abbr:`UUID (Universally Unique IDentifier)`.

That the associated certificate comes from an authority present in its :file:`<wapt>/ssl` directory.

That the request is correctly signed by the certificate key.

That the signature date is within the time interval defined in the WAPT Agent configuration.

Information on data processing
==============================

None
