STM32H735 - MbedTLS wraz blokami HASH, CRYP oraz RNG

W tym poście chciałbym opisać sprzętową akcelerację  niektórych usług kryptograficznych na układzie STM32H735 oraz sposób ich integracji z biblioteką mbedTLS. 

Projekt wykorzystuje takie bloki sprzętowe jak CRYP, HASH oraz RNG. Dzięki nim można przenieść część operacji kryptograficznych z rdzenia Cortex-M7 do odpowiednich bloków sprzętowych. 

Taka implementacja pozwoli na wykorzystanie tych możliwości bez dodatkowych zmian interfejsów w bibliotece mbedTLS. Dostęp do akceleracji sprzętowej będzie realizowany przez standardowe funkcje biblioteki. 

CRYP:

Blok CRYP odpowiada za sprzętową realizację operacji szyfrowania AES. W projekcie wykorzystuje go do AES-ECB, AES-CBC oraz AES-GCM. 

W przypadku AES-ECB realizowane jest szyfrowanie i deszyfrowanie pojedynczych bloków danych o długości 128 bitów. 

Dla AES-CBC przekazywany jest cały bufor danych, bez dodatkowych operacji szyfrowania dla każdego bloku na poziomie aplikacji. Do transferu danych pomiędzy pamięcią a modułem CRYP korzystam z DMA. 

W trybie AES-GCM peryferium realizuje szyfrowanie AES w trybie licznikowym oraz operacje GHASH. Jest ono wykorzystywane podczas obliczania taga uwierzytelniającego. 

HASH:

Blok HASH wykorzystywany jest do sprzętowego obliczania funkcji skrótu (SHA-224, SHA-256). Dane mogą być przekazywane strumieniowo. Dzięki temu nie ma buforowania całej wiadomości w pamięci RAM. 

Nie korzystam tutaj z DMA. W tym przypadku jest to znacznie trudniejsze. Bibliotek mbedTLS obsługuje kilka niezależnych kontekstów SHA-256, które współdzielą jeden blok HASH. Takie działanie w trybie DMA byłoby utrudnione z powodu konieczności synchronizacji końcówki transferu czy współdzielenia HASH. 

Polling pozwala dokładnie określić kiedy obliczenia zostały zakończone. Bezpiecznie zapisać stan tego peryferium. Wykorzystanie DMA w takim przypadku mogłoby wygenerować więcej problemów niż korzyści z jego zastosowania. 

RNG:

Tutaj stosowany jest jako sprzętowe źródło entropii dla mbedTLS. 

Dane przesyłane z RNG podawane są do generowania liczb pseudolosowych CTR_DRBG. Wykorzystywane jest to np. do nawiązywania połączenia TLS czy wykonywania operacji kryptograficznych wymagających losowości.

Konfiguracja MBED-TLS:

Pierwszym krokiem jest wybranie odpowiednich elementów, które odpowiadają za alternatywną implementację:

Otwieramy plik:

1. MBEDTLS/App/mbedtls_config.h

Gdzie uruchamiamy następujące definicje:

1. #define MBEDTLS_GCM_ALT
2. #define MBEDTLS_SHA256_ALT
3. #define MBEDTLS_AES_SETKEY_ENC_ALT
4. #define MBEDTLS_AES_SETKEY_DEC_ALT
5. #define MBEDTLS_AES_ENCRYPT_ALT
6. #define MBEDTLS_AES_DECRYPT_ALT
7. #define MBEDTLS_STM32_AES_CBC_HW
8. #define MBEDTLS_ENTROPY_HARDWARE_ALT

Zostawiamy standardowe moduły z biblioteki uruchomione:

1. #define MBEDTLS_AES_C
2. #define MBEDTLS_GCM_C
3. #define MBEDTLS_SHA256_C
4. #define MBEDTLS_ENTROPY_C
5. #define MBEDTLS_CTR_DRBG_C

Powyższe definicje odpowiadają za włączenie poszczególnych modułów w bibliotece mbedTLS. 

Definicje z końcówka _ALT pozwalają na zastąpienie standardowej implementacji całego modułu czy wybranych funkcji własną implementacją. 

Blok CRYP operacje AES-ECB:

STM32H735 posiada sprzętowy moduł CRYP. Pozwala on na wykonywanie operacji AES odciążając tym samym rdzeń układu Cortex-M7. 

Dołożone zostały cztery podstawowe funkcje:

1. mbedtls_aes_setkey_enc()
2. mbedtls_aes_setkey_dec()
3. mbedtls_internal_aes_encrypt()
4. mbedtls_internal_aes_decrypt()

Odpowiadają one wcześniejszym definicjom:

1. #define MBEDTLS_AES_SETKEY_ENC_ALT
2. #define MBEDTLS_AES_SETKEY_DEC_ALT
3. #define MBEDTLS_AES_ENCRYPT_ALT
4. #define MBEDTLS_AES_DECRYPT_ALT

Przyjrzyjmy się tym funkcjom: 

1. #if defined(MBEDTLS_AES_SETKEY_ENC_ALT)
2.  
3. static int stm32_aes_rounds_from_keybits(unsigned int keybits) {
4.     switch (keybits) {
5.         case 128U: return (10);
6.         case 192U: return (12);
7.         case 256U: return (14);
8.         default:   return (-1);
9.     }
10. }
11.  
12. int mbedtls_aes_setkey_enc(mbedtls_aes_context *ctx,
13.                            const unsigned char *key,
14.                            unsigned int keybits)
15. {
16.     stm32_mbedtls_aes_hw_ctx_t *hw_ctx;
17.     int rounds;
18.  
19.     if ((ctx == NULL) || (key == NULL)) {
20.         return (MBEDTLS_ERR_AES_BAD_INPUT_DATA);
21.     }
22.  
23.     //Wyznaczenie liczby rund AES na podstawie długości klucza
24.     rounds = stm32_aes_rounds_from_keybits(keybits);
25.  
26.     if (rounds < 0) {
27.         return (MBEDTLS_ERR_AES_INVALID_KEY_LENGTH);
28.     }
29.  
30.     memset(ctx, 0, sizeof(*ctx));
31.  
32.     //Zapis liczby rund oraz bufora
33.     ctx->nr = rounds;
34.     ctx->rk = ctx->buf;
35.  
36.     hw_ctx = stm32_aes_ctx_get(ctx);
37.     hw_ctx->keybits = keybits;
38.  
39.     //Zapisywanie klucza
40.     memcpy(hw_ctx->key_bytes, key, keybits / 8U);
41.  
42.     return (0);
43. }
44.  
45. #endif

Powyższa funkcja przygotowuje dane kontekstu AES wykorzystywanego do operacji szyfrowania. Zapamiętywany jest klucz wraz z długością. Operacje AES będę wykonywane później przez blok sprzętowy CRYP. 

Klucz do operacji deszyfrowania jest przygotowany przez tą samą funkcję. Z funkcji mbedtls_aes_setkey_dec(...) jest wywoływana funckja mbedtls_aes_setkey_enc(...). Wykorzystywany będzie ten sam klucz. Wybór operacji w bloku CRYP określi czy będzie wykonywana operacja szyfrowania czy deszyfrowania. 

Teraz funkcja wykonująca szyfrowanie pojedynczego bloku AES:

1. #if defined(MBEDTLS_AES_ENCRYPT_ALT)
2.  
3. static int stm32_aes_prepare_hw(const stm32_mbedtls_aes_hw_ctx_t *hw_ctx)
4. {
5.     stm32_aes_prepare_key_words((uint32_t *)hw_ctx->key_words, hw_ctx->key_bytes,
6.                                 hw_ctx->keybits, g_stm32_aes_swap_key_words);
7.  
8.     return stm32_aes_prepare_hw_words((uint32_t *)hw_ctx->key_words, hw_ctx->keybits,
9.                                       g_stm32_aes_data_type, CRYP_AES_ECB, NULL);
10. }
11.  
12. static void stm32_aes_lock(void)
13. {
14.     if (g_mbedTlsMutex != NULL)
15.     {
16.         (void)xSemaphoreTakeRecursive(g_mbedTlsMutex, portMAX_DELAY);
17.     }
18. }
19.  
20. int mbedtls_internal_aes_encrypt(mbedtls_aes_context *ctx,
21.                                  const unsigned char input[16],
22.                                  unsigned char output[16])
23. {
24.     HAL_StatusTypeDef status;
25.     int ret;
26.  
27.     if ((ctx == NULL) || (input == NULL) || (output == NULL)) {
28.         return (MBEDTLS_ERR_AES_BAD_INPUT_DATA);
29.     }
30.  
31.     //Blokowanie dostępu do modułu przez
32.     //ustawienie mutexa
33.     stm32_aes_lock();
34.  
35.     //Sprawdzenie działania
36.     stm32_aes_run_selftest_once();
37.  
38.     //Przygotowanie modułu do działania:
39.     //ustawienie klucza, jego długości, kolejności
40.     ret = stm32_aes_prepare_hw(stm32_aes_ctx_get(ctx));
41.  
42.     if (ret == 0)
43.     {
44.         //Wykonanie szyfrowania. Operacja na bloku 128 bitowym (16 bajtów)
45.         status = HAL_CRYP_Encrypt(&hcryp, (uint32_t *)input, 16U,
46.                                   (uint32_t *)output, HAL_MAX_DELAY);
47.  
48.         //Konwersja kodu błędu
49.         ret = (status == HAL_OK)
50.             ? 0
51.             : MBEDTLS_ERR_AES_HW_ACCEL_FAILED;
52.  
53.         if (ret != 0) {
54.             //Wypisanie błędu na konsole.
55.             stm32_aes_log_block("enc", input, output,
56.                         stm32_aes_ctx_get(ctx)->keybits, status);
57.         }
58.     }
59.     else {
60.         printf("[AESHW] enc prep ERROR ret=%d\r\n", ret);
61.     }
62.  
63.     //Zwolnienie dostępu
64.     stm32_aes_unlock();
65.  
66.     return ret;
67. }
68.  
69. #endif

Do funkcji przekazywany jest pojedynczy blok AES (16 bajtów) . Po zakończeniu operacji zwracany jest 16-bajtowy blok zaszyfrowanych danych. 

Funkcja deszyfrująca jest podobna więc nie będę jej już tutaj wklejał. 

Głównym elementem sprzętowej implementacji są funkcje HAL_CRYP_Encrypt(...) oraz HAL_CRYP_Decrypt(). Moduł CRYP skonfigurowany jest w trybie CRYP_AES_ECB. Do peryferium przekazywany jest pojedynczy 128-bitowy blok danych. Właściwe operacje AES wykonywane są przez sprzętowy akcelerator kryptograficzny. Rdzeń Cortex-M7 nie musi programowo wykonywać kolejnych rund algorytmu AES. 

Sprzętowa realizacja AES-CBC:

Peryferium konfigurujemy jako CRYP_AES_CBC. Moduł otrzymuje klucz AES, IV, bufor wejściowy oraz długość danych. Blok CRYP wykonuje operacje AES oraz mechanizm łańcuchowania charakterystyczny dla CBC. 

Po stronie programu konieczne jest poprawne przygotowanie konfiguracji modułu. Cała funkcja wygląda następująco:

1. int stm32_mbedtls_aes_crypt_cbc(mbedtls_aes_context *ctx,
2.                                  int mode,
3.                                  size_t length,
4.                                  unsigned char iv[16],
5.                                  const unsigned char *input,
6.                                  unsigned char *output)
7. {
8.     stm32_mbedtls_aes_hw_ctx_t *hw_ctx;
9.     uint32_t iv_words[4];
10.     unsigned char last_cipher[16];
11.     size_t chunk_length;
12.     HAL_StatusTypeDef status;
13.     int ret;
14.  
15.     if ((ctx == NULL) || (iv == NULL) || (input == NULL) || (output == NULL) ||
16.         ((mode != MBEDTLS_AES_ENCRYPT) && (mode != MBEDTLS_AES_DECRYPT)) ||
17.         ((length % 16U) != 0U))
18.     {
19.         return MBEDTLS_ERR_AES_BAD_INPUT_DATA;
20.     }
21.  
22.     if (length == 0U)
23.     {
24.         return 0;
25.     }
26.  
27.     stm32_aes_lock();
28.     stm32_aes_run_selftest_once();
29.     ret = stm32_aes_run_cbc_selftest_once();
30.     if (ret != 0)
31.     {
32.         stm32_aes_unlock();
33.         return ret;
34.     }
35.  
36.     hw_ctx = stm32_aes_ctx_get(ctx);
37.     stm32_aes_prepare_key_words(hw_ctx->key_words, hw_ctx->key_bytes,
38.                                 hw_ctx->keybits, g_stm32_aes_swap_key_words);
39.  
40.     while (length != 0U)
41.     {
42.         chunk_length = (length > 65520U) ? 65520U : length;
43.         stm32_aes_prepare_iv_words(iv_words, iv);
44.         ret = stm32_aes_prepare_hw_words(hw_ctx->key_words, hw_ctx->keybits,
45.                                          g_stm32_aes_data_type, CRYP_AES_CBC,
46.                                          iv_words);
47.         if (ret != 0)
48.         {
49.             break;
50.         }
51.  
52.         if (mode == MBEDTLS_AES_DECRYPT)
53.         {
54.             memcpy(last_cipher, input + chunk_length - sizeof(last_cipher),
55.                    sizeof(last_cipher));
56.         }
57.  
58.         if ((chunk_length >= STM32_AES_DMA_MIN_LENGTH) &&
59.             ((((uintptr_t)input | (uintptr_t)output) & 3U) == 0U) &&
60.             (stm32_aes_dma_addressable(input, chunk_length) != 0) &&
61.             (stm32_aes_dma_addressable(output, chunk_length) != 0))
62.         {
63.             status = stm32_aes_cbc_dma(mode, input, output,
64.                                        (uint16_t)chunk_length);
65.         }
66.         else if (mode == MBEDTLS_AES_DECRYPT)
67.         {
68.             status = HAL_CRYP_Decrypt(&hcryp, (uint32_t *)input,
69.                                       (uint16_t)chunk_length, (uint32_t *)output,
70.                                       HAL_MAX_DELAY);
71.         }
72.         else
73.         {
74.             status = HAL_CRYP_Encrypt(&hcryp, (uint32_t *)input,
75.                                       (uint16_t)chunk_length, (uint32_t *)output,
76.                                       HAL_MAX_DELAY);
77.         }
78.  
79.         if (status != HAL_OK)
80.         {
81.             stm32_aes_log_block("CBC", input, output, hw_ctx->keybits, status);
82.             ret = MBEDTLS_ERR_AES_HW_ACCEL_FAILED;
83.             break;
84.         }
85.  
86.         if (mode == MBEDTLS_AES_DECRYPT)
87.         {
88.             memcpy(iv, last_cipher, sizeof(last_cipher));
89.         }
90.         else
91.         {
92.             memcpy(iv, output + chunk_length - sizeof(last_cipher),
93.                    sizeof(last_cipher));
94.         }
95.  
96.         input += chunk_length;
97.         output += chunk_length;
98.         length -= chunk_length;
99.     }
100.  
101.     stm32_aes_unlock();
102.     return ret;
103. }

Istotnym elementem powyższej funkcji jest:

1. ret = stm32_aes_prepare_hw_words(
2.     hw_ctx->key_words,
3.     hw_ctx->keybits,
4.     g_stm32_aes_data_type,
5.     CRYP_AES_CBC,
6.     iv_words);

Blok CRYP zostaje ustawiony w trybie CRYP_AES_CBC.

Po skonfigurowaniu modułu CRYP dane można przekazywać do HAL_CRYP_Encrypt() czy HAL_CRYP_Decrypt().  Ścieżka DMA jest wykorzystywana jak zostaną spełnione warunki długości danych, wyrównania oraz obszaru pamięci. 

Powyższa funkcja zarządza całym kontekstem, IV, dzieleniem dużych buforów oraz wyborem ścieżki DMA bądź pollingu. 

Sprzętowa realizacja AES-GCM:

Standardowe funkcje GCM z mbedTLS zostały wyłączone. Zostały zastąpione własną implementację z wykorzystaniem bloku CRYP:

1. mbedtls_gcm_setkey();
2. mbedtls_gcm_starts();
3. mbedtls_gcm_update();
4. mbedtls_gcm_finish();
5. mbedtls_gcm_crypt_and_tag();
6. mbedtls_gcm_auth_decrypt();

Na samym początku należy przygotować klucz. 

1. int mbedtls_gcm_setkey(mbedtls_gcm_context *ctx, mbedtls_cipher_id_t cipher,
2.                        const unsigned char *key, unsigned int keybits)
3. {
4.     if ((ctx == NULL) || (key == NULL) || (cipher != MBEDTLS_CIPHER_ID_AES) ||
5.         ((keybits != 128U) && (keybits != 192U) && (keybits != 256U)))
6.     {
7.         return MBEDTLS_ERR_GCM_BAD_INPUT;
8.     }
9.  
10.     gcm_abort(ctx);
11.     memset(ctx->key, 0, sizeof(ctx->key));
12.     memcpy(ctx->key, key, keybits / 8U);
13.     gcm_key_words(ctx->key_words, ctx->key, keybits);
14.     ctx->keybits = keybits;
15.     return 0;
16. }

Powyższa funkcja sprawdza długość klucza, zapisuje wartość w kontekście GCM oraz przygotowuje słowa kluczowe. Wszystko w formacie wymaganym przeze peryferiom CRYP.

W następnym etapie jest wywołanie funkcji mbedtls_gcm_starts(). 

1. int mbedtls_gcm_starts(mbedtls_gcm_context *ctx, int mode,
2.                        const unsigned char *iv, size_t iv_len,
3.                        const unsigned char *add, size_t add_len)
4. {
5.     int ret;
6.  
7.     if (ctx == NULL)
8.     {
9.         return MBEDTLS_ERR_GCM_BAD_INPUT;
10.     }
11.  
12.     gcm_abort(ctx);
13.     if (((mode != MBEDTLS_GCM_ENCRYPT) &&
14.                           (mode != MBEDTLS_GCM_DECRYPT)) || (iv == NULL) ||
15.         (iv_len != 12U) || ((add_len != 0U) && (add == NULL)) ||
16.         (add_len > UINT32_MAX) || (ctx->keybits == 0U))
17.     {
18.         return (iv_len != 12U) ? MBEDTLS_ERR_PLATFORM_FEATURE_UNSUPPORTED :
19.                                  MBEDTLS_ERR_GCM_BAD_INPUT;
20.     }
21.  
22.     ctx->mode = mode;
23.     gcm_initial_counter(ctx->iv_words, iv);
24.     gcm_lock(ctx);
25.     ctx->trace_id = ++g_gcm_trace_sequence;
26.     GCM_TRACE("[GCMHW] start id=%lu mode=%s aad=%lu\r\n",
27.            (unsigned long)ctx->trace_id,
28.            (mode == MBEDTLS_GCM_ENCRYPT) ? "enc" : "dec",
29.            (unsigned long)add_len);
30.     ret = gcm_selftest_once();
31.     if (ret == 0)
32.     {
33.         ret = gcm_start_hardware(ctx, add, add_len);
34.     }
35.     if (ret != 0)
36.     {
37.         gcm_abort(ctx);
38.         return ret;
39.     }
40.  
41.     ctx->active = 1U;
42.     return 0;
43. }

Powyższa funkcja przygotowuje kontekst operacji, IV. Implementacja przyjmuje IV o długości 12 bajtów. Dalej przygotowywany jest początkowy licznik GCM oraz uruchamiana jest konfiguracja sprzętowego CRYP. 

Sprzętowe uruchomienie wygląda następująco:

1. static int gcm_start_hardware(mbedtls_gcm_context *ctx,
2.                               const unsigned char *add, size_t add_len)
3. {
4.     static const unsigned char empty[1] = { 0U };
5.     const unsigned char *header = add;
6.     uint32_t key_size;
7.     HAL_StatusTypeDef status;
8.  
9.     if (gcm_key_size(ctx->keybits, &key_size) != 0)
10.     {
11.         return MBEDTLS_ERR_GCM_BAD_INPUT;
12.     }
13.  
14.     hcryp.Instance = CRYP;
15.     hcryp.Init.DataType = CRYP_BYTE_SWAP;
16.     hcryp.Init.KeySize = key_size;
17.     hcryp.Init.pKey = ctx->key_words;
18.     hcryp.Init.Algorithm = CRYP_AES_GCM;
19.     hcryp.Init.pInitVect = ctx->iv_words;
20.     if ((add_len > 0U) && (add_len <= sizeof(ctx->header_words)))
21.     {
22.         memset(ctx->header_words, 0, sizeof(ctx->header_words));
23.         memcpy(ctx->header_words, add, add_len);
24.         header = (const unsigned char *)ctx->header_words;
25.     }
26.     hcryp.Init.Header = (uint32_t *)header;
27.     hcryp.Init.HeaderSize = (uint32_t)add_len;
28.     hcryp.Init.B0 = NULL;
29.     hcryp.Init.DataWidthUnit = CRYP_DATAWIDTHUNIT_BYTE;
30.     hcryp.Init.HeaderWidthUnit = CRYP_HEADERWIDTHUNIT_BYTE;
31.     hcryp.Init.KeyIVConfigSkip = CRYP_KEYIVCONFIG_ONCE;
32.  
33.     if (HAL_CRYP_Init(&hcryp) != HAL_OK)
34.     {
35.         return MBEDTLS_ERR_GCM_HW_ACCEL_FAILED;
36.     }
37.  
38.     status = (ctx->mode == MBEDTLS_GCM_ENCRYPT) ?
39.              HAL_CRYP_Encrypt(&hcryp, (uint32_t *)empty, 0U,
40.                               (uint32_t *)empty, HAL_MAX_DELAY) :
41.              HAL_CRYP_Decrypt(&hcryp, (uint32_t *)empty, 0U,
42.                               (uint32_t *)empty, HAL_MAX_DELAY);
43.     return (status == HAL_OK) ? 0 : MBEDTLS_ERR_GCM_HW_ACCEL_FAILED;
44. }

Jak widać powyżej ustawione jest w trybie CRYP_AES_GCM. 

Właściwe szyfrowanie czy deszyfrowanie realizowane jest przez funkcje mbedtls_gcm_update().

1. int mbedtls_gcm_update(mbedtls_gcm_context *ctx, size_t length,
2.                        const unsigned char *input, unsigned char *output)
3. {
4.     HAL_StatusTypeDef status;
5.  
6.     if ((ctx == NULL) || (ctx->active == 0U))
7.     {
8.         return MBEDTLS_ERR_GCM_BAD_INPUT;
9.     }
10.     if (((length != 0U) && ((input == NULL) || (output == NULL))) ||
11.         (length > UINT16_MAX) || ((ctx->final_input_seen != 0U) && (length != 0U)))
12.     {
13.         gcm_abort(ctx);
14.         return MBEDTLS_ERR_GCM_BAD_INPUT;
15.     }
16.  
17.     if (length == 0U)
18.     {
19.         return 0;
20.     }
21.  
22.     GCM_TRACE("[GCMHW] update id=%lu mode=%s len=%lu\r\n",
23.            (unsigned long)ctx->trace_id,
24.            (ctx->mode == MBEDTLS_GCM_ENCRYPT) ? "enc" : "dec",
25.            (unsigned long)length);
26.  
27.     size_t dma_length = length & ~(size_t)15U;
28.     if ((dma_length >= GCM_DMA_MIN_LENGTH) && (hcryp.hdmain != NULL) &&
29.         (g_mbedTlsMutex != NULL) &&
30.         (hcryp.hdmaout != NULL) && (xTaskGetSchedulerState() == taskSCHEDULER_RUNNING) &&
31.         stm32_crypto_dma_addressable(g_gcm_dma_input, sizeof(g_gcm_dma_input)) &&
32.         stm32_crypto_dma_addressable(g_gcm_dma_output, sizeof(g_gcm_dma_output)))
33.     {
34.         status = gcm_dma_payload(ctx->mode, input, output, dma_length);
35.     }
36.     else
37.     {
38.         dma_length = 0U;
39.         status = HAL_OK;
40.     }
41.     /* HAL's polling implementation handles partial blocks and silicon workarounds. */
42.     if ((status == HAL_OK) && (dma_length < length))
43.     {
44.         status = (ctx->mode == MBEDTLS_GCM_ENCRYPT) ?
45.              HAL_CRYP_Encrypt(&hcryp, (uint32_t *)(input + dma_length),
46.                               (uint16_t)(length - dma_length),
47.                               (uint32_t *)(output + dma_length), HAL_MAX_DELAY) :
48.              HAL_CRYP_Decrypt(&hcryp, (uint32_t *)(input + dma_length),
49.                               (uint16_t)(length - dma_length),
50.                               (uint32_t *)(output + dma_length), HAL_MAX_DELAY);
51.     }
52.     if (status != HAL_OK)
53.     {
54.         gcm_abort(ctx);
55.         return MBEDTLS_ERR_GCM_HW_ACCEL_FAILED;
56.     }
57.  
58.     ctx->payload_length += length;
59.     if ((length % 16U) != 0U)
60.     {
61.         ctx->final_input_seen = 1U;
62.     }
63.     return 0;
64. }

Dla większych fragmentów danych wykorzystywana jest ścieżka DMA. Minimalna długość danych wynosi 256 bajtów. DMA korzysta z fragmentów do 1024 bajtów. Poprawne przetworzenie danych zwiększa całkowitą długość danych o przetworzony blok.

Transfer danych do DMA wykonywany jest przez funkcję gcm_dma_transfer(). 

 

1. static HAL_StatusTypeDef gcm_dma_transfer(int mode, const unsigned char *input,
2.                                          unsigned char *output, uint16_t length,
3.                                          size_t output_cache_length)
4. {
5.     HAL_StatusTypeDef status;
6.     uint32_t start;
7.  
8.     if (g_gcm_dma_semaphore == NULL)
9.     {
10.         g_gcm_dma_semaphore = xSemaphoreCreateBinaryStatic(&g_gcm_dma_semaphore_storage);
11.     }
12.     (void)xSemaphoreTake(g_gcm_dma_semaphore, 0);
13.     stm32_crypto_dma_clean(input, length);
14.     stm32_crypto_dma_clean(output, output_cache_length);
15.     g_gcm_dma_waiting = 1U;
16.     status = (mode == MBEDTLS_GCM_ENCRYPT) ?
17.              HAL_CRYP_Encrypt_DMA(&hcryp, (uint32_t *)input, length, (uint32_t *)output) :
18.              HAL_CRYP_Decrypt_DMA(&hcryp, (uint32_t *)input, length, (uint32_t *)output);
19.     if ((status == HAL_OK) &&
20.         (xSemaphoreTake(g_gcm_dma_semaphore,
21.                         pdMS_TO_TICKS(STM32_CRYPTO_DMA_TIMEOUT_MS)) != pdTRUE))
22.     {
23.         status = HAL_TIMEOUT;
24.     }
25.     start = HAL_GetTick();
26.  
27.     while ((status == HAL_OK) && (HAL_CRYP_GetError(&hcryp) == HAL_CRYP_ERROR_NONE) &&
28.            ((HAL_CRYP_GetState(&hcryp) == HAL_CRYP_STATE_BUSY) ||
29.             (HAL_DMA_GetState(hcryp.hdmain) == HAL_DMA_STATE_BUSY) ||
30.             (HAL_DMA_GetState(hcryp.hdmaout) == HAL_DMA_STATE_BUSY)))
31.     {
32.         if ((HAL_GetTick() - start) >= STM32_CRYPTO_DMA_TIMEOUT_MS)
33.         {
34.             status = HAL_TIMEOUT;
35.             break;
36.         }
37.         taskYIELD();
38.     }
39.     g_gcm_dma_waiting = 0U;
40.     if ((status != HAL_OK) || (HAL_CRYP_GetError(&hcryp) != HAL_CRYP_ERROR_NONE))
41.     {
42.         CLEAR_BIT(hcryp.Instance->DMACR, CRYP_DMACR_DIEN | CRYP_DMACR_DOEN);
43.         __HAL_CRYP_DISABLE(&hcryp);
44.         (void)HAL_DMA_Abort(hcryp.hdmain);
45.         (void)HAL_DMA_Abort(hcryp.hdmaout);
46.         hcryp.State = HAL_CRYP_STATE_READY;
47.         __HAL_UNLOCK(&hcryp);
48.         if (status == HAL_OK) status = HAL_ERROR;
49.     }
50.     stm32_crypto_dma_invalidate(output, output_cache_length);
51.     return status;
52. }

Przed rozpoczęciem DMA czyszczony jest D-Cache. Po zakończeniu transferu bufor wynikowy jest niszczony. Ta operacja jest konieczna ponieważ bez odpowiedniej obsługi cache DMA mógłby zapisać nowe dane do pamięci RAM. Natomiast procesor dalej korzystałby ze starej kopii, która została umieszczona w D-Cache. 

Jeśli bufor wejściowy lub wyjściowy nie spełnia wymagań dostępności dla DMA czy wyrównania dane zostają skopiowane do buforów pomocniczych. Zostają przeniesione do sekcji .crypto_dma_buffers. Gdzie następuje ich wyrównanie do 32 bajtów. 

Jak już cała wiadomość jest przetworzona. to przechodzimy do generowania taga uwierzytelniającego. 

1. int mbedtls_gcm_finish(mbedtls_gcm_context *ctx, unsigned char *tag, size_t tag_len)
2. {
3.     uint32_t tag_words[4] = { 0U };
4.     unsigned char tag_bytes[16];
5.     size_t payload_length;
6.     int mode;
7.     HAL_StatusTypeDef status;
8.  
9.     if ((ctx == NULL) || (ctx->active == 0U))
10.     {
11.         return MBEDTLS_ERR_GCM_BAD_INPUT;
12.     }
13.     if ((tag == NULL) || (tag_len < 4U) || (tag_len > sizeof(tag_bytes)))
14.     {
15.         gcm_abort(ctx);
16.         return MBEDTLS_ERR_GCM_BAD_INPUT;
17.     }
18.  
19.     status = HAL_CRYPEx_AESGCM_GenerateAuthTAG(&hcryp, tag_words, HAL_MAX_DELAY);
20.     if (status == HAL_OK)
21.     {
22.         gcm_tag_to_bytes(tag_bytes, tag_words);
23.         memcpy(tag, tag_bytes, tag_len);
24.     }
25.     payload_length = ctx->payload_length;
26.     mode = ctx->mode;
27.     gcm_abort(ctx);
28.     GCM_TRACE("[GCMHW] finish id=%lu mode=%s payload=%lu status=%d\r\n",
29.            (unsigned long)ctx->trace_id,
30.            (mode == MBEDTLS_GCM_ENCRYPT) ? "enc" : "dec",
31.            (unsigned long)payload_length, (int)status);
32.     mbedtls_platform_zeroize(tag_bytes, sizeof(tag_bytes));
33.     return (status == HAL_OK) ? 0 : MBEDTLS_ERR_GCM_HW_ACCEL_FAILED;
34. }

Funkcja HAL_CRYPex_AESGCM_GenerateAuthTAG(..) generuje tag uwierzytelniający. Jak już tag jest gotowy to następuje jego konwersja do postaci bajtowej. 

MbedTLS wykonuje cały powyższy proces przez funkcje mbedtls_gmc_crypt_and_tag(). 

Blok CRYP wykonuje znacznie więcej operacji dla AES-GCM niż dla AES-ECB czy AES-CBC. Sprzęt odpowiada za szyfrowanie danych w trybie GCM oraz za operacje związane z wyznaczeniem wartości uwierzytelniającej. 

Sprzętowa realizacja SHA-224 oraz SHA-256:

Teraz przechodzimy do bloku HASH. Obsługuje on w projekcie SHA-224 oraz SHA-256. 

Skupimy się tutaj tylko na jednym z nich czyli SHA-256. Najważniejsze funkcje to mbedtls_sha256_starts_ret(), mbedtls_sha256_update_ret(), mbedtls_sha256_finish_ret(). Należy także pamiętać o mechanizmie zapisywania i odtwarzania sanu sprzętowego HASH. Moduł ten może być współdzielony przez kilka kontekstów mbedTLS. 

Obliczenia są rozpoczynane od funkcji mbedtls_sha256_starts_ret:

1. int mbedtls_sha256_starts_ret(mbedtls_sha256_context *ctx, int is224)
2. {
3.     if (ctx == NULL)
4.     {
5.         return MBEDTLS_ERR_SHA256_BAD_INPUT_DATA;
6.     }
7.  
8.     memset(ctx, 0, sizeof(*ctx));
9.     ctx->is224 = is224 ? 1 : 0;
10.     return 0;
11. }

W niej następuje zerowanie kontekstu oraz określenie który z algorytmów zostanie użyty. 

Jak już wspomniałem istotne jest współdzielenie modułu. Tutaj z pomocą przychodzi następująca funkcja:

1. static HAL_StatusTypeDef sha256_alt_prepare(mbedtls_sha256_context *ctx)
2. {
3.     hhash.Init.DataType = HASH_DATATYPE_8B;
4.     if (HAL_HASH_Init(&hhash) != HAL_OK)
5.     {
6.         return HAL_ERROR;
7.     }
8.  
9.     if (ctx->hw_started != 0U)
10.     {
11.         HAL_HASH_ContextRestoring(&hhash, (const uint8_t *)ctx->hw_context);
12.         hhash.Phase = HAL_HASH_PHASE_PROCESS;
13.         hhash.State = HAL_HASH_STATE_READY;
14.         hhash.Status = HAL_OK;
15.         hhash.Accumulation = 1U;
16.     }
17.  
18.     return HAL_OK;
19. }

Wykonywana jest przed każdym rozpoczęciem operacji. Jeśli dany kontekst był już używany to odtwarzamy jego poprzedni stan. Po przetworzeniu kolejnej partii danych stan sprzętowego mudułu jest zapisywany:

1. static void sha256_alt_save(mbedtls_sha256_context *ctx)
2. {
3.     HAL_HASH_ContextSaving(&hhash, (const uint8_t *)ctx->hw_context);
4.     ctx->hw_started = 1U;
5. }

Przy odtwarzaniu nie ma konieczności ponownego przeliczania danych dla przywróconego kontekstu. 

Najważniejszą funkcją wykorzystywaną przy przetwarzaniu danych jest update_ret:

1. int mbedtls_sha256_update_ret(mbedtls_sha256_context *ctx,
2.                               const unsigned char *input,
3.                               size_t ilen)
4. {
5.     unsigned char block[4];
6.     size_t aligned_length;
7.     size_t offset = 0U;
8.     int ret;
9.  
10.     if ((ctx == NULL) || ((ilen > 0U) && (input == NULL)))
11.     {
12.         return MBEDTLS_ERR_SHA256_BAD_INPUT_DATA;
13.     }
14.  
15.     if (ctx->tail_length != 0U)
16.     {
17.         size_t needed = 4U - ctx->tail_length;
18.  
19.         if (ilen < needed)
20.         {
21.             memcpy(ctx->tail + ctx->tail_length, input, ilen);
22.             ctx->tail_length += (uint8_t)ilen;
23.             return 0;
24.         }
25.  
26.         memcpy(block, ctx->tail, ctx->tail_length);
27.         memcpy(block + ctx->tail_length, input, needed);
28.         ret = (sha256_alt_accumulate(ctx, block, sizeof(block)) == HAL_OK) ?
29.               0 : MBEDTLS_ERR_SHA256_HW_ACCEL_FAILED;
30.         if (ret != 0)
31.         {
32.             return ret;
33.         }
34.  
35.         ctx->tail_length = 0U;
36.         offset = needed;
37.     }
38.  
39.     aligned_length = (ilen - offset) & ~(size_t)0x3U;
40.     if (aligned_length != 0U)
41.     {
42.         if (aligned_length > UINT32_MAX)
43.         {
44.             return MBEDTLS_ERR_SHA256_BAD_INPUT_DATA;
45.         }
46.  
47.         ret = (sha256_alt_accumulate(ctx, input + offset,
48.                                      (uint32_t)aligned_length) == HAL_OK) ?
49.               0 : MBEDTLS_ERR_SHA256_HW_ACCEL_FAILED;
50.         if (ret != 0)
51.         {
52.             return ret;
53.         }
54.  
55.         offset += aligned_length;
56.     }
57.  
58.     if (offset < ilen)
59.     {
60.         ctx->tail_length = (uint8_t)(ilen - offset);
61.         memcpy(ctx->tail, input + offset, ctx->tail_length);
62.     }
63.  
64.     return 0;
65. }

Funkcja przekazuje dane strumieniowo. Nie musi on być trzymany w jednym buforze. Do bloku HASH przekazywane są dane po 32 bity. Pozostałe 1-3 bajty są przechowywane w tail. 

Funkcja korzysta z sha256_alt_accumulate, która przekazuje dane do HASH:

1. static HAL_StatusTypeDef sha256_alt_accumulate(mbedtls_sha256_context *ctx,
2.                                                 const unsigned char *input,
3.                                                 uint32_t length)
4. {
5.     HAL_StatusTypeDef status;
6.  
7.     if (length == 0U)
8.     {
9.         return HAL_OK;
10.     }
11.  
12.     sha256_alt_lock();
13.     if (sha256_alt_prepare(ctx) != HAL_OK)
14.     {
15.         sha256_alt_unlock();
16.         return HAL_ERROR;
17.     }
18.  
19.     if (ctx->is224 != 0)
20.     {
21.         status = HAL_HASHEx_SHA224_Accmlt(&hhash, input, length);
22.     }
23.     else
24.     {
25.         status = HAL_HASHEx_SHA256_Accmlt(&hhash, input, length);
26.     }
27.  
28.     if (status == HAL_OK)
29.     {
30.         status = sha256_alt_wait_idle();
31.     }
32.     if (status == HAL_OK)
33.     {
34.         sha256_alt_save(ctx);
35.     }
36.     sha256_alt_unlock();
37.  
38.     return status;
39. }

SHA-224 wykorzystuje funkcje HAL_HASHEx_SHA224_Accmlt. SHA-256 korzysta z HAL_HASHEx_SHA256_Accnkt(). Funkcja może przetworzyć kolejny fragment wiadomości bez kończenia całej operacji SHA. Aktualny stan sprzętowego HASH jest zapisywany.

Obliczenia są kończone przez funkcję mbedtls_sha256_finish_ret:

1. int mbedtls_sha256_finish_ret(mbedtls_sha256_context *ctx,
2.                               unsigned char output[32])
3. {
4.     static const unsigned char zero_byte[1] = { 0U };
5.  
6.     const unsigned char *tail;
7.     HAL_StatusTypeDef status;
8.  
9.     if ((ctx == NULL) || (output == NULL))
10.     {
11.         return MBEDTLS_ERR_SHA256_BAD_INPUT_DATA;
12.     }
13.  
14.     tail = (ctx->tail_length != 0U) ? ctx->tail : zero_byte;
15.  
16.     sha256_alt_lock();
17.  
18.     status = sha256_alt_finish(
19.         ctx,
20.         tail,
21.         ctx->tail_length,
22.         output);
23.  
24.     sha256_alt_unlock();
25.  
26.     if (status != HAL_OK)
27.     {
28.         return MBEDTLS_ERR_SHA256_HW_ACCEL_FAILED;
29.     }
30.  
31.     ctx->tail_length = 0U;
32.     ctx->hw_started = 0U;
33.  
34.     return 0;
35. }

Powyższa funkcja przekazuje ostatnie bajty danych po czym kończy obliczenia. Powyższa funkcja wywołuje funkcję pomocniczą sha256_alt_finish:

1. static HAL_StatusTypeDef sha256_alt_finish(mbedtls_sha256_context *ctx,
2.                                             const unsigned char *input,
3.                                             uint32_t length,
4.                                             unsigned char output[32])
5. {
6.     HAL_StatusTypeDef status;
7.  
8.     if (sha256_alt_prepare(ctx) != HAL_OK) {
9.         return HAL_ERROR;
10.     }
11.  
12.     if (ctx->is224 != 0) {
13.         status = HAL_HASHEx_SHA224_Accmlt_End(&hhash, input, length, output, HAL_MAX_DELAY);
14.     } else {
15.         status = HAL_HASHEx_SHA256_Accmlt_End(&hhash, input, length, output, HAL_MAX_DELAY);
16.     }
17.  
18.     return status;
19. }

Operacje kończone są przez funkcje z biblioteki HAL w zależności od rodzaju wybranej biblioteki. Wynik operacji jest przekazywany do output. Dla SHA-256 długość wynosi 32 bajty. W przypadku SHA-224 wykorzystywane jest pierwsze 28 bajtów wyniku. 

Najważniejszą częścią tej implementacji jest możliwość strumieniowego przekazywania danych wraz z zapisem stanu sprzętowego HASH pomiędzy wywołaniami. 

Synchronizacja dostępu do CRYP i HASH:

Sprzętowe moduły kryptograficzne są pojedynczymi peryferiami sprzętowymi. Biblioteka mbedTLS może być wykorzystywana przez kilka zadań systemowych np. HTTPS czy klient TLS. 

Przeskakiwanie pomiędzy wywołaniami może jednocześnie zmieniać konfigurację tego samego peryferium. Może to doprowadzić do uszkodzenia kontekstu kryptograficznego bądź do otrzymania niepoprawnego wyniku. 

Z tego powodu dobrze jest zabezpieczać dostęp do bloków sprzętowych przez mutexy

W konfiguracji FreeRTOS została włączona obsługa mutexów rekurencyjnych (configUSE_RECURSIVE_MUTEXES). Tworzenie mutexu odbywa się w następujący sposób:

1. g_mbedTlsMutex = xSemaphoreCreateRecursiveMutex();

Przed rozpoczęciem operacji sprzętowej ustawiany jest ten mutex przez funkcje stm32_aes_lock. Jego zwolnienie obsługiwane jest przez funkcję stm32_aes_unlock:

1. static void stm32_aes_lock(void)
2. {
3.     if (g_mbedTlsMutex != NULL)
4.     {
5.         (void)xSemaphoreTakeRecursive(
6.             g_mbedTlsMutex,
7.             portMAX_DELAY);
8.     }
9. }
10.  
11. static void stm32_aes_unlock(void)
12. {
13.     if (g_mbedTlsMutex != NULL)
14.     {
15.         (void)xSemaphoreGiveRecursive(
16.             g_mbedTlsMutex);
17.     }
18. }

Operacje są podobne dla modułu HASH. 

Jeśli jakieś zadanie w tym samym czasie chce skorzystać z tego samego bloku, to musi poczekać na jego zwolnienie.

Wykorzystywanie mutexu rekurecyjnego jest tutaj szczególnie istotne. Funckja wyższego poziomu może mieć już założoną blokadę. Chce następie wywołać kolejną funkcję, która również potrzebuje dostępu do tego samego mutexu. Zwykły mutex mógłby tu wywołać zaklesczenie zadania. Mutex rekurencyjny pozwala temu samemu zadaniu wielokrotnie przejąć tę samą blokadę. Oczywiście musi ją później zwolnić. 

Dzięki takim operacjom moduły CRYP oraz HASH mogą być wielokrotnie współdzielone przez kilka operacji kryptograficznych.

Zakończenie:

Przedstawiona implementacja wykorzystuje sprzętowe bloku kryptograficzne. Pozwala to znacząco przyśpieszyć wybrane operacje wykonywane przez bibliotekę mbedTLS. 

Blok CRYP realizuje operacje AES w trybach ECB, CBC oraz GCM. W przypadku CBC możliwe jest przetwarzanie większych buforów oraz wykorzystanie DMA. GCM dodatkowo korzysta ze sprzętowej obsługi mechanizmu uwierzytelniania danych.

Blok HASH oblicza SHA-224 oraz SHA-256. Dane mogą być przekazane strumieniowo. Stan peryferium jest zapisywany i odtwarzany pomiędzy kolejnymi operacjami. 

Największą zaletą takiej integracji jest zachowanie standardowego interfejsu biblioteki. 

Zastosowanie sprzętowych peryferiów dostępny w STM32H735 pozwala na odciążenie rdzenia Cortex-M7.