11 основных ошибок аутентификации и способы их исправления

Безопасность аутентификации — важный аспект разработки веб-приложений, который часто упускается из виду при создании продукта. Однако, если вы собираетесь подать заявку онлайн, это является главным приоритетом. В этой статье я объясню некоторые из этих ошибок и как их исправить. Обратите внимание, что это не основные проблемы безопасности, которые рекомендует OWASP ; вместо этого это легко устраняемые проблемы, которые я часто вижу.

Что такое аутентификация?

Аутентификация — это процесс подтверждения личности пользователя или процесса. При нарушении аутентификации злоумышленники могут получить доступ к данным или информации пользователя, нанеся ущерб вашему приложению. Аутентификация — это один из способов, которым злоумышленники могут получить доступ к данным пользователя и вашему приложению.

Когда дело доходит до аутентификации, вот одиннадцать распространенных ошибок, которых следует избегать:

  1. Отображение конкретных сообщений об ошибках
  2. Интеграция идентификаторов сеанса в URL-адрес
  3. Неправильная проверка формы
  4. Санитарная обработка низкой формы
  5. Стратегия слабого пароля
  6. Неиспользование двухфакторной аутентификации (2FA)
  7. Неверный сброс пароля
  8. Небезопасный выход
  9. Атака грубой силы
  10. Использование слабых контрольных вопросов
  11. Неспособность защитить маршрут

Отображение определенных сообщений об ошибках

Отображение определенного сообщения об ошибке опасно, потому что это может позволить злоумышленнику использовать автоматизированный метод проб и ошибок для определения имени пользователя или пароля пользователя.

Вот пример схемы отображения определенного сообщения об ошибке. 

первый

При аутентификации формы в вашем веб-приложении вы должны быть осторожны, чтобы не отображать только одно сообщение об ошибке, когда пользователь вводит неверные данные, например «Ваш пароль неверен». Если вы покажете такое конкретное сообщение об ошибке, злоумышленник поймет, что адрес электронной почты или идентификатор пользователя реальны, но пароль неверный. Это позволит злоумышленнику предложить пароль для этого пользователя.

Как исправить этот недостаток

  • Никогда не показывать конкретное сообщение об ошибке на странице аутентификации. Это позволяет злоумышленнику узнать, какая информация отсутствует, и позволяет ему использовать атаку грубой силы, чтобы угадать, какая информация отсутствует.
  • Отображение сообщений об ошибках, таких как «неправильные данные».

Интеграция идентификаторов сеанса в URL-адрес

Идентификатор сеанса — это число, которое сервер веб-сайта присваивает одному пользователю на время посещения этого пользователя. Вероятность того, что злоумышленник получит токен сеанса и злоупотребит им, увеличивается, если он размещен непосредственно в URL-адресе. Хотя риск при использовании HTTPS для подключения к веб-серверу ниже, опасность все же существует. Несмотря на то, что URL-адреса HTTPS шифруются при передаче, они часто сохраняются в журналах сервера.

Вот пример схемы интеграции идентификаторов сеансов в URL-адреса.

2

Как исправить этот недостаток

  • Проверка идентификатора сеанса на стороне сервера
  • Чтобы создать токен, убедитесь, что вы используете достаточно безопасный генератор случайных чисел.
  • Используйте фильтр, чтобы удалить идентификатор сеанса из URL-адреса.

Неверная проверка формы.

Атаки с внедрением, утечки памяти и скомпрометированные системы могут произойти, если данные, предоставленные во входных данных формы, не проверены или не отформатированы должным образом. Пользователи часто отправляют, не заполнив всю необходимую информацию, поэтому необходимо проверить вашу форму, чтобы убедиться, что вся необходимая информация была соблюдена, прежде чем отправлять ее на сервер.

Как исправить этот недостаток

  • Убедитесь, что письмо имеет форматирование адреса электронной почты.
  • Перед отправкой убедитесь, что пользователь соответствует критериям формы.
  • Проверяйте форму из бэкэнда и внешнего интерфейса, используя обновленную библиотеку или фреймворк.

Некоторые из предлагаемых библиотек, которые я рекомендую для проверки формы:

Все перечисленные библиотеки хороши для проверки вашей формы.

Санитарная обработка низкой формы 

Процесс поддержания чистоты, фильтрации и очистки ввода формы от вредоносного агента называется очисткой формы. Дезинфекция вашего ввода является обязательной, потому что она предотвращает ошибки инъекций. Хорошо продезинфицированная форма ввода может предотвратить следующие атаки:

Межсайтовый скриптинг (XSS): это тип уязвимости системы безопасности, который часто встречается в веб-приложениях. Эта уязвимость позволяет злоумышленникам вставлять клиентские скрипты в просматриваемые пользователями веб-страницы. Эта атака может нанести значительный ущерб безопасности пользователя, например перенаправить его на вредоносный веб-сайт, заставить его загрузить вредоносное приложение и украсть данные пользователя.

Внедрение SQL: Злоумышленники могут вмешиваться в данные, отправленные в его базу данных через ввод формы. 

Дезинфицируя ввод формы, вы должны защитить свой код и данные пользователя от этого вредоносного агента и всех перечисленных уязвимостей. Я лично использую DOM Purify , библиотеку очистки для HTML и строк, и она может фильтровать все, что содержит грязный HTML, и предотвращать атаки XSS.

Как исправить этот недостаток

  • Значительно проще и безопаснее использовать белый список для четко определенных входных данных, таких как числа, даты или почтовые индексы. В связи с этим вы можете явно указать, какие значения разрешены, а какие нет.
  • Используйте предопределенную логику списка разрешенных во встроенных определениях типов данных с проверкой формы HTML5.

Стратегия слабого пароля

Нередко можно встретить веб-сайт, на котором нет надежного плана паролей. Недавно я попробовал приложение, которое требовало минимальной длины пароля из пяти символов. Поскольку разработчики пытаются найти правильный баланс между безопасностью и удобством использования, этот недостаток становится все более распространенным. При работе с паролями убедитесь, что пароль, который вы предлагаете пользователю, или пароль, который создает пользователь, представляет собой смесь символов, цифр и букв смешанного регистра. Избегайте слабых планов паролей.

Как исправить этот недостаток

  • Требовать от пользователя ввести минимум 12 или 8 символов или больше.
  • Из соображений безопасности и удобства использования следует избегать паролей, включающих имена пользователей или названия компаний.
  • Буквы верхнего и нижнего регистра следует смешивать.
  • Используйте библиотеку для расчета надежности пароля, будьте осторожны при выборе и проверяйте минимальные зависимости и ремонтопригодность.
  • Если у человека есть общедоступный профиль, используйте другое отображаемое имя и избегайте использования адреса электронной почты пользователя в качестве отображаемого имени, поскольку это способствует спаму.

Неиспользование двухфакторной аутентификации

Еще одна распространенная ошибка, которую я вижу в механизмах веб-аутентификации, заключается в том, что они не имеют никаких дополнительных мер безопасности. Двухфакторная аутентификация редко используется разработчиками, особенно для топовых аккаунтов. Двухфакторная аутентификация помогает добавить второй уровень защиты к вашему приложению. Двухфакторная аутентификация имеет решающее значение для веб-безопасности, поскольку она сразу устраняет опасность скомпрометированных учетных данных. Когда пароль взломан, угадан или даже заражен вредоносным ПО, уже недостаточно предоставить доступ злоумышленнику без одобрения на втором факторе аутентификации.

Двухфакторная аутентификация — это дополнительный уровень безопасности, добавляемый к странице аутентификации. Примерами этой двухфакторной аутентификации являются SMS, электронная почта и OTP.

Вот пример схемы двухфакторной аутентификации 

3

Как реализовать двухфакторную аутентификацию

Существует множество способов использования шифрования 2FA. Токены RSA, генераторы кодов, такие как Google Authenticator и Duo, и отправка SMS-сообщений с одноразовыми кодами — все это варианты реализации технологии 2FA.

Неверный сброс пароля

Это не так часто, но время от времени я вижу веб-приложение, в котором эта возможность реализована неправильно. Часто это происходит из-за того, что пароль пользователя был отправлен ему по электронной почте, или токен, использованный для сброса пароля, был недостаточно надежным. Отправка открытого текста пароля обратно конечному пользователю — еще одна проблема, влияющая на сброс пароля. Это ужасно по разным причинам, одна из которых заключается в том, что пароль был отправлен по электронной почте, что считается небезопасным. Это может означать, что пароль был сохранен в базе данных без достаточного хеширования или в формате, который можно было бы изменить, например base64.

Хэширование  — это метод, используемый для проверки или подтверждения качества различных видов входных данных. В системах аутентификации он в основном используется для предотвращения хранения незашифрованных паролей, а хэширование делает невероятно сложным для злоумышленников расшифровку сохраненных паролей.

Base64: Base64 — это метод преобразования двоичных данных в текст. Этот метод часто используется для отправки информации на основе контента через Интернет.

Как исправить этот недостаток

  • Всегда шифруйте пароли пользователей перед их сохранением, не храните их в необработанном виде.
  • Отправляйте транзакционные электронные письма только после проверки и проверки адресов электронной почты путем проверки допустимых символов и отправки ссылки для подтверждения с токеном.

Небезопасный выход

Это еще одна уязвимость, которая может серьезно повредить приложение. Также важно предоставить вашим пользователям безопасный способ выхода из системы, чтобы их сеансы не могли быть перехвачены. Если вы сохраняете идентификатор сеанса на стороне сервера, метод выхода из системы должен сделать его недействительным и стереть файл cookie сеанса в браузере. Это не позволяет злоумышленникам украсть файлы cookie сеанса, а затем использовать их для запуска нового сеанса.

Как исправить этот недостаток

  • Когда пользователь выходит из системы, очистите файл cookie сеанса браузера и сделайте недействительным идентификатор сеанса, если он хранится на сервере.
  • Во время выхода сеансы пользователей и токены аутентификации должны быть правильно аннулированы.

Атака грубой силы

Брутфорс — это метод взлома, используемый для получения учетных данных пользователя путем перебора различных возможных учетных данных. В этой атаке хакеры пытаются угадать пароли, чтобы пройти аутентификацию для одной учетной записи. Используя сценарии, которые пробуют многие часто используемые пароли из словаря и миллионы утекших паролей из предыдущих утечек данных, эти попытки имеют больше шансов на успех.

Как исправить этот недостаток

  • Ограничьте попытки входа в систему определенным IP-адресом или диапазоном, заблокировав доступ к URL-адресу аутентификации.
  • Не используйте термины из словарей на любом языке. Вместо слов предпочтительнее использовать случайные строки символов.
  • Блокируйте вредоносные IP-адреса с помощью CAPTCHAS.
  • Отслеживайте неудачные попытки входа пользователя и блокируйте учетную запись.

Использование недостаточного количества контрольных вопросов

Контрольный вопрос или запоминающееся слово также могут помочь в защите от автоматизированных атак. Я столкнулся с ненадежными секретными вопросами, ответы на которые предсказуемы, что позволяет злоумышленнику предлагать или угадывать ответы и получать доступ к данным пользователя.

Вот некоторые из популярных вопросов безопасности, с которыми я столкнулся:

  • В каком городе ты родился?
  • Какая твоя дата рождения?
  • В какой средней школе вы учились?
  • Какая девичья фамилия вашей матери?

Избегайте всех этих вопросов, потому что хакеры могут угадать их из-за некоторой нашей информации в нашем Google или других онлайн-профилях.

Как исправить этот недостаток

  • Рекомендовать вопросы, которые легко запомнить пользователю, но которые сложно предложить злоумышленникам.
  • Сохраняйте ответы, используя безопасный алгоритм хеширования, такой как Bcrypt. Bcrypt — это алгоритм, используемый для хеширования и проверки паролей. Это помогает снизить вероятность атаки киберпреступников на ваше приложение через пароль.

Неспособность защитить маршруты

Еще одна ошибка, которую я видел у разработчиков, когда дело доходит до аутентификации, — это «неспособность защитить маршрут». Крайне важно защитить определенные маршруты в вашем приложении от пользователей, не прошедших проверку подлинности, так как это предотвратит доступ неизвестных пользователей к некоторым личным данным вашего приложения.

Как исправить этот недостаток

  • Защитите маршрут, к которому должны получить доступ пользователи, не прошедшие проверку подлинности.
  • Если пользователь пытается получить доступ к определенному маршруту, перенаправьте его на страницу входа/регистрации, если он не прошел проверку подлинности.

Вывод

При внедрении аутентификации на своем веб-сайте вы как разработчик должны проявлять крайнюю осторожность, поскольку некоторые методы могут нанести серьезный ущерб вашей программе и дать злоумышленникам возможность захватить контроль над данными пользователей и приложением. Надеюсь, в этой статье были выделены такие ошибки и даны советы по их устранению.

Ссылка: https://blog.openreplay.com/11-authentication-mistakes-and-how-to-fix-them

#authentication

What is GEEK

Buddha Community

11 основных ошибок аутентификации и способы их исправления
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 

11 основных ошибок аутентификации и способы их исправления

Безопасность аутентификации — важный аспект разработки веб-приложений, который часто упускается из виду при создании продукта. Однако, если вы собираетесь подать заявку онлайн, это является главным приоритетом. В этой статье я объясню некоторые из этих ошибок и как их исправить. Обратите внимание, что это не основные проблемы безопасности, которые рекомендует OWASP ; вместо этого это легко устраняемые проблемы, которые я часто вижу.

Что такое аутентификация?

Аутентификация — это процесс подтверждения личности пользователя или процесса. При нарушении аутентификации злоумышленники могут получить доступ к данным или информации пользователя, нанеся ущерб вашему приложению. Аутентификация — это один из способов, которым злоумышленники могут получить доступ к данным пользователя и вашему приложению.

Когда дело доходит до аутентификации, вот одиннадцать распространенных ошибок, которых следует избегать:

  1. Отображение конкретных сообщений об ошибках
  2. Интеграция идентификаторов сеанса в URL-адрес
  3. Неправильная проверка формы
  4. Санитарная обработка низкой формы
  5. Стратегия слабого пароля
  6. Неиспользование двухфакторной аутентификации (2FA)
  7. Неверный сброс пароля
  8. Небезопасный выход
  9. Атака грубой силы
  10. Использование слабых контрольных вопросов
  11. Неспособность защитить маршрут

Отображение определенных сообщений об ошибках

Отображение определенного сообщения об ошибке опасно, потому что это может позволить злоумышленнику использовать автоматизированный метод проб и ошибок для определения имени пользователя или пароля пользователя.

Вот пример схемы отображения определенного сообщения об ошибке. 

первый

При аутентификации формы в вашем веб-приложении вы должны быть осторожны, чтобы не отображать только одно сообщение об ошибке, когда пользователь вводит неверные данные, например «Ваш пароль неверен». Если вы покажете такое конкретное сообщение об ошибке, злоумышленник поймет, что адрес электронной почты или идентификатор пользователя реальны, но пароль неверный. Это позволит злоумышленнику предложить пароль для этого пользователя.

Как исправить этот недостаток

  • Никогда не показывать конкретное сообщение об ошибке на странице аутентификации. Это позволяет злоумышленнику узнать, какая информация отсутствует, и позволяет ему использовать атаку грубой силы, чтобы угадать, какая информация отсутствует.
  • Отображение сообщений об ошибках, таких как «неправильные данные».

Интеграция идентификаторов сеанса в URL-адрес

Идентификатор сеанса — это число, которое сервер веб-сайта присваивает одному пользователю на время посещения этого пользователя. Вероятность того, что злоумышленник получит токен сеанса и злоупотребит им, увеличивается, если он размещен непосредственно в URL-адресе. Хотя риск при использовании HTTPS для подключения к веб-серверу ниже, опасность все же существует. Несмотря на то, что URL-адреса HTTPS шифруются при передаче, они часто сохраняются в журналах сервера.

Вот пример схемы интеграции идентификаторов сеансов в URL-адреса.

2

Как исправить этот недостаток

  • Проверка идентификатора сеанса на стороне сервера
  • Чтобы создать токен, убедитесь, что вы используете достаточно безопасный генератор случайных чисел.
  • Используйте фильтр, чтобы удалить идентификатор сеанса из URL-адреса.

Неверная проверка формы.

Атаки с внедрением, утечки памяти и скомпрометированные системы могут произойти, если данные, предоставленные во входных данных формы, не проверены или не отформатированы должным образом. Пользователи часто отправляют, не заполнив всю необходимую информацию, поэтому необходимо проверить вашу форму, чтобы убедиться, что вся необходимая информация была соблюдена, прежде чем отправлять ее на сервер.

Как исправить этот недостаток

  • Убедитесь, что письмо имеет форматирование адреса электронной почты.
  • Перед отправкой убедитесь, что пользователь соответствует критериям формы.
  • Проверяйте форму из бэкэнда и внешнего интерфейса, используя обновленную библиотеку или фреймворк.

Некоторые из предлагаемых библиотек, которые я рекомендую для проверки формы:

Все перечисленные библиотеки хороши для проверки вашей формы.

Санитарная обработка низкой формы 

Процесс поддержания чистоты, фильтрации и очистки ввода формы от вредоносного агента называется очисткой формы. Дезинфекция вашего ввода является обязательной, потому что она предотвращает ошибки инъекций. Хорошо продезинфицированная форма ввода может предотвратить следующие атаки:

Межсайтовый скриптинг (XSS): это тип уязвимости системы безопасности, который часто встречается в веб-приложениях. Эта уязвимость позволяет злоумышленникам вставлять клиентские скрипты в просматриваемые пользователями веб-страницы. Эта атака может нанести значительный ущерб безопасности пользователя, например перенаправить его на вредоносный веб-сайт, заставить его загрузить вредоносное приложение и украсть данные пользователя.

Внедрение SQL: Злоумышленники могут вмешиваться в данные, отправленные в его базу данных через ввод формы. 

Дезинфицируя ввод формы, вы должны защитить свой код и данные пользователя от этого вредоносного агента и всех перечисленных уязвимостей. Я лично использую DOM Purify , библиотеку очистки для HTML и строк, и она может фильтровать все, что содержит грязный HTML, и предотвращать атаки XSS.

Как исправить этот недостаток

  • Значительно проще и безопаснее использовать белый список для четко определенных входных данных, таких как числа, даты или почтовые индексы. В связи с этим вы можете явно указать, какие значения разрешены, а какие нет.
  • Используйте предопределенную логику списка разрешенных во встроенных определениях типов данных с проверкой формы HTML5.

Стратегия слабого пароля

Нередко можно встретить веб-сайт, на котором нет надежного плана паролей. Недавно я попробовал приложение, которое требовало минимальной длины пароля из пяти символов. Поскольку разработчики пытаются найти правильный баланс между безопасностью и удобством использования, этот недостаток становится все более распространенным. При работе с паролями убедитесь, что пароль, который вы предлагаете пользователю, или пароль, который создает пользователь, представляет собой смесь символов, цифр и букв смешанного регистра. Избегайте слабых планов паролей.

Как исправить этот недостаток

  • Требовать от пользователя ввести минимум 12 или 8 символов или больше.
  • Из соображений безопасности и удобства использования следует избегать паролей, включающих имена пользователей или названия компаний.
  • Буквы верхнего и нижнего регистра следует смешивать.
  • Используйте библиотеку для расчета надежности пароля, будьте осторожны при выборе и проверяйте минимальные зависимости и ремонтопригодность.
  • Если у человека есть общедоступный профиль, используйте другое отображаемое имя и избегайте использования адреса электронной почты пользователя в качестве отображаемого имени, поскольку это способствует спаму.

Неиспользование двухфакторной аутентификации

Еще одна распространенная ошибка, которую я вижу в механизмах веб-аутентификации, заключается в том, что они не имеют никаких дополнительных мер безопасности. Двухфакторная аутентификация редко используется разработчиками, особенно для топовых аккаунтов. Двухфакторная аутентификация помогает добавить второй уровень защиты к вашему приложению. Двухфакторная аутентификация имеет решающее значение для веб-безопасности, поскольку она сразу устраняет опасность скомпрометированных учетных данных. Когда пароль взломан, угадан или даже заражен вредоносным ПО, уже недостаточно предоставить доступ злоумышленнику без одобрения на втором факторе аутентификации.

Двухфакторная аутентификация — это дополнительный уровень безопасности, добавляемый к странице аутентификации. Примерами этой двухфакторной аутентификации являются SMS, электронная почта и OTP.

Вот пример схемы двухфакторной аутентификации 

3

Как реализовать двухфакторную аутентификацию

Существует множество способов использования шифрования 2FA. Токены RSA, генераторы кодов, такие как Google Authenticator и Duo, и отправка SMS-сообщений с одноразовыми кодами — все это варианты реализации технологии 2FA.

Неверный сброс пароля

Это не так часто, но время от времени я вижу веб-приложение, в котором эта возможность реализована неправильно. Часто это происходит из-за того, что пароль пользователя был отправлен ему по электронной почте, или токен, использованный для сброса пароля, был недостаточно надежным. Отправка открытого текста пароля обратно конечному пользователю — еще одна проблема, влияющая на сброс пароля. Это ужасно по разным причинам, одна из которых заключается в том, что пароль был отправлен по электронной почте, что считается небезопасным. Это может означать, что пароль был сохранен в базе данных без достаточного хеширования или в формате, который можно было бы изменить, например base64.

Хэширование  — это метод, используемый для проверки или подтверждения качества различных видов входных данных. В системах аутентификации он в основном используется для предотвращения хранения незашифрованных паролей, а хэширование делает невероятно сложным для злоумышленников расшифровку сохраненных паролей.

Base64: Base64 — это метод преобразования двоичных данных в текст. Этот метод часто используется для отправки информации на основе контента через Интернет.

Как исправить этот недостаток

  • Всегда шифруйте пароли пользователей перед их сохранением, не храните их в необработанном виде.
  • Отправляйте транзакционные электронные письма только после проверки и проверки адресов электронной почты путем проверки допустимых символов и отправки ссылки для подтверждения с токеном.

Небезопасный выход

Это еще одна уязвимость, которая может серьезно повредить приложение. Также важно предоставить вашим пользователям безопасный способ выхода из системы, чтобы их сеансы не могли быть перехвачены. Если вы сохраняете идентификатор сеанса на стороне сервера, метод выхода из системы должен сделать его недействительным и стереть файл cookie сеанса в браузере. Это не позволяет злоумышленникам украсть файлы cookie сеанса, а затем использовать их для запуска нового сеанса.

Как исправить этот недостаток

  • Когда пользователь выходит из системы, очистите файл cookie сеанса браузера и сделайте недействительным идентификатор сеанса, если он хранится на сервере.
  • Во время выхода сеансы пользователей и токены аутентификации должны быть правильно аннулированы.

Атака грубой силы

Брутфорс — это метод взлома, используемый для получения учетных данных пользователя путем перебора различных возможных учетных данных. В этой атаке хакеры пытаются угадать пароли, чтобы пройти аутентификацию для одной учетной записи. Используя сценарии, которые пробуют многие часто используемые пароли из словаря и миллионы утекших паролей из предыдущих утечек данных, эти попытки имеют больше шансов на успех.

Как исправить этот недостаток

  • Ограничьте попытки входа в систему определенным IP-адресом или диапазоном, заблокировав доступ к URL-адресу аутентификации.
  • Не используйте термины из словарей на любом языке. Вместо слов предпочтительнее использовать случайные строки символов.
  • Блокируйте вредоносные IP-адреса с помощью CAPTCHAS.
  • Отслеживайте неудачные попытки входа пользователя и блокируйте учетную запись.

Использование недостаточного количества контрольных вопросов

Контрольный вопрос или запоминающееся слово также могут помочь в защите от автоматизированных атак. Я столкнулся с ненадежными секретными вопросами, ответы на которые предсказуемы, что позволяет злоумышленнику предлагать или угадывать ответы и получать доступ к данным пользователя.

Вот некоторые из популярных вопросов безопасности, с которыми я столкнулся:

  • В каком городе ты родился?
  • Какая твоя дата рождения?
  • В какой средней школе вы учились?
  • Какая девичья фамилия вашей матери?

Избегайте всех этих вопросов, потому что хакеры могут угадать их из-за некоторой нашей информации в нашем Google или других онлайн-профилях.

Как исправить этот недостаток

  • Рекомендовать вопросы, которые легко запомнить пользователю, но которые сложно предложить злоумышленникам.
  • Сохраняйте ответы, используя безопасный алгоритм хеширования, такой как Bcrypt. Bcrypt — это алгоритм, используемый для хеширования и проверки паролей. Это помогает снизить вероятность атаки киберпреступников на ваше приложение через пароль.

Неспособность защитить маршруты

Еще одна ошибка, которую я видел у разработчиков, когда дело доходит до аутентификации, — это «неспособность защитить маршрут». Крайне важно защитить определенные маршруты в вашем приложении от пользователей, не прошедших проверку подлинности, так как это предотвратит доступ неизвестных пользователей к некоторым личным данным вашего приложения.

Как исправить этот недостаток

  • Защитите маршрут, к которому должны получить доступ пользователи, не прошедшие проверку подлинности.
  • Если пользователь пытается получить доступ к определенному маршруту, перенаправьте его на страницу входа/регистрации, если он не прошел проверку подлинности.

Вывод

При внедрении аутентификации на своем веб-сайте вы как разработчик должны проявлять крайнюю осторожность, поскольку некоторые методы могут нанести серьезный ущерб вашей программе и дать злоумышленникам возможность захватить контроль над данными пользователей и приложением. Надеюсь, в этой статье были выделены такие ошибки и даны советы по их устранению.

Ссылка: https://blog.openreplay.com/11-authentication-mistakes-and-how-to-fix-them

#authentication

2016-2017 inside Evaluation: How must the Los Angeles Kings hire Dusti

For the up coming thirty day period or 2, wel be having a seem to be at the gamers who produced the Los Angeles Kings2016-17 year what it was: a crushing frustration that acquired All those fired an up-and-down trip which maintained in direction of be both of those uncommon and acquainted. Fairly than the positive-undesirable-long run-quality layout wee made use of inside of last seasons, wel talk to a critical speculate and solution it utilizing it what we observed this calendar year.(Seriously, inside this scenario, wel check with 2 significant issues...)Why need to the Kings section with their #1 decide on inside of purchase in direction of unload Dustin Brown agreement? “WHY WOULD Oneself EVEN Talk to THAT QUESTION”I can say with self esteem that this is a person of the minimum amount beloved components I include at any time prepared, match or non-video game identical. Believe that me Whilst I say that I delight in Dustin Brown, and that my enjoy for him goes over and above his design and style of participate in, his management of the Kings, and his propensity toward do foolish components upon the bench. He is, very easily area, the design and style of individual your self assume your kid grows up towards be https://www.storekingsapparel.com/Alex_Turcotte_Jersey-166, and his personality and commitment towards loved ones are unimpeachable. Moreover, Sean Avery is and will normally be a P.O.S. Nevertheless, Brown is too a before long in the direction of be 30-3 12 months outdated still left-winger with declining output and a significant, albatross-which include agreement. Provided that the Kings are saddled with a different unattractive agreement apart from Brown be concerned, Kings lovers, be amazingly anxious and a determined require for quickness and ability in just their final-6, it is very last year towards lean sentimental with roster alternate options. Therefore, Il create 2 arguments below. The very first is why the Kings need to deliver a bundle with the Vegas Golden Knights in direction of comprise them acquire Dustin Brown Austin Wagner Jersey, even at the price tag of their 1st-spherical pick out (#11) in just the 2017 NHL Draft. The moment argument, which is a much even more possibly predicament, is how the Kings need to seek the services of Brown in just 2017-2018 if he stays upon the roster.I will be trustworthy, I am not persuaded of the argument that follows, and recognize that it fails toward acquire into account Brown management upon and off the ice Alex Turcotte Jersey. I am, Regrettably, cautious of the “what shed towards this personnel is grit!line of questioning, as a result incorporate favored towards discard it for the period staying. I way too comprehend that plenty of will uncover the principle of working the #11 select a awful one particular for a staff with very little organizational element. That is totally a sensible simple fact, nevertheless for a workers with, inside of my estimation, a 2-12 months Cup window, the chance in the direction of increase ability toward the roster getting Brown freed-up AAV is as well essential in direction of move up. Within addition, I do not worthy of to start with spherical selections Very as significant as some others, at bare minimum not presented this team recent context...hence there that.How poor is Dustin Brown agreement? With 5 many years currently being and a $5 Brett Sutter Jersey.875 million ordinary yearly cost, Brown offer is broadly regarded as 1 of the worst in just the league. Inspite of his better 2016-2017 year, the trajectory of Brown upon-ice output is apparent and hopes of a late-point revival possibly unrealistic, even with a looser offensive philosophy needed inside 2017-2018. As Jon Rosen pointed toward inside of his individual investigation of Brown 2016-2017 time, Brown improved generation masked few stressing traits, and there is space for issue that he dragged down his 2 utmost regular centermen, Anze Kopitar and Nic Dowd. Consequently what my issue? My position is that we learnt ultimate time that Brown and Gaborik are no extended final-6 forwards and hiding them inside the backside-6 is a recipe for catastrophe (not towards point out a clogged developmental pipeline). Alternatively, the Kings ought to rethink their very clear unwillingness toward package their #11 select and perspective if the Vegas Golden Knights would assert it and Brown management. Brown agreement is a person yr for a longer time and a single million heavier than Gaborik, and if the intent is toward unload 1 of them, then Brown is the 1 toward shed, and it would produce obtaining out Gaborik that substantially simpler towards swallow.What would I endorse performing with the $5.875 million of further more region down below the cap right after these types of a go? I consider there are couple of intelligent circumstances accessible. All right, yet truly, how really should the Kings seek the services of Dustin Brown within just 2017-2018? “This hurts, and your moment ponder alterations practically nothing.”Now that I contain used 3 hundred and seventy 6 text upon one thing that is not relocating toward come about and will crank out random persons enraged with me, let chat around how the Kings ought to seek the services of Dustin Brown upcoming period. Towards begin, I do not imagine John Stevens must progress tying Brown toward Kopitar. Brown observed 34% of his amount of money ice season with Anze, and either my eye and the quantities direct me toward think he is a drag upon our selection one particular heart. If Stevens is hunting towards boost offensive generation towards Kopitar, selling him with greater ability upon his wings is a precedence. I furthermore do not feel that tying Brown in the direction of a 3rd-line purpose, heading with Nic Dowd (should really Vegas not decide on him upon Wednesday), is a smart thought. Collectively for 29% of Brown general ice season inside 2016-2017, the 2 preserved in the direction of deliver a Objectives For/60 (5v5) of 1.94 whilst conceding 2.81 Plans Versus/60 (5v5). Dowd includes detailed ability and house for enhancement, and it would feel that he and Brown would ease in opposition to some breakup following calendar year. My prescription for Brown is 2017-2018 is a instant-line function with Jeff Carter. Inside 188 minutes of 5v5 period collectively remaining period, they created an modern 3.51 objectives for/60 though conceding an both modern 1.59 plans in opposition to/60. The two start out generally inside of the offensive zone, both equally effort and hard work nicely biking the puck, and Brown greater willingness in direction of take his video game back again toward a world wide web-entrance existence orientation will help Carter natural and organic tendency toward shoot puck https://www.storekingsapparel.com/Denis_Dejordy_Jersey-60.ConclusionDustin Brown is a remarkable specific, a Kings legend, and neither of individuals will at any time difference. It is not his fault that he signed a significant, properly-deserved, deal at the identical issue that his video game deserted him, and there is no wonder that he desires a return toward glory much more than any of us. Continue to, the Kings are within a precarious nation and their chances toward gain a further Stanley Cup are shrinking calendar year by means of 12 months. If the workers thinks that his participate in will progress in direction of deteriorate and that his agreement will keep away from them in opposition to creating for the potential, it would be clever in direction of take into account the worthy of of their 2017 #11 draft decide on. If it doesn hard work (and possibly it now hasn labored), let be expecting they come across the specifically job for him.

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 

Chaz  Homenick

Chaz Homenick

1593274320

Android 11 beta plans

Android 11 was moved to the Developer Preview 4 this week, and beta one has been moved to June 3rd to coincide with the company’s online developer event referred to as #Android11: the Beta Launch Show.

Developer Preview 4 comes with the most recent bug fixes, API tweaks, and features for developers to try in their apps. Extra details on the changes are on the market here.

In addition, Google has decided to add additional time to the Android 11 to announce the schedule. Beta 1 and all subsequent milestones are moved out by a few months to relinquish the additional room, but, to also keep the final unleash for later in Q3.

Beta 1 on June 3rd will include the final SDK and NDK APIs and Google Play publishing for apps targeting Android 11 are going to be opened.

Subsequently, Beta 2 will be moved to July and can contain Platform Stability and system behaviors and non-greylists also will be finalized. Beta 3 can move in August and can include publishing candidate builds for final testing.

“The schedule modification adds some additional time for you to check your app for compatibility and establish any work you’ll have to be compelled to do,” Dave Burke, VP of engineering for Android, wrote in a diary post. “We suggest releasing a compatible app update by Android 11 Beta on June 3rd to get feedback from the larger group of Android Beta users who will obtain the update.”

Google also added that developers can begin to do compatibility tests on a Pixel 2, 3, 3a, or 4 devices, or use the Android Emulator. They only got to flash the most recent build, install their current production app, and check the user flows.

#technology #android 11 beta plans #android 11 beta show #android 11 developer preview 3 #android 11 name #developer events