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 */
41struct 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
87void ossl_pw_clear_passphrase_data(struct ossl_passphrase_data_st *data);
88void ossl_pw_clear_passphrase_cache(struct ossl_passphrase_data_st *data);
89
90int ossl_pw_set_passphrase(struct ossl_passphrase_data_st *data,
91                           const unsigned char *passphrase,
92                           size_t passphrase_len);
93int ossl_pw_set_pem_password_cb(struct ossl_passphrase_data_st *data,
94                                pem_password_cb *cb, void *cbarg);
95int ossl_pw_set_ossl_passphrase_cb(struct ossl_passphrase_data_st *data,
96                                   OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg);
97int ossl_pw_set_ui_method(struct ossl_passphrase_data_st *data,
98                          const UI_METHOD *ui_method, void *ui_data);
99
100int ossl_pw_enable_passphrase_caching(struct ossl_passphrase_data_st *data);
101int ossl_pw_disable_passphrase_caching(struct ossl_passphrase_data_st *data);
102
103/* Central function for direct calls */
104
105int 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
116pem_password_cb ossl_pw_pem_password;
117pem_password_cb ossl_pw_pvk_password;
118/* One callback for encoding (verification prompt) and one for decoding */
119OSSL_PASSPHRASE_CALLBACK ossl_pw_passphrase_callback_enc;
120OSSL_PASSPHRASE_CALLBACK ossl_pw_passphrase_callback_dec;
121
122#endif
123