1=pod 2 3=head1 NAME 4 5ASN1_item_sign, ASN1_item_sign_ex, ASN1_item_sign_ctx, 6ASN1_item_verify, ASN1_item_verify_ex, ASN1_item_verify_ctx - 7ASN1 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 42ASN1_item_sign_ex() is used to sign arbitrary ASN1 data using a data object 43I<data>, the ASN.1 structure I<it>, private key I<pkey> and message digest I<md>. 44The data that is signed is formed by taking the data object in I<data> and 45converting it to der format using the ASN.1 structure I<it>. 46The I<data> that will be signed, and a structure containing the signature may 47both have a copy of the B<X509_ALGOR>. The ASN1_item_sign_ex() function will 48write the correct B<X509_ALGOR> to the structs based on the algorithms and 49parameters that have been set up. If one of I<algor1> or I<algor2> points to the 50B<X509_ALGOR> of the I<data> to be signed, then that B<X509_ALGOR> will first be 51written before the signature is generated. 52Examples of valid values that can be used by the ASN.1 structure I<it> are 53ASN1_ITEM_rptr(X509_CINF), ASN1_ITEM_rptr(X509_REQ_INFO) and 54ASN1_ITEM_rptr(X509_CRL_INFO). 55The B<OSSL_LIB_CTX> specified in I<libctx> and the property query string 56specified in I<props> are used when searching for algorithms in providers. 57The generated signature is set into I<signature>. 58The optional parameter I<id> can be NULL, but can be set for special key types. 59See EVP_PKEY_CTX_set1_id() for further info. The output parameters <algor1> and 60I<algor2> are ignored if they are NULL. 61 62ASN1_item_sign() is similar to ASN1_item_sign_ex() but uses default values of 63NULL for the I<id>, I<libctx> and I<propq>. 64 65ASN1_item_sign_ctx() is similar to ASN1_item_sign() but uses the parameters 66contained in digest context I<ctx>. 67 68ASN1_item_verify_ex() is used to verify the signature I<signature> of internal 69data I<data> using the public key I<pkey> and algorithm identifier I<alg>. 70The data that is verified is formed by taking the data object in I<data> and 71converting it to der format using the ASN.1 structure I<it>. 72The B<OSSL_LIB_CTX> specified in I<libctx> and the property query string 73specified in I<props> are used when searching for algorithms in providers. 74The optional parameter I<id> can be NULL, but can be set for special key types. 75See EVP_PKEY_CTX_set1_id() for further info. 76 77ASN1_item_verify() is similar to ASN1_item_verify_ex() but uses default values of 78NULL for the I<id>, I<libctx> and I<propq>. 79 80ASN1_item_verify_ctx() is similar to ASN1_item_verify() but uses the parameters 81contained in digest context I<ctx>. 82 83 84=head1 RETURN VALUES 85 86All sign functions return the size of the signature in bytes for success and 87zero for failure. 88 89All verify functions return 1 if the signature is valid and 0 if the signature 90check fails. If the signature could not be checked at all because it was 91ill-formed or some other error occurred then -1 is returned. 92 93=head1 EXAMPLES 94 95In the following example a 'MyObject' object is signed using the key contained 96in an EVP_MD_CTX. The signature is written to MyObject.signature. The object is 97then 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); 199err: 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 210L<X509_sign(3)>, 211L<X509_verify(3)> 212 213=head1 HISTORY 214 215ASN1_item_sign_ex() and ASN1_item_verify_ex() were added in OpenSSL 3.0. 216 217=head1 COPYRIGHT 218 219Copyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved. 220 221Licensed under the Apache License 2.0 (the "License"). You may not use 222this file except in compliance with the License. You can obtain a copy 223in the file LICENSE in the source distribution or at 224L<https://www.openssl.org/source/license.html>. 225 226=cut 227