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