1// SPDX-License-Identifier: GPL-2.0-or-later 2/* 3 * Copyright 2019 Google LLC 4 * Copyright (c) Linux Test Project, 2021 5 */ 6/** 7 * @file tst_af_alg.h 8 * 9 * Library for accessing kernel crypto algorithms via AF_ALG. 10 * 11 * See https://www.kernel.org/doc/html/latest/crypto/userspace-if.html 12 * for more information about AF_ALG. 13 */ 14 15#ifndef TST_AF_ALG_H 16#define TST_AF_ALG_H 17 18#include "lapi/if_alg.h" 19#include <stdbool.h> 20 21/** 22 * Create an AF_ALG algorithm socket. 23 * 24 * This creates an AF_ALG algorithm socket that is initially not bound to any 25 * particular algorithm. On failure, tst_brk() is called with TCONF if the 26 * kernel doesn't support AF_ALG, otherwise TBROK. 27 * 28 * @return a new AF_ALG algorithm socket 29 */ 30int tst_alg_create(void); 31 32/** 33 * Bind an AF_ALG algorithm socket to an algorithm. 34 * 35 * @param algfd An AF_ALG algorithm socket 36 * @param addr A structure which specifies the algorithm to use 37 * 38 * On failure, tst_brk() is called with TCONF if the kernel doesn't support the 39 * specified algorithm, otherwise TBROK. 40 */ 41void tst_alg_bind_addr(int algfd, const struct sockaddr_alg *addr); 42 43/** 44 * Bind an AF_ALG algorithm socket to an algorithm. 45 * 46 * @param algfd An AF_ALG algorithm socket 47 * @param algtype The type of algorithm, such as "hash" or "skcipher" 48 * @param algname The name of the algorithm, such as "sha256" or "xts(aes)" 49 * 50 * Like tst_alg_bind_addr(), except this just takes in the algorithm type and 51 * name. The 'feat' and 'mask' fields are left 0. 52 * 53 * On failure, tst_brk() is called with TCONF if the kernel doesn't support the 54 * specified algorithm, otherwise TBROK. 55 */ 56void tst_alg_bind(int algfd, const char *algtype, const char *algname); 57 58/** 59 * Check for the availability of an algorithm. 60 * 61 * @param algtype The type of algorithm, such as "hash" or "skcipher" 62 * @param algname The name of the algorithm, such as "sha256" or "xts(aes)" 63 * 64 * Return 0 if the algorithm is available, or errno if unavailable. 65 */ 66int tst_try_alg(const char *algtype, const char *algname); 67 68/** 69 * Check for the availability of an algorithm. 70 * 71 * @param algtype The type of algorithm, such as "hash" or "skcipher" 72 * @param algname The name of the algorithm, such as "sha256" or "xts(aes)" 73 * 74 * Return true if the algorithm is available, or false if unavailable 75 * and call tst_res() with TCONF. If another error occurs, tst_brk() is called 76 * with TBROK unless algorithm is disabled due FIPS mode (errno ELIBBAD). 77 */ 78bool tst_have_alg(const char *algtype, const char *algname); 79 80/** 81 * Require the availability of an algorithm. 82 * 83 * @param algtype The type of algorithm, such as "hash" or "skcipher" 84 * @param algname The name of the algorithm, such as "sha256" or "xts(aes)" 85 * 86 * If the algorithm is unavailable, tst_brk() is called with TCONF. 87 * If another error occurs, tst_brk() is called with TBROK. 88 */ 89void tst_require_alg(const char *algtype, const char *algname); 90 91/** 92 * Assign a cryptographic key to an AF_ALG algorithm socket. 93 * 94 * @param algfd An AF_ALG algorithm socket 95 * @param key Pointer to the key. If NULL, a random key is generated. 96 * @param keylen Length of the key in bytes 97 * 98 * On failure, tst_brk() is called with TBROK. 99 */ 100void tst_alg_setkey(int algfd, const uint8_t *key, unsigned int keylen); 101 102/** 103 * Create an AF_ALG request socket for the given algorithm socket. 104 * 105 * @param algfd An AF_ALG algorithm socket 106 * 107 * This creates a request socket for the given algorithm socket, which must be 108 * bound to an algorithm. The same algorithm socket can have many request 109 * sockets used concurrently to perform independent cryptographic operations, 110 * e.g. hashing or encryption/decryption. But the key, if any, that has been 111 * assigned to the algorithm is shared by all request sockets. 112 * 113 * On failure, tst_brk() is called with TBROK. 114 * 115 * @return a new AF_ALG request socket 116 */ 117int tst_alg_accept(int algfd); 118 119/** 120 * Set up an AF_ALG algorithm socket for the given algorithm w/ given key. 121 * 122 * @param algtype The type of algorithm, such as "hash" or "skcipher" 123 * @param algname The name of the algorithm, such as "sha256" or "xts(aes)" 124 * @param key The key to use (optional) 125 * @param keylen The length of the key in bytes (optional) 126 * 127 * This is a helper function which creates an AF_ALG algorithm socket, binds it 128 * to the specified algorithm, and optionally sets a key. If keylen is 0 then 129 * no key is set; otherwise if key is NULL a key of the given length is randomly 130 * generated and set; otherwise the given key is set. 131 * 132 * @return the AF_ALG algorithm socket that was set up 133 */ 134int tst_alg_setup(const char *algtype, const char *algname, 135 const uint8_t *key, unsigned int keylen); 136 137/** 138 * Set up an AF_ALG request socket for the given algorithm w/ given key. 139 * 140 * This is like tst_alg_setup(), except this returns a request fd instead of the 141 * alg fd. The alg fd is closed, so it doesn't need to be kept track of. 142 * 143 * @return the AF_ALG request socket that was set up 144 */ 145int tst_alg_setup_reqfd(const char *algtype, const char *algname, 146 const uint8_t *key, unsigned int keylen); 147 148/** Specification of control data to send to an AF_ALG request socket */ 149struct tst_alg_sendmsg_params { 150 151 /** If true, send ALG_SET_OP with ALG_OP_ENCRYPT */ 152 bool encrypt; 153 154 /** If true, send ALG_SET_OP with ALG_OP_DECRYPT */ 155 bool decrypt; 156 157 /** If ivlen != 0, send ALG_SET_IV */ 158 const uint8_t *iv; 159 unsigned int ivlen; 160 161 /** If assoclen != 0, send ALG_SET_AEAD_ASSOCLEN */ 162 unsigned int assoclen; 163 164 /* Value to use as msghdr::msg_flags */ 165 uint32_t msg_flags; 166}; 167 168/** 169 * Send some data to an AF_ALG request socket, including control data. 170 * @param reqfd An AF_ALG request socket 171 * @param data The data to send 172 * @param datalen The length of data in bytes 173 * @param params Specification of the control data to send 174 * 175 * On failure, tst_brk() is called with TBROK. 176 */ 177void tst_alg_sendmsg(int reqfd, const void *data, size_t datalen, 178 const struct tst_alg_sendmsg_params *params); 179 180#endif /* TST_AF_ALG_H */ 181