1*4724848cSchristos=pod 2*4724848cSchristos 3*4724848cSchristos=begin comment 4*4724848cSchristos 5*4724848cSchristosThis is a recommended way to describe OSSL_STORE loaders, 6*4724848cSchristos"ossl_store-{name}", where {name} is replaced with the name of the 7*4724848cSchristosscheme it implements, in man section 7. 8*4724848cSchristos 9*4724848cSchristos=end comment 10*4724848cSchristos 11*4724848cSchristos=head1 NAME 12*4724848cSchristos 13*4724848cSchristosossl_store-file - The store 'file' scheme loader 14*4724848cSchristos 15*4724848cSchristos=head1 SYNOPSIS 16*4724848cSchristos 17*4724848cSchristos=for comment generic 18*4724848cSchristos 19*4724848cSchristos#include <openssl/store.h> 20*4724848cSchristos 21*4724848cSchristos=head1 DESCRIPTION 22*4724848cSchristos 23*4724848cSchristosSupport for the 'file' scheme is built into C<libcrypto>. 24*4724848cSchristosSince files come in all kinds of formats and content types, the 'file' 25*4724848cSchristosscheme has its own layer of functionality called "file handlers", 26*4724848cSchristoswhich are used to try to decode diverse types of file contents. 27*4724848cSchristos 28*4724848cSchristosIn case a file is formatted as PEM, each called file handler receives 29*4724848cSchristosthe PEM name (everything following any 'C<-----BEGIN >') as well as 30*4724848cSchristospossible PEM headers, together with the decoded PEM body. Since PEM 31*4724848cSchristosformatted files can contain more than one object, the file handlers 32*4724848cSchristosare called upon for each such object. 33*4724848cSchristos 34*4724848cSchristosIf the file isn't determined to be formatted as PEM, the content is 35*4724848cSchristosloaded in raw form in its entirety and passed to the available file 36*4724848cSchristoshandlers as is, with no PEM name or headers. 37*4724848cSchristos 38*4724848cSchristosEach file handler is expected to handle PEM and non-PEM content as 39*4724848cSchristosappropriate. Some may refuse non-PEM content for the sake of 40*4724848cSchristosdeterminism (for example, there are keys out in the wild that are 41*4724848cSchristosrepresented as an ASN.1 OCTET STRING. In raw form, it's not easily 42*4724848cSchristospossible to distinguish those from any other data coming as an ASN.1 43*4724848cSchristosOCTET STRING, so such keys would naturally be accepted as PEM files 44*4724848cSchristosonly). 45*4724848cSchristos 46*4724848cSchristos=head1 NOTES 47*4724848cSchristos 48*4724848cSchristosWhen needed, the 'file' scheme loader will require a pass phrase by 49*4724848cSchristosusing the C<UI_METHOD> that was passed via OSSL_STORE_open(). 50*4724848cSchristosThis pass phrase is expected to be UTF-8 encoded, anything else will 51*4724848cSchristosgive an undefined result. 52*4724848cSchristosThe files made accessible through this loader are expected to be 53*4724848cSchristosstandard compliant with regards to pass phrase encoding. 54*4724848cSchristosFiles that aren't should be re-generated with a correctly encoded pass 55*4724848cSchristosphrase. 56*4724848cSchristosSee L<passphrase-encoding(7)> for more information. 57*4724848cSchristos 58*4724848cSchristos=head1 SEE ALSO 59*4724848cSchristos 60*4724848cSchristosL<ossl_store(7)>, L<passphrase-encoding(7)> 61*4724848cSchristos 62*4724848cSchristos=head1 COPYRIGHT 63*4724848cSchristos 64*4724848cSchristosCopyright 2018 The OpenSSL Project Authors. All Rights Reserved. 65*4724848cSchristos 66*4724848cSchristosLicensed under the OpenSSL license (the "License"). You may not use 67*4724848cSchristosthis file except in compliance with the License. You can obtain a copy 68*4724848cSchristosin the file LICENSE in the source distribution or at 69*4724848cSchristosL<https://www.openssl.org/source/license.html>. 70*4724848cSchristos 71*4724848cSchristos=cut 72