1 /* 2 * Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved. 3 * 4 * Licensed under the Apache License 2.0 (the "License"). You may not use 5 * this file except in compliance with the License. You can obtain a copy 6 * in the file LICENSE in the source distribution or at 7 * https://www.openssl.org/source/license.html 8 */ 9 10 #ifndef OSSL_INTERNAL_PASSPHRASE_H 11 # define OSSL_INTERNAL_PASSPHRASE_H 12 # pragma once 13 14 /* 15 * This is a passphrase reader bridge with bells and whistles. 16 * 17 * On one hand, an API may wish to offer all sorts of passphrase callback 18 * possibilities to users, or may have to do so for historical reasons. 19 * On the other hand, that same API may have demands from other interfaces, 20 * notably from the libcrypto <-> provider interface, which uses 21 * OSSL_PASSPHRASE_CALLBACK consistently. 22 * 23 * The structure and functions below are the fundaments for bridging one 24 * passphrase callback form to another. 25 * 26 * In addition, extra features are included (this may be a growing list): 27 * 28 * - password caching. This is to be used by APIs where it's likely 29 * that the same passphrase may be asked for more than once, but the 30 * user shouldn't get prompted more than once. For example, this is 31 * useful for OSSL_DECODER, which may have to use a passphrase while 32 * trying to find out what input it has. 33 */ 34 35 /* 36 * Structure to hold whatever the calling user may specify. This structure 37 * is intended to be integrated into API specific structures or to be used 38 * as a local on-stack variable type. Therefore, no functions to allocate 39 * or freed it on the heap is offered. 40 */ 41 struct ossl_passphrase_data_st { 42 enum { 43 is_expl_passphrase = 1, /* Explicit passphrase given by user */ 44 is_pem_password, /* pem_password_cb given by user */ 45 is_ossl_passphrase, /* OSSL_PASSPHRASE_CALLBACK given by user */ 46 is_ui_method /* UI_METHOD given by user */ 47 } type; 48 union { 49 struct { 50 char *passphrase_copy; 51 size_t passphrase_len; 52 } expl_passphrase; 53 54 struct { 55 pem_password_cb *password_cb; 56 void *password_cbarg; 57 } pem_password; 58 59 struct { 60 OSSL_PASSPHRASE_CALLBACK *passphrase_cb; 61 void *passphrase_cbarg; 62 } ossl_passphrase; 63 64 struct { 65 const UI_METHOD *ui_method; 66 void *ui_method_data; 67 } ui_method; 68 } _; 69 70 /*- 71 * Flags section 72 */ 73 74 /* Set to indicate that caching should be done */ 75 unsigned int flag_cache_passphrase:1; 76 77 /*- 78 * Misc section: caches and other 79 */ 80 81 char *cached_passphrase; 82 size_t cached_passphrase_len; 83 }; 84 85 /* Structure manipulation */ 86 87 void ossl_pw_clear_passphrase_data(struct ossl_passphrase_data_st *data); 88 void ossl_pw_clear_passphrase_cache(struct ossl_passphrase_data_st *data); 89 90 int ossl_pw_set_passphrase(struct ossl_passphrase_data_st *data, 91 const unsigned char *passphrase, 92 size_t passphrase_len); 93 int ossl_pw_set_pem_password_cb(struct ossl_passphrase_data_st *data, 94 pem_password_cb *cb, void *cbarg); 95 int ossl_pw_set_ossl_passphrase_cb(struct ossl_passphrase_data_st *data, 96 OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg); 97 int ossl_pw_set_ui_method(struct ossl_passphrase_data_st *data, 98 const UI_METHOD *ui_method, void *ui_data); 99 100 int ossl_pw_enable_passphrase_caching(struct ossl_passphrase_data_st *data); 101 int ossl_pw_disable_passphrase_caching(struct ossl_passphrase_data_st *data); 102 103 /* Central function for direct calls */ 104 105 int ossl_pw_get_passphrase(char *pass, size_t pass_size, size_t *pass_len, 106 const OSSL_PARAM params[], int verify, 107 struct ossl_passphrase_data_st *data); 108 109 /* Callback functions */ 110 111 /* 112 * All of these callback expect that the callback argument is a 113 * struct ossl_passphrase_data_st 114 */ 115 116 pem_password_cb ossl_pw_pem_password; 117 pem_password_cb ossl_pw_pvk_password; 118 /* One callback for encoding (verification prompt) and one for decoding */ 119 OSSL_PASSPHRASE_CALLBACK ossl_pw_passphrase_callback_enc; 120 OSSL_PASSPHRASE_CALLBACK ossl_pw_passphrase_callback_dec; 121 122 #endif 123