Format przewodu Tink

Na tej stronie opisano format przesyłania kluczy i danych wyjściowych w Tink. Dokumentacja jest przeznaczona dla kryptografów, którzy chcą dodać do Tink dodatkowe języki, oraz dla osób zarządzających innymi bibliotekami kryptograficznymi wysokiego poziomu, które chcą mieć tryb zgodny z protokołem. Nie jest przeznaczona dla ogółu odbiorców.

Serializacja zbioru kluczy

Tink używa Google protobuf do serializacji zestawów kluczy.

  • Binarnie serializowany zestaw kluczy to serializowany proto zestawu kluczy zdefiniowany w pliku tink.proto. Właściwość KeyData wartości klucza to serializowany protokół odpowiedniego typu klucza.
  • Zserializowany w formacie JSON zestaw kluczy to protokół Keyset zserializowany w formacie JSON. Pamiętaj, że wartość KeyData to nadal binarny serializowany protokół.
  • Zaszyfrowany zbiór kluczy to serializowany protokół EncryptedKeyset zdefiniowany w pliku tink.proto. Zawiera zaszyfrowany binarny serializowany zestaw kluczy i opcjonalnie metadane KeysetInfo bez szyfrowania.

Prefiks wyjściowy Tink

Większość typów pierwotnych Tink obsługuje 5-bajtowy prefiks danych wyjściowych składający się z:

  • Wersja 1-bajtowa: 0x01
  • 4-bajtowa wskazówka dotycząca klucza: identyfikator użytego klucza.

Niektóre starsze klucze mogą też obsługiwać bajt wersji 0x00.

Pamiętaj, że ten prefiks nie jest uwierzytelniony i nie można na nim polegać w kwestiach bezpieczeństwa. Tink używa go jako wskazówki, aby przyspieszyć odszyfrowywanie lub weryfikację.

AEAD

Ogólnie rzecz biorąc, Tink formatuje teksty zaszyfrowane AEAD w ten sposób:

prefix || IV || ciphertext || tag

o ile w odpowiednim dokumencie RFC nie określono inaczej. prefix jest puste lub zawiera 5-bajtowy prefiks danych wyjściowych Tink.

AES-CTR-HMAC

W przypadku AES-CTR-HMAC Tink oblicza kod MAC z danymi powiązanymi (AD) w ten sposób:

AD || IV || ciphertext || bitlen(AD)

gdzie bitlen(AD) to długość AD w bitach przedstawiona jako 64-bitowa liczba całkowita bez znaku w formacie big-endian. Ten schemat HMAC jest zgodny z projektem algorytmu AES-CBC-HMAC autorstwa McGrew.

Deterministyczne AEAD

Tink implementuje RFC 5297 dla AES-SIV, umieszczając syntetyczny wektor inicjujący (SIV) na początku tekstu zaszyfrowanego. Typ podstawowy może dodać 5-bajtowy prefiks danych wyjściowych Tink.

Chociaż RFC 5297 obsługuje listę powiązanych danych, Tink obsługuje tylko dokładnie 1 powiązany element danych, który w RFC 5297 odpowiada liście z 1 elementem. Puste powiązane dane to lista z jednym pustym elementem, a nie pusta lista.

Strumieniowe AEAD

Zobacz AES-CTR HMAC i AES-GCM-HKDF.

Szyfrowanie kopertowe

Szyfrowanie kopertowe szyfruje dane za pomocą klucza szyfrującego dane DEK przy użyciu podstawowych elementów AEAD Tink. Szyfrowanie działa w ten sposób:

  • Generowany jest nowy DEK przy użyciu danego szablonu klucza (lub parametrów klucza).
  • Pole DEK jest serializowane do postaci ciągu bajtów. Format serializacji serializacji bufora protokołu typu klucza proto. Na przykład jest to zserializowana AesGcmKey wiadomość bufora protokołu zdefiniowana w pliku aes_gcm.proto dla klucza DEK typu AES GCM. Informacje o serializacji bufora protokołu znajdziesz w artykule Serializacja bufora protokołu.
  • Zserializowany obiekt DEK jest szyfrowany przez zewnętrznego dostawcę (np. GCP) i przekształcany w obiekt encrypted DEK.
  • DEK służy do szyfrowania tekstu jawnego za pomocą powiązanych danych w ciphertext. W związku z tym ciphertext ma dokładnie taki sam format jak podstawowa operacja AEAD odpowiadająca DEK.

Format wyjściowy szyfrowania kopertowego jest następujący:

encrypted DEK length || encrypted DEK || ciphertext

Pole encrypted DEK length ma 4 bajty i przechowuje długość pola encrypted DEK jako 32-bitową liczbę całkowitą w formacie big-endian.

MAC

Tink postępuje zgodnie z odpowiednimi RFC. Typy pierwotne mogą dodawać do tagu 5-bajtowy prefiks wyjściowy Tink.

Zbiór PRF

Tink postępuje zgodnie z odpowiednimi RFC. Pamiętaj, że w przypadku funkcji PRF typ klucza różni się od typu klucza MAC tego samego algorytmu, ponieważ nie zawiera długości danych wyjściowych. Klucze PRF Set nigdy nie dodają prefiksu wyjściowego Tink. Dzięki temu dane wyjściowe będą rzeczywiście funkcją PRF.

Szyfrowanie hybrydowe

Ogólny format transmisji w przypadku szyfrowania hybrydowego Tink jest następujący:

prefix || encapsulated_key || encrypted_data

prefix jest puste lub zawiera 5-bajtowy prefiks danych wyjściowych Tink. Każdy typ klucza zawiera informacje o tym, ile bajtów należy przeanalizować i jak to zrobić w przypadku encapsulated_key.

HPKE (Hybrid Public Key Encryption)

Tink jest zgodny ze standardem HPKE zdefiniowanym w RFC 9180. Zestaw szyfrów HPKE obejmuje te 3 podstawowe elementy:

  • Mechanizm hermetyzacji klucza (KEM)
  • Funkcja derywacji klucza (KDF)
  • Szyfrowanie uwierzytelnione z danymi powiązanymi (AEAD)

Standard HPKE nie definiuje ogólnego formatu transmisji w sekcji 10 dokumentu RFC 9180. Implementacja HPKE w Tinku używa tych wartościencapsulated_key i encrypted_data.

  • encapsulated_key
    • Zserializowany klucz publiczny nadawcy
    • Zdefiniowane jako enc w dokumencie RFC 9180, sekcja 4.1
    • Format zależy od konkretnego algorytmu HPKE KEM.
  • encrypted_data
    • tekst szyfrowany i tag (np. ciphertext || tag bez IV)
    • Zdefiniowane jako ct w RFC 9180, sekcja 4
    • Format zależy od użytego konkretnego algorytmu HPKE AEAD.
KEM oparty na protokole Diffiego-Hellmana X25519

W przypadku algorytmów DHKEM X25519 wartość enc to 32-bajtowy publiczny klucz Diffiego-Hellmana nadawcy.

ECIES-AEAD-HKDF

W przypadku implementacji ECIES-AEAD-HKDF w Tink encapsulated_key to dane wyjściowe mechanizmu hermetyzacji kluczy (KEM), a encrypted_data to dane wyjściowe mechanizmu hermetyzacji danych (DEM).

KEM

W zależności od typu klucza Tink używa skompresowanych i nieskompresowanych punktów krzywej eliptycznej zgodnie ze standardami kodowania RFC 8422/ANSI.X9-62.2005. W przypadku nieskompresowanych punktów po bajcie 0x04 następuje współrzędna x i y jako liczby całkowite o stałym rozmiarze. W przypadku skompresowanych współrzędnych używany jest bajt 0x02 lub 0x03 oraz współrzędna x jako liczba całkowita o stałym rozmiarze. W przypadku X25519, używana jest definicja z dokumentu RFC 7748 (współrzędna x jako liczba całkowita o stałym rozmiarze).

DEM

W przypadku encrypted_data Tink używa tego samego formatu co AEAD. Obejmuje to określenie wektora inicjującego.

Derywacja klucza

Najpierw obliczana jest współrzędna X x_ss udostępnionego punktu. Klucz do AEAD jest następnie ustawiany na:

HKDF(ikm = encapsulated_key || x_ss, salt = salt_of_key, info = context_info, length = dem_key_size)

gdzie encapsulated_key to pełne dane wyjściowe KEM w bajtach.

Podpisy cyfrowe

Tink postępuje zgodnie z odpowiednimi RFC. Typy proste mogą dodawać do wygenerowanego tagu 5-bajtowy prefiks wyjściowy Tink.

ECDSA

W zależności od pola EcdsaSignatureEncoding w kluczu format podpisu ECDSA to IEEE P1363 lub ASN.1 DER.

Format podpisu IEEE P1363 to r || s, gdzie r i s są dopełnione zerami i mają ten sam rozmiar w bajtach co rząd krzywej. Na przykład w przypadku krzywej NIST P-256 wartości r i s są uzupełniane zerami do 32 bajtów.

Podpis DER jest kodowany przy użyciu ASN.1:

ECDSA-Sig-Value :: = SEQUENCE { r INTEGER, s INTEGER }

W szczególności kodowanie to:

0x30 || totalLength || 0x02 || r's length || r || 0x02 || s's length || s

Tink stosuje sprawdzone metody weryfikacji podpisu, akceptując tylko podpisy ECDSA z kodowaniem DER (alternatywne podpisy z kodowaniem BER są nieprawidłowe).

Pomaga to zapobiegać atakom polegającym na modyfikowaniu podpisu, które często wpływają na systemy kryptowalut.

Wartości prehash ML-DSA z zewnętrzną wartością mu

Funkcja Prehash przekształca wiadomość w wartość prehash, którą następnie podpisuje funkcja SignPrehash. W przypadku ML-DSA w trybie External Mu, zgodnie z opisem w RFC 9881, wartość prehash ma 69 bajtów i ten układ:

0xff || key_id (4 bytes, big-endian) || mu (64 bytes)
  • mu to reprezentacja wiadomości ML-DSA obliczona jako SHAKE256(tr || 0x00 || 0x00 || message, 64), gdzie tr to 64-bajtowy skrót klucza publicznego, pierwszy znak 0x00 to separator domeny FIPS 204 dla czystego ML-DSA, a drugi znak 0x00 to długość (pustego) ciągu kontekstowego. Ponieważ tr jest wyprowadzany z klucza publicznego, mu jest kryptograficznie powiązany z tym kluczem, chociaż sprawdzenie powiązania wymaga oryginalnej wiadomości.
  • 5-bajtowy prefiks to ramka Tink, która nie jest częścią mu. Powiązuje wartość wstępnego haszowania z określonym kluczem, dzięki czemu funkcja SignPrehash wie, którego klucza użyć do podpisania, i może odrzucić wartość wstępnego haszowania, dla której nie ma klucza. Prefiks to zwykłe metadane, które nie są powiązane z niczym kryptograficznie: każdy może je zmienić.

Podpisywanie odrzuca wszystkie dane wejściowe, które nie mają dokładnie 69 bajtów, nie zaczynają się od 0xff lub których identyfikator klucza nie pasuje do włączonego klucza w zestawie kluczy.