Catch up to the removal of OSSL_STORE_open_file()
[openssl.git] / doc / man7 / ossl_store.pod
1 =pod
2
3 =head1 NAME
4
5 ossl_store - Store retrieval functions
6
7 =head1 SYNOPSIS
8
9 =for comment generic
10
11 #include <openssl/store.h>
12
13 =head1 DESCRIPTION
14
15 =head2 General
16
17 A STORE is a layer of functionality to retrieve a number of supported
18 objects from a repository of any kind, addressable as a file name or
19 as a URI.
20
21 The functionality supports the pattern "open a channel to the
22 repository", "loop and retrieve one object at a time", and "finish up
23 by closing the channel".
24
25 The retrieved objects are returned as a wrapper type B<OSSL_STORE_INFO>,
26 from which an OpenSSL type can be retrieved.
27
28 =head2 URI schemes and loaders
29
30 Support for a URI scheme is called a STORE "loader", and can be added
31 dynamically from the calling application or from a loadable engine.
32
33 =head2 The 'file' scheme
34
35 Support for the 'file' scheme is already built into C<libcrypto>.
36 Since files come in all kinds of formats and content types, the 'file'
37 scheme has its own layer of functionality called "file handlers",
38 which are used to try to decode diverse types of file contents.
39
40 In case a file is formatted as PEM, each called file handler receives
41 the PEM name (everything following any 'C<-----BEGIN >') as well as
42 possible PEM headers, together with the decoded PEM body.  Since PEM
43 formatted files can contain more than one object, the file handlers
44 are called upon for each such object.
45
46 If the file isn't determined to be formatted as PEM, the content is
47 loaded in raw form in its entirety and passed to the available file
48 handlers as is, with no PEM name or headers.
49
50 Each file handler is expected to handle PEM and non-PEM content as
51 appropriate.  Some may refuse non-PEM content for the sake of
52 determinism (for example, there are keys out in the wild that are
53 represented as an ASN.1 OCTET STRING.  In raw form, it's not easily
54 possible to distinguish those from any other data coming as an ASN.1
55 OCTET STRING, so such keys would naturally be accepted as PEM files
56 only).
57
58 =head1 EXAMPLES
59
60 =head2 A generic call
61
62  OSSL_STORE_CTX *ctx = OSSL_STORE_open("file:/foo/bar/data.pem");
63
64  /*
65   * OSSL_STORE_eof() simulates file semantics for any repository to signal
66   * that no more data can be expected
67   */ 
68  while (!OSSL_STORE_eof(ctx)) {
69      OSSL_STORE_INFO *info = OSSL_STORE_load(ctx);
70
71      /*
72       * Do whatever is necessary with the OSSL_STORE_INFO,
73       * here just one example
74       */
75      switch (OSSL_STORE_INFO_get_type(info)) {
76      case OSSL_STORE_INFO_X509:
77          /* Print the X.509 certificate text */
78          X509_print_fp(stdout, OSSL_STORE_INFO_get0_CERT(info));
79          /* Print the X.509 certificate PEM output */
80          PEM_write_X509(stdout, OSSL_STORE_INFO_get0_CERT(info));
81          break;
82      }
83  }
84
85  OSSL_STORE_close(ctx);
86
87 =head1 SEE ALSO
88
89 L<OSSL_STORE_open(3)>, L<OSSL_STORE_INFO(3)>, L<OSSL_STORE_LOADER(3)>
90
91 =head1 COPYRIGHT
92
93 Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved.
94
95 Licensed under the OpenSSL license (the "License").  You may not use
96 this file except in compliance with the License.  You can obtain a copy
97 in the file LICENSE in the source distribution or at
98 L<https://www.openssl.org/source/license.html>.
99
100 =cut