aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--lib/include/tinycrypt/ctr_prng.h138
-rw-r--r--lib/source/ctr_prng.c141
-rw-r--r--tests/test_ctr_prng.c31
3 files changed, 275 insertions, 35 deletions
diff --git a/lib/include/tinycrypt/ctr_prng.h b/lib/include/tinycrypt/ctr_prng.h
index 17eb0a5..2d3f6f7 100644
--- a/lib/include/tinycrypt/ctr_prng.h
+++ b/lib/include/tinycrypt/ctr_prng.h
@@ -1,5 +1,61 @@
/* ctr_prng.h - TinyCrypt interface to an CTR-PRNG implementation */
+/*
+ * Copyright (c) 2016, Chris Morrison
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * * Redistributions of source code must retain the above copyright notice, this
+ * list of conditions and the following disclaimer.
+ *
+ * * Redistributions in binary form must reproduce the above copyright notice,
+ * this list of conditions and the following disclaimer in the documentation
+ * and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/**
+ * @file
+ * @brief Interface to an CTR-PRNG implementation.
+ *
+ * Overview: A pseudo-random number generator (PRNG) generates a sequence
+ * of numbers that have a distribution close to the one expected
+ * for a sequence of truly random numbers. The NIST Special
+ * Publication 800-90A specifies several mechanisms to generate
+ * sequences of pseudo random numbers, including the CTR-PRNG one
+ * which is based on AES. TinyCrypt implements CTR-PRNG with
+ * AES-128.
+ *
+ * Security: A cryptographically secure PRNG depends on the existence of an
+ * entropy source to provide a truly random seed as well as the
+ * security of the primitives used as the building blocks (AES-128
+ * in this instance).
+ *
+ * Requires: - AES-128
+ *
+ * Usage: 1) call tc_ctr_prng_init to seed the prng context
+ *
+ * 2) call tc_ctr_prng_reseed to mix in additional entropy into
+ * the prng context
+ *
+ * 3) call tc_ctr_prng_generate to output the pseudo-random data
+ *
+ * 4) call tc_ctr_prng_uninstantiate to zero out the prng context
+ */
+
#ifndef __TC_CTR_PRNG_H__
#define __TC_CTR_PRNG_H__
@@ -17,27 +73,91 @@ typedef struct
/* updated whenever the PRNG is reseeded */
struct tc_aes_key_sched_struct key;
- /* number of requests since initialisation/reseeding */
+ /* number of requests since initialization/reseeding */
uint64_t reseedCount;
} TCCtrPrng_t;
-//todo comment
+/**
+ * @brief CTR-PRNG initialization procedure
+ * Initializes prng context with entropy and personalization string (if any)
+ * @return returns TC_SUCCESS (1)
+ * returns TC_FAIL (0) if:
+ * ctx == NULL,
+ * entropy == NULL,
+ * entropyLen < (TC_AES_KEY_SIZE + TC_AES_BLOCK_SIZE)
+ * @note Only the first (TC_AES_KEY_SIZE + TC_AES_BLOCK_SIZE) bytes of
+ * both the entropy and personalization inputs are used -
+ * supplying additional bytes has no effect.
+ * @param ctx IN/OUT -- the PRNG context to initialize
+ * @param entropy IN -- entropy used to seed the PRNG
+ * @param entropyLen IN -- entropy length in bytes
+ * @param personalization IN -- personalization string used to seed the PRNG
+ * (may be null)
+ * @param plen IN -- personalization length in bytes
+ *
+ */
int32_t tc_ctr_prng_init(TCCtrPrng_t * const ctx,
- uint8_t const entropy[],
+ uint8_t const * const entropy,
uint32_t entropyLen,
- uint8_t const personalization[],
+ uint8_t const * const personalization,
uint32_t pLen);
-//todo comment
+/**
+ * @brief CTR-PRNG reseed procedure
+ * Mixes entropy and additional_input into the prng context
+ * @return returns TC_SUCCESS (1)
+ * returns TC_FAIL (0) if:
+ * ctx == NULL,
+ * entropy == NULL,
+ * entropylen < (TC_AES_KEY_SIZE + TC_AES_BLOCK_SIZE)
+ * @note It is better to reseed an existing prng context rather than
+ * re-initialise, so that any existing entropy in the context is
+ * presereved. This offers some protection against undetected failures
+ * of the entropy source.
+ * @note Assumes tc_ctr_prng_init has been called for ctx
+ * @param ctx IN/OUT -- the PRNG state
+ * @param entropy IN -- entropy to mix into the prng
+ * @param entropylen IN -- length of entropy in bytes
+ * @param additional_input IN -- additional input to the prng (may be null)
+ * @param additionallen IN -- additional input length in bytes
+ */
int32_t tc_ctr_prng_reseed(TCCtrPrng_t * const ctx,
- uint8_t const entropy[],
- uint32_t entropyLen);
+ uint8_t const * const entropy,
+ uint32_t entropyLen,
+ uint8_t const * const additional_input,
+ uint32_t additionallen);
-int32_t tc_ctr_prng_generate(TCCtrPrng_t * const ctx,
- uint8_t out[],
+/**
+ * @brief CTR-PRNG generate procedure
+ * Generates outlen pseudo-random bytes into out buffer, updates prng
+ * @return returns TC_SUCCESS (1)
+ * returns TC_RESEED_REQ (-1) if a reseed is needed
+ * returns TC_FAIL (0) if:
+ * ctx == NULL,
+ * out == NULL,
+ * outlen >= 2^16
+ * @note Assumes tc_ctr_prng_init has been called for ctx
+ * @param ctx IN/OUT -- the PRNG context
+ * @param additional_input IN -- additional input to the prng (may be null)
+ * @param additionallen IN -- additional input length in bytes
+ * @param out IN/OUT -- buffer to receive output
+ * @param outlen IN -- size of out buffer in bytes
+ */
+int32_t tc_ctr_prng_generate(TCCtrPrng_t * const ctx,
+ uint8_t const * const additional_input,
+ uint32_t additionallen,
+ uint8_t * const out,
uint32_t outlen);
+/**
+ * @brief CTR-PRNG uninstantiate procedure
+ * Zeroes the internal state of the supplied prng context
+ * @return none
+ * @param ctx IN/OUT -- the PRNG context
+ */
+void tc_ctr_prng_uninstantiate(TCCtrPrng_t * const ctx);
+
#ifdef __cplusplus
}
#endif
diff --git a/lib/source/ctr_prng.c b/lib/source/ctr_prng.c
index e2aa429..d52dc5d 100644
--- a/lib/source/ctr_prng.c
+++ b/lib/source/ctr_prng.c
@@ -1,10 +1,54 @@
/* ctr_prng.c - TinyCrypt implementation of CTR-PRNG */
+/*
+ * Copyright (c) 2016, Chris Morrison
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * * Redistributions of source code must retain the above copyright notice, this
+ * list of conditions and the following disclaimer.
+ *
+ * * Redistributions in binary form must reproduce the above copyright notice,
+ * this list of conditions and the following disclaimer in the documentation
+ * and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+
#include <tinycrypt/ctr_prng.h>
#include <tinycrypt/utils.h>
#include <string.h>
-//todo comment
+/*
+ * This PRNG is based on the CTR_DRBG described in Recommendation for Random
+ * Number Generation Using Deterministic Random Bit Generators,
+ * NIST SP 800-90A Rev. 1.
+ *
+ * Annotations to particular steps (e.g. 10.2.1.2 Step 1) refer to the steps
+ * described in that document.
+ *
+ */
+
+/**
+ * @brief Array incrementer
+ * Treats the supplied array as one contiguous number (MSB in arr[0]), and
+ * increments it by one
+ * @return none
+ * @param arr IN/OUT -- array to be incremented
+ * @param len IN -- size of arr in bytes
+ */
static void arrInc(uint8_t arr[], uint32_t len)
{
uint32_t i;
@@ -20,8 +64,16 @@ static void arrInc(uint8_t arr[], uint32_t len)
}
}
-//todo comment
-static void tc_ctr_prng_update(TCCtrPrng_t * const ctx, uint8_t const providedData[])
+/**
+ * @brief CTR PRNG update
+ * Updates the internal state of supplied the CTR PRNG context
+ * increments it by one
+ * @return none
+ * @note Assumes: providedData is (TC_AES_KEY_SIZE + TC_AES_BLOCK_SIZE) bytes long
+ * @param ctx IN/OUT -- CTR PRNG state
+ * @param providedData IN -- data used when updating the internal state
+ */
+static void tc_ctr_prng_update(TCCtrPrng_t * const ctx, uint8_t const * const providedData)
{
if (0 != ctx)
{
@@ -70,14 +122,14 @@ static void tc_ctr_prng_update(TCCtrPrng_t * const ctx, uint8_t const providedDa
}
int32_t tc_ctr_prng_init(TCCtrPrng_t * const ctx,
- uint8_t const entropy[],
+ uint8_t const * const entropy,
uint32_t entropyLen,
- uint8_t const personalization[],
+ uint8_t const * const personalization,
uint32_t pLen)
{
int32_t result = TC_FAIL;
uint32_t i;
- uint8_t persString[TC_AES_KEY_SIZE + TC_AES_BLOCK_SIZE] = {0U};
+ uint8_t personalization_buf[TC_AES_KEY_SIZE + TC_AES_BLOCK_SIZE] = {0U};
uint8_t seed_material[TC_AES_KEY_SIZE + TC_AES_BLOCK_SIZE];
uint8_t zeroArr[TC_AES_BLOCK_SIZE] = {0U};
@@ -85,22 +137,22 @@ int32_t tc_ctr_prng_init(TCCtrPrng_t * const ctx,
{
/* 10.2.1.3.1 step 1 */
uint32_t len = pLen;
- if (len > sizeof persString)
+ if (len > sizeof personalization_buf)
{
- len = sizeof persString;
+ len = sizeof personalization_buf;
}
/* 10.2.1.3.1 step 2 */
- memcpy(persString, personalization, len);
+ memcpy(personalization_buf, personalization, len);
}
- if ((0 != ctx) && (0 != entropy) && (entropyLen == sizeof seed_material))
+ if ((0 != ctx) && (0 != entropy) && (entropyLen >= sizeof seed_material))
{
/* 10.2.1.3.1 step 3 */
memcpy(seed_material, entropy, sizeof seed_material);
for (i = 0U; i < sizeof seed_material; i++)
{
- seed_material[i] ^= persString[i];
+ seed_material[i] ^= personalization_buf[i];
}
/* 10.2.1.3.1 step 4 */
@@ -121,19 +173,39 @@ int32_t tc_ctr_prng_init(TCCtrPrng_t * const ctx,
}
int32_t tc_ctr_prng_reseed(TCCtrPrng_t * const ctx,
- uint8_t const entropy[],
- uint32_t entropyLen)
+ uint8_t const * const entropy,
+ uint32_t entropyLen,
+ uint8_t const * const additional_input,
+ uint32_t additionallen)
{
+ uint32_t i;
int32_t result = TC_FAIL;
+ uint8_t additional_input_buf[TC_AES_KEY_SIZE + TC_AES_BLOCK_SIZE] = {0U};
+ uint8_t seed_material[TC_AES_KEY_SIZE + TC_AES_BLOCK_SIZE];
+
+ if (0 != additional_input)
+ {
+ /* 10.2.1.4.1 step 1 */
+ uint32_t len = additionallen;
+ if (len > sizeof additional_input_buf)
+ {
+ len = sizeof additional_input_buf;
+ }
+
+ /* 10.2.1.4.1 step 2 */
+ memcpy(additional_input_buf, additional_input, len);
+ }
- //todo - add additional input support
- /*
- * 10.2.1.4.1 steps 1 - 3 not required - no additional input accepted by
- * this reseed function
- */
uint32_t seedlen = (uint32_t)TC_AES_KEY_SIZE + (uint32_t)TC_AES_BLOCK_SIZE;
- if ((0 != ctx) && (entropyLen == seedlen))
+ if ((0 != ctx) && (entropyLen >= seedlen))
{
+ /* 10.2.1.4.1 step 3 */
+ memcpy(seed_material, entropy, sizeof seed_material);
+ for (i = 0U; i < sizeof seed_material; i++)
+ {
+ seed_material[i] ^= additional_input_buf[i];
+ }
+
/* 10.2.1.4.1 step 4 */
tc_ctr_prng_update(ctx, entropy);
@@ -145,9 +217,10 @@ int32_t tc_ctr_prng_reseed(TCCtrPrng_t * const ctx,
return result;
}
-//todo comment
-int32_t tc_ctr_prng_generate(TCCtrPrng_t * const ctx,
- uint8_t out[],
+int32_t tc_ctr_prng_generate(TCCtrPrng_t * const ctx,
+ uint8_t const * const additional_input,
+ uint32_t additionallen,
+ uint8_t * const out,
uint32_t outlen)
{
/* 2^48 - see section 10.2.1 */
@@ -167,8 +240,18 @@ int32_t tc_ctr_prng_generate(TCCtrPrng_t * const ctx,
}
else
{
- //todo - add additional input support
- /* 10.2.1.5.1 step 2 - no additional input supported, so no action */
+ uint8_t additional_input_buf[TC_AES_KEY_SIZE + TC_AES_BLOCK_SIZE] = {0U};
+ if (0 != additional_input)
+ {
+ /* 10.2.1.5.1 step 2 */
+ uint32_t len = additionallen;
+ if (len > sizeof additional_input_buf)
+ {
+ len = sizeof additional_input_buf;
+ }
+ memcpy(additional_input_buf, additional_input, len);
+ tc_ctr_prng_update(ctx, additional_input_buf);
+ }
/* 10.2.1.5.1 step 3 - implicit */
@@ -209,6 +292,16 @@ int32_t tc_ctr_prng_generate(TCCtrPrng_t * const ctx,
return result;
}
+void tc_ctr_prng_uninstantiate(TCCtrPrng_t * const ctx)
+{
+ if (0 != ctx)
+ {
+ memset(ctx->key.words, 0x00, sizeof ctx->key.words);
+ memset(ctx->V, 0x00, sizeof ctx->V);
+ ctx->reseedCount = 0U;
+ }
+}
+
diff --git a/tests/test_ctr_prng.c b/tests/test_ctr_prng.c
index 915fe8a..267dd50 100644
--- a/tests/test_ctr_prng.c
+++ b/tests/test_ctr_prng.c
@@ -1,5 +1,32 @@
/* test_ctr_prng.c - TinyCrypt implementation of some CTR-PRNG tests */
+/*
+ * Copyright (c) 2016, Chris Morrison
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * * Redistributions of source code must retain the above copyright notice, this
+ * list of conditions and the following disclaimer.
+ *
+ * * Redistributions in binary form must reproduce the above copyright notice,
+ * this list of conditions and the following disclaimer in the documentation
+ * and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+
#include <test_utils.h>
#include <stdio.h>
#include <stdlib.h>
@@ -50,8 +77,8 @@ int main(void)
TC_START("Performing CTR-PRNG tests:");
- ret += tc_ctr_prng_generate(&ctx, prngOutput, sizeof prngOutput);
- ret += tc_ctr_prng_generate(&ctx, prngOutput, sizeof prngOutput);
+ ret += tc_ctr_prng_generate(&ctx, 0, 0, prngOutput, sizeof prngOutput);
+ ret += tc_ctr_prng_generate(&ctx, 0, 0, prngOutput, sizeof prngOutput);
if (0 == ret)
{
generated by cgit v1.2.3 (git 2.39.1) at 2024-12-04 11:50:35 +0000