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

Latest update.

Browse Source
This commit is contained in:
Hakase
2020-04-15 18:45:34 +09:00
parent be29e7bcc6
commit 2015c00c43
573 changed files with 22943 additions and 6714 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/internal/man3/DER_w_begin_sequence.pod
+48
View File
@@ -0,0 +1,48 @@
=pod
=head1 NAME
DER_w_begin_sequence, DER_w_end_sequence
- internal DER writers for DER constructed elements
=head1 SYNOPSIS
#include "internal/der.h"
int DER_w_begin_sequence(WPACKET *pkt, int tag);
int DER_w_end_sequence(WPACKET *pkt, int tag);
=head1 DESCRIPTION
All functions described here are wrappers for constructed structures,
i.e. the ASN.1 SEQUENCE, SET and CHOICE specifications. They all come
in pairs, as noted by the function names containing the words C<begin>
and B<end>.
When using these, special care must be taken to ensure that the ASN.1 tag
value I<tag> is the same in the matching C<begin> and C<end> function calls.
DER_w_begin_sequence() and DER_w_end_sequence() begins and ends a
SEQUENCE.
=head1 RETURN VALUES
All the functions return 1 on success and 0 on failure. Failure may
mean that the buffer held by the I<pkt> is too small, but may also
mean that the values given to the functions are invalid, such as the provided
I<tag> value being too large for the implementation.
=head1 SEE ALSO
L<DERlib(7)>
=head1 COPYRIGHT
Copyright 2020 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/DER_w_bn.pod
+56
View File
@@ -0,0 +1,56 @@
=pod
=head1 NAME
DER_w_boolean, DER_w_ulong, DER_w_bn, DER_w_null
- internal DER writers for DER primitives
=head1 SYNOPSIS
#include "internal/der.h"
int DER_w_boolean(WPACKET *pkt, int tag, int b);
int DER_w_ulong(WPACKET *pkt, int tag, unsigned long v);
int DER_w_bn(WPACKET *pkt, int tag, const BIGNUM *v);
int DER_w_null(WPACKET *pkt, int tag);
=head1 DESCRIPTION
All functions described here behave the same way, they prepend
(remember that DER writers are used backwards) the DER encoding of
their respective value to the already written output buffer held by
I<pkt>.
DER_w_boolean() writes the primitive BOOLEAN using the value I<b>.
Any value that evaluates as true will render a B<true> BOOLEAN,
otherwise a B<false> BOOLEAN.
DER_w_ulong() and DER_w_bn() both write the primitive INTEGER using
the value I<v>.
=for comment Other similar functions for diverse C integers should be
added.
DER_w_null() writes the primitive NULL.
=head1 RETURN VALUES
All the functions return 1 on success and 0 on failure. Failure may
mean that the buffer held by the I<pkt> is too small, but may also
mean that the values given to the functions are invalid, such as the provided
I<tag> value being too large for the implementation.
=head1 SEE ALSO
L<DERlib(7)>
=head1 COPYRIGHT
Copyright 2020 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/DER_w_precompiled.pod
+48
View File
@@ -0,0 +1,48 @@
=pod
=head1 NAME
DER_w_precompiled
- internal DER writers for precompiled DER blobs
=head1 SYNOPSIS
#include "internal/der.h"
int DER_w_precompiled(WPACKET *pkt, int tag,
const unsigned char *precompiled,
size_t precompiled_n);
=head1 DESCRIPTION
There may be already existing DER blobs that can simply be copied to
the buffer held by I<pkt>. For example, precompiled values, such as
OIDs (for example, C<id-sha256>) or complete AlgorithmIdentifiers
(for example, C<sha256Identifier>). To add those as an element in a
structure being DER encoded, use DER_w_precompiled().
DER_w_precompiled() will simply take the DER encoded blob given as
I<precompiled> with length I<precompiled_n> and add it to the buffer
held by I<pkt>.
=head1 RETURN VALUES
DER_w_precompiled() returns 1 on success and 0 on failure. Failure
may mean that the buffer held by the I<pkt> is too small, but may also
mean that the values given to the functions are invalid, such as the provided
I<tag> value being too large for the implementation.
=head1 SEE ALSO
L<DERlib(7)>
=head1 COPYRIGHT
Copyright 2020 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/DEFINE_SPARSE_ARRAY_OF.pod → doc/internal/man3/OPENSSL_SA.pod
+1 -3
View File
@@ -2,15 +2,13 @@
=head1 NAME
DEFINE_SPARSE_ARRAY_OF, ossl_sa_TYPE_new, ossl_sa_TYPE_free,
OPENSSL_SA, ossl_sa_TYPE_new, ossl_sa_TYPE_free,
ossl_sa_TYPE_free_leaves, ossl_sa_TYPE_num, ossl_sa_TYPE_doall,
ossl_sa_TYPE_doall_arg, ossl_sa_TYPE_get, ossl_sa_TYPE_set
- sparse array container
=head1 SYNOPSIS
=for openssl generic
#include "crypto/sparse_array.h"
typedef struct sparse_array_st OPENSSL_SA;
doc/internal/man3/ossl_cmp_hdr_init.pod
+10 -3
View File
@@ -5,6 +5,7 @@
ossl_cmp_hdr_set_pvno,
ossl_cmp_hdr_get_pvno,
ossl_cmp_hdr_get0_sendernonce,
ossl_cmp_general_name_is_NULL_DN,
ossl_cmp_hdr_set1_sender,
ossl_cmp_hdr_set1_recipient,
ossl_cmp_hdr_update_messagetime,
@@ -14,7 +15,7 @@ ossl_cmp_hdr_push1_freeText,
ossl_cmp_hdr_generalinfo_item_push0,
ossl_cmp_hdr_generalinfo_items_push1,
ossl_cmp_hdr_set_implicitConfirm,
ossl_cmp_hdr_check_implicitConfirm,
ossl_cmp_hdr_has_implicitConfirm,
ossl_cmp_hdr_init
- functions manipulating CMP message headers
@@ -26,6 +27,7 @@ ossl_cmp_hdr_init
int ossl_cmp_hdr_get_pvno(const OSSL_CMP_PKIHEADER *hdr);
ASN1_OCTET_STRING
*ossl_cmp_hdr_get0_sendernonce(const OSSL_CMP_PKIHEADER *hdr);
int ossl_cmp_general_name_is_NULL_DN(GENERAL_NAME *name);
int ossl_cmp_hdr_set1_sender(OSSL_CMP_PKIHEADER *hdr, const X509_NAME *nm);
int ossl_cmp_hdr_set1_recipient(OSSL_CMP_PKIHEADER *hdr, const X509_NAME *nm);
@@ -41,7 +43,7 @@ ossl_cmp_hdr_init
int ossl_cmp_hdr_push1_freeText(OSSL_CMP_PKIHEADER *hdr,
ASN1_UTF8STRING *text);
int ossl_cmp_hdr_set_implicitConfirm(OSSL_CMP_PKIHEADER *hdr);
int ossl_cmp_hdr_check_implicitConfirm(OSSL_CMP_PKIHEADER *hdr);
int ossl_cmp_hdr_has_implicitConfirm(OSSL_CMP_PKIHEADER *hdr);
int ossl_cmp_hdr_init(OSSL_CMP_CTX *ctx, OSSL_CMP_PKIHEADER *hdr);
=head1 DESCRIPTION
@@ -52,6 +54,9 @@ ossl_cmp_hdr_get_pvno() returns the pvno of the given B<hdr> or -1 on error.
ossl_cmp_hdr_get0_sendernonce() returns the sender nonce of the given PKIHeader.
ossl_cmp_general_name_is_NULL_DN() determines if the given GENERAL_NAME
is the NULL-DN.
ossl_cmp_hdr_set1_sender() sets the sender field in the given PKIHeader
to the given X509 Name value, without consuming the pointer.
@@ -85,7 +90,7 @@ pointer.
ossl_cmp_hdr_set_implicitConfirm() sets implicitConfirm in the generalInfo field
of the PKIMessage header.
ossl_cmp_hdr_check_implicitConfirm() returns 1 if implicitConfirm is
ossl_cmp_hdr_has_implicitConfirm() returns 1 if implicitConfirm is
set int generalInfo field of the given PKIMessage header, 0 if not.
ossl_cmp_hdr_init() initializes a PKIHeader structure based on the
@@ -107,6 +112,8 @@ ossl_cmp_hdr_get_pvno() returns the pvno of the given B<hdr> or -1 on error.
ossl_cmp_hdr_get0_sendernonce() returns the respective nonce.
ossl_cmp_general_name_is_NULL_DN() returns 1 given a NULL-DN, else 0.
All other functions return 1 on success, 0 on error.
See the individual functions above.
doc/internal/man3/ossl_cmp_mock_srv_new.pod
+85
View File
@@ -0,0 +1,85 @@
=pod
=head1 NAME
ossl_cmp_mock_srv_new,
ossl_cmp_mock_srv_free,
ossl_cmp_mock_srv_set1_certOut,
ossl_cmp_mock_srv_set1_chainOut,
ossl_cmp_mock_srv_set1_caPubsOut,
ossl_cmp_mock_srv_set_statusInfo,
ossl_cmp_mock_srv_set_send_error,
ossl_cmp_mock_srv_set_pollCount,
ossl_cmp_mock_srv_set_checkAfterTime
- functions used for testing with CMP mock server
=head1 SYNOPSIS
#include <openssl/cmp.h>
OSSL_CMP_SRV_CTX *ossl_cmp_mock_srv_new(void);
void ossl_cmp_mock_srv_free(OSSL_CMP_SRV_CTX *srv_ctx);
int ossl_cmp_mock_srv_set1_certOut(OSSL_CMP_SRV_CTX *srv_ctx, X509 *cert);
int ossl_cmp_mock_srv_set1_chainOut(OSSL_CMP_SRV_CTX *srv_ctx,
STACK_OF(X509) *chain);
int ossl_cmp_mock_srv_set1_caPubsOut(OSSL_CMP_SRV_CTX *srv_ctx,
STACK_OF(X509) *caPubs);
int ossl_cmp_mock_srv_set_statusInfo(OSSL_CMP_SRV_CTX *srv_ctx, int status,
int fail_info, const char *text);
int ossl_cmp_mock_srv_set_send_error(OSSL_CMP_SRV_CTX *srv_ctx, int val);
int ossl_cmp_mock_srv_set_pollCount(OSSL_CMP_SRV_CTX *srv_ctx, int count);
int ossl_cmp_mock_srv_set_checkAfterTime(OSSL_CMP_SRV_CTX *srv_ctx, int sec);
=head1 DESCRIPTION
ossl_cmp_mock_srv_new() allocates the contexts for the CMP mock server.
ossl_cmp_mock_srv_free() deallocates the contexts for the CMP mock server.
OSSL_CMP_SRV_CTX_set1_certOut() sets the certificate to be returned in
cp/ip/kup.
OSSL_CMP_SRV_CTX_set1_chainOut() sets the certificate chain to be added to
the extraCerts in a cp/ip/kup.
It should to useful to validate B<certOut>.
OSSL_CMP_SRV_CTX_set1_caPubsOut() sets the caPubs to be returned in an ip.
OSSL_CMP_SRV_CTX_set_statusInfo() sets the status info to be returned.
OSSL_CMP_SRV_CTX_set_send_error() enables enforcement of error responses.
OSSL_CMP_SRV_CTX_set_pollCount() sets the number of polls before cert response.
OSSL_CMP_SRV_CTX_set_checkAfterTime() sets the number of seconds
the client should wait for the next poll.
=head1 NOTES
CMP is defined in RFC 4210 (and CRMF in RFC 4211).
=head1 RETURN VALUES
ossl_cmp_mock_srv() returns a B<OSSL_CMP_SRV_CTX> structure on success,
NULL on error.
ossl_cmp_mock_srv_free() does not return a value.
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-2020 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_msg_check_received.pod
+86
View File
@@ -0,0 +1,86 @@
=pod
=head1 NAME
ossl_cmp_allow_unprotected_cb_t,
ossl_cmp_msg_check_received
- does all checks on a received CMP message that can be done generically
=head1 SYNOPSIS
#include "cmp_local.h"
typedef int (*ossl_cmp_allow_unprotected_cb_t)(const OSSL_CMP_CTX *ctx,
const OSSL_CMP_MSG *msg,
int invalid_protection, int arg);
int ossl_cmp_msg_check_received(OSSL_CMP_CTX *ctx, const OSSL_CMP_MSG *msg,
ossl_cmp_allow_unprotected_cb_t cb, int cb_arg);
=head1 DESCRIPTION
ossl_cmp_msg_check_received() checks the given message B<msg>,
which may be a server response or a request by some client.
It is ensured for the B<msg> that
=over 4
=item it has a valid body type,
=item its protection is present and valid (or a callback function B<cb>
is present and indicates that a missing or invalid protection is acceptable),
=item its recipNonce matches any previous senderNonce stored in B<ctx>, and
=item its transaction ID matches any previous transaction ID stored in B<ctx>.
=back
In case no protection is present and B<cb> is not NULL then this callback
function is called with its B<invalid_protection> parameter being 0, while in
case an invalid protection is present the B<invalid_protection> parameter is 1.
The callback is passed also the arguments B<ctx>, B<msg>, and <cb_arg>
(which typically contains the expected message type).
The callback should return 1 on acceptance, 0 on rejection, or -1 on error.
It should not put and error on the error stack since this could be misleading.
If all checks pass then ossl_cmp_msg_check_received()
=over 4
=item learns the senderNonce from the received message,
=item learns the transaction ID if it is not yet in B<ctx>, and
=item adds any extraCerts contained in the <msg> to the list of untrusted
certificates in B<ctx> for future use, such that
they are available already to the certificate confirmation callback and the
peer does not need to send them again (at least not in the same transaction).
For efficiency, the extraCerts are prepended to the list so they get used first.
=back
=head1 RETURN VALUES
ossl_cmp_msg_check_received() returns the message body type (which is >= 0)
on success, -1 on error.
=head1 SEE ALSO
L<OSSL_CMP_validate_msg(3)>
=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_msg_create.pod
+1 -2
View File
@@ -62,8 +62,7 @@ See the individual functions above.
=head1 SEE ALSO
L<OSSL_CMP_CTX_new(3)>, L<OSSL_CMP_exec_IR_ses(3)>,
L<OSSL_CMP_MSG_http_perform(3)>
L<OSSL_CMP_CTX_new(3)>, L<OSSL_CMP_exec_IR_ses(3)>
=head1 HISTORY
doc/internal/man3/ossl_cmp_statusinfo_new.pod → doc/internal/man3/ossl_cmp_pkisi_get_status.pod
+19 -34
View File
@@ -2,13 +2,11 @@
=head1 NAME
ossl_cmp_statusinfo_new,
ossl_cmp_pkisi_pkistatus_get,
ossl_cmp_pkisi_pkifailureinfo_get,
ossl_cmp_pkisi_pkifailureinfo_check,
ossl_cmp_pkisi_failinfo_get0,
ossl_cmp_pkisi_statusstring_get0,
ossl_pkisi_snprint
ossl_cmp_pkisi_get_status,
ossl_cmp_PKIStatus_to_string,
ossl_cmp_pkisi_get0_statusString,
ossl_cmp_pkisi_get_pkifailureinfo,
ossl_cmp_pkisi_check_pkifailureinfo
- functions for managing PKI status information
=head1 SYNOPSIS
@@ -44,40 +42,27 @@ ossl_pkisi_snprint
# define OSSL_CMP_PKIFAILUREINFO_duplicateCertReq 26
# define OSSL_CMP_PKIFAILUREINFO_MAX 26
OSSL_CMP_PKISI *ossl_cmp_statusinfo_new(int status, int fail_info,
const char *text);
int ossl_cmp_pkisi_pkistatus_get(OSSL_CMP_PKISI *si);
int ossl_cmp_pkisi_pkifailureinfo_get(OSSL_CMP_PKISI *si);
int ossl_cmp_pkisi_pkifailureinfo_check(OSSL_CMP_PKISI *si, int bit_index);
OSSL_CMP_PKIFAILUREINFO *ossl_cmp_pkisi_failinfo_get0(const OSSL_CMP_PKISI *si);
OSSL_CMP_PKIFREETEXT *ossl_cmp_pkisi_statusstring_get0(const OSSL_CMP_PKISI *si);
char *ossl_pkisi_snprint(OSSL_CMP_PKISI *si, char *buf, int bufsize);
int ossl_cmp_pkisi_get_status(const OSSL_CMP_PKISI *si);
const char *ossl_cmp_PKIStatus_to_string(int status);
OSSL_CMP_PKIFREETEXT *ossl_cmp_pkisi_get0_statusString(const OSSL_CMP_PKISI *si);
int ossl_cmp_pkisi_get_pkifailureinfo(const OSSL_CMP_PKISI *si);
int ossl_cmp_pkisi_check_pkifailureinfo(const OSSL_CMP_PKISI *si, int index);
=head1 DESCRIPTION
ossl_cmp_statusinfo_new() creates a new PKIStatusInfo structure and fills it
with the given values. It sets the status field to B<status>.
If B<text> is not NULL, it is copied to statusString.
B<fail_info> is is interpreted as bit pattern for the failInfo field.
Returns a pointer to the structure on success, or NULL on error.
ossl_cmp_pkisi_get_status() returns the PKIStatus of B<si>, or -1 on error.
ossl_cmp_pkisi_pkistatus_get() returns the PKIStatus of B<si>, or -1 on error.
ossl_cmp_PKIStatus_to_string() returns a human-readable string representing
the PKIStatus values as specified in RFC 4210, Appendix F.
ossl_cmp_pkisi_pkifailureinfo_get() returns the PKIFailureInfo bits
of B<si>, encoded as integer, or -1 on error.
ossl_cmp_pkisi_pkifailureinfo_check() returns the state of the bit (0 or 1)
with index B<bit_index> in the PKIFailureInfo of the B<si>, or -1 on error.
ossl_cmp_pkisi_failinfo_get0() returns a direct pointer to the failInfo
field contained in B<si>, or NULL on error.
ossl_cmp_pkisi_statusstring_get0() returns a direct pointer to the statusString
ossl_cmp_pkisi_get0_statusString() returns a direct pointer to the statusString
field contained in B<si>.
ossl_pkisi_snprint() places at max B<bufsize> characters of human-readable
error string of B<si> in pre-allocated B<buf>. Returns pointer to the same
B<buf> containing the string, or NULL on error.
ossl_cmp_pkisi_get_pkifailureinfo() returns the PKIFailureInfo bits
of B<si>, encoded as integer, or -1 on error.
ossl_cmp_pkisi_check_pkifailureinfo() returns the state of the bit (0 or 1)
with index B<index> in the PKIFailureInfo of the B<si>, or -1 on error.
=head1 NOTES
doc/internal/man3/ossl_param_bld_init.pod
-195
View File
@@ -1,195 +0,0 @@
=pod
=head1 NAME
ossl_param_bld_init, ossl_param_bld_to_param,
ossl_param_bld_free, ossl_param_bld_push_int, ossl_param_bld_push_uint,
ossl_param_bld_push_long, ossl_param_bld_push_ulong,
ossl_param_bld_push_int32, ossl_param_bld_push_uint32,
ossl_param_bld_push_int64, ossl_param_bld_push_uint64,
ossl_param_bld_push_size_t, ossl_param_bld_push_double,
ossl_param_bld_push_BN, ossl_param_bld_push_BN_pad,
ossl_param_bld_push_utf8_string, ossl_param_bld_push_utf8_ptr,
ossl_param_bld_push_octet_string, ossl_param_bld_push_octet_ptr
- functions to assist in the creation of OSSL_PARAM arrays
=head1 SYNOPSIS
=for openssl generic
#include "internal/params_build.h"
#define OSSL_PARAM_BLD_MAX 10
typedef struct { ... } OSSL_PARAM_BLD;
void ossl_param_bld_init(OSSL_PARAM_BLD *bld);
OSSL_PARAM *ossl_param_bld_to_param(OSSL_PARAM_BLD *bld);
void ossl_param_bld_free(OSSL_PARAM *params);
int ossl_param_bld_push_TYPE(OSSL_PARAM_BLD *bld, const char *key, TYPE val);
int ossl_param_bld_push_BN(OSSL_PARAM_BLD *bld, const char *key,
const BIGNUM *bn);
int ossl_param_bld_push_BN_pad(OSSL_PARAM_BLD *bld, const char *key,
const BIGNUM *bn, size_t sz);
int ossl_param_bld_push_utf8_string(OSSL_PARAM_BLD *bld, const char *key,
const char *buf, size_t bsize);
int ossl_param_bld_push_utf8_ptr(OSSL_PARAM_BLD *bld, const char *key,
char *buf, size_t bsize);
int ossl_param_bld_push_octet_string(OSSL_PARAM_BLD *bld, const char *key,
const void *buf, size_t bsize);
int ossl_param_bld_push_octet_ptr(OSSL_PARAM_BLD *bld, const char *key,
void *buf, size_t bsize);
=head1 DESCRIPTION
A collection of utility functions that simplify the creation of OSSL_PARAM
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
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.
ossl_param_bld_free() deallocates the memory allocated by
ossl_param_bld_to_param().
=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.
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 I<bn>.
If I<bn> is marked as being securely allocated, its OSSL_PARAM representation
will also be securely allocated.
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_BN_pad() is a function that will create an OSSL_PARAM object
that holds the specified BIGNUM I<bn>.
The object will be padded to occupy exactly I<sz> bytes, if insufficient space
is specified an error results.
If I<bn> is marked as being securely allocated, its OSSL_PARAM representation
will also be securely allocated.
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 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 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 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 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
ossl_param_bld_to_param() returns the allocated OSSL_PARAM array, or NULL
on error.
All of the ossl_param_bld_push_TYPE functions return 1 on success and 0
on error.
=head1 NOTES
The constant B<OSSL_PARAM_BLD_MAX> specifies the maximum number of parameters
that can be added.
Exceeding this will result in the push functions returning errors.
The structure B<OSSL_PARAM_BLD> should be considered opaque and subject to
change between versions.
=head1 EXAMPLES
Both examples creating an OSSL_PARAM array that contains an RSA key.
For both, the predefined key variables are:
BIGNUM *p, *q; /* both prime */
BIGNUM *n; /* = p * q */
unsigned int e; /* exponent, usually 65537 */
BIGNUM *d; /* e^-1 */
=head2 Example 1
This example shows how to create an OSSL_PARAM array that contains an RSA
private key.
OSSL_PARAM_BLD bld;
OSSL_PARAM *params;
ossl_param_bld_init(&bld, &secure);
if (!ossl_param_bld_push_BN(&bld, "p", p)
|| !ossl_param_bld_push_BN(&bld, "q", q)
|| !ossl_param_bld_push_uint(&bld, "e", e)
|| !ossl_param_bld_push_BN(&bld, "n", n)
|| !ossl_param_bld_push_BN(&bld, "d", d)
|| (params = ossl_param_bld_to_param(&bld)) == NULL)
goto err;
/* Use params */
...
ossl_param_bld_free(params);
=head2 Example 2
This example shows how to create an OSSL_PARAM array that contains an RSA
public key.
OSSL_PARAM_BLD bld;
OSSL_PARAM *params;
ossl_param_bld_init(&bld, &secure);
if (!ossl_param_bld_push_BN(&bld, "n", n)
|| !ossl_param_bld_push_BN(&bld, "d", d)
|| (params = ossl_param_bld_to_param(&bld)) == NULL)
goto err;
/* Use params */
...
ossl_param_bld_free(params);
=head1 SEE ALSO
L<OSSL_PARAM_int(3)>, L<OSSL_PARAM(3)>
=head1 HISTORY
The functions described here were all added in OpenSSL 3.0.
=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
doc/internal/man3/s2i_ASN1_UTF8STRING.pod
+3 -3
View File
@@ -3,12 +3,12 @@
=head1 NAME
i2s_ASN1_UTF8STRING,
s2i_ASN1_UTF8STRING,
s2i_ASN1_UTF8STRING
- convert objects from/to ASN.1/string representation
=head1 SYNOPSIS
=for openssl generic
#include "crypto/x509v3.h"
char *i2s_ASN1_UTF8STRING(X509V3_EXT_METHOD *method,
ASN1_UTF8STRING *utf8);
@@ -22,7 +22,7 @@ representation. This function is used for B<X509v3> extentions.
=head1 NOTES
The letters B<i> and B<s> in B<i2s_ASN1_UTF8STRING>() stand for
The letters B<i> and B<s> in i2s_ASN1_UTF8STRING() stand for
"internal" (that is, an internal C structure) and string respectively.
So B<i2s_ASN1_UTF8STRING>() converts from internal to string.
doc/internal/man7/DERlib.pod
+148
View File
@@ -0,0 +1,148 @@
=pod
=head1 NAME
DERlib - internal OpenSSL DER library
=head1 DESCRIPTION
OpenSSL contains an internal small DER reading and writing library,
as an alternative to the publically known i2d and d2i functions. It's
solely constituted of functions that work as building blocks to create
more similar functions to encode and decode larger structures.
All these functions have similar function signatures (C<something>
will vary depending on what the function will encode):
int DER_w_something(WPACKET *pkt, int tag, ...);
=begin comment
When readers are added, add this:
int DER_r_something(PACKET *pkt, int tag, ...);
=end comment
I<pkt> is the packet context used, and I<tag> should be the
context-specific tag value of the element being handled, or -1 if there
is no tag number for that element (you may use the convenience macro
B<DER_NO_CONTEXT> instead of -1). Any argument following is the C
variable that's being encoded or decoded.
=head2 DER writers / encoders
DER writers are based in L<WPACKET(3)>, a generic packet writing
library, so before using any of them, I<pkt> must be initialized
using L<WPACKET_init_der(3)> or L<WPACKET_init_null_der(3)>
DER writers must be used in reverse order, except for the wrapping
functions that implement a constructed element. The latter are easily
recognised by their function name including the words C<begin> and
C<end>. As an example, we can look at the DSA signature structure,
which is defined like this in ASN.1 terms:
-- Copied from RFC 3279, section 2.2.2
Dss-Sig-Value ::= SEQUENCE {
r INTEGER,
s INTEGER }
With the DER library, this is the correspoding code, given two OpenSSL
B<BIGNUM>s I<r> and I<s>:
int ok = DER_w_begin_sequence(pkt, -1)
&& DER_w_bn(pkg, -1, s)
&& DER_w_bn(pkg, -1, r)
&& DER_w_end_sequence(pkt, -1);
As an example of the use of I<tag>, an ASN.1 element like this:
v [1] INTEGER OPTIONAL
Would be encoded like this:
DER_w_bn(pkt, 1, v)
=begin comment
=head2 DER readers / decoders
TBA
=end comment
=head1 EXAMPLES
A more complex example, encoding the AlgorithmIdentifier with
RSASSA-PSS values.
As a reminder, the AlgorithmIdentifier is specified like this:
-- From RFC 3280, section 4.1.1.2
AlgorithmIdentifier ::= SEQUENCE {
algorithm OBJECT IDENTIFIER,
parameters ANY DEFINED BY algorithm OPTIONAL }
And the RSASSA-PSS OID and parameters are specified like this:
-- From RFC 3279, section 3.1
id-RSASSA-PSS OBJECT IDENTIFIER ::= { pkcs-1 10 }
RSASSA-PSS-params ::= SEQUENCE {
hashAlgorithm [0] HashAlgorithm DEFAULT
sha1Identifier,
maskGenAlgorithm [1] MaskGenAlgorithm DEFAULT
mgf1SHA1Identifier,
saltLength [2] INTEGER DEFAULT 20,
trailerField [3] INTEGER DEFAULT 1 }
The value we want to encode, written in ASN.1 syntax:
{
algorithm id-RSASSA-PSS,
parameters {
hashAlgorithm sha256Identifier,
maskGenAlgorithm mgf1SHA256Identifier,
saltLength 20 -- unnecessarily explicit
}
}
Assuming that we have precompiled constants for C<id-RSASSA-PSS>,
C<sha256Identifier> and C<mgf1SHA256Identifier>, the DER writing code
looks as follows. This is a complete function to write that specific
value:
int DER_w_AlgorithmIdentifier_RSASSA_PSS_special(WPACKET *pkt,
int tag,
RSA *rsa)
{
return DER_w_begin_sequence(pkt, tag)
&& (DER_w_begin_sequence(pkt, DER_NO_CONTEXT)
&& DER_w_ulong(pkt, 2, 20)
&& DER_w_precompiled(pkt, 1,
der_mgf1SHA256Identifier,
sizeof(der_mgf1SHA256Identifier))
&& DER_w_precompiled(pkt, 0,
der_sha256Identifier,
sizeof(der_sha256Identifier))
&& DER_w_end_sequence(pkt, DER_NO_CONTEXT))
&& DER_w_precompiled(pkt, DER_NO_CONTEXT,
der_id_RSASSA_PSS,
sizeof(der_id_RSASSA_PSS))
&& DER_w_end_sequence(pkt, tag);
}
=head1 SEE ALSO
L<DER_w_bn(3)>, L<DER_w_begin_sequence(3)>, L<DER_w_precompiled(3)>
=head1 COPYRIGHT
Copyright 2020 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