mirror of https://github.com/openssl/openssl
Add documentation for newly added ASN1 functions
Reviewed-by: Shane Lontis <shane.lontis@oracle.com> Reviewed-by: Paul Dale <pauli@openssl.org> (Merged from https://github.com/openssl/openssl/pull/15591)
This commit is contained in:
Matt Caswell
Pauli
parent
d2b6c06274
commit
3d9d1ce529
|
|
@ -471,6 +471,10 @@ DEPEND[html/man3/ADMISSIONS.html]=man3/ADMISSIONS.pod
|
|||
GENERATE[html/man3/ADMISSIONS.html]=man3/ADMISSIONS.pod
|
||||
DEPEND[man/man3/ADMISSIONS.3]=man3/ADMISSIONS.pod
|
||||
GENERATE[man/man3/ADMISSIONS.3]=man3/ADMISSIONS.pod
|
||||
DEPEND[html/man3/ASN1_EXTERN_FUNCS.html]=man3/ASN1_EXTERN_FUNCS.pod
|
||||
GENERATE[html/man3/ASN1_EXTERN_FUNCS.html]=man3/ASN1_EXTERN_FUNCS.pod
|
||||
DEPEND[man/man3/ASN1_EXTERN_FUNCS.3]=man3/ASN1_EXTERN_FUNCS.pod
|
||||
GENERATE[man/man3/ASN1_EXTERN_FUNCS.3]=man3/ASN1_EXTERN_FUNCS.pod
|
||||
DEPEND[html/man3/ASN1_INTEGER_get_int64.html]=man3/ASN1_INTEGER_get_int64.pod
|
||||
GENERATE[html/man3/ASN1_INTEGER_get_int64.html]=man3/ASN1_INTEGER_get_int64.pod
|
||||
DEPEND[man/man3/ASN1_INTEGER_get_int64.3]=man3/ASN1_INTEGER_get_int64.pod
|
||||
|
|
@ -511,6 +515,10 @@ DEPEND[html/man3/ASN1_TYPE_get.html]=man3/ASN1_TYPE_get.pod
|
|||
GENERATE[html/man3/ASN1_TYPE_get.html]=man3/ASN1_TYPE_get.pod
|
||||
DEPEND[man/man3/ASN1_TYPE_get.3]=man3/ASN1_TYPE_get.pod
|
||||
GENERATE[man/man3/ASN1_TYPE_get.3]=man3/ASN1_TYPE_get.pod
|
||||
DEPEND[html/man3/ASN1_aux_cb.html]=man3/ASN1_aux_cb.pod
|
||||
GENERATE[html/man3/ASN1_aux_cb.html]=man3/ASN1_aux_cb.pod
|
||||
DEPEND[man/man3/ASN1_aux_cb.3]=man3/ASN1_aux_cb.pod
|
||||
GENERATE[man/man3/ASN1_aux_cb.3]=man3/ASN1_aux_cb.pod
|
||||
DEPEND[html/man3/ASN1_generate_nconf.html]=man3/ASN1_generate_nconf.pod
|
||||
GENERATE[html/man3/ASN1_generate_nconf.html]=man3/ASN1_generate_nconf.pod
|
||||
DEPEND[man/man3/ASN1_generate_nconf.3]=man3/ASN1_generate_nconf.pod
|
||||
|
|
@ -519,6 +527,10 @@ DEPEND[html/man3/ASN1_item_d2i_bio.html]=man3/ASN1_item_d2i_bio.pod
|
|||
GENERATE[html/man3/ASN1_item_d2i_bio.html]=man3/ASN1_item_d2i_bio.pod
|
||||
DEPEND[man/man3/ASN1_item_d2i_bio.3]=man3/ASN1_item_d2i_bio.pod
|
||||
GENERATE[man/man3/ASN1_item_d2i_bio.3]=man3/ASN1_item_d2i_bio.pod
|
||||
DEPEND[html/man3/ASN1_item_new.html]=man3/ASN1_item_new.pod
|
||||
GENERATE[html/man3/ASN1_item_new.html]=man3/ASN1_item_new.pod
|
||||
DEPEND[man/man3/ASN1_item_new.3]=man3/ASN1_item_new.pod
|
||||
GENERATE[man/man3/ASN1_item_new.3]=man3/ASN1_item_new.pod
|
||||
DEPEND[html/man3/ASN1_item_sign.html]=man3/ASN1_item_sign.pod
|
||||
GENERATE[html/man3/ASN1_item_sign.html]=man3/ASN1_item_sign.pod
|
||||
DEPEND[man/man3/ASN1_item_sign.3]=man3/ASN1_item_sign.pod
|
||||
|
|
@ -2825,6 +2837,7 @@ DEPEND[man/man3/s2i_ASN1_IA5STRING.3]=man3/s2i_ASN1_IA5STRING.pod
|
|||
GENERATE[man/man3/s2i_ASN1_IA5STRING.3]=man3/s2i_ASN1_IA5STRING.pod
|
||||
IMAGEDOCS[man3]=
|
||||
HTMLDOCS[man3]=html/man3/ADMISSIONS.html \
|
||||
html/man3/ASN1_EXTERN_FUNCS.html \
|
||||
html/man3/ASN1_INTEGER_get_int64.html \
|
||||
html/man3/ASN1_INTEGER_new.html \
|
||||
html/man3/ASN1_ITEM_lookup.html \
|
||||
|
|
@ -2835,8 +2848,10 @@ html/man3/ASN1_STRING_new.html \
|
|||
html/man3/ASN1_STRING_print_ex.html \
|
||||
html/man3/ASN1_TIME_set.html \
|
||||
html/man3/ASN1_TYPE_get.html \
|
||||
html/man3/ASN1_aux_cb.html \
|
||||
html/man3/ASN1_generate_nconf.html \
|
||||
html/man3/ASN1_item_d2i_bio.html \
|
||||
html/man3/ASN1_item_new.html \
|
||||
html/man3/ASN1_item_sign.html \
|
||||
html/man3/ASYNC_WAIT_CTX_new.html \
|
||||
html/man3/ASYNC_start_job.html \
|
||||
|
|
@ -3414,6 +3429,7 @@ html/man3/i2d_re_X509_tbs.html \
|
|||
html/man3/o2i_SCT_LIST.html \
|
||||
html/man3/s2i_ASN1_IA5STRING.html
|
||||
MANDOCS[man3]=man/man3/ADMISSIONS.3 \
|
||||
man/man3/ASN1_EXTERN_FUNCS.3 \
|
||||
man/man3/ASN1_INTEGER_get_int64.3 \
|
||||
man/man3/ASN1_INTEGER_new.3 \
|
||||
man/man3/ASN1_ITEM_lookup.3 \
|
||||
|
|
@ -3424,8 +3440,10 @@ man/man3/ASN1_STRING_new.3 \
|
|||
man/man3/ASN1_STRING_print_ex.3 \
|
||||
man/man3/ASN1_TIME_set.3 \
|
||||
man/man3/ASN1_TYPE_get.3 \
|
||||
man/man3/ASN1_aux_cb.3 \
|
||||
man/man3/ASN1_generate_nconf.3 \
|
||||
man/man3/ASN1_item_d2i_bio.3 \
|
||||
man/man3/ASN1_item_new.3 \
|
||||
man/man3/ASN1_item_sign.3 \
|
||||
man/man3/ASYNC_WAIT_CTX_new.3 \
|
||||
man/man3/ASYNC_start_job.3 \
|
||||
|
|
|
|||
|
|
@ -0,0 +1,181 @@
|
|||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
ASN1_EXTERN_FUNCS, ASN1_ex_d2i, ASN1_ex_d2i_ex, ASN1_ex_i2d, ASN1_ex_new_func,
|
||||
ASN1_ex_new_ex_func, ASN1_ex_free_func, ASN1_ex_print_func,
|
||||
IMPLEMENT_EXTERN_ASN1
|
||||
- ASN.1 external function support
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/asn1t.h>
|
||||
|
||||
typedef int ASN1_ex_d2i(ASN1_VALUE **pval, const unsigned char **in, long len,
|
||||
const ASN1_ITEM *it, int tag, int aclass, char opt,
|
||||
ASN1_TLC *ctx);
|
||||
typedef int ASN1_ex_d2i_ex(ASN1_VALUE **pval, const unsigned char **in, long len,
|
||||
const ASN1_ITEM *it, int tag, int aclass, char opt,
|
||||
ASN1_TLC *ctx, OSSL_LIB_CTX *libctx,
|
||||
const char *propq);
|
||||
typedef int ASN1_ex_i2d(const ASN1_VALUE **pval, unsigned char **out,
|
||||
const ASN1_ITEM *it, int tag, int aclass);
|
||||
typedef int ASN1_ex_new_func(ASN1_VALUE **pval, const ASN1_ITEM *it);
|
||||
typedef int ASN1_ex_new_ex_func(ASN1_VALUE **pval, const ASN1_ITEM *it,
|
||||
OSSL_LIB_CTX *libctx, const char *propq);
|
||||
typedef void ASN1_ex_free_func(ASN1_VALUE **pval, const ASN1_ITEM *it);
|
||||
typedef int ASN1_ex_print_func(BIO *out, const ASN1_VALUE **pval,
|
||||
int indent, const char *fname,
|
||||
const ASN1_PCTX *pctx);
|
||||
|
||||
struct ASN1_EXTERN_FUNCS_st {
|
||||
void *app_data;
|
||||
ASN1_ex_new_func *asn1_ex_new;
|
||||
ASN1_ex_free_func *asn1_ex_free;
|
||||
ASN1_ex_free_func *asn1_ex_clear;
|
||||
ASN1_ex_d2i *asn1_ex_d2i;
|
||||
ASN1_ex_i2d *asn1_ex_i2d;
|
||||
ASN1_ex_print_func *asn1_ex_print;
|
||||
ASN1_ex_new_ex_func *asn1_ex_new_ex;
|
||||
ASN1_ex_d2i_ex *asn1_ex_d2i_ex;
|
||||
};
|
||||
typedef struct ASN1_EXTERN_FUNCS_st ASN1_EXTERN_FUNCS;
|
||||
|
||||
#define IMPLEMENT_EXTERN_ASN1(sname, tag, fptrs)
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
ASN.1 data structures templates are typically defined in OpenSSL using a series
|
||||
of macros such as ASN1_SEQUENCE(), ASN1_SEQUENCE_END() and so on. Instead
|
||||
templates can also be defined based entirely on external functions. These
|
||||
external functions are called to perform operations such as creating a new
|
||||
B<ASN1_VALUE> or converting an B<ASN1_VALUE> to or from DER encoding.
|
||||
|
||||
The macro IMPLEMENT_EXTERN_ASN1() can be used to create such an externally
|
||||
defined structure. The name of the structure should be supplied in the I<sname>
|
||||
parameter. The tag for the structure (e.g. typically B<V_ASN1_SEQUENCE>) should
|
||||
be supplied in the I<tag> parameter. Finally a pointer to an
|
||||
B<ASN1_EXTERN_FUNCS> structure should be supplied in the I<fptrs> parameter.
|
||||
|
||||
The B<ASN1_EXTERN_FUNCS> structure has the following entries.
|
||||
|
||||
=over 4
|
||||
|
||||
=item I<app_data>
|
||||
|
||||
A pointer to arbitrary application specific data.
|
||||
|
||||
=item I<asn1_ex_new>
|
||||
|
||||
A "new" function responsible for constructing a new B<ASN1_VALUE> object. The
|
||||
newly constructed value should be stored in I<*pval>. The I<it> parameter is a
|
||||
pointer to the B<ASN1_ITEM> template object created via the
|
||||
IMPLEMENT_EXTERN_ASN1() macro.
|
||||
|
||||
Returns a positive value on success or 0 on error.
|
||||
|
||||
=item I<asn1_ex_free>
|
||||
|
||||
A "free" function responsible for freeing the B<ASN1_VALUE> passed in I<*pval>
|
||||
that was previously allocated via a "new" function. The I<it> parameter is a
|
||||
pointer to the B<ASN1_ITEM> template object created via the
|
||||
IMPLEMENT_EXTERN_ASN1() macro.
|
||||
|
||||
=item I<asn1_ex_clear>
|
||||
|
||||
A "clear" function responsible for clearing any data in the B<ASN1_VALUE> passed
|
||||
in I<*pval> and making it suitable for reuse. The I<it> parameter is a pointer
|
||||
to the B<ASN1_ITEM> template object created via the IMPLEMENT_EXTERN_ASN1()
|
||||
macro.
|
||||
|
||||
=item I<asn1_ex_d2i>
|
||||
|
||||
A "d2i" function responsible for converting DER data with the tag I<tag> and
|
||||
class I<class> into an B<ASN1_VALUE>. If I<*pval> is non-NULL then the
|
||||
B<ASN_VALUE> it points to should be reused. Otherwise a new B<ASN1_VALUE>
|
||||
should be allocated and stored in I<*pval>. I<*in> points to the DER data to be
|
||||
decoded and I<len> is the length of that data. After decoding I<*in> should be
|
||||
updated to point at the next byte after the decoded data. If the B<ASN1_VALUE>
|
||||
is considered optional in this context then I<opt> will be nonzero. Otherwise
|
||||
it will be zero. The I<it> parameter is a pointer to the B<ASN1_ITEM> template
|
||||
object created via the IMPLEMENT_EXTERN_ASN1() macro. A pointer to the current
|
||||
B<ASN1_TLC> context (which may be required for other ASN1 function calls) is
|
||||
passed in the I<ctx> parameter.
|
||||
|
||||
The I<asn1_ex_d2i> entry may be NULL if I<asn1_ex_d2i_ex> has been specified
|
||||
instead.
|
||||
|
||||
Returns <= 0 on error or a positive value on success.
|
||||
|
||||
=item I<asn1_ex_i2d>
|
||||
|
||||
An "i2d" function responsible for converting an B<ASN1_VALUE> into DER encoding.
|
||||
On entry I<*pval> will contain the B<ASN1_VALUE> to be encoded. If default
|
||||
tagging is to be used then I<tag> will be -1 on entry. Otherwise if implicit
|
||||
tagging should be used then I<tag> and I<aclass> will be the tag and associated
|
||||
class.
|
||||
|
||||
If I<out> is not NULL then this function should write the DER encoded data to
|
||||
the buffer in I<*out>, and then increment I<*out> to point to immediately after
|
||||
the data just written.
|
||||
|
||||
If I<out> is NULL then no data should be written but the length calculated and
|
||||
returned as if it were.
|
||||
|
||||
The I<asn1_ex_i2d> entry may be NULL if I<asn1_ex_i2d_ex> has been specified
|
||||
instead.
|
||||
|
||||
The return value should be negative if a fatal error occurred, or 0 if a
|
||||
non-fatal error occurred. Otherwise it should return the length of the encoded
|
||||
data.
|
||||
|
||||
=item I<asn1_ex_print>
|
||||
|
||||
A "print" function. I<out> is the BIO to print the output to. I<*pval> is the
|
||||
B<ASN1_VALUE> to be printed. I<indent> is the number of spaces of indenting to
|
||||
be printed before any data is printed. I<fname> is currently unused and is
|
||||
always "". I<pctx> is a pointer to the B<ASN1_PCTX> for the print operation.
|
||||
|
||||
Returns 0 on error or a positive value on success. If the return value is 2 then
|
||||
an additional newline will be printed after the data printed by this function.
|
||||
|
||||
=item I<asn1_ex_new_ex>
|
||||
|
||||
This is the same as I<asn1_ex_new> except that it is additionally passed the
|
||||
OSSL_LIB_CTX to be used in I<libctx> and any property query string to be used
|
||||
for algorithm fetching in the I<propq> parameter. See
|
||||
L<crypto(7)/ALGORITHM FETCHING> for further details. If I<asn1_ex_new_ex> is
|
||||
non NULL, then it will always be called in preference to I<asn1_ex_new>.
|
||||
|
||||
=item I<asn1_ex_d2i_ex>
|
||||
|
||||
This is the same as I<asn1_ex_d2i> except that it is additionally passed the
|
||||
OSSL_LIB_CTX to be used in I<libctx> and any property query string to be used
|
||||
for algorithm fetching in the I<propq> parameter. See
|
||||
L<crypto(7)/ALGORITHM FETCHING> for further details. If I<asn1_ex_d2i_ex> is
|
||||
non NULL, then it will always be called in preference to I<asn1_ex_d2i>.
|
||||
|
||||
=back
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
Return values for the various callbacks are as described above.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<ASN1_item_new_ex(3)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The I<asn1_ex_new_ex> and I<asn1_ex_d2i_ex> callbacks were added in OpenSSL 3.0.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2021 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
|
||||
|
|
@ -0,0 +1,284 @@
|
|||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
ASN1_AUX, ASN1_PRINT_ARG, ASN1_STREAM_ARG, ASN1_aux_cb, ASN1_aux_const_cb
|
||||
- ASN.1 auxilliary data
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/asn1t.h>
|
||||
|
||||
struct ASN1_AUX_st {
|
||||
void *app_data;
|
||||
int flags;
|
||||
int ref_offset; /* Offset of reference value */
|
||||
int ref_lock; /* Offset to an CRYPTO_RWLOCK */
|
||||
ASN1_aux_cb *asn1_cb;
|
||||
int enc_offset; /* Offset of ASN1_ENCODING structure */
|
||||
ASN1_aux_const_cb *asn1_const_cb; /* for ASN1_OP_I2D_ and ASN1_OP_PRINT_ */
|
||||
};
|
||||
typedef struct ASN1_AUX_st ASN1_AUX;
|
||||
|
||||
struct ASN1_PRINT_ARG_st {
|
||||
BIO *out;
|
||||
int indent;
|
||||
const ASN1_PCTX *pctx;
|
||||
};
|
||||
typedef struct ASN1_PRINT_ARG_st ASN1_PRINT_ARG;
|
||||
|
||||
struct ASN1_STREAM_ARG_st {
|
||||
BIO *out;
|
||||
BIO *ndef_bio;
|
||||
unsigned char **boundary;
|
||||
};
|
||||
typedef struct ASN1_STREAM_ARG_st ASN1_STREAM_ARG;
|
||||
|
||||
typedef int ASN1_aux_cb(int operation, ASN1_VALUE **in, const ASN1_ITEM *it,
|
||||
void *exarg);
|
||||
typedef int ASN1_aux_const_cb(int operation, const ASN1_VALUE **in,
|
||||
const ASN1_ITEM *it, void *exarg);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
ASN.1 data structures can be associated with an B<ASN1_AUX> object to supply
|
||||
additional information about the ASN.1 structure. An B<ASN1_AUX> structure is
|
||||
associated with the structure during the definition of the ASN.1 template. For
|
||||
example an B<ASN1_AUX> structure will be associated by using one of the various
|
||||
ASN.1 template definition macros that supply auxilliary information such as
|
||||
ASN1_SEQUENCE_enc(), ASN1_SEQUENCE_ref(), ASN1_SEQUENCE_cb_const_cb(),
|
||||
ASN1_SEQUENCE_const_cb(), ASN1_SEQUENCE_cb() or ASN1_NDEF_SEQUENCE_cb().
|
||||
|
||||
An B<ASN1_AUX> structure contains the following information.
|
||||
|
||||
=over 4
|
||||
|
||||
=item I<app_data>
|
||||
|
||||
Arbitrary application data
|
||||
|
||||
=item I<flags>
|
||||
|
||||
Flags which indicate the auxiliarly functionality supported.
|
||||
|
||||
The B<ASN1_AFLG_REFCOUNT> flag indicates that objects support reference counting.
|
||||
|
||||
The B<ASN1_AFLG_ENCODING> flag indicates that the original encoding of the
|
||||
object will be saved.
|
||||
|
||||
The B<ASN1_AFLG_BROKEN> flag is a work around for broken encoders where the
|
||||
sequence length value may not be correct. This should generally not be used.
|
||||
|
||||
The B<ASN1_AFLG_CONST_CB> flag indicates that the "const" form of the
|
||||
B<ASN1_AUX> callback should be used in preference to the non-const form.
|
||||
|
||||
=item I<ref_offset>
|
||||
|
||||
If the B<ASN1_AFLG_REFCOUNT> flag is set then this value is assumed to be an
|
||||
offset into the B<ASN1_VALUE> structure where a B<CRYPTO_REF_COUNT> may be
|
||||
found for the purposes of reference counting.
|
||||
|
||||
=item I<ref_lock>
|
||||
|
||||
If the B<ASN1_AFLG_REFCOUNT> flag is set then this value is assumed to be an
|
||||
offset into the B<ASN1_VALUE> structure where a B<CRYPTO_RWLOCK> may be
|
||||
found for the purposes of reference counting.
|
||||
|
||||
=item I<asn1_cb>
|
||||
|
||||
A callback that will be invoked at various points during the processing of
|
||||
the the B<ASN1_VALLUE>. See below for further details.
|
||||
|
||||
=item I<enc_offset>
|
||||
|
||||
Offset into the B<ASN1_VALUE> object where the original encoding of the object
|
||||
will be saved if the B<ASN1_AFLG_ENCODING> flag has been set.
|
||||
|
||||
=item I<asn1_const_cb>
|
||||
|
||||
A callback that will be invoked at various points during the processing of
|
||||
the the B<ASN1_VALLUE>. This is used in preference to the I<asn1_cb> callback if
|
||||
the B<ASN1_AFLG_CONST_CB> flag is set. See below for further details.
|
||||
|
||||
=back
|
||||
|
||||
During the processing of an B<ASN1_VALUE> object the callbacks set via
|
||||
I<asn1_cb> or I<asn1_const_cb> will be invoked as a result of various events
|
||||
indicated via the I<operation> parameter. The value of I<*in> will be the
|
||||
B<ASN1_VALUE> object being processed based on the template in I<it>. An
|
||||
additional operation specific parameter may be passed in I<exarg>. The currently
|
||||
supported operations are as follows. The callbacks should return a positive
|
||||
value on success or zero on error, unless otherwise noted below.
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<ASN1_OP_NEW_PRE>
|
||||
|
||||
Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
|
||||
prior to an B<ASN1_VALUE> object being allocated. The callback may allocate the
|
||||
B<ASN1_VALUE> itself and store it in I<*pval>. If it does so it should return 2
|
||||
from the callback. On error it should return 0.
|
||||
|
||||
=item B<ASN1_OP_NEW_POST>
|
||||
|
||||
Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
|
||||
after an B<ASN1_VALUE> object has been allocated. The allocated object is in
|
||||
I<*pval>.
|
||||
|
||||
=item B<ASN1_OP_FREE_PRE>
|
||||
|
||||
Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
|
||||
immediately before an B<ASN1_VALUE> is freed. If the callback originally
|
||||
constructed the B<ASN1_VALUE> via B<ASN1_OP_NEW_PRE> then it should free it at
|
||||
this point and return 2 from the callback. Otherwise it should return 1 for
|
||||
success or 0 on error.
|
||||
|
||||
=item B<ASN1_OP_FREE_POST>
|
||||
|
||||
Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
|
||||
immediately after B<ASN1_VALUE> sub-structures are freed.
|
||||
|
||||
=item B<ASN1_OP_D2I_PRE>
|
||||
|
||||
Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
|
||||
immediately before a "d2i" operation for the B<ASN1_VALUE>.
|
||||
|
||||
=item B<ASN1_OP_D2I_POST>
|
||||
|
||||
Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
|
||||
immediately after a "d2i" operation for the B<ASN1_VALUE>.
|
||||
|
||||
=item B<ASN1_OP_I2D_PRE>
|
||||
|
||||
Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
|
||||
immediately before a "i2d" operation for the B<ASN1_VALUE>.
|
||||
|
||||
=item B<ASN1_OP_I2D_POST>
|
||||
|
||||
Invoked when processing a B<CHOICE>, B<SEQUENCE> or B<NDEF_SEQUENCE> structure
|
||||
immediately after a "i2d" operation for the B<ASN1_VALUE>.
|
||||
|
||||
=item B<ASN1_OP_PRINT_PRE>
|
||||
|
||||
Invoked when processing a B<SEQUENCE> or B<NDEF_SEQUENCE> structure immediately
|
||||
before printing the B<ASN1_VALUE>. The I<exarg> argument will be a pointer to an
|
||||
B<ASN1_PRINT_ARG> structure (see below).
|
||||
|
||||
=item B<ASN1_OP_PRINT_POST>
|
||||
|
||||
Invoked when processing a B<SEQUENCE> or B<NDEF_SEQUENCE> structure immediately
|
||||
after printing the B<ASN1_VALUE>. The I<exarg> argument will be a pointer to an
|
||||
B<ASN1_PRINT_ARG> structure (see below).
|
||||
|
||||
=item B<ASN1_OP_STREAM_PRE>
|
||||
|
||||
Invoked immediately prior to streaming the B<ASN1_VALUE> data using indefinite
|
||||
length encoding. The I<exarg> argument will be a pointer to a B<ASN1_STREAM_ARG>
|
||||
structure (see below).
|
||||
|
||||
=item B<ASN1_OP_STREAM_POST>
|
||||
|
||||
Invoked immediately after streaming the B<ASN1_VALUE> data using indefinite
|
||||
length encoding. The I<exarg> argument will be a pointer to a B<ASN1_STREAM_ARG>
|
||||
structure (see below).
|
||||
|
||||
=item B<ASN1_OP_DETACHED_PRE>
|
||||
|
||||
Invoked immediately prior to processing the B<ASN1_VALUE> data as a "detached"
|
||||
value (as used in CMS and PKCS7). The I<exarg> argument will be a pointer to a
|
||||
B<ASN1_STREAM_ARG> structure (see below).
|
||||
|
||||
=item B<ASN1_OP_DETACHED_POST>
|
||||
|
||||
Invoked immediately after processing the B<ASN1_VALUE> data as a "detached"
|
||||
value (as used in CMS and PKCS7). The I<exarg> argument will be a pointer to a
|
||||
B<ASN1_STREAM_ARG> structure (see below).
|
||||
|
||||
=item B<ASN1_OP_DUP_PRE>
|
||||
|
||||
Invoked immediate prior to an ASN1_VALUE being duplicated via a call to
|
||||
ASN1_item_dup().
|
||||
|
||||
=item B<ASN1_OP_DUP_POST>
|
||||
|
||||
Invoked immediate after to an ASN1_VALUE has been duplicated via a call to
|
||||
ASN1_item_dup().
|
||||
|
||||
=item B<ASN1_OP_GET0_LIBCTX>
|
||||
|
||||
Invoked in order to obtain the B<OSSL_LIB_CTX> associated with an B<ASN1_VALUE>
|
||||
if any. A pointer to an B<OSSL_LIB_CTX> should be stored in I<*exarg> if such
|
||||
a value exists.
|
||||
|
||||
=item B<ASN1_OP_GET0_PROPQ>
|
||||
|
||||
Invoked in order to obtain the property query string associated with an
|
||||
B<ASN1_VALUE> if any. A pointer to the property query string should be stored in
|
||||
I<*exarg> if such a value exists.
|
||||
|
||||
=back
|
||||
|
||||
An B<ASN1_PRINT_ARG> object is used during processing of B<ASN1_OP_PRINT_PRE>
|
||||
and B<ASN1_OP_PRINT_POST> callback operations. It contains the following
|
||||
information.
|
||||
|
||||
=over 4
|
||||
|
||||
=item I<out>
|
||||
|
||||
The B<BIO> being used to print the data out.
|
||||
|
||||
=item I<ndef_bio>
|
||||
|
||||
The current number of indent spaces that should be used for printing this data.
|
||||
|
||||
=item I<pctx>
|
||||
|
||||
The context for the B<ASN1_PCTX> operation.
|
||||
|
||||
=back
|
||||
|
||||
An B<ASN1_STREAM_ARG> object is used during processing of B<ASN1_OP_STREAM_PRE>,
|
||||
B<ASN1_OP_STREAM_POST>, B<ASN1_OP_DETACHED_PRE> and B<ASN1_OP_DETACHED_POST>
|
||||
callback operations. It contains the following information.
|
||||
|
||||
=over 4
|
||||
|
||||
=item I<out>
|
||||
|
||||
The B<BIO> to stream through
|
||||
|
||||
=item I<ndef_bio>
|
||||
|
||||
The B<BIO> with filters appended
|
||||
|
||||
=item I<boundary>
|
||||
|
||||
The streaming I/O boundary.
|
||||
|
||||
=back
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
The callbacks return 0 on error and a positive value on success. Some operations
|
||||
require specific positive success values as noted above.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<ASN1_item_new_ex(3)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The ASN1_aux_const_cb() callback and the B<ASN1_OP_GET0_LIBCTX> and
|
||||
B<ASN1_OP_GET0_PROPQ> operation types were added in OpenSSL 3.0.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2021 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
|
||||
|
|
@ -2,23 +2,65 @@
|
|||
|
||||
=head1 NAME
|
||||
|
||||
ASN1_item_d2i_bio,
|
||||
ASN1_item_i2d_mem_bio
|
||||
ASN1_item_d2i_ex, ASN1_item_d2i, ASN1_item_d2i_bio_ex, ASN1_item_d2i_bio,
|
||||
ASN1_item_d2i_fp_ex, ASN1_item_d2i_fp, ASN1_item_i2d_mem_bio
|
||||
- decode and encode DER-encoded ASN.1 structures
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/asn1.h>
|
||||
|
||||
ASN1_VALUE *ASN1_item_d2i_ex(ASN1_VALUE **val, const unsigned char **in,
|
||||
long len, const ASN1_ITEM *it,
|
||||
OSSL_LIB_CTX *libctx, const char *propq);
|
||||
ASN1_VALUE *ASN1_item_d2i(ASN1_VALUE **val, const unsigned char **in,
|
||||
long len, const ASN1_ITEM *it);
|
||||
|
||||
void *ASN1_item_d2i_bio_ex(const ASN1_ITEM *it, BIO *in, void *pval,
|
||||
OSSL_LIB_CTX *libctx, const char *propq);
|
||||
void *ASN1_item_d2i_bio(const ASN1_ITEM *it, BIO *in, void *pval);
|
||||
|
||||
void *ASN1_item_d2i_fp_ex(const ASN1_ITEM *it, FILE *in, void *x,
|
||||
OSSL_LIB_CTX *libctx, const char *propq);
|
||||
void *ASN1_item_d2i_fp(const ASN1_ITEM *it, FILE *in, void *x);
|
||||
|
||||
BIO *ASN1_item_i2d_mem_bio(const ASN1_ITEM *it, const ASN1_VALUE *val);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
ASN1_item_d2i_bio() decodes the contents of its input BIO I<in>,
|
||||
ASN1_item_d2i_ex() decodes the contents of the data stored in I<*in> of length
|
||||
I<len> which must be a DER-encoded ASN.1 structure, using the ASN.1 template
|
||||
I<it>. It places the result in I<*pval> unless I<pval> is NULL. If I<*pval> is
|
||||
non-NULL on entry then the B<ASN1_VALUE> present there will be reused. Otherwise
|
||||
a new B<ASN1_VALUE> will be allocated. If any algorithm fetches are required
|
||||
during the process then they will use the B<OSSL_LIB_CTX>provided in the
|
||||
I<libctx> parameter and the property query string in I<propq>. See
|
||||
L<crypto(7)/ALGORITHM FETCHING> for more information about algorithm fetching.
|
||||
On exit I<*in> will be updated to point to the next byte in the buffer after the
|
||||
decoded structure.
|
||||
|
||||
ASN1_item_d2i() is the same as ASN1_item_d2i_ex() except that the default
|
||||
OSSL_LIB_CTX is used (i.e. NULL) and with a NULL property query string.
|
||||
|
||||
ASN1_item_d2i_bio_ex() decodes the contents of its input BIO I<in>,
|
||||
which must be a DER-encoded ASN.1 structure, using the ASN.1 template I<it>
|
||||
and places the result in I<*pval> unless I<pval> is NULL.
|
||||
If I<in> is NULL it returns NULL, else a pointer to the parsed structure.
|
||||
If I<in> is NULL it returns NULL, else a pointer to the parsed structure. If any
|
||||
algorithm fetches are required during the process then they will use the
|
||||
B<OSSL_LIB_CTX> provided in the I<libctx> parameter and the property query
|
||||
string in I<propq>. See L<crypto(7)/ALGORITHM FETCHING> for more information
|
||||
about algorithm fetching.
|
||||
|
||||
ASN1_item_d2i_bio() is the same as ASN1_item_d2i_bio_ex() except that the
|
||||
default B<OSSL_LIB_CTX> is used (i.e. NULL) and with a NULL property query
|
||||
string.
|
||||
|
||||
ASN1_item_d2i_fp_ex() is the same as ASN1_item_d2i_bio_ex() except that a FILE
|
||||
pointer is provided instead of a BIO.
|
||||
|
||||
ASN1_item_d2i_fp() is the same as ASN1_item_d2i_fp_ex() except that the
|
||||
default B<OSSL_LIB_CTX> is used (i.e. NULL) and with a NULL property query
|
||||
string.
|
||||
|
||||
ASN1_item_i2d_mem_bio() encodes the given ASN.1 value I<val>
|
||||
using the ASN.1 template I<it> and returns the result in a memory BIO.
|
||||
|
|
@ -31,7 +73,8 @@ ASN1_item_i2d_mem_bio() returns a pointer to a memory BIO or NULL on error.
|
|||
|
||||
=head1 HISTORY
|
||||
|
||||
ASN1_item_i2d_mem_bio() was added in OpenSSL 3.0.
|
||||
The functions ASN1_item_d2i_ex(), ASN1_item_d2i_bio_ex(), ASN1_item_d2i_fp_ex()
|
||||
and ASN1_item_i2d_mem_bio() were added in OpenSSL 3.0.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,45 @@
|
|||
=pod
|
||||
|
||||
=head1 NAME
|
||||
|
||||
ASN1_item_new_ex, ASN1_item_new
|
||||
- create new ASN.1 values
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
#include <openssl/asn1.h>
|
||||
|
||||
ASN1_VALUE *ASN1_item_new_ex(const ASN1_ITEM *it, OSSL_LIB_CTX *libctx,
|
||||
const char *propq);
|
||||
ASN1_VALUE *ASN1_item_new(const ASN1_ITEM *it);
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
ASN1_item_new_ex() creates a new B<ASN1_VALUE> structure based on the
|
||||
B<ASN1_ITEM> template given in the I<it> parameter. If any algorithm fetches are
|
||||
required during the process then they will use the B<OSSL_LIB_CTX> provided in
|
||||
the I<libctx> parameter and the property query string in I<propq>. See
|
||||
L<crypto(7)/ALGORITHM FETCHING> for more information about algorithm fetching.
|
||||
|
||||
ASN1_item_new() is the same as ASN1_item_new_ex() except that the default
|
||||
B<OSSL_LIB_CTX> is used (i.e. NULL) and with a NULL property query string.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
ASN1_item_new_ex() and ASN1_item_new() return a pointer to the newly created
|
||||
B<ASN1_VALUE> or NULL on error.
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The function ASN1_item_new_ex() was added in OpenSSL 3.0.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2021 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
|
||||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
=head1 NAME
|
||||
|
||||
X509_PUBKEY_new, X509_PUBKEY_free, X509_PUBKEY_dup,
|
||||
X509_PUBKEY_new_ex, X509_PUBKEY_new, X509_PUBKEY_free, X509_PUBKEY_dup,
|
||||
X509_PUBKEY_set, X509_PUBKEY_get0, X509_PUBKEY_get,
|
||||
d2i_PUBKEY_ex, d2i_PUBKEY, i2d_PUBKEY, d2i_PUBKEY_bio, d2i_PUBKEY_fp,
|
||||
i2d_PUBKEY_fp, i2d_PUBKEY_bio, X509_PUBKEY_set0_param, X509_PUBKEY_get0_param,
|
||||
|
|
@ -12,6 +12,7 @@ X509_PUBKEY_eq - SubjectPublicKeyInfo public key functions
|
|||
|
||||
#include <openssl/x509.h>
|
||||
|
||||
X509_PUBKEY *X509_PUBKEY_new_ex(OSSL_LIB_CTX *libctx, const char *propq);
|
||||
X509_PUBKEY *X509_PUBKEY_new(void);
|
||||
void X509_PUBKEY_free(X509_PUBKEY *a);
|
||||
X509_PUBKEY *X509_PUBKEY_dup(const X509_PUBKEY *a);
|
||||
|
|
@ -44,7 +45,14 @@ X509_PUBKEY_eq - SubjectPublicKeyInfo public key functions
|
|||
The B<X509_PUBKEY> structure represents the ASN.1 B<SubjectPublicKeyInfo>
|
||||
structure defined in RFC5280 and used in certificates and certificate requests.
|
||||
|
||||
X509_PUBKEY_new() allocates and initializes an B<X509_PUBKEY> structure.
|
||||
X509_PUBKEY_new_ex() allocates and initializes an B<X509_PUBKEY> structure
|
||||
associated with the given B<OSSL_LIB_CTX> in the I<libctx> parameter. Any
|
||||
algorithm fetches associated with using the B<X509_PUBKEY> object will use
|
||||
the property query string I<propq>. See L<crypto(7)/ALGORITHM FETCHING> for
|
||||
further information about algorithm fetching.
|
||||
|
||||
X509_PUBKEY_new() is the same as X509_PUBKEY_new_ex() except that the default
|
||||
(NULL) B<OSSL_LIB_CTX> and a NULL property query string are used.
|
||||
|
||||
X509_PUBKEY_dup() creates a duplicate copy of the B<X509_PUBKEY> object
|
||||
specified by I<a>.
|
||||
|
|
@ -127,7 +135,8 @@ L<X509_get_pubkey(3)>,
|
|||
|
||||
=head1 HISTORY
|
||||
|
||||
The X509_PUBKEY_eq() function was added in OpenSSL 3.0.
|
||||
The X509_PUBKEY_new_ex() and X509_PUBKEY_eq() functions were added in OpenSSL
|
||||
3.0.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
|
|
|
|||
|
|
@ -562,10 +562,11 @@ B<const EVP_CIPHER *> such as EVP_aes_128_cbc() should be replaced vith a call t
|
|||
L<EVP_CIPHER_fetch(3)>. See L<crypto(7)/ALGORITHM FETCHING>.
|
||||
|
||||
Some functions can be passed an object that has already been set up with a library
|
||||
context such as L<d2i_X509(3)>, L<d2i_X509_CRL(3)> and L<d2i_X509_REQ(3)>.
|
||||
If NULL is passed instead then the created object will be set up with the
|
||||
default library context. Use L<X509_new_ex(3)>, L<X509_CRL_new_ex(3)> and
|
||||
L<X509_REQ_new_ex(3)> if a library context is required.
|
||||
context such as L<d2i_X509(3)>, L<d2i_X509_CRL(3)>, L<d2i_X509_REQ(3)> and
|
||||
L<d2i_X509_PUBKEY(3)>. If NULL is passed instead then the created object will be
|
||||
set up with the default library context. Use L<X509_new_ex(3)>,
|
||||
L<X509_CRL_new_ex(3)>, L<X509_REQ_new_ex(3)> and L<X509_PUBKEY_new_ex(3)> if a
|
||||
library context is required.
|
||||
|
||||
All functions listed below with a I<NAME> have a replacment function I<NAME_ex>
|
||||
that takes B<OSSL_LIB_CTX> as an additional argument. Functions that have other
|
||||
|
|
@ -575,7 +576,8 @@ mappings are listed along with the respective name.
|
|||
|
||||
=item -
|
||||
|
||||
L<ASN1_item_sign(3)> and L<ASN1_item_verify(3)>
|
||||
L<ASN1_item_new(3)>, L<ASN1_item_d2i(3)>, L<ASN1_item_d2i_fp(3)>,
|
||||
L<ASN1_item_d2i_bio(3)>, L<ASN1_item_sign(3)> and L<ASN1_item_verify(3)>
|
||||
|
||||
=item -
|
||||
|
||||
|
|
|
|||
|
|
@ -704,7 +704,7 @@ typedef struct ASN1_AUX_st {
|
|||
void *app_data;
|
||||
int flags;
|
||||
int ref_offset; /* Offset of reference value */
|
||||
int ref_lock; /* Lock type to use */
|
||||
int ref_lock; /* Offset of lock value */
|
||||
ASN1_aux_cb *asn1_cb;
|
||||
int enc_offset; /* Offset of ASN1_ENCODING structure */
|
||||
ASN1_aux_const_cb *asn1_const_cb; /* for ASN1_OP_I2D_ and ASN1_OP_PRINT_ */
|
||||
|
|
|
|||
|
|
@ -137,9 +137,6 @@ ASN1_dup(3)
|
|||
ASN1_get_object(3)
|
||||
ASN1_i2d_bio(3)
|
||||
ASN1_i2d_fp(3)
|
||||
ASN1_item_d2i(3)
|
||||
ASN1_item_d2i_bio(3)
|
||||
ASN1_item_d2i_fp(3)
|
||||
ASN1_item_digest(3)
|
||||
ASN1_item_dup(3)
|
||||
ASN1_item_ex_d2i(3)
|
||||
|
|
@ -151,7 +148,6 @@ ASN1_item_i2d(3)
|
|||
ASN1_item_i2d_bio(3)
|
||||
ASN1_item_i2d_fp(3)
|
||||
ASN1_item_ndef_i2d(3)
|
||||
ASN1_item_new(3)
|
||||
ASN1_item_pack(3)
|
||||
ASN1_item_print(3)
|
||||
ASN1_item_unpack(3)
|
||||
|
|
|
|||
|
|
@ -11,7 +11,20 @@ OPENSSL_instrument_bus2 assembler
|
|||
#
|
||||
ADMISSION_SYNTAX datatype
|
||||
ADMISSIONS datatype
|
||||
ASN1_AUX datatype
|
||||
ASN1_aux_cb datatype
|
||||
ASN1_aux_const_cb datatype
|
||||
ASN1_ex_d2i datatype
|
||||
ASN1_ex_d2i_ex datatype
|
||||
ASN1_ex_free_func datatype
|
||||
ASN1_ex_i2d datatype
|
||||
ASN1_ex_new_func datatype
|
||||
ASN1_ex_new_ex_func datatype
|
||||
ASN1_ex_print_func datatype
|
||||
ASN1_EXTERN_FUNCS datatype
|
||||
ASN1_ITEM datatype
|
||||
ASN1_PRINT_ARG datatype
|
||||
ASN1_STREAM_ARG datatype
|
||||
ASN1_STRING_TABLE datatype
|
||||
ASYNC_callback_fn datatype
|
||||
BIO_ADDR datatype
|
||||
|
|
|
|||
Loading…
Reference in New Issue