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-03-07 13:14:32 +09:00
parent 25fbda8e8b
commit ee0cf37f98
226 changed files with 20407 additions and 2210 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/man3/ASN1_STRING_length.pod
+1 -1
View File
@@ -14,7 +14,7 @@ ASN1_STRING_to_UTF8 - ASN1_STRING utility functions
const unsigned char * ASN1_STRING_get0_data(const ASN1_STRING *x);
unsigned char * ASN1_STRING_data(ASN1_STRING *x);
ASN1_STRING * ASN1_STRING_dup(ASN1_STRING *a);
ASN1_STRING * ASN1_STRING_dup(const ASN1_STRING *a);
int ASN1_STRING_cmp(ASN1_STRING *a, ASN1_STRING *b);
doc/man3/ASN1_TIME_set.pod
+32 -32
View File
@@ -173,38 +173,6 @@ certificates complying with RFC5280 et al use GMT anyway.
Use the ASN1_TIME_normalize() function to normalize the time value before
printing to get GMT results.
=head1 EXAMPLES
Set a time structure to one hour after the current time and print it out:
#include <time.h>
#include <openssl/asn1.h>
ASN1_TIME *tm;
time_t t;
BIO *b;
t = time(NULL);
tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60);
b = BIO_new_fp(stdout, BIO_NOCLOSE);
ASN1_TIME_print(b, tm);
ASN1_STRING_free(tm);
BIO_free(b);
Determine if one time is later or sooner than the current time:
int day, sec;
if (!ASN1_TIME_diff(&day, &sec, NULL, to))
/* Invalid time format */
if (day > 0 || sec > 0)
printf("Later\n");
else if (day < 0 || sec < 0)
printf("Sooner\n");
else
printf("Same\n");
=head1 RETURN VALUES
ASN1_TIME_set(), ASN1_UTCTIME_set(), ASN1_GENERALIZEDTIME_set(), ASN1_TIME_adj(),
@@ -238,6 +206,38 @@ ASN1_TIME_compare() returns -1 if B<a> is before B<b>, 0 if B<a> equals B<b>, or
ASN1_TIME_to_generalizedtime() returns a pointer to
the appropriate time structure on success or NULL if an error occurred.
=head1 EXAMPLES
Set a time structure to one hour after the current time and print it out:
#include <time.h>
#include <openssl/asn1.h>
ASN1_TIME *tm;
time_t t;
BIO *b;
t = time(NULL);
tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60);
b = BIO_new_fp(stdout, BIO_NOCLOSE);
ASN1_TIME_print(b, tm);
ASN1_STRING_free(tm);
BIO_free(b);
Determine if one time is later or sooner than the current time:
int day, sec;
if (!ASN1_TIME_diff(&day, &sec, NULL, to))
/* Invalid time format */
if (day > 0 || sec > 0)
printf("Later\n");
else if (day < 0 || sec < 0)
printf("Sooner\n");
else
printf("Same\n");
=head1 HISTORY
The ASN1_TIME_to_tm() function was added in OpenSSL 1.1.1.
doc/man3/ASN1_generate_nconf.pod
+7 -7
View File
@@ -162,6 +162,13 @@ bits are zero.
=back
=head1 RETURN VALUES
ASN1_generate_nconf() and ASN1_generate_v3() return the encoded
data as an B<ASN1_TYPE> structure or B<NULL> if an error occurred.
The error codes that can be obtained by L<ERR_get_error(3)>.
=head1 EXAMPLES
A simple IA5String:
@@ -247,13 +254,6 @@ structure:
e=INTEGER:0x010001
=head1 RETURN VALUES
ASN1_generate_nconf() and ASN1_generate_v3() return the encoded
data as an B<ASN1_TYPE> structure or B<NULL> if an error occurred.
The error codes that can be obtained by L<ERR_get_error(3)>.
=head1 SEE ALSO
L<ERR_get_error(3)>
doc/man3/BIO_push.pod
+7 -7
View File
@@ -36,6 +36,13 @@ The process of calling BIO_push() and BIO_pop() on a BIO may have additional
consequences (a control call is made to the affected BIOs) any effects will
be noted in the descriptions of individual BIOs.
=head1 RETURN VALUES
BIO_push() returns the end of the chain, B<b>.
BIO_pop() returns the next BIO in the chain, or NULL if there is no next
BIO.
=head1 EXAMPLES
For these examples suppose B<md1> and B<md2> are digest BIOs, B<b64> is
@@ -62,13 +69,6 @@ by B<md1> and B<md2>. If the call:
The call will return B<b64> and the new chain will be B<md1-b64-f> data can
be written to B<md1> as before.
=head1 RETURN VALUES
BIO_push() returns the end of the chain, B<b>.
BIO_pop() returns the next BIO in the chain, or NULL if there is no next
BIO.
=head1 SEE ALSO
L<bio>
doc/man3/BIO_s_file.pod
+18 -18
View File
@@ -80,6 +80,24 @@ On Windows BIO_new_files reserves for the filename argument to be
UTF-8 encoded. In other words if you have to make it work in multi-
lingual environment, encode file names in UTF-8.
=head1 RETURN VALUES
BIO_s_file() returns the file BIO method.
BIO_new_file() and BIO_new_fp() return a file BIO or NULL if an error
occurred.
BIO_set_fp() and BIO_get_fp() return 1 for success or 0 for failure
(although the current implementation never return 0).
BIO_seek() returns the same value as the underlying fseek() function:
0 for success or -1 for failure.
BIO_tell() returns the current file position.
BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and
BIO_rw_filename() return 1 for success or 0 for failure.
=head1 EXAMPLES
File BIO "hello world":
@@ -122,24 +140,6 @@ Alternative technique:
BIO_printf(out, "Hello World\n");
BIO_free(out);
=head1 RETURN VALUES
BIO_s_file() returns the file BIO method.
BIO_new_file() and BIO_new_fp() return a file BIO or NULL if an error
occurred.
BIO_set_fp() and BIO_get_fp() return 1 for success or 0 for failure
(although the current implementation never return 0).
BIO_seek() returns the same value as the underlying fseek() function:
0 for success or -1 for failure.
BIO_tell() returns the current file position.
BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and
BIO_rw_filename() return 1 for success or 0 for failure.
=head1 BUGS
BIO_reset() and BIO_seek() are implemented using fseek() on the underlying
doc/man3/BN_bn2bin.pod
+11 -3
View File
@@ -3,9 +3,9 @@
=head1 NAME
BN_bn2binpad,
BN_bn2bin, BN_bin2bn, BN_bn2lebinpad, BN_lebin2bn, BN_bn2hex, BN_bn2dec,
BN_hex2bn, BN_dec2bn, BN_print, BN_print_fp, BN_bn2mpi,
BN_mpi2bn - format conversions
BN_bn2bin, BN_bin2bn, BN_bn2lebinpad, BN_lebin2bn,
BN_bn2nativepad, BN_native2bn, BN_bn2hex, BN_bn2dec, BN_hex2bn, BN_dec2bn,
BN_print, BN_print_fp, BN_bn2mpi, BN_mpi2bn - format conversions
=head1 SYNOPSIS
@@ -18,6 +18,9 @@ BN_mpi2bn - format conversions
int BN_bn2lebinpad(const BIGNUM *a, unsigned char *to, int tolen);
BIGNUM *BN_lebin2bn(const unsigned char *s, int len, BIGNUM *ret);
int BN_bn2nativepad(const BIGNUM *a, unsigned char *to, int tolen);
BIGNUM *BN_native2bn(const unsigned char *s, int len, BIGNUM *ret);
char *BN_bn2hex(const BIGNUM *a);
char *BN_bn2dec(const BIGNUM *a);
int BN_hex2bn(BIGNUM **a, const char *str);
@@ -47,6 +50,11 @@ NULL, a new B<BIGNUM> is created.
BN_bn2lebinpad() and BN_lebin2bn() are identical to BN_bn2binpad() and
BN_bin2bn() except the buffer is in little-endian format.
BN_bn2nativepad() and BN_native2bn() are identical to BN_bn2binpad() and
BN_bin2bn() except the buffer is in native format, i.e. most significant
byte first on big-endian platforms, and least significant byte first on
little-endian platforms.
BN_bn2hex() and BN_bn2dec() return printable strings containing the
hexadecimal and decimal encoding of B<a> respectively. For negative
numbers, the string is prefaced with a leading '-'. The string must be
doc/man3/CONF_modules_load_file.pod
+6 -6
View File
@@ -67,6 +67,12 @@ Applications can use the CONF_modules_load() function if they wish to load a
configuration file themselves and have finer control over how errors are
treated.
=head1 RETURN VALUES
These functions return 1 for success and a zero or negative value for
failure. If module errors are not ignored the return code will reflect the
return value of the failing module (this will always be zero or negative).
=head1 EXAMPLES
Load a configuration file and print out any errors and exit (missing file
@@ -122,12 +128,6 @@ Load and parse configuration file manually, custom error handling:
NCONF_free(cnf);
}
=head1 RETURN VALUES
These functions return 1 for success and a zero or negative value for
failure. If module errors are not ignored the return code will reflect the
return value of the failing module (this will always be zero or negative).
=head1 SEE ALSO
L<config(5)>, L<OPENSSL_config(3)>
doc/man3/CRYPTO_get_ex_new_index.pod
+1 -1
View File
@@ -104,7 +104,7 @@ to avoid likely double-free crashes.
The function B<CRYPTO_free_ex_data> is used to free all exdata attached
to a structure. The appropriate type-specific routine must be used.
The B<class_index> identifies the structure type, the B<obj> is
be the pointer to the actual structure, and B<r> is a pointer to the
a pointer to the actual structure, and B<r> is a pointer to the
structure's exdata field.
=head2 Callback Functions
doc/man3/EVP_DigestVerifyInit.pod
+2 -2
View File
@@ -28,8 +28,8 @@ EVP_PKEY_CTX of the verification operation will be written to B<*pctx>: this
can be used to set alternative verification options. Note that any existing
value in B<*pctx> is overwritten. The EVP_PKEY_CTX value returned must not be freed
directly by the application if B<ctx> is not assigned an EVP_PKEY_CTX value before
being passed to EVP_DigestSignInit() (which means the EVP_PKEY_CTX is created
inside EVP_DigestSignInit() and it will be freed automatically when the
being passed to EVP_DigestVerifyInit() (which means the EVP_PKEY_CTX is created
inside EVP_DigestVerifyInit() and it will be freed automatically when the
EVP_MD_CTX is freed).
No B<EVP_PKEY_CTX> will be created by EVP_DigsetSignInit() if the passed B<ctx>
doc/man3/EVP_EncryptInit.pod
+3 -1
View File
@@ -479,7 +479,9 @@ The following I<ctrl>s are supported for the ChaCha20-Poly1305 AEAD algorithm.
Sets the nonce length. This call can only be made before specifying the nonce.
If not called a default nonce length of 12 (i.e. 96 bits) is used. The maximum
nonce length is 16 (B<CHACHA_CTR_SIZE>, i.e. 128-bits).
nonce length is 12 bytes (i.e. 96-bits). If a nonce of less than 12 bytes is set
then the nonce is automatically padded with leading 0 bytes to make it 12 bytes
in length.
=item EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag)
doc/man3/EVP_PKEY_CTX_ctrl.pod
+2 -1
View File
@@ -74,7 +74,8 @@ EVP_PKEY_CTX_set1_id, EVP_PKEY_CTX_get1_id, EVP_PKEY_CTX_get1_id_len
int EVP_PKEY_CTX_set_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);
int EVP_PKEY_CTX_get_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD **pmd);
int EVP_PKEY_CTX_set_mac_key(EVP_PKEY_CTX *ctx, unsigned char *key, int len);
int EVP_PKEY_CTX_set_mac_key(EVP_PKEY_CTX *ctx, const unsigned char *key,
int len);
#include <openssl/rsa.h>
doc/man3/EVP_PKEY_CTX_new.pod
+1 -1
View File
@@ -10,7 +10,7 @@ EVP_PKEY_CTX_new, EVP_PKEY_CTX_new_id, EVP_PKEY_CTX_dup, EVP_PKEY_CTX_free - pub
EVP_PKEY_CTX *EVP_PKEY_CTX_new(EVP_PKEY *pkey, ENGINE *e);
EVP_PKEY_CTX *EVP_PKEY_CTX_new_id(int id, ENGINE *e);
EVP_PKEY_CTX *EVP_PKEY_CTX_dup(EVP_PKEY_CTX *ctx);
EVP_PKEY_CTX *EVP_PKEY_CTX_dup(const EVP_PKEY_CTX *ctx);
void EVP_PKEY_CTX_free(EVP_PKEY_CTX *ctx);
=head1 DESCRIPTION
doc/man3/EVP_PKEY_set1_RSA.pod
+11 -11
View File
@@ -28,10 +28,10 @@ EVP_PKEY_set1_engine - EVP_PKEY assignment functions
const unsigned char *EVP_PKEY_get0_hmac(const EVP_PKEY *pkey, size_t *len);
const unsigned char *EVP_PKEY_get0_poly1305(const EVP_PKEY *pkey, size_t *len);
const unsigned char *EVP_PKEY_get0_siphash(const EVP_PKEY *pkey, size_t *len);
RSA *EVP_PKEY_get0_RSA(EVP_PKEY *pkey);
DSA *EVP_PKEY_get0_DSA(EVP_PKEY *pkey);
DH *EVP_PKEY_get0_DH(EVP_PKEY *pkey);
EC_KEY *EVP_PKEY_get0_EC_KEY(EVP_PKEY *pkey);
RSA *EVP_PKEY_get0_RSA(const EVP_PKEY *pkey);
DSA *EVP_PKEY_get0_DSA(const EVP_PKEY *pkey);
DH *EVP_PKEY_get0_DH(const EVP_PKEY *pkey);
EC_KEY *EVP_PKEY_get0_EC_KEY(const EVP_PKEY *pkey);
int EVP_PKEY_assign_RSA(EVP_PKEY *pkey, RSA *key);
int EVP_PKEY_assign_DSA(EVP_PKEY *pkey, DSA *key);
@@ -111,13 +111,6 @@ is no longer possible: the equivalent is EVP_PKEY_base_id(pkey).
EVP_PKEY_set1_engine() is typically used by an ENGINE returning an HSM
key as part of its routine to load a private key.
=head1 EXAMPLES
After loading an ECC key, it is possible to convert it to using SM2
algorithms with EVP_PKEY_set_alias_type:
EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2);
=head1 RETURN VALUES
EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and
@@ -138,6 +131,13 @@ EVP_PKEY_set1_engine() returns 1 for success and 0 for failure.
EVP_PKEY_set_alias_type() returns 1 for success and 0 for error.
=head1 EXAMPLES
After loading an ECC key, it is possible to convert it to using SM2
algorithms with EVP_PKEY_set_alias_type:
EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2);
=head1 SEE ALSO
L<EVP_PKEY_new(3)>
doc/man3/OBJ_nid2obj.pod
+11 -11
View File
@@ -130,6 +130,17 @@ These functions cannot return B<const> because an B<ASN1_OBJECT> can
represent both an internal, constant, OID and a dynamically-created one.
The latter cannot be constant because it needs to be freed after use.
=head1 RETURN VALUES
OBJ_nid2obj() returns an B<ASN1_OBJECT> structure or B<NULL> is an
error occurred.
OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B<NULL>
on error.
OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return
a NID or B<NID_undef> on error.
=head1 EXAMPLES
Create an object for B<commonName>:
@@ -159,17 +170,6 @@ Instead B<buf> must point to a valid buffer and B<buf_len> should
be set to a positive value. A buffer length of 80 should be more
than enough to handle any OID encountered in practice.
=head1 RETURN VALUES
OBJ_nid2obj() returns an B<ASN1_OBJECT> structure or B<NULL> is an
error occurred.
OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B<NULL>
on error.
OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return
a NID or B<NID_undef> on error.
=head1 SEE ALSO
L<ERR_get_error(3)>
doc/man3/OPENSSL_s390xcap.pod
+4 -4
View File
@@ -139,6 +139,10 @@ the numbering is continuous across 64-bit mask boundaries.
# 20 1<<43 KMA-GCM-AES-256
:
=head1 RETURN VALUES
Not available.
=head1 EXAMPLES
Disables all instruction set extensions which the z196 processor does not implement:
@@ -153,10 +157,6 @@ Disables the KM-XTS-AES and and the KIMD-SHAKE function codes:
OPENSSL_s390xcap="km:~0x2800:~0;kimd:~0xc000000:~0"
=head1 RETURN VALUES
Not available.
=head1 SEE ALSO
[1] z/Architecture Principles of Operation, SA22-7832-11
doc/man3/OSSL_PARAM.pod
+302
View File
@@ -0,0 +1,302 @@
=pod
=head1 NAME
OSSL_PARAM - a structure to pass or request object parameters
=head1 SYNOPSIS
#include <openssl/core.h>
typedef struct ossl_param_st OSSL_PARAM;
struct ossl_param_st {
const char *key; /* the name of the parameter */
unsigned char data_type; /* declare what kind of content is in buffer */
void *buffer; /* value being passed in or out */
size_t buffer_size; /* buffer size */
size_t *return_size; /* OPTIONAL: address to content size */
};
=head1 DESCRIPTION
C<OSSL_PARAM> is a type that allows passing arbitrary data for some
object between two parties that have no or very little shared
knowledge about their respective internal structures for that object.
A typical usage example could be an application that wants to set some
parameters for an object, or wants to find out some parameters of an
object.
Arrays of this type can be used for two purposes:
=over 4
=item *
Setting parameters for some object.
The caller sets up the C<OSSL_PARAM> array and calls some function
(the I<setter>) that has intimate knowledge about the object that can
take the data from the C<OSSL_PARAM> array and assign them in a
suitable form for the internal structure of the object.
=item *
Request parameters of some object.
The caller (the I<requestor>) sets up the C<OSSL_PARAM> array and
calls some function (the I<responder>) that has intimate knowledge
about the object, which can take the internal data of the object and
copy (possibly convert) that to the buffers prepared by the
I<requestor>.
=back
=head2 C<OSSL_PARAM> fields
=over 4
=item C<key>
The identity of the parameter in the form of a string.
=item C<data_type>
=for comment It's still debated if this field should be present, or if
the type should always be implied by how it's used.
Either way, these data types will have to be passed together with the
names as an array of OSSL_ITEM, for discovery purposes.
The C<data_type> is a value that describes the type and organization of
the data.
See L</Supported types> below for a description of the types.
=item C<buffer>
=item C<buffer_size>
C<buffer> is a pointer to the memory where the parameter data is (when
setting parameters) or shall (when requesting parameters) be stored,
and C<buffer_size> is its size in bytes.
The organization of the data depends on the parameter type and flag.
=item C<return_size>
When an array of C<OSSL_PARAM> is used to request data, the
I<responder> must set this field to indicate the actual size of the
parameter data.
In case the C<buffer_size> is too small for the data, the I<responder>
must still set this field to indicate the minimum buffer size
required.
=back
B<NOTE:>
The key names and associated types are defined by the entity that
offers these parameters, i.e. names for parameters provided by the
OpenSSL libraries are defined by the libraries, and names for
parameters provided by providers are defined by those providers,
except for the pointer form of strings (see data type descriptions
below).
Entities that want to set or request parameters need to know what
those keys are and of what type, any functionality between those two
entities should remain oblivious and just pass the C<OSSL_PARAM> array
along.
=head2 Supported types
The C<data_type> field can be one of the following types:
=over 4
=item C<OSSL_PARAM_INTEGER>
=item C<OSSL_PARAM_UNSIGNED_INTEGER>
The parameter data is an integer (signed or unsigned) of arbitrary
length, organized in native form, i.e. most significant byte first on
Big-Endian systems, and least significant byte first on Little-Endian
systems.
=item C<OSSL_PARAM_REAL>
=for comment It's still debated if we need this or not.
The parameter data is a floating point value in native form.
=item C<OSSL_PARAM_UTF8_STRING>
The parameter data is a printable string.
=item C<OSSL_PARAM_OCTET_STRING>
The parameter data is an arbitrary string of bytes.
=back
Additionally, this flag can be added to any type:
=over 4
=item C<OSSL_PARAM_POINTER_FLAG>
With this flag, C<buffer> doesn't point directly at the data, but at a
pointer that points at the data.
This can be used to indicate that constant data is or will be passed,
and there is therefore no need to copy the data that is passed, just
the pointer to it.
If an C<OSSL_PARAM> with this flag set is used to set a parameter,
C<buffer_size> must be set to the size of the data, not the size of
the pointer to the data.
If this C<OSSL_PARAM> is used in a parameter request, C<buffer_size>
is not relevant.
However, the I<responder> will set C<*return_size> to the size of the
data (again, not the size of the pointer to the data).
Note that the use of this flag is B<fragile> and can only be safely
used for data that remains constant and in a constant location for a
long enough duration (such as the life-time of the entity that
offers these parameters).
=back
For convenience, these types are provided:
=over 4
=item C<OSSL_PARAM_UTF8_STRING_PTR>
=item C<OSSL_PARAM_OCTET_STRING_PTR>
These are combinations of C<OSSL_PARAM_UTF8_STRING> as well as
C<OSSL_PARAM_OCTET_STRING> with C<OSSL_PARAM_POINTER_FLAG>.
=back
=head1 NOTES
Both when setting and requesting parameters, the functions that are
called will have to decide what is and what is not an error.
The recommended behaviour is:
=over 4
=item *
Keys that a I<setter> or I<responder> doesn't recognise should simply
be ignored.
That in itself isn't an error.
=item *
If the keys that a called I<setter> recognises form a consistent
enough set of data, that call should succeed.
=item *
A I<responder> must never change the fields of an C<OSSL_PARAM>, it
may only change the contents of the buffers that C<buffer> and
C<return_size> point at.
=item *
If the data type for a key that it's associated with is incorrect,
the called function may return an error.
The called function may also try to convert the data to a suitable
form (for example, it's plausible to pass a large number as an octet
string, so even though a given key is defined as an
C<OSSL_PARAM_UNSIGNED_INTEGER>, is plausible to pass the value as an
C<OSSL_PARAM_OCTET_STRING>), but this is in no way mandatory.
=item *
If a I<responder> finds that some buffers are too small for the
requested data, it must set C<*return_size> for each such
C<OSSL_PARAM> item to the required size, and eventually return an
error.
=back
=begin comment RETURN VALUES doesn't make sense for a manual that only
describes a type, but document checkers still want that section, and
to have more than just the section title.
=head1 RETURN VALUES
txt
=end comment
=head1 EXAMPLES
A couple of examples to just show how C<OSSL_PARAM> arrays could be
set up.
=head3 Example 1
This example is for setting parameters on some object:
#include <openssl/core.h>
const char *foo = "some string";
size_t foo_l = strlen(foo) + 1;
const char bar[] = "some other string";
const OSSL_PARAM set[] = {
{ "foo", OSSL_PARAM_UTF8_STRING_PTR, &foo, foo_l, NULL },
{ "bar", OSSL_PARAM_UTF8_STRING, &bar, sizeof(bar), NULL },
{ NULL, 0, NULL, 0, NULL }
};
=head3 Example 2
This example is for requesting parameters on some object:
const char *foo = NULL;
size_t foo_l;
char bar[1024];
size_t bar_l;
const OSSL_PARAM request[] = {
{ "foo", OSSL_PARAM_UTF8_STRING_PTR, &foo, 0 /*irrelevant*/, &foo_l },
{ "bar", OSSL_PARAM_UTF8_STRING, &bar, sizeof(bar), &bar_l },
{ NULL, 0, NULL, 0, NULL }
};
A I<responder> that receives this array (as C<params> in this example)
could fill in the parameters like this:
/* const OSSL_PARAM *params */
int i;
for (i = 0; params[i].key != NULL; i++) {
if (strcmp(params[i].key, "foo") == 0) {
*(char **)params[i].buffer = "foo value";
*params[i].return_size = 10; /* size of "foo value" */
} else if (strcmp(params[i].key, "bar") == 0) {
memcpy(params[1].buffer, "bar value", 10);
*params[1].return_size = 10; /* size of "bar value" */
}
/* Ignore stuff we don't know */
}
=head1 SEE ALSO
L<openssl-core.h(7)>
=head1 HISTORY
C<OSSL_PARAM> was 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/man3/OSSL_trace_enabled.pod
+183
View File
@@ -0,0 +1,183 @@
=pod
=head1 NAME
OSSL_trace_enabled, OSSL_trace_begin, OSSL_trace_end
- OpenSSL Tracing API
=head1 SYNOPSIS
#include <openssl/trace.h>
int OSSL_trace_enabled(int category);
BIO *OSSL_trace_begin(int category);
void OSSL_trace_end(int category, BIO *channel);
=head1 DESCRIPTION
The functions described here are mainly interesting for those who provide
OpenSSL functionality, either in OpenSSL itself or in engine modules
or similar.
If operational (see L</NOTES> below), these functions are used to
generate free text tracing output.
The tracing output is divided into types which are enabled
individually by the application.
The tracing types are described in detail in
L<OSSL_trace_set_callback(3)/Trace types>.
The fallback type C<OSSL_TRACE_CATEGORY_ANY> should I<not> be used
with the functions described here.
=head2 Functions
OSSL_trace_enabled() can be used to check if tracing for the given
C<category> is enabled.
OSSL_trace_begin() is used to starts a tracing section, and get the
channel for the given C<category> in form of a BIO.
This BIO can only be used for output.
OSSL_trace_end() is used to end a tracing section.
Using OSSL_trace_begin() and OSSL_trace_end() to wrap tracing sections
is I<mandatory>.
The result of trying to produce tracing output outside of such
sections is undefined.
=head2 Convenience Macros
There are a number of convenience macros defined, to make tracing
easy and consistent.
C<OSSL_TRACE_BEGIN(category)> and C<OSSL_TRACE_END(category)> reserve
the B<BIO> C<trc_out> and are used as follows to wrap a trace section:
OSSL_TRACE_BEGIN(TLS) {
BIO_fprintf(trc_out, ... );
} OSSL_TRACE_END(TLS);
This will normally expands to:
do {
BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
if (trc_out != NULL) {
...
BIO_fprintf(trc_out, ...);
}
OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
} while (0);
C<OSSL_TRACE_CANCEL(category)> must be used before returning from or
jumping out of a trace section:
OSSL_TRACE_BEGIN(TLS) {
if (condition) {
OSSL_TRACE_CANCEL(TLS);
goto err;
}
BIO_fprintf(trc_out, ... );
} OSSL_TRACE_END(TLS);
This will normally expand to:
do {
BIO *trc_out = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
if (trc_out != NULL) {
if (condition) {
OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
goto err;
}
BIO_fprintf(trc_out, ... );
}
OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trc_out);
} while (0);
=head1 NOTES
It is advisable to always check that a trace type is enabled with
OSSL_trace_enabled() before generating any output, for example:
if (OSSL_trace_enabled(OSSL_TRACE_CATEGORY_TLS)) {
BIO *trace = OSSL_trace_begin(OSSL_TRACE_CATEGORY_TLS);
BIO_printf(trace, "FOO %d\n", somevalue);
BIO_dump(trace, somememory, somememory_l);
OSSL_trace_end(OSSL_TRACE_CATEGORY_TLS, trace);
}
=head2 Tracing disabled
The OpenSSL library may be built with tracing disabled, which makes
everything documented here inoperational.
When the library is built with tracing disabled:
=over 4
=item *
The macro C<OPENSSL_NO_TRACE> is defined in C<openssl/opensslconf.h>.
=item *
all functions are still present, bu OSSL_trace_enabled() will always
report the categories as disabled, and all other functions will do
nothing.
=item *
the convenience macros are defined to produce dead code.
For example, take this example from L</Convenience Macros> above:
OSSL_TRACE_BEGIN(TLS) {
if (condition) {
OSSL_TRACE_CANCEL(TLS);
goto err;
}
BIO_fprintf(trc_out, ... );
} OSSL_TRACE_END(TLS);
When the tracing API isn't operational, that will expand to:
do {
BIO *trc_out = NULL;
if (0) {
if (condition) {
((void)0);
goto err;
}
BIO_fprintf(trc_out, ... );
}
} while (0);
=back
=head1 RETURN VALUES
OSSL_trace_enabled() returns 1 if tracing for the given B<type> is
operational and enabled, otherwise 0.
OSSL_trace_begin() returns a C<BIO *> if the given B<type> is enabled,
otherwise C<NULL>.
=head1 HISTORY
The OpenSSL Tracing API was added ino OpenSSL 3.0.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/man3/OSSL_trace_get_category_num.pod
+44
View File
@@ -0,0 +1,44 @@
=pod
=head1 NAME
OSSL_trace_get_category_num, OSSL_trace_get_category_name
- OpenSSL tracing information functions
=head1 SYNOPSIS
#include <openssl/trace.h>
int OSSL_trace_get_category_num(const char *name);
const char *OSSL_trace_get_category_name(int num);
=head1 DESCRIPTION
OSSL_trace_get_category_num() gives the category number corresponding
to the given C<name>.
OSSL_trace_get_category_name() gives the category name corresponding
to the given C<num>.
=head1 RETURN VALUES
OSSL_trace_get_category_num() returns the category number if the given
C<name> is a recognised category name, otherwise -1.
OSSL_trace_get_category_name() returns the category name if the given
C<num> is a recognised category number, otherwise NULL.
=head1 HISTORY
The OpenSSL Tracing API was added ino OpenSSL 3.0.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/man3/OSSL_trace_set_channel.pod
+288
View File
@@ -0,0 +1,288 @@
=pod
=head1 NAME
OSSL_trace_set_channel, OSSL_trace_set_prefix, OSSL_trace_set_suffix,
OSSL_trace_set_callback, OSSL_trace_cb - Enabling trace output
=head1 SYNOPSIS
#include <openssl/trace.h>
typedef size_t (*OSSL_trace_cb)(const char *buf, size_t cnt,
int category, int cmd, void *data);
void OSSL_trace_set_channel(int category, BIO *bio);
void OSSL_trace_set_prefix(int category, const char *prefix);
void OSSL_trace_set_suffix(int category, const char *suffix);
void OSSL_trace_set_callback(int category, OSSL_trace_cb cb, void *data);
=head1 DESCRIPTION
If available (see L</NOTES> below), the application can request
internal trace output.
This output comes in form of free text for humans to read.
The trace output is divided into categories which can be
enabled individually.
They are enabled by giving them a channel in form of a BIO, or a
tracer callback, which is responsible for performing the actual
output.
=head2 Functions
OSSL_trace_set_channel() is used to enable the given trace C<category>
by giving it the B<BIO> C<bio>.
OSSL_trace_set_prefix() and OSSL_trace_set_suffix() can be used to add
an extra line for each channel, to be output before and after group of
tracing output.
What constitues an output group is decided by the code that produces
the output.
The lines given here are considered immutable; for more dynamic
tracing prefixes, consider setting a callback with
OSSL_trace_set_callback() instead.
OSSL_trace_set_callback() is used to enable the given trace
C<category> by giving it the tracer callback C<cb> with the associated
data C<data>, which will simply be passed through to C<cb> whenever
it's called.
This should be used when it's desirable to do form the trace output to
something suitable for application needs where a prefix and suffix
line aren't enough.
OSSL_trace_set_channel() and OSSL_trace_set_callback() are mutually
exclusive, calling one of them will clear whatever was set by the
previous call.
Calling OSSL_trace_set_channel() with C<NULL> for C<channel> or
OSSL_trace_set_callback() with C<NULL> for C<cb> disables tracing for
the given C<category>
=head2 Trace callback
The tracer callback must return a C<size_t>, which must be zero on
error and otherwise return the number of bytes that were output.
It receives a text buffer C<buf> with C<cnt> bytes of text, as well as
the C<category>, a control number C<cmd>, and the C<data> that was
passed to OSSL_trace_set_callback().
The possible control numbers are:
=over 4
=item C<OSSL_TRACE_CTRL_BEGIN>
The callback is called from OSSL_trace_begin(), which gives the
callback the possibility to output a dynamic starting line, or set a
prefix that should be output at the beginning of each line, or
something other.
=item C<OSSL_TRACE_CTRL_DURING>
The callback is called from any regular BIO output routine.
=item C<OSSL_TRACE_CTRL_END>
The callback is called from OSSL_trace_end(), which gives the callback
the possibility to output a dynamic ending line, or reset the line
prefix that was set with OSSL_TRACE_CTRL_BEGIN, or something other.
=back
=head2 Trace categories
The trace categories are simple numbers available through macros.
=over 4
=item C<OSSL_TRACE_CATEGORY_TRACE>
Traces the OpenSSL trace API itself.
More precisely, this will generate trace output any time a new
trace hook is set.
=item C<OSSL_TRACE_CATEGORY_INIT>
Traces OpenSSL library initialization and cleanup.
This needs special care, as OpenSSL will do automatic cleanup after
exit from C<main()>, and any tracing output done during this cleanup
will be lost if the tracing channel or callback were cleaned away
prematurely.
A suggestion is to make such cleanup part of a function that's
registered very early with L<atexit(3)>.
=item C<OSSL_TRACE_CATEGORY_TLS>
Traces the TLS/SSL protocoll.
=item C<OSSL_TRACE_CATEGORY_TLS_CIPHER>
Traces the ciphers used by the TLS/SSL protocoll.
=item C<OSSL_TRACE_CATEGORY_ENGINE_CONF>
Traces the ENGINE configuration.
=item C<OSSL_TRACE_CATEGORY_ENGINE_TABLE>
Traces the ENGINE algorithm table selection.
More precisely, engine_table_select(), the function that is used by
RSA, DSA (etc) code to select registered ENGINEs, cache defaults and
functional references (etc), will generate trace summaries.
=item C<OSSL_TRACE_CATEGORY_ENGINE_REF_COUNT>
Tracds the ENGINE reference counting.
More precisely, both reference counts in the ENGINE structure will be
monitored with a line of trace output generated for each change.
=item C<OSSL_TRACE_CATEGORY_PKCS5V2>
Traces PKCS#5 v2 key generation.
=item C<OSSL_TRACE_CATEGORY_PKCS12_KEYGEN>
Traces PKCS#12 key generation.
=item C<OSSL_TRACE_CATEGORY_PKCS12_DECRYPT>
Traces PKCS#12 decryption.
=item C<OSSL_TRACE_CATEGORY_X509V3_POLICY>
Traces X509v3 policy processing.
More precisely, this generates the complete policy tree at various
point during evaluation.
=item C<OSSL_TRACE_CATEGORY_BN_CTX>
Traces BIGNUM context operations.
=back
There is also C<OSSL_TRACE_CATEGORY_ANY>, which works as a fallback
and can be used to get I<all> trace output.
=head1 RETURN VALUES
OSSL_trace_set_channel(), OSSL_trace_set_prefix(),
OSSL_trace_set_suffix(), and OSSL_trace_set_callback() return 1 on
success, or 0 on failure.
=head1 EXAMPLES
In all examples below, we assume that the trace producing code is
this:
int foo = 42;
const char bar[] = { 0, 1, 2, 3, 4, 5, 6, 7,
8, 9, 10, 11, 12, 13, 14, 15 };
OSSL_TRACE_BEGIN(TLS) {
BIO_puts(trc_out, "foo: ");
BIO_printf(trc_out, "%d\n", foo);
BIO_dump(trc_out, bar, sizeof(bar));
} OSSL_TRACE_END(TLS);
=head1 Simple example
An example with just a channel and constant prefix / suffix.
int main(int argc, char *argv[])
{
BIO *err = BIO_new_fp(stderr, BIO_NOCLOSE | BIO_FP_TEXT);
OSSL_trace_set_channel(OSSL_TRACE_CATEGORY_SSL, err);
OSSL_trace_set_prefix(OSSL_TRACE_CATEGORY_SSL, "BEGIN TRACE[TLS]");
OSSL_trace_set_suffix(OSSL_TRACE_CATEGORY_SSL, "END TRACE[TLS]");
/* ... work ... */
}
When the trace producing code above is performed, this will be output
on standard error:
BEGIN TRACE[TLS]
foo: 42
0000 - 00 01 02 03 04 05 06 07-08 09 0a 0b 0c 0d 0e 0f ................
END TRACE[TLS]
=head2 Advanced example
This example uses the callback, and depends on pthreads functionality.
static size_t cb(const char *buf, size_t cnt,
int category, int cmd, void *vdata)
{
BIO *bio = vdata;
const char *label = NULL;
switch (cmd) {
case OSSL_TRACE_CTRL_BEGIN:
label = "BEGIN";
break;
case OSSL_TRACE_CTRL_END:
label = "END";
break;
}
if (label != NULL) {
union {
pthread_t tid;
unsigned long ltid;
} tid;
tid.tid = pthread_self();
BIO_printf(bio, "%s TRACE[%s]:%lx\n",
label, OSSL_trace_get_category_name(category), tid.ltid);
}
return (size_t)BIO_puts(bio, buf);
}
int main(int argc, char *argv[])
{
BIO *err = BIO_new_fp(stderr, BIO_NOCLOSE | BIO_FP_TEXT);
OSSL_trace_set_callback(OSSL_TRACE_CATEGORY_SSL, cb, err);
/* ... work ... */
}
The output is almost the same as for the simple example above.
BEGIN TRACE[TLS]:7f9eb0193b80
foo: 42
0000 - 00 01 02 03 04 05 06 07-08 09 0a 0b 0c 0d 0e 0f ................
END TRACE[TLS]:7f9eb0193b80
=head1 NOTES
=head2 Tracing disabled
The OpenSSL library may be built with tracing disabled, which makes
everything documented here inoperational.
When the library is built with tracing disabled, the macro
C<OPENSSL_NO_TRACE> is defined in C<openssl/opensslconf.h> and all
functions described here are inoperational, i.e. will do nothing.
=head1 HISTORY
OSSL_trace_set_channel(), OSSL_trace_set_prefix(),
OSSL_trace_set_suffix(), and OSSL_trace_set_callback() were all added
in OpenSSL 3.0.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/man3/PEM_read_bio_PrivateKey.pod
+68 -69
View File
@@ -36,7 +36,7 @@ PEM_write_bio_PKCS7, PEM_write_PKCS7 - PEM routines
pem_password_cb *cb, void *u);
EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x,
pem_password_cb *cb, void *u);
int PEM_write_bio_PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,
int PEM_write_bio_PrivateKey(BIO *bp, const EVP_PKEY *x, const EVP_CIPHER *enc,
unsigned char *kstr, int klen,
pem_password_cb *cb, void *u);
int PEM_write_bio_PrivateKey_traditional(BIO *bp, EVP_PKEY *x,
@@ -46,17 +46,16 @@ PEM_write_bio_PKCS7, PEM_write_PKCS7 - PEM routines
int PEM_write_PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
unsigned char *kstr, int klen,
pem_password_cb *cb, void *u);
int PEM_write_bio_PKCS8PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,
char *kstr, int klen,
pem_password_cb *cb, void *u);
int PEM_write_PKCS8PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
char *kstr, int klen,
pem_password_cb *cb, void *u);
int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, EVP_PKEY *x, int nid,
int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, const EVP_PKEY *x, int nid,
char *kstr, int klen,
pem_password_cb *cb, void *u);
int PEM_write_PKCS8PrivateKey_nid(FILE *fp, EVP_PKEY *x, int nid,
int PEM_write_PKCS8PrivateKey_nid(FILE *fp, const EVP_PKEY *x, int nid,
char *kstr, int klen,
pem_password_cb *cb, void *u);
@@ -298,71 +297,6 @@ arbitrary data to be passed to the callback by the application
B<must> return the number of characters in the passphrase or -1 if
an error occurred.
=head1 EXAMPLES
Although the PEM routines take several arguments in almost all applications
most of them are set to 0 or NULL.
Read a certificate in PEM format from a BIO:
X509 *x;
x = PEM_read_bio_X509(bp, NULL, 0, NULL);
if (x == NULL)
/* Error */
Alternative method:
X509 *x = NULL;
if (!PEM_read_bio_X509(bp, &x, 0, NULL))
/* Error */
Write a certificate to a BIO:
if (!PEM_write_bio_X509(bp, x))
/* Error */
Write a private key (using traditional format) to a BIO using
triple DES encryption, the pass phrase is prompted for:
if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL))
/* Error */
Write a private key (using PKCS#8 format) to a BIO using triple
DES encryption, using the pass phrase "hello":
if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(),
NULL, 0, 0, "hello"))
/* Error */
Read a private key from a BIO using a pass phrase callback:
key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
if (key == NULL)
/* Error */
Skeleton pass phrase callback:
int pass_cb(char *buf, int size, int rwflag, void *u)
{
/* We'd probably do something else if 'rwflag' is 1 */
printf("Enter pass phrase for \"%s\"\n", (char *)u);
/* get pass phrase, length 'len' into 'tmp' */
char *tmp = "hello";
if (tmp == NULL) /* An error occurred */
return -1;
size_t len = strlen(tmp);
if (len > size)
len = size;
memcpy(buf, tmp, len);
return len;
}
=head1 NOTES
The old B<PrivateKey> write routines are retained for compatibility.
@@ -460,6 +394,71 @@ if an error occurred.
The write routines return 1 for success or 0 for failure.
=head1 EXAMPLES
Although the PEM routines take several arguments in almost all applications
most of them are set to 0 or NULL.
Read a certificate in PEM format from a BIO:
X509 *x;
x = PEM_read_bio_X509(bp, NULL, 0, NULL);
if (x == NULL)
/* Error */
Alternative method:
X509 *x = NULL;
if (!PEM_read_bio_X509(bp, &x, 0, NULL))
/* Error */
Write a certificate to a BIO:
if (!PEM_write_bio_X509(bp, x))
/* Error */
Write a private key (using traditional format) to a BIO using
triple DES encryption, the pass phrase is prompted for:
if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL))
/* Error */
Write a private key (using PKCS#8 format) to a BIO using triple
DES encryption, using the pass phrase "hello":
if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(),
NULL, 0, 0, "hello"))
/* Error */
Read a private key from a BIO using a pass phrase callback:
key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
if (key == NULL)
/* Error */
Skeleton pass phrase callback:
int pass_cb(char *buf, int size, int rwflag, void *u)
{
/* We'd probably do something else if 'rwflag' is 1 */
printf("Enter pass phrase for \"%s\"\n", (char *)u);
/* get pass phrase, length 'len' into 'tmp' */
char *tmp = "hello";
if (tmp == NULL) /* An error occurred */
return -1;
size_t len = strlen(tmp);
if (len > size)
len = size;
memcpy(buf, tmp, len);
return len;
}
=head1 HISTORY
The old Netscape certificate sequences were no longer documented
doc/man3/SSL_CONF_cmd.pod
+17 -17
View File
@@ -598,6 +598,23 @@ checking or translation of the command value. For example if the return
value is B<SSL_CONF_TYPE_FILE> an application could translate a relative
pathname to an absolute pathname.
=head1 RETURN VALUES
SSL_CONF_cmd() returns 1 if the value of B<cmd> is recognised and B<value> is
B<NOT> used and 2 if both B<cmd> and B<value> are used. In other words it
returns the number of arguments processed. This is useful when processing
command lines.
A return value of -2 means B<cmd> is not recognised.
A return value of -3 means B<cmd> is recognised and the command requires a
value but B<value> is NULL.
A return code of 0 indicates that both B<cmd> and B<value> are valid but an
error occurred attempting to perform the operation: for example due to an
error in the syntax of B<value> in this case the error queue may provide
additional information.
=head1 EXAMPLES
Set supported signature algorithms:
@@ -644,23 +661,6 @@ Set supported curves to P-256, P-384:
SSL_CONF_cmd(ctx, "Curves", "P-256:P-384");
=head1 RETURN VALUES
SSL_CONF_cmd() returns 1 if the value of B<cmd> is recognised and B<value> is
B<NOT> used and 2 if both B<cmd> and B<value> are used. In other words it
returns the number of arguments processed. This is useful when processing
command lines.
A return value of -2 means B<cmd> is not recognised.
A return value of -3 means B<cmd> is recognised and the command requires a
value but B<value> is NULL.
A return code of 0 indicates that both B<cmd> and B<value> are valid but an
error occurred attempting to perform the operation: for example due to an
error in the syntax of B<value> in this case the error queue may provide
additional information.
=head1 SEE ALSO
L<SSL_CONF_CTX_new(3)>,
doc/man3/SSL_CTX_load_verify_locations.pod
+17 -17
View File
@@ -100,23 +100,6 @@ with different expiration dates. If a "certificate expired" verification
error occurs, no other certificate will be searched. Make sure to not
have expired certificates mixed with valid ones.
=head1 EXAMPLES
Generate a CA certificate file with descriptive text from the CA certificates
ca1.pem ca2.pem ca3.pem:
#!/bin/sh
rm CAfile.pem
for i in ca1.pem ca2.pem ca3.pem ; do
openssl x509 -in $i -text >> CAfile.pem
done
Prepare the directory /some/where/certs containing several CA certificates
for use as B<CApath>:
cd /some/where/certs
c_rehash .
=head1 RETURN VALUES
For SSL_CTX_load_verify_locations the following return values can occur:
@@ -139,6 +122,23 @@ SSL_CTX_set_default_verify_paths(), SSL_CTX_set_default_verify_dir() and
SSL_CTX_set_default_verify_file() all return 1 on success or 0 on failure. A
missing default location is still treated as a success.
=head1 EXAMPLES
Generate a CA certificate file with descriptive text from the CA certificates
ca1.pem ca2.pem ca3.pem:
#!/bin/sh
rm CAfile.pem
for i in ca1.pem ca2.pem ca3.pem ; do
openssl x509 -in $i -text >> CAfile.pem
done
Prepare the directory /some/where/certs containing several CA certificates
for use as B<CApath>:
cd /some/where/certs
c_rehash .
=head1 SEE ALSO
L<ssl(7)>,
doc/man3/SSL_CTX_set1_sigalgs.pod
+4 -4
View File
@@ -83,6 +83,10 @@ be used with the B<_list> forms of the API.
The use of MD5 as a digest is strongly discouraged due to security weaknesses.
=head1 RETURN VALUES
All these functions return 1 for success and 0 for failure.
=head1 EXAMPLES
Set supported signature algorithms to SHA256 with ECDSA and SHA256 with RSA
@@ -97,10 +101,6 @@ using a string:
SSL_CTX_set1_sigalgs_list(ctx, "ECDSA+SHA256:RSA+SHA256");
=head1 RETURN VALUES
All these functions return 1 for success and 0 for failure.
=head1 SEE ALSO
L<ssl(7)>, L<SSL_get_shared_sigalgs(3)>,
doc/man3/SSL_CTX_set_generate_session_id.pod
+8 -8
View File
@@ -82,6 +82,14 @@ and the same race condition applies.
The callback must return 0 if it cannot generate a session id for whatever
reason and return 1 on success.
=head1 RETURN VALUES
SSL_CTX_set_generate_session_id() and SSL_set_generate_session_id()
always return 1.
SSL_has_matching_session_id() returns 1 if another session with the
same id is already in the cache.
=head1 EXAMPLES
The callback function listed will generate a session id with the
@@ -114,14 +122,6 @@ server id given, and will fill the rest with pseudo random bytes:
}
=head1 RETURN VALUES
SSL_CTX_set_generate_session_id() and SSL_set_generate_session_id()
always return 1.
SSL_has_matching_session_id() returns 1 if another session with the
same id is already in the cache.
=head1 SEE ALSO
L<ssl(7)>, L<SSL_get_version(3)>
doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod
+4 -4
View File
@@ -121,6 +121,10 @@ For example if a cipher suite uses 256 bit ciphers but only a 128 bit ticket key
the overall security is only 128 bits because breaking the ticket key will
enable an attacker to obtain the session keys.
=head1 RETURN VALUES
returns 0 to indicate the callback function was set.
=head1 EXAMPLES
Reference Implementation:
@@ -175,10 +179,6 @@ Reference Implementation:
}
}
=head1 RETURN VALUES
returns 0 to indicate the callback function was set.
=head1 SEE ALSO
L<ssl(7)>, L<SSL_set_session(3)>,
doc/man3/SSL_CTX_set_tmp_dh_callback.pod
+8 -8
View File
@@ -81,6 +81,14 @@ are advised to either use SSL_CTX_set_tmp_dh() or alternatively, use
the callback but ignore B<keylength> and B<is_export> and simply
supply at least 2048-bit parameters in the callback.
=head1 RETURN VALUES
SSL_CTX_set_tmp_dh_callback() and SSL_set_tmp_dh_callback() do not return
diagnostic output.
SSL_CTX_set_tmp_dh() and SSL_set_tmp_dh() do return 1 on success and 0
on failure. Check the error queue to find out the reason of failure.
=head1 EXAMPLES
Setup DH parameters with a key length of 2048 bits. (Error handling
@@ -109,14 +117,6 @@ Code for setting up parameters during server initialization:
/* Error. */
...
=head1 RETURN VALUES
SSL_CTX_set_tmp_dh_callback() and SSL_set_tmp_dh_callback() do not return
diagnostic output.
SSL_CTX_set_tmp_dh() and SSL_set_tmp_dh() do return 1 on success and 0
on failure. Check the error queue to find out the reason of failure.
=head1 SEE ALSO
L<ssl(7)>, L<SSL_CTX_set_cipher_list(3)>,
doc/man3/SSL_SESSION_free.pod
+1 -1
View File
@@ -12,7 +12,7 @@ SSL_SESSION_free - create, free and manage SSL_SESSION structures
#include <openssl/ssl.h>
SSL_SESSION *SSL_SESSION_new(void);
SSL_SESSION *SSL_SESSION_dup(SSL_SESSION *src);
SSL_SESSION *SSL_SESSION_dup(const SSL_SESSION *src);
int SSL_SESSION_up_ref(SSL_SESSION *ses);
void SSL_SESSION_free(SSL_SESSION *session);
doc/man3/SSL_get_error.pod
+8 -5
View File
@@ -138,17 +138,20 @@ Details depend on the application.
=item SSL_ERROR_SYSCALL
Some non-recoverable I/O error occurred.
The OpenSSL error queue may contain more information on the error.
For socket I/O on Unix systems, consult B<errno> for details.
Some non-recoverable, fatal I/O error occurred. The OpenSSL error queue may
contain more information on the error. For socket I/O on Unix systems, consult
B<errno> for details. If this error occurs then no further I/O operations should
be performed on the connection and SSL_shutdown() must not be called.
This value can also be returned for other errors, check the error queue for
details.
=item SSL_ERROR_SSL
A failure in the SSL library occurred, usually a protocol error. The
OpenSSL error queue contains more information on the error.
A non-recoverable, fatal error in the SSL library occurred, usually a protocol
error. The OpenSSL error queue contains more information on the error. If this
error occurs then no further I/O operations should be performed on the
connection and SSL_shutdown() must not be called.
=back
doc/man3/SSL_load_client_CA_file.pod
+15 -15
View File
@@ -23,21 +23,6 @@ the specific usage as support function for
L<SSL_CTX_set_client_CA_list(3)>,
it is not limited to CA certificates.
=head1 EXAMPLES
Load names of CAs from file and use it as a client CA list:
SSL_CTX *ctx;
STACK_OF(X509_NAME) *cert_names;
...
cert_names = SSL_load_client_CA_file("/path/to/CAfile.pem");
if (cert_names != NULL)
SSL_CTX_set_client_CA_list(ctx, cert_names);
else
/* error */
...
=head1 RETURN VALUES
The following return values can occur:
@@ -54,6 +39,21 @@ Pointer to the subject names of the successfully read certificates.
=back
=head1 EXAMPLES
Load names of CAs from file and use it as a client CA list:
SSL_CTX *ctx;
STACK_OF(X509_NAME) *cert_names;
...
cert_names = SSL_load_client_CA_file("/path/to/CAfile.pem");
if (cert_names != NULL)
SSL_CTX_set_client_CA_list(ctx, cert_names);
else
/* error */
...
=head1 SEE ALSO
L<ssl(7)>,
doc/man3/SSL_new.pod
+2 -1
View File
@@ -26,7 +26,8 @@ structure are freed.
SSL_up_ref() increments the reference count for an
existing B<SSL> structure.
SSL_dup() duplicates an existing B<SSL> structure into a new allocated one. All
SSL_dup() duplicates an existing B<SSL> structure into a new allocated one
or just increments the reference count if the connection is active. All
settings are inherited from the original B<SSL> structure. Dynamic data (i.e.
existing connection details) are not copied, the new B<SSL> is set into an
initial accept (server) or connect (client) state.
doc/man3/SSL_shutdown.pod
+4
View File
@@ -22,6 +22,10 @@ Whether the operation succeeds or not, the SSL_SENT_SHUTDOWN flag is set and
a currently open session is considered closed and good and will be kept in the
session cache for further reuse.
Note that SSL_shutdown() must not be called if a previous fatal error has
occurred on a connection i.e. if SSL_get_error() has returned SSL_ERROR_SYSCALL
or SSL_ERROR_SSL.
The shutdown procedure consists of two steps: sending of the close_notify
shutdown alert, and reception of the peer's close_notify shutdown alert.
The order of those two steps depends on the application.
doc/man3/X509_NAME_add_entry_by_txt.pod
+9 -9
View File
@@ -74,6 +74,15 @@ structure respectively. This will then be a multivalued RDN:
since multivalues RDNs are very seldom used B<set> is almost
always set to zero.
=head1 RETURN VALUES
X509_NAME_add_entry_by_txt(), X509_NAME_add_entry_by_OBJ(),
X509_NAME_add_entry_by_NID() and X509_NAME_add_entry() return 1 for
success of 0 if an error occurred.
X509_NAME_delete_entry() returns either the deleted B<X509_NAME_ENTRY>
structure of B<NULL> if an error occurred.
=head1 EXAMPLES
Create an B<X509_NAME> structure:
@@ -95,15 +104,6 @@ Create an B<X509_NAME> structure:
"Joe Bloggs", -1, -1, 0))
/* Error */
=head1 RETURN VALUES
X509_NAME_add_entry_by_txt(), X509_NAME_add_entry_by_OBJ(),
X509_NAME_add_entry_by_NID() and X509_NAME_add_entry() return 1 for
success of 0 if an error occurred.
X509_NAME_delete_entry() returns either the deleted B<X509_NAME_ENTRY>
structure of B<NULL> if an error occurred.
=head1 BUGS
B<type> can still be set to B<V_ASN1_APP_CHOOSE> to use a
doc/man3/X509_NAME_get_index_by_NID.pod
+12 -12
View File
@@ -69,6 +69,18 @@ Applications which could pass invalid NIDs to X509_NAME_get_index_by_NID()
should check for the return value of -2. Alternatively the NID validity
can be determined first by checking OBJ_nid2obj(nid) is not NULL.
=head1 RETURN VALUES
X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ()
return the index of the next matching entry or -1 if not found.
X509_NAME_get_index_by_NID() can also return -2 if the supplied
NID is invalid.
X509_NAME_entry_count() returns the total number of entries.
X509_NAME_get_entry() returns an B<X509_NAME> pointer to the
requested entry or B<NULL> if the index is invalid.
=head1 EXAMPLES
Process all entries:
@@ -94,18 +106,6 @@ Process all commonName entries:
/* Do something with e */
}
=head1 RETURN VALUES
X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ()
return the index of the next matching entry or -1 if not found.
X509_NAME_get_index_by_NID() can also return -2 if the supplied
NID is invalid.
X509_NAME_entry_count() returns the total number of entries.
X509_NAME_get_entry() returns an B<X509_NAME> pointer to the
requested entry or B<NULL> if the index is invalid.
=head1 SEE ALSO
L<ERR_get_error(3)>, L<d2i_X509_NAME(3)>
doc/man3/X509_PUBKEY_new.pod
+3 -3
View File
@@ -19,13 +19,13 @@ X509_PUBKEY_get0_param - SubjectPublicKeyInfo public key functions
EVP_PKEY *X509_PUBKEY_get(X509_PUBKEY *key);
EVP_PKEY *d2i_PUBKEY(EVP_PKEY **a, const unsigned char **pp, long length);
int i2d_PUBKEY(EVP_PKEY *a, unsigned char **pp);
int i2d_PUBKEY(const EVP_PKEY *a, unsigned char **pp);
EVP_PKEY *d2i_PUBKEY_bio(BIO *bp, EVP_PKEY **a);
EVP_PKEY *d2i_PUBKEY_fp(FILE *fp, EVP_PKEY **a);
int i2d_PUBKEY_fp(FILE *fp, EVP_PKEY *pkey);
int i2d_PUBKEY_bio(BIO *bp, EVP_PKEY *pkey);
int i2d_PUBKEY_fp(const FILE *fp, EVP_PKEY *pkey);
int i2d_PUBKEY_bio(BIO *bp, const EVP_PKEY *pkey);
int X509_PUBKEY_set0_param(X509_PUBKEY *pub, ASN1_OBJECT *aobj,
int ptype, void *pval,
doc/man3/X509_dup.pod
+2 -2
View File
@@ -259,7 +259,7 @@ X509_dup,
extern const ASN1_ITEM TYPE_it;
TYPE *TYPE_new(void);
TYPE *TYPE_dup(TYPE *a);
TYPE *TYPE_dup(const TYPE *a);
void TYPE_free(TYPE *a);
int TYPE_print_ctx(BIO *out, TYPE *a, int indent, const ASN1_PCTX *pctx);
@@ -285,7 +285,7 @@ to generate the function bodies.
TYPE_new() allocates an empty object of the indicated type.
The object returned must be released by calling TYPE_free().
TYPE_dup() copies an existing object.
TYPE_dup() copies an existing object, leaving it untouched.
TYPE_free() releases the object and all pointers and sub-objects
within it.
doc/man3/d2i_PKCS8PrivateKey_bio.pod
+4 -4
View File
@@ -13,19 +13,19 @@ i2d_PKCS8PrivateKey_nid_bio, i2d_PKCS8PrivateKey_nid_fp - PKCS#8 format private
EVP_PKEY *d2i_PKCS8PrivateKey_bio(BIO *bp, EVP_PKEY **x, pem_password_cb *cb, void *u);
EVP_PKEY *d2i_PKCS8PrivateKey_fp(FILE *fp, EVP_PKEY **x, pem_password_cb *cb, void *u);
int i2d_PKCS8PrivateKey_bio(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,
int i2d_PKCS8PrivateKey_bio(BIO *bp, const EVP_PKEY *x, const EVP_CIPHER *enc,
char *kstr, int klen,
pem_password_cb *cb, void *u);
int i2d_PKCS8PrivateKey_fp(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
int i2d_PKCS8PrivateKey_fp(FILE *fp, const EVP_PKEY *x, const EVP_CIPHER *enc,
char *kstr, int klen,
pem_password_cb *cb, void *u);
int i2d_PKCS8PrivateKey_nid_bio(BIO *bp, EVP_PKEY *x, int nid,
int i2d_PKCS8PrivateKey_nid_bio(BIO *bp, const EVP_PKEY *x, int nid,
char *kstr, int klen,
pem_password_cb *cb, void *u);
int i2d_PKCS8PrivateKey_nid_fp(FILE *fp, EVP_PKEY *x, int nid,
int i2d_PKCS8PrivateKey_nid_fp(FILE *fp, const EVP_PKEY *x, int nid,
char *kstr, int klen,
pem_password_cb *cb, void *u);
doc/man3/d2i_PrivateKey.pod
+2 -2
View File
@@ -17,8 +17,8 @@ d2i_PrivateKey_bio, d2i_PrivateKey_fp
long length);
EVP_PKEY *d2i_AutoPrivateKey(EVP_PKEY **a, const unsigned char **pp,
long length);
int i2d_PrivateKey(EVP_PKEY *a, unsigned char **pp);
int i2d_PublicKey(EVP_PKEY *a, unsigned char **pp);
int i2d_PrivateKey(const EVP_PKEY *a, unsigned char **pp);
int i2d_PublicKey(const EVP_PKEY *a, unsigned char **pp);
EVP_PKEY *d2i_PrivateKey_bio(BIO *bp, EVP_PKEY **a);
EVP_PKEY *d2i_PrivateKey_fp(FILE *fp, EVP_PKEY **a)
doc/man3/d2i_X509.pod
+16 -13
View File
@@ -368,8 +368,11 @@ i2d_X509_VAL,
TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a);
TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a);
int i2d_TYPE(const TYPE *a, unsigned char **ppout);
int i2d_TYPE(TYPE *a, unsigned char **ppout);
int i2d_TYPE_fp(FILE *fp, const TYPE *a);
int i2d_TYPE_fp(FILE *fp, TYPE *a);
int i2d_TYPE_bio(BIO *bp, const TYPE *a);
int i2d_TYPE_bio(BIO *bp, TYPE *a);
=head1 DESCRIPTION
@@ -496,6 +499,19 @@ Represents the B<DigestInfo> structure defined in PKCS#1 and PKCS#7.
=back
=head1 RETURN VALUES
d2i_TYPE(), d2i_TYPE_bio() and d2i_TYPE_fp() return a valid B<TYPE> structure
or B<NULL> if an error occurs. If the "reuse" capability has been used with
a valid structure being passed in via B<a>, then the object is not freed in
the event of error but may be in a potentially invalid or inconsistent state.
i2d_TYPE() returns the number of bytes successfully encoded or a negative
value if an error occurs.
i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error
occurs.
=head1 EXAMPLES
Allocate and encode the DER encoding of an X509 structure:
@@ -586,19 +602,6 @@ structure has been modified after deserialization or previous
serialization. This is because some objects cache the encoding for
efficiency reasons.
=head1 RETURN VALUES
d2i_TYPE(), d2i_TYPE_bio() and d2i_TYPE_fp() return a valid B<TYPE> structure
or B<NULL> if an error occurs. If the "reuse" capability has been used with
a valid structure being passed in via B<a>, then the object is not freed in
the event of error but may be in a potentially invalid or inconsistent state.
i2d_TYPE() returns the number of bytes successfully encoded or a negative
value if an error occurs.
i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error
occurs.
=head1 COPYRIGHT
Copyright 1998-2018 The OpenSSL Project Authors. All Rights Reserved.