.. 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 ####################################### +------------------------+-------------------------------+ | 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| | +------------------------+-------------------------------+ .. contents:: :local: Cryptographic processes are used in the following activities: * Signature and verification of the **files contained in a package**. * Signature and verification of the **attributes of a package**. * Signature and verification of **instantaneous actions** on the WAPT Agents. * Signature of inventories and **status of WAPT Agents**. * Authentication of the WAPT Agents Websocket connections on the WAPT Server. * HTTPS communication between the WAPT Agents and the WAPT Server. * HTTPS communication between the WAPT Console and the WAPT Server. * HTTPS communication between the WAPT Agents and the WAPT repositories. Folders and files referenced in this document ============================================= * :file:``: WAPT installation folder. By default :file:`%ProgramFiles(x86)%\\WAPT`. * :file:`\\wapt-get.ini`: WAPT Agent configuration file (:program:`wapt-get` and :program:`waptservice`). * :file:`\\ssl`: default directory of trusted certificates for signed packages and actions. * :file:`\\ssl\\server`: default directory for storing the WAPT HTTPS Server certificates (pinning). * :file:`\\private`: default host key and certificate directory for signing the inventory and the Websocket connections. * :file:`%LOCALAPPDATA%\\waptconsole\\waptconsole.ini`: configuration file for the WAPT Console and package development actions for the :program:`wapt-get` tool. * :file:`%APPDATA%\\waptconsole\\ssl`: default trusted certificate directory for importing packages from an external repository (i.e. *package templates*). Definitions of Actors ===================== * **Organization** An Organization is the realm of responsibility within which WAPT is used. * **Certificate Authority** A Certificate Authority is the entity that keeps the keys that have been used to sign certificates for the :term:`Package Developers`, the :term:`Package Deployers` and the WAPT HTTPS Servers. * **Administrators** Administrators have a personal RSA key and a certificate that has been signed by the :term:`Certificate Authority` of the :term:`Organization`; they also have a login and a password for accessing the WAPT Console. * **WAPT Agents** WAPT clients are the realm of devices that the :term:`Organization` has allowed the :term:`Administrators` to manage with WAPT. The clients **may or may not be a member** of the :term:`Organization`'s Active Directory domain. * **WAPT Server** The WAPT Server is the Linux / Nginx/ PostgreSQL that the :term:`Organization` uses to keep the inventory of WAPT equipped devices. By default, the WAPT Server also plays the role of an internal WAPT Repository. The WAPT Server has a host account in the :term:`Organization`'s Active Directory. * **Internal WAPT repositories** Internal WAPT repositories are one or several Linux/ Nginx servers that deliver signed WAPT packages to WAPT clients using the HTTPS protocol. * **External WAPT repositories** External WAPT repositories are a public WAPT repository that the :term:`Package Developers` may use to import packages designed by other :term:`Organizations`, under the condition that they check the adequacy of the WAPT package in regards the internal policies on security and safety; * **Active Directory Server** The Active Directory Server manages the :term:`Organization`'s AD domain; Summary of crypto modules present in WAPT ========================================= The WAPT Agent, the WAPT Server and the WAPT Console make use of both Python interpreter code and Lazarus / FPC compiled code. The Lazarus / FPC code make use of the mORMot framework (>= 2.0.4383) for the https protocol handling, client kerberos handling, X509 certificates operations, and cryptographic operations (Hash, RSA). The mORMot framework is itself configured and linked to make use of :program:`OpenSSL 1.1.1s 1 Nov 2022` library for TLS sockets, asymetric RSA operations (key generation, encrypt, decrypt, sign, verify), and X509 certificates operations. Python code (WAPT Agent, WAPT Server, WAPT Packages) is linked against the very same :program:`OpenSSL 1.1.1s 1 Nov 2022` libraries and makes use of following modules: WAPT Agent Side: * **cryptography==3.3.2** and **pyOpenSSL==20.0.1** python modules linked on :program:`openssl 1.1.1s`: used for all RSA crypto operations, X509 certificate generations and signature verifications in the python WAPT Agent. * **winkerberos==0.8.0** (Windows agent) / **kerberos==1.3.1** (Linux agent) and **requests-kerberos==0.12.0**: used for authenticating the WAPT client on its first registrationg on the WAPT Server. * **certifi==2021.5.30**: used as base for the Root Authorities certificates. WAPT Server Side: * **Python** |python_version| ssl module linked on :program:`openssl 1.1.1s`. * **cryptography==3.3.2** and **pyOpenSSL==20.0.1** linked on :program:`openssl 1.1.1s`: used for all RSA crypto operations such as key generations, X509 certificate generations and signature verifications. On the WAPT Server, the :program:`nginx/1.18.0` service is configured to serve WAPT Packages over https, it handles https API requests to the WAPT Server, client Kerberos authentications, and client certificate check. The nginx server is configured for TLS1.2, cipher 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH'. Types of PKI / CA infrastructures in a standard WAPT Setup ========================================================== There are three types of PKI / CA in a standard WAPT setup .. list-table:: PKI / CA types in a WAPT setup :header-rows: 1 :widths: auto :align: center * - Type - Usage - Origin and registration - Renewal - Revocation * - HTTPS transport certificate - The purpose of this certificate is to secure the communications between the WAPT Agent and the WAPT Server and to authenticate the WAPT Server. - The certificate is issued by a :term:`Certificate Authority` trusted by the client computer (the :term:`Certificate Authority` must be integrated into the local Certificate Store), and the private https key must be stored on the :program:`nginx` http server. - The certificate must be renewed as any https certificates handled by the :term:`Organization`. - The certificate must be revoked as any https certiticates handled by the :term:`Organization`. * - The Administrator / Packager certificate - The purpose of this certificate is to sign Packages and Messages - This certificate is issued by the :term:`Certificate Authority` of the :term:`Organization`, and must be stored in the :file:`\\ssl` directory of each WAPT Agent that needs to trust that certificate. - The certificate must be renewed using the standard process of the :term:`Certificate Authority` of the :term:`Organization`. - :abbr:`CRL (Certificate Revocation List)` must be published through http and reachable by the WAPT Server, and the :abbr:`CRL (Certificate Revocation List)` distribution point attribute must be set in the certificate. The WAPT Server redistributes the :abbr:`CRL (Certificate Revocation List)` to the WAPT Agent. * - The WAPT Agent client certificate - The purpose of this certificate is to authenticate the WAPT Agent with the WAPT server, to sign data and finally potentialy encrypt data that the WAPT Agent sends to the WAPT Server. This certificate is purely technical to identify a WAPT client and is created through a :abbr:`CSR (Certificate Signing Request)` process initiated by the client during registration of the WAPT Agent with the WAPT Server. The private key is stored on the client in :file:`\\ssl\\private`, and the public key is stored on the WAPT Server. - The :term:`Certificate Authority` is handled internaly by the WAPT Server and is used only for the authentication of clients on the WAPT Server. - The renewal is done during intial registration or when the client certification fails. - The revocation is handled internally by the WAPT Server which configures a :abbr:`CRL (Certificate Revocation List)` for the :program:`Nginx` service. Key and certificate management for the Administrators ===================================================== Packages and actions done by an :term:`Administrator` are signed so that only Trusted Administrators are authorized to manage the devices. The WAPT :term:`Administrator` holds: * A private 2048 bit *RSA* key that has been encrypted by the aes-256-cbc algorithm. * A *X509* certificate signed by an :term:`Certificate Authority` trusted by the :term:`Organization`. .. note:: The process for creating the keys and signing, distributing and revocating the certificates are of the responsibility of the :term:`Organization` using WAPT; that process is beyond the functional perimeter of WAPT. However, to make the testing of WAPT easy, WAPT offers a function to generate a RSA key and its corresponding X509 certificate: * The generated RSA key is 2048bit long, encrypted with aes-256-cbc, encoded in PEM format and saved with a :mimetype:`.pem` extension. * The certificate is either self-signed, or signed by a Trusted Authority from whom we have received a key and a PEM formated certificate. * If the certificate is self-signed, then its :code:`KeyUsage` attribute contains the ``keyCertSign`` flag. * If the :term:`Administrator` is authorized by the :term:`Organization` to sign packages that contain python code (the presence of a :file:`setup.py` file is detected in the package), the :code:`extendedKeyUsage` attribute of the certificate contains the ``CodeSigning`` flag. * The *X509* certificate is encoded and handed over to the :term:`Administrator` in PEM format with a :mimetype:`.crt` extension. Validity of the Administrator's certificate ------------------------------------------- The WAPT Agent trusts all unexpired X509 certificates located in the \ssl WAPT Agent directory. If a PEM encoded :mimetype:`.crt` file in \ssl WAPT Agent directory contains more than one certificates, only the first one is trusted. the WAPT Agent only checks the dates of validity (:code:`notValidBefore`/ :code:`notValidAfter` attributes). The certificate is valid if (``Now`` >= :code:`notValidBefore` and ``Now`` <= :code:`notValidAfter`). Authorizing an Administrator's certificate to sign a package ------------------------------------------------------------ The certificate used by the WAPT Console to sign packages and actions is defined with the *personal_certificate_path* parameter in the section ``[global]`` of the file :file:`%LOCALAPPDATA%\\waptconsole\\waptconsole.ini`. WAPT asks the :term:`Administrator` for his password and then searches a private key (encoded in PEM format) that matches a certificate amongst the :mimetype:`.pem` files in the directory containing the certificates. When signing a package, WAPT will refuse the certificate if the package contains a :file:`setup.py` file and the certificate is not a *CodeSigning* type. Managing the WAPT Agent's key and certificate ============================================= The WAPT Agent (:program:`waptservice`) uses RSA keys and X509 certificates to authenticate itself with the WAPT Server. The WAPT client certificate is used in the following situations: * To control access to hosts packages and other packages repositories when client certificate authentication is enabled in NGINX server configuration. * When updating the WAPT client status on the WAPT Server (:command:`update_server_status`) **signing informations**. * When the WAPT Agent establishes a Websocket with the WAPT Server (:program:`waptservice`) **signing the WAPT client UUID**. First emission and later update of the WAPT Agent's certificate --------------------------------------------------------------- * On finishing the installation process of the WAPT Agent on the device, the WAPT Agent automatically registers itself on the WAPT Server by sending a kerberos authenticated HTTPS request that uses the TGT of the host account. The WAPT Agent uses Windows kerberos APIs implemented with :program:`kerberos-sspi` and :program:`requests-kerberos` python modules. .. note:: This process works if and only if the device is joined to the Windows domain for which the WAPT Server is configured. If the key and the certificates have not yet been generated, or if they do not match the current :term:`FQDN` of the device, the WAPT Agent generates a self-signed RSA key and X509 certificate with the following parameters: * The key is 2048 bit RSA encoded in PEM format and stored in the file :file:`\\private\\.pem`. * The generated certificate has the following attributes: - :code:`Subject.COMMON_NAME` = ````. - :code:`Subject.ORGANIZATIONAL_UNIT_NAME` = ``name of the Organization registered in the WAPT client's Windows registry``. - :code:`SubjectAlternativeName.DNSName` = ````. - :code:`BasicConstraint.CA` = ``True``. - :code:`Validity` = ``10 years``. - :code:`Serialnumber` = ``random``. * The temporary self signed client certificate is saved in the :file:`\\private\\.crt`. .. note:: Only host accounts and :term:`Local Administrators` have access to the :file:`\\private` directory because specific :abbr:`ACLs (Access Control Lists)` have been applied upon first installation of the WAPT Agent on the device. * The inventory and the WAPT Agent status updates are sent to the WAPT Server over POST HTTPS requests. * The POST HTTPS requests are authenticated by adding two specific headers: * *X-Signature*: - JSON encoded :abbr:`BLOB (Binary Large Object)` of inventory or status informations. - Signature of the :mimetype:`.json` file with the private key of the WAPT Client: *sha256* hashing and *PKCS#1 v1.5* padding. - *Base64* encoding of the signature. * *X-Signer*: *Subject.COMMON_NAME* of the WAPT Client. * After having initially authenticated the WAPT client with kerberos, the WAPT Server receives the certificate signing request sent by the Client, sign a proper client certificate and stores it in the table *hosts* of its inventory in :mimetype:`PEM` format (column *host_certificate*). * The newly signed client certificate is sent to the client. * The client then saves its certificate in the :file:`\\private\\.crt`. .. note:: If the device is renamed, the key / certificate pair is regenerated. When the WAPT Agent will update its status with the WAPT Server, the POST request will be refused because the remote device is registered in the database with another certificate. The device will then retry to :command:`register` with the WAPT Server using kerberos; then the new client certificate that has been signed by the WAPT Server will be saved in the database. Deploying certificates of Authorities of Certification to verify packages and validate actions on Clients --------------------------------------------------------------------------------------------------------- PEM formatted certificates are stored in files with :mimetype:`.crt` or :mimetype:`.pem` extensions in the directory defined with the :code:`public_certs_dir` parameter in the :file:`\\wapt-get.ini` file. They are reputed to be **trusted certificates**. The :code:`public_certs_dir` parameter is initialized by default to be :file:`\\ssl`. Authority certificates are deployed when the WAPT Agents are first deployed. From the WAPT Console, the :term:`Administrator` builds a personalized installer to be deployed by :term:`GPO` or other means on target devices. The WAPT Console includes in its personalized installer the certificates present in the :file:`\\ssl` directory of the PC on which the installer is being compiled. The :term:`Administrator` must insure to save in :file:`\\ssl` only the certificates of Authorities that are strictly necessary before launching the compilation of the installer. New or updated certificates of :term:`Certificate Authority` for the verification of packages and the validation of actions may also be deployed a posteriori with an Active Directory GPO or a WAPT package. Deploying certificates of Authorities of Certification for the HTTPS communication between the WAPT clients and the WAPT Server ------------------------------------------------------------------------------------------------------------------------------- The WAPT service (:program:`waptservice`) and the command line tool :program:`wapt-get` exchange with the WAPT Server to send its inventory (:command:`register`) and the package deployment status (:command:`update-status`). These two types of connections verify the HTTPS certificate of the WAPT Server. :code:`verify_cert` parameter in section ``[global]`` in :file:`\\wapt-get.ini`: * :code:`verify_cert` = ``True`` or ``1`` This method will only work well if the WAPT HTTPS Server is configured to send its certificate and the intermediary certificates upon initialization of the TLS connexion. * :code:`verify_cert` = ```` This method checks the HTTPS certificate using the indicated bundle of certificates. All the certificates of the intermediary Certificate Authorities **MUST** be bundled in a :mimetype:`.pem` formated file; * :code:`verify_cert` = ``False`` or ``0`` This method does not verify the HTTPS certificate of the WAPT Server. Conventionally, the approved bundle of certificates from the :term:`Certificate Authority` is stored in the :file:`\\ssl\\server` directory. The WAPT Console includes a function to facilitate the initial recovery of the WAPT Server certificate chain. The function stores it in :mimetype:`.pem` format in :file:`\\ssl\\server\\`. The :term:`Administrator` is responsible for insuring that the recovered certificate chain is **authentic**. During the build of the WAPT Agent installer, the certificates or the bundle of certificates is incorporated into the installer. When the installer is deployed on the WAPT clients, the bundle is copied in :file:`\\ssl\\server` and the :code:`verify_cert` parameter in section ``[global]`` in :file:`\\wapt-get.ini` is filled out to indicate the path to the certificate bundle. HTTPS communication between the WAPT clients and the WAPT repositories ====================================================================== Deploying certificates of Authorities of Certification ------------------------------------------------------ The HTTPS exchanges between the WAPT Agent and the main repository and between the WAPT Agent and the WAPT Server use the same methods. The WAPT Agent uses the same bundle of certificates to communicate in HTTPS with the main repository, with the WAPT Server, and with the secondary repositories. The HTTPS connection is implemented with :program:`requests`, :program:`urllib3` et :program:`ssl` python modules. The certificate emitted by the WAPT repository HTTPS Server is verified with the :program:`urllib3.contrib.pysopenssl.PyOpenSSLContext` and :program:`urllib3.util.ssl_wrap_socket` python modules. Websocket communications between the WAPT clients and the WAPT Server --------------------------------------------------------------------- To allow immediate actions on the WAPT clients, the WAPT service deployed on the clients establishes and maintains a permanent Websocket with the WAPT Server. This connection is TLS encrypted and uses on the client side the same bundle of certificates as the HTTPS connexion from the WAPT client to the WAPT Server. Communications between the WAPT Console and the WAPT Server =========================================================== Deploying certificates of Authorities of Certification ------------------------------------------------------ The :code:`verify_cert` parameter in section ``[global]`` in file :file:`%LOCALAPPDATA%\\waptconsole\\waptconsole.ini` can have different values: * :code:`verify_cert` = ``True`` or ``1`` This method will only work well if the WAPT HTTPS Server is configured to send its certificate and the intermediary certificates upon initialization of the TLS connexion. * :code:`verify_cert` = This method checks the HTTPS certificate using the indicated bundle of certificates. All the certificates of the intermediary Certificate Authorities **MUST** be bundled in a :mimetype:`.pem` formated file. * :code:`verify_cert` = ``False`` or ``0`` This method does not verify the HTTPS certificate of the WAPT Server. Conventionally, the approved bundle of certificates from the :term:`Certificate Authority` is stored in the :file:`\\ssl\\server` directory. The WAPT Console includes a function that facilitates the initial recovery of the WAPT Server certificate chain and that stores it in :mimetype:`.pem` format in the :file:`\\ssl\\server\\`. The :term:`Administrator` is responsible for insuring that the recovered certificate chain is **authentic**. It is also possible to recover the WAPT Server certificate chain and fill out the :code:`verify_cert` parameter with the command line :command:`wapt-get enable-check-certificate`. Deploying the certificates of Authorities of Certification to verify packages imported in the main repository ------------------------------------------------------------------------------------------------------------- In the WAPT Console, tab :guilabel:`Private Repository`, a button :guilabel:`Import from Internet` allows to download a package from an external repository whose address is provided with the :code:`repo-url` parameter in the section ``[wapt_templates]`` of :file:`%LOCALAPPDATA%\\waptconsole\\waptconsole.ini`. A checkbox :guilabel:`Verify Package Signature` insures that the imported package has been signed with a trusted certificate. The certificates from Trusted Authorities present in the directory specified with the :code:`public_certs_dir` parameter in section ``[wapt_templates]`` in file :file:`%LOCALAPPDATA%\\waptconsole\\waptconsole.ini` are considered to be trusted. If the parameter is not explicitly mentioned, it is initialized at :file:`%APPDATA%\\waptconsole\\ssl`. This directory is not automatically populated by WAPT. It is the responsibility of the :term:`Administrator` to copy / paste into it the :file:`PEM` files of other trusted :term:`Administrators` or the certificates from trusted Certificate Authorities. The Certificates from Trusted Authorities are encoded in :mimetype:`.pem` format and stored in files with :mimetype:`.pem` or :mimetype:`.crt` extensions. It is possible to store several certificates in each :mimetype:`.crt` or :mimetype:`.pem` file. It is not necessary to have the complete chain of certificates, WAPT will accept the signature of a package as long as: * The certificate of the package is also included in the :code:`public_certs_dir` directory. The matching is done using the fingerprint of the certificate; * The certificate of the Authority that has signed the certificate of the package is included in the :code:`public_certs_dir` directory. The matching is done using the :code:`authority_key_identifier` or :code:`issuer_subject_hash` attribute of the certificate. The signature of the certificate is verified using the :program:`x509.verification.CertificateVerificationContext` class; Process for signing a WAPT package ================================== The process for signing a WAPT package is launched with the following actions: * Action :command:`wapt-get.exe build-upload `. * Action :command:`wapt-get.exe sign-package `. * Saving a *host* package in the WAPT Console. * Editing or saving any package in the WAPT Console. * Importing a package from an external repository. * Creating a package with the setup wizard. Initial parameters ------------------ * ZIP file of the WAPT package. * :mimetype:`.pem` formated RSA private key of the certificate holder (encrypted with OpenSSL's *aes-256-cbc* algorithm if the key has been created in the WAPT Console). * *X509* certificate of the certificate holder matching the private key. * If the package to be signed contains a :file:`setup.py` file, then the *X509* certificate **MUST** have the *advanced Key Usage* extension *codeSigning (1.3.6.1.5.5.7.3.3)*; Signing the attributes in the control file ------------------------------------------ The :file:`control` file defines the metadata of a WAPT package and in particular its name, its version, its dependencies and its conflicts. It is the identity card of the WAPT package. These metadata are primarily used by the WAPT Agent to determine whether a package must be upgraded, and what packages must be first installed or removed. The package attributes are therefore signed to insure the integrity and the authenticity of the WAPT package. Process steps: * The attributes :code:`signed_attributes`, :code:`signer`, :code:`signature_date`, :code:`signer_fingerprint` are added to the structure of the :file:`control` file: - :code:`signed_attributes`: comma separated list of the names of the attributes taken in account in the signature; - :code:`signer`: CommonName of the certificate holder for information; - :code:`signature_date`: current date and time (UTC) in '%Y-%m-%dT%H:%M:%S format; - :code:`signer_fingerprint`: hexadecimal encoded *sha256* fingerprint of the signer's certificate obtained with the :program:`fingerprint` function included in the :program:`cryptography.x509.Certificate` class. * The signed attributes of the control structure are JSON encoded without space and line feed, and sorted in alphabetical order. * The resulting JSON :abbr:`BLOB (Binary Large Object)` is signed with *sha256* hashing and *PKCS#1 v1.5* padding. * The signature is base64 encoded and stored as a :code:`signature` attribute in the :file:`control` file. Signing the files of the package -------------------------------- * The :file:`control` file attributes are signed and serialized in :mimetype:`JSON` format. The result is stored in the :file:`\\control` file of the WAPT package. * The PEM serialized X509 certificate of the certificate holder is stored in the :file:`\\certificate.crt` file of the WAPT package. * The *sha256* fingerprints of the all files contained in the WAPT package are hexadecimal encoded and stored as a JSON list [(filename,hash),] in the :file:`\\manifest.sha256` file in the WAPT package. * The content of the file :file:`\\manifest.sha256` is signed with the private key of the :term:`Administrator` (2048 bit RAS key), *sha256* hashed and *PKCS#1 v1.5* padded: - The signature process relies on the signing function of the :program:`cryptography.rsa.RSAPrivateKey.signer` class. - :program:`cryptography.rsa.RSAPrivateKey.signer` relies on the OpenSSL functions of :program:`EVP_DigestSignInit`. * The signature is base64 serialized and stored in the file :file:`\\signature.sha256` of the WAPT package. Verifying the signature of a package attributes =============================================== The verification takes place: * When the :file:`index` file of available packages on the WAPT client is updated from the :file:`Packages` index file on the repository. * When a package signature is verified (installation, download) when not in *development* mode, i.e. if the installation takes place from a ZIP file and not from a development directory. The verification consists of: * Reading the control attributes from the WAPT package's :file:`control` file. * Recovering the X509 certificate from the certificate holder from the WAPT package's :file:`certificate.crt` file. * Decoding the base64 formated signature attribute. * Constructing a JSON structure with the attributes to be signed (such as defined in the :program:`PackageEntry` class). * Verifying if the public key of the holder's certificate can verify the hash of the JSON structured list of attributes and the signature of the :file:`control` file, using *sha256* hashing and *PKCS#1 v1.5* padding. * Verifying whether the certificate is trusted (either it is present in the list of trusted certificates, or signed by a Trusted :term:`Certificate Authority`). In case we must verify the attributes without having the WAPT package on hand, we recover the list of certificates of potential certificate holders from the :file:`Packages` index file on the WAPT repository. The certificates are named :file:`ssl/.crt`. An attribute in the WAPT package's :file:`control` file specifies the fingerprint of the :file:`control` file's certificate holder. Verifying the signature of a WAPT package ========================================= The verification takes place: * When installing a WAPT package on a WAPT client. * When editing an existing WAPT package. * When importing a WAPT package from an external repository (if the checkbox is checked in the WAPT Console). The verification consists of: * Recovering the X509 certificate of the certificate holder from the WAPT package's :mimetype:`.crt` file. * Verifying that the certificate has been signed by a Trusted Authority whose certificate is present in the folder :file:`ssl` on the WAPT client. * Verifying the signature of the file :file:`manifest.sha256` with the public key. Signing immediate actions ========================= From the WAPT Console, the :term:`Administrators` may launch actions directly on the WAPT clients connected with the WAPT Server using Websockets. The WAPT Console signs these actions with the key and certificate of the :term:`Administrator` before sending them to the WAPT Server using an HTTPS POST request; the request is then forwarded to the targeted WAPT clients. Possible immediate actions are: * :command:`trigger_host_update`. * :command:`trigger_host_upgrade`. * :command:`trigger_install_packages`. * :command:`trigger_remove_packages`. * :command:`trigger_forget_packages`. * :command:`trigger_cancel_all_tasks`. * :command:`trigger_host_register`. * :command:`start_waptexit`. * :command:`show_message`. * :command:`trigger_host_update_server_status`. * :command:`trigger_change_description`. * :command:`trigger_waptservicerestart`. * :command:`unregister_computer`. * :command:`trigger_gpupdate`. * :command:`trigger_waptwua_scan`. * :command:`trigger_waptwua_download`. * :command:`trigger_waptwua_install`. * :command:`trigger_waptwua_uninstall`. * :command:`trigger_host_audit`. * :command:`trigger_audit_packages`. * :command:`trigger_cleanmgr`. * :command:`trigger_host_reboot`. * :command:`trigger_host_shutdown`. * :command:`trigger_session_setup`. * :command:`run_wol`. * :command:`get_tasks_status`. Signing process for immediate actions ------------------------------------- * The action is defined by its name and the actions attributes. The attributes are *uuid*, *action*, *force*, *notify_server*, and *packages* (for actions implicating a list of packages). * The attributes :code:`signed_attributes`, :code:`signer`, :code:`signature_date`, :code:`signer_certificate` are added to the structure of the action: - :code:`signed_attributes` list of the attributes that are signed. - :code:`signer` Subject.COMMON_NAME of certificate holder. - :code:`signature_date`: current date and time (UTC) in '%Y-%m-%dT%H:%M:%S' format. - :code:`signer_certificate` certificate holder's base64 encoded *X509* certificate. * The structure is JSON encoded. * The signature of the JSON file is calculated from the RSA private key of the :code:`signer` using a *sha256* hash algorithm and a *PKCS1 v1.5* padding. * The signature is base64 encoded and stored on the :code:`signature` attribute inside the JSON file. Verifying the signature of an immediate action ---------------------------------------------- From the WAPT Console, the :term:`Administrators` may launch actions directly on the WAPT clients connected with the WAPT Server using Websockets. The actions are JSON encoded, signed with the key and certificate of the :term:`Administrator`, and relayed to the targeted WAPT clients by the WAPT Server. The action :command:`get_tasks_status` does not require SSL authentication. Upon receiving an event on the Websocket connexion of the WAPT client: * The X509 certificate of the certificate holder is extracted from the JSON file (format PEM). * The WAPT client tests whether the certificate is to be trusted, i.e. that it is present in :file:`\\ssl` or that it has been signed by a Trusted Authority (certificate of the Authority present in :file:`\\ssl`). * The WAPT client checks whether the certificate can verify the signature that is present in the JSON structure of the action, which consists of: - Extracting the base64 encoded signature from the :code:`signature` attribute in the JSON file. - Extracting the signature date formated in '%Y-%m-%dT%H:%M:%S' from the :code:`signature_date` attribute. - Checking that the signature date is neither too old in the past, nor too late into the future by over 10 minutes. - Reconstructing a JSON representation of the attributes of the action. - Checking that the certificate's public key can verify the JSON file with the signature by using a *sha256* hash algorithm and a *PKCS1 v1.5* padding. Verifying the complete download of a WAPT package ================================================= For each WAPT package, a *md5* sum of the file is calculated and stored in the :file:`Packages` index file on the repository. When installing a WAPT package, the WAPT client checks whether a local version of the WAPT package is already available in the cache directory :file:`\\cache`. If the package file is cached, its *md5* sum is calculated and compared with the *md5* sum in the index file. If they are different, the cached WAPT package is deleted. .. important:: **This md5 sum is only used to insure that a WAPT package has been fully downloaded**. The checking of the signature of the WAPT package will be used instead of the *md5* sum to fully insure the integrity and the authenticity of the WAPT package.