.. 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 the security principles in WAPT ############################################### .. figure:: wapt-resources/cyber-security.png :align: center :alt: Logo Cybersecurity Here are documented the advanced security principles included in WAPT. The reading of this portion of the documentation is not essential for your daily usage of WAPT; it is however recommended for you to better understand some architectural choices made by the developers of the software. .. _security_principles: ************************ Preamble and definitions ************************ .. attention:: The WAPT service operates as a **privileged** system account. .. attention:: From WAPT version 1.5, the default installation directory becomes :file:`C:\\Program Files (x86)\\wapt`. .. hint:: the sub-components :program:`wapttray`, :program:`waptservice` and :program:`waptexit` of the WAPT agent may be optionally deactivated according to usage context. ******************* Perimeter to secure ******************* The elements to secure and that strictly concern WAPT are: * **The WAPT Server** (*waptserver*). * **The WAPT agents** (*wapt-get*) and its sub-components (*wapttray*, *waptservice* et *waptexit*). * **The management console** (*waptconsole*). * **The network communications** between these different components. In complement to the elements listed above, an :term:`Organization` that uses WAPT will have to choose and follow a methodology that is adapted to her use case: * Insure the safe provisioning of all other files that are to be incorporated into a WAPT package. * Develop the WAPT package python :file:`setup.py` script so as to avoid any exploitable security or confidentiality defect. * Manage in a safe way the private keys for signing the packages. * Manage in a safe way the Authorities of Certification and Revocation for the SSL and HTTPS certificates. The safe management of these complementary elements is excluded from the perimeter of this documentation. **************************** Description of typical users **************************** The following roles must be understood to evaluate the security principles incorporated in WAPT: * **User** A *User* is an individual/ user of a WAPT equipped end-device (**Enterprise** and **Discovery**). * **Package Deployer** A *Package Deployer* is an individual with the ability to sign packages that **DO NOT** contain python code (generally *group*, *host* and *unit* packages) and with the ability to upload the package to the main repository (**Enterprise**). * **Package Developer** A *Package Developer* is an individual with the ability to sign any package, may it include or not include python code, and to upload the package to the main repository (**Enterprise**); .. note:: The distinction between *Package Deployer* and *Package Developer* only exists in the **Enterprise** version of WAPT. * **SuperAdmin** The *SuperAdmin* is an individual with all rights within WAPT. * **Local Administrator** A *Local Administrator* is an individual with local administration right of the WAPT equipped end-devices (**Enterprise** and **Discovery**); .. note:: Depending on the context within this documentation, an :term:`Administrator` will have the meaning of a :term:`Package Deployer`, :term:`Package Developer` or :term:`SuperAdmin`. .. note:: The :term:`Users` that are members of the Active Directory security group **waptselfservice** are considered to be :term:`Local Administrators` from the point of view of WAPT security. ******************************************* Description of the sensitive assets in WAPT ******************************************* By definition, a sensitive asset is a data (or a function) that is considered as having value to an attacker. Its value is estimated according to several security criteria (also called security needs): * Availability; * Integrity; * Confidentiality; * Authenticity. The sensitive assets to protect are as follows: Sensitive assets A1: communications =================================== Communications between the central WAPT Server and the WAPT agents, as well as the communications between the WAPT console and the WAPT Server are a sensitive asset and they must be protected. .. note:: Need for securing the communications * Integrity; * Confidentiality; * Authenticity. Sensitive asset A2: inventory data ================================== The informations on the state of deployment of the packages, as well as hardware and software configurations of the end-devices are a sensitive asset and they must be protected. .. note:: Security need of the inventory data * Integrity; * Confidentiality. Sensitive asset A3: log journals ================================ The logs generated by WAPT on the central server and by the agents are a sensitive asset and they must be protected. .. note:: Security needs of historical logs * Availability. Sensitive asset A4: configuration values ======================================== The configuration values (HTTPS server keys, database access configuration, server authentication configuration) are sensitive and they must be protected. .. note:: Security needs of configuration values * Integrity; * Confidentiality. Sensitive asset A5: WAPT executables on the end-devices ======================================================= The WAPT executables installed on managed clients are a sensitive asset and they must be protected (i.e. the content of the :file:`` directory that includes the binaries, the configuration files and the local database). .. note:: Security needs of configuration values * Integrity. Sensitive asset A6: authentication ================================== Authentication to the administration console as well as the authentication of the clients on the WAPT Server are a sensitive asset and they must be protected (public key of each WAPT agent). .. note:: Security need of the authentication * Integrity; * Confidentiality. ******************************************************* Description of hypotheses on WAPT's working environment ******************************************************* By definition, the hypotheses are statements on WAPT's usage context or its working environment. The following hypotheses on WAPT's working environment must be considered: Hypothesis H1: the Administrators and the Package Deployers are trained ======================================================================= The :term:`Administrators` and the :term:`Package Deployers` are trained on WAPT usage. In particular, they must insure that their logins, passwords and private keys are kept secret. Hypothesis H2: the operating systems underlying WAPT are sane ============================================================= WAPT's underlying operating systems implement adequate protection mechanisms that are configured according to good practice (confinement, access control, etc). The underlying operating system are patched and up to date at the time of the installation of WAPT, they are free of viruses, trojan horses, etc. Hypothesis H3: the binaries necessary for WAPT to operate are sane ================================================================== All libraries and tools necessary to install WAPT are considered to be sane. Upon the WAPT agent receiving a request, the agent verifies that the request has been properly signed. Hypothesis H4: the WAPT packages are built in a safe manner =========================================================== The :term:`Administrator` is responsible for insuring that the files to be incorporated into a WAPT package come from safe sources and are free of viruses, trojan horses, etc. Hypothesis H5: the Users of the end-devices are not Local Administrators ======================================================================== A :term:`User` must not have local administration rights on the WAPT equipped device. Otherwise, the :term:`User` must be considered a :term:`Local Administrator`. In particular, a :term:`User` must not have write access to WAPT's installation directory. Hypothesis H6: the Local Administrators are trained =================================================== The :term:`Local Administrator` of a device must be trained to use WAPT, or at minimum he must not make changes to files located in WAPT's installation folder. ************************************************* Description of threats on WAPT's sensitive assets ************************************************* By definition, a threat is an action or an event susceptible to bring prejudice to the security of the WAPT equipped device. The threat agents to be considered for evaluating security in WAPT are as follows: * **Unauthorized entities**: it is a human attacker or an entity that interacts with WAPT without legitimately having access to it. .. note:: The :term:`Administrators` and the :term:`Local Administrators` are not considered to be attackers. The threats bearing on WAPT's sensitive assets defined above are as follow: Threat T1: installation of an unsafe software by an unauthorized entity ======================================================================= This threat corresponds to an attacker that would be able to use a component of the WAPT agent to permanently install a malicious application, or to remove or deactivate a security component on the WAPT equipped device. Threat T2: modification of configuration values by an unauthorized entity ========================================================================= The threat corresponds to an attacker that would be able to modify a configuration element of WAPT that had been previously defined by a legitimate WAPT :term:`Administrator`. Threat T3: illegitimate access by an unauthorized entity ======================================================== This threat corresponds to an attacker that would be able to recover the login credentials of an :term:`Administrator`, or bypass the authentication mechanism in such a way to access or alter a sensitive asset stored on the server. It also corresponds to an attacker being able to impersonate a WAPT agent. Threat T4: network listening by an unauthorized entity ====================================================== This threat corresponds to an attacker being able to intercept and gain knowledge of network traffic between the WAPT agents and the server hosting WAPT. Threat T5: modification of network traffic by an unauthorized entity (type *Man In The Middle*) =============================================================================================== This threat corresponds to an attacker being able to alter network traffic between the agents and the server hosting WAPT, or between the console and the WAPT Server. **************************************** Description of WAPT's security functions **************************************** By definition, security functions are the set of technical measures and mechanisms implemented to protect in a proportionate way the sensitive assets against identified threats. Security function F1: access authentication =========================================== .. _initial_machine_registration: Security function F1A: authentication of a device on initial registration in the WAPT database ---------------------------------------------------------------------------------------------- .. versionadded:: 1.5 .. note:: risks avoided * The registering of an illegitimate device in the database. * A denial-of-service attack by overloading the database. * The insertion of a fraudulent inventory in the database. Solution implemented ^^^^^^^^^^^^^^^^^^^^ To exist in the database and thus to appear in the management console, a device must register with the WAPT Server using the :command:`register` command. The :command:`register` command may be executed automatically when installing or updating the WAPT agent if the device has a kerberos machine account that is correctly registered in the :term:`Organization`'s Active Directory domain. If the device does not present to the WAPT Server a valid kerberos ticket, then the :command:`register` fails; .. note:: The kerberos registration method assumes that the Active Directory server is responsive at the time of launch of the :command:`register` command. .. _HTTPS_certificate_verification: Security function F1B: verification of server HTTPS certificates by the WAPT agents ----------------------------------------------------------------------------------- .. versionadded:: 1.5 .. note:: risks avoided (notably MITM) * The sending of sensitive informations to an illegitimate and unauthorized WAPT Server. * The recovery of sensitive informations by an unauthorized entity. * The display of fake information in the management console of the :term:`Administrator`. * An incorrect date to be sent upon a HEAD request, thus preventing future upgrades (request for a modified file date). * Sending the WAPT console password to an illegitimate and unauthorized WAPT Server. Solution implemented ^^^^^^^^^^^^^^^^^^^^ For the secured version of WAPT to work correctly: * An option for verifying the server HTTPS certificate is introduced in :file:`C:\\Program Files (x86)\\wapt\wapt-get.ini` on the WAPT agents that will **force the verification of the server certificate by the WAPT agents**. * An option for verifying the server HTTPS certificate is introduced in :file:`C:\\Program Files (x86)\\wapt\wapt-get.ini` on the WAPT agents that will force the verification of the server certificate by the **WAPT console**. Technically, it may be implemented in two ways: * By using a certificate verification tool implemented in the configuration file of WAPT's :program:`Nginx` web server; this method is typically provided by a :term:`Certificate Authority` that is trusted by your network. * By using the *certificate pinning* method, which consists of providing the WAPT agent a short list of trusted certificates that will be stored in :file:`C:\\Program Files (x86)\\wapt\\ssl\\server`. Security function F1C: no listening port on the WAPT agents ----------------------------------------------------------- .. versionadded:: 1.5 .. note:: risks avoided * An unauthorized entity using an open port fraudulently. Solution implemented ^^^^^^^^^^^^^^^^^^^^ The connections to the WAPT Server are initiated exclusively by the agents, and the forced immediate actions are relayed through a permanent websocket initiated by the WAPT agent (:command:`update`/ :command:`upgrade`/ :command:`install` ...). .. note:: if HTTPS is activated, then the WAPT agent checks that the websocket is connecting to the rightful server. .. _signing_inventory_updates: Security function F1D: signature of inventory return states ----------------------------------------------------------- .. versionadded:: 1.3.12.13 .. note:: risks avoided * An unauthorized entity sending a fake inventory for a device that rightfully exists in the database. Solution implemented ^^^^^^^^^^^^^^^^^^^^ * On the first :command:`register`, each device generates a key/ certificate pair that is stored in :file:`C:\\Program Files (x86)\\wapt\\private`, only accessible in read-only mode to :term:`Local Administrators`. Once the device has successfully registered, the public key is sent to the WAPT Server. * When the inventory is updated, the new inventory status is sent along with the private key of the device. The new inventory is then decrypted with the public key stored in the database. * The server will refuse any inventory that is signed with a wrong key. Security function F1E: verification of authorizations before launching of WAPT commands --------------------------------------------------------------------------------------- .. note:: risks avoided * Avoid the execution of sensitive tasks on WAPT clients by unauthorized entities. Solution implemented ^^^^^^^^^^^^^^^^^^^^ The :term:`Users` interact with WAPT through WAPT user interfaces (:program:`wapt-get` in command line interface, :program:`wapttray`, :program:`waptexit`, :program:`waptselfservice`). The user interfaces then delegate the execution of the desired tasks to the local WAPT service running as system account. The following actions do not require to be authenticated with the WAPT service: * :code:`wapt-get update` (update the available list of packages). * :code:`wapt-get upgrade` (launch waiting upgrades). * :code:`wapt-get download-upgrade` (download waiting upgrades). * :code:`wapt-get clean` (remove packages left in cache after installation). * stop any running WAPT task. * stop/ reload the WAPT service. The other actions require the :term:`User` be authenticated and the :term:`User` either be a member of the **waptselfservice** Active Directory security group, or be a :term:`Local Administrator`, they are: * :code:`wapt-get install`: requests the WAPT agent to install a WAPT package flagged as **MISSING**. * :code:`wapt-get remove`: requests the WAPT agent to remove a package. * :code:`wapt-get forget`: requests the WAPT agent to forget the existence of a previously installed WAPT package without removing the software or the configuration. .. _WAPT_package_installation_process_integrity: Security function F2: protecting the integrity of the installation process of WAPT packages =========================================================================================== Security function F2A: signature of WAPT packages ------------------------------------------------- .. note:: risks avoided * To avoid an unauthorized entity modifying the content or the behavior of a WAPT package. Solution implemented ^^^^^^^^^^^^^^^^^^^^ * When an :term:`Administrator` or a :term:`Package Deployer` builds a WAPT package, the file :file:`manifest.sha256` is created that lists the control sums of all files in the package. * A file :file:`signature.sha256` **encrypted** with the WAPT agent's private key is then created in the folder :file:`WAPT`; it contains the control sum of the file :file:`manifest.sha256`. * The whole is then compressed and suffixed with a :mimetype:`.wapt` extension. * When a WAPT agent downloads a WAPT package, the agent checks that the file :file:`signature.sha256` has been signed with the private key that matches the certificate present in the folder :file:`WAPT`. * The WAPT agent then checks that the certificate or the chain of certificates in :file:`certificate.crt` has been signed with a key matching one of the certificates present in the folder :file:`C:\\Program Files (x86)\\wapt\\ssl`. * The WAPT agent then generates the control sum of all the files contained in the package (except the files :file:`signature.sha256` and :file:`certificate.crt`) and verifies that it matches the file :file:`manifest.sha256` contained in the package. * If one of these steps does not pass, this means that a file has been modified/ added/ removed. The execution of the :file:`setup.py` is then canceled. * The altered package is then deleted from the local cache and the event is journalized in the logs of the agent. .. note:: Since the version 1.5 of WAPT, the format of the :file:`manifest` file has changed from *sha1* to *sha256*. Security function F2B: signature of the attributes in the control files ----------------------------------------------------------------------- .. versionadded:: 1.4 .. note:: risks avoided * An unauthorized entity modifying WAPT dependencies on WAPT equipped devices by falsifying :file:`https://waptserver/wapt/Packages`. Solution implemented ^^^^^^^^^^^^^^^^^^^^ When a WAPT package is signed, the sensitive attributes of the package are listed inside the **signed_attributes** attribute of the control file. .. note:: Example of a *signed_attributes* list: *package*, *version*, *architecture*, *section*, *priority*, *maintainer*, *description*, *depends*, *conflicts*, *maturity*, *locale*, *min_os_version*, *max_os_version*, *min_wapt_version*, *sources*, *installed_size*, *signer*, *signer_fingerprint*, *signature_date*, *signed_attributes*, The attributes listed in *signed_attributes* are signed with the private key of the :term:`Administrator` and stored in the attribute *signature* of the :file:`control` file. The certificate matching the private key is stored in :file:`WAPT\\certificate.crt` inside the WAPT package. On the WAPT Server, the index :file:`Packages` is regenerated when the :command:`wapt-scanpackages` command is triggered by adding or removing a package. The WAPT Server extracts from each package the certificate of the signer and adds it in the :file:`Packages` zip file in the directory :file:`ssl`. Each certificate is named after its hexadecimal encoded fingerprint. When the WAPT agent launches an :command:`update`, it downloads the :file:`Packages` index file that contains the signed attributes of all available packages and the certificates of the signers. If the signer's certificate is approved, which means that the certificate has been signed by a Trusted :term:`Certificate Authority` or that the certificate itself is trusted, AND if the signer's certificate can verify the attributes' signature, the package is added to the index of available packages. Otherwise it is ignored. Security function F2C: access restriction to the installation folder of the WAPT agent -------------------------------------------------------------------------------------- .. note:: risks avoided * An unauthorized entity modifying the behavior of a WAPT agent. The installation folder :file:`C:\\Program Files (x86)\\wapt` is accessible in read-write mode: * To the :term:`Local Administrators` by direct access to the installation folder of the WAPT agent on the device. * To the :term:`Administrators` through the deployment of WAPT agent upgrades. Neither the :term:`Package Deployers`, nor the :term:`Users` have write-access to the WAPT agent's installation folder. Security function F2D: total access restriction to the folder storing the key / certificate for inventory signing ----------------------------------------------------------------------------------------------------------------- .. note:: risks avoided * An unauthorized entity falsifying an inventory status update. * An unauthorized entity impersonating the identity of a WAPT equipped device. No access right is granted to any :term:`User` to :file:`C:\\Program Files (x86)\\wapt\\private`, whomever he may be. Only the WAPT agent has a write and read access to this folder. .. note:: This method for storing the key and the certificate results from a technical design choice that says that the WAPT equipped device would embed any and all information related to itself. Security function F3: securing the communications between the different components of WAPT ========================================================================================== .. _signing_actions_relayed_to_WAPT_agents: Security function F3A: signature of immediate action calls sent to the WAPT agents ---------------------------------------------------------------------------------- .. versionadded:: 1.5 .. note:: risks avoided * An unauthorized entity sending falsified requests to the WAPT agents. Solution implemented ^^^^^^^^^^^^^^^^^^^^ The following commands are signed by the WAPT Server before being relayed to the targeted WAPT agents via their Websockets: * :code:`wapt-get install`: requests the WAPT agent to install a WAPT package flagged as **MISSING**. * :code:`wapt-get remove`: requests the WAPT agent to remove a package. * :code:`wapt-get forget`: requests the WAPT agent to forget the existence of a previously installed WAPT package without removing the software or the configuration. * :code:`wapt-get update-status`: requests the WAPT agent to send its current inventory status to the WAPT Server. * :code:`wapt-get upgrade`: requests the WAPT agent to execute a package flagged as **NEED UPGRADE**. * :code:`wapt-get update`: requests the WAPT agent to update the list of available packages. All the attributes in the requests for immediate action are signed: * The device's :term:`UUID`; * The action (ex: :command:`install`); * The arguments (ex: tis-firefox); * The timestamp of the requests. The certificate matching the signature is passed along: * Upon receiving a request, the WAPT agent verifies that the request has been properly signed. * The agent will the verify that the timestamp is within a one minute delay window. * Ultimately, the agent will verify that the certificate is authorized to launch actions. .. _wapt_crypto_principles: *************************************** Presentation of cryptographic processes *************************************** +------------------------+----------------+ | Date | |today| | +------------------------+----------------+ | Written by | Hubert TOUVET | +------------------------+----------------+ | Applicable for WAPT | >= 1.5.0.17 | +------------------------+----------------+ | Version of the Document| 1.5.0.17-0 | +------------------------+----------------+ .. 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 clients. * Signature of inventories and **status of WAPT clients**. * Authentication of the WAPT client Websocket connections on the WAPT server. * HTTPS communication between the WAPT clients and the WAPT Server. * HTTPS communication between the WAPT console and the WAPT Server. * HTTPS communication between the WAPT clients and the WAPT repositories. Folders and files referenced in this document ============================================= * :file:``: WAPT installation folder. By default :file:`%Program Files (x86)%\WAPT`. * :file:`\wapt-get.ini`: WAPT client configuration file (:program:`wapt-get` and :program:`waptservice`). * :file:`\ssl`: default directory for signed actions and trusted certificates. * :file:`\ssl\server`: default directory for storing HTTPS server certificates (pinning). * :file:`\private`: default certificate directory for signing the inventory and the Websocket connections. * :file:`%LOCALAPPDATA%\waptconsole\waptconsole.ini`: configuration file for the 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 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 clients** 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 machine 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 ========================================= .. todo:: sfonteneau On the client side of WAPT (WAPT 1.5.0.12): * **Python 2.7.13** standard *ssl* module linked on :program:`OpenSSL 1.0.2j 26 Sep 2016`: used for the HTTPS connections between the WAPT clients and the WAPT server. * **cryptography==1.9** linked on :program:`openssl 1.1.0f`: used for all RSA crypto operations such as key generations, X509 certificate generations and signature verifications. * **kerberos-sspi==0.2** and **requests-kerberos==0.11.0**: used for authenticating the WAPT client on its first registering on the WAPT Server. * **pyOpenSSL==17.0.0**: used to recover the WAPT Server certificate chain. * **certifi==2017.4.17**: used as base for the Root Authorities certificates. * **Openssl 1.0.2l** dll: used in waptcommon.pas written with the FPC Indy library and the TIdSSLIOHandlerSocketOpenSSL class. On the server side of WAPT: * **nginx/1.10.2**: configured for TLS1.2, cipher 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH'. * **python 2.7.5** standard *ssl* module linked on :program:`OpenSSL 1.0.1e-fips 11 Feb 2013`. * **cryptography==1.9** linked on :program:`OpenSSL 1.0.1e-fips 11 Feb 2013`: used for all RSA crypto operations such as key generations, X509 certificate generations and signature verifications. 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 *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 *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 ------------------------------------------- For WAPT version up to 1.5.0.12, WAPT agent does not verify the revocation state of the :term:`Administrator`'s certificate during the process of verifying the package, the attributes or the actions of the :term:`Administrator`. It only checks the dates of validity (*notValidBefore*/ *notValidAfter* attributes). The certificate is valid if (**Now** >= *notValidBefore* and **Now** <= *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 :file:`.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 client (:program:`waptservice`) uses RSA keys and X509 certificates to interact with the WAPT Server. The WAPT client certificate is used in the following situations: * When updating the WAPT client status on the server (:command:`update_server_status`) **signing informations**. * When the WAPT agent establishes a Websocket with the 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 machine 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: * *Subject.COMMON_NAME* = . * *Subject.ORGANIZATIONAL_UNIT_NAME* = name of the :term:`Organization` registered in the WAPT client's Windows registry. * *SubjectAlternativeName.DNSName* = . * *BasicConstraint.CA* = True. * *Validity* = 10 years. * *Serialnumber* = random; * The certificate is saved in the :file:`\private\.crt`. .. note:: Only machine accounts and :term:`Local Administrators` have access to the :file:`\private` directory because specific ACLs 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 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* or UUID of the WAPT Client. * After having initially authenticated the WAPT client with kerberos, the WAPT Server receives the certificate sent by the Client and stores it in the table *hosts* of its inventory in PEM format (column *host_certificate*). .. 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 certificate 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 ``public_certs_dir`` parameter in the :file:`\wapt-get.ini` file. They are reputed to be **trusted certificates**. The ``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 console, the :term:`Administrator` compiles 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. *verify_cert* parameter in section ``[global]`` in :file:`\wapt-get.ini`: * *verify_cert* = 1 this method will only work well if the HTTPS server is configured to send its certificate and the intermediary certificates upon initialization of the TLS connexion. * *verify_cert* = check the HTTPS certificate using the indicated bundle of certificates. All the certificates of the intermediary Certificate Authorities must be bundled in a *.pem* formated file; * *verify_cert* = 0 do not verify the HTTPS certificate of the 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 server certificate chain. The function stores it in *.pem* format in :file:`\ssl\server\`. The :term:`Administrator` is responsible for insuring that the recovered certificate chain is **authentic**. During the compilation 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 *verify_cert* parameter in section``[global]`` in :file:`\wapt-get.ini` is filled out to indicate the path to the 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 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 ------------------------------------------------------ *verify_cert* parameter in section ``[global]`` in file :file:`%LOCALAPPDATA%\waptconsole\waptconsole.ini`: * *verify_cert* = 1 this method will only work well if the HTTPS server is configured to send its certificate and the intermediary certificates upon initialization of the TLS connexion. * *verify_cert* = check the HTTPS certificate using the indicated bundle of certificates. All the certificates of the intermediary Certificate Authorities must be bundled in a *.pem* formated file; * *verify_cert* = 0 do not verify the HTTPS certificate of the 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 server certificate chain and that stores it in *.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 server certificate chain and fill out the *verify_cert* parameter with the command line :code:`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 *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 *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 *.pem* format and stored in files with *.pem* or *.crt* extensions. It is possible to store several certificates in each :file:`.crt` or :file:`.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 *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 *public_certs_dir* directory. The matching is done using the *issuer_subject_hash* attribute of the certificate. The signature of the certificate is done using the :program:`x509.verification.CertificateVerificationContext` class; Process for signing a package ============================= The process for signing a package is launched with the following actions: * action :code:`wapt-get.exe build-upload `. * action :code:`wapt-get.exe sign-package `. * shell command :code:`wapt-signpackage.py `. * saving a *host* package in the WAPT console. * saving a *group* package in the WAPT console. * importing a package from an external repository. * creating a package with the MSI setup wizard. Initial parameters ------------------ * ZIP file of the package; * *.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 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 *signed_attributes*, *signer*, *signature_date*, *signer_fingerprint* are added to the structure of the :file:`control` file: * *signed_attributes*: comma separated list of the names of the attributes; * *signer*: CommonName of the certificate holder; * *signature_date*: current date and time (UTC) in '%Y-%m-%dT%H:%M:%S format; * *signer_fingerprint*: hexadecimal encoded ``sha256`` fingerprint of the fingerprint obtained with the :program:`fingerprint` function included in the :program:`cryptography.x509.Certificate` class. * The attributes of the control structure are JSON encoded. * 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 *signature* attribute in the :file:`control` file. Signing the files of the package -------------------------------- * The :file:`control` file attributes are signed and serialized in 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 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 package on a WAPT client. * When editing an existing package. * When importing a package from an external repository (if the checkbox is checked in the WAPT console). The verification consists of: * Recovering the X509 certificate from the certificate holder from the WAPT package's :file:`certificate.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`. 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 *signed_attributes*, *signer*, *signature_date*, *signer_certificate* are added to the structure of the action: * *signed_attributes* list of the attributes that are signed. * *signer* Subject.COMMON_NAME of certificate holder. * *signature_date*: current date and time (UTC) in '%Y-%m-%dT%H:%M:%S' format. * *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 *signer* using a *sha256* hash algorithm and a *PKCS1 v1.5* padding. * The signature is base64 encoded and stored on the *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. 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`. 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 *signature* attribute in the JSON file; * Extracting the signature date formated in '%Y-%m-%dT%H:%M:%S' from the *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 package ============================================ For each package, a *md5* sum of the package is calculated and stored in the :file:`Packages` index file of the repository. When installing a package, the WAPT client checks whether a local version of the 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 package is deleted. **This md5 sum is only used to insure that a package has been fully downloaded**. The checking of the signature of the package will be used instead of the md5 sum to fully insure the integrity and the authenticity of the WAPT package.