1 /* 2 * Copyright 2022 Google LLC 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 // C API for Rust implementation of LDT [1], tailored to Nearby Presence's 18 // BLE 4.2 legacy format advertisement parsing use case. 19 // 20 // [1] https://eprint.iacr.org/2017/841.pdf 21 22 #ifndef NP_LDT_H_ 23 #define NP_LDT_H_ 24 25 #ifdef __cplusplus 26 extern "C" { 27 #endif 28 29 #include <stddef.h> 30 #include <stdint.h> 31 32 // Individual encrypt/decrypt API, useful when creating advertisements or when 33 // decrypting advertisements from a known origin 34 35 // Key material from the Nearby Presence credential from which keys will be 36 // derived. 37 typedef struct { 38 uint8_t bytes[32]; 39 } NpLdtKeySeed; 40 41 // The calculated hmac key used for verifying successful decryption of 42 // credential metadata 43 typedef struct{ 44 uint8_t bytes[32]; 45 } NpMetadataKeyHmac; 46 47 // The big-endian 2 byte salt which will be incorporated into the tweaks LDT 48 // uses while encrypting. 49 typedef struct { 50 uint8_t bytes[2]; 51 } NpLdtSalt; 52 53 // The allocated handle to use for encryption 54 typedef struct { 55 uint64_t handle; 56 } NpLdtEncryptHandle; 57 58 // The allocated handle to use for decryption 59 typedef struct { 60 uint64_t handle; 61 } NpLdtDecryptHandle; 62 63 // Possible result codes returned from the LDT NP APIs 64 typedef enum { 65 // Call to api was successful 66 NP_LDT_SUCCESS = 0, 67 // Payload of invalid length was provided must be >= 16 and <=31 bytes 68 NP_LDT_ERROR_INVALID_LENGTH = -1, 69 // The provided metadata hmac did not match the calculated hmac on call to decrypt and verify 70 NP_LDT_ERROR_MAC_MISMATCH = -2, 71 // the provided handle did match one created by NpLdtCreate 72 NP_LDT_INVALID_HANDLE = -3 73 } NP_LDT_RESULT; 74 75 // Allocate an LDT-XTS-AES128 Decryption cipher using the "swap" mix function. 76 // 77 // `key_seed` is the key material from the Nearby Presence credential from which 78 // the LDT key will be derived. 79 // 'hmac_tag' is the hmac auth tag calculated on the metadata key used to verify 80 // decryption was successful 81 // 82 // Returns 0 on error, or a non-zero handle on success. 83 NpLdtDecryptHandle NpLdtDecryptCreate(NpLdtKeySeed key_seed, NpMetadataKeyHmac hmac_tag); 84 85 // Allocate an LDT-XTS-AES128 Encryption cipher using the "swap" mix function. 86 // 87 // `key_seed` is the key material from the Nearby Presence credential from which 88 // the LDT key will be derived. 89 // 90 // Returns 0 on error, or a non-zero handle on success. 91 NpLdtEncryptHandle NpLdtEncryptCreate(NpLdtKeySeed key_seed); 92 93 // Release allocated resources for an NpLdtEncryptHandle 94 // 95 // Returns 0 on success or an NP_LDT_RESULT error code on failure 96 NP_LDT_RESULT NpLdtEncryptClose(NpLdtEncryptHandle handle); 97 98 // Release allocated resources for an NpLdtDecryptHandle 99 // 100 // Returns 0 on success or an NP_LDT_RESULT error code on failure 101 NP_LDT_RESULT NpLdtDecryptClose(NpLdtDecryptHandle handle); 102 103 // Encrypt a 16-31 byte buffer in-place. 104 // 105 // `buffer` is a pointer to a 16-31 byte plaintext, with length in `buffer_len`. 106 // `salt` is the big-endian 2 byte salt that will be used in the Nearby 107 // Presence advertisement, which will be incorporated into the tweaks LDT uses 108 // while encrypting. 109 // 110 // Returns 0 on success, in which case `buffer` will now contain ciphertext. 111 // Returns an NP_LDT_RESULT error code on failure 112 NP_LDT_RESULT NpLdtEncrypt(NpLdtEncryptHandle handle, uint8_t* buffer, size_t buffer_len, 113 NpLdtSalt salt); 114 115 // Decrypt a 16-31 byte buffer in-place and verify the plaintext metadata key matches 116 // this item's MAC, if not the buffer will not be decrypted 117 // 118 // `buffer` is a pointer to a 16-31 byte ciphertext, with length in 119 // `buffer_len`. 120 // `salt` is the big-endian 2 byte salt found in the Nearby Presence 121 // advertisement, which will be incorporated into the tweaks LDT uses while 122 // decrypting. 123 // 124 // Returns 0 on success, in which case `buffer` will now contain plaintext. 125 // Returns an NP_LDT_RESULT error code on failure 126 // - If the buffer has an invalid length 127 // - If the decrypted plaintext fails its HMAC validation 128 NP_LDT_RESULT NpLdtDecryptAndVerify(NpLdtDecryptHandle handle, uint8_t* buffer, size_t buffer_len, 129 NpLdtSalt salt); 130 131 #ifdef __cplusplus 132 } // extern "C" 133 #endif 134 135 #endif // NP_LDT_H_