]>
Commit | Line | Data |
---|---|---|
66ebbb6a LJ |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
a974e64a | 5 | SSL_CTX_set_default_passwd_cb, SSL_CTX_set_default_passwd_cb_userdata, |
0c452abc CH |
6 | SSL_CTX_get_default_passwd_cb, SSL_CTX_get_default_passwd_cb_userdata, |
7 | SSL_set_default_passwd_cb, SSL_set_default_passwd_cb_userdata, | |
8 | SSL_get_default_passwd_cb, SSL_get_default_passwd_cb_userdata - set or | |
9 | get passwd callback for encrypted PEM file handling | |
66ebbb6a LJ |
10 | |
11 | =head1 SYNOPSIS | |
12 | ||
13 | #include <openssl/ssl.h> | |
14 | ||
91da5e77 | 15 | void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx, pem_password_cb *cb); |
66ebbb6a | 16 | void SSL_CTX_set_default_passwd_cb_userdata(SSL_CTX *ctx, void *u); |
91da5e77 | 17 | pem_password_cb *SSL_CTX_get_default_passwd_cb(SSL_CTX *ctx); |
0c452abc CH |
18 | void *SSL_CTX_get_default_passwd_cb_userdata(SSL_CTX *ctx); |
19 | ||
91da5e77 | 20 | void SSL_set_default_passwd_cb(SSL *s, pem_password_cb *cb); |
a974e64a | 21 | void SSL_set_default_passwd_cb_userdata(SSL *s, void *u); |
91da5e77 | 22 | pem_password_cb *SSL_get_default_passwd_cb(SSL *s); |
0c452abc | 23 | void *SSL_get_default_passwd_cb_userdata(SSL *s); |
66ebbb6a | 24 | |
66ebbb6a LJ |
25 | =head1 DESCRIPTION |
26 | ||
27 | SSL_CTX_set_default_passwd_cb() sets the default password callback called | |
28 | when loading/storing a PEM certificate with encryption. | |
29 | ||
c952780c RS |
30 | SSL_CTX_set_default_passwd_cb_userdata() sets a pointer to userdata, B<u>, |
31 | which will be provided to the password callback on invocation. | |
66ebbb6a | 32 | |
0c452abc CH |
33 | SSL_CTX_get_default_passwd_cb() returns a function pointer to the password |
34 | callback currently set in B<ctx>. If no callback was explicitly set, the | |
35 | NULL pointer is returned. | |
36 | ||
c952780c | 37 | SSL_CTX_get_default_passwd_cb_userdata() returns a pointer to the userdata |
0c452abc CH |
38 | currently set in B<ctx>. If no userdata was explicitly set, the NULL pointer |
39 | is returned. | |
40 | ||
41 | SSL_set_default_passwd_cb(), SSL_set_default_passwd_cb_userdata(), | |
42 | SSL_get_default_passwd_cb() and SSL_get_default_passwd_cb_userdata() perform | |
43 | the same function as their SSL_CTX counterparts, but using an SSL object. | |
a974e64a | 44 | |
c952780c | 45 | The password callback, which must be provided by the application, hands back the |
91da5e77 RS |
46 | password to be used during decryption. |
47 | On invocation a pointer to userdata | |
c952780c | 48 | is provided. The function must store the password into the provided buffer |
66ebbb6a LJ |
49 | B<buf> which is of size B<size>. The actual length of the password must |
50 | be returned to the calling function. B<rwflag> indicates whether the | |
51 | callback is used for reading/decryption (rwflag=0) or writing/encryption | |
52 | (rwflag=1). | |
91da5e77 | 53 | For more details, see L<pem_password_cb(3)>. |
66ebbb6a LJ |
54 | |
55 | =head1 NOTES | |
56 | ||
57 | When loading or storing private keys, a password might be supplied to | |
58 | protect the private key. The way this password can be supplied may depend | |
59 | on the application. If only one private key is handled, it can be practical | |
c952780c | 60 | to have the callback handle the password dialog interactively. If several |
66ebbb6a LJ |
61 | keys have to be handled, it can be practical to ask for the password once, |
62 | then keep it in memory and use it several times. In the last case, the | |
c952780c RS |
63 | password could be stored into the userdata storage and the |
64 | callback only returns the password already stored. | |
66ebbb6a | 65 | |
c952780c | 66 | When asking for the password interactively, the callback can use |
a1a63a42 LJ |
67 | B<rwflag> to check, whether an item shall be encrypted (rwflag=1). |
68 | In this case the password dialog may ask for the same password twice | |
69 | for comparison in order to catch typos, that would make decryption | |
70 | impossible. | |
71 | ||
66ebbb6a LJ |
72 | Other items in PEM formatting (certificates) can also be encrypted, it is |
73 | however not usual, as certificate information is considered public. | |
74 | ||
75 | =head1 RETURN VALUES | |
76 | ||
a974e64a | 77 | These functions do not provide diagnostic information. |
66ebbb6a LJ |
78 | |
79 | =head1 EXAMPLES | |
80 | ||
c952780c | 81 | The following example returns the password provided as userdata to the |
66ebbb6a LJ |
82 | calling function. The password is considered to be a '\0' terminated |
83 | string. If the password does not fit into the buffer, the password is | |
84 | truncated. | |
85 | ||
c952780c | 86 | int my_cb(char *buf, int size, int rwflag, void *u) |
66ebbb6a | 87 | { |
2947af32 BB |
88 | strncpy(buf, (char *)u, size); |
89 | buf[size - 1] = '\0'; | |
90 | return strlen(buf); | |
66ebbb6a LJ |
91 | } |
92 | ||
b5c4bbbe JL |
93 | =head1 SEE ALSO |
94 | ||
95 | L<ssl(7)>, | |
96 | L<SSL_CTX_use_certificate(3)> | |
97 | ||
0c452abc CH |
98 | =head1 HISTORY |
99 | ||
100 | SSL_CTX_get_default_passwd_cb(), SSL_CTX_get_default_passwd_cb_userdata(), | |
101 | SSL_set_default_passwd_cb() and SSL_set_default_passwd_cb_userdata() were | |
fc5ecadd | 102 | added in OpenSSL 1.1.0. |
0c452abc | 103 | |
e2f92610 RS |
104 | =head1 COPYRIGHT |
105 | ||
b5c4bbbe | 106 | Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 107 | |
4746f25a | 108 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
109 | this file except in compliance with the License. You can obtain a copy |
110 | in the file LICENSE in the source distribution or at | |
111 | L<https://www.openssl.org/source/license.html>. | |
112 | ||
113 | =cut |