Thierry  Perret

Thierry Perret

1659807540

Top 11 Des Erreurs D'authentification Et Comment Les Corriger

La sécurité de l'authentification est un aspect essentiel du développement d'applications Web qui est souvent négligé lors de la création d'un produit. Cependant, si vous avez l'intention de soumettre votre candidature en ligne, c'est une priorité absolue. Dans cet article, je vais vous expliquer certaines de ces erreurs et comment les corriger. Veuillez noter que ce ne sont pas les principaux problèmes de sécurité recommandés par l' OWASP ; au lieu de cela, ce sont les problèmes faciles à résoudre que je vois fréquemment.

Qu'est-ce que l'authentification ?

L'authentification est le processus de confirmation de l'identité d'un utilisateur ou d'un processus. Lorsque l'authentification est violée, les attaquants peuvent accéder aux données ou aux informations de l'utilisateur, causant des dommages à votre application. L'authentification est l'un des moyens par lesquels les attaquants peuvent accéder aux données d'un utilisateur et à votre application.

En matière d'authentification, voici les onze erreurs courantes à éviter :

  1. Affichage de messages d'erreur spécifiques
  2. Intégration des identifiants de session dans une URL
  3. Validation de formulaire incorrecte
  4. Assainissement de forme basse
  5. Stratégie de mot de passe faible
  6. Non-utilisation de l'authentification à deux facteurs (2FA)
  7. Réinitialisation incorrecte du mot de passe
  8. Déconnexion non sécurisée
  9. Attaque de force brute
  10. Utiliser des questions de sécurité faible
  11. Non-sécurisation de l'itinéraire

Affichage de messages d'erreur spécifiques

L'affichage d'un message d'erreur spécifique est dangereux car il pourrait permettre à un attaquant d'utiliser une méthode automatisée d'essais et d'erreurs pour déterminer le nom d'utilisateur ou le mot de passe d'un utilisateur.

Voici un exemple de schéma d'affichage d'un message d'erreur spécifique. 

première

Lors de l'authentification d'un formulaire sur votre application Web, vous devez veiller à ne pas afficher un seul message d'erreur lorsqu'un utilisateur saisit un détail incorrect, tel que "Votre mot de passe est incorrect". Si vous affichez un message d'erreur spécifique comme celui-ci, l'attaquant se rendra compte que l'adresse e-mail ou l'ID utilisateur est réel mais que le mot de passe est erroné. Cela permettrait à l'attaquant de suggérer un mot de passe pour cet utilisateur.

Comment réparer ce défaut

  • Ne jamais afficher un message d'erreur spécifique sur la page d'authentification. Cela permet à l'attaquant de savoir quelles informations manquent et lui permet d'utiliser une attaque par force brute pour deviner quelles informations manquent.
  • Afficher des messages d'erreur tels que "détails incorrects".

Intégration des identifiants de session dans une URL

Un ID de session est un numéro que le serveur d'un site Web attribue à un seul utilisateur pour la durée de la visite de cet utilisateur. Les chances qu'un attaquant obtienne et abusent d'un jeton de session sont augmentées s'il est placé directement dans l'URL. Bien que le risque soit moindre lors de l'utilisation de HTTPS pour se connecter au serveur Web, il existe toujours un danger. Même si les URL HTTPS sont chiffrées en transit, elles sont souvent conservées dans les journaux du serveur.

Voici un exemple de diagramme d'intégration des identifiants de session dans les URL.

2

Comment réparer ce défaut

  • Valider l'ID de session côté serveur
  • Pour créer le jeton, assurez-vous d'utiliser un générateur aléatoire suffisamment sûr.
  • Utilisez un filtre pour supprimer l'ID de session d'une URL.

Validation de formulaire incorrecte.

Des attaques par injection, des fuites de mémoire et des systèmes compromis peuvent se produire si les données fournies dans une entrée de formulaire ne sont pas correctement vérifiées ou formatées. Les utilisateurs soumettent souvent sans remplir toutes les informations nécessaires, il est donc nécessaire de valider votre formulaire pour vous assurer que toutes les informations requises ont été remplies avant de le soumettre au serveur.

Comment réparer ce défaut

  • Assurez-vous que l'e-mail a un format d'adresse e-mail.
  • Assurez-vous que l'utilisateur répond aux critères du formulaire avant de le soumettre
  • Validez le formulaire depuis le backend et le frontend à l'aide d'une bibliothèque ou d'un framework mis à jour.

Certaines des bibliothèques suggérées que je recommande pour la validation de formulaire sont :

Toutes les bibliothèques répertoriées sont bonnes pour valider votre formulaire.

Assainissement sous forme basse 

Le processus consistant à garder votre entrée de formulaire propre, filtrée et nettoyée d'un agent malveillant est connu sous le nom de nettoyage de formulaire. La désinfection de votre entrée est indispensable car elle évite les défauts d'injection. Un formulaire de saisie bien nettoyé peut empêcher les attaques suivantes :

Cross-site scripting (XSS) : il s'agit d'un type de vulnérabilité de sécurité que l'on trouve souvent dans les applications Web. Cette vulnérabilité permet aux attaquants d'insérer des scripts côté client dans les pages Web consultées par les utilisateurs. Cette attaque peut nuire à la sécurité d'un utilisateur, par exemple en le redirigeant vers un site Web malveillant, en le forçant à télécharger une application malveillante et en volant les données de l'utilisateur.

Injection SQL : les attaquants peuvent interférer avec les données envoyées à sa base de données via la saisie du formulaire. 

En nettoyant la saisie du formulaire, vous devez protéger votre code et les données de l'utilisateur de cet agent malveillant et de toutes les vulnérabilités répertoriées. Personnellement, j'utilise DOM Purify , une bibliothèque de nettoyage pour HTML et les chaînes, et elle peut filtrer tout ce qui contient du HTML sale et empêcher les attaques XSS.

Comment réparer ce défaut

  • Il est considérablement plus facile et plus sûr d'utiliser une liste d'autorisation pour des entrées bien définies telles que des nombres, des dates ou des codes postaux. À cet égard, vous pouvez indiquer explicitement quelles valeurs sont autorisées et quelles valeurs ne le sont pas.
  • Utilisez la logique de liste blanche prédéfinie dans les définitions de type de données intégrées avec la validation de formulaire HTML5.

Stratégie de mot de passe faible

Il n'est pas rare de tomber sur un site Web qui n'a pas de plan de mot de passe fort en ordre. J'ai récemment essayé une application qui nécessitait une longueur de mot de passe minimale de cinq caractères. Alors que les développeurs essaient de trouver le bon équilibre entre sécurité et convivialité, cette faille devient de plus en plus courante. Lorsque vous travaillez avec des mots de passe, assurez-vous que le mot de passe que vous suggérez à un utilisateur ou que le mot de passe créé par un utilisateur est un mélange de symboles, de chiffres et de lettres à casse mixte. Évitez les plans de mots de passe faibles.

Comment réparer ce défaut

  • Exiger qu'un utilisateur entre un minimum de 12 ou 8 caractères ou quelque chose de plus.
  • Les mots de passe incorporant des noms d'utilisateur ou des noms d'entreprise doivent être évités pour des raisons de sécurité et de convivialité.
  • Les lettres majuscules et minuscules doivent être mélangées.
  • Utilisez une bibliothèque pour calculer la force du mot de passe, soyez prudent lors de la sélection et vérifiez les dépendances et la maintenabilité minimales.
  • Lorsqu'une personne a un profil public, utilisez un nom d'affichage différent et évitez d'utiliser l'adresse e-mail de l'utilisateur comme nom d'affichage, car cela invite au spam.

Non-utilisation de l'authentification à deux facteurs

Une autre erreur courante que je vois avec les mécanismes d'authentification Web est qu'ils n'ont aucune mesure de sécurité supplémentaire. L'authentification à deux facteurs est rarement utilisée par les développeurs, en particulier pour les comptes les plus importants. L'authentification à deux facteurs permet d'ajouter une deuxième couche de protection à votre application. L'authentification à deux facteurs est essentielle pour la sécurité Web car elle élimine immédiatement les risques liés aux informations d'identification compromises. Lorsqu'un mot de passe est piraté, deviné ou même infecté par un logiciel malveillant, il ne suffit plus d'accorder l'accès à un intrus sans approbation au deuxième facteur d'authentification.

L'authentification à deux facteurs est une couche de sécurité supplémentaire ajoutée à une page d'authentification. Des exemples de cette authentification à deux facteurs sont les SMS, les e-mails et OTP.

Voici un exemple de schéma d'authentification à deux facteurs 

3

Comment mettre en œuvre l'authentification à deux facteurs

Il existe plusieurs façons d'utiliser le cryptage 2FA. Les jetons RSA, les générateurs de code comme Google Authenticator et Duo, et l'envoi de SMS de codes à usage unique sont toutes des options pour mettre en œuvre la technologie 2FA.

Réinitialisation incorrecte du mot de passe

Ce n'est pas si souvent, mais de temps en temps, je vois une application Web qui a cette capacité implémentée de manière incorrecte. Cela est souvent dû au fait que le mot de passe de l'utilisateur lui a été envoyé par e-mail ou que le jeton utilisé pour réinitialiser le mot de passe n'était pas assez fort. Le renvoi du mot de passe en clair à l'utilisateur final est un autre problème qui affecte les réinitialisations de mot de passe. C'est terrible pour diverses raisons, dont l'une est que le mot de passe a été envoyé par e-mail, ce qui est considéré comme dangereux. Cela pourrait signifier que le mot de passe a été stocké dans la base de données sans suffisamment de hachage ou dans un format pouvant être inversé, comme base64.

Le hachage  est une technique utilisée pour vérifier ou valider la qualité de divers types d'entrées. Dans les systèmes d'authentification, il est principalement utilisé pour empêcher le stockage de mots de passe en clair, et le hachage rend incroyablement difficile pour les attaquants de déchiffrer les mots de passe qui ont été stockés.

Base64 : Base64 est une méthode de conversion de données binaires en texte. La méthode est fréquemment utilisée pour envoyer des informations basées sur le contenu sur Internet.

Comment réparer ce défaut

  • Chiffrez toujours les mots de passe des utilisateurs avant de les stocker, ne les stockez pas sous leur forme brute.
  • N'envoyez des e-mails transactionnels qu'après avoir validé et vérifié les adresses e-mail en vérifiant les caractères valides et en envoyant un lien de vérification avec un jeton.

Déconnexion non sécurisée

Il s'agit d'une autre vulnérabilité qui peut causer de grands ravages à une application. Il est également essentiel de donner à vos utilisateurs un moyen sûr de se déconnecter afin que leurs sessions ne puissent pas être prises en charge. Si vous stockez l'identifiant de session côté serveur, la méthode de déconnexion doit l'invalider et effacer le cookie de session dans le navigateur. Cela empêche les attaquants de voler des cookies de session et de les utiliser ensuite pour démarrer une nouvelle session.

Comment réparer ce défaut

  • Lorsqu'un utilisateur se déconnecte, effacez le cookie de session du navigateur et invalidez l'identifiant de session s'il est stocké sur le serveur.
  • Lors de la déconnexion, les sessions utilisateur et les jetons d'authentification doivent être correctement invalidés.

Attaque de force brute

La force brute est une technique de piratage utilisée pour découvrir les informations d'identification de l'utilisateur en essayant diverses informations d'identification possibles. Dans cette attaque, les pirates essaient de deviner les mots de passe pour passer l'authentification pour un seul compte. En utilisant des scripts qui essaient de nombreux mots de passe couramment utilisés à partir d'un dictionnaire et des millions de mots de passe divulgués lors de violations de données précédentes, ces tentatives ont de meilleures chances de réussir.

Comment réparer ce défaut

  • Limitez les tentatives de connexion à une adresse ou plage IP définie en bloquant l'accès à l'URL d'authentification.
  • N'utilisez aucun terme de dictionnaires dans aucune langue. Plutôt que d'utiliser des mots, il est préférable d'utiliser des chaînes de caractères aléatoires.
  • Bloquez les adresses IP malveillantes avec CAPTCHAS.
  • Gardez une trace des tentatives de connexion infructueuses d'un utilisateur et verrouillez le compte.

Utiliser des questions de sécurité insuffisantes

Une question de sécurité ou un mot mémorable peut également aider à se prémunir contre les attaques automatisées. J'ai rencontré des questions de sécurité faibles qui ont des réponses prévisibles, permettant à un attaquant de suggérer ou de deviner des réponses et d'accéder aux données de l'utilisateur.

Voici quelques-unes des questions de sécurité les plus courantes que j'ai rencontrées :

  • Dans quelle ville êtes-vous né?
  • Quelle est votre date de naissance?
  • Quel lycée as-tu fréquenté ?
  • Quel est le nom de jeune fille de ta mère?

Évitez toutes ces questions car les pirates peuvent les deviner en raison de certaines de nos informations sur Google ou d'autres profils en ligne.

Comment réparer ce défaut

  • Recommander des questions faciles à retenir pour l'utilisateur mais difficiles à suggérer pour les attaquants
  • Stockez les réponses à l'aide d'un algorithme de hachage sécurisé tel que Bcrypt. Bcrypt est un algorithme utilisé pour hacher et vérifier les mots de passe. Cela aide à réduire le risque que des cybercriminels attaquent votre application via un mot de passe.

Non-sécurisation des itinéraires

Une autre erreur que j'ai vue commettre par les développeurs en matière d'authentification est "ne pas protéger la route". Il est essentiel de sécuriser des routes spécifiques dans votre application contre les utilisateurs non authentifiés, car cela empêchera les utilisateurs inconnus d'accéder à certaines des données privées de votre application.

Comment réparer ce défaut

  • Protégez la route à laquelle vous souhaitez que les utilisateurs non authentifiés accèdent.
  • Si un utilisateur tente d'accéder à une route spécifique, redirigez-le vers la page de connexion/inscription s'il n'est pas authentifié

Conclusion

Lors de la mise en œuvre de l'authentification sur votre site Web, vous devez faire preuve d'une extrême prudence en tant que développeur car certaines méthodes pourraient être très dommageables pour votre programme et ouvrir la porte à des attaquants pour prendre le contrôle des données des utilisateurs et de l'application. Espérons que cet article a mis en évidence ces erreurs et fourni des conseils sur la façon de les corriger.

Lien : https://blog.openreplay.com/11-authentication-mistakes-and-how-to-fix-them

#authentification

What is GEEK

Buddha Community

Top 11 Des Erreurs D'authentification Et Comment Les Corriger
Kaia  Schmitt

Kaia Schmitt

1659817260

SDK for Connecting to AWS IoT From A Device using Embedded C

AWS IoT Device SDK for Embedded C

Overview

The AWS IoT Device SDK for Embedded C (C-SDK) is a collection of C source files under the MIT open source license that can be used in embedded applications to securely connect IoT devices to AWS IoT Core. It contains MQTT client, HTTP client, JSON Parser, AWS IoT Device Shadow, AWS IoT Jobs, and AWS IoT Device Defender libraries. This SDK is distributed in source form, and can be built into customer firmware along with application code, other libraries and an operating system (OS) of your choice. These libraries are only dependent on standard C libraries, so they can be ported to various OS's - from embedded Real Time Operating Systems (RTOS) to Linux/Mac/Windows. You can find sample usage of C-SDK libraries on POSIX systems using OpenSSL (e.g. Linux demos in this repository), and on FreeRTOS using mbedTLS (e.g. FreeRTOS demos in FreeRTOS repository).

For the latest release of C-SDK, please see the section for Releases and Documentation.

C-SDK includes libraries that are part of the FreeRTOS 202012.01 LTS release. Learn more about the FreeRTOS 202012.01 LTS libraries by clicking here.

License

The C-SDK libraries are licensed under the MIT open source license.

Features

C-SDK simplifies access to various AWS IoT services. C-SDK has been tested to work with AWS IoT Core and an open source MQTT broker to ensure interoperability. The AWS IoT Device Shadow, AWS IoT Jobs, and AWS IoT Device Defender libraries are flexible to work with any MQTT client and JSON parser. The MQTT client and JSON parser libraries are offered as choices without being tightly coupled with the rest of the SDK. C-SDK contains the following libraries:

coreMQTT

The coreMQTT library provides the ability to establish an MQTT connection with a broker over a customer-implemented transport layer, which can either be a secure channel like a TLS session (mutually authenticated or server-only authentication) or a non-secure channel like a plaintext TCP connection. This MQTT connection can be used for performing publish operations to MQTT topics and subscribing to MQTT topics. The library provides a mechanism to register customer-defined callbacks for receiving incoming PUBLISH, acknowledgement and keep-alive response events from the broker. The library has been refactored for memory optimization and is compliant with the MQTT 3.1.1 standard. It has no dependencies on any additional libraries other than the standard C library, a customer-implemented network transport interface, and optionally a customer-implemented platform time function. The refactored design embraces different use-cases, ranging from resource-constrained platforms using only QoS 0 MQTT PUBLISH messages to resource-rich platforms using QoS 2 MQTT PUBLISH over TLS connections.

See memory requirements for the latest release here.

coreHTTP

The coreHTTP library provides the ability to establish an HTTP connection with a server over a customer-implemented transport layer, which can either be a secure channel like a TLS session (mutually authenticated or server-only authentication) or a non-secure channel like a plaintext TCP connection. The HTTP connection can be used to make "GET" (include range requests), "PUT", "POST" and "HEAD" requests. The library provides a mechanism to register a customer-defined callback for receiving parsed header fields in an HTTP response. The library has been refactored for memory optimization, and is a client implementation of a subset of the HTTP/1.1 standard.

See memory requirements for the latest release here.

coreJSON

The coreJSON library is a JSON parser that strictly enforces the ECMA-404 JSON standard. It provides a function to validate a JSON document, and a function to search for a key and return its value. A search can descend into nested structures using a compound query key. A JSON document validation also checks for illegal UTF8 encodings and illegal Unicode escape sequences.

See memory requirements for the latest release here.

corePKCS11

The corePKCS11 library is an implementation of the PKCS #11 interface (API) that makes it easier to develop applications that rely on cryptographic operations. Only a subset of the PKCS #11 v2.4 standard has been implemented, with a focus on operations involving asymmetric keys, random number generation, and hashing.

The Cryptoki or PKCS #11 standard defines a platform-independent API to manage and use cryptographic tokens. The name, "PKCS #11", is used interchangeably to refer to the API itself and the standard which defines it.

The PKCS #11 API is useful for writing software without taking a dependency on any particular implementation or hardware. By writing against the PKCS #11 standard interface, code can be used interchangeably with multiple algorithms, implementations and hardware.

Generally vendors for secure cryptoprocessors such as Trusted Platform Module (TPM), Hardware Security Module (HSM), Secure Element, or any other type of secure hardware enclave, distribute a PKCS #11 implementation with the hardware. The purpose of corePKCS11 mock is therefore to provide a PKCS #11 implementation that allows for rapid prototyping and development before switching to a cryptoprocessor specific PKCS #11 implementation in production devices.

Since the PKCS #11 interface is defined as part of the PKCS #11 specification replacing corePKCS11 with another implementation should require little porting effort, as the interface will not change. The system tests distributed in corePKCS11 repository can be leveraged to verify the behavior of a different implementation is similar to corePKCS11.

See memory requirements for the latest release here.

AWS IoT Device Shadow

The AWS IoT Device Shadow library enables you to store and retrieve the current state one or more shadows of every registered device. A device’s shadow is a persistent, virtual representation of your device that you can interact with from AWS IoT Core even if the device is offline. The device state is captured in its "shadow" is represented as a JSON document. The device can send commands over MQTT to get, update and delete its latest state as well as receive notifications over MQTT about changes in its state. The device’s shadow(s) are uniquely identified by the name of the corresponding "thing", a representation of a specific device or logical entity on the AWS Cloud. See Managing Devices with AWS IoT for more information on IoT "thing". This library supports named shadows, a feature of the AWS IoT Device Shadow service that allows you to create multiple shadows for a single IoT device. More details about AWS IoT Device Shadow can be found in AWS IoT documentation.

The AWS IoT Device Shadow library has no dependencies on additional libraries other than the standard C library. It also doesn’t have any platform dependencies, such as threading or synchronization. It can be used with any MQTT library and any JSON library (see demos with coreMQTT and coreJSON).

See memory requirements for the latest release here.

AWS IoT Jobs

The AWS IoT Jobs library enables you to interact with the AWS IoT Jobs service which notifies one or more connected devices of a pending “Job”. A Job can be used to manage your fleet of devices, update firmware and security certificates on your devices, or perform administrative tasks such as restarting devices and performing diagnostics. For documentation of the service, please see the AWS IoT Developer Guide. Interactions with the Jobs service use the MQTT protocol. This library provides an API to compose and recognize the MQTT topic strings used by the Jobs service.

The AWS IoT Jobs library has no dependencies on additional libraries other than the standard C library. It also doesn’t have any platform dependencies, such as threading or synchronization. It can be used with any MQTT library and any JSON library (see demos with libmosquitto and coreJSON).

See memory requirements for the latest release here.

AWS IoT Device Defender

The AWS IoT Device Defender library enables you to interact with the AWS IoT Device Defender service to continuously monitor security metrics from devices for deviations from what you have defined as appropriate behavior for each device. If something doesn’t look right, AWS IoT Device Defender sends out an alert so you can take action to remediate the issue. More details about Device Defender can be found in AWS IoT Device Defender documentation. This library supports custom metrics, a feature that helps you monitor operational health metrics that are unique to your fleet or use case. For example, you can define a new metric to monitor the memory usage or CPU usage on your devices.

The AWS IoT Device Defender library has no dependencies on additional libraries other than the standard C library. It also doesn’t have any platform dependencies, such as threading or synchronization. It can be used with any MQTT library and any JSON library (see demos with coreMQTT and coreJSON).

See memory requirements for the latest release here.

AWS IoT Over-the-air Update

The AWS IoT Over-the-air Update (OTA) library enables you to manage the notification of a newly available update, download the update, and perform cryptographic verification of the firmware update. Using the OTA library, you can logically separate firmware updates from the application running on your devices. You can also use the library to send other files (e.g. images, certificates) to one or more devices registered with AWS IoT. More details about OTA library can be found in AWS IoT Over-the-air Update documentation.

The AWS IoT Over-the-air Update library has a dependency on coreJSON for parsing of JSON job document and tinyCBOR for decoding encoded data streams, other than the standard C library. It can be used with any MQTT library, HTTP library, and operating system (e.g. Linux, FreeRTOS) (see demos with coreMQTT and coreHTTP over Linux).

See memory requirements for the latest release here.

AWS IoT Fleet Provisioning

The AWS IoT Fleet Provisioning library enables you to interact with the AWS IoT Fleet Provisioning MQTT APIs in order to provison IoT devices without preexisting device certificates. With AWS IoT Fleet Provisioning, devices can securely receive unique device certificates from AWS IoT when they connect for the first time. For an overview of all provisioning options offered by AWS IoT, see device provisioning documentation. For details about Fleet Provisioning, refer to the AWS IoT Fleet Provisioning documentation.

See memory requirements for the latest release here.

AWS SigV4

The AWS SigV4 library enables you to sign HTTP requests with Signature Version 4 Signing Process. Signature Version 4 (SigV4) is the process to add authentication information to HTTP requests to AWS services. For security, most requests to AWS must be signed with an access key. The access key consists of an access key ID and secret access key.

See memory requirements for the latest release here.

backoffAlgorithm

The backoffAlgorithm library is a utility library to calculate backoff period using an exponential backoff with jitter algorithm for retrying network operations (like failed network connection with server). This library uses the "Full Jitter" strategy for the exponential backoff with jitter algorithm. More information about the algorithm can be seen in the Exponential Backoff and Jitter AWS blog.

Exponential backoff with jitter is typically used when retrying a failed connection or network request to the server. An exponential backoff with jitter helps to mitigate the failed network operations with servers, that are caused due to network congestion or high load on the server, by spreading out retry requests across multiple devices attempting network operations. Besides, in an environment with poor connectivity, a client can get disconnected at any time. A backoff strategy helps the client to conserve battery by not repeatedly attempting reconnections when they are unlikely to succeed.

The backoffAlgorithm library has no dependencies on libraries other than the standard C library.

See memory requirements for the latest release here.

Sending metrics to AWS IoT

When establishing a connection with AWS IoT, users can optionally report the Operating System, Hardware Platform and MQTT client version information of their device to AWS. This information can help AWS IoT provide faster issue resolution and technical support. If users want to report this information, they can send a specially formatted string (see below) in the username field of the MQTT CONNECT packet.

Format

The format of the username string with metrics is:

<Actual_Username>?SDK=<OS_Name>&Version=<OS_Version>&Platform=<Hardware_Platform>&MQTTLib=<MQTT_Library_name>@<MQTT_Library_version>

Where

  • is the actual username used for authentication, if username and password are used for authentication. When username and password based authentication is not used, this is an empty value.
  • is the Operating System the application is running on (e.g. Ubuntu)
  • is the version number of the Operating System (e.g. 20.10)
  • is the Hardware Platform the application is running on (e.g. RaspberryPi)
  • is the MQTT Client library being used (e.g. coreMQTT)
  • is the version of the MQTT Client library being used (e.g. 1.1.0)

Example

  • Actual_Username = “iotuser”, OS_Name = Ubuntu, OS_Version = 20.10, Hardware_Platform_Name = RaspberryPi, MQTT_Library_Name = coremqtt, MQTT_Library_version = 1.1.0. If username is not used, then “iotuser” can be removed.
/* Username string:
 * iotuser?SDK=Ubuntu&Version=20.10&Platform=RaspberryPi&MQTTLib=coremqtt@1.1.0
 */

#define OS_NAME                   "Ubuntu"
#define OS_VERSION                "20.10"
#define HARDWARE_PLATFORM_NAME    "RaspberryPi"
#define MQTT_LIB                  "coremqtt@1.1.0"

#define USERNAME_STRING           "iotuser?SDK=" OS_NAME "&Version=" OS_VERSION "&Platform=" HARDWARE_PLATFORM_NAME "&MQTTLib=" MQTT_LIB
#define USERNAME_STRING_LENGTH    ( ( uint16_t ) ( sizeof( USERNAME_STRING ) - 1 ) )

MQTTConnectInfo_t connectInfo;
connectInfo.pUserName = USERNAME_STRING;
connectInfo.userNameLength = USERNAME_STRING_LENGTH;
mqttStatus = MQTT_Connect( pMqttContext, &connectInfo, NULL, CONNACK_RECV_TIMEOUT_MS, pSessionPresent );

Versioning

C-SDK releases will now follow a date based versioning scheme with the format YYYYMM.NN, where:

  • Y represents the year.
  • M represents the month.
  • N represents the release order within the designated month (00 being the first release).

For example, a second release in June 2021 would be 202106.01. Although the SDK releases have moved to date-based versioning, each library within the SDK will still retain semantic versioning. In semantic versioning, the version number itself (X.Y.Z) indicates whether the release is a major, minor, or point release. You can use the semantic version of a library to assess the scope and impact of a new release on your application.

Releases and Documentation

All of the released versions of the C-SDK libraries are available as git tags. For example, the last release of the v3 SDK version is available at tag 3.1.2.

202108.00

API documentation of 202108.00 release

This release introduces the refactored AWS IoT Fleet Provisioning library and the new AWS SigV4 library.

Additionally, this release brings minor version updates in the AWS IoT Over-the-Air Update and corePKCS11 libraries.

202103.00

API documentation of 202103.00 release

This release includes a major update to the APIs of the AWS IoT Over-the-air Update library.

Additionally, AWS IoT Device Shadow library introduces a minor update by adding support for named shadow, a feature of the AWS IoT Device Shadow service that allows you to create multiple shadows for a single IoT device. AWS IoT Jobs library introduces a minor update by introducing macros for $next job ID and compile-time generation of topic strings. AWS IoT Device Defender library introduces a minor update that adds macros to API for custom metrics feature of AWS IoT Device Defender service.

corePKCS11 also introduces a patch update by removing the pkcs11configPAL_DESTROY_SUPPORTED config and mbedTLS platform abstraction layer of DestroyObject. Lastly, no code changes are introduced for backoffAlgorithm, coreHTTP, coreMQTT, and coreJSON; however, patch updates are made to improve documentation and CI.

202012.01

API documentation of 202012.01 release

This release includes AWS IoT Over-the-air Update(Release Candidate), backoffAlgorithm, and PKCS #11 libraries. Additionally, there is a major update to the coreJSON and coreHTTP APIs. All libraries continue to undergo code quality checks (e.g. MISRA-C compliance), and Coverity static analysis. In addition, all libraries except AWS IoT Over-the-air Update and backoffAlgorithm undergo validation of memory safety with the C Bounded Model Checker (CBMC) automated reasoning tool.

202011.00

API documentation of 202011.00 release

This release includes refactored HTTP client, AWS IoT Device Defender, and AWS IoT Jobs libraries. Additionally, there is a major update to the coreJSON API. All libraries continue to undergo code quality checks (e.g. MISRA-C compliance), Coverity static analysis, and validation of memory safety with the C Bounded Model Checker (CBMC) automated reasoning tool.

202009.00

API documentation of 202009.00 release

This release includes refactored MQTT, JSON Parser, and AWS IoT Device Shadow libraries for optimized memory usage and modularity. These libraries are included in the SDK via Git submoduling. These libraries have gone through code quality checks including verification that no function has a GNU Complexity score over 8, and checks against deviations from mandatory rules in the MISRA coding standard. Deviations from the MISRA C:2012 guidelines are documented under MISRA Deviations. These libraries have also undergone both static code analysis from Coverity static analysis, and validation of memory safety and data structure invariance through the CBMC automated reasoning tool.

If you are upgrading from v3.x API of the C-SDK to the 202009.00 release, please refer to Migration guide from v3.1.2 to 202009.00 and newer releases. If you are using the C-SDK v4_beta_deprecated branch, note that we will continue to maintain this branch for critical bug fixes and security patches but will not add new features to it. See the C-SDK v4_beta_deprecated branch README for additional details.

v3.1.2

Details available here.

Porting Guide for 202009.00 and newer releases

All libraries depend on the ISO C90 standard library and additionally on the stdint.h library for fixed-width integers, including uint8_t, int8_t, uint16_t, uint32_t and int32_t, and constant macros like UINT16_MAX. If your platform does not support the stdint.h library, definitions of the mentioned fixed-width integer types will be required for porting any C-SDK library to your platform.

Porting coreMQTT

Guide for porting coreMQTT library to your platform is available here.

Porting coreHTTP

Guide for porting coreHTTP library is available here.

Porting AWS IoT Device Shadow

Guide for porting AWS IoT Device Shadow library is available here.

Porting AWS IoT Device Defender

Guide for porting AWS IoT Device Defender library is available here.

Porting AWS IoT Over-the-air Update

Guide for porting OTA library to your platform is available here.

Migration guide from v3.1.2 to 202009.00 and newer releases

MQTT Migration

Migration guide for MQTT library is available here.

Shadow Migration

Migration guide for Shadow library is available here.

Jobs Migration

Migration guide for Jobs library is available here.

Branches

main branch

The main branch hosts the continuous development of the AWS IoT Embedded C SDK (C-SDK) libraries. Please be aware that the development at the tip of the main branch is continuously in progress, and may have bugs. Consider using the tagged releases of the C-SDK for production ready software.

v4_beta_deprecated branch (formerly named v4_beta)

The v4_beta_deprecated branch contains a beta version of the C-SDK libraries, which is now deprecated. This branch was earlier named as v4_beta, and was renamed to v4_beta_deprecated. The libraries in this branch will not be released. However, critical bugs will be fixed and tested. No new features will be added to this branch.

Getting Started

Cloning

This repository uses Git Submodules to bring in the C-SDK libraries (eg, MQTT ) and third-party dependencies (eg, mbedtls for POSIX platform transport layer). Note: If you download the ZIP file provided by GitHub UI, you will not get the contents of the submodules (The ZIP file is also not a valid git repository). If you download from the 202012.00 Release Page page, you will get the entire repository (including the submodules) in the ZIP file, aws-iot-device-sdk-embedded-c-202012.00.zip. To clone the latest commit to main branch using HTTPS:

git clone --recurse-submodules https://github.com/aws/aws-iot-device-sdk-embedded-C.git

Using SSH:

git clone --recurse-submodules git@github.com:aws/aws-iot-device-sdk-embedded-C.git

If you have downloaded the repo without using the --recurse-submodules argument, you need to run:

git submodule update --init --recursive

When building with CMake, submodules are also recursively cloned automatically. However, -DBUILD_CLONE_SUBMODULES=0 can be passed as a CMake flag to disable this functionality. This is useful when you'd like to build CMake while using a different commit from a submodule.

Configuring Demos

The libraries in this SDK are not dependent on any operating system. However, the demos for the libraries in this SDK are built and tested on a Linux platform. The demos build with CMake, a cross-platform build tool.

Prerequisites

  • CMake 3.2.0 or any newer version for utilizing the build system of the repository.
  • C90 compiler such as gcc
    • Due to the use of mbedtls in corePKCS11, a C99 compiler is required if building the PKCS11 demos or the CMake install target.
  • Although not a part of the ISO C90 standard, stdint.h is required for fixed-width integer types that include uint8_t, int8_t, uint16_t, uint32_t and int32_t, and constant macros like UINT16_MAX, while stdbool.h is required for boolean parameters in coreMQTT. For compilers that do not provide these header files, coreMQTT provides the files stdint.readme and stdbool.readme, which can be renamed to stdint.h and stdbool.h, respectively, to provide the required type definitions.
  • A supported operating system. The ports provided with this repo are expected to work with all recent versions of the following operating systems, although we cannot guarantee the behavior on all systems.
    • Linux system with POSIX sockets, threads, RT, and timer APIs. (We have tested on Ubuntu 18.04).

Build Dependencies

The follow table shows libraries that need to be installed in your system to run certain demos. If a dependency is not installed and cannot be built from source, demos that require that dependency will be excluded from the default all target.

DependencyVersionUsage
OpenSSL1.1.0 or laterAll TLS demos and tests with the exception of PKCS11
Mosquitto Client1.4.10 or laterAWS IoT Jobs Mosquitto demo

AWS IoT Account Setup

You need to setup an AWS account and access the AWS IoT console for running the AWS IoT Device Shadow library, AWS IoT Device Defender library, AWS IoT Jobs library, AWS IoT OTA library and coreHTTP S3 download demos. Also, the AWS account can be used for running the MQTT mutual auth demo against AWS IoT broker. Note that running the AWS IoT Device Defender, AWS IoT Jobs and AWS IoT Device Shadow library demos require the setup of a Thing resource for the device running the demo. Follow the links to:

The MQTT Mutual Authentication and AWS IoT Shadow demos include example AWS IoT policy documents to run each respective demo with AWS IoT. You may use the MQTT Mutual auth and Shadow example policies by replacing [AWS_REGION] and [AWS_ACCOUNT_ID] with the strings of your region and account identifier. While the IoT Thing name and MQTT client identifier do not need to match for the demos to run, the example policies have the Thing name and client identifier identical as per AWS IoT best practices.

It can be very helpful to also have the AWS Command Line Interface tooling installed.

Configuring mutual authentication demos of MQTT and HTTP

You can pass the following configuration settings as command line options in order to run the mutual auth demos. Make sure to run the following command in the root directory of the C-SDK:

## optionally find your-aws-iot-endpoint from the command line
aws iot describe-endpoint --endpoint-type iot:Data-ATS
cmake -S . -Bbuild
-DAWS_IOT_ENDPOINT="<your-aws-iot-endpoint>" -DCLIENT_CERT_PATH="<your-client-certificate-path>" -DCLIENT_PRIVATE_KEY_PATH="<your-client-private-key-path>" 

In order to set these configurations manually, edit demo_config.h in demos/mqtt/mqtt_demo_mutual_auth/ and demos/http/http_demo_mutual_auth/ to #define the following:

  • Set AWS_IOT_ENDPOINT to your custom endpoint. This is found on the Settings page of the AWS IoT Console and has a format of ABCDEFG1234567.iot.<aws-region>.amazonaws.com where <aws-region> can be an AWS region like us-east-2.
    • Optionally, it can also be found with the AWS CLI command aws iot describe-endpoint --endpoint-type iot:Data-ATS.
  • Set CLIENT_CERT_PATH to the path of the client certificate downloaded when setting up the device certificate in AWS IoT Account Setup.
  • Set CLIENT_PRIVATE_KEY_PATH to the path of the private key downloaded when setting up the device certificate in AWS IoT Account Setup.

It is possible to configure ROOT_CA_CERT_PATH to any PEM-encoded Root CA Certificate. However, this is optional because CMake will download and set it to AmazonRootCA1.pem when unspecified.

Configuring AWS IoT Device Defender and AWS IoT Device Shadow demos

To build the AWS IoT Device Defender and AWS IoT Device Shadow demos, you can pass the following configuration settings as command line options. Make sure to run the following command in the root directory of the C-SDK:

cmake -S . -Bbuild -DAWS_IOT_ENDPOINT="<your-aws-iot-endpoint>" -DROOT_CA_CERT_PATH="<your-path-to-amazon-root-ca>" -DCLIENT_CERT_PATH="<your-client-certificate-path>" -DCLIENT_PRIVATE_KEY_PATH="<your-client-private-key-path>" -DTHING_NAME="<your-registered-thing-name>"

An Amazon Root CA certificate can be downloaded from here.

In order to set these configurations manually, edit demo_config.h in the demo folder to #define the following:

  • Set AWS_IOT_ENDPOINT to your custom endpoint. This is found on the Settings page of the AWS IoT Console and has a format of ABCDEFG1234567.iot.us-east-2.amazonaws.com.
  • Set ROOT_CA_CERT_PATH to the path of the root CA certificate downloaded when setting up the device certificate in AWS IoT Account Setup.
  • Set CLIENT_CERT_PATH to the path of the client certificate downloaded when setting up the device certificate in AWS IoT Account Setup.
  • Set CLIENT_PRIVATE_KEY_PATH to the path of the private key downloaded when setting up the device certificate in AWS IoT Account Setup.
  • Set THING_NAME to the name of the Thing created in AWS IoT Account Setup.

Configuring the AWS IoT Fleet Provisioning demo

To build the AWS IoT Fleet Provisioning Demo, you can pass the following configuration settings as command line options. Make sure to run the following command in the root directory of the C-SDK:

cmake -S . -Bbuild -DAWS_IOT_ENDPOINT="<your-aws-iot-endpoint>" -DROOT_CA_CERT_PATH="<your-path-to-amazon-root-ca>" -DCLAIM_CERT_PATH="<your-claim-certificate-path>" -DCLAIM_PRIVATE_KEY_PATH="<your-claim-private-key-path>" -DPROVISIONING_TEMPLATE_NAME="<your-template-name>" -DDEVICE_SERIAL_NUMBER="<your-serial-number>"

An Amazon Root CA certificate can be downloaded from here.

To create a provisioning template and claim credentials, sign into your AWS account and visit here. Make sure to enable the "Use the AWS IoT registry to manage your device fleet" option. Once you have created the template and credentials, modify the claim certificate's policy to match the sample policy.

In order to set these configurations manually, edit demo_config.h in the demo folder to #define the following:

  • Set AWS_IOT_ENDPOINT to your custom endpoint. This is found on the Settings page of the AWS IoT Console and has a format of ABCDEFG1234567.iot.us-east-2.amazonaws.com.
  • Set ROOT_CA_CERT_PATH to the path of the root CA certificate downloaded when setting up the device certificate in AWS IoT Account Setup.
  • Set CLAIM_CERT_PATH to the path of the claim certificate downloaded when setting up the template and claim credentials.
  • Set CLAIM_PRIVATE_KEY_PATH to the path of the private key downloaded when setting up the template and claim credentials.
  • Set PROVISIONING_TEMPLATE_NAME to the name of the provisioning template created.
  • Set DEVICE_SERIAL_NUMBER to an arbitrary string representing a device identifier.

Configuring the S3 demos

You can pass the following configuration settings as command line options in order to run the S3 demos. Make sure to run the following command in the root directory of the C-SDK:

cmake -S . -Bbuild -DS3_PRESIGNED_GET_URL="s3-get-url" -DS3_PRESIGNED_PUT_URL="s3-put-url"

S3_PRESIGNED_PUT_URL is only needed for the S3 upload demo.

In order to set these configurations manually, edit demo_config.h in demos/http/http_demo_s3_download_multithreaded, and demos/http/http_demo_s3_upload to #define the following:

  • Set S3_PRESIGNED_GET_URL to a S3 presigned URL with GET access.
  • Set S3_PRESIGNED_PUT_URL to a S3 presigned URL with PUT access.

You can generate the presigned urls using demos/http/common/src/presigned_urls_gen.py. More info can be found here.

Configure S3 Download HTTP Demo using SigV4 Library:

Refer this demos/http/http_demo_s3_download/README.md to follow the steps needed to configure and run the S3 Download HTTP Demo using SigV4 Library that generates the authorization HTTP header needed to authenticate the HTTP requests send to S3.

Setup for AWS IoT Jobs demo

  1. The demo requires the Linux platform to contain curl and libmosquitto. On a Debian platform, these dependencies can be installed with:
    apt install curl libmosquitto-dev

If the platform does not contain the libmosquitto library, the demo will build the library from source.

libmosquitto 1.4.10 or any later version of the first major release is required to run this demo.

  1. A job that specifies the URL to download for the demo needs to be created on the AWS account for the Thing resource that will be used by the demo.
    The job can be created directly from the AWS IoT console or using the aws cli tool.

The following creates a job that specifies a Linux Kernel link for downloading.

 aws iot create-job \
        --job-id 'job_1' \
        --targets arn:aws:iot:us-west-2:<account-id>:thing/<thing-name> \
        --document '{"url":"https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.8.5.tar.xz"}'

Prerequisites for the AWS Over-The-Air Update (OTA) demos

  1. To perform a successful OTA update, you need to complete the prerequisites mentioned here.
  2. A code signing certificate is required to authenticate the update. A code signing certificate based on the SHA-256 ECDSA algorithm will work with the current demos. An example of how to generate this kind of certificate can be found here.

Scheduling an OTA Update Job

After you build and run the initial executable you will have to create another executable and schedule an OTA update job with this image.

  1. Increase the version of the application by setting macro APP_VERSION_BUILD in demos/ota/ota_demo_core_[mqtt/http]/demo_config.h to a different version than what is running.
  2. Rebuild the application using the build steps below into a different directory, say build-dir-2.
  3. Rename the demo executable to reflect the change, e.g. mv ota_demo_core_mqtt ota_demo_core_mqtt2
  4. Create an OTA job:
    1. Go to the AWS IoT Core console.
    2. Manage → Jobs → Create → Create a FreeRTOS OTA update job → Select the corresponding name for your device from the thing list.
    3. Sign a new firmware → Create a new profile → Select any SHA-ECDSA signing platform → Upload the code signing certificate(from prerequisites) and provide its path on the device.
    4. Select the image → Select the bucket you created during the prerequisite steps → Upload the binary build-dir-2/bin/ota_demo2.
    5. The path on device should be the absolute path to place the executable and the binary name: e.g. /home/ubuntu/aws-iot-device-sdk-embedded-C-staging/build-dir/bin/ota_demo_core_mqtt2.
    6. Select the IAM role created during the prerequisite steps.
    7. Create the Job.
  5. Run the initial executable again with the following command: sudo ./ota_demo_core_mqtt or sudo ./ota_demo_core_http.
  6. After the initial executable has finished running, go to the directory where the downloaded firmware image resides which is the path name used when creating an OTA job.
  7. Change the permissions of the downloaded firmware to make it executable, as it may be downloaded with read (user default) permissions only: chmod 775 ota_demo_core_mqtt2
  8. Run the downloaded firmware image with the following command: sudo ./ota_demo_core_mqtt2

Building and Running Demos

Before building the demos, ensure you have installed the prerequisite software. On Ubuntu 18.04 and 20.04, gcc, cmake, and OpenSSL can be installed with:

sudo apt install build-essential cmake libssl-dev

Build a single demo

  • Go to the root directory of the C-SDK.
  • Run cmake to generate the Makefiles: cmake -S . -Bbuild && cd build
  • Choose a demo from the list below or alternatively, run make help | grep demo:
defender_demo
http_demo_basic_tls
http_demo_mutual_auth
http_demo_plaintext
http_demo_s3_download
http_demo_s3_download_multithreaded
http_demo_s3_upload
jobs_demo_mosquitto
mqtt_demo_basic_tls
mqtt_demo_mutual_auth
mqtt_demo_plaintext
mqtt_demo_serializer
mqtt_demo_subscription_manager
ota_demo_core_http
ota_demo_core_mqtt
pkcs11_demo_management_and_rng
pkcs11_demo_mechanisms_and_digests
pkcs11_demo_objects
pkcs11_demo_sign_and_verify
shadow_demo_main
  • Replace demo_name with your desired demo then build it: make demo_name
  • Go to the build/bin directory and run any demo executables from there.

Build all configured demos

  • Go to the root directory of the C-SDK.
  • Run cmake to generate the Makefiles: cmake -S . -Bbuild && cd build
  • Run this command to build all configured demos: make
  • Go to the build/bin directory and run any demo executables from there.

Running corePKCS11 demos

The corePKCS11 demos do not require any AWS IoT resources setup, and are standalone. The demos build upon each other to introduce concepts in PKCS #11 sequentially. Below is the recommended order.

  1. pkcs11_demo_management_and_rng
  2. pkcs11_demo_mechanisms_and_digests
  3. pkcs11_demo_objects
  4. pkcs11_demo_sign_and_verify
    1. Please note that this demo requires the private and public key generated from pkcs11_demo_objects to be in the directory the demo is executed from.

Alternative option of Docker containers for running demos locally

Install Docker:

curl -fsSL https://get.docker.com -o get-docker.sh

sh get-docker.sh

Installing Mosquitto to run MQTT demos locally

The following instructions have been tested on an Ubuntu 18.04 environment with Docker and OpenSSL installed.

Download the official Docker image for Mosquitto 1.6.14. This version is deliberately chosen so that the Docker container can load certificates from the host system. Any version after 1.6.14 will drop privileges as soon as the configuration file has been read (before TLS certificates are loaded).

docker pull eclipse-mosquitto:1.6.14

If a Mosquitto broker with TLS communication needs to be run, ignore this step and proceed to the next step. A Mosquitto broker with plain text communication can be run by executing the command below.

docker run -it -p 1883:1883 --name mosquitto-plain-text eclipse-mosquitto:1.6.14

Set BROKER_ENDPOINT defined in demos/mqtt/mqtt_demo_plaintext/demo_config.h to localhost.

Ignore the remaining steps unless a Mosquitto broker with TLS communication also needs to be run.

For TLS communication with Mosquitto broker, server and CA credentials need to be created. Use OpenSSL commands to generate the credentials for the Mosquitto server.

# Generate CA key and certificate. Provide the Subject field information as appropriate for CA certificate.
openssl req -x509 -nodes -sha256 -days 365 -newkey rsa:2048 -keyout ca.key -out ca.crt
# Generate server key and certificate.# Provide the Subject field information as appropriate for Server certificate. Make sure the Common Name (CN) field is different from the root CA certificate.
openssl req -nodes -sha256 -new -keyout server.key -out server.csr # Sign with the CA cert.
openssl x509 -req -sha256 -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 365

Note: Make sure to use different Common Name (CN) detail between the CA and server certificates; otherwise, SSL handshake fails with exactly same Common Name (CN) detail in both the certificates.

port 8883

cafile /mosquitto/config/ca.crt
certfile /mosquitto/config/server.crt
keyfile /mosquitto/config/server.key

# Use this option for TLS mutual authentication (where client will provide CA signed certificate)
#require_certificate true
tls_version tlsv1.2
#use_identity_as_username true

Create a mosquitto.conf file to use port 8883 (for TLS communication) and providing path to the generated credentials.

Run the docker container from the local directory containing the generated credential and mosquitto.conf files.

docker run -it -p 8883:8883 -v $(pwd):/mosquitto/config/ --name mosquitto-basic-tls eclipse-mosquitto:1.6.14

Update demos/mqtt/mqtt_demo_basic_tls/demo_config.h to the following:
Set BROKER_ENDPOINT to localhost.
Set ROOT_CA_CERT_PATH to the absolute path of the CA certificate created in step 4. for the local Mosquitto server.

Installing httpbin to run HTTP demos locally

Run httpbin through port 80:

docker pull kennethreitz/httpbin
docker run -p 80:80 kennethreitz/httpbin

SERVER_HOST defined in demos/http/http_demo_plaintext/demo_config.h can now be set to localhost.

To run http_demo_basic_tls, download ngrok in order to create an HTTPS tunnel to the httpbin server currently hosted on port 80:

./ngrok http 80 # May have to use ./ngrok.exe depending on OS or filename of the executable

ngrok will provide an https link that can be substituted in demos/http/http_demo_basic_tls/demo_config.h and has a format of https://ABCDEFG12345.ngrok.io.

Set SERVER_HOST in demos/http/http_demo_basic_tls/demo_config.h to the https link provided by ngrok, without https:// preceding it.

You must also download the Root CA certificate provided by the ngrok https link and set ROOT_CA_CERT_PATH in demos/http/http_demo_basic_tls/demo_config.h to the file path of the downloaded certificate.

Installation

The C-SDK libraries and platform abstractions can be installed to a file system through CMake. To do so, run the following command in the root directory of the C-SDK. Note that installation is not required to run any of the demos.

cmake -S . -Bbuild -DBUILD_DEMOS=0 -DBUILD_TESTS=0
cd build
sudo make install

Note that because make install will automatically build the all target, it may be useful to disable building demos and tests with -DBUILD_DEMOS=0 -DBUILD_TESTS=0 unless they have already been configured. Super-user permissions may be needed if installing to a system include or system library path.

To install only a subset of all libraries, pass -DINSTALL_LIBS to install only the libraries you need. By default, all libraries will be installed, but you may exclude any library that you don't need from this list:

-DINSTALL_LIBS="DEFENDER;SHADOW;JOBS;OTA;OTA_HTTP;OTA_MQTT;BACKOFF_ALGORITHM;HTTP;JSON;MQTT;PKCS"

By default, the install path will be in the project directory of the SDK. You can also set -DINSTALL_TO_SYSTEM=1 to install to the system path for headers and libraries in your OS (e.g. /usr/local/include & /usr/local/lib for Linux).

Upon entering make install, the location of each library will be specified first followed by the location of all installed headers:

-- Installing: /usr/local/lib/libaws_iot_defender.so
-- Installing: /usr/local/lib/libaws_iot_shadow.so
...
-- Installing: /usr/local/include/aws/defender.h
-- Installing: /usr/local/include/aws/defender_config_defaults.h
-- Installing: /usr/local/include/aws/shadow.h
-- Installing: /usr/local/include/aws/shadow_config_defaults.h

You may also set an installation path of your choice by passing the following flags through CMake. Make sure to run the following command in the root directory of the C-SDK:

cmake -S . -Bbuild -DBUILD_DEMOS=0 -DBUILD_TESTS=0 \
-DCSDK_HEADER_INSTALL_PATH="/header/path" -DCSDK_LIB_INSTALL_PATH="/lib/path"
cd build
sudo make install

POSIX platform abstractions are used together with the C-SDK libraries in the demos. By default, these abstractions are also installed but can be excluded by passing the flag: -DINSTALL_PLATFORM_ABSTRACTIONS=0.

Lastly, a custom config path for any specific library can also be specified through the following CMake flags, allowing libraries to be compiled with a config of your choice:

-DDEFENDER_CUSTOM_CONFIG_DIR="defender-config-directory"
-DSHADOW_CUSTOM_CONFIG_DIR="shadow-config-directory"
-DJOBS_CUSTOM_CONFIG_DIR="jobs-config-directory"
-DOTA_CUSTOM_CONFIG_DIR="ota-config-directory"
-DHTTP_CUSTOM_CONFIG_DIR="http-config-directory"
-DJSON_CUSTOM_CONFIG_DIR="json-config-directory"
-DMQTT_CUSTOM_CONFIG_DIR="mqtt-config-directory"
-DPKCS_CUSTOM_CONFIG_DIR="pkcs-config-directory"

Note that the file name of the header should not be included in the directory.

Generating Documentation

Note: For pre-generated documentation, please visit Releases and Documentation section.

The Doxygen references were created using Doxygen version 1.9.2. To generate the Doxygen pages, use the provided Python script at tools/doxygen/generate_docs.py. Please ensure that each of the library submodules under libraries/standard/ and libraries/aws/ are cloned before using this script.

cd <CSDK_ROOT>
git submodule update --init --recursive --checkout
python3 tools/doxygen/generate_docs.py

The generated documentation landing page is located at docs/doxygen/output/html/index.html.


Author: aws
Source code: https://github.com/aws/aws-iot-device-sdk-embedded-C
License: MIT license

#aws 

Thierry  Perret

Thierry Perret

1659807540

Top 11 Des Erreurs D'authentification Et Comment Les Corriger

La sécurité de l'authentification est un aspect essentiel du développement d'applications Web qui est souvent négligé lors de la création d'un produit. Cependant, si vous avez l'intention de soumettre votre candidature en ligne, c'est une priorité absolue. Dans cet article, je vais vous expliquer certaines de ces erreurs et comment les corriger. Veuillez noter que ce ne sont pas les principaux problèmes de sécurité recommandés par l' OWASP ; au lieu de cela, ce sont les problèmes faciles à résoudre que je vois fréquemment.

Qu'est-ce que l'authentification ?

L'authentification est le processus de confirmation de l'identité d'un utilisateur ou d'un processus. Lorsque l'authentification est violée, les attaquants peuvent accéder aux données ou aux informations de l'utilisateur, causant des dommages à votre application. L'authentification est l'un des moyens par lesquels les attaquants peuvent accéder aux données d'un utilisateur et à votre application.

En matière d'authentification, voici les onze erreurs courantes à éviter :

  1. Affichage de messages d'erreur spécifiques
  2. Intégration des identifiants de session dans une URL
  3. Validation de formulaire incorrecte
  4. Assainissement de forme basse
  5. Stratégie de mot de passe faible
  6. Non-utilisation de l'authentification à deux facteurs (2FA)
  7. Réinitialisation incorrecte du mot de passe
  8. Déconnexion non sécurisée
  9. Attaque de force brute
  10. Utiliser des questions de sécurité faible
  11. Non-sécurisation de l'itinéraire

Affichage de messages d'erreur spécifiques

L'affichage d'un message d'erreur spécifique est dangereux car il pourrait permettre à un attaquant d'utiliser une méthode automatisée d'essais et d'erreurs pour déterminer le nom d'utilisateur ou le mot de passe d'un utilisateur.

Voici un exemple de schéma d'affichage d'un message d'erreur spécifique. 

première

Lors de l'authentification d'un formulaire sur votre application Web, vous devez veiller à ne pas afficher un seul message d'erreur lorsqu'un utilisateur saisit un détail incorrect, tel que "Votre mot de passe est incorrect". Si vous affichez un message d'erreur spécifique comme celui-ci, l'attaquant se rendra compte que l'adresse e-mail ou l'ID utilisateur est réel mais que le mot de passe est erroné. Cela permettrait à l'attaquant de suggérer un mot de passe pour cet utilisateur.

Comment réparer ce défaut

  • Ne jamais afficher un message d'erreur spécifique sur la page d'authentification. Cela permet à l'attaquant de savoir quelles informations manquent et lui permet d'utiliser une attaque par force brute pour deviner quelles informations manquent.
  • Afficher des messages d'erreur tels que "détails incorrects".

Intégration des identifiants de session dans une URL

Un ID de session est un numéro que le serveur d'un site Web attribue à un seul utilisateur pour la durée de la visite de cet utilisateur. Les chances qu'un attaquant obtienne et abusent d'un jeton de session sont augmentées s'il est placé directement dans l'URL. Bien que le risque soit moindre lors de l'utilisation de HTTPS pour se connecter au serveur Web, il existe toujours un danger. Même si les URL HTTPS sont chiffrées en transit, elles sont souvent conservées dans les journaux du serveur.

Voici un exemple de diagramme d'intégration des identifiants de session dans les URL.

2

Comment réparer ce défaut

  • Valider l'ID de session côté serveur
  • Pour créer le jeton, assurez-vous d'utiliser un générateur aléatoire suffisamment sûr.
  • Utilisez un filtre pour supprimer l'ID de session d'une URL.

Validation de formulaire incorrecte.

Des attaques par injection, des fuites de mémoire et des systèmes compromis peuvent se produire si les données fournies dans une entrée de formulaire ne sont pas correctement vérifiées ou formatées. Les utilisateurs soumettent souvent sans remplir toutes les informations nécessaires, il est donc nécessaire de valider votre formulaire pour vous assurer que toutes les informations requises ont été remplies avant de le soumettre au serveur.

Comment réparer ce défaut

  • Assurez-vous que l'e-mail a un format d'adresse e-mail.
  • Assurez-vous que l'utilisateur répond aux critères du formulaire avant de le soumettre
  • Validez le formulaire depuis le backend et le frontend à l'aide d'une bibliothèque ou d'un framework mis à jour.

Certaines des bibliothèques suggérées que je recommande pour la validation de formulaire sont :

Toutes les bibliothèques répertoriées sont bonnes pour valider votre formulaire.

Assainissement sous forme basse 

Le processus consistant à garder votre entrée de formulaire propre, filtrée et nettoyée d'un agent malveillant est connu sous le nom de nettoyage de formulaire. La désinfection de votre entrée est indispensable car elle évite les défauts d'injection. Un formulaire de saisie bien nettoyé peut empêcher les attaques suivantes :

Cross-site scripting (XSS) : il s'agit d'un type de vulnérabilité de sécurité que l'on trouve souvent dans les applications Web. Cette vulnérabilité permet aux attaquants d'insérer des scripts côté client dans les pages Web consultées par les utilisateurs. Cette attaque peut nuire à la sécurité d'un utilisateur, par exemple en le redirigeant vers un site Web malveillant, en le forçant à télécharger une application malveillante et en volant les données de l'utilisateur.

Injection SQL : les attaquants peuvent interférer avec les données envoyées à sa base de données via la saisie du formulaire. 

En nettoyant la saisie du formulaire, vous devez protéger votre code et les données de l'utilisateur de cet agent malveillant et de toutes les vulnérabilités répertoriées. Personnellement, j'utilise DOM Purify , une bibliothèque de nettoyage pour HTML et les chaînes, et elle peut filtrer tout ce qui contient du HTML sale et empêcher les attaques XSS.

Comment réparer ce défaut

  • Il est considérablement plus facile et plus sûr d'utiliser une liste d'autorisation pour des entrées bien définies telles que des nombres, des dates ou des codes postaux. À cet égard, vous pouvez indiquer explicitement quelles valeurs sont autorisées et quelles valeurs ne le sont pas.
  • Utilisez la logique de liste blanche prédéfinie dans les définitions de type de données intégrées avec la validation de formulaire HTML5.

Stratégie de mot de passe faible

Il n'est pas rare de tomber sur un site Web qui n'a pas de plan de mot de passe fort en ordre. J'ai récemment essayé une application qui nécessitait une longueur de mot de passe minimale de cinq caractères. Alors que les développeurs essaient de trouver le bon équilibre entre sécurité et convivialité, cette faille devient de plus en plus courante. Lorsque vous travaillez avec des mots de passe, assurez-vous que le mot de passe que vous suggérez à un utilisateur ou que le mot de passe créé par un utilisateur est un mélange de symboles, de chiffres et de lettres à casse mixte. Évitez les plans de mots de passe faibles.

Comment réparer ce défaut

  • Exiger qu'un utilisateur entre un minimum de 12 ou 8 caractères ou quelque chose de plus.
  • Les mots de passe incorporant des noms d'utilisateur ou des noms d'entreprise doivent être évités pour des raisons de sécurité et de convivialité.
  • Les lettres majuscules et minuscules doivent être mélangées.
  • Utilisez une bibliothèque pour calculer la force du mot de passe, soyez prudent lors de la sélection et vérifiez les dépendances et la maintenabilité minimales.
  • Lorsqu'une personne a un profil public, utilisez un nom d'affichage différent et évitez d'utiliser l'adresse e-mail de l'utilisateur comme nom d'affichage, car cela invite au spam.

Non-utilisation de l'authentification à deux facteurs

Une autre erreur courante que je vois avec les mécanismes d'authentification Web est qu'ils n'ont aucune mesure de sécurité supplémentaire. L'authentification à deux facteurs est rarement utilisée par les développeurs, en particulier pour les comptes les plus importants. L'authentification à deux facteurs permet d'ajouter une deuxième couche de protection à votre application. L'authentification à deux facteurs est essentielle pour la sécurité Web car elle élimine immédiatement les risques liés aux informations d'identification compromises. Lorsqu'un mot de passe est piraté, deviné ou même infecté par un logiciel malveillant, il ne suffit plus d'accorder l'accès à un intrus sans approbation au deuxième facteur d'authentification.

L'authentification à deux facteurs est une couche de sécurité supplémentaire ajoutée à une page d'authentification. Des exemples de cette authentification à deux facteurs sont les SMS, les e-mails et OTP.

Voici un exemple de schéma d'authentification à deux facteurs 

3

Comment mettre en œuvre l'authentification à deux facteurs

Il existe plusieurs façons d'utiliser le cryptage 2FA. Les jetons RSA, les générateurs de code comme Google Authenticator et Duo, et l'envoi de SMS de codes à usage unique sont toutes des options pour mettre en œuvre la technologie 2FA.

Réinitialisation incorrecte du mot de passe

Ce n'est pas si souvent, mais de temps en temps, je vois une application Web qui a cette capacité implémentée de manière incorrecte. Cela est souvent dû au fait que le mot de passe de l'utilisateur lui a été envoyé par e-mail ou que le jeton utilisé pour réinitialiser le mot de passe n'était pas assez fort. Le renvoi du mot de passe en clair à l'utilisateur final est un autre problème qui affecte les réinitialisations de mot de passe. C'est terrible pour diverses raisons, dont l'une est que le mot de passe a été envoyé par e-mail, ce qui est considéré comme dangereux. Cela pourrait signifier que le mot de passe a été stocké dans la base de données sans suffisamment de hachage ou dans un format pouvant être inversé, comme base64.

Le hachage  est une technique utilisée pour vérifier ou valider la qualité de divers types d'entrées. Dans les systèmes d'authentification, il est principalement utilisé pour empêcher le stockage de mots de passe en clair, et le hachage rend incroyablement difficile pour les attaquants de déchiffrer les mots de passe qui ont été stockés.

Base64 : Base64 est une méthode de conversion de données binaires en texte. La méthode est fréquemment utilisée pour envoyer des informations basées sur le contenu sur Internet.

Comment réparer ce défaut

  • Chiffrez toujours les mots de passe des utilisateurs avant de les stocker, ne les stockez pas sous leur forme brute.
  • N'envoyez des e-mails transactionnels qu'après avoir validé et vérifié les adresses e-mail en vérifiant les caractères valides et en envoyant un lien de vérification avec un jeton.

Déconnexion non sécurisée

Il s'agit d'une autre vulnérabilité qui peut causer de grands ravages à une application. Il est également essentiel de donner à vos utilisateurs un moyen sûr de se déconnecter afin que leurs sessions ne puissent pas être prises en charge. Si vous stockez l'identifiant de session côté serveur, la méthode de déconnexion doit l'invalider et effacer le cookie de session dans le navigateur. Cela empêche les attaquants de voler des cookies de session et de les utiliser ensuite pour démarrer une nouvelle session.

Comment réparer ce défaut

  • Lorsqu'un utilisateur se déconnecte, effacez le cookie de session du navigateur et invalidez l'identifiant de session s'il est stocké sur le serveur.
  • Lors de la déconnexion, les sessions utilisateur et les jetons d'authentification doivent être correctement invalidés.

Attaque de force brute

La force brute est une technique de piratage utilisée pour découvrir les informations d'identification de l'utilisateur en essayant diverses informations d'identification possibles. Dans cette attaque, les pirates essaient de deviner les mots de passe pour passer l'authentification pour un seul compte. En utilisant des scripts qui essaient de nombreux mots de passe couramment utilisés à partir d'un dictionnaire et des millions de mots de passe divulgués lors de violations de données précédentes, ces tentatives ont de meilleures chances de réussir.

Comment réparer ce défaut

  • Limitez les tentatives de connexion à une adresse ou plage IP définie en bloquant l'accès à l'URL d'authentification.
  • N'utilisez aucun terme de dictionnaires dans aucune langue. Plutôt que d'utiliser des mots, il est préférable d'utiliser des chaînes de caractères aléatoires.
  • Bloquez les adresses IP malveillantes avec CAPTCHAS.
  • Gardez une trace des tentatives de connexion infructueuses d'un utilisateur et verrouillez le compte.

Utiliser des questions de sécurité insuffisantes

Une question de sécurité ou un mot mémorable peut également aider à se prémunir contre les attaques automatisées. J'ai rencontré des questions de sécurité faibles qui ont des réponses prévisibles, permettant à un attaquant de suggérer ou de deviner des réponses et d'accéder aux données de l'utilisateur.

Voici quelques-unes des questions de sécurité les plus courantes que j'ai rencontrées :

  • Dans quelle ville êtes-vous né?
  • Quelle est votre date de naissance?
  • Quel lycée as-tu fréquenté ?
  • Quel est le nom de jeune fille de ta mère?

Évitez toutes ces questions car les pirates peuvent les deviner en raison de certaines de nos informations sur Google ou d'autres profils en ligne.

Comment réparer ce défaut

  • Recommander des questions faciles à retenir pour l'utilisateur mais difficiles à suggérer pour les attaquants
  • Stockez les réponses à l'aide d'un algorithme de hachage sécurisé tel que Bcrypt. Bcrypt est un algorithme utilisé pour hacher et vérifier les mots de passe. Cela aide à réduire le risque que des cybercriminels attaquent votre application via un mot de passe.

Non-sécurisation des itinéraires

Une autre erreur que j'ai vue commettre par les développeurs en matière d'authentification est "ne pas protéger la route". Il est essentiel de sécuriser des routes spécifiques dans votre application contre les utilisateurs non authentifiés, car cela empêchera les utilisateurs inconnus d'accéder à certaines des données privées de votre application.

Comment réparer ce défaut

  • Protégez la route à laquelle vous souhaitez que les utilisateurs non authentifiés accèdent.
  • Si un utilisateur tente d'accéder à une route spécifique, redirigez-le vers la page de connexion/inscription s'il n'est pas authentifié

Conclusion

Lors de la mise en œuvre de l'authentification sur votre site Web, vous devez faire preuve d'une extrême prudence en tant que développeur car certaines méthodes pourraient être très dommageables pour votre programme et ouvrir la porte à des attaquants pour prendre le contrôle des données des utilisateurs et de l'application. Espérons que cet article a mis en évidence ces erreurs et fourni des conseils sur la façon de les corriger.

Lien : https://blog.openreplay.com/11-authentication-mistakes-and-how-to-fix-them

#authentification

Lokesh Kumar

1603438098

Top 10 Trending Technologies Must Learn in 2021 | igmGuru

Technology has taken a place of more productiveness and give the best to the world. In the current situation, everything is done through the technical process, you don’t have to bother about doing task, everything will be done automatically.This is an article which has some important technologies which are new in the market are explained according to the career preferences. So let’s have a look into the top trending technologies followed in 2021 and its impression in the coming future in the world.

  1. Data Science
    First in the list of newest technologies is surprisingly Data Science. Data Science is the automation that helps to be reasonable for complicated data. The data is produces in a very large amount every day by several companies which comprise sales data, customer profile information, server data, business data, and financial structures. Almost all of the data which is in the form of big data is very indeterminate. The character of a data scientist is to convert the indeterminate datasets into determinate datasets. Then these structured data will examine to recognize trends and patterns. These trends and patterns are beneficial to understand the company’s business performance, customer retention, and how they can be enhanced.

  2. DevOps
    Next one is DevOps, This technology is a mixture of two different things and they are development (Dev) and operations (Ops). This process and technology provide value to their customers in a continuous manner. This technology plays an important role in different aspects and they can be- IT operations, development, security, quality, and engineering to synchronize and cooperate to develop the best and more definitive products. By embracing a culture of DevOps with creative tools and techniques, because through that company will gain the capacity to preferable comeback to consumer requirement, expand the confidence in the request they construct, and accomplish business goals faster. This makes DevOps come into the top 10 trending technologies.

  3. Machine learning
    Next one is Machine learning which is constantly established in all the categories of companies or industries, generating a high command for skilled professionals. The machine learning retailing business is looking forward to enlarging to $8.81 billion by 2022. Machine learning practices is basically use for data mining, data analytics, and pattern recognition. In today’s scenario, Machine learning has its own reputed place in the industry. This makes machine learning come into the top 10 trending technologies. Get the best machine learning course and make yourself future-ready.

To want to know more click on Top 10 Trending Technologies in 2021

You may also read more blogs mentioned below

How to Become a Salesforce Developer

Python VS R Programming

The Scope of Hadoop and Big Data in 2021

#top trending technologies #top 10 trending technologies #top 10 trending technologies in 2021 #top trending technologies in 2021 #top 5 trending technologies in 2021 #top 5 trending technologies

Top 5 Mobile App Development Companies in New York

New York is the best potential business hub for the technology and IT industry. Thousands of companies are established in New York for the mobile app development or technology industry. So, here quite a confusion is that how to choose the right company for your business amongst all the companies. No need to worry about it, We have found the most reliable and trustworthy mobile app development companies that are the top-tiers in New York. Before we share the companies list you need to know the benefits of mobile app development for your business.

Key Benefits of Mobile App Development:

· Improves Efficiency

· Offers High Scalability

· Secures Your App Data

· Integrates With Existing Software

· Easy to Maintain

· Improves Customer Relationship

· Facilitates New Client Data Retrieval

· Provides Real-time Project Access

Are you looking for top mobile app development companies in New York that help to create a custom mobile app as per your business requirements? Please go through these Top 5 mobile app development companies that provide exceptional development and design services for your business.

Top Mobile App Development Companies in New York:

1. AppCluesInfotech

AppClues Infotech is one of the leading mobile app development company based in New York that builds high-quality mobile apps. Being a versatile mobile app development company, they provide services on various platforms like Android, iOS, Cross-platform, Windows, etc. They are aware of the latest technologies and features of industry. They utilize them to create a user-engaging mobile app. They have the best team of designers and developers who are delivered a mobile app with high-quality and performance.

Founded In: 2014

Employees: 50 to 200 Members

Location: USA

Website: https://www.appcluesinfotech.com/

2. Data EximIT

Data EximIT is one of the leading mobile app development company in New York that provides top-notch and elegant mobile app development services with the latest market trends and functionalities at a competitive price. They have highly experienced mobile app designers and developers team who have the best strength of developing all types of a mobile app. They deliver a feature-rich mobile app for their clients that give the best business ROI.

Founded In: 2004

Employees: 50 to 150 Members

Location: USA & India

Website: https://www.dataeximit.com/

3. WebClues Infotech

WebClues Infotech is the most reliable & superior company that builds custom mobile apps to do things differently. They are the best mobile app development company in New York, USA and as well as globally with high proficiency. They have a highly experienced app developers team that has the best strength of work on multiple platforms like android, Cross-platform, and iOS.

They have successfully delivered 950+ mobile app projects effectively and on-time. Build your Robust, Secure, Scalable & High-performance mobile app with WebClues Infotech with creative & dynamic designs at an affordable price.

Founded In: 2014

Employees: 50 to 250 Members

Location: USA, INDIA, UAE, UK & CANADA

Website: https://www.webcluesinfotech.com/

4. AppClues Studio

AppClues Studio is a leading mobile app development company in New York, USA. The company is versatile in developing custom mobile app development solutions to its customers across the globe. With an experience of 8+ years in mobile app development, Utility is hyper-focused on Return on Investment (ROI) and building good relationships with partner companies. The company is worked with a start-up to large enterprises.

Founded In: 2014

Employees: 50 to 150 Members

Location: USA & UK

Website: https://appcluesstudio.com/

5. WebClues Global

WebClues Global is a prominent mobile application development company in New York, USA. They are one of the top-tier mobile app developers who deliver high-end Android mobile app solutions to their clients. The company operated with 100+ qualified developers who working in different domains to give the best solution for their development. WebClues Global offers various services including web and mobile design & development, E-Commerce Development, Ui/Ux Development.

Founded In: 2014

Employees: 50 to 150 Members

Location: USA, INDIA, UAE, UK & CANADA

Website: https://www.webcluesglobal.com/

#top 5 mobile app development companies in new york #top 5 mobile app development companies in usa #top mobile app development companies in new york #top mobile app development companies in usa #top 5 mobile app development companies

Maptable: Converts any Dataset to An interactive Set Of Components

MapTable

MapTable's primary function is to convert any dataset to a customizable set of components of Map, Filters and Table:

  • Map - A fully customizable (zoom & pan) choropleth or heat map rendered using SVG. The map can be exported to a stand alone SVG for external consumption. The map can include markers based on lat/lon with tooltips. Markers and Map are dynamically update based on filters.
  • Table - A tabular representation of your dataset which can be sorted by header rows. Primary sort is the first click and secondary sort is the second click when shift is held down. This also dynamically responds to filters.
  • Filters - A programmatically generated list of drop downs and input fields to drill down into your dataset

This library was originally conceived to render the home page and next generation of IXP directory for Packet Clearing House (PCH).

You can also browse other code samples and examples

Dependencies

* Only used if you need a map

Install

Here is minimum amount of HTML to render a MapTable with Map, Filter and Table.

<div id='vizContainer'></div>

<script src="d3.min.js"></script> <!-- You can import it from cdnjs.com or bower-->
<script src="topojson.min.js"></script> <!-- You can remove this line if you're not using the map --> <!-- You can import it from cdnjs.com or bower -->
<script src="maptable.min.js"></script> <!-- You can import it from cdnjs.com or bower -->
<script>
  var viz = d3.maptable('#vizContainer')
              .csv('dataset.csv')
              .map({ path: 'world-110m.json' }) // You can remove this line if you want to disable the map
              .filters() // You can remove this line if you want to disable filters
              .table() // You can remove this line if you want to disable the table
              .render(); // This is important to render the visualization
</script>

MapTable is available on cdnjs.com. Remember though, cool kids concatenate their scripts to minimize http requests.

If you want to style the MapTable elements with some existing styles, you can prepend the above HTML with:

<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap.min.css">
<link rel="stylesheet" href="../maptable.css">

Declaring MapTable elements

To create a visualization (Map or/and Table or/and Filters) of your dataset, you need to provide first the container of your visualization

<div id='vizContainer'></div>

The default order of the 3 components is Map, Filters and Table. If you want to place the components in a different order, you can put them on the main container:

<div id='vizContainer'>
  <div id='mt-map'></div>
  <div id='mt-filters' class='panel panel-default'></div>
  <div id='mt-table'></div>
</div>

You instantiate the MapTable library into the viz variable based on the #vizContainer ID you declared in the DOM:

<script>
  var viz = d3.maptable('#vizContainer'); // #vizContainer is the css selector that will contain your visualization
</script>

The MapTable viz declaration in the above example is a chain of functions. The possible functions that you can use are:

  • viz.json(jsonPath[, preFilter]) with jsonPath as string and preFilter as function that filters the dataset upfront.
  • viz.csv(csvPath[, preFilter]) with csvPath as string and preFilter.
  • viz.tsv(tsvPath[, preFilter]) with tsvPath as string and preFilter.
  • viz.columns(columnDetails) with columnDetails as a JS dictionary. You can add/remove it of you want to customize your columns or create virtual columns based on the data.
  • viz.map(mapOptions) with mapOptions as a JS dictionary. You can add/remove it of you want a map on your visualization.
  • viz.filters(filtersOptions) with filtersOptions as a JS dictionary. You can add/remove it of you want filters on your visualization.
  • viz.table(tableOptions) with tableOptions as a JS dictionary. You can add/remove it of you want a table on your visualization.
  • viz.render([onComplete]) that closes the chain and renders the visualization. Don't forget this! It can take an optional callback function onComplete, that's executed when MapTable finishes rendering its components. For example if you have function alertTest(){ alert('test!'); } you would call it with viz.render(alertTest).

Example with preFilter

var viz = d3.maptable('#vizContainer')
        .json('dir_data.json', (d) => parseInt(d.traffic) > 0)
        .map({ path: 'countries.json' })
        .render();

Import datasets

Datasets can be defined by using one of the these three sources:

# viz.json(url)

Import JSON file at the specified url with the mime type "application/json".

# viz.csv(url)

Import CSV file at the specified url with the mime type "text/csv".

# viz.tsv(url)

Import TSV file at the specified url with the mime type "text/tab-separated-values".

Map datasets

To plot lands and countries on the map, we're using TopoJSON library. The map can be generated through this tool: topojson-map-generator.

Dataset requirements

In order to plot your dataset on a map, there are minimum set of columns needed.

If you're planning to add markers on your map, you would need to provide latitude, longitude of your markers. You can also edit these keys name using the map options longitudeKey, latitudeKey.

[
    {"longitude": "13.23000", "latitude": "-8.85000"},
    {"longitude": "168.32000", "latitude": "-17.75000"},
]

If you're planing to add country related information, you should provide consistent country information on your dataset from the TopJSON file. You should provide at least one of these types on your mapOptions:

  • countryIdentifierKey: (string, default: 'country_code') Column name of country identifier (from the dataset). It goes as pair with the option countryIdentifierType.
  • countryIdentifierType: (string, default: 'iso_a2') Country identifier type that we're using to attach data to countries on the map. The available types are:
    • iso_a2 (default): ISO_3166-1_alpha-2 country code format
    • iso_a3: ISO_3166-1_alpha-3 country code format
    • name: Country name that came from the GeoJSON map file.
    • continent: Continent name that came from the GeoJSON map file.

For example for this dataset:

[
  {"country_code": "MAR", "Country Name": "Morocco", "bar": "foo"},
  {"country_code": "FRA", "Country Name": "France", "bar": "foo"},
]

You would use these options:

{
  countryIdentifierKey: 'country_code',
  countryIdentifierType: 'iso_a3'
}

or

{
  countryIdentifierKey: 'Country Name',
  countryIdentifierType: 'name'
}

Columns details

By default, MapTable imports all the columns and detects their format automatically. As well, you can customize behaviors of specific columns and create virtual columns.

# viz.columns(columnDetails) with columnDetails as a JS dictionary. You can add/remove it of you want to customize your columns or create virtual columns based on the data.

columnsDetails format

  • <PUT_YOUR_COLUMN_KEY>: (Object) Provide the columns key here to apply the options below to it. If this key is not defined in yoru dataset, then it will be dynamically added as virtual column:
    • nowrap: (bool, default: false) When present, it specifies that the content inside a that column should not wrap.
    • title: (string, default: columnKey) What we show as column name in filters and table.
    • filterMethod: (string, default: 'field') Column format type, used for filtering. Available options:
      • field: filter by keyword
      • dropdown: exact match using a dropdown
      • compare: filter using comparison (≥, ≤, between ....)
    • virtual: (function(d), default: null) To create a new column that doesn't exists in the dataset, and we'd like to show it on the table or filters. You can also use it if you want to transform an existing column.
    • cellContent: (function(d), default: null) Function that transforms an existing content using other rows. (for example to change the color depending on the data).
    • dataParse: (function(d), default: null) Function that return the formatted data used to sort and compare cells.
    • filterInputType: (string, default: 'text') HTML input type that we're using for the filters for that specific column (e.g. date, number, tel ...)

Example (adding nowrap and type to the region column key):

.columns({
  region: {
    nowrap: true,
    filterMethod: 'dropdown'
  }
})

Naming conventions

For the below examples, we define viz as the variable that loads MapTable.

Functions that have d as parameter, means that d is a JS dictionary that contains data for one row.

Functions that have groupedData as parameter, means that groupedData is a JS dictionary { key: 'groupedByKey', values: [ {d}, ... ] } that contains the key that have been used to group the data, and the matching values related to that grouping.

Map

#viz.map(mapOptions) with mapOptions as a JS dictionary. You can add/remove it of you want a map on your visualization.

Options

path: (string, required) URL of the TOPOJSON map, you can get them from Mike Bostock's repo: world atlas and us atlas. Or use this tool to generate these files as we did on the examples.

onComplete: (function, default: null) Callback function when the map first loaded.

onRender: (function, default: null) Callback function when the map finished rendering.

width: (integer, default:'window.innerWidth') Map Width.

height: (integer, default:'window.innerHeight') Map Height.

saveState: (bool, default: true) Save zoom state into the URL

zoom: (bool, default: true) Enable zoom on the map (when scrolling up/down on the map).

filterCountries: (function(country)) Filter countries follow a specific condition. Example:

```js
  filterCountries: (country) => country.id !== 'AQ', // to remove Antarctica from the map
  ```

title: (object, default: see below) Add a title within the map.

  • title.bgColor: (string, default: '#000000') Title font size.
  • title.fontSize: (integer, default: 12) Title font size.
  • title.fontFamily: (string, default: 'Helevetica, Arial, Sans-Serif') Title font family.
  • title.content: (function(countShown, countTotal, filtersDescription) Function to define how the title is rendered
  • title.source: (function())_ Function to define how the HTML in the title. Example:
title: {
  bgColor: "#F5F5F5",
  fontSize: "11",
  content: function(countShown, countTotal, filtersDescription) {
    if (countShown === 0 || countTotal === 0) out = "No data shown";
    else if (countShown < countTotal) out = 'Showing <tspan font-weight="bold">' + countShown + '</tspan> from <tspan font-weight="bold">' + countTotal + "</tspan>";
    else out = '<tspan font-weight="bold">' + countTotal + "</tspan> shown";

    if (filtersDescription !== '') out += " — " + filtersDescription;
    return out;
  },
  source: function() {
    return 'Source: <a xlink:href="http://www.example.com" target="_blank"><tspan font-weight="bold">example.com</tspan></a>';
  }
},

scaleZoom: ([integer, integer], default: [1, 10]) The map zoom scale.

scaleHeight: (float, default: 1.0) Ratio to scale the map height.

autoFitContent: (bool, default: true) Enable auto zoom to focus on the active markers.

fitContentMargin: (integer, default: 10) Padding in pixels to leave when we filter on a specific area.

ratioFromWidth: (float, default: 0.5) Ratio between the height and the width: height/width, used to deduce the height from the the width.

countryIdentifierKey: (string, default: 'country_code') Column name of country identifier (from the dataset). It goes as pair with the option countryIdentifierType.

countryIdentifierType: (string, default: 'iso_a2') Country identifier type that we're using to attach data to countries on the map. The available types are:

  • iso_a2 (default): ISO_3166-1_alpha-2 country code format
  • iso_a3: ISO_3166-1_alpha-3 country code format
  • name: Country name that came from the GeoJSON map file.
  • continent: Continent name that came from the GeoJSON map file.

longitudeKey: (string, default: 'longitude') Column name of the longitude (from the dataset).

latitudeKey: (string, default: 'latitude') Column name of the latitude (from the dataset).

exportSvg: (string, default: null) URL endpoint to download the current visualization as SVG. Read more on the section export SVG. (more details on a the section "Export as SVG")

exportSvgClient: (bool, default: false) Show button to download the current visualization as SVG using only the client browser instead of querying the backend (in the opposite of exportSvg). You'll need to download FileSaver.js and add a <script src="filesaver.min.js"> to make it work. You may also use the CDN version in your <script> source.

watermark: (object, default: null) Add a watermark within the map.

watermark.src: (string) URL of the image (svg, png, jpg).

watermark.width: (integer) Image width.

watermark.height: (integer) Image height.

watermark.position: (string) Watermark position (top|middle|bottom) (left|middle|right). e.g. bottom left.

watermark.style: (string) Additional css style for the watermark.

Example:

watermark: {
  src: 'https://example.com/image.svg',
  width: 130,
  height: 60,
  position: "bottom left",
  style: "opacity:0.1"
},

markers: (object, enabled by default) Add markers on the map. Set it to false to disable it.

markers.customTag: (function(markerObject)), default: null) This is more advanced feature. If you'd like to override the default market tag (svg:circle) to something different (like an image), you can use this callback function to append to the markerObject your custom implementation (see below example). x and y are coordinates in pixels of the marker.

markers.attrX: (string, default: 'cx') Attribute to position the marker on the X-Axis

markers.attrY: (string, default: 'cy') Attribute to position the marker on the Y-Axis

markers.attrXDelta: (integer, default: 0) Left relative margin of the marker

markers.attrYDelta: (integer, default: 0) Top relative margin of the marker

markers.groupBy: (function(groupedData)) Given groupedData (the current row), function that returns a value that we group markers by. See this example for an implementation example.

markers.tooltipClassName: (string, default: 'mt-map-tooltip popover bottom') Class name of the tooltip used for markers (we're using bootstrap).

markers.tooltip: (function(groupedData)) Function that returns html that we would use as content for the tooltip. We recommend you to use the bootstrap popover..

markers.attr: (object) The markers are by default SVG circle, you can custumize the radius, color or stoke of these markers here. You can use the attribute r to set the radius or fill for the color. More details on possible attributes here. We'll use r as example in the following documentation.

  • markers.attr.r: _(string or integer)_To set a static value
  • markers.attr.r: (function) To represent the radius value based on the dataset, see this example on how we set the marker color fill based on the dataset.
  • markers.attr.r: (object) Use an object with the following keys to correlate the value of the radius with the dataset
    • markers.attr.r.aggregate: (object) Information on how we aggregate data. See this example to understand how we adjusted the radius of the markers based on the dataset.
    • markers.attr.r.aggregate.key: (string) Which column we'll use to aggregate the value (it need to be a number)
    • markers.attr.r.aggregate.mode: (enum('sum', 'count', 'avg', 'min', 'max', '50percentile', '95percentile'), default to 'count') what aggreation function we'll use.
    • markers.attr.r.aggregate.scale: (enum('linear', 'rank', 'sqrt', 'pow2', 'pow3', 'log'), default: 'linear') what scale we'll aggregate the data.
    • markers.attr.r.min: (string or integer) Attribute value for the minimum value on the scale
    • markers.attr.r.max: (string or integer) Attribute value for the maximum value on the scale
    • markers.attr.r.empty (string or integer) Attribute value if no data is linked to that country
    • markers.attr.r.rollup: DEPRECATED (use aggregate instead) (function(groupedData), default: groupedData => groupedData.length) Function for the values we're attaching to the country and attribute. return value needs to be an array that contains rows that match that country or marker. Defaults to values.length, the count of matching markers
    • markers.attr.r.transform: (function(value, allRows), default: value) Function for changing the value for the current country. Can only accept value transform(value) to do a simple Math.log(value) call or be defined to use more advanced logic with transform(value, allRows) and then iterate over allRows (all rows from your csv/tsv/json) to calculate relative values like percentile. (It's recommended to use aggreggate if you want to have a different scale).

countries: (object, enabled by default) Add countries on the map. You can not use this with map.heatmap. Set it to false to disable it.

countries.tooltip: (function(groupedData)) Function that returns html that we would use as content for the tooltip. We recommend you to use the bootstrap popover. The parameter is groupedData (check above on the naming conventions for more details).

countries.attr: (object) The countries are by default SVG path, you can custumize the color or stoke here. You can use the attribute fill to set the color. More details on possible attributes here. We'll use fill as example in the following documentation.

  • countries.attr.fill: (string or integer) To set a static value
  • countries.attr.fill: (function) To represent the color value based on the dataset.
  • countries.attr.fill: (object) Use an object with the following keys to correlate the value of the radius with the dataset
    • countries.attr.fill.aggregate: (object) Information on how we aggregate data. See this example to understand how the countries colors change based on the number of markers per country (choropleth).
    • countries.attr.fill.aggregate.key: (string) Which column we'll use to aggregate the value (it need to be a number)
    • countries.attr.fill.aggregate.mode: (enum('sum', 'count', 'avg', 'min', 'max', '50percentile', '95percentile'), default to 'count') what aggreation function we'll use.
    • countries.attr.fill.aggregate.scale: (enum('linear', 'rank', 'sqrt', 'pow2', 'pow3', 'log10'), default: 'linear') what scale we'll aggregate the data.
    • countries.attr.fill.min: (string or integer) Attribute value for the minimum value on the scale
    • countries.attr.fill.max: (string or integer) Attribute value for the maximum value on the scale
    • countries.attr.fill.minNegative: (string or integer, optional) Attribute value for the minimum (closest to 0) negative value. Use this and maxNegative if you want to show different colors on the map for negative values. It is optional. see this example for an implementation example.
    • countries.attr.fill.maxNegative: (string or integer, optional) Attribute value for the maximum (farthest from 0) negative.
    • countries.attr.fill.empty (string or integer) Attribute value if no data is linked to that country
    • countries.attr.fill.legend: (bool, default: false) show or hide the legend
    • countries.attr.fill.rollup: (function(groupedData), default: groupedData => groupedData.length) DEPRECATED (use aggregate instead) Function for the values we're attaching to the country and attribute. return value needs to be an array that contains rows that match that country or marker. Defaults to values.length, the count of matching countries
    • countries.attr.fill.transform: (function(value, allRows), default: value) Function for changing the value for the current country. Can only accept value transform(value) to do a simple Math.log(value) call or be defined to use more advanced logic with transform(value, allRows) and then iterate over allRows (all rows from your csv/tsv/json) to calculate relative values like percentile. (It's recommended to use aggreggate if you want to have a different scale).

heatmap: (object, default: null) Add a heatmap on the map - we use concentrated circles on every location in the dataset. You can not use this with map.countries.. See this example for an implementation example.

heatmap.weightByAttribute: (function(d), default: null) Which attribute we would weight the gradient. it takes a anonymous function that exposes d as one row, and expect a float as returned value.

heatmap.colorStrength: (float, default: 1) Adjusts heatmap color strength, (0 make things transparent, 1 normal behavior, > 1 to make the color darker)

heatmap.weightByAttributeScale: ('log' or 'linear', default: 'linear') Which scale we would use for the weight (only if weightByAttribute is set).

heatmap.mask: (bool, default: true) Mask the heatmap with countries so heatmap doesn't go over oceans

heatmap.circles: (object) Properties of the circles that makes the heatmap gradient

heatmap.circles.color: (string, default: "#FF0000") The color in HEX of the heatmap circles.

heatmap.circles.blur: (float, default: 4.0) Blur radius that we apply on the heatmap.

heatmap.borders: (object) Enable country borders. Set to false to disable it.

heatmap.borders.stroke: (integer, default: 1) Country border stroke width.

heatmap.borders.opacity: (integer, default: 0.1) Country border stroke opacity.

heatmap.borders.color: (string, default: "#000") Country border stroke color.

Example

heatmap: {
  weightByAttribute: function(d) {
    return parseInt(d.traf, 10);
  },
  weightByAttributeScale: 'log',
  circles: {
    color: '#0000FF',
    blur: 6.0,
  },
  borders: {
    opacity: 0.2,
  },
},

Filters

# viz.filters(options) with filtersOptions as a JS dictionary. You can add/remove it of you want filters on your visualization.

Options

  • show: ([string, ...], default: null) Set the order and the columns that we want to see in the filters.
  • saveState: (bool, default: true) Save filters state into the URL

Table

If you want to add a table on your visualization:

# viz.table(tableOptions) with tableOptions as a JS dictionary. You can add/remove it of you want a table on your visualization.

Options

  • show: ([string, ...], default: null) Set the order and the columns that we want to see in the table.
  • onComplete: (function, default: null) Callback function when the table first loaded.
  • onRender: (function, default: null) Callback function when the table finished rendering.
  • className: (string, default: 'table table-striped table-bordered') Table class name
  • rowClassName: (function(d), default: null) Function that returns the row class name depending on its content. Useful to highlight rows.
  • defaultSorting: (object or table or object, default: see below) How we sort things on the table. You can specify a an array of two objects for secondary sorting.
    • defaultSorting.key: (string, default: ) default sorting on which column.
    • defaultSorting.mode: (string, default: 'asc') sorting mode: asc for ascending, desc for descending.
  • collapseRowsBy: ([string, ...], default: null) Array of columns that we want to be collapsed.

Export as SVG

You can enable this feature via exportSvg and set it to a URL. This will allow users download the map on their computer as an SVG. However, you would need to set up a server endpoint that is going to allow users download the SVG file.

The sample code for a PHP server is located in /server/exportSvg.php. Contributions are welcomed for implementations of in other languages.

In the version 1.4.0 exportSvgClient was added to use only the browser to export the SVG.

Credits

  • Mohammed Elalj @melalj - Original Author & Lead Architect
  • Ashley Jones @Ths2-9Y-LqJt6 - Feature Requester & Deliverer, QA, Love, Release Engineer

Contribute

You are welcomed to fork the project and make pull requests.

Set up your development environment

Requirements

Install any items with "sudo":

  • NodeJs, type npm -v on your terminal to check if you have it. node.js 4 and npm 2 versions or higher required.
  • Gulp sudo npm install -g gulp
  • Bower sudo npm install -g bower

Getting Started

Run these commands as your unprivileged user you're doing your development as:

  1. Run npm install to install dependencies
  2. Run bower install to download Browser Javascript libraries
  3. Run gulp to start the local dev environment on http://localhost:5000
  4. Edit files in ./dev and they will be automatically compiled to ./src
  5. To have production ready files, run: gulp dist. All built files are located in the folder ./dist
  6. Enjoy 🍻

Todo

  •  Publish v1
  •  Write unit tests 🙏
  •  Improve documentation (spell, formulation, emoji...)
  •  Secondary sorting
  •  Append SVG filters to the map and use them as styling
  •  Legend gradient transformation (if we used the log scale)
  •  Have multiple legends depending on the attribute
  •  Legend marker radius

Release History

  • Version 1.7.3 November 26 2018
    • Changed the rank worked so that value of 0 is included in ranks.
  • Version 1.7.2 November 15 2018
    • Change first click on column head to be Descending instead of Ascending - Issue #95
    • Fix some corner cases this.legendCountry[attrKey] is not defined in GeoMap.js - Issue #96
  • Version 1.7.1 November 14 2018
    • Fix Excessive updates to window history - Issue #93
  • Version 1.7.0 November 14 2018 (Also includes items in unreleased 1.6.1)
    • Allow map to be re-rendered with a column sort - Issue #88
    • Fix cellContent: function(d) is called twice for every cell - Issue #87
    • Fix Examples JS errors, padding - Issue #86
    • Support secondary sorting in defaultSorting - Issue #78
    • Provide dataset to map.title.content function to have better customizations - Issue #77
    • Be able to set a property (like attr.fill) of an attribute based on the data - Issue #76
  • Version 1.6.0 July 16 2018
    • Add ability to support secondary sorting in defaultSorting - Issue #78
    • Add ability to provide dataset to map.title.content function to have better customizations - Issue #77
    • Add ability to set a property (like attr.fill) of an attribute (eg marker) based on the data - Issue #76
    • Fix first column as defaultSorting - Issue #71
    • Fix sorting, virtual columns demo - Issue #70
  • Version 1.5.3 June 19 2018
  • Version 1.5.2 June 18 2018
  • Version 1.5.1 May 22 2017
  • Version 1.5.0 May 22 2017
  • Version 1.4.0 December 20 2016
  • Version 1.3 September 26 2016
    • Allow fancier math on country values in map.countries.attr.fill.transform() in GeoMap.js - Issue #32
  • Version 1.2.1 September 21 2016
    • Fix bad use of attrValue in GeoMap.js - Issue #30
  • Version 1.2 September 20 2016
    • Allow custom colors for negative values - PR #29
    • Correctly render legend markers - Issue #27
    • Fix countries.attr documentation add add new minNegative and maxNegative docs.
  • Version 1.1.1 July 14 2016
    • Tweak sorting when clicking column headers - PR #23
    • Scrolling up when we click on New filter - Issue #20
    • Fix poor render on first load - PR #22
  • Version 1.1 June 22 2016
  • Version 1.0.2 May 16 2016
    • Fix dev environment for Ubuntu - Issue #11
    • Restore example directory for use with development - Issue #11
    • Fix some npm packaging breakage - Issue #11
  • Version 1.0.1 March 25 2016
    • First Full featured release
  • Version 1.0.0 December 9 2014
    • Initial commit

Author: Packet-Clearing-House
Source Code: https://github.com/Packet-Clearing-House/maptable 
License: MIT license

#javascript #3d #map #table