1 #ifndef MYSQL_PLUGIN_ENCRYPTION_INCLUDED 2 /* Copyright (C) 2014, 2015 Sergei Golubchik and MariaDB 3 4 This program is free software; you can redistribute it and/or modify 5 it under the terms of the GNU General Public License as published by 6 the Free Software Foundation; version 2 of the License. 7 8 This program is distributed in the hope that it will be useful, 9 but WITHOUT ANY WARRANTY; without even the implied warranty of 10 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 11 GNU General Public License for more details. 12 13 You should have received a copy of the GNU General Public License 14 along with this program; if not, write to the Free Software 15 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1335 USA */ 16 17 /** 18 @file 19 20 Encryption Plugin API. 21 22 This file defines the API for server plugins that manage encryption 23 keys for MariaDB on-disk data encryption. 24 */ 25 26 #define MYSQL_PLUGIN_ENCRYPTION_INCLUDED 27 28 #include <mysql/plugin.h> 29 30 #ifdef __cplusplus 31 extern "C" { 32 #endif 33 34 #define MariaDB_ENCRYPTION_INTERFACE_VERSION 0x0300 35 36 /** 37 Encryption plugin descriptor 38 */ 39 struct st_mariadb_encryption 40 { 41 int interface_version; /**< version plugin uses */ 42 43 /*********** KEY MANAGEMENT ********************************************/ 44 45 /** 46 function returning latest key version for a given key id 47 48 @return a version or ENCRYPTION_KEY_VERSION_INVALID to indicate an error. 49 */ 50 unsigned int (*get_latest_key_version)(unsigned int key_id); 51 52 /** 53 function returning a key for a key version 54 55 @param version the requested key version 56 @param key the key will be stored there. Can be NULL - 57 in which case no key will be returned 58 @param key_length in: key buffer size 59 out: the actual length of the key 60 61 This method can be used to query the key length - the required 62 buffer size - by passing key==NULL. 63 64 If the buffer size is less than the key length the content of the 65 key buffer is undefined (the plugin is free to partially fill it with 66 the key data or leave it untouched). 67 68 @return 0 on success, or 69 ENCRYPTION_KEY_VERSION_INVALID, ENCRYPTION_KEY_BUFFER_TOO_SMALL 70 or any other non-zero number for errors 71 */ 72 unsigned int (*get_key)(unsigned int key_id, unsigned int version, 73 unsigned char *key, unsigned int *key_length); 74 75 /*********** ENCRYPTION ************************************************/ 76 /* 77 the caller uses encryption as follows: 78 1. create the encryption context object of the crypt_ctx_size() bytes. 79 2. initialize it with crypt_ctx_init(). 80 3. repeat crypt_ctx_update() until there are no more data to encrypt. 81 4. write the remaining output bytes and destroy the context object 82 with crypt_ctx_finish(). 83 */ 84 85 /** 86 returns the size of the encryption context object in bytes 87 */ 88 unsigned int (*crypt_ctx_size)(unsigned int key_id, unsigned int key_version); 89 /** 90 initializes the encryption context object. 91 */ 92 int (*crypt_ctx_init)(void *ctx, const unsigned char* key, unsigned int klen, 93 const unsigned char* iv, unsigned int ivlen, 94 int flags, unsigned int key_id, 95 unsigned int key_version); 96 /** 97 processes (encrypts or decrypts) a chunk of data 98 99 writes the output to th dst buffer. note that it might write 100 more bytes that were in the input. or less. or none at all. 101 */ 102 int (*crypt_ctx_update)(void *ctx, const unsigned char* src, unsigned int slen, 103 unsigned char* dst, unsigned int* dlen); 104 /** 105 writes the remaining output bytes and destroys the encryption context 106 107 crypt_ctx_update might've cached part of the output in the context, 108 this method will flush these data out. 109 */ 110 int (*crypt_ctx_finish)(void *ctx, unsigned char* dst, unsigned int* dlen); 111 /** 112 returns the length of the encrypted data 113 114 it returns the exact length, given only the source length. 115 which means, this API only supports encryption algorithms where 116 the length of the encrypted data only depends on the length of the 117 input (a.k.a. compression is not supported). 118 */ 119 unsigned int (*encrypted_length)(unsigned int slen, unsigned int key_id, unsigned int key_version); 120 }; 121 122 #ifdef __cplusplus 123 } 124 #endif 125 #endif 126 127