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  /*
  63   * There is also a OSSL_STORE_open_file() that can be used for file paths
  64   * that can't be represented as URIs, such as Windows backslashes
  65   */
  66  OSSL_STORE_CTX *ctx = OSSL_STORE_open("file:/foo/bar/data.pem");
  67
  68  /*
  69   * OSSL_STORE_eof() simulates file semantics for any repository to signal
  70   * that no more data can be expected
  71   */
  72  while (!OSSL_STORE_eof(ctx)) {
  73      OSSL_STORE_INFO *info = OSSL_STORE_load(ctx);
  74
  75      /*
  76       * Do whatever is necessary with the OSSL_STORE_INFO,
  77       * here just one example
  78       */
  79      switch (OSSL_STORE_INFO_get_type(info)) {
  80      case OSSL_STORE_INFO_X509:
  81          /* Print the X.509 certificate text */
  82          X509_print_fp(stdout, OSSL_STORE_INFO_get0_CERT(info));
  83          /* Print the X.509 certificate PEM output */
  84          PEM_write_X509(stdout, OSSL_STORE_INFO_get0_CERT(info));
  85          break;
  86      }
  87  }
  88
  89  OSSL_STORE_close(ctx);
  90
  91 =head1 SEE ALSO
  92 L<OSSL_STORE_open(3)>, L<OSSL_STORE_INFO(3)>, L<OSSL_STORE_LOADER(3)>
  93
  94 =head1 COPYRIGHT
  95
  96 Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved.
  97
  98 Licensed under the OpenSSL license (the "License").  You may not use
  99 this file except in compliance with the License.  You can obtain a copy
 100 in the file LICENSE in the source distribution or at
 101 L<https://www.openssl.org/source/license.html>.
 102
 103 =cut