src/or/hs_intropoint.c

   1 /* Copyright (c) 2016-2017, The Tor Project, Inc. */
   2 /* See LICENSE for licensing information */
   3
   4 /**
   5  * \file hs_intropoint.c
   6  * \brief Implement next generation introductions point functionality
   7  **/
   8
   9 #define HS_INTROPOINT_PRIVATE
  10
  11 #include "or.h"
  12 #include "config.h"
  13 #include "circuitlist.h"
  14 #include "circuituse.h"
  15 #include "config.h"
  16 #include "relay.h"
  17 #include "rendmid.h"
  18 #include "rephist.h"
  19
  20 /* Trunnel */
  21 #include "ed25519_cert.h"
  22 #include "hs/cell_common.h"
  23 #include "hs/cell_establish_intro.h"
  24 #include "hs/cell_introduce1.h"
  25
  26 #include "hs_circuitmap.h"
  27 #include "hs_descriptor.h"
  28 #include "hs_intropoint.h"
  29 #include "hs_common.h"
  30
  31 /** Extract the authentication key from an ESTABLISH_INTRO or INTRODUCE1 using
  32  * the given <b>cell_type</b> from <b>cell</b> and place it in
  33  * <b>auth_key_out</b>. */
  34 STATIC void
  35 get_auth_key_from_cell(ed25519_public_key_t *auth_key_out,
  36                        unsigned int cell_type, const void *cell)
  37 {
  38   size_t auth_key_len;
  39   const uint8_t *key_array;
  40
  41   tor_assert(auth_key_out);
  42   tor_assert(cell);
  43
  44   switch (cell_type) {
  45   case RELAY_COMMAND_ESTABLISH_INTRO:
  46   {
  47     const trn_cell_establish_intro_t *c_cell = cell;
  48     key_array = trn_cell_establish_intro_getconstarray_auth_key(c_cell);
  49     auth_key_len = trn_cell_establish_intro_getlen_auth_key(c_cell);
  50     break;
  51   }
  52   case RELAY_COMMAND_INTRODUCE1:
  53   {
  54     const trn_cell_introduce1_t *c_cell = cell;
  55     key_array = trn_cell_introduce1_getconstarray_auth_key(cell);
  56     auth_key_len = trn_cell_introduce1_getlen_auth_key(c_cell);
  57     break;
  58   }
  59   default:
  60     /* Getting here is really bad as it means we got a unknown cell type from
  61      * this file where every call has an hardcoded value. */
  62     tor_assert(0); /* LCOV_EXCL_LINE */
  63   }
  64   tor_assert(key_array);
  65   tor_assert(auth_key_len == sizeof(auth_key_out->pubkey));
  66   memcpy(auth_key_out->pubkey, key_array, auth_key_len);
  67 }
  68
  69 /** We received an ESTABLISH_INTRO <b>cell</b>. Verify its signature and MAC,
  70  *  given <b>circuit_key_material</b>. Return 0 on success else -1 on error. */
  71 STATIC int
  72 verify_establish_intro_cell(const trn_cell_establish_intro_t *cell,
  73                             const uint8_t *circuit_key_material,
  74                             size_t circuit_key_material_len)
  75 {
  76   /* We only reach this function if the first byte of the cell is 0x02 which
  77    * means that auth_key_type is of ed25519 type, hence this check should
  78    * always pass. See hs_intro_received_establish_intro().  */
  79   if (BUG(cell->auth_key_type != HS_INTRO_AUTH_KEY_TYPE_ED25519)) {
  80     return -1;
  81   }
  82
  83   /* Make sure the auth key length is of the right size for this type. For
  84    * EXTRA safety, we check both the size of the array and the length which
  85    * must be the same. Safety first!*/
  86   if (trn_cell_establish_intro_getlen_auth_key(cell) != ED25519_PUBKEY_LEN ||
  87       trn_cell_establish_intro_get_auth_key_len(cell) != ED25519_PUBKEY_LEN) {
  88     log_fn(LOG_PROTOCOL_WARN, LD_PROTOCOL,
  89            "ESTABLISH_INTRO auth key length is invalid");
  90     return -1;
  91   }
  92
  93   const uint8_t *msg = cell->start_cell;
  94
  95   /* Verify the sig */
  96   {
  97     ed25519_signature_t sig_struct;
  98     const uint8_t *sig_array =
  99       trn_cell_establish_intro_getconstarray_sig(cell);
 100
 101     /* Make sure the signature length is of the right size. For EXTRA safety,
 102      * we check both the size of the array and the length which must be the
 103      * same. Safety first!*/
 104     if (trn_cell_establish_intro_getlen_sig(cell) != sizeof(sig_struct.sig) ||
 105         trn_cell_establish_intro_get_sig_len(cell) != sizeof(sig_struct.sig)) {
 106       log_fn(LOG_PROTOCOL_WARN, LD_PROTOCOL,
 107              "ESTABLISH_INTRO sig len is invalid");
 108       return -1;
 109     }
 110     /* We are now sure that sig_len is of the right size. */
 111     memcpy(sig_struct.sig, sig_array, cell->sig_len);
 112
 113     ed25519_public_key_t auth_key;
 114     get_auth_key_from_cell(&auth_key, RELAY_COMMAND_ESTABLISH_INTRO, cell);
 115
 116     const size_t sig_msg_len = cell->end_sig_fields - msg;
 117     int sig_mismatch = ed25519_checksig_prefixed(&sig_struct,
 118                                                  msg, sig_msg_len,
 119                                                  ESTABLISH_INTRO_SIG_PREFIX,
 120                                                  &auth_key);
 121     if (sig_mismatch) {
 122       log_fn(LOG_PROTOCOL_WARN, LD_PROTOCOL,
 123              "ESTABLISH_INTRO signature not as expected");
 124       return -1;
 125     }
 126   }
 127
 128   /* Verify the MAC */
 129   {
 130     const size_t auth_msg_len = cell->end_mac_fields - msg;
 131     uint8_t mac[DIGEST256_LEN];
 132     crypto_mac_sha3_256(mac, sizeof(mac),
 133                         circuit_key_material, circuit_key_material_len,
 134                         msg, auth_msg_len);
 135     if (tor_memneq(mac, cell->handshake_mac, sizeof(mac))) {
 136       log_fn(LOG_PROTOCOL_WARN, LD_PROTOCOL,
 137              "ESTABLISH_INTRO handshake_auth not as expected");
 138       return -1;
 139     }
 140   }
 141
 142   return 0;
 143 }
 144
 145 /* Send an INTRO_ESTABLISHED cell to <b>circ</b>. */
 146 MOCK_IMPL(int,
 147 hs_intro_send_intro_established_cell,(or_circuit_t *circ))
 148 {
 149   int ret;
 150   uint8_t *encoded_cell = NULL;
 151   ssize_t encoded_len, result_len;
 152   trn_cell_intro_established_t *cell;
 153   trn_cell_extension_t *ext;
 154
 155   tor_assert(circ);
 156
 157   /* Build the cell payload. */
 158   cell = trn_cell_intro_established_new();
 159   ext = trn_cell_extension_new();
 160   trn_cell_extension_set_num(ext, 0);
 161   trn_cell_intro_established_set_extensions(cell, ext);
 162   /* Encode the cell to binary format. */
 163   encoded_len = trn_cell_intro_established_encoded_len(cell);
 164   tor_assert(encoded_len > 0);
 165   encoded_cell = tor_malloc_zero(encoded_len);
 166   result_len = trn_cell_intro_established_encode(encoded_cell, encoded_len,
 167                                                 cell);
 168   tor_assert(encoded_len == result_len);
 169
 170   ret = relay_send_command_from_edge(0, TO_CIRCUIT(circ),
 171                                      RELAY_COMMAND_INTRO_ESTABLISHED,
 172                                      (char *) encoded_cell, encoded_len,
 173                                      NULL);
 174   /* On failure, the above function will close the circuit. */
 175   trn_cell_intro_established_free(cell);
 176   tor_free(encoded_cell);
 177   return ret;
 178 }
 179
 180 /** We received an ESTABLISH_INTRO <b>parsed_cell</b> on <b>circ</b>. It's
 181  *  well-formed and passed our verifications. Perform appropriate actions to
 182  *  establish an intro point. */
 183 static int
 184 handle_verified_establish_intro_cell(or_circuit_t *circ,
 185                                const trn_cell_establish_intro_t *parsed_cell)
 186 {
 187   /* Get the auth key of this intro point */
 188   ed25519_public_key_t auth_key;
 189   get_auth_key_from_cell(&auth_key, RELAY_COMMAND_ESTABLISH_INTRO,
 190                          parsed_cell);
 191
 192   /* Then notify the hidden service that the intro point is established by
 193      sending an INTRO_ESTABLISHED cell */
 194   if (hs_intro_send_intro_established_cell(circ)) {
 195     log_warn(LD_PROTOCOL, "Couldn't send INTRO_ESTABLISHED cell.");
 196     return -1;
 197   }
 198
 199   /* Associate intro point auth key with this circuit. */
 200   hs_circuitmap_register_intro_circ_v3_relay_side(circ, &auth_key);
 201   /* Repurpose this circuit into an intro circuit. */
 202   circuit_change_purpose(TO_CIRCUIT(circ), CIRCUIT_PURPOSE_INTRO_POINT);
 203
 204   return 0;
 205 }
 206
 207 /** We just received an ESTABLISH_INTRO cell in <b>circ</b> with payload in
 208  *  <b>request</b>. Handle it by making <b>circ</b> an intro circuit. Return 0
 209  *  if everything went well, or -1 if there were errors. */
 210 static int
 211 handle_establish_intro(or_circuit_t *circ, const uint8_t *request,
 212                        size_t request_len)
 213 {
 214   int cell_ok, retval = -1;
 215   trn_cell_establish_intro_t *parsed_cell = NULL;
 216
 217   tor_assert(circ);
 218   tor_assert(request);
 219
 220   log_info(LD_REND, "Received an ESTABLISH_INTRO request on circuit %" PRIu32,
 221            circ->p_circ_id);
 222
 223   /* Check that the circuit is in shape to become an intro point */
 224   if (!hs_intro_circuit_is_suitable_for_establish_intro(circ)) {
 225     goto err;
 226   }
 227
 228   /* Parse the cell */
 229   ssize_t parsing_result = trn_cell_establish_intro_parse(&parsed_cell,
 230                                                          request, request_len);
 231   if (parsing_result < 0) {
 232     log_fn(LOG_PROTOCOL_WARN, LD_PROTOCOL,
 233            "Rejecting %s ESTABLISH_INTRO cell.",
 234            parsing_result == -1 ? "invalid" : "truncated");
 235     goto err;
 236   }
 237
 238   cell_ok = verify_establish_intro_cell(parsed_cell,
 239                                         (uint8_t *) circ->rend_circ_nonce,
 240                                         sizeof(circ->rend_circ_nonce));
 241   if (cell_ok < 0) {
 242     log_fn(LOG_PROTOCOL_WARN, LD_PROTOCOL,
 243            "Failed to verify ESTABLISH_INTRO cell.");
 244     goto err;
 245   }
 246
 247   /* This cell is legit. Take the appropriate actions. */
 248   cell_ok = handle_verified_establish_intro_cell(circ, parsed_cell);
 249   if (cell_ok < 0) {
 250     goto err;
 251   }
 252
 253   /* We are done! */
 254   retval = 0;
 255   goto done;
 256
 257  err:
 258   circuit_mark_for_close(TO_CIRCUIT(circ), END_CIRC_REASON_TORPROTOCOL);
 259
 260  done:
 261   trn_cell_establish_intro_free(parsed_cell);
 262   return retval;
 263 }
 264
 265 /* Return True if circuit is suitable for being an intro circuit. */
 266 static int
 267 circuit_is_suitable_intro_point(const or_circuit_t *circ,
 268                                 const char *log_cell_type_str)
 269 {
 270   tor_assert(circ);
 271   tor_assert(log_cell_type_str);
 272
 273   /* Basic circuit state sanity checks. */
 274   if (circ->base_.purpose != CIRCUIT_PURPOSE_OR) {
 275     log_fn(LOG_PROTOCOL_WARN, LD_PROTOCOL,
 276            "Rejecting %s on non-OR circuit.", log_cell_type_str);
 277     return 0;
 278   }
 279
 280   if (circ->base_.n_chan) {
 281     log_fn(LOG_PROTOCOL_WARN, LD_PROTOCOL,
 282            "Rejecting %s on non-edge circuit.", log_cell_type_str);
 283     return 0;
 284   }
 285
 286   /* Suitable. */
 287   return 1;
 288 }
 289
 290 /* Return True if circuit is suitable for being service-side intro circuit. */
 291 int
 292 hs_intro_circuit_is_suitable_for_establish_intro(const or_circuit_t *circ)
 293 {
 294   return circuit_is_suitable_intro_point(circ, "ESTABLISH_INTRO");
 295 }
 296
 297 /* We just received an ESTABLISH_INTRO cell in <b>circ</b>. Figure out of it's
 298  * a legacy or a next gen cell, and pass it to the appropriate handler. */
 299 int
 300 hs_intro_received_establish_intro(or_circuit_t *circ, const uint8_t *request,
 301                             size_t request_len)
 302 {
 303   tor_assert(circ);
 304   tor_assert(request);
 305
 306   if (request_len == 0) {
 307     log_fn(LOG_PROTOCOL_WARN, LD_PROTOCOL, "Empty ESTABLISH_INTRO cell.");
 308     goto err;
 309   }
 310
 311   /* Using the first byte of the cell, figure out the version of
 312    * ESTABLISH_INTRO and pass it to the appropriate cell handler */
 313   const uint8_t first_byte = request[0];
 314   switch (first_byte) {
 315     case HS_INTRO_AUTH_KEY_TYPE_LEGACY0:
 316     case HS_INTRO_AUTH_KEY_TYPE_LEGACY1:
 317       return rend_mid_establish_intro_legacy(circ, request, request_len);
 318     case HS_INTRO_AUTH_KEY_TYPE_ED25519:
 319       return handle_establish_intro(circ, request, request_len);
 320     default:
 321       log_fn(LOG_PROTOCOL_WARN, LD_PROTOCOL,
 322              "Unrecognized AUTH_KEY_TYPE %u.", first_byte);
 323       goto err;
 324   }
 325
 326  err:
 327   circuit_mark_for_close(TO_CIRCUIT(circ), END_CIRC_REASON_TORPROTOCOL);
 328   return -1;
 329 }
 330
 331 /* Send an INTRODUCE_ACK cell onto the circuit <b>circ</b> with the status
 332  * value in <b>status</b>. Depending on the status, it can be ACK or a NACK.
 333  * Return 0 on success else a negative value on error which will close the
 334  * circuit. */
 335 static int
 336 send_introduce_ack_cell(or_circuit_t *circ, hs_intro_ack_status_t status)
 337 {
 338   int ret = -1;
 339   uint8_t *encoded_cell = NULL;
 340   ssize_t encoded_len, result_len;
 341   trn_cell_introduce_ack_t *cell;
 342   trn_cell_extension_t *ext;
 343
 344   tor_assert(circ);
 345
 346   /* Setup the INTRODUCE_ACK cell. We have no extensions so the N_EXTENSIONS
 347    * field is set to 0 by default with a new object. */
 348   cell = trn_cell_introduce_ack_new();
 349   ret = trn_cell_introduce_ack_set_status(cell, status);
 350   /* We have no cell extensions in an INTRODUCE_ACK cell. */
 351   ext = trn_cell_extension_new();
 352   trn_cell_extension_set_num(ext, 0);
 353   trn_cell_introduce_ack_set_extensions(cell, ext);
 354   /* A wrong status is a very bad code flow error as this value is controlled
 355    * by the code in this file and not an external input. This means we use a
 356    * code that is not known by the trunnel ABI. */
 357   tor_assert(ret == 0);
 358   /* Encode the payload. We should never fail to get the encoded length. */
 359   encoded_len = trn_cell_introduce_ack_encoded_len(cell);
 360   tor_assert(encoded_len > 0);
 361   encoded_cell = tor_malloc_zero(encoded_len);
 362   result_len = trn_cell_introduce_ack_encode(encoded_cell, encoded_len, cell);
 363   tor_assert(encoded_len == result_len);
 364
 365   ret = relay_send_command_from_edge(CONTROL_CELL_ID, TO_CIRCUIT(circ),
 366                                      RELAY_COMMAND_INTRODUCE_ACK,
 367                                      (char *) encoded_cell, encoded_len,
 368                                      NULL);
 369   /* On failure, the above function will close the circuit. */
 370   trn_cell_introduce_ack_free(cell);
 371   tor_free(encoded_cell);
 372   return ret;
 373 }
 374
 375 /* Validate a parsed INTRODUCE1 <b>cell</b>. Return 0 if valid or else a
 376  * negative value for an invalid cell that should be NACKed. */
 377 STATIC int
 378 validate_introduce1_parsed_cell(const trn_cell_introduce1_t *cell)
 379 {
 380   size_t legacy_key_id_len;
 381   const uint8_t *legacy_key_id;
 382
 383   tor_assert(cell);
 384
 385   /* This code path SHOULD NEVER be reached if the cell is a legacy type so
 386    * safety net here. The legacy ID must be zeroes in this case. */
 387   legacy_key_id_len = trn_cell_introduce1_getlen_legacy_key_id(cell);
 388   legacy_key_id = trn_cell_introduce1_getconstarray_legacy_key_id(cell);
 389   if (BUG(!tor_mem_is_zero((char *) legacy_key_id, legacy_key_id_len))) {
 390     goto invalid;
 391   }
 392
 393   /* The auth key of an INTRODUCE1 should be of type ed25519 thus leading to a
 394    * known fixed length as well. */
 395   if (trn_cell_introduce1_get_auth_key_type(cell) !=
 396       HS_INTRO_AUTH_KEY_TYPE_ED25519) {
 397     log_fn(LOG_PROTOCOL_WARN, LD_PROTOCOL,
 398            "Rejecting invalid INTRODUCE1 cell auth key type. "
 399            "Responding with NACK.");
 400     goto invalid;
 401   }
 402   if (trn_cell_introduce1_get_auth_key_len(cell) != ED25519_PUBKEY_LEN ||
 403       trn_cell_introduce1_getlen_auth_key(cell) != ED25519_PUBKEY_LEN) {
 404     log_fn(LOG_PROTOCOL_WARN, LD_PROTOCOL,
 405            "Rejecting invalid INTRODUCE1 cell auth key length. "
 406            "Responding with NACK.");
 407     goto invalid;
 408   }
 409   if (trn_cell_introduce1_getlen_encrypted(cell) == 0) {
 410     log_fn(LOG_PROTOCOL_WARN, LD_PROTOCOL,
 411            "Rejecting invalid INTRODUCE1 cell encrypted length. "
 412            "Responding with NACK.");
 413     goto invalid;
 414   }
 415
 416   return 0;
 417  invalid:
 418   return -1;
 419 }
 420
 421 /* We just received a non legacy INTRODUCE1 cell on <b>client_circ</b> with
 422  * the payload in <b>request</b> of size <b>request_len</b>. Return 0 if
 423  * everything went well, or -1 if an error occured. This function is in charge
 424  * of sending back an INTRODUCE_ACK cell and will close client_circ on error.
 425  */
 426 STATIC int
 427 handle_introduce1(or_circuit_t *client_circ, const uint8_t *request,
 428                   size_t request_len)
 429 {
 430   int ret = -1;
 431   or_circuit_t *service_circ;
 432   trn_cell_introduce1_t *parsed_cell;
 433   hs_intro_ack_status_t status = HS_INTRO_ACK_STATUS_SUCCESS;
 434
 435   tor_assert(client_circ);
 436   tor_assert(request);
 437
 438   /* Parse cell. Note that we can only parse the non encrypted section for
 439    * which we'll use the authentication key to find the service introduction
 440    * circuit and relay the cell on it. */
 441   ssize_t cell_size = trn_cell_introduce1_parse(&parsed_cell, request,
 442                                                request_len);
 443   if (cell_size < 0) {
 444     log_fn(LOG_PROTOCOL_WARN, LD_PROTOCOL,
 445            "Rejecting %s INTRODUCE1 cell. Responding with NACK.",
 446            cell_size == -1 ? "invalid" : "truncated");
 447     /* Inform client that the INTRODUCE1 has a bad format. */
 448     status = HS_INTRO_ACK_STATUS_BAD_FORMAT;
 449     goto send_ack;
 450   }
 451
 452   /* Once parsed validate the cell format. */
 453   if (validate_introduce1_parsed_cell(parsed_cell) < 0) {
 454     /* Inform client that the INTRODUCE1 has bad format. */
 455     status = HS_INTRO_ACK_STATUS_BAD_FORMAT;
 456     goto send_ack;
 457   }
 458
 459   /* Find introduction circuit through our circuit map. */
 460   {
 461     ed25519_public_key_t auth_key;
 462     get_auth_key_from_cell(&auth_key, RELAY_COMMAND_INTRODUCE1, parsed_cell);
 463     service_circ = hs_circuitmap_get_intro_circ_v3_relay_side(&auth_key);
 464     if (service_circ == NULL) {
 465       char b64_key[ED25519_BASE64_LEN + 1];
 466       ed25519_public_to_base64(b64_key, &auth_key);
 467       log_info(LD_REND, "No intro circuit found for INTRODUCE1 cell "
 468                         "with auth key %s from circuit %" PRIu32 ". "
 469                         "Responding with NACK.",
 470                safe_str(b64_key), client_circ->p_circ_id);
 471       /* Inform the client that we don't know the requested service ID. */
 472       status = HS_INTRO_ACK_STATUS_UNKNOWN_ID;
 473       goto send_ack;
 474     }
 475   }
 476
 477   /* Relay the cell to the service on its intro circuit with an INTRODUCE2
 478    * cell which is the same exact payload. */
 479   if (relay_send_command_from_edge(CONTROL_CELL_ID, TO_CIRCUIT(service_circ),
 480                                    RELAY_COMMAND_INTRODUCE2,
 481                                    (char *) request, request_len, NULL)) {
 482     log_warn(LD_PROTOCOL, "Unable to send INTRODUCE2 cell to the service.");
 483     /* Inform the client that we can't relay the cell. */
 484     status = HS_INTRO_ACK_STATUS_CANT_RELAY;
 485     goto send_ack;
 486   }
 487
 488   /* Success! Send an INTRODUCE_ACK success status onto the client circuit. */
 489   status = HS_INTRO_ACK_STATUS_SUCCESS;
 490   ret = 0;
 491
 492  send_ack:
 493   /* Send INTRODUCE_ACK or INTRODUCE_NACK to client */
 494   if (send_introduce_ack_cell(client_circ, status) < 0) {
 495     log_warn(LD_PROTOCOL, "Unable to send an INTRODUCE ACK status %d "
 496                           "to client.", status);
 497     /* Circuit has been closed on failure of transmission. */
 498     goto done;
 499   }
 500   if (status != HS_INTRO_ACK_STATUS_SUCCESS) {
 501     /* We just sent a NACK that is a non success status code so close the
 502      * circuit because it's not useful to keep it open. Remember, a client can
 503      * only send one INTRODUCE1 cell on a circuit. */
 504     circuit_mark_for_close(TO_CIRCUIT(client_circ), END_CIRC_REASON_INTERNAL);
 505   }
 506  done:
 507   trn_cell_introduce1_free(parsed_cell);
 508   return ret;
 509 }
 510
 511 /* Identify if the encoded cell we just received is a legacy one or not. The
 512  * <b>request</b> should be at least DIGEST_LEN bytes long. */
 513 STATIC int
 514 introduce1_cell_is_legacy(const uint8_t *request)
 515 {
 516   tor_assert(request);
 517
 518   /* If the first 20 bytes of the cell (DIGEST_LEN) are NOT zeroes, it
 519    * indicates a legacy cell (v2). */
 520   if (!tor_mem_is_zero((const char *) request, DIGEST_LEN)) {
 521     /* Legacy cell. */
 522     return 1;
 523   }
 524   /* Not a legacy cell. */
 525   return 0;
 526 }
 527
 528 /* Return true iff the circuit <b>circ</b> is suitable for receiving an
 529  * INTRODUCE1 cell. */
 530 STATIC int
 531 circuit_is_suitable_for_introduce1(const or_circuit_t *circ)
 532 {
 533   tor_assert(circ);
 534
 535   /* Is this circuit an intro point circuit? */
 536   if (!circuit_is_suitable_intro_point(circ, "INTRODUCE1")) {
 537     return 0;
 538   }
 539
 540   if (circ->already_received_introduce1) {
 541     log_fn(LOG_PROTOCOL_WARN, LD_REND,
 542            "Blocking multiple introductions on the same circuit. "
 543            "Someone might be trying to attack a hidden service through "
 544            "this relay.");
 545     return 0;
 546   }
 547
 548   return 1;
 549 }
 550
 551 /* We just received an INTRODUCE1 cell on <b>circ</b>. Figure out which type
 552  * it is and pass it to the appropriate handler. Return 0 on success else a
 553  * negative value and the circuit is closed. */
 554 int
 555 hs_intro_received_introduce1(or_circuit_t *circ, const uint8_t *request,
 556                              size_t request_len)
 557 {
 558   int ret;
 559
 560   tor_assert(circ);
 561   tor_assert(request);
 562
 563   /* A cell that can't hold a DIGEST_LEN is invalid as we need to check if
 564    * it's a legacy cell or not using the first DIGEST_LEN bytes. */
 565   if (request_len < DIGEST_LEN) {
 566     log_fn(LOG_PROTOCOL_WARN, LD_PROTOCOL, "Invalid INTRODUCE1 cell length.");
 567     goto err;
 568   }
 569
 570   /* Make sure we have a circuit that can have an INTRODUCE1 cell on it. */
 571   if (!circuit_is_suitable_for_introduce1(circ)) {
 572     /* We do not send a NACK because the circuit is not suitable for any kind
 573      * of response or transmission as it's a violation of the protocol. */
 574     goto err;
 575   }
 576   /* Mark the circuit that we got this cell. None are allowed after this as a
 577    * DoS mitigation since one circuit with one client can hammer a service. */
 578   circ->already_received_introduce1 = 1;
 579
 580   /* We are sure here to have at least DIGEST_LEN bytes. */
 581   if (introduce1_cell_is_legacy(request)) {
 582     /* Handle a legacy cell. */
 583     ret = rend_mid_introduce_legacy(circ, request, request_len);
 584   } else {
 585     /* Handle a non legacy cell. */
 586     ret = handle_introduce1(circ, request, request_len);
 587   }
 588   return ret;
 589
 590  err:
 591   circuit_mark_for_close(TO_CIRCUIT(circ), END_CIRC_REASON_TORPROTOCOL);
 592   return -1;
 593 }
 594
 595 /* Clear memory allocated by the given intropoint object ip (but don't free the
 596  * object itself). */
 597 void
 598 hs_intropoint_clear(hs_intropoint_t *ip)
 599 {
 600   if (ip == NULL) {
 601     return;
 602   }
 603   tor_cert_free(ip->auth_key_cert);
 604   SMARTLIST_FOREACH(ip->link_specifiers, hs_desc_link_specifier_t *, ls,
 605                     hs_desc_link_specifier_free(ls));
 606   smartlist_free(ip->link_specifiers);
 607   memset(ip, 0, sizeof(hs_intropoint_t));
 608 }
 609