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