mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-03-31 20:10:45 +08:00
Code Issues Packages Projects Releases Wiki Activity

STORE: Add documentation on search criteria

Browse Source 
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/2688)
This commit is contained in:
Richard Levitte 2017-07-05 19:17:40 +02:00
parent 511e4e0d68
commit 6ab6deccd9
6 changed files with 280 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
doc/man1/storeutl.pod
View File

@ -18,6 +18,12 @@ B<openssl> B<storeutl>
[B<-certs>]
[B<-keys>]
[B<-crls>]
[B<-subject arg>]
[B<-issuer arg>]
[B<-serial arg>]
[B<-alias arg>]
[B<-fingerprint arg>]
[B<-I<digest>>]
B<uri> ...
=head1 DESCRIPTION
@ -73,6 +79,35 @@ Only select the certificates, keys or CRLs from the given URI.
However, if this URI would return a set of names (URIs), those are always
returned.
=item B<-subject arg>
Search for an object having the subject name B<arg>.
The arg must be formatted as I</type0=value0/type1=value1/type2=...>,
characters may be escaped by \ (backslash), no spaces are skipped.
=item B<-issuer arg>
=item B<-serial arg>
Search for an object having the given issuer name and serial number.
These two options I<must> be used together.
The issuer arg must be formatted as I</type0=value0/type1=value1/type2=...>,
characters may be escaped by \ (backslash), no spaces are skipped.
The serial arg may be specified as a decimal value or a hex value if preceded
by B<0x>.
=item B<-alias arg>
Search for an object having the given alias.
=item B<-fingerprint arg>
Search for an object having the given fingerprint.
=item B<-I<digest>>
The digest that was used to compute the fingerprint given with B<-fingerprint>.
=back
=head1 SEE ALSO

23
doc/man3/OSSL_STORE_LOADER.pod
View File

@ -5,12 +5,12 @@
OSSL_STORE_LOADER, OSSL_STORE_LOADER_CTX, OSSL_STORE_LOADER_new,
OSSL_STORE_LOADER_get0_engine, OSSL_STORE_LOADER_get0_scheme,
OSSL_STORE_LOADER_set_open, OSSL_STORE_LOADER_set_ctrl,
OSSL_STORE_LOADER_set_expect,
OSSL_STORE_LOADER_set_expect, OSSL_STORE_LOADER_set_find,
OSSL_STORE_LOADER_set_load, OSSL_STORE_LOADER_set_eof,
OSSL_STORE_LOADER_set_error, OSSL_STORE_LOADER_set_close,
OSSL_STORE_LOADER_free, OSSL_STORE_register_loader,
OSSL_STORE_unregister_loader, OSSL_STORE_open_fn, OSSL_STORE_ctrl_fn,
OSSL_STORE_expect_fn,
OSSL_STORE_expect_fn, OSSL_STORE_find_fn,
OSSL_STORE_load_fn, OSSL_STORE_eof_fn, OSSL_STORE_error_fn,
OSSL_STORE_close_fn - Types and functions to manipulate, register and
unregister STORE loaders for different URI schemes
@ -42,6 +42,10 @@ unregister STORE loaders for different URI schemes
typedef int (*OSSL_STORE_expect_fn)(OSSL_STORE_LOADER_CTX *ctx, int expected);
int OSSL_STORE_LOADER_set_expect(OSSL_STORE_LOADER *loader,
OSSL_STORE_expect_fn expect_function);
typedef int (*OSSL_STORE_find_fn)(OSSL_STORE_LOADER_CTX *ctx,
OSSL_STORE_SEARCH *criteria);
int OSSL_STORE_LOADER_set_find(OSSL_STORE_LOADER *loader,
OSSL_STORE_find_fn find_function);
typedef OSSL_STORE_INFO *(*OSSL_STORE_load_fn)(OSSL_STORE_LOADER_CTX *ctx,
UI_METHOD *ui_method,
void *ui_data);
@ -77,7 +81,8 @@ B<OSSL_STORE_LOADER_CTX> is a type template, to be defined by each loader
using B<struct ossl_store_loader_ctx_st { ... }>.
B<OSSL_STORE_open_fn>, B<OSSL_STORE_ctrl_fn>, B<OSSL_STORE_expect_fn>,
B<OSSL_STORE_load_fn>, B<OSSL_STORE_eof_fn> and B<OSSL_STORE_close_fn>
B<OSSL_STORE_find_fn>, B<OSSL_STORE_load_fn>, B<OSSL_STORE_eof_fn>,
and B<OSSL_STORE_close_fn>
are the function pointer types used within a STORE loader.
The functions pointed at define the functionality of the given loader.
@ -122,6 +127,18 @@ B<expected> may be zero to signify that no specific object type is expected.
This function is expected to return 1 on success, 0 on error.
=item B<OSSL_STORE_find_fn>
This function takes a B<OSSL_STORE_LOADER_CTX> pointer and a
B<OSSL_STORE_SEARCH> search criterion, and is used to tell the loader what
to search for.
When called with the loader context being B<NULL>, this function is expected
to return 1 if the loader supports the criterion, otherwise 0.
When called with the loader context being something other than B<NULL>, this
function is expected to return 1 on success, 0 on error.
=item B<OSSL_STORE_load_fn>
This function takes a B<OSSL_STORE_LOADER_CTX> pointer and a B<UI_METHOD>

193
doc/man3/OSSL_STORE_SEARCH.pod Normal file
View File

@ -0,0 +1,193 @@
=pod
=head1 NAME
OSSL_STORE_SEARCH,
OSSL_STORE_SEARCH_by_name,
OSSL_STORE_SEARCH_by_issuer_serial,
OSSL_STORE_SEARCH_by_key_fingerprint,
OSSL_STORE_SEARCH_by_alias,
OSSL_STORE_SEARCH_free,
OSSL_STORE_SEARCH_get_type,
OSSL_STORE_SEARCH_get0_name,
OSSL_STORE_SEARCH_get0_serial,
OSSL_STORE_SEARCH_get0_bytes,
OSSL_STORE_SEARCH_get0_string,
OSSL_STORE_SEARCH_get0_digest
- Type and functions to create OSSL_STORE search criteria
=head1 SYNOPSIS
#include <openssl/store.h>
typedef struct ossl_store_search_st OSSL_STORE_SEARCH;
OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_name(X509_NAME *name);
OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_issuer_serial(X509_NAME *name,
const ASN1_INTEGER
*serial);
OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_key_fingerprint(const EVP_MD *digest,
const unsigned char
*bytes, int len);
OSSL_STORE_SEARCH *OSSL_STORE_SEARCH_by_alias(const char *alias);
void OSSL_STORE_SEARCH_free(OSSL_STORE_SEARCH *search);
int OSSL_STORE_SEARCH_get_type(const OSSL_STORE_SEARCH *criterion);
X509_NAME *OSSL_STORE_SEARCH_get0_name(OSSL_STORE_SEARCH *criterion);
const ASN1_INTEGER *OSSL_STORE_SEARCH_get0_serial(const OSSL_STORE_SEARCH
*criterion);
const unsigned char *OSSL_STORE_SEARCH_get0_bytes(const OSSL_STORE_SEARCH
*criterion, size_t *length);
const char *OSSL_STORE_SEARCH_get0_string(const OSSL_STORE_SEARCH *criterion);
const EVP_MD *OSSL_STORE_SEARCH_get0_digest(const OSSL_STORE_SEARCH
*criterion);
=head1 DESCRIPTION
These functions are use to specify search criteria to help search for specific
objects through other names than just the URI that's given to OSSL_STORE_open().
For example, this can be useful for an application that has received a URI
and then wants to add on search criteria in a uniform and supported manner.
=head2 Types
B<OSSL_STORE_SEARCH> is an opaque type that holds the constructed search
criterion, and that can be given to an OSSL_STORE context with
OSSL_STORE_find().
The calling application owns the allocation of an B<OSSL_STORE_SEARCH> at all
times, and should therefore be careful not to deallocate it before
OSSL_STORE_close() has been called for the OSSL_STORE context it was given
to.
=head2 Application Functions
OSSL_STORE_SEARCH_by_name(),
OSSL_STORE_SEARCH_by_issuer_serial(),
OSSL_STORE_SEARCH_by_key_fingerprint(),
and OSSL_STORE_SEARCH_by_alias()
are used to create an B<OSSL_STORE_SEARCH> from a subject name, an issuer name
and serial number pair, a key fingerprint, and an alias (for example a friendly
name).
The parameters that are provided are not copied, only referred to in a
criterion, so they must have at least the same life time as the created
B<OSSL_STORE_SEARCH>.
OSSL_STORE_SEARCH_free() is used to free the B<OSSL_STORE_SEARCH>.
=head2 Loader Functions
OSSL_STORE_SEARCH_get_type() returns the criterion type for the given
B<OSSL_STORE_SEARCH>.
OSSL_STORE_SEARCH_get0_name(), OSSL_STORE_SEARCH_get0_serial(),
OSSL_STORE_SEARCH_get0_bytes(), OSSL_STORE_SEARCH_get0_string(),
and OSSL_STORE_SEARCH_get0_digest()
are used to retrieve different data from a B<OSSL_STORE_SEARCH>, as
available for each type.
For more information, see L</SUPPORTED CRITERION TYPES> below.
=head1 SUPPORTED CRITERION TYPES
Currently supported criterion types are:
=over 4
=item OSSL_STORE_SEARCH_BY_NAME
This criterion supports a search by exact match of subject name.
The subject name itself is a B<X509_NAME> pointer.
A criterion of this type is created with OSSL_STORE_SEARCH_by_name(),
and the actual subject name is retrieved with OSSL_STORE_SEARCH_get0_name().
=item OSSL_STORE_SEARCH_BY_ISSUER_SERIAL
This criterion supports a search by exact match of both issuer name and serial
number.
The issuer name itself is a B<X509_NAME> pointer, and the serial number is
a B<ASN1_INTEGER> pointer.
A criterion of this type is created with OSSL_STORE_SEARCH_by_issuer_serial()
and the actual issuer name and serial number are retrieved with
OSSL_STORE_SEARCH_get0_name() and OSSL_STORE_SEARCH_get0_serial().
=item OSSL_STORE_SEARCH_BY_KEY_FINGERPRINT
This criterion supports a search by exact match of key fingerprint.
The key fingerprint in itself is a string of bytes and its length, as
well as the algorithm that was used to compute the fingerprint.
The digest may be left unspecified (NULL), and in that case, the
loader has to decide on a default digest and compare fingerprints
accordingly.
A criterion of this type is created with OSSL_STORE_SEARCH_by_key_fingerprint()
and the actual fingerprint and its length can be retrieved with
OSSL_STORE_SEARCH_get0_bytes().
The digest can be retreived with OSSL_STORE_SEARCH_get0_digest().
=item OSSL_STORE_SEARCH_BY_ALIAS
This criterion supports a search by match of an alias of some kind.
The alias in itself is a simple C string.
A criterion of this type is created with OSSL_STORE_SEARCH_by_alias()
and the actual alias is retrieved with OSSL_STORE_SEARCH_get0_string().
=back
=head1 RETURN VALUES
OSSL_STORE_SEARCH_by_name(),
OSSL_STORE_SEARCH_by_issuer_serial(),
OSSL_STORE_SEARCH_by_key_fingerprint(),
and OSSL_STORE_SEARCH_by_alias()
return a B<OSSL_STORE_SEARCH> pointer on success, or B<NULL> on failure.
OSSL_STORE_SEARCH_get_type() returns the criterion type of the given
B<OSSL_STORE_SEARCH>.
There is no error value.
OSSL_STORE_SEARCH_get0_name() returns a B<X509_NAME> pointer on success,
or B<NULL> when the given B<OSSL_STORE_SEARCH> was of a different type.
OSSL_STORE_SEARCH_get0_serial() returns a B<ASN1_INTEGER> pointer on success,
or B<NULL> when the given B<OSSL_STORE_SEARCH> was of a different type.
OSSL_STORE_SEARCH_get0_bytes() returns a B<const unsigned char> pointer and
sets B<*length> to the strings length on success, or B<NULL> when the given
B<OSSL_STORE_SEARCH> was of a different type.
OSSL_STORE_SEARCH_get0_string() returns a B<const char> pointer on success,
or B<NULL> when the given B<OSSL_STORE_SEARCH> was of a different type.
OSSL_STORE_SEARCH_get0_digest() returns a B<const EVP_MD> pointer.
B<NULL> is a valid value and means that the store loader default will
be used when applicable.
=head1 SEE ALSO
L<ossl_store(7)>, L<OSSL_STORE_supports_search(3)>, L<OSSL_STORE_find(3)>
=head1 HISTORY
B<OSSL_STORE_SEARCH>,
OSSL_STORE_SEARCH_by_name(),
OSSL_STORE_SEARCH_by_issuer_serial(),
OSSL_STORE_SEARCH_by_key_fingerprint(),
OSSL_STORE_SEARCH_by_alias(),
OSSL_STORE_SEARCH_free(),
OSSL_STORE_SEARCH_get_type(),
OSSL_STORE_SEARCH_get0_name(),
OSSL_STORE_SEARCH_get0_serial(),
OSSL_STORE_SEARCH_get0_bytes(),
and OSSL_STORE_SEARCH_get0_string()
were added to OpenSSL 1.1.1.
=head1 COPYRIGHT
Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut

33
doc/man3/OSSL_STORE_expect.pod
View File

@ -2,7 +2,10 @@
=head1 NAME
OSSL_STORE_expect - Specify what object type is expected
OSSL_STORE_expect,
OSSL_STORE_supports_search,
OSSL_STORE_find
- Specify what object type is expected
=head1 SYNOPSIS
@ -10,6 +13,10 @@ OSSL_STORE_expect - Specify what object type is expected
int OSSL_STORE_expect(OSSL_STORE_CTX *ctx, int expected_type);
int OSSL_STORE_supports_search(OSSL_STORE_CTX *ctx, int criterion_type);
int OSSL_STORE_find(OSSL_STORE_CTX *ctx, OSSL_STORE_SEARCH *search);
=head1 DESCRIPTION
OSSL_STORE_expect() helps applications filter what OSSL_STORE_load() returns
@ -20,8 +27,16 @@ that it expects the type B<OSSL_STORE_INFO_CERT>.
All known object types (see L<OSSL_STORE_INFO(3)/SUPPORTED OBJECTS>)
except for B<OSSL_STORE_INFO_NAME> are supported.
OSSL_STORE_expect() I<must> be called before the first OSSL_STORE_load()
of a given session, or it will fail.
OSSL_STORE_find() helps applications specify a criterion for a more fine
grained search of objects.
OSSL_STORE_supports_search() checks if the loader of the given OSSL_STORE
context supports the given search type.
See L<OSSL_STORE_SEARCH/SUPPORED CRITERION TYPES> for information on the
supported search criterion types.
OSSL_STORE_expect() and OSSL_STORE_find I<must> be called before the first
OSSL_STORE_load() of a given session, or they will fail.
=head1 NOTES
@ -37,14 +52,20 @@ method is usually preferable.
OSSL_STORE_expect() returns 1 on success, or 0 on failure.
OSSL_STORE_supports_search() returns 1 if the criterion is supported, or 0
otherwise.
OSSL_STORE_find() returns 1 on success, or 0 on failure.
=head1 SEE ALSO
L<ossl_store(7)>, L<OSSL_STORE_INFO(3)>, L<OSSL_STORE_load(3)>
L<ossl_store(7)>, L<OSSL_STORE_INFO(3)>, L<OSSL_STORE_SEARCH(3)>,
L<OSSL_STORE_load(3)>
=head1 HISTORY
OSSL_STORE_expect()
was added to OpenSSL 1.1.1.
OSSL_STORE_expect(), OSSL_STORE_supports_search() and OSSL_STORE_find()
were added to OpenSSL 1.1.1.
=head1 COPYRIGHT

5
doc/man7/ossl_store.pod
View File

@ -87,11 +87,12 @@ only).
=head1 SEE ALSO
L<OSSL_STORE_INFO(3)>, L<OSSL_STORE_LOADER(3)>,
L<OSSL_STORE_open(3)>, L<OSSL_STORE_expect(3)>
L<OSSL_STORE_open(3)>, L<OSSL_STORE_expect(3)>,
L<OSSL_STORE_SEARCH(3)>
=head1 COPYRIGHT
Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved.
Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy

2
util/private.num
View File

@ -31,9 +31,11 @@ OSSL_STORE_CTX datatype
OSSL_STORE_INFO datatype
OSSL_STORE_LOADER datatype
OSSL_STORE_LOADER_CTX datatype
OSSL_STORE_SEARCH datatype
OSSL_STORE_close_fn datatype
OSSL_STORE_ctrl_fn datatype
OSSL_STORE_expect_fn datatype
OSSL_STORE_find_fn datatype
OSSL_STORE_eof_fn datatype
OSSL_STORE_error_fn datatype
OSSL_STORE_load_fn datatype