xref: /openssl/include/internal/passphrase.h (revision baa88d9d)
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