2 * Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
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
10 #ifndef OSSL_INTERNAL_PASSPHRASE_H
11 # define OSSL_INTERNAL_PASSPHRASE_H
15 * This is a passphrase reader bridge with bells and whistles.
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.
23 * The structure and functions below are the fundaments for bridging one
24 * passphrase callback form to another.
26 * In addition, extra features are included (this may be a growing list):
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.
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.
41 struct ossl_passphrase_data_st {
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 */
50 char *passphrase_copy;
51 size_t passphrase_len;
55 pem_password_cb *password_cb;
60 OSSL_PASSPHRASE_CALLBACK *passphrase_cb;
61 void *passphrase_cbarg;
65 const UI_METHOD *ui_method;
74 /* Set to indicate that caching should be done */
75 unsigned int flag_cache_passphrase:1;
78 * Misc section: caches and other
81 char *cached_passphrase;
82 size_t cached_passphrase_len;
85 /* Structure manipulation */
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);
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);
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);
103 /* Central function for direct calls */
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);
109 /* Callback functions */
112 * All of these callback expect that the callback argument is a
113 * struct ossl_passphrase_data_st
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;