wbrawner/openssl
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

DOC: Add documentation related to X509_LOOKUPs

Browse source 
Most of all, the base X509_LOOKUP functionality is now documented.
Furthermore, the names X509_LOOKUP_METHOD and X509_STORE are added for
reference.

Some functions were moved from X509_LOOKUP_meth_new.pod

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/11120)
This commit is contained in:
Richard Levitte 2020-01-31 15:35:46 +01:00
parent ded6741604
commit 8a7b7c9a79
4 changed files with 209 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

179
doc/man3/X509_LOOKUP.pod Normal file
View file

@ -0,0 +1,179 @@
=pod
=head1 NAME
X509_LOOKUP, X509_LOOKUP_TYPE,
X509_LOOKUP_new, X509_LOOKUP_free, X509_LOOKUP_init,
X509_LOOKUP_shutdown,
X509_LOOKUP_set_method_data, X509_LOOKUP_get_method_data,
X509_LOOKUP_ctrl,
X509_LOOKUP_load_file, X509_LOOKUP_add_dir,
X509_LOOKUP_get_store, X509_LOOKUP_by_subject,
X509_LOOKUP_by_issuer_serial, X509_LOOKUP_by_fingerprint,
X509_LOOKUP_by_alias
- OpenSSL certificate lookup mechanisms
=head1 SYNOPSIS
#include <openssl/x509_vfy.h>
typedef x509_lookup_st X509_LOOKUP;
typedef enum X509_LOOKUP_TYPE;
X509_LOOKUP *X509_LOOKUP_new(X509_LOOKUP_METHOD *method);
int X509_LOOKUP_init(X509_LOOKUP *ctx);
int X509_LOOKUP_shutdown(X509_LOOKUP *ctx);
void X509_LOOKUP_free(X509_LOOKUP *ctx);
int X509_LOOKUP_set_method_data(X509_LOOKUP *ctx, void *data);
void *X509_LOOKUP_get_method_data(const X509_LOOKUP *ctx);
int X509_LOOKUP_ctrl(X509_LOOKUP *ctx, int cmd, const char *argc,
long argl, char **ret);
int X509_LOOKUP_load_file(X509_LOOKUP *ctx, char *name, long type);
int X509_LOOKUP_add_dir(X509_LOOKUP *ctx, char *name, long type);
X509_STORE *X509_LOOKUP_get_store(const X509_LOOKUP *ctx);
int X509_LOOKUP_by_subject(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type,
X509_NAME *name, X509_OBJECT *ret);
int X509_LOOKUP_by_issuer_serial(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type,
X509_NAME *name, ASN1_INTEGER *serial,
X509_OBJECT *ret);
int X509_LOOKUP_by_fingerprint(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type,
const unsigned char *bytes, int len,
X509_OBJECT *ret);
int X509_LOOKUP_by_alias(X509_LOOKUP *ctx, X509_LOOKUP_TYPE type,
const char *str, int len, X509_OBJECT *ret);
=head1 DESCRIPTION
The B<X509_LOOKUP> structure holds the information needed to look up
certificates and CRLs according to an associated L<X509_LOOKUP_METHOD(3)>.
Multiple B<X509_LOOKUP> instances can be added to an L<X509_STORE(3)>
to enable lookup in that store.
X509_LOOKUP_new() creates a new B<X509_LOOKUP> using the given lookup
I<method>.
It can also be created by calling L<X509_STORE_add_lookup(3)>, which
will associate a B<X509_STORE> with the lookup mechanism.
X509_LOOKUP_init() initializes the internal state and resources as
needed by the given B<X509_LOOKUP> to do its work.
X509_LOOKUP_shutdown() tears down the internal state and resources of
the given B<X509_LOOKUP>.
X509_LOOKUP_free() destructs the given B<X509_LOOKUP>.
X509_LOOKUP_set_method_data() and X509_LOOKUP_get_method_data()
associates and retrieves a pointer to application data to and from the
given B<X509_LOOKUP>, respectively.
X509_LOOKUP_ctrl() is used to set or get additional data to or from a
B<X509_LOOKUP> structure or its associated L<X509_LOOKUP_METHOD(3)>.
The arguments of the control command are passed via I<argc> and I<argl>,
its return value via I<*ret>.
The meaning of the arguments depends on the I<cmd> number of the
control command. In general, this function is not called directly, but
wrapped by a macro call, see below.
The control I<cmd>s known to OpenSSL are discussed in more depth
in L</Control Commands>.
X509_LOOKUP_load_file() passes a filename to be loaded immediately
into the associated B<X509_STORE>.
I<type> indicates what type of object is expected.
This can only be used with a lookup using the implementation
L<X509_LOOKUP_file(3)>.
X509_LOOKUP_add_dir() passes a directory specification from which
certificates and CRLs are loaded on demand into the associated
B<X509_STORE>.
I<type> indicates what type of object is expected.
This can only be used with a lookup using the implementation
L<X509_LOOKUP_hash_dir(3)>.
X509_LOOKUP_load_file(), X509_LOOKUP_add_dir(),
X509_LOOKUP_add_store(), and X509_LOOKUP_load_store() are implemented
as macros that use X509_LOOKUP_ctrl().
X509_LOOKUP_by_subject(), X509_LOOKUP_by_issuer_serial(),
X509_LOOKUP_by_fingerprint(), and X509_LOOKUP_by_alias() look up
certificates and CRLs in the L<X509_STORE(3)> associated with the
B<X509_LOOKUP> using different criteria, where the looked up object is
stored in I<ret>.
Some of the underlying B<X509_LOOKUP_METHOD>s will also cache objects
matching the criteria in the associated B<X509_STORE>, which makes it
possible to handle cases where the criteria have more than one hit.
=head2 Control Commands
The B<X509_LOOKUP_METHOD>s built into OpenSSL recognise the following
X509_LOOKUP_ctrl() I<cmd>s:
=over 4
=item B<X509_L_FILE_LOAD>
This is the command that X509_LOOKUP_load_file() uses.
The filename is passed in I<argc>, and the type in I<argl>.
=item B<X509_L_ADD_DIR>
This is the command that X509_LOOKUP_add_dir() uses.
The directory specification is passed in I<argc>, and the type in
I<argl>.
=item B<X509_L_ADD_STORE>
This is the command that X509_LOOKUP_add_store() uses.
The URI is passed in I<argc>.
=item B<X509_L_LOAD_STORE>
This is the command that X509_LOOKUP_load_store() uses.
The URI is passed in I<argc>.
=back
=head1 RETURN VALUES
X509_LOOKUP_new() returns a B<X509_LOOKUP> pointer when successful,
or NULL on error.
X509_LOOKUP_init() and X509_LOOKUP_shutdown() return 1 on success, or
0 on error.
X509_LOOKUP_ctrl() returns -1 if the B<X509_LOOKUP> doesn't have an
associated B<X509_LOOKUP_METHOD>, or 1 if the X<509_LOOKUP_METHOD>
doesn't have a control function.
Otherwise, it returns what the control function in the
B<X509_LOOKUP_METHOD> returns, which is usually 1 on success and 0 in
error.
X509_LOOKUP_get_store() returns a B<X509_STORE> pointer if there is
one, otherwise NULL.
X509_LOOKUP_by_subject(), X509_LOOKUP_by_issuer_serial(),
X509_LOOKUP_by_fingerprint(), and X509_LOOKUP_by_alias() all return 0
if there is no B<X509_LOOKUP_METHOD> or that method doesn't implement
the corresponding function.
Otherwise, it returns what the corresponding function in the
B<X509_LOOKUP_METHOD> returns, which is usually 1 on success and 0 in
error.
=head1 SEE ALSO
L<X509_LOOKUP_METHOD(3)>, L<X509_STORE(3)>
=head1 COPYRIGHT
Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (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

21
doc/man3/X509_LOOKUP_meth_new.pod
View file

@ -2,6 +2,7 @@
=head1 NAME
X509_LOOKUP_METHOD,
X509_LOOKUP_meth_new, X509_LOOKUP_meth_free, X509_LOOKUP_meth_set_new_item,
X509_LOOKUP_meth_get_new_item, X509_LOOKUP_meth_set_free,
X509_LOOKUP_meth_get_free, X509_LOOKUP_meth_set_init,
@ -16,14 +17,15 @@ X509_LOOKUP_get_by_fingerprint_fn, X509_LOOKUP_meth_set_get_by_fingerprint,
X509_LOOKUP_meth_get_get_by_fingerprint,
X509_LOOKUP_get_by_alias_fn, X509_LOOKUP_meth_set_get_by_alias,
X509_LOOKUP_meth_get_get_by_alias,
X509_LOOKUP_set_method_data, X509_LOOKUP_get_method_data,
X509_LOOKUP_get_store, X509_OBJECT_set1_X509, X509_OBJECT_set1_X509_CRL
X509_OBJECT_set1_X509, X509_OBJECT_set1_X509_CRL
- Routines to build up X509_LOOKUP methods
=head1 SYNOPSIS
#include <openssl/x509_vfy.h>
typedef x509_lookup_method_st X509_LOOKUP_METHOD;
X509_LOOKUP_METHOD *X509_LOOKUP_meth_new(const char *name);
void X509_LOOKUP_meth_free(X509_LOOKUP_METHOD *method);
@ -92,11 +94,6 @@ X509_LOOKUP_get_store, X509_OBJECT_set1_X509, X509_OBJECT_set1_X509_CRL
X509_LOOKUP_get_by_alias_fn X509_LOOKUP_meth_get_get_by_alias(
const X509_LOOKUP_METHOD *method);
int X509_LOOKUP_set_method_data(X509_LOOKUP *ctx, void *data);
void *X509_LOOKUP_get_method_data(const X509_LOOKUP *ctx);
X509_STORE *X509_LOOKUP_get_store(const X509_LOOKUP *ctx);
int X509_OBJECT_set1_X509(X509_OBJECT *a, X509 *obj);
int X509_OBJECT_set1_X509_CRL(X509_OBJECT *a, X509_CRL *obj);
@ -118,7 +115,7 @@ X509_LOOKUP_get_new_item() and X509_LOOKUP_set_new_item() get and set the
function that is called when an B<X509_LOOKUP> object is created with
X509_LOOKUP_new(). If an X509_LOOKUP_METHOD requires any per-X509_LOOKUP
specific data, the supplied new_item function should allocate this data and
invoke X509_LOOKUP_set_method_data().
invoke L<X509_LOOKUP_set_method_data(3)>.
X509_LOOKUP_get_free() and X509_LOOKUP_set_free() get and set the function
that is used to free any method data that was allocated and set from within
@ -126,7 +123,7 @@ new_item function.
X509_LOOKUP_meth_get_init() and X509_LOOKUP_meth_set_init() get and set the
function that is used to initialize the method data that was set with
X509_LOOKUP_set_method_data() as part of the new_item routine.
L<X509_LOOKUP_set_method_data(3)> as part of the new_item routine.
X509_LOOKUP_meth_get_shutdown() and X509_LOOKUP_meth_set_shutdown() get and set
the function that is used to shut down the method data whose state was
@ -164,9 +161,9 @@ increments the result's reference count.
Any method data that was created as a result of the new_item function
set by X509_LOOKUP_meth_set_new_item() can be accessed with
X509_LOOKUP_get_method_data(). The B<X509_STORE> object that owns the
X509_LOOKUP may be accessed with X509_LOOKUP_get_store(). Successful lookups
should return 1, and unsuccessful lookups should return 0.
L<X509_LOOKUP_get_method_data(3)>. The B<X509_STORE> object that owns the
X509_LOOKUP may be accessed with L<X509_LOOKUP_get_store(3)>. Successful
lookups should return 1, and unsuccessful lookups should return 0.
X509_LOOKUP_get_get_by_subject(), X509_LOOKUP_get_get_by_issuer_serial(),
X509_LOOKUP_get_get_by_fingerprint(), X509_LOOKUP_get_get_by_alias() retrieve

15
doc/man3/X509_STORE_add_cert.pod
View file

@ -2,8 +2,10 @@
=head1 NAME
X509_STORE,
X509_STORE_add_cert, X509_STORE_add_crl, X509_STORE_set_depth,
X509_STORE_set_flags, X509_STORE_set_purpose, X509_STORE_set_trust,
X509_STORE_add_lookup,
X509_STORE_load_locations,
X509_STORE_set_default_paths
- X509_STORE manipulation
@ -12,6 +14,8 @@ X509_STORE_set_default_paths
#include <openssl/x509_vfy.h>
typedef x509_store_st X509_STORE;
int X509_STORE_add_cert(X509_STORE *ctx, X509 *x);
int X509_STORE_add_crl(X509_STORE *ctx, X509_CRL *x);
int X509_STORE_set_depth(X509_STORE *store, int depth);
@ -19,6 +23,9 @@ X509_STORE_set_default_paths
int X509_STORE_set_purpose(X509_STORE *ctx, int purpose);
int X509_STORE_set_trust(X509_STORE *ctx, int trust);
X509_LOOKUP *X509_STORE_add_lookup(X509_STORE *store,
X509_LOOKUP_METHOD *meth);
int X509_STORE_load_locations(X509_STORE *ctx,
const char *file, const char *dir);
int X509_STORE_set_default_paths(X509_STORE *ctx);
@ -65,6 +72,11 @@ for the corresponding values used in certificate chain validation. Their
behavior is documented in the corresponding B<X509_VERIFY_PARAM> manual
pages, e.g., L<X509_VERIFY_PARAM_set_depth(3)>.
X509_STORE_add_lookup() finds or creates a L<X509_LOOKUP(3)> with the
L<X509_LOOKUP_METHOD(3)> I<meth> and adds it to the B<X509_STORE>
I<store>. This also associates the B<X509_STORE> with the lookup, so
B<X509_LOOKUP> functions can look up objects in that store.
X509_STORE_load_locations() loads trusted certificate(s) into an
B<X509_STORE> from a given file and/or directory path. It is permitted
to specify just a file, just a directory, or both paths. The certificates
@ -83,6 +95,9 @@ X509_STORE_set_flags(), X509_STORE_set_purpose(),
X509_STORE_set_trust(), X509_STORE_load_locations(), and
X509_STORE_set_default_paths() return 1 on success or 0 on failure.
X509_STORE_add_lookup() returns the found or created
L<X509_LOOKUP(3)>, or NULL on error.
=head1 SEE ALSO
L<X509_LOOKUP_hash_dir(3)>.

6
util/private.num
View file

@ -75,11 +75,15 @@ X509_STORE_CTX_lookup_crls_fn datatype
X509_STORE_CTX_verify_cb datatype
X509_STORE_CTX_verify_fn datatype
X509_STORE_set_verify_cb_func datatype
X509_LOOKUP datatype
X509_LOOKUP_METHOD datatype
X509_LOOKUP_TYPE datatype
X509_LOOKUP_get_by_alias_fn datatype
X509_LOOKUP_get_by_subject_fn datatype
X509_LOOKUP_get_by_fingerprint_fn datatype
X509_LOOKUP_ctrl_fn datatype
X509_LOOKUP_get_by_issuer_serial_fn datatype
X509_STORE datatype
bio_info_cb datatype
BIO_info_cb datatype
custom_ext_add_cb datatype
@ -452,6 +456,8 @@ SSL_want_x509_lookup define
SSLv23_client_method define
SSLv23_method define
SSLv23_server_method define
X509_LOOKUP_add_dir define
X509_LOOKUP_load_file define
X509_STORE_set_lookup_crls_cb define
X509_STORE_set_verify_func define
EVP_PKEY_CTX_set1_id define