1 /*************************************************************************** 2 * Copyright (c) 2024 Microsoft Corporation 3 * 4 * This program and the accompanying materials are made available under the 5 * terms of the MIT License which is available at 6 * https://opensource.org/licenses/MIT. 7 * 8 * SPDX-License-Identifier: MIT 9 **************************************************************************/ 10 11 12 /**************************************************************************/ 13 /**************************************************************************/ 14 /** */ 15 /** NetX Crypto Component */ 16 /** */ 17 /** Elliptic-curve Diffie-Hellman (ECDH) */ 18 /** */ 19 /**************************************************************************/ 20 /**************************************************************************/ 21 22 23 /**************************************************************************/ 24 /* */ 25 /* APPLICATION INTERFACE DEFINITION RELEASE */ 26 /* */ 27 /* nx_crypto_ecdh.h PORTABLE C */ 28 /* 6.1.11 */ 29 /* AUTHOR */ 30 /* */ 31 /* Timothy Stapko, Microsoft Corporation */ 32 /* */ 33 /* DESCRIPTION */ 34 /* */ 35 /* This file defines the basic Application Interface (API) to the */ 36 /* NetX Crypto ECDH module. */ 37 /* */ 38 /* RELEASE HISTORY */ 39 /* */ 40 /* DATE NAME DESCRIPTION */ 41 /* */ 42 /* 05-19-2020 Timothy Stapko Initial Version 6.0 */ 43 /* 09-30-2020 Timothy Stapko Modified comment(s), */ 44 /* resulting in version 6.1 */ 45 /* 04-25-2022 Yuxin Zhou Modified comment(s), supported*/ 46 /* x25519 and x448 curves, */ 47 /* resulting in version 6.1.11 */ 48 /* */ 49 /**************************************************************************/ 50 51 #ifndef NX_CRYPTO_ECDH_H 52 #define NX_CRYPTO_ECDH_H 53 54 /* Determine if a C++ compiler is being used. If so, ensure that standard 55 C is used to process the API information. */ 56 #ifdef __cplusplus 57 58 /* Yes, C++ compiler is present. Use standard C. */ 59 extern "C" { 60 61 #endif 62 63 #include "nx_crypto_ec.h" 64 65 66 /* Max Elliptic-curve Diffie-Hellman key size. Buffer size for calculations is 4X the key size */ 67 #define NX_CRYPTO_ECDH_MAX_KEY_SIZE (68) 68 #ifndef NX_CRYPTO_ECDH_SCRATCH_BUFFER_SIZE 69 #define NX_CRYPTO_ECDH_SCRATCH_BUFFER_SIZE 2464 70 #endif /* NX_CRYPTO_ECDSA_SCRATCH_BUFFER_SIZE */ 71 72 /* Diffie-Hellman Key-exchange control structure. */ 73 typedef struct NX_CRYPTO_ECDH_STRUCT 74 { 75 /* The size of the key being used. This is primarily for testing, but also allows for future expansion. 76 The value is assigned in _nx_crypto_dh_setup depending on the chosen group. */ 77 UINT nx_crypto_ecdh_key_size; 78 79 /* The private key is generated by nx_crypto_dh_setup and is a random number. 80 Make the array in units of UINT to make sure the starting address is 4-byte aligned. */ 81 HN_UBASE nx_crypto_ecdh_private_key_buffer[NX_CRYPTO_ECDH_MAX_KEY_SIZE >> HN_SIZE_SHIFT]; 82 83 /* The elliptic curve selected in the call to nx_crypto_ecdh_setup. */ 84 NX_CRYPTO_EC *nx_crypto_ecdh_curve; 85 86 HN_UBASE nx_crypto_ecdh_scratch_buffer[NX_CRYPTO_ECDH_SCRATCH_BUFFER_SIZE >> HN_SIZE_SHIFT]; 87 } NX_CRYPTO_ECDH; 88 89 /* Function prototypes */ 90 91 92 UINT _nx_crypto_ecdh_key_pair_import(NX_CRYPTO_ECDH *ecdh_ptr, 93 NX_CRYPTO_EC *curve, 94 UCHAR *local_private_key_ptr, 95 ULONG local_private_key_len, 96 UCHAR *local_public_key_ptr, 97 ULONG local_public_key_len); 98 99 UINT _nx_crypto_ecdh_private_key_export(NX_CRYPTO_ECDH *ecdh_ptr, 100 UCHAR *local_private_key_ptr, 101 ULONG local_private_key_len, 102 ULONG *actual_local_private_key_len); 103 104 UINT _nx_crypto_ecdh_setup(NX_CRYPTO_ECDH *ecdh_ptr, 105 UCHAR *local_public_key_ptr, 106 ULONG local_public_key_len_ptr, 107 ULONG *actual_local_public_key_len, 108 NX_CRYPTO_EC *curve, 109 HN_UBASE *scratch_buf_ptr); 110 111 UINT _nx_crypto_ecdh_compute_secret(NX_CRYPTO_ECDH *ecdh_ptr, 112 UCHAR *share_secret_key_ptr, 113 ULONG share_secret_key_len_ptr, 114 ULONG *actual_share_secret_key_len, 115 UCHAR *remote_public_key, 116 ULONG remote_public_key_len, 117 HN_UBASE *scratch_buf_ptr); 118 119 UINT _nx_crypto_method_ecdh_init(struct NX_CRYPTO_METHOD_STRUCT *method, 120 UCHAR *key, NX_CRYPTO_KEY_SIZE key_size_in_bits, 121 VOID **handle, 122 VOID *crypto_metadata, 123 ULONG crypto_metadata_size); 124 125 UINT _nx_crypto_method_ecdh_cleanup(VOID *crypto_metadata); 126 127 UINT _nx_crypto_method_ecdh_operation(UINT op, 128 VOID *handle, 129 struct NX_CRYPTO_METHOD_STRUCT *method, 130 UCHAR *key, NX_CRYPTO_KEY_SIZE key_size_in_bits, 131 UCHAR *input, ULONG input_length_in_byte, 132 UCHAR *iv_ptr, 133 UCHAR *output, ULONG output_length_in_byte, 134 VOID *crypto_metadata, ULONG crypto_metadata_size, 135 VOID *packet_ptr, 136 VOID (*nx_crypto_hw_process_callback)(VOID *, UINT)); 137 138 #ifdef NX_CRYPTO_ENABLE_CURVE25519_448 139 UINT _nx_crypto_ecdh_key_pair_import_x25519_448(NX_CRYPTO_ECDH *ecdh_ptr, 140 NX_CRYPTO_EC *curve, 141 UCHAR *local_private_key_ptr, 142 ULONG local_private_key_len, 143 UCHAR *local_public_key_ptr, 144 ULONG local_public_key_len); 145 UINT _nx_crypto_ecdh_private_key_export_x25519_448(NX_CRYPTO_ECDH *ecdh_ptr, 146 UCHAR *local_private_key_ptr, 147 ULONG local_private_key_len, 148 ULONG *actual_local_private_key_len); 149 UINT _nx_crypto_ecdh_setup_x25519_448(NX_CRYPTO_ECDH *ecdh_ptr, 150 UCHAR *local_public_key_ptr, 151 ULONG local_public_key_len, 152 ULONG *actual_local_public_key_len, 153 NX_CRYPTO_EC *curve, 154 HN_UBASE *scratch_buf_ptr); 155 UINT _nx_crypto_ecdh_compute_secret_x25519_448(NX_CRYPTO_ECDH *ecdh_ptr, 156 UCHAR *share_secret_key_ptr, 157 ULONG share_secret_key_len_ptr, 158 ULONG *actual_share_secret_key_len, 159 UCHAR *remote_public_key, 160 ULONG remote_public_key_len, 161 HN_UBASE *scratch_buf_ptr); 162 #endif /* NX_CRYPTO_ENABLE_CURVE25519_448 */ 163 164 #ifdef __cplusplus 165 } 166 #endif 167 168 #endif /* NX_CRYPTO_ECDH_H */ 169 170
