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