|
Packit |
c4476c |
=pod
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 NAME
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
OSSL_STORE_INFO, OSSL_STORE_INFO_get_type, OSSL_STORE_INFO_get0_NAME,
|
|
Packit |
c4476c |
OSSL_STORE_INFO_get0_NAME_description, OSSL_STORE_INFO_get0_PARAMS,
|
|
Packit |
c4476c |
OSSL_STORE_INFO_get0_PKEY, OSSL_STORE_INFO_get0_CERT, OSSL_STORE_INFO_get0_CRL,
|
|
Packit |
c4476c |
OSSL_STORE_INFO_get1_NAME, OSSL_STORE_INFO_get1_NAME_description,
|
|
Packit |
c4476c |
OSSL_STORE_INFO_get1_PARAMS, OSSL_STORE_INFO_get1_PKEY,
|
|
Packit |
c4476c |
OSSL_STORE_INFO_get1_CERT,
|
|
Packit |
c4476c |
OSSL_STORE_INFO_get1_CRL, OSSL_STORE_INFO_type_string, OSSL_STORE_INFO_free,
|
|
Packit |
c4476c |
OSSL_STORE_INFO_new_NAME, OSSL_STORE_INFO_set0_NAME_description,
|
|
Packit |
c4476c |
OSSL_STORE_INFO_new_PARAMS, OSSL_STORE_INFO_new_PKEY, OSSL_STORE_INFO_new_CERT,
|
|
Packit |
c4476c |
OSSL_STORE_INFO_new_CRL - Functions to manipulate OSSL_STORE_INFO objects
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 SYNOPSIS
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
#include <openssl/store.h>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
typedef struct ossl_store_info_st OSSL_STORE_INFO;
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
int OSSL_STORE_INFO_get_type(const OSSL_STORE_INFO *store_info);
|
|
Packit |
c4476c |
const char *OSSL_STORE_INFO_get0_NAME(const OSSL_STORE_INFO *store_info);
|
|
Packit |
c4476c |
char *OSSL_STORE_INFO_get1_NAME(const OSSL_STORE_INFO *store_info);
|
|
Packit |
c4476c |
const char *OSSL_STORE_INFO_get0_NAME_description(const OSSL_STORE_INFO
|
|
Packit |
c4476c |
*store_info);
|
|
Packit |
c4476c |
char *OSSL_STORE_INFO_get1_NAME_description(const OSSL_STORE_INFO *store_info);
|
|
Packit |
c4476c |
EVP_PKEY *OSSL_STORE_INFO_get0_PARAMS(const OSSL_STORE_INFO *store_info);
|
|
Packit |
c4476c |
EVP_PKEY *OSSL_STORE_INFO_get1_PARAMS(const OSSL_STORE_INFO *store_info);
|
|
Packit |
c4476c |
EVP_PKEY *OSSL_STORE_INFO_get0_PKEY(const OSSL_STORE_INFO *store_info);
|
|
Packit |
c4476c |
EVP_PKEY *OSSL_STORE_INFO_get1_PKEY(const OSSL_STORE_INFO *store_info);
|
|
Packit |
c4476c |
X509 *OSSL_STORE_INFO_get0_CERT(const OSSL_STORE_INFO *store_info);
|
|
Packit |
c4476c |
X509 *OSSL_STORE_INFO_get1_CERT(const OSSL_STORE_INFO *store_info);
|
|
Packit |
c4476c |
X509_CRL *OSSL_STORE_INFO_get0_CRL(const OSSL_STORE_INFO *store_info);
|
|
Packit |
c4476c |
X509_CRL *OSSL_STORE_INFO_get1_CRL(const OSSL_STORE_INFO *store_info);
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
const char *OSSL_STORE_INFO_type_string(int type);
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
void OSSL_STORE_INFO_free(OSSL_STORE_INFO *store_info);
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
OSSL_STORE_INFO *OSSL_STORE_INFO_new_NAME(char *name);
|
|
Packit |
c4476c |
int OSSL_STORE_INFO_set0_NAME_description(OSSL_STORE_INFO *info, char *desc);
|
|
Packit |
c4476c |
OSSL_STORE_INFO *OSSL_STORE_INFO_new_PARAMS(DSA *dsa_params);
|
|
Packit |
c4476c |
OSSL_STORE_INFO *OSSL_STORE_INFO_new_PKEY(EVP_PKEY *pkey);
|
|
Packit |
c4476c |
OSSL_STORE_INFO *OSSL_STORE_INFO_new_CERT(X509 *x509);
|
|
Packit |
c4476c |
OSSL_STORE_INFO *OSSL_STORE_INFO_new_CRL(X509_CRL *crl);
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 DESCRIPTION
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
These functions are primarily useful for applications to retrieve
|
|
Packit |
c4476c |
supported objects from B<OSSL_STORE_INFO> objects and for scheme specific
|
|
Packit |
c4476c |
loaders to create B<OSSL_STORE_INFO> holders.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head2 Types
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
B<OSSL_STORE_INFO> is an opaque type that's just an intermediary holder for
|
|
Packit |
c4476c |
the objects that have been retrieved by OSSL_STORE_load() and similar
|
|
Packit |
c4476c |
functions.
|
|
Packit |
c4476c |
Supported OpenSSL type object can be extracted using one of
|
|
Packit |
c4476c |
STORE_INFO_get0_TYPE().
|
|
Packit |
c4476c |
The life time of this extracted object is as long as the life time of
|
|
Packit |
c4476c |
the B<OSSL_STORE_INFO> it was extracted from, so care should be taken not
|
|
Packit |
c4476c |
to free the latter too early.
|
|
Packit |
c4476c |
As an alternative, STORE_INFO_get1_TYPE() extracts a duplicate (or the
|
|
Packit |
c4476c |
same object with its reference count increased), which can be used
|
|
Packit |
c4476c |
after the containing B<OSSL_STORE_INFO> has been freed.
|
|
Packit |
c4476c |
The object returned by STORE_INFO_get1_TYPE() must be freed separately
|
|
Packit |
c4476c |
by the caller.
|
|
Packit |
c4476c |
See L</SUPPORTED OBJECTS> for more information on the types that are
|
|
Packit |
c4476c |
supported.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head2 Functions
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
OSSL_STORE_INFO_get_type() takes a B<OSSL_STORE_INFO> and returns the STORE
|
|
Packit |
c4476c |
type number for the object inside.
|
|
Packit |
c4476c |
STORE_INFO_get_type_string() takes a STORE type number and returns a
|
|
Packit |
c4476c |
short string describing it.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
OSSL_STORE_INFO_get0_NAME(), OSSL_STORE_INFO_get0_NAME_description(),
|
|
Packit |
c4476c |
OSSL_STORE_INFO_get0_PARAMS(), OSSL_STORE_INFO_get0_PKEY(),
|
|
Packit |
c4476c |
OSSL_STORE_INFO_get0_CERT() and OSSL_STORE_INFO_get0_CRL() all take a
|
|
Packit |
c4476c |
B<OSSL_STORE_INFO> and return the held object of the appropriate OpenSSL
|
|
Packit |
c4476c |
type provided that's what's held.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
OSSL_STORE_INFO_get1_NAME(), OSSL_STORE_INFO_get1_NAME_description(),
|
|
Packit |
c4476c |
OSSL_STORE_INFO_get1_PARAMS(), OSSL_STORE_INFO_get1_PKEY(),
|
|
Packit |
c4476c |
OSSL_STORE_INFO_get1_CERT() and OSSL_STORE_INFO_get1_CRL() all take a
|
|
Packit |
c4476c |
B<OSSL_STORE_INFO> and return a duplicate of the held object of the
|
|
Packit |
c4476c |
appropriate OpenSSL type provided that's what's held.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
OSSL_STORE_INFO_free() frees a B<OSSL_STORE_INFO> and its contained type.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
OSSL_STORE_INFO_new_NAME() , OSSL_STORE_INFO_new_PARAMS(),
|
|
Packit |
c4476c |
OSSL_STORE_INFO_new_PKEY(), OSSL_STORE_INFO_new_CERT() and
|
|
Packit |
c4476c |
OSSL_STORE_INFO_new_CRL() create a B<OSSL_STORE_INFO>
|
|
Packit |
c4476c |
object to hold the given input object.
|
|
Packit |
c4476c |
Additionally, for B<OSSL_STORE_INFO_NAME>` objects,
|
|
Packit |
c4476c |
OSSL_STORE_INFO_set0_NAME_description() can be used to add an extra
|
|
Packit |
c4476c |
description.
|
|
Packit |
c4476c |
This description is meant to be human readable and should be used for
|
|
Packit |
c4476c |
information printout.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 SUPPORTED OBJECTS
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Currently supported object types are:
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=over 4
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item OSSL_STORE_INFO_NAME
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
A name is exactly that, a name.
|
|
Packit |
c4476c |
It's like a name in a directory, but formatted as a complete URI.
|
|
Packit |
c4476c |
For example, the path in URI C<file:/foo/bar/> could include a file
|
|
Packit |
c4476c |
named C<cookie.pem>, and in that case, the returned B<OSSL_STORE_INFO_NAME>
|
|
Packit |
c4476c |
object would have the URI C<file:/foo/bar/cookie.pem>, which can be
|
|
Packit |
c4476c |
used by the application to get the objects in that file.
|
|
Packit |
c4476c |
This can be applied to all schemes that can somehow support a listing
|
|
Packit |
c4476c |
of object URIs.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
For C<file:> URIs that are used without the explicit scheme, the
|
|
Packit |
c4476c |
returned name will be the path of each object, so if C</foo/bar> was
|
|
Packit |
c4476c |
given and that path has the file C<cookie.pem>, the name
|
|
Packit |
c4476c |
C</foo/bar/cookie.pem> will be returned.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
The returned URI is considered canonical and must be unique and permanent
|
|
Packit |
c4476c |
for the storage where the object (or collection of objects) resides.
|
|
Packit |
c4476c |
Each loader is responsible for ensuring that it only returns canonical
|
|
Packit |
c4476c |
URIs.
|
|
Packit |
c4476c |
However, it's possible that certain schemes allow an object (or collection
|
|
Packit |
c4476c |
thereof) to be reached with alternative URIs; just because one URI is
|
|
Packit |
c4476c |
canonical doesn't mean that other variants can't be used.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
At the discretion of the loader that was used to get these names, an
|
|
Packit |
c4476c |
extra description may be attached as well.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item OSSL_STORE_INFO_PARAMS
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Key parameters.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item OSSL_STORE_INFO_PKEY
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
A private/public key of some sort.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item OSSL_STORE_INFO_CERT
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
An X.509 certificate.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=item OSSL_STORE_INFO_CRL
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
A X.509 certificate revocation list.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=back
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 RETURN VALUES
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
OSSL_STORE_INFO_get_type() returns the STORE type number of the given
|
|
Packit |
c4476c |
B<OSSL_STORE_INFO>.
|
|
Packit |
c4476c |
There is no error value.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
OSSL_STORE_INFO_get0_NAME(), OSSL_STORE_INFO_get0_NAME_description(),
|
|
Packit |
c4476c |
OSSL_STORE_INFO_get0_PARAMS(), OSSL_STORE_INFO_get0_PKEY(),
|
|
Packit |
c4476c |
OSSL_STORE_INFO_get0_CERT() and OSSL_STORE_INFO_get0_CRL() all return
|
|
Packit |
c4476c |
a pointer to the OpenSSL object on success, NULL otherwise.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
OSSL_STORE_INFO_get0_NAME(), OSSL_STORE_INFO_get0_NAME_description(),
|
|
Packit |
c4476c |
OSSL_STORE_INFO_get0_PARAMS(), OSSL_STORE_INFO_get0_PKEY(),
|
|
Packit |
c4476c |
OSSL_STORE_INFO_get0_CERT() and OSSL_STORE_INFO_get0_CRL() all return
|
|
Packit |
c4476c |
a pointer to a duplicate of the OpenSSL object on success, NULL otherwise.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
OSSL_STORE_INFO_type_string() returns a string on success, or B<NULL> on
|
|
Packit |
c4476c |
failure.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
OSSL_STORE_INFO_new_NAME(), OSSL_STORE_INFO_new_PARAMS(),
|
|
Packit |
c4476c |
OSSL_STORE_INFO_new_PKEY(), OSSL_STORE_INFO_new_CERT() and
|
|
Packit |
c4476c |
OSSL_STORE_INFO_new_CRL() return a B<OSSL_STORE_INFO>
|
|
Packit |
c4476c |
pointer on success, or B<NULL> on failure.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
OSSL_STORE_INFO_set0_NAME_description() returns 1 on success, or 0 on
|
|
Packit |
c4476c |
failure.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 SEE ALSO
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
L<ossl_store(7)>, L<OSSL_STORE_open(3)>, L<OSSL_STORE_register_loader(3)>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 HISTORY
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
OSSL_STORE_INFO(), OSSL_STORE_INFO_get_type(), OSSL_STORE_INFO_get0_NAME(),
|
|
Packit |
c4476c |
OSSL_STORE_INFO_get0_PARAMS(), OSSL_STORE_INFO_get0_PKEY(),
|
|
Packit |
c4476c |
OSSL_STORE_INFO_get0_CERT(), OSSL_STORE_INFO_get0_CRL(),
|
|
Packit |
c4476c |
OSSL_STORE_INFO_type_string(), OSSL_STORE_INFO_free(), OSSL_STORE_INFO_new_NAME(),
|
|
Packit |
c4476c |
OSSL_STORE_INFO_new_PARAMS(), OSSL_STORE_INFO_new_PKEY(),
|
|
Packit |
c4476c |
OSSL_STORE_INFO_new_CERT() and OSSL_STORE_INFO_new_CRL()
|
|
Packit |
c4476c |
were added in OpenSSL 1.1.1.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 COPYRIGHT
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Licensed under the OpenSSL license (the "License"). You may not use
|
|
Packit |
c4476c |
this file except in compliance with the License. You can obtain a copy
|
|
Packit |
c4476c |
in the file LICENSE in the source distribution or at
|
|
Packit |
c4476c |
L<https://www.openssl.org/source/license.html>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=cut
|