lib/ukrandom: Define the driver API

Define the driver API of libukrandom. This is a generic API that
deprecates the CPU-oriented ukarch_random API.

Checkpatch-Ignore: SPACING
Signed-off-by: Michalis Pappas <michalis@unikraft.io>
Reviewed-by: Maria Pana <maria.pana4@gmail.com>
Reviewed-by: Alex Apostolescu <alexx.apostolescu@gmail.com>
Reviewed-by: Simon Kuenzer <simon@unikraft.io>
Approved-by: Simon Kuenzer <simon@unikraft.io>
GitHub-Closes: #1496

diff --git a/include/uk/arch/random.h b/include/uk/arch/random.h
deleted file mode 100644 (file)
index d842e72..0000000
--- a/include/uk/arch/random.h
+++ /dev/null
@@ -1,117 +0,0 @@
-/* SPDX-License-Identifier: BSD-3-Clause */
-/*
- * Copyright (c) 2022, Michalis Pappas <mpappas@fastmail.fm>.
- *                     All rights reserved.
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions
- * are met:
- *
- * 1. Redistributions of source code must retain the above copyright
- *    notice, this list of conditions and the following disclaimer.
- * 2. 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.
- * 3. Neither the name of the copyright holder nor the names of its
- *    contributors may be used to endorse or promote products derived from
- *    this software without specific prior written permission.
- *
- * 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.
- */
-#ifndef __UKARCH_RANDOM_H__
-#define __UKARCH_RANDOM_H__
-
-#include <uk/arch/types.h>
-#include <uk/essentials.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-#if CONFIG_HAVE_RANDOM
-
-#include <uk/asm/random.h>
-
-/**
- * Initialize the RNG
- *
- * @return 0 on success, negative value on failure
- */
-int ukarch_random_init(void);
-
-/**
- * Get a 32-bit random integer
- *
- * @param [out] val Pointer to store the generated value
- * @return 0 on success, negative value on failure
- */
-int __check_result ukarch_random_u32(__u32 *val);
-
-/**
- * Get a 64-bit random integer
- *
- * @param [out] val Pointer to store the generated value
- * @return 0 on success, negative value on failure
- */
-int __check_result ukarch_random_u64(__u64 *val);
-
-/**
- * Get a 32-bit random integer suitable for seeding
- *
- * @param [out] val Pointer to store the generated value
- * @return 0 on success, negative value on failure
- */
-int __check_result ukarch_random_seed_u32(__u32 *val);
-
-/**
- * Get a 64-bit random integer suitable for seeding
- *
- * @param [out] val Pointer to store the generated value
- * @return 0 on success, negative value on failure
- */
-int __check_result ukarch_random_seed_u64(__u64 *val);
-
-#else /* CONFIG_HAVE_RANDOM */
-
-static inline int __check_result ukarch_random_init(void)
-{
-       return -1;
-}
-
-static inline int __check_result ukarch_random_u32(__u32 *val __unused)
-{
-       return -1;
-}
-
-static inline int __check_result ukarch_random_u64(__u64 *val __unused)
-{
-       return -1;
-}
-
-static inline int __check_result ukarch_random_seed_u32(__u32 *val __unused)
-{
-       return -1;
-}
-
-static inline int __check_result ukarch_random_seed_u64(__u64 *val __unused)
-{
-       return -1;
-}
-
-#endif /* CONFIG_HAVE_RANDOM */
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif /* __UKARCH_RANDOM_H__ */

diff --git a/lib/ukrandom/include/uk/random.h b/lib/ukrandom/include/uk/random.h
index 7a6cd22cac1ff7ef8e6b26f3bdeab832c98cb46e..b73ddb93d6cd747bd9c50cd1341cf93e382a3ed2 100644 (file)
--- a/lib/ukrandom/include/uk/random.h
+++ b/lib/ukrandom/include/uk/random.h
@@ -38,14 +38,16 @@ extern "C" {
 #endif
 
 #include <uk/arch/types.h>
+#include <uk/compiler.h>
 
 /**
  * Fills a buffer with random bytes.
  *
  * @param buf Pointer to the buffer to be filled.
  * @param buflen Length of the buffer in bytes.
+ * @return zero on success, negative value on error.
  */
-void uk_random_fill_buffer(void *buf, __sz buflen);
+int __check_result uk_random_fill_buffer(void *buf, __sz buflen);
 
 #ifdef __cplusplus
 }

diff --git a/lib/ukrandom/include/uk/random/driver.h b/lib/ukrandom/include/uk/random/driver.h
new file mode 100644 (file)
index 0000000..5f875b5
--- /dev/null
+++ b/lib/ukrandom/include/uk/random/driver.h
@@ -0,0 +1,81 @@
+/* SPDX-License-Identifier: BSD-3-Clause */
+/* Copyright (c) 2022, Unikraft GmbH and The Unikraft Authors.
+ * Licensed under the BSD-3-Clause License (the "License").
+ * You may not use this file except in compliance with the License.
+ */
+
+#ifndef __UK_RANDOM_DRIVER_H__
+#define __UK_RANDOM_DRIVER_H__
+
+#include <uk/arch/types.h>
+#include <uk/essentials.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define UK_RANDOM_EARLY_DRIVER_PRIO    UK_PRIO_AFTER(3)
+
+struct uk_random_driver_ops {
+       /**
+        * Get random bytes
+        *
+        * @param [out] buf  Buffer to store the generated bytes
+        * @param       size Buffer size
+        * @return 0 on success, negative value on failure
+        */
+       int __check_result (*random_bytes)(__u8 *buf, __sz size);
+
+       /**
+        * Get random bytes suitable for seeding
+        *
+        * Some random number generators, most notably those provided by CPUs,
+        * provide a separate operation for random numbers suitable for seeding.
+        * These normally originate directly from the TRNG instead of a seeded
+        * DRBG, so they have higher multiplicative prediction resistance.
+        *
+        * Devices that don't support this operation return an error.
+        *
+        * @param [out] buf  Buffer to store the generated bytes
+        * @param       size Buffer size
+        * @return 0 on success, negative value on failure
+        */
+       int __check_result (*seed_bytes)(__u8 *buf, __sz size);
+
+       /**
+        * seed_bytes() with fallback.
+        *
+        * This function implementes the same functionality as @seed_bytes
+        * but falls back to random_bytes() if the device does not provide
+        * a seed operation, or if the seed operation fails due to exhaustion.
+        *
+        * @param [out] buf  Buffer to store the generated bytes
+        * @param       size Buffer size
+        * @return 0 on success, negative value on failure
+        */
+       int __check_result (*seed_bytes_fb)(__u8 *buf, __sz size);
+};
+
+struct uk_random_driver {
+       const char *name;
+       struct uk_random_driver_ops *ops;
+};
+
+/**
+ * Initialize libukrandom
+ *
+ * Registers the calling driver with libukrandom and initializes the
+ * software CSPRNG. Only one source of entropy is supported. If more
+ * than one driver is enabled, only the first registration takes
+ * effect.
+ *
+ * @param drv driver representation (@uk_random_driver)
+ * @return zero on success, negative value on error
+ */
+int __check_result uk_random_init(struct uk_random_driver *drv);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __UK_RANDOM_DRIVER_H__*/