demos/keyexch/x25519.c

   1 /*
   2  * Copyright 2022-2023 The OpenSSL Project Authors. All Rights Reserved.
   3  *
   4  * Licensed under the Apache License 2.0 (the "License").  You may not use
   5  * this file except in compliance with the License.  You can obtain a copy
   6  * in the file LICENSE in the source distribution or at
   7  * https://www.openssl.org/source/license.html
   8  */
   9
  10 #include <stdio.h>
  11 #include <string.h>
  12 #include <openssl/core_names.h>
  13 #include <openssl/evp.h>
  14
  15 /*
  16  * This is a demonstration of key exchange using X25519.
  17  *
  18  * The variables beginning `peer1_` / `peer2_` are data which would normally be
  19  * accessible to that peer.
  20  *
  21  * Ordinarily you would use random keys, which are demonstrated
  22  * below when use_kat=0. A known answer test is demonstrated
  23  * when use_kat=1.
  24  */
  25
  26 /* A property query used for selecting the X25519 implementation. */
  27 static const char *propq = NULL;
  28
  29 static const unsigned char peer1_privk_data[32] = {
  30     0x80, 0x5b, 0x30, 0x20, 0x25, 0x4a, 0x70, 0x2c,
  31     0xad, 0xa9, 0x8d, 0x7d, 0x47, 0xf8, 0x1b, 0x20,
  32     0x89, 0xd2, 0xf9, 0x14, 0xac, 0x92, 0x27, 0xf2,
  33     0x10, 0x7e, 0xdb, 0x21, 0xbd, 0x73, 0x73, 0x5d
  34 };
  35
  36 static const unsigned char peer2_privk_data[32] = {
  37     0xf8, 0x84, 0x19, 0x69, 0x79, 0x13, 0x0d, 0xbd,
  38     0xb1, 0x76, 0xd7, 0x0e, 0x7e, 0x0f, 0xb6, 0xf4,
  39     0x8c, 0x4a, 0x8c, 0x5f, 0xd8, 0x15, 0x09, 0x0a,
  40     0x71, 0x78, 0x74, 0x92, 0x0f, 0x85, 0xc8, 0x43
  41 };
  42
  43 static const unsigned char expected_result[32] = {
  44     0x19, 0x71, 0x26, 0x12, 0x74, 0xb5, 0xb1, 0xce,
  45     0x77, 0xd0, 0x79, 0x24, 0xb6, 0x0a, 0x5c, 0x72,
  46     0x0c, 0xa6, 0x56, 0xc0, 0x11, 0xeb, 0x43, 0x11,
  47     0x94, 0x3b, 0x01, 0x45, 0xca, 0x19, 0xfe, 0x09
  48 };
  49
  50 typedef struct peer_data_st {
  51     const char *name;               /* name of peer */
  52     EVP_PKEY *privk;                /* privk generated for peer */
  53     unsigned char pubk_data[32];    /* generated pubk to send to other peer */
  54
  55     unsigned char *secret;          /* allocated shared secret buffer */
  56     size_t secret_len;
  57 } PEER_DATA;
  58
  59 /*
  60  * Prepare for X25519 key exchange. The public key to be sent to the remote peer
  61  * is put in pubk_data, which should be a 32-byte buffer. Returns 1 on success.
  62  */
  63 static int keyexch_x25519_before(
  64     OSSL_LIB_CTX *libctx,
  65     const unsigned char *kat_privk_data,
  66     PEER_DATA *local_peer)
  67 {
  68     int ret = 0;
  69     size_t pubk_data_len = 0;
  70
  71     /* Generate or load X25519 key for the peer */
  72     if (kat_privk_data != NULL)
  73         local_peer->privk =
  74             EVP_PKEY_new_raw_private_key_ex(libctx, "X25519", propq,
  75                                             kat_privk_data,
  76                                             sizeof(peer1_privk_data));
  77     else
  78         local_peer->privk = EVP_PKEY_Q_keygen(libctx, propq, "X25519");
  79
  80     if (local_peer->privk == NULL) {
  81         fprintf(stderr, "Could not load or generate private key\n");
  82         goto end;
  83     }
  84
  85     /* Get public key corresponding to the private key */
  86     if (EVP_PKEY_get_octet_string_param(local_peer->privk,
  87                                         OSSL_PKEY_PARAM_PUB_KEY,
  88                                         local_peer->pubk_data,
  89                                         sizeof(local_peer->pubk_data),
  90                                         &pubk_data_len) == 0) {
  91         fprintf(stderr, "EVP_PKEY_get_octet_string_param() failed\n");
  92         goto end;
  93     }
  94
  95     /* X25519 public keys are always 32 bytes */
  96     if (pubk_data_len != 32) {
  97         fprintf(stderr, "EVP_PKEY_get_octet_string_param() "
  98                 "yielded wrong length\n");
  99         goto end;
 100     }
 101
 102     ret = 1;
 103 end:
 104     if (ret == 0) {
 105         EVP_PKEY_free(local_peer->privk);
 106         local_peer->privk = NULL;
 107     }
 108
 109     return ret;
 110 }
 111
 112 /*
 113  * Complete X25519 key exchange. remote_peer_pubk_data should be the 32 byte
 114  * public key value received from the remote peer. On success, returns 1 and the
 115  * secret is pointed to by *secret. The caller must free it.
 116  */
 117 static int keyexch_x25519_after(
 118     OSSL_LIB_CTX *libctx,
 119     int use_kat,
 120     PEER_DATA *local_peer,
 121     const unsigned char *remote_peer_pubk_data)
 122 {
 123     int ret = 0;
 124     EVP_PKEY *remote_peer_pubk = NULL;
 125     EVP_PKEY_CTX *ctx = NULL;
 126
 127     local_peer->secret = NULL;
 128
 129     /* Load public key for remote peer. */
 130     remote_peer_pubk =
 131         EVP_PKEY_new_raw_public_key_ex(libctx, "X25519", propq,
 132                                        remote_peer_pubk_data, 32);
 133     if (remote_peer_pubk == NULL) {
 134         fprintf(stderr, "EVP_PKEY_new_raw_public_key_ex() failed\n");
 135         goto end;
 136     }
 137
 138     /* Create key exchange context. */
 139     ctx = EVP_PKEY_CTX_new_from_pkey(libctx, local_peer->privk, propq);
 140     if (ctx == NULL) {
 141         fprintf(stderr, "EVP_PKEY_CTX_new_from_pkey() failed\n");
 142         goto end;
 143     }
 144
 145     /* Initialize derivation process. */
 146     if (EVP_PKEY_derive_init(ctx) == 0) {
 147         fprintf(stderr, "EVP_PKEY_derive_init() failed\n");
 148         goto end;
 149     }
 150
 151     /* Configure each peer with the other peer's public key. */
 152     if (EVP_PKEY_derive_set_peer(ctx, remote_peer_pubk) == 0) {
 153         fprintf(stderr, "EVP_PKEY_derive_set_peer() failed\n");
 154         goto end;
 155     }
 156
 157     /* Determine the secret length. */
 158     if (EVP_PKEY_derive(ctx, NULL, &local_peer->secret_len) == 0) {
 159         fprintf(stderr, "EVP_PKEY_derive() failed\n");
 160         goto end;
 161     }
 162
 163     /*
 164      * We are using X25519, so the secret generated will always be 32 bytes.
 165      * However for exposition, the code below demonstrates a generic
 166      * implementation for arbitrary lengths.
 167      */
 168     if (local_peer->secret_len != 32) { /* unreachable */
 169         fprintf(stderr, "Secret is always 32 bytes for X25519\n");
 170         goto end;
 171     }
 172
 173     /* Allocate memory for shared secrets. */
 174     local_peer->secret = OPENSSL_malloc(local_peer->secret_len);
 175     if (local_peer->secret == NULL) {
 176         fprintf(stderr, "Could not allocate memory for secret\n");
 177         goto end;
 178     }
 179
 180     /* Derive the shared secret. */
 181     if (EVP_PKEY_derive(ctx, local_peer->secret,
 182                         &local_peer->secret_len) == 0) {
 183         fprintf(stderr, "EVP_PKEY_derive() failed\n");
 184         goto end;
 185     }
 186
 187     printf("Shared secret (%s):\n", local_peer->name);
 188     BIO_dump_indent_fp(stdout, local_peer->secret, local_peer->secret_len, 2);
 189     putchar('\n');
 190
 191     ret = 1;
 192 end:
 193     EVP_PKEY_CTX_free(ctx);
 194     EVP_PKEY_free(remote_peer_pubk);
 195     if (ret == 0) {
 196         OPENSSL_clear_free(local_peer->secret, local_peer->secret_len);
 197         local_peer->secret = NULL;
 198     }
 199
 200     return ret;
 201 }
 202
 203 static int keyexch_x25519(int use_kat)
 204 {
 205     int ret = 0;
 206     OSSL_LIB_CTX *libctx = NULL;
 207     PEER_DATA peer1 = {"peer 1"}, peer2 = {"peer 2"};
 208
 209     /*
 210      * Each peer generates its private key and sends its public key
 211      * to the other peer. The private key is stored locally for
 212      * later use.
 213      */
 214     if (keyexch_x25519_before(libctx, use_kat ? peer1_privk_data : NULL,
 215                               &peer1) == 0)
 216         return 0;
 217
 218     if (keyexch_x25519_before(libctx, use_kat ? peer2_privk_data : NULL,
 219                               &peer2) == 0)
 220         return 0;
 221
 222     /*
 223      * Each peer uses the other peer's public key to perform key exchange.
 224      * After this succeeds, each peer has the same secret in its
 225      * PEER_DATA.
 226      */
 227     if (keyexch_x25519_after(libctx, use_kat, &peer1, peer2.pubk_data) == 0)
 228         return 0;
 229
 230     if (keyexch_x25519_after(libctx, use_kat, &peer2, peer1.pubk_data) == 0)
 231         return 0;
 232
 233     /*
 234      * Here we demonstrate the secrets are equal for exposition purposes.
 235      *
 236      * Although in practice you will generally not need to compare secrets
 237      * produced through key exchange, if you do compare cryptographic secrets,
 238      * always do so using a constant-time function such as CRYPTO_memcmp, never
 239      * using memcmp(3).
 240      */
 241     if (CRYPTO_memcmp(peer1.secret, peer2.secret, peer1.secret_len) != 0) {
 242         fprintf(stderr, "Negotiated secrets do not match\n");
 243         goto end;
 244     }
 245
 246     /* If we are doing the KAT, the secret should equal our reference result. */
 247     if (use_kat && CRYPTO_memcmp(peer1.secret, expected_result,
 248                                  peer1.secret_len) != 0) {
 249         fprintf(stderr, "Did not get expected result\n");
 250         goto end;
 251     }
 252
 253     ret = 1;
 254 end:
 255     /* The secrets are sensitive, so ensure they are erased before freeing. */
 256     OPENSSL_clear_free(peer1.secret, peer1.secret_len);
 257     OPENSSL_clear_free(peer2.secret, peer2.secret_len);
 258
 259     EVP_PKEY_free(peer1.privk);
 260     EVP_PKEY_free(peer2.privk);
 261     OSSL_LIB_CTX_free(libctx);
 262     return ret;
 263 }
 264
 265 int main(int argc, char **argv)
 266 {
 267     /* Test X25519 key exchange with known result. */
 268     printf("Key exchange using known answer (deterministic):\n");
 269     if (keyexch_x25519(1) == 0)
 270         return EXIT_FAILURE;
 271
 272     /* Test X25519 key exchange with random keys. */
 273     printf("Key exchange using random keys:\n");
 274     if (keyexch_x25519(0) == 0)
 275         return EXIT_FAILURE;
 276
 277     return EXIT_SUCCESS;
 278 }