relay_crypto_cgo.h

Go to the documentation of this file.

/* Copyright (c) 2001 Matej Pfajfar.
 * Copyright (c) 2001-2004, Roger Dingledine.
 * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
 * Copyright (c) 2007-2025, The Tor Project, Inc. */
/* See LICENSE for licensing information */
 
/**
 * \file relay_crypto_cgo.h
 * \brief Header file for relay_crypto_cgo.c.
 **/
 
#ifndef TOR_RELAY_CRYPTO_CGO_H
#define TOR_RELAY_CRYPTO_CGO_H
 
#include "lib/testsupport/testsupport.h"
 
/**
 * State to implement forward _or_ reverse crypto between a client and a single
 * hop on a circuit.
 *
 * (There needs to be one of these for each direction.
 */
typedef struct cgo_crypt_t cgo_crypt_t;
 
typedef enum {
  CGO_MODE_CLIENT_FORWARD,
  CGO_MODE_CLIENT_BACKWARD,
  CGO_MODE_RELAY_FORWARD,
  CGO_MODE_RELAY_BACKWARD,
} cgo_mode_t;
 
/**
 * Length of a CGO cell tag.
 *
 * This is the value used for authenticated SENDMES.
 **/
#define CGO_TAG_LEN 16
 
struct cell_t;
 
size_t cgo_key_material_len(int aesbits);
cgo_crypt_t * cgo_crypt_new(cgo_mode_t mode, int aesbits,
                      const uint8_t *keys, size_t keylen);
void cgo_crypt_free_(cgo_crypt_t *cgo);
#define cgo_crypt_free(cgo) \
  FREE_AND_NULL(cgo_crypt_t, cgo_crypt_free_, (cgo))
 
void cgo_crypt_relay_forward(cgo_crypt_t *cgo, struct cell_t *cell,
                             const uint8_t **recognized_tag_out);
void cgo_crypt_relay_backward(cgo_crypt_t *cgo, struct cell_t *cell);
void cgo_crypt_relay_originate(cgo_crypt_t *cgo, struct cell_t *cell,
                               const uint8_t **tag_out);
void cgo_crypt_client_forward(cgo_crypt_t *cgo, struct cell_t *cell);
void cgo_crypt_client_originate(cgo_crypt_t *cgo, struct cell_t *cell,
                                const uint8_t **tag_out);
void cgo_crypt_client_backward(cgo_crypt_t *cgo, struct cell_t *cell,
                               const uint8_t **recognized_tag_out);
 
#ifdef RELAY_CRYPTO_CGO_PRIVATE
/* Internal types and definitions for CGO encryption algorithms.
 *
 * Where reasonable, the identifiers here are chosen to match those
 * in the spec (proposal 359), which in turn were chosen to match
 * those in the paper.
 */
 
/**
 * Tweakable block cipher, following the LRW2 construction,
 * instantiated with AES.
 *
 * Any given instance can be used for encryption _or_ decryption,
 * not both.
 */
typedef struct cgo_et_t {
  /**
   * AES block cipher instance
   */
  aes_raw_t *kb;
  /**
   * Polyval instance, with expanded key.
   */
  polyvalx_t ku;
} cgo_et_t;
/**
 * Keyed pseudorandom function, based on polyval and AES-CTR.
 */
typedef struct cgo_prf_t {
  /**
   * AES stream cipher: may be 128, 192, or 256 bits.
   */
  aes_cnt_cipher_t *k;
  /**
   * Polyval instance.
   */
  polyval_key_t b;
} cgo_prf_t;
/**
 * Rugged tweakable pseudorandom permutation, using the UIV+ construction.
 *
 * This is, roughly, a wide-block cipher where _encryption_
 * is non-malleable, but where _decryption_ is malleable.
 *
 * UIV+ is the basis of CGO encryption, though it is used in different
 * ways for each of the relay operations.
 */
typedef struct cgo_uiv_t {
  /**
   * Tweakable block cipher instance.
   */
  cgo_et_t j;
  /**
   * PRF instance.
   */
  cgo_prf_t s;
#ifdef TOR_UNIT_TESTS
  /** Testing only: Copy of keys used to instantiate this UIV.
   * We use this in tests so that we can confirm the correctness
   * of cgo_uiv_update().
   */
  uint8_t uiv_keys_[32 * 2 + 16 * 2];
#endif
} cgo_uiv_t;
/**
 * Length of the 'h' component of uiv_tweak_t.
 */
#define ET_TWEAK_LEN_H 16
/**
 * Length of the 'x_r' component of et_tweak_t.
 */
#define ET_TWEAK_LEN_X_R 493
 
/**
 * Tweak for the UIV+ wide-block cipher.
 */
typedef struct uiv_tweak_t {
  /** H component of the wide-block cipher.
   *
   * This must be ET_TWEAK_LEN_H bytes long.
   **/
  const uint8_t *h;
  /** Additional data component of the wide-block cipher.
   * This value is sent to the cell command (RELAY or RELAY_EARLY)
   * for each relay cell.
   */
  const uint8_t cmd;
} uiv_tweak_t;
/**
 * Tweak for the ET tweakable block cipher.
 */
typedef struct et_tweak_t {
  /** Components from the UIV+ tweak. */
  uiv_tweak_t uiv;
  /**
   * X_R component of the ET tweak.
   *
   * This must be X_R bytes long.
   */
  const uint8_t *x_r;
} et_tweak_t;
 
/** Length of expected input to the PRF. */
#define PRF_INPUT_LEN 16
/** Output length for cgo_prf_xor_t0(). */
#define PRF_T0_DATA_LEN 493
 
/** Length of block handled by uiv instantiation. */
#define UIV_BLOCK_LEN 509
 
STATIC int cgo_et_init(cgo_et_t *et, int aesbits, bool encrypt,
                       const uint8_t *key);
STATIC void cgo_et_set_key(cgo_et_t *et, int aesbits, bool encrypt,
                           const uint8_t *key);
STATIC void cgo_et_encrypt(cgo_et_t *et, const et_tweak_t tweak,
                    uint8_t *block);
STATIC void cgo_et_decrypt(cgo_et_t *et, const et_tweak_t tweak,
                    uint8_t *block);
STATIC void cgo_et_clear(cgo_et_t *et);
 
STATIC int cgo_prf_init(cgo_prf_t *prf, int aesbits,
                        const uint8_t *key);
STATIC void cgo_prf_set_key(cgo_prf_t *prf, int aesbits,
                           const uint8_t *key);
STATIC void cgo_prf_xor_t0(cgo_prf_t *prf, const uint8_t *input,
                          uint8_t *data);
STATIC void cgo_prf_gen_t1(cgo_prf_t *prf, const uint8_t *input,
                   uint8_t *buf, size_t n);
STATIC void cgo_prf_clear(cgo_prf_t *prf);
 
STATIC int cgo_uiv_init(cgo_uiv_t *uiv, int aesbits, bool encrypt,
                        const uint8_t *key);
STATIC void cgo_uiv_encrypt(cgo_uiv_t *uiv, const uiv_tweak_t tweak,
                            uint8_t *cell_body);
STATIC void cgo_uiv_decrypt(cgo_uiv_t *uiv, const uiv_tweak_t tweak,
                            uint8_t *cell_body);
STATIC void cgo_uiv_update(cgo_uiv_t *uiv, int aesbits, bool encrypt,
                           uint8_t *nonce);
STATIC void cgo_uiv_clear(cgo_uiv_t *uiv);
 
struct cgo_crypt_t {
  cgo_uiv_t uiv;
  uint8_t nonce[CGO_TAG_LEN];
  uint8_t tprime[CGO_TAG_LEN];
  /**
   * Stored version of the last incoming cell tag.
   * Only used for cgo_crypt_relay_fwd, where this information is not
   * otherwise available after encryption.
   */
  uint8_t last_tag_relay_fwd[CGO_TAG_LEN];
  uint8_t aes_bytes;
};
#endif
 
#endif /* !defined(TOR_RELAY_CRYPTO_CGO_H) */