1 /* 2 * Copyright (c) 2019, Texas Instruments Incorporated 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 9 * * Redistributions of source code must retain the above copyright 10 * notice, this list of conditions and the following disclaimer. 11 * 12 * * Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * 16 * * Neither the name of Texas Instruments Incorporated nor the names of 17 * its contributors may be used to endorse or promote products derived 18 * from this software without specific prior written permission. 19 * 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 */ 32 /** ============================================================================ 33 * @file CryptoUtils.h 34 * 35 * @brief A collection of utility functions for cryptographic purposes 36 * 37 */ 38 39 #ifndef ti_drivers_cryptoutils_utils_CryptoUtils__include 40 #define ti_drivers_cryptoutils_utils_CryptoUtils__include 41 42 #include <stdint.h> 43 #include <stdbool.h> 44 #include <string.h> 45 46 47 #ifdef __cplusplus 48 extern "C" { 49 #endif 50 51 /** 52 * @brief Compares two buffers for equality without branching 53 * 54 * @note This is not a drop-in replacement for memcmp! 55 * 56 * Most memcmp implementations break out of their comparison loop immediately 57 * once a mismatch is detected to save execution time. For cryptographic 58 * purposes, this is a flaw. 59 * 60 * This function compares two buffers without branching thus requiring a 61 * an amount of time that does not vary with the content of @c buffer0 and 62 * @c buffer1. 63 * 64 * @param buffer0 Buffer to compare against @c buffer1. 65 * @param buffer1 Buffer tp compare against @c buffer0 66 * @param bufferByteLength Length in bytes of @c buffer0 and @c buffer1. 67 * @retval true The contents of the buffers match. 68 * @retval false The contents of the buffers do not match. 69 */ 70 bool CryptoUtils_buffersMatch(const void *buffer0, 71 const void *buffer1, 72 size_t bufferByteLength); 73 74 /** 75 * @brief Compares two buffers for equality word-by-word without branching 76 * 77 * @note This is not a drop-in replacement for memcmp! 78 * 79 * Most memcmp implementations break out of their comparison loop immediately 80 * once a mismatch is detected to save execution time. For cryptographic 81 * purposes, this is a flaw. 82 * 83 * This function compares two buffers without branching thus requiring a 84 * an amount of time that does not vary with the content of @c buffer0 and 85 * @c buffer1. 86 * 87 * Unlike #CryptoUtils_buffersMatch(), this function expects @c buffer0 and 88 * @c buffer1 to be 32-bit aligned. It will only perform 32-bit aligned 89 * accesses to memory. This is needed to access the registers of certain 90 * peripherals. 91 * 92 * @param buffer0 Buffer to compare against @c buffer1. 93 * @param buffer1 Buffer tp compare against @c buffer0 94 * @param bufferByteLength Length in bytes of @c buffer0 and @c buffer1. 95 * Must be evenly divisible by sizeof(uint32_t). 96 * This function will return false if @c 97 * bufferByteLength is not evenly divisible by 98 * sizeof(uin32_t). 99 * @retval true The contents of the buffers match. 100 * @retval false The contents of the buffers do not match. 101 */ 102 bool CryptoUtils_buffersMatchWordAligned(const uint32_t *buffer0, 103 const uint32_t *buffer1, 104 size_t bufferByteLength); 105 106 /** 107 * @brief Reverses the byte order in a buffer of a given length 108 * 109 * The left-most byte will become the right-most byte and vice versa. 110 * 111 * @param buffer Buffer containing the data to be reversed. 112 * @param bufferByteLength Length in bytes of @c buffer. 113 */ 114 void CryptoUtils_reverseBufferBytewise(void * buffer, size_t bufferByteLength); 115 116 /** 117 * @brief Reverses, copies, and pads an array of words. 118 * 119 * The \c source array is reversed byte-wise and copied into the \c destination 120 * array. Writes are done word-wise. If \c sourceLength is not a multiple of 4, 121 * any remaining bytes up to the next word boundary are padded with 0. 122 * 123 * The length of the destination array must be a multiple of 4, rounded up to the 124 * padded \c sourceLength if required. 125 * 126 * @param source Source array 127 * 128 * @param destination Destination array 129 * 130 * @param sourceLength Length of the source array (multiple of 4) 131 */ 132 void CryptoUtils_reverseCopyPad(const void *source, 133 void *destination, 134 size_t sourceLength); 135 136 #ifdef __cplusplus 137 } 138 #endif 139 140 #endif /* ti_drivers_cryptoutils_utils_CryptoUtils__include */ 141
