OSSL_STORE_SEARCH.pod 7.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193
  1. =pod
  2. =head1 NAME
  3. OSSL_STORE_SEARCH,
  4. OSSL_STORE_SEARCH_by_name,
  5. OSSL_STORE_SEARCH_by_issuer_serial,
  6. OSSL_STORE_SEARCH_by_key_fingerprint,
  7. OSSL_STORE_SEARCH_by_alias,
  8. OSSL_STORE_SEARCH_free,
  9. OSSL_STORE_SEARCH_get_type,
  10. OSSL_STORE_SEARCH_get0_name,
  11. OSSL_STORE_SEARCH_get0_serial,
  12. OSSL_STORE_SEARCH_get0_bytes,
  13. OSSL_STORE_SEARCH_get0_string,
  14. OSSL_STORE_SEARCH_get0_digest
  15. - Type and functions to create OSSL_STORE search criteria
  16. =head1 SYNOPSIS
  17. #include <openssl/store.h>
  18. typedef struct ossl_store_search_st OSSL_STORE_SEARCH;
  19. OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_name(X509_NAME *name);
  20. OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_issuer_serial(X509_NAME *name,
  21. const ASN1_INTEGER
  22. *serial);
  23. OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_key_fingerprint(const EVP_MD *digest,
  24. const unsigned char
  25. *bytes, int len);
  26. OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_alias(const char *alias);
  27. void OSSL_STORE_SEARCH_free(OSSL_STORE_SEARCH *search);
  28. int OSSL_STORE_SEARCH_get_type(const OSSL_STORE_SEARCH *criterion);
  29. X509_NAME *OSSL_STORE_SEARCH_get0_name(OSSL_STORE_SEARCH *criterion);
  30. const ASN1_INTEGER *OSSL_STORE_SEARCH_get0_serial(const OSSL_STORE_SEARCH
  31. *criterion);
  32. const unsigned char *OSSL_STORE_SEARCH_get0_bytes(const OSSL_STORE_SEARCH
  33. *criterion, size_t *length);
  34. const char *OSSL_STORE_SEARCH_get0_string(const OSSL_STORE_SEARCH *criterion);
  35. const EVP_MD *OSSL_STORE_SEARCH_get0_digest(const OSSL_STORE_SEARCH
  36. *criterion);
  37. =head1 DESCRIPTION
  38. These functions are used to specify search criteria to help search for specific
  39. objects through other names than just the URI that's given to OSSL_STORE_open().
  40. For example, this can be useful for an application that has received a URI
  41. and then wants to add on search criteria in a uniform and supported manner.
  42. =head2 Types
  43. B<OSSL_STORE_SEARCH> is an opaque type that holds the constructed search
  44. criterion, and that can be given to an OSSL_STORE context with
  45. OSSL_STORE_find().
  46. The calling application owns the allocation of an B<OSSL_STORE_SEARCH> at all
  47. times, and should therefore be careful not to deallocate it before
  48. OSSL_STORE_close() has been called for the OSSL_STORE context it was given
  49. to.
  50. =head2 Application Functions
  51. OSSL_STORE_SEARCH_by_name(),
  52. OSSL_STORE_SEARCH_by_issuer_serial(),
  53. OSSL_STORE_SEARCH_by_key_fingerprint(),
  54. and OSSL_STORE_SEARCH_by_alias()
  55. are used to create an B<OSSL_STORE_SEARCH> from a subject name, an issuer name
  56. and serial number pair, a key fingerprint, and an alias (for example a friendly
  57. name).
  58. The parameters that are provided are not copied, only referred to in a
  59. criterion, so they must have at least the same life time as the created
  60. B<OSSL_STORE_SEARCH>.
  61. OSSL_STORE_SEARCH_free() is used to free the B<OSSL_STORE_SEARCH>.
  62. =head2 Loader Functions
  63. OSSL_STORE_SEARCH_get_type() returns the criterion type for the given
  64. B<OSSL_STORE_SEARCH>.
  65. OSSL_STORE_SEARCH_get0_name(), OSSL_STORE_SEARCH_get0_serial(),
  66. OSSL_STORE_SEARCH_get0_bytes(), OSSL_STORE_SEARCH_get0_string(),
  67. and OSSL_STORE_SEARCH_get0_digest()
  68. are used to retrieve different data from a B<OSSL_STORE_SEARCH>, as
  69. available for each type.
  70. For more information, see L</SUPPORTED CRITERION TYPES> below.
  71. =head1 SUPPORTED CRITERION TYPES
  72. Currently supported criterion types are:
  73. =over 4
  74. =item OSSL_STORE_SEARCH_BY_NAME
  75. This criterion supports a search by exact match of subject name.
  76. The subject name itself is a B<X509_NAME> pointer.
  77. A criterion of this type is created with OSSL_STORE_SEARCH_by_name(),
  78. and the actual subject name is retrieved with OSSL_STORE_SEARCH_get0_name().
  79. =item OSSL_STORE_SEARCH_BY_ISSUER_SERIAL
  80. This criterion supports a search by exact match of both issuer name and serial
  81. number.
  82. The issuer name itself is a B<X509_NAME> pointer, and the serial number is
  83. a B<ASN1_INTEGER> pointer.
  84. A criterion of this type is created with OSSL_STORE_SEARCH_by_issuer_serial()
  85. and the actual issuer name and serial number are retrieved with
  86. OSSL_STORE_SEARCH_get0_name() and OSSL_STORE_SEARCH_get0_serial().
  87. =item OSSL_STORE_SEARCH_BY_KEY_FINGERPRINT
  88. This criterion supports a search by exact match of key fingerprint.
  89. The key fingerprint in itself is a string of bytes and its length, as
  90. well as the algorithm that was used to compute the fingerprint.
  91. The digest may be left unspecified (NULL), and in that case, the
  92. loader has to decide on a default digest and compare fingerprints
  93. accordingly.
  94. A criterion of this type is created with OSSL_STORE_SEARCH_by_key_fingerprint()
  95. and the actual fingerprint and its length can be retrieved with
  96. OSSL_STORE_SEARCH_get0_bytes().
  97. The digest can be retrieved with OSSL_STORE_SEARCH_get0_digest().
  98. =item OSSL_STORE_SEARCH_BY_ALIAS
  99. This criterion supports a search by match of an alias of some kind.
  100. The alias in itself is a simple C string.
  101. A criterion of this type is created with OSSL_STORE_SEARCH_by_alias()
  102. and the actual alias is retrieved with OSSL_STORE_SEARCH_get0_string().
  103. =back
  104. =head1 RETURN VALUES
  105. OSSL_STORE_SEARCH_by_name(),
  106. OSSL_STORE_SEARCH_by_issuer_serial(),
  107. OSSL_STORE_SEARCH_by_key_fingerprint(),
  108. and OSSL_STORE_SEARCH_by_alias()
  109. return a B<OSSL_STORE_SEARCH> pointer on success, or B<NULL> on failure.
  110. OSSL_STORE_SEARCH_get_type() returns the criterion type of the given
  111. B<OSSL_STORE_SEARCH>.
  112. There is no error value.
  113. OSSL_STORE_SEARCH_get0_name() returns a B<X509_NAME> pointer on success,
  114. or B<NULL> when the given B<OSSL_STORE_SEARCH> was of a different type.
  115. OSSL_STORE_SEARCH_get0_serial() returns a B<ASN1_INTEGER> pointer on success,
  116. or B<NULL> when the given B<OSSL_STORE_SEARCH> was of a different type.
  117. OSSL_STORE_SEARCH_get0_bytes() returns a B<const unsigned char> pointer and
  118. sets B<*length> to the strings length on success, or B<NULL> when the given
  119. B<OSSL_STORE_SEARCH> was of a different type.
  120. OSSL_STORE_SEARCH_get0_string() returns a B<const char> pointer on success,
  121. or B<NULL> when the given B<OSSL_STORE_SEARCH> was of a different type.
  122. OSSL_STORE_SEARCH_get0_digest() returns a B<const EVP_MD> pointer.
  123. B<NULL> is a valid value and means that the store loader default will
  124. be used when applicable.
  125. =head1 SEE ALSO
  126. L<ossl_store(7)>, L<OSSL_STORE_supports_search(3)>, L<OSSL_STORE_find(3)>
  127. =head1 HISTORY
  128. B<OSSL_STORE_SEARCH>,
  129. OSSL_STORE_SEARCH_by_name(),
  130. OSSL_STORE_SEARCH_by_issuer_serial(),
  131. OSSL_STORE_SEARCH_by_key_fingerprint(),
  132. OSSL_STORE_SEARCH_by_alias(),
  133. OSSL_STORE_SEARCH_free(),
  134. OSSL_STORE_SEARCH_get_type(),
  135. OSSL_STORE_SEARCH_get0_name(),
  136. OSSL_STORE_SEARCH_get0_serial(),
  137. OSSL_STORE_SEARCH_get0_bytes(),
  138. and OSSL_STORE_SEARCH_get0_string()
  139. were added to OpenSSL 1.1.1.
  140. =head1 COPYRIGHT
  141. Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
  142. Licensed under the OpenSSL license (the "License"). You may not use
  143. this file except in compliance with the License. You can obtain a copy
  144. in the file LICENSE in the source distribution or at
  145. L<https://www.openssl.org/source/license.html>.
  146. =cut