crypto.h (9509B)
1 #ifndef LIBQAEDA_CRYPTO_H_ 2 #define LIBQAEDA_CRYPTO_H_ 3 4 #include <stddef.h> 5 6 #include "base.h" 7 8 #ifndef LQ_DIGEST_LEN 9 /** 10 * \brief Length of result produced by digest algorithm. 11 */ 12 #define LQ_DIGEST_LEN 64 13 #endif 14 15 #ifndef LQ_DIGEST_SIG_LEN 16 /** 17 * \brief Length of digest expected by signature. 18 */ 19 #define LQ_DIGEST_SIG_LEN LQ_DIGEST_LEN 20 #endif 21 22 #ifndef LQ_PUBKEY_LEN 23 /** 24 * \brief Length in bytes of the full publickey representation. 25 */ 26 #define LQ_PUBKEY_LEN 32 27 #endif 28 29 #ifndef LQ_PRIVKEY_LEN 30 /** 31 * \brief Length of the literal private key bytes. 32 */ 33 #define LQ_PRIVKEY_LEN 32 34 #endif 35 36 #ifndef LQ_SIGN_LEN 37 /** 38 * \brief Length of the full signature output. 39 */ 40 #define LQ_SIGN_LEN 64 41 #endif 42 43 #ifndef LQ_FP_LEN 44 /** 45 * \brief Length of the public key fingerprint data. 46 */ 47 #define LQ_FP_LEN 20 48 #endif 49 50 #ifndef LQ_SALT_LEN 51 /** 52 * \brief Length of salt used in signatures. 53 */ 54 #define LQ_SALT_LEN 32 55 #endif 56 57 #ifndef LQ_CRYPTO_BUFLEN 58 /** 59 * \brief Length of internal work buffer for crypto and signature operations. 60 */ 61 #define LQ_CRYPTO_BUFLEN 65536 62 #endif 63 64 #ifndef LQ_CRYPTO_BLOCKSIZE 65 /** 66 * \brief Storage size unit for encrypted data. Encrypted, padded data will be stored in a multiplier of this size. 67 */ 68 #define LQ_CRYPTO_BLOCKSIZE LQ_BLOCKSIZE 69 #endif 70 71 #ifndef LQ_POINT_LEN 72 /** 73 * \brief Size of coordinate point on cryptographic curve. 74 */ 75 #define LQ_POINT_LEN 32 76 #endif 77 78 79 /** 80 * \brief State of private key. 81 */ 82 enum lq_keystate_e { 83 LQ_KEY_INIT = 1, ///< Key contains valid data. 84 LQ_KEY_LOCK = 2, ///< Key is locked with passphrase. 85 }; 86 87 /** 88 * \struct LQPrivKey 89 * 90 * \brief Represents a private key used for message signing. 91 * 92 * \see lq_privatekey_t 93 */ 94 struct lq_privatekey_t { 95 short key_typ; ///< Key type identifier. Unused for now. 96 unsigned char key_state; ///< Key state flags. 97 void *impl; ///< Private key implementation object 98 }; 99 typedef struct lq_privatekey_t LQPrivKey; 100 101 /** 102 * \struct LQPubKey 103 * 104 * \brief Represents a public key, to include with certificates and signatures. 105 * 106 * \see lq_publickey_t 107 * 108 * \todo add serialization 109 */ 110 struct lq_publickey_t { 111 short key_typ; ///< Key type identifier. Unused for now. 112 LQPrivKey *pk; ///< Corresponding private key. Optional, and set to NULL if not available. 113 void *impl; ///< Public key implementation object 114 }; 115 typedef struct lq_publickey_t LQPubKey; 116 117 /** 118 * \struct LQSig 119 * 120 * \brief Represents a cryptographic signature over a message digest. 121 * 122 * The public key must be set in order to use this signature in verification. 123 * 124 * \see lq_signature_t 125 * \see lq_signature_verify 126 * 127 * \todo add serialization 128 * 129 */ 130 struct lq_signature_t { 131 LQPubKey *pubkey; ///< Public key corresponding to the signature, used for verification. Optional (if public key can be recovered from signature) 132 void *impl; ///< Signature implementation object 133 }; 134 typedef struct lq_signature_t LQSig; 135 136 /** 137 * \brief Initialize crypto component internals. 138 * 139 * \return ERR_OK on success. 140 */ 141 int lq_crypto_init(const char *base); 142 143 /** 144 * \brief Free resources used by crypto component internals. 145 **/ 146 void lq_crypto_free(); 147 148 /** 149 * \brief Create a new private key 150 * 151 * If passphrase is not null the passphrase will be encrypted using that passphrase by default. 152 * 153 * \param[in] Passphrase to encrypt key with. If NULL, key will be encrypted with a single 0-byte as passphrase. 154 * \param[in] Passphrase length. Ignored if passphrase is NULL. 155 * \return Pointer to new private key. Freeing the object is the caller's responsibility. 156 * 157 * \see lq_privatekey_free 158 */ 159 LQPrivKey* lq_privatekey_new(const char *passphrase, size_t passphrase_len); 160 161 /** 162 * \brief Load a private key from store. 163 * 164 * If passphrase is not null the passphrase will be encrypted using that passphrase by default. 165 * 166 * \param[in] Passphrase to encrypt key with. If NULL, key will be encrypted with a single 0-byte as passphrase. 167 * \param[in] Passphrase length. Ignored if passphrase is NULL. 168 * \param[in] If not NULL, the private key matching the fingerprint will be loaded. If not, a "default" key will be loaded. 169 * \return Pointer to new private key, if found, or NULL if not. Freeing the object is the caller's responsibility. 170 * 171 * \see lq_privatekey_free 172 */ 173 LQPrivKey* lq_privatekey_load(const char *passphrase, size_t passphrase_len, const char *fingerprint); 174 175 /** 176 * \brief Get the raw private key bytes. 177 * 178 * \param[in] Private key object. 179 * \param[out] Pointer to start of data to write to. The buffer must be at least LQ_PRIVKEY_LEN long. 180 * \return Length of key. If 0, no key could be found. 181 */ 182 size_t lq_privatekey_bytes(LQPrivKey *pk, char **out); 183 184 /** 185 * \brief Create a new public key object. 186 * 187 * \param[in] Uncompressed public key data. 188 * \return Pointer to new public key. Freeing the object is the caller's responsibility. 189 * 190 * \see lq_publickey_free 191 */ 192 LQPubKey* lq_publickey_new(const char *full); 193 194 /** 195 * \brief Create a new public key object from a private key. 196 * 197 * Will set the private key property with the given private key. The private key must be freed independently. 198 * 199 * \param[in] Private key to generate public key from. 200 * \return Pointer to new public key. Freeing the object is the caller's responsibility. 201 * 202 * \see lq_publickey_free 203 */ 204 LQPubKey* lq_publickey_from_privatekey(LQPrivKey *pk); 205 206 /** 207 * \brief Get raw public key bytes. 208 * 209 * \param[in] Public key object. 210 * \param[out] Pointer to start of data. 211 * \return Length of key. If 0, no key could be found. 212 */ 213 size_t lq_publickey_bytes(LQPubKey *pubk, char **out); 214 215 /** 216 * \brief Get the public key fingerprint bytes. 217 * 218 * \param[in] Public key object 219 * \param[out] Pointer to start of data to write to. Buffer must have a capacity of at least LQ_PUBKEY_LEN bytes. 220 * \return Length of fingerprint data. If 0, no fingerprint could be found. 221 */ 222 size_t lq_publickey_fingerprint(LQPubKey *pubk, char **out); 223 224 /** 225 * \brief Compare two public keys. 226 * 227 * \param[in] First public key to compare. 228 * \param[in] Second public key to compare. 229 * \return ERR_OK if the public key objects represent the same public key. 230 */ 231 int lq_publickey_match(LQPubKey *left, LQPubKey *right); 232 233 /** 234 * \brief Encrypt private key in place. 235 * 236 * Must clear sensistive memory. 237 * 238 * \param[in] Private Key object. 239 * \param[in] Passphrase to encrypt private key with. 240 * \param[in] Length of passphrase. 241 * \return ERR_OK if encrypted, ERR_NOOP if already encrypted, or ERR_INIT if encryption fails. 242 */ 243 int lq_privatekey_lock(LQPrivKey *pk, const char *passphrase, size_t passphrase_len); 244 245 /** 246 * \brief Decrypt private key in place. 247 * 248 * \param[in] Private Key object. 249 * \param[in] Passphrase to decrypt private key with. 250 * \param[in] Length of passphrase. 251 * \return ERR_OK if decrypted, ERR_NOOP if not encrypted, or ERR_INIT if decryption fails. 252 */ 253 int lq_privatekey_unlock(LQPrivKey *pk, const char *passphrase, size_t passphrase_len); 254 255 /** 256 * \brief Sign digest data using a private key. 257 * 258 * \param[in] Decrypted private key to use for the signature. 259 * \param[in] Message digest to sign. 260 * \param[in] Length of message to sign. Must be 261 * \param[in] Salt data to use for the signature. Set to NULL if salt is not to be used. If not null, must be LQ_SALT_LEN long. 262 * \return Signature object if signing was successful. Returns NULL if signature failed. It is the caller's responsiblity to free the signature. 263 * 264 * \todo Remove msg_len, as it is inferred by LQ_DIGEST_SIG_LEN 265 * 266 * \see lq_signature_free 267 */ 268 LQSig* lq_privatekey_sign(LQPrivKey *pk, const char *msg, size_t msg_len, const char *salt); 269 270 /** 271 * \brief Create a signature object from byte data. 272 * 273 * \param[in] Signature byte data. 274 * \param[in] Length of data. 275 * \param[in] Public key used in signature. Can be NULL for recoverable signatures. 276 * \return Signature object if parse was successful. Returns NULL if parsing failed. It is the caller's responsiblity to free the signature. 277 * 278 * \todo Remove sig_len, as it is inferred by LQ_SIG_LEN 279 */ 280 LQSig* lq_signature_from_bytes(const char *sig_data, size_t sig_len, LQPubKey *pubkey); 281 282 /** 283 * \brief Get raw signature bytes 284 * 285 * \param[in] Signature object. 286 * \param[out] Pointer to start of data to write to. Buffer must have a capacity of at least LQ_SIG_LEN bytes. 287 * \return Length of signature. If 0, no signature data could be found. 288 */ 289 size_t lq_signature_bytes(LQSig *sig, char **out); 290 291 /** 292 * \brief Verify a signature against a private key and message. 293 * 294 * \param[in] Message digest to sign. 295 * \param[in] Length of message to sign. 296 * \return ERR_OK if signature is verified. 297 * 298 * \todo remove msg_len, as it is inferred by LQ_DIGEST_SIG_LEN 299 */ 300 int lq_signature_verify(LQSig *sig, const char *msg, size_t msg_len); 301 302 /** 303 * \brief Free an allocated public key. 304 * 305 * Does not free the associated private key. 306 * 307 * \param[in] Public key to free. 308 */ 309 void lq_publickey_free(LQPubKey *pubk); 310 311 /** 312 * \brief Free an allocated private key. 313 * 314 * \param[in] Private key to free. 315 */ 316 void lq_privatekey_free(LQPrivKey *pk); 317 318 /** 319 * \brief Free an allocated signature object. 320 * 321 * \param[in] Private key to free. 322 */ 323 void lq_signature_free(LQSig *sig); 324 325 /** 326 * \brief Calculate digest over arbitrary data using the default algorithm. 327 * 328 * \param[in] Data to calculate digest over. 329 * \param[in] Length of data. 330 * \param[out] Output buffer. Buffer must have a capacity of at least LQ_DIGEST_LENGTH bytes. 331 * \return ERR_OK on success. 332 */ 333 int lq_digest(const char *in, size_t in_len, char *out); 334 335 #endif // LIBQAEDA_CRYPTO_H_