Clean up the CLI.

A lot of the commands were just useful when testing/implementing
features for the Alpha. Remove them now that they have been merged to
projects/cli-test.

7 files changed, 6 insertions, 392 deletions

diff --git a/projects/hsm/mgmt-dfu.c b/projects/hsm/mgmt-dfu.c
deleted file mode 100644
index e57c521..0000000
--- a/projects/hsm/mgmt-dfu.c
+++ /dev/null
@@ -1,123 +0,0 @@
-/*
- * mgmt-dfu.c
- * ---------
- * CLI code for looking at, jumping to or erasing the loaded firmware.
- *
- * Copyright (c) 2016, NORDUnet A/S 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.
- *
- * - Neither the name of the NORDUnet 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.
- */
-
-#include "stm-init.h"
-#include "mgmt-cli.h"
-#include "stm-uart.h"
-#include "stm-flash.h"
-#include "mgmt-dfu.h"
-
-#include <string.h>
-
-#define DFU_FIRMWARE_ADDR         ((uint32_t) &CRYPTECH_FIRMWARE_START)
-#define DFU_FIRMWARE_END_ADDR     ((uint32_t) &CRYPTECH_FIRMWARE_END)
-#define DFU_UPLOAD_CHUNK_SIZE     256
-#define HARDWARE_EARLY_DFU_JUMP   0xBADABADA
-
-extern uint32_t update_crc(uint32_t crc, uint8_t *buf, int len);
-
-/* Linker symbols are strange in C. Make regular pointers for sanity. */
-__IO uint32_t *dfu_control = &CRYPTECH_DFU_CONTROL;
-__IO uint32_t *dfu_firmware = &CRYPTECH_FIRMWARE_START;
-__IO uint32_t *dfu_firmware_end = &CRYPTECH_FIRMWARE_END;
-/* The first word in the firmware is an address to the stack (msp) */
-__IO uint32_t *dfu_msp_ptr = &CRYPTECH_FIRMWARE_START;
-/* The second word in the firmware is a pointer to the code
- * (points at the Reset_Handler from the linker script).
- */
-__IO uint32_t *dfu_code_ptr = &CRYPTECH_FIRMWARE_START + 1;
-
-static int cmd_dfu_dump(struct cli_def *cli, const char *command, char *argv[], int argc)
-{
-    cli_print(cli, "First 256 bytes from DFU application address %p:\r\n", dfu_firmware);
-
-    uart_send_hexdump(STM_UART_MGMT, (uint8_t *) dfu_firmware, 0, 0xff);
-    uart_send_string2(STM_UART_MGMT, (char *) "\r\n\r\n");
-
-    return CLI_OK;
-}
-
-static int cmd_dfu_erase(struct cli_def *cli, const char *command, char *argv[], int argc)
-{
-    int status;
-
-    cli_print(cli, "Erasing flash sectors %i to %i (address %p to %p) - expect the CLI to crash now",
-	      stm_flash_sector_num((uint32_t) dfu_firmware),
-	      stm_flash_sector_num((uint32_t) dfu_firmware_end),
-	      dfu_firmware,
-	      dfu_firmware_end);
-
-    if ((status = stm_flash_erase_sectors((uint32_t) dfu_firmware, (uint32_t) dfu_firmware_end)) != 0) {
-	cli_print(cli, "Failed erasing flash sectors (%i)", status);
-    }
-
-    return CLI_OK;
-}
-
-static int cmd_dfu_jump(struct cli_def *cli, const char *command, char *argv[], int argc)
-{
-    uint32_t i;
-    /* Load first byte from the DFU_FIRMWARE_PTR to verify it contains an IVT before
-     * jumping there.
-     */
-    cli_print(cli, "Checking for application at %p", dfu_firmware);
-
-    i = *dfu_msp_ptr & 0xFF000000;
-    /* 'new_msp' is supposed to be a pointer to the new applications stack, it should
-     * point either at RAM (0x20000000) or at the CCM memory (0x10000000).
-     */
-    if (i == 0x20000000 || i == 0x10000000) {
-	/* Set dfu_control to the magic value that will cause the us to jump to the
-	 * firmware from the CLI main() function after rebooting.
-	 */
-	*dfu_control = HARDWARE_EARLY_DFU_JUMP;
-	cli_print(cli, "Making the leap");
-	HAL_NVIC_SystemReset();
-	while (1) { ; }
-    } else {
-	cli_print(cli, "No loaded application found at %p (read 0x%x)",
-		  dfu_firmware, (unsigned int) *dfu_msp_ptr);
-    }
-
-    return CLI_OK;
-}
-
-void configure_cli_dfu(struct cli_def *cli)
-{
-    cli_command_root(dfu);
-
-    cli_command_node(dfu, dump, "Show the first 256 bytes of the loaded firmware");
-    cli_command_node(dfu, jump, "Jump to the loaded firmware");
-    cli_command_node(dfu, erase, "Erase the firmware memory (will crash the CLI)");
-}
diff --git a/projects/hsm/mgmt-dfu.h b/projects/hsm/mgmt-dfu.h
deleted file mode 100644
index 047e30a..0000000
--- a/projects/hsm/mgmt-dfu.h
+++ /dev/null
@@ -1,48 +0,0 @@
-/*
- * mgmt-dfu.h
- * ---------
- * Management CLI Device Firmware Upgrade code.
- *
- * Copyright (c) 2016, NORDUnet A/S 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.
- *
- * - Neither the name of the NORDUnet 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 __STM32_CLI_MGMT_DFU_H
-#define __STM32_CLI_MGMT_DFU_H
-
-#include "stm-init.h"
-#include <libcli.h>
-
-/* symbols defined in the linker script (STM32F429BI.ld) */
-extern uint32_t CRYPTECH_FIRMWARE_START;
-extern uint32_t CRYPTECH_FIRMWARE_END;
-extern uint32_t CRYPTECH_DFU_CONTROL;
-
-extern void configure_cli_dfu(struct cli_def *cli);
-
-#endif /* __STM32_CLI_MGMT_DFU_H */
diff --git a/projects/hsm/mgmt-fpga.c b/projects/hsm/mgmt-fpga.c
index 45bd33c..5092599 100644
--- a/projects/hsm/mgmt-fpga.c
+++ b/projects/hsm/mgmt-fpga.c
@@ -124,15 +124,6 @@ static int cmd_fpga_reset(struct cli_def *cli, const char *command, char *argv[]
     return CLI_OK;
 }
 
-static int cmd_fpga_reset_registers(struct cli_def *cli, const char *command, char *argv[], int argc)
-{
-    fpgacfg_access_control(ALLOW_FPGA);
-    fpgacfg_reset_fpga(RESET_REGISTERS);
-    cli_print(cli, "FPGA registers have been reset");
-
-    return CLI_OK;
-}
-
 static int cmd_fpga_show_status(struct cli_def *cli, const char *command, char *argv[], int argc)
 {
     cli_print(cli, "FPGA has %sloaded a bitstream", fpgacfg_check_done() ? "":"NOT ");
@@ -166,8 +157,6 @@ void configure_cli_fpga(struct cli_def *cli)
 
     /* fpga reset */
     cli_command_node(fpga, reset, "Reset FPGA (config reset)");
-    /* fpga reset registers */
-    cli_command_node(fpga_reset, registers, "Reset FPGA registers (soft reset)");
 
     cli_command_branch(fpga, bitstream);
     /* fpga bitstream upload */
diff --git a/projects/hsm/mgmt-keystore.c b/projects/hsm/mgmt-keystore.c
index 128ae4c..ab8bcfb 100644
--- a/projects/hsm/mgmt-keystore.c
+++ b/projects/hsm/mgmt-keystore.c
@@ -149,104 +149,6 @@ int cmd_keystore_set_pin_iterations(struct cli_def *cli, const char *command, ch
     return CLI_OK;
 }
 
-int cmd_keystore_set_key(struct cli_def *cli, const char *command, char *argv[], int argc)
-{
-    hal_error_t status;
-    int hint = 0;
-
-    if (argc != 2) {
-	cli_print(cli, "Wrong number of arguments (%i).", argc);
-	cli_print(cli, "Syntax: keystore set key <name> <der>");
-	return CLI_ERROR;
-    }
-
-    if ((status = hal_ks_store(HAL_KEY_TYPE_EC_PUBLIC,
-			       HAL_CURVE_NONE,
-			       0,
-			       (uint8_t *) argv[0], strlen(argv[0]),
-			       (uint8_t *) argv[1], strlen(argv[1]),
-			       &hint)) != LIBHAL_OK) {
-
-	cli_print(cli, "Failed storing key: %s", hal_error_string(status));
-	return CLI_ERROR;
-    }
-
-    cli_print(cli, "Stored key %i", hint);
-
-    return CLI_OK;
-}
-
-int cmd_keystore_delete_key(struct cli_def *cli, const char *command, char *argv[], int argc)
-{
-    hal_error_t status;
-    int hint = 0;
-
-    if (argc != 1) {
-	cli_print(cli, "Wrong number of arguments (%i).", argc);
-	cli_print(cli, "Syntax: keystore delete key <name>");
-	return CLI_ERROR;
-    }
-
-    if ((status = hal_ks_delete(HAL_KEY_TYPE_EC_PUBLIC,
-				(uint8_t *) argv[0], strlen(argv[0]),
-				&hint)) != LIBHAL_OK) {
-
-	cli_print(cli, "Failed deleting key: %s", hal_error_string(status));
-	return CLI_ERROR;
-    }
-
-    cli_print(cli, "Deleted key %i", hint);
-
-    return CLI_OK;
-}
-
-int cmd_keystore_rename_key(struct cli_def *cli, const char *command, char *argv[], int argc)
-{
-    hal_error_t status;
-    int hint = 0;
-
-    if (argc != 2) {
-	cli_print(cli, "Wrong number of arguments (%i).", argc);
-	cli_print(cli, "Syntax: keystore rename key <name> <new name>");
-	return CLI_ERROR;
-    }
-
-    if ((status = hal_ks_rename(HAL_KEY_TYPE_EC_PUBLIC,
-				(uint8_t *) argv[0], strlen(argv[0]),
-				(uint8_t *) argv[1], strlen(argv[1]),
-				&hint)) != LIBHAL_OK) {
-
-	cli_print(cli, "Failed renaming key: %s", hal_error_string(status));
-	return CLI_ERROR;
-    }
-
-    cli_print(cli, "Renamed key %i", hint);
-
-    return CLI_OK;
-}
-
-int cmd_keystore_show_data(struct cli_def *cli, const char *command, char *argv[], int argc)
-{
-    uint8_t buf[KEYSTORE_PAGE_SIZE];
-    uint32_t i;
-
-    if (keystore_check_id() != 1) {
-	cli_print(cli, "ERROR: The keystore memory is not accessible.");
-    }
-
-    memset(buf, 0, sizeof(buf));
-    if ((i = keystore_read_data(0, buf, sizeof(buf))) != 1) {
-	cli_print(cli, "Failed reading first page from keystore memory: %li", i);
-	return CLI_ERROR;
-    }
-
-    cli_print(cli, "First page from keystore memory:\r\n");
-    uart_send_hexdump(STM_UART_MGMT, buf, 0, sizeof(buf) - 1);
-    uart_send_string2(STM_UART_MGMT, (char *) "\r\n\r\n");
-
-    return CLI_OK;
-}
-
 int cmd_keystore_show_keys(struct cli_def *cli, const char *command, char *argv[], int argc)
 {
     const hal_ks_keydb_t *db;
@@ -258,39 +160,21 @@ int cmd_keystore_show_keys(struct cli_def *cli, const char *command, char *argv[
 	return CLI_OK;
     }
 
-    cli_print(cli, "Sizeof db->keys is %i, sizeof one key is %i\n", sizeof(db->keys), sizeof(*db->keys));
+    /* cli_print(cli, "Sizeof db->keys is %i, sizeof one key is %i\n", sizeof(db->keys), sizeof(*db->keys)); */
 
     for (int i = 0; i < sizeof(db->keys)/sizeof(*db->keys); i++) {
 	if (! db->keys[i].in_use) {
 	    cli_print(cli, "Key %i, not in use", i);
 	} else {
-	    cli_print(cli, "Key %i, in use 0x%x, name '%s' der '%s'",
-		      i, db->keys[i].in_use, db->keys[i].name, db->keys[i].der);
+	    cli_print(cli, "Key %i, in use 0x%x",
+		      i, db->keys[i].in_use);
 	}
     }
 
     cli_print(cli, "\nPins:");
     cli_print(cli, "Wheel iterations: 0x%lx", db->wheel_pin.iterations);
-    cli_print(cli, "pin");
-    uart_send_hexdump(STM_UART_MGMT, db->wheel_pin.pin, 0, sizeof(db->wheel_pin.pin) - 1);
-    cli_print(cli, "\nsalt");
-    uart_send_hexdump(STM_UART_MGMT, db->wheel_pin.salt, 0, sizeof(db->wheel_pin.salt) - 1);
-    cli_print(cli, "");
-
     cli_print(cli, "SO    iterations: 0x%lx", db->so_pin.iterations);
-    cli_print(cli, "pin");
-    uart_send_hexdump(STM_UART_MGMT, db->so_pin.pin, 0, sizeof(db->so_pin.pin) - 1);
-    cli_print(cli, "\nsalt");
-    uart_send_hexdump(STM_UART_MGMT, db->so_pin.salt, 0, sizeof(db->so_pin.salt) - 1);
-    cli_print(cli, "");
-
     cli_print(cli, "User  iterations: 0x%lx", db->user_pin.iterations);
-    cli_print(cli, "pin");
-    uart_send_hexdump(STM_UART_MGMT, db->user_pin.pin, 0, sizeof(db->user_pin.pin) - 1);
-    cli_print(cli, "\nsalt");
-    uart_send_hexdump(STM_UART_MGMT, db->user_pin.salt, 0, sizeof(db->user_pin.salt) - 1);
-    cli_print(cli, "");
-    cli_print(cli, "\n");
 
     return CLI_OK;
 }
@@ -325,10 +209,6 @@ void configure_cli_keystore(struct cli_def *cli)
     cli_command_branch(keystore, set);
     /* keystore clear */
     cli_command_branch(keystore, clear);
-    /* keystore delete */
-    cli_command_branch(keystore, delete);
-    /* keystore rename */
-    cli_command_branch(keystore, rename);
     /* keystore show */
     cli_command_branch(keystore, show);
 
@@ -344,18 +224,6 @@ void configure_cli_keystore(struct cli_def *cli)
     /* keystore clear pin */
     cli_command_node(keystore_clear, pin, "Clear either 'wheel', 'user' or 'so' PIN");
 
-    /* keystore set key */
-    cli_command_node(keystore_set, key, "Set a key");
-
-    /* keystore delete key */
-    cli_command_node(keystore_delete, key, "Delete a key");
-
-    /* keystore rename key */
-    cli_command_node(keystore_rename, key, "Rename a key");
-
-    /* keystore show data */
-    cli_command_node(keystore_show, data, "Dump the first page from the keystore memory");
-
     /* keystore show keys */
     cli_command_node(keystore_show, keys, "Show what PINs and keys are in the keystore");
 }
diff --git a/projects/hsm/mgmt-masterkey.c b/projects/hsm/mgmt-masterkey.c
index 7938e33..3a48057 100644
--- a/projects/hsm/mgmt-masterkey.c
+++ b/projects/hsm/mgmt-masterkey.c
@@ -84,7 +84,6 @@ static int _parse_hex_groups(uint8_t *buf, size_t len, char *argv[], int argc)
 static int cmd_masterkey_status(struct cli_def *cli, const char *command, char *argv[], int argc)
 {
     hal_error_t status;
-    uint8_t buf[KEK_LENGTH] = {0};
 
     cli_print(cli, "Status of master key:\n");
 
@@ -94,28 +93,6 @@ static int cmd_masterkey_status(struct cli_def *cli, const char *command, char *
     status = masterkey_flash_read(NULL, 0);
     cli_print(cli, "     flash: %s / %s", _status2str(status), hal_error_string(status));
 
-    /* XXX Temporary gaping security hole while developing the master key functionality.
-     * REMOVE READ-OUT OF MASTER KEY.
-     */
-
-    status = masterkey_volatile_read(&buf[0], sizeof(buf));
-    if (status == LIBHAL_OK || status == HAL_ERROR_MASTERKEY_NOT_SET) {
-	cli_print(cli, "\nVolatile read-out:\n");
-	uart_send_hexdump(STM_UART_MGMT, buf, 0, sizeof(buf) - 1);
-	cli_print(cli, "\n");
-    } else {
-	cli_print(cli, "Failed reading from volatile memory: %s", hal_error_string(status));
-    }
-
-    status = masterkey_flash_read(&buf[0], sizeof(buf));
-    if (status == LIBHAL_OK || status == HAL_ERROR_MASTERKEY_NOT_SET) {
-	cli_print(cli, "\nFlash read-out:\n");
-	uart_send_hexdump(STM_UART_MGMT, buf, 0, sizeof(buf) - 1);
-	cli_print(cli, "\n");
-    } else {
-	cli_print(cli, "Failed reading from flash: %s", hal_error_string(status));
-    }
-
     return CLI_OK;
 }
 
@@ -126,7 +103,7 @@ static int cmd_masterkey_set(struct cli_def *cli, const char *command, char *arg
     int i;
 
     if ((i = _parse_hex_groups(&buf[0], sizeof(buf), argv, argc)) != 1) {
-	cli_print(cli, "Failed parsing master key (%i)", i);
+	cli_print(cli, "Failed parsing master key, expected up to 8 groups of 32-bit hex chars (%i)", i);
 	return CLI_OK;
     }
 
@@ -161,7 +138,7 @@ static int cmd_masterkey_unsecure_set(struct cli_def *cli, const char *command,
     int i;
 
     if ((i = _parse_hex_groups(&buf[0], sizeof(buf), argv, argc)) != 1) {
-	cli_print(cli, "Failed parsing master key (%i)", i);
+	cli_print(cli, "Failed parsing master key, expected up to 8 groups of 32-bit hex chars (%i)", i);
 	return CLI_OK;
     }
 
diff --git a/projects/hsm/mgmt-show.c b/projects/hsm/mgmt-show.c
index 2019efb..ac78f30 100644
--- a/projects/hsm/mgmt-show.c
+++ b/projects/hsm/mgmt-show.c
@@ -66,54 +66,6 @@ static int cmd_show_keystore_status(struct cli_def *cli, const char *command, ch
     return CLI_OK;
 }
 
-static int cmd_show_keystore_data(struct cli_def *cli, const char *command, char *argv[], int argc)
-{
-    uint8_t buf[KEYSTORE_PAGE_SIZE];
-    uint32_t i;
-
-    if (keystore_check_id() != 1) {
-	cli_print(cli, "ERROR: The keystore memory is not accessible.");
-    }
-
-    memset(buf, 0, sizeof(buf));
-    if ((i = keystore_read_data(0, buf, sizeof(buf))) != 1) {
-	cli_print(cli, "Failed reading first page from keystore memory: %li", i);
-	return CLI_ERROR;
-    }
-
-    cli_print(cli, "First page from keystore memory:\r\n");
-    uart_send_hexdump(STM_UART_MGMT, buf, 0, sizeof(buf) - 1);
-    uart_send_string2(STM_UART_MGMT, (char *) "\r\n\r\n");
-
-    for (i = 0; i < 8; i++) {
-	if (buf[i] == 0xff) break;  /* never written */
-	if (buf[i] != 0x55) break;  /* something other than a tombstone */
-    }
-    /* As a demo, tombstone byte after byte of the first 8 bytes in the keystore memory
-     * (as long as they do not appear to contain real data).
-     * If all of them are tombstones, erase the first sector to start over.
-     */
-    if (i < 8) {
-	if (buf[i] == 0xff) {
-	    cli_print(cli, "Tombstoning byte %li", i);
-	    buf[i] = 0x55;
-	    if ((i = keystore_write_data(0, buf, sizeof(buf))) != 1) {
-		cli_print(cli, "Failed writing data at offset 0: %li", i);
-		return CLI_ERROR;
-	    }
-	}
-    } else {
-	cli_print(cli, "Erasing first sector since all the first 8 bytes are tombstones");
-	if ((i = keystore_erase_sectors(1, 1)) != 1) {
-	    cli_print(cli, "Failed erasing the first sector: %li", i);
-	    return CLI_ERROR;
-	}
-	cli_print(cli, "Erase result: %li", i);
-    }
-
-    return CLI_OK;
-}
-
 void configure_cli_show(struct cli_def *cli)
 {
     /* show */
@@ -129,5 +81,4 @@ void configure_cli_show(struct cli_def *cli)
     cli_command_branch(show, keystore);
     /* show keystore status*/
     cli_command_node(show_keystore, status, "Show status of the keystore memory");
-    cli_command_node(show_keystore, data, "Show the first page of the keystore memory");
 }
diff --git a/projects/hsm/mgmt-show.h b/projects/hsm/mgmt-show.h
index 0d7ba3a..e459acb 100644
--- a/projects/hsm/mgmt-show.h
+++ b/projects/hsm/mgmt-show.h
@@ -1,5 +1,5 @@
 /*
- * mgmt-misc.h
+ * mgmt-show.h
  * -----------
  * Management CLI 'show' functions.
  *