1*b077aed3SPierre Pronchery=pod 2*b077aed3SPierre Pronchery 3*b077aed3SPierre Pronchery=head1 NAME 4*b077aed3SPierre Pronchery 5*b077aed3SPierre ProncheryOSSL_ALGORITHM - OpenSSL Core type to define a fetchable algorithm 6*b077aed3SPierre Pronchery 7*b077aed3SPierre Pronchery=head1 SYNOPSIS 8*b077aed3SPierre Pronchery 9*b077aed3SPierre Pronchery #include <openssl/core.h> 10*b077aed3SPierre Pronchery 11*b077aed3SPierre Pronchery typedef struct ossl_algorithm_st OSSL_ALGORITHM; 12*b077aed3SPierre Pronchery struct ossl_algorithm_st { 13*b077aed3SPierre Pronchery const char *algorithm_names; /* key */ 14*b077aed3SPierre Pronchery const char *property_definition; /* key */ 15*b077aed3SPierre Pronchery const OSSL_DISPATCH *implementation; 16*b077aed3SPierre Pronchery const char *algorithm_description; 17*b077aed3SPierre Pronchery }; 18*b077aed3SPierre Pronchery 19*b077aed3SPierre Pronchery=head1 DESCRIPTION 20*b077aed3SPierre Pronchery 21*b077aed3SPierre ProncheryThe B<OSSL_ALGORITHM> type is a I<public structure> that describes an 22*b077aed3SPierre Proncheryalgorithm that a L<provider(7)> provides. Arrays of this type are returned 23*b077aed3SPierre Proncheryby providers on demand from the OpenSSL libraries to describe what 24*b077aed3SPierre Proncheryalgorithms the providers provide implementations of, and with what 25*b077aed3SPierre Proncheryproperties. 26*b077aed3SPierre Pronchery 27*b077aed3SPierre ProncheryArrays of this type must be terminated with a tuple where I<algorithm_names> 28*b077aed3SPierre Proncheryis NULL. 29*b077aed3SPierre Pronchery 30*b077aed3SPierre ProncheryThis type of array is typically returned by the provider's operation querying 31*b077aed3SPierre Proncheryfunction, further described in L<provider-base(7)/Provider Functions>. 32*b077aed3SPierre Pronchery 33*b077aed3SPierre Pronchery=head2 B<OSSL_ALGORITHM> fields 34*b077aed3SPierre Pronchery 35*b077aed3SPierre Pronchery=over 4 36*b077aed3SPierre Pronchery 37*b077aed3SPierre Pronchery=item I<algorithm_names> 38*b077aed3SPierre Pronchery 39*b077aed3SPierre ProncheryThis string is a colon separated set of names / identities, and is used by 40*b077aed3SPierre Proncherythe appropriate fetching functionality (such as L<EVP_CIPHER_fetch(3)>, 41*b077aed3SPierre ProncheryL<EVP_MD_fetch(3)>, etc) to find the desired algorithm. 42*b077aed3SPierre Pronchery 43*b077aed3SPierre ProncheryMultiple names / identities allow a specific algorithm implementation to be 44*b077aed3SPierre Proncheryfetched multiple ways. For example, the RSA algorithm has the following 45*b077aed3SPierre Proncheryknown identities: 46*b077aed3SPierre Pronchery 47*b077aed3SPierre Pronchery=over 4 48*b077aed3SPierre Pronchery 49*b077aed3SPierre Pronchery=item * 50*b077aed3SPierre Pronchery 51*b077aed3SPierre ProncheryC<RSA> 52*b077aed3SPierre Pronchery 53*b077aed3SPierre Pronchery=item * 54*b077aed3SPierre Pronchery 55*b077aed3SPierre ProncheryC<rsaEncryption> 56*b077aed3SPierre Pronchery 57*b077aed3SPierre ProncheryThis is the name of the algorithm's OBJECT IDENTIFIER (OID), as given by the 58*b077aed3SPierre ProncheryL<PKCS#1 RFC's ASN.1 module|https://www.rfc-editor.org/rfc/rfc8017#appendix-C> 59*b077aed3SPierre Pronchery 60*b077aed3SPierre Pronchery=item * 61*b077aed3SPierre Pronchery 62*b077aed3SPierre ProncheryC<1.2.840.113549.1.1.1> 63*b077aed3SPierre Pronchery 64*b077aed3SPierre ProncheryThis is the OID itself for C<rsaEncryption>, in canonical decimal text form. 65*b077aed3SPierre Pronchery 66*b077aed3SPierre Pronchery=back 67*b077aed3SPierre Pronchery 68*b077aed3SPierre ProncheryThe resulting I<algorithm_names> string would look like this: 69*b077aed3SPierre Pronchery 70*b077aed3SPierre Pronchery "RSA:rsaEncryption:1.2.840.113549.1.1.1" 71*b077aed3SPierre Pronchery 72*b077aed3SPierre ProncheryThe OpenSSL libraries use the first of the algorithm names as the main 73*b077aed3SPierre Proncheryor canonical name, on a per algorithm implementation basis. 74*b077aed3SPierre Pronchery 75*b077aed3SPierre ProncherySee the notes L</On the subject of algorithm names> below for a more in 76*b077aed3SPierre Proncherydepth discussion on I<algorithm_names> and how that may interact with 77*b077aed3SPierre Proncheryapplications and libraries, including OpenSSL's. 78*b077aed3SPierre Pronchery 79*b077aed3SPierre Pronchery=item I<property_definition> 80*b077aed3SPierre Pronchery 81*b077aed3SPierre ProncheryThis string defines a set of properties associated with a particular 82*b077aed3SPierre Proncheryalgorithm implementation, and is used by the appropriate fetching 83*b077aed3SPierre Proncheryfunctionality (such as L<EVP_CIPHER_fetch(3)>, L<EVP_MD_fetch(3)>, etc) for 84*b077aed3SPierre Proncherya finer grained lookup of an algorithm implementation, which is useful in 85*b077aed3SPierre Proncherycase multiple implementations of the same algorithm are available. 86*b077aed3SPierre Pronchery 87*b077aed3SPierre ProncherySee L<property(7)> for a further description of the contents of this 88*b077aed3SPierre Proncherystring. 89*b077aed3SPierre Pronchery 90*b077aed3SPierre Pronchery=item I<implementation> 91*b077aed3SPierre Pronchery 92*b077aed3SPierre ProncheryPointer to an L<OSSL_DISPATCH(3)> array, containing pointers to the 93*b077aed3SPierre Proncheryfunctions of a particular algorithm implementation. 94*b077aed3SPierre Pronchery 95*b077aed3SPierre Pronchery=item I<algorithm_description> 96*b077aed3SPierre Pronchery 97*b077aed3SPierre ProncheryA string with a short human-readable description of the algorithm. 98*b077aed3SPierre Pronchery 99*b077aed3SPierre Pronchery=back 100*b077aed3SPierre Pronchery 101*b077aed3SPierre Pronchery=head1 NOTES 102*b077aed3SPierre Pronchery 103*b077aed3SPierre Pronchery=head2 On the subject of algorithm names 104*b077aed3SPierre Pronchery 105*b077aed3SPierre ProncheryProviders may find the need to register ASN.1 OIDs for algorithms using 106*b077aed3SPierre ProncheryL<OBJ_create(3)> (via the B<core_obj_create> upcall described in 107*b077aed3SPierre ProncheryL<provider-base(7)>, because some application or library -- possibly still 108*b077aed3SPierre Proncherythe OpenSSL libraries, even -- use NIDs to look up algorithms. 109*b077aed3SPierre Pronchery 110*b077aed3SPierre ProncheryIn that scenario, you must make sure that the corresponding B<OSSL_ALGORITHM>'s 111*b077aed3SPierre ProncheryI<algorithm_names> includes both the short and the long name. 112*b077aed3SPierre Pronchery 113*b077aed3SPierre ProncheryMost of the time, registering ASN.1 OIDs like this shouldn't be necessary, 114*b077aed3SPierre Proncheryand applications and libraries are encouraged to use L<OBJ_obj2txt(3)> to 115*b077aed3SPierre Proncheryget a text representation of the OID, which may be a long or short name for 116*b077aed3SPierre ProncheryOIDs that are registered, or the OID itself in canonical decimal text form 117*b077aed3SPierre Proncheryif not (or if L<OBJ_obj2txt(3)> is called with I<no_name> = 1). 118*b077aed3SPierre Pronchery 119*b077aed3SPierre ProncheryIt's recommended to make sure that the corresponding B<OSSL_ALGORITHM>'s 120*b077aed3SPierre ProncheryI<algorithm_names> include known names as well as the OID itself in 121*b077aed3SPierre Proncherycanonical decimal text form. That should cover all scenarios. 122*b077aed3SPierre Pronchery 123*b077aed3SPierre Pronchery=begin comment RETURN VALUES doesn't make sense for a manual that only 124*b077aed3SPierre Proncherydescribes a type, but document checkers still want that section, and 125*b077aed3SPierre Proncheryto have more than just the section title. 126*b077aed3SPierre Pronchery 127*b077aed3SPierre Pronchery=head1 RETURN VALUES 128*b077aed3SPierre Pronchery 129*b077aed3SPierre Proncherytxt 130*b077aed3SPierre Pronchery 131*b077aed3SPierre Pronchery=end comment 132*b077aed3SPierre Pronchery 133*b077aed3SPierre Pronchery=head1 SEE ALSO 134*b077aed3SPierre Pronchery 135*b077aed3SPierre ProncheryL<crypto(7)>, L<provider-base(7)>, L<openssl-core.h(7)>, 136*b077aed3SPierre ProncheryL<openssl-core_dispatch.h(7)>, L<OSSL_DISPATCH(3)> 137*b077aed3SPierre Pronchery 138*b077aed3SPierre Pronchery=head1 HISTORY 139*b077aed3SPierre Pronchery 140*b077aed3SPierre ProncheryB<OSSL_ALGORITHM> was added in OpenSSL 3.0 141*b077aed3SPierre Pronchery 142*b077aed3SPierre Pronchery=head1 COPYRIGHT 143*b077aed3SPierre Pronchery 144*b077aed3SPierre ProncheryCopyright 2022 The OpenSSL Project Authors. All Rights Reserved. 145*b077aed3SPierre Pronchery 146*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 147*b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 148*b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 149*b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 150*b077aed3SPierre Pronchery 151*b077aed3SPierre Pronchery=cut 152