Hakase/openssl-custom
1
0 Fork 0
Code Issues Pull Requests Releases Wiki Activity

Latest update.

Browse Source
This commit is contained in:
Hakase
2019-10-17 23:54:38 +09:00
parent 41a23ae6f6
commit ee84d0dd84
1357 changed files with 41111 additions and 9603 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod
+40 -30
View File
@@ -9,9 +9,9 @@ ossl_sa_TYPE_doall_arg, ossl_sa_TYPE_get, ossl_sa_TYPE_set
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include "internal/sparse_array.h"
#include "crypto/sparse_array.h"
typedef struct sparse_array_st OPENSSL_SA;
@@ -33,42 +33,51 @@ ossl_sa_TYPE_doall_arg, ossl_sa_TYPE_get, ossl_sa_TYPE_set
=head1 DESCRIPTION
=begin comment
POD is pretty good at recognising function names and making them appropriately
bold... however, when part of the function name is variable, we have to help
the processor along
=end comment
SPARSE_ARRAY_OF() returns the name for a sparse array of the specified
B<TYPE>. DEFINE_STACK_OF() creates set of functions for a sparse array of
B<TYPE>. This will mean that a pointer to type B<TYPE> is stored in each
element of a sparse array, the type is referenced by SPARSE_ARRAY_OF(TYPE) and
each function name begins with I<ossl_sa_TYPE_>. For example:
B<I<TYPE>>. DEFINE_STACK_OF() creates set of functions for a sparse
array of B<I<TYPE>>. This will mean that a pointer to type B<I<TYPE>>
is stored in each element of a sparse array, the type is referenced by
B<SPARSE_ARRAY_OF>(B<I<TYPE>>) and each function name begins with
B<ossl_sa_I<TYPE>_>. For example:
TYPE *ossl_sa_TYPE_get(SPARSE_ARRAY_OF(TYPE) *sa, ossl_uintmax_t idx);
ossl_sa_TYPE_num() returns the number of elements in B<sa> or 0 if B<sa> is
B<NULL>.
B<ossl_sa_I<TYPE>_num>() returns the number of elements in I<sa> or 0 if I<sa>
is NULL.
ossl_sa_TYPE_get() returns element B<idx> in B<sa>, where B<idx> starts at
zero. If B<idx> refers to a value that has not been set then B<NULL> is
B<ossl_sa_I<TYPE>_get>() returns element I<idx> in I<sa>, where I<idx> starts
at zero. If I<idx> refers to a value that has not been set then NULL is
returned.
ossl_sa_TYPE_set() sets element B<idx> in B<sa> to B<value>, where B<idx>
B<ossl_sa_I<TYPE>_set>() sets element I<idx> in I<sa> to I<value>, where I<idx>
starts at zero. The sparse array will be resized as required.
ossl_sa_TYPE_new() allocates a new empty sparse array.
B<ossl_sa_I<TYPE>_new>() allocates a new empty sparse array.
ossl_sa_TYPE_free() frees up the B<sa> structure. It does B<not> free up any
elements of B<sa>. After this call B<sa> is no longer valid.
B<ossl_sa_I<TYPE>_free>() frees up the I<sa> structure. It does I<not> free up any
elements of I<sa>. After this call I<sa> is no longer valid.
ossl_sa_TYPE_free_leaves() frees up the B<sa> structure and all of its
elements. After this call B<sa> is no longer valid.
B<ossl_sa_I<TYPE>_free_leaves>() frees up the I<sa> structure and all of its
elements. After this call I<sa> is no longer valid.
ossl_sa_TYPE_doall() calls the function B<leaf> for each element in B<sa>
B<ossl_sa_I<TYPE>_doall>() calls the function I<leaf> for each element in I<sa>
in ascending index order. The index position, within the sparse array,
of each item is passed as the first argument to the leaf function and a
pointer to the associated value is is passed as the second argument.
ossl_sa_TYPE_doall_arg() calls the function B<leaf> for each element in
B<sa> in ascending index order. The index position, within the sparse
B<ossl_sa_I<TYPE>_doall_arg>() calls the function I<leaf> for each element in
I<sa> in ascending index order. The index position, within the sparse
array, of each item is passed as the first argument to the leaf function,
a pointer to the associated value is passed as the second argument and
the third argument is the user supplied B<arg>.
the third argument is the user supplied I<arg>.
=head1 NOTES
@@ -77,9 +86,9 @@ Sparse arrays are an internal data structure and should B<not> be used by user
applications.
Care should be taken when accessing sparse arrays in multi-threaded
environments. The ossl_sa_TYPE_set operation can cause the internal structure
of the sparse array to change which causes race conditions if the sparse array
is accessed in a different thread.
environments. The B<ossl_sa_I<TYPE>_set>() operation can cause the internal
structure of the sparse array to change which causes race conditions if the
sparse array is accessed in a different thread.
SPARSE_ARRAY_OF() and DEFINE_SPARSE_ARRAY_OF() are implemented as macros.
@@ -90,21 +99,22 @@ OPENSSL_SA_num and OPENSSL_SA_set.
=head1 RETURN VALUES
ossl_sa_TYPE_num() returns the number of elements in the sparse array or B<0>
if the passed sparse array is B<NULL>.
B<ossl_sa_I<TYPE>_num>() returns the number of elements in the sparse array or
B<0> if the passed sparse array is NULL.
ossl_sa_TYPE_get() returns a pointer to a sparse array element or B<NULL> if
B<ossl_sa_I<TYPE>_get>() returns a pointer to a sparse array element or NULL if
the element has not be set.
ossl_sa_TYPE_set() return B<1> on success and B<0> on error. In the latter
B<ossl_sa_I<TYPE>_set>() return B<1> on success and B<0> on error. In the latter
case, the elements of the sparse array remain unchanged, although the internal
structures might have.
ossl_sa_TYPE_new() returns an empty sparse array or B<NULL> if an error
B<ossl_sa_I<TYPE>_new>() returns an empty sparse array or NULL if an error
occurs.
ossl_sa_TYPE_doall, ossl_sa_TYPE_doall_arg, ossl_sa_TYPE_free() and
ossl_sa_TYPE_free_leaves() do not return values.
B<ossl_sa_I<TYPE>_doall>(), B<ossl_sa_I<TYPE>_doall_arg>(),
B<ossl_sa_I<TYPE>_free>() and B<ossl_sa_I<TYPE>_free_leaves>()
do not return values.
=head1 HISTORY
doc/internal/man3/OSSL_METHOD_STORE.pod
+26 -26
View File
@@ -53,52 +53,52 @@ separately (see L</Cache Functions> below).
=head2 Store Functions
ossl_method_store_init() initialises the method store subsystem in the scope of
the library context B<ctx>.
the library context I<ctx>.
ossl_method_store_cleanup() cleans up and shuts down the implementation method
store subsystem in the scope of the library context B<ctx>.
store subsystem in the scope of the library context I<ctx>.
ossl_method_store_new() create a new empty method store using the supplied
B<ctx> to allow access to the required underlying property data.
I<ctx> to allow access to the required underlying property data.
ossl_method_store_free() frees resources allocated to B<store>.
ossl_method_store_free() frees resources allocated to I<store>.
ossl_method_store_add() adds the B<method> constructed from an implementation in
the provider B<prov> to the B<store> as an instance of an algorithm indicated by
B<nid> and the property definition B<properties>, unless the B<store> already
has a method from the same provider with the same B<nid> and B<properties>.
If the B<method_up_ref> function is given, it's called to increment the
ossl_method_store_add() adds the I<method> constructed from an implementation in
the provider I<prov> to the I<store> as an instance of an algorithm indicated by
I<nid> and the property definition I<properties>, unless the I<store> already
has a method from the same provider with the same I<nid> and I<properties>.
If the I<method_up_ref> function is given, it's called to increment the
reference count of the method.
If the B<method_destruct> function is given, it's called when this function
If the I<method_destruct> function is given, it's called when this function
fails to add the method to the store, or later on when it is being released from
the B<store>.
the I<store>.
ossl_method_store_remove() removes the B<method> identified by B<nid> from the
B<store>.
ossl_method_store_remove() removes the I<method> identified by I<nid> from the
I<store>.
ossl_method_store_fetch() queries B<store> for a method identified by B<nid>
that matches the property query B<prop_query>.
The result, if any, is returned in B<method>.
ossl_method_store_fetch() queries I<store> for a method identified by I<nid>
that matches the property query I<prop_query>.
The result, if any, is returned in I<method>.
ossl_method_store_set_global_properties() sets method B<store> wide query
properties to B<prop_query>.
ossl_method_store_set_global_properties() sets method I<store> wide query
properties to I<prop_query>.
All subsequent fetches will need to meet both these global query properties
and the ones passed to the ossl_method_store_free().
=head2 Cache Functions
ossl_method_store_cache_get() queries the cache associated with the B<store>
for a method identified by B<nid> that matches the property query
B<prop_query>.
The result, if any, is returned in B<method>.
ossl_method_store_cache_get() queries the cache associated with the I<store>
for a method identified by I<nid> that matches the property query
I<prop_query>.
The result, if any, is returned in I<method>.
ossl_method_store_cache_set() sets a cache entry identified by B<nid> with the
property query B<prop_query> in the B<store>.
Future calls to ossl_method_store_cache_get() will return the specified B<method>.
ossl_method_store_cache_set() sets a cache entry identified by I<nid> with the
property query I<prop_query> in the I<store>.
Future calls to ossl_method_store_cache_get() will return the specified I<method>.
=head1 RETURN VALUES
ossl_method_store_new() returns a new method store object or B<NULL> on failure.
ossl_method_store_new() returns a new method store object or NULL on failure.
ossl_method_store_free(), ossl_method_store_add(),
ossl_method_store_remove(), ossl_method_store_fetch(),
doc/internal/man3/cms_add1_signing_cert.pod
+4 -4
View File
@@ -16,10 +16,10 @@ CMS_SignerInfo data structure
=head1 DESCRIPTION
cms_add1_signing_cert() adds an ESS Signing Certificate B<sc> (version 1) signed
attribute to the CMS_SignerInfo B<si>.
cms_add1_signing_cert_v2() adds an ESS Signing Certificate B<sc2> (version 2) signed
attribute to the CMS_SignerInfo B<si>.
cms_add1_signing_cert() adds an ESS Signing Certificate I<sc> (version 1) signed
attribute to the CMS_SignerInfo I<si>.
cms_add1_signing_cert_v2() adds an ESS Signing Certificate I<sc2> (version 2) signed
attribute to the CMS_SignerInfo I<si>.
The ESS Signing Certificate attributes version 1 and 2 are defined in RFC 5035
which updates Section 5.4 of RFC 2634.
doc/internal/man3/evp_generic_fetch.pod
+3 -3
View File
@@ -8,7 +8,7 @@ evp_generic_fetch, evp_generic_fetch_by_number
=head1 SYNOPSIS
/* Only for EVP source */
#include "evp_locl.h"
#include "evp_local.h"
void *evp_generic_fetch(OPENSSL_CTX *libctx, int operation_id,
const char *name, const char *properties,
@@ -39,7 +39,7 @@ I<new_method>, I<up_ref_method>, and I<free_method>.
evp_generic_fetch_by_number() does the same thing as evp_generic_fetch(),
but takes a I<name_id> instead of a number.
I<name_id> must always be non-zero; as a matter of fact, it being zero
I<name_id> must always be nonzero; as a matter of fact, it being zero
is considered a programming error.
This is meant to be used when one method needs to fetch an associated
other method, and is typically called from inside the given function
@@ -70,7 +70,7 @@ frees the given method.
=head1 RETURN VALUES
evp_generic_fetch() returns a method on success, or B<NULL> on error.
evp_generic_fetch() returns a method on success, or NULL on error.
=head1 EXAMPLES
doc/internal/man3/evp_keymgmt_export_to_provider.pod
+1 -1
View File
@@ -8,7 +8,7 @@ evp_keymgmt_clear_pkey_cache
=head1 SYNOPSIS
#include "internal/evp_int.h"
#include "crypto/evp.h"
void *evp_keymgmt_export_to_provider(EVP_PKEY *pk, EVP_KEYMGMT *keymgmt);
void evp_keymgmt_clear_pkey_cache(EVP_PKEY *pk);
doc/internal/man3/evp_keymgmt_freekey.pod
+1 -1
View File
@@ -14,7 +14,7 @@ evp_keymgmt_importkey_types, evp_keymgmt_exportkey_types
=head1 SYNOPSIS
#include "internal/evp_int.h"
#include "crypto/evp.h"
void *evp_keymgmt_importdomparams(const EVP_KEYMGMT *keymgmt,
const OSSL_PARAM params[]);
doc/internal/man3/openssl_ctx_get_data.pod
+10 -10
View File
@@ -7,7 +7,7 @@ openssl_ctx_get_data, openssl_ctx_run_once, openssl_ctx_onfree
=head1 SYNOPSIS
#include <openssl/ossl_typ.h>
#include <openssl/types.h>
#include "internal/cryptlib.h"
typedef struct openssl_ctx_method {
@@ -24,8 +24,8 @@ openssl_ctx_get_data, openssl_ctx_run_once, openssl_ctx_onfree
=head1 DESCRIPTION
Internally, the OpenSSL library context C<OPENSSL_CTX> is implemented
as a C<CRYPTO_EX_DATA>, which allows data from diverse parts of the
Internally, the OpenSSL library context B<OPENSSL_CTX> is implemented
as a B<CRYPTO_EX_DATA>, which allows data from diverse parts of the
library to be added and removed dynamically.
Each such data item must have a corresponding CRYPTO_EX_DATA index
associated with it. Unlike normal CRYPTO_EX_DATA objects we use static indexes
@@ -34,8 +34,8 @@ indexes internally to the implementation.
See the example further down to see how that's done.
openssl_ctx_get_data() is used to retrieve a pointer to the data in
the library context C<ctx> associated with the given C<index>. An
OPENSSL_CTX_METHOD must be defined and given in the C<meth> parameter. The index
the library context I<ctx> associated with the given I<index>. An
OPENSSL_CTX_METHOD must be defined and given in the I<meth> parameter. The index
for it should be defined in cryptlib.h. The functions through the method are
used to create or free items that are stored at that index whenever a library
context is created or freed, meaning that the code that use a data item of that
@@ -44,18 +44,18 @@ index doesn't have to worry about that, just use the data available.
Deallocation of an index happens automatically when the library
context is freed.
openssl_ctx_run_once is used to run some initialisation routine C<run_once_fn>
exactly once per library context C<ctx> object. Each initialisation routine
openssl_ctx_run_once is used to run some initialisation routine I<run_once_fn>
exactly once per library context I<ctx> object. Each initialisation routine
should be allocate a unique run once index in cryptlib.h.
Any resources allocated via a run once initialisation routine can be cleaned up
using openssl_ctx_onfree. This associates an "on free" routine C<onfreefn> with
the library context C<ctx>. When C<ctx> is freed all associated "on free"
using openssl_ctx_onfree. This associates an "on free" routine I<onfreefn> with
the library context I<ctx>. When I<ctx> is freed all associated "on free"
routines are called.
=head1 RETURN VALUES
openssl_ctx_get_data() returns a pointer on success, or C<NULL> on
openssl_ctx_get_data() returns a pointer on success, or NULL on
failure.
=head1 EXAMPLES
doc/internal/man3/ossl_cmp_asn1_octet_string_set1.pod
+101
View File
@@ -0,0 +1,101 @@
=pod
=head1 NAME
ossl_cmp_log_parse_metadata,
ossl_cmp_add_error_txt,
ossl_cmp_add_error_data,
ossl_cmp_add_error_line,
ossl_cmp_asn1_octet_string_set1,
ossl_cmp_asn1_octet_string_set1_bytes,
ossl_cmp_build_cert_chain
- misc internal utility functions
=head1 SYNOPSIS
#include "cmp_local.h"
const char *ossl_cmp_log_parse_metadata(const char *buf,
OSSL_CMP_severity *level, char **func,
char **file, int *line);
void ossl_cmp_add_error_txt(const char *separator, const char *txt);
#define ossl_cmp_add_error_data(txt)
#define ossl_cmp_add_error_line(txt)
int ossl_cmp_asn1_octet_string_set1(ASN1_OCTET_STRING **tgt,
const ASN1_OCTET_STRING *src);
int ossl_cmp_asn1_octet_string_set1_bytes(ASN1_OCTET_STRING **tgt,
const unsigned char *bytes, int len);
STACK_OF(X509) *ossl_cmp_build_cert_chain(STACK_OF(X509) *certs, X509 *cert);
=head1 DESCRIPTION
ossl_cmp_log_parse_metadata() parses the given message buffer I<buf> populated
by L<OSSL_CMP_log(3)> etc.
according to the pattern OSSL_CMP_LOG_START#level ": %s\n", filling in
the variable pointed to by I<level> with the severity level or -1,
the variable pointed to by I<func> with the function name string or NULL,
the variable pointed to by I<file> with the filename string or NULL, and
the variable pointed to by I<line> with the line number or -1.
Any string returned via I<*func> and I<*file> must be freeed by the caller.
ossl_cmp_add_error_txt() appends text to the extra data field of the last
error message in the OpenSSL error queue, after adding the optional separator
unless data has been empty so far. The text can be of arbitrary length,
which is not possible when using L<ERR_add_error_data(3)> in conjunction with
L<ERR_print_errors_cb(3)>.
ossl_cmp_add_error_data() is a macro calling
ossl_cmp_add_error_txt() with the separator being ":".
ossl_cmp_add_error_line() is a macro calling
ossl_cmp_add_error_txt() with the separator being "\n".
ossl_cmp_asn1_octet_string_set1() frees any previous value of the variable
referenced via the I<tgt> argument and assigns either a copy of
the ASN1_OCTET_STRING given as the I<src> argument or NULL.
It returns 1 on success, 0 on error.
ossl_cmp_asn1_octet_string_set1_bytes() frees any previous value of the variable
referenced via the I<tgt> argument and assigns either a copy of the given byte
string (with the given length) or NULL. It returns 1 on success, 0 on error.
ossl_cmp_build_cert_chain() builds up the certificate chain of cert as high up
as possible using the given X509_STORE containing all possible intermediate
certificates and optionally the (possible) trust anchor(s).
=head1 RETURN VALUES
ossl_cmp_log_parse_metadata() returns the pointer to the actual message text
after the OSSL_CMP_LOG_PREFIX and level and ':' if found in the buffer,
else the beginning of the buffer.
ossl_cmp_add_error_txt()
ossl_cmp_add_error_data(), and
ossl_cmp_add_error_line()
do not return anything.
ossl_cmp_build_cert_chain()
returns NULL on error, else a pointer to a stack of (up_ref'ed) certificates
containing the EE certificate given in the function arguments (cert)
and all intermediate certificates up the chain toward the trust anchor.
The (self-signed) trust anchor is not included.
All other functions return 1 on success, 0 on error.
=head1 HISTORY
The OpenSSL CMP support was added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2007-2019 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
doc/internal/man3/ossl_cmp_ctx_set1_caPubs.pod
+76
View File
@@ -0,0 +1,76 @@
=pod
=head1 NAME
ossl_cmp_ctx_set1_caPubs,
ossl_cmp_ctx_set0_validatedSrvCert,
ossl_cmp_ctx_set_status,
ossl_cmp_ctx_set0_statusString,
ossl_cmp_ctx_set_failInfoCode,
ossl_cmp_ctx_set0_newCert,
ossl_cmp_ctx_set1_extraCertsIn,
ossl_cmp_ctx_set1_recipNonce
- internal functions for managing the CMP client context datastructure
=head1 SYNOPSIS
#include <openssl/cmp.h>
int ossl_cmp_ctx_set1_caPubs(OSSL_CMP_CTX *ctx, STACK_OF(X509) *caPubs);
int ossl_cmp_ctx_set0_validatedSrvCert(OSSL_CMP_CTX *ctx, X509 *cert);
int ossl_cmp_ctx_set_status(OSSL_CMP_CTX *ctx, int status);
int ossl_cmp_ctx_set0_statusString(OSSL_CMP_CTX *ctx,
OSSL_CMP_PKIFREETEXT *text);
int ossl_cmp_ctx_set_failInfoCode(OSSL_CMP_CTX *ctx, int fail_info);
int ossl_cmp_ctx_set0_newCert(OSSL_CMP_CTX *ctx, X509 *cert);
int ossl_cmp_ctx_set1_extraCertsIn(OSSL_CMP_CTX *ctx,
STACK_OF(X509) *extraCertsIn);
int ossl_cmp_ctx_set1_recipNonce(OSSL_CMP_CTX *ctx,
const ASN1_OCTET_STRING *nonce);
=head1 DESCRIPTION
ossl_cmp_ctx_set1_caPubs() copies the given stack of CA certificates
to the caPubs field of the context.
The reference counts of those certificates handled successfully are increased.
ossl_cmp_ctx_set0_validatedSrvCert() sets the validatedSrvCert of the context,
which caches any already validated server cert, or NULL if not available.
ossl_cmp_ctx_set_status() sets the status field of the context.
ossl_cmp_ctx_set0_statusString() sets the statusString field of the context.
ossl_cmp_ctx_set_failInfoCode() sets the error code bits in the failInfoCode
field of the context based on the given OSSL_CMP_PKIFAILUREINFO structure.
ossl_cmp_ctx_set0_newCert() sets the given (newly enrolled) certificate
in the context.
ossl_cmp_ctx_set1_extraCertsIn() sets the extraCertsIn field of the context.
The reference counts of those certificates handled successfully are increased.
ossl_cmp_ctx_set1_recipNonce() sets the given recipient nonce in the context.
=head1 NOTES
CMP is defined in RFC 4210 (and CRMF in RFC 4211).
=head1 RETURN VALUES
All functions return 1 on success, 0 on error.
=head1 HISTORY
The OpenSSL CMP support was added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2007-2018 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
doc/internal/man3/ossl_cmp_sk_X509_add1_cert.pod
+60
View File
@@ -0,0 +1,60 @@
=pod
=head1 NAME
ossl_cmp_sk_X509_add1_cert,
ossl_cmp_sk_X509_add1_certs,
ossl_cmp_X509_STORE_add1_certs,
ossl_cmp_X509_STORE_get1_certs
- functions manipulating lists of certificates
=head1 SYNOPSIS
#include <openssl/cmp_util.h>
int ossl_cmp_sk_X509_add1_cert(STACK_OF(X509) *sk, X509 *cert,
int no_dup, int prepend);
int ossl_cmp_sk_X509_add1_certs(STACK_OF(X509) *sk, STACK_OF(X509) *certs,
int no_self_signed, int no_dups, int prepend);
int ossl_cmp_X509_STORE_add1_certs(X509_STORE *store, STACK_OF(X509) *certs,
int only_self_signed);
STACK_OF(X509) *ossl_cmp_X509_STORE_get1_certs(X509_STORE *store);
=head1 DESCRIPTION
ossl_cmp_sk_X509_add1_cert() appends or prepends (depending on the I<prepend>
argument) a certificate to the given list,
optionally only if it is not already contained.
On success the reference count of the certificate is increased.
ossl_cmp_sk_X509_add1_certs() appends or prepends (depending on the I<prepend>
argument) a list of certificates to the given list,
optionally only if not self-signed and optionally only if not already contained.
The reference counts of those certificates appended successfully are increased.
ossl_cmp_X509_STORE_add1_certs() adds all or only self-signed certificates from
the given stack to given store. The I<certs> parameter may be NULL.
ossl_cmp_X509_STORE_get1_certs() retrieves a copy of all certificates in the
given store.
=head1 RETURN VALUES
ossl_cmp_X509_STORE_get1_certs() returns a list of certificates, NULL on error.
All other functions return 1 on success, 0 on error.
=head1 HISTORY
The OpenSSL CMP support was added in OpenSSL 3.0.
=head1 COPYRIGHT
Copyright 2007-2019 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
doc/internal/man3/ossl_init_thread_deregister.pod
+5 -5
View File
@@ -9,7 +9,7 @@ ossl_init_thread_deregister
=head1 SYNOPSIS
#include "internal/cryptlib_int.h"
#include "crypto/cryptlib.h"
#include <openssl/core.h>
typedef void (*OSSL_thread_stop_handler_fn)(void *arg);
@@ -33,17 +33,17 @@ stopping the stop handler is called (while on that thread) and the code can
clean up the value stored in the thread local variable.
A new stop handler is registerd using the function ossl_init_thread_start().
The B<index> parameter should be a unique value that can be used to identify a
The I<index> parameter should be a unique value that can be used to identify a
set of common stop handlers and is passed in a later call to
ossl_init_thread_deregister. If no later call to ossl_init_thread_deregister is
made then NULL can be passed for this parameter. The B<arg> parameter is passed
made then NULL can be passed for this parameter. The I<arg> parameter is passed
back as an argument to the stop handler when it is later invoked. Finally the
B<handfn> is a function pointer to the stop handler itself.
I<handfn> is a function pointer to the stop handler itself.
In the event that previously registered stop handlers need to be deregistered
then this can be done using the function ossl_init_thread_deregister().
This will deregister all stop handlers (no matter which thread they were
registered for) which the same B<index> value.
registered for) which the same I<index> value.
=head1 RETURN VALUES
doc/internal/man3/ossl_method_construct.pod
+3 -3
View File
@@ -90,7 +90,7 @@ Remove a temporary store.
Look up an already existing method from a store by name.
The store may be given with I<store>.
B<NULL> is a valid value and means that a sub-system default store
NULL is a valid value and means that a sub-system default store
must be used.
This default store should be stored in the library context I<libctx>.
@@ -107,7 +107,7 @@ Places the I<method> created by the construct() function (see below)
in a store.
The store may be given with I<store>.
B<NULL> is a valid value and means that a sub-system default store
NULL is a valid value and means that a sub-system default store
must be used.
This default store should be stored in the library context I<libctx>.
@@ -141,7 +141,7 @@ the reference count reaches zero.
=head1 RETURN VALUES
ossl_method_construct() returns a constructed method on success, or
B<NULL> on error.
NULL on error.
=head1 HISTORY
doc/internal/man3/ossl_namemap_new.pod
+19 -6
View File
@@ -3,7 +3,9 @@
=head1 NAME
ossl_namemap_new, ossl_namemap_free, ossl_namemap_stored,
ossl_namemap_add, ossl_namemap_name2num, ossl_namemap_doall_names
ossl_namemap_add, ossl_namemap_add_n,
ossl_namemap_name2num, ossl_namemap_name2num_n,
ossl_namemap_doall_names
- internal number E<lt>-E<gt> name map
=head1 SYNOPSIS
@@ -16,8 +18,12 @@ ossl_namemap_add, ossl_namemap_name2num, ossl_namemap_doall_names
void ossl_namemap_free(OSSL_NAMEMAP *namemap);
int ossl_namemap_add(OSSL_NAMEMAP *namemap, int number, const char *name);
int ossl_namemap_add_n(OSSL_NAMEMAP *namemap, int number,
const char *name, size_t name_len);
int ossl_namemap_name2num(const OSSL_NAMEMAP *namemap, const char *name);
int ossl_namemap_name2num_n(const OSSL_NAMEMAP *namemap,
const char *name, size_t name_len);
void ossl_namemap_doall_names(const OSSL_NAMEMAP *namemap, int number,
void (*fn)(const char *name, void *data),
void *data);
@@ -43,12 +49,18 @@ ossl_namemap_add() adds a new name to the namemap if it's not already
present.
If the given I<number> is zero, a new number will be allocated to
identify this I<name>.
If the given I<number> is non-zero, the I<name> is added to the set of
If the given I<number> is nonzero, the I<name> is added to the set of
names already associated with that number.
ossl_namemap_name2num() finds the number corresponding to the given
I<name>.
ossl_namemap_add_n() and ossl_namemap_name2num_n() do the same thing
as ossl_namemap_add() and ossl_namemap_name2num(), but take a string
length I<name_len> as well, allowing the caller to use a fragment of
a string as a name.
ossl_namemap_doall_names() walks through all names associated with
I<number> in the given I<namemap> and calls the function I<fn> for
each of them.
@@ -60,15 +72,16 @@ pass extra data for that function to use.
ossl_namemap_new() and ossl_namemap_stored() return the pointer to a
B<OSSL_NAMEMAP>, or NULL on error.
ossl_namemap_add() returns the number associated with the added
string, or zero on error.
ossl_namemap_add() and ossl_namemap_add_n() return the number associated
with the added string, or zero on error.
ossl_namemap_num2names() returns a pointer to a NULL-terminated list of
pointers to the names corresponding to the given number, or NULL if
it's undefined in the given B<OSSL_NAMEMAP>.
ossl_namemap_name2num() returns the number corresponding to the given
name, or 0 if it's undefined in the given B<OSSL_NAMEMAP>.
ossl_namemap_name2num() and ossl_namemap_name2num_n() return the number
corresponding to the given name, or 0 if it's undefined in the given
B<OSSL_NAMEMAP>.
=head1 NOTES
doc/internal/man3/ossl_param_bld_init.pod
+30 -22
View File
@@ -15,7 +15,7 @@ ossl_param_bld_push_octet_ptr
=head1 SYNOPSIS
=for comment generic
=for openssl generic
#include "internal/params_build.h"
@@ -48,14 +48,14 @@ ossl_param_bld_push_octet_ptr
=head1 DESCRIPTION
A collection of utility functions that simplify the creation of OSSL_PARAM
arrays. The B<TYPE> names are as per L<OSSL_PARAM_int(3)>.
arrays. The B<I<TYPE>> names are as per L<OSSL_PARAM_int(3)>.
ossl_param_bld_init() initialises the OSSL_PARAM_BLD structure so that values
can be added.
Any existing values are cleared.
ossl_param_bld_to_param() converts a built up OSSL_PARAM_BLD structure
B<bld> into an allocated OSSL_PARAM array.
I<bld> into an allocated OSSL_PARAM array.
The OSSL_PARAM array and all associated storage must be freed by calling
ossl_param_bld_free() with the functions return value.
@@ -64,44 +64,52 @@ ossl_param_bld_to_param().
ossl_param_bld_to_param_ex() behaves like ossl_param_bld_to_param(), except that
no additional memory is allocated.
An OSSL_PARAM array of at least B<param_n> elements is passed in as B<params>.
An OSSL_PARAM array of at least I<param_n> elements is passed in as I<params>.
The auxiliary storage for the parameters is a block of memory pointed to
by B<data> of at least B<data_n> bytes in size.
by I<data> of at least I<data_n> bytes in size.
If required, secure memory for private BIGNUMs should be pointed to by
B<secure> of at least B<secure_n> bytes in size.
I<secure> of at least I<secure_n> bytes in size.
ossl_param_bld_push_TYPE() are a series of functions which will create
OSSL_PARAM objects of the specified size and correct type for the B<val>
=begin comment
POD is pretty good at recognising function names and making them appropriately
bold... however, when part of the function name is variable, we have to help
the processor along
=end comment
B<ossl_param_bld_push_I<TYPE>>() are a series of functions which will create
OSSL_PARAM objects of the specified size and correct type for the I<val>
argument.
B<val> is stored by value and an expression or auto variable can be used.
I<val> is stored by value and an expression or auto variable can be used.
ossl_param_bld_push_BN() is a function that will create an OSSL_PARAM object
that holds the specified BIGNUM B<bn>.
If B<bn> is marked as being securely allocated, it's OSSL_PARAM representation
that holds the specified BIGNUM I<bn>.
If I<bn> is marked as being securely allocated, it's OSSL_PARAM representation
will also be securely allocated.
The B<bn> argument is stored by reference and the underlying BIGNUM object
The I<bn> argument is stored by reference and the underlying BIGNUM object
must exist until after ossl_param_bld_to_param() has been called.
ossl_param_bld_push_utf8_string() is a function that will create an OSSL_PARAM
object that references the UTF8 string specified by B<buf>.
If the length of the string, B<bsize>, is zero then it will be calculated.
The string that B<buf> points to is stored by reference and must remain in
object that references the UTF8 string specified by I<buf>.
If the length of the string, I<bsize>, is zero then it will be calculated.
The string that I<buf> points to is stored by reference and must remain in
scope until after ossl_param_bld_to_param() has been called.
ossl_param_bld_push_octet_string() is a function that will create an OSSL_PARAM
object that references the octet string specified by B<buf> and <bsize>.
The memory that B<buf> points to is stored by reference and must remain in
object that references the octet string specified by I<buf> and <bsize>.
The memory that I<buf> points to is stored by reference and must remain in
scope until after ossl_param_bld_to_param() has been called.
ossl_param_bld_push_utf8_ptr() is a function that will create an OSSL_PARAM
object that references the UTF8 string specified by B<buf>.
If the length of the string, B<bsize>, is zero then it will be calculated.
The string B<buf> points to is stored by reference and must remain in
object that references the UTF8 string specified by I<buf>.
If the length of the string, I<bsize>, is zero then it will be calculated.
The string I<buf> points to is stored by reference and must remain in
scope until the OSSL_PARAM array is freed.
ossl_param_bld_push_octet_ptr() is a function that will create an OSSL_PARAM
object that references the octet string specified by B<buf>.
The memory B<buf> points to is stored by reference and must remain in
object that references the octet string specified by I<buf>.
The memory I<buf> points to is stored by reference and must remain in
scope until the OSSL_PARAM array is freed.
=head1 RETURN VALUES
doc/internal/man3/ossl_prov_util_nid_to_name.pod
+2 -2
View File
@@ -7,14 +7,14 @@ ossl_prov_util_nid_to_name
=head1 SYNOPSIS
#include "internal/providercommon.h"
#include "prov/providercommon.h"
const char *ossl_prov_util_nid_to_name(int nid);
=head1 DESCRIPTION
The ossl_prov_util_nid_to_name() returns the name of an algorithm given a NID
in the B<nid> parameter. For the default and legacy providers it is equivalent
in the I<nid> parameter. For the default and legacy providers it is equivalent
to calling OBJ_nid2sn(). The FIPS provider does not have the object database
code available to it (because that code relies on the ASN.1 code), so this
function is a static lookup of all known FIPS algorithm NIDs.
doc/internal/man3/ossl_provider_new.pod
+1 -1
View File
@@ -184,7 +184,7 @@ ossl_provider_new().
ossl_provider_dso() returns a reference to the module, for providers
that come in the form of loadable modules.
ossl_provider_module_name() returns the file name of the module, for
ossl_provider_module_name() returns the filename of the module, for
providers that come in the form of loadable modules.
ossl_provider_module_path() returns the full path of the module file,
doc/internal/man3/rand_bytes_ex.pod
+3 -3
View File
@@ -7,7 +7,7 @@ rand_bytes_ex, rand_priv_bytes_ex
=head1 SYNOPSIS
#include "internal/rand_int.h"
#include "crypto/rand.h"
int rand_bytes_ex(OPENSSL_CTX *ctx, unsigned char *buf, int num);
int rand_priv_bytes_ex(OPENSSL_CTX *ctx, unsigned char *buf, int num);
@@ -16,9 +16,9 @@ rand_bytes_ex, rand_priv_bytes_ex
rand_bytes_ex() and rand_priv_bytes_ex() are the equivalent of RAND_bytes() and
RAND_priv_bytes() in the public API except that they both take an additional
B<ctx> parameter.
I<ctx> parameter.
The DRBG used for the operation is the public or private DRBG associated with
the specified B<ctx>. The parameter can be NULL, in which case
the specified I<ctx>. The parameter can be NULL, in which case
the default library ctx is used.
If the default RAND_METHOD has been changed then for compatibility reasons the
RAND_METHOD will be used in preference and the DRBG of the library context
doc/internal/man7/build.info.pod
+602
View File
@@ -0,0 +1,602 @@
=pod
=head1 NAME
build.info - Building information files
=head1 SYNOPSIS
B<IF[>0|1B<]>
B<ELSIF[>0|1B<]>
B<ELSE>
B<ENDIF>
B<SUBDIRS=> I<dir> ...
B<PROGRAMS=> I<name> ...
B<LIBS=> I<name> ...
B<MODULES=> I<name> ...
B<SCRIPTS=> I<name> ...
B<DEPEND[>I<item>B<]=> I<otheritem> ...
B<GENERATE[>I<item>B<]=> I<generator> I<generator-args> ...
B<SOURCE[>I<item>B<]=> I<file> ...
B<SHARED_SOURCE[>I<item>B<]=> I<file> ...
B<DEFINE[>I<item>B<]=> I<name>[B<=>I<value>] ...
B<INCLUDE[>I<item>B<]=> I<dir> ...
B<$>I<VARIABLE>B<=>I<value>
=head1 DESCRIPTION
OpenSSL's build system revolves around three questions:
=over 4
=item What to build for?
This is about choice of platform (combination of hardware, operating
system, and toolchain).
=item What to build?
This is about having all the information on what needs to be built and
from what.
=item How to build it?
This is about build file generation.
=back
This document is all about the second item, "What to build?", and most
of all, how to specify that information.
For some terms used in this document, please see the L</GLOSSARY> at
the end.
=head2 F<build.info> files
F<build.info> files are meta data files for OpenSSL's built file
generators, and are used to specify exactly what end product files
(programs, libraries, modules or scripts) are to be produced, and from
what sources.
Intermediate files, such as object files, are seldom refered to at
all. They sometimes can be, if there's a need, but this should happen
very rarely, and support for that sort of thing is added on as-needed
basis.
Any time a directory or file is expected in a statement value, Unix
syntax must be used, which means that the slash C</> must be used as
the directory separator.
=head2 General syntax
=head3 Comments
Comments are any line that start with a hash sign (C<#>). The hash
sign may be preceded by any number of horizontal spaces.
=head3 Filenames
F<build.info> files are platform agnostic. This means that there is
some information in them that is representative rather than specific.
This is particularly visible with end product names, they work more
like a tag than as the actual filename that's going to be produced.
This is because different platforms have different decorations on
different types of files.
For example, if we say that we want to produce a program C<foo>, it
would look like this:
PROGRAM=foo
However, the program filename may end up being just C<foo> (typical
for Unix), or C<foo.exe> (typical for Windows), or even C<BLAH$FOO.EXE>
(possible on VMS, depending on policy).
These platform specific decorations are not the concern of
F<build.info> files. The build file generators are responsible for
transforming these platform agnostic names to their platform specific
counterparts.
=head3 Statements
With the exception of variables and conditions, the general statement
syntax is one of:
=over 4
=item B<I<KEYWORD>> B<=> I<value> ...
=item B<I<KEYWORD>[>I<item>B<]> B<=> I<value> ...
=back
Every B<I<KEYWORD>> represents some particular type of information.
The first form (sometimes called "plain statement") is used to specify
information on what end products need to be built, for example:
PROGRAMS=foo bar
LIBS=libpoly libcookie
MODULES=awesome-plugin
SCRIPTS=tool1 tool2
SUBDIRS=dir1 dir2
This says that we want to build programs C<foo> and C<bar>, the
libraries C<libpoly> and C<libcookie>, an awesome plugin module
C<awesome-plugin>, a couple of scripts C<tool1> and C<tool2>, and
finally that there are more F<build.info> files in subdirectories
C<dir1> and C<dir2>.
The second form (sometimes called "indexed statement") is used to
specify further details for existing items, for example:
SOURCE[foo]=foo.c details.c
DEPEND[foo]=libcookie
This says that the program C<foo> is built from the source files
F<foo.c> and F<details.c>, and that it depends on the library
C<libcookie> (in other words, the library will be included when
linking that program together).
For any indexed statement for which the item hasn't been specified
through any plain statement, or where the item exists but the indexed
statement does not apply, the value is simply ignored by the build
file generators.
=head3 Statement attributes
Some statements can have attributes added to them, to allow for
variations on how they are treated.
=over 4
=item B<I<KEYWORD>{> I<attrib> | I<attrib>B<=>I<attrib-value> [,...]B<}>
B<=> I<value> ...
=item B<I<KEYWORD>[>I<item>B<]{> I<attrib> | I<attrib>B<=>I<attrib-value>
[,...]B<}> B<=> I<value> ...
=back
Attributes are passed as they are to the build file generators, and
the exact interpretation of those attributes is entirely up to them
(see L</Known attributes> below for details).
A current example:
LIBS{noinst,has_main}=libtestutil.a
This says that the static library C<libtestutil.a> should not be
installed (C<noinst>), and that it includes an object file that has
the C<main> symbol (C<has_main>). Most platforms don't need to know
the latter, but there are some where the program linker will not look
for C<main> in libraries unless it's explicitly told so, so this is
way to tell the build file generator to emit the necessary command
options to make that happen.
Attributes are accumulated globally. This means that a library could
be given like this in different places:
# Location 1
LIBS=libwhatever
# Location 2
LIBS{noinst}=libwhatever
# Location 3
LIBS{has_main}=libwhatever
The end result is that the library C<libwhatever> will have the
attributes C<noinst> and C<has_main> attached to it.
=head3 Quoting and tokens
Statement values are normally split into a list of tokens, separated
by spaces.
To avoid having a value split up into several tokens, they may be
quoted with double (C<">) or single (C<'>) quotes.
For example:
PROGRAMS=foo "space cadet" bar
This says that we sant to build three programs, C<foo>, C<space cadet>
and C<bar>.
=head3 Conditionals
F<build.info> files include a very simple condition system, involving
the following keywords:
=over 4
=item B<IF[>0|1B<]>
=item B<ELSIF[>0|1B<]>
=item B<ELSE>
=item B<ENDIF>
=back
This works like any condition system with similar syntax, and the
condition value in B<IF> and B<ELSIF> can really be any literal value
that perl can interpret as true or false.
Conditional statements are nesting.
In itself, this is not very powerful, but together with L</Perl nuggets>,
it can be.
=head3 Variables
F<build.info> handles simple variables. They are defined by
assignment:
=over 4
=item B<$>I<NAME> B<=> I<value>
=back
These variables can then be used as part of any statement value or
indexed statement item. This should be used with some care, as
I<variables are expanded into their values before the value they are
part of is tokenized>.
I<Variable assignment values are not tokenized.>
=head2 Scope
Most of the statement values are accumulated globally from all the
F<build.info> files that are digested. There are two exceptions,
F<build.info> variables and B<SUBDIRS> statement, for which the scope
is the F<build.info> file they are in.
=head2 Perl nuggets
Whenever a F<build.info> file is read, it is passed through the Perl
template processor L<OpenSSL::Template>, which is a small extension of
L<Text::Template>.
Perl nuggets are anything between C<{-> and C<-}>, and whatever the
result from such a nugget is, that value will replace the nugget in
text form. This is useful to get dynamically generated F<build.info>
statements, and is most often seen used together with the B<IF> and
B<ELSIF> conditional statements.
For example:
IF[{- $disabled{something} -}]
# do whatever's needed when "something" is disabled
ELSIF[{- $somethingelse eq 'blah' -}]
# do whatever's needed to satisfy this condition
ELSE
# fallback
ENDIF
Normal Perl scope applies, so it's possible to have an initial perl
nugget that sets diverse global variables that are used in later
nuggets. Each nugget is a Perl block of its own, so B<my> definitions
are only in scope within the same nugget, while B<our> definitions are
in scope within the whole F<build.info> file.
=head1 REFERENCE
=head2 Conditionals
=over 4
=item B<IF[>0|1B<]>
If the condition is true (represented as C<1> here), everything
between this B<IF> and the next corresponding B<ELSIF> or B<ELSE>
applies, and the rest until the corresponding B<ENDIF> is skipped
over.
If the condition is false (represented as C<0> here), everything
from this B<IF> is skipped over until the next corresponding B<ELSIF>
or B<ELSE>, at which point processing continues.
=item B<ELSE>
If F<build.info> statements have been skipped over to this point since
the corresponding B<IF> or B<ELSIF>, F<build.info> processing starts
again following this line.
=item B<ELSIF[>0|1B<]>
This is B<ELSE> and B<IF> combined.
=item B<ENDIF>
Marks the end of a conditional.
=back
=head2 Plain statements
=over 4
=item B<SUBDIRS=> I<dir> ...
This instructs the F<build.info> reader to also read the F<build.info>
file in every specified directory. All directories should be given
relative to the location of the current F<build.info> file.
=item B<PROGRAMS=> I<name> ...
Collects names of programs that should be built.
B<PROGRAMS> statements may have attributes, which apply to all the
programs given in such a statement. For example:
PROGRAMS=foo
PROGRAMS{noinst}=bar
With those two lines, the program C<foo> will not have the attribute
C<noinst>, while the program C<bar> will.
=item B<LIBS=> I<name> ...
Collects names of libraries that should be built.
The normal case is that libraries are built in both static and shared
form. However, if a name ends with C<.a>, only the static form will
be produced.
Similarly, libraries may be referred in indexed statements as just the
plain name, or the name including the ending C<.a>. If given without
the ending C<.a>, any form available will be used, but if given with
the ending C<.a>, the static library form is used unconditionally.
B<LIBS> statements may have attributes, which apply to all the
libraries given in such a statement. For example:
LIBS=libfoo
LIBS{noinst}=libbar
With those two lines, the library C<libfoo> will not have the
attribute C<noinst>, while the library C<libbar> will.
=item B<MODULES=> I<name>
Collects names of dynamically loadable modules that should be built.
B<MODULES> statements may have attributes, which apply to all the
modules given in such a statement. For example:
MODULES=foo
MODULES{noinst}=bar
With those two lines, the module C<foo> will not have the attribute
C<noinst>, while the module C<bar> will.
=item B<SCRIPTS=> I<name>
Collects names of scripts that should be built, or that just exist.
That is how they differ from programs, as programs are always expected
to be compiled from multiple sources.
B<SCRIPTS> statements may have attributes, which apply to all the
scripts given in such a statement. For example:
SCRIPTS=foo
SCRIPTS{noinst}=bar
With those two lines, the script C<foo> will not have the attribute
C<noinst>, while the script C<bar> will.
=back
=head2 Indexed statements
=over 4
=item B<DEPEND[>I<item>B<]> B<=> I<file> ...
Collects dependencies, where I<item> depends on the given I<file>s.
As a special case, the I<item> may be empty, for which the build file
generators should make the whole build depend on the given I<file>s,
rather than some specific I<item>.
The I<item> may be any program, library, module, script, or any
filename used as a value anywhere.
B<DEPEND> statements may have attributes, which apply to each
individual dependency in such a statement. For example:
DEPEND[libfoo.a]=libmandatory.a
DEPEND[libfoo.a]{weak}=libbar.a libcookie.a
With those statements, the dependency between C<libfoo.a> and
C<libmandatory.a> is strong, while the dependency between C<libfoo.a>
and C<libbar.a> and C<libcookie.a> is weak. See the description of
B<weak> in L</Known attributes> for more information.
=item B<GENERATE[>I<item>B<]> B<=> I<generator> I<generator-arg> ...
This specifies that the I<item> is generated using the I<generator>
with the I<generator-arg>s as arguments, plus the name of the output
file as last argument.
For I<generator>s where this is applicable, any B<INCLUDE> statement
for the same I<item> will be given to the I<generator> as its
inclusion directories. Likewise, any B<DEPEND> statement for the same
I<item> will be given to the I<generator> as an extra file or module
to load, where this is applicable.
The build file generators must be able to recognise the I<generator>.
Currently, they at least recognise files ending in C<.pl>, and will
execute them to generate the I<item>, and files ending in C<.in>,
which will be used as input for L<OpenSSL::Template> to generate
I<item> (in other words, we use the exact same style of
L</Perl nuggets> mechanism that is used to read F<build.info> files).
=item B<SOURCE[>I<item>B<]> B<=> I<file> ...
Collects filenames that will be used as source files for I<item>.
The I<item> must be a singular item, and may be any program, library,
module or script given with B<PROGRAMS>, B<LIBS>, B<MODULES> and
B<SCRIPTS>.
Static libraries may be sources. In that case, its object files are
used directly when building I<item> instead of relying on library
dependency and symbol resolution (through B<DEPEND> statements).
=item B<SHARED_SOURCE[>I<item>B<]> B<=> I<file> ...
Collects filenames that will be used as source files for I<item>.
The I<item> must be a singular item, and may be any library or module
given with B<LIBS> or B<MODULES>. For libraries, the given filenames
are only used for their shared form, so if the item is a library name
ending with C<.a>, the filenames will be ignored.
=item B<DEFINE[>I<item>B<]> B<=> I<name>[B<=>I<value>] ...
Collects I<name> / I<value> pairs (or just I<name> with no defined
value if no I<value> is given) associated with I<item>.
The build file generators will decide what to do with them. For
example, these pairs should become C macro definitions whenever a
C<.c> file is built into an object file.
=item B<INCLUDE[>I<item>B<]> B<=> I<dir> ...
Collects inclusion directories that will be used when building the
I<item> components (object files and whatever else). This is used at
the discretion of the build file generators.
=back
=head2 Known attributes
Note: this will never be a complete list of attributes.
=over 4
=item B<noinst>
This is used to specify that the end products this is set for should
not be installed, that they are only internal. This is applicable on
internal static libraries, or on test programs.
=item B<misc>
This is used with B<SCRIPTS>, to specify that some scripts should be
installed in the "misc" directory rather than the normal program
directory.
=item B<engine>
This is used with B<MODULES>, to specify what modules are engines and
should be installed in the engines directory instead of the modules
directory.
=item B<weak>
This is used with B<DEPEND> where libraries are involved, to specify
that the dependency between two libraries is weak and is only there to
infer order.
Without this attribute, a dependency between two libraries, expressed
like this, means that if C<libfoo.a> appears in a linking command
line, so will C<libmandatory.a>:
DEPEND[libfoo.a]=libmandatory.a
With this attribute, a dependency between two libraries, expressed
like this, means that if I<both> C<libfoo.a> and C<libmandatory.a>
appear in a linking command line (because of recursive dependencies
through other libraries), they will be ordered in such a way that this
dependency is maintained:
DEPEND[libfoo.a]{weak}=libfoo.a libcookie.a
This is useful in complex dependecy trees where two libraries can be
used as alternatives for each other. In this example, C<lib1.a> and
C<lib2.a> have alternative implementations of the same thing, and
C<libmandatory.a> has unresolved references to that same thing, and is
therefore depending on either of them, but not both at the same time:
DEPEND[program1]=libmandatory.a lib1.a
DEPEND[program2]=libmandatory.a lib2.a
DEPEND[libmandatory]{weak}=lib1.a lib2.a
=back
=head1 GLOSSARY
=over 4
=item "build file"
This is any platform specific file that describes the complete build,
with platform specific commands. On Unix, this is typically
F<Makefile>; on VMS, this is typically F<descrip.mms>.
=item "build file generator"
Perl code that generates build files, given configuration data and
data collected from F<build.info> files.
=item "plain statement"
Any F<build.info> statement of the form B<I<KEYWORD>>=I<values>, with
the exception of conditional statements and variable assignments.
=item "indexed statement"
Any F<build.info> statement of the form B<I<KEYWORD>[>I<item>B<]=>I<values>,
with the exception of conditional statements.
=item "intermediate file"
Any file that's an intermediate between a source file and an end
product.
=item "end product"
Any file that is mentioned in the B<PROGRAMS>, B<LIBS>, B<MODULES> or
B<SCRIPTS>.
=back
=head1 SEE ALSO
For OpenSSL::Template documentation,
C<perldoc -o man util/perl/OpenSSL/Template.pm>
L<Text::Temlate|https://metacpan.org/pod/Text::Template>
=head1 COPYRIGHT
Copyright 2019 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