include/internal/passphrase.h

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