crypto.h

Go to the documentation of this file.

/*
 *  OpenVPN -- An application to securely tunnel IP networks
 *             over a single TCP/UDP port, with support for SSL/TLS-based
 *             session authentication and key exchange,
 *             packet encryption, packet authentication, and
 *             packet compression.
 *
 *  Copyright (C) 2002-2026 OpenVPN Inc <sales@openvpn.net>
 *  Copyright (C) 2010-2026 Sentyron B.V. <openvpn@sentyron.com>
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License version 2
 *  as published by the Free Software Foundation.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License along
 *  with this program; if not, see <https://www.gnu.org/licenses/>.
 */
 
#ifndef CRYPTO_H
#define CRYPTO_H
 
#include "crypto_backend.h"
#include "basic.h"
#include "buffer.h"
#include "packet_id.h"
#include "mtu.h"
 
struct sha256_digest
{
    uint8_t digest[SHA256_DIGEST_LENGTH];
};
 
/*
 * Defines a key type and key length for both cipher and HMAC.
 */
struct key_type
{
    const char *cipher; 
    const char *digest; 
};
 
struct key
{
    uint8_t cipher[MAX_CIPHER_KEY_LENGTH];
    uint8_t hmac[MAX_HMAC_KEY_LENGTH];
};
 
struct key_parameters
{
    uint8_t cipher[MAX_CIPHER_KEY_LENGTH];
 
    unsigned int cipher_size;
 
    uint8_t hmac[MAX_HMAC_KEY_LENGTH];
 
    unsigned int hmac_size;
 
    uint16_t epoch;
};
 
void key_parameters_from_key(struct key_parameters *key_params, const struct key *key);
 
struct epoch_key
{
    uint8_t epoch_key[SHA256_DIGEST_LENGTH];
    uint16_t epoch;
};
 
struct key_ctx
{
    cipher_ctx_t *cipher; 
    hmac_ctx_t *hmac;     
    uint8_t implicit_iv[OPENVPN_MAX_IV_LENGTH];
    size_t implicit_iv_len; 
    uint64_t plaintext_blocks;
    uint64_t failed_verifications;
    uint16_t epoch;
};
 
#define KEY_DIRECTION_BIDIRECTIONAL 0 /* same keys for both directions */
#define KEY_DIRECTION_NORMAL        1 /* encrypt with keys[0], decrypt with keys[1] */
#define KEY_DIRECTION_INVERSE       2 /* encrypt with keys[1], decrypt with keys[0] */
 
struct key2
{
    int n;              
    struct key keys[2]; 
};
 
struct key_direction_state
{
    int out_key;   
    int in_key;    
    int need_keys; 
};
 
struct key_ctx_bi
{
    struct key_ctx encrypt; 
    struct key_ctx decrypt; 
    bool initialized;
};
 
struct crypto_options
{
    struct key_ctx_bi key_ctx_bi;
    struct epoch_key epoch_key_send;
 
    struct epoch_key epoch_key_recv;
 
    struct key_type epoch_key_type;
 
    uint64_t aead_usage_limit;
 
    struct key_ctx *epoch_data_keys_future;
 
    uint16_t epoch_data_keys_future_count;
 
    struct key_ctx epoch_retiring_data_receive_key;
    struct packet_id_rec epoch_retiring_key_pid_recv;
 
    struct packet_id packet_id; 
    struct packet_id_persist *pid_persist;
#define CO_PACKET_ID_LONG_FORM         (1u << 0)
#define CO_IGNORE_PACKET_ID            (1u << 1)
#define CO_MUTE_REPLAY_WARNINGS        (1u << 2)
#define CO_USE_TLS_KEY_MATERIAL_EXPORT (1u << 3)
#define CO_RESEND_WKC                  (1u << 4)
#define CO_FORCE_TLSCRYPTV2_COOKIE     (1u << 5)
#define CO_USE_CC_EXIT_NOTIFY          (1u << 6)
#define CO_USE_DYNAMIC_TLS_CRYPT       (1u << 7)
#define CO_EPOCH_DATA_KEY_FORMAT       (1u << 8)
    unsigned int flags; 
};
 
#define CRYPT_ERROR_EXIT(flags, format)          \
    do                                           \
    {                                            \
        msg(flags, "%s: " format, error_prefix); \
        goto error_exit;                         \
    } while (false)
 
#define CRYPT_ERROR(format) CRYPT_ERROR_EXIT(D_CRYPT_ERRORS, format)
#define CRYPT_DROP(format)  CRYPT_ERROR_EXIT(D_MULTI_DROPPED, format)
 
#define OPENVPN_AEAD_MIN_IV_LEN (sizeof(packet_id_type) + 8)
 
#define RKF_MUST_SUCCEED (1 << 0)
#define RKF_INLINE       (1 << 1)
void read_key_file(struct key2 *key2, const char *file, const unsigned int flags);
 
int write_key_file(const int nkeys, const char *filename);
 
void init_key_type(struct key_type *kt, const char *ciphername, const char *authname, bool tls_mode,
                   bool warn);
 
/*
 * Key context functions
 */
 
void init_key_ctx(struct key_ctx *ctx, const struct key_parameters *key, const struct key_type *kt,
                  int enc, const char *prefix);
 
void init_key_bi_ctx_send(struct key_ctx *ctx, const struct key_parameters *key,
                          const struct key_type *kt, const char *name);
 
void init_key_bi_ctx_recv(struct key_ctx *ctx, const struct key_parameters *key,
                          const struct key_type *kt, const char *name);
 
void free_key_ctx(struct key_ctx *ctx);
 
void init_key_ctx_bi(struct key_ctx_bi *ctx, const struct key2 *key2, int key_direction,
                     const struct key_type *kt, const char *name);
 
void free_key_ctx_bi(struct key_ctx_bi *ctx);
 
 
/**************************************************************************/
void openvpn_encrypt(struct buffer *buf, struct buffer work, struct crypto_options *opt);
 
 
bool openvpn_decrypt(struct buffer *buf, struct buffer work, struct crypto_options *opt,
                     const struct frame *frame, const uint8_t *ad_start);
 
bool crypto_check_replay(struct crypto_options *opt, const struct packet_id_net *pin,
                         uint16_t epoch, const char *error_prefix, struct gc_arena *gc);
 
 
size_t calculate_crypto_overhead(const struct key_type *kt, unsigned int pkt_id_size,
                                 bool occ);
 
unsigned int crypto_max_overhead(void);
 
void write_pem_key_file(const char *filename, const char *key_name);
 
bool generate_ephemeral_key(struct buffer *key, const char *pem_name);
 
bool read_pem_key_file(struct buffer *key, const char *pem_name, const char *key_file,
                       bool key_inline);
 
/*
 * Message digest-based pseudo random number generator.
 *
 * If the PRNG was initialised with a certain message digest, uses the digest
 * to calculate the next random number, and prevent depletion of the entropy
 * pool.
 *
 * This PRNG is aimed at IV generation and similar miscellaneous tasks. Use
 * \c rand_bytes() for higher-assurance functionality.
 *
 * Retrieves len bytes of pseudo random data, and places it in output.
 *
 * @param output        Output buffer
 * @param len           Length of the output buffer
 */
void prng_bytes(uint8_t *output, int len);
 
int64_t get_random(void);
 
void print_cipher(const char *cipher);
 
void test_crypto(struct crypto_options *co, const struct frame *f);
 
 
/* key direction functions */
 
void key_direction_state_init(struct key_direction_state *kds, int key_direction);
 
void check_key2(struct key2 *key2);
 
void must_have_n_keys(const char *filename, const char *option, const struct key2 *key2, int n);
 
int ascii2keydirection(msglvl_t msglevel, const char *str);
 
const char *keydirection2ascii(int kd, bool remote, bool humanreadable);
 
/* print keys */
void key2_print(const struct key2 *k, const struct key_type *kt, const char *prefix0,
                const char *prefix1);
 
void crypto_read_openvpn_key(const struct key_type *key_type, struct key_ctx_bi *ctx,
                             const char *key_file, bool key_inline, const int key_direction,
                             const char *key_name, const char *opt_name, struct key2 *keydata);
 
void generate_test_crypto_random_key(const struct key_type *key_type, struct key_ctx_bi *ctx,
                                     const char *key_name);
 
/*
 * Inline functions
 */
 
int memcmp_constant_time(const void *a, const void *b, size_t size);
 
static inline bool
key_ctx_bi_defined(const struct key_ctx_bi *key)
{
    return key->encrypt.cipher || key->encrypt.hmac || key->decrypt.cipher || key->decrypt.hmac;
}
 
const char *print_key_filename(const char *str, bool is_inline);
 
static inline struct key_type
create_kt(const char *cipher, const char *md, const char *optname)
{
    struct key_type kt;
    kt.cipher = cipher;
    kt.digest = md;
 
    if (cipher_defined(kt.cipher) && !cipher_valid(kt.cipher))
    {
        msg(M_WARN, "ERROR: --%s requires %s support.", optname, kt.cipher);
        return (struct key_type){ 0 };
    }
    if (md_defined(kt.digest) && !md_valid(kt.digest))
    {
        msg(M_WARN, "ERROR: --%s requires %s support.", optname, kt.digest);
        return (struct key_type){ 0 };
    }
 
    return kt;
}
 
uint64_t cipher_get_aead_limits(const char *ciphername);
 
static inline bool
cipher_decrypt_verify_fail_exceeded(const struct key_ctx *ctx)
{
    /* Use 2**36, same as DTLS 1.3. Strictly speaking this only guarantees
     * the security margin for packets up to 2^10 blocks (16384 bytes)
     * but we accept slightly lower security bound for the edge
     * of Chacha20-Poly1305 and packets over 16k as MTUs over 16k are
     * extremely rarely used */
    return ctx->failed_verifications > (1ull << 36);
}
 
static inline bool
cipher_decrypt_verify_fail_warn(const struct key_ctx *ctx)
{
    /* Use 2**35, half the amount after which we refuse to decrypt */
    return ctx->failed_verifications > (1ull << 35);
}
 
 
#define AEAD_LIMIT_BLOCKSIZE 16
 
bool check_tls_prf_working(void);
 
static inline bool
aead_usage_limit_reached(const uint64_t limit, const struct key_ctx *key_ctx, int64_t higest_pid)
{
    /* This is the  q + s <=  p^(1/2) * 2^(129/2) - 1 calculation where
     * q is the number of protected messages (highest_pid)
     * s Total plaintext length in all messages (in blocks) */
    return (limit > 0 && key_ctx->plaintext_blocks + (uint64_t)higest_pid > limit);
}
 
#endif /* CRYPTO_H */