1 // SPDX-License-Identifier: GPL-2.0-or-later 2 /* 3 * Copyright 2019 Google LLC 4 */ 5 /** 6 * @file tst_af_alg.h 7 * 8 * Library for accessing kernel crypto algorithms via AF_ALG. 9 * 10 * See https://www.kernel.org/doc/html/latest/crypto/userspace-if.html 11 * for more information about AF_ALG. 12 */ 13 14 #ifndef TST_AF_ALG_H 15 #define TST_AF_ALG_H 16 17 #include "lapi/if_alg.h" 18 #include <stdbool.h> 19 20 /** 21 * Create an AF_ALG algorithm socket. 22 * 23 * This creates an AF_ALG algorithm socket that is initially not bound to any 24 * particular algorithm. On failure, tst_brk() is called with TCONF if the 25 * kernel doesn't support AF_ALG, otherwise TBROK. 26 * 27 * @return a new AF_ALG algorithm socket 28 */ 29 int tst_alg_create(void); 30 31 /** 32 * Bind an AF_ALG algorithm socket to an algorithm. 33 * 34 * @param algfd An AF_ALG algorithm socket 35 * @param addr A structure which specifies the algorithm to use 36 * 37 * On failure, tst_brk() is called with TCONF if the kernel doesn't support the 38 * specified algorithm, otherwise TBROK. 39 */ 40 void tst_alg_bind_addr(int algfd, const struct sockaddr_alg *addr); 41 42 /** 43 * Bind an AF_ALG algorithm socket to an algorithm. 44 * 45 * @param algfd An AF_ALG algorithm socket 46 * @param algtype The type of algorithm, such as "hash" or "skcipher" 47 * @param algname The name of the algorithm, such as "sha256" or "xts(aes)" 48 * 49 * Like tst_alg_bind_addr(), except this just takes in the algorithm type and 50 * name. The 'feat' and 'mask' fields are left 0. 51 * 52 * On failure, tst_brk() is called with TCONF if the kernel doesn't support the 53 * specified algorithm, otherwise TBROK. 54 */ 55 void tst_alg_bind(int algfd, const char *algtype, const char *algname); 56 57 /** 58 * Check for the availability of an algorithm. 59 * 60 * @param algtype The type of algorithm, such as "hash" or "skcipher" 61 * @param algname The name of the algorithm, such as "sha256" or "xts(aes)" 62 * 63 * Return true if the algorithm is available, or false if unavailable. 64 * If another error occurs, tst_brk() is called with TBROK. 65 */ 66 bool tst_have_alg(const char *algtype, const char *algname); 67 68 /** 69 * Require 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 * If the algorithm is unavailable, tst_brk() is called with TCONF. 75 * If another error occurs, tst_brk() is called with TBROK. 76 */ 77 void tst_require_alg(const char *algtype, const char *algname); 78 79 /** 80 * Assign a cryptographic key to an AF_ALG algorithm socket. 81 * 82 * @param algfd An AF_ALG algorithm socket 83 * @param key Pointer to the key. If NULL, a random key is generated. 84 * @param keylen Length of the key in bytes 85 * 86 * On failure, tst_brk() is called with TBROK. 87 */ 88 void tst_alg_setkey(int algfd, const uint8_t *key, unsigned int keylen); 89 90 /** 91 * Create an AF_ALG request socket for the given algorithm socket. 92 * 93 * @param algfd An AF_ALG algorithm socket 94 * 95 * This creates a request socket for the given algorithm socket, which must be 96 * bound to an algorithm. The same algorithm socket can have many request 97 * sockets used concurrently to perform independent cryptographic operations, 98 * e.g. hashing or encryption/decryption. But the key, if any, that has been 99 * assigned to the algorithm is shared by all request sockets. 100 * 101 * On failure, tst_brk() is called with TBROK. 102 * 103 * @return a new AF_ALG request socket 104 */ 105 int tst_alg_accept(int algfd); 106 107 /** 108 * Set up an AF_ALG algorithm socket for the given algorithm w/ given key. 109 * 110 * @param algtype The type of algorithm, such as "hash" or "skcipher" 111 * @param algname The name of the algorithm, such as "sha256" or "xts(aes)" 112 * @param key The key to use (optional) 113 * @param keylen The length of the key in bytes (optional) 114 * 115 * This is a helper function which creates an AF_ALG algorithm socket, binds it 116 * to the specified algorithm, and optionally sets a key. If keylen is 0 then 117 * no key is set; otherwise if key is NULL a key of the given length is randomly 118 * generated and set; otherwise the given key is set. 119 * 120 * @return the AF_ALG algorithm socket that was set up 121 */ 122 int tst_alg_setup(const char *algtype, const char *algname, 123 const uint8_t *key, unsigned int keylen); 124 125 /** 126 * Set up an AF_ALG request socket for the given algorithm w/ given key. 127 * 128 * This is like tst_alg_setup(), except this returns a request fd instead of the 129 * alg fd. The alg fd is closed, so it doesn't need to be kept track of. 130 * 131 * @return the AF_ALG request socket that was set up 132 */ 133 int tst_alg_setup_reqfd(const char *algtype, const char *algname, 134 const uint8_t *key, unsigned int keylen); 135 136 #endif /* TST_AF_ALG_H */ 137