]>
Commit | Line | Data |
---|---|---|
99c166a1 SL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | ASN1_item_sign, ASN1_item_sign_ex, ASN1_item_sign_ctx, | |
6 | ASN1_item_verify, ASN1_item_verify_ex, ASN1_item_verify_ctx - | |
7 | ASN1 sign and verify | |
8 | ||
9 | =head1 SYNOPSIS | |
10 | ||
11 | #include <openssl/x509.h> | |
12 | ||
13 | int ASN1_item_sign_ex(const ASN1_ITEM *it, X509_ALGOR *algor1, | |
14 | X509_ALGOR *algor2, ASN1_BIT_STRING *signature, | |
15 | const void *data, const ASN1_OCTET_STRING *id, | |
16 | EVP_PKEY *pkey, const EVP_MD *md, OSSL_LIB_CTX *libctx, | |
17 | const char *propq); | |
18 | ||
19 | int ASN1_item_sign(const ASN1_ITEM *it, X509_ALGOR *algor1, X509_ALGOR *algor2, | |
20 | ASN1_BIT_STRING *signature, const void *data, | |
21 | EVP_PKEY *pkey, const EVP_MD *md); | |
22 | ||
23 | int ASN1_item_sign_ctx(const ASN1_ITEM *it, X509_ALGOR *algor1, | |
24 | X509_ALGOR *algor2, ASN1_BIT_STRING *signature, | |
25 | const void *data, EVP_MD_CTX *ctx); | |
26 | ||
27 | int ASN1_item_verify_ex(const ASN1_ITEM *it, const X509_ALGOR *alg, | |
28 | const ASN1_BIT_STRING *signature, const void *data, | |
29 | const ASN1_OCTET_STRING *id, EVP_PKEY *pkey, | |
30 | OSSL_LIB_CTX *libctx, const char *propq); | |
31 | ||
32 | int ASN1_item_verify(const ASN1_ITEM *it, const X509_ALGOR *alg, | |
33 | const ASN1_BIT_STRING *signature, const void *data, | |
34 | EVP_PKEY *pkey); | |
35 | ||
36 | int ASN1_item_verify_ctx(const ASN1_ITEM *it, const X509_ALGOR *alg, | |
37 | const ASN1_BIT_STRING *signature, const void *data, | |
38 | EVP_MD_CTX *ctx); | |
39 | ||
40 | =head1 DESCRIPTION | |
41 | ||
42 | ASN1_item_sign_ex() is used to sign arbitrary ASN1 data using a data object | |
43 | I<data>, the ASN.1 structure I<it>, private key I<pkey> and message digest I<md>. | |
44 | The data that is signed is formed by taking the data object in I<data> and | |
45 | converting it to der format using the ASN.1 structure I<it>. | |
46 | The I<data> that will be signed, and a structure containing the signature may | |
47 | both have a copy of the B<X509_ALGOR>. The ASN1_item_sign_ex() function will | |
48 | write the correct B<X509_ALGOR> to the structs based on the algorithms and | |
49 | parameters that have been set up. If one of I<algor1> or I<algor2> points to the | |
50 | B<X509_ALGOR> of the I<data> to be signed, then that B<X509_ALGOR> will first be | |
51 | written before the signature is generated. | |
52 | Examples of valid values that can be used by the ASN.1 structure I<it> are | |
53 | ASN1_ITEM_rptr(X509_CINF), ASN1_ITEM_rptr(X509_REQ_INFO) and | |
54 | ASN1_ITEM_rptr(X509_CRL_INFO). | |
55 | The B<OSSL_LIB_CTX> specified in I<libctx> and the property query string | |
56 | specified in I<props> are used when searching for algorithms in providers. | |
57 | The generated signature is set into I<signature>. | |
58 | The optional parameter I<id> can be NULL, but can be set for special key types. | |
59 | See EVP_PKEY_CTX_set1_id() for further info. The output parameters <algor1> and | |
60 | I<algor2> are ignored if they are NULL. | |
61 | ||
62 | ASN1_item_sign() is similar to ASN1_item_sign_ex() but uses default values of | |
63 | NULL for the I<id>, I<libctx> and I<propq>. | |
64 | ||
e304aa87 | 65 | ASN1_item_sign_ctx() is similar to ASN1_item_sign() but uses the parameters |
99c166a1 SL |
66 | contained in digest context I<ctx>. |
67 | ||
68 | ASN1_item_verify_ex() is used to verify the signature I<signature> of internal | |
69 | data I<data> using the public key I<pkey> and algorithm identifier I<alg>. | |
70 | The data that is verified is formed by taking the data object in I<data> and | |
71 | converting it to der format using the ASN.1 structure I<it>. | |
72 | The B<OSSL_LIB_CTX> specified in I<libctx> and the property query string | |
73 | specified in I<props> are used when searching for algorithms in providers. | |
74 | The optional parameter I<id> can be NULL, but can be set for special key types. | |
75 | See EVP_PKEY_CTX_set1_id() for further info. | |
76 | ||
77 | ASN1_item_verify() is similar to ASN1_item_verify_ex() but uses default values of | |
78 | NULL for the I<id>, I<libctx> and I<propq>. | |
79 | ||
e304aa87 | 80 | ASN1_item_verify_ctx() is similar to ASN1_item_verify() but uses the parameters |
99c166a1 SL |
81 | contained in digest context I<ctx>. |
82 | ||
83 | ||
84 | =head1 RETURN VALUES | |
85 | ||
86 | All sign functions return the size of the signature in bytes for success and | |
87 | zero for failure. | |
88 | ||
89 | All verify functions return 1 if the signature is valid and 0 if the signature | |
90 | check fails. If the signature could not be checked at all because it was | |
91 | ill-formed or some other error occurred then -1 is returned. | |
92 | ||
93 | =head1 EXAMPLES | |
94 | ||
95 | In the following example a 'MyObject' object is signed using the key contained | |
96 | in an EVP_MD_CTX. The signature is written to MyObject.signature. The object is | |
97 | then output in DER format and then loaded back in and verified. | |
98 | ||
99 | #include <openssl/x509.h> | |
100 | #include <openssl/asn1t.h> | |
101 | ||
102 | /* An object used to store the ASN1 data fields that will be signed */ | |
103 | typedef struct MySignInfoObject_st | |
104 | { | |
105 | ASN1_INTEGER *version; | |
106 | X509_ALGOR sig_alg; | |
107 | } MySignInfoObject; | |
108 | ||
109 | DECLARE_ASN1_FUNCTIONS(MySignInfoObject) | |
110 | /* | |
111 | * A higher level object containing the ASN1 fields, signature alg and | |
112 | * output signature. | |
113 | */ | |
114 | typedef struct MyObject_st | |
115 | { | |
116 | MySignInfoObject info; | |
117 | X509_ALGOR sig_alg; | |
118 | ASN1_BIT_STRING *signature; | |
119 | } MyObject; | |
120 | ||
121 | DECLARE_ASN1_FUNCTIONS(MyObject) | |
122 | ||
123 | /* The ASN1 definition of MySignInfoObject */ | |
124 | ASN1_SEQUENCE_cb(MySignInfoObject, NULL) = { | |
125 | ASN1_SIMPLE(MySignInfoObject, version, ASN1_INTEGER) | |
126 | ASN1_EMBED(MySignInfoObject, sig_alg, X509_ALGOR), | |
127 | } ASN1_SEQUENCE_END_cb(MySignInfoObject, MySignInfoObject) | |
128 | ||
129 | /* new, free, d2i & i2d functions for MySignInfoObject */ | |
130 | IMPLEMENT_ASN1_FUNCTIONS(MySignInfoObject) | |
131 | ||
132 | /* The ASN1 definition of MyObject */ | |
133 | ASN1_SEQUENCE_cb(MyObject, NULL) = { | |
134 | ASN1_EMBED(MyObject, info, MySignInfoObject), | |
135 | ASN1_EMBED(MyObject, sig_alg, X509_ALGOR), | |
136 | ASN1_SIMPLE(MyObject, signature, ASN1_BIT_STRING) | |
137 | } ASN1_SEQUENCE_END_cb(MyObject, MyObject) | |
138 | ||
139 | /* new, free, d2i & i2d functions for MyObject */ | |
140 | IMPLEMENT_ASN1_FUNCTIONS(MyObject) | |
141 | ||
142 | int test_asn1_item_sign_verify(const char *mdname, EVP_PKEY *pkey, long version) | |
143 | { | |
144 | int ret = 0; | |
145 | unsigned char *obj_der = NULL; | |
146 | const unsigned char *p = NULL; | |
147 | MyObject *obj = NULL, *loaded_obj = NULL; | |
148 | const ASN1_ITEM *it = ASN1_ITEM_rptr(MySignInfoObject); | |
149 | EVP_MD_CTX *sctx = NULL, *vctx = NULL; | |
150 | int len; | |
151 | ||
152 | /* Create MyObject and set its version */ | |
153 | obj = MyObject_new(); | |
154 | if (obj == NULL) | |
155 | goto err; | |
156 | if (!ASN1_INTEGER_set(obj->info.version, version)) | |
157 | goto err; | |
158 | ||
159 | /* Set the key and digest used for signing */ | |
160 | sctx = EVP_MD_CTX_new(); | |
161 | if (sctx == NULL | |
162 | || !EVP_DigestSignInit_ex(sctx, NULL, mdname, NULL, NULL, pkey)) | |
163 | goto err; | |
164 | ||
165 | /* | |
166 | * it contains the mapping between ASN.1 data and an object MySignInfoObject | |
167 | * obj->info is the 'MySignInfoObject' object that will be | |
168 | * converted into DER data and then signed. | |
169 | * obj->signature will contain the output signature. | |
170 | * obj->sig_alg is filled with the private key's signing algorithm id. | |
171 | * obj->info.sig_alg is another copy of the signing algorithm id that sits | |
172 | * within MyObject. | |
173 | */ | |
174 | len = ASN1_item_sign_ctx(it, &obj->sig_alg, &obj->info.sig_alg, | |
175 | obj->signature, &obj->info, sctx); | |
176 | if (len <= 0 | |
177 | || X509_ALGOR_cmp(&obj->sig_alg, &obj->info.sig_alg) != 0) | |
178 | goto err; | |
179 | ||
180 | /* Output MyObject in der form */ | |
181 | len = i2d_MyObject(obj, &obj_der); | |
182 | if (len <= 0) | |
183 | goto err; | |
184 | ||
185 | /* Set the key and digest used for verifying */ | |
186 | vctx = EVP_MD_CTX_new(); | |
187 | if (vctx == NULL | |
188 | || !EVP_DigestVerifyInit_ex(vctx, NULL, mdname, NULL, NULL, pkey)) | |
189 | goto err; | |
190 | ||
191 | /* Load the der data back into an object */ | |
192 | p = obj_der; | |
193 | loaded_obj = d2i_MyObject(NULL, &p, len); | |
194 | if (loaded_obj == NULL) | |
195 | goto err; | |
196 | /* Verify the loaded object */ | |
197 | ret = ASN1_item_verify_ctx(it, &loaded_obj->sig_alg, loaded_obj->signature, | |
198 | &loaded_obj->info, vctx); | |
199 | err: | |
200 | OPENSSL_free(obj_der); | |
201 | MyObject_free(loaded_obj); | |
202 | MyObject_free(obj); | |
203 | EVP_MD_CTX_free(sctx); | |
204 | EVP_MD_CTX_free(vctx); | |
205 | return ret; | |
206 | } | |
207 | ||
208 | =head1 SEE ALSO | |
209 | ||
210 | L<X509_sign(3)>, | |
211 | L<X509_verify(3)> | |
212 | ||
213 | =head1 HISTORY | |
214 | ||
215 | ASN1_item_sign_ex() and ASN1_item_verify_ex() were added in OpenSSL 3.0. | |
216 | ||
217 | =head1 COPYRIGHT | |
218 | ||
219 | Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved. | |
220 | ||
221 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
222 | this file except in compliance with the License. You can obtain a copy | |
223 | in the file LICENSE in the source distribution or at | |
224 | L<https://www.openssl.org/source/license.html>. | |
225 | ||
226 | =cut |