diff options
| author | Shigeki Ohtsu <ohtsu@ohtsu.org> | 2018-03-29 16:39:12 +0900 |
|---|---|---|
| committer | Shigeki Ohtsu <ohtsu@ohtsu.org> | 2018-04-10 06:45:42 +0900 |
| commit | 66cb29e64621fdd1aa5e377a395ff107d21a613b (patch) | |
| tree | f05243a51577e04b6f1c4a2f8a6b7b2f05786079 /deps/openssl/openssl/doc/crypto | |
| parent | 38c97f5dc7ff3fbf83982d0268fc9e93cfc00c7d (diff) | |
| download | android-node-v8-66cb29e64621fdd1aa5e377a395ff107d21a613b.tar.gz android-node-v8-66cb29e64621fdd1aa5e377a395ff107d21a613b.tar.bz2 android-node-v8-66cb29e64621fdd1aa5e377a395ff107d21a613b.zip | |
deps: upgrade openssl sources to 1.1.0h
This updates all sources in deps/openssl/openssl with openssl-1.1.0h.
Fixes: https://github.com/nodejs/node/issues/4270
PR-URL: https://github.com/nodejs/node/pull/19794
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Rod Vagg <rod@vagg.org>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Diffstat (limited to 'deps/openssl/openssl/doc/crypto')
310 files changed, 16229 insertions, 7063 deletions
diff --git a/deps/openssl/openssl/doc/crypto/ASN1_INTEGER_get_int64.pod b/deps/openssl/openssl/doc/crypto/ASN1_INTEGER_get_int64.pod new file mode 100644 index 0000000000..f61268d6ac --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/ASN1_INTEGER_get_int64.pod @@ -0,0 +1,133 @@ +=pod + +=head1 NAME + +ASN1_INTEGER_get_uint64, ASN1_INTEGER_set_uint64, +ASN1_INTEGER_get_int64, ASN1_INTEGER_get, ASN1_INTEGER_set_int64, ASN1_INTEGER_set, BN_to_ASN1_INTEGER, ASN1_INTEGER_to_BN, ASN1_ENUMERATED_get_int64, ASN1_ENUMERATED_get, ASN1_ENUMERATED_set_int64, ASN1_ENUMERATED_set, BN_to_ASN1_ENUMERATED, ASN1_ENUMERATED_to_BN +- ASN.1 INTEGER and ENUMERATED utilities + +=head1 SYNOPSIS + + #include <openssl/asn1.h> + + int ASN1_INTEGER_get_int64(int64_t *pr, const ASN1_INTEGER *a); + int ASN1_INTEGER_get(const ASN1_INTEGER *a, long v); + + int ASN1_INTEGER_set_int64(ASN1_INTEGER *a, int64_t r); + long ASN1_INTEGER_set(const ASN1_INTEGER *a); + + int ASN1_INTEGER_get_uint64(uint64_t *pr, const ASN1_INTEGER *a); + int ASN1_INTEGER_set_uint64(ASN1_INTEGER *a, uint64_t r); + + ASN1_INTEGER *BN_to_ASN1_INTEGER(const BIGNUM *bn, ASN1_INTEGER *ai); + BIGNUM *ASN1_INTEGER_to_BN(const ASN1_INTEGER *ai, BIGNUM *bn); + + int ASN1_ENUMERATED_get_int64(int64_t *pr, const ASN1_INTEGER *a); + long ASN1_ENUMERATED_get(const ASN1_ENUMERATED *a); + + int ASN1_ENUMERATED_set_int64(ASN1_INTEGER *a, int64_t r); + int ASN1_ENUMERATED_set(ASN1_ENUMERATED *a, long v); + + ASN1_ENUMERATED *BN_to_ASN1_ENUMERATED(BIGNUM *bn, ASN1_ENUMERATED *ai); + BIGNUM *ASN1_ENUMERATED_to_BN(ASN1_ENUMERATED *ai, BIGNUM *bn); + +=head1 DESCRIPTION + +These functions convert to and from B<ASN1_INTEGER> and B<ASN1_ENUMERATED> +structures. + +ASN1_INTEGER_get_int64() converts an B<ASN1_INTEGER> into an B<int64_t> type +If successful it returns 1 and sets B<*pr> to the value of B<a>. If it fails +(due to invalid type or the value being too big to fit into an B<int64_t> type) +it returns 0. + +ASN1_INTEGER_get_uint64() is similar to ASN1_INTEGER_get_int64_t() except it +converts to a B<uint64_t> type and an error is returned if the passed integer +is negative. + +ASN1_INTEGER_get() also returns the value of B<a> but it returns 0 if B<a> is +NULL and -1 on error (which is ambiguous because -1 is a legitimate value for +an B<ASN1_INTEGER>). New applications should use ASN1_INTEGER_get_int64() +instead. + +ASN1_INTEGER_set_int64() sets the value of B<ASN1_INTEGER> B<a> to the +B<int64_t> value B<r>. + +ASN1_INTEGER_set_uint64() sets the value of B<ASN1_INTEGER> B<a> to the +B<uint64_t> value B<r>. + +ASN1_INTEGER_set() sets the value of B<ASN1_INTEGER> B<a> to the B<long> value +B<v>. + +BN_to_ASN1_INTEGER() converts B<BIGNUM> B<bn> to an B<ASN1_INTEGER>. If B<ai> +is NULL a new B<ASN1_INTEGER> structure is returned. If B<ai> is not NULL then +the existing structure will be used instead. + +ASN1_INTEGER_to_BN() converts ASN1_INTEGER B<ai> into a B<BIGNUM>. If B<bn> is +NULL a new B<BIGNUM> structure is returned. If B<bn> is not NULL then the +existing structure will be used instead. + +ASN1_ENUMERATED_get_int64(), ASN1_ENUMERATED_set_int64(), +ASN1_ENUMERATED_set(), BN_to_ASN1_ENUMERATED() and ASN1_ENUMERATED_to_BN() +behave in an identical way to their ASN1_INTEGER counterparts except they +operate on an B<ASN1_ENUMERATED> value. + +ASN1_ENUMERATED_get() returns the value of B<a> in a similar way to +ASN1_INTEGER_get() but it returns B<0xffffffffL> if the value of B<a> will not +fit in a long type. New applications should use ASN1_ENUMERATED_get_int64() +instead. + +=head1 NOTES + +In general an B<ASN1_INTEGER> or B<ASN1_ENUMERATED> type can contain an +integer of almost arbitrary size and so cannot always be represented by a C +B<int64_t> type. However in many cases (for example version numbers) they +represent small integers which can be more easily manipulated if converted to +an appropriate C integer type. + +=head1 BUGS + +The ambiguous return values of ASN1_INTEGER_get() and ASN1_ENUMERATED_get() +mean these functions should be avoided if possible. They are retained for +compatibility. Normally the ambiguous return values are not legitimate +values for the fields they represent. + +=head1 RETURN VALUES + +ASN1_INTEGER_set_int64(), ASN1_INTEGER_set(), ASN1_ENUMERATED_set_int64() and +ASN1_ENUMERATED_set() return 1 for success and 0 for failure. They will only +fail if a memory allocation error occurs. + +ASN1_INTEGER_get_int64() and ASN1_ENUMERATED_get_int64() return 1 for success +and 0 for failure. They will fail if the passed type is incorrect (this will +only happen if there is a programming error) or if the value exceeds the range +of an B<int64_t> type. + +BN_to_ASN1_INTEGER() and BN_to_ASN1_ENUMERATED() return an B<ASN1_INTEGER> or +B<ASN1_ENUMERATED> structure respectively or NULL if an error occurs. They will +only fail due to a memory allocation error. + +ASN1_INTEGER_to_BN() and ASN1_ENUMERATED_to_BN() return a B<BIGNUM> structure +of NULL if an error occurs. They can fail if the passed type is incorrect +(due to programming error) or due to a memory allocation failure. + +=head1 SEE ALSO + +L<ERR_get_error(3)> + +=head1 HISTORY + +ASN1_INTEGER_set_int64(), ASN1_INTEGER_get_int64(), +ASN1_ENUMERATED_set_int64() and ASN1_ENUMERATED_get_int64() +were added to OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/ASN1_OBJECT_new.pod b/deps/openssl/openssl/doc/crypto/ASN1_OBJECT_new.pod index 9bae40fccf..4c018efffd 100644 --- a/deps/openssl/openssl/doc/crypto/ASN1_OBJECT_new.pod +++ b/deps/openssl/openssl/doc/crypto/ASN1_OBJECT_new.pod @@ -2,7 +2,7 @@ =head1 NAME -ASN1_OBJECT_new, ASN1_OBJECT_free, - object allocation functions +ASN1_OBJECT_new, ASN1_OBJECT_free - object allocation functions =head1 SYNOPSIS @@ -16,9 +16,10 @@ ASN1_OBJECT_new, ASN1_OBJECT_free, - object allocation functions The ASN1_OBJECT allocation routines, allocate and free an ASN1_OBJECT structure, which represents an ASN1 OBJECT IDENTIFIER. -ASN1_OBJECT_new() allocates and initializes a ASN1_OBJECT structure. +ASN1_OBJECT_new() allocates and initializes an ASN1_OBJECT structure. ASN1_OBJECT_free() frees up the B<ASN1_OBJECT> structure B<a>. +If B<a> is NULL, nothing is done. =head1 NOTES @@ -29,17 +30,22 @@ such as OBJ_nid2obj() are used instead. =head1 RETURN VALUES If the allocation fails, ASN1_OBJECT_new() returns B<NULL> and sets an error -code that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. +code that can be obtained by L<ERR_get_error(3)>. Otherwise it returns a pointer to the newly allocated structure. ASN1_OBJECT_free() returns no value. =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_ASN1_OBJECT(3)|d2i_ASN1_OBJECT(3)> +L<ERR_get_error(3)>, L<d2i_ASN1_OBJECT(3)> -=head1 HISTORY +=head1 COPYRIGHT -ASN1_OBJECT_new() and ASN1_OBJECT_free() are available in all versions of SSLeay and OpenSSL. +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/ASN1_STRING_length.pod b/deps/openssl/openssl/doc/crypto/ASN1_STRING_length.pod index 4ea6e8c226..20a372dc12 100644 --- a/deps/openssl/openssl/doc/crypto/ASN1_STRING_length.pod +++ b/deps/openssl/openssl/doc/crypto/ASN1_STRING_length.pod @@ -3,14 +3,15 @@ =head1 NAME ASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length, -ASN1_STRING_length_set, ASN1_STRING_type, ASN1_STRING_data, ASN1_STRING_to_UTF8 - -ASN1_STRING utility functions +ASN1_STRING_type, ASN1_STRING_get0_data, ASN1_STRING_data, +ASN1_STRING_to_UTF8 - ASN1_STRING utility functions =head1 SYNOPSIS #include <openssl/asn1.h> int ASN1_STRING_length(ASN1_STRING *x); + 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); @@ -19,9 +20,9 @@ ASN1_STRING utility functions int ASN1_STRING_set(ASN1_STRING *str, const void *data, int len); - int ASN1_STRING_type(ASN1_STRING *x); + int ASN1_STRING_type(const ASN1_STRING *x); - int ASN1_STRING_to_UTF8(unsigned char **out, ASN1_STRING *in); + int ASN1_STRING_to_UTF8(unsigned char **out, const ASN1_STRING *in); =head1 DESCRIPTION @@ -29,10 +30,14 @@ These functions allow an B<ASN1_STRING> structure to be manipulated. ASN1_STRING_length() returns the length of the content of B<x>. -ASN1_STRING_data() returns an internal pointer to the data of B<x>. +ASN1_STRING_get0_data() returns an internal pointer to the data of B<x>. Since this is an internal pointer it should B<not> be freed or modified in any way. +ASN1_STRING_data() is similar to ASN1_STRING_get0_data() except the +returned value is not constant. This function is deprecated: +applications should use ASN1_STRING_get0_data() instead. + ASN1_STRING_dup() returns a copy of the structure B<a>. ASN1_STRING_cmp() compares B<a> and B<b> returning 0 if the two @@ -48,12 +53,12 @@ such as B<V_ASN1_OCTET_STRING>. ASN1_STRING_to_UTF8() converts the string B<in> to UTF8 format, the converted data is allocated in a buffer in B<*out>. The length of B<out> is returned or a negative error code. The buffer B<*out> -should be free using OPENSSL_free(). +should be freed using OPENSSL_free(). =head1 NOTES Almost all ASN1 types in OpenSSL are represented as an B<ASN1_STRING> -structure. Other types such as B<ASN1_OCTET_STRING> are simply typedefed +structure. Other types such as B<ASN1_OCTET_STRING> are simply typedef'ed to B<ASN1_STRING> and the functions call the B<ASN1_STRING> equivalents. B<ASN1_STRING> is also used for some B<CHOICE> types which consist entirely of primitive string types such as B<DirectoryString> and @@ -72,12 +77,17 @@ character in big endian format, and for an UTF8String it will be in UTF8 format. Similar care should be take to ensure the data is in the correct format when calling ASN1_STRING_set(). -=head1 RETURN VALUES - =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)> +L<ERR_get_error(3)> + +=head1 COPYRIGHT + +Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved. -=head1 HISTORY +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/ASN1_STRING_new.pod b/deps/openssl/openssl/doc/crypto/ASN1_STRING_new.pod index 8ac2a03ae2..7bd2fc1921 100644 --- a/deps/openssl/openssl/doc/crypto/ASN1_STRING_new.pod +++ b/deps/openssl/openssl/doc/crypto/ASN1_STRING_new.pod @@ -22,6 +22,7 @@ ASN1_STRING_type_new() returns an allocated B<ASN1_STRING> structure of type B<type>. ASN1_STRING_free() frees up B<a>. +If B<a> is NULL nothing is done. =head1 NOTES @@ -37,10 +38,15 @@ ASN1_STRING_free() does not return a value. =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)> +L<ERR_get_error(3)> -=head1 HISTORY +=head1 COPYRIGHT -TBA +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/ASN1_STRING_print_ex.pod b/deps/openssl/openssl/doc/crypto/ASN1_STRING_print_ex.pod index 19c82ff1e4..a521f78ea9 100644 --- a/deps/openssl/openssl/doc/crypto/ASN1_STRING_print_ex.pod +++ b/deps/openssl/openssl/doc/crypto/ASN1_STRING_print_ex.pod @@ -2,16 +2,18 @@ =head1 NAME -ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp, ASN1_STRING_print - ASN1_STRING output routines. +ASN1_tag2str, ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp, ASN1_STRING_print +- ASN1_STRING output routines =head1 SYNOPSIS #include <openssl/asn1.h> - int ASN1_STRING_print_ex(BIO *out, ASN1_STRING *str, unsigned long flags); - int ASN1_STRING_print_ex_fp(FILE *fp, ASN1_STRING *str, unsigned long flags); - int ASN1_STRING_print(BIO *out, ASN1_STRING *str); + int ASN1_STRING_print_ex(BIO *out, const ASN1_STRING *str, unsigned long flags); + int ASN1_STRING_print_ex_fp(FILE *fp, const ASN1_STRING *str, unsigned long flags); + int ASN1_STRING_print(BIO *out, const ASN1_STRING *str); + const char *ASN1_tag2str(int tag); =head1 DESCRIPTION @@ -26,11 +28,13 @@ ASN1_STRING_print() prints B<str> to B<out> but using a different format to ASN1_STRING_print_ex(). It replaces unprintable characters (other than CR, LF) with '.'. +ASN1_tag2str() returns a human-readable name of the specified ASN.1 B<tag>. + =head1 NOTES ASN1_STRING_print() is a legacy function which should be avoided in new applications. -Although there are a large number of options frequently B<ASN1_STRFLGS_RFC2253> is +Although there are a large number of options frequently B<ASN1_STRFLGS_RFC2253> is suitable, or on UTF8 terminals B<ASN1_STRFLGS_RFC2253 & ~ASN1_STRFLGS_ESC_MSB>. The complete set of supported options for B<flags> is listed below. @@ -75,7 +79,7 @@ Normally non character string types (such as OCTET STRING) are assumed to be one byte per character, if B<ASN1_STRFLGS_DUMP_UNKNOWN> is set then they will be dumped instead. -When a type is dumped normally just the content octets are printed, if +When a type is dumped normally just the content octets are printed, if B<ASN1_STRFLGS_DUMP_DER> is set then the complete encoding is dumped instead (including tag and length octets). @@ -86,11 +90,16 @@ equivalent to: =head1 SEE ALSO -L<X509_NAME_print_ex(3)|X509_NAME_print_ex(3)>, -L<ASN1_tag2str(3)|ASN1_tag2str(3)> +L<X509_NAME_print_ex(3)>, +L<ASN1_tag2str(3)> + +=head1 COPYRIGHT -=head1 HISTORY +Copyright 2002-2017 The OpenSSL Project Authors. All Rights Reserved. -TBA +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/ASN1_TIME_set.pod b/deps/openssl/openssl/doc/crypto/ASN1_TIME_set.pod index ae2b53d355..457b7218d4 100644 --- a/deps/openssl/openssl/doc/crypto/ASN1_TIME_set.pod +++ b/deps/openssl/openssl/doc/crypto/ASN1_TIME_set.pod @@ -3,7 +3,7 @@ =head1 NAME ASN1_TIME_set, ASN1_TIME_adj, ASN1_TIME_check, ASN1_TIME_set_string, -ASN1_TIME_print, ASN1_TIME_diff - ASN.1 Time functions. +ASN1_TIME_print, ASN1_TIME_diff - ASN.1 Time functions =head1 SYNOPSIS @@ -100,7 +100,7 @@ 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 */ + /* Invalid time format */ if (day > 0 || sec > 0) printf("Later\n"); @@ -123,7 +123,16 @@ otherwise. ASN1_TIME_print() returns 1 if the time is successfully printed out and 0 if an error occurred (I/O error or invalid time format). -ASN1_TIME_diff() returns 1 for sucess and 0 for failure. It can fail if the +ASN1_TIME_diff() returns 1 for success and 0 for failure. It can fail if the pass ASN1_TIME structure has invalid syntax for example. +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/ASN1_TYPE_get.pod b/deps/openssl/openssl/doc/crypto/ASN1_TYPE_get.pod new file mode 100644 index 0000000000..70c56878b8 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/ASN1_TYPE_get.pod @@ -0,0 +1,100 @@ +=pod + +=head1 NAME + +ASN1_TYPE_get, ASN1_TYPE_set, ASN1_TYPE_set1, ASN1_TYPE_cmp, ASN1_TYPE_unpack_sequence, ASN1_TYPE_pack_sequence - ASN1_TYPE utility +functions + +=head1 SYNOPSIS + + #include <openssl/asn1.h> + + int ASN1_TYPE_get(const ASN1_TYPE *a); + void ASN1_TYPE_set(ASN1_TYPE *a, int type, void *value); + int ASN1_TYPE_set1(ASN1_TYPE *a, int type, const void *value); + int ASN1_TYPE_cmp(const ASN1_TYPE *a, const ASN1_TYPE *b); + + void *ASN1_TYPE_unpack_sequence(const ASN1_ITEM *it, const ASN1_TYPE *t); + ASN1_TYPE *ASN1_TYPE_pack_sequence(const ASN1_ITEM *it, void *s, + ASN1_TYPE **t); + +=head1 DESCRIPTION + +These functions allow an ASN1_TYPE structure to be manipulated. The +ASN1_TYPE structure can contain any ASN.1 type or constructed type +such as a SEQUENCE: it is effectively equivalent to the ASN.1 ANY type. + +ASN1_TYPE_get() returns the type of B<a>. + +ASN1_TYPE_set() sets the value of B<a> to B<type> and B<value>. This +function uses the pointer B<value> internally so it must B<not> be freed +up after the call. + +ASN1_TYPE_set1() sets the value of B<a> to B<type> a copy of B<value>. + +ASN1_TYPE_cmp() compares ASN.1 types B<a> and B<b> and returns 0 if +they are identical and non-zero otherwise. + +ASN1_TYPE_unpack_sequence() attempts to parse the SEQUENCE present in +B<t> using the ASN.1 structure B<it>. If successful it returns a pointer +to the ASN.1 structure corresponding to B<it> which must be freed by the +caller. If it fails it return NULL. + +ASN1_TYPE_pack_sequence() attempts to encode the ASN.1 structure B<s> +corresponding to B<it> into an ASN1_TYPE. If successful the encoded +ASN1_TYPE is returned. If B<t> and B<*t> are not NULL the encoded type +is written to B<t> overwriting any existing data. If B<t> is not NULL +but B<*t> is NULL the returned ASN1_TYPE is written to B<*t>. + +=head1 NOTES + +The type and meaning of the B<value> parameter for ASN1_TYPE_set() and +ASN1_TYPE_set1() is determined by the B<type> parameter. +If B<type> is V_ASN1_NULL B<value> is ignored. If B<type> is V_ASN1_BOOLEAN +then the boolean is set to TRUE if B<value> is not NULL. If B<type> is +V_ASN1_OBJECT then value is an ASN1_OBJECT structure. Otherwise B<type> +is and ASN1_STRING structure. If B<type> corresponds to a primitive type +(or a string type) then the contents of the ASN1_STRING contain the content +octets of the type. If B<type> corresponds to a constructed type or +a tagged type (V_ASN1_SEQUENCE, V_ASN1_SET or V_ASN1_OTHER) then the +ASN1_STRING contains the entire ASN.1 encoding verbatim (including tag and +length octets). + +ASN1_TYPE_cmp() may not return zero if two types are equivalent but have +different encodings. For example the single content octet of the boolean TRUE +value under BER can have any non-zero encoding but ASN1_TYPE_cmp() will +only return zero if the values are the same. + +If either or both of the parameters passed to ASN1_TYPE_cmp() is NULL the +return value is non-zero. Technically if both parameters are NULL the two +types could be absent OPTIONAL fields and so should match, however passing +NULL values could also indicate a programming error (for example an +unparseable type which returns NULL) for types which do B<not> match. So +applications should handle the case of two absent values separately. + +=head1 RETURN VALUES + +ASN1_TYPE_get() returns the type of the ASN1_TYPE argument. + +ASN1_TYPE_set() does not return a value. + +ASN1_TYPE_set1() returns 1 for success and 0 for failure. + +ASN1_TYPE_cmp() returns 0 if the types are identical and non-zero otherwise. + +ASN1_TYPE_unpack_sequence() returns a pointer to an ASN.1 structure or +NULL on failure. + +ASN1_TYPE_pack_sequence() return an ASN1_TYPE structure if it succeeds or +NULL on failure. + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/ASN1_generate_nconf.pod b/deps/openssl/openssl/doc/crypto/ASN1_generate_nconf.pod index bfa0a04ff9..bf29af62f7 100644 --- a/deps/openssl/openssl/doc/crypto/ASN1_generate_nconf.pod +++ b/deps/openssl/openssl/doc/crypto/ASN1_generate_nconf.pod @@ -8,8 +8,8 @@ ASN1_generate_nconf, ASN1_generate_v3 - ASN1 generation functions #include <openssl/asn1.h> - ASN1_TYPE *ASN1_generate_nconf(char *str, CONF *nconf); - ASN1_TYPE *ASN1_generate_v3(char *str, X509V3_CTX *cnf); + ASN1_TYPE *ASN1_generate_nconf(const char *str, CONF *nconf); + ASN1_TYPE *ASN1_generate_v3(const char *str, X509V3_CTX *cnf); =head1 DESCRIPTION @@ -19,7 +19,7 @@ in an B<ASN1_TYPE> structure. B<str> contains the string to encode B<nconf> or B<cnf> contains the optional configuration information where additional strings will be read from. B<nconf> will typically come from a config -file wherease B<cnf> is obtained from an B<X509V3_CTX> structure +file whereas B<cnf> is obtained from an B<X509V3_CTX> structure which will typically be used by X509 v3 certificate extension functions. B<cnf> or B<nconf> can be set to B<NULL> if no additional configuration will be used. @@ -30,7 +30,7 @@ The actual data encoded is determined by the string B<str> and the configuration information. The general format of the string is: -=over 2 +=over 4 =item B<[modifier,]type[:value]> @@ -40,19 +40,19 @@ That is zero or more comma separated modifiers followed by a type followed by an optional colon and a value. The formats of B<type>, B<value> and B<modifier> are explained below. -=head2 SUPPORTED TYPES +=head2 Supported Types The supported types are listed below. Unless otherwise specified only the B<ASCII> format is permissible. -=over 2 +=over 4 =item B<BOOLEAN>, B<BOOL> This encodes a boolean type. The B<value> string is mandatory and should be B<TRUE> or B<FALSE>. Additionally B<TRUE>, B<true>, B<Y>, B<y>, B<YES>, B<yes>, B<FALSE>, B<false>, B<N>, B<n>, B<NO> and B<no> -are acceptable. +are acceptable. =item B<NULL> @@ -78,12 +78,12 @@ a short name, a long name or numerical format. =item B<UTCTIME>, B<UTC> Encodes an ASN1 B<UTCTime> structure, the value should be in -the format B<YYMMDDHHMMSSZ>. +the format B<YYMMDDHHMMSSZ>. =item B<GENERALIZEDTIME>, B<GENTIME> Encodes an ASN1 B<GeneralizedTime> structure, the value should be in -the format B<YYYYMMDDHHMMSSZ>. +the format B<YYYYMMDDHHMMSSZ>. =item B<OCTETSTRING>, B<OCT> @@ -119,14 +119,14 @@ will be encoded. =back -=head2 MODIFIERS +=head2 Modifiers Modifiers affect the following structure, they can be used to add EXPLICIT or IMPLICIT tagging, add wrappers or to change the string format of the final type and value. The supported formats are documented below. -=over 2 +=over 4 =item B<EXPLICIT>, B<EXP> @@ -181,7 +181,7 @@ A BITSTRING with bits 1 and 5 set and all others zero: FORMAT:BITLIST,BITSTRING:1,5 A more complex example using a config file to produce a -SEQUENCE consiting of a BOOL an OID and a UTF8String: +SEQUENCE consisting of a BOOL an OID and a UTF8String: asn1 = SEQUENCE:seq_section @@ -252,14 +252,19 @@ structure: 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)|ERR_get_error(3)>. +The error codes that can be obtained by L<ERR_get_error(3)>. =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)> +L<ERR_get_error(3)> -=head1 HISTORY +=head1 COPYRIGHT -ASN1_generate_nconf() and ASN1_generate_v3() were added to OpenSSL 0.9.8 +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/ASYNC_WAIT_CTX_new.pod b/deps/openssl/openssl/doc/crypto/ASYNC_WAIT_CTX_new.pod new file mode 100644 index 0000000000..2fb00a3ba4 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/ASYNC_WAIT_CTX_new.pod @@ -0,0 +1,144 @@ +=pod + +=head1 NAME + +ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd, +ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds, +ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd - functions to manage +waiting for asynchronous jobs to complete + +=head1 SYNOPSIS + + #include <openssl/async.h> + + ASYNC_WAIT_CTX *ASYNC_WAIT_CTX_new(void); + void ASYNC_WAIT_CTX_free(ASYNC_WAIT_CTX *ctx); + int ASYNC_WAIT_CTX_set_wait_fd(ASYNC_WAIT_CTX *ctx, const void *key, + OSSL_ASYNC_FD fd, + void *custom_data, + void (*cleanup)(ASYNC_WAIT_CTX *, const void *, + OSSL_ASYNC_FD, void *)); + int ASYNC_WAIT_CTX_get_fd(ASYNC_WAIT_CTX *ctx, const void *key, + OSSL_ASYNC_FD *fd, void **custom_data); + int ASYNC_WAIT_CTX_get_all_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *fd, + size_t *numfds); + int ASYNC_WAIT_CTX_get_changed_fds(ASYNC_WAIT_CTX *ctx, OSSL_ASYNC_FD *addfd, + size_t *numaddfds, OSSL_ASYNC_FD *delfd, + size_t *numdelfds); + int ASYNC_WAIT_CTX_clear_fd(ASYNC_WAIT_CTX *ctx, const void *key); + + +=head1 DESCRIPTION + +For an overview of how asynchronous operations are implemented in OpenSSL see +L<ASYNC_start_job(3)>. An ASYNC_WAIT_CTX object represents an asynchronous +"session", i.e. a related set of crypto operations. For example in SSL terms +this would have a one-to-one correspondence with an SSL connection. + +Application code must create an ASYNC_WAIT_CTX using the ASYNC_WAIT_CTX_new() +function prior to calling ASYNC_start_job() (see L<ASYNC_start_job(3)>). When +the job is started it is associated with the ASYNC_WAIT_CTX for the duration of +that job. An ASYNC_WAIT_CTX should only be used for one ASYNC_JOB at any one +time, but can be reused after an ASYNC_JOB has finished for a subsequent +ASYNC_JOB. When the session is complete (e.g. the SSL connection is closed), +application code cleans up with ASYNC_WAIT_CTX_free(). + +ASYNC_WAIT_CTXs can have "wait" file descriptors associated with them. Calling +ASYNC_WAIT_CTX_get_all_fds() and passing in a pointer to an ASYNC_WAIT_CTX in +the B<ctx> parameter will return the wait file descriptors associated with that +job in B<*fd>. The number of file descriptors returned will be stored in +B<*numfds>. It is the caller's responsibility to ensure that sufficient memory +has been allocated in B<*fd> to receive all the file descriptors. Calling +ASYNC_WAIT_CTX_get_all_fds() with a NULL B<fd> value will return no file +descriptors but will still populate B<*numfds>. Therefore application code is +typically expected to call this function twice: once to get the number of fds, +and then again when sufficient memory has been allocated. If only one +asynchronous engine is being used then normally this call will only ever return +one fd. If multiple asynchronous engines are being used then more could be +returned. + +The function ASYNC_WAIT_CTX_get_changed_fds() can be used to detect if any fds +have changed since the last call time ASYNC_start_job() returned an ASYNC_PAUSE +result (or since the ASYNC_WAIT_CTX was created if no ASYNC_PAUSE result has +been received). The B<numaddfds> and B<numdelfds> parameters will be populated +with the number of fds added or deleted respectively. B<*addfd> and B<*delfd> +will be populated with the list of added and deleted fds respectively. Similarly +to ASYNC_WAIT_CTX_get_all_fds() either of these can be NULL, but if they are not +NULL then the caller is responsible for ensuring sufficient memory is allocated. + +Implementors of async aware code (e.g. engines) are encouraged to return a +stable fd for the lifetime of the ASYNC_WAIT_CTX in order to reduce the "churn" +of regularly changing fds - although no guarantees of this are provided to +applications. + +Applications can wait for the file descriptor to be ready for "read" using a +system function call such as select or poll (being ready for "read" indicates +that the job should be resumed). If no file descriptor is made available then an +application will have to periodically "poll" the job by attempting to restart it +to see if it is ready to continue. + +Async aware code (e.g. engines) can get the current ASYNC_WAIT_CTX from the job +via L<ASYNC_get_wait_ctx(3)> and provide a file descriptor to use for waiting +on by calling ASYNC_WAIT_CTX_set_wait_fd(). Typically this would be done by an +engine immediately prior to calling ASYNC_pause_job() and not by end user code. +An existing association with a file descriptor can be obtained using +ASYNC_WAIT_CTX_get_fd() and cleared using ASYNC_WAIT_CTX_clear_fd(). Both of +these functions requires a B<key> value which is unique to the async aware +code. This could be any unique value but a good candidate might be the +B<ENGINE *> for the engine. The B<custom_data> parameter can be any value, and +will be returned in a subsequent call to ASYNC_WAIT_CTX_get_fd(). The +ASYNC_WAIT_CTX_set_wait_fd() function also expects a pointer to a "cleanup" +routine. This can be NULL but if provided will automatically get called when +the ASYNC_WAIT_CTX is freed, and gives the engine the opportunity to close the +fd or any other resources. Note: The "cleanup" routine does not get called if +the fd is cleared directly via a call to ASYNC_WAIT_CTX_clear_fd(). + +An example of typical usage might be an async capable engine. User code would +initiate cryptographic operations. The engine would initiate those operations +asynchronously and then call ASYNC_WAIT_CTX_set_wait_fd() followed by +ASYNC_pause_job() to return control to the user code. The user code can then +perform other tasks or wait for the job to be ready by calling "select" or other +similar function on the wait file descriptor. The engine can signal to the user +code that the job should be resumed by making the wait file descriptor +"readable". Once resumed the engine should clear the wake signal on the wait +file descriptor. + +=head1 RETURN VALUES + +ASYNC_WAIT_CTX_new() returns a pointer to the newly allocated ASYNC_WAIT_CTX or +NULL on error. + +ASYNC_WAIT_CTX_set_wait_fd, ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds, +ASYNC_WAIT_CTX_get_changed_fds and ASYNC_WAIT_CTX_clear_fd all return 1 on +success or 0 on error. + +=head1 NOTES + +On Windows platforms the openssl/async.h header is dependent on some +of the types customarily made available by including windows.h. The +application developer is likely to require control over when the latter +is included, commonly as one of the first included headers. Therefore +it is defined as an application developer's responsibility to include +windows.h prior to async.h. + +=head1 SEE ALSO + +L<crypto(3)>, L<ASYNC_start_job(3)> + +=head1 HISTORY + +ASYNC_WAIT_CTX_new, ASYNC_WAIT_CTX_free, ASYNC_WAIT_CTX_set_wait_fd, +ASYNC_WAIT_CTX_get_fd, ASYNC_WAIT_CTX_get_all_fds, +ASYNC_WAIT_CTX_get_changed_fds, ASYNC_WAIT_CTX_clear_fd were first added to +OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/ASYNC_start_job.pod b/deps/openssl/openssl/doc/crypto/ASYNC_start_job.pod new file mode 100644 index 0000000000..c10a66f565 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/ASYNC_start_job.pod @@ -0,0 +1,330 @@ +=pod + +=head1 NAME + +ASYNC_get_wait_ctx, +ASYNC_init_thread, ASYNC_cleanup_thread, ASYNC_start_job, ASYNC_pause_job, +ASYNC_get_current_job, ASYNC_block_pause, ASYNC_unblock_pause, ASYNC_is_capable +- asynchronous job management functions + +=head1 SYNOPSIS + + #include <openssl/async.h> + + int ASYNC_init_thread(size_t max_size, size_t init_size); + void ASYNC_cleanup_thread(void); + + int ASYNC_start_job(ASYNC_JOB **job, ASYNC_WAIT_CTX *ctx, int *ret, + int (*func)(void *), void *args, size_t size); + int ASYNC_pause_job(void); + + ASYNC_JOB *ASYNC_get_current_job(void); + ASYNC_WAIT_CTX *ASYNC_get_wait_ctx(ASYNC_JOB *job); + void ASYNC_block_pause(void); + void ASYNC_unblock_pause(void); + + int ASYNC_is_capable(void); + +=head1 DESCRIPTION + +OpenSSL implements asynchronous capabilities through an ASYNC_JOB. This +represents code that can be started and executes until some event occurs. At +that point the code can be paused and control returns to user code until some +subsequent event indicates that the job can be resumed. + +The creation of an ASYNC_JOB is a relatively expensive operation. Therefore, for +efficiency reasons, jobs can be created up front and reused many times. They are +held in a pool until they are needed, at which point they are removed from the +pool, used, and then returned to the pool when the job completes. If the user +application is multi-threaded, then ASYNC_init_thread() may be called for each +thread that will initiate asynchronous jobs. Before +user code exits per-thread resources need to be cleaned up. This will normally +occur automatically (see L<OPENSSL_init_crypto(3)>) but may be explicitly +initiated by using ASYNC_cleanup_thread(). No asynchronous jobs must be +outstanding for the thread when ASYNC_cleanup_thread() is called. Failing to +ensure this will result in memory leaks. + +The B<max_size> argument limits the number of ASYNC_JOBs that will be held in +the pool. If B<max_size> is set to 0 then no upper limit is set. When an +ASYNC_JOB is needed but there are none available in the pool already then one +will be automatically created, as long as the total of ASYNC_JOBs managed by the +pool does not exceed B<max_size>. When the pool is first initialised +B<init_size> ASYNC_JOBs will be created immediately. If ASYNC_init_thread() is +not called before the pool is first used then it will be called automatically +with a B<max_size> of 0 (no upper limit) and an B<init_size> of 0 (no ASYNC_JOBs +created up front). + +An asynchronous job is started by calling the ASYNC_start_job() function. +Initially B<*job> should be NULL. B<ctx> should point to an ASYNC_WAIT_CTX +object created through the L<ASYNC_WAIT_CTX_new(3)> function. B<ret> should +point to a location where the return value of the asynchronous function should +be stored on completion of the job. B<func> represents the function that should +be started asynchronously. The data pointed to by B<args> and of size B<size> +will be copied and then passed as an argument to B<func> when the job starts. +ASYNC_start_job will return one of the following values: + +=over 4 + +=item B<ASYNC_ERR> + +An error occurred trying to start the job. Check the OpenSSL error queue (e.g. +see L<ERR_print_errors(3)>) for more details. + +=item B<ASYNC_NO_JOBS> + +There are no jobs currently available in the pool. This call can be retried +again at a later time. + +=item B<ASYNC_PAUSE> + +The job was successfully started but was "paused" before it completed (see +ASYNC_pause_job() below). A handle to the job is placed in B<*job>. Other work +can be performed (if desired) and the job restarted at a later time. To restart +a job call ASYNC_start_job() again passing the job handle in B<*job>. The +B<func>, B<args> and B<size> parameters will be ignored when restarting a job. +When restarting a job ASYNC_start_job() B<must> be called from the same thread +that the job was originally started from. + +=item B<ASYNC_FINISH> + +The job completed. B<*job> will be NULL and the return value from B<func> will +be placed in B<*ret>. + +=back + +At any one time there can be a maximum of one job actively running per thread +(you can have many that are paused). ASYNC_get_current_job() can be used to get +a pointer to the currently executing ASYNC_JOB. If no job is currently executing +then this will return NULL. + +If executing within the context of a job (i.e. having been called directly or +indirectly by the function "func" passed as an argument to ASYNC_start_job()) +then ASYNC_pause_job() will immediately return control to the calling +application with ASYNC_PAUSE returned from the ASYNC_start_job() call. A +subsequent call to ASYNC_start_job passing in the relevant ASYNC_JOB in the +B<*job> parameter will resume execution from the ASYNC_pause_job() call. If +ASYNC_pause_job() is called whilst not within the context of a job then no +action is taken and ASYNC_pause_job() returns immediately. + +ASYNC_get_wait_ctx() can be used to get a pointer to the ASYNC_WAIT_CTX +for the B<job>. ASYNC_WAIT_CTXs can have a "wait" file descriptor associated +with them. Applications can wait for the file descriptor to be ready for "read" +using a system function call such as select or poll (being ready for "read" +indicates that the job should be resumed). If no file descriptor is made +available then an application will have to periodically "poll" the job by +attempting to restart it to see if it is ready to continue. + +An example of typical usage might be an async capable engine. User code would +initiate cryptographic operations. The engine would initiate those operations +asynchronously and then call L<ASYNC_WAIT_CTX_set_wait_fd(3)> followed by +ASYNC_pause_job() to return control to the user code. The user code can then +perform other tasks or wait for the job to be ready by calling "select" or other +similar function on the wait file descriptor. The engine can signal to the user +code that the job should be resumed by making the wait file descriptor +"readable". Once resumed the engine should clear the wake signal on the wait +file descriptor. + +The ASYNC_block_pause() function will prevent the currently active job from +pausing. The block will remain in place until a subsequent call to +ASYNC_unblock_pause(). These functions can be nested, e.g. if you call +ASYNC_block_pause() twice then you must call ASYNC_unblock_pause() twice in +order to re-enable pausing. If these functions are called while there is no +currently active job then they have no effect. This functionality can be useful +to avoid deadlock scenarios. For example during the execution of an ASYNC_JOB an +application acquires a lock. It then calls some cryptographic function which +invokes ASYNC_pause_job(). This returns control back to the code that created +the ASYNC_JOB. If that code then attempts to acquire the same lock before +resuming the original job then a deadlock can occur. By calling +ASYNC_block_pause() immediately after acquiring the lock and +ASYNC_unblock_pause() immediately before releasing it then this situation cannot +occur. + +Some platforms cannot support async operations. The ASYNC_is_capable() function +can be used to detect whether the current platform is async capable or not. + +=head1 RETURN VALUES + +ASYNC_init_thread returns 1 on success or 0 otherwise. + +ASYNC_start_job returns one of ASYNC_ERR, ASYNC_NO_JOBS, ASYNC_PAUSE or +ASYNC_FINISH as described above. + +ASYNC_pause_job returns 0 if an error occurred or 1 on success. If called when +not within the context of an ASYNC_JOB then this is counted as success so 1 is +returned. + +ASYNC_get_current_job returns a pointer to the currently executing ASYNC_JOB or +NULL if not within the context of a job. + +ASYNC_get_wait_ctx() returns a pointer to the ASYNC_WAIT_CTX for the job. + +ASYNC_is_capable() returns 1 if the current platform is async capable or 0 +otherwise. + +=head1 NOTES + +On Windows platforms the openssl/async.h header is dependent on some +of the types customarily made available by including windows.h. The +application developer is likely to require control over when the latter +is included, commonly as one of the first included headers. Therefore +it is defined as an application developer's responsibility to include +windows.h prior to async.h. + +=head1 EXAMPLE + +The following example demonstrates how to use most of the core async APIs: + + #ifdef _WIN32 + # include <windows.h> + #endif + #include <stdio.h> + #include <unistd.h> + #include <openssl/async.h> + #include <openssl/crypto.h> + + int unique = 0; + + void cleanup(ASYNC_WAIT_CTX *ctx, const void *key, OSSL_ASYNC_FD r, void *vw) + { + OSSL_ASYNC_FD *w = (OSSL_ASYNC_FD *)vw; + close(r); + close(*w); + OPENSSL_free(w); + } + + int jobfunc(void *arg) + { + ASYNC_JOB *currjob; + unsigned char *msg; + int pipefds[2] = {0, 0}; + OSSL_ASYNC_FD *wptr; + char buf = 'X'; + + currjob = ASYNC_get_current_job(); + if (currjob != NULL) { + printf("Executing within a job\n"); + } else { + printf("Not executing within a job - should not happen\n"); + return 0; + } + + msg = (unsigned char *)arg; + printf("Passed in message is: %s\n", msg); + + if (pipe(pipefds) != 0) { + printf("Failed to create pipe\n"); + return 0; + } + wptr = OPENSSL_malloc(sizeof(OSSL_ASYNC_FD)); + if (wptr == NULL) { + printf("Failed to malloc\n"); + return 0; + } + *wptr = pipefds[1]; + ASYNC_WAIT_CTX_set_wait_fd(ASYNC_get_wait_ctx(currjob), &unique, + pipefds[0], wptr, cleanup); + + /* + * Normally some external event would cause this to happen at some + * later point - but we do it here for demo purposes, i.e. + * immediately signalling that the job is ready to be woken up after + * we return to main via ASYNC_pause_job(). + */ + write(pipefds[1], &buf, 1); + + /* Return control back to main */ + ASYNC_pause_job(); + + /* Clear the wake signal */ + read(pipefds[0], &buf, 1); + + printf ("Resumed the job after a pause\n"); + + return 1; + } + + int main(void) + { + ASYNC_JOB *job = NULL; + ASYNC_WAIT_CTX *ctx = NULL; + int ret; + OSSL_ASYNC_FD waitfd; + fd_set waitfdset; + size_t numfds; + unsigned char msg[13] = "Hello world!"; + + printf("Starting...\n"); + + ctx = ASYNC_WAIT_CTX_new(); + if (ctx == NULL) { + printf("Failed to create ASYNC_WAIT_CTX\n"); + abort(); + } + + for (;;) { + switch(ASYNC_start_job(&job, ctx, &ret, jobfunc, msg, sizeof(msg))) { + case ASYNC_ERR: + case ASYNC_NO_JOBS: + printf("An error occurred\n"); + goto end; + case ASYNC_PAUSE: + printf("Job was paused\n"); + break; + case ASYNC_FINISH: + printf("Job finished with return value %d\n", ret); + goto end; + } + + /* Wait for the job to be woken */ + printf("Waiting for the job to be woken up\n"); + + if (!ASYNC_WAIT_CTX_get_all_fds(ctx, NULL, &numfds) + || numfds > 1) { + printf("Unexpected number of fds\n"); + abort(); + } + ASYNC_WAIT_CTX_get_all_fds(ctx, &waitfd, &numfds); + FD_ZERO(&waitfdset); + FD_SET(waitfd, &waitfdset); + select(waitfd + 1, &waitfdset, NULL, NULL, NULL); + } + + end: + ASYNC_WAIT_CTX_free(ctx); + printf("Finishing\n"); + + return 0; + } + +The expected output from executing the above example program is: + + Starting... + Executing within a job + Passed in message is: Hello world! + Job was paused + Waiting for the job to be woken up + Resumed the job after a pause + Job finished with return value 1 + Finishing + +=head1 SEE ALSO + +L<crypto(3)>, L<ERR_print_errors(3)> + +=head1 HISTORY + +ASYNC_init_thread, ASYNC_cleanup_thread, +ASYNC_start_job, ASYNC_pause_job, ASYNC_get_current_job, ASYNC_get_wait_ctx(), +ASYNC_block_pause(), ASYNC_unblock_pause() and ASYNC_is_capable() were first +added to OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/blowfish.pod b/deps/openssl/openssl/doc/crypto/BF_encrypt.pod index 5b2d274c15..0401e90a20 100644 --- a/deps/openssl/openssl/doc/crypto/blowfish.pod +++ b/deps/openssl/openssl/doc/crypto/BF_encrypt.pod @@ -2,7 +2,7 @@ =head1 NAME -blowfish, BF_set_key, BF_encrypt, BF_decrypt, BF_ecb_encrypt, BF_cbc_encrypt, +BF_set_key, BF_encrypt, BF_decrypt, BF_ecb_encrypt, BF_cbc_encrypt, BF_cfb64_encrypt, BF_ofb64_encrypt, BF_options - Blowfish encryption =head1 SYNOPSIS @@ -14,16 +14,16 @@ BF_cfb64_encrypt, BF_ofb64_encrypt, BF_options - Blowfish encryption void BF_ecb_encrypt(const unsigned char *in, unsigned char *out, BF_KEY *key, int enc); void BF_cbc_encrypt(const unsigned char *in, unsigned char *out, - long length, BF_KEY *schedule, unsigned char *ivec, int enc); + long length, BF_KEY *schedule, unsigned char *ivec, int enc); void BF_cfb64_encrypt(const unsigned char *in, unsigned char *out, - long length, BF_KEY *schedule, unsigned char *ivec, int *num, + long length, BF_KEY *schedule, unsigned char *ivec, int *num, int enc); void BF_ofb64_encrypt(const unsigned char *in, unsigned char *out, - long length, BF_KEY *schedule, unsigned char *ivec, int *num); + long length, BF_KEY *schedule, unsigned char *ivec, int *num); const char *BF_options(void); - void BF_encrypt(BF_LONG *data,const BF_KEY *key); - void BF_decrypt(BF_LONG *data,const BF_KEY *key); + void BF_encrypt(BF_LONG *data, const BF_KEY *key); + void BF_decrypt(BF_LONG *data, const BF_KEY *key); =head1 DESCRIPTION @@ -33,7 +33,7 @@ by Counterpane (see http://www.counterpane.com/blowfish.html ). Blowfish is a block cipher that operates on 64 bit (8 byte) blocks of data. It uses a variable size key, but typically, 128 bit (16 byte) keys are considered good for strong encryption. Blowfish can be used in the same -modes as DES (see L<des_modes(7)|des_modes(7)>). Blowfish is currently one +modes as DES (see L<des_modes(7)>). Blowfish is currently one of the faster block ciphers. It is quite a bit faster than DES, and much faster than IDEA or RC2. @@ -52,7 +52,7 @@ everything after the first 64 bits is ignored. The mode functions BF_cbc_encrypt(), BF_cfb64_encrypt() and BF_ofb64_encrypt() all operate on variable length data. They all take an initialization vector -B<ivec> which needs to be passed along into the next call of the same function +B<ivec> which needs to be passed along into the next call of the same function for the same message. B<ivec> may be initialized with anything, but the recipient needs to know what it was initialized with, or it won't be able to decrypt. Some programs and protocols simplify this, like SSH, where @@ -97,16 +97,21 @@ None of the functions presented here return any value. =head1 NOTE Applications should use the higher level functions -L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> etc. instead of calling the -blowfish functions directly. +L<EVP_EncryptInit(3)> etc. instead of calling these +functions directly. =head1 SEE ALSO -L<des_modes(7)|des_modes(7)> +L<EVP_EncryptInit(3)>, +L<des_modes(7)> -=head1 HISTORY +=head1 COPYRIGHT -The Blowfish functions are available in all versions of SSLeay and OpenSSL. +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. -=cut +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BIO_ADDR.pod b/deps/openssl/openssl/doc/crypto/BIO_ADDR.pod new file mode 100644 index 0000000000..4b169e8a89 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/BIO_ADDR.pod @@ -0,0 +1,125 @@ +=pod + +=head1 NAME + +BIO_ADDR, BIO_ADDR_new, BIO_ADDR_clear, BIO_ADDR_free, BIO_ADDR_rawmake, +BIO_ADDR_family, BIO_ADDR_rawaddress, BIO_ADDR_rawport, +BIO_ADDR_hostname_string, BIO_ADDR_service_string, +BIO_ADDR_path_string - BIO_ADDR routines + +=head1 SYNOPSIS + + #include <sys/types.h> + #include <openssl/bio.h> + + typedef union bio_addr_st BIO_ADDR; + + BIO_ADDR *BIO_ADDR_new(void); + void BIO_ADDR_free(BIO_ADDR *); + void BIO_ADDR_clear(BIO_ADDR *ap); + int BIO_ADDR_rawmake(BIO_ADDR *ap, int family, + const void *where, size_t wherelen, unsigned short port); + int BIO_ADDR_family(const BIO_ADDR *ap); + int BIO_ADDR_rawaddress(const BIO_ADDR *ap, void *p, size_t *l); + unsigned short BIO_ADDR_rawport(const BIO_ADDR *ap); + char *BIO_ADDR_hostname_string(const BIO_ADDR *ap, int numeric); + char *BIO_ADDR_service_string(const BIO_ADDR *ap, int numeric); + char *BIO_ADDR_path_string(const BIO_ADDR *ap); + +=head1 DESCRIPTION + +The B<BIO_ADDR> type is a wrapper around all types of socket +addresses that OpenSSL deals with, currently transparently +supporting AF_INET, AF_INET6 and AF_UNIX according to what's +available on the platform at hand. + +BIO_ADDR_new() creates a new unfilled B<BIO_ADDR>, to be used +with routines that will fill it with information, such as +BIO_accept_ex(). + +BIO_ADDR_free() frees a B<BIO_ADDR> created with BIO_ADDR_new(). + +BIO_ADDR_clear() clears any data held within the provided B<BIO_ADDR> and sets +it back to an uninitialised state. + +BIO_ADDR_rawmake() takes a protocol B<family>, an byte array of +size B<wherelen> with an address in network byte order pointed at +by B<where> and a port number in network byte order in B<port> (except +for the B<AF_UNIX> protocol family, where B<port> is meaningless and +therefore ignored) and populates the given B<BIO_ADDR> with them. +In case this creates a B<AF_UNIX> B<BIO_ADDR>, B<wherelen> is expected +to be the length of the path string (not including the terminating +NUL, such as the result of a call to strlen()). +I<Read on about the addresses in L</RAW ADDRESSES> below>. + +BIO_ADDR_family() returns the protocol family of the given +B<BIO_ADDR>. The possible non-error results are one of the +constants AF_INET, AF_INET6 and AF_UNIX. It will also return AF_UNSPEC if the +BIO_ADDR has not been initialised. + +BIO_ADDR_rawaddress() will write the raw address of the given +B<BIO_ADDR> in the area pointed at by B<p> if B<p> is non-NULL, +and will set B<*l> to be the amount of bytes the raw address +takes up if B<l> is non-NULL. +A technique to only find out the size of the address is a call +with B<p> set to B<NULL>. The raw address will be in network byte +order, most significant byte first. +In case this is a B<AF_UNIX> B<BIO_ADDR>, B<l> gets the length of the +path string (not including the terminating NUL, such as the result of +a call to strlen()). +I<Read on about the addresses in L</RAW ADDRESSES> below>. + +BIO_ADDR_rawport() returns the raw port of the given B<BIO_ADDR>. +The raw port will be in network byte order. + +BIO_ADDR_hostname_string() returns a character string with the +hostname of the given B<BIO_ADDR>. If B<numeric> is 1, the string +will contain the numerical form of the address. This only works for +B<BIO_ADDR> of the protocol families AF_INET and AF_INET6. The +returned string has been allocated on the heap and must be freed +with OPENSSL_free(). + +BIO_ADDR_service_string() returns a character string with the +service name of the port of the given B<BIO_ADDR>. If B<numeric> +is 1, the string will contain the port number. This only works +for B<BIO_ADDR> of the protocol families AF_INET and AF_INET6. The +returned string has been allocated on the heap and must be freed +with OPENSSL_free(). + +BIO_ADDR_path_string() returns a character string with the path +of the given B<BIO_ADDR>. This only works for B<BIO_ADDR> of the +protocol family AF_UNIX. The returned string has been allocated +on the heap and must be freed with OPENSSL_free(). + +=head1 RAW ADDRESSES + +Both BIO_ADDR_rawmake() and BIO_ADDR_rawaddress() take a pointer to a +network byte order address of a specific site. Internally, those are +treated as a pointer to B<struct in_addr> (for B<AF_INET>), B<struct +in6_addr> (for B<AF_INET6>) or B<char *> (for B<AF_UNIX>), all +depending on the protocol family the address is for. + +=head1 RETURN VALUES + +The string producing functions BIO_ADDR_hostname_string(), +BIO_ADDR_service_string() and BIO_ADDR_path_string() will +return B<NULL> on error and leave an error indication on the +OpenSSL error stack. + +All other functions described here return 0 or B<NULL> when the +information they should return isn't available. + +=head1 SEE ALSO + +L<BIO_connect(3)>, L<BIO_s_connect(3)> + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BIO_ADDRINFO.pod b/deps/openssl/openssl/doc/crypto/BIO_ADDRINFO.pod new file mode 100644 index 0000000000..7811da46a5 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/BIO_ADDRINFO.pod @@ -0,0 +1,91 @@ +=pod + +=head1 NAME + +BIO_lookup_type, +BIO_ADDRINFO, BIO_ADDRINFO_next, BIO_ADDRINFO_free, +BIO_ADDRINFO_family, BIO_ADDRINFO_socktype, BIO_ADDRINFO_protocol, +BIO_ADDRINFO_address, +BIO_lookup +- BIO_ADDRINFO type and routines + +=head1 SYNOPSIS + + #include <sys/types.h> + #include <openssl/bio.h> + + typedef union bio_addrinfo_st BIO_ADDRINFO; + + enum BIO_lookup_type { + BIO_LOOKUP_CLIENT, BIO_LOOKUP_SERVER + }; + int BIO_lookup(const char *node, const char *service, + enum BIO_lookup_type lookup_type, + int family, int socktype, BIO_ADDRINFO **res); + + const BIO_ADDRINFO *BIO_ADDRINFO_next(const BIO_ADDRINFO *bai); + int BIO_ADDRINFO_family(const BIO_ADDRINFO *bai); + int BIO_ADDRINFO_socktype(const BIO_ADDRINFO *bai); + int BIO_ADDRINFO_protocol(const BIO_ADDRINFO *bai); + const BIO_ADDR *BIO_ADDRINFO_address(const BIO_ADDRINFO *bai); + void BIO_ADDRINFO_free(BIO_ADDRINFO *bai); + +=head1 DESCRIPTION + +The B<BIO_ADDRINFO> type is a wrapper for address information +types provided on your platform. + +B<BIO_ADDRINFO> normally forms a chain of several that can be +picked at one by one. + +BIO_lookup() looks up a specified B<host> and B<service>, and +uses B<lookup_type> to determine what the default address should +be if B<host> is B<NULL>. B<family>, B<socktype> are used to +determine what protocol family and protocol should be used for +the lookup. B<family> can be any of AF_INET, AF_INET6, AF_UNIX and +AF_UNSPEC, and B<socktype> can be SOCK_STREAM or SOCK_DGRAM. +B<res> points at a pointer to hold the start of a B<BIO_ADDRINFO> +chain. +For the family B<AF_UNIX>, BIO_lookup() will ignore the B<service> +parameter and expects the B<node> parameter to hold the path to the +socket file. + +BIO_ADDRINFO_family() returns the family of the given +B<BIO_ADDRINFO>. The result will be one of the constants +AF_INET, AF_INET6 and AF_UNIX. + +BIO_ADDRINFO_socktype() returns the socket type of the given +B<BIO_ADDRINFO>. The result will be one of the constants +SOCK_STREAM and SOCK_DGRAM. + +BIO_ADDRINFO_protocol() returns the protocol id of the given +B<BIO_ADDRINFO>. The result will be one of the constants +IPPROTO_TCP and IPPROTO_UDP. + +BIO_ADDRINFO_address() returns the underlying B<BIO_ADDR> +of the given B<BIO_ADDRINFO>. + +BIO_ADDRINFO_next() returns the next B<BIO_ADDRINFO> in the chain +from the given one. + +BIO_ADDRINFO_free() frees the chain of B<BIO_ADDRINFO> starting +with the given one. + +=head1 RETURN VALUES + +BIO_lookup() returns 1 on success and 0 when an error occurred, and +will leave an error indication on the OpenSSL error stack in that case. + +All other functions described here return 0 or B<NULL> when the +information they should return isn't available. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BIO_connect.pod b/deps/openssl/openssl/doc/crypto/BIO_connect.pod new file mode 100644 index 0000000000..5194033feb --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/BIO_connect.pod @@ -0,0 +1,112 @@ +=pod + +=head1 NAME + +BIO_socket, BIO_connect, BIO_listen, BIO_accept_ex, BIO_closesocket - BIO +socket communication setup routines + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + int BIO_socket(int domain, int socktype, int protocol, int options); + int BIO_connect(int sock, const BIO_ADDR *addr, int options); + int BIO_listen(int sock, const BIO_ADDR *addr, int options); + int BIO_accept_ex(int accept_sock, BIO_ADDR *peer, int options); + int BIO_closesocket(int sock); + +=head1 DESCRIPTION + +BIO_socket() creates a socket in the domain B<domain>, of type +B<socktype> and B<protocol>. Socket B<options> are currently unused, +but is present for future use. + +BIO_connect() connects B<sock> to the address and service given by +B<addr>. Connection B<options> may be zero or any combination of +B<BIO_SOCK_KEEPALIVE>, B<BIO_SOCK_NONBLOCK> and B<BIO_SOCK_NODELAY>. +The flags are described in L</FLAGS> below. + +BIO_listen() has B<sock> start listening on the address and service +given by B<addr>. Connection B<options> may be zero or any +combination of B<BIO_SOCK_KEEPALIVE>, B<BIO_SOCK_NONBLOCK>, +B<BIO_SOCK_NODELAY>, B<BIO_SOCK_REUSEADDR> and B<BIO_SOCK_V6_ONLY>. +The flags are described in L</FLAGS> below. + +BIO_accept_ex() waits for an incoming connections on the given +socket B<accept_sock>. When it gets a connection, the address and +port of the peer gets stored in B<peer> if that one is non-NULL. +Accept B<options> may be zero or B<BIO_SOCK_NONBLOCK>, and is applied +on the accepted socket. The flags are described in L</FLAGS> below. + +BIO_closesocket() closes B<sock>. + +=head1 FLAGS + +=over 4 + +=item BIO_SOCK_KEEPALIVE + +Enables regular sending of keep-alive messages. + +=item BIO_SOCK_NONBLOCK + +Sets the socket to non-blocking mode. + +=item BIO_SOCK_NODELAY + +Corresponds to B<TCP_NODELAY>, and disables the Nagle algorithm. With +this set, any data will be sent as soon as possible instead of being +buffered until there's enough for the socket to send out in one go. + +=item BIO_SOCK_REUSEADDR + +Try to reuse the address and port combination for a recently closed +port. + +=item BIO_SOCK_V6_ONLY + +When creating an IPv6 socket, make it only listen for IPv6 addresses +and not IPv4 addresses mapped to IPv6. + +=back + +These flags are bit flags, so they are to be combined with the +C<|> operator, for example: + + BIO_connect(sock, addr, BIO_SOCK_KEEPALIVE | BIO_SOCK_NONBLOCK); + +=head1 RETURN VALUES + +BIO_socket() returns the socket number on success or B<INVALID_SOCKET> +(-1) on error. When an error has occurred, the OpenSSL error stack +will hold the error data and errno has the system error. + +BIO_connect() and BIO_listen() return 1 on success or 0 on error. +When an error has occurred, the OpenSSL error stack will hold the error +data and errno has the system error. + +BIO_accept_ex() returns the accepted socket on success or +B<INVALID_SOCKET> (-1) on error. When an error has occurred, the +OpenSSL error stack will hold the error data and errno has the system +error. + +=head1 HISTORY + +BIO_gethostname(), BIO_get_port(), BIO_get_host_ip(), +BIO_get_accept_socket() and BIO_accept() are deprecated since OpenSSL +1.1. Use the functions described above instead. + +=head1 SEE ALSO + +L<BIO_ADDR(3)> + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BIO_ctrl.pod b/deps/openssl/openssl/doc/crypto/BIO_ctrl.pod index 722e8b8f46..60cd10883b 100644 --- a/deps/openssl/openssl/doc/crypto/BIO_ctrl.pod +++ b/deps/openssl/openssl/doc/crypto/BIO_ctrl.pod @@ -5,33 +5,34 @@ BIO_ctrl, BIO_callback_ctrl, BIO_ptr_ctrl, BIO_int_ctrl, BIO_reset, BIO_seek, BIO_tell, BIO_flush, BIO_eof, BIO_set_close, BIO_get_close, BIO_pending, BIO_wpending, BIO_ctrl_pending, BIO_ctrl_wpending, -BIO_get_info_callback, BIO_set_info_callback - BIO control operations +BIO_get_info_callback, BIO_set_info_callback, BIO_info_cb +- BIO control operations =head1 SYNOPSIS #include <openssl/bio.h> - long BIO_ctrl(BIO *bp,int cmd,long larg,void *parg); - long BIO_callback_ctrl(BIO *b, int cmd, void (*fp)(struct bio_st *, int, const char *, int, long, long)); - char * BIO_ptr_ctrl(BIO *bp,int cmd,long larg); - long BIO_int_ctrl(BIO *bp,int cmd,long larg,int iarg); + typedef int BIO_info_cb(BIO *b, int state, int res); + + long BIO_ctrl(BIO *bp, int cmd, long larg, void *parg); + long BIO_callback_ctrl(BIO *b, int cmd, BIO_info_cb *cb); + char *BIO_ptr_ctrl(BIO *bp, int cmd, long larg); + long BIO_int_ctrl(BIO *bp, int cmd, long larg, int iarg); int BIO_reset(BIO *b); int BIO_seek(BIO *b, int ofs); int BIO_tell(BIO *b); int BIO_flush(BIO *b); int BIO_eof(BIO *b); - int BIO_set_close(BIO *b,long flag); + int BIO_set_close(BIO *b, long flag); int BIO_get_close(BIO *b); int BIO_pending(BIO *b); int BIO_wpending(BIO *b); size_t BIO_ctrl_pending(BIO *b); size_t BIO_ctrl_wpending(BIO *b); - int BIO_get_info_callback(BIO *b,bio_info_cb **cbp); - int BIO_set_info_callback(BIO *b,bio_info_cb *cb); - - typedef void bio_info_cb(BIO *b, int oper, const char *ptr, int arg1, long arg2, long arg3); + int BIO_get_info_callback(BIO *b, BIO_info_cb **cbp); + int BIO_set_info_callback(BIO *b, BIO_info_cb *cb); =head1 DESCRIPTION @@ -94,7 +95,7 @@ return the amount of pending data. =head1 NOTES BIO_flush(), because it can write data may return 0 or -1 indicating -that the call should be retried later in a similar manner to BIO_write(). +that the call should be retried later in a similar manner to BIO_write_ex(). The BIO_should_retry() call should be used and appropriate action taken is the call fails. @@ -121,8 +122,15 @@ operation. Some of the return values are ambiguous and care should be taken. In particular a return value of 0 can be returned if an operation is not supported, if an error occurred, if EOF has not been reached and in -the case of BIO_seek() on a file BIO for a successful operation. +the case of BIO_seek() on a file BIO for a successful operation. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. -=head1 SEE ALSO +Licensed under the OpenSSL license (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>. -TBA +=cut diff --git a/deps/openssl/openssl/doc/crypto/BIO_f_base64.pod b/deps/openssl/openssl/doc/crypto/BIO_f_base64.pod index d1d7bf0bd0..19df1dd638 100644 --- a/deps/openssl/openssl/doc/crypto/BIO_f_base64.pod +++ b/deps/openssl/openssl/doc/crypto/BIO_f_base64.pod @@ -4,12 +4,14 @@ BIO_f_base64 - base64 BIO filter +=for comment multiple includes + =head1 SYNOPSIS #include <openssl/bio.h> #include <openssl/evp.h> - BIO_METHOD * BIO_f_base64(void); + const BIO_METHOD *BIO_f_base64(void); =head1 DESCRIPTION @@ -17,7 +19,7 @@ BIO_f_base64() returns the base64 BIO method. This is a filter BIO that base64 encodes any data written through it and decodes any data read through it. -Base64 BIOs do not support BIO_gets() or BIO_puts(). +Base64 BIOs do not support BIO_gets() or BIO_puts(). BIO_flush() on a base64 BIO that is being written through is used to signal that no more data is to be encoded: this is used @@ -63,8 +65,8 @@ data to standard output: bio = BIO_new_fp(stdin, BIO_NOCLOSE); bio_out = BIO_new_fp(stdout, BIO_NOCLOSE); BIO_push(b64, bio); - while((inlen = BIO_read(b64, inbuf, 512)) > 0) - BIO_write(bio_out, inbuf, inlen); + while((inlen = BIO_read(b64, inbuf, 512)) > 0) + BIO_write(bio_out, inbuf, inlen); BIO_flush(bio_out); BIO_free_all(b64); @@ -77,6 +79,13 @@ data following the base64 encoded block to be misinterpreted. There should be some way of specifying a test that the BIO can perform to reliably determine EOF (for example a MIME boundary). -=head1 SEE ALSO +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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>. -TBA +=cut diff --git a/deps/openssl/openssl/doc/crypto/BIO_f_buffer.pod b/deps/openssl/openssl/doc/crypto/BIO_f_buffer.pod index c0dccf1abe..3224710942 100644 --- a/deps/openssl/openssl/doc/crypto/BIO_f_buffer.pod +++ b/deps/openssl/openssl/doc/crypto/BIO_f_buffer.pod @@ -2,19 +2,25 @@ =head1 NAME -BIO_f_buffer - buffering BIO +BIO_get_buffer_num_lines, +BIO_set_read_buffer_size, +BIO_set_write_buffer_size, +BIO_set_buffer_size, +BIO_set_buffer_read_data, +BIO_f_buffer +- buffering BIO =head1 SYNOPSIS #include <openssl/bio.h> - BIO_METHOD * BIO_f_buffer(void); + const BIO_METHOD *BIO_f_buffer(void); - #define BIO_get_buffer_num_lines(b) BIO_ctrl(b,BIO_C_GET_BUFF_NUM_LINES,0,NULL) - #define BIO_set_read_buffer_size(b,size) BIO_int_ctrl(b,BIO_C_SET_BUFF_SIZE,size,0) - #define BIO_set_write_buffer_size(b,size) BIO_int_ctrl(b,BIO_C_SET_BUFF_SIZE,size,1) - #define BIO_set_buffer_size(b,size) BIO_ctrl(b,BIO_C_SET_BUFF_SIZE,size,NULL) - #define BIO_set_buffer_read_data(b,buf,num) BIO_ctrl(b,BIO_C_SET_BUFF_READ_DATA,num,buf) + long BIO_get_buffer_num_lines(BIO *b); + long BIO_set_read_buffer_size(BIO *b, long size); + long BIO_set_write_buffer_size(BIO *b, long size); + long BIO_set_buffer_size(BIO *b, long size); + long BIO_set_buffer_read_data(BIO *b, void *buf, long num); =head1 DESCRIPTION @@ -41,6 +47,8 @@ is expanded. =head1 NOTES +These functions, other than BIO_f_buffer(), are implemented as macros. + Buffering BIOs implement BIO_gets() by using BIO_read() operations on the next BIO in the chain. By prepending a buffering BIO to a chain it is therefore possible to provide BIO_gets() functionality if the following BIOs do not @@ -66,9 +74,19 @@ there was an error. =head1 SEE ALSO -L<BIO(3)|BIO(3)>, -L<BIO_reset(3)|BIO_reset(3)>, -L<BIO_flush(3)|BIO_flush(3)>, -L<BIO_pop(3)|BIO_pop(3)>, -L<BIO_ctrl(3)|BIO_ctrl(3)>, -L<BIO_int_ctrl(3)|BIO_ctrl(3)> +L<BIO(3)>, +L<BIO_reset(3)>, +L<BIO_flush(3)>, +L<BIO_pop(3)>, +L<BIO_ctrl(3)>. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BIO_f_cipher.pod b/deps/openssl/openssl/doc/crypto/BIO_f_cipher.pod index 02439cea94..87ab3ccc9d 100644 --- a/deps/openssl/openssl/doc/crypto/BIO_f_cipher.pod +++ b/deps/openssl/openssl/doc/crypto/BIO_f_cipher.pod @@ -4,14 +4,16 @@ BIO_f_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx - cipher BIO filter +=for comment multiple includes + =head1 SYNOPSIS #include <openssl/bio.h> #include <openssl/evp.h> - BIO_METHOD * BIO_f_cipher(void); - void BIO_set_cipher(BIO *b,const EVP_CIPHER *cipher, - unsigned char *key, unsigned char *iv, int enc); + const BIO_METHOD *BIO_f_cipher(void); + void BIO_set_cipher(BIO *b, const EVP_CIPHER *cipher, + unsigned char *key, unsigned char *iv, int enc); int BIO_get_cipher_status(BIO *b) int BIO_get_cipher_ctx(BIO *b, EVP_CIPHER_CTX **pctx) @@ -22,7 +24,7 @@ BIO that encrypts any data written through it, and decrypts any data read from it. It is a BIO wrapper for the cipher routines EVP_CipherInit(), EVP_CipherUpdate() and EVP_CipherFinal(). -Cipher BIOs do not support BIO_gets() or BIO_puts(). +Cipher BIOs do not support BIO_gets() or BIO_puts(). BIO_flush() on an encryption BIO that is being written through is used to signal that no more data is to be encrypted: this is used @@ -48,7 +50,7 @@ When encrypting BIO_flush() B<must> be called to flush the final block through the BIO. If it is not then the final block will fail a subsequent decrypt. -When decrypting an error on the final block is signalled by a zero +When decrypting an error on the final block is signaled by a zero return value from the read operation. A successful decrypt followed by EOF will also return zero for the final read. BIO_get_cipher_status() should be called to determine if the decrypt was successful. @@ -67,10 +69,13 @@ for failure. BIO_get_cipher_ctx() currently always returns 1. -=head1 EXAMPLES +=head1 COPYRIGHT -TBA +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. -=head1 SEE ALSO +Licensed under the OpenSSL license (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>. -TBA +=cut diff --git a/deps/openssl/openssl/doc/crypto/BIO_f_md.pod b/deps/openssl/openssl/doc/crypto/BIO_f_md.pod index 2cc41f89d2..32f0046751 100644 --- a/deps/openssl/openssl/doc/crypto/BIO_f_md.pod +++ b/deps/openssl/openssl/doc/crypto/BIO_f_md.pod @@ -4,15 +4,17 @@ BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx - message digest BIO filter +=for comment multiple includes + =head1 SYNOPSIS #include <openssl/bio.h> #include <openssl/evp.h> - BIO_METHOD * BIO_f_md(void); - int BIO_set_md(BIO *b,EVP_MD *md); - int BIO_get_md(BIO *b,EVP_MD **mdp); - int BIO_get_md_ctx(BIO *b,EVP_MD_CTX **mdcp); + const BIO_METHOD *BIO_f_md(void); + int BIO_set_md(BIO *b, EVP_MD *md); + int BIO_get_md(BIO *b, EVP_MD **mdp); + int BIO_get_md_ctx(BIO *b, EVP_MD_CTX **mdcp); =head1 DESCRIPTION @@ -58,10 +60,8 @@ If an application needs to call BIO_gets() or BIO_puts() through a chain containing digest BIOs then this can be done by prepending a buffering BIO. -Before OpenSSL 1.0.0 the call to BIO_get_md_ctx() would only work if the BIO -had been initialized for example by calling BIO_set_md() ). In OpenSSL -1.0.0 and later the context is always returned and the BIO is state is set -to initialized. This allows applications to initialize the context externally +Calling BIO_get_md_ctx() will return the context and initialize the BIO +state. This allows applications to initialize the context externally if the standard calls such as BIO_set_md() are not sufficiently flexible. =head1 RETURN VALUES @@ -105,9 +105,9 @@ The next example digests data by reading through a chain instead: BIO_set_md(mdtmp, EVP_md5()); bio = BIO_push(mdtmp, bio); do { - rdlen = BIO_read(bio, buf, sizeof(buf)); + rdlen = BIO_read(bio, buf, sizeof(buf)); /* Might want to do something with the data here */ - } while(rdlen > 0); + } while (rdlen > 0); This next example retrieves the message digests from a BIO chain and outputs them. This could be used with the examples above. @@ -116,18 +116,18 @@ outputs them. This could be used with the examples above. unsigned char mdbuf[EVP_MAX_MD_SIZE]; int mdlen; int i; - mdtmp = bio; /* Assume bio has previously been set up */ + mdtmp = bio; /* Assume bio has previously been set up */ do { - EVP_MD *md; - mdtmp = BIO_find_type(mdtmp, BIO_TYPE_MD); - if(!mdtmp) break; - BIO_get_md(mdtmp, &md); + EVP_MD *md; + mdtmp = BIO_find_type(mdtmp, BIO_TYPE_MD); + if (!mdtmp) break; + BIO_get_md(mdtmp, &md); printf("%s digest", OBJ_nid2sn(EVP_MD_type(md))); - mdlen = BIO_gets(mdtmp, mdbuf, EVP_MAX_MD_SIZE); - for(i = 0; i < mdlen; i++) printf(":%02X", mdbuf[i]); - printf("\n"); - mdtmp = BIO_next(mdtmp); - } while(mdtmp); + mdlen = BIO_gets(mdtmp, mdbuf, EVP_MAX_MD_SIZE); + for (i = 0; i < mdlen; i++) printf(":%02X", mdbuf[i]); + printf("\n"); + mdtmp = BIO_next(mdtmp); + } while (mdtmp); BIO_free_all(bio); @@ -139,6 +139,18 @@ and BIO_puts() should be passed to the next BIO in the chain and digest the data passed through and that digests should be retrieved using a separate BIO_ctrl() call. -=head1 SEE ALSO +=head1 HISTORY + +Before OpenSSL 1.0.0., the call to BIO_get_md_ctx() would only work if the +BIO was initialized first. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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>. -TBA +=cut diff --git a/deps/openssl/openssl/doc/crypto/BIO_f_null.pod b/deps/openssl/openssl/doc/crypto/BIO_f_null.pod index b057c18408..c4e4c667c1 100644 --- a/deps/openssl/openssl/doc/crypto/BIO_f_null.pod +++ b/deps/openssl/openssl/doc/crypto/BIO_f_null.pod @@ -8,7 +8,7 @@ BIO_f_null - null filter #include <openssl/bio.h> - BIO_METHOD * BIO_f_null(void); + const BIO_METHOD * BIO_f_null(void); =head1 DESCRIPTION @@ -27,6 +27,13 @@ As may be apparent a null filter BIO is not particularly useful. BIO_f_null() returns the null filter BIO method. -=head1 SEE ALSO +=head1 COPYRIGHT -TBA +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BIO_f_ssl.pod b/deps/openssl/openssl/doc/crypto/BIO_f_ssl.pod index a9f23f1dd7..3f9635ee68 100644 --- a/deps/openssl/openssl/doc/crypto/BIO_f_ssl.pod +++ b/deps/openssl/openssl/doc/crypto/BIO_f_ssl.pod @@ -2,41 +2,42 @@ =head1 NAME -BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode, BIO_set_ssl_renegotiate_bytes, +BIO_do_handshake, +BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode, +BIO_set_ssl_renegotiate_bytes, BIO_get_num_renegotiates, BIO_set_ssl_renegotiate_timeout, BIO_new_ssl, BIO_new_ssl_connect, BIO_new_buffer_ssl_connect, BIO_ssl_copy_session_id, BIO_ssl_shutdown - SSL BIO +=for comment multiple includes + =head1 SYNOPSIS #include <openssl/bio.h> #include <openssl/ssl.h> - BIO_METHOD *BIO_f_ssl(void); + const BIO_METHOD *BIO_f_ssl(void); - #define BIO_set_ssl(b,ssl,c) BIO_ctrl(b,BIO_C_SET_SSL,c,(char *)ssl) - #define BIO_get_ssl(b,sslp) BIO_ctrl(b,BIO_C_GET_SSL,0,(char *)sslp) - #define BIO_set_ssl_mode(b,client) BIO_ctrl(b,BIO_C_SSL_MODE,client,NULL) - #define BIO_set_ssl_renegotiate_bytes(b,num) \ - BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_BYTES,num,NULL); - #define BIO_set_ssl_renegotiate_timeout(b,seconds) \ - BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT,seconds,NULL); - #define BIO_get_num_renegotiates(b) \ - BIO_ctrl(b,BIO_C_SET_SSL_NUM_RENEGOTIATES,0,NULL); + long BIO_set_ssl(BIO *b, SSL *ssl, long c); + long BIO_get_ssl(BIO *b, SSL **sslp); + long BIO_set_ssl_mode(BIO *b, long client); + long BIO_set_ssl_renegotiate_bytes(BIO *b, long num); + long BIO_set_ssl_renegotiate_timeout(BIO *b, long seconds); + long BIO_get_num_renegotiates(BIO *b); - BIO *BIO_new_ssl(SSL_CTX *ctx,int client); + BIO *BIO_new_ssl(SSL_CTX *ctx, int client); BIO *BIO_new_ssl_connect(SSL_CTX *ctx); BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx); - int BIO_ssl_copy_session_id(BIO *to,BIO *from); + int BIO_ssl_copy_session_id(BIO *to, BIO *from); void BIO_ssl_shutdown(BIO *bio); - #define BIO_do_handshake(b) BIO_ctrl(b,BIO_C_DO_STATE_MACHINE,0,NULL) + long BIO_do_handshake(BIO *b); =head1 DESCRIPTION BIO_f_ssl() returns the SSL BIO method. This is a filter BIO which is a wrapper round the OpenSSL SSL routines adding a BIO "flavour" to -SSL I/O. +SSL I/O. I/O performed on an SSL BIO communicates using the SSL protocol with the SSLs read and write BIOs. If an SSL connection is not established @@ -63,7 +64,7 @@ BIO_set_ssl_mode() sets the SSL BIO mode to B<client>. If B<client> is 1 client mode is set. If B<client> is 0 server mode is set. BIO_set_ssl_renegotiate_bytes() sets the renegotiate byte count -to B<num>. When set after every B<num> bytes of I/O (read and write) +to B<num>. When set after every B<num> bytes of I/O (read and write) the SSL session is automatically renegotiated. B<num> must be at least 512 bytes. @@ -84,7 +85,7 @@ BIO_new_buffer_ssl_connect() creates a new BIO chain consisting of a buffering BIO, an SSL BIO (using B<ctx>) and a connect BIO. -BIO_ssl_copy_session_id() copies an SSL session id between +BIO_ssl_copy_session_id() copies an SSL session id between BIO chains B<from> and B<to>. It does this by locating the SSL BIOs in each chain and calling SSL_copy_session_id() on the internal SSL pointer. @@ -110,7 +111,7 @@ circumstances. Specifically this will happen if a session renegotiation takes place during a BIO_read() operation, one case where this happens is when step up occurs. -In OpenSSL 0.9.6 and later the SSL flag SSL_AUTO_RETRY can be +The SSL flag SSL_AUTO_RETRY can be set to disable this behaviour. That is when this flag is set an SSL BIO using a blocking transport will never request a retry. @@ -124,15 +125,15 @@ Applications do not have to call BIO_do_handshake() but may wish to do so to separate the handshake process from other I/O processing. -=head1 RETURN VALUES - -TBA +BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(), +BIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout(), +BIO_get_num_renegotiates(), and BIO_do_handshake() are implemented as macros. =head1 EXAMPLE This SSL/TLS client example, attempts to retrieve a page from an SSL/TLS web server. The I/O routines are identical to those of the -unencrypted example in L<BIO_s_connect(3)|BIO_s_connect(3)>. +unencrypted example in L<BIO_s_connect(3)>. BIO *sbio, *out; int len; @@ -140,57 +141,48 @@ unencrypted example in L<BIO_s_connect(3)|BIO_s_connect(3)>. SSL_CTX *ctx; SSL *ssl; - ERR_load_crypto_strings(); - ERR_load_SSL_strings(); - OpenSSL_add_all_algorithms(); + /* XXX Seed the PRNG if needed. */ - /* We would seed the PRNG here if the platform didn't - * do it automatically - */ + ctx = SSL_CTX_new(TLS_client_method()); - ctx = SSL_CTX_new(SSLv23_client_method()); - - /* We'd normally set some stuff like the verify paths and - * mode here because as things stand this will connect to - * any server whose certificate is signed by any CA. - */ + /* XXX Set verify paths and mode here. */ sbio = BIO_new_ssl_connect(ctx); - BIO_get_ssl(sbio, &ssl); - - if(!ssl) { - fprintf(stderr, "Can't locate SSL pointer\n"); - /* whatever ... */ + if (ssl == NULL) { + fprintf(stderr, "Can't locate SSL pointer\n"); + ERR_print_errors_fp(stderr); + exit(1); } /* Don't want any retries */ SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); - /* We might want to do other things with ssl here */ + /* XXX We might want to do other things with ssl here */ - BIO_set_conn_hostname(sbio, "localhost:https"); + /* An empty host part means the loopback address */ + BIO_set_conn_hostname(sbio, ":https"); out = BIO_new_fp(stdout, BIO_NOCLOSE); - if(BIO_do_connect(sbio) <= 0) { - fprintf(stderr, "Error connecting to server\n"); - ERR_print_errors_fp(stderr); - /* whatever ... */ + if (BIO_do_connect(sbio) <= 0) { + fprintf(stderr, "Error connecting to server\n"); + ERR_print_errors_fp(stderr); + exit(1); } - - if(BIO_do_handshake(sbio) <= 0) { - fprintf(stderr, "Error establishing SSL connection\n"); - ERR_print_errors_fp(stderr); - /* whatever ... */ + if (BIO_do_handshake(sbio) <= 0) { + fprintf(stderr, "Error establishing SSL connection\n"); + ERR_print_errors_fp(stderr); + exit(1); } - /* Could examine ssl here to get connection info */ + /* XXX Could examine ssl here to get connection info */ BIO_puts(sbio, "GET / HTTP/1.0\n\n"); - for(;;) { - len = BIO_read(sbio, tmpbuf, 1024); - if(len <= 0) break; - BIO_write(out, tmpbuf, len); + for ( ; ; ) { + len = BIO_read(sbio, tmpbuf, 1024); + if (len <= 0) + break; + BIO_write(out, tmpbuf, len); } BIO_free_all(sbio); BIO_free(out); @@ -206,106 +198,83 @@ a client and also echoes the request to standard output. SSL_CTX *ctx; SSL *ssl; - ERR_load_crypto_strings(); - ERR_load_SSL_strings(); - OpenSSL_add_all_algorithms(); - - /* Might seed PRNG here */ - - ctx = SSL_CTX_new(SSLv23_server_method()); - - if (!SSL_CTX_use_certificate_file(ctx,"server.pem",SSL_FILETYPE_PEM) - || !SSL_CTX_use_PrivateKey_file(ctx,"server.pem",SSL_FILETYPE_PEM) - || !SSL_CTX_check_private_key(ctx)) { + /* XXX Seed the PRNG if needed. */ - fprintf(stderr, "Error setting up SSL_CTX\n"); - ERR_print_errors_fp(stderr); - return 0; + ctx = SSL_CTX_new(TLS_server_method()); + if (!SSL_CTX_use_certificate_file(ctx, "server.pem", SSL_FILETYPE_PEM) + || !SSL_CTX_use_PrivateKey_file(ctx, "server.pem", SSL_FILETYPE_PEM) + || !SSL_CTX_check_private_key(ctx)) { + fprintf(stderr, "Error setting up SSL_CTX\n"); + ERR_print_errors_fp(stderr); + exit(1); } - /* Might do other things here like setting verify locations and - * DH and/or RSA temporary key callbacks - */ + /* XXX Other things like set verify locations, EDH temp callbacks. */ /* New SSL BIO setup as server */ - sbio=BIO_new_ssl(ctx,0); - + sbio = BIO_new_ssl(ctx, 0); BIO_get_ssl(sbio, &ssl); - - if(!ssl) { - fprintf(stderr, "Can't locate SSL pointer\n"); - /* whatever ... */ + if (ssl == NULL) { + fprintf(stderr, "Can't locate SSL pointer\n"); + ERR_print_errors_fp(stderr); + exit(1); } - /* Don't want any retries */ SSL_set_mode(ssl, SSL_MODE_AUTO_RETRY); - - /* Create the buffering BIO */ - bbio = BIO_new(BIO_f_buffer()); - - /* Add to chain */ sbio = BIO_push(bbio, sbio); + acpt = BIO_new_accept("4433"); - acpt=BIO_new_accept("4433"); - - /* By doing this when a new connection is established + /* + * By doing this when a new connection is established * we automatically have sbio inserted into it. The * BIO chain is now 'swallowed' by the accept BIO and - * will be freed when the accept BIO is freed. + * will be freed when the accept BIO is freed. */ - - BIO_set_accept_bios(acpt,sbio); - + BIO_set_accept_bios(acpt, sbio); out = BIO_new_fp(stdout, BIO_NOCLOSE); /* Setup accept BIO */ - if(BIO_do_accept(acpt) <= 0) { - fprintf(stderr, "Error setting up accept BIO\n"); - ERR_print_errors_fp(stderr); - return 0; + if (BIO_do_accept(acpt) <= 0) { + fprintf(stderr, "Error setting up accept BIO\n"); + ERR_print_errors_fp(stderr); + exit(1); } - /* Now wait for incoming connection */ - if(BIO_do_accept(acpt) <= 0) { - fprintf(stderr, "Error in connection\n"); - ERR_print_errors_fp(stderr); - return 0; + if (BIO_do_accept(acpt) <= 0) { + fprintf(stderr, "Error in connection\n"); + ERR_print_errors_fp(stderr); + exit(1); } - /* We only want one connection so remove and free - * accept BIO - */ - + /* We only want one connection so remove and free accept BIO */ sbio = BIO_pop(acpt); - BIO_free_all(acpt); - if(BIO_do_handshake(sbio) <= 0) { - fprintf(stderr, "Error in SSL handshake\n"); - ERR_print_errors_fp(stderr); - return 0; + if (BIO_do_handshake(sbio) <= 0) { + fprintf(stderr, "Error in SSL handshake\n"); + ERR_print_errors_fp(stderr); + exit(1); } BIO_puts(sbio, "HTTP/1.0 200 OK\r\nContent-type: text/plain\r\n\r\n"); BIO_puts(sbio, "\r\nConnection Established\r\nRequest headers:\r\n"); BIO_puts(sbio, "--------------------------------------------------\r\n"); - for(;;) { - len = BIO_gets(sbio, tmpbuf, 1024); - if(len <= 0) break; - BIO_write(sbio, tmpbuf, len); - BIO_write(out, tmpbuf, len); - /* Look for blank line signifying end of headers*/ - if((tmpbuf[0] == '\r') || (tmpbuf[0] == '\n')) break; + for ( ; ; ) { + len = BIO_gets(sbio, tmpbuf, 1024); + if (len <= 0) + break; + BIO_write(sbio, tmpbuf, len); + BIO_write(out, tmpbuf, len); + /* Look for blank line signifying end of headers*/ + if (tmpbuf[0] == '\r' || tmpbuf[0] == '\n') + break; } BIO_puts(sbio, "--------------------------------------------------\r\n"); BIO_puts(sbio, "\r\n"); - - /* Since there is a buffering BIO present we had better flush it */ BIO_flush(sbio); - BIO_free_all(sbio); =head1 BUGS @@ -317,6 +286,13 @@ explicitly being popped (e.g. a pop higher up the chain). Applications which included workarounds for this bug (e.g. freeing BIOs more than once) should be modified to handle this fix or they may free up an already freed BIO. -=head1 SEE ALSO +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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>. -TBA +=cut diff --git a/deps/openssl/openssl/doc/crypto/BIO_find_type.pod b/deps/openssl/openssl/doc/crypto/BIO_find_type.pod index 2595200327..ff7b488609 100644 --- a/deps/openssl/openssl/doc/crypto/BIO_find_type.pod +++ b/deps/openssl/openssl/doc/crypto/BIO_find_type.pod @@ -8,46 +8,23 @@ BIO_find_type, BIO_next, BIO_method_type - BIO chain traversal #include <openssl/bio.h> - BIO * BIO_find_type(BIO *b,int bio_type); - BIO * BIO_next(BIO *b); - - #define BIO_method_type(b) ((b)->method->type) - - #define BIO_TYPE_NONE 0 - #define BIO_TYPE_MEM (1|0x0400) - #define BIO_TYPE_FILE (2|0x0400) - - #define BIO_TYPE_FD (4|0x0400|0x0100) - #define BIO_TYPE_SOCKET (5|0x0400|0x0100) - #define BIO_TYPE_NULL (6|0x0400) - #define BIO_TYPE_SSL (7|0x0200) - #define BIO_TYPE_MD (8|0x0200) - #define BIO_TYPE_BUFFER (9|0x0200) - #define BIO_TYPE_CIPHER (10|0x0200) - #define BIO_TYPE_BASE64 (11|0x0200) - #define BIO_TYPE_CONNECT (12|0x0400|0x0100) - #define BIO_TYPE_ACCEPT (13|0x0400|0x0100) - #define BIO_TYPE_PROXY_CLIENT (14|0x0200) - #define BIO_TYPE_PROXY_SERVER (15|0x0200) - #define BIO_TYPE_NBIO_TEST (16|0x0200) - #define BIO_TYPE_NULL_FILTER (17|0x0200) - #define BIO_TYPE_BER (18|0x0200) - #define BIO_TYPE_BIO (19|0x0400) - - #define BIO_TYPE_DESCRIPTOR 0x0100 - #define BIO_TYPE_FILTER 0x0200 - #define BIO_TYPE_SOURCE_SINK 0x0400 + BIO *BIO_find_type(BIO *b, int bio_type); + BIO *BIO_next(BIO *b); + int BIO_method_type(const BIO *b); =head1 DESCRIPTION The BIO_find_type() searches for a BIO of a given type in a chain, starting -at BIO B<b>. If B<type> is a specific type (such as BIO_TYPE_MEM) then a search +at BIO B<b>. If B<type> is a specific type (such as B<BIO_TYPE_MEM>) then a search is made for a BIO of that type. If B<type> is a general type (such as B<BIO_TYPE_SOURCE_SINK>) then the next matching BIO of the given general type is searched for. BIO_find_type() returns the next matching BIO or NULL if none is found. -Note: not all the B<BIO_TYPE_*> types above have corresponding BIO implementations. +The following general types are defined: +B<BIO_TYPE_DESCRIPTOR>, B<BIO_TYPE_FILTER>, and B<BIO_TYPE_SOURCE_SINK>. + +For a list of the specific types, see the B<openssl/bio.h> header file. BIO_next() returns the next BIO in a chain. It can be used to traverse all BIOs in a chain or used in conjunction with BIO_find_type() to find all BIOs of a @@ -63,36 +40,30 @@ BIO_next() returns the next BIO in a chain. BIO_method_type() returns the type of the BIO B<b>. -=head1 NOTES - -BIO_next() was added to OpenSSL 0.9.6 to provide a 'clean' way to traverse a BIO -chain or find multiple matches using BIO_find_type(). Previous versions had to -use: - - next = bio->next_bio; - -=head1 BUGS - -BIO_find_type() in OpenSSL 0.9.5a and earlier could not be safely passed a -NULL pointer for the B<b> argument. - =head1 EXAMPLE Traverse a chain looking for digest BIOs: BIO *btmp; - btmp = in_bio; /* in_bio is chain to search through */ + btmp = in_bio; /* in_bio is chain to search through */ do { - btmp = BIO_find_type(btmp, BIO_TYPE_MD); - if(btmp == NULL) break; /* Not found */ - /* btmp is a digest BIO, do something with it ...*/ - ... + btmp = BIO_find_type(btmp, BIO_TYPE_MD); + if (btmp == NULL) break; /* Not found */ + /* btmp is a digest BIO, do something with it ...*/ + ... + + btmp = BIO_next(btmp); + } while (btmp); + - btmp = BIO_next(btmp); - } while(btmp); +=head1 COPYRIGHT +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. -=head1 SEE ALSO +Licensed under the OpenSSL license (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>. -TBA +=cut diff --git a/deps/openssl/openssl/doc/crypto/BIO_get_data.pod b/deps/openssl/openssl/doc/crypto/BIO_get_data.pod new file mode 100644 index 0000000000..c3137c4c55 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/BIO_get_data.pod @@ -0,0 +1,65 @@ +=pod + +=head1 NAME + +BIO_set_data, BIO_get_data, BIO_set_init, BIO_get_init, BIO_set_shutdown, +BIO_get_shutdown - functions for managing BIO state information + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + void BIO_set_data(BIO *a, void *ptr); + void *BIO_get_data(BIO *a); + void BIO_set_init(BIO *a, int init); + int BIO_get_init(BIO *a); + void BIO_set_shutdown(BIO *a, int shut); + int BIO_get_shutdown(BIO *a); + +=head1 DESCRIPTION + +These functions are mainly useful when implementing a custom BIO. + +The BIO_set_data() function associates the custom data pointed to by B<ptr> with +the BIO. This data can subsequently be retrieved via a call to BIO_get_data(). +This can be used by custom BIOs for storing implementation specific information. + +The BIO_set_init() function sets the value of the BIO's "init" flag to indicate +whether initialisation has been completed for this BIO or not. A non-zero value +indicates that initialisation is complete, whilst zero indicates that it is not. +Often initialisation will complete during initial construction of the BIO. For +some BIOs however, initialisation may not complete until after additional steps +have occurred (for example through calling custom ctrls). The BIO_get_init() +function returns the value of the "init" flag. + +The BIO_set_shutdown() and BIO_get_shutdown() functions set and get the state of +this BIO's shutdown (i.e. BIO_CLOSE) flag. If set then the underlying resource +is also closed when the BIO is freed. + +=head1 RETURN VALUES + +BIO_get_data() returns a pointer to the implementation specific custom data +associated with this BIO, or NULL if none has been set. + +BIO_get_init() returns the state of the BIO's init flag. + +BIO_get_shutdown() returns the stat of the BIO's shutdown (i.e. BIO_CLOSE) flag. + +=head1 SEE ALSO + +L<bio>, L<BIO_meth_new> + +=head1 HISTORY + +The functions described here were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BIO_get_ex_new_index.pod b/deps/openssl/openssl/doc/crypto/BIO_get_ex_new_index.pod new file mode 100644 index 0000000000..9cf20c27f3 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/BIO_get_ex_new_index.pod @@ -0,0 +1,64 @@ +=pod + +=head1 NAME + +BIO_get_ex_new_index, BIO_set_ex_data, BIO_get_ex_data, +ENGINE_get_ex_new_index, ENGINE_set_ex_data, ENGINE_get_ex_data, +UI_get_ex_new_index, UI_set_ex_data, UI_get_ex_data, +X509_get_ex_new_index, X509_set_ex_data, X509_get_ex_data, +X509_STORE_get_ex_new_index, X509_STORE_set_ex_data, X509_STORE_get_ex_data, +X509_STORE_CTX_get_ex_new_index, X509_STORE_CTX_set_ex_data, X509_STORE_CTX_get_ex_data, +DH_get_ex_new_index, DH_set_ex_data, DH_get_ex_data, +DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data, +ECDH_get_ex_new_index, ECDH_set_ex_data, ECDH_get_ex_data, +EC_KEY_get_ex_new_index, EC_KEY_set_ex_data, EC_KEY_get_ex_data, +RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data +- application-specific data + +=for comment generic + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + int TYPE_get_ex_new_index(long argl, void *argp, + CRYPTO_EX_new *new_func, + CRYPTO_EX_dup *dup_func, + CRYPTO_EX_free *free_func); + + int TYPE_set_ex_data(TYPE *d, int idx, void *arg); + + void *TYPE_get_ex_data(TYPE *d, int idx); + +=head1 DESCRIPTION + +In the description here, I<TYPE> is used a placeholder +for any of the OpenSSL datatypes listed in +L<CRYPTO_get_ex_new_index(3)>. + +These functions handle application-specific data for OpenSSL data +structures. + +TYPE_get_new_ex_index() is a macro that calls CRYPTO_get_ex_new_index() +with the correct B<index> value. + +TYPE_set_ex_data() is a function that calls CRYPTO_set_ex_data() with +an offset into the opaque exdata part of the TYPE object. + +TYPE_get_ex_data() is a function that calls CRYPTO_get_ex_data() with an +an offset into the opaque exdata part of the TYPE object. + +=head1 SEE ALSO + +L<CRYPTO_get_ex_new_index(3)>. + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BIO_meth_new.pod b/deps/openssl/openssl/doc/crypto/BIO_meth_new.pod new file mode 100644 index 0000000000..f682c37d17 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/BIO_meth_new.pod @@ -0,0 +1,131 @@ +=pod + +=head1 NAME + +BIO_get_new_index, +BIO_meth_new, BIO_meth_free, BIO_meth_get_write, BIO_meth_set_write, +BIO_meth_get_read, BIO_meth_set_read, BIO_meth_get_puts, BIO_meth_set_puts, +BIO_meth_get_gets, BIO_meth_set_gets, BIO_meth_get_ctrl, BIO_meth_set_ctrl, +BIO_meth_get_create, BIO_meth_set_create, BIO_meth_get_destroy, +BIO_meth_set_destroy, BIO_meth_get_callback_ctrl, +BIO_meth_set_callback_ctrl - Routines to build up BIO methods + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + int BIO_get_new_index(void); + BIO_METHOD *BIO_meth_new(int type, const char *name); + void BIO_meth_free(BIO_METHOD *biom); + int (*BIO_meth_get_write(BIO_METHOD *biom)) (BIO *, const char *, int); + int BIO_meth_set_write(BIO_METHOD *biom, + int (*write) (BIO *, const char *, int)); + int (*BIO_meth_get_read(BIO_METHOD *biom)) (BIO *, char *, int); + int BIO_meth_set_read(BIO_METHOD *biom, + int (*read) (BIO *, char *, int)); + int (*BIO_meth_get_puts(BIO_METHOD *biom)) (BIO *, const char *); + int BIO_meth_set_puts(BIO_METHOD *biom, + int (*puts) (BIO *, const char *)); + int (*BIO_meth_get_gets(BIO_METHOD *biom)) (BIO *, char *, int); + int BIO_meth_set_gets(BIO_METHOD *biom, + int (*gets) (BIO *, char *, int)); + long (*BIO_meth_get_ctrl(BIO_METHOD *biom)) (BIO *, int, long, void *); + int BIO_meth_set_ctrl(BIO_METHOD *biom, + long (*ctrl) (BIO *, int, long, void *)); + int (*BIO_meth_get_create(BIO_METHOD *bion)) (BIO *); + int BIO_meth_set_create(BIO_METHOD *biom, int (*create) (BIO *)); + int (*BIO_meth_get_destroy(BIO_METHOD *biom)) (BIO *); + int BIO_meth_set_destroy(BIO_METHOD *biom, int (*destroy) (BIO *)); + long (*BIO_meth_get_callback_ctrl(BIO_METHOD *biom)) + (BIO *, int, BIO_info_cb *); + int BIO_meth_set_callback_ctrl(BIO_METHOD *biom, + long (*callback_ctrl) (BIO *, int, + BIO_info_cb *)); + +=head1 DESCRIPTION + +The B<BIO_METHOD> type is a structure used for the implementation of new BIO +types. It provides a set of of functions used by OpenSSL for the implementation +of the various BIO capabilities. See the L<bio> page for more information. + +BIO_meth_new() creates a new B<BIO_METHOD> structure. It should be given a +unique integer B<type> and a string that represents its B<name>. +Use BIO_get_new_index() to get the value for B<type>. + +The set of +standard OpenSSL provided BIO types is provided in B<bio.h>. Some examples +include B<BIO_TYPE_BUFFER> and B<BIO_TYPE_CIPHER>. Filter BIOs should have a +type which have the "filter" bit set (B<BIO_TYPE_FILTER>). Source/sink BIOs +should have the "source/sink" bit set (B<BIO_TYPE_SOURCE_SINK>). File descriptor +based BIOs (e.g. socket, fd, connect, accept etc) should additionally have the +"descriptor" bit set (B<BIO_TYPE_DESCRIPTOR>). See the L<BIO_find_type> page for +more information. + +BIO_meth_free() destroys a B<BIO_METHOD> structure and frees up any memory +associated with it. + +BIO_meth_get_write() and BIO_meth_set_write() get and set the function used for +writing arbitrary length data to the BIO respectively. This function will be +called in response to the application calling BIO_write(). The parameters for +the function have the same meaning as for BIO_write(). + +BIO_meth_get_read() and BIO_meth_set_read() get and set the function used for +reading arbitrary length data from the BIO respectively. This function will be +called in response to the application calling BIO_read(). The parameters for the +function have the same meaning as for BIO_read(). + +BIO_meth_get_puts() and BIO_meth_set_puts() get and set the function used for +writing a NULL terminated string to the BIO respectively. This function will be +called in response to the application calling BIO_puts(). The parameters for +the function have the same meaning as for BIO_puts(). + +BIO_meth_get_gets() and BIO_meth_set_gets() get and set the function typically +used for reading a line of data from the BIO respectively (see the L<BIO_gets(3)> +page for more information). This function will be called in response to the +application calling BIO_gets(). The parameters for the function have the same +meaning as for BIO_gets(). + +BIO_meth_get_ctrl() and BIO_meth_set_ctrl() get and set the function used for +processing ctrl messages in the BIO respectively. See the L<BIO_ctrl> page for +more information. This function will be called in response to the application +calling BIO_ctrl(). The parameters for the function have the same meaning as for +BIO_ctrl(). + +BIO_meth_get_create() and BIO_meth_set_create() get and set the function used +for creating a new instance of the BIO respectively. This function will be +called in response to the application calling BIO_new() and passing +in a pointer to the current BIO_METHOD. The BIO_new() function will allocate the +memory for the new BIO, and a pointer to this newly allocated structure will +be passed as a parameter to the function. + +BIO_meth_get_destroy() and BIO_meth_set_destroy() get and set the function used +for destroying an instance of a BIO respectively. This function will be +called in response to the application calling BIO_free(). A pointer to the BIO +to be destroyed is passed as a parameter. The destroy function should be used +for BIO specific clean up. The memory for the BIO itself should not be freed by +this function. + +BIO_meth_get_callback_ctrl() and BIO_meth_set_callback_ctrl() get and set the +function used for processing callback ctrl messages in the BIO respectively. See +the L<BIO_callback_ctrl(3)> page for more information. This function will be called +in response to the application calling BIO_callback_ctrl(). The parameters for +the function have the same meaning as for BIO_callback_ctrl(). + +=head1 SEE ALSO + +L<bio>, L<BIO_find_type>, L<BIO_ctrl>, L<BIO_read>, L<BIO_new> + +=head1 HISTORY + +The functions described here were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BIO_new.pod b/deps/openssl/openssl/doc/crypto/BIO_new.pod index 2a245fc8de..006cf5925c 100644 --- a/deps/openssl/openssl/doc/crypto/BIO_new.pod +++ b/deps/openssl/openssl/doc/crypto/BIO_new.pod @@ -2,57 +2,57 @@ =head1 NAME -BIO_new, BIO_set, BIO_free, BIO_vfree, BIO_free_all - BIO allocation and freeing functions +BIO_new, BIO_up_ref, BIO_free, BIO_vfree, BIO_free_all, +BIO_set - BIO allocation and freeing functions =head1 SYNOPSIS #include <openssl/bio.h> - BIO * BIO_new(BIO_METHOD *type); - int BIO_set(BIO *a,BIO_METHOD *type); - int BIO_free(BIO *a); - void BIO_vfree(BIO *a); - void BIO_free_all(BIO *a); + BIO * BIO_new(const BIO_METHOD *type); + int BIO_set(BIO *a, const BIO_METHOD *type); + int BIO_up_ref(BIO *a); + int BIO_free(BIO *a); + void BIO_vfree(BIO *a); + void BIO_free_all(BIO *a); =head1 DESCRIPTION The BIO_new() function returns a new BIO using method B<type>. -BIO_set() sets the method of an already existing BIO. +BIO_up_ref() increments the reference count associated with the BIO object. BIO_free() frees up a single BIO, BIO_vfree() also frees up a single BIO -but it does not return a value. Calling BIO_free() may also have some effect +but it does not return a value. +If B<a> is NULL nothing is done. +Calling BIO_free() may also have some effect on the underlying I/O structure, for example it may close the file being referred to under certain circumstances. For more details see the individual BIO_METHOD descriptions. BIO_free_all() frees up an entire BIO chain, it does not halt if an error occurs freeing up an individual BIO in the chain. +If B<a> is NULL nothing is done. =head1 RETURN VALUES BIO_new() returns a newly created BIO or NULL if the call fails. -BIO_set(), BIO_free() return 1 for success and 0 for failure. +BIO_set(), BIO_up_ref() and BIO_free() return 1 for success and 0 for failure. BIO_free_all() and BIO_vfree() do not return values. =head1 NOTES -Some BIOs (such as memory BIOs) can be used immediately after calling -BIO_new(). Others (such as file BIOs) need some additional initialization, -and frequently a utility function exists to create and initialize such BIOs. - If BIO_free() is called on a BIO chain it will only free one BIO resulting in a memory leak. -Calling BIO_free_all() a single BIO has the same effect as calling BIO_free() +Calling BIO_free_all() on a single BIO has the same effect as calling BIO_free() on it other than the discarded return value. -Normally the B<type> argument is supplied by a function which returns a -pointer to a BIO_METHOD. There is a naming convention for such functions: -a source/sink BIO is normally called BIO_s_*() and a filter BIO -BIO_f_*(); +=head1 HISTORY + +BIO_set() was removed in OpenSSL 1.1.0 as BIO type is now opaque. =head1 EXAMPLE @@ -60,6 +60,13 @@ Create a memory BIO: BIO *mem = BIO_new(BIO_s_mem()); -=head1 SEE ALSO +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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>. -TBA +=cut diff --git a/deps/openssl/openssl/doc/crypto/BIO_new_CMS.pod b/deps/openssl/openssl/doc/crypto/BIO_new_CMS.pod index 9e3a4b7f89..b06c224f71 100644 --- a/deps/openssl/openssl/doc/crypto/BIO_new_CMS.pod +++ b/deps/openssl/openssl/doc/crypto/BIO_new_CMS.pod @@ -2,7 +2,7 @@ =head1 NAME - BIO_new_CMS - CMS streaming filter BIO +BIO_new_CMS - CMS streaming filter BIO =head1 SYNOPSIS @@ -56,11 +56,20 @@ occurred. The error can be obtained from ERR_get_error(3). =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>, -L<CMS_encrypt(3)|CMS_encrypt(3)> +L<ERR_get_error(3)>, L<CMS_sign(3)>, +L<CMS_encrypt(3)> =head1 HISTORY BIO_new_CMS() was added to OpenSSL 1.0.0 +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BIO_parse_hostserv.pod b/deps/openssl/openssl/doc/crypto/BIO_parse_hostserv.pod new file mode 100644 index 0000000000..426e4de999 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/BIO_parse_hostserv.pod @@ -0,0 +1,74 @@ +=pod + +=head1 NAME + +BIO_hostserv_priorities, +BIO_parse_hostserv +- utility routines to parse a standard host and service string + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + enum BIO_hostserv_priorities { + BIO_PARSE_PRIO_HOST, BIO_PARSE_PRIO_SERV + }; + int BIO_parse_hostserv(const char *hostserv, char **host, char **service, + enum BIO_hostserv_priorities hostserv_prio); + +=head1 DESCRIPTION + +BIO_parse_hostserv() will parse the information given in B<hostserv>, +create strings with the host name and service name and give those +back via B<host> and B<service>. Those will need to be freed after +they are used. B<hostserv_prio> helps determine if B<hostserv> shall +be interpreted primarily as a host name or a service name in ambiguous +cases. + +The syntax the BIO_parse_hostserv() recognises is: + + host + ':' + service + host + ':' + '*' + host + ':' + ':' + service + '*' + ':' + service + host + service + +The host part can be a name or an IP address. If it's a IPv6 +address, it MUST be enclosed in brackets, such as '[::1]'. + +The service part can be a service name or its port number. + +The returned values will depend on the given B<hostserv> string +and B<hostserv_prio>, as follows: + + host + ':' + service => *host = "host", *service = "service" + host + ':' + '*' => *host = "host", *service = NULL + host + ':' => *host = "host", *service = NULL + ':' + service => *host = NULL, *service = "service" + '*' + ':' + service => *host = NULL, *service = "service" + + in case no ':' is present in the string, the result depends on + hostserv_prio, as follows: + + when hostserv_prio == BIO_PARSE_PRIO_HOST + host => *host = "host", *service untouched + + when hostserv_prio == BIO_PARSE_PRIO_SERV + service => *host untouched, *service = "service" + +=head1 SEE ALSO + +L<BIO_ADDRINFO(3)> + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BIO_printf.pod b/deps/openssl/openssl/doc/crypto/BIO_printf.pod new file mode 100644 index 0000000000..8045b645cb --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/BIO_printf.pod @@ -0,0 +1,50 @@ +=pod + +=head1 NAME + +BIO_printf, BIO_vprintf, BIO_snprintf, BIO_vsnprintf +- formatted output to a BIO + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + int BIO_printf(BIO *bio, const char *format, ...) + int BIO_vprintf(BIO *bio, const char *format, va_list args) + + int BIO_snprintf(char *buf, size_t n, const char *format, ...) + int BIO_vsnprintf(char *buf, size_t n, const char *format, va_list args) + +=head1 DESCRIPTION + +BIO_printf() is similar to the standard C printf() function, except that +the output is sent to the specified BIO, B<bio>, rather than standard +output. All common format specifiers are supported. + +BIO_vprintf() is similar to the vprintf() function found on many platforms, +the output is sent to the specified BIO, B<bio>, rather than standard +output. All common format specifiers are supported. The argument +list B<args> is a stdarg argument list. + +BIO_snprintf() is for platforms that do not have the common snprintf() +function. It is like sprintf() except that the size parameter, B<n>, +specifies the size of the output buffer. + +BIO_vsnprintf() is to BIO_snprintf() as BIO_vprintf() is to BIO_printf(). + +=head1 RETURN VALUES + +All functions return the number of bytes written, or -1 on error. +For BIO_snprintf() and BIO_vsnprintf() this includes when the output +buffer is too small. + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BIO_push.pod b/deps/openssl/openssl/doc/crypto/BIO_push.pod index 8a2657cd58..ce56db9836 100644 --- a/deps/openssl/openssl/doc/crypto/BIO_push.pod +++ b/deps/openssl/openssl/doc/crypto/BIO_push.pod @@ -2,14 +2,15 @@ =head1 NAME -BIO_push, BIO_pop - add and remove BIOs from a chain. +BIO_push, BIO_pop, BIO_set_next - add and remove BIOs from a chain =head1 SYNOPSIS #include <openssl/bio.h> - BIO * BIO_push(BIO *b,BIO *append); - BIO * BIO_pop(BIO *b); + BIO *BIO_push(BIO *b, BIO *append); + BIO *BIO_pop(BIO *b); + void BIO_set_next(BIO *b, BIO *next); =head1 DESCRIPTION @@ -21,6 +22,10 @@ in the chain, or NULL if there is no next BIO. The removed BIO then becomes a single BIO with no association with the original chain, it can thus be freed or attached to a different chain. +BIO_set_next() replaces the existing next BIO in a chain with the BIO pointed to +by B<next>. The new chain may include some of the same BIOs from the old chain +or it may be completely different. + =head1 NOTES The names of these functions are perhaps a little misleading. BIO_push() @@ -66,4 +71,19 @@ BIO. =head1 SEE ALSO -TBA +L<bio> + +=head1 HISTORY + +The BIO_set_next() function was added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BIO_read.pod b/deps/openssl/openssl/doc/crypto/BIO_read.pod index 2c177f0b6d..45871c1be9 100644 --- a/deps/openssl/openssl/doc/crypto/BIO_read.pod +++ b/deps/openssl/openssl/doc/crypto/BIO_read.pod @@ -8,10 +8,10 @@ BIO_read, BIO_write, BIO_gets, BIO_puts - BIO I/O functions #include <openssl/bio.h> - int BIO_read(BIO *b, void *buf, int len); - int BIO_gets(BIO *b, char *buf, int size); - int BIO_write(BIO *b, const void *buf, int len); - int BIO_puts(BIO *b, const char *buf); + int BIO_read(BIO *b, void *buf, int len); + int BIO_gets(BIO *b, char *buf, int size); + int BIO_write(BIO *b, const void *buf, int len); + int BIO_puts(BIO *b, const char *buf); =head1 DESCRIPTION @@ -20,20 +20,22 @@ the data in B<buf>. BIO_gets() performs the BIOs "gets" operation and places the data in B<buf>. Usually this operation will attempt to read a line of data -from the BIO of maximum length B<len>. There are exceptions to this -however, for example BIO_gets() on a digest BIO will calculate and +from the BIO of maximum length B<len-1>. There are exceptions to this, +however; for example, BIO_gets() on a digest BIO will calculate and return the digest and other BIOs may not support BIO_gets() at all. +The returned string is always NUL-terminated. BIO_write() attempts to write B<len> bytes from B<buf> to BIO B<b>. -BIO_puts() attempts to write a null terminated string B<buf> to BIO B<b>. +BIO_puts() attempts to write a NUL-terminated string B<buf> to BIO B<b>. =head1 RETURN VALUES All these functions return either the amount of data successfully read or written (if the return value is positive) or that no data was successfully read or written if the result is 0 or -1. If the return value is -2 then -the operation is not implemented in the specific BIO type. +the operation is not implemented in the specific BIO type. The trailing +NUL is not included in the length returned by BIO_gets(). =head1 NOTES @@ -52,15 +54,24 @@ I/O structure and may block as a result. Instead select() (or equivalent) should be combined with non blocking I/O so successive reads will request a retry instead of blocking. -See L<BIO_should_retry(3)|BIO_should_retry(3)> for details of how to +See L<BIO_should_retry(3)> for details of how to determine the cause of a retry and other I/O issues. If the BIO_gets() function is not supported by a BIO then it possible to -work around this by adding a buffering BIO L<BIO_f_buffer(3)|BIO_f_buffer(3)> +work around this by adding a buffering BIO L<BIO_f_buffer(3)> to the chain. =head1 SEE ALSO -L<BIO_should_retry(3)|BIO_should_retry(3)> +L<BIO_should_retry(3)> -TBA +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BIO_s_accept.pod b/deps/openssl/openssl/doc/crypto/BIO_s_accept.pod index 560c1128ef..ce9995dc3f 100644 --- a/deps/openssl/openssl/doc/crypto/BIO_s_accept.pod +++ b/deps/openssl/openssl/doc/crypto/BIO_s_accept.pod @@ -2,17 +2,20 @@ =head1 NAME -BIO_s_accept, BIO_set_accept_port, BIO_get_accept_port, BIO_new_accept, -BIO_set_nbio_accept, BIO_set_accept_bios, BIO_set_bind_mode, -BIO_get_bind_mode, BIO_do_accept - accept BIO +BIO_s_accept, BIO_set_accept_name, BIO_set_accept_port, BIO_get_accept_name, +BIO_get_accept_port, BIO_new_accept, BIO_set_nbio_accept, BIO_set_accept_bios, +BIO_set_bind_mode, BIO_get_bind_mode, BIO_do_accept - accept BIO =head1 SYNOPSIS #include <openssl/bio.h> - BIO_METHOD *BIO_s_accept(void); + const BIO_METHOD *BIO_s_accept(void); - long BIO_set_accept_port(BIO *b, char *name); + long BIO_set_accept_name(BIO *b, char *name); + char *BIO_get_accept_name(BIO *b); + + long BIO_set_accept_port(BIO *b, char *port); char *BIO_get_accept_port(BIO *b); BIO *BIO_new_accept(char *host_port); @@ -21,11 +24,7 @@ BIO_get_bind_mode, BIO_do_accept - accept BIO long BIO_set_accept_bios(BIO *b, char *bio); long BIO_set_bind_mode(BIO *b, long mode); - long BIO_get_bind_mode(BIO *b, long dummy); - - #define BIO_BIND_NORMAL 0 - #define BIO_BIND_REUSEADDR_IF_UNUSED 1 - #define BIO_BIND_REUSEADDR 2 + long BIO_get_bind_mode(BIO *b); int BIO_do_accept(BIO *b); @@ -49,23 +48,30 @@ If the close flag is set on an accept BIO then any active connection on that chain is shutdown and the socket closed when the BIO is freed. -Calling BIO_reset() on a accept BIO will close any active +Calling BIO_reset() on an accept BIO will close any active connection and reset the BIO into a state where it awaits another incoming connection. BIO_get_fd() and BIO_set_fd() can be called to retrieve or set -the accept socket. See L<BIO_s_fd(3)|BIO_s_fd(3)> +the accept socket. See L<BIO_s_fd(3)> -BIO_set_accept_port() uses the string B<name> to set the accept -port. The port is represented as a string of the form "host:port", +BIO_set_accept_name() uses the string B<name> to set the accept +name. The name is represented as a string of the form "host:port", where "host" is the interface to use and "port" is the port. -The host can be can be "*" which is interpreted as meaning -any interface; "port" has the same syntax -as the port specified in BIO_set_conn_port() for connect BIOs, -that is it can be a numerical port string or a string to lookup -using getservbyname() and a string table. - -BIO_new_accept() combines BIO_new() and BIO_set_accept_port() into +The host can be "*" or empty which is interpreted as meaning +any interface. If the host is an IPv6 address, it has to be +enclosed in brackets, for example "[::1]:https". "port" has the +same syntax as the port specified in BIO_set_conn_port() for +connect BIOs, that is it can be a numerical port string or a +string to lookup using getservbyname() and a string table. + +BIO_set_accept_port() uses the string B<port> to set the accept +port. "port" has the same syntax as the port specified in +BIO_set_conn_port() for connect BIOs, that is it can be a numerical +port string or a string to lookup using getservbyname() and a string +table. + +BIO_new_accept() combines BIO_new() and BIO_set_accept_name() into a single call: that is it creates a new accept BIO with port B<host_port>. @@ -74,19 +80,19 @@ BIO_set_nbio_accept() sets the accept socket to blocking mode BIO_set_accept_bios() can be used to set a chain of BIOs which will be duplicated and prepended to the chain when an incoming -connection is received. This is useful if, for example, a +connection is received. This is useful if, for example, a buffering or SSL BIO is required for each connection. The chain of BIOs must not be freed after this call, they will be automatically freed when the accept BIO is freed. BIO_set_bind_mode() and BIO_get_bind_mode() set and retrieve -the current bind mode. If BIO_BIND_NORMAL (the default) is set +the current bind mode. If B<BIO_BIND_NORMAL> (the default) is set then another socket cannot be bound to the same port. If -BIO_BIND_REUSEADDR is set then other sockets can bind to the -same port. If BIO_BIND_REUSEADDR_IF_UNUSED is set then and +B<BIO_BIND_REUSEADDR> is set then other sockets can bind to the +same port. If B<BIO_BIND_REUSEADDR_IF_UNUSED> is set then and attempt is first made to use BIO_BIN_NORMAL, if this fails and the port is not in use then a second attempt is made -using BIO_BIND_REUSEADDR. +using B<BIO_BIND_REUSEADDR>. BIO_do_accept() serves two functions. When it is first called, after the accept BIO has been setup, it will attempt @@ -137,13 +143,24 @@ then it is an indication that an accept attempt would block: the application should take appropriate action to wait until the underlying socket has accepted a connection and retry the call. -BIO_set_accept_port(), BIO_get_accept_port(), BIO_set_nbio_accept(), -BIO_set_accept_bios(), BIO_set_bind_mode(), BIO_get_bind_mode() and -BIO_do_accept() are macros. +BIO_set_accept_name(), BIO_get_accept_name(), BIO_set_accept_port(), +BIO_get_accept_port(), BIO_set_nbio_accept(), BIO_set_accept_bios(), +BIO_set_bind_mode(), BIO_get_bind_mode() and BIO_do_accept() are macros. =head1 RETURN VALUES -TBA +BIO_do_accept(), +BIO_set_accept_name(), BIO_set_accept_port(), BIO_set_nbio_accept(), +BIO_set_accept_bios(), and BIO_set_bind_mode(), return 1 for success and 0 or +-1 for failure. + +BIO_get_accept_name() returns the accept name or NULL on error. + +BIO_get_accept_port() returns the port as a string or NULL on error. + +BIO_get_bind_mode() returns the set of B<BIO_BIND> flags, or -1 on failure. + +BIO_new_accept() returns a BIO or NULL on error. =head1 EXAMPLE @@ -151,34 +168,36 @@ This example accepts two connections on port 4444, sends messages down each and finally closes both down. BIO *abio, *cbio, *cbio2; - ERR_load_crypto_strings(); - abio = BIO_new_accept("4444"); /* First call to BIO_accept() sets up accept BIO */ - if(BIO_do_accept(abio) <= 0) { - fprintf(stderr, "Error setting up accept\n"); - ERR_print_errors_fp(stderr); - exit(0); + abio = BIO_new_accept("4444"); + if (BIO_do_accept(abio) <= 0) { + fprintf(stderr, "Error setting up accept\n"); + ERR_print_errors_fp(stderr); + exit(1); } /* Wait for incoming connection */ - if(BIO_do_accept(abio) <= 0) { - fprintf(stderr, "Error accepting connection\n"); - ERR_print_errors_fp(stderr); - exit(0); + if (BIO_do_accept(abio) <= 0) { + fprintf(stderr, "Error accepting connection\n"); + ERR_print_errors_fp(stderr); + exit(1); } fprintf(stderr, "Connection 1 established\n"); + /* Retrieve BIO for connection */ cbio = BIO_pop(abio); BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\n"); fprintf(stderr, "Sent out data on connection 1\n"); + /* Wait for another connection */ - if(BIO_do_accept(abio) <= 0) { - fprintf(stderr, "Error accepting connection\n"); - ERR_print_errors_fp(stderr); - exit(0); + if (BIO_do_accept(abio) <= 0) { + fprintf(stderr, "Error accepting connection\n"); + ERR_print_errors_fp(stderr); + exit(1); } fprintf(stderr, "Connection 2 established\n"); + /* Close accept BIO to refuse further connections */ cbio2 = BIO_pop(abio); BIO_free(abio); @@ -186,10 +205,18 @@ down each and finally closes both down. fprintf(stderr, "Sent out data on connection 2\n"); BIO_puts(cbio, "Connection 1: Second connection established\n"); + /* Close the two established connections */ BIO_free(cbio); BIO_free(cbio2); -=head1 SEE ALSO +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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>. -TBA +=cut diff --git a/deps/openssl/openssl/doc/crypto/BIO_s_bio.pod b/deps/openssl/openssl/doc/crypto/BIO_s_bio.pod index 9fe88b26b0..cb46546e21 100644 --- a/deps/openssl/openssl/doc/crypto/BIO_s_bio.pod +++ b/deps/openssl/openssl/doc/crypto/BIO_s_bio.pod @@ -2,7 +2,7 @@ =head1 NAME -BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr, +BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr, BIO_set_write_buf_size, BIO_get_write_buf_size, BIO_new_bio_pair, BIO_get_write_guarantee, BIO_ctrl_get_write_guarantee, BIO_get_read_request, BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO @@ -11,24 +11,22 @@ BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO #include <openssl/bio.h> - BIO_METHOD *BIO_s_bio(void); + const BIO_METHOD *BIO_s_bio(void); - #define BIO_make_bio_pair(b1,b2) (int)BIO_ctrl(b1,BIO_C_MAKE_BIO_PAIR,0,b2) - #define BIO_destroy_bio_pair(b) (int)BIO_ctrl(b,BIO_C_DESTROY_BIO_PAIR,0,NULL) + int BIO_make_bio_pair(BIO *b1, BIO *b2); + int BIO_destroy_bio_pair(BIO *b); + int BIO_shutdown_wr(BIO *b); - #define BIO_shutdown_wr(b) (int)BIO_ctrl(b, BIO_C_SHUTDOWN_WR, 0, NULL) - #define BIO_set_write_buf_size(b,size) (int)BIO_ctrl(b,BIO_C_SET_WRITE_BUF_SIZE,size,NULL) - #define BIO_get_write_buf_size(b,size) (size_t)BIO_ctrl(b,BIO_C_GET_WRITE_BUF_SIZE,size,NULL) + int BIO_set_write_buf_size(BIO *b, long size); + size_t BIO_get_write_buf_size(BIO *b, long size); int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2); - #define BIO_get_write_guarantee(b) (int)BIO_ctrl(b,BIO_C_GET_WRITE_GUARANTEE,0,NULL) + int BIO_get_write_guarantee(BIO *b); size_t BIO_ctrl_get_write_guarantee(BIO *b); - - #define BIO_get_read_request(b) (int)BIO_ctrl(b,BIO_C_GET_READ_REQUEST,0,NULL) + int BIO_get_read_request(BIO *b); size_t BIO_ctrl_get_read_request(BIO *b); - int BIO_ctrl_reset_read_request(BIO *b); =head1 DESCRIPTION @@ -65,7 +63,7 @@ up any half of the pair will automatically destroy the association. BIO_shutdown_wr() is used to close down a BIO B<b>. After this call no further writes on BIO B<b> are allowed (they will return an error). Reads on the other half of the pair will return any pending data or EOF when all pending data has -been read. +been read. BIO_set_write_buf_size() sets the write buffer size of BIO B<b> to B<size>. If the size is not initialized a default value is used. This is currently @@ -123,6 +121,11 @@ never sent! BIO_eof() is true if no data is in the peer BIO and the peer BIO has been shutdown. +BIO_make_bio_pair(), BIO_destroy_bio_pair(), BIO_shutdown_wr(), +BIO_set_write_buf_size(), BIO_get_write_buf_size(), +BIO_get_write_guarantee(), and BIO_get_read_request() are implemented +as macros. + =head1 RETURN VALUES BIO_new_bio_pair() returns 1 on success, with the new BIOs available in @@ -139,9 +142,9 @@ without having to go through the SSL-interface. BIO *internal_bio, *network_bio; ... - BIO_new_bio_pair(internal_bio, 0, network_bio, 0); + BIO_new_bio_pair(&internal_bio, 0, &network_bio, 0); SSL_set_bio(ssl, internal_bio, internal_bio); - SSL_operations(); + SSL_operations(); //e.g SSL_read and SSL_write ... application | TLS-engine @@ -150,12 +153,16 @@ without having to go through the SSL-interface. | /\ || | || \/ | BIO-pair (internal_bio) - +----------< BIO-pair (network_bio) + | BIO-pair (network_bio) + | || /\ + | \/ || + +-----------< BIO_operations() + | | | | - socket | + socket ... - SSL_free(ssl); /* implicitly frees internal_bio */ + SSL_free(ssl); /* implicitly frees internal_bio */ BIO_free(network_bio); ... @@ -165,13 +172,13 @@ buffer is full or the read buffer is drained. Then the application has to flush the write buffer and/or fill the read buffer. Use the BIO_ctrl_pending(), to find out whether data is buffered in the BIO -and must be transfered to the network. Use BIO_ctrl_get_read_request() to +and must be transferred to the network. Use BIO_ctrl_get_read_request() to find out, how many bytes must be written into the buffer before the SSL_operation() can successfully be continued. =head1 WARNING -As the data is buffered, SSL_operation() may return with a ERROR_SSL_WANT_READ +As the data is buffered, SSL_operation() may return with an ERROR_SSL_WANT_READ condition, but there is still data in the write buffer. An application must not rely on the error value of SSL_operation() but must assure that the write buffer is always flushed first. Otherwise a deadlock may occur as @@ -179,7 +186,16 @@ the peer might be waiting for the data before being able to continue. =head1 SEE ALSO -L<SSL_set_bio(3)|SSL_set_bio(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>, -L<BIO_should_retry(3)|BIO_should_retry(3)>, L<BIO_read(3)|BIO_read(3)> +L<SSL_set_bio(3)>, L<ssl(3)>, L<bio(3)>, +L<BIO_should_retry(3)>, L<BIO_read(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BIO_s_connect.pod b/deps/openssl/openssl/doc/crypto/BIO_s_connect.pod index 345a468a5d..2143acd099 100644 --- a/deps/openssl/openssl/doc/crypto/BIO_s_connect.pod +++ b/deps/openssl/openssl/doc/crypto/BIO_s_connect.pod @@ -2,27 +2,26 @@ =head1 NAME +BIO_set_conn_address, BIO_get_conn_address, BIO_s_connect, BIO_new_connect, BIO_set_conn_hostname, BIO_set_conn_port, -BIO_set_conn_ip, BIO_set_conn_int_port, BIO_get_conn_hostname, -BIO_get_conn_port, BIO_get_conn_ip, BIO_get_conn_int_port, +BIO_get_conn_hostname, +BIO_get_conn_port, BIO_set_nbio, BIO_do_connect - connect BIO =head1 SYNOPSIS #include <openssl/bio.h> - BIO_METHOD * BIO_s_connect(void); + const BIO_METHOD * BIO_s_connect(void); BIO *BIO_new_connect(char *name); long BIO_set_conn_hostname(BIO *b, char *name); long BIO_set_conn_port(BIO *b, char *port); - long BIO_set_conn_ip(BIO *b, char *ip); - long BIO_set_conn_int_port(BIO *b, char *port); - char *BIO_get_conn_hostname(BIO *b); - char *BIO_get_conn_port(BIO *b); - char *BIO_get_conn_ip(BIO *b); - long BIO_get_conn_int_port(BIO *b); + long BIO_set_conn_address(BIO *b, BIO_ADDR *addr); + const char *BIO_get_conn_hostname(BIO *b); + const char *BIO_get_conn_port(BIO *b); + const BIO_ADDR *BIO_get_conn_address(BIO *b); long BIO_set_nbio(BIO *b, long n); @@ -57,36 +56,33 @@ it also returns the socket . If B<c> is not NULL it should be of type (int *). BIO_set_conn_hostname() uses the string B<name> to set the hostname. -The hostname can be an IP address. The hostname can also include the -port in the form hostname:port . It is also acceptable to use the -form "hostname/any/other/path" or "hostname:port/any/other/path". +The hostname can be an IP address; if the address is an IPv6 one, it +must be enclosed with brackets. The hostname can also include the +port in the form hostname:port. BIO_set_conn_port() sets the port to B<port>. B<port> can be the numerical form or a string such as "http". A string will be looked up first using getservbyname() on the host platform but if that -fails a standard table of port names will be used. Currently the -list is http, telnet, socks, https, ssl, ftp, gopher and wais. +fails a standard table of port names will be used. This internal +list is http, telnet, socks, https, ssl, ftp, and gopher. -BIO_set_conn_ip() sets the IP address to B<ip> using binary form, -that is four bytes specifying the IP address in big-endian form. - -BIO_set_conn_int_port() sets the port using B<port>. B<port> should -be of type (int *). +BIO_set_conn_address() sets the address and port information using +a BIO_ADDR(3ssl). BIO_get_conn_hostname() returns the hostname of the connect BIO or NULL if the BIO is initialized but no hostname is set. This return value is an internal pointer which should not be modified. BIO_get_conn_port() returns the port as a string. +This return value is an internal pointer which should not be modified. -BIO_get_conn_ip() returns the IP address in binary form. - -BIO_get_conn_int_port() returns the port as an int. +BIO_get_conn_address() returns the address information as a BIO_ADDR. +This return value is an internal pointer which should not be modified. BIO_set_nbio() sets the non blocking I/O flag to B<n>. If B<n> is zero then blocking I/O is set. If B<n> is 1 then non blocking I/O is set. Blocking I/O is the default. The call to BIO_set_nbio() -should be made before the connection is established because +should be made before the connection is established because non blocking I/O is set during the connect process. BIO_new_connect() combines BIO_new() and BIO_set_conn_hostname() into @@ -169,19 +165,20 @@ to retrieve a page and copy the result to standard output. BIO *cbio, *out; int len; char tmpbuf[1024]; - ERR_load_crypto_strings(); + cbio = BIO_new_connect("localhost:http"); out = BIO_new_fp(stdout, BIO_NOCLOSE); - if(BIO_do_connect(cbio) <= 0) { - fprintf(stderr, "Error connecting to server\n"); - ERR_print_errors_fp(stderr); - /* whatever ... */ - } + if (BIO_do_connect(cbio) <= 0) { + fprintf(stderr, "Error connecting to server\n"); + ERR_print_errors_fp(stderr); + exit(1); + } BIO_puts(cbio, "GET / HTTP/1.0\n\n"); - for(;;) { - len = BIO_read(cbio, tmpbuf, 1024); - if(len <= 0) break; - BIO_write(out, tmpbuf, len); + for ( ; ; ) { + len = BIO_read(cbio, tmpbuf, 1024); + if (len <= 0) + break; + BIO_write(out, tmpbuf, len); } BIO_free(cbio); BIO_free(out); @@ -189,4 +186,15 @@ to retrieve a page and copy the result to standard output. =head1 SEE ALSO -TBA +L<BIO_ADDR(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BIO_s_fd.pod b/deps/openssl/openssl/doc/crypto/BIO_s_fd.pod index b1de1d1015..79c4a5999f 100644 --- a/deps/openssl/openssl/doc/crypto/BIO_s_fd.pod +++ b/deps/openssl/openssl/doc/crypto/BIO_s_fd.pod @@ -8,10 +8,10 @@ BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd - file descriptor BIO #include <openssl/bio.h> - BIO_METHOD * BIO_s_fd(void); + const BIO_METHOD *BIO_s_fd(void); - #define BIO_set_fd(b,fd,c) BIO_int_ctrl(b,BIO_C_SET_FD,c,fd) - #define BIO_get_fd(b,c) BIO_ctrl(b,BIO_C_GET_FD,0,(char *)c) + int BIO_set_fd(BIO *b, int fd, int c); + int BIO_get_fd(BIO *b, int *c); BIO *BIO_new_fd(int fd, int close_flag); @@ -23,46 +23,43 @@ round the platforms file descriptor routines such as read() and write(). BIO_read() and BIO_write() read or write the underlying descriptor. BIO_puts() is supported but BIO_gets() is not. -If the close flag is set then then close() is called on the underlying +If the close flag is set then close() is called on the underlying file descriptor when the BIO is freed. BIO_reset() attempts to change the file pointer to the start of file -using lseek(fd, 0, 0). +such as by using B<lseek(fd, 0, 0)>. BIO_seek() sets the file pointer to position B<ofs> from start of file -using lseek(fd, ofs, 0). +such as by using B<lseek(fd, ofs, 0)>. -BIO_tell() returns the current file position by calling lseek(fd, 0, 1). +BIO_tell() returns the current file position such as by calling +B<lseek(fd, 0, 1)>. BIO_set_fd() sets the file descriptor of BIO B<b> to B<fd> and the close flag to B<c>. BIO_get_fd() places the file descriptor in B<c> if it is not NULL, it also -returns the file descriptor. If B<c> is not NULL it should be of type -(int *). +returns the file descriptor. BIO_new_fd() returns a file descriptor BIO using B<fd> and B<close_flag>. =head1 NOTES The behaviour of BIO_read() and BIO_write() depends on the behavior of the -platforms read() and write() calls on the descriptor. If the underlying +platforms read() and write() calls on the descriptor. If the underlying file descriptor is in a non blocking mode then the BIO will behave in the -manner described in the L<BIO_read(3)|BIO_read(3)> and L<BIO_should_retry(3)|BIO_should_retry(3)> +manner described in the L<BIO_read(3)> and L<BIO_should_retry(3)> manual pages. File descriptor BIOs should not be used for socket I/O. Use socket BIOs instead. +BIO_set_fd() and BIO_get_fd() are implemented as macros. + =head1 RETURN VALUES BIO_s_fd() returns the file descriptor BIO method. -BIO_reset() returns zero for success and -1 if an error occurred. -BIO_seek() and BIO_tell() return the current file position or -1 -is an error occurred. These values reflect the underlying lseek() -behaviour. - BIO_set_fd() always returns 1. BIO_get_fd() returns the file descriptor or -1 if the BIO has not @@ -76,14 +73,26 @@ occurred. This is a file descriptor BIO version of "Hello World": BIO *out; + out = BIO_new_fd(fileno(stdout), BIO_NOCLOSE); BIO_printf(out, "Hello World\n"); BIO_free(out); =head1 SEE ALSO -L<BIO_seek(3)|BIO_seek(3)>, L<BIO_tell(3)|BIO_tell(3)>, -L<BIO_reset(3)|BIO_reset(3)>, L<BIO_read(3)|BIO_read(3)>, -L<BIO_write(3)|BIO_write(3)>, L<BIO_puts(3)|BIO_puts(3)>, -L<BIO_gets(3)|BIO_gets(3)>, L<BIO_printf(3)|BIO_printf(3)>, -L<BIO_set_close(3)|BIO_set_close(3)>, L<BIO_get_close(3)|BIO_get_close(3)> +L<BIO_seek(3)>, L<BIO_tell(3)>, +L<BIO_reset(3)>, L<BIO_read(3)>, +L<BIO_write(3)>, L<BIO_puts(3)>, +L<BIO_gets(3)>, L<BIO_printf(3)>, +L<BIO_set_close(3)>, L<BIO_get_close(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BIO_s_file.pod b/deps/openssl/openssl/doc/crypto/BIO_s_file.pod index 188aea347d..e19d824290 100644 --- a/deps/openssl/openssl/doc/crypto/BIO_s_file.pod +++ b/deps/openssl/openssl/doc/crypto/BIO_s_file.pod @@ -10,12 +10,12 @@ BIO_rw_filename - FILE bio #include <openssl/bio.h> - BIO_METHOD * BIO_s_file(void); + const BIO_METHOD * BIO_s_file(void); BIO *BIO_new_file(const char *filename, const char *mode); BIO *BIO_new_fp(FILE *stream, int flags); - BIO_set_fp(BIO *b,FILE *fp, int flags); - BIO_get_fp(BIO *b,FILE **fpp); + BIO_set_fp(BIO *b, FILE *fp, int flags); + BIO_get_fp(BIO *b, FILE **fpp); int BIO_read_filename(BIO *b, char *name) int BIO_write_filename(BIO *b, char *name) @@ -92,15 +92,15 @@ Alternative technique: BIO *bio_out; bio_out = BIO_new(BIO_s_file()); - if(bio_out == NULL) /* Error ... */ - if(!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE)) /* Error ... */ + if (bio_out == NULL) /* Error ... */ + if (!BIO_set_fp(bio_out, stdout, BIO_NOCLOSE)) /* Error ... */ BIO_printf(bio_out, "Hello World\n"); Write to a file: BIO *out; out = BIO_new_file("filename.txt", "w"); - if(!out) /* Error occurred */ + if (!out) /* Error occurred */ BIO_printf(out, "Hello World\n"); BIO_free(out); @@ -108,8 +108,8 @@ Alternative technique: BIO *out; out = BIO_new(BIO_s_file()); - if(out == NULL) /* Error ... */ - if(!BIO_write_filename(out, "filename.txt")) /* Error ... */ + if (out == NULL) /* Error ... */ + if (!BIO_write_filename(out, "filename.txt")) /* Error ... */ BIO_printf(out, "Hello World\n"); BIO_free(out); @@ -128,7 +128,7 @@ BIO_seek() returns the same value as the underlying fseek() function: BIO_tell() returns the current file position. -BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and +BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and BIO_rw_filename() return 1 for success or 0 for failure. =head1 BUGS @@ -140,9 +140,20 @@ occurred this differs from other types of BIO which will typically return =head1 SEE ALSO -L<BIO_seek(3)|BIO_seek(3)>, L<BIO_tell(3)|BIO_tell(3)>, -L<BIO_reset(3)|BIO_reset(3)>, L<BIO_flush(3)|BIO_flush(3)>, -L<BIO_read(3)|BIO_read(3)>, -L<BIO_write(3)|BIO_write(3)>, L<BIO_puts(3)|BIO_puts(3)>, -L<BIO_gets(3)|BIO_gets(3)>, L<BIO_printf(3)|BIO_printf(3)>, -L<BIO_set_close(3)|BIO_set_close(3)>, L<BIO_get_close(3)|BIO_get_close(3)> +L<BIO_seek(3)>, L<BIO_tell(3)>, +L<BIO_reset(3)>, L<BIO_flush(3)>, +L<BIO_read(3)>, +L<BIO_write(3)>, L<BIO_puts(3)>, +L<BIO_gets(3)>, L<BIO_printf(3)>, +L<BIO_set_close(3)>, L<BIO_get_close(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BIO_s_mem.pod b/deps/openssl/openssl/doc/crypto/BIO_s_mem.pod index 7663d8bf5f..eb67cbe93b 100644 --- a/deps/openssl/openssl/doc/crypto/BIO_s_mem.pod +++ b/deps/openssl/openssl/doc/crypto/BIO_s_mem.pod @@ -2,6 +2,7 @@ =head1 NAME +BIO_s_secmem, BIO_s_mem, BIO_set_mem_eof_return, BIO_get_mem_data, BIO_set_mem_buf, BIO_get_mem_ptr, BIO_new_mem_buf - memory BIO @@ -9,23 +10,27 @@ BIO_get_mem_ptr, BIO_new_mem_buf - memory BIO #include <openssl/bio.h> - BIO_METHOD * BIO_s_mem(void); + const BIO_METHOD * BIO_s_mem(void); + const BIO_METHOD * BIO_s_secmem(void); - BIO_set_mem_eof_return(BIO *b,int v) + BIO_set_mem_eof_return(BIO *b, int v) long BIO_get_mem_data(BIO *b, char **pp) - BIO_set_mem_buf(BIO *b,BUF_MEM *bm,int c) - BIO_get_mem_ptr(BIO *b,BUF_MEM **pp) + BIO_set_mem_buf(BIO *b, BUF_MEM *bm, int c) + BIO_get_mem_ptr(BIO *b, BUF_MEM **pp) BIO *BIO_new_mem_buf(const void *buf, int len); =head1 DESCRIPTION -BIO_s_mem() return the memory BIO method function. +BIO_s_mem() return the memory BIO method function. A memory BIO is a source/sink BIO which uses memory for its I/O. Data written to a memory BIO is stored in a BUF_MEM structure which is extended as appropriate to accommodate the stored data. +BIO_s_secmem() is like BIO_s_mem() except that the secure heap is used +for buffer storage. + Any data written to a memory BIO can be recalled by reading from it. Unless the memory BIO is read only any data read from it is deleted from the BIO. @@ -35,9 +40,10 @@ Memory BIOs support BIO_gets() and BIO_puts(). If the BIO_CLOSE flag is set when a memory BIO is freed then the underlying BUF_MEM structure is also freed. -Calling BIO_reset() on a read write memory BIO clears any data in it. On a -read only BIO it restores the BIO to its original state and the read only -data can be read again. +Calling BIO_reset() on a read write memory BIO clears any data in it if the +flag BIO_FLAGS_NONCLEAR_RST is not set. On a read only BIO or if the flag +BIO_FLAGS_NONCLEAR_RST is set it restores the BIO to its original state and +the data can be read again. BIO_eof() is true if no data is in the BIO. @@ -79,22 +85,19 @@ read in small chunks the operation can be very slow. The use of a read only memory BIO avoids this problem. If the BIO must be read write then adding a buffering BIO to the chain will speed up the process. +Calling BIO_set_mem_buf() on a BIO created with BIO_new_secmem() will +give undefined results, including perhaps a program crash. + =head1 BUGS There should be an option to set the maximum size of a memory BIO. -There should be a way to "rewind" a read write BIO without destroying -its contents. - -The copying operation should not occur after every small read of a large BIO -to improve efficiency. - =head1 EXAMPLE Create a memory BIO and write some data to it: BIO *mem = BIO_new(BIO_s_mem()); - BIO_puts(mem, "Hello World\n"); + BIO_puts(mem, "Hello World\n"); Create a read only memory BIO: @@ -108,8 +111,14 @@ Extract the BUF_MEM structure from a memory BIO and then free up the BIO: BIO_get_mem_ptr(mem, &bptr); BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */ BIO_free(mem); - -=head1 SEE ALSO +=head1 COPYRIGHT + +Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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>. -TBA +=cut diff --git a/deps/openssl/openssl/doc/crypto/BIO_s_null.pod b/deps/openssl/openssl/doc/crypto/BIO_s_null.pod index e5514f7238..5a1d84dd2c 100644 --- a/deps/openssl/openssl/doc/crypto/BIO_s_null.pod +++ b/deps/openssl/openssl/doc/crypto/BIO_s_null.pod @@ -8,7 +8,7 @@ BIO_s_null - null data sink #include <openssl/bio.h> - BIO_METHOD * BIO_s_null(void); + const BIO_METHOD * BIO_s_null(void); =head1 DESCRIPTION @@ -32,6 +32,13 @@ by adding a null sink BIO to the end of the chain BIO_s_null() returns the null sink BIO method. -=head1 SEE ALSO +=head1 COPYRIGHT -TBA +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BIO_s_socket.pod b/deps/openssl/openssl/doc/crypto/BIO_s_socket.pod index 1c8d3a9110..ad0574aee6 100644 --- a/deps/openssl/openssl/doc/crypto/BIO_s_socket.pod +++ b/deps/openssl/openssl/doc/crypto/BIO_s_socket.pod @@ -8,10 +8,7 @@ BIO_s_socket, BIO_new_socket - socket BIO #include <openssl/bio.h> - BIO_METHOD *BIO_s_socket(void); - - long BIO_set_fd(BIO *b, int fd, long close_flag); - long BIO_get_fd(BIO *b, int *c); + const BIO_METHOD *BIO_s_socket(void); BIO *BIO_new_socket(int sock, int close_flag); @@ -26,12 +23,6 @@ BIO_puts() is supported but BIO_gets() is not. If the close flag is set then the socket is shut down and closed when the BIO is freed. -BIO_set_fd() sets the socket of BIO B<b> to B<fd> and the close -flag to B<close_flag>. - -BIO_get_fd() places the socket in B<c> if it is not NULL, it also -returns the socket. If B<c> is not NULL it should be of type (int *). - BIO_new_socket() returns a socket BIO using B<sock> and B<close_flag>. =head1 NOTES @@ -44,20 +35,20 @@ platforms sockets are not file descriptors and use distinct I/O routines, Windows is one such platform. Any code mixing the two will not work on all platforms. -BIO_set_fd() and BIO_get_fd() are macros. - =head1 RETURN VALUES BIO_s_socket() returns the socket BIO method. -BIO_set_fd() always returns 1. - -BIO_get_fd() returns the socket or -1 if the BIO has not been -initialized. - BIO_new_socket() returns the newly allocated BIO or NULL is an error occurred. -=head1 SEE ALSO +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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>. -TBA +=cut diff --git a/deps/openssl/openssl/doc/crypto/BIO_set_callback.pod b/deps/openssl/openssl/doc/crypto/BIO_set_callback.pod index 4759556245..27aa4f45db 100644 --- a/deps/openssl/openssl/doc/crypto/BIO_set_callback.pod +++ b/deps/openssl/openssl/doc/crypto/BIO_set_callback.pod @@ -2,99 +2,205 @@ =head1 NAME -BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg, -BIO_debug_callback - BIO callback functions +BIO_set_callback_ex, BIO_get_callback_ex, BIO_set_callback, BIO_get_callback, +BIO_set_callback_arg, BIO_get_callback_arg, BIO_debug_callback, +BIO_callback_fn_ex, BIO_callback_fn +- BIO callback functions =head1 SYNOPSIS #include <openssl/bio.h> - #define BIO_set_callback(b,cb) ((b)->callback=(cb)) - #define BIO_get_callback(b) ((b)->callback) - #define BIO_set_callback_arg(b,arg) ((b)->cb_arg=(char *)(arg)) - #define BIO_get_callback_arg(b) ((b)->cb_arg) + typedef long (*BIO_callback_fn_ex)(BIO *b, int oper, const char *argp, + size_t len, int argi, + long argl, int ret, size_t *processed); + typedef long (*BIO_callback_fn)(BIO *b, int oper, const char *argp, int argi, + long argl, long ret); - long BIO_debug_callback(BIO *bio,int cmd,const char *argp,int argi, - long argl,long ret); + void BIO_set_callback_ex(BIO *b, BIO_callback_fn_ex callback); + BIO_callback_fn_ex BIO_get_callback_ex(const BIO *b); - typedef long (*callback)(BIO *b, int oper, const char *argp, - int argi, long argl, long retvalue); + void BIO_set_callback(BIO *b, BIO_callback_fn cb); + BIO_callback_fn BIO_get_callback(BIO *b); + void BIO_set_callback_arg(BIO *b, char *arg); + char *BIO_get_callback_arg(const BIO *b); + + long BIO_debug_callback(BIO *bio, int cmd, const char *argp, int argi, + long argl, long ret); =head1 DESCRIPTION -BIO_set_callback() and BIO_get_callback() set and retrieve the BIO callback, -they are both macros. The callback is called during most high level BIO -operations. It can be used for debugging purposes to trace operations on -a BIO or to modify its operation. +BIO_set_callback_ex() and BIO_get_callback_ex() set and retrieve the BIO +callback. The callback is called during most high level BIO operations. It can +be used for debugging purposes to trace operations on a BIO or to modify its +operation. + +BIO_set_callback() and BIO_get_callback() set and retrieve the old format BIO +callback. New code should not use these functions, but they are retained for +backwards compatibility. Any callback set via BIO_set_callback_ex() will get +called in preference to any set by BIO_set_callback(). BIO_set_callback_arg() and BIO_get_callback_arg() are macros which can be used to set and retrieve an argument for use in the callback. BIO_debug_callback() is a standard debugging callback which prints out information relating to each BIO operation. If the callback -argument is set if is interpreted as a BIO to send the information +argument is set it is interpreted as a BIO to send the information to, otherwise stderr is used. -callback() is the callback function itself. The meaning of each -argument is described below. +BIO_callback_fn_ex() is the type of the callback function and BIO_callback_fn() +is the type of the old format callback function. The meaning of each argument +is described below: + +=over 4 + +=item B<b> The BIO the callback is attached to is passed in B<b>. +=item B<oper> + B<oper> is set to the operation being performed. For some operations the callback is called twice, once before and once after the actual operation, the latter case has B<oper> or'ed with BIO_CB_RETURN. +=item B<len> + +The length of the data requested to be read or written. This is only useful if +B<oper> is BIO_CB_READ, BIO_CB_WRITE or BIO_CB_GETS. + +=item B<argp> B<argi> B<argl> + The meaning of the arguments B<argp>, B<argi> and B<argl> depends on the value of B<oper>, that is the operation being performed. -B<retvalue> is the return value that would be returned to the +=item B<processed> + +B<processed> is a pointer to a location which will be updated with the amount of +data that was actually read or written. Only used for BIO_CB_READ, BIO_CB_WRITE, +BIO_CB_GETS and BIO_CB_PUTS. + +=item B<ret> + +B<ret> is the return value that would be returned to the application if no callback were present. The actual value returned is the return value of the callback itself. In the case of callbacks -called before the actual BIO operation 1 is placed in retvalue, if +called before the actual BIO operation 1 is placed in B<ret>, if the return value is not positive it will be immediately returned to the application and the BIO operation will not be performed. -The callback should normally simply return B<retvalue> when it has -finished processing, unless if specifically wishes to modify the +=back + +The callback should normally simply return B<ret> when it has +finished processing, unless it specifically wishes to modify the value returned to the application. =head1 CALLBACK OPERATIONS +In the notes below, B<callback> defers to the actual callback +function that is called. + =over 4 =item B<BIO_free(b)> -callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L) is called before the -free operation. + callback_ex(b, BIO_CB_FREE, NULL, 0, 0, 0L, 1L, NULL) + +or + + callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L) + +is called before the free operation. + +=item B<BIO_read_ex(b, data, dlen, readbytes)> + + callback_ex(b, BIO_CB_READ, data, dlen, 0, 0L, 1L, readbytes) + +or -=item B<BIO_read(b, out, outl)> + callback(b, BIO_CB_READ, data, dlen, 0L, 1L) + +is called before the read and + + callback_ex(b, BIO_CB_READ | BIO_CB_RETURN, data, dlen, 0, 0L, retvalue, readbytes) + +or + + callback(b, BIO_CB_READ|BIO_CB_RETURN, data, dlen, 0L, retvalue) -callback(b, BIO_CB_READ, out, outl, 0L, 1L) is called before -the read and callback(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0L, retvalue) after. -=item B<BIO_write(b, in, inl)> +=item B<BIO_write(b, data, dlen, written)> + + callback_ex(b, BIO_CB_WRITE, data, dlen, 0, 0L, 1L, written) + +or + + callback(b, BIO_CB_WRITE, datat, dlen, 0L, 1L) + +is called before the write and + + callback_ex(b, BIO_CB_WRITE | BIO_CB_RETURN, data, dlen, 0, 0L, retvalue, written) + +or + + callback(b, BIO_CB_WRITE|BIO_CB_RETURN, data, dlen, 0L, retvalue) -callback(b, BIO_CB_WRITE, in, inl, 0L, 1L) is called before -the write and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0L, retvalue) after. -=item B<BIO_gets(b, out, outl)> +=item B<BIO_gets(b, buf, size)> + + callback_ex(b, BIO_CB_GETS, buf, size, 0, 0L, 1, NULL, NULL) + +or + + callback(b, BIO_CB_GETS, buf, size, 0L, 1L) + +is called before the operation and + + callback_ex(b, BIO_CB_GETS | BIO_CB_RETURN, buf, size, 0, 0L, retvalue, readbytes) + +or + + callback(b, BIO_CB_GETS|BIO_CB_RETURN, buf, size, 0L, retvalue) -callback(b, BIO_CB_GETS, out, outl, 0L, 1L) is called before -the operation and callback(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0L, retvalue) after. -=item B<BIO_puts(b, in)> +=item B<BIO_puts(b, buf)> + + callback_ex(b, BIO_CB_PUTS, buf, 0, 0, 0L, 1L, NULL); + +or + + callback(b, BIO_CB_PUTS, buf, 0, 0L, 1L) + +is called before the operation and + + callback_ex(b, BIO_CB_PUTS | BIO_CB_RETURN, buf, 0, 0, 0L, retvalue, written) + +or + + callback(b, BIO_CB_WRITE|BIO_CB_RETURN, buf, 0, 0L, retvalue) -callback(b, BIO_CB_WRITE, in, 0, 0L, 1L) is called before -the operation and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, 0, 0L, retvalue) after. =item B<BIO_ctrl(BIO *b, int cmd, long larg, void *parg)> -callback(b,BIO_CB_CTRL,parg,cmd,larg,1L) is called before the call and -callback(b,BIO_CB_CTRL|BIO_CB_RETURN,parg,cmd, larg,ret) after. + callback_ex(b, BIO_CB_CTRL, parg, 0, cmd, larg, 1L, NULL) + +or + + callback(b, BIO_CB_CTRL, parg, cmd, larg, 1L) + +is called before the call and + + callback_ex(b, BIO_CB_CTRL | BIO_CB_RETURN, parg, 0, cmd, larg, ret, NULL) + +or + + callback(b, BIO_CB_CTRL|BIO_CB_RETURN, parg, cmd, larg, ret) + +after. =back @@ -103,6 +209,13 @@ callback(b,BIO_CB_CTRL|BIO_CB_RETURN,parg,cmd, larg,ret) after. The BIO_debug_callback() function is a good example, its source is in crypto/bio/bio_cb.c -=head1 SEE ALSO +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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>. -TBA +=cut diff --git a/deps/openssl/openssl/doc/crypto/BIO_should_retry.pod b/deps/openssl/openssl/doc/crypto/BIO_should_retry.pod index b6d51f719d..d01d5bbca1 100644 --- a/deps/openssl/openssl/doc/crypto/BIO_should_retry.pod +++ b/deps/openssl/openssl/doc/crypto/BIO_should_retry.pod @@ -2,28 +2,24 @@ =head1 NAME -BIO_should_retry, BIO_should_read, BIO_should_write, +BIO_should_read, BIO_should_write, BIO_should_io_special, BIO_retry_type, BIO_should_retry, -BIO_get_retry_BIO, BIO_get_retry_reason - BIO retry functions +BIO_get_retry_BIO, BIO_get_retry_reason, BIO_set_retry_reason - BIO retry +functions =head1 SYNOPSIS #include <openssl/bio.h> - #define BIO_should_read(a) ((a)->flags & BIO_FLAGS_READ) - #define BIO_should_write(a) ((a)->flags & BIO_FLAGS_WRITE) - #define BIO_should_io_special(a) ((a)->flags & BIO_FLAGS_IO_SPECIAL) - #define BIO_retry_type(a) ((a)->flags & BIO_FLAGS_RWS) - #define BIO_should_retry(a) ((a)->flags & BIO_FLAGS_SHOULD_RETRY) + int BIO_should_read(BIO *b); + int BIO_should_write(BIO *b); + int BIO_should_io_special(iBIO *b); + int BIO_retry_type(BIO *b); + int BIO_should_retry(BIO *b); - #define BIO_FLAGS_READ 0x01 - #define BIO_FLAGS_WRITE 0x02 - #define BIO_FLAGS_IO_SPECIAL 0x04 - #define BIO_FLAGS_RWS (BIO_FLAGS_READ|BIO_FLAGS_WRITE|BIO_FLAGS_IO_SPECIAL) - #define BIO_FLAGS_SHOULD_RETRY 0x08 - - BIO * BIO_get_retry_BIO(BIO *bio, int *reason); - int BIO_get_retry_reason(BIO *bio); + BIO *BIO_get_retry_BIO(BIO *bio, int *reason); + int BIO_get_retry_reason(BIO *bio); + void BIO_set_retry_reason(BIO *bio, int reason); =head1 DESCRIPTION @@ -51,7 +47,7 @@ B<BIO_FLAGS_IO_SPECIAL> though current BIO types will only set one of these. BIO_get_retry_BIO() determines the precise reason for the special -condition, it returns the BIO that caused this condition and if +condition, it returns the BIO that caused this condition and if B<reason> is not NULL it contains the reason code. The meaning of the reason code and the action that should be taken depends on the type of BIO that resulted in this condition. @@ -59,8 +55,14 @@ the type of BIO that resulted in this condition. BIO_get_retry_reason() returns the reason for a special condition if passed the relevant BIO, for example as returned by BIO_get_retry_BIO(). +BIO_set_retry_reason() sets the retry reason for a special condition for a given +BIO. This would usually only be called by BIO implementations. + =head1 NOTES +BIO_should_read(), BIO_should_write(), BIO_should_io_special(), +BIO_retry_type(), and BIO_should_retry(), are implemented as macros. + If BIO_should_retry() returns false then the precise "error condition" depends on the BIO type that caused it and the return code of the BIO operation. For example if a call to BIO_read() on a socket BIO returns @@ -94,7 +96,7 @@ available and then retry the BIO operation. By combining the retry conditions of several non blocking BIOs in a single select() call it is possible to service several BIOs in a single thread, though the performance may be poor if SSL BIOs are present because long delays -can occur during the initial handshake process. +can occur during the initial handshake process. It is possible for a BIO to block indefinitely if the underlying I/O structure cannot process or return any data. This depends on the behaviour of @@ -111,4 +113,20 @@ the entire structure can be read or written. =head1 SEE ALSO -TBA +L<bio> + +=head1 HISTORY + +The BIO_get_retry_reason() and BIO_set_retry_reason() functions were added in +OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BN_BLINDING_new.pod b/deps/openssl/openssl/doc/crypto/BN_BLINDING_new.pod index 06d7ea20a3..4229e754a1 100644 --- a/deps/openssl/openssl/doc/crypto/BN_BLINDING_new.pod +++ b/deps/openssl/openssl/doc/crypto/BN_BLINDING_new.pod @@ -2,38 +2,37 @@ =head1 NAME -BN_BLINDING_new, BN_BLINDING_free, BN_BLINDING_update, BN_BLINDING_convert, -BN_BLINDING_invert, BN_BLINDING_convert_ex, BN_BLINDING_invert_ex, -BN_BLINDING_get_thread_id, BN_BLINDING_set_thread_id, BN_BLINDING_thread_id, BN_BLINDING_get_flags, -BN_BLINDING_set_flags, BN_BLINDING_create_param - blinding related BIGNUM -functions. +BN_BLINDING_new, BN_BLINDING_free, BN_BLINDING_update, BN_BLINDING_convert, +BN_BLINDING_invert, BN_BLINDING_convert_ex, BN_BLINDING_invert_ex, +BN_BLINDING_is_current_thread, BN_BLINDING_set_current_thread, +BN_BLINDING_lock, BN_BLINDING_unlock, BN_BLINDING_get_flags, +BN_BLINDING_set_flags, BN_BLINDING_create_param - blinding related BIGNUM functions =head1 SYNOPSIS #include <openssl/bn.h> BN_BLINDING *BN_BLINDING_new(const BIGNUM *A, const BIGNUM *Ai, - BIGNUM *mod); + BIGNUM *mod); void BN_BLINDING_free(BN_BLINDING *b); - int BN_BLINDING_update(BN_BLINDING *b,BN_CTX *ctx); + int BN_BLINDING_update(BN_BLINDING *b, BN_CTX *ctx); int BN_BLINDING_convert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx); int BN_BLINDING_invert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx); int BN_BLINDING_convert_ex(BIGNUM *n, BIGNUM *r, BN_BLINDING *b, - BN_CTX *ctx); + BN_CTX *ctx); int BN_BLINDING_invert_ex(BIGNUM *n, const BIGNUM *r, BN_BLINDING *b, - BN_CTX *ctx); - #ifndef OPENSSL_NO_DEPRECATED - unsigned long BN_BLINDING_get_thread_id(const BN_BLINDING *); - void BN_BLINDING_set_thread_id(BN_BLINDING *, unsigned long); - #endif - CRYPTO_THREADID *BN_BLINDING_thread_id(BN_BLINDING *); + BN_CTX *ctx); + int BN_BLINDING_is_current_thread(BN_BLINDING *b); + void BN_BLINDING_set_current_thread(BN_BLINDING *b); + int BN_BLINDING_lock(BN_BLINDING *b); + int BN_BLINDING_unlock(BN_BLINDING *b); unsigned long BN_BLINDING_get_flags(const BN_BLINDING *); void BN_BLINDING_set_flags(BN_BLINDING *, unsigned long); BN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b, - const BIGNUM *e, BIGNUM *m, BN_CTX *ctx, - int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, const BIGNUM *p, - const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx), - BN_MONT_CTX *m_ctx); + const BIGNUM *e, BIGNUM *m, BN_CTX *ctx, + int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, const BIGNUM *p, + const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx), + BN_MONT_CTX *m_ctx); =head1 DESCRIPTION @@ -41,6 +40,7 @@ BN_BLINDING_new() allocates a new B<BN_BLINDING> structure and copies the B<A> and B<Ai> values into the newly created B<BN_BLINDING> object. BN_BLINDING_free() frees the B<BN_BLINDING> structure. +If B<b> is NULL, nothing is done. BN_BLINDING_update() updates the B<BN_BLINDING> parameters by squaring the B<A> and B<Ai> or, after specific number of uses and if the @@ -57,11 +57,16 @@ BN_BLINDING_convert() and BN_BLINDING_invert() are wrapper functions for BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex() with B<r> set to NULL. -BN_BLINDING_thread_id() provides access to the B<CRYPTO_THREADID> -object within the B<BN_BLINDING> structure. This is to help users -provide proper locking if needed for multi-threaded use. The "thread -id" object of a newly allocated B<BN_BLINDING> structure is -initialised to the thread id in which BN_BLINDING_new() was called. +BN_BLINDING_is_current_thread() returns whether the B<BN_BLINDING> +structure is owned by the current thread. This is to help users +provide proper locking if needed for multi-threaded use. + +BN_BLINDING_set_current_thread() sets the current thread as the +owner of the B<BN_BLINDING> structure. + +BN_BLINDING_lock() locks the B<BN_BLINDING> structure. + +BN_BLINDING_unlock() unlocks the B<BN_BLINDING> structure. BN_BLINDING_get_flags() returns the BN_BLINDING flags. Currently there are two supported flags: B<BN_BLINDING_NO_UPDATE> and @@ -86,30 +91,32 @@ BN_BLINDING_update(), BN_BLINDING_convert(), BN_BLINDING_invert(), BN_BLINDING_convert_ex() and BN_BLINDING_invert_ex() return 1 on success and 0 if an error occurred. -BN_BLINDING_thread_id() returns a pointer to the thread id object -within a B<BN_BLINDING> object. +BN_BLINDING_is_current_thread() returns 1 if the current thread owns +the B<BN_BLINDING> object, 0 otherwise. + +BN_BLINDING_set_current_thread() doesn't return anything. + +BN_BLINDING_lock(), BN_BLINDING_unlock() return 1 if the operation +succeeded or 0 on error. BN_BLINDING_get_flags() returns the currently set B<BN_BLINDING> flags (a B<unsigned long> value). -BN_BLINDING_create_param() returns the newly created B<BN_BLINDING> +BN_BLINDING_create_param() returns the newly created B<BN_BLINDING> parameters or NULL on error. -=head1 SEE ALSO - -L<bn(3)|bn(3)> - =head1 HISTORY -BN_BLINDING_thread_id was first introduced in OpenSSL 1.0.0, and it -deprecates BN_BLINDING_set_thread_id and BN_BLINDING_get_thread_id. +BN_BLINDING_thread_id() was first introduced in OpenSSL 1.0.0, and it +deprecates BN_BLINDING_set_thread_id() and BN_BLINDING_get_thread_id(). -BN_BLINDING_convert_ex, BN_BLINDIND_invert_ex, BN_BLINDING_get_thread_id, -BN_BLINDING_set_thread_id, BN_BLINDING_set_flags, BN_BLINDING_get_flags -and BN_BLINDING_create_param were first introduced in OpenSSL 0.9.8 +=head1 COPYRIGHT -=head1 AUTHOR +Copyright 2005-2017 The OpenSSL Project Authors. All Rights Reserved. -Nils Larsch for the OpenSSL project (http://www.openssl.org). +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BN_CTX_new.pod b/deps/openssl/openssl/doc/crypto/BN_CTX_new.pod index bbedbb1778..623fcd5692 100644 --- a/deps/openssl/openssl/doc/crypto/BN_CTX_new.pod +++ b/deps/openssl/openssl/doc/crypto/BN_CTX_new.pod @@ -2,7 +2,7 @@ =head1 NAME -BN_CTX_new, BN_CTX_init, BN_CTX_free - allocate and free BN_CTX structures +BN_CTX_new, BN_CTX_secure_new, BN_CTX_free - allocate and free BN_CTX structures =head1 SYNOPSIS @@ -10,12 +10,9 @@ BN_CTX_new, BN_CTX_init, BN_CTX_free - allocate and free BN_CTX structures BN_CTX *BN_CTX_new(void); - void BN_CTX_free(BN_CTX *c); - -Deprecated: - - void BN_CTX_init(BN_CTX *c); + BN_CTX *BN_CTX_secure_new(void); + void BN_CTX_free(BN_CTX *c); =head1 DESCRIPTION @@ -24,34 +21,56 @@ library functions. Since dynamic memory allocation to create B<BIGNUM>s is rather expensive when used in conjunction with repeated subroutine calls, the B<BN_CTX> structure is used. -BN_CTX_new() allocates and initializes a B<BN_CTX> -structure. +BN_CTX_new() allocates and initializes a B<BN_CTX> structure. +BN_CTX_secure_new() allocates and initializes a B<BN_CTX> structure +but uses the secure heap (see L<CRYPTO_secure_malloc(3)>) to hold the +B<BIGNUM>s. BN_CTX_free() frees the components of the B<BN_CTX>, and if it was created by BN_CTX_new(), also the structure itself. -If L<BN_CTX_start(3)|BN_CTX_start(3)> has been used on the B<BN_CTX>, -L<BN_CTX_end(3)|BN_CTX_end(3)> must be called before the B<BN_CTX> +If L<BN_CTX_start(3)> has been used on the B<BN_CTX>, +L<BN_CTX_end(3)> must be called before the B<BN_CTX> may be freed by BN_CTX_free(). - -BN_CTX_init() (deprecated) initializes an existing uninitialized B<BN_CTX>. -This should not be used for new programs. Use BN_CTX_new() instead. +If B<c> is NULL, nothing is done. =head1 RETURN VALUES -BN_CTX_new() returns a pointer to the B<BN_CTX>. If the allocation fails, -it returns B<NULL> and sets an error code that can be obtained by -L<ERR_get_error(3)|ERR_get_error(3)>. +BN_CTX_new() and BN_CTX_secure_new() return a pointer to the B<BN_CTX>. +If the allocation fails, +they return B<NULL> and sets an error code that can be obtained by +L<ERR_get_error(3)>. + +BN_CTX_free() has no return values. -BN_CTX_init() and BN_CTX_free() have no return values. +=head1 REMOVED FUNCTIONALITY + + void BN_CTX_init(BN_CTX *c); + +BN_CTX_init() is no longer available as of OpenSSL 1.1.0. Applications should +replace use of BN_CTX_init with BN_CTX_new instead: + + BN_CTX *ctx; + ctx = BN_CTX_new(); + if(!ctx) /* Handle error */ + ... + BN_CTX_free(ctx); =head1 SEE ALSO -L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)>, -L<BN_CTX_start(3)|BN_CTX_start(3)> +L<ERR_get_error(3)>, L<BN_add(3)>, +L<BN_CTX_start(3)> =head1 HISTORY -BN_CTX_new() and BN_CTX_free() are available in all versions on SSLeay -and OpenSSL. BN_CTX_init() was added in SSLeay 0.9.1b. +BN_CTX_init() was removed in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BN_CTX_start.pod b/deps/openssl/openssl/doc/crypto/BN_CTX_start.pod index dfcefe1a88..372da506d9 100644 --- a/deps/openssl/openssl/doc/crypto/BN_CTX_start.pod +++ b/deps/openssl/openssl/doc/crypto/BN_CTX_start.pod @@ -17,7 +17,7 @@ BN_CTX_start, BN_CTX_get, BN_CTX_end - use temporary BIGNUM variables =head1 DESCRIPTION These functions are used to obtain temporary B<BIGNUM> variables from -a B<BN_CTX> (which can been created by using L<BN_CTX_new(3)|BN_CTX_new(3)>) +a B<BN_CTX> (which can been created by using L<BN_CTX_new(3)>) in order to save the overhead of repeatedly creating and freeing B<BIGNUM>s in functions that are called from inside a loop. @@ -38,15 +38,20 @@ BN_CTX_get() returns a pointer to the B<BIGNUM>, or B<NULL> on error. Once BN_CTX_get() has failed, the subsequent calls will return B<NULL> as well, so it is sufficient to check the return value of the last BN_CTX_get() call. In case of an error, an error code is set, which -can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. +can be obtained by L<ERR_get_error(3)>. =head1 SEE ALSO -L<BN_CTX_new(3)|BN_CTX_new(3)> +L<BN_CTX_new(3)> -=head1 HISTORY +=head1 COPYRIGHT -BN_CTX_start(), BN_CTX_get() and BN_CTX_end() were added in OpenSSL 0.9.5. +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BN_add.pod b/deps/openssl/openssl/doc/crypto/BN_add.pod index 88c7a799ee..db3b0d45b4 100644 --- a/deps/openssl/openssl/doc/crypto/BN_add.pod +++ b/deps/openssl/openssl/doc/crypto/BN_add.pod @@ -49,10 +49,11 @@ BN_add() adds I<a> and I<b> and places the result in I<r> (C<r=a+b>). I<r> may be the same B<BIGNUM> as I<a> or I<b>. BN_sub() subtracts I<b> from I<a> and places the result in I<r> (C<r=a-b>). +I<r> may be the same B<BIGNUM> as I<a> or I<b>. BN_mul() multiplies I<a> and I<b> and places the result in I<r> (C<r=a*b>). I<r> may be the same B<BIGNUM> as I<a> or I<b>. -For multiplication by powers of 2, use L<BN_lshift(3)|BN_lshift(3)>. +For multiplication by powers of 2, use L<BN_lshift(3)>. BN_sqr() takes the square of I<a> and places the result in I<r> (C<r=a^2>). I<r> and I<a> may be the same B<BIGNUM>. @@ -80,8 +81,8 @@ BN_mod_mul() multiplies I<a> by I<b> and finds the non-negative remainder respective to modulus I<m> (C<r=(a*b) mod m>). I<r> may be the same B<BIGNUM> as I<a> or I<b>. For more efficient algorithms for repeated computations using the same modulus, see -L<BN_mod_mul_montgomery(3)|BN_mod_mul_montgomery(3)> and -L<BN_mod_mul_reciprocal(3)|BN_mod_mul_reciprocal(3)>. +L<BN_mod_mul_montgomery(3)> and +L<BN_mod_mul_reciprocal(3)>. BN_mod_sqr() takes the square of I<a> modulo B<m> and places the result in I<r>. @@ -98,7 +99,7 @@ places the result in I<r>. I<r> may be the same B<BIGNUM> as I<a> or I<b>. For all functions, I<ctx> is a previously allocated B<BN_CTX> used for -temporary variables; see L<BN_CTX_new(3)|BN_CTX_new(3)>. +temporary variables; see L<BN_CTX_new(3)>. Unless noted otherwise, the result B<BIGNUM> must be different from the arguments. @@ -107,20 +108,20 @@ the arguments. For all functions, 1 is returned for success, 0 on error. The return value should always be checked (e.g., C<if (!BN_add(r,a,b)) goto err;>). -The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. +The error codes can be obtained by L<ERR_get_error(3)>. =head1 SEE ALSO -L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_CTX_new(3)|BN_CTX_new(3)>, -L<BN_add_word(3)|BN_add_word(3)>, L<BN_set_bit(3)|BN_set_bit(3)> +L<ERR_get_error(3)>, L<BN_CTX_new(3)>, +L<BN_add_word(3)>, L<BN_set_bit(3)> + +=head1 COPYRIGHT -=head1 HISTORY +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. -BN_add(), BN_sub(), BN_sqr(), BN_div(), BN_mod(), BN_mod_mul(), -BN_mod_exp() and BN_gcd() are available in all versions of SSLeay and -OpenSSL. The I<ctx> argument to BN_mul() was added in SSLeay -0.9.1b. BN_exp() appeared in SSLeay 0.9.0. -BN_nnmod(), BN_mod_add(), BN_mod_sub(), and BN_mod_sqr() were added in -OpenSSL 0.9.7. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BN_add_word.pod b/deps/openssl/openssl/doc/crypto/BN_add_word.pod index 70667d2893..6c69bc485f 100644 --- a/deps/openssl/openssl/doc/crypto/BN_add_word.pod +++ b/deps/openssl/openssl/doc/crypto/BN_add_word.pod @@ -40,22 +40,22 @@ For BN_div_word() and BN_mod_word(), B<w> must not be 0. =head1 RETURN VALUES BN_add_word(), BN_sub_word() and BN_mul_word() return 1 for success, 0 -on error. The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. +on error. The error codes can be obtained by L<ERR_get_error(3)>. BN_mod_word() and BN_div_word() return B<a>%B<w> on success and B<(BN_ULONG)-1> if an error occurred. =head1 SEE ALSO -L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)> +L<ERR_get_error(3)>, L<BN_add(3)> -=head1 HISTORY +=head1 COPYRIGHT -BN_add_word() and BN_mod_word() are available in all versions of -SSLeay and OpenSSL. BN_div_word() was added in SSLeay 0.8, and -BN_sub_word() and BN_mul_word() in SSLeay 0.9.0. +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. -Before 0.9.8a the return value for BN_div_word() and BN_mod_word() -in case of an error was 0. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BN_bn2bin.pod b/deps/openssl/openssl/doc/crypto/BN_bn2bin.pod index f6bb484f90..ac46948477 100644 --- a/deps/openssl/openssl/doc/crypto/BN_bn2bin.pod +++ b/deps/openssl/openssl/doc/crypto/BN_bn2bin.pod @@ -2,16 +2,22 @@ =head1 NAME -BN_bn2bin, BN_bin2bn, BN_bn2hex, BN_bn2dec, BN_hex2bn, BN_dec2bn, -BN_print, BN_print_fp, BN_bn2mpi, BN_mpi2bn - format conversions +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 =head1 SYNOPSIS #include <openssl/bn.h> int BN_bn2bin(const BIGNUM *a, unsigned char *to); + int BN_bn2binpad(const BIGNUM *a, unsigned char *to, int tolen); BIGNUM *BN_bin2bn(const unsigned char *s, int len, BIGNUM *ret); + int BN_bn2lebinpad(const BIGNUM *a, unsigned char *to, int tolen); + BIGNUM *BN_lebin2bn(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); @@ -29,20 +35,28 @@ BN_bn2bin() converts the absolute value of B<a> into big-endian form and stores it at B<to>. B<to> must point to BN_num_bytes(B<a>) bytes of memory. +BN_bn2binpad() also converts the absolute value of B<a> into big-endian form +and stores it at B<to>. B<tolen> indicates the length of the output buffer +B<to>. The result is padded with zeroes if necessary. If B<tolen> is less than +BN_num_bytes(B<a>) an error is returned. + BN_bin2bn() converts the positive integer in big-endian form of length B<len> at B<s> into a B<BIGNUM> and places it in B<ret>. If B<ret> is NULL, a new B<BIGNUM> is created. +BN_bn2lebinpad() and BN_bin2lbn() are identical to BN_bn2binpad() and +BN_bin2bn() except the buffer is in little-endian format. + 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 freed later using OPENSSL_free(). -BN_hex2bn() converts the string B<str> containing a hexadecimal number -to a B<BIGNUM> and stores it in **B<bn>. If *B<bn> is NULL, a new -B<BIGNUM> is created. If B<bn> is NULL, it only computes the number's -length in hexadecimal digits. If the string starts with '-', the -number is negative. +BN_hex2bn() takes as many characters as possible from the string B<str>, +including the leading character '-' which means negative, to form a valid +hexadecimal number representation and converts them to a B<BIGNUM> and +stores it in **B<bn>. If *B<bn> is NULL, a new B<BIGNUM> is created. If +B<bn> is NULL, it only computes the length of valid representation. A "negative zero" is converted to zero. BN_dec2bn() is the same using the decimal system. @@ -69,6 +83,9 @@ if B<ret> is NULL. BN_bn2bin() returns the length of the big-endian number placed at B<to>. BN_bin2bn() returns the B<BIGNUM>, NULL on error. +BN_bn2binpad() returns the number of bytes written or -1 if the supplied +buffer is too small. + BN_bn2hex() and BN_bn2dec() return a null-terminated string, or NULL on error. BN_hex2bn() and BN_dec2bn() return the number of characters used in parsing, or 0 on error, in which @@ -79,20 +96,21 @@ BN_print_fp() and BN_print() return 1 on success, 0 on write errors. BN_bn2mpi() returns the length of the representation. BN_mpi2bn() returns the B<BIGNUM>, and NULL on error. -The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. +The error codes can be obtained by L<ERR_get_error(3)>. =head1 SEE ALSO -L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_zero(3)|BN_zero(3)>, -L<ASN1_INTEGER_to_BN(3)|ASN1_INTEGER_to_BN(3)>, -L<BN_num_bytes(3)|BN_num_bytes(3)> +L<ERR_get_error(3)>, L<BN_zero(3)>, +L<ASN1_INTEGER_to_BN(3)>, +L<BN_num_bytes(3)> -=head1 HISTORY +=head1 COPYRIGHT -BN_bn2bin(), BN_bin2bn(), BN_print_fp() and BN_print() are available -in all versions of SSLeay and OpenSSL. +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. -BN_bn2hex(), BN_bn2dec(), BN_hex2bn(), BN_dec2bn(), BN_bn2mpi() and -BN_mpi2bn() were added in SSLeay 0.9.0. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BN_cmp.pod b/deps/openssl/openssl/doc/crypto/BN_cmp.pod index 23e9ed0b4f..95d162ff29 100644 --- a/deps/openssl/openssl/doc/crypto/BN_cmp.pod +++ b/deps/openssl/openssl/doc/crypto/BN_cmp.pod @@ -35,14 +35,13 @@ of B<a> and B<b>. BN_is_zero(), BN_is_one() BN_is_word() and BN_is_odd() return 1 if the condition is true, 0 otherwise. -=head1 SEE ALSO +=head1 COPYRIGHT -L<bn(3)|bn(3)> +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. -=head1 HISTORY - -BN_cmp(), BN_ucmp(), BN_is_zero(), BN_is_one() and BN_is_word() are -available in all versions of SSLeay and OpenSSL. -BN_is_odd() was added in SSLeay 0.8. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BN_copy.pod b/deps/openssl/openssl/doc/crypto/BN_copy.pod index 388dd7df26..46de544286 100644 --- a/deps/openssl/openssl/doc/crypto/BN_copy.pod +++ b/deps/openssl/openssl/doc/crypto/BN_copy.pod @@ -2,7 +2,7 @@ =head1 NAME -BN_copy, BN_dup - copy BIGNUMs +BN_copy, BN_dup, BN_with_flags - copy BIGNUMs =head1 SYNOPSIS @@ -12,23 +12,58 @@ BN_copy, BN_dup - copy BIGNUMs BIGNUM *BN_dup(const BIGNUM *from); + void BN_with_flags(BIGNUM *dest, const BIGNUM *b, int flags); + =head1 DESCRIPTION BN_copy() copies B<from> to B<to>. BN_dup() creates a new B<BIGNUM> containing the value B<from>. +BN_with_flags creates a B<temporary> shallow copy of B<b> in B<dest>. It places +significant restrictions on the copied data. Applications that do no adhere to +these restrictions may encounter unexpected side effects or crashes. For that +reason use of this function is discouraged. Any flags provided in B<flags> will +be set in B<dest> in addition to any flags already set in B<b>. For example this +might commonly be used to create a temporary copy of a BIGNUM with the +B<BN_FLG_CONSTTIME> flag set for constant time operations. The temporary copy in +B<dest> will share some internal state with B<b>. For this reason the following +restrictions apply to the use of B<dest>: + +=over 2 + +=item * + +B<dest> should be a newly allocated BIGNUM obtained via a call to BN_new(). It +should not have been used for other purposes or initialised in any way. + +=item * + +B<dest> must only be used in "read-only" operations, i.e. typically those +functions where the relevant parameter is declared "const". + +=item * + +B<dest> must be used and freed before any further subsequent use of B<b> + +=back + =head1 RETURN VALUES BN_copy() returns B<to> on success, NULL on error. BN_dup() returns the new B<BIGNUM>, and NULL on error. The error codes can be obtained -by L<ERR_get_error(3)|ERR_get_error(3)>. +by L<ERR_get_error(3)>. =head1 SEE ALSO -L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)> +L<ERR_get_error(3)> + +=head1 COPYRIGHT -=head1 HISTORY +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. -BN_copy() and BN_dup() are available in all versions of SSLeay and OpenSSL. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BN_generate_prime.pod b/deps/openssl/openssl/doc/crypto/BN_generate_prime.pod index bf1b5308ad..c97536b5c4 100644 --- a/deps/openssl/openssl/doc/crypto/BN_generate_prime.pod +++ b/deps/openssl/openssl/doc/crypto/BN_generate_prime.pod @@ -3,49 +3,59 @@ =head1 NAME BN_generate_prime_ex, BN_is_prime_ex, BN_is_prime_fasttest_ex, BN_GENCB_call, -BN_GENCB_set_old, BN_GENCB_set, BN_generate_prime, BN_is_prime, -BN_is_prime_fasttest - generate primes and test for primality +BN_GENCB_new, BN_GENCB_free, BN_GENCB_set_old, BN_GENCB_set, BN_GENCB_get_arg, +BN_generate_prime, BN_is_prime, BN_is_prime_fasttest - generate primes and test +for primality =head1 SYNOPSIS #include <openssl/bn.h> - int BN_generate_prime_ex(BIGNUM *ret,int bits,int safe, const BIGNUM *add, + int BN_generate_prime_ex(BIGNUM *ret, int bits, int safe, const BIGNUM *add, const BIGNUM *rem, BN_GENCB *cb); - int BN_is_prime_ex(const BIGNUM *p,int nchecks, BN_CTX *ctx, BN_GENCB *cb); + int BN_is_prime_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx, BN_GENCB *cb); - int BN_is_prime_fasttest_ex(const BIGNUM *p,int nchecks, BN_CTX *ctx, + int BN_is_prime_fasttest_ex(const BIGNUM *p, int nchecks, BN_CTX *ctx, int do_trial_division, BN_GENCB *cb); int BN_GENCB_call(BN_GENCB *cb, int a, int b); - #define BN_GENCB_set_old(gencb, callback, cb_arg) ... + BN_GENCB *BN_GENCB_new(void); - #define BN_GENCB_set(gencb, callback, cb_arg) ... + void BN_GENCB_free(BN_GENCB *cb); + void BN_GENCB_set_old(BN_GENCB *gencb, + void (*callback)(int, int, void *), void *cb_arg); + + void BN_GENCB_set(BN_GENCB *gencb, + int (*callback)(int, int, BN_GENCB *), void *cb_arg); + + void *BN_GENCB_get_arg(BN_GENCB *cb); Deprecated: + #if OPENSSL_API_COMPAT < 0x00908000L BIGNUM *BN_generate_prime(BIGNUM *ret, int num, int safe, BIGNUM *add, BIGNUM *rem, void (*callback)(int, int, void *), void *cb_arg); - int BN_is_prime(const BIGNUM *a, int checks, void (*callback)(int, int, + int BN_is_prime(const BIGNUM *a, int checks, void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg); int BN_is_prime_fasttest(const BIGNUM *a, int checks, void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg, int do_trial_division); + #endif =head1 DESCRIPTION BN_generate_prime_ex() generates a pseudo-random prime number of -bit length B<bits>. +at least bit length B<bits>. If B<ret> is not B<NULL>, it will be used to store the number. If B<cb> is not B<NULL>, it is used as follows: -=over 4 +=over 2 =item * @@ -103,17 +113,23 @@ B<BN_GENCB> structure that are supported: "new" style and "old" style. New programs should prefer the "new" style, whilst the "old" style is provided for backwards compatibility purposes. +A BN_GENCB structure should be created through a call to BN_GENCB_new(), +and freed through a call to BN_GENCB_free(). + For "new" style callbacks a BN_GENCB structure should be initialised with a -call to BN_GENCB_set, where B<gencb> is a B<BN_GENCB *>, B<callback> is of +call to BN_GENCB_set(), where B<gencb> is a B<BN_GENCB *>, B<callback> is of type B<int (*callback)(int, int, BN_GENCB *)> and B<cb_arg> is a B<void *>. "Old" style callbacks are the same except they are initialised with a call -to BN_GENCB_set_old and B<callback> is of type +to BN_GENCB_set_old() and B<callback> is of type B<void (*callback)(int, int, void *)>. A callback is invoked through a call to B<BN_GENCB_call>. This will check the type of the callback and will invoke B<callback(a, b, gencb)> for new style callbacks or B<callback(a, b, cb_arg)> for old style. +It is possible to obtained the argument associated with a BN_GENCB structure +(set via a call to BN_GENCB_set or BN_GENCB_set_old) using BN_GENCB_get_arg. + BN_generate_prime (deprecated) works in the same way as BN_generate_prime_ex but expects an old style callback function directly in the B<callback> parameter, and an argument to pass to it in @@ -132,19 +148,47 @@ prime with an error probability of less than 0.25^B<nchecks>, and BN_generate_prime() returns the prime number on success, B<NULL> otherwise. +BN_GENCB_new returns a pointer to a BN_GENCB structure on success, or B<NULL> +otherwise. + +BN_GENCB_get_arg returns the argument previously associated with a BN_GENCB +structure. + Callback functions should return 1 on success or 0 on error. -The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. +The error codes can be obtained by L<ERR_get_error(3)>. + +=head1 REMOVED FUNCTIONALITY + +As of OpenSSL 1.1.0 it is no longer possible to create a BN_GENCB structure +directly, as in: + + BN_GENCB callback; + +Instead applications should create a BN_GENCB structure using BN_GENCB_new: + + BN_GENCB *callback; + callback = BN_GENCB_new(); + if(!callback) /* handle error */ + ... + BN_GENCB_free(callback); =head1 SEE ALSO -L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)> +L<ERR_get_error(3)>, L<RAND_bytes(3)> =head1 HISTORY -The B<cb_arg> arguments to BN_generate_prime() and to BN_is_prime() -were added in SSLeay 0.9.0. The B<ret> argument to BN_generate_prime() -was added in SSLeay 0.9.1. -BN_is_prime_fasttest() was added in OpenSSL 0.9.5. +BN_GENCB_new(), BN_GENCB_free(), +and BN_GENCB_get_arg() were added in OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BN_mod_inverse.pod b/deps/openssl/openssl/doc/crypto/BN_mod_inverse.pod index 3ea3975c74..cb84a14098 100644 --- a/deps/openssl/openssl/doc/crypto/BN_mod_inverse.pod +++ b/deps/openssl/openssl/doc/crypto/BN_mod_inverse.pod @@ -23,14 +23,19 @@ variables. B<r> may be the same B<BIGNUM> as B<a> or B<n>. =head1 RETURN VALUES BN_mod_inverse() returns the B<BIGNUM> containing the inverse, and -NULL on error. The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. +NULL on error. The error codes can be obtained by L<ERR_get_error(3)>. =head1 SEE ALSO -L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)> +L<ERR_get_error(3)>, L<BN_add(3)> -=head1 HISTORY +=head1 COPYRIGHT -BN_mod_inverse() is available in all versions of SSLeay and OpenSSL. +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BN_mod_mul_montgomery.pod b/deps/openssl/openssl/doc/crypto/BN_mod_mul_montgomery.pod index 6b16351b92..81056c76ac 100644 --- a/deps/openssl/openssl/doc/crypto/BN_mod_mul_montgomery.pod +++ b/deps/openssl/openssl/doc/crypto/BN_mod_mul_montgomery.pod @@ -2,7 +2,7 @@ =head1 NAME -BN_mod_mul_montgomery, BN_MONT_CTX_new, BN_MONT_CTX_init, +BN_mod_mul_montgomery, BN_MONT_CTX_new, BN_MONT_CTX_free, BN_MONT_CTX_set, BN_MONT_CTX_copy, BN_from_montgomery, BN_to_montgomery - Montgomery multiplication @@ -11,7 +11,6 @@ BN_from_montgomery, BN_to_montgomery - Montgomery multiplication #include <openssl/bn.h> BN_MONT_CTX *BN_MONT_CTX_new(void); - void BN_MONT_CTX_init(BN_MONT_CTX *ctx); void BN_MONT_CTX_free(BN_MONT_CTX *mont); int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx); @@ -29,12 +28,11 @@ BN_from_montgomery, BN_to_montgomery - Montgomery multiplication =head1 DESCRIPTION These functions implement Montgomery multiplication. They are used -automatically when L<BN_mod_exp(3)|BN_mod_exp(3)> is called with suitable input, +automatically when L<BN_mod_exp(3)> is called with suitable input, but they may be useful when several operations are to be performed using the same modulus. BN_MONT_CTX_new() allocates and initializes a B<BN_MONT_CTX> structure. -BN_MONT_CTX_init() initializes an existing uninitialized B<BN_MONT_CTX>. BN_MONT_CTX_set() sets up the I<mont> structure from the modulus I<m> by precomputing its inverse and a value R. @@ -43,6 +41,7 @@ BN_MONT_CTX_copy() copies the B<BN_MONT_CTX> I<from> to I<to>. BN_MONT_CTX_free() frees the components of the B<BN_MONT_CTX>, and, if it was created by BN_MONT_CTX_new(), also the structure itself. +If B<mont> is NULL, nothing is done. BN_mod_mul_montgomery() computes Mont(I<a>,I<b>):=I<a>*I<b>*R^-1 and places the result in I<r>. @@ -55,30 +54,15 @@ Note that I<a> must be non-negative and smaller than the modulus. For all functions, I<ctx> is a previously allocated B<BN_CTX> used for temporary variables. -The B<BN_MONT_CTX> structure is defined as follows: - - typedef struct bn_mont_ctx_st - { - int ri; /* number of bits in R */ - BIGNUM RR; /* R^2 (used to convert to Montgomery form) */ - BIGNUM N; /* The modulus */ - BIGNUM Ni; /* R*(1/R mod N) - N*Ni = 1 - * (Ni is only stored for bignum algorithm) */ - BN_ULONG n0; /* least significant word of Ni */ - int flags; - } BN_MONT_CTX; - -BN_to_montgomery() is a macro. - =head1 RETURN VALUES BN_MONT_CTX_new() returns the newly allocated B<BN_MONT_CTX>, and NULL on error. -BN_MONT_CTX_init() and BN_MONT_CTX_free() have no return values. +BN_MONT_CTX_free() has no return value. For the other functions, 1 is returned for success, 0 on error. -The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. +The error codes can be obtained by L<ERR_get_error(3)>. =head1 WARNING @@ -87,15 +71,20 @@ outside the expected range. =head1 SEE ALSO -L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)>, -L<BN_CTX_new(3)|BN_CTX_new(3)> +L<ERR_get_error(3)>, L<BN_add(3)>, +L<BN_CTX_new(3)> =head1 HISTORY -BN_MONT_CTX_new(), BN_MONT_CTX_free(), BN_MONT_CTX_set(), -BN_mod_mul_montgomery(), BN_from_montgomery() and BN_to_montgomery() -are available in all versions of SSLeay and OpenSSL. +BN_MONT_CTX_init() was removed in OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. -BN_MONT_CTX_init() and BN_MONT_CTX_copy() were added in SSLeay 0.9.1b. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BN_mod_mul_reciprocal.pod b/deps/openssl/openssl/doc/crypto/BN_mod_mul_reciprocal.pod index 74a216ddc2..d480fed2d0 100644 --- a/deps/openssl/openssl/doc/crypto/BN_mod_mul_reciprocal.pod +++ b/deps/openssl/openssl/doc/crypto/BN_mod_mul_reciprocal.pod @@ -2,7 +2,7 @@ =head1 NAME -BN_mod_mul_reciprocal, BN_div_recp, BN_RECP_CTX_new, BN_RECP_CTX_init, +BN_mod_mul_reciprocal, BN_div_recp, BN_RECP_CTX_new, BN_RECP_CTX_free, BN_RECP_CTX_set - modular multiplication using reciprocal @@ -11,7 +11,6 @@ reciprocal #include <openssl/bn.h> BN_RECP_CTX *BN_RECP_CTX_new(void); - void BN_RECP_CTX_init(BN_RECP_CTX *recp); void BN_RECP_CTX_free(BN_RECP_CTX *recp); int BN_RECP_CTX_set(BN_RECP_CTX *recp, const BIGNUM *m, BN_CTX *ctx); @@ -25,16 +24,16 @@ reciprocal =head1 DESCRIPTION BN_mod_mul_reciprocal() can be used to perform an efficient -L<BN_mod_mul(3)|BN_mod_mul(3)> operation when the operation will be performed +L<BN_mod_mul(3)> operation when the operation will be performed repeatedly with the same modulus. It computes B<r>=(B<a>*B<b>)%B<m> using B<recp>=1/B<m>, which is set as described below. B<ctx> is a previously allocated B<BN_CTX> used for temporary variables. BN_RECP_CTX_new() allocates and initializes a B<BN_RECP> structure. -BN_RECP_CTX_init() initializes an existing uninitialized B<BN_RECP>. BN_RECP_CTX_free() frees the components of the B<BN_RECP>, and, if it was created by BN_RECP_CTX_new(), also the structure itself. +If B<recp> is NULL, nothing is done. BN_RECP_CTX_set() stores B<m> in B<recp> and sets it up for computing 1/B<m> and shifting it left by BN_num_bits(B<m>)+1 to make it an @@ -44,38 +43,34 @@ later be stored in B<recp>. BN_div_recp() divides B<a> by B<m> using B<recp>. It places the quotient in B<dv> and the remainder in B<rem>. -The B<BN_RECP_CTX> structure is defined as follows: - - typedef struct bn_recp_ctx_st - { - BIGNUM N; /* the divisor */ - BIGNUM Nr; /* the reciprocal */ - int num_bits; - int shift; - int flags; - } BN_RECP_CTX; - -It cannot be shared between threads. +The B<BN_RECP_CTX> structure cannot be shared between threads. =head1 RETURN VALUES BN_RECP_CTX_new() returns the newly allocated B<BN_RECP_CTX>, and NULL on error. -BN_RECP_CTX_init() and BN_RECP_CTX_free() have no return values. +BN_RECP_CTX_free() has no return value. For the other functions, 1 is returned for success, 0 on error. -The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. +The error codes can be obtained by L<ERR_get_error(3)>. =head1 SEE ALSO -L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<BN_add(3)|BN_add(3)>, -L<BN_CTX_new(3)|BN_CTX_new(3)> +L<ERR_get_error(3)>, L<BN_add(3)>, +L<BN_CTX_new(3)> =head1 HISTORY -B<BN_RECP_CTX> was added in SSLeay 0.9.0. Before that, the function -BN_reciprocal() was used instead, and the BN_mod_mul_reciprocal() -arguments were different. +BN_RECP_CTX_init() was removed in OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BN_new.pod b/deps/openssl/openssl/doc/crypto/BN_new.pod index d446603191..08aae5e919 100644 --- a/deps/openssl/openssl/doc/crypto/BN_new.pod +++ b/deps/openssl/openssl/doc/crypto/BN_new.pod @@ -2,7 +2,7 @@ =head1 NAME -BN_new, BN_init, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs +BN_new, BN_secure_new, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs =head1 SYNOPSIS @@ -10,7 +10,7 @@ BN_new, BN_init, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs BIGNUM *BN_new(void); - void BN_init(BIGNUM *); + BIGNUM *BN_secure_new(void); void BN_clear(BIGNUM *a); @@ -20,8 +20,9 @@ BN_new, BN_init, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs =head1 DESCRIPTION -BN_new() allocates and initializes a B<BIGNUM> structure. BN_init() -initializes an existing uninitialized B<BIGNUM>. +BN_new() allocates and initializes a B<BIGNUM> structure. +BN_secure_new() does the same except that the secure heap +OPENSSL_secure_malloc(3) is used to store the value. BN_clear() is used to destroy sensitive data such as keys when they are no longer needed. It erases the memory used by B<a> and sets it @@ -34,22 +35,29 @@ If B<a> is NULL, nothing is done. =head1 RETURN VALUES -BN_new() returns a pointer to the B<BIGNUM> initialised to the value 0. +BN_new() and BN_secure_new() +return a pointer to the B<BIGNUM> initialised to the value 0. If the allocation fails, -it returns B<NULL> and sets an error code that can be obtained -by L<ERR_get_error(3)|ERR_get_error(3)>. +they return B<NULL> and set an error code that can be obtained +by L<ERR_get_error(3)>. -BN_init(), BN_clear(), BN_free() and BN_clear_free() have no return -values. +BN_clear(), BN_free() and BN_clear_free() have no return values. =head1 SEE ALSO -L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)> +L<ERR_get_error(3)> =head1 HISTORY -BN_new(), BN_clear(), BN_free() and BN_clear_free() are available in -all versions on SSLeay and OpenSSL. BN_init() was added in SSLeay -0.9.1b. +BN_init() was removed in OpenSSL 1.1.0; use BN_new() instead. + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BN_num_bytes.pod b/deps/openssl/openssl/doc/crypto/BN_num_bytes.pod index a6a2e3f819..9e0465de54 100644 --- a/deps/openssl/openssl/doc/crypto/BN_num_bytes.pod +++ b/deps/openssl/openssl/doc/crypto/BN_num_bytes.pod @@ -46,12 +46,16 @@ more probability). =head1 SEE ALSO -L<bn(3)|bn(3)>, L<DH_size(3)|DH_size(3)>, L<DSA_size(3)|DSA_size(3)>, -L<RSA_size(3)|RSA_size(3)> +L<DH_size(3)>, L<DSA_size(3)>, +L<RSA_size(3)> -=head1 HISTORY +=head1 COPYRIGHT -BN_num_bytes(), BN_num_bits() and BN_num_bits_word() are available in -all versions of SSLeay and OpenSSL. +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BN_rand.pod b/deps/openssl/openssl/doc/crypto/BN_rand.pod index a1513a9526..08d14de7ee 100644 --- a/deps/openssl/openssl/doc/crypto/BN_rand.pod +++ b/deps/openssl/openssl/doc/crypto/BN_rand.pod @@ -21,15 +21,18 @@ BN_rand, BN_pseudo_rand, BN_rand_range, BN_pseudo_rand_range - generate pseudo-r BN_rand() generates a cryptographically strong pseudo-random number of B<bits> in length and stores it in B<rnd>. If B<bits> is less than zero, or too small to -accomodate the requirements specified by the B<top> and B<bottom> +accommodate the requirements specified by the B<top> and B<bottom> parameters, an error is returned. -If B<top> is -1, the -most significant bit of the random number can be zero. If B<top> is 0, -it is set to 1, and if B<top> is 1, the two most significant bits of +The B<top> parameters specifies +requirements on the most significant bit of the generated number. +If it is B<BN_RAND_TOP_ANY>, there is no constraint. +If it is B<BN_RAND_TOP_ONE>, the top bit must be one. +If it is B<BN_RAND_TOP_TWO>, the two most significant bits of the number will be set to 1, so that the product of two such random -numbers will always have 2*B<bits> length. If B<bottom> is true, the -number will be odd. The value of B<bits> must be zero or greater. If B<bits> is -1 then B<top> cannot also be 1. +numbers will always have 2*B<bits> length. +If B<bottom> is B<BN_RAND_BOTTOM_ODD>, the number will be odd; if it +is B<BN_RAND_BOTTOM_ANY> it can be odd or even. +If B<bits> is 1 then B<top> cannot also be B<BN_RAND_FLG_TOPTWO>. BN_pseudo_rand() does the same, but pseudo-random numbers generated by this function are not necessarily unpredictable. They can be used for @@ -46,18 +49,19 @@ The PRNG must be seeded prior to calling BN_rand() or BN_rand_range(). =head1 RETURN VALUES The functions return 1 on success, 0 on error. -The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. +The error codes can be obtained by L<ERR_get_error(3)>. =head1 SEE ALSO -L<bn(3)|bn(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, -L<RAND_add(3)|RAND_add(3)>, L<RAND_bytes(3)|RAND_bytes(3)> +L<ERR_get_error(3)>, L<RAND_add(3)>, L<RAND_bytes(3)> -=head1 HISTORY +=head1 COPYRIGHT -BN_rand() is available in all versions of SSLeay and OpenSSL. -BN_pseudo_rand() was added in OpenSSL 0.9.5. The B<top> == -1 case -and the function BN_rand_range() were added in OpenSSL 0.9.6a. -BN_pseudo_rand_range() was added in OpenSSL 0.9.6c. +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BN_set_bit.pod b/deps/openssl/openssl/doc/crypto/BN_set_bit.pod index a32cca2cee..af02983c8f 100644 --- a/deps/openssl/openssl/doc/crypto/BN_set_bit.pod +++ b/deps/openssl/openssl/doc/crypto/BN_set_bit.pod @@ -51,16 +51,19 @@ For the shift functions, B<r> and B<a> may be the same variable. BN_is_bit_set() returns 1 if the bit is set, 0 otherwise. All other functions return 1 for success, 0 on error. The error codes -can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. +can be obtained by L<ERR_get_error(3)>. =head1 SEE ALSO -L<bn(3)|bn(3)>, L<BN_num_bytes(3)|BN_num_bytes(3)>, L<BN_add(3)|BN_add(3)> +L<BN_num_bytes(3)>, L<BN_add(3)> -=head1 HISTORY +=head1 COPYRIGHT -BN_set_bit(), BN_clear_bit(), BN_is_bit_set(), BN_mask_bits(), -BN_lshift(), BN_lshift1(), BN_rshift(), and BN_rshift1() are available -in all versions of SSLeay and OpenSSL. +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BN_swap.pod b/deps/openssl/openssl/doc/crypto/BN_swap.pod index 79efaa1446..9f77f22744 100644 --- a/deps/openssl/openssl/doc/crypto/BN_swap.pod +++ b/deps/openssl/openssl/doc/crypto/BN_swap.pod @@ -14,10 +14,13 @@ BN_swap - exchange BIGNUMs BN_swap() exchanges the values of I<a> and I<b>. -L<bn(3)|bn(3)> +=head1 COPYRIGHT -=head1 HISTORY +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. -BN_swap was added in OpenSSL 0.9.7. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BN_zero.pod b/deps/openssl/openssl/doc/crypto/BN_zero.pod index 8aa9c142b7..2ca8850f2d 100644 --- a/deps/openssl/openssl/doc/crypto/BN_zero.pod +++ b/deps/openssl/openssl/doc/crypto/BN_zero.pod @@ -9,7 +9,7 @@ operations #include <openssl/bn.h> - int BN_zero(BIGNUM *a); + void BN_zero(BIGNUM *a); int BN_one(BIGNUM *a); const BIGNUM *BN_value_one(void); @@ -17,6 +17,12 @@ operations int BN_set_word(BIGNUM *a, BN_ULONG w); BN_ULONG BN_get_word(BIGNUM *a); +Deprecated: + + #if OPENSSL_API_COMPAT < 0x00908000L + int BN_zero(BIGNUM *a); + #endif + =head1 DESCRIPTION B<BN_ULONG> is a macro that will be an unsigned integral type optimied @@ -35,8 +41,10 @@ BN_get_word() returns B<a>, if it can be represented as a B<BN_ULONG>. BN_get_word() returns the value B<a>, or all-bits-set if B<a> cannot be represented as a B<BN_ULONG>. -BN_zero(), BN_one() and BN_set_word() return 1 on success, 0 otherwise. +BN_one(), BN_set_word() and the deprecated version of BN_zero() +return 1 on success, 0 otherwise. BN_value_one() returns the constant. +The preferred version of BN_zero() never fails and returns no value. =head1 BUGS @@ -48,15 +56,15 @@ B<BN_ULONG> should probably be a typedef. =head1 SEE ALSO -L<bn(3)|bn(3)>, L<BN_bn2bin(3)|BN_bn2bin(3)> +L<BN_bn2bin(3)> -=head1 HISTORY +=head1 COPYRIGHT -BN_zero(), BN_one() and BN_set_word() are available in all versions of -SSLeay and OpenSSL. BN_value_one() and BN_get_word() were added in -SSLeay 0.8. +Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. -BN_value_one() was changed to return a true const BIGNUM * in OpenSSL -0.9.7. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/BUF_MEM_new.pod b/deps/openssl/openssl/doc/crypto/BUF_MEM_new.pod new file mode 100644 index 0000000000..1d89159cc1 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/BUF_MEM_new.pod @@ -0,0 +1,77 @@ +=pod + +=head1 NAME + +BUF_MEM_new, BUF_MEM_new_ex, BUF_MEM_free, BUF_MEM_grow, +BUF_MEM_grow_clean, BUF_reverse +- simple character array structure + +standard C library equivalents + +=head1 SYNOPSIS + + #include <openssl/buffer.h> + + BUF_MEM *BUF_MEM_new(void); + + BUF_MEM *BUF_MEM_new_ex(unsigned long flags); + + void BUF_MEM_free(BUF_MEM *a); + + int BUF_MEM_grow(BUF_MEM *str, int len); + size_t BUF_MEM_grow_clean(BUF_MEM *str, size_t len); + + void BUF_reverse(unsigned char *out, const unsigned char *in, size_t size); + +=head1 DESCRIPTION + +The buffer library handles simple character arrays. Buffers are used for +various purposes in the library, most notably memory BIOs. + +BUF_MEM_new() allocates a new buffer of zero size. + +BUF_MEM_new_ex() allocates a buffer with the specified flags. +The flag B<BUF_MEM_FLAG_SECURE> specifies that the B<data> pointer +should be allocated on the secure heap; see L<CRYPTO_secure_malloc(3)>. + +BUF_MEM_free() frees up an already existing buffer. The data is zeroed +before freeing up in case the buffer contains sensitive data. + +BUF_MEM_grow() changes the size of an already existing buffer to +B<len>. Any data already in the buffer is preserved if it increases in +size. + +BUF_MEM_grow_clean() is similar to BUF_MEM_grow() but it sets any free'd +or additionally-allocated memory to zero. + +BUF_reverse() reverses B<size> bytes at B<in> into B<out>. If B<in> +is NULL, the array is reversed in-place. + +=head1 RETURN VALUES + +BUF_MEM_new() returns the buffer or NULL on error. + +BUF_MEM_free() has no return value. + +BUF_MEM_grow() and BUF_MEM_grow_clean() return +zero on error or the new size (i.e., B<len>). + +=head1 SEE ALSO + +L<bio(7)>, +L<CRYPTO_secure_malloc(3)>. + +=head1 HISTORY + +BUF_MEM_new_ex() was added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/CMS_add0_cert.pod b/deps/openssl/openssl/doc/crypto/CMS_add0_cert.pod index 8678ca18a5..a5be002de4 100644 --- a/deps/openssl/openssl/doc/crypto/CMS_add0_cert.pod +++ b/deps/openssl/openssl/doc/crypto/CMS_add0_cert.pod @@ -2,7 +2,8 @@ =head1 NAME -CMS_add0_cert, CMS_add1_cert, CMS_get1_certs, CMS_add0_crl, CMS_add1_crl, CMS_get1_crls, - CMS certificate and CRL utility functions +CMS_add0_cert, CMS_add1_cert, CMS_get1_certs, CMS_add0_crl, CMS_add1_crl, CMS_get1_crls +- CMS certificate and CRL utility functions =head1 SYNOPSIS @@ -20,7 +21,7 @@ CMS_add0_cert, CMS_add1_cert, CMS_get1_certs, CMS_add0_crl, CMS_add1_crl, CMS_ge =head1 DESCRIPTION CMS_add0_cert() and CMS_add1_cert() add certificate B<cert> to B<cms>. -must be of type signed data or enveloped data. +must be of type signed data or enveloped data. CMS_get1_certs() returns all certificates in B<cms>. @@ -46,7 +47,7 @@ than once. =head1 RETURN VALUES CMS_add0_cert(), CMS_add1_cert() and CMS_add0_crl() and CMS_add1_crl() return -1 for success and 0 for failure. +1 for success and 0 for failure. CMS_get1_certs() and CMS_get1_crls() return the STACK of certificates or CRLs or NULL if there are none or an error occurs. The only error which will occur @@ -54,13 +55,17 @@ in practice is if the B<cms> type is invalid. =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, -L<CMS_sign(3)|CMS_sign(3)>, -L<CMS_encrypt(3)|CMS_encrypt(3)> +L<ERR_get_error(3)>, +L<CMS_sign(3)>, +L<CMS_encrypt(3)> -=head1 HISTORY +=head1 COPYRIGHT -CMS_add0_cert(), CMS_add1_cert(), CMS_get1_certs(), CMS_add0_crl() -and CMS_get1_crls() were all first added to OpenSSL 0.9.8 +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/CMS_add1_recipient_cert.pod b/deps/openssl/openssl/doc/crypto/CMS_add1_recipient_cert.pod index d7d8e2532c..0dae5cf5fa 100644 --- a/deps/openssl/openssl/doc/crypto/CMS_add1_recipient_cert.pod +++ b/deps/openssl/openssl/doc/crypto/CMS_add1_recipient_cert.pod @@ -2,7 +2,7 @@ =head1 NAME - CMS_add1_recipient_cert, CMS_add0_recipient_key - add recipients to a CMS enveloped data structure +CMS_add1_recipient_cert, CMS_add0_recipient_key - add recipients to a CMS enveloped data structure =head1 SYNOPSIS @@ -51,12 +51,16 @@ occurs. =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_decrypt(3)|CMS_decrypt(3)>, -L<CMS_final(3)|CMS_final(3)>, +L<ERR_get_error(3)>, L<CMS_decrypt(3)>, +L<CMS_final(3)>, -=head1 HISTORY +=head1 COPYRIGHT -CMS_add1_recipient_cert() and CMS_add0_recipient_key() were added to OpenSSL -0.9.8 +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/CMS_add1_signer.pod b/deps/openssl/openssl/doc/crypto/CMS_add1_signer.pod index a055b82695..f4738e0637 100644 --- a/deps/openssl/openssl/doc/crypto/CMS_add1_signer.pod +++ b/deps/openssl/openssl/doc/crypto/CMS_add1_signer.pod @@ -2,7 +2,7 @@ =head1 NAME - CMS_add1_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure. +CMS_add1_signer, CMS_SignerInfo_sign - add a signer to a CMS_ContentInfo signed data structure =head1 SYNOPSIS @@ -52,7 +52,7 @@ structure. An error occurs if a matching digest value cannot be found to copy. The returned CMS_ContentInfo structure will be valid and finalized when this flag is set. -If B<CMS_PARTIAL> is set in addition to B<CMS_REUSE_DIGEST> then the +If B<CMS_PARTIAL> is set in addition to B<CMS_REUSE_DIGEST> then the CMS_SignerInfo structure will not be finalized so additional attributes can be added. In this case an explicit call to CMS_SignerInfo_sign() is needed to finalize it. @@ -81,7 +81,7 @@ If any of these algorithms is not available then it will not be included: for ex not loaded. CMS_add1_signer() returns an internal pointer to the CMS_SignerInfo -structure just added, this can be used to set additional attributes +structure just added, this can be used to set additional attributes before it is finalized. =head1 RETURN VALUES @@ -91,11 +91,16 @@ structure just added or NULL if an error occurs. =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>, -L<CMS_final(3)|CMS_final(3)>, +L<ERR_get_error(3)>, L<CMS_sign(3)>, +L<CMS_final(3)>, -=head1 HISTORY +=head1 COPYRIGHT -CMS_add1_signer() was added to OpenSSL 0.9.8 +Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/CMS_compress.pod b/deps/openssl/openssl/doc/crypto/CMS_compress.pod index 0a0715271d..e40510831f 100644 --- a/deps/openssl/openssl/doc/crypto/CMS_compress.pod +++ b/deps/openssl/openssl/doc/crypto/CMS_compress.pod @@ -63,11 +63,19 @@ occurred. The error can be obtained from ERR_get_error(3). =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_uncompress(3)|CMS_uncompress(3)> +L<ERR_get_error(3)>, L<CMS_uncompress(3)> =head1 HISTORY -CMS_compress() was added to OpenSSL 0.9.8 -The B<CMS_STREAM> flag was first supported in OpenSSL 1.0.0. +The B<CMS_STREAM> flag was added in OpenSSL 1.0.0. + +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/CMS_decrypt.pod b/deps/openssl/openssl/doc/crypto/CMS_decrypt.pod index 3fa9212af3..b3b196c390 100644 --- a/deps/openssl/openssl/doc/crypto/CMS_decrypt.pod +++ b/deps/openssl/openssl/doc/crypto/CMS_decrypt.pod @@ -2,7 +2,7 @@ =head1 NAME - CMS_decrypt - decrypt content from a CMS envelopedData structure +CMS_decrypt - decrypt content from a CMS envelopedData structure =head1 SYNOPSIS @@ -22,9 +22,6 @@ is detached. It will normally be set to NULL. =head1 NOTES -OpenSSL_add_all_algorithms() (or equivalent) should be called before using this -function or errors about unknown algorithms will occur. - Although the recipients certificate is not needed to decrypt the data it is needed to locate the appropriate (of possible several) recipients in the CMS structure. @@ -70,10 +67,15 @@ mentioned in CMS_verify() also applies to CMS_decrypt(). =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)> +L<ERR_get_error(3)>, L<CMS_encrypt(3)> + +=head1 COPYRIGHT -=head1 HISTORY +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. -CMS_decrypt() was added to OpenSSL 0.9.8 +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/CMS_encrypt.pod b/deps/openssl/openssl/doc/crypto/CMS_encrypt.pod index 1ee5b275ec..0ed42628c3 100644 --- a/deps/openssl/openssl/doc/crypto/CMS_encrypt.pod +++ b/deps/openssl/openssl/doc/crypto/CMS_encrypt.pod @@ -2,7 +2,7 @@ =head1 NAME - CMS_encrypt - create a CMS envelopedData structure +CMS_encrypt - create a CMS envelopedData structure =head1 SYNOPSIS @@ -26,7 +26,7 @@ EVP_des_ede3_cbc() (triple DES) is the algorithm of choice for S/MIME use because most clients will support it. The algorithm passed in the B<cipher> parameter must support ASN1 encoding of -its parameters. +its parameters. Many browsers implement a "sign and encrypt" option which is simply an S/MIME envelopedData containing an S/MIME signed message. This can be readily produced @@ -86,11 +86,19 @@ occurred. The error can be obtained from ERR_get_error(3). =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_decrypt(3)|CMS_decrypt(3)> +L<ERR_get_error(3)>, L<CMS_decrypt(3)> =head1 HISTORY -CMS_decrypt() was added to OpenSSL 0.9.8 The B<CMS_STREAM> flag was first supported in OpenSSL 1.0.0. +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/CMS_final.pod b/deps/openssl/openssl/doc/crypto/CMS_final.pod index 36cf96b8a0..264fe7bc3b 100644 --- a/deps/openssl/openssl/doc/crypto/CMS_final.pod +++ b/deps/openssl/openssl/doc/crypto/CMS_final.pod @@ -2,7 +2,7 @@ =head1 NAME - CMS_final - finalise a CMS_ContentInfo structure +CMS_final - finalise a CMS_ContentInfo structure =head1 SYNOPSIS @@ -14,7 +14,7 @@ CMS_final() finalises the structure B<cms>. It's purpose is to perform any operations necessary on B<cms> (digest computation for example) and set the -appropriate fields. The parameter B<data> contains the content to be +appropriate fields. The parameter B<data> contains the content to be processed. The B<dcont> parameter contains a BIO to write content to after processing: this is only used with detached data and will usually be set to NULL. @@ -31,11 +31,16 @@ CMS_final() returns 1 for success or 0 for failure. =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>, -L<CMS_encrypt(3)|CMS_encrypt(3)> +L<ERR_get_error(3)>, L<CMS_sign(3)>, +L<CMS_encrypt(3)> -=head1 HISTORY +=head1 COPYRIGHT -CMS_final() was added to OpenSSL 0.9.8 +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/CMS_get0_RecipientInfos.pod b/deps/openssl/openssl/doc/crypto/CMS_get0_RecipientInfos.pod index fe49772a86..6c33c224e9 100644 --- a/deps/openssl/openssl/doc/crypto/CMS_get0_RecipientInfos.pod +++ b/deps/openssl/openssl/doc/crypto/CMS_get0_RecipientInfos.pod @@ -2,7 +2,12 @@ =head1 NAME -CMS_get0_RecipientInfos, CMS_RecipientInfo_type, CMS_RecipientInfo_ktri_get0_signer_id,CMS_RecipientInfo_ktri_cert_cmp, CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id, CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key, CMS_RecipientInfo_decrypt, CMS_RecipientInfo_encrypt - CMS envelopedData RecipientInfo routines +CMS_get0_RecipientInfos, CMS_RecipientInfo_type, +CMS_RecipientInfo_ktri_get0_signer_id, CMS_RecipientInfo_ktri_cert_cmp, +CMS_RecipientInfo_set0_pkey, CMS_RecipientInfo_kekri_get0_id, +CMS_RecipientInfo_kekri_id_cmp, CMS_RecipientInfo_set0_key, +CMS_RecipientInfo_decrypt, CMS_RecipientInfo_encrypt +- CMS envelopedData RecipientInfo routines =head1 SYNOPSIS @@ -34,7 +39,7 @@ CMS_RECIPINFO_KEK, CMS_RECIPINFO_PASS, or CMS_RECIPINFO_OTHER. CMS_RecipientInfo_ktri_get0_signer_id() retrieves the certificate recipient identifier associated with a specific CMS_RecipientInfo structure B<ri>, which must be of type CMS_RECIPINFO_TRANS. Either the keyidentifier will be set in -B<keyid> or B<both> issuer name and serial number in B<issuer> and B<sno>. +B<keyid> or B<both> issuer name and serial number in B<issuer> and B<sno>. CMS_RecipientInfo_ktri_cert_cmp() compares the certificate B<cert> against the CMS_RecipientInfo structure B<ri>, which must be of type CMS_RECIPINFO_TRANS. @@ -107,14 +112,19 @@ CMS_RecipientInfo_encrypt() return 1 for success or 0 if an error occurs. CMS_RecipientInfo_ktri_cert_cmp() and CMS_RecipientInfo_kekri_cmp() return 0 for a successful comparison and non zero otherwise. -Any error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>. +Any error can be obtained from L<ERR_get_error(3)>. =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_decrypt(3)|CMS_decrypt(3)> +L<ERR_get_error(3)>, L<CMS_decrypt(3)> -=head1 HISTORY +=head1 COPYRIGHT -These functions were first was added to OpenSSL 0.9.8 +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/CMS_get0_SignerInfos.pod b/deps/openssl/openssl/doc/crypto/CMS_get0_SignerInfos.pod index b46c0e07ab..e5532c96f4 100644 --- a/deps/openssl/openssl/doc/crypto/CMS_get0_SignerInfos.pod +++ b/deps/openssl/openssl/doc/crypto/CMS_get0_SignerInfos.pod @@ -2,7 +2,10 @@ =head1 NAME -CMS_get0_SignerInfos, CMS_SignerInfo_get0_signer_id, CMS_SignerInfo_get0_signature, CMS_SignerInfo_cert_cmp, CMS_set1_signer_cert - CMS signedData signer functions. +CMS_SignerInfo_set1_signer_cert, +CMS_get0_SignerInfos, CMS_SignerInfo_get0_signer_id, +CMS_SignerInfo_get0_signature, CMS_SignerInfo_cert_cmp +- CMS signedData signer functions =head1 SYNOPSIS @@ -25,7 +28,7 @@ associated with a specific CMS_SignerInfo structure B<si>. Either the keyidentifier will be set in B<keyid> or B<both> issuer name and serial number in B<issuer> and B<sno>. -CMS_SignerInfo_get0_signature() retrieves the signature associated with +CMS_SignerInfo_get0_signature() retrieves the signature associated with B<si> in a pointer to an ASN1_OCTET_STRING structure. This pointer returned corresponds to the internal signature value if B<si> so it may be read or modified. @@ -68,14 +71,19 @@ zero otherwise. CMS_SignerInfo_set1_signer_cert() does not return a value. -Any error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)> +Any error can be obtained from L<ERR_get_error(3)> =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_verify(3)|CMS_verify(3)> +L<ERR_get_error(3)>, L<CMS_verify(3)> -=head1 HISTORY +=head1 COPYRIGHT -These functions were first was added to OpenSSL 0.9.8 +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/CMS_get0_type.pod b/deps/openssl/openssl/doc/crypto/CMS_get0_type.pod index 3ed92bdbbe..cad8d3f662 100644 --- a/deps/openssl/openssl/doc/crypto/CMS_get0_type.pod +++ b/deps/openssl/openssl/doc/crypto/CMS_get0_type.pod @@ -2,13 +2,13 @@ =head1 NAME - CMS_get0_type, CMS_set1_eContentType, CMS_get0_eContentType, CMS_get0_content - get and set CMS content types and content +CMS_get0_type, CMS_set1_eContentType, CMS_get0_eContentType, CMS_get0_content - get and set CMS content types and content =head1 SYNOPSIS #include <openssl/cms.h> - const ASN1_OBJECT *CMS_get0_type(CMS_ContentInfo *cms); + const ASN1_OBJECT *CMS_get0_type(const CMS_ContentInfo *cms); int CMS_set1_eContentType(CMS_ContentInfo *cms, const ASN1_OBJECT *oid); const ASN1_OBJECT *CMS_get0_eContentType(CMS_ContentInfo *cms); ASN1_OCTET_STRING **CMS_get0_content(CMS_ContentInfo *cms); @@ -67,11 +67,15 @@ error can be obtained from ERR_get_error(3). =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)> +L<ERR_get_error(3)> -=head1 HISTORY +=head1 COPYRIGHT -CMS_get0_type(), CMS_set1_eContentType() and CMS_get0_eContentType() were all -first added to OpenSSL 0.9.8 +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/CMS_get1_ReceiptRequest.pod b/deps/openssl/openssl/doc/crypto/CMS_get1_ReceiptRequest.pod index f546376a1e..79f5f4232d 100644 --- a/deps/openssl/openssl/doc/crypto/CMS_get1_ReceiptRequest.pod +++ b/deps/openssl/openssl/doc/crypto/CMS_get1_ReceiptRequest.pod @@ -2,7 +2,7 @@ =head1 NAME - CMS_ReceiptRequest_create0, CMS_add1_ReceiptRequest, CMS_get1_ReceiptRequest, CMS_ReceiptRequest_get0_values - CMS signed receipt request functions. +CMS_ReceiptRequest_create0, CMS_add1_ReceiptRequest, CMS_get1_ReceiptRequest, CMS_ReceiptRequest_get0_values - CMS signed receipt request functions =head1 SYNOPSIS @@ -45,7 +45,7 @@ CMS_verify(). =head1 RETURN VALUES -CMS_ReceiptRequest_create0() returns a signed receipt request structure or +CMS_ReceiptRequest_create0() returns a signed receipt request structure or NULL if an error occurred. CMS_add1_ReceiptRequest() returns 1 for success or 0 is an error occurred. @@ -56,14 +56,17 @@ it is present but malformed. =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>, -L<CMS_sign_receipt(3)|CMS_sign_receipt(3)>, L<CMS_verify(3)|CMS_verify(3)> -L<CMS_verify_receipt(3)|CMS_verify_receipt(3)> +L<ERR_get_error(3)>, L<CMS_sign(3)>, +L<CMS_sign_receipt(3)>, L<CMS_verify(3)> +L<CMS_verify_receipt(3)> -=head1 HISTORY +=head1 COPYRIGHT -CMS_ReceiptRequest_create0(), CMS_add1_ReceiptRequest(), -CMS_get1_ReceiptRequest() and CMS_ReceiptRequest_get0_values() were added to -OpenSSL 0.9.8 +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/CMS_sign.pod b/deps/openssl/openssl/doc/crypto/CMS_sign.pod index 2cc72de327..396deef772 100644 --- a/deps/openssl/openssl/doc/crypto/CMS_sign.pod +++ b/deps/openssl/openssl/doc/crypto/CMS_sign.pod @@ -2,7 +2,7 @@ =head1 NAME - CMS_sign - create a CMS SignedData structure +CMS_sign - create a CMS SignedData structure =head1 SYNOPSIS @@ -95,8 +95,8 @@ suitable for many purposes. For finer control of the output format the B<certs>, B<signcert> and B<pkey> parameters can all be B<NULL> and the B<CMS_PARTIAL> flag set. Then one or more signers can be added using the function CMS_sign_add1_signer(), non default digests can be used and custom -attributes added. B<CMS_final()> must then be called to finalize the -structure if streaming is not enabled. +attributes added. CMS_final() must then be called to finalize the +structure if streaming is not enabled. =head1 BUGS @@ -109,13 +109,20 @@ occurred. The error can be obtained from ERR_get_error(3). =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_verify(3)|CMS_verify(3)> +L<ERR_get_error(3)>, L<CMS_verify(3)> =head1 HISTORY -CMS_sign() was added to OpenSSL 0.9.8 - The B<CMS_STREAM> flag is only supported for detached data in OpenSSL 0.9.8, it is supported for embedded data in OpenSSL 1.0.0 and later. +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/CMS_sign_receipt.pod b/deps/openssl/openssl/doc/crypto/CMS_sign_receipt.pod index cae1f83384..8ea6df1fbc 100644 --- a/deps/openssl/openssl/doc/crypto/CMS_sign_receipt.pod +++ b/deps/openssl/openssl/doc/crypto/CMS_sign_receipt.pod @@ -2,7 +2,7 @@ =head1 NAME - CMS_sign_receipt - create a CMS signed receipt +CMS_sign_receipt - create a CMS signed receipt =head1 SYNOPSIS @@ -34,12 +34,17 @@ an error occurred. The error can be obtained from ERR_get_error(3). =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, -L<CMS_verify_receipt(3)|CMS_verify_receipt(3)>, -L<CMS_sign(3)|CMS_sign(3)> +L<ERR_get_error(3)>, +L<CMS_verify_receipt(3)>, +L<CMS_sign(3)> -=head1 HISTORY +=head1 COPYRIGHT -CMS_sign_receipt() was added to OpenSSL 0.9.8 +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/CMS_uncompress.pod b/deps/openssl/openssl/doc/crypto/CMS_uncompress.pod index c6056b027d..80f9c0d168 100644 --- a/deps/openssl/openssl/doc/crypto/CMS_uncompress.pod +++ b/deps/openssl/openssl/doc/crypto/CMS_uncompress.pod @@ -2,7 +2,7 @@ =head1 NAME - CMS_uncompress - uncompress a CMS CompressedData structure +CMS_uncompress - uncompress a CMS CompressedData structure =head1 SYNOPSIS @@ -45,10 +45,15 @@ mentioned in CMS_verify() also applies to CMS_decompress(). =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_compress(3)|CMS_compress(3)> +L<ERR_get_error(3)>, L<CMS_compress(3)> -=head1 HISTORY +=head1 COPYRIGHT -CMS_uncompress() was added to OpenSSL 0.9.8 +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/CMS_verify.pod b/deps/openssl/openssl/doc/crypto/CMS_verify.pod index 7a2c1ee251..c2ff57bcf2 100644 --- a/deps/openssl/openssl/doc/crypto/CMS_verify.pod +++ b/deps/openssl/openssl/doc/crypto/CMS_verify.pod @@ -67,7 +67,7 @@ returned. If B<CMS_NO_SIGNER_CERT_VERIFY> is set the signing certificates are not verified. -If B<CMS_NO_ATTR_VERIFY> is set the signed attributes signature is not +If B<CMS_NO_ATTR_VERIFY> is set the signed attributes signature is not verified. If B<CMS_NO_CONTENT_VERIFY> is set then the content digest is not checked. @@ -81,13 +81,13 @@ certificates supplied in B<certs> then the verify will fail because the signer cannot be found. In some cases the standard techniques for looking up and validating -certificates are not appropriate: for example an application may wish to +certificates are not appropriate: for example an application may wish to lookup certificates in a database or perform customised verification. This -can be achieved by setting and verifying the signers certificates manually +can be achieved by setting and verifying the signers certificates manually using the signed data utility functions. Care should be taken when modifying the default verify behaviour, for example -setting B<CMS_NO_CONTENT_VERIFY> will totally disable all content verification +setting B<CMS_NO_CONTENT_VERIFY> will totally disable all content verification and any modified content will be considered valid. This combination is however useful if one merely wishes to write the content to B<out> and its validity is not considered important. @@ -104,7 +104,7 @@ occurred. CMS_get0_signers() returns all signers or NULL if an error occurred. -The error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)> +The error can be obtained from L<ERR_get_error(3)> =head1 BUGS @@ -117,10 +117,15 @@ be held in memory if it is not detached. =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)> +L<ERR_get_error(3)>, L<CMS_sign(3)> -=head1 HISTORY +=head1 COPYRIGHT -CMS_verify() was added to OpenSSL 0.9.8 +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/CMS_verify_receipt.pod b/deps/openssl/openssl/doc/crypto/CMS_verify_receipt.pod index 9283e0e04b..193241c620 100644 --- a/deps/openssl/openssl/doc/crypto/CMS_verify_receipt.pod +++ b/deps/openssl/openssl/doc/crypto/CMS_verify_receipt.pod @@ -2,7 +2,7 @@ =head1 NAME - CMS_verify_receipt - verify a CMS signed receipt +CMS_verify_receipt - verify a CMS signed receipt =head1 SYNOPSIS @@ -16,7 +16,7 @@ CMS_verify_receipt() verifies a CMS signed receipt. B<rcms> is the signed receipt to verify. B<ocms> is the original SignedData structure containing the receipt request. B<certs> is a set of certificates in which to search for the signing certificate. B<store> is a trusted certificate store (used for chain -verification). +verification). B<flags> is an optional set of flags, which can be used to modify the verify operation. @@ -32,16 +32,21 @@ supported since they do not make sense in the context of signed receipts. CMS_verify_receipt() returns 1 for a successful verification and zero if an error occurred. -The error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)> +The error can be obtained from L<ERR_get_error(3)> =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, -L<CMS_sign_receipt(3)|CMS_sign_receipt(3)>, -L<CMS_verify(3)|CMS_verify(3)>, +L<ERR_get_error(3)>, +L<CMS_sign_receipt(3)>, +L<CMS_verify(3)>, -=head1 HISTORY +=head1 COPYRIGHT -CMS_verify_receipt() was added to OpenSSL 0.9.8 +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/CONF_modules_free.pod b/deps/openssl/openssl/doc/crypto/CONF_modules_free.pod index 347020c5fe..ac59f3736a 100644 --- a/deps/openssl/openssl/doc/crypto/CONF_modules_free.pod +++ b/deps/openssl/openssl/doc/crypto/CONF_modules_free.pod @@ -2,17 +2,22 @@ =head1 NAME - CONF_modules_free, CONF_modules_finish, CONF_modules_unload - - OpenSSL configuration cleanup functions +CONF_modules_free, CONF_modules_finish, CONF_modules_unload - +OpenSSL configuration cleanup functions =head1 SYNOPSIS #include <openssl/conf.h> - void CONF_modules_free(void); void CONF_modules_finish(void); void CONF_modules_unload(int all); +Deprecated: + + #if OPENSSL_API_COMPAT < 0x10100000L + void CONF_modules_free(void) + #endif + =head1 DESCRIPTION CONF_modules_free() closes down and frees up all memory allocated by all @@ -27,8 +32,10 @@ B<all> is B<1> all modules, including builtin modules will be unloaded. =head1 NOTES -Normally applications will only call CONF_modules_free() at application to -tidy up any configuration performed. +Normally in versions of OpenSSL prior to 1.1.0 applications will only call +CONF_modules_free() at application exit to tidy up any configuration performed. +From 1.1.0 CONF_modules_free() is deprecated and no explicit CONF cleanup is +required at all. For more information see L<OPENSSL_init_crypto(3)>. =head1 RETURN VALUE @@ -36,12 +43,20 @@ None of the functions return a value. =head1 SEE ALSO -L<conf(5)|conf(5)>, L<OPENSSL_config(3)|OPENSSL_config(3)>, -L<CONF_modules_load_file(3)|CONF_modules_load_file(3)> +L<conf(5)>, L<OPENSSL_config(3)>, +L<CONF_modules_load_file(3)> =head1 HISTORY -CONF_modules_free(), CONF_modules_unload(), and CONF_modules_finish() -first appeared in OpenSSL 0.9.7. +CONF_modules_free() was deprecated in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/CONF_modules_load_file.pod b/deps/openssl/openssl/doc/crypto/CONF_modules_load_file.pod index cc0b537b8e..4f02f52f6a 100644 --- a/deps/openssl/openssl/doc/crypto/CONF_modules_load_file.pod +++ b/deps/openssl/openssl/doc/crypto/CONF_modules_load_file.pod @@ -2,16 +2,16 @@ =head1 NAME - CONF_modules_load_file, CONF_modules_load - OpenSSL configuration functions +CONF_modules_load_file, CONF_modules_load - OpenSSL configuration functions =head1 SYNOPSIS #include <openssl/conf.h> int CONF_modules_load_file(const char *filename, const char *appname, - unsigned long flags); + unsigned long flags); int CONF_modules_load(const CONF *cnf, const char *appname, - unsigned long flags); + unsigned long flags); =head1 DESCRIPTION @@ -19,9 +19,9 @@ The function CONF_modules_load_file() configures OpenSSL using file B<filename> and application name B<appname>. If B<filename> is NULL the standard OpenSSL configuration file is used. If B<appname> is NULL the standard OpenSSL application name B<openssl_conf> is used. -The behaviour can be cutomized using B<flags>. +The behaviour can be customized using B<flags>. -CONF_modules_load() is idential to CONF_modules_load_file() except it +CONF_modules_load() is identical to CONF_modules_load_file() except it reads configuration information from B<cnf>. =head1 NOTES @@ -45,12 +45,6 @@ return an error. B<CONF_MFLAGS_DEFAULT_SECTION> if set and B<appname> is not NULL will use the default section pointed to by B<openssl_conf> if B<appname> does not exist. -Applications should call these functions after loading builtin modules using -OPENSSL_load_builtin_modules(), any ENGINEs for example using -ENGINE_load_builtin_engines(), any algorithms for example -OPENSSL_add_all_algorithms() and (if the application uses libssl) -SSL_library_init(). - By using CONF_modules_load_file() with appropriate flags an application can customise application configuration to best suit its needs. In some cases the use of a configuration file is optional and its absence is not an error: in @@ -127,11 +121,15 @@ return value of the failing module (this will always be zero or negative). =head1 SEE ALSO -L<conf(5)|conf(5)>, L<OPENSSL_config(3)|OPENSSL_config(3)>, -L<CONF_free(3)|CONF_free(3)>, L<err(3)|err(3)> +L<config(5)>, L<OPENSSL_config(3)> + +=head1 COPYRIGHT -=head1 HISTORY +Copyright 2004-2017 The OpenSSL Project Authors. All Rights Reserved. -CONF_modules_load_file and CONF_modules_load first appeared in OpenSSL 0.9.7. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/CRYPTO_THREAD_run_once.pod b/deps/openssl/openssl/doc/crypto/CRYPTO_THREAD_run_once.pod new file mode 100644 index 0000000000..b256a18637 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/CRYPTO_THREAD_run_once.pod @@ -0,0 +1,170 @@ +=pod + +=head1 NAME + +CRYPTO_THREAD_run_once, +CRYPTO_THREAD_lock_new, CRYPTO_THREAD_read_lock, CRYPTO_THREAD_write_lock, +CRYPTO_THREAD_unlock, CRYPTO_THREAD_lock_free, CRYPTO_atomic_add - OpenSSL thread support + +=head1 SYNOPSIS + + #include <openssl/crypto.h> + + CRYPTO_ONCE CRYPTO_ONCE_STATIC_INIT; + int CRYPTO_THREAD_run_once(CRYPTO_ONCE *once, void (*init)(void)); + + CRYPTO_RWLOCK *CRYPTO_THREAD_lock_new(void); + int CRYPTO_THREAD_read_lock(CRYPTO_RWLOCK *lock); + int CRYPTO_THREAD_write_lock(CRYPTO_RWLOCK *lock); + int CRYPTO_THREAD_unlock(CRYPTO_RWLOCK *lock); + void CRYPTO_THREAD_lock_free(CRYPTO_RWLOCK *lock); + + int CRYPTO_atomic_add(int *val, int amount, int *ret, CRYPTO_RWLOCK *lock); + +=head1 DESCRIPTION + +OpenSSL can be safely used in multi-threaded applications provided that +support for the underlying OS threading API is built-in. Currently, OpenSSL +supports the pthread and Windows APIs. OpenSSL can also be built without +any multi-threading support, for example on platforms that don't provide +any threading support or that provide a threading API that is not yet +supported by OpenSSL. + +The following multi-threading function are provided: + +=over 2 + +=item * + +CRYPTO_THREAD_run_once() can be used to perform one-time initialization. +The B<once> argument must be a pointer to a static object of type +B<CRYPTO_ONCE> that was statically initialized to the value +B<CRYPTO_ONCE_STATIC_INIT>. +The B<init> argument is a pointer to a function that performs the desired +exactly once initialization. +In particular, this can be used to allocate locks in a thread-safe manner, +which can then be used with the locking functions below. + +=item * + +CRYPTO_THREAD_lock_new() allocates, initializes and returns a new read/write +lock. + +=item * + +CRYPTO_THREAD_read_lock() locks the provided B<lock> for reading. + +=item * + +CRYPTO_THREAD_write_lock() locks the provided B<lock> for writing. + +=item * + +CRYPTO_THREAD_unlock() unlocks the previously locked B<lock>. + +=item * + +CRYPTO_THREAD_lock_frees() frees the provided B<lock>. + +=item * + +CRYPTO_atomic_add() atomically adds B<amount> to B<val> and returns the +result of the operation in B<ret>. B<lock> will be locked, unless atomic +operations are supported on the specific platform. Because of this, if a +variable is modified by CRYPTO_atomic_add() then CRYPTO_atomic_add() must +be the only way that the variable is modified. + +=back + +=head1 RETURN VALUES + +CRYPTO_THREAD_run_once() returns 1 on success, or 0 on error. + +CRYPTO_THREAD_lock_new() returns the allocated lock, or NULL on error. + +CRYPTO_THREAD_lock_frees() returns no value. + +The other functions return 1 on success or 0 on error. + +=head1 NOTES + +On Windows platforms the CRYPTO_THREAD_* types and functions in the +openssl/crypto.h header are dependent on some of the types customarily +made available by including windows.h. The application developer is +likely to require control over when the latter is included, commonly as +one of the first included headers. Therefore it is defined as an +application developer's responsibility to include windows.h prior to +crypto.h where use of CRYPTO_THREAD_* types and functions is required. + +=head1 EXAMPLE + +This example safely initializes and uses a lock. + + #ifdef _WIN32 + # include <windows.h> + #endif + #include <openssl/crypto.h> + + static CRYPTO_ONCE once = CRYPTO_ONCE_STATIC_INIT; + static CRYPTO_RWLOCK *lock; + + static void myinit(void) + { + lock = CRYPTO_THREAD_lock_new(); + } + + static int mylock(void) + { + if (!CRYPTO_THREAD_run_once(&once, void init) || lock == NULL) + return 0; + return CRYPTO_THREAD_write_lock(lock); + } + + static int myunlock(void) + { + return CRYPTO_THREAD_unlock(lock); + } + + int serialized(void) + { + int ret = 0; + + if (mylock()) { + /* Your code here, do not return without releasing the lock! */ + ret = ... ; + } + myunlock(); + return ret; + } + +Finalization of locks is an advanced topic, not covered in this example. +This can only be done at process exit or when a dynamically loaded library is +no longer in use and is unloaded. +The simplest solution is to just "leak" the lock in applications and not +repeatedly load/unload shared libraries that allocate locks. + +=head1 NOTES + +You can find out if OpenSSL was configured with thread support: + + #include <openssl/opensslconf.h> + #if defined(OPENSSL_THREADS) + // thread support enabled + #else + // no thread support + #endif + +=head1 SEE ALSO + +L<crypto(7)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/CRYPTO_get_ex_new_index.pod b/deps/openssl/openssl/doc/crypto/CRYPTO_get_ex_new_index.pod new file mode 100644 index 0000000000..a5bf620972 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/CRYPTO_get_ex_new_index.pod @@ -0,0 +1,166 @@ +=pod + +=head1 NAME + +CRYPTO_EX_new, CRYPTO_EX_free, CRYPTO_EX_dup, +CRYPTO_free_ex_index, CRYPTO_get_ex_new_index, CRYPTO_set_ex_data, +CRYPTO_get_ex_data, CRYPTO_free_ex_data, CRYPTO_new_ex_data +- functions supporting application-specific data + +=head1 SYNOPSIS + + #include <openssl/crypto.h> + + int CRYPTO_get_ex_new_index(int class_index, + long argl, void *argp, + CRYPTO_EX_new *new_func, + CRYPTO_EX_dup *dup_func, + CRYPTO_EX_free *free_func); + + typedef void CRYPTO_EX_new(void *parent, void *ptr, CRYPTO_EX_DATA *ad, + int idx, long argl, void *argp); + typedef void CRYPTO_EX_free(void *parent, void *ptr, CRYPTO_EX_DATA *ad, + int idx, long argl, void *argp); + typedef int CRYPTO_EX_dup(CRYPTO_EX_DATA *to, const CRYPTO_EX_DATA *from, + void *from_d, int idx, long argl, void *argp); + + int CRYPTO_new_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *ad) + + int CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg); + + void *CRYPTO_get_ex_data(CRYPTO_EX_DATA *r, int idx); + + void CRYPTO_free_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *r); + + int CRYPTO_free_ex_index(int class_index, int idx); + +=head1 DESCRIPTION + +Several OpenSSL structures can have application-specific data attached to them, +known as "exdata." +The specific structures are: + + SSL + SSL_CTX + SSL_SESSION + X509 + X509_STORE + X509_STORE_CTX + DH + DSA + EC_KEY + RSA + ENGINE + UI + UI_METHOD + BIO + +Each is identified by an B<CRYPTO_EX_INDEX_xxx> define in the B<crypto.h> +header file. In addition, B<CRYPTO_EX_INDEX_APP> is reserved for +applications to use this facility for their own structures. + +The API described here is used by OpenSSL to manipulate exdata for specific +structures. Since the application data can be anything at all it is passed +and retrieved as a B<void *> type. + +The B<CRYPTO_EX_DATA> type is opaque. To initialize the exdata part of +a structure, call CRYPTO_new_ex_data(). This is only necessary for +B<CRYPTO_EX_INDEX_APP> objects. + +Exdata types are identified by an B<index>, an integer guaranteed to be +unique within structures for the lifetime of the program. Applications +using exdata typically call B<CRYPTO_get_ex_new_index> at startup, and +store the result in a global variable, or write a wrapper function to +provide lazy evaluation. The B<class_index> should be one of the +B<CRYPTO_EX_INDEX_xxx> values. The B<argl> and B<argp> parameters are saved +to be passed to the callbacks but are otherwise not used. In order to +transparently manipulate exdata, three callbacks must be provided. The +semantics of those callbacks are described below. + +When copying or releasing objects with exdata, the callback functions +are called in increasing order of their B<index> value. + +If a dynamic library can be unloaded, it should call CRYPTO_free_ex_index() +when this is done. +This will replace the callbacks with no-ops +so that applications don't crash. Any existing exdata will be leaked. + +To set or get the exdata on an object, the appropriate type-specific +routine must be used. This is because the containing structure is opaque +and the B<CRYPTO_EX_DATA> field is not accessible. In both API's, the +B<idx> parameter should be an already-created index value. + +When setting exdata, the pointer specified with a particular index is saved, +and returned on a subsequent "get" call. If the application is going to +release the data, it must make sure to set a B<NULL> value at the index, +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 +structure's exdata field. + +=head2 Callback Functions + +This section describes how the callback functions are used. Applications +that are defining their own exdata using B<CYPRTO_EX_INDEX_APP> must +call them as described here. + +When a structure is initially allocated (such as RSA_new()) then the +new_func() is called for every defined index. There is no requirement +that the entire parent, or containing, structure has been set up. +The new_func() is typically used only to allocate memory to store the +exdata, and perhaps an "initialized" flag within that memory. +The exdata value should be set by calling CRYPTO_set_ex_data(). + +When a structure is free'd (such as SSL_CTX_free()) then the +free_func() is called for every defined index. Again, the state of the +parent structure is not guaranteed. The free_func() may be called with a +NULL pointer. + +Both new_func() and free_func() take the same parameters. +The B<parent> is the pointer to the structure that contains the exdata. +The B<ptr> is the current exdata item; for new_func() this will typically +be NULL. The B<r> parameter is a pointer to the exdata field of the object. +The B<idx> is the index and is the value returned when the callbacks were +initially registered via CRYPTO_get_ex_new_index() and can be used if +the same callback handles different types of exdata. + +dup_func() is called when a structure is being copied. This is only done +for B<SSL>, B<SSL_SESSION>, B<EC_KEY> objects and B<BIO> chains via +BIO_dup_chain(). The B<to> and B<from> parameters +are pointers to the destination and source B<CRYPTO_EX_DATA> structures, +respectively. The B<from_d> parameter needs to be cast to a B<void **pptr> +as the API has currently the wrong signature; that will be changed in a +future version. The B<*pptr> is a pointer to the source exdata. +When the dup_func() returns, the value in B<*pptr> is copied to the +destination ex_data. If the pointer contained in B<*pptr> is not modified +by the dup_func(), then both B<to> and B<from> will point to the same data. +The B<idx>, B<argl> and B<argp> parameters are as described for the other +two callbacks. If the dup_func() returns B<0> the whole CRYPTO_dup_ex_data() +will fail. + +=head1 RETURN VALUES + +CRYPTO_get_ex_new_index() returns a new index or -1 on failure; the +value B<0> is reserved for the legacy "app_data" API's. + +CRYPTO_free_ex_index() and +CRYPTO_set_ex_data() return 1 on success or 0 on failure. + +CRYPTO_get_ex_data() returns the application data or NULL on failure; +note that NULL may be a valid value. + +dup_func() should return 0 for failure and 1 for success. + +=head1 COPYRIGHT + +Copyright 2015-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/CRYPTO_set_ex_data.pod b/deps/openssl/openssl/doc/crypto/CRYPTO_set_ex_data.pod deleted file mode 100644 index 7409c02aac..0000000000 --- a/deps/openssl/openssl/doc/crypto/CRYPTO_set_ex_data.pod +++ /dev/null @@ -1,53 +0,0 @@ -=pod - -=head1 NAME - -CRYPTO_set_ex_data, CRYPTO_get_ex_data - internal application specific data functions - -=head1 SYNOPSIS - - #include <openssl/crypto.h> - - int CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg); - - void *CRYPTO_get_ex_data(CRYPTO_EX_DATA *r, int idx); - -=head1 DESCRIPTION - -Several OpenSSL structures can have application specific data attached to them. -These functions are used internally by OpenSSL to manipulate application -specific data attached to a specific structure. - -These functions should only be used by applications to manipulate -B<CRYPTO_EX_DATA> structures passed to the B<new_func()>, B<free_func()> and -B<dup_func()> callbacks: as passed to B<RSA_get_ex_new_index()> for example. - -B<CRYPTO_set_ex_data()> is used to set application specific data, the data is -supplied in the B<arg> parameter and its precise meaning is up to the -application. - -B<CRYPTO_get_ex_data()> is used to retrieve application specific data. The data -is returned to the application, this will be the same value as supplied to -a previous B<CRYPTO_set_ex_data()> call. - -=head1 RETURN VALUES - -B<CRYPTO_set_ex_data()> returns 1 on success or 0 on failure. - -B<CRYPTO_get_ex_data()> returns the application data or 0 on failure. 0 may also -be valid application data but currently it can only fail if given an invalid B<idx> -parameter. - -On failure an error code can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, -L<DSA_get_ex_new_index(3)|DSA_get_ex_new_index(3)>, -L<DH_get_ex_new_index(3)|DH_get_ex_new_index(3)> - -=head1 HISTORY - -CRYPTO_set_ex_data() and CRYPTO_get_ex_data() have been available since SSLeay 0.9.0. - -=cut diff --git a/deps/openssl/openssl/doc/crypto/CTLOG_STORE_get0_log_by_id.pod b/deps/openssl/openssl/doc/crypto/CTLOG_STORE_get0_log_by_id.pod new file mode 100644 index 0000000000..c517e95e0f --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/CTLOG_STORE_get0_log_by_id.pod @@ -0,0 +1,49 @@ +=pod + +=head1 NAME + +CTLOG_STORE_get0_log_by_id - +Get a Certificate Transparency log from a CTLOG_STORE + +=head1 SYNOPSIS + + #include <openssl/ct.h> + + const CTLOG *CTLOG_STORE_get0_log_by_id(const CTLOG_STORE *store, + const uint8_t *log_id, + size_t log_id_len); + +=head1 DESCRIPTION + +A Signed Certificate Timestamp (SCT) identifies the Certificate Transparency +(CT) log that issued it using the log's LogID (see RFC 6962, Section 3.2). +Therefore, it is useful to be able to look up more information about a log +(e.g. its public key) using this LogID. + +CTLOG_STORE_get0_log_by_id() provides a way to do this. It will find a CTLOG +in a CTLOG_STORE that has a given LogID. + +=head1 RETURN VALUES + +B<CTLOG_STORE_get0_log_by_id> returns a CTLOG with the given LogID, if it +exists in the given CTLOG_STORE, otherwise it returns NULL. + +=head1 SEE ALSO + +L<ct(3)>, +L<CTLOG_STORE_new(3)> + +=head1 HISTORY + +This function was added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/CTLOG_STORE_new.pod b/deps/openssl/openssl/doc/crypto/CTLOG_STORE_new.pod new file mode 100644 index 0000000000..2a38f263ba --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/CTLOG_STORE_new.pod @@ -0,0 +1,79 @@ +=pod + +=head1 NAME + +CTLOG_STORE_new, CTLOG_STORE_free, +CTLOG_STORE_load_default_file, CTLOG_STORE_load_file - +Create and populate a Certificate Transparency log list + +=head1 SYNOPSIS + + #include <openssl/ct.h> + + CTLOG_STORE *CTLOG_STORE_new(void); + void CTLOG_STORE_free(CTLOG_STORE *store); + + int CTLOG_STORE_load_default_file(CTLOG_STORE *store); + int CTLOG_STORE_load_file(CTLOG_STORE *store, const char *file); + +=head1 DESCRIPTION + +A CTLOG_STORE is a container for a list of CTLOGs (Certificate Transparency +logs). The list can be loaded from one or more files and then searched by LogID +(see RFC 6962, Section 3.2, for the definition of a LogID). + +CTLOG_STORE_new() creates an empty list of CT logs. This is then populated +by CTLOG_STORE_load_default_file() or CTLOG_STORE_load_file(). +CTLOG_STORE_load_default_file() loads from the default file, which is named +"ct_log_list.cnf" in OPENSSLDIR (see the output of L<version>). This can be +overridden using an environment variable named "CTLOG_FILE". +CTLOG_STORE_load_file() loads from a caller-specified file path instead. +Both of these functions append any loaded CT logs to the CTLOG_STORE. + +The expected format of the file is: + + enabled_logs=foo,bar + + [foo] + description = Log 1 + key = <base64-encoded DER SubjectPublicKeyInfo here> + + [bar] + description = Log 2 + key = <base64-encoded DER SubjectPublicKeyInfo here> + +Once a CTLOG_STORE is no longer required, it should be passed to +CTLOG_STORE_free(). This will delete all of the CTLOGs stored within, along +with the CTLOG_STORE itself. + +=head1 NOTES + +If there are any invalid CT logs in a file, they are skipped and the remaining +valid logs will still be added to the CTLOG_STORE. A CT log will be considered +invalid if it is missing a "key" or "description" field. + +=head1 RETURN VALUES + +Both B<CTLOG_STORE_load_default_file> and B<CTLOG_STORE_load_file> return 1 if +all CT logs in the file are successfully parsed and loaded, 0 otherwise. + +=head1 SEE ALSO + +L<ct(3)>, +L<CTLOG_STORE_get0_log_by_id(3)>, +L<SSL_CTX_set_ctlog_list_file(3)> + +=head1 HISTORY + +These functions were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/CTLOG_new.pod b/deps/openssl/openssl/doc/crypto/CTLOG_new.pod new file mode 100644 index 0000000000..ccda6b9c41 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/CTLOG_new.pod @@ -0,0 +1,72 @@ +=pod + +=head1 NAME + +CTLOG_new, CTLOG_new_from_base64, CTLOG_free, +CTLOG_get0_name, CTLOG_get0_log_id, CTLOG_get0_public_key - +encapsulates information about a Certificate Transparency log + +=head1 SYNOPSIS + + #include <openssl/ct.h> + + CTLOG *CTLOG_new(EVP_PKEY *public_key, const char *name); + int CTLOG_new_from_base64(CTLOG ** ct_log, + const char *pkey_base64, const char *name); + void CTLOG_free(CTLOG *log); + const char *CTLOG_get0_name(const CTLOG *log); + void CTLOG_get0_log_id(const CTLOG *log, const uint8_t **log_id, + size_t *log_id_len); + EVP_PKEY *CTLOG_get0_public_key(const CTLOG *log); + +=head1 DESCRIPTION + +CTLOG_new() returns a new CTLOG that represents the Certificate Transparency +(CT) log with the given public key. A name must also be provided that can be +used to help users identify this log. Ownership of the public key is +transferred. + +CTLOG_new_from_base64() also creates a new CTLOG, but takes the public key in +base64-encoded DER form and sets the ct_log pointer to point to the new CTLOG. +The base64 will be decoded and the public key parsed. + +Regardless of whether CTLOG_new() or CTLOG_new_from_base64() is used, it is the +caller's responsibility to pass the CTLOG to CTLOG_free() once it is no longer +needed. This will delete it and, if created by CTLOG_new(), the EVP_PKEY that +was passed to it. + +CTLOG_get0_name() returns the name of the log, as provided when the CTLOG was +created. Ownership of the string remains with the CTLOG. + +CTLOG_get0_log_id() sets *log_id to point to a string containing that log's +LogID (see RFC 6962). It sets *log_id_len to the length of that LogID. For a +v1 CT log, the LogID will be a SHA-256 hash (i.e. 32 bytes long). Ownership of +the string remains with the CTLOG. + +CTLOG_get0_public_key() returns the public key of the CT log. Ownership of the +EVP_PKEY remains with the CTLOG. + +=head1 RETURN VALUES + +CTLOG_new() will return NULL if an error occurs. + +CTLOG_new_from_base64() will return 1 on success, 0 otherwise. + +=head1 SEE ALSO + +L<ct(3)> + +=head1 HISTORY + +These functions were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/CT_POLICY_EVAL_CTX_new.pod b/deps/openssl/openssl/doc/crypto/CT_POLICY_EVAL_CTX_new.pod new file mode 100644 index 0000000000..7839fd393a --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/CT_POLICY_EVAL_CTX_new.pod @@ -0,0 +1,111 @@ +=pod + +=head1 NAME + +CT_POLICY_EVAL_CTX_new, CT_POLICY_EVAL_CTX_free, +CT_POLICY_EVAL_CTX_get0_cert, CT_POLICY_EVAL_CTX_set1_cert, +CT_POLICY_EVAL_CTX_get0_issuer, CT_POLICY_EVAL_CTX_set1_issuer, +CT_POLICY_EVAL_CTX_get0_log_store, CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE, +CT_POLICY_EVAL_CTX_get_time, CT_POLICY_EVAL_CTX_set_time - +Encapsulates the data required to evaluate whether SCTs meet a Certificate Transparency policy + +=head1 SYNOPSIS + + #include <openssl/ct.h> + + CT_POLICY_EVAL_CTX *CT_POLICY_EVAL_CTX_new(void); + void CT_POLICY_EVAL_CTX_free(CT_POLICY_EVAL_CTX *ctx); + X509* CT_POLICY_EVAL_CTX_get0_cert(const CT_POLICY_EVAL_CTX *ctx); + int CT_POLICY_EVAL_CTX_set1_cert(CT_POLICY_EVAL_CTX *ctx, X509 *cert); + X509* CT_POLICY_EVAL_CTX_get0_issuer(const CT_POLICY_EVAL_CTX *ctx); + int CT_POLICY_EVAL_CTX_set1_issuer(CT_POLICY_EVAL_CTX *ctx, X509 *issuer); + const CTLOG_STORE *CT_POLICY_EVAL_CTX_get0_log_store(const CT_POLICY_EVAL_CTX *ctx); + void CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE(CT_POLICY_EVAL_CTX *ctx, CTLOG_STORE *log_store); + uint64_t CT_POLICY_EVAL_CTX_get_time(const CT_POLICY_EVAL_CTX *ctx); + void CT_POLICY_EVAL_CTX_set_time(CT_POLICY_EVAL_CTX *ctx, uint64_t time_in_ms); + +=head1 DESCRIPTION + +A B<CT_POLICY_EVAL_CTX> is used by functions that evaluate whether Signed +Certificate Timestamps (SCTs) fulfil a Certificate Transparency (CT) policy. +This policy may be, for example, that at least one valid SCT is available. To +determine this, an SCT's timestamp and signature must be verified. +This requires: + +=over 4 + +=item * the public key of the log that issued the SCT + +=item * the certificate that the SCT was issued for + +=item * the issuer certificate (if the SCT was issued for a pre-certificate) + +=item * the current time + +=back + +The above requirements are met using the setters described below. + +CT_POLICY_EVAL_CTX_new() creates an empty policy evaluation context. This +should then be populated using: + +=over 4 + +=item * CT_POLICY_EVAL_CTX_set1_cert() to provide the certificate the SCTs were issued for + +Increments the reference count of the certificate. + +=item * CT_POLICY_EVAL_CTX_set1_issuer() to provide the issuer certificate + +Increments the reference count of the certificate. + +=item * CT_POLICY_EVAL_CTX_set_shared_CTLOG_STORE() to provide a list of logs that are trusted as sources of SCTs + +Holds a pointer to the CTLOG_STORE, so the CTLOG_STORE must outlive the +CT_POLICY_EVAL_CTX. + +=item * CT_POLICY_EVAL_CTX_set_time() to set the time SCTs should be compared with to determine if they are valid + +The SCT timestamp will be compared to this time to check whether the SCT was +issued in the future. RFC6962 states that "TLS clients MUST reject SCTs whose +timestamp is in the future". By default, this will be set to 5 minutes in the +future (e.g. (time() + 300) * 1000), to allow for clock drift. + +The time should be in milliseconds since the Unix epoch. + +=back + +Each setter has a matching getter for accessing the current value. + +When no longer required, the B<CT_POLICY_EVAL_CTX> should be passed to +CT_POLICY_EVAL_CTX_free() to delete it. + +=head1 NOTES + +The issuer certificate only needs to be provided if at least one of the SCTs +was issued for a pre-certificate. This will be the case for SCTs embedded in a +certificate (i.e. those in an X.509 extension), but may not be the case for SCTs +found in the TLS SCT extension or OCSP response. + +=head1 RETURN VALUES + +CT_POLICY_EVAL_CTX_new() will return NULL if malloc fails. + +=head1 SEE ALSO + +L<ct(7)> + +=head1 HISTORY + +These functions were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/DEFINE_STACK_OF.pod b/deps/openssl/openssl/doc/crypto/DEFINE_STACK_OF.pod new file mode 100644 index 0000000000..f655f84eea --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/DEFINE_STACK_OF.pod @@ -0,0 +1,241 @@ +=pod + +=head1 NAME + +DEFINE_STACK_OF, DEFINE_STACK_OF_CONST, DEFINE_SPECIAL_STACK_OF, +DEFINE_SPECIAL_STACK_OF_CONST, +OPENSSL_sk_deep_copy, OPENSSL_sk_delete, OPENSSL_sk_delete_ptr, +OPENSSL_sk_dup, OPENSSL_sk_find, OPENSSL_sk_find_ex, OPENSSL_sk_free, +OPENSSL_sk_insert, OPENSSL_sk_is_sorted, OPENSSL_sk_new, OPENSSL_sk_new_null, +OPENSSL_sk_num, OPENSSL_sk_pop, OPENSSL_sk_pop_free, OPENSSL_sk_push, +OPENSSL_sk_set, OPENSSL_sk_set_cmp_func, OPENSSL_sk_shift, OPENSSL_sk_sort, +OPENSSL_sk_unshift, OPENSSL_sk_value, OPENSSL_sk_zero, +sk_TYPE_num, sk_TYPE_value, sk_TYPE_new, sk_TYPE_new_null, sk_TYPE_free, +sk_TYPE_zero, sk_TYPE_delete, sk_TYPE_delete_ptr, sk_TYPE_push, +sk_TYPE_unshift, sk_TYPE_pop, sk_TYPE_shift, sk_TYPE_pop_free, +sk_TYPE_insert, sk_TYPE_set, sk_TYPE_find, sk_TYPE_find_ex, sk_TYPE_sort, +sk_TYPE_is_sorted, sk_TYPE_dup, sk_TYPE_deep_copy, sk_TYPE_set_cmp_func - +stack container + +=for comment generic + +=head1 SYNOPSIS + + #include <openssl/safestack.h> + + STACK_OF(TYPE) + DEFINE_STACK_OF(TYPE) + DEFINE_STACK_OF_CONST(TYPE) + DEFINE_SPECIAL_STACK_OF(FUNCTYPE, TYPE) + DEFINE_SPECIAL_STACK_OF_CONST(FUNCTYPE, TYPE) + + typedef int (*sk_TYPE_compfunc)(const TYPE *const *a, const TYPE *const *b); + typedef TYPE * (*sk_TYPE_copyfunc)(const TYPE *a); + typedef void (*sk_TYPE_freefunc)(TYPE *a); + + int sk_TYPE_num(const STACK_OF(TYPE) *sk); + TYPE *sk_TYPE_value(const STACK_OF(TYPE) *sk, int idx); + STACK_OF(TYPE) *sk_TYPE_new(sk_TYPE_compfunc compare); + STACK_OF(TYPE) *sk_TYPE_new_null(void); + void sk_TYPE_free(const STACK_OF(TYPE) *sk); + void sk_TYPE_zero(const STACK_OF(TYPE) *sk); + TYPE *sk_TYPE_delete(STACK_OF(TYPE) *sk, int i); + TYPE *sk_TYPE_delete_ptr(STACK_OF(TYPE) *sk, TYPE *ptr); + int sk_TYPE_push(STACK_OF(TYPE) *sk, const TYPE *ptr); + int sk_TYPE_unshift(STACK_OF(TYPE) *sk, const TYPE *ptr); + TYPE *sk_TYPE_pop(STACK_OF(TYPE) *sk); + TYPE *sk_TYPE_shift(STACK_OF(TYPE) *sk); + void sk_TYPE_pop_free(STACK_OF(TYPE) *sk, sk_TYPE_freefunc freefunc); + int sk_TYPE_insert(STACK_OF(TYPE) *sk, TYPE *ptr, int idx); + TYPE *sk_TYPE_set(STACK_OF(TYPE) *sk, int idx, const TYPE *ptr); + int sk_TYPE_find(STACK_OF(TYPE) *sk, TYPE *ptr); + int sk_TYPE_find_ex(STACK_OF(TYPE) *sk, TYPE *ptr); + void sk_TYPE_sort(const STACK_OF(TYPE) *sk); + int sk_TYPE_is_sorted(const STACK_OF(TYPE) *sk); + STACK_OF(TYPE) *sk_TYPE_dup(const STACK_OF(TYPE) *sk); + STACK_OF(TYPE) *sk_TYPE_deep_copy(const STACK_OF(TYPE) *sk, + sk_TYPE_copyfunc copyfunc, + sk_TYPE_freefunc freefunc); + sk_TYPE_compfunc (*sk_TYPE_set_cmp_func(STACK_OF(TYPE) *sk, sk_TYPE_compfunc compare); + +=head1 DESCRIPTION + +Applications can create and use their own stacks by placing any of the macros +described below in a header file. These macros define typesafe inline +functions that wrap around the utility B<OPENSSL_sk_> API. +In the description here, I<TYPE> is used +as a placeholder for any of the OpenSSL datatypes, such as I<X509>. + +STACK_OF() returns the name for a stack of the specified B<TYPE>. +DEFINE_STACK_OF() creates set of functions for a stack of B<TYPE>. This +will mean that type B<TYPE> is stored in each stack, the type is referenced by +STACK_OF(TYPE) and each function name begins with I<sk_TYPE_>. For example: + + TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx); + +DEFINE_STACK_OF_CONST() is identical to DEFINE_STACK_OF() except +each element is constant. For example: + + const TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx); + +DEFINE_SPECIAL_STACK_OF() defines a stack of B<TYPE> but +each function uses B<FUNCNAME> in the function name. For example: + + TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx); + +DEFINE_SPECIAL_STACK_OF_CONST() is similar except that each element is +constant: + + const TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx); + +sk_TYPE_num() returns the number of elements in B<sk> or -1 if B<sk> is +B<NULL>. + +sk_TYPE_value() returns element B<idx> in B<sk>, where B<idx> starts at +zero. If B<idx> is out of range then B<NULL> is returned. + +sk_TYPE_new() allocates a new empty stack using comparison function B<compare>. +If B<compare> is B<NULL> then no comparison function is used. + +sk_TYPE_new_null() allocates a new empty stack with no comparison function. + +sk_TYPE_set_cmp_func() sets the comparison function of B<sk> to B<compare>. +The previous comparison function is returned or B<NULL> if there was +no previous comparison function. + +sk_TYPE_free() frees up the B<sk> structure. It does B<not> free up any +elements of B<sk>. After this call B<sk> is no longer valid. + +sk_TYPE_zero() sets the number of elements in B<sk> to zero. It does not free +B<sk> so after this call B<sk> is still valid. + +sk_TYPE_pop_free() frees up all elements of B<sk> and B<sk> itself. The +free function freefunc() is called on each element to free it. + +sk_TYPE_delete() deletes element B<i> from B<sk>. It returns the deleted +element or B<NULL> if B<i> is out of range. + +sk_TYPE_delete_ptr() deletes element matching B<ptr> from B<sk>. It returns +the deleted element or B<NULL> if no element matching B<ptr> was found. + +sk_TYPE_insert() inserts B<ptr> into B<sk> at position B<idx>. Any existing +elements at or after B<idx> are moved downwards. If B<idx> is out of range +the new element is appended to B<sk>. sk_TYPE_insert() either returns the +number of elements in B<sk> after the new element is inserted or zero if +an error (such as memory allocation failure) occurred. + +sk_TYPE_push() appends B<ptr> to B<sk> it is equivalent to: + + sk_TYPE_insert(sk, ptr, -1); + +sk_TYPE_unshift() inserts B<ptr> at the start of B<sk> it is equivalent to: + + sk_TYPE_insert(sk, ptr, 0); + +sk_TYPE_pop() returns and removes the last element from B<sk>. + +sk_TYPE_shift() returns and removes the first element from B<sk>. + +sk_TYPE_set() sets element B<idx> of B<sk> to B<ptr> replacing the current +element. The new element value is returned or B<NULL> if an error occurred: +this will only happen if B<sk> is B<NULL> or B<idx> is out of range. + +sk_TYPE_find() searches B<sk> for the element B<ptr>. In the case +where no comparison function has been specified, the function performs +a linear search for a pointer equal to B<ptr>. The index of the first +matching element is returned or B<-1> if there is no match. In the case +where a comparison function has been specified, B<sk> is sorted then +sk_TYPE_find() returns the index of a matching element or B<-1> if there +is no match. Note that, in this case, the matching element returned is +not guaranteed to be the first; the comparison function will usually +compare the values pointed to rather than the pointers themselves and +the order of elements in B<sk> could change. + +sk_TYPE_find_ex() operates like sk_TYPE_find() except when a comparison +function has been specified and no matching element is found. Instead +of returning B<-1>, sk_TYPE_find_ex() returns the index of the element +either before or after the location where B<ptr> would be if it were +present in B<sk>. + +sk_TYPE_sort() sorts B<sk> using the supplied comparison function. + +sk_TYPE_is_sorted() returns B<1> if B<sk> is sorted and B<0> otherwise. + +sk_TYPE_dup() returns a copy of B<sk>. Note the pointers in the copy +are identical to the original. + +sk_TYPE_deep_copy() returns a new stack where each element has been copied. +Copying is performed by the supplied copyfunc() and freeing by freefunc(). The +function freefunc() is only called if an error occurs. + +=head1 NOTES + +Care should be taken when accessing stacks in multi-threaded environments. +Any operation which increases the size of a stack such as sk_TYPE_insert() or +sk_push() can "grow" the size of an internal array and cause race conditions +if the same stack is accessed in a different thread. Operations such as +sk_find() and sk_sort() can also reorder the stack. + +Any comparison function supplied should use a metric suitable +for use in a binary search operation. That is it should return zero, a +positive or negative value if B<a> is equal to, greater than +or less than B<b> respectively. + +Care should be taken when checking the return values of the functions +sk_TYPE_find() and sk_TYPE_find_ex(). They return an index to the +matching element. In particular B<0> indicates a matching first element. +A failed search is indicated by a B<-1> return value. + +STACK_OF(), DEFINE_STACK_OF(), DEFINE_STACK_OF_CONST(), and +DEFINE_SPECIAL_STACK_OF() are implemented as macros. + +=head1 RETURN VALUES + +sk_TYPE_num() returns the number of elements in the stack or B<-1> if the +passed stack is B<NULL>. + +sk_TYPE_value() returns a pointer to a stack element or B<NULL> if the +index is out of range. + +sk_TYPE_new() and sk_TYPE_new_null() return an empty stack or B<NULL> if +an error occurs. + +sk_TYPE_set_cmp_func() returns the old comparison function or B<NULL> if +there was no old comparison function. + +sk_TYPE_free(), sk_TYPE_zero(), sk_TYPE_pop_free() and sk_TYPE_sort() do +not return values. + +sk_TYPE_pop(), sk_TYPE_shift(), sk_TYPE_delete() and sk_TYPE_delete_ptr() +return a pointer to the deleted element or B<NULL> on error. + +sk_TYPE_insert(), sk_TYPE_push() and sk_TYPE_unshift() return the total +number of elements in the stack and 0 if an error occurred. + +sk_TYPE_set() returns a pointer to the replacement element or B<NULL> on +error. + +sk_TYPE_find() and sk_TYPE_find_ex() return an index to the found element +or B<-1> on error. + +sk_TYPE_is_sorted() returns B<1> if the stack is sorted and B<0> if it is +not. + +sk_TYPE_dup() and sk_TYPE_deep_copy() return a pointer to the copy of the +stack. + +=head1 HISTORY + +Before OpenSSL 1.1.0, this was implemented via macros and not inline functions +and was not a public API. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/des.pod b/deps/openssl/openssl/doc/crypto/DES_random_key.pod index 339617aab0..77cfddab3b 100644 --- a/deps/openssl/openssl/doc/crypto/des.pod +++ b/deps/openssl/openssl/doc/crypto/DES_random_key.pod @@ -8,9 +8,9 @@ DES_ecb_encrypt, DES_ecb2_encrypt, DES_ecb3_encrypt, DES_ncbc_encrypt, DES_cfb_encrypt, DES_ofb_encrypt, DES_pcbc_encrypt, DES_cfb64_encrypt, DES_ofb64_encrypt, DES_xcbc_encrypt, DES_ede2_cbc_encrypt, DES_ede2_cfb64_encrypt, DES_ede2_ofb64_encrypt, DES_ede3_cbc_encrypt, -DES_ede3_cbcm_encrypt, DES_ede3_cfb64_encrypt, DES_ede3_ofb64_encrypt, +DES_ede3_cfb64_encrypt, DES_ede3_ofb64_encrypt, DES_cbc_cksum, DES_quad_cksum, DES_string_to_key, DES_string_to_2keys, -DES_fcrypt, DES_crypt, DES_enc_read, DES_enc_write - DES encryption +DES_fcrypt, DES_crypt - DES encryption =head1 SYNOPSIS @@ -28,16 +28,16 @@ DES_fcrypt, DES_crypt, DES_enc_read, DES_enc_write - DES encryption void DES_set_odd_parity(DES_cblock *key); int DES_is_weak_key(const_DES_cblock *key); - void DES_ecb_encrypt(const_DES_cblock *input, DES_cblock *output, + void DES_ecb_encrypt(const_DES_cblock *input, DES_cblock *output, DES_key_schedule *ks, int enc); - void DES_ecb2_encrypt(const_DES_cblock *input, DES_cblock *output, + void DES_ecb2_encrypt(const_DES_cblock *input, DES_cblock *output, DES_key_schedule *ks1, DES_key_schedule *ks2, int enc); - void DES_ecb3_encrypt(const_DES_cblock *input, DES_cblock *output, - DES_key_schedule *ks1, DES_key_schedule *ks2, + void DES_ecb3_encrypt(const_DES_cblock *input, DES_cblock *output, + DES_key_schedule *ks1, DES_key_schedule *ks2, DES_key_schedule *ks3, int enc); - void DES_ncbc_encrypt(const unsigned char *input, unsigned char *output, - long length, DES_key_schedule *schedule, DES_cblock *ivec, + void DES_ncbc_encrypt(const unsigned char *input, unsigned char *output, + long length, DES_key_schedule *schedule, DES_cblock *ivec, int enc); void DES_cfb_encrypt(const unsigned char *in, unsigned char *out, int numbits, long length, DES_key_schedule *schedule, @@ -45,8 +45,8 @@ DES_fcrypt, DES_crypt, DES_enc_read, DES_enc_write - DES encryption void DES_ofb_encrypt(const unsigned char *in, unsigned char *out, int numbits, long length, DES_key_schedule *schedule, DES_cblock *ivec); - void DES_pcbc_encrypt(const unsigned char *input, unsigned char *output, - long length, DES_key_schedule *schedule, DES_cblock *ivec, + void DES_pcbc_encrypt(const unsigned char *input, unsigned char *output, + long length, DES_key_schedule *schedule, DES_cblock *ivec, int enc); void DES_cfb64_encrypt(const unsigned char *in, unsigned char *out, long length, DES_key_schedule *schedule, DES_cblock *ivec, @@ -55,8 +55,8 @@ DES_fcrypt, DES_crypt, DES_enc_read, DES_enc_write - DES encryption long length, DES_key_schedule *schedule, DES_cblock *ivec, int *num); - void DES_xcbc_encrypt(const unsigned char *input, unsigned char *output, - long length, DES_key_schedule *schedule, DES_cblock *ivec, + void DES_xcbc_encrypt(const unsigned char *input, unsigned char *output, + long length, DES_key_schedule *schedule, DES_cblock *ivec, const_DES_cblock *inw, const_DES_cblock *outw, int enc); void DES_ede2_cbc_encrypt(const unsigned char *input, @@ -73,22 +73,18 @@ DES_fcrypt, DES_crypt, DES_enc_read, DES_enc_write - DES encryption unsigned char *output, long length, DES_key_schedule *ks1, DES_key_schedule *ks2, DES_key_schedule *ks3, DES_cblock *ivec, int enc); - void DES_ede3_cbcm_encrypt(const unsigned char *in, unsigned char *out, - long length, DES_key_schedule *ks1, DES_key_schedule *ks2, - DES_key_schedule *ks3, DES_cblock *ivec1, DES_cblock *ivec2, - int enc); - void DES_ede3_cfb64_encrypt(const unsigned char *in, unsigned char *out, + void DES_ede3_cfb64_encrypt(const unsigned char *in, unsigned char *out, long length, DES_key_schedule *ks1, DES_key_schedule *ks2, DES_key_schedule *ks3, DES_cblock *ivec, int *num, int enc); - void DES_ede3_ofb64_encrypt(const unsigned char *in, unsigned char *out, - long length, DES_key_schedule *ks1, - DES_key_schedule *ks2, DES_key_schedule *ks3, + void DES_ede3_ofb64_encrypt(const unsigned char *in, unsigned char *out, + long length, DES_key_schedule *ks1, + DES_key_schedule *ks2, DES_key_schedule *ks3, DES_cblock *ivec, int *num); - DES_LONG DES_cbc_cksum(const unsigned char *input, DES_cblock *output, - long length, DES_key_schedule *schedule, + DES_LONG DES_cbc_cksum(const unsigned char *input, DES_cblock *output, + long length, DES_key_schedule *schedule, const_DES_cblock *ivec); - DES_LONG DES_quad_cksum(const unsigned char *input, DES_cblock output[], + DES_LONG DES_quad_cksum(const unsigned char *input, DES_cblock output[], long length, int out_count, DES_cblock *seed); void DES_string_to_key(const char *str, DES_cblock *key); void DES_string_to_2keys(const char *str, DES_cblock *key1, @@ -97,11 +93,6 @@ DES_fcrypt, DES_crypt, DES_enc_read, DES_enc_write - DES encryption char *DES_fcrypt(const char *buf, const char *salt, char *ret); char *DES_crypt(const char *buf, const char *salt); - int DES_enc_read(int fd, void *buf, int len, DES_key_schedule *sched, - DES_cblock *iv); - int DES_enc_write(int fd, const void *buf, int len, - DES_key_schedule *sched, DES_cblock *iv); - =head1 DESCRIPTION This library contains a fast implementation of the DES encryption @@ -115,7 +106,7 @@ each byte is the parity bit. The key schedule is an expanded form of the key; it is used to speed the encryption process. DES_random_key() generates a random key. The PRNG must be seeded -prior to using this function (see L<rand(3)|rand(3)>). If the PRNG +prior to using this function (see L<rand(3)>). If the PRNG could not generate a secure key, 0 is returned. Before a DES key can be used, it must be converted into the @@ -136,7 +127,7 @@ depend on a global variable. DES_set_odd_parity() sets the parity of the passed I<key> to odd. DES_is_weak_key() returns 1 if the passed key is a weak key, 0 if it -is ok. +is ok. The following routines mostly operate on an input and output stream of I<DES_cblock>s. @@ -230,7 +221,7 @@ DES_cbc_cksum() produces an 8 byte checksum based on the input stream (via CBC encryption). The last 4 bytes of the checksum are returned and the complete 8 bytes are placed in I<output>. This function is used by Kerberos v4. Other applications should use -L<EVP_DigestInit(3)|EVP_DigestInit(3)> etc. instead. +L<EVP_DigestInit(3)> etc. instead. DES_quad_cksum() is a Kerberos v4 function. It returns a 4 byte checksum from the input bytes. The algorithm can be iterated over the @@ -249,8 +240,9 @@ is thread safe, unlike the normal crypt. DES_crypt() is a faster replacement for the normal system crypt(). This function calls DES_fcrypt() with a static array passed as the -third parameter. This emulates the normal non-thread safe semantics +third parameter. This mostly emulates the normal non-thread-safe semantics of crypt(3). +The B<salt> must be two ASCII characters. DES_enc_write() writes I<len> bytes to file descriptor I<fd> from buffer I<buf>. The data is encrypted via I<pcbc_encrypt> (default) @@ -260,32 +252,6 @@ containing the length of the following encrypted data. The encrypted data then follows, padded with random data out to a multiple of 8 bytes. -DES_enc_read() is used to read I<len> bytes from file descriptor -I<fd> into buffer I<buf>. The data being read from I<fd> is assumed to -have come from DES_enc_write() and is decrypted using I<sched> for -the key schedule and I<iv> for the initial vector. - -B<Warning:> The data format used by DES_enc_write() and DES_enc_read() -has a cryptographic weakness: When asked to write more than MAXWRITE -bytes, DES_enc_write() will split the data into several chunks that -are all encrypted using the same IV. So don't use these functions -unless you are sure you know what you do (in which case you might not -want to use them anyway). They cannot handle non-blocking sockets. -DES_enc_read() uses an internal state and thus cannot be used on -multiple files. - -I<DES_rw_mode> is used to specify the encryption mode to use with -DES_enc_read() and DES_end_write(). If set to I<DES_PCBC_MODE> (the -default), DES_pcbc_encrypt is used. If set to I<DES_CBC_MODE> -DES_cbc_encrypt is used. - -=head1 NOTES - -Single-key DES is insecure due to its short key size. ECB mode is -not suitable for most applications; see L<des_modes(7)|des_modes(7)>. - -The L<evp(3)|evp(3)> library provides higher-level encryption functions. - =head1 BUGS DES_3cbc_encrypt() is flawed and must not be used in applications. @@ -307,51 +273,38 @@ DES_string_to_key() is available for backward compatibility with the MIT library. New applications should use a cryptographic hash function. The same applies for DES_string_to_2key(). -=head1 CONFORMING TO - -ANSI X3.106 +=head1 NOTES The B<des> library was written to be source code compatible with the MIT Kerberos library. -=head1 SEE ALSO +Applications should use the higher level functions +L<EVP_EncryptInit(3)> etc. instead of calling these +functions directly. -crypt(3), L<des_modes(7)|des_modes(7)>, L<evp(3)|evp(3)>, L<rand(3)|rand(3)> +Single-key DES is insecure due to its short key size. ECB mode is +not suitable for most applications; see L<des_modes(7)>. =head1 HISTORY -In OpenSSL 0.9.7, all des_ functions were renamed to DES_ to avoid -clashes with older versions of libdes. Compatibility des_ functions -are provided for a short while, as well as crypt(). -Declarations for these are in <openssl/des_old.h>. There is no DES_ -variant for des_random_seed(). -This will happen to other functions -as well if they are deemed redundant (des_random_seed() just calls -RAND_seed() and is present for backward compatibility only), buggy or -already scheduled for removal. - -des_cbc_cksum(), des_cbc_encrypt(), des_ecb_encrypt(), -des_is_weak_key(), des_key_sched(), des_pcbc_encrypt(), -des_quad_cksum(), des_random_key() and des_string_to_key() -are available in the MIT Kerberos library; -des_check_key_parity(), des_fixup_key_parity() and des_is_weak_key() -are available in newer versions of that library. - -des_set_key_checked() and des_set_key_unchecked() were added in -OpenSSL 0.9.5. - -des_generate_random_block(), des_init_random_number_generator(), -des_new_random_key(), des_set_random_generator_seed() and -des_set_sequence_number() and des_rand_data() are used in newer -versions of Kerberos but are not implemented here. - -des_random_key() generated cryptographically weak random data in -SSLeay and in OpenSSL prior version 0.9.5, as well as in the original -MIT library. - -=head1 AUTHOR - -Eric Young (eay@cryptsoft.com). Modified for the OpenSSL project -(http://www.openssl.org). +The requirement that the B<salt> parameter to DES_crypt() and DES_fcrypt() +be two ASCII characters was first enforced in +OpenSSL 1.1.0. Previous versions tried to use the letter uppercase B<A> +if both character were not present, and could crash when given non-ASCII +on some platforms. + +=head1 SEE ALSO + +L<des_modes(7)>, +L<EVP_EncryptInit(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/DH_generate_key.pod b/deps/openssl/openssl/doc/crypto/DH_generate_key.pod index 81f09fdf45..de0847a94d 100644 --- a/deps/openssl/openssl/doc/crypto/DH_generate_key.pod +++ b/deps/openssl/openssl/doc/crypto/DH_generate_key.pod @@ -36,15 +36,19 @@ DH_generate_key() returns 1 on success, 0 otherwise. DH_compute_key() returns the size of the shared secret on success, -1 on error. -The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. +The error codes can be obtained by L<ERR_get_error(3)>. =head1 SEE ALSO -L<dh(3)|dh(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, L<DH_size(3)|DH_size(3)> +L<dh(3)>, L<ERR_get_error(3)>, L<rand(3)>, L<DH_size(3)> -=head1 HISTORY +=head1 COPYRIGHT -DH_generate_key() and DH_compute_key() are available in all versions -of SSLeay and OpenSSL. +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/DH_generate_parameters.pod b/deps/openssl/openssl/doc/crypto/DH_generate_parameters.pod index 7f81a04d91..ce178af0be 100644 --- a/deps/openssl/openssl/doc/crypto/DH_generate_parameters.pod +++ b/deps/openssl/openssl/doc/crypto/DH_generate_parameters.pod @@ -2,22 +2,25 @@ =head1 NAME - DH_generate_parameters_ex, DH_generate_parameters, -DH_check - generate and check Diffie-Hellman parameters +DH_check, DH_check_params - generate and check Diffie-Hellman +parameters =head1 SYNOPSIS #include <openssl/dh.h> - int DH_generate_parameters_ex(DH *dh, int prime_len,int generator, BN_GENCB *cb); + int DH_generate_parameters_ex(DH *dh, int prime_len, int generator, BN_GENCB *cb); int DH_check(DH *dh, int *codes); + int DH_check_params(DH *dh, int *codes); Deprecated: + #if OPENSSL_API_COMPAT < 0x00908000L DH *DH_generate_parameters(int prime_len, int generator, void (*callback)(int, int, void *), void *cb_arg); + #endif =head1 DESCRIPTION @@ -27,31 +30,84 @@ structure. The pseudo-random number generator must be seeded prior to calling DH_generate_parameters(). B<prime_len> is the length in bits of the safe prime to be generated. -B<generator> is a small number E<gt> 1, typically 2 or 5. +B<generator> is a small number E<gt> 1, typically 2 or 5. A callback function may be used to provide feedback about the progress of the key generation. If B<cb> is not B<NULL>, it will be -called as described in L<BN_generate_prime(3)|BN_generate_prime(3)> while a random prime +called as described in L<BN_generate_prime(3)> while a random prime number is generated, and when a prime has been found, B<BN_GENCB_call(cb, 3, 0)> -is called. See L<BN_generate_prime(3)|BN_generate_prime(3)> for information on +is called. See L<BN_generate_prime(3)> for information on the BN_GENCB_call() function. -DH_check() validates Diffie-Hellman parameters. It checks that B<p> is -a safe prime, and that B<g> is a suitable generator. In the case of an -error, the bit flags DH_CHECK_P_NOT_SAFE_PRIME or -DH_NOT_SUITABLE_GENERATOR are set in B<*codes>. -DH_UNABLE_TO_CHECK_GENERATOR is set if the generator cannot be -checked, i.e. it does not equal 2 or 5. +DH_check_params() confirms that the B<p> and B<g> are likely enough to +be valid. +This is a lightweight check, if a more thorough check is needed, use +DH_check(). +The value of B<*codes> is updated with any problems found. +If B<*codes> is zero then no problems were found, otherwise the +following bits may be set: + +=over 4 + +=item DH_CHECK_P_NOT_PRIME + +The parameter B<p> has been determined to not being an odd prime. +Note that the lack of this bit doesn't guarantee that B<p> is a +prime. + +=item DH_NOT_SUITABLE_GENERATOR + +The generator B<g> is not suitable. +Note that the lack of this bit doesn't guarantee that B<g> is +suitable, unless B<p> is known to be a strong prime. + +=back + +DH_check() confirms that the Diffie-Hellman parameters B<dh> are valid. The +value of B<*codes> is updated with any problems found. If B<*codes> is zero then +no problems were found, otherwise the following bits may be set: + +=over 4 + +=item DH_CHECK_P_NOT_PRIME + +The parameter B<p> is not prime. + +=item DH_CHECK_P_NOT_SAFE_PRIME + +The parameter B<p> is not a safe prime and no B<q> value is present. + +=item DH_UNABLE_TO_CHECK_GENERATOR + +The generator B<g> cannot be checked for suitability. + +=item DH_NOT_SUITABLE_GENERATOR + +The generator B<g> is not suitable. + +=item DH_CHECK_Q_NOT_PRIME + +The parameter B<q> is not prime. + +=item DH_CHECK_INVALID_Q_VALUE + +The parameter B<q> is invalid. + +=item DH_CHECK_INVALID_J_VALUE + +The parameter B<j> is invalid. + +=back =head1 RETURN VALUES -DH_generate_parameters_ex() and DH_check() return 1 if the check could be -performed, 0 otherwise. +DH_generate_parameters_ex(), DH_check() and DH_check_params() return 1 +if the check could be performed, 0 otherwise. DH_generate_parameters() (deprecated) returns a pointer to the DH structure, or NULL if the parameter generation fails. -The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. +The error codes can be obtained by L<ERR_get_error(3)>. =head1 NOTES @@ -61,22 +117,18 @@ hours before finding a suitable prime. The parameters generated by DH_generate_parameters_ex() and DH_generate_parameters() are not to be used in signature schemes. -=head1 BUGS - -If B<generator> is not 2 or 5, B<dh-E<gt>g>=B<generator> is not -a usable generator. - =head1 SEE ALSO -L<dh(3)|dh(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, -L<DH_free(3)|DH_free(3)> +L<DH_new(3)>, L<ERR_get_error(3)>, L<RAND_bytes(3)>, +L<DH_free(3)> -=head1 HISTORY +=head1 COPYRIGHT -DH_check() is available in all versions of SSLeay and OpenSSL. -The B<cb_arg> argument to DH_generate_parameters() was added in SSLeay 0.9.0. +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. -In versions before OpenSSL 0.9.5, DH_CHECK_P_NOT_STRONG_PRIME is used -instead of DH_CHECK_P_NOT_SAFE_PRIME. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/DH_get0_pqg.pod b/deps/openssl/openssl/doc/crypto/DH_get0_pqg.pod new file mode 100644 index 0000000000..3809813531 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/DH_get0_pqg.pod @@ -0,0 +1,110 @@ +=pod + +=head1 NAME + +DH_get0_pqg, DH_set0_pqg, DH_get0_key, DH_set0_key, DH_clear_flags, +DH_test_flags, DH_set_flags, DH_get0_engine, DH_get_length, +DH_set_length - Routines for getting and setting data in a DH object + +=head1 SYNOPSIS + + #include <openssl/dh.h> + + void DH_get0_pqg(const DH *dh, + const BIGNUM **p, const BIGNUM **q, const BIGNUM **g); + int DH_set0_pqg(DH *dh, BIGNUM *p, BIGNUM *q, BIGNUM *g); + void DH_get0_key(const DH *dh, + const BIGNUM **pub_key, const BIGNUM **priv_key); + int DH_set0_key(DH *dh, BIGNUM *pub_key, BIGNUM *priv_key); + void DH_clear_flags(DH *dh, int flags); + int DH_test_flags(const DH *dh, int flags); + void DH_set_flags(DH *dh, int flags); + ENGINE *DH_get0_engine(DH *d); + long DH_get_length(const DH *dh); + int DH_set_length(DH *dh, long length); + +=head1 DESCRIPTION + +A DH object contains the parameters B<p>, B<q> and B<g>. Note that the B<q> +parameter is optional. It also contains a public key (B<pub_key>) and +(optionally) a private key (B<priv_key>). + +The B<p>, B<q> and B<g> parameters can be obtained by calling DH_get0_pqg(). +If the parameters have not yet been set then B<*p>, B<*q> and B<*g> will be set +to NULL. Otherwise they are set to pointers to their respective values. These +point directly to the internal representations of the values and therefore +should not be freed directly. + +The B<p>, B<q> and B<g> values can be set by calling DH_set0_pqg() and passing +the new values for B<p>, B<q> and B<g> as parameters to the function. Calling +this function transfers the memory management of the values to the DH object, +and therefore the values that have been passed in should not be freed directly +after this function has been called. The B<q> parameter may be NULL. + +To get the public and private key values use the DH_get0_key() function. A +pointer to the public key will be stored in B<*pub_key>, and a pointer to the +private key will be stored in B<*priv_key>. Either may be NULL if they have not +been set yet, although if the private key has been set then the public key must +be. The values point to the internal representation of the public key and +private key values. This memory should not be freed directly. + +The public and private key values can be set using DH_set0_key(). Either +parameter may be NULL, which means the corresponding DH field is left +untouched. As with DH_set0_pqg() this function transfers the memory management +of the key values to the DH object, and therefore they should not be freed +directly after this function has been called. + +DH_set_flags() sets the flags in the B<flags> parameter on the DH object. +Multiple flags can be passed in one go (bitwise ORed together). Any flags that +are already set are left set. DH_test_flags() tests to see whether the flags +passed in the B<flags> parameter are currently set in the DH object. Multiple +flags can be tested in one go. All flags that are currently set are returned, or +zero if none of the flags are set. DH_clear_flags() clears the specified flags +within the DH object. + +DH_get0_engine() returns a handle to the ENGINE that has been set for this DH +object, or NULL if no such ENGINE has been set. + +The DH_get_length() and DH_set_length() functions get and set the optional +length parameter associated with this DH object. If the length is non-zero then +it is used, otherwise it is ignored. The B<length> parameter indicates the +length of the secret exponent (private key) in bits. + +=head1 NOTES + +Values retrieved with DH_get0_key() are owned by the DH object used +in the call and may therefore I<not> be passed to DH_set0_key(). If +needed, duplicate the received value using BN_dup() and pass the +duplicate. The same applies to DH_get0_pqg() and DH_set0_pqg(). + +=head1 RETURN VALUES + +DH_set0_pqg() and DH_set0_key() return 1 on success or 0 on failure. + +DH_test_flags() returns the current state of the flags in the DH object. + +DH_get0_engine() returns the ENGINE set for the DH object or NULL if no ENGINE +has been set. + +DH_get_length() returns the length of the secret exponent (private key) in bits, +or zero if no such length has been explicitly set. + +=head1 SEE ALSO + +L<dh(3)>, L<DH_new(3)>, L<DH_generate_parameters(3)>, L<DH_generate_key(3)>, +L<DH_set_method(3)>, L<DH_size(3)>, L<DH_meth_new(3)> + +=head1 HISTORY + +The functions described here were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/DH_get_1024_160.pod b/deps/openssl/openssl/doc/crypto/DH_get_1024_160.pod new file mode 100644 index 0000000000..4044f10418 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/DH_get_1024_160.pod @@ -0,0 +1,74 @@ +=pod + +=head1 NAME + +DH_get_1024_160, +DH_get_2048_224, +DH_get_2048_256, +BN_get0_nist_prime_192, +BN_get0_nist_prime_224, +BN_get0_nist_prime_256, +BN_get0_nist_prime_384, +BN_get0_nist_prime_521, +BN_get_rfc2409_prime_768, +BN_get_rfc2409_prime_1024, +BN_get_rfc3526_prime_1536, +BN_get_rfc3526_prime_2048, +BN_get_rfc3526_prime_3072, +BN_get_rfc3526_prime_4096, +BN_get_rfc3526_prime_6144, +BN_get_rfc3526_prime_8192 +- Create standardized public primes or DH pairs + +=head1 SYNOPSIS + + #include <openssl/dh.h> + DH *DH_get_1024_160(void) + DH *DH_get_2048_224(void) + DH *DH_get_2048_256(void) + + const BIGNUM *BN_get0_nist_prime_192(void) + const BIGNUM *BN_get0_nist_prime_224(void) + const BIGNUM *BN_get0_nist_prime_256(void) + const BIGNUM *BN_get0_nist_prime_384(void) + const BIGNUM *BN_get0_nist_prime_521(void) + + BIGNUM *BN_get_rfc2409_prime_768(BIGNUM *bn) + BIGNUM *BN_get_rfc2409_prime_1024(BIGNUM *bn) + BIGNUM *BN_get_rfc3526_prime_1536(BIGNUM *bn) + BIGNUM *BN_get_rfc3526_prime_2048(BIGNUM *bn) + BIGNUM *BN_get_rfc3526_prime_3072(BIGNUM *bn) + BIGNUM *BN_get_rfc3526_prime_4096(BIGNUM *bn) + BIGNUM *BN_get_rfc3526_prime_6144(BIGNUM *bn) + BIGNUM *BN_get_rfc3526_prime_8192(BIGNUM *bn) + +=head1 DESCRIPTION + +DH_get_1024_160(), DH_get_2048_224(), and DH_get_2048_256() each return +a DH object for the IETF RFC 5114 value. + +BN_get0_nist_prime_192(), BN_get0_nist_prime_224(), BN_get0_nist_prime_256(), +BN_get0_nist_prime_384(), and BN_get0_nist_prime_521() functions return +a BIGNUM for the specific NIST prime curve (e.g., P-256). + +BN_get_rfc2409_prime_768(), BN_get_rfc2409_prime_1024(), +BN_get_rfc3526_prime_1536(), BN_get_rfc3526_prime_2048(), +BN_get_rfc3526_prime_3072(), BN_get_rfc3526_prime_4096(), +BN_get_rfc3526_prime_6144(), and BN_get_rfc3526_prime_8192() functions +return a BIGNUM for the specified size from IETF RFC 2409. If B<bn> +is not NULL, the BIGNUM will be set into that location as well. + +=head1 RETURN VALUES + +Defined above. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/DH_get_ex_new_index.pod b/deps/openssl/openssl/doc/crypto/DH_get_ex_new_index.pod deleted file mode 100644 index fa5eab2650..0000000000 --- a/deps/openssl/openssl/doc/crypto/DH_get_ex_new_index.pod +++ /dev/null @@ -1,36 +0,0 @@ -=pod - -=head1 NAME - -DH_get_ex_new_index, DH_set_ex_data, DH_get_ex_data - add application specific data to DH structures - -=head1 SYNOPSIS - - #include <openssl/dh.h> - - int DH_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - - int DH_set_ex_data(DH *d, int idx, void *arg); - - char *DH_get_ex_data(DH *d, int idx); - -=head1 DESCRIPTION - -These functions handle application specific data in DH -structures. Their usage is identical to that of -RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() -as described in L<RSA_get_ex_new_index(3)>. - -=head1 SEE ALSO - -L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, L<dh(3)|dh(3)> - -=head1 HISTORY - -DH_get_ex_new_index(), DH_set_ex_data() and DH_get_ex_data() are -available since OpenSSL 0.9.5. - -=cut diff --git a/deps/openssl/openssl/doc/crypto/DH_meth_new.pod b/deps/openssl/openssl/doc/crypto/DH_meth_new.pod new file mode 100644 index 0000000000..d768da8c6e --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/DH_meth_new.pod @@ -0,0 +1,156 @@ +=pod + +=head1 NAME + +DH_meth_new, DH_meth_free, DH_meth_dup, DH_meth_get0_name, DH_meth_set1_name, +DH_meth_get_flags, DH_meth_set_flags, DH_meth_get0_app_data, +DH_meth_set0_app_data, DH_meth_get_generate_key, DH_meth_set_generate_key, +DH_meth_get_compute_key, DH_meth_set_compute_key, DH_meth_get_bn_mod_exp, +DH_meth_set_bn_mod_exp, DH_meth_get_init, DH_meth_set_init, DH_meth_get_finish, +DH_meth_set_finish, DH_meth_get_generate_params, +DH_meth_set_generate_params - Routines to build up DH methods + +=head1 SYNOPSIS + + #include <openssl/dh.h> + + DH_METHOD *DH_meth_new(const char *name, int flags); + void DH_meth_free(DH_METHOD *dhm); + DH_METHOD *DH_meth_dup(const DH_METHOD *dhm); + const char *DH_meth_get0_name(const DH_METHOD *dhm); + int DH_meth_set1_name(DH_METHOD *dhm, const char *name); + int DH_meth_get_flags(DH_METHOD *dhm); + int DH_meth_set_flags(DH_METHOD *dhm, int flags); + void *DH_meth_get0_app_data(const DH_METHOD *dhm); + int DH_meth_set0_app_data(DH_METHOD *dhm, void *app_data); + int (*DH_meth_get_generate_key(const DH_METHOD *dhm)) (DH *); + int DH_meth_set_generate_key(DH_METHOD *dhm, int (*generate_key) (DH *)); + int (*DH_meth_get_compute_key(const DH_METHOD *dhm)) + (unsigned char *key, const BIGNUM *pub_key, DH *dh); + int DH_meth_set_compute_key(DH_METHOD *dhm, + int (*compute_key) (unsigned char *key, const BIGNUM *pub_key, DH *dh)); + int (*DH_meth_get_bn_mod_exp(const DH_METHOD *dhm)) + (const DH *dh, BIGNUM *r, const BIGNUM *a, const BIGNUM *p, + const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx); + int DH_meth_set_bn_mod_exp(DH_METHOD *dhm, + int (*bn_mod_exp) (const DH *dh, BIGNUM *r, const BIGNUM *a, + const BIGNUM *p, const BIGNUM *m, BN_CTX *ctx, + BN_MONT_CTX *m_ctx)); + int (*DH_meth_get_init(const DH_METHOD *dhm))(DH *); + int DH_meth_set_init(DH_METHOD *dhm, int (*init)(DH *)); + int (*DH_meth_get_finish(const DH_METHOD *dhm)) (DH *); + int DH_meth_set_finish(DH_METHOD *dhm, int (*finish) (DH *)); + int (*DH_meth_get_generate_params(const DH_METHOD *dhm)) + (DH *, int, int, BN_GENCB *); + int DH_meth_set_generate_params(DH_METHOD *dhm, + int (*generate_params) (DH *, int, int, BN_GENCB *)); + +=head1 DESCRIPTION + +The B<DH_METHOD> type is a structure used for the provision of custom DH +implementations. It provides a set of of functions used by OpenSSL for the +implementation of the various DH capabilities. + +DH_meth_new() creates a new B<DH_METHOD> structure. It should be given a +unique B<name> and a set of B<flags>. The B<name> should be a NULL terminated +string, which will be duplicated and stored in the B<DH_METHOD> object. It is +the callers responsibility to free the original string. The flags will be used +during the construction of a new B<DH> object based on this B<DH_METHOD>. Any +new B<DH> object will have those flags set by default. + +DH_meth_dup() creates a duplicate copy of the B<DH_METHOD> object passed as a +parameter. This might be useful for creating a new B<DH_METHOD> based on an +existing one, but with some differences. + +DH_meth_free() destroys a B<DH_METHOD> structure and frees up any memory +associated with it. + +DH_meth_get0_name() will return a pointer to the name of this DH_METHOD. This +is a pointer to the internal name string and so should not be freed by the +caller. DH_meth_set1_name() sets the name of the DH_METHOD to B<name>. The +string is duplicated and the copy is stored in the DH_METHOD structure, so the +caller remains responsible for freeing the memory associated with the name. + +DH_meth_get_flags() returns the current value of the flags associated with this +DH_METHOD. DH_meth_set_flags() provides the ability to set these flags. + +The functions DH_meth_get0_app_data() and DH_meth_set0_app_data() provide the +ability to associate implementation specific data with the DH_METHOD. It is +the application's responsibility to free this data before the DH_METHOD is +freed via a call to DH_meth_free(). + +DH_meth_get_generate_key() and DH_meth_set_generate_key() get and set the +function used for generating a new DH key pair respectively. This function will +be called in response to the application calling DH_generate_key(). The +parameter for the function has the same meaning as for DH_generate_key(). + +DH_meth_get_compute_key() and DH_meth_set_compute_key() get and set the +function used for computing a new DH shared secret respectively. This function +will be called in response to the application calling DH_compute_key(). The +parameters for the function have the same meaning as for DH_compute_key(). + +DH_meth_get_bn_mod_exp() and DH_meth_set_bn_mod_exp() get and set the function +used for computing the following value: + + r = a ^ p mod m + +This function will be called by the default OpenSSL function for +DH_generate_key(). The result is stored in the B<r> parameter. This function +may be NULL unless using the default generate key function, in which case it +must be present. + +DH_meth_get_init() and DH_meth_set_init() get and set the function used +for creating a new DH instance respectively. This function will be +called in response to the application calling DH_new() (if the current default +DH_METHOD is this one) or DH_new_method(). The DH_new() and DH_new_method() +functions will allocate the memory for the new DH object, and a pointer to this +newly allocated structure will be passed as a parameter to the function. This +function may be NULL. + +DH_meth_get_finish() and DH_meth_set_finish() get and set the function used +for destroying an instance of a DH object respectively. This function will be +called in response to the application calling DH_free(). A pointer to the DH +to be destroyed is passed as a parameter. The destroy function should be used +for DH implementation specific clean up. The memory for the DH itself should +not be freed by this function. This function may be NULL. + +DH_meth_get_generate_params() and DH_meth_set_generate_params() get and set the +function used for generating DH parameters respectively. This function will be +called in response to the application calling DH_generate_parameters_ex() (or +DH_generate_parameters()). The parameters for the function have the same +meaning as for DH_generate_parameters_ex(). This function may be NULL. + +=head1 RETURN VALUES + +DH_meth_new() and DH_meth_dup() return the newly allocated DH_METHOD object +or NULL on failure. + +DH_meth_get0_name() and DH_meth_get_flags() return the name and flags +associated with the DH_METHOD respectively. + +All other DH_meth_get_*() functions return the appropriate function pointer +that has been set in the DH_METHOD, or NULL if no such pointer has yet been +set. + +DH_meth_set1_name() and all DH_meth_set_*() functions return 1 on success or +0 on failure. + +=head1 SEE ALSO + +L<dh(3)>, L<DH_new(3)>, L<DH_generate_parameters(3)>, L<DH_generate_key(3)>, +L<DH_set_method(3)>, L<DH_size(3)>, L<DH_get0_pqg(3)> + +=head1 HISTORY + +The functions described here were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/DH_new.pod b/deps/openssl/openssl/doc/crypto/DH_new.pod index 60c930093e..959a470ec4 100644 --- a/deps/openssl/openssl/doc/crypto/DH_new.pod +++ b/deps/openssl/openssl/doc/crypto/DH_new.pod @@ -18,23 +18,29 @@ DH_new() allocates and initializes a B<DH> structure. DH_free() frees the B<DH> structure and its components. The values are erased before the memory is returned to the system. +If B<dh> is NULL nothing is done. =head1 RETURN VALUES If the allocation fails, DH_new() returns B<NULL> and sets an error -code that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns +code that can be obtained by L<ERR_get_error(3)>. Otherwise it returns a pointer to the newly allocated structure. DH_free() returns no value. =head1 SEE ALSO -L<dh(3)|dh(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, -L<DH_generate_parameters(3)|DH_generate_parameters(3)>, -L<DH_generate_key(3)|DH_generate_key(3)> +L<dh(3)>, L<ERR_get_error(3)>, +L<DH_generate_parameters(3)>, +L<DH_generate_key(3)> -=head1 HISTORY +=head1 COPYRIGHT -DH_new() and DH_free() are available in all versions of SSLeay and OpenSSL. +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/DH_set_method.pod b/deps/openssl/openssl/doc/crypto/DH_set_method.pod index d5cdc3be0c..2100608674 100644 --- a/deps/openssl/openssl/doc/crypto/DH_set_method.pod +++ b/deps/openssl/openssl/doc/crypto/DH_set_method.pod @@ -8,7 +8,6 @@ DH_set_method, DH_new_method, DH_OpenSSL - select DH method =head1 SYNOPSIS #include <openssl/dh.h> - #include <openssl/engine.h> void DH_set_default_method(const DH_METHOD *meth); @@ -32,8 +31,11 @@ Initially, the default DH_METHOD is the OpenSSL internal implementation, as returned by DH_OpenSSL(). DH_set_default_method() makes B<meth> the default method for all DH -structures created later. B<NB>: This is true only whilst no ENGINE has been set +structures created later. +B<NB>: This is true only whilst no ENGINE has been set as a default for DH, so this function is no longer recommended. +This function is not thread-safe and should not be called at the same time +as other OpenSSL functions. DH_get_default_method() returns a pointer to the current default DH_METHOD. However, the meaningfulness of this result is dependent on whether the ENGINE @@ -52,35 +54,8 @@ be used for the DH operations. If B<engine> is NULL, the default ENGINE for DH operations is used, and if no default ENGINE is set, the DH_METHOD controlled by DH_set_default_method() is used. -=head1 THE DH_METHOD STRUCTURE - - typedef struct dh_meth_st - { - /* name of the implementation */ - const char *name; - - /* generate private and public DH values for key agreement */ - int (*generate_key)(DH *dh); - - /* compute shared secret */ - int (*compute_key)(unsigned char *key, BIGNUM *pub_key, DH *dh); - - /* compute r = a ^ p mod m (May be NULL for some implementations) */ - int (*bn_mod_exp)(DH *dh, BIGNUM *r, BIGNUM *a, const BIGNUM *p, - const BIGNUM *m, BN_CTX *ctx, - BN_MONT_CTX *m_ctx); - - /* called at DH_new */ - int (*init)(DH *dh); - - /* called at DH_free */ - int (*finish)(DH *dh); - - int flags; - - char *app_data; /* ?? */ - - } DH_METHOD; +A new DH_METHOD object may be constructed using DH_meth_new() (see +L<DH_meth_new(3)>). =head1 RETURN VALUES @@ -94,36 +69,20 @@ the method for B<dh> (including unloading the ENGINE handle if the previous method was supplied by an ENGINE). DH_new_method() returns NULL and sets an error code that can be obtained by -L<ERR_get_error(3)|ERR_get_error(3)> if the allocation fails. Otherwise it +L<ERR_get_error(3)> if the allocation fails. Otherwise it returns a pointer to the newly allocated structure. -=head1 NOTES - -As of version 0.9.7, DH_METHOD implementations are grouped together with other -algorithmic APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in B<ENGINE> modules. If a -default ENGINE is specified for DH functionality using an ENGINE API function, -that will override any DH defaults set using the DH API (ie. -DH_set_default_method()). For this reason, the ENGINE API is the recommended way -to control default implementations for use in DH and other cryptographic -algorithms. - =head1 SEE ALSO -L<dh(3)|dh(3)>, L<DH_new(3)|DH_new(3)> +L<dh(3)>, L<DH_new(3)>, L<DH_meth_new(3)> -=head1 HISTORY +=head1 COPYRIGHT -DH_set_default_method(), DH_get_default_method(), DH_set_method(), -DH_new_method() and DH_OpenSSL() were added in OpenSSL 0.9.4. +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. -DH_set_default_openssl_method() and DH_get_default_openssl_method() replaced -DH_set_default_method() and DH_get_default_method() respectively, and -DH_set_method() and DH_new_method() were altered to use B<ENGINE>s rather than -B<DH_METHOD>s during development of the engine version of OpenSSL 0.9.6. For -0.9.7, the handling of defaults in the ENGINE API was restructured so that this -change was reversed, and behaviour of the other functions resembled more closely -the previous behaviour. The behaviour of defaults in the ENGINE API now -transparently overrides the behaviour of defaults in the DH API without -requiring changing these function prototypes. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/DH_size.pod b/deps/openssl/openssl/doc/crypto/DH_size.pod index 97f26fda78..8c1d151fcf 100644 --- a/deps/openssl/openssl/doc/crypto/DH_size.pod +++ b/deps/openssl/openssl/doc/crypto/DH_size.pod @@ -2,32 +2,46 @@ =head1 NAME -DH_size - get Diffie-Hellman prime size +DH_size, DH_bits - get Diffie-Hellman prime size =head1 SYNOPSIS - #include <openssl/dh.h> +#include <openssl/dh.h> - int DH_size(DH *dh); +int DH_size(const DH *dh); + +int DH_bits(const DH *dh); =head1 DESCRIPTION -This function returns the Diffie-Hellman size in bytes. It can be used +DH_size() returns the Diffie-Hellman prime size in bytes. It can be used to determine how much memory must be allocated for the shared secret computed by DH_compute_key(). -B<dh-E<gt>p> must not be B<NULL>. +DH_bits() returns the number of significant bits. + +B<dh> and B<dh-E<gt>p> must not be B<NULL>. =head1 RETURN VALUE -The size in bytes. +The size. =head1 SEE ALSO -L<dh(3)|dh(3)>, L<DH_generate_key(3)|DH_generate_key(3)> +L<dh(3)>, L<DH_generate_key(3)>, +L<BN_num_bits(3)> =head1 HISTORY -DH_size() is available in all versions of SSLeay and OpenSSL. +DH_bits() was added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/DSA_SIG_new.pod b/deps/openssl/openssl/doc/crypto/DSA_SIG_new.pod index 3ac6140038..7503460a19 100644 --- a/deps/openssl/openssl/doc/crypto/DSA_SIG_new.pod +++ b/deps/openssl/openssl/doc/crypto/DSA_SIG_new.pod @@ -2,6 +2,7 @@ =head1 NAME +DSA_SIG_get0, DSA_SIG_set0, DSA_SIG_new, DSA_SIG_free - allocate and free DSA signature objects =head1 SYNOPSIS @@ -9,32 +10,49 @@ DSA_SIG_new, DSA_SIG_free - allocate and free DSA signature objects #include <openssl/dsa.h> DSA_SIG *DSA_SIG_new(void); - - void DSA_SIG_free(DSA_SIG *a); + void DSA_SIG_free(DSA_SIG *a); + void DSA_SIG_get0(const DSA_SIG *sig, const BIGNUM **pr, const BIGNUM **ps); + int DSA_SIG_set0(DSA_SIG *sig, BIGNUM *r, BIGNUM *s); =head1 DESCRIPTION -DSA_SIG_new() allocates and initializes a B<DSA_SIG> structure. +DSA_SIG_new() allocates an empty B<DSA_SIG> structure. DSA_SIG_free() frees the B<DSA_SIG> structure and its components. The values are erased before the memory is returned to the system. +DSA_SIG_get0() returns internal pointers to the B<r> and B<s> values contained +in B<sig>. + +The B<r> and B<s> values can be set by calling DSA_SIG_set0() and passing the +new values for B<r> and B<s> as parameters to the function. Calling this +function transfers the memory management of the values to the DSA_SIG object, +and therefore the values that have been passed in should not be freed directly +after this function has been called. + =head1 RETURN VALUES If the allocation fails, DSA_SIG_new() returns B<NULL> and sets an error code that can be obtained by -L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns a pointer +L<ERR_get_error(3)>. Otherwise it returns a pointer to the newly allocated structure. DSA_SIG_free() returns no value. +DSA_SIG_set0() returns 1 on success or 0 on failure. + =head1 SEE ALSO -L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, -L<DSA_do_sign(3)|DSA_do_sign(3)> +L<dsa(3)>, L<ERR_get_error(3)>, +L<DSA_do_sign(3)> + +=head1 COPYRIGHT -=head1 HISTORY +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. -DSA_SIG_new() and DSA_SIG_free() were added in OpenSSL 0.9.3. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/DSA_do_sign.pod b/deps/openssl/openssl/doc/crypto/DSA_do_sign.pod index 5dfc733b20..5e56d20944 100644 --- a/deps/openssl/openssl/doc/crypto/DSA_do_sign.pod +++ b/deps/openssl/openssl/doc/crypto/DSA_do_sign.pod @@ -11,7 +11,7 @@ DSA_do_sign, DSA_do_verify - raw DSA signature operations DSA_SIG *DSA_do_sign(const unsigned char *dgst, int dlen, DSA *dsa); int DSA_do_verify(const unsigned char *dgst, int dgst_len, - DSA_SIG *sig, DSA *dsa); + DSA_SIG *sig, DSA *dsa); =head1 DESCRIPTION @@ -19,7 +19,7 @@ DSA_do_sign() computes a digital signature on the B<len> byte message digest B<dgst> using the private key B<dsa> and returns it in a newly allocated B<DSA_SIG> structure. -L<DSA_sign_setup(3)|DSA_sign_setup(3)> may be used to precompute part +L<DSA_sign_setup(3)> may be used to precompute part of the signing operation in case signature generation is time-critical. @@ -32,16 +32,21 @@ key. DSA_do_sign() returns the signature, NULL on error. DSA_do_verify() returns 1 for a valid signature, 0 for an incorrect signature and -1 on error. The error codes can be obtained by -L<ERR_get_error(3)|ERR_get_error(3)>. +L<ERR_get_error(3)>. =head1 SEE ALSO -L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, -L<DSA_SIG_new(3)|DSA_SIG_new(3)>, -L<DSA_sign(3)|DSA_sign(3)> +L<dsa(3)>, L<ERR_get_error(3)>, L<rand(3)>, +L<DSA_SIG_new(3)>, +L<DSA_sign(3)> -=head1 HISTORY +=head1 COPYRIGHT -DSA_do_sign() and DSA_do_verify() were added in OpenSSL 0.9.3. +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/DSA_dup_DH.pod b/deps/openssl/openssl/doc/crypto/DSA_dup_DH.pod index 7f6f0d1115..6967ef3dcf 100644 --- a/deps/openssl/openssl/doc/crypto/DSA_dup_DH.pod +++ b/deps/openssl/openssl/doc/crypto/DSA_dup_DH.pod @@ -19,7 +19,7 @@ contain its length. =head1 RETURN VALUE DSA_dup_DH() returns the new B<DH> structure, and NULL on error. The -error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. +error codes can be obtained by L<ERR_get_error(3)>. =head1 NOTE @@ -27,10 +27,15 @@ Be careful to avoid small subgroup attacks when using this. =head1 SEE ALSO -L<dh(3)|dh(3)>, L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)> +L<dh(3)>, L<dsa(3)>, L<ERR_get_error(3)> -=head1 HISTORY +=head1 COPYRIGHT -DSA_dup_DH() was added in OpenSSL 0.9.4. +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/DSA_generate_key.pod b/deps/openssl/openssl/doc/crypto/DSA_generate_key.pod index af83ccfaa1..4781abed7a 100644 --- a/deps/openssl/openssl/doc/crypto/DSA_generate_key.pod +++ b/deps/openssl/openssl/doc/crypto/DSA_generate_key.pod @@ -20,15 +20,20 @@ The PRNG must be seeded prior to calling DSA_generate_key(). =head1 RETURN VALUE DSA_generate_key() returns 1 on success, 0 otherwise. -The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. +The error codes can be obtained by L<ERR_get_error(3)>. =head1 SEE ALSO -L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, -L<DSA_generate_parameters(3)|DSA_generate_parameters(3)> +L<dsa(3)>, L<ERR_get_error(3)>, L<rand(3)>, +L<DSA_generate_parameters(3)> -=head1 HISTORY +=head1 COPYRIGHT -DSA_generate_key() is available since SSLeay 0.8. +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/DSA_generate_parameters.pod b/deps/openssl/openssl/doc/crypto/DSA_generate_parameters.pod index b1a4d201b7..fc051495f6 100644 --- a/deps/openssl/openssl/doc/crypto/DSA_generate_parameters.pod +++ b/deps/openssl/openssl/doc/crypto/DSA_generate_parameters.pod @@ -9,27 +9,28 @@ DSA_generate_parameters_ex, DSA_generate_parameters - generate DSA parameters #include <openssl/dsa.h> int DSA_generate_parameters_ex(DSA *dsa, int bits, - const unsigned char *seed,int seed_len, - int *counter_ret, unsigned long *h_ret, BN_GENCB *cb); + const unsigned char *seed, int seed_len, + int *counter_ret, unsigned long *h_ret, BN_GENCB *cb); Deprecated: + #if OPENSSL_API_COMPAT < 0x00908000L DSA *DSA_generate_parameters(int bits, unsigned char *seed, int seed_len, int *counter_ret, unsigned long *h_ret, - void (*callback)(int, int, void *), void *cb_arg); + void (*callback)(int, int, void *), void *cb_arg); + #endif =head1 DESCRIPTION DSA_generate_parameters_ex() generates primes p and q and a generator g for use in the DSA and stores the result in B<dsa>. -B<bits> is the length of the prime to be generated; the DSS allows a -maximum of 1024 bits. +B<bits> is the length of the prime p to be generated. +For lengths under 2048 bits, the length of q is 160 bits; for lengths +greater than or equal to 2048 bits, the length of q is set to 256 bits. -If B<seed> is B<NULL> or B<seed_len> E<lt> 20, the primes will be -generated at random. Otherwise, the seed is used to generate -them. If the given seed does not yield a prime q, a new random -seed is chosen. +If B<seed> is NULL, the primes will be generated at random. +If B<seed_len> is less than the length of q, an error is returned. DSA_generate_parameters_ex() places the iteration count in *B<counter_ret> and a counter used for finding a generator in @@ -39,9 +40,9 @@ A callback function may be used to provide feedback about the progress of the key generation. If B<cb> is not B<NULL>, it will be called as shown below. For information on the BN_GENCB structure and the BN_GENCB_call function discussed below, refer to -L<BN_generate_prime(3)|BN_generate_prime(3)>. +L<BN_generate_prime(3)>. -=over 4 +=over 2 =item * @@ -89,7 +90,7 @@ When the generator has been found, B<BN_GENCB_call(cb, 3, 1)> is called. DSA_generate_parameters() (deprecated) works in much the same way as for DSA_generate_parameters_ex, except that no B<dsa> parameter is passed and instead a newly allocated B<DSA> structure is returned. Additionally "old style" callbacks are used instead of the newer BN_GENCB based approach. -Refer to L<BN_generate_prime(3)|BN_generate_prime(3)> for further information. +Refer to L<BN_generate_prime(3)> for further information. =head1 RETURN VALUE @@ -98,7 +99,7 @@ DSA_generate_parameters_ex() returns a 1 on success, or 0 otherwise. DSA_generate_parameters() returns a pointer to the DSA structure, or B<NULL> if the parameter generation fails. -The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. +The error codes can be obtained by L<ERR_get_error(3)>. =head1 BUGS @@ -106,16 +107,16 @@ Seed lengths E<gt> 20 are not supported. =head1 SEE ALSO -L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, -L<DSA_free(3)|DSA_free(3)>, L<BN_generate_prime(3)|BN_generate_prime(3)> +L<DSA_new(3)>, L<ERR_get_error(3)>, L<RAND_bytes(3)>, +L<DSA_free(3)>, L<BN_generate_prime(3)> -=head1 HISTORY +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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>. -DSA_generate_parameters() appeared in SSLeay 0.8. The B<cb_arg> -argument was added in SSLeay 0.9.0. -In versions up to OpenSSL 0.9.4, B<callback(1, ...)> was called -in the inner loop of the Miller-Rabin test whenever it reached the -squaring step (the parameters to B<callback> did not reveal how many -witnesses had been tested); since OpenSSL 0.9.5, B<callback(1, ...)> -is called as in BN_is_prime(3), i.e. once for each witness. =cut diff --git a/deps/openssl/openssl/doc/crypto/DSA_get0_pqg.pod b/deps/openssl/openssl/doc/crypto/DSA_get0_pqg.pod new file mode 100644 index 0000000000..6c1c09a56e --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/DSA_get0_pqg.pod @@ -0,0 +1,102 @@ +=pod + +=head1 NAME + +DSA_get0_pqg, DSA_set0_pqg, DSA_get0_key, DSA_set0_key, DSA_clear_flags, +DSA_test_flags, DSA_set_flags, DSA_get0_engine - Routines for getting and +setting data in a DSA object + +=head1 SYNOPSIS + + #include <openssl/dsa.h> + + void DSA_get0_pqg(const DSA *d, + const BIGNUM **p, const BIGNUM **q, const BIGNUM **g); + int DSA_set0_pqg(DSA *d, BIGNUM *p, BIGNUM *q, BIGNUM *g); + void DSA_get0_key(const DSA *d, + const BIGNUM **pub_key, const BIGNUM **priv_key); + int DSA_set0_key(DSA *d, BIGNUM *pub_key, BIGNUM *priv_key); + void DSA_clear_flags(DSA *d, int flags); + int DSA_test_flags(const DSA *d, int flags); + void DSA_set_flags(DSA *d, int flags); + ENGINE *DSA_get0_engine(DSA *d); + +=head1 DESCRIPTION + +A DSA object contains the parameters B<p>, B<q> and B<g>. It also contains a +public key (B<pub_key>) and (optionally) a private key (B<priv_key>). + +The B<p>, B<q> and B<g> parameters can be obtained by calling DSA_get0_pqg(). +If the parameters have not yet been set then B<*p>, B<*q> and B<*g> will be set +to NULL. Otherwise they are set to pointers to their respective values. These +point directly to the internal representations of the values and therefore +should not be freed directly. + +The B<p>, B<q> and B<g> values can be set by calling DSA_set0_pqg() and passing +the new values for B<p>, B<q> and B<g> as parameters to the function. Calling +this function transfers the memory management of the values to the DSA object, +and therefore the values that have been passed in should not be freed directly +after this function has been called. + +To get the public and private key values use the DSA_get0_key() function. A +pointer to the public key will be stored in B<*pub_key>, and a pointer to the +private key will be stored in B<*priv_key>. Either may be NULL if they have not +been set yet, although if the private key has been set then the public key must +be. The values point to the internal representation of the public key and +private key values. This memory should not be freed directly. + +The public and private key values can be set using DSA_set0_key(). The public +key must be non-NULL the first time this function is called on a given DSA +object. The private key may be NULL. On subsequent calls, either may be NULL, +which means the corresponding DSA field is left untouched. As for DSA_set0_pqg() +this function transfers the memory management of the key values to the DSA +object, and therefore they should not be freed directly after this function has +been called. + +DSA_set_flags() sets the flags in the B<flags> parameter on the DSA object. +Multiple flags can be passed in one go (bitwise ORed together). Any flags that +are already set are left set. DSA_test_flags() tests to see whether the flags +passed in the B<flags> parameter are currently set in the DSA object. Multiple +flags can be tested in one go. All flags that are currently set are returned, or +zero if none of the flags are set. DSA_clear_flags() clears the specified flags +within the DSA object. + +DSA_get0_engine() returns a handle to the ENGINE that has been set for this DSA +object, or NULL if no such ENGINE has been set. + +=head1 NOTES + +Values retrieved with DSA_get0_key() are owned by the DSA object used +in the call and may therefore I<not> be passed to DSA_set0_key(). If +needed, duplicate the received value using BN_dup() and pass the +duplicate. The same applies to DSA_get0_pqg() and DSA_set0_pqg(). + +=head1 RETURN VALUES + +DSA_set0_pqg() and DSA_set0_key() return 1 on success or 0 on failure. + +DSA_test_flags() returns the current state of the flags in the DSA object. + +DSA_get0_engine() returns the ENGINE set for the DSA object or NULL if no ENGINE +has been set. + +=head1 SEE ALSO + +L<dsa(3)>, L<DSA_new(3)>, L<DSA_generate_parameters(3)>, L<DSA_generate_key(3)>, +L<DSA_dup_DH(3)>, L<DSA_do_sign(3)>, L<DSA_set_method(3)>, L<DSA_SIG_new(3)>, +L<DSA_sign(3)>, L<DSA_size(3)>, L<DSA_meth_new(3)> + +=head1 HISTORY + +The functions described here were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/DSA_get_ex_new_index.pod b/deps/openssl/openssl/doc/crypto/DSA_get_ex_new_index.pod deleted file mode 100644 index fb6efc1182..0000000000 --- a/deps/openssl/openssl/doc/crypto/DSA_get_ex_new_index.pod +++ /dev/null @@ -1,36 +0,0 @@ -=pod - -=head1 NAME - -DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data - add application specific data to DSA structures - -=head1 SYNOPSIS - - #include <openssl/dsa.h> - - int DSA_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - - int DSA_set_ex_data(DSA *d, int idx, void *arg); - - char *DSA_get_ex_data(DSA *d, int idx); - -=head1 DESCRIPTION - -These functions handle application specific data in DSA -structures. Their usage is identical to that of -RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() -as described in L<RSA_get_ex_new_index(3)>. - -=head1 SEE ALSO - -L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, L<dsa(3)|dsa(3)> - -=head1 HISTORY - -DSA_get_ex_new_index(), DSA_set_ex_data() and DSA_get_ex_data() are -available since OpenSSL 0.9.5. - -=cut diff --git a/deps/openssl/openssl/doc/crypto/DSA_meth_new.pod b/deps/openssl/openssl/doc/crypto/DSA_meth_new.pod new file mode 100644 index 0000000000..948ab29b58 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/DSA_meth_new.pod @@ -0,0 +1,193 @@ +=pod + +=head1 NAME + +DSA_meth_new, DSA_meth_free, DSA_meth_dup, DSA_meth_get0_name, +DSA_meth_set1_name, DSA_meth_get_flags, DSA_meth_set_flags, +DSA_meth_get0_app_data, DSA_meth_set0_app_data, DSA_meth_get_sign, +DSA_meth_set_sign, DSA_meth_get_sign_setup, DSA_meth_set_sign_setup, +DSA_meth_get_verify, DSA_meth_set_verify, DSA_meth_get_mod_exp, +DSA_meth_set_mod_exp, DSA_meth_get_bn_mod_exp, DSA_meth_set_bn_mod_exp, +DSA_meth_get_init, DSA_meth_set_init, DSA_meth_get_finish, DSA_meth_set_finish, +DSA_meth_get_paramgen, DSA_meth_set_paramgen, DSA_meth_get_keygen, +DSA_meth_set_keygen - Routines to build up DSA methods + +=head1 SYNOPSIS + + #include <openssl/dsa.h> + + DSA_METHOD *DSA_meth_new(const char *name, int flags); + void DSA_meth_free(DSA_METHOD *dsam); + DSA_METHOD *DSA_meth_dup(const DSA_METHOD *meth); + const char *DSA_meth_get0_name(const DSA_METHOD *dsam); + int DSA_meth_set1_name(DSA_METHOD *dsam, const char *name); + int DSA_meth_get_flags(DSA_METHOD *dsam); + int DSA_meth_set_flags(DSA_METHOD *dsam, int flags); + void *DSA_meth_get0_app_data(const DSA_METHOD *dsam); + int DSA_meth_set0_app_data(DSA_METHOD *dsam, void *app_data); + DSA_SIG *(*DSA_meth_get_sign(const DSA_METHOD *dsam)) + (const unsigned char *, int, DSA *); + int DSA_meth_set_sign(DSA_METHOD *dsam, + DSA_SIG *(*sign) (const unsigned char *, int, DSA *)); + int (*DSA_meth_get_sign_setup(const DSA_METHOD *dsam)) + (DSA *, BN_CTX *, BIGNUM **, BIGNUM **); + int DSA_meth_set_sign_setup(DSA_METHOD *dsam, + int (*sign_setup) (DSA *, BN_CTX *, BIGNUM **, BIGNUM **)); + int (*DSA_meth_get_verify(const DSA_METHOD *dsam)) + (const unsigned char *, int , DSA_SIG *, DSA *); + int DSA_meth_set_verify(DSA_METHOD *dsam, + int (*verify) (const unsigned char *, int, DSA_SIG *, DSA *)); + int (*DSA_meth_get_mod_exp(const DSA_METHOD *dsam)) + (DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1, BIGNUM *a2, BIGNUM *p2, + BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *in_mont); + int DSA_meth_set_mod_exp(DSA_METHOD *dsam, + int (*mod_exp) (DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1, BIGNUM *a2, + BIGNUM *p2, BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *mont)); + int (*DSA_meth_get_bn_mod_exp(const DSA_METHOD *dsam)) + (DSA *dsa, BIGNUM *r, BIGNUM *a, const BIGNUM *p, const BIGNUM *m, + BN_CTX *ctx, BN_MONT_CTX *mont); + int DSA_meth_set_bn_mod_exp(DSA_METHOD *dsam, + int (*bn_mod_exp) (DSA *dsa, BIGNUM *r, BIGNUM *a, const BIGNUM *p, + const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *mont)); + int (*DSA_meth_get_init(const DSA_METHOD *dsam))(DSA *); + int DSA_meth_set_init(DSA_METHOD *dsam, int (*init)(DSA *)); + int (*DSA_meth_get_finish(const DSA_METHOD *dsam)) (DSA *); + int DSA_meth_set_finish(DSA_METHOD *dsam, int (*finish) (DSA *)); + int (*DSA_meth_get_paramgen(const DSA_METHOD *dsam)) + (DSA *, int, const unsigned char *, int, int *, unsigned long *, + BN_GENCB *); + int DSA_meth_set_paramgen(DSA_METHOD *dsam, + int (*paramgen) (DSA *, int, const unsigned char *, int, int *, + unsigned long *, BN_GENCB *)); + int (*DSA_meth_get_keygen(const DSA_METHOD *dsam)) (DSA *); + int DSA_meth_set_keygen(DSA_METHOD *dsam, int (*keygen) (DSA *)); + +=head1 DESCRIPTION + +The B<DSA_METHOD> type is a structure used for the provision of custom DSA +implementations. It provides a set of of functions used by OpenSSL for the +implementation of the various DSA capabilities. See the L<dsa> page for more +information. + +DSA_meth_new() creates a new B<DSA_METHOD> structure. It should be given a +unique B<name> and a set of B<flags>. The B<name> should be a NULL terminated +string, which will be duplicated and stored in the B<DSA_METHOD> object. It is +the callers responsibility to free the original string. The flags will be used +during the construction of a new B<DSA> object based on this B<DSA_METHOD>. Any +new B<DSA> object will have those flags set by default. + +DSA_meth_dup() creates a duplicate copy of the B<DSA_METHOD> object passed as a +parameter. This might be useful for creating a new B<DSA_METHOD> based on an +existing one, but with some differences. + +DSA_meth_free() destroys a B<DSA_METHOD> structure and frees up any memory +associated with it. + +DSA_meth_get0_name() will return a pointer to the name of this DSA_METHOD. This +is a pointer to the internal name string and so should not be freed by the +caller. DSA_meth_set1_name() sets the name of the DSA_METHOD to B<name>. The +string is duplicated and the copy is stored in the DSA_METHOD structure, so the +caller remains responsible for freeing the memory associated with the name. + +DSA_meth_get_flags() returns the current value of the flags associated with this +DSA_METHOD. DSA_meth_set_flags() provides the ability to set these flags. + +The functions DSA_meth_get0_app_data() and DSA_meth_set0_app_data() provide the +ability to associate implementation specific data with the DSA_METHOD. It is +the application's responsibility to free this data before the DSA_METHOD is +freed via a call to DSA_meth_free(). + +DSA_meth_get_sign() and DSA_meth_set_sign() get and set the function used for +creating a DSA signature respectively. This function will be +called in response to the application calling DSA_do_sign() (or DSA_sign()). The +parameters for the function have the same meaning as for DSA_do_sign(). + +DSA_meth_get_sign_setup() and DSA_meth_set_sign_setup() get and set the function +used for precalculating the DSA signature values B<k^-1> and B<r>. This function +will be called in response to the application calling DSA_sign_setup(). The +parameters for the function have the same meaning as for DSA_sign_setup(). + +DSA_meth_get_verify() and DSA_meth_set_verify() get and set the function used +for verifying a DSA signature respectively. This function will be called in +response to the application calling DSA_do_verify() (or DSA_verify()). The +parameters for the function have the same meaning as for DSA_do_verify(). + +DSA_meth_get_mod_exp() and DSA_meth_set_mod_exp() get and set the function used +for computing the following value: + + rr = a1^p1 * a2^p2 mod m + +This function will be called by the default OpenSSL method during verification +of a DSA signature. The result is stored in the B<rr> parameter. This function +may be NULL. + +DSA_meth_get_bn_mod_exp() and DSA_meth_set_bn_mod_exp() get and set the function +used for computing the following value: + + r = a ^ p mod m + +This function will be called by the default OpenSSL function for +DSA_sign_setup(). The result is stored in the B<r> parameter. This function +may be NULL. + +DSA_meth_get_init() and DSA_meth_set_init() get and set the function used +for creating a new DSA instance respectively. This function will be +called in response to the application calling DSA_new() (if the current default +DSA_METHOD is this one) or DSA_new_method(). The DSA_new() and DSA_new_method() +functions will allocate the memory for the new DSA object, and a pointer to this +newly allocated structure will be passed as a parameter to the function. This +function may be NULL. + +DSA_meth_get_finish() and DSA_meth_set_finish() get and set the function used +for destroying an instance of a DSA object respectively. This function will be +called in response to the application calling DSA_free(). A pointer to the DSA +to be destroyed is passed as a parameter. The destroy function should be used +for DSA implementation specific clean up. The memory for the DSA itself should +not be freed by this function. This function may be NULL. + +DSA_meth_get_paramgen() and DSA_meth_set_paramgen() get and set the function +used for generating DSA parameters respectively. This function will be called in +response to the application calling DSA_generate_parameters_ex() (or +DSA_generate_parameters()). The parameters for the function have the same +meaning as for DSA_generate_parameters_ex(). + +DSA_meth_get_keygen() and DSA_meth_set_keygen() get and set the function +used for generating a new DSA key pair respectively. This function will be +called in response to the application calling DSA_generate_key(). The parameter +for the function has the same meaning as for DSA_generate_key(). + +=head1 RETURN VALUES + +DSA_meth_new() and DSA_meth_dup() return the newly allocated DSA_METHOD object +or NULL on failure. + +DSA_meth_get0_name() and DSA_meth_get_flags() return the name and flags +associated with the DSA_METHOD respectively. + +All other DSA_meth_get_*() functions return the appropriate function pointer +that has been set in the DSA_METHOD, or NULL if no such pointer has yet been +set. + +DSA_meth_set1_name() and all DSA_meth_set_*() functions return 1 on success or +0 on failure. + +=head1 SEE ALSO + +L<dsa(3)>, L<DSA_new(3)>, L<DSA_generate_parameters(3)>, L<DSA_generate_key(3)>, +L<DSA_dup_DH(3)>, L<DSA_do_sign(3)>, L<DSA_set_method(3)>, L<DSA_SIG_new(3)>, +L<DSA_sign(3)>, L<DSA_size(3)>, L<DSA_get0_pqg(3)> + +=head1 HISTORY + +The functions described here were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/DSA_new.pod b/deps/openssl/openssl/doc/crypto/DSA_new.pod index 48e9b82a09..a967ab5da5 100644 --- a/deps/openssl/openssl/doc/crypto/DSA_new.pod +++ b/deps/openssl/openssl/doc/crypto/DSA_new.pod @@ -19,24 +19,30 @@ calling DSA_new_method(NULL). DSA_free() frees the B<DSA> structure and its components. The values are erased before the memory is returned to the system. +If B<dsa> is NULL nothing is done. =head1 RETURN VALUES If the allocation fails, DSA_new() returns B<NULL> and sets an error code that can be obtained by -L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns a pointer +L<ERR_get_error(3)>. Otherwise it returns a pointer to the newly allocated structure. DSA_free() returns no value. =head1 SEE ALSO -L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, -L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>, -L<DSA_generate_key(3)|DSA_generate_key(3)> +L<dsa(3)>, L<ERR_get_error(3)>, +L<DSA_generate_parameters(3)>, +L<DSA_generate_key(3)> -=head1 HISTORY +=head1 COPYRIGHT -DSA_new() and DSA_free() are available in all versions of SSLeay and OpenSSL. +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/DSA_set_method.pod b/deps/openssl/openssl/doc/crypto/DSA_set_method.pod index 9c1434bd8d..d870f56f26 100644 --- a/deps/openssl/openssl/doc/crypto/DSA_set_method.pod +++ b/deps/openssl/openssl/doc/crypto/DSA_set_method.pod @@ -8,7 +8,6 @@ DSA_set_method, DSA_new_method, DSA_OpenSSL - select DSA method =head1 SYNOPSIS #include <openssl/dsa.h> - #include <openssl/engine.h> void DSA_set_default_method(const DSA_METHOD *meth); @@ -32,12 +31,15 @@ Initially, the default DSA_METHOD is the OpenSSL internal implementation, as returned by DSA_OpenSSL(). DSA_set_default_method() makes B<meth> the default method for all DSA -structures created later. B<NB>: This is true only whilst no ENGINE has +structures created later. +B<NB>: This is true only whilst no ENGINE has been set as a default for DSA, so this function is no longer recommended. +This function is not thread-safe and should not be called at the same time +as other OpenSSL functions. DSA_get_default_method() returns a pointer to the current default DSA_METHOD. However, the meaningfulness of this result is dependent on -whether the ENGINE API is being used, so this function is no longer +whether the ENGINE API is being used, so this function is no longer recommended. DSA_set_method() selects B<meth> to perform all operations using the key @@ -47,55 +49,14 @@ be released during the change. It is possible to have DSA keys that only work with certain DSA_METHOD implementations (eg. from an ENGINE module that supports embedded hardware-protected keys), and in such cases attempting to change the DSA_METHOD for the key can have unexpected -results. +results. See L<DSA_meth_new> for information on constructing custom DSA_METHOD +objects; DSA_new_method() allocates and initializes a DSA structure so that B<engine> will be used for the DSA operations. If B<engine> is NULL, the default engine for DSA operations is used, and if no default ENGINE is set, the DSA_METHOD controlled by DSA_set_default_method() is used. -=head1 THE DSA_METHOD STRUCTURE - -struct - { - /* name of the implementation */ - const char *name; - - /* sign */ - DSA_SIG *(*dsa_do_sign)(const unsigned char *dgst, int dlen, - DSA *dsa); - - /* pre-compute k^-1 and r */ - int (*dsa_sign_setup)(DSA *dsa, BN_CTX *ctx_in, BIGNUM **kinvp, - BIGNUM **rp); - - /* verify */ - int (*dsa_do_verify)(const unsigned char *dgst, int dgst_len, - DSA_SIG *sig, DSA *dsa); - - /* compute rr = a1^p1 * a2^p2 mod m (May be NULL for some - implementations) */ - int (*dsa_mod_exp)(DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1, - BIGNUM *a2, BIGNUM *p2, BIGNUM *m, - BN_CTX *ctx, BN_MONT_CTX *in_mont); - - /* compute r = a ^ p mod m (May be NULL for some implementations) */ - int (*bn_mod_exp)(DSA *dsa, BIGNUM *r, BIGNUM *a, - const BIGNUM *p, const BIGNUM *m, - BN_CTX *ctx, BN_MONT_CTX *m_ctx); - - /* called at DSA_new */ - int (*init)(DSA *DSA); - - /* called at DSA_free */ - int (*finish)(DSA *DSA); - - int flags; - - char *app_data; /* ?? */ - - } DSA_METHOD; - =head1 RETURN VALUES DSA_OpenSSL() and DSA_get_default_method() return pointers to the respective @@ -108,36 +69,20 @@ the method for B<dsa> (including unloading the ENGINE handle if the previous method was supplied by an ENGINE). DSA_new_method() returns NULL and sets an error code that can be -obtained by L<ERR_get_error(3)|ERR_get_error(3)> if the allocation +obtained by L<ERR_get_error(3)> if the allocation fails. Otherwise it returns a pointer to the newly allocated structure. -=head1 NOTES - -As of version 0.9.7, DSA_METHOD implementations are grouped together with other -algorithmic APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in B<ENGINE> modules. If a -default ENGINE is specified for DSA functionality using an ENGINE API function, -that will override any DSA defaults set using the DSA API (ie. -DSA_set_default_method()). For this reason, the ENGINE API is the recommended way -to control default implementations for use in DSA and other cryptographic -algorithms. - =head1 SEE ALSO -L<dsa(3)|dsa(3)>, L<DSA_new(3)|DSA_new(3)> +L<dsa(3)>, L<DSA_new(3)>, L<DSA_meth_new(3)> -=head1 HISTORY +=head1 COPYRIGHT -DSA_set_default_method(), DSA_get_default_method(), DSA_set_method(), -DSA_new_method() and DSA_OpenSSL() were added in OpenSSL 0.9.4. +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. -DSA_set_default_openssl_method() and DSA_get_default_openssl_method() replaced -DSA_set_default_method() and DSA_get_default_method() respectively, and -DSA_set_method() and DSA_new_method() were altered to use B<ENGINE>s rather than -B<DSA_METHOD>s during development of the engine version of OpenSSL 0.9.6. For -0.9.7, the handling of defaults in the ENGINE API was restructured so that this -change was reversed, and behaviour of the other functions resembled more closely -the previous behaviour. The behaviour of defaults in the ENGINE API now -transparently overrides the behaviour of defaults in the DSA API without -requiring changing these function prototypes. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/DSA_sign.pod b/deps/openssl/openssl/doc/crypto/DSA_sign.pod index 97389e8ec8..ba0f6b863e 100644 --- a/deps/openssl/openssl/doc/crypto/DSA_sign.pod +++ b/deps/openssl/openssl/doc/crypto/DSA_sign.pod @@ -8,14 +8,14 @@ DSA_sign, DSA_sign_setup, DSA_verify - DSA signatures #include <openssl/dsa.h> - int DSA_sign(int type, const unsigned char *dgst, int len, - unsigned char *sigret, unsigned int *siglen, DSA *dsa); + int DSA_sign(int type, const unsigned char *dgst, int len, + unsigned char *sigret, unsigned int *siglen, DSA *dsa); - int DSA_sign_setup(DSA *dsa, BN_CTX *ctx, BIGNUM **kinvp, + int DSA_sign_setup(DSA *dsa, BN_CTX *ctx, BIGNUM **kinvp, BIGNUM **rp); - int DSA_verify(int type, const unsigned char *dgst, int len, - unsigned char *sigbuf, int siglen, DSA *dsa); + int DSA_verify(int type, const unsigned char *dgst, int len, + unsigned char *sigbuf, int siglen, DSA *dsa); =head1 DESCRIPTION @@ -46,7 +46,7 @@ is called. DSA_sign() and DSA_sign_setup() return 1 on success, 0 on error. DSA_verify() returns 1 for a valid signature, 0 for an incorrect signature and -1 on error. The error codes can be obtained by -L<ERR_get_error(3)|ERR_get_error(3)>. +L<ERR_get_error(3)>. =head1 CONFORMING TO @@ -55,12 +55,16 @@ Standard, DSS), ANSI X9.30 =head1 SEE ALSO -L<dsa(3)|dsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, -L<DSA_do_sign(3)|DSA_do_sign(3)> +L<dsa(3)>, L<ERR_get_error(3)>, L<rand(3)>, +L<DSA_do_sign(3)> -=head1 HISTORY +=head1 COPYRIGHT -DSA_sign() and DSA_verify() are available in all versions of SSLeay. -DSA_sign_setup() was added in SSLeay 0.8. +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/DSA_size.pod b/deps/openssl/openssl/doc/crypto/DSA_size.pod index ba4f650361..16e6f3a963 100644 --- a/deps/openssl/openssl/doc/crypto/DSA_size.pod +++ b/deps/openssl/openssl/doc/crypto/DSA_size.pod @@ -2,32 +2,43 @@ =head1 NAME -DSA_size - get DSA signature size +DSA_size, DSA_bits - get DSA signature size or key bits =head1 SYNOPSIS #include <openssl/dsa.h> int DSA_size(const DSA *dsa); + int DSA_bits(const DSA *dsa); =head1 DESCRIPTION -This function returns the size of an ASN.1 encoded DSA signature in -bytes. It can be used to determine how much memory must be allocated -for a DSA signature. +DSA_size() returns the maximum size of an ASN.1 encoded DSA signature +for key B<dsa> in bytes. It can be used to determine how much memory must +be allocated for a DSA signature. B<dsa-E<gt>q> must not be B<NULL>. +DSA_bits() returns the number of bits in key B<dsa>: this is the number +of bits in the B<p> parameter. + =head1 RETURN VALUE -The size in bytes. +DSA_size() returns the size in bytes. + +DSA_bits() returns the number of bits in the key. =head1 SEE ALSO -L<dsa(3)|dsa(3)>, L<DSA_sign(3)|DSA_sign(3)> +L<dsa(3)>, L<DSA_sign(3)> + +=head1 COPYRIGHT -=head1 HISTORY +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. -DSA_size() is available in all versions of SSLeay and OpenSSL. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/ECDSA_SIG_new.pod b/deps/openssl/openssl/doc/crypto/ECDSA_SIG_new.pod new file mode 100644 index 0000000000..9e1f662c62 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/ECDSA_SIG_new.pod @@ -0,0 +1,207 @@ +=pod + +=head1 NAME + +ECDSA_SIG_get0, ECDSA_SIG_set0, +ECDSA_SIG_new, ECDSA_SIG_free, i2d_ECDSA_SIG, d2i_ECDSA_SIG, ECDSA_size, +ECDSA_sign, ECDSA_do_sign, ECDSA_verify, ECDSA_do_verify, ECDSA_sign_setup, +ECDSA_sign_ex, ECDSA_do_sign_ex - low level elliptic curve digital signature +algorithm (ECDSA) functions + +=head1 SYNOPSIS + + #include <openssl/ecdsa.h> + + ECDSA_SIG *ECDSA_SIG_new(void); + void ECDSA_SIG_free(ECDSA_SIG *sig); + void ECDSA_SIG_get0(const ECDSA_SIG *sig, const BIGNUM **pr, const BIGNUM **ps); + int ECDSA_SIG_set0(ECDSA_SIG *sig, BIGNUM *r, BIGNUM *s); + int i2d_ECDSA_SIG(const ECDSA_SIG *sig, unsigned char **pp); + ECDSA_SIG *d2i_ECDSA_SIG(ECDSA_SIG **sig, const unsigned char **pp, long len); + int ECDSA_size(const EC_KEY *eckey); + + int ECDSA_sign(int type, const unsigned char *dgst, int dgstlen, + unsigned char *sig, unsigned int *siglen, EC_KEY *eckey); + ECDSA_SIG *ECDSA_do_sign(const unsigned char *dgst, int dgst_len, + EC_KEY *eckey); + + int ECDSA_verify(int type, const unsigned char *dgst, int dgstlen, + const unsigned char *sig, int siglen, EC_KEY *eckey); + int ECDSA_do_verify(const unsigned char *dgst, int dgst_len, + const ECDSA_SIG *sig, EC_KEY* eckey); + + ECDSA_SIG *ECDSA_do_sign_ex(const unsigned char *dgst, int dgstlen, + const BIGNUM *kinv, const BIGNUM *rp, + EC_KEY *eckey); + int ECDSA_sign_setup(EC_KEY *eckey, BN_CTX *ctx, BIGNUM **kinv, BIGNUM **rp); + int ECDSA_sign_ex(int type, const unsigned char *dgst, int dgstlen, + unsigned char *sig, unsigned int *siglen, + const BIGNUM *kinv, const BIGNUM *rp, EC_KEY *eckey); + +=head1 DESCRIPTION + +Note: these functions provide a low level interface to ECDSA. Most +applications should use the higher level B<EVP> interface such as +L<EVP_DigestSignInit(3)> or L<EVP_DigestVerifyInit(3)> instead. + +B<ECDSA_SIG> is an opaque structure consisting of two BIGNUMs for the +B<r> and B<s> value of an ECDSA signature (see X9.62 or FIPS 186-2). + +ECDSA_SIG_new() allocates an empty B<ECDSA_SIG> structure. Note: before +OpenSSL 1.1.0 the: the B<r> and B<s> components were initialised. + +ECDSA_SIG_free() frees the B<ECDSA_SIG> structure B<sig>. + +ECDSA_SIG_get0() returns internal pointers the B<r> and B<s> values contained +in B<sig>. + +The B<r> and B<s> values can be set by calling ECDSA_SIG_set0() and passing the +new values for B<r> and B<s> as parameters to the function. Calling this +function transfers the memory management of the values to the ECDSA_SIG object, +and therefore the values that have been passed in should not be freed directly +after this function has been called. + +i2d_ECDSA_SIG() creates the DER encoding of the ECDSA signature B<sig> and +writes the encoded signature to B<*pp> (note: if B<pp> is NULL i2d_ECDSA_SIG() +returns the expected length in bytes of the DER encoded signature). +i2d_ECDSA_SIG() returns the length of the DER encoded signature (or 0 on +error). + +d2i_ECDSA_SIG() decodes a DER encoded ECDSA signature and returns the decoded +signature in a newly allocated B<ECDSA_SIG> structure. B<*sig> points to the +buffer containing the DER encoded signature of size B<len>. + +ECDSA_size() returns the maximum length of a DER encoded ECDSA signature +created with the private EC key B<eckey>. + +ECDSA_sign() computes a digital signature of the B<dgstlen> bytes hash value +B<dgst> using the private EC key B<eckey>. The DER encoded signatures is +stored in B<sig> and its length is returned in B<sig_len>. Note: B<sig> must +point to ECDSA_size(eckey) bytes of memory. The parameter B<type> is currently +ignored. ECDSA_sign() is wrapper function for ECDSA_sign_ex() with B<kinv> +and B<rp> set to NULL. + +ECDSA_do_sign() is similar to ECDSA_sign() except the signature is returned +as a newly allocated B<ECDSA_SIG> structure (or NULL on error). ECDSA_do_sign() +is a wrapper function for ECDSA_do_sign_ex() with B<kinv> and B<rp> set to +NULL. + +ECDSA_verify() verifies that the signature in B<sig> of size B<siglen> is a +valid ECDSA signature of the hash value B<dgst> of size B<dgstlen> using the +public key B<eckey>. The parameter B<type> is ignored. + +ECDSA_do_verify() is similar to ECDSA_verify() except the signature is +presented in the form of a pointer to an B<ECDSA_SIG> structure. + +The remaining functions utilise the internal B<kinv> and B<r> values used +during signature computation. Most applications will never need to call these +and some external ECDSA ENGINE implementations may not support them at all if +either B<kinv> or B<r> is not B<NULL>. + +ECDSA_sign_setup() may be used to precompute parts of the signing operation. +B<eckey> is the private EC key and B<ctx> is a pointer to B<BN_CTX> structure +(or NULL). The precomputed values or returned in B<kinv> and B<rp> and can be +used in a later call to ECDSA_sign_ex() or ECDSA_do_sign_ex(). + +ECDSA_sign_ex() computes a digital signature of the B<dgstlen> bytes hash value +B<dgst> using the private EC key B<eckey> and the optional pre-computed values +B<kinv> and B<rp>. The DER encoded signature is stored in B<sig> and its +length is returned in B<sig_len>. Note: B<sig> must point to ECDSA_size(eckey) +bytes of memory. The parameter B<type> is ignored. + +ECDSA_do_sign_ex() is similar to ECDSA_sign_ex() except the signature is +returned as a newly allocated B<ECDSA_SIG> structure (or NULL on error). + +=head1 RETURN VALUES + +ECDSA_SIG_set0() returns 1 on success or 0 on failure. + +ECDSA_size() returns the maximum length signature or 0 on error. + +ECDSA_sign(), ECDSA_sign_ex() and ECDSA_sign_setup() return 1 if successful +or 0 on error. + +ECDSA_do_sign() and ECDSA_do_sign_ex() return a pointer to an allocated +B<ECDSA_SIG> structure or NULL on error. + +ECDSA_verify() and ECDSA_do_verify() return 1 for a valid +signature, 0 for an invalid signature and -1 on error. +The error codes can be obtained by L<ERR_get_error(3)>. + +=head1 EXAMPLES + +Creating an ECDSA signature of a given SHA-256 hash value using the +named curve prime256v1 (aka P-256). + +First step: create an EC_KEY object (note: this part is B<not> ECDSA +specific) + + int ret; + ECDSA_SIG *sig; + EC_KEY *eckey; + eckey = EC_KEY_new_by_curve_name(NID_X9_62_prime256v1); + if (eckey == NULL) { + /* error */ + } + if (EC_KEY_generate_key(eckey) == 0) { + /* error */ + } + +Second step: compute the ECDSA signature of a SHA-256 hash value +using ECDSA_do_sign(): + + sig = ECDSA_do_sign(digest, 32, eckey); + if (sig == NULL) { + /* error */ + } + +or using ECDSA_sign(): + + unsigned char *buffer, *pp; + int buf_len; + buf_len = ECDSA_size(eckey); + buffer = OPENSSL_malloc(buf_len); + pp = buffer; + if (ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey) == 0) { + /* error */ + } + +Third step: verify the created ECDSA signature using ECDSA_do_verify(): + + ret = ECDSA_do_verify(digest, 32, sig, eckey); + +or using ECDSA_verify(): + + ret = ECDSA_verify(0, digest, 32, buffer, buf_len, eckey); + +and finally evaluate the return value: + + if (ret == 1) { + /* signature ok */ + } else if (ret == 0) { + /* incorrect signature */ + } else { + /* error */ + } + +=head1 CONFORMING TO + +ANSI X9.62, US Federal Information Processing Standard FIPS 186-2 +(Digital Signature Standard, DSS) + +=head1 SEE ALSO + +L<DSA_new(3)>, +L<EVP_DigestSignInit(3)>, +L<EVP_DigestVerifyInit(3)> + +=head1 COPYRIGHT + +Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/ECPKParameters_print.pod b/deps/openssl/openssl/doc/crypto/ECPKParameters_print.pod new file mode 100644 index 0000000000..24b6bb9e04 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/ECPKParameters_print.pod @@ -0,0 +1,44 @@ +=pod + +=head1 NAME + +ECPKParameters_print, ECPKParameters_print_fp - Functions for decoding and +encoding ASN1 representations of elliptic curve entities + +=head1 SYNOPSIS + + #include <openssl/ec.h> + + int ECPKParameters_print(BIO *bp, const EC_GROUP *x, int off); + int ECPKParameters_print_fp(FILE *fp, const EC_GROUP *x, int off); + +=head1 DESCRIPTION + +The ECPKParameters represent the public parameters for an +B<EC_GROUP> structure, which represents a curve. + +The ECPKParameters_print() and ECPKParameters_print_fp() functions print +a human-readable output of the public parameters of the EC_GROUP to B<bp> +or B<fp>. The output lines are indented by B<off> spaces. + +=head1 RETURN VALUES + +ECPKParameters_print() and ECPKParameters_print_fp() +return 1 for success and 0 if an error occurs. + +=head1 SEE ALSO + +L<crypto(7)>, L<EC_GROUP_new(3)>, L<EC_GROUP_copy(3)>, +L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_KEY_new(3)>, +L<EC_GFp_simple_method(3)>, + +=head1 COPYRIGHT + +Copyright 2013-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EC_GFp_simple_method.pod b/deps/openssl/openssl/doc/crypto/EC_GFp_simple_method.pod index aff20ac175..f283d8e71e 100644 --- a/deps/openssl/openssl/doc/crypto/EC_GFp_simple_method.pod +++ b/deps/openssl/openssl/doc/crypto/EC_GFp_simple_method.pod @@ -2,7 +2,7 @@ =head1 NAME -EC_GFp_simple_method, EC_GFp_mont_method, EC_GFp_nist_method, EC_GFp_nistp224_method, EC_GFp_nistp256_method, EC_GFp_nistp521_method, EC_GF2m_simple_method, EC_METHOD_get_field_type - Functions for obtaining B<EC_METHOD> objects. +EC_GFp_simple_method, EC_GFp_mont_method, EC_GFp_nist_method, EC_GFp_nistp224_method, EC_GFp_nistp256_method, EC_GFp_nistp521_method, EC_GF2m_simple_method, EC_METHOD_get_field_type - Functions for obtaining EC_METHOD objects =head1 SYNOPSIS @@ -22,7 +22,7 @@ EC_GFp_simple_method, EC_GFp_mont_method, EC_GFp_nist_method, EC_GFp_nistp224_me =head1 DESCRIPTION The Elliptic Curve library provides a number of different implementations through a single common interface. -When constructing a curve using EC_GROUP_new (see L<EC_GROUP_new(3)|EC_GROUP_new(3)>) an +When constructing a curve using EC_GROUP_new (see L<EC_GROUP_new(3)>) an implementation method must be provided. The functions described here all return a const pointer to an B<EC_METHOD> structure that can be passed to EC_GROUP_NEW. It is important that the correct implementation type for the form of curve selected is used. @@ -31,9 +31,9 @@ For F2^m curves there is only one implementation choice, i.e. EC_GF2_simple_meth For Fp curves the lowest common denominator implementation is the EC_GFp_simple_method implementation. All other implementations are based on this one. EC_GFp_mont_method builds on EC_GFp_simple_method but adds the -use of montgomery multiplication (see L<BN_mod_mul_montgomery(3)|BN_mod_mul_montgomery(3)>). EC_GFp_nist_method +use of montgomery multiplication (see L<BN_mod_mul_montgomery(3)>). EC_GFp_nist_method offers an implementation optimised for use with NIST recommended curves (NIST curves are available through -EC_GROUP_new_by_curve_name as described in L<EC_GROUP_new(3)|EC_GROUP_new(3)>). +EC_GROUP_new_by_curve_name as described in L<EC_GROUP_new(3)>). The functions EC_GFp_nistp224_method, EC_GFp_nistp256_method and EC_GFp_nistp521_method offer 64 bit optimised implementations for the NIST P224, P256 and P521 curves respectively. Note, however, that these @@ -52,9 +52,18 @@ EC_METHOD_get_field_type returns an integer that identifies the type of field th =head1 SEE ALSO -L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, -L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>, -L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>, -L<BN_mod_mul_montgomery(3)|BN_mod_mul_montgomery(3)> +L<crypto(7)>, L<EC_GROUP_new(3)>, L<EC_GROUP_copy(3)>, +L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_KEY_new(3)>, +L<d2i_ECPKParameters(3)>, +L<BN_mod_mul_montgomery(3)> + +=head1 COPYRIGHT + +Copyright 2013-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EC_GROUP_copy.pod b/deps/openssl/openssl/doc/crypto/EC_GROUP_copy.pod index 49dc01ced1..fd5f58c919 100644 --- a/deps/openssl/openssl/doc/crypto/EC_GROUP_copy.pod +++ b/deps/openssl/openssl/doc/crypto/EC_GROUP_copy.pod @@ -2,12 +2,21 @@ =head1 NAME -EC_GROUP_copy, EC_GROUP_dup, EC_GROUP_method_of, EC_GROUP_set_generator, EC_GROUP_get0_generator, EC_GROUP_get_order, EC_GROUP_get_cofactor, EC_GROUP_set_curve_name, EC_GROUP_get_curve_name, EC_GROUP_set_asn1_flag, EC_GROUP_get_asn1_flag, EC_GROUP_set_point_conversion_form, EC_GROUP_get_point_conversion_form, EC_GROUP_get0_seed, EC_GROUP_get_seed_len, EC_GROUP_set_seed, EC_GROUP_get_degree, EC_GROUP_check, EC_GROUP_check_discriminant, EC_GROUP_cmp, EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis, EC_GROUP_get_pentanomial_basis - Functions for manipulating B<EC_GROUP> objects. +EC_GROUP_get0_order, EC_GROUP_order_bits, EC_GROUP_get0_cofactor, +EC_GROUP_copy, EC_GROUP_dup, EC_GROUP_method_of, EC_GROUP_set_generator, +EC_GROUP_get0_generator, EC_GROUP_get_order, EC_GROUP_get_cofactor, +EC_GROUP_set_curve_name, EC_GROUP_get_curve_name, EC_GROUP_set_asn1_flag, +EC_GROUP_get_asn1_flag, EC_GROUP_set_point_conversion_form, +EC_GROUP_get_point_conversion_form, EC_GROUP_get0_seed, +EC_GROUP_get_seed_len, EC_GROUP_set_seed, EC_GROUP_get_degree, +EC_GROUP_check, EC_GROUP_check_discriminant, EC_GROUP_cmp, +EC_GROUP_get_basis_type, EC_GROUP_get_trinomial_basis, +EC_GROUP_get_pentanomial_basis +- Functions for manipulating EC_GROUP objects =head1 SYNOPSIS #include <openssl/ec.h> - #include <openssl/bn.h> int EC_GROUP_copy(EC_GROUP *dst, const EC_GROUP *src); EC_GROUP *EC_GROUP_dup(const EC_GROUP *src); @@ -18,7 +27,10 @@ EC_GROUP_copy, EC_GROUP_dup, EC_GROUP_method_of, EC_GROUP_set_generator, EC_GROU const EC_POINT *EC_GROUP_get0_generator(const EC_GROUP *group); int EC_GROUP_get_order(const EC_GROUP *group, BIGNUM *order, BN_CTX *ctx); + const BIGNUM *EC_GROUP_get0_order(const EC_GROUP *group); + int EC_GROUP_order_bits(const EC_GROUP *group); int EC_GROUP_get_cofactor(const EC_GROUP *group, BIGNUM *cofactor, BN_CTX *ctx); + const BIGNUM *EC_GROUP_get0_cofactor(const EC_GROUP *group); void EC_GROUP_set_curve_name(EC_GROUP *group, int nid); int EC_GROUP_get_curve_name(const EC_GROUP *group); @@ -43,8 +55,8 @@ EC_GROUP_copy, EC_GROUP_dup, EC_GROUP_method_of, EC_GROUP_set_generator, EC_GROU int EC_GROUP_get_basis_type(const EC_GROUP *); int EC_GROUP_get_trinomial_basis(const EC_GROUP *, unsigned int *k); - int EC_GROUP_get_pentanomial_basis(const EC_GROUP *, unsigned int *k1, - unsigned int *k2, unsigned int *k3); + int EC_GROUP_get_pentanomial_basis(const EC_GROUP *, unsigned int *k1, + unsigned int *k2, unsigned int *k3); =head1 DESCRIPTION @@ -55,10 +67,10 @@ EC_GROUP object. EC_GROUP_method_of obtains the EC_METHOD of B<group>. -EC_GROUP_set_generator sets curve paramaters that must be agreed by all participants using the curve. These -paramaters include the B<generator>, the B<order> and the B<cofactor>. The B<generator> is a well defined point on the +EC_GROUP_set_generator sets curve parameters that must be agreed by all participants using the curve. These +parameters include the B<generator>, the B<order> and the B<cofactor>. The B<generator> is a well defined point on the curve chosen for cryptographic operations. Integers used for point multiplications will be between 0 and -n-1 where n is the B<order>. The B<order> multipied by the B<cofactor> gives the number of points on the curve. +n-1 where n is the B<order>. The B<order> multiplied by the B<cofactor> gives the number of points on the curve. EC_GROUP_get0_generator returns the generator for the identified B<group>. @@ -66,35 +78,42 @@ The functions EC_GROUP_get_order and EC_GROUP_get_cofactor populate the provided with the respective order and cofactors for the B<group>. The functions EC_GROUP_set_curve_name and EC_GROUP_get_curve_name, set and get the NID for the curve respectively -(see L<EC_GROUP_new(3)|EC_GROUP_new(3)>). If a curve does not have a NID associated with it, then EC_GROUP_get_curve_name +(see L<EC_GROUP_new(3)>). If a curve does not have a NID associated with it, then EC_GROUP_get_curve_name will return 0. -The asn1_flag value on a curve is used to determine whether there is a specific ASN1 OID to describe the curve or not. -If the asn1_flag is 1 then this is a named curve with an associated ASN1 OID. If not then asn1_flag is 0. The functions -EC_GROUP_get_asn1_flag and EC_GROUP_set_asn1_flag get and set the status of the asn1_flag for the curve. If set then -the curve_name must also be set. - -The point_coversion_form for a curve controls how EC_POINT data is encoded as ASN1 as defined in X9.62 (ECDSA). -point_conversion_form_t is an enum defined as follows: +The asn1_flag value is used to determine whether the curve encoding uses +explicit parameters or a named curve using an ASN1 OID: many applications only +support the latter form. If asn1_flag is B<OPENSSL_EC_NAMED_CURVE> then the +named curve form is used and the parameters must have a corresponding +named curve NID set. If asn1_flags is B<OPENSSL_EC_EXPLICIT_CURVE> the +parameters are explicitly encoded. The functions EC_GROUP_get_asn1_flag and +EC_GROUP_set_asn1_flag get and set the status of the asn1_flag for the curve. +Note: B<OPENSSL_EC_EXPLICIT_CURVE> was first added to OpenSSL 1.1.0, for +previous versions of OpenSSL the value 0 must be used instead. Before OpenSSL +1.1.0 the default form was to use explicit parameters (meaning that +applications would have to explicitly set the named curve form) in OpenSSL +1.1.0 and later the named curve form is the default. + +The point_conversion_form for a curve controls how EC_POINT data is encoded as ASN1 as defined in X9.62 (ECDSA). +point_conversion_form_t is an enum defined as follows: typedef enum { - /** the point is encoded as z||x, where the octet z specifies - * which solution of the quadratic equation y is */ - POINT_CONVERSION_COMPRESSED = 2, - /** the point is encoded as z||x||y, where z is the octet 0x02 */ - POINT_CONVERSION_UNCOMPRESSED = 4, - /** the point is encoded as z||x||y, where the octet z specifies + /** the point is encoded as z||x, where the octet z specifies + * which solution of the quadratic equation y is */ + POINT_CONVERSION_COMPRESSED = 2, + /** the point is encoded as z||x||y, where z is the octet 0x04 */ + POINT_CONVERSION_UNCOMPRESSED = 4, + /** the point is encoded as z||x||y, where the octet z specifies * which solution of the quadratic equation y is */ - POINT_CONVERSION_HYBRID = 6 + POINT_CONVERSION_HYBRID = 6 } point_conversion_form_t; - For POINT_CONVERSION_UNCOMPRESSED the point is encoded as an octet signifying the UNCOMPRESSED form has been used followed by the octets for x, followed by the octets for y. For any given x co-ordinate for a point on a curve it is possible to derive two possible y values. For POINT_CONVERSION_COMPRESSED the point is encoded as an octet signifying that the COMPRESSED form has been used AND which of -the two possible solutions for y has been used, followed by the octets for x. +the two possible solutions for y has been used, followed by the octets for x. For POINT_CONVERSION_HYBRID the point is encoded as an octet signifying the HYBRID form has been used AND which of the two possible solutions for y has been used, followed by the octets for x, followed by the octets for y. @@ -135,7 +154,7 @@ or a pentanomial of the form: f(x) = x^m + x^k3 + x^k2 + x^k1 + 1 with m > k3 > k2 > k1 >= 1 The function EC_GROUP_get_basis_type returns a NID identifying whether a trinomial or pentanomial is in use for the field. The -function EC_GROUP_get_trinomial_basis must only be called where f(x) is of the trinomial form, and returns the value of B<k>. Similary +function EC_GROUP_get_trinomial_basis must only be called where f(x) is of the trinomial form, and returns the value of B<k>. Similarly the function EC_GROUP_get_pentanomial_basis must only be called where f(x) is of the pentanomial form, and returns the values of B<k1>, B<k2> and B<k3> respectively. @@ -154,6 +173,10 @@ EC_GROUP_get_order, EC_GROUP_get_cofactor, EC_GROUP_get_curve_name, EC_GROUP_get and EC_GROUP_get_degree return the order, cofactor, curve name (NID), ASN1 flag, point_conversion_form and degree for the specified curve respectively. If there is no curve name associated with a curve then EC_GROUP_get_curve_name will return 0. +EC_GROUP_get0_order() returns an internal pointer to the group order. +EC_GROUP_get_order_bits() returns the number of bits in the group order. +EC_GROUP_get0_cofactor() returns an internal pointer to the group cofactor. + EC_GROUP_get0_seed returns a pointer to the seed that was used to generate the parameter b, or NULL if the seed is not specified. EC_GROUP_get_seed_len returns the length of the seed or 0 if the seed is not specified. @@ -167,8 +190,17 @@ trinomial or pentanomial respectively. Alternatively in the event of an error a =head1 SEE ALSO -L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, -L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>, -L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)> +L<crypto(7)>, L<EC_GROUP_new(3)>, +L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_KEY_new(3)>, +L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)> + +=head1 COPYRIGHT + +Copyright 2013-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EC_GROUP_new.pod b/deps/openssl/openssl/doc/crypto/EC_GROUP_new.pod index ff55bf33a3..2f658dc2c3 100644 --- a/deps/openssl/openssl/doc/crypto/EC_GROUP_new.pod +++ b/deps/openssl/openssl/doc/crypto/EC_GROUP_new.pod @@ -2,14 +2,22 @@ =head1 NAME -EC_GROUP_new, EC_GROUP_free, EC_GROUP_clear_free, EC_GROUP_new_curve_GFp, EC_GROUP_new_curve_GF2m, EC_GROUP_new_by_curve_name, EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m, EC_get_builtin_curves - Functions for creating and destroying B<EC_GROUP> objects. +EC_GROUP_get_ecparameters, EC_GROUP_get_ecpkparameters, +EC_GROUP_new, EC_GROUP_new_from_ecparameters, +EC_GROUP_new_from_ecpkparameters, +EC_GROUP_free, EC_GROUP_clear_free, EC_GROUP_new_curve_GFp, +EC_GROUP_new_curve_GF2m, EC_GROUP_new_by_curve_name, EC_GROUP_set_curve_GFp, +EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROUP_get_curve_GF2m, +EC_get_builtin_curves - Functions for creating and destroying EC_GROUP +objects =head1 SYNOPSIS #include <openssl/ec.h> - #include <openssl/bn.h> EC_GROUP *EC_GROUP_new(const EC_METHOD *meth); + EC_GROUP *EC_GROUP_new_from_ecparameters(const ECPARAMETERS *params) + EC_GROUP *EC_GROUP_new_from_ecpkparameters(const ECPKPARAMETERS *params) void EC_GROUP_free(EC_GROUP *group); void EC_GROUP_clear_free(EC_GROUP *group); @@ -22,6 +30,9 @@ EC_GROUP_new, EC_GROUP_free, EC_GROUP_clear_free, EC_GROUP_new_curve_GFp, EC_GRO int EC_GROUP_set_curve_GF2m(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); int EC_GROUP_get_curve_GF2m(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); + ECPARAMETERS *EC_GROUP_get_ecparameters(const EC_GROUP *group, ECPARAMETERS *params) + ECPKPARAMETERS *EC_GROUP_get_ecpkparameters(const EC_GROUP *group, ECPKPARAMETERS *params) + size_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems); =head1 DESCRIPTION @@ -41,15 +52,18 @@ Operations in a binary field are performed relative to an B<irreducible polynomi use a trinomial or a pentanomial for this parameter. A new curve can be constructed by calling EC_GROUP_new, using the implementation provided by B<meth> (see -L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>). It is then necessary to call either EC_GROUP_set_curve_GFp or -EC_GROUP_set_curve_GF2m as appropriate to create a curve defined over Fp or over F2^m respectively. +L<EC_GFp_simple_method(3)>). It is then necessary to call either EC_GROUP_set_curve_GFp or +EC_GROUP_set_curve_GF2m as appropriate to create a curve defined over Fp or over F2^m respectively. +EC_GROUP_new_from_ecparameters() will create a group from the +specified B<params> and +EC_GROUP_new_from_ecpkparameters() will create a group from the specific PK B<params>. EC_GROUP_set_curve_GFp sets the curve parameters B<p>, B<a> and B<b> for a curve over Fp stored in B<group>. EC_group_get_curve_GFp obtains the previously set curve parameters. EC_GROUP_set_curve_GF2m sets the equivalent curve parameters for a curve over F2^m. In this case B<p> represents -the irreducible polybnomial - each bit represents a term in the polynomial. Therefore there will either be three -or five bits set dependant on whether the polynomial is a trinomial or a pentanomial. +the irreducible polynomial - each bit represents a term in the polynomial. Therefore there will either be three +or five bits set dependent on whether the polynomial is a trinomial or a pentanomial. EC_group_get_curve_GF2m obtains the previously set curve parameters. The functions EC_GROUP_new_curve_GFp and EC_GROUP_new_curve_GF2m are shortcuts for calling EC_GROUP_new and the @@ -64,10 +78,10 @@ provided. The return value is the total number of curves available (whether that not). Passing a NULL B<r>, or setting B<nitems> to 0 will do nothing other than return the total number of curves available. The EC_builtin_curve structure is defined as follows: - typedef struct { - int nid; - const char *comment; - } EC_builtin_curve; + typedef struct { + int nid; + const char *comment; + } EC_builtin_curve; Each EC_builtin_curve item has a unique integer id (B<nid>), and a human readable comment string describing the curve. @@ -75,8 +89,10 @@ In order to construct a builtin curve use the function EC_GROUP_new_by_curve_nam be constructed. EC_GROUP_free frees the memory associated with the EC_GROUP. +If B<group> is NULL nothing is done. EC_GROUP_clear_free destroys any sensitive data held within the EC_GROUP and then frees its memory. +If B<group> is NULL nothing is done. =head1 RETURN VALUES @@ -88,8 +104,17 @@ EC_GROUP_set_curve_GFp, EC_GROUP_get_curve_GFp, EC_GROUP_set_curve_GF2m, EC_GROU =head1 SEE ALSO -L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, -L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>, -L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)> +L<crypto(7)>, L<EC_GROUP_copy(3)>, +L<EC_POINT_new(3)>, L<EC_POINT_add(3)>, L<EC_KEY_new(3)>, +L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)> + +=head1 COPYRIGHT + +Copyright 2013-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EC_KEY_get_enc_flags.pod b/deps/openssl/openssl/doc/crypto/EC_KEY_get_enc_flags.pod new file mode 100644 index 0000000000..4f73a1d59d --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/EC_KEY_get_enc_flags.pod @@ -0,0 +1,59 @@ +=pod + +=head1 NAME + +EC_KEY_get_enc_flags, EC_KEY_set_enc_flags +- Get and set flags for encoding EC_KEY structures + +=head1 SYNOPSIS + + #include <openssl/ec.h> + + unsigned int EC_KEY_get_enc_flags(const EC_KEY *key); + void EC_KEY_set_enc_flags(EC_KEY *eckey, unsigned int flags); + +=head1 DESCRIPTION + +The format of the external representation of the public key written by +i2d_ECPrivateKey() (such as whether it is stored in a compressed form or not) is +described by the point_conversion_form. See L<EC_GROUP_copy(3)> +for a description of point_conversion_form. + +When reading a private key encoded without an associated public key (e.g. if +EC_PKEY_NO_PUBKEY has been used - see below), then d2i_ECPrivateKey() generates +the missing public key automatically. Private keys encoded without parameters +(e.g. if EC_PKEY_NO_PARAMETERS has been used - see below) cannot be loaded using +d2i_ECPrivateKey(). + +The functions EC_KEY_get_enc_flags() and EC_KEY_set_enc_flags() get and set the +value of the encoding flags for the B<key>. There are two encoding flags +currently defined - EC_PKEY_NO_PARAMETERS and EC_PKEY_NO_PUBKEY. These flags +define the behaviour of how the B<key> is converted into ASN1 in a call to +i2d_ECPrivateKey(). If EC_PKEY_NO_PARAMETERS is set then the public parameters for +the curve are not encoded along with the private key. If EC_PKEY_NO_PUBKEY is +set then the public key is not encoded along with the private key. + +=head1 RETURN VALUES + +EC_KEY_get_enc_flags() returns the value of the current encoding flags for the +EC_KEY. + +=head1 SEE ALSO + +L<crypto(7)>, L<EC_GROUP_new(3)>, +L<EC_GROUP_copy(3)>, L<EC_POINT_new(3)>, +L<EC_POINT_add(3)>, +L<EC_GFp_simple_method(3)>, +L<d2i_ECPKParameters(3)>, +L<d2i_ECPrivateKey(3)> + +=head1 COPYRIGHT + +Copyright 2015-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EC_KEY_new.pod b/deps/openssl/openssl/doc/crypto/EC_KEY_new.pod index 0fa2de1721..591529fd47 100644 --- a/deps/openssl/openssl/doc/crypto/EC_KEY_new.pod +++ b/deps/openssl/openssl/doc/crypto/EC_KEY_new.pod @@ -2,12 +2,21 @@ =head1 NAME -EC_KEY_new, EC_KEY_get_flags, EC_KEY_set_flags, EC_KEY_clear_flags, EC_KEY_new_by_curve_name, EC_KEY_free, EC_KEY_copy, EC_KEY_dup, EC_KEY_up_ref, EC_KEY_get0_group, EC_KEY_set_group, EC_KEY_get0_private_key, EC_KEY_set_private_key, EC_KEY_get0_public_key, EC_KEY_set_public_key, EC_KEY_get_enc_flags, EC_KEY_set_enc_flags, EC_KEY_get_conv_form, EC_KEY_set_conv_form, EC_KEY_get_key_method_data, EC_KEY_insert_key_method_data, EC_KEY_set_asn1_flag, EC_KEY_precompute_mult, EC_KEY_generate_key, EC_KEY_check_key, EC_KEY_set_public_key_affine_coordinates - Functions for creating, destroying and manipulating B<EC_KEY> objects. +EC_KEY_get_method, EC_KEY_set_method, +EC_KEY_new, EC_KEY_get_flags, EC_KEY_set_flags, EC_KEY_clear_flags, +EC_KEY_new_by_curve_name, EC_KEY_free, EC_KEY_copy, EC_KEY_dup, EC_KEY_up_ref, +EC_KEY_get0_group, EC_KEY_set_group, EC_KEY_get0_private_key, +EC_KEY_set_private_key, EC_KEY_get0_public_key, EC_KEY_set_public_key, +EC_KEY_get_conv_form, +EC_KEY_set_conv_form, EC_KEY_set_asn1_flag, EC_KEY_precompute_mult, +EC_KEY_generate_key, EC_KEY_check_key, EC_KEY_set_public_key_affine_coordinates, +EC_KEY_oct2key, EC_KEY_key2buf, EC_KEY_oct2priv, EC_KEY_priv2oct, +EC_KEY_priv2buf - Functions for creating, destroying and manipulating +EC_KEY objects =head1 SYNOPSIS #include <openssl/ec.h> - #include <openssl/bn.h> EC_KEY *EC_KEY_new(void); int EC_KEY_get_flags(const EC_KEY *key); @@ -26,83 +35,149 @@ EC_KEY_new, EC_KEY_get_flags, EC_KEY_set_flags, EC_KEY_clear_flags, EC_KEY_new_b int EC_KEY_set_public_key(EC_KEY *key, const EC_POINT *pub); point_conversion_form_t EC_KEY_get_conv_form(const EC_KEY *key); void EC_KEY_set_conv_form(EC_KEY *eckey, point_conversion_form_t cform); - void *EC_KEY_get_key_method_data(EC_KEY *key, - void *(*dup_func)(void *), void (*free_func)(void *), void (*clear_free_func)(void *)); - void EC_KEY_insert_key_method_data(EC_KEY *key, void *data, - void *(*dup_func)(void *), void (*free_func)(void *), void (*clear_free_func)(void *)); void EC_KEY_set_asn1_flag(EC_KEY *eckey, int asn1_flag); int EC_KEY_precompute_mult(EC_KEY *key, BN_CTX *ctx); int EC_KEY_generate_key(EC_KEY *key); int EC_KEY_check_key(const EC_KEY *key); - int EC_KEY_set_public_key_affine_coordinates(EC_KEY *key, BIGNUM *x, BIGNUM *y); + int EC_KEY_set_public_key_affine_coordinates(EC_KEY *key, + BIGNUM *x, BIGNUM *y); + const EC_KEY_METHOD *EC_KEY_get_method(const EC_KEY *key); + int EC_KEY_set_method(EC_KEY *key, const EC_KEY_METHOD *meth); -=head1 DESCRIPTION - -An EC_KEY represents a public key and (optionaly) an associated private key. A new EC_KEY (with no associated curve) can be constructed by calling EC_KEY_new. -The reference count for the newly created EC_KEY is initially set to 1. A curve can be associated with the EC_KEY by calling -EC_KEY_set_group. - -Alternatively a new EC_KEY can be constructed by calling EC_KEY_new_by_curve_name and supplying the nid of the associated curve. Refer to L<EC_GROUP_new(3)|EC_GROUP_new(3)> for a description of curve names. This function simply wraps calls to EC_KEY_new and -EC_GROUP_new_by_curve_name. - -Calling EC_KEY_free decrements the reference count for the EC_KEY object, and if it has dropped to zero then frees the memory associated -with it. - -EC_KEY_copy copies the contents of the EC_KEY in B<src> into B<dest>. - -EC_KEY_dup creates a new EC_KEY object and copies B<ec_key> into it. - -EC_KEY_up_ref increments the reference count associated with the EC_KEY object. - -EC_KEY_generate_key generates a new public and private key for the supplied B<eckey> object. B<eckey> must have an EC_GROUP object -associated with it before calling this function. The private key is a random integer (0 < priv_key < order, where order is the order -of the EC_GROUP object). The public key is an EC_POINT on the curve calculated by multiplying the generator for the curve by the -private key. + int EC_KEY_oct2key(EC_KEY *eckey, const unsigned char *buf, size_t len, + BN_CTX *ctx); + size_t EC_KEY_key2buf(const EC_KEY *eckey, point_conversion_form_t form, + unsigned char **pbuf, BN_CTX *ctx); -EC_KEY_check_key performs various sanity checks on the EC_KEY object to confirm that it is valid. + int EC_KEY_oct2priv(EC_KEY *eckey, const unsigned char *buf, size_t len); + size_t EC_KEY_priv2oct(const EC_KEY *eckey, unsigned char *buf, size_t len); -EC_KEY_set_public_key_affine_coordinates sets the public key for B<key> based on its affine co-ordinates, i.e. it constructs an EC_POINT -object based on the supplied B<x> and B<y> values and sets the public key to be this EC_POINT. It will also performs certain sanity checks -on the key to confirm that it is valid. + size_t EC_KEY_priv2buf(const EC_KEY *eckey, unsigned char **pbuf); -The functions EC_KEY_get0_group, EC_KEY_set_group, EC_KEY_get0_private_key, EC_KEY_set_private_key, EC_KEY_get0_public_key, and EC_KEY_set_public_key get and set the EC_GROUP object, the private key and the EC_POINT public key for the B<key> respectively. - -The functions EC_KEY_get_conv_form and EC_KEY_set_conv_form get and set the point_conversion_form for the B<key>. For a description -of point_conversion_forms please refer to L<EC_POINT_new(3)|EC_POINT_new(3)>. +=head1 DESCRIPTION -EC_KEY_insert_key_method_data and EC_KEY_get_key_method_data enable the caller to associate arbitrary additional data specific to the -elliptic curve scheme being used with the EC_KEY object. This data is treated as a "black box" by the ec library. The data to be stored by EC_KEY_insert_key_method_data is provided in the B<data> parameter, which must have associated functions for duplicating, freeing and "clear_freeing" the data item. If a subsequent EC_KEY_get_key_method_data call is issued, the functions for duplicating, freeing and "clear_freeing" the data item must be provided again, and they must be the same as they were when the data item was inserted. +An EC_KEY represents a public key and, optionally, the associated private +key. A new EC_KEY with no associated curve can be constructed by calling +EC_KEY_new(). The reference count for the newly created EC_KEY is initially +set to 1. A curve can be associated with the EC_KEY by calling +EC_KEY_set_group(). + +Alternatively a new EC_KEY can be constructed by calling +EC_KEY_new_by_curve_name() and supplying the nid of the associated curve. See +L<EC_GROUP_new(3)> for a description of curve names. This function simply +wraps calls to EC_KEY_new() and EC_GROUP_new_by_curve_name(). + +Calling EC_KEY_free() decrements the reference count for the EC_KEY object, +and if it has dropped to zero then frees the memory associated with it. If +B<key> is NULL nothing is done. + +EC_KEY_copy() copies the contents of the EC_KEY in B<src> into B<dest>. + +EC_KEY_dup() creates a new EC_KEY object and copies B<ec_key> into it. + +EC_KEY_up_ref() increments the reference count associated with the EC_KEY +object. + +EC_KEY_generate_key() generates a new public and private key for the supplied +B<eckey> object. B<eckey> must have an EC_GROUP object associated with it +before calling this function. The private key is a random integer (0 < priv_key +< order, where I<order> is the order of the EC_GROUP object). The public key is +an EC_POINT on the curve calculated by multiplying the generator for the +curve by the private key. + +EC_KEY_check_key() performs various sanity checks on the EC_KEY object to +confirm that it is valid. + +EC_KEY_set_public_key_affine_coordinates() sets the public key for B<key> based +on its affine co-ordinates; i.e., it constructs an EC_POINT object based on +the supplied B<x> and B<y> values and sets the public key to be this +EC_POINT. It also performs certain sanity checks on the key to confirm +that it is valid. + +The functions EC_KEY_get0_group(), EC_KEY_set_group(), +EC_KEY_get0_private_key(), EC_KEY_set_private_key(), EC_KEY_get0_public_key(), +and EC_KEY_set_public_key() get and set the EC_GROUP object, the private key, +and the EC_POINT public key for the B<key> respectively. + +The functions EC_KEY_get_conv_form() and EC_KEY_set_conv_form() get and set the +point_conversion_form for the B<key>. For a description of +point_conversion_forms please see L<EC_POINT_new(3)>. + +EC_KEY_set_flags() sets the flags in the B<flags> parameter on the EC_KEY +object. Any flags that are already set are left set. The flags currently +defined are EC_FLAG_NON_FIPS_ALLOW and EC_FLAG_FIPS_CHECKED. In +addition there is the flag EC_FLAG_COFACTOR_ECDH which is specific to ECDH. +EC_KEY_get_flags() returns the current flags that are set for this EC_KEY. +EC_KEY_clear_flags() clears the flags indicated by the B<flags> parameter; all +other flags are left in their existing state. + +EC_KEY_set_asn1_flag() sets the asn1_flag on the underlying EC_GROUP object +(if set). Refer to L<EC_GROUP_copy(3)> for further information on the +asn1_flag. + +EC_KEY_precompute_mult() stores multiples of the underlying EC_GROUP generator +for faster point multiplication. See also L<EC_POINT_add(3)>. + +EC_KEY_oct2key() and EC_KEY_key2buf() are identical to the functions +EC_POINT_oct2point() and EC_KEY_point2buf() except they use the public key +EC_POINT in B<eckey>. + +EC_KEY_oct2priv() and EC_KEY_priv2oct() convert between the private key +component of B<eckey> and octet form. The octet form consists of the content +octets of the B<privateKey> OCTET STRING in an B<ECPrivateKey> ASN.1 structure. + +The function EC_KEY_priv2oct() must be supplied with a buffer long enough to +store the octet form. The return value provides the number of octets stored. +Calling the function with a NULL buffer will not perform the conversion but +will just return the required buffer length. + +The function EC_KEY_priv2buf() allocates a buffer of suitable length and writes +an EC_KEY to it in octet format. The allocated buffer is written to B<*pbuf> +and its length is returned. The caller must free up the allocated buffer with a +call to OPENSSL_free(). Since the allocated buffer value is written to B<*pbuf> +the B<pbuf> parameter B<MUST NOT> be B<NULL>. + +EC_KEY_priv2buf() converts an EC_KEY private key into an allocated buffer. -EC_KEY_set_flags sets the flags in the B<flags> parameter on the EC_KEY object. Any flags that are already set are left set. The currently defined standard flags are EC_FLAG_NON_FIPS_ALLOW and EC_FLAG_FIPS_CHECKED. In addition there is the flag EC_FLAG_COFACTOR_ECDH which is specific to ECDH and is defined in ecdh.h. EC_KEY_get_flags returns the current flags that are set for this EC_KEY. EC_KEY_clear_flags clears the flags indicated by the B<flags> parameter. All other flags are left in their existing state. +=head1 RETURN VALUES -EC_KEY_set_asn1_flag sets the asn1_flag on the underlying EC_GROUP object (if set). Refer to L<EC_GROUP_copy(3)|EC_GROUP_copy(3)> for further information on the asn1_flag. +EC_KEY_new(), EC_KEY_new_by_curve_name() and EC_KEY_dup() return a pointer to +the newly created EC_KEY object, or NULL on error. -EC_KEY_precompute_mult stores multiples of the underlying EC_GROUP generator for faster point multiplication. See also L<EC_POINT_add(3)|EC_POINT_add(3)>. +EC_KEY_get_flags() returns the flags associated with the EC_KEY object as an +integer. +EC_KEY_copy() returns a pointer to the destination key, or NULL on error. -=head1 RETURN VALUES +EC_KEY_up_ref(), EC_KEY_set_group(), EC_KEY_set_private_key(), +EC_KEY_set_public_key(), EC_KEY_precompute_mult(), EC_KEY_generate_key(), +EC_KEY_check_key(), EC_KEY_set_public_key_affine_coordinates(), +EC_KEY_oct2key() and EC_KEY_oct2priv() return 1 on success or 0 on error. -EC_KEY_new, EC_KEY_new_by_curve_name and EC_KEY_dup return a pointer to the newly created EC_KEY object, or NULL on error. +EC_KEY_get0_group() returns the EC_GROUP associated with the EC_KEY. -EC_KEY_get_flags returns the flags associated with the EC_KEY object as an integer. +EC_KEY_get0_private_key() returns the private key associated with the EC_KEY. -EC_KEY_copy returns a pointer to the destination key, or NULL on error. +EC_KEY_get_conv_form() return the point_conversion_form for the EC_KEY. -EC_KEY_up_ref, EC_KEY_set_group, EC_KEY_set_private_key, EC_KEY_set_public_key, EC_KEY_precompute_mult, EC_KEY_generate_key, EC_KEY_check_key and EC_KEY_set_public_key_affine_coordinates return 1 on success or 0 on error. +EC_KEY_key2buf(), EC_KEY_priv2oct() and EC_KEY_priv2buf() return the length +of the buffer or 0 on error. -EC_KEY_get0_group returns the EC_GROUP associated with the EC_KEY. - -EC_KEY_get0_private_key returns the private key associated with the EC_KEY. +=head1 SEE ALSO -EC_KEY_get_conv_form return the point_conversion_form for the EC_KEY. +L<crypto(7)>, L<EC_GROUP_new(3)>, +L<EC_GROUP_copy(3)>, L<EC_POINT_new(3)>, +L<EC_POINT_add(3)>, +L<EC_GFp_simple_method(3)>, +L<d2i_ECPKParameters(3)> +=head1 COPYRIGHT -=head1 SEE ALSO +Copyright 2013-2017 The OpenSSL Project Authors. All Rights Reserved. -L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, -L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, L<EC_POINT_new(3)|EC_POINT_new(3)>, -L<EC_POINT_add(3)|EC_POINT_add(3)>, -L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, -L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)> +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EC_POINT_add.pod b/deps/openssl/openssl/doc/crypto/EC_POINT_add.pod index ae92640843..6f3e2308bd 100644 --- a/deps/openssl/openssl/doc/crypto/EC_POINT_add.pod +++ b/deps/openssl/openssl/doc/crypto/EC_POINT_add.pod @@ -2,12 +2,11 @@ =head1 NAME -EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_is_at_infinity, EC_POINT_is_on_curve, EC_POINT_cmp, EC_POINT_make_affine, EC_POINTs_make_affine, EC_POINTs_mul, EC_POINT_mul, EC_GROUP_precompute_mult, EC_GROUP_have_precompute_mult - Functions for performing mathematical operations and tests on B<EC_POINT> objects. +EC_POINT_add, EC_POINT_dbl, EC_POINT_invert, EC_POINT_is_at_infinity, EC_POINT_is_on_curve, EC_POINT_cmp, EC_POINT_make_affine, EC_POINTs_make_affine, EC_POINTs_mul, EC_POINT_mul, EC_GROUP_precompute_mult, EC_GROUP_have_precompute_mult - Functions for performing mathematical operations and tests on EC_POINT objects =head1 SYNOPSIS #include <openssl/ec.h> - #include <openssl/bn.h> int EC_POINT_add(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx); int EC_POINT_dbl(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, BN_CTX *ctx); @@ -46,7 +45,7 @@ EC_POINTs_mul calculates the value generator * B<n> + B<q[0]> * B<m[0]> + ... + B<n> may be NULL. The function EC_GROUP_precompute_mult stores multiples of the generator for faster point multiplication, whilst -EC_GROUP_have_precompute_mult tests whether precomputation has already been done. See L<EC_GROUP_copy(3)|EC_GROUP_copy(3)> for information +EC_GROUP_have_precompute_mult tests whether precomputation has already been done. See L<EC_GROUP_copy(3)> for information about the generator. @@ -65,8 +64,17 @@ EC_GROUP_have_precompute_mult return 1 if a precomputation has been done, or 0 i =head1 SEE ALSO -L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, -L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>, -L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)> +L<crypto(7)>, L<EC_GROUP_new(3)>, L<EC_GROUP_copy(3)>, +L<EC_POINT_new(3)>, L<EC_KEY_new(3)>, +L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)> + +=head1 COPYRIGHT + +Copyright 2013-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EC_POINT_new.pod b/deps/openssl/openssl/doc/crypto/EC_POINT_new.pod index 858baf4244..5ac41b3295 100644 --- a/deps/openssl/openssl/doc/crypto/EC_POINT_new.pod +++ b/deps/openssl/openssl/doc/crypto/EC_POINT_new.pod @@ -2,12 +2,22 @@ =head1 NAME -EC_POINT_new, EC_POINT_free, EC_POINT_clear_free, EC_POINT_copy, EC_POINT_dup, EC_POINT_method_of, EC_POINT_set_to_infinity, EC_POINT_set_Jprojective_coordinates, EC_POINT_get_Jprojective_coordinates_GFp, EC_POINT_set_affine_coordinates_GFp, EC_POINT_get_affine_coordinates_GFp, EC_POINT_set_compressed_coordinates_GFp, EC_POINT_set_affine_coordinates_GF2m, EC_POINT_get_affine_coordinates_GF2m, EC_POINT_set_compressed_coordinates_GF2m, EC_POINT_point2oct, EC_POINT_oct2point, EC_POINT_point2bn, EC_POINT_bn2point, EC_POINT_point2hex, EC_POINT_hex2point - Functions for creating, destroying and manipulating B<EC_POINT> objects. +EC_POINT_set_Jprojective_coordinates_GFp, EC_POINT_point2buf, +EC_POINT_new, EC_POINT_free, EC_POINT_clear_free, +EC_POINT_copy, EC_POINT_dup, EC_POINT_method_of, +EC_POINT_set_to_infinity, +EC_POINT_get_Jprojective_coordinates_GFp, +EC_POINT_set_affine_coordinates_GFp, +EC_POINT_get_affine_coordinates_GFp, EC_POINT_set_compressed_coordinates_GFp, +EC_POINT_set_affine_coordinates_GF2m, EC_POINT_get_affine_coordinates_GF2m, +EC_POINT_set_compressed_coordinates_GF2m, EC_POINT_point2oct, +EC_POINT_oct2point, EC_POINT_point2bn, EC_POINT_bn2point, EC_POINT_point2hex, +EC_POINT_hex2point +- Functions for creating, destroying and manipulating EC_POINT objects =head1 SYNOPSIS #include <openssl/ec.h> - #include <openssl/bn.h> EC_POINT *EC_POINT_new(const EC_GROUP *group); void EC_POINT_free(EC_POINT *point); @@ -16,113 +26,171 @@ EC_POINT_new, EC_POINT_free, EC_POINT_clear_free, EC_POINT_copy, EC_POINT_dup, E EC_POINT *EC_POINT_dup(const EC_POINT *src, const EC_GROUP *group); const EC_METHOD *EC_POINT_method_of(const EC_POINT *point); int EC_POINT_set_to_infinity(const EC_GROUP *group, EC_POINT *point); - int EC_POINT_set_Jprojective_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, - const BIGNUM *x, const BIGNUM *y, const BIGNUM *z, BN_CTX *ctx); + int EC_POINT_set_Jprojective_coordinates_GFp(const EC_GROUP *group, + EC_POINT *p, + const BIGNUM *x, const BIGNUM *y, + const BIGNUM *z, BN_CTX *ctx); int EC_POINT_get_Jprojective_coordinates_GFp(const EC_GROUP *group, - const EC_POINT *p, BIGNUM *x, BIGNUM *y, BIGNUM *z, BN_CTX *ctx); + const EC_POINT *p, + BIGNUM *x, BIGNUM *y, BIGNUM *z, + BN_CTX *ctx); int EC_POINT_set_affine_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, - const BIGNUM *x, const BIGNUM *y, BN_CTX *ctx); + const BIGNUM *x, const BIGNUM *y, + BN_CTX *ctx); int EC_POINT_get_affine_coordinates_GFp(const EC_GROUP *group, - const EC_POINT *p, BIGNUM *x, BIGNUM *y, BN_CTX *ctx); - int EC_POINT_set_compressed_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, - const BIGNUM *x, int y_bit, BN_CTX *ctx); + const EC_POINT *p, + BIGNUM *x, BIGNUM *y, BN_CTX *ctx); + int EC_POINT_set_compressed_coordinates_GFp(const EC_GROUP *group, + EC_POINT *p, + const BIGNUM *x, int y_bit, + BN_CTX *ctx); int EC_POINT_set_affine_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p, - const BIGNUM *x, const BIGNUM *y, BN_CTX *ctx); + const BIGNUM *x, const BIGNUM *y, + BN_CTX *ctx); int EC_POINT_get_affine_coordinates_GF2m(const EC_GROUP *group, - const EC_POINT *p, BIGNUM *x, BIGNUM *y, BN_CTX *ctx); - int EC_POINT_set_compressed_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p, - const BIGNUM *x, int y_bit, BN_CTX *ctx); + const EC_POINT *p, + BIGNUM *x, BIGNUM *y, BN_CTX *ctx); + int EC_POINT_set_compressed_coordinates_GF2m(const EC_GROUP *group, + EC_POINT *p, + const BIGNUM *x, int y_bit, + BN_CTX *ctx); size_t EC_POINT_point2oct(const EC_GROUP *group, const EC_POINT *p, - point_conversion_form_t form, - unsigned char *buf, size_t len, BN_CTX *ctx); + point_conversion_form_t form, + unsigned char *buf, size_t len, BN_CTX *ctx); + size_t EC_POINT_point2buf(const EC_GROUP *group, const EC_POINT *point, + point_conversion_form_t form, + unsigned char **pbuf, BN_CTX *ctx); int EC_POINT_oct2point(const EC_GROUP *group, EC_POINT *p, - const unsigned char *buf, size_t len, BN_CTX *ctx); - BIGNUM *EC_POINT_point2bn(const EC_GROUP *, const EC_POINT *, - point_conversion_form_t form, BIGNUM *, BN_CTX *); - EC_POINT *EC_POINT_bn2point(const EC_GROUP *, const BIGNUM *, - EC_POINT *, BN_CTX *); - char *EC_POINT_point2hex(const EC_GROUP *, const EC_POINT *, - point_conversion_form_t form, BN_CTX *); - EC_POINT *EC_POINT_hex2point(const EC_GROUP *, const char *, - EC_POINT *, BN_CTX *); + const unsigned char *buf, size_t len, BN_CTX *ctx); + BIGNUM *EC_POINT_point2bn(const EC_GROUP *group, const EC_POINT *p, + point_conversion_form_t form, BIGNUM *bn, + BN_CTX *ctx); + EC_POINT *EC_POINT_bn2point(const EC_GROUP *group, const BIGNUM *bn, + EC_POINT *p, BN_CTX *ctx); + char *EC_POINT_point2hex(const EC_GROUP *group, const EC_POINT *p, + point_conversion_form_t form, BN_CTX *ctx); + EC_POINT *EC_POINT_hex2point(const EC_GROUP *group, const char *hex, + EC_POINT *p, BN_CTX *ctx); =head1 DESCRIPTION -An EC_POINT represents a point on a curve. A new point is constructed by calling the function EC_POINT_new and providing the B<group> -object that the point relates to. - -EC_POINT_free frees the memory associated with the EC_POINT. - -EC_POINT_clear_free destroys any sensitive data held within the EC_POINT and then frees its memory. - -EC_POINT_copy copies the point B<src> into B<dst>. Both B<src> and B<dst> must use the same EC_METHOD. - -EC_POINT_dup creates a new EC_POINT object and copies the content from B<src> to the newly created -EC_POINT object. - -EC_POINT_method_of obtains the EC_METHOD associated with B<point>. - -A valid point on a curve is the special point at infinity. A point is set to be at infinity by calling EC_POINT_set_to_infinity. - -The affine co-ordinates for a point describe a point in terms of its x and y position. The functions -EC_POINT_set_affine_coordinates_GFp and EC_POINT_set_affine_coordinates_GF2m set the B<x> and B<y> co-ordinates for the point -B<p> defined over the curve given in B<group>. - -As well as the affine co-ordinates, a point can alternatively be described in terms of its Jacobian -projective co-ordinates (for Fp curves only). Jacobian projective co-ordinates are expressed as three values x, y and z. Working in -this co-ordinate system provides more efficient point multiplication operations. -A mapping exists between Jacobian projective co-ordinates and affine co-ordinates. A Jacobian projective co-ordinate (x, y, z) can be written as an affine co-ordinate as (x/(z^2), y/(z^3)). Conversion to Jacobian projective to affine co-ordinates is simple. The co-ordinate (x, y) is -mapped to (x, y, 1). To set or get the projective co-ordinates use EC_POINT_set_Jprojective_coordinates_GFp and -EC_POINT_get_Jprojective_coordinates_GFp respectively. - -Points can also be described in terms of their compressed co-ordinates. For a point (x, y), for any given value for x such that the point is -on the curve there will only ever be two possible values for y. Therefore a point can be set using the EC_POINT_set_compressed_coordinates_GFp -and EC_POINT_set_compressed_coordinates_GF2m functions where B<x> is the x co-ordinate and B<y_bit> is a value 0 or 1 to identify which of -the two possible values for y should be used. - -In addition EC_POINTs can be converted to and from various external -representations. Supported representations are octet strings, BIGNUMs and -hexadecimal. Octet strings are stored in a buffer along with an associated -buffer length. A point held in a BIGNUM is calculated by converting the point to -an octet string and then converting that octet string into a BIGNUM integer. -Points in hexadecimal format are stored in a NULL terminated character string -where each character is one of the printable values 0-9 or A-F (or a-f). - -The functions EC_POINT_point2oct, EC_POINT_oct2point, EC_POINT_point2bn, EC_POINT_bn2point, EC_POINT_point2hex and EC_POINT_hex2point convert -from and to EC_POINTs for the formats: octet string, BIGNUM and hexadecimal respectively. - -The function EC_POINT_point2oct must be supplied with a buffer long enough to store the octet string. The return value provides the number of -octets stored. Calling the function with a NULL buffer will not perform the conversion but will still return the required buffer length. - -The function EC_POINT_point2hex will allocate sufficient memory to store the hexadecimal string. It is the caller's responsibility to free -this memory with a subsequent call to OPENSSL_free(). +An B<EC_POINT> structure represents a point on a curve. A new point is +constructed by calling the function EC_POINT_new() and providing the +B<group> object that the point relates to. + +EC_POINT_free() frees the memory associated with the B<EC_POINT>. +if B<point> is NULL nothing is done. + +EC_POINT_clear_free() destroys any sensitive data held within the EC_POINT and +then frees its memory. If B<point> is NULL nothing is done. + +EC_POINT_copy() copies the point B<src> into B<dst>. Both B<src> and B<dst> +must use the same B<EC_METHOD>. + +EC_POINT_dup() creates a new B<EC_POINT> object and copies the content from +B<src> to the newly created B<EC_POINT> object. + +EC_POINT_method_of() obtains the B<EC_METHOD> associated with B<point>. + +A valid point on a curve is the special point at infinity. A point is set to +be at infinity by calling EC_POINT_set_to_infinity(). + +The affine co-ordinates for a point describe a point in terms of its x and y +position. The functions EC_POINT_set_affine_coordinates_GFp() and +EC_POINT_set_affine_coordinates_GF2m() set the B<x> and B<y> co-ordinates for +the point B<p> defined over the curve given in B<group>. + +As well as the affine co-ordinates, a point can alternatively be described in +terms of its Jacobian projective co-ordinates (for Fp curves only). Jacobian +projective co-ordinates are expressed as three values x, y and z. Working in +this co-ordinate system provides more efficient point multiplication +operations. A mapping exists between Jacobian projective co-ordinates and +affine co-ordinates. A Jacobian projective co-ordinate (x, y, z) can be written +as an affine co-ordinate as (x/(z^2), y/(z^3)). Conversion to Jacobian +projective from affine co-ordinates is simple. The co-ordinate (x, y) is mapped +to (x, y, 1). To set or get the projective co-ordinates use +EC_POINT_set_Jprojective_coordinates_GFp() and +EC_POINT_get_Jprojective_coordinates_GFp() respectively. + +Points can also be described in terms of their compressed co-ordinates. For a +point (x, y), for any given value for x such that the point is on the curve +there will only ever be two possible values for y. Therefore a point can be set +using the EC_POINT_set_compressed_coordinates_GFp() and +EC_POINT_set_compressed_coordinates_GF2m() functions where B<x> is the x +co-ordinate and B<y_bit> is a value 0 or 1 to identify which of the two +possible values for y should be used. + +In addition B<EC_POINT> can be converted to and from various external +representations. The octet form is the binary encoding of the B<ECPoint> +structure (as defined in RFC5480 and used in certificates and TLS records): +only the content octets are present, the B<OCTET STRING> tag and length are +not included. B<BIGNUM> form is the octet form interpreted as a big endian +integer converted to a B<BIGNUM> structure. Hexadecimal form is the octet +form converted to a NULL terminated character string where each character +is one of the printable values 0-9 or A-F (or a-f). + +The functions EC_POINT_point2oct(), EC_POINT_oct2point(), EC_POINT_point2bn(), +EC_POINT_bn2point(), EC_POINT_point2hex() and EC_POINT_hex2point() convert from +and to EC_POINTs for the formats: octet, BIGNUM and hexadecimal respectively. + +The function EC_POINT_point2oct() must be supplied with a buffer long enough to +store the octet form. The return value provides the number of octets stored. +Calling the function with a NULL buffer will not perform the conversion but +will still return the required buffer length. + +The function EC_POINT_point2buf() allocates a buffer of suitable length and +writes an EC_POINT to it in octet format. The allocated buffer is written to +B<*pbuf> and its length is returned. The caller must free up the allocated +buffer with a call to OPENSSL_free(). Since the allocated buffer value is +written to B<*pbuf> the B<pbuf> parameter B<MUST NOT> be B<NULL>. + +The function EC_POINT_point2hex() will allocate sufficient memory to store the +hexadecimal string. It is the caller's responsibility to free this memory with +a subsequent call to OPENSSL_free(). =head1 RETURN VALUES -EC_POINT_new and EC_POINT_dup return the newly allocated EC_POINT or NULL on error. +EC_POINT_new() and EC_POINT_dup() return the newly allocated EC_POINT or NULL +on error. -The following functions return 1 on success or 0 on error: EC_POINT_copy, EC_POINT_set_to_infinity, EC_POINT_set_Jprojective_coordinates_GFp, -EC_POINT_get_Jprojective_coordinates_GFp, EC_POINT_set_affine_coordinates_GFp, EC_POINT_get_affine_coordinates_GFp, -EC_POINT_set_compressed_coordinates_GFp, EC_POINT_set_affine_coordinates_GF2m, EC_POINT_get_affine_coordinates_GF2m, -EC_POINT_set_compressed_coordinates_GF2m and EC_POINT_oct2point. +The following functions return 1 on success or 0 on error: EC_POINT_copy(), +EC_POINT_set_to_infinity(), EC_POINT_set_Jprojective_coordinates_GFp(), +EC_POINT_get_Jprojective_coordinates_GFp(), +EC_POINT_set_affine_coordinates_GFp(), EC_POINT_get_affine_coordinates_GFp(), +EC_POINT_set_compressed_coordinates_GFp(), +EC_POINT_set_affine_coordinates_GF2m(), EC_POINT_get_affine_coordinates_GF2m(), +EC_POINT_set_compressed_coordinates_GF2m() and EC_POINT_oct2point(). EC_POINT_method_of returns the EC_METHOD associated with the supplied EC_POINT. -EC_POINT_point2oct returns the length of the required buffer, or 0 on error. +EC_POINT_point2oct() and EC_POINT_point2buf() return the length of the required +buffer or 0 on error. -EC_POINT_point2bn returns the pointer to the BIGNUM supplied, or NULL on error. +EC_POINT_point2bn() returns the pointer to the BIGNUM supplied, or NULL on +error. -EC_POINT_bn2point returns the pointer to the EC_POINT supplied, or NULL on error. +EC_POINT_bn2point() returns the pointer to the EC_POINT supplied, or NULL on +error. -EC_POINT_point2hex returns a pointer to the hex string, or NULL on error. +EC_POINT_point2hex() returns a pointer to the hex string, or NULL on error. -EC_POINT_hex2point returns the pointer to the EC_POINT supplied, or NULL on error. +EC_POINT_hex2point() returns the pointer to the EC_POINT supplied, or NULL on +error. =head1 SEE ALSO -L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, -L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>, -L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)> +L<crypto(7)>, L<EC_GROUP_new(3)>, L<EC_GROUP_copy(3)>, +L<EC_POINT_add(3)>, L<EC_KEY_new(3)>, +L<EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)> + +=head1 COPYRIGHT + +Copyright 2013-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/engine.pod b/deps/openssl/openssl/doc/crypto/ENGINE_add.pod index 48741ee306..d5a7d7242f 100644 --- a/deps/openssl/openssl/doc/crypto/engine.pod +++ b/deps/openssl/openssl/doc/crypto/ENGINE_add.pod @@ -2,7 +2,45 @@ =head1 NAME -engine - ENGINE cryptographic module support +ENGINE_get_DH, ENGINE_get_DSA, ENGINE_get_ECDH, ENGINE_get_ECDSA, +ENGINE_by_id, ENGINE_get_cipher_engine, ENGINE_get_default_DH, +ENGINE_get_default_DSA, ENGINE_get_default_ECDH, +ENGINE_get_default_ECDSA, ENGINE_get_default_RAND, +ENGINE_get_default_RSA, ENGINE_get_digest_engine, ENGINE_get_first, +ENGINE_get_last, ENGINE_get_next, ENGINE_get_prev, ENGINE_new, +ENGINE_get_ciphers, ENGINE_get_ctrl_function, ENGINE_get_digests, +ENGINE_get_destroy_function, ENGINE_get_finish_function, +ENGINE_get_init_function, ENGINE_get_load_privkey_function, +ENGINE_get_load_pubkey_function, ENGINE_load_private_key, +ENGINE_load_public_key, ENGINE_get_RAND, ENGINE_get_RSA, ENGINE_get_id, +ENGINE_get_name, ENGINE_get_cmd_defns, ENGINE_get_cipher, +ENGINE_get_digest, ENGINE_add, ENGINE_cmd_is_executable, +ENGINE_ctrl, ENGINE_ctrl_cmd, ENGINE_ctrl_cmd_string, +ENGINE_finish, ENGINE_free, ENGINE_get_flags, ENGINE_init, +ENGINE_register_DH, ENGINE_register_DSA, ENGINE_register_ECDH, +ENGINE_register_ECDSA, ENGINE_register_RAND, ENGINE_register_RSA, +ENGINE_register_all_complete, ENGINE_register_ciphers, +ENGINE_register_complete, ENGINE_register_digests, ENGINE_remove, +ENGINE_set_DH, ENGINE_set_DSA, ENGINE_set_ECDH, ENGINE_set_ECDSA, +ENGINE_set_RAND, ENGINE_set_RSA, ENGINE_set_ciphers, +ENGINE_set_cmd_defns, ENGINE_set_ctrl_function, ENGINE_set_default, +ENGINE_set_default_DH, ENGINE_set_default_DSA, ENGINE_set_default_ECDH, +ENGINE_set_default_ECDSA, ENGINE_set_default_RAND, ENGINE_set_default_RSA, +ENGINE_set_default_ciphers, ENGINE_set_default_digests, +ENGINE_set_default_string, ENGINE_set_destroy_function, +ENGINE_set_digests, ENGINE_set_finish_function, ENGINE_set_flags, +ENGINE_set_id, ENGINE_set_init_function, ENGINE_set_load_privkey_function, +ENGINE_set_load_pubkey_function, ENGINE_set_name, ENGINE_up_ref, +ENGINE_get_table_flags, ENGINE_cleanup, +ENGINE_load_builtin_engines, ENGINE_register_all_DH, +ENGINE_register_all_DSA, ENGINE_register_all_ECDH, +ENGINE_register_all_ECDSA, ENGINE_register_all_RAND, +ENGINE_register_all_RSA, ENGINE_register_all_ciphers, +ENGINE_register_all_digests, ENGINE_set_table_flags, ENGINE_unregister_DH, +ENGINE_unregister_DSA, ENGINE_unregister_ECDH, ENGINE_unregister_ECDSA, +ENGINE_unregister_RAND, ENGINE_unregister_RSA, ENGINE_unregister_ciphers, +ENGINE_unregister_digests +- ENGINE cryptographic module support =head1 SYNOPSIS @@ -21,24 +59,8 @@ engine - ENGINE cryptographic module support int ENGINE_init(ENGINE *e); int ENGINE_finish(ENGINE *e); - void ENGINE_load_openssl(void); - void ENGINE_load_dynamic(void); - #ifndef OPENSSL_NO_STATIC_ENGINE - void ENGINE_load_4758cca(void); - void ENGINE_load_aep(void); - void ENGINE_load_atalla(void); - void ENGINE_load_chil(void); - void ENGINE_load_cswift(void); - void ENGINE_load_gmp(void); - void ENGINE_load_nuron(void); - void ENGINE_load_sureware(void); - void ENGINE_load_ubsec(void); - #endif - void ENGINE_load_cryptodev(void); void ENGINE_load_builtin_engines(void); - void ENGINE_cleanup(void); - ENGINE *ENGINE_get_default_RSA(void); ENGINE *ENGINE_get_default_DSA(void); ENGINE *ENGINE_get_default_ECDH(void); @@ -81,9 +103,6 @@ engine - ENGINE cryptographic module support int ENGINE_register_RAND(ENGINE *e); void ENGINE_unregister_RAND(ENGINE *e); void ENGINE_register_all_RAND(void); - int ENGINE_register_STORE(ENGINE *e); - void ENGINE_unregister_STORE(ENGINE *e); - void ENGINE_register_all_STORE(void); int ENGINE_register_ciphers(ENGINE *e); void ENGINE_unregister_ciphers(ENGINE *e); void ENGINE_register_all_ciphers(void); @@ -100,12 +119,6 @@ engine - ENGINE cryptographic module support int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg, int cmd_optional); - int ENGINE_set_ex_data(ENGINE *e, int idx, void *arg); - void *ENGINE_get_ex_data(const ENGINE *e, int idx); - - int ENGINE_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func); - ENGINE *ENGINE_new(void); int ENGINE_free(ENGINE *e); int ENGINE_up_ref(ENGINE *e); @@ -118,7 +131,6 @@ engine - ENGINE cryptographic module support int ENGINE_set_ECDSA(ENGINE *e, const ECDSA_METHOD *dh_meth); int ENGINE_set_DH(ENGINE *e, const DH_METHOD *dh_meth); int ENGINE_set_RAND(ENGINE *e, const RAND_METHOD *rand_meth); - int ENGINE_set_STORE(ENGINE *e, const STORE_METHOD *rand_meth); int ENGINE_set_destroy_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR destroy_f); int ENGINE_set_init_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR init_f); int ENGINE_set_finish_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR finish_f); @@ -138,7 +150,6 @@ engine - ENGINE cryptographic module support const ECDSA_METHOD *ENGINE_get_ECDSA(const ENGINE *e); const DH_METHOD *ENGINE_get_DH(const ENGINE *e); const RAND_METHOD *ENGINE_get_RAND(const ENGINE *e); - const STORE_METHOD *ENGINE_get_STORE(const ENGINE *e); ENGINE_GEN_INT_FUNC_PTR ENGINE_get_destroy_function(const ENGINE *e); ENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(const ENGINE *e); ENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(const ENGINE *e); @@ -157,7 +168,11 @@ engine - ENGINE cryptographic module support EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id, UI_METHOD *ui_method, void *callback_data); - void ENGINE_add_conf_module(void); +Deprecated: + + #if OPENSSL_API_COMPAT < 0x10100000L + void ENGINE_cleanup(void) + #endif =head1 DESCRIPTION @@ -172,7 +187,7 @@ implementation includes the following abstractions; RSA_METHOD - for providing alternative RSA implementations DSA_METHOD, DH_METHOD, RAND_METHOD, ECDH_METHOD, ECDSA_METHOD, - STORE_METHOD - similarly for other OpenSSL APIs + - similarly for other OpenSSL APIs EVP_CIPHER - potentially multiple cipher algorithms (indexed by 'nid') EVP_DIGEST - potentially multiple hash algorithms (indexed by 'nid') key-loading - loading public and/or private EVP_PKEY keys @@ -318,38 +333,30 @@ it uses static linking against openssl, then the resulting application binary will not contain any alternative ENGINE code at all. So the first consideration is whether any/all available ENGINE implementations should be made visible to OpenSSL - this is controlled by calling the various "load" -functions, eg. - - /* Make the "dynamic" ENGINE available */ - void ENGINE_load_dynamic(void); - /* Make the CryptoSwift hardware acceleration support available */ - void ENGINE_load_cswift(void); - /* Make support for nCipher's "CHIL" hardware available */ - void ENGINE_load_chil(void); - ... - /* Make ALL ENGINE implementations bundled with OpenSSL available */ - void ENGINE_load_builtin_engines(void); +functions. Having called any of these functions, ENGINE objects would have been dynamically allocated and populated with these implementations and linked into OpenSSL's internal linked list. At this point it is important to mention an important API function; - void ENGINE_cleanup(void); + void ENGINE_cleanup(void) If no ENGINE API functions are called at all in an application, then there -are no inherent memory leaks to worry about from the ENGINE functionality, -however if any ENGINEs are loaded, even if they are never registered or -used, it is necessary to use the ENGINE_cleanup() function to -correspondingly cleanup before program exit, if the caller wishes to avoid -memory leaks. This mechanism uses an internal callback registration table +are no inherent memory leaks to worry about from the ENGINE functionality. +However, prior to OpenSSL 1.1.0 if any ENGINEs are loaded, even if they are +never registered or used, it was necessary to use the ENGINE_cleanup() function +to correspondingly cleanup before program exit, if the caller wishes to avoid +memory leaks. This mechanism used an internal callback registration table so that any ENGINE API functionality that knows it requires cleanup can register its cleanup details to be called during ENGINE_cleanup(). This -approach allows ENGINE_cleanup() to clean up after any ENGINE functionality +approach allowed ENGINE_cleanup() to clean up after any ENGINE functionality at all that your program uses, yet doesn't automatically create linker dependencies to all possible ENGINE functionality - only the cleanup callbacks required by the functionality you do use will be required by the -linker. +linker. From OpenSSL 1.1.0 it is no longer necessary to explicitly call +ENGINE_cleanup and this function is deprecated. Cleanup automatically takes +place at program exit. The fact that ENGINEs are made visible to OpenSSL (and thus are linked into the program and loaded into memory at run-time) does not mean they are @@ -465,17 +472,17 @@ boolean success or failure. const char **post_cmds, int post_num) { ENGINE *e = ENGINE_by_id(engine_id); - if(!e) return 0; - while(pre_num--) { + if (!e) return 0; + while (pre_num--) { if(!ENGINE_ctrl_cmd_string(e, pre_cmds[0], pre_cmds[1], 0)) { fprintf(stderr, "Failed command (%s - %s:%s)\n", engine_id, pre_cmds[0], pre_cmds[1] ? pre_cmds[1] : "(NULL)"); ENGINE_free(e); return 0; } - pre_cmds += 2; + pre_cmds += 2; } - if(!ENGINE_init(e)) { + if (!ENGINE_init(e)) { fprintf(stderr, "Failed initialisation\n"); ENGINE_free(e); return 0; @@ -490,7 +497,7 @@ boolean success or failure. ENGINE_finish(e); return 0; } - post_cmds += 2; + post_cmds += 2; } ENGINE_set_default(e, ENGINE_METHOD_ALL & ~ENGINE_METHOD_RAND); /* Success */ @@ -517,18 +524,18 @@ implemented by ENGINEs should be numbered from. Any command value lower than this symbol is considered a "generic" command is handled directly by the OpenSSL core routines. -It is using these "core" control commands that one can discover the the control -commands implemented by a given ENGINE, specifically the commands; +It is using these "core" control commands that one can discover the control +commands implemented by a given ENGINE, specifically the commands: - #define ENGINE_HAS_CTRL_FUNCTION 10 - #define ENGINE_CTRL_GET_FIRST_CMD_TYPE 11 - #define ENGINE_CTRL_GET_NEXT_CMD_TYPE 12 - #define ENGINE_CTRL_GET_CMD_FROM_NAME 13 - #define ENGINE_CTRL_GET_NAME_LEN_FROM_CMD 14 - #define ENGINE_CTRL_GET_NAME_FROM_CMD 15 - #define ENGINE_CTRL_GET_DESC_LEN_FROM_CMD 16 - #define ENGINE_CTRL_GET_DESC_FROM_CMD 17 - #define ENGINE_CTRL_GET_CMD_FLAGS 18 + ENGINE_HAS_CTRL_FUNCTION + ENGINE_CTRL_GET_FIRST_CMD_TYPE + ENGINE_CTRL_GET_NEXT_CMD_TYPE + ENGINE_CTRL_GET_CMD_FROM_NAME + ENGINE_CTRL_GET_NAME_LEN_FROM_CMD + ENGINE_CTRL_GET_NAME_FROM_CMD + ENGINE_CTRL_GET_DESC_LEN_FROM_CMD + ENGINE_CTRL_GET_DESC_FROM_CMD + ENGINE_CTRL_GET_CMD_FLAGS Whilst these commands are automatically processed by the OpenSSL framework code, they use various properties exposed by each ENGINE to process these @@ -562,12 +569,12 @@ return properties of the corresponding commands. All except ENGINE_CTRL_GET_FLAGS return the string length of a command name or description, or populate a supplied character buffer with a copy of the command name or description. ENGINE_CTRL_GET_FLAGS returns a bitwise-OR'd mask of the following -possible values; +possible values: - #define ENGINE_CMD_FLAG_NUMERIC (unsigned int)0x0001 - #define ENGINE_CMD_FLAG_STRING (unsigned int)0x0002 - #define ENGINE_CMD_FLAG_NO_INPUT (unsigned int)0x0004 - #define ENGINE_CMD_FLAG_INTERNAL (unsigned int)0x0008 + ENGINE_CMD_FLAG_NUMERIC + ENGINE_CMD_FLAG_STRING + ENGINE_CMD_FLAG_NO_INPUT + ENGINE_CMD_FLAG_INTERNAL If the ENGINE_CMD_FLAG_INTERNAL flag is set, then any other flags are purely informational to the caller - this flag will prevent the command being usable @@ -576,24 +583,39 @@ for any higher-level ENGINE functions such as ENGINE_ctrl_cmd_string(). by applications, administrations, users, etc. These can support arbitrary operations via ENGINE_ctrl(), including passing to and/or from the control commands data of any arbitrary type. These commands are supported in the -discovery mechanisms simply to allow applications determinie if an ENGINE +discovery mechanisms simply to allow applications to determine if an ENGINE supports certain specific commands it might want to use (eg. application "foo" might query various ENGINEs to see if they implement "FOO_GET_VENDOR_LOGO_GIF" - and ENGINE could therefore decide whether or not to support this "foo"-specific extension). -=head2 Future developments +=head1 ENVIRONMENT + +=over 4 -The ENGINE API and internal architecture is currently being reviewed. Slated for -possible release in 0.9.8 is support for transparent loading of "dynamic" -ENGINEs (built as self-contained shared-libraries). This would allow ENGINE -implementations to be provided independently of OpenSSL libraries and/or -OpenSSL-based applications, and would also remove any requirement for -applications to explicitly use the "dynamic" ENGINE to bind to shared-library -implementations. +=item B<OPENSSL_ENGINES> + +The path to the engines directory. + +=back =head1 SEE ALSO -L<rsa(3)|rsa(3)>, L<dsa(3)|dsa(3)>, L<dh(3)|dh(3)>, L<rand(3)|rand(3)> +L<OPENSSL_init_crypto(3)>, L<RSA_new_method(3)>, L<dsa(3)>, L<dh(3)>, L<rand(3)> + +=head1 HISTORY + +ENGINE_cleanup(), ENGINE_load_openssl(), ENGINE_load_dynamic(), and +ENGINE_load_cryptodev() were deprecated in OpenSSL 1.1.0 by +OPENSSL_init_crypto(). + +=head1 COPYRIGHT + +Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/ERR_GET_LIB.pod b/deps/openssl/openssl/doc/crypto/ERR_GET_LIB.pod index 2a129da036..5602a8e754 100644 --- a/deps/openssl/openssl/doc/crypto/ERR_GET_LIB.pod +++ b/deps/openssl/openssl/doc/crypto/ERR_GET_LIB.pod @@ -2,8 +2,8 @@ =head1 NAME -ERR_GET_LIB, ERR_GET_FUNC, ERR_GET_REASON - get library, function and -reason code +ERR_GET_LIB, ERR_GET_FUNC, ERR_GET_REASON, ERR_FATAL_ERROR +- get information from error codes =head1 SYNOPSIS @@ -15,12 +15,16 @@ reason code int ERR_GET_REASON(unsigned long e); + int ERR_FATAL_ERROR(unsigned long e); + =head1 DESCRIPTION The error code returned by ERR_get_error() consists of a library number, function code and reason code. ERR_GET_LIB(), ERR_GET_FUNC() and ERR_GET_REASON() can be used to extract these. +ERR_FATAL_ERROR() indicates whether a given error code is a fatal error. + The library number and function code describe where the error occurred, the reason code is the information about what went wrong. @@ -33,19 +37,30 @@ B<ERR_R_...> reason codes such as B<ERR_R_MALLOC_FAILURE> are globally unique. However, when checking for sub-library specific reason codes, be sure to also compare the library number. -ERR_GET_LIB(), ERR_GET_FUNC() and ERR_GET_REASON() are macros. +ERR_GET_LIB(), ERR_GET_FUNC(), ERR_GET_REASON(), and ERR_FATAL_ERROR() + are macros. =head1 RETURN VALUES -The library number, function code and reason code respectively. +The library number, function code, reason code, and whether the error +is fatal, respectively. =head1 SEE ALSO -L<err(3)|err(3)>, L<ERR_get_error(3)|ERR_get_error(3)> +L<ERR_get_error(3)> =head1 HISTORY ERR_GET_LIB(), ERR_GET_FUNC() and ERR_GET_REASON() are available in -all versions of SSLeay and OpenSSL. +all versions of OpenSSL. + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/ERR_clear_error.pod b/deps/openssl/openssl/doc/crypto/ERR_clear_error.pod index 566e1f4e31..c8766158c2 100644 --- a/deps/openssl/openssl/doc/crypto/ERR_clear_error.pod +++ b/deps/openssl/openssl/doc/crypto/ERR_clear_error.pod @@ -20,10 +20,15 @@ ERR_clear_error() has no return value. =head1 SEE ALSO -L<err(3)|err(3)>, L<ERR_get_error(3)|ERR_get_error(3)> +L<ERR_get_error(3)> -=head1 HISTORY +=head1 COPYRIGHT -ERR_clear_error() is available in all versions of SSLeay and OpenSSL. +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/ERR_error_string.pod b/deps/openssl/openssl/doc/crypto/ERR_error_string.pod index cdfa7fe1fe..695eaf20f0 100644 --- a/deps/openssl/openssl/doc/crypto/ERR_error_string.pod +++ b/deps/openssl/openssl/doc/crypto/ERR_error_string.pod @@ -20,9 +20,12 @@ error message =head1 DESCRIPTION ERR_error_string() generates a human-readable string representing the -error code I<e>, and places it at I<buf>. I<buf> must be at least 120 +error code I<e>, and places it at I<buf>. I<buf> must be at least 256 bytes long. If I<buf> is B<NULL>, the error string is placed in a static buffer. +Note that this function is not thread-safe and does no checks on the size +of the buffer; use ERR_error_string_n() instead. + ERR_error_string_n() is a variant of ERR_error_string() that writes at most I<len> characters (including the terminating 0) and truncates the string if necessary. @@ -39,14 +42,10 @@ ERR_lib_error_string(), ERR_func_error_string() and ERR_reason_error_string() return the library name, function name and reason string respectively. -The OpenSSL error strings should be loaded by calling -L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)> or, for SSL -applications, L<SSL_load_error_strings(3)|SSL_load_error_strings(3)> -first. If there is no text string registered for the given error code, the error string will contain the numeric code. -L<ERR_print_errors(3)|ERR_print_errors(3)> can be used to print +L<ERR_print_errors(3)> can be used to print all error codes currently in the queue. =head1 RETURN VALUES @@ -60,14 +59,16 @@ none is registered for the error code. =head1 SEE ALSO -L<err(3)|err(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, -L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>, -L<SSL_load_error_strings(3)|SSL_load_error_strings(3)> -L<ERR_print_errors(3)|ERR_print_errors(3)> +L<ERR_get_error(3)>, +L<ERR_print_errors(3)> + +=head1 COPYRIGHT -=head1 HISTORY +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. -ERR_error_string() is available in all versions of SSLeay and OpenSSL. -ERR_error_string_n() was added in OpenSSL 0.9.6. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/ERR_get_error.pod b/deps/openssl/openssl/doc/crypto/ERR_get_error.pod index 01e196c95f..3b223c99de 100644 --- a/deps/openssl/openssl/doc/crypto/ERR_get_error.pod +++ b/deps/openssl/openssl/doc/crypto/ERR_get_error.pod @@ -38,9 +38,9 @@ error queue without modifying it. ERR_peek_last_error() returns the latest error code from the thread's error queue without modifying it. -See L<ERR_GET_LIB(3)|ERR_GET_LIB(3)> for obtaining information about +See L<ERR_GET_LIB(3)> for obtaining information about location and reason of the error, and -L<ERR_error_string(3)|ERR_error_string(3)> for human-readable error +L<ERR_error_string(3)> for human-readable error messages. ERR_get_error_line(), ERR_peek_error_line() and @@ -64,16 +64,16 @@ The error code, or 0 if there is no error in the queue. =head1 SEE ALSO -L<err(3)|err(3)>, L<ERR_error_string(3)|ERR_error_string(3)>, -L<ERR_GET_LIB(3)|ERR_GET_LIB(3)> +L<ERR_error_string(3)>, +L<ERR_GET_LIB(3)> -=head1 HISTORY +=head1 COPYRIGHT -ERR_get_error(), ERR_peek_error(), ERR_get_error_line() and -ERR_peek_error_line() are available in all versions of SSLeay and -OpenSSL. ERR_get_error_line_data() and ERR_peek_error_line_data() -were added in SSLeay 0.9.0. -ERR_peek_last_error(), ERR_peek_last_error_line() and -ERR_peek_last_error_line_data() were added in OpenSSL 0.9.7. +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/ERR_load_crypto_strings.pod b/deps/openssl/openssl/doc/crypto/ERR_load_crypto_strings.pod index 9bdec75a46..56d91d5dc9 100644 --- a/deps/openssl/openssl/doc/crypto/ERR_load_crypto_strings.pod +++ b/deps/openssl/openssl/doc/crypto/ERR_load_crypto_strings.pod @@ -7,26 +7,33 @@ load and free error strings =head1 SYNOPSIS +Deprecated: + #include <openssl/err.h> + #if OPENSSL_API_COMPAT < 0x10100000L void ERR_load_crypto_strings(void); void ERR_free_strings(void); + #endif #include <openssl/ssl.h> + #if OPENSSL_API_COMPAT < 0x10100000L void SSL_load_error_strings(void); + #endif =head1 DESCRIPTION +All of the following functions are deprecated from OpenSSL 1.1.0. No explicit +initialisation or de-initialisation is necessary. See L<OPENSSL_init_crypto(3)> +and L<OPENSSL_init_ssl(3)>. + ERR_load_crypto_strings() registers the error strings for all B<libcrypto> functions. SSL_load_error_strings() does the same, but also registers the B<libssl> error strings. -One of these functions should be called before generating -textual error messages. However, this is not required when memory -usage is an issue. - -ERR_free_strings() frees all previously loaded error strings. +In versions of OpenSSL prior to 1.1.0 ERR_free_strings() freed all previously +loaded error strings. However from OpenSSL 1.1.0 it does nothing. =head1 RETURN VALUES @@ -35,12 +42,21 @@ ERR_free_strings() return no values. =head1 SEE ALSO -L<err(3)|err(3)>, L<ERR_error_string(3)|ERR_error_string(3)> +L<ERR_error_string(3)> =head1 HISTORY -ERR_load_error_strings(), SSL_load_error_strings() and -ERR_free_strings() are available in all versions of SSLeay and -OpenSSL. +The ERR_load_crypto_strings(), SSL_load_error_strings(), and +ERR_free_strings() functions were deprecated in OpenSSL 1.1.0 by +OPENSSL_init_crypto() and OPENSSL_init_ssl(). + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/ERR_load_strings.pod b/deps/openssl/openssl/doc/crypto/ERR_load_strings.pod index 5acdd0edbc..ee8de2c9dc 100644 --- a/deps/openssl/openssl/doc/crypto/ERR_load_strings.pod +++ b/deps/openssl/openssl/doc/crypto/ERR_load_strings.pod @@ -39,16 +39,20 @@ to user libraries at runtime. =head1 RETURN VALUE ERR_load_strings() returns no value. ERR_PACK() return the error code. -ERR_get_next_error_library() returns a new library number. +ERR_get_next_error_library() returns zero on failure, otherwise a new +library number. =head1 SEE ALSO -L<err(3)|err(3)>, L<ERR_load_strings(3)|ERR_load_strings(3)> +L<ERR_load_strings(3)> -=head1 HISTORY +=head1 COPYRIGHT -ERR_load_error_strings() and ERR_PACK() are available in all versions -of SSLeay and OpenSSL. ERR_get_next_error_library() was added in -SSLeay 0.9.0. +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/ERR_print_errors.pod b/deps/openssl/openssl/doc/crypto/ERR_print_errors.pod index b100a5fa2b..134b374d0d 100644 --- a/deps/openssl/openssl/doc/crypto/ERR_print_errors.pod +++ b/deps/openssl/openssl/doc/crypto/ERR_print_errors.pod @@ -2,7 +2,8 @@ =head1 NAME -ERR_print_errors, ERR_print_errors_fp - print error messages +ERR_print_errors, ERR_print_errors_fp, ERR_print_errors_cb +- print error messages =head1 SYNOPSIS @@ -10,6 +11,9 @@ ERR_print_errors, ERR_print_errors_fp - print error messages void ERR_print_errors(BIO *bp); void ERR_print_errors_fp(FILE *fp); + void ERR_print_errors_cb(int (*cb)(const char *str, size_t len, void *u), + void *u) + =head1 DESCRIPTION @@ -20,6 +24,9 @@ emptying the error queue. ERR_print_errors_fp() is the same, except that the output goes to a B<FILE>. +ERR_print_errors_cb() is the same, except that the callback function, +B<cb>, is called for each error line with the string, length, and userdata +B<u> as the callback parameters. The error strings will have the following format: @@ -38,14 +45,16 @@ ERR_print_errors() and ERR_print_errors_fp() return no values. =head1 SEE ALSO -L<err(3)|err(3)>, L<ERR_error_string(3)|ERR_error_string(3)>, -L<ERR_get_error(3)|ERR_get_error(3)>, -L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>, -L<SSL_load_error_strings(3)|SSL_load_error_strings(3)> +L<ERR_error_string(3)>, +L<ERR_get_error(3)> + +=head1 COPYRIGHT -=head1 HISTORY +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. -ERR_print_errors() and ERR_print_errors_fp() -are available in all versions of SSLeay and OpenSSL. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/ERR_put_error.pod b/deps/openssl/openssl/doc/crypto/ERR_put_error.pod index acd241fbe4..14695baa19 100644 --- a/deps/openssl/openssl/doc/crypto/ERR_put_error.pod +++ b/deps/openssl/openssl/doc/crypto/ERR_put_error.pod @@ -12,6 +12,7 @@ ERR_put_error, ERR_add_error_data - record an error int line); void ERR_add_error_data(int num, ...); + void ERR_add_error_data(int num, va_list arg); =head1 DESCRIPTION @@ -22,11 +23,38 @@ This function is usually called by a macro. ERR_add_error_data() associates the concatenation of its B<num> string arguments with the error code added last. +ERR_add_error_vdata() is similar except the argument is a B<va_list>. -L<ERR_load_strings(3)|ERR_load_strings(3)> can be used to register +L<ERR_load_strings(3)> can be used to register error strings so that the application can a generate human-readable error messages for the error code. +=head2 Reporting errors + +Each sub-library has a specific macro XXXerr() that is used to report +errors. Its first argument is a function code B<XXX_F_...>, the second +argument is a reason code B<XXX_R_...>. Function codes are derived +from the function names; reason codes consist of textual error +descriptions. For example, the function ssl3_read_bytes() reports a +"handshake failure" as follows: + + SSLerr(SSL_F_SSL3_READ_BYTES, SSL_R_SSL_HANDSHAKE_FAILURE); + +Function and reason codes should consist of upper case characters, +numbers and underscores only. The error file generation script translates +function codes into function names by looking in the header files +for an appropriate function name, if none is found it just uses +the capitalized form such as "SSL3_READ_BYTES" in the above example. + +The trailing section of a reason code (after the "_R_") is translated +into lower case and underscores changed to spaces. + +Although a library will normally report errors using its own specific +XXXerr macro, another library's macro can be used. This is normally +only done when a library wants to include ASN1 code which must use +the ASN1err() macro. + + =head1 RETURN VALUES ERR_put_error() and ERR_add_error_data() return @@ -34,11 +62,15 @@ no values. =head1 SEE ALSO -L<err(3)|err(3)>, L<ERR_load_strings(3)|ERR_load_strings(3)> +L<ERR_load_strings(3)> + +=head1 COPYRIGHT -=head1 HISTORY +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. -ERR_put_error() is available in all versions of SSLeay and OpenSSL. -ERR_add_error_data() was added in SSLeay 0.9.0. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/ERR_remove_state.pod b/deps/openssl/openssl/doc/crypto/ERR_remove_state.pod index a4d38c17fd..617b4b7029 100644 --- a/deps/openssl/openssl/doc/crypto/ERR_remove_state.pod +++ b/deps/openssl/openssl/doc/crypto/ERR_remove_state.pod @@ -2,44 +2,52 @@ =head1 NAME -ERR_remove_thread_state, ERR_remove_state - free a thread's error queue +ERR_remove_thread_state, ERR_remove_state - DEPRECATED =head1 SYNOPSIS - #include <openssl/err.h> - - void ERR_remove_thread_state(const CRYPTO_THREADID *tid); - Deprecated: + #if OPENSSL_API_COMPAT < 0x10000000L void ERR_remove_state(unsigned long pid); + #endif -=head1 DESCRIPTION + #if OPENSSL_API_COMPAT < 0x10100000L + void ERR_remove_thread_state(void *); + #endif -ERR_remove_thread_state() frees the error queue associated with thread B<tid>. -If B<tid> == B<NULL>, the current thread will have its error queue removed. +=head1 DESCRIPTION -Since error queue data structures are allocated automatically for new -threads, they must be freed when threads are terminated in order to -avoid memory leaks. +The functions described here were used to free the error queue +associated with the current or specified thread. -ERR_remove_state is deprecated and has been replaced by -ERR_remove_thread_state. Since threads in OpenSSL are no longer identified -by unsigned long values any argument to this function is ignored. Calling -ERR_remove_state is equivalent to B<ERR_remove_thread_state(NULL)>. +They are now deprecated and do nothing, as the OpenSSL libraries now +normally do all thread initialisation and deinitialisation +automatically (see L<OPENSSL_init_crypto(3)>). =head1 RETURN VALUE -ERR_remove_thread_state and ERR_remove_state() return no value. +The functions described here return no value. =head1 SEE ALSO -L<err(3)|err(3)> +LL<OPENSSL_init_crypto(3)> =head1 HISTORY -ERR_remove_state() is available in all versions of SSLeay and OpenSSL. It -was deprecated in OpenSSL 1.0.0 when ERR_remove_thread_state was introduced -and thread IDs were introduced to identify threads instead of 'unsigned long'. +ERR_remove_state() was deprecated in OpenSSL 1.0.0 when +ERR_remove_thread_state() was introduced. + +ERR_remove_thread_state() was deprecated in OpenSSL 1.1.0 when the +thread handling functionality was entirely rewritten. + +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/ERR_set_mark.pod b/deps/openssl/openssl/doc/crypto/ERR_set_mark.pod index d3ca4f2e77..b3afea81e4 100644 --- a/deps/openssl/openssl/doc/crypto/ERR_set_mark.pod +++ b/deps/openssl/openssl/doc/crypto/ERR_set_mark.pod @@ -27,12 +27,13 @@ ERR_set_mark() returns 0 if the error stack is empty, otherwise 1. ERR_pop_to_mark() returns 0 if there was no mark in the error stack, which implies that the stack became empty, otherwise 1. -=head1 SEE ALSO +=head1 COPYRIGHT -L<err(3)|err(3)> +Copyright 2003-2017 The OpenSSL Project Authors. All Rights Reserved. -=head1 HISTORY - -ERR_set_mark() and ERR_pop_to_mark() were added in OpenSSL 0.9.8. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_BytesToKey.pod b/deps/openssl/openssl/doc/crypto/EVP_BytesToKey.pod index a9b6bb0c73..728c94e980 100644 --- a/deps/openssl/openssl/doc/crypto/EVP_BytesToKey.pod +++ b/deps/openssl/openssl/doc/crypto/EVP_BytesToKey.pod @@ -8,10 +8,10 @@ EVP_BytesToKey - password based encryption routine #include <openssl/evp.h> - int EVP_BytesToKey(const EVP_CIPHER *type,const EVP_MD *md, - const unsigned char *salt, - const unsigned char *data, int datal, int count, - unsigned char *key,unsigned char *iv); + int EVP_BytesToKey(const EVP_CIPHER *type, const EVP_MD *md, + const unsigned char *salt, + const unsigned char *data, int datal, int count, + unsigned char *key, unsigned char *iv); =head1 DESCRIPTION @@ -29,7 +29,7 @@ A typical application of this function is to derive keying material for an encryption algorithm from a password in the B<data> parameter. Increasing the B<count> parameter slows down the algorithm which makes it -harder for an attacker to peform a brute force attack using a large number +harder for an attacker to perform a brute force attack using a large number of candidate passwords. If the total key and IV length is less than the digest length and @@ -44,9 +44,9 @@ defined in PKCS#5v2.1 and provided by PKCS5_PBKDF2_HMAC. The key and IV is derived by concatenating D_1, D_2, etc until enough data is available for the key and IV. D_i is defined as: - D_i = HASH^count(D_(i-1) || data || salt) + D_i = HASH^count(D_(i-1) || data || salt) -where || denotes concatentaion, D_0 is empty, HASH is the digest +where || denotes concatenation, D_0 is empty, HASH is the digest algorithm in use, HASH^1(data) is simply HASH(data), HASH^2(data) is HASH(HASH(data)) and so on. @@ -62,9 +62,17 @@ or 0 on error. =head1 SEE ALSO -L<evp(3)|evp(3)>, L<rand(3)|rand(3)>, -L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> +L<evp(3)>, L<rand(3)>, +L<PKCS5_PBKDF2_HMAC(3)>, +L<EVP_EncryptInit(3)> -=head1 HISTORY +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_CIPHER_CTX_get_cipher_data.pod b/deps/openssl/openssl/doc/crypto/EVP_CIPHER_CTX_get_cipher_data.pod new file mode 100644 index 0000000000..3a57fcdb67 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/EVP_CIPHER_CTX_get_cipher_data.pod @@ -0,0 +1,51 @@ +=pod + +=head1 NAME + +EVP_CIPHER_CTX_get_cipher_data, EVP_CIPHER_CTX_set_cipher_data - Routines to +inspect and modify EVP_CIPHER_CTX objects + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + void *EVP_CIPHER_CTX_get_cipher_data(const EVP_CIPHER_CTX *ctx); + void *EVP_CIPHER_CTX_set_cipher_data(EVP_CIPHER_CTX *ctx, void *cipher_data); + +=head1 DESCRIPTION + +The EVP_CIPHER_CTX_get_cipher_data() function returns a pointer to the cipher +data relevant to EVP_CIPHER_CTX. The contents of this data is specific to the +particular implementation of the cipher. For example this data can be used by +engines to store engine specific information. The data is automatically +allocated and freed by OpenSSL, so applications and engines should not normally +free this directly (but see below). + +The EVP_CIPHER_CTX_set_cipher_data() function allows an application or engine to +replace the cipher data with new data. A pointer to any existing cipher data is +returned from this function. If the old data is no longer required then it +should be freed through a call to OPENSSL_free(). + +=head1 RETURN VALUES + +The EVP_CIPHER_CTX_get_cipher_data() function returns a pointer to the current +cipher data for the EVP_CIPHER_CTX. + +The EVP_CIPHER_CTX_set_cipher_data() function returns a pointer to the old +cipher data for the EVP_CIPHER_CTX. + +=head1 HISTORY + +The EVP_CIPHER_CTX_get_cipher_data() and EVP_CIPHER_CTX_set_cipher_data() +functions were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_CIPHER_meth_new.pod b/deps/openssl/openssl/doc/crypto/EVP_CIPHER_meth_new.pod new file mode 100644 index 0000000000..08e8290bef --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/EVP_CIPHER_meth_new.pod @@ -0,0 +1,253 @@ +=pod + +=head1 NAME + +EVP_CIPHER_meth_new, EVP_CIPHER_meth_dup, EVP_CIPHER_meth_free, +EVP_CIPHER_meth_set_iv_length, EVP_CIPHER_meth_set_flags, +EVP_CIPHER_meth_set_impl_ctx_size, EVP_CIPHER_meth_set_init, +EVP_CIPHER_meth_set_do_cipher, EVP_CIPHER_meth_set_cleanup, +EVP_CIPHER_meth_set_set_asn1_params, EVP_CIPHER_meth_set_get_asn1_params, +EVP_CIPHER_meth_set_ctrl, EVP_CIPHER_meth_get_init, +EVP_CIPHER_meth_get_do_cipher, EVP_CIPHER_meth_get_cleanup, +EVP_CIPHER_meth_get_set_asn1_params, EVP_CIPHER_meth_get_get_asn1_params, +EVP_CIPHER_meth_get_ctrl - Routines to build up EVP_CIPHER methods + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + EVP_CIPHER *EVP_CIPHER_meth_new(int cipher_type, int block_size, int key_len); + EVP_CIPHER *EVP_CIPHER_meth_dup(const EVP_CIPHER *cipher); + void EVP_CIPHER_meth_free(EVP_CIPHER *cipher); + + int EVP_CIPHER_meth_set_iv_length(EVP_CIPHER *cipher, int iv_len); + int EVP_CIPHER_meth_set_flags(EVP_CIPHER *cipher, unsigned long flags); + int EVP_CIPHER_meth_set_impl_ctx_size(EVP_CIPHER *cipher, int ctx_size); + int EVP_CIPHER_meth_set_init(EVP_CIPHER *cipher, + int (*init) (EVP_CIPHER_CTX *ctx, + const unsigned char *key, + const unsigned char *iv, + int enc)); + int EVP_CIPHER_meth_set_do_cipher(EVP_CIPHER *cipher, + int (*do_cipher) (EVP_CIPHER_CTX *ctx, + unsigned char *out, + const unsigned char *in, + size_t inl)); + int EVP_CIPHER_meth_set_cleanup(EVP_CIPHER *cipher, + int (*cleanup) (EVP_CIPHER_CTX *)); + int EVP_CIPHER_meth_set_set_asn1_params(EVP_CIPHER *cipher, + int (*set_asn1_parameters) (EVP_CIPHER_CTX *, + ASN1_TYPE *)); + int EVP_CIPHER_meth_set_get_asn1_params(EVP_CIPHER *cipher, + int (*get_asn1_parameters) (EVP_CIPHER_CTX *, + ASN1_TYPE *)); + int EVP_CIPHER_meth_set_ctrl(EVP_CIPHER *cipher, + int (*ctrl) (EVP_CIPHER_CTX *, int type, + int arg, void *ptr)); + + int (*EVP_CIPHER_meth_get_init(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *ctx, + const unsigned char *key, + const unsigned char *iv, + int enc); + int (*EVP_CIPHER_meth_get_do_cipher(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *ctx, + unsigned char *out, + const unsigned char *in, + size_t inl); + int (*EVP_CIPHER_meth_get_cleanup(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *); + int (*EVP_CIPHER_meth_get_set_asn1_params(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *, + ASN1_TYPE *); + int (*EVP_CIPHER_meth_get_get_asn1_params(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *, + ASN1_TYPE *); + int (*EVP_CIPHER_meth_get_ctrl(const EVP_CIPHER *cipher))(EVP_CIPHER_CTX *, + int type, int arg, + void *ptr); + +=head1 DESCRIPTION + +The B<EVP_CIPHER> type is a structure for symmetric cipher method +implementation. + +EVP_CIPHER_meth_new() creates a new B<EVP_CIPHER> structure. + +EVP_CIPHER_meth_dup() creates a copy of B<cipher>. + +EVP_CIPHER_meth_free() destroys a B<EVP_CIPHER> structure. + +EVP_CIPHER_meth_iv_length() sets the length of the IV. +This is only needed when the implemented cipher mode requires it. + +EVP_CIPHER_meth_set_flags() sets the flags to describe optional +behaviours in the particular B<cipher>. +With the exception of cipher modes, of which only one may be present, +several flags can be or'd together. +The available flags are: + +=over 4 + +=item EVP_CIPH_STREAM_CIPHER, EVP_CIPH_ECB_MODE EVP_CIPH_CBC_MODE, +EVP_CIPH_CFB_MODE, EVP_CIPH_OFB_MODE, EVP_CIPH_CTR_MODE, EVP_CIPH_GCM_MODE, +EVP_CIPH_CCM_MODE, EVP_CIPH_XTS_MODE, EVP_CIPH_WRAP_MODE, +EVP_CIPH_OCB_MODE + +The cipher mode. + +=item EVP_CIPH_VARIABLE_LENGTH + +This cipher is of variable length. + +=item EVP_CIPH_CUSTOM_IV + +Storing and initialising the IV is left entirely to the +implementation. + +=item EVP_CIPH_ALWAYS_CALL_INIT + +Set this if the implementation's init() function should be called even +if B<key> is B<NULL>. + +=item EVP_CIPH_CTRL_INIT + +Set this to have the implementation's ctrl() function called with +command code B<EVP_CTRL_INIT> early in its setup. + +=item EVP_CIPH_CUSTOM_KEY_LENGTH + +Checking and setting the key length after creating the B<EVP_CIPHER> +is left to the implementation. +Whenever someone uses EVP_CIPHER_CTX_set_key_length() on a +B<EVP_CIPHER> with this flag set, the implementation's ctrl() function +will be called with the control code B<EVP_CTRL_SET_KEY_LENGTH> and +the key length in B<arg>. + +=item EVP_CIPH_NO_PADDING + +Don't use standard block padding. + +=item EVP_CIPH_RAND_KEY + +Making a key with random content is left to the implementation. +This is done by calling the implementation's ctrl() function with the +control code B<EVP_CTRL_RAND_KEY> and the pointer to the key memory +storage in B<ptr>. + +=item EVP_CIPH_CUSTOM_COPY + +Set this to have the implementation's ctrl() function called with +command code B<EVP_CTRL_COPY> at the end of EVP_CIPHER_CTX_copy(). +The intended use is for further things to deal with after the +implementation specific data block has been copied. +The destination B<EVP_CIPHER_CTX> is passed to the control with the +B<ptr> parameter. +The implementation specific data block is reached with +EVP_CIPHER_CTX_get_cipher_data(). + +=item EVP_CIPH_FLAG_DEFAULT_ASN1 + +Use the default EVP routines to pass IV to and from ASN.1. + +=item EVP_CIPH_FLAG_LENGTH_BITS + +Signals that the length of the input buffer for encryption / +decryption is to be understood as the number of bits bits instead of +bytes for this implementation. +This is only useful for CFB1 ciphers. + +=begin comment +The FIPS flags seem to be unused, so I'm hiding them until I get an +explanation or they get removed. /RL + +=item EVP_CIPH_FLAG_FIPS + +=item EVP_CIPH_FLAG_NON_FIPS_ALLOW + +=end comment + +=item EVP_CIPH_FLAG_CUSTOM_CIPHER + +This indicates that the implementation takes care of everything, +including padding, buffering and finalization. +The EVP routines will simply give them control and do nothing more. + +=item EVP_CIPH_FLAG_AEAD_CIPHER + +This indicates that this is an AEAD cipher implementation. + +=item EVP_CIPH_FLAG_TLS1_1_MULTIBLOCK + +Allow interleaving of crypto blocks, a particular optimization only applicable +to certain TLS ciphers. + +=back + +EVP_CIPHER_meth_set_impl_ctx_size() sets the size of the EVP_CIPHER's +implementation context so that it can be automatically allocated. + +EVP_CIPHER_meth_set_init() sets the cipher init function for +B<cipher>. +The cipher init function is called by EVP_CipherInit(), +EVP_CipherInit_ex(), EVP_EncryptInit(), EVP_EncryptInit_ex(), +EVP_DecryptInit(), EVP_DecryptInit_ex(). + +EVP_CIPHER_meth_set_do_cipher() sets the cipher function for +B<cipher>. +The cipher function is called by EVP_CipherUpdate(), +EVP_EncryptUpdate(), EVP_DecryptUpdate(), EVP_CipherFinal(), +EVP_EncryptFinal(), EVP_EncryptFinal_ex(), EVP_DecryptFinal() and +EVP_DecryptFinal_ex(). + +EVP_CIPHER_meth_set_cleanup() sets the function for B<cipher> to do +extra cleanup before the method's private data structure is cleaned +out and freed. +Note that the cleanup function is passed a B<EVP_CIPHER_CTX *>, the +private data structure is then available with +EVP_CIPHER_CTX_get_cipher_data(). +This cleanup function is called by EVP_CIPHER_CTX_reset() and +EVP_CIPHER_CTX_free(). + +EVP_CIPHER_meth_set_set_asn1_params() sets the function for B<cipher> +to set the AlgorithmIdentifier "parameter" based on the passed cipher. +This function is called by EVP_CIPHER_param_to_asn1(). +EVP_CIPHER_meth_set_get_asn1_params() sets the function for B<cipher> +that sets the cipher parameters based on an ASN.1 AlgorithmIdentifier +"parameter". +Both these functions are needed when there is a need for custom data +(more or other than the cipher IV). +They are called by EVP_CIPHER_param_to_asn1() and +EVP_CIPHER_asn1_to_param() respectively if defined. + +EVP_CIPHER_meth_set_ctrl() sets the control function for B<cipher>. + +EVP_CIPHER_meth_get_init(), EVP_CIPHER_meth_get_do_cipher(), +EVP_CIPHER_meth_get_cleanup(), EVP_CIPHER_meth_get_set_asn1_params(), +EVP_CIPHER_meth_get_get_asn1_params() and EVP_CIPHER_meth_get_ctrl() +are all used to retrieve the method data given with the +EVP_CIPHER_meth_set_*() functions above. + +=head1 RETURN VALUES + +EVP_CIPHER_meth_new() and EVP_CIPHER_meth_dup() return a pointer to a +newly created B<EVP_CIPHER>, or NULL on failure. +All EVP_CIPHER_meth_set_*() functions return 1. +All EVP_CIPHER_meth_get_*() functions return pointers to their +respective B<cipher> function. + +=head1 SEE ALSO + +L<EVP_EncryptInit> + +=head1 HISTORY + +The B<EVP_CIPHER> structure was openly available in OpenSSL before version +1.1.0. +The functions described here were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_DigestInit.pod b/deps/openssl/openssl/doc/crypto/EVP_DigestInit.pod index 0895e8c392..bb7ef7a28f 100644 --- a/deps/openssl/openssl/doc/crypto/EVP_DigestInit.pod +++ b/deps/openssl/openssl/doc/crypto/EVP_DigestInit.pod @@ -2,59 +2,54 @@ =head1 NAME -EVP_MD_CTX_init, EVP_MD_CTX_create, EVP_DigestInit_ex, EVP_DigestUpdate, -EVP_DigestFinal_ex, EVP_MD_CTX_cleanup, EVP_MD_CTX_destroy, EVP_MAX_MD_SIZE, -EVP_MD_CTX_copy_ex, EVP_DigestInit, EVP_DigestFinal, EVP_MD_CTX_copy, EVP_MD_type, +EVP_MD_CTX_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_copy_ex, +EVP_DigestInit_ex, EVP_DigestUpdate, EVP_DigestFinal_ex, +EVP_DigestInit, EVP_DigestFinal, EVP_MD_CTX_copy, EVP_MD_type, EVP_MD_pkey_type, EVP_MD_size, EVP_MD_block_size, EVP_MD_CTX_md, EVP_MD_CTX_size, -EVP_MD_CTX_block_size, EVP_MD_CTX_type, EVP_md_null, EVP_md2, EVP_md5, EVP_sha, EVP_sha1, -EVP_sha224, EVP_sha256, EVP_sha384, EVP_sha512, EVP_dss, EVP_dss1, EVP_mdc2, -EVP_ripemd160, EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj - -EVP digest routines +EVP_MD_CTX_block_size, EVP_MD_CTX_type, EVP_md_null, EVP_md2, EVP_md5, EVP_sha1, +EVP_sha224, EVP_sha256, EVP_sha384, EVP_sha512, EVP_mdc2, +EVP_ripemd160, EVP_blake2b512, EVP_blake2s256, EVP_get_digestbyname, +EVP_get_digestbynid, EVP_get_digestbyobj - EVP digest routines =head1 SYNOPSIS #include <openssl/evp.h> - void EVP_MD_CTX_init(EVP_MD_CTX *ctx); - EVP_MD_CTX *EVP_MD_CTX_create(void); + EVP_MD_CTX *EVP_MD_CTX_new(void); + int EVP_MD_CTX_reset(EVP_MD_CTX *ctx); + void EVP_MD_CTX_free(EVP_MD_CTX *ctx); int EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl); int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt); int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s); - int EVP_MD_CTX_cleanup(EVP_MD_CTX *ctx); - void EVP_MD_CTX_destroy(EVP_MD_CTX *ctx); - - int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out,const EVP_MD_CTX *in); + int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out, const EVP_MD_CTX *in); int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type); int EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s); - int EVP_MD_CTX_copy(EVP_MD_CTX *out,EVP_MD_CTX *in); - - #define EVP_MAX_MD_SIZE 64 /* SHA512 */ + int EVP_MD_CTX_copy(EVP_MD_CTX *out, EVP_MD_CTX *in); int EVP_MD_type(const EVP_MD *md); - int EVP_MD_pkey_type(const EVP_MD *md); + int EVP_MD_pkey_type(const EVP_MD *md); int EVP_MD_size(const EVP_MD *md); int EVP_MD_block_size(const EVP_MD *md); const EVP_MD *EVP_MD_CTX_md(const EVP_MD_CTX *ctx); - #define EVP_MD_CTX_size(e) EVP_MD_size(EVP_MD_CTX_md(e)) - #define EVP_MD_CTX_block_size(e) EVP_MD_block_size((e)->digest) - #define EVP_MD_CTX_type(e) EVP_MD_type((e)->digest) + int EVP_MD_CTX_size(const EVP_MD *ctx); + int EVP_MD_CTX_block_size(const EVP_MD *ctx); + int EVP_MD_CTX_type(const EVP_MD *ctx); const EVP_MD *EVP_md_null(void); const EVP_MD *EVP_md2(void); const EVP_MD *EVP_md5(void); - const EVP_MD *EVP_sha(void); const EVP_MD *EVP_sha1(void); - const EVP_MD *EVP_dss(void); - const EVP_MD *EVP_dss1(void); const EVP_MD *EVP_mdc2(void); const EVP_MD *EVP_ripemd160(void); + const EVP_MD *EVP_blake2b512(void); + const EVP_MD *EVP_blake2s256(void); const EVP_MD *EVP_sha224(void); const EVP_MD *EVP_sha256(void); @@ -62,20 +57,25 @@ EVP digest routines const EVP_MD *EVP_sha512(void); const EVP_MD *EVP_get_digestbyname(const char *name); - #define EVP_get_digestbynid(a) EVP_get_digestbyname(OBJ_nid2sn(a)) - #define EVP_get_digestbyobj(a) EVP_get_digestbynid(OBJ_obj2nid(a)) + const EVP_MD *EVP_get_digestbynid(int type); + const EVP_MD *EVP_get_digestbyobj(const ASN1_OBJECT *o); =head1 DESCRIPTION -The EVP digest routines are a high level interface to message digests. +The EVP digest routines are a high level interface to message digests, +and should be used instead of the cipher-specific functions. -EVP_MD_CTX_init() initializes digest context B<ctx>. +EVP_MD_CTX_new() allocates, initializes and returns a digest context. -EVP_MD_CTX_create() allocates, initializes and returns a digest context. +EVP_MD_CTX_reset() resets the digest context B<ctx>. This can be used +to reuse an already existing context. + +EVP_MD_CTX_free() cleans up digest context B<ctx> and frees up the +space allocated to it. EVP_DigestInit_ex() sets up digest context B<ctx> to use a digest B<type> from ENGINE B<impl>. B<ctx> must be initialized before calling this -function. B<type> will typically be supplied by a functionsuch as EVP_sha1(). +function. B<type> will typically be supplied by a function such as EVP_sha1(). If B<impl> is NULL then the default implementation of digest B<type> is used. EVP_DigestUpdate() hashes B<cnt> bytes of data at B<d> into the @@ -90,13 +90,6 @@ After calling EVP_DigestFinal_ex() no additional calls to EVP_DigestUpdate() can be made, but EVP_DigestInit_ex() can be called to initialize a new digest operation. -EVP_MD_CTX_cleanup() cleans up digest context B<ctx>, it should be called -after a digest context is no longer needed. - -EVP_MD_CTX_destroy() cleans up digest context B<ctx> and frees up the -space allocated to it, it should be called only on a context created -using EVP_MD_CTX_create(). - EVP_MD_CTX_copy_ex() can be used to copy the message digest state from B<in> to B<out>. This is useful if large amounts of data are to be hashed which only differ in the last few bytes. B<out> must be initialized @@ -133,23 +126,18 @@ return B<NID_sha1WithRSAEncryption>. Since digests and signature algorithms are no longer linked this function is only retained for compatibility reasons. -EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_sha224(), EVP_sha256(), -EVP_sha384(), EVP_sha512(), EVP_mdc2() and EVP_ripemd160() return B<EVP_MD> -structures for the MD2, MD5, SHA, SHA1, SHA224, SHA256, SHA384, SHA512, MDC2 -and RIPEMD160 digest algorithms respectively. - -EVP_dss() and EVP_dss1() return B<EVP_MD> structures for SHA and SHA1 digest -algorithms but using DSS (DSA) for the signature algorithm. Note: there is -no need to use these pseudo-digests in OpenSSL 1.0.0 and later, they are -however retained for compatibility. +EVP_md2(), EVP_md5(), EVP_sha1(), EVP_sha224(), EVP_sha256(), +EVP_sha384(), EVP_sha512(), EVP_mdc2(), EVP_ripemd160(), EVP_blake2b512(), and +EVP_blake2s256() return B<EVP_MD> structures for the MD2, MD5, SHA1, SHA224, +SHA256, SHA384, SHA512, MDC2, RIPEMD160, BLAKE2b-512, and BLAKE2s-256 digest +algorithms respectively. EVP_md_null() is a "null" message digest that does nothing: i.e. the hash it returns is of zero length. EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj() return an B<EVP_MD> structure when passed a digest name, a digest NID or -an ASN1_OBJECT structure respectively. The digest table must be initialized -using, for example, OpenSSL_add_all_digests() for these functions to work. +an ASN1_OBJECT structure respectively. =head1 RETURN VALUES @@ -164,9 +152,9 @@ corresponding OBJECT IDENTIFIER or NID_undef if none exists. EVP_MD_size(), EVP_MD_block_size(), EVP_MD_CTX_size() and EVP_MD_CTX_block_size() return the digest or block size in bytes. -EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_dss(), -EVP_dss1(), EVP_mdc2() and EVP_ripemd160() return pointers to the -corresponding EVP_MD structures. +EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha1(), +EVP_mdc2(), EVP_ripemd160(), EVP_blake2b512(), and EVP_blake2s256() return +pointers to the corresponding EVP_MD structures. EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj() return either an B<EVP_MD> structure or NULL if an error occurs. @@ -190,20 +178,12 @@ EVP_MD_CTX_copy_ex() because they can efficiently reuse a digest context instead of initializing and cleaning it up on each call and allow non default implementations of digests to be specified. -In OpenSSL 0.9.7 and later if digest contexts are not cleaned up after use +If digest contexts are not cleaned up after use memory leaks will occur. -Stack allocation of EVP_MD_CTX structures is common, for example: - - EVP_MD_CTX mctx; - EVP_MD_CTX_init(&mctx); - -This will cause binary compatibility issues if the size of EVP_MD_CTX -structure changes (this will only happen with a major release of OpenSSL). -Applications wishing to avoid this should use EVP_MD_CTX_create() instead: - - EVP_MD_CTX *mctx; - mctx = EVP_MD_CTX_create(); +EVP_MD_CTX_size(), EVP_MD_CTX_block_size(), EVP_MD_CTX_type(), +EVP_get_digestbynid() and EVP_get_digestbyobj() are defined as +macros. =head1 EXAMPLE @@ -223,60 +203,57 @@ digest name passed on the command line. unsigned char md_value[EVP_MAX_MD_SIZE]; int md_len, i; - OpenSSL_add_all_digests(); - if(!argv[1]) { - printf("Usage: mdtest digestname\n"); - exit(1); + printf("Usage: mdtest digestname\n"); + exit(1); } md = EVP_get_digestbyname(argv[1]); if(!md) { - printf("Unknown message digest %s\n", argv[1]); - exit(1); + printf("Unknown message digest %s\n", argv[1]); + exit(1); } - mdctx = EVP_MD_CTX_create(); + mdctx = EVP_MD_CTX_new(); EVP_DigestInit_ex(mdctx, md, NULL); EVP_DigestUpdate(mdctx, mess1, strlen(mess1)); EVP_DigestUpdate(mdctx, mess2, strlen(mess2)); EVP_DigestFinal_ex(mdctx, md_value, &md_len); - EVP_MD_CTX_destroy(mdctx); + EVP_MD_CTX_free(mdctx); printf("Digest is: "); - for(i = 0; i < md_len; i++) - printf("%02x", md_value[i]); + for (i = 0; i < md_len; i++) + printf("%02x", md_value[i]); printf("\n"); - /* Call this once before exit. */ - EVP_cleanup(); exit(0); } =head1 SEE ALSO -L<dgst(1)|dgst(1)>, -L<evp(3)|evp(3)> +L<dgst(1)>, +L<evp(7)> =head1 HISTORY -EVP_DigestInit(), EVP_DigestUpdate() and EVP_DigestFinal() are -available in all versions of SSLeay and OpenSSL. +B<EVP_MD_CTX> became opaque in OpenSSL 1.1. Consequently, stack +allocated B<EVP_MD_CTX>s are no longer supported. -EVP_MD_CTX_init(), EVP_MD_CTX_create(), EVP_MD_CTX_copy_ex(), -EVP_MD_CTX_cleanup(), EVP_MD_CTX_destroy(), EVP_DigestInit_ex() -and EVP_DigestFinal_ex() were added in OpenSSL 0.9.7. - -EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), -EVP_dss(), EVP_dss1(), EVP_mdc2() and EVP_ripemd160() were -changed to return truly const EVP_MD * in OpenSSL 0.9.7. +EVP_MD_CTX_create() and EVP_MD_CTX_destroy() were renamed to +EVP_MD_CTX_new() and EVP_MD_CTX_free() in OpenSSL 1.1. The link between digests and signing algorithms was fixed in OpenSSL 1.0 and -later, so now EVP_sha1() can be used with RSA and DSA; there is no need to -use EVP_dss1() any more. +later, so now EVP_sha1() can be used with RSA and DSA. The legacy EVP_dss1() +was removed in OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. -OpenSSL 1.0 and later does not include the MD2 digest algorithm in the -default configuration due to its security weaknesses. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_DigestSignInit.pod b/deps/openssl/openssl/doc/crypto/EVP_DigestSignInit.pod index 83e65894d9..7ec06b7a27 100644 --- a/deps/openssl/openssl/doc/crypto/EVP_DigestSignInit.pod +++ b/deps/openssl/openssl/doc/crypto/EVP_DigestSignInit.pod @@ -9,7 +9,7 @@ EVP_DigestSignInit, EVP_DigestSignUpdate, EVP_DigestSignFinal - EVP signing func #include <openssl/evp.h> int EVP_DigestSignInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, - const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey); + const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey); int EVP_DigestSignUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt); int EVP_DigestSignFinal(EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen); @@ -18,15 +18,15 @@ EVP_DigestSignInit, EVP_DigestSignUpdate, EVP_DigestSignFinal - EVP signing func The EVP signature routines are a high level interface to digital signatures. EVP_DigestSignInit() sets up signing context B<ctx> to use digest B<type> from -ENGINE B<impl> and private key B<pkey>. B<ctx> must be initialized with -EVP_MD_CTX_init() before calling this function. If B<pctx> is not NULL the +ENGINE B<impl> and private key B<pkey>. B<ctx> must be created with +EVP_MD_CTX_new() before calling this function. If B<pctx> is not NULL the EVP_PKEY_CTX of the signing operation will be written to B<*pctx>: this can be used to set alternative signing options. EVP_DigestSignUpdate() hashes B<cnt> bytes of data at B<d> into the signature context B<ctx>. This function can be called several times on the same B<ctx> to include additional data. This function is currently implemented -usig a macro. +using a macro. EVP_DigestSignFinal() signs the data in B<ctx> places the signature in B<sig>. If B<sig> is B<NULL> then the maximum size of the output buffer is written to @@ -42,7 +42,7 @@ EVP_DigestSignInit() EVP_DigestSignUpdate() and EVP_DigestSignaFinal() return value of -2 indicates the operation is not supported by the public key algorithm. -The error codes can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>. +The error codes can be obtained from L<ERR_get_error(3)>. =head1 NOTES @@ -56,7 +56,7 @@ needed to be used to sign using SHA1 and DSA. This is no longer necessary and the use of clone digest is now discouraged. For some key types and parameters the random number generator must be seeded -or the operation will fail. +or the operation will fail. The call to EVP_DigestSignFinal() internally finalizes a copy of the digest context. This means that calls to EVP_DigestSignUpdate() and @@ -73,15 +73,24 @@ which indicates the maximum possible signature for any set of parameters. =head1 SEE ALSO -L<EVP_DigestVerifyInit(3)|EVP_DigestVerifyInit(3)>, -L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>, -L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, -L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, -L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)> +L<EVP_DigestVerifyInit(3)>, +L<EVP_DigestInit(3)>, +L<evp(7)>, L<HMAC(3)>, L<MD2(3)>, +L<MD5(3)>, L<MDC2(3)>, L<RIPEMD160(3)>, +L<SHA1(3)>, L<dgst(1)> =head1 HISTORY -EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal() +EVP_DigestSignInit(), EVP_DigestSignUpdate() and EVP_DigestSignFinal() were first added to OpenSSL 1.0.0. +=head1 COPYRIGHT + +Copyright 2006-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_DigestVerifyInit.pod b/deps/openssl/openssl/doc/crypto/EVP_DigestVerifyInit.pod index 347c511663..ce59422d3e 100644 --- a/deps/openssl/openssl/doc/crypto/EVP_DigestVerifyInit.pod +++ b/deps/openssl/openssl/doc/crypto/EVP_DigestVerifyInit.pod @@ -9,7 +9,7 @@ EVP_DigestVerifyInit, EVP_DigestVerifyUpdate, EVP_DigestVerifyFinal - EVP signat #include <openssl/evp.h> int EVP_DigestVerifyInit(EVP_MD_CTX *ctx, EVP_PKEY_CTX **pctx, - const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey); + const EVP_MD *type, ENGINE *e, EVP_PKEY *pkey); int EVP_DigestVerifyUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt); int EVP_DigestVerifyFinal(EVP_MD_CTX *ctx, const unsigned char *sig, size_t siglen); @@ -18,8 +18,8 @@ EVP_DigestVerifyInit, EVP_DigestVerifyUpdate, EVP_DigestVerifyFinal - EVP signat The EVP signature routines are a high level interface to digital signatures. EVP_DigestVerifyInit() sets up verification context B<ctx> to use digest -B<type> from ENGINE B<impl> and public key B<pkey>. B<ctx> must be initialized -with EVP_MD_CTX_init() before calling this function. If B<pctx> is not NULL the +B<type> from ENGINE B<impl> and public key B<pkey>. B<ctx> must be created +with EVP_MD_CTX_new() before calling this function. If B<pctx> is not NULL the EVP_PKEY_CTX of the verification operation will be written to B<*pctx>: this can be used to set alternative verification options. @@ -34,8 +34,7 @@ B<sig> of length B<siglen>. =head1 RETURN VALUES EVP_DigestVerifyInit() and EVP_DigestVerifyUpdate() return 1 for success and 0 -or a negative value for failure. In particular a return value of -2 indicates -the operation is not supported by the public key algorithm. +for failure. EVP_DigestVerifyFinal() returns 1 for success; any other value indicates failure. A return value of zero indicates that the signature did not verify @@ -43,7 +42,7 @@ successfully (that is, tbs did not match the original data or the signature had an invalid form), while other values indicate a more serious error (and sometimes also indicate an invalid signature form). -The error codes can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>. +The error codes can be obtained from L<ERR_get_error(3)>. =head1 NOTES @@ -57,7 +56,7 @@ needed to be used to sign using SHA1 and DSA. This is no longer necessary and the use of clone digest is now discouraged. For some key types and parameters the random number generator must be seeded -or the operation will fail. +or the operation will fail. The call to EVP_DigestVerifyFinal() internally finalizes a copy of the digest context. This means that EVP_VerifyUpdate() and EVP_VerifyFinal() can @@ -69,15 +68,24 @@ will occur. =head1 SEE ALSO -L<EVP_DigestSignInit(3)|EVP_DigestSignInit(3)>, -L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>, -L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, -L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, -L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)> +L<EVP_DigestSignInit(3)>, +L<EVP_DigestInit(3)>, +L<evp(7)>, L<HMAC(3)>, L<MD2(3)>, +L<MD5(3)>, L<MDC2(3)>, L<RIPEMD160(3)>, +L<SHA1(3)>, L<dgst(1)> =head1 HISTORY -EVP_DigestVerifyInit(), EVP_DigestVerifyUpdate() and EVP_DigestVerifyFinal() +EVP_DigestVerifyInit(), EVP_DigestVerifyUpdate() and EVP_DigestVerifyFinal() were first added to OpenSSL 1.0.0. +=head1 COPYRIGHT + +Copyright 2006-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_EncodeInit.pod b/deps/openssl/openssl/doc/crypto/EVP_EncodeInit.pod index c6f12674f6..d919b14b29 100644 --- a/deps/openssl/openssl/doc/crypto/EVP_EncodeInit.pod +++ b/deps/openssl/openssl/doc/crypto/EVP_EncodeInit.pod @@ -2,17 +2,22 @@ =head1 NAME -EVP_EncodeInit, EVP_EncodeUpdate, EVP_EncodeFinal, EVP_EncodeBlock, -EVP_DecodeInit, EVP_DecodeUpdate, EVP_DecodeFinal, EVP_DecodeBlock - EVP base 64 -encode/decode routines +EVP_ENCODE_CTX_new, EVP_ENCODE_CTX_free, EVP_ENCODE_CTX_copy, +EVP_ENCODE_CTX_num, EVP_EncodeInit, EVP_EncodeUpdate, EVP_EncodeFinal, +EVP_EncodeBlock, EVP_DecodeInit, EVP_DecodeUpdate, EVP_DecodeFinal, +EVP_DecodeBlock - EVP base 64 encode/decode routines =head1 SYNOPSIS #include <openssl/evp.h> + EVP_ENCODE_CTX *EVP_ENCODE_CTX_new(void); + void EVP_ENCODE_CTX_free(EVP_ENCODE_CTX *ctx); + int EVP_ENCODE_CTX_copy(EVP_ENCODE_CTX *dctx, EVP_ENCODE_CTX *sctx); + int EVP_ENCODE_CTX_num(EVP_ENCODE_CTX *ctx); void EVP_EncodeInit(EVP_ENCODE_CTX *ctx); - void EVP_EncodeUpdate(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl, - const unsigned char *in, int inl); + int EVP_EncodeUpdate(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl, + const unsigned char *in, int inl); void EVP_EncodeFinal(EVP_ENCODE_CTX *ctx, unsigned char *out, int *outl); int EVP_EncodeBlock(unsigned char *t, const unsigned char *f, int n); @@ -33,6 +38,12 @@ plus some occasional newlines (see below). If the input data length is not a multiple of 3 then the output data will be padded at the end using the "=" character. +EVP_ENCODE_CTX_new() allocates, initializes and returns a context to be used for +the encode/decode functions. + +EVP_ENCODE_CTX_free() cleans up an encode/decode context B<ctx> and frees up the +space allocated to it. + Encoding of binary data is performed in blocks of 48 input bytes (or less for the final block). For each 48 byte input block encoded 64 bytes of base 64 data is output plus an additional newline character (i.e. 65 bytes in total). The @@ -56,7 +67,8 @@ any remainder). This gives the number of blocks of data that will be processed. Ensure the output buffer contains 65 bytes of storage for each block, plus an additional byte for a NUL terminator. EVP_EncodeUpdate() may be called repeatedly to process large amounts of input data. In the event of an error -EVP_EncodeUpdate() will set B<*outl> to 0. +EVP_EncodeUpdate() will set B<*outl> to 0 and return 0. On success 1 will be +returned. EVP_EncodeFinal() must be called at the end of an encoding operation. It will process any partial block of data remaining in the B<ctx> object. The output @@ -65,6 +77,12 @@ in B<*outl>. It is the caller's responsibility to ensure that B<out> is sufficiently large to accommodate the output data which will never be more than 65 bytes plus an additional NUL terminator (i.e. 66 bytes in total). +EVP_ENCODE_CTX_copy() can be used to copy a context B<sctx> to a context +B<dctx>. B<dctx> must be initialized before calling this function. + +EVP_ENCODE_CTX_num() will return the number of as yet unprocessed bytes still to +be encoded or decoded that are pending in the B<ctx> object. + EVP_EncodeBlock() encodes a full block of input data in B<f> and of length B<dlen> and stores it in B<t>. For every 3 bytes of input provided 4 bytes of output data will be produced. If B<dlen> is not divisible by 3 then the block is @@ -102,7 +120,7 @@ in this case. Otherwise the function returns 1 on success. EVP_DecodeBlock() will decode the block of B<n> characters of base 64 data contained in B<f> and store the result in B<t>. Any leading whitespace will be trimmed as will any trailing whitespace, newlines, carriage returns or EOF -characters. After such trimming the length of the data in B<f> must be divisbile +characters. After such trimming the length of the data in B<f> must be divisible by 4. For every 4 input bytes exactly 3 output bytes will be produced. The output will be padded with 0 bits if necessary to ensure that the output is always 3 bytes for every 4 input bytes. This function will return the length of @@ -110,6 +128,14 @@ the data decoded or -1 on error. =head1 RETURN VALUES +EVP_ENCODE_CTX_new() returns a pointer to the newly allocated EVP_ENCODE_CTX +object or NULL on error. + +EVP_ENCODE_CTX_num() returns the number of bytes pending encoding or decoding in +B<ctx>. + +EVP_EncodeUpdate() returns 0 on error or 1 on success. + EVP_EncodeBlock() returns the number of bytes encoded excluding the NUL terminator. @@ -124,4 +150,13 @@ EVP_DecodeBlock() returns the length of the data decoded or -1 on error. L<evp(3)> +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_EncryptInit.pod b/deps/openssl/openssl/doc/crypto/EVP_EncryptInit.pod index 4973f0a23b..d1af772fc8 100644 --- a/deps/openssl/openssl/doc/crypto/EVP_EncryptInit.pod +++ b/deps/openssl/openssl/doc/crypto/EVP_EncryptInit.pod @@ -2,11 +2,11 @@ =head1 NAME -EVP_CIPHER_CTX_init, EVP_EncryptInit_ex, EVP_EncryptUpdate, -EVP_EncryptFinal_ex, EVP_DecryptInit_ex, EVP_DecryptUpdate, -EVP_DecryptFinal_ex, EVP_CipherInit_ex, EVP_CipherUpdate, -EVP_CipherFinal_ex, EVP_CIPHER_CTX_set_key_length, -EVP_CIPHER_CTX_ctrl, EVP_CIPHER_CTX_cleanup, EVP_EncryptInit, +EVP_CIPHER_CTX_new, EVP_CIPHER_CTX_reset, EVP_CIPHER_CTX_free, +EVP_EncryptInit_ex, EVP_EncryptUpdate, EVP_EncryptFinal_ex, +EVP_DecryptInit_ex, EVP_DecryptUpdate, EVP_DecryptFinal_ex, +EVP_CipherInit_ex, EVP_CipherUpdate, EVP_CipherFinal_ex, +EVP_CIPHER_CTX_set_key_length, EVP_CIPHER_CTX_ctrl, EVP_EncryptInit, EVP_EncryptFinal, EVP_DecryptInit, EVP_DecryptFinal, EVP_CipherInit, EVP_CipherFinal, EVP_get_cipherbyname, EVP_get_cipherbynid, EVP_get_cipherbyobj, EVP_CIPHER_nid, @@ -16,7 +16,7 @@ EVP_CIPHER_CTX_nid, EVP_CIPHER_CTX_block_size, EVP_CIPHER_CTX_key_length, EVP_CIPHER_CTX_iv_length, EVP_CIPHER_CTX_get_app_data, EVP_CIPHER_CTX_set_app_data, EVP_CIPHER_CTX_type, EVP_CIPHER_CTX_flags, EVP_CIPHER_CTX_mode, EVP_CIPHER_param_to_asn1, EVP_CIPHER_asn1_to_param, -EVP_CIPHER_CTX_set_padding, EVP_enc_null, EVP_des_cbc, EVP_des_ecb, +EVP_CIPHER_CTX_set_padding, EVP_enc_null, EVP_des_cbc, EVP_des_ecb, EVP_des_cfb, EVP_des_ofb, EVP_des_ede_cbc, EVP_des_ede, EVP_des_ede_ofb, EVP_des_ede_cfb, EVP_des_ede3_cbc, EVP_des_ede3, EVP_des_ede3_ofb, EVP_des_ede3_cfb, EVP_desx_cbc, EVP_rc4, EVP_rc4_40, EVP_rc4_hmac_md5, @@ -24,18 +24,25 @@ EVP_idea_cbc, EVP_idea_ecb, EVP_idea_cfb, EVP_idea_ofb, EVP_rc2_cbc, EVP_rc2_ecb, EVP_rc2_cfb, EVP_rc2_ofb, EVP_rc2_40_cbc, EVP_rc2_64_cbc, EVP_bf_cbc, EVP_bf_ecb, EVP_bf_cfb, EVP_bf_ofb, EVP_cast5_cbc, EVP_cast5_ecb, EVP_cast5_cfb, EVP_cast5_ofb, EVP_rc5_32_12_16_cbc, -EVP_rc5_32_12_16_ecb, EVP_rc5_32_12_16_cfb, EVP_rc5_32_12_16_ofb, -EVP_aes_128_gcm, EVP_aes_192_gcm, EVP_aes_256_gcm, EVP_aes_128_ccm, -EVP_aes_192_ccm, EVP_aes_256_ccm, +EVP_rc5_32_12_16_ecb, EVP_rc5_32_12_16_cfb, EVP_rc5_32_12_16_ofb, +EVP_aes_128_cbc, EVP_aes_128_ecb, EVP_aes_128_cfb, EVP_aes_128_ofb, +EVP_aes_192_cbc, EVP_aes_192_ecb, EVP_aes_192_cfb, EVP_aes_192_ofb, +EVP_aes_256_cbc, EVP_aes_256_ecb, EVP_aes_256_cfb, EVP_aes_256_ofb, +EVP_aes_128_gcm, EVP_aes_192_gcm, EVP_aes_256_gcm, +EVP_aes_128_ccm, EVP_aes_192_ccm, EVP_aes_256_ccm, EVP_aes_128_cbc_hmac_sha1, EVP_aes_256_cbc_hmac_sha1, -EVP_aes_128_cbc_hmac_sha256, EVP_aes_256_cbc_hmac_sha256 -- EVP cipher routines +EVP_aes_128_cbc_hmac_sha256, EVP_aes_256_cbc_hmac_sha256, +EVP_chacha20, EVP_chacha20_poly1305 - EVP cipher routines =head1 SYNOPSIS +=for comment generic + #include <openssl/evp.h> - void EVP_CIPHER_CTX_init(EVP_CIPHER_CTX *a); + EVP_CIPHER_CTX *EVP_CIPHER_CTX_new(void); + int EVP_CIPHER_CTX_reset(EVP_CIPHER_CTX *ctx); + void EVP_CIPHER_CTX_free(EVP_CIPHER_CTX *ctx); int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, ENGINE *impl, const unsigned char *key, const unsigned char *iv); @@ -76,30 +83,29 @@ EVP_aes_128_cbc_hmac_sha256, EVP_aes_256_cbc_hmac_sha256 int EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *x, int padding); int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *x, int keylen); int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int type, int arg, void *ptr); - int EVP_CIPHER_CTX_cleanup(EVP_CIPHER_CTX *a); const EVP_CIPHER *EVP_get_cipherbyname(const char *name); - #define EVP_get_cipherbynid(a) EVP_get_cipherbyname(OBJ_nid2sn(a)) - #define EVP_get_cipherbyobj(a) EVP_get_cipherbynid(OBJ_obj2nid(a)) - - #define EVP_CIPHER_nid(e) ((e)->nid) - #define EVP_CIPHER_block_size(e) ((e)->block_size) - #define EVP_CIPHER_key_length(e) ((e)->key_len) - #define EVP_CIPHER_iv_length(e) ((e)->iv_len) - #define EVP_CIPHER_flags(e) ((e)->flags) - #define EVP_CIPHER_mode(e) ((e)->flags) & EVP_CIPH_MODE) + const EVP_CIPHER *EVP_get_cipherbynid(int nid); + const EVP_CIPHER *EVP_get_cipherbyobj(const ASN1_OBJECT *a); + + int EVP_CIPHER_nid(const EVP_CIPHER *e); + int EVP_CIPHER_block_size(const EVP_CIPHER *e); + int EVP_CIPHER_key_length(const EVP_CIPHER *e) + int EVP_CIPHER_key_length(const EVP_CIPHER *e); + int EVP_CIPHER_iv_length(const EVP_CIPHER *e); + unsigned long EVP_CIPHER_flags(const EVP_CIPHER *e); + unsigned long EVP_CIPHER_mode(const EVP_CIPHER *e); int EVP_CIPHER_type(const EVP_CIPHER *ctx); - #define EVP_CIPHER_CTX_cipher(e) ((e)->cipher) - #define EVP_CIPHER_CTX_nid(e) ((e)->cipher->nid) - #define EVP_CIPHER_CTX_block_size(e) ((e)->cipher->block_size) - #define EVP_CIPHER_CTX_key_length(e) ((e)->key_len) - #define EVP_CIPHER_CTX_iv_length(e) ((e)->cipher->iv_len) - #define EVP_CIPHER_CTX_get_app_data(e) ((e)->app_data) - #define EVP_CIPHER_CTX_set_app_data(e,d) ((e)->app_data=(char *)(d)) - #define EVP_CIPHER_CTX_type(c) EVP_CIPHER_type(EVP_CIPHER_CTX_cipher(c)) - #define EVP_CIPHER_CTX_flags(e) ((e)->cipher->flags) - #define EVP_CIPHER_CTX_mode(e) ((e)->cipher->flags & EVP_CIPH_MODE) + const EVP_CIPHER *EVP_CIPHER_CTX_cipher(const EVP_CIPHER_CTX *ctx); + int EVP_CIPHER_CTX_nid(const EVP_CIPHER_CTX *ctx); + int EVP_CIPHER_CTX_block_size(const EVP_CIPHER_CTX *ctx); + int EVP_CIPHER_CTX_key_length(const EVP_CIPHER_CTX *ctx); + int EVP_CIPHER_CTX_iv_length(const EVP_CIPHER_CTX *ctx); + void *EVP_CIPHER_CTX_get_app_data(const EVP_CIPHER_CTX *ctx); + void EVP_CIPHER_CTX_set_app_data(const EVP_CIPHER_CTX *ctx, void *data); + int EVP_CIPHER_CTX_type(const EVP_CIPHER_CTX *ctx); + int EVP_CIPHER_CTX_mode(const EVP_CIPHER_CTX *ctx); int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type); int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type); @@ -109,10 +115,16 @@ EVP_aes_128_cbc_hmac_sha256, EVP_aes_256_cbc_hmac_sha256 The EVP cipher routines are a high level interface to certain symmetric ciphers. -EVP_CIPHER_CTX_init() initializes cipher contex B<ctx>. +EVP_CIPHER_CTX_new() creates a cipher context. + +EVP_CIPHER_CTX_free() clears all information from a cipher context +and free up any allocated memory associate with it, including B<ctx> +itself. This function should be called after all operations using a +cipher are complete so sensitive information does not remain in +memory. EVP_EncryptInit_ex() sets up cipher context B<ctx> for encryption -with cipher B<type> from ENGINE B<impl>. B<ctx> must be initialized +with cipher B<type> from ENGINE B<impl>. B<ctx> must be created before calling this function. B<type> is normally supplied by a function such as EVP_aes_256_cbc(). If B<impl> is NULL then the default implementation is used. B<key> is the symmetric key to use @@ -129,11 +141,14 @@ multiple times to encrypt successive blocks of data. The amount of data written depends on the block alignment of the encrypted data: as a result the amount of data written may be anything from zero bytes to (inl + cipher_block_size - 1) so B<out> should contain sufficient -room. The actual number of bytes written is placed in B<outl>. +room. The actual number of bytes written is placed in B<outl>. It also +checks if B<in> and B<out> are partially overlapping, and if they are +0 is returned to indicate failure. If padding is enabled (the default) then EVP_EncryptFinal_ex() encrypts the "final" data, that is any data that remains in a partial block. -It uses L<standard block padding|/NOTES> (aka PKCS padding). The encrypted +It uses standard block padding (aka PKCS padding) as described in +the NOTES section, below. The encrypted final data is written to B<out> which should have sufficient space for one cipher block. The number of bytes written is placed in B<outl>. After this function is called the encryption operation is finished and no further @@ -141,7 +156,7 @@ calls to EVP_EncryptUpdate() should be made. If padding is disabled then EVP_EncryptFinal_ex() will not encrypt any more data and it will return an error if any data remains in a partial block: -that is if the total data length is not a multiple of the block size. +that is if the total data length is not a multiple of the block size. EVP_DecryptInit_ex(), EVP_DecryptUpdate() and EVP_DecryptFinal_ex() are the corresponding decryption operations. EVP_DecryptFinal() will return an @@ -158,13 +173,14 @@ performed depends on the value of the B<enc> parameter. It should be set to 1 for encryption, 0 for decryption and -1 to leave the value unchanged (the actual value of 'enc' being supplied in a previous call). -EVP_CIPHER_CTX_cleanup() clears all information from a cipher context -and free up any allocated memory associate with it. It should be called -after all operations using a cipher are complete so sensitive information -does not remain in memory. +EVP_CIPHER_CTX_reset() clears all information from a cipher context +and free up any allocated memory associate with it, except the B<ctx> +itself. This function should be called anytime B<ctx> is to be reused +for another EVP_CipherInit() / EVP_CipherUpdate() / EVP_CipherFinal() +series of calls. EVP_EncryptInit(), EVP_DecryptInit() and EVP_CipherInit() behave in a -similar way to EVP_EncryptInit_ex(), EVP_DecryptInit_ex and +similar way to EVP_EncryptInit_ex(), EVP_DecryptInit_ex() and EVP_CipherInit_ex() except the B<ctx> parameter does not need to be initialized and they always use the default cipher implementation. @@ -183,12 +199,14 @@ passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX> structure. The actual NID value is an internal value which may not have a corresponding OBJECT IDENTIFIER. -EVP_CIPHER_CTX_set_padding() enables or disables padding. By default -encryption operations are padded using standard block padding and the -padding is checked and removed when decrypting. If the B<pad> parameter -is zero then no padding is performed, the total amount of data encrypted -or decrypted must then be a multiple of the block size or an error will -occur. +EVP_CIPHER_CTX_set_padding() enables or disables padding. This +function should be called after the context is set up for encryption +or decryption with EVP_EncryptInit_ex(), EVP_DecryptInit_ex() or +EVP_CipherInit_ex(). By default encryption operations are padded using +standard block padding and the padding is checked and removed when +decrypting. If the B<pad> parameter is zero then no padding is +performed, the total amount of data encrypted or decrypted must then +be a multiple of the block size or an error will occur. EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key length of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX> @@ -208,7 +226,7 @@ B<EVP_MAX_IV_LENGTH> is the maximum IV length for all ciphers. EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block size of a cipher when passed an B<EVP_CIPHER> or B<EVP_CIPHER_CTX> -structure. The constant B<EVP_MAX_IV_LENGTH> is also the maximum block +structure. The constant B<EVP_MAX_BLOCK_LENGTH> is also the maximum block length for all ciphers. EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the type of the passed @@ -249,6 +267,9 @@ and set. =head1 RETURN VALUES +EVP_CIPHER_CTX_new() returns a pointer to a newly created +B<EVP_CIPHER_CTX> for success and B<NULL> for failure. + EVP_EncryptInit_ex(), EVP_EncryptUpdate() and EVP_EncryptFinal_ex() return 1 for success and 0 for failure. @@ -258,7 +279,7 @@ EVP_DecryptFinal_ex() returns 0 if the decrypt failed or 1 for success. EVP_CipherInit_ex() and EVP_CipherUpdate() return 1 for success and 0 for failure. EVP_CipherFinal_ex() returns 0 for a decryption failure or 1 for success. -EVP_CIPHER_CTX_cleanup() returns 1 for success and 0 for failure. +EVP_CIPHER_CTX_reset() returns 1 for success and 0 for failure. EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj() return an B<EVP_CIPHER> structure or NULL on error. @@ -281,8 +302,8 @@ OBJECT IDENTIFIER or NID_undef if it has no defined OBJECT IDENTIFIER. EVP_CIPHER_CTX_cipher() returns an B<EVP_CIPHER> structure. -EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return 1 for -success or zero for failure. +EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return greater +than zero for success and zero or a negative number. =head1 CIPHER LISTING @@ -294,84 +315,114 @@ All algorithms have a fixed key length unless otherwise stated. Null cipher: does nothing. -=item EVP_des_cbc(void), EVP_des_ecb(void), EVP_des_cfb(void), EVP_des_ofb(void) +=item EVP_aes_128_cbc(), EVP_aes_128_ecb(), EVP_aes_128_cfb(), EVP_aes_128_ofb() + +AES with a 128-bit key in CBC, ECB, CFB and OFB modes respectively. + +=item EVP_aes_192_cbc(), EVP_aes_192_ecb(), EVP_aes_192_cfb(), EVP_aes_192_ofb() + +AES with a 192-bit key in CBC, ECB, CFB and OFB modes respectively. + +=item EVP_aes_256_cbc(), EVP_aes_256_ecb(), EVP_aes_256_cfb(), EVP_aes_256_ofb() -DES in CBC, ECB, CFB and OFB modes respectively. +AES with a 256-bit key in CBC, ECB, CFB and OFB modes respectively. -=item EVP_des_ede_cbc(void), EVP_des_ede(), EVP_des_ede_ofb(void), EVP_des_ede_cfb(void) +=item EVP_des_cbc(), EVP_des_ecb(), EVP_des_cfb(), EVP_des_ofb() + +DES in CBC, ECB, CFB and OFB modes respectively. + +=item EVP_des_ede_cbc(), EVP_des_ede(), EVP_des_ede_ofb(), EVP_des_ede_cfb() Two key triple DES in CBC, ECB, CFB and OFB modes respectively. -=item EVP_des_ede3_cbc(void), EVP_des_ede3(), EVP_des_ede3_ofb(void), EVP_des_ede3_cfb(void) +=item EVP_des_ede3_cbc(), EVP_des_ede3(), EVP_des_ede3_ofb(), EVP_des_ede3_cfb() Three key triple DES in CBC, ECB, CFB and OFB modes respectively. -=item EVP_desx_cbc(void) +=item EVP_desx_cbc() DESX algorithm in CBC mode. -=item EVP_rc4(void) +=item EVP_rc4() RC4 stream cipher. This is a variable key length cipher with default key length 128 bits. -=item EVP_rc4_40(void) +=item EVP_rc4_40() -RC4 stream cipher with 40 bit key length. This is obsolete and new code should use EVP_rc4() +RC4 stream cipher with 40 bit key length. +This is obsolete and new code should use EVP_rc4() and the EVP_CIPHER_CTX_set_key_length() function. -=item EVP_idea_cbc() EVP_idea_ecb(void), EVP_idea_cfb(void), EVP_idea_ofb(void), EVP_idea_cbc(void) +=item EVP_idea_cbc() EVP_idea_ecb(), EVP_idea_cfb(), EVP_idea_ofb() IDEA encryption algorithm in CBC, ECB, CFB and OFB modes respectively. -=item EVP_rc2_cbc(void), EVP_rc2_ecb(void), EVP_rc2_cfb(void), EVP_rc2_ofb(void) +=item EVP_rc2_cbc(), EVP_rc2_ecb(), EVP_rc2_cfb(), EVP_rc2_ofb() RC2 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key length cipher with an additional parameter called "effective key bits" or "effective key length". By default both are set to 128 bits. -=item EVP_rc2_40_cbc(void), EVP_rc2_64_cbc(void) +=item EVP_rc2_40_cbc(), EVP_rc2_64_cbc() RC2 algorithm in CBC mode with a default key length and effective key length of 40 and 64 bits. These are obsolete and new code should use EVP_rc2_cbc(), EVP_CIPHER_CTX_set_key_length() and EVP_CIPHER_CTX_ctrl() to set the key length and effective key length. -=item EVP_bf_cbc(void), EVP_bf_ecb(void), EVP_bf_cfb(void), EVP_bf_ofb(void); +=item EVP_bf_cbc(), EVP_bf_ecb(), EVP_bf_cfb(), EVP_bf_ofb() Blowfish encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key length cipher. -=item EVP_cast5_cbc(void), EVP_cast5_ecb(void), EVP_cast5_cfb(void), EVP_cast5_ofb(void) +=item EVP_cast5_cbc(), EVP_cast5_ecb(), EVP_cast5_cfb(), EVP_cast5_ofb() CAST encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key length cipher. -=item EVP_rc5_32_12_16_cbc(void), EVP_rc5_32_12_16_ecb(void), EVP_rc5_32_12_16_cfb(void), EVP_rc5_32_12_16_ofb(void) +=item EVP_rc5_32_12_16_cbc(), EVP_rc5_32_12_16_ecb(), EVP_rc5_32_12_16_cfb(), EVP_rc5_32_12_16_ofb() RC5 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key length cipher with an additional "number of rounds" parameter. By default the key length is set to 128 bits and 12 rounds. -=item EVP_aes_128_gcm(void), EVP_aes_192_gcm(void), EVP_aes_256_gcm(void) +=item EVP_aes_128_gcm(), EVP_aes_192_gcm(), EVP_aes_256_gcm() AES Galois Counter Mode (GCM) for 128, 192 and 256 bit keys respectively. These ciphers require additional control operations to function correctly: see -L<GCM mode> section below for details. +the L</GCM and OCB Modes> section below for details. + +=item EVP_aes_128_ocb(void), EVP_aes_192_ocb(void), EVP_aes_256_ocb(void) + +Offset Codebook Mode (OCB) for 128, 192 and 256 bit keys respectively. +These ciphers require additional control operations to function correctly: see +the L</GCM and OCB Modes> section below for details. -=item EVP_aes_128_ccm(void), EVP_aes_192_ccm(void), EVP_aes_256_ccm(void) +=item EVP_aes_128_ccm(), EVP_aes_192_ccm(), EVP_aes_256_ccm() AES Counter with CBC-MAC Mode (CCM) for 128, 192 and 256 bit keys respectively. These ciphers require additional control operations to function correctly: see CCM mode section below for details. +=item EVP_chacha20() + +The ChaCha20 stream cipher. The key length is 256 bits, the IV is 96 bits long. + +=item EVP_chacha20_poly1305() + +Authenticated encryption with ChaCha20-Poly1305. Like EVP_chacha20() the key is +256 bits and the IV is 96 bits. This supports additional authenticated +data (AAD) and produces a 128 bit authentication tag. See the +L</GCM and OCB Modes> section for more information. + =back -=head1 GCM Mode +=head1 GCM and OCB Modes -For GCM mode ciphers the behaviour of the EVP interface is subtly altered and -several GCM specific ctrl operations are supported. +For GCM and OCB mode ciphers the behaviour of the EVP interface is subtly +altered and several additional ctrl operations are supported. To specify any additional authenticated data (AAD) a call to EVP_CipherUpdate(), -EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made with the output +EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made with the output parameter B<out> set to B<NULL>. When decrypting the return value of EVP_DecryptFinal() or EVP_CipherFinal() @@ -379,39 +430,47 @@ indicates if the operation was successful. If it does not indicate success the authentication operation has failed and any output data B<MUST NOT> be used as it is corrupted. -The following ctrls are supported in GCM mode: +The following ctrls are supported in both GCM and OCB modes: + + EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL); - EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_IVLEN, ivlen, NULL); +Sets the IV length: this call can only be made before specifying an IV. If +not called a default IV length is used. For GCM AES and OCB AES the default is +12 (i.e. 96 bits). For OCB mode the maximum is 15. -Sets the GCM IV length: this call can only be made before specifying an IV. If -not called a default IV length is used (96 bits for AES). - - EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_GET_TAG, taglen, tag); + EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_GET_TAG, taglen, tag); Writes B<taglen> bytes of the tag value to the buffer indicated by B<tag>. This call can only be made when encrypting data and B<after> all data has been -processed (e.g. after an EVP_EncryptFinal() call). +processed (e.g. after an EVP_EncryptFinal() call). For OCB mode the taglen must +either be 16 or the value previously set via EVP_CTRL_OCB_SET_TAGLEN. - EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_TAG, taglen, tag); + EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag); Sets the expected tag to B<taglen> bytes from B<tag>. This call is only legal -when decrypting data. +when decrypting data. For OCB mode the taglen must either be 16 or the value +previously set via EVP_CTRL_AEAD_SET_TAG. + +In OCB mode calling this with B<tag> set to NULL sets the tag length. The tag +length can only be set before specifying an IV. If not called a default tag +length is used. For OCB AES the default is 16 (i.e. 128 bits). This is also the +maximum tag length for OCB. =head1 CCM Mode -The behaviour of CCM mode ciphers is similar to CCM mode but with a few +The behaviour of CCM mode ciphers is similar to GCM mode but with a few additional requirements and different ctrl values. -Like GCM mode any additional authenticated data (AAD) is passed by calling -EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() with the output +Like GCM and OCB modes any additional authenticated data (AAD) is passed by calling +EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() with the output parameter B<out> set to B<NULL>. Additionally the total plaintext or ciphertext length B<MUST> be passed to EVP_CipherUpdate(), EVP_EncryptUpdate() or -EVP_DecryptUpdate() with the output and input parameters (B<in> and B<out>) +EVP_DecryptUpdate() with the output and input parameters (B<in> and B<out>) set to B<NULL> and the length passed in the B<inl> parameter. The following ctrls are supported in CCM mode: - - EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_TAG, taglen, tag); + + EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_TAG, taglen, tag); This call is made to set the expected B<CCM> tag value when decrypting or the length of the tag (with the B<tag> parameter set to NULL) when encrypting. @@ -422,14 +481,12 @@ used (12 for AES). Sets the CCM B<L> value. If not set a default is used (8 for AES). - EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_IVLEN, ivlen, NULL); + EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_AEAD_SET_IVLEN, ivlen, NULL); Sets the CCM nonce (IV) length: this call can only be made before specifying an nonce value. The nonce length is given by B<15 - L> so it is 7 by default for AES. - - =head1 NOTES Where possible the B<EVP> interface to symmetric ciphers should be used in @@ -439,7 +496,7 @@ B<EVP> interface will ensure the use of platform specific cryptographic acceleration such as AES-NI (the low level interfaces do not provide the guarantee). -PKCS padding works by adding B<n> padding bytes of value B<n> to make the total +PKCS padding works by adding B<n> padding bytes of value B<n> to make the total length of the encrypted data a multiple of the block size. Padding is always added so if the data is already a multiple of the block size B<n> will equal the block size. For example if the block size is 8 and 11 bytes are to be @@ -462,6 +519,8 @@ EVP_EncryptFinal_ex(), EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(), EVP_CipherInit_ex() and EVP_CipherFinal_ex() because they can reuse an existing context without allocating and freeing it up on each call. +EVP_get_cipherbynid(), and EVP_get_cipherbyobj() are implemented as macros. + =head1 BUGS For RC5 the number of rounds can currently only be set to 8, 12 or 16. This is @@ -469,7 +528,7 @@ a limitation of the current RC5 code rather than the EVP interface. EVP_MAX_KEY_LENGTH and EVP_MAX_IV_LENGTH only refer to the internal ciphers with default key lengths. If custom ciphers exceed these values the results are -unpredictable. This is because it has become standard practice to define a +unpredictable. This is because it has become standard practice to define a generic key as a fixed unsigned char array containing EVP_MAX_KEY_LENGTH bytes. The ASN1 code is incomplete (and sometimes inaccurate) it has only been tested @@ -480,50 +539,50 @@ for certain common S/MIME ciphers (RC2, DES, triple DES) in CBC mode. Encrypt a string using IDEA: int do_crypt(char *outfile) - { - unsigned char outbuf[1024]; - int outlen, tmplen; - /* Bogus key and IV: we'd normally set these from - * another source. - */ - unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}; - unsigned char iv[] = {1,2,3,4,5,6,7,8}; - char intext[] = "Some Crypto Text"; - EVP_CIPHER_CTX ctx; - FILE *out; - - EVP_CIPHER_CTX_init(&ctx); - EVP_EncryptInit_ex(&ctx, EVP_idea_cbc(), NULL, key, iv); - - if(!EVP_EncryptUpdate(&ctx, outbuf, &outlen, intext, strlen(intext))) - { - /* Error */ - return 0; - } - /* Buffer passed to EVP_EncryptFinal() must be after data just - * encrypted to avoid overwriting it. - */ - if(!EVP_EncryptFinal_ex(&ctx, outbuf + outlen, &tmplen)) - { - /* Error */ - return 0; - } - outlen += tmplen; - EVP_CIPHER_CTX_cleanup(&ctx); - /* Need binary mode for fopen because encrypted data is - * binary data. Also cannot use strlen() on it because - * it wont be null terminated and may contain embedded - * nulls. - */ - out = fopen(outfile, "wb"); - fwrite(outbuf, 1, outlen, out); - fclose(out); - return 1; - } + { + unsigned char outbuf[1024]; + int outlen, tmplen; + /* Bogus key and IV: we'd normally set these from + * another source. + */ + unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}; + unsigned char iv[] = {1,2,3,4,5,6,7,8}; + char intext[] = "Some Crypto Text"; + EVP_CIPHER_CTX *ctx; + FILE *out; + + ctx = EVP_CIPHER_CTX_new(); + EVP_EncryptInit_ex(ctx, EVP_idea_cbc(), NULL, key, iv); + + if(!EVP_EncryptUpdate(ctx, outbuf, &outlen, intext, strlen(intext))) + { + /* Error */ + return 0; + } + /* Buffer passed to EVP_EncryptFinal() must be after data just + * encrypted to avoid overwriting it. + */ + if(!EVP_EncryptFinal_ex(ctx, outbuf + outlen, &tmplen)) + { + /* Error */ + return 0; + } + outlen += tmplen; + EVP_CIPHER_CTX_free(ctx); + /* Need binary mode for fopen because encrypted data is + * binary data. Also cannot use strlen() on it because + * it won't be null terminated and may contain embedded + * nulls. + */ + out = fopen(outfile, "wb"); + fwrite(outbuf, 1, outlen, out); + fclose(out); + return 1; + } The ciphertext from the above example can be decrypted using the B<openssl> utility with the command line (shown on two lines for clarity): - + openssl idea -d <filename -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708 @@ -531,64 +590,72 @@ General encryption and decryption function example using FILE I/O and AES128 with a 128-bit key: int do_crypt(FILE *in, FILE *out, int do_encrypt) - { - /* Allow enough space in output buffer for additional block */ - unsigned char inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH]; - int inlen, outlen; - EVP_CIPHER_CTX ctx; - /* Bogus key and IV: we'd normally set these from - * another source. - */ - unsigned char key[] = "0123456789abcdeF"; - unsigned char iv[] = "1234567887654321"; - - /* Don't set key or IV right away; we want to check lengths */ - EVP_CIPHER_CTX_init(&ctx); - EVP_CipherInit_ex(&ctx, EVP_aes_128_cbc(), NULL, NULL, NULL, - do_encrypt); - OPENSSL_assert(EVP_CIPHER_CTX_key_length(&ctx) == 16); - OPENSSL_assert(EVP_CIPHER_CTX_iv_length(&ctx) == 16); - - /* Now we can set key and IV */ - EVP_CipherInit_ex(&ctx, NULL, NULL, key, iv, do_encrypt); - - for(;;) - { - inlen = fread(inbuf, 1, 1024, in); - if(inlen <= 0) break; - if(!EVP_CipherUpdate(&ctx, outbuf, &outlen, inbuf, inlen)) - { - /* Error */ - EVP_CIPHER_CTX_cleanup(&ctx); - return 0; - } - fwrite(outbuf, 1, outlen, out); - } - if(!EVP_CipherFinal_ex(&ctx, outbuf, &outlen)) - { - /* Error */ - EVP_CIPHER_CTX_cleanup(&ctx); - return 0; - } - fwrite(outbuf, 1, outlen, out); - - EVP_CIPHER_CTX_cleanup(&ctx); - return 1; - } + { + /* Allow enough space in output buffer for additional block */ + unsigned char inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH]; + int inlen, outlen; + EVP_CIPHER_CTX *ctx; + /* Bogus key and IV: we'd normally set these from + * another source. + */ + unsigned char key[] = "0123456789abcdeF"; + unsigned char iv[] = "1234567887654321"; + + /* Don't set key or IV right away; we want to check lengths */ + ctx = EVP_CIPHER_CTX_new(); + EVP_CipherInit_ex(&ctx, EVP_aes_128_cbc(), NULL, NULL, NULL, + do_encrypt); + OPENSSL_assert(EVP_CIPHER_CTX_key_length(ctx) == 16); + OPENSSL_assert(EVP_CIPHER_CTX_iv_length(ctx) == 16); + + /* Now we can set key and IV */ + EVP_CipherInit_ex(ctx, NULL, NULL, key, iv, do_encrypt); + + for(;;) + { + inlen = fread(inbuf, 1, 1024, in); + if (inlen <= 0) break; + if(!EVP_CipherUpdate(ctx, outbuf, &outlen, inbuf, inlen)) + { + /* Error */ + EVP_CIPHER_CTX_free(ctx); + return 0; + } + fwrite(outbuf, 1, outlen, out); + } + if(!EVP_CipherFinal_ex(ctx, outbuf, &outlen)) + { + /* Error */ + EVP_CIPHER_CTX_free(ctx); + return 0; + } + fwrite(outbuf, 1, outlen, out); + + EVP_CIPHER_CTX_free(ctx); + return 1; + } =head1 SEE ALSO -L<evp(3)|evp(3)> +L<evp(7)> =head1 HISTORY -EVP_CIPHER_CTX_init(), EVP_EncryptInit_ex(), EVP_EncryptFinal_ex(), -EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(), EVP_CipherInit_ex(), -EVP_CipherFinal_ex() and EVP_CIPHER_CTX_set_padding() appeared in -OpenSSL 0.9.7. +Support for OCB mode was added in OpenSSL 1.1.0 + +B<EVP_CIPHER_CTX> was made opaque in OpenSSL 1.1.0. As a result, +EVP_CIPHER_CTX_reset() appeared and EVP_CIPHER_CTX_cleanup() +disappeared. EVP_CIPHER_CTX_init() remains as an alias for +EVP_CIPHER_CTX_reset(). + +=head1 COPYRIGHT + +Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. -IDEA appeared in OpenSSL 0.9.7 but was often disabled due to -patent concerns; the last patents expired in 2012. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_MD_meth_new.pod b/deps/openssl/openssl/doc/crypto/EVP_MD_meth_new.pod new file mode 100644 index 0000000000..4dac672260 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/EVP_MD_meth_new.pod @@ -0,0 +1,179 @@ +=pod + +=head1 NAME + +EVP_MD_meth_dup, +EVP_MD_meth_new, EVP_MD_meth_free, EVP_MD_meth_set_input_blocksize, +EVP_MD_meth_set_result_size, EVP_MD_meth_set_app_datasize, +EVP_MD_meth_set_flags, EVP_MD_meth_set_init, EVP_MD_meth_set_update, +EVP_MD_meth_set_final, EVP_MD_meth_set_copy, EVP_MD_meth_set_cleanup, +EVP_MD_meth_set_ctrl, EVP_MD_meth_get_input_blocksize, +EVP_MD_meth_get_result_size, EVP_MD_meth_get_app_datasize, +EVP_MD_meth_get_flags, EVP_MD_meth_get_init, EVP_MD_meth_get_update, +EVP_MD_meth_get_final, EVP_MD_meth_get_copy, EVP_MD_meth_get_cleanup, +EVP_MD_meth_get_ctrl +- Routines to build up EVP_MD methods + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + EVP_MD *EVP_MD_meth_new(int md_type, int pkey_type); + void EVP_MD_meth_free(EVP_MD *md); + EVP_MD *EVP_MD_meth_dup(const EVP_MD *md); + + int EVP_MD_meth_set_input_blocksize(EVP_MD *md, int blocksize); + int EVP_MD_meth_set_result_size(EVP_MD *md, int resultsize); + int EVP_MD_meth_set_app_datasize(EVP_MD *md, int datasize); + int EVP_MD_meth_set_flags(EVP_MD *md, unsigned long flags); + int EVP_MD_meth_set_init(EVP_MD *md, int (*init)(EVP_MD_CTX *ctx)); + int EVP_MD_meth_set_update(EVP_MD *md, int (*update)(EVP_MD_CTX *ctx, + const void *data, + size_t count)); + int EVP_MD_meth_set_final(EVP_MD *md, int (*final)(EVP_MD_CTX *ctx, + unsigned char *md)); + int EVP_MD_meth_set_copy(EVP_MD *md, int (*copy)(EVP_MD_CTX *to, + const EVP_MD_CTX *from)); + int EVP_MD_meth_set_cleanup(EVP_MD *md, int (*cleanup)(EVP_MD_CTX *ctx)); + int EVP_MD_meth_set_ctrl(EVP_MD *md, int (*ctrl)(EVP_MD_CTX *ctx, int cmd, + int p1, void *p2)); + + int EVP_MD_meth_get_input_blocksize(const EVP_MD *md); + int EVP_MD_meth_get_result_size(const EVP_MD *md); + int EVP_MD_meth_get_app_datasize(const EVP_MD *md); + unsigned long EVP_MD_meth_get_flags(const EVP_MD *md); + int (*EVP_MD_meth_get_init(const EVP_MD *md))(EVP_MD_CTX *ctx); + int (*EVP_MD_meth_get_update(const EVP_MD *md))(EVP_MD_CTX *ctx, + const void *data, + size_t count); + int (*EVP_MD_meth_get_final(const EVP_MD *md))(EVP_MD_CTX *ctx, + unsigned char *md); + int (*EVP_MD_meth_get_copy(const EVP_MD *md))(EVP_MD_CTX *to, + const EVP_MD_CTX *from); + int (*EVP_MD_meth_get_cleanup(const EVP_MD *md))(EVP_MD_CTX *ctx); + int (*EVP_MD_meth_get_ctrl(const EVP_MD *md))(EVP_MD_CTX *ctx, int cmd, + int p1, void *p2); + +=head1 DESCRIPTION + +The B<EVP_MD> type is a structure for digest method implementation. +It can also have associated public/private key signing and verifying +routines. + +EVP_MD_meth_new() creates a new B<EVP_MD> structure. + +EVP_MD_meth_dup() creates a copy of B<md>. + +EVP_MD_meth_free() destroys a B<EVP_MD> structure. + +EVP_MD_meth_set_input_blocksize() sets the internal input block size +for the method B<md> to B<blocksize> bytes. + +EVP_MD_meth_set_result_size() sets the size of the result that the +digest method in B<md> is expected to produce to B<resultsize> bytes. + +The digest method may have its own private data, which OpenSSL will +allocate for it. EVP_MD_meth_set_app_datasize() should be used to +set the size for it to B<datasize>. + +EVP_MD_meth_set_flags() sets the flags to describe optional +behaviours in the particular B<md>. Several flags can be or'd +together. The available flags are: + +=over 4 + +=item EVP_MD_FLAG_ONESHOT + +This digest method can only handles one block of input. + +=item EVP_MD_FLAG_DIGALGID_NULL + +When setting up a DigestAlgorithmIdentifier, this flag will have the +parameter set to NULL by default. Use this for PKCS#1. I<Note: if +combined with EVP_MD_FLAG_DIGALGID_ABSENT, the latter will override.> + +=item EVP_MD_FLAG_DIGALGID_ABSENT + +When setting up a DigestAlgorithmIdentifier, this flag will have the +parameter be left absent by default. I<Note: if combined with +EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.> + +=item EVP_MD_FLAG_DIGALGID_CUSTOM + +Custom DigestAlgorithmIdentifier handling via ctrl, with +B<EVP_MD_FLAG_DIGALGID_ABSENT> as default. I<Note: if combined with +EVP_MD_FLAG_DIGALGID_NULL, the latter will be overridden.> +Currently unused. + +=back + +EVP_MD_meth_set_init() sets the digest init function for B<md>. +The digest init function is called by EVP_DigestInit(), +EVP_DigestInit_ex(), EVP_SignInit, EVP_SignInit_ex(), EVP_VerifyInit() +and EVP_VerifyInit_ex(). + +EVP_MD_meth_set_update() sets the digest update function for B<md>. +The digest update function is called by EVP_DigestUpdate(), +EVP_SignUpdate(). + +EVP_MD_meth_set_final() sets the digest final function for B<md>. +The digest final function is called by EVP_DigestFinal(), +EVP_DigestFinal_ex(), EVP_SignFinal() and EVP_VerifyFinal(). + +EVP_MD_meth_set_copy() sets the function for B<md> to do extra +computations after the method's private data structure has been copied +from one B<EVP_MD_CTX> to another. If all that's needed is to copy +the data, there is no need for this copy function. +Note that the copy function is passed two B<EVP_MD_CTX *>, the private +data structure is then available with EVP_MD_CTX_md_data(). +This copy function is called by EVP_MD_CTX_copy() and +EVP_MD_CTX_copy_ex(). + +EVP_MD_meth_set_cleanup() sets the function for B<md> to do extra +cleanup before the method's private data structure is cleaned out and +freed. +Note that the cleanup function is passed a B<EVP_MD_CTX *>, the +private data structure is then available with EVP_MD_CTX_md_data(). +This cleanup function is called by EVP_MD_CTX_reset() and +EVP_MD_CTX_free(). + +EVP_MD_meth_set_ctrl() sets the control function for B<md>. + +EVP_MD_meth_get_input_blocksize(), EVP_MD_meth_get_result_size(), +EVP_MD_meth_get_app_datasize(), EVP_MD_meth_get_flags(), +EVP_MD_meth_get_init(), EVP_MD_meth_get_update(), +EVP_MD_meth_get_final(), EVP_MD_meth_get_copy(), +EVP_MD_meth_get_cleanup() and EVP_MD_meth_get_ctrl() are all used +to retrieve the method data given with the EVP_MD_meth_set_*() +functions above. + +=head1 RETURN VALUES + +EVP_MD_meth_new() and EVP_MD_meth_dup() return a pointer to a newly +created B<EVP_MD>, or NULL on failure. +All EVP_MD_meth_set_*() functions return 1. +EVP_MD_get_input_blocksize(), EVP_MD_meth_get_result_size(), +EVP_MD_meth_get_app_datasize() and EVP_MD_meth_get_flags() return the +indicated sizes or flags. +All other EVP_CIPHER_meth_get_*() functions return pointers to their +respective B<md> function. + +=head1 SEE ALSO + +L<EVP_DigestInit(3)>, L<EVP_SignInit(3)>, L<EVP_VerifyInit(3)> + +=head1 HISTORY + +The B<EVP_MD> structure was openly available in OpenSSL before version +1.1.0. The functions described here were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2015-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_OpenInit.pod b/deps/openssl/openssl/doc/crypto/EVP_OpenInit.pod index 2e710da945..ff84490a42 100644 --- a/deps/openssl/openssl/doc/crypto/EVP_OpenInit.pod +++ b/deps/openssl/openssl/doc/crypto/EVP_OpenInit.pod @@ -8,8 +8,8 @@ EVP_OpenInit, EVP_OpenUpdate, EVP_OpenFinal - EVP envelope decryption #include <openssl/evp.h> - int EVP_OpenInit(EVP_CIPHER_CTX *ctx,EVP_CIPHER *type,unsigned char *ek, - int ekl,unsigned char *iv,EVP_PKEY *priv); + int EVP_OpenInit(EVP_CIPHER_CTX *ctx, EVP_CIPHER *type, unsigned char *ek, + int ekl, unsigned char *iv, EVP_PKEY *priv); int EVP_OpenUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl, unsigned char *in, int inl); int EVP_OpenFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, @@ -27,8 +27,8 @@ B<ekl> bytes passed in the B<ek> parameter using the private key B<priv>. The IV is supplied in the B<iv> parameter. EVP_OpenUpdate() and EVP_OpenFinal() have exactly the same properties -as the EVP_DecryptUpdate() and EVP_DecryptFinal() routines, as -documented on the L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> manual +as the EVP_DecryptUpdate() and EVP_DecryptFinal() routines, as +documented on the L<EVP_EncryptInit(3)> manual page. =head1 NOTES @@ -54,10 +54,17 @@ EVP_OpenFinal() returns 0 if the decrypt failed or 1 for success. =head1 SEE ALSO -L<evp(3)|evp(3)>, L<rand(3)|rand(3)>, -L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>, -L<EVP_SealInit(3)|EVP_SealInit(3)> +L<evp(3)>, L<rand(3)>, +L<EVP_EncryptInit(3)>, +L<EVP_SealInit(3)> -=head1 HISTORY +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_PKEY_ASN1_METHOD.pod b/deps/openssl/openssl/doc/crypto/EVP_PKEY_ASN1_METHOD.pod new file mode 100644 index 0000000000..0eece53cf6 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/EVP_PKEY_ASN1_METHOD.pod @@ -0,0 +1,358 @@ +=pod + +=head1 NAME + +EVP_PKEY_ASN1_METHOD, +EVP_PKEY_asn1_new, +EVP_PKEY_asn1_copy, +EVP_PKEY_asn1_free, +EVP_PKEY_asn1_add0, +EVP_PKEY_asn1_add_alias, +EVP_PKEY_asn1_set_public, +EVP_PKEY_asn1_set_private, +EVP_PKEY_asn1_set_param, +EVP_PKEY_asn1_set_free, +EVP_PKEY_asn1_set_ctrl, +EVP_PKEY_asn1_set_item, +EVP_PKEY_asn1_set_security_bits, +EVP_PKEY_get0_asn1 +- manipulating and registering EVP_PKEY_ASN1_METHOD structure + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + typedef struct evp_pkey_asn1_method_st EVP_PKEY_ASN1_METHOD; + + EVP_PKEY_ASN1_METHOD *EVP_PKEY_asn1_new(int id, int flags, + const char *pem_str, + const char *info); + void EVP_PKEY_asn1_copy(EVP_PKEY_ASN1_METHOD *dst, + const EVP_PKEY_ASN1_METHOD *src); + void EVP_PKEY_asn1_free(EVP_PKEY_ASN1_METHOD *ameth); + int EVP_PKEY_asn1_add0(const EVP_PKEY_ASN1_METHOD *ameth); + int EVP_PKEY_asn1_add_alias(int to, int from); + + void EVP_PKEY_asn1_set_public(EVP_PKEY_ASN1_METHOD *ameth, + int (*pub_decode) (EVP_PKEY *pk, + X509_PUBKEY *pub), + int (*pub_encode) (X509_PUBKEY *pub, + const EVP_PKEY *pk), + int (*pub_cmp) (const EVP_PKEY *a, + const EVP_PKEY *b), + int (*pub_print) (BIO *out, + const EVP_PKEY *pkey, + int indent, ASN1_PCTX *pctx), + int (*pkey_size) (const EVP_PKEY *pk), + int (*pkey_bits) (const EVP_PKEY *pk)); + void EVP_PKEY_asn1_set_private(EVP_PKEY_ASN1_METHOD *ameth, + int (*priv_decode) (EVP_PKEY *pk, + const PKCS8_PRIV_KEY_INFO + *p8inf), + int (*priv_encode) (PKCS8_PRIV_KEY_INFO *p8, + const EVP_PKEY *pk), + int (*priv_print) (BIO *out, + const EVP_PKEY *pkey, + int indent, + ASN1_PCTX *pctx)); + void EVP_PKEY_asn1_set_param(EVP_PKEY_ASN1_METHOD *ameth, + int (*param_decode) (EVP_PKEY *pkey, + const unsigned char **pder, + int derlen), + int (*param_encode) (const EVP_PKEY *pkey, + unsigned char **pder), + int (*param_missing) (const EVP_PKEY *pk), + int (*param_copy) (EVP_PKEY *to, + const EVP_PKEY *from), + int (*param_cmp) (const EVP_PKEY *a, + const EVP_PKEY *b), + int (*param_print) (BIO *out, + const EVP_PKEY *pkey, + int indent, + ASN1_PCTX *pctx)); + + void EVP_PKEY_asn1_set_free(EVP_PKEY_ASN1_METHOD *ameth, + void (*pkey_free) (EVP_PKEY *pkey)); + void EVP_PKEY_asn1_set_ctrl(EVP_PKEY_ASN1_METHOD *ameth, + int (*pkey_ctrl) (EVP_PKEY *pkey, int op, + long arg1, void *arg2)); + void EVP_PKEY_asn1_set_item(EVP_PKEY_ASN1_METHOD *ameth, + int (*item_verify) (EVP_MD_CTX *ctx, + const ASN1_ITEM *it, + void *asn, + X509_ALGOR *a, + ASN1_BIT_STRING *sig, + EVP_PKEY *pkey), + int (*item_sign) (EVP_MD_CTX *ctx, + const ASN1_ITEM *it, + void *asn, + X509_ALGOR *alg1, + X509_ALGOR *alg2, + ASN1_BIT_STRING *sig)); + + void EVP_PKEY_asn1_set_security_bits(EVP_PKEY_ASN1_METHOD *ameth, + int (*pkey_security_bits) (const EVP_PKEY + *pk)); + + const EVP_PKEY_ASN1_METHOD *EVP_PKEY_get0_asn1(const EVP_PKEY *pkey); + +=head1 DESCRIPTION + +B<EVP_PKEY_ASN1_METHOD> is a structure which holds a set of ASN.1 +conversion, printing and information methods for a specific public key +algorithm. + +There are two places where the B<EVP_PKEY_ASN1_METHOD> objects are +stored: one is a built-in array representing the standard methods for +different algorithms, and the other one is a stack of user-defined +application-specific methods, which can be manipulated by using +L<EVP_PKEY_asn1_add0(3)>. + +=head2 Methods + +The methods are the underlying implementations of a particular public +key algorithm present by the B<EVP_PKEY> object. + + int (*pub_decode) (EVP_PKEY *pk, X509_PUBKEY *pub); + int (*pub_encode) (X509_PUBKEY *pub, const EVP_PKEY *pk); + int (*pub_cmp) (const EVP_PKEY *a, const EVP_PKEY *b); + int (*pub_print) (BIO *out, const EVP_PKEY *pkey, int indent, + ASN1_PCTX *pctx); + +The pub_decode() and pub_encode() methods are called to decode / +encode B<X509_PUBKEY> ASN.1 parameters to / from B<pk>. +They MUST return 0 on error, 1 on success. +They're called by L<X509_PUBKEY_get0(3)> and L<X509_PUBKEY_set(3)>. + +The pub_cmp() method is called when two public keys are to be +compared. +It MUST return 1 when the keys are equal, 0 otherwise. +It's called by L<EVP_PKEY_cmp(3)>. + +The pub_print() method is called to print a public key in humanly +readable text to B<out>, indented B<indent> spaces. +It MUST return 0 on error, 1 on success. +It's called by L<EVP_PKEY_print_public(3)>. + + int (*priv_decode) (EVP_PKEY *pk, const PKCS8_PRIV_KEY_INFO *p8inf); + int (*priv_encode) (PKCS8_PRIV_KEY_INFO *p8, const EVP_PKEY *pk); + int (*priv_print) (BIO *out, const EVP_PKEY *pkey, int indent, + ASN1_PCTX *pctx); + +The priv_decode() and priv_encode() methods are called to decode / +encode B<PKCS8_PRIV_KEY_INFO> form private key to / from B<pk>. +They MUST return 0 on error, 1 on success. +They're called by L<EVP_PKCS82PKEY(3)> and L<EVP_PKEY2PKCS8(3)>. + +The priv_print() method is called to print a private key in humanly +readable text to B<out>, indented B<indent> spaces. +It MUST return 0 on error, 1 on success. +It's called by L<EVP_PKEY_print_private(3)>. + + int (*pkey_size) (const EVP_PKEY *pk); + int (*pkey_bits) (const EVP_PKEY *pk); + int (*pkey_security_bits) (const EVP_PKEY *pk); + +The pkey_size() method returns the key size in bytes. +It's called by L<EVP_PKEY_size(3)>. + +The pkey_bits() method returns the key size in bits. +It's called by L<EVP_PKEY_bits(3)>. + + int (*param_decode) (EVP_PKEY *pkey, + const unsigned char **pder, int derlen); + int (*param_encode) (const EVP_PKEY *pkey, unsigned char **pder); + int (*param_missing) (const EVP_PKEY *pk); + int (*param_copy) (EVP_PKEY *to, const EVP_PKEY *from); + int (*param_cmp) (const EVP_PKEY *a, const EVP_PKEY *b); + int (*param_print) (BIO *out, const EVP_PKEY *pkey, int indent, + ASN1_PCTX *pctx); + +The param_decode() and param_encode() methods are called to decode / +encode DER formatted parameters to / from B<pk>. +They MUST return 0 on error, 1 on success. +They're called by L<PEM_read_bio_Parameters(3)> and the B<file:> +L<OSSL_STORE_LOADER(3)>. + +The param_missing() method returns 0 if a key parameter is missing, +otherwise 1. +It's called by L<EVP_PKEY_missing_parameters(3)>. + +The param_copy() method copies key parameters from B<from> to B<to>. +It MUST return 0 on error, 1 on success. +It's called by L<EVP_PKEY_copy_parameters(3)>. + +The param_cmp() method compares the parameters of keys B<a> and B<b>. +It MUST return 1 when the keys are equal, 0 when not equal, or a +negative number on error. +It's called by L<EVP_PKEY_cmp_parameters(3)>. + +The param_print() method prints the private key parameters in humanly +readable text to B<out>, indented B<indent> spaces. +It MUST return 0 on error, 1 on success. +It's called by L<EVP_PKEY_print_params(3)>. + + int (*sig_print) (BIO *out, + const X509_ALGOR *sigalg, const ASN1_STRING *sig, + int indent, ASN1_PCTX *pctx); + +The sig_print() method prints a signature in humanly readable text to +B<out>, indented B<indent> spaces. +B<sigalg> contains the exact signature algorithm. +If the signature in B<sig> doesn't correspond to what this method +expects, X509_signature_dump() must be used as a last resort. +It MUST return 0 on error, 1 on success. +It's called by L<X509_signature_print(3)>. + + void (*pkey_free) (EVP_PKEY *pkey); + +The pkey_free() method helps freeing the internals of B<pkey>. +It's called by L<EVP_PKEY_free(3)>, L<EVP_PKEY_set_type(3)>, +L<EVP_PKEY_set_type_str(3)>, and L<EVP_PKEY_assign(3)>. + + int (*pkey_ctrl) (EVP_PKEY *pkey, int op, long arg1, void *arg2); + +The pkey_ctrl() method adds extra algorithm specific control. +It's called by L<EVP_PKEY_get_default_digest_nid(3)>, +L<EVP_PKEY_set1_tls_encodedpoint(3)>, +L<EVP_PKEY_get1_tls_encodedpoint(3)>, L<PKCS7_SIGNER_INFO_set(3)>, +L<PKCS7_RECIP_INFO_set(3)>, ... + + int (*old_priv_decode) (EVP_PKEY *pkey, + const unsigned char **pder, int derlen); + int (*old_priv_encode) (const EVP_PKEY *pkey, unsigned char **pder); + +The old_priv_decode() and old_priv_encode() methods decode / encode +they private key B<pkey> from / to a DER formatted array. +These are exclusively used to help decoding / encoding older (pre +PKCS#8) PEM formatted encrypted private keys. +old_priv_decode() MUST return 0 on error, 1 on success. +old_priv_encode() MUST the return same kind of values as +i2d_PrivateKey(). +They're called by L<d2i_PrivateKey(3)> and L<i2d_PrivateKey(3)>. + + int (*item_verify) (EVP_MD_CTX *ctx, const ASN1_ITEM *it, void *asn, + X509_ALGOR *a, ASN1_BIT_STRING *sig, EVP_PKEY *pkey); + int (*item_sign) (EVP_MD_CTX *ctx, const ASN1_ITEM *it, void *asn, + X509_ALGOR *alg1, X509_ALGOR *alg2, + ASN1_BIT_STRING *sig); + +The item_sign() and item_verify() methods make it possible to have +algorithm specific signatures and verification of them. + +item_sign() MUST return one of: + +=over 4 + +=item <=0 + +error + +=item Z<>1 + +item_sign() did everything, OpenSSL internals just needs to pass the +signature length back. + +=item Z<>2 + +item_sign() did nothing, OpenSSL internal standard routines are +expected to continue with the default signature production. + +=item Z<>3 + +item_sign() set the algorithm identifier B<algor1> and B<algor2>, +OpenSSL internals should just sign using those algorithms. + +=back + +item_verify() MUST return one of: + +=over 4 + +=item <=0 + +error + +=item Z<>1 + +item_sign() did everything, OpenSSL internals just needs to pass the +signature length back. + +=item Z<>2 + +item_sign() did nothing, OpenSSL internal standard routines are +expected to continue with the default signature production. + +=back + +item_verify() and item_sign() are called by L<ASN1_item_verify(3)> and +L<ASN1_item_sign(3)>, and by extension, L<X509_verify(3)>, +L<X509_REQ_verify(3)>, L<X509_sign(3)>, L<X509_REQ_sign(3)>, ... + +=head2 Functions + +EVP_PKEY_asn1_new() creates and returns a new B<EVP_PKEY_ASN1_METHOD> +object, and associates the given B<id>, B<flags>, B<pem_str> and +B<info>. +B<id> is a NID, B<pem_str> is the PEM type string, B<info> is a +descriptive string. +The following B<flags> are supported: + + ASN1_PKEY_SIGPARAM_NULL + +If B<ASN1_PKEY_SIGPARAM_NULL> is set, then the signature algorithm +parameters are given the type B<V_ASN1_NULL> by default, otherwise +they will be given the type B<V_ASN1_UNDEF> (i.e. the parameter is +omitted). +See L<X509_ALGOR_set0(3)> for more information. + +EVP_PKEY_asn1_copy() copies an B<EVP_PKEY_ASN1_METHOD> object from +B<src> to B<dst>. +This function is not thread safe, it's recommended to only use this +when initializing the application. + +EVP_PKEY_asn1_free() frees an existing B<EVP_PKEY_ASN1_METHOD> pointed +by B<ameth>. + +EVP_PKEY_asn1_add0() adds B<ameth> to the user defined stack of +methods unless another B<EVP_PKEY_ASN1_METHOD> with the same NID is +already there. +This function is not thread safe, it's recommended to only use this +when initializing the application. + +EVP_PKEY_asn1_add_alias() creates an alias with the NID B<to> for the +B<EVP_PKEY_ASN1_METHOD> with NID B<from> unless another +B<EVP_PKEY_ASN1_METHOD> with the same NID is already added. +This function is not thread safe, it's recommended to only use this +when initializing the application. + +EVP_PKEY_asn1_set_public(), EVP_PKEY_asn1_set_private(), +EVP_PKEY_asn1_set_param(), EVP_PKEY_asn1_set_free(), +EVP_PKEY_asn1_set_ctrl(), EVP_PKEY_asn1_set_item(), and +EVP_PKEY_asn1_set_security_bits() set the diverse methods of the given +B<EVP_PKEY_ASN1_METHOD> object. + +EVP_PKEY_get0_asn1() finds the B<EVP_PKEY_ASN1_METHOD> associated +with the key B<pkey>. + +=head1 RETURN VALUES + +EVP_PKEY_asn1_new() returns NULL on error, or a pointer to an +B<EVP_PKEY_ASN1_METHOD> object otherwise. + +EVP_PKEY_asn1_add0() and EVP_PKEY_asn1_add_alias() return 0 on error, +or 1 on success. + +EVP_PKEY_get0_asn1() returns NULL on error, or a pointer to a constant +B<EVP_PKEY_ASN1_METHOD> object otherwise. + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_PKEY_CTX_ctrl.pod b/deps/openssl/openssl/doc/crypto/EVP_PKEY_CTX_ctrl.pod index 44b5fdb7f2..a30450bb46 100644 --- a/deps/openssl/openssl/doc/crypto/EVP_PKEY_CTX_ctrl.pod +++ b/deps/openssl/openssl/doc/crypto/EVP_PKEY_CTX_ctrl.pod @@ -2,24 +2,23 @@ =head1 NAME -EVP_PKEY_CTX_ctrl, EVP_PKEY_CTX_ctrl_str, EVP_PKEY_get_default_digest_nid, +EVP_PKEY_CTX_ctrl, EVP_PKEY_CTX_ctrl_str, EVP_PKEY_CTX_set_signature_md, EVP_PKEY_CTX_set_rsa_padding, EVP_PKEY_CTX_set_rsa_pss_saltlen, EVP_PKEY_CTX_set_rsa_rsa_keygen_bits, EVP_PKEY_CTX_set_rsa_keygen_pubexp, EVP_PKEY_CTX_set_dsa_paramgen_bits, EVP_PKEY_CTX_set_dh_paramgen_prime_len, EVP_PKEY_CTX_set_dh_paramgen_generator, -EVP_PKEY_CTX_set_ec_paramgen_curve_nid - algorithm specific control operations +EVP_PKEY_CTX_set_ec_paramgen_curve_nid, +EVP_PKEY_CTX_set_ec_param_enc - algorithm specific control operations =head1 SYNOPSIS #include <openssl/evp.h> int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype, - int cmd, int p1, void *p2); + int cmd, int p1, void *p2); int EVP_PKEY_CTX_ctrl_str(EVP_PKEY_CTX *ctx, const char *type, - const char *value); - - int EVP_PKEY_get_default_digest_nid(EVP_PKEY *pkey, int *pnid); + const char *value); #include <openssl/rsa.h> @@ -39,6 +38,7 @@ EVP_PKEY_CTX_set_ec_paramgen_curve_nid - algorithm specific control operations #include <openssl/ec.h> int EVP_PKEY_CTX_set_ec_paramgen_curve_nid(EVP_PKEY_CTX *ctx, int nid); + int EVP_PKEY_CTX_set_ec_param_enc(EVP_PKEY_CTX *ctx, int param_enc); =head1 DESCRIPTION @@ -68,7 +68,7 @@ The macro EVP_PKEY_CTX_set_rsa_padding() sets the RSA padding mode for B<ctx>. The B<pad> parameter can take the value RSA_PKCS1_PADDING for PKCS#1 padding, RSA_SSLV23_PADDING for SSLv23 padding, RSA_NO_PADDING for no padding, RSA_PKCS1_OAEP_PADDING for OAEP padding (encrypt and decrypt only), -RSA_X931_PADDING for X9.31 padding (signature operations only) and +RSA_X931_PADDING for X9.31 padding (signature operations only) and RSA_PKCS1_PSS_PADDING (sign and verify only). Two RSA padding modes behave differently if EVP_PKEY_CTX_set_signature_md() @@ -78,7 +78,8 @@ to PKCS#1 when signing and this structure is expected (and stripped off) when verifying. If this control is not used with RSA and PKCS#1 padding then the supplied data is used directly and not encapsulated. In the case of X9.31 padding for RSA the algorithm identifier byte is added or checked and removed -if this control is called. If it is not called then the first byte of the plaintext buffer is expected to be the algorithm identifier byte. +if this control is called. If it is not called then the first byte of the plaintext +buffer is expected to be the algorithm identifier byte. The EVP_PKEY_CTX_set_rsa_pss_saltlen() macro sets the RSA PSS salt length to B<len> as its name implies it is only supported for PSS padding. Two special @@ -89,11 +90,11 @@ B<PSS> block structure. If this macro is not called a salt length value of -2 is used by default. The EVP_PKEY_CTX_set_rsa_rsa_keygen_bits() macro sets the RSA key length for -RSA key genration to B<bits>. If not specified 1024 bits is used. +RSA key generation to B<bits>. If not specified 1024 bits is used. The EVP_PKEY_CTX_set_rsa_keygen_pubexp() macro sets the public exponent value for RSA key generation to B<pubexp> currently it should be an odd integer. The -B<pubexp> pointer is used internally by this function so it should not be +B<pubexp> pointer is used internally by this function so it should not be modified or free after the call. If this macro is not called then 65537 is used. The macro EVP_PKEY_CTX_set_dsa_paramgen_bits() sets the number of bits used @@ -109,6 +110,16 @@ for DH parameter generation. If not specified 2 is used. The EVP_PKEY_CTX_set_ec_paramgen_curve_nid() sets the EC curve for EC parameter generation to B<nid>. For EC parameter generation this macro must be called or an error occurs because there is no default curve. +This function can also be called to set the curve explicitly when +generating an EC key. + +The EVP_PKEY_CTX_set_ec_param_enc() sets the EC parameter encoding to +B<param_enc> when generating EC parameters or an EC key. The encoding can be +B<OPENSSL_EC_EXPLICIT_CURVE> for explicit parameters (the default in versions +of OpenSSL before 1.1.0) or B<OPENSSL_EC_NAMED_CURVE> to use named curve form. +For maximum compatibility the named curve form should be used. Note: the +B<OPENSSL_EC_NAMED_CURVE> value was only added to OpenSSL 1.1.0; previous +versions should use 0 instead. =head1 RETURN VALUES @@ -118,17 +129,26 @@ indicates the operation is not supported by the public key algorithm. =head1 SEE ALSO -L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, -L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, -L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, -L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, -L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, -L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>, -L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> -L<EVP_PKEY_keygen(3)|EVP_PKEY_keygen(3)> +L<EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_encrypt(3)>, +L<EVP_PKEY_decrypt(3)>, +L<EVP_PKEY_sign(3)>, +L<EVP_PKEY_verify(3)>, +L<EVP_PKEY_verify_recover(3)>, +L<EVP_PKEY_derive(3)> +L<EVP_PKEY_keygen(3)> =head1 HISTORY These functions were first added to OpenSSL 1.0.0. +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_PKEY_CTX_new.pod b/deps/openssl/openssl/doc/crypto/EVP_PKEY_CTX_new.pod index a9af867580..eff94cd943 100644 --- a/deps/openssl/openssl/doc/crypto/EVP_PKEY_CTX_new.pod +++ b/deps/openssl/openssl/doc/crypto/EVP_PKEY_CTX_new.pod @@ -2,7 +2,7 @@ =head1 NAME -EVP_PKEY_CTX_new, EVP_PKEY_CTX_new_id, EVP_PKEY_CTX_dup, EVP_PKEY_CTX_free - public key algorithm context functions. +EVP_PKEY_CTX_new, EVP_PKEY_CTX_new_id, EVP_PKEY_CTX_dup, EVP_PKEY_CTX_free - public key algorithm context functions =head1 SYNOPSIS @@ -21,11 +21,12 @@ the algorithm specified in B<pkey> and ENGINE B<e>. The EVP_PKEY_CTX_new_id() function allocates public key algorithm context using the algorithm specified by B<id> and ENGINE B<e>. It is normally used when no B<EVP_PKEY> structure is associated with the operations, for example -during parameter generation of key genration for some algorithms. +during parameter generation of key generation for some algorithms. EVP_PKEY_CTX_dup() duplicates the context B<ctx>. EVP_PKEY_CTX_free() frees up the context B<ctx>. +If B<ctx> is NULL, nothing is done. =head1 NOTES @@ -43,10 +44,19 @@ EVP_PKEY_CTX_free() does not return a value. =head1 SEE ALSO -L<EVP_PKEY_new(3)|EVP_PKEY_new(3)> +L<EVP_PKEY_new(3)> =head1 HISTORY These functions were first added to OpenSSL 1.0.0. +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_PKEY_CTX_set_hkdf_md.pod b/deps/openssl/openssl/doc/crypto/EVP_PKEY_CTX_set_hkdf_md.pod new file mode 100644 index 0000000000..61e0eec528 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/EVP_PKEY_CTX_set_hkdf_md.pod @@ -0,0 +1,128 @@ +=pod + +=head1 NAME + +EVP_PKEY_CTX_set_hkdf_md, EVP_PKEY_CTX_set1_hkdf_salt, +EVP_PKEY_CTX_set1_hkdf_key, EVP_PKEY_CTX_add1_hkdf_info - +HMAC-based Extract-and-Expand key derivation algorithm + +=head1 SYNOPSIS + + #include <openssl/kdf.h> + + int EVP_PKEY_CTX_set_hkdf_md(EVP_PKEY_CTX *pctx, const EVP_MD *md); + + int EVP_PKEY_CTX_set1_hkdf_salt(EVP_PKEY_CTX *pctx, unsigned char *salt, + int saltlen); + + int EVP_PKEY_CTX_set1_hkdf_key(EVP_PKEY_CTX *pctx, unsigned char *key, + int keylen); + + int EVP_PKEY_CTX_add1_hkdf_info(EVP_PKEY_CTX *pctx, unsigned char *info, + int infolen); + +=head1 DESCRIPTION + +The EVP_PKEY_HKDF algorithm implements the HKDF key derivation function. +HKDF follows the "extract-then-expand" paradigm, where the KDF logically +consists of two modules. The first stage takes the input keying material +and "extracts" from it a fixed-length pseudorandom key K. The second stage +"expands" the key K into several additional pseudorandom keys (the output +of the KDF). + +EVP_PKEY_set_hkdf_md() sets the message digest associated with the HKDF. + +EVP_PKEY_CTX_set1_hkdf_salt() sets the salt to B<saltlen> bytes of the +buffer B<salt>. Any existing value is replaced. + +EVP_PKEY_CTX_set_hkdf_key() sets the key to B<keylen> bytes of the buffer +B<key>. Any existing value is replaced. + +EVP_PKEY_CTX_add1_hkdf_info() sets the info value to B<infolen> bytes of the +buffer B<info>. If a value is already set, it is appended to the existing +value. + +=head1 STRING CTRLS + +HKDF also supports string based control operations via +L<EVP_PKEY_CTX_ctrl_str(3)>. +The B<type> parameter "md" uses the supplied B<value> as the name of the digest +algorithm to use. +The B<type> parameters "salt", "key" and "info" use the supplied B<value> +parameter as a B<seed>, B<key> or B<info> value. +The names "hexsalt", "hexkey" and "hexinfo" are similar except they take a hex +string which is converted to binary. + +=head1 NOTES + +All these functions are implemented as macros. + +A context for HKDF can be obtained by calling: + + EVP_PKEY_CTX *pctx = EVP_PKEY_new_id(EVP_PKEY_HKDF, NULL); + +The digest, key, salt and info values must be set before a key is derived or +an error occurs. + +The total length of the info buffer cannot exceed 1024 bytes in length: this +should be more than enough for any normal use of HKDF. + +The output length of the KDF is specified via the length parameter to the +L<EVP_PKEY_derive(3)> function. +Since the HKDF output length is variable, passing a B<NULL> buffer as a means +to obtain the requisite length is not meaningful with HKDF. +Instead, the caller must allocate a buffer of the desired length, and pass that +buffer to L<EVP_PKEY_derive(3)> along with (a pointer initialized to) the +desired length. + +Optimised versions of HKDF can be implemented in an ENGINE. + +=head1 RETURN VALUES + +All these functions return 1 for success and 0 or a negative value for failure. +In particular a return value of -2 indicates the operation is not supported by +the public key algorithm. + +=head1 EXAMPLE + +This example derives 10 bytes using SHA-256 with the secret key "secret", +salt value "salt" and info value "label": + + EVP_PKEY_CTX *pctx; + unsigned char out[10]; + size_t outlen = sizeof(out); + pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_HKDF, NULL); + + if (EVP_PKEY_derive_init(pctx) <= 0) + /* Error */ + if (EVP_PKEY_CTX_set_hkdf_md(pctx, EVP_sha256()) <= 0) + /* Error */ + if (EVP_PKEY_CTX_set1_salt(pctx, "salt", 4) <= 0) + /* Error */ + if (EVP_PKEY_CTX_set1_key(pctx, "secret", 6) <= 0) + /* Error */ + if (EVP_PKEY_CTX_add1_hkdf_info(pctx, "label", 6) <= 0) + /* Error */ + if (EVP_PKEY_derive(pctx, out, &outlen) <= 0) + /* Error */ + +=head1 CONFORMING TO + +RFC 5869 + +=head1 SEE ALSO + +L<EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_CTX_ctrl_str(3)>, +L<EVP_PKEY_derive(3)> + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_PKEY_CTX_set_tls1_prf_md.pod b/deps/openssl/openssl/doc/crypto/EVP_PKEY_CTX_set_tls1_prf_md.pod new file mode 100644 index 0000000000..f1f0ae4fbe --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/EVP_PKEY_CTX_set_tls1_prf_md.pod @@ -0,0 +1,108 @@ +=pod + +=head1 NAME + +EVP_PKEY_CTX_set_tls1_prf_md, +EVP_PKEY_CTX_set1_tls1_prf_secret, EVP_PKEY_CTX_add1_tls1_prf_seed - +TLS PRF key derivation algorithm + +=head1 SYNOPSIS + + #include <openssl/kdf.h> + + int EVP_PKEY_CTX_set_tls1_prf_md(EVP_PKEY_CTX *pctx, const EVP_MD *md); + int EVP_PKEY_CTX_set1_tls1_prf_secret(EVP_PKEY_CTX *pctx, + unsigned char *sec, int seclen); + int EVP_PKEY_CTX_add1_tls1_prf_seed(EVP_PKEY_CTX *pctx, + unsigned char *seed, int seedlen); + +=head1 DESCRIPTION + +The B<EVP_PKEY_TLS1_PRF> algorithm implements the PRF key derivation function for +TLS. It has no associated private key and only implements key derivation +using L<EVP_PKEY_derive(3)>. + +EVP_PKEY_set_tls1_prf_md() sets the message digest associated with the +TLS PRF. EVP_md5_sha1() is treated as a special case which uses the PRF +algorithm using both B<MD5> and B<SHA1> as used in TLS 1.0 and 1.1. + +EVP_PKEY_CTX_set_tls1_prf_secret() sets the secret value of the TLS PRF +to B<seclen> bytes of the buffer B<sec>. Any existing secret value is replaced +and any seed is reset. + +EVP_PKEY_CTX_add1_tls1_prf_seed() sets the seed to B<seedlen> bytes of B<seed>. +If a seed is already set it is appended to the existing value. + +=head1 STRING CTRLS + +The TLS PRF also supports string based control operations using +L<EVP_PKEY_CTX_ctrl_str(3)>. +The B<type> parameter "md" uses the supplied B<value> as the name of the digest +algorithm to use. +The B<type> parameters "secret" and "seed" use the supplied B<value> parameter +as a secret or seed value. +The names "hexsecret" and "hexseed" are similar except they take a hex string +which is converted to binary. + +=head1 NOTES + +All these functions are implemented as macros. + +A context for the TLS PRF can be obtained by calling: + + EVP_PKEY_CTX *pctx = EVP_PKEY_new_id(EVP_PKEY_TLS1_PRF, NULL); + +The digest, secret value and seed must be set before a key is derived or an +error occurs. + +The total length of all seeds cannot exceed 1024 bytes in length: this should +be more than enough for any normal use of the TLS PRF. + +The output length of the PRF is specified by the length parameter in the +EVP_PKEY_derive() function. Since the output length is variable, setting +the buffer to B<NULL> is not meaningful for the TLS PRF. + +Optimised versions of the TLS PRF can be implemented in an ENGINE. + +=head1 RETURN VALUES + +All these functions return 1 for success and 0 or a negative value for failure. +In particular a return value of -2 indicates the operation is not supported by +the public key algorithm. + +=head1 EXAMPLE + +This example derives 10 bytes using SHA-256 with the secret key "secret" +and seed value "seed": + + EVP_PKEY_CTX *pctx; + unsigned char out[10]; + size_t outlen = sizeof(out); + pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_TLS1_PRF, NULL); + if (EVP_PKEY_derive_init(pctx) <= 0) + /* Error */ + if (EVP_PKEY_CTX_set_tls1_prf_md(pctx, EVP_sha256()) <= 0) + /* Error */ + if (EVP_PKEY_CTX_set1_tls1_prf_secret(pctx, "secret", 6) <= 0) + /* Error */ + if (EVP_PKEY_CTX_add1_tls1_prf_seed(pctx, "seed", 4) <= 0) + /* Error */ + if (EVP_PKEY_derive(pctx, out, &outlen) <= 0) + /* Error */ + +=head1 SEE ALSO + +L<EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_CTX_ctrl_str(3)>, +L<EVP_PKEY_derive(3)> + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_PKEY_asn1_get_count.pod b/deps/openssl/openssl/doc/crypto/EVP_PKEY_asn1_get_count.pod new file mode 100644 index 0000000000..a190f5e9ab --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/EVP_PKEY_asn1_get_count.pod @@ -0,0 +1,80 @@ +=pod + +=head1 NAME + +EVP_PKEY_asn1_find, +EVP_PKEY_asn1_find_str, +EVP_PKEY_asn1_get_count, +EVP_PKEY_asn1_get0, +EVP_PKEY_asn1_get0_info +- enumerate public key ASN.1 methods + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int EVP_PKEY_asn1_get_count(void); + const EVP_PKEY_ASN1_METHOD *EVP_PKEY_asn1_get0(int idx); + const EVP_PKEY_ASN1_METHOD *EVP_PKEY_asn1_find(ENGINE **pe, int type); + const EVP_PKEY_ASN1_METHOD *EVP_PKEY_asn1_find_str(ENGINE **pe, + const char *str, int len); + int EVP_PKEY_asn1_get0_info(int *ppkey_id, int *pkey_base_id, + int *ppkey_flags, const char **pinfo, + const char **ppem_str, + const EVP_PKEY_ASN1_METHOD *ameth); + +=head1 DESCRIPTION + +EVP_PKEY_asn1_count() returns a count of the number of public key +ASN.1 methods available: it includes standard methods and any methods +added by the application. + +EVP_PKEY_asn1_get0() returns the public key ASN.1 method B<idx>. +The value of B<idx> must be between zero and EVP_PKEY_asn1_get_count() +- 1. + +EVP_PKEY_asn1_find() looks up the B<EVP_PKEY_ASN1_METHOD> with NID +B<type>. +If B<pe> isn't B<NULL>, then it will look up an engine implementing a +B<EVP_PKEY_ASN1_METHOD> for the NID B<type> and return that instead, +and also set B<*pe> to point at the engine that implements it. + +EVP_PKEY_asn1_find_str() looks up the B<EVP_PKEY_ASN1_METHOD> with PEM +type string B<str>. +Just like EVP_PKEY_asn1_find(), if B<pe> isn't B<NULL>, then it will +look up an engine implementing a B<EVP_PKEY_ASN1_METHOD> for the NID +B<type> and return that instead, and also set B<*pe> to point at the +engine that implements it. + +EVP_PKEY_asn1_get0_info() returns the public key ID, base public key +ID (both NIDs), any flags, the method description and PEM type string +associated with the public key ASN.1 method B<*ameth>. + +EVP_PKEY_asn1_count(), EVP_PKEY_asn1_get0(), EVP_PKEY_asn1_find() and +EVP_PKEY_asn1_find_str() are not thread safe, but as long as all +B<EVP_PKEY_ASN1_METHOD> objects are added before the application gets +threaded, using them is safe. See L<EVP_PKEY_asn1_add0(3)>. + +=head1 RETURN VALUES + +EVP_PKEY_asn1_count() returns the number of available public key methods. + +EVP_PKEY_asn1_get0() return a public key method or B<NULL> if B<idx> is +out of range. + +EVP_PKEY_asn1_get0_info() returns 0 on failure, 1 on success. + +=head1 SEE ALSO + +L<EVP_PKEY_asn1_new(3)>, L<EVP_PKEY_asn1_add0(3)> + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_PKEY_cmp.pod b/deps/openssl/openssl/doc/crypto/EVP_PKEY_cmp.pod index f8e7ff1039..270d635ce2 100644 --- a/deps/openssl/openssl/doc/crypto/EVP_PKEY_cmp.pod +++ b/deps/openssl/openssl/doc/crypto/EVP_PKEY_cmp.pod @@ -2,7 +2,8 @@ =head1 NAME -EVP_PKEY_copy_parameters, EVP_PKEY_missing_parameters, EVP_PKEY_cmp_parameters, EVP_PKEY_cmp - public key parameter and comparison functions +EVP_PKEY_copy_parameters, EVP_PKEY_missing_parameters, EVP_PKEY_cmp_parameters, +EVP_PKEY_cmp - public key parameter and comparison functions =head1 SYNOPSIS @@ -28,7 +29,7 @@ in B<from> and B<to> are both present and match this function has no effect. The function EVP_PKEY_cmp_parameters() compares the parameters of keys B<a> and B<b>. -The function EVP_PKEY_cmp() compares the public key components and paramters +The function EVP_PKEY_cmp() compares the public key components and parameters (if present) of keys B<a> and B<b>. =head1 NOTES @@ -57,7 +58,16 @@ keys match, 0 if they don't match, -1 if the key types are different and =head1 SEE ALSO -L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, -L<EVP_PKEY_keygen(3)|EVP_PKEY_keygen(3)> +L<EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_keygen(3)> + +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_PKEY_decrypt.pod b/deps/openssl/openssl/doc/crypto/EVP_PKEY_decrypt.pod index 847983237b..ca732ed0f9 100644 --- a/deps/openssl/openssl/doc/crypto/EVP_PKEY_decrypt.pod +++ b/deps/openssl/openssl/doc/crypto/EVP_PKEY_decrypt.pod @@ -10,8 +10,8 @@ EVP_PKEY_decrypt_init, EVP_PKEY_decrypt - decrypt using a public key algorithm int EVP_PKEY_decrypt_init(EVP_PKEY_CTX *ctx); int EVP_PKEY_decrypt(EVP_PKEY_CTX *ctx, - unsigned char *out, size_t *outlen, - const unsigned char *in, size_t inlen); + unsigned char *out, size_t *outlen, + const unsigned char *in, size_t inlen); =head1 DESCRIPTION @@ -50,44 +50,53 @@ Decrypt data using OAEP (for RSA keys): EVP_PKEY_CTX *ctx; unsigned char *out, *in; - size_t outlen, inlen; + size_t outlen, inlen; EVP_PKEY *key; /* NB: assumes key in, inlen are already set up * and that key is an RSA private key */ ctx = EVP_PKEY_CTX_new(key); if (!ctx) - /* Error occurred */ + /* Error occurred */ if (EVP_PKEY_decrypt_init(ctx) <= 0) - /* Error */ + /* Error */ if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_OAEP_PADDING) <= 0) - /* Error */ + /* Error */ /* Determine buffer length */ if (EVP_PKEY_decrypt(ctx, NULL, &outlen, in, inlen) <= 0) - /* Error */ + /* Error */ out = OPENSSL_malloc(outlen); if (!out) - /* malloc failure */ - + /* malloc failure */ + if (EVP_PKEY_decrypt(ctx, out, &outlen, in, inlen) <= 0) - /* Error */ + /* Error */ /* Decrypted data is outlen bytes written to buffer out */ =head1 SEE ALSO -L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, -L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, -L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, -L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, -L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>, -L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> +L<EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_encrypt(3)>, +L<EVP_PKEY_sign(3)>, +L<EVP_PKEY_verify(3)>, +L<EVP_PKEY_verify_recover(3)>, +L<EVP_PKEY_derive(3)> =head1 HISTORY These functions were first added to OpenSSL 1.0.0. +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_PKEY_derive.pod b/deps/openssl/openssl/doc/crypto/EVP_PKEY_derive.pod index 27464be571..f70a0b8d9b 100644 --- a/deps/openssl/openssl/doc/crypto/EVP_PKEY_derive.pod +++ b/deps/openssl/openssl/doc/crypto/EVP_PKEY_derive.pod @@ -2,7 +2,7 @@ =head1 NAME -EVP_PKEY_derive_init, EVP_PKEY_derive_set_peer, EVP_PKEY_derive - derive public key algorithm shared secret. +EVP_PKEY_derive_init, EVP_PKEY_derive_set_peer, EVP_PKEY_derive - derive public key algorithm shared secret =head1 SYNOPSIS @@ -57,37 +57,46 @@ Derive shared secret (for example DH or EC keys): ctx = EVP_PKEY_CTX_new(pkey); if (!ctx) - /* Error occurred */ + /* Error occurred */ if (EVP_PKEY_derive_init(ctx) <= 0) - /* Error */ + /* Error */ if (EVP_PKEY_derive_set_peer(ctx, peerkey) <= 0) - /* Error */ + /* Error */ /* Determine buffer length */ if (EVP_PKEY_derive(ctx, NULL, &skeylen) <= 0) - /* Error */ + /* Error */ skey = OPENSSL_malloc(skeylen); if (!skey) - /* malloc failure */ - + /* malloc failure */ + if (EVP_PKEY_derive(ctx, skey, &skeylen) <= 0) - /* Error */ + /* Error */ /* Shared secret is skey bytes written to buffer skey */ =head1 SEE ALSO -L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, -L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, -L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, -L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, -L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, -L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>, +L<EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_encrypt(3)>, +L<EVP_PKEY_decrypt(3)>, +L<EVP_PKEY_sign(3)>, +L<EVP_PKEY_verify(3)>, +L<EVP_PKEY_verify_recover(3)>, =head1 HISTORY These functions were first added to OpenSSL 1.0.0. +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_PKEY_encrypt.pod b/deps/openssl/openssl/doc/crypto/EVP_PKEY_encrypt.pod index 6799ce1010..01336e128b 100644 --- a/deps/openssl/openssl/doc/crypto/EVP_PKEY_encrypt.pod +++ b/deps/openssl/openssl/doc/crypto/EVP_PKEY_encrypt.pod @@ -10,8 +10,8 @@ EVP_PKEY_encrypt_init, EVP_PKEY_encrypt - encrypt using a public key algorithm int EVP_PKEY_encrypt_init(EVP_PKEY_CTX *ctx); int EVP_PKEY_encrypt(EVP_PKEY_CTX *ctx, - unsigned char *out, size_t *outlen, - const unsigned char *in, size_t inlen); + unsigned char *out, size_t *outlen, + const unsigned char *in, size_t inlen); =head1 DESCRIPTION @@ -43,8 +43,8 @@ indicates the operation is not supported by the public key algorithm. =head1 EXAMPLE -Encrypt data using OAEP (for RSA keys). See also L<PEM_read_PUBKEY(3)|pem(3)> or -L<d2i_X509(3)|d2i_X509(3)> for means to load a public key. You may also simply +Encrypt data using OAEP (for RSA keys). See also L<PEM_read_PUBKEY(3)> or +L<d2i_X509(3)> for means to load a public key. You may also simply set 'eng = NULL;' to start with the default OpenSSL RSA implementation: #include <openssl/evp.h> @@ -54,46 +54,55 @@ set 'eng = NULL;' to start with the default OpenSSL RSA implementation: EVP_PKEY_CTX *ctx; ENGINE *eng; unsigned char *out, *in; - size_t outlen, inlen; + size_t outlen, inlen; EVP_PKEY *key; /* NB: assumes eng, key, in, inlen are already set up, * and that key is an RSA public key */ - ctx = EVP_PKEY_CTX_new(key,eng); + ctx = EVP_PKEY_CTX_new(key, eng); if (!ctx) - /* Error occurred */ + /* Error occurred */ if (EVP_PKEY_encrypt_init(ctx) <= 0) - /* Error */ + /* Error */ if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_OAEP_PADDING) <= 0) - /* Error */ + /* Error */ /* Determine buffer length */ if (EVP_PKEY_encrypt(ctx, NULL, &outlen, in, inlen) <= 0) - /* Error */ + /* Error */ out = OPENSSL_malloc(outlen); if (!out) - /* malloc failure */ - + /* malloc failure */ + if (EVP_PKEY_encrypt(ctx, out, &outlen, in, inlen) <= 0) - /* Error */ + /* Error */ /* Encrypted data is outlen bytes written to buffer out */ =head1 SEE ALSO -L<d2i_X509(3)|d2i_X509(3)>, -L<engine(3)|engine(3)>, -L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, -L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, -L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, -L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, -L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>, -L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> +L<d2i_X509(3)>, +L<engine(3)>, +L<EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_decrypt(3)>, +L<EVP_PKEY_sign(3)>, +L<EVP_PKEY_verify(3)>, +L<EVP_PKEY_verify_recover(3)>, +L<EVP_PKEY_derive(3)> =head1 HISTORY These functions were first added to OpenSSL 1.0.0. +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_PKEY_get_default_digest.pod b/deps/openssl/openssl/doc/crypto/EVP_PKEY_get_default_digest_nid.pod index 8ff597d44a..3dce5c59a8 100644 --- a/deps/openssl/openssl/doc/crypto/EVP_PKEY_get_default_digest.pod +++ b/deps/openssl/openssl/doc/crypto/EVP_PKEY_get_default_digest_nid.pod @@ -29,13 +29,22 @@ public key algorithm. =head1 SEE ALSO -L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, -L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, -L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, -L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>, +L<EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_sign(3)>, +L<EVP_PKEY_verify(3)>, +L<EVP_PKEY_verify_recover(3)>, =head1 HISTORY This function was first added to OpenSSL 1.0.0. +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_PKEY_keygen.pod b/deps/openssl/openssl/doc/crypto/EVP_PKEY_keygen.pod index fd431ace6d..b1e708fc5b 100644 --- a/deps/openssl/openssl/doc/crypto/EVP_PKEY_keygen.pod +++ b/deps/openssl/openssl/doc/crypto/EVP_PKEY_keygen.pod @@ -2,7 +2,12 @@ =head1 NAME -EVP_PKEY_keygen_init, EVP_PKEY_keygen, EVP_PKEY_paramgen_init, EVP_PKEY_paramgen, EVP_PKEY_CTX_set_cb, EVP_PKEY_CTX_get_cb, EVP_PKEY_CTX_get_keygen_info, EVP_PKEVP_PKEY_CTX_set_app_data, EVP_PKEY_CTX_get_app_data - key and parameter generation functions +EVP_PKEY_keygen_init, EVP_PKEY_keygen, EVP_PKEY_paramgen_init, +EVP_PKEY_paramgen, EVP_PKEY_CTX_set_cb, EVP_PKEY_CTX_get_cb, +EVP_PKEY_CTX_get_keygen_info, EVP_PKEY_CTX_set_app_data, +EVP_PKEY_CTX_get_app_data, +EVP_PKEY_gen_cb +- key and parameter generation functions =head1 SYNOPSIS @@ -26,9 +31,9 @@ EVP_PKEY_keygen_init, EVP_PKEY_keygen, EVP_PKEY_paramgen_init, EVP_PKEY_paramgen =head1 DESCRIPTION The EVP_PKEY_keygen_init() function initializes a public key algorithm -context using key B<pkey> for a key genration operation. +context using key B<pkey> for a key generation operation. -The EVP_PKEY_keygen() function performs a key generation operation, the +The EVP_PKEY_keygen() function performs a key generation operation, the generated key is written to B<ppkey>. The functions EVP_PKEY_paramgen_init() and EVP_PKEY_paramgen() are similar @@ -44,7 +49,7 @@ parameters available is returned. Any non negative value returns the value of that parameter. EVP_PKEY_CTX_gen_keygen_info() with a non-negative value for B<idx> should only be called within the generation callback. -If the callback returns 0 then the key genration operation is aborted and an +If the callback returns 0 then the key generation operation is aborted and an error occurs. This might occur during a time consuming operation where a user clicks on a "cancel" button. @@ -64,7 +69,7 @@ once on the same context if several operations are performed using the same parameters. The meaning of the parameters passed to the callback will depend on the -algorithm and the specifiic implementation of the algorithm. Some might not +algorithm and the specific implementation of the algorithm. Some might not give any useful information at all during key or parameter generation. Others might not even call the callback. @@ -95,15 +100,15 @@ Generate a 2048 bit RSA key: EVP_PKEY *pkey = NULL; ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_RSA, NULL); if (!ctx) - /* Error occurred */ + /* Error occurred */ if (EVP_PKEY_keygen_init(ctx) <= 0) - /* Error */ + /* Error */ if (EVP_PKEY_CTX_set_rsa_keygen_bits(ctx, 2048) <= 0) - /* Error */ + /* Error */ /* Generate key */ if (EVP_PKEY_keygen(ctx, &pkey) <= 0) - /* Error */ + /* Error */ Generate a key from a set of parameters: @@ -115,13 +120,13 @@ Generate a key from a set of parameters: /* Assumed param is set up already */ ctx = EVP_PKEY_CTX_new(param); if (!ctx) - /* Error occurred */ + /* Error occurred */ if (EVP_PKEY_keygen_init(ctx) <= 0) - /* Error */ + /* Error */ /* Generate key */ if (EVP_PKEY_keygen(ctx, &pkey) <= 0) - /* Error */ + /* Error */ Example of generation callback for OpenSSL public key implementations: @@ -130,32 +135,41 @@ Example of generation callback for OpenSSL public key implementations: EVP_PKEY_CTX_set_app_data(ctx, status_bio); static int genpkey_cb(EVP_PKEY_CTX *ctx) - { - char c='*'; - BIO *b = EVP_PKEY_CTX_get_app_data(ctx); - int p; - p = EVP_PKEY_CTX_get_keygen_info(ctx, 0); - if (p == 0) c='.'; - if (p == 1) c='+'; - if (p == 2) c='*'; - if (p == 3) c='\n'; - BIO_write(b,&c,1); - (void)BIO_flush(b); - return 1; - } + { + char c = '*'; + BIO *b = EVP_PKEY_CTX_get_app_data(ctx); + int p; + p = EVP_PKEY_CTX_get_keygen_info(ctx, 0); + if (p == 0) c = '.'; + if (p == 1) c = '+'; + if (p == 2) c = '*'; + if (p == 3) c = '\n'; + BIO_write(b, &c, 1); + (void)BIO_flush(b); + return 1; + } =head1 SEE ALSO -L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, -L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, -L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, -L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, -L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, -L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>, -L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> +L<EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_encrypt(3)>, +L<EVP_PKEY_decrypt(3)>, +L<EVP_PKEY_sign(3)>, +L<EVP_PKEY_verify(3)>, +L<EVP_PKEY_verify_recover(3)>, +L<EVP_PKEY_derive(3)> =head1 HISTORY These functions were first added to OpenSSL 1.0.0. +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_PKEY_meth_new.pod b/deps/openssl/openssl/doc/crypto/EVP_PKEY_meth_new.pod deleted file mode 100644 index 041492a8f0..0000000000 --- a/deps/openssl/openssl/doc/crypto/EVP_PKEY_meth_new.pod +++ /dev/null @@ -1,376 +0,0 @@ -=pod - -=head1 NAME - -EVP_PKEY_meth_new, EVP_PKEY_meth_free, EVP_PKEY_meth_copy, EVP_PKEY_meth_find, -EVP_PKEY_meth_add0, EVP_PKEY_METHOD, -EVP_PKEY_meth_set_init, EVP_PKEY_meth_set_copy, EVP_PKEY_meth_set_cleanup, -EVP_PKEY_meth_set_paramgen, EVP_PKEY_meth_set_keygen, EVP_PKEY_meth_set_sign, -EVP_PKEY_meth_set_verify, EVP_PKEY_meth_set_verify_recover, EVP_PKEY_meth_set_signctx, -EVP_PKEY_meth_set_verifyctx, EVP_PKEY_meth_set_encrypt, EVP_PKEY_meth_set_decrypt, -EVP_PKEY_meth_set_derive, EVP_PKEY_meth_set_ctrl, -EVP_PKEY_meth_get_init, EVP_PKEY_meth_get_copy, EVP_PKEY_meth_get_cleanup, -EVP_PKEY_meth_get_paramgen, EVP_PKEY_meth_get_keygen, EVP_PKEY_meth_get_sign, -EVP_PKEY_meth_get_verify, EVP_PKEY_meth_get_verify_recover, EVP_PKEY_meth_get_signctx, -EVP_PKEY_meth_get_verifyctx, EVP_PKEY_meth_get_encrypt, EVP_PKEY_meth_get_decrypt, -EVP_PKEY_meth_get_derive, EVP_PKEY_meth_get_ctrl -- manipulating EVP_PKEY_METHOD structure - -=head1 SYNOPSIS - - #include <openssl/evp.h> - - typedef struct evp_pkey_method_st EVP_PKEY_METHOD; - - EVP_PKEY_METHOD *EVP_PKEY_meth_new(int id, int flags); - void EVP_PKEY_meth_free(EVP_PKEY_METHOD *pmeth); - void EVP_PKEY_meth_copy(EVP_PKEY_METHOD *dst, const EVP_PKEY_METHOD *src); - const EVP_PKEY_METHOD *EVP_PKEY_meth_find(int type); - int EVP_PKEY_meth_add0(const EVP_PKEY_METHOD *pmeth); - - void EVP_PKEY_meth_set_init(EVP_PKEY_METHOD *pmeth, - int (*init) (EVP_PKEY_CTX *ctx)); - void EVP_PKEY_meth_set_copy(EVP_PKEY_METHOD *pmeth, - int (*copy) (EVP_PKEY_CTX *dst, - EVP_PKEY_CTX *src)); - void EVP_PKEY_meth_set_cleanup(EVP_PKEY_METHOD *pmeth, - void (*cleanup) (EVP_PKEY_CTX *ctx)); - void EVP_PKEY_meth_set_paramgen(EVP_PKEY_METHOD *pmeth, - int (*paramgen_init) (EVP_PKEY_CTX *ctx), - int (*paramgen) (EVP_PKEY_CTX *ctx, - EVP_PKEY *pkey)); - void EVP_PKEY_meth_set_keygen(EVP_PKEY_METHOD *pmeth, - int (*keygen_init) (EVP_PKEY_CTX *ctx), - int (*keygen) (EVP_PKEY_CTX *ctx, - EVP_PKEY *pkey)); - void EVP_PKEY_meth_set_sign(EVP_PKEY_METHOD *pmeth, - int (*sign_init) (EVP_PKEY_CTX *ctx), - int (*sign) (EVP_PKEY_CTX *ctx, - unsigned char *sig, size_t *siglen, - const unsigned char *tbs, - size_t tbslen)); - void EVP_PKEY_meth_set_verify(EVP_PKEY_METHOD *pmeth, - int (*verify_init) (EVP_PKEY_CTX *ctx), - int (*verify) (EVP_PKEY_CTX *ctx, - const unsigned char *sig, - size_t siglen, - const unsigned char *tbs, - size_t tbslen)); - void EVP_PKEY_meth_set_verify_recover(EVP_PKEY_METHOD *pmeth, - int (*verify_recover_init) (EVP_PKEY_CTX - *ctx), - int (*verify_recover) (EVP_PKEY_CTX - *ctx, - unsigned char - *sig, - size_t *siglen, - const unsigned - char *tbs, - size_t tbslen)); - void EVP_PKEY_meth_set_signctx(EVP_PKEY_METHOD *pmeth, - int (*signctx_init) (EVP_PKEY_CTX *ctx, - EVP_MD_CTX *mctx), - int (*signctx) (EVP_PKEY_CTX *ctx, - unsigned char *sig, - size_t *siglen, - EVP_MD_CTX *mctx)); - void EVP_PKEY_meth_set_verifyctx(EVP_PKEY_METHOD *pmeth, - int (*verifyctx_init) (EVP_PKEY_CTX *ctx, - EVP_MD_CTX *mctx), - int (*verifyctx) (EVP_PKEY_CTX *ctx, - const unsigned char *sig, - int siglen, - EVP_MD_CTX *mctx)); - void EVP_PKEY_meth_set_encrypt(EVP_PKEY_METHOD *pmeth, - int (*encrypt_init) (EVP_PKEY_CTX *ctx), - int (*encryptfn) (EVP_PKEY_CTX *ctx, - unsigned char *out, - size_t *outlen, - const unsigned char *in, - size_t inlen)); - void EVP_PKEY_meth_set_decrypt(EVP_PKEY_METHOD *pmeth, - int (*decrypt_init) (EVP_PKEY_CTX *ctx), - int (*decrypt) (EVP_PKEY_CTX *ctx, - unsigned char *out, - size_t *outlen, - const unsigned char *in, - size_t inlen)); - void EVP_PKEY_meth_set_derive(EVP_PKEY_METHOD *pmeth, - int (*derive_init) (EVP_PKEY_CTX *ctx), - int (*derive) (EVP_PKEY_CTX *ctx, - unsigned char *key, - size_t *keylen)); - void EVP_PKEY_meth_set_ctrl(EVP_PKEY_METHOD *pmeth, - int (*ctrl) (EVP_PKEY_CTX *ctx, int type, int p1, - void *p2), - int (*ctrl_str) (EVP_PKEY_CTX *ctx, - const char *type, - const char *value)); - - void EVP_PKEY_meth_get_init(EVP_PKEY_METHOD *pmeth, - int (**pinit) (EVP_PKEY_CTX *ctx)); - void EVP_PKEY_meth_get_copy(EVP_PKEY_METHOD *pmeth, - int (**pcopy) (EVP_PKEY_CTX *dst, - EVP_PKEY_CTX *src)); - void EVP_PKEY_meth_get_cleanup(EVP_PKEY_METHOD *pmeth, - void (**pcleanup) (EVP_PKEY_CTX *ctx)); - void EVP_PKEY_meth_get_paramgen(EVP_PKEY_METHOD *pmeth, - int (**pparamgen_init) (EVP_PKEY_CTX *ctx), - int (**pparamgen) (EVP_PKEY_CTX *ctx, - EVP_PKEY *pkey)); - void EVP_PKEY_meth_get_keygen(EVP_PKEY_METHOD *pmeth, - int (**pkeygen_init) (EVP_PKEY_CTX *ctx), - int (**pkeygen) (EVP_PKEY_CTX *ctx, - EVP_PKEY *pkey)); - void EVP_PKEY_meth_get_sign(EVP_PKEY_METHOD *pmeth, - int (**psign_init) (EVP_PKEY_CTX *ctx), - int (**psign) (EVP_PKEY_CTX *ctx, - unsigned char *sig, size_t *siglen, - const unsigned char *tbs, - size_t tbslen)); - void EVP_PKEY_meth_get_verify(EVP_PKEY_METHOD *pmeth, - int (**pverify_init) (EVP_PKEY_CTX *ctx), - int (**pverify) (EVP_PKEY_CTX *ctx, - const unsigned char *sig, - size_t siglen, - const unsigned char *tbs, - size_t tbslen)); - void EVP_PKEY_meth_get_verify_recover(EVP_PKEY_METHOD *pmeth, - int (**pverify_recover_init) (EVP_PKEY_CTX - *ctx), - int (**pverify_recover) (EVP_PKEY_CTX - *ctx, - unsigned char - *sig, - size_t *siglen, - const unsigned - char *tbs, - size_t tbslen)); - void EVP_PKEY_meth_get_signctx(EVP_PKEY_METHOD *pmeth, - int (**psignctx_init) (EVP_PKEY_CTX *ctx, - EVP_MD_CTX *mctx), - int (**psignctx) (EVP_PKEY_CTX *ctx, - unsigned char *sig, - size_t *siglen, - EVP_MD_CTX *mctx)); - void EVP_PKEY_meth_get_verifyctx(EVP_PKEY_METHOD *pmeth, - int (**pverifyctx_init) (EVP_PKEY_CTX *ctx, - EVP_MD_CTX *mctx), - int (**pverifyctx) (EVP_PKEY_CTX *ctx, - const unsigned char *sig, - int siglen, - EVP_MD_CTX *mctx)); - void EVP_PKEY_meth_get_encrypt(EVP_PKEY_METHOD *pmeth, - int (**pencrypt_init) (EVP_PKEY_CTX *ctx), - int (**pencryptfn) (EVP_PKEY_CTX *ctx, - unsigned char *out, - size_t *outlen, - const unsigned char *in, - size_t inlen)); - void EVP_PKEY_meth_get_decrypt(EVP_PKEY_METHOD *pmeth, - int (**pdecrypt_init) (EVP_PKEY_CTX *ctx), - int (**pdecrypt) (EVP_PKEY_CTX *ctx, - unsigned char *out, - size_t *outlen, - const unsigned char *in, - size_t inlen)); - void EVP_PKEY_meth_get_derive(EVP_PKEY_METHOD *pmeth, - int (**pderive_init) (EVP_PKEY_CTX *ctx), - int (**pderive) (EVP_PKEY_CTX *ctx, - unsigned char *key, - size_t *keylen)); - void EVP_PKEY_meth_get_ctrl(EVP_PKEY_METHOD *pmeth, - int (**pctrl) (EVP_PKEY_CTX *ctx, int type, int p1, - void *p2), - int (**pctrl_str) (EVP_PKEY_CTX *ctx, - const char *type, - const char *value)); - -=head1 DESCRIPTION - -B<EVP_PKEY_METHOD> is a structure which holds a set of methods for a -specific public key cryptographic algorithm. Those methods are usually -used to perform different jobs, such as generating a key, signing or -verifying, encrypting or decrypting, etc. - -There are two places where the B<EVP_PKEY_METHOD> objects are stored: one -is a built-in static array representing the standard methods for different -algorithms, and the other one is a stack of user-defined application-specific -methods, which can be manipulated by using L<EVP_PKEY_meth_add0(3)>. - -The B<EVP_PKEY_METHOD> objects are usually referenced by B<EVP_PKEY_CTX> -objects. - -=head2 Methods - -The methods are the underlying implementations of a particular public key -algorithm present by the B<EVP_PKEY_CTX> object. - - int (*init) (EVP_PKEY_CTX *ctx); - int (*copy) (EVP_PKEY_CTX *dst, EVP_PKEY_CTX *src); - void (*cleanup) (EVP_PKEY_CTX *ctx); - -The init() method is called to initialize algorithm-specific data when a new -B<EVP_PKEY_CTX> is created. As opposed to init(), the cleanup() method is called -when an B<EVP_PKEY_CTX> is freed. The copy() method is called when an B<EVP_PKEY_CTX> -is being duplicated. Refer to L<EVP_PKEY_CTX_new(3)>, L<EVP_PKEY_CTX_new_id(3)>, -L<EVP_PKEY_CTX_free(3)> and L<EVP_PKEY_CTX_dup(3)>. - - int (*paramgen_init) (EVP_PKEY_CTX *ctx); - int (*paramgen) (EVP_PKEY_CTX *ctx, EVP_PKEY *pkey); - -The paramgen_init() and paramgen() methods deal with key parameter generation. -They are called by L<EVP_PKEY_paramgen_init(3)> and L<EVP_PKEY_paramgen(3)> to -handle the parameter generation process. - - int (*keygen_init) (EVP_PKEY_CTX *ctx); - int (*keygen) (EVP_PKEY_CTX *ctx, EVP_PKEY *pkey); - -The keygen_init() and keygen() methods are used to generate the actual key for -the specified algorithm. They are called by L<EVP_PKEY_keygen_init(3)> and -L<EVP_PKEY_keygen(3)>. - - int (*sign_init) (EVP_PKEY_CTX *ctx); - int (*sign) (EVP_PKEY_CTX *ctx, unsigned char *sig, size_t *siglen, - const unsigned char *tbs, size_t tbslen); - -The sign_init() and sign() methods are used to generate the signature of a -piece of data using a private key. They are called by L<EVP_PKEY_sign_init(3)> -and L<EVP_PKEY_sign(3)>. - - int (*verify_init) (EVP_PKEY_CTX *ctx); - int (*verify) (EVP_PKEY_CTX *ctx, - const unsigned char *sig, size_t siglen, - const unsigned char *tbs, size_t tbslen); - -The verify_init() and verify() methods are used to verify whether a signature is -valid. They are called by L<EVP_PKEY_verify_init(3)> and L<EVP_PKEY_verify(3)>. - - int (*verify_recover_init) (EVP_PKEY_CTX *ctx); - int (*verify_recover) (EVP_PKEY_CTX *ctx, - unsigned char *rout, size_t *routlen, - const unsigned char *sig, size_t siglen); - -The verify_recover_init() and verify_recover() methods are used to verify a -signature and then recover the digest from the signature (for instance, a -signature that was generated by RSA signing algorithm). They are called by -L<EVP_PKEY_verify_recover_init(3)> and L<EVP_PKEY_verify_recover(3)>. - - int (*signctx_init) (EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx); - int (*signctx) (EVP_PKEY_CTX *ctx, unsigned char *sig, size_t *siglen, - EVP_MD_CTX *mctx); - -The signctx_init() and signctx() methods are used to sign a digest present by -a B<EVP_MD_CTX> object. They are called by the EVP_DigestSign functions. See -L<EVP_DigestSignInit(3)> for detail. - - int (*verifyctx_init) (EVP_PKEY_CTX *ctx, EVP_MD_CTX *mctx); - int (*verifyctx) (EVP_PKEY_CTX *ctx, const unsigned char *sig, int siglen, - EVP_MD_CTX *mctx); - -The verifyctx_init() and verifyctx() methods are used to verify a signature -against the data in a B<EVP_MD_CTX> object. They are called by the various -EVP_DigestVerify functions. See L<EVP_DigestVerifyInit(3)> for detail. - - int (*encrypt_init) (EVP_PKEY_CTX *ctx); - int (*encrypt) (EVP_PKEY_CTX *ctx, unsigned char *out, size_t *outlen, - const unsigned char *in, size_t inlen); - -The encrypt_init() and encrypt() methods are used to encrypt a piece of data. -They are called by L<EVP_PKEY_encrypt_init(3)> and L<EVP_PKEY_encrypt(3)>. - - int (*decrypt_init) (EVP_PKEY_CTX *ctx); - int (*decrypt) (EVP_PKEY_CTX *ctx, unsigned char *out, size_t *outlen, - const unsigned char *in, size_t inlen); - -The decrypt_init() and decrypt() methods are used to decrypt a piece of data. -They are called by L<EVP_PKEY_decrypt_init(3)> and L<EVP_PKEY_decrypt(3)>. - - int (*derive_init) (EVP_PKEY_CTX *ctx); - int (*derive) (EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen); - -The derive_init() and derive() methods are used to derive the shared secret -from a public key algorithm (for instance, the DH algorithm). They are called by -L<EVP_PKEY_derive_init(3)> and L<EVP_PKEY_derive(3)>. - - int (*ctrl) (EVP_PKEY_CTX *ctx, int type, int p1, void *p2); - int (*ctrl_str) (EVP_PKEY_CTX *ctx, const char *type, const char *value); - -The ctrl() and ctrl_str() methods are used to adjust algorithm-specific -settings. See L<EVP_PKEY_CTX_ctrl(3)> and related functions for detail. - - int (*digestsign) (EVP_MD_CTX *ctx, unsigned char *sig, size_t *siglen, - const unsigned char *tbs, size_t tbslen); - int (*digestverify) (EVP_MD_CTX *ctx, const unsigned char *sig, - size_t siglen, const unsigned char *tbs, - size_t tbslen); - -The digestsign() and digestverify() methods are used to generate or verify -a signature in a one-shot mode. They could be called by L<EVP_DigetSign(3)> -and L<EVP_DigestVerify(3)>. - -=head2 Functions - -EVP_PKEY_meth_new() creates and returns a new B<EVP_PKEY_METHOD> object, -and associates the given B<id> and B<flags>. The following flags are -supported: - - EVP_PKEY_FLAG_AUTOARGLEN - EVP_PKEY_FLAG_SIGCTX_CUSTOM - -If an B<EVP_PKEY_METHOD> is set with the B<EVP_PKEY_FLAG_AUTOARGLEN> flag, the -maximum size of the output buffer will be automatically calculated or checked -in corresponding EVP methods by the EVP framework. Thus the implementations of -these methods don't need to care about handling the case of returning output -buffer size by themselves. For details on the output buffer size, refer to -L<EVP_PKEY_sign(3)>. - -The B<EVP_PKEY_FLAG_SIGCTX_CUSTOM> is used to indicate the signctx() method -of an B<EVP_PKEY_METHOD> is always called by the EVP framework while doing a -digest signing operation by calling L<EVP_DigestSignFinal(3)>. - -EVP_PKEY_meth_free() frees an existing B<EVP_PKEY_METHOD> pointed by -B<pmeth>. - -EVP_PKEY_meth_copy() copies an B<EVP_PKEY_METHOD> object from B<src> -to B<dst>. - -EVP_PKEY_meth_find() finds an B<EVP_PKEY_METHOD> object with the B<id>. -This function first searches through the user-defined method objects and -then the built-in objects. - -EVP_PKEY_meth_add0() adds B<pmeth> to the user defined stack of methods. - -The EVP_PKEY_meth_set functions set the corresponding fields of -B<EVP_PKEY_METHOD> structure with the arguments passed. - -The EVP_PKEY_meth_get functions get the corresponding fields of -B<EVP_PKEY_METHOD> structure to the arguments provided. - -=head1 RETURN VALUES - -EVP_PKEY_meth_new() returns a pointer to a new B<EVP_PKEY_METHOD> -object or returns NULL on error. - -EVP_PKEY_meth_free() and EVP_PKEY_meth_copy() do not return values. - -EVP_PKEY_meth_find() returns a pointer to the found B<EVP_PKEY_METHOD> -object or returns NULL if not found. - -EVP_PKEY_meth_add0() returns 1 if method is added successfully or 0 -if an error occurred. - -All EVP_PKEY_meth_set and EVP_PKEY_meth_get functions have no return -values. For the 'get' functions, function pointers are returned by -arguments. - -=head1 COPYRIGHT - -Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_PKEY_new.pod b/deps/openssl/openssl/doc/crypto/EVP_PKEY_new.pod index 10687e458d..956d699002 100644 --- a/deps/openssl/openssl/doc/crypto/EVP_PKEY_new.pod +++ b/deps/openssl/openssl/doc/crypto/EVP_PKEY_new.pod @@ -2,46 +2,60 @@ =head1 NAME -EVP_PKEY_new, EVP_PKEY_free - private key allocation functions. +EVP_PKEY_new, EVP_PKEY_up_ref, EVP_PKEY_free - private key allocation functions =head1 SYNOPSIS #include <openssl/evp.h> EVP_PKEY *EVP_PKEY_new(void); + int EVP_PKEY_up_ref(EVP_PKEY *key); void EVP_PKEY_free(EVP_PKEY *key); =head1 DESCRIPTION -The EVP_PKEY_new() function allocates an empty B<EVP_PKEY> -structure which is used by OpenSSL to store private keys. +The EVP_PKEY_new() function allocates an empty B<EVP_PKEY> structure which is +used by OpenSSL to store private keys. The reference count is set to B<1>. -EVP_PKEY_free() frees up the private key B<key>. +EVP_PKEY_up_ref() increments the reference count of B<key>. + +EVP_PKEY_free() decrements the reference count of B<key> and, if the reference +count is zero, frees it up. If B<key> is NULL, nothing is done. =head1 NOTES -The B<EVP_PKEY> structure is used by various OpenSSL functions -which require a general private key without reference to any -particular algorithm. +The B<EVP_PKEY> structure is used by various OpenSSL functions which require a +general private key without reference to any particular algorithm. -The structure returned by EVP_PKEY_new() is empty. To add a -private key to this empty structure the functions described in -L<EVP_PKEY_set1_RSA(3)|EVP_PKEY_set1_RSA(3)> should be used. +The structure returned by EVP_PKEY_new() is empty. To add a private key to this +empty structure the functions described in L<EVP_PKEY_set1_RSA(3)> should be +used. =head1 RETURN VALUES -EVP_PKEY_new() returns either the newly allocated B<EVP_PKEY> -structure of B<NULL> if an error occurred. +EVP_PKEY_new() returns either the newly allocated B<EVP_PKEY> structure or +B<NULL> if an error occurred. -EVP_PKEY_free() does not return a value. +EVP_PKEY_up_ref() returns 1 for success and 0 for failure. =head1 SEE ALSO -L<EVP_PKEY_set1_RSA(3)|EVP_PKEY_set1_RSA(3)> +L<EVP_PKEY_set1_RSA(3)> =head1 HISTORY -TBA +EVP_PKEY_new() and EVP_PKEY_free() exist in all versions of OpenSSL. + +EVP_PKEY_up_ref() was first added to OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_PKEY_print_private.pod b/deps/openssl/openssl/doc/crypto/EVP_PKEY_print_private.pod index ce9d70d7a7..9f1d324f81 100644 --- a/deps/openssl/openssl/doc/crypto/EVP_PKEY_print_private.pod +++ b/deps/openssl/openssl/doc/crypto/EVP_PKEY_print_private.pod @@ -2,18 +2,18 @@ =head1 NAME -EVP_PKEY_print_public, EVP_PKEY_print_private, EVP_PKEY_print_params - public key algorithm printing routines. +EVP_PKEY_print_public, EVP_PKEY_print_private, EVP_PKEY_print_params - public key algorithm printing routines =head1 SYNOPSIS #include <openssl/evp.h> int EVP_PKEY_print_public(BIO *out, const EVP_PKEY *pkey, - int indent, ASN1_PCTX *pctx); + int indent, ASN1_PCTX *pctx); int EVP_PKEY_print_private(BIO *out, const EVP_PKEY *pkey, - int indent, ASN1_PCTX *pctx); + int indent, ASN1_PCTX *pctx); int EVP_PKEY_print_params(BIO *out, const EVP_PKEY *pkey, - int indent, ASN1_PCTX *pctx); + int indent, ASN1_PCTX *pctx); =head1 DESCRIPTION @@ -28,7 +28,7 @@ be used. =head1 NOTES -Currently no public key algorithms include any options in the B<pctx> parameter +Currently no public key algorithms include any options in the B<pctx> parameter parameter. If the key does not include all the components indicated by the function then @@ -43,11 +43,20 @@ the public key algorithm. =head1 SEE ALSO -L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, -L<EVP_PKEY_keygen(3)|EVP_PKEY_keygen(3)> +L<EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_keygen(3)> =head1 HISTORY These functions were first added to OpenSSL 1.0.0. +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_PKEY_set1_RSA.pod b/deps/openssl/openssl/doc/crypto/EVP_PKEY_set1_RSA.pod index 6f10175615..884cf91cb7 100644 --- a/deps/openssl/openssl/doc/crypto/EVP_PKEY_set1_RSA.pod +++ b/deps/openssl/openssl/doc/crypto/EVP_PKEY_set1_RSA.pod @@ -4,30 +4,42 @@ EVP_PKEY_set1_RSA, EVP_PKEY_set1_DSA, EVP_PKEY_set1_DH, EVP_PKEY_set1_EC_KEY, EVP_PKEY_get1_RSA, EVP_PKEY_get1_DSA, EVP_PKEY_get1_DH, EVP_PKEY_get1_EC_KEY, -EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH, EVP_PKEY_assign_EC_KEY, -EVP_PKEY_type - EVP_PKEY assignment functions. +EVP_PKEY_get0_RSA, EVP_PKEY_get0_DSA, EVP_PKEY_get0_DH, EVP_PKEY_get0_EC_KEY, +EVP_PKEY_assign_RSA, EVP_PKEY_assign_DSA, EVP_PKEY_assign_DH, +EVP_PKEY_assign_EC_KEY, EVP_PKEY_get0_hmac, EVP_PKEY_type, EVP_PKEY_id, +EVP_PKEY_base_id, EVP_PKEY_set1_engine - EVP_PKEY assignment functions =head1 SYNOPSIS #include <openssl/evp.h> - int EVP_PKEY_set1_RSA(EVP_PKEY *pkey,RSA *key); - int EVP_PKEY_set1_DSA(EVP_PKEY *pkey,DSA *key); - int EVP_PKEY_set1_DH(EVP_PKEY *pkey,DH *key); - int EVP_PKEY_set1_EC_KEY(EVP_PKEY *pkey,EC_KEY *key); + int EVP_PKEY_set1_RSA(EVP_PKEY *pkey, RSA *key); + int EVP_PKEY_set1_DSA(EVP_PKEY *pkey, DSA *key); + int EVP_PKEY_set1_DH(EVP_PKEY *pkey, DH *key); + int EVP_PKEY_set1_EC_KEY(EVP_PKEY *pkey, EC_KEY *key); RSA *EVP_PKEY_get1_RSA(EVP_PKEY *pkey); DSA *EVP_PKEY_get1_DSA(EVP_PKEY *pkey); DH *EVP_PKEY_get1_DH(EVP_PKEY *pkey); EC_KEY *EVP_PKEY_get1_EC_KEY(EVP_PKEY *pkey); - int EVP_PKEY_assign_RSA(EVP_PKEY *pkey,RSA *key); - int EVP_PKEY_assign_DSA(EVP_PKEY *pkey,DSA *key); - int EVP_PKEY_assign_DH(EVP_PKEY *pkey,DH *key); - int EVP_PKEY_assign_EC_KEY(EVP_PKEY *pkey,EC_KEY *key); + const unsigned char *EVP_PKEY_get0_hmac(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); + int EVP_PKEY_assign_RSA(EVP_PKEY *pkey, RSA *key); + int EVP_PKEY_assign_DSA(EVP_PKEY *pkey, DSA *key); + int EVP_PKEY_assign_DH(EVP_PKEY *pkey, DH *key); + int EVP_PKEY_assign_EC_KEY(EVP_PKEY *pkey, EC_KEY *key); + + int EVP_PKEY_id(const EVP_PKEY *pkey); + int EVP_PKEY_base_id(const EVP_PKEY *pkey); int EVP_PKEY_type(int type); + int EVP_PKEY_set1_engine(EVP_PKEY *pkey, ENGINE *engine); + =head1 DESCRIPTION EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and @@ -37,16 +49,34 @@ EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and EVP_PKEY_get1_EC_KEY() return the referenced key in B<pkey> or B<NULL> if the key is not of the correct type. +EVP_PKEY_get0_hmac(), EVP_PKEY_get0_RSA(), EVP_PKEY_get0_DSA(), +EVP_PKEY_get0_DH() and EVP_PKEY_get0_EC_KEY() also return the +referenced key in B<pkey> or B<NULL> if the key is not of the +correct type but the reference count of the returned key is +B<not> incremented and so must not be freed up after use. + EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH() and EVP_PKEY_assign_EC_KEY() also set the referenced key to B<key> however these use the supplied B<key> internally and so B<key> will be freed when the parent B<pkey> is freed. -EVP_PKEY_type() returns the type of key corresponding to the value -B<type>. The type of a key can be obtained with -EVP_PKEY_type(pkey->type). The return value will be EVP_PKEY_RSA, -EVP_PKEY_DSA, EVP_PKEY_DH or EVP_PKEY_EC for the corresponding -key types or NID_undef if the key type is unassigned. +EVP_PKEY_base_id() returns the type of B<pkey>. For example +an RSA key will return B<EVP_PKEY_RSA>. + +EVP_PKEY_id() returns the actual OID associated with B<pkey>. Historically keys +using the same algorithm could use different OIDs. For example an RSA key could +use the OIDs corresponding to the NIDs B<NID_rsaEncryption> (equivalent to +B<EVP_PKEY_RSA>) or B<NID_rsa> (equivalent to B<EVP_PKEY_RSA2>). The use of +alternative non-standard OIDs is now rare so B<EVP_PKEY_RSA2> et al are not +often seen in practice. + +EVP_PKEY_type() returns the underlying type of the NID B<type>. For example +EVP_PKEY_type(EVP_PKEY_RSA2) will return B<EVP_PKEY_RSA>. + +EVP_PKEY_set1_engine() sets the ENGINE handling B<pkey> to B<engine>. It +must be called after the key algorithm and components are set up. +If B<engine> does not include an B<EVP_PKEY_METHOD> for B<pkey> an +error occurs. =head1 NOTES @@ -57,24 +87,45 @@ freed as well as B<pkey>. EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH() and EVP_PKEY_assign_EC_KEY() are implemented as macros. +Most applications wishing to know a key type will simply call +EVP_PKEY_base_id() and will not care about the actual type: +which will be identical in almost all cases. + +Previous versions of this document suggested using EVP_PKEY_type(pkey->type) +to determine the type of a key. Since B<EVP_PKEY> is now opaque this +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 RETURN VALUES EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and EVP_PKEY_set1_EC_KEY() return 1 for success or 0 for failure. EVP_PKEY_get1_RSA(), EVP_PKEY_get1_DSA(), EVP_PKEY_get1_DH() and -EVP_PKEY_get1_EC_KEY() return the referenced key or B<NULL> if +EVP_PKEY_get1_EC_KEY() return the referenced key or B<NULL> if an error occurred. EVP_PKEY_assign_RSA(), EVP_PKEY_assign_DSA(), EVP_PKEY_assign_DH() and EVP_PKEY_assign_EC_KEY() return 1 for success and 0 for failure. +EVP_PKEY_base_id(), EVP_PKEY_id() and EVP_PKEY_type() return a key +type or B<NID_undef> (equivalently B<EVP_PKEY_NONE>) on error. + +EVP_PKEY_set1_engine() returns 1 for success and 0 for failure. + =head1 SEE ALSO -L<EVP_PKEY_new(3)|EVP_PKEY_new(3)> +L<EVP_PKEY_new(3)> + +=head1 COPYRIGHT -=head1 HISTORY +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. -TBA +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_PKEY_sign.pod b/deps/openssl/openssl/doc/crypto/EVP_PKEY_sign.pod index 21974b4b1a..9b3c8d4593 100644 --- a/deps/openssl/openssl/doc/crypto/EVP_PKEY_sign.pod +++ b/deps/openssl/openssl/doc/crypto/EVP_PKEY_sign.pod @@ -10,8 +10,8 @@ EVP_PKEY_sign_init, EVP_PKEY_sign - sign using a public key algorithm int EVP_PKEY_sign_init(EVP_PKEY_CTX *ctx); int EVP_PKEY_sign(EVP_PKEY_CTX *ctx, - unsigned char *sig, size_t *siglen, - const unsigned char *tbs, size_t tbslen); + unsigned char *sig, size_t *siglen, + const unsigned char *tbs, size_t tbslen); =head1 DESCRIPTION @@ -30,12 +30,12 @@ B<sig> and the amount of data written to B<siglen>. EVP_PKEY_sign() does not hash the data to be signed, and therefore is normally used to sign digests. For signing arbitrary messages, see the -L<EVP_DigestSignInit(3)|EVP_DigestSignInit(3)> and -L<EVP_SignInit(3)|EVP_SignInit(3)> signing interfaces instead. +L<EVP_DigestSignInit(3)> and +L<EVP_SignInit(3)> signing interfaces instead. After the call to EVP_PKEY_sign_init() algorithm specific control operations can be performed to set any appropriate parameters for the -operation (see L<EVP_PKEY_CTX_ctrl(3)|EVP_PKEY_CTX_ctrl(3)>). +operation (see L<EVP_PKEY_CTX_ctrl(3)>). The function EVP_PKEY_sign() can be called more than once on the same context if several operations are performed using the same parameters. @@ -66,41 +66,50 @@ Sign data using RSA with PKCS#1 padding and SHA256 digest: */ ctx = EVP_PKEY_CTX_new(signing_key, NULL /* no engine */); if (!ctx) - /* Error occurred */ + /* Error occurred */ if (EVP_PKEY_sign_init(ctx) <= 0) - /* Error */ + /* Error */ if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0) - /* Error */ + /* Error */ if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0) - /* Error */ + /* Error */ /* Determine buffer length */ if (EVP_PKEY_sign(ctx, NULL, &siglen, md, mdlen) <= 0) - /* Error */ + /* Error */ sig = OPENSSL_malloc(siglen); if (!sig) - /* malloc failure */ - + /* malloc failure */ + if (EVP_PKEY_sign(ctx, sig, &siglen, md, mdlen) <= 0) - /* Error */ + /* Error */ /* Signature is siglen bytes written to buffer sig */ =head1 SEE ALSO -L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, -L<EVP_PKEY_CTX_ctrl(3)|EVP_PKEY_CTX_ctrl(3)>, -L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, -L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, -L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, -L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>, -L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> +L<EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_CTX_ctrl(3)>, +L<EVP_PKEY_encrypt(3)>, +L<EVP_PKEY_decrypt(3)>, +L<EVP_PKEY_verify(3)>, +L<EVP_PKEY_verify_recover(3)>, +L<EVP_PKEY_derive(3)> =head1 HISTORY These functions were first added to OpenSSL 1.0.0. +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_PKEY_verify.pod b/deps/openssl/openssl/doc/crypto/EVP_PKEY_verify.pod index 90612ba2f0..e84f880419 100644 --- a/deps/openssl/openssl/doc/crypto/EVP_PKEY_verify.pod +++ b/deps/openssl/openssl/doc/crypto/EVP_PKEY_verify.pod @@ -10,8 +10,8 @@ EVP_PKEY_verify_init, EVP_PKEY_verify - signature verification using a public ke int EVP_PKEY_verify_init(EVP_PKEY_CTX *ctx); int EVP_PKEY_verify(EVP_PKEY_CTX *ctx, - const unsigned char *sig, size_t siglen, - const unsigned char *tbs, size_t tbslen); + const unsigned char *sig, size_t siglen, + const unsigned char *tbs, size_t tbslen); =head1 DESCRIPTION @@ -53,20 +53,20 @@ Verify signature using PKCS#1 and SHA256 digest: EVP_PKEY_CTX *ctx; unsigned char *md, *sig; - size_t mdlen, siglen; + size_t mdlen, siglen; EVP_PKEY *verify_key; /* NB: assumes verify_key, sig, siglen md and mdlen are already set up * and that verify_key is an RSA public key */ ctx = EVP_PKEY_CTX_new(verify_key); if (!ctx) - /* Error occurred */ + /* Error occurred */ if (EVP_PKEY_verify_init(ctx) <= 0) - /* Error */ + /* Error */ if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0) - /* Error */ + /* Error */ if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0) - /* Error */ + /* Error */ /* Perform operation */ ret = EVP_PKEY_verify(ctx, sig, siglen, md, mdlen); @@ -77,15 +77,24 @@ Verify signature using PKCS#1 and SHA256 digest: =head1 SEE ALSO -L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, -L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, -L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, -L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, -L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>, -L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> +L<EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_encrypt(3)>, +L<EVP_PKEY_decrypt(3)>, +L<EVP_PKEY_sign(3)>, +L<EVP_PKEY_verify_recover(3)>, +L<EVP_PKEY_derive(3)> =head1 HISTORY These functions were first added to OpenSSL 1.0.0. +=head1 COPYRIGHT + +Copyright 2006-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_PKEY_verify_recover.pod b/deps/openssl/openssl/doc/crypto/EVP_PKEY_verify_recover.pod index 23a28a9c43..837bc64ec2 100644 --- a/deps/openssl/openssl/doc/crypto/EVP_PKEY_verify_recover.pod +++ b/deps/openssl/openssl/doc/crypto/EVP_PKEY_verify_recover.pod @@ -10,8 +10,8 @@ EVP_PKEY_verify_recover_init, EVP_PKEY_verify_recover - recover signature using int EVP_PKEY_verify_recover_init(EVP_PKEY_CTX *ctx); int EVP_PKEY_verify_recover(EVP_PKEY_CTX *ctx, - unsigned char *rout, size_t *routlen, - const unsigned char *sig, size_t siglen); + unsigned char *rout, size_t *routlen, + const unsigned char *sig, size_t siglen); =head1 DESCRIPTION @@ -29,7 +29,7 @@ B<rout> and the amount of data written to B<routlen>. =head1 NOTES Normally an application is only interested in whether a signature verification -operation is successful in those cases the EVP_verify() function should be +operation is successful in those cases the EVP_verify() function should be used. Sometimes however it is useful to obtain the data originally signed using a @@ -58,46 +58,55 @@ Recover digest originally signed using PKCS#1 and SHA256 digest: EVP_PKEY_CTX *ctx; unsigned char *rout, *sig; - size_t routlen, siglen; + size_t routlen, siglen; EVP_PKEY *verify_key; /* NB: assumes verify_key, sig and siglen are already set up * and that verify_key is an RSA public key */ ctx = EVP_PKEY_CTX_new(verify_key); if (!ctx) - /* Error occurred */ + /* Error occurred */ if (EVP_PKEY_verify_recover_init(ctx) <= 0) - /* Error */ + /* Error */ if (EVP_PKEY_CTX_set_rsa_padding(ctx, RSA_PKCS1_PADDING) <= 0) - /* Error */ + /* Error */ if (EVP_PKEY_CTX_set_signature_md(ctx, EVP_sha256()) <= 0) - /* Error */ + /* Error */ /* Determine buffer length */ if (EVP_PKEY_verify_recover(ctx, NULL, &routlen, sig, siglen) <= 0) - /* Error */ + /* Error */ rout = OPENSSL_malloc(routlen); if (!rout) - /* malloc failure */ - + /* malloc failure */ + if (EVP_PKEY_verify_recover(ctx, rout, &routlen, sig, siglen) <= 0) - /* Error */ + /* Error */ /* Recovered data is routlen bytes written to buffer rout */ =head1 SEE ALSO -L<EVP_PKEY_CTX_new(3)|EVP_PKEY_CTX_new(3)>, -L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, -L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, -L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, -L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, -L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> +L<EVP_PKEY_CTX_new(3)>, +L<EVP_PKEY_encrypt(3)>, +L<EVP_PKEY_decrypt(3)>, +L<EVP_PKEY_sign(3)>, +L<EVP_PKEY_verify(3)>, +L<EVP_PKEY_derive(3)> =head1 HISTORY These functions were first added to OpenSSL 1.0.0. +=head1 COPYRIGHT + +Copyright 2013-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_SealInit.pod b/deps/openssl/openssl/doc/crypto/EVP_SealInit.pod index 19112a542d..30bd6808c1 100644 --- a/deps/openssl/openssl/doc/crypto/EVP_SealInit.pod +++ b/deps/openssl/openssl/doc/crypto/EVP_SealInit.pod @@ -42,9 +42,9 @@ If the cipher does not require an IV then the B<iv> parameter is ignored and can be B<NULL>. EVP_SealUpdate() and EVP_SealFinal() have exactly the same properties -as the EVP_EncryptUpdate() and EVP_EncryptFinal() routines, as -documented on the L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> manual -page. +as the EVP_EncryptUpdate() and EVP_EncryptFinal() routines, as +documented on the L<EVP_EncryptInit(3)> manual +page. =head1 RETURN VALUES @@ -74,12 +74,17 @@ with B<type> set to NULL. =head1 SEE ALSO -L<evp(3)|evp(3)>, L<rand(3)|rand(3)>, -L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>, -L<EVP_OpenInit(3)|EVP_OpenInit(3)> +L<evp(3)>, L<rand(3)>, +L<EVP_EncryptInit(3)>, +L<EVP_OpenInit(3)> -=head1 HISTORY +=head1 COPYRIGHT -EVP_SealFinal() did not return a value before OpenSSL 0.9.7. +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_SignInit.pod b/deps/openssl/openssl/doc/crypto/EVP_SignInit.pod index c63d6b3393..21eb868b19 100644 --- a/deps/openssl/openssl/doc/crypto/EVP_SignInit.pod +++ b/deps/openssl/openssl/doc/crypto/EVP_SignInit.pod @@ -2,6 +2,7 @@ =head1 NAME +EVP_PKEY_size, EVP_SignInit, EVP_SignInit_ex, EVP_SignUpdate, EVP_SignFinal - EVP signing functions @@ -11,7 +12,7 @@ functions int EVP_SignInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl); int EVP_SignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); - int EVP_SignFinal(EVP_MD_CTX *ctx,unsigned char *sig,unsigned int *s, EVP_PKEY *pkey); + int EVP_SignFinal(EVP_MD_CTX *ctx, unsigned char *sig, unsigned int *s, EVP_PKEY *pkey); void EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type); @@ -23,8 +24,8 @@ The EVP signature routines are a high level interface to digital signatures. EVP_SignInit_ex() sets up signing context B<ctx> to use digest -B<type> from ENGINE B<impl>. B<ctx> must be initialized with -EVP_MD_CTX_init() before calling this function. +B<type> from ENGINE B<impl>. B<ctx> must be created with +EVP_MD_CTX_new() before calling this function. EVP_SignUpdate() hashes B<cnt> bytes of data at B<d> into the signature context B<ctx>. This function can be called several times on the @@ -32,7 +33,7 @@ same B<ctx> to include additional data. EVP_SignFinal() signs the data in B<ctx> using the private key B<pkey> and places the signature in B<sig>. B<sig> must be at least EVP_PKEY_size(pkey) -bytes in size. B<s> is an OUT paramter, and not used as an IN parameter. +bytes in size. B<s> is an OUT parameter, and not used as an IN parameter. The number of bytes of data written (i.e. the length of the signature) will be written to the integer at B<s>, at most EVP_PKEY_size(pkey) bytes will be written. @@ -50,7 +51,7 @@ for success and 0 for failure. EVP_PKEY_size() returns the maximum size of a signature in bytes. -The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. +The error codes can be obtained by L<ERR_get_error(3)>. =head1 NOTES @@ -58,11 +59,6 @@ The B<EVP> interface to digital signatures should almost always be used in preference to the low level interfaces. This is because the code then becomes transparent to the algorithm used and much more flexible. -Due to the link between message digests and public key algorithms the correct -digest algorithm must be used with the correct public key type. A list of -algorithms and associated public key algorithms appears in -L<EVP_DigestInit(3)|EVP_DigestInit(3)>. - When signing with DSA private keys the random number generator must be seeded or the operation will fail. The random number generator does not need to be seeded for RSA signatures. @@ -77,7 +73,7 @@ will occur. =head1 BUGS -Older versions of this documentation wrongly stated that calls to +Older versions of this documentation wrongly stated that calls to EVP_SignUpdate() could not be made after calling EVP_SignFinal(). Since the private key is passed in the call to EVP_SignFinal() any error @@ -91,17 +87,19 @@ The previous two bugs are fixed in the newer EVP_SignDigest*() function. =head1 SEE ALSO -L<EVP_VerifyInit(3)|EVP_VerifyInit(3)>, -L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>, -L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, -L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, -L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)> +L<EVP_VerifyInit(3)>, +L<EVP_DigestInit(3)>, +L<evp(7)>, L<HMAC(3)>, L<MD2(3)>, +L<MD5(3)>, L<MDC2(3)>, L<RIPEMD160(3)>, +L<SHA1(3)>, L<dgst(1)> -=head1 HISTORY +=head1 COPYRIGHT -EVP_SignInit(), EVP_SignUpdate() and EVP_SignFinal() are -available in all versions of SSLeay and OpenSSL. +Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. -EVP_SignInit_ex() was added in OpenSSL 0.9.7. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/EVP_VerifyInit.pod b/deps/openssl/openssl/doc/crypto/EVP_VerifyInit.pod index 9097f09410..92146098a8 100644 --- a/deps/openssl/openssl/doc/crypto/EVP_VerifyInit.pod +++ b/deps/openssl/openssl/doc/crypto/EVP_VerifyInit.pod @@ -2,7 +2,9 @@ =head1 NAME -EVP_VerifyInit, EVP_VerifyUpdate, EVP_VerifyFinal - EVP signature verification functions +EVP_VerifyInit_ex, +EVP_VerifyInit, EVP_VerifyUpdate, EVP_VerifyFinal +- EVP signature verification functions =head1 SYNOPSIS @@ -10,7 +12,7 @@ EVP_VerifyInit, EVP_VerifyUpdate, EVP_VerifyFinal - EVP signature verification f int EVP_VerifyInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl); int EVP_VerifyUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); - int EVP_VerifyFinal(EVP_MD_CTX *ctx,unsigned char *sigbuf, unsigned int siglen,EVP_PKEY *pkey); + int EVP_VerifyFinal(EVP_MD_CTX *ctx, unsigned char *sigbuf, unsigned int siglen, EVP_PKEY *pkey); int EVP_VerifyInit(EVP_MD_CTX *ctx, const EVP_MD *type); @@ -20,8 +22,8 @@ The EVP signature verification routines are a high level interface to digital signatures. EVP_VerifyInit_ex() sets up verification context B<ctx> to use digest -B<type> from ENGINE B<impl>. B<ctx> must be initialized by calling -EVP_MD_CTX_init() before calling this function. +B<type> from ENGINE B<impl>. B<ctx> must be created by calling +EVP_MD_CTX_new() before calling this function. EVP_VerifyUpdate() hashes B<cnt> bytes of data at B<d> into the verification context B<ctx>. This function can be called several times on the @@ -41,7 +43,7 @@ failure. EVP_VerifyFinal() returns 1 for a correct signature, 0 for failure and -1 if some other error occurred. -The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. +The error codes can be obtained by L<ERR_get_error(3)>. =head1 NOTES @@ -49,11 +51,6 @@ The B<EVP> interface to digital signatures should almost always be used in preference to the low level interfaces. This is because the code then becomes transparent to the algorithm used and much more flexible. -Due to the link between message digests and public key algorithms the correct -digest algorithm must be used with the correct public key type. A list of -algorithms and associated public key algorithms appears in -L<EVP_DigestInit(3)|EVP_DigestInit(3)>. - The call to EVP_VerifyFinal() internally finalizes a copy of the digest context. This means that calls to EVP_VerifyUpdate() and EVP_VerifyFinal() can be called later to digest and verify additional data. @@ -64,7 +61,7 @@ will occur. =head1 BUGS -Older versions of this documentation wrongly stated that calls to +Older versions of this documentation wrongly stated that calls to EVP_VerifyUpdate() could not be made after calling EVP_VerifyFinal(). Since the public key is passed in the call to EVP_SignFinal() any error @@ -78,18 +75,20 @@ The previous two bugs are fixed in the newer EVP_VerifyDigest*() function. =head1 SEE ALSO -L<evp(3)|evp(3)>, -L<EVP_SignInit(3)|EVP_SignInit(3)>, -L<EVP_DigestInit(3)|EVP_DigestInit(3)>, L<err(3)|err(3)>, -L<evp(3)|evp(3)>, L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, -L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, -L<sha(3)|sha(3)>, L<dgst(1)|dgst(1)> +L<evp(7)>, +L<EVP_SignInit(3)>, +L<EVP_DigestInit(3)>, +L<evp(7)>, L<HMAC(3)>, L<MD2(3)>, +L<MD5(3)>, L<MDC2(3)>, L<RIPEMD160(3)>, +L<SHA1(3)>, L<dgst(1)> -=head1 HISTORY +=head1 COPYRIGHT -EVP_VerifyInit(), EVP_VerifyUpdate() and EVP_VerifyFinal() are -available in all versions of SSLeay and OpenSSL. +Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. -EVP_VerifyInit_ex() was added in OpenSSL 0.9.7 +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/hmac.pod b/deps/openssl/openssl/doc/crypto/HMAC.pod index ca9798af62..219c9ba208 100644 --- a/deps/openssl/openssl/doc/crypto/hmac.pod +++ b/deps/openssl/openssl/doc/crypto/HMAC.pod @@ -2,8 +2,18 @@ =head1 NAME -HMAC, HMAC_CTX_init, HMAC_Init, HMAC_Init_ex, HMAC_Update, HMAC_Final, HMAC_CTX_cleanup, -HMAC_cleanup - HMAC message authentication code +HMAC, +HMAC_CTX_new, +HMAC_CTX_reset, +HMAC_CTX_free, +HMAC_Init, +HMAC_Init_ex, +HMAC_Update, +HMAC_Final, +HMAC_CTX_copy, +HMAC_CTX_set_flags, +HMAC_CTX_get_md +- HMAC message authentication code =head1 SYNOPSIS @@ -13,17 +23,26 @@ HMAC_cleanup - HMAC message authentication code int key_len, const unsigned char *d, int n, unsigned char *md, unsigned int *md_len); - void HMAC_CTX_init(HMAC_CTX *ctx); + HMAC_CTX *HMAC_CTX_new(void); + int HMAC_CTX_reset(HMAC_CTX *ctx); - int HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len, - const EVP_MD *md); int HMAC_Init_ex(HMAC_CTX *ctx, const void *key, int key_len, - const EVP_MD *md, ENGINE *impl); + const EVP_MD *md, ENGINE *impl); int HMAC_Update(HMAC_CTX *ctx, const unsigned char *data, int len); int HMAC_Final(HMAC_CTX *ctx, unsigned char *md, unsigned int *len); - void HMAC_CTX_cleanup(HMAC_CTX *ctx); - void HMAC_cleanup(HMAC_CTX *ctx); + void HMAC_CTX_free(HMAC_CTX *ctx); + + int HMAC_CTX_copy(HMAC_CTX *dctx, HMAC_CTX *sctx); + void HMAC_CTX_set_flags(HMAC_CTX *ctx, unsigned long flags); + const EVP_MD *HMAC_CTX_get_md(const HMAC_CTX *ctx); + +Deprecated: + + #if OPENSSL_API_COMPAT < 0x10100000L + int HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len, + const EVP_MD *md); + #endif =head1 DESCRIPTION @@ -43,15 +62,15 @@ value for B<md> to use the static array is not thread safe. B<evp_md> can be EVP_sha1(), EVP_ripemd160() etc. -HMAC_CTX_init() initialises a B<HMAC_CTX> before first use. It must be -called. +HMAC_CTX_new() creates a new HMAC_CTX in heap memory. -HMAC_CTX_cleanup() erases the key and other data from the B<HMAC_CTX> -and releases any associated resources. It must be called when an -B<HMAC_CTX> is no longer required. +HMAC_CTX_reset() zeroes an existing B<HMAC_CTX> and associated +resources, making it suitable for new computations as if it was newly +created with HMAC_CTX_new(). -HMAC_cleanup() is an alias for HMAC_CTX_cleanup() included for back -compatibility with 0.9.6b, it is deprecated. +HMAC_CTX_free() erases the key and other data from the B<HMAC_CTX>, +releases any associated resources and finally frees the B<HMAC_CTX> +itself. The following functions may be used if the message is not completely stored in memory: @@ -69,9 +88,9 @@ of an B<HMAC_CTX> in this function. B<N.B. HMAC_Init() had this undocumented behaviour in previous versions of OpenSSL - failure to switch to HMAC_Init_ex() in programs that expect it will cause them to stop working>. -B<NB: if HMAC_Init_ex() is called with B<key> NULL and B<evp_md> is not the +B<NOTE:> If HMAC_Init_ex() is called with B<key> NULL and B<evp_md> is not the same as the previous digest used by B<ctx> then an error is returned -because reuse of an existing key with a different digest is not supported.> +because reuse of an existing key with a different digest is not supported. HMAC_Update() can be called repeatedly with chunks of the message to be authenticated (B<len> bytes at B<data>). @@ -79,15 +98,27 @@ be authenticated (B<len> bytes at B<data>). HMAC_Final() places the message authentication code in B<md>, which must have space for the hash function output. +HMAC_CTX_copy() copies all of the internal state from B<sctx> into B<dctx>. + +HMAC_CTX_set_flags() applies the specified flags to the internal EVP_MD_CTXs. +These flags have the same meaning as for L<EVP_MD_CTX_set_flags(3)>. + +HMAC_CTX_get_md() returns the EVP_MD that has previously been set for the +supplied HMAC_CTX. + =head1 RETURN VALUES HMAC() returns a pointer to the message authentication code or NULL if an error occurred. -HMAC_Init_ex(), HMAC_Update() and HMAC_Final() return 1 for success or 0 if -an error occurred. +HMAC_CTX_new() returns a pointer to a new B<HMAC_CTX> on success or +B<NULL> if an error occurred. + +HMAC_CTX_reset(), HMAC_Init_ex(), HMAC_Update(), HMAC_Final() and +HMAC_CTX_copy() return 1 for success or 0 if an error occurred. -HMAC_CTX_init() and HMAC_CTX_cleanup() do not return values. +HMAC_CTX_get_md() return the EVP_MD previously set for the supplied HMAC_CTX or +NULL if no EVP_MD has been set. =head1 CONFORMING TO @@ -95,17 +126,27 @@ RFC 2104 =head1 SEE ALSO -L<sha(3)|sha(3)>, L<evp(3)|evp(3)> +L<sha(3)>, L<evp(3)> =head1 HISTORY -HMAC(), HMAC_Init(), HMAC_Update(), HMAC_Final() and HMAC_cleanup() -are available since SSLeay 0.9.0. +HMAC_CTX_init() was replaced with HMAC_CTX_reset() in OpenSSL versions 1.1.0. -HMAC_CTX_init(), HMAC_Init_ex() and HMAC_CTX_cleanup() are available -since OpenSSL 0.9.7. +HMAC_CTX_cleanup() existed in OpenSSL versions before 1.1.0. + +HMAC_CTX_new(), HMAC_CTX_free() and HMAC_CTX_get_md() are new in OpenSSL version +1.1.0. HMAC_Init_ex(), HMAC_Update() and HMAC_Final() did not return values in versions of OpenSSL before 1.0.0. +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/md5.pod b/deps/openssl/openssl/doc/crypto/MD5.pod index d11d5c32cb..78da750796 100644 --- a/deps/openssl/openssl/doc/crypto/md5.pod +++ b/deps/openssl/openssl/doc/crypto/MD5.pod @@ -64,7 +64,7 @@ MD4_Init(), MD4_Update(), MD4_Final(), MD5_Init(), MD5_Update(), and MD5_Final() are analogous using an B<MD4_CTX> and B<MD5_CTX> structure. Applications should use the higher level functions -L<EVP_DigestInit(3)|EVP_DigestInit(3)> +L<EVP_DigestInit(3)> etc. instead of calling the hash functions directly. =head1 NOTE @@ -75,7 +75,7 @@ preferred. =head1 RETURN VALUES -MD2(), MD4(), and MD5() return pointers to the hash value. +MD2(), MD4(), and MD5() return pointers to the hash value. MD2_Init(), MD2_Update(), MD2_Final(), MD4_Init(), MD4_Update(), MD4_Final(), MD5_Init(), MD5_Update(), and MD5_Final() return 1 for @@ -87,15 +87,15 @@ RFC 1319, RFC 1320, RFC 1321 =head1 SEE ALSO -L<sha(3)|sha(3)>, L<ripemd(3)|ripemd(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)> +L<EVP_DigestInit(3)> -=head1 HISTORY +=head1 COPYRIGHT -MD2(), MD2_Init(), MD2_Update() MD2_Final(), MD5(), MD5_Init(), -MD5_Update() and MD5_Final() are available in all versions of SSLeay -and OpenSSL. +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. -MD4(), MD4_Init(), and MD4_Update() are available in OpenSSL 0.9.6 and -above. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/mdc2.pod b/deps/openssl/openssl/doc/crypto/MDC2_Init.pod index 41f648af36..f7db71b460 100644 --- a/deps/openssl/openssl/doc/crypto/mdc2.pod +++ b/deps/openssl/openssl/doc/crypto/MDC2_Init.pod @@ -39,12 +39,12 @@ MDC2_Final() places the message digest in B<md>, which must have space for MDC2_DIGEST_LENGTH == 16 bytes of output, and erases the B<MDC2_CTX>. Applications should use the higher level functions -L<EVP_DigestInit(3)|EVP_DigestInit(3)> etc. instead of calling the +L<EVP_DigestInit(3)> etc. instead of calling the hash functions directly. =head1 RETURN VALUES -MDC2() returns a pointer to the hash value. +MDC2() returns a pointer to the hash value. MDC2_Init(), MDC2_Update() and MDC2_Final() return 1 for success, 0 otherwise. @@ -54,11 +54,15 @@ ISO/IEC 10118-2, with DES =head1 SEE ALSO -L<sha(3)|sha(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)> +L<EVP_DigestInit(3)> -=head1 HISTORY +=head1 COPYRIGHT -MDC2(), MDC2_Init(), MDC2_Update() and MDC2_Final() are available since -SSLeay 0.8. +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/OBJ_nid2obj.pod b/deps/openssl/openssl/doc/crypto/OBJ_nid2obj.pod index b8d289673d..3ada6679cf 100644 --- a/deps/openssl/openssl/doc/crypto/OBJ_nid2obj.pod +++ b/deps/openssl/openssl/doc/crypto/OBJ_nid2obj.pod @@ -2,17 +2,19 @@ =head1 NAME -OBJ_nid2obj, OBJ_nid2ln, OBJ_nid2sn, OBJ_obj2nid, OBJ_txt2nid, OBJ_ln2nid, OBJ_sn2nid, -OBJ_cmp, OBJ_dup, OBJ_txt2obj, OBJ_obj2txt, OBJ_create, OBJ_cleanup - ASN1 object utility -functions +i2t_ASN1_OBJECT, +OBJ_length, OBJ_get0_data, OBJ_nid2obj, OBJ_nid2ln, +OBJ_nid2sn, OBJ_obj2nid, OBJ_txt2nid, OBJ_ln2nid, OBJ_sn2nid, OBJ_cmp, +OBJ_dup, OBJ_txt2obj, OBJ_obj2txt, OBJ_create, OBJ_cleanup +- ASN1 object utility functions =head1 SYNOPSIS #include <openssl/objects.h> - ASN1_OBJECT * OBJ_nid2obj(int n); - const char * OBJ_nid2ln(int n); - const char * OBJ_nid2sn(int n); + ASN1_OBJECT *OBJ_nid2obj(int n); + const char *OBJ_nid2ln(int n); + const char *OBJ_nid2sn(int n); int OBJ_obj2nid(const ASN1_OBJECT *o); int OBJ_ln2nid(const char *ln); @@ -20,14 +22,24 @@ functions int OBJ_txt2nid(const char *s); - ASN1_OBJECT * OBJ_txt2obj(const char *s, int no_name); + ASN1_OBJECT *OBJ_txt2obj(const char *s, int no_name); int OBJ_obj2txt(char *buf, int buf_len, const ASN1_OBJECT *a, int no_name); - int OBJ_cmp(const ASN1_OBJECT *a,const ASN1_OBJECT *b); - ASN1_OBJECT * OBJ_dup(const ASN1_OBJECT *o); + int i2t_ASN1_OBJECT(char *buf, int buf_len, const ASN1_OBJECT *a); - int OBJ_create(const char *oid,const char *sn,const char *ln); - void OBJ_cleanup(void); + int OBJ_cmp(const ASN1_OBJECT *a, const ASN1_OBJECT *b); + ASN1_OBJECT *OBJ_dup(const ASN1_OBJECT *o); + + int OBJ_create(const char *oid, const char *sn, const char *ln); + + size_t OBJ_length(const ASN1_OBJECT *obj); + const unsigned char *OBJ_get0_data(const ASN1_OBJECT *obj); + +Deprecated: + + #if OPENSSL_API_COMPAT < 0x10100000L + void OBJ_cleanup(void) + #endif =head1 DESCRIPTION @@ -40,7 +52,7 @@ are available as defined constants. For the functions below, application code should treat all returned values -- OIDs, NIDs, or names -- as constants. -OBJ_nid2obj(), OBJ_nid2ln() and OBJ_nid2sn() convert the NID B<n> to +OBJ_nid2obj(), OBJ_nid2ln() and OBJ_nid2sn() convert the NID B<n> to an ASN1_OBJECT structure, its long name and its short name respectively, or B<NULL> is an error occurred. @@ -49,7 +61,7 @@ for the object B<o>, the long name <ln> or the short name <sn> respectively or NID_undef if an error occurred. OBJ_txt2nid() returns NID corresponding to text string <s>. B<s> can be -a long name, a short name or the numerical respresentation of an object. +a long name, a short name or the numerical representation of an object. OBJ_txt2obj() converts the text string B<s> into an ASN1_OBJECT structure. If B<no_name> is 0 then long names and short names will be interpreted @@ -64,17 +76,26 @@ if the object has a long or short name then that will be used, otherwise the numerical form will be used. If B<no_name> is 1 then the numerical form will always be used. +i2t_ASN1_OBJECT() is the same as OBJ_obj2txt() with the B<no_name> set to zero. + OBJ_cmp() compares B<a> to B<b>. If the two are identical 0 is returned. OBJ_dup() returns a copy of B<o>. -OBJ_create() adds a new object to the internal table. B<oid> is the +OBJ_create() adds a new object to the internal table. B<oid> is the numerical form of the object, B<sn> the short name and B<ln> the long name. A new NID is returned for the created object. -OBJ_cleanup() cleans up OpenSSLs internal object table: this should -be called before an application exits if any new objects were added -using OBJ_create(). +OBJ_length() returns the size of the content octets of B<obj>. + +OBJ_get0_data() returns a pointer to the content octets of B<obj>. +The returned pointer is an internal pointer which B<must not> be freed. + +In OpenSSL versions prior to 1.1.0 OBJ_cleanup() cleaned up OpenSSLs internal +object table and was called before an application exits if any new objects were +added using OBJ_create(). This function is deprecated in version 1.1.0 and now +does nothing if called. No explicit de-initialisation is now required. See +L<OPENSSL_init_crypto(3)> for further information. =head1 NOTES @@ -132,14 +153,14 @@ Create a new NID and initialize an object from it: new_nid = OBJ_create("1.2.3.4", "NewOID", "New Object Identifier"); obj = OBJ_nid2obj(new_nid); - + Create a new object directly: obj = OBJ_txt2obj("1.2.3.4", 1); =head1 BUGS -OBJ_obj2txt() is awkward and messy to use: it doesn't follow the +OBJ_obj2txt() is awkward and messy to use: it doesn't follow the convention of other OpenSSL functions where the buffer can be set to B<NULL> to determine the amount of data that should be written. Instead B<buf> must point to a valid buffer and B<buf_len> should @@ -150,8 +171,6 @@ than enough to handle any OID encountered in practice. OBJ_nid2obj() returns an B<ASN1_OBJECT> structure or B<NULL> is an error occurred. -It returns a pointer to an internal table and does not -allocate memory; ASN1_OBJECT_free() will have no effect. OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B<NULL> on error. @@ -161,10 +180,19 @@ a NID or B<NID_undef> on error. =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)> +L<ERR_get_error(3)> =head1 HISTORY -TBA +OBJ_cleanup() was deprecated in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/OCSP_REQUEST_new.pod b/deps/openssl/openssl/doc/crypto/OCSP_REQUEST_new.pod new file mode 100644 index 0000000000..97c2337d10 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/OCSP_REQUEST_new.pod @@ -0,0 +1,118 @@ +=pod + +=head1 NAME + +OCSP_REQUEST_new, OCSP_REQUEST_free, OCSP_request_add0_id, OCSP_request_sign, +OCSP_request_add1_cert, OCSP_request_onereq_count, +OCSP_request_onereq_get0 - OCSP request functions + +=head1 SYNOPSIS + + #include <openssl/ocsp.h> + + OCSP_REQUEST *OCSP_REQUEST_new(void); + void OCSP_REQUEST_free(OCSP_REQUEST *req); + + OCSP_ONEREQ *OCSP_request_add0_id(OCSP_REQUEST *req, OCSP_CERTID *cid); + + int OCSP_request_sign(OCSP_REQUEST *req, + X509 *signer, EVP_PKEY *key, const EVP_MD *dgst, + STACK_OF(X509) *certs, unsigned long flags); + + int OCSP_request_add1_cert(OCSP_REQUEST *req, X509 *cert); + + int OCSP_request_onereq_count(OCSP_REQUEST *req); + OCSP_ONEREQ *OCSP_request_onereq_get0(OCSP_REQUEST *req, int i); + +=head1 DESCRIPTION + +OCSP_REQUEST_new() allocates and returns an empty B<OCSP_REQUEST> structure. + +OCSP_REQUEST_free() frees up the request structure B<req>. + +OCSP_request_add0_id() adds certificate ID B<cid> to B<req>. It returns +the B<OCSP_ONEREQ> structure added so an application can add additional +extensions to the request. The B<id> parameter B<MUST NOT> be freed up after +the operation. + +OCSP_request_sign() signs OCSP request B<req> using certificate +B<signer>, private key B<key>, digest B<dgst> and additional certificates +B<certs>. If the B<flags> option B<OCSP_NOCERTS> is set then no certificates +will be included in the request. + +OCSP_request_add1_cert() adds certificate B<cert> to request B<req>. The +application is responsible for freeing up B<cert> after use. + +OCSP_request_onereq_count() returns the total number of B<OCSP_ONEREQ> +structures in B<req>. + +OCSP_request_onereq_get0() returns an internal pointer to the B<OCSP_ONEREQ> +contained in B<req> of index B<i>. The index value B<i> runs from 0 to +OCSP_request_onereq_count(req) - 1. + +=head1 RETURN VALUES + +OCSP_REQUEST_new() returns an empty B<OCSP_REQUEST> structure or B<NULL> if +an error occurred. + +OCSP_request_add0_id() returns the B<OCSP_ONEREQ> structure containing B<cid> +or B<NULL> if an error occurred. + +OCSP_request_sign() and OCSP_request_add1_cert() return 1 for success and 0 +for failure. + +OCSP_request_onereq_count() returns the total number of B<OCSP_ONEREQ> +structures in B<req>. + +OCSP_request_onereq_get0() returns a pointer to an B<OCSP_ONEREQ> structure +or B<NULL> if the index value is out or range. + +=head1 NOTES + +An OCSP request structure contains one or more B<OCSP_ONEREQ> structures +corresponding to each certificate. + +OCSP_request_onereq_count() and OCSP_request_onereq_get0() are mainly used by +OCSP responders. + +=head1 EXAMPLE + +Create an B<OCSP_REQUEST> structure for certificate B<cert> with issuer +B<issuer>: + + OCSP_REQUEST *req; + OCSP_ID *cid; + + req = OCSP_REQUEST_new(); + if (req == NULL) + /* error */ + cid = OCSP_cert_to_id(EVP_sha1(), cert, issuer); + if (cid == NULL) + /* error */ + + if (OCSP_REQUEST_add0_id(req, cid) == NULL) + /* error */ + + /* Do something with req, e.g. query responder */ + + OCSP_REQUEST_free(req); + +=head1 SEE ALSO + +L<crypto(3)>, +L<OCSP_cert_to_id(3)>, +L<OCSP_request_add1_nonce(3)>, +L<OCSP_response_find_status(3)>, +L<OCSP_response_status(3)>, +L<OCSP_sendreq_new(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/OCSP_cert_to_id.pod b/deps/openssl/openssl/doc/crypto/OCSP_cert_to_id.pod new file mode 100644 index 0000000000..0e37937fea --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/OCSP_cert_to_id.pod @@ -0,0 +1,89 @@ +=pod + +=head1 NAME + +OCSP_cert_to_id, OCSP_cert_id_new, OCSP_CERTID_free, OCSP_id_issuer_cmp, +OCSP_id_cmp, OCSP_id_get0_info - OCSP certificate ID utility functions + +=head1 SYNOPSIS + + #include <openssl/ocsp.h> + + OCSP_CERTID *OCSP_cert_to_id(const EVP_MD *dgst, + X509 *subject, X509 *issuer); + + OCSP_CERTID *OCSP_cert_id_new(const EVP_MD *dgst, + X509_NAME *issuerName, + ASN1_BIT_STRING *issuerKey, + ASN1_INTEGER *serialNumber); + + void OCSP_CERTID_free(OCSP_CERTID *id); + + int OCSP_id_issuer_cmp(OCSP_CERTID *a, OCSP_CERTID *b); + int OCSP_id_cmp(OCSP_CERTID *a, OCSP_CERTID *b); + + int OCSP_id_get0_info(ASN1_OCTET_STRING **piNameHash, ASN1_OBJECT **pmd, + ASN1_OCTET_STRING **pikeyHash, + ASN1_INTEGER **pserial, OCSP_CERTID *cid); + + +=head1 DESCRIPTION + +OCSP_cert_to_id() creates and returns a new B<OCSP_CERTID> structure using +message digest B<dgst> for certificate B<subject> with issuer B<issuer>. If +B<dgst> is B<NULL> then SHA1 is used. + +OCSP_cert_id_new() creates and returns a new B<OCSP_CERTID> using B<dgst> and +issuer name B<issuerName>, issuer key hash B<issuerKey> and serial number +B<serialNumber>. + +OCSP_CERTID_free() frees up B<id>. + +OCSP_id_cmp() compares B<OCSP_CERTID> B<a> and B<b>. + +OCSP_id_issuer_cmp() compares only the issuer name of B<OCSP_CERTID> B<a> and B<b>. + +OCSP_id_get0_info() returns the issuer name hash, hash OID, issuer key hash and +serial number contained in B<cid>. If any of the values are not required the +corresponding parameter can be set to B<NULL>. + +=head1 RETURN VALUES + +OCSP_cert_to_id() and OCSP_cert_id_new() return either a pointer to a valid +B<OCSP_CERTID> structure or B<NULL> if an error occurred. + +OCSP_id_cmp() and OCSP_id_issuer_cmp() returns zero for a match and non-zero +otherwise. + +OCSP_CERTID_free() does not return a value. + +OCSP_id_get0_info() returns 1 for success and 0 for failure. + +=head1 NOTES + +OCSP clients will typically only use OCSP_cert_to_id() or OCSP_cert_id_new(): +the other functions are used by responder applications. + +The values returned by OCSP_id_get0_info() are internal pointers and B<MUST +NOT> be freed up by an application: they will be freed when the corresponding +B<OCSP_CERTID> structure is freed. + +=head1 SEE ALSO + +L<crypto(3)>, +L<OCSP_request_add1_nonce(3)>, +L<OCSP_REQUEST_new(3)>, +L<OCSP_response_find_status(3)>, +L<OCSP_response_status(3)>, +L<OCSP_sendreq_new(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/OCSP_request_add1_nonce.pod b/deps/openssl/openssl/doc/crypto/OCSP_request_add1_nonce.pod new file mode 100644 index 0000000000..dab42c67be --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/OCSP_request_add1_nonce.pod @@ -0,0 +1,84 @@ +=pod + +=head1 NAME + +OCSP_request_add1_nonce, OCSP_basic_add1_nonce, OCSP_check_nonce, OCSP_copy_nonce - OCSP nonce functions + +=head1 SYNOPSIS + + #include <openssl/ocsp.h> + + int OCSP_request_add1_nonce(OCSP_REQUEST *req, unsigned char *val, int len); + int OCSP_basic_add1_nonce(OCSP_BASICRESP *resp, unsigned char *val, int len); + int OCSP_copy_nonce(OCSP_BASICRESP *resp, OCSP_REQUEST *req); + int OCSP_check_nonce(OCSP_REQUEST *req, OCSP_BASICRESP *resp); + +=head1 DESCRIPTION + +OCSP_request_add1_nonce() adds a nonce of value B<val> and length B<len> to +OCSP request B<req>. If B<val> is B<NULL> a random nonce is used. If B<len> +is zero or negative a default length will be used (currently 16 bytes). + +OCSP_basic_add1_nonce() is identical to OCSP_request_add1_nonce() except +it adds a nonce to OCSP basic response B<resp>. + +OCSP_check_nonce() compares the nonce value in B<req> and B<resp>. + +OCSP_copy_nonce() copys any nonce value present in B<req> to B<resp>. + +=head1 RETURN VALUES + +OCSP_request_add1_nonce() and OCSP_basic_add1_nonce() return 1 for success +and 0 for failure. + +OCSP_copy_nonce() returns 1 if a nonce was successfully copied, 2 if no nonce +was present in B<req> and 0 if an error occurred. + +OCSP_check_nonce() returns the result of the nonce comparison between B<req> +and B<resp>. The return value indicates the result of the comparison. If +nonces are present and equal 1 is returned. If the nonces are absent 2 is +returned. If a nonce is present in the response only 3 is returned. If nonces +are present and unequal 0 is returned. If the nonce is present in the request +only then -1 is returned. + +=head1 NOTES + +For most purposes the nonce value in a request is set to a random value so +the B<val> parameter in OCSP_request_add1_nonce() is usually NULL. + +An OCSP nonce is typically added to an OCSP request to thwart replay attacks +by checking the same nonce value appears in the response. + +Some responders may include a nonce in all responses even if one is not +supplied. + +Some responders cache OCSP responses and do not sign each response for +performance reasons. As a result they do not support nonces. + +The return values of OCSP_check_nonce() can be checked to cover each case. A +positive return value effectively indicates success: nonces are both present +and match, both absent or present in the response only. A non-zero return +additionally covers the case where the nonce is present in the request only: +this will happen if the responder doesn't support nonces. A zero return value +indicates present and mismatched nonces: this should be treated as an error +condition. + +=head1 SEE ALSO + +L<crypto(3)>, +L<OCSP_cert_to_id(3)>, +L<OCSP_REQUEST_new(3)>, +L<OCSP_response_find_status(3)>, +L<OCSP_response_status(3)>, +L<OCSP_sendreq_new(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/OCSP_resp_find_status.pod b/deps/openssl/openssl/doc/crypto/OCSP_resp_find_status.pod new file mode 100644 index 0000000000..5123f0ad6d --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/OCSP_resp_find_status.pod @@ -0,0 +1,152 @@ +=pod + +=head1 NAME + +OCSP_resp_get0_certs, +OCSP_resp_get0_signer, +OCSP_resp_get0_id, +OCSP_resp_get0_produced_at, +OCSP_resp_find_status, OCSP_resp_count, OCSP_resp_get0, OCSP_resp_find, +OCSP_single_get0_status, OCSP_check_validity +- OCSP response utility functions + +=head1 SYNOPSIS + + #include <openssl/ocsp.h> + + int OCSP_resp_find_status(OCSP_BASICRESP *bs, OCSP_CERTID *id, int *status, + int *reason, + ASN1_GENERALIZEDTIME **revtime, + ASN1_GENERALIZEDTIME **thisupd, + ASN1_GENERALIZEDTIME **nextupd); + + int OCSP_resp_count(OCSP_BASICRESP *bs); + OCSP_SINGLERESP *OCSP_resp_get0(OCSP_BASICRESP *bs, int idx); + int OCSP_resp_find(OCSP_BASICRESP *bs, OCSP_CERTID *id, int last); + int OCSP_single_get0_status(OCSP_SINGLERESP *single, int *reason, + ASN1_GENERALIZEDTIME **revtime, + ASN1_GENERALIZEDTIME **thisupd, + ASN1_GENERALIZEDTIME **nextupd); + + const ASN1_GENERALIZEDTIME *OCSP_resp_get0_produced_at( + const OCSP_BASICRESP* single); + + const STACK_OF(X509) *OCSP_resp_get0_certs(const OCSP_BASICRESP *bs); + + int OCSP_resp_get0_signer(OCSP_BASICRESP *bs, X509 **signer, + STACK_OF(X509) *extra_certs); + + int OCSP_resp_get0_id(const OCSP_BASICRESP *bs, + const ASN1_OCTET_STRING **pid, + const X509_NAME **pname); + + int OCSP_check_validity(ASN1_GENERALIZEDTIME *thisupd, + ASN1_GENERALIZEDTIME *nextupd, + long sec, long maxsec); + +=head1 DESCRIPTION + +OCSP_resp_find_status() searches B<bs> for an OCSP response for B<id>. If it is +successful the fields of the response are returned in B<*status>, B<*reason>, +B<*revtime>, B<*thisupd> and B<*nextupd>. The B<*status> value will be one of +B<V_OCSP_CERTSTATUS_GOOD>, B<V_OCSP_CERTSTATUS_REVOKED> or +B<V_OCSP_CERTSTATUS_UNKNOWN>. The B<*reason> and B<*revtime> fields are only +set if the status is B<V_OCSP_CERTSTATUS_REVOKED>. If set the B<*reason> field +will be set to the revocation reason which will be one of +B<OCSP_REVOKED_STATUS_NOSTATUS>, B<OCSP_REVOKED_STATUS_UNSPECIFIED>, +B<OCSP_REVOKED_STATUS_KEYCOMPROMISE>, B<OCSP_REVOKED_STATUS_CACOMPROMISE>, +B<OCSP_REVOKED_STATUS_AFFILIATIONCHANGED>, B<OCSP_REVOKED_STATUS_SUPERSEDED>, +B<OCSP_REVOKED_STATUS_CESSATIONOFOPERATION>, +B<OCSP_REVOKED_STATUS_CERTIFICATEHOLD> or B<OCSP_REVOKED_STATUS_REMOVEFROMCRL>. + +OCSP_resp_count() returns the number of B<OCSP_SINGLERESP> structures in B<bs>. + +OCSP_resp_get0() returns the B<OCSP_SINGLERESP> structure in B<bs> +corresponding to index B<idx>. Where B<idx> runs from 0 to +OCSP_resp_count(bs) - 1. + +OCSP_resp_find() searches B<bs> for B<id> and returns the index of the first +matching entry after B<last> or starting from the beginning if B<last> is -1. + +OCSP_single_get0_status() extracts the fields of B<single> in B<*reason>, +B<*revtime>, B<*thisupd> and B<*nextupd>. + +OCSP_resp_get0_produced_at() extracts the B<producedAt> field from the +single response B<bs>. + +OCSP_resp_get0_certs() returns any certificates included in B<bs>. + +OCSP_resp_get0_signer() attempts to retrieve the certificate that directly +signed B<bs>. The OCSP protocol does not require that this certificate +is included in the B<certs> field of the response, so additional certificates +can be supplied in B<extra_certs> if the certificates that may have +signed the response are known via some out-of-band mechanism. + +OCSP_resp_get0_id() gets the responder id of B<bs>. If the responder ID is +a name then <*pname> is set to the name and B<*pid> is set to NULL. If the +responder ID is by key ID then B<*pid> is set to the key ID and B<*pname> +is set to NULL. + +OCSP_check_validity() checks the validity of B<thisupd> and B<nextupd> values +which will be typically obtained from OCSP_resp_find_status() or +OCSP_single_get0_status(). If B<sec> is non-zero it indicates how many seconds +leeway should be allowed in the check. If B<maxsec> is positive it indicates +the maximum age of B<thisupd> in seconds. + +=head1 RETURN VALUES + +OCSP_resp_find_status() returns 1 if B<id> is found in B<bs> and 0 otherwise. + +OCSP_resp_count() returns the total number of B<OCSP_SINGLERESP> fields in +B<bs>. + +OCSP_resp_get0() returns a pointer to an B<OCSP_SINGLERESP> structure or +B<NULL> if B<idx> is out of range. + +OCSP_resp_find() returns the index of B<id> in B<bs> (which may be 0) or -1 if +B<id> was not found. + +OCSP_single_get0_status() returns the status of B<single> or -1 if an error +occurred. + +OCSP_resp_get0_signer() returns 1 if the signing certificate was located, +or 0 on error. + +=head1 NOTES + +Applications will typically call OCSP_resp_find_status() using the certificate +ID of interest and then check its validity using OCSP_check_validity(). They +can then take appropriate action based on the status of the certificate. + +An OCSP response for a certificate contains B<thisUpdate> and B<nextUpdate> +fields. Normally the current time should be between these two values. To +account for clock skew the B<maxsec> field can be set to non-zero in +OCSP_check_validity(). Some responders do not set the B<nextUpdate> field, this +would otherwise mean an ancient response would be considered valid: the +B<maxsec> parameter to OCSP_check_validity() can be used to limit the permitted +age of responses. + +The values written to B<*revtime>, B<*thisupd> and B<*nextupd> by +OCSP_resp_find_status() and OCSP_single_get0_status() are internal pointers +which B<MUST NOT> be freed up by the calling application. Any or all of these +parameters can be set to NULL if their value is not required. + +=head1 SEE ALSO + +L<crypto(3)>, +L<OCSP_cert_to_id(3)>, +L<OCSP_request_add1_nonce(3)>, +L<OCSP_REQUEST_new(3)>, +L<OCSP_response_status(3)>, +L<OCSP_sendreq_new(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/OCSP_response_status.pod b/deps/openssl/openssl/doc/crypto/OCSP_response_status.pod new file mode 100644 index 0000000000..180ab8d30c --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/OCSP_response_status.pod @@ -0,0 +1,100 @@ +=pod + +=head1 NAME + +OCSP_response_status, OCSP_response_get1_basic, OCSP_response_create, +OCSP_RESPONSE_free, OCSP_RESPID_set_by_name, +OCSP_RESPID_set_by_key, OCSP_RESPID_match - OCSP response functions + +=head1 SYNOPSIS + + #include <openssl/ocsp.h> + + int OCSP_response_status(OCSP_RESPONSE *resp); + OCSP_BASICRESP *OCSP_response_get1_basic(OCSP_RESPONSE *resp); + OCSP_RESPONSE *OCSP_response_create(int status, OCSP_BASICRESP *bs); + void OCSP_RESPONSE_free(OCSP_RESPONSE *resp); + + int OCSP_RESPID_set_by_name(OCSP_RESPID *respid, X509 *cert); + int OCSP_RESPID_set_by_key(OCSP_RESPID *respid, X509 *cert); + int OCSP_RESPID_match(OCSP_RESPID *respid, X509 *cert); + +=head1 DESCRIPTION + +OCSP_response_status() returns the OCSP response status of B<resp>. It returns +one of the values: B<OCSP_RESPONSE_STATUS_SUCCESSFUL>, +B<OCSP_RESPONSE_STATUS_MALFORMEDREQUEST>, +B<OCSP_RESPONSE_STATUS_INTERNALERROR>, B<OCSP_RESPONSE_STATUS_TRYLATER> +B<OCSP_RESPONSE_STATUS_SIGREQUIRED>, or B<OCSP_RESPONSE_STATUS_UNAUTHORIZED>. + +OCSP_response_get1_basic() decodes and returns the B<OCSP_BASICRESP> structure +contained in B<resp>. + +OCSP_response_create() creates and returns an B<OCSP_RESPONSE> structure for +B<status> and optionally including basic response B<bs>. + +OCSP_RESPONSE_free() frees up OCSP response B<resp>. + +OCSP_RESPID_set_by_name() sets the name of the OCSP_RESPID to be the same as the +subject name in the supplied X509 certificate B<cert> for the OCSP responder. + +OCSP_RESPID_set_by_key() sets the key of the OCSP_RESPID to be the same as the +key in the supplied X509 certificate B<cert> for the OCSP responder. The key is +stored as a SHA1 hash. + +Note that an OCSP_RESPID can only have one of the name, or the key set. Calling +OCSP_RESPID_set_by_name() or OCSP_RESPID_set_by_key() will clear any existing +setting. + +OCSP_RESPID_match() tests whether the OCSP_RESPID given in B<respid> matches +with the X509 certificate B<cert>. + +=head1 RETURN VALUES + +OCSP_RESPONSE_status() returns a status value. + +OCSP_response_get1_basic() returns an B<OCSP_BASICRESP> structure pointer or +B<NULL> if an error occurred. + +OCSP_response_create() returns an B<OCSP_RESPONSE> structure pointer or B<NULL> +if an error occurred. + +OCSP_RESPONSE_free() does not return a value. + +OCSP_RESPID_set_by_name() and OCSP_RESPID_set_by_key() return 1 on success or 0 +on failure. + +OCSP_RESPID_match() returns 1 if the OCSP_RESPID and the X509 certificate match +or 0 otherwise. + +=head1 NOTES + +OCSP_response_get1_basic() is only called if the status of a response is +B<OCSP_RESPONSE_STATUS_SUCCESSFUL>. + +=head1 SEE ALSO + +L<crypto(3)> +L<OCSP_cert_to_id(3)> +L<OCSP_request_add1_nonce(3)> +L<OCSP_REQUEST_new(3)> +L<OCSP_response_find_status(3)> +L<OCSP_sendreq_new(3)> +L<OCSP_RESPID_new(3)> +L<OCSP_RESPID_free(3)> + +=head1 HISTORY + +The OCSP_RESPID_set_by_name(), OCSP_RESPID_set_by_key() and OCSP_RESPID_match() +functions were added in OpenSSL 1.1.0a. + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/OCSP_sendreq_new.pod b/deps/openssl/openssl/doc/crypto/OCSP_sendreq_new.pod new file mode 100644 index 0000000000..c7fdc9b12e --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/OCSP_sendreq_new.pod @@ -0,0 +1,122 @@ +=pod + +=head1 NAME + +OCSP_sendreq_new, OCSP_sendreq_nbio, OCSP_REQ_CTX_free, +OCSP_set_max_response_length, OCSP_REQ_CTX_add1_header, +OCSP_REQ_CTX_set1_req, OCSP_sendreq_bio - OCSP responder query functions + +=head1 SYNOPSIS + + #include <openssl/ocsp.h> + + OCSP_REQ_CTX *OCSP_sendreq_new(BIO *io, const char *path, OCSP_REQUEST *req, + int maxline); + + int OCSP_sendreq_nbio(OCSP_RESPONSE **presp, OCSP_REQ_CTX *rctx); + + void OCSP_REQ_CTX_free(OCSP_REQ_CTX *rctx); + + void OCSP_set_max_response_length(OCSP_REQ_CTX *rctx, unsigned long len); + + int OCSP_REQ_CTX_add1_header(OCSP_REQ_CTX *rctx, + const char *name, const char *value); + + int OCSP_REQ_CTX_set1_req(OCSP_REQ_CTX *rctx, OCSP_REQUEST *req); + + OCSP_RESPONSE *OCSP_sendreq_bio(BIO *io, const char *path, OCSP_REQUEST *req, + int maxline); + +=head1 DESCRIPTION + +The function OCSP_sendreq_new() returns an B<OCSP_CTX> structure using the +responder B<io>, the URL path B<path>, the OCSP request B<req> and with a +response header maximum line length of B<maxline>. If B<maxline> is zero a +default value of 4k is used. The OCSP request B<req> may be set to B<NULL> +and provided later if required. + +OCSP_sendreq_nbio() performs non-blocking I/O on the OCSP request context +B<rctx>. When the operation is complete it returns the response in B<*presp>. + +OCSP_REQ_CTX_free() frees up the OCSP context B<rctx>. + +OCSP_set_max_response_length() sets the maximum response length for B<rctx> +to B<len>. If the response exceeds this length an error occurs. If not +set a default value of 100k is used. + +OCSP_REQ_CTX_add1_header() adds header B<name> with value B<value> to the +context B<rctx>. It can be called more than once to add multiple headers. +It B<MUST> be called before any calls to OCSP_sendreq_nbio(). The B<req> +parameter in the initial to OCSP_sendreq_new() call MUST be set to B<NULL> if +additional headers are set. + +OCSP_REQ_CTX_set1_req() sets the OCSP request in B<rctx> to B<req>. This +function should be called after any calls to OCSP_REQ_CTX_add1_header(). + +OCSP_sendreq_bio() performs an OCSP request using the responder B<io>, the URL +path B<path>, the OCSP request B<req> and with a response header maximum line +length of B<maxline>. If B<maxline> is zero a default value of 4k is used. + +=head1 RETURN VALUES + +OCSP_sendreq_new() returns a valid B<OCSP_REQ_CTX> structure or B<NULL> if +an error occurred. + +OCSP_sendreq_nbio() returns B<1> if the operation was completed successfully, +B<-1> if the operation should be retried and B<0> if an error occurred. + +OCSP_REQ_CTX_add1_header() and OCSP_REQ_CTX_set1_req() return B<1> for success +and B<0> for failure. + +OCSP_sendreq_bio() returns the B<OCSP_RESPONSE> structure sent by the +responder or B<NULL> if an error occurred. + +OCSP_REQ_CTX_free() and OCSP_set_max_response_length() do not return values. + +=head1 NOTES + +These functions only perform a minimal HTTP query to a responder. If an +application wishes to support more advanced features it should use an +alternative more complete HTTP library. + +Currently only HTTP POST queries to responders are supported. + +The arguments to OCSP_sendreq_new() correspond to the components of the URL. +For example if the responder URL is B<http://ocsp.com/ocspreq> the BIO +B<io> should be connected to host B<ocsp.com> on port 80 and B<path> +should be set to B<"/ocspreq"> + +The headers added with OCSP_REQ_CTX_add1_header() are of the form +"B<name>: B<value>" or just "B<name>" if B<value> is B<NULL>. So to add +a Host header for B<ocsp.com> you would call: + + OCSP_REQ_CTX_add1_header(ctx, "Host", "ocsp.com"); + +If OCSP_sendreq_nbio() indicates an operation should be retried the +corresponding BIO can be examined to determine which operation (read or +write) should be retried and appropriate action taken (for example a select() +call on the underlying socket). + +OCSP_sendreq_bio() does not support retries and so cannot handle non-blocking +I/O efficiently. It is retained for compatibility and its use in new +applications is not recommended. + +=head1 SEE ALSO + +L<crypto(3)>, +L<OCSP_cert_to_id(3)>, +L<OCSP_request_add1_nonce(3)>, +L<OCSP_REQUEST_new(3)>, +L<OCSP_response_find_status(3)>, +L<OCSP_response_status(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/OPENSSL_Applink.pod b/deps/openssl/openssl/doc/crypto/OPENSSL_Applink.pod index e54de12cc8..d3a461ba39 100644 --- a/deps/openssl/openssl/doc/crypto/OPENSSL_Applink.pod +++ b/deps/openssl/openssl/doc/crypto/OPENSSL_Applink.pod @@ -16,6 +16,16 @@ Even though it appears at application side, it's essentially OpenSSL private interface. For this reason application developers are not expected to implement it, but to compile provided module with compiler of their choice and link it into the target application. -The referred module is available as <openssl>/ms/applink.c. +The referred module is available as F<applink.c>, located alongside +the public header files (only on the platforms where applicable). + +=head1 COPYRIGHT + +Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/OPENSSL_LH_COMPFUNC.pod b/deps/openssl/openssl/doc/crypto/OPENSSL_LH_COMPFUNC.pod new file mode 100644 index 0000000000..e760ae3be7 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/OPENSSL_LH_COMPFUNC.pod @@ -0,0 +1,239 @@ +=pod + +=head1 NAME + +DECLARE_LHASH_OF, +OPENSSL_LH_COMPFUNC, OPENSSL_LH_HASHFUNC, OPENSSL_LH_DOALL_FUNC, +LHASH_DOALL_ARG_FN_TYPE, +IMPLEMENT_LHASH_HASH_FN, IMPLEMENT_LHASH_COMP_FN, +lh_TYPE_new, lh_TYPE_free, +lh_TYPE_insert, lh_TYPE_delete, lh_TYPE_retrieve, +lh_TYPE_doall, lh_TYPE_doall_arg, lh_TYPE_error - dynamic hash table + +=for comment generic + +=head1 SYNOPSIS + + #include <openssl/lhash.h> + + DECLARE_LHASH_OF(TYPE); + + LHASH *lh_TYPE_new(); + void lh_TYPE_free(LHASH_OF(TYPE *table); + + TYPE *lh_TYPE_insert(LHASH_OF(TYPE *table, TYPE *data); + TYPE *lh_TYPE_delete(LHASH_OF(TYPE *table, TYPE *data); + TYPE *lh_retrieve(LHASH_OFTYPE *table, TYPE *data); + + void lh_TYPE_doall(LHASH_OF(TYPE *table, OPENSSL_LH_DOALL_FUNC func); + void lh_TYPE_doall_arg(LHASH_OF(TYPE) *table, OPENSSL_LH_DOALL_FUNCARG func, + TYPE, TYPE *arg); + + int lh_TYPE_error(LHASH_OF(TYPE) *table); + + typedef int (*OPENSSL_LH_COMPFUNC)(const void *, const void *); + typedef unsigned long (*OPENSSL_LH_HASHFUNC)(const void *); + typedef void (*OPENSSL_LH_DOALL_FUNC)(const void *); + typedef void (*LHASH_DOALL_ARG_FN_TYPE)(const void *, const void *); + +=head1 DESCRIPTION + +This library implements type-checked dynamic hash tables. The hash +table entries can be arbitrary structures. Usually they consist of key +and value fields. In the description here, I<TYPE> is used a placeholder +for any of the OpenSSL datatypes, such as I<SSL_SESSION>. + +lh_TYPE_new() creates a new B<LHASH_OF(TYPE)> structure to store +arbitrary data entries, and specifies the 'hash' and 'compare' +callbacks to be used in organising the table's entries. The B<hash> +callback takes a pointer to a table entry as its argument and returns +an unsigned long hash value for its key field. The hash value is +normally truncated to a power of 2, so make sure that your hash +function returns well mixed low order bits. The B<compare> callback +takes two arguments (pointers to two hash table entries), and returns +0 if their keys are equal, non-zero otherwise. + +If your hash table +will contain items of some particular type and the B<hash> and +B<compare> callbacks hash/compare these types, then the +B<IMPLEMENT_LHASH_HASH_FN> and B<IMPLEMENT_LHASH_COMP_FN> macros can be +used to create callback wrappers of the prototypes required by +lh_TYPE_new() as shown in this example: + + /* + * Implement the hash and compare functions; "stuff" can be any word. + */ + static unsigned long stuff_hash(const TYPE *a) + { + ... + } + static int stuff_cmp(const TYPE *a, const TYPE *b) + { + ... + } + + /* + * Implement the wrapper functions. + */ + static IMPLEMENT_LHASH_HASH_FN(stuff, TYPE) + static IMPLEMENT_LHASH_COMP_FN(stuff, TYPE) + +If the type is going to be used in several places, the following macros +can be used in a common header file to declare the function wrappers: + + DECLARE_LHASH_HASH_FN(stuff, TYPE) + DECLARE_LHASH_COMP_FN(stuff, TYPE) + +Then a hash table of TYPE objects can be created using this: + + LHASH_OF(TYPE) *htable; + + htable = lh_TYPE_new(LHASH_HASH_FN(stuff), LHASH_COMP_FN(stuff)); + +lh_TYPE_free() frees the B<LHASH_OF(TYPE)> structure +B<table>. Allocated hash table entries will not be freed; consider +using lh_TYPE_doall() to deallocate any remaining entries in the +hash table (see below). + +lh_TYPE_insert() inserts the structure pointed to by B<data> into +B<table>. If there already is an entry with the same key, the old +value is replaced. Note that lh_TYPE_insert() stores pointers, the +data are not copied. + +lh_TYPE_delete() deletes an entry from B<table>. + +lh_TYPE_retrieve() looks up an entry in B<table>. Normally, B<data> +is a structure with the key field(s) set; the function will return a +pointer to a fully populated structure. + +lh_TYPE_doall() will, for every entry in the hash table, call +B<func> with the data item as its parameter. +For example: + + /* Cleans up resources belonging to 'a' (this is implemented elsewhere) */ + void TYPE_cleanup_doall(TYPE *a); + + /* Implement a prototype-compatible wrapper for "TYPE_cleanup" */ + IMPLEMENT_LHASH_DOALL_FN(TYPE_cleanup, TYPE) + + /* Call "TYPE_cleanup" against all items in a hash table. */ + lh_TYPE_doall(hashtable, LHASH_DOALL_FN(TYPE_cleanup)); + + /* Then the hash table itself can be deallocated */ + lh_TYPE_free(hashtable); + +When doing this, be careful if you delete entries from the hash table +in your callbacks: the table may decrease in size, moving the item +that you are currently on down lower in the hash table - this could +cause some entries to be skipped during the iteration. The second +best solution to this problem is to set hash-E<gt>down_load=0 before +you start (which will stop the hash table ever decreasing in size). +The best solution is probably to avoid deleting items from the hash +table inside a "doall" callback! + +lh_TYPE_doall_arg() is the same as lh_TYPE_doall() except that +B<func> will be called with B<arg> as the second argument and B<func> +should be of type B<LHASH_DOALL_ARG_FN_TYPE> (a callback prototype +that is passed both the table entry and an extra argument). As with +lh_doall(), you can instead choose to declare your callback with a +prototype matching the types you are dealing with and use the +declare/implement macros to create compatible wrappers that cast +variables before calling your type-specific callbacks. An example of +this is demonstrated here (printing all hash table entries to a BIO +that is provided by the caller): + + /* Prints item 'a' to 'output_bio' (this is implemented elsewhere) */ + void TYPE_print_doall_arg(const TYPE *a, BIO *output_bio); + + /* Implement a prototype-compatible wrapper for "TYPE_print" */ + static IMPLEMENT_LHASH_DOALL_ARG_FN(TYPE, const TYPE, BIO) + + /* Print out the entire hashtable to a particular BIO */ + lh_TYPE_doall_arg(hashtable, LHASH_DOALL_ARG_FN(TYPE_print), BIO, + logging_bio); + + +lh_TYPE_error() can be used to determine if an error occurred in the last +operation. + +=head1 RETURN VALUES + +lh_TYPE_new() returns B<NULL> on error, otherwise a pointer to the new +B<LHASH> structure. + +When a hash table entry is replaced, lh_TYPE_insert() returns the value +being replaced. B<NULL> is returned on normal operation and on error. + +lh_TYPE_delete() returns the entry being deleted. B<NULL> is returned if +there is no such value in the hash table. + +lh_TYPE_retrieve() returns the hash table entry if it has been found, +B<NULL> otherwise. + +lh_TYPE_error() returns 1 if an error occurred in the last operation, 0 +otherwise. + +lh_TYPE_free(), lh_TYPE_doall() and lh_TYPE_doall_arg() return no values. + +=head1 NOTE + +The various LHASH macros and callback types exist to make it possible +to write type-checked code without resorting to function-prototype +casting - an evil that makes application code much harder to +audit/verify and also opens the window of opportunity for stack +corruption and other hard-to-find bugs. It also, apparently, violates +ANSI-C. + +The LHASH code regards table entries as constant data. As such, it +internally represents lh_insert()'d items with a "const void *" +pointer type. This is why callbacks such as those used by lh_doall() +and lh_doall_arg() declare their prototypes with "const", even for the +parameters that pass back the table items' data pointers - for +consistency, user-provided data is "const" at all times as far as the +LHASH code is concerned. However, as callers are themselves providing +these pointers, they can choose whether they too should be treating +all such parameters as constant. + +As an example, a hash table may be maintained by code that, for +reasons of encapsulation, has only "const" access to the data being +indexed in the hash table (ie. it is returned as "const" from +elsewhere in their code) - in this case the LHASH prototypes are +appropriate as-is. Conversely, if the caller is responsible for the +life-time of the data in question, then they may well wish to make +modifications to table item passed back in the lh_doall() or +lh_doall_arg() callbacks (see the "TYPE_cleanup" example above). If +so, the caller can either cast the "const" away (if they're providing +the raw callbacks themselves) or use the macros to declare/implement +the wrapper functions without "const" types. + +Callers that only have "const" access to data they're indexing in a +table, yet declare callbacks without constant types (or cast the +"const" away themselves), are therefore creating their own risks/bugs +without being encouraged to do so by the API. On a related note, +those auditing code should pay special attention to any instances of +DECLARE/IMPLEMENT_LHASH_DOALL_[ARG_]_FN macros that provide types +without any "const" qualifiers. + +=head1 BUGS + +lh_TYPE_insert() returns B<NULL> both for success and error. + +=head1 SEE ALSO + +L<lh_stats(3)> + +=head1 HISTORY + +In OpenSSL 1.0.0, the lhash interface was revamped for better +type checking. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/OPENSSL_LH_stats.pod b/deps/openssl/openssl/doc/crypto/OPENSSL_LH_stats.pod new file mode 100644 index 0000000000..c454a47eef --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/OPENSSL_LH_stats.pod @@ -0,0 +1,64 @@ +=pod + +=head1 NAME + +OPENSSL_LH_stats, OPENSSL_LH_node_stats, OPENSSL_LH_node_usage_stats, +OPENSSL_LH_stats_bio, +OPENSSL_LH_node_stats_bio, OPENSSL_LH_node_usage_stats_bio - LHASH statistics + +=head1 SYNOPSIS + + #include <openssl/lhash.h> + + void OPENSSL_LH_stats(LHASH *table, FILE *out); + void OPENSSL_LH_node_stats(LHASH *table, FILE *out); + void OPENSSL_LH_node_usage_stats(LHASH *table, FILE *out); + + void OPENSSL_LH_stats_bio(LHASH *table, BIO *out); + void OPENSSL_LH_node_stats_bio(LHASH *table, BIO *out); + void OPENSSL_LH_node_usage_stats_bio(LHASH *table, BIO *out); + +=head1 DESCRIPTION + +The B<LHASH> structure records statistics about most aspects of +accessing the hash table. This is mostly a legacy of Eric Young +writing this library for the reasons of implementing what looked like +a nice algorithm rather than for a particular software product. + +OPENSSL_LH_stats() prints out statistics on the size of the hash table, how +many entries are in it, and the number and result of calls to the +routines in this library. + +OPENSSL_LH_node_stats() prints the number of entries for each 'bucket' in the +hash table. + +OPENSSL_LH_node_usage_stats() prints out a short summary of the state of the +hash table. It prints the 'load' and the 'actual load'. The load is +the average number of data items per 'bucket' in the hash table. The +'actual load' is the average number of items per 'bucket', but only +for buckets which contain entries. So the 'actual load' is the +average number of searches that will need to find an item in the hash +table, while the 'load' is the average number that will be done to +record a miss. + +OPENSSL_LH_stats_bio(), OPENSSL_LH_node_stats_bio() and OPENSSL_LH_node_usage_stats_bio() +are the same as the above, except that the output goes to a B<BIO>. + +=head1 RETURN VALUES + +These functions do not return values. + +=head1 SEE ALSO + +L<bio(3)>, L<lhash(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/OPENSSL_VERSION_NUMBER.pod b/deps/openssl/openssl/doc/crypto/OPENSSL_VERSION_NUMBER.pod index f7ca7cb790..f50faec772 100644 --- a/deps/openssl/openssl/doc/crypto/OPENSSL_VERSION_NUMBER.pod +++ b/deps/openssl/openssl/doc/crypto/OPENSSL_VERSION_NUMBER.pod @@ -2,7 +2,8 @@ =head1 NAME -OPENSSL_VERSION_NUMBER, SSLeay, SSLeay_version - get OpenSSL version number +OPENSSL_VERSION_NUMBER, OpenSSL_version, +OpenSSL_version_num - get OpenSSL version number =head1 SYNOPSIS @@ -10,8 +11,9 @@ OPENSSL_VERSION_NUMBER, SSLeay, SSLeay_version - get OpenSSL version number #define OPENSSL_VERSION_NUMBER 0xnnnnnnnnnL #include <openssl/crypto.h> - long SSLeay(void); - const char *SSLeay_version(int t); + + unsigned long OpenSSL_version_num(); + const char *OpenSSL_version(int t); =head1 DESCRIPTION @@ -43,43 +45,48 @@ Version 0.9.5a had an interim interpretation that is like the current one, except the patch level got the highest bit set, to keep continuity. The number was therefore 0x0090581f. +OpenSSL_version_num() returns the version number. -For backward compatibility, SSLEAY_VERSION_NUMBER is also defined. - -SSLeay() returns this number. The return value can be compared to the -macro to make sure that the correct version of the library has been -loaded, especially when using DLLs on Windows systems. +The macro OPENSSL_VERSION_AT_LEAST(major,minor) can be used at compile +time test if the current version is at least as new as the version provided. +The arguments major, minor and fix correspond to the version information +as given above. -SSLeay_version() returns different strings depending on B<t>: +OpenSSL_version() returns different strings depending on B<t>: =over 4 -=item SSLEAY_VERSION +=item OPENSSL_VERSION The text variant of the version number and the release date. For example, -"OpenSSL 0.9.5a 1 Apr 2000". +"OpenSSL 1.0.1a 15 Oct 2015". -=item SSLEAY_CFLAGS +=item OPENSSL_CFLAGS The compiler flags set for the compilation process in the form "compiler: ..." if available or "compiler: information not available" otherwise. -=item SSLEAY_BUILT_ON +=item OPENSSL_BUILT_ON The date of the build process in the form "built on: ..." if available or "built on: date not available" otherwise. -=item SSLEAY_PLATFORM +=item OPENSSL_PLATFORM The "Configure" target of the library build in the form "platform: ..." if available or "platform: information not available" otherwise. -=item SSLEAY_DIR +=item OPENSSL_DIR The "OPENSSLDIR" setting of the library build in the form "OPENSSLDIR: "..."" if available or "OPENSSLDIR: N/A" otherwise. +=item OPENSSL_ENGINES_DIR + +The "ENGINESDIR" setting of the library build in the form "ENGINESDIR: "..."" +if available or "ENGINESDIR: N/A" otherwise. + =back For an unknown B<t>, the text "not available" is returned. @@ -90,12 +97,15 @@ The version number. =head1 SEE ALSO -L<crypto(3)|crypto(3)> +L<crypto(3)> + +=head1 COPYRIGHT -=head1 HISTORY +Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. -SSLeay() and SSLEAY_VERSION_NUMBER are available in all versions of SSLeay and OpenSSL. -OPENSSL_VERSION_NUMBER is available in all versions of OpenSSL. -B<SSLEAY_DIR> was added in OpenSSL 0.9.7. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/OPENSSL_config.pod b/deps/openssl/openssl/doc/crypto/OPENSSL_config.pod index 4e713653d0..eae634a8fa 100644 --- a/deps/openssl/openssl/doc/crypto/OPENSSL_config.pod +++ b/deps/openssl/openssl/doc/crypto/OPENSSL_config.pod @@ -8,8 +8,10 @@ OPENSSL_config, OPENSSL_no_config - simple OpenSSL configuration functions #include <openssl/conf.h> + #if OPENSSL_API_COMPAT < 0x10100000L void OPENSSL_config(const char *appname); void OPENSSL_no_config(void); + #endif =head1 DESCRIPTION @@ -22,6 +24,10 @@ Multiple calls have no effect. OPENSSL_no_config() disables configuration. If called before OPENSSL_config() no configuration takes place. +If the application is built with B<OPENSSL_LOAD_CONF> defined, then a +call to OpenSSL_add_all_algorithms() will implicitly call OPENSSL_config() +first. + =head1 NOTES The OPENSSL_config() function is designed to be a very simple "call it and @@ -34,9 +40,7 @@ Applications should instead call CONF_modules_load() during initialization (that is before starting any threads). There are several reasons why calling the OpenSSL configuration routines is -advisable. For example new ENGINE functionality was added to OpenSSL 0.9.7. -In OpenSSL 0.9.7 control functions can be supported by ENGINEs, this can be -used (among other things) to load dynamic ENGINEs from shared libraries (DSOs). +advisable. For example, to load dynamic ENGINEs from shared libraries (DSOs). However very few applications currently support the control interface and so very few can load and use dynamic ENGINEs. Equally in future more sophisticated ENGINEs will require certain control operations to customize them. If an @@ -44,20 +48,27 @@ application calls OPENSSL_config() it doesn't need to know or care about ENGINE control operations because they can be performed by editing a configuration file. -Applications should free up configuration at application closedown by calling -CONF_modules_free(). - =head1 RETURN VALUES Neither OPENSSL_config() nor OPENSSL_no_config() return a value. =head1 SEE ALSO -L<conf(5)|conf(5)>, L<CONF_load_modules_file(3)|CONF_load_modules_file(3)>, -L<CONF_modules_free(3)|CONF_modules_free(3)> +L<conf(5)>, +L<CONF_modules_load_file(3)> =head1 HISTORY -OPENSSL_config() and OPENSSL_no_config() first appeared in OpenSSL 0.9.7 +The OPENSSL_no_config() and OPENSSL_config() functions were +deprecated in OpenSSL 1.1.0 by OPENSSL_init_crypto(). + +=head1 COPYRIGHT + +Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/OPENSSL_ia32cap.pod b/deps/openssl/openssl/doc/crypto/OPENSSL_ia32cap.pod index 5bcb82e3cf..b0ab0ce551 100644 --- a/deps/openssl/openssl/doc/crypto/OPENSSL_ia32cap.pod +++ b/deps/openssl/openssl/doc/crypto/OPENSSL_ia32cap.pod @@ -2,25 +2,24 @@ =head1 NAME -OPENSSL_ia32cap, OPENSSL_ia32cap_loc - the IA-32 processor capabilities vector +OPENSSL_ia32cap - the x86[_64] processor capabilities vector =head1 SYNOPSIS - unsigned long *OPENSSL_ia32cap_loc(void); - #define OPENSSL_ia32cap ((OPENSSL_ia32cap_loc())[0]) + env OPENSSL_ia32cap=... <application> =head1 DESCRIPTION -Value returned by OPENSSL_ia32cap_loc() is address of a variable -containing IA-32 processor capabilities bit vector as it appears in -EDX:ECX register pair after executing CPUID instruction with EAX=1 -input value (see Intel Application Note #241618). Naturally it's -meaningful on x86 and x86_64 platforms only. The variable is normally -set up automatically upon toolkit initialization, but can be -manipulated afterwards to modify crypto library behaviour. For the -moment of this writing following bits are significant: +OpenSSL supports a range of x86[_64] instruction set extensions. These +extensions are denoted by individual bits in capability vector returned +by processor in EDX:ECX register pair after executing CPUID instruction +with EAX=1 input value (see Intel Application Note #241618). This vector +is copied to memory upon toolkit initialization and used to choose +between different code paths to provide optimal performance across wide +range of processors. For the moment of this writing following bits are +significant: -=over +=over 4 =item bit #4 denoting presence of Time-Stamp Counter. @@ -47,8 +46,13 @@ cores with shared cache; =item bit #43 denoting AMD XOP support (forced to zero on non-AMD CPUs); +=item bit #54 denoting availability of MOVBE instruction; + =item bit #57 denoting AES-NI instruction set extension; +=item bit #58, XSAVE bit, lack of which in combination with MOVBE is used +to identify Atom Silvermont core; + =item bit #59, OSXSAVE bit, denoting availability of YMM registers; =item bit #60 denoting AVX extension; @@ -57,40 +61,80 @@ cores with shared cache; =back -For example, clearing bit #26 at run-time disables high-performance -SSE2 code present in the crypto library, while clearing bit #24 -disables SSE2 code operating on 128-bit XMM register bank. You might -have to do the latter if target OpenSSL application is executed on SSE2 -capable CPU, but under control of OS that does not enable XMM -registers. Even though you can manipulate the value programmatically, -you most likely will find it more appropriate to set up an environment -variable with the same name prior starting target application, e.g. on -Intel P4 processor 'env OPENSSL_ia32cap=0x16980010 apps/openssl', or -better yet 'env OPENSSL_ia32cap=~0x1000000 apps/openssl' to achieve same -effect without modifying the application source code. Alternatively you -can reconfigure the toolkit with no-sse2 option and recompile. - -Less intuitive is clearing bit #28. The truth is that it's not copied -from CPUID output verbatim, but is adjusted to reflect whether or not -the data cache is actually shared between logical cores. This in turn -affects the decision on whether or not expensive countermeasures -against cache-timing attacks are applied, most notably in AES assembler -module. - -The vector is further extended with EBX value returned by CPUID with -EAX=7 and ECX=0 as input. Following bits are significant: - -=over +For example, in 32-bit application context clearing bit #26 at run-time +disables high-performance SSE2 code present in the crypto library, while +clearing bit #24 disables SSE2 code operating on 128-bit XMM register +bank. You might have to do the latter if target OpenSSL application is +executed on SSE2 capable CPU, but under control of OS that does not +enable XMM registers. Historically address of the capability vector copy +was exposed to application through OPENSSL_ia32cap_loc(), but not +anymore. Now the only way to affect the capability detection is to set +OPENSSL_ia32cap environment variable prior target application start. To +give a specific example, on Intel P4 processor 'env +OPENSSL_ia32cap=0x16980010 apps/openssl', or better yet 'env +OPENSSL_ia32cap=~0x1000000 apps/openssl' would achieve the desired +effect. Alternatively you can reconfigure the toolkit with no-sse2 +option and recompile. + +Less intuitive is clearing bit #28, or ~0x10000000 in the "environment +variable" terms. The truth is that it's not copied from CPUID output +verbatim, but is adjusted to reflect whether or not the data cache is +actually shared between logical cores. This in turn affects the decision +on whether or not expensive countermeasures against cache-timing attacks +are applied, most notably in AES assembler module. + +The capability vector is further extended with EBX value returned by +CPUID with EAX=7 and ECX=0 as input. Following bits are significant: + +=over 4 =item bit #64+3 denoting availability of BMI1 instructions, e.g. ANDN; =item bit #64+5 denoting availability of AVX2 instructions; -=item bit #64+8 denoting availability of BMI2 instructions, e.g. MUXL +=item bit #64+8 denoting availability of BMI2 instructions, e.g. MULX and RORX; +=item bit #64+16 denoting availability of AVX512F extension; + =item bit #64+18 denoting availability of RDSEED instruction; =item bit #64+19 denoting availability of ADCX and ADOX instructions; +=item bit #64+29 denoting availability of SHA extension; + +=item bit #64+30 denoting availability of AVX512BW extension; + +=item bit #64+31 denoting availability of AVX512VL extension; + =back + +To control this extended capability word use ':' as delimiter when +setting up OPENSSL_ia32cap environment variable. For example assigning +':~0x20' would disable AVX2 code paths, and ':0' - all post-AVX +extensions. + +It should be noted that whether or not some of the most "fancy" +extension code paths are actually assembled depends on current assembler +version. Base minimum of AES-NI/PCLMULQDQ, SSSE3 and SHA extension code +paths are always assembled. Besides that, minimum assembler version +requirements are summarized in below table: + + Extension | GNU as | nasm | llvm + ------------+--------+--------+-------- + AVX | 2.19 | 2.09 | 3.0 + AVX2 | 2.22 | 2.10 | 3.1 + AVX512 | 2.25 | 2.11.8 | 3.6 + +B<OPENSSL_ia32cap> is a macro returning the first word of the vector. + +=head1 COPYRIGHT + +Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/OPENSSL_init_crypto.pod b/deps/openssl/openssl/doc/crypto/OPENSSL_init_crypto.pod new file mode 100644 index 0000000000..f0b3c8aa8d --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/OPENSSL_init_crypto.pod @@ -0,0 +1,245 @@ +=pod + +=head1 NAME + +OPENSSL_init_new, OPENSSL_INIT_set_config_appname, OPENSSL_INIT_free, +OPENSSL_init_crypto, OPENSSL_cleanup, +OPENSSL_atexit, OPENSSL_thread_stop - OpenSSL +initialisation and deinitialisation functions + +=head1 SYNOPSIS + + #include <openssl/crypto.h> + + void OPENSSL_cleanup(void); + int OPENSSL_init_crypto(uint64_t opts, const OPENSSL_INIT_SETTINGS *settings); + int OPENSSL_atexit(void (*handler)(void)); + void OPENSSL_thread_stop(void); + + OPENSSL_INIT_SETTINGS *OPENSSL_init_new(void); + int OPENSSL_INIT_set_config_appname(OPENSSL_INIT_SETTINGS *init, + const char* name); + void OPENSSL_INIT_free(OPENSSL_INIT_SETTINGS *init); + +=head1 DESCRIPTION + +During normal operation OpenSSL (libcrypto) will allocate various resources at +start up that must, subsequently, be freed on close down of the library. +Additionally some resources are allocated on a per thread basis (if the +application is multi-threaded), and these resources must be freed prior to the +thread closing. + +As of version 1.1.0 OpenSSL will automatically allocate all resources that it +needs so no explicit initialisation is required. Similarly it will also +automatically deinitialise as required. + +However, there way be situations when explicit initialisation is desirable or +needed, for example when some non-default initialisation is required. The +function OPENSSL_init_crypto() can be used for this purpose for +libcrypto (see also L<OPENSSL_init_ssl(3)> for the libssl +equivalent). + +Numerous internal OpenSSL functions call OPENSSL_init_crypto(). +Therefore, in order to perform non-default initialisation, +OPENSSL_init_crypto() MUST be called by application code prior to +any other OpenSSL function calls. + +The B<opts> parameter specifies which aspects of libcrypto should be +initialised. Valid options are: + +=over 4 + +=item OPENSSL_INIT_NO_LOAD_CRYPTO_STRINGS + +Suppress automatic loading of the libcrypto error strings. This option is +not a default option. Once selected subsequent calls to +OPENSSL_init_crypto() with the option +B<OPENSSL_INIT_LOAD_CRYPTO_STRINGS> will be ignored. + +=item OPENSSL_INIT_LOAD_CRYPTO_STRINGS + +Automatic loading of the libcrypto error strings. With this option the +library will automatically load the libcrypto error strings. +This option is a default option. Once selected subsequent calls to +OPENSSL_init_crypto() with the option +B<OPENSSL_INIT_NO_LOAD_CRYPTO_STRINGS> will be ignored. + +=item OPENSSL_INIT_ADD_ALL_CIPHERS + +With this option the library will automatically load and make available all +libcrypto ciphers. This option is a default option. Once selected subsequent +calls to OPENSSL_init_crypto() with the option +B<OPENSSL_INIT_NO_ADD_ALL_CIPHERS> will be ignored. + +=item OPENSSL_INIT_ADD_ALL_DIGESTS + +With this option the library will automatically load and make available all +libcrypto digests. This option is a default option. Once selected subsequent +calls to OPENSSL_init_crypto() with the option +B<OPENSSL_INIT_NO_ADD_ALL_CIPHERS> will be ignored. + +=item OPENSSL_INIT_NO_ADD_ALL_CIPHERS + +With this option the library will suppress automatic loading of libcrypto +ciphers. This option is not a default option. Once selected subsequent +calls to OPENSSL_init_crypto() with the option +B<OPENSSL_INIT_ADD_ALL_CIPHERS> will be ignored. + +=item OPENSSL_INIT_NO_ADD_ALL_DIGESTS + +With this option the library will suppress automatic loading of libcrypto +digests. This option is not a default option. Once selected subsequent +calls to OPENSSL_init_crypto() with the option +B<OPENSSL_INIT_ADD_ALL_DIGESTS> will be ignored. + +=item OPENSSL_INIT_LOAD_CONFIG + +With this option an OpenSSL configuration file will be automatically loaded and +used by calling OPENSSL_config(). This is not a default option. +See the description of OPENSSL_init_new(), below. + +=item OPENSSL_INIT_NO_LOAD_CONFIG + +With this option the loading of OpenSSL configuration files will be suppressed. +It is the equivalent of calling OPENSSL_no_config(). This is not a default +option. + +=item OPENSSL_INIT_ASYNC + +With this option the library with automatically initialise the libcrypto async +sub-library (see L<ASYNC_start_job(3)>). This is a default option. + +=item OPENSSL_INIT_ENGINE_RDRAND + +With this option the library will automatically load and initialise the +RDRAND engine (if available). This not a default option. + +=item OPENSSL_INIT_ENGINE_DYNAMIC + +With this option the library will automatically load and initialise the +dynamic engine. This not a default option. + +=item OPENSSL_INIT_ENGINE_OPENSSL + +With this option the library will automatically load and initialise the +openssl engine. This not a default option. + +=item OPENSSL_INIT_ENGINE_CRYPTODEV + +With this option the library will automatically load and initialise the +cryptodev engine (if available). This not a default option. + +=item OPENSSL_INIT_ENGINE_CAPI + +With this option the library will automatically load and initialise the +CAPI engine (if available). This not a default option. + +=item OPENSSL_INIT_ENGINE_PADLOCK + +With this option the library will automatically load and initialise the +padlock engine (if available). This not a default option. + +=item OPENSSL_INIT_ENGINE_DASYNC + +With this option the library will automatically load and initialise the +DASYNC engine. This not a default option. + +=item OPENSSL_INIT_ENGINE_ALL_BUILTIN + +With this option the library will automatically load and initialise all the +built in engines listed above with the exception of the openssl and dasync +engines. This not a default option. + +=back + +Multiple options may be combined together in a single call to +OPENSSL_init_crypto(). For example: + + OPENSSL_init_crypto(OPENSSL_INIT_NO_ADD_ALL_CIPHERS + | OPENSSL_INIT_NO_ADD_ALL_DIGESTS, NULL); + +The OPENSSL_cleanup() function deinitialises OpenSSL (both libcrypto +and libssl). All resources allocated by OpenSSL are freed. Typically there +should be no need to call this function directly as it is initiated +automatically on application exit. This is done via the standard C library +atexit() function. In the event that the application will close in a manner +that will not call the registered atexit() handlers then the application should +call OPENSSL_cleanup() directly. Developers of libraries using OpenSSL +are discouraged from calling this function and should instead, typically, rely +on auto-deinitialisation. This is to avoid error conditions where both an +application and a library it depends on both use OpenSSL, and the library +deinitialises it before the application has finished using it. + +Once OPENSSL_cleanup() has been called the library cannot be reinitialised. +Attempts to call OPENSSL_init_crypto() will fail and an ERR_R_INIT_FAIL error +will be added to the error stack. Note that because initialisation has failed +OpenSSL error strings will not be available, only an error code. This code can +be put through the openssl errstr command line application to produce a human +readable error (see L<errstr(1)>). + +The OPENSSL_atexit() function enables the registration of a +function to be called during OPENSSL_cleanup(). Stop handlers are +called after deinitialisation of resources local to a thread, but before other +process wide resources are freed. In the event that multiple stop handlers are +registered, no guarantees are made about the order of execution. + +The OPENSSL_thread_stop() function deallocates resources associated +with the current thread. Typically this function will be called automatically by +the library when the thread exits. This should only be called directly if +resources should be freed at an earlier time, or under the circumstances +described in the NOTES section below. + +The B<OPENSSL_INIT_LOAD_CONFIG> flag will load a default configuration +file. To specify a different file, an B<OPENSSL_INIT_SETTINGS> must +be created and used. The routines +OPENSSL_init_new() and OPENSSL_INIT_set_config_appname() can be used to +allocate the object and set the application name, and then the +object can be released with OPENSSL_INIT_free() when done. + +=head1 NOTES + +Resources local to a thread are deallocated automatically when the thread exits +(e.g. in a pthreads environment, when pthread_exit() is called). On Windows +platforms this is done in response to a DLL_THREAD_DETACH message being sent to +the libcrypto32.dll entry point. Some windows functions may cause threads to exit +without sending this message (for example ExitProcess()). If the application +uses such functions, then the application must free up OpenSSL resources +directly via a call to OPENSSL_thread_stop() on each thread. Similarly this +message will also not be sent if OpenSSL is linked statically, and therefore +applications using static linking should also call OPENSSL_thread_stop() on each +thread. Additionally if OpenSSL is loaded dynamically via LoadLibrary() and the +threads are not destroyed until after FreeLibrary() is called then each thread +should call OPENSSL_thread_stop() prior to the FreeLibrary() call. + +On Linux/Unix where OpenSSL has been loaded via dlopen() and the application is +multi-threaded and if dlclose() is subsequently called prior to the threads +being destroyed then OpenSSL will not be able to deallocate resources associated +with those threads. The application should either call OPENSSL_thread_stop() on +each thread prior to the dlclose() call, or alternatively the original dlopen() +call should use the RTLD_NODELETE flag (where available on the platform). + +=head1 RETURN VALUES + +The functions OPENSSL_init_crypto, OPENSSL_atexit() and +OPENSSL_INIT_set_config_appname() return 1 on success or 0 on error. + +=head1 SEE ALSO + +L<OPENSSL_init_ssl(3)> + +=head1 HISTORY + +The OPENSSL_init_crypto(), OPENSSL_cleanup(), OPENSSL_atexit(), +OPENSSL_thread_stop(), OPENSSL_init_new(), OPENSSL_INIT_set_config_appname() +and OPENSSL_INIT_free() functions were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/OPENSSL_instrument_bus.pod b/deps/openssl/openssl/doc/crypto/OPENSSL_instrument_bus.pod index 4ed83e4950..1407261035 100644 --- a/deps/openssl/openssl/doc/crypto/OPENSSL_instrument_bus.pod +++ b/deps/openssl/openssl/doc/crypto/OPENSSL_instrument_bus.pod @@ -7,8 +7,8 @@ OPENSSL_instrument_bus, OPENSSL_instrument_bus2 - instrument references to memor =head1 SYNOPSIS #ifdef OPENSSL_CPUID_OBJ - size_t OPENSSL_instrument_bus (int *vector,size_t num); - size_t OPENSSL_instrument_bus2(int *vector,size_t num,size_t max); + size_t OPENSSL_instrument_bus(int *vector, size_t num); + size_t OPENSSL_instrument_bus2(int *vector, size_t num, size_t max); #endif =head1 DESCRIPTION @@ -23,10 +23,10 @@ interlocked manner, which should contribute additional noise on multi-processor systems. This also means that B<vector[num]> should be zeroed upon invocation (if you want to retrieve actual probe values). -OPENSSL_instrument_bus performs B<num> probes and records the number of +OPENSSL_instrument_bus() performs B<num> probes and records the number of oscillator cycles every probe took. -OPENSSL_instrument_bus2 on the other hand B<accumulates> consecutive +OPENSSL_instrument_bus2() on the other hand B<accumulates> consecutive probes with the same value, i.e. in a way it records duration of periods when probe values appeared deterministic. The subroutine performs at most B<max> probes in attempt to fill the B<vector[num]>, @@ -40,3 +40,14 @@ not available on current platform. For reference, on x86 'flush cache line' was introduced with the SSE2 extensions. Otherwise number of recorded values is returned. + +=head1 COPYRIGHT + +Copyright 2011-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/OPENSSL_load_builtin_modules.pod b/deps/openssl/openssl/doc/crypto/OPENSSL_load_builtin_modules.pod index de62912ff2..112718a68a 100644 --- a/deps/openssl/openssl/doc/crypto/OPENSSL_load_builtin_modules.pod +++ b/deps/openssl/openssl/doc/crypto/OPENSSL_load_builtin_modules.pod @@ -24,15 +24,15 @@ ENGINE_add_conf_module() adds just the ENGINE configuration module. =head1 NOTES -If the simple configuration function OPENSSL_config() is called then +If the simple configuration function OPENSSL_config() is called then OPENSSL_load_builtin_modules() is called automatically. Applications which use the configuration functions directly will need to -call OPENSSL_load_builtin_modules() themselves I<before> any other +call OPENSSL_load_builtin_modules() themselves I<before> any other configuration code. Applications should call OPENSSL_load_builtin_modules() to load all -configuration modules instead of adding modules selectively: otherwise +configuration modules instead of adding modules selectively: otherwise functionality may be missing from the application if an when new modules are added. @@ -42,10 +42,15 @@ None of the functions return a value. =head1 SEE ALSO -L<conf(3)|conf(3)>, L<OPENSSL_config(3)|OPENSSL_config(3)> +L<conf(3)>, L<OPENSSL_config(3)> -=head1 HISTORY +=head1 COPYRIGHT -These functions first appeared in OpenSSL 0.9.7. +Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/OPENSSL_malloc.pod b/deps/openssl/openssl/doc/crypto/OPENSSL_malloc.pod new file mode 100644 index 0000000000..2104f43108 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/OPENSSL_malloc.pod @@ -0,0 +1,207 @@ +=pod + +=head1 NAME + +OPENSSL_malloc_init, +OPENSSL_malloc, OPENSSL_zalloc, OPENSSL_realloc, OPENSSL_free, +OPENSSL_clear_realloc, OPENSSL_clear_free, OPENSSL_cleanse, +CRYPTO_malloc, CRYPTO_zalloc, CRYPTO_realloc, CRYPTO_free, +OPENSSL_strdup, OPENSSL_strndup, +OPENSSL_memdup, OPENSSL_strlcpy, OPENSSL_strlcat, +OPENSSL_hexstr2buf, OPENSSL_buf2hexstr, OPENSSL_hexchar2int, +CRYPTO_strdup, CRYPTO_strndup, +OPENSSL_mem_debug_push, OPENSSL_mem_debug_pop, +CRYPTO_mem_debug_push, CRYPTO_mem_debug_pop, +CRYPTO_clear_realloc, CRYPTO_clear_free, +CRYPTO_get_mem_functions, CRYPTO_set_mem_functions, +CRYPTO_set_mem_debug, CRYPTO_mem_ctrl, +CRYPTO_mem_leaks, CRYPTO_mem_leaks_fp - Memory allocation functions + +=head1 SYNOPSIS + + #include <openssl/crypto.h> + + int OPENSSL_malloc_init(void) + + void *OPENSSL_malloc(size_t num) + void *OPENSSL_zalloc(size_t num) + void *OPENSSL_realloc(void *addr, size_t num) + void OPENSSL_free(void *addr) + char *OPENSSL_strdup(const char *str) + char *OPENSSL_strndup(const char *str, size_t s) + size_t OPENSSL_strlcat(char *dst, const char *src, size_t size); + size_t OPENSSL_strlcpy(char *dst, const char *src, size_t size); + void *OPENSSL_memdup(void *data, size_t s) + void *OPENSSL_clear_realloc(void *p, size_t old_len, size_t num) + void OPENSSL_clear_free(void *str, size_t num) + void OPENSSL_cleanse(void *ptr, size_t len); + + unsigned char *OPENSSL_hexstr2buf(const char *str, long *len); + char *OPENSSL_buf2hexstr(const unsigned char *buffer, long len); + int OPENSSL_hexchar2int(unsigned char c); + + void *CRYPTO_malloc(size_t num, const char *file, int line) + void *CRYPTO_zalloc(size_t num, const char *file, int line) + void *CRYPTO_realloc(void *p, size_t num, const char *file, int line) + void CRYPTO_free(void *str, const char *, int) + char *CRYPTO_strdup(const char *p, const char *file, int line) + char *CRYPTO_strndup(const char *p, size_t num, const char *file, int line) + void *CRYPTO_clear_realloc(void *p, size_t old_len, size_t num, const char *file, int line) + void CRYPTO_clear_free(void *str, size_t num, const char *, int) + + void CRYPTO_get_mem_functions( + void *(**m)(size_t, const char *, int), + void *(**r)(void *, size_t, const char *, int), + void (**f)(void *, const char *, int)) + int CRYPTO_set_mem_functions( + void *(*m)(size_t, const char *, int), + void *(*r)(void *, size_t, const char *, int), + void (*f)(void *, const char *, int)) + + int CRYPTO_set_mem_debug(int onoff) + + int CRYPTO_mem_ctrl(int mode); + + int OPENSSL_mem_debug_push(const char *info) + int OPENSSL_mem_debug_pop(void); + + int CRYPTO_mem_debug_push(const char *info, const char *file, int line); + int CRYPTO_mem_debug_pop(void); + + void CRYPTO_mem_leaks(BIO *b); + void CRYPTO_mem_leaks_fp(FILE *fp); + +=head1 DESCRIPTION + +OpenSSL memory allocation is handled by the B<OPENSSL_xxx> API. These are +generally macro's that add the standard C B<__FILE__> and B<__LINE__> +parameters and call a lower-level B<CRYPTO_xxx> API. +Some functions do not add those parameters, but exist for consistency. + +OPENSSL_malloc_init() sets the lower-level memory allocation functions +to their default implementation. +It is generally not necessary to call this, except perhaps in certain +shared-library situations. + +OPENSSL_malloc(), OPENSSL_realloc(), and OPENSSL_free() are like the +C malloc(), realloc(), and free() functions. +OPENSSL_zalloc() calls memset() to zero the memory before returning. + +OPENSSL_clear_realloc() and OPENSSL_clear_free() should be used +when the buffer at B<addr> holds sensitive information. +The old buffer is filled with zero's by calling OPENSSL_cleanse() +before ultimately calling OPENSSL_free(). + +OPENSSL_cleanse() fills B<ptr> of size B<len> with a string of 0's. +Use OPENSSL_cleanse() with care if the memory is a mapping of a file. +If the storage controller uses write compression, then its possible +that sensitive tail bytes will survive zeroization because the block of +zeros will be compressed. If the storage controller uses wear leveling, +then the old sensitive data will not be overwritten; rather, a block of +0's will be written at a new physical location. + +OPENSSL_strdup(), OPENSSL_strndup() and OPENSSL_memdup() are like the +equivalent C functions, except that memory is allocated by calling the +OPENSSL_malloc() and should be released by calling OPENSSL_free(). + +OPENSSL_strlcpy(), +OPENSSL_strlcat() and OPENSSL_strnlen() are equivalents of the common C +library functions and are provided for portability. + +OPENSSL_hexstr2buf() parses B<str> as a hex string and returns a +pointer to the parsed value. The memory is allocated by calling +OPENSSL_malloc() and should be released by calling OPENSSL_free(). +If B<len> is not NULL, it is filled in with the output length. +Colons between two-character hex "bytes" are ignored. +An odd number of hex digits is an error. + +OPENSSL_buf2hexstr() takes the specified buffer and length, and returns +a hex string for value, or NULL on error. +B<Buffer> cannot be NULL; if B<len> is 0 an empty string is returned. + +OPENSSL_hexchar2int() converts a character to the hexadecimal equivalent, +or returns -1 on error. + +If no allocations have been done, it is possible to "swap out" the default +implementations for OPENSSL_malloc(), OPENSSL_realloc and OPENSSL_free() +and replace them with alternate versions (hooks). +CRYPTO_get_mem_functions() function fills in the given arguments with the +function pointers for the current implementations. +With CRYPTO_set_mem_functions(), you can specify a different set of functions. +If any of B<m>, B<r>, or B<f> are NULL, then the function is not changed. + +The default implementation can include some debugging capability (if enabled +at build-time). +This adds some overhead by keeping a list of all memory allocations, and +removes items from the list when they are free'd. +This is most useful for identifying memory leaks. +CRYPTO_set_mem_debug() turns this tracking on and off. In order to have +any effect, is must be called before any of the allocation functions +(e.g., CRYPTO_malloc()) are called, and is therefore normally one of the +first lines of main() in an application. + +CRYPTO_mem_ctrl() provides fine-grained control of memory leak tracking. +To enable tracking call CRYPTO_mem_ctrl() with a B<mode> argument of +the B<CRYPTO_MEM_CHECK_ON>. +To disable tracking call CRYPTO_mem_ctrl() with a B<mode> argument of +the B<CRYPTO_MEM_CHECK_OFF>. + +While checking memory, it can be useful to store additional context +about what is being done. +For example, identifying the field names when parsing a complicated +data structure. +OPENSSL_mem_debug_push() (which calls CRYPTO_mem_debug_push()) +attachs an identifying string to the allocation stack. +This must be a global or other static string; it is not copied. +OPENSSL_mem_debug_pop() removes identifying state from the stack. + +At the end of the program, calling CRYPTO_mem_leaks() or +CRYPTO_mem_leaks_fp() will report all "leaked" memory, writing it +to the specified BIO B<b> or FILE B<fp>. These functions return 1 if +there are no leaks, 0 if there are leaks and -1 if an error occurred. + +=head1 RETURN VALUES + +OPENSSL_malloc_init(), OPENSSL_free(), OPENSSL_clear_free() +CRYPTO_free(), CRYPTO_clear_free() and CRYPTO_get_mem_functions() +return no value. + +CRYPTO_mem_leaks() and CRYPTO_mem_leaks_fp() return 1 if there +are no leaks, 0 if there are leaks and -1 if an error occurred. + +OPENSSL_malloc(), OPENSSL_zalloc(), OPENSSL_realloc(), +OPENSSL_clear_realloc(), +CRYPTO_malloc(), CRYPTO_zalloc(), CRYPTO_realloc(), +CRYPTO_clear_realloc(), +OPENSSL_buf2hexstr(), OPENSSL_hexstr2buf(), +OPENSSL_strdup(), and OPENSSL_strndup() +return a pointer to allocated memory or NULL on error. + +CRYPTO_set_mem_functions() and CRYPTO_set_mem_debug() +return 1 on success or 0 on failure (almost +always because allocations have already happened). + +CRYPTO_mem_ctrl() returns -1 if an error occurred, otherwise the +previous value of the mode. + +OPENSSL_mem_debug_push() and OPENSSL_mem_debug_pop() +return 1 on success or 0 on failure. + +=head1 NOTES + +While it's permitted to swap out only a few and not all the functions +with CRYPTO_set_mem_functions(), it's recommended to swap them all out +at once. I<This applies specially if OpenSSL was built with the +configuration option> C<crypto-mdebug> I<enabled. In case, swapping out +only, say, the malloc() implementation is outright dangerous.> + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/OPENSSL_secure_malloc.pod b/deps/openssl/openssl/doc/crypto/OPENSSL_secure_malloc.pod new file mode 100644 index 0000000000..3f27d76d20 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/OPENSSL_secure_malloc.pod @@ -0,0 +1,131 @@ +=pod + +=head1 NAME + +CRYPTO_secure_malloc_init, CRYPTO_secure_malloc_initialized, +CRYPTO_secure_malloc_done, OPENSSL_secure_malloc, CRYPTO_secure_malloc, +OPENSSL_secure_zalloc, CRYPTO_secure_zalloc, OPENSSL_secure_free, +OPENSSL_secure_clear_free, CRYPTO_secure_free, CRYPTO_secure_clear_free, +OPENSSL_secure_actual_size, OPENSSL_secure_allocated, CRYPTO_secure_used +- secure heap storage + +=head1 SYNOPSIS + + #include <openssl/crypto.h> + + int CRYPTO_secure_malloc_init(size_t size, int minsize); + + int CRYPTO_secure_malloc_initialized(); + + int CRYPTO_secure_malloc_done(); + + void *OPENSSL_secure_malloc(size_t num); + void *CRYPTO_secure_malloc(size_t num, const char *file, int line); + + void *OPENSSL_secure_zalloc(size_t num); + void *CRYPTO_secure_zalloc(size_t num, const char *file, int line); + + void OPENSSL_secure_free(void* ptr); + void CRYPTO_secure_free(void *ptr, const char *, int); + + void OPENSSL_secure_clear_free(void* ptr, size_t num); + void CRYPTO_secure_clear_free(void *ptr, size_t num, const char *, int); + + size_t OPENSSL_secure_actual_size(const void *ptr); + int OPENSSL_secure_allocated(const void *ptr); + + size_t CRYPTO_secure_used(); + +=head1 DESCRIPTION + +In order to help protect applications (particularly long-running servers) +from pointer overruns or underruns that could return arbitrary data from +the program's dynamic memory area, where keys and other sensitive +information might be stored, OpenSSL supports the concept of a "secure heap." +The level and type of security guarantees depend on the operating system. +It is a good idea to review the code and see if it addresses your +threat model and concerns. + +If a secure heap is used, then private key B<BIGNUM> values are stored there. +This protects long-term storage of private keys, but will not necessarily +put all intermediate values and computations there. + +CRYPTO_secure_malloc_init() creates the secure heap, with the specified +C<size> in bytes. The C<minsize> parameter is the minimum size to +allocate from the heap. Both C<size> and C<minsize> must be a power +of two. + +CRYPTO_secure_malloc_initialized() indicates whether or not the secure +heap as been initialized and is available. + +CRYPTO_secure_malloc_done() releases the heap and makes the memory unavailable +to the process if all secure memory has been freed. +It can take noticeably long to complete. + +OPENSSL_secure_malloc() allocates C<num> bytes from the heap. +If CRYPTO_secure_malloc_init() is not called, this is equivalent to +calling OPENSSL_malloc(). +It is a macro that expands to +CRYPTO_secure_malloc() and adds the C<__FILE__> and C<__LINE__> parameters. + +OPENSSL_secure_zalloc() and CRYPTO_secure_zalloc() are like +OPENSSL_secure_malloc() and CRYPTO_secure_malloc(), respectively, +except that they call memset() to zero the memory before returning. + +OPENSSL_secure_free() releases the memory at C<ptr> back to the heap. +It must be called with a value previously obtained from +OPENSSL_secure_malloc(). +If CRYPTO_secure_malloc_init() is not called, this is equivalent to +calling OPENSSL_free(). +It exists for consistency with OPENSSL_secure_malloc() , and +is a macro that expands to CRYPTO_secure_free() and adds the C<__FILE__> +and C<__LINE__> parameters.. + +OPENSSL_secure_allocated() tells whether or not a pointer is within +the secure heap. +OPENSSL_secure_actual_size() tells the actual size allocated to the +pointer; implementations may allocate more space than initially +requested, in order to "round up" and reduce secure heap fragmentation. + +CRYPTO_secure_used() returns the number of bytes allocated in the +secure heap. + +=head1 RETURN VALUES + +CRYPTO_secure_malloc_init() returns 0 on failure, 1 if successful, +and 2 if successful but the heap could not be protected by memory +mapping. + +CRYPTO_secure_malloc_initialized() returns 1 if the secure heap is +available (that is, if CRYPTO_secure_malloc_init() has been called, +but CRYPTO_secure_malloc_done() has not been called or failed) or 0 if not. + +OPENSSL_secure_malloc() and OPENSSL_secure_zalloc() return a pointer into +the secure heap of the requested size, or C<NULL> if memory could not be +allocated. + +CRYPTO_secure_allocated() returns 1 if the pointer is in the secure heap, or 0 if not. + +CRYPTO_secure_malloc_done() returns 1 if the secure memory area is released, or 0 if not. + +OPENSSL_secure_free() and OPENSSL_secure_clear_free() return no values. + +=head1 SEE ALSO + +L<OPENSSL_malloc(3)>, +L<BN_new(3)> + +=head1 HISTORY + +OPENSSL_secure_clear_free() was added in OpenSSL 1.1.0g. + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/OpenSSL_add_all_algorithms.pod b/deps/openssl/openssl/doc/crypto/OpenSSL_add_all_algorithms.pod index bcb79e5f6b..aaa28dd6a9 100644 --- a/deps/openssl/openssl/doc/crypto/OpenSSL_add_all_algorithms.pod +++ b/deps/openssl/openssl/doc/crypto/OpenSSL_add_all_algorithms.pod @@ -9,16 +9,24 @@ add algorithms to internal table #include <openssl/evp.h> +Deprecated: + + # if OPENSSL_API_COMPAT < 0x10100000L void OpenSSL_add_all_algorithms(void); void OpenSSL_add_all_ciphers(void); void OpenSSL_add_all_digests(void); - void EVP_cleanup(void); + void EVP_cleanup(void) +# endif =head1 DESCRIPTION OpenSSL keeps an internal table of digest algorithms and ciphers. It uses -this table to lookup ciphers via functions such as EVP_get_cipher_byname(). +this table to lookup ciphers via functions such as EVP_get_cipher_byname(). In +OpenSSL versions prior to 1.1.0 these functions initialised and de-initialised +this table. From OpenSSL 1.1.0 they are deprecated. No explicit initialisation +or de-initialisation is required. See L<OPENSSL_init_crypto(3)> for further +information. OpenSSL_add_all_digests() adds all digest algorithms to the table. @@ -28,7 +36,8 @@ ciphers). OpenSSL_add_all_ciphers() adds all encryption algorithms to the table including password based encryption algorithms. -EVP_cleanup() removes all ciphers and digests from the table. +In versions prior to 1.1.0 EVP_cleanup() removed all ciphers and digests from +the table. It no longer has any effect in OpenSSL 1.1.0. =head1 RETURN VALUES @@ -60,7 +69,22 @@ too much of a problem in practice. =head1 SEE ALSO -L<evp(3)|evp(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)>, -L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> +L<evp(3)>, L<EVP_DigestInit(3)>, +L<EVP_EncryptInit(3)> + +=head1 HISTORY + +The OpenSSL_add_all_algorithms(), OpenSSL_add_all_ciphers(), +OpenSSL_add_all_digests(), and EVP_cleanup(), functions +were deprecated in OpenSSL 1.1.0 by OPENSSL_init_crypto(). + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/PEM_read.pod b/deps/openssl/openssl/doc/crypto/PEM_read.pod new file mode 100644 index 0000000000..66cbc7d243 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/PEM_read.pod @@ -0,0 +1,127 @@ +=pod + +=head1 NAME + +PEM_write, PEM_write_bio, +PEM_read, PEM_read_bio, PEM_do_header, PEM_get_EVP_CIPHER_INFO +- PEM encoding routines + +=head1 SYNOPSIS + + #include <openssl/pem.h> + + int PEM_write(FILE *fp, const char *name, const char *header, + const unsigned char *data, long len) + int PEM_write_bio(BIO *bp, const char *name, const char *header, + const unsigned char *data, long len) + + int PEM_read(FILE *fp, char **name, char **header, + unsigned char **data, long *len); + int PEM_read_bio(BIO *bp, char **name, char **header, + unsigned char **data, long *len); + + int PEM_get_EVP_CIPHER_INFO(char *header, EVP_CIPHER_INFO *cinfo); + int PEM_do_header(EVP_CIPHER_INFO *cinfo, unsigned char *data, long *len, + pem_password_cb *cb, void *u); + +=head1 DESCRIPTION + +These functions read and write PEM-encoded objects, using the PEM +type B<name>, any additional B<header> information, and the raw +B<data> of length B<len>. + +PEM is the term used for binary content encoding first defined in IETF +RFC 1421. The content is a series of base64-encoded lines, surrounded +by begin/end markers each on their own line. For example: + + -----BEGIN PRIVATE KEY----- + MIICdg.... + ... bhTQ== + -----END PRIVATE KEY----- + +Optional header line(s) may appear after the begin line, and their +existence depends on the type of object being written or read. + +PEM_write() writes to the file B<fp>, while PEM_write_bio() writes to +the BIO B<bp>. The B<name> is the name to use in the marker, the +B<header> is the header value or NULL, and B<data> and B<len> specify +the data and its length. + +The final B<data> buffer is typically an ASN.1 object which can be decoded with +the B<d2i> function appropriate to the type B<name>; see L<d2i_X509(3)> +for examples. + +PEM_read() reads from the file B<fp>, while PEM_read_bio() reads +from the BIO B<bp>. +Both skip any non-PEM data that precedes the start of the next PEM object. +When an object is successfully retrieved, the type name from the "----BEGIN +<type>-----" is returned via the B<name> argument, any encapsulation headers +are returned in B<header> and the base64-decoded content and its length are +returned via B<data> and B<len> respectively. +The B<name>, B<header> and B<data> pointers are allocated via OPENSSL_malloc() +and should be freed by the caller via OPENSSL_free() when no longer needed. + +PEM_get_EVP_CIPHER_INFO() can be used to determine the B<data> returned by +PEM_read() or PEM_read_bio() is encrypted and to retrieve the associated cipher +and IV. +The caller passes a pointer to structure of type B<EVP_CIPHER_INFO> via the +B<cinfo> argument and the B<header> returned via PEM_read() or PEM_read_bio(). +If the call is successful 1 is returned and the cipher and IV are stored at the +address pointed to by B<cinfo>. +When the header is malformed, or not supported or when the cipher is unknown +or some internal error happens 0 is returned. +This function is deprecated, see B<NOTES> below. + +PEM_do_header() can then be used to decrypt the data if the header +indicates encryption. +The B<cinfo> argument is a pointer to the structure initialized by the previous +call to PEM_get_EVP_CIPHER_INFO(). +The B<data> and B<len> arguments are those returned by the previous call to +PEM_read() or PEM_read_bio(). +The B<cb> and B<u> arguments make it possible to override the default password +prompt function as described in L<PEM_read_PrivateKey(3)>. +On successful completion the B<data> is decrypted in place, and B<len> is +updated to indicate the plaintext length. +This function is deprecated, see B<NOTES> below. + +If the data is a priori known to not be encrypted, then neither PEM_do_header() +nor PEM_get_EVP_CIPHER_INFO() need be called. + +=head1 RETURN VALUES + +PEM_read() and PEM_read_bio() return 1 on success and 0 on failure, the latter +includes the case when no more PEM objects remain in the input file. +To distinguish end of file from more serious errors the caller must peek at the +error stack and check for B<PEM_R_NO_START_LINE>, which indicates that no more +PEM objects were found. See L<ERR_peek_last_error(3)>, L<ERR_GET_REASON(3)>. + +PEM_get_EVP_CIPHER_INFO() and PEM_do_header() return 1 on success, and 0 on +failure. +The B<data> is likely meaningless if these functions fail. + +=head1 NOTES + +The PEM_get_EVP_CIPHER_INFO() and PEM_do_header() functions are deprecated. +This is because the underlying PEM encryption format is obsolete, and should +be avoided. +It uses an encryption format with an OpenSSL-specific key-derivation function, +which employs MD5 with an iteration count of 1! +Instead, private keys should be stored in PKCS#8 form, with a strong PKCS#5 +v2.0 PBE. +See L<PEM_write_PrivateKey(3)> and L<d2i_PKCS8PrivateKey_bio(3)>. + +=head1 SEE ALSO + +L<ERR_peek_last_error(3)>, L<ERR_GET_LIB(3)>, +L<d2i_PKCS8PrivateKey_bio(3)>. + +=head1 COPYRIGHT + +Copyright 1998-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/PEM_read_CMS.pod b/deps/openssl/openssl/doc/crypto/PEM_read_CMS.pod new file mode 100644 index 0000000000..649c8089a9 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/PEM_read_CMS.pod @@ -0,0 +1,97 @@ +=pod + +=head1 NAME + +DECLARE_PEM_rw, +PEM_read_CMS, +PEM_read_bio_CMS, +PEM_write_CMS, +PEM_write_bio_CMS, +PEM_write_DHxparams, +PEM_write_bio_DHxparams, +PEM_read_ECPKParameters, +PEM_read_bio_ECPKParameters, +PEM_write_ECPKParameters, +PEM_write_bio_ECPKParameters, +PEM_read_ECPrivateKey, +PEM_write_ECPrivateKey, +PEM_write_bio_ECPrivateKey, +PEM_read_EC_PUBKEY, +PEM_read_bio_EC_PUBKEY, +PEM_write_EC_PUBKEY, +PEM_write_bio_EC_PUBKEY, +PEM_read_NETSCAPE_CERT_SEQUENCE, +PEM_read_bio_NETSCAPE_CERT_SEQUENCE, +PEM_write_NETSCAPE_CERT_SEQUENCE, +PEM_write_bio_NETSCAPE_CERT_SEQUENCE, +PEM_read_PKCS8, +PEM_read_bio_PKCS8, +PEM_write_PKCS8, +PEM_write_bio_PKCS8, +PEM_write_PKCS8_PRIV_KEY_INFO, +PEM_read_bio_PKCS8_PRIV_KEY_INFO, +PEM_read_PKCS8_PRIV_KEY_INFO, +PEM_write_bio_PKCS8_PRIV_KEY_INFO, +PEM_read_SSL_SESSION, +PEM_read_bio_SSL_SESSION, +PEM_write_SSL_SESSION, +PEM_write_bio_SSL_SESSION +- PEM object encoding routines + +=for comment generic + +=head1 SYNOPSIS + + #include <openssl/pem.h> + + DECLARE_PEM_rw(name, TYPE) + + TYPE *PEM_read_TYPE(FILE *fp, TYPE **a, pem_password_cb *cb, void *u); + TYPE *PEM_read_bio_TYPE(BIO *bp, TYPE **a, pem_password_cb *cb, void *u); + int PEM_write_TYPE(FILE *fp, const TYPE *a); + int PEM_write_bio_TYPE(BIO *bp, const TYPE *a); + +=head1 DESCRIPTION + +In the description below, I<TYPE> is used +as a placeholder for any of the OpenSSL datatypes, such as I<X509>. +The macro B<DECLARE_PEM_rw> expands to the set of declarations shown in +the next four lines of the synopsis. + +These routines convert between local instances of ASN1 datatypes and +the PEM encoding. For more information on the templates, see +L<ASN1_ITEM(3)>. For more information on the lower-level routines used +by the functions here, see L<PEM_read(3)>. + +PEM_read_TYPE() reads a PEM-encoded object of I<TYPE> from the file B<fp> +and returns it. The B<cb> and B<u> parameters are as described in +L<pem_password_cb(3)>. + +PEM_read_bio_TYPE() is similar to PEM_read_TYPE() but reads from the BIO B<bp>. + +PEM_write_TYPE() writes the PEM encoding of the object B<a> to the file B<fp>. + +PEM_write_bio_TYPE() similarly writes to the BIO B<bp>. + +=head1 RETURN VALUES + +PEM_read_TYPE() and PEM_read_bio_TYPE() return a pointer to an allocated +object, which should be released by calling TYPE_free(), or NULL on error. + +PEM_write_TYPE() and PEM_write_bio_TYPE() return the number of bytes written +or zero on error. + +=head1 SEE ALSO + +L<PEM_read(3)> + +=head1 COPYRIGHT + +Copyright 1998-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/pem.pod b/deps/openssl/openssl/doc/crypto/PEM_read_bio_PrivateKey.pod index 763eb6f533..6b3006ef35 100644 --- a/deps/openssl/openssl/doc/crypto/pem.pod +++ b/deps/openssl/openssl/doc/crypto/PEM_read_bio_PrivateKey.pod @@ -2,8 +2,10 @@ =head1 NAME -PEM, PEM_read_bio_PrivateKey, PEM_read_PrivateKey, PEM_write_bio_PrivateKey, -PEM_write_PrivateKey, PEM_write_bio_PKCS8PrivateKey, PEM_write_PKCS8PrivateKey, +pem_password_cb, +PEM_read_bio_PrivateKey, PEM_read_PrivateKey, PEM_write_bio_PrivateKey, +PEM_write_bio_PrivateKey_traditional, PEM_write_PrivateKey, +PEM_write_bio_PKCS8PrivateKey, PEM_write_PKCS8PrivateKey, PEM_write_bio_PKCS8PrivateKey_nid, PEM_write_PKCS8PrivateKey_nid, PEM_read_bio_PUBKEY, PEM_read_PUBKEY, PEM_write_bio_PUBKEY, PEM_write_PUBKEY, PEM_read_bio_RSAPrivateKey, PEM_read_RSAPrivateKey, @@ -22,184 +24,133 @@ PEM_write_X509_AUX, PEM_read_bio_X509_REQ, PEM_read_X509_REQ, PEM_write_bio_X509_REQ, PEM_write_X509_REQ, PEM_write_bio_X509_REQ_NEW, PEM_write_X509_REQ_NEW, PEM_read_bio_X509_CRL, PEM_read_X509_CRL, PEM_write_bio_X509_CRL, PEM_write_X509_CRL, PEM_read_bio_PKCS7, PEM_read_PKCS7, -PEM_write_bio_PKCS7, PEM_write_PKCS7, PEM_read_bio_NETSCAPE_CERT_SEQUENCE, -PEM_read_NETSCAPE_CERT_SEQUENCE, PEM_write_bio_NETSCAPE_CERT_SEQUENCE, -PEM_write_NETSCAPE_CERT_SEQUENCE - PEM routines +PEM_write_bio_PKCS7, PEM_write_PKCS7 - PEM routines =head1 SYNOPSIS #include <openssl/pem.h> - EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x, - pem_password_cb *cb, void *u); + typedef int pem_password_cb(char *buf, int size, int rwflag, void *u); + EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x, + pem_password_cb *cb, void *u); EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x, - pem_password_cb *cb, void *u); - + pem_password_cb *cb, void *u); int PEM_write_bio_PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc, - unsigned char *kstr, int klen, - pem_password_cb *cb, void *u); - + unsigned char *kstr, int klen, + pem_password_cb *cb, void *u); + int PEM_write_bio_PrivateKey_traditional(BIO *bp, EVP_PKEY *x, + const EVP_CIPHER *enc, + unsigned char *kstr, int klen, + pem_password_cb *cb, void *u); int PEM_write_PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, - unsigned char *kstr, int klen, - pem_password_cb *cb, void *u); + 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); - + 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); - + char *kstr, int klen, + pem_password_cb *cb, void *u); int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, EVP_PKEY *x, int nid, - char *kstr, int klen, - pem_password_cb *cb, void *u); - + char *kstr, int klen, + pem_password_cb *cb, void *u); int PEM_write_PKCS8PrivateKey_nid(FILE *fp, EVP_PKEY *x, int nid, - char *kstr, int klen, - pem_password_cb *cb, void *u); + char *kstr, int klen, + pem_password_cb *cb, void *u); EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x, - pem_password_cb *cb, void *u); - + pem_password_cb *cb, void *u); EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x, - pem_password_cb *cb, void *u); - + pem_password_cb *cb, void *u); int PEM_write_bio_PUBKEY(BIO *bp, EVP_PKEY *x); int PEM_write_PUBKEY(FILE *fp, EVP_PKEY *x); RSA *PEM_read_bio_RSAPrivateKey(BIO *bp, RSA **x, - pem_password_cb *cb, void *u); - + pem_password_cb *cb, void *u); RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x, - pem_password_cb *cb, void *u); - + pem_password_cb *cb, void *u); int PEM_write_bio_RSAPrivateKey(BIO *bp, RSA *x, const EVP_CIPHER *enc, - unsigned char *kstr, int klen, - pem_password_cb *cb, void *u); - + unsigned char *kstr, int klen, + pem_password_cb *cb, void *u); int PEM_write_RSAPrivateKey(FILE *fp, RSA *x, const EVP_CIPHER *enc, - unsigned char *kstr, int klen, - pem_password_cb *cb, void *u); + unsigned char *kstr, int klen, + pem_password_cb *cb, void *u); RSA *PEM_read_bio_RSAPublicKey(BIO *bp, RSA **x, - pem_password_cb *cb, void *u); - + pem_password_cb *cb, void *u); RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x, - pem_password_cb *cb, void *u); - + pem_password_cb *cb, void *u); int PEM_write_bio_RSAPublicKey(BIO *bp, RSA *x); - int PEM_write_RSAPublicKey(FILE *fp, RSA *x); RSA *PEM_read_bio_RSA_PUBKEY(BIO *bp, RSA **x, - pem_password_cb *cb, void *u); - + pem_password_cb *cb, void *u); RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x, - pem_password_cb *cb, void *u); - + pem_password_cb *cb, void *u); int PEM_write_bio_RSA_PUBKEY(BIO *bp, RSA *x); - int PEM_write_RSA_PUBKEY(FILE *fp, RSA *x); DSA *PEM_read_bio_DSAPrivateKey(BIO *bp, DSA **x, - pem_password_cb *cb, void *u); - + pem_password_cb *cb, void *u); DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x, - pem_password_cb *cb, void *u); - + pem_password_cb *cb, void *u); int PEM_write_bio_DSAPrivateKey(BIO *bp, DSA *x, const EVP_CIPHER *enc, - unsigned char *kstr, int klen, - pem_password_cb *cb, void *u); - + unsigned char *kstr, int klen, + pem_password_cb *cb, void *u); int PEM_write_DSAPrivateKey(FILE *fp, DSA *x, const EVP_CIPHER *enc, - unsigned char *kstr, int klen, - pem_password_cb *cb, void *u); + unsigned char *kstr, int klen, + pem_password_cb *cb, void *u); DSA *PEM_read_bio_DSA_PUBKEY(BIO *bp, DSA **x, - pem_password_cb *cb, void *u); - + pem_password_cb *cb, void *u); DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x, - pem_password_cb *cb, void *u); - + pem_password_cb *cb, void *u); int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x); - int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x); DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u); - DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u); - int PEM_write_bio_DSAparams(BIO *bp, DSA *x); - int PEM_write_DSAparams(FILE *fp, DSA *x); DH *PEM_read_bio_DHparams(BIO *bp, DH **x, pem_password_cb *cb, void *u); - DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u); - int PEM_write_bio_DHparams(BIO *bp, DH *x); - int PEM_write_DHparams(FILE *fp, DH *x); X509 *PEM_read_bio_X509(BIO *bp, X509 **x, pem_password_cb *cb, void *u); - X509 *PEM_read_X509(FILE *fp, X509 **x, pem_password_cb *cb, void *u); - int PEM_write_bio_X509(BIO *bp, X509 *x); - int PEM_write_X509(FILE *fp, X509 *x); X509 *PEM_read_bio_X509_AUX(BIO *bp, X509 **x, pem_password_cb *cb, void *u); - X509 *PEM_read_X509_AUX(FILE *fp, X509 **x, pem_password_cb *cb, void *u); - int PEM_write_bio_X509_AUX(BIO *bp, X509 *x); - int PEM_write_X509_AUX(FILE *fp, X509 *x); X509_REQ *PEM_read_bio_X509_REQ(BIO *bp, X509_REQ **x, - pem_password_cb *cb, void *u); - + pem_password_cb *cb, void *u); X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x, - pem_password_cb *cb, void *u); - + pem_password_cb *cb, void *u); int PEM_write_bio_X509_REQ(BIO *bp, X509_REQ *x); - int PEM_write_X509_REQ(FILE *fp, X509_REQ *x); - int PEM_write_bio_X509_REQ_NEW(BIO *bp, X509_REQ *x); - int PEM_write_X509_REQ_NEW(FILE *fp, X509_REQ *x); X509_CRL *PEM_read_bio_X509_CRL(BIO *bp, X509_CRL **x, - pem_password_cb *cb, void *u); + pem_password_cb *cb, void *u); X509_CRL *PEM_read_X509_CRL(FILE *fp, X509_CRL **x, - pem_password_cb *cb, void *u); + pem_password_cb *cb, void *u); int PEM_write_bio_X509_CRL(BIO *bp, X509_CRL *x); int PEM_write_X509_CRL(FILE *fp, X509_CRL *x); PKCS7 *PEM_read_bio_PKCS7(BIO *bp, PKCS7 **x, pem_password_cb *cb, void *u); - PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **x, pem_password_cb *cb, void *u); - int PEM_write_bio_PKCS7(BIO *bp, PKCS7 *x); - int PEM_write_PKCS7(FILE *fp, PKCS7 *x); - NETSCAPE_CERT_SEQUENCE *PEM_read_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, - NETSCAPE_CERT_SEQUENCE **x, - pem_password_cb *cb, void *u); - - NETSCAPE_CERT_SEQUENCE *PEM_read_NETSCAPE_CERT_SEQUENCE(FILE *fp, - NETSCAPE_CERT_SEQUENCE **x, - pem_password_cb *cb, void *u); - - int PEM_write_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, NETSCAPE_CERT_SEQUENCE *x); - - int PEM_write_NETSCAPE_CERT_SEQUENCE(FILE *fp, NETSCAPE_CERT_SEQUENCE *x); - =head1 DESCRIPTION The PEM functions read or write structures in PEM format. In @@ -214,19 +165,21 @@ clarity the term "B<foobar> functions" will be used to collectively refer to the PEM_read_bio_foobar(), PEM_read_foobar(), PEM_write_bio_foobar() and PEM_write_foobar() functions. -The B<PrivateKey> functions read or write a private key in -PEM format using an EVP_PKEY structure. The write routines use -"traditional" private key format and can handle both RSA and DSA -private keys. The read functions can additionally transparently -handle PKCS#8 format encrypted and unencrypted keys too. +The B<PrivateKey> functions read or write a private key in PEM format using an +EVP_PKEY structure. The write routines use PKCS#8 private key format and are +equivalent to PEM_write_bio_PKCS8PrivateKey().The read functions transparently +handle traditional and PKCS#8 format encrypted and unencrypted keys. -PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey() -write a private key in an EVP_PKEY structure in PKCS#8 -EncryptedPrivateKeyInfo format using PKCS#5 v2.0 password based encryption -algorithms. The B<cipher> argument specifies the encryption algorithm to -use: unlike all other PEM routines the encryption is applied at the -PKCS#8 level and not in the PEM headers. If B<cipher> is NULL then no -encryption is used and a PKCS#8 PrivateKeyInfo structure is used instead. +PEM_write_bio_PrivateKey_traditional() writes out a private key in legacy +"traditional" format. + +PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey() write a private +key in an EVP_PKEY structure in PKCS#8 EncryptedPrivateKeyInfo format using +PKCS#5 v2.0 password based encryption algorithms. The B<cipher> argument +specifies the encryption algorithm to use: unlike some other PEM routines the +encryption is applied at the PKCS#8 level and not in the PEM headers. If +B<cipher> is NULL then no encryption is used and a PKCS#8 PrivateKeyInfo +structure is used instead. PEM_write_bio_PKCS8PrivateKey_nid() and PEM_write_PKCS8PrivateKey_nid() also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo however @@ -239,7 +192,8 @@ structure. The public key is encoded as a SubjectPublicKeyInfo structure. The B<RSAPrivateKey> functions process an RSA private key using an -RSA structure. It handles the same formats as the B<PrivateKey> +RSA structure. The write routines uses traditional format. The read +routines handles the same formats as the B<PrivateKey> functions but an error occurs if the private key is not RSA. The B<RSAPublicKey> functions process an RSA public key using an @@ -252,7 +206,8 @@ SubjectPublicKeyInfo structure and an error occurs if the public key is not RSA. The B<DSAPrivateKey> functions process a DSA private key using a -DSA structure. It handles the same formats as the B<PrivateKey> +DSA structure. The write routines uses traditional format. The read +routines handles the same formats as the B<PrivateKey> functions but an error occurs if the private key is not DSA. The B<DSA_PUBKEY> functions process a DSA public key using @@ -273,7 +228,7 @@ structure. They will also process a trusted X509 certificate but any trust settings are discarded. The B<X509_AUX> functions process a trusted X509 certificate using -an X509 structure. +an X509 structure. The B<X509_REQ> and B<X509_REQ_NEW> functions process a PKCS#10 certificate request using an X509_REQ structure. The B<X509_REQ> @@ -288,9 +243,6 @@ structure. The B<PKCS7> functions process a PKCS#7 ContentInfo using a PKCS7 structure. -The B<NETSCAPE_CERT_SEQUENCE> functions process a Netscape Certificate -Sequence using a NETSCAPE_CERT_SEQUENCE structure. - =head1 PEM FUNCTION ARGUMENTS The PEM functions have many common arguments. @@ -354,84 +306,65 @@ Read a certificate in PEM format from a BIO: X509 *x; x = PEM_read_bio_X509(bp, NULL, 0, NULL); - if (x == NULL) - { - /* Error */ - } + if (x == NULL) { + /* Error */ + } Alternative method: X509 *x = NULL; - if (!PEM_read_bio_X509(bp, &x, 0, NULL)) - { - /* Error */ - } + 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 an unencrypted private key to a FILE pointer: - - if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL)) - { - /* Error */ - } + 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 */ - } + 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 the pass phrase "hello": - - key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello"); - if (key == NULL) - { - /* Error */ - } + 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 */ - } + if (key == NULL) { + /* Error */ + } Skeleton pass phrase callback: - int pass_cb(char *buf, int size, int rwflag, void *u); - { - int len; - char *tmp; - /* We'd probably do something else if 'rwflag' is 1 */ - printf("Enter pass phrase for \"%s\"\n", u); + int pass_cb(char *buf, int size, int rwflag, void *u) + { + int len; + char *tmp; - /* get pass phrase, length 'len' into 'tmp' */ - tmp = "hello"; - len = strlen(tmp); + /* We'd probably do something else if 'rwflag' is 1 */ + printf("Enter pass phrase for \"%s\"\n", (char *)u); - if (len <= 0) return 0; - /* if too long, truncate */ - if (len > size) len = size; - memcpy(buf, tmp, len); - return len; - } + /* get pass phrase, length 'len' into 'tmp' */ + tmp = "hello"; + len = strlen(tmp); + if (len <= 0) + return 0; + + if (len > size) + len = size; + memcpy(buf, tmp, len); + return len; + } =head1 NOTES @@ -456,9 +389,9 @@ which is an uninitialised pointer. =head1 PEM ENCRYPTION FORMAT -This old B<PrivateKey> routines use a non standard technique for encryption. +These old B<PrivateKey> routines use a non standard technique for encryption. -The private key (or other data) takes the following form: +The private key (or other data) takes the following form: -----BEGIN RSA PRIVATE KEY----- Proc-Type: 4,ENCRYPTED @@ -467,15 +400,43 @@ The private key (or other data) takes the following form: ...base64 encoded data... -----END RSA PRIVATE KEY----- -The line beginning DEK-Info contains two comma separated pieces of information: -the encryption algorithm name as used by EVP_get_cipherbyname() and an 8 -byte B<salt> encoded as a set of hexadecimal digits. +The line beginning with I<Proc-Type> contains the version and the +protection on the encapsulated data. The line beginning I<DEK-Info> +contains two comma separated values: the encryption algorithm name as +used by EVP_get_cipherbyname() and an initialization vector used by the +cipher encoded as a set of hexadecimal digits. After those two lines is +the base64-encoded encrypted data. + +The encryption key is derived using EVP_BytesToKey(). The cipher's +initialization vector is passed to EVP_BytesToKey() as the B<salt> +parameter. Internally, B<PKCS5_SALT_LEN> bytes of the salt are used +(regardless of the size of the initialization vector). The user's +password is passed to EVP_BytesToKey() using the B<data> and B<datal> +parameters. Finally, the library uses an iteration count of 1 for +EVP_BytesToKey(). + +The B<key> derived by EVP_BytesToKey() along with the original initialization +vector is then used to decrypt the encrypted data. The B<iv> produced by +EVP_BytesToKey() is not utilized or needed, and NULL should be passed to +the function. + +The pseudo code to derive the key would look similar to: -After this is the base64 encoded encrypted data. + EVP_CIPHER* cipher = EVP_des_ede3_cbc(); + EVP_MD* md = EVP_md5(); -The encryption key is determined using EVP_BytesToKey(), using B<salt> and an -iteration count of 1. The IV used is the value of B<salt> and *not* the IV -returned by EVP_BytesToKey(). + unsigned int nkey = EVP_CIPHER_key_length(cipher); + unsigned int niv = EVP_CIPHER_iv_length(cipher); + unsigned char key[nkey]; + unsigned char iv[niv]; + + memcpy(iv, HexToBin("3F17F5316E2BAC89"), niv); + rc = EVP_BytesToKey(cipher, md, iv /*salt*/, pword, plen, 1, key, NULL /*iv*/); + if (rc != nkey) { + /* Error */ + } + + /* On success, use key and iv to initialize the cipher */ =head1 BUGS @@ -484,7 +445,7 @@ an existing structure. Therefore the following: PEM_read_bio_X509(bp, &x, 0, NULL); -where B<x> already contains a valid certificate, may not work, whereas: +where B<x> already contains a valid certificate, may not work, whereas: X509_free(x); x = PEM_read_bio_X509(bp, NULL, 0, NULL); @@ -498,6 +459,23 @@ if an error occurred. The write routines return 1 for success or 0 for failure. +=head1 HISTORY + +The old Netscape certificate sequences were no longer documented +in OpenSSL 1.1; applications should use the PKCS7 standard instead +as they will be formally deprecated in a future releases. + =head1 SEE ALSO -L<EVP_get_cipherbyname(3)|EVP_get_cipherbyname>, L<EVP_BytesToKey(3)|EVP_BytesToKey(3)> +L<EVP_EncryptInit(3)>, L<EVP_BytesToKey(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/PEM_write_bio_CMS_stream.pod b/deps/openssl/openssl/doc/crypto/PEM_write_bio_CMS_stream.pod index e070c45c2e..c73fafd44b 100644 --- a/deps/openssl/openssl/doc/crypto/PEM_write_bio_CMS_stream.pod +++ b/deps/openssl/openssl/doc/crypto/PEM_write_bio_CMS_stream.pod @@ -2,12 +2,11 @@ =head1 NAME - PEM_write_bio_CMS_stream - output CMS_ContentInfo structure in PEM format. +PEM_write_bio_CMS_stream - output CMS_ContentInfo structure in PEM format =head1 SYNOPSIS #include <openssl/cms.h> - #include <openssl/pem.h> int PEM_write_bio_CMS_stream(BIO *out, CMS_ContentInfo *cms, BIO *data, int flags); @@ -28,14 +27,24 @@ PEM_write_bio_CMS_stream() returns 1 for success or 0 for failure. =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>, -L<CMS_verify(3)|CMS_verify(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)> -L<CMS_decrypt(3)|CMS_decrypt(3)>, -L<SMIME_write_CMS(3)|SMIME_write_CMS(3)>, -L<i2d_CMS_bio_stream(3)|i2d_CMS_bio_stream(3)> +L<ERR_get_error(3)>, L<CMS_sign(3)>, +L<CMS_verify(3)>, L<CMS_encrypt(3)> +L<CMS_decrypt(3)>, +L<PEM_write(3)>, +L<SMIME_write_CMS(3)>, +L<i2d_CMS_bio_stream(3)> =head1 HISTORY PEM_write_bio_CMS_stream() was added to OpenSSL 1.0.0 +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/PEM_write_bio_PKCS7_stream.pod b/deps/openssl/openssl/doc/crypto/PEM_write_bio_PKCS7_stream.pod index 16fc9b6845..77f97aaa2b 100644 --- a/deps/openssl/openssl/doc/crypto/PEM_write_bio_PKCS7_stream.pod +++ b/deps/openssl/openssl/doc/crypto/PEM_write_bio_PKCS7_stream.pod @@ -2,12 +2,11 @@ =head1 NAME -PEM_write_bio_PKCS7_stream - output PKCS7 structure in PEM format. +PEM_write_bio_PKCS7_stream - output PKCS7 structure in PEM format =head1 SYNOPSIS #include <openssl/pkcs7.h> - #include <openssl/pem.h> int PEM_write_bio_PKCS7_stream(BIO *out, PKCS7 *p7, BIO *data, int flags); @@ -28,14 +27,23 @@ PEM_write_bio_PKCS7_stream() returns 1 for success or 0 for failure. =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>, -L<PKCS7_verify(3)|PKCS7_verify(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)> -L<PKCS7_decrypt(3)|PKCS7_decrypt(3)>, -L<SMIME_write_PKCS7(3)|SMIME_write_PKCS7(3)>, -L<i2d_PKCS7_bio_stream(3)|i2d_PKCS7_bio_stream(3)> +L<ERR_get_error(3)>, L<PKCS7_sign(3)>, +L<PKCS7_verify(3)>, L<PKCS7_encrypt(3)> +L<PKCS7_decrypt(3)>, +L<SMIME_write_PKCS7(3)>, +L<i2d_PKCS7_bio_stream(3)> =head1 HISTORY PEM_write_bio_PKCS7_stream() was added to OpenSSL 1.0.0 +=head1 COPYRIGHT + +Copyright 2007-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/PKCS12_create.pod b/deps/openssl/openssl/doc/crypto/PKCS12_create.pod index de7cab2bdf..0a43b96c31 100644 --- a/deps/openssl/openssl/doc/crypto/PKCS12_create.pod +++ b/deps/openssl/openssl/doc/crypto/PKCS12_create.pod @@ -8,15 +8,16 @@ PKCS12_create - create a PKCS#12 structure #include <openssl/pkcs12.h> - PKCS12 *PKCS12_create(char *pass, char *name, EVP_PKEY *pkey, X509 *cert, STACK_OF(X509) *ca, - int nid_key, int nid_cert, int iter, int mac_iter, int keytype); + PKCS12 *PKCS12_create(const char *pass, const char *name, EVP_PKEY *pkey, + X509 *cert, STACK_OF(X509) *ca, + int nid_key, int nid_cert, int iter, int mac_iter, int keytype); =head1 DESCRIPTION PKCS12_create() creates a PKCS#12 structure. B<pass> is the passphrase to use. B<name> is the B<friendlyName> to use for -the supplied certifictate and key. B<pkey> is the private key to include in +the supplied certificate and key. B<pkey> is the private key to include in the structure and B<cert> its corresponding certificates. B<ca>, if not B<NULL> is an optional set of certificates to also include in the structure. @@ -46,30 +47,30 @@ export grade software which could use signing only keys of arbitrary size but had restrictions on the permissible sizes of keys which could be used for encryption. -=head1 NEW FUNCTIONALITY IN OPENSSL 0.9.8 - -Some additional functionality was added to PKCS12_create() in OpenSSL -0.9.8. These extensions are detailed below. - If a certificate contains an B<alias> or B<keyid> then this will be used for the corresponding B<friendlyName> or B<localKeyID> in the PKCS12 structure. Either B<pkey>, B<cert> or both can be B<NULL> to indicate that no key or -certficate is required. In previous versions both had to be present or +certificate is required. In previous versions both had to be present or a fatal error is returned. B<nid_key> or B<nid_cert> can be set to -1 indicating that no encryption -should be used. +should be used. B<mac_iter> can be set to -1 and the MAC will then be omitted entirely. =head1 SEE ALSO -L<d2i_PKCS12(3)|d2i_PKCS12(3)> +L<d2i_PKCS12(3)> + +=head1 COPYRIGHT -=head1 HISTORY +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. -PKCS12_create was added in OpenSSL 0.9.3 +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/PKCS12_newpass.pod b/deps/openssl/openssl/doc/crypto/PKCS12_newpass.pod new file mode 100644 index 0000000000..6b22fd7280 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/PKCS12_newpass.pod @@ -0,0 +1,115 @@ +=pod + +=head1 NAME + +PKCS12_newpass - change the password of a PKCS12 structure + +=head1 SYNOPSIS + + #include <openssl/pkcs12.h> + + int PKCS12_newpass(PKCS12 *p12, const char *oldpass, const char *newpass); + +=head1 DESCRIPTION + +PKCS12_newpass() changes the password of a PKCS12 structure. + +B<p12> is a pointer to a PKCS12 structure. B<oldpass> is the existing password +and B<newpass> is the new password. + +=head1 NOTES + +Each of B<oldpass> and B<newpass> is independently interpreted as a string in +the UTF-8 encoding. If it is not valid UTF-8, it is assumed to be ISO8859-1 +instead. + +In particular, this means that passwords in the locale character set +(or code page on Windows) must potentially be converted to UTF-8 before +use. This may include passwords from local text files, or input from +the terminal or command line. Refer to the documentation of +L<UI_OpenSSL(3)>, for example. + +=head1 RETURN VALUES + +PKCS12_newpass() returns 1 on success or 0 on failure. Applications can +retrieve the most recent error from PKCS12_newpass() with ERR_get_error(). + +=head1 EXAMPLE + +This example loads a PKCS#12 file, changes its password and writes out +the result to a new file. + + #include <stdio.h> + #include <stdlib.h> + #include <openssl/pem.h> + #include <openssl/err.h> + #include <openssl/pkcs12.h> + + int main(int argc, char **argv) + { + FILE *fp; + PKCS12 *p12; + if (argc != 5) { + fprintf(stderr, "Usage: pkread p12file password newpass opfile\n"); + return 1; + } + if ((fp = fopen(argv[1], "rb")) == NULL) { + fprintf(stderr, "Error opening file %s\n", argv[1]); + return 1; + } + p12 = d2i_PKCS12_fp(fp, NULL); + fclose(fp); + if (p12 == NULL) { + fprintf(stderr, "Error reading PKCS#12 file\n"); + ERR_print_errors_fp(stderr); + return 1; + } + if (PKCS12_newpass(p12, argv[2], argv[3]) == 0) { + fprintf(stderr, "Error changing password\n"); + ERR_print_errors_fp(stderr); + PKCS12_free(p12); + return 1; + } + if ((fp = fopen(argv[4], "wb")) == NULL) { + fprintf(stderr, "Error opening file %s\n", argv[4]); + PKCS12_free(p12); + return 1; + } + i2d_PKCS12_fp(fp, p12); + PKCS12_free(p12); + fclose(fp); + return 0; + } + + +=head1 NOTES + +If the PKCS#12 structure does not have a password, then you must use the empty +string "" for B<oldpass>. Using NULL for B<oldpass> will result in a +PKCS12_newpass() failure. + +If the wrong password is used for B<oldpass> then the function will fail, +with a MAC verification error. In rare cases the PKCS12 structure does not +contain a MAC: in this case it will usually fail with a decryption padding +error. + +=head1 BUGS + +The password format is a NULL terminated ASCII string which is converted to +Unicode form internally. As a result some passwords cannot be supplied to +this function. + +=head1 SEE ALSO + +L<PKCS12_create(3)>, L<ERR_get_error(3)> + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/PKCS12_parse.pod b/deps/openssl/openssl/doc/crypto/PKCS12_parse.pod index c54cf2ad61..c03c371a6e 100644 --- a/deps/openssl/openssl/doc/crypto/PKCS12_parse.pod +++ b/deps/openssl/openssl/doc/crypto/PKCS12_parse.pod @@ -29,11 +29,20 @@ The B<friendlyName> and B<localKeyID> attributes (if present) on each certificate will be stored in the B<alias> and B<keyid> attributes of the B<X509> structure. +The parameter B<pass> is interpreted as a string in the UTF-8 encoding. If it +is not valid UTF-8, then it is assumed to be ISO8859-1 instead. + +In particular, this means that passwords in the locale character set +(or code page on Windows) must potentially be converted to UTF-8 before +use. This may include passwords from local text files, or input from +the terminal or command line. Refer to the documentation of +L<UI_OpenSSL(3)>, for example. + =head1 RETURN VALUES PKCS12_parse() returns 1 for success and zero if an error occurred. -The error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)> +The error can be obtained from L<ERR_get_error(3)> =head1 BUGS @@ -48,10 +57,15 @@ Attributes currently cannot be stored in the private key B<EVP_PKEY> structure. =head1 SEE ALSO -L<d2i_PKCS12(3)|d2i_PKCS12(3)> +L<d2i_PKCS12(3)> + +=head1 COPYRIGHT -=head1 HISTORY +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. -PKCS12_parse was added in OpenSSL 0.9.3 +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/PKCS5_PBKDF2_HMAC.pod b/deps/openssl/openssl/doc/crypto/PKCS5_PBKDF2_HMAC.pod new file mode 100644 index 0000000000..5cc2caa5fb --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/PKCS5_PBKDF2_HMAC.pod @@ -0,0 +1,73 @@ +=pod + +=head1 NAME + +PKCS5_PBKDF2_HMAC, PKCS5_PBKDF2_HMAC_SHA1 - password based derivation routines with salt and iteration count + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int PKCS5_PBKDF2_HMAC(const char *pass, int passlen, + const unsigned char *salt, int saltlen, int iter, + const EVP_MD *digest, + int keylen, unsigned char *out); + +int PKCS5_PBKDF2_HMAC_SHA1(const char *pass, int passlen, + const unsigned char *salt, int saltlen, int iter, + int keylen, unsigned char *out); + +=head1 DESCRIPTION + +PKCS5_PBKDF2_HMAC() derives a key from a password using a salt and iteration count +as specified in RFC 2898. + +B<pass> is the password used in the derivation of length B<passlen>. B<pass> +is an optional parameter and can be NULL. If B<passlen> is -1, then the +function will calculate the length of B<pass> using strlen(). + +B<salt> is the salt used in the derivation of length B<saltlen>. If the +B<salt> is NULL, then B<saltlen> must be 0. The function will not +attempt to calculate the length of the B<salt> because it is not assumed to +be NULL terminated. + +B<iter> is the iteration count and its value should be greater than or +equal to 1. RFC 2898 suggests an iteration count of at least 1000. Any +B<iter> less than 1 is treated as a single iteration. + +B<digest> is the message digest function used in the derivation. Values include +any of the EVP_* message digests. PKCS5_PBKDF2_HMAC_SHA1() calls +PKCS5_PBKDF2_HMAC() with EVP_sha1(). + +The derived key will be written to B<out>. The size of the B<out> buffer +is specified via B<keylen>. + +=head1 NOTES + +A typical application of this function is to derive keying material for an +encryption algorithm from a password in the B<pass>, a salt in B<salt>, +and an iteration count. + +Increasing the B<iter> parameter slows down the algorithm which makes it +harder for an attacker to perform a brute force attack using a large number +of candidate passwords. + +=head1 RETURN VALUES + +PKCS5_PBKDF2_HMAC() and PBKCS5_PBKDF2_HMAC_SHA1() return 1 on success or 0 on error. + +=head1 SEE ALSO + +L<evp(3)>, L<rand(3)>, +L<EVP_BytesToKey(3)> + +=head1 COPYRIGHT + +Copyright 2014-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/PKCS7_decrypt.pod b/deps/openssl/openssl/doc/crypto/PKCS7_decrypt.pod index 325699d0b6..4ed8aa77fa 100644 --- a/deps/openssl/openssl/doc/crypto/PKCS7_decrypt.pod +++ b/deps/openssl/openssl/doc/crypto/PKCS7_decrypt.pod @@ -19,9 +19,6 @@ B<flags> is an optional set of flags. =head1 NOTES -OpenSSL_add_all_algorithms() (or equivalent) should be called before using this -function or errors about unknown algorithms will occur. - Although the recipients certificate is not needed to decrypt the data it is needed to locate the appropriate (of possible several) recipients in the PKCS#7 structure. @@ -46,10 +43,15 @@ mentioned in PKCS7_sign() also applies to PKCS7_verify(). =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)> +L<ERR_get_error(3)>, L<PKCS7_encrypt(3)> + +=head1 COPYRIGHT -=head1 HISTORY +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. -PKCS7_decrypt() was added to OpenSSL 0.9.5 +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/PKCS7_encrypt.pod b/deps/openssl/openssl/doc/crypto/PKCS7_encrypt.pod index 2cd925a7e0..4e1afc916f 100644 --- a/deps/openssl/openssl/doc/crypto/PKCS7_encrypt.pod +++ b/deps/openssl/openssl/doc/crypto/PKCS7_encrypt.pod @@ -30,7 +30,7 @@ bit RC2. These can be used by passing EVP_rc2_40_cbc() and EVP_rc2_64_cbc() respectively. The algorithm passed in the B<cipher> parameter must support ASN1 encoding of -its parameters. +its parameters. Many browsers implement a "sign and encrypt" option which is simply an S/MIME envelopedData containing an S/MIME signed message. This can be readily produced @@ -55,7 +55,7 @@ suitable for streaming I/O: no data is read from the BIO B<in>. If the flag B<PKCS7_STREAM> is set the returned B<PKCS7> structure is B<not> complete and outputting its contents via a function that does not -properly finalize the B<PKCS7> structure will give unpredictable +properly finalize the B<PKCS7> structure will give unpredictable results. Several functions including SMIME_write_PKCS7(), i2d_PKCS7_bio_stream(), @@ -70,11 +70,19 @@ The error can be obtained from ERR_get_error(3). =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_decrypt(3)|PKCS7_decrypt(3)> +L<ERR_get_error(3)>, L<PKCS7_decrypt(3)> =head1 HISTORY -PKCS7_decrypt() was added to OpenSSL 0.9.5 -The B<PKCS7_STREAM> flag was first supported in OpenSSL 1.0.0. +The B<PKCS7_STREAM> flag was added in OpenSSL 1.0.0. + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/PKCS7_sign.pod b/deps/openssl/openssl/doc/crypto/PKCS7_sign.pod index 64a35144f8..f319f664b9 100644 --- a/deps/openssl/openssl/doc/crypto/PKCS7_sign.pod +++ b/deps/openssl/openssl/doc/crypto/PKCS7_sign.pod @@ -13,9 +13,9 @@ PKCS7_sign - create a PKCS#7 signedData structure =head1 DESCRIPTION PKCS7_sign() creates and returns a PKCS#7 signedData structure. B<signcert> is -the certificate to sign with, B<pkey> is the corresponsding private key. +the certificate to sign with, B<pkey> is the corresponding private key. B<certs> is an optional additional set of certificates to include in the PKCS#7 -structure (for example any intermediate CAs in the chain). +structure (for example any intermediate CAs in the chain). The data to be signed is read from BIO B<data>. @@ -46,7 +46,7 @@ required by the S/MIME specifications) if B<PKCS7_BINARY> is set no translation occurs. This option should be used if the supplied data is in binary format otherwise the translation will corrupt it. -The signedData structure includes several PKCS#7 autenticatedAttributes +The signedData structure includes several PKCS#7 authenticatedAttributes including the signing time, the PKCS#7 content type and the supported list of ciphers in an SMIMECapabilities attribute. If B<PKCS7_NOATTR> is set then no authenticatedAttributes will be used. If B<PKCS7_NOSMIMECAP> is set then just @@ -80,13 +80,13 @@ BIO_new_PKCS7(). If a signer is specified it will use the default digest for the signing algorithm. This is B<SHA1> for both RSA and DSA keys. -In OpenSSL 1.0.0 the B<certs>, B<signcert> and B<pkey> parameters can all be +The B<certs>, B<signcert> and B<pkey> parameters can all be B<NULL> if the B<PKCS7_PARTIAL> flag is set. One or more signers can be added -using the function B<PKCS7_sign_add_signer()>. B<PKCS7_final()> must also be +using the function PKCS7_sign_add_signer(). PKCS7_final() must also be called to finalize the structure if streaming is not enabled. Alternative signing digests can also be specified using this method. -In OpenSSL 1.0.0 if B<signcert> and B<pkey> are NULL then a certificates only +If B<signcert> and B<pkey> are NULL then a certificates only PKCS#7 structure is output. In versions of OpenSSL before 1.0.0 the B<signcert> and B<pkey> parameters must @@ -103,14 +103,22 @@ occurred. The error can be obtained from ERR_get_error(3). =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_verify(3)|PKCS7_verify(3)> +L<ERR_get_error(3)>, L<PKCS7_verify(3)> =head1 HISTORY -PKCS7_sign() was added to OpenSSL 0.9.5 - -The B<PKCS7_PARTIAL> flag was added in OpenSSL 1.0.0 +The B<PKCS7_PARTIAL> flag, and the ability for B<certs>, B<signcert>, +and B<pkey> parameters to be B<NULL> to be was added in OpenSSL 1.0.0 The B<PKCS7_STREAM> flag was added in OpenSSL 1.0.0 +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/PKCS7_sign_add_signer.pod b/deps/openssl/openssl/doc/crypto/PKCS7_sign_add_signer.pod index ebec4d57de..88fef771b0 100644 --- a/deps/openssl/openssl/doc/crypto/PKCS7_sign_add_signer.pod +++ b/deps/openssl/openssl/doc/crypto/PKCS7_sign_add_signer.pod @@ -2,7 +2,7 @@ =head1 NAME -PKCS7_sign_add_signer - add a signer PKCS7 signed data structure. +PKCS7_sign_add_signer - add a signer PKCS7 signed data structure =head1 SYNOPSIS @@ -40,11 +40,11 @@ Any of the following flags (ored together) can be passed in the B<flags> parameter. If B<PKCS7_REUSE_DIGEST> is set then an attempt is made to copy the content -digest value from the PKCS7 struture: to add a signer to an existing structure. +digest value from the PKCS7 structure: to add a signer to an existing structure. An error occurs if a matching digest value cannot be found to copy. The returned PKCS7 structure will be valid and finalized when this flag is set. -If B<PKCS7_PARTIAL> is set in addition to B<PKCS7_REUSE_DIGEST> then the +If B<PKCS7_PARTIAL> is set in addition to B<PKCS7_REUSE_DIGEST> then the B<PKCS7_SIGNER_INO> structure will not be finalized so additional attributes can be added. In this case an explicit call to PKCS7_SIGNER_INFO_sign() is needed to finalize it. @@ -55,7 +55,7 @@ B<signcert> parameter though. This can reduce the size of the signature if the signers certificate can be obtained by other means: for example a previously signed message. -The signedData structure includes several PKCS#7 autenticatedAttributes +The signedData structure includes several PKCS#7 authenticatedAttributes including the signing time, the PKCS#7 content type and the supported list of ciphers in an SMIMECapabilities attribute. If B<PKCS7_NOATTR> is set then no authenticatedAttributes will be used. If B<PKCS7_NOSMIMECAP> is set then just @@ -67,7 +67,7 @@ these algorithms is disabled then it will not be included. PKCS7_sign_add_signers() returns an internal pointer to the PKCS7_SIGNER_INFO -structure just added, this can be used to set additional attributes +structure just added, this can be used to set additional attributes before it is finalized. =head1 RETURN VALUES @@ -77,11 +77,20 @@ structure just added or NULL if an error occurs. =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>, -L<PKCS7_final(3)|PKCS7_final(3)>, +L<ERR_get_error(3)>, L<PKCS7_sign(3)>, +L<PKCS7_final(3)>, =head1 HISTORY PPKCS7_sign_add_signer() was added to OpenSSL 1.0.0 +=head1 COPYRIGHT + +Copyright 2007-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/PKCS7_verify.pod b/deps/openssl/openssl/doc/crypto/PKCS7_verify.pod index f083306b0d..c34808eced 100644 --- a/deps/openssl/openssl/doc/crypto/PKCS7_verify.pod +++ b/deps/openssl/openssl/doc/crypto/PKCS7_verify.pod @@ -16,7 +16,7 @@ PKCS7_verify, PKCS7_get0_signers - verify a PKCS#7 signedData structure PKCS7_verify() verifies a PKCS#7 signedData structure. B<p7> is the PKCS7 structure to verify. B<certs> is a set of certificates in which to search for -the signer's certificate. B<store> is a trusted certficate store (used for +the signer's certificate. B<store> is a trusted certificate store (used for chain verification). B<indata> is the signed data if the content is not present in B<p7> (that is it is detached). The content is written to B<out> if it is not NULL. @@ -34,7 +34,12 @@ Normally the verify process proceeds as follows. Initially some sanity checks are performed on B<p7>. The type of B<p7> must be signedData. There must be at least one signature on the data and if -the content is detached B<indata> cannot be B<NULL>. +the content is detached B<indata> cannot be B<NULL>. If the content is +not detached and B<indata> is not B<NULL>, then the structure has both +embedded and external content. To treat this as an error, use the flag +B<PKCS7_NO_DUAL_CONTENT>. +The default behavior allows this, for compatibility with older +versions of OpenSSL. An attempt is made to locate all the signer's certificates, first looking in the B<certs> parameter (if it is not B<NULL>) and then looking in any certificates @@ -54,7 +59,7 @@ Any of the following flags (ored together) can be passed in the B<flags> paramet to change the default verify behaviour. Only the flag B<PKCS7_NOINTERN> is meaningful to PKCS7_get0_signers(). -If B<PKCS7_NOINTERN> is set the certificates in the message itself are not +If B<PKCS7_NOINTERN> is set the certificates in the message itself are not searched when locating the signer's certificate. This means that all the signers certificates must be in the B<certs> parameter. @@ -79,7 +84,7 @@ certificates supplied in B<certs> then the verify will fail because the signer cannot be found. Care should be taken when modifying the default verify behaviour, for example -setting B<PKCS7_NOVERIFY|PKCS7_NOSIGS> will totally disable all verification +setting B<PKCS7_NOVERIFY|PKCS7_NOSIGS> will totally disable all verification and any signed message will be considered valid. This combination is however useful if one merely wishes to write the content to B<out> and its validity is not considered important. @@ -96,7 +101,7 @@ if an error occurs. PKCS7_get0_signers() returns all signers or B<NULL> if an error occurred. -The error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)> +The error can be obtained from L<ERR_get_error(3)> =head1 BUGS @@ -109,10 +114,15 @@ mentioned in PKCS7_sign() also applies to PKCS7_verify(). =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)> +L<ERR_get_error(3)>, L<PKCS7_sign(3)> -=head1 HISTORY +=head1 COPYRIGHT -PKCS7_verify() was added to OpenSSL 0.9.5 +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/RAND_add.pod b/deps/openssl/openssl/doc/crypto/RAND_add.pod index 67c66f3e0c..46de165a97 100644 --- a/deps/openssl/openssl/doc/crypto/RAND_add.pod +++ b/deps/openssl/openssl/doc/crypto/RAND_add.pod @@ -15,8 +15,10 @@ entropy to the PRNG int RAND_status(void); + #if OPENSSL_API_COMPAT < 0x10100000L int RAND_event(UINT iMsg, WPARAM wParam, LPARAM lParam); void RAND_screen(void); + #endif =head1 DESCRIPTION @@ -37,41 +39,41 @@ OpenSSL makes sure that the PRNG state is unique for each thread. On systems that provide C</dev/urandom>, the randomness device is used to seed the PRNG transparently. However, on all other systems, the application is responsible for seeding the PRNG by calling RAND_add(), -L<RAND_egd(3)|RAND_egd(3)> -or L<RAND_load_file(3)|RAND_load_file(3)>. +L<RAND_egd(3)> +or L<RAND_load_file(3)>. RAND_seed() is equivalent to RAND_add() when B<num == entropy>. -RAND_event() collects the entropy from Windows events such as mouse -movements and other user interaction. It should be called with the -B<iMsg>, B<wParam> and B<lParam> arguments of I<all> messages sent to -the window procedure. It will estimate the entropy contained in the -event message (if any), and add it to the PRNG. The program can then -process the messages as usual. - -The RAND_screen() function is available for the convenience of Windows -programmers. It adds the current contents of the screen to the PRNG. -For applications that can catch Windows events, seeding the PRNG by -calling RAND_event() is a significantly better source of -randomness. It should be noted that both methods cannot be used on -servers that run without user interaction. +RAND_event() and RAND_screen() are deprecated and should not be called. =head1 RETURN VALUES -RAND_status() and RAND_event() return 1 if the PRNG has been seeded +RAND_status() returns 1 if the PRNG has been seeded with enough data, 0 otherwise. +RAND_event() calls RAND_poll() and returns RAND_status(). + +RAND_screen calls RAND_poll(). + The other functions do not return values. +=head1 HISTORY + +RAND_event() and RAND_screen() are deprecated since OpenSSL +1.1.0. Use the functions described above instead. + =head1 SEE ALSO -L<rand(3)|rand(3)>, L<RAND_egd(3)|RAND_egd(3)>, -L<RAND_load_file(3)|RAND_load_file(3)>, L<RAND_cleanup(3)|RAND_cleanup(3)> +L<rand(3)>, L<RAND_egd(3)>, +L<RAND_load_file(3)>, L<RAND_cleanup(3)> -=head1 HISTORY +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. -RAND_seed() and RAND_screen() are available in all versions of SSLeay -and OpenSSL. RAND_add() and RAND_status() have been added in OpenSSL -0.9.5, RAND_event() in OpenSSL 0.9.5a. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/RAND_bytes.pod b/deps/openssl/openssl/doc/crypto/RAND_bytes.pod index 1a9b91e281..684215cea3 100644 --- a/deps/openssl/openssl/doc/crypto/RAND_bytes.pod +++ b/deps/openssl/openssl/doc/crypto/RAND_bytes.pod @@ -10,7 +10,11 @@ RAND_bytes, RAND_pseudo_bytes - generate random data int RAND_bytes(unsigned char *buf, int num); +Deprecated: + + #if OPENSSL_API_COMPAT < 0x10100000L int RAND_pseudo_bytes(unsigned char *buf, int num); + #endif =head1 DESCRIPTION @@ -18,6 +22,7 @@ RAND_bytes() puts B<num> cryptographically strong pseudo-random bytes into B<buf>. An error occurs if the PRNG has not been seeded with enough randomness to ensure an unpredictable byte sequence. +RAND_pseudo_bytes() has been deprecated. Users should use RAND_bytes() instead. RAND_pseudo_bytes() puts B<num> pseudo-random bytes into B<buf>. Pseudo-random byte sequences generated by RAND_pseudo_bytes() will be unique if they are of sufficient length, but are not necessarily @@ -31,20 +36,23 @@ the new pseudo-random bytes unless disabled at compile time (see FAQ). =head1 RETURN VALUES RAND_bytes() returns 1 on success, 0 otherwise. The error code can be -obtained by L<ERR_get_error(3)|ERR_get_error(3)>. RAND_pseudo_bytes() returns 1 if the +obtained by L<ERR_get_error(3)>. RAND_pseudo_bytes() returns 1 if the bytes generated are cryptographically strong, 0 otherwise. Both functions return -1 if they are not supported by the current RAND method. =head1 SEE ALSO -L<rand(3)|rand(3)>, L<ERR_get_error(3)|ERR_get_error(3)>, -L<RAND_add(3)|RAND_add(3)> +L<rand(3)>, L<ERR_get_error(3)>, +L<RAND_add(3)> + +=head1 COPYRIGHT -=head1 HISTORY +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. -RAND_bytes() is available in all versions of SSLeay and OpenSSL. It -has a return value since OpenSSL 0.9.5. RAND_pseudo_bytes() was added -in OpenSSL 0.9.5. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/RAND_cleanup.pod b/deps/openssl/openssl/doc/crypto/RAND_cleanup.pod index 3a8f0749a8..2640c7d2c7 100644 --- a/deps/openssl/openssl/doc/crypto/RAND_cleanup.pod +++ b/deps/openssl/openssl/doc/crypto/RAND_cleanup.pod @@ -8,11 +8,15 @@ RAND_cleanup - erase the PRNG state #include <openssl/rand.h> - void RAND_cleanup(void); + #if OPENSSL_API_COMPAT < 0x10100000L + void RAND_cleanup(void) + #endif =head1 DESCRIPTION -RAND_cleanup() erases the memory used by the PRNG. +Prior to OpenSSL 1.1.0 RAND_cleanup() erases the memory used by the PRNG. This +function is deprecated and as of version 1.1.0 does nothing. No explicit +initialisation or de-initialisation is necessary. See L<OPENSSL_init_crypto(3)>. =head1 RETURN VALUE @@ -20,10 +24,19 @@ RAND_cleanup() returns no value. =head1 SEE ALSO -L<rand(3)|rand(3)> +L<rand(3)> =head1 HISTORY -RAND_cleanup() is available in all versions of SSLeay and OpenSSL. +RAND_cleanup() was deprecated in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/RAND_egd.pod b/deps/openssl/openssl/doc/crypto/RAND_egd.pod index 80fa734d18..fcc57c06f9 100644 --- a/deps/openssl/openssl/doc/crypto/RAND_egd.pod +++ b/deps/openssl/openssl/doc/crypto/RAND_egd.pod @@ -16,12 +16,12 @@ RAND_egd, RAND_egd_bytes, RAND_query_egd_bytes - query entropy gathering daemon =head1 DESCRIPTION RAND_egd() queries the entropy gathering daemon EGD on socket B<path>. -It queries 255 bytes and uses L<RAND_add(3)|RAND_add(3)> to seed the +It queries 255 bytes and uses L<RAND_add(3)> to seed the OpenSSL built-in PRNG. RAND_egd(path) is a wrapper for RAND_egd_bytes(path, 255); RAND_egd_bytes() queries the entropy gathering daemon EGD on socket B<path>. -It queries B<bytes> bytes and uses L<RAND_add(3)|RAND_add(3)> to seed the +It queries B<bytes> bytes and uses L<RAND_add(3)> to seed the OpenSSL built-in PRNG. This function is more flexible than RAND_egd(). When only one secret key must @@ -32,7 +32,7 @@ that can be retrieved from EGD over time is limited. RAND_query_egd_bytes() performs the actual query of the EGD daemon on socket B<path>. If B<buf> is given, B<bytes> bytes are queried and written into B<buf>. If B<buf> is NULL, B<bytes> bytes are queried and used to seed the -OpenSSL built-in PRNG using L<RAND_add(3)|RAND_add(3)>. +OpenSSL built-in PRNG using L<RAND_add(3)>. =head1 NOTES @@ -72,17 +72,16 @@ success, and -1 if the connection failed. The PRNG state is not considered. =head1 SEE ALSO -L<rand(3)|rand(3)>, L<RAND_add(3)|RAND_add(3)>, -L<RAND_cleanup(3)|RAND_cleanup(3)> +L<rand(3)>, L<RAND_add(3)>, +L<RAND_cleanup(3)> -=head1 HISTORY +=head1 COPYRIGHT -RAND_egd() is available since OpenSSL 0.9.5. +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. -RAND_egd_bytes() is available since OpenSSL 0.9.6. - -RAND_query_egd_bytes() is available since OpenSSL 0.9.7. - -The automatic query of /var/run/egd-pool et al was added in OpenSSL 0.9.7. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/RAND_load_file.pod b/deps/openssl/openssl/doc/crypto/RAND_load_file.pod index d8c134e621..1053a925ad 100644 --- a/deps/openssl/openssl/doc/crypto/RAND_load_file.pod +++ b/deps/openssl/openssl/doc/crypto/RAND_load_file.pod @@ -18,13 +18,35 @@ RAND_load_file, RAND_write_file, RAND_file_name - PRNG seed file RAND_file_name() generates a default path for the random seed file. B<buf> points to a buffer of size B<num> in which to store the -filename. The seed file is $RANDFILE if that environment variable is -set, $HOME/.rnd otherwise. If $HOME is not set either, or B<num> is -too small for the path name, an error occurs. +filename. + +On all systems, if the environment variable B<RANDFILE> is set, its +value will be used as the seed file name. + +Otherwise, the file is called ".rnd", found in platform dependent locations: + +=over 4 + +=item On Windows (in order of preference) + +%HOME%, %USERPROFILE%, %SYSTEMROOT%, C:\ + +=item On VMS + +SYS$LOGIN: + +=item On all other systems + +$HOME + +=back + +If C<$HOME> (on non-Windows and non-VMS system) is not set either, or +B<num> is too small for the path name, an error occurs. RAND_load_file() reads a number of bytes from file B<filename> and adds them to the PRNG. If B<max_bytes> is non-negative, -up to to B<max_bytes> are read; starting with OpenSSL 0.9.5, +up to B<max_bytes> are read; if B<max_bytes> is -1, the complete file is read. RAND_write_file() writes a number of random bytes (currently 1024) to @@ -33,7 +55,7 @@ RAND_load_file() in a later session. =head1 RETURN VALUES -RAND_load_file() returns the number of bytes read. +RAND_load_file() returns the number of bytes read or -1 on error. RAND_write_file() returns the number of bytes written, and -1 if the bytes written were generated without appropriate seed. @@ -43,11 +65,15 @@ error. =head1 SEE ALSO -L<rand(3)|rand(3)>, L<RAND_add(3)|RAND_add(3)>, L<RAND_cleanup(3)|RAND_cleanup(3)> +L<rand(3)>, L<RAND_add(3)>, L<RAND_cleanup(3)> + +=head1 COPYRIGHT -=head1 HISTORY +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. -RAND_load_file(), RAND_write_file() and RAND_file_name() are available in -all versions of SSLeay and OpenSSL. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/RAND_set_rand_method.pod b/deps/openssl/openssl/doc/crypto/RAND_set_rand_method.pod index e5b780fad0..02fe90ca89 100644 --- a/deps/openssl/openssl/doc/crypto/RAND_set_rand_method.pod +++ b/deps/openssl/openssl/doc/crypto/RAND_set_rand_method.pod @@ -2,7 +2,7 @@ =head1 NAME -RAND_set_rand_method, RAND_get_rand_method, RAND_SSLeay - select RAND method +RAND_set_rand_method, RAND_get_rand_method, RAND_OpenSSL - select RAND method =head1 SYNOPSIS @@ -12,7 +12,7 @@ RAND_set_rand_method, RAND_get_rand_method, RAND_SSLeay - select RAND method const RAND_METHOD *RAND_get_rand_method(void); - RAND_METHOD *RAND_SSLeay(void); + RAND_METHOD *RAND_OpenSSL(void); =head1 DESCRIPTION @@ -23,7 +23,7 @@ information about how these RAND API functions are affected by the use of B<ENGINE> API calls. Initially, the default RAND_METHOD is the OpenSSL internal implementation, as -returned by RAND_SSLeay(). +returned by RAND_OpenSSL(). RAND_set_default_method() makes B<meth> the method for PRNG use. B<NB>: This is true only whilst no ENGINE has been set as a default for RAND, so this function @@ -42,22 +42,22 @@ API is being used, so this function is no longer recommended. void (*cleanup)(void); void (*add)(const void *buf, int num, int entropy); int (*pseudorand)(unsigned char *buf, int num); - int (*status)(void); + int (*status)(void); } RAND_METHOD; -The components point to the implementation of RAND_seed(), -RAND_bytes(), RAND_cleanup(), RAND_add(), RAND_pseudo_rand() +The components point to method implementations used by (or called by), in order, +RAND_seed(), RAND_bytes(), internal RAND cleanup, RAND_add(), RAND_pseudo_rand() and RAND_status(). Each component may be NULL if the function is not implemented. =head1 RETURN VALUES RAND_set_rand_method() returns no value. RAND_get_rand_method() and -RAND_SSLeay() return pointers to the respective methods. +RAND_OpenSSL() return pointers to the respective methods. =head1 NOTES -As of version 0.9.7, RAND_METHOD implementations are grouped together with other +RAND_METHOD implementations are grouped together with other algorithmic APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in B<ENGINE> modules. If a default ENGINE is specified for RAND functionality using an ENGINE API function, that will override any RAND defaults set using the RAND API (ie. @@ -67,17 +67,15 @@ algorithms. =head1 SEE ALSO -L<rand(3)|rand(3)>, L<engine(3)|engine(3)> +L<rand(3)>, L<engine(3)> -=head1 HISTORY +=head1 COPYRIGHT -RAND_set_rand_method(), RAND_get_rand_method() and RAND_SSLeay() are -available in all versions of OpenSSL. +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. -In the engine version of version 0.9.6, RAND_set_rand_method() was altered to -take an ENGINE pointer as its argument. As of version 0.9.7, that has been -reverted as the ENGINE API transparently overrides RAND defaults if used, -otherwise RAND API functions work as before. RAND_set_rand_engine() was also -introduced in version 0.9.7. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/rc4.pod b/deps/openssl/openssl/doc/crypto/RC4_set_key.pod index b6d3a4342c..fe5d2d1485 100644 --- a/deps/openssl/openssl/doc/crypto/rc4.pod +++ b/deps/openssl/openssl/doc/crypto/RC4_set_key.pod @@ -37,26 +37,30 @@ Since RC4 is a stream cipher (the input is XORed with a pseudo-random key stream to produce the output), decryption uses the same function calls as encryption. -Applications should use the higher level functions -L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> -etc. instead of calling the RC4 functions directly. - =head1 RETURN VALUES RC4_set_key() and RC4() do not return values. =head1 NOTE -Certain conditions have to be observed to securely use stream ciphers. -It is not permissible to perform multiple encryptions using the same -key stream. +Applications should use the higher level functions +L<EVP_EncryptInit(3)> etc. instead of calling these +functions directly. + +It is difficult to securely use stream ciphers. For example, do not perform +multiple encryptions using the same key stream. =head1 SEE ALSO -L<blowfish(3)|blowfish(3)>, L<des(3)|des(3)>, L<rc2(3)|rc2(3)> +L<EVP_EncryptInit(3)> + +=head1 COPYRIGHT -=head1 HISTORY +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. -RC4_set_key() and RC4() are available in all versions of SSLeay and OpenSSL. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/ripemd.pod b/deps/openssl/openssl/doc/crypto/RIPEMD160_Init.pod index 264bb99ae7..a372e32ca3 100644 --- a/deps/openssl/openssl/doc/crypto/ripemd.pod +++ b/deps/openssl/openssl/doc/crypto/RIPEMD160_Init.pod @@ -39,28 +39,34 @@ RIPEMD160_Final() places the message digest in B<md>, which must have space for RIPEMD160_DIGEST_LENGTH == 20 bytes of output, and erases the B<RIPEMD160_CTX>. -Applications should use the higher level functions -L<EVP_DigestInit(3)|EVP_DigestInit(3)> etc. instead of calling the -hash functions directly. - =head1 RETURN VALUES -RIPEMD160() returns a pointer to the hash value. +RIPEMD160() returns a pointer to the hash value. RIPEMD160_Init(), RIPEMD160_Update() and RIPEMD160_Final() return 1 for success, 0 otherwise. +=head1 NOTE + +Applications should use the higher level functions +L<EVP_DigestInit(3)> etc. instead of calling these +functions directly. + =head1 CONFORMING TO ISO/IEC 10118-3 (draft) (??) =head1 SEE ALSO -L<sha(3)|sha(3)>, L<hmac(3)|hmac(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)> +L<EVP_DigestInit(3)> + +=head1 COPYRIGHT -=head1 HISTORY +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. -RIPEMD160(), RIPEMD160_Init(), RIPEMD160_Update() and -RIPEMD160_Final() are available since SSLeay 0.9.0. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/RSA_blinding_on.pod b/deps/openssl/openssl/doc/crypto/RSA_blinding_on.pod index fd2c69abd8..33d49d3720 100644 --- a/deps/openssl/openssl/doc/crypto/RSA_blinding_on.pod +++ b/deps/openssl/openssl/doc/crypto/RSA_blinding_on.pod @@ -32,12 +32,13 @@ RSA_blinding_on() returns 1 on success, and 0 if an error occurred. RSA_blinding_off() returns no value. -=head1 SEE ALSO +=head1 COPYRIGHT -L<rsa(3)|rsa(3)>, L<rand(3)|rand(3)> +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. -=head1 HISTORY - -RSA_blinding_on() and RSA_blinding_off() appeared in SSLeay 0.9.0. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/RSA_check_key.pod b/deps/openssl/openssl/doc/crypto/RSA_check_key.pod index a5198f3db5..d8689f4a2b 100644 --- a/deps/openssl/openssl/doc/crypto/RSA_check_key.pod +++ b/deps/openssl/openssl/doc/crypto/RSA_check_key.pod @@ -2,41 +2,48 @@ =head1 NAME -RSA_check_key - validate private RSA keys +RSA_check_key_ex, RSA_check_key - validate private RSA keys =head1 SYNOPSIS #include <openssl/rsa.h> + int RSA_check_key_ex(RSA *rsa, BN_GENCB *cb); + int RSA_check_key(RSA *rsa); =head1 DESCRIPTION -This function validates RSA keys. It checks that B<p> and B<q> are +RSA_check_key_ex() function validates RSA keys. +It checks that B<p> and B<q> are in fact prime, and that B<n = p*q>. +It does not work on RSA public keys that have only the modulus +and public exponent elements populated. It also checks that B<d*e = 1 mod (p-1*q-1)>, and that B<dmp1>, B<dmq1> and B<iqmp> are set correctly or are B<NULL>. +It performs integrity checks on all +the RSA key material, so the RSA key structure must contain all the private +key data too. +Therefore, it cannot be used with any arbitrary RSA key object, +even if it is otherwise fit for regular RSA operation. -As such, this function can not be used with any arbitrary RSA key object, -even if it is otherwise fit for regular RSA operation. See B<NOTES> for more -information. +The B<cb> parameter is a callback that will be invoked in the same +manner as L<BN_is_prime_ex(3)>. + +RSA_check_key() is equivalent to RSA_check_key_ex() with a NULL B<cb>. =head1 RETURN VALUE -RSA_check_key() returns 1 if B<rsa> is a valid RSA key, and 0 otherwise. --1 is returned if an error occurs while checking the key. +RSA_check_key_ex() and RSA_check_key() +return 1 if B<rsa> is a valid RSA key, and 0 otherwise. +They return -1 if an error occurs while checking the key. If the key is invalid or an error occurred, the reason code can be -obtained using L<ERR_get_error(3)|ERR_get_error(3)>. +obtained using L<ERR_get_error(3)>. =head1 NOTES -This function does not work on RSA public keys that have only the modulus -and public exponent elements populated. It performs integrity checks on all -the RSA key material, so the RSA key structure must contain all the private -key data too. - Unlike most other RSA functions, this function does B<not> work transparently with any underlying ENGINE implementation because it uses the key data in the RSA structure directly. An ENGINE implementation can @@ -58,10 +65,20 @@ provide their own verifiers. =head1 SEE ALSO -L<rsa(3)|rsa(3)>, L<ERR_get_error(3)|ERR_get_error(3)> +L<BN_is_prime_ex(3)>, +L<ERR_get_error(3)> =head1 HISTORY -RSA_check_key() appeared in OpenSSL 0.9.4. +RSA_check_key_ex() appeared after OpenSSL 1.0.2. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/RSA_generate_key.pod b/deps/openssl/openssl/doc/crypto/RSA_generate_key.pod index 0882a1a59d..e51c0b147b 100644 --- a/deps/openssl/openssl/doc/crypto/RSA_generate_key.pod +++ b/deps/openssl/openssl/doc/crypto/RSA_generate_key.pod @@ -12,8 +12,10 @@ RSA_generate_key_ex, RSA_generate_key - generate RSA key pair Deprecated: + #if OPENSSL_API_COMPAT < 0x00908000L RSA *RSA_generate_key(int num, unsigned long e, - void (*callback)(int,int,void *), void *cb_arg); + void (*callback)(int, int, void *), void *cb_arg); + #endif =head1 DESCRIPTION @@ -28,14 +30,14 @@ The exponent is an odd number, typically 3, 17 or 65537. A callback function may be used to provide feedback about the progress of the key generation. If B<cb> is not B<NULL>, it will be called as follows using the BN_GENCB_call() function -described on the L<BN_generate_prime(3)|BN_generate_prime(3)> page. +described on the L<BN_generate_prime(3)> page. -=over 4 +=over 2 =item * While a random prime number is generated, it is called as -described in L<BN_generate_prime(3)|BN_generate_prime(3)>. +described in L<BN_generate_prime(3)>. =item * @@ -51,16 +53,17 @@ it is called as B<BN_GENCB_call(cb, 3, 0)>. The process is then repeated for prime q with B<BN_GENCB_call(cb, 3, 1)>. -RSA_generate_key is deprecated (new applications should use -RSA_generate_key_ex instead). RSA_generate_key works in the same way as -RSA_generate_key_ex except it uses "old style" call backs. See -L<BN_generate_prime(3)|BN_generate_prime(3)> for further details. +RSA_generate_key() is deprecated (new applications should use +RSA_generate_key_ex() instead). RSA_generate_key() works in the same way as +RSA_generate_key_ex() except it uses "old style" call backs. See +L<BN_generate_prime(3)> for further details. =head1 RETURN VALUE -If key generation fails, RSA_generate_key() returns B<NULL>. +RSA_generate_key_ex() returns 1 on success or 0 on error. +RSA_generate_key() returns the key on success or B<NULL> on error. -The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. +The error codes can be obtained by L<ERR_get_error(3)>. =head1 BUGS @@ -70,11 +73,16 @@ RSA_generate_key() goes into an infinite loop for illegal input values. =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, -L<RSA_free(3)|RSA_free(3)>, L<BN_generate_prime(3)|BN_generate_prime(3)> +L<ERR_get_error(3)>, L<RAND_bytes(3)>, +L<RSA_generate_key(3)>, L<BN_generate_prime(3)> -=head1 HISTORY +=head1 COPYRIGHT -The B<cb_arg> argument was added in SSLeay 0.9.0. +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/RSA_get0_key.pod b/deps/openssl/openssl/doc/crypto/RSA_get0_key.pod new file mode 100644 index 0000000000..579a2df000 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/RSA_get0_key.pod @@ -0,0 +1,112 @@ +=pod + +=head1 NAME + +RSA_set0_key, RSA_set0_factors, RSA_set0_crt_params, RSA_get0_key, +RSA_get0_factors, RSA_get0_crt_params, RSA_clear_flags, +RSA_test_flags, RSA_set_flags, RSA_get0_engine - Routines for getting +and setting data in an RSA object + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + int RSA_set0_key(RSA *r, BIGNUM *n, BIGNUM *e, BIGNUM *d); + int RSA_set0_factors(RSA *r, BIGNUM *p, BIGNUM *q); + int RSA_set0_crt_params(RSA *r, BIGNUM *dmp1, BIGNUM *dmq1, BIGNUM *iqmp); + void RSA_get0_key(const RSA *r, + const BIGNUM **n, const BIGNUM **e, const BIGNUM **d); + void RSA_get0_factors(const RSA *r, const BIGNUM **p, const BIGNUM **q); + void RSA_get0_crt_params(const RSA *r, + const BIGNUM **dmp1, const BIGNUM **dmq1, + const BIGNUM **iqmp); + void RSA_clear_flags(RSA *r, int flags); + int RSA_test_flags(const RSA *r, int flags); + void RSA_set_flags(RSA *r, int flags); + ENGINE *RSA_get0_engine(RSA *r); + +=head1 DESCRIPTION + +An RSA object contains the components for the public and private key, +B<n>, B<e>, B<d>, B<p>, B<q>, B<dmp1>, B<dmq1> and B<iqmp>. B<n> is +the modulus common to both public and private key, B<e> is the public +exponent and B<d> is the private exponent. B<p>, B<q>, B<dmp1>, +B<dmq1> and B<iqmp> are the factors for the second representation of a +private key (see PKCS#1 section 3 Key Types), where B<p> and B<q> are +the first and second factor of B<n> and B<dmp1>, B<dmq1> and B<iqmp> +are the exponents and coefficient for CRT calculations. + +The B<n>, B<e> and B<d> parameters can be obtained by calling +RSA_get0_key(). If they have not been set yet, then B<*n>, B<*e> and +B<*d> will be set to NULL. Otherwise, they are set to pointers to +their respective values. These point directly to the internal +representations of the values and therefore should not be freed +by the caller. + +The B<n>, B<e> and B<d> parameter values can be set by calling +RSA_set0_key() and passing the new values for B<n>, B<e> and B<d> as +parameters to the function. The values B<n> and B<e> must be non-NULL +the first time this function is called on a given RSA object. The +value B<d> may be NULL. On subsequent calls any of these values may be +NULL which means the corresponding RSA field is left untouched. +Calling this function transfers the memory management of the values to +the RSA object, and therefore the values that have been passed in +should not be freed by the caller after this function has been called. + +In a similar fashion, the B<p> and B<q> parameters can be obtained and +set with RSA_get0_factors() and RSA_set0_factors(), and the B<dmp1>, +B<dmq1> and B<iqmp> parameters can be obtained and set with +RSA_get0_crt_params() and RSA_set0_crt_params(). + +For RSA_get0_key(), RSA_get0_factors(), and RSA_get0_crt_params(), +NULL value BIGNUM ** output parameters are permitted. The functions +ignore NULL parameters but return values for other, non-NULL, parameters. + +RSA_set_flags() sets the flags in the B<flags> parameter on the RSA +object. Multiple flags can be passed in one go (bitwise ORed together). +Any flags that are already set are left set. RSA_test_flags() tests to +see whether the flags passed in the B<flags> parameter are currently +set in the RSA object. Multiple flags can be tested in one go. All +flags that are currently set are returned, or zero if none of the +flags are set. RSA_clear_flags() clears the specified flags within the +RSA object. + +RSA_get0_engine() returns a handle to the ENGINE that has been set for +this RSA object, or NULL if no such ENGINE has been set. + +=head1 NOTES + +Values retrieved with RSA_get0_key() are owned by the RSA object used +in the call and may therefore I<not> be passed to RSA_set0_key(). If +needed, duplicate the received value using BN_dup() and pass the +duplicate. The same applies to RSA_get0_factors() and RSA_set0_factors() +as well as RSA_get0_crt_params() and RSA_set0_crt_params(). + +=head1 RETURN VALUES + +RSA_set0_key(), RSA_set0_factors and RSA_set0_crt_params() return 1 on +success or 0 on failure. + +RSA_test_flags() returns the current state of the flags in the RSA object. + +RSA_get0_engine() returns the ENGINE set for the RSA object or NULL if no +ENGINE has been set. + +=head1 SEE ALSO + +L<rsa(3)>, L<RSA_new(3)>, L<RSA_size(3)> + +=head1 HISTORY + +The functions described here were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/RSA_get_ex_new_index.pod b/deps/openssl/openssl/doc/crypto/RSA_get_ex_new_index.pod deleted file mode 100644 index 7d0fd1f91d..0000000000 --- a/deps/openssl/openssl/doc/crypto/RSA_get_ex_new_index.pod +++ /dev/null @@ -1,120 +0,0 @@ -=pod - -=head1 NAME - -RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data - add application specific data to RSA structures - -=head1 SYNOPSIS - - #include <openssl/rsa.h> - - int RSA_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - - int RSA_set_ex_data(RSA *r, int idx, void *arg); - - void *RSA_get_ex_data(RSA *r, int idx); - - typedef int CRYPTO_EX_new(void *parent, void *ptr, CRYPTO_EX_DATA *ad, - int idx, long argl, void *argp); - typedef void CRYPTO_EX_free(void *parent, void *ptr, CRYPTO_EX_DATA *ad, - int idx, long argl, void *argp); - typedef int CRYPTO_EX_dup(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d, - int idx, long argl, void *argp); - -=head1 DESCRIPTION - -Several OpenSSL structures can have application specific data attached to them. -This has several potential uses, it can be used to cache data associated with -a structure (for example the hash of some part of the structure) or some -additional data (for example a handle to the data in an external library). - -Since the application data can be anything at all it is passed and retrieved -as a B<void *> type. - -The B<RSA_get_ex_new_index()> function is initially called to "register" some -new application specific data. It takes three optional function pointers which -are called when the parent structure (in this case an RSA structure) is -initially created, when it is copied and when it is freed up. If any or all of -these function pointer arguments are not used they should be set to NULL. The -precise manner in which these function pointers are called is described in more -detail below. B<RSA_get_ex_new_index()> also takes additional long and pointer -parameters which will be passed to the supplied functions but which otherwise -have no special meaning. It returns an B<index> which should be stored -(typically in a static variable) and passed used in the B<idx> parameter in -the remaining functions. Each successful call to B<RSA_get_ex_new_index()> -will return an index greater than any previously returned, this is important -because the optional functions are called in order of increasing index value. - -B<RSA_set_ex_data()> is used to set application specific data, the data is -supplied in the B<arg> parameter and its precise meaning is up to the -application. - -B<RSA_get_ex_data()> is used to retrieve application specific data. The data -is returned to the application, this will be the same value as supplied to -a previous B<RSA_set_ex_data()> call. - -B<new_func()> is called when a structure is initially allocated (for example -with B<RSA_new()>. The parent structure members will not have any meaningful -values at this point. This function will typically be used to allocate any -application specific structure. - -B<free_func()> is called when a structure is being freed up. The dynamic parent -structure members should not be accessed because they will be freed up when -this function is called. - -B<new_func()> and B<free_func()> take the same parameters. B<parent> is a -pointer to the parent RSA structure. B<ptr> is a the application specific data -(this wont be of much use in B<new_func()>. B<ad> is a pointer to the -B<CRYPTO_EX_DATA> structure from the parent RSA structure: the functions -B<CRYPTO_get_ex_data()> and B<CRYPTO_set_ex_data()> can be called to manipulate -it. The B<idx> parameter is the index: this will be the same value returned by -B<RSA_get_ex_new_index()> when the functions were initially registered. Finally -the B<argl> and B<argp> parameters are the values originally passed to the same -corresponding parameters when B<RSA_get_ex_new_index()> was called. - -B<dup_func()> is called when a structure is being copied. Pointers to the -destination and source B<CRYPTO_EX_DATA> structures are passed in the B<to> and -B<from> parameters respectively. The B<from_d> parameter is passed a pointer to -the source application data when the function is called, when the function returns -the value is copied to the destination: the application can thus modify the data -pointed to by B<from_d> and have different values in the source and destination. -The B<idx>, B<argl> and B<argp> parameters are the same as those in B<new_func()> -and B<free_func()>. - -=head1 RETURN VALUES - -B<RSA_get_ex_new_index()> returns a new index or -1 on failure (note 0 is a valid -index value). - -B<RSA_set_ex_data()> returns 1 on success or 0 on failure. - -B<RSA_get_ex_data()> returns the application data or 0 on failure. 0 may also -be valid application data but currently it can only fail if given an invalid B<idx> -parameter. - -B<new_func()> and B<dup_func()> should return 0 for failure and 1 for success. - -On failure an error code can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>. - -=head1 BUGS - -B<dup_func()> is currently never called. - -The return value of B<new_func()> is ignored. - -The B<new_func()> function isn't very useful because no meaningful values are -present in the parent RSA structure when it is called. - -=head1 SEE ALSO - -L<rsa(3)|rsa(3)>, L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)> - -=head1 HISTORY - -RSA_get_ex_new_index(), RSA_set_ex_data() and RSA_get_ex_data() are -available since SSLeay 0.9.0. - -=cut diff --git a/deps/openssl/openssl/doc/crypto/RSA_meth_new.pod b/deps/openssl/openssl/doc/crypto/RSA_meth_new.pod new file mode 100644 index 0000000000..9970aa6b73 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/RSA_meth_new.pod @@ -0,0 +1,235 @@ +=pod + +=head1 NAME + +RSA_meth_get0_app_data, RSA_meth_set0_app_data, +RSA_meth_new, RSA_meth_free, RSA_meth_dup, RSA_meth_get0_name, +RSA_meth_set1_name, RSA_meth_get_flags, RSA_meth_set_flags, +RSA_meth_get_pub_enc, +RSA_meth_set_pub_enc, RSA_meth_get_pub_dec, RSA_meth_set_pub_dec, +RSA_meth_get_priv_enc, RSA_meth_set_priv_enc, RSA_meth_get_priv_dec, +RSA_meth_set_priv_dec, RSA_meth_get_mod_exp, RSA_meth_set_mod_exp, +RSA_meth_get_bn_mod_exp, RSA_meth_set_bn_mod_exp, RSA_meth_get_init, +RSA_meth_set_init, RSA_meth_get_finish, RSA_meth_set_finish, +RSA_meth_get_sign, RSA_meth_set_sign, RSA_meth_get_verify, +RSA_meth_set_verify, RSA_meth_get_keygen, RSA_meth_set_keygen +- Routines to build up RSA methods + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + RSA_METHOD *RSA_meth_new(const char *name, int flags); + void RSA_meth_free(RSA_METHOD *meth); + RSA_METHOD *RSA_meth_dup(const RSA_METHOD *meth); + const char *RSA_meth_get0_name(const RSA_METHOD *meth); + int RSA_meth_set1_name(RSA_METHOD *meth, const char *name); + int RSA_meth_get_flags(RSA_METHOD *meth); + int RSA_meth_set_flags(RSA_METHOD *meth, int flags); + void *RSA_meth_get0_app_data(const RSA_METHOD *meth); + int RSA_meth_set0_app_data(RSA_METHOD *meth, void *app_data); + int (*RSA_meth_get_pub_enc(const RSA_METHOD *meth)) + (int flen, const unsigned char *from, + unsigned char *to, RSA *rsa, int padding); + int RSA_meth_set_pub_enc(RSA_METHOD *rsa, + int (*pub_enc) (int flen, const unsigned char *from, + unsigned char *to, RSA *rsa, + int padding)); + int (*RSA_meth_get_pub_dec(const RSA_METHOD *meth)) + (int flen, const unsigned char *from, + unsigned char *to, RSA *rsa, int padding); + int RSA_meth_set_pub_dec(RSA_METHOD *rsa, + int (*pub_dec) (int flen, const unsigned char *from, + unsigned char *to, RSA *rsa, + int padding)); + int (*RSA_meth_get_priv_enc(const RSA_METHOD *meth)) + (int flen, const unsigned char *from, + unsigned char *to, RSA *rsa, int padding); + int RSA_meth_set_priv_enc(RSA_METHOD *rsa, + int (*priv_enc) (int flen, const unsigned char *from, + unsigned char *to, RSA *rsa, + int padding)); + int (*RSA_meth_get_priv_dec(const RSA_METHOD *meth)) + (int flen, const unsigned char *from, + unsigned char *to, RSA *rsa, int padding); + int RSA_meth_set_priv_dec(RSA_METHOD *rsa, + int (*priv_dec) (int flen, const unsigned char *from, + unsigned char *to, RSA *rsa, + int padding)); + /* Can be null */ + int (*RSA_meth_get_mod_exp(const RSA_METHOD *meth)) + (BIGNUM *r0, const BIGNUM *I, RSA *rsa, BN_CTX *ctx); + int RSA_meth_set_mod_exp(RSA_METHOD *rsa, + int (*mod_exp) (BIGNUM *r0, const BIGNUM *I, RSA *rsa, + BN_CTX *ctx)); + /* Can be null */ + int (*RSA_meth_get_bn_mod_exp(const RSA_METHOD *meth)) + (BIGNUM *r, const BIGNUM *a, const BIGNUM *p, + const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx); + int RSA_meth_set_bn_mod_exp(RSA_METHOD *rsa, + int (*bn_mod_exp) (BIGNUM *r, + const BIGNUM *a, + const BIGNUM *p, + const BIGNUM *m, + BN_CTX *ctx, + BN_MONT_CTX *m_ctx)); + /* called at new */ + int (*RSA_meth_get_init(const RSA_METHOD *meth)) (RSA *rsa); + int RSA_meth_set_init(RSA_METHOD *rsa, int (*init) (RSA *rsa)); + /* called at free */ + int (*RSA_meth_get_finish(const RSA_METHOD *meth)) (RSA *rsa); + int RSA_meth_set_finish(RSA_METHOD *rsa, int (*finish) (RSA *rsa)); + int (*RSA_meth_get_sign(const RSA_METHOD *meth)) + (int type, + const unsigned char *m, unsigned int m_length, + unsigned char *sigret, unsigned int *siglen, + const RSA *rsa); + int RSA_meth_set_sign(RSA_METHOD *rsa, + int (*sign) (int type, const unsigned char *m, + unsigned int m_length, + unsigned char *sigret, unsigned int *siglen, + const RSA *rsa)); + int (*RSA_meth_get_verify(const RSA_METHOD *meth)) + (int dtype, const unsigned char *m, + unsigned int m_length, const unsigned char *sigbuf, + unsigned int siglen, const RSA *rsa); + int RSA_meth_set_verify(RSA_METHOD *rsa, + int (*verify) (int dtype, const unsigned char *m, + unsigned int m_length, + const unsigned char *sigbuf, + unsigned int siglen, const RSA *rsa)); + int (*RSA_meth_get_keygen(const RSA_METHOD *meth)) + (RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb); + int RSA_meth_set_keygen(RSA_METHOD *rsa, + int (*keygen) (RSA *rsa, int bits, BIGNUM *e, + BN_GENCB *cb)); + +=head1 DESCRIPTION + +The B<RSA_METHOD> type is a structure used for the provision of custom +RSA implementations. It provides a set of of functions used by OpenSSL +for the implementation of the various RSA capabilities. See the L<rsa> +page for more information. + +RSA_meth_new() creates a new B<RSA_METHOD> structure. It should be +given a unique B<name> and a set of B<flags>. The B<name> should be a +NULL terminated string, which will be duplicated and stored in the +B<RSA_METHOD> object. It is the callers responsibility to free the +original string. The flags will be used during the construction of a +new B<RSA> object based on this B<RSA_METHOD>. Any new B<RSA> object +will have those flags set by default. + +RSA_meth_dup() creates a duplicate copy of the B<RSA_METHOD> object +passed as a parameter. This might be useful for creating a new +B<RSA_METHOD> based on an existing one, but with some differences. + +RSA_meth_free() destroys an B<RSA_METHOD> structure and frees up any +memory associated with it. + +RSA_meth_get0_name() will return a pointer to the name of this +RSA_METHOD. This is a pointer to the internal name string and so +should not be freed by the caller. RSA_meth_set1_name() sets the name +of the RSA_METHOD to B<name>. The string is duplicated and the copy is +stored in the RSA_METHOD structure, so the caller remains responsible +for freeing the memory associated with the name. + +RSA_meth_get_flags() returns the current value of the flags associated +with this RSA_METHOD. RSA_meth_set_flags() provides the ability to set +these flags. + +The functions RSA_meth_get0_app_data() and RSA_meth_set0_app_data() +provide the ability to associate implementation specific data with the +RSA_METHOD. It is the application's responsibility to free this data +before the RSA_METHOD is freed via a call to RSA_meth_free(). + +RSA_meth_get_sign() and RSA_meth_set_sign() get and set the function +used for creating an RSA signature respectively. This function will be +called in response to the application calling RSA_sign(). The +parameters for the function have the same meaning as for RSA_sign(). + +RSA_meth_get_verify() and RSA_meth_set_verify() get and set the +function used for verifying an RSA signature respectively. This +function will be called in response to the application calling +RSA_verify(). The parameters for the function have the same meaning as +for RSA_verify(). + +RSA_meth_get_mod_exp() and RSA_meth_set_mod_exp() get and set the +function used for CRT computations. + +RSA_meth_get_bn_mod_exp() and RSA_meth_set_bn_mod_exp() get and set +the function used for CRT computations, specifically the following +value: + + r = a ^ p mod m + +Both the mod_exp() and bn_mod_exp() functions are called by the +default OpenSSL method during encryption, decryption, signing and +verification. + +RSA_meth_get_init() and RSA_meth_set_init() get and set the function +used for creating a new RSA instance respectively. This function will +be called in response to the application calling RSA_new() (if the +current default RSA_METHOD is this one) or RSA_new_method(). The +RSA_new() and RSA_new_method() functions will allocate the memory for +the new RSA object, and a pointer to this newly allocated structure +will be passed as a parameter to the function. This function may be +NULL. + +RSA_meth_get_finish() and RSA_meth_set_finish() get and set the +function used for destroying an instance of an RSA object respectively. +This function will be called in response to the application calling +RSA_free(). A pointer to the RSA to be destroyed is passed as a +parameter. The destroy function should be used for RSA implementation +specific clean up. The memory for the RSA itself should not be freed +by this function. This function may be NULL. + +RSA_meth_get_keygen() and RSA_meth_set_keygen() get and set the +function used for generating a new RSA key pair respectively. This +function will be called in response to the application calling +RSA_generate_key(). The parameter for the function has the same +meaning as for RSA_generate_key(). + +RSA_meth_get_pub_enc(), RSA_meth_set_pub_enc(), +RSA_meth_get_pub_dec(), RSA_meth_set_pub_dec(), +RSA_meth_get_priv_enc(), RSA_meth_set_priv_enc(), +RSA_meth_get_priv_dec(), RSA_meth_set_priv_dec() get and set the +functions used for public and private key encryption and decryption. +These functions will be called in response to the application calling +RSA_public_encrypt(), RSA_private_decrypt(), RSA_private_encrypt() and +RSA_public_decrypt() and take the same parameters as those. + + +=head1 RETURN VALUES + +RSA_meth_new() and RSA_meth_dup() return the newly allocated +RSA_METHOD object or NULL on failure. + +RSA_meth_get0_name() and RSA_meth_get_flags() return the name and +flags associated with the RSA_METHOD respectively. + +All other RSA_meth_get_*() functions return the appropriate function +pointer that has been set in the RSA_METHOD, or NULL if no such +pointer has yet been set. + +RSA_meth_set1_name and all RSA_meth_set_*() functions return 1 on +success or 0 on failure. + +=head1 SEE ALSO + +L<RSA_new(3)>, L<RSA_generate_key(3)>, L<RSA_sign(3)>, +L<RSA_set_method(3)>, L<RSA_size(3)>, L<RSA_get0_key(3)> + +=head1 HISTORY + +The functions described here were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/RSA_new.pod b/deps/openssl/openssl/doc/crypto/RSA_new.pod index 3d15b92824..3317920741 100644 --- a/deps/openssl/openssl/doc/crypto/RSA_new.pod +++ b/deps/openssl/openssl/doc/crypto/RSA_new.pod @@ -19,23 +19,29 @@ calling RSA_new_method(NULL). RSA_free() frees the B<RSA> structure and its components. The key is erased before the memory is returned to the system. +If B<rsa> is NULL nothing is done. =head1 RETURN VALUES If the allocation fails, RSA_new() returns B<NULL> and sets an error -code that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. Otherwise it returns +code that can be obtained by L<ERR_get_error(3)>. Otherwise it returns a pointer to the newly allocated structure. RSA_free() returns no value. =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<rsa(3)|rsa(3)>, -L<RSA_generate_key(3)|RSA_generate_key(3)>, -L<RSA_new_method(3)|RSA_new_method(3)> +L<ERR_get_error(3)>, +L<RSA_generate_key(3)>, +L<RSA_new_method(3)> -=head1 HISTORY +=head1 COPYRIGHT -RSA_new() and RSA_free() are available in all versions of SSLeay and OpenSSL. +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/RSA_padding_add_PKCS1_type_1.pod b/deps/openssl/openssl/doc/crypto/RSA_padding_add_PKCS1_type_1.pod index f20f815d47..5b53eb9e95 100644 --- a/deps/openssl/openssl/doc/crypto/RSA_padding_add_PKCS1_type_1.pod +++ b/deps/openssl/openssl/doc/crypto/RSA_padding_add_PKCS1_type_1.pod @@ -102,7 +102,7 @@ of length B<pl>. B<p> may be B<NULL> if B<pl> is 0. The RSA_padding_add_xxx() functions return 1 on success, 0 on error. The RSA_padding_check_xxx() functions return the length of the recovered data, -1 on error. Error codes can be obtained by calling -L<ERR_get_error(3)|ERR_get_error(3)>. +L<ERR_get_error(3)>. =head1 WARNING @@ -113,19 +113,17 @@ v1.5 padding design. Prefer PKCS1_OAEP padding. =head1 SEE ALSO -L<RSA_public_encrypt(3)|RSA_public_encrypt(3)>, -L<RSA_private_decrypt(3)|RSA_private_decrypt(3)>, -L<RSA_sign(3)|RSA_sign(3)>, L<RSA_verify(3)|RSA_verify(3)> +L<RSA_public_encrypt(3)>, +L<RSA_private_decrypt(3)>, +L<RSA_sign(3)>, L<RSA_verify(3)> -=head1 HISTORY +=head1 COPYRIGHT -RSA_padding_add_PKCS1_type_1(), RSA_padding_check_PKCS1_type_1(), -RSA_padding_add_PKCS1_type_2(), RSA_padding_check_PKCS1_type_2(), -RSA_padding_add_SSLv23(), RSA_padding_check_SSLv23(), -RSA_padding_add_none() and RSA_padding_check_none() appeared in -SSLeay 0.9.0. +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. -RSA_padding_add_PKCS1_OAEP() and RSA_padding_check_PKCS1_OAEP() were -added in OpenSSL 0.9.2b. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/RSA_print.pod b/deps/openssl/openssl/doc/crypto/RSA_print.pod index c971e91f4d..1367478f93 100644 --- a/deps/openssl/openssl/doc/crypto/RSA_print.pod +++ b/deps/openssl/openssl/doc/crypto/RSA_print.pod @@ -38,12 +38,15 @@ These functions return 1 on success, 0 on error. =head1 SEE ALSO -L<dh(3)|dh(3)>, L<dsa(3)|dsa(3)>, L<rsa(3)|rsa(3)>, L<BN_bn2bin(3)|BN_bn2bin(3)> +L<BN_bn2bin(3)> -=head1 HISTORY +=head1 COPYRIGHT -RSA_print(), RSA_print_fp(), DSA_print(), DSA_print_fp(), DH_print(), -DH_print_fp() are available in all versions of SSLeay and OpenSSL. -DSAparams_print() and DSAparams_print_fp() were added in SSLeay 0.8. +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/RSA_private_encrypt.pod b/deps/openssl/openssl/doc/crypto/RSA_private_encrypt.pod index 3e1f895c5a..1eb7a0adbd 100644 --- a/deps/openssl/openssl/doc/crypto/RSA_private_encrypt.pod +++ b/deps/openssl/openssl/doc/crypto/RSA_private_encrypt.pod @@ -31,7 +31,7 @@ B<padding> denotes one of the following modes: PKCS #1 v1.5 padding. This function does not handle the B<algorithmIdentifier> specified in PKCS #1. When generating or -verifying PKCS #1 signatures, L<RSA_sign(3)|RSA_sign(3)> and L<RSA_verify(3)|RSA_verify(3)> should be +verifying PKCS #1 signatures, L<RSA_sign(3)> and L<RSA_verify(3)> should be used. =item RSA_NO_PADDING @@ -55,16 +55,20 @@ RSA_size(rsa)). RSA_public_decrypt() returns the size of the recovered message digest. On error, -1 is returned; the error codes can be -obtained by L<ERR_get_error(3)|ERR_get_error(3)>. +obtained by L<ERR_get_error(3)>. =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<rsa(3)|rsa(3)>, -L<RSA_sign(3)|RSA_sign(3)>, L<RSA_verify(3)|RSA_verify(3)> +L<ERR_get_error(3)>, +L<RSA_sign(3)>, L<RSA_verify(3)> -=head1 HISTORY +=head1 COPYRIGHT -The B<padding> argument was added in SSLeay 0.8. RSA_NO_PADDING is -available since SSLeay 0.9.0. +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/RSA_public_encrypt.pod b/deps/openssl/openssl/doc/crypto/RSA_public_encrypt.pod index 4d7c1f2cac..b1dd50d752 100644 --- a/deps/openssl/openssl/doc/crypto/RSA_public_encrypt.pod +++ b/deps/openssl/openssl/doc/crypto/RSA_public_encrypt.pod @@ -65,7 +65,7 @@ RSA_size(B<rsa>)). RSA_private_decrypt() returns the size of the recovered plaintext. On error, -1 is returned; the error codes can be -obtained by L<ERR_get_error(3)|ERR_get_error(3)>. +obtained by L<ERR_get_error(3)>. =head1 WARNING @@ -80,12 +80,16 @@ SSL, PKCS #1 v2.0 =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, -L<RSA_size(3)|RSA_size(3)> +L<ERR_get_error(3)>, L<rand(3)>, +L<RSA_size(3)> -=head1 HISTORY +=head1 COPYRIGHT -The B<padding> argument was added in SSLeay 0.8. RSA_NO_PADDING is -available since SSLeay 0.9.0, OAEP was added in OpenSSL 0.9.2b. +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/RSA_set_method.pod b/deps/openssl/openssl/doc/crypto/RSA_set_method.pod index 0ef0781186..668ad7a16b 100644 --- a/deps/openssl/openssl/doc/crypto/RSA_set_method.pod +++ b/deps/openssl/openssl/doc/crypto/RSA_set_method.pod @@ -3,7 +3,7 @@ =head1 NAME RSA_set_default_method, RSA_get_default_method, RSA_set_method, -RSA_get_method, RSA_PKCS1_SSLeay, RSA_null_method, RSA_flags, +RSA_get_method, RSA_PKCS1_OpenSSL, RSA_flags, RSA_new_method - select RSA method =head1 SYNOPSIS @@ -18,13 +18,11 @@ RSA_new_method - select RSA method RSA_METHOD *RSA_get_method(const RSA *rsa); - RSA_METHOD *RSA_PKCS1_SSLeay(void); - - RSA_METHOD *RSA_null_method(void); + RSA_METHOD *RSA_PKCS1_OpenSSL(void); int RSA_flags(const RSA *rsa); - RSA *RSA_new_method(RSA_METHOD *method); + RSA *RSA_new_method(ENGINE *engine); =head1 DESCRIPTION @@ -35,15 +33,18 @@ important information about how these RSA API functions are affected by the use of B<ENGINE> API calls. Initially, the default RSA_METHOD is the OpenSSL internal implementation, -as returned by RSA_PKCS1_SSLeay(). +as returned by RSA_PKCS1_OpenSSL(). RSA_set_default_method() makes B<meth> the default method for all RSA -structures created later. B<NB>: This is true only whilst no ENGINE has +structures created later. +B<NB>: This is true only whilst no ENGINE has been set as a default for RSA, so this function is no longer recommended. +This function is not thread-safe and should not be called at the same time +as other OpenSSL functions. RSA_get_default_method() returns a pointer to the current default RSA_METHOD. However, the meaningfulness of this result is dependent on -whether the ENGINE API is being used, so this function is no longer +whether the ENGINE API is being used, so this function is no longer recommended. RSA_set_method() selects B<meth> to perform all operations using the key @@ -80,69 +81,62 @@ the default method is used. typedef struct rsa_meth_st { /* name of the implementation */ - const char *name; + const char *name; /* encrypt */ - int (*rsa_pub_enc)(int flen, unsigned char *from, + int (*rsa_pub_enc)(int flen, unsigned char *from, unsigned char *to, RSA *rsa, int padding); /* verify arbitrary data */ - int (*rsa_pub_dec)(int flen, unsigned char *from, + int (*rsa_pub_dec)(int flen, unsigned char *from, unsigned char *to, RSA *rsa, int padding); /* sign arbitrary data */ - int (*rsa_priv_enc)(int flen, unsigned char *from, + int (*rsa_priv_enc)(int flen, unsigned char *from, unsigned char *to, RSA *rsa, int padding); /* decrypt */ - int (*rsa_priv_dec)(int flen, unsigned char *from, + int (*rsa_priv_dec)(int flen, unsigned char *from, unsigned char *to, RSA *rsa, int padding); /* compute r0 = r0 ^ I mod rsa->n (May be NULL for some implementations) */ - int (*rsa_mod_exp)(BIGNUM *r0, BIGNUM *I, RSA *rsa); + int (*rsa_mod_exp)(BIGNUM *r0, BIGNUM *I, RSA *rsa); /* compute r = a ^ p mod m (May be NULL for some implementations) */ - int (*bn_mod_exp)(BIGNUM *r, BIGNUM *a, const BIGNUM *p, + int (*bn_mod_exp)(BIGNUM *r, BIGNUM *a, const BIGNUM *p, const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx); /* called at RSA_new */ - int (*init)(RSA *rsa); + int (*init)(RSA *rsa); /* called at RSA_free */ - int (*finish)(RSA *rsa); + int (*finish)(RSA *rsa); /* RSA_FLAG_EXT_PKEY - rsa_mod_exp is called for private key * operations, even if p,q,dmp1,dmq1,iqmp * are NULL - * RSA_FLAG_SIGN_VER - enable rsa_sign and rsa_verify * RSA_METHOD_FLAG_NO_CHECK - don't check pub/private match */ - int flags; + int flags; - char *app_data; /* ?? */ + char *app_data; /* ?? */ - /* sign. For backward compatibility, this is used only - * if (flags & RSA_FLAG_SIGN_VER) - */ - int (*rsa_sign)(int type, - const unsigned char *m, unsigned int m_length, - unsigned char *sigret, unsigned int *siglen, const RSA *rsa); - /* verify. For backward compatibility, this is used only - * if (flags & RSA_FLAG_SIGN_VER) - */ - int (*rsa_verify)(int dtype, - const unsigned char *m, unsigned int m_length, - const unsigned char *sigbuf, unsigned int siglen, - const RSA *rsa); + int (*rsa_sign)(int type, + const unsigned char *m, unsigned int m_length, + unsigned char *sigret, unsigned int *siglen, const RSA *rsa); + int (*rsa_verify)(int dtype, + const unsigned char *m, unsigned int m_length, + const unsigned char *sigbuf, unsigned int siglen, + const RSA *rsa); /* keygen. If NULL builtin RSA key generation will be used */ - int (*rsa_keygen)(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb); + int (*rsa_keygen)(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb); } RSA_METHOD; =head1 RETURN VALUES -RSA_PKCS1_SSLeay(), RSA_PKCS1_null_method(), RSA_get_default_method() +RSA_PKCS1_OpenSSL(), RSA_PKCS1_null_method(), RSA_get_default_method() and RSA_get_method() return pointers to the respective RSA_METHODs. RSA_set_default_method() returns no value. @@ -156,19 +150,9 @@ ENGINE). For this reason, the return type may be replaced with a B<void> declaration in a future release. RSA_new_method() returns NULL and sets an error code that can be obtained -by L<ERR_get_error(3)|ERR_get_error(3)> if the allocation fails. Otherwise +by L<ERR_get_error(3)> if the allocation fails. Otherwise it returns a pointer to the newly allocated structure. -=head1 NOTES - -As of version 0.9.7, RSA_METHOD implementations are grouped together with -other algorithmic APIs (eg. DSA_METHOD, EVP_CIPHER, etc) into B<ENGINE> -modules. If a default ENGINE is specified for RSA functionality using an -ENGINE API function, that will override any RSA defaults set using the RSA -API (ie. RSA_set_default_method()). For this reason, the ENGINE API is the -recommended way to control default implementations for use in RSA and other -cryptographic algorithms. - =head1 BUGS The behaviour of RSA_flags() is a mis-feature that is left as-is for now @@ -183,24 +167,20 @@ not currently exist). =head1 SEE ALSO -L<rsa(3)|rsa(3)>, L<RSA_new(3)|RSA_new(3)> +L<RSA_new(3)> =head1 HISTORY -RSA_new_method() and RSA_set_default_method() appeared in SSLeay 0.8. -RSA_get_default_method(), RSA_set_method() and RSA_get_method() as -well as the rsa_sign and rsa_verify components of RSA_METHOD were -added in OpenSSL 0.9.4. - -RSA_set_default_openssl_method() and RSA_get_default_openssl_method() -replaced RSA_set_default_method() and RSA_get_default_method() -respectively, and RSA_set_method() and RSA_new_method() were altered to use -B<ENGINE>s rather than B<RSA_METHOD>s during development of the engine -version of OpenSSL 0.9.6. For 0.9.7, the handling of defaults in the ENGINE -API was restructured so that this change was reversed, and behaviour of the -other functions resembled more closely the previous behaviour. The -behaviour of defaults in the ENGINE API now transparently overrides the -behaviour of defaults in the RSA API without requiring changing these -function prototypes. +The RSA_null_method(), which was a partial attempt to avoid patent issues, +was replaced to always return NULL in OpenSSL 1.1.0f. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/RSA_sign.pod b/deps/openssl/openssl/doc/crypto/RSA_sign.pod index fc16b1f4f8..fbb38d811c 100644 --- a/deps/openssl/openssl/doc/crypto/RSA_sign.pod +++ b/deps/openssl/openssl/doc/crypto/RSA_sign.pod @@ -17,17 +17,17 @@ RSA_sign, RSA_verify - RSA signatures =head1 DESCRIPTION RSA_sign() signs the message digest B<m> of size B<m_len> using the -private key B<rsa> as specified in PKCS #1 v2.0. It stores the -signature in B<sigret> and the signature size in B<siglen>. B<sigret> -must point to RSA_size(B<rsa>) bytes of memory. +private key B<rsa> using RSASSA-PKCS1-v1_5 as specified in RFC 3447. It +stores the signature in B<sigret> and the signature size in B<siglen>. +B<sigret> must point to RSA_size(B<rsa>) bytes of memory. Note that PKCS #1 adds meta-data, placing limits on the size of the key that can be used. -See L<RSA_private_encrypt(3)|RSA_private_encrypt(3)> for lower-level +See L<RSA_private_encrypt(3)> for lower-level operations. B<type> denotes the message digest algorithm that was used to generate -B<m>. It usually is one of B<NID_sha1>, B<NID_ripemd160> and B<NID_md5>; -see L<objects(3)|objects(3)> for details. If B<type> is B<NID_md5_sha1>, +B<m>. +If B<type> is B<NID_md5_sha1>, an SSL signature (MD5 and SHA1 message digests with PKCS #1 padding and no algorithm identifier) is created. @@ -38,15 +38,10 @@ B<rsa> is the signer's public key. =head1 RETURN VALUES -RSA_sign() returns 1 on success, 0 otherwise. RSA_verify() returns 1 -on successful verification, 0 otherwise. +RSA_sign() returns 1 on success. +RSA_verify() returns 1 on successful verification. -The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. - -=head1 BUGS - -Certain signatures with an improper algorithm identifier are accepted -for compatibility with SSLeay 0.4.5 :-) +The error codes can be obtained by L<ERR_get_error(3)>. =head1 CONFORMING TO @@ -54,13 +49,17 @@ SSL, PKCS #1 v2.0 =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<objects(3)|objects(3)>, -L<rsa(3)|rsa(3)>, L<RSA_private_encrypt(3)|RSA_private_encrypt(3)>, -L<RSA_public_decrypt(3)|RSA_public_decrypt(3)> +L<ERR_get_error(3)>, +L<RSA_private_encrypt(3)>, +L<RSA_public_decrypt(3)> + +=head1 COPYRIGHT -=head1 HISTORY +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. -RSA_sign() and RSA_verify() are available in all versions of SSLeay -and OpenSSL. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod b/deps/openssl/openssl/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod index e70380bbfc..16303c9f90 100644 --- a/deps/openssl/openssl/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod +++ b/deps/openssl/openssl/doc/crypto/RSA_sign_ASN1_OCTET_STRING.pod @@ -39,7 +39,7 @@ RSA_sign_ASN1_OCTET_STRING() returns 1 on success, 0 otherwise. RSA_verify_ASN1_OCTET_STRING() returns 1 on successful verification, 0 otherwise. -The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. +The error codes can be obtained by L<ERR_get_error(3)>. =head1 BUGS @@ -47,13 +47,17 @@ These functions serve no recognizable purpose. =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<objects(3)|objects(3)>, -L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, L<RSA_sign(3)|RSA_sign(3)>, -L<RSA_verify(3)|RSA_verify(3)> +L<ERR_get_error(3)>, +L<rand(3)>, L<RSA_sign(3)>, +L<RSA_verify(3)> -=head1 HISTORY +=head1 COPYRIGHT -RSA_sign_ASN1_OCTET_STRING() and RSA_verify_ASN1_OCTET_STRING() were -added in SSLeay 0.8. +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/RSA_size.pod b/deps/openssl/openssl/doc/crypto/RSA_size.pod index 5b7f835f95..eb6e481361 100644 --- a/deps/openssl/openssl/doc/crypto/RSA_size.pod +++ b/deps/openssl/openssl/doc/crypto/RSA_size.pod @@ -2,32 +2,45 @@ =head1 NAME -RSA_size - get RSA modulus size +RSA_size, RSA_bits - get RSA modulus size =head1 SYNOPSIS - #include <openssl/rsa.h> +#include <openssl/rsa.h> - int RSA_size(const RSA *rsa); +int RSA_size(const RSA *rsa); + +int RSA_bits(const RSA *rsa); =head1 DESCRIPTION -This function returns the RSA modulus size in bytes. It can be used to +RSA_size() returns the RSA modulus size in bytes. It can be used to determine how much memory must be allocated for an RSA encrypted value. -B<rsa-E<gt>n> must not be B<NULL>. +RSA_bits() returns the number of significant bits. + +B<rsa> and B<rsa-E<gt>n> must not be B<NULL>. =head1 RETURN VALUE -The size in bytes. +The size. =head1 SEE ALSO -L<rsa(3)|rsa(3)> +L<BN_num_bits(3)> =head1 HISTORY -RSA_size() is available in all versions of SSLeay and OpenSSL. +RSA_bits() was added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/SCT_new.pod b/deps/openssl/openssl/doc/crypto/SCT_new.pod new file mode 100644 index 0000000000..fb395a51a7 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/SCT_new.pod @@ -0,0 +1,194 @@ +=pod + +=head1 NAME + +SCT_new, SCT_new_from_base64, SCT_free, SCT_LIST_free, +SCT_get_version, SCT_set_version, +SCT_get_log_entry_type, SCT_set_log_entry_type, +SCT_get0_log_id, SCT_set0_log_id, SCT_set1_log_id, +SCT_get_timestamp, SCT_set_timestamp, +SCT_get_signature_nid, SCT_set_signature_nid, +SCT_get0_signature, SCT_set0_signature, SCT_set1_signature, +SCT_get0_extensions, SCT_set0_extensions, SCT_set1_extensions, +SCT_get_source, SCT_set_source +- A Certificate Transparency Signed Certificate Timestamp + +=head1 SYNOPSIS + + #include <openssl/ct.h> + + typedef enum { + CT_LOG_ENTRY_TYPE_NOT_SET = -1, + CT_LOG_ENTRY_TYPE_X509 = 0, + CT_LOG_ENTRY_TYPE_PRECERT = 1 + } ct_log_entry_type_t; + + typedef enum { + SCT_VERSION_NOT_SET = -1, + SCT_VERSION_V1 = 0 + } sct_version_t; + + typedef enum { + SCT_SOURCE_UNKNOWN, + SCT_SOURCE_TLS_EXTENSION, + SCT_SOURCE_X509V3_EXTENSION, + SCT_SOURCE_OCSP_STAPLED_RESPONSE + } sct_source_t; + + SCT *SCT_new(void); + SCT *SCT_new_from_base64(unsigned char version, + const char *logid_base64, + ct_log_entry_type_t entry_type, + uint64_t timestamp, + const char *extensions_base64, + const char *signature_base64); + + void SCT_free(SCT *sct); + void SCT_LIST_free(STACK_OF(SCT) *a); + + sct_version_t SCT_get_version(const SCT *sct); + int SCT_set_version(SCT *sct, sct_version_t version); + + ct_log_entry_type_t SCT_get_log_entry_type(const SCT *sct); + int SCT_set_log_entry_type(SCT *sct, ct_log_entry_type_t entry_type); + + size_t SCT_get0_log_id(const SCT *sct, unsigned char **log_id); + int SCT_set0_log_id(SCT *sct, unsigned char *log_id, size_t log_id_len); + int SCT_set1_log_id(SCT *sct, const unsigned char *log_id, size_t log_id_len); + + uint64_t SCT_get_timestamp(const SCT *sct); + void SCT_set_timestamp(SCT *sct, uint64_t timestamp); + + int SCT_get_signature_nid(const SCT *sct); + int SCT_set_signature_nid(SCT *sct, int nid); + + size_t SCT_get0_signature(const SCT *sct, unsigned char **sig); + void SCT_set0_signature(SCT *sct, unsigned char *sig, size_t sig_len); + int SCT_set1_signature(SCT *sct, const unsigned char *sig, size_t sig_len); + + size_t SCT_get0_extensions(const SCT *sct, unsigned char **ext); + void SCT_set0_extensions(SCT *sct, unsigned char *ext, size_t ext_len); + int SCT_set1_extensions(SCT *sct, const unsigned char *ext, size_t ext_len); + + sct_source_t SCT_get_source(const SCT *sct); + int SCT_set_source(SCT *sct, sct_source_t source); + +=head1 DESCRIPTION + +Signed Certificate Timestamps (SCTs) are defined by RFC 6962, Section 3.2. +They constitute a promise by a Certificate Transparency (CT) log to publicly +record a certificate. By cryptographically verifying that a log did indeed issue +an SCT, some confidence can be gained that the certificate is publicly known. + +An internal representation of an SCT can be created in one of two ways. +The first option is to create a blank SCT, using SCT_new(), and then populate +it using: + +=over 4 + +=item * SCT_set_version() to set the SCT version. + +Only SCT_VERSION_V1 is currently supported. + +=item * SCT_set_log_entry_type() to set the type of certificate the SCT was issued for: + +B<CT_LOG_ENTRY_TYPE_X509> for a normal certificate. +B<CT_LOG_ENTRY_TYPE_PRECERT> for a pre-certificate. + +=item * SCT_set0_log_id() or SCT_set1_log_id() to set the LogID of the CT log that the SCT came from. + +The former takes ownership, whereas the latter makes a copy. +See RFC 6962, Section 3.2 for the definition of LogID. + +=item * SCT_set_timestamp() to set the time the SCT was issued (epoch time in milliseconds). + +=item * SCT_set_signature_nid() to set the NID of the signature. + +=item * SCT_set0_signature() or SCT_set1_signature() to set the raw signature value. + +The former takes ownership, whereas the latter makes a copy. + +=item * SCT_set0_extensions() or B<SCT_set1_extensions> to provide SCT extensions. + +The former takes ownership, whereas the latter makes a copy. + +=back + +Alternatively, the SCT can be pre-populated from the following data using +SCT_new_from_base64(): + +=over 4 + +=item * The SCT version (only SCT_VERSION_V1 is currently supported). + +=item * The LogID (see RFC 6962, Section 3.2), base64 encoded. + +=item * The type of certificate the SCT was issued for: + +B<CT_LOG_ENTRY_TYPE_X509> for a normal certificate. +B<CT_LOG_ENTRY_TYPE_PRECERT> for a pre-certificate. + +=item * The time that the SCT was issued (epoch time in milliseconds). + +=item * The SCT extensions, base64 encoded. + +=item * The SCT signature, base64 encoded. + +=back + +SCT_set_source() can be used to record where the SCT was found +(TLS extension, X.509 certificate extension or OCSP response). This is not +required for verifying the SCT. + +=head1 NOTES + +Some of the setters return int, instead of void. These will all return 1 on +success, 0 on failure. They will not make changes on failure. + +All of the setters will reset the validation status of the SCT to +SCT_VALIDATION_STATUS_NOT_SET (see L<SCT_validate(3)>). + +SCT_set_source() will call SCT_set_log_entry_type() if the type of +certificate the SCT was issued for can be inferred from where the SCT was found. +For example, an SCT found in an X.509 extension must have been issued for a pre- +certificate. + +SCT_set_source() will not refuse unknown values. + +=head1 RETURN VALUES + +SCT_set_version() returns 1 if the specified version is supported, 0 otherwise. + +SCT_set_log_entry_type() returns 1 if the specified log entry type is supported, 0 otherwise. + +SCT_set0_log_id() and B<SCT_set1_log_id> return 1 if the specified LogID is a +valid SHA-256 hash, 0 otherwise. Additionally, B<SCT_set1_log_id> returns 0 if +malloc fails. + +B<SCT_set_signature_nid> returns 1 if the specified NID is supported, 0 otherwise. + +B<SCT_set1_extensions> and B<SCT_set1_signature> return 1 if the supplied buffer +is copied successfully, 0 otherwise (i.e. if malloc fails). + +B<SCT_set_source> returns 1 on success, 0 otherwise. + +=head1 SEE ALSO + +L<ct(7)>, +L<SCT_validate(3)>, +L<OBJ_nid2obj(3)> + +=head1 HISTORY + +These functions were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/SCT_print.pod b/deps/openssl/openssl/doc/crypto/SCT_print.pod new file mode 100644 index 0000000000..88ad43ecdc --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/SCT_print.pod @@ -0,0 +1,52 @@ +=pod + +=head1 NAME + +SCT_print, SCT_LIST_print, SCT_validation_status_string - +Prints Signed Certificate Timestamps in a human-readable way + +=head1 SYNOPSIS + + #include <openssl/ct.h> + + void SCT_print(const SCT *sct, BIO *out, int indent, const CTLOG_STORE *logs); + void SCT_LIST_print(const STACK_OF(SCT) *sct_list, BIO *out, int indent, + const char *separator, const CTLOG_STORE *logs); + const char *SCT_validation_status_string(const SCT *sct); + +=head1 DESCRIPTION + +SCT_print() prints a single Signed Certificate Timestamp (SCT) to a L<bio> in +a human-readable format. SCT_LIST_print() prints an entire list of SCTs in a +similar way. A separator can be specified to delimit each SCT in the output. + +The output can be indented by a specified number of spaces. If a B<CTLOG_STORE> +is provided, it will be used to print the description of the CT log that issued +each SCT (if that log is in the CTLOG_STORE). Alternatively, NULL can be passed +as the CTLOG_STORE parameter to disable this feature. + +SCT_validation_status_string() will return the validation status of an SCT as +a human-readable string. Call SCT_validate() or SCT_LIST_validate() +beforehand in order to set the validation status of an SCT first. + +=head1 SEE ALSO + +L<ct(3)>, +L<bio(3)>, +L<CTLOG_STORE_new(3)>, +L<SCT_validate(3)> + +=head1 HISTORY + +These functions were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/SCT_validate.pod b/deps/openssl/openssl/doc/crypto/SCT_validate.pod new file mode 100644 index 0000000000..3c03e97287 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/SCT_validate.pod @@ -0,0 +1,98 @@ +=pod + +=head1 NAME + +SCT_validate, SCT_LIST_validate, SCT_get_validation_status - +checks Signed Certificate Timestamps (SCTs) are valid + +=head1 SYNOPSIS + + #include <openssl/ct.h> + + typedef enum { + SCT_VALIDATION_STATUS_NOT_SET, + SCT_VALIDATION_STATUS_UNKNOWN_LOG, + SCT_VALIDATION_STATUS_VALID, + SCT_VALIDATION_STATUS_INVALID, + SCT_VALIDATION_STATUS_UNVERIFIED, + SCT_VALIDATION_STATUS_UNKNOWN_VERSION + } sct_validation_status_t; + + int SCT_validate(SCT *sct, const CT_POLICY_EVAL_CTX *ctx); + int SCT_LIST_validate(const STACK_OF(SCT) *scts, CT_POLICY_EVAL_CTX *ctx); + sct_validation_status_t SCT_get_validation_status(const SCT *sct); + +=head1 DESCRIPTION + +SCT_validate() will check that an SCT is valid and verify its signature. +SCT_LIST_validate() performs the same checks on an entire stack of SCTs. +The result of the validation checks can be obtained by passing the SCT to +SCT_get_validation_status(). + +A CT_POLICY_EVAL_CTX must be provided that specifies: + +=over 4 + +=item * The certificate the SCT was issued for. + +Failure to provide the certificate will result in the validation status being +SCT_VALIDATION_STATUS_UNVERIFIED. + +=item * The issuer of that certificate. + +This is only required if the SCT was issued for a pre-certificate +(see RFC 6962). If it is required but not provided, the validation status will +be SCT_VALIDATION_STATUS_UNVERIFIED. + +=item * A CTLOG_STORE that contains the CT log that issued this SCT. + +If the SCT was issued by a log that is not in this CTLOG_STORE, the validation +status will be SCT_VALIDATION_STATUS_UNKNOWN_LOG. + +=back + +If the SCT is of an unsupported version (only v1 is currently supported), the +validation status will be SCT_VALIDATION_STATUS_UNKNOWN_VERSION. + +If the SCT's signature is incorrect, its timestamp is in the future (relative to +the time in CT_POLICY_EVAL_CTX), or if it is otherwise invalid, the validation +status will be SCT_VALIDATION_STATUS_INVALID. + +If all checks pass, the validation status will be SCT_VALIDATION_STATUS_VALID. + +=head1 NOTES + +A return value of 0 from SCT_LIST_validate() should not be interpreted as a +failure. At a minimum, only one valid SCT may provide sufficient confidence +that a certificate has been publicly logged. + +=head1 RETURN VALUES + +SCT_validate() returns a negative integer if an internal error occurs, 0 if the +SCT fails validation, or 1 if the SCT passes validation. + +SCT_LIST_validate() returns a negative integer if an internal error occurs, 0 +if any of SCTs fails validation, or 1 if they all pass validation. + +SCT_get_validation_status() returns the validation status of the SCT. +If SCT_validate() or SCT_LIST_validate() have not been passed that SCT, the +returned value will be SCT_VALIDATION_STATUS_NOT_SET. + +=head1 SEE ALSO + +L<ct(7)> + +=head1 HISTORY + +These functions were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/sha.pod b/deps/openssl/openssl/doc/crypto/SHA256_Init.pod index 0c9dbf2f3d..f3565bb2f4 100644 --- a/deps/openssl/openssl/doc/crypto/sha.pod +++ b/deps/openssl/openssl/doc/crypto/SHA256_Init.pod @@ -44,7 +44,7 @@ SHA512_Final - Secure Hash Algorithm =head1 DESCRIPTION Applications should use the higher level functions -L<EVP_DigestInit(3)|EVP_DigestInit(3)> etc. instead of calling the hash +L<EVP_DigestInit(3)> etc. instead of calling the hash functions directly. SHA-1 (Secure Hash Algorithm) is a cryptographic hash function with a @@ -81,7 +81,7 @@ used only when backward compatibility is required. =head1 RETURN VALUES SHA1(), SHA224(), SHA256(), SHA384() and SHA512() return a pointer to the hash -value. +value. SHA1_Init(), SHA1_Update() and SHA1_Final() and equivalent SHA224, SHA256, SHA384 and SHA512 functions return 1 for success, 0 otherwise. @@ -94,11 +94,15 @@ ANSI X9.30 =head1 SEE ALSO -L<ripemd(3)|ripemd(3)>, L<hmac(3)|hmac(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)> +L<EVP_DigestInit(3)> -=head1 HISTORY +=head1 COPYRIGHT -SHA1(), SHA1_Init(), SHA1_Update() and SHA1_Final() are available in all -versions of SSLeay and OpenSSL. +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/SMIME_read_CMS.pod b/deps/openssl/openssl/doc/crypto/SMIME_read_CMS.pod index acc5524c14..efde0bda54 100644 --- a/deps/openssl/openssl/doc/crypto/SMIME_read_CMS.pod +++ b/deps/openssl/openssl/doc/crypto/SMIME_read_CMS.pod @@ -2,7 +2,7 @@ =head1 NAME - SMIME_read_CMS - parse S/MIME message. +SMIME_read_CMS - parse S/MIME message =head1 SYNOPSIS @@ -58,13 +58,18 @@ if an error occurred. The error can be obtained from ERR_get_error(3). =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_type(3)|CMS_type(3)> -L<SMIME_read_CMS(3)|SMIME_read_CMS(3)>, L<CMS_sign(3)|CMS_sign(3)>, -L<CMS_verify(3)|CMS_verify(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)> -L<CMS_decrypt(3)|CMS_decrypt(3)> +L<ERR_get_error(3)>, L<CMS_type(3)> +L<SMIME_read_CMS(3)>, L<CMS_sign(3)>, +L<CMS_verify(3)>, L<CMS_encrypt(3)> +L<CMS_decrypt(3)> -=head1 HISTORY +=head1 COPYRIGHT -SMIME_read_CMS() was added to OpenSSL 0.9.8 +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/SMIME_read_PKCS7.pod b/deps/openssl/openssl/doc/crypto/SMIME_read_PKCS7.pod index 9d46715941..3eb8bbc9a0 100644 --- a/deps/openssl/openssl/doc/crypto/SMIME_read_PKCS7.pod +++ b/deps/openssl/openssl/doc/crypto/SMIME_read_PKCS7.pod @@ -2,7 +2,7 @@ =head1 NAME -SMIME_read_PKCS7 - parse S/MIME message. +SMIME_read_PKCS7 - parse S/MIME message =head1 SYNOPSIS @@ -30,7 +30,7 @@ signed. B<*bcont> can then be passed to PKCS7_verify() with the B<PKCS7_DETACHED> flag set. Otherwise the type of the returned structure can be determined -using PKCS7_type(). +using PKCS7_type_is_enveloped(), etc. To support future functionality if B<bcont> is not B<NULL> B<*bcont> should be initialized to B<NULL>. For example: @@ -61,13 +61,18 @@ is an error occurred. The error can be obtained from ERR_get_error(3). =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_type(3)|PKCS7_type(3)> -L<SMIME_read_PKCS7(3)|SMIME_read_PKCS7(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>, -L<PKCS7_verify(3)|PKCS7_verify(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)> -L<PKCS7_decrypt(3)|PKCS7_decrypt(3)> +L<ERR_get_error(3)>, +L<SMIME_read_PKCS7(3)>, L<PKCS7_sign(3)>, +L<PKCS7_verify(3)>, L<PKCS7_encrypt(3)> +L<PKCS7_decrypt(3)> -=head1 HISTORY +=head1 COPYRIGHT -SMIME_read_PKCS7() was added to OpenSSL 0.9.5 +Copyright 2002-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/SMIME_write_CMS.pod b/deps/openssl/openssl/doc/crypto/SMIME_write_CMS.pod index 04bedfb429..d58baeb746 100644 --- a/deps/openssl/openssl/doc/crypto/SMIME_write_CMS.pod +++ b/deps/openssl/openssl/doc/crypto/SMIME_write_CMS.pod @@ -2,7 +2,7 @@ =head1 NAME - SMIME_write_CMS - convert CMS structure to S/MIME format. +SMIME_write_CMS - convert CMS structure to S/MIME format =head1 SYNOPSIS @@ -53,12 +53,17 @@ SMIME_write_CMS() returns 1 for success or 0 for failure. =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>, -L<CMS_verify(3)|CMS_verify(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)> -L<CMS_decrypt(3)|CMS_decrypt(3)> +L<ERR_get_error(3)>, L<CMS_sign(3)>, +L<CMS_verify(3)>, L<CMS_encrypt(3)> +L<CMS_decrypt(3)> -=head1 HISTORY +=head1 COPYRIGHT -SMIME_write_CMS() was added to OpenSSL 0.9.8 +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/SMIME_write_PKCS7.pod b/deps/openssl/openssl/doc/crypto/SMIME_write_PKCS7.pod index ca6bd02763..b57312386e 100644 --- a/deps/openssl/openssl/doc/crypto/SMIME_write_PKCS7.pod +++ b/deps/openssl/openssl/doc/crypto/SMIME_write_PKCS7.pod @@ -2,7 +2,7 @@ =head1 NAME -SMIME_write_PKCS7 - convert PKCS#7 structure to S/MIME format. +SMIME_write_PKCS7 - convert PKCS#7 structure to S/MIME format =head1 SYNOPSIS @@ -33,14 +33,14 @@ is also set. If the B<PKCS7_STREAM> flag is set streaming is performed. This flag should only be set if B<PKCS7_STREAM> was also set in the previous call to -PKCS7_sign() or B<PKCS7_encrypt()>. +PKCS7_sign() or PKCS7_encrypt(). If cleartext signing is being used and B<PKCS7_STREAM> not set then the data must be read twice: once to compute the signature in PKCS7_sign() and once to output the S/MIME message. If streaming is performed the content is output in BER format using indefinite -length constructuted encoding except in the case of signed data with detached +length constructed encoding except in the case of signed data with detached content where the content is absent and DER format is used. =head1 BUGS @@ -54,12 +54,17 @@ SMIME_write_PKCS7() returns 1 for success or 0 for failure. =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>, -L<PKCS7_verify(3)|PKCS7_verify(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)> -L<PKCS7_decrypt(3)|PKCS7_decrypt(3)> +L<ERR_get_error(3)>, L<PKCS7_sign(3)>, +L<PKCS7_verify(3)>, L<PKCS7_encrypt(3)> +L<PKCS7_decrypt(3)> -=head1 HISTORY +=head1 COPYRIGHT -SMIME_write_PKCS7() was added to OpenSSL 0.9.5 +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/SSL_CTX_set_tlsext_use_srtp.pod b/deps/openssl/openssl/doc/crypto/SSL_CTX_set_tlsext_use_srtp.pod new file mode 100644 index 0000000000..2746d5018c --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/SSL_CTX_set_tlsext_use_srtp.pod @@ -0,0 +1,111 @@ +=pod + +=head1 NAME + +SSL_CTX_set_tlsext_use_srtp, +SSL_set_tlsext_use_srtp, +SSL_get_srtp_profiles, +SSL_get_selected_srtp_profile +- Configure and query SRTP support + +=head1 SYNOPSIS + + #include <openssl/srtp.h> + + int SSL_CTX_set_tlsext_use_srtp(SSL_CTX *ctx, const char *profiles); + int SSL_set_tlsext_use_srtp(SSL *ssl, const char *profiles); + + STACK_OF(SRTP_PROTECTION_PROFILE) *SSL_get_srtp_profiles(SSL *ssl); + SRTP_PROTECTION_PROFILE *SSL_get_selected_srtp_profile(SSL *s); + +=head1 DESCRIPTION + +SRTP is the Secure Real-Time Transport Protocol. OpenSSL implements support for +the "use_srtp" DTLS extension defined in RFC5764. This provides a mechanism for +establishing SRTP keying material, algorithms and parameters using DTLS. This +capability may be used as part of an implementation that conforms to RFC5763. +OpenSSL does not implement SRTP itself or RFC5763. Note that OpenSSL does not +support the use of SRTP Master Key Identifiers (MKIs). Also note that this +extension is only supported in DTLS. Any SRTP configuration will be ignored if a +TLS connection is attempted. + +An OpenSSL client wishing to send the "use_srtp" extension should call +SSL_CTX_set_tlsext_use_srtp() to set its use for all SSL objects subsequently +created from an SSL_CTX. Alternatively a client may call +SSL_set_tlsext_use_srtp() to set its use for an individual SSL object. The +B<profiles> parameters should point to a NUL-terminated, colon delimited list of +SRTP protection profile names. + +The currently supported protection profile names are: + +=over 4 + +=item SRTP_AES128_CM_SHA1_80 + +This corresponds to SRTP_AES128_CM_HMAC_SHA1_80 defined in RFC5764. + +=item SRTP_AES128_CM_SHA1_32 + +This corresponds to SRTP_AES128_CM_HMAC_SHA1_32 defined in RFC5764. + +=item SRTP_AEAD_AES_128_GCM + +This corresponds to the profile of the same name defined in RFC7714. + +=item SRTP_AEAD_AES_256_GCM + +This corresponds to the profile of the same name defined in RFC7714. + +=back + +Supplying an unrecognised protection profile name will result in an error. + +An OpenSSL server wishing to support the "use_srtp" extension should also call +SSL_CTX_set_tlsext_use_srtp() or SSL_set_tlsext_use_srtp() to indicate the +protection profiles that it is willing to negotiate. + +The currently configured list of protection profiles for either a client or a +server can be obtained by calling SSL_get_srtp_profiles(). This returns a stack +of SRTP_PROTECTION_PROFILE objects. The memory pointed to in the return value of +this function should not be freed by the caller. + +After a handshake has been completed the negotiated SRTP protection profile (if +any) can be obtained (on the client or the server) by calling +SSL_get_selected_srtp_profile(). This function will return NULL if no SRTP +protection profile was negotiated. The memory returned from this function should +not be freed by the caller. + +If an SRTP protection profile has been sucessfully negotiated then the SRTP +keying material (on both the client and server) should be obtained via a call to +L<SSL_export_keying_material(3)>. This call should provide a label value of +"EXTRACTOR-dtls_srtp" and a NULL context value (use_context is 0). The total +length of keying material obtained should be equal to two times the sum of the +master key length and the salt length as defined for the protection profile in +use. This provides the client write master key, the server write master key, the +client write master salt and the server write master salt in that order. + +=head1 RETURN VALUES + +SSL_CTX_set_tlsext_use_srtp() and SSL_set_tlsext_use_srtp() return 0 on success +or 1 on error. + +SSL_get_srtp_profiles() returns a stack of SRTP_PROTECTION_PROFILE objects on +success or NULL on error or if no protection profiles have been configured. + +SSL_get_selected_srtp_profile() returns a pointer to an SRTP_PROTECTION_PROFILE +object if one has been negotiated or NULL otherwise. + +=head1 SEE ALSO + +L<SSL_export_keying_material(3)> + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/SSLeay_version.pod b/deps/openssl/openssl/doc/crypto/SSLeay_version.pod deleted file mode 100644 index 1500c2af91..0000000000 --- a/deps/openssl/openssl/doc/crypto/SSLeay_version.pod +++ /dev/null @@ -1,74 +0,0 @@ -=pod - -=head1 NAME - -SSLeay_version - retrieve version/build information about OpenSSL library - -=head1 SYNOPSIS - - #include <openssl/crypto.h> - - const char *SSLeay_version(int type); - -=head1 DESCRIPTION - -SSLeay_version() returns a pointer to a constant string describing the -version of the OpenSSL library or giving information about the library -build. - -The following B<type> values are supported: - -=over 4 - -=item SSLEAY_VERSION - -The version of the OpenSSL library including the release date. - -=item SSLEAY_CFLAGS - -The compiler flags set for the compilation process in the form -"compiler: ..." if available or "compiler: information not available" -otherwise. - -=item SSLEAY_BUILT_ON - -The date of the build process in the form "built on: ..." if available -or "built on: date not available" otherwise. - -=item SSLEAY_PLATFORM - -The "Configure" target of the library build in the form "platform: ..." -if available or "platform: information not available" otherwise. - -=item SSLEAY_DIR - -The "OPENSSLDIR" setting of the library build in the form "OPENSSLDIR: "..."" -if available or "OPENSSLDIR: N/A" otherwise. - -=back - -=head1 RETURN VALUES - -The following return values can occur: - -=over 4 - -=item "not available" - -An invalid value for B<type> was given. - -=item Pointer to constant string - -Textual description. - -=back - -=head1 SEE ALSO - -L<crypto(3)|crypto(3)> - -=head1 HISTORY - -B<SSLEAY_DIR> was added in OpenSSL 0.9.7. - -=cut diff --git a/deps/openssl/openssl/doc/crypto/UI_STRING.pod b/deps/openssl/openssl/doc/crypto/UI_STRING.pod new file mode 100644 index 0000000000..8a0d9f2d25 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/UI_STRING.pod @@ -0,0 +1,134 @@ +=pod + +=head1 NAME + +UI_STRING, UI_string_types, UI_get_string_type, +UI_get_input_flags, UI_get0_output_string, +UI_get0_action_string, UI_get0_result_string, +UI_get0_test_string, UI_get_result_minsize, +UI_get_result_maxsize, UI_set_result +- User interface string parsing + +=head1 SYNOPSIS + + #include <openssl/ui.h> + + typedef struct ui_string_st UI_STRING; + + enum UI_string_types { + UIT_NONE = 0, + UIT_PROMPT, /* Prompt for a string */ + UIT_VERIFY, /* Prompt for a string and verify */ + UIT_BOOLEAN, /* Prompt for a yes/no response */ + UIT_INFO, /* Send info to the user */ + UIT_ERROR /* Send an error message to the user */ + }; + + enum UI_string_types UI_get_string_type(UI_STRING *uis); + int UI_get_input_flags(UI_STRING *uis); + const char *UI_get0_output_string(UI_STRING *uis); + const char *UI_get0_action_string(UI_STRING *uis); + const char *UI_get0_result_string(UI_STRING *uis); + const char *UI_get0_test_string(UI_STRING *uis); + int UI_get_result_minsize(UI_STRING *uis); + int UI_get_result_maxsize(UI_STRING *uis); + int UI_set_result(UI *ui, UI_STRING *uis, const char *result); + +=head1 DESCRIPTION + +The B<UI_STRING> gets created internally and added to a B<UI> whenever +one of the functions UI_add_input_string(), UI_dup_input_string(), +UI_add_verify_string(), UI_dup_verify_string(), +UI_add_input_boolean(), UI_dup_input_boolean(), UI_add_info_string(), +UI_dup_info_string(), UI_add_error_string() or UI_dup_error_string() +is called. +For a B<UI_METHOD> user, there's no need to know more. +For a B<UI_METHOD> creator, it is of interest to fetch text from these +B<UI_STRING> objects as well as adding results to some of them. + +UI_get_string_type() is used to retrieve the type of the given +B<UI_STRING>. + +UI_get_input_flags() is used to retrieve the flags associated with the +given B<UI_STRING>. + +UI_get0_output_string() is used to retrieve the actual string to +output (prompt, info, error, ...). + +UI_get0_action_string() is used to retrieve the action description +associated with a B<UIT_BOOLEAN> type B<UI_STRING>. +For all other B<UI_STRING> types, NULL is returned. +See L<UI_add_input_boolean(3)>. + +UI_get0_result_string() is used to retrieve the result of a prompt. +This is only useful for B<UIT_PROMPT> and B<UIT_VERIFY> type strings. +For all other B<UI_STRING> types, NULL is returned. + +UI_get0_test_string() is used to retrieve the string to compare the +prompt result with. +This is only useful for B<UIT_VERIFY> type strings. +For all other B<UI_STRING> types, NULL is returned. + +UI_get_result_minsize() and UI_get_result_maxsize() are used to +retrieve the minimum and maximum required size of the result. +This is only useful for B<UIT_PROMPT> and B<UIT_VERIFY> type strings. +For all other B<UI_STRING> types, -1 is returned. + +UI_set_result() is used to set the result value of a prompt. +For B<UIT_PROMPT> and B<UIT_VERIFY> type UI strings, this sets the +result retrievable with UI_get0_result_string() by copying the +contents of B<result> if its length fits the minimum and maximum size +requirements. +For B<UIT_BOOLEAN> type UI strings, this sets the first character of +the result retrievable with UI_get0_result_string() to the first +B<ok_char> given with UI_add_input_boolean() or UI_dup_input_boolean() +if the B<result> matched any of them, or the first of the +B<cancel_chars> if the B<result> matched any of them, otherwise it's +set to the NUL char C<\0>. +See L<UI_add_input_boolean(3)> for more information on B<ok_chars> and +B<cancel_chars>. + +=head1 RETURN VALUES + +UI_get_string_type() returns the UI string type. + +UI_get_input_flags() returns the UI string flags. + +UI_get0_output_string() returns the UI string output string. + +UI_get0_action_string() returns the UI string action description +string for B<UIT_BOOLEAN> type UI strings, NULL for any other type. + +UI_get0_result_string() returns the UI string result buffer for +B<UIT_PROMPT> and B<UIT_VERIFY> type UI strings, NULL for any other +type. + +UI_get0_test_string() returns the UI string action description +string for B<UIT_VERIFY> type UI strings, NULL for any other type. + +UI_get_result_minsize() returns the minimum allowed result size for +the UI string for for B<UIT_PROMPT> and B<UIT_VERIFY> type strings, +-1 for any other type. + +UI_get_result_maxsize() returns the minimum allowed result size for +the UI string for for B<UIT_PROMPT> and B<UIT_VERIFY> type strings, +-1 for any other type. + +UI_set_result() returns 0 on success or when the UI string is of any +type other than B<UIT_PROMPT>, B<UIT_VERIFY> or B<UIT_BOOLEAN>, -1 on +error. + +=head1 SEE ALSO + +L<UI(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/UI_create_method.pod b/deps/openssl/openssl/doc/crypto/UI_create_method.pod new file mode 100644 index 0000000000..1c40153a3f --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/UI_create_method.pod @@ -0,0 +1,202 @@ +=pod + +=head1 NAME + +UI_METHOD, +UI_create_method, UI_destroy_method, UI_method_set_opener, +UI_method_set_writer, UI_method_set_flusher, UI_method_set_reader, +UI_method_set_closer, UI_method_set_prompt_constructor, +UI_method_set_ex_data, UI_method_get_opener, UI_method_get_writer, +UI_method_get_flusher, UI_method_get_reader, UI_method_get_closer, +UI_method_get_prompt_constructor, UI_method_get_ex_data - user +interface method creation and destruction + +=head1 SYNOPSIS + + #include <openssl/ui.h> + + typedef struct ui_method_st UI_METHOD; + + UI_METHOD *UI_create_method(const char *name); + void UI_destroy_method(UI_METHOD *ui_method); + int UI_method_set_opener(UI_METHOD *method, int (*opener) (UI *ui)); + int UI_method_set_writer(UI_METHOD *method, + int (*writer) (UI *ui, UI_STRING *uis)); + int UI_method_set_flusher(UI_METHOD *method, int (*flusher) (UI *ui)); + int UI_method_set_reader(UI_METHOD *method, + int (*reader) (UI *ui, UI_STRING *uis)); + int UI_method_set_closer(UI_METHOD *method, int (*closer) (UI *ui)); + int UI_method_set_prompt_constructor(UI_METHOD *method, + char *(*prompt_constructor) (UI *ui, + const char + *object_desc, + const char + *object_name)); + int UI_method_set_ex_data(UI_METHOD *method, int idx, void *data); + int (*UI_method_get_opener(const UI_METHOD *method)) (UI *); + int (*UI_method_get_writer(const UI_METHOD *method)) (UI *, UI_STRING *); + int (*UI_method_get_flusher(const UI_METHOD *method)) (UI *); + int (*UI_method_get_reader(const UI_METHOD *method)) (UI *, UI_STRING *); + int (*UI_method_get_closer(const UI_METHOD *method)) (UI *); + char *(*UI_method_get_prompt_constructor(const UI_METHOD *method)) + (UI *, const char *, const char *); + const void *UI_method_get_ex_data(const UI_METHOD *method, int idx); + +=head1 DESCRIPTION + +A method contains a few functions that implement the low level of the +User Interface. +These functions are: + +=over 4 + +=item an opener + +This function takes a reference to a UI and starts a session, for +example by opening a channel to a tty, or by creating a dialog box. + +=item a writer + +This function takes a reference to a UI and a UI String, and writes +the string where appropriate, maybe to the tty, maybe added as a field +label in a dialog box. +Note that this gets fed all strings associated with a UI, one after +the other, so care must be taken which ones it actually uses. + +=item a flusher + +This function takes a reference to a UI, and flushes everything that +has been output so far. +For example, if the method builds up a dialog box, this can be used to +actually display it and accepting input ended with a pressed button. + +=item a reader + +This function takes a reference to a UI and a UI string and reads off +the given prompt, maybe from the tty, maybe from a field in a dialog +box. +Note that this gets fed all strings associated with a UI, one after +the other, so care must be taken which ones it actually uses. + +=item a closer + +This function takes a reference to a UI, and closes the session, maybe +by closing the channel to the tty, maybe by destroying a dialog box. + +=back + +All of these functions are expected to return 0 on error, 1 on +success, or -1 on out-off-band events, for example if some prompting +has been cancelled (by pressing Ctrl-C, for example). +Only the flusher or the reader are expected to return -1. +If returned by another of the functions, it's treated as if 0 was +returned. + +Regarding the writer and the reader, don't assume the former should +only write and don't assume the latter should only read. +This depends on the needs of the method. + +For example, a typical tty reader wouldn't write the prompts in the +write, but would rather do so in the reader, because of the sequential +nature of prompting on a tty. +This is how the UI_OpenSSL() method does it. + +In contrast, a method that builds up a dialog box would add all prompt +text in the writer, have all input read in the flusher and store the +results in some temporary buffer, and finally have the reader just +fetch those results. + +The central function that uses these method functions is UI_process(), +and it does it in five steps: + +=over 4 + +=item 1. + +Open the session using the opener function if that one's defined. +If an error occurs, jump to 5. + +=item 2. + +For every UI String associated with the UI, call the writer function +if that one's defined. +If an error occurs, jump to 5. + +=item 3. + +Flush everything using the flusher function if that one's defined. +If an error occurs, jump to 5. + +=item 4. + +For every UI String associated with the UI, call the reader function +if that one's defined. +If an error occurs, jump to 5. + +=item 5. + +Close the session using the closer function if that one's defined. + +=back + +UI_create_method() creates a new UI method with a given B<name>. + +UI_destroy_method() destroys the given UI method B<ui_method>. + +UI_method_set_opener(), UI_method_set_writer(), +UI_method_set_flusher(), UI_method_set_reader() and +UI_method_set_closer() set the five main method function to the given +function pointer. + +UI_method_set_prompt_constructor() sets the prompt constructor. +See L<UI_construct_prompt(3)>. + +UI_method_set_ex_data() sets application specific data with a given +EX_DATA index. +See L<CRYPTO_get_ex_new_index(3)> for general information on how to +get that index. + +UI_method_get_opener(), UI_method_get_writer(), +UI_method_get_flusher(), UI_method_get_reader(), +UI_method_get_closer() and UI_method_get_prompt_constructor() return +the different method functions. + +UI_method_get_ex_data() returns the application data previously stored +with UI_method_set_ex_data(). + +=head1 RETURN VALUES + +UI_create_method() returns a UI_METHOD pointer on success, NULL on +error. + +UI_method_set_opener(), UI_method_set_writer(), +UI_method_set_flusher(), UI_method_set_reader(), +UI_method_set_closer() and UI_method_set_prompt_constructor() return +0 on success, -1 if the given B<method> is NULL. + +UI_method_set_ex_data() returns 1 on success and 0 on error (because +CRYPTO_set_ex_data() does so). + +UI_method_get_opener(), UI_method_get_writer(), +UI_method_get_flusher(), UI_method_get_reader(), +UI_method_get_closer() and UI_method_get_prompt_constructor() return +the requested function pointer if it's set in the method, otherwise +NULL. + +UI_method_get_ex_data() returns a pointer to the application specific +data associated with the method. + +=head1 SEE ALSO + +L<UI(3)>, L<CRYPTO_get_ex_data(3)>, L<UI_STRING(3)> + +=head1 COPYRIGHT + +Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/ui.pod b/deps/openssl/openssl/doc/crypto/UI_new.pod index 2e94d8c0f6..5b98cf8d0d 100644 --- a/deps/openssl/openssl/doc/crypto/ui.pod +++ b/deps/openssl/openssl/doc/crypto/UI_new.pod @@ -2,50 +2,46 @@ =head1 NAME +UI, UI_new, UI_new_method, UI_free, UI_add_input_string, UI_dup_input_string, UI_add_verify_string, UI_dup_verify_string, UI_add_input_boolean, UI_dup_input_boolean, UI_add_info_string, UI_dup_info_string, UI_add_error_string, UI_dup_error_string, UI_construct_prompt, UI_add_user_data, UI_get0_user_data, UI_get0_result, UI_process, UI_ctrl, UI_set_default_method, UI_get_default_method, UI_get_method, -UI_set_method, UI_OpenSSL, ERR_load_UI_strings - New User Interface +UI_set_method, UI_OpenSSL, UI_null - user interface =head1 SYNOPSIS #include <openssl/ui.h> typedef struct ui_st UI; - typedef struct ui_method_st UI_METHOD; UI *UI_new(void); UI *UI_new_method(const UI_METHOD *method); void UI_free(UI *ui); int UI_add_input_string(UI *ui, const char *prompt, int flags, - char *result_buf, int minsize, int maxsize); + char *result_buf, int minsize, int maxsize); int UI_dup_input_string(UI *ui, const char *prompt, int flags, - char *result_buf, int minsize, int maxsize); + char *result_buf, int minsize, int maxsize); int UI_add_verify_string(UI *ui, const char *prompt, int flags, - char *result_buf, int minsize, int maxsize, const char *test_buf); + char *result_buf, int minsize, int maxsize, const char *test_buf); int UI_dup_verify_string(UI *ui, const char *prompt, int flags, - char *result_buf, int minsize, int maxsize, const char *test_buf); + char *result_buf, int minsize, int maxsize, const char *test_buf); int UI_add_input_boolean(UI *ui, const char *prompt, const char *action_desc, - const char *ok_chars, const char *cancel_chars, - int flags, char *result_buf); + const char *ok_chars, const char *cancel_chars, + int flags, char *result_buf); int UI_dup_input_boolean(UI *ui, const char *prompt, const char *action_desc, - const char *ok_chars, const char *cancel_chars, - int flags, char *result_buf); + const char *ok_chars, const char *cancel_chars, + int flags, char *result_buf); int UI_add_info_string(UI *ui, const char *text); int UI_dup_info_string(UI *ui, const char *text); int UI_add_error_string(UI *ui, const char *text); int UI_dup_error_string(UI *ui, const char *text); - /* These are the possible flags. They can be or'ed together. */ - #define UI_INPUT_FLAG_ECHO 0x01 - #define UI_INPUT_FLAG_DEFAULT_PWD 0x02 - char *UI_construct_prompt(UI *ui_method, - const char *object_desc, const char *object_name); + const char *object_desc, const char *object_name); void *UI_add_user_data(UI *ui, void *user_data); void *UI_get0_user_data(UI *ui); @@ -55,8 +51,6 @@ UI_set_method, UI_OpenSSL, ERR_load_UI_strings - New User Interface int UI_process(UI *ui); int UI_ctrl(UI *ui, int cmd, long i, void *p, void (*f)()); - #define UI_CTRL_PRINT_ERRORS 1 - #define UI_CTRL_IS_REDOABLE 2 void UI_set_default_method(const UI_METHOD *meth); const UI_METHOD *UI_get_default_method(void); @@ -64,12 +58,13 @@ UI_set_method, UI_OpenSSL, ERR_load_UI_strings - New User Interface const UI_METHOD *UI_set_method(UI *ui, const UI_METHOD *meth); UI_METHOD *UI_OpenSSL(void); + const UI_METHOD *UI_null(void); =head1 DESCRIPTION UI stands for User Interface, and is general purpose set of routines to prompt the user for text-based information. Through user-written methods -(see L<ui_create(3)|ui_create(3)>), prompting can be done in any way +(see L<UI_create_method(3)>), prompting can be done in any way imaginable, be it plain text prompting, through dialog boxes or from a cell phone. @@ -99,13 +94,17 @@ this UI, it should be freed using UI_free(). UI_new_method() creates a new UI using the given UI method. When done with this UI, it should be freed using UI_free(). -UI_OpenSSL() returns the built-in UI method (note: not the default one, -since the default can be changed. See further on). This method is the -most machine/OS dependent part of OpenSSL and normally generates the -most problems when porting. +UI_OpenSSL() returns the built-in UI method (note: not necessarely the +default one, since the default can be changed. See further on). This +method is the most machine/OS dependent part of OpenSSL and normally +generates the most problems when porting. + +UI_null() returns a UI method that does nothing. Its use is to avoid +getting internal defaults for passed UI_METHOD pointers. UI_free() removes a UI from memory, along with all other pieces of memory that's connected to it, like duplicated input strings, results and others. +If B<ui> is NULL nothing is done. UI_add_input_string() and UI_add_verify_string() add a prompt to the UI, as well as flags and a result buffer and the desired minimum and maximum @@ -129,10 +128,10 @@ The difference between the two is only conceptual. With the builtin method, there's no technical difference between them. Other methods may make a difference between them, however. -The flags currently supported are UI_INPUT_FLAG_ECHO, which is relevant for +The flags currently supported are B<UI_INPUT_FLAG_ECHO>, which is relevant for UI_add_input_string() and will have the users response be echoed (when prompting for a password, this flag should obviously not be used, and -UI_INPUT_FLAG_DEFAULT_PWD, which means that a default password of some +B<UI_INPUT_FLAG_DEFAULT_PWD>, which means that a default password of some sort will be used (completely depending on the application and the UI method). @@ -162,15 +161,18 @@ UI_get0_result() returns a pointer to the result buffer associated with the information indexed by I<i>. UI_process() goes through the information given so far, does all the printing -and prompting and returns. +and prompting and returns the final status, which is -2 on out-of-band events +(Interrupt, Cancel, ...), -1 on error and 0 on success. UI_ctrl() adds extra control for the application author. For now, it -understands two commands: UI_CTRL_PRINT_ERRORS, which makes UI_process() +understands two commands: B<UI_CTRL_PRINT_ERRORS>, which makes UI_process() print the OpenSSL error stack as part of processing the UI, and -UI_CTRL_IS_REDOABLE, which returns a flag saying if the used UI can +B<UI_CTRL_IS_REDOABLE>, which returns a flag saying if the used UI can be used again or not. UI_set_default_method() changes the default UI method to the one given. +This function is not thread-safe and should not be called at the same time +as other OpenSSL functions. UI_get_default_method() returns a pointer to the current default UI method. @@ -178,17 +180,24 @@ UI_get_method() returns the UI method associated with a given UI. UI_set_method() changes the UI method associated with a given UI. -=head1 SEE ALSO - -L<ui_create(3)|ui_create(3)>, L<ui_compat(3)|ui_compat(3)> +=head1 NOTES -=head1 HISTORY +The resulting strings that the built in method UI_OpenSSL() generate +are assumed to be encoded according to the current locale or (for +Windows) code page. +For applications having different demands, these strings need to be +converted appropriately by the caller. +For Windows, if the OPENSSL_WIN32_UTF8 environment variable is set, +the built-in method UI_OpenSSL() will produce UTF-8 encoded strings +instead. -The UI section was first introduced in OpenSSL 0.9.7. +=head1 COPYRIGHT -=head1 AUTHOR +Copyright 2001-2017 The OpenSSL Project Authors. All Rights Reserved. -Richard Levitte (richard@levitte.org) for the OpenSSL project -(http://www.openssl.org). +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509V3_get_d2i.pod b/deps/openssl/openssl/doc/crypto/X509V3_get_d2i.pod new file mode 100644 index 0000000000..ac560b21e9 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/X509V3_get_d2i.pod @@ -0,0 +1,241 @@ +=pod + +=head1 NAME + +X509_get0_extensions, X509_CRL_get0_extensions, X509_REVOKED_get0_extensions, +X509V3_get_d2i, X509V3_add1_i2d, X509V3_EXT_d2i, X509V3_EXT_i2d, +X509_get_ext_d2i, X509_add1_ext_i2d, X509_CRL_get_ext_d2i, +X509_CRL_add1_ext_i2d, X509_REVOKED_get_ext_d2i, +X509_REVOKED_add1_ext_i2d - X509 extension decode and encode functions + +=head1 SYNOPSIS + + #include <openssl/x509v3.h> + + void *X509V3_get_d2i(const STACK_OF(X509_EXTENSION) *x, int nid, int *crit, + int *idx); + int X509V3_add1_i2d(STACK_OF(X509_EXTENSION) **x, int nid, void *value, + int crit, unsigned long flags); + + void *X509V3_EXT_d2i(X509_EXTENSION *ext); + X509_EXTENSION *X509V3_EXT_i2d(int ext_nid, int crit, void *ext); + + void *X509_get_ext_d2i(const X509 *x, int nid, int *crit, int *idx); + int X509_add1_ext_i2d(X509 *x, int nid, void *value, int crit, + unsigned long flags); + + void *X509_CRL_get_ext_d2i(const X509_CRL *crl, int nid, int *crit, int *idx); + int X509_CRL_add1_ext_i2d(X509_CRL *crl, int nid, void *value, int crit, + unsigned long flags); + + void *X509_REVOKED_get_ext_d2i(const X509_REVOKED *r, int nid, int *crit, int *idx); + int X509_REVOKED_add1_ext_i2d(X509_REVOKED *r, int nid, void *value, int crit, + unsigned long flags); + + const STACK_OF(X509_EXTENSION) *X509_get0_extensions(const X509 *x); + const STACK_OF(X509_EXTENSION) *X509_CRL_get0_extensions(const X509_CRL *crl); + const STACK_OF(X509_EXTENSION) *X509_REVOKED_get0_extensions(const X509_REVOKED *r); + +=head1 DESCRIPTION + +X509V3_get_ext_d2i() looks for an extension with OID B<nid> in the extensions +B<x> and, if found, decodes it. If B<idx> is B<NULL> then only one +occurrence of an extension is permissible otherwise the first extension after +index B<*idx> is returned and B<*idx> updated to the location of the extension. +If B<crit> is not B<NULL> then B<*crit> is set to a status value: -2 if the +extension occurs multiple times (this is only returned if B<idx> is B<NULL>), +-1 if the extension could not be found, 0 if the extension is found and is +not critical and 1 if critical. A pointer to an extension specific structure +or B<NULL> is returned. + +X509V3_add1_i2d() adds extension B<value> to STACK B<*x> (allocating a new +STACK if necessary) using OID B<nid> and criticality B<crit> according +to B<flags>. + +X509V3_EXT_d2i() attempts to decode the ASN.1 data contained in extension +B<ext> and returns a pointer to an extension specific structure or B<NULL> +if the extension could not be decoded (invalid syntax or not supported). + +X509V3_EXT_i2d() encodes the extension specific structure B<ext> +with OID B<ext_nid> and criticality B<crit>. + +X509_get_ext_d2i() and X509_add1_ext_i2d() operate on the extensions of +certificate B<x>, they are otherwise identical to X509V3_get_d2i() and +X509V3_add_i2d(). + +X509_CRL_get_ext_d2i() and X509_CRL_add1_ext_i2d() operate on the extensions +of CRL B<crl>, they are otherwise identical to X509V3_get_d2i() and +X509V3_add_i2d(). + +X509_REVOKED_get_ext_d2i() and X509_REVOKED_add1_ext_i2d() operate on the +extensions of B<X509_REVOKED> structure B<r> (i.e for CRL entry extensions), +they are otherwise identical to X509V3_get_d2i() and X509V3_add_i2d(). + +X509_get0_extensions(), X509_CRL_get0_extensions() and +X509_REVOKED_get0_extensions() return a stack of all the extensions +of a certificate a CRL or a CRL entry respectively. + +=head1 NOTES + +In almost all cases an extension can occur at most once and multiple +occurrences is an error. Therefore the B<idx> parameter is usually B<NULL>. + +The B<flags> parameter may be one of the following values. + +B<X509V3_ADD_DEFAULT> appends a new extension only if the extension does +not already exist. An error is returned if the extension does already +exist. + +B<X509V3_ADD_APPEND> appends a new extension, ignoring whether the extension +already exists. + +B<X509V3_ADD_REPLACE> replaces an extension if it exists otherwise appends +a new extension. + +B<X509V3_ADD_REPLACE_EXISTING> replaces an existing extension if it exists +otherwise returns an error. + +B<X509V3_ADD_KEEP_EXISTING> appends a new extension only if the extension does +not already exist. An error B<is not> returned if the extension does already +exist. + +B<X509V3_ADD_DELETE> extension B<nid> is deleted: no new extension is added. + +If B<X509V3_ADD_SILENT> is ored with B<flags>: any error returned will not +be added to the error queue. + +The function X509V3_get_d2i() will return B<NULL> if the extension is not +found, occurs multiple times or cannot be decoded. It is possible to +determine the precise reason by checking the value of B<*crit>. + +=head1 SUPPORTED EXTENSIONS + +The following sections contain a list of all supported extensions +including their name and NID. + +=head2 PKIX Certificate Extensions + +The following certificate extensions are defined in PKIX standards such as +RFC5280. + + Basic Constraints NID_basic_constraints + Key Usage NID_key_usage + Extended Key Usage NID_ext_key_usage + + Subject Key Identifier NID_subject_key_identifier + Authority Key Identifier NID_authority_key_identifier + + Private Key Usage Period NID_private_key_usage_period + + Subject Alternative Name NID_subject_alt_name + Issuer Alternative Name NID_issuer_alt_name + + Authority Information Access NID_info_access + Subject Information Access NID_sinfo_access + + Name Constraints NID_name_constraints + + Certificate Policies NID_certificate_policies + Policy Mappings NID_policy_mappings + Policy Constraints NID_policy_constraints + Inhibit Any Policy NID_inhibit_any_policy + + TLS Feature NID_tlsfeature + +=head2 Netscape Certificate Extensions + +The following are (largely obsolete) Netscape certificate extensions. + + Netscape Cert Type NID_netscape_cert_type + Netscape Base Url NID_netscape_base_url + Netscape Revocation Url NID_netscape_revocation_url + Netscape CA Revocation Url NID_netscape_ca_revocation_url + Netscape Renewal Url NID_netscape_renewal_url + Netscape CA Policy Url NID_netscape_ca_policy_url + Netscape SSL Server Name NID_netscape_ssl_server_name + Netscape Comment NID_netscape_comment + +=head2 Miscellaneous Certificate Extensions + + Strong Extranet ID NID_sxnet + Proxy Certificate Information NID_proxyCertInfo + +=head2 PKIX CRL Extensions + +The following are CRL extensions from PKIX standards such as RFC5280. + + CRL Number NID_crl_number + CRL Distribution Points NID_crl_distribution_points + Delta CRL Indicator NID_delta_crl + Freshest CRL NID_freshest_crl + Invalidity Date NID_invalidity_date + Issuing Distribution Point NID_issuing_distribution_point + +The following are CRL entry extensions from PKIX standards such as RFC5280. + + CRL Reason Code NID_crl_reason + Certificate Issuer NID_certificate_issuer + +=head2 OCSP Extensions + + OCSP Nonce NID_id_pkix_OCSP_Nonce + OCSP CRL ID NID_id_pkix_OCSP_CrlID + Acceptable OCSP Responses NID_id_pkix_OCSP_acceptableResponses + OCSP No Check NID_id_pkix_OCSP_noCheck + OCSP Archive Cutoff NID_id_pkix_OCSP_archiveCutoff + OCSP Service Locator NID_id_pkix_OCSP_serviceLocator + Hold Instruction Code NID_hold_instruction_code + +=head2 Certificate Transparency Extensions + +The following extensions are used by certificate transparency, RFC6962 + + CT Precertificate SCTs NID_ct_precert_scts + CT Certificate SCTs NID_ct_cert_scts + +=head1 RETURN VALUES + +X509V3_EXT_d2i() and *X509V3_get_d2i() return a pointer to an extension +specific structure of B<NULL> if an error occurs. + +X509V3_EXT_i2d() returns a pointer to an B<X509_EXTENSION> structure +or B<NULL> if an error occurs. + +X509V3_add1_i2d() returns 1 if the operation is successful and 0 if it +fails due to a non-fatal error (extension not found, already exists, +cannot be encoded) or -1 due to a fatal error such as a memory allocation +failure. + +X509_get0_extensions(), X509_CRL_get0_extensions() and +X509_REVOKED_get0_extensions() return a stack of extensions. They return +NULL if no extensions are present. + +=head1 SEE ALSO + +L<d2i_X509(3)>, +L<ERR_get_error(3)>, +L<X509_CRL_get0_by_serial(3)>, +L<X509_get0_signature(3)>, +L<X509_get_ext_d2i(3)>, +L<X509_get_extension_flags(3)>, +L<X509_get_pubkey(3)>, +L<X509_get_subject_name(3)>, +L<X509_get_version(3)>, +L<X509_NAME_add_entry_by_txt(3)>, +L<X509_NAME_ENTRY_get_object(3)>, +L<X509_NAME_get_index_by_NID(3)>, +L<X509_NAME_print_ex(3)>, +L<X509_new(3)>, +L<X509_sign(3)>, +L<X509_verify_cert(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_ALGOR_dup.pod b/deps/openssl/openssl/doc/crypto/X509_ALGOR_dup.pod new file mode 100644 index 0000000000..21845e975a --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/X509_ALGOR_dup.pod @@ -0,0 +1,48 @@ +=pod + +=head1 NAME + +X509_ALGOR_dup, X509_ALGOR_set0, X509_ALGOR_get0, X509_ALGOR_set_md, X509_ALGOR_cmp - AlgorithmIdentifier functions + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + X509_ALGOR *X509_ALGOR_dup(X509_ALGOR *alg); + int X509_ALGOR_set0(X509_ALGOR *alg, ASN1_OBJECT *aobj, int ptype, void *pval); + void X509_ALGOR_get0(const ASN1_OBJECT **paobj, int *pptype, + const void **ppval, const X509_ALGOR *alg); + void X509_ALGOR_set_md(X509_ALGOR *alg, const EVP_MD *md); + int X509_ALGOR_cmp(const X509_ALGOR *a, const X509_ALGOR *b); + +=head1 DESCRIPTION + +X509_ALGOR_dup() returns a copy of B<alg>. + +X509_ALGOR_set0() sets the algorithm OID of B<alg> to B<aobj> and the +associated parameter type to B<ptype> with value B<pval>. If B<ptype> is +B<V_ASN1_UNDEF> the parameter is omitted, otherwise B<ptype> and B<pval> have +the same meaning as the B<type> and B<value> parameters to ASN1_TYPE_set(). +All the supplied parameters are used internally so must B<NOT> be freed after +this call. + +X509_ALGOR_get0() is the inverse of X509_ALGOR_set0(): it returns the +algorithm OID in B<*paobj> and the associated parameter in B<*pptype> +and B<*ppval> from the B<AlgorithmIdentifier> B<alg>. + +X509_ALGOR_set_md() sets the B<AlgorithmIdentifier> B<alg> to appropriate +values for the message digest B<md>. + +X509_ALGOR_cmp() compares B<a> and B<b> and returns 0 if they have identical +encodings and non-zero otherwise. + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_CRL_get0_by_serial.pod b/deps/openssl/openssl/doc/crypto/X509_CRL_get0_by_serial.pod new file mode 100644 index 0000000000..a704228eb9 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/X509_CRL_get0_by_serial.pod @@ -0,0 +1,115 @@ +=pod + +=head1 NAME + +X509_CRL_get0_by_serial, X509_CRL_get0_by_cert, X509_CRL_get_REVOKED, +X509_REVOKED_get0_serialNumber, X509_REVOKED_get0_revocationDate, +X509_REVOKED_set_serialNumber, X509_REVOKED_set_revocationDate, +X509_CRL_add0_revoked, X509_CRL_sort - CRL revoked entry utility +functions + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + int X509_CRL_get0_by_serial(X509_CRL *crl, + X509_REVOKED **ret, ASN1_INTEGER *serial); + int X509_CRL_get0_by_cert(X509_CRL *crl, X509_REVOKED **ret, X509 *x); + + STACK_OF(X509_REVOKED) *X509_CRL_get_REVOKED(X509_CRL *crl); + + const ASN1_INTEGER *X509_REVOKED_get0_serialNumber(const X509_REVOKED *r); + const ASN1_TIME *X509_REVOKED_get0_revocationDate(const X509_REVOKED *r); + + int X509_REVOKED_set_serialNumber(X509_REVOKED *r, ASN1_INTEGER *serial); + int X509_REVOKED_set_revocationDate(X509_REVOKED *r, ASN1_TIME *tm); + + int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev); + + int X509_CRL_sort(X509_CRL *crl); + +=head1 DESCRIPTION + +X509_CRL_get0_by_serial() attempts to find a revoked entry in B<crl> for +serial number B<serial>. If it is successful it sets B<*ret> to the internal +pointer of the matching entry, as a result B<*ret> must not be freed up +after the call. + +X509_CRL_get0_by_cert() is similar to X509_get0_by_serial() except it +looks for a revoked entry using the serial number of certificate B<x>. + +X509_CRL_get_REVOKED() returns an internal pointer to a stack of all +revoked entries for B<crl>. + +X509_REVOKED_get0_serialNumber() returns an internal pointer to the +serial number of B<r>. + +X509_REVOKED_get0_revocationDate() returns an internal pointer to the +revocation date of B<r>. + +X509_REVOKED_set_serialNumber() sets the serial number of B<r> to B<serial>. +The supplied B<serial> pointer is not used internally so it should be +freed up after use. + +X509_REVOKED_set_revocationDate() sets the revocation date of B<r> to +B<tm>. The supplied B<tm> pointer is not used internally so it should be +freed up after use. + +X509_CRL_add0_revoked() appends revoked entry B<rev> to CRL B<crl>. The +pointer B<rev> is used internally so it must not be freed up after the call: +it is freed when the parent CRL is freed. + +X509_CRL_sort() sorts the revoked entries of B<crl> into ascending serial +number order. + +=head1 NOTES + +Applications can determine the number of revoked entries returned by +X509_CRL_get_revoked() using sk_X509_REVOKED_num() and examine each one +in turn using sk_X509_REVOKED_value(). + +=head1 RETURN VALUES + +X509_CRL_get0_by_serial() and X509_CRL_get0_by_cert() return 0 for failure, +1 on success except if the revoked entry has the reason C<removeFromCRL> (8), +in which case 2 is returned. + +X509_REVOKED_set_serialNumber(), X509_REVOKED_set_revocationDate(), +X509_CRL_add0_revoked() and X509_CRL_sort() return 1 for success and 0 for +failure. + +X509_REVOKED_get0_serialNumber() returns an B<ASN1_INTEGER> pointer. + +X509_REVOKED_get0_revocationDate() returns an B<ASN1_TIME> value. + +X509_CRL_get_REVOKED() returns a STACK of revoked entries. + +=head1 SEE ALSO + +L<d2i_X509(3)>, +L<ERR_get_error(3)>, +L<X509_get0_signature(3)>, +L<X509_get_ext_d2i(3)>, +L<X509_get_extension_flags(3)>, +L<X509_get_pubkey(3)>, +L<X509_get_subject_name(3)>, +L<X509_get_version(3)>, +L<X509_NAME_add_entry_by_txt(3)>, +L<X509_NAME_ENTRY_get_object(3)>, +L<X509_NAME_get_index_by_NID(3)>, +L<X509_NAME_print_ex(3)>, +L<X509_new(3)>, +L<X509_sign(3)>, +L<X509V3_get_d2i(3)>, +L<X509_verify_cert(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_EXTENSION_set_object.pod b/deps/openssl/openssl/doc/crypto/X509_EXTENSION_set_object.pod new file mode 100644 index 0000000000..f3f0de636e --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/X509_EXTENSION_set_object.pod @@ -0,0 +1,96 @@ +=pod + +=head1 NAME + +X509_EXTENSION_set_object, X509_EXTENSION_set_critical, +X509_EXTENSION_set_data, X509_EXTENSION_create_by_NID, +X509_EXTENSION_create_by_OBJ, X509_EXTENSION_get_object, +X509_EXTENSION_get_critical, X509_EXTENSION_get_data - extension utility +functions + +=head1 SYNOPSIS + + int X509_EXTENSION_set_object(X509_EXTENSION *ex, const ASN1_OBJECT *obj); + int X509_EXTENSION_set_critical(X509_EXTENSION *ex, int crit); + int X509_EXTENSION_set_data(X509_EXTENSION *ex, ASN1_OCTET_STRING *data); + + X509_EXTENSION *X509_EXTENSION_create_by_NID(X509_EXTENSION **ex, + int nid, int crit, + ASN1_OCTET_STRING *data); + X509_EXTENSION *X509_EXTENSION_create_by_OBJ(X509_EXTENSION **ex, + const ASN1_OBJECT *obj, int crit, + ASN1_OCTET_STRING *data); + + ASN1_OBJECT *X509_EXTENSION_get_object(X509_EXTENSION *ex); + int X509_EXTENSION_get_critical(const X509_EXTENSION *ex); + ASN1_OCTET_STRING *X509_EXTENSION_get_data(X509_EXTENSION *ne); + +=head1 DESCRIPTION + +X509_EXTENSION_set_object() sets the extension type of B<ex> to B<obj>. The +B<obj> pointer is duplicated internally so B<obj> should be freed up after use. + +X509_EXTENSION_set_critical() sets the criticality of B<ex> to B<crit>. If +B<crit> is zero the extension in non-critical otherwise it is critical. + +X509_EXTENSION_set_data() sets the data in extension B<ex> to B<data>. The +B<data> pointer is duplicated internally. + +X509_EXTENSION_create_by_NID() creates an extension of type B<nid>, +criticality B<crit> using data B<data>. The created extension is returned and +written to B<*ex> reusing or allocating a new extension if necessary so B<*ex> +should either be B<NULL> or a valid B<X509_EXTENSION> structure it must +B<not> be an uninitialised pointer. + +X509_EXTENSION_create_by_OBJ() is identical to X509_EXTENSION_create_by_NID() +except it creates and extension using B<obj> instead of a NID. + +X509_EXTENSION_get_object() returns the extension type of B<ex> as an +B<ASN1_OBJECT> pointer. The returned pointer is an internal value which must +not be freed up. + +X509_EXTENSION_get_critical() returns the criticality of extension B<ex> it +returns B<1> for critical and B<0> for non-critical. + +X509_EXTENSION_get_data() returns the data of extension B<ex>. The returned +pointer is an internal value which must not be freed up. + +=head1 NOTES + +These functions manipulate the contents of an extension directly. Most +applications will want to parse or encode and add an extension: they should +use the extension encode and decode functions instead such as +X509_add1_ext_i2d() and X509_get_ext_d2i(). + +The B<data> associated with an extension is the extension encoding in an +B<ASN1_OCTET_STRING> structure. + +=head1 RETURN VALUES + +X509_EXTENSION_set_object() X509_EXTENSION_set_critical() and +X509_EXTENSION_set_data() return B<1> for success and B<0> for failure. + +X509_EXTENSION_create_by_NID() and X509_EXTENSION_create_by_OBJ() return +an B<X509_EXTENSION> pointer or B<NULL> if an error occurs. + +X509_EXTENSION_get_object() returns an B<ASN1_OBJECT> pointer. + +X509_EXTENSION_get_critical() returns B<0> for non-critical and B<1> for +critical. + +X509_EXTENSION_get_data() returns an B<ASN1_OCTET_STRING> pointer. + +=head1 SEE ALSO + +L<X509V3_get_d2i(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_LOOKUP_hash_dir.pod b/deps/openssl/openssl/doc/crypto/X509_LOOKUP_hash_dir.pod new file mode 100644 index 0000000000..5f8dfa93b0 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/X509_LOOKUP_hash_dir.pod @@ -0,0 +1,130 @@ +=pod + +=head1 NAME + +X509_LOOKUP_hash_dir, X509_LOOKUP_file, +X509_load_cert_file, +X509_load_crl_file, +X509_load_cert_crl_file - Default OpenSSL certificate +lookup methods + +=head1 SYNOPSIS + + #include <openssl/x509_vfy.h> + + X509_LOOKUP_METHOD *X509_LOOKUP_hash_dir(void); + X509_LOOKUP_METHOD *X509_LOOKUP_file(void); + + int X509_load_cert_file(X509_LOOKUP *ctx, const char *file, int type); + int X509_load_crl_file(X509_LOOKUP *ctx, const char *file, int type); + int X509_load_cert_crl_file(X509_LOOKUP *ctx, const char *file, int type); + +=head1 DESCRIPTION + +B<X509_LOOKUP_hash_dir> and B<X509_LOOKUP_file> are two certificate +lookup methods to use with B<X509_STORE>, provided by OpenSSL library. + +Users of the library typically do not need to create instances of these +methods manually, they would be created automatically by +L<X509_STORE_load_locations(3)> or +L<SSL_CTX_load_verify_locations(3)> +functions. + +Internally loading of certificates and CRLs is implemented via functions +B<X509_load_cert_crl_file>, B<X509_load_cert_file> and +B<X509_load_crl_file>. These functions support parameter I<type>, which +can be one of constants B<FILETYPE_PEM>, B<FILETYPE_ASN1> and +B<FILETYPE_DEFAULT>. They load certificates and/or CRLs from specified +file into memory cache of B<X509_STORE> objects which given B<ctx> +parameter is associated with. + +Functions B<X509_load_cert_file> and +B<X509_load_crl_file> can load both PEM and DER formats depending of +type value. Because DER format cannot contain more than one certificate +or CRL object (while PEM can contain several concatenated PEM objects) +B<X509_load_cert_crl_file> with B<FILETYPE_ASN1> is equivalent to +B<X509_load_cert_file>. + +Constant B<FILETYPE_DEFAULT> with NULL filename causes these functions +to load default certificate store file (see +L<X509_STORE_set_default_paths(3)>. + + +Functions return number of objects loaded from file or 0 in case of +error. + +Both methods support adding several certificate locations into one +B<X509_STORE>. + +This page documents certificate store formats used by these methods and +caching policy. + +=head2 File Method + +The B<X509_LOOKUP_file> method loads all the certificates or CRLs +present in a file into memory at the time the file is added as a +lookup source. + +File format is ASCII text which contains concatenated PEM certificates +and CRLs. + +This method should be used by applications which work with a small +set of CAs. + +=head2 Hashed Directory Method + +B<X509_LOOKUP_hash_dir> is a more advanced method, which loads +certificates and CRLs on demand, and caches them in memory once +they are loaded. As of OpenSSL 1.0.0, it also checks for newer CRLs +upon each lookup, so that newer CRLs are as soon as they appear in +the directory. + +The directory should contain one certificate or CRL per file in PEM format, +with a file name of the form I<hash>.I<N> for a certificate, or +I<hash>.B<r>I<N> for a CRL. +The I<hash> is the value returned by the L<X509_NAME_hash(3)> function applied +to the subject name for certificates or issuer name for CRLs. +The hash can also be obtained via the B<-hash> option of the L<x509(1)> or +L<crl(1)> commands. + +The .I<N> or .B<r>I<N> suffix is a sequence number that starts at zero, and is +incremented consecutively for each certificate or CRL with the same I<hash> +value. +Gaps in the sequence numbers are not supported, it is assumed that there are no +more objects with the same hash beyond the first missing number in the +sequence. + +Sequence numbers make it possible for the directory to contain multiple +certificates with same subject name hash value. +For example, it is possible to have in the store several certificates with same +subject or several CRLs with same issuer (and, for example, different validity +period). + +When checking for new CRLs once one CRL for given hash value is +loaded, hash_dir lookup method checks only for certificates with +sequence number greater than that of the already cached CRL. + +Note that the hash algorithm used for subject name hashing changed in OpenSSL +1.0.0, and all certificate stores have to be rehashed when moving from OpenSSL +0.9.8 to 1.0.0. + +OpenSSL includes a L<rehash(1)> utility which creates symlinks with correct +hashed names for all files with .pem suffix in a given directory. + +=head1 SEE ALSO + +L<PEM_read_PrivateKey(3)>, +L<X509_STORE_load_locations(3)>, +L<X509_store_add_lookup(3)>, +L<SSL_CTX_load_verify_locations(3)>, + +=head1 COPYRIGHT + +Copyright 2015-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_NAME_ENTRY_get_object.pod b/deps/openssl/openssl/doc/crypto/X509_NAME_ENTRY_get_object.pod index 4716e7ee75..72e0f7b11d 100644 --- a/deps/openssl/openssl/doc/crypto/X509_NAME_ENTRY_get_object.pod +++ b/deps/openssl/openssl/doc/crypto/X509_NAME_ENTRY_get_object.pod @@ -11,15 +11,15 @@ X509_NAME_ENTRY_create_by_OBJ - X509_NAME_ENTRY utility functions #include <openssl/x509.h> - ASN1_OBJECT * X509_NAME_ENTRY_get_object(X509_NAME_ENTRY *ne); - ASN1_STRING * X509_NAME_ENTRY_get_data(X509_NAME_ENTRY *ne); + ASN1_OBJECT * X509_NAME_ENTRY_get_object(const X509_NAME_ENTRY *ne); + ASN1_STRING * X509_NAME_ENTRY_get_data(const X509_NAME_ENTRY *ne); - int X509_NAME_ENTRY_set_object(X509_NAME_ENTRY *ne, ASN1_OBJECT *obj); + int X509_NAME_ENTRY_set_object(X509_NAME_ENTRY *ne, const ASN1_OBJECT *obj); int X509_NAME_ENTRY_set_data(X509_NAME_ENTRY *ne, int type, const unsigned char *bytes, int len); X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_txt(X509_NAME_ENTRY **ne, const char *field, int type, const unsigned char *bytes, int len); - X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_NID(X509_NAME_ENTRY **ne, int nid, int type,unsigned char *bytes, int len); - X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_OBJ(X509_NAME_ENTRY **ne, ASN1_OBJECT *obj, int type, const unsigned char *bytes, int len); + X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_NID(X509_NAME_ENTRY **ne, int nid, int type, const unsigned char *bytes, int len); + X509_NAME_ENTRY *X509_NAME_ENTRY_create_by_OBJ(X509_NAME_ENTRY **ne, const ASN1_OBJECT *obj, int type, const unsigned char *bytes, int len); =head1 DESCRIPTION @@ -35,17 +35,17 @@ X509_NAME_ENTRY_set_data() sets the field value of B<ne> to string type B<type> and value determined by B<bytes> and B<len>. X509_NAME_ENTRY_create_by_txt(), X509_NAME_ENTRY_create_by_NID() -and X509_NAME_ENTRY_create_by_OBJ() create and return an +and X509_NAME_ENTRY_create_by_OBJ() create and return an B<X509_NAME_ENTRY> structure. =head1 NOTES X509_NAME_ENTRY_get_object() and X509_NAME_ENTRY_get_data() can be -used to examine an B<X509_NAME_ENTRY> function as returned by +used to examine an B<X509_NAME_ENTRY> function as returned by X509_NAME_get_entry() for example. X509_NAME_ENTRY_create_by_txt(), X509_NAME_ENTRY_create_by_NID(), -and X509_NAME_ENTRY_create_by_OBJ() create and return an +and X509_NAME_ENTRY_create_by_OBJ() create and return an X509_NAME_ENTRY_create_by_txt(), X509_NAME_ENTRY_create_by_OBJ(), X509_NAME_ENTRY_create_by_NID() and X509_NAME_ENTRY_set_data() @@ -60,15 +60,18 @@ X509_NAME_add_entry_by_txt(). So for example B<type> can be set to B<MBSTRING_ASC> but in the case of X509_set_data() the field name must be set first so the relevant field information can be looked up internally. -=head1 RETURN VALUES - =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_X509_NAME(3)|d2i_X509_NAME(3)>, -L<OBJ_nid2obj(3)|OBJ_nid2obj(3)> +L<ERR_get_error(3)>, L<d2i_X509_NAME(3)>, +L<OBJ_nid2obj(3)> + +=head1 COPYRIGHT -=head1 HISTORY +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. -TBA +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_NAME_add_entry_by_txt.pod b/deps/openssl/openssl/doc/crypto/X509_NAME_add_entry_by_txt.pod index 3bdc07fcfb..27e5baf856 100644 --- a/deps/openssl/openssl/doc/crypto/X509_NAME_add_entry_by_txt.pod +++ b/deps/openssl/openssl/doc/crypto/X509_NAME_add_entry_by_txt.pod @@ -11,11 +11,11 @@ X509_NAME_add_entry, X509_NAME_delete_entry - X509_NAME modification functions int X509_NAME_add_entry_by_txt(X509_NAME *name, const char *field, int type, const unsigned char *bytes, int len, int loc, int set); - int X509_NAME_add_entry_by_OBJ(X509_NAME *name, ASN1_OBJECT *obj, int type, unsigned char *bytes, int len, int loc, int set); + int X509_NAME_add_entry_by_OBJ(X509_NAME *name, const ASN1_OBJECT *obj, int type, const unsigned char *bytes, int len, int loc, int set); - int X509_NAME_add_entry_by_NID(X509_NAME *name, int nid, int type, unsigned char *bytes, int len, int loc, int set); + int X509_NAME_add_entry_by_NID(X509_NAME *name, int nid, int type, const unsigned char *bytes, int len, int loc, int set); - int X509_NAME_add_entry(X509_NAME *name,X509_NAME_ENTRY *ne, int loc, int set); + int X509_NAME_add_entry(X509_NAME *name, const X509_NAME_ENTRY *ne, int loc, int set); X509_NAME_ENTRY *X509_NAME_delete_entry(X509_NAME *name, int loc); @@ -61,7 +61,7 @@ to 0. This adds a new entry to the end of B<name> as a single valued RelativeDistinguishedName (RDN). B<loc> actually determines the index where the new entry is inserted: -if it is -1 it is appended. +if it is -1 it is appended. B<set> determines how the new type is added. If it is zero a new RDN is created. @@ -80,16 +80,16 @@ Create an B<X509_NAME> structure: X509_NAME *nm; nm = X509_NAME_new(); if (nm == NULL) - /* Some error */ - if (!X509_NAME_add_entry_by_txt(nm, "C", MBSTRING_ASC, - "UK", -1, -1, 0)) - /* Error */ + /* Some error */ + if (!X509_NAME_add_entry_by_txt(nm, "C", MBSTRING_ASC, + "UK", -1, -1, 0)) + /* Error */ if (!X509_NAME_add_entry_by_txt(nm, "O", MBSTRING_ASC, - "Disorganized Organization", -1, -1, 0)) - /* Error */ + "Disorganized Organization", -1, -1, 0)) + /* Error */ if (!X509_NAME_add_entry_by_txt(nm, "CN", MBSTRING_ASC, - "Joe Bloggs", -1, -1, 0)) - /* Error */ + "Joe Bloggs", -1, -1, 0)) + /* Error */ =head1 RETURN VALUES @@ -109,8 +109,15 @@ can result in invalid field types its use is strongly discouraged. =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_X509_NAME(3)|d2i_X509_NAME(3)> +L<ERR_get_error(3)>, L<d2i_X509_NAME(3)> -=head1 HISTORY +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_NAME_get0_der.pod b/deps/openssl/openssl/doc/crypto/X509_NAME_get0_der.pod new file mode 100644 index 0000000000..f91fd4d977 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/X509_NAME_get0_der.pod @@ -0,0 +1,40 @@ +=pod + +=head1 NAME + +X509_NAME_get0_der - get X509_NAME DER encoding + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + int X509_NAME_get0_der(X509_NAME *nm, const unsigned char **pder, + size_t *pderlen) + + +=head1 DESCRIPTION + +The function X509_NAME_get0_der() returns an internal pointer to the +encoding of an B<X509_NAME> structure in B<*pder> and consisting of +B<*pderlen> bytes. It is useful for applications that wish to examine +the encoding of an B<X509_NAME> structure without copying it. + +=head1 RETURN VALUES + +The function X509_NAME_get0_der() returns 1 for success and 0 if an error +occurred. + +=head1 SEE ALSO + +L<d2i_X509(3)> + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_NAME_get_index_by_NID.pod b/deps/openssl/openssl/doc/crypto/X509_NAME_get_index_by_NID.pod index cdec4b1d6d..2d6713ba29 100644 --- a/deps/openssl/openssl/doc/crypto/X509_NAME_get_index_by_NID.pod +++ b/deps/openssl/openssl/doc/crypto/X509_NAME_get_index_by_NID.pod @@ -10,14 +10,14 @@ X509_NAME lookup and enumeration functions #include <openssl/x509.h> - int X509_NAME_get_index_by_NID(X509_NAME *name,int nid,int lastpos); - int X509_NAME_get_index_by_OBJ(X509_NAME *name,ASN1_OBJECT *obj, int lastpos); + int X509_NAME_get_index_by_NID(X509_NAME *name, int nid, int lastpos); + int X509_NAME_get_index_by_OBJ(X509_NAME *name, const ASN1_OBJECT *obj, int lastpos); - int X509_NAME_entry_count(X509_NAME *name); - X509_NAME_ENTRY *X509_NAME_get_entry(X509_NAME *name, int loc); + int X509_NAME_entry_count(const X509_NAME *name); + X509_NAME_ENTRY *X509_NAME_get_entry(const X509_NAME *name, int loc); - int X509_NAME_get_text_by_NID(X509_NAME *name, int nid, char *buf,int len); - int X509_NAME_get_text_by_OBJ(X509_NAME *name, ASN1_OBJECT *obj, char *buf,int len); + int X509_NAME_get_text_by_NID(X509_NAME *name, int nid, char *buf, int len); + int X509_NAME_get_text_by_OBJ(X509_NAME *name, const ASN1_OBJECT *obj, char *buf, int len); =head1 DESCRIPTION @@ -44,7 +44,7 @@ B<obj>, if no such entry exists -1 is returned. At most B<len> bytes will be written and the text written to B<buf> will be null terminated. The length of the output string written is returned excluding the terminating null. If B<buf> is <NULL> then the amount -of space needed in B<buf> (excluding the final null) is returned. +of space needed in B<buf> (excluding the final null) is returned. =head1 NOTES @@ -52,7 +52,7 @@ X509_NAME_get_text_by_NID() and X509_NAME_get_text_by_OBJ() are legacy functions which have various limitations which make them of minimal use in practice. They can only find the first matching entry and will copy the contents of the field verbatim: this can -be highly confusing if the target is a muticharacter string type +be highly confusing if the target is a multicharacter string type like a BMPString or a UTF8String. For a more general solution X509_NAME_get_index_by_NID() or @@ -76,10 +76,10 @@ Process all entries: X509_NAME_ENTRY *e; for (i = 0; i < X509_NAME_entry_count(nm); i++) - { - e = X509_NAME_get_entry(nm, i); - /* Do something with e */ - } + { + e = X509_NAME_get_entry(nm, i); + /* Do something with e */ + } Process all commonName entries: @@ -87,13 +87,13 @@ Process all commonName entries: X509_NAME_ENTRY *e; for (;;) - { - lastpos = X509_NAME_get_index_by_NID(nm, NID_commonName, lastpos); - if (lastpos == -1) - break; - e = X509_NAME_get_entry(nm, lastpos); - /* Do something with e */ - } + { + lastpos = X509_NAME_get_index_by_NID(nm, NID_commonName, lastpos); + if (lastpos == -1) + break; + e = X509_NAME_get_entry(nm, lastpos); + /* Do something with e */ + } =head1 RETURN VALUES @@ -109,10 +109,15 @@ requested entry or B<NULL> if the index is invalid. =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_X509_NAME(3)|d2i_X509_NAME(3)> +L<ERR_get_error(3)>, L<d2i_X509_NAME(3)> -=head1 HISTORY +=head1 COPYRIGHT -TBA +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_NAME_print_ex.pod b/deps/openssl/openssl/doc/crypto/X509_NAME_print_ex.pod index d73520f35e..3e9caa889c 100644 --- a/deps/openssl/openssl/doc/crypto/X509_NAME_print_ex.pod +++ b/deps/openssl/openssl/doc/crypto/X509_NAME_print_ex.pod @@ -3,16 +3,16 @@ =head1 NAME X509_NAME_print_ex, X509_NAME_print_ex_fp, X509_NAME_print, -X509_NAME_oneline - X509_NAME printing routines. +X509_NAME_oneline - X509_NAME printing routines =head1 SYNOPSIS #include <openssl/x509.h> - int X509_NAME_print_ex(BIO *out, X509_NAME *nm, int indent, unsigned long flags); - int X509_NAME_print_ex_fp(FILE *fp, X509_NAME *nm, int indent, unsigned long flags); - char * X509_NAME_oneline(X509_NAME *a,char *buf,int size); - int X509_NAME_print(BIO *bp, X509_NAME *name, int obase); + int X509_NAME_print_ex(BIO *out, const X509_NAME *nm, int indent, unsigned long flags); + int X509_NAME_print_ex_fp(FILE *fp, const X509_NAME *nm, int indent, unsigned long flags); + char * X509_NAME_oneline(const X509_NAME *a, char *buf, int size); + int X509_NAME_print(BIO *bp, const X509_NAME *name, int obase); =head1 DESCRIPTION @@ -29,7 +29,7 @@ B<size> is ignored. Otherwise, at most B<size> bytes will be written, including the ending '\0', and B<buf> is returned. -X509_NAME_print() prints out B<name> to B<bp> indenting each line by B<obase> +X509_NAME_print() prints out B<name> to B<bp> indenting each line by B<obase> characters. Multiple lines are used if the output (including indent) exceeds 80 characters. @@ -42,7 +42,7 @@ applications. Although there are a large number of possible flags for most purposes B<XN_FLAG_ONELINE>, B<XN_FLAG_MULTILINE> or B<XN_FLAG_RFC2253> will suffice. -As noted on the L<ASN1_STRING_print_ex(3)|ASN1_STRING_print_ex(3)> manual page +As noted on the L<ASN1_STRING_print_ex(3)> manual page for UTF8 terminals the B<ASN1_STRFLGS_ESC_MSB> should be unset: so for example B<XN_FLAG_ONELINE & ~ASN1_STRFLGS_ESC_MSB> would be used. @@ -78,7 +78,7 @@ printed instead of the values. If B<XN_FLAG_FN_ALIGN> is set then field names are padded to 20 characters: this is only of use for multiline format. -Additionally all the options supported by ASN1_STRING_print_ex() can be used to +Additionally all the options supported by ASN1_STRING_print_ex() can be used to control how each field value is displayed. In addition a number options can be set for commonly used formats. @@ -98,10 +98,15 @@ B<XN_FLAG_COMPAT> uses a format identical to X509_NAME_print(): in fact it calls =head1 SEE ALSO -L<ASN1_STRING_print_ex(3)|ASN1_STRING_print_ex(3)> +L<ASN1_STRING_print_ex(3)> -=head1 HISTORY +=head1 COPYRIGHT -TBA +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_PUBKEY_new.pod b/deps/openssl/openssl/doc/crypto/X509_PUBKEY_new.pod new file mode 100644 index 0000000000..b13310513b --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/X509_PUBKEY_new.pod @@ -0,0 +1,120 @@ +=pod + +=head1 NAME + +X509_PUBKEY_new, X509_PUBKEY_free, X509_PUBKEY_set, X509_PUBKEY_get0, +X509_PUBKEY_get, d2i_PUBKEY, i2d_PUBKEY, d2i_PUBKEY_bio, d2i_PUBKEY_fp, +i2d_PUBKEY_fp, i2d_PUBKEY_bio, X509_PUBKEY_set0_param, +X509_PUBKEY_get0_param - SubjectPublicKeyInfo public key functions + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + X509_PUBKEY *X509_PUBKEY_new(void); + void X509_PUBKEY_free(X509_PUBKEY *a); + + int X509_PUBKEY_set(X509_PUBKEY **x, EVP_PKEY *pkey); + EVP_PKEY *X509_PUBKEY_get0(X509_PUBKEY *key); + 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); + + 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 X509_PUBKEY_set0_param(X509_PUBKEY *pub, ASN1_OBJECT *aobj, + int ptype, void *pval, + unsigned char *penc, int penclen); + int X509_PUBKEY_get0_param(ASN1_OBJECT **ppkalg, + const unsigned char **pk, int *ppklen, + X509_ALGOR **pa, X509_PUBKEY *pub); + +=head1 DESCRIPTION + +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_free() frees up B<X509_PUBKEY> structure B<a>. If B<a> is NULL +nothing is done. + +X509_PUBKEY_set() sets the public key in B<*x> to the public key contained +in the B<EVP_PKEY> structure B<pkey>. If B<*x> is not NULL any existing +public key structure will be freed. + +X509_PUBKEY_get0() returns the public key contained in B<key>. The returned +value is an internal pointer which B<MUST NOT> be freed after use. + +X509_PUBKEY_get() is similar to X509_PUBKEY_get0() except the reference +count on the returned key is incremented so it B<MUST> be freed using +EVP_PKEY_free() after use. + +d2i_PUBKEY() and i2d_PUBKEY() decode and encode an B<EVP_PKEY> structure +using B<SubjectPublicKeyInfo> format. They otherwise follow the conventions of +other ASN.1 functions such as d2i_X509(). + +d2i_PUBKEY_bio(), d2i_PUBKEY_fp(), i2d_PUBKEY_bio() and i2d_PUBKEY_fp() are +similar to d2i_PUBKEY() and i2d_PUBKEY() except they decode or encode using a +B<BIO> or B<FILE> pointer. + +X509_PUBKEY_set0_param() sets the public key parameters of B<pub>. The +OID associated with the algorithm is set to B<aobj>. The type of the +algorithm parameters is set to B<type> using the structure B<pval>. +The encoding of the public key itself is set to the B<penclen> +bytes contained in buffer B<penc>. On success ownership of all the supplied +parameters is passed to B<pub> so they must not be freed after the +call. + +X509_PUBKEY_get0_param() retrieves the public key parameters from B<pub>, +B<*ppkalg> is set to the associated OID and the encoding consists of +B<*ppklen> bytes at B<*pk>, B<*pa> is set to the associated +AlgorithmIdentifier for the public key. If the value of any of these +parameters is not required it can be set to B<NULL>. All of the +retrieved pointers are internal and must not be freed after the +call. + +=head1 NOTES + +The B<X509_PUBKEY> functions can be used to encode and decode public keys +in a standard format. + +In many cases applications will not call the B<X509_PUBKEY> functions +directly: they will instead call wrapper functions such as X509_get0_pubkey(). + +=head1 RETURN VALUES + +If the allocation fails, X509_PUBKEY_new() returns B<NULL> and sets an error +code that can be obtained by L<ERR_get_error(3)>. + +Otherwise it returns a pointer to the newly allocated structure. + +X509_PUBKEY_free() does not return a value. + +X509_PUBKEY_get0() and X509_PUBKEY_get() return a pointer to an B<EVP_PKEY> +structure or B<NULL> if an error occurs. + +X509_PUBKEY_set(), X509_PUBKEY_set0_param() and X509_PUBKEY_get0_param() +return 1 for success and 0 if an error occurred. + +=head1 SEE ALSO + +L<d2i_X509(3)>, +L<ERR_get_error(3)>, +L<X509_get_pubkey(3)>, + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_SIG_get0.pod b/deps/openssl/openssl/doc/crypto/X509_SIG_get0.pod new file mode 100644 index 0000000000..d24eadcdf9 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/X509_SIG_get0.pod @@ -0,0 +1,36 @@ +=pod + +=head1 NAME + +X509_SIG_get0, X509_SIG_getm - DigestInfo functions + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + void X509_SIG_get0(const X509_SIG *sig, const X509_ALGOR **palg, + const ASN1_OCTET_STRING **pdigest); + void X509_SIG_getm(X509_SIG *sig, X509_ALGOR **palg, + ASN1_OCTET_STRING **pdigest, + +=head1 DESCRIPTION + +X509_SIG_get0() returns pointers to the algorithm identifier and digest +value in B<sig>. X509_SIG_getm() is identical to X509_SIG_get0() +except the pointers returned are not constant and can be modified: +for example to initialise them. + +=head1 SEE ALSO + +L<d2i_X509(3)> + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_STORE_CTX_get_error.pod b/deps/openssl/openssl/doc/crypto/X509_STORE_CTX_get_error.pod index be00ff1fec..105e051a1d 100644 --- a/deps/openssl/openssl/doc/crypto/X509_STORE_CTX_get_error.pod +++ b/deps/openssl/openssl/doc/crypto/X509_STORE_CTX_get_error.pod @@ -2,17 +2,24 @@ =head1 NAME -X509_STORE_CTX_get_error, X509_STORE_CTX_set_error, X509_STORE_CTX_get_error_depth, X509_STORE_CTX_get_current_cert, X509_STORE_CTX_get1_chain, X509_verify_cert_error_string - get or set certificate verification status information +X509_STORE_CTX_get_error, X509_STORE_CTX_set_error, +X509_STORE_CTX_get_error_depth, X509_STORE_CTX_set_error_depth, +X509_STORE_CTX_get_current_cert, X509_STORE_CTX_set_current_cert, +X509_STORE_CTX_get0_cert, X509_STORE_CTX_get1_chain, +X509_verify_cert_error_string - get or set certificate verification status +information =head1 SYNOPSIS #include <openssl/x509.h> - #include <openssl/x509_vfy.h> - int X509_STORE_CTX_get_error(X509_STORE_CTX *ctx); - void X509_STORE_CTX_set_error(X509_STORE_CTX *ctx,int s); - int X509_STORE_CTX_get_error_depth(X509_STORE_CTX *ctx); - X509 * X509_STORE_CTX_get_current_cert(X509_STORE_CTX *ctx); + int X509_STORE_CTX_get_error(X509_STORE_CTX *ctx); + void X509_STORE_CTX_set_error(X509_STORE_CTX *ctx, int s); + int X509_STORE_CTX_get_error_depth(X509_STORE_CTX *ctx); + void X509_STORE_CTX_set_error_depth(X509_STORE_CTX *ctx, int depth); + X509 *X509_STORE_CTX_get_current_cert(X509_STORE_CTX *ctx); + void X509_STORE_CTX_set_current_cert(X509_STORE_CTX *ctx, X509 *x); + X509 *X509_STORE_CTX_get0_cert(X509_STORE_CTX *ctx); STACK_OF(X509) *X509_STORE_CTX_get1_chain(X509_STORE_CTX *ctx); @@ -35,9 +42,28 @@ non-negative integer representing where in the certificate chain the error occurred. If it is zero it occurred in the end entity certificate, one if it is the certificate which signed the end entity certificate and so on. +X509_STORE_CTX_set_error_depth() sets the error B<depth>. +This can be used in combination with X509_STORE_CTX_set_error() to set the +depth at which an error condition was detected. + X509_STORE_CTX_get_current_cert() returns the certificate in B<ctx> which caused the error or B<NULL> if no certificate is relevant. +X509_STORE_CTX_set_current_cert() sets the certificate B<x> in B<ctx> which +caused the error. +This value is not intended to remain valid for very long, and remains owned by +the caller. +It may be examined by a verification callback invoked to handle each error +encountered during chain verification and is no longer required after such a +callback. +If a callback wishes the save the certificate for use after it returns, it +needs to increment its reference count via L<X509_up_ref(3)>. +Once such a I<saved> certificate is no longer needed it can be freed with +L<X509_free(3)>. + +X509_STORE_CTX_get0_cert() retrieves an internal pointer to the +certificate being verified by the B<ctx>. + X509_STORE_CTX_get1_chain() returns a complete validate chain if a previous call to X509_verify_cert() is successful. If the call to X509_verify_cert() is B<not> successful the returned chain may be incomplete or invalid. The @@ -55,7 +81,7 @@ X509_STORE_CTX_get_error() returns B<X509_V_OK> or an error code. X509_STORE_CTX_get_error_depth() returns a non-negative error depth. -X509_STORE_CTX_get_current_cert() returns the cerificate which caused the +X509_STORE_CTX_get_current_cert() returns the certificate which caused the error or B<NULL> if no certificate is relevant to the error. X509_verify_cert_error_string() returns a human readable error string for @@ -177,7 +203,7 @@ consistent with the supplied purpose. =item B<X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded> -the basicConstraints pathlength parameter has been exceeded. +the basicConstraints path-length parameter has been exceeded. =item B<X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose> @@ -296,10 +322,17 @@ thread safe but will never happen unless an invalid code is passed. =head1 SEE ALSO -L<X509_verify_cert(3)|X509_verify_cert(3)> +L<X509_verify_cert(3)>, +L<X509_up_ref(3)>, +L<X509_free(3)>. + +=head1 COPYRIGHT -=head1 HISTORY +Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved. -TBA +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_STORE_CTX_get_ex_new_index.pod b/deps/openssl/openssl/doc/crypto/X509_STORE_CTX_get_ex_new_index.pod deleted file mode 100644 index 8a9243d756..0000000000 --- a/deps/openssl/openssl/doc/crypto/X509_STORE_CTX_get_ex_new_index.pod +++ /dev/null @@ -1,41 +0,0 @@ -=pod - -=head1 NAME - -X509_STORE_CTX_get_ex_new_index, X509_STORE_CTX_set_ex_data, X509_STORE_CTX_get_ex_data - add application specific data to X509_STORE_CTX structures - -=head1 SYNOPSIS - - #include <openssl/x509_vfy.h> - - int X509_STORE_CTX_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - - int X509_STORE_CTX_set_ex_data(X509_STORE_CTX *d, int idx, void *arg); - - void *X509_STORE_CTX_get_ex_data(X509_STORE_CTX *d, int idx); - -=head1 DESCRIPTION - -These functions handle application specific data in X509_STORE_CTX structures. -Their usage is identical to that of RSA_get_ex_new_index(), RSA_set_ex_data() -and RSA_get_ex_data() as described in L<RSA_get_ex_new_index(3)>. - -=head1 NOTES - -This mechanism is used internally by the B<ssl> library to store the B<SSL> -structure associated with a verification operation in an B<X509_STORE_CTX> -structure. - -=head1 SEE ALSO - -L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)> - -=head1 HISTORY - -X509_STORE_CTX_get_ex_new_index(), X509_STORE_CTX_set_ex_data() and -X509_STORE_CTX_get_ex_data() are available since OpenSSL 0.9.5. - -=cut diff --git a/deps/openssl/openssl/doc/crypto/X509_STORE_CTX_new.pod b/deps/openssl/openssl/doc/crypto/X509_STORE_CTX_new.pod index 1aee117268..2828ed75d2 100644 --- a/deps/openssl/openssl/doc/crypto/X509_STORE_CTX_new.pod +++ b/deps/openssl/openssl/doc/crypto/X509_STORE_CTX_new.pod @@ -2,7 +2,17 @@ =head1 NAME -X509_STORE_CTX_new, X509_STORE_CTX_cleanup, X509_STORE_CTX_free, X509_STORE_CTX_init, X509_STORE_CTX_trusted_stack, X509_STORE_CTX_set_cert, X509_STORE_CTX_set_chain, X509_STORE_CTX_set0_crls, X509_STORE_CTX_get0_param, X509_STORE_CTX_set0_param, X509_STORE_CTX_set_default - X509_STORE_CTX initialisation +X509_STORE_CTX_new, X509_STORE_CTX_cleanup, X509_STORE_CTX_free, +X509_STORE_CTX_init, X509_STORE_CTX_set0_trusted_stack, X509_STORE_CTX_set_cert, +X509_STORE_CTX_set0_crls, +X509_STORE_CTX_get0_chain, X509_STORE_CTX_set0_verified_chain, +X509_STORE_CTX_get0_param, X509_STORE_CTX_set0_param, +X509_STORE_CTX_get0_untrusted, X509_STORE_CTX_set0_untrusted, +X509_STORE_CTX_get_num_untrusted, +X509_STORE_CTX_set_default, +X509_STORE_CTX_set_verify, +X509_STORE_CTX_verify_fn +- X509_STORE_CTX initialisation =head1 SYNOPSIS @@ -13,18 +23,27 @@ X509_STORE_CTX_new, X509_STORE_CTX_cleanup, X509_STORE_CTX_free, X509_STORE_CTX_ void X509_STORE_CTX_free(X509_STORE_CTX *ctx); int X509_STORE_CTX_init(X509_STORE_CTX *ctx, X509_STORE *store, - X509 *x509, STACK_OF(X509) *chain); + X509 *x509, STACK_OF(X509) *chain); - void X509_STORE_CTX_trusted_stack(X509_STORE_CTX *ctx, STACK_OF(X509) *sk); + void X509_STORE_CTX_set0_trusted_stack(X509_STORE_CTX *ctx, STACK_OF(X509) *sk); - void X509_STORE_CTX_set_cert(X509_STORE_CTX *ctx,X509 *x); - void X509_STORE_CTX_set_chain(X509_STORE_CTX *ctx,STACK_OF(X509) *sk); - void X509_STORE_CTX_set0_crls(X509_STORE_CTX *ctx, STACK_OF(X509_CRL) *sk); + void X509_STORE_CTX_set_cert(X509_STORE_CTX *ctx, X509 *x); + STACK_OF(X509) *X509_STORE_CTX_get0_chain(X609_STORE_CTX *ctx); + void X509_STORE_CTX_set0_verified_chain(X509_STORE_CTX *ctx, STACK_OF(X509) *chain); + void X509_STORE_CTX_set0_crls(X509_STORE_CTX *ctx, STACK_OF(X509_CRL) *sk); X509_VERIFY_PARAM *X509_STORE_CTX_get0_param(X509_STORE_CTX *ctx); void X509_STORE_CTX_set0_param(X509_STORE_CTX *ctx, X509_VERIFY_PARAM *param); int X509_STORE_CTX_set_default(X509_STORE_CTX *ctx, const char *name); + STACK_OF(X509)* X509_STORE_CTX_get0_untrusted(X509_STORE_CTX *ctx); + void X509_STORE_CTX_set0_untrusted(X509_STORE_CTX *ctx, STACK_OF(X509) *sk); + + int X509_STORE_CTX_get_num_untrusted(X509_STORE_CTX *ctx); + + typedef int (*X509_STORE_CTX_verify_fn)(X509_STORE_CTX *); + void X509_STORE_CTX_set_verify(X509_STORE_CTX *ctx, X509_STORE_CTX_verify_fn verify); + =head1 DESCRIPTION These functions initialise an B<X509_STORE_CTX> structure for subsequent use @@ -37,6 +56,7 @@ The context can then be reused with an new call to X509_STORE_CTX_init(). X509_STORE_CTX_free() completely frees up B<ctx>. After this call B<ctx> is no longer valid. +If B<ctx> is NULL nothing is done. X509_STORE_CTX_init() sets up B<ctx> for a subsequent verification operation. It must be called before each call to X509_verify_cert(), i.e. a B<ctx> is only @@ -49,15 +69,19 @@ certificates (which will be untrusted but may be used to build the chain) in B<chain>. Any or all of the B<store>, B<x509> and B<chain> parameters can be B<NULL>. -X509_STORE_CTX_trusted_stack() sets the set of trusted certificates of B<ctx> -to B<sk>. This is an alternative way of specifying trusted certificates +X509_STORE_CTX_set0_trusted_stack() sets the set of trusted certificates of +B<ctx> to B<sk>. This is an alternative way of specifying trusted certificates instead of using an B<X509_STORE>. -X509_STORE_CTX_set_cert() sets the certificate to be vertified in B<ctx> to +X509_STORE_CTX_set_cert() sets the certificate to be verified in B<ctx> to B<x>. -X509_STORE_CTX_set_chain() sets the additional certificate chain used by B<ctx> -to B<sk>. +X509_STORE_CTX_set0_verified_chain() sets the validated chain used +by B<ctx> to be B<chain>. +Ownership of the chain is transferred to B<ctx> and should not be +free'd by the caller. +X509_STORE_CTX_get0_chain() returns a the internal pointer used by the +B<ctx> that contains the validated chain. X509_STORE_CTX_set0_crls() sets a set of CRLs to use to aid certificate verification to B<sk>. These CRLs will only be used if CRL verification is @@ -65,32 +89,41 @@ enabled in the associated B<X509_VERIFY_PARAM> structure. This might be used where additional "useful" CRLs are supplied as part of a protocol, for example in a PKCS#7 structure. -X509_VERIFY_PARAM *X509_STORE_CTX_get0_param() retrieves an intenal pointer +X509_STORE_CTX_get0_param() retrieves an internal pointer to the verification parameters associated with B<ctx>. -X509_STORE_CTX_set0_param() sets the intenal verification parameter pointer +X509_STORE_CTX_get0_untrusted() retrieves an internal pointer to the +stack of untrusted certificates associated with B<ctx>. + +X509_STORE_CTX_set0_untrusted() sets the internal point to the stack +of untrusted certificates associated with B<ctx> to B<sk>. + +X509_STORE_CTX_set0_param() sets the internal verification parameter pointer to B<param>. After this call B<param> should not be used. X509_STORE_CTX_set_default() looks up and sets the default verification method to B<name>. This uses the function X509_VERIFY_PARAM_lookup() to find an appropriate set of parameters from B<name>. -=head1 NOTES +X509_STORE_CTX_get_num_untrusted() returns the number of untrusted certificates +that were used in building the chain following a call to X509_verify_cert(). -The certificates and CRLs in a store are used internally and should B<not> -be freed up until after the associated B<X509_STORE_CTX> is freed. Legacy -applications might implicitly use an B<X509_STORE_CTX> like this: +X509_STORE_CTX_set_verify() provides the capability for overriding the default +verify function. This function is responsible for verifying chain signatures and +expiration times. - X509_STORE_CTX ctx; - X509_STORE_CTX_init(&ctx, store, cert, chain); +A verify function is defined as an X509_STORE_CTX_verify type which has the +following signature: -this is B<not> recommended in new applications they should instead do: + int (*verify)(X509_STORE_CTX *); - X509_STORE_CTX *ctx; - ctx = X509_STORE_CTX_new(); - if (ctx == NULL) - /* Bad error */ - X509_STORE_CTX_init(ctx, store, cert, chain); +This function should receive the current X509_STORE_CTX as a parameter and +return 1 on success or 0 on failure. + +=head1 NOTES + +The certificates and CRLs in a store are used internally and should B<not> +be freed up until after the associated B<X509_STORE_CTX> is freed. =head1 BUGS @@ -108,20 +141,34 @@ X509_STORE_CTX_init() returns 1 for success or 0 if an error occurred. X509_STORE_CTX_get0_param() returns a pointer to an B<X509_VERIFY_PARAM> structure or B<NULL> if an error occurred. -X509_STORE_CTX_cleanup(), X509_STORE_CTX_free(), X509_STORE_CTX_trusted_stack(), -X509_STORE_CTX_set_cert(), X509_STORE_CTX_set_chain(), +X509_STORE_CTX_cleanup(), X509_STORE_CTX_free(), +X509_STORE_CTX_set0_trusted_stack(), +X509_STORE_CTX_set_cert(), X509_STORE_CTX_set0_crls() and X509_STORE_CTX_set0_param() do not return values. X509_STORE_CTX_set_default() returns 1 for success or 0 if an error occurred. +X509_STORE_CTX_get_num_untrusted() returns the number of untrusted certificates +used. + =head1 SEE ALSO -L<X509_verify_cert(3)|X509_verify_cert(3)> -L<X509_VERIFY_PARAM_set_flags(3)|X509_VERIFY_PARAM_set_flags(3)> +L<X509_verify_cert(3)> +L<X509_VERIFY_PARAM_set_flags(3)> =head1 HISTORY X509_STORE_CTX_set0_crls() was first added to OpenSSL 1.0.0 +X509_STORE_CTX_get_num_untrusted() was first added to OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_STORE_CTX_set_verify_cb.pod b/deps/openssl/openssl/doc/crypto/X509_STORE_CTX_set_verify_cb.pod index b9787a6ca6..3be256dc74 100644 --- a/deps/openssl/openssl/doc/crypto/X509_STORE_CTX_set_verify_cb.pod +++ b/deps/openssl/openssl/doc/crypto/X509_STORE_CTX_set_verify_cb.pod @@ -2,14 +2,42 @@ =head1 NAME -X509_STORE_CTX_set_verify_cb - set verification callback +X509_STORE_CTX_get_cleanup, +X509_STORE_CTX_get_lookup_crls, +X509_STORE_CTX_get_lookup_certs, +X509_STORE_CTX_get_check_policy, +X509_STORE_CTX_get_cert_crl, +X509_STORE_CTX_get_check_crl, +X509_STORE_CTX_get_get_crl, +X509_STORE_CTX_get_check_revocation, +X509_STORE_CTX_get_check_issued, +X509_STORE_CTX_get_get_issuer, +X509_STORE_CTX_get_verify_cb, +X509_STORE_CTX_set_verify_cb, +X509_STORE_CTX_verify_cb +- get and set verification callback =head1 SYNOPSIS #include <openssl/x509_vfy.h> + typedef int (*X509_STORE_CTX_verify_cb)(int, X509_STORE_CTX *); + + X509_STORE_CTX_verify_cb X509_STORE_CTX_get_verify_cb(X509_STORE_CTX *ctx); + void X509_STORE_CTX_set_verify_cb(X509_STORE_CTX *ctx, - int (*verify_cb)(int ok, X509_STORE_CTX *ctx)); + X509_STORE_CTX_verify_cb verify_cb); + + X509_STORE_CTX_get_issuer_fn X509_STORE_CTX_get_get_issuer(X509_STORE_CTX *ctx); + X509_STORE_CTX_check_issued_fn X509_STORE_CTX_get_check_issued(X509_STORE_CTX *ctx); + X509_STORE_CTX_check_revocation_fn X509_STORE_CTX_get_check_revocation(X509_STORE_CTX *ctx); + X509_STORE_CTX_get_crl_fn X509_STORE_CTX_get_get_crl(X509_STORE_CTX *ctx); + X509_STORE_CTX_check_crl_fn X509_STORE_CTX_get_check_crl(X509_STORE_CTX *ctx); + X509_STORE_CTX_cert_crl_fn X509_STORE_CTX_get_cert_crl(X509_STORE_CTX *ctx); + X509_STORE_CTX_check_policy_fn X509_STORE_CTX_get_check_policy(X509_STORE_CTX *ctx); + X509_STORE_CTX_lookup_certs_fn X509_STORE_CTX_get_lookup_certs(X509_STORE_CTX *ctx); + X509_STORE_CTX_lookup_crls_fn X509_STORE_CTX_get_lookup_crls(X509_STORE_CTX *ctx); + X509_STORE_CTX_cleanup_fn X509_STORE_CTX_get_cleanup(X509_STORE_CTX *ctx); =head1 DESCRIPTION @@ -24,7 +52,7 @@ However a verification callback is B<not> essential and the default operation is often sufficient. The B<ok> parameter to the callback indicates the value the callback should -return to retain the default behaviour. If it is zero then and error condition +return to retain the default behaviour. If it is zero then an error condition is indicated. If it is 1 then no error occurred. If the flag B<X509_V_FLAG_NOTIFY_POLICY> is set then B<ok> is set to 2 to indicate the policy checking is complete. @@ -35,6 +63,19 @@ structure and receive additional information about the error, for example by calling X509_STORE_CTX_get_current_cert(). Additional application data can be passed to the callback via the B<ex_data> mechanism. +X509_STORE_CTX_get_verify_cb() returns the value of the current callback +for the specific B<ctx>. + +X509_STORE_CTX_get_get_issuer(), +X509_STORE_CTX_get_check_issued(), X509_STORE_CTX_get_check_revocation(), +X509_STORE_CTX_get_get_crl(), X509_STORE_CTX_get_check_crl(), +X509_STORE_CTX_get_cert_crl(), X509_STORE_CTX_get_check_policy(), +X509_STORE_CTX_get_lookup_certs(), X509_STORE_CTX_get_lookup_crls() +and X509_STORE_CTX_get_cleanup() return the function pointers cached +from the corresponding B<X509_STORE>, please see +L<X509_STORE_set_verify(3)> for more information. + + =head1 WARNING In general a verification callback should B<NOT> unconditionally return 1 in @@ -60,102 +101,115 @@ X509_STORE_CTX_set_verify_cb() does not return a value. Default callback operation: int verify_callback(int ok, X509_STORE_CTX *ctx) - { - return ok; - } + { + return ok; + } Simple example, suppose a certificate in the chain is expired and we wish to continue after this error: int verify_callback(int ok, X509_STORE_CTX *ctx) - { - /* Tolerate certificate expiration */ - if (X509_STORE_CTX_get_error(ctx) == X509_V_ERR_CERT_HAS_EXPIRED) - return 1; - /* Otherwise don't override */ - return ok; - } + { + /* Tolerate certificate expiration */ + if (X509_STORE_CTX_get_error(ctx) == X509_V_ERR_CERT_HAS_EXPIRED) + return 1; + /* Otherwise don't override */ + return ok; + } More complex example, we don't wish to continue after B<any> certificate has expired just one specific case: int verify_callback(int ok, X509_STORE_CTX *ctx) - { - int err = X509_STORE_CTX_get_error(ctx); - X509 *err_cert = X509_STORE_CTX_get_current_cert(ctx); - if (err == X509_V_ERR_CERT_HAS_EXPIRED) - { - if (check_is_acceptable_expired_cert(err_cert) - return 1; - } - return ok; - } + { + int err = X509_STORE_CTX_get_error(ctx); + X509 *err_cert = X509_STORE_CTX_get_current_cert(ctx); + if (err == X509_V_ERR_CERT_HAS_EXPIRED) + { + if (check_is_acceptable_expired_cert(err_cert) + return 1; + } + return ok; + } Full featured logging callback. In this case the B<bio_err> is assumed to be a global logging B<BIO>, an alternative would to store a BIO in B<ctx> using B<ex_data>. - + int verify_callback(int ok, X509_STORE_CTX *ctx) - { - X509 *err_cert; - int err,depth; - - err_cert = X509_STORE_CTX_get_current_cert(ctx); - err = X509_STORE_CTX_get_error(ctx); - depth = X509_STORE_CTX_get_error_depth(ctx); - - BIO_printf(bio_err,"depth=%d ",depth); - if (err_cert) - { - X509_NAME_print_ex(bio_err, X509_get_subject_name(err_cert), - 0, XN_FLAG_ONELINE); - BIO_puts(bio_err, "\n"); - } - else - BIO_puts(bio_err, "<no cert>\n"); - if (!ok) - BIO_printf(bio_err,"verify error:num=%d:%s\n",err, - X509_verify_cert_error_string(err)); - switch (err) - { - case X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: - BIO_puts(bio_err,"issuer= "); - X509_NAME_print_ex(bio_err, X509_get_issuer_name(err_cert), - 0, XN_FLAG_ONELINE); - BIO_puts(bio_err, "\n"); - break; - case X509_V_ERR_CERT_NOT_YET_VALID: - case X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: - BIO_printf(bio_err,"notBefore="); - ASN1_TIME_print(bio_err,X509_get_notBefore(err_cert)); - BIO_printf(bio_err,"\n"); - break; - case X509_V_ERR_CERT_HAS_EXPIRED: - case X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: - BIO_printf(bio_err,"notAfter="); - ASN1_TIME_print(bio_err,X509_get_notAfter(err_cert)); - BIO_printf(bio_err,"\n"); - break; - case X509_V_ERR_NO_EXPLICIT_POLICY: - policies_print(bio_err, ctx); - break; - } - if (err == X509_V_OK && ok == 2) - /* print out policies */ - - BIO_printf(bio_err,"verify return:%d\n",ok); - return(ok); - } + { + X509 *err_cert; + int err, depth; + + err_cert = X509_STORE_CTX_get_current_cert(ctx); + err = X509_STORE_CTX_get_error(ctx); + depth = X509_STORE_CTX_get_error_depth(ctx); + + BIO_printf(bio_err, "depth=%d ", depth); + if (err_cert) + { + X509_NAME_print_ex(bio_err, X509_get_subject_name(err_cert), + 0, XN_FLAG_ONELINE); + BIO_puts(bio_err, "\n"); + } + else + BIO_puts(bio_err, "<no cert>\n"); + if (!ok) + BIO_printf(bio_err, "verify error:num=%d:%s\n", err, + X509_verify_cert_error_string(err)); + switch (err) + { + case X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: + BIO_puts(bio_err, "issuer= "); + X509_NAME_print_ex(bio_err, X509_get_issuer_name(err_cert), + 0, XN_FLAG_ONELINE); + BIO_puts(bio_err, "\n"); + break; + case X509_V_ERR_CERT_NOT_YET_VALID: + case X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: + BIO_printf(bio_err, "notBefore="); + ASN1_TIME_print(bio_err, X509_get_notBefore(err_cert)); + BIO_printf(bio_err, "\n"); + break; + case X509_V_ERR_CERT_HAS_EXPIRED: + case X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: + BIO_printf(bio_err, "notAfter="); + ASN1_TIME_print(bio_err, X509_get_notAfter(err_cert)); + BIO_printf(bio_err, "\n"); + break; + case X509_V_ERR_NO_EXPLICIT_POLICY: + policies_print(bio_err, ctx); + break; + } + if (err == X509_V_OK && ok == 2) + /* print out policies */ + + BIO_printf(bio_err, "verify return:%d\n", ok); + return(ok); + } =head1 SEE ALSO -L<X509_STORE_CTX_get_error(3)|X509_STORE_CTX_get_error(3)> -L<X509_STORE_set_verify_cb_func(3)|X509_STORE_set_verify_cb_func(3)> -L<X509_STORE_CTX_get_ex_new_index(3)|X509_STORE_CTX_get_ex_new_index(3)> +L<X509_STORE_CTX_get_error(3)> +L<X509_STORE_set_verify_cb_func(3)> +L<X509_STORE_CTX_get_ex_new_index(3)> =head1 HISTORY -X509_STORE_CTX_set_verify_cb() is available in all versions of SSLeay and -OpenSSL. +X509_STORE_CTX_get_get_issuer(), +X509_STORE_CTX_get_check_issued(), X509_STORE_CTX_get_check_revocation(), +X509_STORE_CTX_get_get_crl(), X509_STORE_CTX_get_check_crl(), +X509_STORE_CTX_get_cert_crl(), X509_STORE_CTX_get_check_policy(), +X509_STORE_CTX_get_lookup_certs(), X509_STORE_CTX_get_lookup_crls() +and X509_STORE_CTX_get_cleanup() were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_STORE_get0_param.pod b/deps/openssl/openssl/doc/crypto/X509_STORE_get0_param.pod new file mode 100644 index 0000000000..0aed725ad6 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/X509_STORE_get0_param.pod @@ -0,0 +1,57 @@ +=pod + +=head1 NAME + +X509_STORE_get0_param, X509_STORE_set1_param, +X509_STORE_get0_objects - X509_STORE setter and getter functions + +=head1 SYNOPSIS + + #include <openssl/x509_vfy.h> + + X509_VERIFY_PARAM *X509_STORE_get0_param(X509_STORE *ctx); + int X509_STORE_set1_param(X509_STORE *ctx, X509_VERIFY_PARAM *pm); + STACK_OF(X509_OBJECT) *X509_STORE_get0_objects(X509_STORE *ctx); + +=head1 DESCRIPTION + +X509_STORE_set1_param() sets the verification parameters +to B<pm> for B<ctx>. + +X509_STORE_get0_param() retrieves an internal pointer to the verification +parameters for B<ctx>. The returned pointer must not be freed by the +calling application + +X509_STORE_get0_objects() retrieve an internal pointer to the store's +X509 object cache. The cache contains B<X509> and B<X509_CRL> objects. The +returned pointer must not be freed by the calling application. + + +=head1 RETURN VALUES + +X509_STORE_get0_param() returns a pointer to an +B<X509_VERIFY_PARAM> structure. + +X509_STORE_set1_param() returns 1 for success and 0 for failure. + +X509_STORE_get0_objects() returns a pointer to a stack of B<X509_OBJECT>. + +=head1 SEE ALSO + +L<X509_STORE_new(3)> + +=head1 HISTORY + +B<X509_STORE_get0_param> and B<X509_STORE_get0_objects> were added in +OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_STORE_new.pod b/deps/openssl/openssl/doc/crypto/X509_STORE_new.pod new file mode 100644 index 0000000000..f7a5c81416 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/X509_STORE_new.pod @@ -0,0 +1,58 @@ +=pod + +=head1 NAME + +X509_STORE_new, X509_STORE_up_ref, X509_STORE_free, X509_STORE_lock, +X509_STORE_unlock - X509_STORE allocation, freeing and locking functions + +=head1 SYNOPSIS + + #include <openssl/x509_vfy.h> + + X509_STORE *X509_STORE_new(void); + void X509_STORE_free(X509_STORE *v); + int X509_STORE_lock(X509_STORE *v); + int X509_STORE_unlock(X509_STORE *v); + int X509_STORE_up_ref(X509_STORE *v); + +=head1 DESCRIPTION + +The X509_STORE_new() function returns a new X509_STORE. + +X509_STORE_up_ref() increments the reference count associated with the +X509_STORE object. + +X509_STORE_lock() locks the store from modification by other threads, +X509_STORE_unlock() locks it. + +X509_STORE_free() frees up a single X509_STORE object. + +=head1 RETURN VALUES + +X509_STORE_new() returns a newly created X509_STORE or NULL if the call fails. + +X509_STORE_up_ref(), X509_STORE_lock() and X509_STORE_unlock() return +1 for success and 0 for failure. + +X509_STORE_free() does not return values. + +=head1 SEE ALSO + +L<X509_STORE_set_verify_cb_func(3)> +L<X509_STORE_get0_param(3)> + +=head1 HISTORY + +The X509_STORE_up_ref(), X509_STORE_lock() and X509_STORE_unlock() +functions were added in OpenSSL 1.1.0 + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_STORE_set_verify_cb_func.pod b/deps/openssl/openssl/doc/crypto/X509_STORE_set_verify_cb_func.pod index 29e3bbe3bc..12a4646741 100644 --- a/deps/openssl/openssl/doc/crypto/X509_STORE_set_verify_cb_func.pod +++ b/deps/openssl/openssl/doc/crypto/X509_STORE_set_verify_cb_func.pod @@ -2,53 +2,264 @@ =head1 NAME -X509_STORE_set_verify_cb_func, X509_STORE_set_verify_cb - set verification callback +X509_STORE_set_lookup_crls_cb, +X509_STORE_set_verify_func, +X509_STORE_get_cleanup, +X509_STORE_set_cleanup, +X509_STORE_get_lookup_crls, +X509_STORE_set_lookup_crls, +X509_STORE_get_lookup_certs, +X509_STORE_set_lookup_certs, +X509_STORE_get_check_policy, +X509_STORE_set_check_policy, +X509_STORE_get_cert_crl, +X509_STORE_set_cert_crl, +X509_STORE_get_check_crl, +X509_STORE_set_check_crl, +X509_STORE_get_get_crl, +X509_STORE_set_get_crl, +X509_STORE_get_check_revocation, +X509_STORE_set_check_revocation, +X509_STORE_get_check_issued, +X509_STORE_set_check_issued, +X509_STORE_get_get_issuer, +X509_STORE_set_get_issuer, +X509_STORE_CTX_get_verify, +X509_STORE_set_verify, +X509_STORE_get_verify_cb, +X509_STORE_set_verify_cb_func, X509_STORE_set_verify_cb, +X509_STORE_CTX_cert_crl_fn, X509_STORE_CTX_check_crl_fn, +X509_STORE_CTX_check_issued_fn, X509_STORE_CTX_check_policy_fn, +X509_STORE_CTX_check_revocation_fn, X509_STORE_CTX_cleanup_fn, +X509_STORE_CTX_get_crl_fn, X509_STORE_CTX_get_issuer_fn, +X509_STORE_CTX_lookup_certs_fn, X509_STORE_CTX_lookup_crls_fn +- set verification callback =head1 SYNOPSIS #include <openssl/x509_vfy.h> - void X509_STORE_set_verify_cb(X509_STORE *st, - int (*verify_cb)(int ok, X509_STORE_CTX *ctx)); + typedef int (*X509_STORE_CTX_get_issuer_fn)(X509 **issuer, + X509_STORE_CTX *ctx, X509 *x); + typedef int (*X509_STORE_CTX_check_issued_fn)(X509_STORE_CTX *ctx, + X509 *x, X509 *issuer); + typedef int (*X509_STORE_CTX_check_revocation_fn)(X509_STORE_CTX *ctx); + typedef int (*X509_STORE_CTX_get_crl_fn)(X509_STORE_CTX *ctx, + X509_CRL **crl, X509 *x); + typedef int (*X509_STORE_CTX_check_crl_fn)(X509_STORE_CTX *ctx, X509_CRL *crl); + typedef int (*X509_STORE_CTX_cert_crl_fn)(X509_STORE_CTX *ctx, + X509_CRL *crl, X509 *x); + typedef int (*X509_STORE_CTX_check_policy_fn)(X509_STORE_CTX *ctx); + typedef STACK_OF(X509) *(*X509_STORE_CTX_lookup_certs_fn)(X509_STORE_CTX *ctx, + X509_NAME *nm); + typedef STACK_OF(X509_CRL) *(*X509_STORE_CTX_lookup_crls_fn)(X509_STORE_CTX *ctx, + X509_NAME *nm); + typedef int (*X509_STORE_CTX_cleanup_fn)(X509_STORE_CTX *ctx); + void X509_STORE_set_verify_cb(X509_STORE *ctx, + X509_STORE_CTX_verify_cb verify_cb); + X509_STORE_CTX_verify_cb X509_STORE_get_verify_cb(X509_STORE_CTX *ctx); + + void X509_STORE_set_verify(X509_STORE *ctx, X509_STORE_CTX_verify_fn verify); + X509_STORE_CTX_verify_fn X509_STORE_CTX_get_verify(X509_STORE_CTX *ctx); + + void X509_STORE_set_get_issuer(X509_STORE *ctx, + X509_STORE_CTX_get_issuer_fn get_issuer); + X509_STORE_CTX_get_issuer_fn X509_STORE_get_get_issuer(X509_STORE_CTX *ctx); + + void X509_STORE_set_check_issued(X509_STORE *ctx, + X509_STORE_CTX_check_issued_fn check_issued); + X509_STORE_CTX_check_issued_fn X509_STORE_get_check_issued(X509_STORE_CTX *ctx); + + void X509_STORE_set_check_revocation(X509_STORE *ctx, + X509_STORE_CTX_check_revocation_fn check_revocation); + X509_STORE_CTX_check_revocation_fn X509_STORE_get_check_revocation(X509_STORE_CTX *ctx); + + void X509_STORE_set_get_crl(X509_STORE *ctx, + X509_STORE_CTX_get_crl_fn get_crl); + X509_STORE_CTX_get_crl_fn X509_STORE_get_get_crl(X509_STORE_CTX *ctx); + + void X509_STORE_set_check_crl(X509_STORE *ctx, + X509_STORE_CTX_check_crl_fn check_crl); + X509_STORE_CTX_check_crl_fn X509_STORE_get_check_crl(X509_STORE_CTX *ctx); + + void X509_STORE_set_cert_crl(X509_STORE *ctx, + X509_STORE_CTX_cert_crl_fn cert_crl); + X509_STORE_CTX_cert_crl_fn X509_STORE_get_cert_crl(X509_STORE_CTX *ctx); + + void X509_STORE_set_check_policy(X509_STORE *ctx, + X509_STORE_CTX_check_policy_fn check_policy); + X509_STORE_CTX_check_policy_fn X509_STORE_get_check_policy(X509_STORE_CTX *ctx); + + void X509_STORE_set_lookup_certs(X509_STORE *ctx, + X509_STORE_CTX_lookup_certs_fn lookup_certs); + X509_STORE_CTX_lookup_certs_fn X509_STORE_get_lookup_certs(X509_STORE_CTX *ctx); + + void X509_STORE_set_lookup_crls(X509_STORE *ctx, + X509_STORE_CTX_lookup_crls_fn lookup_crls); + X509_STORE_CTX_lookup_crls_fn X509_STORE_get_lookup_crls(X509_STORE_CTX *ctx); + + void X509_STORE_set_cleanup(X509_STORE *ctx, + X509_STORE_CTX_cleanup_fn cleanup); + X509_STORE_CTX_cleanup_fn X509_STORE_get_cleanup(X509_STORE_CTX *ctx); + + /* Aliases */ void X509_STORE_set_verify_cb_func(X509_STORE *st, - int (*verify_cb)(int ok, X509_STORE_CTX *ctx)); + X509_STORE_CTX_verify_cb verify_cb); + void X509_STORE_set_verify_func(X509_STORE *ctx, + X509_STORE_CTX_verify_fn verify); + void X509_STORE_set_lookup_crls_cb(X509_STORE *ctx, + X509_STORE_CTX_lookup_crls_fn lookup_crls); =head1 DESCRIPTION X509_STORE_set_verify_cb() sets the verification callback of B<ctx> to -B<verify_cb> overwriting any existing callback. +B<verify_cb> overwriting the previous callback. +The callback assigned with this function becomes a default for the one +that can be assigned directly to the corresponding B<X509_STORE_CTX>, +please see L<X509_STORE_CTX_set_verify_cb(3)> for further information. + +X509_STORE_set_verify() sets the final chain verification function for +B<ctx> to B<verify>. +Its purpose is to go through the chain of certificates and check that +all signatures are valid and that the current time is within the +limits of each certificate's first and last validity time. +The final chain verification functions must return 0 on failure and 1 +on success. +I<If no chain verification function is provided, the internal default +function will be used instead.> + +X509_STORE_set_get_issuer() sets the function to get the issuer +certificate that verifies the given certificate B<x>. +When found, the issuer certificate must be assigned to B<*issuer>. +This function must return 0 on failure and 1 on success. +I<If no function to get the issuer is provided, the internal default +function will be used instead.> + +X509_STORE_set_check_issued() sets the function to check that a given +certificate B<x> is issued with the issuer certificate B<issuer>. +This function must return 0 on failure (among others if B<x> hasn't +been issued with B<issuer>) and 1 on success. +I<If no function to get the issuer is provided, the internal default +function will be used instead.> -X509_STORE_set_verify_cb_func() also sets the verification callback but it -is implemented as a macro. +X509_STORE_set_check_revocation() sets the revocation checking +function. +Its purpose is to look through the final chain and check the +revocation status for each certificate. +It must return 0 on failure and 1 on success. +I<If no function to get the issuer is provided, the internal default +function will be used instead.> + +X509_STORE_set_get_crl() sets the function to get the crl for a given +certificate B<x>. +When found, the crl must be assigned to B<*crl>. +This function must return 0 on failure and 1 on success. +I<If no function to get the issuer is provided, the internal default +function will be used instead.> + +X509_STORE_set_check_crl() sets the function to check the validity of +the given B<crl>. +This function must return 0 on failure and 1 on success. +I<If no function to get the issuer is provided, the internal default +function will be used instead.> + +X509_STORE_set_cert_crl() sets the function to check the revocation +status of the given certificate B<x> against the given B<crl>. +This function must return 0 on failure and 1 on success. +I<If no function to get the issuer is provided, the internal default +function will be used instead.> + +X509_STORE_set_check_policy() sets the function to check the policies +of all the certificates in the final chain.. +This function must return 0 on failure and 1 on success. +I<If no function to get the issuer is provided, the internal default +function will be used instead.> + +X509_STORE_set_lookup_certs() and X509_STORE_set_lookup_crls() set the +functions to look up all the certs or all the CRLs that match the +given name B<nm>. +These functions return NULL on failure and a pointer to a stack of +certificates (B<X509>) or to a stack of CRLs (B<X509_CRL>) on +success. +I<If no function to get the issuer is provided, the internal default +function will be used instead.> + +X509_STORE_set_cleanup() sets the final cleanup function, which is +called when the context (B<X509_STORE_CTX>) is being torn down. +This function doesn't return any value. +I<If no function to get the issuer is provided, the internal default +function will be used instead.> + +X509_STORE_get_verify_cb(), X509_STORE_CTX_get_verify(), +X509_STORE_get_get_issuer(), X509_STORE_get_check_issued(), +X509_STORE_get_check_revocation(), X509_STORE_get_get_crl(), +X509_STORE_get_check_crl(), X509_STORE_set_verify(), +X509_STORE_set_get_issuer(), X509_STORE_get_cert_crl(), +X509_STORE_get_check_policy(), X509_STORE_get_lookup_certs(), +X509_STORE_get_lookup_crls() and X509_STORE_get_cleanup() all return +the function pointer assigned with X509_STORE_set_check_issued(), +X509_STORE_set_check_revocation(), X509_STORE_set_get_crl(), +X509_STORE_set_check_crl(), X509_STORE_set_cert_crl(), +X509_STORE_set_check_policy(), X509_STORE_set_lookup_certs(), +X509_STORE_set_lookup_crls() and X509_STORE_set_cleanup(), or NULL if +no assignment has been made. + +X509_STORE_set_verify_cb_func(), X509_STORE_set_verify_func() and +X509_STORE_set_lookup_crls_cb() are aliases for +X509_STORE_set_verify_cb(), X509_STORE_set_verify() and +X509_STORE_set_lookup_crls, available as macros for backward +compatibility. =head1 NOTES -The verification callback from an B<X509_STORE> is inherited by -the corresponding B<X509_STORE_CTX> structure when it is initialized. This can -be used to set the verification callback when the B<X509_STORE_CTX> is -otherwise inaccessible (for example during S/MIME verification). +All the callbacks from a B<X509_STORE> are inherited by the +corresponding B<X509_STORE_CTX> structure when it is initialized. +See L<X509_STORE_CTX_set_verify_cb(3)> for further details. =head1 BUGS -The macro version of this function was the only one available before +The macro version of this function was the only one available before OpenSSL 1.0.0. =head1 RETURN VALUES -X509_STORE_set_verify_cb() and X509_STORE_set_verify_cb_func() do not return -a value. +The X509_STORE_set_*() functions do not return a value. + +The X509_STORE_get_*() functions return a pointer of the appropriate +function type. =head1 SEE ALSO -L<X509_STORE_CTX_set_verify_cb(3)|X509_STORE_CTX_set_verify_cb(3)> -L<CMS_verify(3)|CMS_verify(3)> +L<X509_STORE_CTX_set_verify_cb(3)>, L<X509_STORE_CTX_get0_chain(3)>, +L<X509_STORE_CTX_verify_cb(3)>, L<X509_STORE_CTX_verify_fn(3)>, +L<CMS_verify(3)> =head1 HISTORY -X509_STORE_set_verify_cb_func() is available in all versions of SSLeay and -OpenSSL. - X509_STORE_set_verify_cb() was added to OpenSSL 1.0.0. +X509_STORE_set_verify_cb(), X509_STORE_get_verify_cb(), +X509_STORE_set_verify(), X509_STORE_CTX_get_verify(), +X509_STORE_set_get_issuer(), X509_STORE_get_get_issuer(), +X509_STORE_set_check_issued(), X509_STORE_get_check_issued(), +X509_STORE_set_check_revocation(), X509_STORE_get_check_revocation(), +X509_STORE_set_get_crl(), X509_STORE_get_get_crl(), +X509_STORE_set_check_crl(), X509_STORE_get_check_crl(), +X509_STORE_set_cert_crl(), X509_STORE_get_cert_crl(), +X509_STORE_set_check_policy(), X509_STORE_get_check_policy(), +X509_STORE_set_lookup_certs(), X509_STORE_get_lookup_certs(), +X509_STORE_set_lookup_crls(), X509_STORE_get_lookup_crls(), +X509_STORE_set_cleanup() and X509_STORE_get_cleanup() were added in +OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_VERIFY_PARAM_set_flags.pod b/deps/openssl/openssl/doc/crypto/X509_VERIFY_PARAM_set_flags.pod index 10399ecbaf..5263facfd4 100644 --- a/deps/openssl/openssl/doc/crypto/X509_VERIFY_PARAM_set_flags.pod +++ b/deps/openssl/openssl/doc/crypto/X509_VERIFY_PARAM_set_flags.pod @@ -2,47 +2,69 @@ =head1 NAME -X509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags, X509_VERIFY_PARAM_get_flags, X509_VERIFY_PARAM_set_purpose, X509_VERIFY_PARAM_set_trust, X509_VERIFY_PARAM_set_depth, X509_VERIFY_PARAM_get_depth, X509_VERIFY_PARAM_set_time, X509_VERIFY_PARAM_add0_policy, X509_VERIFY_PARAM_set1_policies, X509_VERIFY_PARAM_set1_host, X509_VERIFY_PARAM_add1_host, X509_VERIFY_PARAM_set_hostflags, X509_VERIFY_PARAM_get0_peername, X509_VERIFY_PARAM_set1_email, X509_VERIFY_PARAM_set1_ip, X509_VERIFY_PARAM_set1_ip_asc - X509 verification parameters +X509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags, +X509_VERIFY_PARAM_get_flags, X509_VERIFY_PARAM_set_purpose, +X509_VERIFY_PARAM_get_inh_flags, X509_VERIFY_PARAM_set_inh_flags, +X509_VERIFY_PARAM_set_trust, X509_VERIFY_PARAM_set_depth, +X509_VERIFY_PARAM_get_depth, X509_VERIFY_PARAM_set_auth_level, +X509_VERIFY_PARAM_get_auth_level, X509_VERIFY_PARAM_set_time, +X509_VERIFY_PARAM_get_time, +X509_VERIFY_PARAM_add0_policy, X509_VERIFY_PARAM_set1_policies, +X509_VERIFY_PARAM_set1_host, X509_VERIFY_PARAM_add1_host, +X509_VERIFY_PARAM_set_hostflags, X509_VERIFY_PARAM_get0_peername, +X509_VERIFY_PARAM_set1_email, X509_VERIFY_PARAM_set1_ip, +X509_VERIFY_PARAM_set1_ip_asc +- X509 verification parameters =head1 SYNOPSIS #include <openssl/x509_vfy.h> - int X509_VERIFY_PARAM_set_flags(X509_VERIFY_PARAM *param, unsigned long flags); + int X509_VERIFY_PARAM_set_flags(X509_VERIFY_PARAM *param, + unsigned long flags); int X509_VERIFY_PARAM_clear_flags(X509_VERIFY_PARAM *param, - unsigned long flags); + unsigned long flags); unsigned long X509_VERIFY_PARAM_get_flags(X509_VERIFY_PARAM *param); + int X509_VERIFY_PARAM_set_inh_flags(X509_VERIFY_PARAM *param, + uint32_t flags); + uint32_t X509_VERIFY_PARAM_get_inh_flags(const X509_VERIFY_PARAM *param); + int X509_VERIFY_PARAM_set_purpose(X509_VERIFY_PARAM *param, int purpose); int X509_VERIFY_PARAM_set_trust(X509_VERIFY_PARAM *param, int trust); void X509_VERIFY_PARAM_set_time(X509_VERIFY_PARAM *param, time_t t); + time_t X509_VERIFY_PARAM_get_time(const X509_VERIFY_PARAM *param); int X509_VERIFY_PARAM_add0_policy(X509_VERIFY_PARAM *param, - ASN1_OBJECT *policy); - int X509_VERIFY_PARAM_set1_policies(X509_VERIFY_PARAM *param, - STACK_OF(ASN1_OBJECT) *policies); + ASN1_OBJECT *policy); + int X509_VERIFY_PARAM_set1_policies(X509_VERIFY_PARAM *param, + STACK_OF(ASN1_OBJECT) *policies); void X509_VERIFY_PARAM_set_depth(X509_VERIFY_PARAM *param, int depth); int X509_VERIFY_PARAM_get_depth(const X509_VERIFY_PARAM *param); + void X509_VERIFY_PARAM_set_auth_level(X509_VERIFY_PARAM *param, + int auth_level); + int X509_VERIFY_PARAM_get_auth_level(const X509_VERIFY_PARAM *param); + int X509_VERIFY_PARAM_set1_host(X509_VERIFY_PARAM *param, - const char *name, size_t namelen); + const char *name, size_t namelen); int X509_VERIFY_PARAM_add1_host(X509_VERIFY_PARAM *param, const char *name, size_t namelen); void X509_VERIFY_PARAM_set_hostflags(X509_VERIFY_PARAM *param, - unsigned int flags); + unsigned int flags); char *X509_VERIFY_PARAM_get0_peername(X509_VERIFY_PARAM *param); int X509_VERIFY_PARAM_set1_email(X509_VERIFY_PARAM *param, - const char *email, size_t emaillen); + const char *email, size_t emaillen); int X509_VERIFY_PARAM_set1_ip(X509_VERIFY_PARAM *param, - const unsigned char *ip, size_t iplen); + const unsigned char *ip, size_t iplen); int X509_VERIFY_PARAM_set1_ip_asc(X509_VERIFY_PARAM *param, const char *ipasc); =head1 DESCRIPTION These functions manipulate the B<X509_VERIFY_PARAM> structure associated with -a certificate verification operation. +a certificate verification operation. The X509_VERIFY_PARAM_set_flags() function sets the flags in B<param> by oring it with B<flags>. See the B<VERIFICATION FLAGS> section for a complete @@ -50,13 +72,18 @@ description of values the B<flags> parameter can take. X509_VERIFY_PARAM_get_flags() returns the flags in B<param>. +X509_VERIFY_PARAM_get_inh_flags() returns the inheritance flags in B<param> +which specifies how verification flags are copied from one structure to +another. X509_VERIFY_PARAM_set_inh_flags() sets the inheritance flags. +See the B<INHERITANCE FLAGS> section for a description of these bits. + X509_VERIFY_PARAM_clear_flags() clears the flags B<flags> in B<param>. X509_VERIFY_PARAM_set_purpose() sets the verification purpose in B<param> to B<purpose>. This determines the acceptable purpose of the certificate chain, for example SSL client or SSL server. -X509_VERIFY_PARAM_set_trust() sets the trust setting in B<param> to +X509_VERIFY_PARAM_set_trust() sets the trust setting in B<param> to B<trust>. X509_VERIFY_PARAM_set_time() sets the verification time in B<param> to @@ -71,8 +98,32 @@ policy set is cleared. The B<policies> parameter can be B<NULL> to clear an existing policy set. X509_VERIFY_PARAM_set_depth() sets the maximum verification depth to B<depth>. -That is the maximum number of untrusted CA certificates that can appear in a +That is the maximum number of intermediate CA certificates that can appear in a chain. +A maximal depth chain contains 2 more certificates than the limit, since +neither the end-entity certificate nor the trust-anchor count against this +limit. +Thus a B<depth> limit of 0 only allows the end-entity certificate to be signed +directly by the trust-anchor, while with a B<depth> limit of 1 there can be one +intermediate CA certificate between the trust-anchor and the end-entity +certificate. + +X509_VERIFY_PARAM_set_auth_level() sets the authentication security level to +B<auth_level>. +The authentication security level determines the acceptable signature and public +key strength when verifying certificate chains. +For a certificate chain to validate, the public keys of all the certificates +must meet the specified security level. +The signature algorithm security level is not enforced for the chain's I<trust +anchor> certificate, which is either directly trusted or validated by means other +than its signature. +See L<SSL_CTX_set_security_level(3)> for the definitions of the available +levels. +The default security level is -1, or "not set". +At security level 0 or lower all algorithms are acceptable. +Security level 1 requires at least 80-bit-equivalent security and is broadly +interoperable, though it will, for example, reject MD5 signatures or RSA keys +shorter than 1024 bits. X509_VERIFY_PARAM_set1_host() sets the expected DNS hostname to B<name> clearing any previously specified host name or names. If @@ -82,14 +133,14 @@ is NUL-terminated, B<namelen> may be zero, otherwise B<namelen> must be set to the length of B<name>. When a hostname is specified, certificate verification automatically invokes L<X509_check_host(3)> with flags equal to the B<flags> argument given to -B<X509_VERIFY_PARAM_set_hostflags()> (default zero). Applications +X509_VERIFY_PARAM_set_hostflags() (default zero). Applications are strongly advised to use this interface in preference to explicitly calling L<X509_check_host(3)>, hostname checks are out of scope with the DANE-EE(3) certificate usage, and the internal check will be suppressed as appropriate when DANE support is added to OpenSSL. X509_VERIFY_PARAM_add1_host() adds B<name> as an additional reference -identifer that can match the peer's certificate. Any previous names +identifier that can match the peer's certificate. Any previous names set via X509_VERIFY_PARAM_set1_host() or X509_VERIFY_PARAM_add1_host() are retained, no change is made if B<name> is NULL or empty. When multiple names are configured, the peer is considered verified when @@ -125,27 +176,33 @@ IPv6. The condensed "::" notation is supported for IPv6 addresses. =head1 RETURN VALUES X509_VERIFY_PARAM_set_flags(), X509_VERIFY_PARAM_clear_flags(), +X509_VERIFY_PARAM_set_inh_flags(), X509_VERIFY_PARAM_set_purpose(), X509_VERIFY_PARAM_set_trust(), X509_VERIFY_PARAM_add0_policy() X509_VERIFY_PARAM_set1_policies(), -X509_VERIFY_PARAM_set1_host(), X509_VERIFY_PARAM_set_hostflags(), +X509_VERIFY_PARAM_set1_host(), X509_VERIFY_PARAM_add1_host(), X509_VERIFY_PARAM_set1_email(), X509_VERIFY_PARAM_set1_ip() and X509_VERIFY_PARAM_set1_ip_asc() return 1 for success and 0 for failure. X509_VERIFY_PARAM_get_flags() returns the current verification flags. +X509_VERIFY_PARAM_get_inh_flags() returns the current inheritance flags. + X509_VERIFY_PARAM_set_time() and X509_VERIFY_PARAM_set_depth() do not return values. X509_VERIFY_PARAM_get_depth() returns the current verification depth. +X509_VERIFY_PARAM_get_auth_level() returns the current authentication security +level. + =head1 VERIFICATION FLAGS The verification flags consists of zero or more of the following flags ored together. B<X509_V_FLAG_CRL_CHECK> enables CRL checking for the certificate chain leaf -certificate. An error occurs if a suitable CRL cannot be found. +certificate. An error occurs if a suitable CRL cannot be found. B<X509_V_FLAG_CRL_CHECK_ALL> enables CRL checking for the entire certificate chain. @@ -157,13 +214,13 @@ ignored. B<WARNING> setting this option for anything other than debugging purposes can be a security risk. Finer control over which extensions are supported can be performed in the verification callback. -THe B<X509_V_FLAG_X509_STRICT> flag disables workarounds for some broken +The B<X509_V_FLAG_X509_STRICT> flag disables workarounds for some broken certificates and makes the verification strictly apply B<X509> rules. B<X509_V_FLAG_ALLOW_PROXY_CERTS> enables proxy certificate verification. B<X509_V_FLAG_POLICY_CHECK> enables certificate policy checking, by default -no policy checking is peformed. Additional information is sent to the +no policy checking is performed. Additional information is sent to the verification callback relating to policy checking. B<X509_V_FLAG_EXPLICIT_POLICY>, B<X509_V_FLAG_INHIBIT_ANY> and @@ -181,48 +238,73 @@ By default some additional features such as indirect CRLs and CRLs signed by different keys are disabled. If B<X509_V_FLAG_EXTENDED_CRL_SUPPORT> is set they are enabled. -If B<X509_V_FLAG_USE_DELTAS> ise set delta CRLs (if present) are used to +If B<X509_V_FLAG_USE_DELTAS> is set delta CRLs (if present) are used to determine certificate status. If not set deltas are ignored. B<X509_V_FLAG_CHECK_SS_SIGNATURE> enables checking of the root CA self signed -cerificate signature. By default this check is disabled because it doesn't +certificate signature. By default this check is disabled because it doesn't add any additional security but in some cases applications might want to check the signature anyway. A side effect of not checking the root CA signature is that disabled or unsupported message digests on the root CA are not treated as fatal errors. -The B<X509_V_FLAG_CB_ISSUER_CHECK> flag enables debugging of certificate -issuer checks. It is B<not> needed unless you are logging certificate -verification. If this flag is set then additional status codes will be sent -to the verification callback and it B<must> be prepared to handle such cases -without assuming they are hard errors. - -The B<X509_V_FLAG_NO_ALT_CHAINS> flag suppresses checking for alternative -chains. By default, when building a certificate chain, if the first certificate -chain found is not trusted, then OpenSSL will continue to check to see if an -alternative chain can be found that is trusted. With this flag set the behaviour -will match that of OpenSSL versions prior to 1.0.2b. - -The B<X509_V_FLAG_TRUSTED_FIRST> flag causes chain construction to look for -issuers in the trust store before looking at the untrusted certificates -provided as part of the the peer chain. -Though it is not on by default in OpenSSL 1.0.2, applications should generally -set this flag. +When B<X509_V_FLAG_TRUSTED_FIRST> is set, construction of the certificate chain +in L<X509_verify_cert(3)> will search the trust store for issuer certificates +before searching the provided untrusted certificates. Local issuer certificates are often more likely to satisfy local security requirements and lead to a locally trusted root. -This is especially important When some certificates in the trust store have +This is especially important when some certificates in the trust store have explicit trust settings (see "TRUST SETTINGS" in L<x509(1)>). +As of OpenSSL 1.1.0 this option is on by default. + +The B<X509_V_FLAG_NO_ALT_CHAINS> flag suppresses checking for alternative +chains. +By default, unless B<X509_V_FLAG_TRUSTED_FIRST> is set, when building a +certificate chain, if the first certificate chain found is not trusted, then +OpenSSL will attempt to replace untrusted certificates supplied by the peer +with certificates from the trust store to see if an alternative chain can be +found that is trusted. +As of OpenSSL 1.1.0, with B<X509_V_FLAG_TRUSTED_FIRST> always set, this option +has no effect. The B<X509_V_FLAG_PARTIAL_CHAIN> flag causes intermediate certificates in the trust store to be treated as trust-anchors, in the same way as the self-signed root CA certificates. This makes it possible to trust certificates issued by an intermediate CA without having to trust its ancestor root CA. -With OpenSSL 1.0.2, chain construction continues as long as there are -additional trusted issuers in the trust store, and the last trusted issuer -becomes the trust-anchor. -Thus, even when an intermediate certificate is found in the trust store, the -verified chain passed to callbacks may still be anchored by a root CA. +With OpenSSL 1.1.0 and later and <X509_V_FLAG_PARTIAL_CHAIN> set, chain +construction stops as soon as the first certificate from the trust store is +added to the chain, whether that certificate is a self-signed "root" +certificate or a not self-signed intermediate certificate. +Thus, when an intermediate certificate is found in the trust store, the +verified chain passed to callbacks may be shorter than it otherwise would +be without the B<X509_V_FLAG_PARTIAL_CHAIN> flag. + +The B<X509_V_FLAG_NO_CHECK_TIME> flag suppresses checking the validity period +of certificates and CRLs against the current time. If X509_VERIFY_PARAM_set_time() +is used to specify a verification time, the check is not suppressed. + +=head1 INHERITANCE FLAGS + +These flags specify how parameters are "inherited" from one structure to +another. + +If B<X509_VP_FLAG_ONCE> is set then the current setting is zeroed +after the next call. + +If B<X509_VP_FLAG_LOCKED> is set then no values are copied. This overrides +all of the following flags. + +If B<X509_VP_FLAG_DEFAULT> is set then anything set in the source is copied +to the destination. Effectively the values in "to" become default values +which will be used only if nothing new is set in "from". This is the +default. + +If B<X509_VP_FLAG_OVERWRITE> is set then all value are copied across whether +they are set or not. Flags is still Ored though. + +If B<X509_VP_FLAG_RESET_FLAGS> is set then the flags value is copied instead +of ORed. =head1 NOTES @@ -233,7 +315,7 @@ X509_STORE_CTX_set_flags(). =head1 BUGS Delta CRL checking is currently primitive. Only a single delta can be used and -(partly due to limitations of B<X509_STORE>) constructed CRLs are not +(partly due to limitations of B<X509_STORE>) constructed CRLs are not maintained. If CRLs checking is enable CRLs are expected to be available in the @@ -242,7 +324,7 @@ CRLs from the CRL distribution points extension. =head1 EXAMPLE -Enable CRL checking when performing certificate verification during SSL +Enable CRL checking when performing certificate verification during SSL connections associated with an B<SSL_CTX> structure B<ctx>: X509_VERIFY_PARAM *param; @@ -253,14 +335,25 @@ connections associated with an B<SSL_CTX> structure B<ctx>: =head1 SEE ALSO -L<X509_verify_cert(3)|X509_verify_cert(3)>, -L<X509_check_host(3)|X509_check_host(3)>, -L<X509_check_email(3)|X509_check_email(3)>, -L<X509_check_ip(3)|X509_check_ip(3)>, -L<x509(1)|x509(1)> +L<X509_verify_cert(3)>, +L<X509_check_host(3)>, +L<X509_check_email(3)>, +L<X509_check_ip(3)>, +L<x509(1)> =head1 HISTORY -The B<X509_V_FLAG_NO_ALT_CHAINS> flag was added in OpenSSL 1.0.2b +The B<X509_V_FLAG_NO_ALT_CHAINS> flag was added in OpenSSL 1.1.0 +The legacy B<X509_V_FLAG_CB_ISSUER_CHECK> flag is deprecated as of +OpenSSL 1.1.0, and has no effect. + +=head1 COPYRIGHT + +Copyright 2009-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_check_ca.pod b/deps/openssl/openssl/doc/crypto/X509_check_ca.pod new file mode 100644 index 0000000000..b79efb5b5a --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/X509_check_ca.pod @@ -0,0 +1,45 @@ +=pod + +=head1 NAME + +X509_check_ca - check if given certificate is CA certificate + +=head1 SYNOPSIS + + #include <openssl/x509v3.h> + + int X509_check_ca(X509 *cert); + +=head1 DESCRIPTION + +This function checks if given certificate is CA certificate (can be used +to sign other certificates). + +=head1 RETURN VALUE + +Function return 0, if it is not CA certificate, 1 if it is proper X509v3 +CA certificate with B<basicConstraints> extension CA:TRUE, +3, if it is self-signed X509 v1 certificate, 4, if it is certificate with +B<keyUsage> extension with bit B<keyCertSign> set, but without +B<basicConstraints>, and 5 if it has outdated Netscape Certificate Type +extension telling that it is CA certificate. + +Actually, any non-zero value means that this certificate could have been +used to sign other certificates. + +=head1 SEE ALSO + +L<X509_verify_cert(3)>, +L<X509_check_issued(3)>, +L<X509_check_purpose(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_check_host.pod b/deps/openssl/openssl/doc/crypto/X509_check_host.pod index 521b9f535c..93848152b5 100644 --- a/deps/openssl/openssl/doc/crypto/X509_check_host.pod +++ b/deps/openssl/openssl/doc/crypto/X509_check_host.pod @@ -9,11 +9,11 @@ X509_check_host, X509_check_email, X509_check_ip, X509_check_ip_asc - X.509 cert #include <openssl/x509.h> int X509_check_host(X509 *, const char *name, size_t namelen, - unsigned int flags, char **peername); + unsigned int flags, char **peername); int X509_check_email(X509 *, const char *address, size_t addresslen, - unsigned int flags); + unsigned int flags); int X509_check_ip(X509 *, const unsigned char *address, size_t addresslen, - unsigned int flags); + unsigned int flags); int X509_check_ip_asc(X509 *, const char *address, unsigned int flags); =head1 DESCRIPTION @@ -70,6 +70,8 @@ flags: =item B<X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT>, +=item B<X509_CHECK_FLAG_NEVER_CHECK_SUBJECT>, + =item B<X509_CHECK_FLAG_NO_WILDCARDS>, =item B<X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS>, @@ -86,12 +88,18 @@ one subject alternative name of the right type (DNS name or email address as appropriate); the default is to ignore the subject DN when at least one corresponding subject alternative names is present. +The B<X509_CHECK_FLAG_NEVER_CHECK_SUBJECT> flag causes the function to never +consider the subject DN even if the certificate contains no subject alternative +names of the right type (DNS name or email address as appropriate); the default +is to use the subject DN when no corresponding subject alternative names are +present. + If set, B<X509_CHECK_FLAG_NO_WILDCARDS> disables wildcard expansion; this only applies to B<X509_check_host>. If set, B<X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS> suppresses support for "*" as wildcard pattern in labels that have a prefix or suffix, -such as: "www*" or "*www"; this only aplies to B<X509_check_host>. +such as: "www*" or "*www"; this only applies to B<X509_check_host>. If set, B<X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS> allows a "*" that constitutes the complete label of a DNS name (e.g. "*.example.com") @@ -126,15 +134,24 @@ DANE support is added to OpenSSL. =head1 SEE ALSO -L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>, -L<X509_VERIFY_PARAM_set1_host(3)|X509_VERIFY_PARAM_set1_host(3)>, -L<X509_VERIFY_PARAM_add1_host(3)|X509_VERIFY_PARAM_add1_host(3)>, -L<X509_VERIFY_PARAM_set1_email(3)|X509_VERIFY_PARAM_set1_email(3)>, -L<X509_VERIFY_PARAM_set1_ip(3)|X509_VERIFY_PARAM_set1_ip(3)>, -L<X509_VERIFY_PARAM_set1_ipasc(3)|X509_VERIFY_PARAM_set1_ipasc(3)> +L<SSL_get_verify_result(3)>, +L<X509_VERIFY_PARAM_set1_host(3)>, +L<X509_VERIFY_PARAM_add1_host(3)>, +L<X509_VERIFY_PARAM_set1_email(3)>, +L<X509_VERIFY_PARAM_set1_ip(3)>, +L<X509_VERIFY_PARAM_set1_ipasc(3)> =head1 HISTORY These functions were added in OpenSSL 1.0.2. +=head1 COPYRIGHT + +Copyright 2012-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_check_issued.pod b/deps/openssl/openssl/doc/crypto/X509_check_issued.pod new file mode 100644 index 0000000000..8e4b1117ca --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/X509_check_issued.pod @@ -0,0 +1,45 @@ +=pod + +=head1 NAME + +X509_check_issued - checks if certificate is issued by another +certificate + +=head1 SYNOPSIS + + #include <openssl/x509v3.h> + + int X509_check_issued(X509 *issuer, X509 *subject); + + +=head1 DESCRIPTION + +This function checks if certificate I<subject> was issued using CA +certificate I<issuer>. This function takes into account not only +matching of issuer field of I<subject> with subject field of I<issuer>, +but also compares B<authorityKeyIdentifier> extension of I<subject> with +B<subjectKeyIdentifier> of I<issuer> if B<authorityKeyIdentifier> +present in the I<subject> certificate and checks B<keyUsage> field of +I<issuer>. + +=head1 RETURN VALUE + +Function return B<X509_V_OK> if certificate I<subject> is issued by +I<issuer> or some B<X509_V_ERR*> constant to indicate an error. + +=head1 SEE ALSO + +L<X509_verify_cert(3)>, +L<X509_check_ca(3)>, +L<verify(1)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_check_private_key.pod b/deps/openssl/openssl/doc/crypto/X509_check_private_key.pod deleted file mode 100644 index a1fb07b109..0000000000 --- a/deps/openssl/openssl/doc/crypto/X509_check_private_key.pod +++ /dev/null @@ -1,54 +0,0 @@ -=pod - -=head1 NAME - -X509_check_private_key, X509_REQ_check_private_key - check the consistency -of a private key with the public key in an X509 certificate or certificate -request - -=head1 SYNOPSIS - - #include <openssl/x509.h> - - int X509_check_private_key(X509 *x, EVP_PKEY *k); - - int X509_REQ_check_private_key(X509_REQ *x, EVP_PKEY *k); - -=head1 DESCRIPTION - -X509_check_private_key() function checks the consistency of private -key B<k> with the public key in B<x>. - -X509_REQ_check_private_key() is equivalent to X509_check_private_key() -except that B<x> represents a certificate request of structure B<X509_REQ>. - -=head1 RETURN VALUE - -X509_check_private_key() and X509_REQ_check_private_key() return 1 if -the keys match each other, and 0 if not. - -If the key is invalid or an error occurred, the reason code can be -obtained using L<ERR_get_error(3)>. - -=head1 BUGS - -The B<check_private_key> functions don't check if B<k> itself is indeed -a private key or not. It merely compares the public materials (e.g. exponent -and modulus of an RSA key) and/or key parameters (e.g. EC params of an EC key) -of a key pair. So if you pass a public key to these functions in B<k>, it will -return success. - -=head1 SEE ALSO - -L<ERR_get_error(3)> - -=head1 COPYRIGHT - -Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_digest.pod b/deps/openssl/openssl/doc/crypto/X509_digest.pod new file mode 100644 index 0000000000..3c76c8fdfa --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/X509_digest.pod @@ -0,0 +1,65 @@ +=pod + +=head1 NAME + +X509_digest, X509_CRL_digest, +X509_pubkey_digest, +X509_NAME_digest, +X509_REQ_digest, +PKCS7_ISSUER_AND_SERIAL_digest +- get digest of various objects + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + int X509_digest(const X509 *data, const EVP_MD *type, unsigned char *md, + unsigned int *len); + + int X509_CRL_digest(const X509_CRL *data, const EVP_MD *type, unsigned char *md, + unsigned int *len); + + int X509_pubkey_digest(const X509 *data, const EVP_MD *type, + unsigned char *md, unsigned int *len); + + int X509_REQ_digest(const X509_REQ *data, const EVP_MD *type, + unsigned char *md, unsigned int *len); + + int X509_NAME_digest(const X509_NAME *data, const EVP_MD *type, + unsigned char *md, unsigned int *len); + + int PKCS7_ISSUER_AND_SERIAL_digest(PKCS7_ISSUER_AND_SERIAL *data, + const EVP_MD *type, unsigned char *md, + unsigned int *len); + +=head1 DESCRIPTION + +X509_pubkey_digest() returns a digest of the DER representation of the public +key in the specified X509 B<data> object. +All other functions described here return a digest of the DER representation +of their entire B<data> objects. + +The B<type> parameter specifies the digest to +be used, such as EVP_sha1(). The B<md> is a pointer to the buffer where the +digest will be copied and is assumed to be large enough; the constant +B<EVP_MAX_MD_SIZE> is suggested. The B<len> parameter, if not NULL, points +to a place where the digest size will be stored. + +=head1 RETURN VALUES + +All functions described here return 1 for success and 0 for failure. + +=head1 SEE ALSO + +L<EVP_sha1(3)> + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_dup.pod b/deps/openssl/openssl/doc/crypto/X509_dup.pod new file mode 100644 index 0000000000..c5d01b281f --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/X509_dup.pod @@ -0,0 +1,303 @@ +=pod + +=head1 NAME + +DECLARE_ASN1_FUNCTIONS, +IMPLEMENT_ASN1_FUNCTIONS, +ASN1_ITEM, +ACCESS_DESCRIPTION_free, +ACCESS_DESCRIPTION_new, +ASIdOrRange_free, +ASIdOrRange_new, +ASIdentifierChoice_free, +ASIdentifierChoice_new, +ASIdentifiers_free, +ASIdentifiers_new, +ASRange_free, +ASRange_new, +AUTHORITY_INFO_ACCESS_free, +AUTHORITY_INFO_ACCESS_new, +AUTHORITY_KEYID_free, +AUTHORITY_KEYID_new, +BASIC_CONSTRAINTS_free, +BASIC_CONSTRAINTS_new, +CERTIFICATEPOLICIES_free, +CERTIFICATEPOLICIES_new, +CMS_ContentInfo_free, +CMS_ContentInfo_new, +CMS_ContentInfo_print_ctx, +CMS_ReceiptRequest_free, +CMS_ReceiptRequest_new, +CRL_DIST_POINTS_free, +CRL_DIST_POINTS_new, +DIRECTORYSTRING_free, +DIRECTORYSTRING_new, +DISPLAYTEXT_free, +DISPLAYTEXT_new, +DIST_POINT_NAME_free, +DIST_POINT_NAME_new, +DIST_POINT_free, +DIST_POINT_new, +DSAparams_dup, +ECPARAMETERS_free, +ECPARAMETERS_new, +ECPKPARAMETERS_free, +ECPKPARAMETERS_new, +EDIPARTYNAME_free, +EDIPARTYNAME_new, +ESS_CERT_ID_dup, +ESS_CERT_ID_free, +ESS_CERT_ID_new, +ESS_ISSUER_SERIAL_dup, +ESS_ISSUER_SERIAL_free, +ESS_ISSUER_SERIAL_new, +ESS_SIGNING_CERT_dup, +ESS_SIGNING_CERT_free, +ESS_SIGNING_CERT_new, +EXTENDED_KEY_USAGE_free, +EXTENDED_KEY_USAGE_new, +GENERAL_NAMES_free, +GENERAL_NAMES_new, +GENERAL_NAME_dup, +GENERAL_NAME_free, +GENERAL_NAME_new, +GENERAL_SUBTREE_free, +GENERAL_SUBTREE_new, +IPAddressChoice_free, +IPAddressChoice_new, +IPAddressFamily_free, +IPAddressFamily_new, +IPAddressOrRange_free, +IPAddressOrRange_new, +IPAddressRange_free, +IPAddressRange_new, +ISSUING_DIST_POINT_free, +ISSUING_DIST_POINT_new, +NAME_CONSTRAINTS_free, +NAME_CONSTRAINTS_new, +NETSCAPE_CERT_SEQUENCE_free, +NETSCAPE_CERT_SEQUENCE_new, +NETSCAPE_SPKAC_free, +NETSCAPE_SPKAC_new, +NETSCAPE_SPKI_free, +NETSCAPE_SPKI_new, +NOTICEREF_free, +NOTICEREF_new, +OCSP_BASICRESP_free, +OCSP_BASICRESP_new, +OCSP_CERTID_dup, +OCSP_CERTID_new, +OCSP_CERTSTATUS_free, +OCSP_CERTSTATUS_new, +OCSP_CRLID_free, +OCSP_CRLID_new, +OCSP_ONEREQ_free, +OCSP_ONEREQ_new, +OCSP_REQINFO_free, +OCSP_REQINFO_new, +OCSP_RESPBYTES_free, +OCSP_RESPBYTES_new, +OCSP_RESPDATA_free, +OCSP_RESPDATA_new, +OCSP_RESPID_free, +OCSP_RESPID_new, +OCSP_RESPONSE_new, +OCSP_REVOKEDINFO_free, +OCSP_REVOKEDINFO_new, +OCSP_SERVICELOC_free, +OCSP_SERVICELOC_new, +OCSP_SIGNATURE_free, +OCSP_SIGNATURE_new, +OCSP_SINGLERESP_free, +OCSP_SINGLERESP_new, +OTHERNAME_free, +OTHERNAME_new, +PBE2PARAM_free, +PBE2PARAM_new, +PBEPARAM_free, +PBEPARAM_new, +PBKDF2PARAM_free, +PBKDF2PARAM_new, +PKCS12_BAGS_free, +PKCS12_BAGS_new, +PKCS12_MAC_DATA_free, +PKCS12_MAC_DATA_new, +PKCS12_SAFEBAG_free, +PKCS12_SAFEBAG_new, +PKCS12_free, +PKCS12_new, +PKCS7_DIGEST_free, +PKCS7_DIGEST_new, +PKCS7_ENCRYPT_free, +PKCS7_ENCRYPT_new, +PKCS7_ENC_CONTENT_free, +PKCS7_ENC_CONTENT_new, +PKCS7_ENVELOPE_free, +PKCS7_ENVELOPE_new, +PKCS7_ISSUER_AND_SERIAL_free, +PKCS7_ISSUER_AND_SERIAL_new, +PKCS7_RECIP_INFO_free, +PKCS7_RECIP_INFO_new, +PKCS7_SIGNED_free, +PKCS7_SIGNED_new, +PKCS7_SIGNER_INFO_free, +PKCS7_SIGNER_INFO_new, +PKCS7_SIGN_ENVELOPE_free, +PKCS7_SIGN_ENVELOPE_new, +PKCS7_dup, +PKCS7_free, +PKCS7_new, +PKCS7_print_ctx, +PKCS8_PRIV_KEY_INFO_free, +PKCS8_PRIV_KEY_INFO_new, +PKEY_USAGE_PERIOD_free, +PKEY_USAGE_PERIOD_new, +POLICYINFO_free, +POLICYINFO_new, +POLICYQUALINFO_free, +POLICYQUALINFO_new, +POLICY_CONSTRAINTS_free, +POLICY_CONSTRAINTS_new, +POLICY_MAPPING_free, +POLICY_MAPPING_new, +PROXY_CERT_INFO_EXTENSION_free, +PROXY_CERT_INFO_EXTENSION_new, +PROXY_POLICY_free, +PROXY_POLICY_new, +RSAPrivateKey_dup, +RSAPublicKey_dup, +RSA_OAEP_PARAMS_free, +RSA_OAEP_PARAMS_new, +RSA_PSS_PARAMS_free, +RSA_PSS_PARAMS_new, +SCT_LIST_free, +SXNETID_free, +SXNETID_new, +SXNET_free, +SXNET_new, +TLS_FEATURE_free, +TLS_FEATURE_new, +TS_ACCURACY_dup, +TS_ACCURACY_free, +TS_ACCURACY_new, +TS_MSG_IMPRINT_dup, +TS_MSG_IMPRINT_free, +TS_MSG_IMPRINT_new, +TS_REQ_dup, +TS_REQ_free, +TS_REQ_new, +TS_RESP_dup, +TS_RESP_free, +TS_RESP_new, +TS_STATUS_INFO_dup, +TS_STATUS_INFO_free, +TS_STATUS_INFO_new, +TS_TST_INFO_dup, +TS_TST_INFO_free, +TS_TST_INFO_new, +USERNOTICE_free, +USERNOTICE_new, +X509_ALGOR_free, +X509_ALGOR_new, +X509_ATTRIBUTE_dup, +X509_ATTRIBUTE_free, +X509_ATTRIBUTE_new, +X509_CERT_AUX_free, +X509_CERT_AUX_new, +X509_CINF_free, +X509_CINF_new, +X509_CRL_INFO_free, +X509_CRL_INFO_new, +X509_CRL_dup, +X509_CRL_free, +X509_CRL_new, +X509_EXTENSION_dup, +X509_EXTENSION_free, +X509_EXTENSION_new, +X509_NAME_ENTRY_dup, +X509_NAME_ENTRY_free, +X509_NAME_ENTRY_new, +X509_NAME_dup, +X509_NAME_free, +X509_NAME_new, +X509_REQ_INFO_free, +X509_REQ_INFO_new, +X509_REQ_dup, +X509_REQ_free, +X509_REQ_new, +X509_REVOKED_dup, +X509_REVOKED_free, +X509_REVOKED_new, +X509_SIG_free, +X509_SIG_new, +X509_VAL_free, +X509_VAL_new, +X509_dup, +- ASN1 object utilities + +=for comment generic + +=head1 SYNOPSIS + + #include <openssl/asn1t.h> + + DECLARE_ASN1_FUNCTIONS(type) + IMPLEMENT_ASN1_FUNCTIONS(stname) + + typedef struct ASN1_ITEM_st ASN1_ITEM; + + extern const ASN1_ITEM TYPE_it; + TYPE *TYPE_new(void); + TYPE *TYPE_dup(TYPE *a); + void TYPE_free(TYPE *a); + int TYPE_print_ctx(BIO *out, TYPE *a, int indent, const ASN1_PCTX *pctx); + +=head1 DESCRIPTION + +In the description below, I<TYPE> is used +as a placeholder for any of the OpenSSL datatypes, such as I<X509>. + +The OpenSSL ASN1 parsing library templates are like a data-driven bytecode +interpreter. +Every ASN1 object as a global variable, TYPE_it, that describes the item +such as its fields. (On systems which cannot export variables from shared +libraries, the global is instead a function which returns a pointer to a +static variable. + +The macro DECLARE_ASN1_FUNCTIONS() is typically used in header files +to generate the function declarations. + +The macro IMPLEMENT_ASN1_FUNCTIONS() is used once in a source file +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_free() releases the object and all pointers and sub-objects +within it. + +TYPE_print_ctx() prints the object B<a> on the specified BIO B<out>. +Each line will be prefixed with B<indent> spaces. +The B<pctx> specifies the printing context and is for internal +use; use NULL to get the default behavior. If a print function is +user-defined, then pass in any B<pctx> down to any nested calls. + +=head1 RETURN VALUES + +TYPE_new() and TYPE_dup() return a pointer to the object or NULL on failure. + +TYPE_print_ctx() returns 1 on success or zero on failure. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_get0_notBefore.pod b/deps/openssl/openssl/doc/crypto/X509_get0_notBefore.pod new file mode 100644 index 0000000000..0427d4122a --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/X509_get0_notBefore.pod @@ -0,0 +1,103 @@ +=pod + +=head1 NAME + +X509_get0_notBefore, X509_getm_notBefore, X509_get0_notAfter, +X509_getm_notAfter, X509_set1_notBefore, X509_set1_notAfter, +X509_CRL_get0_lastUpdate, X509_CRL_get0_nextUpdate, X509_CRL_set1_lastUpdate, +X509_CRL_set1_nextUpdate - get or set certificate or CRL dates + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + const ASN1_TIME *X509_get0_notBefore(const X509 *x); + const ASN1_TIME *X509_get0_notAfter(const X509 *x); + + ASN1_TIME *X509_getm_notBefore(const X509 *x); + ASN1_TIME *X509_getm_notAfter(const X509 *x); + + int X509_set1_notBefore(X509 *x, const ASN1_TIME *tm); + int X509_set1_notAfter(X509 *x, const ASN1_TIME *tm); + + const ASN1_TIME *X509_CRL_get0_lastUpdate(const X509_CRL *crl); + const ASN1_TIME *X509_CRL_get0_nextUpdate(const X509_CRL *crl); + + int X509_CRL_set1_lastUpdate(X509_CRL *x, const ASN1_TIME *tm); + int X509_CRL_set1_nextUpdate(X509_CRL *x, const ASN1_TIME *tm); + +=head1 DESCRIPTION + +X509_get0_notBefore() and X509_get0_notAfter() return the B<notBefore> +and B<notAfter> fields of certificate B<x> respectively. The value +returned is an internal pointer which must not be freed up after +the call. + +X509_getm_notBefore() and X509_getm_notAfter() are similar to +X509_get0_notBefore() and X509_get0_notAfter() except they return +non-constant mutable references to the associated date field of +the certificate. + +X509_set1_notBefore() and X509_set1_notAfter() set the B<notBefore> +and B<notAfter> fields of B<x> to B<tm>. Ownership of the passed +parameter B<tm> is not transferred by these functions so it must +be freed up after the call. + +X509_CRL_get0_lastUpdate() and X509_CRL_get0_nextUpdate() return the +B<lastUpdate> and B<nextUpdate> fields of B<crl>. The value +returned is an internal pointer which must not be freed up after +the call. If the B<nextUpdate> field is absent from B<crl> then +B<NULL> is returned. + +X509_CRL_set1_lastUpdate() and X509_CRL_set1_nextUpdate() set the B<lastUpdate> +and B<nextUpdate> fields of B<crl> to B<tm>. Ownership of the passed parameter +B<tm> is not transferred by these functions so it must be freed up after the +call. + +=head1 RETURN VALUES + +X509_get0_notBefore(), X509_get0_notAfter() and X509_CRL_get0_lastUpdate() +return a pointer to an B<ASN1_TIME> structure. + +X509_CRL_get0_lastUpdate() return a pointer to an B<ASN1_TIME> structure +or NULL if the B<lastUpdate> field is absent. + +X509_set1_notBefore(), X509_set1_notAfter(), X509_CRL_set1_lastUpdate() and +X509_CRL_set1_nextUpdate() return 1 for success or 0 for failure. + +=head1 SEE ALSO + +L<d2i_X509(3)>, +L<ERR_get_error(3)>, +L<X509_CRL_get0_by_serial(3)>, +L<X509_get0_signature(3)>, +L<X509_get_ext_d2i(3)>, +L<X509_get_extension_flags(3)>, +L<X509_get_pubkey(3)>, +L<X509_get_subject_name(3)>, +L<X509_NAME_add_entry_by_txt(3)>, +L<X509_NAME_ENTRY_get_object(3)>, +L<X509_NAME_get_index_by_NID(3)>, +L<X509_NAME_print_ex(3)>, +L<X509_new(3)>, +L<X509_sign(3)>, +L<X509V3_get_d2i(3)>, +L<X509_verify_cert(3)> + +=head1 HISTORY + +These functions are available in all versions of OpenSSL. + +X509_get_notBefore() and X509_get_notAfter() were deprecated in OpenSSL +1.1.0 + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_get0_signature.pod b/deps/openssl/openssl/doc/crypto/X509_get0_signature.pod new file mode 100644 index 0000000000..61a2dda981 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/X509_get0_signature.pod @@ -0,0 +1,97 @@ +=pod + +=head1 NAME + +X509_get0_signature, X509_get_signature_nid, X509_get0_tbs_sigalg, +X509_REQ_get0_signature, X509_REQ_get_signature_nid, X509_CRL_get0_signature, +X509_CRL_get_signature_nid - signature information + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + void X509_get0_signature(const ASN1_BIT_STRING **psig, + const X509_ALGOR **palg, + const X509 *x); + int X509_get_signature_nid(const X509 *x); + const X509_ALGOR *X509_get0_tbs_sigalg(const X509 *x); + + void X509_REQ_get0_signature(const X509_REQ *crl, + const ASN1_BIT_STRING **psig, + const X509_ALGOR **palg); + int X509_REQ_get_signature_nid(const X509_REQ *crl); + + void X509_CRL_get0_signature(const X509_CRL *crl, + const ASN1_BIT_STRING **psig, + const X509_ALGOR **palg); + int X509_CRL_get_signature_nid(const X509_CRL *crl); + +=head1 DESCRIPTION + +X509_get0_signature() sets B<*psig> to the signature of B<x> and B<*palg> +to the signature algorithm of B<x>. The values returned are internal +pointers which B<MUST NOT> be freed up after the call. + +X509_get0_tbs_sigalg() returns the signature algorithm in the signed +portion of B<x>. + +X509_get_signature_nid() returns the NID corresponding to the signature +algorithm of B<x>. + +X509_REQ_get0_signature(), X509_REQ_get_signature_nid() +X509_CRL_get0_signature() and X509_CRL_get_signature_nid() perform the +same function for certificate requests and CRLs. + +=head1 NOTES + +These functions provide lower level access to signatures in certificates +where an application wishes to analyse or generate a signature in a form +where X509_sign() et al is not appropriate (for example a non standard +or unsupported format). + +=head1 RETURN VALUES + +X509_get_signature_nid(), X509_REQ_get_signature_nid() and +X509_CRL_get_signature_nid() return a NID. + +X509_get0_signature(), X509_REQ_get0_signature() and +X509_CRL_get0_signature() do not return values. + +=head1 SEE ALSO + +L<d2i_X509(3)>, +L<ERR_get_error(3)>, +L<X509_CRL_get0_by_serial(3)>, +L<X509_get_ext_d2i(3)>, +L<X509_get_extension_flags(3)>, +L<X509_get_pubkey(3)>, +L<X509_get_subject_name(3)>, +L<X509_get_version(3)>, +L<X509_NAME_add_entry_by_txt(3)>, +L<X509_NAME_ENTRY_get_object(3)>, +L<X509_NAME_get_index_by_NID(3)>, +L<X509_NAME_print_ex(3)>, +L<X509_new(3)>, +L<X509_sign(3)>, +L<X509V3_get_d2i(3)>, +L<X509_verify_cert(3)> + +=head1 HISTORY + +X509_get0_signature() and X509_get_signature_nid() were first added to +OpenSSL 1.0.2. + +X509_REQ_get0_signature(), X509_REQ_get_signature_nid(), +X509_CRL_get0_signature() and X509_CRL_get_signature_nid() were first added +to OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_get0_uids.pod b/deps/openssl/openssl/doc/crypto/X509_get0_uids.pod new file mode 100644 index 0000000000..4eab26e23f --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/X509_get0_uids.pod @@ -0,0 +1,57 @@ +=pod + +=head1 NAME + +X509_get0_uids - get certificate unique identifiers + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + void X509_get0_uids(const X509 *x, const ASN1_BIT_STRING **piuid, + const ASN1_BIT_STRING **psuid); + +=head1 DESCRIPTION + +X509_get0_uids() sets B<*piuid> and B<*psuid> to the issuer and subject unique +identifiers of certificate B<x> or NULL if the fields are not present. + +=head1 NOTES + +The issuer and subject unique identifier fields are very rarely encountered in +practice outside test cases. + +=head1 RETURN VALUES + +X509_get0_uids() does not return a value. + +=head1 SEE ALSO + +L<d2i_X509(3)>, +L<ERR_get_error(3)>, +L<X509_CRL_get0_by_serial(3)>, +L<X509_get0_signature(3)>, +L<X509_get_ext_d2i(3)>, +L<X509_get_extension_flags(3)>, +L<X509_get_pubkey(3)>, +L<X509_get_subject_name(3)>, +L<X509_get_version(3)>, +L<X509_NAME_add_entry_by_txt(3)>, +L<X509_NAME_ENTRY_get_object(3)>, +L<X509_NAME_get_index_by_NID(3)>, +L<X509_NAME_print_ex(3)>, +L<X509_new(3)>, +L<X509_sign(3)>, +L<X509V3_get_d2i(3)>, +L<X509_verify_cert(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_get_extension_flags.pod b/deps/openssl/openssl/doc/crypto/X509_get_extension_flags.pod new file mode 100644 index 0000000000..c07ef972ed --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/X509_get_extension_flags.pod @@ -0,0 +1,181 @@ +=pod + +=head1 NAME + +X509_get0_subject_key_id, +X509_get0_authority_key_id, +X509_get_pathlen, +X509_get_extension_flags, +X509_get_key_usage, +X509_get_extended_key_usage, +X509_set_proxy_flag, +X509_set_proxy_pathlen, +X509_get_proxy_pathlen - retrieve certificate extension data + +=head1 SYNOPSIS + + #include <openssl/x509v3.h> + + long X509_get_pathlen(X509 *x); + uint32_t X509_get_extension_flags(X509 *x); + uint32_t X509_get_key_usage(X509 *x); + uint32_t X509_get_extended_key_usage(X509 *x); + const ASN1_OCTET_STRING *X509_get0_subject_key_id(X509 *x); + const ASN1_OCTET_STRING *X509_get0_authority_key_id(X509 *x); + void X509_set_proxy_flag(X509 *x); + void X509_set_proxy_pathlen(int l); + long X509_get_proxy_pathlen(X509 *x); + +=head1 DESCRIPTION + +These functions retrieve information related to commonly used certificate extensions. + +X509_get_pathlen() retrieves the path length extension from a certificate. +This extension is used to limit the length of a cert chain that may be +issued from that CA. + +X509_get_extension_flags() retrieves general information about a certificate, +it will return one or more of the following flags ored together. + +=over 4 + +=item B<EXFLAG_V1> + +The certificate is an obsolete version 1 certificate. + +=item B<EXFLAG_BCONS> + +The certificate contains a basic constraints extension. + +=item B<EXFLAG_CA> + +The certificate contains basic constraints and asserts the CA flag. + +=item B<EXFLAG_PROXY> + +The certificate is a valid proxy certificate. + +=item B<EXFLAG_SI> + +The certificate is self issued (that is subject and issuer names match). + +=item B<EXFLAG_SS> + +The subject and issuer names match and extension values imply it is self +signed. + +=item B<EXFLAG_FRESHEST> + +The freshest CRL extension is present in the certificate. + +=item B<EXFLAG_CRITICAL> + +The certificate contains an unhandled critical extension. + +=item B<EXFLAG_INVALID> + +Some certificate extension values are invalid or inconsistent. The +certificate should be rejected. + +=item B<EXFLAG_KUSAGE> + +The certificate contains a key usage extension. The value can be retrieved +using X509_get_key_usage(). + +=item B<EXFLAG_XKUSAGE> + +The certificate contains an extended key usage extension. The value can be +retrieved using X509_get_extended_key_usage(). + +=back + +X509_get_key_usage() returns the value of the key usage extension. If key +usage is present will return zero or more of the flags: +B<KU_DIGITAL_SIGNATURE>, B<KU_NON_REPUDIATION>, B<KU_KEY_ENCIPHERMENT>, +B<KU_DATA_ENCIPHERMENT>, B<KU_KEY_AGREEMENT>, B<KU_KEY_CERT_SIGN>, +B<KU_CRL_SIGN>, B<KU_ENCIPHER_ONLY> or B<KU_DECIPHER_ONLY> corresponding to +individual key usage bits. If key usage is absent then B<UINT32_MAX> is +returned. + +X509_get_extended_key_usage() returns the value of the extended key usage +extension. If extended key usage is present it will return zero or more of the +flags: B<XKU_SSL_SERVER>, B<XKU_SSL_CLIENT>, B<XKU_SMIME>, B<XKU_CODE_SIGN> +B<XKU_OCSP_SIGN>, B<XKU_TIMESTAMP>, B<XKU_DVCS> or B<XKU_ANYEKU>. These +correspond to the OIDs B<id-kp-serverAuth>, B<id-kp-clientAuth>, +B<id-kp-emailProtection>, B<id-kp-codeSigning>, B<id-kp-OCSPSigning>, +B<id-kp-timeStamping>, B<id-kp-dvcs> and B<anyExtendedKeyUsage> respectively. +Additionally B<XKU_SGC> is set if either Netscape or Microsoft SGC OIDs are +present. + +X509_get0_subject_key_id() returns an internal pointer to the subject key +identifier of B<x> as an B<ASN1_OCTET_STRING> or B<NULL> if the extension +is not present or cannot be parsed. + +X509_get0_authority_key_id() returns an internal pointer to the authority key +identifier of B<x> as an B<ASN1_OCTET_STRING> or B<NULL> if the extension +is not present or cannot be parsed. + +X509_set_proxy_flag() marks the certificate with the B<EXFLAG_PROXY> flag. +This is for the users who need to mark non-RFC3820 proxy certificates as +such, as OpenSSL only detects RFC3820 compliant ones. + +X509_set_proxy_pathlen() sets the proxy certificate path length for the given +certificate B<x>. This is for the users who need to mark non-RFC3820 proxy +certificates as such, as OpenSSL only detects RFC3820 compliant ones. + +X509_get_proxy_pathlen() returns the proxy certificate path length for the +given certificate B<x> if it is a proxy certificate. + +=head1 NOTES + +The value of the flags correspond to extension values which are cached +in the B<X509> structure. If the flags returned do not provide sufficient +information an application should examine extension values directly +for example using X509_get_ext_d2i(). + +If the key usage or extended key usage extension is absent then typically usage +is unrestricted. For this reason X509_get_key_usage() and +X509_get_extended_key_usage() return B<UINT32_MAX> when the corresponding +extension is absent. Applications can additionally check the return value of +X509_get_extension_flags() and take appropriate action is an extension is +absent. + +If X509_get0_subject_key_id() returns B<NULL> then the extension may be +absent or malformed. Applications can determine the precise reason using +X509_get_ext_d2i(). + +=head1 RETURN VALUE + +X509_get_pathlen() returns the path length value, or -1 if the extension +is not present. + +X509_get_extension_flags(), X509_get_key_usage() and +X509_get_extended_key_usage() return sets of flags corresponding to the +certificate extension values. + +X509_get0_subject_key_id() returns the subject key identifier as a +pointer to an B<ASN1_OCTET_STRING> structure or B<NULL> if the extension +is absent or an error occurred during parsing. + +X509_get_proxy_pathlen() returns the path length value if the given +certificate is a proxy one and has a path length set, and -1 otherwise. + +=head1 SEE ALSO + +L<X509_check_purpose(3)> + +=head1 HISTORY + +X509_get_pathlen(), X509_set_proxy_flag(), X509_set_proxy_pathlen() and +X509_get_proxy_pathlen() were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2015-2018 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_get_pubkey.pod b/deps/openssl/openssl/doc/crypto/X509_get_pubkey.pod new file mode 100644 index 0000000000..2b9a956c2d --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/X509_get_pubkey.pod @@ -0,0 +1,87 @@ +=pod + +=head1 NAME + +X509_get_pubkey, X509_get0_pubkey, X509_set_pubkey, X509_get_X509_PUBKEY, +X509_REQ_get_pubkey, X509_REQ_get0_pubkey, X509_REQ_set_pubkey, +X509_REQ_get_X509_PUBKEY - get or set certificate or certificate request +public key + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + EVP_PKEY *X509_get_pubkey(X509 *x); + EVP_PKEY *X509_get0_pubkey(const X509 *x); + int X509_set_pubkey(X509 *x, EVP_PKEY *pkey); + X509_PUBKEY *X509_get_X509_PUBKEY(X509 *x); + + EVP_PKEY *X509_REQ_get_pubkey(X509_REQ *req); + EVP_PKEY *X509_REQ_get0_pubkey(X509_REQ *req); + int X509_REQ_set_pubkey(X509_REQ *x, EVP_PKEY *pkey); + X509_PUBKEY *X509_REQ_get_X509_PUBKEY(X509_REQ *x); + +=head1 DESCRIPTION + +X509_get_pubkey() attempts to decode the public key for certificate B<x>. If +successful it returns the public key as an B<EVP_PKEY> pointer with its +reference count incremented: this means the returned key must be freed up +after use. X509_get0_pubkey() is similar except it does B<not> increment +the reference count of the returned B<EVP_PKEY> so it must not be freed up +after use. + +X509_get_X509_PUBKEY() returns an internal pointer to the B<X509_PUBKEY> +structure which encodes the certificate of B<x>. The returned value +must not be freed up after use. + +X509_set_pubkey() attempts to set the public key for certificate B<x> to +B<pkey>. The key B<pkey> should be freed up after use. + +X509_REQ_get_pubkey(), X509_REQ_get0_pubkey(), X509_REQ_set_pubkey() and +X509_REQ_get_X509_PUBKEY() are similar but operate on certificate request B<req>. + +=head1 NOTES + +The first time a public key is decoded the B<EVP_PKEY> structure is +cached in the certificate or certificate request itself. Subsequent calls +return the cached structure with its reference count incremented to +improve performance. + +=head1 RETURN VALUES + +X509_get_pubkey(), X509_get0_pubkey(), X509_get_X509_PUBKEY(), +X509_REQ_get_pubkey() and X509_REQ_get_X509_PUBKEY() return a public key or +B<NULL> if an error occurred. + +X509_set_pubkey() and X509_REQ_set_pubkey() return 1 for success and 0 +for failure. + +=head1 SEE ALSO + +L<d2i_X509(3)>, +L<ERR_get_error(3)>, +L<X509_CRL_get0_by_serial(3)>, +L<X509_get0_signature(3)>, +L<X509_get_ext_d2i(3)>, +L<X509_get_extension_flags(3)>, +L<X509_get_subject_name(3)>, +L<X509_get_version(3)>, +L<X509_NAME_add_entry_by_txt(3)>, +L<X509_NAME_ENTRY_get_object(3)>, +L<X509_NAME_get_index_by_NID(3)>, +L<X509_NAME_print_ex(3)>, +L<X509_new(3)>, +L<X509_sign(3)>, +L<X509V3_get_d2i(3)>, +L<X509_verify_cert(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_get_serialNumber.pod b/deps/openssl/openssl/doc/crypto/X509_get_serialNumber.pod new file mode 100644 index 0000000000..2e81c62396 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/X509_get_serialNumber.pod @@ -0,0 +1,71 @@ +=pod + +=head1 NAME + +X509_get_serialNumber, +X509_get0_serialNumber, +X509_set_serialNumber +- get or set certificate serial number + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + ASN1_INTEGER *X509_get_serialNumber(X509 *x); + const ASN1_INTEGER *X509_get0_serialNumber(const X509 *x); + int X509_set_serialNumber(X509 *x, ASN1_INTEGER *serial); + +=head1 DESCRIPTION + +X509_get_serialNumber() returns the serial number of certificate B<x> as an +B<ASN1_INTEGER> structure which can be examined or initialised. The value +returned is an internal pointer which B<MUST NOT> be freed up after the call. + +X509_get0_serialNumber() is the same as X509_get_serialNumber() except it +accepts a const parameter and returns a const result. + +X509_set_serialNumber() sets the serial number of certificate B<x> to +B<serial>. A copy of the serial number is used internally so B<serial> should +be freed up after use. + +=head1 RETURN VALUES + +X509_get_serialNumber() and X509_get0_serialNumber() return an B<ASN1_INTEGER> +structure. + +X509_set_serialNumber() returns 1 for success and 0 for failure. + +=head1 SEE ALSO + +L<d2i_X509(3)>, +L<ERR_get_error(3)>, +L<X509_CRL_get0_by_serial(3)>, +L<X509_get0_signature(3)>, +L<X509_get_ext_d2i(3)>, +L<X509_get_extension_flags(3)>, +L<X509_get_pubkey(3)>, +L<X509_get_subject_name(3)>, +L<X509_NAME_add_entry_by_txt(3)>, +L<X509_NAME_ENTRY_get_object(3)>, +L<X509_NAME_get_index_by_NID(3)>, +L<X509_NAME_print_ex(3)>, +L<X509_new(3)>, +L<X509_sign(3)>, +L<X509V3_get_d2i(3)>, +L<X509_verify_cert(3)> + +=head1 HISTORY + +X509_get_serialNumber() and X509_set_serialNumber() are available in +all versions of OpenSSL. X509_get0_serialNumber() was added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_get_subject_name.pod b/deps/openssl/openssl/doc/crypto/X509_get_subject_name.pod new file mode 100644 index 0000000000..ce36bbf0b2 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/X509_get_subject_name.pod @@ -0,0 +1,86 @@ +=pod + +=head1 NAME + +X509_get_subject_name, X509_set_subject_name, X509_get_issuer_name, +X509_set_issuer_name, X509_REQ_get_subject_name, X509_REQ_set_subject_name, +X509_CRL_get_issuer, X509_CRL_set_issuer_name - get and set issuer or +subject names + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + X509_NAME *X509_get_subject_name(const X509 *x); + int X509_set_subject_name(X509 *x, X509_NAME *name); + + X509_NAME *X509_get_issuer_name(const X509 *x); + int X509_set_issuer_name(X509 *x, X509_NAME *name); + + X509_NAME *X509_REQ_get_subject_name(const X509_REQ *req); + int X509_REQ_set_subject_name(X509_REQ *req, X509_NAME *name); + + X509_NAME *X509_CRL_get_issuer(const X509_CRL *crl); + int X509_CRL_set_issuer_name(X509_CRL *x, X509_NAME *name); + +=head1 DESCRIPTION + +X509_get_subject_name() returns the subject name of certificate B<x>. The +returned value is an internal pointer which B<MUST NOT> be freed. + +X509_set_subject_name() sets the issuer name of certificate B<x> to +B<name>. The B<name> parameter is copied internally and should be freed +up when it is no longer needed. + +X509_get_issuer_name() and X509_set_issuer_name() are identical to +X509_get_subject_name() and X509_set_subject_name() except the get and +set the issuer name of B<x>. + +Similarly X509_REQ_get_subject_name(), X509_REQ_set_subject_name(), + X509_CRL_get_issuer() and X509_CRL_set_issuer_name() get or set the subject +or issuer names of certificate requests of CRLs respectively. + +=head1 RETURN VALUES + +X509_get_subject_name(), X509_get_issuer_name(), X509_REQ_get_subject_name() +and X509_CRL_get_issuer() return an B<X509_NAME> pointer. + +X509_set_subject_name(), X509_set_issuer_name(), X509_REQ_set_subject_name() +and X509_CRL_set_issuer_name() return 1 for success and 0 for failure. + +=head1 HISTORY + +X509_REQ_get_subject_name() is a function in OpenSSL 1.1.0 and a macro in +earlier versions. + +X509_CRL_get_issuer() is a function in OpenSSL 1.1.0. It was first added +to OpenSSL 1.0.0 as a macro. + +=head1 SEE ALSO + +L<d2i_X509(3)>, +L<ERR_get_error(3)>, L<d2i_X509(3)> +L<X509_CRL_get0_by_serial(3)>, +L<X509_get0_signature(3)>, +L<X509_get_ext_d2i(3)>, +L<X509_get_extension_flags(3)>, +L<X509_get_pubkey(3)>, +L<X509_NAME_add_entry_by_txt(3)>, +L<X509_NAME_ENTRY_get_object(3)>, +L<X509_NAME_get_index_by_NID(3)>, +L<X509_NAME_print_ex(3)>, +L<X509_new(3)>, +L<X509_sign(3)>, +L<X509V3_get_d2i(3)>, +L<X509_verify_cert(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_get_version.pod b/deps/openssl/openssl/doc/crypto/X509_get_version.pod new file mode 100644 index 0000000000..c1826ea30d --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/X509_get_version.pod @@ -0,0 +1,83 @@ +=pod + +=head1 NAME + +X509_get_version, X509_set_version, X509_REQ_get_version, X509_REQ_set_version, +X509_CRL_get_version, X509_CRL_set_version - get or set certificate, +certificate request or CRL version + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + long X509_get_version(const X509 *x); + int X509_set_version(X509 *x, long version); + + long X509_REQ_get_version(const X509_REQ *req); + int X509_REQ_set_version(X509_REQ *x, long version); + + long X509_CRL_get_version(const X509_CRL *crl); + int X509_CRL_set_version(X509_CRL *x, long version); + +=head1 DESCRIPTION + +X509_get_version() returns the numerical value of the version field of +certificate B<x>. Note: this is defined by standards (X.509 et al) to be one +less than the certificate version. So a version 3 certificate will return 2 and +a version 1 certificate will return 0. + +X509_set_version() sets the numerical value of the version field of certificate +B<x> to B<version>. + +Similarly X509_REQ_get_version(), X509_REQ_set_version(), +X509_CRL_get_version() and X509_CRL_set_version() get and set the version +number of certificate requests and CRLs. + +=head1 NOTES + +The version field of certificates, certificate requests and CRLs has a +DEFAULT value of B<v1(0)> meaning the field should be omitted for version +1. This is handled transparently by these functions. + +=head1 RETURN VALUES + +X509_get_version(), X509_REQ_get_version() and X509_CRL_get_version() +return the numerical value of the version field. + +X509_set_version(), X509_REQ_set_version() and X509_CRL_set_version() +return 1 for success and 0 for failure. + +=head1 SEE ALSO + +L<d2i_X509(3)>, +L<ERR_get_error(3)>, +L<X509_CRL_get0_by_serial(3)>, +L<X509_get0_signature(3)>, +L<X509_get_ext_d2i(3)>, +L<X509_get_extension_flags(3)>, +L<X509_get_pubkey(3)>, +L<X509_get_subject_name(3)>, +L<X509_NAME_add_entry_by_txt(3)>, +L<X509_NAME_ENTRY_get_object(3)>, +L<X509_NAME_get_index_by_NID(3)>, +L<X509_NAME_print_ex(3)>, +L<X509_new(3)>, +L<X509_sign(3)>, +L<X509V3_get_d2i(3)>, +L<X509_verify_cert(3)> + +=head1 HISTORY + +X509_get_version(), X509_REQ_get_version() and X509_CRL_get_version() are +functions in OpenSSL 1.1.0, in previous versions they were macros. + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_new.pod b/deps/openssl/openssl/doc/crypto/X509_new.pod index d38872335f..4f5349931a 100644 --- a/deps/openssl/openssl/doc/crypto/X509_new.pod +++ b/deps/openssl/openssl/doc/crypto/X509_new.pod @@ -2,7 +2,8 @@ =head1 NAME -X509_new, X509_free - X509 certificate ASN1 allocation functions +X509_chain_up_ref, +X509_new, X509_free, X509_up_ref - X509 certificate ASN1 allocation functions =head1 SYNOPSIS @@ -10,30 +11,73 @@ X509_new, X509_free - X509 certificate ASN1 allocation functions X509 *X509_new(void); void X509_free(X509 *a); + int X509_up_ref(X509 *a); + STACK_OF(X509) *X509_chain_up_ref(STACK_OF(X509) *x); =head1 DESCRIPTION The X509 ASN1 allocation routines, allocate and free an X509 structure, which represents an X509 certificate. -X509_new() allocates and initializes a X509 structure. +X509_new() allocates and initializes a X509 structure with reference count +B<1>. -X509_free() frees up the B<X509> structure B<a>. +X509_free() decrements the reference count of B<X509> structure B<a> and +frees it up if the reference count is zero. If B<a> is NULL nothing is done. + +X509_up_ref() increments the reference count of B<a>. + +X509_chain_up_ref() increases the reference count of all certificates in +chain B<x> and returns a copy of the stack. + +=head1 NOTES + +The function X509_up_ref() if useful if a certificate structure is being +used by several different operations each of which will free it up after +use: this avoids the need to duplicate the entire certificate structure. + +The function X509_chain_up_ref() doesn't just up the reference count of +each certificate it also returns a copy of the stack, using sk_X509_dup(), +but it serves a similar purpose: the returned chain persists after the +original has been freed. =head1 RETURN VALUES If the allocation fails, X509_new() returns B<NULL> and sets an error -code that can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. +code that can be obtained by L<ERR_get_error(3)>. Otherwise it returns a pointer to the newly allocated structure. -X509_free() returns no value. - -=head1 SEE ALSO +X509_up_ref() returns 1 for success and 0 for failure. -L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_X509(3)|d2i_X509(3)> +X509_chain_up_ref() returns a copy of the stack or B<NULL> if an error +occurred. -=head1 HISTORY +=head1 SEE ALSO -X509_new() and X509_free() are available in all versions of SSLeay and OpenSSL. +L<d2i_X509(3)>, +L<ERR_get_error(3)>, +L<X509_CRL_get0_by_serial(3)>, +L<X509_get0_signature(3)>, +L<X509_get_ext_d2i(3)>, +L<X509_get_extension_flags(3)>, +L<X509_get_pubkey(3)>, +L<X509_get_subject_name(3)>, +L<X509_get_version(3)>, +L<X509_NAME_add_entry_by_txt(3)>, +L<X509_NAME_ENTRY_get_object(3)>, +L<X509_NAME_get_index_by_NID(3)>, +L<X509_NAME_print_ex(3)>, +L<X509_sign(3)>, +L<X509V3_get_d2i(3)>, +L<X509_verify_cert(3)> + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_sign.pod b/deps/openssl/openssl/doc/crypto/X509_sign.pod new file mode 100644 index 0000000000..994fd43881 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/X509_sign.pod @@ -0,0 +1,99 @@ +=pod + +=head1 NAME + +X509_sign, X509_sign_ctx, X509_verify, X509_REQ_sign, X509_REQ_sign_ctx, +X509_REQ_verify, X509_CRL_sign, X509_CRL_sign_ctx, X509_CRL_verify - +sign or verify certificate, certificate request or CRL signature + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + int X509_sign(X509 *x, EVP_PKEY *pkey, const EVP_MD *md); + int X509_sign_ctx(X509 *x, EVP_MD_CTX *ctx); + int X509_verify(X509 *a, EVP_PKEY *r); + + int X509_REQ_sign(X509_REQ *x, EVP_PKEY *pkey, const EVP_MD *md); + int X509_REQ_sign_ctx(X509_REQ *x, EVP_MD_CTX *ctx); + int X509_REQ_verify(X509_REQ *a, EVP_PKEY *r); + + int X509_CRL_sign(X509_CRL *x, EVP_PKEY *pkey, const EVP_MD *md); + int X509_CRL_sign_ctx(X509_CRL *x, EVP_MD_CTX *ctx); + int X509_CRL_verify(X509_CRL *a, EVP_PKEY *r); + +=head1 DESCRIPTION + +X509_sign() signs certificate B<x> using private key B<pkey> and message +digest B<md> and sets the signature in B<x>. X509_sign_ctx() also signs +certificate B<x> but uses the parameters contained in digest context B<ctx>. + +X509_verify() verifies the signature of certificate B<x> using public key +B<pkey>. Only the signature is checked: no other checks (such as certificate +chain validity) are performed. + +X509_REQ_sign(), X509_REQ_sign_ctx(), X509_REQ_verify(), +X509_CRL_sign(), X509_CRL_sign_ctx() and X509_CRL_verify() sign and verify +certificate requests and CRLs respectively. + +=head1 NOTES + +X509_sign_ctx() is used where the default parameters for the corresponding +public key and digest are not suitable. It can be used to sign keys using +RSA-PSS for example. + +For efficiency reasons and to work around ASN.1 encoding issues the encoding +of the signed portion of a certificate, certificate request and CRL is cached +internally. If the signed portion of the structure is modified the encoding +is not always updated meaning a stale version is sometimes used. This is not +normally a problem because modifying the signed portion will invalidate the +signature and signing will always update the encoding. + +=head1 RETURN VALUES + +X509_sign(), X509_sign_ctx(), X509_REQ_sign(), X509_REQ_sign_ctx(), +X509_CRL_sign() and X509_CRL_sign_ctx() return the size of the signature +in bytes for success and zero for failure. + +X509_verify(), X509_REQ_verify() and X509_CRL_verify() return 1 if the +signature is valid and 0 if the signature check fails. If the signature +could not be checked at all because it was invalid or some other error +occurred then -1 is returned. + +=head1 SEE ALSO + +L<d2i_X509(3)>, +L<ERR_get_error(3)>, +L<X509_CRL_get0_by_serial(3)>, +L<X509_get0_signature(3)>, +L<X509_get_ext_d2i(3)>, +L<X509_get_extension_flags(3)>, +L<X509_get_pubkey(3)>, +L<X509_get_subject_name(3)>, +L<X509_get_version(3)>, +L<X509_NAME_add_entry_by_txt(3)>, +L<X509_NAME_ENTRY_get_object(3)>, +L<X509_NAME_get_index_by_NID(3)>, +L<X509_NAME_print_ex(3)>, +L<X509_new(3)>, +L<X509V3_get_d2i(3)>, +L<X509_verify_cert(3)> + +=head1 HISTORY + +X509_sign(), X509_REQ_sign() and X509_CRL_sign() are available in all +versions of OpenSSL. + +X509_sign_ctx(), X509_REQ_sign_ctx() and X509_CRL_sign_ctx() were first added +to OpenSSL 1.0.1. + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509_verify_cert.pod b/deps/openssl/openssl/doc/crypto/X509_verify_cert.pod index 4689e3afea..74acf8df71 100644 --- a/deps/openssl/openssl/doc/crypto/X509_verify_cert.pod +++ b/deps/openssl/openssl/doc/crypto/X509_verify_cert.pod @@ -2,7 +2,7 @@ =head1 NAME -X509_verify_cert - discover and verify X509 certificte chain +X509_verify_cert - discover and verify X509 certificate chain =head1 SYNOPSIS @@ -14,7 +14,7 @@ X509_verify_cert - discover and verify X509 certificte chain The X509_verify_cert() function attempts to discover and validate a certificate chain based on parameters in B<ctx>. A complete description of -the process is contained in the L<verify(1)|verify(1)> manual page. +the process is contained in the L<verify(1)> manual page. =head1 RETURN VALUES @@ -42,14 +42,19 @@ Applications must check for <= 0 return value on error. =head1 BUGS This function uses the header B<x509.h> as opposed to most chain verification -functiosn which use B<x509_vfy.h>. +functions which use B<x509_vfy.h>. =head1 SEE ALSO -L<X509_STORE_CTX_get_error(3)|X509_STORE_CTX_get_error(3)> +L<X509_STORE_CTX_get_error(3)> -=head1 HISTORY +=head1 COPYRIGHT -X509_verify_cert() is available in all versions of SSLeay and OpenSSL. +Copyright 2009-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/X509v3_get_ext_by_NID.pod b/deps/openssl/openssl/doc/crypto/X509v3_get_ext_by_NID.pod new file mode 100644 index 0000000000..032f71c494 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/X509v3_get_ext_by_NID.pod @@ -0,0 +1,140 @@ +=pod + +=head1 NAME + +X509v3_get_ext_count, X509v3_get_ext, X509v3_get_ext_by_NID, +X509v3_get_ext_by_OBJ, X509v3_get_ext_by_critical, X509v3_delete_ext, +X509v3_add_ext, X509_get_ext_count, X509_get_ext, +X509_get_ext_by_NID, X509_get_ext_by_OBJ, X509_get_ext_by_critical, +X509_delete_ext, X509_add_ext, X509_CRL_get_ext_count, X509_CRL_get_ext, +X509_CRL_get_ext_by_NID, X509_CRL_get_ext_by_OBJ, X509_CRL_get_ext_by_critical, +X509_CRL_delete_ext, X509_CRL_add_ext, X509_REVOKED_get_ext_count, +X509_REVOKED_get_ext, X509_REVOKED_get_ext_by_NID, X509_REVOKED_get_ext_by_OBJ, +X509_REVOKED_get_ext_by_critical, X509_REVOKED_delete_ext, +X509_REVOKED_add_ext - extension stack utility functions + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + int X509v3_get_ext_count(const STACK_OF(X509_EXTENSION) *x); + X509_EXTENSION *X509v3_get_ext(const STACK_OF(X509_EXTENSION) *x, int loc); + + int X509v3_get_ext_by_NID(const STACK_OF(X509_EXTENSION) *x, + int nid, int lastpos); + int X509v3_get_ext_by_OBJ(const STACK_OF(X509_EXTENSION) *x, + const ASN1_OBJECT *obj, int lastpos); + int X509v3_get_ext_by_critical(const STACK_OF(X509_EXTENSION) *x, + int crit, int lastpos); + X509_EXTENSION *X509v3_delete_ext(STACK_OF(X509_EXTENSION) *x, int loc); + STACK_OF(X509_EXTENSION) *X509v3_add_ext(STACK_OF(X509_EXTENSION) **x, + X509_EXTENSION *ex, int loc); + + int X509_get_ext_count(const X509 *x); + X509_EXTENSION *X509_get_ext(const X509 *x, int loc); + int X509_get_ext_by_NID(const X509 *x, int nid, int lastpos); + int X509_get_ext_by_OBJ(const X509 *x, const ASN1_OBJECT *obj, int lastpos); + int X509_get_ext_by_critical(const X509 *x, int crit, int lastpos); + X509_EXTENSION *X509_delete_ext(X509 *x, int loc); + int X509_add_ext(X509 *x, X509_EXTENSION *ex, int loc); + + int X509_CRL_get_ext_count(const X509_CRL *x); + X509_EXTENSION *X509_CRL_get_ext(const X509_CRL *x, int loc); + int X509_CRL_get_ext_by_NID(const X509_CRL *x, int nid, int lastpos); + int X509_CRL_get_ext_by_OBJ(const X509_CRL *x, const ASN1_OBJECT *obj, int lastpos); + int X509_CRL_get_ext_by_critical(const X509_CRL *x, int crit, int lastpos); + X509_EXTENSION *X509_CRL_delete_ext(X509_CRL *x, int loc); + int X509_CRL_add_ext(X509_CRL *x, X509_EXTENSION *ex, int loc); + + int X509_REVOKED_get_ext_count(const X509_REVOKED *x); + X509_EXTENSION *X509_REVOKED_get_ext(const X509_REVOKED *x, int loc); + int X509_REVOKED_get_ext_by_NID(const X509_REVOKED *x, int nid, int lastpos); + int X509_REVOKED_get_ext_by_OBJ(const X509_REVOKED *x, const ASN1_OBJECT *obj, + int lastpos); + int X509_REVOKED_get_ext_by_critical(const X509_REVOKED *x, int crit, int lastpos); + X509_EXTENSION *X509_REVOKED_delete_ext(X509_REVOKED *x, int loc); + int X509_REVOKED_add_ext(X509_REVOKED *x, X509_EXTENSION *ex, int loc); + +=head1 DESCRIPTION + +X509v3_get_ext_count() retrieves the number of extensions in B<x>. + +X509v3_get_ext() retrieves extension B<loc> from B<x>. The index B<loc> +can take any value from B<0> to X509_get_ext_count(x) - 1. The returned +extension is an internal pointer which B<must not> be freed up by the +application. + +X509v3_get_ext_by_NID() and X509v3_get_ext_by_OBJ() look for an extension +with B<nid> or B<obj> from extension stack B<x>. The search starts from the +extension after B<lastpos> or from the beginning if <lastpos> is B<-1>. If +the extension is found its index is returned otherwise B<-1> is returned. + +X509v3_get_ext_by_critical() is similar to X509v3_get_ext_by_NID() except it +looks for an extension of criticality B<crit>. A zero value for B<crit> +looks for a non-critical extension a non-zero value looks for a critical +extension. + +X509v3_delete_ext() deletes the extension with index B<loc> from B<x>. The +deleted extension is returned and must be freed by the caller. If B<loc> +is in invalid index value B<NULL> is returned. + +X509v3_add_ext() adds extension B<ex> to stack B<*x> at position B<loc>. If +B<loc> is B<-1> the new extension is added to the end. If B<*x> is B<NULL> +a new stack will be allocated. The passed extension B<ex> is duplicated +internally so it must be freed after use. + +X509_get_ext_count(), X509_get_ext(), X509_get_ext_by_NID(), +X509_get_ext_by_OBJ(), X509_get_ext_by_critical(), X509_delete_ext() +and X509_add_ext() operate on the extensions of certificate B<x> they are +otherwise identical to the X509v3 functions. + +X509_CRL_get_ext_count(), X509_CRL_get_ext(), X509_CRL_get_ext_by_NID(), +X509_CRL_get_ext_by_OBJ(), X509_CRL_get_ext_by_critical(), +X509_CRL_delete_ext() and X509_CRL_add_ext() operate on the extensions of +CRL B<x> they are otherwise identical to the X509v3 functions. + +X509_REVOKED_get_ext_count(), X509_REVOKED_get_ext(), +X509_REVOKED_get_ext_by_NID(), X509_REVOKED_get_ext_by_OBJ(), +X509_REVOKED_get_ext_by_critical(), X509_REVOKED_delete_ext() and +X509_REVOKED_add_ext() operate on the extensions of CRL entry B<x> +they are otherwise identical to the X509v3 functions. + +=head1 NOTES + +These functions are used to examine stacks of extensions directly. Many +applications will want to parse or encode and add an extension: they should +use the extension encode and decode functions instead such as +X509_add1_ext_i2d() and X509_get_ext_d2i(). + +Extension indices start from zero, so a zero index return value is B<not> an +error. These search functions start from the extension B<after> the B<lastpos> +parameter so it should initially be set to B<-1>, if it is set to zero the +initial extension will not be checked. + +=head1 RETURN VALUES + +X509v3_get_ext_count() returns the extension count. + +X509v3_get_ext() and X509v3_delete_ext() return an B<X509_EXTENSION> pointer +or B<NULL> if an error occurs. + +X509v3_get_ext_by_NID() X509v3_get_ext_by_OBJ() and +X509v3_get_ext_by_critical() return the an extension index or B<-1> if an +error occurs. + +X509v3_add_ext() returns a stack of extensions or B<NULL> on error. + +=head1 SEE ALSO + +L<X509V3_get_d2i(3)> + +=head1 COPYRIGHT + +Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/bio.pod b/deps/openssl/openssl/doc/crypto/bio.pod index f9239226ff..7be3121fd1 100644 --- a/deps/openssl/openssl/doc/crypto/bio.pod +++ b/deps/openssl/openssl/doc/crypto/bio.pod @@ -1,16 +1,17 @@ =pod +=for comment openssl_manual_section 7 + =head1 NAME -bio - I/O abstraction +bio - Basic I/O abstraction + +=for comment generic =head1 SYNOPSIS #include <openssl/bio.h> -TBA - - =head1 DESCRIPTION A BIO is an I/O abstraction, it hides many of the underlying I/O @@ -37,18 +38,52 @@ BIO and one or more filter BIOs. Data read from or written to the first BIO then traverses the chain to the end (normally a source/sink BIO). + +Some BIOs (such as memory BIOs) can be used immediately after calling +BIO_new(). Others (such as file BIOs) need some additional initialization, +and frequently a utility function exists to create and initialize such BIOs. + +If BIO_free() is called on a BIO chain it will only free one BIO resulting +in a memory leak. + +Calling BIO_free_all() a single BIO has the same effect as calling BIO_free() +on it other than the discarded return value. + +Normally the B<type> argument is supplied by a function which returns a +pointer to a BIO_METHOD. There is a naming convention for such functions: +a source/sink BIO is normally called BIO_s_*() and a filter BIO +BIO_f_*(); + +=head1 EXAMPLE + +Create a memory BIO: + + BIO *mem = BIO_new(BIO_s_mem()); + =head1 SEE ALSO -L<BIO_ctrl(3)|BIO_ctrl(3)>, -L<BIO_f_base64(3)|BIO_f_base64(3)>, L<BIO_f_buffer(3)|BIO_f_buffer(3)>, -L<BIO_f_cipher(3)|BIO_f_cipher(3)>, L<BIO_f_md(3)|BIO_f_md(3)>, -L<BIO_f_null(3)|BIO_f_null(3)>, L<BIO_f_ssl(3)|BIO_f_ssl(3)>, -L<BIO_find_type(3)|BIO_find_type(3)>, L<BIO_new(3)|BIO_new(3)>, -L<BIO_new_bio_pair(3)|BIO_new_bio_pair(3)>, -L<BIO_push(3)|BIO_push(3)>, L<BIO_read(3)|BIO_read(3)>, -L<BIO_s_accept(3)|BIO_s_accept(3)>, L<BIO_s_bio(3)|BIO_s_bio(3)>, -L<BIO_s_connect(3)|BIO_s_connect(3)>, L<BIO_s_fd(3)|BIO_s_fd(3)>, -L<BIO_s_file(3)|BIO_s_file(3)>, L<BIO_s_mem(3)|BIO_s_mem(3)>, -L<BIO_s_null(3)|BIO_s_null(3)>, L<BIO_s_socket(3)|BIO_s_socket(3)>, -L<BIO_set_callback(3)|BIO_set_callback(3)>, -L<BIO_should_retry(3)|BIO_should_retry(3)> +L<BIO_ctrl(3)>, +L<BIO_f_base64(3)>, L<BIO_f_buffer(3)>, +L<BIO_f_cipher(3)>, L<BIO_f_md(3)>, +L<BIO_f_null(3)>, L<BIO_f_ssl(3)>, +L<BIO_find_type(3)>, L<BIO_new(3)>, +L<BIO_new_bio_pair(3)>, +L<BIO_push(3)>, L<BIO_read(3)>, +L<BIO_s_accept(3)>, L<BIO_s_bio(3)>, +L<BIO_s_connect(3)>, L<BIO_s_fd(3)>, +L<BIO_s_file(3)>, L<BIO_s_mem(3)>, +L<BIO_s_mem(3)>, +L<BIO_s_null(3)>, L<BIO_s_socket(3)>, +L<BIO_set_callback(3)>, +L<BIO_should_retry(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/bn.pod b/deps/openssl/openssl/doc/crypto/bn.pod deleted file mode 100644 index cd2f8e50c6..0000000000 --- a/deps/openssl/openssl/doc/crypto/bn.pod +++ /dev/null @@ -1,181 +0,0 @@ -=pod - -=head1 NAME - -bn - multiprecision integer arithmetics - -=head1 SYNOPSIS - - #include <openssl/bn.h> - - BIGNUM *BN_new(void); - void BN_free(BIGNUM *a); - void BN_init(BIGNUM *); - void BN_clear(BIGNUM *a); - void BN_clear_free(BIGNUM *a); - - BN_CTX *BN_CTX_new(void); - void BN_CTX_init(BN_CTX *c); - void BN_CTX_free(BN_CTX *c); - - BIGNUM *BN_copy(BIGNUM *a, const BIGNUM *b); - BIGNUM *BN_dup(const BIGNUM *a); - - BIGNUM *BN_swap(BIGNUM *a, BIGNUM *b); - - int BN_num_bytes(const BIGNUM *a); - int BN_num_bits(const BIGNUM *a); - int BN_num_bits_word(BN_ULONG w); - - void BN_set_negative(BIGNUM *a, int n); - int BN_is_negative(const BIGNUM *a); - - int BN_add(BIGNUM *r, const BIGNUM *a, const BIGNUM *b); - int BN_sub(BIGNUM *r, const BIGNUM *a, const BIGNUM *b); - int BN_mul(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); - int BN_sqr(BIGNUM *r, BIGNUM *a, BN_CTX *ctx); - int BN_div(BIGNUM *dv, BIGNUM *rem, const BIGNUM *a, const BIGNUM *d, - BN_CTX *ctx); - int BN_mod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); - int BN_nnmod(BIGNUM *rem, const BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); - int BN_mod_add(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m, - BN_CTX *ctx); - int BN_mod_sub(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m, - BN_CTX *ctx); - int BN_mod_mul(BIGNUM *ret, BIGNUM *a, BIGNUM *b, const BIGNUM *m, - BN_CTX *ctx); - int BN_mod_sqr(BIGNUM *ret, BIGNUM *a, const BIGNUM *m, BN_CTX *ctx); - int BN_exp(BIGNUM *r, BIGNUM *a, BIGNUM *p, BN_CTX *ctx); - int BN_mod_exp(BIGNUM *r, BIGNUM *a, const BIGNUM *p, - const BIGNUM *m, BN_CTX *ctx); - int BN_gcd(BIGNUM *r, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); - - int BN_add_word(BIGNUM *a, BN_ULONG w); - int BN_sub_word(BIGNUM *a, BN_ULONG w); - int BN_mul_word(BIGNUM *a, BN_ULONG w); - BN_ULONG BN_div_word(BIGNUM *a, BN_ULONG w); - BN_ULONG BN_mod_word(const BIGNUM *a, BN_ULONG w); - - int BN_cmp(BIGNUM *a, BIGNUM *b); - int BN_ucmp(BIGNUM *a, BIGNUM *b); - int BN_is_zero(BIGNUM *a); - int BN_is_one(BIGNUM *a); - int BN_is_word(BIGNUM *a, BN_ULONG w); - int BN_is_odd(BIGNUM *a); - - int BN_zero(BIGNUM *a); - int BN_one(BIGNUM *a); - const BIGNUM *BN_value_one(void); - int BN_set_word(BIGNUM *a, unsigned long w); - unsigned long BN_get_word(BIGNUM *a); - - int BN_rand(BIGNUM *rnd, int bits, int top, int bottom); - int BN_pseudo_rand(BIGNUM *rnd, int bits, int top, int bottom); - int BN_rand_range(BIGNUM *rnd, BIGNUM *range); - int BN_pseudo_rand_range(BIGNUM *rnd, BIGNUM *range); - - BIGNUM *BN_generate_prime(BIGNUM *ret, int bits,int safe, BIGNUM *add, - BIGNUM *rem, void (*callback)(int, int, void *), void *cb_arg); - int BN_is_prime(const BIGNUM *p, int nchecks, - void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg); - - int BN_set_bit(BIGNUM *a, int n); - int BN_clear_bit(BIGNUM *a, int n); - int BN_is_bit_set(const BIGNUM *a, int n); - int BN_mask_bits(BIGNUM *a, int n); - int BN_lshift(BIGNUM *r, const BIGNUM *a, int n); - int BN_lshift1(BIGNUM *r, BIGNUM *a); - int BN_rshift(BIGNUM *r, BIGNUM *a, int n); - int BN_rshift1(BIGNUM *r, BIGNUM *a); - - int BN_bn2bin(const BIGNUM *a, unsigned char *to); - BIGNUM *BN_bin2bn(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); - int BN_dec2bn(BIGNUM **a, const char *str); - int BN_print(BIO *fp, const BIGNUM *a); - int BN_print_fp(FILE *fp, const BIGNUM *a); - int BN_bn2mpi(const BIGNUM *a, unsigned char *to); - BIGNUM *BN_mpi2bn(unsigned char *s, int len, BIGNUM *ret); - - BIGNUM *BN_mod_inverse(BIGNUM *r, BIGNUM *a, const BIGNUM *n, - BN_CTX *ctx); - - BN_RECP_CTX *BN_RECP_CTX_new(void); - void BN_RECP_CTX_init(BN_RECP_CTX *recp); - void BN_RECP_CTX_free(BN_RECP_CTX *recp); - int BN_RECP_CTX_set(BN_RECP_CTX *recp, const BIGNUM *m, BN_CTX *ctx); - int BN_mod_mul_reciprocal(BIGNUM *r, BIGNUM *a, BIGNUM *b, - BN_RECP_CTX *recp, BN_CTX *ctx); - - BN_MONT_CTX *BN_MONT_CTX_new(void); - void BN_MONT_CTX_init(BN_MONT_CTX *ctx); - void BN_MONT_CTX_free(BN_MONT_CTX *mont); - int BN_MONT_CTX_set(BN_MONT_CTX *mont, const BIGNUM *m, BN_CTX *ctx); - BN_MONT_CTX *BN_MONT_CTX_copy(BN_MONT_CTX *to, BN_MONT_CTX *from); - int BN_mod_mul_montgomery(BIGNUM *r, BIGNUM *a, BIGNUM *b, - BN_MONT_CTX *mont, BN_CTX *ctx); - int BN_from_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont, - BN_CTX *ctx); - int BN_to_montgomery(BIGNUM *r, BIGNUM *a, BN_MONT_CTX *mont, - BN_CTX *ctx); - - BN_BLINDING *BN_BLINDING_new(const BIGNUM *A, const BIGNUM *Ai, - BIGNUM *mod); - void BN_BLINDING_free(BN_BLINDING *b); - int BN_BLINDING_update(BN_BLINDING *b,BN_CTX *ctx); - int BN_BLINDING_convert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx); - int BN_BLINDING_invert(BIGNUM *n, BN_BLINDING *b, BN_CTX *ctx); - int BN_BLINDING_convert_ex(BIGNUM *n, BIGNUM *r, BN_BLINDING *b, - BN_CTX *ctx); - int BN_BLINDING_invert_ex(BIGNUM *n,const BIGNUM *r,BN_BLINDING *b, - BN_CTX *ctx); - unsigned long BN_BLINDING_get_thread_id(const BN_BLINDING *); - void BN_BLINDING_set_thread_id(BN_BLINDING *, unsigned long); - unsigned long BN_BLINDING_get_flags(const BN_BLINDING *); - void BN_BLINDING_set_flags(BN_BLINDING *, unsigned long); - BN_BLINDING *BN_BLINDING_create_param(BN_BLINDING *b, - const BIGNUM *e, BIGNUM *m, BN_CTX *ctx, - int (*bn_mod_exp)(BIGNUM *r, const BIGNUM *a, const BIGNUM *p, - const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx), - BN_MONT_CTX *m_ctx); - -=head1 DESCRIPTION - -This library performs arithmetic operations on integers of arbitrary -size. It was written for use in public key cryptography, such as RSA -and Diffie-Hellman. - -It uses dynamic memory allocation for storing its data structures. -That means that there is no limit on the size of the numbers -manipulated by these functions, but return values must always be -checked in case a memory allocation error has occurred. - -The basic object in this library is a B<BIGNUM>. It is used to hold a -single large integer. This type should be considered opaque and fields -should not be modified or accessed directly. - -The creation of B<BIGNUM> objects is described in L<BN_new(3)|BN_new(3)>; -L<BN_add(3)|BN_add(3)> describes most of the arithmetic operations. -Comparison is described in L<BN_cmp(3)|BN_cmp(3)>; L<BN_zero(3)|BN_zero(3)> -describes certain assignments, L<BN_rand(3)|BN_rand(3)> the generation of -random numbers, L<BN_generate_prime(3)|BN_generate_prime(3)> deals with prime -numbers and L<BN_set_bit(3)|BN_set_bit(3)> with bit operations. The conversion -of B<BIGNUM>s to external formats is described in L<BN_bn2bin(3)|BN_bn2bin(3)>. - -=head1 SEE ALSO - -L<bn_internal(3)|bn_internal(3)>, -L<dh(3)|dh(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, -L<BN_new(3)|BN_new(3)>, L<BN_CTX_new(3)|BN_CTX_new(3)>, -L<BN_copy(3)|BN_copy(3)>, L<BN_swap(3)|BN_swap(3)>, L<BN_num_bytes(3)|BN_num_bytes(3)>, -L<BN_add(3)|BN_add(3)>, L<BN_add_word(3)|BN_add_word(3)>, -L<BN_cmp(3)|BN_cmp(3)>, L<BN_zero(3)|BN_zero(3)>, L<BN_rand(3)|BN_rand(3)>, -L<BN_generate_prime(3)|BN_generate_prime(3)>, L<BN_set_bit(3)|BN_set_bit(3)>, -L<BN_bn2bin(3)|BN_bn2bin(3)>, L<BN_mod_inverse(3)|BN_mod_inverse(3)>, -L<BN_mod_mul_reciprocal(3)|BN_mod_mul_reciprocal(3)>, -L<BN_mod_mul_montgomery(3)|BN_mod_mul_montgomery(3)>, -L<BN_BLINDING_new(3)|BN_BLINDING_new(3)> - -=cut diff --git a/deps/openssl/openssl/doc/crypto/bn_internal.pod b/deps/openssl/openssl/doc/crypto/bn_internal.pod deleted file mode 100644 index 91840b0f0d..0000000000 --- a/deps/openssl/openssl/doc/crypto/bn_internal.pod +++ /dev/null @@ -1,238 +0,0 @@ -=pod - -=head1 NAME - -bn_mul_words, bn_mul_add_words, bn_sqr_words, bn_div_words, -bn_add_words, bn_sub_words, bn_mul_comba4, bn_mul_comba8, -bn_sqr_comba4, bn_sqr_comba8, bn_cmp_words, bn_mul_normal, -bn_mul_low_normal, bn_mul_recursive, bn_mul_part_recursive, -bn_mul_low_recursive, bn_mul_high, bn_sqr_normal, bn_sqr_recursive, -bn_expand, bn_wexpand, bn_expand2, bn_fix_top, bn_check_top, -bn_print, bn_dump, bn_set_max, bn_set_high, bn_set_low - BIGNUM -library internal functions - -=head1 SYNOPSIS - - #include <openssl/bn.h> - - BN_ULONG bn_mul_words(BN_ULONG *rp, BN_ULONG *ap, int num, BN_ULONG w); - BN_ULONG bn_mul_add_words(BN_ULONG *rp, BN_ULONG *ap, int num, - BN_ULONG w); - void bn_sqr_words(BN_ULONG *rp, BN_ULONG *ap, int num); - BN_ULONG bn_div_words(BN_ULONG h, BN_ULONG l, BN_ULONG d); - BN_ULONG bn_add_words(BN_ULONG *rp, BN_ULONG *ap, BN_ULONG *bp, - int num); - BN_ULONG bn_sub_words(BN_ULONG *rp, BN_ULONG *ap, BN_ULONG *bp, - int num); - - void bn_mul_comba4(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b); - void bn_mul_comba8(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b); - void bn_sqr_comba4(BN_ULONG *r, BN_ULONG *a); - void bn_sqr_comba8(BN_ULONG *r, BN_ULONG *a); - - int bn_cmp_words(BN_ULONG *a, BN_ULONG *b, int n); - - void bn_mul_normal(BN_ULONG *r, BN_ULONG *a, int na, BN_ULONG *b, - int nb); - void bn_mul_low_normal(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, int n); - void bn_mul_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, int n2, - int dna,int dnb,BN_ULONG *tmp); - void bn_mul_part_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, - int n, int tna,int tnb, BN_ULONG *tmp); - void bn_mul_low_recursive(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, - int n2, BN_ULONG *tmp); - void bn_mul_high(BN_ULONG *r, BN_ULONG *a, BN_ULONG *b, BN_ULONG *l, - int n2, BN_ULONG *tmp); - - void bn_sqr_normal(BN_ULONG *r, BN_ULONG *a, int n, BN_ULONG *tmp); - void bn_sqr_recursive(BN_ULONG *r, BN_ULONG *a, int n2, BN_ULONG *tmp); - - void mul(BN_ULONG r, BN_ULONG a, BN_ULONG w, BN_ULONG c); - void mul_add(BN_ULONG r, BN_ULONG a, BN_ULONG w, BN_ULONG c); - void sqr(BN_ULONG r0, BN_ULONG r1, BN_ULONG a); - - BIGNUM *bn_expand(BIGNUM *a, int bits); - BIGNUM *bn_wexpand(BIGNUM *a, int n); - BIGNUM *bn_expand2(BIGNUM *a, int n); - void bn_fix_top(BIGNUM *a); - - void bn_check_top(BIGNUM *a); - void bn_print(BIGNUM *a); - void bn_dump(BN_ULONG *d, int n); - void bn_set_max(BIGNUM *a); - void bn_set_high(BIGNUM *r, BIGNUM *a, int n); - void bn_set_low(BIGNUM *r, BIGNUM *a, int n); - -=head1 DESCRIPTION - -This page documents the internal functions used by the OpenSSL -B<BIGNUM> implementation. They are described here to facilitate -debugging and extending the library. They are I<not> to be used by -applications. - -=head2 The BIGNUM structure - - typedef struct bignum_st BIGNUM; - - struct bignum_st - { - BN_ULONG *d; /* Pointer to an array of 'BN_BITS2' bit chunks. */ - int top; /* Index of last used d +1. */ - /* The next are internal book keeping for bn_expand. */ - int dmax; /* Size of the d array. */ - int neg; /* one if the number is negative */ - int flags; - }; - - -The integer value is stored in B<d>, a malloc()ed array of words (B<BN_ULONG>), -least significant word first. A B<BN_ULONG> can be either 16, 32 or 64 bits -in size, depending on the 'number of bits' (B<BITS2>) specified in -C<openssl/bn.h>. - -B<dmax> is the size of the B<d> array that has been allocated. B<top> -is the number of words being used, so for a value of 4, bn.d[0]=4 and -bn.top=1. B<neg> is 1 if the number is negative. When a B<BIGNUM> is -B<0>, the B<d> field can be B<NULL> and B<top> == B<0>. - -B<flags> is a bit field of flags which are defined in C<openssl/bn.h>. The -flags begin with B<BN_FLG_>. The macros BN_set_flags(b,n) and -BN_get_flags(b,n) exist to enable or fetch flag(s) B<n> from B<BIGNUM> -structure B<b>. - -Various routines in this library require the use of temporary -B<BIGNUM> variables during their execution. Since dynamic memory -allocation to create B<BIGNUM>s is rather expensive when used in -conjunction with repeated subroutine calls, the B<BN_CTX> structure is -used. This structure contains B<BN_CTX_NUM> B<BIGNUM>s, see -L<BN_CTX_start(3)|BN_CTX_start(3)>. - -=head2 Low-level arithmetic operations - -These functions are implemented in C and for several platforms in -assembly language: - -bn_mul_words(B<rp>, B<ap>, B<num>, B<w>) operates on the B<num> word -arrays B<rp> and B<ap>. It computes B<ap> * B<w>, places the result -in B<rp>, and returns the high word (carry). - -bn_mul_add_words(B<rp>, B<ap>, B<num>, B<w>) operates on the B<num> -word arrays B<rp> and B<ap>. It computes B<ap> * B<w> + B<rp>, places -the result in B<rp>, and returns the high word (carry). - -bn_sqr_words(B<rp>, B<ap>, B<n>) operates on the B<num> word array -B<ap> and the 2*B<num> word array B<ap>. It computes B<ap> * B<ap> -word-wise, and places the low and high bytes of the result in B<rp>. - -bn_div_words(B<h>, B<l>, B<d>) divides the two word number (B<h>,B<l>) -by B<d> and returns the result. - -bn_add_words(B<rp>, B<ap>, B<bp>, B<num>) operates on the B<num> word -arrays B<ap>, B<bp> and B<rp>. It computes B<ap> + B<bp>, places the -result in B<rp>, and returns the high word (carry). - -bn_sub_words(B<rp>, B<ap>, B<bp>, B<num>) operates on the B<num> word -arrays B<ap>, B<bp> and B<rp>. It computes B<ap> - B<bp>, places the -result in B<rp>, and returns the carry (1 if B<bp> E<gt> B<ap>, 0 -otherwise). - -bn_mul_comba4(B<r>, B<a>, B<b>) operates on the 4 word arrays B<a> and -B<b> and the 8 word array B<r>. It computes B<a>*B<b> and places the -result in B<r>. - -bn_mul_comba8(B<r>, B<a>, B<b>) operates on the 8 word arrays B<a> and -B<b> and the 16 word array B<r>. It computes B<a>*B<b> and places the -result in B<r>. - -bn_sqr_comba4(B<r>, B<a>, B<b>) operates on the 4 word arrays B<a> and -B<b> and the 8 word array B<r>. - -bn_sqr_comba8(B<r>, B<a>, B<b>) operates on the 8 word arrays B<a> and -B<b> and the 16 word array B<r>. - -The following functions are implemented in C: - -bn_cmp_words(B<a>, B<b>, B<n>) operates on the B<n> word arrays B<a> -and B<b>. It returns 1, 0 and -1 if B<a> is greater than, equal and -less than B<b>. - -bn_mul_normal(B<r>, B<a>, B<na>, B<b>, B<nb>) operates on the B<na> -word array B<a>, the B<nb> word array B<b> and the B<na>+B<nb> word -array B<r>. It computes B<a>*B<b> and places the result in B<r>. - -bn_mul_low_normal(B<r>, B<a>, B<b>, B<n>) operates on the B<n> word -arrays B<r>, B<a> and B<b>. It computes the B<n> low words of -B<a>*B<b> and places the result in B<r>. - -bn_mul_recursive(B<r>, B<a>, B<b>, B<n2>, B<dna>, B<dnb>, B<t>) operates -on the word arrays B<a> and B<b> of length B<n2>+B<dna> and B<n2>+B<dnb> -(B<dna> and B<dnb> are currently allowed to be 0 or negative) and the 2*B<n2> -word arrays B<r> and B<t>. B<n2> must be a power of 2. It computes -B<a>*B<b> and places the result in B<r>. - -bn_mul_part_recursive(B<r>, B<a>, B<b>, B<n>, B<tna>, B<tnb>, B<tmp>) -operates on the word arrays B<a> and B<b> of length B<n>+B<tna> and -B<n>+B<tnb> and the 4*B<n> word arrays B<r> and B<tmp>. - -bn_mul_low_recursive(B<r>, B<a>, B<b>, B<n2>, B<tmp>) operates on the -B<n2> word arrays B<r> and B<tmp> and the B<n2>/2 word arrays B<a> -and B<b>. - -bn_mul_high(B<r>, B<a>, B<b>, B<l>, B<n2>, B<tmp>) operates on the -B<n2> word arrays B<r>, B<a>, B<b> and B<l> (?) and the 3*B<n2> word -array B<tmp>. - -BN_mul() calls bn_mul_normal(), or an optimized implementation if the -factors have the same size: bn_mul_comba8() is used if they are 8 -words long, bn_mul_recursive() if they are larger than -B<BN_MULL_SIZE_NORMAL> and the size is an exact multiple of the word -size, and bn_mul_part_recursive() for others that are larger than -B<BN_MULL_SIZE_NORMAL>. - -bn_sqr_normal(B<r>, B<a>, B<n>, B<tmp>) operates on the B<n> word array -B<a> and the 2*B<n> word arrays B<tmp> and B<r>. - -The implementations use the following macros which, depending on the -architecture, may use "long long" C operations or inline assembler. -They are defined in C<bn_lcl.h>. - -mul(B<r>, B<a>, B<w>, B<c>) computes B<w>*B<a>+B<c> and places the -low word of the result in B<r> and the high word in B<c>. - -mul_add(B<r>, B<a>, B<w>, B<c>) computes B<w>*B<a>+B<r>+B<c> and -places the low word of the result in B<r> and the high word in B<c>. - -sqr(B<r0>, B<r1>, B<a>) computes B<a>*B<a> and places the low word -of the result in B<r0> and the high word in B<r1>. - -=head2 Size changes - -bn_expand() ensures that B<b> has enough space for a B<bits> bit -number. bn_wexpand() ensures that B<b> has enough space for an -B<n> word number. If the number has to be expanded, both macros -call bn_expand2(), which allocates a new B<d> array and copies the -data. They return B<NULL> on error, B<b> otherwise. - -The bn_fix_top() macro reduces B<a-E<gt>top> to point to the most -significant non-zero word plus one when B<a> has shrunk. - -=head2 Debugging - -bn_check_top() verifies that C<((a)-E<gt>top E<gt>= 0 && (a)-E<gt>top -E<lt>= (a)-E<gt>dmax)>. A violation will cause the program to abort. - -bn_print() prints B<a> to stderr. bn_dump() prints B<n> words at B<d> -(in reverse order, i.e. most significant word first) to stderr. - -bn_set_max() makes B<a> a static number with a B<dmax> of its current size. -This is used by bn_set_low() and bn_set_high() to make B<r> a read-only -B<BIGNUM> that contains the B<n> low or high words of B<a>. - -If B<BN_DEBUG> is not defined, bn_check_top(), bn_print(), bn_dump() -and bn_set_max() are defined as empty macros. - -=head1 SEE ALSO - -L<bn(3)|bn(3)> - -=cut diff --git a/deps/openssl/openssl/doc/crypto/buffer.pod b/deps/openssl/openssl/doc/crypto/buffer.pod deleted file mode 100644 index 52c5c841eb..0000000000 --- a/deps/openssl/openssl/doc/crypto/buffer.pod +++ /dev/null @@ -1,76 +0,0 @@ -=pod - -=head1 NAME - -BUF_MEM_new, BUF_MEM_new_ex, BUF_MEM_free, BUF_MEM_grow - simple -character array structure - -BUF_strdup, BUF_strndup, BUF_memdup, BUF_strlcpy, BUF_strlcat - -standard C library equivalents - -=head1 SYNOPSIS - - #include <openssl/buffer.h> - - BUF_MEM *BUF_MEM_new(void); - - void BUF_MEM_free(BUF_MEM *a); - - int BUF_MEM_grow(BUF_MEM *str, int len); - - char *BUF_strdup(const char *str); - - char *BUF_strndup(const char *str, size_t siz); - - void *BUF_memdup(const void *data, size_t siz); - - size_t BUF_strlcpy(char *dst, const char *src, size_t size); - - size_t BUF_strlcat(char *dst, const char *src, size_t size); - - size_t BUF_strnlen(const char *str, size_t maxlen); - -=head1 DESCRIPTION - -The buffer library handles simple character arrays. Buffers are used for -various purposes in the library, most notably memory BIOs. - -BUF_MEM_new() allocates a new buffer of zero size. - -BUF_MEM_free() frees up an already existing buffer. The data is zeroed -before freeing up in case the buffer contains sensitive data. - -BUF_MEM_grow() changes the size of an already existing buffer to -B<len>. Any data already in the buffer is preserved if it increases in -size. - -BUF_strdup(), BUF_strndup(), BUF_memdup(), BUF_strlcpy(), -BUF_strlcat() and BUF_strnlen are equivalents of the standard C -library functions. The dup() functions use OPENSSL_malloc() underneath -and so should be used in preference to the standard library for memory -leak checking or replacing the malloc() function. - -Memory allocated from these functions should be freed up using the -OPENSSL_free() function. - -BUF_strndup makes the explicit guarantee that it will never read past -the first B<siz> bytes of B<str>. - -=head1 RETURN VALUES - -BUF_MEM_new() returns the buffer or NULL on error. - -BUF_MEM_free() has no return value. - -BUF_MEM_grow() returns zero on error or the new size (i.e. B<len>). - -=head1 SEE ALSO - -L<bio(3)|bio(3)> - -=head1 HISTORY - -BUF_MEM_new(), BUF_MEM_free() and BUF_MEM_grow() are available in all -versions of SSLeay and OpenSSL. BUF_strdup() was added in SSLeay 0.8. - -=cut diff --git a/deps/openssl/openssl/doc/crypto/crypto.pod b/deps/openssl/openssl/doc/crypto/crypto.pod index f18edfe305..082f8435b2 100644 --- a/deps/openssl/openssl/doc/crypto/crypto.pod +++ b/deps/openssl/openssl/doc/crypto/crypto.pod @@ -1,11 +1,15 @@ =pod +=for comment openssl_manual_section:7 + =head1 NAME crypto - OpenSSL cryptographic library =head1 SYNOPSIS +See the individual manual pages for details. + =head1 DESCRIPTION The OpenSSL B<crypto> library implements a wide range of cryptographic @@ -14,53 +18,13 @@ by this library are used by the OpenSSL implementations of SSL, TLS and S/MIME, and they have also been used to implement SSH, OpenPGP, and other cryptographic standards. -=head1 OVERVIEW - B<libcrypto> consists of a number of sub-libraries that implement the individual algorithms. The functionality includes symmetric encryption, public key cryptography and key agreement, certificate handling, cryptographic -hash functions and a cryptographic pseudo-random number generator. - -=over 4 - -=item SYMMETRIC CIPHERS - -L<blowfish(3)|blowfish(3)>, L<cast(3)|cast(3)>, L<des(3)|des(3)>, -L<idea(3)|idea(3)>, L<rc2(3)|rc2(3)>, L<rc4(3)|rc4(3)>, L<rc5(3)|rc5(3)> - -=item PUBLIC KEY CRYPTOGRAPHY AND KEY AGREEMENT - -L<dsa(3)|dsa(3)>, L<dh(3)|dh(3)>, L<rsa(3)|rsa(3)> - -=item CERTIFICATES - -L<x509(3)|x509(3)>, L<x509v3(3)|x509v3(3)> - -=item AUTHENTICATION CODES, HASH FUNCTIONS - -L<hmac(3)|hmac(3)>, L<md2(3)|md2(3)>, L<md4(3)|md4(3)>, -L<md5(3)|md5(3)>, L<mdc2(3)|mdc2(3)>, L<ripemd(3)|ripemd(3)>, -L<sha(3)|sha(3)> - -=item AUXILIARY FUNCTIONS - -L<err(3)|err(3)>, L<threads(3)|threads(3)>, L<rand(3)|rand(3)>, -L<OPENSSL_VERSION_NUMBER(3)|OPENSSL_VERSION_NUMBER(3)> - -=item INPUT/OUTPUT, DATA ENCODING - -L<asn1(3)|asn1(3)>, L<bio(3)|bio(3)>, L<evp(3)|evp(3)>, L<pem(3)|pem(3)>, -L<pkcs7(3)|pkcs7(3)>, L<pkcs12(3)|pkcs12(3)> - -=item INTERNAL FUNCTIONS - -L<bn(3)|bn(3)>, L<buffer(3)|buffer(3)>, L<ec(3)|ec(3)>, L<lhash(3)|lhash(3)>, -L<objects(3)|objects(3)>, L<stack(3)|stack(3)>, -L<txt_db(3)|txt_db(3)> - -=back +hash functions, cryptographic pseudo-random number generator, and +various utilities. =head1 NOTES @@ -68,7 +32,7 @@ Some of the newer functions follow a naming convention using the numbers B<0> and B<1>. For example the functions: int X509_CRL_add0_revoked(X509_CRL *crl, X509_REVOKED *rev); - int X509_add1_trust_object(X509 *x, ASN1_OBJECT *obj); + int X509_add1_trust_object(X509 *x, const ASN1_OBJECT *obj); The B<0> version uses the supplied structure pointer directly in the parent and it will be freed up when the parent is freed. @@ -78,8 +42,21 @@ The B<1> function uses a copy of the supplied structure pointer (or in some cases increases its link count) in the parent and so both (B<x> and B<obj> above) should be freed up. +=head1 RETURN VALUES + +See the individual manual pages for details. + =head1 SEE ALSO -L<openssl(1)|openssl(1)>, L<ssl(3)|ssl(3)> +L<openssl(1)>, L<ssl(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/ct.pod b/deps/openssl/openssl/doc/crypto/ct.pod new file mode 100644 index 0000000000..60718b3f6d --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/ct.pod @@ -0,0 +1,55 @@ +=pod + +=for comment openssl_manual_section:7 + +=head1 NAME + +ct - Certificate Transparency + +=head1 SYNOPSIS + + #include <openssl/ct.h> + +=head1 DESCRIPTION + +This library implements Certificate Transparency (CT) verification for TLS +clients, as defined in RFC 6962. This verification can provide some confidence +that a certificate has been publicly logged in a set of CT logs. + +By default, these checks are disabled. They can be enabled using +SSL_CTX_ct_enable() or SSL_ct_enable(). + +This library can also be used to parse and examine CT data structures, such as +Signed Certificate Timestamps (SCTs), or to read a list of CT logs. There are +functions for: +- decoding and encoding SCTs in DER and TLS wire format. +- printing SCTs. +- verifying the authenticity of SCTs. +- loading a CT log list from a CONF file. + +=head1 SEE ALSO + +L<d2i_SCT_LIST(3)>, +L<CTLOG_STORE_new(3)>, +L<CTLOG_STORE_get0_log_by_id(3)>, +L<SCT_new(3)>, +L<SCT_print(3)>, +L<SCT_validate(3)>, +L<SCT_validate(3)>, +L<CT_POLICY_EVAL_CTX_new(3)>, +L<SSL_CTX_set_ct_validation_callback(3)> + +=head1 HISTORY + +This library was added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/d2i_ASN1_OBJECT.pod b/deps/openssl/openssl/doc/crypto/d2i_ASN1_OBJECT.pod deleted file mode 100644 index 45bb18492c..0000000000 --- a/deps/openssl/openssl/doc/crypto/d2i_ASN1_OBJECT.pod +++ /dev/null @@ -1,29 +0,0 @@ -=pod - -=head1 NAME - -d2i_ASN1_OBJECT, i2d_ASN1_OBJECT - ASN1 OBJECT IDENTIFIER functions - -=head1 SYNOPSIS - - #include <openssl/objects.h> - - ASN1_OBJECT *d2i_ASN1_OBJECT(ASN1_OBJECT **a, unsigned char **pp, long length); - int i2d_ASN1_OBJECT(ASN1_OBJECT *a, unsigned char **pp); - -=head1 DESCRIPTION - -These functions decode and encode an ASN1 OBJECT IDENTIFIER. - -Othewise these behave in a similar way to d2i_X509() and i2d_X509() -described in the L<d2i_X509(3)|d2i_X509(3)> manual page. - -=head1 SEE ALSO - -L<d2i_X509(3)|d2i_X509(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/deps/openssl/openssl/doc/crypto/d2i_CMS_ContentInfo.pod b/deps/openssl/openssl/doc/crypto/d2i_CMS_ContentInfo.pod deleted file mode 100644 index 6ddb2f6d05..0000000000 --- a/deps/openssl/openssl/doc/crypto/d2i_CMS_ContentInfo.pod +++ /dev/null @@ -1,29 +0,0 @@ -=pod - -=head1 NAME - -d2i_CMS_ContentInfo, i2d_CMS_ContentInfo - CMS ContentInfo functions - -=head1 SYNOPSIS - - #include <openssl/cms.h> - - CMS_ContentInfo *d2i_CMS_ContentInfo(CMS_ContentInfo **a, unsigned char **pp, long length); - int i2d_CMS_ContentInfo(CMS_ContentInfo *a, unsigned char **pp); - -=head1 DESCRIPTION - -These functions decode and encode an CMS ContentInfo structure. - -Otherwise they behave in a similar way to d2i_X509() and i2d_X509() -described in the L<d2i_X509(3)|d2i_X509(3)> manual page. - -=head1 SEE ALSO - -L<d2i_X509(3)|d2i_X509(3)> - -=head1 HISTORY - -These functions were first added to OpenSSL 0.9.8 - -=cut diff --git a/deps/openssl/openssl/doc/crypto/d2i_DHparams.pod b/deps/openssl/openssl/doc/crypto/d2i_DHparams.pod index 1e98aebeca..cd1c162b40 100644 --- a/deps/openssl/openssl/doc/crypto/d2i_DHparams.pod +++ b/deps/openssl/openssl/doc/crypto/d2i_DHparams.pod @@ -2,7 +2,7 @@ =head1 NAME -d2i_DHparams, i2d_DHparams - PKCS#3 DH parameter functions. +d2i_DHparams, i2d_DHparams - PKCS#3 DH parameter functions =head1 SYNOPSIS @@ -16,15 +16,20 @@ d2i_DHparams, i2d_DHparams - PKCS#3 DH parameter functions. These functions decode and encode PKCS#3 DH parameters using the DHparameter structure described in PKCS#3. -Othewise these behave in a similar way to d2i_X509() and i2d_X509() -described in the L<d2i_X509(3)|d2i_X509(3)> manual page. +Otherwise these behave in a similar way to d2i_X509() and i2d_X509() +described in the L<d2i_X509(3)> manual page. =head1 SEE ALSO -L<d2i_X509(3)|d2i_X509(3)> +L<d2i_X509(3)> -=head1 HISTORY +=head1 COPYRIGHT -TBA +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/d2i_DSAPublicKey.pod b/deps/openssl/openssl/doc/crypto/d2i_DSAPublicKey.pod deleted file mode 100644 index e999376492..0000000000 --- a/deps/openssl/openssl/doc/crypto/d2i_DSAPublicKey.pod +++ /dev/null @@ -1,83 +0,0 @@ -=pod - -=head1 NAME - -d2i_DSAPublicKey, i2d_DSAPublicKey, d2i_DSAPrivateKey, i2d_DSAPrivateKey, -d2i_DSA_PUBKEY, i2d_DSA_PUBKEY, d2i_DSAparams, i2d_DSAparams, d2i_DSA_SIG, i2d_DSA_SIG - DSA key encoding -and parsing functions. - -=head1 SYNOPSIS - - #include <openssl/dsa.h> - #include <openssl/x509.h> - - DSA * d2i_DSAPublicKey(DSA **a, const unsigned char **pp, long length); - - int i2d_DSAPublicKey(const DSA *a, unsigned char **pp); - - DSA * d2i_DSA_PUBKEY(DSA **a, const unsigned char **pp, long length); - - int i2d_DSA_PUBKEY(const DSA *a, unsigned char **pp); - - DSA * d2i_DSAPrivateKey(DSA **a, const unsigned char **pp, long length); - - int i2d_DSAPrivateKey(const DSA *a, unsigned char **pp); - - DSA * d2i_DSAparams(DSA **a, const unsigned char **pp, long length); - - int i2d_DSAparams(const DSA *a, unsigned char **pp); - - DSA * d2i_DSA_SIG(DSA_SIG **a, const unsigned char **pp, long length); - - int i2d_DSA_SIG(const DSA_SIG *a, unsigned char **pp); - -=head1 DESCRIPTION - -d2i_DSAPublicKey() and i2d_DSAPublicKey() decode and encode the DSA public key -components structure. - -d2i_DSA_PUBKEY() and i2d_DSA_PUBKEY() decode and encode an DSA public key using -a SubjectPublicKeyInfo (certificate public key) structure. - -d2i_DSAPrivateKey(), i2d_DSAPrivateKey() decode and encode the DSA private key -components. - -d2i_DSAparams(), i2d_DSAparams() decode and encode the DSA parameters using -a B<Dss-Parms> structure as defined in RFC2459. - -d2i_DSA_SIG(), i2d_DSA_SIG() decode and encode a DSA signature using a -B<Dss-Sig-Value> structure as defined in RFC2459. - -The usage of all of these functions is similar to the d2i_X509() and -i2d_X509() described in the L<d2i_X509(3)|d2i_X509(3)> manual page. - -=head1 NOTES - -The B<DSA> structure passed to the private key encoding functions should have -all the private key components present. - -The data encoded by the private key functions is unencrypted and therefore -offers no private key security. - -The B<DSA_PUBKEY> functions should be used in preference to the B<DSAPublicKey> -functions when encoding public keys because they use a standard format. - -The B<DSAPublicKey> functions use an non standard format the actual data encoded -depends on the value of the B<write_params> field of the B<a> key parameter. -If B<write_params> is zero then only the B<pub_key> field is encoded as an -B<INTEGER>. If B<write_params> is 1 then a B<SEQUENCE> consisting of the -B<p>, B<q>, B<g> and B<pub_key> respectively fields are encoded. - -The B<DSAPrivateKey> functions also use a non standard structure consiting -consisting of a SEQUENCE containing the B<p>, B<q>, B<g> and B<pub_key> and -B<priv_key> fields respectively. - -=head1 SEE ALSO - -L<d2i_X509(3)|d2i_X509(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/deps/openssl/openssl/doc/crypto/d2i_ECPKParameters.pod b/deps/openssl/openssl/doc/crypto/d2i_ECPKParameters.pod deleted file mode 100644 index 704b4ab352..0000000000 --- a/deps/openssl/openssl/doc/crypto/d2i_ECPKParameters.pod +++ /dev/null @@ -1,84 +0,0 @@ -=pod - -=head1 NAME - -d2i_ECPKParameters, i2d_ECPKParameters, d2i_ECPKParameters_bio, i2d_ECPKParameters_bio, d2i_ECPKParameters_fp, i2d_ECPKParameters_fp, ECPKParameters_print, ECPKParameters_print_fp - Functions for decoding and encoding ASN1 representations of elliptic curve entities - -=head1 SYNOPSIS - - #include <openssl/ec.h> - - EC_GROUP *d2i_ECPKParameters(EC_GROUP **px, const unsigned char **in, long len); - int i2d_ECPKParameters(const EC_GROUP *x, unsigned char **out); - #define d2i_ECPKParameters_bio(bp,x) ASN1_d2i_bio_of(EC_GROUP,NULL,d2i_ECPKParameters,bp,x) - #define i2d_ECPKParameters_bio(bp,x) ASN1_i2d_bio_of_const(EC_GROUP,i2d_ECPKParameters,bp,x) - #define d2i_ECPKParameters_fp(fp,x) (EC_GROUP *)ASN1_d2i_fp(NULL, \ - (char *(*)())d2i_ECPKParameters,(fp),(unsigned char **)(x)) - #define i2d_ECPKParameters_fp(fp,x) ASN1_i2d_fp(i2d_ECPKParameters,(fp), \ - (unsigned char *)(x)) - int ECPKParameters_print(BIO *bp, const EC_GROUP *x, int off); - int ECPKParameters_print_fp(FILE *fp, const EC_GROUP *x, int off); - - -=head1 DESCRIPTION - -The ECPKParameters encode and decode routines encode and parse the public parameters for an -B<EC_GROUP> structure, which represents a curve. - -d2i_ECPKParameters() attempts to decode B<len> bytes at B<*in>. If -successful a pointer to the B<EC_GROUP> structure is returned. If an error -occurred then B<NULL> is returned. If B<px> is not B<NULL> then the -returned structure is written to B<*px>. If B<*px> is not B<NULL> -then it is assumed that B<*px> contains a valid B<EC_GROUP> -structure and an attempt is made to reuse it. If the call is -successful B<*in> is incremented to the byte following the -parsed data. - -i2d_ECPKParameters() encodes the structure pointed to by B<x> into DER format. -If B<out> is not B<NULL> is writes the DER encoded data to the buffer -at B<*out>, and increments it to point after the data just written. -If the return value is negative an error occurred, otherwise it -returns the length of the encoded data. - -If B<*out> is B<NULL> memory will be allocated for a buffer and the encoded -data written to it. In this case B<*out> is not incremented and it points to -the start of the data just written. - -d2i_ECPKParameters_bio() is similar to d2i_ECPKParameters() except it attempts -to parse data from BIO B<bp>. - -d2i_ECPKParameters_fp() is similar to d2i_ECPKParameters() except it attempts -to parse data from FILE pointer B<fp>. - -i2d_ECPKParameters_bio() is similar to i2d_ECPKParameters() except it writes -the encoding of the structure B<x> to BIO B<bp> and it -returns 1 for success and 0 for failure. - -i2d_ECPKParameters_fp() is similar to i2d_ECPKParameters() except it writes -the encoding of the structure B<x> to BIO B<bp> and it -returns 1 for success and 0 for failure. - -These functions are very similar to the X509 functions described in L<d2i_X509(3)|d2i_X509(3)>, -where further notes and examples are available. - -The ECPKParameters_print and ECPKParameters_print_fp functions print a human-readable output -of the public parameters of the EC_GROUP to B<bp> or B<fp>. The output lines are indented by B<off> spaces. - -=head1 RETURN VALUES - -d2i_ECPKParameters(), d2i_ECPKParameters_bio() and d2i_ECPKParameters_fp() return a valid B<EC_GROUP> structure -or B<NULL> if an error occurs. - -i2d_ECPKParameters() returns the number of bytes successfully encoded or a negative -value if an error occurs. - -i2d_ECPKParameters_bio(), i2d_ECPKParameters_fp(), ECPKParameters_print and ECPKParameters_print_fp -return 1 for success and 0 if an error occurs. - -=head1 SEE ALSO - -L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, -L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>, -L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_X509(3)|d2i_X509(3)> - -=cut diff --git a/deps/openssl/openssl/doc/crypto/d2i_ECPrivateKey.pod b/deps/openssl/openssl/doc/crypto/d2i_ECPrivateKey.pod deleted file mode 100644 index adeffe643c..0000000000 --- a/deps/openssl/openssl/doc/crypto/d2i_ECPrivateKey.pod +++ /dev/null @@ -1,67 +0,0 @@ -=pod - -=head1 NAME - -i2d_ECPrivateKey, d2i_ECPrivate_key - Encode and decode functions for saving and -reading EC_KEY structures - -=head1 SYNOPSIS - - #include <openssl/ec.h> - - EC_KEY *d2i_ECPrivateKey(EC_KEY **key, const unsigned char **in, long len); - int i2d_ECPrivateKey(EC_KEY *key, unsigned char **out); - - unsigned int EC_KEY_get_enc_flags(const EC_KEY *key); - void EC_KEY_set_enc_flags(EC_KEY *eckey, unsigned int flags); - -=head1 DESCRIPTION - -The ECPrivateKey encode and decode routines encode and parse an -B<EC_KEY> structure into a binary format (ASN.1 DER) and back again. - -These functions are similar to the d2i_X509() functions, and you should refer to -that page for a detailed description (see L<d2i_X509(3)|d2i_X509(3)>). - -The format of the external representation of the public key written by -i2d_ECPrivateKey (such as whether it is stored in a compressed form or not) is -described by the point_conversion_form. See L<EC_GROUP_copy(3)|EC_GROUP_copy(3)> -for a description of point_conversion_form. - -When reading a private key encoded without an associated public key (e.g. if -EC_PKEY_NO_PUBKEY has been used - see below), then d2i_ECPrivateKey generates -the missing public key automatically. Private keys encoded without parameters -(e.g. if EC_PKEY_NO_PARAMETERS has been used - see below) cannot be loaded using -d2i_ECPrivateKey. - -The functions EC_KEY_get_enc_flags and EC_KEY_set_enc_flags get and set the -value of the encoding flags for the B<key>. There are two encoding flags -currently defined - EC_PKEY_NO_PARAMETERS and EC_PKEY_NO_PUBKEY. These flags -define the behaviour of how the B<key> is converted into ASN1 in a call to -i2d_ECPrivateKey. If EC_PKEY_NO_PARAMETERS is set then the public parameters for -the curve are not encoded along with the private key. If EC_PKEY_NO_PUBKEY is -set then the public key is not encoded along with the private key. - -=head1 RETURN VALUES - -d2i_ECPrivateKey() returns a valid B<EC_KEY> structure or B<NULL> if an error -occurs. The error code that can be obtained by -L<ERR_get_error(3)|ERR_get_error(3)>. - -i2d_ECPrivateKey() returns the number of bytes successfully encoded or a -negative value if an error occurs. The error code can be obtained by -L<ERR_get_error(3)|ERR_get_error(3)>. - -EC_KEY_get_enc_flags returns the value of the current encoding flags for the -EC_KEY. - -=head1 SEE ALSO - -L<crypto(3)|crypto(3)>, L<ec(3)|ec(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, -L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, L<EC_POINT_new(3)|EC_POINT_new(3)>, -L<EC_POINT_add(3)|EC_POINT_add(3)>, -L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, -L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>, -L<d2i_ECPrivateKey(3)|d2i_ECPrivateKey(3)> - -=cut diff --git a/deps/openssl/openssl/doc/crypto/d2i_Netscape_RSA.pod b/deps/openssl/openssl/doc/crypto/d2i_Netscape_RSA.pod new file mode 100644 index 0000000000..ee39bd817a --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/d2i_Netscape_RSA.pod @@ -0,0 +1,38 @@ +=pod + +=head1 NAME + +i2d_Netscape_RSA, +d2i_Netscape_RSA +- insecure RSA public and private key encoding functions + +=head1 SYNOPSIS + + #include <openssl/rsa.h> + + int i2d_Netscape_RSA(RSA *a, unsigned char **pp, int (*cb)()); + RSA * d2i_Netscape_RSA(RSA **a, const unsigned char **pp, long length, int (*cb)()); + +=head1 DESCRIPTION + +These functions decode and encode an RSA private +key in NET format. These functions are present to provide compatibility +with very old software. This format has some severe security weaknesses +and should be avoided if possible. + +These functions are similar to the B<d2i_RSAPrivateKey> functions. + +=head1 SEE ALSO + +L<d2i_RSAPrivateKey(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/d2i_PKCS8PrivateKey.pod b/deps/openssl/openssl/doc/crypto/d2i_PKCS8PrivateKey_bio.pod index a54b779088..164d93ff4f 100644 --- a/deps/openssl/openssl/doc/crypto/d2i_PKCS8PrivateKey.pod +++ b/deps/openssl/openssl/doc/crypto/d2i_PKCS8PrivateKey_bio.pod @@ -14,20 +14,20 @@ i2d_PKCS8PrivateKey_nid_bio, i2d_PKCS8PrivateKey_nid_fp - PKCS#8 format private 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, - char *kstr, int klen, - pem_password_cb *cb, void *u); + char *kstr, int klen, + pem_password_cb *cb, void *u); int i2d_PKCS8PrivateKey_fp(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc, - char *kstr, int klen, - pem_password_cb *cb, void *u); + char *kstr, int klen, + pem_password_cb *cb, void *u); int i2d_PKCS8PrivateKey_nid_bio(BIO *bp, EVP_PKEY *x, int nid, - char *kstr, int klen, - pem_password_cb *cb, void *u); + char *kstr, int klen, + pem_password_cb *cb, void *u); int i2d_PKCS8PrivateKey_nid_fp(FILE *fp, EVP_PKEY *x, int nid, - char *kstr, int klen, - pem_password_cb *cb, void *u); + char *kstr, int klen, + pem_password_cb *cb, void *u); =head1 DESCRIPTION @@ -35,22 +35,27 @@ The PKCS#8 functions encode and decode private keys in PKCS#8 format using both PKCS#5 v1.5 and PKCS#5 v2.0 password based encryption algorithms. Other than the use of DER as opposed to PEM these functions are identical to the -corresponding B<PEM> function as described in the L<pem(3)|pem(3)> manual page. +corresponding B<PEM> function as described in L<PEM_read_PrivateKey(3)>. =head1 NOTES -Before using these functions L<OpenSSL_add_all_algorithms(3)|OpenSSL_add_all_algorithms(3)> -should be called to initialize the internal algorithm lookup tables otherwise errors about -unknown algorithms will occur if an attempt is made to decrypt a private key. - These functions are currently the only way to store encrypted private keys using DER format. Currently all the functions use BIOs or FILE pointers, there are no functions which work directly on memory: this can be readily worked around by converting the buffers -to memory BIOs, see L<BIO_s_mem(3)|BIO_s_mem(3)> for details. +to memory BIOs, see L<BIO_s_mem(3)> for details. =head1 SEE ALSO -L<pem(3)|pem(3)> +L<PEM_read_PrivateKey(3)> + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/d2i_PrivateKey.pod b/deps/openssl/openssl/doc/crypto/d2i_PrivateKey.pod index e06ab6c5de..f5b4667acd 100644 --- a/deps/openssl/openssl/doc/crypto/d2i_PrivateKey.pod +++ b/deps/openssl/openssl/doc/crypto/d2i_PrivateKey.pod @@ -2,8 +2,10 @@ =head1 NAME -d2i_Private_key, d2i_AutoPrivateKey, i2d_PrivateKey - decode and encode -functions for reading and saving EVP_PKEY structures. +d2i_PrivateKey, d2i_PublicKey, d2i_AutoPrivateKey, +i2d_PrivateKey, i2d_PublicKey, +d2i_PrivateKey_bio, d2i_PrivateKey_fp +- decode and encode functions for reading and saving EVP_PKEY structures =head1 SYNOPSIS @@ -11,9 +13,15 @@ functions for reading and saving EVP_PKEY structures. EVP_PKEY *d2i_PrivateKey(int type, EVP_PKEY **a, const unsigned char **pp, long length); + EVP_PKEY *d2i_PublicKey(int type, EVP_PKEY **a, const unsigned char **pp, + 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); + + EVP_PKEY *d2i_PrivateKey_bio(BIO *bp, EVP_PKEY **a); + EVP_PKEY *d2i_PrivateKey_fp(FILE *fp, EVP_PKEY **a) =head1 DESCRIPTION @@ -21,15 +29,16 @@ d2i_PrivateKey() decodes a private key using algorithm B<type>. It attempts to use any key specific format or PKCS#8 unencrypted PrivateKeyInfo format. The B<type> parameter should be a public key algorithm constant such as B<EVP_PKEY_RSA>. An error occurs if the decoded key does not match B<type>. +d2i_PublicKey() does the same for public keys. d2i_AutoPrivateKey() is similar to d2i_PrivateKey() except it attempts to automatically detect the private key format. i2d_PrivateKey() encodes B<key>. It uses a key specific format or, if none is defined for that key type, PKCS#8 unencrypted PrivateKeyInfo format. +i2d_PublicKey() does the same for public keys. -These functions are similar to the d2i_X509() functions, and you should refer to -that page for a detailed description (see L<d2i_X509(3)>). +These functions are similar to the d2i_X509() functions; see L<d2i_X509(3)>. =head1 NOTES @@ -53,7 +62,16 @@ L<ERR_get_error(3)>. =head1 SEE ALSO -L<crypto(3)>, -L<d2i_PKCS8PrivateKey(3)> +L<crypto(7)>, +L<d2i_PKCS8PrivateKey_bio(3)> + +=head1 COPYRIGHT + +Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/d2i_RSAPublicKey.pod b/deps/openssl/openssl/doc/crypto/d2i_RSAPublicKey.pod deleted file mode 100644 index aa6078bcf6..0000000000 --- a/deps/openssl/openssl/doc/crypto/d2i_RSAPublicKey.pod +++ /dev/null @@ -1,67 +0,0 @@ -=pod - -=head1 NAME - -d2i_RSAPublicKey, i2d_RSAPublicKey, d2i_RSAPrivateKey, i2d_RSAPrivateKey, -d2i_RSA_PUBKEY, i2d_RSA_PUBKEY, i2d_Netscape_RSA, -d2i_Netscape_RSA - RSA public and private key encoding functions. - -=head1 SYNOPSIS - - #include <openssl/rsa.h> - #include <openssl/x509.h> - - RSA * d2i_RSAPublicKey(RSA **a, const unsigned char **pp, long length); - - int i2d_RSAPublicKey(RSA *a, unsigned char **pp); - - RSA * d2i_RSA_PUBKEY(RSA **a, const unsigned char **pp, long length); - - int i2d_RSA_PUBKEY(RSA *a, unsigned char **pp); - - RSA * d2i_RSAPrivateKey(RSA **a, const unsigned char **pp, long length); - - int i2d_RSAPrivateKey(RSA *a, unsigned char **pp); - - int i2d_Netscape_RSA(RSA *a, unsigned char **pp, int (*cb)()); - - RSA * d2i_Netscape_RSA(RSA **a, const unsigned char **pp, long length, int (*cb)()); - -=head1 DESCRIPTION - -d2i_RSAPublicKey() and i2d_RSAPublicKey() decode and encode a PKCS#1 RSAPublicKey -structure. - -d2i_RSA_PUBKEY() and i2d_RSA_PUBKEY() decode and encode an RSA public key using -a SubjectPublicKeyInfo (certificate public key) structure. - -d2i_RSAPrivateKey(), i2d_RSAPrivateKey() decode and encode a PKCS#1 RSAPrivateKey -structure. - -d2i_Netscape_RSA(), i2d_Netscape_RSA() decode and encode an RSA private key in -NET format. - -The usage of all of these functions is similar to the d2i_X509() and -i2d_X509() described in the L<d2i_X509(3)|d2i_X509(3)> manual page. - -=head1 NOTES - -The B<RSA> structure passed to the private key encoding functions should have -all the PKCS#1 private key components present. - -The data encoded by the private key functions is unencrypted and therefore -offers no private key security. - -The NET format functions are present to provide compatibility with certain very -old software. This format has some severe security weaknesses and should be -avoided if possible. - -=head1 SEE ALSO - -L<d2i_X509(3)|d2i_X509(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/deps/openssl/openssl/doc/crypto/d2i_X509.pod b/deps/openssl/openssl/doc/crypto/d2i_X509.pod index 2743bc73e7..1fbe5cad4e 100644 --- a/deps/openssl/openssl/doc/crypto/d2i_X509.pod +++ b/deps/openssl/openssl/doc/crypto/d2i_X509.pod @@ -2,214 +2,555 @@ =head1 NAME -d2i_X509, i2d_X509, d2i_X509_bio, d2i_X509_fp, i2d_X509_bio, -i2d_X509_fp - X509 encode and decode functions +d2i_ACCESS_DESCRIPTION, +d2i_ASIdOrRange, +d2i_ASIdentifierChoice, +d2i_ASIdentifiers, +d2i_ASN1_BIT_STRING, +d2i_ASN1_BMPSTRING, +d2i_ASN1_ENUMERATED, +d2i_ASN1_GENERALIZEDTIME, +d2i_ASN1_GENERALSTRING, +d2i_ASN1_IA5STRING, +d2i_ASN1_INTEGER, +d2i_ASN1_NULL, +d2i_ASN1_OBJECT, +d2i_ASN1_OCTET_STRING, +d2i_ASN1_PRINTABLE, +d2i_ASN1_PRINTABLESTRING, +d2i_ASN1_SEQUENCE_ANY, +d2i_ASN1_SET_ANY, +d2i_ASN1_T61STRING, +d2i_ASN1_TIME, +d2i_ASN1_TYPE, +d2i_ASN1_UINTEGER, +d2i_ASN1_UNIVERSALSTRING, +d2i_ASN1_UTCTIME, +d2i_ASN1_UTF8STRING, +d2i_ASN1_VISIBLESTRING, +d2i_ASRange, +d2i_AUTHORITY_INFO_ACCESS, +d2i_AUTHORITY_KEYID, +d2i_BASIC_CONSTRAINTS, +d2i_CERTIFICATEPOLICIES, +d2i_CMS_ContentInfo, +d2i_CMS_ReceiptRequest, +d2i_CMS_bio, +d2i_CRL_DIST_POINTS, +d2i_DHxparams, +d2i_DIRECTORYSTRING, +d2i_DISPLAYTEXT, +d2i_DIST_POINT, +d2i_DIST_POINT_NAME, +d2i_DSAPrivateKey, +d2i_DSAPrivateKey_bio, +d2i_DSAPrivateKey_fp, +d2i_DSAPublicKey, +d2i_DSA_PUBKEY, +d2i_DSA_PUBKEY_bio, +d2i_DSA_PUBKEY_fp, +d2i_DSA_SIG, +d2i_DSAparams, +d2i_ECPKParameters, +d2i_ECParameters, +d2i_ECPrivateKey, +d2i_ECPrivateKey_bio, +d2i_ECPrivateKey_fp, +d2i_EC_PUBKEY, +d2i_EC_PUBKEY_bio, +d2i_EC_PUBKEY_fp, +d2i_EDIPARTYNAME, +d2i_ESS_CERT_ID, +d2i_ESS_ISSUER_SERIAL, +d2i_ESS_SIGNING_CERT, +d2i_EXTENDED_KEY_USAGE, +d2i_GENERAL_NAME, +d2i_GENERAL_NAMES, +d2i_IPAddressChoice, +d2i_IPAddressFamily, +d2i_IPAddressOrRange, +d2i_IPAddressRange, +d2i_ISSUING_DIST_POINT, +d2i_NETSCAPE_CERT_SEQUENCE, +d2i_NETSCAPE_SPKAC, +d2i_NETSCAPE_SPKI, +d2i_NOTICEREF, +d2i_OCSP_BASICRESP, +d2i_OCSP_CERTID, +d2i_OCSP_CERTSTATUS, +d2i_OCSP_CRLID, +d2i_OCSP_ONEREQ, +d2i_OCSP_REQINFO, +d2i_OCSP_REQUEST, +d2i_OCSP_RESPBYTES, +d2i_OCSP_RESPDATA, +d2i_OCSP_RESPID, +d2i_OCSP_RESPONSE, +d2i_OCSP_REVOKEDINFO, +d2i_OCSP_SERVICELOC, +d2i_OCSP_SIGNATURE, +d2i_OCSP_SINGLERESP, +d2i_OTHERNAME, +d2i_PBE2PARAM, +d2i_PBEPARAM, +d2i_PBKDF2PARAM, +d2i_PKCS12, +d2i_PKCS12_BAGS, +d2i_PKCS12_MAC_DATA, +d2i_PKCS12_SAFEBAG, +d2i_PKCS12_bio, +d2i_PKCS12_fp, +d2i_PKCS7, +d2i_PKCS7_DIGEST, +d2i_PKCS7_ENCRYPT, +d2i_PKCS7_ENC_CONTENT, +d2i_PKCS7_ENVELOPE, +d2i_PKCS7_ISSUER_AND_SERIAL, +d2i_PKCS7_RECIP_INFO, +d2i_PKCS7_SIGNED, +d2i_PKCS7_SIGNER_INFO, +d2i_PKCS7_SIGN_ENVELOPE, +d2i_PKCS7_bio, +d2i_PKCS7_fp, +d2i_PKCS8_PRIV_KEY_INFO, +d2i_PKCS8_PRIV_KEY_INFO_bio, +d2i_PKCS8_PRIV_KEY_INFO_fp, +d2i_PKCS8_bio, +d2i_PKCS8_fp, +d2i_PKEY_USAGE_PERIOD, +d2i_POLICYINFO, +d2i_POLICYQUALINFO, +d2i_PROXY_CERT_INFO_EXTENSION, +d2i_PROXY_POLICY, +d2i_RSAPrivateKey, +d2i_RSAPrivateKey_bio, +d2i_RSAPrivateKey_fp, +d2i_RSAPublicKey, +d2i_RSAPublicKey_bio, +d2i_RSAPublicKey_fp, +d2i_RSA_OAEP_PARAMS, +d2i_RSA_PSS_PARAMS, +d2i_RSA_PUBKEY, +d2i_RSA_PUBKEY_bio, +d2i_RSA_PUBKEY_fp, +d2i_SCT_LIST, +d2i_SXNET, +d2i_SXNETID, +d2i_TS_ACCURACY, +d2i_TS_MSG_IMPRINT, +d2i_TS_MSG_IMPRINT_bio, +d2i_TS_MSG_IMPRINT_fp, +d2i_TS_REQ, +d2i_TS_REQ_bio, +d2i_TS_REQ_fp, +d2i_TS_RESP, +d2i_TS_RESP_bio, +d2i_TS_RESP_fp, +d2i_TS_STATUS_INFO, +d2i_TS_TST_INFO, +d2i_TS_TST_INFO_bio, +d2i_TS_TST_INFO_fp, +d2i_USERNOTICE, +d2i_X509, +d2i_X509_ALGOR, +d2i_X509_ALGORS, +d2i_X509_ATTRIBUTE, +d2i_X509_CERT_AUX, +d2i_X509_CINF, +d2i_X509_CRL, +d2i_X509_CRL_INFO, +d2i_X509_CRL_bio, +d2i_X509_CRL_fp, +d2i_X509_EXTENSION, +d2i_X509_EXTENSIONS, +d2i_X509_NAME, +d2i_X509_NAME_ENTRY, +d2i_X509_PUBKEY, +d2i_X509_REQ, +d2i_X509_REQ_INFO, +d2i_X509_REQ_bio, +d2i_X509_REQ_fp, +d2i_X509_REVOKED, +d2i_X509_SIG, +d2i_X509_VAL, +i2d_ACCESS_DESCRIPTION, +i2d_ASIdOrRange, +i2d_ASIdentifierChoice, +i2d_ASIdentifiers, +i2d_ASN1_BIT_STRING, +i2d_ASN1_BMPSTRING, +i2d_ASN1_ENUMERATED, +i2d_ASN1_GENERALIZEDTIME, +i2d_ASN1_GENERALSTRING, +i2d_ASN1_IA5STRING, +i2d_ASN1_INTEGER, +i2d_ASN1_NULL, +i2d_ASN1_OBJECT, +i2d_ASN1_OCTET_STRING, +i2d_ASN1_PRINTABLE, +i2d_ASN1_PRINTABLESTRING, +i2d_ASN1_SEQUENCE_ANY, +i2d_ASN1_SET_ANY, +i2d_ASN1_T61STRING, +i2d_ASN1_TIME, +i2d_ASN1_TYPE, +i2d_ASN1_UNIVERSALSTRING, +i2d_ASN1_UTCTIME, +i2d_ASN1_UTF8STRING, +i2d_ASN1_VISIBLESTRING, +i2d_ASN1_bio_stream, +i2d_ASRange, +i2d_AUTHORITY_INFO_ACCESS, +i2d_AUTHORITY_KEYID, +i2d_BASIC_CONSTRAINTS, +i2d_CERTIFICATEPOLICIES, +i2d_CMS_ContentInfo, +i2d_CMS_ReceiptRequest, +i2d_CMS_bio, +i2d_CRL_DIST_POINTS, +i2d_DHxparams, +i2d_DIRECTORYSTRING, +i2d_DISPLAYTEXT, +i2d_DIST_POINT, +i2d_DIST_POINT_NAME, +i2d_DSAPrivateKey, +i2d_DSAPrivateKey_bio, +i2d_DSAPrivateKey_fp, +i2d_DSAPublicKey, +i2d_DSA_PUBKEY, +i2d_DSA_PUBKEY_bio, +i2d_DSA_PUBKEY_fp, +i2d_DSA_SIG, +i2d_DSAparams, +i2d_ECPKParameters, +i2d_ECParameters, +i2d_ECPrivateKey, +i2d_ECPrivateKey_bio, +i2d_ECPrivateKey_fp, +i2d_EC_PUBKEY, +i2d_EC_PUBKEY_bio, +i2d_EC_PUBKEY_fp, +i2d_EDIPARTYNAME, +i2d_ESS_CERT_ID, +i2d_ESS_ISSUER_SERIAL, +i2d_ESS_SIGNING_CERT, +i2d_EXTENDED_KEY_USAGE, +i2d_GENERAL_NAME, +i2d_GENERAL_NAMES, +i2d_IPAddressChoice, +i2d_IPAddressFamily, +i2d_IPAddressOrRange, +i2d_IPAddressRange, +i2d_ISSUING_DIST_POINT, +i2d_NETSCAPE_CERT_SEQUENCE, +i2d_NETSCAPE_SPKAC, +i2d_NETSCAPE_SPKI, +i2d_NOTICEREF, +i2d_OCSP_BASICRESP, +i2d_OCSP_CERTID, +i2d_OCSP_CERTSTATUS, +i2d_OCSP_CRLID, +i2d_OCSP_ONEREQ, +i2d_OCSP_REQINFO, +i2d_OCSP_REQUEST, +i2d_OCSP_RESPBYTES, +i2d_OCSP_RESPDATA, +i2d_OCSP_RESPID, +i2d_OCSP_RESPONSE, +i2d_OCSP_REVOKEDINFO, +i2d_OCSP_SERVICELOC, +i2d_OCSP_SIGNATURE, +i2d_OCSP_SINGLERESP, +i2d_OTHERNAME, +i2d_PBE2PARAM, +i2d_PBEPARAM, +i2d_PBKDF2PARAM, +i2d_PKCS12, +i2d_PKCS12_BAGS, +i2d_PKCS12_MAC_DATA, +i2d_PKCS12_SAFEBAG, +i2d_PKCS12_bio, +i2d_PKCS12_fp, +i2d_PKCS7, +i2d_PKCS7_DIGEST, +i2d_PKCS7_ENCRYPT, +i2d_PKCS7_ENC_CONTENT, +i2d_PKCS7_ENVELOPE, +i2d_PKCS7_ISSUER_AND_SERIAL, +i2d_PKCS7_NDEF, +i2d_PKCS7_RECIP_INFO, +i2d_PKCS7_SIGNED, +i2d_PKCS7_SIGNER_INFO, +i2d_PKCS7_SIGN_ENVELOPE, +i2d_PKCS7_bio, +i2d_PKCS7_fp, +i2d_PKCS8PrivateKeyInfo_bio, +i2d_PKCS8PrivateKeyInfo_fp, +i2d_PKCS8_PRIV_KEY_INFO, +i2d_PKCS8_PRIV_KEY_INFO_bio, +i2d_PKCS8_PRIV_KEY_INFO_fp, +i2d_PKCS8_bio, +i2d_PKCS8_fp, +i2d_PKEY_USAGE_PERIOD, +i2d_POLICYINFO, +i2d_POLICYQUALINFO, +i2d_PROXY_CERT_INFO_EXTENSION, +i2d_PROXY_POLICY, +i2d_PublicKey, +i2d_RSAPrivateKey, +i2d_RSAPrivateKey_bio, +i2d_RSAPrivateKey_fp, +i2d_RSAPublicKey, +i2d_RSAPublicKey_bio, +i2d_RSAPublicKey_fp, +i2d_RSA_OAEP_PARAMS, +i2d_RSA_PSS_PARAMS, +i2d_RSA_PUBKEY, +i2d_RSA_PUBKEY_bio, +i2d_RSA_PUBKEY_fp, +i2d_SCT_LIST, +i2d_SXNET, +i2d_SXNETID, +i2d_TS_ACCURACY, +i2d_TS_MSG_IMPRINT, +i2d_TS_MSG_IMPRINT_bio, +i2d_TS_MSG_IMPRINT_fp, +i2d_TS_REQ, +i2d_TS_REQ_bio, +i2d_TS_REQ_fp, +i2d_TS_RESP, +i2d_TS_RESP_bio, +i2d_TS_RESP_fp, +i2d_TS_STATUS_INFO, +i2d_TS_TST_INFO, +i2d_TS_TST_INFO_bio, +i2d_TS_TST_INFO_fp, +i2d_USERNOTICE, +i2d_X509, +i2d_X509_ALGOR, +i2d_X509_ALGORS, +i2d_X509_ATTRIBUTE, +i2d_X509_CERT_AUX, +i2d_X509_CINF, +i2d_X509_CRL, +i2d_X509_CRL_INFO, +i2d_X509_CRL_bio, +i2d_X509_CRL_fp, +i2d_X509_EXTENSION, +i2d_X509_EXTENSIONS, +i2d_X509_NAME, +i2d_X509_NAME_ENTRY, +i2d_X509_PUBKEY, +i2d_X509_REQ, +i2d_X509_REQ_INFO, +i2d_X509_REQ_bio, +i2d_X509_REQ_fp, +i2d_X509_REVOKED, +i2d_X509_SIG, +i2d_X509_VAL, +- convert objects from/to ASN.1/DER representation =head1 SYNOPSIS - #include <openssl/x509.h> +=for comment generic - X509 *d2i_X509(X509 **px, const unsigned char **in, long len); - X509 *d2i_X509_AUX(X509 **px, const unsigned char **in, long len); - int i2d_X509(X509 *x, unsigned char **out); - int i2d_X509_AUX(X509 *x, unsigned char **out); + TYPE *d2i_TYPE(TYPE **a, unsigned char **ppin, long length); + TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a); + TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a); - X509 *d2i_X509_bio(BIO *bp, X509 **x); - X509 *d2i_X509_fp(FILE *fp, X509 **x); - - int i2d_X509_bio(BIO *bp, X509 *x); - int i2d_X509_fp(FILE *fp, X509 *x); - - int i2d_re_X509_tbs(X509 *x, unsigned char **out); + int i2d_TYPE(TYPE *a, unsigned char **ppout); + int i2d_TYPE_fp(FILE *fp, TYPE *a); + int i2d_TYPE_bio(BIO *bp, TYPE *a); =head1 DESCRIPTION -The X509 encode and decode routines encode and parse an -B<X509> structure, which represents an X509 certificate. - -d2i_X509() attempts to decode B<len> bytes at B<*in>. If -successful a pointer to the B<X509> structure is returned. If an error -occurred then B<NULL> is returned. If B<px> is not B<NULL> then the -returned structure is written to B<*px>. If B<*px> is not B<NULL> -then it is assumed that B<*px> contains a valid B<X509> -structure and an attempt is made to reuse it. This "reuse" capability is present -for historical compatibility but its use is B<strongly discouraged> (see BUGS -below, and the discussion in the RETURN VALUES section). - -If the call is successful B<*in> is incremented to the byte following the -parsed data. - -d2i_X509_AUX() is similar to d2i_X509() but the input is expected to consist of -an X509 certificate followed by auxiliary trust information. -This is used by the PEM routines to read "TRUSTED CERTIFICATE" objects. -This function should not be called on untrusted input. - -i2d_X509() encodes the structure pointed to by B<x> into DER format. -If B<out> is not B<NULL> is writes the DER encoded data to the buffer -at B<*out>, and increments it to point after the data just written. -If the return value is negative an error occurred, otherwise it -returns the length of the encoded data. - -For OpenSSL 0.9.7 and later if B<*out> is B<NULL> memory will be -allocated for a buffer and the encoded data written to it. In this -case B<*out> is not incremented and it points to the start of the -data just written. - -i2d_X509_AUX() is similar to i2d_X509(), but the encoded output contains both -the certificate and any auxiliary trust information. -This is used by the PEM routines to write "TRUSTED CERTIFICATE" objects. -Note, this is a non-standard OpenSSL-specific data format. - -d2i_X509_bio() is similar to d2i_X509() except it attempts +In the description here, I<TYPE> is used a placeholder +for any of the OpenSSL datatypes, such as I<X509_CRL>. +The function parameters I<ppin> and I<ppout> are generally +either both named I<pp> in the headers, or I<in> and I<out>. + +These functions convert OpenSSL objects to and from their ASN.1/DER +encoding. Unlike the C structures which can have pointers to sub-objects +within, the DER is a serialized encoding, suitable for sending over the +network, writing to a file, and so on. + +d2i_TYPE() attempts to decode B<len> bytes at B<*ppin>. If successful a +pointer to the B<TYPE> structure is returned and B<*ppin> is incremented to +the byte following the parsed data. If B<a> is not B<NULL> then a pointer +to the returned structure is also written to B<*a>. If an error occurred +then B<NULL> is returned. + +On a successful return, if B<*a> is not B<NULL> then it is assumed that B<*a> +contains a valid B<TYPE> structure and an attempt is made to reuse it. This +"reuse" capability is present for historical compatibility but its use is +B<strongly discouraged> (see BUGS below, and the discussion in the RETURN +VALUES section). + +d2i_TYPE_bio() is similar to d2i_TYPE() except it attempts to parse data from BIO B<bp>. -d2i_X509_fp() is similar to d2i_X509() except it attempts +d2i_TYPE_fp() is similar to d2i_TYPE() except it attempts to parse data from FILE pointer B<fp>. -i2d_X509_bio() is similar to i2d_X509() except it writes -the encoding of the structure B<x> to BIO B<bp> and it +i2d_TYPE() encodes the structure pointed to by B<a> into DER format. +If B<ppout> is not B<NULL>, it writes the DER encoded data to the buffer +at B<*ppout>, and increments it to point after the data just written. +If the return value is negative an error occurred, otherwise it +returns the length of the encoded data. + +If B<*ppout> is B<NULL> memory will be allocated for a buffer and the encoded +data written to it. In this case B<*ppout> is not incremented and it points +to the start of the data just written. + +i2d_TYPE_bio() is similar to i2d_TYPE() except it writes +the encoding of the structure B<a> to BIO B<bp> and it returns 1 for success and 0 for failure. -i2d_X509_fp() is similar to i2d_X509() except it writes -the encoding of the structure B<x> to BIO B<bp> and it +i2d_TYPE_fp() is similar to i2d_TYPE() except it writes +the encoding of the structure B<a> to BIO B<bp> and it returns 1 for success and 0 for failure. -i2d_re_X509_tbs() is similar to i2d_X509() except it encodes -only the TBSCertificate portion of the certificate. +These routines do not encrypt private keys and therefore offer no +security; use L<PEM_write_PrivateKey(3)> or similar for writing to files. =head1 NOTES -The letters B<i> and B<d> in for example B<i2d_X509> stand for -"internal" (that is an internal C structure) and "DER". So -B<i2d_X509> converts from internal to DER. The "re" in -B<i2d_re_X509_tbs> stands for "re-encode", and ensures that a fresh -encoding is generated in case the object has been modified after -creation (see the BUGS section). +The letters B<i> and B<d> in B<i2d_TYPE> stand for +"internal" (that is, an internal C structure) and "DER" respectively. +So B<i2d_TYPE> converts from internal to DER. The functions can also understand B<BER> forms. -The actual X509 structure passed to i2d_X509() must be a valid -populated B<X509> structure it can B<not> simply be fed with an -empty structure such as that returned by X509_new(). +The actual TYPE structure passed to i2d_TYPE() must be a valid +populated B<TYPE> structure -- it B<cannot> simply be fed with an +empty structure such as that returned by TYPE_new(). The encoded data is in binary form and may contain embedded zeroes. Therefore any FILE pointers or BIOs should be opened in binary mode. -Functions such as B<strlen()> will B<not> return the correct length +Functions such as strlen() will B<not> return the correct length of the encoded structure. -The ways that B<*in> and B<*out> are incremented after the operation +The ways that B<*ppin> and B<*ppout> are incremented after the operation can trap the unwary. See the B<WARNINGS> section for some common errors. - -The reason for the auto increment behaviour is to reflect a typical +The reason for this-auto increment behaviour is to reflect a typical usage of ASN1 functions: after one structure is encoded or decoded -another will processed after it. +another will be processed after it. -=head1 EXAMPLES +The following points about the data types might be useful: -Allocate and encode the DER encoding of an X509 structure: +=over 4 - int len; - unsigned char *buf, *p; +=item B<ASN1_OBJECT> - len = i2d_X509(x, NULL); +Represents an ASN1 OBJECT IDENTIFIER. - buf = OPENSSL_malloc(len); +=item B<DHparams> - if (buf == NULL) - /* error */ +Represents a PKCS#3 DH parameters structure. - p = buf; +=item B<DHparamx> + +Represents a ANSI X9.42 DH parameters structure. + +=item B<DSA_PUBKEY> + +Represents a DSA public key using a B<SubjectPublicKeyInfo> structure. + +=item B<DSAPublicKey, DSAPrivateKey> + +Use a non-standard OpenSSL format and should be avoided; use B<DSA_PUBKEY>, +B<PEM_write_PrivateKey(3)>, or similar instead. + +=item B<RSAPublicKey> + +Represents a PKCS#1 RSA public key structure. + +=item B<X509_ALGOR> + +Represents an B<AlgorithmIdentifier> structure as used in IETF RFC 6960 and +elsewhere. + +=item B<X509_Name> + +Represents a B<Name> type as used for subject and issuer names in +IETF RFC 6960 and elsewhere. - i2d_X509(x, &p); +=item B<X509_REQ> -If you are using OpenSSL 0.9.7 or later then this can be -simplified to: +Represents a PKCS#10 certificate request. +=item B<X509_SIG> + +Represents the B<DigestInfo> structure defined in PKCS#1 and PKCS#7. + +=back + +=head1 EXAMPLES + +Allocate and encode the DER encoding of an X509 structure: int len; unsigned char *buf; buf = NULL; - len = i2d_X509(x, &buf); - if (len < 0) - /* error */ + /* error */ Attempt to decode a buffer: X509 *x; - unsigned char *buf, *p; - int len; - /* Something to setup buf and len */ - + /* Set up buf and len to point to the input buffer. */ p = buf; - x = d2i_X509(NULL, &p, len); - if (x == NULL) - /* Some error */ + /* error */ Alternative technique: X509 *x; - unsigned char *buf, *p; - int len; - /* Something to setup buf and len */ - + /* Set up buf and len to point to the input buffer. */ p = buf; - x = NULL; - if(!d2i_X509(&x, &p, len)) - /* Some error */ - + if (d2i_X509(&x, &p, len) == NULL) + /* error */ =head1 WARNINGS -The use of temporary variable is mandatory. A common +Using a temporary variable is mandatory. A common mistake is to attempt to use a buffer directly as follows: int len; unsigned char *buf; len = i2d_X509(x, NULL); - buf = OPENSSL_malloc(len); - - if (buf == NULL) - /* error */ - + ... i2d_X509(x, &buf); - - /* Other stuff ... */ - + ... OPENSSL_free(buf); This code will result in B<buf> apparently containing garbage because it was incremented after the call to point after the data just written. -Also B<buf> will no longer contain the pointer allocated by B<OPENSSL_malloc()> -and the subsequent call to B<OPENSSL_free()> may well crash. - -The auto allocation feature (setting buf to NULL) only works on OpenSSL -0.9.7 and later. Attempts to use it on earlier versions will typically -cause a segmentation violation. +Also B<buf> will no longer contain the pointer allocated by OPENSSL_malloc() +and the subsequent call to OPENSSL_free() is likely to crash. -Another trap to avoid is misuse of the B<xp> argument to B<d2i_X509()>: +Another trap to avoid is misuse of the B<a> argument to d2i_TYPE(): X509 *x; - if (!d2i_X509(&x, &p, len)) - /* Some error */ + if (d2i_X509(&x, &p, len) == NULL) + /* error */ -This will probably crash somewhere in B<d2i_X509()>. The reason for this +This will probably crash somewhere in d2i_X509(). The reason for this is that the variable B<x> is uninitialized and an attempt will be made to interpret its (invalid) value as an B<X509> structure, typically causing a segmentation violation. If B<x> is set to NULL first then this will not @@ -217,56 +558,44 @@ happen. =head1 BUGS -In some versions of OpenSSL the "reuse" behaviour of d2i_X509() when +In some versions of OpenSSL the "reuse" behaviour of d2i_TYPE() when B<*px> is valid is broken and some parts of the reused structure may persist if they are not present in the new one. As a result the use of this "reuse" behaviour is strongly discouraged. -i2d_X509() will not return an error in many versions of OpenSSL, +i2d_TYPE() will not return an error in many versions of OpenSSL, if mandatory fields are not initialized due to a programming error then the encoded structure may contain invalid data or omit the -fields entirely and will not be parsed by d2i_X509(). This may be -fixed in future so code should not assume that i2d_X509() will +fields entirely and will not be parsed by d2i_TYPE(). This may be +fixed in future so code should not assume that i2d_TYPE() will always succeed. -The encoding of the TBSCertificate portion of a certificate is cached -in the B<X509> structure internally to improve encoding performance -and to ensure certificate signatures are verified correctly in some -certificates with broken (non-DER) encodings. - -Any function which encodes an X509 structure such as i2d_X509(), -i2d_X509_fp() or i2d_X509_bio() may return a stale encoding if the -B<X509> structure has been modified after deserialization or previous -serialization. - -If, after modification, the B<X509> object is re-signed with X509_sign(), -the encoding is automatically renewed. Otherwise, the encoding of the -TBSCertificate portion of the B<X509> can be manually renewed by calling -i2d_re_X509_tbs(). +Any function which encodes a structure (i2d_TYPE(), +i2d_TYPE() or i2d_TYPE()) may return a stale encoding if the +structure has been modified after deserialization or previous +serialization. This is because some objects cache the encoding for +efficiency reasons. =head1 RETURN VALUES -d2i_X509(), d2i_X509_bio() and d2i_X509_fp() return a valid B<X509> structure -or B<NULL> if an error occurs. The error code that can be obtained by -L<ERR_get_error(3)|ERR_get_error(3)>. If the "reuse" capability has been used -with a valid X509 structure being passed in via B<px> then the object is not -freed in the event of error but may be in a potentially invalid or inconsistent -state. - -i2d_X509() returns the number of bytes successfully encoded or a negative -value if an error occurs. The error code can be obtained by -L<ERR_get_error(3)|ERR_get_error(3)>. +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_X509_bio() and i2d_X509_fp() return 1 for success and 0 if an error -occurs The error code can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. +i2d_TYPE() returns the number of bytes successfully encoded or a negative +value if an error occurs. -=head1 SEE ALSO +i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error +occurs. -L<ERR_get_error(3)|ERR_get_error(3)> +=head1 COPYRIGHT -=head1 HISTORY +Copyright 1998-2018 The OpenSSL Project Authors. All Rights Reserved. -d2i_X509, i2d_X509, d2i_X509_bio, d2i_X509_fp, i2d_X509_bio and i2d_X509_fp -are available in all versions of SSLeay and OpenSSL. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/d2i_X509_ALGOR.pod b/deps/openssl/openssl/doc/crypto/d2i_X509_ALGOR.pod deleted file mode 100644 index 9e5cd92ca7..0000000000 --- a/deps/openssl/openssl/doc/crypto/d2i_X509_ALGOR.pod +++ /dev/null @@ -1,30 +0,0 @@ -=pod - -=head1 NAME - -d2i_X509_ALGOR, i2d_X509_ALGOR - AlgorithmIdentifier functions. - -=head1 SYNOPSIS - - #include <openssl/x509.h> - - X509_ALGOR *d2i_X509_ALGOR(X509_ALGOR **a, unsigned char **pp, long length); - int i2d_X509_ALGOR(X509_ALGOR *a, unsigned char **pp); - -=head1 DESCRIPTION - -These functions decode and encode an B<X509_ALGOR> structure which is -equivalent to the B<AlgorithmIdentifier> structure. - -Othewise these behave in a similar way to d2i_X509() and i2d_X509() -described in the L<d2i_X509(3)|d2i_X509(3)> manual page. - -=head1 SEE ALSO - -L<d2i_X509(3)|d2i_X509(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/deps/openssl/openssl/doc/crypto/d2i_X509_CRL.pod b/deps/openssl/openssl/doc/crypto/d2i_X509_CRL.pod deleted file mode 100644 index 675d38b3e5..0000000000 --- a/deps/openssl/openssl/doc/crypto/d2i_X509_CRL.pod +++ /dev/null @@ -1,37 +0,0 @@ -=pod - -=head1 NAME - -d2i_X509_CRL, i2d_X509_CRL, d2i_X509_CRL_bio, d2i_X509_CRL_fp, -i2d_X509_CRL_bio, i2d_X509_CRL_fp - PKCS#10 certificate request functions. - -=head1 SYNOPSIS - - #include <openssl/x509.h> - - X509_CRL *d2i_X509_CRL(X509_CRL **a, const unsigned char **pp, long length); - int i2d_X509_CRL(X509_CRL *a, unsigned char **pp); - - X509_CRL *d2i_X509_CRL_bio(BIO *bp, X509_CRL **x); - X509_CRL *d2i_X509_CRL_fp(FILE *fp, X509_CRL **x); - - int i2d_X509_CRL_bio(BIO *bp, X509_CRL *x); - int i2d_X509_CRL_fp(FILE *fp, X509_CRL *x); - -=head1 DESCRIPTION - -These functions decode and encode an X509 CRL (certificate revocation -list). - -Othewise the functions behave in a similar way to d2i_X509() and i2d_X509() -described in the L<d2i_X509(3)|d2i_X509(3)> manual page. - -=head1 SEE ALSO - -L<d2i_X509(3)|d2i_X509(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/deps/openssl/openssl/doc/crypto/d2i_X509_NAME.pod b/deps/openssl/openssl/doc/crypto/d2i_X509_NAME.pod deleted file mode 100644 index b025de7b2f..0000000000 --- a/deps/openssl/openssl/doc/crypto/d2i_X509_NAME.pod +++ /dev/null @@ -1,31 +0,0 @@ -=pod - -=head1 NAME - -d2i_X509_NAME, i2d_X509_NAME - X509_NAME encoding functions - -=head1 SYNOPSIS - - #include <openssl/x509.h> - - X509_NAME *d2i_X509_NAME(X509_NAME **a, unsigned char **pp, long length); - int i2d_X509_NAME(X509_NAME *a, unsigned char **pp); - -=head1 DESCRIPTION - -These functions decode and encode an B<X509_NAME> structure which is the -same as the B<Name> type defined in RFC2459 (and elsewhere) and used -for example in certificate subject and issuer names. - -Othewise the functions behave in a similar way to d2i_X509() and i2d_X509() -described in the L<d2i_X509(3)|d2i_X509(3)> manual page. - -=head1 SEE ALSO - -L<d2i_X509(3)|d2i_X509(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/deps/openssl/openssl/doc/crypto/d2i_X509_REQ.pod b/deps/openssl/openssl/doc/crypto/d2i_X509_REQ.pod deleted file mode 100644 index 91c0c1974b..0000000000 --- a/deps/openssl/openssl/doc/crypto/d2i_X509_REQ.pod +++ /dev/null @@ -1,36 +0,0 @@ -=pod - -=head1 NAME - -d2i_X509_REQ, i2d_X509_REQ, d2i_X509_REQ_bio, d2i_X509_REQ_fp, -i2d_X509_REQ_bio, i2d_X509_REQ_fp - PKCS#10 certificate request functions. - -=head1 SYNOPSIS - - #include <openssl/x509.h> - - X509_REQ *d2i_X509_REQ(X509_REQ **a, const unsigned char **pp, long length); - int i2d_X509_REQ(X509_REQ *a, unsigned char **pp); - - X509_REQ *d2i_X509_REQ_bio(BIO *bp, X509_REQ **x); - X509_REQ *d2i_X509_REQ_fp(FILE *fp, X509_REQ **x); - - int i2d_X509_REQ_bio(BIO *bp, X509_REQ *x); - int i2d_X509_REQ_fp(FILE *fp, X509_REQ *x); - -=head1 DESCRIPTION - -These functions decode and encode a PKCS#10 certificate request. - -Othewise these behave in a similar way to d2i_X509() and i2d_X509() -described in the L<d2i_X509(3)|d2i_X509(3)> manual page. - -=head1 SEE ALSO - -L<d2i_X509(3)|d2i_X509(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/deps/openssl/openssl/doc/crypto/d2i_X509_SIG.pod b/deps/openssl/openssl/doc/crypto/d2i_X509_SIG.pod deleted file mode 100644 index e48fd79a51..0000000000 --- a/deps/openssl/openssl/doc/crypto/d2i_X509_SIG.pod +++ /dev/null @@ -1,30 +0,0 @@ -=pod - -=head1 NAME - -d2i_X509_SIG, i2d_X509_SIG - DigestInfo functions. - -=head1 SYNOPSIS - - #include <openssl/x509.h> - - X509_SIG *d2i_X509_SIG(X509_SIG **a, unsigned char **pp, long length); - int i2d_X509_SIG(X509_SIG *a, unsigned char **pp); - -=head1 DESCRIPTION - -These functions decode and encode an X509_SIG structure which is -equivalent to the B<DigestInfo> structure defined in PKCS#1 and PKCS#7. - -Othewise these behave in a similar way to d2i_X509() and i2d_X509() -described in the L<d2i_X509(3)|d2i_X509(3)> manual page. - -=head1 SEE ALSO - -L<d2i_X509(3)|d2i_X509(3)> - -=head1 HISTORY - -TBA - -=cut diff --git a/deps/openssl/openssl/doc/crypto/des_modes.pod b/deps/openssl/openssl/doc/crypto/des_modes.pod index e883ca8fde..d5a3f8d636 100644 --- a/deps/openssl/openssl/doc/crypto/des_modes.pod +++ b/deps/openssl/openssl/doc/crypto/des_modes.pod @@ -18,7 +18,7 @@ other things. Normally, this is found as the function I<algorithm>_ecb_encrypt(). -=over 2 +=over 4 =item * @@ -45,7 +45,7 @@ Normally, this is found as the function I<algorithm>_cbc_encrypt(). Be aware that des_cbc_encrypt() is not really DES CBC (it does not update the IV); use des_ncbc_encrypt() instead. -=over 2 +=over 4 =item * @@ -77,7 +77,7 @@ An error will affect the current and the following ciphertext blocks. Normally, this is found as the function I<algorithm>_cfb_encrypt(). -=over 2 +=over 4 =item * @@ -124,7 +124,7 @@ An error will affect the current and the following ciphertext variables. Normally, this is found as the function I<algorithm>_ofb_encrypt(). -=over 2 +=over 4 =item * @@ -185,7 +185,7 @@ susceptible to a 'known plaintext' attack. Normally, this is found as the function I<algorithm>_ecb3_encrypt(). -=over 2 +=over 4 =item * @@ -220,8 +220,7 @@ ecb mode. Normally, this is found as the function I<algorithm>_ede3_cbc_encrypt(). -=over 2 - +=over 4 =item * @@ -240,16 +239,23 @@ This text was been written in large parts by Eric Young in his original documentation for SSLeay, the predecessor of OpenSSL. In turn, he attributed it to: - AS 2805.5.2 - Australian Standard - Electronic funds transfer - Requirements for interfaces, - Part 5.2: Modes of operation for an n-bit block cipher algorithm - Appendix A + AS 2805.5.2 + Australian Standard + Electronic funds transfer - Requirements for interfaces, + Part 5.2: Modes of operation for an n-bit block cipher algorithm + Appendix A =head1 SEE ALSO -L<blowfish(3)|blowfish(3)>, L<des(3)|des(3)>, L<idea(3)|idea(3)>, -L<rc2(3)|rc2(3)> +L<BF_encrypt(3)>, L<DES_crypt(3)> -=cut +=head1 COPYRIGHT + +Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved. +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/dh.pod b/deps/openssl/openssl/doc/crypto/dh.pod deleted file mode 100644 index c3ccd06207..0000000000 --- a/deps/openssl/openssl/doc/crypto/dh.pod +++ /dev/null @@ -1,78 +0,0 @@ -=pod - -=head1 NAME - -dh - Diffie-Hellman key agreement - -=head1 SYNOPSIS - - #include <openssl/dh.h> - #include <openssl/engine.h> - - DH * DH_new(void); - void DH_free(DH *dh); - - int DH_size(const DH *dh); - - DH * DH_generate_parameters(int prime_len, int generator, - void (*callback)(int, int, void *), void *cb_arg); - int DH_check(const DH *dh, int *codes); - - int DH_generate_key(DH *dh); - int DH_compute_key(unsigned char *key, BIGNUM *pub_key, DH *dh); - - void DH_set_default_method(const DH_METHOD *meth); - const DH_METHOD *DH_get_default_method(void); - int DH_set_method(DH *dh, const DH_METHOD *meth); - DH *DH_new_method(ENGINE *engine); - const DH_METHOD *DH_OpenSSL(void); - - int DH_get_ex_new_index(long argl, char *argp, int (*new_func)(), - int (*dup_func)(), void (*free_func)()); - int DH_set_ex_data(DH *d, int idx, char *arg); - char *DH_get_ex_data(DH *d, int idx); - - DH * d2i_DHparams(DH **a, unsigned char **pp, long length); - int i2d_DHparams(const DH *a, unsigned char **pp); - - int DHparams_print_fp(FILE *fp, const DH *x); - int DHparams_print(BIO *bp, const DH *x); - -=head1 DESCRIPTION - -These functions implement the Diffie-Hellman key agreement protocol. -The generation of shared DH parameters is described in -L<DH_generate_parameters(3)|DH_generate_parameters(3)>; L<DH_generate_key(3)|DH_generate_key(3)> describes how -to perform a key agreement. - -The B<DH> structure consists of several BIGNUM components. - - struct - { - BIGNUM *p; // prime number (shared) - BIGNUM *g; // generator of Z_p (shared) - BIGNUM *priv_key; // private DH value x - BIGNUM *pub_key; // public DH value g^x - // ... - }; - DH - -Note that DH keys may use non-standard B<DH_METHOD> implementations, -either directly or by the use of B<ENGINE> modules. In some cases (eg. an -ENGINE providing support for hardware-embedded keys), these BIGNUM values -will not be used by the implementation or may be used for alternative data -storage. For this reason, applications should generally avoid using DH -structure elements directly and instead use API functions to query or -modify keys. - -=head1 SEE ALSO - -L<dhparam(1)|dhparam(1)>, L<bn(3)|bn(3)>, L<dsa(3)|dsa(3)>, L<err(3)|err(3)>, -L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, L<engine(3)|engine(3)>, -L<DH_set_method(3)|DH_set_method(3)>, L<DH_new(3)|DH_new(3)>, -L<DH_get_ex_new_index(3)|DH_get_ex_new_index(3)>, -L<DH_generate_parameters(3)|DH_generate_parameters(3)>, -L<DH_compute_key(3)|DH_compute_key(3)>, L<d2i_DHparams(3)|d2i_DHparams(3)>, -L<RSA_print(3)|RSA_print(3)> - -=cut diff --git a/deps/openssl/openssl/doc/crypto/dsa.pod b/deps/openssl/openssl/doc/crypto/dsa.pod deleted file mode 100644 index da07d2b930..0000000000 --- a/deps/openssl/openssl/doc/crypto/dsa.pod +++ /dev/null @@ -1,114 +0,0 @@ -=pod - -=head1 NAME - -dsa - Digital Signature Algorithm - -=head1 SYNOPSIS - - #include <openssl/dsa.h> - #include <openssl/engine.h> - - DSA * DSA_new(void); - void DSA_free(DSA *dsa); - - int DSA_size(const DSA *dsa); - - DSA * DSA_generate_parameters(int bits, unsigned char *seed, - int seed_len, int *counter_ret, unsigned long *h_ret, - void (*callback)(int, int, void *), void *cb_arg); - - DH * DSA_dup_DH(const DSA *r); - - int DSA_generate_key(DSA *dsa); - - int DSA_sign(int dummy, const unsigned char *dgst, int len, - unsigned char *sigret, unsigned int *siglen, DSA *dsa); - int DSA_sign_setup(DSA *dsa, BN_CTX *ctx, BIGNUM **kinvp, - BIGNUM **rp); - int DSA_verify(int dummy, const unsigned char *dgst, int len, - const unsigned char *sigbuf, int siglen, DSA *dsa); - - void DSA_set_default_method(const DSA_METHOD *meth); - const DSA_METHOD *DSA_get_default_method(void); - int DSA_set_method(DSA *dsa, const DSA_METHOD *meth); - DSA *DSA_new_method(ENGINE *engine); - const DSA_METHOD *DSA_OpenSSL(void); - - int DSA_get_ex_new_index(long argl, char *argp, int (*new_func)(), - int (*dup_func)(), void (*free_func)()); - int DSA_set_ex_data(DSA *d, int idx, char *arg); - char *DSA_get_ex_data(DSA *d, int idx); - - DSA_SIG *DSA_SIG_new(void); - void DSA_SIG_free(DSA_SIG *a); - int i2d_DSA_SIG(const DSA_SIG *a, unsigned char **pp); - DSA_SIG *d2i_DSA_SIG(DSA_SIG **v, unsigned char **pp, long length); - - DSA_SIG *DSA_do_sign(const unsigned char *dgst, int dlen, DSA *dsa); - int DSA_do_verify(const unsigned char *dgst, int dgst_len, - DSA_SIG *sig, DSA *dsa); - - DSA * d2i_DSAPublicKey(DSA **a, unsigned char **pp, long length); - DSA * d2i_DSAPrivateKey(DSA **a, unsigned char **pp, long length); - DSA * d2i_DSAparams(DSA **a, unsigned char **pp, long length); - int i2d_DSAPublicKey(const DSA *a, unsigned char **pp); - int i2d_DSAPrivateKey(const DSA *a, unsigned char **pp); - int i2d_DSAparams(const DSA *a,unsigned char **pp); - - int DSAparams_print(BIO *bp, const DSA *x); - int DSAparams_print_fp(FILE *fp, const DSA *x); - int DSA_print(BIO *bp, const DSA *x, int off); - int DSA_print_fp(FILE *bp, const DSA *x, int off); - -=head1 DESCRIPTION - -These functions implement the Digital Signature Algorithm (DSA). The -generation of shared DSA parameters is described in -L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>; -L<DSA_generate_key(3)|DSA_generate_key(3)> describes how to -generate a signature key. Signature generation and verification are -described in L<DSA_sign(3)|DSA_sign(3)>. - -The B<DSA> structure consists of several BIGNUM components. - - struct - { - BIGNUM *p; // prime number (public) - BIGNUM *q; // 160-bit subprime, q | p-1 (public) - BIGNUM *g; // generator of subgroup (public) - BIGNUM *priv_key; // private key x - BIGNUM *pub_key; // public key y = g^x - // ... - } - DSA; - -In public keys, B<priv_key> is NULL. - -Note that DSA keys may use non-standard B<DSA_METHOD> implementations, -either directly or by the use of B<ENGINE> modules. In some cases (eg. an -ENGINE providing support for hardware-embedded keys), these BIGNUM values -will not be used by the implementation or may be used for alternative data -storage. For this reason, applications should generally avoid using DSA -structure elements directly and instead use API functions to query or -modify keys. - -=head1 CONFORMING TO - -US Federal Information Processing Standard FIPS 186 (Digital Signature -Standard, DSS), ANSI X9.30 - -=head1 SEE ALSO - -L<bn(3)|bn(3)>, L<dh(3)|dh(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, -L<rsa(3)|rsa(3)>, L<sha(3)|sha(3)>, L<engine(3)|engine(3)>, -L<DSA_new(3)|DSA_new(3)>, -L<DSA_size(3)|DSA_size(3)>, -L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>, -L<DSA_dup_DH(3)|DSA_dup_DH(3)>, -L<DSA_generate_key(3)|DSA_generate_key(3)>, -L<DSA_sign(3)|DSA_sign(3)>, L<DSA_set_method(3)|DSA_set_method(3)>, -L<DSA_get_ex_new_index(3)|DSA_get_ex_new_index(3)>, -L<RSA_print(3)|RSA_print(3)> - -=cut diff --git a/deps/openssl/openssl/doc/crypto/ec.pod b/deps/openssl/openssl/doc/crypto/ec.pod deleted file mode 100644 index 7d57ba8ea0..0000000000 --- a/deps/openssl/openssl/doc/crypto/ec.pod +++ /dev/null @@ -1,201 +0,0 @@ -=pod - -=head1 NAME - -ec - Elliptic Curve functions - -=head1 SYNOPSIS - - #include <openssl/ec.h> - #include <openssl/bn.h> - - const EC_METHOD *EC_GFp_simple_method(void); - const EC_METHOD *EC_GFp_mont_method(void); - const EC_METHOD *EC_GFp_nist_method(void); - const EC_METHOD *EC_GFp_nistp224_method(void); - const EC_METHOD *EC_GFp_nistp256_method(void); - const EC_METHOD *EC_GFp_nistp521_method(void); - - const EC_METHOD *EC_GF2m_simple_method(void); - - EC_GROUP *EC_GROUP_new(const EC_METHOD *meth); - void EC_GROUP_free(EC_GROUP *group); - void EC_GROUP_clear_free(EC_GROUP *group); - int EC_GROUP_copy(EC_GROUP *dst, const EC_GROUP *src); - EC_GROUP *EC_GROUP_dup(const EC_GROUP *src); - const EC_METHOD *EC_GROUP_method_of(const EC_GROUP *group); - int EC_METHOD_get_field_type(const EC_METHOD *meth); - int EC_GROUP_set_generator(EC_GROUP *group, const EC_POINT *generator, const BIGNUM *order, const BIGNUM *cofactor); - const EC_POINT *EC_GROUP_get0_generator(const EC_GROUP *group); - int EC_GROUP_get_order(const EC_GROUP *group, BIGNUM *order, BN_CTX *ctx); - int EC_GROUP_get_cofactor(const EC_GROUP *group, BIGNUM *cofactor, BN_CTX *ctx); - void EC_GROUP_set_curve_name(EC_GROUP *group, int nid); - int EC_GROUP_get_curve_name(const EC_GROUP *group); - void EC_GROUP_set_asn1_flag(EC_GROUP *group, int flag); - int EC_GROUP_get_asn1_flag(const EC_GROUP *group); - void EC_GROUP_set_point_conversion_form(EC_GROUP *group, point_conversion_form_t form); - point_conversion_form_t EC_GROUP_get_point_conversion_form(const EC_GROUP *); - unsigned char *EC_GROUP_get0_seed(const EC_GROUP *x); - size_t EC_GROUP_get_seed_len(const EC_GROUP *); - size_t EC_GROUP_set_seed(EC_GROUP *, const unsigned char *, size_t len); - int EC_GROUP_set_curve_GFp(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); - int EC_GROUP_get_curve_GFp(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); - int EC_GROUP_set_curve_GF2m(EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); - int EC_GROUP_get_curve_GF2m(const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX *ctx); - int EC_GROUP_get_degree(const EC_GROUP *group); - int EC_GROUP_check(const EC_GROUP *group, BN_CTX *ctx); - int EC_GROUP_check_discriminant(const EC_GROUP *group, BN_CTX *ctx); - int EC_GROUP_cmp(const EC_GROUP *a, const EC_GROUP *b, BN_CTX *ctx); - EC_GROUP *EC_GROUP_new_curve_GFp(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); - EC_GROUP *EC_GROUP_new_curve_GF2m(const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX *ctx); - EC_GROUP *EC_GROUP_new_by_curve_name(int nid); - - size_t EC_get_builtin_curves(EC_builtin_curve *r, size_t nitems); - - EC_POINT *EC_POINT_new(const EC_GROUP *group); - void EC_POINT_free(EC_POINT *point); - void EC_POINT_clear_free(EC_POINT *point); - int EC_POINT_copy(EC_POINT *dst, const EC_POINT *src); - EC_POINT *EC_POINT_dup(const EC_POINT *src, const EC_GROUP *group); - const EC_METHOD *EC_POINT_method_of(const EC_POINT *point); - int EC_POINT_set_to_infinity(const EC_GROUP *group, EC_POINT *point); - int EC_POINT_set_Jprojective_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, - const BIGNUM *x, const BIGNUM *y, const BIGNUM *z, BN_CTX *ctx); - int EC_POINT_get_Jprojective_coordinates_GFp(const EC_GROUP *group, - const EC_POINT *p, BIGNUM *x, BIGNUM *y, BIGNUM *z, BN_CTX *ctx); - int EC_POINT_set_affine_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, - const BIGNUM *x, const BIGNUM *y, BN_CTX *ctx); - int EC_POINT_get_affine_coordinates_GFp(const EC_GROUP *group, - const EC_POINT *p, BIGNUM *x, BIGNUM *y, BN_CTX *ctx); - int EC_POINT_set_compressed_coordinates_GFp(const EC_GROUP *group, EC_POINT *p, - const BIGNUM *x, int y_bit, BN_CTX *ctx); - int EC_POINT_set_affine_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p, - const BIGNUM *x, const BIGNUM *y, BN_CTX *ctx); - int EC_POINT_get_affine_coordinates_GF2m(const EC_GROUP *group, - const EC_POINT *p, BIGNUM *x, BIGNUM *y, BN_CTX *ctx); - int EC_POINT_set_compressed_coordinates_GF2m(const EC_GROUP *group, EC_POINT *p, - const BIGNUM *x, int y_bit, BN_CTX *ctx); - size_t EC_POINT_point2oct(const EC_GROUP *group, const EC_POINT *p, - point_conversion_form_t form, - unsigned char *buf, size_t len, BN_CTX *ctx); - int EC_POINT_oct2point(const EC_GROUP *group, EC_POINT *p, - const unsigned char *buf, size_t len, BN_CTX *ctx); - BIGNUM *EC_POINT_point2bn(const EC_GROUP *, const EC_POINT *, - point_conversion_form_t form, BIGNUM *, BN_CTX *); - EC_POINT *EC_POINT_bn2point(const EC_GROUP *, const BIGNUM *, - EC_POINT *, BN_CTX *); - char *EC_POINT_point2hex(const EC_GROUP *, const EC_POINT *, - point_conversion_form_t form, BN_CTX *); - EC_POINT *EC_POINT_hex2point(const EC_GROUP *, const char *, - EC_POINT *, BN_CTX *); - - int EC_POINT_add(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx); - int EC_POINT_dbl(const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, BN_CTX *ctx); - int EC_POINT_invert(const EC_GROUP *group, EC_POINT *a, BN_CTX *ctx); - int EC_POINT_is_at_infinity(const EC_GROUP *group, const EC_POINT *p); - int EC_POINT_is_on_curve(const EC_GROUP *group, const EC_POINT *point, BN_CTX *ctx); - int EC_POINT_cmp(const EC_GROUP *group, const EC_POINT *a, const EC_POINT *b, BN_CTX *ctx); - int EC_POINT_make_affine(const EC_GROUP *group, EC_POINT *point, BN_CTX *ctx); - int EC_POINTs_make_affine(const EC_GROUP *group, size_t num, EC_POINT *points[], BN_CTX *ctx); - int EC_POINTs_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, size_t num, const EC_POINT *p[], const BIGNUM *m[], BN_CTX *ctx); - int EC_POINT_mul(const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, const EC_POINT *q, const BIGNUM *m, BN_CTX *ctx); - int EC_GROUP_precompute_mult(EC_GROUP *group, BN_CTX *ctx); - int EC_GROUP_have_precompute_mult(const EC_GROUP *group); - - int EC_GROUP_get_basis_type(const EC_GROUP *); - int EC_GROUP_get_trinomial_basis(const EC_GROUP *, unsigned int *k); - int EC_GROUP_get_pentanomial_basis(const EC_GROUP *, unsigned int *k1, - unsigned int *k2, unsigned int *k3); - EC_GROUP *d2i_ECPKParameters(EC_GROUP **, const unsigned char **in, long len); - int i2d_ECPKParameters(const EC_GROUP *, unsigned char **out); - #define d2i_ECPKParameters_bio(bp,x) ASN1_d2i_bio_of(EC_GROUP,NULL,d2i_ECPKParameters,bp,x) - #define i2d_ECPKParameters_bio(bp,x) ASN1_i2d_bio_of_const(EC_GROUP,i2d_ECPKParameters,bp,x) - #define d2i_ECPKParameters_fp(fp,x) (EC_GROUP *)ASN1_d2i_fp(NULL, \ - (char *(*)())d2i_ECPKParameters,(fp),(unsigned char **)(x)) - #define i2d_ECPKParameters_fp(fp,x) ASN1_i2d_fp(i2d_ECPKParameters,(fp), \ - (unsigned char *)(x)) - int ECPKParameters_print(BIO *bp, const EC_GROUP *x, int off); - int ECPKParameters_print_fp(FILE *fp, const EC_GROUP *x, int off); - - EC_KEY *EC_KEY_new(void); - int EC_KEY_get_flags(const EC_KEY *key); - void EC_KEY_set_flags(EC_KEY *key, int flags); - void EC_KEY_clear_flags(EC_KEY *key, int flags); - EC_KEY *EC_KEY_new_by_curve_name(int nid); - void EC_KEY_free(EC_KEY *key); - EC_KEY *EC_KEY_copy(EC_KEY *dst, const EC_KEY *src); - EC_KEY *EC_KEY_dup(const EC_KEY *src); - int EC_KEY_up_ref(EC_KEY *key); - const EC_GROUP *EC_KEY_get0_group(const EC_KEY *key); - int EC_KEY_set_group(EC_KEY *key, const EC_GROUP *group); - const BIGNUM *EC_KEY_get0_private_key(const EC_KEY *key); - int EC_KEY_set_private_key(EC_KEY *key, const BIGNUM *prv); - const EC_POINT *EC_KEY_get0_public_key(const EC_KEY *key); - int EC_KEY_set_public_key(EC_KEY *key, const EC_POINT *pub); - unsigned EC_KEY_get_enc_flags(const EC_KEY *key); - void EC_KEY_set_enc_flags(EC_KEY *eckey, unsigned int flags); - point_conversion_form_t EC_KEY_get_conv_form(const EC_KEY *key); - void EC_KEY_set_conv_form(EC_KEY *eckey, point_conversion_form_t cform); - void *EC_KEY_get_key_method_data(EC_KEY *key, - void *(*dup_func)(void *), void (*free_func)(void *), void (*clear_free_func)(void *)); - void EC_KEY_insert_key_method_data(EC_KEY *key, void *data, - void *(*dup_func)(void *), void (*free_func)(void *), void (*clear_free_func)(void *)); - void EC_KEY_set_asn1_flag(EC_KEY *eckey, int asn1_flag); - int EC_KEY_precompute_mult(EC_KEY *key, BN_CTX *ctx); - int EC_KEY_generate_key(EC_KEY *key); - int EC_KEY_check_key(const EC_KEY *key); - int EC_KEY_set_public_key_affine_coordinates(EC_KEY *key, BIGNUM *x, BIGNUM *y); - - EC_KEY *d2i_ECPrivateKey(EC_KEY **key, const unsigned char **in, long len); - int i2d_ECPrivateKey(EC_KEY *key, unsigned char **out); - - EC_KEY *d2i_ECParameters(EC_KEY **key, const unsigned char **in, long len); - int i2d_ECParameters(EC_KEY *key, unsigned char **out); - - EC_KEY *o2i_ECPublicKey(EC_KEY **key, const unsigned char **in, long len); - int i2o_ECPublicKey(EC_KEY *key, unsigned char **out); - int ECParameters_print(BIO *bp, const EC_KEY *key); - int EC_KEY_print(BIO *bp, const EC_KEY *key, int off); - int ECParameters_print_fp(FILE *fp, const EC_KEY *key); - int EC_KEY_print_fp(FILE *fp, const EC_KEY *key, int off); - #define ECParameters_dup(x) ASN1_dup_of(EC_KEY,i2d_ECParameters,d2i_ECParameters,x) - #define EVP_PKEY_CTX_set_ec_paramgen_curve_nid(ctx, nid) \ - EVP_PKEY_CTX_ctrl(ctx, EVP_PKEY_EC, EVP_PKEY_OP_PARAMGEN, \ - EVP_PKEY_CTRL_EC_PARAMGEN_CURVE_NID, nid, NULL) - - -=head1 DESCRIPTION - -This library provides an extensive set of functions for performing operations on elliptic curves over finite fields. -In general an elliptic curve is one with an equation of the form: - -y^2 = x^3 + ax + b - -An B<EC_GROUP> structure is used to represent the definition of an elliptic curve. Points on a curve are stored using an -B<EC_POINT> structure. An B<EC_KEY> is used to hold a private/public key pair, where a private key is simply a BIGNUM and a -public key is a point on a curve (represented by an B<EC_POINT>). - -The library contains a number of alternative implementations of the different functions. Each implementation is optimised -for different scenarios. No matter which implementation is being used, the interface remains the same. The library -handles calling the correct implementation when an interface function is invoked. An implementation is represented by -an B<EC_METHOD> structure. - -The creation and destruction of B<EC_GROUP> objects is described in L<EC_GROUP_new(3)|EC_GROUP_new(3)>. Functions for -manipulating B<EC_GROUP> objects are described in L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>. - -Functions for creating, destroying and manipulating B<EC_POINT> objects are explained in L<EC_POINT_new(3)|EC_POINT_new(3)>, -whilst functions for performing mathematical operations and tests on B<EC_POINTs> are coverd in L<EC_POINT_add(3)|EC_POINT_add(3)>. - -For working with private and public keys refer to L<EC_KEY_new(3)|EC_KEY_new(3)>. Implementations are covered in -L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>. - -For information on encoding and decoding curve parameters to and from ASN1 see L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)>. - -=head1 SEE ALSO - -L<crypto(3)|crypto(3)>, L<EC_GROUP_new(3)|EC_GROUP_new(3)>, L<EC_GROUP_copy(3)|EC_GROUP_copy(3)>, -L<EC_POINT_new(3)|EC_POINT_new(3)>, L<EC_POINT_add(3)|EC_POINT_add(3)>, L<EC_KEY_new(3)|EC_KEY_new(3)>, -L<EC_GFp_simple_method(3)|EC_GFp_simple_method(3)>, L<d2i_ECPKParameters(3)|d2i_ECPKParameters(3)> - - -=cut diff --git a/deps/openssl/openssl/doc/crypto/ecdsa.pod b/deps/openssl/openssl/doc/crypto/ecdsa.pod deleted file mode 100644 index 46c071b733..0000000000 --- a/deps/openssl/openssl/doc/crypto/ecdsa.pod +++ /dev/null @@ -1,206 +0,0 @@ -=pod - -=head1 NAME - -ECDSA_SIG_new, ECDSA_SIG_free, i2d_ECDSA_SIG, d2i_ECDSA_SIG, ECDSA_size, ECDSA_sign_setup, ECDSA_sign, ECDSA_sign_ex, ECDSA_verify, ECDSA_do_sign, ECDSA_do_sign_ex, ECDSA_do_verify - Elliptic Curve Digital Signature Algorithm - -=head1 SYNOPSIS - - #include <openssl/ecdsa.h> - - ECDSA_SIG* ECDSA_SIG_new(void); - void ECDSA_SIG_free(ECDSA_SIG *sig); - int i2d_ECDSA_SIG(const ECDSA_SIG *sig, unsigned char **pp); - ECDSA_SIG* d2i_ECDSA_SIG(ECDSA_SIG **sig, const unsigned char **pp, - long len); - - ECDSA_SIG* ECDSA_do_sign(const unsigned char *dgst, int dgst_len, - EC_KEY *eckey); - ECDSA_SIG* ECDSA_do_sign_ex(const unsigned char *dgst, int dgstlen, - const BIGNUM *kinv, const BIGNUM *rp, - EC_KEY *eckey); - int ECDSA_do_verify(const unsigned char *dgst, int dgst_len, - const ECDSA_SIG *sig, EC_KEY* eckey); - int ECDSA_sign_setup(EC_KEY *eckey, BN_CTX *ctx, - BIGNUM **kinv, BIGNUM **rp); - int ECDSA_sign(int type, const unsigned char *dgst, - int dgstlen, unsigned char *sig, - unsigned int *siglen, EC_KEY *eckey); - int ECDSA_sign_ex(int type, const unsigned char *dgst, - int dgstlen, unsigned char *sig, - unsigned int *siglen, const BIGNUM *kinv, - const BIGNUM *rp, EC_KEY *eckey); - int ECDSA_verify(int type, const unsigned char *dgst, - int dgstlen, const unsigned char *sig, - int siglen, EC_KEY *eckey); - int ECDSA_size(const EC_KEY *eckey); - - const ECDSA_METHOD* ECDSA_OpenSSL(void); - void ECDSA_set_default_method(const ECDSA_METHOD *meth); - const ECDSA_METHOD* ECDSA_get_default_method(void); - int ECDSA_set_method(EC_KEY *eckey,const ECDSA_METHOD *meth); - - int ECDSA_get_ex_new_index(long argl, void *argp, - CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - int ECDSA_set_ex_data(EC_KEY *d, int idx, void *arg); - void* ECDSA_get_ex_data(EC_KEY *d, int idx); - -=head1 DESCRIPTION - -The B<ECDSA_SIG> structure consists of two BIGNUMs for the -r and s value of a ECDSA signature (see X9.62 or FIPS 186-2). - - struct - { - BIGNUM *r; - BIGNUM *s; - } ECDSA_SIG; - -ECDSA_SIG_new() allocates a new B<ECDSA_SIG> structure (note: this -function also allocates the BIGNUMs) and initialize it. - -ECDSA_SIG_free() frees the B<ECDSA_SIG> structure B<sig>. - -i2d_ECDSA_SIG() creates the DER encoding of the ECDSA signature -B<sig> and writes the encoded signature to B<*pp> (note: if B<pp> -is NULL B<i2d_ECDSA_SIG> returns the expected length in bytes of -the DER encoded signature). B<i2d_ECDSA_SIG> returns the length -of the DER encoded signature (or 0 on error). - -d2i_ECDSA_SIG() decodes a DER encoded ECDSA signature and returns -the decoded signature in a newly allocated B<ECDSA_SIG> structure. -B<*sig> points to the buffer containing the DER encoded signature -of size B<len>. - -ECDSA_size() returns the maximum length of a DER encoded -ECDSA signature created with the private EC key B<eckey>. - -ECDSA_sign_setup() may be used to precompute parts of the -signing operation. B<eckey> is the private EC key and B<ctx> -is a pointer to B<BN_CTX> structure (or NULL). The precomputed -values or returned in B<kinv> and B<rp> and can be used in a -later call to B<ECDSA_sign_ex> or B<ECDSA_do_sign_ex>. - -ECDSA_sign() is wrapper function for ECDSA_sign_ex with B<kinv> -and B<rp> set to NULL. - -ECDSA_sign_ex() computes a digital signature of the B<dgstlen> bytes -hash value B<dgst> using the private EC key B<eckey> and the optional -pre-computed values B<kinv> and B<rp>. The DER encoded signatures is -stored in B<sig> and it's length is returned in B<sig_len>. Note: B<sig> -must point to B<ECDSA_size> bytes of memory. The parameter B<type> -is ignored. - -ECDSA_verify() verifies that the signature in B<sig> of size -B<siglen> is a valid ECDSA signature of the hash value -B<dgst> of size B<dgstlen> using the public key B<eckey>. -The parameter B<type> is ignored. - -ECDSA_do_sign() is wrapper function for ECDSA_do_sign_ex with B<kinv> -and B<rp> set to NULL. - -ECDSA_do_sign_ex() computes a digital signature of the B<dgst_len> -bytes hash value B<dgst> using the private key B<eckey> and the -optional pre-computed values B<kinv> and B<rp>. The signature is -returned in a newly allocated B<ECDSA_SIG> structure (or NULL on error). - -ECDSA_do_verify() verifies that the signature B<sig> is a valid -ECDSA signature of the hash value B<dgst> of size B<dgst_len> -using the public key B<eckey>. - -=head1 RETURN VALUES - -ECDSA_size() returns the maximum length signature or 0 on error. - -ECDSA_sign_setup() and ECDSA_sign() return 1 if successful or 0 -on error. - -ECDSA_verify() and ECDSA_do_verify() return 1 for a valid -signature, 0 for an invalid signature and -1 on error. -The error codes can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. - -=head1 EXAMPLES - -Creating a ECDSA signature of given SHA-1 hash value using the -named curve secp192k1. - -First step: create a EC_KEY object (note: this part is B<not> ECDSA -specific) - - int ret; - ECDSA_SIG *sig; - EC_KEY *eckey; - eckey = EC_KEY_new_by_curve_name(NID_secp192k1); - if (eckey == NULL) - { - /* error */ - } - if (!EC_KEY_generate_key(eckey)) - { - /* error */ - } - -Second step: compute the ECDSA signature of a SHA-1 hash value -using B<ECDSA_do_sign> - - sig = ECDSA_do_sign(digest, 20, eckey); - if (sig == NULL) - { - /* error */ - } - -or using B<ECDSA_sign> - - unsigned char *buffer, *pp; - int buf_len; - buf_len = ECDSA_size(eckey); - buffer = OPENSSL_malloc(buf_len); - pp = buffer; - if (!ECDSA_sign(0, dgst, dgstlen, pp, &buf_len, eckey); - { - /* error */ - } - -Third step: verify the created ECDSA signature using B<ECDSA_do_verify> - - ret = ECDSA_do_verify(digest, 20, sig, eckey); - -or using B<ECDSA_verify> - - ret = ECDSA_verify(0, digest, 20, buffer, buf_len, eckey); - -and finally evaluate the return value: - - if (ret == -1) - { - /* error */ - } - else if (ret == 0) - { - /* incorrect signature */ - } - else /* ret == 1 */ - { - /* signature ok */ - } - -=head1 CONFORMING TO - -ANSI X9.62, US Federal Information Processing Standard FIPS 186-2 -(Digital Signature Standard, DSS) - -=head1 SEE ALSO - -L<dsa(3)|dsa(3)>, L<rsa(3)|rsa(3)> - -=head1 HISTORY - -The ecdsa implementation was first introduced in OpenSSL 0.9.8 - -=head1 AUTHOR - -Nils Larsch for the OpenSSL project (http://www.openssl.org). - -=cut diff --git a/deps/openssl/openssl/doc/crypto/err.pod b/deps/openssl/openssl/doc/crypto/err.pod deleted file mode 100644 index 4a5dc6935c..0000000000 --- a/deps/openssl/openssl/doc/crypto/err.pod +++ /dev/null @@ -1,186 +0,0 @@ -=pod - -=head1 NAME - -err - error codes - -=head1 SYNOPSIS - - #include <openssl/err.h> - - unsigned long ERR_get_error(void); - unsigned long ERR_peek_error(void); - unsigned long ERR_get_error_line(const char **file, int *line); - unsigned long ERR_peek_error_line(const char **file, int *line); - unsigned long ERR_get_error_line_data(const char **file, int *line, - const char **data, int *flags); - unsigned long ERR_peek_error_line_data(const char **file, int *line, - const char **data, int *flags); - - int ERR_GET_LIB(unsigned long e); - int ERR_GET_FUNC(unsigned long e); - int ERR_GET_REASON(unsigned long e); - - void ERR_clear_error(void); - - char *ERR_error_string(unsigned long e, char *buf); - const char *ERR_lib_error_string(unsigned long e); - const char *ERR_func_error_string(unsigned long e); - const char *ERR_reason_error_string(unsigned long e); - - void ERR_print_errors(BIO *bp); - void ERR_print_errors_fp(FILE *fp); - - void ERR_load_crypto_strings(void); - void ERR_free_strings(void); - - void ERR_remove_state(unsigned long pid); - - void ERR_put_error(int lib, int func, int reason, const char *file, - int line); - void ERR_add_error_data(int num, ...); - - void ERR_load_strings(int lib,ERR_STRING_DATA str[]); - unsigned long ERR_PACK(int lib, int func, int reason); - int ERR_get_next_error_library(void); - -=head1 DESCRIPTION - -When a call to the OpenSSL library fails, this is usually signalled -by the return value, and an error code is stored in an error queue -associated with the current thread. The B<err> library provides -functions to obtain these error codes and textual error messages. - -The L<ERR_get_error(3)|ERR_get_error(3)> manpage describes how to -access error codes. - -Error codes contain information about where the error occurred, and -what went wrong. L<ERR_GET_LIB(3)|ERR_GET_LIB(3)> describes how to -extract this information. A method to obtain human-readable error -messages is described in L<ERR_error_string(3)|ERR_error_string(3)>. - -L<ERR_clear_error(3)|ERR_clear_error(3)> can be used to clear the -error queue. - -Note that L<ERR_remove_state(3)|ERR_remove_state(3)> should be used to -avoid memory leaks when threads are terminated. - -=head1 ADDING NEW ERROR CODES TO OPENSSL - -See L<ERR_put_error(3)> if you want to record error codes in the -OpenSSL error system from within your application. - -The remainder of this section is of interest only if you want to add -new error codes to OpenSSL or add error codes from external libraries. - -=head2 Reporting errors - -Each sub-library has a specific macro XXXerr() that is used to report -errors. Its first argument is a function code B<XXX_F_...>, the second -argument is a reason code B<XXX_R_...>. Function codes are derived -from the function names; reason codes consist of textual error -descriptions. For example, the function ssl23_read() reports a -"handshake failure" as follows: - - SSLerr(SSL_F_SSL23_READ, SSL_R_SSL_HANDSHAKE_FAILURE); - -Function and reason codes should consist of upper case characters, -numbers and underscores only. The error file generation script translates -function codes into function names by looking in the header files -for an appropriate function name, if none is found it just uses -the capitalized form such as "SSL23_READ" in the above example. - -The trailing section of a reason code (after the "_R_") is translated -into lower case and underscores changed to spaces. - -When you are using new function or reason codes, run B<make errors>. -The necessary B<#define>s will then automatically be added to the -sub-library's header file. - -Although a library will normally report errors using its own specific -XXXerr macro, another library's macro can be used. This is normally -only done when a library wants to include ASN1 code which must use -the ASN1err() macro. - -=head2 Adding new libraries - -When adding a new sub-library to OpenSSL, assign it a library number -B<ERR_LIB_XXX>, define a macro XXXerr() (both in B<err.h>), add its -name to B<ERR_str_libraries[]> (in B<crypto/err/err.c>), and add -C<ERR_load_XXX_strings()> to the ERR_load_crypto_strings() function -(in B<crypto/err/err_all.c>). Finally, add an entry - - L XXX xxx.h xxx_err.c - -to B<crypto/err/openssl.ec>, and add B<xxx_err.c> to the Makefile. -Running B<make errors> will then generate a file B<xxx_err.c>, and -add all error codes used in the library to B<xxx.h>. - -Additionally the library include file must have a certain form. -Typically it will initially look like this: - - #ifndef HEADER_XXX_H - #define HEADER_XXX_H - - #ifdef __cplusplus - extern "C" { - #endif - - /* Include files */ - - #include <openssl/bio.h> - #include <openssl/x509.h> - - /* Macros, structures and function prototypes */ - - - /* BEGIN ERROR CODES */ - -The B<BEGIN ERROR CODES> sequence is used by the error code -generation script as the point to place new error codes, any text -after this point will be overwritten when B<make errors> is run. -The closing #endif etc will be automatically added by the script. - -The generated C error code file B<xxx_err.c> will load the header -files B<stdio.h>, B<openssl/err.h> and B<openssl/xxx.h> so the -header file must load any additional header files containing any -definitions it uses. - -=head1 USING ERROR CODES IN EXTERNAL LIBRARIES - -It is also possible to use OpenSSL's error code scheme in external -libraries. The library needs to load its own codes and call the OpenSSL -error code insertion script B<mkerr.pl> explicitly to add codes to -the header file and generate the C error code file. This will normally -be done if the external library needs to generate new ASN1 structures -but it can also be used to add more general purpose error code handling. - -TBA more details - -=head1 INTERNALS - -The error queues are stored in a hash table with one B<ERR_STATE> -entry for each pid. ERR_get_state() returns the current thread's -B<ERR_STATE>. An B<ERR_STATE> can hold up to B<ERR_NUM_ERRORS> error -codes. When more error codes are added, the old ones are overwritten, -on the assumption that the most recent errors are most important. - -Error strings are also stored in hash table. The hash tables can -be obtained by calling ERR_get_err_state_table(void) and -ERR_get_string_table(void) respectively. - -=head1 SEE ALSO - -L<CRYPTO_set_locking_callback(3)|CRYPTO_set_locking_callback(3)>, -L<ERR_get_error(3)|ERR_get_error(3)>, -L<ERR_GET_LIB(3)|ERR_GET_LIB(3)>, -L<ERR_clear_error(3)|ERR_clear_error(3)>, -L<ERR_error_string(3)|ERR_error_string(3)>, -L<ERR_print_errors(3)|ERR_print_errors(3)>, -L<ERR_load_crypto_strings(3)|ERR_load_crypto_strings(3)>, -L<ERR_remove_state(3)|ERR_remove_state(3)>, -L<ERR_put_error(3)|ERR_put_error(3)>, -L<ERR_load_strings(3)|ERR_load_strings(3)>, -L<SSL_get_error(3)|SSL_get_error(3)> - -=cut diff --git a/deps/openssl/openssl/doc/crypto/evp.pod b/deps/openssl/openssl/doc/crypto/evp.pod index 303cd95a70..02051df6bc 100644 --- a/deps/openssl/openssl/doc/crypto/evp.pod +++ b/deps/openssl/openssl/doc/crypto/evp.pod @@ -1,5 +1,7 @@ =pod +=for comment openssl_manual_section:7 + =head1 NAME evp - high-level cryptographic functions @@ -27,36 +29,36 @@ functions. The L<B<EVP_Digest>I<...>|EVP_DigestInit(3)> functions provide messa The B<EVP_PKEY>I<...> functions provide a high level interface to asymmetric algorithms. To create a new EVP_PKEY see -L<EVP_PKEY_new(3)|EVP_PKEY_new(3)>. EVP_PKEYs can be associated +L<EVP_PKEY_new(3)>. EVP_PKEYs can be associated with a private key of a particular algorithm by using the functions -described on the L<EVP_PKEY_set1_RSA(3)|EVP_PKEY_set1_RSA(3)> page, or -new keys can be generated using L<EVP_PKEY_keygen(3)|EVP_PKEY_keygen(3)>. -EVP_PKEYs can be compared using L<EVP_PKEY_cmp(3)|EVP_PKEY_cmp(3)>, or printed using -L<EVP_PKEY_print_private(3)|EVP_PKEY_print_private(3)>. +described on the L<EVP_PKEY_set1_RSA(3)> page, or +new keys can be generated using L<EVP_PKEY_keygen(3)>. +EVP_PKEYs can be compared using L<EVP_PKEY_cmp(3)>, or printed using +L<EVP_PKEY_print_private(3)>. The EVP_PKEY functions support the full range of asymmetric algorithm operations: -=over +=over 4 -=item For key agreement see L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)> +=item For key agreement see L<EVP_PKEY_derive(3)> -=item For signing and verifying see L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, -L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)> and L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>. +=item For signing and verifying see L<EVP_PKEY_sign(3)>, +L<EVP_PKEY_verify(3)> and L<EVP_PKEY_verify_recover(3)>. However, note that these functions do not perform a digest of the data to be signed. Therefore -normally you would use the L<B<EVP_DigestSign>I<...>|EVP_DigestSignInit(3)> +normally you would use the L<EVP_DigestSignInit(3)> functions for this purpose. -=item For encryption and decryption see L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)> -and L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)> respectively. However, note that +=item For encryption and decryption see L<EVP_PKEY_encrypt(3)> +and L<EVP_PKEY_decrypt(3)> respectively. However, note that these functions perform encryption and decryption only. As public key encryption is an expensive operation, normally you would wrap -an encrypted message in a "digital envelope" using the L<B<EVP_Seal>I<...>|EVP_SealInit(3)> and -L<B<EVP_Open>I<...>|EVP_OpenInit(3)> functions. +an encrypted message in a "digital envelope" using the L<EVP_SealInit(3)> and +L<EVP_OpenInit(3)> functions. =back -The L<EVP_BytesToKey(3)|EVP_BytesToKey(3)> function provides some limited support for password +The L<EVP_BytesToKey(3)> function provides some limited support for password based encryption. Careful selection of the parameters will provide a PKCS#5 PBKDF1 compatible implementation. However, new applications should not typically use this (preferring, for example, PBKDF2 from PCKS#5). @@ -65,10 +67,8 @@ The L<B<EVP_Encode>I<...>|EVP_EncodeInit(3)> and L<B<EVP_Decode>I<...>|EVP_EncodeInit(3)> functions implement base 64 encoding and decoding. -Algorithms are loaded with L<OpenSSL_add_all_algorithms(3)|OpenSSL_add_all_algorithms(3)>. - All the symmetric algorithms (ciphers), digests and asymmetric algorithms -(public key algorithms) can be replaced by L<ENGINE|engine(3)> modules providing alternative +(public key algorithms) can be replaced by L<engine(3)> modules providing alternative implementations. If ENGINE implementations of ciphers or digests are registered as defaults, then the various EVP functions will automatically use those implementations automatically in preference to built in software @@ -77,32 +77,40 @@ implementations. For more information, consult the engine(3) man page. Although low level algorithm specific functions exist for many algorithms their use is discouraged. They cannot be used with an ENGINE and ENGINE versions of new algorithms cannot be accessed using the low level functions. -Also makes code harder to adapt to new algorithms and some options are not +Also makes code harder to adapt to new algorithms and some options are not cleanly supported at the low level and some operations are more efficient using the high level interface. =head1 SEE ALSO -L<EVP_DigestInit(3)|EVP_DigestInit(3)>, -L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>, -L<EVP_OpenInit(3)|EVP_OpenInit(3)>, -L<EVP_SealInit(3)|EVP_SealInit(3)>, -L<EVP_DigestSignInit(3)|EVP_DigestSignInit(3)>, -L<EVP_SignInit(3)|EVP_SignInit(3)>, -L<EVP_VerifyInit(3)|EVP_VerifyInit(3)>, +L<EVP_DigestInit(3)>, +L<EVP_EncryptInit(3)>, +L<EVP_OpenInit(3)>, +L<EVP_SealInit(3)>, +L<EVP_DigestSignInit(3)>, +L<EVP_SignInit(3)>, +L<EVP_VerifyInit(3)>, L<EVP_EncodeInit(3)>, -L<EVP_PKEY_new(3)|EVP_PKEY_new(3)>, -L<EVP_PKEY_set1_RSA(3)|EVP_PKEY_set1_RSA(3)>, -L<EVP_PKEY_keygen(3)|EVP_PKEY_keygen(3)>, -L<EVP_PKEY_print_private(3)|EVP_PKEY_print_private(3)>, -L<EVP_PKEY_decrypt(3)|EVP_PKEY_decrypt(3)>, -L<EVP_PKEY_encrypt(3)|EVP_PKEY_encrypt(3)>, -L<EVP_PKEY_sign(3)|EVP_PKEY_sign(3)>, -L<EVP_PKEY_verify(3)|EVP_PKEY_verify(3)>, -L<EVP_PKEY_verify_recover(3)|EVP_PKEY_verify_recover(3)>, -L<EVP_PKEY_derive(3)|EVP_PKEY_derive(3)>, -L<EVP_BytesToKey(3)|EVP_BytesToKey(3)>, -L<OpenSSL_add_all_algorithms(3)|OpenSSL_add_all_algorithms(3)>, -L<engine(3)|engine(3)> +L<EVP_PKEY_new(3)>, +L<EVP_PKEY_set1_RSA(3)>, +L<EVP_PKEY_keygen(3)>, +L<EVP_PKEY_print_private(3)>, +L<EVP_PKEY_decrypt(3)>, +L<EVP_PKEY_encrypt(3)>, +L<EVP_PKEY_sign(3)>, +L<EVP_PKEY_verify(3)>, +L<EVP_PKEY_verify_recover(3)>, +L<EVP_PKEY_derive(3)>, +L<EVP_BytesToKey(3)>, +L<engine(3)> + +=head1 COPYRIGHT + +Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/i2d_CMS_bio_stream.pod b/deps/openssl/openssl/doc/crypto/i2d_CMS_bio_stream.pod index 558bdd0812..ece7a4800e 100644 --- a/deps/openssl/openssl/doc/crypto/i2d_CMS_bio_stream.pod +++ b/deps/openssl/openssl/doc/crypto/i2d_CMS_bio_stream.pod @@ -2,7 +2,7 @@ =head1 NAME - i2d_CMS_bio_stream - output CMS_ContentInfo structure in BER format. +i2d_CMS_bio_stream - output CMS_ContentInfo structure in BER format =head1 SYNOPSIS @@ -31,14 +31,23 @@ i2d_CMS_bio_stream() returns 1 for success or 0 for failure. =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<CMS_sign(3)|CMS_sign(3)>, -L<CMS_verify(3)|CMS_verify(3)>, L<CMS_encrypt(3)|CMS_encrypt(3)> -L<CMS_decrypt(3)|CMS_decrypt(3)>, -L<SMIME_write_CMS(3)|SMIME_write_CMS(3)>, -L<PEM_write_bio_CMS_stream(3)|PEM_write_bio_CMS_stream(3)> +L<ERR_get_error(3)>, L<CMS_sign(3)>, +L<CMS_verify(3)>, L<CMS_encrypt(3)> +L<CMS_decrypt(3)>, +L<SMIME_write_CMS(3)>, +L<PEM_write_bio_CMS_stream(3)> =head1 HISTORY i2d_CMS_bio_stream() was added to OpenSSL 1.0.0 +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/i2d_PKCS7_bio_stream.pod b/deps/openssl/openssl/doc/crypto/i2d_PKCS7_bio_stream.pod index a37231e267..b42940a83c 100644 --- a/deps/openssl/openssl/doc/crypto/i2d_PKCS7_bio_stream.pod +++ b/deps/openssl/openssl/doc/crypto/i2d_PKCS7_bio_stream.pod @@ -2,7 +2,7 @@ =head1 NAME -i2d_PKCS7_bio_stream - output PKCS7 structure in BER format. +i2d_PKCS7_bio_stream - output PKCS7 structure in BER format =head1 SYNOPSIS @@ -31,14 +31,23 @@ i2d_PKCS7_bio_stream() returns 1 for success or 0 for failure. =head1 SEE ALSO -L<ERR_get_error(3)|ERR_get_error(3)>, L<PKCS7_sign(3)|PKCS7_sign(3)>, -L<PKCS7_verify(3)|PKCS7_verify(3)>, L<PKCS7_encrypt(3)|PKCS7_encrypt(3)> -L<PKCS7_decrypt(3)|PKCS7_decrypt(3)>, -L<SMIME_write_PKCS7(3)|SMIME_write_PKCS7(3)>, -L<PEM_write_bio_PKCS7_stream(3)|PEM_write_bio_PKCS7_stream(3)> +L<ERR_get_error(3)>, L<PKCS7_sign(3)>, +L<PKCS7_verify(3)>, L<PKCS7_encrypt(3)> +L<PKCS7_decrypt(3)>, +L<SMIME_write_PKCS7(3)>, +L<PEM_write_bio_PKCS7_stream(3)> =head1 HISTORY i2d_PKCS7_bio_stream() was added to OpenSSL 1.0.0 +=head1 COPYRIGHT + +Copyright 2008-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/i2d_re_X509_tbs.pod b/deps/openssl/openssl/doc/crypto/i2d_re_X509_tbs.pod new file mode 100644 index 0000000000..672c7ab5ae --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/i2d_re_X509_tbs.pod @@ -0,0 +1,79 @@ +=pod + +=head1 NAME + +d2i_X509_AUX, i2d_X509_AUX, +i2d_re_X509_tbs, i2d_re_X509_CRL_tbs, i2d_re_X509_REQ_tbs +- X509 encode and decode functions + +=head1 SYNOPSIS + + #include <openssl/x509.h> + + X509 *d2i_X509_AUX(X509 **px, const unsigned char **in, long len); + int i2d_X509_AUX(X509 *x, unsigned char **out); + int i2d_re_X509_tbs(X509 *x, unsigned char **out); + int i2d_re_X509_CRL_tbs(X509_CRL *crl, unsigned char **pp); + int i2d_re_X509_REQ_tbs(X509_REQ *req, unsigned char **pp); + +=head1 DESCRIPTION + +The X509 encode and decode routines encode and parse an +B<X509> structure, which represents an X509 certificate. + +d2i_X509_AUX() is similar to L<d2i_X509(3)> but the input is expected to +consist of an X509 certificate followed by auxiliary trust information. +This is used by the PEM routines to read "TRUSTED CERTIFICATE" objects. +This function should not be called on untrusted input. + +i2d_X509_AUX() is similar to L<i2d_X509(3)>, but the encoded output +contains both the certificate and any auxiliary trust information. +This is used by the PEM routines to write "TRUSTED CERTIFICATE" objects. +Note that this is a non-standard OpenSSL-specific data format. + +i2d_re_X509_tbs() is similar to L<i2d_X509(3)> except it encodes only +the TBSCertificate portion of the certificate. i2d_re_X509_CRL_tbs() +and i2d_re_X509_REQ_tbs() are analogous for CRL and certificate request, +respectively. The "re" in B<i2d_re_X509_tbs> stands for "re-encode", +and ensures that a fresh encoding is generated in case the object has been +modified after creation (see the BUGS section). + +The encoding of the TBSCertificate portion of a certificate is cached +in the B<X509> structure internally to improve encoding performance +and to ensure certificate signatures are verified correctly in some +certificates with broken (non-DER) encodings. + +If, after modification, the B<X509> object is re-signed with X509_sign(), +the encoding is automatically renewed. Otherwise, the encoding of the +TBSCertificate portion of the B<X509> can be manually renewed by calling +i2d_re_X509_tbs(). + +=head1 SEE ALSO + +L<ERR_get_error(3)> +L<X509_CRL_get0_by_serial(3)>, +L<X509_get0_signature(3)>, +L<X509_get_ext_d2i(3)>, +L<X509_get_extension_flags(3)>, +L<X509_get_pubkey(3)>, +L<X509_get_subject_name(3)>, +L<X509_get_version(3)>, +L<X509_NAME_add_entry_by_txt(3)>, +L<X509_NAME_ENTRY_get_object(3)>, +L<X509_NAME_get_index_by_NID(3)>, +L<X509_NAME_print_ex(3)>, +L<X509_new(3)>, +L<X509_sign(3)>, +L<X509V3_get_d2i(3)>, +L<X509_verify_cert(3)> + +=head1 COPYRIGHT + +Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/lh_stats.pod b/deps/openssl/openssl/doc/crypto/lh_stats.pod deleted file mode 100644 index 3eeaa72e52..0000000000 --- a/deps/openssl/openssl/doc/crypto/lh_stats.pod +++ /dev/null @@ -1,60 +0,0 @@ -=pod - -=head1 NAME - -lh_stats, lh_node_stats, lh_node_usage_stats, lh_stats_bio, -lh_node_stats_bio, lh_node_usage_stats_bio - LHASH statistics - -=head1 SYNOPSIS - - #include <openssl/lhash.h> - - void lh_stats(LHASH *table, FILE *out); - void lh_node_stats(LHASH *table, FILE *out); - void lh_node_usage_stats(LHASH *table, FILE *out); - - void lh_stats_bio(LHASH *table, BIO *out); - void lh_node_stats_bio(LHASH *table, BIO *out); - void lh_node_usage_stats_bio(LHASH *table, BIO *out); - -=head1 DESCRIPTION - -The B<LHASH> structure records statistics about most aspects of -accessing the hash table. This is mostly a legacy of Eric Young -writing this library for the reasons of implementing what looked like -a nice algorithm rather than for a particular software product. - -lh_stats() prints out statistics on the size of the hash table, how -many entries are in it, and the number and result of calls to the -routines in this library. - -lh_node_stats() prints the number of entries for each 'bucket' in the -hash table. - -lh_node_usage_stats() prints out a short summary of the state of the -hash table. It prints the 'load' and the 'actual load'. The load is -the average number of data items per 'bucket' in the hash table. The -'actual load' is the average number of items per 'bucket', but only -for buckets which contain entries. So the 'actual load' is the -average number of searches that will need to find an item in the hash -table, while the 'load' is the average number that will be done to -record a miss. - -lh_stats_bio(), lh_node_stats_bio() and lh_node_usage_stats_bio() -are the same as the above, except that the output goes to a B<BIO>. - -=head1 RETURN VALUES - -These functions do not return values. - -=head1 SEE ALSO - -L<bio(3)|bio(3)>, L<lhash(3)|lhash(3)> - -=head1 HISTORY - -These functions are available in all versions of SSLeay and OpenSSL. - -This manpage is derived from the SSLeay documentation. - -=cut diff --git a/deps/openssl/openssl/doc/crypto/lhash.pod b/deps/openssl/openssl/doc/crypto/lhash.pod deleted file mode 100644 index 73a19b6c7e..0000000000 --- a/deps/openssl/openssl/doc/crypto/lhash.pod +++ /dev/null @@ -1,302 +0,0 @@ -=pod - -=head1 NAME - -lh_new, lh_free, lh_insert, lh_delete, lh_retrieve, lh_doall, lh_doall_arg, lh_error - dynamic hash table - -=head1 SYNOPSIS - - #include <openssl/lhash.h> - - DECLARE_LHASH_OF(<type>); - - LHASH *lh_<type>_new(); - void lh_<type>_free(LHASH_OF(<type> *table); - - <type> *lh_<type>_insert(LHASH_OF(<type> *table, <type> *data); - <type> *lh_<type>_delete(LHASH_OF(<type> *table, <type> *data); - <type> *lh_retrieve(LHASH_OF<type> *table, <type> *data); - - void lh_<type>_doall(LHASH_OF(<type> *table, LHASH_DOALL_FN_TYPE func); - void lh_<type>_doall_arg(LHASH_OF(<type> *table, LHASH_DOALL_ARG_FN_TYPE func, - <type2>, <type2> *arg); - - int lh_<type>_error(LHASH_OF(<type> *table); - - typedef int (*LHASH_COMP_FN_TYPE)(const void *, const void *); - typedef unsigned long (*LHASH_HASH_FN_TYPE)(const void *); - typedef void (*LHASH_DOALL_FN_TYPE)(const void *); - typedef void (*LHASH_DOALL_ARG_FN_TYPE)(const void *, const void *); - -=head1 DESCRIPTION - -This library implements type-checked dynamic hash tables. The hash -table entries can be arbitrary structures. Usually they consist of key -and value fields. - -lh_<type>_new() creates a new B<LHASH_OF(<type>> structure to store -arbitrary data entries, and provides the 'hash' and 'compare' -callbacks to be used in organising the table's entries. The B<hash> -callback takes a pointer to a table entry as its argument and returns -an unsigned long hash value for its key field. The hash value is -normally truncated to a power of 2, so make sure that your hash -function returns well mixed low order bits. The B<compare> callback -takes two arguments (pointers to two hash table entries), and returns -0 if their keys are equal, non-zero otherwise. If your hash table -will contain items of some particular type and the B<hash> and -B<compare> callbacks hash/compare these types, then the -B<DECLARE_LHASH_HASH_FN> and B<IMPLEMENT_LHASH_COMP_FN> macros can be -used to create callback wrappers of the prototypes required by -lh_<type>_new(). These provide per-variable casts before calling the -type-specific callbacks written by the application author. These -macros, as well as those used for the "doall" callbacks, are defined -as; - - #define DECLARE_LHASH_HASH_FN(name, o_type) \ - unsigned long name##_LHASH_HASH(const void *); - #define IMPLEMENT_LHASH_HASH_FN(name, o_type) \ - unsigned long name##_LHASH_HASH(const void *arg) { \ - const o_type *a = arg; \ - return name##_hash(a); } - #define LHASH_HASH_FN(name) name##_LHASH_HASH - - #define DECLARE_LHASH_COMP_FN(name, o_type) \ - int name##_LHASH_COMP(const void *, const void *); - #define IMPLEMENT_LHASH_COMP_FN(name, o_type) \ - int name##_LHASH_COMP(const void *arg1, const void *arg2) { \ - const o_type *a = arg1; \ - const o_type *b = arg2; \ - return name##_cmp(a,b); } - #define LHASH_COMP_FN(name) name##_LHASH_COMP - - #define DECLARE_LHASH_DOALL_FN(name, o_type) \ - void name##_LHASH_DOALL(void *); - #define IMPLEMENT_LHASH_DOALL_FN(name, o_type) \ - void name##_LHASH_DOALL(void *arg) { \ - o_type *a = arg; \ - name##_doall(a); } - #define LHASH_DOALL_FN(name) name##_LHASH_DOALL - - #define DECLARE_LHASH_DOALL_ARG_FN(name, o_type, a_type) \ - void name##_LHASH_DOALL_ARG(void *, void *); - #define IMPLEMENT_LHASH_DOALL_ARG_FN(name, o_type, a_type) \ - void name##_LHASH_DOALL_ARG(void *arg1, void *arg2) { \ - o_type *a = arg1; \ - a_type *b = arg2; \ - name##_doall_arg(a, b); } - #define LHASH_DOALL_ARG_FN(name) name##_LHASH_DOALL_ARG - - An example of a hash table storing (pointers to) structures of type 'STUFF' - could be defined as follows; - - /* Calculates the hash value of 'tohash' (implemented elsewhere) */ - unsigned long STUFF_hash(const STUFF *tohash); - /* Orders 'arg1' and 'arg2' (implemented elsewhere) */ - int stuff_cmp(const STUFF *arg1, const STUFF *arg2); - /* Create the type-safe wrapper functions for use in the LHASH internals */ - static IMPLEMENT_LHASH_HASH_FN(stuff, STUFF); - static IMPLEMENT_LHASH_COMP_FN(stuff, STUFF); - /* ... */ - int main(int argc, char *argv[]) { - /* Create the new hash table using the hash/compare wrappers */ - LHASH_OF(STUFF) *hashtable = lh_STUFF_new(LHASH_HASH_FN(STUFF_hash), - LHASH_COMP_FN(STUFF_cmp)); - /* ... */ - } - -lh_<type>_free() frees the B<LHASH_OF(<type>> structure -B<table>. Allocated hash table entries will not be freed; consider -using lh_<type>_doall() to deallocate any remaining entries in the -hash table (see below). - -lh_<type>_insert() inserts the structure pointed to by B<data> into -B<table>. If there already is an entry with the same key, the old -value is replaced. Note that lh_<type>_insert() stores pointers, the -data are not copied. - -lh_<type>_delete() deletes an entry from B<table>. - -lh_<type>_retrieve() looks up an entry in B<table>. Normally, B<data> -is a structure with the key field(s) set; the function will return a -pointer to a fully populated structure. - -lh_<type>_doall() will, for every entry in the hash table, call -B<func> with the data item as its parameter. For lh_<type>_doall() -and lh_<type>_doall_arg(), function pointer casting should be avoided -in the callbacks (see B<NOTE>) - instead use the declare/implement -macros to create type-checked wrappers that cast variables prior to -calling your type-specific callbacks. An example of this is -illustrated here where the callback is used to cleanup resources for -items in the hash table prior to the hashtable itself being -deallocated: - - /* Cleans up resources belonging to 'a' (this is implemented elsewhere) */ - void STUFF_cleanup_doall(STUFF *a); - /* Implement a prototype-compatible wrapper for "STUFF_cleanup" */ - IMPLEMENT_LHASH_DOALL_FN(STUFF_cleanup, STUFF) - /* ... then later in the code ... */ - /* So to run "STUFF_cleanup" against all items in a hash table ... */ - lh_STUFF_doall(hashtable, LHASH_DOALL_FN(STUFF_cleanup)); - /* Then the hash table itself can be deallocated */ - lh_STUFF_free(hashtable); - -When doing this, be careful if you delete entries from the hash table -in your callbacks: the table may decrease in size, moving the item -that you are currently on down lower in the hash table - this could -cause some entries to be skipped during the iteration. The second -best solution to this problem is to set hash-E<gt>down_load=0 before -you start (which will stop the hash table ever decreasing in size). -The best solution is probably to avoid deleting items from the hash -table inside a "doall" callback! - -lh_<type>_doall_arg() is the same as lh_<type>_doall() except that -B<func> will be called with B<arg> as the second argument and B<func> -should be of type B<LHASH_DOALL_ARG_FN_TYPE> (a callback prototype -that is passed both the table entry and an extra argument). As with -lh_doall(), you can instead choose to declare your callback with a -prototype matching the types you are dealing with and use the -declare/implement macros to create compatible wrappers that cast -variables before calling your type-specific callbacks. An example of -this is demonstrated here (printing all hash table entries to a BIO -that is provided by the caller): - - /* Prints item 'a' to 'output_bio' (this is implemented elsewhere) */ - void STUFF_print_doall_arg(const STUFF *a, BIO *output_bio); - /* Implement a prototype-compatible wrapper for "STUFF_print" */ - static IMPLEMENT_LHASH_DOALL_ARG_FN(STUFF, const STUFF, BIO) - /* ... then later in the code ... */ - /* Print out the entire hashtable to a particular BIO */ - lh_STUFF_doall_arg(hashtable, LHASH_DOALL_ARG_FN(STUFF_print), BIO, - logging_bio); - -lh_<type>_error() can be used to determine if an error occurred in the last -operation. lh_<type>_error() is a macro. - -=head1 RETURN VALUES - -lh_<type>_new() returns B<NULL> on error, otherwise a pointer to the new -B<LHASH> structure. - -When a hash table entry is replaced, lh_<type>_insert() returns the value -being replaced. B<NULL> is returned on normal operation and on error. - -lh_<type>_delete() returns the entry being deleted. B<NULL> is returned if -there is no such value in the hash table. - -lh_<type>_retrieve() returns the hash table entry if it has been found, -B<NULL> otherwise. - -lh_<type>_error() returns 1 if an error occurred in the last operation, 0 -otherwise. - -lh_<type>_free(), lh_<type>_doall() and lh_<type>_doall_arg() return no values. - -=head1 NOTE - -The various LHASH macros and callback types exist to make it possible -to write type-checked code without resorting to function-prototype -casting - an evil that makes application code much harder to -audit/verify and also opens the window of opportunity for stack -corruption and other hard-to-find bugs. It also, apparently, violates -ANSI-C. - -The LHASH code regards table entries as constant data. As such, it -internally represents lh_insert()'d items with a "const void *" -pointer type. This is why callbacks such as those used by lh_doall() -and lh_doall_arg() declare their prototypes with "const", even for the -parameters that pass back the table items' data pointers - for -consistency, user-provided data is "const" at all times as far as the -LHASH code is concerned. However, as callers are themselves providing -these pointers, they can choose whether they too should be treating -all such parameters as constant. - -As an example, a hash table may be maintained by code that, for -reasons of encapsulation, has only "const" access to the data being -indexed in the hash table (ie. it is returned as "const" from -elsewhere in their code) - in this case the LHASH prototypes are -appropriate as-is. Conversely, if the caller is responsible for the -life-time of the data in question, then they may well wish to make -modifications to table item passed back in the lh_doall() or -lh_doall_arg() callbacks (see the "STUFF_cleanup" example above). If -so, the caller can either cast the "const" away (if they're providing -the raw callbacks themselves) or use the macros to declare/implement -the wrapper functions without "const" types. - -Callers that only have "const" access to data they're indexing in a -table, yet declare callbacks without constant types (or cast the -"const" away themselves), are therefore creating their own risks/bugs -without being encouraged to do so by the API. On a related note, -those auditing code should pay special attention to any instances of -DECLARE/IMPLEMENT_LHASH_DOALL_[ARG_]_FN macros that provide types -without any "const" qualifiers. - -=head1 BUGS - -lh_<type>_insert() returns B<NULL> both for success and error. - -=head1 INTERNALS - -The following description is based on the SSLeay documentation: - -The B<lhash> library implements a hash table described in the -I<Communications of the ACM> in 1991. What makes this hash table -different is that as the table fills, the hash table is increased (or -decreased) in size via OPENSSL_realloc(). When a 'resize' is done, instead of -all hashes being redistributed over twice as many 'buckets', one -bucket is split. So when an 'expand' is done, there is only a minimal -cost to redistribute some values. Subsequent inserts will cause more -single 'bucket' redistributions but there will never be a sudden large -cost due to redistributing all the 'buckets'. - -The state for a particular hash table is kept in the B<LHASH> structure. -The decision to increase or decrease the hash table size is made -depending on the 'load' of the hash table. The load is the number of -items in the hash table divided by the size of the hash table. The -default values are as follows. If (hash->up_load E<lt> load) =E<gt> -expand. if (hash-E<gt>down_load E<gt> load) =E<gt> contract. The -B<up_load> has a default value of 1 and B<down_load> has a default value -of 2. These numbers can be modified by the application by just -playing with the B<up_load> and B<down_load> variables. The 'load' is -kept in a form which is multiplied by 256. So -hash-E<gt>up_load=8*256; will cause a load of 8 to be set. - -If you are interested in performance the field to watch is -num_comp_calls. The hash library keeps track of the 'hash' value for -each item so when a lookup is done, the 'hashes' are compared, if -there is a match, then a full compare is done, and -hash-E<gt>num_comp_calls is incremented. If num_comp_calls is not equal -to num_delete plus num_retrieve it means that your hash function is -generating hashes that are the same for different values. It is -probably worth changing your hash function if this is the case because -even if your hash table has 10 items in a 'bucket', it can be searched -with 10 B<unsigned long> compares and 10 linked list traverses. This -will be much less expensive that 10 calls to your compare function. - -lh_strhash() is a demo string hashing function: - - unsigned long lh_strhash(const char *c); - -Since the B<LHASH> routines would normally be passed structures, this -routine would not normally be passed to lh_<type>_new(), rather it would be -used in the function passed to lh_<type>_new(). - -=head1 SEE ALSO - -L<lh_stats(3)|lh_stats(3)> - -=head1 HISTORY - -The B<lhash> library is available in all versions of SSLeay and OpenSSL. -lh_error() was added in SSLeay 0.9.1b. - -This manpage is derived from the SSLeay documentation. - -In OpenSSL 0.9.7, all lhash functions that were passed function pointers -were changed for better type safety, and the function types LHASH_COMP_FN_TYPE, -LHASH_HASH_FN_TYPE, LHASH_DOALL_FN_TYPE and LHASH_DOALL_ARG_FN_TYPE -became available. - -In OpenSSL 1.0.0, the lhash interface was revamped for even better -type checking. - -=cut diff --git a/deps/openssl/openssl/doc/crypto/o2i_SCT_LIST.pod b/deps/openssl/openssl/doc/crypto/o2i_SCT_LIST.pod new file mode 100644 index 0000000000..82922fce15 --- /dev/null +++ b/deps/openssl/openssl/doc/crypto/o2i_SCT_LIST.pod @@ -0,0 +1,48 @@ +=pod + +=head1 NAME + +o2i_SCT_LIST, i2o_SCT_LIST, o2i_SCT, i2o_SCT - +decode and encode Signed Certificate Timestamp lists in TLS wire format + +=head1 SYNOPSIS + + #include <openssl/ct.h> + + STACK_OF(SCT) *o2i_SCT_LIST(STACK_OF(SCT) **a, const unsigned char **pp, size_t len); + int i2o_SCT_LIST(const STACK_OF(SCT) *a, unsigned char **pp); + SCT *o2i_SCT(SCT **psct, const unsigned char **in, size_t len); + int i2o_SCT(const SCT *sct, unsigned char **out); + +=head1 DESCRIPTION + +The SCT_LIST and SCT functions are very similar to the i2d and d2i family of +functions, except that they convert to and from TLS wire format, as described in +RFC 6962. See L<d2i_SCT_LIST> for more information about how the parameters are +treated and the return values. + +=head1 RETURN VALUES + +All of the functions have return values consistent with those stated for +L<d2i_SCT_LIST> and L<i2d_SCT_LIST>. + +=head1 SEE ALSO + +L<ct(3)>, +L<d2i_SCT_LIST(3)>, +L<i2d_SCT_LIST(3)> + +=head1 HISTORY + +These functions were added in OpenSSL 1.1.0. + +=head1 COPYRIGHT + +Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 diff --git a/deps/openssl/openssl/doc/crypto/rand.pod b/deps/openssl/openssl/doc/crypto/rand.pod deleted file mode 100644 index b754854bcf..0000000000 --- a/deps/openssl/openssl/doc/crypto/rand.pod +++ /dev/null @@ -1,175 +0,0 @@ -=pod - -=head1 NAME - -rand - pseudo-random number generator - -=head1 SYNOPSIS - - #include <openssl/rand.h> - - int RAND_set_rand_engine(ENGINE *engine); - - int RAND_bytes(unsigned char *buf, int num); - int RAND_pseudo_bytes(unsigned char *buf, int num); - - void RAND_seed(const void *buf, int num); - void RAND_add(const void *buf, int num, double entropy); - int RAND_status(void); - - int RAND_load_file(const char *file, long max_bytes); - int RAND_write_file(const char *file); - const char *RAND_file_name(char *file, size_t num); - - int RAND_egd(const char *path); - - void RAND_set_rand_method(const RAND_METHOD *meth); - const RAND_METHOD *RAND_get_rand_method(void); - RAND_METHOD *RAND_SSLeay(void); - - void RAND_cleanup(void); - - /* For Win32 only */ - void RAND_screen(void); - int RAND_event(UINT, WPARAM, LPARAM); - -=head1 DESCRIPTION - -Since the introduction of the ENGINE API, the recommended way of controlling -default implementations is by using the ENGINE API functions. The default -B<RAND_METHOD>, as set by RAND_set_rand_method() and returned by -RAND_get_rand_method(), is only used if no ENGINE has been set as the default -"rand" implementation. Hence, these two functions are no longer the recommended -way to control defaults. - -If an alternative B<RAND_METHOD> implementation is being used (either set -directly or as provided by an ENGINE module), then it is entirely responsible -for the generation and management of a cryptographically secure PRNG stream. The -mechanisms described below relate solely to the software PRNG implementation -built in to OpenSSL and used by default. - -These functions implement a cryptographically secure pseudo-random -number generator (PRNG). It is used by other library functions for -example to generate random keys, and applications can use it when they -need randomness. - -A cryptographic PRNG must be seeded with unpredictable data such as -mouse movements or keys pressed at random by the user. This is -described in L<RAND_add(3)|RAND_add(3)>. Its state can be saved in a seed file -(see L<RAND_load_file(3)|RAND_load_file(3)>) to avoid having to go through the -seeding process whenever the application is started. - -L<RAND_bytes(3)|RAND_bytes(3)> describes how to obtain random data from the -PRNG. - -=head1 INTERNALS - -The RAND_SSLeay() method implements a PRNG based on a cryptographic -hash function. - -The following description of its design is based on the SSLeay -documentation: - -First up I will state the things I believe I need for a good RNG. - -=over 4 - -=item 1 - -A good hashing algorithm to mix things up and to convert the RNG 'state' -to random numbers. - -=item 2 - -An initial source of random 'state'. - -=item 3 - -The state should be very large. If the RNG is being used to generate -4096 bit RSA keys, 2 2048 bit random strings are required (at a minimum). -If your RNG state only has 128 bits, you are obviously limiting the -search space to 128 bits, not 2048. I'm probably getting a little -carried away on this last point but it does indicate that it may not be -a bad idea to keep quite a lot of RNG state. It should be easier to -break a cipher than guess the RNG seed data. - -=item 4 - -Any RNG seed data should influence all subsequent random numbers -generated. This implies that any random seed data entered will have -an influence on all subsequent random numbers generated. - -=item 5 - -When using data to seed the RNG state, the data used should not be -extractable from the RNG state. I believe this should be a -requirement because one possible source of 'secret' semi random -data would be a private key or a password. This data must -not be disclosed by either subsequent random numbers or a -'core' dump left by a program crash. - -=item 6 - -Given the same initial 'state', 2 systems should deviate in their RNG state -(and hence the random numbers generated) over time if at all possible. - -=item 7 - -Given the random number output stream, it should not be possible to determine -the RNG state or the next random number. - -=back - -The algorithm is as follows. - -There is global state made up of a 1023 byte buffer (the 'state'), a -working hash value ('md'), and a counter ('count'). - -Whenever seed data is added, it is inserted into the 'state' as -follows. - -The input is chopped up into units of 20 bytes (or less for -the last block). Each of these blocks is run through the hash -function as follows: The data passed to the hash function -is the current 'md', the same number of bytes from the 'state' -(the location determined by in incremented looping index) as -the current 'block', the new key data 'block', and 'count' -(which is incremented after each use). -The result of this is kept in 'md' and also xored into the -'state' at the same locations that were used as input into the -hash function. I -believe this system addresses points 1 (hash function; currently -SHA-1), 3 (the 'state'), 4 (via the 'md'), 5 (by the use of a hash -function and xor). - -When bytes are extracted from the RNG, the following process is used. -For each group of 10 bytes (or less), we do the following: - -Input into the hash function the local 'md' (which is initialized from -the global 'md' before any bytes are generated), the bytes that are to -be overwritten by the random bytes, and bytes from the 'state' -(incrementing looping index). From this digest output (which is kept -in 'md'), the top (up to) 10 bytes are returned to the caller and the -bottom 10 bytes are xored into the 'state'. - -Finally, after we have finished 'num' random bytes for the caller, -'count' (which is incremented) and the local and global 'md' are fed -into the hash function and the results are kept in the global 'md'. - -I believe the above addressed points 1 (use of SHA-1), 6 (by hashing -into the 'state' the 'old' data from the caller that is about to be -overwritten) and 7 (by not using the 10 bytes given to the caller to -update the 'state', but they are used to update 'md'). - -So of the points raised, only 2 is not addressed (but see -L<RAND_add(3)|RAND_add(3)>). - -=head1 SEE ALSO - -L<BN_rand(3)|BN_rand(3)>, L<RAND_add(3)|RAND_add(3)>, -L<RAND_load_file(3)|RAND_load_file(3)>, L<RAND_egd(3)|RAND_egd(3)>, -L<RAND_bytes(3)|RAND_bytes(3)>, -L<RAND_set_rand_method(3)|RAND_set_rand_method(3)>, -L<RAND_cleanup(3)|RAND_cleanup(3)> - -=cut diff --git a/deps/openssl/openssl/doc/crypto/rsa.pod b/deps/openssl/openssl/doc/crypto/rsa.pod deleted file mode 100644 index 45ac53ffc1..0000000000 --- a/deps/openssl/openssl/doc/crypto/rsa.pod +++ /dev/null @@ -1,123 +0,0 @@ -=pod - -=head1 NAME - -rsa - RSA public key cryptosystem - -=head1 SYNOPSIS - - #include <openssl/rsa.h> - #include <openssl/engine.h> - - RSA * RSA_new(void); - void RSA_free(RSA *rsa); - - int RSA_public_encrypt(int flen, unsigned char *from, - unsigned char *to, RSA *rsa, int padding); - int RSA_private_decrypt(int flen, unsigned char *from, - unsigned char *to, RSA *rsa, int padding); - int RSA_private_encrypt(int flen, unsigned char *from, - unsigned char *to, RSA *rsa,int padding); - int RSA_public_decrypt(int flen, unsigned char *from, - unsigned char *to, RSA *rsa,int padding); - - int RSA_sign(int type, unsigned char *m, unsigned int m_len, - unsigned char *sigret, unsigned int *siglen, RSA *rsa); - int RSA_verify(int type, unsigned char *m, unsigned int m_len, - unsigned char *sigbuf, unsigned int siglen, RSA *rsa); - - int RSA_size(const RSA *rsa); - - RSA *RSA_generate_key(int num, unsigned long e, - void (*callback)(int,int,void *), void *cb_arg); - - int RSA_check_key(RSA *rsa); - - int RSA_blinding_on(RSA *rsa, BN_CTX *ctx); - void RSA_blinding_off(RSA *rsa); - - void RSA_set_default_method(const RSA_METHOD *meth); - const RSA_METHOD *RSA_get_default_method(void); - int RSA_set_method(RSA *rsa, const RSA_METHOD *meth); - const RSA_METHOD *RSA_get_method(const RSA *rsa); - RSA_METHOD *RSA_PKCS1_SSLeay(void); - RSA_METHOD *RSA_null_method(void); - int RSA_flags(const RSA *rsa); - RSA *RSA_new_method(ENGINE *engine); - - int RSA_print(BIO *bp, RSA *x, int offset); - int RSA_print_fp(FILE *fp, RSA *x, int offset); - - int RSA_get_ex_new_index(long argl, char *argp, int (*new_func)(), - int (*dup_func)(), void (*free_func)()); - int RSA_set_ex_data(RSA *r,int idx,char *arg); - char *RSA_get_ex_data(RSA *r, int idx); - - int RSA_sign_ASN1_OCTET_STRING(int dummy, unsigned char *m, - unsigned int m_len, unsigned char *sigret, unsigned int *siglen, - RSA *rsa); - int RSA_verify_ASN1_OCTET_STRING(int dummy, unsigned char *m, - unsigned int m_len, unsigned char *sigbuf, unsigned int siglen, - RSA *rsa); - -=head1 DESCRIPTION - -These functions implement RSA public key encryption and signatures -as defined in PKCS #1 v2.0 [RFC 2437]. - -The B<RSA> structure consists of several BIGNUM components. It can -contain public as well as private RSA keys: - - struct - { - BIGNUM *n; // public modulus - BIGNUM *e; // public exponent - BIGNUM *d; // private exponent - BIGNUM *p; // secret prime factor - BIGNUM *q; // secret prime factor - BIGNUM *dmp1; // d mod (p-1) - BIGNUM *dmq1; // d mod (q-1) - BIGNUM *iqmp; // q^-1 mod p - // ... - }; - RSA - -In public keys, the private exponent and the related secret values are -B<NULL>. - -B<p>, B<q>, B<dmp1>, B<dmq1> and B<iqmp> may be B<NULL> in private -keys, but the RSA operations are much faster when these values are -available. - -Note that RSA keys may use non-standard B<RSA_METHOD> implementations, -either directly or by the use of B<ENGINE> modules. In some cases (eg. an -ENGINE providing support for hardware-embedded keys), these BIGNUM values -will not be used by the implementation or may be used for alternative data -storage. For this reason, applications should generally avoid using RSA -structure elements directly and instead use API functions to query or -modify keys. - -=head1 CONFORMING TO - -SSL, PKCS #1 v2.0 - -=head1 PATENTS - -RSA was covered by a US patent which expired in September 2000. - -=head1 SEE ALSO - -L<rsa(1)|rsa(1)>, L<bn(3)|bn(3)>, L<dsa(3)|dsa(3)>, L<dh(3)|dh(3)>, -L<rand(3)|rand(3)>, L<engine(3)|engine(3)>, L<RSA_new(3)|RSA_new(3)>, -L<RSA_public_encrypt(3)|RSA_public_encrypt(3)>, -L<RSA_sign(3)|RSA_sign(3)>, L<RSA_size(3)|RSA_size(3)>, -L<RSA_generate_key(3)|RSA_generate_key(3)>, -L<RSA_check_key(3)|RSA_check_key(3)>, -L<RSA_blinding_on(3)|RSA_blinding_on(3)>, -L<RSA_set_method(3)|RSA_set_method(3)>, L<RSA_print(3)|RSA_print(3)>, -L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>, -L<RSA_private_encrypt(3)|RSA_private_encrypt(3)>, -L<RSA_sign_ASN1_OCTET_STRING(3)|RSA_sign_ASN1_OCTET_STRING(3)>, -L<RSA_padding_add_PKCS1_type_1(3)|RSA_padding_add_PKCS1_type_1(3)> - -=cut diff --git a/deps/openssl/openssl/doc/crypto/threads.pod b/deps/openssl/openssl/doc/crypto/threads.pod deleted file mode 100644 index 30c19b815f..0000000000 --- a/deps/openssl/openssl/doc/crypto/threads.pod +++ /dev/null @@ -1,214 +0,0 @@ -=pod - -=head1 NAME - -CRYPTO_THREADID_set_callback, CRYPTO_THREADID_get_callback, -CRYPTO_THREADID_current, CRYPTO_THREADID_cmp, CRYPTO_THREADID_cpy, -CRYPTO_THREADID_hash, CRYPTO_set_locking_callback, CRYPTO_num_locks, -CRYPTO_set_dynlock_create_callback, CRYPTO_set_dynlock_lock_callback, -CRYPTO_set_dynlock_destroy_callback, CRYPTO_get_new_dynlockid, -CRYPTO_destroy_dynlockid, CRYPTO_lock - OpenSSL thread support - -=head1 SYNOPSIS - - #include <openssl/crypto.h> - - /* Don't use this structure directly. */ - typedef struct crypto_threadid_st - { - void *ptr; - unsigned long val; - } CRYPTO_THREADID; - /* Only use CRYPTO_THREADID_set_[numeric|pointer]() within callbacks */ - void CRYPTO_THREADID_set_numeric(CRYPTO_THREADID *id, unsigned long val); - void CRYPTO_THREADID_set_pointer(CRYPTO_THREADID *id, void *ptr); - int CRYPTO_THREADID_set_callback(void (*threadid_func)(CRYPTO_THREADID *)); - void (*CRYPTO_THREADID_get_callback(void))(CRYPTO_THREADID *); - void CRYPTO_THREADID_current(CRYPTO_THREADID *id); - int CRYPTO_THREADID_cmp(const CRYPTO_THREADID *a, - const CRYPTO_THREADID *b); - void CRYPTO_THREADID_cpy(CRYPTO_THREADID *dest, - const CRYPTO_THREADID *src); - unsigned long CRYPTO_THREADID_hash(const CRYPTO_THREADID *id); - - int CRYPTO_num_locks(void); - - /* struct CRYPTO_dynlock_value needs to be defined by the user */ - struct CRYPTO_dynlock_value; - - void CRYPTO_set_dynlock_create_callback(struct CRYPTO_dynlock_value * - (*dyn_create_function)(char *file, int line)); - void CRYPTO_set_dynlock_lock_callback(void (*dyn_lock_function) - (int mode, struct CRYPTO_dynlock_value *l, - const char *file, int line)); - void CRYPTO_set_dynlock_destroy_callback(void (*dyn_destroy_function) - (struct CRYPTO_dynlock_value *l, const char *file, int line)); - - int CRYPTO_get_new_dynlockid(void); - - void CRYPTO_destroy_dynlockid(int i); - - void CRYPTO_lock(int mode, int n, const char *file, int line); - - #define CRYPTO_w_lock(type) \ - CRYPTO_lock(CRYPTO_LOCK|CRYPTO_WRITE,type,__FILE__,__LINE__) - #define CRYPTO_w_unlock(type) \ - CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_WRITE,type,__FILE__,__LINE__) - #define CRYPTO_r_lock(type) \ - CRYPTO_lock(CRYPTO_LOCK|CRYPTO_READ,type,__FILE__,__LINE__) - #define CRYPTO_r_unlock(type) \ - CRYPTO_lock(CRYPTO_UNLOCK|CRYPTO_READ,type,__FILE__,__LINE__) - #define CRYPTO_add(addr,amount,type) \ - CRYPTO_add_lock(addr,amount,type,__FILE__,__LINE__) - -=head1 DESCRIPTION - -OpenSSL can generally be used safely in multi-threaded applications provided -that at least two callback functions are set, the locking_function and -threadid_func. -Note that OpenSSL is not completely thread-safe, and unfortunately not all -global resources have the necessary locks. -Further, the thread-safety does not extend to things like multiple threads -using the same B<SSL> object at the same time. - -locking_function(int mode, int n, const char *file, int line) is -needed to perform locking on shared data structures. -(Note that OpenSSL uses a number of global data structures that -will be implicitly shared whenever multiple threads use OpenSSL.) -Multi-threaded applications will crash at random if it is not set. - -locking_function() must be able to handle up to CRYPTO_num_locks() -different mutex locks. It sets the B<n>-th lock if B<mode> & -B<CRYPTO_LOCK>, and releases it otherwise. - -B<file> and B<line> are the file number of the function setting the -lock. They can be useful for debugging. - -threadid_func(CRYPTO_THREADID *id) is needed to record the currently-executing -thread's identifier into B<id>. The implementation of this callback should not -fill in B<id> directly, but should use CRYPTO_THREADID_set_numeric() if thread -IDs are numeric, or CRYPTO_THREADID_set_pointer() if they are pointer-based. -If the application does not register such a callback using -CRYPTO_THREADID_set_callback(), then a default implementation is used - on -Windows and BeOS this uses the system's default thread identifying APIs, and on -all other platforms it uses the address of B<errno>. The latter is satisfactory -for thread-safety if and only if the platform has a thread-local error number -facility. - -Once threadid_func() is registered, or if the built-in default implementation is -to be used; - -=over 4 - -=item * -CRYPTO_THREADID_current() records the currently-executing thread ID into the -given B<id> object. - -=item * -CRYPTO_THREADID_cmp() compares two thread IDs (returning zero for equality, ie. -the same semantics as memcmp()). - -=item * -CRYPTO_THREADID_cpy() duplicates a thread ID value, - -=item * -CRYPTO_THREADID_hash() returns a numeric value usable as a hash-table key. This -is usually the exact numeric or pointer-based thread ID used internally, however -this also handles the unusual case where pointers are larger than 'long' -variables and the platform's thread IDs are pointer-based - in this case, mixing -is done to attempt to produce a unique numeric value even though it is not as -wide as the platform's true thread IDs. - -=back - -Additionally, OpenSSL supports dynamic locks, and sometimes, some parts -of OpenSSL need it for better performance. To enable this, the following -is required: - -=over 4 - -=item * -Three additional callback function, dyn_create_function, dyn_lock_function -and dyn_destroy_function. - -=item * -A structure defined with the data that each lock needs to handle. - -=back - -struct CRYPTO_dynlock_value has to be defined to contain whatever structure -is needed to handle locks. - -dyn_create_function(const char *file, int line) is needed to create a -lock. Multi-threaded applications might crash at random if it is not set. - -dyn_lock_function(int mode, CRYPTO_dynlock *l, const char *file, int line) -is needed to perform locking off dynamic lock numbered n. Multi-threaded -applications might crash at random if it is not set. - -dyn_destroy_function(CRYPTO_dynlock *l, const char *file, int line) is -needed to destroy the lock l. Multi-threaded applications might crash at -random if it is not set. - -CRYPTO_get_new_dynlockid() is used to create locks. It will call -dyn_create_function for the actual creation. - -CRYPTO_destroy_dynlockid() is used to destroy locks. It will call -dyn_destroy_function for the actual destruction. - -CRYPTO_lock() is used to lock and unlock the locks. mode is a bitfield -describing what should be done with the lock. n is the number of the -lock as returned from CRYPTO_get_new_dynlockid(). mode can be combined -from the following values. These values are pairwise exclusive, with -undefined behaviour if misused (for example, CRYPTO_READ and CRYPTO_WRITE -should not be used together): - - CRYPTO_LOCK 0x01 - CRYPTO_UNLOCK 0x02 - CRYPTO_READ 0x04 - CRYPTO_WRITE 0x08 - -=head1 RETURN VALUES - -CRYPTO_num_locks() returns the required number of locks. - -CRYPTO_get_new_dynlockid() returns the index to the newly created lock. - -The other functions return no values. - -=head1 NOTES - -You can find out if OpenSSL was configured with thread support: - - #define OPENSSL_THREAD_DEFINES - #include <openssl/opensslconf.h> - #if defined(OPENSSL_THREADS) - // thread support enabled - #else - // no thread support - #endif - -Also, dynamic locks are currently not used internally by OpenSSL, but -may do so in the future. - -=head1 EXAMPLES - -B<crypto/threads/mttest.c> shows examples of the callback functions on -Solaris, Irix and Win32. - -=head1 HISTORY - -CRYPTO_set_locking_callback() is -available in all versions of SSLeay and OpenSSL. -CRYPTO_num_locks() was added in OpenSSL 0.9.4. -All functions dealing with dynamic locks were added in OpenSSL 0.9.5b-dev. -B<CRYPTO_THREADID> and associated functions were introduced in OpenSSL 1.0.0 -to replace (actually, deprecate) the previous CRYPTO_set_id_callback(), -CRYPTO_get_id_callback(), and CRYPTO_thread_id() functions which assumed -thread IDs to always be represented by 'unsigned long'. - -=head1 SEE ALSO - -L<crypto(3)|crypto(3)> - -=cut diff --git a/deps/openssl/openssl/doc/crypto/ui_compat.pod b/deps/openssl/openssl/doc/crypto/ui_compat.pod deleted file mode 100644 index adf2ae5e53..0000000000 --- a/deps/openssl/openssl/doc/crypto/ui_compat.pod +++ /dev/null @@ -1,57 +0,0 @@ -=pod - -=head1 NAME - -des_read_password, des_read_2passwords, des_read_pw_string, des_read_pw - -Compatibility user interface functions - -=head1 SYNOPSIS - - #include <openssl/des_old.h> - - int des_read_password(DES_cblock *key,const char *prompt,int verify); - int des_read_2passwords(DES_cblock *key1,DES_cblock *key2, - const char *prompt,int verify); - - int des_read_pw_string(char *buf,int length,const char *prompt,int verify); - int des_read_pw(char *buf,char *buff,int size,const char *prompt,int verify); - -=head1 DESCRIPTION - -The DES library contained a few routines to prompt for passwords. These -aren't necessarely dependent on DES, and have therefore become part of the -UI compatibility library. - -des_read_pw() writes the string specified by I<prompt> to standard output -turns echo off and reads an input string from the terminal. The string is -returned in I<buf>, which must have spac for at least I<size> bytes. -If I<verify> is set, the user is asked for the password twice and unless -the two copies match, an error is returned. The second password is stored -in I<buff>, which must therefore also be at least I<size> bytes. A return -code of -1 indicates a system error, 1 failure due to use interaction, and -0 is success. All other functions described here use des_read_pw() to do -the work. - -des_read_pw_string() is a variant of des_read_pw() that provides a buffer -for you if I<verify> is set. - -des_read_password() calls des_read_pw() and converts the password to a -DES key by calling DES_string_to_key(); des_read_2password() operates in -the same way as des_read_password() except that it generates two keys -by using the DES_string_to_2key() function. - -=head1 NOTES - -des_read_pw_string() is available in the MIT Kerberos library as well, and -is also available under the name EVP_read_pw_string(). - -=head1 SEE ALSO - -L<ui(3)|ui(3)>, L<ui_create(3)|ui_create(3)> - -=head1 AUTHOR - -Richard Levitte (richard@levitte.org) for the OpenSSL project -(http://www.openssl.org). - -=cut diff --git a/deps/openssl/openssl/doc/crypto/x509.pod b/deps/openssl/openssl/doc/crypto/x509.pod index f9e58e0e41..483b037647 100644 --- a/deps/openssl/openssl/doc/crypto/x509.pod +++ b/deps/openssl/openssl/doc/crypto/x509.pod @@ -1,5 +1,7 @@ =pod +=for comment openssl_manual_section:7 + =head1 NAME x509 - X.509 certificate handling @@ -10,7 +12,7 @@ x509 - X.509 certificate handling =head1 DESCRIPTION -A X.509 certificate is a structured grouping of information about +An X.509 certificate is a structured grouping of information about an individual, a device, or anything one can imagine. A X.509 CRL (certificate revocation list) is a tool to help determine if a certificate is still valid. The exact definition of those can be @@ -47,18 +49,27 @@ B<X509_EXTENSION_>I<...> handle certificate extensions. =head1 SEE ALSO -L<X509_NAME_ENTRY_get_object(3)|X509_NAME_ENTRY_get_object(3)>, -L<X509_NAME_add_entry_by_txt(3)|X509_NAME_add_entry_by_txt(3)>, -L<X509_NAME_add_entry_by_NID(3)|X509_NAME_add_entry_by_NID(3)>, -L<X509_NAME_print_ex(3)|X509_NAME_print_ex(3)>, -L<X509_NAME_new(3)|X509_NAME_new(3)>, -L<d2i_X509(3)|d2i_X509(3)>, -L<d2i_X509_ALGOR(3)|d2i_X509_ALGOR(3)>, -L<d2i_X509_CRL(3)|d2i_X509_CRL(3)>, -L<d2i_X509_NAME(3)|d2i_X509_NAME(3)>, -L<d2i_X509_REQ(3)|d2i_X509_REQ(3)>, -L<d2i_X509_SIG(3)|d2i_X509_SIG(3)>, -L<crypto(3)|crypto(3)>, -L<x509v3(3)|x509v3(3)> +L<X509_NAME_ENTRY_get_object(3)>, +L<X509_NAME_add_entry_by_txt(3)>, +L<X509_NAME_add_entry_by_NID(3)>, +L<X509_NAME_print_ex(3)>, +L<X509_NAME_new(3)>, +L<d2i_X509(3)>, +L<d2i_X509_ALGOR(3)>, +L<d2i_X509_CRL(3)>, +L<d2i_X509_NAME(3)>, +L<d2i_X509_REQ(3)>, +L<d2i_X509_SIG(3)>, +L<X509v3(3)>, +L<crypto(7)> + +=head1 COPYRIGHT + +Copyright 2003-2017 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (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 |